Contact Sales

All fields are required

Stop Spoofed Robocalls with libstirshaken: A STIR/SHAKEN… | SignalWire
Product

Stop Spoofed Robocalls with libstirshaken: A STIR/SHAKEN Library

Using libstirshaken to verify caller ID with an open-source STIR/SHAKEN library

Start for free Talk to an Expert
SignalWire

STIR/SHAKEN is an industry standard that helps verify caller identity and reduce caller ID spoofing by digitally signing calls with authentication tokens. When a compliant provider implements STIR/SHAKEN, it cryptographically validates that the caller ID being displayed on outbound calls truly matches the party authorized to use that number. This increases trust in voice communications, improves deliverability for legitimate calls, and makes it harder for scammers to impersonate numbers. SignalWire supports STIR/SHAKEN compliance on its network, allowing authenticated outbound calls to carry verified caller ID information.

What is STIR/SHAKEN?

STIR/SHAKEN is VoIP technology that brings an end to robocalling by securing a caller’s identity. This is accomplished with PASSporT - an encryption token transported by SIP Identity Header - and SSL certificates issued to trusted Service Providers, Certificate Authorities and Policy Administrators.

When receiving a call protected with STIR/SHAKEN you can examine the encryption token and tell what is the amount of trust you should assign to the displayed Caller ID. Robocallers would need to properly identify themselves to be considered trusted, thereby removing much of the motivation to make robocalls in the first place!

A positive result of a SHAKEN verification check means that:

1. You can be sure that the Caller ID you see is the true Caller ID that the originating Service Provider (SP) assigned to the call (it has not been spoofed.)

2. The originating Service Provider is registered on a secure network and is trusted by all participating entities.

3. And optionally, that the originating Service Provider is legally eligible to use that Caller ID, i.e. origination has the authority over this number on the secure network. This may be skipped in simple form of SHAKEN but it is a critical component.

Therefore by using SHAKEN you will be able to filter out fake callers, robocallers, spammers, and similar call impersonations because you will only accept calls that originated from trusted origin and have call data that was not changed by malicious user.

STIR/SHAKEN must be implemented by service providers by June 2021

On March 31st 2020 the Federal Communications Commission adopted new rules making STIR/SHAKEN mandatory from June 2021:

These rules will further the FCC’s efforts to protect consumers against malicious caller ID “spoofing,” which is often used during robocall scam campaigns to trick consumers into answering their phones. STIR/SHAKEN enables phone companies to verify that the caller ID information transmitted with a call matches the caller’s phone number. Widespread deployment of STIR/SHAKEN will reduce the effectiveness of illegal spoofing, allow law enforcement to identify bad actors more easily, and help phone companies identify calls with illegally spoofed caller ID information before those calls reach their subscribers.

Today’s Order requires all originating and terminating voice service providers to implement STIR/SHAKEN in the Internet Protocol (IP) portions of their networks by June 30, 2021, a deadline that is consistent with Congress’s direction in the recently-enacted TRACED Act.

The model of trust and software components

In STIR/SHAKEN software component may implement following roles: STI-PA, STI-CA and STI-SP (Policy Administrator, Certificate Authority and Service Provider). These are the main actors in STIR/SHAKEN.

STI-PA and STI-CA issue certificates to the STI-SPs. STI-SP makes and terminates secure calls. STI-SP may implement one or two services:

  • authentication service (STI-SP/AS), at the call origination point
  • verification service (STI-SP/VS), at the call termination point

The trust is established by means of SSL certificates and security tokens.

Tokens

There are two important tokens in STIR/SHAKEN.

The first one is SPC (Service Provider Code) token. This is given to SP by PA and allows SP to obtain certificate from CA, when CA challenges SP to prove the right to get certificate. It is necessary to obtain such certificate if SP wants to run STI-SP/AS service, but is not needed for STI-SP/VS service.

The second is called PASSporT - a JWT (JSON Web Token) created for every call by STI-SP/AS. It is describing and protecting call data when the call is going through unsecured channels between call origination and destination. It is checked by STI-SP/VS service at the call termination point.

Token examples

Example SPC token may look like this:

{
 "alg": "ES256",
 "issuer": "SignalWire STI-PA Test",
 "typ": "JWT",
 "x5u": "pa.shaken.signalwire.cloud/pa.pem"
}
.
{
 "notAfter": "1 year from now",
 "notBefore": "today",
 "spc": "1",
 "type": "spc-token"
}

Same SPC token in encoded form:

eyJhbGciOiJFUzI1NiIsImlzc3VlciI6IlNpZ25hbFdpcmUgU1RJLVBBIFRlc3QiLCJ0eXAiOiJKV1QiLCJ4NXUiOiJwYS5zaGFrZW4uc2lnbmFsd2lyZS5jbG91ZC9wYS5wZW0ifQ.eyJub3RBZnRlciI6IjEgeWVhciBmcm9tIG5vdyIsIm5vdEJlZm9yZSI6InRvZGF5Iiwic3BjIjoiMSIsInR5cGUiOiJzcGMtdG9rZW4ifQ.l61Y8K1bwZw9APXsrAQPZVPAkx5UIucwNKzRWxn0N5DcdVWaEgA_i5tW65f_aeqA46CTP789l4o6rFpiN7IZUA

