Browse code

Copied files from cvs.berlios.de:/cvsroot/osp-module

git-svn-id: https://openser.svn.sourceforge.net/svnroot/openser/trunk@366 689a6050-402a-0410-94f2-e92a70836424

Dmitry Isakbayev authored on 07/11/2005 16:42:34
Showing 30 changed files
1 1
new file mode 100644
... ...
@@ -0,0 +1,17 @@
1
+
2
+# osp module makefile
3
+
4
+# WARNING: do not run this directly, it should be run by the master Makefile
5
+
6
+include ../../Makefile.defs
7
+auto_gen=
8
+NAME=osp.so
9
+DEFS+=-D_POSIX_THREADS
10
+
11
+LIBS=$(shell if [ -f /usr/local/lib/libosptk.a ]; then echo "-losptk" ; else echo "-losp" ; fi)
12
+LIBS+=-lssl -lcrypto -lpthread -lm
13
+
14
+
15
+
16
+include ../../Makefile.modules
17
+
0 18
new file mode 100644
... ...
@@ -0,0 +1,632 @@
1
+                                   OSP Module
2
+
3
+  Ulrich Abend
4
+
5
+   FhG Fokus
6
+
7
+    Edited by
8
+
9
+  Di-Shi Sun
10
+
11
+   Copyright (c) 2003 FhG Fokus
12
+
13
+   ---------------------------------------------------------------------------
14
+
15
+   Table of Contents
16
+
17
+   [1]User's Guide
18
+
19
+                [2]Overview
20
+
21
+                [3]Dependencies
22
+
23
+                [4]Exported Parameters
24
+
25
+                             [5]sp1_uri (string), sp2_uri (string)
26
+
27
+                             [6]sp1_weight (integer), sp2_weight (integer)
28
+
29
+                             [7]device_ip (string)
30
+
31
+                             [8]device_port (string)
32
+
33
+                             [9]private_key (string)
34
+
35
+                             [10]local_certificate (string)
36
+
37
+                             [11]ca_certificates (string)
38
+
39
+                             [12]token_format (integer)
40
+
41
+                             [13]enable_crypto_hardware_support (integer)
42
+
43
+                             [14]ssl_lifetime (integer)
44
+
45
+                             [15]persistence (integer)
46
+
47
+                             [16]retry_delay (integer)
48
+
49
+                             [17]retry_limit (integer)
50
+
51
+                             [18]timeout (integer)
52
+
53
+                             [19]max_destinations (integer)
54
+
55
+                             [20]validate_call_id (integer)
56
+
57
+                [21]Exported Functions
58
+
59
+                             [22]checkospheader()
60
+
61
+                             [23]validateospheader()
62
+
63
+                             [24]requestosprouting()
64
+
65
+                             [25]preparefirstosproute()
66
+
67
+                             [26]preparenextosproute()
68
+
69
+                             [27]prepareallosproute()
70
+
71
+                             [28]reportospusage()
72
+
73
+   [29]Developer's Guide
74
+
75
+   [30]Frequently Asked Questions
76
+
77
+   ---------------------------------------------------------------------------
78
+
79
+                                  User's Guide
80
+
81
+Overview
82
+
83
+   This module implements the client part of the Open Settlement Protocol
84
+   (OSP) defined by ETSI (ETSI TS 101 321 V4.1.1). OSP can be used to request
85
+   a validation, request a route and validate a request.
86
+
87
+   This module has been tested with the OSP server from TransNexus
88
+   (www.transnexus.com).
89
+
90
+   ---------------------------------------------------------------------------
91
+
92
+Dependencies
93
+
94
+   The module depends on the following modules (in the other words, the
95
+   listed modules must be loaded before this module):
96
+
97
+     * textops -- text based operation
98
+
99
+   ---------------------------------------------------------------------------
100
+
101
+Exported Parameters
102
+
103
+  sp1_uri (string), sp2_uri (string)
104
+
105
+   Defines the one or two OSP servers to be used for requesting authorization
106
+   and routing information. One OSP server MUST be configured. sp2_uri is
107
+   required only if there are two OSP servers.
108
+
109
+   This parameter has no default value and must be specified. To use a test
110
+   server hosted by TransNexus, send an email to support@transnexus.com and
111
+   request an account. Each service point takes the form of a standard URL,
112
+   and may consist of up to four components:
113
+
114
+     * An optional indication of the protocol to be used for communicating
115
+       with the service point. Both HTTP and HTTP secured with SSL are
116
+       supported; they are indicated by "http://" and "https://"
117
+       respectively. If the protocol is not explicitly indicated, the Toolkit
118
+       defaults to HTTP secured with SSL.
119
+
120
+     * The Internet domain name for the service point. Raw IP addresses may
121
+       also be used, provided they are enclosed in square brackets such as
122
+       "[172.16.1.1]".
123
+
124
+     * An optional TCP port number for communicating with the service point.
125
+       If the port number is omitted, the Toolkit defaults to port 1080 (for
126
+       HTTP) or port 1443 (for HTTP secured with SSL).
127
+
128
+     * The uniform resource identifier for requests to the service point.
129
+       This component is not optional and must be included.
130
+
131
+   Example 1. Setting the OSP server
132
+
133
+   modparam ("osp", "sp1_uri", "http://osptestserver.transnexus.com:1080/osp") 
134
+                                                                               
135
+
136
+   ---------------------------------------------------------------------------
137
+
138
+  sp1_weight (integer), sp2_weight (integer)
139
+
140
+   The number of messages that can be sent over each connection to the
141
+   various service points configured. This variable can be used to load
142
+   balance messages across a set of OSP servers.
143
+
144
+   Default value is set to 0.
145
+
146
+   Example 2. Setting the OSP server weight
147
+
148
+   modparam ("osp", "sp1_weight", 0)                                          
149
+                                                                              
150
+
151
+   ---------------------------------------------------------------------------
152
+
153
+  device_ip (string)
154
+
155
+   This is an optional field; if configured the information is sent out as
156
+   "SourceAlternate/transport" in the OSP message.
157
+
158
+   Example 3. Setting the device IP address
159
+
160
+   modparam ("osp", "device_ip", "[1.1.1.1]")                                 
161
+                                                                              
162
+
163
+   ---------------------------------------------------------------------------
164
+
165
+  device_port (string)
166
+
167
+   This is an optional field; if configured the information is sent out as
168
+   "SourceAlternate/network" in the OSP message.
169
+
170
+   Example 4. Setting the device port
171
+
172
+   modparam ("osp", "device_port", "5060")                                    
173
+                                                                              
174
+
175
+   ---------------------------------------------------------------------------
176
+
177
+  private_key (string)
178
+
179
+   Defines the private key owned by this device. The crypto files are used
180
+   for validating OSP authorization tokens and establishing a secure channel
181
+   between the Proxy and OSP server using SSL. The files can be generated
182
+   using an enrollment process and the utility 'enroll' from the OSP Toolkit.
183
+   By default, the proxy will look for pkey.pem, localcert.pem, and
184
+   cacart_0.pem in the default configuration directory. The default
185
+   configuration directory is set at compile time using CFG_DIR and defaults
186
+   to /usr/local/etc/ser/.
187
+
188
+   Test files are distributed with the module in the osp/etc folder. You can
189
+   copy the files to the expected location and/or change the parameters.
190
+
191
+   This parameter defaults to "/usr/local/etc/ser/pkey.pem", if the default
192
+   CFG_DIR value was used at compile time.
193
+
194
+   Example 5. Setting the private key
195
+
196
+   modparam ("osp", "private_key", "/usr/local/etc/ser/pkey.pem")             
197
+                                                                              
198
+
199
+   ---------------------------------------------------------------------------
200
+
201
+  local_certificate (string)
202
+
203
+   Defines the local certificate of this device. The crypto files are used
204
+   for validating OSP authorization tokens and establishing a secure channel
205
+   between the Proxy and OSP server using SSL. The files can be generated
206
+   using an enrollment process and the utility 'enroll' from the OSP toolkit.
207
+   By default, the proxy will look for pkey.pem, localcert.pem, and
208
+   cacart_0.pem in the default configuration directory. The default
209
+   configuration directory is set at compile time using CFG_DIR and defaults
210
+   to /usr/local/etc/ser/.
211
+
212
+   Test files are distributed with the module in the osp/etc folder. You can
213
+   copy the files to the expected location and/or change the parameters.
214
+
215
+   This parameter defaults to "/usr/local/etc/ser/localcert.pem", if the
216
+   default CFG_DIR value was used at compile time.
217
+
218
+   Example 6. Setting the local certificate
219
+
220
+   modparam ("osp", "local_certificate", "/usr/local/etc/ser/localcert.pem")  
221
+                                                                              
222
+
223
+   ---------------------------------------------------------------------------
224
+
225
+  ca_certificates (string)
226
+
227
+   Defines the CA certificate of the OSP server. The crypto files are used
228
+   for validating OSP authorization tokens and establishing a secure channel
229
+   between the Proxy and OSP server using SSL. The files can be generated
230
+   using an enrollment process and the utility 'enroll' from the OSP toolkit.
231
+   By default, the proxy will look for pkey.pem, localcert.pem, and
232
+   cacart_0.pem in the default configuration directory. The default
233
+   configuration directory is set at compile time using CFG_DIR and defaults
234
+   to /usr/local/etc/ser/.
235
+
236
+   Test files are distributed with the module in the osp/etc folder. You can
237
+   copy the files to the expected location and/or change the parameters.
238
+
239
+   This parameter defaults to "/usr/local/etc/ser/cacert.pem", if the default
240
+   CFG_DIR value was used at compile time.
241
+
242
+   Example 7. Setting the CA certificate
243
+
244
+   modparam ("osp", "ca_certificates", "/usr/local/etc/ser/cacert.pem")       
245
+                                                                              
246
+
247
+   ---------------------------------------------------------------------------
248
+
249
+  token_format (integer)
250
+
251
+   Defines the token format that the OSP module can validate. 0 - signed
252
+   tokens only, 1 - unsigned tokens only, 2 - both signed and unsigned.
253
+
254
+   This parameter is an optional field, the defaults to 2, i.e. the OSP
255
+   module can validate both signed and unsigned tokens.
256
+
257
+   Example 8. Setting the token format
258
+
259
+   modparam ("osp", "token_format", 2)                                        
260
+                                                                              
261
+
262
+   ---------------------------------------------------------------------------
263
+
264
+  enable_crypto_hardware_support (integer)
265
+
266
+   This is an optional field used to set cryptographic hardware acceleration
267
+   engine in the openssl library.
268
+
269
+   Default value is False (0). True is 1.
270
+
271
+   Example 9. Setting the hardware support
272
+
273
+   modparam ("osp", "enable_crypto_hardware_support", 0)                      
274
+                                                                              
275
+
276
+   ---------------------------------------------------------------------------
277
+
278
+  ssl_lifetime (integer)
279
+
280
+   The lifetime, in seconds, of a single SSL session key. Once this time
281
+   limit is exceeded, the Toolkit library will negotiate a new session key.
282
+   Communication exchanges in progress will not be interrupted when this time
283
+   limit expires.
284
+
285
+   This is an optional field with default value is 200 seconds.
286
+
287
+   Example 10. Setting the ssl lifetime
288
+
289
+   modparam ("osp", "ssl_lifetime", 200)                                      
290
+                                                                              
291
+
292
+   ---------------------------------------------------------------------------
293
+
294
+  persistence (integer)
295
+
296
+   The time, in seconds, that an HTTP connection should be maintained after
297
+   the completion of a communication exchange. The library will maintain the
298
+   connection for this time period in anticipation of future communication
299
+   exchanges to the same server.
300
+
301
+   This is an optional field with default value is 1000 seconds.
302
+
303
+   Example 11. Setting the persistence
304
+
305
+   modparam ("osp", "persistence", 1000)                                      
306
+                                                                              
307
+
308
+   ---------------------------------------------------------------------------
309
+
310
+  retry_delay (integer)
311
+
312
+   The time, in seconds, between retrying connection attempts to the
313
+   provider. After exhausting all service points for the provider, the
314
+   library will delay for this amount of time before resuming connection
315
+   attempts.
316
+
317
+   This is an optional field with default value is 1 second.
318
+
319
+   Example 12. Setting the retry delay
320
+
321
+   modparam ("osp", "retry_delay", 1)                                         
322
+                                                                              
323
+
324
+   ---------------------------------------------------------------------------
325
+
326
+  retry_limit (integer)
327
+
328
+   The maximum number of retries for connection attempts to the provider. If
329
+   no connection is established after this many retry attempts to all service
330
+   points, then the library will cease connection attempts and return
331
+   appropriate error codes. This number does not count the initial connection
332
+   attempt, so that a retry_limit of 1 will result in a total of two
333
+   connection attempts to every service point.
334
+
335
+   This is an optional field with default value is 2.
336
+
337
+   Example 13. Setting the retry limit
338
+
339
+   modparam ("osp", "retry_limit", 2)                                         
340
+                                                                              
341
+
342
+   ---------------------------------------------------------------------------
343
+
344
+  timeout (integer)
345
+
346
+   The maximum time in milliseconds, to wait for a response from a server. If
347
+   no response is received within this time, the current connection is
348
+   aborted and the library attempts to contact the next service point.
349
+
350
+   This is an optional field with default value is 10 seconds.
351
+
352
+   Example 14. Setting the timeout
353
+
354
+   modparam ("osp", "timeout", 10)                                            
355
+                                                                              
356
+
357
+   ---------------------------------------------------------------------------
358
+
359
+  max_destinations (integer)
360
+
361
+   The maximum number of destinations that the client wants the server to
362
+   return. Valid range is 1 through 5.
363
+
364
+   This is an optional field.
365
+
366
+   Example 15. Setting the number of destination
367
+
368
+   modparam ("osp", "max_destinations", 3)                                    
369
+                                                                              
370
+
371
+   ---------------------------------------------------------------------------
372
+
373
+  validate_call_id (integer)
374
+
375
+   Instructs the module to validate call id in the OSP token. Valid range is
376
+   0 (No) or 1 (Yes).
377
+
378
+   This is an optional field.
379
+
380
+   Default value is 1 (Yes).
381
+
382
+   Example 16. Instructing the module to validate call id
383
+
384
+   modparam ("osp", "validate_call_id", 1)                                    
385
+                                                                              
386
+
387
+   ---------------------------------------------------------------------------
388
+
389
+Exported Functions
390
+
391
+  checkospheader()
392
+
393
+   This function checks for the existence of the OSP-Auth-Token header field.
394
+
395
+   Example 17. checkospheader usage
396
+
397
+   ...                                                                        
398
+   if (checkospheader()) {                                                    
399
+     log("OSP header field found.\n");                                        
400
+   } else {                                                                   
401
+     log("no OSP header field present\n");                                    
402
+   };                                                                         
403
+   ...                                                                        
404
+                                                                              
405
+
406
+   ---------------------------------------------------------------------------
407
+
408
+  validateospheader()
409
+
410
+   This function validates an OSP-Token specified in the OSP-Auth-Token
411
+   header field of the SIP message. If a token is present, it will be
412
+   validated locally. If no OSP header is found or the header token is
413
+   invalid or expired, -1 is returned; on successful validation 1 is
414
+   returned.
415
+
416
+   Example 18. validateospheader usage
417
+
418
+   ...                                                                        
419
+   if (validateospheader()) {                                                 
420
+     log("valid OSP header found\n");                                         
421
+   } else {                                                                   
422
+     log("OSP header not found, invalid or expired\n");                       
423
+   };                                                                         
424
+   ...                                                                        
425
+                                                                              
426
+
427
+   ---------------------------------------------------------------------------
428
+
429
+  requestosprouting()
430
+
431
+   This function tries to acquire a valid call destination and an
432
+   authorization token from the OSP server. If the OSP server accepts the
433
+   request, an OSP-Auth-Token Header field is inserted into the SIP message
434
+   and the SIP uri is rewritten to the destination the OSP server sent to
435
+   this site.
436
+
437
+   The destination of the call must be a valid E164 number, otherwise this
438
+   function returns -1. If the transaction was accepted by the OSP server,
439
+   the uri is being rewritten and 1 returned, on errors (OSP service points
440
+   are not available, authentication failed or there is no route to
441
+   destination or the route is blocked) -1 is returned.
442
+
443
+   Example 19. requestosprouting usage
444
+
445
+   ...                                                                        
446
+   if (requestosprouting()) {                                                 
447
+     log("successfully queried OSP server, now relaying call\n");             
448
+   } else {                                                                   
449
+     log("Authorization request was rejected from OSP server\n");             
450
+   };                                                                         
451
+   ...                                                                        
452
+                                                                              
453
+
454
+   ---------------------------------------------------------------------------
455
+
456
+  preparefirstosproute()
457
+
458
+   This function tries to prepare the INVITE to be forwarded or redirected
459
+   using the first destination in the list returned by the OSP server. If the
460
+   route could not be prepared, the function returns 'FALSE' back to the
461
+   script, which can then decide how to handle the failure.
462
+
463
+   Example 20. preparefirstosproute usage
464
+
465
+   ...                                                                        
466
+   if (preparefirstosproute ()) {                                             
467
+     log("successfully prepared the first route, now relaying call\n");       
468
+   } else {                                                                   
469
+     log("could not prepare the route. The first destination was blocked\n"); 
470
+   };                                                                         
471
+   ...                                                                        
472
+                                                                              
473
+
474
+   ---------------------------------------------------------------------------
475
+
476
+  preparenextosproute()
477
+
478
+   Once the call could not be completed through the first destination, this
479
+   function tries to prepare the INVITE message using the next destination in
480
+   the list returned by the OSP Server. If it succeeds in preparing the
481
+   route, the message is either redirected or relayed on (using the t_relay
482
+   call), or else the function returns 'FALSE' back to the script, which can
483
+   then decide how to handle the failure.
484
+
485
+   Example 21. preparenextosproute usage
486
+
487
+   ...                                                                        
488
+   if (preparenextosproute ()) {                                              
489
+     log("successfully prepared the next route, now relaying call\n");        
490
+   } else {                                                                   
491
+     log("could not prepare the route. No next destination available\n");     
492
+   };                                                                         
493
+   ...                                                                        
494
+                                                                              
495
+
496
+   ---------------------------------------------------------------------------
497
+
498
+  prepareallosproute()
499
+
500
+   This function tries to prepare all the routes in the list returned by the
501
+   OSP server. The message is then either forked off or redirected to the
502
+   destination. If unsuccessful in preparing the routes a SIP 500 is sent
503
+   back and a trace message is logged.
504
+
505
+   Example 22. prepareallosproute usage
506
+
507
+...                                                                                      
508
+if (prepareallosproute ()) {                                                             
509
+  log("successfully prepared the routes, now either forking or redirecting the call\n"); 
510
+} else {                                                                                 
511
+  log("could not prepare the route. No destination available\n");                        
512
+};                                                                                       
513
+...                                                                                      
514
+                                                                                         
515
+
516
+   ---------------------------------------------------------------------------
517
+
518
+  reportospusage()
519
+
520
+   This function should be called after receiving a BYE message. If the
521
+   message contains an OSP cooky, the function will forward originating
522
+   and/or terminating duration usage information to an OSP server. The
523
+   function returns TRUE if the BYE includes an OSP cooky. The actual usage
524
+   message will be send on a different thread and will not delay BYE
525
+   processing. The function should be called before relaying the message.
526
+
527
+   Example 23. reportospusage usage
528
+
529
+...                                                                                                  
530
+if (reportospusage ()) {                                                                             
531
+  log("OSP call duration usage will be reported\n");                                                 
532
+} else {                                                                                             
533
+  log("The BYE message does not include OSP information, it was not authorized by an OSP server\n"); 
534
+};                                                                                                   
535
+...                                                                                                  
536
+                                                                                                     
537
+
538
+   ---------------------------------------------------------------------------
539
+
540
+                               Developer's Guide
541
+
542
+   Use of the osp modules' functions by other OpenSER modules is not useful.
543
+
544
+   ---------------------------------------------------------------------------
545
+
546
+                           Frequently Asked Questions
547
+
548
+   Q: [31]What platforms does this module work on?
549
+
550
+   Q: [32]Where can I get more information on this module?
551
+
552
+   Q: [33]Where can I get more information on OSP?
553
+
554
+   Q: [34]How do I obtain an OSP server for testing?
555
+
556
+   Q: [35]How are the exported functions used by the OSP module?
557
+
558
+   Q: What platforms does this module work on?
559
+
560
+   A: The module has been implemented using linux, the underlying toolkit and
561
+   the module code itself should compile and work on Solaris, *BSD, and
562
+   probably most other unix platforms with ssl and pthreads available, but
563
+   all platforms other than linux are completely untested.
564
+
565
+   Q: Where can I get more information on this module?
566
+
567
+   A: Please contact TransNexus by sending email to support@transnexus.com or
568
+   posting a message on email lists @
569
+   http://developer.berlios.de/mail/?group_id=3799 or at the sipfoundry
570
+   website (www.sipfoundry.org).
571
+
572
+   Q: Where can I get more information on OSP?
573
+
574
+   A: The OSP technical specification (ETSI TS 101 321) may be obtained from
575
+   www.etsi.org. Additional documentation on OSP is available from
576
+   www.sipfoundry.org.
577
+
578
+   Q: How do I obtain an OSP server for testing?
579
+
580
+   A: OSP servers are available from the following sources:
581
+
582
+     * OpenOSP server from www.sipfoundry.org is a complete OSP server
583
+       written in C.
584
+
585
+     * RAMS from www.sipfoundry.org is a new java based open source OSP
586
+       server project.
587
+
588
+     * TransNexus provides free access to a hosted OSP server on the Internet
589
+       for testing. Contact support@transnexus.com.
590
+
591
+   Q: How are the exported functions used by the OSP module?
592
+
593
+   A: See sample-osp-openser.cfg in modules/osp/etc for examples
594
+
595
+References
596
+
597
+   Visible links
598
+   1. file:///tmp/html-E15379#AEN24
599
+   2. file:///tmp/html-E15379#AEN31
600
+   3. file:///tmp/html-E15379#AEN35
601
+   4. file:///tmp/html-E15379#AEN42
602
+   5. file:///tmp/html-E15379#AEN44
603
+   6. file:///tmp/html-E15379#AEN62
604
+   7. file:///tmp/html-E15379#AEN71
605
+   8. file:///tmp/html-E15379#AEN78
606
+   9. file:///tmp/html-E15379#AEN85
607
+  10. file:///tmp/html-E15379#AEN94
608
+  11. file:///tmp/html-E15379#AEN103
609
+  12. file:///tmp/html-E15379#AEN112
610
+  13. file:///tmp/html-E15379#AEN120
611
+  14. file:///tmp/html-E15379#AEN128
612
+  15. file:///tmp/html-E15379#AEN136
613
+  16. file:///tmp/html-E15379#AEN144
614
+  17. file:///tmp/html-E15379#AEN152
615
+  18. file:///tmp/html-E15379#AEN160
616
+  19. file:///tmp/html-E15379#AEN168
617
+  20. file:///tmp/html-E15379#AEN176
618
+  21. file:///tmp/html-E15379#AEN185
619
+  22. file:///tmp/html-E15379#AEN187
620
+  23. file:///tmp/html-E15379#AEN194
621
+  24. file:///tmp/html-E15379#AEN201
622
+  25. file:///tmp/html-E15379#AEN209
623
+  26. file:///tmp/html-E15379#AEN216
624
+  27. file:///tmp/html-E15379#AEN223
625
+  28. file:///tmp/html-E15379#AEN230
626
+  29. file:///tmp/html-E15379#AEN237
627
+  30. file:///tmp/html-E15379#AEN245
628
+  31. file:///tmp/html-E15379#AEN254
629
+  32. file:///tmp/html-E15379#AEN259
630
+  33. file:///tmp/html-E15379#AEN264
631
+  34. file:///tmp/html-E15379#AEN269
632
+  35. file:///tmp/html-E15379#AEN281
0 633
new file mode 100644
... ...
@@ -0,0 +1,56 @@
1
+
2
+2005 July 23
3
+  Implemented routing and authorization validation.  The module can:
4
+   o Request authorization and routing information from an OSP server
5
+   o Use provided routes to:
6
+     o Redirect the originating UI to all routes OR
7
+     o Try all routes simultaneously using parallel forking OR
8
+     o Try routes in the order they were received using sequential forking
9
+   o Add and retrieve P-OSP-Auth-Token header
10
+   o Perform local validation of the P-OSP-Auth-Token
11
+
12
+2005 September 12
13
+   o Bug 4863 - the module will remove OSP Auth token from the incoming Invite
14
+     after validating the token and before forwarding Invite to the next hop.
15
+   o Bug 4891 - added a new flag 'validate_call_id' for disabling call id
16
+     validation in OSP tokens.  The value is optional, call id validation
17
+     can be turned off by setting the value to 0 (No).  It may be used for
18
+     interoperability issues with some OSP clients sending invalid call ids
19
+     in Authorization Requests.
20
+   o Bug 4986 - changed return value for 'prepareallosproutes' from
21
+     0 - stop routing logic to 1 - true
22
+   o Bug 5039 - changed return value for 'preparenextosproute' when there is
23
+     no more routes from 0 - stop routing logic to -1 - false
24
+   o Bug 5039 - changed return value for 'preparenextosproute' when there is
25
+   o Bug 4893 - sequential routing (in failure_route[1]) now checks for code 
26
+     487 (Canceled) before trying the next OSP route.
27
+   o Bug 4892 - removed trailing binary chars from some log messages.
28
+   o Bug 4987 - fixed a compile time error on Solaris
29
+   o Bug 4946 - added README file
30
+
31
+2005 September 26
32
+   o Bug 5094 - don't route the call if OSP token validation fails.
33
+   o Bug 5109 - send "100 Trying" message before requesting OSP routes.
34
+   o Bug 5111 - fixed typos in error messages.
35
+   o Bug 5153 - removed trailing binary chars from P-OSP-Auth-Token header
36
+                value.
37
+
38
+2005 October 3
39
+   o Report OSP usage indications after the call set-up and tear down
40
+     transactions complete.
41
+
42
+2005 October 11
43
+   o Report call set-up usage indication after receiving either 200 or 202.
44
+   o Report termination cause code for duration usage indications as 10,016
45
+     instead of 1,016.
46
+   o Improved error checking and logging.
47
+   o Bug 5366 - removed a memory leak in usage reporting logic.
48
+
49
+2005 November 4
50
+   o Bug 5110 and 5531 - Updated the sample configuration files to not
51
+     fail-over on 486 - user busy and 408 - user not available.
52
+   o Bug 5535 - The module will report call set-up usage details after
53
+     sending any final response code to UAC.
54
+
55
+2005 November 7
56
+   o Copied files from cvs.berlios.de:/cvsroot/osp-module
0 57
new file mode 100644
... ...
@@ -0,0 +1,354 @@
1
+/*
2
+ * openser osp module. 
3
+ *
4
+ * This module enables openser to communicate with an Open Settlement 
5
+ * Protocol (OSP) server.  The Open Settlement Protocol is an ETSI 
6
+ * defined standard for Inter-Domain VoIP pricing, authorization
7
+ * and usage exchange.  The technical specifications for OSP 
8
+ * (ETSI TS 101 321 V4.1.1) are available at www.etsi.org.
9
+ *
10
+ * Uli Abend was the original contributor to this module.
11
+ * 
12
+ * Copyright (C) 2001-2005 Fhg Fokus
13
+ *
14
+ * This file is part of openser, a free SIP server.
15
+ *
16
+ * openser is free software; you can redistribute it and/or modify
17
+ * it under the terms of the GNU General Public License as published by
18
+ * the Free Software Foundation; either version 2 of the License, or
19
+ * (at your option) any later version
20
+ *
21
+ * openser is distributed in the hope that it will be useful,
22
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
23
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
24
+ * GNU General Public License for more details.
25
+ *
26
+ * You should have received a copy of the GNU General Public License
27
+ * along with this program; if not, write to the Free Software
28
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
29
+ */
30
+
31
+
32
+
33
+
34
+
35
+#include "../../sr_module.h"
36
+#include "../../mem/mem.h"
37
+#include "../../usr_avp.h"
38
+#include "destination.h"
39
+#include "usage.h"
40
+#include <time.h>
41
+
42
+
43
+/* A list of destination URIs */
44
+str ORIG_OSPDESTS_LABEL = {"orig_osp_dests",14};
45
+str TERM_OSPDESTS_LABEL = {"term_osp_dests",14};
46
+
47
+
48
+static int saveDestination(osp_dest* dest, str* label);
49
+static osp_dest* getLastOrigDestination();
50
+static void recordCode(int code, osp_dest* dest);
51
+static int isTimeToReportUsage(int code);
52
+
53
+
54
+
55
+
56
+osp_dest* initDestination(osp_dest* dest) {
57
+
58
+	memset(dest,0,sizeof(osp_dest));
59
+
60
+	dest->sizeofcallid   =  sizeof(dest->callid);
61
+	dest->sizeoftoken    =  sizeof(dest->osptoken);
62
+
63
+	return dest;
64
+}
65
+
66
+
67
+int saveOrigDestination(osp_dest* dest) {
68
+	DBG("osp: Saving originating destination\n");
69
+
70
+	return saveDestination(dest,&ORIG_OSPDESTS_LABEL);
71
+}
72
+
73
+int saveTermDestination(osp_dest* dest) {
74
+	DBG("osp: Saving terminating destination\n");
75
+
76
+	return saveDestination(dest,&TERM_OSPDESTS_LABEL);
77
+}
78
+
79
+/** Save destination as an AVP
80
+ *  name - label
81
+ *  value - osp_dest wrapped in a string
82
+ *
83
+ *  Returns: 0 - success, -1 failure
84
+ */
85
+static int saveDestination(osp_dest* dest, str* label) {
86
+	str wrapper;
87
+	int status = -1;
88
+
89
+	DBG("osp: Saving destination to avp\n");
90
+
91
+	wrapper.s   = (char *)dest;
92
+	wrapper.len = sizeof(osp_dest);
93
+
94
+	/* add_avp will make a private copy of both the name and value in shared memory.
95
+	 * memory will be released by TM at the end of the transaction
96
+	 */
97
+	if (add_avp(AVP_NAME_STR|AVP_VAL_STR,(int_str)label,(int_str)&wrapper) == 0) {
98
+		status = 0;
99
+		DBG("osp: Saved\n");
100
+	} else {
101
+		LOG(L_ERR, "ERROR: osp: Failed to add_avp destination\n");
102
+	}
103
+
104
+	return status;
105
+}
106
+
107
+
108
+/** Retrieved an unused orig destination from an AVP
109
+ *  name - ORIG_OSPDESTS_LABEL
110
+ *  value - osp_dest wrapped in a string
111
+ *  There can be 0, 1 or more orig destinations.  Find the 1st unused destination (used==0),
112
+ *  return it, and mark it as used (used==1).
113
+ *
114
+ *  Returns: NULL on failure
115
+ */
116
+osp_dest* getNextOrigDestination() {
117
+	osp_dest*       retVal   = NULL;
118
+	osp_dest*       dest     = NULL;
119
+	struct usr_avp* dest_avp = NULL;
120
+	int_str         dest_val;
121
+
122
+	DBG("osp: Looking for the first unused orig destination\n");
123
+
124
+	for (	dest_avp=search_first_avp(AVP_NAME_STR|AVP_VAL_STR,(int_str)&ORIG_OSPDESTS_LABEL,NULL);
125
+		dest_avp != NULL;
126
+		dest_avp=search_next_avp(dest_avp,NULL)) {
127
+
128
+		get_avp_val(dest_avp, &dest_val);
129
+
130
+		/* osp dest is wrapped in a string */
131
+		dest = (osp_dest *)dest_val.s->s;
132
+
133
+		if (dest->used == 0) {
134
+			DBG("osp: Found\n");
135
+			break;
136
+		} else {
137
+			DBG("osp: This destination has already been used\n");
138
+		}
139
+	}
140
+
141
+	if (dest != NULL && dest->used==0) {
142
+		dest->used = 1;
143
+		retVal = dest;
144
+	} else {
145
+		DBG("osp: There is no unused destinations\n");
146
+	}
147
+
148
+	return retVal;
149
+}
150
+
151
+
152
+/** Retrieved the last used orig destination from an AVP
153
+ *  name - ORIG_OSPDESTS_LABEL
154
+ *  value - osp_dest wrapped in a string
155
+ *  There can be 0, 1 or more destinations.  Find the last used destination (used==1),
156
+ *  and return it.
157
+ *
158
+ *  Returns: NULL on failure
159
+ */
160
+osp_dest* getLastOrigDestination() {
161
+
162
+	osp_dest* dest = NULL;
163
+	osp_dest* last_dest = NULL;
164
+	struct usr_avp* dest_avp = NULL;
165
+	int_str   dest_val;
166
+
167
+	for (	dest_avp=search_first_avp(AVP_NAME_STR|AVP_VAL_STR,(int_str)&ORIG_OSPDESTS_LABEL,NULL);
168
+		dest_avp != NULL;
169
+		dest_avp=search_next_avp(dest_avp,NULL)) {
170
+
171
+		get_avp_val(dest_avp, &dest_val);
172
+
173
+		/* osp dest is wrapped in a string */
174
+		dest = (osp_dest *)dest_val.s->s;
175
+
176
+		if (dest->used == 1) {
177
+			last_dest = dest;
178
+			DBG("osp: getLastOrigDestination: updating curent destination to '%s'\n",last_dest->destination);
179
+		} else {
180
+			break;
181
+		}
182
+	}
183
+
184
+	return last_dest;
185
+}
186
+
187
+
188
+/** Retrieved the term destination from an AVP
189
+ *  name - TERM_OSPDESTS_LABEL
190
+ *  value - osp_dest wrapped in a string
191
+ *  There can be 0 or 1 term destinations.  Find and return it.
192
+ *
193
+ *  Returns: NULL on failure (no term destination)
194
+ */
195
+osp_dest* getTermDestination() {
196
+	osp_dest* term_dest = NULL;
197
+	struct usr_avp* dest_avp = NULL;
198
+	int_str   dest_val;
199
+
200
+	dest_avp=search_first_avp(AVP_NAME_STR|AVP_VAL_STR,(int_str)&TERM_OSPDESTS_LABEL,NULL);
201
+
202
+	if (dest_avp) {
203
+		get_avp_val(dest_avp, &dest_val);
204
+
205
+		/* osp dest is wrapped in a string */
206
+		term_dest = (osp_dest *)dest_val.s->s;
207
+	}
208
+
209
+	return term_dest;
210
+}
211
+
212
+
213
+
214
+
215
+void recordEvent(int client_code, int server_code) {
216
+	DBG("osp: recordEvent: client code %d / server code %d\n",client_code, server_code);
217
+
218
+	osp_dest* dest;
219
+
220
+	if (client_code!=0 && (dest=getLastOrigDestination())) {
221
+		recordCode(client_code,dest);
222
+
223
+		if (isTimeToReportUsage(server_code)==0) {
224
+			reportOrigCallSetUpUsage();
225
+		}
226
+	} 
227
+
228
+	if (server_code!=0 && (dest=getTermDestination())) {
229
+		recordCode(server_code,dest);
230
+
231
+		if (isTimeToReportUsage(server_code)==0) {
232
+			reportTermCallSetUpUsage();
233
+		}
234
+	}
235
+}
236
+
237
+
238
+
239
+static int isTimeToReportUsage(int code)
240
+{
241
+	int isTime = -1;
242
+
243
+	if (code >= 200) {
244
+		isTime = 0;
245
+	}
246
+
247
+	return isTime;
248
+}
249
+
250
+
251
+
252
+
253
+void recordCode(int code, osp_dest* dest) {
254
+
255
+	DBG("osp: recordCode: recording code %d\n",code);
256
+
257
+	dest->last_code = code;
258
+
259
+	switch (code) {
260
+		case 100:
261
+			if (!dest->time_100) {
262
+				dest->time_100 = time(NULL);
263
+			} else {
264
+				DBG("osp: recordCode: 100 has already been recorded\n");
265
+			}
266
+			break;
267
+		case 180:
268
+		case 181:
269
+		case 182:
270
+		case 183:
271
+			if (!dest->time_180) {
272
+				dest->time_180 = time(NULL);
273
+			} else {
274
+				DBG("osp: recordCode: 180, 181, 182 or 183 has allready been recorded\n");
275
+			}
276
+			break;
277
+		case 200:
278
+		case 202:
279
+			if (!dest->time_200) {
280
+				dest->time_200 = time(NULL);
281
+			} else {
282
+				DBG("osp: recordCode: 200 or 202 has allready been recorded\n");
283
+			}
284
+			break;
285
+		default:
286
+			DBG("osp: recordCode: will not record time for this code\n");
287
+	}
288
+
289
+}
290
+
291
+
292
+
293
+
294
+
295
+
296
+void dumpDebugInfo() {
297
+
298
+	osp_dest*       dest     = NULL;
299
+	struct usr_avp* dest_avp = NULL;
300
+	int_str         dest_val;
301
+	int             i = 0;
302
+
303
+	DBG("osp: dumpDebugInfo: IN\n");
304
+
305
+	for (	dest_avp=search_first_avp(AVP_NAME_STR|AVP_VAL_STR,(int_str)&ORIG_OSPDESTS_LABEL,NULL);
306
+		dest_avp != NULL;
307
+		dest_avp=search_next_avp(dest_avp,NULL)) {
308
+
309
+		get_avp_val(dest_avp, &dest_val);
310
+
311
+		/* osp dest is wrapped in a string */
312
+		dest = (osp_dest *)dest_val.s->s;
313
+
314
+		DBG("osp: dumpDebugInfo: .....orig index...'%d'\n", i);
315
+
316
+		dumbDestDebugInfo(dest);
317
+
318
+		i++;
319
+	}
320
+	if (i==0) {
321
+		DBG("osp: dumpDebugInfo: There is no orig OSPDESTS AVP\n");
322
+	}
323
+
324
+	dest_avp=search_first_avp(AVP_NAME_STR|AVP_VAL_STR,(int_str)&TERM_OSPDESTS_LABEL,NULL);
325
+
326
+	if (dest_avp) {
327
+		get_avp_val(dest_avp, &dest_val);
328
+
329
+		/* osp dest is wrapped in a string */
330
+		dest = (osp_dest *)dest_val.s->s;
331
+
332
+		DBG("osp: dumpDebugInfo: .....destination......\n");
333
+
334
+		dumbDestDebugInfo(dest);
335
+	} else {
336
+		DBG("osp: dumpDebugInfo: There is no dest OSPDESTS AVP\n");
337
+	}
338
+
339
+
340
+	DBG("osp: dumpDebugInfo: OUT\n");
341
+}
342
+
343
+
344
+
345
+
346
+void dumbDestDebugInfo(osp_dest *dest) {
347
+	DBG("osp: dumpDebugInfo: dest->destination...'%s'\n", dest->destination);
348
+	DBG("osp: dumpDebugInfo: dest->used..........'%d'\n", dest->used);
349
+	DBG("osp: dumpDebugInfo: dest->last_code.....'%d'\n", dest->last_code);
350
+	DBG("osp: dumpDebugInfo: dest->time_100......'%d'\n", (unsigned int)dest->time_100);
351
+	DBG("osp: dumpDebugInfo: dest->time_180......'%d'\n", (unsigned int)dest->time_180);
352
+	DBG("osp: dumpDebugInfo: dest->time_200......'%d'\n", (unsigned int)dest->time_200);
353
+}
354
+
0 355
new file mode 100644
... ...
@@ -0,0 +1,81 @@
1
+/*
2
+ * openser osp module. 
3
+ *
4
+ * This module enables openser to communicate with an Open Settlement 
5
+ * Protocol (OSP) server.  The Open Settlement Protocol is an ETSI 
6
+ * defined standard for Inter-Domain VoIP pricing, authorization
7
+ * and usage exchange.  The technical specifications for OSP 
8
+ * (ETSI TS 101 321 V4.1.1) are available at www.etsi.org.
9
+ *
10
+ * Uli Abend was the original contributor to this module.
11
+ * 
12
+ * Copyright (C) 2001-2005 Fhg Fokus
13
+ *
14
+ * This file is part of openser, a free SIP server.
15
+ *
16
+ * openser is free software; you can redistribute it and/or modify
17
+ * it under the terms of the GNU General Public License as published by
18
+ * the Free Software Foundation; either version 2 of the License, or
19
+ * (at your option) any later version
20
+ *
21
+ * openser is distributed in the hope that it will be useful,
22
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
23
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
24
+ * GNU General Public License for more details.
25
+ *
26
+ * You should have received a copy of the GNU General Public License
27
+ * along with this program; if not, write to the Free Software
28
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
29
+ */
30
+
31
+
32
+
33
+
34
+
35
+#ifndef OSP_MOD_DESTINATION_H
36
+#define OSP_MOD_DESTINATION_H
37
+
38
+#include "../../str.h"
39
+
40
+struct _osp_dest {
41
+	char validafter[100];
42
+	char validuntil[100];
43
+	char callid[100];
44
+	char callednumber[100];
45
+	char callingnumber[100];
46
+	char source[100];
47
+	char sourcedevice[100];
48
+	char destination[100];
49
+	char destinationdevice[100];
50
+	char network_id[100];
51
+	char osptoken[2000];
52
+	unsigned int sizeofcallid;
53
+	unsigned int timelimit;
54
+	unsigned int sizeoftoken;
55
+	int  used;
56
+	int  last_code;
57
+	time_t time_auth;
58
+	time_t time_100;
59
+	time_t time_180;
60
+	time_t time_200;
61
+	unsigned long long tid;
62
+	int type;
63
+	int reported;
64
+};
65
+
66
+typedef struct _osp_dest osp_dest;
67
+
68
+osp_dest* initDestination(osp_dest* dest);
69
+
70
+osp_dest* getNextOrigDestination();
71
+osp_dest* getTermDestination();
72
+
73
+
74
+int       saveOrigDestination(osp_dest* dest);
75
+int       saveTermDestination(osp_dest* dest);
76
+
77
+void	  recordEvent(int client_code, int server_code);
78
+
79
+void      dumpDebugInfo();
80
+void      dumbDestDebugInfo(osp_dest *dest);
81
+#endif
0 82
new file mode 100644
... ...
@@ -0,0 +1,40 @@
1
+<!DOCTYPE Book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
2
+<!ENTITY ser "SIP Express Router">
3
+<!ENTITY user SYSTEM "osp_user.sgml">
4
+<!ENTITY devel SYSTEM "osp_devel.sgml">
5
+<!ENTITY faq SYSTEM "osp_faq.sgml">
6
+]>
7
+
8
+<book>
9
+  <bookinfo>
10
+    <title>OSP Module</title>
11
+    <productname class="trade">&ser;</productname>
12
+    <authorgroup>
13
+      <author>
14
+        <firstname>Ulrich</firstname>
15
+        <surname>Abend</surname>
16
+        <affiliation><orgname>FhG Fokus</orgname></affiliation>
17
+        <email>ullstar@iptel.org</email>
18
+      </author>
19
+      <editor>
20
+        <firstname>Di-Shi</firstname>
21
+        <surname>Sun</surname>
22
+        <email>support@transnexus.com</email>
23
+      </editor>
24
+    </authorgroup>
25
+    <copyright>
26
+      <year>2003</year>
27
+      <holder>FhG Fokus</holder>
28
+    </copyright>
29
+    <revhistory>
30
+      <revision>
31
+        <revnumber>$Revision$</revnumber>
32
+        <date>$Date$</date>
33
+      </revision>
34
+    </revhistory>
35
+  </bookinfo>
36
+  <toc></toc>
37
+    &user;
38
+    &devel;
39
+    &faq;
40
+</book>
0 41
new file mode 100644
... ...
@@ -0,0 +1,20 @@
1
+<!-- OSP Module Developer's Guide -->
2
+
3
+<chapter>
4
+  <chapterinfo>
5
+    <revhistory>
6
+      <revision>
7
+        <revnumber>$Revision$</revnumber>
8
+        <date>$Date$</date>
9
+      </revision>
10
+    </revhistory>
11
+  </chapterinfo>
12
+  <title>Developer's Guide</title>
13
+  <para>Use of the osp modules' functions by other OpenSER modules is not useful.</para>
14
+</chapter>
15
+
16
+<!-- Keep this element at the end of the file
17
+Local Variables:
18
+sgml-parent-document: ("osp.sgml" "book" "chapter")
19
+End:
20
+-->
0 21
new file mode 100644
... ...
@@ -0,0 +1,50 @@
1
+<!-- OSP Module FAQ -->
2
+
3
+<chapter>
4
+  <chapterinfo>
5
+    <revhistory>
6
+      <revision>
7
+        <revnumber>$Revision$</revnumber>
8
+        <date>$Date$</date>
9
+      </revision>
10
+    </revhistory>
11
+  </chapterinfo>
12
+  <title>Frequently Asked Questions</title>
13
+  <qandaset>
14
+    <qandaentry>
15
+      <question><para>What platforms does this module work on?</para></question>
16
+      <answer><para>The module has been implemented using linux, the underlying toolkit and the module code itself should compile and work on Solaris, *BSD, and probably most other unix platforms with ssl and pthreads available, but all platforms other than linux are completely untested.</para></answer>
17
+    </qandaentry>
18
+    <qandaentry>
19
+      <question><para>Where can I get more information on this module?</para></question>
20
+      <answer><para>Please contact TransNexus by sending email to support@transnexus.com or posting a message on email lists @ http://developer.berlios.de/mail/?group_id=3799 or at the sipfoundry website (www.sipfoundry.org).</para></answer>
21
+    </qandaentry>
22
+    <qandaentry>
23
+      <question><para>Where can I get more information on OSP?</para></question>
24
+      <answer><para>The OSP technical specification (ETSI TS 101 321) may be obtained from www.etsi.org.  Additional documentation on OSP is available from www.sipfoundry.org.</para></answer>
25
+    </qandaentry>
26
+    <qandaentry>
27
+      <question><para>How do I obtain an OSP server for testing?</para></question>
28
+      <answer>
29
+        <para>OSP servers are available from the following sources:</para>
30
+        <itemizedlist>
31
+          <listitem><para>OpenOSP server from www.sipfoundry.org is a complete OSP server written in C.</para></listitem>
32
+          <listitem><para>RAMS from www.sipfoundry.org is a new java based open source OSP server project.</para></listitem>
33
+          <listitem><para>TransNexus provides free access to a hosted OSP server on the Internet for testing. Contact support@transnexus.com.</para></listitem>
34
+        </itemizedlist>
35
+      </answer>
36
+    </qandaentry>
37
+    <qandaentry>
38
+      <question><para>How are the exported functions used by the OSP module?</para></question>
39
+      <answer>
40
+        <para>See sample-osp-openser.cfg in modules/osp/etc for examples</para>
41
+      </answer>
42
+    </qandaentry>
43
+  </qandaset>
44
+</chapter>
45
+
46
+<!-- Keep this element at the end of the file
47
+Local Variables:
48
+sgml-parent-document: ("osp.sgml" "Book" "chapter")
49
+End:
50
+-->
0 51
new file mode 100644
... ...
@@ -0,0 +1,344 @@
1
+<!-- OSP Module User's Guide -->
2
+
3
+<chapter>
4
+  <chapterinfo>
5
+    <revhistory>
6
+      <revision>
7
+        <revnumber>$Revision$</revnumber>
8
+        <date>$Date$</date>
9
+      </revision>
10
+    </revhistory>
11
+  </chapterinfo>
12
+  <title>User's Guide</title>
13
+  <section>
14
+    <title>Overview</title>
15
+    <para>This module implements the client part of the Open Settlement Protocol (OSP) defined by ETSI (ETSI TS 101 321 V4.1.1). OSP can be used to request a validation, request a route and validate a request.</para>
16
+    <para>This module has been tested with the OSP server from TransNexus (www.transnexus.com).</para>
17
+  </section>
18
+  <section>
19
+    <title>Dependencies</title>
20
+    <para>The module depends on the following modules (in the other words, the listed modules must be loaded before this module):</para>
21
+    <itemizedlist>
22
+      <listitem>
23
+        <para><emphasis>textops</emphasis> -- text based operation</para>
24
+      </listitem>
25
+    </itemizedlist>
26
+  </section>
27
+  <section>
28
+    <title>Exported Parameters</title>
29
+    <section>
30
+      <title><varname>sp1_uri</varname> (string), <varname>sp2_uri</varname> (string)</title>
31
+      <para>Defines the one or two OSP servers to be used for requesting authorization and routing information. One OSP server MUST be configured. sp2_uri is required only if there are two OSP servers.</para>
32
+      <para>This parameter has no default value and must be specified. To use a test server hosted by TransNexus, send an email to support@transnexus.com and request an account. Each service point takes the form of a standard URL, and may consist of up to four components:</para>
33
+      <itemizedlist>
34
+        <listitem>
35
+          <para>An optional indication of the protocol to be used for communicating with the service point. Both HTTP and HTTP secured with SSL are supported; they are indicated by "http://" and "https://" respectively. If the protocol is not explicitly indicated, the Toolkit defaults to HTTP secured with SSL.</para>
36
+        </listitem>
37
+        <listitem>
38
+          <para>The Internet domain name for the service point. Raw IP addresses may also be used, provided they are enclosed in square brackets such as "[172.16.1.1]".</para>
39
+        </listitem>
40
+        <listitem>
41
+          <para>An optional TCP port number for communicating with the service point. If the port number is omitted, the Toolkit defaults to port 1080 (for HTTP) or port 1443 (for HTTP secured with SSL).</para>
42
+        </listitem>
43
+        <listitem>
44
+          <para>The uniform resource identifier for requests to the service point. This component is not optional and must be included.</para>
45
+        </listitem>
46
+      </itemizedlist>
47
+      <example>
48
+        <title>Setting the OSP server</title>
49
+        <programlisting format="linespecific">
50
+modparam ("osp", "sp1_uri", "http://osptestserver.transnexus.com:1080/osp")
51
+        </programlisting>
52
+      </example>
53
+    </section>
54
+    <section>
55
+      <title><varname>sp1_weight</varname> (integer), <varname>sp2_weight</varname> (integer)</title>
56
+      <para>The number of messages that can be sent over each connection to the various service points configured. This variable can be used to load balance messages across a set of OSP servers.</para>
57
+      <para>Default value is set to 0.</para>
58
+      <example>
59
+        <title>Setting the OSP server weight</title>
60
+        <programlisting format="linespecific">
61
+modparam ("osp", "sp1_weight", 0)
62
+        </programlisting>
63
+      </example>
64
+    </section>
65
+    <section>
66
+      <title><varname>device_ip </varname> (string)</title>
67
+      <para>This is an optional field; if configured the information is sent out as "SourceAlternate/transport" in the OSP message. </para>
68
+      <example>
69
+        <title>Setting the device IP address</title>
70
+        <programlisting format="linespecific">
71
+modparam ("osp", "device_ip", "[1.1.1.1]")
72
+        </programlisting>
73
+      </example>
74
+    </section>
75
+    <section>
76
+      <title><varname>device_port</varname> (string)</title>
77
+      <para>This is an optional field; if configured the information is sent out as "SourceAlternate/network" in the OSP message.</para>
78
+      <example>
79
+        <title>Setting the device port</title>
80
+        <programlisting format="linespecific">
81
+modparam ("osp", "device_port", "5060")
82
+        </programlisting>
83
+      </example>
84
+    </section>
85
+    <section>
86
+      <title><varname>private_key</varname> (string)</title>
87
+      <para>Defines the private key owned by this device. The crypto files are used for validating OSP authorization tokens and establishing a secure channel between the Proxy and OSP server using SSL. The files can be generated using an enrollment process and the utility 'enroll' from the OSP Toolkit. By default, the proxy will look for pkey.pem, localcert.pem, and cacart_0.pem in the default configuration directory. The default configuration directory is set at compile time using CFG_DIR and defaults to /usr/local/etc/ser/.</para>
88
+      <para>Test files are distributed with the module in the osp/etc folder. You can copy the files to the expected location and/or change the parameters.</para>
89
+      <para>This parameter defaults to "/usr/local/etc/ser/pkey.pem", if the default CFG_DIR value was used at compile time.</para>
90
+      <example>
91
+        <title>Setting the private key</title>
92
+        <programlisting format="linespecific">
93
+modparam ("osp", "private_key", "/usr/local/etc/ser/pkey.pem")
94
+        </programlisting>
95
+      </example>
96
+    </section>
97
+    <section>
98
+      <title><varname>local_certificate</varname> (string)</title>
99
+      <para>Defines the local certificate of this device. The crypto files are used for validating OSP authorization tokens and establishing a secure channel between the Proxy and OSP server using SSL. The files can be generated using an enrollment process and the utility 'enroll' from the OSP toolkit. By default, the proxy will look for pkey.pem, localcert.pem, and cacart_0.pem in the default configuration directory. The default configuration directory is set at compile time using CFG_DIR and defaults to /usr/local/etc/ser/.</para>
100
+      <para>Test files are distributed with the module in the osp/etc folder. You can copy the files to the expected location and/or change the parameters.</para>
101
+      <para>This parameter defaults to "/usr/local/etc/ser/localcert.pem", if the default CFG_DIR value was used at compile time.</para>
102
+      <example>
103
+        <title>Setting the local certificate</title>
104
+        <programlisting format="linespecific">
105
+modparam ("osp", "local_certificate", "/usr/local/etc/ser/localcert.pem")
106
+        </programlisting>
107
+      </example>
108
+    </section>
109
+    <section>
110
+      <title><varname>ca_certificates</varname> (string)</title>
111
+      <para>Defines the CA certificate of the OSP server. The crypto files are used for validating OSP authorization tokens and establishing a secure channel between the Proxy and OSP server using SSL. The files can be generated using an enrollment process and the utility 'enroll' from the OSP toolkit. By default, the proxy will look for pkey.pem, localcert.pem, and cacart_0.pem in the default configuration directory. The default configuration directory is set at compile time using CFG_DIR and defaults to /usr/local/etc/ser/.</para>
112
+      <para>Test files are distributed with the module in the osp/etc folder. You can copy the files to the expected location and/or change the parameters.</para>
113
+      <para>This parameter defaults to "/usr/local/etc/ser/cacert.pem", if the default CFG_DIR value was used at compile time.</para>
114
+      <example>
115
+        <title>Setting the CA certificate</title>
116
+        <programlisting format="linespecific">
117
+modparam ("osp", "ca_certificates", "/usr/local/etc/ser/cacert.pem")
118
+        </programlisting>
119
+      </example>
120
+    </section>
121
+    <section>
122