Asterisk STIR/SHAKEN and CNAM configuration with ClearIP

1. Introduction

This documentation explains how to build and configure Asterisk to work with ClearIP for STIR/SHAKEN and CNAM services. These instructions are based on Asterisk version 18.11.2.

2. Build Asterisk

To work with ClearIP for STIR/SHAKEN and CNAM services, Asterisk must be built with the bundled pjproject. In addition, you must apply a pjproject patch to support the SIP 3xx Contact header URI header parameter (embedded header) mechanism.

2.1. Configure to build with bundled pjproject

$ ./configure --with-pjproject-bundled

2.2. Apply pjproject patch, build and install

The pjproject patch is available on GitHub. After applying this patch, Asterisk can be built as usual.

$ make && make install

If the patch is applied to a compiled Asterisk source tree, perform the following steps after applying the patch:

$ cd third-party/
$ make clean && make
$ cd ..
$ make && make install

3. Configure Asterisk

Asterisk can be configured for two different call scenario use cases:

Using ClearIP routing features, or
Using a hairpin.

3.1. Using ClearIP routing features

ClearIP returns target destinations based on different mechanisms, such as LCR, etc. Asterisk redirects the calls to the target destinations directly.

pjsip.conf

The ClearIP endpoint must be configured with the following parameters:

[clearip]
type=endpoint
aors=clearip
redirect_method=uri_pjsip
…

The ClearIP aor must be configured with the following parameters:

[clearip]
type=aor
contact=sip:sip.clearip.com\;transport=tcp
…

Optionally, SIP OPTIONS ping also can be configured for ClearIP in its aor.

extensions.conf

; Context for incoming traffic
[incoming]
; Exten for calls sent to ClearIP
exten => _1XXXXXXXXXX,1,NoOp(toClearIP)
; Store P-Asserted-Identity header
same => n,Set(_IN_PAI=${PJSIP_HEADER(read,P-Asserted-Identity)})
; Store Identity header
same => n,Set(_IN_STI=${PJSIP_HEADER(read,Identity)})
; Send calls to ClearIP with pre-dial subroutine to forward P-Asserted-Identity and Identity headers to ClearIP
same => n,Dial(PJSIP/${EXTEN}@clearip,,b(preDial^passParam^1))
; Done
same => n,NoOp(afterToClearIP)

; Pre-dial subroutine copying P-Asserted-Identity and Identity headers
[preDial]
exten => passParam,1,NoOp(predial)
; Copy P-Asserted-Identity header
same => n,Set(PJSIP_HEADER(add,P-Asserted-Identity)=${IN_PAI})
; Copy Identity header
same => n,Set(PJSIP_HEADER(add,Identity)=${IN_STI})
same => n,Return()

3.2. Hairpin

With the hairpin configuration, ClearIP returns Asterisk as the target destination, then Asterisk routes calls based on its internal routing logic.

pjsip.conf

The ClearIP endpoint must be configured with the following parameters:

[clearip]
type=endpoint
aors=clearip
redirect_method=uri_pjsip

The ClearIP aor must be configured with the following parameters:

[clearip]
type=aor
contact=sip:sip.clearip.com\;transport=tcp

Optionally, SIP OPTIONS ping also can be configured for ClearIP in its aor.

Asterisk endpoint must be configured with context, say hairpin, and identified by its IP address.

[asterisk]
type=endpoint
context=hairpin
…

[asterisk]
type=identify
endpoint=asterisk
match=<Asterisk IP address>
…

extensions.conf