modules/osp/README
ac238d6a
 OSP Module for Secure, Multi-Lateral Peering
62689231
 
ac238d6a
 Ulrich Abend
62689231
 
4f879832
    FhG FOKUS
 
    <ullstar@iptel.org>
62689231
 
ac238d6a
 Edited by
62689231
 
ac238d6a
 Di-Shi Sun
62689231
 
d77df08a
    TransNexus, Inc.
 
    <support@transnexus.com>
 
779bb373
    Copyright © 2003 FhG FOKUS
      __________________________________________________________________
62689231
 
    Table of Contents
d77df08a
 
9fc784c6
    1. Admin Guide
ac238d6a
 
779bb373
         1. Overview
         2. Dependencies
ba7961bb
         3. Parameters
779bb373
 
               3.1. sp1_uri, sp2_uri, ..., sp16_uri
               3.2. sp1_weight, sp2_weight, ..., sp16_weight
               3.3. device_ip
               3.4. device_port
               3.5. token_format
               3.6. private_key, local_certificate, ca_certificates
               3.7. enable_crypto_hardware_support
               3.8. ssl_lifetime
               3.9. persistence
               3.10. retry_delay
               3.11. retry_limit
               3.12. timeout
               3.13. max_destinations
               3.14. validate_call_id
               3.15. use_rpid_for_calling_number
               3.16. redirection_uri_format
               3.17. source_networkid_avp
 
ba7961bb
         4. Functions
779bb373
 
               4.1. checkospheader()
               4.2. validateospheader()
               4.3. requestosprouting()
               4.4. checkosproute()
               4.5. prepareosproute()
               4.6. checkcallingtranslation()
               4.7. prepareallosproute()
               4.8. reportospusage()
ac238d6a
 
9fc784c6
    2. Developer Guide
ac238d6a
 
    List of Examples
d77df08a
 
    1.1. Setting the OSP servers
9cbd0164
    1.2. Setting the OSP server weights
    1.3. Setting the device IP address
    1.4. Setting the device port
    1.5. Setting the token format
    1.6. Set authorization files
d77df08a
    1.7. Setting the hardware support
    1.8. Setting the ssl lifetime
    1.9. Setting the persistence
    1.10. Setting the retry delay
    1.11. Setting the retry limit
    1.12. Setting the timeout
    1.13. Setting the number of destination
    1.14. Instructing the module to validate call id
779bb373
    1.15. Instructing the module to use calling number in Remote-Party-ID
9cbd0164
    1.16. Setting the redirection URI format
    1.17. Setting the source network ID AVP
    1.18. checkospheader usage
    1.19. validateospheader usage
    1.20. requestosprouting usage
    1.21. checkosproute usage
    1.22. prepareosproute usage
    1.23. checkcallingtranslation usage
    1.24. prepareallosproute usage
    1.25. reportospusage usage
ac238d6a
 
9fc784c6
 Chapter 1. Admin Guide
ac238d6a
 
779bb373
    Table of Contents
ac238d6a
 
779bb373
    1. Overview
    2. Dependencies
ba7961bb
    3. Parameters
779bb373
 
         3.1. sp1_uri, sp2_uri, ..., sp16_uri
         3.2. sp1_weight, sp2_weight, ..., sp16_weight
         3.3. device_ip
         3.4. device_port
         3.5. token_format
         3.6. private_key, local_certificate, ca_certificates
         3.7. enable_crypto_hardware_support
         3.8. ssl_lifetime
         3.9. persistence
         3.10. retry_delay
         3.11. retry_limit
         3.12. timeout
         3.13. max_destinations
         3.14. validate_call_id
         3.15. use_rpid_for_calling_number
         3.16. redirection_uri_format
         3.17. source_networkid_avp
 
ba7961bb
    4. Functions
779bb373
 
         4.1. checkospheader()
         4.2. validateospheader()
         4.3. requestosprouting()
         4.4. checkosproute()
         4.5. prepareosproute()
         4.6. checkcallingtranslation()
         4.7. prepareallosproute()
         4.8. reportospusage()
 
 1. Overview
 
    The OSP module enables Kamailio to support secure, multi-lateral
    peering using the OSP standard defined by ETSI (TS 101 321 V4.1.1).
    This module will enable your Kamailio to:
6fb4bf09
      * Send a peering authorization request to a peering server.
779bb373
      * Validate a digitally signed peering authorization token received in
        a SIP INVITE message.
6fb4bf09
      * Report usage information to a peering server.
62689231
 
779bb373
 2. Dependencies
62689231
 
779bb373
    The OSP module depends on the following modules which must be loaded
    before the OSP module.
4f879832
      * sl -- stateless replier
      * tm -- stateful processing
      * rr -- Record-Route/Route operation
62689231
      * textops -- text based operation
779bb373
      * siputils -- Remote-Party-ID operattion
ac238d6a
      * OSP Toolkit -- The OSP Toolkit, available from
779bb373
        http://sourceforge.net/projects/osp-toolkit, must be built before
        building Kamailio with the OSP Module. For instructions on building
        Kamailio with the OSP Toolkit, see
        http://www.transnexus.com/White%20Papers/Multi-Lateral_Peering_with
        _Kamailio_V1.4.pdf
 
ba7961bb
 3. Parameters
779bb373
 
    3.1. sp1_uri, sp2_uri, ..., sp16_uri
    3.2. sp1_weight, sp2_weight, ..., sp16_weight
    3.3. device_ip
    3.4. device_port
    3.5. token_format
    3.6. private_key, local_certificate, ca_certificates
    3.7. enable_crypto_hardware_support
    3.8. ssl_lifetime
    3.9. persistence
    3.10. retry_delay
    3.11. retry_limit
    3.12. timeout
    3.13. max_destinations
    3.14. validate_call_id
    3.15. use_rpid_for_calling_number
    3.16. redirection_uri_format
    3.17. source_networkid_avp
 
 3.1. sp1_uri, sp2_uri, ..., sp16_uri
 
    These sp_uri (string) parameters define peering servers to be used for
    requesting peering authorization and routing information. At least one
    peering server must be configured. Others are required only if there
    are more than one peering servers. Each peering server address takes
    the form of a standard URL, and consists of up to four components:
      * An optional indication of the protocol to be used for communicating
        with the peering server. Both HTTP and HTTP secured with SSL/TLS
        are supported and are indicated by "http://" and "https://"
        respectively. If the protocol is not explicitly indicated, the
        Kamailio defaults to HTTP secured with SSL.
      * The Internet domain name for the peering server. An IP address may
        also be used, provided it is enclosed in square brackets such as
        [172.16.1.1].
      * An optional TCP port number for communicating with the peering
        server. If the port number is omitted, the Kamailio defaults to
        port 1080 (for HTTP) or port 1443 (for HTTP secured with SSL).
        The uniform resource identifier for requests to the peering server.
        This component is not optional and must be included.
ac238d6a
 
d77df08a
    Example 1.1. Setting the OSP servers
989206bd
 modparam("osp","sp1_uri","http://osptestserver.transnexus.com:1080/osp")
4f879832
 modparam("osp","sp2_uri","https://[1.2.3.4]:1443/osp")
ac238d6a
 
779bb373
 3.2. sp1_weight, sp2_weight, ..., sp16_weight
9cbd0164
 
779bb373
    These sp_weight (integer) parameters are used for load balancing
    peering requests to peering servers. These parameters are most
    effective when configured as factors of 1000. For example, if sp1_uri
    should manage twice the traffic load of sp2_uri, then set sp1_weight to
    2000 and sp2_weight to 1000. Shared load balancing between peering
    servers is recommended. However, peering servers can be configured as
    primary and backup by assigning a sp_weight of 0 to the primary server
    and a non-zero sp_weight to the back-up server. The default values for
    sp1_weight and sp2_weight are 1000.
9cbd0164
 
    Example 1.2. Setting the OSP server weights
 modparam("osp","sp1_weight",1000)
 
779bb373
 3.3. device_ip
