[Asterisk-code-review] res_pjsip: Update documentation for the auth object (asterisk[16])
Joshua Colp
asteriskteam at digium.com
Thu Apr 22 06:55:45 CDT 2021
Joshua Colp has submitted this change. ( https://gerrit.asterisk.org/c/asterisk/+/15765 )
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(+), 26 deletions(-)
Approvals:
Joshua Colp: Looks good to me, but someone else must approve; Approved for Submit
George Joseph: Looks good to me, approved
diff --git a/configs/samples/pjsip.conf.sample b/configs/samples/pjsip.conf.sample
index d2287cb..ba269a3 100644
--- a/configs/samples/pjsip.conf.sample
+++ b/configs/samples/pjsip.conf.sample
@@ -886,14 +886,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 2ea07fd..4978a24 100644
--- a/res/res_pjsip.c
+++ b/res/res_pjsip.c
@@ -1192,33 +1192,78 @@
<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>
<description><para>Only used when auth_type is <literal>userpass</literal>.</para></description>
</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/+/15765
To unsubscribe, or for help writing mail filters, visit https://gerrit.asterisk.org/settings
Gerrit-Project: asterisk
Gerrit-Branch: 16
Gerrit-Change-Id: I2f76867ce02ec611964925159be099de83346e38
Gerrit-Change-Number: 15765
Gerrit-PatchSet: 2
Gerrit-Owner: George Joseph <gjoseph at digium.com>
Gerrit-Reviewer: Friendly Automation
Gerrit-Reviewer: George Joseph <gjoseph at digium.com>
Gerrit-Reviewer: Joshua Colp <jcolp at sangoma.com>
Gerrit-MessageType: merged
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-code-review/attachments/20210422/6290d58c/attachment-0001.html>
More information about the asterisk-code-review
mailing list