GitList
Browse code

Merge pull request #3144 from space88man/wolfssl

tls_wolfssl: new module TLS stack based on wolfSSL

Daniel-Constantin Mierla authored on 16/06/2022 06:39:02 • GitHub committed on 16/06/2022 06:39:02
Showing 46 changed files
src/modules/tls_wolfssl/Makefile
History View file @ c08a7cbdfc
1 1 
new file mode 100644
... ... 
@@ -0,0 +1,81 @@
1 
+#
2 
+# TLS module makefile
3 
+#
4 
+#
5 
+# WARNING: do not run this directly, it should be run by the main Makefile
6 
+
7 
+include ../../Makefile.defs
8 
+auto_gen=
9 
+NAME=tls_wolfssl.so
10 
+
11 
+# set to yes when wanting to link with static libraries
12 
+LIBSSL_STATIC ?= no
13 
+# set to yes when wanting to link with static libraries compiled from source
14 
+LIBSSL_STATIC_SRCLIB ?= no
15 
+# set to the path of the folder with static libraries compiled from source
16 
+LIBSSL_STATIC_SRCPATH ?= /usr/local/src/openssl
17 
+
18 
+ifeq ($(CROSS_COMPILE),)
19 
+WOLFSSL_BUILDER=$(shell \
20 
+	if pkg-config --exists wolfssl; then \
21 
+		echo 'pkg-config wolfssl'; \
22 
+	fi)
23 
+endif
24 
+
25 
+ifneq ($(WOLFSSL_BUILDER),)
26 
+
27 
+ifneq ($(WOLFSSL_STATIC),yes)
28 
+	DEFS += $(shell $(WOLFSSL_BUILDER) --cflags)
29 
+	LIBS += $(shell $(WOLFSSL_BUILDER) --libs)
30 
+
31 
+else # $(WOLFSSL_STATIC),yes)
32 
+
33 
+	DEFS += -DKSR_WOLFSSL_STATIC
34 
+
35 
+ifneq ($(WOLFSSL_STATIC_SRCLIB),yes)
36 
+	## when static libs (*.a) from packages are compiled with -fPIC
37 
+	DEFS += $(shell $(WOLFSSL_BUILDER) --cflags)
38 
+	LIBS += $(shell $(WOLFSSL_BUILDER) --libs-only-L)
39 
+	# TODO: explore use of LIBS += -Wl,-Bstatic $(shell $(SSL_BUILDER) --libs-only-l)
40 
+	LIBS += -l:libwolfssl.a -l:libz.a -l:libdl.a
41 
+else
42 
+	## when linking against static libs compiled from sources
43 
+	DEFS += -I$(WOLFSSL_STATIC_SRCPATH)/include
44 
+	LIBS += $(WOLFSSL_STATIC_SRCPATH)/libwolfssl.a
45 
+endif # ifneq ($(WOLFSSL_STATIC_SRCLIB),yes)
46 
+
47 
+endif # ifneq ($(WOLFSSL_STATIC),yes)
48 
+
49 
+else # ifneq ($(SSL_BUILDER),)
50 
+
51 
+	DEFS += -I$(LOCALBASE)/wolfssl/include
52 
+	LIBS += -L$(LOCALBASE)/lib \
53 
+			-L$(LOCALBASE)/lib64  \
54 
+			-lwolfssl
55 
+endif # ifneq ($(SSL_BUILDER),)
56 
+
57 
+LIBS+= $(TLS_EXTRA_LIBS)
58 
+
59 
+# dcm: tls.cfg installed via local 'install-cfg' to update paths
60 
+#MOD_INSTALL_CFGS=tls.cfg
61 
+
62 
+include ../../Makefile.modules
63 
+
64 
+install-tls-cert: $(cfg_prefix)/$(cfg_dir)
65 
+	MAIN_NAME=$(MAIN_NAME) ./tls_cert.sh -d $(cfg_prefix)/$(cfg_dir)
66 
+
67 
+install-cfg:
68 
+	@if ! [ -d $(cfg_prefix)/$(cfg_dir) ]; then \
69 
+		mkdir -p "$(cfg_prefix)/$(cfg_dir)" ; \
70 
+	fi
71 
+	@$(call try_err, $(INSTALL_TOUCH) \
72 
+			"$(cfg_prefix)/$(cfg_dir)tls.cfg.sample" )
73 
+	@sed -e "s#\/usr/local/etc/kamailio/#$(cfg_target)#g" \
74 
+			-e "s#kamailio-selfsigned#$(MAIN_NAME)-selfsigned#g" \
75 
+				< ./tls.cfg > "$(cfg_prefix)/$(cfg_dir)tls.cfg.sample"
76 
+	@if [ -z "${skip_cfg_install}" -a \
77 
+			! -f "$(cfg_prefix)/$(cfg_dir)tls.cfg" ]; then \
78 
+		mv -f "$(cfg_prefix)/$(cfg_dir)tls.cfg.sample" \
79 
+						"$(cfg_prefix)/$(cfg_dir)tls.cfg" ; \
80 
+	fi
81 
+
src/modules/tls_wolfssl/README
History View file @ c08a7cbdfc
0 82 
new file mode 100644
... ... 
@@ -0,0 +1,1713 @@
1 
+TLS Module
2 
+
3 
+Andrei Pelinescu-Onciul
4 
+
5 
+   iptelorg GmbH
6 
+
7 
+Carsten Bock
8 
+
9 
+   ng-voice GmbH
10 
+
11 
+Olle E. Johansson
12 
+
13 
+   Edvina AB
14 
+
15 
+   Copyright © 2007 iptelorg GmbH
16 
+
17 
+   Copyright © 2014 ng-voice GmbH
18 
+     __________________________________________________________________
19 
+
20 
+   Table of Contents
21 
+
22 
+   1. Admin Guide
23 
+
24 
+        1. Overview
25 
+        2. Quick Start
26 
+        3. Important Notes
27 
+        4. Compiling the TLS Module
28 
+        5. TLS and Low Memory
29 
+        6. TLS Debugging
30 
+        7. Known Limitations
31 
+        8. Quick Certificate Howto
32 
+        9. HSM Howto
33 
+        10. Parameters
34 
+
35 
+              10.1. tls_method (string)
36 
+              10.2. certificate (string)
37 
+              10.3. private_key (string)
38 
+              10.4. ca_list (string)
39 
+              10.5. ca_path (str)
40 
+              10.6. crl (string)
41 
+              10.7. verify_certificate (boolean)
42 
+              10.8. verify_depth (integer)
43 
+              10.9. require_certificate (boolean)
44 
+              10.10. cipher_list (string)
45 
+              10.11. server_name (string)
46 
+              10.12. connection_timeout (int)
47 
+              10.13. tls_disable_compression (boolean)
48 
+              10.14. ssl_release_buffers (integer)
49 
+              10.15. ssl_freelist_max_len (integer)
50 
+              10.16. ssl_max_send_fragment (integer)
51 
+              10.17. ssl_read_ahead (boolean)
52 
+              10.18. send_close_notify (boolean)
53 
+              10.19. con_ct_wq_max (integer)
54 
+              10.20. ct_wq_max (integer)
55 
+              10.21. ct_wq_blk_size (integer)
56 
+              10.22. tls_log (int)
57 
+              10.23. tls_debug (int)
58 
+              10.24. low_mem_threshold1 (integer)
59 
+              10.25. low_mem_threshold2 (integer)
60 
+              10.26. tls_force_run (boolean)
61 
+              10.27. session_cache (boolean)
62 
+              10.28. session_id (str)
63 
+              10.29. renegotiation (boolean)
64 
+              10.30. config (string)
65 
+              10.31. xavp_cfg (string)
66 
+              10.32. event_callback (str)
67 
+              10.33. rand_engine (str)
68 
+              10.34. engine (string)
69 
+              10.35. engine_config (string)
70 
+              10.36. engine_algorithms (string)
71 
+              10.37. verify_client (string)
72 
+
73 
+        11. Functions
74 
+
75 
+              11.1. is_peer_verified()
76 
+              11.2. tls_set_connect_server_id(srvid)
77 
+
78 
+        12. RPC Commands
79 
+
80 
+              12.1. tls.info
81 
+              12.2. tls.list
82 
+              12.3. tls.options
83 
+              12.4. tls.reload
84 
+
85 
+        13. Status
86 
+
87 
+              13.1. License
88 
+              13.2. History
89 
+
90 
+        14. Event Routes
91 
+
92 
+              14.1. event_route[tls:connection-out]
93 
+
94 
+        15. TLS With Database Backend
95 
+
96 
+   List of Examples
97 
+
98 
+   1.1. Quick Start Basic Config
99 
+   1.2. Compiling TLS with Debug Messages
100 
+   1.3. Set tls_method parameter
101 
+   1.4. Set certificate parameter
102 
+   1.5. Set private_key parameter
103 
+   1.6. Set ca_list parameter
104 
+   1.7. Set ca_path parameter
105 
+   1.8. Set crl parameter
106 
+   1.9. Set verify_certificate parameter
107 
+   1.10. Set verify_depth parameter
108 
+   1.11. Set require_certificate parameter
109 
+   1.12. Set cipher_list parameter
110 
+   1.13. Set server_name parameter
111 
+   1.14. Set connection_timeout parameter
112 
+   1.15. Set tls.connection_timeout at runtime
113 
+   1.16. Set tls_disable_compression parameter
114 
+   1.17. Set ssl_release_buffers parameter
115 
+   1.18. Set ssl_freelist_max_len parameter
116 
+   1.19. Set ssl_max_send_fragment parameter
117 
+   1.20. Set ssl_read_ahead parameter
118 
+   1.21. Set send_close_notify parameter
119 
+   1.22. Set tls.send_close_notify at runtime
120 
+   1.23. Set con_ct_wq_max parameter
121 
+   1.24. Set tls.con_ct_wq_max at runtime
122 
+   1.25. Set ct_wq_max parameter
123 
+   1.26. Set tls.ct_wq_max at runtime
124 
+   1.27. Set ct_wq_blk_size parameter
125 
+   1.28. Set tls.ct_wq_max at runtime
126 
+   1.29. Set tls_log parameter
127 
+   1.30. Set tls.log at runtime
128 
+   1.31. Set tls_debug parameter
129 
+   1.32. Set tls.debug at runtime
130 
+   1.33. Set low_mem_threshold1 parameter
131 
+   1.34. Set tls.low_mem_threshold1 at runtime
132 
+   1.35. Set tls.low_mem_threshold2 parameter
133 
+   1.36. Set tls.low_mem_threshold2 at runtime
134 
+   1.37. Set tls_force_run parameter
135 
+   1.38. Set session_cache parameter
136 
+   1.39. Set session_id parameter
137 
+   1.40. Set renegotiation parameter
138 
+   1.41. Sample TLS Config File
139 
+   1.42. Set config parameter
140 
+   1.43. Change and reload the TLS configuration at runtime
141 
+   1.44. Set xavp_cfg parameter
142 
+   1.45. Set event_callback parameter
143 
+   1.46. Set rand_engine parameter
144 
+   1.47. Set verify_client modparam parameter
145 
+   1.48. Set verify_client tls.cfg parameter
146 
+   1.49. is_peer_verified usage
147 
+   1.50. tls_set_connect_server_id usage
148 
+   1.51. Use of event_route[tls:connection-out]
149 
+
150 
+Chapter 1. Admin Guide
151 
+
152 
+   Table of Contents
153 
+
154 
+   1. Overview
155 
+   2. Quick Start
156 
+   3. Important Notes
157 
+   4. Compiling the TLS Module
158 
+   5. TLS and Low Memory
159 
+   6. TLS Debugging
160 
+   7. Known Limitations
161 
+   8. Quick Certificate Howto
162 
+   9. HSM Howto
163 
+   10. Parameters
164 
+
165 
+        10.1. tls_method (string)
166 
+        10.2. certificate (string)
167 
+        10.3. private_key (string)
168 
+        10.4. ca_list (string)
169 
+        10.5. ca_path (str)
170 
+        10.6. crl (string)
171 
+        10.7. verify_certificate (boolean)
172 
+        10.8. verify_depth (integer)
173 
+        10.9. require_certificate (boolean)
174 
+        10.10. cipher_list (string)
175 
+        10.11. server_name (string)
176 
+        10.12. connection_timeout (int)
177 
+        10.13. tls_disable_compression (boolean)
178 
+        10.14. ssl_release_buffers (integer)
179 
+        10.15. ssl_freelist_max_len (integer)
180 
+        10.16. ssl_max_send_fragment (integer)
181 
+        10.17. ssl_read_ahead (boolean)
182 
+        10.18. send_close_notify (boolean)
183 
+        10.19. con_ct_wq_max (integer)
184 
+        10.20. ct_wq_max (integer)
185 
+        10.21. ct_wq_blk_size (integer)
186 
+        10.22. tls_log (int)
187 
+        10.23. tls_debug (int)
188 
+        10.24. low_mem_threshold1 (integer)
189 
+        10.25. low_mem_threshold2 (integer)
190 
+        10.26. tls_force_run (boolean)
191 
+        10.27. session_cache (boolean)
192 
+        10.28. session_id (str)
193 
+        10.29. renegotiation (boolean)
194 
+        10.30. config (string)
195 
+        10.31. xavp_cfg (string)
196 
+        10.32. event_callback (str)
197 
+        10.33. rand_engine (str)
198 
+        10.34. engine (string)
199 
+        10.35. engine_config (string)
200 
+        10.36. engine_algorithms (string)
201 
+        10.37. verify_client (string)
202 
+
203 
+   11. Functions
204 
+
205 
+        11.1. is_peer_verified()
206 
+        11.2. tls_set_connect_server_id(srvid)
207 
+
208 
+   12. RPC Commands
209 
+
210 
+        12.1. tls.info
211 
+        12.2. tls.list
212 
+        12.3. tls.options
213 
+        12.4. tls.reload
214 
+
215 
+   13. Status
216 
+
217 
+        13.1. License
218 
+        13.2. History
219 
+
220 
+   14. Event Routes
221 
+
222 
+        14.1. event_route[tls:connection-out]
223 
+
224 
+   15. TLS With Database Backend
225 
+
226 
+1. Overview
227 
+
228 
+   This module implements the TLS transport for Kamailio using the OpenSSL
229 
+   library (http://www.openssl.org). To enable the Kamailio TLS support
230 
+   this module must be loaded and enable_tls=yes core setting must be
231 
+   added to the Kamailio config file.
232 
+
233 
+   IMPORTANT: the tls module must be loaded before any other Kamailio
234 
+   module that uses libssl (OpenSSL library). A safe option is to have the
235 
+   tls module loaded first (be in the first "loadmodule" in Kamailio.cfg).
236 
+
237 
+   IMPORTANT: using this module compiled with newer versions of libssl
238 
+   (e.g., v1.1+) may require Kamailio to be started with --atexit=no
239 
+   command line parameters to avoid calling C atexit callbacks inside the
240 
+   process ending during daemonize procedure as well as during shut down,
241 
+   which can lead to crashes because it destroys and then accesses shared
242 
+   memory. For example, such case has been reported for Ubuntu 20.04 or
243 
+   RedHat 8.
244 
+
245 
+2. Quick Start
246 
+
247 
+   The default kamailio.cfg file has basic tls support included, it has to
248 
+   be enabled with "#!define WITH_TLS" directive.
249 
+
250 
+   The most important parameters to set the path to the public certificate
251 
+   and private key files. You can either have them in different file or in
252 
+   the same file in PEM format. The parameters for them are certificate
253 
+   and private_key. They can be given as modparam or or provided in the
254 
+   profiles of tls.cfg file.
255 
+
256 
+   When installing tls module of kamailio, a sample 'tls.cfg' file is
257 
+   deployed in the same folder with 'kamailio.cfg', along with freshly
258 
+   generated self signed certificates.
259 
+
260 
+   HINT: be sure you have enable_tls=yes to your kamailio.cfg.
261 
+
262 
+   Example 1.1. Quick Start Basic Config
263 
+#...
264 
+loadmodule "sl.so"
265 
+loadmodule "tls.so"
266 
+
267 
+modparam("tls", "private_key", "./server-test.pem")
268 
+modparam("tls", "certificate", "./server-test.pem")
269 
+modparam("tls", "ca_list", "./calist.pem")
270 
+
271 
+enable_tls=yes
272 
+
273 
+request_route {
274 
+        if(proto != TLS) {
275 
+                sl_send_reply("403", "Accepting TLS Only");
276 
+                exit;
277 
+        }
278 
+        ...
279 
+}
280 
+
281 
+3. Important Notes
282 
+
283 
+   The TLS module needs some special options enabled when compiling
284 
+   Kamailio. These options are enabled by default, however in case you're
285 
+   using a modified Kamailio version or Makefile, make sure that you
286 
+   enable -DUSE_TLS and -DTLS_HOOKS (or compile with make TLS_HOOKS=1
287 
+   which will take care of both options).
288 
+
289 
+   To quickly check if your Kamailio version was compiled with these
290 
+   options, run kamailio -V and look for USE_TLS and TLS_HOOKS among the
291 
+   flags.
292 
+
293 
+   For OpenSSL (libssl) v1.1.x, it is required to preload
294 
+   'openssl_mutex_shared' library shipped by Kamailio. For more details
295 
+   see 'src/modules/tls/openssl_mutex_shared/README.md'.
296 
+
297 
+   This module includes several workarounds for various Openssl bugs (like
298 
+   compression and Kerberos using the wrong memory allocations functions,
299 
+   low memory problems a.s.o). On startup it will try to enable the needed
300 
+   workarounds based on the OpenSSL library version. Each time a known
301 
+   problem is detected and a workaround is enabled, a message will be
302 
+   logged. In general it is recommended to compile this module on the same
303 
+   machine or a similar machine to where kamailio will be run or to link
304 
+   it statically with libssl. For example if on the compile machine
305 
+   OpenSSL does not have the Kerberos support enabled, but on the target
306 
+   machine a Kerberos enabled OpenSSL library is installed, Kamailio
307 
+   cannot apply the needed workarounds and will refuse to start. The same
308 
+   thing will happen if the OpenSSL versions are too different (to force
309 
+   Kamailio startup anyway, see the tls_force_run module parameter).
310 
+
311 
+   Compression is fully supported if you have a new enough OpenSSL version
312 
+   (starting with 0.9.8). Although there are some problems with zlib
313 
+   compression in currently deployed OpenSSL versions (up to and including
314 
+   0.9.8d, see openssl bug #1468), the TLS module will automatically
315 
+   switch to its own fixed version. Note however that starting with
316 
+   Kamailio 3.1 compression is not enabled by default, due to the huge
317 
+   extra memory consumption that it causes (about 10x more memory). To
318 
+   enable it use modparam("tls", "tls_disable_compression", 0) (see
319 
+   tls_disable_compression).
320 
+
321 
+   The TLS module includes workarounds for the following known openssl
322 
+   bugs:
323 
+     * openssl #1204 (disable SS_OP_TLS_BLOCK_PADDING_BUG if compression
324 
+       is enabled, for versions between 0.9.8 and 0.9.8c),
325 
+     * openssl #1468 (fix zlib compression memory allocation),
326 
+     * openssl #1467 (kerberos support will be disabled if the openssl
327 
+       version is less than 0.9.8e-beta1)
328 
+     * openssl #1491 (stop using tls in low memory situations due to the
329 
+       very high risk of openssl crashing or leaking memory).
330 
+
331 
+   The bug reports can be viewed at http://rt.openssl.org/.
332 
+
333 
+4. Compiling the TLS Module
334 
+
335 
+   In most case compiling the TLS module is as simple as:
336 
+make -C modules/tls
337 
+
338 
+   or
339 
+make modules modules=modules/tls
340 
+
341 
+   or (compiling whole Kamailio and the tls module)
342 
+make all include_modules=tls
343 
+
344 
+   .
345 
+
346 
+   However in some cases the OpenSSL library requires linking with other
347 
+   libraries. For example compiling the OpenSSL library with Kerberos and
348 
+   zlib-shared support will require linking the TLS module with libkrb5
349 
+   and libz. In this case just add TLS_EXTRA_LIBS="library list" to make's
350 
+   command line. E.g.:
351 
+make TLS_EXTRA_LIBS="-lkrb5 -lz" all include_modules=tls
352 
+
353 
+   In general, if Kamailio fails to start with a symbol not found error
354 
+   when trying to load the TLS module (check the log), it means some
355 
+   needed library was not linked and it must be added to TLS_EXTRA_LIBS
356 
+
357 
+   Elliptic Curve Diffie-Hellman (EDCH)-Ciphers are only supported in
358 
+   OpenSSL 1.0.0e and later.
359 
+
360 
+5. TLS and Low Memory
361 
+
362 
+   The Openssl library doesn't handle low memory situations very well. If
363 
+   memory allocations start to fail (due to memory shortage), Openssl can
364 
+   crash or cause memory leaks (making the memory shortage even worse). As
365 
+   of this writing all Openssl versions were affected (including 0.9.8e),
366 
+   see Openssl bug #1491. The TLS module has some workarounds for
367 
+   preventing this problem (see low_mem_treshold1 and low_mem_threshold2),
368 
+   however starting Kamailio with enough shared memory is higly
369 
+   recommended. When this is not possible a quick way to significantly
370 
+   reduce Openssl memory usage it to disable compression (see
371 
+   tls_disable_compression).
372 
+
373 
+6. TLS Debugging
374 
+
375 
+   Debugging messages can be selectively enabled by recompiling the TLS
376 
+   module with a combination of the following defines:
377 
+     * TLS_WR_DEBUG - debug messages for the write/send part.
378 
+     * TLS_RD_DEBUG - debug messages for the read/receive part.
379 
+     * TLS_BIO_DEBUG - debug messages for the custom BIO.
380 
+
381 
+   Example 1.2. Compiling TLS with Debug Messages
382 
+make -C modules/tls extra_defs="-DTLS_WR_DEBUG -DTLS_RD_DEBUG"
383 
+
384 
+   To change the level at which the debug messages are logged, change the
385 
+   tls_debug module parameter.
386 
+
387 
+7. Known Limitations
388 
+
389 
+   The private key must not be encrypted (Kamailio cannot ask you for a
390 
+   password on startup).
391 
+
392 
+   The TLS certificate verifications ignores the certificate name, Subject
393 
+   Altname and IP extensions, it just checks if the certificate is signed
394 
+   by a recognized CA. One can use the select framework to try to overcome
395 
+   this limitation (check in the script for the contents of various
396 
+   certificate fields), but this is not only slow, but also not exactly
397 
+   standard conforming (the verification should happen during TLS
398 
+   connection establishment and not after).
399 
+
400 
+   TLS specific config reloading is not safe, so for now better don't use
401 
+   it, especially under heavy traffic.
402 
+
403 
+   This documentation is incomplete. The provided selects are not
404 
+   documented in this file. A list with all the ones implemented by the
405 
+   TLS module can be found in the Cookbook https://www.kamailio.org/wiki/
406 
+   in the section Selects for the respective version of Kamailio.
407 
+
408 
+8. Quick Certificate Howto
409 
+
410 
+   There are various ways to create, sign certificates and manage small
411 
+   CAs (Certificate Authorities). If you are in a hurry and everything you
412 
+   have are the installed OpenSSL libraries and utilities, read on.
413 
+
414 
+   Assumptions: we run our own CA.
415 
+
416 
+   Warning: in this example no key is encrypted. The client and server
417 
+   private keys must not be encrypted (Kamailio doesn't support encrypted
418 
+   keys), so make sure the corresponding files are readable only by
419 
+   trusted people. You should use a password to protect your CA private
420 
+   key.
421 
+
422 
+Assumptions
423 
+------------
424 
+
425 
+The default openssl configuration (usually /etc/ssl/openssl.cnf)
426 
+default_ca section is the one distributed with openssl and uses the default
427 
+directories:
428 
+
429 
+...
430 
+
431 
+default_ca      = CA_default            # The default ca section
432 
+
433 
+[ CA_default ]
434 
+
435 
+dir             = ./demoCA              # Where everything is kept
436 
+certs           = $dir/certs            # Where the issued certs are kept
437 
+crl_dir         = $dir/crl              # Where the issued crl are kept
438 
+database        = $dir/index.txt        # database index file.
439 
+#unique_subject = no                    # Set to 'no' to allow creation of
440 
+                                        # several certificates with same subject
441 
+.
442 
+new_certs_dir   = $dir/newcerts         # default place for new certs.
443 
+
444 
+certificate     = $dir/cacert.pem       # The CA certificate
445 
+serial          = $dir/serial           # The current serial number
446 
+crlnumber       = $dir/crlnumber        # the current CRL number
447 
+crl             = $dir/crl.pem          # The current CRL
448 
+private_key     = $dir/private/cakey.pem# The private key
449 
+RANDFILE        = $dir/private/.rand    # private random number file
450 
+
451 
+...
452 
+
453 
+If this is not the case create a new OpenSSL config file that uses the above
454 
+paths for the default CA and add to all the openssl commands:
455 
+ -config filename. E.g.:
456 
+        openssl ca -config my_openssl.cnf -in kamailio1_cert_req.pem -out kamail
457 
+io1_cert.pem
458 
+
459 
+
460 
+Creating the CA certificate
461 
+---------------------------
462 
+1. Create the CA directory
463 
+        mkdir ca
464 
+        cd ca
465 
+
466 
+2. Create the CA directory structure and files  (see ca(1))
467 
+        mkdir demoCA            #default CA name, edit /etc/ssl/openssl.cnf
468 
+        mkdir  demoCA/private
469 
+        mkdir demoCA/newcerts
470 
+        touch demoCA/index.txt
471 
+        echo 01 >demoCA/serial
472 
+        echo 01 >demoCA/crlnumber
473 
+
474 
+2. Create CA private key
475 
+        openssl genrsa -out demoCA/private/cakey.pem 2048
476 
+        chmod 600 demoCA/private/cakey.pem
477 
+
478 
+3. Create CA self-signed certificate
479 
+        openssl req -out demoCA/cacert.pem   -x509 -new -key demoCA/private/cake
480 
+y.pem
481 
+
482 
+
483 
+Creating a server/client TLS certificate
484 
+----------------------------------------
485 
+1. Create a certificate request (and its private key in privkey.pem)
486 
+
487 
+        openssl req -out kamailio1_cert_req.pem -new -nodes
488 
+
489 
+        WARNING: the organization name should be the same as in the CA certifica
490 
+te.
491 
+
492 
+2. Sign it with the CA certificate
493 
+        openssl ca -in kamailio1_cert_req.pem -out kamailio1_cert.pem
494 
+
495 
+3. Copy kamailio1_cert.pem to your Kamailio configuration dir
496 
+
497 
+
498 
+Setting Kamailio to use the TLS certificate
499 
+---------------------------------------------
500 
+1. Create the CA list file:
501 
+        for each of your CA certificates that you intend to use do:
502 
+                cat cacert.pem >>calist.pem
503 
+
504 
+2. Copy your Kamailio certificate, private key and ca list file to your
505 
+        intended machine (preferably in your Kamailio configuration directory,
506 
+         this is the default place Kamailio searches for).
507 
+
508 
+3. Set up Kamailio.cfg to use the certificate
509 
+        if your Kamailio certificate name is different from cert.pem or it is no
510 
+t
511 
+        placed in Kamailio cfg. directory, add to your kamailio.cfg:
512 
+                modparam("tls", "certificate", "/path/cert_file_name")
513 
+
514 
+4. Set up Kamailio to use the private key
515 
+        if your private key is not contained in the same file as the certificate
516 
+        (or the certificate name is not the default cert.pem), add to your
517 
+         Kamailio.cfg:
518 
+                modparam("tls", "private_key", "/path/private_key_file")
519 
+
520 
+5. Set up Kamailio to use the CA list (optional)
521 
+   The CA list is not used for your server certificate - it's used to approve ot
522 
+her servers
523 
+   and clients connecting to your server with a client certificate or for approv
524 
+ing
525 
+   a certificate used by a server your server connects to.
526 
+        add to your Kamailio.cfg:
527 
+                modparam("tls", "ca_list", "/path/ca_list_file")
528 
+
529 
+6. Set up TLS authentication options:
530 
+                modparam("tls", "verify_certificate", 1)
531 
+                modparam("tls", "require_certificate", 1)
532 
+        (for more information see the module parameters documentation)
533 
+
534 
+
535 
+Revoking a certificate and using a CRL
536 
+--------------------------------------
537 
+1. Revoking a certificate:
538 
+        openssl ca -revoke bad_cert.pem
539 
+
540 
+2. Generate/update the certificate revocation list:
541 
+        openssl ca -gencrl -out my_crl.pem
542 
+
543 
+3. Copy my_crl.pem to your Kamailio config. dir
544 
+
545 
+4. Set up Kamailio to use the CRL:
546 
+                modparam("tls", "crl", "path/my_crl.pem")
547 
+
548 
+9. HSM Howto
549 
+
550 
+   This documents OpenSSL engine support for private keys in HSM.
551 
+
552 
+   Assumptions: an OpenSSL engine configured with private key. We still
553 
+   require the certificate file and list of CA certificates per a regular
554 
+   TLS configuration.
555 
+
556 
+Thales Luna Example
557 
+--------------------
558 
+
559 
+...
560 
+# Example for Thales Luna
561 
+modparam("tls", "engine", "gem")
562 
+modparam("tls", "engine_config", "/usr/local/etc/kamailio/thales.cnf")
563 
+modparam("tls", "engine_algorithms", "EC")
564 
+...
565 
+
566 
+/usr/local/etc/kamailio/thales.cnf is a OpenSSL config format file used to
567 
+bootstrap the engine, e.g., pass the PIN.
568 
+
569 
+...
570 
+# the key kamailio is mandatory
571 
+kamailio = openssl_init
572 
+
573 
+[ openssl_init ]
574 
+engines = engine_section
575 
+
576 
+[ engine_section ]
577 
+# gem is the name of the Thales Luna OpenSSL engine
578 
+gem = gem_section
579 
+
580 
+[ gem_section ]
581 
+# from Thales documentation
582 
+dynamic_path = /usr/lib64/engines-1.1/gem.so
583 
+ENGINE_INIT = 0:20:21:password=1234-ABCD-5678-EFGH
584 
+...
585 
+
586 
+
587 
+Thales nShield Connect
588 
+----------------------
589 
+
590 
+Place holder
591 
+
592 
+10. Parameters
593 
+
594 
+   10.1. tls_method (string)
595 
+   10.2. certificate (string)
596 
+   10.3. private_key (string)
597 
+   10.4. ca_list (string)
598 
+   10.5. ca_path (str)
599 
+   10.6. crl (string)
600 
+   10.7. verify_certificate (boolean)
601 
+   10.8. verify_depth (integer)
602 
+   10.9. require_certificate (boolean)
603 
+   10.10. cipher_list (string)
604 
+   10.11. server_name (string)
605 
+   10.12. connection_timeout (int)
606 
+   10.13. tls_disable_compression (boolean)
607 
+   10.14. ssl_release_buffers (integer)
608 
+   10.15. ssl_freelist_max_len (integer)
609 
+   10.16. ssl_max_send_fragment (integer)
610 
+   10.17. ssl_read_ahead (boolean)
611 
+   10.18. send_close_notify (boolean)
612 
+   10.19. con_ct_wq_max (integer)
613 
+   10.20. ct_wq_max (integer)
614 
+   10.21. ct_wq_blk_size (integer)
615 
+   10.22. tls_log (int)
616 
+   10.23. tls_debug (int)
617 
+   10.24. low_mem_threshold1 (integer)
618 
+   10.25. low_mem_threshold2 (integer)
619 
+   10.26. tls_force_run (boolean)
620 
+   10.27. session_cache (boolean)
621 
+   10.28. session_id (str)
622 
+   10.29. renegotiation (boolean)
623 
+   10.30. config (string)
624 
+   10.31. xavp_cfg (string)
625 
+   10.32. event_callback (str)
626 
+   10.33. rand_engine (str)
627 
+   10.34. engine (string)
628 
+   10.35. engine_config (string)
629 
+   10.36. engine_algorithms (string)
630 
+   10.37. verify_client (string)
631 
+
632 
+10.1. tls_method (string)
633 
+
634 
+   Sets the TLS protocol method. Possible values are:
635 
+     * TLSv1.2+ - TLSv1.2 or newer (TLSv1.3, ...) connections are accepted
636 
+       (available starting with openssl/libssl v1.1.1)
637 
+     * TLSv1.2 - only TLSv1.2 connections are accepted (available starting
638 
+       with openssl/libssl v1.0.1e)
639 
+     * TLSv1.1+ - TLSv1.1 or newer (TLSv1.2, ...) connections are accepted
640 
+       (available starting with openssl/libssl v1.0.1)
641 
+     * TLSv1.1 - only TLSv1.1 connections are accepted (available starting
642 
+       with openssl/libssl v1.0.1)
643 
+     * TLSv1+ - TLSv1.0 or newer (TLSv1.1, TLSv1.2, ...) connections are
644 
+       accepted.
645 
+     * TLSv1 - only TLSv1 (TLSv1.0) connections are accepted. This is the
646 
+       default value.
647 
+     * SSLv3 - only SSLv3 connections are accepted. Note: you shouldn't
648 
+       use SSLv3 for anything which should be secure.
649 
+     * SSLv2 - only SSLv2 connections, for old clients. Note: you
650 
+       shouldn't use SSLv2 for anything which should be secure. Newer
651 
+       versions of OpenSSL libraries don't include support for it anymore.
652 
+     * SSLv23 - any of the SSLv2, SSLv3 and TLSv1 or newer methods will be
653 
+       accepted.
654 
+       From the OpenSSL manual: "A TLS/SSL connection established with
655 
+       these methods may understand the SSLv3, TLSv1, TLSv1.1 and TLSv1.2
656 
+       protocols. If extensions are required (for example server name) a
657 
+       client will send out TLSv1 client hello messages including
658 
+       extensions and will indicate that it also understands TLSv1.1,
659 
+       TLSv1.2 and permits a fallback to SSLv3. A server will support
660 
+       SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols. This is the best
661 
+       choice when compatibility is a concern."
662 
+       Note: For older OpenSSL library versions, this option allows SSLv2,
663 
+       with hello messages done over SSLv2. You shouldn't use SSLv2 or
664 
+       SSLv3 for anything which should be secure.
665 
+
666 
+   If RFC 3261 conformance is desired, at least TLSv1 must be used. For
667 
+   compatibility with older clients SSLv23 is the option, but again, be
668 
+   aware of security concerns, SSLv2/3 being considered very insecure by
669 
+   2014. For current information about what's considered secure, please
670 
+   consult, IETF BCP 195, currently RFC 7525 - "Recommendations for Secure
671 
+   Use of Transport Layer Security (TLS) and Datagram Transport Layer
672 
+   Security (DTLS)"
673 
+
674 
+   Example 1.3. Set tls_method parameter
675 
+...
676 
+modparam("tls", "tls_method", "TLSv1")
677 
+...
678 
+
679 
+10.2. certificate (string)
680 
+
681 
+   Sets the certificate file name. The certificate file can also contain
682 
+   the private key in PEM format.
683 
+
684 
+   If the file name starts with a '.' the path will be relative to the
685 
+   working directory (at runtime). If it starts with a '/' it will be an
686 
+   absolute path and if it starts with anything else the path will be
687 
+   relative to the main config file directory (e.g.: for kamailio -f
688 
+   /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).
689 
+
690 
+   The default value is /usr/local/etc/kamailio/cert.pem
691 
+
692 
+   Example 1.4. Set certificate parameter
693 
+...
694 
+modparam("tls", "certificate", "/usr/local/etc/kamailio/my_certificate.pem")
695 
+...
696 
+
697 
+10.3. private_key (string)
698 
+
699 
+   Sets the private key file name. The private key can be in the same file
700 
+   as the certificate or in a separate file, specified by this
701 
+   configuration parameter.
702 
+
703 
+   If the file name starts with a '.' the path will be relative to the
704 
+   working directory (at runtime). If it starts with a '/' it will be an
705 
+   absolute path and if it starts with anything else the path will be
706 
+   relative to the main config file directory (e.g.: for kamailio -f
707 
+   /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).
708 
+
709 
+   Note: the private key can be contained in the same file as the
710 
+   certificate (just append it to the certificate file, e.g.: cat pkey.pem
711 
+   >> cert.pem)
712 
+
713 
+   The default value is /usr/local/etc/kamailio/cert.pem
714 
+
715 
+   Example 1.5. Set private_key parameter
716 
+...
717 
+modparam("tls", "private_key", "/usr/local/etc/kamailio/my_pkey.pem")
718 
+...
719 
+
720 
+10.4. ca_list (string)
721 
+
722 
+   Sets the CA list file name. This file contains a list of all the
723 
+   trusted CAs certificates used when connecting to other SIP
724 
+   implementations. If a signature in a certificate chain belongs to one
725 
+   of the listed CAs, the verification of that certificate will succeed.
726 
+
727 
+   If the file name starts with a '.' the path will be relative to the
728 
+   working directory (at runtime). If it starts with a '/' it will be an
729 
+   absolute path and if it starts with anything else the path will be
730 
+   relative to the main config file directory (e.g.: for kamailio -f
731 
+   /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).
732 
+
733 
+   By default the CA file is not set.
734 
+
735 
+   An easy way to create the CA list is to append each trusted trusted CA
736 
+   certificate in the PEM format to one file, e.g.:
737 
+for f in trusted_cas/*.pem ; do cat "$f" >> ca_list.pem ; done
738 
+
739 
+   See also verify_certificate, verify_depth, require_certificate and crl.
740 
+
741 
+   Example 1.6. Set ca_list parameter
742 
+...
743 
+modparam("tls", "ca_list", "/usr/local/etc/kamailio/ca_list.pem")
744 
+...
745 
+
746 
+10.5. ca_path (str)
747 
+
748 
+   Sets the path with the trusted CA files, to be given as parameter
749 
+   SSL_CTX_load_verify_locations(). The certificates in ca_path are only
750 
+   looked up when required, e.g. when building the certificate chain or
751 
+   when actually performing the verification of a peer certificate. They
752 
+   are not given to the client (not loaded to be provided to
753 
+   SSL_CTX_set_client_CA_list()), only the ones in ca_list files are sent
754 
+   to the client. It requires to use c_rehash to generate the hash map for
755 
+   certificate search, for more see the manual of libssl for
756 
+   SSL_CTX_load_verify_locations() function.
757 
+
758 
+   By default it is not set.
759 
+
760 
+   Example 1.7. Set ca_path parameter
761 
+...
762 
+modparam("tls", "ca_path", "/usr/local/etc/kamailio/ca")
763 
+...
764 
+
765 
+10.6. crl (string)
766 
+
767 
+   Sets the certificate revocation list (CRL) file name. This file
768 
+   contains a list of revoked certificates. Any attempt to verify a
769 
+   revoked certificate will fail.
770 
+
771 
+   If not set, no CRL list will be used.
772 
+
773 
+   If the file name starts with a '.' the path will be relative to the
774 
+   working directory (at runtime). If it starts with a '/' it will be an
775 
+   absolute path and if it starts with anything else the path will be
776 
+   relative to the main config file directory (e.g.: for kamailio -f
777 
+   /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).
778 
+
779 
+Note
780 
+
781 
+   If set, require_certificate should also be set or it will not have any
782 
+   effect.
783 
+
784 
+   By default the CRL file name is not set.
785 
+
786 
+   To update the CRL in a running Kamailio, make sure you configure TLS
787 
+   via a separate TLS config file (the config modparam) and issue a
788 
+   tls.reload RPC call, e.g.:
789 
+ $ kamcmd tls.reload
790 
+
791 
+   A quick way to create the CRL in PEM format, using OpenSSL is:
792 
+ $ openssl ca -gencrl -keyfile cacert.key -cert cacert.pem -out my_crl.pem
793 
+
794 
+   my_crl.pem will contain the signed list of the revoked certificates.
795 
+
796 
+   To revoke a TLS certificate use something like:
797 
+ $ openssl ca -revoke bad_cert.pem -keyfile cacert.key -cert cacert.pem
798 
+
799 
+   and then refresh the crl file using the command above.
800 
+
801 
+   To display the CRL contents use:
802 
+ $ openssl crl -in crl.pem -noout -text
803 
+
804 
+   See also ca_list, verify_certificate, verify_depth and
805 
+   require_certificate.
806 
+
807 
+   Example 1.8. Set crl parameter
808 
+...
809 
+modparam("tls", "crl", "/usr/local/etc/kamailio/crl.pem")
810 
+...
811 
+
812 
+10.7. verify_certificate (boolean)
813 
+
814 
+   If enabled it will force certificate verification when connecting to
815 
+   other SIP servers.. For more information see the verify(1) OpenSSL man
816 
+   page.
817 
+
818 
+   Note: the certificate verification will always fail if the ca_list is
819 
+   empty.
820 
+
821 
+   See also: ca_list, require_certificate, verify_depth.
822 
+
823 
+   By default the certificate verification is off.
824 
+
825 
+   Example 1.9. Set verify_certificate parameter
826 
+...
827 
+modparam("tls", "verify_certificate", 1)
828 
+...
829 
+
830 
+10.8. verify_depth (integer)
831 
+
832 
+   Sets how far up the certificate chain will the certificate verification
833 
+   go in the search for a trusted CA.
834 
+
835 
+   See also: ca_list, require_certificate, verify_certificate,
836 
+
837 
+   The default value is 9.
838 
+
839 
+   Example 1.10. Set verify_depth parameter
840 
+...
841 
+modparam("tls", "verify_depth", 9)
842 
+...
843 
+
844 
+10.9. require_certificate (boolean)
845 
+
846 
+   When enabled Kamailio will require a certificate from a client
847 
+   connecting to the TLS port. If the client does not offer a certificate
848 
+   and verify_certificate is on, certificate verification will fail.
849 
+
850 
+   The default value is off.
851 
+
852 
+   Example 1.11. Set require_certificate parameter
853 
+...
854 
+modparam("tls", "require_certificate", 1)
855 
+...
856 
+
857 
+10.10. cipher_list (string)
858 
+
859 
+   Sets the list of accepted ciphers. The list consists of cipher strings
860 
+   separated by colons. For more information on the cipher list format see
861 
+   the cipher(1) OpenSSL man page.
862 
+
863 
+   The default value is not set (all the OpenSSL supported ciphers are
864 
+   enabled).
865 
+
866 
+   Example 1.12. Set cipher_list parameter
867 
+...
868 
+modparam("tls", "cipher_list", "HIGH")
869 
+...
870 
+
871 
+10.11. server_name (string)
872 
+
873 
+   Sets the Server Name Indication (SNI) value.
874 
+
875 
+   This is a TLS extension enabling one TLS server to serve multiple host
876 
+   names with unique certificates.
877 
+
878 
+   The default value is empty (not set).
879 
+
880 
+   Example 1.13. Set server_name parameter
881 
+...
882 
+modparam("tls", "server_name", "kamailio.org")
883 
+...
884 
+
885 
+10.12. connection_timeout (int)
886 
+
887 
+   Sets the amount of time after which an idle TLS connection will be
888 
+   closed, if no I/O ever occurred after the initial open. If an I/O event
889 
+   occurs, the timeout will be extended with tcp_connection_lifetime. The
890 
+   value is expressed in seconds.
891 
+
892 
+   The default value is 10 min.
893 
+
894 
+   If the value set is -1, the connection will never be close on idle.
895 
+
896 
+   This setting can be changed also at runtime, via the RPC interface and
897 
+   config framework. The config variable name is tls.connection_timeout.
898 
+
899 
+   Example 1.14. Set connection_timeout parameter
900 
+...
901 
+modparam("tls", "connection_timeout", 60)
902 
+...
903 
+
904 
+   Example 1.15. Set tls.connection_timeout at runtime
905 
+ $ kamcmd cfg.set_now_int tls connection_timeout 180
906 
+
907 
+10.13. tls_disable_compression (boolean)
908 
+
909 
+   If set compression over TLS will be disabled. Note that compression
910 
+   uses a lot of memory (about 10x more then with the compression
911 
+   disabled), so if you want to minimize memory usage is a good idea to
912 
+   disable it. TLS compression also expose you for the CRIME security
913 
+   vulnerability.
914 
+
915 
+   By default TLS compression is disabled.
916 
+
917 
+   Example 1.16. Set tls_disable_compression parameter
918 
+...
919 
+modparam("tls", "tls_disable_compression", 0) # enable
920 
+...
921 
+
922 
+10.14. ssl_release_buffers (integer)
923 
+
924 
+   Release internal OpenSSL read or write buffers as soon as they are no
925 
+   longer needed. Combined with ssl_freelist_max_len has the potential of
926 
+   saving a lot of memory ( ~ 32k per connection in the default
927 
+   configuration, or 16k + ssl_max_send_fragment). For Kamailio versions >
928 
+   3.0 it makes little sense to disable it (0) since the tls module
929 
+   already has its own internal buffering.
930 
+
931 
+   A value of -1 would not change this option from its openssl default.
932 
+   Use 0 or 1 for enable/disable.
933 
+
934 
+   By default the value is 1 (enabled).
935 
+
936 
+Note
937 
+
938 
+   This option is supported only for OpenSSL versions >= 1.0.0. On all the
939 
+   other versions attempting to change the default will trigger an error.
940 
+
941 
+   Example 1.17. Set ssl_release_buffers parameter
942 
+modparam("tls", "ssl_release_buffers", 1)
943 
+
944 
+10.15. ssl_freelist_max_len (integer)
945 
+
946 
+   Sets the maximum number of free memory chunks, that OpenSSL will keep
947 
+   per connection. Setting it to 0 would cause any unused memory chunk to
948 
+   be immediately freed, reducing the memory footprint. A too large value
949 
+   would result in extra memory consumption.
950 
+
951 
+   Should be combined with ssl_release_buffers.
952 
+
953 
+   A value of -1 has a special meaning: the OpenSSL default will be used
954 
+   (no attempt on changing the value will be made). For OpenSSL 1.0 the
955 
+   internal default is 32.
956 
+
957 
+   By default the value is 0 (no freelist).
958 
+
959 
+Note
960 
+
961 
+   This option is supported only for OpenSSL versions >= 1.0.0. On all the
962 
+   other versions attempting to change the default will trigger an error.
963 
+
964 
+   Example 1.18. Set ssl_freelist_max_len parameter
965 
+modparam("tls", "ssl_freelist_max_len", 0)
966 
+
967 
+10.16. ssl_max_send_fragment (integer)
968 
+
969 
+   Sets the maximum number of bytes (from the clear text) sent into one
970 
+   TLS record. Valid values are between 512 and 16384. Note however that
971 
+   even valid low values might not be big enough to allow a successful
972 
+   handshake (try minimum 1024).
973 
+
974 
+   Lower values would lead to less memory usage, but values lower then the
975 
+   typical Kamailio write size would incur a slight performance penalty.
976 
+   Good values are bigger then the size of the biggest SIP packet one
977 
+   normally expects to forward. For example in most setups 2048 would be a
978 
+   good value.
979 
+
980 
+Note
981 
+
982 
+   Values on the lower side, even if valid (> 512), might not allow for a
983 
+   successful initial handshake. This happens if the certificate does not
984 
+   fit inside one send fragment. Values lower then 1024 should not be
985 
+   used. Even with higher values, if the handshake fails, try increasing
986 
+   the value.
987 
+
988 
+   A value of -1 has a special meaning: the OpenSSL default will be used
989 
+   (no attempt on changing the value will be made).
990 
+
991 
+   By default the value is -1 (the OpenSSL default, which at least in
992 
+   OpenSSL 1.0.0 is ~ 16k).
993 
+
994 
+Note
995 
+
996 
+   This option is supported only for OpenSSL versions >= 0.9.9. On all the
997 
+   other versions attempting to change the default will trigger an error.
998 
+
999 
+   Example 1.19. Set ssl_max_send_fragment parameter
1000 
+modparam("tls", "ssl_max_send_fragment", 4096)
1001 
+
1002 
+10.17. ssl_read_ahead (boolean)
1003 
+
1004 
+   Enables read ahead, reducing the number of internal OpenSSL BIO read()
1005 
+   calls. This option has only debugging value, in normal circumstances it
1006 
+   should not be changed from the default.
1007 
+
1008 
+   When disabled OpenSSL will make at least 2 BIO read() calls per
1009 
+   received record: one to get the record header and one to get the rest
1010 
+   of the record.
1011 
+
1012 
+   The TLS module buffers internally all read()s and defines its own fast
1013 
+   BIO so enabling this option would only cause more memory consumption
1014 
+   and a minor slow-down (extra memcpy).
1015 
+
1016 
+   A value of -1 has a special meaning: the OpenSSL default will be used
1017 
+   (no attempt on changing the value will be made).
1018 
+
1019 
+   By default the value is 0 (disabled).
1020 
+
1021 
+   Example 1.20. Set ssl_read_ahead parameter
1022 
+modparam("tls", "ssl_read_ahead", 1)
1023 
+
1024 
+10.18. send_close_notify (boolean)
1025 
+
1026 
+   Enables/disables sending close notify alerts prior to closing the
1027 
+   corresponding TCP connection. Sending the close notify prior to TCP
1028 
+   shutdown is "nicer" from a TLS point of view, but it has a measurable
1029 
+   performance impact. Default: off. Can be set at runtime
1030 
+   (tls.send_close_notify).
1031 
+
1032 
+   The default value is 0 (off).
1033 
+
1034 
+   It can be changed also at runtime, via the RPC interface and config
1035 
+   framework. The config variable name is tls.send_close_notify.
1036 
+
1037 
+   Example 1.21. Set send_close_notify parameter
1038 
+...
1039 
+modparam("tls", "send_close_notify", 1)
1040 
+...
1041 
+
1042 
+   Example 1.22. Set tls.send_close_notify at runtime
1043 
+ $ kamcmd cfg.set_now_int tls send_close_notify 1
1044 
+
1045 
+10.19. con_ct_wq_max (integer)
1046 
+
1047 
+   Sets the maximum allowed per connection clear-text send queue size in
1048 
+   bytes. This queue is used when data cannot be encrypted and sent
1049 
+   immediately because of an ongoing TLS level renegotiation.
1050 
+
1051 
+   The default value is 65536 (64 Kb).
1052 
+
1053 
+   It can be changed also at runtime, via the RPC interface and config
1054 
+   framework. The config variable name is tls.con_ct_wq_max.
1055 
+
1056 
+   Example 1.23. Set con_ct_wq_max parameter
1057 
+...
1058 
+modparam("tls", "con_ct_wq_max", 1048576)
1059 
+...
1060 
+
1061 
+   Example 1.24. Set tls.con_ct_wq_max at runtime
1062 
+ $ kamcmd cfg.set_now_int tls con_ct_wq_max 1048576
1063 
+
1064 
+10.20. ct_wq_max (integer)
1065 
+
1066 
+   Sets the maximum total number of bytes queued in all the clear-text
1067 
+   send queues. These queues are used when data cannot be encrypted and
1068 
+   sent immediately because of an ongoing TLS level renegotiation.
1069 
+
1070 
+   The default value is 10485760 (10 Mb).
1071 
+
1072 
+   It can be changed also at runtime, via the RPC interface and config
1073 
+   framework. The config variable name is tls.ct_wq_max.
1074 
+
1075 
+   Example 1.25. Set ct_wq_max parameter
1076 
+...
1077 
+modparam("tls", "ct_wq_max", 4194304)
1078 
+...
1079 
+
1080 
+   Example 1.26. Set tls.ct_wq_max at runtime
1081 
+ $ kamcmd cfg.set_now_int tls ct_wq_max 4194304
1082 
+
1083 
+10.21. ct_wq_blk_size (integer)
1084 
+
1085 
+   Minimum block size for the internal clear-text send queues (debugging /
1086 
+   advanced tuning). Good values are multiple of typical datagram sizes.
1087 
+
1088 
+   The default value is 4096.
1089 
+
1090 
+   It can be changed also at runtime, via the RPC interface and config
1091 
+   framework. The config variable name is tls.ct_wq_blk_size.
1092 
+
1093 
+   Example 1.27. Set ct_wq_blk_size parameter
1094 
+...
1095 
+modparam("tls", "ct_wq_blk_size", 2048)
1096 
+...
1097 
+
1098 
+   Example 1.28. Set tls.ct_wq_max at runtime
1099 
+ $ kamcmd cfg.set_now_int tls ct_wq_blk_size 2048
1100 
+
1101 
+10.22. tls_log (int)
1102 
+
1103 
+   Sets the log level at which TLS related messages will be logged.
1104 
+
1105 
+   The default value is 3 (L_DBG).
1106 
+
1107 
+   It can be changed also at runtime, via the RPC interface and config
1108 
+   framework. The config variable name is tls.log.
1109 
+
1110 
+   Example 1.29. Set tls_log parameter
1111 
+...
1112 
+# ignore TLS messages if Kamailio is started with debug less than 10
1113 
+modparam("tls", "tls_log", 10)
1114 
+...
1115 
+
1116 
+   Example 1.30. Set tls.log at runtime
1117 
+ $ kamcmd cfg.set_now_int tls log 10
1118 
+
1119 
+10.23. tls_debug (int)
1120 
+
1121 
+   Sets the log level at which TLS debug messages will be logged. Note
1122 
+   that TLS debug messages are enabled only if the TLS module is compiled
1123 
+   with debugging enabled (e.g. -DTLS_WR_DEBUG, -DTLS_RD_DEBUG or
1124 
+   -DTLS_BIO_DEBUG).
1125 
+
1126 
+   The default value is 3 (L_DBG).
1127 
+
1128 
+   It can be changed also at runtime, via the RPC interface and config
1129 
+   framework. The config variable name is tls.debug.
1130 
+
1131 
+   Example 1.31. Set tls_debug parameter
1132 
+...
1133 
+# ignore TLS debug messages if Kamailio is started with debug less than 10
1134 
+modparam("tls", "tls_debug", 10)
1135 
+...
1136 
+
1137 
+   Example 1.32. Set tls.debug at runtime
1138 
+ $ kamcmd cfg.set_now_int tls debug 10
1139 
+
1140 
+10.24. low_mem_threshold1 (integer)
1141 
+
1142 
+   Sets the minimal free memory from which attempts to open or accept new
1143 
+   TLS connections will start to fail. The value is expressed in KB.
1144 
+
1145 
+   The default value depends on whether the OpenSSL library used handles
1146 
+   low memory situations in a good way (openssl bug #1491). As of this
1147 
+   writing this is not true for any OpenSSL version (including 0.9.8e).
1148 
+
1149 
+   If an ill-behaved OpenSSL version is detected, a very conservative
1150 
+   value is chosen, which depends on the maximum possible number of
1151 
+   simultaneously created TLS connections (and hence on the process
1152 
+   number).
1153 
+
1154 
+   The following values have a special meaning:
1155 
+     * -1 - use the default value
1156 
+     * 0 - disable (TLS connections will not fail preemptively)
1157 
+
1158 
+   It can be changed also at runtime, via the RPC interface and config
1159 
+   framework. The config variable name is tls.low_mem_threshold1.
1160 
+
1161 
+   See also tls.low_mem_threshold2.
1162 
+
1163 
+   Example 1.33. Set low_mem_threshold1 parameter
1164 
+...
1165 
+modparam("tls", "low_mem_threshold1", -1)
1166 
+...
1167 
+
1168 
+   Example 1.34. Set tls.low_mem_threshold1 at runtime
1169 
+ $ kamcmd cfg.set_now_int tls low_mem_threshold1 2048
1170 
+
1171 
+10.25. low_mem_threshold2 (integer)
1172 
+
1173 
+   Sets the minimal free memory from which TLS operations on already
1174 
+   established TLS connections will start to fail preemptively. The value
1175 
+   is expressed in KB.
1176 
+
1177 
+   The default value depends on whether the OpenSSL library used handles
1178 
+   low memory situations (openssl bug #1491). As of this writing this is
1179 
+   not true for any OpenSSL version (including 0.9.8e).
1180 
+
1181 
+   If an ill-behaved OpenSSL version is detected, a very conservative
1182 
+   value is chosen, which depends on the maximum possible number of
1183 
+   simultaneously created TLS connections (and hence on the process
1184 
+   number).
1185 
+
1186 
+   The following values have a special meaning:
1187 
+     * -1 - use the default value
1188 
+     * 0 - disable (TLS operations will not fail preemptively)
1189 
+
1190 
+   It can be changed also at runtime, via the RPC interface and config
1191 
+   framework. The config variable name is tls.low_mem_threshold2.
1192 
+
1193 
+   See also tls.low_mem_threshold1.
1194 
+
1195 
+   Example 1.35. Set tls.low_mem_threshold2 parameter
1196 
+...
1197 
+modparam("tls", "low_mem_threshold2", -1)
1198 
+...
1199 
+
1200 
+   Example 1.36. Set tls.low_mem_threshold2 at runtime
1201 
+ $ kamcmd cfg.set_now_int tls low_mem_threshold2 1024
1202 
+
1203 
+10.26. tls_force_run (boolean)
1204 
+
1205 
+   If enabled Kamailio will start even if some of the OpenSSL sanity
1206 
+   checks fail (turn it on at your own risk).
1207 
+
1208 
+   If any of the following sanity checks fail, Kamailio will not start:
1209 
+     * the version of the library the TLS module was compiled with is "too
1210 
+       different" from the library used at runtime. The versions should
1211 
+       have the same major, minor and fix level (e.g.: 0.9.8a and 0.9.8c
1212 
+       are ok, but 0.9.8 and 0.9.9 are not)
1213 
+     * the OpenSSL library used at compile time and the one used at
1214 
+       runtime have different Kerberos options
1215 
+
1216 
+   By default tls_force_run is disabled.
1217 
+
1218 
+   Example 1.37. Set tls_force_run parameter
1219 
+...
1220 
+modparam("tls", "tls_force_run", 11)
1221 
+...
1222 
+
1223 
+10.27. session_cache (boolean)
1224 
+
1225 
+   If enabled Kamailio will do caching of the TLS sessions data,
1226 
+   generation a session_id and sending it back to client.
1227 
+
1228 
+   By default TLS session caching is disabled (0).
1229 
+
1230 
+   Example 1.38. Set session_cache parameter
1231 
+...
1232 
+modparam("tls", "session_cache", 1)
1233 
+...
1234 
+
1235 
+10.28. session_id (str)
1236 
+
1237 
+   The value for session ID context, making sense when session caching is
1238 
+   enabled.
1239 
+
1240 
+   By default TLS session_id is "kamailio-tls-5.x.y".
1241 
+
1242 
+   Example 1.39. Set session_id parameter
1243 
+...
1244 
+modparam("tls", "session_id", "my-session-id-context")
1245 
+...
1246 
+
1247 
+10.29. renegotiation (boolean)
1248 
+
1249 
+   If enabled Kamailio will allow renegotiations of TLS connection
1250 
+   initiated by the client. This may expose to a security risk if the
1251 
+   client is not a trusted peer and keeps renegotiating, consuming CPU and
1252 
+   bandwidth resources.
1253 
+
1254 
+   By default TLS renegotiation is disabled (0).
1255 
+
1256 
+   Example 1.40. Set renegotiation parameter
1257 
+...
1258 
+modparam("tls", "renegotiation", 1)
1259 
+...
1260 
+
1261 
+10.30. config (string)
1262 
+
1263 
+   Sets the name of the TLS specific configuration file or configuration
1264 
+   directory.
1265 
+
1266 
+   If set the TLS module will load a special configuration file or
1267 
+   configuration files from configuration directory, in which different
1268 
+   TLS parameters can be specified on a per role (server or client) and
1269 
+   domain basis (for now only IPs). The corresponding module parameters
1270 
+   will be ignored if a separate configuration file is used.
1271 
+
1272 
+   If the file or directory name starts with a '.' the path will be
1273 
+   relative to the working directory (at runtime). If it starts with a '/'
1274 
+   it will be an absolute path and if it starts with anything else the
1275 
+   path will be relative to the main config file directory (e.g.: for
1276 
+   kamailio -f /etc/kamailio/kamailio.cfg it will be relative to
1277 
+   /etc/kamailio/).
1278 
+
1279 
+   By default no TLS configuration file is specified.
1280 
+
1281 
+   The following parameters can be set in the config file, for each
1282 
+   domain:
1283 
+     * tls_method - (str) - TLS methods
1284 
+     * verify_certificate - (bool) - see modparam
1285 
+     * require_certificate - (bool) - see modparam
1286 
+     * verify_client - (str) - see modparam
1287 
+     * private_key - (str) - see modparam
1288 
+     * certificate - (str) - see modparam
1289 
+     * verify_depth - (int) - see modparam
1290 
+     * ca_list - (str) - see modparam
1291 
+     * crl - (str) - see modparam
1292 
+     * cipher_list - (str) - see modparam
1293 
+     * server_name - (str) - SNI (server name identification)
1294 
+     * server_name_mode - (int) - how to match server_name
1295 
+     * server_id - (str) - server id
1296 
+
1297 
+   The value for server_name_mode specifies how to match the server_name
1298 
+   (SNI). If set to 1, match the domain and all its subdomains. If set to
1299 
+   2, match only the subdomains. If set to 0 (or anything else), match
1300 
+   only the domain given in server_name.
1301 
+
1302 
+   The value for server_id can be any string, being used to match TLS
1303 
+   client config profile, overriding the match on ip:port and server_name.
1304 
+   This is the recommended way for selecting a specific TLS client config