TransNexus and OSP Secures are trademarks of TransNexus, Inc.
TransNexus and OSP Secures are trademarks of TransNexus, Inc.
Revision History
Revision Date of Issue Description
1 26 Jul 2005 OSP Module User Guide for Asterisk V1.2
1.4 16 Jun 2006 OSP Module User Guide for Asterisk V1.4
1.6.0 13 Dec 2006 OSP Module User Guide for Asterisk V1.6
1.6.1 4 Jan 2007 Clarifying edits, add revision history, add general
purpose extensions.conf example
1.6.2 9 Feb 2007 Replace OSP Toolkit site from SIPfoundry with
SourceForge
1 Introduction
1 Introduction
This document provides instructions on how to build and configure Asterisk
This document provides instructions on how to build and configure Asterisk V1.6 with the OSP Toolkit to enable secure, multi-lateral peering. This document is also available in the Asterisk source package as doc/osp.txt. The OSP Toolkit is an open source implementation of the OSP peering protocol and is freely available from https://sourceforge.net/projects/osp-toolkit. The OSP standard defined by the European Telecommunications Standards Institute (ETSI TS 101 321) www.esti.org. If you have questions or need help, building Asterisk with the OSP Toolkit, please post your question on the OSP mailing list at https://lists.sourceforge.net/lists/listinfo/osp-toolkit-client.
V1.6 with the OSP Toolkit to enable secure, multi-lateral peering. This
document is also available in the Asterisk source package as doc/osp.txt.
The OSP Toolkit is an open source implementation of the OSP peering protocol
and is freely available from www.sipfoundry.org. The OSP standard defined by
the European Telecommunications Standards Institute (ETSI TS 101 321)
www.esti.org. If you have questions or need help, building Asterisk with the
OSP Toolkit, please post your question on the OSP mailing list at
https://list.sipfoundry.org/mailman/listinfo/osp.
2 OSP Toolkit
2 OSP Toolkit
Please reference the OSP Toolkit document "How to Build and Test the OSP
Please reference the OSP Toolkit document "How to Build and Test the OSP Toolkit” available from https://sourceforge.net/projects/osp-toolkit.
Toolkit" available from https://www.sipfoundry.org/OSPclient.
2.1 Build OSP Toolkit
2.1 Build OSP Toolkit
The software listed below is required to build and use the OSP Toolkit:
The software listed below is required to build and use the OSP Toolkit:
* OpenSSL (required for building) - Open Source SSL protocol and Cryptographic
* OpenSSL (required for building) - Open Source SSL protocol and Cryptographic Algorithms (version 0.9.7g recommended) from www.openssl.org. Pre-compiled OpenSSL binary packages are not recommended because of the binary compatibility issue.
Algorithms (version 0.9.7g recommended) from www.openssl.org. Pre-compiled
* Perl (required for building) - A programming language used by OpenSSL for compilation. Any version of Perl should work. One version of Perl is available from www.activestate.com/Products/ActivePer. If pre-compiled OpenSSL packages are used, Perl package is not required.
OpenSSL binary packages are not recommended because of the binary
* C compiler (required for building) - Any C compiler should work. The GNU Compiler Collection from www.gnu.org is routinely used for building the OSP Toolkit for testing.
compatibility issue.
* OSP Server (required for testing) - Access to any OSP server should work. An open source reference OSP server developed by Cisco System is available at http://www.vovida.org/applications/downloads/openosp/. RAMS, a java based open source OSP server is available at https://sourceforge.net/projects/rams. A free version of the TransNexus commercial OSP server may be downloaded from http://www.transnexus.com/OSP%20Toolkit/Peering_Server/VoIP_Peering_Server.htm.
* Perl (required for building) - A programming language used by OpenSSL for
compilation. Any version of Perl should work. One version of Perl is
available from www.activestate.com/Products/ActivePer. If pre-compiled
OpenSSL packages are used, Perl package is not required.
* C compiler (required for building) - Any C compiler should work. The GNU
Compiler Collection from www.gnu.org is routinely used for building the OSP
Toolkit for testing.
* OSP Server (required for testing) - Access to any OSP server should work.
Open source OSP servers are available from https://www.sipfoundry.org/OSP,
or go to http://www.transnexus.com/OSP%20Toolkit/Peering_Server/VoIP_Peering_Server.htm
to download a free commercial OSP server.
2.1.1 Unpacking the Toolkit
2.1.1 Unpacking the Toolkit
After downloading the OSP Toolkit (version 3.3.6 or later release) from
After downloading the OSP Toolkit (version 3.3.6 or later release) from www.sourceforge.net, perform the following steps in order:
www.sipfoundry.org, perform the following steps in order:
1) Copy the OSP Toolkit distribution into the directory where it will reside.
1) Copy the OSP Toolkit distribution into the directory where it will reside. The default directory for the OSP Toolkit is /usr/src.
The default directory for the OSP Toolkit is /usr/src.
2) Un-package the distribution file by executing the following command:
2) Un-package the distribution file by executing the following command:
gunzip -c OSPToolkit-###.tar.gz | tar xvf -
gunzip –c OSPToolkit-###.tar.gz | tar xvf –
Where ### is the version number separated by underlines. For example, if
Where ### is the version number separated by underlines. For example, if the version is 3.3.6, then the above command would be:
the version is 3.3.6, then the above command would be:
gunzip –c OSPToolkit-3_3_6.tar.gz | tar xvf –
gunzip -c OSPToolkit-3_3_6.tar.gz | tar xvf -
A new directory (TK-3_3_6-20060303) will be created within the same directory as the tar file.
A new directory (TK-3_3_6-20060303) will be created within the same
directory as the tar file.
3) Go to the TK-3_3_6-20060303 directory by running this command:
3) Go to the TK-3_3_6-20060303 directory by running this command:
cd TK-3_3_6-20060303
cd TK-3_3_6-20060303
Within this directory, you will find directories and files similar to what
Within this directory, you will find directories and files similar to what is listed below if the command "ls -F" is executed):
is listed below if the command "ls -F" is executed):
ls -F
ls -F
enroll/
enroll/
RelNotes.txt lib/
RelNotes.txt lib/
@ -89,82 +104,43 @@ TransNexus and OSP Secures are trademarks of TransNexus, Inc.
include/
include/
2.1.2 Preparing to build the OSP Toolkit
2.1.2 Preparing to build the OSP Toolkit
4) Compile OpenSSL according to the instructions provided with the OpenSSL
4) Compile OpenSSL according to the instructions provided with the OpenSSL distribution (You would need to do this only if you don’t have openssl already).
distribution (You would need to do this only if you don't have openssl
already).
5) Copy the OpenSSL header files (the *.h files) into the crypto/openssl directory within the osptoolkit directory. The OpenSSL header files are located under the openssl/include/openssl directory.
5) Copy the OpenSSL header files (the *.h files) into the crypto/openssl
directory within the osptoolkit directory. The OpenSSL header files are
6) Copy the OpenSSL library files (libcrypto.a and libssl.a) into the lib directory within the osptoolkit directory. The OpenSSL library files are located under the openssl directory.
located under the openssl/include/openssl directory.
Note: Since the Asterisk requires the OpenSSL package. If the OpenSSL package has been installed, steps 4 through 6 are not necessary.
6) Copy the OpenSSL library files (libcrypto.a and libssl.a) into the lib
directory within the osptoolkit directory. The OpenSSL library files are
7) Optionally, change the install directory of the OSP Toolkit. Open the Makefile in the /usr/src/TK-3_3_6-20060303/src directory, look for the install path variable – INSTALL_PATH, and edit it to be anywhere you want (defaults /usr/local).
located under the openssl directory.
Note: Please change the install path variable only if you are familiar with both the OSP Toolkit and the Asterisk.
Note: Since the Asterisk requires the OpenSSL package. If the OpenSSL
package has been installed, steps 4 through 6 are not necessary.
7) Optionally, change the install directory of the OSP Toolkit. Open the
Makefile in the /usr/src/TK-3_3_6-20060303/src directory, look for the
install path variable - INSTALL_PATH, and edit it to be anywhere you want
(defaults /usr/local).
Note: Please change the install path variable only if you are familiar
with both the OSP Toolkit and the Asterisk.
2.1.3 Building the OSP Toolkit
2.1.3 Building the OSP Toolkit
8) From within the OSP Toolkit directory (/usr/src/TK-3_3_6-20060303), start
8) From within the OSP Toolkit directory (/usr/src/TK-3_3_6-20060303), start the compilation script by executing the following commands:
the compilation script by executing the following commands:
cd src
cd src
make clean; make build
make clean; make build
2.1.4 Installing the OSP Toolkit
2.1.4 Installing the OSP Toolkit
The header files and the library of the OSP Toolkit should be installed.
The header files and the library of the OSP Toolkit should be installed. Otherwise, you must specify the OSP Toolkit path for the Asterisk.
Otherwise, you must specify the OSP Toolkit path for the Asterisk.
9) Use the make script to install the Toolkit.
9) Use the make script to install the Toolkit.
make install
make install
The make script is also used to install the OSP Toolkit header files and
The make script is also used to install the OSP Toolkit header files and the library into the INSTALL_PATH specified in the Makefile.
the library into the INSTALL_PATH specified in the Makefile.
Note: Please make sure you have the rights to access the INSTALL_PATH
directory. For example, in order to access /usr/local directory,
root privileges are required.
Note: Please make sure you have the rights to access the INSTALL_PATH directory. For example, in order to access /usr/local directory, root privileges are required.
2.1.5 Building the Enrollment Utility
2.1.5 Building the Enrollment Utility
Device enrollment is the process of establishing a trusted cryptographic
Device enrollment is the process of establishing a trusted cryptographic relationship between the VoIP device and the OSP Server. The Enroll program is a utility application for establishing a trusted relationship between an OSP client and an OSP server. Please see the document "Device Enrollment" at http://www.transnexus.com/OSP%20Toolkit/OSP%20Toolkit%20Documents/Device_Enrollment.pdf for more information about the enroll application.
relationship between the VoIP device and the OSP Server. The Enroll program is
a utility application for establishing a trusted relationship between an OSP
10) From within the OSP Toolkit directory (example: /usr/src/TK-3_3_6-20060303), execute the following commands at the command prompt:
client and an OSP server. Please see the document "Device Enrollment" at
https://www.sipfoundry.org/OSPclient for more information about the enroll
application.
10) From within the OSP Toolkit directory (example:
/usr/src/TK-3_3_6-20060303), execute the following commands at the command
prompt:
cd enroll
cd enroll
make clean; make linux
make clean; make linux
Compilation is successful if there are no errors in the compiler output.
Compilation is successful if there are no errors in the compiler output. The enroll program is now located in the OSP Toolkit/bin directory (example: /usr/src/ TK-3_3_6-20060303/bin).
The enroll program is now located in the OSP Toolkit/bin directory
(example: /usr/src/ TK-3_3_6-20060303/bin).
2.2 Obtain Crypto Files
2.2 Obtain Crypto Files
The OSP module in Asterisk requires three crypto files containing a local
The OSP module in Asterisk requires three crypto files containing a local certificate (localcert.pem), private key (pkey.pem), and CA certificate (cacert_0.pem). Asterisk will try to load the files from the Asterisk public/private key directory - /var/lib/asterisk/keys. If the files are not present, the OSP module will not start and the Asterisk will not support the OSP protocol. Use the enroll.sh script from the toolkit distribution to enroll Asterisk with an OSP server and obtain the crypto files. Documentation explaining how to use the enroll.sh script (Device Enrollment) to enroll with an OSP server is available at http://www.transnexus.com/OSP%20Toolkit/OSP%20Toolkit%20Documents/Device_Enrollment.pdf. Copy the files generated by the enrollment process to the Asterisk /var/lib/asterisk/keys directory.
certificate (localcert.pem), private key (pkey.pem), and CA certificate
(cacert_0.pem). Asterisk will try to load the files from the Asterisk
Note: The osptestserver.transnexus.com is configured only for sending and receiving non-SSL messages, and issuing signed tokens. If you need help, post a message on the OSP mailing list at https://lists.sourceforge.net/lists/listinfo/osp-toolkit-client..
public/private key directory - /var/lib/asterisk/keys. If the files are not
present, the OSP module will not start and the Asterisk will not support the
The enroll.sh script takes the domain name or IP addresses of the OSP servers that the OSP Toolkit needs to enroll with as arguments, and then generates pem files – cacert_#.pem, certreq.pem, localcert.pem, and pkey.pem. The ‘#’ in the cacert file name is used to differentiate the ca certificate file names for the various SP’s (OSP servers). If only one address is provided at the command line, cacert_0.pem will be generated. If 2 addresses are provided at the command line, 2 files will be generated – cacert_0.pem and cacert_1.pem, one for each SP (OSP server). The example below shows the usage when the client is registering with osptestserver.transnexus.com.
OSP protocol. Use the enroll.sh script from the toolkit distribution to
enroll Asterisk with an OSP server and obtain the crypto files. Documentation
explaining how to use the enroll.sh script (Device Enrollment) to enroll with
an OSP server is available at https://www.sipfoundry.org/OSPclient. Copy the
files generated by the enrollment process to the Asterisk
/var/lib/asterisk/keys directory.
Note: The osptestserver.transnexus.com is configured only for sending and
receiving non-SSL messages, and issuing signed tokens. If you need help,
post a message on the OSP mailing list of www.sipfoundry.org or send an
e-mail to support@transnexus.com.
The enroll.sh script takes the domain name or IP addresses of the OSP servers
that the OSP Toolkit needs to enroll with as arguments, and then generates pem
files - cacert_#.pem, certreq.pem, localcert.pem, and pkey.pem. The "#" in the
cacert file name is used to differentiate the ca certificate file names for
the various SP's (OSP servers). If only one address is provided at the command
line, cacert_0.pem will be generated. If 2 addresses are provided at the
command line, 2 files will be generated - cacert_0.pem and cacert_1.pem, one
for each SP (OSP server). The example below shows the usage when the client
is registering with osptestserver.transnexus.com.
./enroll.sh osptestserver.transnexus.com
./enroll.sh osptestserver.transnexus.com
Generating a 512 bit RSA private key
Generating a 512 bit RSA private key
........................++++++++++++
........................++++++++++++
@ -208,45 +184,25 @@ TransNexus and OSP Secures are trademarks of TransNexus, Inc.
The certificate request was successful.
The certificate request was successful.
Error Code returned from localcert command : 0
Error Code returned from localcert command : 0
The files generated should be copied to the /var/lib/asterisk/keys directory.
The files generated should be copied to the /var/lib/asterisk/keys directory.
Note: The script enroll.sh requires AT&T korn shell (ksh) or any of its
Note: The script enroll.sh requires AT&T korn shell (ksh) or any of its compatible variants. The /usr/src/TK-3_3_6-20060303/bin directory should be in the PATH variable. Otherwise, enroll.sh cannot find the enroll file.
compatible variants. The /usr/src/TK-3_3_6-20060303/bin directory should
be in the PATH variable. Otherwise, enroll.sh cannot find the enroll
file.
3 Asterisk
3 Asterisk
In Asterisk, all OSP support is implemented as dial plan functions. In
In Asterisk, all OSP support is implemented as dial plan functions. In Asterisk V1.6, all combinations of routing between OSP and non-OSP enabled networks using any combination of SIP, H.323 and IAX protocols are fully supported. Section
Asterisk V1.6, all combinations of routing between OSP and non-OSP enabled
3.1 describes the three easy steps to add OSP support to Asterisk:
networks using any combination of SIP, H.323 and IAX protocols are fully
supported. Section 3.1 describes the three easy steps to add OSP support to
Asterisk:
1. Build Asterisk with OSP Toolkit
1. Build Asterisk with OSP Toolkit
2. Configure osp.conf file
2. Configure osp.conf file
3. Cut and paste to extensions.conf
3. Cut and paste to extensions.conf
Sections 3.2 and 3.3 provide a detailed explanation of OSP dial plan functions
Sections 3.2 and 3.3 provide a detailed explanation of OSP dial plan functions and configuration examples. The detailed information provided in Sections 3.2 and 3.3 is not required for operating Asterisk with OSP, but may be helpful to developers who want to customize their Asterisk OSP implementation.
and configuration examples. The detailed information provided in Sections 3.2
and 3.3 is not required for operating Asterisk with OSP, but may be helpful to
developers who want to customize their Asterisk OSP implementation.
3.1 Configure for OSP Support
3.1 Configure for OSP Support
3.1.1 Build Asterisk with OSP Toolkit
3.1.1 Build Asterisk with OSP Toolkit
The first step is to build Asterisk with the OSP Toolkit. If the OSP Toolkit
The first step is to build Asterisk with the OSP Toolkit. If the OSP Toolkit is installed in the default install directory, /usr/local, no additional configuration is required. Compile Asterisk according to the instructions provided with the Asterisk distribution.
is installed in the default install directory, /usr/local, no additional
If the OSP Toolkit is installed in another directory, such as /myosp, Asterisk must be configured with the location of the OSP Toolkit. See the example below.
configuration is required. Compile Asterisk according to the instructions
provided with the Asterisk distribution.
If the OSP Toolkit is installed in another directory, such as /myosp, Asterisk
must be configured with the location of the OSP Toolkit. See the example
below.
--with-osptk=/myosp
--with-osptk=/myosp
Note: Please change the install path only if you familiar with both the OSP
Note: Please change the install path only if you familiar with both the OSP Toolkit and the Asterisk. Otherwise, the change may result in Asterisk not supporting the OSP protocol.
Toolkit and the Asterisk. Otherwise, the change may result in Asterisk
not supporting the OSP protocol.
3.1.2 osp.conf
3.1.2 osp.conf
The /etc/asterisk/osp.conf file, shown below, contains configuration
The /etc/asterisk/osp.conf file, shown below, contains configuration parameters for using OSP. Two parameters, servicepoint and source must be configured. The default values for all other parameters will work well for standard OSP implementations.
parameters for using OSP. Two parameters, servicepoint and source must be
configured. The default values for all other parameters will work well for
standard OSP implementations.
;
;
; Open Settlement Protocol Sample Configuration File
; Open Settlement Protocol Sample Configuration File
;
;
@ -332,9 +288,9 @@ TransNexus and OSP Secures are trademarks of TransNexus, Inc.
;
;
; Set the authentication policy.
; Set the authentication policy.
; 0 - NO - Accept all calls.
; 0 - NO - Accept all calls.
; 1 - YES - Accept calls with valid token or no token.
; 1 – YES - Accept calls with valid token or no token.
; Block calls with invalid token.
; Block calls with invalid token.
; 2 - EXCLUSIVE - Accept calls with valid token.
; 2 – EXCLUSIVE – Accept calls with valid token.
; Block calls with invalid token or no token.
; Block calls with invalid token or no token.
; Default is 1,
; Default is 1,
;
;
@ -346,11 +302,7 @@ TransNexus and OSP Secures are trademarks of TransNexus, Inc.
defaultprotocol=SIP
defaultprotocol=SIP
3.1.3 extensions.conf
3.1.3 extensions.conf
OSP functions are implemented as dial plan functions in the extensions.conf
OSP functions are implemented as dial plan functions in the extensions.conf file. To add OSP support to your Asterisk server, simply copy and paste the text box below to your extensions.conf file. These functions will enable your Asterisk server to support all OSP call scenarios. Configuration of your Asterisk server for OSP is now complete.
file. To add OSP support to your Asterisk server, simply copy and paste the
text box below to your extensions.conf file. These functions will enable your
Asterisk server to support all OSP call scenarios. Configuration of your
Asterisk server for OSP is now complete.
[globals]
[globals]
DIALOUT=Zap/1
DIALOUT=Zap/1
@ -500,7 +452,6 @@ TransNexus and OSP Secures are trademarks of TransNexus, Inc.
3.2 OSP Dial Plan Functions
3.2 OSP Dial Plan Functions
This section provides a description of each OSP dial plan function.
This section provides a description of each OSP dial plan function.
3.2.1 OSPAuth
3.2.1 OSPAuth
OSP token validation function.
OSP token validation function.
Input:
Input:
@ -573,17 +524,9 @@ TransNexus and OSP Secures are trademarks of TransNexus, Inc.
The extensions.conf file example provided in Section 3.1 is designed to
The extensions.conf file example provided in Section 3.1 is designed to handle all OSP call scenarios when Asterisk is used as a source or destination gateway to the PSTN or as a proxy between VoIP networks. The extenstion.conf examples in this section are designed for specific use cases only.
handle all OSP call scenarios when Asterisk is used as a source or destination
gateway to the PSTN or as a proxy between VoIP networks. The extenstion.conf
examples in this section are designed for specific use cases only.
3.3.1 Source Gateway
3.3.1 Source Gateway
The examples in this section apply when the Asterisk server is being used as
The examples in this section apply when the Asterisk server is being used as a TDM to VoIP gateway. Calls originate on the TDM network and are converted to VoIP by Asterisk. In these cases, the Asterisk server queries an OSP server to find a route to a VoIP destination. When the call ends, Asterisk sends a CDR to the OSP server.
a TDM to VoIP gateway. Calls originate on the TDM network and are converted
to VoIP by Asterisk. In these cases, the Asterisk server queries an OSP
server to find a route to a VoIP destination. When the call ends, Asterisk
sends a CDR to the OSP server.
For SIP protocol.
For SIP protocol.
[SIPSrcGW]
[SIPSrcGW]
exten => _XXXX.,1,NoOp(SIPSrcGW)
exten => _XXXX.,1,NoOp(SIPSrcGW)
@ -632,7 +575,7 @@ TransNexus and OSP Secures are trademarks of TransNexus, Inc.
; OSP lookup using default provider, if fail/error jump to lookup+101
; OSP lookup using default provider, if fail/error jump to lookup+101
; "h" parameter is used to generate a call id
; “h” parameter is used to generate a call id
; Cisco OSP gateways use this call id to validate OSP token
; Cisco OSP gateways use this call id to validate OSP token
exten => _XXXX.,n(lookup),OSPLookup(${EXTEN}||jh)
exten => _XXXX.,n(lookup),OSPLookup(${EXTEN}||jh)
; Set outbound call id
; Set outbound call id
@ -654,10 +597,7 @@ TransNexus and OSP Secures are trademarks of TransNexus, Inc.
exten => h,n,OSPFinish(${HANGUPCAUSE})
exten => h,n,OSPFinish(${HANGUPCAUSE})
3.3.2 Destination Gateway
3.3.2 Destination Gateway
The examples in this section apply when Asterisk is being used as a VoIP to
The examples in this section apply when Asterisk is being used as a VoIP to TDM gateway. VoIP calls are received by Asterisk which validates the OSP peering token and completes to the TDM network. After the call ends, Asterisk sends a CDR to the OSP server.
TDM gateway. VoIP calls are received by Asterisk which validates the OSP
peering token and completes to the TDM network. After the call ends,
Asterisk sends a CDR to the OSP server.
For SIP protocol
For SIP protocol
[SIPDstGW]
[SIPDstGW]
exten => _XXXX.,1,NoOp(SIPDstGW)
exten => _XXXX.,1,NoOp(SIPDstGW)
@ -749,7 +689,7 @@ TransNexus and OSP Secures are trademarks of TransNexus, Inc.
; Validate token using default provider, if fail/error jump to auth+101
; Validate token using default provider, if fail/error jump to auth+101
exten => _XXXX.,n(auth),OSPAuth(|j)
exten => _XXXX.,n(auth),OSPAuth(|j)
; OSP lookup using default provider, if fail/error jump to lookup+101
; OSP lookup using default provider, if fail/error jump to lookup+101
; "h" parameter is used to generate a call id for H.323 destinations
; “h” parameter is used to generate a call id for H.323 destinations
; Cisco OSP gateways use this call id to validate OSP token
; Cisco OSP gateways use this call id to validate OSP token
exten => _XXXX.,n(lookup),OSPLookup(${EXTEN}||jh)
exten => _XXXX.,n(lookup),OSPLookup(${EXTEN}||jh)
; Set outbound call id and OSP token
; Set outbound call id and OSP token
@ -802,3 +742,6 @@ TransNexus and OSP Secures are trademarks of TransNexus, Inc.
TransNexus OSP Development
19 years ago