src/modules/peering/README
f9742764
 Peering Module
 
 Juha Heinanen
 
    <jh@tutpro.com>
 
 Edited by
 
 Juha Heinanen
 
    <jh@tutpro.com>
 
d9bb387b
    Copyright © 2008 Juha Heinanen
39adc361
      __________________________________________________________________
f9742764
 
    Table of Contents
 
    1. Admin Guide
 
39adc361
         1. Overview
         2. Dependencies
f9742764
 
39adc361
               2.1. Kamailio Modules
               2.2. External Libraries or Applications
f9742764
 
ba7961bb
         3. Parameters
f9742764
 
39adc361
               3.1. radius_config (string)
               3.2. verify_destination_service_type (integer)
               3.3. verify_source_service_type (integer)
f9742764
 
ba7961bb
         4. Functions
f9742764
 
39adc361
               4.1. verify_destination()
               4.2. verify_source()
f9742764
 
    List of Examples
 
    1.1. radius_config parameter usage
    1.2. verify_destination_service_type parameter usage
    1.3. verify_source_service_type parameter usage
    1.4. verify_destination() usage
    1.5. verify_source() usage
 
 Chapter 1. Admin Guide
 
39adc361
    Table of Contents
 
    1. Overview
    2. Dependencies
 
         2.1. Kamailio Modules
         2.2. External Libraries or Applications
 
ba7961bb
    3. Parameters
39adc361
 
         3.1. radius_config (string)
         3.2. verify_destination_service_type (integer)
         3.3. verify_source_service_type (integer)
 
ba7961bb
    4. Functions
39adc361
 
         4.1. verify_destination()
         4.2. verify_source()
 
 1. Overview
 
    The peering module allows SIP providers (operators or organizations) to
    verify from a broker if source or destination of a SIP request is a
    trusted peer.
 
    In order to participate in the trust community provided by a broker,
    each SIP provider registers the domains (host parts of SIP URIs) that
    they serve with the broker. When a SIP proxy of a provider needs to
    send a SIP request to a non-local domain, it can find out from the
    broker using verify_destination() function if the non-local domain is
    served by a trusted peer. If so, the provider receives from the broker
    a hash of the SIP request and a timestamp that it includes in the
    request to the non-local domain. When a SIP proxy of the non-local
    domain receives the SIP request, it, in turn, can verify from the
    broker using verify_source() function if the request came from a
    trusted peer.
989206bd
 
    Verification functions communicate with the broker using Radius
39adc361
    protocol. Sample FreeRADIUS configuration files for broker's Radius
    server are available from http://www.wirlab.net/tsi/.
6e599899
 
    Comments and suggestions for improvements are welcome.
f9742764
 
39adc361
 2. Dependencies
f9742764
 
39adc361
    2.1. Kamailio Modules
    2.2. External Libraries or Applications
f9742764
 
39adc361
 2.1. Kamailio Modules
 
    The module depends on the following modules (in the other words the
    listed modules must be loaded before this module):
f9742764
      * none
 
39adc361
 2.2. External Libraries or Applications
 
    The following libraries or applications must be installed before
8868e624
    compiling Kamailio with this module loaded:
39adc361
      * radiusclient-ng 0.5.0 or higher -- library and development files.
        See http://developer.berlios.de/projects/radiusclient-ng/.
f9742764
 
ba7961bb
 3. Parameters
f9742764
 
39adc361
    3.1. radius_config (string)
    3.2. verify_destination_service_type (integer)
    3.3. verify_source_service_type (integer)
f9742764
 
39adc361
 3.1. radius_config (string)
f9742764
 
39adc361
    This is the location of the configuration file of Radius client
989206bd
    libraries.
f9742764
 
d9bb387b
    Default value is “/usr/local/etc/radiusclient-ng/radiusclient.conf”.
f9742764
 
    Example 1.1. radius_config parameter usage
 modparam("peering", "radius_config", "/etc/broker/radiusclient.conf")
 
