source: mod_gnutls/doc/mod_gnutls_manual.md @ e932ba5

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

Do not enforce OCSP nonces by default

The reason for this change is that in practice most public CAs do not
support OCSP nonces, which is permitted by both RFC 6960 and the
CA/Browser Forum baseline requirements. In this situation enforcing
correct nonces by default makes the automatic OCSP stapling support
mostly useless, so I'm changing the default.

  • Property mode set to 100644
File size: 33.8 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### GnuTLSDHFile
177
178Use the provided PKCS \#3 encoded Diffie-Hellman parameters
179
180    GnuTLSDHFile FILEPATH
181
182Default: *none*\
183Context: server config, virtual host
184
185By default `mod_gnutls` uses the DH parameters included with GnuTLS
186corresponding to the security level of the configured private keys.
187
188If you need to use different DH parameters, you can provide a PEM file
189containing them in PKCS \#3 encoding using this option. Please see the
190"[Parameter
191generation](https://gnutls.org/manual/html_node/Parameter-generation.html)"
192section of the GnuTLS documentation for a short discussion of the
193security implications.
194
195### GnuTLSPriorities
196
197Set the allowed protocol versions, ciphers, key exchange algorithms,
198MACs and compression methods
199
200    GnuTLSPriorities NORMAL:+CIPHER_0:+CIPHER_1:...:+CIPHER_N
201
202Default: `NORMAL`\
203Context: server config, virtual host
204
205Sets the allowed protocol version(s), ciphers, key exchange methods,
206message authentication codes, and other TLS parameters for the server.
207The parameter is a GnuTLS priority string as described in the
208[the GnuTLS documentation](https://gnutls.org/manual/html_node/Priority-Strings.html).
209
210For example, to disable TLS 1.0 use `NORMAL:-VERS-TLS1.0`.
211
212### GnuTLSP11Module
213
214Load this PKCS #11 module.
215
216    GnuTLSP11Module PATH_TO_LIBRARY
217
218Default: *none*\
219Context: server config
220
221Load this PKCS #11 provider module, instead of the system
222defaults. May occur multiple times to load multiple modules.
223
224### GnuTLSPIN
225
226Set the PIN to be used to access encrypted key files or PKCS #11 objects.
227
228    GnuTLSPIN XXXXXX
229
230Default: *none*\
231Context: server config, virtual host
232
233Takes a string to be used as a PIN for the protected objects in
234a security module, or as a key to be used to decrypt PKCS #8, PKCS #12,
235or openssl encrypted keys.
236
237### GnuTLSSRKPIN
238
239Set the SRK PIN to be used to access the TPM.
240
241    GnuTLSSRKPIN XXXXXX
242
243Default: *none*\
244Context: server config, virtual host
245
246Takes a string to be used as a PIN for the protected objects in
247the TPM module.
248
249### GnuTLSExportCertificates
250
251Export the PEM encoded certificates to CGIs
252
253    GnuTLSExportCertificates [off|on|SIZE]
254
255Default: `off`\
256Context: server config, virtual host
257
258This directive configures exporting the full certificates of the
259server and the client to CGI scripts via the `SSL_SERVER_CERT` and
260`SSL_CLIENT_CERT` environment variables. The exported certificates
261will be PEM-encoded, limited to the given size. The type of the
262certificate will be exported in `SSL_SERVER_CERT_TYPE` and
263`SSL_CLIENT_CERT_TYPE`.
264
265SIZE should be an integer number of bytes, or may be written with a
266trailing `K` to indicate kibibytes.  `off` means the same thing as
267`0`, in which case the certificates will not be exported to the
268environment. `on` is an alias for `16K`. If a non-zero size is
269specified for this directive, but a certificate is too large to fit in
270the buffer, then the corresponding environment variable will contain
271the fixed string `GNUTLS_CERTIFICATE_SIZE_LIMIT_EXCEEDED`.
272
273With GnuTLSExportCertificates enabled, `mod_gnutls` exports the same
274environment variables to the CGI process as `mod_ssl`.
275
276X.509 Certificate Authentication
277--------------------------------
278
279### GnuTLSCertificateFile
280
281Set the PEM encoded server certificate or certificate chain
282
283    GnuTLSCertificateFile FILEPATH
284
285Default: *none*\
286Context: server config, virtual host
287
288FILEPATH is an absolute or relative path to a file containing the
289PEM-encoded X.509 certificate to use as this Server's End Entity (EE)
290certificate, and optionally those of the issuing Certificate
291Authorities (CAs). If the file contains multiple certificates they
292must be ordered from EE to the CA closest to the root CA.
293
294Including the full certificate chain is highly recommended because the
295CA certificates are needed for [OCSP stapling](#ocsp-stapling-configuration).
296
297Since version 0.7 this can be a PKCS #11 URL instead of a file.
298
299On Linux and other Unix-like systems you can create the file with a
300command like this (assuming "CA 1" issued the server certificate and
301has been issued by "Root CA" itself):
302
303        $ cat server.pem ca-1.pem root-ca.pem >server-chain.pem
304
305### GnuTLSKeyFile
306
307Set to the PEM Encoded Server Private Key
308
309    GnuTLSKeyFile FILEPATH
310
311Default: *none*\
312Context: server config, virtual host
313
314Takes an absolute or relative path to the Server Private Key. Set
315`GnuTLSPIN` if the key file is encrypted.
316
317Since version 0.7 this can be a PKCS #11 URL.
318
319**Security Warning:**\
320This private key must be protected. It is read while Apache is still
321running as root, and does not need to be readable by the nobody or
322apache user.
323
324### GnuTLSClientVerify
325
326Enable client certificate verification
327
328    GnuTLSClientVerify [ignore|request|require]
329
330Default: `ignore`\
331Context: server config, virtual host, directory, .htaccess
332
333This directive controls if clients need to authenticate with a
334certificate to access resources. If a mode other than `ignore` is used
335in a directory context the server may request post-handshake
336authentication (TLS 1.3 only, see below). Trusted CAs for certificate
337validation are set using [`GnuTLSClientCAFile`](#gnutlsclientcafile).
338
339`ignore`
340:   `mod_gnutls` will not request certificates from clients, and allow
341    any requests.
342
343`request`
344:   Client certificates will be requested, but requests are still
345    allowed if the client does not send one or the provided
346    certificate is invalid. If the client authenticates, the
347    certificate validation status will be stored in the
348    [`SSL_CLIENT_VERIFY`](#ssl_client_verify) environment variable and
349    can be `SUCCESS`, `FAILED` or `NONE`.
350
351`require`
352:   Client certificate authentication will be required for access. If
353    set at server or virtual host level TLS connections from clients
354    without a valid certificate will be denied. If set at directory
355    level any requests without a valid client certificate will be
356    denied with a 403 Forbidden error. The `SSL_CLIENT_VERIFY`
357    environment variable will be set to `SUCCESS` if access is
358    allowed, additional [environment
359    variables](#environment-variables) will hold details on the client
360    certificate.
361
362When using TLS 1.3 `mod_gnutls` will request [post-handshake
363authentication](https://tools.ietf.org/html/rfc8446#section-4.6.2) as
364necessary if the client announced support during the handshake. With
365TLS versions 1.2 and earlier `mod_gnutls` supports client
366authentication only during the initial handshake.
367
368If you want clients that do not support TLS 1.3 at all or do not
369support the post-handshake authentication extension to have access to
370resources that require authentication, you can set `GnuTLSClientVerify
371request` at the server or virtual host level so clients can
372authenticate during the initial handshake.
373
374### GnuTLSClientCAFile
375
376Set the PEM encoded Certificate Authority list to use for X.509 base
377client authentication
378
379    GnuTLSClientCAFile FILEPATH
380
381Default: *none*
382Context: server config, virtual host
383
384Takes an absolute or relative path to a PEM Encoded Certificate to use
385as a Certificate Authority with Client Certificate Authentication.
386This file may contain a list of trusted authorities.
387
388SRP Authentication
389------------------
390
391### GnuTLSSRPPasswdFile
392
393Set to the SRP password file for SRP ciphersuites
394
395    GnuTLSSRPPasswdFile FILEPATH
396
397Default: *none*\
398Context: server config, virtual host
399
400Takes an absolute or relative path to an SRP password file. This is
401the same format as used in libsrp.  You can generate such file using
402the command `srptool --passwd /etc/tpasswd --passwd-conf
403/etc/tpasswd.conf -u test` to set a password for user test.  This
404password file holds the username, a password verifier and the
405dependency to the SRP parameters.
406
407### GnuTLSSRPPasswdConfFile
408
409Set to the SRP password.conf file for SRP ciphersuites
410
411    GnuTLSSRPPasswdConfFile FILEPATH
412
413Default: *none*\
414Context: server config, virtual host
415
416Takes an absolute or relative path to an SRP password.conf file. This
417is the same format as used in `libsrp`.  You can generate such file
418using the command `srptool --create-conf /etc/tpasswd.conf`.  This
419file holds the SRP parameters and is associate with the password file
420(the verifiers depends on these parameters).
421
422TLS Proxy Configuration
423-----------------------
424
425### GnuTLSProxyEngine
426
427Enable TLS proxy connections for this virtual host
428
429    GnuTLSProxyEngine [on|off]
430
431Default: *off*\
432Context: virtual host
433
434This directive enables support for TLS proxy connections for a virtual
435host.
436
437### GnuTLSProxyCAFile
438
439Set to the PEM encoded Certificate Authority Certificate
440
441    GnuTLSProxyCAFile FILEPATH
442
443Default: *none*\
444Context: server config, virtual host
445
446Takes an absolute or relative path to a PEM encoded certificate to use
447as a Certificate Authority when verifying certificates provided by
448proxy back end servers. This file may contain a list of trusted
449authorities. If not set, verification of TLS back end servers will
450always fail due to lack of a trusted CA.
451
452### GnuTLSProxyCRLFile
453
454Set to the PEM encoded Certificate Revocation List
455
456    GnuTLSProxyCRLFile FILEPATH
457
458Default: *none*\
459Context: server config, virtual host
460
461Takes an absolute or relative path to a PEM encoded Certificate
462Revocation List to use when verifying certificates provided by proxy
463back end servers. The file may contain a list of CRLs.
464
465### GnuTLSProxyCertificateFile
466
467Set to the PEM encoded Client Certificate
468
469    GnuTLSProxyCertificateFile FILEPATH
470
471Default: *none*\
472Context: server config, virtual host
473
474Takes an absolute or relative path to a PEM encoded X.509 certificate
475to use as this Server's End Entity (EE) client certificate for TLS
476client authentication in proxy TLS connections. If you need to supply
477certificates for intermediate Certificate Authorities (iCAs), they
478should be listed in sequence in the file, from EE to the iCA closest
479to the root CA. Optionally, you can also include the root CA's
480certificate as the last certificate in the list.
481
482If not set, TLS client authentication will be disabled for TLS proxy
483connections. If set, `GnuTLSProxyKeyFile` must be set as well to
484provide the matching private key.
485
486### GnuTLSProxyKeyFile
487
488Set to the PEM encoded Private Key
489
490    GnuTLSProxyKeyFile FILEPATH
491
492Default: *none*\
493Context: server config, virtual host
494
495Takes an absolute or relative path to the Private Key matching the
496certificate configured using the `GnuTLSProxyCertificateFile`
497directive. This key cannot currently be password protected.
498
499**Security Warning:**\
500This private key must be protected. It is read while Apache is still
501running as root, and does not need to be readable by the nobody or
502apache user.
503
504### GnuTLSProxyPriorities
505
506Set the allowed ciphers, key exchange algorithms, MACs and compression
507methods for proxy connections
508
509    GnuTLSProxyPriorities NORMAL:+CIPHER_0:+CIPHER_1:...:+CIPHER_N
510
511Default: `NORMAL`\
512Context: server config, virtual host
513
514Sets the allowed protocol version(s), ciphers, key exchange methods,
515message authentication codes, and other TLS parameters for TLS proxy
516connections. Like for `GnuTLSPriorities` the parameter is a GnuTLS
517priority string as described in the
518[the GnuTLS documentation](https://gnutls.org/manual/html_node/Priority-Strings.html).
519
520OCSP Stapling Configuration
521---------------------------
522
523OCSP stapling, formally known as the TLS Certificate Status Request
524extension, allows the server to provide the client with a cached OCSP
525response for its certificate during the handshake. With OCSP stapling
526the client does not have to send an OCSP request to the issuer CA to
527check the certificate status, which offers privacy and performance
528advantages, and avoids the security issue of how to handle errors that
529prevent the client from getting a response.
530
531With TLS 1.2 stapling can be used only for the server certificate.
532TLS 1.3 supports stapling for all transmitted certificates.
533Mod\_gnutls will staple for as many consecutive certificates in the
534certificate chain as possible, ideally all except the root CA.
535
536Mod\_gnutls enables OCSP stapling by default if possible. The following
537requirements must be met:
538
539* OCSP responses are verified using the issuer CAs of the certificates
540  being checked, so the CAs must be included in
541  [`GnuTLSCertificateFile`](#gnutlscertificatefile). Providing the
542  whole certificate chain (including the root CA) is recommended.
543
544* Mod\_gnutls needs a cache to store OCSP responses for stapling. If
545  [mod\_socache\_shmcb](http://httpd.apache.org/docs/current/en/mod/mod_socache_shmcb.html)
546  is loaded mod\_gnutls can set up the cache without additional
547  configuration, for other options see
548  [`GnuTLSOCSPCache`](#gnutlsocspcache).
549
550* The certificates must contain OCSP access URIs using HTTP so
551  mod_gnutls can fetch responses, alternatively you may provide
552  responses using [`GnuTLSOCSPResponseFile`](#gnutlsocspresponsefile).
553
554If a server certificate contains the "must-staple" extension (X.509
555TLS Feature extension defined in [RFC
5567633](https://tools.ietf.org/html/rfc7633)) and the configuration does
557not support stapling mod_gnutls will refuse to start.
558
559By default mod\_gnutls regularly refreshes the cached OCSP responses
560in the background, see
561[`GnuTLSOCSPAutoRefresh`](#gnutlsocspautorefresh) for details.
562
563### GnuTLSOCSPStapling
564
565Enable OCSP stapling for this (virtual) host.
566
567    GnuTLSOCSPStapling [On|Off]
568
569Default: *on* if requirements are met, *off* otherwise\
570Context: server config, virtual host
571
572Stapling is activated by default if the requirements [listed
573above](#ocsp-stapling-configuration) are met.
574
575If the server certificate requires stapling ("must-staple") or
576`GnuTLSOCSPStapling` is explicitly set to `on` unmet requirements are
577an error.
578
579OCSP cache updates are serialized using the `gnutls-ocsp` mutex.
580
581### GnuTLSOCSPCache
582
583OCSP stapling cache configuration
584
585        GnuTLSOCSPCache (shmcb|memcache|...|none)[:PARAMETERS]
586
587Default: `shmcb:gnutls_ocsp_cache`\
588Context: server config
589
590This directive configures the OCSP stapling cache, and uses the same
591syntax as [`GnuTLSCache`](#gnutlscache). Please check there for
592details.
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: *off*\
647Context: server config, virtual host
648
649Most CAs do not to send nonces in their OCSP responses, probably
650because that way they can cache responses, which is [explicitly
651allowed by RFC
6526960](https://tools.ietf.org/html/rfc6960#section-2.5). You can enable
653`GnuTLSOCSPCheckNonce` to enforce nonce validation if your CA is one
654that supports OCSP nonces. Note that `mod_gnutls` will _send_ a nonce
655either way.
656
657### GnuTLSOCSPResponseFile
658
659Read OCSP responses for stapling from these files (one or more)
660instead of sending a request over HTTP.
661
662    GnuTLSOCSPResponseFile /path/to/response.der [...]
663
664Default: *empty*\
665Context: server config, virtual host
666
667The first listed file must contain a response for the server
668certificate, responses for intermediate CAs may be added in the order
669they appear in [GnuTLSCertificateFile](#gnutlscertificatefile). You
670can revert to the default fetch mechanism for a specific certificate
671(including the server certificate) by giving the empty string (`""`)
672instead of a file path.
673
674The response files must be updated externally, for example using a
675cron job. This option is an alternative to the server fetching OCSP
676responses over HTTP. Reasons to use this option include:
677
678* Performing OCSP requests separate from the web server (e.g. to share
679  responses across a server cluster).
680* The issuer CA uses an access method other than HTTP, or doesn't
681  include an OCSP URL in the certificate.
682* Testing
683
684You can use a GnuTLS `ocsptool` command like the following to create
685and update the response file:
686
687    ocsptool --ask --nonce --load-issuer ca_cert.pem \
688        --load-cert server_cert.pem --outfile ocsp_response.der
689
690Additional error checking is highly recommended. You may have to
691remove the `--nonce` option if the OCSP responder of your CA does not
692support nonces.
693
694### GnuTLSOCSPCacheTimeout
695
696Cache timeout for OCSP responses
697
698    GnuTLSOCSPCacheTimeout SECONDS
699
700Default: *3600*\
701Context: server config, virtual host
702
703Cached OCSP responses will be refreshed after the configured number of
704seconds. How long this timeout should reasonably be depends on your
705CA, namely how often its OCSP responder is updated and how long
706responses are valid. Note that a response will not be cached beyond
707its lifetime as denoted in the `nextUpdate` field of the response.
708
709### GnuTLSOCSPFailureTimeout
710
711Wait this many seconds before retrying a failed OCSP request.
712
713    GnuTLSOCSPFailureTimeout SECONDS
714
715Default: *300*\
716Context: server config, virtual host
717
718Retries of failed OCSP requests must be rate limited to avoid
719overloading both the server using mod_gnutls and the CA's OCSP
720responder. A shorter value increases the load on both sides, a longer
721one means that stapling will remain disabled for longer after a failed
722request. The auto-refresh mechanism updates OCSP responses before they
723expire and can cover short unavailability of OCSP responders, see
724[`GnuTLSOCSPAutoRefresh`](#gnutlsocspautorefresh) for details.
725
726### GnuTLSOCSPFuzzTime
727
728Update the cached OCSP response up to this time before the cache expires
729
730    GnuTLSOCSPFuzzTime SECONDS
731
732Default: *larger of GnuTLSOCSPCacheTimeout / 8 and GnuTLSOCSPFailureTimeout \* 2*\
733Context: server config, virtual host
734
735Refreshing the cached response before it expires hides short OCSP
736responder unavailability. See `GnuTLSOCSPAutoRefresh` for how this
737value is used, using at least twice `GnuTLSOCSPFailureTimeout` is
738recommended.
739
740### GnuTLSOCSPSocketTimeout
741
742Timeout for TCP sockets used to send OCSP requests
743
744    GnuTLSOCSPFailureTimeout SECONDS
745
746Default: *6*\
747Context: server config, virtual host
748
749Stalled OCSP requests must time out after a while to prevent stalling
750the server too much. However, if the timeout is too short requests may
751fail with a slow OCSP responder or high latency network
752connection. This parameter allows you to adjust the timeout if
753necessary.
754
755Note that this is not an upper limit for the completion of an OCSP
756request but a socket timeout. The connection will time out if there is
757no activity (successful send or receive) at all for the configured
758time.
759
760* * * * *
761
762Configuration Examples
763======================
764
765Minimal Example
766---------------
767
768A minimal server configuration using mod_gnutls might look like this
769(other than the default setup):
770
771```apache
772# Load mod_gnutls into Apache.
773LoadModule gnutls_module modules/mod_gnutls.so
774
775Listen 192.0.2.1:443
776
777<VirtualHost _default_:443>
778        # Standard virtual host stuff
779        DocumentRoot /www/site1.example.com/html
780        ServerName site1.example.com:443
781
782        # Minimal mod_gnutls setup: enable, and set credentials
783        GnuTLSEnable on
784        GnuTLSCertificateFile conf/tls/site1_cert_chain.pem
785        GnuTLSKeyFile conf/tls/site1_key.pem
786</VirtualHost>
787```
788
789This gives you an HTTPS site using the GnuTLS `NORMAL` set of
790ciphersuites. OCSP stapling will be enabled if the server certificate
791contains an OCSP URI, `conf/tls/site1_cert_chain.pem` contains the
792issuer certificate in addition to the server's, and
793[mod\_socache\_shmcb](http://httpd.apache.org/docs/current/en/mod/mod_socache_shmcb.html)
794is loaded. With Gnutls 3.6.4 or newer session tickets are enabled,
795too.
796
797Virtual Hosts with Server Name Indication
798-----------------------------------------
799
800`mod_gnutls` supports Server Name Indication (SNI), as specified in
801[RFC 6066, Section 3](https://tools.ietf.org/html/rfc6066#section-3).
802This allows hosting many TLS websites with a single IP address, you
803can just add virtual host configurations. All recent browsers support
804this standard. Here is an example using SNI:
805
806```apache
807# Load the module into Apache.
808LoadModule gnutls_module modules/mod_gnutls.so
809# This example server uses session tickets, no cache.
810GnuTLSSessionTickets on
811
812# SNI allows hosting multiple sites using one IP address. This
813# could also be 'Listen *:443', just like '*:80' is common for
814# non-HTTPS
815Listen 198.51.100.1:443
816
817<VirtualHost _default_:443>
818        GnuTLSEnable on
819        DocumentRoot /www/site1.example.com/html
820    ServerName site1.example.com:443
821        GnuTLSCertificateFile conf/tls/site1.crt
822        GnuTLSKeyFile conf/tls/site1.key
823</VirtualHost>
824
825<VirtualHost _default_:443>
826        GnuTLSEnable on
827        DocumentRoot /www/site2.example.com/html
828        ServerName site2.example.com:443
829        GnuTLSCertificateFile conf/tls/site2.crt
830        GnuTLSKeyFile conf/tls/site2.key
831</VirtualHost>
832
833<VirtualHost _default_:443>
834        GnuTLSEnable on
835        DocumentRoot /www/site3.example.com/html
836        ServerName site3.example.com:443
837        GnuTLSCertificateFile conf/tls/site3.crt
838        GnuTLSKeyFile conf/tls/site3.key
839        # Enable HTTP/2
840        Protocols h2 http/1.1
841</VirtualHost>
842```
843
844Virtual Hosts without SNI
845-------------------------
846
847If you need to support clients that do not use SNI, you have to use a
848unique IP address/port combination for each virtual host. In this
849example all virtual hosts use the default port for HTTPS (443) and
850different IP addresses.
851
852```apache
853# Load the module into Apache.
854LoadModule gnutls_module modules/mod_gnutls.so
855# This example server uses a session cache.
856GnuTLSCache dbm:/var/cache/www-tls-cache
857GnuTLSCacheTimeout 1200
858
859# Without SNI you need one IP Address per site. The IP addresses
860# are listed separately for clarity, you could also use "Listen 443"
861# to use that port on all available IP addresses.
862Listen 192.0.2.1:443
863Listen 192.0.2.2:443
864Listen 192.0.2.3:443
865
866<VirtualHost 192.0.2.1:443>
867        GnuTLSEnable on
868        GnuTLSPriorities SECURE128
869        DocumentRoot /www/site1.example.com/html
870        ServerName site1.example.com:443
871        GnuTLSCertificateFile conf/tls/site1.crt
872        GnuTLSKeyFile conf/tls/site1.key
873</VirtualHost>
874
875<VirtualHost 192.0.2.2:443>
876    # This virtual host enables SRP authentication
877        GnuTLSEnable on
878        GnuTLSPriorities NORMAL:+SRP
879        DocumentRoot /www/site2.example.com/html
880        ServerName site2.example.com:443
881        GnuTLSSRPPasswdFile conf/tls/tpasswd.site2
882        GnuTLSSRPPasswdConfFile conf/tls/tpasswd.site2.conf
883</VirtualHost>
884
885<VirtualHost 192.0.2.3:443>
886        # This server enables SRP and X.509 authentication.
887        GnuTLSEnable on
888        GnuTLSPriorities NORMAL:+SRP:+SRP-RSA:+SRP-DSS
889        DocumentRoot /www/site3.example.com/html
890        ServerName site3.example.com:443
891        GnuTLSCertificateFile conf/tls/site3.crt
892        GnuTLSKeyFile conf/tls/site3.key
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_VERIFY`
1001-------------------
1002
1003Verification status of the client's certificate, if any. May be
1004`SUCCESS`, `FAILED` or `NONE`. See
1005[`GnuTLSClientVerify`](#gnutlsclientverify).
1006
1007`SSL_CLIENT_V_REMAIN`
1008---------------------
1009
1010The number of days until the client's certificate is expired.
1011
1012`SSL_CLIENT_V_START`
1013--------------------
1014
1015The activation time of client's certificate.
1016
1017`SSL_CLIENT_V_END`
1018------------------
1019
1020The expiration time of client's certificate.
1021
1022`SSL_CLIENT_S_DN`
1023-----------------
1024
1025The distinguished name of client's certificate in RFC2253 format.
1026
1027`SSL_CLIENT_I_DN`
1028-----------------
1029
1030The distinguished name of the issuer of the client's certificate in
1031RFC2253 format.
1032
1033`SSL_CLIENT_S_AN%`
1034------------------
1035
1036These will contain the alternative names of the client certificate (`%` is
1037a number starting from zero).
1038
1039The values will be prepended by `DNSNAME:`, `RFC822NAME:` or `URI:`
1040depending on the type.
1041
1042If it is not supported the value `UNSUPPORTED` will be set.
1043
1044`SSL_SERVER_M_SERIAL`
1045---------------------
1046
1047The serial number of the server's certificate.
1048
1049`SSL_SERVER_M_VERSION`
1050----------------------
1051
1052The version of the server's certificate.
1053
1054`SSL_SERVER_A_SIG`
1055------------------
1056
1057The algorithm used for the signature in server's certificate.
1058
1059`SSL_SERVER_A_KEY`
1060------------------
1061
1062The public key algorithm in server's certificate.
1063
1064`SSL_SERVER_CERT`
1065------------------
1066
1067The PEM-encoded (X.509) server certificate (see the
1068`GnuTLSExportCertificates` directive).
1069
1070`SSL_SERVER_CERT_TYPE`
1071----------------------
1072
1073The certificate type will be `X.509`.
1074
1075`SSL_CLIENT_CERT`
1076------------------
1077
1078PEM-encoded (X.509) client certificate, if any (see the
1079`GnuTLSExportCertificates` directive).
1080
1081`SSL_CLIENT_CERT_TYPE`
1082----------------------
1083
1084The certificate type will be `X.509`, if any.
Note: See TracBrowser for help on using the repository browser.