tls minor updates to documentation

docbook/entities.xml

@@ -9,6 +9,7 @@
 <!ENTITY kamailiobinary "kamailio">
 <!ENTITY kamailioname "Kamailio SIP Server Platform">
 <!ENTITY kamailioconfig "kamailio.cfg">
+<!ENTITY kamailioconfdir "/usr/local/etc/kamailio">
 
 <!ENTITY kamwiki "http://www.kamailio.org/wiki/">
 <!ENTITY kamwikilink "<ulink url='&kamwiki;'>&kamwiki;</ulink>">

modules/tls/README

@@ -119,7 +119,7 @@ Carsten Bock
    1.39. Set renegotiation parameter
    1.40. Short config file
    1.41. Set config parameter
-   1.42. Change and reload tls config at runtime
+   1.42. Change and reload the tls configuration at runtime
    1.43. Set xavp_cfg parameter
    1.44. is_peer_verified usage
 
@@ -230,20 +230,20 @@ route{
    This module includes several workarounds for various Openssl bugs (like
    compression and Kerberos using the wrong memory allocations functions,
    low memory problems a.s.o). On startup it will try to enable the needed
-   workarounds based on the Openssl library version. Each time a known
+   workarounds based on the OpenSSL library version. Each time a known
    problem is detected and a workaround is enabled, a message will be
    logged. In general it is recommended to compile this module on the same
    machine or a similar machine to where kamailio will be run or to link
    it statically with libssl. For example if on the compile machine
-   Openssl does not have the Kerberos support enabled, but on the target
-   machine a Kerberos enabled Openssl library is installed, Kamailio
+   OpenSSL does not have the Kerberos support enabled, but on the target
+   machine a Kerberos enabled OpenSSL library is installed, Kamailio
    cannot apply the needed workarounds and will refuse to start. The same
-   thing will happen if the Openssl versions are too different (to force
+   thing will happen if the OpenSSL versions are too different (to force
    Kamailio startup anyway, see the tls_force_run module parameter).
 
-   Compression is fully supported if you have a new enough Openssl version
+   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
+   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
    Kamailio 3.1 compression is not enabled by default, due to the huge
@@ -276,8 +276,8 @@ make all include_modules=tls
 
    .
 
-   However in some cases the Openssl library requires linking with other
-   libraries. For example compiling the Openssl library with Kerberos and
+   However in some cases the OpenSSL library requires linking with other
+   libraries. For example compiling the OpenSSL library with Kerberos and
    zlib-shared support will require linking the TLS module with libkrb5
    and libz. In this case just add TLS_EXTRA_LIBS="library list" to make's
    command line. E.g.:
@@ -342,17 +342,16 @@ make -C modules/tls extra_defs="-DTLS_WR_DEBUG -DTLS_RD_DEBUG"
 8. Quick Certificate Howto
 
    There are various ways to create, sign certificates and manage small
-   CAs (Certificate Authorities). If you want a GUI, try tinyca
-   (http://tinyca.sm-zone.net/), a very nice and small CA management
-   application. If you are in a hurry and everything you have are the
-   installed openssl libraries and utilities, read on.
+   CAs (Certificate Authorities). If you are in a hurry and everything you
+   have are the installed OpenSSL libraries and utilities, read on.
 
    Assumptions: we run our own CA.
 
    Warning: in this example no key is encrypted. The client and server
    private keys must not be encrypted (Kamailio doesn't support encrypted
    keys), so make sure the corresponding files are readable only by
-   trusted people. You should use a password for your CA private key.
+   trusted people. You should use a password to protect your CA private
+   key.
 
 Assumptions
 ------------
@@ -377,83 +376,90 @@ new_certs_dir   = $dir/newcerts         # default place for new certs.
 
 certificate     = $dir/cacert.pem       # The CA certificate
 serial          = $dir/serial           # The current serial number
-crlnumber       = $dir/crlnumber        # the current crl number
+crlnumber       = $dir/crlnumber        # the current CRL number
 crl             = $dir/crl.pem          # The current CRL
 private_key     = $dir/private/cakey.pem# The private key
 RANDFILE        = $dir/private/.rand    # private random number file
 
 ...
 
-If this is not the case create a new openssl config file that uses the above
+If this is not the case create a new OpenSSL config file that uses the above
 paths for the default CA and add to all the openssl commands:
  -config filename. E.g.:
         openssl ca -config my_openssl.cnf -in kamailio1_cert_req.pem -out kamail
 io1_cert.pem
 
 
-Creating CA certificate
------------------------
-1. create CA directory
+Creating the CA certificate
+---------------------------
+1. Create the CA directory
         mkdir ca
         cd ca
 
-2. create ca directory structure and files  (see ca(1))
-        mkdir demoCA #default CA name, edit /etc/ssl/openssl.cnf
+2. Create the CA directory structure and files  (see ca(1))
+        mkdir demoCA            #default CA name, edit /etc/ssl/openssl.cnf
         mkdir  demoCA/private
         mkdir demoCA/newcerts
         touch demoCA/index.txt
         echo 01 >demoCA/serial
         echo 01 >demoCA/crlnumber
 
-2. create CA private key
+2. Create CA private key
         openssl genrsa -out demoCA/private/cakey.pem 2048
         chmod 600 demoCA/private/cakey.pem
 
-3. create CA self-signed certificate
+3. Create CA self-signed certificate
         openssl req -out demoCA/cacert.pem   -x509 -new -key demoCA/private/cake
 y.pem
 
 
-Creating a server/client certificate
-------------------------------------
-1. create a certificate request (and its private key in privkey.pem)
+Creating a server/client TLS certificate
+----------------------------------------
+1. Create a certificate request (and its private key in privkey.pem)
+
         openssl req -out kamailio1_cert_req.pem -new -nodes
+
         WARNING: the organization name should be the same as in the CA certifica
 te.
 
-2. sign it with the ca certificate
+2. Sign it with the CA certificate
         openssl ca -in kamailio1_cert_req.pem -out kamailio1_cert.pem
 
-3. copy kamailio1_cert.pem to your Kamailio config. dir
+3. Copy kamailio1_cert.pem to your Kamailio configuration dir
 
 
-Setting Kamailio to use the certificate
------------------------------------------
-1. Create the ca list file:
-        for each of your ca certificates that you intend to use do:
+Setting Kamailio to use the TLS certificate
+---------------------------------------------
+1. Create the CA list file:
+        for each of your CA certificates that you intend to use do:
                 cat cacert.pem >>calist.pem
 
 2. Copy your Kamailio certificate, private key and ca list file to your
         intended machine (preferably in your Kamailio configuration directory,
          this is the default place Kamailio searches for).
 
-3. set up Kamailio.cfg to use the certificate
+3. Set up Kamailio.cfg to use the certificate
         if your Kamailio certificate name is different from cert.pem or it is no
 t
         placed in Kamailio cfg. directory, add to your kamailio.cfg:
                 modparam("tls", "certificate", "/path/cert_file_name")
 
-4. set up Kamailio to use the private key
+4. Set up Kamailio to use the private key
         if your private key is not contained in the same file as the certificate
         (or the certificate name is not the default cert.pem), add to your
          Kamailio.cfg:
                 modparam("tls", "private_key", "/path/private_key_file")
 
-5. set up Kamailio to use the ca list (optional)
+5. Set up Kamailio to use the CA list (optional)
+   The CA list is not used for your server certificate - it's used to approve ot
+her servers
+   and clients connecting to your server with a client certificate or for approv
+ing
+   a certificate used by a server your server connects to.
         add to your Kamailio.cfg:
                 modparam("tls", "ca_list", "/path/ca_list_file")
 
-6. set up tls authentication options:
+6. Set up TLS authentication options:
                 modparam("tls", "verify_certificate", 1)
                 modparam("tls", "require_certificate", 1)
         (for more information see the module parameters documentation)
@@ -461,15 +467,15 @@ t
 
 Revoking a certificate and using a CRL
 --------------------------------------
-1. revoking a certificate:
+1. Revoking a certificate:
         openssl ca -revoke bad_cert.pem
 
-2. generate/update the certificate revocation list:
+2. Generate/update the certificate revocation list:
         openssl ca -gencrl -out my_crl.pem
 
-3. copy my_crl.pem to your Kamailio config. dir
+3. Copy my_crl.pem to your Kamailio config. dir
 
-4. set up Kamailio to use the CRL:
+4. Set up Kamailio to use the CRL:
                 modparam("tls", "crl", "path/my_crl.pem")
 
 9. Parameters
@@ -527,8 +533,8 @@ Revoking a certificate and using a CRL
        Newer versions of libssl don't include support for it anymore.
      * SSLv23 - any of the SSLv2, SSLv3 and TLSv1 or newer methods will be
        accepted.
-       From OpenSSL manual: "A TLS/SSL connection established with these
-       methods may understand the SSLv3, TLSv1, TLSv1.1 and TLSv1.2
+       From the OpenSSL manual: "A TLS/SSL connection established with
+       these methods may understand the SSLv3, TLSv1, TLSv1.1 and TLSv1.2
        protocols. If extensions are required (for example server name) a
        client will send out TLSv1 client hello messages including
        extensions and will indicate that it also understands TLSv1.1,
@@ -539,7 +545,7 @@ Revoking a certificate and using a CRL
        hello messages done over SSLv2. You shouldn't use SSLv2 or SSLv3
        for anything which should be highly secure.
 
-   If rfc3261 conformance is desired, at least TLSv1 must be used. For
+   If RFC 3261 conformance is desired, at least TLSv1 must be used. For
    compatibility with older clients SSLv23 is the option, but again, be
    aware of security concerns, SSLv2/3 being considered very insecure by
    2014.
@@ -560,11 +566,11 @@ modparam("tls", "tls_method", "TLSv1")
    relative to the main config file directory (e.g.: for kamailio -f
    /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).
 
-   Warning: try not to use certificate with keys longer then 1024 bytes.
+   Warning: try not to use certificate with keys longer then 2048 bytes.
    Longer keys will severely impact performance, in particular the TLS
    connection rate.
 
-   The default value is [SER_CFG_DIR]/cert.pem.
+   The default value is /usr/local/etc/kamailio/cert.pem
 
    Example 1.4. Set certificate parameter
 ...
@@ -573,7 +579,9 @@ modparam("tls", "certificate", "/usr/local/etc/kamailio/my_certificate.pem")
 
 9.3. private_key (string)
 
-   Sets the private key file name.
+   Sets the private key file name. The private key can be in the same file
+   as the certificate or in a separate file, specified by this
+   configuration parameter.
 
    If the file name starts with a '.' the path will be relative to the
    working directory (at runtime). If it starts with a '/' it will be an
@@ -585,7 +593,7 @@ modparam("tls", "certificate", "/usr/local/etc/kamailio/my_certificate.pem")
    certificate (just append it to the certificate file, e.g.: cat pkey.pem
    >> cert.pem)
 
-   The default value is [SER_CFG_DIR]/cert.pem.
+   The default value is /usr/local/etc/kamailio/cert.pem
 
    Example 1.5. Set private_key parameter
 ...
@@ -596,7 +604,8 @@ modparam("tls", "private", "/usr/local/etc/kamailio/my_pkey.pem")
 
    Sets the CA list file name. This file contains a list of all the
    trusted CAs certificates. If a signature in a certificate chain belongs
-   to one of the listed CAs, the authentication will succeed.
+   to one of the listed CAs, the verification of that certificate will
+   succeed.
 
    If the file name starts with a '.' the path will be relative to the
    working directory (at runtime). If it starts with a '/' it will be an
@@ -619,11 +628,11 @@ modparam("tls", "ca_list", "/usr/local/etc/kamailio/ca_list.pem")
 
 9.5. crl (string)
 
-   Sets the certificate revocation list file name. This file contains a
-   list of revoked certificates. Any attempt to verify a revoked
-   certificate will fail.
+   Sets the certificate revocation list (CRL) file name. This file
+   contains a list of revoked certificates. Any attempt to verify a
+   revoked certificate will fail.
 
-   If not set, no crl list will be used.
+   If not set, no CRL list will be used.
 
    If the file name starts with a '.' the path will be relative to the
    working directory (at runtime). If it starts with a '/' it will be an
@@ -636,19 +645,19 @@ Note
    If set, require_certificate should also be set or it will not have any
    effect.
 
-   By default the crl file is not set.
+   By default the CRL file name is not set.
 
-   To update the crl in a running Kamailio, make sure you configure tls
-   via a separate tls config file (the config modparam) and issue a
+   To update the CRL in a running Kamailio, make sure you configure TLS
+   via a separate TLS config file (the config modparam) and issue a
    tls.reload RPC call, e.g.:
  $ kamcmd tls.reload
 
-   A quick way to create the CRL in PEM format, using openssl is:
+   A quick way to create the CRL in PEM format, using OpenSSL is:
  $ openssl ca -gencrl -keyfile cacert.key -cert cacert.pem -out my_crl.pem
 
    my_crl.pem will contain the signed list of the revoked certificates.
 
-   To revoke a certificate use something like:
+   To revoke a TLS certificate use something like:
  $ openssl ca -revoke bad_cert.pem -keyfile cacert.key -cert cacert.pem
 
    and then refresh the crl file using the command above.
@@ -698,8 +707,8 @@ modparam("tls", "verify_depth", 9)
 9.8. require_certificate (boolean)
 
    When enabled it will require a certificate from a client. If the client
-   does not offer a certificate and verify_certificate is on, the
-   certificate verification will fail.
+   does not offer a certificate and verify_certificate is on, certificate
+   verification will fail.
 
    The default value is off.
 
@@ -759,8 +768,8 @@ modparam("tls", "server_name", "kamailio.org")
 
    If the value set is -1, the connection will never be close on idle.
 
-   It can be changed also at runtime, via the RPC interface and config
-   framework. The config variable name is tls.connection_timeout.
+   This setting can be changed also at runtime, via the RPC interface and
+   config framework. The config variable name is tls.connection_timeout.
 
    Example 1.13. Set connection_timeout parameter
 ...
@@ -772,7 +781,7 @@ modparam("tls", "connection_timeout", 60)
 
 9.14. tls_disable_compression (boolean)
 
-   If set compression over SSL/TLS will be disabled. Note that compression
+   If set compression over TLS will be disabled. Note that compression
    uses a lot of memory (about 10x more then with the compression
    disabled), so if you want to minimize memory usage is a good idea to
    disable it.
@@ -789,9 +798,9 @@ 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). For sr versions > 3.0
-   it makes little sense to disable it (0) since the tls module already
-   has its own internal buffering.
+   configuration, or 16k + ssl_max_send_fragment). For Kamailio 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.
@@ -889,7 +898,7 @@ modparam("tls", "ssl_read_ahead", 1)
 9.19. send_close_notify (boolean)
 
    Enables/disables sending close notify alerts prior to closing the
-   corresponding TCP connection. Sending the close notify prior to tcp
+   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).
@@ -930,7 +939,7 @@ modparam("tls", "con_ct_wq_max", 1048576)
 
    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.
