source: mod_gnutls/doc/mod_gnutls_manual.mdwn @ 7105869

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

Update GnuTLSCache documentation

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