f53789848f675592ab54667cccfb919d8a81ccd4
[asterisk/asterisk.git] / doc / osp.txt
1 OSP User Guide for Asterisk V1.6
2
3 4 January 2007
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     Configure for OSP Support
17 3.1.1   Build Asterisk with OSP Toolkit
18 3.1.2   osp.conf
19 3.1.3   extensions.conf
20 3.1.4   zapata/sip/iax/h323/ooh323.conf
21 3.2     OSP Dial Plan Functions
22 3.2.1   OSPAuth
23 3.2.2   OSPLookup
24 3.2.3   OSPNext
25 3.2.4   OSPFinish
26 3.3     extensions.conf Examples
27 3.3.1   Source Gateway
28 3.3.2   Destination Gateway
29 3.3.3   Proxy
30
31 Asterisk is a trademark of Digium, Inc.
32 TransNexus and OSP Secures are trademarks of TransNexus, Inc.
33
34 1 Introduction
35   This document provides instructions on how to build and configure Asterisk 
36   V1.6 with the OSP Toolkit to enable secure, multi-lateral peering.  This 
37   document is also available in the Asterisk source package as doc/osp.txt.  
38   The OSP Toolkit is an open source implementation of the OSP peering protocol 
39   and is freely available from www.sipfoundry.org.  The OSP standard defined by 
40   the European Telecommunications Standards Institute (ETSI TS 101 321) 
41   www.esti.org.  If you have questions or need help, building Asterisk with the 
42   OSP Toolkit, please post your question on the OSP mailing list at 
43   https://list.sipfoundry.org/mailman/listinfo/osp.
44
45 2 OSP Toolkit
46   Please reference the OSP Toolkit document "How to Build and Test the OSP 
47   Toolkit" available from https://www.sipfoundry.org/OSPclient.  
48
49 2.1 Build OSP Toolkit
50   The software listed below is required to build and use the OSP Toolkit:
51   * OpenSSL (required for building) - Open Source SSL protocol and Cryptographic 
52     Algorithms (version 0.9.7g recommended) from www.openssl.org. Pre-compiled 
53     OpenSSL binary packages are not recommended because of the binary 
54     compatibility issue. 
55   * Perl (required for building) - A programming language used by OpenSSL for 
56     compilation. Any version of Perl should work. One version of Perl is 
57     available from www.activestate.com/Products/ActivePer. If pre-compiled 
58     OpenSSL packages are used, Perl package is not required.
59   * C compiler (required for building) - Any C compiler should work.  The GNU 
60     Compiler Collection from www.gnu.org is routinely used for building the OSP 
61     Toolkit for testing.
62   * OSP Server (required for testing) - Access to any OSP server should work.  
63     Open source OSP servers are available from https://www.sipfoundry.org/OSP, 
64     or go to http://www.transnexus.com/OSP%20Toolkit/Peering_Server/VoIP_Peering_Server.htm 
65     to download a free commercial OSP server. 
66
67 2.1.1 Unpacking the Toolkit
68   After downloading the OSP Toolkit (version 3.3.6 or later release) from 
69   www.sipfoundry.org, perform the following steps in order:
70   1) Copy the OSP Toolkit distribution into the directory where it will reside. 
71      The default directory for the OSP Toolkit is /usr/src. 
72   2) Un-package the distribution file by executing the following command: 
73        gunzip -c OSPToolkit-###.tar.gz | tar xvf -
74      Where ### is the version number separated by underlines. For example, if 
75      the version is 3.3.6, then the above command would be: 
76        gunzip -c OSPToolkit-3_3_6.tar.gz | tar xvf -
77      A new directory (TK-3_3_6-20060303) will be created within the same 
78      directory as the tar file.
79   3) Go to the TK-3_3_6-20060303 directory by running this command:
80        cd TK-3_3_6-20060303
81      Within this directory, you will find directories and files similar to what 
82      is listed below if the command "ls -F" is executed):
83        ls -F
84        enroll/
85        RelNotes.txt     lib/
86        README.txt       license.txt
87        bin/             src/
88        crypto/          test/
89        include/
90
91 2.1.2 Preparing to build the OSP Toolkit
92   4) Compile OpenSSL according to the instructions provided with the OpenSSL 
93      distribution (You would need to do this only if you don't have openssl 
94      already).
95   5) Copy the OpenSSL header files (the *.h files) into the crypto/openssl 
96      directory within the osptoolkit directory. The OpenSSL header files are 
97      located under the openssl/include/openssl directory.
98   6) Copy the OpenSSL library files (libcrypto.a and libssl.a) into the lib 
99      directory within the osptoolkit directory. The OpenSSL library files are 
100      located under the openssl directory.
101      Note: Since the Asterisk requires the OpenSSL package. If the OpenSSL 
102            package has been installed, steps 4 through 6 are not necessary.
103   7) Optionally, change the install directory of the OSP Toolkit. Open the 
104      Makefile in the /usr/src/TK-3_3_6-20060303/src directory, look for the 
105      install path variable - INSTALL_PATH, and edit it to be anywhere you want 
106      (defaults /usr/local). 
107      Note: Please change the install path variable only if you are familiar 
108            with both the OSP Toolkit and the Asterisk. 
109
110 2.1.3 Building the OSP Toolkit
111   8) From within the OSP Toolkit directory (/usr/src/TK-3_3_6-20060303), start 
112      the compilation script by executing the following commands:
113        cd src
114        make clean; make build
115
116 2.1.4 Installing the OSP Toolkit
117   The header files and the library of the OSP Toolkit should be installed. 
118   Otherwise, you must specify the OSP Toolkit path for the Asterisk.
119   9) Use the make script to install the Toolkit.
120        make install
121      The make script is also used to install the OSP Toolkit header files and 
122      the library into the INSTALL_PATH specified in the Makefile. 
123      Note: Please make sure you have the rights to access the INSTALL_PATH 
124            directory. For example, in order to access /usr/local directory, 
125            root privileges are required.
126
127 2.1.5 Building the Enrollment Utility
128   Device enrollment is the process of establishing a trusted cryptographic 
129   relationship between the VoIP device and the OSP Server. The Enroll program is
130   a utility application for establishing a trusted relationship between an OSP 
131   client and an OSP server. Please see the document "Device Enrollment" at 
132   https://www.sipfoundry.org/OSPclient for more information about the enroll 
133   application.
134   10) From within the OSP Toolkit directory (example: 
135       /usr/src/TK-3_3_6-20060303), execute the following commands at the command 
136       prompt:
137         cd enroll
138         make clean; make linux
139       Compilation is successful if there are no errors in the compiler output. 
140       The enroll program is now located in the OSP Toolkit/bin directory 
141       (example: /usr/src/ TK-3_3_6-20060303/bin). 
142
143 2.2 Obtain Crypto Files
144   The OSP module in Asterisk requires three crypto files containing a local 
145   certificate (localcert.pem), private key (pkey.pem), and CA certificate 
146   (cacert_0.pem).  Asterisk will try to load the files from the Asterisk 
147   public/private key directory - /var/lib/asterisk/keys.  If the files are not 
148   present, the OSP module will not start and the Asterisk will not support the 
149   OSP protocol.  Use the enroll.sh script from the toolkit distribution to 
150   enroll Asterisk with an OSP server and obtain the crypto files.  Documentation 
151   explaining how to use the enroll.sh script (Device Enrollment) to enroll with 
152   an OSP server is available at https://www.sipfoundry.org/OSPclient.  Copy the 
153   files generated by the enrollment process to the Asterisk 
154   /var/lib/asterisk/keys directory.  
155   Note: The osptestserver.transnexus.com is configured only for sending and 
156         receiving non-SSL messages, and issuing signed tokens. If you need help, 
157         post a message on the OSP mailing list of www.sipfoundry.org or send an 
158         e-mail to support@transnexus.com.
159   The enroll.sh script takes the domain name or IP addresses of the OSP servers 
160   that the OSP Toolkit needs to enroll with as arguments, and then generates pem 
161   files - cacert_#.pem, certreq.pem, localcert.pem, and pkey.pem. The "#" in the 
162   cacert file name is used to differentiate the ca certificate file names for 
163   the various SP's (OSP servers). If only one address is provided at the command 
164   line, cacert_0.pem will be generated. If 2 addresses are provided at the 
165   command line, 2 files will be generated - cacert_0.pem and cacert_1.pem, one 
166   for each SP (OSP server). The example below shows the usage when the client 
167   is registering with osptestserver.transnexus.com. 
168     ./enroll.sh osptestserver.transnexus.com
169     Generating a 512 bit RSA private key
170     ........................++++++++++++
171     .........++++++++++++
172     writing new private key to 'pkey.pem'
173     -----
174     You are about to be asked to enter information that will be incorporated
175     into your certificate request.
176     What you are about to enter is what is called a Distinguished Name or a DN.
177     There are quite a few fields but you can leave some blank
178     For some fields there will be a default value,
179     If you enter '.', the field will be left blank.
180     -----
181     Country Name (2 letter code) [AU]: _______
182     State or Province Name (full name) [Some-State]: _______
183     Locality Name (eg, city) []:_______
184     Organization Name (eg, company) [Internet Widgits Pty Ltd]: _______
185     Organizational Unit Name (eg, section) []:_______
186     Common Name (eg, YOUR name) []:_______
187     Email Address []:_______
188     
189     Please enter the following 'extra' attributes
190     to be sent with your certificate request
191     A challenge password []:_______
192     An optional company name []:_______
193    
194     Error Code returned from openssl command : 0
195   
196     CA certificate received
197     [SP: osptestserver.transnexus.com]Error Code returned from getcacert command : 0
198       
199     output buffer after operation: operation=request
200     output buffer after nonce: operation=request&nonce=1655976791184458
201     X509 CertInfo context is null pointer
202     Unable to get Local Certificate
203     depth=0 /CN=osptestserver.transnexus.com/O=OSPServer
204     verify error:num=18:self signed certificate
205     verify return:1
206     depth=0 /CN=osptestserver.transnexus.com/O=OSPServer
207     verify return:1
208     The certificate request was successful.
209     Error Code returned from localcert command : 0
210   The files generated should be copied to the /var/lib/asterisk/keys directory. 
211   Note: The script enroll.sh requires AT&T korn shell (ksh) or any of its 
212         compatible variants. The /usr/src/TK-3_3_6-20060303/bin directory should 
213         be in the PATH variable. Otherwise, enroll.sh cannot find the enroll 
214         file.
215
216 3 Asterisk
217   In Asterisk, all OSP support is implemented as dial plan functions. In 
218   Asterisk V1.6, all combinations of routing between OSP and non-OSP enabled 
219   networks using any combination of SIP, H.323 and IAX protocols are fully 
220   supported.  Section 3.1 describes the three easy steps to add OSP support to 
221   Asterisk:
222     1. Build Asterisk with OSP Toolkit
223     2. Configure osp.conf file
224     3. Cut and paste to extensions.conf
225   Sections 3.2 and 3.3 provide a detailed explanation of OSP dial plan functions 
226   and configuration examples.  The detailed information provided in Sections 3.2 
227   and 3.3 is not required for operating Asterisk with OSP, but may be helpful to 
228   developers who want to customize their Asterisk OSP implementation.
229
230 3.1 Configure for OSP Support
231
232 3.1.1 Build Asterisk with OSP Toolkit
233   The first step is to build Asterisk with the OSP Toolkit.  If the OSP Toolkit 
234   is installed in the default install directory, /usr/local, no additional 
235   configuration is required.  Compile Asterisk according to the instructions 
236   provided with the Asterisk distribution. 
237   If the OSP Toolkit is installed in another directory, such as /myosp, Asterisk 
238   must be configured with the location of the OSP Toolkit.  See the example 
239   below.
240     --with-osptk=/myosp
241   Note: Please change the install path only if you familiar with both the OSP 
242         Toolkit and the Asterisk. Otherwise, the change may result in Asterisk 
243         not supporting the OSP protocol.
244
245 3.1.2 osp.conf
246   The /etc/asterisk/osp.conf file, shown below, contains configuration 
247   parameters for using OSP.  Two parameters, servicepoint and source must be 
248   configured.  The default values for all other parameters will work well for 
249   standard OSP implementations.
250     ;
251     ; Open Settlement Protocol Sample Configuration File
252     ;
253     ; This file contains configuration of OSP server providers that
254     ; are used by the Asterisk OSP module.  The section "general" is 
255     ; reserved for global options.  All other sections describe specific 
256     ; OSP Providers.  The provider "default" is used when no provider is 
257     ; otherwise specified.
258     :
259     : The "servicepoint" and "source" parameters must be configured.  For
260     ; most implementations the other parameters in this file can be left 
261     ; unchanged.
262     ;
263     [general]
264     ;
265     ; Enable cryptographic acceleration hardware.  
266     ;
267     accelerate=no
268     ;
269     ; Defines the status of tokens that Asterisk will validate. 
270     ; 0 - signed tokens only 
271     ; 1 - unsigned tokens only 
272     ; 2 - both signed and unsigned
273     ; The default value is 0, i.e. the Asterisk will only validate signed
274     ; tokens.
275     ;
276     tokenformat=0
277     ;
278     [default]
279     ;
280     ; List all service points (OSP servers) for this provider.  Use 
281     ; either domain name or IP address.  Most OSP servers use port 1080.
282     ;
283     ;servicepoint=http://osptestserver.transnexus.com:1080/osp
284     servicepoint=http://OSP server IP:1080/osp
285     ;
286     ; Define the "source" device for requesting OSP authorization.
287     : This value is usually the domain name or IP address of the
288     : the Asterisk server.
289     ;
290     ;source=domain name or [IP address in brackets]
291     source=[host IP]
292     ;
293     ; Define path and file name of crypto files.
294     ; The default path for crypto file is /var/lib/asterisk/keys.  If no
295     ; path is defined, crypto files should be in  
296     ; /var/lib/asterisk/keys directory.
297     ;
298     ; Specify the private key file name.  
299     ; If this parameter is unspecified or not present, the default name 
300     ; will be the osp.conf section name followed by "-privatekey.pem" 
301     ; (for example: default-privatekey.pem)
302     ;
303     privatekey=pkey.pem
304     ;
305     ; Specify the local certificate file.  
306     ; If this parameter is unspecified or not present, the default name 
307     ; will be the osp.conf section name followed by "- localcert.pem " 
308     ; (for example: default-localcert.pem)
309     ;
310     localcert=localcert.pem
311     ;
312     ; Specify one or more Certificate Authority key file names.  If none 
313     ; are listed, a single Certificate Authority key file name is added 
314     ; with the default name of the osp.conf section name followed by 
315     ; "-cacert_0.pem " (for example: default-cacert_0.pem)
316     ;
317     cacert=cacert_0.pem
318     ;
319     ; Configure parameters for OSP communication between Asterisk OSP 
320     ; client and OSP servers. 
321     ;
322     ; maxconnections: Max number of simultaneous connections to the 
323     ;                 provider OSP server (default=20)
324     ; retrydelay:     Extra delay between retries (default=0)
325     ; retrylimit:     Max number of retries before giving up (default=2)
326     ; timeout:        Timeout for response in milliseconds (default=500)
327     ;
328     maxconnections=20
329     retrydelay=0
330     retrylimit=2
331     timeout=500
332     ;
333     ; Set the authentication policy.  
334     ; 0 - NO        - Accept all calls.
335     ; 1 - YES       - Accept calls with valid token or no token.
336     ;                  Block calls with invalid token.  
337     ; 2 - EXCLUSIVE - Accept calls with valid token.
338     ;                  Block calls with invalid token or no token.
339     ; Default is 1,
340     ;
341     authpolicy=1
342     ;
343     ; Set the default destination protocol. The OSP module supports 
344     ; SIP, H323, and IAX protocols.  The default protocol is set to SIP.
345     ;
346     defaultprotocol=SIP
347
348 3.1.3 extensions.conf
349   OSP functions are implemented as dial plan functions in the extensions.conf 
350   file.  To add OSP support to your Asterisk server, simply copy and paste the 
351   text box below to your extensions.conf file.  These functions will enable your 
352   Asterisk server to support all OSP call scenarios.  Configuration of your 
353   Asterisk server for OSP is now complete.
354     [globals]
355     DIALOUT=Zap/1
356     
357     [SrcGW]     ; OSP Source Gateway
358     exten => _XXXX.,1,NoOp(OSPSrcGW)
359     ; Set calling number if necessary
360     exten => _XXXX.,n,Set(CALLERID(numner)=1234567890)
361     ; OSP lookup using default provider, if fail/error jump to lookup+101
362     exten => _XXXX.,n(lookup),OSPLookup(${EXTEN}||j)
363     ; Deal with outbound call according to protocol
364     exten => _XXXX.,n,Macro(outbound)
365     ; Dial to destination, 60 timeout, with call duration limit
366     exten => _XXXX.,n,Dial(${OSPDIALSTR},60,oL($[${OSPOUTTIMELIMIT}*1000]))
367     ; Wait 1 second
368     exten => _XXXX.,n,Wait,1
369     ; Hangup
370     exten => _XXXX.,n,Hangup
371     ; Deal with OSPLookup fail/error
372     exten => _XXXX.,lookup+101,Hangup
373     exten => h,1,NoOp()
374     ; OSP report usage
375     exten => h,n,OSPFinish(${HANGUPCAUSE})
376     
377     [DstGW]     ; OSP Destination Gateway
378     exten => _XXXX.,1,NoOp(OSPDstGW)
379     ; Deal with inbound call according to protocol
380     exten => _XXXX.,n,Macro(inbound)
381     ; Validate token using default provider, if fail/error jump to auth+101
382     exten => _XXXX.,n(auth),OSPAuth(|j)
383     ; Ringing
384     exten => _XXXX.,n,Ringing
385     ; Wait 1 second
386     exten => _XXXX.,n,Wait,1
387     ; Check inbound call duration limit
388     exten => _XXXX.,n,GoToIf($[${OSPINTIMELIMIT}=0]?100:200)
389     ; Without duration limit
390     exten => _XXXX.,100,Dial(${DIALOUT},15,o)
391     exten => _XXXX.,n,Goto(1000)
392     ; With duration limit
393     exten => _XXXX.,200,Dial(${DIALOUT},15,oL($[${OSPINTIMELIMIT}*1000]))
394     exten => _XXXX.,n,Goto(1000)
395     ; Wait 1 second
396     exten => _XXXX.,1000,Wait,1
397     ; Hangup
398     exten => _XXXX.,n,Hangup
399     ; Deal with OSPAuth fail/error
400     exten => _XXXX.,auth+101,Hangup
401     exten => h,1,NoOp()
402     ; OSP report usage
403     exten => h,n,OSPFinish(${HANGUPCAUSE})
404     
405     [GeneralProxy]      ; Proxy
406     exten => _XXXX.,1,NoOp(OSP-GeneralProxy)
407     ; Deal with inbound call according to protocol
408     exten => _XXXX.,n,Macro(inbound)
409     ; Validate token using default provider, if fail/error jump to auth+101
410     exten => _XXXX.,n(auth),OSPAuth(|j)
411     ; OSP lookup using default provider, if fail/error jump to lookup+101
412     exten => _XXXX.,n(lookup),OSPLookup(${EXTEN}||j)
413     ; Deal with outbound call according to protocol
414     exten => _XXXX.,n,Macro(outbound)
415     ; Dial to destination, 14 timeout, with call duration limit
416     exten => _XXXX.,n,Dial(${OSPDIALSTR},14,oL($[${OSPOUTTIMELIMIT}*1000]))
417     ; OSP lookup next destination using default provider, if fail/error jump to next1+101
418     exten => _XXXX.,n(next1),OSPNext(${HANGUPCAUSE}||j)
419     ; Deal with outbound call according to protocol
420     exten => _XXXX.,n,Macro(outbound)
421     ; Dial to destination, 15 timeout, with call duration limit
422     exten => _XXXX.,n,Dial(${OSPDIALSTR},15,oL($[${OSPOUTTIMELIMIT}*1000]))
423     ; OSP lookup next destination using default provider, if fail/error jump to next2+101
424     exten => _XXXX.,n(next2),OSPNext(${HANGUPCAUSE}||j)
425     ; Deal with outbound call according to protocol
426     exten => _XXXX.,n,Macro(outbound)
427     ; Dial to destination, 16 timeout, with call duration limit
428     exten => _XXXX.,n,Dial(${OSPDIALSTR},16,oL($[${OSPOUTTIMELIMIT}*1000]))
429     ; Hangup
430     exten => _XXXX.,n,Hangup
431     ; Deal with OSPAuth fail/error
432     exten => _XXXX.,auth+101,Hangup
433     ; Deal with OSPLookup fail/error
434     exten => _XXXX.,lookup+101,Hangup
435     ; Deal with OSPNext fail/error
436     exten => _XXXX.,next1+101,Hangup
437     ; Deal with OSPNext fail/error
438     exten => _XXXX.,next2+101,Hangup
439     exten => h,1,NoOp()
440     ; OSP report usage
441     exten => h,n,OSPFinish(${HANGUPCAUSE})
442     
443     [macro-inbound]
444     exten => s,1,NoOp(inbound)
445     ; Get inbound protocol
446     exten => s,n,Set(CHANTECH=${CUT(CHANNEL,/,1)})
447     exten => s,n,GoToIf($["${CHANTECH}"="H323"]?100)
448     exten => s,n,GoToIf($["${CHANTECH}"="IAX2"]?200)
449     exten => s,n,GoToIf($["${CHANTECH}"="SIP"]?300)
450     exten => s,n,GoTo(1000)
451     ; H323 --------------------------------------------------------
452     ; Get peer IP
453     exten => s,100,Set(OSPPEERIP=${H323CHANINFO(peerip)})
454     ; Get OSP token
455     exten => s,n,Set(OSPINTOKEN=${H323CHANINFO(osptoken)})
456     exten => s,n,GoTo(1000)
457     ; IAX ----------------------------------------------------------
458     ; Get peer IP
459     exten => s,200,Set(OSPPEERIP=${IAXPEER(CURRENTCHANNEL)})
460     ; Get OSP token
461     exten => s,n,Set(OSPINTOKEN=${IAXCHANINFO(osptoken)})
462     exten => s,n,GoTo(1000)
463     ; SIP ----------------------------------------------------------
464     ; Get peer IP
465     exten => s,300,Set(OSPPEERIP=${SIPCHANINFO(peerip)})
466     ; Get OSP token
467     exten => s,n,Set(OSPINTOKEN=${SIP_HEADER(P-OSP-Auth-Token)})
468     exten => s,n,GoTo(1000)
469     ; --------------------------------------------------------------
470     exten => s,1000,MacroExit
471     
472     [macro-outbound]
473     exten => s,1,NoOp(outbound)
474     ; Set calling number which may be translated
475     exten => s,n,Set(CALLERID(number)=${OSPCALLING})
476     ; Check destinatio protocol
477     exten => s,n,GoToIf($["${OSPTECH}"="H323"]?100)
478     exten => s,n,GoToIf($["${OSPTECH}"="IAX2"]?200)
479     exten => s,n,GoToIf($["${OSPTECH}"="SIP"]?300)
480     ; Something wrong
481     exten => s,n,Hangup
482     exten => s,n,GoTo(1000)
483     ; H323 --------------------------------------------------------
484     ; Set call id
485     exten => s,100,Set(H323CHANINFO(callid)=${OSPOUTCALLID})
486     ; Set OSP token
487     exten => s,n,Set(H323CHANINFO(osptoken)=${OSPOUTTOKEN})
488     exten => s,n,GoTo(1000)
489     ; IAX ----------------------------------------------------------
490     ; Set OSP token
491     exten => s,200,Set(IAXCHANINFO(osptoken)=${OSPOUTTOKEN})
492     exten => s,n,GoTo(1000)
493     ; SIP ----------------------------------------------------------
494     exten => s,300,GoTo(1000)
495     ; --------------------------------------------------------------
496     exten => s,1000,MacroExit
497
498 3.1.4 zapata/sip/iax/h323/ooh323.conf
499   There is no configuration required for OSP.
500
501 3.2 OSP Dial Plan Functions
502   This section provides a description of each OSP dial plan function.
503
504 3.2.1 OSPAuth 
505   OSP token validation function.
506   Input:
507   * OSPPEERIP: last hop IP address
508   * OSPINTOKEN: inbound OSP token
509   * provider: OSP service provider configured in osp.conf. If it is empty, default provider is used.
510   * priority jump
511   Output:
512   * OSPINHANDLE: inbound OSP transaction handle
513   * OSPINTIMELIMIT: inbound call duration limit
514   * OSPAUTHSTATUS: OSPAuth return value. SUCCESS/FAILED/ERROR
515
516 3.2.2 OSPLookup
517   OSP lookup function.
518   Input:
519   * OSPPEERIP: last hop IP address
520   * OSPINHANDLE: inbound OSP transaction handle
521   * OSPINTIMELIMIT: inbound call duration limit 
522   * exten: called number
523   * provider: OSP service provider configured in osp.conf. If it is empty, default provider is used.
524   * priority jump
525   * callidtypes: Generate call ID for the outbound call. h: H.323; s: SIP; i: IAX. Only h, H.323, has been implemented.
526   Output:
527   * OSPOUTHANDLE: outbound transaction handle
528   * OSPTECH: outbound protocol
529   * OSPDEST: outbound destination IP address
530   * OSPCALLED: outbound called nummber
531   * OSPCALLING: outbound calling number
532   * OSPOUTTOKEN: outbound OSP token
533   * OSPRESULTS: number of remaining destinations
534   * OSPOUTTIMELIMIT: outbound call duration limit
535   * OSPOUTCALLIDTYPES: same as input callidtypes
536   * OSPOUTCALLID: outbound call ID. Only for H.323
537   * OSPDIALSTR: outbound dial string
538   * OSPLOOKUPSTATUS: OSPLookup return value. SUCCESS/FAILED/ERROR
539
540 3.2.3 OSPNext
541   OSP lookup next function.
542   Input:
543   * OSPINHANDLE: inbound transaction handle
544   * OSPOUTHANDLE: outbound transaction handle
545   * OSPINTIMELIMIT: inbound call duration limit 
546   * OSPOUTCALLIDTYPES: types of call ID generated by Asterisk.
547   * OSPRESULTS: number of remain destinations
548   * cause: last destination disconnect cause
549   * priority jump
550   Output:
551   * OSPTECH: outbound protocol
552   * OSPDEST: outbound destination IP address
553   * OSPCALLED: outbound called number
554   * OSPCALLING: outbound calling number
555   * OSPOUTTOKEN: outbound OSP token
556   * OSPRESULTS: number of remain destinations
557   * OSPOUTTIMELIMIT: outbound call duration limit
558   * OSPOUTCALLID: outbound call ID. Only for H.323
559   * OSPDIALSTR: outbound dial string
560   * OSPNEXTSTATUS: OSPLookup return value. SUCCESS/FAILED/ERROR
561
562 3.2.4 OSPFinish
563   OSP report usage function.
564   Input:
565   * OSPINHANDLE: inbound transaction handle
566   * OSPOUTHANDLE: outbound transaction handle
567   * OSPAUTHSTATUS: OSPAuth return value
568   * OSPLOOKUPTSTATUS: OSPLookup return value
569   * OSPNEXTSTATUS: OSPNext return value
570   * cause: last destination disconnect cause
571   * priority jump
572   Output:
573   * OSPFINISHSTATUS: OSPLookup return value. SUCCESS/FAILED/ERROR
574
575 3.3 extensions.conf Examples
576   The extensions.conf file example provided in Section 3.1 is designed to 
577   handle all OSP call scenarios when Asterisk is used as a source or destination 
578   gateway to the PSTN or as a proxy between VoIP networks.  The extenstion.conf 
579   examples in this section are designed for specific use cases only.
580
581 3.3.1 Source Gateway
582   The examples in this section apply when the Asterisk server is being used as 
583   a TDM to VoIP gateway.  Calls originate on the TDM network and are converted 
584   to VoIP by Asterisk.  In these cases, the Asterisk server queries an OSP 
585   server to find a route to a VoIP destination.  When the call ends, Asterisk 
586   sends a CDR to the OSP server.
587   For SIP protocol.
588     [SIPSrcGW]
589     exten => _XXXX.,1,NoOp(SIPSrcGW)
590     ; Set calling number if necessary
591     exten => _XXXX.,n,Set(CALLERID(numner)=CallingNumber)
592     ; OSP lookup using default provider, if fail/error jump to lookup+101
593     exten => _XXXX.,n(lookup),OSPLookup(${EXTEN}||j)
594     ; Set calling number which may be translated 
595     exten => _XXXX.,n,Set(CALLERID(number)=${OSPCALLING})
596     ; Dial to destination, 60 timeout, with call duration limit
597     exten => _XXXX.,n,Dial(${OSPDIALSTR},60,oL($[${OSPOUTTIMELIMIT}*1000]))
598     ; Wait 3 seconds
599     exten => _XXXX.,n,Wait,3
600     ; Hangup
601     exten => _XXXX.,n,Hangup
602     ; Deal with OSPLookup fail/error
603     exten => _XXXX.,lookup+101,Hangup
604     exten => h,1,NoOp()
605     ; OSP report usage
606     exten => h,n,OSPFinish(${HANGUPCAUSE})
607   For IAX protocol.
608     [IAXSrcGW]
609     exten => _XXXX.,1,NoOp(IAXSrcGW)
610     ; Set calling number if necessary
611     exten => _XXXX.,n,Set(CALLERID(numner)=CallingNumber)
612     ; OSP lookup using default provider, if fail/error jump to lookup+101
613     exten => _XXXX.,n(lookup),OSPLookup(${EXTEN}||j)
614     ; Set outbound OSP token
615     exten => _XXXX.,n,Set(IAXCHANINFO(osptoken)=${OSPOUTTOKEN})
616     ; Set calling number which may be translated 
617     exten => _XXXX.,n,Set(CALLERID(number)=${OSPCALLING})
618     ; Dial to destination, 60 timeout, with call duration limit
619     exten => _XXXX.,n,Dial(${OSPDIALSTR},60,oL($[${OSPOUTTIMELIMIT}*1000]))
620     ; Wait 3 seconds
621     exten => _XXXX.,n,Wait,3
622     ; Hangup
623     exten => _XXXX.,n,Hangup
624     ; Deal with OSPLookup fail/error
625     exten => _XXXX.,lookup+101,Hangup
626     exten => h,1,NoOp()
627     ; OSP report usage
628     exten => h,n,OSPFinish(${HANGUPCAUSE})
629   For H.323 protocol.
630     [H323SrcGW]
631     exten => _XXXX.,1,NoOp(H323SrcGW)
632     ; Set calling number if necessary
633     exten => _XXXX.,n,Set(CALLERID(numner)=CallingNumber)
634     ; OSP lookup using default provider, if fail/error jump to lookup+101
635     ; "h" parameter is used to generate a call id
636     ; Cisco OSP gateways use this call id to validate OSP token
637     exten => _XXXX.,n(lookup),OSPLookup(${EXTEN}||jh)
638     ; Set outbound call id
639     exten => _XXXX.,n,Set(OH323CHANINFO(callid)=${OSPOUTCALLID})
640     ; Set outbound OSP token
641     exten => _XXXX.,n,Set(OH323CHANINFO(osptoken)=${OSPOUTTOKEN})
642     ; Set calling number which may be translated 
643     exten => _XXXX.,n,Set(CALLERID(number)=${OSPCALLING})
644     ; Dial to destination, 60 timeout, with call duration limit
645     exten => _XXXX.,n,Dial(${OSPDIALSTR},60,oL($[${OSPOUTTIMELIMIT}*1000]))
646     ; Wait 3 seconds
647     exten => _XXXX.,n,Wait,3
648     ; Hangup
649     exten => _XXXX.,n,Hangup
650     ; Deal with OSPLookup fail/error
651     exten => _XXXX.,lookup+101,Hangup
652     exten => h,1,NoOp()
653     ; OSP report usage
654     exten => h,n,OSPFinish(${HANGUPCAUSE})
655
656 3.3.2 Destination Gateway
657   The examples in this section apply when Asterisk is being used as a VoIP to 
658   TDM gateway.  VoIP calls are received by Asterisk which validates the OSP 
659   peering token and completes to the TDM network.  After the call ends, 
660   Asterisk sends a CDR to the OSP server.
661   For SIP protocol
662     [SIPDstGW]
663     exten => _XXXX.,1,NoOp(SIPDstGW)
664     ; Get peer IP
665     exten => _XXXX.,n,Set(OSPPEERIP=${SIPCHANINFO(peerip)})
666     ; Get OSP token
667     exten => _XXXX.,n,Set(OSPINTOKEN=${SIP_HEADER(P-OSP-Auth-Token)})
668     ; Validate token using default provider, if fail/error jump to auth+101
669     exten => _XXXX.,n(auth),OSPAuth(|j)
670     ; Ringing
671     exten => _XXXX.,n,Ringing
672     ; Wait 1 second
673     exten => _XXXX.,n,Wait,1
674     ; Dial phone, timeout 15 seconds, with call duration limit
675     exten => _XXXX.,n,Dial(${DIALOUTANALOG}/${EXTEN:1},15,oL($[${OSPINTIMELIMIT}*1000]))
676     ; Wait 3 seconds
677     exten => _XXXX.,n,Wait,3
678     ; Hangup
679     exten => _XXXX.,n,Hangup
680     ; Deal with OSPAuth fail/error
681     exten => _XXXX.,auth+101,Hangup
682     exten => h,1,NoOp()
683     ; OSP report usage
684     exten => h,n,OSPFinish(${HANGUPCAUSE})
685   For IAX protocol
686     [IAXDstGW]
687     exten => _XXXX.,1,NoOp(IAXDstGW)
688     ; Get peer IP
689     exten => _XXXX.,n,Set(OSPPEERIP=${IAXPEER(CURRENTCHANNEL)})
690     ; Get OSP token
691     exten => _XXXX.,n,Set(OSPINTOKEN=${IAXCHANINFO(osptoken)})
692     ; Validate token using default provider, if fail/error jump to auth+101
693     exten => _XXXX.,n(auth),OSPAuth(|j)
694     ; Ringing
695     exten => _XXXX.,n,Ringing
696     ; Wait 1 second
697     exten => _XXXX.,n,Wait,1
698     ; Dial phone, timeout 15 seconds, with call duration limit
699     exten => _XXXX.,n,Dial(${DIALOUTANALOG}/${EXTEN:1},15,oL($[${OSPINTIMELIMIT}*1000]))
700     ; Wait 3 seconds
701     exten => _XXXX.,n,Wait,3
702     ; Hangup
703     exten => _XXXX.,n,Hangup
704     ; Deal with OSPAuth fail/error
705     exten => _XXXX.,auth+101,Hangup
706     exten => h,1,NoOp()
707     ; OSP report usage
708     exten => h,n,OSPFinish(${HANGUPCAUSE})
709   For H.323 protocol
710     [H323DstGW]
711     exten => _XXXX.,1,NoOp(H323DstGW)
712     ; Get peer IP
713     exten => _XXXX.,n,Set(OSPPEERIP=${H323CHANINFO(peerip)})
714     ; Get OSP token
715     exten => _XXXX.,n,Set(OSPINTOKEN=${H323CHANINFO(osptoken)})
716     ; Validate token using default provider, if fail/error jump to auth+101
717     exten => _XXXX.,n(auth),OSPAuth(|j)
718     ; Ringing
719     exten => _XXXX.,n,Ringing
720     ; Wait 1 second
721     exten => _XXXX.,n,Wait,1
722     ; Dial phone, timeout 15 seconds, with call duration limit
723     exten => _XXXX.,n,Dial(${DIALOUTANALOG}/${EXTEN:1},15,oL($[${OSPINTIMELIMIT}*1000]))
724     ; Wait 3 seconds
725     exten => _XXXX.,n,Wait,3
726     ; Hangup
727     exten => _XXXX.,n,Hangup
728     ; Deal with OSPAuth fail/error
729     exten => _XXXX.,auth+101,Hangup
730     exten => h,1,NoOp()
731     ; OSP report usage
732     exten => h,n,OSPFinish(${HANGUPCAUSE})
733
734 3.3.3 Proxy
735   The example in this section applies when Asterisk is a proxy between two VoIP networks.
736     [GeneralProxy]
737     exten => _XXXX.,1,NoOp(GeneralProxy)
738     ; Get peer IP and inbound OSP token
739     ; SIP, un-comment the following two lines.
740     ;exten => _XXXX.,n,Set(OSPPEERIP=${SIPCHANINFO(peerip)})
741     ;exten => _XXXX.,n,Set(OSPINTOKEN=${SIP_HEADER(P-OSP-Auth-Token)})
742     ; IAX, un-comment the following 2 lines
743     ;exten => _XXXX.,n,Set(OSPPEERIP=${IAXPEER(CURRENTCHANNEL)})
744     ;exten => _XXXX.,n,Set(OSPINTOKEN=${IAXCHANINFO(osptoken)})
745     ; H323, un-comment the following two lines.
746     ;exten => _XXXX.,n,Set(OSPPEERIP=${OH323CHANINFO(peerip)})
747     ;exten => _XXXX.,n,Set(OSPINTOKEN=${OH323CHANINFO(osptoken)})
748     ;---------------------------------------------------------------
749     ; Validate token using default provider, if fail/error jump to auth+101
750     exten => _XXXX.,n(auth),OSPAuth(|j)
751     ; OSP lookup using default provider, if fail/error jump to lookup+101
752     ; "h" parameter is used to generate a call id for H.323 destinations
753     ; Cisco OSP gateways use this call id to validate OSP token
754     exten => _XXXX.,n(lookup),OSPLookup(${EXTEN}||jh)
755     ; Set outbound call id and OSP token
756     ; IAX, un-comment the following line. 
757     ;exten => _XXXX.,n,Set(IAXCHANINFO(osptoken)=${OSPOUTTOKEN})
758     ; H323, un-comment the following two lines. 
759     ;exten => _XXXX.,n,Set(OH323CHANINFO(callid)=${OSPOUTCALLID})
760     ;exten => _XXXX.,n,Set(OH323CHANINFO(osptoken)=${OSPOUTTOKEN})
761     ;---------------------------------------------------------------
762     ; Set calling number which may be translated 
763     exten => _XXXX.,n,Set(CALLERID(number)=${OSPCALLING})
764     ; Dial to destination, 14 timeout, with call duration limit
765     exten => _XXXX.,n,Dial(${OSPDIALSTR},14,oL($[${OSPOUTTIMELIMIT}*1000]))
766     ; OSP lookup next destination using default provider, if fail/error jump to next1+101
767     exten => _XXXX.,n(next1),OSPNext(${HANGUPCAUSE}||j)
768     ; Set outbound call id and OSP token
769     ; IAX, un-comment the following line. 
770     ;exten => _XXXX.,n,Set(IAXCHANINFO(osptoken)=${OSPOUTTOKEN})
771     ; H323, un-comment the following two lines.
772     ;exten => _XXXX.,n,Set(OH323CHANINFO(callid)=${OSPOUTCALLID})
773     ;exten => _XXXX.,n,Set(OH323CHANINFO(osptoken)=${OSPOUTTOKEN})
774     ;---------------------------------------------------------------
775     ; Set calling number which may be translated 
776     exten => _XXXX.,n,Set(CALLERID(number)=${OSPCALLING})
777     ; Dial to destination, 15 timeout, with call duration limit
778     exten => _XXXX.,n,Dial(${OSPDIALSTR},15,oL($[${OSPOUTTIMELIMIT}*1000]))
779     ; OSP lookup next destination using default provider, if fail/error jump to next2+101
780     exten => _XXXX.,n(next2),OSPNext(${HANGUPCAUSE}||j)
781     ; Set outbound call id and OSP token
782     ; IAX, un-comment the following line. 
783     ;exten => _XXXX.,n,Set(IAXCHANINFO(osptoken)=${OSPOUTTOKEN})
784     ; H323, un-comment the following two lines.
785     ;exten => _XXXX.,n,Set(OH323CHANINFO(callid)=${OSPOUTCALLID})
786     ;exten => _XXXX.,n,Set(OH323CHANINFO(osptoken)=${OSPOUTTOKEN})
787     ;---------------------------------------------------------------
788     ; Set calling number which may be translated 
789     exten => _XXXX.,n,Set(CALLERID(number)=${OSPCALLING})
790     ; Dial to destination, 16 timeout, with call duration limit
791     exten => _XXXX.,n,Dial(${OSPDIALSTR},16,oL($[${OSPOUTTIMELIMIT}*1000]))
792     ; Hangup
793     exten => _XXXX.,n,Hangup
794     ; Deal with OSPAuth fail/error
795     exten => _XXXX.,auth+101,Hangup
796     ; Deal with OSPLookup fail/error
797     exten => _XXXX.,lookup+101,Hangup
798     ; Deal with 1st OSPNext fail/error
799     exten => _XXXX.,next1+101,Hangup
800     ; Deal with 2nd OSPNext fail/error
801     exten => _XXXX.,next2+101,Hangup
802     exten => h,1,NoOp()
803     ; OSP report usage
804     exten => h,n,OSPFinish(${HANGUPCAUSE})