1. Configuration Guide
  2. STIR/SHAKEN Client
  3. STIR/SHAKEN Client Operation

STIR/SHAKEN Client Operation

The SBC can use STIR/SHAKEN to perform key security functions. These include authentication, which attempts to obtain identify information that was not provided, and verification, which attempts to verify identity information that has been provided. Authentication processes use AS servers; verification processes use VS servers. In addition to these, the SBC participates in the STIR/SHAKEN architecture to signing, or attestation, functions, within which the system distributes the results of these security checks.

Triggers to authentication and verification procedures include:

  • If the SBC receives an out-of-dialog INVITE that includes a TN in either the PAI or FROM headers, it sends:
    • A signing request with the TN in the orig parameter if the "Identity" header is absent in the Invite and you have set the mandatory configuration on the SBC for initiating signing requests.
    • A verification request with the TN in the From header if the "Identity" header is present in the Invite and you have set the mandatory configuration on the SBC for initiating verification requests.
  • If a TN is not present, meaning the SIP URI has no digits and only letters for the username in either the PAI or From header, the SBC does not initiate a signing request because there is no valid TN for the orig parameter. Also, it does not initiate a verification request because there is no valid TN for the from parameter.
  • If the PAI and From have different TNs, and the signing/verification fails with the PAI TN, the system does not try with the TN in the From.

    For example, a call requesting privacy may not contain a PAI and the From may contain anonymous@anonymous.invalid. In this case, the call would not be signed.

Note:

By default, the system applies precedence to incoming PAI headers when determining how to populate outgoing verstat and orig values. You can change this behavior globally or on a per-server basis, causing the system to consider information in FROM headers first, as described below.

Authentication

From a high level, authentication includes the following functions:

  • Upon receiving an initial out-of-dialog SIP INVITE request that does not have a SIP identity header, the SBC sends a STIR AS request using REST. If the STIR server replies with a success response, the SBC adds the signed signature of the calling party to the INVITE request in a SIP identity header before routing the INVITE to the next hop.
  • If preferred, you can configure the SBC to also use attestation level and origination ID headers from the ingress SIP INVITE in the REST query to the STI-AS. You do this by enabling the sti-signaling-attest on the applicable realm, sip-interface or session-agent, with the SBC using that configuration precedence to determine whether to perform the function.
    (session-agent)# sti-signaling-attest enable

    When this is configured, the Attestation-Info and Origination-ID headers override the configured values, if present. If one of the two requested headers is present, the other value is obtained from configured parameters.

    Note:

    If there are multiple instances of ‘Attestation-Info’ or ‘Origination-ID’, the SBC only inspects the first occurrence of these headers.
    You can configure the SBC to generate an origination-ID or specify a server-associated origination-ID using the orig-id parameter in the applicable sti-server configuration. This parameter is required, but it accepts a full origination-ID or empty quotes (""). The empty quotes allow you to create the sti-server object without an actual origination-ID. When configured with empty quotes (""), the SBC generates its own origination-ID that identifies the SBC.
    ORACLE(sti-server)# orig-id ""

Authentication Procedure

When the SBC receives an initial out-of-dialog SIP INVITE that does not have a SIP identity header, it determines the route for sending the INVITE and then sends an AS request to a STIR server if STIR/SHAKEN is enabled on the egress side. The SBC determines if STIR/SHAKEN is enabled by checking the following:

  1. Is sti-as configured in the outbound session-agent
  2. If not, is sti-as configured in the outbound sip-interface
  3. If not, is sti-as is configured in the outbound realm-config

