source: mod_gnutls/doc/mod_gnutls_manual.mdwn @ 0202d6b

debian/masterdebian/stretch-backportsupstream mod_gnutls/0.8.2
Last change on this file since 0202d6b was c22af3a, checked in by Thomas Klute <thomas2.klute@…>, 3 years ago

Handbook: List Berkeley DB and GDBM as equal options for DBM caches

Some major Linux distributions do not provide APR libraries with GDBM
support, so it doesn't really make sense to list it as
"recommended". Debian only VERY recently enabled it in unstable [1].

[1] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=843206

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