Script for Stir/Shaken with Neustar

[NicoleTan]

This script is to handle the below AS Authentication and VS verification call flow with Nuestar
Nuestar AS Authentication signing call flow:

a. ProSBC receives call from customers with NO token
b. ProSBC sends Invite to Neustar Authentication service (AS) to get the token
c. Neustar responds 302 with token:
e.g.
Identity: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9jci11YXQuY2NpZC5uZXVzdGFyLmJpei9jY2lkL2F1dGhuL3YyL2NlcnRzLzExNDUwLjEwMTQwIn0.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyI2MzE3OTE4Mzc4Il19

d. ProSBC forwards the call to outbound Vendor with the token


2- Nuestar VS verification call flow:

a. ProSBC receives call from Vendor with token
b. ProSBC sends Invite to Neustar Verification service (VS) to validate the token
c. If the token is good, Neustar responds 302 with verstat in PAI
e.g. P-Asserted-Identity: "1235724705"sip:1235724705;verstat=TN-Validation-Passed@xxx.xxx.xxx.xxx
d. ProSBC forwards the call to the customers with the verstat header . Same DID could be sent to multiple customers
e. If the token is NOT good, Neustar responds 4xx (could be remapped to any reason code) with detail reason:
e..g in a 403 (438 with remapped reason code: 403) response:
Reason: SIP;cause=438;text="IdentityClaimOrigMismatch - 'orig' value specified in PASSporT claim does not match SIP From/P-Asserted-Identity header values. orig_cc is empty"
f. Upon the 4xx response, ProSBC determines to drop the call or continue the call


In order to use this module, follow the steps below:
1- Add the "require 'Nuestar' unless defined?(NuestarQuery)" statement at the top of the main script.
2- Add the "include NuestarQuery" statement in the main routing class.
3- Add the filter " after_filter :method => :nuestar_query" in the main routing class.



4a- Create Link to Nuestar
4a1- Create a TCP transport server
SIP -> Create New Transport Server
Name: SIP_TS_Nuestar
Port Type: UDP
Port: 5060
IP Interface: [Select IP interface that can have access to the internet]

4a2- Create Nuestar AS or VS NAP
NAPs -> Create New NAP
Name: NAP_Nuestar_AS or NAP_Nuestar_VS
SIP Transport Servers: SIP_TS_Nuestar
Proxy address: FQDN of the Nuestar_AS or Nuestar_VS (provided by Nuestar )
Port range: [Select port range of IP interface above)
--> Other settings are unchanged

5- In Profiles -> default -> Edit Reason Cause Mapping
503 Service unavailable -> Route retry action: Continue call
603 Decline -> Route retry action: Stop call
302 Moved Temporarily -> Route retry action: Process call routing

6- Add NAP information to identify the type of destination
In NAP Columns -> Create New NAP Column
Name: service_type
Type Attributes: NORMAL|AUTHENTICATION|VERIFICATION
Default: NORMAL
Save

7 - In NAP menu -> select NAP_Nuestar_AS
Service_type: AUTHENTICATION
- In NAP menu -> select NAP_Nuestar_VS
Service_type: VERIFICATION

[NicoleTan]

An example of the use case:

[zictec]

Hi, do you have a script that works with REST API ?

I need to use a variable to normalize the called and calling number to E164 with regexp ( on the script, not on routing ), and send a REST HTTP POST similar to this:


$ curl 'https://ca-authn.neustarlab.biz/ccid/authn/v2/identity?apiKey=%3CapiKey5%3E' -i
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"from" : "\"Alice\" <sip:alice@example.com>",
"to" : "\"Bob\" <sip:5715550000@example.com>"
}'

The reply would be 200 OK sucess , or 4xx, 5xx in case of failure.
Depending on the failure the should continue the call ( or drop it ).

A sucessfull response will look like this:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 510
{
"identity" :
"eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLWNtcy5uZXVzdGFybGFiLmJpejo4MDAwL2NlcnRzL2QwY2JjM2Y2YmFjMGQwYTFmNzlmNzg2YWE1NTQzYjAxIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE1NTUwMDAwIl19LCJpYXQiOjE2OTUxNDc4ODUsIm9yaWciOnsidXJpIjoic2lwOmFsaWNlQGV4YW1wbGUuY29tIn19.HVjm-trXMvzv6Ie2T7wQSYYeALZFhMMBHv4CHY2KQoSheU-NDc5qxqaikQUJFnseIWfRFLTYDfZZWQNUO_hLjA;info=<http://ca-
cms.neustarlab.biz:8000/certs/d0cbc3f6bac0d0a1f79f786aa5543b01>;alg=ES256",
"date" : "Tue, 19 Sep 2023 18:24:45 GMT"
}

