<!-- Module User's Guide -->

<chapter>
	<title>&adminguide;</title>

	<section id="overview" xreflabel="Overview">
		<title>Overview</title>
		<para>
			This module is a management module for TLS certificates and
			parameters. It provides an interface for all the modules that
			use the TLS protocol. It also exports pseudo variables with
			certificate and TLS parameters.
		</para>
	</section>

	<section>
		<title>Usage</title>
		<para>
			This module is used to provision TLS certificates and parameters
			for all the modules that use TLS transport (like
			<emphasis>proto_tls</emphasis> or <emphasis>proto_wss</emphasis>).
			The module supports multiple
			virtual domains that can be assigned to different listeners
			(servers) or new connections (clients). Each TLS module that uses
			this management module should assign itself to one or more domains.
		</para>
		<para>
			The module allows the definition of the TLS domains both via 
			module parameters (script level) and via an SQL table.
		</para>
		<para>
		A script example which details this module's usage can be found in
		<xref linkend="tls-example"/>.
		</para>
	</section>

	<section>
		<title>TLS libraries</title>
		<para>
			Besides TLS certificates and parameters, this module also acts as
			an inteface between the actual TLS implemenation (provided by
			<emphasis>openSSL</emphasis> or <emphasis>wolfSSL</emphasis> libraries)
			and transport protocol modules like <emphasis>proto_tls</emphasis> or
			<emphasis>proto_wss</emphasis>. The <emphasis>tls_mgm</emphasis> module
			transparently exposes the TLS operations implemented by
			<emphasis>tls_openssl</emphasis> and <emphasis>tls_wolfssl</emphasis> modules
			to the higher-level OpenSIPS transport modules.
		</para>
		<para>
			The TLS library selection ca be configured through the
			<xref linkend="param_tls_library"/> module parameter.
		</para>
	</section>

	<section>
		<title>TLS domains</title>
		<para>
		The wording 'TLS domain' means that this TLS connection will have different
		parameters than another TLS connection (from another TLS domain). Thus, TLS
		domains are not directly related to different SIP domains, although they
		are often used in conjunction. Depending on the direction of the TLS handshake, a
		TLS domain is called 'client domain' (=outgoing TLS connection) or 'server domain'
		(= incoming TLS connection).
		</para>
		<para>
		If you run several SIP domains you can specify some parameters for each of them
		separately (regardless if you have only one or multiple socket=tls:ip:port entries
		in the config file).
		</para>
		<para>
		For example, TLS domains can be used in virtual hosting scenarios with TLS.
		&osips; offers SIP service for multiple domains, e.g. atlanta.com and biloxi.com. Altough
		both domains will be hosted on a single SIP proxy, the SIP proxy needs 2 certificates: One
		for atlanta.com and one for biloxi.com. For incoming TLS connections, the SIP proxy
		has to present the respective certificate during the TLS handshake. As the SIP proxy
		does not have a received SIP message yet (this is done after the TLS handshake), the SIP
		proxy can not retrieve the target domain from SIP (which would have been usually retrieved 
		from the domain in the request URI). Thus, distinction for these domains must be done by using multiple listening sockets or by having clients that send the Servername TLS extension(SNI) in the
		handshake process.
		</para>
		<para>
		For outgoing TLS connections, the TLS domain is chosen based on the destination socket of the underlying outgoing TCP connection and/or by taking a decision at script level via an AVP. For example, you can inspect headers like RURI or From and match the domain in the SIP header with filters that you have set up for the TLS domains.
		</para>
		<para>
		NOTE: Except tls_handshake_timeout and tls_send_timeout all TLS parameters can be set
		per TLS domain.
		</para>
	</section>

	<section>
		<title>Defining TLS domains</title>
		<para>
			TLS domains can be defined in two ways:
			<itemizedlist>
				<listitem><para>by setting the <emphasis>server_domain</emphasis> or <emphasis>client_domain</emphasis> module parameters</para>
				</listitem>
				<listitem><para>by provisioning in DB</para></listitem>
			</itemizedlist>
		</para>
		<para>For the domains defined in the DB, the certificate, private key, list of trusted CAs and Diffie-Hellman parameters are provisioned as BLOB values while for script defined domains you must provide path to files.</para>
		<para>
			You can define domains both in the DB and script at the same time.
		</para>
		<para>
			For any TLS domain (defined through script or DB) if not specified otherwise, the default settings are:
			<itemizedlist>
				<listitem><para>method - <emphasis>SSLv23</emphasis></para></listitem>
				<listitem><para>verify_cert - <emphasis>1</emphasis></para></listitem>
				<listitem><para>require_cert - <emphasis>1</emphasis></para></listitem>
				<listitem><para>certificate - <emphasis>CFG_DIR/tls/cert.pem</emphasis></para></listitem>
				<listitem><para>private_key - <emphasis>CFG_DIR/tls/ckey.pem</emphasis></para></listitem>
				<listitem><para>crl_check_all - <emphasis>0</emphasis></para></listitem>
				<listitem><para>crl_dir - none</para></listitem>
				<listitem><para>ca_list - none</para></listitem>
				<listitem><para>ca_dir - <emphasis>/etc/pki/CA/</emphasis></para></listitem>
				<listitem><para>cipher_list -  the OpenSSL default ciphers</para></listitem>
				<listitem><para>dh_params -  none</para></listitem>
				<listitem><para>ec_curve -  none</para></listitem>
			</itemizedlist>
		</para>
	</section>

	<section id="dependencies" xreflabel="Dependencies">
	<title>Dependencies</title>
	<section>
		<title>&osips; Modules</title>
		<para>
		The following modules must be loaded before this module:
         <itemizedlist>
			<listitem>
			<para>
				<emphasis>tls_openssl</emphasis> or <emphasis>tls_wolfssl</emphasis>,
				unless <xref linkend="param_tls_library"/> is set to 'none'.
			</para>
			</listitem>
        </itemizedlist>
		</para>
	</section>
	<section>
		<title>Dependencies of external libraries</title>
		<para>
		The following libraries or applications must be installed before
		running &osips; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>

	<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
	<section id="func_is_peer_verified" xreflabel="is_peer_verified()">
		<title>
		<function moreinfo="none">is_peer_verified</function>
		</title>
		<para>
		Returns 1 if the message is received via TLS and the peer was verified
		during TLS connection handshake, otherwise it returns -1
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>is_peer_verified</function> usage</title>
		<programlisting format="linespecific">
