topology_hiding Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. OpenSIPS Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. th_callid_passwd (string)
              1.3.2. th_callid_prefix (string)
              1.3.3. th_passed_contact_uri_params (string)
              1.3.4. th_passed_contact_params (string)
              1.3.5. force_dialog (int)
              1.3.6. th_contact_encode_passwd (string)
              1.3.7. th_contact_encode_param (string)
              1.3.8. th_contact_encode_scheme (string)
              1.3.9. th_contact_caller_username_var (string)
              1.3.10. th_contact_callee_username_var (string)

        1.4. Exported Functions

              1.4.1. topology_hiding()
              1.4.2. topology_hiding_match([dlg_match_mode])

        1.5. Exported Pseudo-Variables

              1.5.1. $TH_callee_callid

   2. Contributors

        2.1. By Commit Statistics
        2.2. By Commit Activity

   3. Documentation

        3.1. Contributors

   List of Tables

   2.1. Top contributors by DevScore^(1), authored commits^(2) and
          lines added/removed^(3)

   2.2. Most recently active contributors^(1) to this module

   List of Examples

   1.1. Set th_callid_passwd parameter
   1.2. Set th_callid_prefix parameter
   1.3. Set th_passed_contact_uri_params parameter
   1.4. Set th_passed_contact_params parameter
   1.5. Set force_dialog parameter
   1.6. Set th_contact_encode_passwd parameter
   1.7. Set th_contact_encode_param parameter
   1.8. Set th_contact_encode_scheme parameter
   1.9. Set th_contact_caller_username_var parameter
   1.10. Set th_contact_callee_username_var parameter
   1.11. topology_hiding usage
   1.12. Calling topology_hiding_match() function for topology
          hiding sequential requests

   1.13. topology_hiding_match_dialog() usage

Chapter 1. Admin Guide

1.1. Overview

   This is a module which provides topology hiding capabilities.
   The module can work on top of the dialog module, or as a
   standalone module ( thus alowing topology hiding for all types
   of requests )

1.2. Dependencies

1.2.1. OpenSIPS Modules

   The following modules must be loaded before this module:
     * TM - Transaction Module.
     * Dialog Module, if “force_dialog” module parameter is
       enabled, or a dialog is created from the configuration
       script.

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSIPS with this module loaded:
     * None

1.3. Exported Parameters

1.3.1. th_callid_passwd (string)

   The string password that will be used for encoding/decoding the
   callid in case of topology_hiding with callid mangling.

   Default value is “"OpenSIPS"”

   Example 1.1. Set th_callid_passwd parameter
...
modparam("topology_hiding", "th_callid_passwd", "my_topo_hiding_secret")
...

1.3.2. th_callid_prefix (string)

   The prefix that will be used for detecting callids which have
   been encoded by the dialog topology hiding. Make sure to change
   this value in case your SIP path contains multiple OpenSIPS
   boxes with topology hiding.

   Default value is “"DLGCH_"”

   Example 1.2. Set th_callid_prefix parameter
...
modparam("topology_hiding", "th_callid_prefix", "MYCALLIDPREFIX_")
...

1.3.3. th_passed_contact_uri_params (string)

   List of semicolon-separated Contact URI parameters that will be
   passed from one side to the other for topology hiding calls. To
   be used when end-to-end functionality uses such Contact URI
   parameters.

   Default value is “empty” - do not pass any parameters

   Example 1.3. Set th_passed_contact_uri_params parameter
