Whitelists for SIP

Oracle Communications Session Border Controller by default ignores and passes-through unknown SIP headers and URI parameters. However, some operators require that the Oracle Communications Session Border Controller only accept messages with headers and URI parameters complying with those supported by their internal equipment. This section describes the use of whitelists to control unknown headers and parameters in request and response traffic.

What is a Whitelist

A whitelist is an approved list of entities for which equipment provides particular privileges, access, and recognition. The Oracle Communications Session Border Controller can use configured whitelist profiles to control and accept specific inbound SIP headers and URI parameters that are being passed-through the Oracle Communications Session Border Controller. When you configure this feature, the Oracle Communications Session Border Controller rejects requests not matching the configured profile, or removes the unspecified headers or URI parameters not in the configured profile.

Whitelists Configuration

You can configure whitelist profiles or rules that allow the Oracle Communications Session Border Controller to only accept inbound SIP headers and URI parameters that are configured in this whitelist, using the parameter allowed-elements-profile. You can configure the settings for this parameter using the ACLI interface at session-router, enforcement-profile. Since the enforcement-profile object also pertains to session agents, realms, and SIP interfaces, you can also apply the profiles you configure to these remote entities using the ACLI interface at session-router, session-agent, session-router, sip-interface, and media-manager, realm-config.

In the following configuration example, it is assumed that your baseline configuration passes SIP traffic, with the Oracle Communications Session Border Controller in the role of an Access SBC. Use this procedure to configure a whitelist for the session router and optionally apply the specific whitelists to the session agent and SIP interface, as well as the media manager’s realm configuration.

To configure a whitelist for the session router:

Access the allowed-elements-profile configuration element.

ORACLE# configure terminal
ORACLE(configure)# session-router
ORACLE(session-router)# allowed-elements-profile
ORACLE(allowed-elements-profile)#

name— Enter a unique name for the whitelist you are creating. This name can be referenced when configuring the enforcement-profiles for session-agent, SIP interface, and realm-config.
```
ORACLE(allowed-elements-profile)# name whitelist1
```
description— Enter a description that explains the purpose of creating this whitelist. You can use any alpha-numeric characters when entering the description.
```
ORACLE(allowed-elements-profile)# description Basic Whitelist
```
Navigate to the rule-sets configuration element to specify the rules to match against specific incoming SIP headers and/or URI parameters.
```
ORACLE(allowed-elements-profile)# rule-sets
ORACLE(rule-sets)#
```
unmatched-action— Select the action for the Oracle Communications Session Border Controller to perform when a header does not exist in an incoming message. The default value is reject. The valid values are:
- reject — Rejects all incoming messages that do not contain a header.
- delete — Deletes all incoming message that do not contain a header.
  
  Note:
  This parameter applies to non-matching header names only (not non-matching URI parameters).
```
ORACLE(rule-sets)# unmatched action delete
```
msg-type — Specify the type of messages for which the Oracle Communications Session Border Controller applies this whitelist configuration. The default value is any. The valid values are:
- any — Applies to all incoming messages.
- request — Applies to only incoming REQUEST messages.
- response — Applies to only incoming RESPONSE messages.
```
ORACLE(rule-sets)# msg-type any
```
methods — Enter the packet method(s), separated by a comma, for which this whitelist is enforced. Packet methods include, INVITE, OPTIONS, ACK, BYE, etc. If this field is left blank, the whitelist applies to all packet methods. You can enter up to a maximum of 255 characters.
```
ORACLE(rule-sets)# methods INVITE,ACK,BYE
```
logging — Select whether or not an incoming message is written to a log file called matched.log when the message contains an element not specified in the whitelist. The default value is disabled. The valid values are:
- enabled | disabled
```
ORACLE(rule-sets)# logging enabled
```
The matched.log contains information about the timestamp, received/sent Oracle Communications Session Border Controller network-interface, IP address/port from which it was received or being sent from, and which peer IP address/port it was received from or sent to. The log also specifies the request URI (if applicable), and the From, To, and Contact headers in the message, as well as which rule triggered the log action. An example of the log output of the matched.log file is as follows:
```
Dec 17 14:17:54.526 On [0:0]192.168.1.84:5060 sent to 192.168.1.60:5060
allowed-elements-profile[whitelist1(reject)]
INVITE sip:service@192.168.1.84:5060 SIP/2.0
From: sipp <sip:+2125551212@192.168.1.60:5060>;tag=3035SIPpTag001
To: sut <sip:service@192.168.1.84>
Contact: sip:sipp@192.168.1.60:5060
```
The header-rule object consists of 6 parameters that make up the header-rule:
- header-name
- unmatched-action
- allow-header-param
- allow-uri-param
- allow-uri-user-param
- allow-uri-header-name
  
  You can configure an unlimited number of header-rules on the Oracle Communications Session Border Controller that you can apply to your network. Use the following parameters to configure a header-rule that the Oracle Communications Session Border Controller uses to control which incoming messages it allows.
