Browse code

modules: readme files regenerated - tls_wolfssl ... [skip ci]

Kamailio Dev authored on 16/06/2022 07:46:18
Showing 1 changed files
... ...
@@ -1,20 +1,8 @@
1
-TLS Module
1
+wolfSSL TLS Module
2 2
 
3
-Andrei Pelinescu-Onciul
3
+Shih-Ping Chan
4 4
 
5
-   iptelorg GmbH
6
-
7
-Carsten Bock
8
-
9
-   ng-voice GmbH
10
-
11
-Olle E. Johansson
12
-
13
-   Edvina AB
14
-
15
-   Copyright © 2007 iptelorg GmbH
16
-
17
-   Copyright © 2014 ng-voice GmbH
5
+   Copyright © 2022 Chan Shih-Ping
18 6
      __________________________________________________________________
19 7
 
20 8
    Table of Contents
... ...
@@ -24,128 +12,11 @@ Olle E. Johansson
24 12
         1. Overview
25 13
         2. Quick Start
26 14
         3. Important Notes
27
-        4. Compiling the TLS Module
28
-        5. TLS and Low Memory
29
-        6. TLS Debugging
30
-        7. Known Limitations
31
-        8. Quick Certificate Howto
32
-        9. HSM Howto
33
-        10. Parameters
34
-
35
-              10.1. tls_method (string)
36
-              10.2. certificate (string)
37
-              10.3. private_key (string)
38
-              10.4. ca_list (string)
39
-              10.5. ca_path (str)
40
-              10.6. crl (string)
41
-              10.7. verify_certificate (boolean)
42
-              10.8. verify_depth (integer)
43
-              10.9. require_certificate (boolean)
44
-              10.10. cipher_list (string)
45
-              10.11. server_name (string)
46
-              10.12. connection_timeout (int)
47
-              10.13. tls_disable_compression (boolean)
48
-              10.14. ssl_release_buffers (integer)
49
-              10.15. ssl_freelist_max_len (integer)
50
-              10.16. ssl_max_send_fragment (integer)
51
-              10.17. ssl_read_ahead (boolean)
52
-              10.18. send_close_notify (boolean)
53
-              10.19. con_ct_wq_max (integer)
54
-              10.20. ct_wq_max (integer)
55
-              10.21. ct_wq_blk_size (integer)
56
-              10.22. tls_log (int)
57
-              10.23. tls_debug (int)
58
-              10.24. low_mem_threshold1 (integer)
59
-              10.25. low_mem_threshold2 (integer)
60
-              10.26. tls_force_run (boolean)
61
-              10.27. session_cache (boolean)
62
-              10.28. session_id (str)
63
-              10.29. renegotiation (boolean)
64
-              10.30. config (string)
65
-              10.31. xavp_cfg (string)
66
-              10.32. event_callback (str)
67
-              10.33. rand_engine (str)
68
-              10.34. engine (string)
69
-              10.35. engine_config (string)
70
-              10.36. engine_algorithms (string)
71
-              10.37. verify_client (string)
72
-
73
-        11. Functions
74
-
75
-              11.1. is_peer_verified()
76
-              11.2. tls_set_connect_server_id(srvid)
77
-
78
-        12. RPC Commands
79
-
80
-              12.1. tls.info
81
-              12.2. tls.list
82
-              12.3. tls.options
83
-              12.4. tls.reload
84
-
85
-        13. Status
86
-
87
-              13.1. License
88
-              13.2. History
89
-
90
-        14. Event Routes
91
-
92
-              14.1. event_route[tls:connection-out]
93
-
94
-        15. TLS With Database Backend
15
+        4. Compiling the wolfSSL TLS Module
95 16
 
96 17
    List of Examples
97 18
 
98 19
    1.1. Quick Start Basic Config
99
-   1.2. Compiling TLS with Debug Messages
100
-   1.3. Set tls_method parameter
101
-   1.4. Set certificate parameter
102
-   1.5. Set private_key parameter
103
-   1.6. Set ca_list parameter
104
-   1.7. Set ca_path parameter
105
-   1.8. Set crl parameter
106
-   1.9. Set verify_certificate parameter
107
-   1.10. Set verify_depth parameter
108
-   1.11. Set require_certificate parameter
109
-   1.12. Set cipher_list parameter
110
-   1.13. Set server_name parameter
111
-   1.14. Set connection_timeout parameter
112
-   1.15. Set tls.connection_timeout at runtime
113
-   1.16. Set tls_disable_compression parameter
114
-   1.17. Set ssl_release_buffers parameter
115
-   1.18. Set ssl_freelist_max_len parameter
116
-   1.19. Set ssl_max_send_fragment parameter
117
-   1.20. Set ssl_read_ahead parameter
118
-   1.21. Set send_close_notify parameter
119
-   1.22. Set tls.send_close_notify at runtime
120
-   1.23. Set con_ct_wq_max parameter
121
-   1.24. Set tls.con_ct_wq_max at runtime
122
-   1.25. Set ct_wq_max parameter
123
-   1.26. Set tls.ct_wq_max at runtime
124
-   1.27. Set ct_wq_blk_size parameter
125
-   1.28. Set tls.ct_wq_max at runtime
126
-   1.29. Set tls_log parameter
127
-   1.30. Set tls.log at runtime
128
-   1.31. Set tls_debug parameter
129
-   1.32. Set tls.debug at runtime
130
-   1.33. Set low_mem_threshold1 parameter
131
-   1.34. Set tls.low_mem_threshold1 at runtime
132
-   1.35. Set tls.low_mem_threshold2 parameter
133
-   1.36. Set tls.low_mem_threshold2 at runtime
134
-   1.37. Set tls_force_run parameter
135
-   1.38. Set session_cache parameter
136
-   1.39. Set session_id parameter
137
-   1.40. Set renegotiation parameter
138
-   1.41. Sample TLS Config File
139
-   1.42. Set config parameter
140
-   1.43. Change and reload the TLS configuration at runtime
141
-   1.44. Set xavp_cfg parameter
142
-   1.45. Set event_callback parameter
143
-   1.46. Set rand_engine parameter
144
-   1.47. Set verify_client modparam parameter
145
-   1.48. Set verify_client tls.cfg parameter
146
-   1.49. is_peer_verified usage
147
-   1.50. tls_set_connect_server_id usage
148
-   1.51. Use of event_route[tls:connection-out]
149 20
 
150 21
 Chapter 1. Admin Guide
151 22
 
... ...
@@ -154,1560 +25,57 @@ Chapter 1. Admin Guide
154 25
    1. Overview
155 26
    2. Quick Start
156 27
    3. Important Notes
