res_pjsip: Update authentication realm documentation.
authorRichard Mudgett <rmudgett@digium.com>
Sun, 1 Jan 2017 14:02:17 +0000 (08:02 -0600)
committerRichard Mudgett <rmudgett@digium.com>
Tue, 21 Feb 2017 04:24:31 +0000 (22:24 -0600)
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 authentication uses.

An empty inbound auth realm represents the global section's default_realm
value when the authentication object is used to challenge an incoming
request.  An empty outgoing auth realm is treated as a don't care wildcard
when the authentication object is used to respond to an incoming
authentication challenge.

ASTERISK-26799

Change-Id: Id3952f7cfa1b6683b9954f2c5d2352d2f11059ce

configs/samples/pjsip.conf.sample
res/res_pjsip.c
res/res_pjsip_outbound_publish.c
res/res_pjsip_outbound_registration.c

index 6595423..323100b 100644 (file)
 ; If you want to see more detail please check the documentation sources
 ; mentioned at the top of this file.
 
+; ============================================================================
+; NOTICE NOTICE NOTICE NOTICE NOTICE NOTICE NOTICE NOTICE NOTICE NOTICE
+;
+; This file does not maintain the complete option documentation.
+; ============================================================================
+
 ; Documentation
 ;
 ; The official documentation is at http://wiki.asterisk.org
 ;==========================AUTH SECTION OPTIONS=========================
 ;[auth]
 ;  SYNOPSIS: Authentication type
+;
+;  Note: 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
+;  authentication uses.  Look to the CLI config help
+;  "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")
                                 ; From header username will be set to this value if
                                 ; there is no better option (such as CallerID or
                                 ; endpoint/from_user) to be used
-;default_realm=asterisk         ; When Asterisk generates a challenge, the realm will be
-                                ; set to this value if there is no better option (such as
-                                ; auth/realm) to be used
+;default_realm=asterisk         ; When Asterisk generates a challenge, the digest realm
+                                ; will be set to this value if there is no better option
+                                ; (such as auth/realm) to be used.
 
                     ; Asterisk Task Processor Queue Size
                     ; On heavy loaded system with DB storage you may need to increase
index 90eb372..4dead21 100644 (file)
                                                This is a comma-delimited list of <replaceable>auth</replaceable> sections defined
                                                in <filename>pjsip.conf</filename> to be used to verify inbound connection attempts.
                                                </para><para>
-                                               Endpoints without an <literal>authentication</literal> object
-                                               configured will allow connections without vertification.
-                                       </para></description>
+                                               Endpoints without an authentication object
+                                               configured will allow connections without verification.</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
+                                               authentication uses.  See the auth realm description for details.
+                                               </para></note>
+                                       </description>
                                </configOption>
                                <configOption name="callerid">
                                        <synopsis>CallerID information for the endpoint</synopsis>
                                        <synopsis>Default Music On Hold class</synopsis>
                                </configOption>
                                <configOption name="outbound_auth">
-                                       <synopsis>Authentication object used for outbound requests</synopsis>
+                                       <synopsis>Authentication object(s) used for outbound requests</synopsis>
+                                       <description><para>
+                                               This is a comma-delimited list of <replaceable>auth</replaceable>
+                                               sections defined in <filename>pjsip.conf</filename> used to respond
+                                               to outbound connection authentication challenges.</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
+                                               authentication uses.  See the auth realm description for details.
+                                               </para></note>
+                                       </description>
                                </configOption>
                                <configOption name="outbound_proxy">
                                        <synopsis>Proxy through which to send requests, a full SIP URI must be provided</synopsis>
                                        <synopsis>PlainText password used for authentication.</synopsis>
                                        <description><para>Only used when auth_type is <literal>userpass</literal>.</para></description>
                                </configOption>
-                               <configOption name="realm" default="asterisk">
+                               <configOption name="realm">
                                        <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.
+                                               </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
+                                               authentication uses.</para></note>
+                                       </description>
                                </configOption>
                                <configOption name="type">
                                        <synopsis>Must be 'auth'</synopsis>
                                                used.</synopsis>
                                </configOption>
                                <configOption name="default_realm" default="asterisk">
-                                       <synopsis>When Asterisk generates an challenge, the digest will be
+                                       <synopsis>When Asterisk generates a challenge, the digest realm will be
                                                set to this value if there is no better option (such as auth/realm) to be
                                                used.</synopsis>
                                </configOption>
index 8768048..53eb6ac 100644 (file)
                                        <synopsis>Expiration time for publications in seconds</synopsis>
                                </configOption>
                                <configOption name="outbound_auth" default="">
-                                       <synopsis>Authentication object to be used for outbound publishes.</synopsis>
+                                       <synopsis>Authentication object(s) to be used for outbound publishes.</synopsis>
+                                       <description><para>
+                                               This is a comma-delimited list of <replaceable>auth</replaceable>
+                                               sections defined in <filename>pjsip.conf</filename> used to respond
+                                               to outbound authentication challenges.</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
+                                               authentication uses.  See the auth realm description for details.
+                                               </para></note>
+                                       </description>
                                </configOption>
                                <configOption name="outbound_proxy" default="">
                                        <synopsis>SIP URI of the outbound proxy used to send publishes</synopsis>
index d486ccd..137f3a8 100644 (file)
                                        <synopsis>Maximum number of registration attempts.</synopsis>
                                </configOption>
                                <configOption name="outbound_auth" default="">
-                                       <synopsis>Authentication object to be used for outbound registrations.</synopsis>
+                                       <synopsis>Authentication object(s) to be used for outbound registrations.</synopsis>
+                                       <description><para>
+                                               This is a comma-delimited list of <replaceable>auth</replaceable>
+                                               sections defined in <filename>pjsip.conf</filename> used to respond
+                                               to outbound authentication challenges.</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
+                                               authentication uses.  See the auth realm description for details.
+                                               </para></note>
+                                       </description>
                                </configOption>
                                <configOption name="outbound_proxy" default="">
                                        <synopsis>Outbound Proxy used to send registrations</synopsis>