Menu

Expand
Rate this page:

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

SHAKEN/STIR is in Public BETA. Direct customers using Twilio phone numbers are eligible to receive highest attestation.

API changes described below that are "Coming later" are subject to change.

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.

Only (some) carriers in the United States support SHAKEN/STIR signing and verifying as of 9/2020.

Canada is moving forward with SHAKEN/STIR. The STI-PA/GA went live on 9/2020.

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.

Twilio's Compliance operations team is responsible for vetting the Business Profile and the SHAKEN/STIR Trust Product. The time to vet can be between 24 to 48 hours.

Twilio will only sign calls with A attestation that use Twilio numbers in your account that are assigned to your Business Profile and SHAKEN/STIR Trust Product. Other numbers in your account or verified callerIds used to make calls will not be signed. The industry is still reaching consensus on signing calls with B and C attestation and Twilio will follow adoption and meet it's obligations per the TRACED ACT.

You are considered a direct customer if your employees are responsible for making the calls. This includes BPOs.
You are considered an ISV (independent software vendor) if your customers are responsible for making the calls using your product.

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

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.

New TwiML fetch parameters Description
StirVerstat

Possible values:

  • TN-Validation-Passed-A
  • TN-Validation-Passed-B
  • TN-Validation-Passed-C
  • TN-Validation-Failed-A
  • TN-Validation-Failed-B
  • TN-Validation-Failed-C
  • No-TN-Validation
  • TN-Validation-Failed
  • NULL
See definitions below

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

Property Description
stir_status

For outgoing calls, this is the attestation that Twilio gave the call with possible values of A, B, C.

For incoming calls, this is the verification result. One of:

  • TN-Validation-Passed-A
  • TN-Validation-Passed-B
  • TN-Validation-Passed-C
  • TN-Validation-Failed-A
  • TN-Validation-Failed-B
  • TN-Validation-Failed-C
  • No-TN-Validation
  • NULL

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)

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.

Elastic SIP Trunking product changes

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

New SIP headers Possible Values
X-Twilio-VerStat
  • TN-Validation-Passed-A
  • TN-Validation-Passed-B
  • TN-Validation-Passed-C
  • TN-Validation-Failed-A
  • TN-Validation-Failed-B
  • TN-Validation-Failed-C
  • No-TN-Validation
Identity Base64 encoded SHAKEN PASSporT equivalent to the StirPassportToken described above.

You must explicitly request from Twilio to enable passing the StirPassportToken in the SIP INVITE. Twilio removes it by default to avoid passing a SIP INVITE to you that will create UDP fragmentation and possible networking issues on your network.

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.

        
        
        

        Thank you for your feedback!

        We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more