[Asterisk-code-review] res_pjsip: Update documentation for the auth object (asterisk[16])

Joshua Colp asteriskteam at digium.com
Thu Apr 22 06:55:45 CDT 2021


Joshua Colp has submitted this change. ( https://gerrit.asterisk.org/c/asterisk/+/15765 )

Change subject: res_pjsip:  Update documentation for the auth object
......................................................................

res_pjsip:  Update documentation for the auth object

Change-Id: I2f76867ce02ec611964925159be099de83346e38
---
M configs/samples/pjsip.conf.sample
M res/res_pjsip.c
2 files changed, 101 insertions(+), 26 deletions(-)

Approvals:
  Joshua Colp: Looks good to me, but someone else must approve; Approved for Submit
  George Joseph: Looks good to me, approved



diff --git a/configs/samples/pjsip.conf.sample b/configs/samples/pjsip.conf.sample
index d2287cb..ba269a3 100644
--- a/configs/samples/pjsip.conf.sample
+++ b/configs/samples/pjsip.conf.sample
@@ -886,14 +886,44 @@
 ;  "config show help res_pjsip auth realm" or on the wiki for the
 ;  difference.
 ;
-;auth_type=userpass     ; Authentication type (default: "userpass")
-;nonce_lifetime=32      ; Lifetime of a nonce associated with this
-                        ; authentication config (default: "32")
-;md5_cred=      ; MD5 Hash used for authentication (default: "")
-;password=      ; PlainText password used for authentication (default: "")
-;realm= ; SIP realm for endpoint (default: "")
-;type=  ; Must be auth (default: "")
-;username=      ; Username to use for account (default: "")
+;auth_type=userpass  ; Authentication type.  May be
+                     ; "userpass" for plain text passwords or
+                     ; "md5" for pre-hashed credentials.
+                     ; (default: "userpass")
+;nonce_lifetime=32   ; Lifetime of a nonce associated with this
+                     ; authentication config (default: "32")
+;md5_cred=     ; As an alternative to specifying a plain text password,
+               ; you can hash the username, realm and password
+               ; together one time and place the hash value here.
+               ; The input to the hash function must be in the
+               ; following format:
+               ; <username>:<realm>:<password>
+               ; For incoming authentication (asterisk is the server),
+               ; the realm must match either the realm set in this object
+               ; or the default set in in the "global" object.
+               ; For outgoing authentication (asterisk is the client),
+               ; the realm must match what the server will be sending
+               ; in their WWW-Authenticate header.  It can't be blank
+               ; unless you expect the server to be sending a blank
+               ; realm in the header.
+               ; You can generate the hash with the following shell
+               ; command:
+               ; $ echo -n "myname:myrealm:mypassword" | md5sum
+               ; Note the '-n'.  You don't want a newline to be part
+               ; of the hash.  (default: "")
+;password=     ; PlainText password used for authentication (default: "")
+;realm=        ; For incoming authentication (asterisk is the server),
+               ; this is the realm to be sent on WWW-Authenticate
+               ; headers.  If not specified, the global object's
+               ; "default_realm" will be used.
+               ; For outgoing authentication (asterisk is the client), this
+               ; must either be the realm the server is expected to send,
+               ; or blank to automatically use the realm sent by the server.
+               ; If you have multiple auth object for an endpoint, the realm
+               ; is also used to match the auth object to the realm the
+               ; server sends.  (default: "")
+;type=         ; Must be auth (default: "")
+;username=     ; Username to use for account (default: "")
 
 
 ;==========================DOMAIN_ALIAS SECTION OPTIONS=========================
diff --git a/res/res_pjsip.c b/res/res_pjsip.c
index 2ea07fd..4978a24 100644
--- a/res/res_pjsip.c
+++ b/res/res_pjsip.c
@@ -1192,33 +1192,78 @@
 				<configOption name="nonce_lifetime" default="32">
 					<synopsis>Lifetime of a nonce associated with this authentication config.</synopsis>
 				</configOption>
-				<configOption name="md5_cred">
+				<configOption name="md5_cred" default="">
 					<synopsis>MD5 Hash used for authentication.</synopsis>
-					<description><para>Only used when auth_type is <literal>md5</literal>.</para></description>
+					<description><para>
+						Only used when auth_type is <literal>md5</literal>.
+						As an alternative to specifying a plain text password,
+						you can hash the username, realm and password
+						together one time and place the hash value here.
+						The input to the hash function must be in the
+						following format:
+						</para>
+						<para>
+						</para>
+						<para>
+						<username>:<realm>:<password>
+						</para>
+						<para>
+						</para>
+						<para>
+						For incoming authentication (asterisk is the server),
+						the realm must match either the realm set in this object
+						or the <variable>default_realm</variable> set in in the
+						<replaceable>global</replaceable> object.
+						</para>
+						<para>
+						</para>
+						<para>
+						For outgoing authentication (asterisk is the client),
+						the realm must match what the server will be sending
+						in their WWW-Authenticate header.  It can't be blank
+						unless you expect the server to be sending a blank
+						realm in the header.
+						You can generate the hash with the following shell
+						command:
+						</para>
+						<para>
+						</para>
+						<para>
+						$ echo -n "myname:myrealm:mypassword" | md5sum
+						</para>
+						<para>
+						</para>
+						<para>
+						Note the '-n'.  You don't want a newline to be part
+						of the hash.
+					</para></description>
 				</configOption>
 				<configOption name="password">
 					<synopsis>Plain text password used for authentication.</synopsis>
 					<description><para>Only used when auth_type is <literal>userpass</literal>.</para></description>
 				</configOption>
-				<configOption name="realm">
+				<configOption name="realm" default="">
 					<synopsis>SIP realm for endpoint</synopsis>
 					<description><para>
-						The treatment of this value depends upon how the authentication
-						object is used.
-						</para><para>
-						When used as an inbound authentication object, the realm is sent
-						as part of the challenge so the peer can know which key to use
-						when responding.  An empty value will use the
-						<replaceable>global</replaceable> section's
-						<literal>default_realm</literal> value when issuing a challenge.
-						</para><para>
-						When used as an outbound authentication object, the realm is
-						matched with the received challenge realm to determine which
-						authentication object to use when responding to the challenge.  An
-						empty value matches any challenging realm when determining
-						which authentication object matches a received challenge.
+						For incoming authentication (asterisk is the server),
+						this is the realm to be sent on WWW-Authenticate
+						headers.  If not specified, the <replaceable>global</replaceable>
+						object's <variable>default_realm</variable> will be used.
 						</para>
-						<note><para>
+						<para>
+						</para>
+						<para>
+						For outgoing authentication (asterisk is the client), this
+						must either be the realm the server is expected to send,
+						or blank to automatically use the realm sent by the server.
+						If you have multiple auth object for an endpoint, the realm
+						is also used to match the auth object to the realm the
+						server sent.
+						</para>
+						<para>
+						</para>
+						<note>
+						<para>
 						Using the same auth section for inbound and outbound
 						authentication is not recommended.  There is a difference in
 						meaning for an empty realm setting between inbound and outbound

-- 
To view, visit https://gerrit.asterisk.org/c/asterisk/+/15765
To unsubscribe, or for help writing mail filters, visit https://gerrit.asterisk.org/settings

Gerrit-Project: asterisk
Gerrit-Branch: 16
Gerrit-Change-Id: I2f76867ce02ec611964925159be099de83346e38
Gerrit-Change-Number: 15765
Gerrit-PatchSet: 2
Gerrit-Owner: George Joseph <gjoseph at digium.com>
Gerrit-Reviewer: Friendly Automation
Gerrit-Reviewer: George Joseph <gjoseph at digium.com>
Gerrit-Reviewer: Joshua Colp <jcolp at sangoma.com>
Gerrit-MessageType: merged
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-code-review/attachments/20210422/6290d58c/attachment-0001.html>


More information about the asterisk-code-review mailing list