White Lists for Managing Incoming SIP Headers and Parameters

By default, the Oracle® Enterprise Session Border Controller (E-SBC) ignores unknown SIP headers and URI parameters and passes them through. If you require the E-SBC to accept only messages with headers and URI parameters complying with those supported by your internal equipment, you can use white lists to control unknown headers and parameters in request and response traffic. A white list is an approved list of entities for which your equipment provides particular privileges, access, and recognition. The E-SBC uses configured white list profiles to control and accept specific inbound SIP headers and URI parameters. When you configure this service, the E-SBC rejects requests not matching the configured profile, or removes the headers or URI parameters not specified in the configured profile.

White lists allow you to specify which SIP signaling messages you want to allow into your network and which messages to reject or delete. In the flow of SIP traffic to and from the E-SBC, the E-SBC matches any received request or response against the white list and rejects or deletes elements that do not match based on the actions specified in the white list configuration.

For responses, the E-SBC does not reject the message if a header or parameter is not found in the white list, even if the action is set to reject. Instead, the E-SBC deletes the offending parameter or header. In addition, if the message is a request of the method type ACK, PRACK, CANCEL or BYE, the E-SBC deletes all unmatched elements and does not reject the request, even if the action was configured to reject.

The white list verification performs for any method, but you can narrow the list to operate only on specific methods by defining them in the methods parameter of the configuration.

White list verification occurs when the E-SBC receives a request or response, but only after the E-SBC processes the inbound header manipulation rule (HMR), network management controls (NMC), Resource-Priority header (RPH), and monthly minutes checking.

The E-SBC responds to requests that with 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 white list operates transparently on headers that contain 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 cannot be parsed, for example an invalid URI (<sip:user@host.com&hp=val>), the E-SBC ignores this URI header parameter value of "hp" because it is not contained within a valid URI. Even though it might look like 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 E-SBC does not remove the parameter just because it cannot identify it.

White List Learning

You can build a SIP header and URI parameter white list configuration by way of the learning capabilities of the Oracle® Enterprise Session Border Controller (E-SBC). When you enable learning mode on the E-SBC, it acquires the knowledge of the allowable headers and parameters currently coming into your network. The E-SBC collects the information about the headers received and the parameters that exist within each header. The system gathers the information until you disable the learning mode.

After you disable the learning mode, the E-SBC prompts you to enter a name for the allowed-elements-profile. If the profile name you entered does not exist, the captured information is written to the new allowed-elements-profile configuration. The administrator can then make changes to the configuration as applicable, save the configuration, and apply it to a logical remote entity.

The allowed-elements-profile does not contain any wildcard rules because the E-SBC cannot generate wildcard headers and parameters during the learning mode. The Methods object is populated from the list of methods seen by the E-SBC while learning.

Note:

Oracle recommends running the learning mode during off-peak and light traffic periods. Learning mode can operate in conjunction with the execution of an allowed-elements-profile. The learning occurs just before any configured allowed-elements-profile configuration.

White List Learning Configuration

The ACLI interface provides two commands that allow a Superuser to start and stop white list learning on the Oracle® Enterprise Session Border Controller:

Command	Description
start <argument> <options>	Starts white list learning on the Oracle® Enterprise Session Border Controller. You must specify the argument learn-allowed-elements with this command to start the learning operation. Optionally, you can use method, msg-type, and params after the argument.
stop <argument> <identifier>	Stops the white list learning on the Oracle® Enterprise Session Border Controller and writes the learned configuration to the editing configuration on the Oracle® Enterprise Session Border Controller where it is saved and activated. You must specify the argument learn-allowed-elements with this command to stop the learning operation. You must specify a unique identifier that identifies the allowed-elements-profile name. If you specify an identifier name that already exists as a profile, the ACLI returns an error message and prompts you to enter a different name.

Command

Description

start <argument> <options>

Starts white list learning on the Oracle® Enterprise Session Border Controller.

You must specify the argument learn-allowed-elements with this command to start the learning operation.

Optionally, you can use method, msg-type, and params after the argument.

stop <argument> <identifier>

Stops the white list learning on the Oracle® Enterprise Session Border Controller and writes the learned configuration to the editing configuration on the Oracle® Enterprise Session Border Controller where it is saved and activated.

You must specify the argument learn-allowed-elements with this command to stop the learning operation.

You must specify a unique identifier that identifies the allowed-elements-profile name.

If you specify an identifier name that already exists as a profile, the ACLI returns an error message and prompts you to enter a different name.

You can use these commands at the top level ACLI prompt as required on the Oracle® Enterprise Session Border Controller.

You use these commands with the argument, learn-allowed-elements to start/stop the white list learning feature. By default, the learning mode creates a single rule-set under which all of the headers and their respective parameters are stored.

For example:

ORACLE# start learn-allowed-elements
Learning mode for allowed-elements-profile started.

In the above example, start is the top level ACLI command and learn-allowed-elements is the operation being performed.

Optionally, you can specify [method], [msg-type], and [params] in any order, for the Oracle® Enterprise Session Border Controller to learn specific rule-set elements from incoming messages and save them to the white list configuration.

For example:

ORACLE# start learn-allowed-elements method msg-type params

The method option creates a new rule-set per unique method. The msg-type option creates a new rule-set per unique message-type seen. The params option performs URI and header parsing to examine parameters within the message. By default, parameter parsing is disabled.

Specify White List Rule Sets

Enter Superuser mode.

