ClearIP Documentation

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.

Return Rich Call Data Claims

Whether or not rich call data claims will be returned in the SIP response.

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.

STI Verification Status

Status And Action

The following table describes which STI Verification Policy action is followed for each STI Verification Status:

STI Verification StatusSTI Verification Policy Action
No Verification Requestednone
Successfulnone
No Identity HeaderNo Identity Header Action
all other statusesInvalid Identity Header Action

No Verification Requested

The “No Verification Requested” status means that a ClearIP STI Verification Policy did not match for the SIP message, or that the matching Verification Policy was disabled.

No Identity Header

The “No Identity Header” status can mean one of three things:

  • No identity header was included in the SIP message.
  • Multiple identity headers were included in the SIP message. ClearIP is unsure which to pick, and so it classifies the SIP message just like it would with a missing identity header.
  • The Asserted Called Number does not match the Translated Called Number.

Malformed Identity Header

The “Malformed Identity Header” status means that the identity header was not parsable according to the standards.

Invalid Parameter info

The “Invalid Parameter Info” status can mean one of two things:

  • The info parameter was found but was not properly formatted
  • The info parameter was found but did not match the value in the token header’s x5u.

Invalid Parameter alg

The “Invalid Parameter alg” status can mean one of two things:

  • The alg parameter was found but was not properly formatted
  • The alg parameter was found but the value did not match ES256 (without quotes) or “ES256” (with quotes)

Invalid Parameter ppt

The “Invalid Parameter ppt” status can mean one of two things:

  • The ppt parameter was found but was not properly formatted
  • The ppt parameter was found but the value did not match SHAKEN (without quotes) or “SHAKEN” (with quotes)

Malformed Token

The “Malformed Token” status can mean one of two things:

  • The token header was not parsable
  • The token payload was not parsable

Malformed Certificate Repository

The “Malformed Certificate Repository” status is no longer used.

Invalid Token Attestation Indicator

The “Invalid Token Attestation Indicator” status can mean one of two things:

  • The attest value is missing from the token payload
  • The attest value is not A, B, or C

Invalid Token origid

The “Invalid Token origid” status can mean one of two things:

  • The origid value is missing from the token payload
  • The origid value uses characters that do not follow the standards

Invalid Token iat

The “Invalid Token iat” status can mean one of three things:

  • The iat value is missing from the token payload
  • The iat value is not a number
  • The iat time is too old or too far in the future

Invalid Token orig

The “Invalid Token orig” status can mean one of two things:

  • The orig.tn value is missing from the token payload
  • The orig.tn value does not contain a string of numeric characters

Invalid Token dest

The “Invalid Token dest” status can mean one of three things:

  • The dest.tn value is missing from the token payload
  • The dest.tn value is not an array
  • The dest.tn array does not contain a string with only numeric characters

Invalid Token x5u

The “Invalid Token x5u” status can mean one of three things:

  • The x5u value is missing from the token header
  • The x5u value does not start with https
  • The x5u value contains invalid characters

Invalid Token alg

The “Invalid Token alg” status can mean one of two things:

  • The alg value is missing from the token header
  • The alg value does not equal ES256

Invalid Token ppt

The “Invalid Token ppt” status can mean one of two things:

  • The ppt value is missing from the token header
  • The ppt value does not equal shaken

Invalid Token typ

The “Invalid Token typ” status can mean one of three things:

  • The typ value is missing from the token header
  • The typ value does not equal passport

Calling Number Mismatch

The “Calling Number Mismatch” status means that the token’s payload.orig.tn value does not match the Asserted Calling Number

Called Number Mismatch

The “Called Number Mismatch” status means that the token’s payload.dest.tn value does not match the Asserted Called Number

Certificate Repository Error

The “Certificate Repository Error” status means that there was a problem in retrieving the certificate chain from the token’s header.x5u

Certificate Error

The “Certificate Error” status is no longer used.

Certificate Chain Error

The “Certificate Chain Error” status means that there was a problem in verifying the certificate chain

Invalid Token Signature

The “Invalid Token Signature” status means that ClearIP was unable to verify the token’s signature against the certificate chain

Successful

The “Successful” status means that STI Verification was successful

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

Decoded STI Verification Token

To see the decoded STI Verification Token for a particular SIP Message, click the “Show” button in the “Show Message” column. Then click on the “STI Verification” tab. This tab shows the decoded header, decoded payload, and signature. The token must conform to the following structure in order to successfully verify a SIP request:

Decoded Header
{
  "alg": "ES256",
  "ppt": "shaken",
  "typ": "passport",
  "x5u": "https://certificates.clearip.com/99999999-9999-4999-9999-999999999999/00000000000000000000000000000000.pem"
}
Decoded Payload
{
  "attest": "A",
  "dest": {
    "tn": [
      "18554742536"
    ]
  },
  "iat": 1577836800,
  "orig": {
    "tn": "14045266060"
  },
  "origid": "99999999-9999-4999-9999-999999999999"
}
Signature
abcdefghijklmnopqrstuvwzyzABCDEFGHIJKLMNOPQRSTUVWZYZ0123456789012345678901234567890123
Verification Policies