How to make trusted calls and protect against unlawful spoofing using SHAKEN/STIR

The Problem: Robocalls

Robocalls are calls that are created by an auto-dialer that typically play a pre-recorded message. Spoofing is a term that refers to falsifying where a call originates. Fraudsters use Robocalls with spoofed caller IDs to impersonate identities attempting to acquire something of value from the victim. In 2019 there were over 50 billion robocalls in the United States eroding trust in the telephone network and leading to a drop in call answer rates from unidentified numbers.

The Solution: SHAKEN / STIR

SHAKEN/STIR is a caller authentication framework meant to help restore trust in the calling number (callerId). SHAKEN stands for Signature-based Handling of Asserted information using toKENs and STIR stands for Secure Telephone Identity Revisited. They are standards developed by ATIS and the IETF respectively.

The protocol specifies how to insert a new Identity header in the SIP INVITE used to initiate a phone call. The new identity header called a SHAKEN PASSporT, allows the Originating Service Provider (OSP) to provide information to the Terminating Service Provider (TSP) about the caller. The information provided in the SHAKEN PASSporT says (1) if the caller's identity is known, and (2) if the caller has the right to use the phone number they provided as the caller ID.

Twilio, like all major carriers in the United States, has signing and verifying priviledge. You should learn how you might use these product changes to derive trust on your incoming calls and deliver trust on your outgoing calls.

Deliver a trusted impression on the called party's phone

For direct customers, in a few clicks in the Console, you can enable SHAKEN/STIR on your outgoing calls that deliver a trust indicator on the called party's phone.

Here are the steps:

1. Create a Business Profile in the Trust Hub part of the Console and submit for vetting. Click here.
2. Assign phone numbers in your account to the Business Profile. This associates a single identity with the phone number.
3. Create a SHAKEN/STIR Trust Product in the Trust Hub and submit for vetting. Click here.
4. Assign phone numbers already assigned to your Business Profile identity to the SHAKEN/STIR Trust Product

That's it. No coding required.

Learn more about Business Profiles and other Trust Products in the Trust Hub here.

New Incoming webhook parameters

Incoming calls to your application's Webhook will now be provided with one additional parameter.

As an example of how to use this new parameter, you may choose to use the result, TN-Validation-Passed-A, to accelerate identity verification in your contact center.

StirVerstat Interpretation

TN-Validation-Passed-*: Twilio received the SIP INVITE, with a SHAKEN PASSporT, and was able to fetch the public certificate of the originating service provider from the Certificate Authority that signed the call to verify that no one tampered with the SIP INVITE during transit.

TN-Validation-Failed-*: means Twilio was unable to verify the contents of the SHAKEN PASSporT. This could mean tampering, or simply that Twilio could not retrieve the public certificate of the originating service provider from the Certificate Authority.

A : the highest attestation given by the originating service provider to indicate that the caller is known and has the right to use the phone number as the caller ID

B : the customer is known, it is unknown if they have the right to use the caller ID being used

C : it doesn't meet the requirements of A or B including international calls.

For international calls or domestic calls that don’t have a SHAKEN PASSporT the StirStatus will not be presented in the Webhook nor the SIP INVITE.

No-TN-Validation : Malformed E.164 numbers can lead to this being presented.

Other reasons for No-TN-Validation

• SHAKEN PASSporT format is invalid. It should consist of header, payload, signature, and params.
• SHAKEN PASSporT does not have required field like ppt headers or info parameter.
• SHAKEN PASSporT orig field doesn't match with actual callerid in the SIP messages (P-Asserted-Identity, Remote-Party-Identity, or From header).
• SHAKEN PASSporT dest field doesn't match with the actual destination of the call in the SIP Request-URI.
• SHAKEN PASSporT iat field is too old – more than 1 minutes from current timestamp or the SIP Date header value.

Calls from Twilio to Clients

When your application receives a request webhook, that has the new StirVerstat parameter all you have to do is <Dial><Client> and Twilio will implicitly pass the StirVerstat to the Client. It can be used to display a trust indicator to the recipient when an incoming call, from the public telephone network, has been verified under the SHAKEN/STIR framework.

Calls from Twilio to Clients (WebRTC browser)

