Menu

Expand
Rate this page:

Trusted Calling with SHAKEN/STIR

This page contains general information on SHAKEN/STIR, along with some implementation details.

If you're ready to enable SHAKEN/STIR on your account(s), go to the SHAKEN/STIR Onboarding page.

SHAKEN/STIR Overview

The Problem: Robocalls

Robocalls are calls that are created by an auto-dialer, and typically play pre-recorded messages. Fraudsters use robocalls in combination with spoofing (falsifying caller IDs) to acquire something of value from their victims. In 2020, there were 48.9 billion robocalls in the United States, leading to an erosion of trust in the telephone network and a decline in call answer rates from unidentified phone numbers.

The Solution: SHAKEN/STIR

SHAKEN stands for Signature-based Handling of Asserted Information using toKENs. It is a specification designed by the Alliance for Telecommunications Industry Solutions (ATIS) to fight caller ID spoofing. STIR (Secure Telephone Identity Revisited) is a protocol developed by the Internet Engineering Task Force (IETF) to enable end-to-end call authentication, but the protocol is very broad and doesn't ensure that different providers will be able to verify each others' calls. SHAKEN is a set of implementation details that follows the STIR protocol, but streamlines specifications to increase the likelihood of carrier interoperability. This is why you will often see the technology referred to as "SHAKEN/STIR" or "STIR/SHAKEN".

Essentially, SHAKEN/STIR uses encrypted digital signatures to share information about the caller to each provider along a call's path from caller to recipient, such as the caller's identity and whether the caller has the right to use the phone number they provided as the caller ID.

To learn more about the implementation of SHAKEN/STIR, read our blog post "Everything You Need to Know about SHAKEN/STIR Today".

Twilio, like all major carriers in the United States, has signing and verifying privileges. Keep reading to learn about the product changes you can expect when you to enable SHAKEN/STIR on your account(s).

Changes for Twilio Customers

As of 06/2021, support for the SHAKEN/STIR call authentication framework is being deployed in the United States only.

  • For Programmable Voice customers, a new parameter will be present in incoming webhooks and outgoing calls: StirVerstat.
  • For Elastic SIP Trunking customers, there is a new header called X-Twilio-VerStat, and a new Identity header with the SHAKEN PASSporT.

To understand the possible values for the StirVerstat parameter/X-Twilio-VerStat header, you will first need to understand the three different attestation levels:

  • 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.

The table below describes the possible values for the StirVerstat parameter/X-Twilio-VerStat header.

StirVerstat parameter / X-Twilio-VerStat header value Definition
TN-Validation-Passed-A

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.

Attestation level A

TN-Validation-Passed-B

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.

Attestation level B

TN-Validation-Passed-C

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.

Attestation level C

TN-Validation-Failed-A

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.

Attestation level A

TN-Validation-Failed-B

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.

Attestation level B

TN-Validation-Failed-C

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.

Attestation level C

No-TN-Validation

Possible causes:

  • A malformed E.164 phone number
  • SHAKEN PASSporT format is invalid. It should consist of a header, payload, signature, and parameters.
  • SHAKEN PASSporT does not have required fields 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.
TN-Validation-Failed

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.

No attestation level determined.

NULL

Incoming Calls

Twilio Programmable Voice and Elastic SIP Trunking now perform SHAKEN/STIR verification on incoming calls to your Twilio local phone numbers. It can be used to display a trust indicator or to make a routing decision, such as bypassing a voice captcha or IVR and directing the call to an end user.

A verified call that has been given the highest attestation under SHAKEN/STIR means that the carrier that originated the call both (1) knows the identity of the caller, and (2) knows the caller has the right to use the phone number as the caller ID.

Note: The new StirVerstatparameter/X-Twilio-VerStat header are only present for incoming calls with SHAKEN PASSporT identity headers. To take advantage of X-Twilio-VerStat header on inbound Elastic SIP Trunking calls you will need to reach out for it to be enabled.

Outgoing Calls

When your application receives a request webhook that has the new StirVerstat parameter, Twilio will implicitly pass the StirVerstat to the Client when you <Dial><Client>. The information in the StirVerstat parameter 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.

The Javascript Client now has: Connection.CallerInfo.isVerified

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

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 (functionality coming soon), this will be attestation of the incoming call that was forwarded.

Call Forwarding - Coming Later

Anything marked as "Coming Later" is subject to change.

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 CallToken to the bridged call. Additionally, Twilio and carriers must support an additional PASSporT called the DIVERSION header.

CallToken

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

The CallToken contains all the identity headers that contain the raw SHAKEN PASSporT identity information about the caller:

CallToken=eyJhbGciOiAiRVMyNTYiLCJwcHQiOiAic2hha2VuIiwidHlwIjogInBhc3Nwb3J0IiwieDV1IjogImh0dHBzOi8vY2VydGlmaWNhdGVzLmNsZWFyaXAuY29tL2IxNWQ3Y2M5LTBmMjYtNDZjMi04M2VhLWEzZTYzYTgyZWMzYS83Y2M0ZGI2OTVkMTNlZGFkYTRkMWY5ODYxYjliODBmZS5jcnQifQ.eyJhdHRlc3QiOiAiQSIsImRlc3QiOiB7InRuIjogWyIxNDA0NTI2NjA2MCJdfSwiaWF0IjogMTU0ODg1OTk4Miwib3JpZyI6IHsid

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

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 by visiting Twilio's Community Forums or 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