res_pjsip: Update documentation for the auth object

Change-Id: I2f76867ce02ec611964925159be099de83346e38

configs/samples/pjsip.conf.sample

@@ -939,14 +939,44 @@
 ;  "config show help res_pjsip auth realm" or on the wiki for the
 ;  difference.
 ;
-;auth_type=userpass     ; Authentication type (default: "userpass")
+;auth_type=userpass  ; Authentication type.  May be
-;nonce_lifetime=32      ; Lifetime of a nonce associated with this
+                     ; "userpass" for plain text passwords or
-                        ; authentication config (default: "32")
+                     ; "md5" for pre-hashed credentials.
-;md5_cred=      ; MD5 Hash used for authentication (default: "")
+                     ; (default: "userpass")
-;password=      ; PlainText password used for authentication (default: "")
+;nonce_lifetime=32   ; Lifetime of a nonce associated with this
-;realm= ; SIP realm for endpoint (default: "")
+                     ; authentication config (default: "32")
-;type=  ; Must be auth (default: "")
+;md5_cred=     ; As an alternative to specifying a plain text password,
-;username=      ; Username to use for account (default: "")
+               ; 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=========================

res/res_pjsip.c

@@ -1499,9 +1499,51 @@
 				<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>
+						&lt;username&gt;:&lt;realm&gt;:&lt;password&gt;
+						</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>
@@ -1516,25 +1558,28 @@
 				<configOption name="oauth_secret">
 					<synopsis>OAuth 2.0 application's secret</synopsis>
 				</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
+						For incoming authentication (asterisk is the server),
-						object is used.
+						this is the realm to be sent on WWW-Authenticate
-						</para><para>
+						headers.  If not specified, the <replaceable>global</replaceable>
-						When used as an inbound authentication object, the realm is sent
+						object's <variable>default_realm</variable> will be used.
-						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.
 						</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