source: mod_gnutls/doc/mod_gnutls_manual.mdwn @ bd6591f

asynciodebian/masterdebian/stretch-backportsproxy-ticketupstream
Last change on this file since bd6591f was bd6591f, checked in by Thomas Klute <thomas2.klute@…>, 4 years ago

Update documentation of the GnuTLSDHFile option

  • Property mode set to 100644
File size: 27.6 KB
Line 
1% `mod_gnutls` Manual
2
3* * * * *
4
5`mod_gnutls` is a module for the Apache web server that provides HTTPS
6(HTTP over Transport Layer Security (TLS) or the older Secure Sockets
7Layer (SSL)) using the GnuTLS library.  More information about the
8module can be found at [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### GnuTLSPGPCertificateFile
364
365Set to a base64 Encoded Server OpenPGP Certificate
366
367    GnuTLSPGPCertificateFile FILEPATH
368
369Default: *none*\
370Context: server config, virtual host
371
372Takes an absolute or relative path to a base64 Encoded OpenPGP
373Certificate to use as this Server's Certificate.
374
375### GnuTLSPGPKeyFile
376
377Set to the Server OpenPGP Secret Key
378
379    GnuTLSPGPKeyFile FILEPATH
380
381Default: *none*\
382Context: server config, virtual host
383
384Takes an absolute or relative path to the Server Private Key. This key
385cannot currently be password protected.
386
387**Security Warning:**\
388 This private key must be protected. It is read while Apache is still
389running as root, and does not need to be readable by the nobody or
390apache user.
391
392### GnuTLSPGPKeyringFile
393
394Set to a base64 Encoded key ring
395
396    GnuTLSPGPKeyringFile FILEPATH
397
398Default: *none*\
399Context: server config, virtual host
400
401Takes an absolute or relative path to a base64 Encoded Certificate
402list (key ring) to use as a means of verification of Client
403Certificates.  This file should contain a list of trusted signers.
404
405SRP Authentication
406------------------
407
408### GnuTLSSRPPasswdFile
409
410Set to the SRP password file for SRP ciphersuites
411
412    GnuTLSSRPPasswdFile FILEPATH
413
414Default: *none*\
415Context: server config, virtual host
416
417Takes an absolute or relative path to an SRP password file. This is
418the same format as used in libsrp.  You can generate such file using
419the command `srptool --passwd /etc/tpasswd --passwd-conf
420/etc/tpasswd.conf -u test` to set a password for user test.  This
421password file holds the username, a password verifier and the
422dependency to the SRP parameters.
423
424### GnuTLSSRPPasswdConfFile
425
426Set to the SRP password.conf file for SRP ciphersuites
427
428    GnuTLSSRPPasswdConfFile FILEPATH
429
430Default: *none*\
431Context: server config, virtual host
432
433Takes an absolute or relative path to an SRP password.conf file. This
434is the same format as used in `libsrp`.  You can generate such file
435using the command `srptool --create-conf /etc/tpasswd.conf`.  This
436file holds the SRP parameters and is associate with the password file
437(the verifiers depends on these parameters).
438
439TLS Proxy Configuration
440-----------------------
441
442### GnuTLSProxyEngine
443
444Enable TLS proxy connections for this virtual host
445
446    GnuTLSProxyEngine [on|off]
447
448Default: *off*\
449Context: virtual host
450
451This directive enables support for TLS proxy connections for a virtual
452host.
453
454### GnuTLSProxyCAFile
455
456Set to the PEM encoded Certificate Authority Certificate
457
458    GnuTLSProxyCAFile FILEPATH
459
460Default: *none*\
461Context: server config, virtual host
462
463Takes an absolute or relative path to a PEM encoded certificate to use
464as a Certificate Authority when verifying certificates provided by
465proxy back end servers. This file may contain a list of trusted
466authorities. If not set, verification of TLS back end servers will
467always fail due to lack of a trusted CA.
468
469### GnuTLSProxyCRLFile
470
471Set to the PEM encoded Certificate Revocation List
472
473    GnuTLSProxyCRLFile FILEPATH
474
475Default: *none*\
476Context: server config, virtual host
477
478Takes an absolute or relative path to a PEM encoded Certificate
479Revocation List to use when verifying certificates provided by proxy
480back end servers. The file may contain a list of CRLs.
481
482### GnuTLSProxyCertificateFile
483
484Set to the PEM encoded Client Certificate
485
486    GnuTLSProxyCertificateFile FILEPATH
487
488Default: *none*\
489Context: server config, virtual host
490
491Takes an absolute or relative path to a PEM encoded X.509 certificate
492to use as this Server's End Entity (EE) client certificate for TLS
493client authentication in proxy TLS connections. If you need to supply
494certificates for intermediate Certificate Authorities (iCAs), they
495should be listed in sequence in the file, from EE to the iCA closest
496to the root CA. Optionally, you can also include the root CA's
497certificate as the last certificate in the list.
498
499If not set, TLS client authentication will be disabled for TLS proxy
500connections. If set, `GnuTLSProxyKeyFile` must be set as well to
501provide the matching private key.
502
503### GnuTLSProxyKeyFile
504
505Set to the PEM encoded Private Key
506
507    GnuTLSProxyKeyFile FILEPATH
508
509Default: *none*\
510Context: server config, virtual host
511
512Takes an absolute or relative path to the Private Key matching the
513certificate configured using the `GnuTLSProxyCertificateFile`
514directive. This key cannot currently be password protected.
515
516**Security Warning:**\
517This private key must be protected. It is read while Apache is still
518running as root, and does not need to be readable by the nobody or
519apache user.
520
521### GnuTLSProxyPriorities
522
523Set the allowed ciphers, key exchange algorithms, MACs and compression
524methods for proxy connections
525
526    GnuTLSProxyPriorities NORMAL:+CIPHER_0:+CIPHER_1:...:+CIPHER_N
527
528Default: *none*\
529Context: server config, virtual host
530
531This option is used to set the allowed ciphers, key exchange
532algorithms, MACs and compression methods for proxy connections. It
533takes the same parameters as `GnuTLSPriorities`. Required if
534`GnuTLSProxyEngine` is `On`.
535
536OCSP Stapling Configuration
537---------------------------
538
539### GnuTLSOCSPStapling
540
541Enable OCSP stapling for this (virtual) host.
542
543    GnuTLSOCSPStapling [On|Off]
544
545Default: *off*\
546Context: server config, virtual host
547
548OCSP stapling, formally known as the TLS Certificate Status Request
549extension, allows the server to provide the client with an OCSP
550response for its certificate during the handshake. This way the client
551does not have to send an OCSP request to the CA to check the
552certificate status, which offers privacy and performance advantages.
553
554Using OCSP stapling has a few requirements:
555
556* Caching OCSP responses requires a cache, so `GnuTLSCache` must not
557  be `none`.
558* `GnuTLSCertificateFile` must contain the issuer CA certificate in
559  addition to the server certificate so responses can be verified.
560* The certificate must either contain an OCSP access URI using HTTP,
561  or `GnuTLSOCSPResponseFile` must be set.
562
563OCSP cache updates are serialized using the `gnutls-ocsp` mutex.
564
565### GnuTLSOCSPCheckNonce
566
567Check the nonce in OCSP responses?
568
569    GnuTLSOCSPCheckNonce [On|Off]
570
571Default: *on*\
572Context: server config, virtual host
573
574Some CAs refuse to send nonces in their OCSP responses, probably
575because that way they can cache responses. If your CA is one of them
576you can use this flag to disable nonce verification. Note that
577`mod_gnutls` will _send_ a nonce either way.
578
579### GnuTLSOCSPResponseFile
580
581Read the OCSP response for stapling from this file instead of sending
582a request over HTTP.
583
584    GnuTLSOCSPResponseFile /path/to/response.der
585
586Default: *empty*\
587Context: server config, virtual host
588
589The response file must be updated externally, for example using a cron
590job. This option is an alternative to the server fetching OCSP
591responses over HTTP. Reasons to use this option include:
592
593* Performing OCSP requests separate from the web server, to prevent slow
594  responses from stalling handshakes.
595* The issuer CA uses an access method other than HTTP.
596* Testing
597
598You can use a GnuTLS `ocsptool` command like the following to create
599and update the response file:
600
601    ocsptool --ask --nonce --load-issuer ca_cert.pem \
602        --load-cert server_cert.pem --outfile ocsp_response.der
603
604Additional error checking is highly recommended. You may have to
605remove the `--nonce` option if the OCSP responder of your CA does not
606support nonces.
607
608### GnuTLSOCSPCacheTimeout
609
610Cache timeout for OCSP responses
611
612    GnuTLSOCSPCacheTimeout SECONDS
613
614Default: *3600*\
615Context: server config, virtual host
616
617Cached OCSP responses will be refreshed after the configured number of
618seconds. How long this timeout should reasonably be depends on your
619CA, namely how often its OCSP responder is updated and how long
620responses are valid. Note that a response will not be cached beyond
621its lifetime as denoted in the `nextUpdate` field of the response.
622
623### GnuTLSOCSPFailureTimeout
624
625Wait this many seconds before retrying a failed OCSP request.
626
627    GnuTLSOCSPFailureTimeout SECONDS
628
629Default: *300*\
630Context: server config, virtual host
631
632Retries of failed OCSP requests must be rate limited to avoid
633overloading both the server using mod_gnutls and the CA's OCSP
634responder. A shorter value increases the load on both sides, a longer
635one means that stapling will remain disabled for longer after a failed
636request.
637
638### GnuTLSOCSPSocketTimeout
639
640Timeout for TCP sockets used to send OCSP requests
641
642    GnuTLSOCSPFailureTimeout SECONDS
643
644Default: *6*\
645Context: server config, virtual host
646
647Stalled OCSP requests must time out after a while to prevent stalling
648the server too much. However, if the timeout is too short requests may
649fail with a slow OCSP responder or high latency network
650connection. This parameter allows you to adjust the timeout if
651necessary.
652
653Note that this is not an upper limit for the completion of an OCSP
654request but a socket timeout. The connection will time out if there is
655no activity (successful send or receive) at all for the configured
656time.
657
658* * * * *
659
660Configuration Examples
661======================
662
663Simple Standard TLS Example
664---------------------------
665
666The following is an example of simple TLS hosting, using one IP
667Addresses for each virtual host.
668
669     # Load the module into Apache.
670     LoadModule gnutls_module modules/mod_gnutls.so
671     GnuTLSCache gdbm /var/cache/www-tls-cache
672     GnuTLSCacheTimeout 500
673
674     # Without SNI you need one IP Address per-site.
675     Listen 192.0.2.1:443
676     Listen 192.0.2.2:443
677     Listen 192.0.2.3:443
678     Listen 192.0.2.4:443
679
680     <VirtualHost 192.0.2.1:443>
681         GnuTLSEnable on
682         GnuTLSPriorities SECURE128
683         DocumentRoot /www/site1.example.com/html
684         ServerName site1.example.com:443
685         GnuTLSCertificateFile conf/tls/site1.crt
686         GnuTLSKeyFile conf/tls/site1.key
687     </VirtualHost>
688
689     <VirtualHost 192.0.2.2:443>
690         # This virtual host enables SRP authentication
691         GnuTLSEnable on
692         GnuTLSPriorities NORMAL:+SRP
693         DocumentRoot /www/site2.example.com/html
694         ServerName site2.example.com:443
695         GnuTLSSRPPasswdFile conf/tls/tpasswd.site2
696         GnuTLSSRPPasswdConfFile conf/tls/tpasswd.site2.conf
697     </VirtualHost>
698
699     <VirtualHost 192.0.2.3:443>
700         # This server enables SRP, OpenPGP and X.509 authentication.
701         GnuTLSEnable on
702         GnuTLSPriorities NORMAL:+SRP:+SRP-RSA:+SRP-DSS:+CTYPE-OPENPGP
703         DocumentRoot /www/site3.example.com/html
704         ServerName site3.example.com:443
705         GnuTLSCertificateFile conf/tls/site3.crt
706         GnuTLSKeyFile conf/tls/site3.key
707         GnuTLSClientVerify ignore
708         GnuTLSPGPCertificateFile conf/tls/site3.pub.asc
709         GnuTLSPGPKeyFile conf/tls/site3.sec.asc
710         GnuTLSSRPPasswdFile conf/tls/tpasswd.site3
711         GnuTLSSRPPasswdConfFile conf/tls/tpasswd.site3.conf
712     </VirtualHost>
713
714     <VirtualHost 192.0.2.4:443>
715         GnuTLSEnable on
716         # %COMPAT disables some security features to enable maximum
717         # compatibility with clients. Don't use this if you need strong
718         # security.
719         GnuTLSPriorities NORMAL:%COMPAT
720         DocumentRoot /www/site4.example.com/html
721         ServerName site4.example.com:443
722         GnuTLSCertificateFile conf/tls/site4.crt
723         GnuTLSKeyFile conf/tls/site4.key
724     </VirtualHost>
725
726Server Name Indication Example
727------------------------------
728
729`mod_gnutls` supports "Server Name Indication", as specified in
730RFC 3546. This allows hosting many TLS websites with a single IP
731address. All recent browsers support this standard. Here is an
732example using SNI:
733
734     # Load the module into Apache.
735     LoadModule gnutls_module modules/mod_gnutls.so
736
737     # SNI allows hosting multiple sites using one IP address. This
738     # could also be 'Listen *:443', just like '*:80' is common for
739     # non-HTTPS
740     Listen 198.51.100.1:443
741
742     <VirtualHost _default_:443>
743         GnuTLSEnable on
744         GnuTLSSessionTickets on
745         GnuTLSPriorities NORMAL
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 _default_:443>
753         GnuTLSEnable on
754         GnuTLSPriorities NORMAL
755         DocumentRoot /www/site2.example.com/html
756         ServerName site2.example.com:443
757         GnuTLSCertificateFile conf/tls/site2.crt
758         GnuTLSKeyFile conf/tls/site2.key
759     </VirtualHost>
760
761     <VirtualHost _default_:443>
762         GnuTLSEnable on
763         GnuTLSPriorities NORMAL
764         DocumentRoot /www/site3.example.com/html
765         ServerName site3.example.com:443
766         GnuTLSCertificateFile conf/tls/site3.crt
767         GnuTLSKeyFile conf/tls/site3.key
768     </VirtualHost>
769
770     <VirtualHost _default_:443>
771         GnuTLSEnable on
772         GnuTLSPriorities NORMAL
773         DocumentRoot /www/site4.example.com/html
774         ServerName site4.example.com:443
775         GnuTLSCertificateFile conf/tls/site4.crt
776         GnuTLSKeyFile conf/tls/site4.key
777     </VirtualHost>
778
779OCSP Stapling Example
780---------------------
781
782This example uses an X.509 server certificate. The server will fetch
783OCSP responses from the responder listed in the certificate and store
784them im a memcached cache shared with another server.
785
786     # Load the module into Apache.
787     LoadModule gnutls_module modules/mod_gnutls.so
788     GnuTLSCache memcache "192.0.2.1:11211 192.0.2.2:11211"
789     GnuTLSCacheTimeout 600
790
791     Listen 192.0.2.1:443
792
793     <VirtualHost _default_:443>
794         GnuTLSEnable          On
795         GnuTLSPriorities      NORMAL
796         DocumentRoot          /www/site1.example.com/html
797         ServerName            site1.example.com:443
798         GnuTLSCertificateFile conf/tls/site1.crt
799         GnuTLSKeyFile         conf/tls/site1.key
800         GnuTLSPriorities      NORMAL
801         GnuTLSOCSPStapling    On
802     </VirtualHost>
803
804* * * * *
805
806Environment Variables
807=====================
808
809`mod_gnutls` exports the following environment variables to scripts.
810These are compatible with `mod_ssl`.
811
812`HTTPS`
813-------
814
815Can be `on` or `off`
816
817`SSL_VERSION_LIBRARY`
818---------------------
819
820The version of the GnuTLS library
821
822`SSL_VERSION_INTERFACE`
823-----------------------
824
825The version of this module
826
827`SSL_PROTOCOL`
828--------------
829
830The SSL or TLS protocol name (such as `TLS 1.0` etc.)
831
832`SSL_CIPHER`
833------------
834
835The SSL or TLS cipher suite name
836
837`SSL_COMPRESS_METHOD`
838---------------------
839
840The negotiated compression method (`NULL` or `DEFLATE`)
841
842`SSL_SRP_USER`
843--------------
844
845The SRP username used for authentication (only set when
846`GnuTLSSRPPasswdFile` and `GnuTLSSRPPasswdConfFile` are configured).
847
848`SSL_CIPHER_USEKEYSIZE` & `SSL_CIPHER_ALGKEYSIZE`
849-------------------------------------------------
850
851The number if bits used in the used cipher algorithm.
852
853This does not fully reflect the security level since the size of
854RSA or DHE key exchange parameters affect the security level too.
855
856`SSL_DH_PRIME_BITS`
857-------------------
858
859The number if bits in the modulus for the DH group, if DHE or static
860DH is used.
861
862This will not be set if DH is not used.
863
864`SSL_CIPHER_EXPORT`
865-------------------
866
867`True` or `False`. Whether the cipher suite negotiated is an export one.
868
869`SSL_SESSION_ID`
870----------------
871
872The session ID negotiated in this session. Can be the same during client
873reloads.
874
875`SSL_CLIENT_V_REMAIN`
876---------------------
877
878The number of days until the client's certificate is expired.
879
880`SSL_CLIENT_V_START`
881--------------------
882
883The activation time of client's certificate.
884
885`SSL_CLIENT_V_END`
886------------------
887
888The expiration time of client's certificate.
889
890`SSL_CLIENT_S_DN`
891-----------------
892
893The distinguished name of client's certificate in RFC2253 format.
894
895`SSL_CLIENT_I_DN`
896-----------------
897
898The SSL or TLS cipher suite name
899
900`SSL_CLIENT_S_AN%`
901------------------
902
903These will contain the alternative names of the client certificate (`%` is
904a number starting from zero).
905
906The values will be prepended by `DNSNAME:`, `RFC822NAME:` or `URI:`
907depending on the type.
908
909If it is not supported the value `UNSUPPORTED` will be set.
910
911`SSL_SERVER_M_SERIAL`
912---------------------
913
914The serial number of the server's certificate.
915
916`SSL_SERVER_M_VERSION`
917----------------------
918
919The version of the server's certificate.
920
921`SSL_SERVER_A_SIG`
922------------------
923
924The algorithm used for the signature in server's certificate.
925
926`SSL_SERVER_A_KEY`
927------------------
928
929The public key algorithm in server's certificate.
930
931`SSL_SERVER_CERT`
932------------------
933
934The PEM-encoded (X.509) or ASCII-armored (OpenPGP) server certificate
935(see the `GnuTLSExportCertificates` directive).
936
937`SSL_SERVER_CERT_TYPE`
938----------------------
939
940The certificate type can be `X.509` or `OPENPGP`.
941
942`SSL_CLIENT_CERT`
943------------------
944
945The PEM-encoded (X.509) or ASCII-armored (OpenPGP) client certificate
946(see the `GnuTLSExportCertificates` directive).
947
948`SSL_CLIENT_CERT_TYPE`
949----------------------
950
951The certificate type can be `X.509` or `OPENPGP`.
Note: See TracBrowser for help on using the repository browser.