source: mod_gnutls/doc/mod_gnutls_manual.mdwn @ 8adfa57

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

Remove "experimental" note from Early SNI status in ./configure output

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