TABLE OF CONTENTS
STIR/SHAKEN compliance refers to the implementation of a framework aimed at combating illegal robocalls and caller ID spoofing in telecommunications. STIR stands for Secure Telephone Identity Revisited, and SHAKEN stands for Signature-based Handling of Asserted Information Using toKENs. Together, they form a set of protocols and standards designed to ensure the integrity of caller ID information.
PBXware added its implementation of STIR/SHAKEN which allows signing and validating calls with valid STIR/SHAKEN certificates that customers own.
We do not provide certificates.
Purpose of STIR/SHAKEN
STIR/SHAKEN is used to:
- Verify Caller ID Authenticity: Prevent bad actors from using spoofed caller IDs to trick recipients into answering calls or engaging in fraudulent activities.
- Reduce Fraud: Protect consumers and businesses from scams, such as phishing and robocall schemes.
- Improve Trust in Communications: Build confidence in the legitimacy of incoming calls by ensuring they are correctly identified.
- Enable Blocking: Help service providers and end-users block or flag suspicious calls more effectively.
How It Works
STIR/SHAKEN operates as follows:
- Caller Authentication: When a call is initiated, the originating service provider verifies the caller's identity.
- Digital Signature: The provider attaches a digital certificate (token) to the call, affirming the caller's authenticity and legitimacy.
- Verification by Recipient's Provider: The receiving service provider checks the digital signature against a trusted database to confirm the caller's identity.
- Call Labeling: Depending on the verification outcome, the call is labeled as Verified, Not Verified, or Suspicious.
Why Is It Used?
- Compliance with Regulations: Many countries, including the United States, require service providers to implement STIR/SHAKEN under regulatory mandates (e.g., the TRACED Act in the U.S.).
- Consumer Protection: By reducing caller ID spoofing, STIR/SHAKEN safeguards consumers against fraudulent or misleading calls.
- Industry Standardization: Establishes a uniform approach across carriers, enabling better cooperation and effectiveness.
- Regaining Consumer Trust: Helps rebuild trust in phone communications, especially for businesses relying on outbound calls for legitimate purposes.
Incoming calls
There are 2 ways of using STIR/SHAKEN for Caller ID verification on incoming calls and these 2 are not related (Can be used both at the same time, but do not depend on each other).
1. Call Filtering on Slave Tenant
PBXware STIR/SHAKEN Call Filtering works in a way where it is expected from providers to complete the whole process of Caller ID verification and pass a parameter value in the P-Asserted-Identity SIP header which is by default named 'verstat'. The users can reject calls depending on the value of the verstat parameter by enabling call filtering.
Enable Call Filtering option can be enabled per tenant and the user can choose the statuses for which he wants the calls to be rejected.
This means that PBXware does not perform any kind of validation or call signing. It just checks if the value under the verstat parameter matches one of the values that are listed in the Drop Calls with Verification Status dropdown.
Here is an example of the PAI header verstat parameter.
P-Asserted-Identity: <sip:+1234567890;[email protected]:xxxx>.
It is also possible that the 'P-Asserted-Identity' header has one of the following values: 'TN-Validation-Passed', 'TN-Validation-Failed', or 'No-TN-Validation', while the level can be seen in a new header, for example: 'P-Attestation-Indicator: B'.
P-Asserted-Identity: <sip:+1234567890;[email protected]:xxxx>
P-Attestation-Indicator: B
In case a user selects 'TN-Validation-Failed-B' and 'No-TN-Validation' as values for 'Drop Calls with Verification Status', the call will be dropped as it matches 'TN-Validation-Failed' plus 'B'.
There are three options in the STIR/SHAKEN section that can be configured per Tenant Level:
- PAI Header Parameter Name
Set this field to a desired value
(E.g. 'verstat')
NOTE: This parameter is parsed for the caller ID validation and it is generally named 'verstat'. Other variations depend on the Trunk provider.
- Enable Call Filtering
Enable PBXware STIR/SHAKEN Call Filtering
(E.g. Yes/No)
- Drop Calls with Verification status
Select for which verification status calls will be dropped
(E.g. 'TN-Validation-Failed')
The PAI header value will be parsed and if the given parameter is set and contains any of the selected values from the 'Drop Calls with Verification status' list, the call will be dropped.
Please refer to the list of verification statuses:
No-TN-Validation
- No validation was performed on the telephone number.
- Possible reasons: network limitations, non-participation in STIR/SHAKEN, or calls originating from legacy systems.
TN-Validation-Failed
- The validation process failed.
- Indicates that the caller's identity could not be verified, suggesting a potential spoofed or illegitimate caller ID.
TN-Validation-Passed-B
- Indicates Partial Attestation (B-level):
- The originating network validated that the call originated from one of its subscribers or endpoints but could not confirm the actual telephone number used.
- Trust level is moderate.
TN-Validation-Passed-C
- Indicates Gateway Attestation (C-level):
- The originating network knows only the source of the call (e.g., a gateway) but cannot authenticate the caller ID.
- Trust level is low.
TN-Validation-Failed-A
- The validation failed for a call that should have had Full Attestation (A-level).
- Suggests that the caller ID was expected to be fully validated but couldn't be authenticated.
- This is a stronger failure indication compared to general validation failure.
TN-Validation-Failed-B
- Validation failed for a call with Partial Attestation (B-level).
- Indicates issues in verifying the subscriber or endpoint within the network.
TN-Validation-Failed-C
- Validation failed for a call with Gateway Attestation (C-level).
- Indicates issues with even the minimal validation expected from the gateway level.
NOTE: Please note that verification statuses are case insensitive which means that all three of the following options are acceptable: ‘No-TN-Validation’, ‘NO-TN-VALIDATION’, and ‘No-tn-Validation’.
This will only work for calls from Trunks.
Case #1
Enable Call Filtering: Yes
Drop Calls with Verification Status: TN-Validation-Failed-B, No-TN-Validation
Validate Incoming Calls: No
If we take a look at the CLI report we will see something like this:
In SNGREP we see the following:
This indicates that the Call Filtering was enabled and in PAI there was 'TN-Validation-Failed-B' sent. As that value was set under filters to drop calls with that value in PAI, the call was dropped on the PBXware side.
2. Call validation on Master Tenant
Besides Call Filtering using the PAI header, PBXware also added its implementation of STIR/SHAKEN which allows signing and validating calls with valid STIR/SHAKEN certificates that customers own. These options are added on Master Tenant and in order to have these options, STIR/SHAKEN needs to be enabled in license.
The certificate that was obtained is uploaded to Master Tenant.
If the 'Validate Incoming Calls' option is set to 'Yes', the Identity header will be checked for incoming calls, and STIR/SHAKEN validation will be done. If the Identity header is not present or is invalid, the call will be dropped.
Please note that once the certificate and key are uploaded, they will be verified. If the verification fails (e.g. the certificate is invalid or a certificate/key pair is not correct), the following error message will be displayed:
In case the verification is successful, users will be able to see more information including the certificate expiry date.
Case #2
Enable Call Filtering: Yes
Drop Calls with Verification Status: TN-Validation-Failed-B, No-TN-Validation
Validate Incoming Calls: Yes
In this case, the Call Filtering check will be executed first and after that, the Identity header will be checked. If the verstat parameter contains the same value in the PAI header as in the previous example (TN-Validation-Failed-B) the result will be the same, no matter if the Identity header is set or not. The call will be dropped because the PAI status matches the selected TN-Validation-Failed-B status.
Case #3
Enable Call Filtering: Yes
Drop Calls with Verification Status: TN-Validation-Failed-C, No-TN-Validation
Validate Incoming Calls: Yes
Let’s say that the verstat value does not match any selected status and the Call Filtering does not result with rejecting the call. Here is an example of sngrep log:
INVITE sip:24843636000108.60.153.175:9395 SIP/2.0
Via: SIP/2.0/UDP64.136.173.31:5060;branch=z9hG4bKlsansav556738916rdb15303
Record-Route:‹sip:[email protected]:5060;lr;transport=udp>
To:
From:
Call-ID:[email protected]
CSeg: 1 INVITE
Contact:
Supported: timer
Session-Expires:1800;refresher=uac
Min-SE: 90
P-Asserted-Identity:
Identity: eyJhbGciOiAiRVMyNTYiLCJwcHQiOiAic2hha2VuIiwidHlwIjogInBhc3Nwb3J0IiwieDV1IjogImh0dHBzOi8vY2VydGlmaWNhdGVzLmNsZWFyaXAuY29tL2IxNWQ3Y2M5LTBmMjYtNDZjMi04M2VhLWEzZTYzYTgyZWMzYS83Y2M0ZGI2OTVkMTNlZGFkYTRkMWY5ODYxYjliODBmZS5jcnQifQ.eyJhdHRlc3QiOiAiQSIsImRlc3QiOiB7InRuIjogWyIxNDA0NTI2NjA2MCJdfSwiaWF0IjogMTU0ODg1OTk4Miwib3JpZyI6IHsidG4iOiAiMTgwMDEyMzQ1NjcifSwib3JpZ2lkIjogIjNhNDdjYTIzLWQ3YWItNDQ2Yi04MjFkLTMzZDVkZWVkYmVkNCJ9.S_vqkgCk88ee9rtk89P6a6ru0ncDfSrdb1GyK_mJj-10hsLW-dMF7eCjDYARLR7EZSZwiu0fd4H_QD_9Z5U2bg;info=<https://certificates.clearip.com/b15d7cc9-0f26-46c2-83ea-a3e63a82ec3a/7cc4db695d13edada4d1f9861b9b80fe.crt>alg=ES256;ppt=shaken
Max-Forwards: 147
Content-Type: application/sdp
Content-Length: 299
In this case, after the PAI header check is completed and the call is not dropped, the incoming call validation will be executed (the Identity header will be checked). If the Identity header is not set or it is set but not valid, the call will be dropped and in asterisk log these messages can be seen:
*** MISSING ***
== agi://127.0.0.1: [1654699374.18] STIR/SHAKEN Call Filtering enabled ...
== agi://127.0.0.1: [1654699374.18] STIR/SHAKEN call check starting
== agi://127.0.0.1: [1654699374.18] Missing identity header, STIR/SHAKEN Caller ID verification failed
*** VALIDATION FAILED ***
== agi://127.0.0.1: [1654699374.18] STIR/SHAKEN Call Filtering enabled ...
== agi://127.0.0.1: [1654699374.18] STIR/SHAKEN call check starting
== agi://127.0.0.1: [1654699374.18] Validation request did not return valid value, STIR/SHAKEN Caller ID verification failed
In case the validation is completed successfully the following messages will be in the asterisk log:
== agi://127.0.0.1: [1654699374.18] STIR/SHAKEN Call Filtering enabled ...
== agi://127.0.0.1: [1654699374.18] STIR/SHAKEN call check starting
== agi://127.0.0.1: [1654699374.18] STIR/SHAKEN check passed successfully
Call Signing
Based on the uploaded certificate the call will be signed and the Identity header will be set.
== agi://127.0.0.1: [1654699386.73] Setting SIP header 'Identity' ...
== agi://127.0.0.1: [1654699386.73] Setting SIP header 'Date' …
If the certificate is missing the following message will be displayed in asterisk log:
agi://127.0.0.1: [1654693785.4] Could not find certificate file on this system, can't sign STIR/SHAKEN call correctly
NOTE: In this case, the call will not be dropped, it will just not be signed (the Identity header will not be set).
Outbound calls
PBXware does not currently perform caller ID verification or signing based on its validation. However, if a valid certificate provided by the service provider is uploaded to PBXware, a hidden option can be enabled to ensure that all calls are signed with A-level attestation.
NOTE: A hidden option is available from 6.7.5 PBXware and before the mentioned version, a patch needs to be applied.
To verify that A-attestation is sent on the outbound call, the 'Identity header' needs to be obtained from the SIP trace and decoded. For decoding, we can use JWT.
Here, we paste the Identity header and check the payload.