+   sent immediately because of an ongoing TLS level renegotiation.
 
    The default value is 10485760 (10 Mb).
 
@@ -1011,7 +1020,7 @@ modparam("tls", "tls_debug", 10)
    well low memory situations (openssl bug #1491). As of this writing this
    is not true for any openssl version (including 0.9.8e).
 
-   If an ill-behaved openssl version is detected, a very conservative
+   If an ill-behaved OpenSSL version is detected, a very conservative
    value is choosed, which depends on the maximum possible number of
    simultaneously created TLS connections (and hence on the process
    number).
@@ -1039,9 +1048,9 @@ modparam("tls", "low_mem_threshold1", -1)
    established TLS connections will start to fail preemptively. The value
    is expressed in KB.
 
-   The default value depends on whether the openssl library used handles
+   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).
+   is not true for any OpenSSL version (including 0.9.8e).
 
    If an ill-behaved openssl version is detected, a very conservative
    value is choosed, which depends on the maximum possible number of
@@ -1067,7 +1076,7 @@ modparam("tls", "low_mem_threshold2", -1)
 
 9.27. tls_force_run (boolean)
 
-   If enabled Kamailio will start even if some of the openssl sanity
+   If enabled Kamailio will start even if some of the OpenSSL sanity
    checks fail (turn it on at your own risk).
 
    Currently failing any of the following sanity checks will not allow
