Rejecting Calls During Verification

You can configure the SBC to reject calls based on the verstat and reasonCode from STI-VS server. The SBC uses sti-response-treatment-entry entries applied to the sti-config or sti-server to identify and reject matching calls. 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 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-entry parameters, which are multi-instance sub-elements 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-entry list to determine a match. The system looks to match your entries with both the verstat and reason-code. Because endstations are not consistent with the call information that they provide, you may decide to create multiple entries with the same verstat, but variations in the reason-code. If you do not configure a reason-code to an entry, you create a single entry that matches the verstat and any reason-code.

For example, for the following sti-response-treatment-config entry, the SBC matches any STI-VS response where verstat is TN-Validation-Failed and 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 replies to the caller with a SIP message mapping the strings “403" and "Forbidden” into the response, and drops the call.

Applicable 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. When the man-compliance option is enabled on sti-config, 200 OK responses are the exception to this; in this case, the SBC checks only for SHAKEN verstat values.
  • If the reply does not have a verstat in the response (SHAKEN or DIV, in 3GPP deployments), the SBC takes the verstat as “No-TN-Validation-None" to find a match with configured entries for call rejection purpose.
  • 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.
  • Timeout scenarios:
    • 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 SIP reason header using SIP;cause=403;text=Forbidden.
      • For 3GPP deployments, the SBC does not populate the SIP reason header.
    • 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.
  • For 4xx or 5xx response scenarios:
    • 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 constructing the reason-header, because the reason-code is not in the response body for 4xx and 5xx responses, the SBC reads the reason-code from the HTTP status code in the FROM status line of the response
  • For 200 OK response scenarios:
    • For ATIS deployments, the SBC constructs the response header from the reasonCode and reasonText from the STI-VS response. The SBC also sends this response header for 3GPP deployments when the man-compliance option is enabled on sti-config.

      When reasonCode and reasonText are missing from the STI-VS response, the behavior depends on the STI operational mode of the SBC:

      • For ATIS deployments, the SBC uses SIP;cause=403;text=Forbidden.
      • For 3GPP deployments, when either reasonCode or reasonText is missing, no reason header is included, regardless of man-compliance setting.
    • The SBC constructs the response body as follows:
      • If the matching sti-response-treatment-entry includes a sip-reason-code and sip-reason-text, the SBC uses them in the response body.
      • If either is missing, the SBC uses the corresponding reasonCode or reasonText from the STI-VS response.
      • If either is missing from both locations, the SBC uses the default value of 403 for the reason code or Forbidden for the reason text.

      See Table of Responses to Rejected Requests below for the behavior in all different combinations.

    • For 3GPP, the SBC looks at SHAKEN verstat values only when rejecting calls based on 200 OK responses. If there is no SHAKEN verstat on the STI response that matches a sti-response-treatment-entry, even if a DIV verstat matches, the call will not be rejected.

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 / configured sip-reason-text
No No Yes Yes STI-VS response reasonCode / STI-VS response reasonText
No No No No 403 / Forbidden
Yes No Yes/No Yes Configured sip-reason-code / STI-VS response reasonText
Yes No Yes/No No Configured sip-reason-code / Forbidden
No Yes No Yes/No 403 / configured sip-reason-text
No Yes Yes Yes/No STI-VS response reasonCode / configured sip-reason-text
For example:
  • If the STI response includes reasonCode:437 and reasonText:"Stale Date" and the matching sti-response-treatment-entry sets sip-reason-code to 400 and sip-reason-text to Bad Request, the SBC would use the following:
    • reason-header: Reason: SIP ;cause=437 ;text="Stale Date"
    • Message: 400 Bad Request
  • However, if the matching sti-response-treatment-entry does not set sip-reason-code or sip-reason-text, the SBC would instead use the following:
    • reason-header: Reason: SIP ;cause=437 ;text="Stale Date"
    • Message: 437 Stale Date

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.