Javascript Client now has: Connection.CallerInfo.isVerified

Calls from Twilio to Clients (iOS, Android)

The Android and iOS Mobile SDKs now have the CallerInfo object and TVOCallerInfo class to represent information about the caller.

New Calls Resource Property: stir_status (Coming later)

curl 'https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXX/Calls/CAXXXXXXXXXXXXXXXX.json' -u ACXXXXXXXXXXXXXX:[AuthToken]
 
{
    "sid": "CAXXXXXXXXXXXXXXXXXXXXXXX",
    "date_created": "Mon, 30 Sep 2019 21:18:06 +0000",
    "date_updated": "Mon, 30 Sep 2019 21:18:24 +0000",
    "parent_call_sid": null,
    "account_sid": "ACXXXXXXXXXXXXXXXXXXX",
    "to": "+15103300034",
   ...
    "stir_status" : "A"
    }
}

Call forwarding (Coming Later)

It's very common for a consumer to call into a Twilio phone number and a need to bridge the call with a second call to the public telephone network. In this case, Twilio must facilitate passing the incoming StirPassportToken to the bridged call. Additionally, Twilio and carriers must support an additional PASSporT called the DIVERSION header.

To support call forwarding flows the following changes will be rolled out gradually to accounts.
If you believe your application cannot handle the StirPassportToken because of the contents or size then please contact help@twilio.com.

StirPassportToken

The StirPassportToken is a header that contains the raw SHAKEN PASSporT identity information about the caller:

StirPassportToken="Identity: eyJhbGciOiAiRVMyNTYiLCJwcHQiOiAic2hha2VuIiwidHlwIjogInBhc3Nwb3J0IiwieDV1IjogImh0dHBzOi8vY2VydGlmaWNhdGVzLmNsZWFyaXAuY29tL2IxNWQ3Y2M5LTBmMjYtNDZjMi04M2VhLWEzZTYzYTgyZWMzYS83Y2M0ZGI2OTVkMTNlZGFkYTRkMWY5ODYxYjliODBmZS5jcnQifQ.eyJhdHRlc3QiOiAiQSIsImRlc3QiOiB7InRuIjogWyIxNDA0NTI2NjA2MCJdfSwiaWF0IjogMTU0ODg1OTk4Miwib3JpZyI6IHsidG4iOiAiMTgwMDEyMzQ1NjcifSwib3JpZ2lkIjogIjNhNDdjYTIzLWQ3YWItNDQ2Yi04MjFkLTMzZDVkZWVkYmVkNCJ9.S_vqkgCk88ee9rtk89P6a6ru0ncDfSrdb1GyK_mJj-10hsLW-dMF7eCjDYARLR7EZSZwiu0fd4H_QD_9Z5U2bg;info=<https://certs.com/sdfasdfdsfds.crt>alg=ES256;ppt=shaken"

The token is in jwt format. If you decode the token you'll find the following information:

// HEADER: Algorithm & Token type

{
  "alg": "ES256",
  "ppt": "shaken",
  "typ": "passport",
  "x5u": "https://certificates.clearip.com/b15d7cc9-0f26-46c2-83ea-a3e63a82ec3a/7cc4db695d13edada4d1f9861b9b80fe.crt"
}

// PAYLOAD: Data

{
  "attest": "A",
  "dest": {
    "tn": [
      "14045266060"
    ]
  },
  "iat": 1548859982,
  "orig": {
    "tn": "18001234567"
  },
  "origid": "3a47ca23-d7ab-446b-821d-33d5deedbed4"
}

To enable call forwarding, changes to the following will be done (Coming later)

A new optional attribute of StirPassportToken will be added to the following calling methods:
(Subject to change)

• <Dial>
• Calls Resource
• Agent Conference Participant Resource
• Task Router Reservation Resource

Calls Status Callbacks

The Status Callback StirStatus optional parameter will inform you of the attestation Twilio gave your call to the public telephone network. If the call is forwarded, this will be attestation of the incoming call that was forwarded.

• <Dial>
• Call Resource
• Voice Webhooks

Elastic SIP Trunking product changes

For origination calls from the public telephone network towards your SIP infrastructure