kenmirrors/asterisk
1
0
Fork 0
mirror of https://github.com/asterisk/asterisk.git synced 2025-09-18 18:58:22 +00:00
Code Issues Packages Projects Releases Wiki Activity

res_pjsip.c: Update the endpoint identification documentation.

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

Change-Id: Id92f00b495acca7be945daf749d2abd7f76a0b5a
This commit is contained in:
Richard Mudgett
2018-01-03 17:26:42 -06:00
parent 3a7d917256
commit 8f3167c5f1
3 changed files with 96 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
configs/samples/pjsip.conf.sample
View File

@@ -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: "")

93
res/res_pjsip.c
View File

@@ -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>

45
res/res_pjsip_endpoint_identifier_ip.c
View File

@@ -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>