source: mod_gnutls/doc/mod_gnutls_manual.mdwn @ 7105869

asynciodebian/masterproxy-ticket
Last change on this file since 7105869 was 7105869, checked in by Fiona Klute <fiona.klute@…>, 3 years ago

Update GnuTLSCache documentation

  • Property mode set to 100644
File size: 30.3 KB
RevLine 
[e7527b9]1% `mod_gnutls` Manual
[4ee45a1]2
3* * * * *
4
[bce7907]5`mod_gnutls` is a module for the Apache web server that provides HTTPS
[2246a84]6(HTTP over Transport Layer Security (TLS)) using the GnuTLS library.
7More information about the module can be found at
8[the project's website](https://mod.gnutls.org/).
[4ee45a1]9
10* * * * *
11
12Compilation & Installation
[2b16350]13==========================
[4ee45a1]14
[e7527b9]15`mod_gnutls` uses the `./configure && make && make install` mechanism
16common to many Open Source programs.  Most of the dirty work is
17handled by either `./configure` or Apache's `apxs` utility. If you have
18built Apache modules before, there shouldn't be any surprises for you.
19
20The interesting options you can pass to configure are:
21
22`--with-apxs=PATH`
23:   This option is used to specify the location of the apxs utility that
24    was installed as part of apache. Specify the location of the
25    binary, not the directory it is located in.
26
[dc058b8]27`--with-apu-config=PATH`
28:   Path to APR Utility Library config tool (`apu-1-config`)
[e7527b9]29
30`--help`
31:   Provides a list of all available configure options.
[4ee45a1]32
[dff57b4]33It is recommended to run `make check` before installation. If your
34system doesn't have a loopback device with IPv6 and IPv4 support or
35`localhost` does not resolve to at least one of `[::1]` and
36`127.0.0.1`, you may have to set the `TEST_HOST` or `TEST_IP`
[dc058b8]37environment variables when running `./configure` to make the test
38suite work correctly.
39
[4ee45a1]40* * * * *
41
42Integration
[2b16350]43===========
[4ee45a1]44
[2b16350]45To activate `mod_gnutls` just add the following line to your httpd.conf
[4ee45a1]46and restart Apache:
47
[2b16350]48    LoadModule gnutls_module modules/mod_gnutls.so
[4ee45a1]49
50* * * * *
51
[2b16350]52Configuration Directives
53========================
[4ee45a1]54
[df49a2d]55General Options
56---------------
57
58### GnuTLSEnable
[4ee45a1]59
[2b16350]60Enable GnuTLS for this virtual host
[4ee45a1]61
[2b16350]62    GnuTLSEnable [on|off]
[4ee45a1]63
[2b16350]64Default: *off*\
65Context: virtual host
[4ee45a1]66
[2b16350]67This directive enables SSL/TLS Encryption for a Virtual Host.
[4ee45a1]68
[df49a2d]69### GnuTLSCache
[4ee45a1]70
[743e31f]71Configure TLS Session Cache
[4ee45a1]72
[7105869]73    GnuTLSCache (shmcb|dbm|memcache|...|none)[:PARAMETERS]
[4ee45a1]74
[2b16350]75Default: `GnuTLSCache none`\
76Context: server config
[4ee45a1]77
[7105869]78This directive configures the TLS Session Cache for `mod_gnutls`. This
79could be shared between machines of different architectures. If the
80selected cache implementation is not thread-safe, access is serialized
81using the `gnutls-cache` mutex.
[4ee45a1]82
[7105869]83Which cache implementations are available depends on your Apache
84installation and configuration, `mod_gnutls` can use any socache
85provider. In general you will need to load a `mod_socache_PROVIDER`
86module. Common options are described below, please check the Apache
87HTTPD documentation for details on available providers and their
88configuration.
[4ee45a1]89
[7105869]90`shmcb`
91:   Uses a shared memory segment. This is a high performance local
92    cache. The parameter is a relative or absolute path to be used if
93    the local shared memory implementation requires one, followed by
94    the cache size in bytes enclosed in parentheses.
[c22af3a]95
[7105869]96    Example: `shmcb:cache/gnutls_cache(65536)`
[4ee45a1]97
[7105869]98`dbm`
99:   Uses a DBM cache file. The parameter is a relative or absolute
100    path to be used as the DBM cache file.
101
102    Example: `dbm:cache/gnutls_cache`
[4ee45a1]103
[2b16350]104`memcache`
[7105869]105:   Uses memcached server(s) to cache TLS session data. The parameter
106    is a comma separated list of servers (host:port). This can be used
107    to share a session cache between all servers in a cluster.
[4ee45a1]108
[7105869]109    Example: `memcache:memcache.example.com:12345,memcache2.example.com:12345`
[4ee45a1]110
[2b16350]111`none`
[7105869]112:   Turns off all caching of TLS sessions.
113
114    This can significantly reduce the performance of `mod_gnutls`
115    since even followup connections by a client must renegotiate
116    parameters instead of reusing old ones. This is the default, since
117    it requires no configuration.
[4ee45a1]118
[7105869]119    Session tickets are an alternative to using a session cache,
120    please see `GnuTLSSessionTickets`. Note that for TLS 1.3 GnuTLS
121    supports resumption using session tickets only as of version
122    3.6.4.
[4ee45a1]123
[df49a2d]124### GnuTLSCacheTimeout
[4ee45a1]125
[743e31f]126Timeout for TLS Session Cache expiration
[4ee45a1]127
[2b16350]128    GnuTLSCacheTimeout SECONDS
[4ee45a1]129
[2b16350]130Default: `GnuTLSCacheTimeout 300`\
[f52f1b4]131Context: server config, virtual host
[4ee45a1]132
[444e6ed]133Sets the timeout for TLS Session Cache entries expiration. This value
134is also used for OCSP responses if they do not contain a `nextUpdate`
135time.
[4ee45a1]136
[df49a2d]137### GnuTLSSessionTickets
[4ee45a1]138
[2b16350]139Enable Session Tickets for the server
[4ee45a1]140
[2b16350]141    GnuTLSSessionTickets [on|off]
[4ee45a1]142
[2b16350]143Default: `off`\
144Context: server config, virtual host
[4ee45a1]145
[444e6ed]146To avoid storing data for TLS session resumption the server can
147provide clients with tickets, to use on return. Tickets are an
[e9ef72c]148alternative to using a session cache, mostly used for busy servers
149with limited storage. For a pool of servers this option is not
150recommended since the tickets are bound to the issuing server only.
[4ee45a1]151
[e9ef72c]152If this option is set in the global configuration, virtual hosts
153without a `GnuTLSSessionTickets` setting will use the global setting.
154
155*Warning:* Currently the master key that protects the tickets is
156generated only on server start, and there is no mechanism to roll over
157the key. If session tickets are enabled it is highly recommened to
158restart the server regularly to protect past sessions in case an
159attacker gains access to server memory.
[4ee45a1]160
[df49a2d]161### GnuTLSClientVerify
[4ee45a1]162
[df49a2d]163Enable Client Certificate Verification
[4ee45a1]164
[2b16350]165    GnuTLSClientVerify [ignore|request|require]
[4ee45a1]166
[2b16350]167Default: `ignore`\
168Context: server config, virtual host, directory, .htaccess
[4ee45a1]169
[743e31f]170This directive controls the use of TLS Client Certificate
[2b16350]171Authentication. If used in the .htaccess context, it can force TLS
172re-negotiation.
[4ee45a1]173
[2b16350]174`ignore`
[743e31f]175:   `mod_gnutls` will ignore the contents of any TLS Client Certificates
[2b16350]176    sent. It will not request that the client sends a certificate.
[4ee45a1]177
[2b16350]178`request`
179:   The client certificate will be requested, but not required.
180    The Certificate will be validated if sent.  The output of the
181    validation status will be stored in the `SSL_CLIENT_VERIFY`
182    environment variable and can be `SUCCESS`, `FAILED` or `NONE`.
[4ee45a1]183
[2b16350]184`require`
185:   A Client certificate will be required. Any requests without a valid
186    client certificate will be denied.  The `SSL_CLIENT_VERIFY`
187    environment variable will only be set to `SUCCESS`.
[4ee45a1]188
[df49a2d]189### GnuTLSDHFile
[4ee45a1]190
[bd6591f]191Use the provided PKCS \#3 encoded Diffie-Hellman parameters
[4ee45a1]192
[2b16350]193    GnuTLSDHFile FILEPATH
[4ee45a1]194
[2b16350]195Default: *none*\
196Context: server config, virtual host
[4ee45a1]197
[bd6591f]198By default, `mod_gnutls` uses the DH parameters included with GnuTLS
199corresponding to the security level of the configured private keys if
200compiled with GnuTLS 3.5.6 or newer, and the ffdhe2048 DH group as
201defined in RFC 7919, Appendix A.1 otherwise.
202
203If you need to use different DH parameters, you can provide a PEM file
204containing them in PKCS \#3 encoding using this option. Please see the
205"[Parameter
206generation](https://gnutls.org/manual/html_node/Parameter-generation.html)"
207section of the GnuTLS documentation for a short discussion of the
208security implications.
[4ee45a1]209
[df49a2d]210### GnuTLSPriorities
[4ee45a1]211
[c3c96ca]212Set the allowed protocol versions, ciphers, key exchange algorithms,
213MACs and compression methods
[4ee45a1]214
[5409165]215    GnuTLSPriorities NORMAL:+CIPHER_0:+CIPHER_1:...:+CIPHER_N
[4ee45a1]216
[2b16350]217Default: *none*\
218Context: server config, virtual host
[4ee45a1]219
[c3c96ca]220Takes a colon separated list of protocol version, ciphers, key
221exchange methods message authentication codes, and compression methods
222to enable. The allowed keywords are specified in the
223`gnutls_priority_init()` function of GnuTLS.
[4ee45a1]224
[c3c96ca]225Please refer to [the GnuTLS documentation](https://gnutls.org/manual/html_node/Priority-Strings.html#Priority-Strings)
226for details. A few commonly used sets are listed below, note that
227their exact meaning may change with GnuTLS versions.
[4ee45a1]228
[2b16350]229`PERFORMANCE`
[c3c96ca]230:   A list with all the secure cipher combinations sorted in terms of
231    performance.
[4ee45a1]232
[2b16350]233`NORMAL`
234:   A list with all the secure cipher combinations sorted
235    with respect to security margin (subjective term).
[4ee45a1]236
[c3c96ca]237`SECURE128`
238:   A list with all the secure cipher suites that offer a security level
239    of 128-bit or more.
[4ee45a1]240
[c3c96ca]241`PFS`
242:   Only cipher suites offering perfect forward secrecy (ECDHE and DHE),
243    sorted by security margin.
[4ee45a1]244
[c3c96ca]245You can add or remove algorithms using the `+` and `!` prefixes
246respectively. For example, in order to use the `NORMAL` set but
247disable TLS 1.0 and 1.1 you can use the string
248`NORMAL:!VERS-TLS1.0:!VERS-TLS1.1`.
[4ee45a1]249
[2b16350]250You can find a list of all supported Ciphers, Versions, MACs, etc.  by
251running `gnutls-cli --list`.
[4ee45a1]252
[df49a2d]253### GnuTLSP11Module
[8873a06]254
[7764015]255Load this PKCS #11 module.
[8873a06]256
257    GnuTLSP11Module PATH_TO_LIBRARY
258
259Default: *none*\
260Context: server config
261
[9ca1f21]262Load this PKCS #11 provider module, instead of the system
263defaults. May occur multiple times to load multiple modules.
[8873a06]264
[df49a2d]265### GnuTLSPIN
[031acac]266
267Set the PIN to be used to access encrypted key files or PKCS #11 objects.
268
269    GnuTLSPIN XXXXXX
270
271Default: *none*\
272Context: server config, virtual host
273
274Takes a string to be used as a PIN for the protected objects in
275a security module, or as a key to be used to decrypt PKCS #8, PKCS #12,
276or openssl encrypted keys.
277
[df49a2d]278### GnuTLSSRKPIN
[031acac]279
[df49a2d]280Set the SRK PIN to be used to access the TPM.
[031acac]281
282    GnuTLSSRKPIN XXXXXX
283
284Default: *none*\
285Context: server config, virtual host
286
287Takes a string to be used as a PIN for the protected objects in
288the TPM module.
289
[df49a2d]290### GnuTLSExportCertificates
[4ee45a1]291
[2b16350]292Export the PEM encoded certificates to CGIs
[4ee45a1]293
[999cdec]294    GnuTLSExportCertificates [off|on|SIZE]
[4ee45a1]295
[2b16350]296Default: `off`\
297Context: server config, virtual host
[4ee45a1]298
[999cdec]299This directive configures exporting the full certificates of the
300server and the client to CGI scripts via the `SSL_SERVER_CERT` and
301`SSL_CLIENT_CERT` environment variables. The exported certificates
302will be PEM-encoded (if X.509) or ASCII-armored (if OpenPGP) up to the
303size given.  The type of the certificate will be exported in
304`SSL_SERVER_CERT_TYPE` and `SSL_CLIENT_CERT_TYPE`.
305
306SIZE should be an integer number of bytes, or may be written with a
307trailing `K` to indicate kibibytes.  `off` means the same thing as
308`0`, in which case the certificates will not be exported to the
309environment.  `on` is an alias for `16K`.  If a non-zero size is
310specified for this directive, but a certificate is too large to fit in
311the buffer, then the corresponding environment variable will contain
312the fixed string `GNUTLS_CERTIFICATE_SIZE_LIMIT_EXCEEDED`.
313
[2b16350]314With GnuTLSExportCertificates enabled, `mod_gnutls` exports the same
315environment variables to the CGI process as `mod_ssl`.
[4ee45a1]316
[df49a2d]317X.509 Certificate Authentication
318--------------------------------
319
320### GnuTLSCertificateFile
[d8ae2a0]321
[df49a2d]322Set to the PEM Encoded Server Certificate
323
324    GnuTLSCertificateFile FILEPATH
325
326Default: *none*\
327Context: server config, virtual host
328
329Takes an absolute or relative path to a PEM-encoded X.509 certificate to
330use as this Server's End Entity (EE) certificate. If you need to supply
331certificates for intermediate Certificate Authorities (iCAs), they
332should be listed in sequence in the file, from EE to the iCA closest to
333the root CA. Optionally, you can also include the root CA's certificate
334as the last certificate in the list.
335
336Since version 0.7 this can be a PKCS #11 URL.
337
338### GnuTLSKeyFile
339
340Set to the PEM Encoded Server Private Key
341
342    GnuTLSKeyFile FILEPATH
343
344Default: *none*\
345Context: server config, virtual host
346
347Takes an absolute or relative path to the Server Private Key. Set
348`GnuTLSPIN` if the key file is encrypted.
349
350Since version 0.7 this can be a PKCS #11 URL.
351
352**Security Warning:**\
353This private key must be protected. It is read while Apache is still
354running as root, and does not need to be readable by the nobody or
355apache user.
356
357### GnuTLSClientCAFile
358
359Set the PEM encoded Certificate Authority list to use for X.509 base
360client authentication
361
362    GnuTLSClientCAFile FILEPATH
363
364Default: *none*
365Context: server config, virtual host
366
367Takes an absolute or relative path to a PEM Encoded Certificate to use
368as a Certificate Authority with Client Certificate Authentication.
369This file may contain a list of trusted authorities.
370
371OpenPGP Certificate Authentication
372----------------------------------
373
[f4deac5]374*Warning:* OpenPGP support has been deprecated in GnuTLS since version
3753.5.9 and will be removed completely. Consequently, OpenPGP support in
376`mod_gnutls` is deprecated as well and will be removed in a future
377release.
378
[df49a2d]379### GnuTLSPGPCertificateFile
380
381Set to a base64 Encoded Server OpenPGP Certificate
382
383    GnuTLSPGPCertificateFile FILEPATH
384
385Default: *none*\
386Context: server config, virtual host
387
388Takes an absolute or relative path to a base64 Encoded OpenPGP
389Certificate to use as this Server's Certificate.
390
391### GnuTLSPGPKeyFile
392
393Set to the Server OpenPGP Secret Key
394
395    GnuTLSPGPKeyFile FILEPATH
396
397Default: *none*\
398Context: server config, virtual host
399
400Takes an absolute or relative path to the Server Private Key. This key
401cannot currently be password protected.
402
403**Security Warning:**\
404 This private key must be protected. It is read while Apache is still
405running as root, and does not need to be readable by the nobody or
406apache user.
407
408### GnuTLSPGPKeyringFile
409
410Set to a base64 Encoded key ring
411
412    GnuTLSPGPKeyringFile FILEPATH
413
414Default: *none*\
415Context: server config, virtual host
416
417Takes an absolute or relative path to a base64 Encoded Certificate
418list (key ring) to use as a means of verification of Client
419Certificates.  This file should contain a list of trusted signers.
420
421SRP Authentication
422------------------
423
424### GnuTLSSRPPasswdFile
425
426Set to the SRP password file for SRP ciphersuites
427
428    GnuTLSSRPPasswdFile FILEPATH
429
430Default: *none*\
431Context: server config, virtual host
432
433Takes an absolute or relative path to an SRP password file. This is
434the same format as used in libsrp.  You can generate such file using
435the command `srptool --passwd /etc/tpasswd --passwd-conf
436/etc/tpasswd.conf -u test` to set a password for user test.  This
437password file holds the username, a password verifier and the
438dependency to the SRP parameters.
439
440### GnuTLSSRPPasswdConfFile
441
442Set to the SRP password.conf file for SRP ciphersuites
443
444    GnuTLSSRPPasswdConfFile FILEPATH
445
446Default: *none*\
447Context: server config, virtual host
448
449Takes an absolute or relative path to an SRP password.conf file. This
450is the same format as used in `libsrp`.  You can generate such file
451using the command `srptool --create-conf /etc/tpasswd.conf`.  This
452file holds the SRP parameters and is associate with the password file
453(the verifiers depends on these parameters).
454
455TLS Proxy Configuration
456-----------------------
457
458### GnuTLSProxyEngine
[d8ae2a0]459
460Enable TLS proxy connections for this virtual host
461
[a2e3c33]462    GnuTLSProxyEngine [on|off]
[d8ae2a0]463
464Default: *off*\
465Context: virtual host
466
467This directive enables support for TLS proxy connections for a virtual
468host.
469
[df49a2d]470### GnuTLSProxyCAFile
[d8ae2a0]471
[809c422]472Set to the PEM encoded Certificate Authority Certificate
[d8ae2a0]473
474    GnuTLSProxyCAFile FILEPATH
475
476Default: *none*\
477Context: server config, virtual host
478
[809c422]479Takes an absolute or relative path to a PEM encoded certificate to use
[d8ae2a0]480as a Certificate Authority when verifying certificates provided by
481proxy back end servers. This file may contain a list of trusted
482authorities. If not set, verification of TLS back end servers will
483always fail due to lack of a trusted CA.
484
[df49a2d]485### GnuTLSProxyCRLFile
[809c422]486
487Set to the PEM encoded Certificate Revocation List
488
489    GnuTLSProxyCRLFile FILEPATH
490
491Default: *none*\
492Context: server config, virtual host
493
494Takes an absolute or relative path to a PEM encoded Certificate
495Revocation List to use when verifying certificates provided by proxy
496back end servers. The file may contain a list of CRLs.
497
[df49a2d]498### GnuTLSProxyCertificateFile
[d8ae2a0]499
[809c422]500Set to the PEM encoded Client Certificate
[d8ae2a0]501
502    GnuTLSProxyCertificateFile FILEPATH
503
504Default: *none*\
505Context: server config, virtual host
506
[809c422]507Takes an absolute or relative path to a PEM encoded X.509 certificate
[d8ae2a0]508to use as this Server's End Entity (EE) client certificate for TLS
509client authentication in proxy TLS connections. If you need to supply
510certificates for intermediate Certificate Authorities (iCAs), they
511should be listed in sequence in the file, from EE to the iCA closest
512to the root CA. Optionally, you can also include the root CA's
513certificate as the last certificate in the list.
514
515If not set, TLS client authentication will be disabled for TLS proxy
516connections. If set, `GnuTLSProxyKeyFile` must be set as well to
517provide the matching private key.
518
[df49a2d]519### GnuTLSProxyKeyFile
[d8ae2a0]520
[809c422]521Set to the PEM encoded Private Key
[d8ae2a0]522
523    GnuTLSProxyKeyFile FILEPATH
524
525Default: *none*\
526Context: server config, virtual host
527
528Takes an absolute or relative path to the Private Key matching the
529certificate configured using the `GnuTLSProxyCertificateFile`
530directive. This key cannot currently be password protected.
531
532**Security Warning:**\
533This private key must be protected. It is read while Apache is still
534running as root, and does not need to be readable by the nobody or
535apache user.
536
[df49a2d]537### GnuTLSProxyPriorities
[f030883]538
539Set the allowed ciphers, key exchange algorithms, MACs and compression
540methods for proxy connections
541
542    GnuTLSProxyPriorities NORMAL:+CIPHER_0:+CIPHER_1:...:+CIPHER_N
543
544Default: *none*\
545Context: server config, virtual host
546
547This option is used to set the allowed ciphers, key exchange
548algorithms, MACs and compression methods for proxy connections. It
549takes the same parameters as `GnuTLSPriorities`. Required if
[a2e3c33]550`GnuTLSProxyEngine` is `On`.
[f030883]551
[df49a2d]552OCSP Stapling Configuration
553---------------------------
554
555### GnuTLSOCSPStapling
[5a5032f]556
[0cd8f3d]557Enable OCSP stapling for this (virtual) host.
[5a5032f]558
559    GnuTLSOCSPStapling [On|Off]
560
561Default: *off*\
562Context: server config, virtual host
563
564OCSP stapling, formally known as the TLS Certificate Status Request
565extension, allows the server to provide the client with an OCSP
566response for its certificate during the handshake. This way the client
567does not have to send an OCSP request to the CA to check the
568certificate status, which offers privacy and performance advantages.
569
570Using OCSP stapling has a few requirements:
571
572* Caching OCSP responses requires a cache, so `GnuTLSCache` must not
573  be `none`.
574* `GnuTLSCertificateFile` must contain the issuer CA certificate in
575  addition to the server certificate so responses can be verified.
576* The certificate must either contain an OCSP access URI using HTTP,
577  or `GnuTLSOCSPResponseFile` must be set.
578
579OCSP cache updates are serialized using the `gnutls-ocsp` mutex.
580
[2246a84]581### GnuTLSOCSPAutoRefresh
582
583Regularly refresh cached OCSP response independent of TLS handshakes?
584
585    GnuTLSOCSPAutoRefresh [On|Off]
586
587Default: *on*\
588Context: server config, virtual host
589
590By default `mod_gnutls` will regularly refresh the cached OCSP
591response for hosts that have OCSP stapling enabled, regardless of
592whether it is used. This has advantages over updating the OCSP
593response only if a TLS handshake needs it:
594
595* Updating the cached response before it expires can hide short
596  unavailability of the OCSP responder, if a repeated request is
597  successful before the cache expires (see below).
598
599* Handshakes are not slowed down by fetching responses.
600
601The interval to the next request is determined as follows: After a
602successful OCSP request the next one is scheduled for a random period
603between `GnuTLSOCSPFuzzTime` and half of it before
604`GnuTLSOCSPCacheTimeout` expires. For example, if the cache timeout is
6053600 seconds and the fuzz time 600 seconds, the next request will be
606sent after 3000 to 3300 seconds. If the validity period of the
607response expires before then, the selected interval is halved until it
608is smaller than the time until expiry. If an OCSP request fails, it is
609retried after `GnuTLSOCSPFailureTimeout`.
610
611Regularly updating the OCSP cache requires `mod_watchdog`,
612`mod_gnutls` will fall back to updating the OCSP cache during
613handshakes if `mod_watchdog` is not available or this option is set to
614`Off`.
615
[b888e8b]616### GnuTLSOCSPCheckNonce
617
618Check the nonce in OCSP responses?
619
620    GnuTLSOCSPCheckNonce [On|Off]
621
622Default: *on*\
623Context: server config, virtual host
624
625Some CAs refuse to send nonces in their OCSP responses, probably
626because that way they can cache responses. If your CA is one of them
627you can use this flag to disable nonce verification. Note that
628`mod_gnutls` will _send_ a nonce either way.
629
[df49a2d]630### GnuTLSOCSPResponseFile
[5a5032f]631
[0cd8f3d]632Read the OCSP response for stapling from this file instead of sending
633a request over HTTP.
[5a5032f]634
635    GnuTLSOCSPResponseFile /path/to/response.der
636
637Default: *empty*\
638Context: server config, virtual host
639
640The response file must be updated externally, for example using a cron
641job. This option is an alternative to the server fetching OCSP
642responses over HTTP. Reasons to use this option include:
643
644* Performing OCSP requests separate from the web server, to prevent slow
645  responses from stalling handshakes.
646* The issuer CA uses an access method other than HTTP.
647* Testing
648
[b34a67e]649You can use a GnuTLS `ocsptool` command like the following to create
650and update the response file:
651
652    ocsptool --ask --nonce --load-issuer ca_cert.pem \
653        --load-cert server_cert.pem --outfile ocsp_response.der
654
655Additional error checking is highly recommended. You may have to
656remove the `--nonce` option if the OCSP responder of your CA does not
657support nonces.
658
[e1c094c]659### GnuTLSOCSPCacheTimeout
[5a5032f]660
[e1c094c]661Cache timeout for OCSP responses
[5a5032f]662
[e1c094c]663    GnuTLSOCSPCacheTimeout SECONDS
[5a5032f]664
[e1c094c]665Default: *3600*\
[5a5032f]666Context: server config, virtual host
667
[e1c094c]668Cached OCSP responses will be refreshed after the configured number of
669seconds. How long this timeout should reasonably be depends on your
670CA, namely how often its OCSP responder is updated and how long
671responses are valid. Note that a response will not be cached beyond
672its lifetime as denoted in the `nextUpdate` field of the response.
[5a5032f]673
[c6dda6d]674### GnuTLSOCSPFailureTimeout
675
[0cd8f3d]676Wait this many seconds before retrying a failed OCSP request.
[c6dda6d]677
678    GnuTLSOCSPFailureTimeout SECONDS
679
680Default: *300*\
681Context: server config, virtual host
682
683Retries of failed OCSP requests must be rate limited to avoid
684overloading both the server using mod_gnutls and the CA's OCSP
685responder. A shorter value increases the load on both sides, a longer
686one means that stapling will remain disabled for longer after a failed
687request.
688
[2246a84]689### GnuTLSOCSPFuzzTime
690
691Update the cached OCSP response up to this time before the cache expires
692
693    GnuTLSOCSPFuzzTime SECONDS
694
695Default: *larger of GnuTLSOCSPCacheTimeout / 8 and GnuTLSOCSPFailureTimeout \* 2*\
696Context: server config, virtual host
697
698Refreshing the cached response before it expires hides short OCSP
699responder unavailability. See `GnuTLSOCSPAutoRefresh` for how this
700value is used, using at least twice `GnuTLSOCSPFailureTimeout` is
701recommended.
702
[333bbc7]703### GnuTLSOCSPSocketTimeout
704
[0cd8f3d]705Timeout for TCP sockets used to send OCSP requests
[333bbc7]706
707    GnuTLSOCSPFailureTimeout SECONDS
708
709Default: *6*\
710Context: server config, virtual host
711
712Stalled OCSP requests must time out after a while to prevent stalling
713the server too much. However, if the timeout is too short requests may
714fail with a slow OCSP responder or high latency network
715connection. This parameter allows you to adjust the timeout if
716necessary.
717
718Note that this is not an upper limit for the completion of an OCSP
719request but a socket timeout. The connection will time out if there is
720no activity (successful send or receive) at all for the configured
721time.
722
[4ee45a1]723* * * * *
724
725Configuration Examples
[2b16350]726======================
[4ee45a1]727
[743e31f]728Simple Standard TLS Example
[2b16350]729---------------------------
[4ee45a1]730
[fc124e9]731The following is an example of simple TLS hosting, using one IP
732Addresses for each virtual host.
[4ee45a1]733
[2b16350]734     # Load the module into Apache.
735     LoadModule gnutls_module modules/mod_gnutls.so
[7105869]736     GnuTLSCache dbm:/var/cache/www-tls-cache
[2b16350]737     GnuTLSCacheTimeout 500
[fc124e9]738
739     # Without SNI you need one IP Address per-site.
740     Listen 192.0.2.1:443
741     Listen 192.0.2.2:443
742     Listen 192.0.2.3:443
743     Listen 192.0.2.4:443
744
745     <VirtualHost 192.0.2.1:443>
746         GnuTLSEnable on
747         GnuTLSPriorities SECURE128
748         DocumentRoot /www/site1.example.com/html
749         ServerName site1.example.com:443
750         GnuTLSCertificateFile conf/tls/site1.crt
751         GnuTLSKeyFile conf/tls/site1.key
[2b16350]752     </VirtualHost>
[fc124e9]753
754     <VirtualHost 192.0.2.2:443>
755         # This virtual host enables SRP authentication
756         GnuTLSEnable on
757         GnuTLSPriorities NORMAL:+SRP
758         DocumentRoot /www/site2.example.com/html
759         ServerName site2.example.com:443
760         GnuTLSSRPPasswdFile conf/tls/tpasswd.site2
761         GnuTLSSRPPasswdConfFile conf/tls/tpasswd.site2.conf
[2b16350]762     </VirtualHost>
[fc124e9]763
764     <VirtualHost 192.0.2.3:443>
765         # This server enables SRP, OpenPGP and X.509 authentication.
766         GnuTLSEnable on
767         GnuTLSPriorities NORMAL:+SRP:+SRP-RSA:+SRP-DSS:+CTYPE-OPENPGP
768         DocumentRoot /www/site3.example.com/html
769         ServerName site3.example.com:443
770         GnuTLSCertificateFile conf/tls/site3.crt
771         GnuTLSKeyFile conf/tls/site3.key
772         GnuTLSClientVerify ignore
773         GnuTLSPGPCertificateFile conf/tls/site3.pub.asc
774         GnuTLSPGPKeyFile conf/tls/site3.sec.asc
775         GnuTLSSRPPasswdFile conf/tls/tpasswd.site3
776         GnuTLSSRPPasswdConfFile conf/tls/tpasswd.site3.conf
[2b16350]777     </VirtualHost>
[fc124e9]778
779     <VirtualHost 192.0.2.4:443>
780         GnuTLSEnable on
781         # %COMPAT disables some security features to enable maximum
782         # compatibility with clients. Don't use this if you need strong
783         # security.
784         GnuTLSPriorities NORMAL:%COMPAT
785         DocumentRoot /www/site4.example.com/html
786         ServerName site4.example.com:443
787         GnuTLSCertificateFile conf/tls/site4.crt
788         GnuTLSKeyFile conf/tls/site4.key
[2b16350]789     </VirtualHost>
790
791Server Name Indication Example
792------------------------------
793
[fc124e9]794`mod_gnutls` supports "Server Name Indication", as specified in
[a09df8c]795[RFC 6066, Section 3](https://tools.ietf.org/html/rfc6066#section-3). This
796allows hosting many TLS websites with a single IP address. All recent
797browsers support this standard. Here is an example using SNI:
[2b16350]798
799     # Load the module into Apache.
800     LoadModule gnutls_module modules/mod_gnutls.so
[fc124e9]801
802     # SNI allows hosting multiple sites using one IP address. This
803     # could also be 'Listen *:443', just like '*:80' is common for
804     # non-HTTPS
805     Listen 198.51.100.1:443
806
807     <VirtualHost _default_:443>
808         GnuTLSEnable on
809         GnuTLSSessionTickets on
810         GnuTLSPriorities NORMAL
811         DocumentRoot /www/site1.example.com/html
812         ServerName site1.example.com:443
813         GnuTLSCertificateFile conf/tls/site1.crt
814         GnuTLSKeyFile conf/tls/site1.key
[2b16350]815     </VirtualHost>
[4ee45a1]816
[fc124e9]817     <VirtualHost _default_:443>
818         GnuTLSEnable on
819         GnuTLSPriorities NORMAL
820         DocumentRoot /www/site2.example.com/html
821         ServerName site2.example.com:443
822         GnuTLSCertificateFile conf/tls/site2.crt
823         GnuTLSKeyFile conf/tls/site2.key
824     </VirtualHost>
[4ee45a1]825
[fc124e9]826     <VirtualHost _default_:443>
827         GnuTLSEnable on
828         GnuTLSPriorities NORMAL
829         DocumentRoot /www/site3.example.com/html
830         ServerName site3.example.com:443
831         GnuTLSCertificateFile conf/tls/site3.crt
832         GnuTLSKeyFile conf/tls/site3.key
833     </VirtualHost>
[4ee45a1]834
[fc124e9]835     <VirtualHost _default_:443>
836         GnuTLSEnable on
837         GnuTLSPriorities NORMAL
838         DocumentRoot /www/site4.example.com/html
839         ServerName site4.example.com:443
840         GnuTLSCertificateFile conf/tls/site4.crt
841         GnuTLSKeyFile conf/tls/site4.key
842     </VirtualHost>
[2b16350]843
[fc124e9]844OCSP Stapling Example
845---------------------
[2b16350]846
[fc124e9]847This example uses an X.509 server certificate. The server will fetch
848OCSP responses from the responder listed in the certificate and store
849them im a memcached cache shared with another server.
[2b16350]850
851     # Load the module into Apache.
852     LoadModule gnutls_module modules/mod_gnutls.so
[7105869]853     GnuTLSCache memcache:192.0.2.1:11211,192.0.2.2:11211
[2b16350]854     GnuTLSCacheTimeout 600
[fc124e9]855
856     Listen 192.0.2.1:443
857
858     <VirtualHost _default_:443>
859         GnuTLSEnable          On
860         GnuTLSPriorities      NORMAL
861         DocumentRoot          /www/site1.example.com/html
862         ServerName            site1.example.com:443
863         GnuTLSCertificateFile conf/tls/site1.crt
864         GnuTLSKeyFile         conf/tls/site1.key
865         GnuTLSPriorities      NORMAL
866         GnuTLSOCSPStapling    On
[2b16350]867     </VirtualHost>
[4ee45a1]868
869* * * * *
870
[2b16350]871Environment Variables
872=====================
[4ee45a1]873
[2b16350]874`mod_gnutls` exports the following environment variables to scripts.
875These are compatible with `mod_ssl`.
[4ee45a1]876
[2b16350]877`HTTPS`
878-------
[4ee45a1]879
[2b16350]880Can be `on` or `off`
[4ee45a1]881
[2b16350]882`SSL_VERSION_LIBRARY`
883---------------------
[4ee45a1]884
[2b16350]885The version of the GnuTLS library
[4ee45a1]886
[2b16350]887`SSL_VERSION_INTERFACE`
888-----------------------
[4ee45a1]889
890The version of this module
891
[2b16350]892`SSL_PROTOCOL`
893--------------
[4ee45a1]894
[2b16350]895The SSL or TLS protocol name (such as `TLS 1.0` etc.)
[4ee45a1]896
[2b16350]897`SSL_CIPHER`
898------------
[4ee45a1]899
900The SSL or TLS cipher suite name
901
[2b16350]902`SSL_COMPRESS_METHOD`
903---------------------
[4ee45a1]904
[2b16350]905The negotiated compression method (`NULL` or `DEFLATE`)
[4ee45a1]906
[2b16350]907`SSL_SRP_USER`
908--------------
[4ee45a1]909
910The SRP username used for authentication (only set when
[2b16350]911`GnuTLSSRPPasswdFile` and `GnuTLSSRPPasswdConfFile` are configured).
[4ee45a1]912
[2b16350]913`SSL_CIPHER_USEKEYSIZE` & `SSL_CIPHER_ALGKEYSIZE`
914-------------------------------------------------
[4ee45a1]915
916The number if bits used in the used cipher algorithm.
917
918This does not fully reflect the security level since the size of
919RSA or DHE key exchange parameters affect the security level too.
920
[5674676]921`SSL_DH_PRIME_BITS`
922-------------------
923
924The number if bits in the modulus for the DH group, if DHE or static
925DH is used.
926
927This will not be set if DH is not used.
928
[2b16350]929`SSL_CIPHER_EXPORT`
930-------------------
[4ee45a1]931
[2b16350]932`True` or `False`. Whether the cipher suite negotiated is an export one.
[4ee45a1]933
[2b16350]934`SSL_SESSION_ID`
935----------------
[4ee45a1]936
937The session ID negotiated in this session. Can be the same during client
938reloads.
939
[2b16350]940`SSL_CLIENT_V_REMAIN`
941---------------------
[4ee45a1]942
943The number of days until the client's certificate is expired.
944
[2b16350]945`SSL_CLIENT_V_START`
946--------------------
[4ee45a1]947
948The activation time of client's certificate.
949
[2b16350]950`SSL_CLIENT_V_END`
951------------------
[4ee45a1]952
953The expiration time of client's certificate.
954
[2b16350]955`SSL_CLIENT_S_DN`
956-----------------
[4ee45a1]957
958The distinguished name of client's certificate in RFC2253 format.
959
[2b16350]960`SSL_CLIENT_I_DN`
961-----------------
[4ee45a1]962
[732c5733]963The distinguished name of the issuer of the client's certificate in
964RFC2253 format.
[4ee45a1]965
[2b16350]966`SSL_CLIENT_S_AN%`
967------------------
[4ee45a1]968
[2b16350]969These will contain the alternative names of the client certificate (`%` is
[4ee45a1]970a number starting from zero).
971
[2b16350]972The values will be prepended by `DNSNAME:`, `RFC822NAME:` or `URI:`
[4ee45a1]973depending on the type.
974
[2b16350]975If it is not supported the value `UNSUPPORTED` will be set.
[4ee45a1]976
[2b16350]977`SSL_SERVER_M_SERIAL`
978---------------------
[4ee45a1]979
980The serial number of the server's certificate.
981
[2b16350]982`SSL_SERVER_M_VERSION`
983----------------------
[4ee45a1]984
985The version of the server's certificate.
986
[2b16350]987`SSL_SERVER_A_SIG`
988------------------
[4ee45a1]989
990The algorithm used for the signature in server's certificate.
991
[2b16350]992`SSL_SERVER_A_KEY`
993------------------
[4ee45a1]994
995The public key algorithm in server's certificate.
996
[999cdec]997`SSL_SERVER_CERT`
[2b16350]998------------------
[4ee45a1]999
[999cdec]1000The PEM-encoded (X.509) or ASCII-armored (OpenPGP) server certificate
1001(see the `GnuTLSExportCertificates` directive).
[4ee45a1]1002
[2b16350]1003`SSL_SERVER_CERT_TYPE`
1004----------------------
[4ee45a1]1005
[2b16350]1006The certificate type can be `X.509` or `OPENPGP`.
[ac32bb5]1007
[999cdec]1008`SSL_CLIENT_CERT`
1009------------------
1010
1011The PEM-encoded (X.509) or ASCII-armored (OpenPGP) client certificate
1012(see the `GnuTLSExportCertificates` directive).
1013
[ac32bb5]1014`SSL_CLIENT_CERT_TYPE`
1015----------------------
1016
1017The certificate type can be `X.509` or `OPENPGP`.
Note: See TracBrowser for help on using the repository browser.