39adc361
 3.2. verify_destination_service_type (integer)
f9742764
 
39adc361
    This is the value of the Service-Type Radius attribute to be used, when
    sender of SIP Request verifies the request's destination using
    verify_destination() function.
f9742764
 
d9bb387b
    Default value is the dictionary value of “Sip-Verify-Destination”
f9742764
    Service-Type.
 
    Example 1.2. verify_destination_service_type parameter usage
 modparam("peering", "verify_destination_service_type", 21)
 
39adc361
 3.3. verify_source_service_type (integer)
f9742764
 
39adc361
    This is the value of the Service-Type Radius attribute to be used, when
    receiver of SIP Request verifies the request's source using
    verify_source() function.
f9742764
 
d9bb387b
    Default value is the dictionary value of “Sip-Verify-Source”
f9742764
    Service-Type.
 
    Example 1.3. verify_source_service_type parameter usage
 modparam("peering", "verify_source_service_type", 22)
 
ba7961bb
 4. Functions
39adc361
 
    4.1. verify_destination()
    4.2. verify_source()
f9742764
 
39adc361
 4.1. verify_destination()
f9742764
 
39adc361
    Function verify_destination() queries from broker's Radius server if
    domain (host part) of Request URI is served by a trusted peer. Radius
    request contains the following attributes/values:
f9742764
      * User-Name - Request-URI host
      * SIP-URI-User - Request-URI user
      * SIP-From-Tag - From tag
      * SIP-Call-Id - Call id
      * Service-Type - verify_destination_service_type
 
39adc361
    Function returns value 1 if domain of Request URI is served by a
    trusted peer and -1 otherwise. In case of positive result, the Radius
    server returns a set of SIP-AVP reply attributes. The value of each
    SIP-AVP is of form:
f9742764
 
    [#]name(:|#)value
 
39adc361
    Value of each SIP-AVP reply attribute is mapped to an Kamailio AVP.
    Prefix # in front of name or value indicates a string name or string
    value, respectively.
f9742764
 
39adc361
    One of the SIP-AVP reply attributes contains a string that the source
    peer must include "as is" in a P-Request-Hash: header when it sends the
    SIP request to the destination peer. The string value may, for example,
    be of form hash@timestamp, where hash contains a hash calculated by the
    broker based on the attributes of the query and some local information
    and timestamp is the time when the calculation was done.
f9742764
 
    AVP names used in reply attributes are assigned by the broker.
 
989206bd
    This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
f9742764
 
    Example 1.4. verify_destination() usage
 ...
 if (verify_destination()) {
660402eb
    append_hf("P-Request-Hash: $avp(i:200)\r\n");
f9742764
 }
 ...
 
39adc361
 4.2. verify_source()
f9742764
 
39adc361
    Function verify_source() queries the broker's Radius server whether the
    SIP request was received from a trusted peer. The Radius request
989206bd
    contains the following attributes/values:
f9742764
      * User-Name - Request-URI host
      * SIP-URI-User - Request-URI user
      * SIP-From-Tag - From tag
      * SIP-Call-Id - Call id
      * SIP-Request-Hash - body of P-Request-Hash header
      * Service-Type - verify_source_service_type
 
39adc361
    Function returns value 1 if SIP request was received from a trusted
    peer and -1 otherwise. In case of positive result, Radius server may
    return a set of SIP-AVP reply attributes. Value of each SIP-AVP is of
    form:
f9742764
 
    [#]name(:|#)value
 
39adc361
    Value of each SIP-AVP reply attribute is mapped to an Kamailio AVP.
    Prefix # in front of name or value indicates a string name or string
    value, respectively.
f9742764
 
    AVP names used in reply attributes are assigned by the broker.
 
989206bd
    This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
f9742764
 
    Example 1.5. verify_source() usage
 ...
 if (is_present_hf("P-Request-Hash")) {
    if (verify_source()) {
       xlog("L_INFO", "Request came from trusted peer\n")
    }
 }
 ...