Verification Policies

Introduction

The Verification Policies feature allows users to choose which calls to verify using STIR/SHAKEN and how to respond to verification errors.

The terminating provider is responsible for checking for the presence of an Identity token whether in the SIP Invite or call placement service, validating the originating provider’s certificate, and verifying the signature. The verification results whether successful or not are communicated to the terminating provider’s SBC or softswitch. If verification fails, an error response is also returned to the originating provider.

During the verification process, ClearIP checks that the SIP Identity token and certificate are valid. It checks that:

  • The Identity header and/or token have the proper format
  • The information in the Identity token matches with the information in the overall SIP invite
  • The signature belongs to the originating service provider
  • The certificate is trusted
  • And more.

A verification error occurs if at least one of the things listed above is not correct.

Note: SHAKEN by itself does not determine if a call has a malicious intent. In other words, SHAKEN cannot decide that a call is likely to be fraudulent or spam. A call’s risk for being fraudulent or spam can be evaluated through an additional analytics function such as ClearIP’s Fraud Control, Shield Database, or Reputation Policies in conjunction with the use of SHAKEN.

Setup

Verification policies can be applied to an SBC, service provider, group, user, and/or called number. The verification process looks for three classes of errors relating to the SIP Identity token and certificate:

  • No Identity Header Error - No Identity token was found when it was expected. Either the originating service provider did not create the Identity token, the Identity token was not delivered to the call placement service, or an intermediary service provider stripped the SIP Identity header.
  • Invalid Identity Header Error - An error that is not covered by the above two errors occurs.

For different possible errors, users can configure the verification policy to block, divert, or only report the SIP invite that generated an error.

If the indicated action is selected for the No Identity Header Error and Invalid Identity Header Error, ClearIP will overwrite the current CNAM value, if one is present, with and return it in the SIP 302 response. By default, CNAM values are returned in the P-Asserted-Identity header, but this can be configured.

If a ClearIP user configures the SPAM indication feature in STI verification policies, then he or she should ensure that any CNAM provisioning or modification functions external to ClearIP take place before the call is sent to ClearIP so that the SPAM indication is not overwritten.

If verification is requested, ClearIP automatically checks the SIP Invite for the Identity header and checks the call placement service for a token. Users do not have to specify whether ClearIP should look for in-band or out-of-band identity tokens.

Users can configure ClearIP to return in-band SIP Identity headers in the SIP response after ClearIP receives out-of-band tokens in its Call Placement Service. If the verification policy is configured with the Return Out-Of-Band Token field set to Yes, then for a given call ClearIP checks if a token with a matching calling and called number exists in the Call Placement Service. If so, then ClearIP converts the out-of-band token into an Identity header and returns the Identity header in the SIP response.

Indication method

ClearIP returns the verification result to the terminating service provider’s softswitch or SBC. Users can specify how that result is communicated:

  • None - No verification result is returned to the softswitch or SBC. The verification result is viewable in the SIP Messages page.
  • Verstat - The verification result is returned in a verstat parameter within the P-Asserted-Identity header. The value can indicate that verification is successful or failed.
  • CNAM - A successful verification is indicated by modifying the existing CNAM value (if it exists) by prepending a [V] as shown in the SIP Response example below. A failed verification is not indicated in CNAM and does not modify the existing CNAM value.
  • Verstat and CNAM - The verification result is returned in a verstat parameter, and the CNAM value is modified if verification is successful.

Viewing verification in SIP Messages

Users can review the verification results of authenticated calls that have received by going to the SIP Messages page, clicking on the Columns button, and selecting the STI Verification option to only see column headers related to verification:

  • STI Verification Status - Whether the verification was successful or not. If there is an error, the specific error is listed.
  • STI Verification Attestation Indicator - The attestation level of an authenticated call that is received.
  • STI Verification Origination Identifier - The origid value of an authenticated call that is received.
  • STI Verification Certificate Repository Domain - The domain name of the certificate repository included in the identity token.
  • STI Verification Certificate Latency - The time in milliseconds needed to retrieve the certificate. The latency is zero for certificates that have been cached.
  • STI Verification Certificate Cached - Whether or not ClearIP has retrieved the certificate recently before. When ClearIP retrieves a certificate, ClearIP makes a temporary local copy of the certificate to reference again quickly.

SIP Identity header

To look at the SIP Identity header included in a signed SIP invite received previously, go to the SIP Messages page and locate the SIP message for the call in which you are interested. It may be helpful to filter calls by STI Verification Status. Click on the blue Show button corresponding to the desired SIP message under the Show Message column.

Scroll down to find the SIP Request which looks like the image below. This is the request sent to ClearIP from the SBC. The SIP request displays the SIP invite with the Identity header.

