465fcf1b1dcb9bd2ccad61409c8ebba59beb19f7
[asterisk/asterisk.git] / doc / osp.txt
1 Asterisk OSP Module User Guide
2
3 June 16, 2006
4
5 Table of Contents
6 1        Introduction
7 2        OSP Toolkit
8 2.1      Build OSP Toolkit
9 2.1.1    Unpacking the Toolkit
10 2.1.2    Preparing to build the OSP Toolkit
11 2.1.3    Building the OSP Toolkit
12 2.1.4    Installing the OSP Toolkit
13 2.1.5    Building the Enrollment Utility
14 2.2      Obtain Crypto Files
15 3        Asterisk
16 3.1      OSP Support Implementation
17 3.1.1    OSPAuth
18 3.1.2    OSPLookup
19 3.1.3    OSPNext
20 3.1.4    OSPFinish
21 3.2      Build with OSP Support
22 3.3      Configure with OSP Support
23 3.3.1    osp.conf
24 3.3.2    zapata/sip/iax.conf
25 3.3.3    extensions.conf
26
27 Asterisk is a trademark of Digium, Inc.
28 TransNexus and OSP Secured are trademarks of TransNexus, Inc.
29
30 1 Introduction
31   This document provides instructions on how to build and configure Asterisk 
32   V1.4 with the OSP Toolkit to enable secure, multi-lateral peering. The OSP 
33   Toolkit is an open source implementation of the OSP peering protocol and is 
34   freely available from www.sipfoundry.org.  The OSP standard defined by the 
35   European Telecommunications Standards Institute (ETSI TS 101 321) 
36   www.esti.org.  If you have questions or need help, building Asterisk with the
37   OSP Toolkit, please post your question on the OSP mailing list at 
38   https://list.sipfoundry.org/mailman/listinfo/osp. 
39
40 2 OSP Toolkit
41   Please reference the OSP Toolkit document "How to Build and Test the OSP 
42   Toolkit" available from www.sipfoundry.org/OSP/OSPclient .  
43
44 2.1 Build OSP Toolkit
45   The software listed below is required ti build and use the OSP Toolkit:
46   * OpenSSL (required for building) - Open Source SSL protocol and 
47   Cryptographic Algorithms (version 0.9.7g recommended) from www.openssl.org. 
48   Pre-compiled OpenSSL binary packages are not recommended because of the 
49   binary compatibility issue. 
50   * Perl (required for building) - A programming language used by OpenSSL for 
51   compilation. Any version of Perl should work. One version of Perl is 
52   available from www.activestate.com/ActivePerl. If pre-compiled OpenSSL 
53   packages are used, Perl package is not required.
54   * C compiler (required for building) - Any C compiler should work.  The GNU 
55   Compiler Collection from www.gnu.org is routinely used for building the OSP 
56   Toolkit for testing.
57   * OSP Server (required for testing) - Access to any OSP server should work.  
58   Open source OSP servers are available from www.sipfoundry.org/osp, a free 
59   commercial OSP server may be downloaded from www.transnexus.com and an OSP 
60   server osptestserver.transnexus.com is freely available on the internet for 
61   testing for testing. Please contact support@transnexus.com for testing access
62   to osptestserver.transnexus.com.
63
64 2.1.1 Unpacking the Toolkit
65   After downloading the OSP Toolkit (version 3.3.4 or later release) from 
66   www.sipfoundry.org, perform the following steps in order:
67   1) Copy the OSP Toolkit distribution into the directory where it will reside,
68   say /usr/src. 
69   2) Un-package the distribution file by executing the following command: 
70     gunzip -c OSPToolkit-###.tar.gz | tar xvf -
71     Where ### is the version number separated by underlines. For example, if 
72     the version is 3.3.4, then the above command would be: 
73     gunzip -c OSPToolkit-3_3_4.tar.gz | tar xvf -
74   A new directory (TK-3_3_4-20051103) will be created within the same directory
75   as the tar file.
76   3) Go to the TK-3_3_4-20051103 directory by running this command:
77     cd TK-3_3_4-20051103
78   Within this directory, you will find directories and files similar to what is
79   listed below if the command "ls -F" is executed):
80     ls -F
81     enroll/
82     RelNotes.txt        lib/
83     README.txt          license.txt
84     bin/                src/
85     crypto/             test/
86     include/
87
88 2.1.2 Preparing to build the OSP Toolkit
89   4) Compile OpenSSL according to the instructions provided with the OpenSSL 
90   distribution (You would need to do this only if you don't have openssl 
91   already).
92   5) Copy the OpenSSL header files (the *.h files) into the crypto/openssl 
93   directory within the osptoolkit directory. The OpenSSL header files are 
94   located under the openssl/include/openssl directory.
95   6) Copy the OpenSSL library files (libcrypto.a and libssl.a) into the lib 
96   directory within the osptoolkit directory. The OpenSSL library files are 
97   located under the openssl directory.
98   Note: Since the Asterisk requires the OpenSSL package. If the OpenSSL package
99   has been installed, 4~6 are not necessary.
100
101 2.1.3 Building the OSP Toolkit
102   7) Optionally, change the install directory of the OSP Toolkit. Open the 
103   Makefile in the /usr/src/TK-3_3_4-20051103/src directory, look for the 
104   install path variable - INSTALL_PATH, and edit it to be anywhere you want 
105   (defaults /usr/local). 
106   Note: Please change the install path variable only if you are familiar with 
107   both the OSP Toolkit and the Asterisk. Otherwise, it may case that the 
108   Asterisk does not support the OSP protocol.
109   8) From within the OSP Toolkit directory (/usr/src/TK-3_3_4-20051103), start 
110   the compilation script by executing the following commands:
111     cd src
112     make clean; make build
113
114 2.1.4 Installing the OSP Toolkit
115   The header files and the library of the OSP Toolkit should be installed. 
116   Otherwise, you must specify the OSP Toolkit path for the Asterisk.
117   9) Use the same script to install the Toolkit.
118     make install
119   The make script is also used to install the OSP Toolkit header files and the 
120   library into the INSTALL_PATH specified in the Makefile. 
121   Note: Please make sure you have the rights to access the INSTALL_PATH 
122   directory. For example, in order to access /usr/local directory, normally, 
123   you should be root.
124   By default, the OSP Toolkit is compiled in the production mode. The following
125   table identifies which default features are activated with each compile 
126   option:
127     Default Feature                Production    Development
128     Debug Information Displayed    No            Yes
129   The "Development" option is recommended for a first time build. The CFLAGS 
130   definition in the Makefile must be modified to build in development mode.  
131
132 2.1.5 Building the Enrollment Utility
133   Device enrollment is the process of establishing a trusted cryptographic 
134   relationship between the VoIP device and the OSP Server. The Enroll program 
135   is a utility application for establishing a trusted relationship between and 
136   OSP client and an OSP server. Please see the document "Device Enrollment" at 
137   www.sipfoundry.org/OSP/OSPclient for more information about the enroll 
138   application.
139   10) From within the OSP Toolkit directory (/usr/src/TK-3_3_4-20051103), 
140   execute the following commands at the command prompt:
141     cd enroll
142     make clean; make linux
143   Compilation is successful if there are no errors anywhere in the compiler 
144   output. The enroll program is now located in the 
145   /usr/src/TK-3_3_4-20051103/bin directory. By this point, a fully functioning 
146   OSP Toolkit should have been successfully built.
147
148 2.2 Obtain Crypto Files
149   The OSP module in Asterisk requires three crypto files containing local 
150   certificate (localcert.pem), private key (pkey.pem), and CA certificate 
151   (cacert_0.pem).  Asterisk will try to load the files from the Asterisk 
152   public/private key directory - /var/lib/asterisk/key.  If the files are not 
153   present, the OSP module will not start and the Asterisk will not support the 
154   OSP protocol.  Use the enroll.sh script from the toolkit distribution to 
155   enroll the Asterisk OSP module with an OSP server to obtain the crypto files.
156   Documentation explaining how to use the enroll.sh script (Device Enrollment) 
157   to enroll with an OSP server is available at 
158   www.sipfoundry.org/OSP/ospclient.  Copy the files file generated by the 
159   enrollment process to the Asterisk configuration directory.  
160   Note: The osptestserver.transnexus.com is configured only for sending and 
161   receiving non-SSL messages, and issuing signed tokens. If you need help, post
162   a message on the OSP mailing list of www.sipfoundry.org or send an e-mail to 
163   support@transnexus.com.
164   The enroll.sh script takes the domain name or IP addresses of the OSP servers
165   that the OSP Toolkit needs to enroll with as arguments, and then generates 
166   pem files - cacert_#.pem, certreq.pem, localcert.pem, and pkey.pem. The '#'
167   in the cacert file name is used to differentiate the ca certificate file 
168   names for the various SP's (OSP servers). If only one address is provided at 
169   the command line, cacert_0.pem will be generated. If 2 addresses are provided
170   at the command line, 2 files will be generated - cacert_0.pem and 
171   cacert_1.pem, one for each SP. The example below shows the usage when the 
172   client is registering with osptestserver.transnexus.com. If all goes well, 
173   the following text will be displayed. The gray boxes indicate required input.
174     ./enroll.sh osptestserver.transnexus.com
175     Generating a 512 bit RSA private key
176     ........................++++++++++++
177     .........++++++++++++
178     writing new private key to 'pkey.pem'
179     -----
180     You are about to be asked to enter information that will be incorporated
181     into your certificate request.
182     What you are about to enter is what is called a Distinguished Name or a DN.
183     There are quite a few fields but you can leave some blank
184     For some fields there will be a default value,
185     If you enter '.', the field will be left blank.
186     -----
187     Country Name (2 letter code) [AU]: _______
188     State or Province Name (full name) [Some-State]: _______
189     Locality Name (eg, city) []:_______
190     Organization Name (eg, company) [Internet Widgits Pty Ltd]: _______
191     Organizational Unit Name (eg, section) []:_______
192     Common Name (eg, YOUR name) []:_______
193     Email Address []:_______
194
195     Please enter the following 'extra' attributes
196     to be sent with your certificate request
197     A challenge password []:_______
198     An optional company name []:_______
199
200     Error Code returned from openssl command : 0
201
202     CA certificate received
203     [SP: osptestserver.transnexus.com]Error Code returned from getcacert command : 0
204
205     output buffer after operation: operation=request
206     output buffer after nonce: operation=request&nonce=1655976791184458
207     X509 CertInfo context is null pointer
208     Unable to get Local Certificate
209     depth=0 /CN=osptestserver.transnexus.com/O=OSPServer
210     verify error:num=18:self signed certificate
211     verify return:1
212     depth=0 /CN=osptestserver.transnexus.com/O=OSPServer
213     verify return:1
214     The certificate request was successful.
215     Error Code returned from localcert command : 0
216   The files generated should be copied to the /var/lib/asterisk/key 
217   directory. 
218   Note: The script enroll.sh requires AT&T korn shell (ksh) or any of its 
219   compatible variants. The /usr/src/TK-3_3_4-20051103/bin directory should be 
220   in the PATH variable. Otherwise, enroll.sh cannot find the enroll file.
221
222 3 Asterisk
223
224 3.1 OSP Support Implementation
225   In Asterisk, all OSP support is implemented as dial plan functions.
226
227 3.1.1 OSPAuth 
228   OSP token validation function.
229   Input:
230   * OSPPEERIP: last hop IP address
231   * OSPINTOKEN: inbound OSP token
232   * provider: OSP service provider configured in osp.conf. If it is empty, 
233   default provider is used.
234   * priority jump
235   Output:
236   * OSPINHANDLE: inbound OSP transaction handle
237   * OSPINTIMELIMIT: inbound call duration limit
238   * OSPAUTHSTATUS: OSPAuth return value. SUCCESS/FAILED/ERROR
239
240 3.1.2 OSPLookup
241   OSP lookup function.
242   Input:
243   * OSPPEERIP: last hop IP address
244   * OSPINHANDLE: inbound OSP transaction handle
245   * OSPINTIMELIMIT: inbound call duration limit 
246   * exten: called number
247   * provider: OSP service provider configured in osp.conf. If it is empty, 
248   default provider is used.
249   * priority jump
250   Output:
251   * OSPOUTHANDLE: outbound transaction handle
252   * OSPTECH: outbound protocol
253   * OSPDEST: outbound destination
254   * OSPCALLING: outbound calling number
255   * OSPOUTTOKEN: outbound OSP token
256   * OSPRESULTS: number of remain destinations
257   * OSPOUTTIMELIMIT: outbound call duration limit
258   * OSPLOOKUPSTATUS: OSPLookup return value. SUCCESS/FAILED/ERROR
259
260 3.1.3 OSPNext
261   OSP lookup next function.
262   Input:
263   * OSPINHANDLE: inbound transaction handle
264   * OSPOUTHANDLE: outbound transaction handle
265   * OSPINTIMELIMIT: inbound call duration limit 
266   * OSPRESULTS: number of remain destinations
267   * cause: last destination disconnect cause
268   * priority jump
269   Output:
270   * OSPTECH: outbound protocol
271   * OSPDEST: outbound destination
272   * OSPCALLING: outbound calling number
273   * OSPOUTTOKEN: outbound OSP token
274   * OSPRESULTS: number of remain destinations
275   * OSPOUTTIMELIMIT: outbound call duration limit
276   * OSPNEXTSTATUS: OSPLookup return value. SUCCESS/FAILED/ERROR
277
278 3.1.4 OSPFinish
279   OSP report usage function.
280   Input:
281   * OSPINHANDLE: inbound transaction handle
282   * OSPOUTHANDLE: outbound transaction handle
283   * OSPAUTHSTATUS: OSPAuth return value
284   * OSPLOOKUPTSTATUS: OSPLookup return value
285   * OSPNEXTSTATUS: OSPNext return value
286   * cause: last destination disconnect cause
287   * priority jump
288   Output:
289   * OSPFINISHSTATUS: OSPLookup return value. SUCCESS/FAILED/ERROR
290
291 3.2 Build with OSP Support
292   If the OSP Toolkit is installed in the default install directory, /usr/local,
293   no additional configuration is required. If the OSP Toolkit is installed in 
294   another directory, say /myosp, Asterisk must be configured with the location 
295   of the OSP Toolkit.
296     --with-osptk=/myosp
297   Note: Please change the install path only if you familiar with both the OSP 
298   Toolkit and the Asterisk. Otherwise, the change may results Asterisk not 
299   supporting the OSP protocol.
300   Now, you can compile Asterisk according to the instructions provided with the
301   Asterisk distribution.
302
303 3.3 Configure with OSP Support
304
305 3.3.1 osp.conf
306   ;
307   ; Open Settlement Protocol Sample Configuration File
308   ;
309   ; This file contains configuration of providers that
310   ; are used by the OSP subsystem of Asterisk.  The section
311   ; "general" is reserved for global options.  Each other 
312   ; section declares an OSP Provider.  The provider "default"
313   ; is used when no provider is otherwise specified.
314   ;
315   [general]
316   ;
317   ; Should hardware accelleration be enabled?  May not be changed
318   ; on a reload.
319   ;
320   accelerate=no
321   ;
322   ; Defines the token format that Asterisk can validate. 
323   ; 0 - signed tokens only 
324   ; 1 - unsigned tokens only 
325   ; 2 - both signed and unsigned
326   ; The defaults to 0, i.e. the Asterisk can validate signed tokens only.
327   ;
328   tokenformat=0
329   ;
330   [default]
331   ;
332   ; All paths are presumed to be under /var/lib/asterisk/keys unless
333   ; the path begins with '/'
334   ;
335   ; Specify the private keyfile.  If unspecified, defaults to the name
336   ; of the section followed by "-privatekey.pem" (e.g. default-privatekey.pem)
337   ;
338   privatekey=pkey.pem
339   ;
340   ; Specify the local certificate file.  If unspecified, defaults to
341   ; the name of the section followed by "-localcert.pem"
342   ;
343   localcert=localcert.pem
344   ;
345   ; Specify one or more Certificate Authority keys.  If none are listed,
346   ; a single one is added with the name "-cacert.pem"
347   ;
348   cacert=cacert_0.pem
349   ;
350   ; Specific parameters can be tuned as well:
351   ;
352   ; maxconnections: Max number of simultaneous connections to the provider (default=20)
353   ; retrydelay:     Extra delay between retries (default=0)
354   ; retrylimit:     Max number of retries before giving up (default=2)
355   ; timeout:        Timeout for response in milliseconds (default=500)
356   ;
357   maxconnections=20
358   retrydelay=0
359   retrylimit=2
360   timeout=500
361   ;
362   ; List all service points for this provider
363   ;
364   ;servicepoint=http://osptestserver.transnexus.com:1080/osp
365   servicepoint=http://OSP server IP:1080/osp
366   ;
367   ; Set the "source" for requesting authorization
368   ;
369   ;source=foo
370   source=[host IP]
371   ;
372   ; Set the authentication policy.  
373   ; 0 - NO 
374   ; 1 - YES
375   ; 2 - EXCLUSIVE
376   ; Default is 1, validate token but allow no token.
377   ;
378   authpolicy=1
379
380 3.3.2 zapata/sip/iax.conf
381   There is no configuration required for OSP.
382
383 3.3.3 extensions.conf
384   An Asterisk box can be configured as OSP source/destination gateway or OSP proxy.
385
386 3.3.3.1 OSP Source Gateway
387   [PhoneSrcGW]
388   ; Set calling number if necessary
389   exten => _XXXX.,1,Set(CALLERID(numner)=CallingNumber)
390   ; OSP lookup using default provider, if fail/error jump to 2+101
391   exten => _XXXX.,2,OSPLookup(${EXTEN}||j)
392   ; Set calling number which may be translated 
393   exten => _XXXX.,3,Set(CALLERID(number)=${OSPCALLING})
394   ; Dial to destination, 60 timeout, with call duration limit
395   exten => _XXXX.,4,Dial(${OSPTECH}/${OSPDEST},60,oL($[${OSPOUTTIMELIMIT}*1000]))
396   ; Wait 3 seconds
397   exten => _XXXX.,5,Wait,3
398   ; Hangup
399   exten => _XXXX.,6,Hangup
400   ; Deal with OSPLookup fail/error
401   exten => _XXXX.,2+101,Hangup
402   ; OSP report usage
403   exten => h,1,OSPFinish(${HANGUPCAUSE})
404   3.3.3.2 OSP Destination Gateway
405   [PhoneDstGW]
406   ; Get peer IP
407   exten => _XXXX.,1,Set(OSPPEERIP=${SIPCHANINFO(peerip)})
408   ; Get OSP token
409   exten => _XXXX.,2,Set(OSPINTOKEN=${SIP_HEADER(P-OSP-Auth-Token)})
410   ; Validate token using default provider, if fail/error jump to 3+101
411   exten => _XXXX.,3,OSPAuth(|j)
412   ; Ringing
413   exten => _XXXX.,4,Ringing
414   ; Wait 1 second
415   exten => _XXXX.,5,Wait,1
416   ; Dial phone, timeout 15 seconds, with call duration limit
417   exten => _XXXX.,6,Dial(${DIALOUTANALOG}/${EXTEN:1},15,oL($[${OSPINTIMELIMIT}*1000]))
418   ; Wait 3 seconds
419   exten => _XXXX.,7,Wait,3
420   ; Hangup
421   exten => _XXXX.,8,Hangup
422   ; Deal with OSPAuth fail/error
423   exten => _XXXX.,3+101,Hangup
424   ; OSP report usage
425   exten => h,1,OSPFinish(${HANGUPCAUSE})
426   3.3.3.3 Proxy
427   [GeneralProxy]
428   ; Get peer IP
429   exten => _XXXX.,1,Set(OSPPEERIP=${SIPCHANINFO(peerip)})
430   ; Get OSP token
431   exten => _XXXX.,2,Set(OSPINTOKEN=${SIP_HEADER(P-OSP-Auth-Token)})
432   ; Validate token using default provider, if fail/error jump to 3+101
433   exten => _XXXX.,3,OSPAuth(|j)
434   ; OSP lookup using default provider, if fail/error jump to 4+101
435   exten => _XXXX.,4,OSPLookup(${EXTEN}||j)
436   ; Set calling number which may be translated 
437   exten => _XXXX.,5,Set(CALLERID(number)=${OSPCALLING})
438   ; Dial to 1st destination, 60 timeout, with call duration limit
439   exten => _XXXX.,6,Dial(${OSPTECH}/${OSPDEST},24,oL($[${OSPOUTTIMELIMIT}*1000]))
440   ; OSP lookup next, if fail/error jump to 7+101
441   exten => _XXXX.,7,OSPNext(${HANGUPCAUSE}||j)
442   ; Set calling number which may be translated 
443   exten => _XXXX.,8,Set(CALLERID(number)=${OSPCALLING})
444   ; Dial to 2nd destination, 60 timeout, with call duration limit
445   exten => _XXXX.,9,Dial(${OSPTECH}/${OSPDEST},25,oL($[${OSPOUTTIMELIMIT}*1000]))
446   ; OSP lookup next, if fail/error jump to 10+101
447   exten => _XXXX.,10,OSPNext(${HANGUPCAUSE}||j)
448   ; Set calling number which may be translated 
449   exten => _XXXX.,11,Set(CALLERID(number)=${OSPCALLING})
450   ; Dial to 3rd destination, 60 timeout, with call duration limit
451   exten => _XXXX.,12,Dial(${OSPTECH}/${OSPDEST},26,oL($[${OSPOUTTIMELIMIT}*1000]))
452   ; Hangup
453   exten => _XXXX.,13,Hangup
454   ; Deal with OSPAuth fail/error
455   exten => _XXXX.,3+101,Hangup
456   ; Deal with OSPLookup fail/error
457   exten => _XXXX.,4+101,Hangup
458   ; Deal with 1st OSPNext fail/error
459   exten => _XXXX.,7+101,Hangup
460   ; Deal with 2nd OSPNext fail/error
461   exten => _XXXX.,10+101,Hangup
462   ; OSP report usage
463   exten => h,1,OSPFinish(${HANGUPCAUSE})