tls: doc - new & async related config options
authorAndrei Pelinescu-Onciul <andrei@iptel.org>
Sun, 15 Aug 2010 15:47:17 +0000 (17:47 +0200)
committerAndrei Pelinescu-Onciul <andrei@iptel.org>
Sun, 15 Aug 2010 16:03:01 +0000 (18:03 +0200)
- 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.

NEWS
modules/tls/README
modules/tls/doc/history.xml
modules/tls/doc/params.xml
modules/tls/doc/tls.xml

diff --git a/NEWS b/NEWS
index 1e5d4b5..e0ab4cf 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -6,6 +6,7 @@ $Id$
 sip-router 3.1 chages
 
 core:
+  - asynchronous TLS support
   - onreply_route {...} is now equivalent with onreply_route[0] {...}
   - global, per protocol blacklist ignore masks (via extended send_flags).
     See dst_blacklist_udp_imask a.s.o (dst_blacklist_*_imask).
@@ -38,11 +39,39 @@ modules:
            blst_rpl_clear_ignore(mask): like blst_rpl_ignore(mask), but
             clears instead of setting.
    - tls:
-           new options for better tuning memory usage for modern openssl
-            versions: ssl_release_buffers, ssl_freelist_max_len,
-            ssl_max_send_fragment, ssl_read_ahead. For more info see
-            modules/doc/tls/README.
-           compression is now disabled by default. To enable it set
+          asynchronous TLS support
+          new TLS RPCs (tls.info, tls.options), tls.list more detailed.
+          removed handshake_timeout and send_timeout module parameters /
+            config variables. The values from tcp are used instead
+            (tcp_connect_timeout and tcp_send_timeout).
+          runtime config support
+          more config options:
+            send_close_notify - enables/disables sending close notify
+              alerts prior to closing the corresponding TCP connection.
+              Sending the close notify prior to tcp shutdown is "nicer"
+              from a TLS point of view, but it has a measurable
+              performance impact. Default: off. Can be set at runtime
+              (tls.send_close_notify).
+            con_ct_wq_max - per connection tls maximum clear text write
+              queue size.  The TLS clear-text write queues are used when a
+              send attempt has to be delayed due to an on-going TLS level
+              renegotiation. Can be set at runtime (tls.con_ct_wq_max).
+              Default: 65536 (64 Kb).
+            ct_wq_max - maximum total for all the tls clear text write
+              queues (summed). Can be set at runtime (tls.ct_wq_max).
+              Default: 10485760 (10 Mb).
+            ct_wq_blk_size - internal TLS pre-write (clear-text) queue
+              minimum block size (advance tunning or debugging).
+              Can be set at runtime (tls.ct_wq_blk_size).
+              Default: 4096 (4 Kb).
+          verbose debug messages can be enable by re-compiling with
+            -DTLS_RD_DEBUG (for the read path) and -DTLS_WR_DEBUG
+            (for the write path).
+          new options for better tuning memory usage for modern openssl
+            versions: ssl_release_buffers (default 1), ssl_freelist_max_len
+            (default 0), ssl_max_send_fragment, ssl_read_ahead (default 0).
+            For more info see modules/doc/tls/README.
+          compression is now disabled by default. To enable it set
             tls_disable_compression to 0, but note that memory usage will
             increase dramatically especially for large number of
             connections (>1000).
index 1532c9f..cc35940 100644 (file)
@@ -34,11 +34,15 @@ Andrei Pelinescu-Onciul
         1.8.14. ssl_free_list_max_len (integer)
         1.8.15. ssl_max_send_fragment (integer)
         1.8.16. ssl_read_ahead (boolean)
-        1.8.17. tls_log (int)
-        1.8.18. low_mem_threshold1 (integer)
-        1.8.19. low_mem_threshold2 (integer)
-        1.8.20. tls_force_run (boolean)
-        1.8.21. config (string)
+        1.8.17. send_close_notify (boolean)
+        1.8.18. con_ct_wq_max (integer)
+        1.8.19. ct_wq_max (integer)
+        1.8.20. ct_wq_blk_size (integer)
+        1.8.21. tls_log (int)
+        1.8.22. low_mem_threshold1 (integer)
+        1.8.23. low_mem_threshold2 (integer)
+        1.8.24. tls_force_run (boolean)
+        1.8.25. config (string)
 
    1.9. Functions
 
@@ -49,7 +53,7 @@ Andrei Pelinescu-Onciul
 1.1. Overview
 
    This module implements the TLS transport for SIP-router using the
