yeti-switch · dmitry-sinina · Aug 23, 2025 · Aug 23, 2025 · Aug 23, 2025 · Aug 23, 2025
diff --git a/en/best-practices/stir-shaken.rst b/en/best-practices/stir-shaken.rst
@@ -0,0 +1,87 @@
+.. :maxdepth: 2
+
+===========
+STIR/SHAKEN
+===========
+
+.. _stir_shaken:
+
+Yeti-Switch is compatible with STIR/SHAKEN mechanisms and allows you to perform both Identity validation and signing.
+The Yeti system does not require any external components to perform these operations.
+
+.. mermaid::
+
+    graph LR
+        gw1[Call originator]
+        gw2[Termination provider]
+
+
+        gw1 -->|legA SIP initial INVITE<br>**Identity:.....;x5u=https:\/\/example.com/certs/pub.pem**| validation-logic
+        validation-logic --> call-routing
+        validation-logic --> call-reject
+        call-routing --> signing-logic
+
+        signing-logic -->|legB SIP initial INVITE| gw2
+
+        signing-certificate-repository -->|Fetching private certificate| signing-logic
+
+
+        public-certificate-repository[Public certificate repository<br>**https:\/\/example.com/certs/pub.pem**]
+        public-certificate-cache[Certificate Cache]
+
+        validation-logic -->|Fetching public certificate| public-certificate-cache
+        public-certificate-cache -->|Fetching public certificate| public-certificate-repository
+
+
+        subgraph yeti[Yeti SBC]
+            validation-logic[Signature Validation]
+            public-certificate-cache
+            signing-certificate-repository
+            signing-logic[Signing]
+            call-routing
+            call-reject
+        end
+
+
+Signature Validation
+====================
+
+.. _stir_shaken_validation:
+
+Signature validation logic is controlled by :ref:`Customers Auth STIR/SHAKEN settings <customer_auth_stir_shaken>`.
+Depending on the configuration, Yeti may take different actions if the signature is missing or invalid.
+
+The validation procedure requires a public key certificate to perform the cryptographic signature check.
+This certificate is retrieved from a public repository according to the **X5U** parameter of the incoming Identity header.
+
+During signature validation, Yeti performs the following steps:
+
+    - Check if the public certificate repository URL from the **X5U** parameter is allowed by :ref:`Trusted repository configuration <stir_shaken_trusted_repositories>`
+    - Retrieve the public certificate from the repository URL or from the internal cache
+    - Verify that the public certificate is valid and not expired
+    - Ensure that the certificate chain is linked to a trusted root certificate defined in :ref:`Trusted certificates configuration <stir_shaken_trusted_certificates>`
+    - Validate the JWT signature
+    - Check the ``iat`` (issued-at) timestamp for expiration
+    - Confirm that the ``orig.tn`` and ``dest.tn`` attributes in the Identity header match the Source and Destination numbers present in SIP signaling
+
+The results of signature validation are stored in the CDR fields: ``Lega Ss Status`` and ``Lega Identity``.
+
+
+Signing
+=======
+
+.. _stir_shaken_signing:
+
+When sending a call to the termination gateway, Yeti can either:
+
+    - pass the original Identity header as-is,
+    - remove it,
+    - generate and attach its own signature.
+
+This behavior is controlled by :ref:`Termination gateway STIR/SHAKEN settings <gateway_stir_shaken>`.
+
+To perform signing, a private certificate and key material are required.
+These are defined in :ref:`Signing Certificates configuration <stir_shaken_signing_certificates>`.
+
+Yeti supports multiple signing certificates, and you can choose which certificate will be used for signing in :ref:`Termination gateway STIR/SHAKEN settings <gateway_stir_shaken>`.
+Additionally, it is possible to override the certificate in :ref:`Customers Auth STIR/SHAKEN settings <customer_auth_stir_shaken>`, allowing different certificates to be used for different call originators (customers).
diff --git a/en/index.rst b/en/index.rst
@@ -37,6 +37,7 @@ Welcome to Yeti's documentation!
    best-practices/headers-transit.rst
    best-practices/numbers-translations.rst
    best-practices/teams-direct-routing.rst
