
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
              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
              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
       www.sipfoundry.org/OSP, must be built before building
       OpenSER with the OSP Module. See the document "Secure,
       Multi-lateral Peering with OpenSER", located at
       http://www.openser.org/docs/osp/Multi-Lateral_VoIP_Peering
       _with_OpenSER_V1.1.pdf for build instructions.
     _________________________________________________________

1.3. Exported Parameters

1.3.1. sp1_uri, sp2_uri

   These string parameters define peering servers to be used for
   requesting peering authorization and routing information.
   sp1_uri must be configured. sp2_uri is required only if there
   are two 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

   device_ip (string) is a recommended parameter that explicitly
   defines the IP address of OpenSER in an 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.pe
m")
modparam("osp","ca_certificates","/usr/local/etc/openser/cacert.pem")

     _________________________________________________________

1.3.5. sp1_weight, sp2_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.

   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 an 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 an 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("OSP header field found.\n");
} else {
  log("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("valid OSP header found\n");
} else {
  log("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("successfully queried OSP server, now relaying call\n");
} else {
  log("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("There is at least one route for the call\n");
} else {
  log("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("successfully prepared the route, now relaying call\n");
} else {
  log("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("Routes are prepared, now either forking or redirecting the call\
n");
} else {
  log("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,"-----------------ROUTE: This BYE message is from SOURCE\n");
  if (!reportospusage("0")) {
    log(1,"-----------------ROUTE: This BYE message does not include OS
P usage information\n");
  }
} else {
  log(1,"-----------------ROUTE: This BYE message is from DESTINATION\n
");
  if (!reportospusage("1")) {
    log(1,"-----------------ROUTE: This BYE message does not include OS
P 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 the document "Secure, Multi-lateral Peering with
   OpenSER", located at
   http://www.openser.org/docs/osp/Multi-Lateral_VoIP_Peering_wit
   h_OpenSER_V1.1.pdf or post a message on the OpenSER mailing
   list. You may also send an e-mail to support@transnexus.com.

   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. Additional documentation on OSP is
   available from www.sipfoundry.org.

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

   OSP peering servers are available from the following sources:

     * OpenOSP server from www.sipfoundry.org is a complete OSP
       server
     * RAMS from www.sipfoundry.org is a new java based open
       source OSP
     * TransNexus provides free access to a hosted OSP peering
       server on the Internet for testing. Contact
       support@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
