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

STIR/SHAKEN Client Operation

The SBC can use STIR/SHAKEN to perform two key security functions:

  • Authentication:
    • 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 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

      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 also 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, as follows.
      ORACLE(sti-server)# orig-id ""
  • Verification:
    • 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.
    • The SBC adds this same header parameter to the “P-Asserted-Identity” header if it is present in the INVITE.
    • If the SBC does not receive a success response from the STIR server or times out while waiting for a response, it can add the header parameter “verstat=No-TN-Validation” instead. This action is disabled by default and can be enabled by configuration.
    • 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 Request

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. If the SBC receives a success response for the VS request, it adds the parameter “verstat=TN-Validation-Passed” to the From header and the P-Asserted-Identity header (if present) of the INVITE message.
  6. If the SBC does not receive a success response, it adds the parameter “verstat=No-TN-Validation” to the From header and the P-Asserted-Identity header (if present) of the INVITE message. The SBC also does this when the VS request times out or there is an error that causes a failure to send the VS request.
  7. In either case, the INVITE message is modified with the From header and the P-Asserted-Identity (if present) having either the parameter “verstat=TN-Validation-Passed” or “verstat=No-TN-Validation” added.
  8. The SBC “continues” the call by resuming the processing of the INVITE message.

Authentication Request

When the SBC receives an initial out-of-dialog SIP INVITE, 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 also counts as 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.

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.