routing and adaptation enhancements in avaya aura session

Routing and Adaptation Enhancements in Avaya Aura® Session Manager 8.0.1

Release 8.0.1 Issue 1

August 2019

2

Aug 2019 Routing and Adaptation Enhancements in Avaya Aura® Session Manager

© 2018 – 2019, Avaya Inc.

All Rights Reserved.

Notice

While reasonable efforts have been made to ensure that the information in this document is complete and accurate at the time of printing, Avaya assumes no liability for any errors. Avaya reserves the right to make changes and corrections to the information in this document without the obligation to notify any person or organization of such changes.

Documentation disclaimer

“Documentation” means information published in varying mediums which may include product information, operating instructions and performance specifications that are generally made available to users of products. Documentation does not include marketing materials. Avaya shall not be responsible for any modifications, additions, or deletions to the original published version of Documentation unless such modifications, additions, or deletions were performed by or on the express behalf of Avaya. End User agrees to indemnify and hold harmless Avaya, Avaya's agents, servants and employees against all claims, lawsuits, demands and judgments arising out of, or in connection with, subsequent modifications, additions or deletions to this documentation, to the extent made by End User.

Link disclaimer

Avaya is not responsible for the contents or reliability of any linked websites referenced within this site or Documentation provided by Avaya. Avaya is not responsible for the accuracy of any information, statement or content provided on these sites and does not necessarily endorse the products, services, or information described or offered within them. Avaya does not guarantee that these links will work all the time and has no control over the availability of the linked pages.

Warranty

Avaya provides a limited warranty on Avaya hardware and software. Refer to your sales agreement to establish the terms of the limited warranty. In addition, Avaya’s standard warranty language, as well as information regarding support for this product while under warranty is

available to Avaya customers and other parties through the Avaya Support website: http://support.avaya.com/helpcenter/getGenericDetails?detailId=C20091120112456651010 under the link “Warranty & Product Lifecycle” or such successor site as designated by Avaya. Please note that if You acquired the product(s) from an authorized Avaya Channel Partner outside of the United States and Canada, the warranty is provided to You by said Avaya Channel Partner and not by Avaya.

“Hosted Service” means an Avaya hosted service subscription that You acquire from either Avaya or an authorized Avaya Channel Partner (as applicable) and which is described further in Hosted SAS or other service description documentation regarding the applicable hosted service. If You purchase a Hosted Service subscription, the foregoing limited warranty may not apply but You may be entitled to support services in connection with the Hosted Service as described further in your service description documents for the applicable Hosted Service. Contact Avaya or Avaya Channel Partner (as applicable) for more information.

Hosted Service

THE FOLLOWING APPLIES ONLY IF YOU PURCHASE AN AVAYA HOSTED SERVICE SUBSCRIPTION FROM AVAYA OR AN AVAYA CHANNEL PARTNER (AS APPLICABLE), THE TERMS OF USE FOR HOSTED SERVICES ARE AVAILABLE ON THE AVAYA WEBSITE, HTTP://SUPPORT.AVAYA.COM/LICENSEINFO UNDER THE LINK “Avaya Terms of Use for Hosted Services” OR SUCH SUCCESSOR SITE AS DESIGNATED BY AVAYA, AND ARE APPLICABLE TO ANYONE WHO ACCESSES OR USES THE HOSTED SERVICE. BY ACCESSING OR USING THE HOSTED SERVICE, OR AUTHORIZING OTHERS TO DO SO, YOU, ON BEHALF OF YOURSELF AND THE ENTITY FOR WHOM YOU ARE DOING SO (HEREINAFTER REFERRED TO INTERCHANGEABLY AS “YOU” AND “END USER”), AGREE TO THE TERMS OF USE. IF YOU ARE ACCEPTING THE TERMS OF USE ON BEHALF A COMPANY OR OTHER LEGAL ENTITY, YOU REPRESENT THAT YOU HAVE THE AUTHORITY TO BIND SUCH ENTITY TO THESE TERMS OF USE. IF YOU DO NOT HAVE SUCH AUTHORITY, OR IF YOU DO NOT WISH TO ACCEPT THESE TERMS OF

http://support.avaya.com/helpcenter/getGenericDetails?detailId=C20091120112456651010

http://support.avaya.com/helpcenter/getGenericDetails?detailId=C20091120112456651010

http://support.avaya.com/LicenseInfo

3


USE, YOU MUST NOT ACCESS OR USE THE HOSTED SERVICE OR AUTHORIZE ANYONE TO ACCESS OR USE THE HOSTED SERVICE.

Licenses THE SOFTWARE LICENSE TERMS AVAILABLE ON THE AVAYA WEBSITE, HTTP://SUPPORT.AVAYA.COM/LICENSEINFO, UNDER THE LINK “AVAYA SOFTWARE LICENSE TERMS (Avaya Products)” OR SUCH SUCCESSOR SITE AS DESIGNATED BY AVAYA, ARE APPLICABLE TO ANYONE WHO DOWNLOADS, USES AND/OR INSTALLS AVAYA SOFTWARE, PURCHASED FROM AVAYA INC., ANY AVAYA AFFILIATE, OR AN AVAYA CHANNEL PARTNER (AS APPLICABLE) UNDER A COMMERCIAL AGREEMENT WITH AVAYA OR AN AVAYA CHANNEL PARTNER. UNLESS OTHERWISE AGREED TO BY AVAYA IN WRITING, AVAYA DOES NOT EXTEND THIS LICENSE IF THE SOFTWARE WAS OBTAINED FROM ANYONE OTHER THAN AVAYA, AN AVAYA AFFILIATE OR AN AVAYA CHANNEL PARTNER; AVAYA RESERVES THE RIGHT TO TAKE LEGAL ACTION AGAINST YOU AND ANYONE ELSE USING OR SELLING THE SOFTWARE WITHOUT A LICENSE. BY INSTALLING, DOWNLOADING OR USING THE SOFTWARE, OR AUTHORIZING OTHERS TO DO SO, YOU, ON BEHALF OF YOURSELF AND THE ENTITY FOR WHOM YOU ARE INSTALLING, DOWNLOADING OR USING THE SOFTWARE (HEREINAFTER REFERRED TO INTERCHANGEABLY AS “YOU” AND “END USER”), AGREE TO THESE TERMS AND CONDITIONS AND CREATE A BINDING CONTRACT BETWEEN YOU AND AVAYA INC. OR THE APPLICABLE AVAYA AFFILIATE (“AVAYA”).

Avaya grants You a license within the scope of the license types described below, with the exception of Heritage Nortel Software, for which the scope of the license is detailed below. Where the order documentation does not expressly identify a license type, the applicable license will be a Designated System License as set forth below in Section M(i)1 or 2 as applicable. The applicable number of licenses and units of capacity for which the license is granted will be one (1), unless a different number of licenses or units of capacity is specified in the documentation or other materials available to You. “Software” means computer

programs in object code, provided by Avaya or an Avaya Channel Partner, whether as stand-alone products, pre-installed on hardware products, and any upgrades, updates, patches, bug fixes, or modified versions thereto. “Designated Processor” means a single stand-alone computing device. “Server” means a set of Designated Processors that hosts (physically or virtually) a software application to be accessed by multiple users. “Instance” means a single copy of the Software executing at a particular time: (i) on one physical machine; or (ii) on one deployed software virtual machine (“VM”) or similar deployment.

License types

Designated System(s) License (DS). End

User may install and use each copy or an

Instance of the Software only: 1) on a

number of Designated Processors up to the

number indicated in the order; or 2) up to the

number of Instances of the Software as

indicated in the order, Documentation, or as

authorized by Avaya in writing. Avaya may

require the Designated Processor(s) to be

identified in the order by type, serial number,

feature key, Instance, location or other

specific designation, or to be provided by

End User to Avaya through electronic

means established by Avaya specifically for

this purpose.

Named User License (NU). You may: (i)

install and use each copy or Instance of the

Software on a single Designated Processor

or Server per authorized Named User