SIP Request

INVITE sip:+17187171131@sip.clearip.com;transport=tcp SIP/2.0
Via: SIP/2.0/TLS sip.clearip.com:5061;branch=z9hG4bKb6c4.8a2399fe3de18f587042c29685f8c0f0.0;i=09ffd4d2;received=::ffff:10.0.12.110
Via: SIP/2.0/TCP 192.168.1.200;received=52.207.147.53;branch=z9hG4bKKeFBHX3gDjZDN
Max-Forwards: 65
From: "Alice" <sip:+12013776051@192.168.1.200>;tag=rXmHFjHyDpSre
To: <sip:+17187171131@sip.clearip.com;transport=tcp>
Call-ID: 4fd9d329-e977-1238-33b9-12ab5f1d9310
CSeq: 18029679 INVITE
Content-Length: 222
Identity: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9jZXJ0aWZpY2F0ZXMuY2xlYXJpcC5jb20vNGE4NzFjMDYtZTBiNS00Y2I5LTgzNDctNDMxMjZiZDg2Yzg1LzNlMDRmZDRlZDAwMzJhYmJlY2ZjZmZiOWQwM2I3MzFkLmNydCJ9.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxNzE4NzE3MTEzMSJdfSwiaWF0IjoxNTg1MTY2OTQyLCJvcmlnIjp7InRuIjoiMTIwMTM3NzYwNTEifSwib3JpZ2lkIjoiNGFlYzk0ZTItNTA4Yy00YzFjLTkwN2ItMzczN2JhYzBhODBlIn0.0U6T10zllPOc29GGCj6OIaPmPB-v-kybRzzZ-O6T0Qp1bRJacqAlKBSex4YcaBpR3TbLcswGK3fH56Zl8XYwcw;info=<https://certificates.clearip.com/4a871c06-e0b5-4cb9-8347-43126bd86c85/3e04fd4ed0032abbecfcffb9d03b731d.crt>;alg=ES256;ppt=shaken
X-Real-Ip: 52.207.147.53

Below the SIP Request, you can find the SIP Response. The response includes information about any possible verification errors that were found.

SIP Response

SIP/2.0 302 Moved Temporarily
Via: SIP/2.0/TLS sip.clearip.com:5061;branch=z9hG4bKb6c4.8a2399fe3de18f587042c29685f8c0f0.0;i=09ffd4d2;received=::ffff:10.0.12.110
Via: SIP/2.0/TCP 192.168.1.200;received=52.207.147.53;branch=z9hG4bKKeFBHX3gDjZDN
To: <sip:+17187171131@sip.clearip.com;transport=tcp>;tag=306edb03-2ca8-47fc-bff3-6e79ddfa2cf7
From: "Alice" <sip:+12013776051@192.168.1.200>;tag=rXmHFjHyDpSre
Call-ID: 4fd9d329-e977-1238-33b9-12ab5f1d9310
CSeq: 18029679 INVITE
P-Asserted-Identity: "[V]Alice" <sip:12013776051;verstat=TN-Validation-Passed@192.168.1.200>
Contact: <sip:17187171131@sip.clearip.com>;q=0.99
Reason: SIP;cause=302;text="no-fraud-detected"
Content-Length: 0

By default, the modified CNAM and verstat values are returned in the P-Asserted-Identity header of the SIP 302 response. The SBC or softswitch must be configured to copy the modified CNAM and/or verstat parameter into the SIP INVITE sent from the softswitch to the subscriber.

ClearIP can also be configured to send a SIP 302 response with the CNAM embedded in the Contact header if preferred.

SIP/2.0 302 Moved Temporarily
Via: SIP/2.0/TLS sip.clearip.com:5061;branch=z9hG4bK8472.eec5ea4106a4437d534bbc8d01e74812.0;i=234a06e5;received=::ffff:10.0.11.242
Via: SIP/2.0/TCP 35.153.225.168;received=35.153.225.168;rport=50791;branch=z9hG4bK1F1gpvF03vveS
To: <sip:+17187171131@sip.clearip.com;transport=tcp>;tag=750802c3-8062-4ef8-ac42-4b267cf84c1c
From: "Alice" <sip:+12013776051@35.153.225.168>;tag=7rvypmtp21B0e
Call-ID: 3c7ab9c0-ea1b-1238-16a0-126d9ce6b6ba
CSeq: 18064881 INVITE
Contact: <sip:+17187171131@clearip-demo.pstn.us1.twilio.com:5061;transport=tls>;q=0.99?P-Asserted-Identity=%22ALICE%22%20%3Csip%3A12013776051%4035.153.225.168%3E
Reason: SIP;cause=302;text="no-fraud-detected"
Content-Length: 0