@@ -1076,8 +1085,8 @@ modparam("tls", "low_mem_threshold2", -1)
        different" from the library used at runtime. The versions should
        have the same major, minor and fix level (e.g.: 0.9.8a and 0.9.8c
        are ok, but 0.9.8 and 0.9.9 are not)
-     * the openssl library used at compile time and the one used at
-       runtime have different kerberos options
+     * the OpenSSL library used at compile time and the one used at
+       runtime have different Kerberos options
 
    By default tls_force_run is disabled.
 
@@ -1126,12 +1135,14 @@ modparam("tls", "renegotiation", 1)
 
 9.31. config (string)
 
-   Sets the name of the TLS specific config file or config directory.
+   Sets the name of the TLS specific configuration file or configuration
+   directory.
 
-   If set the TLS module will load a special config file or config files
-   from config directory, in which different TLS parameters can be
-   specified on a per role (server or client) and domain basis (for now
-   only IPs). The corresponding module parameters will be ignored.
+   If set the TLS module will load a special configuration file or
+   configuration files from configuration directory, in which different
+   TLS parameters can be specified on a per role (server or client) and
+   domain basis (for now only IPs). The corresponding module parameters
+   will be ignored if a separate configuraiton file is used.
 
    If the file or directory name starts with a '.' the path will be
    relative to the working directory (at runtime). If it starts with a '/'