(defined below); or (ii) install and use each

copy or Instance of the Software on a Server

so long as only authorized Named Users

access and use the Software. “Named

User,” means a user or device that has been

expressly authorized by Avaya to access

and use the Software. At Avaya’s sole

discretion, a “Named User” may be, without

limitation, designated by name, corporate

function (e.g., webmaster or helpdesk), an

e-mail or voice mail account in the name of

a person or corporate function, or a directory

entry in the administrative database utilized

http://support.avaya.com/LICENSEINFO

http://support.avaya.com/LICENSEINFO

4


by the Software that permits one user to

interface with the Software.

Shrinkwrap License (SR). You may install

and use the Software in accordance with the

terms and conditions of the applicable

license agreements, such as “shrinkwrap” or

“clickthrough” license accompanying or

applicable to the Software (“Shrinkwrap

License”). Heritage Nortel Software “Heritage Nortel Software” means the software that was acquired by Avaya as part of its purchase of the Nortel Enterprise Solutions Business in December 2009. The Heritage Nortel Software is the software contained within the list of Heritage Nortel Products located at http://support.avaya.com/LicenseInfo/ under the link “Heritage Nortel Products,” or such successor site as designated by Avaya. For Heritage Nortel Software, Avaya grants Customer a license to use Heritage Nortel Software provided hereunder solely to the extent of the authorized activation or authorized usage level, solely for the purpose specified in the Documentation, and solely as embedded in, for execution on, or for communication with Avaya equipment. Charges for Heritage Nortel Software may be based on extent of activation or use authorized as specified in an order or invoice.

Copyright

Except where expressly stated otherwise, no use should be made of materials on this site, the Documentation, Software, Hosted Service, or hardware provided by Avaya. All content on this site, the documentation, Hosted Service, and the product provided by Avaya including the selection, arrangement and design of the content is owned either by Avaya or its licensors and is protected by copyright and other intellectual property laws including the sui generis rights relating to the protection of databases. You may not modify, copy, reproduce, republish, upload, post, transmit or distribute in any way any content, in whole or in part, including any code and software unless expressly authorized by Avaya. Unauthorized reproduction, transmission, dissemination,

storage, and or use without the express written consent of Avaya can be a criminal, as well as a civil offense under the applicable law.

Virtualization

The following applies if the product is deployed on a virtual machine. Each product has its own ordering code and license types. Unless otherwise stated, each Instance of a product must be separately licensed and ordered. For example, if the end user customer or Avaya Channel Partner would like to install two Instances of the same type of products, then two products of that type must be ordered.

Third Party Components

“Third Party Components” mean certain software programs or portions thereof included in the Software or Hosted Service may contain software (including open source software) distributed under third party agreements (“Third Party Components”), which contain terms regarding the rights to use certain portions of the Software (“Third Party Terms”). As required, information regarding distributed Linux OS source code (for those products that have distributed Linux OS source code) and identifying the copyright holders of the Third Party Components and the Third Party Terms that apply is available in the products, Documentation or on Avaya’s website at: http://support.avaya.com/Copyright or such successor site as designated by Avaya. The open source software license terms provided as Third Party Terms are consistent with the license rights granted in these Software License Terms, and may contain additional rights benefiting You, such as modification and distribution of the open source software. The Third Party Terms shall take precedence over these Software License Terms, solely with respect to the applicable Third Party Components, to the extent that these Software License Terms impose greater restrictions on You than the applicable Third Party Terms.

The following applies only if the H.264 (AVC) codec is distributed with the product. THIS PRODUCT IS LICENSED UNDER THE AVC PATENT PORTFOLIO LICENSE FOR THE PERSONAL USE OF A CONSUMER OR OTHER USES IN WHICH IT DOES NOT RECEIVE REMUNERATION TO (i) ENCODE VIDEO IN COMPLIANCE WITH THE AVC

5


STANDARD ("AVC VIDEO") AND/OR (ii) DECODE AVC VIDEO THAT WAS ENCODED BY A CONSUMER ENGAGED IN A PERSONAL ACTIVITY AND/OR WAS OBTAINED FROM A VIDEO PROVIDER LICENSED TO PROVIDE AVC VIDEO. NO LICENSE IS GRANTED OR SHALL BE IMPLIED FOR ANY OTHER USE. ADDITIONAL INFORMATION MAY BE OBTAINED FROM MPEG LA, L.L.C. SEE HTTP://WWW.MPEGLA.COM

Service Provider

THE FOLLOWING APPLIES TO AVAYA CHANNEL PARTNER’S HOSTING OF AVAYA PRODUCTS OR SERVICES. THE PRODUCT OR HOSTED SERVICE MAY USE THIRD PARTY COMPONENTS SUBJECT TO THIRD PARTY TERMS AND REQUIRE A SERVICE PROVIDER TO BE INDEPENDENTLY LICENSED DIRECTLY FROM THE THIRD PARTY SUPPLIER. AN AVAYA CHANNEL PARTNER’S HOSTING OF AVAYA PRODUCTS MUST BE AUTHORIZED IN WRITING BY AVAYA AND IF THOSE HOSTED PRODUCTS USE OR EMBED CERTAIN THIRD PARTY SOFTWARE, INCLUDING BUT NOT LIMITED TO MICROSOFT SOFTWARE OR CODECS, THE AVAYA CHANNEL PARTNER IS REQUIRED TO INDEPENDENTLY OBTAIN ANY APPLICABLE LICENSE AGREEMENTS, AT THE AVAYA CHANNEL PARTNER’S EXPENSE, DIRECTLY FROM THE APPLICABLE THIRD PARTY SUPPLIER.

WITH RESPECT TO CODECS, IF THE AVAYA CHANNEL PARTNER IS HOSTING ANY PRODUCTS THAT USE OR EMBED THE H.264 CODEC OR H.265 CODEC, THE AVAYA CHANNEL PARTNER ACKNOWLEDGES AND AGREES THE AVAYA CHANNEL PARTNER IS RESPONSIBLE FOR ANY AND ALL RELATED FEES AND/OR ROYALTIES. THE H.264 (AVC) CODEC IS LICENSED UNDER THE AVC PATENT PORTFOLIO LICENSE FOR THE PERSONAL USE OF A CONSUMER OR OTHER USES IN WHICH IT DOES NOT RECEIVE REMUNERATION TO: (I) ENCODE VIDEO IN COMPLIANCE WITH THE AVC STANDARD ("AVC VIDEO") AND/OR (II) DECODE AVC VIDEO THAT WAS ENCODED BY A CONSUMER ENGAGED IN A PERSONAL ACTIVITY AND/OR WAS OBTAINED FROM A VIDEO PROVIDER

LICENSED TO PROVIDE AVC VIDEO. NO LICENSE IS GRANTED OR SHALL BE IMPLIED FOR ANY OTHER USE. ADDITIONAL INFORMATION FOR H.264 (AVC) AND H.265 (HEVC) CODECS MAY BE OBTAINED FROM MPEG LA, L.L.C. SEE HTTP://WWW.MPEGLA.COM.

Compliance with Laws

You acknowledge and agree that it is Your responsibility for complying with any applicable laws and regulations, including, but not limited to laws and regulations related to call recording, data privacy, intellectual property, trade secret, fraud, and music performance rights, in the country or territory where the Avaya product is used.

Preventing Toll Fraud