ac238d6a
 
779bb373
    The device_ip (string) is a recommended parameter that explicitly
    defines the IP address of Kamailio in a peering request message (as
    SourceAlternate type=transport). The IP address must be in brackets as
    shown in the example below.
ac238d6a
 
9cbd0164
    Example 1.3. Setting the device IP address
4f879832
 modparam("osp","device_ip","[1.1.1.1]")
ac238d6a
 
779bb373
 3.4. device_port
9cbd0164
 
779bb373
    The device_port (string) parameter is an optional field which includes
    the SIP port being used by Kamailio in the peering request (as
    SourceAlternate type=network) to the peering server. If is not
    configured, this information is not included in the peering request.
    This field is useful if multiple Kamailio are running on the same Linux
    computer since it enables the peering server to administer different
    peering policies based on different SIP proxies. This parameter has not
989206bd
    been implemented yet.
9cbd0164
 
    Example 1.4. Setting the device port
 modparam("osp","device_port","5060")
 
779bb373
 3.5. token_format
ac238d6a
 
779bb373
    When Kamailio receives a SIP INVITE with a peering token, the OSP
    Module will validate the token to determine whether or not the call has
    been authorized by a peering server. Peering tokens may, or may not, be
    digitally signed. The token_format (integer) parameter defines if
    Kamailio will validate signed or unsigned tokens or both. The values
    for token format are defined below. The default value is 2.
ac238d6a
 
779bb373
    0 - Validate only signed tokens. Calls with valid signed tokens are
    allowed.
62689231
 
779bb373
    1 - Validate only unsigned tokens. Calls with valid unsigned tokens are
    allowed.
62689231
 
779bb373
    2 - Validate both signed and unsigned tokens are allowed. Calls with
    valid tokens are allowed.
62689231
 
9cbd0164
    Example 1.5. Setting the token format
4f879832
 modparam("osp","token_format",2)
62689231
 
779bb373
 3.6. private_key, local_certificate, ca_certificates
62689231
 
989206bd
    These parameters identify files are used for validating peering
779bb373
    authorization tokens and establishing a secure channel between Kamailio
    and a peering server using SSL. The files are generated using the
    'Enroll' utility from the OSP Toolkit. By default, the proxy will look
    for pkey.pem, localcert.pem, and cacart_0.pem in the default
    configuration directory. The default config directory is set at compile
    time using CFG_DIR and defaults to /usr/local/etc/kamailio/. The files
    may be copied to the expected file location or the parameters below may
    be changed.
62689231
 
9cbd0164
    Example 1.6. Set authorization files
62689231
 
779bb373
    If the default CFG_DIR value was used at compile time, the files will
    be loaded from:
9b64b9f3
 modparam("osp","private_key","/usr/local/etc/kamailio/pkey.pem")
779bb373
 modparam("osp","local_certificate","/usr/local/etc/kamailio/localcert.pem")
9b64b9f3
 modparam("osp","ca_certificates","/usr/local/etc/kamailio/cacert.pem")
62689231
 
779bb373
 3.7. enable_crypto_hardware_support
62689231
 
779bb373
    The enable_crypto_hardware_support (integer) parameter is used to set
    the cryptographic hardware acceleration engine in the openssl library.
    The default value is 0 (no crypto hardware is present). If crypto
    hardware is used, the value should be set to 1.
62689231
 
d77df08a
    Example 1.7. Setting the hardware support
4f879832
 modparam("osp","enable_crypto_hardware_support",0)
62689231
 
779bb373
 3.8. ssl_lifetime
62689231
 
779bb373
    The ssl_lifetime (integer) parameter defines the lifetime, in seconds,
    of a single SSL session key. Once this time limit is exceeded, the OSP
    Module will negotiate a new session key. Communication exchanges in
    progress will not be interrupted when this time limit expires. This is
    an optional field with default value is 200 seconds.
62689231
 
d77df08a
    Example 1.8. Setting the ssl lifetime
4f879832
 modparam("osp","ssl_lifetime",200)
62689231
 
