res_pjsip.c: Update the endpoint identification documentation.
authorRichard Mudgett <rmudgett@digium.com>
Wed, 3 Jan 2018 23:26:42 +0000 (17:26 -0600)
committerRichard Mudgett <rmudgett@digium.com>
Tue, 9 Jan 2018 19:38:59 +0000 (13:38 -0600)
* Endpoint identify_by documentation.
* IP/Header endpoint identifier documentation.

Change-Id: Id92f00b495acca7be945daf749d2abd7f76a0b5a

configs/samples/pjsip.conf.sample
res/res_pjsip.c
res/res_pjsip_endpoint_identifier_ip.c

index 302899a..8499320 100644 (file)
                         ; "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")
 ; 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: "")
 
 
index 654f4ba..de1df53 100644 (file)
                                <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>
                                        <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_*).
                                <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>
index e40f9bf..add1146 100644 (file)
                                        <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>