source: mod_gnutls/doc/mod_gnutls_manual.mdwn @ 2246a84

debian/masterproxy-ticket
Last change on this file since 2246a84 was 2246a84, checked in by Fiona Klute <fiona.klute@…>, 3 years ago

Make automatic OCSP cache updates and fuzz time configurable

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