topoh Module

Daniel-Constantin Mierla

   <miconda@gmail.com>

Edited by

Daniel-Constantin Mierla

   <miconda@gmail.com>

   Copyright © 2009 FhG FOKUS
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Parameters

              3.1. mask_key (str)
              3.2. mask_ip (str)
              3.3. mask_callid (integer)
              3.4. mask_mode (integer)
              3.5. uparam_name (str)
              3.6. uparam_prefix (str)
              3.7. vparam_name (str)
              3.8. vparam_prefix (str)
              3.9. callid_prefix (str)
              3.10. sanity_checks (integer)
              3.11. uri_prefix_checks (integer)
              3.12. event_callback (str)
              3.13. event_mode (int)
              3.14. use_mode (int)

        4. Event Routes

              4.1. event_route[topoh:msg-outgoing]
              4.2. event_route[topoh:msg-sending]

   List of Examples

   1.1. Set mask_key parameter
   1.2. Set mask_ip parameter
   1.3. Set mask_callid parameter
   1.4. Set mask_mode parameter
   1.5. Set uparam_name parameter
   1.6. Set uparam_prefix parameter
   1.7. Set vparam_name parameter
   1.8. Set vparam_prefix parameter
   1.9. Set callid_prefix parameter
   1.10. Set sanity_checks parameter
   1.11. Set uri_prefix_checks parameter
   1.12. Set event_callback parameter
   1.13. Set event_mode parameter
   1.14. Set use_mode parameter
   1.15. Usage of event_route[topoh:msg-outgoing]
   1.16. Usage of event_route[topoh:msg-sending]

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. Parameters

        3.1. mask_key (str)
        3.2. mask_ip (str)
        3.3. mask_callid (integer)
        3.4. mask_mode (integer)
        3.5. uparam_name (str)
        3.6. uparam_prefix (str)
        3.7. vparam_name (str)
        3.8. vparam_prefix (str)
        3.9. callid_prefix (str)
        3.10. sanity_checks (integer)
        3.11. uri_prefix_checks (integer)
        3.12. event_callback (str)
        3.13. event_mode (int)
        3.14. use_mode (int)

   4. Event Routes

        4.1. event_route[topoh:msg-outgoing]
        4.2. event_route[topoh:msg-sending]

1. Overview

   This module hides the SIP routing headers that show topology details.
   It is not affected by the server being transaction stateless or
   stateful. The script interpreter gets the SIP messages decoded, so all
   existing functionality is preserved.

   The module is transparent for the configuration writer. It only needs
   to be loaded (tune the parameters if needed). The SIP server can be
   restarted without affecting ongoing calls - once it is up, can
   encode/decode topology details, thus no call will be lost.

   By using same mask_key, many SIP servers can decode the message, for
   example, applicable for servers behind load balancers.

2. Dependencies

   2.1. Kamailio Modules
   2.2. External Libraries or Applications

2.1. Kamailio Modules

   The following modules must be loaded before this module:
     * rr module - server must perform record routing to ensure in-dialog
       requests are encoded/decoded.

2.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * None. In the future the module can be enhanced to use a stronger
       encryption algorithm.

3. Parameters

   3.1. mask_key (str)
   3.2. mask_ip (str)
   3.3. mask_callid (integer)
   3.4. mask_mode (integer)
   3.5. uparam_name (str)
   3.6. uparam_prefix (str)
   3.7. vparam_name (str)
   3.8. vparam_prefix (str)
   3.9. callid_prefix (str)
   3.10. sanity_checks (integer)
   3.11. uri_prefix_checks (integer)
   3.12. event_callback (str)
   3.13. event_mode (int)
   3.14. use_mode (int)

3.1. mask_key (str)

   Keyword to mask the headers.

   Default value is "_static_value_".

   Example 1.1. Set mask_key parameter
...
modparam("topoh", "mask_key", "some secret here")
...

3.2. mask_ip (str)

   IP address to be used in masked headers to build valid SIP URIs. Can be
   any IP address, even a private-space or non-existing IP address (e.g.,
   192.168.1.1, 127.0.0.2), including the SIP server address, but must not
   be an address potentially used by clients. If set to empty string, the
   advertised IP of the incoming or outgoing socket is used when
   specified, otherwise the IP of the socket is used. Note that the value
   is actually not used at all for SIP routing.

   Default value is "127.0.0.8".

   Example 1.2. Set mask_ip parameter
...
modparam("topoh", "mask_ip", "192.168.0.1")
...

3.3. mask_callid (integer)

   Whether to encode the Call-id: header. Some SIP extensions include the
   Call-id in the SIP message payload or header, so it is safe to not
   encode Call-id in such cases. Well-known extensions such as call
   transfer or conference join will be added to work with encoded Call-id.

   NOTE: if you are using dialog module to terminate calls and this
   parameter is enabled, you must set the dialog module parameter
   'lreq_callee_headers' to include the header: 'TH: dlh\r\n'.

   Default value is 0 (do not mask).

   Example 1.3. Set mask_callid parameter
...
modparam("topoh", "mask_callid", 1)
...

