source: mod_gnutls/doc/mod_gnutls_manual.md @ a4e3b2c

asyncio
Last change on this file since a4e3b2c was 4f39196, checked in by Fiona Klute <fiona.klute@…>, 7 months ago

Update documentation for the GnuTLSCache directive

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