Guidelines for Header and Element Rules

Splitting and Joining Headers

To simplify header manipulation processes, the Oracle Enterprise Communications Broker provides a means of combining or breaking apart header strings that actually consist of multiple headers. An example application would be to separate headers that another SIP device joined together into a single string. This would allow header manipulation to work on each distinct header, after which the system could re-combine the headers, making the forwarded output consistent with the initial message.

Some SIP devices combine multiple headers into a single header, with each distinct header separated by a comma. This is not precluded by RFC 3261. The user can configure a header manipulation to separate these headers prior to performing the manipulation using the split-headers command. The user can also configure the system to join headers together after a manipulation is complete using the join-headers command. Split and join functions do not have to co-exist within a single header manipulation.

Precedence

The Oracle Enterprise Communications Broker applies SIP header rules in the order you have entered them. This guards against the Oracle Enterprise Communications Broker removing data that might be used in the other header rules.

This ordering also provides you with ways to use manipulations strategically. For example, you might want to use two rules if you want to store the values of a regular expression. The first rule would store the value of a matched regular expression, and the second could delete the matched value.

In addition to taking note of the order in which header rules are configured, you now must also configure a given header rule prior to referencing it. For example, you must create Rule1 with the action store for the Contact header BEFORE you can create Rule2 which uses the stored value from the Contact header.

Duplicate Header Names

If more than one header exists for a configured header-name, the OECB stores each value in an array whose index starts at 0. To reference those values, use the syntax $<header-name>[<index>].

Add a trailing [<index>] value after the header-name parameter to represent the specific instance of the header on which to operate. Additional stored header values are indexed in the order in which they appear within the SIP message, and there is no limit to the index. The OECB takes no action if the header does not exist.

Use index 0 to reference the first header. In addition to numerical values, possible index values are:

* The OECB references all headers.
^ The OECB references the last stored header in the header rule.

Note that the header instance functionality has no impact on HMR’s add action, and you cannot use this feature to insert headers into a specific location. Headers are added to the end of the list, except that Via headers are added to the top.

Performing HMR on a Specific Header

HMR has been enhanced so that you can now operate on a specific instance of a given header. The syntax you use to accomplish this is similar to that you used to refer to a specific header rule stored value instance.

Using the header-name parameter, you can now add a trailing [<index>] value after the header name. This [<index>] is a numerical value representing the specific instance of the header on which to operate. However, the Oracle Enterprise Communications Broker takes no action if the header does not exist. You can also use the caret (^) to reference the last header of that type (if there are multiple instances)

The count for referencing is zero-based, meaning that the first instance of the header counts as 0.

Note that the header instance functionality has no impact on HMR’s add action, and you cannot use this feature to insert headers into a specific location. Headers are added to the end of the list, except that Via headers are added to the top.

Multiple SIP HMR Sets

In general you use SIP HMR by configuring rules and then applying those rules to session agents, realms, or SIP interfaces in the inbound or outbound direction. In addition, the Oracle Enterprise Communications Broker has a set method for how certain manipulation rules take precedence over others. For instance, inbound SIP manipulation rules defined in a session agent take precedence over any configured for a realm, and the rules for a realm take precedence over SIP interface manipulation rules.

The multiple SIP HMR feature gives you the ability to:

Apply multiple inbound and outbound manipulations rules to a SIP message
Provision the order in which the Oracle Enterprise Communications Broker applies manipulation rules

The action parameter in the header rules configuration now takes the value sip-manip. When you set the parameter to sip-manip, you then configure the new-value parameter with the name of a SIP manipulation rule that you want to invoke. The values for the match-value, comparison-type, and methods parameters for invoked rule are all supported. This means that the manipulation defined by the rules identified in the new-value parameter are carried out when the values for the match-value, comparison-type, and methods parameters are true.

The relationship between manipulation rules and manipulation rule sets is created once you load your configuration, meaning that the order in which you enter them does not matter. It also means that the Oracle Enterprise Communications Broker cannot dynamically perform validation as you enter rules, so you should use the ACLI verify-config command to confirm your manipulation rules contain neither invalid nor circular references. Invalid references are those that point to SIP manipulation rules that do not exist, and circular references are those that create endless loops of manipulation rules being carried out over and over. If you load a configuration exhibiting either of these issues, the Oracle Enterprise Communications Broker forces the action value for the rule to none and the rule will not be used.

