Browse code

tls: doc - notes about enabling debugging

- notes about compiling with debugging enabled
- document tls_debug modparam

Andrei Pelinescu-Onciul authored on 15/08/2010 16:55:15
Showing 3 changed files
... ...
@@ -14,41 +14,43 @@ Andrei Pelinescu-Onciul
14 14
    1.3. Important Notes
15 15
    1.4. Compiling the TLS Module
16 16
    1.5. TLS and Low Memory
17
-   1.6. Known Limitations
18
-   1.7. Quick Certificate Howto
19
-   1.8. Parameters
20
-
21
-        1.8.1. tls_method (string)
22
-        1.8.2. certificate (string)
23
-        1.8.3. private_key (string)
24
-        1.8.4. ca_list (string)
25
-        1.8.5. verify_certificate (boolean)
26
-        1.8.6. verify_depth (integer)
27
-        1.8.7. require_certificate (boolean)
28
-        1.8.8. cipher_list (string)
29
-        1.8.9. send_timeout (int)
30
-        1.8.10. handshake_timeout (int)
31
-        1.8.11. connection_timeout (int)
32
-        1.8.12. tls_disable_compression (boolean)
33
-        1.8.13. ssl_release_buffers (integer)
34
-        1.8.14. ssl_free_list_max_len (integer)
35
-        1.8.15. ssl_max_send_fragment (integer)
36
-        1.8.16. ssl_read_ahead (boolean)
37
-        1.8.17. send_close_notify (boolean)
38
-        1.8.18. con_ct_wq_max (integer)
39
-        1.8.19. ct_wq_max (integer)
40
-        1.8.20. ct_wq_blk_size (integer)
41
-        1.8.21. tls_log (int)
42
-        1.8.22. low_mem_threshold1 (integer)
43
-        1.8.23. low_mem_threshold2 (integer)
44
-        1.8.24. tls_force_run (boolean)
45
-        1.8.25. config (string)
46
-
47
-   1.9. Functions
48
-
49
-        1.9.1. is_peer_verified()
50
-
51
-   1.10. History
17
+   1.6. TLS Debugging
18
+   1.7. Known Limitations
19
+   1.8. Quick Certificate Howto
20
+   1.9. Parameters
21
+
22
+        1.9.1. tls_method (string)
23
+        1.9.2. certificate (string)
24
+        1.9.3. private_key (string)
25
+        1.9.4. ca_list (string)
26
+        1.9.5. verify_certificate (boolean)
27
+        1.9.6. verify_depth (integer)
28
+        1.9.7. require_certificate (boolean)
29
+        1.9.8. cipher_list (string)
30
+        1.9.9. send_timeout (int)
31
+        1.9.10. handshake_timeout (int)
32
+        1.9.11. connection_timeout (int)
33
+        1.9.12. tls_disable_compression (boolean)
34
+        1.9.13. ssl_release_buffers (integer)
35
+        1.9.14. ssl_free_list_max_len (integer)
36
+        1.9.15. ssl_max_send_fragment (integer)
37
+        1.9.16. ssl_read_ahead (boolean)
38
+        1.9.17. send_close_notify (boolean)
39
+        1.9.18. con_ct_wq_max (integer)
40
+        1.9.19. ct_wq_max (integer)
41
+        1.9.20. ct_wq_blk_size (integer)
42
+        1.9.21. tls_log (int)
43
+        1.9.22. tls_debug (int)
44
+        1.9.23. low_mem_threshold1 (integer)
45
+        1.9.24. low_mem_threshold2 (integer)
46
+        1.9.25. tls_force_run (boolean)
47
+        1.9.26. config (string)
48
+
49
+   1.10. Functions
50
+
51
+        1.10.1. is_peer_verified()
52
+
53
+   1.11. History
52 54
 
53 55
 1.1. Overview
54 56
 
... ...
@@ -163,7 +165,21 @@ make TLS_EXTRA_LIBS="-lkrb5 -lz" all include_modules=tls
163 165
    reduce openssl memory usage it to disable compression (see
164 166
    tls_disable_compression).
165 167
 