@@ -1198,16 +1209,16 @@ server_name = kamailio.org
 modparam("tls", "config", "/usr/local/etc/kamailio/tls.cfg")
 ...
 
-   It can be changed also at runtime. The new config will not be loaded
+   The file can be changed at runtime. The new config will not be loaded
    immediately, but after the first tls.reload RPC call.
 
-   Example 1.42. Change and reload tls config at runtime
+   Example 1.42. Change and reload the tls configuration at runtime
  $ kamcmd cfg.set_now_string tls config "/usr/local/etc/kamailio/new_tls.cfg"
  $ kamcmd tls.reload
 
 9.32. xavp_cfg (string)
 
-   Sets the name of XAVP that stored attributes for TLS connections.
+   Sets the name of XAVP that stores attributes for TLS connections.
 
    The following (inner) attributes can be set:
      * server_name - SNI to be used for outbound connections

modules/tls/doc/certs_howto.xml

@@ -14,14 +14,16 @@
 
 	<title>Quick Certificate Howto</title>
 		<para>
-			There are various ways to create, sign certificates and manage small CAs (Certificate Authorities). If you want a GUI, try <ulink url="http://tinyca.sm-zone.net/">tinyca (http://tinyca.sm-zone.net/)</ulink>, a very nice and small CA management application. If you are in a hurry and everything you have are the installed openssl libraries and utilities, read on.
+			There are various ways to create, sign certificates and manage small CAs (Certificate Authorities).
+			If you are in a hurry and everything you have are the installed OpenSSL libraries and utilities, read on.
 		</para>
 		<para>
 			Assumptions: we run our own CA.
 		</para>
 		<para>
-			Warning: in this example no key is encrypted. The client and server private keys must not be encrypted (&kamailio; doesn't support encrypted keys),
-			so make sure the corresponding files are readable only by trusted people. You should use a password for your CA private key.
+			Warning: in this example no key is encrypted. The client and server private keys must not be encrypted
+			(&kamailio; doesn't support encrypted keys), so make sure the corresponding files are readable only by
+			trusted people. You should use a password to protect your CA private key.
 		</para>
 		<para>
 		<programlisting>
@@ -48,79 +50,84 @@ new_certs_dir   = $dir/newcerts         # default place for new certs.
 
 certificate     = $dir/cacert.pem       # The CA certificate
 serial          = $dir/serial           # The current serial number
-crlnumber       = $dir/crlnumber        # the current crl number
+crlnumber       = $dir/crlnumber        # the current CRL number
 crl             = $dir/crl.pem          # The current CRL
 private_key     = $dir/private/cakey.pem# The private key
 RANDFILE        = $dir/private/.rand    # private random number file
 
 ...
 
-If this is not the case create a new openssl config file that uses the above
+If this is not the case create a new OpenSSL config file that uses the above
 paths for the default CA and add to all the openssl commands:
  -config filename. E.g.:
 	openssl ca -config my_openssl.cnf -in kamailio1_cert_req.pem -out kamailio1_cert.pem
 
 
-Creating CA certificate
------------------------
-1. create CA directory
+Creating the CA certificate
+---------------------------
+1. Create the CA directory
 	mkdir ca
 	cd ca
 	
-2. create ca directory structure and files  (see ca(1))
-	mkdir demoCA #default CA name, edit /etc/ssl/openssl.cnf
+2. Create the CA directory structure and files  (see ca(1))
+	mkdir demoCA 		#default CA name, edit /etc/ssl/openssl.cnf
 	mkdir  demoCA/private
 	mkdir demoCA/newcerts
 	touch demoCA/index.txt
 	echo 01 >demoCA/serial
 	echo 01 >demoCA/crlnumber
 	
-2. create CA private key
+2. Create CA private key
 	openssl genrsa -out demoCA/private/cakey.pem 2048
 	chmod 600 demoCA/private/cakey.pem
 	
-3. create CA self-signed certificate
+3. Create CA self-signed certificate
 	openssl req -out demoCA/cacert.pem   -x509 -new -key demoCA/private/cakey.pem
 
 
-Creating a server/client certificate
-------------------------------------
-1. create a certificate request (and its private key in privkey.pem)
+Creating a server/client TLS certificate
+----------------------------------------
+1. Create a certificate request (and its private key in privkey.pem)
+
 	openssl req -out kamailio1_cert_req.pem -new -nodes
+
 	WARNING: the organization name should be the same as in the CA certificate.
 	
-2. sign it with the ca certificate
+2. Sign it with the CA certificate
 	openssl ca -in kamailio1_cert_req.pem -out kamailio1_cert.pem
 	
-3. copy kamailio1_cert.pem to your &kamailio; config. dir
+3. Copy kamailio1_cert.pem to your &kamailio; configuration dir
 
 
-Setting &kamailio; to use the certificate
------------------------------------------
-1. Create the ca list file:
-	for each of your ca certificates that you intend to use do:
+Setting &kamailio; to use the TLS certificate
+---------------------------------------------
+1. Create the CA list file:
+	for each of your CA certificates that you intend to use do:
 		cat cacert.pem >>calist.pem
 	
 2. Copy your &kamailio; certificate, private key and ca list file to your 
 	intended machine (preferably in your &kamailio; configuration directory,
 	 this is the default place &kamailio; searches for).
 	
-3. set up &kamailio;.cfg to use the certificate
+3. Set up &kamailio;.cfg to use the certificate
 	if your &kamailio; certificate name is different from cert.pem or it is not
 	placed in &kamailio; cfg. directory, add to your kamailio.cfg:
 		modparam("tls", "certificate", "/path/cert_file_name")
 	
-4. set up &kamailio; to use the private key
+4. Set up &kamailio; to use the private key
 	if your private key is not contained in the same file as the certificate
 	(or the certificate name is not the default cert.pem), add to your
 	 &kamailio;.cfg:
 		modparam("tls", "private_key", "/path/private_key_file")
 	
-5. set up &kamailio; to use the ca list (optional)
+5. Set up &kamailio; to use the CA list (optional)
+   The CA list is not used for your server certificate - it's used to approve other servers
+   and clients connecting to your server with a client certificate or for approving
+   a certificate used by a server your server connects to.
 	add to your &kamailio;.cfg:
 		modparam("tls", "ca_list", "/path/ca_list_file")
 	
-6. set up tls authentication options:
+6. Set up TLS authentication options:
 		modparam("tls", "verify_certificate", 1)
 		modparam("tls", "require_certificate", 1) 
 	(for more information see the module parameters documentation)
@@ -128,15 +135,15 @@ Setting &kamailio; to use the certificate
 
 Revoking a certificate and using a CRL
 --------------------------------------
-1. revoking a certificate:
+1. Revoking a certificate:
 	openssl ca -revoke bad_cert.pem
 	
-2. generate/update the certificate revocation list:
+2. Generate/update the certificate revocation list:
 	openssl ca -gencrl -out my_crl.pem
 	
-3. copy my_crl.pem to your &kamailio; config. dir
+3. Copy my_crl.pem to your &kamailio; config. dir
 	
-4. set up &kamailio; to use the CRL:
+4. Set up &kamailio; to use the CRL:
 		modparam("tls", "crl", "path/my_crl.pem")
 
 

modules/tls/doc/params.xml

@@ -68,7 +68,7 @@
 				newer methods will be accepted.
 				</para>
 				<para>
-				From OpenSSL manual: "A TLS/SSL connection established with these
+				From the OpenSSL manual: "A TLS/SSL connection established with these
 				methods may understand the SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols.
 				If extensions are required (for example server name) a client will
 				send out TLSv1 client hello messages including extensions and will
@@ -85,7 +85,7 @@
 			</listitem>
 	</itemizedlist>
 	<para>
-		If rfc3261 conformance is desired, at least TLSv1 must be used. For
+		If RFC 3261 conformance is desired, at least TLSv1 must be used. For
 		compatibility with older clients SSLv23 is the option, but again, be aware
 		of security concerns, SSLv2/3 being considered very insecure by 2014.
 	</para>
@@ -114,11 +114,11 @@ modparam("tls", "tls_method", "TLSv1")
 	</para>
 	<para>
 		<emphasis>Warning:</emphasis> try not to use certificate with keys
-		longer then 1024 bytes. Longer keys will severely impact performance,
+		longer then 2048 bytes. Longer keys will severely impact performance,
 		in particular the TLS connection rate.
 	</para>
 	<para>
-		The default value is [SER_CFG_DIR]/cert.pem.
+		The default value is &kamailioconfdir;/cert.pem
 	</para>
 	<example>
 	    <title>Set <varname>certificate</varname> parameter</title>
@@ -133,7 +133,9 @@ modparam("tls", "certificate", "/usr/local/etc/kamailio/my_certificate.pem")
 	<section id="tls.p.private_key">
 	<title><varname>private_key</varname> (string)</title>
 	<para>
-		Sets the private key file name.
+		Sets the private key file name. The private key can be in the same
+		file as the certificate or in a separate file, specified by this
+		configuration parameter.
 	</para>
 	<para>
 		If the file name starts with a '.' the path will be relative to the
@@ -148,7 +150,7 @@ modparam("tls", "certificate", "/usr/local/etc/kamailio/my_certificate.pem")
 		cat pkey.pem &gt;&gt; cert.pem)
 	</para>
 	<para>
-		The default value is [SER_CFG_DIR]/cert.pem.
+		The default value is &kamailioconfdir;/cert.pem
 	</para>
 	<example>
 	    <title>Set <varname>private_key</varname> parameter</title>
@@ -165,7 +167,7 @@ modparam("tls", "private", "/usr/local/etc/kamailio/my_pkey.pem")
 	<para>
 		Sets the CA list file name. This file contains a list of all the
 		trusted CAs certificates. If a signature in a certificate chain belongs
-		to one of the listed CAs, the authentication will succeed.
+		to one of the listed CAs, the verification of that certificate will succeed.
 	</para>
 	<para>
 		If the file name starts with a '.' the path will be relative to the
@@ -202,12 +204,12 @@ modparam("tls", "ca_list", "/usr/local/etc/kamailio/ca_list.pem")
 	<section id="tls.p.crl">
 	<title><varname>crl</varname> (string)</title>
 	<para>
-		Sets the certificate revocation list file name. This file contains a
+		Sets the certificate revocation list (CRL) file name. This file contains a
 		list of revoked certificates. Any attempt to verify a revoked
 		certificate will fail.
 	</para>
 	<para>
-		If not set, no crl list will be used.
+		If not set, no CRL list will be used.
 	</para>
 	<para>
 		If the file name starts with a '.' the path will be relative to the
@@ -221,11 +223,11 @@ modparam("tls", "ca_list", "/usr/local/etc/kamailio/ca_list.pem")
 		or it will not have any effect.
 	</para></note>
 	<para>
-		By default the crl file is not set.
+		By default the CRL file name is not set.
 	</para>
 	<para>
-		To update the crl in a running &kamailio;, make sure you configure tls
-		via a separate tls config file
+		To update the CRL in a running &kamailio;, make sure you configure TLS
+		via a separate TLS config file
 		(the <varname>config</varname> modparam) and issue a tls.reload
 		RPC call, e.g.:
 		<programlisting>
@@ -233,14 +235,14 @@ modparam("tls", "ca_list", "/usr/local/etc/kamailio/ca_list.pem")
 		</programlisting>
 	</para>
 	<para>
-		A quick way to create the CRL in PEM format, using openssl is:
+		A quick way to create the CRL in PEM format, using OpenSSL is:
 		<programlisting>
  $ openssl ca -gencrl -keyfile cacert.key -cert cacert.pem -out my_crl.pem
 		</programlisting>
 		 my_crl.pem will contain the signed list of the revoked certificates.
 	</para>
 	<para>
-		To revoke a certificate use something like:
+		To revoke a TLS certificate use something like:
 		<programlisting>
  $ openssl ca -revoke bad_cert.pem -keyfile cacert.key -cert cacert.pem
 		</programlisting>
@@ -272,7 +274,8 @@ modparam("tls", "crl", "/usr/local/etc/kamailio/crl.pem")
 <section id="tls.p.verify_certificate">
 	<title><varname>verify_certificate</varname> (boolean)</title>
 	<para>
-		If enabled it will force certificate verification. For more information see the <ulink url="http://www.openssl.org/docs/apps/verify.html">verify(1)</ulink> openssl man page.
+		If enabled it will force certificate verification.
+		For more information see the <ulink url="http://www.openssl.org/docs/apps/verify.html">verify(1)</ulink> openssl man page.
 	</para>
 	<para>
 		Note: the certificate verification will always fail if the ca_list is empty.
@@ -317,7 +320,8 @@ modparam("tls", "verify_depth", 9)
 <section id="tls.p.require_certificate">
 	<title><varname>require_certificate</varname> (boolean)</title>
 	<para>
-		When enabled it will require a certificate from a client. If the client does not offer a certificate and <varname>verify_certificate</varname> is on, the certificate verification will fail.
+		When enabled it will require a certificate from a client. If the client does not offer a certificate
+		and <varname>verify_certificate</varname> is on, certificate verification will fail.
 	</para>
 	<para>
 		The default value is off.
@@ -335,7 +339,9 @@ modparam("tls", "require_certificate", 1)
 <section id="tls.p.cipher_list">
 	<title><varname>cipher_list</varname> (string)</title>
 	<para>
-		Sets the list of accepted ciphers. The list consists of cipher strings separated by colons. For more information on the cipher list format see the <ulink url="http://www.openssl.org/docs/apps/ciphers.html">cipher(1)</ulink> openssl man page.
+		Sets the list of accepted ciphers. The list consists of cipher strings separated by colons.
+		For more information on the cipher list format see the
+		<ulink url="https://www.openssl.org/docs/manmaster/apps/ciphers.html">cipher(1)</ulink> openssl man page.
 	</para>
 	<para>
 		The default value is not set (all the Openssl supported ciphers are enabled).
@@ -407,7 +413,7 @@ modparam("tls", "server_name", "kamailio.org")
 		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
+		This setting can be changed also at runtime, via the RPC interface and config
 		framework. The config variable name is tls.connection_timeout.
 	</para>
 	<example>
@@ -429,7 +435,7 @@ modparam("tls", "connection_timeout", 60)
 	<section id="tls.p.tls_disable_compression">
 	<title><varname>tls_disable_compression</varname> (boolean)</title>
 	<para>
-		If set compression over SSL/TLS will be disabled.
+		If set compression over TLS will be disabled.
 		Note that compression uses a lot of memory (about 10x more then with
 		the compression disabled), so if you want to minimize
 		memory usage is a good idea to disable it.
@@ -456,7 +462,7 @@ 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)
+		For &kamailio; versions &gt; 3.0 it makes little sense to disable it (0)
 		since the tls module already has its own internal buffering.
 	</para>
 	<para>
@@ -606,7 +612,7 @@ modparam("tls", "ssl_read_ahead", 1)
 	<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
+		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).
@@ -671,7 +677,7 @@ modparam("tls", "con_ct_wq_max", 1048576)
 	<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.
