WIP: privacy improvements

en/best-practices/sip-headers.rst

@@ -0,0 +1,79 @@
+
+
+.. _sip_headers:
+
+===========
+SIP Headers
+===========
+
+This document explains some common SIP message headers
+
+
+Headers formats. URI
+====================
+
+ * `RFC2806 <https://datatracker.ietf.org/doc/html/rfc2806>`_- Standard - URLs for Telephone Calls
+ * `RFC5630 <https://datatracker.ietf.org/doc/html/rfc5630>`_ - Standard - The Use of the SIPS URI Scheme in the Session Initiation Protocol (SIP)
+ * `RFC3966 <https://datatracker.ietf.org/doc/html/rfc3966>`_ - Standard - The tel URI for Telephone Numbers
+
+
+sip uri with **user=phone** parameter:
+
+ `RFC3398 <https://datatracker.ietf.org/doc/html/rfc3398>`_ - Standard - Integrated Services Digital Network (ISDN) User Part (ISUP) to Session Initiation Protocol (SIP) Mapping
+ `RFC3261 Section-19.1.6 <https://datatracker.ietf.org/doc/html/rfc3261#section-19.1.6>`_ - Relating SIP URIs and tel URLs
+
+
+P-Asserted-Identity
+===================
+
+The P-Asserted-Identity header field can be used to convey the proven identity of the originator of a request within a trusted network. Since the From header field is populated by the originating UA it may not necessarily contain the actual identity. It usually is established by means of authentication between the originating UA and its outgoing proxy. The outgoing proxy then adds a P-Asserted-Identity header field to assert the identity of the originator to other proxies.
+
+This header field has only meaning within what is called a trusted network by mutual agreement on the requirements for its use by the parties involved.
+
+The P-Asserted-Identity header field is defined in RFC 3325.
+
+Source: `z9hg4bk.org <http://www.z9hg4bk.org/sip/hf/p-asserted-identity.html>`_
+
+- `RFC3325 <https://datatracker.ietf.org/doc/html/rfc3325>`_ - Informational - Private Extensions to the Session Initiation Protocol (SIP) for Asserted Identity within Trusted Networks
+
+
+P-Preferred-Identity
+====================
+
+
+
+.. _sip_headers_privacy:
+
+Privacy
+=======
+
+Privacy framework allows to hide address information from non-trusted network elements(usually end-user terminals or gateways). In Yeti trusted domain boundaries configured by customers auth Privacy mode and termination gateway Privacy mode.
+
+RFCs to read:
+
+    - `RFC3323 <https://datatracker.ietf.org/doc/html/rfc3323>`_ - Standard - A Privacy Mechanism for the Session Initiation Protocol (SIP)
+    - `RFC3325 <https://datatracker.ietf.org/doc/html/rfc3325>`_ - Informational - Private Extensions to the Session Initiation Protocol (SIP) for Asserted Identity within Trusted Networks
+    - `RFC5379 <https://datatracker.ietf.org/doc/html/rfc5379>`_ - Informational - Guidelines for Using the Privacy Mechanism for SIP
+
+
+.. _sip_headers_privacy_critical:
+
+Critical private calls
+    Calls where Privacy header includes value **critical**. Such calls should be dropped if system can't provide proper privacy level.
+    See `RFC3323 section-4.2 <https://datatracker.ietf.org/doc/html/rfc3323#section-4.2>`_ for details
+
+
+.. _sip_headers_diversion:
+
+Diversion Header
+================
+
+`RFC5806 <https://datatracker.ietf.org/doc/html/rfc5806>`_ - Historical
+`RFC4244 <https://datatracker.ietf.org/doc/html/rfc4244>`_ - History-Info header
+
+
+Call scenarios Examples
+=======================
+
+`RFC5359 <https://datatracker.ietf.org/doc/html/rfc5359>`_
+

en/conf.py

@@ -299,7 +299,7 @@
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 # texinfo_no_detailmenu = False
 