At the top level ACLI prompt, type start learn-allowed-elements method msg-type params and press Enter.
The system displays the following message:
```
Learning mode for allowed-elements-profile started.
```
Note:
If you try to start a white list learning operation while another learning operation is already running, the following message displays:
```
Learning mode restarted without saving
Learning mode for allowed-elements-profile started.
```

Start White List Learning

Enter Superuser mode.

At the top level ACLI prompt, type start learn-allowed-elements, and press Enter.
The system displays the following message:
```
Learning mode for allowed-elements-profile started.
```

Stop White List Learning

Enter Superuser mode.

If you specify an identifier name that already exists as a profile, the ACLI returns an error message and prompts you to enter a different name.

At the top level ACLI prompt, type stop learn-allowed-elements <list name>, where <list name> is the allowed-elements-profile name, and press Enter.
The system displays the following message:
```
Learning mode for allowed-elements-profile stopped.
```

Configure White Lists for SIP Header and URI Parameter Management

You can configure white list profiles that tell the Oracle® Enterprise Session Border Controller (E-SBC) to accept only inbound SIP headers and URI parameters that are configured in this white list. Using the allowed-elements-profile parameter, you can configure the settings for this parameter using the ACLI interface at session-router, enforcement-profile. Because the enforcement-profile object also pertains to session agents, realms, and SIP interfaces, you can also apply the enforcement profiles you configure to these entities, as well. (Use the ACLI interface at session-router, session-agent, session-router, sip-interface, and media-manager, realm-config.)

The following configuration example assumes that your baseline configuration passes SIP traffic, with the E-SBC in the role of an Access SBC. Use this procedure to configure a white list for the session router and optionally apply the specific white lists to the session agent and SIP interface, as well as the media manager realm configuration.

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—Type a unique name for the white list you are creating. You can reference this name when configuring the enforcement-profiles for session-agent, SIP interface, and realm-config.
```
ORACLE(allowed-elements-profile)# name whitelist1
```
description—Type a description that explains the purpose of creating this white list. Valid values: Any alpha-numeric characters.
```
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 URI parameters.
```
ORACLE(allowed-elements-profile)# rule-sets
ORACLE(rule-sets)#
```
unmatched-action—Select the action for the E-SBC to perform when a header does not exist in an incoming message. Default: reject. Valid values:
- 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. (It does not apply to non-matching URI parameters.)
```
ORACLE(rule-sets)# unmatched action delete
```
msg-type—Specify the type of messages to which the E-SBC applies this white list configuration. Default: any. Valid values:
- any—Applies to all incoming messages.
- request—Applies to incoming REQUEST messages, only.
- response—Applies to incoming RESPONSE messages, only.
```
ORACLE(rule-sets)# msg-type any
```
methods—Type the packet methods, separated by a comma, for which this white list is enforced. Packet methods include, INVITE, OPTIONS, ACK, BYE, and so on. If this field is left blank, the white list applies to all packet methods. You can type 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 the matched.log file, when the message contains an element not specified in the white list. Default: disabled. Valid values: enabled | disabled.
Navigate to allowed-header-rule—Configure multiple parameters as part of the white list to make up the header rule that the E-SBC allows from incoming messages. You can configure an unlimited number of header-rules, and they do not need 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—Type the name of the header in the white list that you want theE-SBC to allow from incoming messages. The text is not case sensitive 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. Default: *. The default value allows 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 E-SBC to perform when an incoming header’s parameters do not match the relevant allowed parameters specified for this header-name. Default: reject. Valid values:
- 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 to non-matching URI parameters).
```
ORACLE(allowed-header-rule)# unmatched-action delete
```
allow-header-param—Type the header parameter that the E-SBC 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 (+). Default: *, 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—Type the URI parameter that the E-SBC 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 (+). Default: *, 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—Type the URI user parameter that the E-SBC 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 (+). Default: *, 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—Type the URI header name that the E-SBC 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 (+). Default: *, 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.

The matched.log File

The matched.log file contains information about the timestamp, the received and sent E-SBC network-interface, the IP address and port from which an incoming message was received, and which peer IP address and 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.

The following example shows the log output of the matched.log file:

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

Rejected Messages Monitoring

White lists control whether or not the Oracle® Enterprise Session Border Controller (E-SBC) accepts unknown headers and URI parameters in incoming request and response traffic. When the E-SBC rejects messages according to the white list, the system logs the rejected messages a file called “matched.log,” if you set logging to enabled. You can open and view the log when you want to view the rejected messages.

In addition to sending rejected messages to the “matched.log” file, the system sends rejected messages through a burst counter that keeps track of the number of messages rejected. You can enter the show sipd command to display the number of rejected messages. The counter is titled Rejected Message.

Configuration Exception

In certain circumstances, the Oracle® Enterprise Session Border Controller (E-SBC) ignores specific parameters in incoming Request-URI messages 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 E-SBC ignores these parameters in the Request-URI. Instead, the E-SBC automatically adds header-rules for incoming “Via”, “From”, To”, “Call-ID”, and “CSeq” messages. These are explicit header rules that you cannot delete. Each header-rule in a Request-URI includes parameters populated with the value of *. If required, you 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 White List Configuration

After you configure and save a white list on the Oracle® Enterprise Session Border Controller (E-SBC), you can use the verify-config command at the top level prompt to verify the saved configuration: For example:

ORACLE# verify-config

The verify-config command checks for errors in the E-SBC configuration. White list configuration errors specifically related to the enforcement-profile object also display in the output of this command when applicable. The white list configuration errors display if any references to the allowed-element-profiles are improperly configured. If errors exist, the system displays the following message:

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