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 tested on Asterisk LTS version 18.23.1 and 20.8.1.

2. Build Asterisk

To work with ClearIP for STIR/SHAKEN and CNAM services, Asterisk must be built with the bundled pjproject. In addition, pjproject version 2.14 or later must be used to support the SIP 3xx Contact header URI header parameter (embedded header) mechanism.

Note: Asterisk LTS version 18.22.0 and 20.7.0 are shipped with pjproject version 2.14.

2.1. Configure to build with bundled pjproject

$ ./configure --with-pjproject-bundled

2.2. Build and install

$ make && make install

3. Configure Asterisk

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

  1. Using ClearIP routing features, or
  2. 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

; 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()

; Context for hairpin traffic
[hairpin]
; Exten for calls received from ClearIP
exten => _1XXXXXXXXXX,1,NoOp(fromHairpin)
; P-Asserted-Identity and Identity headers are visible
…

gears