+   best-practices/stir-shaken.rst
    best-practices/using-routing-tags.rst
    best-practices/troubleshooting.rst
 

diff --git a/en/web-interface/equipment.rst b/en/web-interface/equipment.rst
@@ -17,3 +17,6 @@ YETI WEB interface - Equipment menu description. This section describes Equipmen
    equipment/lnp_databases
    equipment/radius_auth_profiles
    equipment/radius_accounting_profiles
+   equipment/stir_shaken_trusted_repositories
+   equipment/stir_shaken_trusted_certificates
+   equipment/stir_shaken_signing_certificates
diff --git a/en/web-interface/equipment/gateways.rst b/en/web-interface/equipment/gateways.rst
@@ -803,6 +803,8 @@ Radius accounting profile
 STIR/SHAKEN attributes
 ======================
 
+.. _gateway_stir_shaken:
+
 STIR/SHAKEN mode
     STIR/SHAKEN behavior when gateway used for call termination. Possible values:
 
@@ -814,4 +816,4 @@ STIR/SHAKEN crt
     STIR/SHAKEN certificate to use for Identify signing.
 
 
-.. warning:: **STIR/SHAKEN** mechanisms are experimental features and not enabled by default.
+.. warning:: **STIR/SHAKEN** mechanisms are disabled by default.
diff --git a/en/web-interface/equipment/stir_shaken_signing_certificates.rst b/en/web-interface/equipment/stir_shaken_signing_certificates.rst
@@ -0,0 +1,27 @@
+
+
+.. _stir_shaken_signing_certificates:
+
+================================
+STIR/SHAKEN Signing Certificates
+================================
+
+This configuration section defines the certificates and private keys used for the :ref:`Identity Signing procedure <stir_shaken_signing>`.
+
+Attributes
+==========
+
+Name
+    A user-friendly name for the signing certificate.
+
+Certificate
+    The certificate in PEM format.
+    The certificate must use the ``ecdsa-with-SHA256`` signature algorithm.
+
+Private Key
+    The corresponding ECDSA private key in PEM format.
+
+X5U
+    The **X5U** parameter for the Identity header.
+    The URL in X5U must point to your certificate and be publicly accessible.
+    Remote systems will use this URL to fetch your certificate during their own Identity validation procedure.
diff --git a/en/web-interface/equipment/stir_shaken_trusted_certificates.rst b/en/web-interface/equipment/stir_shaken_trusted_certificates.rst
@@ -0,0 +1,34 @@
+
+.. _stir_shaken_trusted_certificates:
+
+================================
+STIR/SHAKEN Trusted Certificates
+================================
+
+This configuration section defines the trusted root certificates required for validating public certificates.
+See :ref:`Identity Validation procedure <stir_shaken_validation>` for details.
+
+Attributes
+==========
+
+Name
+    A user-friendly name for the trusted root certificate.
+
+Certificate
+    The trusted root certificate in PEM format. Example::
+
+        -----BEGIN CERTIFICATE-----
+        MIIBqzCCAVCgAwIBAgIJALwomIWcKYBrMAoGCCqGSM49BAMCMCgxJjAkBgNVBAMM
+        .........
+        .........
+        vcv6Kxxaj1puvAi5AiEAtbkNa56M4Sip0yLbWTXKdXcqAC5DHxbF4ab45aor220=
+        -----END CERTIFICATE-----
+
+Notes
+=====
+
+- In the USA, trusted root certificates can be obtained from:
+  https://authenticatereg.iconectiv.com/download-lists
+
+- In France, trusted root certificates can be fetched from:
+  https://api.man-bpco.fr/ca/certs/
diff --git a/en/web-interface/equipment/stir_shaken_trusted_repositories.rst b/en/web-interface/equipment/stir_shaken_trusted_repositories.rst
@@ -0,0 +1,20 @@
+
+.. _stir_shaken_trusted_repositories:
+
+================================
+STIR/SHAKEN Trusted Repositories
+================================
+
+This configuration section defines the list of trusted URLs from which Yeti may fetch STIR/SHAKEN public certificates during the :ref:`Identity Validation procedure <stir_shaken_validation>`.
+
+Attributes
+==========
+
+URL Pattern
+    A regex pattern or specific URL that defines which repositories are allowed. Examples:
+
+        - ``https://\*`` — allows requests to any HTTPS URL
+        - ``https://example.com/\*`` — allows fetching any certificate from the **example.com** domain
+
+Validate HTTPS Certificate
+    When using the HTTPS protocol, this flag enforces validation of the HTTPS server certificate to ensure authenticity.
diff --git a/en/web-interface/routing/customers-auths.rst b/en/web-interface/routing/customers-auths.rst
@@ -1,8 +1,9 @@
 
 .. _customer_auth:
 
