source: mod_gnutls/doc/mod_gnutls_manual.md @ adcd021

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

Small documentation updates

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