+		sent immediately because of an ongoing TLS level renegotiation.
 	</para>
 	<para>
 		The default value is 10485760 (10 Mb).
@@ -798,10 +804,14 @@ modparam("tls", "tls_debug", 10)
 		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).
+		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).
 	</para>
 	<para>
-		If an ill-behaved openssl version is detected, a very conservative value is choosed, which depends on the maximum possible number of simultaneously created TLS connections (and hence on the process number).
+		If an ill-behaved OpenSSL version is detected, a very conservative value is choosed,
+		which depends on the maximum possible number of simultaneously created TLS connections
+		(and hence on the process number).
 	</para>
 	<para>
 		The following values have a special meaning:
@@ -844,13 +854,16 @@ modparam("tls", "low_mem_threshold1", -1)
 <section id="tls.p.low_mem_threshold2">
 	<title><varname>low_mem_threshold2</varname> (integer)</title>
 	<para>
-		Sets the minimal free memory from which TLS operations on already established TLS connections will start to fail preemptively.  The value is expressed in KB.
+		Sets the minimal free memory from which TLS operations on already established
+		TLS connections will start to fail preemptively.  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).
+		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).
 	</para>
 	<para>
-		If an ill-behaved openssl version is detected, a very conservative value is choosed, which depends on the maximum possible number of simultaneously created TLS connections (and hence on the process number).
+		If an ill-behaved openssl version is detected, a very conservative value is choosed,
+		which depends on the maximum possible number of simultaneously created TLS connections (and hence on the process number).
 	</para>
 	<para>
 		The following values have a special meaning:
@@ -893,7 +906,7 @@ modparam("tls", "low_mem_threshold2", -1)
 	<section id="tls.p.tls_force_run">
 	<title><varname>tls_force_run</varname> (boolean)</title>
 	<para>
-		If enabled Kamailio  will start even if some of the openssl sanity checks fail (turn it on at your own risk).
+		If enabled &kamailio; will start even if some of the OpenSSL sanity checks fail (turn it on at your own risk).
 	</para>
 	<para>
 		Currently failing any of the following sanity checks will not allow Kamailio  to start:
@@ -901,12 +914,14 @@ modparam("tls", "low_mem_threshold2", -1)
 	<itemizedlist>
 			<listitem>
 				<para>
-					the version of the library the TLS module was compiled with is "too different" from the library used at runtime. The versions should have the same major, minor and fix level (e.g.: 0.9.8a and 0.9.8c are ok, but 0.9.8 and 0.9.9 are not)
+					the version of the library the TLS module was compiled with is
+					"too different" from the library used at runtime. The versions should have the same major,
+					minor and fix level (e.g.: 0.9.8a and 0.9.8c are ok, but 0.9.8 and 0.9.9 are not)
 				</para>
 			</listitem>
 			<listitem>
 				<para>
-					the openssl library used at compile time and the one used at runtime have different kerberos options 
+					the OpenSSL library used at compile time and the one used at runtime have different Kerberos options 
 				</para>
 			</listitem>
 	</itemizedlist>