...
if (is_peer_verified()) {
        xlog("L_INFO","request from verified TLS peer\n");
} else {
        xlog("L_INFO","request not verified\n");
}
...
</programlisting>
		</example>
	</section>
	</section>

        <section id="exported_mi_functions" xreflabel="Exported MI Functions">
            <title>Exported MI Functions</title>
            <section id="mi_tls_list" xreflabel="tls_list">
                <title>
		<function moreinfo="none">tls_list</function>
                </title>
                <para>
                List all domains information.
                </para>
            </section>

            <section id="mi_tls_reload" xreflabel="tls_reload">
                <title>
		<function moreinfo="none">tls_reload</function>
                </title>
                <para>
                Reloads the TLS domains information from the database.
                The previous DB defined domains are discarded but the
                script defined domains are preserved.
                </para>
            </section>
        </section>

	<section>
		<title>&osips; Exported parameters</title>
		<para>
		All these parameters can be used from the opensips.cfg file,
		to configure the behavior of &osips;-TLS.
		</para>

		<section id="param_listen" xreflabel="listen">
			<title><varname>listen</varname>=interface</title>
			<para>
			Not specific to TLS. Allows to specify the protocol
			(udp, tcp, tls), the IP address and the port where the
			listening server will be.
			</para>
			<example>
				<title>Set <varname>listen</varname> variable</title>
				<programlisting format="linespecific">
...
socket= tls:1.2.3.4:5061
...
				</programlisting>
			</example>
		</section>

		<section id="param_tls_library" xreflabel="tls_library">
			<title><varname>tls_library</varname> (string)</title>
			<para>
				Selects which TLS library to use. Possible values are:
			</para>
			<itemizedlist>
				<listitem>
				<para><emphasis>auto</emphasis> - auto-detect which TLS library
				module (<emphasis>tls_openssl</emphasis> or <emphasis>tls_wolfssl</emphasis>)
				was loaded. OpenSIPS will not start if no module, or both modules are
				found.
				</para>
				</listitem>
				<listitem>
				<para><emphasis>none</emphasis> - do not use any TLS library; this
				is useful when the <emphasis>tls_mgm</emphasis> module is required only
				for the management of TLS certificates and parameters by modules like
				<emphasis>db_mysql</emphasis>, <emphasis>rabbitmq</emphasis> etc. (
				and not for TLS operations by transport modules like
				<emphasis>proto_tls</emphasis> etc.)
				</para>
				</listitem>
				<listitem>
				<para><emphasis>openssl</emphasis> - use the <emphasis>openSSL</emphasis>
				library through the <emphasis>tls_openssl</emphasis> module.
				</para>
				</listitem>
				<listitem>
				<para><emphasis>wolfssl</emphasis> - use the <emphasis>wolfSSL</emphasis>
				library through the <emphasis>tls_wolfssl</emphasis> module.
				</para>
				</listitem>
			</itemizedlist>
			<para>
				Default value is <emphasis>auto</emphasis>.
			</para>
			<example>
				<title>Set <varname>tls_library</varname> variable</title>
				<programlisting format="linespecific">
...
modparam("tls_mgm", "tls_library", "none")
...
				</programlisting>
			</example>
		</section>

		<section id="param_tls_method" xreflabel="tls_method">
			<title><varname>tls_method</varname> ([domain]string)</title>
			<para>
				Sets the TLS protocol. The domain part represents the name of
				the TLS domain. The supported TLS methods are:
			</para>
			<itemizedlist>
				<listitem>
				<para><emphasis>TLSv1_3</emphasis> - means &osips; will
				accept only TLSv1.3 connections. This version is only
				available starting with OpenSSL 1.1.1 version.
				</para>
				</listitem>
				<listitem>
				<para><emphasis>TLSv1_2</emphasis> - means &osips; will
				accept only TLSv1.2 connections (rfc3261 conformant).
				</para>
				</listitem>
				<listitem>
				<para><emphasis>TLSv1</emphasis> - means &osips; will
				accept only TLSv1 connections (rfc3261 conformant).
				</para>
				</listitem>
				<listitem>
				<para><emphasis>SSLv23</emphasis> - means &osips; will
				accept any of the above methods, but the initial SSL
				hello must be v2 (in the initial hello all the supported
				protocols are advertised enabling switching to a higher
				and more secure version). The initial v2 hello means it
				will not accept connections from SSLv3 or TLSv1 only
				clients.
				</para>
				</listitem>
			</itemizedlist>
			<para><emphasis>
				If you are using an OpenSSL library newer than 1.1.0, you can
				also specify a range of accepted TLS versions as [VLOW]-[VHIGH].
				If VLOW is not specified it will use the minimum supported
				protocol version and if VHIGH is not specified it will use
				the maximum supported protocol version. This means that using
				a range where both the low and high values are missing, will
				accept all the supported methods, but unlike SSLv23 will not
				require the initial hello to be SSLv2.
			</emphasis></para>
			<para><emphasis>
				Default value is SSLv23.
			</emphasis></para>
			<warning><para>
			For extended compatibility with older system, best use SSLv23.
			</para></warning>
			<para>
			If you want RFC3261 conformance and all your clients support
			TLSv1 (or you are planning to use encrypted "tunnels" only
			between different &osips; proxies) use TLSv1. If you want to
			support older clients use SSLv23 (in fact most of the
			applications with SSL support use the SSLv23 method).
			</para>
			<example>
				<title>Set <varname>tls_method</varname> variable</title>
				<programlisting format="linespecific">
...
modparam("tls_mgm", "tls_method", "[dom]TLSv1")
...
				</programlisting>
			</example>
			<example>
				<title>Set <varname>tls_method</varname> range variable</title>
				<programlisting format="linespecific">
