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

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

@@ -16,6 +16,11 @@

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

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

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

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

@@ -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'"> ]

 >