source: mod_gnutls/doc/mod_gnutls_manual.md

Last change on this file was 9fe353a, checked in by Fiona Klute <fiona.klute@…>, 10 months ago

Clarify GnuTLSDHFile documentation

Most people shouldn't really be using this anyway, but still.

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