OSP Module for Secure, Multi-Lateral Peering

Ulrich Abend

   FhG FOKUS

   <ullstar@iptel.org>

Edited by

Di-Shi Sun

   Copyright  2003 FhG FOKUS
     __________________________________________________________

   Table of Contents
   1. User's Guide

        1.1. Overview
        1.2. Dependencies
        1.3. Exported Parameters

              1.3.1. sp1_uri, sp2_uri, ..., sp16_uri
              1.3.2. device_ip
              1.3.3. token_format
              1.3.4. private_key, local_certificate,
                      ca_certificates

              1.3.5. sp1_weight, sp2_weight, ..., sp16_weight
              1.3.6. device_port
              1.3.7. enable_crypto_hardware_support
              1.3.8. ssl_lifetime
              1.3.9. persistence
              1.3.10. retry_delay
              1.3.11. retry_limit
              1.3.12. timeout
              1.3.13. max_destinations
              1.3.14. validate_call_id
              1.3.15. use_rpid_for_calling_number

        1.4. Exported Functions

              1.4.1. checkospheader()
              1.4.2. validateospheader()
              1.4.3. requestosprouting()
              1.4.4. checkosproute()
              1.4.5. prepareosproute()
              1.4.6. checkcallingtranslation()
              1.4.7. prepareallosproute()
              1.4.8. reportospusage()

   2. Developer's Guide
   3. Frequently Asked Questions

   List of Examples
   1-1. Setting the OSP servers
   1-2. Setting the device IP address
   1-3. Setting the token format
   1-4. Set authorization files
   1-5. Setting the OSP server weights
   1-6. Setting the device port
   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
   1-15. Instructing the module to use calling number in
          Remote-Party-ID

   1-16. checkospheader usage
   1-17. validateospheader usage
   1-18. requestosprouting usage
   1-19. checkosproute usage
   1-20. prepareosproute usage
   1-21. checkcallingtranslation usage
   1-22. prepareallosproute usage
   1-23. reportospusage usage
     __________________________________________________________

Chapter 1. User's Guide

1.1. Overview

   The OSP module enables OpenSER to support secure, multi-lateral
   peering using the OSP standard defined by ETSI (TS 101 321
   V4.1.1). This module will enable your OpenSER to:

     * Send a peering authorization request to a peering server.
     * Validate a digitally signed peering authorization token
       received in a SIP INVITE message.
     * Report usage information to a peering server.
     __________________________________________________________

1.2. Dependencies

   The OSP module depends on the following modules which must be
   loaded before the OSP module.

     * sl -- stateless replier
     * tm -- stateful processing
     * rr -- Record-Route/Route operation
     * textops -- text based operation
     * auth -- Remote-Party-ID operattion
     * OSP Toolkit -- The OSP Toolkit, available from
       http://sourceforge.net/projects/osp-toolkit, must be built
       before building OpenSER with the OSP Module. For
       instructions on building OpenSER with the OSP Toolkit, see
       http://www.transnexus.com/White%20Papers/Multi-Lateral_Peer
       ing_with_OpenSER_V1.1.1pdf
     __________________________________________________________

1.3. Exported Parameters

1.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 OpenSER 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 OpenSER
       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.

   Example 1-1. Setting the OSP servers
modparam("osp","sp1_uri","http://osptestserver.transnexus.com:1080/osp")
modparam("osp","sp2_uri","https://[1.2.3.4]:1443/osp")
     __________________________________________________________

1.3.2. device_ip

   The device_ip (string) is a recommended parameter that
   explicitly defines the IP address of OpenSER in a peering
   request message (as SourceAlternate type=transport). The IP
   address must be in brackets as shown in the example below.

   Example 1-2. Setting the device IP address
modparam("osp","device_ip","[1.1.1.1]")
     __________________________________________________________

1.3.3. token_format

   When OpenSER 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 OpenSER will validate signed or
   unsigned tokens or both. The values for token format are
   defined below. The default value is 2.

   0 - Validate only signed tokens. Calls with valid signed tokens
   are allowed.

   1 - Validate only unsigned tokens. Calls with valid unsigned
   tokens are allowed.

   2 - Validate both signed and unsigned tokens are allowed. Calls
   with valid tokens are allowed.

   Example 1-3. Setting the token format
modparam("osp","token_format",2)
     __________________________________________________________

1.3.4. private_key, local_certificate, ca_certificates

   These parameters identify files are used for validating peering
   authorization tokens and establishing a secure channel between
   OpenSER 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/openser/. The files may be
   copied to the expected file location or the parameters below
   may be changed.

   Example 1-4. Set authorization files

   If the default CFG_DIR value was used at compile time, the
   files will be loaded from:
