source: mod_gnutls/doc/mod_gnutls_manual.mdwn @ 0bed0a0

debian/master
Last change on this file since 0bed0a0 was 0bed0a0, checked in by Fiona Klute <fiona.klute@…>, 11 months ago

Update documentation on ALPN and HTTP/2

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