header-rule — This object allows you to configure, as part of the whitelist, multiple parameters which make up the header rule that the Oracle Communications Session Border Controller allows from incoming messages. Header-rules do NOT have to be in any specific order. The system prompt changes to let you know that you can begin configuring individual parameters for this object.
```
ORACLE(rule-set)# header-rule
ORACLE(allowed-header-rule)#
```
header-name — Enter the name of the header in the whitelist that the Oracle Communications Session Border Controller allows from incoming messages. It is case-insensitive and supports abbreviated forms of header names. For example, “Via”, “via”, or “v” all match against the same header. A header name of “request-uri” refers to the request URI of requests, while a header name of * applies to any header-type not matched by any other header-rule. The default value is *. This default value provides the ability to have header-rules for commonly known headers that remove unknown parameters, but leave unknown headers alone.
```
ORACLE(allowed-header-rule)# header-name Contact
```
unmatched-action — Select the action for the Oracle Communications Session Border Controller to perform when an incoming header’s parameters do not match the relevant allowed parameters specified for this header-name. The default value is reject. The valid values are:
- reject — Rejects all incoming messages that have header parameters that do not match the parameters specified in this header-name.
- delete — Deletes all incoming messages that have header parameters that do not match the parameters specified in this header-name.
  
  Note:
  This parameter applies to non-matching header names only (not non-matching URI parameters).
```
ORACLE(allowed-header-rule)# unmatched-action delete
```
allow-header-param — Enter the header parameter that the Oracle Communications Session Border Controller allows from the headers in incoming messages. You can enter up to 255 characters, including a comma (,), semi-colon (;), equal sign (=), question mark (?), at-symbol (@), backslash (\), or plus sign (+). The default value is *, which allows all header parameters to pass through. If you leave this field empty, no header parameters are allowed.
```
ORACLE(allowed-header-rule)# allow-header-param *
```
allow-uri-param — Enter the URI parameter that the Oracle Communications Session Border Controller allows from the headers in incoming messages. You can enter up to 255 characters, including a comma (,), semi-colon (;), equal sign (=), question mark (?), at-symbol (@), backslash (\), or plus sign (+). The default value is *, which allows all URI parameters to pass through. If you leave this field empty, no URI parameters are allowed.
```
ORACLE(allowed-header-rule)# allow-uri-param *
```
allow-uri-user-param — Enter the URI user parameter that the Oracle Communications Session Border Controller allows from the headers in incoming messages. You can enter up to 255 characters, including a comma (,), semi-colon (;), equal sign (=), question mark (?), at-symbol (@), backslash (\), or plus sign (+). The default value is *, which allows all URI user parameters to pass through. If you leave this field empty, no URI user parameters are allowed.
```
ORACLE(allowed-header-rule)# allow-uri-user-param *
```
allow-uri-header-name — Enter the URI header name that the Oracle Communications Session Border Controller allows from the headers in incoming messages. You can enter up to 255 characters, including a comma (,), semi-colon (;), equal sign (=), question mark (?), at-symbol (@), backslash (\), or plus sign (+). The default value is *, which allows all URI header name parameters to pass through. If you leave this field empty, no URI header name parameters are allowed.
```
ORACLE(allowed-header-rule)# allow-uri-header-name *
```
Save your work using the done command.

