- document send_close_notify con_ct_wq_max, ct_wq_max and
ct_wq_blk_size.
- document runtime support for tls_log, low_mem_threshold1,
low_mem_threshold2, connection_timeout and config
- note about compression being now disabled by default
- changed defaults for ssl_release_buffers, ssl_freelist_max_len
and ssl_read_ahead.
... | ... |
@@ -6,6 +6,7 @@ $Id$ |
6 | 6 |
sip-router 3.1 chages |
7 | 7 |
|
8 | 8 |
core: |
9 |
+ - asynchronous TLS support |
|
9 | 10 |
- onreply_route {...} is now equivalent with onreply_route[0] {...} |
10 | 11 |
- global, per protocol blacklist ignore masks (via extended send_flags). |
11 | 12 |
See dst_blacklist_udp_imask a.s.o (dst_blacklist_*_imask). |
... | ... |
@@ -38,11 +39,39 @@ modules: |
38 | 38 |
blst_rpl_clear_ignore(mask): like blst_rpl_ignore(mask), but |
39 | 39 |
clears instead of setting. |
40 | 40 |
- tls: |
41 |
- new options for better tuning memory usage for modern openssl |
|
42 |
- versions: ssl_release_buffers, ssl_freelist_max_len, |
|
43 |
- ssl_max_send_fragment, ssl_read_ahead. For more info see |
|
44 |
- modules/doc/tls/README. |
|
45 |
- compression is now disabled by default. To enable it set |
|
41 |
+ asynchronous TLS support |
|
42 |
+ new TLS RPCs (tls.info, tls.options), tls.list more detailed. |
|
43 |
+ removed handshake_timeout and send_timeout module parameters / |
|
44 |
+ config variables. The values from tcp are used instead |
|
45 |
+ (tcp_connect_timeout and tcp_send_timeout). |
|
46 |
+ runtime config support |
|
47 |
+ more config options: |
|
48 |
+ send_close_notify - enables/disables sending close notify |
|
49 |
+ alerts prior to closing the corresponding TCP connection. |
|
50 |
+ Sending the close notify prior to tcp shutdown is "nicer" |
|
51 |
+ from a TLS point of view, but it has a measurable |
|
52 |
+ performance impact. Default: off. Can be set at runtime |
|
53 |
+ (tls.send_close_notify). |
|
54 |
+ con_ct_wq_max - per connection tls maximum clear text write |
|
55 |
+ queue size. The TLS clear-text write queues are used when a |
|
56 |
+ send attempt has to be delayed due to an on-going TLS level |
|
57 |
+ renegotiation. Can be set at runtime (tls.con_ct_wq_max). |
|
58 |
+ Default: 65536 (64 Kb). |
|
59 |
+ ct_wq_max - maximum total for all the tls clear text write |
|
60 |
+ queues (summed). Can be set at runtime (tls.ct_wq_max). |
|
61 |
+ Default: 10485760 (10 Mb). |
|
62 |
+ ct_wq_blk_size - internal TLS pre-write (clear-text) queue |
|
63 |
+ minimum block size (advance tunning or debugging). |
|
64 |
+ Can be set at runtime (tls.ct_wq_blk_size). |
|
65 |
+ Default: 4096 (4 Kb). |
|
66 |
+ verbose debug messages can be enable by re-compiling with |
|
67 |
+ -DTLS_RD_DEBUG (for the read path) and -DTLS_WR_DEBUG |
|
68 |
+ (for the write path). |
|
69 |
+ new options for better tuning memory usage for modern openssl |
|
70 |
+ versions: ssl_release_buffers (default 1), ssl_freelist_max_len |
|
71 |
+ (default 0), ssl_max_send_fragment, ssl_read_ahead (default 0). |
|
72 |
+ For more info see modules/doc/tls/README. |
|
73 |
+ compression is now disabled by default. To enable it set |
|
46 | 74 |
tls_disable_compression to 0, but note that memory usage will |
47 | 75 |
increase dramatically especially for large number of |
48 | 76 |
connections (>1000). |
... | ... |
@@ -34,11 +34,15 @@ Andrei Pelinescu-Onciul |
34 | 34 |
1.8.14. ssl_free_list_max_len (integer) |
35 | 35 |
1.8.15. ssl_max_send_fragment (integer) |
36 | 36 |
1.8.16. ssl_read_ahead (boolean) |
37 |
- 1.8.17. tls_log (int) |
|
38 |
- 1.8.18. low_mem_threshold1 (integer) |
|
39 |
- 1.8.19. low_mem_threshold2 (integer) |
|
40 |
- 1.8.20. tls_force_run (boolean) |
|
41 |
- 1.8.21. config (string) |
|
37 |
+ 1.8.17. send_close_notify (boolean) |
|
38 |
+ 1.8.18. con_ct_wq_max (integer) |
|
39 |
+ 1.8.19. ct_wq_max (integer) |
|
40 |
+ 1.8.20. ct_wq_blk_size (integer) |
|
41 |
+ 1.8.21. tls_log (int) |
|
42 |
+ 1.8.22. low_mem_threshold1 (integer) |
|
43 |
+ 1.8.23. low_mem_threshold2 (integer) |
|
44 |
+ 1.8.24. tls_force_run (boolean) |
|
45 |
+ 1.8.25. config (string) |
|
42 | 46 |
|
43 | 47 |
1.9. Functions |
44 | 48 |
|
... | ... |
@@ -49,7 +53,7 @@ Andrei Pelinescu-Onciul |
49 | 49 |
1.1. Overview |
50 | 50 |
|
51 | 51 |
This module implements the TLS transport for SIP-router using the |
52 |
- Openssl library (http://www.openssl.org). To enable the TLS support |
|
52 |
+ OpenSSL library (http://www.openssl.org). To enable the TLS support |
|
53 | 53 |
this module must be loaded and enable_tls=yes must be added to the |
54 | 54 |
SIP-router config file |
55 | 55 |
|
... | ... |
@@ -103,12 +107,15 @@ route{ |
103 | 103 |
significantly slow down the TLS connection handshake, thus limiting the |
104 | 104 |
maximum SIP-router TLS connection rate. |
105 | 105 |
|
106 |
- Compression is fully supported and used by default, if you have a new |
|
107 |
- enough Openssl version (starting with 0.9.8). Although there are some |
|
108 |
- problems with zlib compression in currently deployed Openssl versions |
|
109 |
- (up to and including 0.9.8d, see openssl bug #1468), the TLS module |
|
110 |
- will automatically switch to its own fixed version. There's no need to |
|
111 |
- force-disable the compression. |
|
106 |
+ Compression is fully supported if you have a new enough Openssl version |
|
107 |
+ (starting with 0.9.8). Although there are some problems with zlib |
|
108 |
+ compression in currently deployed Openssl versions (up to and including |
|
109 |
+ 0.9.8d, see openssl bug #1468), the TLS module will automatically |
|
110 |
+ switch to its own fixed version. Note however that starting with sr 3.1 |
|
111 |
+ compression is not enabled by default, due to the huge extra memory |
|
112 |
+ consumption that it causes (about 10x more memory). To enable it use |
|
113 |
+ modparam("tls", "tls_disable_compression", 0) (see |
|
114 |
+ tls_disable_compression). |
|
112 | 115 |
|
113 | 116 |
The TLS module includes workarounds for the following known openssl |
114 | 117 |
bugs: openssl #1204 (disable SS_OP_TLS_BLOCK_PADDING_BUG if compression |
... | ... |
@@ -122,11 +129,10 @@ route{ |
122 | 122 |
1.4. Compiling the TLS Module |
123 | 123 |
|
124 | 124 |
In most case compiling the TLS module is as simple as: |
125 |
-make modules modules=modules/tls |
|
125 |
+make -C modules/tls |
|
126 | 126 |
|
127 | 127 |
or |
128 |
-cd modules/tls |
|
129 |
-make |
|
128 |
+make modules modules=modules/tls |
|
130 | 129 |
|
131 | 130 |
or (compiling whole SIP-router and the tls module) |
132 | 131 |
make all include_modules=tls |
... | ... |
@@ -173,8 +179,14 @@ make TLS_EXTRA_LIBS="-lkrb5 -lz" all include_modules=tls |
173 | 173 |
TLS specific config reloading is not safe, so for now better don't use |
174 | 174 |
it, especially under heavy traffic. |
175 | 175 |
|
176 |
- This documentation is incomplete. The select framework and rpc sections |
|
177 |
- are completely missing. |
|
176 |
+ This documentation is incomplete. The RPCs are not documented here, but |
|
177 |
+ in doc/rpc_list/rpc_tls.txt or |
|
178 |
+ http://sip-router.org/docbook/sip-router/branch/master/rpc_list/rpc_lis |
|
179 |
+ t.html#rpc_exports.tls. The provided selects are not documented. A list |
|
180 |
+ with all the ones implemented by the tls module can be seen under |
|
181 |
+ doc/select_list/select_tls.txt or or |
|
182 |
+ http://sip-router.org/docbook/sip-router/branch/master/select_list/sele |
|
183 |
+ ct_list.html#select_list.tls. |
|
178 | 184 |
|
179 | 185 |
1.7. Quick Certificate Howto |
180 | 186 |
|
... | ... |
@@ -401,22 +413,12 @@ modparam("tls", "cipher_list", "HIGH") |
401 | 401 |
sip-router 3.0). In these versions the send_timeout is replaced by |
402 | 402 |
tcp_send_timeout (common with all the tcp connections). |
403 | 403 |
|
404 |
- Example 10. Set send_timeout parameter |
|
405 |
-... |
|
406 |
-tls_send_timeout = 10 |
|
407 |
-... |
|
408 |
- |
|
409 | 404 |
1.8.10. handshake_timeout (int) |
410 | 405 |
|
411 | 406 |
This parameter is obsolete and cannot be used in newer TLS versions (> |
412 | 407 |
sip-router 3.0). In these versions the handshake_timeout is replaced by |
413 | 408 |
tcp_connect_timeout (common with all the tcp connections). |
414 | 409 |
|
415 |
- Example 11. Set handshake_timeout parameter |
|
416 |
-... |
|
417 |
-tcp_connect_timeout = 60 |
|
418 |
-... |
|
419 |
- |
|
420 | 410 |
1.8.11. connection_timeout (int) |
421 | 411 |
|
422 | 412 |
Sets the amount of time after which an idle TLS connection will be |
... | ... |
@@ -428,11 +430,17 @@ tcp_connect_timeout = 60 |
428 | 428 |
|
429 | 429 |
If the value set is -1, the connection will never be close on idle. |
430 | 430 |
|
431 |
- Example 12. Set connection_timeout parameter |
|
431 |
+ It can be changed also at runtime, via the RPC interface and config |
|
432 |
+ framework. The config variable name is tls.connection_timeout. |
|
433 |
+ |
|
434 |
+ Example 10. Set connection_timeout parameter |
|
432 | 435 |
... |
433 | 436 |
modparam("tls", "connection_timeout", 60) |
434 | 437 |
... |
435 | 438 |
|
439 |
+ Example 11. Set tls.connection_timeout at runtime |
|
440 |
+ $ sercmd cfg.set_now_int tls connection_timeout 180 |
|
441 |
+ |
|
436 | 442 |
1.8.12. tls_disable_compression (boolean) |
437 | 443 |
|
438 | 444 |
If set compression over SSL/TLS will be disabled. Note that compression |
... | ... |
@@ -442,7 +450,7 @@ modparam("tls", "connection_timeout", 60) |
442 | 442 |
|
443 | 443 |
By default compression is disabled. |
444 | 444 |
|
445 |
- Example 13. Set tls_disable_compression parameter |
|
445 |
+ Example 12. Set tls_disable_compression parameter |
|
446 | 446 |
... |
447 | 447 |
modparam("tls", "tls_disable_compression", 0) # enable |
448 | 448 |
... |
... | ... |
@@ -452,20 +460,21 @@ modparam("tls", "tls_disable_compression", 0) # enable |
452 | 452 |
Release internal OpenSSL read or write buffers as soon as they are no |
453 | 453 |
longer needed. Combined with ssl_free_list_max_len has the potential of |
454 | 454 |
saving a lot of memory ( ~ 32k per connection in the default |
455 |
- configuration, or 16k + ssl_max_send_fragment). |
|
455 |
+ configuration, or 16k + ssl_max_send_fragment). For sr versions > 3.0 |
|
456 |
+ it makes little sense to disable it (0) since the tls module already |
|
457 |
+ has its own internal buffering. |
|
456 | 458 |
|
457 | 459 |
A value of -1 would not change this option from its openssl default. |
458 | 460 |
Use 0 or 1 for enable/disable. |
459 | 461 |
|
460 |
- By default the value is -1 (the openssl default, which at least in |
|
461 |
- openssl 1.0.0 is 0/disabled). |
|
462 |
+ By default the value is 1 (enabled). |
|
462 | 463 |
|
463 | 464 |
Note |
464 | 465 |
|
465 | 466 |
This option is supported only for OpenSSL versions >= 1.0.0. On all the |
466 | 467 |
other versions attempting to change the default will trigger an error. |
467 | 468 |
|
468 |
- Example 14. Set ssl_release_buffers parameter |
|
469 |
+ Example 13. Set ssl_release_buffers parameter |
|
469 | 470 |
modparam("tls", "ssl_release_buffers", 1) |
470 | 471 |
|
471 | 472 |
1.8.14. ssl_free_list_max_len (integer) |
... | ... |
@@ -478,17 +487,17 @@ modparam("tls", "ssl_release_buffers", 1) |
478 | 478 |
Should be combined with ssl_release_buffers. |
479 | 479 |
|
480 | 480 |
A value of -1 has a special meaning: the OpenSSL default will be used |
481 |
- (no attempt on changing the value will be made). |
|
481 |
+ (no attempt on changing the value will be made). For OpenSSL 1.0 the |
|
482 |
+ internal default is 32. |
|
482 | 483 |
|
483 |
- By default the value is -1 (the OpenSSL default, which at least in |
|
484 |
- OpenSSL 1.0.0 is 32). |
|
484 |
+ By default the value is 0 (no freelist). |
|
485 | 485 |
|
486 | 486 |
Note |
487 | 487 |
|
488 | 488 |
This option is supported only for OpenSSL versions >= 1.0.0. On all the |
489 | 489 |
other versions attempting to change the default will trigger an error. |
490 | 490 |
|
491 |
- Example 15. Set ssl_freelist_max_len parameter |
|
491 |
+ Example 14. Set ssl_freelist_max_len parameter |
|
492 | 492 |
modparam("tls", "ssl_freelist_max_len", 0) |
493 | 493 |
|
494 | 494 |
1.8.15. ssl_max_send_fragment (integer) |
... | ... |
@@ -523,42 +532,130 @@ Note |
523 | 523 |
This option is supported only for OpenSSL versions >= 0.9.9. On all the |
524 | 524 |
other versions attempting to change the default will trigger an error. |
525 | 525 |
|
526 |
- Example 16. Set ssl_max_send_fragment parameter |
|
526 |
+ Example 15. Set ssl_max_send_fragment parameter |
|
527 | 527 |
modparam("tls", "ssl_max_send_fragment", 4096) |
528 | 528 |
|
529 | 529 |
1.8.16. ssl_read_ahead (boolean) |
530 | 530 |
|
531 |
- Enables read ahead, reducing the number of read() system calls done |
|
532 |
- internally by the OpenSSL library. |
|
531 |
+ Enables read ahead, reducing the number of internal OpenSSL BIO read() |
|
532 |
+ calls. This option has only debugging value, in normal circumstances it |
|
533 |
+ should not be changed from the default. |
|
533 | 534 |
|
534 |
- When disabled OpenSSL will make at least 2 read() sytem calls per |
|
535 |
+ When disabled OpenSSL will make at least 2 BIO read() calls per |
|
535 | 536 |
received record: one to get the record header and one to get the rest |
536 | 537 |
of the record. |
537 | 538 |
|
539 |
+ The TLS module buffers internally all read()s and defines its own fast |
|
540 |
+ BIO so enabling this option would only cause more memory consumption |
|
541 |
+ and a minor slow-down (extra memcpy). |
|
542 |
+ |
|
538 | 543 |
A value of -1 has a special meaning: the OpenSSL default will be used |
539 | 544 |
(no attempt on changing the value will be made). |
540 | 545 |
|
541 |
- By default the value is 1 (enabled). |
|
546 |
+ By default the value is 0 (disabled). |
|
542 | 547 |
|
543 |
- Example 17. Set ssl_read_ahead parameter |
|
548 |
+ Example 16. Set ssl_read_ahead parameter |
|
544 | 549 |
modparam("tls", "ssl_read_ahead", 1) |
545 | 550 |
|
546 |
-1.8.17. tls_log (int) |
|
551 |
+1.8.17. send_close_notify (boolean) |
|
552 |
+ |
|
553 |
+ Enables/disables sending close notify alerts prior to closing the |
|
554 |
+ corresponding TCP connection. Sending the close notify prior to tcp |
|
555 |
+ shutdown is "nicer" from a TLS point of view, but it has a measurable |
|
556 |
+ performance impact. Default: off. Can be set at runtime |
|
557 |
+ (tls.send_close_notify). |
|
558 |
+ |
|
559 |
+ The default value is 0 (off). |
|
560 |
+ |
|
561 |
+ It can be changed also at runtime, via the RPC interface and config |
|
562 |
+ framework. The config variable name is tls.send_close_notify. |
|
563 |
+ |
|
564 |
+ Example 17. Set send_close_notify parameter |
|
565 |
+... |
|
566 |
+modparam("tls", "send_close_notify", 1) |
|
567 |
+... |
|
568 |
+ |
|
569 |
+ Example 18. Set tls.send_close_notify at runtime |
|
570 |
+ $ sercmd cfg.set_now_int tls send_close_notify 1 |
|
571 |
+ |
|
572 |
+1.8.18. con_ct_wq_max (integer) |
|
573 |
+ |
|
574 |
+ Sets the maximum allowed per connection clear-text send queue size in |
|
575 |
+ bytes. This queue is used when data cannot be encrypted and sent |
|
576 |
+ immediately because of an ongoing TLS/SSL level renegotiation. |
|
577 |
+ |
|
578 |
+ The default value is 65536 (64 Kb). |
|
579 |
+ |
|
580 |
+ It can be changed also at runtime, via the RPC interface and config |
|
581 |
+ framework. The config variable name is tls.con_ct_wq_max. |
|
582 |
+ |
|
583 |
+ Example 19. Set con_ct_wq_max parameter |
|
584 |
+... |
|
585 |
+modparam("tls", "con_ct_wq_max", 1048576) |
|
586 |
+... |
|
587 |
+ |
|
588 |
+ Example 20. Set tls.con_ct_wq_max at runtime |
|
589 |
+ $ sercmd cfg.set_now_int tls con_ct_wq_max 1048576 |
|
590 |
+ |
|
591 |
+1.8.19. ct_wq_max (integer) |
|
592 |
+ |
|
593 |
+ Sets the maximum total number of bytes queued in all the clear-text |
|
594 |
+ send queues. These queues are used when data cannot be encrypted and |
|
595 |
+ sent immediately because of an ongoing TLS/SSL level renegotiation. |
|
596 |
+ |
|
597 |
+ The default value is 10485760 (10 Mb). |
|
598 |
+ |
|
599 |
+ It can be changed also at runtime, via the RPC interface and config |
|
600 |
+ framework. The config variable name is tls.ct_wq_max. |
|
601 |
+ |
|
602 |
+ Example 21. Set ct_wq_max parameter |
|
603 |
+... |
|
604 |
+modparam("tls", "ct_wq_max", 4194304) |
|
605 |
+... |
|
606 |
+ |
|
607 |
+ Example 22. Set tls.ct_wq_max at runtime |
|
608 |
+ $ sercmd cfg.set_now_int tls ct_wq_max 4194304 |
|
609 |
+ |
|
610 |
+1.8.20. ct_wq_blk_size (integer) |
|
611 |
+ |
|
612 |
+ Minimum block size for the internal clear-text send queues (debugging / |
|
613 |
+ advanced tunning). Good values are multiple of typical datagram sizes. |
|
614 |
+ |
|
615 |
+ The default value is 4096. |
|
616 |
+ |
|
617 |
+ It can be changed also at runtime, via the RPC interface and config |
|
618 |
+ framework. The config variable name is tls.ct_wq_blk_size. |
|
619 |
+ |
|
620 |
+ Example 23. Set ct_wq_blk_size parameter |
|
621 |
+... |
|
622 |
+modparam("tls", "ct_wq_blk_size", 2048) |
|
623 |
+... |
|
624 |
+ |
|
625 |
+ Example 24. Set tls.ct_wq_max at runtime |
|
626 |
+ $ sercmd cfg.set_now_int tls ct_wq_blk_size 2048 |
|
627 |
+ |
|
628 |
+1.8.21. tls_log (int) |
|
547 | 629 |
|
548 | 630 |
Sets the log level at which TLS related messages will be logged. |
549 | 631 |
|
550 | 632 |
The default value is 3. |
551 | 633 |
|
552 |
- Example 18. Set tls_log parameter |
|
634 |
+ It can be changed also at runtime, via the RPC interface and config |
|
635 |
+ framework. The config variable name is tls.log. |
|
636 |
+ |
|
637 |
+ Example 25. Set tls_log parameter |
|
553 | 638 |
... |
554 | 639 |
# ignore TLS messages if SIP-router is started with debug less than 10 |
555 | 640 |
modparam("tls", "tls_log", 10) |
556 | 641 |
... |
557 | 642 |
|
558 |
-1.8.18. low_mem_threshold1 (integer) |
|
643 |
+ Example 26. Set tls.log at runtime |
|
644 |
+ $ sercmd cfg.set_now_int tls log 10 |
|
645 |
+ |
|
646 |
+1.8.22. low_mem_threshold1 (integer) |
|
559 | 647 |
|
560 |
- Sets the minimal free memory from which new TLS connection will start |
|
561 |
- to fail. The value is expressed in KB. |
|
648 |
+ Sets the minimal free memory from which attempts to open or accept new |
|
649 |
+ TLS connections will start to fail. The value is expressed in KB. |
|
562 | 650 |
|
563 | 651 |
The default value depends on whether the openssl library used handles |
564 | 652 |
well low memory situations (openssl bug #1491). As of this writing this |
... | ... |
@@ -573,14 +670,20 @@ modparam("tls", "tls_log", 10) |
573 | 573 |
* -1 - use the default value |
574 | 574 |
* 0 - disable (TLS connections will not fail preemptively) |
575 | 575 |
|
576 |
+ It can be changed also at runtime, via the RPC interface and config |
|
577 |
+ framework. The config variable name is tls.low_mem_threshold1. |
|
578 |
+ |
|
576 | 579 |
See also low_mem_threshold2. |
577 | 580 |
|
578 |
- Example 19. Set low_mem_threshold1 parameter |
|
581 |
+ Example 27. Set low_mem_threshold1 parameter |
|
579 | 582 |
... |
580 | 583 |
modparam("tls", "low_mem_threshold1", -1) |
581 | 584 |
... |
582 | 585 |
|
583 |
-1.8.19. low_mem_threshold2 (integer) |
|
586 |
+ Example 28. Set tls.low_mem_threshold1 at runtime |
|
587 |
+ $ sercmd cfg.set_now_int tls low_mem_threshold1 2048 |
|
588 |
+ |
|
589 |
+1.8.23. low_mem_threshold2 (integer) |
|
584 | 590 |
|
585 | 591 |
Sets the minimal free memory from which TLS operations on already |
586 | 592 |
established TLS connections will start to fail preemptively. The value |
... | ... |
@@ -599,14 +702,20 @@ modparam("tls", "low_mem_threshold1", -1) |
599 | 599 |
* -1 - use the default value |
600 | 600 |
* 0 - disable (TLS operations will not fail preemptively) |
601 | 601 |
|
602 |
+ It can be changed also at runtime, via the RPC interface and config |
|
603 |
+ framework. The config variable name is tls.low_mem_threshold2. |
|
604 |
+ |
|
602 | 605 |
See also low_mem_threshold1. |
603 | 606 |
|
604 |
- Example 20. Set low_mem_threshold2 parameter |
|
607 |
+ Example 29. Set low_mem_threshold2 parameter |
|
605 | 608 |
... |
606 | 609 |
modparam("tls", "low_mem_threshold2", -1) |
607 | 610 |
... |
608 | 611 |
|
609 |
-1.8.20. tls_force_run (boolean) |
|
612 |
+ Example 30. Set tls.low_mem_threshold2 at runtime |
|
613 |
+ $ sercmd cfg.set_now_int tls low_mem_threshold2 1024 |
|
614 |
+ |
|
615 |
+1.8.24. tls_force_run (boolean) |
|
610 | 616 |
|
611 | 617 |
If enabled SIP-router will start even if some of the openssl sanity |
612 | 618 |
checks fail (turn it on at your own risk). |
... | ... |
@@ -622,12 +731,12 @@ modparam("tls", "low_mem_threshold2", -1) |
622 | 622 |
|
623 | 623 |
By default tls_force_run is disabled. |
624 | 624 |
|
625 |
- Example 21. Set tls_force_run parameter |
|
625 |
+ Example 31. Set tls_force_run parameter |
|
626 | 626 |
... |
627 | 627 |
modparam("tls", "tls_force_run", 11) |
628 | 628 |
... |
629 | 629 |
|
630 |
-1.8.21. config (string) |
|
630 |
+1.8.25. config (string) |
|
631 | 631 |
|
632 | 632 |
Sets the name of the TLS specific config file. |
633 | 633 |
|
... | ... |
@@ -653,7 +762,7 @@ modparam("tls", "tls_force_run", 11) |
653 | 653 |
client when it initiates a new connection by itself (it connects to |
654 | 654 |
something). |
655 | 655 |
|
656 |
- Example 22. Short config file |
|
656 |
+ Example 32. Short config file |
|
657 | 657 |
[server:default] |
658 | 658 |
method = TLSv1 |
659 | 659 |
verify_certificate = no |
... | ... |
@@ -679,11 +788,18 @@ ca_list = local_ca.pem |
679 | 679 |
For a more complete example check the tls.cfg distributed with the |
680 | 680 |
SIP-router source (sip_router/modules/tls/tls.cfg). |
681 | 681 |
|
682 |
- Example 23. Set config parameter |
|
682 |
+ Example 33. Set config parameter |
|
683 | 683 |
... |
684 | 684 |
modparam("tls", "config", "/usr/local/etc/ser/tls.cfg") |
685 | 685 |
... |
686 | 686 |
|
687 |
+ It can be changed also at runtime. The new config will not be loaded |
|
688 |
+ immediately, but after the first tls.reload RPC call. |
|
689 |
+ |
|
690 |
+ Example 34. Change and reload tls config at runtime |
|
691 |
+ $ sercmd cfg.set_now_string tls config "/usr/local/etc/ser/new_tls.cfg" |
|
692 |
+ $ sercmd tls.reload |
|
693 |
+ |
|
687 | 694 |
1.9. Functions |
688 | 695 |
|
689 | 696 |
Revision History |
... | ... |
@@ -695,7 +811,7 @@ modparam("tls", "config", "/usr/local/etc/ser/tls.cfg") |
695 | 695 |
, the peer presented an X509 certificate and the certificate chain |
696 | 696 |
verified ok. It can be used only in a request route. |
697 | 697 |
|
698 |
- Example 24. is_peer_verified usage |
|
698 |
+ Example 35. is_peer_verified usage |
|
699 | 699 |
if (proto==TLS && !is_peer_verified()){ |
700 | 700 |
sl_send_reply("400", "No certificate or verification failed"); |
701 | 701 |
drop; |
... | ... |
@@ -715,5 +831,9 @@ modparam("tls", "config", "/usr/local/etc/ser/tls.cfg") |
715 | 715 |
multiple domains, a tls specific config, config reloading and a tls |
716 | 716 |
specific select framework. |
717 | 717 |
|
718 |
+ For ser/sr 3.1 most of the TLS specific code was completely re-written |
|
719 |
+ to add support for asynchrounous TLS and fix several long standing |
|
720 |
+ bugs. |
|
721 |
+ |
|
718 | 722 |
The code is currently maintained by Andrei Pelinescu-Onciul |
719 | 723 |
<andrei@iptel.org>. |
... | ... |
@@ -17,6 +17,11 @@ |
17 | 17 |
This module was put together by Jan Janak <email>jan@iptel.org</email> from code from the experimental tls core addon (<ulink url="http://cvs.berlios.de/cgi-bin/viewcvs.cgi/ser/experimental/tls/">http://cvs.berlios.de/cgi-bin/viewcvs.cgi/ser/experimental/tls/</ulink>), code originally written by Peter Griffiths and later maintained by Cesc Santasusana and from an iptelorg tls code addon, written by Andrei Pelinescu-Onciul <email>andrei@iptel.org</email>. Jan also added support for multiple domains, a tls specific config, config reloading and a tls specific select framework. |
18 | 18 |
</para> |
19 | 19 |
<para> |
20 |
+ For ser/sr 3.1 most of the TLS specific code was completely |
|
21 |
+ re-written to add support for asynchrounous TLS and fix several |
|
22 |
+ long standing bugs. |
|
23 |
+ </para> |
|
24 |
+ <para> |
|
20 | 25 |
The code is currently maintained by Andrei Pelinescu-Onciul <email>andrei@iptel.org</email>. |
21 | 26 |
</para> |
22 | 27 |
</section> |
... | ... |
@@ -1,8 +1,13 @@ |
1 | 1 |
<?xml version="1.0" encoding="UTF-8"?> |
2 |
-<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
|
3 |
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> |
|
4 |
- |
|
5 |
-<section id="tm.parameters"> |
|
2 |
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
|
3 |
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
|
4 |
+ [<!-- Include general documentation entities --> |
|
5 |
+ <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml"> |
|
6 |
+ %docentities; |
|
7 |
+ ] |
|
8 |
+> |
|
9 |
+ |
|
10 |
+<section id="tls.parameters"> |
|
6 | 11 |
<sectioninfo> |
7 | 12 |
<revhistory> |
8 | 13 |
<revision> |
... | ... |
@@ -201,35 +206,21 @@ modparam("tls", "cipher_list", "HIGH") |
201 | 201 |
<section id="send_timeout"> |
202 | 202 |
<title><varname>send_timeout</varname> (int)</title> |
203 | 203 |
<para> |
204 |
- This parameter is obsolete and cannot be used in newer TLS versions |
|
205 |
- (> sip-router 3.0). In these versions the send_timeout is |
|
206 |
- replaced by tcp_send_timeout (common with all the tcp connections). |
|
204 |
+ This parameter is <emphasis>obsolete</emphasis> and cannot be used |
|
205 |
+ in newer TLS versions (> sip-router 3.0). In these versions the |
|
206 |
+ send_timeout is replaced by <varname>tcp_send_timeout</varname> |
|
207 |
+ (common with all the tcp connections). |
|
207 | 208 |
</para> |
208 |
- <example> |
|
209 |
- <title>Set <varname>send_timeout</varname> parameter</title> |
|
210 |
- <programlisting> |
|
211 |
-... |
|
212 |
-tls_send_timeout = 10 |
|
213 |
-... |
|
214 |
- </programlisting> |
|
215 |
- </example> |
|
216 | 209 |
</section> |
217 | 210 |
|
218 | 211 |
<section id="handshake_timeout"> |
219 | 212 |
<title><varname>handshake_timeout</varname> (int)</title> |
220 | 213 |
<para> |
221 |
- This parameter is obsolete and cannot be used in newer TLS versions |
|
222 |
- (> sip-router 3.0). In these versions the handshake_timeout is |
|
223 |
- replaced by tcp_connect_timeout (common with all the tcp connections). |
|
214 |
+ This parameter is <emphasis>obsolete</emphasis> and cannot be used |
|
215 |
+ in newer TLS versions (> sip-router 3.0). In these versions the |
|
216 |
+ handshake_timeout is replaced by <varname>tcp_connect_timeout</varname> |
|
217 |
+ (common with all the tcp connections). |
|
224 | 218 |
</para> |
225 |
- <example> |
|
226 |
- <title>Set <varname>handshake_timeout</varname> parameter</title> |
|
227 |
- <programlisting> |
|
228 |
-... |
|
229 |
-tcp_connect_timeout = 60 |
|
230 |
-... |
|
231 |
- </programlisting> |
|
232 |
- </example> |
|
233 | 219 |
</section> |
234 | 220 |
|
235 | 221 |
<section id="connection_timeout"> |
... | ... |
@@ -246,6 +237,10 @@ tcp_connect_timeout = 60 |
246 | 246 |
<para> |
247 | 247 |
If the value set is -1, the connection will never be close on idle. |
248 | 248 |
</para> |
249 |
+ <para> |
|
250 |
+ It can be changed also at runtime, via the RPC interface and config |
|
251 |
+ framework. The config variable name is tls.connection_timeout. |
|
252 |
+ </para> |
|
249 | 253 |
<example> |
250 | 254 |
<title>Set <varname>connection_timeout</varname> parameter</title> |
251 | 255 |
<programlisting> |
... | ... |
@@ -254,6 +249,12 @@ modparam("tls", "connection_timeout", 60) |
254 | 254 |
... |
255 | 255 |
</programlisting> |
256 | 256 |
</example> |
257 |
+ <example> |
|
258 |
+ <title>Set <varname>tls.connection_timeout</varname> at runtime</title> |
|
259 |
+ <programlisting> |
|
260 |
+ $ &sercmd; cfg.set_now_int tls connection_timeout 180 |
|
261 |
+ </programlisting> |
|
262 |
+ </example> |
|
257 | 263 |
</section> |
258 | 264 |
|
259 | 265 |
<section id="tls_disable_compression"> |
... | ... |
@@ -286,14 +287,15 @@ modparam("tls", "tls_disable_compression", 0) # enable |
286 | 286 |
<varname>ssl_free_list_max_len</varname> has the potential of saving |
287 | 287 |
a lot of memory ( ~ 32k per connection in the default configuration, |
288 | 288 |
or 16k + <varname>ssl_max_send_fragment</varname>). |
289 |
+ For sr versions > 3.0 it makes little sense to disable it (0) |
|
290 |
+ since the tls module already has its own internal buffering. |
|
289 | 291 |
</para> |
290 | 292 |
<para> |
291 | 293 |
A value of -1 would not change this option from its openssl default. |
292 | 294 |
Use 0 or 1 for enable/disable. |
293 | 295 |
</para> |
294 | 296 |
<para> |
295 |
- By default the value is -1 (the openssl default, which at least in |
|
296 |
- openssl 1.0.0 is 0/disabled). |
|
297 |
+ By default the value is 1 (enabled). |
|
297 | 298 |
</para> |
298 | 299 |
<note> |
299 | 300 |
<para> |
... | ... |
@@ -325,11 +327,11 @@ modparam("tls", "ssl_release_buffers", 1) |
325 | 325 |
</para> |
326 | 326 |
<para> |
327 | 327 |
A value of -1 has a special meaning: the OpenSSL default will be used |
328 |
- (no attempt on changing the value will be made). |
|
328 |
+ (no attempt on changing the value will be made). For OpenSSL 1.0 |
|
329 |
+ the internal default is 32. |
|
329 | 330 |
</para> |
330 | 331 |
<para> |
331 |
- By default the value is -1 (the OpenSSL default, which at least in |
|
332 |
- OpenSSL 1.0.0 is 32). |
|
332 |
+ By default the value is 0 (no freelist). |
|
333 | 333 |
</para> |
334 | 334 |
<note> |
335 | 335 |
<para> |
... | ... |
@@ -401,20 +403,26 @@ modparam("tls", "ssl_max_send_fragment", 4096) |
401 | 401 |
<section id="ssl_read_ahead"> |
402 | 402 |
<title><varname>ssl_read_ahead</varname> (boolean)</title> |
403 | 403 |
<para> |
404 |
- Enables read ahead, reducing the number of read() system calls |
|
405 |
- done internally by the OpenSSL library. |
|
404 |
+ Enables read ahead, reducing the number of internal OpenSSL BIO read() |
|
405 |
+ calls. This option has only debugging value, in normal circumstances |
|
406 |
+ it should not be changed from the default. |
|
406 | 407 |
</para> |
407 | 408 |
<para> |
408 |
- When disabled OpenSSL will make at least 2 read() sytem calls per |
|
409 |
+ When disabled OpenSSL will make at least 2 BIO read() calls per |
|
409 | 410 |
received record: one to get the record header and one to get the |
410 | 411 |
rest of the record. |
411 | 412 |
</para> |
412 | 413 |
<para> |
414 |
+ The TLS module buffers internally all read()s and defines its own fast |
|
415 |
+ BIO so enabling this option would only cause more memory consumption |
|
416 |
+ and a minor slow-down (extra memcpy). |
|
417 |
+ </para> |
|
418 |
+ <para> |
|
413 | 419 |
A value of -1 has a special meaning: the OpenSSL default will be used |
414 | 420 |
(no attempt on changing the value will be made). |
415 | 421 |
</para> |
416 | 422 |
<para> |
417 |
- By default the value is 1 (enabled). |
|
423 |
+ By default the value is 0 (disabled). |
|
418 | 424 |
</para> |
419 | 425 |
<example> |
420 | 426 |
<title>Set <varname>ssl_read_ahead</varname> parameter</title> |
... | ... |
@@ -425,6 +433,132 @@ modparam("tls", "ssl_read_ahead", 1) |
425 | 425 |
</section> |
426 | 426 |
|
427 | 427 |
|
428 |
+ <section id="send_close_notify"> |
|
429 |
+ <title><varname>send_close_notify</varname> (boolean)</title> |
|
430 |
+ <para> |
|
431 |
+ Enables/disables sending close notify alerts prior to closing the |
|
432 |
+ corresponding TCP connection. Sending the close notify prior to tcp |
|
433 |
+ shutdown is "nicer" from a TLS point of view, but it has a measurable |
|
434 |
+ performance impact. Default: off. Can be set at runtime |
|
435 |
+ (tls.send_close_notify). |
|
436 |
+ </para> |
|
437 |
+ <para> |
|
438 |
+ The default value is 0 (off). |
|
439 |
+ </para> |
|
440 |
+ <para> |
|
441 |
+ It can be changed also at runtime, via the RPC interface and config |
|
442 |
+ framework. The config variable name is tls.send_close_notify. |
|
443 |
+ </para> |
|
444 |
+ <example> |
|
445 |
+ <title>Set <varname>send_close_notify</varname> parameter</title> |
|
446 |
+ <programlisting> |
|
447 |
+... |
|
448 |
+modparam("tls", "send_close_notify", 1) |
|
449 |
+... |
|
450 |
+ </programlisting> |
|
451 |
+ </example> |
|
452 |
+ <example> |
|
453 |
+ <title>Set <varname>tls.send_close_notify</varname> at runtime</title> |
|
454 |
+ <programlisting> |
|
455 |
+ $ &sercmd; cfg.set_now_int tls send_close_notify 1 |
|
456 |
+ </programlisting> |
|
457 |
+ </example> |
|
458 |
+ </section> |
|
459 |
+ |
|
460 |
+ |
|
461 |
+ <section id="con_ct_wq_max"> |
|
462 |
+ <title><varname>con_ct_wq_max</varname> (integer)</title> |
|
463 |
+ <para> |
|
464 |
+ Sets the maximum allowed per connection clear-text send queue size in |
|
465 |
+ bytes. This queue is used when data cannot be encrypted and sent |
|
466 |
+ immediately because of an ongoing TLS/SSL level renegotiation. |
|
467 |
+ </para> |
|
468 |
+ <para> |
|
469 |
+ The default value is 65536 (64 Kb). |
|
470 |
+ </para> |
|
471 |
+ <para> |
|
472 |
+ It can be changed also at runtime, via the RPC interface and config |
|
473 |
+ framework. The config variable name is tls.con_ct_wq_max. |
|
474 |
+ </para> |
|
475 |
+ <example> |
|
476 |
+ <title>Set <varname>con_ct_wq_max</varname> parameter</title> |
|
477 |
+ <programlisting> |
|
478 |
+... |
|
479 |
+modparam("tls", "con_ct_wq_max", 1048576) |
|
480 |
+... |
|
481 |
+ </programlisting> |
|
482 |
+ </example> |
|
483 |
+ <example> |
|
484 |
+ <title>Set <varname>tls.con_ct_wq_max</varname> at runtime</title> |
|
485 |
+ <programlisting> |
|
486 |
+ $ &sercmd; cfg.set_now_int tls con_ct_wq_max 1048576 |
|
487 |
+ </programlisting> |
|
488 |
+ </example> |
|
489 |
+ </section> |
|
490 |
+ |
|
491 |
+ |
|
492 |
+ <section id="ct_wq_max"> |
|
493 |
+ <title><varname>ct_wq_max</varname> (integer)</title> |
|
494 |
+ <para> |
|
495 |
+ Sets the maximum total number of bytes queued in all the clear-text |
|
496 |
+ send queues. These queues are used when data cannot be encrypted and |
|
497 |
+ sent immediately because of an ongoing TLS/SSL level renegotiation. |
|
498 |
+ </para> |
|
499 |
+ <para> |
|
500 |
+ The default value is 10485760 (10 Mb). |
|
501 |
+ </para> |
|
502 |
+ <para> |
|
503 |
+ It can be changed also at runtime, via the RPC interface and config |
|
504 |
+ framework. The config variable name is tls.ct_wq_max. |
|
505 |
+ </para> |
|
506 |
+ <example> |
|
507 |
+ <title>Set <varname>ct_wq_max</varname> parameter</title> |
|
508 |
+ <programlisting> |
|
509 |
+... |
|
510 |
+modparam("tls", "ct_wq_max", 4194304) |
|
511 |
+... |
|
512 |
+ </programlisting> |
|
513 |
+ </example> |
|
514 |
+ <example> |
|
515 |
+ <title>Set <varname>tls.ct_wq_max</varname> at runtime</title> |
|
516 |
+ <programlisting> |
|
517 |
+ $ &sercmd; cfg.set_now_int tls ct_wq_max 4194304 |
|
518 |
+ </programlisting> |
|
519 |
+ </example> |
|
520 |
+ </section> |
|
521 |
+ |
|
522 |
+ |
|
523 |
+ <section id="ct_wq_blk_size"> |
|
524 |
+ <title><varname>ct_wq_blk_size</varname> (integer)</title> |
|
525 |
+ <para> |
|
526 |
+ Minimum block size for the internal clear-text send queues |
|
527 |
+ (debugging / advanced tunning). |
|
528 |
+ Good values are multiple of typical datagram sizes. |
|
529 |
+ </para> |
|
530 |
+ <para> |
|
531 |
+ The default value is 4096. |
|
532 |
+ </para> |
|
533 |
+ <para> |
|
534 |
+ It can be changed also at runtime, via the RPC interface and config |
|
535 |
+ framework. The config variable name is tls.ct_wq_blk_size. |
|
536 |
+ </para> |
|
537 |
+ <example> |
|
538 |
+ <title>Set <varname>ct_wq_blk_size</varname> parameter</title> |
|
539 |
+ <programlisting> |
|
540 |
+... |
|
541 |
+modparam("tls", "ct_wq_blk_size", 2048) |
|
542 |
+... |
|
543 |
+ </programlisting> |
|
544 |
+ </example> |
|
545 |
+ <example> |
|
546 |
+ <title>Set <varname>tls.ct_wq_max</varname> at runtime</title> |
|
547 |
+ <programlisting> |
|
548 |
+ $ &sercmd; cfg.set_now_int tls ct_wq_blk_size 2048 |
|
549 |
+ </programlisting> |
|
550 |
+ </example> |
|
551 |
+ </section> |
|
552 |
+ |
|
553 |
+ |
|
428 | 554 |
<section id="tls_log"> |
429 | 555 |
<title><varname>tls_log</varname> (int)</title> |
430 | 556 |
<para> |
... | ... |
@@ -433,6 +567,10 @@ modparam("tls", "ssl_read_ahead", 1) |
433 | 433 |
<para> |
434 | 434 |
The default value is 3. |
435 | 435 |
</para> |
436 |
+ <para> |
|
437 |
+ It can be changed also at runtime, via the RPC interface and config |
|
438 |
+ framework. The config variable name is tls.log. |
|
439 |
+ </para> |
|
436 | 440 |
<example> |
437 | 441 |
<title>Set <varname>tls_log</varname> parameter</title> |
438 | 442 |
<programlisting> |
... | ... |
@@ -442,13 +580,20 @@ modparam("tls", "tls_log", 10) |
442 | 442 |
... |
443 | 443 |
</programlisting> |
444 | 444 |
</example> |
445 |
+ <example> |
|
446 |
+ <title>Set <varname>tls.log</varname> at runtime</title> |
|
447 |
+ <programlisting> |
|
448 |
+ $ &sercmd; cfg.set_now_int tls log 10 |
|
449 |
+ </programlisting> |
|
450 |
+ </example> |
|
445 | 451 |
</section> |
446 | 452 |
|
447 | 453 |
|
448 | 454 |
<section id="low_mem_threshold1"> |
449 | 455 |
<title><varname>low_mem_threshold1</varname> (integer)</title> |
450 | 456 |
<para> |
451 |
- Sets the minimal free memory from which new TLS connection will start to fail. The value is expressed in KB. |
|
457 |
+ Sets the minimal free memory from which attempts to open or accept |
|
458 |
+ new TLS connections will start to fail. The value is expressed in KB. |
|
452 | 459 |
</para> |
453 | 460 |
<para> |
454 | 461 |
The default value depends on whether the openssl library used handles well low memory situations (openssl bug #1491). As of this writing this is not true for any openssl version (including 0.9.8e). |
... | ... |
@@ -472,6 +617,10 @@ modparam("tls", "tls_log", 10) |
472 | 472 |
</listitem> |
473 | 473 |
</itemizedlist> |
474 | 474 |
<para> |
475 |
+ It can be changed also at runtime, via the RPC interface and config |
|
476 |
+ framework. The config variable name is tls.low_mem_threshold1. |
|
477 |
+ </para> |
|
478 |
+ <para> |
|
475 | 479 |
See also <varname>low_mem_threshold2</varname>. |
476 | 480 |
</para> |
477 | 481 |
<example> |
... | ... |
@@ -482,6 +631,12 @@ modparam("tls", "low_mem_threshold1", -1) |
482 | 482 |
... |
483 | 483 |
</programlisting> |
484 | 484 |
</example> |
485 |
+ <example> |
|
486 |
+ <title>Set <varname>tls.low_mem_threshold1</varname> at runtime</title> |
|
487 |
+ <programlisting> |
|
488 |
+ $ &sercmd; cfg.set_now_int tls low_mem_threshold1 2048 |
|
489 |
+ </programlisting> |
|
490 |
+ </example> |
|
485 | 491 |
</section> |
486 | 492 |
|
487 | 493 |
<section id="low_mem_threshold2"> |
... | ... |
@@ -511,6 +666,10 @@ modparam("tls", "low_mem_threshold1", -1) |
511 | 511 |
</listitem> |
512 | 512 |
</itemizedlist> |
513 | 513 |
<para> |
514 |
+ It can be changed also at runtime, via the RPC interface and config |
|
515 |
+ framework. The config variable name is tls.low_mem_threshold2. |
|
516 |
+ </para> |
|
517 |
+ <para> |
|
514 | 518 |
See also <varname>low_mem_threshold1</varname>. |
515 | 519 |
</para> |
516 | 520 |
<example> |
... | ... |
@@ -521,6 +680,12 @@ modparam("tls", "low_mem_threshold2", -1) |
521 | 521 |
... |
522 | 522 |
</programlisting> |
523 | 523 |
</example> |
524 |
+ <example> |
|
525 |
+ <title>Set <varname>tls.low_mem_threshold2</varname> at runtime</title> |
|
526 |
+ <programlisting> |
|
527 |
+ $ &sercmd; cfg.set_now_int tls low_mem_threshold2 1024 |
|
528 |
+ </programlisting> |
|
529 |
+ </example> |
|
524 | 530 |
</section> |
525 | 531 |
|
526 | 532 |
<section id="tls_force_run"> |
... | ... |
@@ -621,6 +786,17 @@ modparam("tls", "config", "/usr/local/etc/ser/tls.cfg") |
621 | 621 |
... |
622 | 622 |
</programlisting> |
623 | 623 |
</example> |
624 |
+ <para> |
|
625 |
+ It can be changed also at runtime. The new config will not be loaded |
|
626 |
+ immediately, but after the first tls.reload RPC call. |
|
627 |
+ <example> |
|
628 |
+ <title>Change and reload tls config at runtime</title> |
|
629 |
+ <programlisting> |
|
630 |
+ $ &sercmd; cfg.set_now_string tls config "/usr/local/etc/ser/new_tls.cfg" |
|
631 |
+ $ &sercmd; tls.reload |
|
632 |
+ </programlisting> |
|
633 |
+ </example> |
|
634 |
+ </para> |
|
624 | 635 |
</section> |
625 | 636 |
|
626 | 637 |
</section> |
... | ... |
@@ -2,7 +2,7 @@ |
2 | 2 |
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
3 | 3 |
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
4 | 4 |
[ <!ENTITY % local.common.attrib |
5 |
- "xmlns:xi CDATA #FIXED 'http://www.w3.org/2001/XInclude'">] |
|
5 |
+ "xmlns:xi CDATA #FIXED 'http://www.w3.org/2001/XInclude'"> ] |
|
6 | 6 |
> |
7 | 7 |
|
8 | 8 |
<section id="tls" xmlns:xi="http://www.w3.org/2001/XInclude"> |
... | ... |
@@ -34,7 +34,7 @@ |
34 | 34 |
<section id="tls.overview"> |
35 | 35 |
<title>Overview</title> |
36 | 36 |
<para> |
37 |
- This module implements the TLS transport for SIP-router using the <ulink url="http://www.openssl.org">Openssl library</ulink> (http://www.openssl.org). To enable the TLS support this module must be loaded and <emphasis>enable_tls=yes</emphasis> must be added to the SIP-router config file |
|
37 |
+ This module implements the TLS transport for SIP-router using the <ulink url="http://www.openssl.org">OpenSSL library</ulink> (http://www.openssl.org). To enable the TLS support this module must be loaded and <emphasis>enable_tls=yes</emphasis> must be added to the SIP-router config file |
|
38 | 38 |
</para> |
39 | 39 |
</section> |
40 | 40 |
<section id="tls.quick_start"> |
... | ... |
@@ -76,7 +76,9 @@ route{ |
76 | 76 |
Try to avoid using keys larger then 1024 bytes. Large keys significantly slow down the TLS connection handshake, thus limiting the maximum SIP-router TLS connection rate. |
77 | 77 |
</para> |
78 | 78 |
<para> |
79 |
- Compression is fully supported and used by default, if you have a new enough Openssl version (starting with 0.9.8). Although there are some problems with zlib compression in currently deployed Openssl versions (up to and including 0.9.8d, see openssl bug #1468), the TLS module will automatically switch to its own fixed version. There's no need to force-disable the compression. |
|
79 |
+ Compression is fully supported if you have a new enough Openssl version (starting with 0.9.8). Although there are some problems with zlib compression in currently deployed Openssl versions (up to and including 0.9.8d, see openssl bug #1468), the TLS module will automatically switch to its own fixed version. |
|
80 |
+ Note however that starting with sr 3.1 compression is not enabled by default, due to the huge extra memory consumption that it causes (about 10x more memory). To enable it use modparam("tls", "tls_disable_compression", 0) |
|
81 |
+ (see <varname>tls_disable_compression</varname>). |
|
80 | 82 |
</para> |
81 | 83 |
<para> |
82 | 84 |
The TLS module includes workarounds for the following known openssl bugs: openssl #1204 (disable SS_OP_TLS_BLOCK_PADDING_BUG if compression is enabled, for versions between 0.9.8 and 0.9.8c), openssl #1468 (fix zlib compression memory allocation), openssl #1467 (kerberos support will be disabled if the openssl version is less than 0.9.8e-beta1) and openssl #1491 (stop using tls in low memory situations due to the very high risk of openssl crashing or leaking memory). The bug reports can be viewed at |
... | ... |
@@ -90,12 +92,11 @@ route{ |
90 | 90 |
<para> |
91 | 91 |
In most case compiling the TLS module is as simple as: |
92 | 92 |
<programlisting> |
93 |
-make modules modules=modules/tls |
|
93 |
+make -C modules/tls |
|
94 | 94 |
</programlisting> |
95 | 95 |
or |
96 | 96 |
<programlisting> |
97 |
-cd modules/tls |
|
98 |
-make |
|
97 |
+make modules modules=modules/tls |
|
99 | 98 |
</programlisting> |
100 | 99 |
or (compiling whole SIP-router and the tls module) |
101 | 100 |
<programlisting> |
... | ... |
@@ -133,7 +134,15 @@ make TLS_EXTRA_LIBS="-lkrb5 -lz" all include_modules=tls |
133 | 133 |
TLS specific config reloading is not safe, so for now better don't use it, especially under heavy traffic. |
134 | 134 |
</para> |
135 | 135 |
<para> |
136 |
- This documentation is incomplete. The select framework and rpc sections are completely missing. |
|
136 |
+ This documentation is incomplete. |
|
137 |
+ The RPCs are not documented here, but in doc/rpc_list/rpc_tls.txt |
|
138 |
+ or <ulink url="http://sip-router.org/docbook/sip-router/branch/master/rpc_list/rpc_list.html#rpc_exports.tls"> |
|
139 |
+ http://sip-router.org/docbook/sip-router/branch/master/rpc_list/rpc_list.html#rpc_exports.tls</ulink>. |
|
140 |
+ The provided selects are not documented. A list with all the |
|
141 |
+ ones implemented by the tls module can be seen under |
|
142 |
+ doc/select_list/select_tls.txt or |
|
143 |
+ or <ulink url="http://sip-router.org/docbook/sip-router/branch/master/select_list/select_list.html#select_list.tls"> |
|
144 |
+ http://sip-router.org/docbook/sip-router/branch/master/select_list/select_list.html#select_list.tls</ulink>. |
|
137 | 145 |
</para> |
138 | 146 |
</section> |
139 | 147 |
|