157
-   4. Compiling the TLS Module
158
-   5. TLS and Low Memory
159
-   6. TLS Debugging
160
-   7. Known Limitations
161
-   8. Quick Certificate Howto
162
-   9. HSM Howto
163
-   10. Parameters
164
-
165
-        10.1. tls_method (string)
166
-        10.2. certificate (string)
167
-        10.3. private_key (string)
168
-        10.4. ca_list (string)
169
-        10.5. ca_path (str)
170
-        10.6. crl (string)
171
-        10.7. verify_certificate (boolean)
172
-        10.8. verify_depth (integer)
173
-        10.9. require_certificate (boolean)
174
-        10.10. cipher_list (string)
175
-        10.11. server_name (string)
176
-        10.12. connection_timeout (int)
177
-        10.13. tls_disable_compression (boolean)
178
-        10.14. ssl_release_buffers (integer)
179
-        10.15. ssl_freelist_max_len (integer)
180
-        10.16. ssl_max_send_fragment (integer)
181
-        10.17. ssl_read_ahead (boolean)
182
-        10.18. send_close_notify (boolean)
183
-        10.19. con_ct_wq_max (integer)
184
-        10.20. ct_wq_max (integer)
185
-        10.21. ct_wq_blk_size (integer)
186
-        10.22. tls_log (int)
187
-        10.23. tls_debug (int)
188
-        10.24. low_mem_threshold1 (integer)
189
-        10.25. low_mem_threshold2 (integer)
190
-        10.26. tls_force_run (boolean)
191
-        10.27. session_cache (boolean)
192
-        10.28. session_id (str)
193
-        10.29. renegotiation (boolean)
194
-        10.30. config (string)
195
-        10.31. xavp_cfg (string)
196
-        10.32. event_callback (str)
197
-        10.33. rand_engine (str)
198
-        10.34. engine (string)
199
-        10.35. engine_config (string)
200
-        10.36. engine_algorithms (string)
201
-        10.37. verify_client (string)
202
-
203
-   11. Functions
204
-
205
-        11.1. is_peer_verified()
206
-        11.2. tls_set_connect_server_id(srvid)
207
-
208
-   12. RPC Commands
209
-
210
-        12.1. tls.info
211
-        12.2. tls.list
212
-        12.3. tls.options
213
-        12.4. tls.reload
214
-
215
-   13. Status
216
-
217
-        13.1. License
218
-        13.2. History
219
-
220
-   14. Event Routes
221
-
222
-        14.1. event_route[tls:connection-out]
223
-
224
-   15. TLS With Database Backend
28
+   4. Compiling the wolfSSL TLS Module
225 29
 
226 30
 1. Overview
227 31
 
