[Asterisk-code-review] res_pjsip: Update documentation for the auth object (asterisk[18])
George Joseph
asteriskteam at digium.com
Tue Apr 20 08:50:51 CDT 2021
George Joseph has uploaded this change for review. ( https://gerrit.asterisk.org/c/asterisk/+/15766 )
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(+), 25 deletions(-)
git pull ssh://gerrit.asterisk.org:29418/asterisk refs/changes/66/15766/1
diff --git a/configs/samples/pjsip.conf.sample b/configs/samples/pjsip.conf.sample
index cded743..de3e866 100644
--- a/configs/samples/pjsip.conf.sample
+++ b/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")
-;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 1b44aa6..cd33300 100644
--- a/res/res_pjsip.c
+++ b/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>
+ <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>
@@ -1517,24 +1559,28 @@
<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
- 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/+/15766
To unsubscribe, or for help writing mail filters, visit https://gerrit.asterisk.org/settings
Gerrit-Project: asterisk
Gerrit-Branch: 18
Gerrit-Change-Id: I2f76867ce02ec611964925159be099de83346e38
Gerrit-Change-Number: 15766
Gerrit-PatchSet: 1
Gerrit-Owner: George Joseph <gjoseph at digium.com>
Gerrit-MessageType: newchange
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-code-review/attachments/20210420/a8aeed06/attachment-0001.html>
More information about the asterisk-code-review
mailing list