ClearIP Documentation

Verification Process

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 that will be discussed on this page.

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.

Identity Header Check

The verification process begins with ClearIP checking for the presence of an Identity Header. ClearIP determines the Identity Header to use for verification by the following logic:

  • Same-Call Authentication - If ClearIP authenticated the call, it will generate and retrieve the Identity Header from the SHAKEN authentication process.*
  • SIP Invite from Originating Service Provider - If ClearIP did not authenticate the call, it will then look to the SIP Invite from the Originating Service Provider.
  • Out-of-Band Token - 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 retrieving the out-of-band token is not possible, then ClearIP will take the No Identity Header Action that has been 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 intermediate service provider.

* Same-call authentication refers to a specific scenario in which the Originating Service Provider is also the Terminating Service Provider, and ClearIP is being used for both authentication and verification of the same call (i.e. a call within the same network).

Identity Header and 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 there are multiple identity headers, the No Identity Header Action is taken.
  • If header length is too long/short, the Invalid Identity Header Action is taken.
  • 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 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, because these specific formatting issues within the Identity header and token result in these specific verification policy actions being taken.

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:+18554742536@sip.clearip.com:5060 SIP/2.0

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

To: <sip:+18554742536@sip.clearip.com:5060>

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.

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: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9jZXJ0aWZpY2F0ZXMuY2xlYXJpcC5jb20vOTk5OTk5OTktOTk5OS00OTk5LTk5OTktOTk5OTk5OTk5OTk5LzAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwLnBlbSJ9.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxODU1NDc0MjUzNiJdfSwiaWF0IjoxNTc3ODM2ODAwLCJvcmlnIjp7InRuIjoiMTQwNDUyNjYwNjAifSwib3JpZ2lkIjoiOTk5OTk5OTktOTk5OS00OTk5LTk5OTktOTk5OTk5OTk5OTk5In0.abcdefghijklmnopqrstuvwzyzABCDEFGHIJKLMNOPQRSTUVWZYZ0123456789012345678901234567890123;info=<https://certificates.clearip.com/99999999-9999-4999-9999-999999999999/00000000000000000000000000000000.pem>;alg=ES256;ppt=shaken

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/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

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 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 the Asserted Called Number and the Asserted Calling Number.

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.

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 Action is taken.

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 ClearIP has been configured to do so. For more information on the indication methods available for returning verification results, please read the Indication Method section of the Verification Policies page

Verification Process