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.

The Solution: SHAKEN / STIR

SHAKEN/STIR is a framework of interconnected standards. SHAKEN/STIR are acronyms for Signature-based Handling of Asserted information using toKENs (SHAKEN) and the Secure Telephone Identity Revisited (STIR) standards.

You can think of SHAKEN/STIR as a call authentication framework. It extends the Session Initiation Protocol (SIP) to allow the Originating Service Provider (OSP) to provide information to the Terminating Service Provider (TSP). It allows the OSP to state that they not only know the caller, but they also know that 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. There aren't any product changes required by you to comply with the TRACED Act and the FCC ORDER. You should learn how you might use these product changes to derive trust on your incoming calls and deliver trust on your outgoing calls.

New Incoming webhook parameters

Incoming calls to your application's Webhook will now be provided with two additional parameters.

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.

StirPassportToken

The StirPassportToken is a header that contains information:

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"
}

StirVerstat

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 NULL will be presented.

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 consists of header, payload, signature, and params.
• SHAKEN PASSporT doesn't 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.

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"
    }
}

Deliver a trusted impression on the called party's phone

Coming soon, Twilio will launch Business Profiles. You will be able to submit your business information for vetting so you can gain elevated permissions such as full Attestation under SHAKEN/STIR

For ISVs, a REST API will be available to allow you to pass your customer's business information directly to Twilio so your customers can also get highest attestation under SHAKEN/STIR.

Once your business has been verified, your provisioned Twilio numbers will get highest attestation, with no coding changes required.

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.

Calls from Twilio to Public Telephone Network (PSTN) (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 from Twilio to Clients

When your application receives a request webhook, that has the new StirStatus parameter all you have to do is <Dial><Client> and Twilio will implicitly pass the StirStatus 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.

Calls Status Callbacks (Coming later)

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

Elastic SIP Trunking product changes

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

SHAKEN / STIR rollout to Twilio accounts

Twilio has an obligation to sign outgoing calls to the public telephone network and to verify incoming calls by June 2021, per the TRACED ACT.

Twilio will gradually start onboarding Twilio accounts throughout 2020.