From: Richard Mudgett Date: Sun, 1 Jan 2017 14:02:17 +0000 (-0600) Subject: res_pjsip: Update authentication realm documentation. X-Git-Tag: 13.15.0-rc1~68^2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fchanges%2F85%2F4985%2F3;p=thirdparty%2Fasterisk.git res_pjsip: Update authentication realm documentation. 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 --- diff --git a/configs/samples/pjsip.conf.sample b/configs/samples/pjsip.conf.sample index 2ef8933845..bb2ad94f82 100644 --- a/configs/samples/pjsip.conf.sample +++ b/configs/samples/pjsip.conf.sample @@ -12,6 +12,12 @@ ; 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 @@ -759,6 +765,14 @@ ;==========================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") @@ -947,9 +961,9 @@ ; 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 diff --git a/res/res_pjsip.c b/res/res_pjsip.c index 9b9905826a..2390bc0413 100644 --- a/res/res_pjsip.c +++ b/res/res_pjsip.c @@ -112,9 +112,15 @@ This is a comma-delimited list of auth sections defined in pjsip.conf to be used to verify inbound connection attempts. - Endpoints without an authentication object - configured will allow connections without vertification. - + Endpoints without an authentication object + configured will allow connections without verification. + + 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. + + CallerID information for the endpoint @@ -329,7 +335,18 @@ Default Music On Hold class - Authentication object used for outbound requests + Authentication object(s) used for outbound requests + + This is a comma-delimited list of auth + sections defined in pjsip.conf used to respond + to outbound connection authentication challenges. + + 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. + + Proxy through which to send requests, a full SIP URI must be provided @@ -961,8 +978,30 @@ PlainText password used for authentication. Only used when auth_type is userpass. - + SIP realm for endpoint + + The treatment of this value depends upon how the authentication + object is used. + + 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 + global section's + default_realm value when issuing a challenge. + + 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. + + + 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. + Must be 'auth' @@ -1506,7 +1545,7 @@ used. - When Asterisk generates an challenge, the digest will be + 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. diff --git a/res/res_pjsip_outbound_publish.c b/res/res_pjsip_outbound_publish.c index 35eedf0d2c..3afa41307d 100644 --- a/res/res_pjsip_outbound_publish.c +++ b/res/res_pjsip_outbound_publish.c @@ -54,7 +54,18 @@ Expiration time for publications in seconds - Authentication object to be used for outbound publishes. + Authentication object(s) to be used for outbound publishes. + + This is a comma-delimited list of auth + sections defined in pjsip.conf used to respond + to outbound authentication challenges. + + 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. + + SIP URI of the outbound proxy used to send publishes diff --git a/res/res_pjsip_outbound_registration.c b/res/res_pjsip_outbound_registration.c index da15f19f5d..bfb327c75e 100644 --- a/res/res_pjsip_outbound_registration.c +++ b/res/res_pjsip_outbound_registration.c @@ -82,7 +82,18 @@ Maximum number of registration attempts. - Authentication object to be used for outbound registrations. + Authentication object(s) to be used for outbound registrations. + + This is a comma-delimited list of auth + sections defined in pjsip.conf used to respond + to outbound authentication challenges. + + 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. + + Outbound Proxy used to send registrations