Verification Policies

The STI 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 a PASSporT whether from the Identity header of the SIP INVITE or from the 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 PASSporT and certificate are valid. Some of the things that it checks include:

• The PASSporT has the proper format
• The information in the PASSporT 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. Please see the STI Verification Status section for detailed information on why PASSporT verification can fail.

NOTE: SHAKEN only ensures the calling number is not spoofed. SHAKEN Verification does not determine if a call is likely to be fraudulent or SPAM. 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 additional analytics functions 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 - This action will be applied when there is no Identity header or PASSporT found when it was expected. The following conditions can cause this error:

  • The originating service provider did not create the Identity header.
  • The PASSporT was not delivered to the Call Placement Service in cases where out-of-band SHAKEN is used.
  • An intermediate service provider stripped the SIP Identity header before it reached the terminating service provider.
  • The terminating service provider stripped the Identity header before it was sent to ClearIP.
  • Multiple Identity headers were included in the SIP message.
  • The Asserted Called Number does not match the Translated Called Number.

• Invalid Identity Header Action - This Action will be applied when the Identity header is invalid. An invalid Identity header occurs when an Identity header or PASSporT or certificate related error occurs. This type of error is described in more detail in the STI Verification Status section.

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 and the result of the verification is logged.
• Block - ClearIP will return a SIP 603 response.
• Divert - ClearIP will return a diversion destination in the Contact header to the SBC. If a diversion destination is not configured on the SBC, ClearIP will return a SIP 603 response.
• Indicate - ClearIP will return a SPAM indicator in the SIP 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 response. By default, CNAM values are returned in the P-Asserted-Identity header, but can be configured to be returned in other SIP headers on the SBCs page.

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 PASSporT. Users do not have to specify whether ClearIP should look for in-band or out-of-band PASSporTs.

Users can configure ClearIP to return in-band SIP Identity headers in the SIP response after ClearIP receives out-of-band PASSporTs 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 PASSporT 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.

Called Number

A Verification Policy can be matched to a prefix for an Asserted Called Number, or the Called Number field can be left blank for the Verification Policy to apply to any Asserted Called Number. For STI Verification Policies, the prefix refers to the Asserted Called Number regardless of whether the number has been ported.

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 the STI Verification Status 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 or PASSporT present or attestation level set to ‘B’ or ‘C’.

CNAM

If verification is successful with Attestation level A, 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 unless Privacy is requested. Information on how Privacy is determined can be found at Analytics -> SIP Messages -> Privacy. If Privacy is requested, the existing CNAM value will be overwritten and the display name returned will be “[V]ANONYMOUS”.

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 setting by choosing ‘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

This parameter has two values, Yes or No, and determines whether or not rich call data (RCD) claims in a verified SHAKEN PASSporT will be returned in the SIP response.

The following is an example of a SHAKEN PASSporT with rich call data claims.

{
  "header": {
    "alg": "ES256",
    "ppt": "shaken",
    "typ": "passport",
    "x5u": "https://certificates.clearip.com/99999999-9999-4999-9999-999999999999/00000000000000000000000000000000.pem"
  },
  "payload": {
    "attest": "A",
    "crn": "Requested Callback[JD1.1]",
    "dest": {
      "tn": [
        "18554742536"
      ]
    },
    "iat": 1577836800,
    "orig": {
      "tn": "14045266060"
    },
    "origid": "99999999-9999-4999-9999-999999999999",
    "rcd": {
      "icn": "https://rcd.clearip.com/example.bmp",
      "nam": "TransNexus"
    },
    "rcdi": {
      "/icn": "sha256-0000000000000000000000000000000000000000000"
    }
  },
  "signature": "abcdefghijklmnopqrstuvwzyzABCDEFGHIJKLMNOPQRSTUVWZYZ0123456789012345678901234567890123"
}

If this value is set to Yes, ClearIP will return the following RCD claims if they are present:

• crn - Call reason
• icn – URL where the logo of the calling party can be fetched
• nam – Caller Name that will be added to the display name of the P-Asserted-Identity header
• rcdi – RCD integrity claim to verify that the logo has not changed since the PASSporT was signed.

