x

SignalWire Work is here. An innovative, clientless, and secure virtual office. Sign up for a 30-DAY FREE TRIAL or Learn more.

Stop spoofed robocalls with libstirshaken - a new STIR/SHAKEN library from SignalWire

Using `libstirshaken` to verify caller ID with our new open-source STIR/SHAKEN library

Piotr Gregor | Software Engineer

Jul 30, 2020



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



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



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


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


5. Token Examples


Example SPC token may look like this:

Same SPC token in encoded form:


Example PASSporT may look like this:

Same PASSporT in encoded form:



6. 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).



7. STIR/SHAKEN Security Model: The process of obtaining STI Certificate from CA



8. 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):


9. 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).

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



10. This is great! Can we use it?


Unfortunately, this is not possible in general yet. The reason being that the work on the technology backing up STIR/SHAKEN, and on the environment within which SHAKEN operates has not been finished yet and SHAKEN is subject to frequent changes. It is not a very complex technology but there is couple of things that inject slowness in the process. There are issues with creation of SHAKEN environment and with testing interoperability.

Some of the issues are:


  • Registering at both the CA & PA
  • Becoming an SP: rules are not clear for smaller telecommunications businesses which may not have access to numbering plan

  • Obtaining SPC from PA (SPC token not very well defined as of today yet, and same with the whole process of getting the SPC token)

  • TNAuthList and dynamically changing, non-contiguous telephone resources

  • Model of trust (who can become CA, who can use delegated cert, who can issue STI certificate, etc.)

  • OpenSSL: TNAuthList v3 extension to X509 (openssl library doesn't implement this extension yet - it can be extended by user though to include this extension and it's how SignalWire uses it today )


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

We will provide you with details of the library in next blog posts. You can use  libstirshaken as a core of STIR/SHAKEN integration to your system. Here we simply present it's capabilities:


You can download (or git clone) libstirshaken here: https://github.com/signalwire/libstirshaken 


12. STIR/SHAKEN in FreeSWITCH


If you are a FreeSWITCH user, then you will get libstirshaken integrated with FreeSWITCH out of the box with next FreeSWITCH releases.

FreeSWITCH will contain 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.


13. So... How can I use it with SignalWire? SignalWire acting as a STIR/SHAKEN trust anchor for STI-PA/CA


SignalWire is actively pursuing the possibility of becoming an STI-CA in the global SHAKEN network, and is also investigating building its own network of trusted Service Providers. 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 (https://signalwire.com), 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.



    14. What's Next

    In the next blogs we will explain:

    • The details of STI-SP/AS and STI-SP/VS and their implementation in libstirshaken
    • The details of STI-CA and it's implementation in libstirshaken
    • How to obtain STI-SP certificate from SignalWire using FreeSWITCH or the `stirshaken` program (part of libstirshaken)
    • How to test it with test-reference setup in FreeSWITCH