Example PASSporT may look like this:

{
 "alg": "ES256",
 "ppt": "shaken",
 "typ": "passport",
 "x5u": "http://3.17.177.174/stir_shake..."
}
.
{
 "attest": "B",
 "dest": "{"tn":"1010"}",
 "iat": 1595694574,
 "orig": "{"tn":"9005551212"}",
 "origid": "986279842-79894328-45254-42543525243"
}


Same PASSporT in encoded form:

eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovLzMuMTcuMTc3LjE3NC9zdGlyX3NoYWtlbi9zcC5wZW0ifQ.eyJhdHRlc3QiOiJCIiwiZGVzdCI6IntcInRuXCI6XCIxMDEwXCJ9IiwiaWF0IjoxNTk1Njk0NTc0LCJvcmlnIjoie1widG5cIjpcIjkwMDU1NTEyMTJcIn0iLCJvcmlnaWQiOiI5ODYyNzk4NDItNzk4OTQzMjgtNDUyNTQtNDI1NDM1MjUyNDMifQ.ALWvxCXnY6QAMhMDQgG69yjpuQNHTnwBTf8i7La0eY0hV4hXiuWbD6HStXtzrFO4KD5Nmq_lPasTn70h00n0nQ


A quick overview of SHAKEN components

The basic use case in the SHAKEN framework would be:

Use Case 1

There is a Service Provider "A" who wants to be able to sign secure calls, so that other Service Providers can display to their users information about authenticity of the caller (trusted, fake, etc.).

The SP "A" would apply for a SPC token at PA, and would then use that token to obtain the STI Certificate from CA (CA and PA must cooperate as CA will only honour specific PAs).

SP "A" can then authenticate the calls it is originating with PASSporT signed by SP's private key and referencing SP's STI Certificate through PASSporT's "x5u" header. If we are talking the SIP world, then PASSporT would end up in the SIP Identity Header.

Service Provider "A" wants to implement (run) STI-SP/AS service.

Use Case 2

Service Provider "B" wants to check calls signed with SHAKEN, to be able to display to their users information about authenticity of the caller (trusted, fake, etc.).

SP "B" doesn't need STI Certificate, but must obtain a root certificates of the CAs it trusts. When PASSporT is retrieved from the incoming call, the link to the STI Certificate of the originating SP (say, SP "A") is dereferenced and PASSporT's signature is verified against the public key of that certificate.

Additionally, the certificate itself is subject to X509 certificate path verification procedure, which checks if the chain of trust can be established between that certificate and one of trusted anchors (CAs).

Service Provider "B" wants to implement (run) STI-SP/VS service.

We will focus on each software component (service) within SHAKEN framework in separate blogs, but let's have a very brief look at the flow charts of three most important processes involved in SHAKEN: obtaining STI certificate, authenticating the call and verifying it (with the PASSporT and SSL certificate).

STIR/SHAKEN security model: The process of obtaining STI Certificate from CA

STI-SP/AS: Call authentication

The authentication service is using JWT (JSON Web Token) for signing the call (creating PASSporT) with the SSL key of the Service Provider.

A1. Obtain a STI SP certificate from Certificate Authority.

A2. For every call STI-SP/AS create JSON Web Token (PASSporT) with call data (Caller ID, attestation/trust level for the call, and a link to SP’s public certificate).

A3. Sign PASSporT with STI-SP’s certificate.

A4. Add this to the SIP through SIP Identity Header.

This is how SHAKEN authentication may look like in practice (e.g. in FreeSWITCH):

2020-07-27 13:57:36.323122 [NOTICE] switch_channel.c:1118 New Channel sofia/external/1017@190.102.98.199:5880 [a879a76c-bd0d-4889-9e78-78f0aedde459]
freeswitch@ip-172-31-6-20> 
2020-07-27 13:57:36.343114 [NOTICE] sofia_glue.c:1674 sofia/external/1017@190.102.98.199:5880 STI-SP/AS: Authenticating Caller with STIR-Shaken/PASSporT...
freeswitch@ip-172-31-6-20> 
2020-07-27 13:57:36.343114 [WARNING] sofia_glue.c:1683 sofia/external/1017@190.102.98.199:5880 STI-SP/AS: Channel variable for cert not set. Set stir-shaken-cert? Trying XML default...
freeswitch@ip-172-31-6-20> 
2020-07-27 13:57:36.343114 [NOTICE] sofia_glue.c:1689 Using XML default value for certificate: /usr/local/freeswitch/conf/stir_shaken/as/sp.pem
{
 "alg": "ES256",
 "ppt": "shaken",
 "typ": "passport",
 "x5u": "http://3.17.177.174/stir_shake..."
}
.
{
 "attest": "B",
 "dest": "{\"tn\":\"1017\"}",
 "iat": 1595858256,
 "orig": "{\"tn\":\"TrustedCallerID\"}",
 "origid": "986279842-79894328-45254-42543525243"
}

