Menu

Expand
Rate this page:

Thanks for rating this page!

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

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

SHAKEN/STIR is in PRIVATE BETA so only select accounts are enabled with the behavior described in this page.

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.

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.

Currently SHAKEN/STIR is only supported in the United States.

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.

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
StirPassportToken The raw Base64 encoded header that contains the attestation and origination identifier that can be used in call forwarding scenarios.

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

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

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)

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.

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.

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.