Rejecting Calls During Verification
You can configure the SBC to reject calls based on the verstat and reason code from sti-vs server. To perform this function, you configure a sti-response-treatment-entry element and apply it to the sti-config or sti-server. The SBC uses each entry to determine whether to reject any call that matches the entry with the verstat and/or reasoncode in an STI-VS response. This function applies to both ATIS and 3GPP deployments.
When you have configured the SBC for STI treatment and it receives an INVITE that results in an STI-VS response that includes specific verstat and/or reason code information, the SBC can reject the call. The SBC compares the verstat and, depending on the message, the HTTP reason-code provided by the STI server, to establish a match with your configuration and determine whether or not to reject the call. This rejection consists of sending a SIP message to notify the caller of the reason for rejecting the call, using your mapped sip-reason-code and sip-reason-text. Having sent this message, the SBC then drops the call.
To configure this function, you create one or more sti-response-treatment-config elements under session-router. Each sti-response-treatment-config has a name and one or more sti-response-treatment-entries parameter(s). The sti-response-treatment-entries is a multi-instance sub-element that includes the details for rejecting a call.
Parameters include:
- verstat—This mandatory parameter specifies the actionable verstat value returned in the STI-VS response. Values include TN-Validation-Passed, TN-Validation-Failed, No-TN-Validation, or custom, which you define.
- reason-code—Specifies the reason code as
returned in the STI-VS response. Values include 403, 428, 436, 437, 438, or a custom
value you specify within the range of 1xx to 5xx.
You leave this parameter empty if you want to reject the call based on the verstat only.
- role—Specifies whether this rule applies to
verification (STI-VS) or authentication (STI-AS).
Note:
The only supported value in the S-Cz9.3.0 software version is STI-VS. - sip-reason-code—Specifies the SIP reason code the
system uses to generate the SIP response. Values include 403, 428, 436, 437, 438, or
a custom value you specify within the range of 4xx to 6xx.
You can leave this parameter empty if you want to use the reasoncode provided by the STI-VS in the final SIP response. If the parameter is empty and the STI-VS does not return a reasoncode, the system uses the default value of 403.
- sip-reason-text—SIP reason text the system uses
to generate the sip response. Values include Forbidden (default), or a custom
string.
You can leave this parameter empty if you want to use the reasontext provided by the STI-VS in the final SIP response. If the STI-VS does not return a reasontext, the system uses the default value of Forbidden.
To complete your configuration, you enter the name of a sti-response-treatment-config to the sti-response-treatment-config-name parameter within a sti-server or the sti-config. The sti-server configuration takes precedence over the sti-config configuration.
The SBC compares the input from the STI server with your sti-response-treatment-entries to determine a match. The system looks to match your entries with both the verstat and reason-code. But endstations are not consistent with the call information that they provide. For this reason, you may decide to create multiple entries with the same verstat, but variations in the reason-code. Furthermore, if you do not configure a reason-code to an entry, you create a single entry that matches the verstat and any reason-code.
As an operational example, consider an STI-VS response that matches to the following sti-response-treatment-config entry. (The received verstat is TN-Validation-Failed and the reasoncode is 437).
sti-response-treatment-entry
verstat TN-Validation-Failed
reason-code 437
role STI-VS
sip-reason-code 403
sip-reason-text Forbidden
In this case, the SBC matches any STI-VS reply with both verstat and reason-code, replies to the caller with a SIP message mapping the strings “403" and "Forbidden” into the response, and drops the call.
Applicable 3GPP versus ATIS deployment behaviors include:
- For 3GPP deployments, the SBC checks all the verstat results in the response, including SHAKEN verstat and DIV verstat values to find a match and reject the call based on first best match policy.
- For 3GPP deployments, if the reply does not have a SHAKEN or DIV verstat in the response, the SBC takes the verstat as “No-TN-Validation-None" to find a match with configured entries for call rejection purpose.
- For ATIS deployments, if the reply does not have a verstat in the response, the SBC takes the verstat as “No-TN-Validation-None" to find a match with configured entries for call rejection purpose.
- If the SBC fails to send a request
to an sti-vs server due to internal error, it uses the verstat
“No-TN-Validation-Timeout” to find a match for call rejection. To support this,
configure an entry that uses this verstat and no reason-code, sip-reason-code or
sip-reason-text.
- For ATIS deployments, the SBC populates the case SIP reason header using SIP;cause=403;text=Forbidden.
- For 3GPP deployments, the SBC does not populate the SIP reason header.
Applicable deployment behavior that applies to both ATIS and 3GPP STIR/SHAKEN modes:
- In ATIS and 3GPP, if 4xx and 5xx responses do not have verstat values, the SBC uses the verstat value as "No-TN-Validation-None" for call rejection purpose. Configure an entry that matches “No-TN-Validation-None” if you want to reject these calls. For SIP rejection messages to these calls, the SBC adds the default verstat, "No-TN-Validation".
- When receiving 4xx or 5xx responses, because the reason-code is not in the response body, the SBC reads the reason-code from the HTTP status code in the FROM status line of the response.
- To accommodate timeout scenarios, you can create an entry wherein the verstat is "No-TN-Validation-Timeout" and the reason code is empty or zero as a match to reject those calls.
- If an STI-VS does not answer or answers without any verstat key in the JSON body, the SBC adds "No-TN-Validation" to the From and PAI header.
When rejecting a call based on this feature, the reason-header the SBC sends in the final response message back to the UAC is dependent on the STI operational mode of the SBC:
- ATIS:
- In the case of a 200OK response:
- If the body contains reasoncode and reasontext Reason header is filled with reasoncode + reason text
- If reason code is not present, the system uses 403
- If reason text is not present, the system uses forbidden.
- In the case of a 200OK response:
- 3GPP—In the case of a 200 OK response, the system leaves the reason header empty.
- ATIS and 3GPP—In the case of 4xx or 5xx responses, the system reads the reason code and reason text from the status line and uses them in the reason header.
Table of Responses to Rejected Requests
The SBC follows the table below to determine what to include as reason-text when it rejects SIP requests within the context of STIR/SHAKEN authentication and verification.
sip-reason-code Configured | sip-reason-text Configured | reasoncode in STI-VS response | reasontext in STI-VS response | Final Sip Reasoncode/Reasontext in Response |
---|---|---|---|---|
Yes | Yes | Yes/No | Yes/No | Configured sip-reason-code and /sip-reason-text |
No | No | Yes | Yes | reasoncode in STI-VS response/ reasontext in STI-VS response |
No | No | No | No | 403 / Forbidden |
Yes | No | Yes/No | Yes | sip-reason-code Configured / reasontext in STI-VS response |
Yes | No | Yes/No | No | sip-reason-code Configured / Forbidden |
No | Yes | No | Yes/No | 403 / sip-reason-text Configured |
No | Yes | Yes | Yes/No | reasoncode in STI-VS response/Configured sip-reason-text |
Reporting on Call Rejection
The SBC provides counters on rejected calls within ACLI commands, SNMP, HDR and CDR records.
- From the ACLI, you can find these statistics listed as 'STI-VS INVITEs Rejected' within the output of the server, interface, realm, agent, and system wide versions of the show stir command.
- From CDRs, you can find per-call indications of call rejection presented using the Stir-VS-Invite-State VSA for RADIUS and Stir-VS-Invite-State AVP for Diameter.
- From HDRs, you can find you can find these statistics listed as 'Stir-VS-Invite-State' within the output of the server, interface, realm, agent, and system wide HDR records.
- From SNMP, you can find these statistics listed as 'vsInviteRejected' within the output of the server, interface, realm, agent, and system wide tables.
Related Configuration
This rejection feature works in conjunction with the server retry feature implemented with your max-retry-attempts configuration.
- If max-retry-attempts is greater than zero, meaning recursion is disabled, the system rejects calls based on the sti-vs response from the first server that responds.
- If max-retry-attempts is greater than zero, meaning recursion is enabled, the system rejects calls based on the sti-vs response to the last server the system attempts to reach.