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

STIR/SHAKEN Client Operation

The ESBC 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 ESBC sends a STIR AS request using REST. If the STIR server replies with a success response, the ESBC 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 ESBC 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 ESBC 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 ESBC only inspects the first occurrence of these headers.
      You can also configure the ESBC 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 ESBC generates its own origination-ID that identifies the ESBC, 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 ESBC 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 ESBC 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 ESBC adds this same header parameter to the “P-Asserted-Identity” header if it is present in the INVITE.
    • If the ESBC 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 ESBC 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 ESBC 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 ESBC 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 ESBC 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 ESBC stops checking. The ESBC 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 ESBC 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 ESBC 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 ESBC uses to decide on a query are always from the inbound side configuration, while the parameters the ESBC 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 ESBC 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 ESBC 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 ESBC 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 ESBC uses the management interface to send the STI request
  4. The ESBC “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 ESBC 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 ESBC 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 ESBC 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 ESBC “continues” the call by resuming the processing of the INVITE message.

Authentication Request

When the ESBC 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 ESBC 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 ESBC stops checking. The ESBC 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 ESBC 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 ESBC uses the applicable configured value.

    Additional detail includes:

    • If the sti-orig-id is not configured on any object, the ESBC uses the value from the sti-server.
    • If the sti-attest is not configured on any object, the ESBC 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 ESBC 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 ESBC 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 ESBC 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 ESBC uses the management interface to send the STI request
  4. The ESBC “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 ESBC 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 ESBC does not receive a success response, the ESBC 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 ESBC “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 ESBC performs a DNS query for an A record (or AAAA record if you are using IPv6) to resolve the FQDN. The ESBC sends AS/VS requests to the first IP address returned by the DNS server. Additional IP addresses are not used.