The Authentication Policies feature allows users to choose which phone calls should be authenticated using STIR/SHAKEN and how the authentication should be done. By default, calls are not authenticated.
The originating provider is responsible for attesting to each call leaving their network by determining which calls are made from legitimate calling numbers through the originating provider’s own criteria and then configuring their policies with the appropriate attestation level.
For call authentication, ClearIP generates a PASSporT token for a call which can be returned as an Identity header in a SIP 302 response or directly sent out-of-band to a call placement service.
Setup
Only outbound calls should be authenticated. Authentication policies can be applied to an Operator, SBC, service provider, group, user, calling SPID, and/or calling number.
Calling SPID
The Calling SPID refers to the porting corrected OCN. If your organization owns number blocks registered with their OCN, then you can create an authentication policy to sign all calls with a calling number registered to your OCN. If any numbers are ported out from your OCN, then calls from those numbers are automatically not authenticated using this policy. ClearIP directly access the NPAC database for number portability data, so you do not need to be manually update ClearIP with numbers ported in or out.
Method
ClearIP can perform call authentication in-band, out-of-band, or both in-band and out-of-band for a single call. Users can select the preferred method of authentication:
- In-Band - ClearIP creates a PASSporT token containing a reference to the originating service provider’s certificate. The PASSporT token is returned in the SIP 302 response as a SIP Identity header. This SIP Identity header must be copied and inserted into the SIP Invite delivered to the terminating service provider. ClearIP can return the Identity header value in the SIP response as an Identity header, X-Identity header, or Identity header embedded in the Contact header. This is configurable per SBC in the SBCs page.
- Out-of-Band - ClearIP creates a PASSporT token containing a reference to the originating service provider’s certificate. This PASSporT token is encrypted and delivered to the terminating service provider’s call placement service if it is listed in the Call Placement Services page. The call is routed to the terminating service provider over the voice network (TDM or IP). The delivery of the PASSporT token is independent of the call routing and does not impact the call signaling.
- In-Band and Out-of-Band - ClearIP creates a PASSporT token which is both returned in the SIP 302 response as a SIP Identity header and is delivered to the terminating service provider’s call placement service.
Action
- Ignore - Does not authenticate the call, but continues to route the call.
- Attest - Authenticates the call with an attestation level of A, B, or C.
- Block - Stops the call from being routed, returns a SIP 603 Decline.
Attestation level
Every PASSporT token created for an authenticated call includes an attestation level which is set by the originating service provider. The attestation level serves as an indication of how well the originating service provider trusts the calling party. It is a combination of familiarity with the customer making the call and the telephone number being asserted. There are three levels of attestation that an originating service provider can choose when authenticating a call:
Attestation Level A
An attestation level of A denotes Full Attestation. This means that the originating service provider:
- Is responsible for the origination of the call onto the VoIP network.
- Has a direct authenticated relationship with the customer and can identify the customer.
- Has established a verified association with the telephone number used for the call.
The originating service provider indicates that an identifiable caller is authorized to assert a calling number according to the service provider’s own policy. For example, calls from a subscriber using their registered phone number can be authenticated with attest A.
Attestation Level B
An attestation level of B denotes Partial Attestation. This means that the originating service provider.
- Is responsible for the origination of the call onto the VoIP network.
- Has a direct authenticated relationship with the customer and can identify the customer.
- Has NOT established a verified association with the telephone number being used for the call.
The originating service provider cannot confirm that an identifiable caller is authorized to assert a calling number according to the service provider’s own policy. For example, a call comes from behind a PBX, and the originating service provider does not control phone number registration directly. The highest attestation level the originating service provider can authenticate the call with attest B.
Attestation Level C
An attestation level of C denotes Gateway Attestation. This means that the originating service provider:
- Is the entry point of the call onto its VoIP network.
- Has no relationship with the initiator of the call (e.g., international gateways).
For example, the originating service provider is a wholesale carrier that provides authentication and verification services to retail service providers. A call from a retail service provider’s subscriber can be authenticated by the wholesale carrier with attest C.
If the call is forwarded and the Diversion header is present in the SIP Invite, the attestation level is automatically set to C regardless of the attestation level selected in the Action. In the SIP Messages page, you can confirm whether the call has a Diversion header by checking whether the Forwarded field is set to Yes or No.
Origid
The PASSporT token includes an origid which is a unique value that is linked to the call source and can be used for traceback. The origid has the format of a universally unique identifier (UUID) like this example: 99999999-9999-4999-9999-999999999999.
The origid can typically be generated by ClearIP, but customers also have the option to configure their network equipment to directly provide the desired origid values.
The Origination Identifier Algorithm field determines how ClearIP generates the origid. The default value for this field is Random, so ClearIP generates a new origid for each phone call.
You also have the option to set the algorithm value to Automatic. If this is configured and the attestation level is A, then the origid is set to consistently be the ClearIP Operator ID. If the attestation level is B or C, then the origid is set to consistently be the ClearIP User ID.
User-supplied Attestation and Origid
By default, ClearIP assigns an Attestation level to a call based on the configured Action of the authentication policy and generates the Origid. Alternatively, users have an option to supply their own desired Attestation level by inserting a Attestation-Info header in the SIP Invite and setting the Use Attestation Info Header field to Yes.
Similarly, users can choose to supply their own desired Origid values by inserting the Origination-Id header with a valid UUID in the SIP Invite and setting the Use Origination Id Header field to Yes.
If the supplied Attestation-Info or Origination-Info values are invalid, then ClearIP will ignore the invalid Attestation-Info or Origination-Info headers, and assign the attestation level and origid based on the next best match configured authentication policy.
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>
Attestation-Info: A
Origination-Id: 99999999-9999-4999-9999-999999999999
Call-ID: 123456
CSeq: 1 INVITE
Content-Length: 0
Certificate
Calls must be authenticated using a specific certificate.
If your organization has been approved by the STI-PA, then you must have created a certificate in the Certificates page, so that you can select that certificate in this field.
Examples
Sign all calls with Attest A
The easiest way to authenticate your calls is to sign all calls with attest A regardless of the calling number. This can be done by leaving the Calling SPID and Calling Number fields blank to denote a wildcard entry. This can be used if it is impossible for any of your subscribers to spoof their calling number if, for instance, you operate a class 5 switch.
On-premises PBX Customer
A user called 1st National Bank is defined by their on-premises PBX IP address. From the authentication policies, all phone calls made from the 1st National Bank using their assigned phone numbers are automatically authenticated with attest A. The user has chosen to authenticate calls both in-band and out-of-band. Any calls coming from the 1st National Bank with a different calling number than the assigned numbers are signed with attest B.
| User | Calling Number | Method | Action | Certificate | Comment |
|---|---|---|---|---|---|
| 1st National Bank | Out-of-Band | Attest B | SHAKEN Authentication Demo X745 | Attest B all calls from this user made with a calling number not assigned to this user | |
| 1st National Bank | 12012104111 | Out-of-Band | Attest A | SHAKEN Authentication Demo X745 | Calling number assigned to this customer |
| 1st National Bank | 12012104152 | Out-of-Band | Attest A | SHAKEN Authentication Demo X745 | Calling number assigned to this customer |
Sign list of trusted numbers
ClearIP can be used to only authenticate calls with a calling number that can be found in a list of trusted calling numbers. This list can be maintained by manually by users or automatically through the ClearIP API.
| Calling Number | Method | Action | Certificate | Comment |
|---|---|---|---|---|
| In-Band and Out-of-Band | Attest C | TransNexus Telecom | Sign other numbers with Attest C | |
| 12025550107 | In-Band and Out-of-Band | Attest A | TransNexus Telecom | Sign trusted number with Attest A |
| 14045266060 | In-Band and Out-of-Band | Attest A | TransNexus Telecom | Sign trusted number with Attest A |
Sign ranges of trusted numbers
Authentication policies can be configured for calls with a calling number within a trusted number range.
| Calling Number | Method | Action | Certificate | Comment |
|---|---|---|---|---|
| In-Band and Out-of-Band | Attest C | TransNexus Telecom | Sign other numbers with Attest C | |
| 1404526 | In-Band and Out-of-Band | Attest A | TransNexus Telecom | Sign trusted number range with Attest A |
Sign all numbers owned by a specific OCN
Authentication policies can be configured for calls with a calling number owned by a particular OCN.
| Calling Number | Method | Action | Certificate | Comment |
|---|---|---|---|---|
| In-Band and Out-of-Band | Attest C | TransNexus Telecom | Sign other numbers with Attest C | |
| 1234 | In-Band and Out-of-Band | Attest A | TransNexus Telecom | Sign all numbers owned by OCN 234 with Attest A |
View authentication in SIP Messages
You can review the authentication results of signed calls by going to the SIP Messages page, clicking on the Columns button.
When you select the STI Authentication option, ClearIP only displays column headers related to authentication:
- STI Authentication Status - Whether the authentication was successful or not.
- STI Authentication Attestation Indicator - The attestation level of a authenticated call that is sent.
- STI Authentication Origination Identifier - The origid value of a authenticated call that is sent. The origid is a unique number associated with the call source.
View SIP Identity header and token
To look at the SIP identity header created for a signed SIP invite sent previously, 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 Authentication Status. Click on the blue Show button corresponding to the desired SIP message under the Show Message column.
Scroll down to find the SIP Response which looks like the image below. This is the response sent from ClearIP to the SBC. The SIP Identity header value is contained in the Identity header field in the SIP response. The switch or SBC must be configured to copy the Identity header and insert it into the redirected SIP Invite routed to the carrier.
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>
Identity: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9jZXJ0aWZpY2F0ZXMuY2xlYXJpcC5jb20vOTk5OTk5OTktOTk5OS00OTk5LTk5OTktOTk5OTk5OTk5OTk5LzAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwLnBlbSJ9.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxODU1NDc0MjUzNiJdfSwiaWF0IjoxNTc3ODM2ODAwLCJvcmlnIjp7InRuIjoiMTQwNDUyNjYwNjAifSwib3JpZ2lkIjoiOTk5OTk5OTktOTk5OS00OTk5LTk5OTktOTk5OTk5OTk5OTk5In0.abcdefghijklmnopqrstuvwzyzABCDEFGHIJKLMNOPQRSTUVWZYZ0123456789012345678901234567890123;info=<https://certificates.clearip.com/99999999-9999-4999-9999-999999999999/00000000000000000000000000000000.pem>;alg=ES256;ppt=shaken
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
To decode the token contained in the Identity header, click on the STI Authentication Token tab. An example decoded token is shown below.
View decoded token
{
"header": {
"alg": "ES256",
"ppt": "shaken",
"typ": "passport",
"x5u": "https://certificates.clearip.com/99999999-9999-4999-9999-999999999999/00000000000000000000000000000000.pem"
},
"payload": {
"attest": "A",
"dest": {
"tn": [
"18554742536"
]
},
"iat": 1577836800,
"orig": {
"tn": "14045266060"
},
"origid": "99999999-9999-4999-9999-999999999999"
},
"signature": "abcdefghijklmnopqrstuvwzyzABCDEFGHIJKLMNOPQRSTUVWZYZ0123456789012345678901234567890123"
}
The header contains general information about the format of the identity token and also includes a reference to the originating service provider’s certificate. This information is the same as that contained in the identity header.
The payload contains information about the call with most of it taken directly from the SIP invite.
The dest field contains the destination or called number. This is the value from the To header in the SIP Invite. In the SIP Messages page, this value is shown under the Asserted Called Number column.
The iat field represents the exact date and time that the identity token was created. Specifically, it represents the number of seconds that have elapsed since 00:00:00 UTC 1 January 1970.
The orig field contains the originating or calling number. This is the value from the P-asserted-identity header in the SIP Invite. If that is not available, the orig field copies the value in the From header. In the SIP Messages page, this value is shown under the Asserted Calling Number column.
The origid field is a unique number that can be associated with the call source. It can be used for trace back and allows one to create reputation profiles based on call sources.
SIP Response Identity Header Options
By default, ClearIP returns the token in the Identity header of a SIP 302 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>
Identity: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9jZXJ0aWZpY2F0ZXMuY2xlYXJpcC5jb20vOTk5OTk5OTktOTk5OS00OTk5LTk5OTktOTk5OTk5OTk5OTk5LzAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwLnBlbSJ9.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxODU1NDc0MjUzNiJdfSwiaWF0IjoxNTc3ODM2ODAwLCJvcmlnIjp7InRuIjoiMTQwNDUyNjYwNjAifSwib3JpZ2lkIjoiOTk5OTk5OTktOTk5OS00OTk5LTk5OTktOTk5OTk5OTk5OTk5In0.abcdefghijklmnopqrstuvwzyzABCDEFGHIJKLMNOPQRSTUVWZYZ0123456789012345678901234567890123;info=<https://certificates.clearip.com/99999999-9999-4999-9999-999999999999/00000000000000000000000000000000.pem>;alg=ES256;ppt=shaken
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
ClearIP can be configured to return the token value in an alternative header if configured in the SBCs page under the Identity Header field:
- X-Identity
X-Identity: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9jZXJ0aWZpY2F0ZXMuY2xlYXJpcC5jb20vOTk5OTk5OTktOTk5OS00OTk5LTk5OTktOTk5OTk5OTk5OTk5LzAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwLnBlbSJ9.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxODU1NDc0MjUzNiJdfSwiaWF0IjoxNTc3ODM2ODAwLCJvcmlnIjp7InRuIjoiMTQwNDUyNjYwNjAifSwib3JpZ2lkIjoiOTk5OTk5OTktOTk5OS00OTk5LTk5OTktOTk5OTk5OTk5OTk5In0.abcdefghijklmnopqrstuvwzyzABCDEFGHIJKLMNOPQRSTUVWZYZ0123456789012345678901234567890123;info=<https://certificates.clearip.com/99999999-9999-4999-9999-999999999999/00000000000000000000000000000000.pem>;alg=ES256;ppt=shaken
- Identity Embedded in Contact
Contact: <sip:+18554742536@sip.clearip.com:5060>;q=0.99?Identity=eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9jZXJ0aWZpY2F0ZXMuY2xlYXJpcC5jb20vOTk5OTk5OTktOTk5OS00OTk5LTk5OTktOTk5OTk5OTk5OTk5LzAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwLnBlbSJ9.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxODU1NDc0MjUzNiJdfSwiaWF0IjoxNTc3ODM2ODAwLCJvcmlnIjp7InRuIjoiMTQwNDUyNjYwNjAifSwib3JpZ2lkIjoiOTk5OTk5OTktOTk5OS00OTk5LTk5OTktOTk5OTk5OTk5OTk5In0.abcdefghijklmnopqrstuvwzyzABCDEFGHIJKLMNOPQRSTUVWZYZ0123456789012345678901234567890123%3Binfo%3D%3Chttps%3A%2F%2Fcertificates.clearip.com%2F99999999-9999-4999-9999-999999999999%2F00000000000000000000000000000000.pem%3E%3Balg%3DES256%3Bppt%3Dshaken
- Identity Embedded in Contact URI
Contact: <sip:+18554742536@sip.clearip.com:5060?Identity=eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9jZXJ0aWZpY2F0ZXMuY2xlYXJpcC5jb20vOTk5OTk5OTktOTk5OS00OTk5LTk5OTktOTk5OTk5OTk5OTk5LzAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwLnBlbSJ9.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxODU1NDc0MjUzNiJdfSwiaWF0IjoxNTc3ODM2ODAwLCJvcmlnIjp7InRuIjoiMTQwNDUyNjYwNjAifSwib3JpZ2lkIjoiOTk5OTk5OTktOTk5OS00OTk5LTk5OTktOTk5OTk5OTk5OTk5In0.abcdefghijklmnopqrstuvwzyzABCDEFGHIJKLMNOPQRSTUVWZYZ0123456789012345678901234567890123%3Binfo%3D%3Chttps%3A%2F%2Fcertificates.clearip.com%2F99999999-9999-4999-9999-999999999999%2F00000000000000000000000000000000.pem%3E%3Balg%3DES256%3Bppt%3Dshaken>;q=0.99
SIP Invite containing Identity header
The SBC must be configured to copy the Identity header from the SIP 302 response and insert it into the SIP Invite sent to the termination carrier. In the call trace, you should confirm whether your SBC is inserting the Identity header into the outgoing SIP Invite.
Here is an example SIP Invite containing the Identity header which is sent to a termination carrier.
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