source: mod_gnutls/doc/mod_gnutls_manual.md @ f51d359

asyncioproxy-ticket
Last change on this file since f51d359 was f51d359, checked in by Fiona Klute <fiona.klute@…>, 19 months ago

Remove obsolete restrictions on HTTP/2 from documentation

GnuTLS versions before 3.6.3 aren't supported by mod_gnutls any more,
so restrictions applying only to older versions are irrelevant.

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