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