diff --git a/en/best-practices/stir-shaken.rst b/en/best-practices/stir-shaken.rst new file mode 100644 index 0000000..a4004dc --- /dev/null +++ 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
**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
**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 `. +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 ` + - 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 ` + - 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 `. + +To perform signing, a private certificate and key material are required. +These are defined in :ref:`Signing Certificates configuration `. + +Yeti supports multiple signing certificates, and you can choose which certificate will be used for signing in :ref:`Termination gateway STIR/SHAKEN settings `. +Additionally, it is possible to override the certificate in :ref:`Customers Auth STIR/SHAKEN settings `, allowing different certificates to be used for different call originators (customers). diff --git a/en/index.rst b/en/index.rst index 99352c5..362218a 100644 --- 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 index 9c8a072..bf29dcd 100644 --- 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 index a6f59c0..94d12ee 100644 --- 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 new file mode 100644 index 0000000..d64041b --- /dev/null +++ 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 `. + +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 new file mode 100644 index 0000000..b4fb3bb --- /dev/null +++ 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 ` 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 new file mode 100644 index 0000000..5ed712e --- /dev/null +++ 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 `. + +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 index d343434..3430f87 100644 --- 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 `. 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 ` that are applied for the call with using *Tag action value* below. Usually *Authentication* it is first step where :ref:`Routing Tags ` 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 ` 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 `, 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 `. + +.. warning:: **STIR/SHAKEN** mechanisms are disabled by default. diff --git a/en/web-interface/routing/numberlist-items.rst b/en/web-interface/routing/numberlist-items.rst index 9eca1a1..42908de 100644 --- a/en/web-interface/routing/numberlist-items.rst +++ b/en/web-interface/routing/numberlist-items.rst @@ -1,63 +1,66 @@ .. _numberlist_items: -Numberlist items -~~~~~~~~~~~~~~~~ +================ +Numberlist Items +================ Numberlist items allow to do something with source or destination number or reject call in general before its routing and after rewriting on the level of :ref:`Customer Auth `. -**Numberlist item**'s attributes: -````````````````````````````````` - Id - Unique Numberlist item's id. - Numberlist - :ref:`Numberlist ` that is associated with this *Numberlist item*. +Attributes +========== + +Id + Unique Numberlist item's id. + +Numberlist + :ref:`Numberlist ` that is associated with this *Numberlist item*. .. _numberlist_items_key: - Key - Full number or Prefix. Interpretation of this field depends on Mode of comparison that was chosen in the :ref:`Numberlist `. - Action - This action will be applied to the call in case of conformity source (A) or destination (B) number and the Key field (according to the Mode that was chosen in the :ref:`Numberlist `): +Key + Full number or Prefix. Interpretation of this field depends on Mode of comparison that was chosen in the :ref:`Numberlist `. - **Default action** - Action that is set for the :ref:`Numberlist `) will be used. +Action + This action will be applied to the call in case of conformity source (A) or destination (B) number and the Key field (according to the Mode that was chosen in the :ref:`Numberlist `): - **Reject call** - Reject call in case of conformity source (A) or destination (B) number and the Key field (according to the Mode that was chosen in the :ref:`Numberlist `). Action from the :ref:`Numberlist `) will be ignored in case of choosing this action. + **Default action** - Action that is set for the :ref:`Numberlist `) will be used. - **Allow call** - Allow call in case of conformity source (A) or destination (B) number and the Key field (according to the Mode that was chosen in the :ref:`Numberlist `). Action from the :ref:`Numberlist `) will be ignored in case of choosing this action. + **Reject call** - Reject call in case of conformity source (A) or destination (B) number and the Key field (according to the Mode that was chosen in the :ref:`Numberlist `). Action from the :ref:`Numberlist `) will be ignored in case of choosing this action. + + **Allow call** - Allow call in case of conformity source (A) or destination (B) number and the Key field (according to the Mode that was chosen in the :ref:`Numberlist `). Action from the :ref:`Numberlist `) will be ignored in case of choosing this action. .. _numberlist_items_rewrite_rules: - Src rewrite rule - *Pattern* parameter of **regexp_replace** function from the `POSIX Regular Expressions `_. As *Source* parameter of **regexp_replace** function is used source number (number A), as a *Replacement* parameter of **regexp_replace** function is used value from *Src rewrite result* bellow. Returned value of **regexp_replace** function will be used as source number (number A) for the call during future routing. It helps to change format of the source number for providing compatibility. - See :ref:`how to use POSIX Regular Expressions in Yeti `. - Src rewrite result - *Replacement* parameter of **regexp_replace** function from the `POSIX Regular Expressions `_. As *Source* parameter of **regexp_replace** function is used source number (number A), as a *Pattern* parameter of **regexp_replace** function is used value from *Src rewrite rule* above. Returned value of **regexp_replace** function will be used as source number (number A) for the call during future routing. It helps to change format of the source number for providing compatibility. - See :ref:`how to use POSIX Regular Expressions in Yeti `. - Dst rewrite rule - *Pattern* parameter of **regexp_replace** function from the `POSIX Regular Expressions `_. As *Source* parameter of **regexp_replace** function is used destination number (number B), as a *Replacement* parameter of **regexp_replace** function is used value from *Dst rewrite result* bellow. Returned value of **regexp_replace** function will be used as destination number (number B) for the call during future routing. It helps to change format of the destination number for providing compatibility. - See :ref:`how to use POSIX Regular Expressions in Yeti `. - Dst rewrite result - *Replacement* parameter of **regexp_replace** function from the `POSIX Regular Expressions `_. As *Source* parameter of **regexp_replace** function is used destination number (number B), as a *Pattern* parameter of **regexp_replace** function is used value from *Dst rewrite rule* above. Returned value of **regexp_replace** function will be used as destination number (number B) for the call during future routing. It helps to change format of the destination number for providing compatibility. - See :ref:`how to use POSIX Regular Expressions in Yeti `. +Src rewrite rule + *Pattern* parameter of **regexp_replace** function from the `POSIX Regular Expressions `_. As *Source* parameter of **regexp_replace** function is used source number (number A), as a *Replacement* parameter of **regexp_replace** function is used value from *Src rewrite result* bellow. Returned value of **regexp_replace** function will be used as source number (number A) for the call during future routing. It helps to change format of the source number for providing compatibility. + See :ref:`how to use POSIX Regular Expressions in Yeti `. + +Src rewrite result + *Replacement* parameter of **regexp_replace** function from the `POSIX Regular Expressions `_. As *Source* parameter of **regexp_replace** function is used source number (number A), as a *Pattern* parameter of **regexp_replace** function is used value from *Src rewrite rule* above. Returned value of **regexp_replace** function will be used as source number (number A) for the call during future routing. It helps to change format of the source number for providing compatibility. + See :ref:`how to use POSIX Regular Expressions in Yeti `. - Tag action - Describes one of the possible actions that could be applied to the current set of :ref:`Routing Tags ` that are applied for the call with using *Tag action value* below. *Numberlist* it is second step (after *Authentication*) where :ref:`Routing Tags ` can be added to (or removed from) the call. Destination *Numberlist* is processed before the Source *Numberlist*. Following actions can be selected in this field: +Dst rewrite rule + *Pattern* parameter of **regexp_replace** function from the `POSIX Regular Expressions `_. As *Source* parameter of **regexp_replace** function is used destination number (number B), as a *Replacement* parameter of **regexp_replace** function is used value from *Dst rewrite result* bellow. Returned value of **regexp_replace** function will be used as destination number (number B) for the call during future routing. It helps to change format of the destination number for providing compatibility. + See :ref:`how to use POSIX Regular Expressions in Yeti `. - - **Clear tags**. Removes all :ref:`Routing Tags ` from the call (if any were added early); +Dst rewrite result + *Replacement* parameter of **regexp_replace** function from the `POSIX Regular Expressions `_. As *Source* parameter of **regexp_replace** function is used destination number (number B), as a *Pattern* parameter of **regexp_replace** function is used value from *Dst rewrite rule* above. Returned value of **regexp_replace** function will be used as destination number (number B) for the call during future routing. It helps to change format of the destination number for providing compatibility. + See :ref:`how to use POSIX Regular Expressions in Yeti `. - - **Remove selected tags**. Removes only :ref:`Routing Tags ` that were chosen in the *Tag action value* field bellow (if any were chosen) from the call; +Tag action + Describes one of the possible actions that could be applied to the current set of :ref:`Routing Tags ` that are applied for the call with using *Tag action value* below. *Numberlist* it is second step (after *Authentication*) where :ref:`Routing Tags ` can be added to (or removed from) the call. Destination *Numberlist* is processed before the Source *Numberlist*. Following actions can be selected in this field: - - **Append selected tags**. Appends :ref:`Routing Tags ` that were chosen in the *Tag action value* field bellow (if any were chosen) to the call; + - **Clear tags**. Removes all :ref:`Routing Tags ` from the call (if any were added early); - - **Intersection with selected tags**. Yeti leaves as is :ref:`Routing Tags ` that were chosen in the *Tag action value* field bellow (if any were chosen) in the call in case of their presence in the current set of :ref:`Routing Tags ` and removes any other :ref:`Routing Tags ` from the call. + - **Remove selected tags**. Removes only :ref:`Routing Tags ` that were chosen in the *Tag action value* field bellow (if any were chosen) from the call; - Tag action value - In this field :ref:`Routing Tags ` for making some *Tag action* above could be chosen. + - **Append selected tags**. Appends :ref:`Routing Tags ` that were chosen in the *Tag action value* field bellow (if any were chosen) to the call; - Created At - Date and time of this Numberlist item creation. - Updated At - Date and time of last updating of this Numberlist item. + - **Intersection with selected tags**. Yeti leaves as is :ref:`Routing Tags ` that were chosen in the *Tag action value* field bellow (if any were chosen) in the call in case of their presence in the current set of :ref:`Routing Tags ` and removes any other :ref:`Routing Tags ` from the call. +Tag action value + In this field :ref:`Routing Tags ` for making some *Tag action* above could be chosen. +Rewrite SS Status + This attribute allows overriding the original STIR/SHAKEN attestation level by redefining :ref:`Customer Auth Rewrite SS Status value `