source: mod_gnutls/doc/mod_gnutls_manual.mdwn @ 5f15295

asynciodebian/masterproxy-ticket
Last change on this file since 5f15295 was 5f15295, checked in by Fiona Klute <fiona.klute@…>, 2 years ago

Update configuration examples

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