<p>Joshua Colp <strong>submitted</strong> this change.</p><p><a href="https://gerrit.asterisk.org/c/asterisk/+/15765">View Change</a></p><div style="white-space:pre-wrap">Approvals:
Joshua Colp: Looks good to me, but someone else must approve; Approved for Submit
George Joseph: Looks good to me, approved
</div><pre style="font-family: monospace,monospace; white-space: pre-wrap;">res_pjsip: Update documentation for the auth object<br><br>Change-Id: I2f76867ce02ec611964925159be099de83346e38<br>---<br>M configs/samples/pjsip.conf.sample<br>M res/res_pjsip.c<br>2 files changed, 101 insertions(+), 26 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/configs/samples/pjsip.conf.sample b/configs/samples/pjsip.conf.sample</span><br><span>index d2287cb..ba269a3 100644</span><br><span>--- a/configs/samples/pjsip.conf.sample</span><br><span>+++ b/configs/samples/pjsip.conf.sample</span><br><span>@@ -886,14 +886,44 @@</span><br><span> ; "config show help res_pjsip auth realm" or on the wiki for the</span><br><span> ; difference.</span><br><span> ;</span><br><span style="color: hsl(0, 100%, 40%);">-;auth_type=userpass ; Authentication type (default: "userpass")</span><br><span style="color: hsl(0, 100%, 40%);">-;nonce_lifetime=32 ; Lifetime of a nonce associated with this</span><br><span style="color: hsl(0, 100%, 40%);">- ; authentication config (default: "32")</span><br><span style="color: hsl(0, 100%, 40%);">-;md5_cred= ; MD5 Hash used for authentication (default: "")</span><br><span style="color: hsl(0, 100%, 40%);">-;password= ; PlainText password used for authentication (default: "")</span><br><span style="color: hsl(0, 100%, 40%);">-;realm= ; SIP realm for endpoint (default: "")</span><br><span style="color: hsl(0, 100%, 40%);">-;type= ; Must be auth (default: "")</span><br><span style="color: hsl(0, 100%, 40%);">-;username= ; Username to use for account (default: "")</span><br><span style="color: hsl(120, 100%, 40%);">+;auth_type=userpass ; Authentication type. May be</span><br><span style="color: hsl(120, 100%, 40%);">+ ; "userpass" for plain text passwords or</span><br><span style="color: hsl(120, 100%, 40%);">+ ; "md5" for pre-hashed credentials.</span><br><span style="color: hsl(120, 100%, 40%);">+ ; (default: "userpass")</span><br><span style="color: hsl(120, 100%, 40%);">+;nonce_lifetime=32 ; Lifetime of a nonce associated with this</span><br><span style="color: hsl(120, 100%, 40%);">+ ; authentication config (default: "32")</span><br><span style="color: hsl(120, 100%, 40%);">+;md5_cred= ; As an alternative to specifying a plain text password,</span><br><span style="color: hsl(120, 100%, 40%);">+ ; you can hash the username, realm and password</span><br><span style="color: hsl(120, 100%, 40%);">+ ; together one time and place the hash value here.</span><br><span style="color: hsl(120, 100%, 40%);">+ ; The input to the hash function must be in the</span><br><span style="color: hsl(120, 100%, 40%);">+ ; following format:</span><br><span style="color: hsl(120, 100%, 40%);">+ ; <username>:<realm>:<password></span><br><span style="color: hsl(120, 100%, 40%);">+ ; For incoming authentication (asterisk is the server),</span><br><span style="color: hsl(120, 100%, 40%);">+ ; the realm must match either the realm set in this object</span><br><span style="color: hsl(120, 100%, 40%);">+ ; or the default set in in the "global" object.</span><br><span style="color: hsl(120, 100%, 40%);">+ ; For outgoing authentication (asterisk is the client),</span><br><span style="color: hsl(120, 100%, 40%);">+ ; the realm must match what the server will be sending</span><br><span style="color: hsl(120, 100%, 40%);">+ ; in their WWW-Authenticate header. It can't be blank</span><br><span style="color: hsl(120, 100%, 40%);">+ ; unless you expect the server to be sending a blank</span><br><span style="color: hsl(120, 100%, 40%);">+ ; realm in the header.</span><br><span style="color: hsl(120, 100%, 40%);">+ ; You can generate the hash with the following shell</span><br><span style="color: hsl(120, 100%, 40%);">+ ; command:</span><br><span style="color: hsl(120, 100%, 40%);">+ ; $ echo -n "myname:myrealm:mypassword" | md5sum</span><br><span style="color: hsl(120, 100%, 40%);">+ ; Note the '-n'. You don't want a newline to be part</span><br><span style="color: hsl(120, 100%, 40%);">+ ; of the hash. (default: "")</span><br><span style="color: hsl(120, 100%, 40%);">+;password= ; PlainText password used for authentication (default: "")</span><br><span style="color: hsl(120, 100%, 40%);">+;realm= ; For incoming authentication (asterisk is the server),</span><br><span style="color: hsl(120, 100%, 40%);">+ ; this is the realm to be sent on WWW-Authenticate</span><br><span style="color: hsl(120, 100%, 40%);">+ ; headers. If not specified, the global object's</span><br><span style="color: hsl(120, 100%, 40%);">+ ; "default_realm" will be used.</span><br><span style="color: hsl(120, 100%, 40%);">+ ; For outgoing authentication (asterisk is the client), this</span><br><span style="color: hsl(120, 100%, 40%);">+ ; must either be the realm the server is expected to send,</span><br><span style="color: hsl(120, 100%, 40%);">+ ; or blank to automatically use the realm sent by the server.</span><br><span style="color: hsl(120, 100%, 40%);">+ ; If you have multiple auth object for an endpoint, the realm</span><br><span style="color: hsl(120, 100%, 40%);">+ ; is also used to match the auth object to the realm the</span><br><span style="color: hsl(120, 100%, 40%);">+ ; server sends. (default: "")</span><br><span style="color: hsl(120, 100%, 40%);">+;type= ; Must be auth (default: "")</span><br><span style="color: hsl(120, 100%, 40%);">+;username= ; Username to use for account (default: "")</span><br><span> </span><br><span> </span><br><span> ;==========================DOMAIN_ALIAS SECTION OPTIONS=========================</span><br><span>diff --git a/res/res_pjsip.c b/res/res_pjsip.c</span><br><span>index 2ea07fd..4978a24 100644</span><br><span>--- a/res/res_pjsip.c</span><br><span>+++ b/res/res_pjsip.c</span><br><span>@@ -1192,33 +1192,78 @@</span><br><span> <configOption name="nonce_lifetime" default="32"></span><br><span> <synopsis>Lifetime of a nonce associated with this authentication config.</synopsis></span><br><span> </configOption></span><br><span style="color: hsl(0, 100%, 40%);">- <configOption name="md5_cred"></span><br><span style="color: hsl(120, 100%, 40%);">+ <configOption name="md5_cred" default=""></span><br><span> <synopsis>MD5 Hash used for authentication.</synopsis></span><br><span style="color: hsl(0, 100%, 40%);">- <description><para>Only used when auth_type is <literal>md5</literal>.</para></description></span><br><span style="color: hsl(120, 100%, 40%);">+ <description><para></span><br><span style="color: hsl(120, 100%, 40%);">+ Only used when auth_type is <literal>md5</literal>.</span><br><span style="color: hsl(120, 100%, 40%);">+ As an alternative to specifying a plain text password,</span><br><span style="color: hsl(120, 100%, 40%);">+ you can hash the username, realm and password</span><br><span style="color: hsl(120, 100%, 40%);">+ together one time and place the hash value here.</span><br><span style="color: hsl(120, 100%, 40%);">+ The input to the hash function must be in the</span><br><span style="color: hsl(120, 100%, 40%);">+ following format:</span><br><span style="color: hsl(120, 100%, 40%);">+ </para></span><br><span style="color: hsl(120, 100%, 40%);">+ <para></span><br><span style="color: hsl(120, 100%, 40%);">+ </para></span><br><span style="color: hsl(120, 100%, 40%);">+ <para></span><br><span style="color: hsl(120, 100%, 40%);">+ <username>:<realm>:<password></span><br><span style="color: hsl(120, 100%, 40%);">+ </para></span><br><span style="color: hsl(120, 100%, 40%);">+ <para></span><br><span style="color: hsl(120, 100%, 40%);">+ </para></span><br><span style="color: hsl(120, 100%, 40%);">+ <para></span><br><span style="color: hsl(120, 100%, 40%);">+ For incoming authentication (asterisk is the server),</span><br><span style="color: hsl(120, 100%, 40%);">+ the realm must match either the realm set in this object</span><br><span style="color: hsl(120, 100%, 40%);">+ or the <variable>default_realm</variable> set in in the</span><br><span style="color: hsl(120, 100%, 40%);">+ <replaceable>global</replaceable> object.</span><br><span style="color: hsl(120, 100%, 40%);">+ </para></span><br><span style="color: hsl(120, 100%, 40%);">+ <para></span><br><span style="color: hsl(120, 100%, 40%);">+ </para></span><br><span style="color: hsl(120, 100%, 40%);">+ <para></span><br><span style="color: hsl(120, 100%, 40%);">+ For outgoing authentication (asterisk is the client),</span><br><span style="color: hsl(120, 100%, 40%);">+ the realm must match what the server will be sending</span><br><span style="color: hsl(120, 100%, 40%);">+ in their WWW-Authenticate header. It can't be blank</span><br><span style="color: hsl(120, 100%, 40%);">+ unless you expect the server to be sending a blank</span><br><span style="color: hsl(120, 100%, 40%);">+ realm in the header.</span><br><span style="color: hsl(120, 100%, 40%);">+ You can generate the hash with the following shell</span><br><span style="color: hsl(120, 100%, 40%);">+ command:</span><br><span style="color: hsl(120, 100%, 40%);">+ </para></span><br><span style="color: hsl(120, 100%, 40%);">+ <para></span><br><span style="color: hsl(120, 100%, 40%);">+ </para></span><br><span style="color: hsl(120, 100%, 40%);">+ <para></span><br><span style="color: hsl(120, 100%, 40%);">+ $ echo -n "myname:myrealm:mypassword" | md5sum</span><br><span style="color: hsl(120, 100%, 40%);">+ </para></span><br><span style="color: hsl(120, 100%, 40%);">+ <para></span><br><span style="color: hsl(120, 100%, 40%);">+ </para></span><br><span style="color: hsl(120, 100%, 40%);">+ <para></span><br><span style="color: hsl(120, 100%, 40%);">+ Note the '-n'. You don't want a newline to be part</span><br><span style="color: hsl(120, 100%, 40%);">+ of the hash.</span><br><span style="color: hsl(120, 100%, 40%);">+ </para></description></span><br><span> </configOption></span><br><span> <configOption name="password"></span><br><span> <synopsis>Plain text password used for authentication.</synopsis></span><br><span> <description><para>Only used when auth_type is <literal>userpass</literal>.</para></description></span><br><span> </configOption></span><br><span style="color: hsl(0, 100%, 40%);">- <configOption name="realm"></span><br><span style="color: hsl(120, 100%, 40%);">+ <configOption name="realm" default=""></span><br><span> <synopsis>SIP realm for endpoint</synopsis></span><br><span> <description><para></span><br><span style="color: hsl(0, 100%, 40%);">- The treatment of this value depends upon how the authentication</span><br><span style="color: hsl(0, 100%, 40%);">- object is used.</span><br><span style="color: hsl(0, 100%, 40%);">- </para><para></span><br><span style="color: hsl(0, 100%, 40%);">- When used as an inbound authentication object, the realm is sent</span><br><span style="color: hsl(0, 100%, 40%);">- as part of the challenge so the peer can know which key to use</span><br><span style="color: hsl(0, 100%, 40%);">- when responding. An empty value will use the</span><br><span style="color: hsl(0, 100%, 40%);">- <replaceable>global</replaceable> section's</span><br><span style="color: hsl(0, 100%, 40%);">- <literal>default_realm</literal> value when issuing a challenge.</span><br><span style="color: hsl(0, 100%, 40%);">- </para><para></span><br><span style="color: hsl(0, 100%, 40%);">- When used as an outbound authentication object, the realm is</span><br><span style="color: hsl(0, 100%, 40%);">- matched with the received challenge realm to determine which</span><br><span style="color: hsl(0, 100%, 40%);">- authentication object to use when responding to the challenge. An</span><br><span style="color: hsl(0, 100%, 40%);">- empty value matches any challenging realm when determining</span><br><span style="color: hsl(0, 100%, 40%);">- which authentication object matches a received challenge.</span><br><span style="color: hsl(120, 100%, 40%);">+ For incoming authentication (asterisk is the server),</span><br><span style="color: hsl(120, 100%, 40%);">+ this is the realm to be sent on WWW-Authenticate</span><br><span style="color: hsl(120, 100%, 40%);">+ headers. If not specified, the <replaceable>global</replaceable></span><br><span style="color: hsl(120, 100%, 40%);">+ object's <variable>default_realm</variable> will be used.</span><br><span> </para></span><br><span style="color: hsl(0, 100%, 40%);">- <note><para></span><br><span style="color: hsl(120, 100%, 40%);">+ <para></span><br><span style="color: hsl(120, 100%, 40%);">+ </para></span><br><span style="color: hsl(120, 100%, 40%);">+ <para></span><br><span style="color: hsl(120, 100%, 40%);">+ For outgoing authentication (asterisk is the client), this</span><br><span style="color: hsl(120, 100%, 40%);">+ must either be the realm the server is expected to send,</span><br><span style="color: hsl(120, 100%, 40%);">+ or blank to automatically use the realm sent by the server.</span><br><span style="color: hsl(120, 100%, 40%);">+ If you have multiple auth object for an endpoint, the realm</span><br><span style="color: hsl(120, 100%, 40%);">+ is also used to match the auth object to the realm the</span><br><span style="color: hsl(120, 100%, 40%);">+ server sent.</span><br><span style="color: hsl(120, 100%, 40%);">+ </para></span><br><span style="color: hsl(120, 100%, 40%);">+ <para></span><br><span style="color: hsl(120, 100%, 40%);">+ </para></span><br><span style="color: hsl(120, 100%, 40%);">+ <note></span><br><span style="color: hsl(120, 100%, 40%);">+ <para></span><br><span> Using the same auth section for inbound and outbound</span><br><span> authentication is not recommended. There is a difference in</span><br><span> meaning for an empty realm setting between inbound and outbound</span><br><span></span><br></pre><p>To view, visit <a href="https://gerrit.asterisk.org/c/asterisk/+/15765">change 15765</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://gerrit.asterisk.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://gerrit.asterisk.org/c/asterisk/+/15765"/><meta itemprop="name" content="View Change"/></div></div>
<div style="display:none"> Gerrit-Project: asterisk </div>
<div style="display:none"> Gerrit-Branch: 16 </div>
<div style="display:none"> Gerrit-Change-Id: I2f76867ce02ec611964925159be099de83346e38 </div>
<div style="display:none"> Gerrit-Change-Number: 15765 </div>
<div style="display:none"> Gerrit-PatchSet: 2 </div>
<div style="display:none"> Gerrit-Owner: George Joseph <gjoseph@digium.com> </div>
<div style="display:none"> Gerrit-Reviewer: Friendly Automation </div>
<div style="display:none"> Gerrit-Reviewer: George Joseph <gjoseph@digium.com> </div>
<div style="display:none"> Gerrit-Reviewer: Joshua Colp <jcolp@sangoma.com> </div>
<div style="display:none"> Gerrit-MessageType: merged </div>