This is very basic, and it's the minimum required fields to sucessfully authenticate. There are several other parameters that can be added that are optional, but let's start with the simpler ones.

And for incoming calls, I need to check if there is a Identity header on the call, if it is, I need to call the Verification Service by the same REST HTTP API, and place the headers I got on the reply to the outgoing call leg.

The more easy way is to place the entire SIP INVITE into the request like this:
With SIP INVITE Message & Response in SIP Format
This API entry point accepts SIP INVITE messages with SIP Identity headers as requests and produces responses in SIP Format. If the API client prefers full SIP INVITE messages in the responses with SIP Identity headers embedded in, the following HTTP header needs be specified in the request:

Accept: text/plain
If the verification result of SIP Identity headers has met the verification status requirement, the SIP INVITE message will be returned in the response. The returned SIP INVITE message may have the CNAM field modified if CNAM lookup operation is performed, and/or the "cnamPrefix" parameter is specified. Additionally, the returned SIP INVITE message may include a new SIP P-Asserted-Identity header if a successful ECNAM lookup operation is performed

If the verification result does not meet the verification status requirement, an error message in SIP format will be returned with proper HTTP status code, SIP code and SIP Reason header, such as:

HTTP/1.1 403 Forbidden
Content-Type: text/plain;charset=UTF-8
Content-Length: 197

SIP/2.0 437 Credential has expired
...
Reason: SIP;cause=437;text="Credential has expired"
...


The following is an example of submitting a SIP INVITE message with a SIP Identity header and full set of available URL parameters as the request and producing a new SIP INVITE message with modified CNAM field and a new SIP P-Asserted-Identity header, including "verstat" tagging on SIP From/P-Asserted-Identity headers and added SIP P-Attestation-Indicator/P-Origination-Id headers:

$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity?apiKey=%3CapiKey1%3E&status=all&origcc=1,44&destcc=1&cnam=true&ecnam=true&robocall=true&cvt=false&cnamPrefix=%E2%9C%94,%E2%9C%98&verstat=TN-Validation-Passed&identity=true' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: text/plain' \
-d 'INVITE sip:+15715550001@proxy.example.com;transport=UDP SIP/2.0
v: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
m: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
f: "alice" <sip:+15715550000@example.com>;tag=1f4e4f40
t: "bob" <sip:+15715550001@example.com>
Date: Wed, 28 Aug 2024 16:29:22 GMT
i: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
y: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxNTcxNTU1MDAwMSJdfSwiaWF0IjoxNzI0ODYyNTYyLCJta3kiOlt7ImFsZyI6IlNIQS0xIiwiZGlnIjoiNEFBREI5QjEzRjgyMTgzQjU0MDIxMkRGM0U1RDQ5NkIxOUU1N0NBQiJ9LHsiYWxnIjoiU0hBLTI1NiIsImRpZyI6IjM2M0JBRTEyOTU5NUY1OTcyREY3RTA4NEZFQ0RGMUJDQUQ3QTcwNjRGN0U3NEY3RUE2MDIwNjBFMzc1NENGRjcifV0sIm9yaWciOnsidG4iOiIxNzAzNTU1MDAwMSJ9LCJvcmlnaWQiOiIxMjM0NTYtQUJDRC05OTk5OTkiLCJyY2QiOnsibmFtIjoiQWxpY2UifX0.l2XJ_AGp0iw7CbBvPATaME4YvSm_Qcky1ZOIEFzbm2JcPqAdT7f7AEva3p5ND9f58JB9EDxoRBzVg4Ojleu68w;info=<http://ca.example.com/test.der>;alg=ES256;ppt="shaken"
P-Asserted-Identity: "Alice" <tel:+17035550001>
P-Asserted-Identity: "Alice" <sip:+17035550001@example.com>
CSeq: 2 INVITE
c: application/sdp
User-Agent: Z 3.3.25608 r25552
k: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
l: 439