779bb373
 3.9. persistence
62689231
 
779bb373
    The persistence (integer) parameter defines the time, in seconds, that
    an HTTP connection should be maintained after the completion of a
    communication exchange. The OSP Module will maintain the connection for
    this time period in anticipation of future communication exchanges to
    the same peering server.
6fb4bf09
 
d77df08a
    Example 1.9. Setting the persistence
4f879832
 modparam("osp","persistence",1000)
62689231
 
779bb373
 3.10. retry_delay
62689231
 
779bb373
    The retry_delay (integer) parameter defines the time, in seconds,
    between retrying connection attempts to an OSP peering server. After
    exhausting all peering servers the OSP Module will delay for this
    amount of time before resuming connection attempts. This is an optional
    field with default value is 1 second.
62689231
 
d77df08a
    Example 1.10. Setting the retry delay
4f879832
 modparam("osp","retry_delay",1)
62689231
 
779bb373
 3.11. retry_limit
62689231
 
779bb373
    The retry_limit (integer) parameter defines the maximum number of
    retries for connection attempts to a peering server. If no connection
    is established after this many retry attempts to all peering servers,
    the OSP Module will cease connection attempts and return appropriate
    error codes. This number does not count the initial connection attempt,
    so that a retry_limit of 1 will result in a total of two connection
    attempts to every peering server. The default value is 2.
62689231
 
d77df08a
    Example 1.11. Setting the retry limit
4f879832
 modparam("osp","retry_limit",2)
62689231
 
779bb373
 3.12. timeout
62689231
 
ac238d6a
    The timeout (integer) parameter defines the maximum time in
779bb373
    milliseconds, to wait for a response from a peering server. If no
    response is received within this time, the current connection is
    aborted and the OSP Module attempts to contact the next peering server.
    The default value is 10 seconds.
62689231
 
d77df08a
    Example 1.12. Setting the timeout
4f879832
 modparam("osp","timeout",10)
62689231
 
779bb373
 3.13. max_destinations
62689231
 
779bb373
    The max_destinations (integer) parameter defines the maximum number of
    destinations that Kamailio requests the peering server to return in a
    peering response. The default value is 5.
62689231
 
d77df08a
    Example 1.13. Setting the number of destination
4f879832
 modparam("osp","max_destinations",5)
62689231
 
779bb373
 3.14. validate_call_id
62689231
 
779bb373
    The validate_call_id (integer) parameter instructs the OSP module to
    validate call id in the peering token. If this value is set to 1, the
    OSP Module validates that the call id in the SIP INVITE message matches
    the call id in the peering token. If they do not match the INVITE is
    rejected. If this value is set to 0, the OSP Module will not validate
    the call id in the peering token. The default value is 1.
62689231
 
d77df08a
    Example 1.14. Instructing the module to validate call id
4f879832
 modparam("osp","validate_call_id",1)
 
779bb373
 3.15. use_rpid_for_calling_number
4f879832
 
779bb373
    The use_rpid_for_calling_number (integer) parameter instructs the OSP
    module to use the calling number in the Remote-Party-ID of the SIP
    INVITE message. If this value is set to 1, the OSP Module uses the
    calling number in the Reomte-Party-ID header of the INVITE message when
    a Remote-Party-ID exists. If this value is set to 0, the OSP Module
    will use the calling number in the From header of the INVITE message.
    The default value is 1.
4f879832
 
d77df08a
    Example 1.15. Instructing the module to use calling number in
4f879832
    Remote-Party-ID
 modparam("osp","use_rpid_calling_number",1)
ac238d6a
 
779bb373
 3.16. redirection_uri_format
9cbd0164
 
779bb373
    The redirection_uri_format (integer) parameter instructs the OSP module
    to use the different URI format in the SIP redirection message. If this
    value is set to 0, the OSP Module uses "xxxxxxxxxx@xxx.xxx.xxx.xxx" URI
    in the SIP redirection messages. If this value is set to 1, the OSP
    Module will use “<xxxxxxxxxx@xxx.xxx.xxx.xxx>” URI in the SIP
    redirection messages. The default value is 0