-linkcheck_ignore = ["sip:sip-proxy.example.com"]
+linkcheck_ignore = ["sip:sip-proxy.example.com", "http://www.z9hg4bk.org/sip/hf/p-asserted-identity.html"]
 linkcheck_anchors_ignore = ["L50"]
 
 html_context = {

en/index.rst

@@ -32,6 +32,7 @@ Welcome to Yeti's documentation!
 
    quick-start/quick_start.rst
    disconnect-codes
+   best-practices/sip-headers.rst
    best-practices/headers-transit.rst
    best-practices/numbers-translations.rst
    best-practices/teams-direct-routing.rst

en/spelling_wordlist.txt

@@ -18,12 +18,15 @@ Auth
 auth
 Auths
 Autorefresh
+anonymized
+
 backend
 Balancer
 balancer
 Balancers
 blockedPages
 blocklist
+
 callee
 callid
 cdr
@@ -43,6 +46,8 @@ crt
 CSeq
 cseq
 Csv
+Cnam
+
 Datagram
 decrypt
 di

en/web-interface/equipment/gateways.rst

@@ -416,19 +416,31 @@ Translations attributes
 =======================
 
 Privacy mode
-    TODO
+    Mode of privacy processing for calls terminated to gateway. Available options:
+
+    - **Do nothing**
+    - **Skip for private calls** - gateway will be excluded from routeset during private call routing.
+    - **Skip for critical private calls** - gateway will be excluded from routeset during private **critical** call routing.
+    - **Not trusted gw. Apply** - Private call will be anonymized before sending call to gateway in order to hide private information.
+    - **Trusted gw. Forward** - Private call will be sent to termination gw. PAI, PPI and From headers will ne not anonymized.
+    - **Trusted gw. Forward. Anonymize From** - Private call will be sent to termination gw, From header will be anonymized.
 
 Termination SRC Numberlist
     TODO
 
 Termination DST Numberlist
     TODO
 
+.. _gateways_diversion_send_mode:
+
 Diversion send mode
     TODO
+    - Do not send
+    - Send as SIP URI
+    - Send as Tel URI
 
 Diversion domain
-    TODO
+    Domain part of **Diversion** header generated by **Diversion Send mode** logic.
 
 Diversion rewrite rule
     Regular expression pattern for Diversion.
@@ -450,17 +462,13 @@ PAI Send mode
     - Relay PAI/PPI as TEL uri
         Build **P-Asserted-Identity** and **P-Preferred-Identity** as `tel URI <https://datatracker.ietf.org/doc/html/rfc3966>`_  based on P-Asserted-Identity and P-Preferred-Identity received from call legA.
 
-        .. warning:: Experimental feature.  Disabled by default.
-
     - Relay PAI/PPI as SIP uri
         Build **P-Asserted-Identity** and **P-Preferred-Identity** as **sip URI**  based on P-Asserted-Identity and P-Preferred-Identity received from call legA. If PAI and PPI headers received on legA have sip URI format, domain will be preserved. Otherwise **PAI Domain** will be used.
 
-        .. warning:: Experimental feature.  Disabled by default.
-
     - Relay PAI/PPI as SIP uri. Replace domain
         Build **P-Asserted-Identity** and **P-Preferred-Identity** as **sip URI**  based on P-Asserted-Identity and P-Preferred-Identity received from call legA. Domain part will be replaced with **PAI Domain** value.
 
-        .. warning:: Experimental feature.  Disabled by default.
+    .. warning:: **Relay PAI/PPI as TEL uri**, **Relay PAI/PPI as SIP uri**, **Relay PAI/PPI as SIP uri. Replace domain** are experimental featured.  Disabled by default.
 
     Modes that relays headers from call legA also require proper :ref:`PAI Policy <customers_auth_pai_policy>` configuration at CustomersAuth object. **P-Asserted-Identity** and **P-Preferred-Identity** values sent to termination gateway will be saved in :ref:`CDR attributes PAI Out and PPI OUT <cdr_pai>`
 
@@ -511,10 +519,7 @@ Sdp c location
 
 Codec group
     Codecs group which will be used to interact with this gateway.
-
-Anonymize sdp
-    Anonymize client's SDP session data ( session name, uri, origin user ).
-
+
 Proxy media
     Determines RTP processing mode. Must be enabled to have possibility of transcoding.
 

en/web-interface/routing/customers-auths.rst

@@ -283,95 +283,109 @@ Match condition options
 Number translation options
 ``````````````````````````
 
-    Diversion policy
-        Defines what to do with Diversion header within SIP-signalization.
-        Default value is "Clear header", so this header will be deleted.
-    Diversion rewrite rule
-        This option should contain a regular expression for changing a Diversion header.
-        See :ref:`how to use POSIX Regular Expressions in Yeti <posix_regular_expressions2>`.
-    Diversion rewrite result
-        The result of changing a Diversion header, using the Rewrite Rule above.
-        See :ref:`how to use POSIX Regular Expressions in Yeti <posix_regular_expressions2>`.
-
-    .. _customers_auth_pai_policy:
-
-    PAI Policy
-        **P-Asserted-Identity** and **P-Preferred-Identity** headers processing logic. Available options:
-
-        - Do not accept
-            Do not accept incoming **P-Asserted-Identity** and **P-Preferred-Identity** data. It will not be possible to relay PAI and PPI to termination gateway
-
-        - Accept
-            Accept incoming **P-Asserted-Identity** and **P-Preferred-Identity** data. It will be possible to relay PAI and PPI to termination gateway
-
-        - Require
-            Yeti will reject call if no **P-Asserted-Identity** header received from call originator
-
-        **P-Asserted-Identity** and **P-Preferred-Identity** values received from call originator will be saved in :ref:`CDR attributes PAI In and PPI In <cdr_pai>`
-
-    PAI Rewrite rule/PAI Rewrite result
-        Rewrite rules for **P-Asserted-Identity** and **P-Preferred-Identity** URI user-part.
-        See :ref:`how to use POSIX Regular Expressions in Yeti <posix_regular_expressions2>`.
-
-        .. warning:: Experimental feature.  Disabled by default.
-
-    Src name rewrite rule
-        This field should contain a regular expression for changing the Name field in the Source-number within SIP-signalization.
-        See :ref:`how to use POSIX Regular Expressions in Yeti <posix_regular_expressions2>`.
-    Src name rewrite result
-        The result of changing the Name field in the Source-number, using the Src name rewrite rule above.
-        See :ref:`how to use POSIX Regular Expressions in Yeti <posix_regular_expressions2>`.
-    Src rewrite rule
-        This field should contain a regular expression for changing the Source-number within SIP-signalization.
-        See :ref:`how to use POSIX Regular Expressions in Yeti <posix_regular_expressions2>`.
-    Src rewrite result
-        The result of changing the Source-number, using the Src rewrite rule above.
-        See :ref:`how to use POSIX Regular Expressions in Yeti <posix_regular_expressions2>`.
-    Dst rewrite rule
-        This field should contain a regular expression for changing the Destination-number within SIP-signalization.
-        See :ref:`how to use POSIX Regular Expressions in Yeti <posix_regular_expressions2>`.
-    Dst rewrite result
-        The result of changing the Name field in the Destination-number, using the Dst rewrite rule above.
-        See :ref:`how to use POSIX Regular Expressions in Yeti <posix_regular_expressions2>`.
-
-    .. _radius_options:
+Privacy mode
+    Processing mode for :ref:`Private calls <sip_headers_privacy>`. Available options:
+
+    - Allow any calls
+    - Reject private calls - Private calls will be rejected
+    - Reject critical private calls - Critical private calls will be rejected
+    - Reject anonymous calls(no CLI/PAI/PPI) - Private calls with anonymous From, PAI, PPI headers will be rejected
+
+Diversion policy
+    Defines what to do with :ref:`Diversion <sip_headers_diversion>` header received in initial INVITE from call originator. Available options:
+
+    - Do not accept - Yeti will not process incoming **Diversion** header
+    - Accept - Yeti will accept Diversion header. It will be possible to relay it to termination gateway according to :ref:`Diversion Send Mode <gateways_diversion_send_mode>`
+
+Diversion rewrite rule/Diversion rewrite result
+    Rewrite rules for **Diversion** URI user-part. See :ref:`how to use POSIX Regular Expressions in Yeti <posix_regular_expressions2>`.
+
+.. _customers_auth_pai_policy:
+
+PAI Policy
+    **P-Asserted-Identity** and **P-Preferred-Identity** headers processing logic. Available options:
+
+    - Do not accept
+        Do not accept incoming **P-Asserted-Identity** and **P-Preferred-Identity** data. It will not be possible to relay PAI and PPI to termination gateway
+
+    - Accept
+        Accept incoming **P-Asserted-Identity** and **P-Preferred-Identity** data. It will be possible to relay PAI and PPI to termination gateway
+
+    - Require
+        Yeti will reject call if no **P-Asserted-Identity** header received from call originator
+
+    **P-Asserted-Identity** and **P-Preferred-Identity** values received from call originator will be saved in :ref:`CDR attributes PAI In and PPI In <cdr_pai>`
+
+PAI Rewrite rule/PAI Rewrite result
+    Rewrite rules for **P-Asserted-Identity** and **P-Preferred-Identity** URI user-part.
+    See :ref:`how to use POSIX Regular Expressions in Yeti <posix_regular_expressions2>`.
+
+    .. warning:: Experimental feature.  Disabled by default.
+
+Src name Field
+    Src name Field setting defined where yeti reading Src Name from. Available options:
+
+    - From URI Display name - use From header display name as Src Name
+    - From URI :spelling:ignore:`:spelling:ignore:`userpart`` - use From header user part as Src Name
+
+Src name rewrite rule/Src name rewrite result
+    Rewrite rules for SRC Name. See :ref:`how to use POSIX Regular Expressions in Yeti <posix_regular_expressions2>`.
+
+Src number Field
+    Src number Field setting defined where yeti reading Src Number from. Available options:
+
+    - From URI :spelling:ignore:`userpart` - use From header user part as Src Name
+    - From URI Display name - use From header display name as Src Name
+
+Src rewrite rule/Src rewrite result
+    Rewrite rules for SRC Number. See :ref:`how to use POSIX Regular Expressions in Yeti <posix_regular_expressions2>`.
+
+Dst number field
+    TODO
+    - R-URI :spelling:ignore:`userpart`
+    - To URI :spelling:ignore:`userpart`
+    - Top Diversion header :spelling:ignore:`userpart`
+
+Dst rewrite rule/Dst rewrite result
+    Rewrite rules for Destination number.
+    See :ref:`how to use POSIX Regular Expressions in Yeti <posix_regular_expressions2>`.
+
+Cnam Database
+    TODO
+
+.. _radius_options:
 
 Radius options
 ``````````````
 
-    Radius auth profile
-        Must be specified if the additional radius authentication is required.
-    Src number radius rewrite rule
-        Should contain regular expression for changing Source-number which will be send to Radius-server if it's required.
-        See :ref:`how to use POSIX Regular Expressions in Yeti <posix_regular_expressions2>`.
-    Src number radius rewrite result
-        The result of applying the Src number radius rewrite rule to Source-number.
-        See :ref:`how to use POSIX Regular Expressions in Yeti <posix_regular_expressions2>`.
-    Dst number radius rewrite rule
-        Should contain regular expression for changing Destination-number which will be send to Radius-server if it's required.
-        See :ref:`how to use POSIX Regular Expressions in Yeti <posix_regular_expressions2>`.
-    Dst number radius rewrite result
-        The result of applying the Dst number radius rewrite rule to Destination-number.
-        See :ref:`how to use POSIX Regular Expressions in Yeti <posix_regular_expressions2>`.
-    Radius accounting profile
-        Must be specified if the radius accounting is required.
+Radius auth profile
+    Must be specified if the additional radius authentication is required.
 
-    .. _routing_tags_options:
+Src number radius rewrite rule/Src number radius rewrite result
+    Rewrite rules for changing Source-number which will be send to Radius-server if it's required.
+    See :ref:`how to use POSIX Regular Expressions in Yeti <posix_regular_expressions2>`.
 
-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:
 
-            -   **Clear tags**. Removes all :ref:`Routing Tags <routing_tag>` from the call (if any were added early);
+Dst number radius rewrite rule/Dst number radius rewrite result
+    Rewrite rules for changing Destination-number which will be send to Radius-server if it's required.
+    See :ref:`how to use POSIX Regular Expressions in Yeti <posix_regular_expressions2>`.
 
-            -   **Remove selected tags**. Removes only :ref:`Routing Tags <routing_tag>` that were chosen in the *Tag action value* field bellow (if any were chosen) from the call;
+Radius accounting profile
+    Must be specified if the radius accounting is required.
 
-            -   **Append selected tags**. Appends :ref:`Routing Tags <routing_tag>` that were chosen in the *Tag action value* field bellow (if any were chosen) to the call;
+    .. _routing_tags_options:
+
+Routing Tags options
+````````````````````
 
-            -   **Intersection with selected tags**. Yeti leaves as is :ref:`Routing Tags <routing_tag>` 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 <routing_tag>` and removes any other :ref:`Routing Tags <routing_tag>` from the call.
+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:
 
+    - **Clear tags**. Removes all :ref:`Routing Tags <routing_tag>` from the call (if any were added early);
+    - **Remove selected tags**. Removes only :ref:`Routing Tags <routing_tag>` that were chosen in the *Tag action value* field bellow (if any were chosen) from the call;
+    - **Append selected tags**. Appends :ref:`Routing Tags <routing_tag>` that were chosen in the *Tag action value* field bellow (if any were chosen) to the call;
+    - **Intersection with selected tags**. Yeti leaves as is :ref:`Routing Tags <routing_tag>` 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 <routing_tag>` and removes any other :ref:`Routing Tags <routing_tag>` from the call.
 
-    Tag action value
-        In this field :ref:`Routing Tags <routing_tag>` for making some *Tag action* above could be chosen.
+Tag action value
+    In this field :ref:`Routing Tags <routing_tag>` for making some *Tag action* above could be chosen.