Configuration Exception

There are specific instances in incoming Request-URI messages where the Oracle Communications Session Border Controller ignores specific parameters and automatically adds header-rules.

In a Request-URI, all parameters are URI parameters, and URI headers are not allowed. If you define values for the “allow-header-param”, “allow-uri-header-name”, and “allow-uri-param”, the Oracle Communications Session Border Controller ignores these parameters in the Request-URI. Instead the Oracle Communications Session Border Controller automatically adds header-rules for incoming “Via”, “From”, To”, “Call-ID”, and “CSeq” messages. These are explicit header rules and cannot be deleted. Each header-rule in a Request-URI has parameters populated with the value of *. If required, a user can change the header-rule parameter values with the values identified in the following table.

Header Rule	Applicable Parameter	Required Value(s)
Via	allow-header-param	branch received rport
From	allow-header-param	tag
To	allow-header-param	tag
Call-ID	allow-header-param	No restrictions
CSeq	allow-header-param	No restrictions

Verify Whitelist Configuration

After you have configured and saved a whitelist on the Oracle Communications Session Border Controller, you can use the existing verify-config command at the top level prompt to verify the saved configuration: For example:

ORACLE# verify-config

This command checks for errors in the Oracle Communications Session Border Controller configuration. Whitelist configuration errors specifically related to the enforcement-profile object also display in the output of this command if applicable. The whitelist configuration errors display if any references to the allowed-element-profiles are improperly configured. If errors exist, the following message displays:

---------------------------------------------------------------------
ERROR: enforcement-profile [ep] contains a reference to an allowed-enforcement-profile [abc] that does not exist
---------------------------------------------------------------------

How Whitelists Work

Whitelists allow you to customize which SIP signaling messages to allow into your network and which messages to reject or delete. In the flow of SIP traffic to/from the Oracle Communications Session Border Controller, the Oracle Communications Session Border Controller matches any received request or response, in or out of a dialog against the configured allowed list, and rejects or deletes the non-matching element based on the actions specified in the whitelist configuration.

For responses, the Oracle Communications Session Border Controller does not reject the message if a header or parameter is not found in the allowed list, even if the action is set to reject. Instead it deletes the offending parameter or header. In addition, if the message is a request of the method type ACK, PRACK, CANCEL or BYE, it deletes all unmatched elements, but does not reject the request, even if the action was configured to reject.

The whitelist verification performs for any method; however you can narrow this list to operate only on specific methods by defining them in the methods parameter of the configuration.

Whitelist verification occurs when a request or response is received by the Oracle Communications Session Border Controller, but only after the Oracle Communications Session Border Controller has processed the inbound header manipulation rule (HMR), network management controls (NMC), Resource-Priority header (RPH), and monthly-minutes checking.

The Oracle Communications Session Border Controller responds to requests which have non-matching headers or parameters configured with an action of reject, with a "403 Forbidden" response by default. You can use a local-response event, allowed-elements-profile-rejection, to override the default reject status code and reason phrase.

The configured whitelist operates transparently on headers that have multiple URIs or multiple header values within a single header (header values separated by a comma).

Parameter parsing operates only on parameters that it can identify. For parameters that can not be parsed, for example an invalid URI (e.g. <sip:user@host.com&hp=val>), the Oracle Communications Session Border Controller ignores this URI header parameter value of "hp" since it is not contained within a valid URI. Even though it would appear to be a URI header parameter, URI headers must come after URI parameters. Parameter matching does not occur if the headers and parameters in the URI are not well-formed. The Oracle Communications Session Border Controller does not remove the parameter since it cannot identify it.