Browse code

tls: doc - new & async related config options

- 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.

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