9cbd0164
 
    Example 1.16. Setting the redirection URI format
 modparam("osp","redirection_uri_format",1)
 
779bb373
 3.17. source_networkid_avp
9cbd0164
 
779bb373
    The source_networkid_avp (string) parameter instructs the OSP module to
    use the defined AVP to pass the source network ID value. The default
    value is "$avp(s:_osp_source_networkid_)". Then the source network ID
    can be set by "$avp(s:_osp_source_networkid_) = pseudo-variables". All
    pseudo variables are described in
9b64b9f3
    http://kamailio.org/dokuwiki/doku.php/pseudovariables:1.3.x.
9cbd0164
 
    Example 1.17. Setting the source network ID AVP
 modparam("osp","source_networkid_avp","$avp(s:snid)")
 
ba7961bb
 4. Functions
779bb373
 
    4.1. checkospheader()
    4.2. validateospheader()
    4.3. requestosprouting()
    4.4. checkosproute()
    4.5. prepareosproute()
    4.6. checkcallingtranslation()
    4.7. prepareallosproute()
    4.8. reportospusage()
ac238d6a
 
779bb373
 4.1. checkospheader()
ac238d6a
 
779bb373
    This function checks for the existence of the OSP-Auth-Token header
    field.
62689231
 
989206bd
    This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
4f879832
 
9cbd0164
    Example 1.18. checkospheader usage
ac238d6a
 ...
 if (checkospheader()) {
719e7b81
   log(1,"OSP header field found.\n");
ac238d6a
 } else {
719e7b81
   log(1,"no OSP header field present\n");
ac238d6a
 };
 ...
 
779bb373
 4.2. validateospheader()
ac238d6a
 
    This function validates an OSP-Token specified in the
779bb373
    OSP-Auth-Tokenheader field of the SIP message. If a peering token is
    present, it will be validated locally. If no OSP header is found or the
    header token is invalid or expired, -1 is returned; on successful
    validation 1 is returned.
ac238d6a
 
989206bd
    This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
4f879832
 
9cbd0164
    Example 1.19. validateospheader usage
ac238d6a
 ...
 if (validateospheader()) {
719e7b81
   log(1,"valid OSP header found\n");
ac238d6a
 } else {
719e7b81
   log(1,"OSP header not found, invalid or expired\n");
ac238d6a
 };
 ...
 
779bb373
 4.3. requestosprouting()
ac238d6a
 
779bb373
    This function launches a query to the peering server requesting the IP
    address of one or more destination peers serving the called party. If
    destination peers are available, the peering server will return the IP
    address and a peering authorization token for each destination peer.
    The OSP-Auth-Token Header field is inserted into the SIP message and
    the SIP uri is rewritten to the IP address of destination peer provided
    by the peering server.
ac238d6a
 
779bb373
    The address of the called party must be a valid E164 number, otherwise
    this function returns -1. If the transaction was accepted by the
    peering server, the uri is being rewritten and 1 returned, on errors
    (peering servers are not available, authentication failed or there is
    no route to destination or the route is blocked) -1 is returned.
ac238d6a
 
989206bd
    This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
4f879832
 
9cbd0164
    Example 1.20. requestosprouting usage
ac238d6a
 ...
 if (requestosprouting()) {
719e7b81
   log(1,"successfully queried OSP server, now relaying call\n");
ac238d6a
 } else {
719e7b81
   log(1,"Authorization request was rejected from OSP server\n");
ac238d6a
 };
 ...
 
779bb373
 4.4. checkosproute()
ac238d6a
 
779bb373
    This function is used to check if there is any route for the call.
ac238d6a
 
989206bd
    This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
4f879832
 
9cbd0164
    Example 1.21. checkosproute usage
ac238d6a
 ...
4f879832
 if (checkosproute()) {
719e7b81
   log(1,"There is at least one route for the call\n");
ac238d6a
 } else {
719e7b81
   log(1,"There is not any route for the call\n");
ac238d6a
 };
 ...
 
