Troubleshooting STIR/SHAKEN

cperez
updated 7 days ago

This article covers general problem troubleshooting related to STIR/SHAKEN signatures. We expect to be updating this page over the next several months as calls with STIR/SHAKEN signatures increase in volume.

SHAKEN Echo Number

When deploying STIR/SHAKEN, adding a new vendor or making changes to your network you might want to know if your calls are being delivered properly using STIR/SHAKEN. An effective approach is to verify how is your call is being handled outside of your network. Our SHAKEN Echo Number facilitates this and more.

Meant to be used with our companion website (https://test-shaken.sansay.cloud) our test number will provide real-time results including:

Verstat/STI-VS Verification Results
Attestation Level
STIR/SHAKEN Certificate used to sign the call
RCD Claim for Branded Calling.

Embedded in our SHAKEN Test Number site you will find our Identity Header Decoder which can examine a SHAKEN PASSPorT and the most common issues.

Invalid Signature

This problem normally happens during the initial setup/install.

Private key and certificate mismatch

This problem occurs during the initial setup on your switch/STI engine or after re-keying a certificate and consists in signing calls with a private key different than the certificate exposed in the Identity header.

A great utility when troubleshooting failed STI-VS verificatios is to use Sansay's Identity Header Decoder.

Here's an example:

Upon viewing the error it's evident that something is wrong with the signature. Using openssl it is possible match the private key against the certificate:

openssl s_server -accept 9999 -cert certificate.crt -key privatekey.key

Syntax issues

Another common problem is when the SHAKEN passport is miscontructed with syntax issues. Syntax issues can occur in different areas and it is difficult to outline all of them. The best way to go about this issue is using a signature decoder/validation.

Here's Sansay's Identity Header Decoder. in action:

NTP synchronization

The SIP Identity header token contains the time of day when the token was originally created by the STI-AS server. This timestamp is contained within the "iat" object within the token time is used as a criteria to verify the call as a way of protect against the re-use of the same web token.

{
  "attest": "A",
  "dest": {
    "tn": [
      "18587542200"
    ]
  },
  "iat": 1621616667,
  "orig": {
    "tn": "18587542216"
  },
  "origid": "9b2a8a00-b9a9-11eb-824e-bbbebbc98888"
}

Symptom

If the verification service receives a request with an "iat" value older than the STI-VS local policy for freshness permits, the INVITE will get rejected. Most STI-VS including Sansay's NSS use a 60s policy. If the "iat" timestamp is set to the future an error condition is expected as well.

What to do

NTP time synchronization on your STI-AS (Sansay NSS) is critical to ensure an accurate "iat" is included in your signatures. Make sure you are using trusted and updated NTP servers.
Use Sansay PSM to monitor time synchronization. If your NSS were to fall behind in time you will get notified.

Packet Fragmentation

The SIP Identity header adds approximately 500 bytes to the initial INVITE at call setup time. When enabling STIR/SHAKEN your SIP INVITEs will be larger than they previously were, now exceeding most network MTUs (Maximum Transmission Unit) and causing packet fragmentation.

While most SIP servers do not have an issue re-assembling fragmented packets, underlying network infrastructure might present an obstacle on over-the-top/public Internet interconnects.

Symptom

When using SIP/UDP and packet fragmentation occurs the observed symptoms are:

You do not see the INVITE arrive. Your peering partner may see it leave their network.
Your INVITEs result in a timeout.

UDP, which to date widely used for SIP interconnects, being a message oriented protocol is prone to packet fragmentation and packet loss. UDP does not have built-in re-ordering or re-transmission mechanisms and should be avoided when packets are fragmented.

TCP is a connection oriented protocol which handles packet re-ordering and re-transmission of lost packets and it is better suited for situations where fragmentation would occur. Switching to SIP/TCP will prevent issues related to packet fragmentation.

What to do

The SIP/UDP to SIP/TCP change will be done in your SBC. For VSXi users it will depend whether you are enabling TCP to receive traffic from customers, send traffic to vendors.
1. Ingress traffic: You can simply switch your Service Port from UDP to UDP/TCP. This will allow customers to seamlessly switch from UDP to TCP.
2. Egress traffic: Egress traffic must use a TCP-only Service Port. This will trigger the VSXi that it must initiate a TCP connection before INVITEs can be sent. You will need to coordinate with your downstream vendor switching to TCP.

DNS Resolution

The SIP Identity header contains a certificate URL. This URL is used to verify the signature against a certificate.

Identity: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9jci5zYW5zYXkuY29tL0VHR19JTkNfdDNzdCJ9.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxMjI5NTYzNDU1MCJdfSwiaWF0IjoxNjE5NDQzNTk3LCJvcmlnIjp7InRuIjoiMTIyOTMxNjI4MjYifSwib3JpZ2lkIjoiMDcxYTc5M2UtYTY5My0xMWViLWJhMDQtZmNiYmZiZmM4ODg4In0.MBaGznoIqWT2ZOneiHeyA3v2ksRD65s6ukm0vDVHLmH464J0Lj4rNfq2QHZAZurgeydQW-NGawhR06JqeUWubw;info=<https://cr.sansay.com/Sansay_Test.crt>;alg=ES256;ppt=\"shaken\"

An important aspect of STIR/SHAKEN is that STI-VS cache certificates using different mechanisms: not every time the certificate in the URL will be retrieved to save on post dial delay (PDD). The certificate is retrieved if it has not been cached or if it's cache lifetime has expired.

Symptom

If your STI-VS is having DNS resolution issues it will fail certificate validation. Sansay NSS in particular will reject the STI-VS query with a SIP 437 Unsupported Credential cause.

What to do

Make sure you configure redundant DNS servers that you trust on your STI-VS infrastructure. For Sansay NSS this is configured under System > General: Edit.