3.4. mask_mode (integer)

   Control when and what parts of SIP message are masked.

   It works as a bitmask value. The following options are available: (1) -
   skip masking Contact headers in 3XX (redirect) replies.

   Default value is 0.

   Example 1.4. Set mask_mode parameter
...
modparam("topoh", "mask_mode", 1)
...

3.5. uparam_name (str)

   Name of URI parameter where to store encoded value.

   Default value is "line".

   Example 1.5. Set uparam_name parameter
...
modparam("topoh", "uparam_name", "myparam")
...

3.6. uparam_prefix (str)

   Prefix to be added in encoded URI parameters.

   Default value is "sr-".

   Example 1.6. Set uparam_prefix parameter
...
modparam("topoh", "uparam_prefix", "xyz")
...

3.7. vparam_name (str)

   Name of Via: parameter used to store encoded value.

   Default value is "branch".

   Example 1.7. Set vparam_name parameter
...
modparam("topoh", "vparam_name", "myv")
...

3.8. vparam_prefix (str)

   Prefix to be added in encoded Via: parameters.

   Default value is "z9hG4bKsr-".

   Example 1.8. Set vparam_prefix parameter
...
modparam("topoh", "vparam_prefix", "xyz")
...

3.9. callid_prefix (str)

   Prefix to be added in encoded Call-ID: headers.

   Default value is "!!:".

   Example 1.9. Set callid_prefix parameter
...
modparam("topoh", "callid_prefix", "***")
...

3.10. sanity_checks (integer)

   If set to 1, topoh module will bind to sanity module in order to
   perform sanity checks over received SIP request. Default sanity checks
   are done. It is useful to check if received request is well formatted
   before proceeding to encoding/decoding.

   Default value is 0 (do not bind to sanity module).

   Example 1.10. Set sanity_checks parameter
...
modparam("topoh", "sanity_checks", 1)
...

3.11. uri_prefix_checks (integer)

   If set to 1, topoh module will check if URIs to be decoded match the
   expected prefix composed from mask IP and parameter name prefix. It can
   make the topoh processing safer by avoiding to try decoding URIs which
   were not encoded previously by topoh.

   Note: do not enable this option if you have SIP devices that can alter
   the URI values it takes from Contact or Record-Route headers (like
   adding port 5060 when no port is in received URIs, or that introduces
   new parameters at an unknown position).

   Default value is 0.

   Example 1.11. Set uri_prefix_checks parameter
...
modparam("topoh", "uri_prefix_checks", 1)
...

3.12. event_callback (str)

   The name of the function in the KEMI configuration file (embedded
   scripting language such as Lua, Python, ...) to be executed instead of
   event_route[...] blocks.

   The function receives a string parameter with the name of the event.

   Default value is 'empty' (no function is executed for events).

   Example 1.12. Set event_callback parameter
...
modparam("topoh", "event_callback", "ksr_topoh_event")
...
-- event callback function implemented in Lua
function ksr_topoh_event(evname)
        KSR.info("===== topoh module triggered event: " .. evname .. "\n");
        return 1;
end
...

3.13. event_mode (int)

   Control what event_route blocks to be executed. It is a bitmask of: 1 -
   execute event_route[topoh:msg-outgoing]; 2 - execute
   event_route[topoh:msg-sending].

   Default value is 3 (execute both event_route blocks).

   Example 1.13. Set event_mode parameter
...
modparam("topoh", "event_mode", 2)
...

3.14. use_mode (int)

   Control how the module is initialized. If set to 1, the module is only
   initialized to be used as a library via inter-module API functions. If
   set to 0, the module is initialized for SIP messages processing.

   Default value is 0 (to process SIP messages).

   Example 1.14. Set use_mode parameter
...
modparam("topoh", "use_mode", 1)
...

4. Event Routes

   4.1. event_route[topoh:msg-outgoing]
   4.2. event_route[topoh:msg-sending]

4.1. event_route[topoh:msg-outgoing]

   It is executed before doing topology hiding processing for an outgoing
   SIP message. If 'drop' is executed inside the event route, then the
   module skips doing the topology hiding.

   Inside the event route the variables $sndto(ip), $sndto(port) and
   $sndto(proto) point to the destination. The SIP message is not the one
   to be sent out, but an internally generated one at startup, to avoid
   reparsing the outgoing SIP message for the cases when topology hiding
   is not wanted.

   Example 1.15. Usage of event_route[topoh:msg-outgoing]
...
event_route[topoh:msg-outgoing] {
  if($sndto(ip)=="10.1.1.10") {
    drop;
  }
}
...

4.2. event_route[topoh:msg-sending]

   It is executed before doing topology hiding processing for a SIP
   message to be sent out, being executed after
   event_route[topoh:msg-outgoing].

   Inside the event route the variables $sndto(ip), $sndto(port) and
   $sndto(proto) point to the destination. The SIP message is the one to
   be sent out.

   Example 1.16. Usage of event_route[topoh:msg-sending]
...
event_route[topoh:msg-sending] {
  if(is_request() and $fU=="alice") {
    drop;
  }
}
...