779bb373
 4.5. prepareosproute()
4f879832
 
779bb373
    This function tries to prepare the INVITE to be forwarded using the
    destination in the list returned by the peering server. If the calling
    number is translated, a RPID value for the RPID AVP will be set. If the
    route could not be prepared, the function returns 'FALSE' back to the
    script, which can then decide how to handle the failure. Note, if
    checkosproute has been called and returns 'TRUE' before calling
    prepareosproute, prepareosproute should not return 'FALSE' because
    checkosproute has confirmed that there is at least one route.
ac238d6a
 
4f879832
    This function can be used from BRANCH_ROUTE.
ac238d6a
 
9cbd0164
    Example 1.22. prepareosproute usage
ac238d6a
 ...
4f879832
 if (prepareosproute()) {
719e7b81
   log(1,"successfully prepared the route, now relaying call\n");
ac238d6a
 } else {
719e7b81
   log(1,"could not prepare the route, there is not route\n");
ac238d6a
 };
 ...
 
779bb373
 4.6. checkcallingtranslation()
4f879832
 
779bb373
    This function is used to check if the calling number is translated.
    Before calling checkcallingtranslation, prepareosproute should be
    called. If the calling number does been translated, the original
    Remote-Party-ID, if it exists, should be removed from the INVITE
    message. And a new Remote-Party-ID header should be added (a RPID value
    for the RPID AVP has been set by prepareosproute). If the calling
4f879832
    number is not translated, nothing should be done.
 
    This function can be used from BRANCH_ROUTE.
 
9cbd0164
    Example 1.23. checkcallingtranslation usage
4f879832
 ...
 if (checkcallingtranslation()) {
   # Remove the Remote_Party-ID from the received message
   # Otherwise it will be forwarded on to the next hop
   remove_hf("Remote-Party-ID");
 
   # Append a new Remote_Party
   append_rpid_hf();
 }
 ...
 
779bb373
 4.7. prepareallosproute()
ac238d6a
 
779bb373
    This function tries to prepare all the routes in the list returned by
    the peering server. The message is then either forked off or redirected
    to the destination. If unsuccessful in preparing the routes a SIP 500
    is sent back and a trace message is logged.
ac238d6a
 
989206bd
    This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
4f879832
 
9cbd0164
    Example 1.24. prepareallosproute usage
ac238d6a
 ...
4f879832
 if (prepareallosproute()) {
779bb373
   log(1,"Routes are prepared, now either forking or redirecting the call\n");
ac238d6a
 } else {
719e7b81
   log(1,"Could not prepare the routes. No destination available\n");
ac238d6a
 };
 ...
 
779bb373
 4.8. reportospusage()
ac238d6a
 
779bb373
    This function should be called after receiving a BYE message. If the
    message contains an OSP cookie, the function will forward originating
    and/or terminating duration usage information to a peering server. The
    function returns TRUE if the BYE includes an OSP cookie. The actual
    usage message will be send on a different thread and will not delay BYE
    processing. The function should be called before relaying the message.
ac238d6a
 
4f879832
    Meaning of the parameter is as follows:
      * "0" - Source device releases the call.
      * "1" - Destination device releases the call.
 
    This function can be used from REQUEST_ROUTE.
 
9cbd0164
    Example 1.25. reportospusage usage
ac238d6a
 ...
4f879832
 if (is_direction("downstream")) {
719e7b81
   log(1,"This BYE message is from SOURCE\n");
4f879832
   if (!reportospusage("0")) {
719e7b81
     log(1,"This BYE message does not include OSP usage information\n");
4f879832
   }
ac238d6a
 } else {
719e7b81
   log(1,"This BYE message is from DESTINATION\n");
4f879832
   if (!reportospusage("1")) {
719e7b81
     log(1,"This BYE message does not include OSP usage information\n");
4f879832
   }
 }
ac238d6a
 ...
 
9fc784c6
 Chapter 2. Developer Guide
ac238d6a
 
989206bd
    The functions of the OSP modules are not used by other Kamailio
    modules.