Configuring STIR/SHAKEN
Last updated
Last updated
In PortSIP PBX, you can configure the system to drop inbound calls on a specified SIP trunk based on Caller ID verification - when the trunk provider passes a parameter value in the P-Asserted-Identity SIP header in the INVITE message, which by default is named 'verstat'. Additionally, you can also upload the STIR/SHAKEN certificate to sign outbound calls on a specified SIP trunk.
To configure call handling based on verification status:
Navigate to Call Manager > Trunks.
Double-click the trunk you want to edit.
Click the Inbound Parameters tab.
In the STIR/SHAKEN section, you will find three configurable options, which can be set at the trunk level.
These options allow you to customize how the PBX handles calls based on STIR/SHAKEN verification status for each trunk.
Set this field to your desired value, it's 'verstat' by default.
This parameter is used for caller ID validation and is typically named 'verstat'. However, the exact name may vary depending on your trunk provider.
This option allows you to enable or disable PortSIP PBX's validation of inbound calls based on STIR/SHAKEN Caller ID verification.
This option allows you to select which verification status will trigger call drops when Enable STIR/SHAKEN Validation is enabled.
For example, selecting 'TN-Validation-Failed' means that if the PAI header contains this verification status, the call will be dropped.
The PAI header value will be parsed, and if the specified parameter matches any of the selected values in the Drop Calls with Verification Status list, the call will be dropped.
Refer to the list of verification statuses:
No-TN-Validation
TN-Validation-Failed
TN-Validation-Passed-B
TN-Validation-Passed-C
TN-Validation-Failed-A
TN-Validation-Failed-B
TN-Validation-Failed-C
Note: Verification statuses are case-insensitive, meaning all variations (e.g., 'No-TN-Validation', 'NO-TN-VALIDATION', and 'No-tn-Validation') are acceptable.
This feature applies only to the inbound calls received from this trunk.
If a call is received from the SIP trunk with the following PAI header:
Please note that the additional header check is included for STIR/SHAKEN. The P-Asserted-Identity can contain one of the following values: 'TN-Validation-Passed', 'TN-Validation-Failed', or 'No-TN-Validation'. The attestation level is specified in a separate header, such as P-Attestation-Indicator: B.
If a user selects 'TN-Validation-Failed-B' and 'No-TN-Validation' as values in the Drop Calls with Verification Status field, the call will be dropped, since it matches 'TN-Validation-Passed' with 'B' as the attestation level.
However, if no attestation indicator is provided, the PBX expects an exact match between the verstat value in the PAI header and the value specified in the Drop Calls with Verification Status field. For example:
To sign outbound calls on a trunk, you must follow the process of obtaining your own STIR/SHAKEN certificate. This involves the following steps:
Acquire a US FCC 499-A Filer ID and an Operating Company Number (OCN).
After securing these, you can then proceed to apply for your STIR/SHAKEN token and certificate, which are required for authenticating calls.
To implement STIR/SHAKEN, follow these steps:
Obtain an FCC 499 ID Apply for and receive an FCC 499-A Filer ID, which is necessary for companies providing telecom services in the U.S.
Get an Operating Company Number (OCN) An OCN is a 4-character identifier assigned to telecom companies in North America. You’ll need this to proceed with certification.
Acquire Your iConnectiv Token iConnectiv is the designated policy administrator for the STIR/SHAKEN framework. Obtain your token through their portal.
Partner with a Certificate Authority (CA) Collaborate with a trusted Certificate Authority (CA) to issue your STIR/SHAKEN certificate, enabling you to sign and authenticate your outbound calls.
You can upload the STIR/SHAKEN certificate either at the System Administrator level or the Tenant level, depending on the scope of the calls.
The PBX will use the System Administrator's certificate to sign calls on trunks that are added by the System Administrator.
Tenant-level certificates are used to sign calls on trunks that are added by the Tenant Administrator.
Navigate to Advanced > Settings in the menu.
Select the STIR/SHAKEN Certificates tab.
Open your STIR/SHAKEN certificate file using Windows Notepad, then copy and paste its contents into the Public Certificate field.
Similarly, open your STIR/SHAKEN private key file using Windows Notepad, and copy and paste the contents into the Private Key field.
Click OK to save your changes.
Navigate to Advanced > STIR/SHAKEN in the menu.
Open your STIR/SHAKEN certificate file using Windows Notepad, then copy and paste its contents into the Public Certificate field.
Similarly, open your STIR/SHAKEN private key file using Windows Notepad, and copy and paste the contents into the Private Key field.
Click OK to save your changes.
To enable the STIR/SHAKEN signature on a specific trunk, follow these steps:
Go to Call Manager > Trunks.
Double-click the trunk you wish to edit.
Select the Options tab.
Toggle on the STIR/SHAKEN Signature Required option.
Click OK to save your changes.
Now that you’ve enabled the STIR/SHAKEN signature, when an extension makes an outbound call over a trunk where the STIR/SHAKEN Signature Required option is enabled, the PortSIP PBX will sign the call using the uploaded certificates. It will then add an Identity header to the INVITE message, which contains the call signature. The INVITE message will look similar to the following example:
