From 8f3167c5f17a5c85bd7d6c42f3c22f56e081eaba Mon Sep 17 00:00:00 2001
From: Richard Mudgett <rmudgett@digium.com>
Date: Wed, 3 Jan 2018 17:26:42 -0600
Subject: [PATCH] res_pjsip.c: Update the endpoint identification
documentation.
* Endpoint identify_by documentation.
* IP/Header endpoint identifier documentation.
Change-Id: Id92f00b495acca7be945daf749d2abd7f76a0b5a
---
configs/samples/pjsip.conf.sample | 18 +++--
res/res_pjsip.c | 93 ++++++++++++++++----------
res/res_pjsip_endpoint_identifier_ip.c | 45 ++++++++-----
3 files changed, 96 insertions(+), 60 deletions(-)
diff --git a/configs/samples/pjsip.conf.sample b/configs/samples/pjsip.conf.sample
index 302899a174..8499320699 100644
--- a/configs/samples/pjsip.conf.sample
+++ b/configs/samples/pjsip.conf.sample
@@ -635,9 +635,9 @@
; "username": Identify by the From or To username and domain
; "auth_username": Identify by the Authorization username and realm
; "ip": Identify by the source IP address
- ; In username and auth_username cases, if an exact match on
- ; username and domain/realm fails, the match will be retried
- ; with just the username.
+ ; In the username and auth_username cases, if an exact match
+ ; on both username and domain/realm fails, the match is
+ ; retried with just the username.
; (default: "username,ip")
;redirect_method=user ; How redirects received from an endpoint are handled
; (default: "user")
@@ -1135,9 +1135,15 @@
; MODULE PROVIDING BELOW SECTION(S): res_pjsip_endpoint_identifier_ip
;==========================IDENTIFY SECTION OPTIONS=========================
;[identify]
-; SYNOPSIS: Identifies endpoints via source IP address
-;endpoint= ; Name of Endpoint (default: "")
-;match= ; IP addresses or networks to match against (default: "")
+; SYNOPSIS: Identifies endpoints via some criteria.
+;
+; NOTE: If multiple matching criteria are provided then an inbound request will
+; be matched to the endpoint if it matches ANY of the criteria.
+;endpoint= ; Name of endpoint identified (default: "")
+;srv_lookups=yes ; Perform SRV lookups for provided hostnames. (default: yes)
+;match= ; Comma separated list of IP addresses, networks, or hostnames to match
+ ; against (default: "")
+;match_header= ; SIP header with specified value to match against (default: "")
;type= ; Must be of type identify (default: "")
diff --git a/res/res_pjsip.c b/res/res_pjsip.c
index 654f4ba4ea..de1df531d9 100644
--- a/res/res_pjsip.c
+++ b/res/res_pjsip.c
@@ -269,45 +269,60 @@
<configOption name="ice_support" default="no">
<synopsis>Enable the ICE mechanism to help traverse NAT</synopsis>
</configOption>
- <configOption name="identify_by" default="username,ip">
- <synopsis>Way(s) for Endpoint to be identified</synopsis>
- <description><para>
- Endpoints and aors can be identified in multiple ways. Currently, the supported
- options are <literal>username</literal>, which matches the endpoint or aor id based on
- the username and domain in the From header (or To header for aors),
- <literal>auth_username</literal>, which matches the endpoint or aor id based on the
- username and realm in the Authentication header, and <literal>ip</literal> which matches
- an endpoint based on the source IP address. In the <literal>username</literal> and
- <literal>auth_username</literal> cases, if an exact match on both username and
- domain/realm fails, the match will be retried with just the username.
+ <configOption name="identify_by">
+ <synopsis>Way(s) for the endpoint to be identified</synopsis>
+ <description>
+ <para>Endpoints and AORs can be identified in multiple ways. This
+ option is a comma separated list of methods the endpoint can be
+ identified.
</para>
<note><para>
- Identification by auth_username has some security considerations because an
- Authentication header is not present on the first message of a dialog when
- digest authentication is used. The client can't generate it until the server
- sends the challenge in a 401 response. Since Asterisk normally sends a security
- event when an incoming request can't be matched to an endpoint, using auth_username
- requires that the security event be deferred until a request is received with
- the Authentication header and only generated if the username doesn't result in a
- match. This may result in a delay before an attack is recognized. You can control
- how many unmatched requests are received from a single ip address before a security
- event is generated using the unidentified_request parameters in the "global"
- configuration object.
+ This option controls both how an endpoint is matched for incoming
+ traffic and also how an AOR is determined if a registration
+ occurs. You must list at least one method that also matches for
+ AORs or the registration will fail.
</para></note>
- <note><para>Endpoints can also be identified by IP address; however, that method
- of identification is not configured but simply allowed by this configuration option.
- See the documentation for the <literal>identify</literal> configuration section for
- more details on that method of endpoint identification.</para></note>
- <note><para>
- This option controls both how an endpoint is matched for incoming traffic and also how
- an AoR is determined if a registration occurs. If <literal>ip</literal> is set alone
- then incoming registration will not find an AoR and the registration attempt will fail.
- If you want to allow incoming registrations to succeed you must set a second identify
- method such as <literal>username</literal> in this case.</para></note>
<enumlist>
- <enum name="username" />
- <enum name="auth_username" />
- <enum name="ip" />
+ <enum name="username">
+ <para>Matches the endpoint or AOR ID based on the username
+ and domain in the From header (or To header for AORs). If
+ an exact match on both username and domain/realm fails, the
+ match is retried with just the username.
+ </para>
+ </enum>
+ <enum name="auth_username">
+ <para>Matches the endpoint or AOR ID based on the username
+ and realm in the Authentication header. If an exact match
+ on both username and domain/realm fails, the match is
+ retried with just the username.
+ </para>
+ <note><para>This method of identification has some security
+ considerations because an Authentication header is not
+ present on the first message of a dialog when digest
+ authentication is used. The client can't generate it until
+ the server sends the challenge in a 401 response. Since
+ Asterisk normally sends a security event when an incoming
+ request can't be matched to an endpoint, using this method
+ requires that the security event be deferred until a request
+ is received with the Authentication header and only
+ generated if the username doesn't result in a match. This
+ may result in a delay before an attack is recognized. You
+ can control how many unmatched requests are received from
+ a single ip address before a security event is generated
+ using the <literal>unidentified_request</literal>
+ parameters in the "global" configuration object.
+ </para></note>
+ </enum>
+ <enum name="ip">
+ <para>Matches the endpoint based on the source IP address.
+ </para>
+ <para>This method of identification is not configured here
+ but simply allowed by this configuration option. See the
+ documentation for the <literal>identify</literal>
+ configuration section for more details on this method of
+ endpoint identification.
+ </para>
+ </enum>
</enumlist>
</description>
</configOption>
@@ -1676,7 +1691,7 @@
<synopsis>Enable/Disable SIP debug logging. Valid options include yes|no or
a host address</synopsis>
</configOption>
- <configOption name="endpoint_identifier_order" default="ip,username,anonymous">
+ <configOption name="endpoint_identifier_order">
<synopsis>The order by which endpoint identifiers are processed and checked.
Identifier names are usually derived from and can be found in the endpoint
identifier module itself (res_pjsip_endpoint_identifier_*).
@@ -1804,9 +1819,15 @@
<parameter name="Endpoint">
<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>
</parameter>
+ <parameter name="SrvLookups">
+ <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>
+ </parameter>
<parameter name="Match">
<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>
</parameter>
+ <parameter name="MatchHeader">
+ <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>
+ </parameter>
<parameter name="EndpointName">
<para>The name of the endpoint associated with this information.</para>
</parameter>
diff --git a/res/res_pjsip_endpoint_identifier_ip.c b/res/res_pjsip_endpoint_identifier_ip.c
index e40f9bff49..add1146f71 100644
--- a/res/res_pjsip_endpoint_identifier_ip.c
+++ b/res/res_pjsip_endpoint_identifier_ip.c
@@ -43,41 +43,50 @@
<para>This module provides alternatives to matching inbound requests to
a configured endpoint. At least one of the matching mechanisms
must be provided, or the object configuration will be invalid.</para>
- <para>If multiple criteria are provided, an inbound request will
- be matched if it matches <emphasis>any</emphasis> of the criteria.</para>
<para>The matching mechanisms are provided by the following
configuration options:</para>
<enumlist>
<enum name="match"><para>Match by source IP address.</para></enum>
<enum name="match_header"><para>Match by SIP header.</para></enum>
</enumlist>
+ <note><para>If multiple matching criteria are provided then an inbound
+ request will be matched to the endpoint if it matches
+ <emphasis>any</emphasis> of the criteria.</para></note>
</description>
<configOption name="endpoint">
- <synopsis>Name of Endpoint</synopsis>
+ <synopsis>Name of endpoint identified</synopsis>
</configOption>
<configOption name="match">
<synopsis>IP addresses or networks to match against.</synopsis>
- <description><para>
- The value is a comma-delimited list of IP addresses. IP addresses may
- have a subnet mask appended. The subnet mask may be written in either
- CIDR or dot-decimal notation. Separate the IP address and subnet
- mask with a slash ('/').
- </para></description>
+ <description>
+ <para>The value is a comma-delimited list of IP addresses or
+ hostnames. IP addresses may have a subnet mask appended. The
+ subnet mask may be written in either CIDR or dotted-decimal
+ notation. Separate the IP address and subnet mask with a slash
+ ('/').
+ </para>
+ </description>
</configOption>
<configOption name="srv_lookups" default="yes">
<synopsis>Perform SRV lookups for provided hostnames.</synopsis>
- <description><para>When enabled, <replaceable>srv_lookups</replaceable> will
- perform SRV lookups for _sip._udp, _sip._tcp, and _sips._tcp of the given
- hostnames to determine additional addresses that traffic may originate from.
- </para></description>
+ <description>
+ <para>When enabled, <replaceable>srv_lookups</replaceable> will
+ perform SRV lookups for _sip._udp, _sip._tcp, and _sips._tcp of
+ the given hostnames to determine additional addresses that traffic
+ may originate from.
+ </para>
+ </description>
</configOption>
<configOption name="match_header">
<synopsis>Header/value pair to match against.</synopsis>
- <description><para>A SIP header who value is used to match against. SIP
- requests containing the header, along with the specified value, will be
- mapped to the specified endpoint. The header must be specified with a
- <literal>:</literal>, as in <literal>match_header = SIPHeader: value</literal>.
- </para></description>
+ <description>
+ <para>A SIP header whose value is used to match against. SIP
+ requests containing the header, along with the specified value,
+ will be mapped to the specified endpoint. The header must be
+ specified with a <literal>:</literal>, as in
+ <literal>match_header = SIPHeader: value</literal>.
+ </para>
+ </description>
</configOption>
<configOption name="type">
<synopsis>Must be of type 'identify'.</synopsis>
--
GitLab