“Toll Fraud” is the unauthorized use of your telecommunications system by an unauthorized party (for example, a person who is not a corporate employee, agent, subcontractor, or is not working on your company's behalf). Be aware that there can be a risk of Toll Fraud associated with your system and that, if Toll Fraud occurs, it can result in substantial additional charges for your telecommunications services.

Avaya Toll Fraud intervention

If You suspect that You are being victimized by Toll Fraud and You need technical assistance or support, call Technical Service Center Toll Fraud Intervention Hotline at +1-800-643-2353 for the United States and Canada. For additional support telephone numbers, see the Avaya Support website: http://support.avaya.com, or such successor site as designated by Avaya.

Security Vulnerabilities

Information about Avaya’s security support policies can be found in the Security Policies and Support section of https://support.avaya.com/security

Suspected Avaya product security vulnerabilities are handled per the Avaya Product Security Support Flow (https://support.avaya.com/css/P8/documents/100161515).

http://www.mpegla.com/

http://www.mpegla.com/

https://support.avaya.com/

6


Downloading Documentation

For the most current versions of Documentation, see the Avaya Support website: http://support.avaya.com, or such successor site as designated by Avaya.

Contact Avaya Support

See the Avaya Support website: http://support.avaya.com for product or Hosted Service notices and articles, or to report a problem with your Avaya product or Hosted Service. For a list of support telephone numbers and contact addresses, go to the Avaya Support website: http://support.avaya.com (or such successor site as designated by Avaya), scroll to the bottom of the page, and select Contact Avaya Support.

Trademarks

The trademarks, logos and service marks (“Marks”) displayed in this site, the Documentation, Hosted Service(s), and product(s) provided by Avaya are the registered

or unregistered Marks of Avaya, its affiliates, its licensors, its suppliers, or other third parties. Users are not permitted to use such Marks without prior written consent from Avaya or such third party which may own the Mark. Nothing contained in this site, the Documentation, Hosted Service(s) and product(s) should be construed as granting, by implication, estoppel, or otherwise, any license or right in and to the Marks without the express written permission of Avaya or the applicable third party.

Avaya is a registered trademark of Avaya Inc.

All non-Avaya trademarks are the property of their respective owners.

Linux® is the registered trademark of Linus Torvalds in the U.S. and other countries.

http://support.avaya.com/

http://support.avaya.com/

7


Contents

1 Introduction ............................................................................................................ 10

2 Digit-Based Routing ............................................................................................... 11

3 Source-Based Routing ........................................................................................... 13

3.1 Origination Dial Pattern Set .............................................................................. 13

3.2 Modified: Dial Pattern Details ........................................................................... 14

3.3 Global Settings: Dial Patterns Precedence ...................................................... 15

3.4 Examples ......................................................................................................... 16

3.4.1 911 Routing ............................................................................................... 16

4 Regular-Expression Routing .................................................................................. 17

4.1 Existing: Request-URI Match ........................................................................... 17

4.2 New: Origination Location ................................................................................ 17

4.3 New: Condition ................................................................................................. 18

4.4 New: Precedence of Digit and Regular-Expression Routing ............................ 18

4.5 Performance Concerns .................................................................................... 19

5 Conditions .............................................................................................................. 20

5.1 Source Type, Source and Instance .................................................................. 21

5.2 Match Expression ............................................................................................. 22

5.3 Logical Operators (NOT, AND, OR) ................................................................. 22

5.4 Building a Condition Tree ................................................................................. 23

6 Regular-Expression Routing Examples .................................................................. 25

6.1 Denying a SIP Request .................................................................................... 25

6.2 Routing H.264 Video from Android Devices ..................................................... 26

8


7 Adaptation .............................................................................................................. 28

7.1 Existing: A Single Digit-Based Adapter ............................................................ 28

7.2 New: A Sequence of Digit-Based and Regular-Expression Adapters .............. 28

8 Regular-Expression Adaptation.............................................................................. 29

8.1 Regular-Expression Adaptation Rules ............................................................. 29

8.2 Regular-Expression Variables .......................................................................... 30

8.3 Regular-Expression Adaptation Actions ........................................................... 32

8.3.1 Add Actions ............................................................................................... 32

8.3.2 Delete Actions ........................................................................................... 33

8.3.3 Modify Actions ........................................................................................... 34

8.4 Performance Impact ......................................................................................... 37

9 Regular-Expression Adaptation Examples ............................................................. 38

9.1 Adding a Route Header .................................................................................... 38

9.2 Deleting the Last Record-Route Header .......................................................... 38

9.3 Modifying a Route Header Using Named and Numbered Variables ................ 39

9.4 Adapting a Response Code for Alternate Routing ............................................ 39

9.5 Replacing the P-Asserted-Identity Header with the Alternate-CLI header ........ 40

9.6 Modifying an INVITE request to Comply with STIR/SHAKEN Regulations ...... 42

10 Regular-Expression Adaptation Tips and Tricks .................................................. 47

10.1 Regular-Expression Basics ........................................................................... 47

10.2 Multiple-Instance Headers ............................................................................ 47

10.3 Using Embedded Flags in Regular Expressions ........................................... 47

10.4 Modifying Multiline Attachments ................................................................... 48

10.5 Matching SIP URIs ........................................................................................ 49

9


10.6 Matching IP Addresses ................................................................................. 49

10.7 Adapting System Headers ............................................................................ 49

10.8 Deleting Private/Proprietary Headers ............................................................ 50

10.9 Regular-Expression Denial-of-Service Attacks ............................................. 52

10


1 Introduction

Avaya Aura Session Manager 8.0.1 is enhanced in routing and adaptation:

• Previously, digit-based routing considered only originating location and destination digits. With 8.0.1, digit-based routing can also consider source digits.

• Previously, regular-expression routing was based entirely on the request-URI. With 8.0.1, regular-expression routing also considers originating location. Further, regular-expression conditions can be applied to routes, allowing routing to be based on any portion of the SIP message.

• Previously, adaptation allowed primarily modification of digit strings in SIP messages. With 8.0.1, regular-expression adaptation allows modification of virtually any portion of a SIP message. Further, more than one adaptation can be applied to a SIP entity, including combinations of digit-based and regular-expression adaptations.

11


2 Digit-Based Routing

The figure below depicts the differences between the existing and new digit-based routing designs:

Current and new digit-based routing design.

With the existing routing design, the algorithm considers the digits (and domain) present within the SIP Request-URI as well as the originating location1 associated with the request. The dial pattern is specified as either a simple pattern with min/max length qualifiers (e.g. “+1303” with min/max length of 12) and also contains wildcard characters (‘x’), or as a number range (e.g. “13035380000:13035387999”). Originating location can be a specific, administrator defined location or the location ‘ALL’, which matches all locations.

Multiple dial pattern matches are possible for a single request, depending on how the administrator has administered the system. By default, specific location matches take precedence over location ALL matches, even if the pattern match length is longer for location ALL. However, a global setting is available to override this behavior.

1 Session Manager typically associates multiple location types with a request. For routing purposes, the signaling location type

is used to match the location specified in the Dial Patterns.

12


Once a single dial pattern and location pair match has been identified, the set of routing policies associated with the match are ranked and used to route the request. Ranking of the routing policies involves analyzing the time-of-day entries associated with each routing policy, and then sorting the policies based on the resolved rankings. Any routing policies marked as disabled are removed from the list prior to actual routing taking place.

In the new design, in addition to the dial pattern match and location match, the algorithm considers an additional third criterion associated with the request called Origination Dial Pattern Set. The Origination Dial Pattern Set (described in detail below) is identified using the source address associated with the request. Use of this third criterion is completely optional. When not specified, the digit-based routing logic is equivalent to and fully backwards compatible with existing operation.

13


3 Source-Based Routing

3.1 Origination Dial Pattern Set

An origination pattern set is a collection of dial patterns (including ranges) that help to associate a given digit-based source address with the set (or possibly sets). The matching set(s) can then be used as additional criteria for routing as described in the preceding section. Note that dial patterns within a set can also specify an associated matching SIP domain, or they can specify matching on ANY domain.

A given specific dial pattern can only exist in one set. However, overlapping dial patterns (e.g. 303 with min/max of 10 and 303538 with min/max of 10) across sets are allowed, thereby allowing for a given source address to match more than one origination dial pattern set. This facilitates addition of exceptions to dial patterns (e.g. pattern 303 is used as a default match but has an exception for numbers matching pattern 303538).

The origination dial pattern sets represent a grouping of source numbers where the groupings are relevant for routing purposes. A sample use case is described in the Examples section below.

Origination Dial Pattern Sets appear as a new item within the navigation pane in the System Manager UI under the Elements -> Routing -> Dial Patterns2 category. Navigating to this item renders the Origination Dial Pattern Sets list view which lists all the administered origination dial pattern sets. New, Edit, Delete, and More Actions buttons are available to manage the sets.

Adding or editing a set involves a new Origination Dial Pattern Set Details screen that allows the user to manage the individual dial patterns that make up the given set. Selecting the Add button will open a new table row and allows the administrator to add the Pattern (or range), Min / Max values, and SIP Domain associated with the dial pattern entry. Previously added rows may be deleted using the Remove button.

2 Note that previously the Dial Patterns item appeared directly below the Elements -> Routing section in the navigation pane.

Now it appears under Elements -> Routing -> Dial Patterns (i.e. under an extra level within the navigation menu).

14


3.2 Modified: Dial Pattern Details

When adding or modifying a routing Dial Pattern an enhanced version of the Dial Pattern Details screen is displayed. This enhanced version displays the Origination Dial Pattern Set as an optional additional criterion for selecting the routing policies associated with the given dial pattern and optionally an originating location.

As new entries are added to either the “Originating Locations, Origination Dial Pattern Sets, and Routing Policies” or “Denied Originating Locations and Origination Dial Pattern Sets” sections of this screen, a (new) selection of Origination Dial Pattern Set

15


can be made3. Selection of the Origination Dial Pattern Set in the selection screen is, however, optional. When no Origination Dial Pattern Set is selected, the route matching will disregard source address as a criterion (i.e. any source address, including a non-numeric address will match the specific route). However, if an Origination Dial Pattern Set is included in the entry, the source address match criterion must be met for the route to be considered.

3.3 Global Settings: Dial Patterns Precedence

Since multiple matches can result during execution of the routing algorithm, a mechanism exists to identify the best match using a new Dial Patterns Precedence setting that appears on the Session Manager Global settings page. This new setting replaces the existing setting named “Better Matching Dial Pattern or Range in Location ALL Overrides Match in Originator's Location” on the screen when the Flexible Routing feature is enabled.

The Dial Patterns Precedence setting allows the user to arrange the three criteria used in dial pattern matching (i.e. Destination, Origination, Location) in priority order using the up/down arrows. The topmost criteria in the list has highest precedence and bottommost in the list has lowest precedence. A higher precedence for a given criteria means that a longer length match, or exact match in the case of Location, will be chosen over a shorter length match, or match on location ALL, above all lower precedence criteria.

3 Only one Origination Dial Pattern Set selection can be made for each added entry. However, multiple selections can be made

by invoking the Add operation multiple times.

16


For example, if there are multiple matches and the dial patterns precedence is set to Origination, Location, Destination, then the Origination Dial Pattern match has the highest precedence and the match with the longest length origination dial pattern would be selected over other matches that have a better location match or a longer (destination) dial pattern length match. If there are multiple matches with the same Origination Dial Pattern match, then the next highest-level precedence is checked to see if there is a single best match. In this example, that would be Location, so the algorithm would look to prefer exact location matches over location ANY matches. If there still multiple matches remaining, then the next highest-level precedence is used to determine the best match. In this example, that would be (destination) Dial Pattern, so the algorithm would look for the longest length destination dial pattern match.

3.4 Examples

3.4.1 911 Routing

An example use case involving emergency (911) calling illustrates the use of the origination dial pattern set capability to effect source-based routing. Suppose that an enterprise utilizes a configuration with trunks to multiple service providers and that the DID numbers assigned to each of the trunks correspond to a user within the enterprise. When a given user dials 911, the call should be routed to the service provider trunk with the assigned DID number that corresponds to the originating user. This is a typical use case for source-based routing.

To affect this type of routing, the administrator would set up origination dial pattern sets that correspond to each of the service providers. Each set would be populated with the dial patterns that reflect the set of DID numbers assigned to the service provider trunk(s). These can be specified as individual numbers, patterns with min/max lengths, or number ranges. A domain can be optionally specified for each pattern within the sets as well.

When the Dial Pattern 9114 is administered, the administrator configures multiple routes, each referencing a routing policy. At least one route and corresponding routing policy must be configured for each service provider. The route for each service provider references the origination dial pattern set corresponding to the service provider. Only calls originated from source addresses that match a dial pattern in the referenced origination dial pattern set can utilize routes that reference the set. Therefore, a user’s call to 911 will utilize the service provider trunk that the user is associated with.

4 Pattern is 911 with min/max length of 3 and domain ANY, for example.

17


4 Regular-Expression Routing

The figure below depicts the differences between the existing and new digit-based routing designs:

Current and new regular expression routing design.

4.1 Existing: Request-URI Match

With the existing design, the algorithm matches the administered regular expression patterns sequentially against the request URI, according to the administered rank order. This is the only criteria in the match. Also, regular expressions routes are only evaluated if digit-based routing has failed to identify a match. The sequence in which digit-based and regular expression-based routes are evaluated is not configurable.

When a regular expression match occurs, the associated routing policies are ranked in similar fashion to digit-based routing. The routing policies are ranked by analyzing the time-of-day entries associated with each routing policy, and then sorting the policies based on the resolved rankings. Any routing policies marked as disabled are removed from the list prior to actual routing taking place.

4.2 New: Origination Location

In the new design, originating location can be used as an additional, optional match criterion for any administered regular expression. The first regular expression found that

18


matches all the administered criteria is used to route the request. This enhancement brings regular expression-based routing on par with digit-based routing with respect to routing based on originating location.

4.3 New: Condition

In the new design, a new Condition criterion may also be optionally specified. This capability is quite powerful in that it can test for all sorts of conditions associated with the request. In fact, it can test any part of a message, including the request-line, response-line, headers, or attachments (body) for any specific content. Conditions can be combined using Boolean operators such as AND, OR and NOT and nested to compose arbitrarily complex sets of compound conditions. Conditions are described in detail in the Conditions section.

As with digit-based routing, all the specified criteria must match for any regular expression route to be used. Conditions are evaluated as they are encountered. Rank ordering of the regular expression continues to dictate the order of evaluation of the regular expression routes.

4.4 New: Precedence of Digit and Regular-Expression Routing

In the new design, the order of evaluation of digit-based and regular expression-based routes is configurable. On the Session Manager Global Settings page, a new setting for Set Precedence for Routing appears when Flexible Routing is enabled. The drop-down choices are: Dial Patterns (i.e. digit-based routes are evaluated first), and Regular Expressions (i.e. regular expression-based routes are evaluated first).

Note that when digit-based routes are evaluated first and find a match, regular expression routes are not evaluated. Similarly, when regular expression-based routes are evaluated first and find a match, digit-based routes are not evaluated. Due to this

19


behavior, there is never a need for the system to decide between a digit-based match and regular expression-based match. The decision, rather, is implicit within the Set Precedence for Routing setting.

4.5 Performance Concerns

Initial performance measurements suggest that typical usage of regular-expression routing will have very little impact on CPU usage. While running call traffic at 100 calls per second, taking the 1000th regular-expression route increased CPU usage by less than one percent compared to taking the first regular-expression route. Results will, of course, vary depending on the complexity of routing conditions.

20


5 Conditions

Conditions provide a generalized mechanism for testing whether the SIP message contains or does not contain specific content. Conditions specify regular expressions that are used to perform the content matching. Conditions can be combined with each other to form arbitrarily long Boolean expressions that can test multiple parts of the message content. For example, a Condition can be created that tests that the request method is INVITE and that the Contact header does not contain a parameter.

Conditions use what is termed as qualified expressions. A qualified expression is a regular expression match that operates on only a specific part of the message content, such as a specific instance of a header. This greatly reduces the processing overhead associated with regular expression matching that would otherwise occur if the input consisted of the entire message content. The Source Type, Source and Instance act as qualifiers for the part of the message to be selected and tested.

Conditions appear as a new navigation item under Elements -> Routing. Navigating to this item renders the Conditions List screen:

A new Condition Details screen is available for adding new conditions or modifying existing conditions:

21


5.1 Source Type, Source and Instance

The table below summarizes the available Source Type, Source and Instance values used when specifying a Condition. These values qualify the portion of the message to be used for the associated regular expression match.

Source-Type

Source Instance Value

request-line

method N/A Only applies to request messages. Selects the request method in the request-line.

request-uri N/A Only applies to request messages. Selects the Request-URI value in the request-line.

response-line

status-code N/A Only applies to response messages. Selects the status code value in the response-line.

reason-phrase

N/A Only applies to response messages. Selects the reason phrase value in the response-line.

header header name

any Selects all instances of the specified header. Used to test if any instance of the header matches the given regular expression.

all Selects all instances of the specified header. Used to test if all instances of the header match the given regular expression.

22


positive integer (n)

Selects value of instance n of the header from the top.

negative integer (-n)

Selects value of instance n of the header from the bottom.

attachment content type

any, all positive integer (n), negative integer (-n)

Selects the attachment with the given content type. Instance value behaves the same as for headers above.

Note that although in the SIP standard multiple instance headers can appear as comma-separate values within the message, the regular expression matching operates on each instance individually regardless of how the multi-instance header is represented in the message. Therefore, never try to do a match on a multi-instance header using a regular expression that expects comma-separate values as input. This will never be the case and will not work as desired.

5.2 Match Expression

The match expression represents the regular expression to be used for matching qualified message content. Any regular expression conforming to the standard Java programming language regular expression package can be used. A reference for the allowed regex patterns can be found at: https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html.

5.3 Logical Operators (NOT, AND, OR)

Within a Condition a Logical Operator of AND or OR may be selected. When one of these is selected, the Condition is defined to have two operands (i.e. Operand 1 and Operand 2) where each operand can test a separate part (i.e. Source-Type, Source, and Instance) of the message. Logically the operand results are to be AND’ed or OR’ed to produce an overall value for the Condition at runtime.

In addition, the Logical Operator field can be left blank. This indicates that the Condition is defined to have just a single operand (i.e. Operand 1). Normally the resulting value of the Condition would be equal to the value of the single operand.

https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html

23


It is also possible to negate the value of each operand thereby providing a logical NOT operation on the operand result. This is accomplished by checking the Negative checkbox associated with each operand.

5.4 Building a Condition Tree

More complex logical expressions can be created by having Conditions refer to other Conditions. Each operand in a Condition definition may either test some part of a message for content, or it may directly refer to yet another Condition. Through such Condition nesting arbitrarily complex expressions, or Condition Tree’s, can be constructed.

For example, say we had three existing Conditions: Condition A, Condition B, and Condition C defined in the system and we wanted to produce a single Condition Q that combined these conditions as follows:

Condition Q = (Condition A AND NOT Condition B) OR Condition C

To accomplish this task, we would need to define one extra intermediate Condition D as follows:

Condition D = (Condition A AND NOT Condition B)

And then define Condition Q by referring to Condition D as follows:

Condition Q = Condition D OR Condition C

The screen below captures the definition of the intermediate Condition D used in this example. Note that Operand 2 has the Negative checkbox checked which provides for the NOT operator applied to Condition B.

As can be seen from the preceding example, Conditions can be combined to produce as complex a logical expression as is desired.

24


Since it is possible define Conditions with loops (i.e. Conditions that reference other Conditions higher in the constructed Condition Tree), SM limits the recursion through the tree to 100 steps or levels.

25


6 Regular-Expression Routing Examples

6.1 Denying a SIP Request

Regular-expression routing has always allowed a request-URI regular-expression match to deny a SIP request. Now, a routing condition can be used to deny a SIP request based on a wide variety of criteria.

For example, to deny all OPTIONS requests, set up a condition based on the SIP

method.

Next, apply the condition to a regular expression route matching .* (i.e. any request

URI).

26


Any incoming OPTIONS request will now be denied with a 403 Forbidden response.

6.2 Routing H.264 Video from Android Devices

Suppose INVITE requests with request-URI [email protected] from Android devices

requesting H.264 video should be routed to a destination.

To detect an Android device requesting H.264 video, create a condition that checks the User-Agent header for the string Android.

Add a second operand to the condition to check the application/sdp attachment for

a video m-line followed by an H.264 a-line. The regular expression m=video(.*\r\n)+a=.*H264 will match m=video followed by one or more lines

ending in \r\n, the CRLF combination that is required at the end of each line in the

application/sdp attachment. Note that .* will not by default match CRLF, so that

the \r\n must be explicitly matched by the regular expression.

Tie the two operands together with the AND logical operator.

27


Add a regular-expression route for request-URI [email protected] and add the

Android H.264 video condition to the route.

Now, any INVITE request with request-URI must match the Android H.264 video

condition to choose this route. If the condition fails, the INVITE will be matched against

other regular-expression routes until a match is found.

28


7 Adaptation

Adaptation is a mechanism for modifying SIP messages as they enter Session Manager (incoming or ingress adaptation) or leave Session Manager (outgoing or egress adaptation).

7.1 Existing: A Single Digit-Based Adapter

Prior to Session Manager 8.0.1, adaptations were all based on the DigitConversionAdapter, which primarily allowed modification of digit strings in request-URIs and headers such as From, To, and P-Asserted-Identity. Other standard adaptation modules provided digit conversion as well as minor protocol conversions to allow various service providers and third-party SIP components to interwork. More exotic modifications could be performed by custom adapters, created by Avaya Professional Services. Each SIP entity could be assigned at most one adaptation module.

7.2 New: A Sequence of Digit-Based and Regular-Expression Adapters

Session Manager 8.0.1 introduces regular-expression adaptation, which allows the administrator to build adaptations that can modify virtually any part of a SIP message using regular expressions.

Additionally, each SIP entity can now have a sequence of multiple adaptations, mixing digit-based and regular-expression adaptations. When an entity has more than one adaptation, the sequence is run in forward order for ingress adaptation and in reverse order for egress adaptation.

29


8 Regular-Expression Adaptation

Each regular-expression adaptation consists of a sequence of zero or more incoming adaptation rules and a sequence of zero or more outgoing adaptation rules, administered on System Manager’s Regular Expression Adaptation Details form.

8.1 Regular-Expression Adaptation Rules

Each regular-expression adaptation rule consists of zero or more variables and one or more actions.

30


8.2 Regular-Expression Variables

For each regular-expression rule, zero or more regular-expression variables can be defined. These variables can be used to in add or modify actions to insert content saved from one part of a SIP message into another part.

The part of the SIP message that may be saved into the variable is defined in terms of source type, source, and instance, as defined in the table below.

Source-Type Source Instance Result

request-line method not applicable Request only: the variable is set from the matching part of the SIP method.

request-uri not applicable Request only: the variable is set from the matching part of the request-URI.

31


response-

line

status-code not applicable Response only: the variable is set from the matching part of the status code.

reason-phrase not applicable Response only: the variable is set from the matching part of the reason phrase.

header or attachment

header name or content type

positive integer or top

For instance, n, the variable is set from the matching part of the n'th header/attachment of the specified type. The variable is not set if there are fewer than n headers/attachments of that type. top is an alias for 1.

negative integer or bottom

For instance -n, the variable is set from the matching part of the n'th header/attachment of the specified type, in reverse order. For example, instance -1 is the last

instance. The variable is not set if there are fewer than n headers/attachments of that type. bottom is an alias for

-1.

first-match The variable is set from the matching part of the first header/attachment of the specified type that matches the regular expression.

last-match The variable is set from the matching part of the last header of the specified type that matches the regular

32


expression.

Each variable has an associated regular expression. If the regular expression matches at least part of the source string, the variable will be assigned the value of the first capture group (sequence of characters in parentheses); subsequent capture groups will be ignored. For example, for regular expression (a.c)def(g.i) and source string

abcdefghi, the variable will be assigned the string abc, and the second capture group

will be discarded. If there is no capture group in the regular expression, the variable will not be assigned.

Regular-expression variables administered for a regular-expression adaptation rule are evaluated for every message that matches the rule's condition. The scope of the variable is limited to a single message, i.e. a variable set for one message cannot be used in another message, and variables are reevaluated per message.

8.3 Regular-Expression Adaptation Actions

A regular-expression adaptation action can modify a SIP message by:

• Adding a SIP header or attachment, optionally using variables to specify the content

• Deleting a SIP header or attachment, if it matches the specified regular expression

• Modifying virtually any part of the SIP message, replacing the portion that matches the specified regular expression with a replacement expression, optionally using variables

8.3.1 Add Actions

An add action adds a new SIP header or attachment to a SIP message. The header or attachment to be added is specified in terms of source-type (header or attachment),

source (header name or content-type), and instance.

The instance is a positive or negative integer. For instance, n, a header is added such that it becomes instance n of the specified type, e.g. instance 1 will be added before all existing headers, while instance 2 will be added between the first and second existing header. If n is negative, headers are counted from the bottom, e.g. instance -1 will be added after all existing headers, while instance -2 will be added between the last and second-to-last existing headers. top and bottom are aliases for 1 and -1, respectively.

33


If there are fewer headers than n-1, the new header cannot be added in position n, and so will not be added at all. The relative order of the existing headers is maintained.

The Replace/Add Expression is used to create the content of the new SIP header or attachment. The Replace/Add Expression is not a regular expression, but rather an expression involving literal characters and named variables. Named variables (${string}, where string contains upper-case letters, lower-case letters, numbers

or underscores) are set based on regular expression variable administration for the adaptation rule being executed.

8.3.2 Delete Actions

A delete action deletes one or more SIP headers or attachments from a SIP message. The headers or attachments to delete are specified in terms of source-type (header or

attachment), source (header name or content-type), and instance. The

header/attachment is deleted only if the Match Expression matches at least part of the header/attachment.



header name or content-type

any All headers/attachments of the specified type that match the Match Expression are deleted. The relative order of the remaining headers/attachments is maintained.


For instance n,if the n'th header/attachment of the specified type matches the Match Expression, it is deleted. top is an alias for 1. If there

are fewer headers/attachments than n, no header/attachment is deleted. The relative order of the remaining headers/attachments is maintained.

negative Behaves as specified above for

34


integer or bottom

positive integers, except that instance counting is down from the end, i.e. instance -1 is the last instance. bottom is an

alias for -1.

first-match The first header/attachment of the specified type that matches the Match Expression is deleted. The relative order of the remaining headers is maintained.

last-match Behaves as specified above for first-match, except that the last matching header is modified/deleted.

8.3.3 Modify Actions

A modify action can modify virtually any part of a SIP message. The part to be modified is specified in terms of source-type, source, and instance. The modification occurs only if the Match Expression matches at least part of the specified source instance.


request-line method not applicable Cannot be modified

request-URI not applicable Request only: the part matching the Match Expression is replaced by the Replace/Add Expression, after variable evaluation.

response- status-code not applicable Response only: the part matching the Match Expression

35


line is replaced by the Replace/Add Expression, after variable evaluation. If the resulting status code is invalid, the status code will not be modified.

reason-

phrase

not applicable Response only: the part matching the Match Expression is replaced by the Replace/Add Expression, after variable evaluation.


header name or content-type

any All headers/attachments of the specified type that match the Match Expression are modified such that the part matching the Match Expression is replaced by the Replace/Add Expression, after variable evaluation. The relative order of the headers/attachments is maintained.


For instance, n, if the n'th header/attachment of the specified type matches the Match Expression, it is modified such that the part matching the Match Expression is replaced by the Replace Expression, after variable evaluation. top is an

alias for 1. If there are fewer

headers/attachments than n, no header/attachment is modified. The relative order of the headers/attachments is maintained.

negative integer or

Behaves as specified above for positive integers, except that instance counting is down from

36


bottom the end, i.e. instance -1 is the last instance. bottom is an alias

for -1.

first-

match

The first header/attachment of the specified type that matches the Match Expression is modified such that the part matching the Match Expression is replaced by the Replace Expression, after variable evaluation. The relative order of the headers/attachments is maintained.

last-match Behaves as specified above for first-match, except that the

last matching header/attachment is modified.

The Replace/Add Expression is used to replace the source content that matched the Match Expression. The Replace/Add Expression is not a regular expression, but rather an expression involving literal characters and numeric and named variables. Numeric variables (${i}, where i is a positive integer) are set by capture groups (sub-

expressions in parentheses) in the Match Expression, while named variables (${string}, where string contains upper-case letters, lower-case letters, numbers

or underscores) are set based on regular expression variable administration for the adaptation rule being executed.

For example, assume named variables A and D are set to abc and def, respectively.

Assume a Match Expression (1.3)456(7.9), and a Replace/Add Expression

${1}x${A}y${2}z${B}. Given a source string 123456789, the numeric variables

${1} and ${2} will be set to 123 and 789, respectively, and the Replace/Add

Expression will evaluate to 123xabcy789zdef.

Note that for a modify action, the Replace/Add Expression can be empty, indicating that the portion of the input matched by the Match Expression will be deleted.

37


8.4 Performance Impact

Initial performance measurements suggest that typical usage of regular-expression adaptation will have modest impact on CPU usage. While running call traffic at 100 calls per second, applying typical regular-expression adaptations increased CPU usage by less than five percent compared to not adapting at all. Results will, of course, vary depending on the complexity of regular-expression conditions and adaptations.

38


9 Regular-Expression Adaptation Examples

9.1 Adding a Route Header

To add a Route header based on an address in a different header, create a variable to

read the address, and create an add action to add the Route header, using that

variable.

9.2 Deleting the Last Record-Route Header

To delete the last Record-Route header that matches avaya.com, create a delete

action using instance last-match. To avoid unintended matches, remember to

escape the dot (avaya\.com).

39


9.3 Modifying a Route Header Using Named and Numbered Variables

Suppose that if the third Route header matches a IP address, you want to modify the header such that the address is changed to the content of another header and the transport is changed from TCP to TLS.

Create a variable to read the address and create a modify action to match and change the Route header.

If the third Route header matches the Match Expression, the parenthesized part of the expression (i.e. anything between the address and the transport parameter) will be

captured into the variable ${1} for use in the Replace/Add Expression.

9.4 Adapting a Response Code for Alternate Routing

Suppose an INVITE request leaves Session Manager and gets a 606 response from a remote SIP entity. A 606 response will not normally cause Session Manager to alternate route the INVITE request, and the 606 response will be proxied back to the originator, causing the call to fail.

A regular-expression adaptation could change the status code in the response to one (for example, 503) that will cause alternate routing.

40


9.5 Replacing the P-Asserted-Identity Header with the Alternate-CLI header

The Alternate-CLI header is populated by Avaya Aura Communication Manager

with a preferred caller identification for outbound call centers. A regular-expression adaptation could be used to replace the display name and URI user part of the P-Asserted-Identity header with the content of the Alternate-CLI header. For illustrative purposes, suppose this modification should only happen for certain Alternate-CLI values.

Add a condition to match the Alternate-CLI header against the regular expression “[Ww]ealth ([Mm]anagement|[Mm]gmt)”. This expression will match either “Wealth Management” or “Wealth Mgmt”, with the initials either upper-case or lower-case.

Create a regular-expression adaptation with an incoming adaptation rule using the Wealth Management condition. The rule will be executed only if the condition passes,

i.e. if the Alternate-CLI header matches the regular expression in the condition.

41


The incoming adaptation rule has one variable, to capture the content of the Alternate-CLI header, and two rules. The first rule deletes the Alternate-CLI

header, and the second rule modifies the P-Asserted-Identity header.

The variable AlternateCLI captures from the Alternate-CLI header using the

regular expression (.*). .* matches the entire header, and everything inside the

parentheses (i.e. the entire header) is captured into the variable.

The second action modifies the P-Asserted-Identity header if it matches the

regular expression ".*" (<sips?:).*@ . The header must have a display name

inside quotation marks. The SIP scheme is captured into a numbered variable for reinsertion into the modified header – note that the expression <sips?: will match

either <sip: or <sips:, due to the use of the ? quantifier.

The Replace/Add Expression "${AlternateCLI}" ${1}${AlternateCLI}@ will

modify the portion of the header that matched the Match Expression. The display name is replaced by the content of the ${AlternateCLI} variable, as is the user portion of

the URI. The captured SIP scheme is reinserted using the variable ${1}.

Suppose an incoming INVITE request contains the following:

P-Asserted-Identity: “56666" sip:[email protected]

42


Alternate-CLI: Wealth Management

After adaptation, the INVITE request will no longer have an Alternate-CLI header,

and the P-Asserted-Identity header will have been modified:

P-Asserted-Identity: "Wealth Management"

<sip:Wealth%[email protected]>

Note that the space in Wealth Management has been escaped, as required by RFC

3261, in the URI, without any special handling required in the Replace/Add Expression.

9.6 Modifying an INVITE request to Comply with STIR/SHAKEN Regulations

To combat calling-number spoofing, the telecommunications industry has proposed the STIR (Secure Telephone Identity Revisited) and SHAKEN (Signature-based Handling of Asserted information using toKENs) standards. When service providers are required by regulations to comply with these standards, SIP networks will no longer accept INVITE

requests with caller-identification headers (From, Contact, P-Asserted-Identity)

with user parts that do not belong to the range of numbers assigned to the originating entity.

For Avaya Aura customers, there are certain call scenarios where INVITE requests

sent to a service provider SIP network will not comply with the STIR/SHAKEN standards. Regular-expression adaptation can modify the relevant headers to provide compliance.

Consider the call scenario where a call from the public network to a Communication Manager endpoint is forwarded to another destination in the public network. The INVITE request sent by Communication Manager to the public network via Session

Manager will have the original caller’s number in the From, Contact, and P-Assert-

Identity headers rather than the forwarding endpoint’s number, Since the caller’s

number is not in the number range assigned to this enterprise, the service provider may reject the INVITE request when STIR/SHAKEN regulations take effect.

Below is a partial example of an INVITE request sent from Communication Manager to

Session Manager when a call from public-network user +13035551111 calls +13035552222 and the call is forwarded to public-network user +13035553333.

INVITE sip:[email protected] SIP/2.0

From: <sip:[email protected]>;tag=1-SIPp-caller

Contact: "+13035551111"

sip:[email protected]:5070;transport=TCP

43


P-Asserted-Identity: "+13035551111" sip:[email protected]

History-Info: "+13035552222"

<sip:[email protected];5061?Reason=SIP%3Bcause%3D302%3Btext

%3D%22Moved%20Temporarily%22&Reason=Redirection%3Bcause%3DCFI>;i

ndex=1.1

A regular-expression adaptation can save the forwarding endpoint’s number from the History-Info header and replace the original caller’s number with the forwarding

number in the From, Contact, and P-Asserted-Identity headers.

First, administer a condition to detect that the call has been forwarded by Communication Manager. This condition will match on cause%3DCFI in any History-

Info header. (Note that the string inserted by Communication Manager is actually

cause=CFI, but the equals sign must, according to the SIP standard, be escaped as

%3D.)

Next, administer a regular-expression adaptation with this condition and an ingress rule that will save the user from the History-Info header.

44


This rule finds the first History-Info header that matches the regular expression

sips?:(.*)@.*cause%3DCFI and saves the capture group (expression in

parentheses, i.e. the user part of the SIP URI) into a variable called redirector. Note

the use of the expression sips? To match both sip and sips.

The rule then matches the regular expression (sips?):.*@ against the From,

Contact, and P-Asserted-Identity headers. The capture group (expression in

parentheses) in this expression will store either sip or sips in the numbered variable

${1}. This variable will be used to reinject sip or sips, as appropriate into the

modified header. For each header, the matching part of the header is replaced by ${1}:${redirector}@, with ${1} and ${redirector} replaced by the contents of

those variables.

Apply this adaptation to the Communication Manager SIP entity.

After adaptation, the INVITE request looks as follows:

INVITE sip:[email protected] SIP/2.0

From: <sip:[email protected]>;tag=1-SIPp-caller

Contact: "+13035551111"

sip:[email protected]:5070;transport=TCP

45


P-Asserted-Identity: "+13035551111" sip:[email protected]

History-Info: "+13035552222"

<sip:[email protected];5061?Reason=SIP%3Bcause%3D302%3Btext

%3D%22Moved%20Temporarily%22&Reason=Redirection%3Bcause%3DCFI>;i

ndex=1.1

Note that the display portion (characters inside double quotes) of the headers has not been modified, and it is not anticipated that the display portion needs to be modified to comply with STIR/SHAKEN regulations. Should it be desirable to modify the display portion, that can be accomplished with the more elaborate match expression (".*"

)?<(sips?):.*@ and replace expression "${redirector}" <${2}:${redirector}@

The redirection cause CFI is not the only one that can occur in the History-Info

header when Communication Manager redirects a call. Possible causes include:

• CFI (call forward immediate)

• CFB (call forward on busy)

• CFNR (call forward on no reply)

• NORMAL/avaya-cm-reason=extension-to-cellular (EC500)

• NORMAL/avaya-cm-reason=cover-busy (remote coverage on busy)

• NORMAL/avaya-cm-reason=cover-no-reply (remote coverage on no reply)

• NORMAL/avaya-cm-reason=send-all-calls (remote coverage for send-all-

calls active)

To modify headers for multiple redirection causes, you can either:

1) Add a condition and corresponding ingress rule for each redirection cause, replacing CFI in the condition and in the redirector variable match expression

with the desired cause.

2) Expand the regular expression in the condition to include multiple redirection causes, separated by vertical bars (|). For example, to match CFI, CFB, or