MIME Support

Using the SIP HMR feature set, you can manipulate MIME types in SIP message bodies. While you can manipulate the body of SIP messages or a specific content type using other iterations of SIP HMR, this version gives you the power to change the MIME attachment of a specific type within the body by using regular expressions. To achieve this, you use the find-replace-all action type, which enables the search for a particular string and the replacement of all matches for that type. Although you use find-replace-all to manipulate MIME attachments, it can also be used to achieve other goals in SIP HMR.

Note that using find-replace-all might consume more system resources than other HMR types. Therefore this powerful action type should only be used when another type cannot perform the type of manipulation you require.

Manipulating MIME Attachments

Set the action type to find-replace-all to modify MIME attachments.

To manipulate a particular portion of the MIME attachment, for example when removing a certain attribute within the Content-Type of application/sdp, the OECB needs to search the content multiple times because:

SDP can have more than one media line
The SIP message body can contain more than one application/sdp.

When the action type is find-replace-all, the OECB treats the match-value as a regular expression and binds the comparison-type to pattern-rule, even if comparison-type is set to some other value. This type of action is both a comparison and action: for each regular expression match within the supplied string, the OECB substitutes the new value for that match.

Use subgroups to replace portions of the regular expression rather than the entire matched expression. The subgroup replacement syntax is formed by adding the string [[:n:]] to the end of the regular expression—where n is a number between 0 and 9. For example, setting the following parameters

        action                      find-replace-all
        match-value                 sip:(user)@host[[:1:]]
        new-value                   bob

creates a new rule to replace only the user portion of the URI that searches for the regular expression and replaces all instances of the user subgroup with the value bob.

Setting the following parameters

        action                      find-replace-all
        match-value                 0
        new-value                   1

creates a new rule to recursively replace all the 0 digits in a telephone number with 1. With this rule the user portion of a URI—or for any other string—with a value 1-781-308-4400 would be replaced as 1-781-318-4411.

If you leave the new-value parameter blank for find-replace-all, the OECB replaces the matched sub-group with an empty string—an equivalent of deleting the sub-group match. You can also replace empty sub-groups, which is like inserting a value within the second sub-group match. For example, user()@host.com[[:1:]] with a configured new-value _bob yields user_bob@host.com.

Setting find-replace-all disables the following parameter-type values: uri-param-name, uri-header-name, and header-param-name. These values are unusable because the OECB only uses case-sensitive matches for the match-value to find the parameter name within the URI. Since it can only be found by exact match, the OECB does not support finding and replacing that parameter.

Escaped Characters

SIP HMR’s support for escaped characters allows for searches for values you would be unable to enter yourself. Because they are necessary to MIME manipulation, support for escaped characters now includes:

\f
\n
\r
\t
\v

New Reserved Word

To allow you to search for carriage returns an new lines, the SIP HMR MIME feature also adds support for the reserved word $CRLF. Because you can search for these value and replace them, you also must be able to add them back in when necessary. Configuring $CRLF in the new-value parameter always resolves to /r/n, which you normally cannot otherwise enter through the ACLI.

About the MIME Value Type

To modify the MIME attachment, SIP HMR supports a mime value for the type parameter in the element rules configuration. Like the status-code and reason-phrase values, you can only use the mime type value against the Content-Type header.

When you set the element rule type to mime, you must also configure the parameter-name with a value. This step is a requirement because it sets the content-type the Oracle Enterprise Communications Broker (OECB) manipulates in a specific part of the MIME attachment. You cannot leave this parameter blank because the OECB does not let you save the configuration if you do. When you use the store action on a multi-part MIME attachment that has different attachment types, the OECB stores the final instance of the content-type because it does not support storing multiple instances of element rule stored values.

