source: mod_gnutls/doc/mod_gnutls_manual.mdwn @ ed5d2b8

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

Update GnuTLSCacheTimeout documentation: No longer used for OCSP

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