If sti-as is configured in one of the above steps, the SBC stops checking. The SBC uses the found sti-as to find the sti-server and uses information from the sti-server configuration to create and send the AS request.

  1. The authority of the as-server-root specifies the address of the STIR server. If it is a FQDN then the SBC performs a DNS query to resolve the FQDN to an IP address. If the authority has a port, the AS request is sent to that port. Otherwise, port 80 is used if it is HTTP and port 443 is used if it is HTTPS.
  2. The sti-orig-id and sti-attest from the inbound session-agent, sip-interface or realm-config are used in the AS request. The first values found in that order are used.

    The exception to this is when the INVITE message already has origId and attest values, and the parameter sti-signaling-attest is enabled in the inbound session-agent, sip-interface or realm-config. In that case, the system uses the origId and attest from the INVITE message. If there is no value in the INVITE, the SBC uses the applicable configured value.

    Additional detail includes:

    • If the sti-orig-id is not configured on any object, the SBC uses the value from the sti-server.
    • If the sti-attest is not configured on any object, the SBC uses the value from the sti-server.
    • The decision to send AS request is based on the sti-as parameter on the outbound side, but the values for origId and attest are obtained from the inbound side.
  3. The AS request is sent over the network interface specified by the http-client that is configured in the sti-server configuration. If it is HTTPS, the tls-profile from the same http-client is used. Additional detail includes:
    • The SBC negotiates HTTP/2 by setting the ALPN parameter in the TLS negotiation, if HTTPS is used. If HTTP is used, only HTTP/1.1 is used. When HTTP/1.1 is used, the SBC maintains multiple TCP or TLS connections towards the STI server to avoid head-of-line issues with HTTP/1.1. If HTTP/2 is negotiated over TLS, only one HTTPS connection is established and HTTP/2 pipelining is used to send REST requests.
    • The SBC determines the interface using the realm you configure on the sti-server. If the realm field is empty, then the ip-address also has to be empty. In this case, the SBC uses the management interface to send the STI request
  4. The SBC “parks” the call (i.e. pause processing the INVITE) and waits for a response from the STIR server for the amount of time configured in the sti-server timeout parameters. The default timeout is 2000 ms.
  5. If the SBC receives a success response for the AS request, it adds a SIP Identity header the INVITE message using the identity returned in the AS response.
  6. If the SBC does not receive a success response, the SBC does not add a SIP Identify header to the INVITE message. AS request timeout and failure to send due to internal error are both considered a failure to receive a success response.
  7. In either case, the SBC “continues” the call by resuming the processing of the INVITE message to be sent to the next hop.

Verification

The SBC performs its verification process dependent on your configuration and the contents of the applicable INVITEs. Applicable configuration parameters includes the sti-signaling-attest-info-mandatory and anonymous-uri-add-verstat-to-hostpart, which are within the sti-config and disabled by default.

Note:

By default, the SBC sends signing requests to the server even if the INVITE does not include attestation and origination information.

Specifically, the SBC ensures that the TN is in either the PAI header, the FROM header or both before sending out any signing and verification request. When you enable sti-signaling-attest-info-mandatory, the SBC also refrains from sending the signing request if the INVITE does not contain attestation and origination information. In this case, the received INVITE must contain a P-Attestation-Info or Attestation-Info, and a P-Origination-ID header or Origination-ID header.

When you enable the anonymous-uri-add-verstat-to-hostpart parameter, and the received INVITE:

  • Contains a Privacy header
  • Contains a From header with an anonymous URI (For e.g. sip:anonymous@anonymous.invalid)
  • Does not contain any PAI headers

The SBC adds the verstat parameter after the hostpart of the anonymous From URI. The SBC indicates privacy by placing this verstat in the hostpart of the FROM, as shown below. 

From: ""Anonymous""<sip:anonymous@anonymous.invalid;verstat=TN-Validation-Passed>;tag=9802748 " (V#12). 
If privacy is requested then , then verstat=”No-TN-Validation”.

Finally, the SBC adds a reason header to 18x, 19x, 2xx, 4xx and 5xx responses to the INVITE if the verification fails.

Note:

PAI information may be presented in a single or in multiple headers. The behaviors below are the same if there are two separate PAI headers, or if the SIP URI PAI and TEL URI PAI are in the same header.

From a high level, verification includes the following tasks performed by the SBC:

  • Upon receiving an initial out-of-dialog SIP INVITE request that has a SIP identity header, the SBC sends a STIR VS request to a STIR verification server for verification of the SIP identity. If the STIR server replies with a success response, the SBC adds the header parameter ‘verstat=TN-Validation-Passed’ to the “From:” header of the INVITE before it routes the INVITE to the next hop.
  • If the SBC receives an INVITE without a PAI header, it adds the verstat parameter to the FROM header.
  • The SBC adds this same header parameter to the “P-Asserted-Identity” header if it is present in the INVITE.
  • If the SBC receives an INVITE with one SIP PAI header without a TN and a FROM header that has a TN, it adds the verstat parameter to the FROM header only.
  • If the TN value from TEL URI PAI header is the same as the TN value from the FROM header. the SBC inserts a verstat parameter to both the FROM and the TEL URI PAI.
  • If the SBC receives an INVITE with one PAI header, either a Tel PAI or a SIP PAI with a TN and:
    • A FROM with no TN, it adds the verstat parameter to the PAI header and not to the FROM Header.
    • A FROM with a TN, and if the values of the TNs match, it adds the verstat parameter to the PAI and FROM Headers.
  • If the SBC receives an INVITE with two PAI headers, one of which is a TEL PAI and the other a SIP PAI and:
    • The SIP PAI has a TN, the SBC:
      • Compares each TN and, if all three TN's match, adds a verstat to all three headers.
      • Checks whether the FROM has a TN. If these TNs are not the same, it adds a verstat to the TEL PAI only.
      • If there is no FROM TN, the SBC compares the TNs in the SIP PAI and the TEL PAI, and:
        • If the TN's match, adds a verstat to both headers.
        • If the TNs do not match, add a verstat to the TEL PAI only.
    • If the SIP PAI has no TN, the SBC checks whether the FROM has a TN and whether that TN is the same as the TEL PAI TN:
      • If so, it adds a verstat to the TEL PAI and the FROM
      • If not, it adds a verstat to the TEL PAI only
  • If the SBC does not receive a success response from the STIR server or times out while waiting for a response, you can configure the SBC to add the header parameter “verstat=No-TN-Validation” instead. This action is disabled by default.
  • If the SBC receives a SIP INVITE without a SIP identity header on an ingress realm that is configured to trigger a STIR request to the STI-VS, the SBC adds the verstat parameter to the “From” and “P-Asserted-Identity” headers, when present, with a value of “No-TN-Validation”.

