source: mod_gnutls/doc/mod_gnutls_manual.md @ facbb08

asyncio
Last change on this file since facbb08 was facbb08, checked in by Fiona Klute <fiona.klute@…>, 22 months ago

Update default priorities

This removes insecure and outdated things still included in the GnuTLS
priority set "NORMAL":

  • Plain RSA key exchange, which does not provide forward secrecy

Co-authored-by: Krista Karppinen <krista.celestia@…>

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