[Asterisk-code-review] res pjsip.c: Update the endpoint identification documentation. (asterisk[13])

Richard Mudgett asteriskteam at digium.com
Tue Jan 9 12:15:33 CST 2018


Richard Mudgett has uploaded this change for review. ( https://gerrit.asterisk.org/7890


Change subject: res_pjsip.c: Update the endpoint identification documentation.
......................................................................

res_pjsip.c: Update the endpoint identification documentation.

* Endpoint identify_by documentation.
* IP/Header endpoint identifier documentation.

Change-Id: Id92f00b495acca7be945daf749d2abd7f76a0b5a
---
M configs/samples/pjsip.conf.sample
M res/res_pjsip.c
M res/res_pjsip_endpoint_identifier_ip.c
3 files changed, 90 insertions(+), 58 deletions(-)



  git pull ssh://gerrit.asterisk.org:29418/asterisk refs/changes/90/7890/1

diff --git a/configs/samples/pjsip.conf.sample b/configs/samples/pjsip.conf.sample
index aff8ead..bdd2e65 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")
@@ -1109,9 +1109,12 @@
 ; 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.
+;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 842cc20..f61071a 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>
@@ -1623,7 +1638,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_*).
@@ -1751,9 +1766,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 5324af7..2e6f565 100644
--- a/res/res_pjsip_endpoint_identifier_ip.c
+++ b/res/res_pjsip_endpoint_identifier_ip.c
@@ -53,31 +53,39 @@
 					</enumlist>
 				</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>

-- 
To view, visit https://gerrit.asterisk.org/7890
To unsubscribe, visit https://gerrit.asterisk.org/settings

Gerrit-Project: asterisk
Gerrit-Branch: 13
Gerrit-MessageType: newchange
Gerrit-Change-Id: Id92f00b495acca7be945daf749d2abd7f76a0b5a
Gerrit-Change-Number: 7890
Gerrit-PatchSet: 1
Gerrit-Owner: Richard Mudgett <rmudgett at digium.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-code-review/attachments/20180109/f5c601a0/attachment-0001.html>


More information about the asterisk-code-review mailing list