Verification Steps

When the SBC receives an initial out-of-dialog SIP INVITE that contains a SIP Identity header and STIR/SHAKEN is enabled on the ingress side, it sends a VS request to the STIR server configured for the ingress side. The SBC determines if STIR/SHAKEN is enabled by checking the following:

  1. Is sti-vs configured in the inbound session-agent
  2. If not, is sti-vs configured in the inbound sip-interface
  3. If not, is sti-vs is configured in the inbound realm-config

If sti-vs is found configured in one of the above steps, the SBC stops checking. The SBC uses the found sti-vs to find the sti-server and uses information from the sti-server configuration to create and send the VS request.

  1. The authority of the vs-server-root specifies the address of the STIR server. If it is an FQDN then the SBC performs a DNS query to resolve the FQDN to an IP address. If the authority has a port, the VS request is sent to that port. Otherwise, port 80 is used if it is HTTP and port 443 is used if it is HTTPS.
  2. The X-Instance-Id HTTP header on the REST request is set to the sti-orig-id from the inbound session-agent, sip-interface or realm-config. The first sti-orig-id found in that order is used. Additional detail includes:
    • If the sti-orig-id is not configured on any object, the SBC takes the value from the sti-server.
    • The decision to send AS request is based on the sti-as parameter on the outbound side, but the values for origId and attest are obtained from the inbound side.

    Note:

    The parameters the SBC uses to decide on a query are always from the inbound side configuration, while the parameters the SBC uses to decide whether to make the query are dependent on the query type, as follows:
    • sti-as: inbound side configuration
    • sti-vs: outbound side configuration
  3. The VS request is sent over the network interface specified by the http-client that is configured in the sti-server configuration. If it is HTTPS, the tls-profile from the same http-client is used. Additional detail includes:
    • If an auth-profile is defined on the http-client, it refers to security, authentication-profile. An HTTP authorization header is sent with a Bearer token defined as the preshared-key in the authentication-profile.
    • The SBC negotiates HTTP/2 by setting the ALPN parameter in the TLS negotiation, if HTTPS is used. If HTTP is used, only HTTP/1.1 is used. When HTTP/1.1 is used, the SBC maintains multiple TCP or TLS connections towards the STI server to avoid head-of-line issues with HTTP/1.1. If HTTP/2 is negotiated over TLS, only one HTTPS connection is established and HTTP/2 pipelining is used to send REST requests.
    • The SBC determines the interface using the realm you configure on the sti-server. If the realm field is empty, then the ip-address also has to be empty. In this case, the SBC uses the management interface to send the STI request
  4. The SBC “parks” the call (pauses the processing of the INVITE) and waits for a response from the STIR server for the amount of time configured in the sti-server timeout parameters. The default timeout is 2000 ms.

    Note:

    Upon receiving the INVITE, the inbound SIP manipulations are applied first. Then the caller information is obtained from the P-Asserted-Identity header, if it exists, or from the From: header. The destination number is extracted from the To: header. If the numbers are in e.164 format, the leading + sign is not sent on the STI request, but the numbers on the INVITE are not modified.
  5. The SBC refers to the high-level verification rules above to determine how to proceed with header population and forwarding.
  6. The SBC “continues” the call by resuming the processing of the INVITE message.

FQDN Server Root

The as-server-root and vs-server-root in the sti-server configuration allows a URL that uses IPv4, IPv6 or FQDN for the authority part. For FQDN, the SBC performs a DNS query for an A record (or AAAA record if you are using IPv6) to resolve the FQDN. The SBC sends AS/VS requests to the first IP address returned by the DNS server. Additional IP addresses are not used.

Adding Reason Headers

The SBC adds reason headers with reasoncode and reasontext information extracted from the JSON body of the response from STI-VS. The SBC adds these reason headers to all 18X, 19x and final responses, which include 200, 4xx, 5xx and 6xx messages, toward the calling party if verification fails. The system uses syntax defined by ATIS-1000074 version 17, as the example shows below. 

Reason: SIP ;cause=436 ;text="Bad Identity Info"

No additional configuration is required to generate these reason headers.