CFNR, use the regular expression cause%3D(CFI|CFB|CFNR) in the condition

and the match expression sips?:(.*)@.*cause%3D(CFI|CFB|CFNR) in the

definition of the redirector variable.

46


If any cause contains an equals sign, it must be replaced by the escaped version (%3D)

in the regular expression!

The From header in any responses will automatically be restored to the original From

header before the response is sent to Communication Manager.

47


10 Regular-Expression Adaptation Tips and Tricks

10.1 Regular-Expression Basics

Regular-expression adaptation is implemented using Java 8 regular expressions, so the definitive guide to how to write regular expressions for adaptations is the Java 8 documentation: https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html.

10.2 Multiple-Instance Headers

RFC 3261 specifies that multiple SIP headers of the same type can appear either on separate lines or as one header with comma-separated fields. When trying to adapt such headers, keep in mind that Session Manager treats a comma-separated list of headers as separate headers, thus adaptation will as well.

Consider, for example, an Allow header:

Allow: INVITE, ACK, OPTIONS, BYE, CANCEL, SUBSCRIBE,

NOTIFY, PRACK

It's tempting to try to match this header using a regular expression like ", BYE,". However, each of the methods specified in the Allow header is a separate Allow

header, and the commas don't exist in any Allow header, thus the match fails. Instead,

