From 6d9482267bb2b4384c5377522ef119842ad9f5f0 Mon Sep 17 00:00:00 2001 From: Richard Mudgett 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 7ee15acadb..798831554b 100644 --- a/res/res_pjsip.c +++ b/res/res_pjsip.c @@ -269,45 +269,60 @@ Enable the ICE mechanism to help traverse NAT - - Way(s) for Endpoint to be identified - - Endpoints and aors can be identified in multiple ways. Currently, the supported - options are username, which matches the endpoint or aor id based on - the username and domain in the From header (or To header for aors), - auth_username, which matches the endpoint or aor id based on the - username and realm in the Authentication header, and ip which matches - an endpoint based on the source IP address. In the username and - auth_username cases, if an exact match on both username and - domain/realm fails, the match will be retried with just the username. + + Way(s) for the endpoint to be identified + + Endpoints and AORs can be identified in multiple ways. This + option is a comma separated list of methods the endpoint can be + identified. - 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. - 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 identify configuration section for - more details on that method of endpoint identification. - - This option controls both how an endpoint is matched for incoming traffic and also how - an AoR is determined if a registration occurs. If ip 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 username in this case. - - - + + 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. + + + + 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. + + 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 unidentified_request + parameters in the "global" configuration object. + + + + Matches the endpoint based on the source IP address. + + This method of identification is not configured here + but simply allowed by this configuration option. See the + documentation for the identify + configuration section for more details on this method of + endpoint identification. + + @@ -1676,7 +1691,7 @@ Enable/Disable SIP debug logging. Valid options include yes|no or a host address - + 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 @@ + + + + + + The name of the endpoint associated with this information. 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 @@ 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. - If multiple criteria are provided, an inbound request will - be matched if it matches any of the criteria. The matching mechanisms are provided by the following configuration options: Match by source IP address. Match by SIP header. + If multiple matching criteria are provided then an inbound + request will be matched to the endpoint if it matches + any of the criteria. - Name of Endpoint + Name of endpoint identified IP addresses or networks to match against. - - 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 ('/'). - + + 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 + ('/'). + + Perform SRV lookups for provided hostnames. - When enabled, srv_lookups 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. - + + When enabled, srv_lookups 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. + + Header/value pair to match against. - 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 - :, as in match_header = SIPHeader: value. - + + 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 :, as in + match_header = SIPHeader: value. + + Must be of type 'identify'.