The Number Authentication Mechanism specification requires additional reason header capabilities that give the provider more specific reasons for call handling. Within the context of this specification, the key SBC function is to better identify call verification issues, allowing the system to conform with the specification's requirements for handling and rejecting SPAM calls. This feature applies to the information provided in a reason header within an egress INVITE towards the callee.

You use the sti-reason-header-config element to create multiple reason header configurations that define how the SBC behaves when confronted with specific verification issue scenarios.

Each instance of sti-reason-header-config includes a name along with the sti-reason-header-entries parameter, which provides access to detailed reason header configuration. You enter a name for your element to apply to a sti-server or, globally, to the sti-config. When both elements have a sti-reason-header-config, the sti-server configuration takes precedence.

An example of a configured sti-reason-header-config is provided below. This configuration has two reason header entries, which define reason header behavior that is in addition to your other configured reason header behavior.

ORACLE(sti-reason-header-config) # show
sti-reason-header-config
name reason-header-scenario-list
         sti-reason-header-entry               
                  scenario              sti-server-timeout                                         
                  cause-code            690               
                  reason-text           STI Server Timeout
         sti-reason-header-entry               
                  scenario              invalid-sti-response                                      
                  cause-code            691               
                  reason-text           Invalid STI Response

Under sti-reason-header-entry, there are three parameters:

• scenario (Required)—You configure the scenario parameter using the scenario list below. The default setting is sti-server-timeout. Settings include:
  • sti-server-timeout—The system recognizes this timeout scenario when it does not receive a reply from the STI server.

    Oracle recommends you configure this scenario as sti-server-timeout, with a cause-code (690) and reason-text STI Server Timeout.

  • invalid-sti-response—The system recognizes this scenario when it receives an STI-VS answer that it cannot derive. Applicable scenarios include the JSON being missing or malformed.

    Oracle recommends you configure this scenario as invalid-sti-response, with a cause-code to 691 and reason-text Invalid STI Response. If you leave the cause-code empty, the system populates its message with 691. If you leave the reason-text empty, the system populates its message with Invalid STI Response.

    Oracle considers a verification response as an invalid STI response based on the following:

    • 200 OK case
      • From an ATIS perspective, meaningless answer:
        • no JSON body
        • JSON body but no verificationResponse
        • JSON body and verificationResponse but no verstat
      • From a 3GPP perspective, meaningless answer:
        • no JSON body
        • JSON body but no verificationResponse
        • if SHAKEN verification: JSON body and verificationResponse but no verstatValue
        • if DIV verification:
        • JSON body and verificationResponse but no divResult
        • JSON body and verificationResponse and divResult but no verstatValue
    • 4xx/5xx case—Within 4xx/5xx responses from the STI-VS, there is no "invalid sti response" possible. The SBC, therefore, populates the SIP Reason Header as follows:
      • cause:
        • reasonCode if included in JSON body
        • HTTP response status-code if reasonCode is not available in JSON body
      • text:
        • reasonText if included in JSON body
        • OR error included in JSON body if reasonText is not available in JSON body
        • OR HTTP reason phrase if reasonText nor error is available in JSON body
  • use-identity-header—The system recognizes this scenario when it receives an INVITE with the Identity header missing or empty. You configure this scenario as use-identity-header, with a cause-code of 428 and reason-text of Use Identity Header. If you leave the cause-code empty, the system populates its messages with 428. You can leave the reason-text empty or configured. If left empty, the system populates the field with Use Identity Header.
  • tn-missing—The system recognizes this scenario when it receives an INVITE that does not include any telephone number in the From or the PAI.

    Oracle recommends you configure this scenario as tn-missing, with a cause-code of 692 and reason text of TN missing. If you leave the cause-code empty, the system populates the field with 692. You can also leave the reason-text empty or configured. If you leave the cause-code empty, the system populates the field with Invalid STI Response.

  • sti-constraints-exceeded—The system recognizes this scenario when it does not send the request because traffic has exceeded a configured STI admission control parameter, including max-burst-rate, max-sustain-rate, burst-rate-window or sustain-rate-window.

    Oracle recommends you configure this scenario as sti-constraints-exceeded, with a cause-code of 693 and a reason text of STI Constraints Exceeded. If you leave the cause-code empty, the system populates the field with 693. You can also leave the reason-text left empty or configured. If left empty, the system populates the text with STI Constraints Exceeded.

    Note:

    In case of SAG recursion, meaning you have enabled the retry parameter in the sti-config and applied on sti-server-group, and none of the servers are available, meaning all the servers in the group have exceeded constraints, the system populates the SIP reason header per the Oracle recommendation.
  • sti-server-unreachable—The system recognizes this scenario when the sti-server is unreachable, meaning the applicable circuit-breaker is either open or half-open. In these scenarios, the SBC does not send a request.

    Oracle recommends you configure this scenario as sti-server-unreachable, with a cause-code as 694 and reason-text as STI Server Unreachable. If you leave the cause-code empty, the system populates the field with 694. You can also leave the reason-text left empty or configured. If left empty, the system populates the text with Sti Server Unreachable.

  • internal-client-error—The system recognizes this scenario when the SBC fails to send the request to the STI server.

    Oracle recommends you configure this scenario as internal-client-error, with a cause-code of 695 and reason-text of Internal Client Error. If you leave the cause-code empty, the system populates the field with 695. You can also leave the reason-text left empty or configured. If left empty, the system populates the text with Internal Client Error.

  • sti-server-bypass—The system recognizes this scenario when it has bypass a STIR/SHAKEN request. You typically configure the exotic code is to 696 when you configure the scenario to 'sti server bypass'. Configure scenario as “sti-server-bypass” and cause-code as 696. If you leave the cause-code parameter empty, the system populates the cause code with 696 for this scenario. You can also leave the reason-text empty or configured. If left empty, the system populates the applicable fields with “Sti Server Bypass”.
• cause-code (Optional)—As described in the scenarios, you can set this to any value within the range 400-699.
• reason-text (Optional)—The system has this reason text field empty by default for all the scenarios. The system maps actual text, however, internally mapped to respective strings based on scenario. As described in the scenarios, you can configure preferred text to overwrite the defaults.

The sti-reason-header-entry element is a multi-instance element, allowing you to create an entry for every scenario needed.