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 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
-		(&gt; 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 (&gt; 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
-		(&gt; 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 (&gt; 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 &gt; 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