mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
589 lines
20 KiB
589 lines
20 KiB
OSP Module for Secure, Multi-Lateral Peering
|
|
|
|
Ulrich Abend
|
|
|
|
FhG FOKUS
|
|
|
|
<ullstar@iptel.org>
|
|
|
|
Edited by
|
|
|
|
Di-Shi Sun
|
|
|
|
TransNexus, Inc.
|
|
|
|
<support@transnexus.com>
|
|
|
|
Copyright © 2003 FhG FOKUS
|
|
__________________________________________________________________
|
|
|
|
Table of Contents
|
|
|
|
1. User's Guide
|
|
|
|
1. Overview
|
|
2. Dependencies
|
|
3. Exported Parameters
|
|
|
|
3.1. sp1_uri, sp2_uri, ..., sp16_uri
|
|
3.2. device_ip
|
|
3.3. token_format
|
|
3.4. private_key, local_certificate, ca_certificates
|
|
3.5. sp1_weight, sp2_weight, ..., sp16_weight
|
|
3.6. device_port
|
|
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
|
|
|
|
4. Exported Functions
|
|
|
|
4.1. checkospheader()
|
|
4.2. validateospheader()
|
|
4.3. requestosprouting()
|
|
4.4. prepareospfirstroute()
|
|
4.5. prepareosprnextoute()
|
|
4.6. appendospheaders()
|
|
4.7. prepareallosproute()
|
|
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. prepareospfirstroute usage
|
|
1.20. prepareospnextroute usage
|
|
1.21. appendospheaders usage
|
|
1.22. prepareallosproute usage
|
|
1.23. reportospusage usage
|
|
|
|
Chapter 1. User's Guide
|
|
|
|
Table of Contents
|
|
|
|
1. Overview
|
|
2. Dependencies
|
|
3. Exported Parameters
|
|
|
|
3.1. sp1_uri, sp2_uri, ..., sp16_uri
|
|
3.2. device_ip
|
|
3.3. token_format
|
|
3.4. private_key, local_certificate, ca_certificates
|
|
3.5. sp1_weight, sp2_weight, ..., sp16_weight
|
|
3.6. device_port
|
|
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
|
|
|
|
4. Exported Functions
|
|
|
|
4.1. checkospheader()
|
|
4.2. validateospheader()
|
|
4.3. requestosprouting()
|
|
4.4. prepareospfirstroute()
|
|
4.5. prepareosprnextoute()
|
|
4.6. appendospheaders()
|
|
4.7. prepareallosproute()
|
|
4.8. reportospusage()
|
|
|
|
1. Overview
|
|
|
|
The OSP module enables SER to support secure, multi-lateral peering
|
|
using the OSP standard defined by ETSI (TS 101 321 V4.1.1). This module
|
|
will enable your SER 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.
|
|
|
|
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
|
|
* avpops -- AVP operation
|
|
* OSP Toolkit -- The OSP Toolkit, available from
|
|
http://sourceforge.net/projects/osp-toolkit, must be built before
|
|
building SER with the OSP Module. For instructions on building SER
|
|
with the OSP Toolkit, see
|
|
http://www.transnexus.com/White%20Papers/Multi-Lateral_Peering_with
|
|
_SER_V2.0.x.pdf
|
|
|
|
3. Exported Parameters
|
|
|
|
3.1. sp1_uri, sp2_uri, ..., sp16_uri
|
|
3.2. device_ip
|
|
3.3. token_format
|
|
3.4. private_key, local_certificate, ca_certificates
|
|
3.5. sp1_weight, sp2_weight, ..., sp16_weight
|
|
3.6. device_port
|
|
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.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 SER
|
|
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 SER 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")
|
|
|
|
3.2. device_ip
|
|
|
|
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.
|
|
|
|
Example 1.2. Setting the device IP address
|
|
modparam("osp","device_ip","[1.1.1.1]")
|
|
|
|
3.3. token_format
|
|
|
|
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.
|
|
|
|
Example 1.3. Setting the token format
|
|
modparam("osp","token_format",2)
|
|
|
|
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 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.
|
|
|
|
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/ser/pkey.pem")
|
|
modparam("osp","local_certificate","/usr/local/etc/ser/localcert.pem")
|
|
modparam("osp","ca_certificates","/usr/local/etc/ser/cacert.pem")
|
|
|
|
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)
|
|
|
|
3.6. device_port
|
|
|
|
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.
|
|
|
|
Example 1.6. Setting the device port
|
|
modparam("osp","device_port","5060")
|
|
|
|
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)
|
|
|
|
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)
|
|
|
|
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)
|
|
|
|
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)
|
|
|
|
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)
|
|
|
|
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)
|
|
|
|
3.13. max_destinations
|
|
|
|
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.
|
|
|
|
Example 1.13. Setting the number of destination
|
|
modparam("osp","max_destinations",5)
|
|
|
|
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)
|
|
|
|
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)
|
|
|
|
4. Exported Functions
|
|
|
|
4.1. checkospheader()
|
|
4.2. validateospheader()
|
|
4.3. requestosprouting()
|
|
4.4. prepareospfirstroute()
|
|
4.5. prepareosprnextoute()
|
|
4.6. appendospheaders()
|
|
4.7. prepareallosproute()
|
|
4.8. reportospusage()
|
|
|
|
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");
|
|
};
|
|
...
|
|
|
|
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");
|
|
};
|
|
...
|
|
|
|
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");
|
|
};
|
|
...
|
|
|
|
4.4. prepareospfirstroute()
|
|
|
|
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.
|
|
|
|
Example 1.19. prepareospfirstroute usage
|
|
...
|
|
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");
|
|
};
|
|
...
|
|
|
|
4.5. prepareosprnextoute()
|
|
|
|
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.
|
|
|
|
Example 1.20. prepareospnextroute usage
|
|
...
|
|
if (prepareospnextroute ()) {
|
|
log("successfully prepared the next route, now relaying call\n");
|
|
} else {
|
|
log("could not prepare the route. No next destination available\n");
|
|
};
|
|
...
|
|
|
|
4.6. appendospheaders()
|
|
|
|
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.
|
|
|
|
Example 1.21. appendospheaders usage
|
|
...
|
|
branch_route[1] {
|
|
log("Prepare route specific OSP information\n");
|
|
appendospheaders();
|
|
}
|
|
...
|
|
|
|
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");
|
|
};
|
|
...
|
|
|
|
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.
|
|
|
|
This function can be used from REQUEST_ROUTE.
|
|
|
|
Example 1.23. reportospusage usage
|
|
...
|
|
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 b
|
|
y an OSP server\n");
|
|
};
|
|
...
|
|
|
|
Chapter 2. Developer's Guide
|
|
|
|
The functions of the OSP modules are not used by other SER 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.iptel.org/views/moduledocs/ or post a message on
|
|
the SER 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-ser.cfg in modules/osp/etc for examples
|