source: mod_gnutls/doc/mod_gnutls_manual.md @ 546bf35

proxy-ticket
Last change on this file since 546bf35 was 546bf35, checked in by Fiona Klute <fiona.klute@…>, 8 months ago

Update documentation on OCSP stapling

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