v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=fingerprint:SHA-1 4A:AD:B9:B1:3F:82:18:3B:54:02:12:DF:3E:5D:49:6B:19:E5:7C:AB
a=fingerprint:SHA-256 36:3B:AE:12:95:95:F5:97:2D:F7:E0:84:FE:CD:F1:BC:AD:7A:70:64:F7:E7:4F:7E:A6:02:06:0E:37:54:CF:F7
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'


The successful response message is as below, with SIP Identity header embedded:

HTTP/1.1 200 OK
Content-Type: text/plain;charset=UTF-8
Content-Length: 2611

INVITE sip:+15715550001@proxy.example.com;transport=UDP SIP/2.0
v: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
m: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
f: "Alice In Wonderland" <sip:+15715550000;verstat=TN-Validation-Passed@example.com>;tag=1f4e4f40
t: "bob" <sip:+15715550001@example.com>
Date: Wed, 28 Aug 2024 16:29:22 GMT
i: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
P-Attestation-Indicator: A
P-Origination-Id: 123456-ABCD-999999
y: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxNTcxNTU1MDAwMSJdfSwiaWF0IjoxNzI0ODYyNTYyLCJta3kiOlt7ImFsZyI6IlNIQS0xIiwiZGlnIjoiNEFBREI5QjEzRjgyMTgzQjU0MDIxMkRGM0U1RDQ5NkIxOUU1N0NBQiJ9LHsiYWxnIjoiU0hBLTI1NiIsImRpZyI6IjM2M0JBRTEyOTU5NUY1OTcyREY3RTA4NEZFQ0RGMUJDQUQ3QTcwNjRGN0U3NEY3RUE2MDIwNjBFMzc1NENGRjcifV0sIm9yaWciOnsidG4iOiIxNzAzNTU1MDAwMSJ9LCJvcmlnaWQiOiIxMjM0NTYtQUJDRC05OTk5OTkiLCJyY2QiOnsibmFtIjoiQWxpY2UifX0.l2XJ_AGp0iw7CbBvPATaME4YvSm_Qcky1ZOIEFzbm2JcPqAdT7f7AEva3p5ND9f58JB9EDxoRBzVg4Ojleu68w;info=<http://ca.example.com/test.der>;alg=ES256;ppt="shaken"
P-Asserted-Identity: "Alice In Wonderland,Walt Disney World Resort,Orlando,FL 32830" <sip:+15715550000@example.com;tmpl=none;bn=Disney%20World;dept=Theme%20Park;lt=Wireline;st=Business;bt=Entertainment;ba=Walt%20Disney%20World%20Resort;cs=Orlando, FL;city=Orlando;state=FL;ct=US;zip=32830;wb=http://movies.disney.com/alice-in-wonderland-1951;lg=https://static-mh.content.disney.io/matterhorn/assets/goc/nav-logo-dark@2x-2b3eb08c507c.png;tg=#AliceInWonderLand;sm=%7B%22Facebook%22%3A%22https%3A%2F%2Fwww.facebook.com%2FDisneyAliceInWonderland%22%2C%22Twitter%22%3A%22https%3A%2F%2Ftwitter.com%2FDisney%22%7D;nm=Alice;fn=Alice;ln=Liddell;jt=Adventurer;hs=https://encrypted-tbn0.gstatic.com/images?q%3dtbn:ANd9GcR2Q1GWX6hdmMr2dh10SoTeEKEn4S4toc4V3yAJCrPQHlzWvr_I;cp=Customer Support;email=alice@disney.com;verstat=TN-Validation-Passed>
CSeq: 2 INVITE
c: application/sdp
User-Agent: Z 3.3.25608 r25552
k: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
l: 439

v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=fingerprint:SHA-1 4A:AD:B9:B1:3F:82:18:3B:54:02:12:DF:3E:5D:49:6B:19:E5:7C:AB
a=fingerprint:SHA-256 36:3B:AE:12:95:95:F5:97:2D:F7:E0:84:FE:CD:F1:BC:AD:7A:70:64:F7:E7:4F:7E:A6:02:06:0E:37:54:CF:F7
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv



Then we get the resulting SIP with the headers added/reformated that need to be processed and added to the outgoing NAP.


More info on: https://docs.ccid.neustar.biz/ccid/verify/docs/api-guide.html

[Sponsored content]