Introduction

Class 4 Fusion supports different kinds of configuration Stir Shaken configuration.

1. If you are already an iconnectiv certified SP, then you can use the built-in AS/VS within Class 4

2. If you are not an existing iconnectiv certified SP, you can use an external AS/VS service to sign and verify your calls.

3. If you just simply want to bypass stir shaken signature from ingress to egress, you can configure Class 4 to block calls that don't have valid stir shaken signature. This setting can be done on a per ingress trunk basis.

STIR/SHAKEN

I. Validating incoming requests

STIR/SHAKEN Identity is a JWT with encoded origination ANI and DNIS, signed by a certified STIR/SHAKEN Service Provider, included into the INVITE request.

Ingress and egress trunks may put requirements on incoming and outgoing INVITE requests respectively, using resource.shaken_vfy_policy parameter: 0 - Do not check STIR/SHAKEN Identity; 1 - Require STIR/SHAKEN Identity; 2 - Require valid STIR/SHAKEN Identity; 3 - Require STIR/SHAKEN Identity; Try to validate, but bypass if failed.

If the inbound INVITE request does not satisfy ingress verification policy, the call should be blocked with the corresponding reason:

 Release cause | SIP code                      | Reason
------------------------------------------------------------------------------------------------------------
            71 | 428 - Use Identity header     | Ingress requires STIR/SHAKEN Identity
            72 | 438 - Invalid Identity Header | Call blocked due to invalid STIR/SHAKEN Identity signature

Another set of codes represents errors in the STIR/SHAKEN module, which prevent ingress trunk from validating the Identity:

 Release cause | SIP code                  | Reason
-------------------------------------------------------------------------------------
            73 | 503 - Service Unavailable | All SHAKEN providers failed
            74 | 503 - Service Unavailable | No SHAKEN providers configured
            75 | 503 - Service Unavailable | General error in the STIR/SHAKEN module

II. Signing outgoing requests

1. STIR/SHAKEN identity creation

Switch can create STIR/SHAKEN Identity when placing the outbound INVITE, if caller did not provide it. Ingress trunk can regulate the conditions on which switch can generate Identity for the call, using resource.shaken_sign_policy parameter: 0 - Do not sign calls; 1 - Sign call, if ANI is a US numbers; 2 - Sign, if ANI is a valid phone number (do not allow URI as ANI); 3 - Sign, if ANI is in the SHAKEN ANI pool.

Since class4 switch has options to alter, replace or randomize ANI, final ANI/DNIS may not match numbers in the original Identity provided by the caller. In such scenarios, switch may re-create Identity using the new ANI and DNIS. This behavior is controlled by resource.shaken_allow_resign flag in the ingress trunk configuration. NOTE: New identity creation is allowed only due to ANI/DNIS mismatch. Switch cannot re-sign call, if STIR/SHAKEN Identity did not pass validation.

1. ANI pools and attestation levels

STIR/SHAKEN Identity contains a trust level for the call (attestation level): A - Full attestation B - Partial Attestation C - Gateway Attestation

Client may control attestation levels for each ANI, using SHAKEN ANI groups. Attestation level for numbers outside of the pool can be set with resource.shaken_default_attest_lvl ingress parameter.

1. SHAKEN ANI pool creation

Create SHAKEN ANI group:

INSERT INTO shaken_ani_group (name) VALUES ('my test group') RETURNING id;

Populate ANI group:

INSERT INTO shaken_ani_group_rel (group_id, did) VALUES (<shaken_ani_group.id>, <number>);

Create ANI pool (list of groups):

INSERT INTO shaken_ani_group_list (name) VALUES ('Trunk X ANI pool') RETURNING id;

Add created ANI group to the pool, defining the attestation level:

INSERT INTO shaken_ani_group_list_rel (ani_group_list_id, ani_group_id, attest_lvl) VALUES (<shaken_ani_group_list.id>, <shaken_ani_group.id>, 'B');

Assign SHAKEN ANI pool ID to the ingress trunk, using resource.shaken_ani_group_list_id parameter.

ANI groups and/or pools may be shared between different resources freely.

III. Routing

Egress trunks may put requirements on STIR/SHAKEN Identity using resource.shaken_vfy_policy parameter (see above). If verification policy cannot be satisfied, egress trunk should be removed from routing with the corresponding cause:

 Egress cause | Reason
----------------------------------------------------------------------------
           62 | Egress requires STIR/SHAKEN Identity
           63 | Provided STIR/SHAKEN Identity is not valid
           64 | All SHAKEN providers failed
           65 | No SHAKEN providers configured
           66 | General error in the STIR/SHAKEN module

If all egress routes failed due to STIR/SHAKEN policy, ingress shall block the call with the regular "No egress found" reason.