Verification Process

Introduction

Understanding how the verification process works in ClearIP can help users with setting up appropriate policies and troubleshooting.

As explained in the Verification Policies page, ClearIP checks the following during the verification process, and a verification error will occur if at least one is not correct:

  • 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.

This page will break down the above checks in the order they occur during the verification process, as well as cover verification error handling (policy action configuration) and common questions that can arise during verification setup.

1. Same-Call Authentication & Identity Header Check

The verification process begins with ClearIP checking if it also authenticated the call. If ClearIP did authenticate the call, it will generate and retrieve the Identity Header from the SHAKEN authentication process.

If ClearIP did not authenticate the call, it will then look to the SIP Invite from the Originating Service Provider. If there is no identity header present, ClearIP will check the validity of the Asserted Calling and Asserted Called numbers from the From and To headers respectively to determine if retrieving an out-of-band token for verification is possible. If these numbers are valid, ClearIP will use the out-of-band token for verification. If they are not valid, then ClearIP will take the No Identity Header Action that the user has configured in the verification policy.

NOTE: There can be multiple reasons why a SIP Invite might not have an Identity Header:

  • The call was not authenticated by the Originating Service Provider
  • The call traveled through TDM networks, and the identity header was removed

In the case of a call not being authenticated by an Originating Service Provider, it is likely that the identity token was not created or not delivered.

In the case of the call traveling through TDM networks, it is likely that the identity header was stripped while passing through an intermediary service provider.

2. Identity Header/Token Format

The verification service checks the format and contents of the Identity header and PASSporT token to ensure every required parameter is present and contains a value. The following format issues correspond to the respective verification error action that the user configures:

  • If header length is too long/short, the Invalid Identity Header Action is taken.
  • If there are multiple identity headers, the No Identity Header Action is taken.
  • If the identity header format splitting on semicolons fails, the Invalid Identity Header Action is taken.
  • If the token format (in the ‘Identity’ section of the SIP Request) is incorrect, the Invalid Identity Header Action is taken.

It is important to keep the above in mind when configuring verification policies or troubleshooting, as specific formatting issues within the Identity header and token relate to the verification policy actions that must be configured.

3. Called Number Verification

ClearIP performs multiple checks to ensure that all the information in the SIP request is correct; the first of these checks is to verify that the Requested Called Number is both valid and matches the Asserted Called Number.

Requested Called Number vs. Asserted Called Number

The Requested Called Number is retrieved from the request URI, shown below. Called number translation rules are applied to the Requested Called Number to get the Translated Called Number, which is the Requested Called Number normalized into E.164.

INVITE sip:+17187171131@sip.clearip.com;transport=tcp SIP/2.0

The Asserted Called Number is taken from the To header, after having applied called number translation rules.

To: <sip:+17187171131@sip.clearip.com;transport=tcp>

To pass verification, the Asserted Called Number must match the Translated Called Number. If they do not match, ClearIP will skip verification and take the No Identity Header Action.

4. Parameter Check

The next step of the verification process is to check the identity header parameters. If the info, alg and/or ppt parameters are missing or incorrect, ClearIP will take the Invalid Identity Header Action.

NOTE: The alg parameter must be ES256, and the ppt parameter must be ‘shaken’.

Identity: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9jZXJ0aWZpY2F0ZXMuY2xlYXJpcC5jb20vNGE4NzFjMDYtZTBiNS00Y2I5LTgzNDctNDMxMjZiZDg2Yzg1LzNlMDRmZDRlZDAwMzJhYmJlY2ZjZmZiOWQwM2I3MzFkLmNydCJ9.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxNzE4NzE3MTEzMSJdfSwiaWF0IjoxNTg1MTY2OTQyLCJvcmlnIjp7InRuIjoiMTIwMTM3NzYwNTEifSwib3JpZ2lkIjoiNGFlYzk0ZTItNTA4Yy00YzFjLTkwN2ItMzczN2JhYzBhODBlIn0.0U6T10zllPOc29GGCj6OIaPmPB-v-kybRzzZ-O6T0Qp1bRJacqAlKBSex4YcaBpR3TbLcswGK3fH56Zl8XYwcw;info=<https://certificates.clearip.com/4a871c06-e0b5-4cb9-8347-43126bd86c85/3e04fd4ed0032abbecfcffb9d03b731d.crt>;alg=ES256;ppt=shaken

