STIR/SHAKEN for VoIP Platforms: How It Works and How to Implement It
If your platform sends calls to the US phone network, unsigned or poorly attested calls get labelled as spam, blocked, or never answered. This guide explains how STIR/SHAKEN signs and verifies a call, what the A, B and C attestation levels really promise, the rule changes of 2025 and 2026, and how to implement signing and verification on Kamailio, Asterisk and FreeSWITCH.
Quick answer
What is STIR/SHAKEN and how do VoIP providers implement it?
STIR/SHAKEN is the caller ID authentication framework US voice providers use on SIP calls. The originating provider signs each call with a PASSporT token, carried in the SIP Identity header, that states an attestation level (A, B or C). The terminating provider downloads the signer's certificate and verifies the signature. Since 18 September 2025, providers with an implementation obligation must sign with their own SPC token and certificate, even when a vendor does the signing for them.
What STIR/SHAKEN is and why it matters
Caller ID on the phone network was built on trust: whoever started the call could put almost any number in the From field. Robocallers exploited that by spoofing local or familiar numbers. STIR/SHAKEN adds a cryptographic signature so the network can tell whether the provider that started the call stands behind the caller ID.
The name joins two pieces. STIR (Secure Telephone Identity Revisited) is a set of IETF standards: RFC 8224 defines the SIP Identity header, RFC 8225 defines the PASSporT token, and RFC 8588 adds the SHAKEN extension with the attestation field. SHAKEN (Signature-based Handling of Asserted information using toKENs) is the ATIS and SIP Forum framework that says how carriers use those standards, who issues certificates and how attestation levels are chosen.
In practice it works like this. The originating provider runs an Authentication Service that builds a PASSporT for each outbound call. The PASSporT contains the calling and called numbers, a timestamp, a unique ID and an attestation level, and it is signed with the provider's private key. Intermediate carriers pass the Identity header along unchanged. The terminating provider runs a Verification Service that downloads the signer's certificate from the URL in the token, checks that it chains to a trusted certificate authority, checks the signature and the timestamp, and passes the result to call analytics and the called party's display.
For anyone building a VoIP platform, a softswitch, a hosted PBX or an AI calling product that reaches US numbers, this is no longer optional plumbing. Calls without a valid signature, or with a weak attestation, are more likely to be labelled "Spam Likely", blocked by analytics engines, or simply ignored by the person being called.
Attestation levels A, B and C
The attestation level is the signing provider's statement about what it knows. It is the single most important value in the token, and the one regulators are now looking at most closely.
| Level | What the signing provider asserts | Typical example | How terminating analytics tend to treat it |
|---|---|---|---|
| A (Full) | It has an authenticated relationship with the customer making the call AND has verified the customer may use the calling number | A business calling from a DID you assigned to it | Strongest positive signal |
| B (Partial) | It has an authenticated relationship with the customer, but cannot verify the customer's right to use the calling number | A PBX customer sending a number you did not issue, such as a toll-free number hosted elsewhere | Neutral; relies more on other signals |
| C (Gateway) | It is the entry point for the call but has no relationship with the initiator | Calls arriving from an international gateway or an unauthenticated upstream | Weak; often treated with suspicion |
Getting A attestation right depends on data, not code. Your signing service needs an accurate, current answer to the question "did we assign this number to this customer, or have we verified that they own it?" For a multi-tenant platform, that means a numbers table linked to customer accounts, number porting records and an approval process for customers who bring their own numbers. Signing A for numbers you have not verified is exactly the behaviour the FCC's 2026 proposals target.
Share of outbound calls by attestation level on a typical multi-tenant platform (illustrative)
Illustrative only. The real mix depends on how many customers use numbers you issued versus numbers hosted elsewhere.
Who has to implement STIR/SHAKEN
Under the FCC's rules, voice service providers with control over the network infrastructure needed to sign calls must implement STIR/SHAKEN on the IP portions of their networks. In plain terms, if you run your own SIP network, assign numbers to customers and hand calls to the phone network, you very likely have an obligation. The exact boundaries are a legal question, so confirm your position with telecom counsel.
Usually in scope
Interconnected VoIP providers, CLECs, hosted PBX and UCaaS operators, CPaaS platforms and wholesale carriers that originate calls on their own SIP networks.
Usually treated differently
Resellers and some MVNOs that do not control the network infrastructure needed to sign; they rely on the underlying provider but still have robocall mitigation duties.
Intermediate providers
Carriers that only transit calls must pass Identity headers unaltered, and under current rules the first intermediate provider in the path must authenticate unauthenticated SIP calls it receives. The 2026 proposals would extend that to all intermediate providers.
Software builders
If you build a dialler, AI calling product or PBX for others, your customer's provider signs the calls; your job is to send accurate caller ID and support the data needed for attestation.
Everyone in the call path also has duties beyond signing: a filed robocall mitigation plan in the Robocall Mitigation Database, know-your-customer checks, and taking action on traceback requests. Our TCPA compliance guide for AI outbound calling covers the consent side, and the AI calling laws by country guide covers rules outside the US.
The 2025 and 2026 rule changes
The rules have moved quickly. Some changes are in force; others are proposals still open for comment. Treat the table below as a map of what to check, and read the final orders before acting on anything marked "proposed".
| Change | Status | Date | What it means for you |
|---|---|---|---|
| Third-party authentication: sign with your own SPC token and certificate | In force | Effective 18 September 2025 | A vendor may perform the signing, but the certificate must be yours and the attestation decision must be yours. Keep records of the arrangement. |
| Codify A/B/C attestation criteria and ban improper attestations | Proposed (April 2026 notice) | Notice dated 29 April 2026 | Expect scrutiny of how you decide A versus B; document your logic now |
| Repeal remaining undue-hardship extensions | Proposed (April 2026 notice) | Notice dated 29 April 2026 | Providers still relying on an extension should plan to implement |
| Block unauthenticated SIP calls; intermediates must authenticate | Proposed (April 2026 notice) | Notice dated 29 April 2026 | Unsigned SIP traffic may stop being delivered; sign everything you originate |
| Stricter Robocall Mitigation Database filings, screening and audits | Proposed (July 2026 notice) | Notice dated 1 July 2026 | Keep your RMD filing accurate and up to date |
| Non-IP caller ID authentication | Pending proceeding | Proposed in April 2025 | Move TDM interconnects to SIP, or plan for a non-IP framework |
A note on dates: some trade articles reported 20 June 2025 as the deadline for the own-token rule. The Federal Register notice published on 19 August 2025 set the effective date as 18 September 2025.
Getting your SPC token and certificate
The trust chain starts with governance. The STI Governance Authority (STI-GA) sets the policy for who may receive a Service Provider Code (SPC) token. The STI Policy Administrator (STI-PA), operated by iconectiv, issues tokens. Approved Certification Authorities (STI-CAs) issue the certificates you sign with. Here is the path from nothing to signed calls.
1. Confirm your obligation
Work out whether you originate calls on your own SIP network with numbers you assign to customers, which creates a STIR/SHAKEN implementation obligation, or whether you resell another provider's service.
2. Complete the regulatory filings
Have a current FCC Form 499-A filing, an Operating Company Number and a Robocall Mitigation Database certification in place; the STI Governance Authority's token-access policy lists the current prerequisites.
3. Register with the STI Policy Administrator
Create an account with the STI-PA (operated by iconectiv) and request a Service Provider Code token.
4. Choose an approved Certification Authority
Pick an STI-CA approved by the Governance Authority and create a certificate signing request using your SPC token.
5. Publish the certificate
Host the certificate chain at a stable HTTPS URL; this URL goes in the x5u field of every PASSporT you sign.
6. Protect the private key
Keep the signing key in a hardware security module or a locked-down key store reachable only by your signing service.
7. Turn on signing and verification
Enable the Authentication Service on outbound calls and the Verification Service on inbound calls at your SIP edge, then test with your carriers.
8. Log and review attestations
Record the attestation level and reason for every signed call, keep records of any third-party signing arrangement, and review them regularly.
Certificates expire, so automate renewal and alerting from day one. A lapsed certificate means every outbound call goes out unsigned or fails verification at the far end, which shows up as a sudden drop in answer rates rather than an obvious error.
Where to sign: the SIP edge, not every PBX
On a platform with many PBXs, tenants or media servers, the cleanest design signs at the SIP edge: the Kamailio, OpenSIPS or session border controller layer that already sits between your platform and your carriers. Every outbound call passes through it, so you need only one copy of the private key and one place to log every attestation decision.
| Where you sign | Pros | Cons | Good for |
|---|---|---|---|
| SIP edge (Kamailio / OpenSIPS / SBC) | One key, one log, one config; PBXs stay simple | Edge needs access to number ownership data | Multi-tenant platforms, carriers, CPaaS |
| Each PBX (Asterisk / FreeSWITCH) | No extra component; works for a single PBX | Key copied to many servers; attestation logic duplicated | A single-company PBX with its own trunk |
| Signing-as-a-service vendor | Fast to start; vendor handles crypto | Must still use your own certificate and make attestation decisions; per-call fees | Smaller providers without in-house SIP engineers |
The edge needs to answer one question quickly for every call: which attestation does this caller ID earn? A local cache of the numbers table, refreshed from your provisioning database, keeps that lookup to a millisecond or two. Our Kamailio SBC configuration guide covers the rest of the edge: topology hiding, TLS, rate limiting and media relay.
Inside the Identity header
The Identity header carries a compact JSON Web Token followed by parameters. Decoded, the PASSporT has a header that says how it was signed and where to find the certificate, and a payload with the call details.
Identity: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9jZXJ0LmV4YW1wbGUubmV0L3NwLnBlbSJ9.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxMjEyNTU1MDEwMCJdfSwiaWF0IjoxNzk1MDcwMDAwLCJvcmlnIjp7InRuIjoiMTMxMjU1NTAxOTkifSwib3JpZ2lkIjoiNGQ2YjFjNGUtLi4uIn0.<signature>;info=<https://cert.example.net/sp.pem>;alg=ES256;ppt=shaken
# Decoded PASSporT header
{ "alg": "ES256", "ppt": "shaken", "typ": "passport",
"x5u": "https://cert.example.net/sp.pem" }
# Decoded PASSporT payload
{ "attest": "A",
"dest": { "tn": ["12125550100"] },
"iat": 1795070000, # signing time, seconds since epoch
"orig": { "tn": "13125550199" },
"origid": "4d6b1c4e-..." } # unique ID for tracebackThree fields cause most real-world problems. orig.tn must be the caller ID in normalised E.164 digits, so number formatting must be consistent across your platform. iat must be recent; verifiers reject tokens older than a short window (often 60 seconds), so server clocks must be synchronised with NTP. x5u must point to a certificate that is reachable over HTTPS from the public internet, every time.
Signing and verifying with Kamailio
Kamailio offers two maintained modules. stirshaken is built on SignalWire's libstirshaken and has no dependencies on other Kamailio modules; secsipid uses the libsecsipid library. Either works. The example below uses the stirshaken module's documented parameters and functions, and assumes your routing logic has already set the attestation level in a variable.
loadmodule "stirshaken.so"
# Authentication Service: default signing key
modparam("stirshaken", "as_default_key", "/etc/kamailio/stir/sp-key.pem")
# Verification Service
modparam("stirshaken", "vs_verify_x509_cert_path", 1)
modparam("stirshaken", "vs_ca_dir", "/etc/kamailio/stir/ca") # hashed STI-CA roots
modparam("stirshaken", "vs_identity_expire_s", 60)
modparam("stirshaken", "vs_cache_certificates", 1)
modparam("stirshaken", "vs_cache_dir", "/var/cache/kamailio/stir")
modparam("stirshaken", "vs_cache_expire_s", 300)
route[SIGN_OUTBOUND] {
# $avp(attest) was set to "A", "B" or "C" from the numbers table
if (!is_present_hf("Identity")) {
if (stirshaken_add_identity("https://cert.example.net/sp.pem",
"$avp(attest)", "$fU", "$rU", "") == 1) {
xlog("L_INFO", "SHAKEN signed $fU -> $rU attest=$avp(attest)\n");
} else {
xlog("L_ERR", "SHAKEN signing failed for $fU\n");
}
}
}
route[VERIFY_INBOUND] {
if (is_present_hf("Identity")) {
if (stirshaken_check_identity() == 1) {
append_hf("X-Shaken-Verstat: TN-Validation-Passed\r\n");
} else {
append_hf("X-Shaken-Verstat: TN-Validation-Failed\r\n");
}
} else {
append_hf("X-Shaken-Verstat: No-TN-Validation\r\n");
}
}Two practical notes. First, make sure $fU and $rU are already normalised to E.164 digits before signing; strip any plus sign or tech prefix in an earlier route. Second, certificate caching matters at volume: without it, every inbound call triggers an HTTPS download. The X-Shaken-Verstat header shown here is an internal convention for passing the result to your PBX, not a standard header, so remove it before calls leave your network.
Signing and verifying with Asterisk
Asterisk's res_stir_shaken module was refactored in 2024. In current releases, stir_shaken.conf has an attestation section, a verification section and named profiles, and each PJSIP endpoint points to a profile. The example follows the structure in the Asterisk documentation.
; /etc/asterisk/stir_shaken.conf [attestation] global_disable = no private_key_file = /var/lib/asterisk/keys/stir_shaken/sp-key.pem public_cert_url = https://cert.example.net/sp.pem attest_level = B ; default; override per tn where you can do better [verification] global_disable = no load_system_certs = no ca_path = /var/lib/asterisk/keys/stir_shaken/verification_ca cert_cache_dir = /var/lib/asterisk/keys/stir_shaken/verification_cache failure_action = continue ; or reject_request max_iat_age = 60 max_date_header_age = 60 [carrier_profile] type = profile endpoint_behavior = verify ; on: sign and verify; attest: sign only; verify: verify only [tenant_out_profile] type = profile endpoint_behavior = attest ; /etc/asterisk/pjsip.conf [carrier-trunk] type = endpoint stir_shaken_profile = carrier_profile [tenant-outbound] type = endpoint stir_shaken_profile = tenant_out_profile
On a single-company PBX this is all you need. On a platform with many Asterisk servers, it is usually better to sign at the edge, as described above, so the key is not copied to every server and attestation logic lives in one place. Check the Asterisk documentation for the version you run, as option names changed with the refactor.
FreeSWITCH and STIR/SHAKEN
FreeSWITCH's STIR/SHAKEN support is built on libstirshaken, the library SignalWire sponsored and later contributed to the community. It provides PASSporT signing and verification functions that FreeSWITCH applications and dialplan can call. Package names and configuration differ between FreeSWITCH versions and distributions, so follow the SignalWire FreeSWITCH documentation for your release rather than copying settings between versions.
In most FreeSWITCH estates we build, FreeSWITCH handles media and call logic while a Kamailio or OpenSIPS edge signs and verifies. That keeps the cryptography, certificate cache and attestation logic out of the media servers, which can then be added or replaced freely. The same pattern suits AI voice agent platforms that run on FreeSWITCH, as described in our SIP trunk and AI voice agent integration guide.
Where implementation effort usually goes (illustrative)
Illustrative split of engineering effort on a platform that signs at the SIP edge. Teams with messy number data spend far more on attestation logic.
Verifying inbound calls and using the result
Verification is the other half. When a call arrives with an Identity header, the Verification Service fetches the certificate from the x5u URL, checks it chains to a trusted STI-CA and is not revoked, checks the signature, compares the signed numbers with the SIP headers, and checks that the token is fresh. RFC 8224 defines response codes for failures.
| SIP response | Meaning | When you might send it |
|---|---|---|
| 428 Use Identity Header | The request should have carried an Identity header | Only where policy requires signed calls on that interconnect |
| 436 Bad Identity Info | The certificate URL could not be used | x5u unreachable or not HTTPS |
| 437 Unsupported Credential | The certificate is not trusted | Unknown CA, revoked or expired certificate |
| 438 Invalid Identity Header | The signature or token is invalid | Signature mismatch, numbers do not match, token too old |
Most platforms do not reject calls on a failed check. They pass the result to the destination as a verification status, feed it into spam scoring and show it to agents or AI voice agents. For example, an anti-fraud rule set can treat unsigned calls from unexpected origins differently, and a contact centre can show a "verified caller" badge on the agent screen.
Common failures and how to fix them
| Symptom | Likely cause | Fix |
|---|---|---|
| Every call fails verification at the far end | Certificate URL not publicly reachable or certificate expired | Monitor the x5u URL externally and automate renewal |
| Some calls fail with a stale token | Server clock drift | Run NTP or chrony on every signing server and alert on drift |
| Calls signed but caller ID shows as unverified | orig.tn format does not match the From or P-Asserted-Identity number | Normalise to E.164 digits before signing |
| Identity header missing at the terminating side | An intermediate SBC or a TDM hop stripped it | Test each carrier route; move TDM legs to SIP |
| A attestation on numbers you do not own | Attestation logic defaults to A | Default to B; grant A only on verified numbers |
| Verification adds noticeable post-dial delay | Certificates downloaded on every call | Enable certificate caching with a sensible expiry |
| Edge crashes on malformed certificates | Unhardened verifier | Keep libraries patched; interop testing in 2021 found such bugs in several stacks |
Implementation checklist
- Confirm with counsel whether you have a STIR/SHAKEN implementation obligation
- Keep your Form 499-A, OCN and Robocall Mitigation Database filing current
- Obtain your own SPC token and certificate, even if a vendor signs for you
- Store the private key in an HSM or locked-down key store
- Sign at the SIP edge with one key and one attestation service
- Build attestation from a numbers table linked to verified customers; default to B
- Normalise every number to E.164 before signing and before verifying
- Synchronise clocks on every signing and verifying server
- Cache downloaded certificates and monitor your own x5u URL
- Log attestation level and reason per call, and keep third-party signing records
- Test signed calls with each carrier, including after failover
- Track the 2026 proposals and update the logic when final rules are adopted
A real example: a WebRTC-to-SIP gateway platform
CelloIP built a WebRTC-to-SIP gateway for a North American VoIP and UCaaS provider, with a Kamailio edge in front of FreeSWITCH, carrying browser softphone, click-to-call, video and PSTN calls. In platforms like this, the Kamailio edge is the natural place for caller ID policy: it already normalises numbers, applies per-tenant rules and talks to every carrier.
If you are adding STIR/SHAKEN to an existing platform, the order that works best is usually: clean up number ownership data first, then put signing and verification on the edge, then add reporting. Doing it the other way round tends to produce A-attested calls on numbers nobody has verified.
CelloIP project outcome (client kept private)
Need STIR/SHAKEN signing, verification and attestation logic on Kamailio, OpenSIPS, Asterisk or FreeSWITCH? CelloIP builds and maintains SIP edges for VoIP and UCaaS providers.
Frequently asked questions
What is STIR/SHAKEN in simple terms?
It is a way for the provider that starts a call to vouch for the caller ID digitally. The provider signs the call with a certificate, the terminating provider checks the signature, and the result helps decide whether the call is shown as verified, labelled as spam or blocked. STIR is the IETF set of standards for the signature; SHAKEN is the ATIS framework for how carriers use it.
What do attestation levels A, B and C mean?
A (full) means the signing provider knows the customer making the call and has verified that the customer may use the calling number. B (partial) means the provider knows the customer but cannot verify the number. C (gateway) means the provider is passing the call on from a source it cannot authenticate, such as an international gateway. Only A tells the terminating side that both the caller and the number were checked.
Do I need my own SPC token?
If your company has a STIR/SHAKEN implementation obligation under FCC rules, yes. The third-party authentication rules that took effect on 18 September 2025 require such providers to get their own SPC token and certificate and to sign calls with them, even when a vendor performs the signing. Providers that do not control the network infrastructure needed to sign, such as many resellers, are treated differently, so check your position with counsel.
Can Kamailio, Asterisk and FreeSWITCH do STIR/SHAKEN?
Yes. Kamailio has two maintained modules, stirshaken (built on libstirshaken) and secsipid. Asterisk has res_stir_shaken, configured in stir_shaken.conf and enabled per PJSIP endpoint with a profile. FreeSWITCH uses SignalWire's libstirshaken. Most VoIP platforms sign and verify at the SIP edge rather than on every PBX.
Does STIR/SHAKEN stop robocalls on its own?
No. It makes caller ID spoofing easier to detect and gives terminating providers a signal for analytics, labelling and blocking. It does not judge whether a call is wanted. That is why the FCC pairs it with robocall mitigation plans, the Robocall Mitigation Database and know-your-upstream-provider duties.
What changed for STIR/SHAKEN in 2026?
In 2026 the FCC issued further proposals rather than final rules: an April 2026 notice proposes codifying the attestation criteria, repealing the remaining hardship extensions, requiring every provider that serves end users to make attestation decisions and requiring blocking of unauthenticated SIP calls. A July 2026 notice proposes stricter Robocall Mitigation Database filings. Check the final orders before you rely on any of these.
Does STIR/SHAKEN work on TDM or non-IP networks?
Not natively. SHAKEN is built for SIP, so the Identity header is lost when a call crosses a TDM link. The FCC has a pending proceeding on non-IP caller ID authentication; until it concludes, providers with non-IP networks must show reasonable progress toward a solution. Moving interconnects to SIP is the usual fix.
How long does a STIR/SHAKEN implementation take?
The technical part, signing and verifying at a Kamailio or SBC edge with attestation logic and logging, is often a few weeks of engineering once you have a token and certificate. Getting the token depends on your regulatory filings. The attestation logic, which needs accurate number ownership data, usually takes the most thought.
This guide explains technical implementation and public FCC documents. It is not legal advice; confirm your obligations with telecom counsel.
Work with CelloIP
Adding STIR/SHAKEN to your VoIP platform?
CelloIP engineers SIP edges, softswitches and hosted PBX platforms on Kamailio, OpenSIPS, Asterisk and FreeSWITCH, including caller ID signing, verification and attestation logic. We reply within one business day, and you own the code.