[Asterisk-code-review] res pjsip: Update authentication realm documentation. (asterisk[master])
Anonymous Coward
asteriskteam at digium.com
Tue Feb 21 22:39:10 CST 2017
Anonymous Coward #1000019 has submitted this change and it was merged. ( https://gerrit.asterisk.org/4991 )
Change subject: res_pjsip: Update authentication realm documentation.
......................................................................
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
---
M configs/samples/pjsip.conf.sample
M res/res_pjsip.c
M res/res_pjsip_outbound_publish.c
M res/res_pjsip_outbound_registration.c
4 files changed, 86 insertions(+), 11 deletions(-)
Approvals:
Kevin Harwell: Looks good to me, but someone else must approve
Mark Michelson: Looks good to me, approved
Anonymous Coward #1000019: Verified
diff --git a/configs/samples/pjsip.conf.sample b/configs/samples/pjsip.conf.sample
index 6595423..323100b 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
@@ -765,6 +771,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")
@@ -959,9 +973,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 90eb372..4dead21 100644
--- a/res/res_pjsip.c
+++ b/res/res_pjsip.c
@@ -112,9 +112,15 @@
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>
@@ -329,7 +335,18 @@
<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>
@@ -967,8 +984,30 @@
<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>
@@ -1512,7 +1551,7 @@
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>
diff --git a/res/res_pjsip_outbound_publish.c b/res/res_pjsip_outbound_publish.c
index 8768048..53eb6ac 100644
--- a/res/res_pjsip_outbound_publish.c
+++ b/res/res_pjsip_outbound_publish.c
@@ -55,7 +55,18 @@
<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>
diff --git a/res/res_pjsip_outbound_registration.c b/res/res_pjsip_outbound_registration.c
index d486ccd..137f3a8 100644
--- a/res/res_pjsip_outbound_registration.c
+++ b/res/res_pjsip_outbound_registration.c
@@ -82,7 +82,18 @@
<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>
--
To view, visit https://gerrit.asterisk.org/4991
To unsubscribe, visit https://gerrit.asterisk.org/settings
Gerrit-MessageType: merged
Gerrit-Change-Id: Id3952f7cfa1b6683b9954f2c5d2352d2f11059ce
Gerrit-PatchSet: 3
Gerrit-Project: asterisk
Gerrit-Branch: master
Gerrit-Owner: Richard Mudgett <rmudgett at digium.com>
Gerrit-Reviewer: Anonymous Coward #1000019
Gerrit-Reviewer: George Joseph <gjoseph at digium.com>
Gerrit-Reviewer: Joshua Colp <jcolp at digium.com>
Gerrit-Reviewer: Kevin Harwell <kharwell at digium.com>
Gerrit-Reviewer: Mark Michelson <mmichelson at digium.com>
More information about the asterisk-code-review
mailing list