If you do not know the specific content-type where the OECB will find the match-value, you can use a wildcard in the parameter-name by setting with the asterisk (*) as a value. You cannot, set partial content-types (for example, application/*). So configured, the OECB loops through the MIME attachment’s content types.

You can set the additional action types listed in the following table with the described result:

Action Type	Description
delete-element	Removes the matched mime-type from the body. If this is the last mime-type within in message body, the Oracle Enterprise Communications Broker removes the Content-Type header.
delete-header	Removes all body content and removes the Content-Type header.
replace	Performs a complete replacement of the matched mime-type with the new-value you configure.
find-replace-all	Searches the specifies mime-type’s contents and replaces all matching regular expressions with the new-value you configure
store	Stores the final instance of the content-type (if there are multi-part MIME attachments of various attachment types)
add	Not supported

MIME manipulation does not support manipulating headers in the individual MIME attachments. For example, the OECB cannot modify the Content-Type given a portion of a message body such as the following one:

--boundary-1
Content-Type: application/sdp
v=0
o=use1 53655765 2353687637 IN IP4 192.168.1.60
s=-
c=IN IP4 192.168.1.60
t=0 0
m=audio 10000 RTP/AVP 8
a=rtpmap:8 PCMA/8000/1
a=sendrecv
a=ptime:20
a=maxptime:200

Back Reference Syntax

You can use back reference syntax in the new-value parameter for header and element rules configurations. Denoted by the use of $1, $2, $3, etc. (where the number refers to the regular expression’s stored value), you can reference the header and header rule’s stored value without having to use the header rule’s name. It instead refers to the stored value of this rule.

For example, when these settings are in place:

header-rule=changeHeader
action=manipulate
match-value=(.+)([^;])

you can set the new-value as sip:$2 instead of sip:$changeHeader.$2.

You can use the back reference syntax for:

Header rule actions manipulate and find-replace-all
Element rule actions replace and find-replace-all

Using back reference syntax simplifies your configuration steps because you do not need to create a store rule and then manipulate rule; the manipulate rule itself performs the store action if the comparison-type is set to pattern-rule.

Notes on the Regular Expression Library

In the regular expression library, the dot (.) character does not match new lines or carriage returns. Conversely, the not-dot does match new lines and carriage returns. This provides a safety mechanism preventing egregious backtracking of the entire SIP message body when there are no matches. Thus, the Oracle Enterprise Communications Broker (OECB)reduces backtracking to a single line within the body. The OECB also supports:

Syntax	Description
\s	Whitespace
\S	Non-whitespace
\d	Digits
\D	Non-digits
\R	Any \r, \n, \r\n
\w	Word
\W	Non-word
\A	Beginning of buffer
\Z	End of buffer
\	Any character including newline, in the event that the dot (.) is not

In addition, you can also use:

Escaped character shortcuts (\w\W\S\s\d\D\R) operating inside brackets [...]

SIP Message-Body Separator Normalization

The Oracle Enterprise Communications Broker supports SIP with Multipurpose Internet Mail Extension (MIME) attachments — up to a maximum payload size of 64KB — and has the ability to allow more than the required two CRLFs between the SIP message headers and the multipart body’s first boundary. The first two CRLFs that appear in all SIP messages signify the end of the SIP header and the separation of the header and body of the message, respectively. Sometimes additional extraneous CRLFs can appear within the preamble before any text.

The Oracle Enterprise Communications Broker works by forwarding received SIP messages regardless of whether they contain two or more CRLFs. Although three or more CRLFs are legal, some SIP devices do not accept more than two.

The solution to ensuring all SIP devices accept messages sent from the Oracle Enterprise Communications Broker is to strip all CRLFs located at the beginning of the preamble before the appearance of any text, ensuring that there are no more than two CRLFs between the end of the last header and the beginning of the body within a SIP message. You enable this feature by adding the new stripPreambleCrlf option to the global SIP configuration.

To enable the stripping of CRLFs in the preamble, add the +stripPreambleCrlf option to SIP Options.

SIP Header Pre-Processing HMR

By default, the Oracle Enterprise Communications Broker performs in-bound SIP manipulations after it carries out header validation. Adding the inmanip-before-validate option in the global SIP configuration allows the Oracle Enterprise Communications Broker to perform HMR on received requests prior to header validation. Because there are occaisional issues with other SIP implementations—causing invalid headers to be used in messages they send to the Oracle Enterprise Communications Broker—it can be beneficial to use HMR to remove or repair these faulty headers before the request bearing them are rejected.

When configured to do so, the Oracle Enterprise Communications Broker performs pre-validation header manipulation immediately after it executes the top via check. Inbound SIP manipulations are performed in order of increasing precedence: SIP interface, realm, and session agent.

The fact that the top via check happens right before the Oracle Enterprise Communications Broker carries out pre-validation header manipulations means that you cannot use this capability to repairs the first via header if it is indeed invalid. If pre-validation header manipulation were to take place at another time during processing, it would not be possible to use it for SIP session agents. The system learns of matching session agents after top via checking completes.

For logistical reasons, this capability does not extend to SIP responses. Inbound manipulation for responses cannot be performed any sooner that it does by default, a time already preceding any header validation.

To enable SIP header pre-processing, add the +inmanip-before-validate option to SIP Options.

Best Practices

The following list describes practices that Oracle recommends you follow for successful implementation of Header Manipulation Rules.

Define all storage rules first.
This recommendation is made because each subsequent header rule processes against the same SIP message, so each additional header rules works off of the results from the application of the rule that precedes it.

In general, you want to store values from the original SIP header rather than from the iteratively changed versions.
Implement rules at the element rule rather than the header rule level.
Header rules should only be a container for element rules.
When you are creating rules to edit a header, add additional element rules to modify a single header rather than try to create multiple header rules each with one element rule. That is, create multiple element rules within a header rule rather than creating multiple header rules.
Do not use header or element rule names that are all capital letters (for example, $IP_ADDRESS). Capital letters refer to predefined rules that are used as macros, and they might conflict with a name that uses capital letters.

About Regular Expressions

Two of the most fundamental ideas you need to know to work with regular expressions and with Header Manipulation Rules include:

Regular expressions are a way of creating strings to match other string values.
You can use groupings to create stored values on which you can then operate.

To learn more about regex, you can visit the following Web site, which has information and tutorials that can help to get you started:http://www.regular-expressions.info/.

Many of the characters you can type on your keyboard are literal, ordinary characters, which present their actual value in the pattern. Some characters have special meaning, and they instruct the regex function (or engine which interprets the expressions) to treat the characters in designated ways. The following table outlines these “special characters” or metacharacters.

Character	Name	Description
.	dot	Matches any one character, including a space; it will match one character, but there must be one character to match. Literally a . (dot) when bracketed ([]), or placed next to a \ (backslash).
*	star/asterisk	Matches one or more preceding character (0, 1, or any number), bracketed carrier class, or group in parentheses. Used for quantification. Typically used with a . (dot) in the format .* to indicate that a match for any character, 0 or more times. Literally an * (asterisk) when bracketed ([]).
+	plus	Matches one or more of the preceding character, bracketed carrier class, or group in parentheses. Used for quantification. Literally a + (plus sign) when bracketed ([]).
\|	bar/vertical bar/pipe	Matches anything to the left or to the right; the bar separates the alternatives. Both sides are not always tried; if the left does not match, only then is the right attempted. Used for alternation.
{	left brace	Begins an interval range, ended with } (right brace) to match; identifies how many times the previous singles character or group in parentheses must repeat. Interval ranges are entered as minimum and maximums ({minimum,maximum}) where the character/group must appear a minimum of times up to the maximum. You can also use these character to set magnitude, or exactly the number of times a character must appear; you can set this, for example, as the minimum value without the maximum ({minimum,}).
?	question mark	Signifies that the preceding character or group in parentheses is optional; the character or group can appear not at all or one time.
^	caret	Acts as an anchor to represent the beginning of a string.
$	dollar sign	Acts as an anchor to represent the end of a string.
[	left bracket	Acts as the start of a bracketed character class, ended with the ] (right bracket). A character class is a list of character options; one and only on of the characters in the bracketed class must appear for a match. A - (dash) in between two character enclosed by brackets designates a range; for example [a-z] is the character range of the lower case twenty-six letters of the alphabet. Note that the ] (right bracket) ends a bracketed character class unless it sits directly next to the [ (left bracket) or the ^ (caret); in those two cases, it is the literal character.
(	left parenthesis	Creates a grouping when used with the ) (right parenthesis). Groupings have two functions: They separate pattern strings so that a whole string can have special characters within it as if it were a single character. They allow the designated pattern to be stored and referenced later (so that other operations can be performed on it).

Expression Building Using Parentheses

You can now use parentheses ( () )when you use HMR to support order of operations and to simplify header manipulation rules that might otherwise prove complex. This means that expressions such as (sip + urp) - (u + rp) can now be evaluated to sip. Previously, the same expression would have evaluated to sipurprp. In addition, you previously would have been required to create several different manipulation rules to perform the same expression.