1. Configuration Guide
  2. STIR/SHAKEN Client
  3. Mapping SIP to HTTP Headers

Mapping SIP to HTTP Headers

You can configure the SBC with static mapping to and from SIP INVITEs and HTTP requests or responses. This mapping provides a means of conveying SIP header information within HTTP headers and vice-versa. The HTTP exchanges can be during authentication or verification procedures. This feature adds headers and their new parameters in the rules' targets, or modifies existing headers with the new parameters presented by the rule. This feature applies to both ATIS and 3GPP modes.

You configure this feature using the sti-header-mapping-ruleset in the session-router. From this parameter, you create multi-instance sub-elements that contain your SIP/HTTP mapping rules. The ruleset element includes a name parameter that you use when you apply a sti-header-mapping-ruleset-name on a sti-server or the sti-config. The ruleset element also provides access to rule configuration sub-elements using the mapping-rules parameter. The ruleset assigned to a sti-server takes precedence over the sti-config configuration.

When using these rulesets, the SBC performs functions including:

  • Selecting the configured source-header
  • Adding or modifying the configured target-header with that value

For each SIP call that invokes STIR/SHAKEN authentication or verification, the SBC first checks the applicable sti-server for a configured sti-header-mapping-ruleset-name. If found, the SBC uses the corresponding ruleset to get the mapping details. If it is not found, the SBC checks for an applicable configuration in the sti-config for the same purpose.

You configure a ruleset by specifying:
  • the ruleset identifier
  • the headers the system uses as the source for the mapping
  • the headers the system uses as the target for the mapping
  • the role, STI-AS or STI-VS, within which the ruleset operates
  • the direction of the mapping, based on the perspective of the SBC

For call flows that include a single HTTP request and response, the SBC behaviors are the same for both ATIS and 3GPP modes. In 3GPP mode when there are both SHAKEN and DIV signing request/responses, the SBC:

  • Adds the mapping target header(s) to both the SHAKEN and DIV signing request towards the STI-AS.
  • Uses the following behaviors when receiving responses for both SHAKEN and DIV signing requests:
    • If it receives multiple responses, the SBC processes and saves the first response. When it receives the second, the SBC processes this second response but does not save it. This results in any final processing using the first response.
    • If the same header for which mapping is set is present in both responses, the SBC have either value from the response that will be processed later that overwrites value from the response that was processed first, or headers that will get duplicated (if [^] or [~] is used in the mapping-rule).

Selecting a Header

To perform this function, the SBC selects your configured source-header from a SIP INVITE or from an HTTP response received from the STI server, depending upon your direction configuration. After getting the value of this header, the SBC inserts this value into the target-header of the HTTP request or the egress SIP INVITE.

  • If a mapping rule has a source-header configured with a SIP header and the direction of the mapping set to outbound, the SBC retrieves the SIP header values from the ingress INVITE.
  • If a mapping rule has a source-header configured with an HTTP header and the direction of the mapping set to inbound, the SBC retrieves the HTTP header value from the HTTP response sent by the STI-AS or STI-VS server, depending on your role configuration.

Rules for selecting a header include:

  • The SBC retrieves a SIP or HTTP header value based on the digit in the subscript, if present, after the header name in your configuration. If you have not configured a subscript, the SBC uses the first header.

    Note:

    This is equivalent to writing the header name with a 0 in the subscript. For example, Attestation-Info[0].
  • The SBC only selects a header if the number of the header in the ingress INVITE that matches source-header the configuration is greater than 0 and is greater than the digit present in the subscript.

Adding/Modifying a Header

This feature allows you to add or modify the target header. When performing the function when the target-header is a SIP header and the direction is inbound, the SBC:

  • Adds a new header when the target header count, meaning either the HTTP header in the POST request or the SIP header in the outgoing INVITE, is the same as the digit in the subscript of the header name in your configuration.
  • Modifies the header referenced by the subscript when the digit in the header name subscript is less than the number of headers in the HTTP request or SIP INVITE.
  • Does not perform the mapping when the subscript is greater than the number of headers.
  • When your configuration includes the ^ symbols, adds the header at the first position.
  • When your configuration includes the ~ symbols, adds the header at the last position.

When performing the function when the target-header is an HTTP header and the direction is outbound, the SBC:

The SBC does not support indexing HTTP headers. Instead, the SBC appends existing HTTP headers, such as when the SBC creates the header using multiple rules, with the new header after a comma.

Configuration

You configure this feature by creating a sti-header-mapping-ruleset within the session-router element and applying your ruleset name to the sti-header-mapping-ruleset-name parameter within the sti-config or a sti-server element.

Parameters for sti-header-mapping-ruleset include:

  • name—Unique identifier for the ruleset
  • mapping-rules—Enters the mapping rules sub-element, from which you define the details or each rule.

Parameters for mapping-rules include:

  • id—Unique identifier for the rule, allowing the execution of multiple rules from a single mapping-rules element.
  • source-header—Name of the source header. This could be a SIP header or an HTTP header.
  • target-header—Name of the target header. This could be a SIP header or an HTTP header.
  • direction—The direction of the translation. Values include:
    • outbound— Map headers from the SBC to an external STI server (SIP to HTTP).
    • inbound—Map headers received from an external STI server to the SBC (HTTP to SIP).
  • role—The type of operation the system is performing, including STI-AS or STI-VS

You can configure SIP source-header and target-header parameters with the header names using the same syntax you use within HMR configurations. This formatting does not apply to HTTP headers. These header names support alphanumeric characters, which specify the header name, as well as the following special characters, which can be used in the custom header name:

  • . (period)
  • ! (exclamation point)
  • % (percent sign)
  • * (star)
  • _ (underscore)
  • + (plus sign)
  • `(closed quote)
  • ' (apostrophe)
  • ~ (tilde)
  • - (dash)
  • @ (ampersand)

Note the example configuration using formatting:

ORACLE(mapping-rules)#target-header P-Origination-Id[0]

Header names can end with or without a subscript operator, enclosed in brackets, []. Subscript operators include a digit, a caret or a tilde. These operators indicate the sequence number of the header in the incoming or outgoing SIP INVITE, or in the HTTP request or response. Operators include:

  • [^] — Last occurrence
  • [~] — first occurrence
  • [0] — first
  • [1] — second
  • [2] — third

If a subscript operator is not provided, it means that the subscript is 0, referring to the first occurrence of the header.

Note the example configuration using subscripts:

ORACLE(mapping-rules)#target-header P-Origination-Id[0]

The SBC provides syntax validation after you run the done command. When your source or target header values violate syntax, the SBC throws the following error message. 

Value must be alphanumeric and can contain the following special characters @.!%*_+`'~-. 
It can optionally  be followed by a digit, ~ or ^ enclosed in a subscript operator '[]'

A more specific syntax error includes the following, explaining that an outbound rule is unable to apply a target header that uses subscripts.

% Cannot save configuration object 
When the direction is set as outbound, the target header can't contain the subscript [] operator

Note also that an inbound rule is unable to apply a source header that uses subscripts.

Header Mapping Statistics

The SBC provides a command to show statistics on traffic for which is has performed header modification. To see these statistics, run the show stir header-mapping.