-   Openssl library (http://www.openssl.org). To enable the TLS support
+   OpenSSL library (http://www.openssl.org). To enable the TLS support
    this module must be loaded and enable_tls=yes must be added to the
    SIP-router config file
 
@@ -103,12 +107,15 @@ route{
    significantly slow down the TLS connection handshake, thus limiting the
    maximum SIP-router TLS connection rate.
 
-   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.
+   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. 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) (see
+   tls_disable_compression).
 
    The TLS module includes workarounds for the following known openssl
    bugs: openssl #1204 (disable SS_OP_TLS_BLOCK_PADDING_BUG if compression
@@ -122,11 +129,10 @@ route{
 1.4. Compiling the TLS Module
 
    In most case compiling the TLS module is as simple as:
-make modules modules=modules/tls
+make -C modules/tls
 
    or
-cd modules/tls
-make
+make modules modules=modules/tls
 
    or (compiling whole SIP-router and the tls module)
 make all include_modules=tls
@@ -173,8 +179,14 @@ make TLS_EXTRA_LIBS="-lkrb5 -lz" all include_modules=tls
    TLS specific config reloading is not safe, so for now better don't use
    it, especially under heavy traffic.
 
-   This documentation is incomplete. The select framework and rpc sections
-   are completely missing.
+   This documentation is incomplete. The RPCs are not documented here, but
+   in doc/rpc_list/rpc_tls.txt or
+   http://sip-router.org/docbook/sip-router/branch/master/rpc_list/rpc_lis
+   t.html#rpc_exports.tls. The provided selects are not documented. A list
+   with all the ones implemented by the tls module can be seen under
+   doc/select_list/select_tls.txt or or
+   http://sip-router.org/docbook/sip-router/branch/master/select_list/sele
+   ct_list.html#select_list.tls.
 
 1.7. Quick Certificate Howto
 
@@ -401,22 +413,12 @@ modparam("tls", "cipher_list", "HIGH")
    sip-router 3.0). In these versions the send_timeout is replaced by
    tcp_send_timeout (common with all the tcp connections).
 
-   Example 10. Set send_timeout parameter
-...
-tls_send_timeout = 10
-...
-
 1.8.10. handshake_timeout (int)
 
    This parameter is obsolete and cannot be used in newer TLS versions (>
    sip-router 3.0). In these versions the handshake_timeout is replaced by
    tcp_connect_timeout (common with all the tcp connections).
 
-   Example 11. Set handshake_timeout parameter
-...
-tcp_connect_timeout = 60
-...
-
 1.8.11. connection_timeout (int)
 
    Sets the amount of time after which an idle TLS connection will be
@@ -428,11 +430,17 @@ tcp_connect_timeout = 60
 
    If the value set is -1, the connection will never be close on idle.
 
-   Example 12. Set connection_timeout parameter
+   It can be changed also at runtime, via the RPC interface and config
+   framework. The config variable name is tls.connection_timeout.
+
+   Example 10. Set connection_timeout parameter
 ...
 modparam("tls", "connection_timeout", 60)
 ...
 
+   Example 11. Set tls.connection_timeout at runtime
+ $ sercmd cfg.set_now_int tls connection_timeout 180
+
 1.8.12. tls_disable_compression (boolean)
 
    If set compression over SSL/TLS will be disabled. Note that compression
@@ -442,7 +450,7 @@ modparam("tls", "connection_timeout", 60)
 
    By default compression is disabled.
 
-   Example 13. Set tls_disable_compression parameter
+   Example 12. Set tls_disable_compression parameter
 ...
 modparam("tls", "tls_disable_compression", 0) # enable
 ...
@@ -452,20 +460,21 @@ modparam("tls", "tls_disable_compression", 0) # enable
    Release internal OpenSSL read or write buffers as soon as they are no
    longer needed. Combined with ssl_free_list_max_len has the potential of
    saving a lot of memory ( ~ 32k per connection in the default
-   configuration, or 16k + ssl_max_send_fragment).
+   configuration, or 16k + ssl_max_send_fragment). For sr versions > 3.0
+   it makes little sense to disable it (0) since the tls module already
+   has its own internal buffering.
 
    A value of -1 would not change this option from its openssl default.
    Use 0 or 1 for enable/disable.
 
-   By default the value is -1 (the openssl default, which at least in
-   openssl 1.0.0 is 0/disabled).
+   By default the value is 1 (enabled).
 
 Note
 
    This option is supported only for OpenSSL versions >= 1.0.0. On all the
    other versions attempting to change the default will trigger an error.
 
-   Example 14. Set ssl_release_buffers parameter
+   Example 13. Set ssl_release_buffers parameter
 modparam("tls", "ssl_release_buffers", 1)
 
 1.8.14. ssl_free_list_max_len (integer)
@@ -478,17 +487,17 @@ modparam("tls", "ssl_release_buffers", 1)
    Should be combined with ssl_release_buffers.
 
    A value of -1 has a special meaning: the OpenSSL default will be used
-   (no attempt on changing the value will be made).
+   (no attempt on changing the value will be made). For OpenSSL 1.0 the
+   internal default is 32.
 
-   By default the value is -1 (the OpenSSL default, which at least in
-   OpenSSL 1.0.0 is 32).
+   By default the value is 0 (no freelist).
 
 Note
 
    This option is supported only for OpenSSL versions >= 1.0.0. On all the
    other versions attempting to change the default will trigger an error.
 
-   Example 15. Set ssl_freelist_max_len parameter
+   Example 14. Set ssl_freelist_max_len parameter
 modparam("tls", "ssl_freelist_max_len", 0)
 
 1.8.15. ssl_max_send_fragment (integer)
@@ -523,42 +532,130 @@ Note
    This option is supported only for OpenSSL versions >= 0.9.9. On all the
    other versions attempting to change the default will trigger an error.
 
-   Example 16. Set ssl_max_send_fragment parameter
+   Example 15. Set ssl_max_send_fragment parameter
 modparam("tls", "ssl_max_send_fragment", 4096)
 
 1.8.16. ssl_read_ahead (boolean)
 
-   Enables read ahead, reducing the number of read() system calls done
-   internally by the OpenSSL library.
+   Enables read ahead, reducing the number of internal OpenSSL BIO read()
+   calls. This option has only debugging value, in normal circumstances it
+   should not be changed from the default.
 
-   When disabled OpenSSL will make at least 2 read() sytem calls per
+   When disabled OpenSSL will make at least 2 BIO read() calls per
    received record: one to get the record header and one to get the rest
    of the record.
 
+   The TLS module buffers internally all read()s and defines its own fast
+   BIO so enabling this option would only cause more memory consumption
+   and a minor slow-down (extra memcpy).
+
    A value of -1 has a special meaning: the OpenSSL default will be used
    (no attempt on changing the value will be made).
 
-   By default the value is 1 (enabled).
+   By default the value is 0 (disabled).
 
-   Example 17. Set ssl_read_ahead parameter
+   Example 16. Set ssl_read_ahead parameter
 modparam("tls", "ssl_read_ahead", 1)
 
-1.8.17. tls_log (int)
+1.8.17. send_close_notify (boolean)
+
+   Enables/disables sending close notify alerts prior to closing the
+   corresponding TCP connection. Sending the close notify prior to tcp
+   shutdown is "nicer" from a TLS point of view, but it has a measurable
+   performance impact. Default: off. Can be set at runtime
+   (tls.send_close_notify).
+
+   The default value is 0 (off).
+
+   It can be changed also at runtime, via the RPC interface and config
+   framework. The config variable name is tls.send_close_notify.
+
+   Example 17. Set send_close_notify parameter
+...
+modparam("tls", "send_close_notify", 1)
+...
+
+   Example 18. Set tls.send_close_notify at runtime
+ $ sercmd cfg.set_now_int tls send_close_notify 1
+
+1.8.18. con_ct_wq_max (integer)
+
+   Sets the maximum allowed per connection clear-text send queue size in
+   bytes. This queue is used when data cannot be encrypted and sent
+   immediately because of an ongoing TLS/SSL level renegotiation.
+
+   The default value is 65536 (64 Kb).
+
+   It can be changed also at runtime, via the RPC interface and config
+   framework. The config variable name is tls.con_ct_wq_max.
+
+   Example 19. Set con_ct_wq_max parameter
+...
+modparam("tls", "con_ct_wq_max", 1048576)
+...
+
+   Example 20. Set tls.con_ct_wq_max at runtime
+ $ sercmd cfg.set_now_int tls con_ct_wq_max 1048576
+
+1.8.19. ct_wq_max (integer)
+
+   Sets the maximum total number of bytes queued in all the clear-text
+   send queues. These queues are used when data cannot be encrypted and
+   sent immediately because of an ongoing TLS/SSL level renegotiation.
+
+   The default value is 10485760 (10 Mb).
+
+   It can be changed also at runtime, via the RPC interface and config
+   framework. The config variable name is tls.ct_wq_max.
+
+   Example 21. Set ct_wq_max parameter
+...
+modparam("tls", "ct_wq_max", 4194304)
+...
+
+   Example 22. Set tls.ct_wq_max at runtime
+ $ sercmd cfg.set_now_int tls ct_wq_max 4194304
+
+1.8.20. ct_wq_blk_size (integer)
+
+   Minimum block size for the internal clear-text send queues (debugging /
+   advanced tunning). Good values are multiple of typical datagram sizes.
+
+   The default value is 4096.
+
+   It can be changed also at runtime, via the RPC interface and config
+   framework. The config variable name is tls.ct_wq_blk_size.
+
+   Example 23. Set ct_wq_blk_size parameter
+...
+modparam("tls", "ct_wq_blk_size", 2048)
+...
+
+   Example 24. Set tls.ct_wq_max at runtime
+ $ sercmd cfg.set_now_int tls ct_wq_blk_size 2048
+
+1.8.21. tls_log (int)
 
    Sets the log level at which TLS related messages will be logged.
 
    The default value is 3.
 
-   Example 18. Set tls_log parameter
+   It can be changed also at runtime, via the RPC interface and config
+   framework. The config variable name is tls.log.
+
+   Example 25. Set tls_log parameter
 ...
 # ignore TLS messages if SIP-router is started with debug less than 10
 modparam("tls", "tls_log", 10)
 ...
 
-1.8.18. low_mem_threshold1 (integer)
+   Example 26. Set tls.log at runtime
+ $ sercmd cfg.set_now_int tls log 10
+
+1.8.22. low_mem_threshold1 (integer)
 
-   Sets the minimal free memory from which new TLS connection will start
-   to fail. The value is expressed in KB.
+   Sets the minimal free memory from which attempts to open or accept new
+   TLS connections will start to fail. The value is expressed in KB.
 
    The default value depends on whether the openssl library used handles
    well low memory situations (openssl bug #1491). As of this writing this
@@ -573,14 +670,20 @@ modparam("tls", "tls_log", 10)
      * -1 - use the default value
      * 0 - disable (TLS connections will not fail preemptively)
 
+   It can be changed also at runtime, via the RPC interface and config
+   framework. The config variable name is tls.low_mem_threshold1.
+
    See also low_mem_threshold2.
 
-   Example 19. Set low_mem_threshold1 parameter
+   Example 27. Set low_mem_threshold1 parameter
 ...
 modparam("tls", "low_mem_threshold1", -1)
 ...
 
-1.8.19. low_mem_threshold2 (integer)
+   Example 28. Set tls.low_mem_threshold1 at runtime
+ $ sercmd cfg.set_now_int tls low_mem_threshold1 2048
+
+1.8.23. low_mem_threshold2 (integer)
 
    Sets the minimal free memory from which TLS operations on already
    established TLS connections will start to fail preemptively. The value
@@ -599,14 +702,20 @@ modparam("tls", "low_mem_threshold1", -1)
      * -1 - use the default value
      * 0 - disable (TLS operations will not fail preemptively)
 
+   It can be changed also at runtime, via the RPC interface and config
+   framework. The config variable name is tls.low_mem_threshold2.
+
    See also low_mem_threshold1.
 
-   Example 20. Set low_mem_threshold2 parameter
+   Example 29. Set low_mem_threshold2 parameter
 ...
 modparam("tls", "low_mem_threshold2", -1)
 ...
 
-1.8.20. tls_force_run (boolean)
+   Example 30. Set tls.low_mem_threshold2 at runtime
+ $ sercmd cfg.set_now_int tls low_mem_threshold2 1024
+
+1.8.24. tls_force_run (boolean)
 
    If enabled SIP-router will start even if some of the openssl sanity
    checks fail (turn it on at your own risk).
@@ -622,12 +731,12 @@ modparam("tls", "low_mem_threshold2", -1)
 
    By default tls_force_run is disabled.
 
-   Example 21. Set tls_force_run parameter
+   Example 31. Set tls_force_run parameter
 ...
 modparam("tls", "tls_force_run", 11)
 ...
 
-1.8.21. config (string)
+1.8.25. config (string)
 
    Sets the name of the TLS specific config file.
 
@@ -653,7 +762,7 @@ modparam("tls", "tls_force_run", 11)
    client when it initiates a new connection by itself (it connects to
    something).
 
-   Example 22. Short config file
+   Example 32. Short config file
 [server:default]
 method = TLSv1
 verify_certificate = no
@@ -679,11 +788,18 @@ ca_list = local_ca.pem
    For a more complete example check the tls.cfg distributed with the
    SIP-router source (sip_router/modules/tls/tls.cfg).
 
-   Example 23. Set config parameter
+   Example 33. Set config parameter
 ...
 modparam("tls", "config", "/usr/local/etc/ser/tls.cfg")
 ...
 
+   It can be changed also at runtime. The new config will not be loaded
+   immediately, but after the first tls.reload RPC call.
+
+   Example 34. Change and reload tls config at runtime
+ $ sercmd cfg.set_now_string tls config "/usr/local/etc/ser/new_tls.cfg"
+ $ sercmd tls.reload
+
 1.9. Functions
 
    Revision History
@@ -695,7 +811,7 @@ modparam("tls", "config", "/usr/local/etc/ser/tls.cfg")
    , the peer presented an X509 certificate and the certificate chain
    verified ok. It can be used only in a request route.
 
-   Example 24. is_peer_verified usage
+   Example 35. is_peer_verified usage
         if (proto==TLS && !is_peer_verified()){
                 sl_send_reply("400", "No certificate or verification failed");
                 drop;
@@ -715,5 +831,9 @@ modparam("tls", "config", "/usr/local/etc/ser/tls.cfg")
    multiple domains, a tls specific config, config reloading and a tls
    specific select framework.
 
+   For ser/sr 3.1 most of the TLS specific code was completely re-written
+   to add support for asynchrounous TLS and fix several long standing
+   bugs.
+
    The code is currently maintained by Andrei Pelinescu-Onciul
    <andrei@iptel.org>.
index 9be05b8..cf42712 100644 (file)
                <para>
                        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.
                </para>
+               <para>
+                       For ser/sr 3.1 most of the TLS specific code was completely
+                       re-written to add support for asynchrounous TLS and fix several
+                       long standing bugs.
+               </para>
                <para>
                        The code is currently maintained by Andrei Pelinescu-Onciul <email>andrei@iptel.org</email>.
                </para>
index a489243..3c3e91e 100644 (file)
@@ -1,8 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
-   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-
-<section id="tm.parameters">
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+               "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+       [<!-- Include general documentation entities -->
+        <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
+        %docentities;
+       ]
+>
+
+<section id="tls.parameters">
     <sectioninfo>
        <revhistory>
            <revision>
@@ -201,35 +206,21 @@ modparam("tls", "cipher_list", "HIGH")
        <section id="send_timeout">
        <title><varname>send_timeout</varname> (int)</title>
        <para>
-               This parameter is obsolete and cannot be used in newer TLS versions
-               (&gt; sip-router 3.0). In these versions the send_timeout is
-               replaced by tcp_send_timeout (common with all the tcp connections).
+               This parameter is <emphasis>obsolete</emphasis> and cannot be used
+               in newer TLS versions (&gt; sip-router 3.0). In these versions the
+               send_timeout is replaced by <varname>tcp_send_timeout</varname>
+               (common with all the tcp connections).
        </para>
-       <example>
-           <title>Set <varname>send_timeout</varname> parameter</title>
-           <programlisting>
-...
-tls_send_timeout = 10
-...
-           </programlisting>
-       </example>
        </section>
 
        <section id="handshake_timeout">
        <title><varname>handshake_timeout</varname> (int)</title>
        <para>
-               This parameter is obsolete and cannot be used in newer TLS versions
-               (&gt; sip-router 3.0). In these versions the handshake_timeout is
-               replaced by tcp_connect_timeout (common with all the tcp connections).
+               This parameter is <emphasis>obsolete</emphasis> and cannot be used
+               in newer TLS versions (&gt; sip-router 3.0). In these versions the
+               handshake_timeout is replaced by <varname>tcp_connect_timeout</varname>
+               (common with all the tcp connections).
        </para>
-       <example>
-           <title>Set <varname>handshake_timeout</varname> parameter</title>
-           <programlisting>
-...
-tcp_connect_timeout = 60
-...
-           </programlisting>
-       </example>
        </section>
 
        <section id="connection_timeout">
@@ -246,6 +237,10 @@ tcp_connect_timeout = 60
        <para>
                If the value set is -1, the connection will never be close on idle.
        </para>
+       <para>
+               It can be changed also at runtime, via the RPC interface and config
+               framework. The config variable name is tls.connection_timeout.
+       </para>
        <example>
            <title>Set <varname>connection_timeout</varname> parameter</title>
            <programlisting>
@@ -254,6 +249,12 @@ modparam("tls", "connection_timeout", 60)
 ...
            </programlisting>
        </example>
+       <example>
+               <title>Set <varname>tls.connection_timeout</varname> at runtime</title>
+               <programlisting>
+ $ &sercmd; cfg.set_now_int tls connection_timeout 180
+               </programlisting>
+       </example>
        </section>
 
        <section id="tls_disable_compression">
@@ -286,14 +287,15 @@ modparam("tls", "tls_disable_compression", 0) # enable
                <varname>ssl_free_list_max_len</varname> has the potential of saving
                a lot of memory ( ~ 32k per connection in the default configuration,
                or 16k + <varname>ssl_max_send_fragment</varname>).
+               For sr versions &gt; 3.0 it makes little sense to disable it (0)
+               since the tls module already has its own internal buffering.
        </para>
        <para>
                A value of -1 would not change this option from its openssl default.
                Use 0 or 1 for enable/disable.
        </para>
        <para>
-               By default the value is -1 (the openssl default, which at least in
-               openssl 1.0.0 is 0/disabled).
+               By default the value is 1 (enabled).
        </para>
        <note>
                <para>
@@ -325,11 +327,11 @@ modparam("tls", "ssl_release_buffers", 1)
        </para>
        <para>
                A value of -1 has a special meaning: the OpenSSL default will be used
-               (no attempt on changing the value will be made).
+               (no attempt on changing the value will be made). For OpenSSL 1.0
+               the internal default is 32.
        </para>
        <para>
-               By default the value is -1 (the OpenSSL default, which at least in
-               OpenSSL 1.0.0 is 32).
+               By default the value is 0 (no freelist).
        </para>
        <note>
                <para>
@@ -401,20 +403,26 @@ modparam("tls", "ssl_max_send_fragment", 4096)
 <section id="ssl_read_ahead">
        <title><varname>ssl_read_ahead</varname> (boolean)</title>
        <para>
-               Enables read ahead, reducing the number of read() system calls
-               done internally by the OpenSSL library.
+               Enables read ahead, reducing the number of internal OpenSSL BIO read()
+               calls. This option has only debugging value, in normal circumstances
+               it should not be changed from the default.
        </para>
        <para>
-               When disabled OpenSSL will make at least 2 read() sytem calls per
+               When disabled OpenSSL will make at least 2 BIO read() calls per
                received record: one to get the record header and one to get the
                rest of the record.
        </para>
+       <para>
+               The TLS module buffers internally all read()s and defines its own fast
+               BIO so enabling this option would only cause more memory consumption
+               and a minor slow-down (extra memcpy).
+       </para>
        <para>
                A value of -1 has a special meaning: the OpenSSL default will be used
                (no attempt on changing the value will be made).
        </para>
        <para>
-               By default the value is 1 (enabled).
+               By default the value is 0 (disabled).
        </para>
        <example>
                <title>Set <varname>ssl_read_ahead</varname> parameter</title>
@@ -425,6 +433,132 @@ modparam("tls", "ssl_read_ahead", 1)
        </section>
 
 
+       <section id="send_close_notify">
+       <title><varname>send_close_notify</varname> (boolean)</title>
+       <para>
+               Enables/disables sending close notify alerts prior to closing the
+               corresponding TCP connection.  Sending the close notify prior to tcp
+               shutdown is "nicer" from a TLS point of view, but it has a measurable
+               performance impact. Default: off. Can be set at runtime
+               (tls.send_close_notify).
+       </para>
+       <para>
+               The default value is 0 (off).
+       </para>
+       <para>
+               It can be changed also at runtime, via the RPC interface and config
+               framework. The config variable name is tls.send_close_notify.
+       </para>
+       <example>
+           <title>Set <varname>send_close_notify</varname> parameter</title>
+           <programlisting>
+...
+modparam("tls", "send_close_notify", 1)
+...
+           </programlisting>
+       </example>
+       <example>
+               <title>Set <varname>tls.send_close_notify</varname> at runtime</title>
+               <programlisting>
+ $ &sercmd; cfg.set_now_int tls send_close_notify 1
+               </programlisting>
+       </example>
+       </section>
+
+
+       <section id="con_ct_wq_max">
+       <title><varname>con_ct_wq_max</varname> (integer)</title>
+       <para>
+               Sets the maximum allowed per connection clear-text send queue size in
+               bytes. This queue is used when data cannot be encrypted and sent
+               immediately because of an ongoing TLS/SSL level renegotiation.
+       </para>
+       <para>
+               The default value is 65536 (64 Kb).
+       </para>
+       <para>
+               It can be changed also at runtime, via the RPC interface and config
+               framework. The config variable name is tls.con_ct_wq_max.
+       </para>
+       <example>
+           <title>Set <varname>con_ct_wq_max</varname> parameter</title>
+           <programlisting>
+...
+modparam("tls", "con_ct_wq_max", 1048576)
+...
+           </programlisting>
+       </example>
+       <example>
+               <title>Set <varname>tls.con_ct_wq_max</varname> at runtime</title>
+               <programlisting>
+ $ &sercmd; cfg.set_now_int tls con_ct_wq_max 1048576
+               </programlisting>
+       </example>
+       </section>
+
+
+       <section id="ct_wq_max">
+       <title><varname>ct_wq_max</varname> (integer)</title>
+       <para>
+               Sets the maximum total number of bytes queued in all the clear-text
+               send queues.  These queues are used when data cannot be encrypted and
+               sent immediately because of an ongoing TLS/SSL level renegotiation.
+       </para>
+       <para>
+               The default value is 10485760 (10 Mb).
+       </para>
+       <para>
+               It can be changed also at runtime, via the RPC interface and config
+               framework. The config variable name is tls.ct_wq_max.
+       </para>
+       <example>
+           <title>Set <varname>ct_wq_max</varname> parameter</title>
+           <programlisting>
+...
+modparam("tls", "ct_wq_max", 4194304)
+...
+           </programlisting>
+       </example>
+       <example>
+               <title>Set <varname>tls.ct_wq_max</varname> at runtime</title>
+               <programlisting>
+ $ &sercmd; cfg.set_now_int tls ct_wq_max 4194304
+               </programlisting>
+       </example>
+       </section>
+
+
+       <section id="ct_wq_blk_size">
+       <title><varname>ct_wq_blk_size</varname> (integer)</title>
+       <para>
+               Minimum block size for the internal clear-text send queues
+               (debugging / advanced tunning).
+               Good values are multiple of typical datagram sizes.
+       </para>
+       <para>
+               The default value is 4096.
+       </para>
+       <para>
+               It can be changed also at runtime, via the RPC interface and config
+               framework. The config variable name is tls.ct_wq_blk_size.
+       </para>
+       <example>
+           <title>Set <varname>ct_wq_blk_size</varname> parameter</title>
+           <programlisting>
+...
+modparam("tls", "ct_wq_blk_size", 2048)
+...
+           </programlisting>
+       </example>
+       <example>
+               <title>Set <varname>tls.ct_wq_max</varname> at runtime</title>
+               <programlisting>
+ $ &sercmd; cfg.set_now_int tls ct_wq_blk_size 2048
+               </programlisting>
+       </example>
+       </section>
+
+
        <section id="tls_log">
        <title><varname>tls_log</varname> (int)</title>
        <para>
@@ -433,6 +567,10 @@ modparam("tls", "ssl_read_ahead", 1)
        <para>
                The default value is 3.
        </para>
+       <para>
+               It can be changed also at runtime, via the RPC interface and config
+               framework. The config variable name is tls.log.
+       </para>
        <example>
                <title>Set <varname>tls_log</varname> parameter</title>
                <programlisting>
@@ -442,13 +580,20 @@ modparam("tls", "tls_log", 10)
 ...
                </programlisting>
        </example>
+       <example>
+               <title>Set <varname>tls.log</varname> at runtime</title>
+               <programlisting>
+ $ &sercmd; cfg.set_now_int tls log 10
+               </programlisting>
+       </example>
        </section>
 
 
 <section id="low_mem_threshold1">
        <title><varname>low_mem_threshold1</varname> (integer)</title>
        <para>
-               Sets the minimal free memory from which new TLS connection will start to fail. The value is expressed in KB.
+               Sets the minimal free memory from which attempts to open or accept
+               new TLS connections will start to fail. The value is expressed in KB.
        </para>
        <para>
                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)
                                </para>
                        </listitem>
        </itemizedlist>
+       <para>
+               It can be changed also at runtime, via the RPC interface and config
+               framework. The config variable name is tls.low_mem_threshold1.
+       </para>
        <para>
                See also <varname>low_mem_threshold2</varname>.
        </para>
@@ -482,6 +631,12 @@ modparam("tls", "low_mem_threshold1", -1)
 ...
        </programlisting>
        </example>
+       <example>
+               <title>Set <varname>tls.low_mem_threshold1</varname> at runtime</title>
+               <programlisting>
+ $ &sercmd; cfg.set_now_int tls low_mem_threshold1 2048
+               </programlisting>
+       </example>
        </section>
 
 <section id="low_mem_threshold2">
@@ -510,6 +665,10 @@ modparam("tls", "low_mem_threshold1", -1)
                                </para>
                        </listitem>
        </itemizedlist>
+       <para>
+               It can be changed also at runtime, via the RPC interface and config
+               framework. The config variable name is tls.low_mem_threshold2.
+       </para>
        <para>
                See also <varname>low_mem_threshold1</varname>.
        </para>
@@ -521,6 +680,12 @@ modparam("tls", "low_mem_threshold2", -1)
 ...
        </programlisting>
        </example>
+       <example>
+               <title>Set <varname>tls.low_mem_threshold2</varname> at runtime</title>
+               <programlisting>
+ $ &sercmd; cfg.set_now_int tls low_mem_threshold2 1024
+               </programlisting>
+       </example>
        </section>
 
        <section id="tls_force_run">
@@ -621,6 +786,17 @@ modparam("tls", "config", "/usr/local/etc/ser/tls.cfg")
 ...
        </programlisting>
        </example>
+       <para>
+               It can be changed also at runtime. The new config will not be loaded
+               immediately, but after the first tls.reload RPC call.
+               <example>
+                       <title>Change and reload tls config at runtime</title>
+                       <programlisting>
+ $ &sercmd; cfg.set_now_string tls config "/usr/local/etc/ser/new_tls.cfg"
+ $ &sercmd; tls.reload
+                       </programlisting>
+               </example>
+       </para>
        </section>
 
 </section>
index f59f381..e21e985 100644 (file)
@@ -2,7 +2,7 @@
 <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
        [ <!ENTITY % local.common.attrib
-        "xmlns:xi CDATA #FIXED 'http://www.w3.org/2001/XInclude'">]
+        "xmlns:xi CDATA #FIXED 'http://www.w3.org/2001/XInclude'"> ]
 >
 
 <section id="tls" xmlns:xi="http://www.w3.org/2001/XInclude">
