STIR/SHAKEN Caller ID Authentication

Attestation Levels

When a provider signs a call, it assigns an attestation level based on what it knows about the caller and the caller's right to use the asserted telephone number:

Attestation is assigned by the signing service provider. A PBX cannot obtain A attestation merely by setting a configuration option. The provider must have an authorized certificate and must be able to validate the relationship between the customer and the calling number.

Asterisk Configuration

Configuration is split between stir_shaken.conf and pjsip.conf. The following is a minimal outline. Production deployments should also configure the appropriate STI certificate authority chain.

Example stir_shaken.conf:

[general]
cache_max_size = 1000

[attestation]
attest_level = B
private_key_file = /etc/asterisk/keys/stir_shaken_key.pem
public_cert_url = https://example.com/certs/stir_shaken_cert.pem
check_tn_cert_public_url = yes

[verification]
ca_file = /etc/asterisk/keys/stir_shaken-ca.pem
max_iat_age = 15
max_cache_entry_age = 3600
max_cache_size = 1000

Option names and defaults vary by Asterisk branch. In current documentation, the attestation key is private_key_file, not private_key_path. Verification may also use ca_path, cert_cache_dir, CRL files, and X5U access controls. The CA file or directory must contain the trusted root, issuing CA, and required intermediate certificates.

The general section's cache_max_size setting is shown in older Asterisk documentation. The verification section uses max_cache_size.

PJSIP endpoint configuration:

[mytrunk]
type = endpoint
; ... other settings ...
stir_shaken = yes
; Optional:
; stir_shaken_profile = my-profile

The endpoint option enables STIR/SHAKEN processing. On incoming INVITEs, Asterisk checks the Identity header. On outgoing INVITEs, Asterisk adds an Identity header when it has the required signing configuration.

For reusable behavior and verification policies, define a profile in stir_shaken.conf and reference it with stir_shaken_profile. Profile endpoint_behavior values include:

• off - Do not perform STIR/SHAKEN processing
• attest - Attest outgoing calls
• verify - Verify incoming calls
• on - Attest outgoing calls and verify incoming calls

These profile values should not be confused with the endpoint's boolean stir_shaken option.

Verification in Dialplan

The STIR_SHAKEN() function uses an identity index. First check the number of results, then retrieve values from a selected result:

[from-trunk]
exten => _X.,1,NoOp(Call from ${CALLERID(num)})
 same => n,Set(STIR_COUNT=${STIR_SHAKEN(count)})
 same => n,GotoIf($[${STIR_COUNT} = 0]?unverified)
 same => n,Set(ATTEST=${STIR_SHAKEN(0,attestation)})
 same => n,Set(VERIFY=${STIR_SHAKEN(0,verify_result)})
 same => n,GotoIf($["${VERIFY}" = "passed"]?verified:unverified)
 same => n(verified),Set(CALLERID(name)=Verified ${ATTEST})
 same => n,Goto(continue)
 same => n(unverified),Set(CALLERID(name)=Unverified)
 same => n(continue),Dial(PJSIP/100)

The available values include identity, attestation, and verify_result. The exact verification result values and failure handling depend on the Asterisk branch and configuration. Test the result on the target release rather than assuming that a missing, failed, or untrusted Identity header should be treated as equivalent to a passed verification.

By default, verification failures can continue to the dialplan. Configure failure_action as appropriate, or use the dialplan result and PJSIPHangup() when calls should be rejected. Asterisk also supports RFC 8224 response behavior and optional RFC 9410 Reason headers.

Common use cases:

• Label calls in caller ID based on verification and attestation results
• Route unverified calls to voicemail or an IVR screening flow
• Log verification results for operational and compliance reporting
• Reject or limit calls according to a documented fraud policy

When to Sign Calls Yourself

Most enterprise Asterisk deployments do not sign calls directly. The ITSP receives the SIP INVITE, assigns the appropriate attestation, signs it with its authorized certificate, and forwards it.

You would sign calls yourself only when you operate within the SHAKEN governance model and have:

1. An authorized service-provider identity and SPC token
2. An appropriate signing certificate from the relevant STI-CA or STI-PA process
3. Valid private-key and public-certificate configuration
4. Telephone-number configuration and authorization for the numbers being asserted

For a production enterprise PBX, the usual flow is:

Asterisk sends an INVITE to the ITSP, the ITSP signs the call, the downstream provider verifies it, and the terminating network applies its own call-labeling or blocking policy.

Signing locally may be pointless if the ITSP strips the Identity header, rewrites the calling number, or signs the call again. Confirm the provider's behavior before enabling local signing.

Certificate Trust and Hierarchy

STIR/SHAKEN deployments use governance and certificate authorities that establish trust in signing certificates:

• STI-GA, or Governance Authority: Defines governance policies and authorizes policy administrators.
• STI-PA, or Policy Administrator: Handles provider authorization and certificate policy for the ecosystem. In the United States, iconectiv operates the STI-PA.
• STI-CA, or Certification Authority: Issues signing certificates under the applicable policy.
• Service-provider certificate: The certificate and private key used by an authorized provider to sign calls.

Asterisk verification needs the trusted CA chain, while signing needs the authorized private key and a publicly reachable certificate URL. Do not treat a self-signed certificate as a production SHAKEN certificate.

Practical Guidance

Ask your ITSP:

1. Do you sign my outbound calls?
2. What attestation level do you normally assign?
3. What evidence is required for A attestation?
4. Do you pass inbound Identity headers to my PBX?
5. Do you strip or replace Identity headers on outbound calls?
6. Which Asterisk or SIP configuration is required on your side?
7. How can I test the resulting attestation and verification status?

Checking attestation on outbound calls:

• Capture the SIP INVITE with sngrep or a controlled packet capture and inspect the Identity header
• Call a test destination that reports STIR/SHAKEN results
• Use the ITSP's debug portal or attestation reports
• Verify that the provider did not rewrite the calling number or remove the Identity header

Protect private keys, use accurate system time through NTP, and make the certificate URL reachable over HTTPS. Avoid making call-blocking decisions based only on the presence of an Identity header. A present header can still fail signature, certificate, timestamp, or caller-ID consistency checks.

Common misconfigurations:

Limitations

• Calls over non-SIP protocols such as IAX2 and H.323 are not signed by the PJSIP STIR/SHAKEN module
• TDM-to-IP gateway calls may receive C attestation because there is no upstream cryptographic identity
• International interoperability and attestation depend on the destination ecosystem and current provider support
• A private Asterisk-to-Asterisk deployment can exchange STIR/SHAKEN information, but local signing still requires appropriate certificates and trust configuration
• An attestation level is not a guarantee that a call is legitimate. It is one input to provider and terminating-network policy