...
modparam("topology_hiding", "th_passed_contact_uri_params", "paramname1;
myparam;custom_param")
...

1.3.4. th_passed_contact_params (string)

   List of semicolon-separated Contact header parameters that will
   be passed from one side to the other for topology hiding calls.
   To be used when end-to-end functionality uses such Contact
   header parameters.

   Default value is “empty” - do not pass any parameters

   Example 1.4. Set th_passed_contact_params parameter
...
modparam("topology_hiding", "th_passed_contact_params", "paramname1;mypa
ram;custom_param")
...

1.3.5. force_dialog (int)

   If set to 1, the module will internally create the dialog ( if
   not already created ). This will only work for INVITE based
   dialogs, and the dialog module must be loaded.

   Default value is “0”

   Example 1.5. Set force_dialog parameter
...
modparam("topology_hiding", "force_dialog", 1)
...

1.3.6. th_contact_encode_passwd (string)

   When not relying on the dialog module ( due to script writer
   preference or simply when doing topo hiding for non INVITE
   dialogs ), the module will store the needed information in a
   Contact URI param. The parameter configures the string password
   that will be used for encoding/decoding that specific param .

   Default value is “"ToPoCtPaSS"”

   Example 1.6. Set th_contact_encode_passwd parameter
...
modparam("topology_hiding", "th_contact_encode_passwd", "my_topoh_passwd
")
...

1.3.7. th_contact_encode_param (string)

   When not relying on the dialog module ( due to script writer
   preference or simply when doing topo hiding for non INVITE
   dialogs ), the module will store the needed information in a
   Contact URI param. The parameter configures the respective
   parameter name.

   Default value is “"thinfo"”

   Example 1.7. Set th_contact_encode_param parameter
...
modparam("topology_hiding", "th_contact_encode_param", "customparam")
...

1.3.8. th_contact_encode_scheme (string)

   When not relying on the dialog module ( due to script writer
   preference or simply when doing topo hiding for non INVITE
   dialogs ), the module will store the needed information in a
   Contact URI param. This parameter configures the encoding
   scheme to be used for the data stored in the Contact URI param.
   Possible values are:
     * base64
     * base32

   Default value is “"base64"”

   Example 1.8. Set th_contact_encode_scheme parameter
...
modparam("topology_hiding", "th_contact_encode_scheme", "base32")
...

1.3.9. th_contact_caller_username_var (string)

   Variable used to store the value of the contact username
   advertised to the caller.

   Default value is “_th_contact_caller_username_var_”

   Example 1.9. Set th_contact_caller_username_var parameter
...
modparam("topology_hiding", "th_contact_caller_username_var", "__topo_hi
ding_username_var__")
...

1.3.10. th_contact_callee_username_var (string)

   Variable used to store the value of the contact username
   advertised to the callee.

   Default value is “_th_contact_callee_username_var_”

   Example 1.10. Set th_contact_callee_username_var parameter
...
modparam("topology_hiding", "th_contact_callee_username_var", "__topo_hi
ding_username_var__")
...

1.4. Exported Functions

1.4.1.  topology_hiding()

   By calling this function on an initial request, the modules
   will hide the topology, meaning that it will strip and restore
   all the Via, Record-Route and Route headers and it will replace
   the contact with the IP address of the interface where the
   request was received.

   You must note however, that the detection of the future
   in-dialog requests(BYE, reInvite, etc.) for these dialogs on
   which topology hiding is applied, is not done automatically.
   Without topology hiding and only normal dialog, the detection
   was done when loose_route was called. But now, for this dialogs
   where topology hiding is applied, the in dialog requests
   reaching OpenSIPS won't have any Route headers and the RURI
   will point to OpenSIPS machine. So, to be able to match the
   in-dialog requests to the corresponding dialog, a script
   function must be called. It's name is topology_hiding_match and
   you can read it's description above. The in-dialog topology
   requests are requests with a to tag, RURI pointing to opensips
   and with a method specific to a Invite dialog. For this kind of
   requests you should call topology_hiding_match() function. If
   the request is successfully matched and fixed as according to
   the topology hiding logic,the function returns success.

   Optionally,the function also receives a string parameter, which
   holds string flags. Current options for the string flags are :
     * U - Propagate the Username in the Contact header URI
     * D - Dialog ID (DID) is pushed into Contact username, rather
       than URI param. This option makes sense only when using
       topology hiding with dialog support.
     * a - Preserve the advertised Contact header advertised to
       the caller throughout the entire dialog.
     * A - Preserve the advertised Contact header advertised to
       the callee throughout the entire dialog.
     * D - Dialog ID (DID) is pushed into Contact username, rather
       than URI param. This option makes sense only when using
       topology hiding with dialog support.
     * C - Encode the callid header
       There are many cases where propagating the callid towards
       the callee side is not a good idea, since sometimes the
       callid contains the IP of the actual caller side, thus
       revealing part of the network topology.
       When using the "C" flag, the callid will be automatically
       encoded / decoded, transparent for the script writer -
       inside OpenSIPS (script,MI functions, etc ) all the
       variables related to the callid will represent the callid
       value for the caller side. If the callid for the callee
       side is needed, refer to the $TH_callee_callid pvar.
       Note: Changing the callid of the call using the "C" flag is
       only available when doing topology_hiding with dialog
       support. Using this flag without dialog support will not
       change the callid at all!.

   The second parameter can be used to advertise a particular
   username in the Contact header URI, either on the caller,
   either on the callee leg, separated by /. The format of the
   parameter is
   caller_username|/[caller_contact_username][/callee_contact_user
   name]. If the separator is missing, the same contact username
   is advertised on both legs. If the separator is being used, you
   can control the username put in contact per leg.

   Example 1.11. topology_hiding usage
...
if(!has_totag() && is_method("INVITE")) {
        topology_hiding();
}
...
...
if(!has_totag() && is_method("INVITE")) {
        topology_hiding("U");
}
...
# set "opensips" for both caller and the callee's Contact username
if(!has_totag() && is_method("INVITE")) {
        topology_hiding("U", "opensips");
}
...
# set "caller" in the caller's Contact username
if(!has_totag() && is_method("INVITE")) {
        topology_hiding("U", "/caller");
}
...
# set "callee" in the callee's Contact username
if(!has_totag() && is_method("INVITE")) {
        topology_hiding("U", "//callee");
}
...
# set "caller" in the caller's Contact username and
# "callee" in the callee's Contact username
if(!has_totag() && is_method("INVITE")) {
        topology_hiding("U", "/caller/callee");
}
...

   Example 1.12. Calling topology_hiding_match() function for
   topology hiding sequential requests
...
if (has_totag())
        if(topology_hiding_match())
        {
                xlog("Found a request $rm belonging to an existing topol
ogy hiding dialog\n");
                route(relay);
                exit;
        }
}
...

1.4.2.  topology_hiding_match([dlg_match_mode])

   This function is to be used to match and fix a sequential
   request belong to an existing topology hiding dialog.

   With regards to dialog matching (including the optional
   parameter), this function behaves identically to
   match_dialog(). Please see the dialog module documentation for
   further details regarding dialog matching options.

   The function returns true if a topology hiding dialog exists
   for the request and the request has been successfully fixed.

   This function can be used from REQUEST_ROUTE.

   Example 1.13. topology_hiding_match_dialog() usage
...
    if (has_totag()) {
        if (!topology_hiding_match() ) {
            xlog(" cannot match request to a dialog \n");
            send_reply(404,"Not found");
        } else
                route(RELAY);
    }
...

1.5. Exported Pseudo-Variables

1.5.1. $TH_callee_callid

   Read only variable that will contain the callid as it is
   propagated towards the callee side, in case
   topology_hiding("C") is called.

   NULL will be returned if there is no topology hiding dialog for
   the request or if topology_hiding with callid encoding was not
   used for the current dialog.

Chapter 2. Contributors

2.1. By Commit Statistics

   Table 2.1. Top contributors by DevScore^(1), authored
   commits^(2) and lines added/removed^(3)
     Name DevScore Commits Lines ++ Lines --
   1. Razvan Crainea (@razvancrainea) 39 27 728 290
   2. Vlad Paiu (@vladpaiu) 32 8 2700 25
   3. Bogdan-Andrei Iancu (@bogdan-iancu) 25 21 146 88
   4. Liviu Chircu (@liviuchircu) 17 15 81 56
   5. Vlad Patrascu (@rvlad-patrascu) 9 6 82 72
   6. Maksym Sobolyev (@sobomax) 8 6 9 10
   7. Alexey Vasilyev (@vasilevalex) 4 2 3 15
   8. Peter Lemenkov (@lemenkov) 4 2 2 2
   9. James Stanley 3 1 2 2

   (1) DevScore = author_commits + author_lines_added /
   (project_lines_added / project_commits) + author_lines_deleted
   / (project_lines_deleted / project_commits)

   (2) including any documentation-related commits, excluding
   merge commits. Regarding imported patches/code, we do our best
   to count the work on behalf of the proper owner, as per the
   "fix_authors" and "mod_renames" arrays in
   opensips/doc/build-contrib.sh. If you identify any
   patches/commits which do not get properly attributed to you,
   please submit a pull request which extends "fix_authors" and/or
   "mod_renames".

   (3) ignoring whitespace edits, renamed files and auto-generated
   files

2.2. By Commit Activity

   Table 2.2. Most recently active contributors^(1) to this module
                     Name                   Commit Activity
   1. Liviu Chircu (@liviuchircu)         Mar 2015 - Mar 2025
   2. Razvan Crainea (@razvancrainea)     Aug 2015 - Mar 2025
   3. Bogdan-Andrei Iancu (@bogdan-iancu) Mar 2015 - Dec 2023
   4. James Stanley                       Dec 2023 - Dec 2023
   5. Maksym Sobolyev (@sobomax)          Jan 2021 - Nov 2023
   6. Vlad Patrascu (@rvlad-patrascu)     May 2017 - Feb 2020
   7. Peter Lemenkov (@lemenkov)          Jun 2018 - Jan 2020
   8. Alexey Vasilyev (@vasilevalex)      Sep 2019 - Sep 2019
   9. Vlad Paiu (@vladpaiu)               Feb 2015 - Mar 2016

   (1) including any documentation-related commits, excluding
   merge commits

Chapter 3. Documentation

3.1. Contributors

   Last edited by: Razvan Crainea (@razvancrainea), Vlad Patrascu
   (@rvlad-patrascu), Peter Lemenkov (@lemenkov), Liviu Chircu
   (@liviuchircu), Bogdan-Andrei Iancu (@bogdan-iancu), Vlad Paiu
   (@vladpaiu).

   Documentation Copyrights:

   Copyright © 2015 OpenSIPS Foundation