166
-1.6. Known Limitations
168
+1.6. TLS Debugging
169
+
170
+   Debugging messages can be selectively enabled by recompiling the tls
171
+   module with a combination of the following defines:
172
+     * TLS_WR_DEBUG - debug messages for the write/send part.
173
+     * TLS_RD_DEBUG - debug messages for the read/receive part.
174
+     * TLS_BIO_DEBUG - debug messages for the custom BIO.
175
+
176
+   Example 2. Compiling TLS with Debug Messages
177
+make -C modules/tls extra_defs="-DTLS_WR_DEBUG -DTLS_RD_DEBUG"
178
+
179
+   To change the level at which the debug messages are logged, change the
180
+   tls_debug module parameter.
181
+
182
+1.7. Known Limitations
167 183
 
168 184
    The private key must not encrypted (SIP-router cannot ask you for a
169 185
    password on startup).
... ...
@@ -188,7 +204,7 @@ make TLS_EXTRA_LIBS="-lkrb5 -lz" all include_modules=tls
188 204
    http://sip-router.org/docbook/sip-router/branch/master/select_list/sele
189 205
    ct_list.html#select_list.tls.
190 206
 
191
-1.7. Quick Certificate Howto
207
+1.8. Quick Certificate Howto
192 208
 
193 209
    Revision History
194 210
    Revision $Revision$ $Date$
... ...
@@ -272,12 +288,12 @@ fg:
272 288
                 modparam("tls", "require_certificate", 1)
273 289
         (for more information see the module parameters documentation)
274 290
 
275
-1.8. Parameters
291
+1.9. Parameters
276 292
 
277 293
    Revision History
278 294
    Revision $Revision$ $Date$
279 295
 
280
-1.8.1. tls_method (string)
296
+1.9.1. tls_method (string)
281 297
 
282 298
    Sets the SSL/TLS protocol method. Possible values are:
283 299
      * TLSv1 - only TLSv1 connections are accepted. This is the default
... ...
@@ -295,12 +311,12 @@ fg:
295 311
    If rfc3261 conformance is desired, TLSv1 must be used. For
296 312
    compatibility with older clients SSLv23 is a good option.
297 313
 
298
-   Example 2. Set tls_method parameter
314
+   Example 3. Set tls_method parameter
299 315
 ...
300 316
 modparam("tls", "tls_method", "TLSv1")
301 317
 ...
302 318
 
303
-1.8.2. certificate (string)
319
+1.9.2. certificate (string)
304 320
 
305 321
    Sets the certificate file name. The certificate file can also contain
306 322
    the private key in PEM format.
... ...
@@ -311,12 +327,12 @@ modparam("tls", "tls_method", "TLSv1")
311 327
 
312 328
    The default value is [SER_CFG_DIR]/cert.pem.
313 329
 
314
-   Example 3. Set certificate parameter
330
+   Example 4. Set certificate parameter
315 331
 ...
316 332
 modparam("tls", "certificate", "/usr/local/etc/ser/my_certificate.pem")
317 333
 ...
318 334
 
319
-1.8.3. private_key (string)
335
+1.9.3. private_key (string)
320 336
 
321 337
    Sets the private key file name.
322 338
 
... ...
@@ -326,12 +342,12 @@ modparam("tls", "certificate", "/usr/local/etc/ser/my_certificate.pem")
326 342
 
327 343
    The default value is [SER_CFG_DIR]/cert.pem.
328 344
 
329
-   Example 4. Set private_key parameter
345
+   Example 5. Set private_key parameter
330 346
 ...
331 347
 modparam("tls", "private", "/usr/local/etc/ser/my_pkey.pem")
332 348
 ...
333 349
 
334
-1.8.4. ca_list (string)
350
+1.9.4. ca_list (string)
335 351
 
336 352
    Sets the CA list file name. This file contains a list of all the
337 353
    trusted CAs certificates. If a signature in a certificate chain belongs
... ...
@@ -344,12 +360,12 @@ modparam("tls", "private", "/usr/local/etc/ser/my_pkey.pem")
344 360
    certificate in the PEM format to one file, e.g.: for f in
