source: mod_gnutls/doc/mod_gnutls_manual.mdwn @ 60868d2

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

Default to NORMAL for the GnuTLS priority settings

This simplifies configuration and should be resonable for most users.

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