Verification Policies

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

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

NOTE: SHAKEN only ensures the calling number is not spoofed. SHAKEN does not determine if a call has a malicious intent. In other words, SHAKEN cannot decide if 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. Verification policies are classified by the following policy actions relating to errors that can occur during the verification process:

No Identity Header Action - The result of an error caused by no Identity token being 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 intermediate service provider stripped the SIP Identity header.
Invalid Identity Header Action - The result of an error that encompasses various Identity token and certificate related errors, described in more detail on the Verification Process page.

For each of the Action classifications, users can configure the verification policy to do one of the following to the SIP invite that generated an error:

Report only - The SIP Invite is viewable on the SIP Messages page or via email reports, which the user must set up to receive.
Block - ClearIP will return a SIP 603 response.
Divert - ClearIP will return a diversion destination in the Contact header to the SBC.
Indicate - ClearIP will return SPAM indicator in the SIP 302 response

If the Indicate action is selected, ClearIP will overwrite the current CNAM value, if one is present, with “<SPAM>” 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 the SPAM indication feature in STI verification policies is configured, then users 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, verstat, CNAM or verstat and CNAM.

None

No verification result is returned to the softswitch or SBC. If this option is chosen, there will effectively be no indication in the SIP Response that verification occurred. The user, however, can view verification results in the ClearIP SIP Messages page.

Verstat

The verification result is returned in a verstat parameter within the P-Asserted-Identity header. If this option is chosen for verification results, the value of that parameter can only be one of the following values:

TN-Validation-Passed - Attestation level is ‘A’ and verification was successful.
TN-Validation-Failed - Verification was unsuccessful.
No-TN-Validation - No Identity Header present or attestation level set to ‘B’ or ‘C’.

CNAM

If verification is successful, ClearIP will prepend a “[V]” to the CNAM value, if it exists, as shown in the SIP Response example below. In the case of verification failure, there will be no indication in CNAM and any existing CNAM value will not be overwritten.

NOTE: To enable the SPAM indicator in CNAM for verification failures, the user must configure this via either the No Identity Header Action or Invalid Identity Header Action being set to ‘Indicate’. If either action is set to ‘Indicate’, verification errors that result in either of these actions will result in the CNAM, only if present, being overwritten with “<SPAM>”. In the event of a private call where the calling party wishes to remain anonymous, if the method is set to indicate, it will set the CNAM to “<SPAM>”, not Anonymous, even though that’s how the CNAM might appear in the original SIP INVITE.

Verstat and CNAM

The verification result is returned in a verstat parameter, and the CNAM value is modified if verification is successful. Verification results will be returned via both methods, in the manner discussed above.

Viewing verification in SIP Messages

Users can review the verification results of authenticated calls that have been 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 ClearIP has retrieved the certificate recently. 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 , 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:+18554742536@sip.clearip.com:5060 SIP/2.0
Via: SIP/2.0/TCP sip.clearip.com:5060
From: <sip:+14045266060@transnexus.com:5060>
To: <sip:+18554742536@sip.clearip.com:5060>
Identity: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9jZXJ0aWZpY2F0ZXMuY2xlYXJpcC5jb20vOTk5OTk5OTktOTk5OS00OTk5LTk5OTktOTk5OTk5OTk5OTk5LzAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwLnBlbSJ9.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxODU1NDc0MjUzNiJdfSwiaWF0IjoxNTc3ODM2ODAwLCJvcmlnIjp7InRuIjoiMTQwNDUyNjYwNjAifSwib3JpZ2lkIjoiOTk5OTk5OTktOTk5OS00OTk5LTk5OTktOTk5OTk5OTk5OTk5In0.abcdefghijklmnopqrstuvwzyzABCDEFGHIJKLMNOPQRSTUVWZYZ0123456789012345678901234567890123;info=<https://certificates.clearip.com/99999999-9999-4999-9999-999999999999/00000000000000000000000000000000.pem>;alg=ES256;ppt=shaken
Call-ID: 123456
CSeq: 1 INVITE
Content-Length: 0

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/TCP sip.clearip.com:5060
From: <sip:+14045266060@transnexus.com:5060>
To: <sip:+18554742536@sip.clearip.com:5060>
P-Asserted-Identity: "[V]TransNexus" <sip:+14045266060;verstat=TN-Validation-Passed@transnexus.com:5060>
Contact: <sip:+18554742536@sip.clearip.com:5060>;q=0.99
Reason: SIP;cause=302;text="no-fraud-detected"
Call-ID: 123456
CSeq: 1 INVITE
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/TCP sip.clearip.com:5060
From: <sip:+14045266060@transnexus.com:5060>
To: <sip:+18554742536@sip.clearip.com:5060>
Contact: <sip:+18554742536@sip.clearip.com:5060>;q=0.99?P-Asserted-Identity=%22%5BV%5DTransNexus%22%20%3Csip:+14045266060;verstat=TN-Validation-Passed@transnexus.com:5060%3E
Reason: SIP;cause=302;text="no-fraud-detected"
Call-ID: 123456
CSeq: 1 INVITE
Content-Length: 0