Identity header anatomy
A STIR/SHAKEN Identity header carries a signed PASSporT token plus parameters describing the signing algorithm, PASSporT type and certificate location. Its presence alone is not authentication: the verifier must parse the token, retrieve and validate the certificate under the applicable trust framework, verify the signature and compare signed claims with the SIP request.
Identity: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9jZXJ0cy5leGFtcGxlLmNvbS9leGFtcGxlLnBlbSJ9.eyJhdHRlc3QiOiJCIiwiZGVzdCI6eyJ0biI6WyIxMjAyNTU1MDEyMyJdfSwiaWF0IjoxNzg5MzE1MjAwLCJvcmlnIjp7InRuIjoiMTIwMjU1NTAxMjMifSwib3JpZ2lkIjoiNTUwZTY4NDAtZXhhbXBsZSJ9.REDACTED_SIGNATURE;info=<https://certs.example.com/example.pem>;alg=ES256;ppt="shaken"Decode claims without treating them as trusted
{
"alg": "ES256",
"ppt": "shaken",
"typ": "passport",
"x5u": "https://certs.example.com/example.pem"
}
{
"orig": { "tn": "12025550123" },
"dest": { "tn": ["12025550123"] },
"iat": 1789315200,
"attest": "B",
"origid": "550e6840-example"
}alg names the signature algorithm, ppt the PASSporT extension, typ the token type, and x5u a certificate URL. orig and dest bind calling and called identity; iat limits freshness; attest states the signer’s relationship/knowledge; origid correlates origination. Decoding Base64URL proves no signature.
Trust and certificate retrieval flow
In the U.S. framework, the Policy Administrator governs authorization and SPC token relationships, an approved STI Certification Authority issues certificates, the authentication service signs, and the verification service validates. Certificate retrieval must resist unsafe URL behavior and validate chain, authorization and freshness. A reachable x5u is not sufficient.
Why a hand-written header is invalid
# Concept only — this does NOT create a valid Identity header
printf 'header.payload.fake-signature'
# A valid signature requires the authorized private key and canonical PASSporT processing.Editing JSON or pasting an encoded token changes the signed bytes and invalidates the signature. A private key alone is also insufficient if its certificate and authorization are not valid for the telephone number and trust framework. Never extract signing keys into shell history or public build files.
Modern Asterisk object relationship
[verification]
type=verification
load_system_certs=no
ca_path=/etc/asterisk/keys/stir-example/ca
cert_cache_dir=/var/lib/asterisk/stir-example/cache
failure_action=continue
curl_timeout=5
max_iat_age=60
[example-tn]
type=tn
; Consult the installed sample for current required fields.
; Private signing key and authorized certificate paths remain private.
[carrier-profile]
type=profile
; Associate the reviewed verification/attestation behavior.
[carrier-endpoint]
type=endpoint
stir_shaken_profile=carrier-profileThis deliberately incomplete skeleton shows separation between global verification, telephone-number signing material, a profile and the PJSIP endpoint. It is not deployable and does not claim ARCAMUSA owns an SPC token, certificate, Option 1 status or live signing capability. Populate only from the installed official sample and authorized trust materials.
Validate modules, configuration and certificates
sudo asterisk -rx "module show like stir_shaken"
sudo asterisk -rx "stir_shaken show settings"
sudo asterisk -rx "stir_shaken show profiles"
openssl verify -CAfile /etc/asterisk/keys/stir-example/ca-chain.pem /etc/asterisk/keys/stir-example/example-x5u.pem
# Supported newer branches may provide:
sudo asterisk -rx "stir_shaken verify certificate_file /etc/asterisk/keys/stir-example/example-x5u.pem"/etc/asterisk/keys/stir-example/example-x5u.pem: OK
# Illustrative chain result; authorization and PASSporT signature still require validation.The Asterisk certificate verification command is available only in specified supported patch versions documented upstream. Chain success does not prove the certificate is authorized for the calling number or that a particular Identity signature is valid. Inspect the verification result produced for the actual INVITE.
Verification evidence matrix
| Observation | Meaning | Next evidence |
|---|---|---|
| Identity absent | No token delivered on this hop. | Policy, signing eligibility and upstream handling. |
| Token decodes | Serialization is parseable. | Signature and claim binding remain unproven. |
| x5u unreachable | Certificate retrieval failed. | DNS/TLS/HTTP policy and safe URL restrictions. |
| Certificate chain invalid | Trust validation failed. | Issuer, expiry, CRL and configured trust store. |
| Signature invalid | Signed bytes/key do not verify. | Token integrity and authorized certificate. |
| orig/dest mismatch | Claims do not bind to SIP identities. | Normalization and request identity. |
| iat stale | Token falls outside freshness policy. | Clock and generation time. |
| Attestation C | Signer asserts gateway-level knowledge. | Do not reinterpret it as a fraud verdict. |
Security and privacy notes
Identity tokens contain calling/called numbers, timestamps, origination identifiers and certificate locations. Restrict logs, prevent arbitrary certificate-fetch destinations, retain only necessary incident evidence and never publish private keys. Do not weaken x5u scheme/path restrictions as a default workaround; official Asterisk documentation warns that relaxation options can have serious security implications.
Rollback
If a new profile causes unexpected treatment, restore the previous endpoint/profile association during an approved window while preserving verification evidence. Do not silently disable verification or signing as a permanent fix. Revoke or rotate compromised key material through the authorized governance process, not by merely changing a local file.
Related engineering resources
Bind verified claims to the SIP request
Signature success is one stage. The verifier must also compare the PASSporT origin and destination claims with normalized SIP identities, enforce freshness, evaluate certificate authorization and apply local policy to the verification result. Normalization must be documented because punctuation, country codes and URI schemes can otherwise produce false mismatch decisions. Attestation describes the signer’s asserted relationship; it is not a guarantee that the call is wanted or non-fraudulent.
Preserve the verification outcome rather than the full token whenever that satisfies the operational need. A downstream network may add, remove or replace Identity information according to its role and policy, so identify the hop where the header was observed. Missing Identity is neutral evidence until the applicable obligation and interconnection behavior are known.
Certificate retrieval and cache controls
The verifier retrieves the x5u certificate over an allowed secure scheme, validates the server connection as applicable, constrains the destination to avoid server-side request abuse, and validates the certificate chain and authorization. Cache policy must balance availability with certificate expiry, revocation and maximum entry age. Retrieval success alone does not validate the PASSporT.
Monitor timeout, DNS failure, HTTP/TLS failure, invalid content, chain failure and signature failure as separate outcomes. Do not relax x5u port or path restrictions globally to diagnose one certificate. Use the official verification command where supported and a protected sample certificate; never download a private signing key from x5u.
Authoritative references
Inputs you need from your peer
| Peer-provided value | Object or parameter that consumes it |
|---|---|
| Authorized originating identities | signing policy and orig claim |
| STI-PA/SPC authorization | certificate enrollment process |
| STI certificate and x5u publication | signing profile and Identity info parameter |
| Accepted attestation policy | attestation assignment |
| Verifier trust and cache requirements | certificate retrieval and validation policy |
Implementation closure
Authorized originating identity, attestation policy, STI-PA/SPC authorization, STI certificate and private-key custody, x5u URL, trust-store policy, and verifier clock requirements.
Signing/verifying service or supported Asterisk STIR/SHAKEN objects, certificate retrieval/cache policy, and SIP Identity handling.
Validate authorization and certificate chain in a controlled environment before enabling signing or verification. Use only the reload/restart behavior documented for the installed implementation.
Signature, certificate trust and authorization, freshness, orig/dest binding, and policy outcome all verify for controlled calls.
Separate token parsing, x5u retrieval, chain/authorization, signature, time, identity binding, and attestation-policy failures.
Stop if the signing identity is unauthorized, private-key custody is uncertain, x5u is not safely retrievable, or a hand-built token is proposed for production.
Controlled signed calls validate end to end, failure cases are observable, certificate renewal and rollback are tested, and attestation is assigned by documented policy.