regular-expression adaptation will operate on each Allow header as if it were a

separate header.

10.3 Using Embedded Flags in Regular Expressions

To enable case-insensitive matching, use the embedded flag expression (?i). For

example, the regular expression a.c will match abc, but not ABC. However, the regular

expression (?i)a.c will match both abc and ABC.

To enable dotall mode, use the embedded flag expression (?s). Without dotall mode,

the dot character will not match new-line characters, thus the expression .* will not

cross new-line boundaries. With dotall mode enabled, the dot character will match new-line characters and the expression .* will match across new-line boundaries. Consider

the string a\nb\nc; the regular expression a.*c will not match, but the regular

expression (?s)a.*c will match.

https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html

48


To enable multiline mode, use the embedded flag expression (?m). Without multiline mode, the carat and dollar characters match the beginning and end of the entire input string. With multiline mode enabled, the carat and dollar characters match the beginning and end of any single line. Consider the string a\nb; the regular expression â$ will not

match, but the regular expression (?m)â$ will match.

Note that the parentheses in the embedded flag expression do not create a capture group. In the expression (?m)^(abc), there is only one capture group, and numbered

variable ${1} will contain abc.

10.4 Modifying Multiline Attachments

A potentially common use case for regular-expression adaptation is modifying SDP attachments, but modifying a multiline attachment poses interesting challenges.

