<p>Richard Mudgett has uploaded this change for <strong>review</strong>.</p><p><a href="https://gerrit.asterisk.org/7890">View Change</a></p><pre style="font-family: monospace,monospace; white-space: pre-wrap;">res_pjsip.c: Update the endpoint identification documentation.<br><br>* Endpoint identify_by documentation.<br>* IP/Header endpoint identifier documentation.<br><br>Change-Id: Id92f00b495acca7be945daf749d2abd7f76a0b5a<br>---<br>M configs/samples/pjsip.conf.sample<br>M res/res_pjsip.c<br>M res/res_pjsip_endpoint_identifier_ip.c<br>3 files changed, 90 insertions(+), 58 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;">git pull ssh://gerrit.asterisk.org:29418/asterisk refs/changes/90/7890/1</pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;">diff --git a/configs/samples/pjsip.conf.sample b/configs/samples/pjsip.conf.sample<br>index aff8ead..bdd2e65 100644<br>--- a/configs/samples/pjsip.conf.sample<br>+++ b/configs/samples/pjsip.conf.sample<br>@@ -635,9 +635,9 @@<br> ; "username": Identify by the From or To username and domain<br> ; "auth_username": Identify by the Authorization username and realm<br> ; "ip": Identify by the source IP address<br>- ; In username and auth_username cases, if an exact match on<br>- ; username and domain/realm fails, the match will be retried<br>- ; with just the username.<br>+ ; In the username and auth_username cases, if an exact match<br>+ ; on both username and domain/realm fails, the match is<br>+ ; retried with just the username.<br> ; (default: "username,ip")<br> ;redirect_method=user ; How redirects received from an endpoint are handled<br> ; (default: "user")<br>@@ -1109,9 +1109,12 @@<br> ; MODULE PROVIDING BELOW SECTION(S): res_pjsip_endpoint_identifier_ip<br> ;==========================IDENTIFY SECTION OPTIONS=========================<br> ;[identify]<br>-; SYNOPSIS: Identifies endpoints via source IP address<br>-;endpoint= ; Name of Endpoint (default: "")<br>-;match= ; IP addresses or networks to match against (default: "")<br>+; SYNOPSIS: Identifies endpoints via some criteria.<br>+;endpoint= ; Name of endpoint identified (default: "")<br>+;srv_lookups=yes ; Perform SRV lookups for provided hostnames. (default: yes)<br>+;match= ; Comma separated list of IP addresses, networks, or hostnames to match<br>+ ; against (default: "")<br>+;match_header= ; SIP header with specified value to match against (default: "")<br> ;type= ; Must be of type identify (default: "")<br> <br> <br>diff --git a/res/res_pjsip.c b/res/res_pjsip.c<br>index 842cc20..f61071a 100644<br>--- a/res/res_pjsip.c<br>+++ b/res/res_pjsip.c<br>@@ -269,45 +269,60 @@<br> <configOption name="ice_support" default="no"><br> <synopsis>Enable the ICE mechanism to help traverse NAT</synopsis><br> </configOption><br>- <configOption name="identify_by" default="username,ip"><br>- <synopsis>Way(s) for Endpoint to be identified</synopsis><br>- <description><para><br>- Endpoints and aors can be identified in multiple ways. Currently, the supported<br>- options are <literal>username</literal>, which matches the endpoint or aor id based on<br>- the username and domain in the From header (or To header for aors),<br>- <literal>auth_username</literal>, which matches the endpoint or aor id based on the<br>- username and realm in the Authentication header, and <literal>ip</literal> which matches<br>- an endpoint based on the source IP address. In the <literal>username</literal> and<br>- <literal>auth_username</literal> cases, if an exact match on both username and<br>- domain/realm fails, the match will be retried with just the username.<br>+ <configOption name="identify_by"><br>+ <synopsis>Way(s) for the endpoint to be identified</synopsis><br>+ <description><br>+ <para>Endpoints and AORs can be identified in multiple ways. This<br>+ option is a comma separated list of methods the endpoint can be<br>+ identified.<br> </para><br> <note><para><br>- Identification by auth_username has some security considerations because an<br>- Authentication header is not present on the first message of a dialog when<br>- digest authentication is used. The client can't generate it until the server<br>- sends the challenge in a 401 response. Since Asterisk normally sends a security<br>- event when an incoming request can't be matched to an endpoint, using auth_username<br>- requires that the security event be deferred until a request is received with<br>- the Authentication header and only generated if the username doesn't result in a<br>- match. This may result in a delay before an attack is recognized. You can control<br>- how many unmatched requests are received from a single ip address before a security<br>- event is generated using the unidentified_request parameters in the "global"<br>- configuration object.<br>+ This option controls both how an endpoint is matched for incoming<br>+ traffic and also how an AOR is determined if a registration<br>+ occurs. You must list at least one method that also matches for<br>+ AORs or the registration will fail.<br> </para></note><br>- <note><para>Endpoints can also be identified by IP address; however, that method<br>- of identification is not configured but simply allowed by this configuration option.<br>- See the documentation for the <literal>identify</literal> configuration section for<br>- more details on that method of endpoint identification.</para></note><br>- <note><para><br>- This option controls both how an endpoint is matched for incoming traffic and also how<br>- an AoR is determined if a registration occurs. If <literal>ip</literal> is set alone<br>- then incoming registration will not find an AoR and the registration attempt will fail.<br>- If you want to allow incoming registrations to succeed you must set a second identify<br>- method such as <literal>username</literal> in this case.</para></note><br> <enumlist><br>- <enum name="username" /><br>- <enum name="auth_username" /><br>- <enum name="ip" /><br>+ <enum name="username"><br>+ <para>Matches the endpoint or AOR ID based on the username<br>+ and domain in the From header (or To header for AORs). If<br>+ an exact match on both username and domain/realm fails, the<br>+ match is retried with just the username.<br>+ </para><br>+ </enum><br>+ <enum name="auth_username"><br>+ <para>Matches the endpoint or AOR ID based on the username<br>+ and realm in the Authentication header. If an exact match<br>+ on both username and domain/realm fails, the match is<br>+ retried with just the username.<br>+ </para><br>+ <note><para>This method of identification has some security<br>+ considerations because an Authentication header is not<br>+ present on the first message of a dialog when digest<br>+ authentication is used. The client can't generate it until<br>+ the server sends the challenge in a 401 response. Since<br>+ Asterisk normally sends a security event when an incoming<br>+ request can't be matched to an endpoint, using this method<br>+ requires that the security event be deferred until a request<br>+ is received with the Authentication header and only<br>+ generated if the username doesn't result in a match. This<br>+ may result in a delay before an attack is recognized. You<br>+ can control how many unmatched requests are received from<br>+ a single ip address before a security event is generated<br>+ using the <literal>unidentified_request</literal><br>+ parameters in the "global" configuration object.<br>+ </para></note><br>+ </enum><br>+ <enum name="ip"><br>+ <para>Matches the endpoint based on the source IP address.<br>+ </para><br>+ <para>This method of identification is not configured here<br>+ but simply allowed by this configuration option. See the<br>+ documentation for the <literal>identify</literal><br>+ configuration section for more details on this method of<br>+ endpoint identification.<br>+ </para><br>+ </enum><br> </enumlist><br> </description><br> </configOption><br>@@ -1623,7 +1638,7 @@<br> <synopsis>Enable/Disable SIP debug logging. Valid options include yes|no or<br> a host address</synopsis><br> </configOption><br>- <configOption name="endpoint_identifier_order" default="ip,username,anonymous"><br>+ <configOption name="endpoint_identifier_order"><br> <synopsis>The order by which endpoint identifiers are processed and checked.<br> Identifier names are usually derived from and can be found in the endpoint<br> identifier module itself (res_pjsip_endpoint_identifier_*).<br>@@ -1751,9 +1766,15 @@<br> <parameter name="Endpoint"><br> <para><xi:include xpointer="xpointer(/docs/configInfo[@name='res_pjsip_endpoint_identifier_ip']/configFile[@name='pjsip.conf']/configObject[@name='identify']/configOption[@name='endpoint']/synopsis/node())"/></para><br> </parameter><br>+ <parameter name="SrvLookups"><br>+ <para><xi:include xpointer="xpointer(/docs/configInfo[@name='res_pjsip_endpoint_identifier_ip']/configFile[@name='pjsip.conf']/configObject[@name='identify']/configOption[@name='srv_lookups']/synopsis/node())"/></para><br>+ </parameter><br> <parameter name="Match"><br> <para><xi:include xpointer="xpointer(/docs/configInfo[@name='res_pjsip_endpoint_identifier_ip']/configFile[@name='pjsip.conf']/configObject[@name='identify']/configOption[@name='match']/synopsis/node())"/></para><br> </parameter><br>+ <parameter name="MatchHeader"><br>+ <para><xi:include xpointer="xpointer(/docs/configInfo[@name='res_pjsip_endpoint_identifier_ip']/configFile[@name='pjsip.conf']/configObject[@name='identify']/configOption[@name='match_header']/synopsis/node())"/></para><br>+ </parameter><br> <parameter name="EndpointName"><br> <para>The name of the endpoint associated with this information.</para><br> </parameter><br>diff --git a/res/res_pjsip_endpoint_identifier_ip.c b/res/res_pjsip_endpoint_identifier_ip.c<br>index 5324af7..2e6f565 100644<br>--- a/res/res_pjsip_endpoint_identifier_ip.c<br>+++ b/res/res_pjsip_endpoint_identifier_ip.c<br>@@ -53,31 +53,39 @@<br> </enumlist><br> </description><br> <configOption name="endpoint"><br>- <synopsis>Name of Endpoint</synopsis><br>+ <synopsis>Name of endpoint identified</synopsis><br> </configOption><br> <configOption name="match"><br> <synopsis>IP addresses or networks to match against.</synopsis><br>- <description><para><br>- The value is a comma-delimited list of IP addresses. IP addresses may<br>- have a subnet mask appended. The subnet mask may be written in either<br>- CIDR or dot-decimal notation. Separate the IP address and subnet<br>- mask with a slash ('/').<br>- </para></description><br>+ <description><br>+ <para>The value is a comma-delimited list of IP addresses or<br>+ hostnames. IP addresses may have a subnet mask appended. The<br>+ subnet mask may be written in either CIDR or dotted-decimal<br>+ notation. Separate the IP address and subnet mask with a slash<br>+ ('/').<br>+ </para><br>+ </description><br> </configOption><br> <configOption name="srv_lookups" default="yes"><br> <synopsis>Perform SRV lookups for provided hostnames.</synopsis><br>- <description><para>When enabled, <replaceable>srv_lookups</replaceable> will<br>- perform SRV lookups for _sip._udp, _sip._tcp, and _sips._tcp of the given<br>- hostnames to determine additional addresses that traffic may originate from.<br>- </para></description><br>+ <description><br>+ <para>When enabled, <replaceable>srv_lookups</replaceable> will<br>+ perform SRV lookups for _sip._udp, _sip._tcp, and _sips._tcp of<br>+ the given hostnames to determine additional addresses that traffic<br>+ may originate from.<br>+ </para><br>+ </description><br> </configOption><br> <configOption name="match_header"><br> <synopsis>Header/value pair to match against.</synopsis><br>- <description><para>A SIP header who value is used to match against. SIP<br>- requests containing the header, along with the specified value, will be<br>- mapped to the specified endpoint. The header must be specified with a<br>- <literal>:</literal>, as in <literal>match_header = SIPHeader: value</literal>.<br>- </para></description><br>+ <description><br>+ <para>A SIP header whose value is used to match against. SIP<br>+ requests containing the header, along with the specified value,<br>+ will be mapped to the specified endpoint. The header must be<br>+ specified with a <literal>:</literal>, as in<br>+ <literal>match_header = SIPHeader: value</literal>.<br>+ </para><br>+ </description><br> </configOption><br> <configOption name="type"><br> <synopsis>Must be of type 'identify'.</synopsis><br></pre><p>To view, visit <a href="https://gerrit.asterisk.org/7890">change 7890</a>. To unsubscribe, 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/7890"/><meta itemprop="name" content="View Change"/></div></div>
<div style="display:none"> Gerrit-Project: asterisk </div>
<div style="display:none"> Gerrit-Branch: 13 </div>
<div style="display:none"> Gerrit-MessageType: newchange </div>
<div style="display:none"> Gerrit-Change-Id: Id92f00b495acca7be945daf749d2abd7f76a0b5a </div>
<div style="display:none"> Gerrit-Change-Number: 7890 </div>
<div style="display:none"> Gerrit-PatchSet: 1 </div>
<div style="display:none"> Gerrit-Owner: Richard Mudgett <rmudgett@digium.com> </div>