Browse code

tls_wolfssl: initial docs

S-P Chan authored on 16/06/2022 07:36:17
Showing 8 changed files
... ...
@@ -1,4 +1,4 @@
1
-docs = tls.xml
1
+docs = tls_wolfssl.xml
2 2
 
3 3
 docbook_dir = ../../../../doc/docbook
4 4
 include $(docbook_dir)/Makefile.module
5 5
deleted file mode 100644
... ...
@@ -1,154 +0,0 @@
1
-<?xml version="1.0" encoding='ISO-8859-1'?>
2
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3
-"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
-
5
-<!-- Include general documentation entities -->
6
-<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
7
-%docentities;
8
-
9
-]>
10
-
11
-<section id="tls.certs_howto" xmlns:xi="http://www.w3.org/2001/XInclude">
12
-    <sectioninfo>
13
-    </sectioninfo>
14
-
15
-	<title>Quick Certificate Howto</title>
16
-		<para>
17
-			There are various ways to create, sign certificates and manage small CAs (Certificate Authorities).
18
-			If you are in a hurry and everything you have are the installed OpenSSL libraries and utilities, read on.
19
-		</para>
20
-		<para>
21
-			Assumptions: we run our own CA.
22
-		</para>
23
-		<para>
24
-			Warning: in this example no key is encrypted. The client and server private keys must not be encrypted
25
-			(&kamailio; doesn't support encrypted keys), so make sure the corresponding files are readable only by
26
-			trusted people. You should use a password to protect your CA private key.
27
-		</para>
28
-		<para>
29
-		<programlisting>
30
-Assumptions
31
-
32
-The default openssl configuration (usually /etc/ssl/openssl.cnf)
33
-default_ca section is the one distributed with openssl and uses the default
34
-directories:
35
-
36
-...
37
-
38
-default_ca      = CA_default            # The default ca section
39
-
40
-[ CA_default ]
41
-
42
-dir             = ./demoCA              # Where everything is kept
43
-certs           = $dir/certs            # Where the issued certs are kept
44
-crl_dir         = $dir/crl              # Where the issued crl are kept
45
-database        = $dir/index.txt        # database index file.
46
-#unique_subject = no                    # Set to 'no' to allow creation of
47
-                                        # several certificates with same subject.
48
-new_certs_dir   = $dir/newcerts         # default place for new certs.
49
-
50
-certificate     = $dir/cacert.pem       # The CA certificate
51
-serial          = $dir/serial           # The current serial number
52
-crlnumber       = $dir/crlnumber        # the current CRL number
53
-crl             = $dir/crl.pem          # The current CRL
54
-private_key     = $dir/private/cakey.pem# The private key
55
-RANDFILE        = $dir/private/.rand    # private random number file
56
-
57
-...
58
-
59
-If this is not the case create a new OpenSSL config file that uses the above
60
-paths for the default CA and add to all the openssl commands:
61
- -config filename. E.g.:
62
-	openssl ca -config my_openssl.cnf -in kamailio1_cert_req.pem -out kamailio1_cert.pem
63
-
64
-
65
-Creating the CA certificate
66
-1. Create the CA directory
67
-	mkdir ca
68
-	cd ca
69
-	
70
-2. Create the CA directory structure and files  (see ca(1))
71
-	mkdir demoCA 		#default CA name, edit /etc/ssl/openssl.cnf
72
-	mkdir  demoCA/private
73
-	mkdir demoCA/newcerts
74
-	touch demoCA/index.txt
75
-	echo 01 >demoCA/serial
76
-	echo 01 >demoCA/crlnumber
77
-	
78
-2. Create CA private key
79
-	openssl genrsa -out demoCA/private/cakey.pem 2048
80
-	chmod 600 demoCA/private/cakey.pem
81
-	
82
-3. Create CA self-signed certificate
83
-	openssl req -out demoCA/cacert.pem   -x509 -new -key demoCA/private/cakey.pem
84
-
85
-
86
-Creating a server/client TLS certificate
87
-1. Create a certificate request (and its private key in privkey.pem)
88
-
89
-	openssl req -out kamailio1_cert_req.pem -new -nodes
90
-
91
-	WARNING: the organization name should be the same as in the CA certificate.
92
-	
93
-2. Sign it with the CA certificate
94
-	openssl ca -in kamailio1_cert_req.pem -out kamailio1_cert.pem
95
-	
96
-3. Copy kamailio1_cert.pem to your &kamailio; configuration dir
97
-
98
-
99
-Setting &kamailio; to use the TLS certificate
100
-1. Create the CA list file:
101
-	for each of your CA certificates that you intend to use do:
102
-		cat cacert.pem >>calist.pem
103
-	
104
-2. Copy your &kamailio; certificate, private key and ca list file to your 
105
-	intended machine (preferably in your &kamailio; configuration directory,
106
-	 this is the default place &kamailio; searches for).
107
-	
108
-3. Set up &kamailio;.cfg to use the certificate
109
-	if your &kamailio; certificate name is different from cert.pem or it is not
110
-	placed in &kamailio; cfg. directory, add to your kamailio.cfg:
111
-		modparam("tls", "certificate", "/path/cert_file_name")
112
-	
113
-4. Set up &kamailio; to use the private key
114
-	if your private key is not contained in the same file as the certificate
115
-	(or the certificate name is not the default cert.pem), add to your
116
-	 &kamailio;.cfg:
117
-		modparam("tls", "private_key", "/path/private_key_file")
118
-	
119
-5. Set up &kamailio; to use the CA list (optional)
120
-   The CA list is not used for your server certificate - it's used to approve other servers
121
-   and clients connecting to your server with a client certificate or for approving
122
-   a certificate used by a server your server connects to.
123
-	add to your &kamailio;.cfg:
124
-		modparam("tls", "ca_list", "/path/ca_list_file")
125
-	
126
-6. Set up TLS authentication options:
127
-		modparam("tls", "verify_certificate", 1)
128
-		modparam("tls", "require_certificate", 1) 
129
-	(for more information see the module parameters documentation)
130
-
131
-
132
-Revoking a certificate and using a CRL
133
-1. Revoking a certificate:
134
-	openssl ca -revoke bad_cert.pem
135
-	
136
-2. Generate/update the certificate revocation list:
137
-	openssl ca -gencrl -out my_crl.pem
138
-	
139
-3. Copy my_crl.pem to your &kamailio; config. dir
140
-	
141
-4. Set up &kamailio; to use the CRL:
142
-		modparam("tls", "crl", "path/my_crl.pem")
143
-
144
-
145
-		</programlisting>
146
-		</para>
147
-
148
-
149
-</section>
150 0
deleted file mode 100644
... ...
@@ -1,38 +0,0 @@
1
-<?xml version="1.0" encoding='ISO-8859-1'?>
2
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3
-"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
-
5
-<!-- Include general documentation entities -->
6
-<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
7
-%docentities;
8
-
9
-]>
10
-
11
-<section id="tls.status">
12
-	<title>Status</title>
13
-	<section id="tls.license">
14
-	<title>License</title>
15
-		<para>
16
-			Most of the code for this module has been released under BSD by
17
-			iptelorg. The GPL parts are released with an exception to link
18
-			with OpenSSL toolkit software components.
19
-		</para>
20
-	</section>
21
-	<section id="tls.history">
22
-	<title>History</title>
23
-		<para>
24
-			For version 3.1 most of the TLS specific code was completely
25
-			re-written to add support for asynchronous TLS and fix several
26
-			long standing bugs.
27
-		</para>
28
-		<para>
29
-			The code is currently maintained by Andrei Pelinescu-Onciul
30
-			<email>andrei@iptel.org</email>.
31
-		</para>
32
-		<para>
33
-			Install does not generate self-signed certificates by default
34
-			anymore. In order to generate them now you should do
35
-			"make install-tls-cert"
36
-		</para>
37
-	</section>
38
-</section>
39 0
deleted file mode 100644
... ...
@@ -1,64 +0,0 @@
1
-<?xml version="1.0" encoding='ISO-8859-1'?>
2
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3
-"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
-
5
-<!-- Include general documentation entities -->
6
-<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
7
-%docentities;
8
-
9
-]>
10
-
11
-<section id="tls.hsm_howto" xmlns:xi="http://www.w3.org/2001/XInclude">
12
-    <sectioninfo>
13
-    </sectioninfo>
14
-
15
-	<title>HSM Howto</title>
16
-		<para>
17
-			This documents OpenSSL engine support for private keys in HSM. 
18
-		</para>
19
-		<para>
20
-		        Assumptions: an OpenSSL engine configured with private key. We still require the certificate file
21
-			and list of CA certificates per a regular TLS configuration.
22
-		</para>
23
-		<para>
24
-		<programlisting>
25
-Thales Luna Example
26
-
27
-...
28
-# Example for Thales Luna
29
-modparam("tls", "engine", "gem")
30
-modparam("tls", "engine_config", "/usr/local/etc/kamailio/thales.cnf")
31
-modparam("tls", "engine_algorithms", "EC")
32
-...
33
-
34
-/usr/local/etc/kamailio/thales.cnf is a OpenSSL config format file used to
35
-bootstrap the engine, e.g., pass the PIN.
36
-
37
-...
38
-# the key kamailio is mandatory
39
-kamailio = openssl_init
40
-
41
-[ openssl_init ]
42
-engines = engine_section
43
-
44
-[ engine_section ]
45
-# gem is the name of the Thales Luna OpenSSL engine
46
-gem = gem_section
47
-
48
-[ gem_section ]
49
-# from Thales documentation
50
-dynamic_path = /usr/lib64/engines-1.1/gem.so
51
-ENGINE_INIT = 0:20:21:password=1234-ABCD-5678-EFGH
52
-...
53
-
54
-
55
-Thales nShield Connect
56
-
57
-Place holder
58
-		</programlisting>
59
-		</para>
60
-
61
-
62
-</section>
63 0
deleted file mode 100644
... ...
@@ -1,1410 +0,0 @@
1
-<?xml version="1.0" encoding="UTF-8"?>
2
-<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3
-		"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
4
-	[<!-- Include general documentation entities -->
5
-	 <!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
6
-	 %docentities;
7
-	]
8
->
9
-
10
-<section id="tls.parameters">
11
-    <sectioninfo>
12
-    </sectioninfo>
13
-
14
-    <title>Parameters</title>
15
-
16
-	<section id="tls.p.tls_method">
17
-	<title><varname>tls_method</varname> (string)</title>
18
-	<para>
19
-		Sets the TLS protocol method. Possible values are:
20
-	</para>
21
-	<itemizedlist>
22
-			<listitem>
23
-				<para>
24
-				<emphasis>TLSv1.2+</emphasis> - TLSv1.2 or newer (TLSv1.3, ...)
25
-				connections are accepted (available starting with openssl/libssl v1.1.1)
26
-				</para>
27
-			</listitem>
28
-			<listitem>
29
-				<para>
30
-				<emphasis>TLSv1.2</emphasis> - only TLSv1.2 connections are accepted
31
-				(available starting with openssl/libssl v1.0.1e)
32
-				</para>
33
-			</listitem>
34
-			<listitem>
35
-				<para>
36
-				<emphasis>TLSv1.1+</emphasis> - TLSv1.1 or newer (TLSv1.2, ...)
37
-				connections are accepted (available starting with openssl/libssl v1.0.1)
38
-				</para>
39
-			</listitem>
40
-			<listitem>
41
-				<para>
42
-				<emphasis>TLSv1.1</emphasis> - only TLSv1.1 connections are accepted
43
-				(available starting with openssl/libssl v1.0.1)
44
-				</para>
45
-			</listitem>
46
-			<listitem>
47
-				<para>
48
-				<emphasis>TLSv1+</emphasis> - TLSv1.0 or newer (TLSv1.1, TLSv1.2, ...)
49
-				connections are accepted.
50
-				</para>
51
-			</listitem>
52
-			<listitem>
53
-				<para>
54
-				<emphasis>TLSv1</emphasis> - only TLSv1 (TLSv1.0) connections are
55
-				accepted. This is the default value.
56
-				</para>
57
-			</listitem>
58
-			<listitem>
59
-				<para>
60
-				<emphasis>SSLv3</emphasis> - only SSLv3 connections are accepted.
61
-				Note: you shouldn't use SSLv3 for anything which should be secure.
62
-				</para>
63
-			</listitem>
64
-			<listitem>
65
-				<para>
66
-				<emphasis>SSLv2</emphasis> - only SSLv2 connections, for old clients.
67
-				Note: you shouldn't use SSLv2 for anything which should be secure.
68
-				Newer versions of OpenSSL libraries don't include support for it anymore.
69
-				</para>
70
-			</listitem>
71
-			<listitem>
72
-				<para>
73
-				<emphasis>SSLv23</emphasis> - any of the SSLv2, SSLv3 and TLSv1 or
74
-				newer methods will be accepted.
75
-				</para>
76
-				<para>
77
-				From the OpenSSL manual: "A TLS/SSL connection established with these
78
-				methods may understand the SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols.
79
-				If extensions are required (for example server name) a client will
80
-				send out TLSv1 client hello messages including extensions and will
81
-				indicate that it also understands TLSv1.1, TLSv1.2 and permits a
82
-				fallback to SSLv3. A server will support SSLv3, TLSv1, TLSv1.1
83
-				and TLSv1.2 protocols. This is the best choice when compatibility
84
-				is a concern."
85
-				</para>
86
-				<para>
87
-				Note: For older OpenSSL library versions, this option allows SSLv2, with hello
88
-				messages done over SSLv2. You shouldn't use SSLv2 or SSLv3 for anything
89
-				which should be secure.
90
-				</para>
91
-			</listitem>
92
-	</itemizedlist>
93
-	<para>
94
-		If RFC 3261 conformance is desired, at least TLSv1 must be used. For
95
-		compatibility with older clients SSLv23 is the option, but again, be aware
96
-		of security concerns, SSLv2/3 being considered very insecure by 2014.
97
-		For current information about what's considered secure, please consult,
98
-		IETF BCP 195, currently RFC 7525  - "Recommendations for Secure Use of 
99
-		Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)"
100
-	</para>
101
-	<example>
102
-	    <title>Set <varname>tls_method</varname> parameter</title>
103
-	    <programlisting>
104
-...
105
-modparam("tls", "tls_method", "TLSv1")
106
-...
107
-	    </programlisting>
108
-	</example>
109
-	</section>
110
-
111
-	<section id="tls.p.certificate">
112
-	<title><varname>certificate</varname> (string)</title>
113
-	<para>
114
-		Sets the certificate file name. The certificate file can also contain
115
-		the private key in PEM format.
116
-	</para>
117
-	<para>
118
-		If the file name starts with a '.' the path will be relative to the
119
-		working directory (<emphasis>at runtime</emphasis>). If it starts
120
-		with a '/' it will be an absolute path and if it starts with anything
121
-		else the path will be relative to the main config file directory
122
-		(e.g.: for kamailio -f /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).
123
-	</para>
124
-	<para>
125
-		The default value is &kamailioconfdir;/cert.pem
126
-	</para>
127
-	<example>
128
-	    <title>Set <varname>certificate</varname> parameter</title>
129
-	    <programlisting>
130
-...
131
-modparam("tls", "certificate", "/usr/local/etc/kamailio/my_certificate.pem")
132
-...
133
-	    </programlisting>
134
-	</example>
135
-	</section>
136
-
137
-	<section id="tls.p.private_key">
138
-	<title><varname>private_key</varname> (string)</title>
139
-	<para>
140
-		Sets the private key file name. The private key can be in the same
141
-		file as the certificate or in a separate file, specified by this
142
-		configuration parameter.
143
-	</para>
144
-	<para>
145
-		If the file name starts with a '.' the path will be relative to the
146
-		working directory (<emphasis>at runtime</emphasis>). If it starts
147
-		with a '/' it will be an absolute path and if it starts with anything
148
-		else the path will be relative to the main config file directory
149
-		(e.g.: for kamailio -f /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).
150
-	</para>
151
-	<para>
152
-		Note: the private key can be contained in the same file as the
153
-		certificate (just append it to the certificate file, e.g.:
154
-		cat pkey.pem &gt;&gt; cert.pem)
155
-	</para>
156
-	<para>
157
-		The default value is &kamailioconfdir;/cert.pem
158
-	</para>
159
-	<example>
160
-	    <title>Set <varname>private_key</varname> parameter</title>
161
-	    <programlisting>
162
-...
163
-modparam("tls", "private_key", "/usr/local/etc/kamailio/my_pkey.pem")
164
-...
165
-	    </programlisting>
166
-	</example>
167
-	</section>
168
-
169
-	<section id="tls.p.ca_list">
170
-	<title><varname>ca_list</varname> (string)</title>
171
-	<para>
172
-		Sets the CA list file name. This file contains a list of all the
173
-		trusted CAs certificates used when connecting to other SIP implementations.
174
-		If a signature in a certificate chain belongs
175
-		to one of the listed CAs, the verification of that certificate will succeed.
176
-	</para>
177
-	<para>
178
-		If the file name starts with a '.' the path will be relative to the
179
-		working directory (<emphasis>at runtime</emphasis>). If it starts
180
-		with a '/' it will be an absolute path and if it starts with anything
181
-		else the path will be relative to the main config file directory
182
-		(e.g.: for kamailio -f /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).
183
-	</para>
184
-	<para>
185
-		By default the CA file is not set.
186
-	</para>
187
-	<para>
188
-		An easy way to create the CA list is to append each trusted trusted CA
189
-		certificate in the PEM format to one file, e.g.:
190
-	    <programlisting>
191
-for f in trusted_cas/*.pem ; do cat "$f" &gt;&gt; ca_list.pem ; done 
192
-	    </programlisting>
193
-	</para>
194
-	<para>
195
-		See also
196
-		<emphasis>verify_certificate</emphasis>,
197
-		<emphasis>verify_depth</emphasis>,
198
-		<emphasis>require_certificate</emphasis> and
199
-		<emphasis>crl</emphasis>.
200
-	</para>
201
-	<example>
202
-	    <title>Set <varname>ca_list</varname> parameter</title>
203
-	    <programlisting>
204
-...
205
-modparam("tls", "ca_list", "/usr/local/etc/kamailio/ca_list.pem")
206
-...
207
-	    </programlisting>
208
-	</example>
209
-	</section>
210
-
211
-	<section id="tls.p.ca_path">
212
-	<title><varname>ca_path</varname> (str)</title>
213
-	<para>
214
-		Sets the path with the trusted CA files, to be given as parameter
215
-		SSL_CTX_load_verify_locations(). The certificates in ca_path are only
216
-		looked up when required, e.g. when building the certificate chain
217
-		or when actually performing the verification of a peer certificate. They
218
-		are not given to the client (not loaded to be provided to
219
-		SSL_CTX_set_client_CA_list()), only the ones in ca_list files are sent
220
-		to the client. It requires to use c_rehash to generate the hash map
221
-		for certificate search, for more see the manual of libssl for
222
-		SSL_CTX_load_verify_locations() function.
223
-	</para>
224
-	<para>
225
-		By default it is not set.
226
-	</para>
227
-	<example>
228
-	    <title>Set <varname>ca_path</varname> parameter</title>
229
-	    <programlisting>
230
-...
231
-modparam("tls", "ca_path", "/usr/local/etc/kamailio/ca")
232
-...
233
-	    </programlisting>
234
-	</example>
235
-	</section>
236
-
237
-	<section id="tls.p.crl">
238
-	<title><varname>crl</varname> (string)</title>
239
-	<para>
240
-		Sets the certificate revocation list (CRL) file name. This file contains a
241
-		list of revoked certificates. Any attempt to verify a revoked
242
-		certificate will fail.
243
-	</para>
244
-	<para>
245
-		If not set, no CRL list will be used.
246
-	</para>
247
-	<para>
248
-		If the file name starts with a '.' the path will be relative to the
249
-		working directory (<emphasis>at runtime</emphasis>). If it starts
250
-		with a '/' it will be an absolute path and if it starts with anything
251
-		else the path will be relative to the main config file directory
252
-		(e.g.: for kamailio -f /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).
253
-	</para>
254
-	<note><para>
255
-		If set, <varname>require_certificate</varname> should also be set
256
-		or it will not have any effect.
257
-	</para></note>
258
-	<para>
259
-		By default the CRL file name is not set.
260
-	</para>
261
-	<para>
262
-		To update the CRL in a running &kamailio;, make sure you configure TLS
263
-		via a separate TLS config file
264
-		(the <varname>config</varname> modparam) and issue a tls.reload
265
-		RPC call, e.g.:
266
-		<programlisting>
267
- $ &sercmd; tls.reload
268
-		</programlisting>
269
-	</para>
270
-	<para>
271
-		A quick way to create the CRL in PEM format, using OpenSSL is:
272
-		<programlisting>
273
- $ openssl ca -gencrl -keyfile cacert.key -cert cacert.pem -out my_crl.pem
274
-		</programlisting>
275
-		 my_crl.pem will contain the signed list of the revoked certificates.
276
-	</para>
277
-	<para>
278
-		To revoke a TLS certificate use something like:
279
-		<programlisting>
280
- $ openssl ca -revoke bad_cert.pem -keyfile cacert.key -cert cacert.pem
281
-		</programlisting>
282
-		and then refresh the crl file using the command above.
283
-	</para>
284
-	<para>
285
-		To display the CRL contents use:
286
-		<programlisting>
287
- $ openssl crl -in crl.pem -noout -text
288
-		</programlisting>
289
-	</para>
290
-	<para>
291
-		See also
292
-		<emphasis>ca_list</emphasis>,
293
-		<emphasis>verify_certificate</emphasis>,
294
-		<emphasis>verify_depth</emphasis> and
295
-		<emphasis>require_certificate</emphasis>.
296
-	</para>
297
-	<example>
298
-	    <title>Set <varname>crl</varname> parameter</title>
299
-	    <programlisting>
300
-...
301
-modparam("tls", "crl", "/usr/local/etc/kamailio/crl.pem")
302
-...
303
-	    </programlisting>
304
-	</example>
305
-	</section>
306
-
307
-<section id="tls.p.verify_certificate">
308
-	<title><varname>verify_certificate</varname> (boolean)</title>
309
-	<para>
310
-		If enabled it will force certificate verification when connecting to 
311
-		other SIP servers..
312
-		For more information see the
313
-		<ulink url="https://www.openssl.org/docs/manmaster/man1/verify.html">verify(1)</ulink>
314
-		OpenSSL man page.
315
-	</para>
316
-	<para>
317
-		Note: the certificate verification will always fail if the ca_list is empty.
318
-	</para>
319
-	<para>
320
-		See also: <varname>ca_list</varname>, <varname>require_certificate</varname>, <varname>verify_depth</varname>.
321
-	</para>
322
-	<para>
323
-		By default the certificate verification is off.
324
-	</para>
325
-	<example>
326
-	    <title>Set <varname>verify_certificate</varname> parameter</title>
327
-	    <programlisting>
328
-...
329
-modparam("tls", "verify_certificate", 1)
330
-...
331
-	    </programlisting>
332
-	</example>
333
-	</section>
334
-
335
-<section id="tls.p.verify_depth">
336
-	<title><varname>verify_depth</varname> (integer)</title>
337
-	<para>
338
-		Sets how far up the certificate chain will the certificate verification go in the search for a trusted CA.
339
-	</para>
340
-	<para>
341
-		See also: <varname>ca_list</varname>, <varname>require_certificate</varname>, <varname>verify_certificate</varname>,
342
-	</para>
343
-	<para>
344
-		The default value is 9.
345
-	</para>
346
-	<example>
347
-	    <title>Set <varname>verify_depth</varname> parameter</title>
348
-	    <programlisting>
349
-...
350
-modparam("tls", "verify_depth", 9)
351
-...
352
-	    </programlisting>
353
-	</example>
354
-	</section>
355
-
356
-<section id="tls.p.require_certificate">
357
-	<title><varname>require_certificate</varname> (boolean)</title>
358
-	<para>
359
-		When enabled &kamailio; will require a certificate from a client
360
-		connecting to the TLS port. If the client does not offer a certificate
361
-		and <varname>verify_certificate</varname> is on, certificate verification will fail.
362
-	</para>
363
-	<para>
364
-		The default value is off.
365
-	</para>
366
-	<example>
367
-	    <title>Set <varname>require_certificate</varname> parameter</title>
368
-	    <programlisting>
369
-...
370
-modparam("tls", "require_certificate", 1)
371
-...
372
-	    </programlisting>
373
-	</example>
374
-	</section>
375
-
376
-<section id="tls.p.cipher_list">
377
-	<title><varname>cipher_list</varname> (string)</title>
378
-	<para>
379
-		Sets the list of accepted ciphers. The list consists of cipher strings separated by colons.
380
-		For more information on the cipher list format see the
381
-		<ulink url="https://www.openssl.org/docs/manmaster/man1/ciphers.html">
382
-		cipher(1)</ulink> OpenSSL man page.
383
-	</para>
384
-	<para>
385
-		The default value is not set (all the OpenSSL supported ciphers are enabled).
386
-	</para>
387
-	<example>
388
-	    <title>Set <varname>cipher_list</varname> parameter</title>
389
-	    <programlisting>
390
-...
391
-modparam("tls", "cipher_list", "HIGH")
392
-...
393
-	    </programlisting>
394
-	</example>
395
-	</section>
396
-
397
-	<section id="tls.p.server_name">
398
-	<title><varname>server_name</varname> (string)</title>
399
-	<para>
400
-		Sets the Server Name Indication (SNI) value.
401
-	</para>
402
-	<para>
403
-		This is a TLS extension enabling one TLS server to serve multiple host
404
-		names with unique certificates.
405
-	</para>
406
-	<para>
407
-		The default value is empty (not set).
408
-	</para>
409
-	<example>
410
-	    <title>Set <varname>server_name</varname> parameter</title>
411
-	    <programlisting>
412
-...
413
-modparam("tls", "server_name", "kamailio.org")
414
-...
415
-	    </programlisting>
416
-	</example>
417
-	</section>
418
-
419
-	<section id="tls.p.connection_timeout">
420
-	<title><varname>connection_timeout</varname> (int)</title>
421
-	<para>
422
-		Sets the amount of time after which an idle TLS connection will be
423
-		closed, if no I/O ever occurred after the initial open. If an I/O event
424
-		occurs, the timeout will be extended with tcp_connection_lifetime.
425
-		The value is expressed in seconds.
426
-	</para>
427
-	<para>
428
-		The default value is 10 min.
429
-	</para>
430
-	<para>
431
-		If the value set is -1, the connection will never be close on idle.
432
-	</para>
433
-	<para>
434
-		This setting can be changed also at runtime, via the RPC interface and config
435
-		framework. The config variable name is
436
-		<emphasis>tls.connection_timeout</emphasis>.
437
-	</para>
438
-	<example>
439
-	    <title>Set <varname>connection_timeout</varname> parameter</title>
440
-	    <programlisting>
441
-...
442
-modparam("tls", "connection_timeout", 60)
443
-...
444
-	    </programlisting>
445
-	</example>
446
-	<example>
447
-		<title>Set <varname>tls.connection_timeout</varname> at runtime</title>
448
-		<programlisting>
449
- $ &sercmd; cfg.set_now_int tls connection_timeout 180
450
-		</programlisting>
451
-	</example>
452
-	</section>
453
-
454
-	<section id="tls.p.tls_disable_compression">
455
-	<title><varname>tls_disable_compression</varname> (boolean)</title>
456
-	<para>
457
-		If set compression over TLS will be disabled.
458
-		Note that compression uses a lot of memory (about 10x more then with
459
-		the compression disabled), so if you want to minimize
460
-		memory usage is a good idea to disable it. TLS compression also 
461
-		expose you for the 
462
- 		<ulink url="https://en.wikipedia.org/wiki/CRIME_(security_exploit)">
463
-		CRIME</ulink> security vulnerability.
464
-	</para>
465
-	<para>
466
-		By default TLS compression is disabled.
467
-	</para>
468
-	<example>
469
-	    <title>Set <varname>tls_disable_compression</varname> parameter</title>
470
-	    <programlisting>
471
-...
472
-modparam("tls", "tls_disable_compression", 0) # enable
473
-...
474
-	    </programlisting>
475
-	</example>
476
-	</section>
477
-
478
-
479
-<section id="tls.p.ssl_release_buffers">
480
-	<title><varname>ssl_release_buffers</varname> (integer)</title>
481
-	<para>
482
-		Release internal OpenSSL read or write buffers as soon as they are
483
-		no longer needed. Combined with
484
-		<varname>ssl_freelist_max_len</varname> has the potential of saving
485
-		a lot of memory ( ~ 32k per connection in the default configuration,
486
-		or 16k + <varname>ssl_max_send_fragment</varname>).
487
-		For &kamailio; versions &gt; 3.0 it makes little sense to disable it (0)
488
-		since the tls module already has its own internal buffering.
489
-	</para>
490
-	<para>
491
-		A value of -1 would not change this option from its openssl default.
492
-		Use 0 or 1 for enable/disable.
493
-	</para>
494
-	<para>
495
-		By default the value is 1 (enabled).
496
-	</para>
497
-	<note>
498
-		<para>
499
-			This option is supported only for
500
-			OpenSSL versions >= <emphasis>1.0.0</emphasis>.
501
-			On all the other versions attempting
502
-			to change the default will trigger an error.
503
-		</para>
504
-	</note>
505
-	<example>
506
-	    <title>Set <varname>ssl_release_buffers</varname> parameter</title>
507
-	    <programlisting>
508
-modparam("tls", "ssl_release_buffers", 1)
509
-	    </programlisting>
510
-	</example>
511
-	</section>
512
-
513
-
514
-<section id="tls.p.ssl_freelist_max_len">
515
-	<title><varname>ssl_freelist_max_len</varname> (integer)</title>
516
-	<para>
517
-		Sets the maximum number of free memory chunks, that OpenSSL will keep
518
-		per connection. Setting it to 0 would cause any unused memory chunk
519
-		to be immediately freed, reducing the memory footprint. A too large
520
-		value would result in extra memory consumption.
521
-	</para>
522
-	<para>
523
-		Should be combined with <varname>ssl_release_buffers</varname>.
524
-	</para>
525
-	<para>
526
-		A value of -1 has a special meaning: the OpenSSL default will be used
527
-		(no attempt on changing the value will be made). For OpenSSL 1.0
528
-		the internal default is 32.
529
-	</para>
530
-	<para>
531
-		By default the value is 0 (no freelist).
532
-	</para>
533
-	<note>
534
-		<para>
535
-			This option is supported only for
536
-			OpenSSL versions >= <emphasis>1.0.0</emphasis>.
537
-			On all the other versions attempting
538
-			to change the default will trigger an error.
539
-		</para>
540
-	</note>
541
-	<example>
542
-		<title>Set <varname>ssl_freelist_max_len</varname> parameter</title>
543
-		<programlisting>
544
-modparam("tls", "ssl_freelist_max_len", 0)
545
-		</programlisting>
546
-	</example>
547
-	</section>
548
-
549
-
550
-<section id="tls.p.ssl_max_send_fragment">
551
-	<title><varname>ssl_max_send_fragment</varname> (integer)</title>
552
-	<para>
553
-		Sets the maximum number of bytes (from the clear text) sent into
554
-		one TLS record. Valid values are between 512 and 16384.
555
-		Note however that even valid low values might not be big enough to
556
-		allow a successful handshake (try minimum 1024).
557
-	</para>
558
-	<para>
559
-		Lower values would lead to less memory usage, but values lower then
560
-		the typical &kamailio; write size would incur a slight performance
561
-		penalty. Good values are bigger then the  size of the biggest
562
-		SIP packet one normally expects to forward. For example in most
563
-		setups 2048 would be a good value.
564
-	</para>
565
-	<note>
566
-		<para>
567
-			Values on the lower side, even if valid (> 512), might not allow
568
-			for a successful initial handshake. This happens if the
569
-			certificate does not fit inside one send fragment.
570
-			Values lower then 1024 should not be used.
571
-			Even with higher values, if the handshake fails,
572
-			try increasing the value.
573
-		</para>
574
-	</note>
575
-	<para>
576
-		A value of -1 has a special meaning: the OpenSSL default will be used
577
-		(no attempt on changing the value will be made).
578
-	</para>
579
-	<para>
580
-		By default the value is -1 (the OpenSSL default, which at least in
581
-		OpenSSL 1.0.0 is ~ 16k).
582
-	</para>
583
-	<note>
584
-		<para>
585
-			This option is supported only for
586
-			OpenSSL versions >= <emphasis>0.9.9</emphasis>.
587
-			On all the other versions attempting
588
-			to change the default will trigger an error.
589
-		</para>
590
-	</note>
591
-	<example>
592
-		<title>Set <varname>ssl_max_send_fragment</varname> parameter</title>
593
-		<programlisting>
594
-modparam("tls", "ssl_max_send_fragment", 4096)
595
-		</programlisting>
596
-	</example>
597
-	</section>
598
-
599
-
600
-<section id="tls.p.ssl_read_ahead">
601
-	<title><varname>ssl_read_ahead</varname> (boolean)</title>
602
-	<para>
603
-		Enables read ahead, reducing the number of internal OpenSSL BIO read()
604
-		calls. This option has only debugging value, in normal circumstances
605
-		it should not be changed from the default.
606
-	</para>
607
-	<para>
608
-		When disabled OpenSSL will make at least 2 BIO read() calls per
609
-		received record: one to get the record header and one to get the
610
-		rest of the record.
611
-	</para>
612
-	<para>
613
-		The TLS module buffers internally all read()s and defines its own fast
614
-		BIO so enabling this option would only cause more memory consumption
615
-		and a minor slow-down (extra memcpy).
616
-	</para>
617
-	<para>
618
-		A value of -1 has a special meaning: the OpenSSL default will be used
619
-		(no attempt on changing the value will be made).
620
-	</para>
621
-	<para>
622
-		By default the value is 0 (disabled).
623
-	</para>
624
-	<example>
625
-		<title>Set <varname>ssl_read_ahead</varname> parameter</title>
626
-		<programlisting>
627
-modparam("tls", "ssl_read_ahead", 1)
628
-		</programlisting>
629
-	</example>
630
-	</section>
631
-
632
-
633
-	<section id="tls.p.send_close_notify">
634
-	<title><varname>send_close_notify</varname> (boolean)</title>
635
-	<para>
636
-		Enables/disables sending close notify alerts prior to closing the
637
-		corresponding TCP connection.  Sending the close notify prior to TCP
638
-		shutdown is "nicer" from a TLS point of view, but it has a measurable
639
-		performance impact. Default: off. Can be set at runtime
640
-		(tls.send_close_notify).
641
-	</para>
642
-	<para>
643
-		The default value is 0 (off).
644
-	</para>
645
-	<para>
646
-		It can be changed also at runtime, via the RPC interface and config
647
-		framework. The config variable name is tls.send_close_notify.
648
-	</para>
649
-	<example>
650
-	    <title>Set <varname>send_close_notify</varname> parameter</title>
651
-	    <programlisting>
652
-...
653
-modparam("tls", "send_close_notify", 1)
654
-...
655
-	    </programlisting>
656
-	</example>
657
-	<example>
658
-		<title>Set <varname>tls.send_close_notify</varname> at runtime</title>
659
-		<programlisting>
660
- $ &sercmd; cfg.set_now_int tls send_close_notify 1
661
-		</programlisting>
662
-	</example>
663
-	</section>
664
-
665
-
666
-	<section id="tls.p.con_ct_wq_max">
667
-	<title><varname>con_ct_wq_max</varname> (integer)</title>
668
-	<para>
669
-		Sets the maximum allowed per connection clear-text send queue size in
670
-		bytes. This queue is used when data cannot be encrypted and sent
671
-		immediately because of an ongoing TLS level renegotiation.
672
-	</para>
673
-	<para>
674
-		The default value is 65536 (64 Kb).
675
-	</para>
676
-	<para>
677
-		It can be changed also at runtime, via the RPC interface and config
678
-		framework. The config variable name is tls.con_ct_wq_max.
679
-	</para>
680
-	<example>
681
-	    <title>Set <varname>con_ct_wq_max</varname> parameter</title>
682
-	    <programlisting>
683
-...
684
-modparam("tls", "con_ct_wq_max", 1048576)
685
-...
686
-	    </programlisting>
687
-	</example>
688
-	<example>
689
-		<title>Set <varname>tls.con_ct_wq_max</varname> at runtime</title>
690
-		<programlisting>
691
- $ &sercmd; cfg.set_now_int tls con_ct_wq_max 1048576
692
-		</programlisting>
693
-	</example>
694
-	</section>
695
-
696
-
697
-	<section id="tls.p.ct_wq_max">
698
-	<title><varname>ct_wq_max</varname> (integer)</title>
699
-	<para>
700
-		Sets the maximum total number of bytes queued in all the clear-text
701
-		send queues.  These queues are used when data cannot be encrypted and
702
-		sent immediately because of an ongoing TLS level renegotiation.
703
-	</para>
704
-	<para>
705
-		The default value is 10485760 (10 Mb).
706
-	</para>
707
-	<para>
708
-		It can be changed also at runtime, via the RPC interface and config
709
-		framework. The config variable name is <varname>tls.ct_wq_max</varname>.
710
-	</para>
711
-	<example>
712
-	    <title>Set <varname>ct_wq_max</varname> parameter</title>
713
-	    <programlisting>
714
-...
715
-modparam("tls", "ct_wq_max", 4194304)
716
-...
717
-	    </programlisting>
718
-	</example>
719
-	<example>
720
-		<title>Set <varname>tls.ct_wq_max</varname> at runtime</title>
721
-		<programlisting>
722
- $ &sercmd; cfg.set_now_int tls ct_wq_max 4194304
723
-		</programlisting>
724
-	</example>
725
-	</section>
726
-
727
-
728
-	<section id="tls.p.ct_wq_blk_size">
729
-	<title><varname>ct_wq_blk_size</varname> (integer)</title>
730
-	<para>
731
-		Minimum block size for the internal clear-text send queues
732
-		(debugging / advanced tuning).
733
-		Good values are multiple of typical datagram sizes.
734
-	</para>
735
-	<para>
736
-		The default value is 4096.
737
-	</para>
738
-	<para>
739
-		It can be changed also at runtime, via the RPC interface and config
740
-		framework. The config variable name is <varname>tls.ct_wq_blk_size</varname>.
741
-	</para>
742
-	<example>
743
-	    <title>Set <varname>ct_wq_blk_size</varname> parameter</title>
744
-	    <programlisting>
745
-...
746
-modparam("tls", "ct_wq_blk_size", 2048)
747
-...
748
-	    </programlisting>
749
-	</example>
750
-	<example>
751
-		<title>Set <varname>tls.ct_wq_max</varname> at runtime</title>
752
-		<programlisting>
753
- $ &sercmd; cfg.set_now_int tls ct_wq_blk_size 2048
754
-		</programlisting>
755
-	</example>
756
-	</section>
757
-
758
-
759
-	<section id="tls.p.tls_log">
760
-	<title><varname>tls_log</varname> (int)</title>
761
-	<para>
762
-		Sets the log level at which TLS related messages will be logged.
763
-	</para>
764
-	<para>
765
-		The default value is 3 (L_DBG).
766
-	</para>
767
-	<para>
768
-		It can be changed also at runtime, via the RPC interface and config
769
-		framework. The config variable name is <varname>tls.log</varname>.
770
-	</para>
771
-	<example>
772
-		<title>Set <varname>tls_log</varname> parameter</title>
773
-		<programlisting>
774
-...
775
-# ignore TLS messages if Kamailio is started with debug less than 10
776
-modparam("tls", "tls_log", 10)
777
-...
778
-		</programlisting>
779
-	</example>
780
-	<example>
781
-		<title>Set <varname>tls.log</varname> at runtime</title>
782
-		<programlisting>
783
- $ &sercmd; cfg.set_now_int tls log 10
784
-		</programlisting>
785
-	</example>
786
-	</section>
787
-
788
-
789
-	<section id="tls.p.tls_debug">
790
-	<title><varname>tls_debug</varname> (int)</title>
791
-	<para>
792
-		Sets the log level at which TLS debug messages will be logged.
793
-		Note that TLS debug messages are enabled only if the TLS module
794
-		is compiled with debugging enabled (e.g. -DTLS_WR_DEBUG,
795
-		-DTLS_RD_DEBUG or -DTLS_BIO_DEBUG).
796
-	</para>
797
-	<para>
798
-		The default value is 3 (L_DBG).
799
-	</para>
800
-	<para>
801
-		It can be changed also at runtime, via the RPC interface and config
802
-		framework. The config variable name is <varname>tls.debug</varname>.
803
-	</para>
804
-	<example>
805
-		<title>Set <varname>tls_debug</varname> parameter</title>
806
-		<programlisting>
807
-...
808
-# ignore TLS debug messages if Kamailio is started with debug less than 10
809
-modparam("tls", "tls_debug", 10)
810
-...
811
-		</programlisting>
812
-	</example>
813
-	<example>
814
-		<title>Set <varname>tls.debug</varname> at runtime</title>
815
-		<programlisting>
816
- $ &sercmd; cfg.set_now_int tls debug 10
817
-		</programlisting>
818
-	</example>
819
-	</section>
820
-
821
-
822
-<section id="tls.p.low_mem_threshold1">
823
-	<title><varname>low_mem_threshold1</varname> (integer)</title>
824
-	<para>
825
-		Sets the minimal free memory from which attempts to open or accept
826
-		new TLS connections will start to fail. The value is expressed in KB.
827
-	</para>
828
-	<para>
829
-		The default value depends on whether the OpenSSL library used handles 
830
-		low memory situations in a good way (openssl bug #1491).
831
-		As of this writing this is not true for any OpenSSL version (including 0.9.8e).
832
-	</para>
833
-	<para>
834
-		If an ill-behaved OpenSSL version is detected, a very conservative value is chosen,
835
-		which depends on the maximum possible number of simultaneously created TLS connections
836
-		(and hence on the process number).
837
-	</para>
838
-	<para>
839
-		The following values have a special meaning:
840
-	</para>
841
-	<itemizedlist>
842
-			<listitem>
843
-				<para>
844
-					-1 - use the default value
845
-				</para>
846
-			</listitem>
847
-			<listitem>
848
-				<para>
849
-					0 - disable (TLS connections will not fail preemptively)
850
-				</para>
851
-			</listitem>
852
-	</itemizedlist>
853
-	<para>
854
-		It can be changed also at runtime, via the RPC interface and config
855
-		framework. The config variable name is <varname>tls.low_mem_threshold1</varname>.
856
-	</para>
857
-	<para>
858
-		See also <varname>tls.low_mem_threshold2</varname>.
859
-	</para>
860
-	<example>
861
-		<title>Set <varname>low_mem_threshold1</varname> parameter</title>
862
-		<programlisting>
863
-...
864
-modparam("tls", "low_mem_threshold1", -1)
865
-...
866
-	</programlisting>
867
-	</example>
868
-	<example>
869
-		<title>Set <varname>tls.low_mem_threshold1</varname> at runtime</title>
870
-		<programlisting>
871
- $ &sercmd; cfg.set_now_int tls low_mem_threshold1 2048
872
-		</programlisting>
873
-	</example>
874
-	</section>
875
-
876
-<section id="tls.p.low_mem_threshold2">
877
-	<title><varname>low_mem_threshold2</varname> (integer)</title>
878
-	<para>
879
-		Sets the minimal free memory from which TLS operations on already established
880
-		TLS connections will start to fail preemptively.  The value is expressed in KB.
881
-	</para>
882
-	<para>
883
-		The default value depends on whether the OpenSSL library used handles low memory
884
-		situations (openssl bug #1491).
885
-		As of this writing this is not true for any OpenSSL version (including 0.9.8e).
886
-	</para>
887
-	<para>
888
-		If an ill-behaved OpenSSL version is detected, a very conservative value is chosen,
889
-		which depends on the maximum possible number of simultaneously created
890
-		TLS connections (and hence on the process number).
891
-	</para>
892
-	<para>
893
-		The following values have a special meaning:
894
-	</para>
895
-	<itemizedlist>
896
-			<listitem>
897
-				<para>
898
-					-1 - use the default value
899
-				</para>
900
-			</listitem>
901
-			<listitem>
902
-				<para>
903
-					0 - disable (TLS operations will not fail preemptively)
904
-				</para>
905
-			</listitem>
906
-	</itemizedlist>
907
-	<para>
908
-		It can be changed also at runtime, via the RPC interface and config
909
-		framework. The config variable name is <varname>tls.low_mem_threshold2</varname>.
910
-	</para>
911
-	<para>
912
-		See also <varname>tls.low_mem_threshold1</varname>.
913
-	</para>
914
-	<example>
915
-		<title>Set <varname>tls.low_mem_threshold2</varname> parameter</title>
916
-		<programlisting>
917
-...
918
-modparam("tls", "low_mem_threshold2", -1)
919
-...
920
-	</programlisting>
921
-	</example>
922
-	<example>
923
-		<title>Set <varname>tls.low_mem_threshold2</varname> at runtime</title>
924
-		<programlisting>
925
- $ &sercmd; cfg.set_now_int tls low_mem_threshold2 1024
926
-		</programlisting>
927
-	</example>
928
-	</section>
929
-
930
-	<section id="tls.p.tls_force_run">
931
-	<title><varname>tls_force_run</varname> (boolean)</title>
932
-	<para>
933
-		If enabled &kamailio; will start even if some of the OpenSSL sanity checks fail (turn it on at your own risk).
934
-	</para>
935
-	<para>
936
-		If any of the following sanity checks fail, Kamailio will not start:
937
-	</para>
938
-	<itemizedlist>
939
-		<listitem>
940
-			<para>
941
-				the version of the library the TLS module was compiled with is
942
-				"too different" from the library used at runtime. The versions should have the same major,
943
-				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)
944
-			</para>
945
-		</listitem>
946
-		<listitem>
947
-			<para>
948
-				the OpenSSL library used at compile time and the one used at
949
-				runtime have different Kerberos options 
950
-			</para>
951
-		</listitem>
952
-	</itemizedlist>
953
-	<para>
954
-		By default tls_force_run is disabled.
955
-	</para>
956
-	<example>
957
-		<title>Set <varname>tls_force_run</varname> parameter</title>
958
-		<programlisting>
959
-...
960
-modparam("tls", "tls_force_run", 11)
961
-...
962
-	</programlisting>
963
-	</example>
964
-	</section>
965
-
966
-	<section id="tls.p.session_cache">
967
-	<title><varname>session_cache</varname> (boolean)</title>
968
-	<para>
969
-		If enabled &kamailio; will do caching of the TLS sessions data,
970
-		generation a session_id and sending it back to client.
971
-	</para>
972
-	<para>
973
-		By default TLS session caching is disabled (0).
974
-	</para>
975
-	<example>
976
-		<title>Set <varname>session_cache</varname> parameter</title>
977
-		<programlisting>
978
-...
979
-modparam("tls", "session_cache", 1)
980
-...
981
-	</programlisting>
982
-	</example>
983
-	</section>
984
-
985
-	<section id="tls.p.session_id">
986
-	<title><varname>session_id</varname> (str)</title>
987
-	<para>
988
-		The value for session ID context, making sense when session caching is enabled.
989
-	</para>
990
-	<para>
991
-		By default TLS session_id is "kamailio-tls-5.x.y".
992
-	</para>
993
-	<example>
994
-		<title>Set <varname>session_id</varname> parameter</title>
995
-		<programlisting>
996
-...
997
-modparam("tls", "session_id", "my-session-id-context")
998
-...
999
-	</programlisting>
1000
-	</example>
1001
-	</section>
1002
-
1003
-	<section id="tls.p.renegotiation">
1004
-	<title><varname>renegotiation</varname> (boolean)</title>
1005
-	<para>
1006
-		If enabled &kamailio;  will allow renegotiations of TLS connection initiated by the client. This may
1007
-		expose to a security risk if the client is not a trusted peer and keeps renegotiating, consuming CPU
1008
-		and bandwidth resources.
1009
-	</para>
1010
-	<para>
1011
-		By default TLS renegotiation is disabled (0).
1012
-	</para>
1013
-	<example>
1014
-		<title>Set <varname>renegotiation</varname> parameter</title>
1015
-		<programlisting>
1016
-...
1017
-modparam("tls", "renegotiation", 1)
1018
-...
1019
-	</programlisting>
1020
-	</example>
1021
-	</section>
1022
-
1023
-	<section id="tls.p.config">
1024
-	<title><varname>config</varname> (string)</title>
1025
-	<para>
1026
-		Sets the name of the TLS specific configuration file or configuration directory.
1027
-	</para>
1028
-	<para>
1029
-		If set the TLS module will load a special configuration file or configuration files
1030
-		from configuration directory, in which different TLS parameters can be specified on
1031
-		a per role (server or client) and domain basis (for now only IPs). The corresponding
1032
-		module parameters will be ignored if a separate configuration file is used.
1033
-	</para>
1034
-	<para>
1035
-		If the file or directory name starts with a '.' the path will be relative to the
1036
-		working directory (<emphasis>at runtime</emphasis>). If it starts
1037
-		with a '/' it will be an absolute path and if it starts with anything
1038
-		else the path will be relative to the main config file directory
1039
-		(e.g.: for kamailio -f /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).
1040
-	</para>
1041
-	<para>
1042
-		By default no TLS configuration file is specified.
1043
-	</para>
1044
-	<para>
1045
-		The following parameters can be set in the config file, for each
1046
-		domain:
1047
-	</para>
1048
-	<itemizedlist>
1049
-			<listitem><para>tls_method - (str) - TLS methods</para></listitem>
1050
-			<listitem><para>verify_certificate - (bool) - see modparam</para></listitem>
1051
-			<listitem><para>require_certificate - (bool) - see modparam</para></listitem>
1052
-			<listitem><para>verify_client - (str) - see modparam</para></listitem>
1053
-			<listitem><para>private_key - (str) - see modparam</para></listitem>
1054
-			<listitem><para>certificate - (str) - see modparam</para></listitem>
1055
-			<listitem><para>verify_depth - (int) - see modparam</para></listitem>
1056
-			<listitem><para>ca_list - (str) - see modparam</para></listitem>
1057
-			<listitem><para>crl - (str) - see modparam</para></listitem>
1058
-			<listitem><para>cipher_list - (str) - see modparam</para></listitem>
1059
-			<listitem><para>server_name - (str) - SNI (server name identification)</para></listitem>
1060
-			<listitem><para>server_name_mode - (int) - how to match server_name</para></listitem>
1061
-			<listitem><para>server_id - (str) - server id</para></listitem>
1062
-	</itemizedlist>
1063
-	<para>
1064
-		The value for server_name_mode specifies how to match the server_name
1065
-		(SNI). If set to 1, match the domain and all its subdomains. If set to
1066
-		2, match only the subdomains. If set to 0 (or anything else), match only
1067
-		the domain given in server_name.
1068
-	</para>
1069
-	<para>
1070
-		The value for server_id can be any string, being used to match TLS
1071
-		client config profile, overriding the match on ip:port and
1072
-		server_name. This is the recommended way for selecting a specific
1073
-		TLS client config profile, because the local or remote port is hard
1074
-		to predict for a stream connection - see parameter
1075
-		<varname>xavp_cfg</varname> to learn how to enable it.
1076
-	</para>
1077
-	<para>
1078
-		All the parameters that take filenames as values will be resolved
1079
-		using the same rules as for the tls config filename itself: starting
1080
-		with a '.' means relative to the working directory, a '/' means an
1081
-		absolute path and  anything else a path relative to the directory of
1082
-		the current &kamailio; main config file.
1083
-	</para>
1084
-	<para>
1085
-		Kamailio acts as a server when it accepts a connection and as a
1086
-		client when it initiates a new connection by itself (it connects to
1087
-		something).
1088
-	</para>
1089
-	<para>
1090
-		The tls.cfg consists on a set of server and client TLS domain profiles.
1091
-		A server TLS domain profile starts with [server:domain]. A client TLS
1092
-		domain profile starts with [client:domain]. The tokens 'server' and
1093
-		'client' are static values. The 'domain' part can be: 'ip:port' - the
1094
-		IP address and port to match with the TLS connection; 'default' -
1095
-		(static string) for client and server profiles to be used when
1096
-		no other profile is matched; 'any' - (static string) for client and
1097
-		server profiles to be matched based on 'server_name', no matter of
1098
-		IP and port of the TLS connection.
1099
-	</para>
1100
-	<para>
1101
-		There can be only one of each [server:default] and [client:default]
1102
-		profile definitions. Other profiles can be defined many times with the
1103
-		same domain ('ip:port' or 'any'), but in that case they must have
1104
-		'server_name' set for matching SNI.
1105
-	</para>
1106
-	<para>
1107
-		It is highly recommended to have [server:default] and [client:default]
1108
-		profile definitions. They are needed when SNI is not yet available. If
1109
-		SNI is provided, then the profile definition is searched again to match
1110
-		on 'server_name'.
1111
-	</para>
1112
-
1113
-	<example>
1114
-		<title>Sample TLS Config File</title>
1115
-	<programlisting>
1116
-...
1117
-[server:default]
1118
-method = TLSv1
1119
-verify_certificate = yes
1120
-require_certificate = yes
1121
-private_key = default_key.pem
1122
-certificate = default_cert.pem
1123
-ca_list = default_ca.pem
1124
-crl = default_crl.pem
1125
-
1126
-[client:default]
1127
-verify_certificate = yes
1128
-require_certificate = yes
1129
-
1130
-# more relaxed for connection on the loopback interface
1131
-[server:127.0.0.1:5061]
1132
-method = TLSv1
1133
-verify_certificate = yes