By default, the regular expression .* does not match across new-lines. As a result,

matching a=rtpmap.* will match only the first rtpmap line, and nothing past that line.

Use the multiline embedded flag expression (?m) to change this behavior. Note,

however, that a negated character class like \D (non-digits) and [âbc] (anything

other than a, b, or c) will match new-lines and cause behavior you likely didn't expect.

Note that SDP lines end with CRLF rather than just LF. To match multiple lines, put \r\n between lines.

To remove an m=audio line, match m=audio.*\r\n and replace it with an empty

string. Not specifying the CRLF in the regular expression results in an unexpected blank line in the SDP attachment.

Specifying remove as the operation for an attachment will remove the entire attachment, not just the matching portion, or a single matching line in the attachment.

The most convenient way to match the second occurrence of an m=audio line in an

SDP attachment is to use an embedded flag expression to enable dotall mode. But beware of greedy matching in dotall mode! Consider the following SDP attachment:

m=audio 1 RTP/AVP 0

m=audio 2 RTP/AVP 0

m=audio 3 RTP/AVP 0

To capture the port from the second line, you might try (?s)m=audio.*m=audio

(\d+), and you might be surprised when ${1} is set to 3 - that's because .* is greedy

(i.e. it matches the longest possible string) and matches past the second line to the third line. To capture the port from the second line, use a reluctant quantifier:

