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:
- Create a Business Profile in the Trust Hub part of the Console and submit for vetting. Click here.
- Assign phone numbers in your account to the Business Profile. This associates a single identity with the phone number.
- Create a SHAKEN/STIR Trust Product in the Trust Hub and submit for vetting. Click here.
- 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:
|
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 orinfo
parameter. - SHAKEN PASSporT
orig
field doesn't match with actualcallerid
in the SIP messages (P-Asserted-Identity
,Remote-Party-Identity
, orFrom
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 For incoming calls, this is the verification result. One of:
|
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 |
|
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.
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.