...
modparam("tls_mgm", "tls_method", "[dom]TLSv1-TLSv1_3")  # between v1 and v1.3
modparam("tls_mgm", "tls_method", "[dom]TLSv1-")         # v1 or higher
modparam("tls_mgm", "tls_method", "[dom]-TLSv1_2")       # up to v1.2
modparam("tls_mgm", "tls_method", "[dom]-")              # all supported
...
				</programlisting>
			</example>
		</section>

		<section id="param_certificate" xreflabel="certificate">
			<title><varname>certificate</varname> ([domain](string)</title>
			<para>
			Public certificate file for &osips;. It will be used as
			server-side certificate for incoming TLS connections, and as
			a client-side certificate for outgoing TLS connections. The domain
			part represents the name of the TLS domain.
			</para>
			<para><emphasis>
				Default value is "CFG_DIR/tls/cert.pem".
			</emphasis></para>
			<example>
				<title>Set <varname>certificate</varname> variable
					</title>
				<programlisting format="linespecific">
...
modparam("tls_mgm", "certificate", "[dom]/mycerts/certs/opensips_server_cert.pem")
...
				</programlisting>
			</example>
		</section>

		<section id="param_private_key" xreflabel="private_key">
			<title><varname>private_key</varname> ([domain](string)</title>
			<para>
			Private key of the above certificate. I must be kept in a
			safe place with tight permissions! The domain part
			represents the name of the TLS omain.
			</para>
			<para><emphasis>
				Default value is "CFG_DIR/tls/ckey.pem".
			</emphasis></para>
			<example>
				<title>Set <varname>private_key</varname> variable
					</title>
				<programlisting format="linespecific">
...
modparam("tls_mgm", "private_key", "[dom]/mycerts/private/prik.pem")
...
				</programlisting>
			</example>
		</section>

		<section id="param_ca_list" xreflabel="ca_list">
			<title><varname>ca_list</varname> ([domain](string)</title>
			<para>
			List of trusted CAs. The file contains the certificates
			accepted, one after the other. It MUST be a file, not
			a folder. The domain part represents the name
			of the TLS domain.
			</para>
			<para><emphasis>
				Default value is "".
			</emphasis></para>
			<example>
				<title>Set <varname>ca_list</varname> variable</title>
				<programlisting format="linespecific">
...
modparam("tls_mgm", "ca_list", "[dom]/mycerts/certs/ca_list.pem")
...
				</programlisting>
			</example>
		</section>

		<section id="param_ca_dir" xreflabel="ca_dir">
			<title><varname>ca_dir</varname> ([domain](string)</title>
			<para>
			Directory storing trusted CAs. The certificates in the directory
			must be in hashed form, as described in the
			<ulink url="https://www.openssl.org/docs/manmaster/man3/X509_LOOKUP_hash_dir.html">
			<citetitle>openssl documentation</citetitle></ulink> for the
			<emphasis>Hashed Directory Method</emphasis>. The domain part
			represents the name of the TLS domain.
			</para>
			<para><emphasis>
				Default value is "/etc/pki/CA/".
			</emphasis></para>
			<example>
				<title>Set <varname>ca_dir</varname> variable</title>
				<programlisting format="linespecific">
...
modparam("tls_mgm", "ca_dir", "[dom]/mycerts/certs")
...
				</programlisting>
			</example>
		</section>

		<section id="param_crl_dir" xreflabel="crl_dir">
			<title><varname>crl_dir</varname> ([domain](string)</title>
			<para>
			Directory storing certificate revocation lists (CRLs). The domain
			part represents the name of the TLS domain.
			</para>
			<para><emphasis>
				If this parameter is not set, no CRLs will be used.
			</emphasis></para>
			<example>
				<title>Set <varname>crl_dir</varname> variable</title>
				<programlisting format="linespecific">
...
modparam("tls_mgm", "crl_dir", "[dom]/mycerts/crls")
...
				</programlisting>
			</example>
		</section>

		<section id="param_crl_check_all" xreflabel="crl_check_all">
			<title><varname>crl_check_all</varname> ([domain](string)</title>
			<para>
			Setting this parameter with a non-zero integer value enables CRL
			checking for the entire certificate chain.
			</para>
			<para><emphasis>
				By default, only the leaf certificate in the certificate chain
				is checked.
			</emphasis></para>
			<example>
				<title>Set <varname>crl_check_all</varname> variable</title>
				<programlisting format="linespecific">
...
modparam("tls_mgm", "crl_check_all", "[dom]1")
...
				</programlisting>
			</example>
		</section>

		<section id="param_ciphers_list" xreflabel="ciphers_list">
			<title><varname>ciphers_list</varname> ([domain](string)</title>
			<para>
			You can specify the list of algorithms for authentication
			and encryption that you allow. The domain part
			represents the name of the TLS domain. To obtain a list of ciphers
			and then choose, use the openssl application:
			</para>
			<itemizedlist>
				<listitem>
				<para>openssl ciphers 'ALL:eNULL:!LOW:!EXPORT'</para>
				</listitem>
			</itemizedlist>
			<warning><para>
			Do not use the NULL algorithms (no encryption) ... only for testing!!!
			</para></warning>
			<para><emphasis>
				It defaults to the OpenSSL default ciphers.
			</emphasis></para>
			<example>
				<title>Set <varname>ciphers_list</varname> variable
					</title>
				<programlisting format="linespecific">
...
modparam("tls_mgm", "ciphers_list", "[dom]NULL")
...
				</programlisting>
			</example>
		</section>

		<section id="param_dh_params" xreflabel="dh_params">
			<title><varname>dh_params</varname> ([domain](string)</title>
			<para>
			You can specify a file which contains Diffie-Hellman
			parameters as a PEM-file. This is needed if you would like
			to specify ciphers including Diffie-Hellman mode. The 
			domain part represents the name of the TLS domain.
			</para>
			<para><emphasis>
				It defaults to not set a dh param file.
			</emphasis></para>
			<example>
				<title>Set <varname>dh_params</varname> variable
					</title>
				<programlisting format="linespecific">
...
modparam("tls_mgm", "dh_params", "[dom]/etc/pki/CA/dh1024.pem")
...
				</programlisting>
			</example>
		</section>

		<section id="param_ec_curve" xreflabel="ec_curve">
			<title><varname>ec_curve</varname> ([domain](string)</title>
			<para>
			You can specify an elliptic curve which should be used for
			ciphers which demand an elliptic curve. The domain part
			represents the name of the TLS domain.
			</para>
			<para>
			It's usable only if TLS v1.1/1.2 support was compiled.
			A list of curves which can be used you can get by
			<programlisting format="linespecific">
				openssl ecparam -list_curves
			</programlisting>
			</para>
			<para><emphasis>
				It defaults to not set a elliptic curve.
			</emphasis></para>
		</section>

		<section id="param_verify_cert" xreflabel="verify_cert">
			<title><varname>verify_cert</varname> ([domain](string)</title>
			<para>
			Activates SSL_VERIFY_PEER in the ssl_context. For a detailed
			explanation, check the <emphasis>openssl</emphasis> documentation.
			</para>
			<para>The domain part represents the name of the TLS domain.</para>
			<para>
				Default value is <emphasis>1</emphasis>.
			</para>
			<example>
				<title>Set <varname>verify_cert</varname> variable</title>
				<programlisting format="linespecific">
...
modparam("tls_mgm", "verify_cert", "[dom]0")
...
				</programlisting>
			</example>
		</section>

		<section id="param_require_cert" xreflabel="require_cert">
			<title><varname>require_cert</varname> ([domain](string)</title>
			<para>
			Activates SSL_VERIFY_FAIL_IF_NO_PEER_CERT in the ssl_context. For a
			detailed explanation, check the <emphasis>openssl</emphasis>
			documentation. This parameter only makes sense for server domains
			and if the <xref linkend="param_verify_cert"/> parameter is also set.
			</para>
			<para>The domain part represents the name of the TLS domain.</para>
			<para>
				Default value is <emphasis>1</emphasis>.
			</para>
			<example>
				<title>Set <varname>require_cert</varname> variable</title>
				<programlisting format="linespecific">
...
modparam("tls_mgm", "require_cert", "[dom]0")
...
				</programlisting>
			</example>
		</section>

		<section id="param_client_tls_domain_avp" xreflabel="client_tls_domain_avp">
			<title><varname>client_tls_domain_avp</varname> (string)</title>
			<para>
			Name of the AVP used for enforcing the selection of a specific TLS
			client domain. Setting this AVP to the name of a TLS client domain will
			result in using that specific domain regardless of the standard matching
			mechanism.
			</para>
			<para>
			Note: If there is already an existing TLS connection to the remote target,
			it will be reused and setting this AVP has no effect.
			</para>
			<para>
			Note: You can force a particular domain to be used just for a particular
			branch by setting the <emphasis>$bavp</emphasis> variable with the same
			name. When both <emphasis>$bavp</emphasis> and <emphasis>$avp</emphasis>
			variables are set, the first one takes precedence.
			</para>
			<para><emphasis>
				No default value.
			</emphasis></para>
			<example>
				<title>Set <varname>client_tls_domain_avp</varname> variable</title>
				<programlisting format="linespecific">
...
modparam("tls_mgm", "client_tls_domain_avp", "tls_match_dom")
...
				</programlisting>
			</example>
		</section>

		<section id="param_client_sip_domain_avp" xreflabel="client_sip_domain_avp">
			<title><varname>client_sip_domain_avp</varname> (string)</title>
			<para>
			Name of the AVP that sets the SIP domain used in the TLS client
			domain matching process.
			</para>
			<para>
			Note: If there is already an existing TLS connection to the remote target,
			it will be reused and setting this AVP has no effect.
			</para>
			<para>
			Note: You can force a particular SIP domain to be used just for a particular
			branch by setting the <emphasis>$bavp</emphasis> variable with the same
			name. When both <emphasis>$bavp</emphasis> and <emphasis>$avp</emphasis>
			variables are set, the first one takes precedence.
			</para>
			<para>
			For the AVP usage example, refer to  <xref linkend="domains-param"/>.
			</para>
			<para><emphasis>
				No default value.
			</emphasis></para>
			<example>
				<title>Set <varname>client_sip_domain_avp</varname> variable</title>
				<programlisting format="linespecific">
...
modparam("tls_mgm", "client_sip_domain_avp", "sip_match_dom")
...
				</programlisting>
			</example>
		</section>

		<section id="param_db_url" xreflabel="db_url">
			<title><varname>db_url</varname> (string)</title>
			<para>
			The database url. It cannot be NULL.
			</para>
			<para>
			You cannot use the "tls_domain=<emphasis>dom_name</emphasis>" URL parameter
			for a TLS connection to the database for the tls_mgm module itself.
			</para>
			<example>
				<title>Usage of <varname>db_url</varname> block
					</title>
				<programlisting format="linespecific">
modparam("tls_mgm", "db_url", "mysql://root:admin@localhost/opensips")
				</programlisting>
			</example>
		</section>

                <section>
                    <title>
                        <varname>db_table</varname> (string)
                    </title>
                    <para>
                        Sets the database table name.
                    </para>
                    <para>Default value is "tls_mgm".</para>
                    <example>
				<title>Usage of <varname>db_table</varname> block
					</title>
				<programlisting format="linespecific">
modparam("tls_mgm", "db_table", "tls_mgm")
                                </programlisting>
                    </example>
                </section>

                <section>
                    <title>
                        <varname>domain_col</varname> (string)
                    </title>
                    <para>
                        Sets the name for the TLS domain column.
                    </para>
                    <para>Default value is "domain".</para>
                    <example>
				<title>Usage of <varname>domain_col</varname> block
					</title>
				<programlisting format="linespecific">
modparam("tls_mgm", "domain_col", "tls_domain")
                                </programlisting>
                    </example>
                </section>

                <section>
                    <title>
                        <varname>match_ip_address_col</varname> (string)
                    </title>
                    <para>
                        Sets the IP address matching column name.
                    </para>
                    <para>Default value is "match_ip_address".</para>
                    <example>
				<title>Usage of <varname>match_ip_address_col</varname> block
					</title>
				<programlisting format="linespecific">
modparam("tls_mgm", "match_ip_address_col", "addr")
                                </programlisting>
                    </example>
                </section>

                <section>
                    <title>
                        <varname>match_sip_domain_col</varname> (string)
                    </title>
                    <para>
                        Sets the SIP domain matching column name.
                    </para>
                    <para>Default value is "match_sip_domain".</para>
                    <example>
				<title>Usage of <varname>match_sip_domain_col</varname> block
					</title>
				<programlisting format="linespecific">
modparam("tls_mgm", "match_sip_domain_col", "addr")
                                </programlisting>
                    </example>
                </section>

                <section>
                    <title>
                        <varname>tls_method_col</varname> (string)
                    </title>
                    <para>
                        Sets the method column name.
                    </para>
                    <para>Default value is "method".</para>
                    <example>
				<title>Usage of <varname>tls_method_col</varname> block
					</title>
				<programlisting format="linespecific">
modparam("tls_mgm", "tls_method_col", "method")
                                </programlisting>
                    </example>
                </section>

                <section>
                    <title>
                        <varname>verify_cert_col</varname> (string)
                    </title>
                    <para>
                        Sets the verrify certificate column name.
                    </para>
                    <para>Default value is "verify_cert".</para>
                    <example>
				<title>Usage of <varname>vertify_cert_col</varname> block
					</title>
				<programlisting format="linespecific">
modparam("tls_mgm", "verify_cert_col", "verify_cert")
                                </programlisting>
                    </example>
                </section>

                <section>
                    <title>
                        <varname>require_cert_col</varname> (string)
                    </title>
                    <para>
                        Sets the require certificate column name.
                    </para>
                    <para>Default value is "require_cert".</para>
                    <example>
				<title>Usage of <varname>require_cert_col</varname> block
					</title>
				<programlisting format="linespecific">
modparam("tls_mgm", "require_cert_col", "req")
                                </programlisting>
                    </example>
                </section>

                <section>
                    <title>
                        <varname>certificate_col</varname> (string)
                    </title>
                    <para>
                        Sets the certificate column name.
                    </para>
                    <para>Default value is "certificate".</para>
                    <example>
				<title>Usage of <varname>certificate_col</varname> block
					</title>
				<programlisting format="linespecific">
modparam("tls_mgm", "certificate_col", "certificate")
                                </programlisting>
                    </example>
                </section>

                <section>
                    <title>
                        <varname>private_key_col</varname> (string)
                    </title>
                    <para>
                        Sets the private key column name.
                    </para>
                    <para>Default value is "private_key".</para>
                    <example>
				<title>Usage of <varname>private_key_col</varname> block
					</title>
				<programlisting format="linespecific">
modparam("tls_mgm", "private_key_col", "pk")
                                </programlisting>
                    </example>
                </section>

                <section>
                    <title>
                        <varname>crl_check_all_col</varname> (string)
                    </title>
                    <para>
                        Sets the crl_check_all column name.
                    </para>
                    <para>Default value is "crl_check_all".</para>
                    <example>
				<title>Usage of <varname>crl_check_all</varname> block
					</title>
				<programlisting format="linespecific">
modparam("tls_mgm", "crl_check_all_col", "crl_check")
                                </programlisting>
                    </example>
                </section>

                <section>
                    <title>
                        <varname>crl_dir_col</varname> (string)
                    </title>
                    <para>
                        Sets the crl directory column name.
                    </para>
                    <para>Default value is "crl_dir".</para>
                    <example>
				<title>Usage of <varname>crl_dir_col</varname> block
					</title>
				<programlisting format="linespecific">
modparam("tls_mgm", "crl_dir_col", "crl_dir")
                                </programlisting>
                    </example>
                </section>
                            <section>
                    <title>
                        <varname>ca_list_col</varname> (string)
                    </title>
                    <para>
                        Sets the CA list column name.
                    </para>
                    <para>Default value is "ca_list".</para>
                    <example>
				<title>Usage of <varname>ca_list_col</varname> block
					</title>
				<programlisting format="linespecific">
modparam("tls_mgm", "ca_list_col", "ca_list")
                                </programlisting>
                    </example>
                </section>



                <section>
                    <title>
                        <varname>ca_dir_col</varname> (string)
                    </title>
                    <para>
                        Sets the CA directory column name.
                    </para>
                    <para>Default value is "ca_dir".</para>
                    <example>
				<title>Usage of <varname>ca_dir_col</varname> block
					</title>
				<programlisting format="linespecific">
modparam("tls_mgm", "ca_dir_col", "ca_dir")
                                </programlisting>
                    </example>
                </section>


                 <section>
                    <title>
                        <varname>cipher_list_col</varname> (string)
                    </title>
                    <para>
                        Sets the cipher list column name.
                    </para>
                    <para>Default value is "cipher_list".</para>
                    <example>
				<title>Usage of <varname>cipher_list_col</varname> block
					</title>
				<programlisting format="linespecific">
modparam("tls_mgm", "cipher_list_col", "cipher_list")
                                </programlisting>
                    </example>
                </section>


                <section>
                    <title>
                        <varname>dh_params_col</varname> (string)
                    </title>
                    <para>
                        Sets the Diffie-Hellmann parameters column name.
                    </para>
                    <para>Default value is "dh_params".</para>
                    <example>
				<title>Usage of <varname>dh_params_col</varname> block
					</title>
				<programlisting format="linespecific">
modparam("tls_mgm", "dh_params_col", "dh_parms")
                                </programlisting>
                    </example>
                </section>

               <section>
                    <title>
                        <varname>ec_curve_col</varname> (string)
                    </title>
                    <para>
                        Sets the ec_curve column name.
                    </para>
                    <para>Default value is "ec_curve".</para>
                    <example>
				<title>Usage of <varname>ec_curve_col</varname> block
					</title>
				<programlisting format="linespecific">
modparam("tls_mgm", "ec_curve_col", "ec_curve")
                                </programlisting>
                    </example>
                </section>

        <section id="param_match_ip_address" xreflabel="match_ip_address">
			<title><varname>match_ip_address</varname> (string)</title>
			<para>
			The IP addresses and ports used to match a TLS connection with a
			virtual TLS domain. For TLS server domains, these values will be
			mathced against the socket on which the connection is received. For
			TLS client domains, the values will be compared with the destination
			socket of the connection.
			</para>
			<para>
				The parameter accepts a list of values, and the special value "*"
				means: match any address.
			</para>
			<para><emphasis>
				Default value is "*" (match any address).
			</emphasis></para>
			<example>
				<title>Set <varname>match_ip_address</varname> variable</title>
				<programlisting format="linespecific">
...
modparam("tls_mgm", "match_ip_address", "[dom1]10.0.0.10:5061, 10.0.0.11:5061")
...
				</programlisting>
			</example>
		</section>

		<section id="param_match_sip_domain" xreflabel="match_sip_domain">
			<title><varname>match_sip_domain</varname> (string)</title>
			<para>
			The SIP domains used to match a TLS connection with a
			virtual TLS domain. For TLS server domains, these values will be
			matched against the hostname provided in the TLS Servername extension(SNI).
			For TLS client domains, the values will be compared with the value of
			the <xref linkend="param_client_sip_domain_avp"/> AVP.
			</para>
			<para>
				The parameter accepts a list of FQDNs or the special values:
				<itemizedlist>
					<listitem><para><emphasis>*</emphasis> - match any sip domain(
					including no SNI provided, in case of TLS server domains);
					</para></listitem>
					<listitem><para><emphasis>none</emphasis> - match the TLS domain
					when there is no SNI provided (make sense only for TLS server
					domains). Note that if a SNI is provided, but does not match any
					other SIP domain filter, the connection will be rejected.
					</para></listitem>
				</itemizedlist>
			</para>
			<para>
				The FQDNs can be specified as with Unix shell-style wildcards. If
				there are multiple potential matches, the most specific domain will
				be selected(eg. a request for "foo.bar.com" is matched with the domain
				specified with "foo.bar.com" versus the one with "*.bar.com").
			</para>
			<para><emphasis>
				Default value is "*" (match any sip domain).
			</emphasis></para>
			<example>
				<title>Set <varname>match_sip_domain</varname> variable</title>
				<programlisting format="linespecific">
...
modparam("tls_mgm", "match_sip_domain", "[dom1]foo.com, bar.com, *.baz.com")
modparam("tls_mgm", "match_sip_domain", "[default_dom]*")
...
				</programlisting>
			</example>
		</section>

		<section id="domains-param">
			<title><varname>server_domain, client_domain</varname> (string)</title>
			<para>
				You can define virtual TLS domains through these parameters.
			</para>
			<para>
				The value of these parameters represents the virtual tls domain's
				name which is only used for identification.
			</para>
			<example>
				<title>Usage of <varname>tls_client_domain</varname> and
					<varname>tls_server_domain</varname> block
					</title>
				<programlisting format="linespecific">
...
socket=tls:10.0.0.10:5061
...
# set the TLS client domain AVP
modparam("tls_mgm", "client_sip_domain_avp", "tls_sip_dom")
...

# 'atlanta' server domain
modparam("tls_mgm", "server_domain", "dom1")
modparam("tls_mgm", "match_ip_address", "[dom1]10.0.0.10:5061")
modparam("tls_mgm", "match_sip_domain", "[dom1]atlanta.com")

modparam("tls_mgm", "certificate", "[dom1]/certs/atlanta.com/cert.pem")
modparam("tls_mgm", "private_key", "[dom1]/certs/atlanta.com/privkey.pem")
modparam("tls_mgm", "ca_list", "[dom1]/certs/wellknownCAs")
modparam("tls_mgm", "tls_method", "[dom1]tlsv1")
modparam("tls_mgm", "verify_cert", "[dom1]1")
modparam("tls_mgm", "require_cert", "[dom1]1")

#'biloxi' server domain
modparam("tls_mgm", "server_domain", "dom2")
modparam("tls_mgm", "match_ip_address", "[dom2]10.0.0.10:5061")
modparam("tls_mgm", "match_sip_domain", "[dom2]biloxi.com")

modparam("tls_mgm", "certificate", "[dom2]/certs/biloxi.com/cert.pem")
modparam("tls_mgm", "private_key", "[dom2]/certs/biloxi.com/privkey.pem")
modparam("tls_mgm", "ca_list", "[dom2]/certs/wellknownCAs")
modparam("tls_mgm", "tls_method", "[dom2]tlsv1")
modparam("tls_mgm", "verify_cert", "[dom2]1")
modparam("tls_mgm", "require_cert", "[dom2]1")

# generic TLS server domain, if the client does not provide SNI
modparam("tls_mgm", "server_domain", "dom3")
modparam("tls_mgm", "match_ip_address", "[dom3]10.0.0.10:5061")
modparam("tls_mgm", "match_sip_domain", "[dom3]none")

modparam("tls_mgm", "certificate", "[dom3]/certs/generic/cert.pem")
modparam("tls_mgm", "private_key", "[dom3]/certs/generic/privkey.pem")
modparam("tls_mgm", "ca_list", "[dom3]/certs/wellknownCAs")
modparam("tls_mgm", "tls_method", "[dom3]tlsv1")
modparam("tls_mgm", "verify_cert", "[dom3]1")
modparam("tls_mgm", "require_cert", "[dom3]1")

# 'atlanta' client domain
modparam("tls_mgm", "client_domain", "dom4")
modparam("tls_mgm", "match_ip_address", "[dom4]*")
modparam("tls_mgm", "match_sip_domain", "[dom4]atlanta.com")


modparam("tls_mgm", "certificate", "[dom4]/certs/atlanta.com/cert.pem")
modparam("tls_mgm", "private_key", "[dom4]/certs/atlanta.com/privkey.pem")
modparam("tls_mgm", "ca_list", "[dom4]/certs/wellknownCAs")
modparam("tls_mgm", "tls_method", "[dom4]tlsv1")
modparam("tls_mgm", "verify_cert", "[dom4]1")
modparam("tls_mgm", "require_cert", "[dom4]1")

# 'biloxi' client domain
modparam("tls_mgm", "client_domain", "dom5")
modparam("tls_mgm", "match_ip_address", "[dom5]*")
modparam("tls_mgm", "match_sip_domain", "[dom5]biloxi.com")

modparam("tls_mgm", "certificate", "[dom5]/certs/biloxi.com/cert.pem")
modparam("tls_mgm", "private_key", "[dom5]/certs/biloxi.com/privkey.pem")
modparam("tls_mgm", "ca_list", "[dom5]/certs/wellknownCAs")
modparam("tls_mgm", "tls_method", "[dom5]tlsv1")
modparam("tls_mgm", "verify_cert", "[dom5]1")
modparam("tls_mgm", "require_cert", "[dom5]1")

# TLS client domain for GW provider
modparam("tls_mgm", "client_domain", "dom6")
modparam("tls_mgm", "match_ip_address", "[dom6]1.2.3.4:6677")
modparam("tls_mgm", "match_sip_domain", "[dom6]*")

modparam("tls_mgm", "certificate", "[dom6]/certs/gw/cert.pem")
modparam("tls_mgm", "private_key", "[dom6]/certs/gw/privkey.pem")
modparam("tls_mgm", "ca_list", "[dom6]/certs/wellknownCAs")
modparam("tls_mgm", "tls_method", "[dom6]tlsv1")
modparam("tls_mgm", "verify_cert", "[dom6]0")

...
route{
...
    # we match the TLS client domain using the SIP domain in the RURI
    $avp(tls_sip_dom) = $rd;
    t_relay();
    exit;
...
    # calls to the PSTN GW, will match the correct TLS domain by IP
    t_relay("tls:1.2.3.4:6677");
    exit;
...
				</programlisting>
			</example>
		</section>
	</section>


	<section>
	<title>Variables</title>
	<para>
	This module exports the follong variables:
	</para>
	<para>
	Some variables are available for both, the peer'S certificate and
	the local certificate. Further, some parameters can be read from the
	<quote>Subject</quote> field or the <quote>Issuer</quote> field.
	</para>
	<section>
		<title>$tls_version</title>
			<para>
			<emphasis>$tls_version</emphasis> - the TLS/SSL version which is
			used on the TLS connection from which the message was received.
			String type.
			</para>
	</section>
	<section>
		<title>$tls_description</title>
			<para>
			<emphasis>$tls_description</emphasis> - the TLS/SSL description
			of the TLS connection from which the message was received. String
			type.
			</para>
	</section>
	<section>
		<title>$tls_cipher_info</title>
			<para>
			<emphasis>$tls_cipher_info</emphasis> - the TLS/SSL cipher which
			is used on the TLS connection from which the message was received.
			String type.
			</para>
	</section>
	<section>
		<title>$tls_cipher_bits</title>
			<para>
			<emphasis>$tls_cipher_bits</emphasis> - the number of cipher bits
			which are used on the TLS connection from which the message was
			received. String and Integer type.
			</para>
	</section>
	<section>
		<title>$tls_[peer|my]_version</title>
			<para>
			<emphasis>$tls_[peer|my]_version</emphasis> - the version of the
			certificate. String type.
			</para>
	</section>
	<section>
		<title>$tls_[peer|my]_serial</title>
			<para>
			<emphasis>$tls_[peer|my]_serial</emphasis> - the serial number
			of the certificate. String and Integer type.
			</para>
	</section>
	<section>
		<title>$tls_[peer|my]_[subject|issuer]</title>
			<para>
			<emphasis>$tls_[peer|my]_[subject|issuer]</emphasis> - ASCII dump
			of the fields in the issuer/subject section of the certificate.
			String type.
			</para>
			<example>
				<title>Example of <varname>$tls_[peer|my]_[subject|issuer]</varname></title>
<programlisting format="linespecific">
/C=AT/ST=Vienna/L=Vienna/O=enum.at/CN=enum.at
</programlisting>
			</example>

	</section>
	<section>
		<title>$tls_[peer|my]_[subject|issuer]_cn</title>
			<para>
			<emphasis>$tls_[peer|my]_[subject|issuer]_cn</emphasis> -
			commonName in the issuer/subject section of the certificate.
			String type.
			</para>
	</section>
	<section>
		<title>$tls_[peer|my]_[subject|issuer]_locality</title>
			<para>
			<emphasis>$tls_[peer|my]_[subject|issuer]_locality</emphasis> -
			localityName in the issuer/subject section of the certificate.
			String type.
			</para>
	</section>
	<section>
		<title>$tls_[peer|my]_[subject|issuer]_country</title>
			<para>
			<emphasis>$tls_[peer|my]_[subject|issuer]_country</emphasis> -
			countryName in the issuer/subject section of the certificate.
			String type.
			</para>
	</section>
	<section>
		<title>$tls_[peer|my]_[subject|issuer]_state</title>
			<para>
			<emphasis>$tls_[peer|my]_[subject|issuer]_state</emphasis> -
			stateOrProvinceName in the issuer/subject section of the
			certificate. String type.
			</para>
	</section>
	<section>
		<title>$tls_[peer|my]_[subject|issuer]_organization</title>
			<para>
			<emphasis>$tls_[peer|my]_[subject|issuer]_organization</emphasis> -
			organizationName in the issuer/subject section of the certificate.
			String type.
			</para>
	</section>
	<section>
		<title>$tls_[peer|my]_[subject|issuer]_unit</title>
			<para>
			<emphasis>$tls_[peer|my]_[subject|issuer]_unit</emphasis> -
			organizationalUnitName in the issuer/subject section of the
			certificate. String type.
			</para>
	</section>
	<section>
		<title>$tls_[peer|my]_san_email</title>
			<para>
			<emphasis>$tls_[peer|my]_san_email</emphasis> - email address in
			the <quote>subject alternative name</quote> extension. String type.
			</para>
	</section>
	<section>
		<title>$tls_[peer|my]_san_hostname</title>
			<para>
			<emphasis>$tls_[peer|my]_san_hostname</emphasis> - hostname (DNS)
			in the <quote>subject alternative name</quote> extension. String
			type.
			</para>
	</section>
	<section>
		<title>$tls_[peer|my]_san_uri</title>
			<para>
			<emphasis>$tls_[peer|my]_san_uri</emphasis> - URI in the
			<quote>subject alternative name</quote> extension.
			String type.
			</para>
	</section>
	<section>
		<title>$tls_[peer|my]_san_ip</title>
			<para>
			<emphasis>$tls_[peer|my]_san_ip</emphasis> - ip address in the
			<quote>subject alternative name</quote> extension.
			String type.
			</para>
	</section>
	<section>
		<title>$tls_peer_verified</title>
			<para>
			<emphasis>$tls_peer_verified</emphasis> - Returns 1 if the peer's
			certificate was successful verified. Otherwise it returns 0.
			String and Integer type.
			</para>
	</section>
	<section>
		<title>$tls_peer_revoked</title>
			<para>
			<emphasis>$tls_peer_revoked</emphasis> - Returns 1 if the peer's
			certificate was revoked. Otherwise it returns 0.
			String and Integer type.
			</para>
	</section>
	<section>
		<title>$tls_peer_expired</title>
			<para>
			<emphasis>$tls_peer_expired</emphasis> - Returns 1 if the peer's
			certificate is expired. Otherwise it returns 0.
			String and Integer type.
			</para>
	</section>
	<section>
		<title>$tls_peer_selfsigned</title>
			<para>
			<emphasis>$tls_peer_selfsigned</emphasis> - Returns 1 if the
			peer's certificate is selfsigned. Otherwise it returns 0.
			String and Integer type.
			</para>
	</section>
	<section>
		<title>$tls_peer_notBefore</title>
			<para>
			<emphasis>$tls_peer_notBefore</emphasis> - Returns the notBefore
			validity date of the peer's certificate.
			String type.
			</para>
	</section>
	<section>
		<title>$tls_peer_notAfter</title>
			<para>
			<emphasis>$tls_peer_notAfter</emphasis> - Returns the notAfter
			validity date of the peer's certificate.
			String type.
			</para>
	</section>
	</section>



	<section id="tls-example">
		<title>&osips; with TLS - script example</title>
		<para>
		IMPORTANT: The TLS support is based on TCP, and for allowing &osips;
		to use TCP, it must be started in multi-process mode. So, there is
		a must to have the "fork" parameter set to "yes":
		</para>
		<para>
		NOTE: Since the TLS engine is quite memory consuming, increase the
		used memory by the run time parameter "-m" (see &osips; -h for more
		details).
		</para>
		<itemizedlist>
			<listitem>
				<para>fork = yes</para>
			</listitem>
		</itemizedlist>

		<example>
			<title>Script with TLS support</title>
		<programlisting format="linespecific">
  # ----------- global configuration parameters ------------------------
  log_level=3
  stderror_enabled=no
  syslog_enabled=yes

  check_via=no
  dns=no
  rev_dns=no
  socket=udp:your_serv_IP:5060
  socket=tls:your_serv_IP:5061
  udp_workers=4

  # ------------------ module loading ----------------------------------

  loadmodule "proto_tls.so"
  loadmodule "proto_udp.so"

  #TLS specific settings
  loadmodule "tls_mgm.so"

  modparam("tls_mgm", "certificate", "/path/opensipsX_cert.pem")
  modparam("tls_mgm", "private_key", "/path/privkey.pem")
  modparam("tls_mgm", "ca_list", "/path/calist.pem")
  modparam("tls_mgm", "ca_list", "/path/calist.pem")
  modparam("tls_mgm", "require_cert", "1")
  modparam("tls_mgm", "verify_cert", "1")

  alias=_DNS_ALIAS_


  loadmodule "sl.so"
  loadmodule "rr.so"
  loadmodule "maxfwd.so"
  loadmodule "mysql.so"
  loadmodule "usrloc.so"
  loadmodule "registrar.so"
  loadmodule "tm.so"
  loadmodule "auth.so"
  loadmodule "auth_db.so"
  loadmodule "textops.so"
  loadmodule "sipmsgops.so"
  loadmodule "signaling.so"
  loadmodule "uri_db.so"

  # ----------------- setting module-specific parameters ---------------

  # -- auth_db params --
  modparam("auth_db", "db_url", "sql_url")
  modparam("auth_db", "password_column", "password")
  modparam("auth_db", "calculate_ha1", 1)

  # -- registrar params --
  # no multiple registrations
  modparam("registrar", "append_branches", 0)

  # -------------------------  request routing logic -------------------

  # main routing logic

  route{

  # initial sanity checks
  if (!mf_process_maxfwd_header("10")) {
      send_reply(483,"Too Many Hops");
      exit;
  };

  # if somene claims to belong to our domain in From,
  # challenge him (skip REGISTERs -- we will chalenge them later)
  if (is_myself("$fd")) {
      setflag(1);
      if ( is_method("INVITE|SUBSCRIBE|MESSAGE")
      &amp;&amp; !(is_myself("$si")) ) {
          if  (!(proxy_authorize( "domA.net", "subscriber" ))) {
              proxy_challenge("domA.net","0"/*no-qop*/);
              exit;
          };
          if ($au!=$fU) {
              xlog("FROM hdr Cheating attempt in INVITE\n");
              send_reply(403,
                  "That is ugly -- use From=id next time (OB)");
              exit;
          };
      }; # non-REGISTER from other domain
  } else if ( is_method("INVITE") &amp;&amp; !is_myself("$rd") ) {
      send_reply(403, "No relaying");
      exit;
  };

  /* ********   do record-route and loose-route ******* */
  if (!is_method("REGISTER"))
      record_route();

  if (loose_route()) {
      append_hf("P-hint: rr-enforced\r\n");
      t_relay();
      exit;
  };

  /* ******* check for requests targeted out of our domain ******* */
  if ( !is_myself("$rd") ) {
      append_hf("P-hint: OUTBOUND\r\n");
      if ($rd=="domB.net") {
          t_relay("tls:domB.net:5061");
      } else if ($rd=="domC.net") {
          t_relay("tls:domC.net:5061");
      } else {
          t_relay();
      };
      exit;
  };

  /* ******* divert to other domain according to prefixes ******* */
  if (!is_method("REGISTER")) {
      if ( $ru=~"sip:201") {
          strip(3);
          $rd = "domB.net";
          t_relay("tls:domB.net:5061");
          exit;
      } else if ( $ru=~"sip:202" ) {
          strip(3);
          $rd = "domC.net";
          t_relay("tls:domC.net:5061");
          exit;
      };
  };

  /* ************ requests for our domain ********** */
  if (is_method("REGISTER")) {
      if (!www_authorize( "domA.net", "subscriber" )) {
          # challenge if none or invalid credentials
          www_challenge( "domA.net" /* realm */,
              "0" /* no qop -- some phones can't deal with it */);
          exit;
      };
      if ($au!=$tU) {
          xlog("TO hdr Cheating attempt\n");
          send_reply(403, "That is ugly -- use To=id in REGISTERs");
          exit;
      };
      # it is an authenticated request, update Contact database now
      if (!save("location")) {
          sl_reply_error();
      };
      exit;
  };

  # native SIP destinations are handled using USRLOC DB
  if (!lookup("location")) {
      # handle user which was not found
      send_reply(404, "Not Found");
      exit;
  };

  # remove all present Alert-info headers
  remove_hf("Alert-Info");

  if (is_method("INVITE") &amp;&amp; ($rP=="TLS" || isflagset(1))) {
      append_hf("Alert-info: 1\r\n");                     # cisco 7960
      append_hf("Alert-info: Bellcore-dr4\r\n");          # cisco ATA
      append_hf("Alert-info: http://foo.bar/x.wav\r\n");  # snom
  };

  # do forwarding
  if (!t_relay()) {
      sl_reply_error();
  };

  #end of script
  }
		</programlisting>
		</example>
	</section>

	<section>
		<title>Debug TLS connections</title>
	<para>If you want to debug TLS connections, put the following log
	statements into your &osips;.cfg.
	This will dump all available TLS pseudo variables.
	</para>
	<example>
		<title>Example of TLS logging</title>
<programlisting format="linespecific">
xlog("L_INFO","================= start TLS pseudo variables ===============\n");
xlog("L_INFO","$$tls_version                   = '$tls_version'\n");
xlog("L_INFO","$$tls_description               = '$tls_description'\n");
xlog("L_INFO","$$tls_cipher_info               = '$tls_cipher_info'\n");
xlog("L_INFO","$$tls_cipher_bits               = '$tls_cipher_bits'\n");
xlog("L_INFO","$$tls_peer_subject              = '$tls_peer_subject'\n");
xlog("L_INFO","$$tls_peer_issuer               = '$tls_peer_issuer'\n");
xlog("L_INFO","$$tls_my_subject                = '$tls_my_subject'\n");
xlog("L_INFO","$$tls_my_issuer                 = '$tls_my_issuer'\n");
xlog("L_INFO","$$tls_peer_version              = '$tls_peer_version'\n");
xlog("L_INFO","$$tls_my_version                = '$tls_my_version'\n");
xlog("L_INFO","$$tls_peer_serial               = '$tls_peer_serial'\n");
xlog("L_INFO","$$tls_my_serial                 = '$tls_my_serial'\n");
xlog("L_INFO","$$tls_peer_subject_cn           = '$tls_peer_subject_cn'\n");
xlog("L_INFO","$$tls_peer_issuer_cn            = '$tls_peer_issuer_cn'\n");
xlog("L_INFO","$$tls_my_subject_cn             = '$tls_my_subject_cn'\n");
xlog("L_INFO","$$tls_my_issuer_cn              = '$tls_my_issuer_cn'\n");
xlog("L_INFO","$$tls_peer_subject_locality     = '$tls_peer_subject_locality'\n");
xlog("L_INFO","$$tls_peer_issuer_locality      = '$tls_peer_issuer_locality'\n");
xlog("L_INFO","$$tls_my_subject_locality       = '$tls_my_subject_locality'\n");
xlog("L_INFO","$$tls_my_issuer_locality        = '$tls_my_issuer_locality'\n");
xlog("L_INFO","$$tls_peer_subject_country      = '$tls_peer_subject_country'\n");
xlog("L_INFO","$$tls_peer_issuer_country       = '$tls_peer_issuer_country'\n");
xlog("L_INFO","$$tls_my_subject_country        = '$tls_my_subject_country'\n");
xlog("L_INFO","$$tls_my_issuer_country         = '$tls_my_issuer_country'\n");
xlog("L_INFO","$$tls_peer_subject_state        = '$tls_peer_subject_state'\n");
xlog("L_INFO","$$tls_peer_issuer_state         = '$tls_peer_issuer_state'\n");
xlog("L_INFO","$$tls_my_subject_state          = '$tls_my_subject_state'\n");
xlog("L_INFO","$$tls_my_issuer_state           = '$tls_my_issuer_state'\n");
xlog("L_INFO","$$tls_peer_subject_organization = '$tls_peer_subject_organization'\n");
xlog("L_INFO","$$tls_peer_issuer_organization  = '$tls_peer_issuer_organization'\n");
xlog("L_INFO","$$tls_my_subject_organization   = '$tls_my_subject_organization'\n");
xlog("L_INFO","$$tls_my_issuer_organization    = '$tls_my_issuer_organization'\n");
xlog("L_INFO","$$tls_peer_subject_unit         = '$tls_peer_subject_unit'\n");
xlog("L_INFO","$$tls_peer_issuer_unit          = '$tls_peer_issuer_unit'\n");
xlog("L_INFO","$$tls_my_subject_unit           = '$tls_my_subject_unit'\n");
xlog("L_INFO","$$tls_my_issuer_unit            = '$tls_my_issuer_unit'\n");
xlog("L_INFO","$$tls_peer_san_email            = '$tls_peer_san_email'\n");
xlog("L_INFO","$$tls_my_san_email              = '$tls_my_san_email'\n");
xlog("L_INFO","$$tls_peer_san_hostname         = '$tls_peer_san_hostname'\n");
xlog("L_INFO","$$tls_my_san_hostname           = '$tls_my_san_hostname'\n");
xlog("L_INFO","$$tls_peer_san_uri              = '$tls_peer_san_uri'\n");
xlog("L_INFO","$$tls_my_san_uri                = '$tls_my_san_uri'\n");
xlog("L_INFO","$$tls_peer_san_ip               = '$tls_peer_san_ip'\n");
xlog("L_INFO","$$tls_my_san_ip                 = '$tls_my_san_ip'\n");
xlog("L_INFO","$$tls_peer_verified             = '$tls_peer_verified'\n");
xlog("L_INFO","$$tls_peer_revoked              = '$tls_peer_revoked'\n");
xlog("L_INFO","$$tls_peer_expired              = '$tls_peer_expired'\n");
xlog("L_INFO","$$tls_peer_selfsigned           = '$tls_peer_selfsigned'\n");
xlog("L_INFO","$$tls_peer_notBefore            = '$tls_peer_notBefore'\n");
xlog("L_INFO","$$tls_peer_notAfter             = '$tls_peer_notAfter'\n");
xlog("L_INFO","================= end TLS pseudo variables ===============\n");
</programlisting>
	</example>

	</section>



</chapter>