2020-07-27 13:57:36.343114 [NOTICE] sofia.c:12867 sofia/external/1017@190.102.98.199:5880 STI Cert: Version: 3
2020-07-27 13:57:36.343114 [INFO] sofia_glue.c:2020 sofia/external/1017@190.102.98.199:5880 STI-SP/AS: Cert location: /usr/local/freeswitch/conf/stir_shaken/as/sp.pem
2020-07-27 13:57:36.343114 [INFO] sofia_glue.c:2021 sofia/external/1017@190.102.98.199:5880 STI-SP/AS: Cert install location: /var/www/html/stir_shaken/sp.pem
2020-07-27 13:57:36.343114 [INFO] sofia_glue.c:2022 sofia/external/1017@190.102.98.199:5880 STI-SP/AS: Cert URL: http://3.17.177.174/stir_shake...
2020-07-27 13:57:36.343114 [INFO] sofia_glue.c:2023 sofia/external/1017@190.102.98.199:5880 STI-SP/AS: SIP Date header: Mon, 27 Jul 2020 13:57:36 GMT
2020-07-27 13:57:36.343114 [INFO] sofia_glue.c:2035 sofia/external/1017@190.102.98.199:5880 STI-SP/AS: === Caller authenticated


STI-SP/VS: Call verification

Verification service reads the URL to STI-SP SSL certificate of the originating SP from PASSporT or <info> param in SIP Identity Header, downloads it, checks if it is trusted, ans uses it for PASSporT verification check.

V1. Get the SIP Identity Header and PASSporT out of it.

V2. Read a link to the certificate of the STI-SP who is originator of the call and download that certificate.

V3. Check that downloaded certificate is trusted, by performing X509 certificate path validation procedure (this checks if certificate trust chain of the downloaded certificate originates from any of the trusted root CA).

V4. Decode PASSporT using downloaded certificate. If the PASSporT decodes successfully then terminating point knows that the data contained in PASSporT has not been spoofed, changed or otherwise manipulated by malicious user.

V5. Check that Caller ID in PASSporT matches data from SIP. If it does, then terminating point knows that the call has not been spoofed, changed or otherwise manipulated by malicious user.

V6. (Optional) Finally, check that originating SP used one of the numbers assigned to it (authority over Caller ID).


What is libstirshaken?

Even if the industry may not be ready yet to use SHAKEN on a global scale, the core technology behind it can be used today to benefit users with trusted, secure calls. This is why SignalWire decided to release libstirshaken. This is C library that implements the core technology behind STIR/SHAKEN framework. In short:

  • C library

  • STI-SP: STI-SP/AS, STI-SP/VS

  • STI-CA and elements of STI-PA (filling the gaps in specs with sane approach)

  • libjwt for JWT (PASSporT, SPC token)

  • libcurl for http requests

  • mongoose for handling of http requests (by CA)

libstirshaken ships with test-reference setup for SP, CA/PA, so you can test process of obtaining STI-SP certificate from test-reference CA: `ca.shaken.signalwire.com`. You can then use FreeSWITCH to complete the testing by making secure calls between two servers.

You can use libstirshaken as a core of STIR/SHAKEN integration to your system.


STIR/SHAKEN in FreeSWITCH

FreeSWITCH contains test-reference setup for STI-SP/AS, STI-SP/VS, so you can test process of obtaining STI-SP certificate from test-reference CA: ca.shaken.signalwire.com and use that to complete the testing by making secure calls between FreeSWITCHes running test-reference STI-SP/AS, STI-SP/VS.

How can I use it with SignalWire?

SignalWire participates in the SHAKEN interoperability testbed run by Neustar/ATIS and actively monitors developments within SHAKEN technology, e.g. by taking part in IETF effort.

SignalWire plans to embed SPC token functionality into SignalWire platform, effectively running combined role of STI-CA/STI-PA and allowing customers to obtain end entity STI-SP certificates from SignalWire for making secure calls (with protected call data and trusted call origin.)

Customers will be able to join this network using either FreeSWITCH or their own implementations of SHAKEN, compatible with (or completely built on) libstirshaken.

Have questions? Join our developer community on Discord to connect with our team and other experts!

Frequently asked questions

What is STIR/SHAKEN?
STIR/SHAKEN is a framework designed to authenticate caller identity in Internet Protocol (IP) voice calls by digitally signing caller ID information, making it harder for fraudsters to spoof numbers.

Why does caller ID authentication matter?
Caller ID authentication increases trust in phone calls, reduces the chance of spoofed numbers reaching users, and helps legitimate businesses get answered more often by avoiding spam labeling on networks.

How does STIR/SHAKEN work?
Service providers use cryptographic certificates to sign outgoing calls in the SIP header; receiving networks then check those signatures to confirm that the caller ID matches the authenticated origin.

Do all service providers have to implement STIR/SHAKEN?
In many regions — including the United States — regulatory bodies like the FCC require service providers to implement STIR/SHAKEN in the IP portions of their networks to combat illegal robocalls.

Does STIR/SHAKEN stop all spoofed calls?
STIR/SHAKEN significantly reduces spoofed and illegal robocalls by enforcing authentication, but it does not eliminate all fraudulent calls on its own; other defenses and monitoring may still be needed.

Related Articles