From 109737eb1c3af44506f4a98a7e645b38841ce6a2 Mon Sep 17 00:00:00 2001 From: Matt O'Gorman Date: Fri, 30 Jun 2006 15:12:35 +0000 Subject: Updates from transnexus to osplookup, removes res_osp and puts all logic into the app, documentation provided now in osp.txt. git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@36406 65c4cc65-6c06-0410-ace0-fbb531ad65f3 --- doc/osp.txt | 463 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 463 insertions(+) create mode 100644 doc/osp.txt (limited to 'doc/osp.txt') diff --git a/doc/osp.txt b/doc/osp.txt new file mode 100644 index 000000000..465fcf1b1 --- /dev/null +++ b/doc/osp.txt @@ -0,0 +1,463 @@ +Asterisk OSP Module User Guide + +June 16, 2006 + +Table of Contents +1 Introduction +2 OSP Toolkit +2.1 Build OSP Toolkit +2.1.1 Unpacking the Toolkit +2.1.2 Preparing to build the OSP Toolkit +2.1.3 Building the OSP Toolkit +2.1.4 Installing the OSP Toolkit +2.1.5 Building the Enrollment Utility +2.2 Obtain Crypto Files +3 Asterisk +3.1 OSP Support Implementation +3.1.1 OSPAuth +3.1.2 OSPLookup +3.1.3 OSPNext +3.1.4 OSPFinish +3.2 Build with OSP Support +3.3 Configure with OSP Support +3.3.1 osp.conf +3.3.2 zapata/sip/iax.conf +3.3.3 extensions.conf + +Asterisk is a trademark of Digium, Inc. +TransNexus and OSP Secured are trademarks of TransNexus, Inc. + +1 Introduction + This document provides instructions on how to build and configure Asterisk + V1.4 with the OSP Toolkit to enable secure, multi-lateral peering. 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 + Please reference the OSP Toolkit document "How to Build and Test the OSP + Toolkit" available from www.sipfoundry.org/OSP/OSPclient . + +2.1 Build OSP Toolkit + The software listed below is required ti build and use the OSP Toolkit: + * 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. + * 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/ActivePerl. 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 www.sipfoundry.org/osp, a free + commercial OSP server may be downloaded from www.transnexus.com and an OSP + server osptestserver.transnexus.com is freely available on the internet for + testing for testing. Please contact support@transnexus.com for testing access + to osptestserver.transnexus.com. + +2.1.1 Unpacking the Toolkit + After downloading the OSP Toolkit (version 3.3.4 or later release) from + www.sipfoundry.org, perform the following steps in order: + 1) Copy the OSP Toolkit distribution into the directory where it will reside, + say /usr/src. + 2) Un-package the distribution file by executing the following command: + gunzip -c OSPToolkit-###.tar.gz | tar xvf - + Where ### is the version number separated by underlines. For example, if + the version is 3.3.4, then the above command would be: + gunzip -c OSPToolkit-3_3_4.tar.gz | tar xvf - + A new directory (TK-3_3_4-20051103) will be created within the same directory + as the tar file. + 3) Go to the TK-3_3_4-20051103 directory by running this command: + cd TK-3_3_4-20051103 + Within this directory, you will find directories and files similar to what is + listed below if the command "ls -F" is executed): + ls -F + enroll/ + RelNotes.txt lib/ + README.txt license.txt + bin/ src/ + crypto/ test/ + include/ + +2.1.2 Preparing to build the OSP Toolkit + 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). + 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. + 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. + Note: Since the Asterisk requires the OpenSSL package. If the OpenSSL package + has been installed, 4~6 are not necessary. + +2.1.3 Building the OSP Toolkit + 7) Optionally, change the install directory of the OSP Toolkit. Open the + Makefile in the /usr/src/TK-3_3_4-20051103/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. Otherwise, it may case that the + Asterisk does not support the OSP protocol. + 8) From within the OSP Toolkit directory (/usr/src/TK-3_3_4-20051103), start + the compilation script by executing the following commands: + cd src + make clean; make build + +2.1.4 Installing the OSP Toolkit + The header files and the library of the OSP Toolkit should be installed. + Otherwise, you must specify the OSP Toolkit path for the Asterisk. + 9) Use the same script to install the Toolkit. + make install + The make script is also used to install the OSP Toolkit header files and 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, normally, + you should be root. + By default, the OSP Toolkit is compiled in the production mode. The following + table identifies which default features are activated with each compile + option: + Default Feature Production Development + Debug Information Displayed No Yes + The "Development" option is recommended for a first time build. The CFLAGS + definition in the Makefile must be modified to build in development mode. + +2.1.5 Building the Enrollment Utility + 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 and + OSP client and an OSP server. Please see the document "Device Enrollment" at + www.sipfoundry.org/OSP/OSPclient for more information about the enroll + application. + 10) From within the OSP Toolkit directory (/usr/src/TK-3_3_4-20051103), + execute the following commands at the command prompt: + cd enroll + make clean; make linux + Compilation is successful if there are no errors anywhere in the compiler + output. The enroll program is now located in the + /usr/src/TK-3_3_4-20051103/bin directory. By this point, a fully functioning + OSP Toolkit should have been successfully built. + +2.2 Obtain Crypto Files + The OSP module in Asterisk requires three crypto files containing 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/key. 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 the Asterisk OSP module with an OSP server to obtain the crypto files. + Documentation explaining how to use the enroll.sh script (Device Enrollment) + to enroll with an OSP server is available at + www.sipfoundry.org/OSP/ospclient. Copy the files file generated by the + enrollment process to the Asterisk configuration 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. The example below shows the usage when the + client is registering with osptestserver.transnexus.com. If all goes well, + the following text will be displayed. The gray boxes indicate required input. + ./enroll.sh osptestserver.transnexus.com + Generating a 512 bit RSA private key + ........................++++++++++++ + .........++++++++++++ + writing new private key to 'pkey.pem' + ----- + You are about to be asked to enter information that will be incorporated + into your certificate request. + What you are about to enter is what is called a Distinguished Name or a DN. + There are quite a few fields but you can leave some blank + For some fields there will be a default value, + If you enter '.', the field will be left blank. + ----- + Country Name (2 letter code) [AU]: _______ + State or Province Name (full name) [Some-State]: _______ + Locality Name (eg, city) []:_______ + Organization Name (eg, company) [Internet Widgits Pty Ltd]: _______ + Organizational Unit Name (eg, section) []:_______ + Common Name (eg, YOUR name) []:_______ + Email Address []:_______ + + Please enter the following 'extra' attributes + to be sent with your certificate request + A challenge password []:_______ + An optional company name []:_______ + + Error Code returned from openssl command : 0 + + CA certificate received + [SP: osptestserver.transnexus.com]Error Code returned from getcacert command : 0 + + output buffer after operation: operation=request + output buffer after nonce: operation=request&nonce=1655976791184458 + X509 CertInfo context is null pointer + Unable to get Local Certificate + depth=0 /CN=osptestserver.transnexus.com/O=OSPServer + verify error:num=18:self signed certificate + verify return:1 + depth=0 /CN=osptestserver.transnexus.com/O=OSPServer + verify return:1 + The certificate request was successful. + Error Code returned from localcert command : 0 + The files generated should be copied to the /var/lib/asterisk/key + directory. + Note: The script enroll.sh requires AT&T korn shell (ksh) or any of its + compatible variants. The /usr/src/TK-3_3_4-20051103/bin directory should be + in the PATH variable. Otherwise, enroll.sh cannot find the enroll file. + +3 Asterisk + +3.1 OSP Support Implementation + In Asterisk, all OSP support is implemented as dial plan functions. + +3.1.1 OSPAuth + OSP token validation function. + Input: + * OSPPEERIP: last hop IP address + * OSPINTOKEN: inbound OSP token + * provider: OSP service provider configured in osp.conf. If it is empty, + default provider is used. + * priority jump + Output: + * OSPINHANDLE: inbound OSP transaction handle + * OSPINTIMELIMIT: inbound call duration limit + * OSPAUTHSTATUS: OSPAuth return value. SUCCESS/FAILED/ERROR + +3.1.2 OSPLookup + OSP lookup function. + Input: + * OSPPEERIP: last hop IP address + * OSPINHANDLE: inbound OSP transaction handle + * OSPINTIMELIMIT: inbound call duration limit + * exten: called number + * provider: OSP service provider configured in osp.conf. If it is empty, + default provider is used. + * priority jump + Output: + * OSPOUTHANDLE: outbound transaction handle + * OSPTECH: outbound protocol + * OSPDEST: outbound destination + * OSPCALLING: outbound calling number + * OSPOUTTOKEN: outbound OSP token + * OSPRESULTS: number of remain destinations + * OSPOUTTIMELIMIT: outbound call duration limit + * OSPLOOKUPSTATUS: OSPLookup return value. SUCCESS/FAILED/ERROR + +3.1.3 OSPNext + OSP lookup next function. + Input: + * OSPINHANDLE: inbound transaction handle + * OSPOUTHANDLE: outbound transaction handle + * OSPINTIMELIMIT: inbound call duration limit + * OSPRESULTS: number of remain destinations + * cause: last destination disconnect cause + * priority jump + Output: + * OSPTECH: outbound protocol + * OSPDEST: outbound destination + * OSPCALLING: outbound calling number + * OSPOUTTOKEN: outbound OSP token + * OSPRESULTS: number of remain destinations + * OSPOUTTIMELIMIT: outbound call duration limit + * OSPNEXTSTATUS: OSPLookup return value. SUCCESS/FAILED/ERROR + +3.1.4 OSPFinish + OSP report usage function. + Input: + * OSPINHANDLE: inbound transaction handle + * OSPOUTHANDLE: outbound transaction handle + * OSPAUTHSTATUS: OSPAuth return value + * OSPLOOKUPTSTATUS: OSPLookup return value + * OSPNEXTSTATUS: OSPNext return value + * cause: last destination disconnect cause + * priority jump + Output: + * OSPFINISHSTATUS: OSPLookup return value. SUCCESS/FAILED/ERROR + +3.2 Build with OSP Support + If the OSP Toolkit is installed in the default install directory, /usr/local, + no additional configuration is required. If the OSP Toolkit is installed in + another directory, say /myosp, Asterisk must be configured with the location + of the OSP Toolkit. + --with-osptk=/myosp + Note: Please change the install path only if you familiar with both the OSP + Toolkit and the Asterisk. Otherwise, the change may results Asterisk not + supporting the OSP protocol. + Now, you can compile Asterisk according to the instructions provided with the + Asterisk distribution. + +3.3 Configure with OSP Support + +3.3.1 osp.conf + ; + ; Open Settlement Protocol Sample Configuration File + ; + ; This file contains configuration of providers that + ; are used by the OSP subsystem of Asterisk. The section + ; "general" is reserved for global options. Each other + ; section declares an OSP Provider. The provider "default" + ; is used when no provider is otherwise specified. + ; + [general] + ; + ; Should hardware accelleration be enabled? May not be changed + ; on a reload. + ; + accelerate=no + ; + ; Defines the token format that Asterisk can validate. + ; 0 - signed tokens only + ; 1 - unsigned tokens only + ; 2 - both signed and unsigned + ; The defaults to 0, i.e. the Asterisk can validate signed tokens only. + ; + tokenformat=0 + ; + [default] + ; + ; All paths are presumed to be under /var/lib/asterisk/keys unless + ; the path begins with '/' + ; + ; Specify the private keyfile. If unspecified, defaults to the name + ; of the section followed by "-privatekey.pem" (e.g. default-privatekey.pem) + ; + privatekey=pkey.pem + ; + ; Specify the local certificate file. If unspecified, defaults to + ; the name of the section followed by "-localcert.pem" + ; + localcert=localcert.pem + ; + ; Specify one or more Certificate Authority keys. If none are listed, + ; a single one is added with the name "-cacert.pem" + ; + cacert=cacert_0.pem + ; + ; Specific parameters can be tuned as well: + ; + ; maxconnections: Max number of simultaneous connections to the provider (default=20) + ; retrydelay: Extra delay between retries (default=0) + ; retrylimit: Max number of retries before giving up (default=2) + ; timeout: Timeout for response in milliseconds (default=500) + ; + maxconnections=20 + retrydelay=0 + retrylimit=2 + timeout=500 + ; + ; List all service points for this provider + ; + ;servicepoint=http://osptestserver.transnexus.com:1080/osp + servicepoint=http://OSP server IP:1080/osp + ; + ; Set the "source" for requesting authorization + ; + ;source=foo + source=[host IP] + ; + ; Set the authentication policy. + ; 0 - NO + ; 1 - YES + ; 2 - EXCLUSIVE + ; Default is 1, validate token but allow no token. + ; + authpolicy=1 + +3.3.2 zapata/sip/iax.conf + There is no configuration required for OSP. + +3.3.3 extensions.conf + An Asterisk box can be configured as OSP source/destination gateway or OSP proxy. + +3.3.3.1 OSP Source Gateway + [PhoneSrcGW] + ; Set calling number if necessary + exten => _XXXX.,1,Set(CALLERID(numner)=CallingNumber) + ; OSP lookup using default provider, if fail/error jump to 2+101 + exten => _XXXX.,2,OSPLookup(${EXTEN}||j) + ; Set calling number which may be translated + exten => _XXXX.,3,Set(CALLERID(number)=${OSPCALLING}) + ; Dial to destination, 60 timeout, with call duration limit + exten => _XXXX.,4,Dial(${OSPTECH}/${OSPDEST},60,oL($[${OSPOUTTIMELIMIT}*1000])) + ; Wait 3 seconds + exten => _XXXX.,5,Wait,3 + ; Hangup + exten => _XXXX.,6,Hangup + ; Deal with OSPLookup fail/error + exten => _XXXX.,2+101,Hangup + ; OSP report usage + exten => h,1,OSPFinish(${HANGUPCAUSE}) + 3.3.3.2 OSP Destination Gateway + [PhoneDstGW] + ; Get peer IP + exten => _XXXX.,1,Set(OSPPEERIP=${SIPCHANINFO(peerip)}) + ; Get OSP token + exten => _XXXX.,2,Set(OSPINTOKEN=${SIP_HEADER(P-OSP-Auth-Token)}) + ; Validate token using default provider, if fail/error jump to 3+101 + exten => _XXXX.,3,OSPAuth(|j) + ; Ringing + exten => _XXXX.,4,Ringing + ; Wait 1 second + exten => _XXXX.,5,Wait,1 + ; Dial phone, timeout 15 seconds, with call duration limit + exten => _XXXX.,6,Dial(${DIALOUTANALOG}/${EXTEN:1},15,oL($[${OSPINTIMELIMIT}*1000])) + ; Wait 3 seconds + exten => _XXXX.,7,Wait,3 + ; Hangup + exten => _XXXX.,8,Hangup + ; Deal with OSPAuth fail/error + exten => _XXXX.,3+101,Hangup + ; OSP report usage + exten => h,1,OSPFinish(${HANGUPCAUSE}) + 3.3.3.3 Proxy + [GeneralProxy] + ; Get peer IP + exten => _XXXX.,1,Set(OSPPEERIP=${SIPCHANINFO(peerip)}) + ; Get OSP token + exten => _XXXX.,2,Set(OSPINTOKEN=${SIP_HEADER(P-OSP-Auth-Token)}) + ; Validate token using default provider, if fail/error jump to 3+101 + exten => _XXXX.,3,OSPAuth(|j) + ; OSP lookup using default provider, if fail/error jump to 4+101 + exten => _XXXX.,4,OSPLookup(${EXTEN}||j) + ; Set calling number which may be translated + exten => _XXXX.,5,Set(CALLERID(number)=${OSPCALLING}) + ; Dial to 1st destination, 60 timeout, with call duration limit + exten => _XXXX.,6,Dial(${OSPTECH}/${OSPDEST},24,oL($[${OSPOUTTIMELIMIT}*1000])) + ; OSP lookup next, if fail/error jump to 7+101 + exten => _XXXX.,7,OSPNext(${HANGUPCAUSE}||j) + ; Set calling number which may be translated + exten => _XXXX.,8,Set(CALLERID(number)=${OSPCALLING}) + ; Dial to 2nd destination, 60 timeout, with call duration limit + exten => _XXXX.,9,Dial(${OSPTECH}/${OSPDEST},25,oL($[${OSPOUTTIMELIMIT}*1000])) + ; OSP lookup next, if fail/error jump to 10+101 + exten => _XXXX.,10,OSPNext(${HANGUPCAUSE}||j) + ; Set calling number which may be translated + exten => _XXXX.,11,Set(CALLERID(number)=${OSPCALLING}) + ; Dial to 3rd destination, 60 timeout, with call duration limit + exten => _XXXX.,12,Dial(${OSPTECH}/${OSPDEST},26,oL($[${OSPOUTTIMELIMIT}*1000])) + ; Hangup + exten => _XXXX.,13,Hangup + ; Deal with OSPAuth fail/error + exten => _XXXX.,3+101,Hangup + ; Deal with OSPLookup fail/error + exten => _XXXX.,4+101,Hangup + ; Deal with 1st OSPNext fail/error + exten => _XXXX.,7+101,Hangup + ; Deal with 2nd OSPNext fail/error + exten => _XXXX.,10+101,Hangup + ; OSP report usage + exten => h,1,OSPFinish(${HANGUPCAUSE}) -- cgit v1.2.3