49


(?s)m=audio.*?m=audio (\d+) . The question mark after the .* makes it

reluctant, i.e. it matches the shortest possible string. Note that there is only one capture group in this expression (embedded flag expressions are not capture groups, in spite of the parentheses).

There is no straightforward way to modify multiple matches of a regular expression within one attachment or header. Such functionality could be implemented by adding a global checkbox for each rule action in the System Manager GUI. (As a workaround, one could administer two identical modify actions such that each will modify one occurrence of the regular expression.)

10.5 Matching SIP URIs

A common use case for a regular-expression variable is to extract the user part from a SIP URI. Keeping in mind that a regular-expression variable is populated from the first capture group (i.e. expression in parentheses) in the regular expression, a natural first attempt at a regular expression to capture the user part is sip:(.*)@, with the

captured user part being anything between sip: and @.

Note, however, that this regular expression will not match a SIPS URI. To match both SIP and SIPS URIs, instead use the regular expression sips?:(.*)@, where the

question mark specifies that either zero or ones will match.

10.6 Matching IP Addresses

Reading an IP address into a variable and using it to modify a header is likely to be a popular use case for regular expression adaptation. To correctly match an IPv4 address, remember to escape the dots, so that they don't unintentionally match other characters: \d+\.\d+\.\d+\.\d+ . Note that this regular expression will still match

