source: mod_gnutls/doc/mod_gnutls_manual.mdwn @ a939015

debian/masterproxy-ticket
Last change on this file since a939015 was a997449, checked in by Fiona Klute <fiona.klute@…>, 22 months ago

Document ALPN issue

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