+===============
 Customers Auths
-~~~~~~~~~~~~~~~
+===============
 
 This entity authenticates calls from customers or gateways, applies them to
 routing table and has some useful filters and options.
@@ -151,7 +152,7 @@ After sorting of *Customer Auth* records routing procedure will be continued wit
 Customer Auth form contains few tabs and each one is described below.
 
 General attributes
-``````````````````
+==================
 
     .. _customer_auth_id:
 
@@ -211,7 +212,8 @@ General attributes
         current price for calls, in order to a Customer should be informed.
 
 Match condition options
-```````````````````````
+=======================
+
     This part is crucial for authentication process of incoming calls. You should note that a one
     customer may have many of Customer Auth with almost the same parameters, so pay
     attention to parameters besides Ip address.
@@ -278,7 +280,7 @@ Match condition options
     .. _customers_auth_number_translation:
 
 Number translation options
-``````````````````````````
+==========================
 
 Privacy mode
     Processing mode for :ref:`Private calls <sip_headers_privacy>`. Available options:
@@ -353,7 +355,7 @@ Cnam Database
 .. _radius_options:
 
 Radius options
-``````````````
+==============
 
 Radius auth profile
     Must be specified if the additional radius authentication is required.
@@ -373,7 +375,7 @@ Radius accounting profile
     .. _routing_tags_options:
 
 Routing Tags options
-````````````````````
+====================
 
 Tag action
     Describes one of the possible actions that could be applied to the current set of :ref:`Routing Tags <routing_tag>` that are applied for the call with using *Tag action value* below. Usually *Authentication* it is first step where :ref:`Routing Tags <routing_tag>` can be added to the call. Following actions can be selected in this field:
@@ -386,3 +388,44 @@ Tag action
 Tag action value
     In this field :ref:`Routing Tags <routing_tag>` for making some *Tag action* above could be chosen.
 
+
+STIR/SHAKEN Attributes
+======================
+
+.. _customer_auth_stir_shaken:
+
+SS Mode
+    Defines the STIR/SHAKEN operating mode. Possible values:
+
+        Disable STIR/SHAKEN processing
+            No validation or signing is performed.
+
+        Validate identity
+            Perform STIR/SHAKEN signature validation.
+
+        Force rewrite attestation level
+            Override the attestation level.
+            Since it is not possible to change the attestation level within an existing signature, this option replaces the existing signature with a new one.
+
+SS Invalid Identity Action
+    Defines system behavior when an invalid STIR/SHAKEN signature is received.
+
+SS No Identity Action
+    Defines system behavior when a call is received without an Identity header.
+
+Rewrite SS Status
+    Allows overriding the original attestation level.
+    During the Identity signing procedure, this value determines the attestation level of the outgoing call.
+
+    Additionally, the attestation level can be overridden in :ref:`Numberlist Item configuration <numberlist_items>`, which enables logic where the attestation level depends on the call’s Source/Destination number or prefix.
+
+SS Src Rewrite Rule/Result
+    A regular expression applied to the original Source Number (``Src Number In``) from SIP signaling before comparing it with the ``orig.tn`` attribute in the signature.
+
+SS Dst Rewrite Rule/Result
+    A regular expression applied to the original Destination Number (``Dst Number In``) from SIP signaling before comparing it with the ``dest.tn`` attribute in the signature.
+
+STIR/SHAKEN Certificate
+    The STIR/SHAKEN certificate to be used for the :ref:`Identity Signing procedure <stir_shaken_signing>`.
+
+.. warning:: **STIR/SHAKEN** mechanisms are disabled by default.