| 1 |
TLS Module |
| 2 |
|
| 3 |
Andrei Pelinescu-Onciul |
| 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 |
| 18 |
__________________________________________________________________ |
| 19 |
|
| 20 |
Table of Contents |
| 21 |
|
| 22 |
1. Admin Guide |
| 23 |
|
| 24 |
1. Overview |
| 25 |
2. Quick Start |
| 26 |
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. private_key_password (string) |
| 39 |
10.5. key_password_mode (int) |
| 40 |
10.6. ca_list (string) |
| 41 |
10.7. ca_path (str) |
| 42 |
10.8. crl (string) |
| 43 |
10.9. verify_certificate (boolean) |
| 44 |
10.10. verify_depth (integer) |
| 45 |
10.11. require_certificate (boolean) |
| 46 |
10.12. cipher_list (string) |
| 47 |
10.13. server_name (string) |
| 48 |
10.14. connection_timeout (int) |
| 49 |
10.15. tls_disable_compression (boolean) |
| 50 |
10.16. ssl_release_buffers (integer) |
| 51 |
10.17. ssl_freelist_max_len (integer) |
| 52 |
10.18. ssl_max_send_fragment (integer) |
| 53 |
10.19. ssl_read_ahead (boolean) |
| 54 |
10.20. send_close_notify (boolean) |
| 55 |
10.21. con_ct_wq_max (integer) |
| 56 |
10.22. ct_wq_max (integer) |
| 57 |
10.23. ct_wq_blk_size (integer) |
| 58 |
10.24. tls_log (int) |
| 59 |
10.25. tls_debug (int) |
| 60 |
10.26. low_mem_threshold1 (integer) |
| 61 |
10.27. low_mem_threshold2 (integer) |
| 62 |
10.28. tls_force_run (boolean) |
| 63 |
10.29. session_cache (boolean) |
| 64 |
10.30. session_id (str) |
| 65 |
10.31. renegotiation (boolean) |
| 66 |
10.32. init_mode (int) |
| 67 |
10.33. config (string) |
| 68 |
10.34. xavp_cfg (string) |
| 69 |
10.35. event_callback (str) |
| 70 |
10.36. rand_engine (str) |
| 71 |
10.37. engine (string) |
| 72 |
10.38. engine_config (string) |
| 73 |
10.39. engine_algorithms (string) |
| 74 |
10.40. verify_client (string) |
| 75 |
10.41. provider_quirks (integer) |
| 76 |
10.42. provider_quirks_config (string) |
| 77 |
10.43. keylog_mode (int) |
| 78 |
10.44. keylog_file (str) |
| 79 |
10.45. keylog_peer (str) |
| 80 |
|
| 81 |
11. Functions |
| 82 |
|
| 83 |
11.1. is_peer_verified() |
| 84 |
11.2. tls_set_connect_server_id(srvid) |
| 85 |
|
| 86 |
12. RPC Commands |
| 87 |
|
| 88 |
12.1. tls.info |
| 89 |
12.2. tls.list |
| 90 |
12.3. tls.options |
| 91 |
12.4. tls.kill |
| 92 |
12.5. tls.reload |
| 93 |
|
| 94 |
13. Status |
| 95 |
|
| 96 |
13.1. License |
| 97 |
13.2. History |
| 98 |
|
| 99 |
14. Event Routes |
| 100 |
|
| 101 |
14.1. event_route[tls:connection-out] |
| 102 |
|
| 103 |
15. TLS With Database Backend |
| 104 |
|
| 105 |
List of Examples |
| 106 |
|
| 107 |
1.1. Quick Start Basic Config |
| 108 |
1.2. Compiling TLS with Debug Messages |
| 109 |
1.3. Set tls_method parameter |
| 110 |
1.4. Set certificate parameter |
| 111 |
1.5. Set private_key parameter |
| 112 |
1.6. Set private_key_password parameter |
| 113 |
1.7. Set key_password_mode parameter |
| 114 |
1.8. Set ca_list parameter |
| 115 |
1.9. Set ca_path parameter |
| 116 |
1.10. Set crl parameter |
| 117 |
1.11. Set verify_certificate parameter |
| 118 |
1.12. Set verify_depth parameter |
| 119 |
1.13. Set require_certificate parameter |
| 120 |
1.14. Set cipher_list parameter |
| 121 |
1.15. Set server_name parameter |
| 122 |
1.16. Set connection_timeout parameter |
| 123 |
1.17. Set tls.connection_timeout at runtime |
| 124 |
1.18. Set tls_disable_compression parameter |
| 125 |
1.19. Set ssl_release_buffers parameter |
| 126 |
1.20. Set ssl_freelist_max_len parameter |
| 127 |
1.21. Set ssl_max_send_fragment parameter |
| 128 |
1.22. Set ssl_read_ahead parameter |
| 129 |
1.23. Set send_close_notify parameter |
| 130 |
1.24. Set tls.send_close_notify at runtime |
| 131 |
1.25. Set con_ct_wq_max parameter |
| 132 |
1.26. Set tls.con_ct_wq_max at runtime |
| 133 |
1.27. Set ct_wq_max parameter |
| 134 |
1.28. Set tls.ct_wq_max at runtime |
| 135 |
1.29. Set ct_wq_blk_size parameter |
| 136 |
1.30. Set tls.ct_wq_max at runtime |
| 137 |
1.31. Set tls_log parameter |
| 138 |
1.32. Set tls.log at runtime |
| 139 |
1.33. Set tls_debug parameter |
| 140 |
1.34. Set tls.debug at runtime |
| 141 |
1.35. Set low_mem_threshold1 parameter |
| 142 |
1.36. Set tls.low_mem_threshold1 at runtime |
| 143 |
1.37. Set tls.low_mem_threshold2 parameter |
| 144 |
1.38. Set tls.low_mem_threshold2 at runtime |
| 145 |
1.39. Set tls_force_run parameter |
| 146 |
1.40. Set session_cache parameter |
| 147 |
1.41. Set session_id parameter |
| 148 |
1.42. Set renegotiation parameter |
| 149 |
1.43. Set init_mode parameter |
| 150 |
1.44. Sample TLS Config File |
| 151 |
1.45. Set config parameter |
| 152 |
1.46. Change and reload the TLS configuration at runtime |
| 153 |
1.47. Set xavp_cfg parameter |
| 154 |
1.48. Set event_callback parameter |
| 155 |
1.49. Set rand_engine parameter |
| 156 |
1.50. Set verify_client modparam parameter |
| 157 |
1.51. Set verify_client tls.cfg parameter |
| 158 |
1.52. Set provider_quirks modparam parameter |
| 159 |
1.53. Set provider_quirks_config modparam parameter |
| 160 |
1.54. Set keylog_mode parameter |
| 161 |
1.55. Set keylog_file parameter |
| 162 |
1.56. Set keylog_peer parameter |
| 163 |
1.57. is_peer_verified usage |
| 164 |
1.58. tls_set_connect_server_id usage |
| 165 |
1.59. Use of event_route[tls:connection-out] |
| 166 |
|
| 167 |
Chapter 1. Admin Guide |
| 168 |
|
| 169 |
Table of Contents |
| 170 |
|
| 171 |
1. Overview |
| 172 |
2. Quick Start |
| 173 |
3. Important Notes |
| 174 |
4. Compiling the TLS Module |
| 175 |
5. TLS and Low Memory |
| 176 |
6. TLS Debugging |
| 177 |
7. Known Limitations |
| 178 |
8. Quick Certificate Howto |
| 179 |
9. HSM Howto |
| 180 |
10. Parameters |
| 181 |
|
| 182 |
10.1. tls_method (string) |
| 183 |
10.2. certificate (string) |
| 184 |
10.3. private_key (string) |
| 185 |
10.4. private_key_password (string) |
| 186 |
10.5. key_password_mode (int) |
| 187 |
10.6. ca_list (string) |
| 188 |
10.7. ca_path (str) |
| 189 |
10.8. crl (string) |
| 190 |
10.9. verify_certificate (boolean) |
| 191 |
10.10. verify_depth (integer) |
| 192 |
10.11. require_certificate (boolean) |
| 193 |
10.12. cipher_list (string) |
| 194 |
10.13. server_name (string) |
| 195 |
10.14. connection_timeout (int) |
| 196 |
10.15. tls_disable_compression (boolean) |
| 197 |
10.16. ssl_release_buffers (integer) |
| 198 |
10.17. ssl_freelist_max_len (integer) |
| 199 |
10.18. ssl_max_send_fragment (integer) |
| 200 |
10.19. ssl_read_ahead (boolean) |
| 201 |
10.20. send_close_notify (boolean) |
| 202 |
10.21. con_ct_wq_max (integer) |
| 203 |
10.22. ct_wq_max (integer) |
| 204 |
10.23. ct_wq_blk_size (integer) |
| 205 |
10.24. tls_log (int) |
| 206 |
10.25. tls_debug (int) |
| 207 |
10.26. low_mem_threshold1 (integer) |
| 208 |
10.27. low_mem_threshold2 (integer) |
| 209 |
10.28. tls_force_run (boolean) |
| 210 |
10.29. session_cache (boolean) |
| 211 |
10.30. session_id (str) |
| 212 |
10.31. renegotiation (boolean) |
| 213 |
10.32. init_mode (int) |
| 214 |
10.33. config (string) |
| 215 |
10.34. xavp_cfg (string) |
| 216 |
10.35. event_callback (str) |
| 217 |
10.36. rand_engine (str) |
| 218 |
10.37. engine (string) |
| 219 |
10.38. engine_config (string) |
| 220 |
10.39. engine_algorithms (string) |
| 221 |
10.40. verify_client (string) |
| 222 |
10.41. provider_quirks (integer) |
| 223 |
10.42. provider_quirks_config (string) |
| 224 |
10.43. keylog_mode (int) |
| 225 |
10.44. keylog_file (str) |
| 226 |
10.45. keylog_peer (str) |
| 227 |
|
| 228 |
11. Functions |
| 229 |
|
| 230 |
11.1. is_peer_verified() |
| 231 |
11.2. tls_set_connect_server_id(srvid) |
| 232 |
|
| 233 |
12. RPC Commands |
| 234 |
|
| 235 |
12.1. tls.info |
| 236 |
12.2. tls.list |
| 237 |
12.3. tls.options |
| 238 |
12.4. tls.kill |
| 239 |
12.5. tls.reload |
| 240 |
|
| 241 |
13. Status |
| 242 |
|
| 243 |
13.1. License |
| 244 |
13.2. History |
| 245 |
|
| 246 |
14. Event Routes |
| 247 |
|
| 248 |
14.1. event_route[tls:connection-out] |
| 249 |
|
| 250 |
15. TLS With Database Backend |
| 251 |
|
| 252 |
1. Overview |
| 253 |
|
| 254 |
This module implements the TLS transport for Kamailio using the OpenSSL |
| 255 |
library. To enable the Kamailio TLS support this module must be loaded |
| 256 |
and enable_tls=yes core setting must be added to the Kamailio config |
| 257 |
file. |
| 258 |
|
| 259 |
Read the "Important Notes" section because it has relevant information |
| 260 |
about configuring properly the module for various libssl versions, |
| 261 |
components and operating systems. |
| 262 |
|
| 263 |
2. Quick Start |
| 264 |
|
| 265 |
The default kamailio.cfg file has basic tls support included, it has to |
| 266 |
be enabled with "#!define WITH_TLS" directive. |
| 267 |
|
| 268 |
The most important parameters to set the path to the public certificate |
| 269 |
and private key files. You can either have them in different file or in |
| 270 |
the same file in PEM format. The parameters for them are certificate |
| 271 |
and private_key. They can be given as modparam or provided in the |
| 272 |
profiles of tls.cfg file. |
| 273 |
|
| 274 |
When installing tls module of kamailio, a sample 'tls.cfg' file is |
| 275 |
deployed in the same folder with 'kamailio.cfg'. For freshly generated |
| 276 |
self signed certificates make must be called from tls folder |
| 277 |
make install-tls-cert |
| 278 |
|
| 279 |
HINT: be sure you have enable_tls=yes to your kamailio.cfg. |
| 280 |
|
| 281 |
Example 1.1. Quick Start Basic Config |
| 282 |
#... |
| 283 |
loadmodule "sl.so" |
| 284 |
loadmodule "tls.so" |
| 285 |
|
| 286 |
modparam("tls", "private_key", "./server-test.pem") |
| 287 |
modparam("tls", "certificate", "./server-test.pem") |
| 288 |
modparam("tls", "ca_list", "./calist.pem") |
| 289 |
|
| 290 |
enable_tls=yes |
| 291 |
|
| 292 |
request_route { |
| 293 |
if(proto != TLS) { |
| 294 |
sl_send_reply("403", "Accepting TLS Only"); |
| 295 |
exit; |
| 296 |
} |
| 297 |
... |
| 298 |
} |
| 299 |
|
| 300 |
3. Important Notes |
| 301 |
|
| 302 |
The TLS module needs some special options enabled when compiling |
| 303 |
Kamailio. These options are enabled by default, however in case you are |
| 304 |
using a modified Kamailio version or Makefile, make sure that you |
| 305 |
enable -DUSE_TLS and -DTLS_HOOKS (or compile with make TLS_HOOKS=1 |
| 306 |
which will take care of both options). |
| 307 |
|
| 308 |
To quickly check if your Kamailio version was compiled with these |
| 309 |
options, run kamailio -V and look for USE_TLS and TLS_HOOKS among the |
| 310 |
flags. |
| 311 |
|
| 312 |
This module includes several workarounds for various Openssl bugs (like |
| 313 |
compression and Kerberos using the wrong memory allocations functions, |
| 314 |
low memory problems a.s.o). On startup it will try to enable the needed |
| 315 |
workarounds based on the OpenSSL library version. Each time a known |
| 316 |
problem is detected and a workaround is enabled, a message will be |
| 317 |
logged. In general it is recommended to compile this module on the same |
| 318 |
machine or a similar machine to where kamailio will be run or to link |
| 319 |
it statically with libssl. For example if on the compile machine |
| 320 |
OpenSSL does not have the Kerberos support enabled, but on the target |
| 321 |
machine a Kerberos enabled OpenSSL library is installed, Kamailio |
| 322 |
cannot apply the needed workarounds and will refuse to start. The same |
| 323 |
thing will happen if the OpenSSL versions are too different (to force |
| 324 |
Kamailio startup anyway, see the tls_force_run module parameter). |
| 325 |
|
| 326 |
Compression is fully supported if you have a new enough OpenSSL version |
| 327 |
(starting with 0.9.8). Although there are some problems with zlib |
| 328 |
compression in currently deployed OpenSSL versions (up to and including |
| 329 |
0.9.8d, see openssl bug #1468), the TLS module will automatically |
| 330 |
switch to its own fixed version. Note however that starting with |
| 331 |
Kamailio 3.1 compression is not enabled by default, due to the huge |
| 332 |
extra memory consumption that it causes (about 10x more memory). To |
| 333 |
enable it use modparam("tls", "tls_disable_compression", 0) (see |
| 334 |
tls_disable_compression). |
| 335 |
|
| 336 |
The TLS module includes workarounds for the following known openssl |
| 337 |
bugs: |
| 338 |
* openssl #1204 (disable SS_OP_TLS_BLOCK_PADDING_BUG if compression |
| 339 |
is enabled, for versions between 0.9.8 and 0.9.8c), |
| 340 |
* openssl #1468 (fix zlib compression memory allocation), |
| 341 |
* openssl #1467 (kerberos support will be disabled if the openssl |
| 342 |
version is less than 0.9.8e-beta1) |
| 343 |
* openssl #1491 (stop using tls in low memory situations due to the |
| 344 |
very high risk of openssl crashing or leaking memory). |
| 345 |
|
| 346 |
The bug reports can be viewed at http://rt.openssl.org/. |
| 347 |
|
| 348 |
Note 1: the tls module must be loaded before any other Kamailio module |
| 349 |
that uses libssl (OpenSSL library). A safe option is to have the tls |
| 350 |
module loaded first (be in the first "loadmodule" in kamailio.cfg). |
| 351 |
|
| 352 |
Note 2: for libssl v3.x, the core parameter "tls_threads_mode" has to |
| 353 |
be set, see the Core Cookbook for possible values. |
| 354 |
|
| 355 |
Note 3: using this module compiled with newer versions of libssl (e.g., |
| 356 |
v1.1+) may require Kamailio to be started with --atexit=no command line |
| 357 |
parameters to avoid calling C atexit callbacks inside the process |
| 358 |
ending during daemonize procedure as well as during shut down, which |
| 359 |
can lead to crashes because it destroys and then accesses shared |
| 360 |
memory. For example, such case has been reported for Ubuntu 20.04 or |
| 361 |
RedHat 8. |
| 362 |
|
| 363 |
Note 4: with some particular combination of OS, openssl and |
| 364 |
mysql-client libraries, there were reports of random crashes, in such |
| 365 |
case try to set the db_mysql module parameter opt_ssl_mode to 1. |
| 366 |
|
| 367 |
4. Compiling the TLS Module |
| 368 |
|
| 369 |
In most case compiling the TLS module is as simple as: |
| 370 |
make -C modules/tls |
| 371 |
|
| 372 |
or |
| 373 |
make modules modules=modules/tls |
| 374 |
|
| 375 |
or (compiling whole Kamailio and the tls module) |
| 376 |
make all include_modules=tls |
| 377 |
|
| 378 |
. |
| 379 |
|
| 380 |
However in some cases the OpenSSL library requires linking with other |
| 381 |
libraries. For example compiling the OpenSSL library with Kerberos and |
| 382 |
zlib-shared support will require linking the TLS module with libkrb5 |
| 383 |
and libz. In this case just add TLS_EXTRA_LIBS="library list" to make's |
| 384 |
command line. E.g.: |
| 385 |
make TLS_EXTRA_LIBS="-lkrb5 -lz" all include_modules=tls |
| 386 |
|
| 387 |
In general, if Kamailio fails to start with a symbol not found error |
| 388 |
when trying to load the TLS module (check the log), it means some |
| 389 |
needed library was not linked and it must be added to TLS_EXTRA_LIBS |
| 390 |
|
| 391 |
Elliptic Curve Diffie-Hellman (EDCH)-Ciphers are only supported in |
| 392 |
OpenSSL 1.0.0e and later. |
| 393 |
|
| 394 |
5. TLS and Low Memory |
| 395 |
|
| 396 |
The Openssl library doesn't handle low memory situations very well. If |
| 397 |
memory allocations start to fail (due to memory shortage), Openssl can |
| 398 |
crash or cause memory leaks (making the memory shortage even worse). As |
| 399 |
of this writing all Openssl versions were affected (including 0.9.8e), |
| 400 |
see Openssl bug #1491. The TLS module has some workarounds for |
| 401 |
preventing this problem (see low_mem_threshold1 and |
| 402 |
low_mem_threshold2), however starting Kamailio with enough shared |
| 403 |
memory is higly recommended. When this is not possible a quick way to |
| 404 |
significantly reduce Openssl memory usage it to disable compression |
| 405 |
(see tls_disable_compression). |
| 406 |
|
| 407 |
6. TLS Debugging |
| 408 |
|
| 409 |
Debugging messages can be selectively enabled by recompiling the TLS |
| 410 |
module with a combination of the following defines: |
| 411 |
* TLS_WR_DEBUG - debug messages for the write/send part. |
| 412 |
* TLS_RD_DEBUG - debug messages for the read/receive part. |
| 413 |
* TLS_BIO_DEBUG - debug messages for the custom BIO. |
| 414 |
|
| 415 |
Example 1.2. Compiling TLS with Debug Messages |
| 416 |
make -C modules/tls extra_defs="-DTLS_WR_DEBUG -DTLS_RD_DEBUG" |
| 417 |
|
| 418 |
To change the level at which the debug messages are logged, change the |
| 419 |
tls_debug module parameter. |
| 420 |
|
| 421 |
7. Known Limitations |
| 422 |
|
| 423 |
The private key must not be encrypted (Kamailio cannot ask you for a |
| 424 |
password on startup). |
| 425 |
|
| 426 |
The TLS certificate verifications ignores the certificate name, Subject |
| 427 |
Altname and IP extensions, it just checks if the certificate is signed |
| 428 |
by a recognized CA. One can use the select framework to try to overcome |
| 429 |
this limitation (check in the script for the contents of various |
| 430 |
certificate fields), but this is not only slow, but also not exactly |
| 431 |
standard conforming (the verification should happen during TLS |
| 432 |
connection establishment and not after). |
| 433 |
|
| 434 |
This documentation is incomplete. The provided selects are not |
| 435 |
documented in this file. A list with all the ones implemented by the |
| 436 |
TLS module can be found in the Cookbook |
| 437 |
https://www.kamailio.org/wikidocs/ in the section Selects for the |
| 438 |
respective version of Kamailio. |
| 439 |
|
| 440 |
8. Quick Certificate Howto |
| 441 |
|
| 442 |
There are various ways to create, sign certificates and manage small |
| 443 |
CAs (Certificate Authorities). If you are in a hurry and everything you |
| 444 |
have are the installed OpenSSL libraries and utilities, read on. |
| 445 |
|
| 446 |
Assumptions: we run our own CA. |
| 447 |
|
| 448 |
Warning: in this example no key is encrypted. The client and server |
| 449 |
private keys must not be encrypted (Kamailio doesn't support encrypted |
| 450 |
keys), so make sure the corresponding files are readable only by |
| 451 |
trusted people. You should use a password to protect your CA private |
| 452 |
key. |
| 453 |
|
| 454 |
Assumptions |
| 455 |
------------ |
| 456 |
|
| 457 |
The default openssl configuration (usually /etc/ssl/openssl.cnf) |
| 458 |
default_ca section is the one distributed with openssl and uses the default |
| 459 |
directories: |
| 460 |
|
| 461 |
... |
| 462 |
|
| 463 |
default_ca = CA_default # The default ca section |
| 464 |
|
| 465 |
[ CA_default ] |
| 466 |
|
| 467 |
dir = ./demoCA # Where everything is kept |
| 468 |
certs = $dir/certs # Where the issued certs are kept |
| 469 |
crl_dir = $dir/crl # Where the issued crl are kept |
| 470 |
database = $dir/index.txt # database index file. |
| 471 |
#unique_subject = no # Set to 'no' to allow creation of |
| 472 |
# several certificates with same subject |
| 473 |
. |
| 474 |
new_certs_dir = $dir/newcerts # default place for new certs. |
| 475 |
|
| 476 |
certificate = $dir/cacert.pem # The CA certificate |
| 477 |
serial = $dir/serial # The current serial number |
| 478 |
crlnumber = $dir/crlnumber # the current CRL number |
| 479 |
crl = $dir/crl.pem # The current CRL |
| 480 |
private_key = $dir/private/cakey.pem# The private key |
| 481 |
RANDFILE = $dir/private/.rand # private random number file |
| 482 |
|
| 483 |
... |
| 484 |
|
| 485 |
If this is not the case create a new OpenSSL config file that uses the above |
| 486 |
paths for the default CA and add to all the openssl commands: |
| 487 |
-config filename. E.g.: |
| 488 |
openssl ca -config my_openssl.cnf -in kamailio1_cert_req.pem -out kamail |
| 489 |
io1_cert.pem |
| 490 |
|
| 491 |
|
| 492 |
Creating the CA certificate |
| 493 |
--------------------------- |
| 494 |
1. Create the CA directory |
| 495 |
mkdir ca |
| 496 |
cd ca |
| 497 |
|
| 498 |
2. Create the CA directory structure and files (see ca(1)) |
| 499 |
mkdir demoCA #default CA name, edit /etc/ssl/openssl.cnf |
| 500 |
mkdir demoCA/private |
| 501 |
mkdir demoCA/newcerts |
| 502 |
touch demoCA/index.txt |
| 503 |
echo 01 >demoCA/serial |
| 504 |
echo 01 >demoCA/crlnumber |
| 505 |
|
| 506 |
2. Create CA private key |
| 507 |
openssl genrsa -out demoCA/private/cakey.pem 2048 |
| 508 |
chmod 600 demoCA/private/cakey.pem |
| 509 |
|
| 510 |
3. Create CA self-signed certificate |
| 511 |
openssl req -out demoCA/cacert.pem -x509 -new -key demoCA/private/cake |
| 512 |
y.pem |
| 513 |
|
| 514 |
|
| 515 |
Creating a server/client TLS certificate |
| 516 |
---------------------------------------- |
| 517 |
1. Create a certificate request (and its private key in privkey.pem) |
| 518 |
|
| 519 |
openssl req -out kamailio1_cert_req.pem -new -nodes |
| 520 |
|
| 521 |
WARNING: the organization name should be the same as in the CA certifica |
| 522 |
te. |
| 523 |
|
| 524 |
2. Sign it with the CA certificate |
| 525 |
openssl ca -in kamailio1_cert_req.pem -out kamailio1_cert.pem |
| 526 |
|
| 527 |
3. Copy kamailio1_cert.pem to your Kamailio configuration dir |
| 528 |
|
| 529 |
|
| 530 |
Setting Kamailio to use the TLS certificate |
| 531 |
--------------------------------------------- |
| 532 |
1. Create the CA list file: |
| 533 |
for each of your CA certificates that you intend to use do: |
| 534 |
cat cacert.pem >>calist.pem |
| 535 |
|
| 536 |
2. Copy your Kamailio certificate, private key and ca list file to your |
| 537 |
intended machine (preferably in your Kamailio configuration directory, |
| 538 |
this is the default place Kamailio searches for). |
| 539 |
|
| 540 |
3. Set up kamailio.cfg to use the certificate |
| 541 |
if your Kamailio certificate name is different from cert.pem or it is no |
| 542 |
t |
| 543 |
placed in Kamailio config directory, add to your kamailio.cfg: |
| 544 |
modparam("tls", "certificate", "/path/cert_file_name") |
| 545 |
|
| 546 |
4. Set up Kamailio to use the private key |
| 547 |
if your private key is not contained in the same file as the certificate |
| 548 |
(or the certificate name is not the default cert.pem), add to your |
| 549 |
kamailio.cfg: |
| 550 |
modparam("tls", "private_key", "/path/private_key_file") |
| 551 |
|
| 552 |
5. Set up Kamailio to use the CA list (optional) |
| 553 |
The CA list is not used for your server certificate - it's used to approve ot |
| 554 |
her servers |
| 555 |
and clients connecting to your server with a client certificate or for approv |
| 556 |
ing |
| 557 |
a certificate used by a server your server connects to. |
| 558 |
add to your Kamailio.cfg: |
| 559 |
modparam("tls", "ca_list", "/path/ca_list_file") |
| 560 |
|
| 561 |
6. Set up TLS authentication options: |
| 562 |
modparam("tls", "verify_certificate", 1) |
| 563 |
modparam("tls", "require_certificate", 1) |
| 564 |
(for more information see the module parameters documentation) |
| 565 |
|
| 566 |
|
| 567 |
Revoking a certificate and using a CRL |
| 568 |
-------------------------------------- |
| 569 |
1. Revoking a certificate: |
| 570 |
openssl ca -revoke bad_cert.pem |
| 571 |
|
| 572 |
2. Generate/update the certificate revocation list: |
| 573 |
openssl ca -gencrl -out my_crl.pem |
| 574 |
|
| 575 |
3. Copy my_crl.pem to your Kamailio config directory. |
| 576 |
|
| 577 |
4. Set up kamailio.cfg to use the CRL: |
| 578 |
modparam("tls", "crl", "path/my_crl.pem") |
| 579 |
|
| 580 |
9. HSM Howto |
| 581 |
|
| 582 |
This documents OpenSSL engine support for private keys in HSM. |
| 583 |
|
| 584 |
Assumptions: an OpenSSL engine configured with private key. We still |
| 585 |
require the certificate file and list of CA certificates per a regular |
| 586 |
TLS configuration. |
| 587 |
|
| 588 |
Thales Luna Example |
| 589 |
-------------------- |
| 590 |
|
| 591 |
... |
| 592 |
# Example for Thales Luna |
| 593 |
modparam("tls", "engine", "gem") |
| 594 |
modparam("tls", "engine_config", "/usr/local/etc/kamailio/thales.cnf") |
| 595 |
modparam("tls", "engine_algorithms", "EC") |
| 596 |
... |
| 597 |
|
| 598 |
/usr/local/etc/kamailio/thales.cnf is an OpenSSL config format file used to |
| 599 |
bootstrap the engine, e.g., pass the PIN. |
| 600 |
|
| 601 |
... |
| 602 |
# the key kamailio is mandatory |
| 603 |
kamailio = openssl_init |
| 604 |
|
| 605 |
[ openssl_init ] |
| 606 |
engines = engine_section |
| 607 |
|
| 608 |
[ engine_section ] |
| 609 |
# gem is the name of the Thales Luna OpenSSL engine |
| 610 |
gem = gem_section |
| 611 |
|
| 612 |
[ gem_section ] |
| 613 |
# from Thales documentation |
| 614 |
dynamic_path = /usr/lib64/engines-1.1/gem.so |
| 615 |
ENGINE_INIT = 0:20:21:password=1234-ABCD-5678-EFGH |
| 616 |
... |
| 617 |
|
| 618 |
|
| 619 |
Thales nShield Connect |
| 620 |
---------------------- |
| 621 |
|
| 622 |
Place holder |
| 623 |
|
| 624 |
10. Parameters |
| 625 |
|
| 626 |
10.1. tls_method (string) |
| 627 |
10.2. certificate (string) |
| 628 |
10.3. private_key (string) |
| 629 |
10.4. private_key_password (string) |
| 630 |
10.5. key_password_mode (int) |
| 631 |
10.6. ca_list (string) |
| 632 |
10.7. ca_path (str) |
| 633 |
10.8. crl (string) |
| 634 |
10.9. verify_certificate (boolean) |
| 635 |
10.10. verify_depth (integer) |
| 636 |
10.11. require_certificate (boolean) |
| 637 |
10.12. cipher_list (string) |
| 638 |
10.13. server_name (string) |
| 639 |
10.14. connection_timeout (int) |
| 640 |
10.15. tls_disable_compression (boolean) |
| 641 |
10.16. ssl_release_buffers (integer) |
| 642 |
10.17. ssl_freelist_max_len (integer) |
| 643 |
10.18. ssl_max_send_fragment (integer) |
| 644 |
10.19. ssl_read_ahead (boolean) |
| 645 |
10.20. send_close_notify (boolean) |
| 646 |
10.21. con_ct_wq_max (integer) |
| 647 |
10.22. ct_wq_max (integer) |
| 648 |
10.23. ct_wq_blk_size (integer) |
| 649 |
10.24. tls_log (int) |
| 650 |
10.25. tls_debug (int) |
| 651 |
10.26. low_mem_threshold1 (integer) |
| 652 |
10.27. low_mem_threshold2 (integer) |
| 653 |
10.28. tls_force_run (boolean) |
| 654 |
10.29. session_cache (boolean) |
| 655 |
10.30. session_id (str) |
| 656 |
10.31. renegotiation (boolean) |
| 657 |
10.32. init_mode (int) |
| 658 |
10.33. config (string) |
| 659 |
10.34. xavp_cfg (string) |
| 660 |
10.35. event_callback (str) |
| 661 |
10.36. rand_engine (str) |
| 662 |
10.37. engine (string) |
| 663 |
10.38. engine_config (string) |
| 664 |
10.39. engine_algorithms (string) |
| 665 |
10.40. verify_client (string) |
| 666 |
10.41. provider_quirks (integer) |
| 667 |
10.42. provider_quirks_config (string) |
| 668 |
10.43. keylog_mode (int) |
| 669 |
10.44. keylog_file (str) |
| 670 |
10.45. keylog_peer (str) |
| 671 |
|
| 672 |
10.1. tls_method (string) |
| 673 |
|
| 674 |
Sets the TLS protocol method. Possible values are: |
| 675 |
* TLSv1.3+ - TLSv1.3 or newer (TLSv1.3, ...) connections are accepted |
| 676 |
(available starting with openssl/libssl v1.1.1) |
| 677 |
* TLSv1.3 - only TLSv1.3 connections are accepted (available starting |
| 678 |
with openssl/libssl v1.1.1) |
| 679 |
* TLSv1.2+ - TLSv1.2 or newer (TLSv1.3, ...) connections are accepted |
| 680 |
(available starting with openssl/libssl v1.1.1) |
| 681 |
* TLSv1.2 - only TLSv1.2 connections are accepted (available starting |
| 682 |
with openssl/libssl v1.0.1e) |
| 683 |
* TLSv1.1+ - TLSv1.1 or newer (TLSv1.2, ...) connections are accepted |
| 684 |
(available starting with openssl/libssl v1.0.1) |
| 685 |
* TLSv1.1 - only TLSv1.1 connections are accepted (available starting |
| 686 |
with openssl/libssl v1.0.1) |
| 687 |
* TLSv1+ - TLSv1.0 or newer (TLSv1.1, TLSv1.2, ...) connections are |
| 688 |
accepted. |
| 689 |
* TLSv1 - only TLSv1 (TLSv1.0) connections are accepted. This is the |
| 690 |
default value. |
| 691 |
* SSLv3 - only SSLv3 connections are accepted. Note: you shouldn't |
| 692 |
use SSLv3 for anything which should be secure. |
| 693 |
* SSLv2 - only SSLv2 connections, for old clients. Note: you |
| 694 |
shouldn't use SSLv2 for anything which should be secure. Newer |
| 695 |
versions of OpenSSL libraries don't include support for it anymore. |
| 696 |
* SSLv23 - any of the SSLv2, SSLv3 and TLSv1 or newer methods will be |
| 697 |
accepted. |
| 698 |
From the OpenSSL manual: "A TLS/SSL connection established with |
| 699 |
these methods may understand the SSLv3, TLSv1, TLSv1.1 and TLSv1.2 |
| 700 |
protocols. If extensions are required (for example server name) a |
| 701 |
client will send out TLSv1 client hello messages including |
| 702 |
extensions and will indicate that it also understands TLSv1.1, |
| 703 |
TLSv1.2 and permits a fallback to SSLv3. A server will support |
| 704 |
SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols. This is the best |
| 705 |
choice when compatibility is a concern." |
| 706 |
Note: For older OpenSSL library versions, this option allows SSLv2, |
| 707 |
with hello messages done over SSLv2. You shouldn't use SSLv2 or |
| 708 |
SSLv3 for anything which should be secure. |
| 709 |
|
| 710 |
If RFC 3261 conformance is desired, at least TLSv1 must be used. For |
| 711 |
compatibility with older clients SSLv23 is the option, but again, be |
| 712 |
aware of security concerns, SSLv2/3 as well as TLS v1.0 and v1.1 are |
| 713 |
being considered very insecure and are therefore deprecated since March |
| 714 |
2021 (RFC 8996). For current information about what's considered |
| 715 |
secure, please consult, IETF BCP 195, currently RFC 9325 - |
| 716 |
"Recommendations for Secure Use of Transport Layer Security (TLS) and |
| 717 |
Datagram Transport Layer Security (DTLS)" |
| 718 |
|
| 719 |
Example 1.3. Set tls_method parameter |
| 720 |
... |
| 721 |
modparam("tls", "tls_method", "TLSv1") |
| 722 |
... |
| 723 |
|
| 724 |
10.2. certificate (string) |
| 725 |
|
| 726 |
Sets the certificate file name. The certificate file can also contain |
| 727 |
the private key in PEM format. |
| 728 |
|
| 729 |
If the file name starts with a '.' the path will be relative to the |
| 730 |
working directory (at runtime). If it starts with a '/' it will be an |
| 731 |
absolute path and if it starts with anything else the path will be |
| 732 |
relative to the main config file directory (e.g.: for kamailio -f |
| 733 |
/etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/). |
| 734 |
|
| 735 |
The default value is /usr/local/etc/kamailio/cert.pem |
| 736 |
|
| 737 |
Example 1.4. Set certificate parameter |
| 738 |
... |
| 739 |
modparam("tls", "certificate", "/usr/local/etc/kamailio/my_certificate.pem") |
| 740 |
... |
| 741 |
|
| 742 |
10.3. private_key (string) |
| 743 |
|
| 744 |
Sets the private key file name. The private key can be in the same file |
| 745 |
as the certificate or in a separate file, specified by this |
| 746 |
configuration parameter. |
| 747 |
|
| 748 |
If the file name starts with a '.' the path will be relative to the |
| 749 |
working directory (at runtime). If it starts with a '/' it will be an |
| 750 |
absolute path and if it starts with anything else the path will be |
| 751 |
relative to the main config file directory (e.g.: for kamailio -f |
| 752 |
/etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/). |
| 753 |
|
| 754 |
Note: the private key can be contained in the same file as the |
| 755 |
certificate (just append it to the certificate file, e.g.: cat pkey.pem |
| 756 |
>> cert.pem) |
| 757 |
|
| 758 |
The default value is /usr/local/etc/kamailio/cert.pem |
| 759 |
|
| 760 |
Example 1.5. Set private_key parameter |
| 761 |
... |
| 762 |
modparam("tls", "private_key", "/usr/local/etc/kamailio/my_pkey.pem") |
| 763 |
... |
| 764 |
|
| 765 |
10.4. private_key_password (string) |
| 766 |
|
| 767 |
The password for the private key. |
| 768 |
|
| 769 |
The default value is empty. |
| 770 |
|
| 771 |
Example 1.6. Set private_key_password parameter |
| 772 |
... |
| 773 |
modparam("tls", "private_key_password", "secret") |
| 774 |
... |
| 775 |
|
| 776 |
10.5. key_password_mode (int) |
| 777 |
|
| 778 |
The mode to get the password for the private key. If 0, take it from |
| 779 |
the config "private_key_password". If 1, promt for it at start up. |
| 780 |
|
| 781 |
The default value is 0. |
| 782 |
|
| 783 |
Example 1.7. Set key_password_mode parameter |
| 784 |
... |
| 785 |
modparam("tls", "key_password_mode", 0) |
| 786 |
... |
| 787 |
|
| 788 |
10.6. ca_list (string) |
| 789 |
|
| 790 |
Sets the CA list file name. This file contains a list of all the |
| 791 |
trusted CAs certificates used when connecting to other SIP |
| 792 |
implementations. If a signature in a certificate chain belongs to one |
| 793 |
of the listed CAs, the verification of that certificate will succeed. |
| 794 |
|
| 795 |
If the file name starts with a '.' the path will be relative to the |
| 796 |
working directory (at runtime). If it starts with a '/' it will be an |
| 797 |
absolute path and if it starts with anything else the path will be |
| 798 |
relative to the main config file directory (e.g.: for kamailio -f |
| 799 |
/etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/). |
| 800 |
|
| 801 |
By default the CA file is not set. |
| 802 |
|
| 803 |
An easy way to create the CA list is to append each trusted trusted CA |
| 804 |
certificate in the PEM format to one file, e.g.: |
| 805 |
for f in trusted_cas/*.pem ; do cat "$f" >> ca_list.pem ; done |
| 806 |
|
| 807 |
See also verify_certificate, verify_depth, require_certificate and crl. |
| 808 |
|
| 809 |
Example 1.8. Set ca_list parameter |
| 810 |
... |
| 811 |
modparam("tls", "ca_list", "/usr/local/etc/kamailio/ca_list.pem") |
| 812 |
... |
| 813 |
|
| 814 |
10.7. ca_path (str) |
| 815 |
|
| 816 |
Sets the path with the trusted CA files, to be given as parameter |
| 817 |
SSL_CTX_load_verify_locations(). The certificates in ca_path are only |
| 818 |
looked up when required, e.g. when building the certificate chain or |
| 819 |
when actually performing the verification of a peer certificate. They |
| 820 |
are not given to the client (not loaded to be provided to |
| 821 |
SSL_CTX_set_client_CA_list()), only the ones in ca_list files are sent |
| 822 |
to the client. It requires to use c_rehash to generate the hash map for |
| 823 |
certificate search, for more see the manual of libssl for |
| 824 |
SSL_CTX_load_verify_locations() function. |
| 825 |
|
| 826 |
By default it is not set. |
| 827 |
|
| 828 |
Example 1.9. Set ca_path parameter |
| 829 |
... |
| 830 |
modparam("tls", "ca_path", "/usr/local/etc/kamailio/ca") |
| 831 |
... |
| 832 |
|
| 833 |
10.8. crl (string) |
| 834 |
|
| 835 |
Sets the certificate revocation list (CRL) file name. This file |
| 836 |
contains a list of revoked certificates. Any attempt to verify a |
| 837 |
revoked certificate will fail. |
| 838 |
|
| 839 |
If not set, no CRL list will be used. |
| 840 |
|
| 841 |
If the file name starts with a '.' the path will be relative to the |
| 842 |
working directory (at runtime). If it starts with a '/' it will be an |
| 843 |
absolute path and if it starts with anything else the path will be |
| 844 |
relative to the main config file directory (e.g.: for kamailio -f |
| 845 |
/etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/). |
| 846 |
|
| 847 |
Note |
| 848 |
|
| 849 |
If set, require_certificate should also be set or it will not have any |
| 850 |
effect. |
| 851 |
|
| 852 |
By default the CRL file name is not set. |
| 853 |
|
| 854 |
To update the CRL in a running Kamailio, make sure you configure TLS |
| 855 |
via a separate TLS config file (the config modparam) and issue a |
| 856 |
tls.reload RPC call, e.g.: |
| 857 |
$ kamcmd tls.reload |
| 858 |
|
| 859 |
A quick way to create the CRL in PEM format, using OpenSSL is: |
| 860 |
$ openssl ca -gencrl -keyfile cacert.key -cert cacert.pem -out my_crl.pem |
| 861 |
|
| 862 |
my_crl.pem will contain the signed list of the revoked certificates. |
| 863 |
|
| 864 |
To revoke a TLS certificate use something like: |
| 865 |
$ openssl ca -revoke bad_cert.pem -keyfile cacert.key -cert cacert.pem |
| 866 |
|
| 867 |
and then refresh the crl file using the command above. |
| 868 |
|
| 869 |
To display the CRL contents use: |
| 870 |
$ openssl crl -in crl.pem -noout -text |
| 871 |
|
| 872 |
See also ca_list, verify_certificate, verify_depth and |
| 873 |
require_certificate. |
| 874 |
|
| 875 |
Example 1.10. Set crl parameter |
| 876 |
... |
| 877 |
modparam("tls", "crl", "/usr/local/etc/kamailio/crl.pem") |
| 878 |
... |
| 879 |
|
| 880 |
10.9. verify_certificate (boolean) |
| 881 |
|
| 882 |
If enabled it will force certificate verification when connecting to |
| 883 |
other SIP servers.. For more information see the verify(1) OpenSSL man |
| 884 |
page. |
| 885 |
|
| 886 |
Note: the certificate verification will always fail if the ca_list is |
| 887 |
empty. |
| 888 |
|
| 889 |
See also: ca_list, require_certificate, verify_depth. |
| 890 |
|
| 891 |
By default the certificate verification is off. |
| 892 |
|
| 893 |
Example 1.11. Set verify_certificate parameter |
| 894 |
... |
| 895 |
modparam("tls", "verify_certificate", 1) |
| 896 |
... |
| 897 |
|
| 898 |
10.10. verify_depth (integer) |
| 899 |
|
| 900 |
Sets how far up the certificate chain will the certificate verification |
| 901 |
go in the search for a trusted CA. |
| 902 |
|
| 903 |
See also: ca_list, require_certificate, verify_certificate, |
| 904 |
|
| 905 |
The default value is 9. |
| 906 |
|
| 907 |
Example 1.12. Set verify_depth parameter |
| 908 |
... |
| 909 |
modparam("tls", "verify_depth", 9) |
| 910 |
... |
| 911 |
|
| 912 |
10.11. require_certificate (boolean) |
| 913 |
|
| 914 |
When enabled Kamailio will require a certificate from a client |
| 915 |
connecting to the TLS port. If the client does not offer a certificate |
| 916 |
and verify_certificate is on, certificate verification will fail. |
| 917 |
|
| 918 |
The default value is off. |
| 919 |
|
| 920 |
Example 1.13. Set require_certificate parameter |
| 921 |
... |
| 922 |
modparam("tls", "require_certificate", 1) |
| 923 |
... |
| 924 |
|
| 925 |
10.12. cipher_list (string) |
| 926 |
|
| 927 |
Sets the list of accepted ciphers. The list consists of cipher strings |
| 928 |
separated by colons. For more information on the cipher list format see |
| 929 |
the cipher(1) OpenSSL man page. |
| 930 |
|
| 931 |
The default value is not set (all the OpenSSL supported ciphers are |
| 932 |
enabled). |
| 933 |
|
| 934 |
Example 1.14. Set cipher_list parameter |
| 935 |
... |
| 936 |
modparam("tls", "cipher_list", "HIGH") |
| 937 |
... |
| 938 |
|
| 939 |
10.13. server_name (string) |
| 940 |
|
| 941 |
Sets the Server Name Indication (SNI) value. |
| 942 |
|
| 943 |
This is a TLS extension enabling one TLS server to serve multiple host |
| 944 |
names with unique certificates. |
| 945 |
|
| 946 |
The default value is empty (not set). |
| 947 |
|
| 948 |
Example 1.15. Set server_name parameter |
| 949 |
... |
| 950 |
modparam("tls", "server_name", "kamailio.org") |
| 951 |
... |
| 952 |
|
| 953 |
10.14. connection_timeout (int) |
| 954 |
|
| 955 |
Sets the amount of time after which an idle TLS connection will be |
| 956 |
closed, if no I/O ever occurred after the initial open. If an I/O event |
| 957 |
occurs, the timeout will be extended with tcp_connection_lifetime. The |
| 958 |
value is expressed in seconds. |
| 959 |
|
| 960 |
The default value is 10 min. |
| 961 |
|
| 962 |
If the value set is -1, the connection will never be close on idle. |
| 963 |
|
| 964 |
This setting can be changed also at runtime, via the RPC interface and |
| 965 |
config framework. The config variable name is tls.connection_timeout. |
| 966 |
|
| 967 |
Example 1.16. Set connection_timeout parameter |
| 968 |
... |
| 969 |
modparam("tls", "connection_timeout", 60) |
| 970 |
... |
| 971 |
|
| 972 |
Example 1.17. Set tls.connection_timeout at runtime |
| 973 |
$ kamcmd cfg.set_now_int tls connection_timeout 180 |
| 974 |
|
| 975 |
10.15. tls_disable_compression (boolean) |
| 976 |
|
| 977 |
If set compression over TLS will be disabled. Note that compression |
| 978 |
uses a lot of memory (about 10x more than with the compression |
| 979 |
disabled), so if you want to minimize memory usage is a good idea to |
| 980 |
disable it. TLS compression also expose you for the CRIME security |
| 981 |
vulnerability. |
| 982 |
|
| 983 |
By default TLS compression is disabled. |
| 984 |
|
| 985 |
Example 1.18. Set tls_disable_compression parameter |
| 986 |
... |
| 987 |
modparam("tls", "tls_disable_compression", 0) # enable |
| 988 |
... |
| 989 |
|
| 990 |
10.16. ssl_release_buffers (integer) |
| 991 |
|
| 992 |
Release internal OpenSSL read or write buffers as soon as they are no |
| 993 |
longer needed. Combined with ssl_freelist_max_len has the potential of |
| 994 |
saving a lot of memory ( ~ 32k per connection in the default |
| 995 |
configuration, or 16k + ssl_max_send_fragment). For Kamailio versions > |
| 996 |
3.0 it makes little sense to disable it (0) since the tls module |
| 997 |
already has its own internal buffering. |
| 998 |
|
| 999 |
A value of -1 would not change this option from its openssl default. |
| 1000 |
Use 0 or 1 for enable/disable. |
| 1001 |
|
| 1002 |
By default the value is 1 (enabled). |
| 1003 |
|
| 1004 |
Note |
| 1005 |
|
| 1006 |
This option is supported only for OpenSSL versions >= 1.0.0. On all the |
| 1007 |
other versions attempting to change the default will trigger an error. |
| 1008 |
|
| 1009 |
Example 1.19. Set ssl_release_buffers parameter |
| 1010 |
modparam("tls", "ssl_release_buffers", 1) |
| 1011 |
|
| 1012 |
10.17. ssl_freelist_max_len (integer) |
| 1013 |
|
| 1014 |
Sets the maximum number of free memory chunks, that OpenSSL will keep |
| 1015 |
per connection. Setting it to 0 would cause any unused memory chunk to |
| 1016 |
be immediately freed, reducing the memory footprint. A too large value |
| 1017 |
would result in extra memory consumption. |
| 1018 |
|
| 1019 |
Should be combined with ssl_release_buffers. |
| 1020 |
|
| 1021 |
A value of -1 has a special meaning: the OpenSSL default will be used |
| 1022 |
(no attempt on changing the value will be made). For OpenSSL 1.0 the |
| 1023 |
internal default is 32. |
| 1024 |
|
| 1025 |
By default the value is 0 (no freelist). |
| 1026 |
|
| 1027 |
Note |
| 1028 |
|
| 1029 |
This option is supported only for OpenSSL versions >= 1.0.0. On all the |
| 1030 |
other versions attempting to change the default will trigger an error. |
| 1031 |
|
| 1032 |
Example 1.20. Set ssl_freelist_max_len parameter |
| 1033 |
modparam("tls", "ssl_freelist_max_len", 0) |
| 1034 |
|
| 1035 |
10.18. ssl_max_send_fragment (integer) |
| 1036 |
|
| 1037 |
Sets the maximum number of bytes (from the clear text) sent into one |
| 1038 |
TLS record. Valid values are between 512 and 16384. Note however that |
| 1039 |
even valid low values might not be big enough to allow a successful |
| 1040 |
handshake (try minimum 1024). |
| 1041 |
|
| 1042 |
Lower values would lead to less memory usage, but values lower than the |
| 1043 |
typical Kamailio write size would incur a slight performance penalty. |
| 1044 |
Good values are bigger than the size of the biggest SIP packet one |
| 1045 |
normally expects to forward. For example in most setups 2048 would be a |
| 1046 |
good value. |
| 1047 |
|
| 1048 |
Note |
| 1049 |
|
| 1050 |
Values on the lower side, even if valid (> 512), might not allow for a |
| 1051 |
successful initial handshake. This happens if the certificate does not |
| 1052 |
fit inside one send fragment. Values lower than 1024 should not be |
| 1053 |
used. Even with higher values, if the handshake fails, try increasing |
| 1054 |
the value. |
| 1055 |
|
| 1056 |
A value of -1 has a special meaning: the OpenSSL default will be used |
| 1057 |
(no attempt on changing the value will be made). |
| 1058 |
|
| 1059 |
By default the value is -1 (the OpenSSL default, which at least in |
| 1060 |
OpenSSL 1.0.0 is ~ 16k). |
| 1061 |
|
| 1062 |
Note |
| 1063 |
|
| 1064 |
This option is supported only for OpenSSL versions >= 0.9.9. On all the |
| 1065 |
other versions attempting to change the default will trigger an error. |
| 1066 |
|
| 1067 |
Example 1.21. Set ssl_max_send_fragment parameter |
| 1068 |
modparam("tls", "ssl_max_send_fragment", 4096) |
| 1069 |
|
| 1070 |
10.19. ssl_read_ahead (boolean) |
| 1071 |
|
| 1072 |
Enables read ahead, reducing the number of internal OpenSSL BIO read() |
| 1073 |
calls. This option has only debugging value, in normal circumstances it |
| 1074 |
should not be changed from the default. |
| 1075 |
|
| 1076 |
When disabled OpenSSL will make at least 2 BIO read() calls per |
| 1077 |
received record: one to get the record header and one to get the rest |
| 1078 |
of the record. |
| 1079 |
|
| 1080 |
The TLS module buffers internally all read()s and defines its own fast |
| 1081 |
BIO so enabling this option would only cause more memory consumption |
| 1082 |
and a minor slow-down (extra memcpy). |
| 1083 |
|
| 1084 |
A value of -1 has a special meaning: the OpenSSL default will be used |
| 1085 |
(no attempt on changing the value will be made). |
| 1086 |
|
| 1087 |
By default the value is 0 (disabled). |
| 1088 |
|
| 1089 |
Example 1.22. Set ssl_read_ahead parameter |
| 1090 |
modparam("tls", "ssl_read_ahead", 1) |
| 1091 |
|
| 1092 |
10.20. send_close_notify (boolean) |
| 1093 |
|
| 1094 |
Enables/disables sending close notify alerts prior to closing the |
| 1095 |
corresponding TCP connection. Sending the close notify prior to TCP |
| 1096 |
shutdown is "nicer" from a TLS point of view, but it has a measurable |
| 1097 |
performance impact. Default: off. Can be set at runtime |
| 1098 |
(tls.send_close_notify). |
| 1099 |
|
| 1100 |
The default value is 0 (off). |
| 1101 |
|
| 1102 |
It can be changed also at runtime, via the RPC interface and config |
| 1103 |
framework. The config variable name is tls.send_close_notify. |
| 1104 |
|
| 1105 |
Example 1.23. Set send_close_notify parameter |
| 1106 |
... |
| 1107 |
modparam("tls", "send_close_notify", 1) |
| 1108 |
... |
| 1109 |
|
| 1110 |
Example 1.24. Set tls.send_close_notify at runtime |
| 1111 |
$ kamcmd cfg.set_now_int tls send_close_notify 1 |
| 1112 |
|
| 1113 |
10.21. con_ct_wq_max (integer) |
| 1114 |
|
| 1115 |
Sets the maximum allowed per connection clear-text send queue size in |
| 1116 |
bytes. This queue is used when data cannot be encrypted and sent |
| 1117 |
immediately because of an ongoing TLS level renegotiation. |
| 1118 |
|
| 1119 |
The default value is 65536 (64 Kb). |
| 1120 |
|
| 1121 |
It can be changed also at runtime, via the RPC interface and config |
| 1122 |
framework. The config variable name is tls.con_ct_wq_max. |
| 1123 |
|
| 1124 |
Example 1.25. Set con_ct_wq_max parameter |
| 1125 |
... |
| 1126 |
modparam("tls", "con_ct_wq_max", 1048576) |
| 1127 |
... |
| 1128 |
|
| 1129 |
Example 1.26. Set tls.con_ct_wq_max at runtime |
| 1130 |
$ kamcmd cfg.set_now_int tls con_ct_wq_max 1048576 |
| 1131 |
|
| 1132 |
10.22. ct_wq_max (integer) |
| 1133 |
|
| 1134 |
Sets the maximum total number of bytes queued in all the clear-text |
| 1135 |
send queues. These queues are used when data cannot be encrypted and |
| 1136 |
sent immediately because of an ongoing TLS level renegotiation. |
| 1137 |
|
| 1138 |
The default value is 10485760 (10 Mb). |
| 1139 |
|
| 1140 |
It can be changed also at runtime, via the RPC interface and config |
| 1141 |
framework. The config variable name is tls.ct_wq_max. |
| 1142 |
|
| 1143 |
Example 1.27. Set ct_wq_max parameter |
| 1144 |
... |
| 1145 |
modparam("tls", "ct_wq_max", 4194304) |
| 1146 |
... |
| 1147 |
|
| 1148 |
Example 1.28. Set tls.ct_wq_max at runtime |
| 1149 |
$ kamcmd cfg.set_now_int tls ct_wq_max 4194304 |
| 1150 |
|
| 1151 |
10.23. ct_wq_blk_size (integer) |
| 1152 |
|
| 1153 |
Minimum block size for the internal clear-text send queues (debugging / |
| 1154 |
advanced tuning). Good values are multiple of typical datagram sizes. |
| 1155 |
|
| 1156 |
The default value is 4096. |
| 1157 |
|
| 1158 |
It can be changed also at runtime, via the RPC interface and config |
| 1159 |
framework. The config variable name is tls.ct_wq_blk_size. |
| 1160 |
|
| 1161 |
Example 1.29. Set ct_wq_blk_size parameter |
| 1162 |
... |
| 1163 |
modparam("tls", "ct_wq_blk_size", 2048) |
| 1164 |
... |
| 1165 |
|
| 1166 |
Example 1.30. Set tls.ct_wq_max at runtime |
| 1167 |
$ kamcmd cfg.set_now_int tls ct_wq_blk_size 2048 |
| 1168 |
|
| 1169 |
10.24. tls_log (int) |
| 1170 |
|
| 1171 |
Sets the log level at which TLS related messages will be logged. |
| 1172 |
|
| 1173 |
The default value is 3 (L_DBG). |
| 1174 |
|
| 1175 |
It can be changed also at runtime, via the RPC interface and config |
| 1176 |
framework. The config variable name is tls.log. |
| 1177 |
|
| 1178 |
Example 1.31. Set tls_log parameter |
| 1179 |
... |
| 1180 |
# ignore TLS messages if Kamailio is started with debug less than 10 |
| 1181 |
modparam("tls", "tls_log", 10) |
| 1182 |
... |
| 1183 |
|
| 1184 |
Example 1.32. Set tls.log at runtime |
| 1185 |
$ kamcmd cfg.set_now_int tls log 10 |
| 1186 |
|
| 1187 |
10.25. tls_debug (int) |
| 1188 |
|
| 1189 |
Sets the log level at which TLS debug messages will be logged. Note |
| 1190 |
that TLS debug messages are enabled only if the TLS module is compiled |
| 1191 |
with debugging enabled (e.g. -DTLS_WR_DEBUG, -DTLS_RD_DEBUG or |
| 1192 |
-DTLS_BIO_DEBUG). |
| 1193 |
|
| 1194 |
The default value is 3 (L_DBG). |
| 1195 |
|
| 1196 |
It can be changed also at runtime, via the RPC interface and config |
| 1197 |
framework. The config variable name is tls.debug. |
| 1198 |
|
| 1199 |
Example 1.33. Set tls_debug parameter |
| 1200 |
... |
| 1201 |
# ignore TLS debug messages if Kamailio is started with debug less than 10 |
| 1202 |
modparam("tls", "tls_debug", 10) |
| 1203 |
... |
| 1204 |
|
| 1205 |
Example 1.34. Set tls.debug at runtime |
| 1206 |
$ kamcmd cfg.set_now_int tls debug 10 |
| 1207 |
|
| 1208 |
10.26. low_mem_threshold1 (integer) |
| 1209 |
|
| 1210 |
Sets the minimal free memory from which attempts to open or accept new |
| 1211 |
TLS connections will start to fail. The value is expressed in KB. |
| 1212 |
|
| 1213 |
The default value depends on whether the OpenSSL library used handles |
| 1214 |
low memory situations in a good way (openssl bug #1491). As of this |
| 1215 |
writing this is not true for any OpenSSL version (including 0.9.8e). |
| 1216 |
|
| 1217 |
If an ill-behaved OpenSSL version is detected, a very conservative |
| 1218 |
value is chosen, which depends on the maximum possible number of |
| 1219 |
simultaneously created TLS connections (and hence on the process |
| 1220 |
number). |
| 1221 |
|
| 1222 |
The following values have a special meaning: |
| 1223 |
* -1 - use the default value |
| 1224 |
* 0 - disable (TLS connections will not fail preemptively) |
| 1225 |
|
| 1226 |
It can be changed also at runtime, via the RPC interface and config |
| 1227 |
framework. The config variable name is tls.low_mem_threshold1. |
| 1228 |
|
| 1229 |
See also tls.low_mem_threshold2. |
| 1230 |
|
| 1231 |
Example 1.35. Set low_mem_threshold1 parameter |
| 1232 |
... |
| 1233 |
modparam("tls", "low_mem_threshold1", -1) |
| 1234 |
... |
| 1235 |
|
| 1236 |
Example 1.36. Set tls.low_mem_threshold1 at runtime |
| 1237 |
$ kamcmd cfg.set_now_int tls low_mem_threshold1 2048 |
| 1238 |
|
| 1239 |
10.27. low_mem_threshold2 (integer) |
| 1240 |
|
| 1241 |
Sets the minimal free memory from which TLS operations on already |
| 1242 |
established TLS connections will start to fail preemptively. The value |
| 1243 |
is expressed in KB. |
| 1244 |
|
| 1245 |
The default value depends on whether the OpenSSL library used handles |
| 1246 |
low memory situations (openssl bug #1491). As of this writing this is |
| 1247 |
not true for any OpenSSL version (including 0.9.8e). |
| 1248 |
|
| 1249 |
If an ill-behaved OpenSSL version is detected, a very conservative |
| 1250 |
value is chosen, which depends on the maximum possible number of |
| 1251 |
simultaneously created TLS connections (and hence on the process |
| 1252 |
number). |
| 1253 |
|
| 1254 |
The following values have a special meaning: |
| 1255 |
* -1 - use the default value |
| 1256 |
* 0 - disable (TLS operations will not fail preemptively) |
| 1257 |
|
| 1258 |
It can be changed also at runtime, via the RPC interface and config |
| 1259 |
framework. The config variable name is tls.low_mem_threshold2. |
| 1260 |
|
| 1261 |
See also tls.low_mem_threshold1. |
| 1262 |
|
| 1263 |
Example 1.37. Set tls.low_mem_threshold2 parameter |
| 1264 |
... |
| 1265 |
modparam("tls", "low_mem_threshold2", -1) |
| 1266 |
... |
| 1267 |
|
| 1268 |
Example 1.38. Set tls.low_mem_threshold2 at runtime |
| 1269 |
$ kamcmd cfg.set_now_int tls low_mem_threshold2 1024 |
| 1270 |
|
| 1271 |
10.28. tls_force_run (boolean) |
| 1272 |
|
| 1273 |
If enabled Kamailio will start even if some of the OpenSSL sanity |
| 1274 |
checks fail (turn it on at your own risk). |
| 1275 |
|
| 1276 |
If any of the following sanity checks fail, Kamailio will not start: |
| 1277 |
* the version of the library the TLS module was compiled with is "too |
| 1278 |
different" from the library used at runtime. The versions should |
| 1279 |
have the same major, minor and fix level (e.g.: 0.9.8a and 0.9.8c |
| 1280 |
are ok, but 0.9.8 and 0.9.9 are not) |
| 1281 |
* the OpenSSL library used at compile time and the one used at |
| 1282 |
runtime have different Kerberos options |
| 1283 |
|
| 1284 |
By default tls_force_run is disabled. |
| 1285 |
|
| 1286 |
Example 1.39. Set tls_force_run parameter |
| 1287 |
... |
| 1288 |
modparam("tls", "tls_force_run", 11) |
| 1289 |
... |
| 1290 |
|
| 1291 |
10.29. session_cache (boolean) |
| 1292 |
|
| 1293 |
If enabled Kamailio will do caching of the TLS sessions data, |
| 1294 |
generation a session_id and sending it back to client. |
| 1295 |
|
| 1296 |
By default TLS session caching is disabled (0). |
| 1297 |
|
| 1298 |
Example 1.40. Set session_cache parameter |
| 1299 |
... |
| 1300 |
modparam("tls", "session_cache", 1) |
| 1301 |
... |
| 1302 |
|
| 1303 |
10.30. session_id (str) |
| 1304 |
|
| 1305 |
The value for session ID context, making sense when session caching is |
| 1306 |
enabled. |
| 1307 |
|
| 1308 |
By default TLS session_id is "kamailio-tls-5.x.y". |
| 1309 |
|
| 1310 |
Example 1.41. Set session_id parameter |
| 1311 |
... |
| 1312 |
modparam("tls", "session_id", "my-session-id-context") |
| 1313 |
... |
| 1314 |
|
| 1315 |
10.31. renegotiation (boolean) |
| 1316 |
|
| 1317 |
If enabled Kamailio will allow renegotiations of TLS connection |
| 1318 |
initiated by the client. This may expose to a security risk if the |
| 1319 |
client is not a trusted peer and keeps renegotiating, consuming CPU and |
| 1320 |
bandwidth resources. |
| 1321 |
|
| 1322 |
By default TLS renegotiation is disabled (0). |
| 1323 |
|
| 1324 |
Example 1.42. Set renegotiation parameter |
| 1325 |
... |
| 1326 |
modparam("tls", "renegotiation", 1) |
| 1327 |
... |
| 1328 |
|
| 1329 |
10.32. init_mode (int) |
| 1330 |
|
| 1331 |
Allow setting flags that control how the module is initialized and |
| 1332 |
works at runtime. Many flags (bits) can be set at the same time (set |
| 1333 |
the parameter to the sum of corresponding values). The flags are |
| 1334 |
refered with 0-indexing. |
| 1335 |
|
| 1336 |
If flag (bit) at index 0 is set (value 1), the memory management |
| 1337 |
operations registered for TLS are wrapped within a pthread mutex lock. |
| 1338 |
It can be useful with newer versions of libssl and libcrypto, which |
| 1339 |
have a more pthread multi-threading oriented design. |
| 1340 |
|
| 1341 |
If flag (bit) at index 1 is set (value 2), the module executes openssl |
| 1342 |
fork prepare API functions (see |
| 1343 |
https://www.openssl.org/docs/man1.1.1/man3/OPENSSL_fork_prepare.html). |
| 1344 |
It is done only for openssl version greater or equal with 1.1.1. |
| 1345 |
|
| 1346 |
Default value is 0. |
| 1347 |
|
| 1348 |
Example 1.43. Set init_mode parameter |
| 1349 |
... |
| 1350 |
modparam("tls", "init_mode", 1) |
| 1351 |
... |
| 1352 |
|
| 1353 |
10.33. config (string) |
| 1354 |
|
| 1355 |
Sets the name of the TLS specific configuration file or configuration |
| 1356 |
directory. |
| 1357 |
|
| 1358 |
If set the TLS module will load a special configuration file or |
| 1359 |
configuration files from configuration directory, in which different |
| 1360 |
TLS parameters can be specified on a per role (server or client) and |
| 1361 |
domain basis (for now only IPs). The corresponding module parameters |
| 1362 |
will be ignored if a separate configuration file is used. |
| 1363 |
|
| 1364 |
If the file or directory name starts with a '.' the path will be |
| 1365 |
relative to the working directory (at runtime). If it starts with a '/' |
| 1366 |
it will be an absolute path and if it starts with anything else the |
| 1367 |
path will be relative to the main config file directory (e.g.: for |
| 1368 |
kamailio -f /etc/kamailio/kamailio.cfg it will be relative to |
| 1369 |
/etc/kamailio/). |
| 1370 |
|
| 1371 |
By default no TLS configuration file is specified. |
| 1372 |
|
| 1373 |
The following parameters can be set in the config file, for each |
| 1374 |
domain: |
| 1375 |
* tls_method - (str) - TLS methods |
| 1376 |
* verify_certificate - (bool) - see modparam |
| 1377 |
* require_certificate - (bool) - see modparam |
| 1378 |
* verify_client - (str) - see modparam |
| 1379 |
* private_key - (str) - see modparam |
| 1380 |
* certificate - (str) - see modparam |
| 1381 |
* verify_depth - (int) - see modparam |
| 1382 |
* ca_list - (str) - see modparam |
| 1383 |
* crl - (str) - see modparam |
| 1384 |
* cipher_list - (str) - see modparam |
| 1385 |
* server_name - (str) - SNI (server name identification) |
| 1386 |
* server_name_mode - (int) - how to match server_name |
| 1387 |
* server_id - (str) - server id |
| 1388 |
|
| 1389 |
The value for server_name_mode specifies how to match the server_name |
| 1390 |
(SNI). If set to 1, match the domain and all its subdomains. If set to |
| 1391 |
2, match only the subdomains. If set to 0 (or anything else), match |
| 1392 |
only the domain given in server_name. |
| 1393 |
|
| 1394 |
The value for server_id can be any string, being used to match TLS |
| 1395 |
client config profile, overriding the match on ip:port and server_name. |
| 1396 |
This is the recommended way for selecting a specific TLS client config |
| 1397 |
profile, because the local or remote port is hard to predict for a |
| 1398 |
stream connection - see parameter xavp_cfg to learn how to enable it. |
| 1399 |
|
| 1400 |
All the parameters that take filenames as values will be resolved using |
| 1401 |
the same rules as for the tls config filename itself: starting with a |
| 1402 |
'.' means relative to the working directory, a '/' means an absolute |
| 1403 |
path and anything else a path relative to the directory of the current |
| 1404 |
Kamailio main config file. |
| 1405 |
|
| 1406 |
Kamailio acts as a server when it accepts a connection and as a client |
| 1407 |
when it initiates a new connection by itself (it connects to |
| 1408 |
something). |
| 1409 |
|
| 1410 |
The tls.cfg consists on a set of server and client TLS domain profiles. |
| 1411 |
A server TLS domain profile starts with [server:domain]. A client TLS |
| 1412 |
domain profile starts with [client:domain]. The tokens 'server' and |
| 1413 |
'client' are static values. The 'domain' part can be: 'ip:port' - the |
| 1414 |
IP address and port to match with the TLS connection; 'default' - |
| 1415 |
(static string) for client and server profiles to be used when no other |
| 1416 |
profile is matched; 'any' - (static string) for client and server |
| 1417 |
profiles to be matched based on 'server_name', no matter of IP and port |
| 1418 |
of the TLS connection. |
| 1419 |
|
| 1420 |
There can be only one of each [server:default] and [client:default] |
| 1421 |
profile definitions. Other profiles can be defined many times with the |
| 1422 |
same domain ('ip:port' or 'any'), but in that case they must have |
| 1423 |
'server_name' set for matching SNI. |
| 1424 |
|
| 1425 |
It is highly recommended to have [server:default] and [client:default] |
| 1426 |
profile definitions. They are needed when SNI is not yet available. If |
| 1427 |
SNI is provided, then the profile definition is searched again to match |
| 1428 |
on 'server_name'. |
| 1429 |
|
| 1430 |
Example 1.44. Sample TLS Config File |
| 1431 |
... |
| 1432 |
[server:default] |
| 1433 |
method = TLSv1 |
| 1434 |
verify_certificate = yes |
| 1435 |
require_certificate = yes |
| 1436 |
private_key = default_key.pem |
| 1437 |
certificate = default_cert.pem |
| 1438 |
ca_list = default_ca.pem |
| 1439 |
crl = default_crl.pem |
| 1440 |
|
| 1441 |
[client:default] |
| 1442 |
verify_certificate = yes |
| 1443 |
require_certificate = yes |
| 1444 |
|
| 1445 |
# more relaxed for connection on the loopback interface |
| 1446 |
[server:127.0.0.1:5061] |
| 1447 |
method = TLSv1 |
| 1448 |
verify_certificate = yes |
| 1449 |
require_certificate = no |
| 1450 |
private_key = local_kamailio_org_key.pem |
| 1451 |
certificate = local_kamailio_org_cert.pem |
| 1452 |
verify_depth = 3 |
| 1453 |
ca_list = local_ca.pem |
| 1454 |
server_name = kamailio.org |
| 1455 |
|
| 1456 |
[client:127.0.0.1:5061] |
| 1457 |
method = TLSv1 |
| 1458 |
verify_certificate = yes |
| 1459 |
require_certificate = yes |
| 1460 |
private_key = default_key.pem |
| 1461 |
certificate = default_cert.pem |
| 1462 |
ca_list = default_ca.pem |
| 1463 |
crl = default_crl.pem |
| 1464 |
server_name = kamailio.org |
| 1465 |
server_id = kamailio.org |
| 1466 |
|
| 1467 |
# server profile on any address |
| 1468 |
[server:any] |
| 1469 |
method = TLSv1 |
| 1470 |
verify_certificate = yes |
| 1471 |
require_certificate = no |
| 1472 |
private_key = kamailio_net_key.pem |
| 1473 |
certificate = kamailio_net_cert.pem |
| 1474 |
verify_depth = 3 |
| 1475 |
ca_list = local_ca.pem |
| 1476 |
server_name = kamailio.net |
| 1477 |
server_name_mode = 1 |
| 1478 |
... |
| 1479 |
|
| 1480 |
For a more complete example check the tls.cfg distributed with the |
| 1481 |
Kamailio source (kamailio/modules/tls/tls.cfg). |
| 1482 |
|
| 1483 |
Example 1.45. Set config parameter |
| 1484 |
... |
| 1485 |
modparam("tls", "config", "/usr/local/etc/kamailio/tls.cfg") |
| 1486 |
... |
| 1487 |
|
| 1488 |
The file can be changed at runtime. The new config will not be loaded |
| 1489 |
immediately, but after the first tls.reload RPC call. |
| 1490 |
|
| 1491 |
Example 1.46. Change and reload the TLS configuration at runtime |
| 1492 |
$ kamcmd cfg.set_now_string tls config "/usr/local/etc/kamailio/new_tls.cfg" |
| 1493 |
$ kamcmd tls.reload |
| 1494 |
|
| 1495 |
10.34. xavp_cfg (string) |
| 1496 |
|
| 1497 |
Sets the name of XAVP that stores attributes for TLS connections. |
| 1498 |
|
| 1499 |
The following (inner) attributes can be set: |
| 1500 |
* server_name - SNI to be used for outbound connections |
| 1501 |
* server_id - string value to be used to match TLS config profile for |
| 1502 |
client (outbound) connections. If it is set, matching the TLS |
| 1503 |
config profile is done first on server_id and then on ip:port and |
| 1504 |
server_name. This is the recommended way for selecting a specific |
| 1505 |
TLS client config profile as the local or remote port is hard to |
| 1506 |
predict for a stream connection. |
| 1507 |
|
| 1508 |
The default value is empty (not set). |
| 1509 |
|
| 1510 |
Example 1.47. Set xavp_cfg parameter |
| 1511 |
... |
| 1512 |
modparam("tls", "xavp_cfg", "tls") |
| 1513 |
... |
| 1514 |
$xavp(tls=>server_name) = "kamailio.org"; |
| 1515 |
$xavp(tls[0]=>server_id) = "kamailio.org"; |
| 1516 |
$du = "sip:kamailio.org:5061;transport=tls"; |
| 1517 |
route(RELAY); |
| 1518 |
... |
| 1519 |
|
| 1520 |
10.35. event_callback (str) |
| 1521 |
|
| 1522 |
The name of the function in the kemi configuration file (embedded |
| 1523 |
scripting language such as Lua, Python, ...) to be executed instead of |
| 1524 |
event_route[...] blocks specific for tls module. |
| 1525 |
|
| 1526 |
The function has one string parameter, the value is the name of the |
| 1527 |
event_route block, respectively "tls:connection-out". |
| 1528 |
|
| 1529 |
Default value is 'empty' (no function is executed for events). |
| 1530 |
|
| 1531 |
Example 1.48. Set event_callback parameter |
| 1532 |
... |
| 1533 |
modparam("tls", "event_callback", "ksr_tls_event") |
| 1534 |
... |
| 1535 |
-- event callback function implemented in Lua |
| 1536 |
function ksr_tls_event(evname) |
| 1537 |
KSR.info("===== tls module triggered event: " .. evname .. "\n"); |
| 1538 |
return 1; |
| 1539 |
end |
| 1540 |
... |
| 1541 |
|
| 1542 |
10.36. rand_engine (str) |
| 1543 |
|
| 1544 |
Set the random number generator engine for libssl. |
| 1545 |
|
| 1546 |
Note: the default random number generator (PRNG) engine of libssl |
| 1547 |
v1.1.x is not designed for multi-process applications and can result in |
| 1548 |
a crash. Therefore set the PRNG engine to one of the options listed in |
| 1549 |
this section. If libssl 1.1.x (or newer) is detected at compile time, |
| 1550 |
then the PRNG engine is set to "cryptorand". |
| 1551 |
|
| 1552 |
The following options are available: |
| 1553 |
* krand - use internal kam_rand() function |
| 1554 |
* fastrand - use internal fastrand (ISAAC) function |
| 1555 |
* cryptorand - use internal cryptorand (Fortuna) function |
| 1556 |
* kxlibssl - default libssl rand engine wrapped by a Kamailio mutex |
| 1557 |
|
| 1558 |
Note: the krand and fastrand engines are not recommended for use on |
| 1559 |
systems requiring strong security, as they may not generate numbers |
| 1560 |
with enough randomness and are not cryptographically secure. |
| 1561 |
|
| 1562 |
The default value is empty (not set) for libssl v1.0.x or older, and |
| 1563 |
"cryptorand" for libssl v1.1.x or newer. |
| 1564 |
|
| 1565 |
Example 1.49. Set rand_engine parameter |
| 1566 |
... |
| 1567 |
modparam("tls", "rand_engine", "fastrand") |
| 1568 |
... |
| 1569 |
|
| 1570 |
10.37. engine (string) |
| 1571 |
|
| 1572 |
If OpenSSL is compiled with engine support this will allow algorithms |
| 1573 |
to be offloaded and private keys from HSM to be used. Currently only a |
| 1574 |
single global engine is supported. However, private keys can be |
| 1575 |
specified per_domain. |
| 1576 |
|
| 1577 |
To use private keys from the HSM, the name is the HSM key label |
| 1578 |
prefixed by /engine:. |
| 1579 |
... |
| 1580 |
## example for the Gem engine |
| 1581 |
modparam("tls", "engine", "gem") |
| 1582 |
# can also be set per-domain in tls.cfg |
| 1583 |
modparam("tls", "private_key", "/engine:my_HSM_key_label") |
| 1584 |
|
| 1585 |
## example for engine_pkcs11 |
| 1586 |
modparam("tls", "engine", "pkcs11") |
| 1587 |
modparam("tls", "private_key", "/engine:pkcs11:token=MYTOKEN;object=MYKEYLABEL") |
| 1588 |
|
| 1589 |
modparam("tls", "engine_config", "/usr/local/etc/kamailio/openssl.cnf") |
| 1590 |
modparam("tls", "engine_algorithms", "ALL") |
| 1591 |
... |
| 1592 |
|
| 1593 |
By default OpenSSL engine support is disabled (NONE). This global param |
| 1594 |
is not supported in the tls config file. |
| 1595 |
|
| 1596 |
10.38. engine_config (string) |
| 1597 |
|
| 1598 |
An OpenSSL configuration file to initialize the engine. Typically used |
| 1599 |
to send PIN to HSMs to unlock private keys. See the HSM howto for an |
| 1600 |
example. This global param is not supported in the tls config file. |
| 1601 |
|
| 1602 |
10.39. engine_algorithms (string) |
| 1603 |
|
| 1604 |
A list of cryptographic methods to be set as default in the engine. |
| 1605 |
This is a comma-separated list of values from ALL RSA DSA DH EC RAND |
| 1606 |
CIPHERS DIGESTS PKEY PKEY_CRYPTO PKEY_ASN1. Not all methods are |
| 1607 |
supported by every engine. |
| 1608 |
|
| 1609 |
The default is not to set any methods as default. This global param is |
| 1610 |
not supported in the tls config file. |
| 1611 |
|
| 1612 |
10.40. verify_client (string) |
| 1613 |
|
| 1614 |
Provides an alternative to verify_certificate and require_certificate |
| 1615 |
modparam and tls.cfg parameters, and creates an additional |
| 1616 |
opportunistic connection establishment option for connections with with |
| 1617 |
unverifiable certificates (optional_no_ca). |
| 1618 |
|
| 1619 |
This is useful for allowing connections from SIP phones with |
| 1620 |
self-signed certificates, signed by unrecognized root CAs, expired |
| 1621 |
certificates, etc. |
| 1622 |
|
| 1623 |
The following values have respective behaviors: |
| 1624 |
* off - no client certificate request performed. |
| 1625 |
* on - require a verified certificate from the client. |
| 1626 |
* optional - ask client for certificate. If one is provided, it must |
| 1627 |
be verified. Allowing missing certificate. |
| 1628 |
* optional_no_ca - ask client for certificate. Opportunistically try |
| 1629 |
to verify certificate. Allow connection regardless of whether there |
| 1630 |
is no certificate or whether certificate is present (verified or |
| 1631 |
not). Note that verification status can be retrieved via |
| 1632 |
$tls_peer_verified. |
| 1633 |
|
| 1634 |
Default value is 'off' (no client certificate request performed). |
| 1635 |
|
| 1636 |
Recommendation: when using this parameter, do not use |
| 1637 |
verify_certificate or require_certificate parameters. Conversion table |
| 1638 |
is as follows: |
| 1639 |
* verify_certificate=0, require_certificate=0 => verify_client="off" |
| 1640 |
* verify_certificate=1, require_certificate=0 => |
| 1641 |
verify_client="optional" |
| 1642 |
* verify_certificate=1, require_certificate=1 => verify_client="on" |
| 1643 |
|
| 1644 |
Example 1.50. Set verify_client modparam parameter |
| 1645 |
... |
| 1646 |
modparam("tls", "verify_client", "on") |
| 1647 |
... |
| 1648 |
|
| 1649 |
Example 1.51. Set verify_client tls.cfg parameter |
| 1650 |
... |
| 1651 |
[server:1.2.3.4:5061] |
| 1652 |
method = TLSv1 |
| 1653 |
verify_client = on |
| 1654 |
... |
| 1655 |
|
| 1656 |
[server:5.6.7.8:5061] |
| 1657 |
method = TLSv1.2 |
| 1658 |
verify_client = optional_no_ca |
| 1659 |
... |
| 1660 |
|
| 1661 |
10.41. provider_quirks (integer) |
| 1662 |
|
| 1663 |
Reload a provider in the child - needed in MP-mode only |
| 1664 |
(tcp_main_threads = 0) for some providers. The configuration file for |
| 1665 |
the provider is provided in the provider_quirks_config parameter. |
| 1666 |
Should be 0 in MT-mode. |
| 1667 |
* 0 - no reload (default) |
| 1668 |
* 1 - reloads a provider in a new library context in the child. |
| 1669 |
pkcs11-provider is known to require this. |
| 1670 |
|
| 1671 |
Example 1.52. Set provider_quirks modparam parameter |
| 1672 |
... |
| 1673 |
modparam("tls", "provider_quirks", 1) |
| 1674 |
# 1: provider_quirks_config parameter must be set |
| 1675 |
... |
| 1676 |
|
| 1677 |
10.42. provider_quirks_config (string) |
| 1678 |
|
| 1679 |
A file name of a OpenSSL configuration snippet that contains the |
| 1680 |
provider configuration. The file must contain two mandatory keys: |
| 1681 |
quirks_sect - section to load, quirks_provider - the provider to load. |
| 1682 |
|
| 1683 |
Example 1.53. Set provider_quirks_config modparam parameter |
| 1684 |
... |
| 1685 |
modparam("tls", "provider_quirks_config", "/etc/kamailio/tls/pkcs11-provider.cnf |
| 1686 |
") |
| 1687 |
... |
| 1688 |
|
| 1689 |
A provider example: |
| 1690 |
# /etc/kamailio/tls/pkcs11-provider.cnf |
| 1691 |
quirks_sect = pkcs11_sect |
| 1692 |
quirks_provider = pkcs11 |
| 1693 |
|
| 1694 |
[pkcs11_sect] |
| 1695 |
module = pkcs11.so |
| 1696 |
pkcs11-module-path = /usr/lib64/libsoftokn3.so |
| 1697 |
pkcs11-module-init-args = configDir=/etc/kamailio/certs/tokens |
| 1698 |
pkcs11-module-token-pin = file:/etc/kamailio/certs/pinfile-softoken.txt |
| 1699 |
pkcs11-module-quirks = no-deinit no-operation-state |
| 1700 |
activate = 1 |
| 1701 |
|
| 1702 |
10.43. keylog_mode (int) |
| 1703 |
|
| 1704 |
Control the TLS key logging functionality, available for libssl version |
| 1705 |
greater than 1.1.0. Its value is composed from bitwise values (can be |
| 1706 |
made as sum of them): |
| 1707 |
* 0 - keys logging not enabled |
| 1708 |
* 1 (bit 1) - initialise keys logging |
| 1709 |
* 2 (bit 2) - keys logging active |
| 1710 |
* 4 (bit 3) - write keys to NOTICE log |
| 1711 |
* 8 (bit 4) - write keys to file |
| 1712 |
* 16 (bit 5) - send keys to udp peer |
| 1713 |
* 1024 (bit 11) - enable filtering of keys logging. When set, |
| 1714 |
filtering is done on: "CLIENT_RANDOM", |
| 1715 |
"CLIENT_HANDSHAKE_TRAFFIC_SECRET", |
| 1716 |
"SERVER_HANDSHAKE_TRAFFIC_SECRET", "EXPORTER_SECRET", |
| 1717 |
"CLIENT_TRAFFIC_SECRET_0", "SERVER_TRAFFIC_SECRET_0" |
| 1718 |
|
| 1719 |
Bit position is the index starting from 1 (practically a non-zero value |
| 1720 |
is (2 power (bitpos - 1)) ). |
| 1721 |
|
| 1722 |
The default value: 0. |
| 1723 |
|
| 1724 |
Example 1.54. Set keylog_mode parameter |
| 1725 |
... |
| 1726 |
modparam("tls", "keylog_mode", 15) |
| 1727 |
... |
| 1728 |
|
| 1729 |
10.44. keylog_file (str) |
| 1730 |
|
| 1731 |
Path to the file where to write the TLS keys. The values are appended |
| 1732 |
to the content of the file. The value 8 (bit 4) has to be set to |
| 1733 |
keylog_mode parameter. |
| 1734 |
|
| 1735 |
The default value: NULL. |
| 1736 |
|
| 1737 |
Example 1.55. Set keylog_file parameter |
| 1738 |
... |
| 1739 |
modparam("tls", "keylog_file", "/tmp/kamailio-tls-keylog.txt") |
| 1740 |
... |
| 1741 |
|
| 1742 |
10.45. keylog_peer (str) |
| 1743 |
|
| 1744 |
Address of the peer where to send the keys log. It has to be in the |
| 1745 |
format "proto:ip:port". Only "udp" protocol (proto) is supported. The |
| 1746 |
value 16 (bit 5) has to be set to keylog_mode parameter. |
| 1747 |
|
| 1748 |
The default value: NULL. |
| 1749 |
|
| 1750 |
Example 1.56. Set keylog_peer parameter |
| 1751 |
... |
| 1752 |
modparam("tls", "keylog_peer", "udp:127.0.0.1:8020") |
| 1753 |
... |
| 1754 |
|
| 1755 |
11. Functions |
| 1756 |
|
| 1757 |
11.1. is_peer_verified() |
| 1758 |
11.2. tls_set_connect_server_id(srvid) |
| 1759 |
|
| 1760 |
11.1. is_peer_verified() |
| 1761 |
|
| 1762 |
Returns true if the connection on which the message was received is |
| 1763 |
TLS, the peer presented an X509 certificate and the certificate chain |
| 1764 |
verified ok. |
| 1765 |
|
| 1766 |
It can be used only in a request route. |
| 1767 |
|
| 1768 |
Example 1.57. is_peer_verified usage |
| 1769 |
... |
| 1770 |
if (proto==TLS && !is_peer_verified()) { |
| 1771 |
sl_send_reply("400", "No certificate or verification failed"); |
| 1772 |
exit; |
| 1773 |
} |
| 1774 |
... |
| 1775 |
|
| 1776 |
11.2. tls_set_connect_server_id(srvid) |
| 1777 |
|
| 1778 |
Set the server id of the tls profile to be used by next client connect, |
| 1779 |
being reset after use. It is an alternative to the use of xavp to |
| 1780 |
specify server id of a client profile for the cases when xavps are no |
| 1781 |
longer available (e.g., after event_route[tm:local-request]). |
| 1782 |
|
| 1783 |
If the parameter is an empty string, then the value is reset. |
| 1784 |
|
| 1785 |
It can be used only in ANY_ROUTE. |
| 1786 |
|
| 1787 |
Example 1.58. tls_set_connect_server_id usage |
| 1788 |
... |
| 1789 |
tls_set_connect_server_id("clientone"); |
| 1790 |
... |
| 1791 |
|
| 1792 |
12. RPC Commands |
| 1793 |
|
| 1794 |
12.1. tls.info |
| 1795 |
12.2. tls.list |
| 1796 |
12.3. tls.options |
| 1797 |
12.4. tls.kill |
| 1798 |
12.5. tls.reload |
| 1799 |
|
| 1800 |
12.1. tls.info |
| 1801 |
|
| 1802 |
List internal information related to the TLS module in a short list - |
| 1803 |
max connections, open connections and the write queue size. |
| 1804 |
|
| 1805 |
Parameters: |
| 1806 |
* None. |
| 1807 |
|
| 1808 |
12.2. tls.list |
| 1809 |
|
| 1810 |
List details about all active TLS connections. |
| 1811 |
|
| 1812 |
Parameters: |
| 1813 |
* None. |
| 1814 |
|
| 1815 |
12.3. tls.options |
| 1816 |
|
| 1817 |
List the current TLS configuration. |
| 1818 |
|
| 1819 |
Parameters: |
| 1820 |
* None. |
| 1821 |
|
| 1822 |
12.4. tls.kill |
| 1823 |
|
| 1824 |
Kill a TLS session by id. |
| 1825 |
|
| 1826 |
Parameters: |
| 1827 |
* None. |
| 1828 |
|
| 1829 |
12.5. tls.reload |
| 1830 |
|
| 1831 |
Reload the external TLS configuration file (aka tls.cfg). It does not |
| 1832 |
reload modparam() parameters. Note that existing active TLS connections |
| 1833 |
are not terminated and they continue to use the old certificates. The |
| 1834 |
new configuration will be used for new connections. |
| 1835 |
|
| 1836 |
Reload is generally safe and usable in production environments. If |
| 1837 |
possible should be done in a time where the service has lower |
| 1838 |
usage/connections. |
| 1839 |
|
| 1840 |
This RPC command is exported with "RPC_EXEC_DELTA" flag, therefore its |
| 1841 |
execution rate can be restricted to specific time intervals by setting |
| 1842 |
the "rpc_exec_delta" core parameter. |
| 1843 |
|
| 1844 |
Parameters: |
| 1845 |
* None. |
| 1846 |
|
| 1847 |
13. Status |
| 1848 |
|
| 1849 |
13.1. License |
| 1850 |
13.2. History |
| 1851 |
|
| 1852 |
13.1. License |
| 1853 |
|
| 1854 |
Most of the code for this module has been released under BSD by |
| 1855 |
iptelorg. The GPL parts are released with an exception to link with |
| 1856 |
OpenSSL toolkit software components. |
| 1857 |
|
| 1858 |
13.2. History |
| 1859 |
|
| 1860 |
For version 3.1 most of the TLS specific code was completely re-written |
| 1861 |
to add support for asynchronous TLS and fix several long standing bugs. |
| 1862 |
|
| 1863 |
The code is currently maintained by Andrei Pelinescu-Onciul |
| 1864 |
<[email protected]>. |
| 1865 |
|
| 1866 |
Install does not generate self-signed certificates by default anymore. |
| 1867 |
In order to generate them now you should do "make install-tls-cert" |
| 1868 |
|
| 1869 |
14. Event Routes |
| 1870 |
|
| 1871 |
14.1. event_route[tls:connection-out] |
| 1872 |
|
| 1873 |
14.1. event_route[tls:connection-out] |
| 1874 |
|
| 1875 |
Event route to be executed when a TLS connection is opened by Kamailio. |
| 1876 |
If drop() is executed in the event route, then the data is no longer |
| 1877 |
sent over the connection. |
| 1878 |
|
| 1879 |
Example 1.59. Use of event_route[tls:connection-out] |
| 1880 |
... |
| 1881 |
event_route[tls:connection-out] { |
| 1882 |
if($sndto(ip)=="1.2.3.4") { |
| 1883 |
drop; |
| 1884 |
} |
| 1885 |
} |
| 1886 |
... |
| 1887 |
|
| 1888 |
15. TLS With Database Backend |
| 1889 |
|
| 1890 |
The module does not connect to database to fetch the values for the TLS |
| 1891 |
profile attributes. However the 'kamcli' tool can generate the tls.cfg |
| 1892 |
from a database table. Once generated, the 'tls.cfg' can be reloaded |
| 1893 |
with an RPC command. |
| 1894 |
|
| 1895 |
The kamcli tool can be found at https://github.com/kamailio/kamcli. |
| 1896 |
|
| 1897 |
The schema to create the database table can be seen with the command: |
| 1898 |
"kamcli tls sqlprint". The default name for database table is 'tlscfg'. |
| 1899 |
|
| 1900 |
The most of the column names matches the corresponding attribute names |
| 1901 |
from a TLS profile. |
| 1902 |
|
| 1903 |
The profile id in 'tls.cfg' is generated from |
| 1904 |
'[profile_type:profile_name]'. The 'profile_type' has to be 'server' or |
| 1905 |
'client'. The 'profile_name' can be 'default', 'any' or the pair of IP |
| 1906 |
address and port like 'ipaddr:port'. |
| 1907 |
|
| 1908 |
The 'file_type' is specifying if the values for 'certificate', |
| 1909 |
'private_key', 'ca_list' and 'crl' are path to files on disc (when is |
| 1910 |
set to 0) or the content of the files (when set to 1). If 'file_type' |
| 1911 |
is 1, then 'kamcli' will create new files on disc and store the values |
| 1912 |
from the database in them. The target folder for 'tls.cfg' and the |
| 1913 |
certificates related files can be set via command options for 'kamcli |
| 1914 |
tls', for more details see the output of 'kamcli tls --help' and |
| 1915 |
'kamcli tls cfgprint --help'. |