5. JSON Web Token Decoding

As part of the verification process, the JSON Web Token is decoded to separate the header from the payload and signature. The decoded JWT is then used for additional verification checks. Below is an example of the decoded payload:

DECODED HEADER

{
  "alg": "ES256",
  "ppt": "shaken",
  "typ": "passport",
  "x5u": "https://certificates.clearip.com/4a871c06-e0b5-4cb9-8347-43126bd86c85/3e04fd4ed0032abbecfcffb9d03b731d.crt"
}

DECODED PAYLOAD

{
  "attest": "A",
  "dest": {
    "tn": [
      "17187171131"
    ]
  },
  "iat": 1585166942,
  "orig": {
    "tn": "12013776051"
  },
  "origid": "4aec94e2-508c-4c1c-907b-3737bac0a80e"
}

SIGNATURE

0U6T10zllPOc29GGCj6OIaPmPB-v-kybRzzZ-O6T0Qp1bRJacqAlKBSex4YcaBpR3TbLcswGK3fH56Zl8XYwcw

6. Decoded JWT Checks

Once decoded, the contents of the header and payload are used to continue the verification process.

From the header, there are various checks on the x5u value, of which the first and most important is to check the info parameter against the x5u. If they do not match, the Invalid Identity Header Action is taken.

From the payload, the following checks occur:

  • Check the attestation level (attest) is not empty and has a value of A, B, or C
  • Check origid is not empty and not malformed
  • Check iat is is not empty and not malformed
  • Check that the date and time indicated in the iat parameter is not earlier than 60 seconds before the time of verification.
  • Check orig is not empty
  • Check dest is not empty

Failure on any of the above will result in the Invalid Identity Header Action being taken.

Once it is determined that orig and dest in the payload are not empty, they are used to verify called and calling number assertions.

ClearIP will get the Asserted Calling Number from one of these headers in order of priority, and apply translation rules if applicable:

  • P-Asserted-Identity: ClearIP will first look to the P-Asserted Identity header for the Asserted Calling Number.
  • From: ClearIP will only get the Asserted Calling Number via the From header if the P-Asserted Identity is not present or malformed.

The Asserted Calling Number must match the orig parameter in the decoded payload. The Asserted Called Number must match the dest payload parameter. If either does not match, then the Invalid Identity Header Action will be taken.

7. Certificate Verification

The next step in the verification process is to retrieve and verify that the certificate from the Originating Service Provider is valid and trusted.

ClearIP will send a request to the OSP’s certificate repository to get a copy of the certificate. If it cannot get the certificate, the Invalid Identity Header Action is taken.

If the certificate is successfully retrieved, the following are some of the notable checks completed to ensure its validity:

  • The expiration date and time have not passed.
  • The issuing certificate authority is currently valid according to a list of approved certificate authorities compiled by the SHAKEN policy administrator.
  • The certificate authority signature on the originating provider’s certificate is verified with the certificate authority’s public key.

If any of the above fail, verification has failed, and the Invalid Identity Header Aciton is taken.

8. Verification Results

The final step of the verification process is to send verification results in the SIP Response to the terminating service provider’s softswitch or SBC, if the user has configured ClearIP to do so. There are a few things to note about each of the indication methods the user has the option to configure to communicate verification results.

None

If the user has chosen to not to send verifications results to the terminating service provider’s softswitch or SBC, 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

If the user has chosen to send verification results via the verstat parameter in the P-Asserted Identity header in the SIP Response, 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 the user has chosen to indicate verification via CNAM value in the SIP Response, the user can choose to prepend a [V] to the CNAM value in the case of successful verification, and/or set the CNAM value to <SPAM> in the case of verification failure.

The user can choose to configure the CNAM successful verification only ([V] indicator), = for verification failure only (<SPAM> indicator) or both ([V] prepend when successful and <SPAM> replacement when failed). In any case, it is important to keep in mind that this verification indicator only represents the result of the verification process outlined; it does not necessarily speak to the nature of the call.