doc/osp.txt

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