modparam("osp","private_key","/usr/local/etc/openser/pkey.pem")
modparam("osp","local_certificate","/usr/local/etc/openser/localcert.pem
")
modparam("osp","ca_certificates","/usr/local/etc/openser/cacert.pem")
     __________________________________________________________

1.3.5. sp1_weight, sp2_weight, ..., sp16_weight

   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.

   Example 1-5. Setting the OSP server weights
modparam("osp","sp1_weight",1000)
     __________________________________________________________

1.3.6. device_port

   The device_port (string) parameter is an optional field which
   includes the SIP port being used by OpenSER 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
   OpenSERs 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
   been implemented yet.

   Example 1-6. Setting the device port
modparam("osp","device_port","5060")
     __________________________________________________________

1.3.7. enable_crypto_hardware_support

   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.

   Example 1-7. Setting the hardware support
modparam("osp","enable_crypto_hardware_support",0)
     __________________________________________________________

1.3.8. ssl_lifetime

   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.

   Example 1-8. Setting the ssl lifetime
modparam("osp","ssl_lifetime",200)
     __________________________________________________________

1.3.9. persistence

   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.

   Example 1-9. Setting the persistence
modparam("osp","persistence",1000)
     __________________________________________________________

1.3.10. retry_delay

   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.

   Example 1-10. Setting the retry delay
modparam("osp","retry_delay",1)
     __________________________________________________________

1.3.11. retry_limit

   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.

   Example 1-11. Setting the retry limit
modparam("osp","retry_limit",2)
     __________________________________________________________

1.3.12. timeout

   The timeout (integer) parameter defines the maximum time in
   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.

   Example 1-12. Setting the timeout
modparam("osp","timeout",10)
     __________________________________________________________

1.3.13. max_destinations

   The max_destinations (integer) parameter defines the maximum
   number of destinations that OpenSER requests the peering server
   to return in a peering response. The default value is 5.

   Example 1-13. Setting the number of destination
modparam("osp","max_destinations",5)
     __________________________________________________________

1.3.14. validate_call_id

   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.

   Example 1-14. Instructing the module to validate call id
modparam("osp","validate_call_id",1)
     __________________________________________________________

1.3.15. use_rpid_for_calling_number

   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.

   Example 1-15. Instructing the module to use calling number in
   Remote-Party-ID
modparam("osp","use_rpid_calling_number",1)
     __________________________________________________________

1.4. Exported Functions

1.4.1. checkospheader()

   This function checks for the existence of the OSP-Auth-Token
   header field.

   This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.

   Example 1-16. checkospheader usage
...
if (checkospheader()) {
  log(1,"OSP header field found.\n");
} else {
  log(1,"no OSP header field present\n");
};
...
     __________________________________________________________

1.4.2. validateospheader()

   This function validates an OSP-Token specified in the
   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.

   This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.

   Example 1-17. validateospheader usage
...
if (validateospheader()) {
  log(1,"valid OSP header found\n");
} else {
  log(1,"OSP header not found, invalid or expired\n");
};
...
     __________________________________________________________

1.4.3. requestosprouting()

   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.

   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.

   This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.

   Example 1-18. requestosprouting usage
...
if (requestosprouting()) {
  log(1,"successfully queried OSP server, now relaying call\n");
} else {
  log(1,"Authorization request was rejected from OSP server\n");
};
...
     __________________________________________________________

1.4.4. checkosproute()

   This function is used to check if there is any route for the
   call.

   This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.

   Example 1-19. checkosproute usage
...
if (checkosproute()) {
  log(1,"There is at least one route for the call\n");
} else {
  log(1,"There is not any route for the call\n");
};
...
     __________________________________________________________

1.4.5. prepareosproute()

   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.

   This function can be used from BRANCH_ROUTE.

   Example 1-20. prepareosproute usage
...
if (prepareosproute()) {
  log(1,"successfully prepared the route, now relaying call\n");
} else {
  log(1,"could not prepare the route, there is not route\n");
};
...
     __________________________________________________________

1.4.6. checkcallingtranslation()

   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
   number is not translated, nothing should be done.

   This function can be used from BRANCH_ROUTE.

   Example 1-21. checkcallingtranslation usage
...
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();
}
...
     __________________________________________________________

1.4.7. prepareallosproute()

   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.

   This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.

   Example 1-22. prepareallosproute usage
...
if (prepareallosproute()) {
  log(1,"Routes are prepared, now either forking or redirecting the call
\n");
} else {
  log(1,"Could not prepare the routes. No destination available\n");
};
...
     __________________________________________________________

1.4.8. reportospusage()

   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.

   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.

   Example 1-23. reportospusage usage
...
if (is_direction("downstream")) {
  log(1,"This BYE message is from SOURCE\n");
  if (!reportospusage("0")) {
    log(1,"This BYE message does not include OSP usage information\n");
  }
} else {
  log(1,"This BYE message is from DESTINATION\n");
  if (!reportospusage("1")) {
    log(1,"This BYE message does not include OSP usage information\n");
  }
}
...
     __________________________________________________________

Chapter 2. Developer's Guide

   The functions of the OSP modules are not used by other OpenSER
   modules.
     __________________________________________________________

Chapter 3. Frequently Asked Questions

   3.1. What platforms does this module work on?
   3.2. Where can I get more information on this module?
   3.3. Where can I get more information on OSP?
   3.4. How do I obtain an OSP server for testing?
   3.5. How are the exported functions used by the OSP module?

   3.1. What platforms does this module work on?

   The module has been implemented using Linux, the underlying
   toolkit and the module code itself should compile and work on
   Solaris, *BSD, and probably most other unix platforms with ssl
   and pthreads available, but the OSP Module has only been tested
   Linux.

   3.2. Where can I get more information on this module?

   Please see http://www.openser.org/docs/modules/ or post a
   message on the OpenSER mailing list.

   3.3. Where can I get more information on OSP?

   The OSP technical specification (ETSI TS 101 321) may be
   obtained from www.etsi.org. You can also post a message on the
   OSP Toolkit mailing list at
   https://lists.sourceforge.net/lists/listinfo/osp-toolkit-client
   .

   3.4. How do I obtain an OSP server for testing?

   OSP peering servers are available from the following sources:

     * OpenOSP is an OSP server reference implementation created
       by Cisco Systems and available at
       http://www.vovida.org/applications/downloads/openosp/
     * RAMS is an open source, java based OSP server project
       available from http://sourceforge.net/projects/rams/
     * A free version of the commercial TransNexus OSP peering
       server is available at www.transnexus.com.

   3.5. How are the exported functions used by the OSP module?

   See sample-osp-openser.cfg in modules/osp/etc for examples.