345 361
    trusted_cas/*.pem ; do cat "$f" >> ca_list.pem ; done .
346 362
 
347
-   Example 5. Set ca_list parameter
363
+   Example 6. Set ca_list parameter
348 364
 ...
349 365
 modparam("tls", "ca_list", "/usr/local/etc/ser/ca_list.pem")
350 366
 ...
351 367
 
352
-1.8.5. verify_certificate (boolean)
368
+1.9.5. verify_certificate (boolean)
353 369
 
354 370
    If enabled it will force certificate verification. For more information
355 371
    see the verify(1) openssl man page.
... ...
@@ -361,12 +377,12 @@ modparam("tls", "ca_list", "/usr/local/etc/ser/ca_list.pem")
361 377
 
362 378
    By default the certificate verification is off.
363 379
 
364
-   Example 6. Set verify_certificate parameter
380
+   Example 7. Set verify_certificate parameter
365 381
 ...
366 382
 modparam("tls", "verify_certificate", 1)
367 383
 ...
368 384
 
369
-1.8.6. verify_depth (integer)
385
+1.9.6. verify_depth (integer)
370 386
 
371 387
    Sets how far up the certificate chain will the certificate verification
372 388
    go in the search for a trusted CA.
... ...
@@ -375,12 +391,12 @@ modparam("tls", "verify_certificate", 1)
375 391
 
376 392
    The default value is 9.
377 393
 
378
-   Example 7. Set verify_depth parameter
394
+   Example 8. Set verify_depth parameter
379 395
 ...
380 396
 modparam("tls", "verify_depth", 9)
381 397
 ...
382 398
 
383
-1.8.7. require_certificate (boolean)
399
+1.9.7. require_certificate (boolean)
384 400
 
385 401
    When enabled it will require a certificate from a client. If the client
386 402
    does not offer a certificate and verify_certificate is on, the
... ...
@@ -388,12 +404,12 @@ modparam("tls", "verify_depth", 9)
388 404
 
389 405
    The default value is off.
390 406
 
391
-   Example 8. Set require_certificate parameter
407
+   Example 9. Set require_certificate parameter
392 408
 ...
393 409
 modparam("tls", "require_certificate", 1)
394 410
 ...
395 411
 
396
-1.8.8. cipher_list (string)
412
+1.9.8. cipher_list (string)
397 413
 
398 414
    Sets the list of accepted ciphers. The list consists of cipher strings
399 415
    separated by colons. For more information on the cipher list format see
... ...
@@ -402,24 +418,24 @@ modparam("tls", "require_certificate", 1)
402 418
    The default value is not set (all the Openssl supported ciphers are
403 419
    enabled).
404 420
 
405
-   Example 9. Set cipher_list parameter
421
+   Example 10. Set cipher_list parameter
406 422
 ...
407 423
 modparam("tls", "cipher_list", "HIGH")
408 424
 ...
409 425
 
410
-1.8.9. send_timeout (int)
426
+1.9.9. send_timeout (int)
411 427
 
412 428
    This parameter is obsolete and cannot be used in newer TLS versions (>
413 429
    sip-router 3.0). In these versions the send_timeout is replaced by
414 430
    tcp_send_timeout (common with all the tcp connections).
415 431
 
416
-1.8.10. handshake_timeout (int)
432
+1.9.10. handshake_timeout (int)
417 433
 
418 434
    This parameter is obsolete and cannot be used in newer TLS versions (>
419 435
    sip-router 3.0). In these versions the handshake_timeout is replaced by
420 436
    tcp_connect_timeout (common with all the tcp connections).
421 437
 
422
-1.8.11. connection_timeout (int)
438
+1.9.11. connection_timeout (int)
423 439
 
424 440
    Sets the amount of time after which an idle TLS connection will be
425 441
    closed, if no I/O ever occured after the initial open. If an I/O event
... ...
@@ -433,15 +449,15 @@ modparam("tls", "cipher_list", "HIGH")
433 449
    It can be changed also at runtime, via the RPC interface and config
434 450
    framework. The config variable name is tls.connection_timeout.
435 451
 
436
-   Example 10. Set connection_timeout parameter
452
+   Example 11. Set connection_timeout parameter
437 453
 ...
438 454
 modparam("tls", "connection_timeout", 60)
439 455
 ...
440 456
 
441
-   Example 11. Set tls.connection_timeout at runtime
457
+   Example 12. Set tls.connection_timeout at runtime
442 458
  $ sercmd cfg.set_now_int tls connection_timeout 180
443 459
 
444
-1.8.12. tls_disable_compression (boolean)
460
+1.9.12. tls_disable_compression (boolean)
445 461
 
446 462
    If set compression over SSL/TLS will be disabled. Note that compression
447 463
    uses a lot of memory (about 10x more then with the compression
... ...
@@ -450,12 +466,12 @@ modparam("tls", "connection_timeout", 60)
450 466
 
451 467
    By default compression is disabled.
452 468
 
453
-   Example 12. Set tls_disable_compression parameter
469
+   Example 13. Set tls_disable_compression parameter
454 470
 ...
455 471
 modparam("tls", "tls_disable_compression", 0) # enable
456 472
 ...
457 473
 
458
-1.8.13. ssl_release_buffers (integer)
474
+1.9.13. ssl_release_buffers (integer)
459 475
 
460 476
    Release internal OpenSSL read or write buffers as soon as they are no
461 477
    longer needed. Combined with ssl_free_list_max_len has the potential of
... ...
@@ -474,10 +490,10 @@ Note
474 490
    This option is supported only for OpenSSL versions >= 1.0.0. On all the
475 491
    other versions attempting to change the default will trigger an error.
476 492
 
477
-   Example 13. Set ssl_release_buffers parameter
493
+   Example 14. Set ssl_release_buffers parameter
478 494
 modparam("tls", "ssl_release_buffers", 1)
479 495
 
480
-1.8.14. ssl_free_list_max_len (integer)
496
+1.9.14. ssl_free_list_max_len (integer)
481 497
 
482 498
    Sets the maximum number of free memory chunks, that OpenSSL will keep
483 499
    per connection. Setting it to 0 would cause any unused memory chunk to
... ...
@@ -497,10 +513,10 @@ Note
497 513
    This option is supported only for OpenSSL versions >= 1.0.0. On all the
498 514
    other versions attempting to change the default will trigger an error.
499 515
 
500
-   Example 14. Set ssl_freelist_max_len parameter
516
+   Example 15. Set ssl_freelist_max_len parameter
501 517
 modparam("tls", "ssl_freelist_max_len", 0)
502 518
 
503
-1.8.15. ssl_max_send_fragment (integer)
519
+1.9.15. ssl_max_send_fragment (integer)
504 520
 
505 521
    Sets the maximum number of bytes (from the clear text) sent into one
506 522
    TLS or SSL record. Valid values are between 512 and 16384. Note however
... ...
@@ -532,10 +548,10 @@ Note
532 548
    This option is supported only for OpenSSL versions >= 0.9.9. On all the
533 549
    other versions attempting to change the default will trigger an error.
534 550
 
535
-   Example 15. Set ssl_max_send_fragment parameter
551
+   Example 16. Set ssl_max_send_fragment parameter
536 552
 modparam("tls", "ssl_max_send_fragment", 4096)
537 553
 
538
-1.8.16. ssl_read_ahead (boolean)
554
+1.9.16. ssl_read_ahead (boolean)
539 555
 
540 556
    Enables read ahead, reducing the number of internal OpenSSL BIO read()
541 557
    calls. This option has only debugging value, in normal circumstances it
... ...
@@ -554,10 +570,10 @@ modparam("tls", "ssl_max_send_fragment", 4096)
554 570
 
555 571
    By default the value is 0 (disabled).
556 572
 
557
-   Example 16. Set ssl_read_ahead parameter
573
+   Example 17. Set ssl_read_ahead parameter
558 574
 modparam("tls", "ssl_read_ahead", 1)
559 575
 
560
-1.8.17. send_close_notify (boolean)
576
+1.9.17. send_close_notify (boolean)
561 577
 
562 578
    Enables/disables sending close notify alerts prior to closing the
563 579
    corresponding TCP connection. Sending the close notify prior to tcp
... ...
@@ -570,15 +586,15 @@ modparam("tls", "ssl_read_ahead", 1)
570 586
    It can be changed also at runtime, via the RPC interface and config
571 587
    framework. The config variable name is tls.send_close_notify.
572 588
 
573
-   Example 17. Set send_close_notify parameter
589
+   Example 18. Set send_close_notify parameter
574 590
 ...
575 591
 modparam("tls", "send_close_notify", 1)
576 592
 ...
577 593
 
578
-   Example 18. Set tls.send_close_notify at runtime
594
+   Example 19. Set tls.send_close_notify at runtime
579 595
  $ sercmd cfg.set_now_int tls send_close_notify 1
580 596
 
581
-1.8.18. con_ct_wq_max (integer)
597
+1.9.18. con_ct_wq_max (integer)
582 598
 
583 599
    Sets the maximum allowed per connection clear-text send queue size in
584 600
    bytes. This queue is used when data cannot be encrypted and sent
... ...
@@ -589,15 +605,15 @@ modparam("tls", "send_close_notify", 1)
589 605
    It can be changed also at runtime, via the RPC interface and config
590 606
    framework. The config variable name is tls.con_ct_wq_max.
591 607
 
592
-   Example 19. Set con_ct_wq_max parameter
608
+   Example 20. Set con_ct_wq_max parameter
593 609
 ...
594 610
 modparam("tls", "con_ct_wq_max", 1048576)
595 611
 ...
596 612
 
597
-   Example 20. Set tls.con_ct_wq_max at runtime
613
+   Example 21. Set tls.con_ct_wq_max at runtime
598 614
  $ sercmd cfg.set_now_int tls con_ct_wq_max 1048576
599 615
 
600
-1.8.19. ct_wq_max (integer)
616
+1.9.19. ct_wq_max (integer)
601 617
 
602 618
    Sets the maximum total number of bytes queued in all the clear-text
603 619
    send queues. These queues are used when data cannot be encrypted and
... ...
@@ -608,15 +624,15 @@ modparam("tls", "con_ct_wq_max", 1048576)
608 624
    It can be changed also at runtime, via the RPC interface and config
609 625
    framework. The config variable name is tls.ct_wq_max.
610 626
 
611
-   Example 21. Set ct_wq_max parameter
627
+   Example 22. Set ct_wq_max parameter
612 628
 ...
613 629
 modparam("tls", "ct_wq_max", 4194304)
614 630
 ...
615 631
 
616
-   Example 22. Set tls.ct_wq_max at runtime
632
+   Example 23. Set tls.ct_wq_max at runtime
617 633
  $ sercmd cfg.set_now_int tls ct_wq_max 4194304
618 634
 
619
-1.8.20. ct_wq_blk_size (integer)
635
+1.9.20. ct_wq_blk_size (integer)
620 636
 
621 637
    Minimum block size for the internal clear-text send queues (debugging /
622 638
    advanced tunning). Good values are multiple of typical datagram sizes.
... ...
@@ -626,33 +642,54 @@ modparam("tls", "ct_wq_max", 4194304)
626 642
    It can be changed also at runtime, via the RPC interface and config
627 643
    framework. The config variable name is tls.ct_wq_blk_size.
628 644
 
629
-   Example 23. Set ct_wq_blk_size parameter
645
+   Example 24. Set ct_wq_blk_size parameter
630 646
 ...
631 647
 modparam("tls", "ct_wq_blk_size", 2048)
632 648
 ...
633 649
 
634
-   Example 24. Set tls.ct_wq_max at runtime
650
+   Example 25. Set tls.ct_wq_max at runtime
635 651
  $ sercmd cfg.set_now_int tls ct_wq_blk_size 2048
636 652
 
637
-1.8.21. tls_log (int)
653
+1.9.21. tls_log (int)
638 654
 
639 655
    Sets the log level at which TLS related messages will be logged.
640 656
 
641
-   The default value is 3.
657
+   The default value is 3 (L_DBG).
642 658
 
643 659
    It can be changed also at runtime, via the RPC interface and config
644 660
    framework. The config variable name is tls.log.
645 661
 
646
-   Example 25. Set tls_log parameter
662
+   Example 26. Set tls_log parameter
647 663
 ...
648 664
 # ignore TLS messages if SIP-router is started with debug less than 10
649 665
 modparam("tls", "tls_log", 10)
650 666
 ...
651 667
 
652
-   Example 26. Set tls.log at runtime
668
+   Example 27. Set tls.log at runtime
653 669
  $ sercmd cfg.set_now_int tls log 10
654 670
 
655
-1.8.22. low_mem_threshold1 (integer)
671
+1.9.22. tls_debug (int)
672
+
673
+   Sets the log level at which TLS debug messages will be logged. Note
674
+   that TLS debug messages are enabled only if the TLS module is compiled
675
+   with debugging enabled (e.g. -DTLS_WR_DEBUG, -DTLS_RD_DEBUG or
676
+   -DTLS_BIO_DEBUG).
677
+
678
+   The default value is 3 (L_DBG).
679
+
680
+   It can be changed also at runtime, via the RPC interface and config
681
+   framework. The config variable name is tls.debug.
682
+
683
+   Example 28. Set tls_debug parameter
684
+...
685
+# ignore TLS debug messages if SIP-router is started with debug less than 10
686
+modparam("tls", "tls_debug", 10)
687
+...
688
+
689
+   Example 29. Set tls.debug at runtime
690
+ $ sercmd cfg.set_now_int tls debug 10
691
+
692
+1.9.23. low_mem_threshold1 (integer)
656 693
 
657 694
    Sets the minimal free memory from which attempts to open or accept new
658 695
    TLS connections will start to fail. The value is expressed in KB.
... ...
@@ -675,15 +712,15 @@ modparam("tls", "tls_log", 10)
675 712
 
676 713
    See also low_mem_threshold2.
677 714
 
678
-   Example 27. Set low_mem_threshold1 parameter
715
+   Example 30. Set low_mem_threshold1 parameter
679 716
 ...
680 717
 modparam("tls", "low_mem_threshold1", -1)
681 718
 ...
682 719
 
683
-   Example 28. Set tls.low_mem_threshold1 at runtime
720
+   Example 31. Set tls.low_mem_threshold1 at runtime
684 721
  $ sercmd cfg.set_now_int tls low_mem_threshold1 2048
685 722
 
686
-1.8.23. low_mem_threshold2 (integer)
723
+1.9.24. low_mem_threshold2 (integer)
687 724
 
688 725
    Sets the minimal free memory from which TLS operations on already
689 726
    established TLS connections will start to fail preemptively. The value
... ...
@@ -707,15 +744,15 @@ modparam("tls", "low_mem_threshold1", -1)
707 744
 
708 745
    See also low_mem_threshold1.
709 746
 
710
-   Example 29. Set low_mem_threshold2 parameter
747
+   Example 32. Set low_mem_threshold2 parameter
711 748
 ...
712 749
 modparam("tls", "low_mem_threshold2", -1)
713 750
 ...
714 751
 
715
-   Example 30. Set tls.low_mem_threshold2 at runtime
752
+   Example 33. Set tls.low_mem_threshold2 at runtime
716 753
  $ sercmd cfg.set_now_int tls low_mem_threshold2 1024
717 754
 
718
-1.8.24. tls_force_run (boolean)
755
+1.9.25. tls_force_run (boolean)
719 756
 
720 757
    If enabled SIP-router will start even if some of the openssl sanity
721 758
    checks fail (turn it on at your own risk).
... ...
@@ -731,12 +768,12 @@ modparam("tls", "low_mem_threshold2", -1)
731 768
 
732 769
    By default tls_force_run is disabled.
733 770
 
734
-   Example 31. Set tls_force_run parameter
771
+   Example 34. Set tls_force_run parameter
735 772
 ...
736 773
 modparam("tls", "tls_force_run", 11)
737 774
 ...
738 775
 
739
-1.8.25. config (string)
776
+1.9.26. config (string)
740 777
 
741 778
    Sets the name of the TLS specific config file.
742 779
 
... ...
@@ -762,7 +799,7 @@ modparam("tls", "tls_force_run", 11)
762 799
    client when it initiates a new connection by itself (it connects to
763 800
    something).
764 801
 
765
-   Example 32. Short config file
802
+   Example 35. Short config file
766 803
 [server:default]
767 804
 method = TLSv1
768 805
 verify_certificate = no
... ...
@@ -788,7 +825,7 @@ ca_list = local_ca.pem
788 825
    For a more complete example check the tls.cfg distributed with the
789 826
    SIP-router source (sip_router/modules/tls/tls.cfg).
790 827
 
791
-   Example 33. Set config parameter
828
+   Example 36. Set config parameter
792 829
 ...
793 830
 modparam("tls", "config", "/usr/local/etc/ser/tls.cfg")
794 831
 ...
... ...
@@ -796,28 +833,28 @@ modparam("tls", "config", "/usr/local/etc/ser/tls.cfg")
796 833
    It can be changed also at runtime. The new config will not be loaded
797 834
    immediately, but after the first tls.reload RPC call.
798 835
 
799
-   Example 34. Change and reload tls config at runtime
836
+   Example 37. Change and reload tls config at runtime
800 837
  $ sercmd cfg.set_now_string tls config "/usr/local/etc/ser/new_tls.cfg"
801 838
  $ sercmd tls.reload
802 839
 
803
-1.9. Functions
840
+1.10. Functions
804 841
 
805 842
    Revision History
806 843
    Revision $Revision$ $Date$
807 844
 
808
-1.9.1. is_peer_verified()
845
+1.10.1. is_peer_verified()
809 846
 
810 847
    Returns true if the connection on which the message was received is TLS
811 848
    , the peer presented an X509 certificate and the certificate chain
812 849
    verified ok. It can be used only in a request route.
813 850
 
814
-   Example 35. is_peer_verified usage
851
+   Example 38. is_peer_verified usage
815 852
         if (proto==TLS && !is_peer_verified()){
816 853
                 sl_send_reply("400", "No certificate or verification failed");
817 854
                 drop;
818 855
         }
819 856
 
820
-1.10. History
857
+1.11. History
821 858
 
822 859
    Revision History
823 860
    Revision $Revision$ $Date$
... ...
@@ -565,7 +565,7 @@ modparam("tls", "ct_wq_blk_size", 2048)
565 565
 		Sets the log level at which TLS related messages will be logged.
566 566
 	</para>
567 567
 	<para>
568
-		The default value is 3.
568
+		The default value is 3 (L_DBG).
569 569
 	</para>
570 570
 	<para>
571 571
 		It can be changed also at runtime, via the RPC interface and config
... ...
@@ -589,6 +589,39 @@ modparam("tls", "tls_log", 10)
589 589
 	</section>
590 590
 
591 591
 
592
+	<section id="tls_debug">
593
+	<title><varname>tls_debug</varname> (int)</title>
594
+	<para>
595
+		Sets the log level at which TLS debug messages will be logged.
596
+		Note that TLS debug messages are enabled only if the TLS module
597
+		is compiled with debugging enabled (e.g. -DTLS_WR_DEBUG,
598
+		-DTLS_RD_DEBUG or -DTLS_BIO_DEBUG).
599
+	</para>
600
+	<para>
601
+		The default value is 3 (L_DBG).
602
+	</para>
603
+	<para>
604
+		It can be changed also at runtime, via the RPC interface and config
605
+		framework. The config variable name is tls.debug.
606
+	</para>
607
+	<example>
608
+		<title>Set <varname>tls_debug</varname> parameter</title>
609
+		<programlisting>
610
+...
611
+# ignore TLS debug messages if SIP-router is started with debug less than 10
612
+modparam("tls", "tls_debug", 10)
613
+...
614
+		</programlisting>
615
+	</example>
616
+	<example>
617
+		<title>Set <varname>tls.debug</varname> at runtime</title>
618
+		<programlisting>
619
+ $ &sercmd; cfg.set_now_int tls debug 10
620
+		</programlisting>
621
+	</example>
622
+	</section>
623
+
624
+
592 625
 <section id="low_mem_threshold1">
593 626
 	<title><varname>low_mem_threshold1</varname> (integer)</title>
594 627
 	<para>
... ...
@@ -122,6 +122,42 @@ make TLS_EXTRA_LIBS="-lkrb5 -lz" all include_modules=tls
122 122
 		</para>
123 123
 		</section>
124 124
 
125
+		<section id="tls.debugging">
126
+		<title>TLS Debugging</title>
127
+		<para>
128
+			Debugging messages can be selectively enabled by recompiling
129
+			the tls module with a combination of the following defines:
130
+			<itemizedlist>
131
+				<listitem>
132
+					<para>
133
+						TLS_WR_DEBUG - debug messages for the write/send part.
134
+					</para>
135
+				</listitem>
136
+				<listitem>
137
+					<para>
138
+						TLS_RD_DEBUG - debug messages for the read/receive
139
+						part.
140
+					</para>
141
+				</listitem>
142
+				<listitem>
143
+					<para>
144
+						TLS_BIO_DEBUG - debug messages for the custom BIO.
145
+					</para>
146
+				</listitem>
147
+			</itemizedlist>
148
+		</para>
149
+		<example>
150
+			<title>Compiling TLS with Debug Messages</title>
151
+			<programlisting>
152
+make -C modules/tls extra_defs="-DTLS_WR_DEBUG -DTLS_RD_DEBUG"
153
+			</programlisting>
154
+		</example>
155
+		<para>
156
+			To change the level at which the debug messages are logged,
157
+			change the <varname>tls_debug</varname> module parameter.
158
+		</para>
159
+		</section>
160
+
125 161
 		<section id="tls.known_limitations">
126 162
 		<title>Known Limitations</title>
127 163
 		<para>