OSP Module for Secure, Multi-Lateral Peering

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:

modparam("osp","sp1_uri","http://osptestserver.transnexus.com:1080/osp")
modparam("osp","sp2_uri","https://[1.2.3.4]:1443/osp")

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

modparam("osp","device_ip","[1.1.1.1]")

When SER 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 SER 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.

modparam("osp","token_format",2)

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

modparam("osp","private_key","/usr/local/etc/ser/pkey.pem")
modparam("osp","local_certificate","/usr/local/etc/ser/localcert.pem")
modparam("osp","ca_certificates","/usr/local/etc/ser/cacert.pem")

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.

modparam("osp","sp1_weight",1000)

The device_port (string) parameter is an optional field which includes the SIP port being used by SER 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 SERs 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.

modparam("osp","device_port","5060")

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.

modparam("osp","enable_crypto_hardware_support",0)

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.

modparam("osp","ssl_lifetime",200)

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.

modparam("osp","persistence",1000)

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.

modparam("osp","retry_delay",1)

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.

modparam("osp","retry_limit",2)

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.

modparam("osp","timeout",10)

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

modparam("osp","max_destinations",5)

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.

modparam("osp","validate_call_id",1)

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.

modparam("osp","use_rpid_calling_number",1)

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

This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.

...
if (checkospheader()) {
  log("OSP header field found.\n");
} else {
  log("no OSP header field present\n");
};
...

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.

...
if (validateospheader()) {
  log("valid OSP header found\n");
} else {
  log("OSP header not found, invalid or expired\n");
};
...

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.

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

This function tries to prepare the INVITE to be forwarded or redirected using the first destination in the list returned by the peering server. If the route could not be prepared, the function returns 'FALSE' back to the script, which can then decide how to handle the failure.

This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.

...
if (prepareospfirstroute ()) {
  log("successfully prepared the first route, now relaying call\n");
} else {
  log("could not prepare the route. The first destination was blocked\n");
};
...

Once the call could not be completed through the first destination, this function tries to prepare the INVITE message using the next destination in the list returned by the peering Server. If it succeeds in preparing the route, the message is either redirected or relayed on (using the t_relay call), or else the function returns 'FALSE' back to the script, which can then decide how to handle the failure.

This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.

...
if (prepareospnextroute ()) {
  log("successfully prepared the next route, now relaying call\n");
} else {
  log("could not prepare the route. No next destination available\n");
};
...

This function is used to append route specific OSP headers. Before calling appendospheaders, prepareospfirst/nextroute should be called.

This function can be used from BRANCH_ROUTE.

...
branch_route[1] {
  log("Prepare route specific OSP information\n");
  appendospheaders();
}
...

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.

...
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");
};
...

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.

This function can be used from REQUEST_ROUTE.

...
if (reportospusage ()) {
  log("OSP call duration usage will be reported\n");
} else {
  log("The BYE message does not include OSP information, it was not authorized by an OSP server\n");
};
...