strings that are not valid IPv4 addresses, like 555.1.2.123456. It is possible, but tedious, to specify a slightly more restrictive and slightly more accurate regular expression: \d{1-3}\.\d{1-3}\.\d{1-3}\.\d{1-3} . To see an example of the ridiculous

lengths to which one must go to perfectly match IPv4 addresses and only IPv4 addresses, see https://www.regular-expressions.info/ip.html.

IPv6 addresses are significantly more difficult to match perfectly. A simple, but overly generous regular expression that matches IPv6 addresses is [0-9a-fA-F:]+ , or the

more cryptic [\p{XDigit}:]+ . More correct expressions for matching IPv6

addresses are well over 100 characters long.

10.7 Adapting System Headers

As described in JSR 289, system headers are SIP headers that are managed by the SIP servlet container. This includes the headers Call-ID, From, To, CSeq, Via,

50


Record-Route, Route, and Path. The SIP servlet container places limitations on how

these headers can be added, modified, or deleted, thus there are limitations on how these headers can (or should) be adapted. The result of adapting a system header can be unpredictable, ranging from no effect to the desired effect to call failures.

Consider, for example, possible results of adapting the From header:

• Deleting the From header will cause a call to fail.

• Adding a From header will have no effect.

• Modifying the URI in a From header is allowed, and is a common use case.

• Modifying the From header such that the tag is removed will cause a call to fail.

10.8 Deleting Private/Proprietary Headers

As various Avaya Aura components process SIP messages, they may add, modify, or delete various private/proprietary SIP headers to provide call-processing features. These headers will have names start with P- or Av-; private/proprietary headers

currently used by Session Manager include:

• Av-Call-Appearance

• AV-Correlation-ID

• Av-Map-URI

• Av-Media-Server-Perf

• Av-Secure-Indication

• Av-SM-Join

• Av-SM-Replaces

• Av-Global-Session-ID

• Av-SM-User-to-User

• P-Asserted-Identity

• P-AV-Failed-Entity

51


• P-AV-Original-Handle

• P-AV-Message-Id

• P-Av-Transport

• P-Charging-Vector

• P-Location

• P-Preferred-Identity

• P-Site

Note that future Session Manager feature development may add further private/proprietary headers.

A common use case for adaptation is deleting private/proprietary headers to prevent incompatibility with non-Avaya SIP components that may not be tolerant of unfamiliar SIP headers. One might expect that regular-expression adaptation is the perfect vehicle for deleting those headers. However, certain private/proprietary headers (for example, headers used by Session Manager’s Call Admission Control feature) are added after regular-expression adaptation is performed, and so deleting those headers using regular-expression adaptation will be ineffective.

To delete private/proprietary headers, use a digit-based adaptation with the eRHdrs

parameter specifying the headers to remove on egress, independent of any digit modifications administered in the adaptation.

52


10.9 Regular-Expression Denial-of-Service Attacks

Poorly chosen regular expressions combined with unfortunate SIP message content can result in something resembling a regular-expression denial-of-service attack, i.e. extremely high CPU usage while SIP messages are matched against regular expressions.

Typical regular expressions used in regular-expression routing and adaptation, combined with typical SIP message content, will not cause performance problems. However, the proper conditions for a regular-expression denial-of-service attack could be created by a malicious (or very, very unlucky) administrator.

Consider, for example, a condition that tries to match a SIP header against the regular expression (x+x+)+y. For the clear majority of possible header content, whether a

header matches this regular expression will be evaluated with minimal CPU usage; however, for a header that contains, for example, xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx, evaluating whether the header

matches the regular expression will take several seconds.

The reason such a combination of regular expression and input takes such a large amount of time to process is beyond the scope of this paper, but has to do with how most regular-expression engines (including the one included with Java) are implemented – see https://www.regular-expressions.info/catastrophic.html for a good discussion.

Some guidelines that will help prevent regular-expression denial-of-service attacks (see https://www.regular-expressions.info/redos.html for more detail):

• Avoid alternatives that can match the same input. For example, the regular expression (.|\s)* will, when presented with a long string of spaces, consume

a large amount of CPU while trying to match spaces against either . (any

character) or \s (any white-space character).

• Avoid successive quantified strings that can match the same input. For example, the regular expression (x+x+)+y will, when presented with a long string of x’s,

consume a large amount of CPU while trying to match varying numbers of x’s

against the two x+ subexpressions.

• Avoid nested quantifiers. Using the same example, the regular expression (x+x+)+y will, when presented with a long string of x’s, consume a large

amount of CPU while trying to match varying numbers of x’s inside the

parentheses and outside the parentheses.

https://www.regular-expressions.info/catastrophic.html

https://www.regular-expressions.info/catastrophic.html

https://www.regular-expressions.info/redos.html

https://www.regular-expressions.info/redos.html

routing and adaptation enhancements in avaya aura session

Documents