@@ -983,13 +998,13 @@ modparam("tls", "renegotiation", 1)
 	<section id="tls.p.config">
 	<title><varname>config</varname> (string)</title>
 	<para>
-		Sets the name of the TLS specific config file or config directory.
+		Sets the name of the TLS specific configuration file or configuration directory.
 	</para>
 	<para>
-		If set the TLS module will load a special config file or config files from config directory, in which
-		different TLS parameters can be specified on a per role (server or
+		If set the TLS module will load a special configuration file or configuration files
+		from configuration directory, in which different TLS parameters can be specified on a per role (server or
 		client) and domain basis (for now only IPs). The corresponding module
-		parameters will be ignored.
+		parameters will be ignored if a separate configuraiton file is used.
 	</para>
 	<para>
 		If the file or directory name starts with a '.' the path will be relative to the
@@ -1059,7 +1074,8 @@ server_name = kamailio.org
 	</programlisting>
 	</example>
 	<para>
-		For a more complete example check the <emphasis>tls.cfg</emphasis> distributed with the Kamailio source (kamailio/modules/tls/tls.cfg).
+		For a more complete example check the <emphasis>tls.cfg</emphasis> distributed 
+		with the &kamailio; source (kamailio/modules/tls/tls.cfg).
 	</para>
 	<example>
 		<title>Set <varname>config</varname> parameter</title>
@@ -1070,10 +1086,10 @@ modparam("tls", "config", "/usr/local/etc/kamailio/tls.cfg")
 	</programlisting>
 	</example>
 	<para>
-		It can be changed also at runtime. The new config will not be loaded
+		The file can be changed 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>
+			<title>Change and reload the tls configuration at runtime</title>
 			<programlisting>
  $ &sercmd; cfg.set_now_string tls config "/usr/local/etc/kamailio/new_tls.cfg"
  $ &sercmd; tls.reload
@@ -1085,7 +1101,7 @@ modparam("tls", "config", "/usr/local/etc/kamailio/tls.cfg")
 	<section id="tls.p.xavp_cfg">
 	<title><varname>xavp_cfg</varname> (string)</title>
 	<para>
-		Sets the name of XAVP that stored attributes for TLS connections.
+		Sets the name of XAVP that stores attributes for TLS connections.
 	</para>
 	<para>
 		The following (inner) attributes can be set:

modules/tls/doc/rpc.xml

@@ -64,5 +64,4 @@
                 </itemizedlist>
 	</section>
 
-
 </section>

modules/tls/doc/tls.xml

@@ -98,22 +98,22 @@ route{
 			This module includes several workarounds for various Openssl bugs
 			(like compression and Kerberos using the wrong memory allocations
 			functions, low memory problems a.s.o). On startup it will try to enable 
-			the needed workarounds based on the Openssl library version. Each time
+			the needed workarounds based on the OpenSSL library version. Each time
 			a known problem is detected and a workaround is enabled, a message will
 			be logged. In general it is recommended to compile this module on the
 			same machine or a similar machine to where kamailio will be run or to
 			link it statically with <emphasis>libssl</emphasis>. For example if on
-			the compile machine Openssl does not have the Kerberos support enabled,
-			but on the target machine a Kerberos enabled Openssl library is installed,
+			the compile machine OpenSSL does not have the Kerberos support enabled,
+			but on the target machine a Kerberos enabled OpenSSL library is installed,
 			Kamailio cannot apply the needed workarounds and will refuse to start.
-			The same thing will happen if the Openssl versions are too different
+			The same thing will happen if the OpenSSL versions are too different
 			(to force Kamailio startup anyway, see the <varname>tls_force_run</varname>
 			module parameter).
 		</para>
 		<para>
-			Compression is fully supported if you have a new enough Openssl version
+			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
+			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 &kamailio; 3.1 compression is not enabled by
 			default, due to the huge extra memory consumption that it causes (about 10x
@@ -161,8 +161,8 @@ make all include_modules=tls
 			.
 		</para>
 		<para>
-			However in some cases the Openssl library requires linking with other libraries.
-			For example compiling the Openssl library with Kerberos and zlib-shared support
+			However in some cases the OpenSSL library requires linking with other libraries.
+			For example compiling the OpenSSL library with Kerberos and zlib-shared support
 			will require linking the TLS module with libkrb5 and libz. In this case just add
 			<emphasis>TLS_EXTRA_LIBS</emphasis>="library list" to make's command line. E.g.:
 			<programlisting>