228
-   This module implements the TLS transport for Kamailio using the OpenSSL
229
-   library (http://www.openssl.org). To enable the Kamailio TLS support
32
+   This module implements the TLS transport for Kamailio using the wolfSSL
33
+   library (https://www.wolfssl.com). To enable the Kamailio TLS support
230 34
    this module must be loaded and enable_tls=yes core setting must be
231 35
    added to the Kamailio config file.
232 36
 
233
-   IMPORTANT: the tls module must be loaded before any other Kamailio
234
-   module that uses libssl (OpenSSL library). A safe option is to have the
235
-   tls module loaded first (be in the first "loadmodule" in Kamailio.cfg).
37
+   This module is derived from the tls module and adapted to wolfSSL using
38
+   the OpenSSL-compatibility layer. Credit goes to the authors of the tls
39
+   module.
40
+
41
+   This module is based on wolfSSL 5.2.0 and 5.3.0 and is not fully
42
+   compatible with the tls module (protocol versions < 1.1 not supported
43
+   it the Debian package for example.
236 44
 
237
-   IMPORTANT: using this module compiled with newer versions of libssl
238
-   (e.g., v1.1+) may require Kamailio to be started with --atexit=no
239
-   command line parameters to avoid calling C atexit callbacks inside the
240
-   process ending during daemonize procedure as well as during shut down,
241
-   which can lead to crashes because it destroys and then accesses shared
242
-   memory. For example, such case has been reported for Ubuntu 20.04 or
243
-   RedHat 8.
45
+   This user is referred to the documentation of the tls module for
46
+   configuration and other information. Not all configuration keys are
47
+   implemented (e.g., protocol versions — defaults to 1.2+ and cipher
48
+   suites).
244 49
 
245 50
 2. Quick Start
246 51
 
247 52
    The default kamailio.cfg file has basic tls support included, it has to
248 53
    be enabled with "#!define WITH_TLS" directive.
249 54
 
250
-   The most important parameters to set the path to the public certificate
251
-   and private key files. You can either have them in different file or in
252
-   the same file in PEM format. The parameters for them are certificate
253
-   and private_key. They can be given as modparam or or provided in the
254
-   profiles of tls.cfg file.
255
-
256
-   When installing tls module of kamailio, a sample 'tls.cfg' file is
257
-   deployed in the same folder with 'kamailio.cfg', along with freshly
258
-   generated self signed certificates.
259
-
260
-   HINT: be sure you have enable_tls=yes to your kamailio.cfg.
261
-
262 55
    Example 1.1. Quick Start Basic Config
263 56
 #...
264 57
 loadmodule "sl.so"
265
-loadmodule "tls.so"
266
-
267
-modparam("tls", "private_key", "./server-test.pem")
268
-modparam("tls", "certificate", "./server-test.pem")
269
-modparam("tls", "ca_list", "./calist.pem")
270
-
271
-enable_tls=yes
272
-
273
-request_route {
274
-        if(proto != TLS) {
275
-                sl_send_reply("403", "Accepting TLS Only");
276
-                exit;
277
-        }
278
-        ...
279
-}
58
+loadmodule "tls_wolfssl.so"
59
+#... refer to Quick Start oftls module
60
+#... for further configuration
280 61
 
281 62
 3. Important Notes
282 63
 
283
-   The TLS module needs some special options enabled when compiling
284
-   Kamailio. These options are enabled by default, however in case you're
285
-   using a modified Kamailio version or Makefile, make sure that you
286
-   enable -DUSE_TLS and -DTLS_HOOKS (or compile with make TLS_HOOKS=1
287
-   which will take care of both options).
288
-
289
-   To quickly check if your Kamailio version was compiled with these
290
-   options, run kamailio -V and look for USE_TLS and TLS_HOOKS among the
291
-   flags.
292
-
293
-   For OpenSSL (libssl) v1.1.x, it is required to preload
294
-   'openssl_mutex_shared' library shipped by Kamailio. For more details
295
-   see 'src/modules/tls/openssl_mutex_shared/README.md'.
296
-
297
-   This module includes several workarounds for various Openssl bugs (like
298
-   compression and Kerberos using the wrong memory allocations functions,
299
-   low memory problems a.s.o). On startup it will try to enable the needed
300
-   workarounds based on the OpenSSL library version. Each time a known
301
-   problem is detected and a workaround is enabled, a message will be
302
-   logged. In general it is recommended to compile this module on the same
303
-   machine or a similar machine to where kamailio will be run or to link
304
-   it statically with libssl. For example if on the compile machine
305
-   OpenSSL does not have the Kerberos support enabled, but on the target
306
-   machine a Kerberos enabled OpenSSL library is installed, Kamailio
307
-   cannot apply the needed workarounds and will refuse to start. The same
308
-   thing will happen if the OpenSSL versions are too different (to force
309
-   Kamailio startup anyway, see the tls_force_run module parameter).
310
-
311
-   Compression is fully supported if you have a new enough OpenSSL version
312
-   (starting with 0.9.8). Although there are some problems with zlib
313
-   compression in currently deployed OpenSSL versions (up to and including
314
-   0.9.8d, see openssl bug #1468), the TLS module will automatically
315
-   switch to its own fixed version. Note however that starting with
316
-   Kamailio 3.1 compression is not enabled by default, due to the huge
317
-   extra memory consumption that it causes (about 10x more memory). To
318
-   enable it use modparam("tls", "tls_disable_compression", 0) (see
319
-   tls_disable_compression).
64
+   The wolfSSL TLS module is intended to be compiled with a recent version
65
+   of wolfSSL (5.2.0+).
320 66
 
321
-   The TLS module includes workarounds for the following known openssl
322
-   bugs:
323
-     * openssl #1204 (disable SS_OP_TLS_BLOCK_PADDING_BUG if compression
324
-       is enabled, for versions between 0.9.8 and 0.9.8c),
325
-     * openssl #1468 (fix zlib compression memory allocation),
326
-     * openssl #1467 (kerberos support will be disabled if the openssl
327
-       version is less than 0.9.8e-beta1)
328
-     * openssl #1491 (stop using tls in low memory situations due to the
329
-       very high risk of openssl crashing or leaking memory).
67
+4. Compiling the wolfSSL TLS Module
330 68
 
331
-   The bug reports can be viewed at http://rt.openssl.org/.
69
+   The development package for wolfSSL is required (libwolfssl-dev or
70
+   equivalent).
332 71
 
333
-4. Compiling the TLS Module
334
-
335
-   In most case compiling the TLS module is as simple as:
336
-make -C modules/tls
72
+   In most case compiling the wolfSSL TLS module is as simple as:
73
+make -C modules/tls_wolfssl
337 74
 
338 75
    or
339
-make modules modules=modules/tls
76
+make modules modules=modules/tls_wolfssl
340 77
 
341 78
    or (compiling whole Kamailio and the tls module)
342
-make all include_modules=tls
79
+make all include_modules=tls_wolfssl
343 80
 
344 81
    .
345
-
346
-   However in some cases the OpenSSL library requires linking with other
347
-   libraries. For example compiling the OpenSSL library with Kerberos and
348
-   zlib-shared support will require linking the TLS module with libkrb5
349
-   and libz. In this case just add TLS_EXTRA_LIBS="library list" to make's
350
-   command line. E.g.:
351
-make TLS_EXTRA_LIBS="-lkrb5 -lz" all include_modules=tls
352
-
353
-   In general, if Kamailio fails to start with a symbol not found error
354
-   when trying to load the TLS module (check the log), it means some
355
-   needed library was not linked and it must be added to TLS_EXTRA_LIBS
356
-
357
-   Elliptic Curve Diffie-Hellman (EDCH)-Ciphers are only supported in
358
-   OpenSSL 1.0.0e and later.
359
-
360
-5. TLS and Low Memory
361
-
362
-   The Openssl library doesn't handle low memory situations very well. If
363
-   memory allocations start to fail (due to memory shortage), Openssl can
364
-   crash or cause memory leaks (making the memory shortage even worse). As
365
-   of this writing all Openssl versions were affected (including 0.9.8e),
366
-   see Openssl bug #1491. The TLS module has some workarounds for
367
-   preventing this problem (see low_mem_treshold1 and low_mem_threshold2),
368
-   however starting Kamailio with enough shared memory is higly
369
-   recommended. When this is not possible a quick way to significantly
370
-   reduce Openssl memory usage it to disable compression (see
371
-   tls_disable_compression).
372
-
373
-6. TLS Debugging
374
-
375
-   Debugging messages can be selectively enabled by recompiling the TLS
376
-   module with a combination of the following defines:
377
-     * TLS_WR_DEBUG - debug messages for the write/send part.
378
-     * TLS_RD_DEBUG - debug messages for the read/receive part.
379
-     * TLS_BIO_DEBUG - debug messages for the custom BIO.
380
-
381
-   Example 1.2. Compiling TLS with Debug Messages
382
-make -C modules/tls extra_defs="-DTLS_WR_DEBUG -DTLS_RD_DEBUG"
383
-
384
-   To change the level at which the debug messages are logged, change the
385
-   tls_debug module parameter.
386
-
387
-7. Known Limitations
388
-
389
-   The private key must not be encrypted (Kamailio cannot ask you for a
390
-   password on startup).
391
-
392
-   The TLS certificate verifications ignores the certificate name, Subject
393
-   Altname and IP extensions, it just checks if the certificate is signed
394
-   by a recognized CA. One can use the select framework to try to overcome
395
-   this limitation (check in the script for the contents of various
396
-   certificate fields), but this is not only slow, but also not exactly
397
-   standard conforming (the verification should happen during TLS
398
-   connection establishment and not after).
399
-
400
-   TLS specific config reloading is not safe, so for now better don't use
401
-   it, especially under heavy traffic.
402
-
403
-   This documentation is incomplete. The provided selects are not
404
-   documented in this file. A list with all the ones implemented by the
405
-   TLS module can be found in the Cookbook https://www.kamailio.org/wiki/
406
-   in the section Selects for the respective version of Kamailio.
407
-
408
-8. Quick Certificate Howto
409
-
410
-   There are various ways to create, sign certificates and manage small
411
-   CAs (Certificate Authorities). If you are in a hurry and everything you
412
-   have are the installed OpenSSL libraries and utilities, read on.
413
-
414
-   Assumptions: we run our own CA.
415
-
416
-   Warning: in this example no key is encrypted. The client and server
417
-   private keys must not be encrypted (Kamailio doesn't support encrypted
418
-   keys), so make sure the corresponding files are readable only by
419
-   trusted people. You should use a password to protect your CA private
420
-   key.
421
-
422
-Assumptions
423
-
424
-The default openssl configuration (usually /etc/ssl/openssl.cnf)
425
-default_ca section is the one distributed with openssl and uses the default
426
-directories:
427
-
428
-...
429
-
430
-default_ca      = CA_default            # The default ca section
431
-
432
-[ CA_default ]
433
-
434
-dir             = ./demoCA              # Where everything is kept
435
-certs           = $dir/certs            # Where the issued certs are kept
436
-crl_dir         = $dir/crl              # Where the issued crl are kept
437
-database        = $dir/index.txt        # database index file.
438
-#unique_subject = no                    # Set to 'no' to allow creation of
439
-                                        # several certificates with same subject
440
-.
441
-new_certs_dir   = $dir/newcerts         # default place for new certs.
442
-
443
-certificate     = $dir/cacert.pem       # The CA certificate
444
-serial          = $dir/serial           # The current serial number
445
-crlnumber       = $dir/crlnumber        # the current CRL number
446
-crl             = $dir/crl.pem          # The current CRL
447
-private_key     = $dir/private/cakey.pem# The private key
448
-RANDFILE        = $dir/private/.rand    # private random number file
449
-
450
-...
451
-
452
-If this is not the case create a new OpenSSL config file that uses the above
453
-paths for the default CA and add to all the openssl commands:
454
- -config filename. E.g.:
455
-        openssl ca -config my_openssl.cnf -in kamailio1_cert_req.pem -out kamail
456
-io1_cert.pem
457
-
458
-
459
-Creating the CA certificate
460
-1. Create the CA directory
461
-        mkdir ca
462
-        cd ca
463
-
464
-2. Create the CA directory structure and files  (see ca(1))
465
-        mkdir demoCA            #default CA name, edit /etc/ssl/openssl.cnf
466
-        mkdir  demoCA/private
467
-        mkdir demoCA/newcerts
468
-        touch demoCA/index.txt
469
-        echo 01 >demoCA/serial
470
-        echo 01 >demoCA/crlnumber
471
-
472
-2. Create CA private key
473
-        openssl genrsa -out demoCA/private/cakey.pem 2048
474
-        chmod 600 demoCA/private/cakey.pem
475
-
476
-3. Create CA self-signed certificate
477
-        openssl req -out demoCA/cacert.pem   -x509 -new -key demoCA/private/cake
478
-y.pem
479
-
480
-
481
-Creating a server/client TLS certificate
482
-1. Create a certificate request (and its private key in privkey.pem)
483
-
484
-        openssl req -out kamailio1_cert_req.pem -new -nodes
485
-
486
-        WARNING: the organization name should be the same as in the CA certifica
487
-te.
488
-
489
-2. Sign it with the CA certificate
490
-        openssl ca -in kamailio1_cert_req.pem -out kamailio1_cert.pem
491
-
492
-3. Copy kamailio1_cert.pem to your Kamailio configuration dir
493
-
494
-
495
-Setting Kamailio to use the TLS certificate
496
-1. Create the CA list file:
497
-        for each of your CA certificates that you intend to use do:
498
-                cat cacert.pem >>calist.pem
499
-
500
-2. Copy your Kamailio certificate, private key and ca list file to your
501
-        intended machine (preferably in your Kamailio configuration directory,
502
-         this is the default place Kamailio searches for).
503
-
504
-3. Set up Kamailio.cfg to use the certificate
505
-        if your Kamailio certificate name is different from cert.pem or it is no
506
-t
507
-        placed in Kamailio cfg. directory, add to your kamailio.cfg:
508
-                modparam("tls", "certificate", "/path/cert_file_name")
509
-
510
-4. Set up Kamailio to use the private key
511
-        if your private key is not contained in the same file as the certificate
512
-        (or the certificate name is not the default cert.pem), add to your
513
-         Kamailio.cfg:
514
-                modparam("tls", "private_key", "/path/private_key_file")
515
-
516
-5. Set up Kamailio to use the CA list (optional)
517
-   The CA list is not used for your server certificate - it's used to approve ot
518
-her servers
519
-   and clients connecting to your server with a client certificate or for approv
520
-ing
521
-   a certificate used by a server your server connects to.
522
-        add to your Kamailio.cfg:
523
-                modparam("tls", "ca_list", "/path/ca_list_file")
524
-
525
-6. Set up TLS authentication options:
526
-                modparam("tls", "verify_certificate", 1)
527
-                modparam("tls", "require_certificate", 1)
528
-        (for more information see the module parameters documentation)
529
-
530
-
531
-Revoking a certificate and using a CRL
532
-1. Revoking a certificate:
533
-        openssl ca -revoke bad_cert.pem
534
-
535
-2. Generate/update the certificate revocation list:
536
-        openssl ca -gencrl -out my_crl.pem
537
-
538
-3. Copy my_crl.pem to your Kamailio config. dir
539
-
540
-4. Set up Kamailio to use the CRL:
541
-                modparam("tls", "crl", "path/my_crl.pem")
542
-
543
-9. HSM Howto
544
-
545
-   This documents OpenSSL engine support for private keys in HSM.
546
-
547
-   Assumptions: an OpenSSL engine configured with private key. We still
548
-   require the certificate file and list of CA certificates per a regular
549
-   TLS configuration.
550
-
551
-Thales Luna Example
552
-
553
-...
554
-# Example for Thales Luna
555
-modparam("tls", "engine", "gem")
556
-modparam("tls", "engine_config", "/usr/local/etc/kamailio/thales.cnf")
557
-modparam("tls", "engine_algorithms", "EC")
558
-...
559
-
560
-/usr/local/etc/kamailio/thales.cnf is a OpenSSL config format file used to
561
-bootstrap the engine, e.g., pass the PIN.
562
-
563
-...
564
-# the key kamailio is mandatory
565
-kamailio = openssl_init
566
-
567
-[ openssl_init ]
568
-engines = engine_section
569
-
570
-[ engine_section ]
571
-# gem is the name of the Thales Luna OpenSSL engine
572
-gem = gem_section
573
-
574
-[ gem_section ]
575
-# from Thales documentation
576
-dynamic_path = /usr/lib64/engines-1.1/gem.so
577
-ENGINE_INIT = 0:20:21:password=1234-ABCD-5678-EFGH
578
-...
579
-
580
-
581
-Thales nShield Connect
582
-
583
-Place holder
584
-
585
-10. Parameters
586
-
587
-   10.1. tls_method (string)
588
-   10.2. certificate (string)
589
-   10.3. private_key (string)
590
-   10.4. ca_list (string)
591
-   10.5. ca_path (str)
592
-   10.6. crl (string)
593
-   10.7. verify_certificate (boolean)
594
-   10.8. verify_depth (integer)
595
-   10.9. require_certificate (boolean)
596
-   10.10. cipher_list (string)
597
-   10.11. server_name (string)
598
-   10.12. connection_timeout (int)
599
-   10.13. tls_disable_compression (boolean)
600
-   10.14. ssl_release_buffers (integer)
601
-   10.15. ssl_freelist_max_len (integer)
602
-   10.16. ssl_max_send_fragment (integer)
603
-   10.17. ssl_read_ahead (boolean)
604
-   10.18. send_close_notify (boolean)
605
-   10.19. con_ct_wq_max (integer)
606
-   10.20. ct_wq_max (integer)
607
-   10.21. ct_wq_blk_size (integer)
608
-   10.22. tls_log (int)
609
-   10.23. tls_debug (int)
610
-   10.24. low_mem_threshold1 (integer)
611
-   10.25. low_mem_threshold2 (integer)
612
-   10.26. tls_force_run (boolean)
613
-   10.27. session_cache (boolean)
614
-   10.28. session_id (str)
615
-   10.29. renegotiation (boolean)
616
-   10.30. config (string)
617
-   10.31. xavp_cfg (string)
618
-   10.32. event_callback (str)
619
-   10.33. rand_engine (str)
620
-   10.34. engine (string)
621
-   10.35. engine_config (string)
622
-   10.36. engine_algorithms (string)
623
-   10.37. verify_client (string)
624
-
625
-10.1. tls_method (string)
626
-
627
-   Sets the TLS protocol method. Possible values are:
628
-     * TLSv1.2+ - TLSv1.2 or newer (TLSv1.3, ...) connections are accepted
629
-       (available starting with openssl/libssl v1.1.1)
630
-     * TLSv1.2 - only TLSv1.2 connections are accepted (available starting
631
-       with openssl/libssl v1.0.1e)
632
-     * TLSv1.1+ - TLSv1.1 or newer (TLSv1.2, ...) connections are accepted
633
-       (available starting with openssl/libssl v1.0.1)
634
-     * TLSv1.1 - only TLSv1.1 connections are accepted (available starting
635
-       with openssl/libssl v1.0.1)
636
-     * TLSv1+ - TLSv1.0 or newer (TLSv1.1, TLSv1.2, ...) connections are
637
-       accepted.
638
-     * TLSv1 - only TLSv1 (TLSv1.0) connections are accepted. This is the
639
-       default value.
640
-     * SSLv3 - only SSLv3 connections are accepted. Note: you shouldn't
641
-       use SSLv3 for anything which should be secure.
642
-     * SSLv2 - only SSLv2 connections, for old clients. Note: you
643
-       shouldn't use SSLv2 for anything which should be secure. Newer
644
-       versions of OpenSSL libraries don't include support for it anymore.
645
-     * SSLv23 - any of the SSLv2, SSLv3 and TLSv1 or newer methods will be
646
-       accepted.
647
-       From the OpenSSL manual: "A TLS/SSL connection established with
648
-       these methods may understand the SSLv3, TLSv1, TLSv1.1 and TLSv1.2
649
-       protocols. If extensions are required (for example server name) a
650
-       client will send out TLSv1 client hello messages including
651
-       extensions and will indicate that it also understands TLSv1.1,
652
-       TLSv1.2 and permits a fallback to SSLv3. A server will support
653
-       SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols. This is the best
654
-       choice when compatibility is a concern."
655
-       Note: For older OpenSSL library versions, this option allows SSLv2,
656
-       with hello messages done over SSLv2. You shouldn't use SSLv2 or
657
-       SSLv3 for anything which should be secure.
658
-
659
-   If RFC 3261 conformance is desired, at least TLSv1 must be used. For
660
-   compatibility with older clients SSLv23 is the option, but again, be
661
-   aware of security concerns, SSLv2/3 being considered very insecure by
662
-   2014. For current information about what's considered secure, please
663
-   consult, IETF BCP 195, currently RFC 7525 - "Recommendations for Secure
664
-   Use of Transport Layer Security (TLS) and Datagram Transport Layer
665
-   Security (DTLS)"
666
-
667
-   Example 1.3. Set tls_method parameter
668
-...
669
-modparam("tls", "tls_method", "TLSv1")
670
-...
671
-
672
-10.2. certificate (string)
673
-
674
-   Sets the certificate file name. The certificate file can also contain
675
-   the private key in PEM format.
676
-
677
-   If the file name starts with a '.' the path will be relative to the
678
-   working directory (at runtime). If it starts with a '/' it will be an
679
-   absolute path and if it starts with anything else the path will be
680
-   relative to the main config file directory (e.g.: for kamailio -f
681
-   /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).
682
-
683
-   The default value is /usr/local/etc/kamailio/cert.pem
684
-
685
-   Example 1.4. Set certificate parameter
686
-...
687
-modparam("tls", "certificate", "/usr/local/etc/kamailio/my_certificate.pem")
688
-...
689
-
690
-10.3. private_key (string)
691
-
692
-   Sets the private key file name. The private key can be in the same file
693
-   as the certificate or in a separate file, specified by this
694
-   configuration parameter.
695
-
696
-   If the file name starts with a '.' the path will be relative to the
697
-   working directory (at runtime). If it starts with a '/' it will be an
698
-   absolute path and if it starts with anything else the path will be
699
-   relative to the main config file directory (e.g.: for kamailio -f
700
-   /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).
701
-
702
-   Note: the private key can be contained in the same file as the
703
-   certificate (just append it to the certificate file, e.g.: cat pkey.pem
704
-   >> cert.pem)
705
-
706
-   The default value is /usr/local/etc/kamailio/cert.pem
707
-
708
-   Example 1.5. Set private_key parameter
709
-...
710
-modparam("tls", "private_key", "/usr/local/etc/kamailio/my_pkey.pem")
711
-...
712
-
713
-10.4. ca_list (string)
714
-
715
-   Sets the CA list file name. This file contains a list of all the
716
-   trusted CAs certificates used when connecting to other SIP
717
-   implementations. If a signature in a certificate chain belongs to one
718
-   of the listed CAs, the verification of that certificate will succeed.
719
-
720
-   If the file name starts with a '.' the path will be relative to the
721
-   working directory (at runtime). If it starts with a '/' it will be an
722
-   absolute path and if it starts with anything else the path will be
723
-   relative to the main config file directory (e.g.: for kamailio -f
724
-   /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).
725
-
726
-   By default the CA file is not set.
727
-
728
-   An easy way to create the CA list is to append each trusted trusted CA
729
-   certificate in the PEM format to one file, e.g.:
730
-for f in trusted_cas/*.pem ; do cat "$f" >> ca_list.pem ; done
731
-
732
-   See also verify_certificate, verify_depth, require_certificate and crl.
733
-
734
-   Example 1.6. Set ca_list parameter
735
-...
736
-modparam("tls", "ca_list", "/usr/local/etc/kamailio/ca_list.pem")
737
-...
738
-
739
-10.5. ca_path (str)
740
-
741
-   Sets the path with the trusted CA files, to be given as parameter
742
-   SSL_CTX_load_verify_locations(). The certificates in ca_path are only
743
-   looked up when required, e.g. when building the certificate chain or
744
-   when actually performing the verification of a peer certificate. They
745
-   are not given to the client (not loaded to be provided to
746
-   SSL_CTX_set_client_CA_list()), only the ones in ca_list files are sent
747
-   to the client. It requires to use c_rehash to generate the hash map for
748
-   certificate search, for more see the manual of libssl for
749
-   SSL_CTX_load_verify_locations() function.
750
-
751
-   By default it is not set.
752
-
753
-   Example 1.7. Set ca_path parameter
754
-...
755
-modparam("tls", "ca_path", "/usr/local/etc/kamailio/ca")
756
-...
757
-
758
-10.6. crl (string)
759
-
760
-   Sets the certificate revocation list (CRL) file name. This file
761
-   contains a list of revoked certificates. Any attempt to verify a
762
-   revoked certificate will fail.
763
-
764
-   If not set, no CRL list will be used.
765
-
766
-   If the file name starts with a '.' the path will be relative to the
767
-   working directory (at runtime). If it starts with a '/' it will be an
768
-   absolute path and if it starts with anything else the path will be
769
-   relative to the main config file directory (e.g.: for kamailio -f
770
-   /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).
771
-
772
-Note
773
-
774
-   If set, require_certificate should also be set or it will not have any
775
-   effect.
776
-
777
-   By default the CRL file name is not set.
778
-
779
-   To update the CRL in a running Kamailio, make sure you configure TLS
780
-   via a separate TLS config file (the config modparam) and issue a
781
-   tls.reload RPC call, e.g.:
782
- $ kamcmd tls.reload
783
-
784
-   A quick way to create the CRL in PEM format, using OpenSSL is:
785
- $ openssl ca -gencrl -keyfile cacert.key -cert cacert.pem -out my_crl.pem
786
-
787
-   my_crl.pem will contain the signed list of the revoked certificates.
788
-
789
-   To revoke a TLS certificate use something like:
790
- $ openssl ca -revoke bad_cert.pem -keyfile cacert.key -cert cacert.pem
791
-
792
-   and then refresh the crl file using the command above.
793
-
794
-   To display the CRL contents use:
795
- $ openssl crl -in crl.pem -noout -text
796
-
797
-   See also ca_list, verify_certificate, verify_depth and
798
-   require_certificate.
799
-
800
-   Example 1.8. Set crl parameter
801
-...
802
-modparam("tls", "crl", "/usr/local/etc/kamailio/crl.pem")
803
-...
804
-
805
-10.7. verify_certificate (boolean)
806
-
807
-   If enabled it will force certificate verification when connecting to
808
-   other SIP servers.. For more information see the verify(1) OpenSSL man
809
-   page.
810
-
811
-   Note: the certificate verification will always fail if the ca_list is
812
-   empty.
813
-
814
-   See also: ca_list, require_certificate, verify_depth.
815
-
816
-   By default the certificate verification is off.
817
-
818
-   Example 1.9. Set verify_certificate parameter
819
-...
820
-modparam("tls", "verify_certificate", 1)
821
-...
822
-
823
-10.8. verify_depth (integer)
824
-
825
-   Sets how far up the certificate chain will the certificate verification
826
-   go in the search for a trusted CA.
827
-
828
-   See also: ca_list, require_certificate, verify_certificate,
829
-
830
-   The default value is 9.
831
-
832
-   Example 1.10. Set verify_depth parameter
833
-...
834
-modparam("tls", "verify_depth", 9)
835
-...
836
-
837
-10.9. require_certificate (boolean)
838
-
839
-   When enabled Kamailio will require a certificate from a client
840
-   connecting to the TLS port. If the client does not offer a certificate
841
-   and verify_certificate is on, certificate verification will fail.
842
-
843
-   The default value is off.
844
-
845
-   Example 1.11. Set require_certificate parameter
846
-...
847
-modparam("tls", "require_certificate", 1)
848
-...
849
-
850
-10.10. cipher_list (string)
851
-
852
-   Sets the list of accepted ciphers. The list consists of cipher strings
853
-   separated by colons. For more information on the cipher list format see
854
-   the cipher(1) OpenSSL man page.
855
-
856
-   The default value is not set (all the OpenSSL supported ciphers are
857
-   enabled).
858
-
859
-   Example 1.12. Set cipher_list parameter
860
-...
861
-modparam("tls", "cipher_list", "HIGH")
862
-...
863
-
864
-10.11. server_name (string)
865
-
866
-   Sets the Server Name Indication (SNI) value.
867
-
868
-   This is a TLS extension enabling one TLS server to serve multiple host
869
-   names with unique certificates.
870
-
871
-   The default value is empty (not set).
872
-
873
-   Example 1.13. Set server_name parameter
874
-...
875
-modparam("tls", "server_name", "kamailio.org")
876
-...
877
-
878
-10.12. connection_timeout (int)
879
-
880
-   Sets the amount of time after which an idle TLS connection will be
881
-   closed, if no I/O ever occurred after the initial open. If an I/O event
882
-   occurs, the timeout will be extended with tcp_connection_lifetime. The
883
-   value is expressed in seconds.
884
-
885
-   The default value is 10 min.
886
-
887
-   If the value set is -1, the connection will never be close on idle.
888
-
889
-   This setting can be changed also at runtime, via the RPC interface and
890
-   config framework. The config variable name is tls.connection_timeout.
891
-
892
-   Example 1.14. Set connection_timeout parameter
893
-...
894
-modparam("tls", "connection_timeout", 60)
895
-...
896
-
897
-   Example 1.15. Set tls.connection_timeout at runtime
898
- $ kamcmd cfg.set_now_int tls connection_timeout 180
899
-
900
-10.13. tls_disable_compression (boolean)
901
-
902
-   If set compression over TLS will be disabled. Note that compression
903
-   uses a lot of memory (about 10x more then with the compression
904
-   disabled), so if you want to minimize memory usage is a good idea to
905
-   disable it. TLS compression also expose you for the CRIME security
906
-   vulnerability.
907
-
908
-   By default TLS compression is disabled.
909
-
910
-   Example 1.16. Set tls_disable_compression parameter
911
-...
912
-modparam("tls", "tls_disable_compression", 0) # enable
913
-...
914
-
915
-10.14. ssl_release_buffers (integer)
916
-
917
-   Release internal OpenSSL read or write buffers as soon as they are no
918
-   longer needed. Combined with ssl_freelist_max_len has the potential of
919
-   saving a lot of memory ( ~ 32k per connection in the default
920
-   configuration, or 16k + ssl_max_send_fragment). For Kamailio versions >
921
-   3.0 it makes little sense to disable it (0) since the tls module
922
-   already has its own internal buffering.
923
-
924
-   A value of -1 would not change this option from its openssl default.
925
-   Use 0 or 1 for enable/disable.
926
-
927
-   By default the value is 1 (enabled).
928
-
929
-Note
930
-
931
-   This option is supported only for OpenSSL versions >= 1.0.0. On all the
932
-   other versions attempting to change the default will trigger an error.
933
-
934
-   Example 1.17. Set ssl_release_buffers parameter
935
-modparam("tls", "ssl_release_buffers", 1)
936
-
937
-10.15. ssl_freelist_max_len (integer)
938
-
939
-   Sets the maximum number of free memory chunks, that OpenSSL will keep
940
-   per connection. Setting it to 0 would cause any unused memory chunk to
941
-   be immediately freed, reducing the memory footprint. A too large value
942
-   would result in extra memory consumption.
943
-
944
-   Should be combined with ssl_release_buffers.
945
-
946
-   A value of -1 has a special meaning: the OpenSSL default will be used
947
-   (no attempt on changing the value will be made). For OpenSSL 1.0 the
948
-   internal default is 32.
949
-
950
-   By default the value is 0 (no freelist).
951
-
952
-Note
953
-
954
-   This option is supported only for OpenSSL versions >= 1.0.0. On all the
955
-   other versions attempting to change the default will trigger an error.
956
-
957
-   Example 1.18. Set ssl_freelist_max_len parameter
958
-modparam("tls", "ssl_freelist_max_len", 0)
959
-
960
-10.16. ssl_max_send_fragment (integer)
961
-
962
-   Sets the maximum number of bytes (from the clear text) sent into one
963
-   TLS record. Valid values are between 512 and 16384. Note however that
964
-   even valid low values might not be big enough to allow a successful
965
-   handshake (try minimum 1024).
966
-
967
-   Lower values would lead to less memory usage, but values lower then the
968
-   typical Kamailio write size would incur a slight performance penalty.
969
-   Good values are bigger then the size of the biggest SIP packet one
970
-   normally expects to forward. For example in most setups 2048 would be a
971
-   good value.
972
-
973
-Note
974
-
975
-   Values on the lower side, even if valid (> 512), might not allow for a
976
-   successful initial handshake. This happens if the certificate does not
977
-   fit inside one send fragment. Values lower then 1024 should not be
978
-   used. Even with higher values, if the handshake fails, try increasing
979
-   the value.
980
-
981
-   A value of -1 has a special meaning: the OpenSSL default will be used
982
-   (no attempt on changing the value will be made).
983
-
984
-   By default the value is -1 (the OpenSSL default, which at least in
985
-   OpenSSL 1.0.0 is ~ 16k).
986
-
987
-Note
988
-
989
-   This option is supported only for OpenSSL versions >= 0.9.9. On all the
990
-   other versions attempting to change the default will trigger an error.
991
-
992
-   Example 1.19. Set ssl_max_send_fragment parameter
993
-modparam("tls", "ssl_max_send_fragment", 4096)
994
-
995
-10.17. ssl_read_ahead (boolean)
996
-
997
-   Enables read ahead, reducing the number of internal OpenSSL BIO read()
998
-   calls. This option has only debugging value, in normal circumstances it
999
-   should not be changed from the default.
1000
-
1001
-   When disabled OpenSSL will make at least 2 BIO read() calls per
1002
-   received record: one to get the record header and one to get the rest
1003
-   of the record.
1004
-
1005
-   The TLS module buffers internally all read()s and defines its own fast
1006
-   BIO so enabling this option would only cause more memory consumption
1007
-   and a minor slow-down (extra memcpy).
1008
-
1009
-   A value of -1 has a special meaning: the OpenSSL default will be used
1010
-   (no attempt on changing the value will be made).
1011
-
1012
-   By default the value is 0 (disabled).
1013
-
1014
-   Example 1.20. Set ssl_read_ahead parameter
1015
-modparam("tls", "ssl_read_ahead", 1)
1016
-
1017
-10.18. send_close_notify (boolean)
1018
-
1019
-   Enables/disables sending close notify alerts prior to closing the
1020
-   corresponding TCP connection. Sending the close notify prior to TCP
1021
-   shutdown is "nicer" from a TLS point of view, but it has a measurable
1022
-   performance impact. Default: off. Can be set at runtime
1023
-   (tls.send_close_notify).
1024
-
1025
-   The default value is 0 (off).
1026
-
1027
-   It can be changed also at runtime, via the RPC interface and config
1028
-   framework. The config variable name is tls.send_close_notify.
1029
-
1030
-   Example 1.21. Set send_close_notify parameter
1031
-...
1032
-modparam("tls", "send_close_notify", 1)
1033
-...
1034
-
1035
-   Example 1.22. Set tls.send_close_notify at runtime
1036
- $ kamcmd cfg.set_now_int tls send_close_notify 1
1037
-
1038
-10.19. con_ct_wq_max (integer)
1039
-
1040
-   Sets the maximum allowed per connection clear-text send queue size in
1041
-   bytes. This queue is used when data cannot be encrypted and sent
1042
-   immediately because of an ongoing TLS level renegotiation.
1043
-
1044
-   The default value is 65536 (64 Kb).
1045
-
1046
-   It can be changed also at runtime, via the RPC interface and config
1047
-   framework. The config variable name is tls.con_ct_wq_max.
1048
-
1049
-   Example 1.23. Set con_ct_wq_max parameter
1050
-...
1051
-modparam("tls", "con_ct_wq_max", 1048576)
1052
-...
1053
-
1054
-   Example 1.24. Set tls.con_ct_wq_max at runtime
1055
- $ kamcmd cfg.set_now_int tls con_ct_wq_max 1048576
1056
-
1057
-10.20. ct_wq_max (integer)
1058
-
1059
-   Sets the maximum total number of bytes queued in all the clear-text
1060
-   send queues. These queues are used when data cannot be encrypted and
1061
-   sent immediately because of an ongoing TLS level renegotiation.
1062
-
1063
-   The default value is 10485760 (10 Mb).
1064
-
1065
-   It can be changed also at runtime, via the RPC interface and config
1066
-   framework. The config variable name is tls.ct_wq_max.
1067
-
1068
-   Example 1.25. Set ct_wq_max parameter
1069
-...
1070
-modparam("tls", "ct_wq_max", 4194304)
1071
-...
1072
-
1073
-   Example 1.26. Set tls.ct_wq_max at runtime
1074
- $ kamcmd cfg.set_now_int tls ct_wq_max 4194304
1075
-
1076
-10.21. ct_wq_blk_size (integer)
1077
-
1078
-   Minimum block size for the internal clear-text send queues (debugging /
1079
-   advanced tuning). Good values are multiple of typical datagram sizes.
1080
-
1081
-   The default value is 4096.
1082
-
1083
-   It can be changed also at runtime, via the RPC interface and config
1084
-   framework. The config variable name is tls.ct_wq_blk_size.
1085
-
1086
-   Example 1.27. Set ct_wq_blk_size parameter
1087
-...
1088
-modparam("tls", "ct_wq_blk_size", 2048)
1089
-...
1090
-
1091
-   Example 1.28. Set tls.ct_wq_max at runtime
1092
- $ kamcmd cfg.set_now_int tls ct_wq_blk_size 2048
1093
-
1094
-10.22. tls_log (int)
1095
-
1096
-   Sets the log level at which TLS related messages will be logged.
1097
-
1098
-   The default value is 3 (L_DBG).
1099
-
1100
-   It can be changed also at runtime, via the RPC interface and config
1101
-   framework. The config variable name is tls.log.
1102
-
1103
-   Example 1.29. Set tls_log parameter
1104
-...
1105
-# ignore TLS messages if Kamailio is started with debug less than 10
1106
-modparam("tls", "tls_log", 10)
1107
-...
1108
-
1109
-   Example 1.30. Set tls.log at runtime
1110
- $ kamcmd cfg.set_now_int tls log 10
1111
-
1112
-10.23. tls_debug (int)
1113
-
1114
-   Sets the log level at which TLS debug messages will be logged. Note
1115
-   that TLS debug messages are enabled only if the TLS module is compiled
1116
-   with debugging enabled (e.g. -DTLS_WR_DEBUG, -DTLS_RD_DEBUG or
1117
-   -DTLS_BIO_DEBUG).
1118
-
1119
-   The default value is 3 (L_DBG).
1120
-
1121
-   It can be changed also at runtime, via the RPC interface and config
1122
-   framework. The config variable name is tls.debug.
1123
-
1124
-   Example 1.31. Set tls_debug parameter
1125
-...
1126
-# ignore TLS debug messages if Kamailio is started with debug less than 10
1127
-modparam("tls", "tls_debug", 10)
1128
-...
1129
-
1130
-   Example 1.32. Set tls.debug at runtime
1131
- $ kamcmd cfg.set_now_int tls debug 10
1132
-
1133
-10.24. low_mem_threshold1 (integer)
1134
-
1135
-   Sets the minimal free memory from which attempts to open or accept new
1136
-   TLS connections will start to fail. The value is expressed in KB.
1137
-
1138
-   The default value depends on whether the OpenSSL library used handles
1139
-   low memory situations in a good way (openssl bug #1491). As of this
1140
-   writing this is not true for any OpenSSL version (including 0.9.8e).
1141
-
1142
-   If an ill-behaved OpenSSL version is detected, a very conservative
1143
-   value is chosen, which depends on the maximum possible number of
1144
-   simultaneously created TLS connections (and hence on the process
1145
-   number).
1146
-
1147
-   The following values have a special meaning:
1148
-     * -1 - use the default value
1149
-     * 0 - disable (TLS connections will not fail preemptively)
1150
-
1151
-   It can be changed also at runtime, via the RPC interface and config
1152
-   framework. The config variable name is tls.low_mem_threshold1.
1153
-
1154
-   See also tls.low_mem_threshold2.
1155
-
1156
-   Example 1.33. Set low_mem_threshold1 parameter
1157
-...
1158
-modparam("tls", "low_mem_threshold1", -1)
1159
-...
1160
-
1161
-   Example 1.34. Set tls.low_mem_threshold1 at runtime
1162
- $ kamcmd cfg.set_now_int tls low_mem_threshold1 2048
1163
-
1164
-10.25. low_mem_threshold2 (integer)
1165
-
1166
-   Sets the minimal free memory from which TLS operations on already
1167
-   established TLS connections will start to fail preemptively. The value
1168
-   is expressed in KB.
1169
-
1170
-   The default value depends on whether the OpenSSL library used handles
1171
-   low memory situations (openssl bug #1491). As of this writing this is
1172
-   not true for any OpenSSL version (including 0.9.8e).
1173
-
1174
-   If an ill-behaved OpenSSL version is detected, a very conservative
1175
-   value is chosen, which depends on the maximum possible number of
1176
-   simultaneously created TLS connections (and hence on the process
1177
-   number).
1178
-
1179
-   The following values have a special meaning:
1180
-     * -1 - use the default value
1181
-     * 0 - disable (TLS operations will not fail preemptively)
1182
-
1183
-   It can be changed also at runtime, via the RPC interface and config
1184
-   framework. The config variable name is tls.low_mem_threshold2.
1185
-
1186
-   See also tls.low_mem_threshold1.
1187
-
1188
-   Example 1.35. Set tls.low_mem_threshold2 parameter
1189
-...
1190
-modparam("tls", "low_mem_threshold2", -1)
1191
-...
1192
-
1193
-   Example 1.36. Set tls.low_mem_threshold2 at runtime
1194
- $ kamcmd cfg.set_now_int tls low_mem_threshold2 1024
1195
-
1196
-10.26. tls_force_run (boolean)
1197
-
1198
-   If enabled Kamailio will start even if some of the OpenSSL sanity
1199
-   checks fail (turn it on at your own risk).
1200
-
1201
-   If any of the following sanity checks fail, Kamailio will not start:
1202
-     * the version of the library the TLS module was compiled with is "too
1203
-       different" from the library used at runtime. The versions should
1204
-       have the same major, minor and fix level (e.g.: 0.9.8a and 0.9.8c
1205
-       are ok, but 0.9.8 and 0.9.9 are not)
1206
-     * the OpenSSL library used at compile time and the one used at
1207
-       runtime have different Kerberos options
1208
-
1209
-   By default tls_force_run is disabled.
1210
-
1211
-   Example 1.37. Set tls_force_run parameter
1212
-...
1213
-modparam("tls", "tls_force_run", 11)
1214
-...
1215
-
1216
-10.27. session_cache (boolean)
1217
-
1218
-   If enabled Kamailio will do caching of the TLS sessions data,
1219
-   generation a session_id and sending it back to client.
1220
-
1221
-   By default TLS session caching is disabled (0).
1222
-
1223
-   Example 1.38. Set session_cache parameter
1224
-...
1225
-modparam("tls", "session_cache", 1)
1226
-...
1227
-
1228
-10.28. session_id (str)
1229
-
1230
-   The value for session ID context, making sense when session caching is
1231
-   enabled.
1232
-
1233
-   By default TLS session_id is "kamailio-tls-5.x.y".
1234
-
1235
-   Example 1.39. Set session_id parameter
1236
-...
1237
-modparam("tls", "session_id", "my-session-id-context")
1238
-...
1239
-
1240
-10.29. renegotiation (boolean)
1241
-
1242
-   If enabled Kamailio will allow renegotiations of TLS connection
1243
-   initiated by the client. This may expose to a security risk if the
1244
-   client is not a trusted peer and keeps renegotiating, consuming CPU and
1245
-   bandwidth resources.
1246
-
1247
-   By default TLS renegotiation is disabled (0).
1248
-
1249
-   Example 1.40. Set renegotiation parameter
1250
-...
1251
-modparam("tls", "renegotiation", 1)
1252
-...
1253
-
1254
-10.30. config (string)
1255
-
1256
-   Sets the name of the TLS specific configuration file or configuration
1257
-   directory.
1258
-
1259
-   If set the TLS module will load a special configuration file or
1260
-   configuration files from configuration directory, in which different
1261
-   TLS parameters can be specified on a per role (server or client) and
1262
-   domain basis (for now only IPs). The corresponding module parameters
1263
-   will be ignored if a separate configuration file is used.
1264
-
1265
-   If the file or directory name starts with a '.' the path will be
1266
-   relative to the working directory (at runtime). If it starts with a '/'
1267
-   it will be an absolute path and if it starts with anything else the
1268
-   path will be relative to the main config file directory (e.g.: for
1269
-   kamailio -f /etc/kamailio/kamailio.cfg it will be relative to
1270
-   /etc/kamailio/).
1271
-
1272
-   By default no TLS configuration file is specified.
1273
-
1274
-   The following parameters can be set in the config file, for each
1275
-   domain:
1276
-     * tls_method - (str) - TLS methods
1277
-     * verify_certificate - (bool) - see modparam
1278
-     * require_certificate - (bool) - see modparam
1279
-     * verify_client - (str) - see modparam
1280
-     * private_key - (str) - see modparam
1281
-     * certificate - (str) - see modparam
1282
-     * verify_depth - (int) - see modparam
1283
-     * ca_list - (str) - see modparam
1284
-     * crl - (str) - see modparam
1285
-     * cipher_list - (str) - see modparam
1286
-     * server_name - (str) - SNI (server name identification)
1287
-     * server_name_mode - (int) - how to match server_name
1288
-     * server_id - (str) - server id
1289
-
1290
-   The value for server_name_mode specifies how to match the server_name
1291
-   (SNI). If set to 1, match the domain and all its subdomains. If set to
1292
-   2, match only the subdomains. If set to 0 (or anything else), match
1293
-   only the domain given in server_name.
1294
-
1295
-   The value for server_id can be any string, being used to match TLS
1296
-   client config profile, overriding the match on ip:port and server_name.
1297
-   This is the recommended way for selecting a specific TLS client config
1298
-   profile, because the local or remote port is hard to predict for a
1299
-   stream connection - see parameter xavp_cfg to learn how to enable it.
1300
-
1301
-   All the parameters that take filenames as values will be resolved using
1302
-   the same rules as for the tls config filename itself: starting with a
1303
-   '.' means relative to the working directory, a '/' means an absolute
1304
-   path and anything else a path relative to the directory of the current
1305
-   Kamailio main config file.
1306
-
1307
-   Kamailio acts as a server when it accepts a connection and as a client
1308
-   when it initiates a new connection by itself (it connects to
1309
-   something).
1310
-
1311
-   The tls.cfg consists on a set of server and client TLS domain profiles.
1312
-   A server TLS domain profile starts with [server:domain]. A client TLS
1313
-   domain profile starts with [client:domain]. The tokens 'server' and
1314
-   'client' are static values. The 'domain' part can be: 'ip:port' - the
1315
-   IP address and port to match with the TLS connection; 'default' -
1316
-   (static string) for client and server profiles to be used when no other
1317
-   profile is matched; 'any' - (static string) for client and server
1318
-   profiles to be matched based on 'server_name', no matter of IP and port
1319
-   of the TLS connection.
1320
-
1321
-   There can be only one of each [server:default] and [client:default]
1322
-   profile definitions. Other profiles can be defined many times with the
1323
-   same domain ('ip:port' or 'any'), but in that case they must have
1324
-   'server_name' set for matching SNI.
1325
-
1326
-   It is highly recommended to have [server:default] and [client:default]
1327
-   profile definitions. They are needed when SNI is not yet available. If
1328
-   SNI is provided, then the profile definition is searched again to match
1329
-   on 'server_name'.
1330
-
1331
-   Example 1.41. Sample TLS Config File
1332
-...
1333
-[server:default]
1334
-method = TLSv1
1335
-verify_certificate = yes
1336
-require_certificate = yes
1337
-private_key = default_key.pem
1338
-certificate = default_cert.pem
1339
-ca_list = default_ca.pem
1340
-crl = default_crl.pem
1341
-
1342
-[client:default]
1343
-verify_certificate = yes
1344
-require_certificate = yes
1345
-
1346
-# more relaxed for connection on the loopback interface
1347
-[server:127.0.0.1:5061]
1348
-method = TLSv1
1349
-verify_certificate = yes
1350
-require_certificate = no
1351
-private_key = local_kamailio_org_key.pem
1352
-certificate = local_kamailio_org_cert.pem
1353
-verify_depth = 3
1354
-ca_list = local_ca.pem
1355
-server_name = kamailio.org
1356
-
1357
-[client:127.0.0.1:5061]
1358
-method = TLSv1
1359
-verify_certificate = yes
1360
-require_certificate = yes
1361
-private_key = default_key.pem
1362
-certificate = default_cert.pem
1363
-ca_list = default_ca.pem
1364
-crl = default_crl.pem
1365
-server_name = kamailio.org
1366
-server_id = kamailio.org
1367
-
1368
-# server profile on any address
1369
-[server:any]
1370
-method = TLSv1
1371
-verify_certificate = yes