The following SIP headers provide an example of how RCD claims are returned in a SIP 302 response from ClearIP.

P-Asserted-Identity: "TransNexus[JD2.1]" <sip:14045266060;verstat=TN-Validation-Passed@example.com>
Call-Info: <https://rcd.clearip.com/example.bmp>;purpose=icon;verified=true;integrity=sha256-0000000000000000000000000000000000000000000;call-reason="Requested Callback"

Important Points for returning RCD claims

1. If a CNAM Policy is enabled, setting the Return Rich Call Data Claims parameter to Yes will override the CNAM policy. ClearIP will return the Branded Calling ID name as the display name in the P-Asserted-Identity and will skip the CNAM lookup.
2. If Return Rich Call Data Claims is set to Yes, ClearIP will return RCD claims in a SIP message even if the STI Verification Policy Indication Method is set to None. If the Indication Method is set to None, the ClearIP user should make certain their SBC is configured to accept SIP messages from ClearIP.

Important: Service providers who display verified Branded Calling ID Rich Call Data to the called party will avoid CNAM query fees and can receive payments from BCID LLC. Contact your TransNexus representative for more information.

Viewing verification in SIP Messages

Users can review the verification results of verified 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 the verified call.
• STI Verification Origination Identifier - The origid value of the verified call.
• STI Verification Certificate Repository Domain - The domain name of the certificate repository included in the PASSporT.
• 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 from its cache. When ClearIP retrieves a certificate, ClearIP makes a temporary local copy of the certificate to reference again quickly.

Investigating the Identity Header of SIP Messages

If you received an authenticated call and you want to contact the service provider who authenticated it:

Find the Call

First, find the suspected call in the Analytics -> SIP Messages section of ClearIP. There could be several calls with matching calling and called numbers around the same time, so be sure to identify the exact call in question.

Checking STI Verification Status

Once the call in question is found, check to see if ClearIP verified the call in question. The first thing to do is to check the STI Verification Status. If the Verification Status is not “Successful” then the call was handled based on the Action configured in the STI Verification Policy.

If the Verification Status is “Successful” then the next step is to investigate who authenticated the call. The table below describes each piece of information and where you can get it:

You can follow the procedures below to find the necessary information and send the information to the correct originating service provider.

Finding the Organization Name of the Originating Service Provider

ClearIP users can view the parsed certificate to see which organization signed the call.

1. Find the call in question in SIP Messages.
2. Click on the “Show” button on the far right.
3. Click on the “STI Verification” tab.
4. Scroll down to the “Parsed STI Verification Certificate” section.
5. Find the Organization in the Decoded STI Verification Token
6. Find the Organization in the Parsed STI Verification Certificate. Look for the value of “organization” in the “subject” section. That is the name of the owner of the certificate which was used to authenticate the call. The “organization” in the “issuer” section is the Certificate Authority which provided the certificate, not the entity which used the certificate to authenticate the call.
7. The contact information for that organization should be available in the FCC’s Robocall Mitigation Database. If you need assistance finding the contact information for an organization, please reach out to your contacts at the Robocall Mitigation Database.

Finding the Decoded STI Verification Token

1. Find the call in question in SIP Messages.
2. Click on the “Show” button on the far right.
3. Click on the “STI Verification” tab.
4. The decoded PASSporT is visible in the “Decoded STI Verification Token” section.
5. Originating service providers should be able to find the call in question using the Decoded STI Verification Token.

You can then use that information to contact the originating service provider with any questions you may have.

STI Verification Status

Status And Action

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

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 use, 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 ClearIP could not process the Identity header because it was not formatted per 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 PASSporT 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 able to be parsed
• The token payload was not able to be parsed

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 an authenticated SIP INVITE, 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.

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="Moved Temporarily"
Call-ID: 123456
CSeq: 1 INVITE
Content-Length: 0

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

ClearIP can also be configured to send a SIP response with the P-Asserted-Identity header 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="Moved Temporarily"
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, payload, and signature from the PASSporT. 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