@@ -34,7 +34,7 @@
                <section id="tls.overview">
                <title>Overview</title>
                <para>
-                       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 
+                       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 
                </para>
                </section>
                <section id="tls.quick_start">
@@ -76,7 +76,9 @@ route{
                        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.
                </para>
                <para>
-                       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.
+                       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.
+                       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)
+ (see <varname>tls_disable_compression</varname>).
                </para>
                <para>
                        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{
                <para>
                        In most case compiling the TLS module is as simple as:
                        <programlisting>
-make modules modules=modules/tls
+make -C modules/tls
                        </programlisting>
                        or
                        <programlisting>
-cd modules/tls
-make
+make modules modules=modules/tls
                        </programlisting>
                        or (compiling whole SIP-router and the tls module)
                        <programlisting>
@@ -133,7 +134,15 @@ make TLS_EXTRA_LIBS="-lkrb5 -lz" all include_modules=tls
                        TLS specific config reloading is not safe, so for now better don't use it, especially under heavy traffic.
                </para>
                <para>
-                       This documentation is incomplete. The select framework and rpc sections are completely missing.
+                       This documentation is incomplete.
+                       The RPCs are not documented here, but in doc/rpc_list/rpc_tls.txt
+                       or <ulink url="http://sip-router.org/docbook/sip-router/branch/master/rpc_list/rpc_list.html#rpc_exports.tls">
+                       http://sip-router.org/docbook/sip-router/branch/master/rpc_list/rpc_list.html#rpc_exports.tls</ulink>.
+                       The provided selects are not documented. A list with all the
+                       ones implemented by the tls module can be seen under
+                       doc/select_list/select_tls.txt or
+                       or <ulink url="http://sip-router.org/docbook/sip-router/branch/master/select_list/select_list.html#select_list.tls">
+                       http://sip-router.org/docbook/sip-router/branch/master/select_list/select_list.html#select_list.tls</ulink>.
                </para>
                </section>