source: mod_gnutls/doc/mod_gnutls_manual.mdwn @ 5a5032f

debian/masterdebian/stretch-backportsupstream
Last change on this file since 5a5032f was 5a5032f, checked in by Thomas Klute <thomas2.klute@…>, 2 years ago

Documentation for OCSP stapling options

  • Property mode set to 100644
File size: 26.9 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
55`GnuTLSEnable`
56--------------
57
58Enable GnuTLS for this virtual host
59
60    GnuTLSEnable [on|off]
61
62Default: *off*\
63Context: virtual host
64
65This directive enables SSL/TLS Encryption for a Virtual Host.
66
67`GnuTLSCache`
68-------------
69
70Configure SSL Session Cache
71
72    GnuTLSCache [dbm|gdbm|memcache|none] [PATH|SERVERLIST|-]
73
74Default: `GnuTLSCache none`\
75Context: server config
76
77This directive configures the SSL Session Cache for `mod_gnutls`.
78This could be shared between machines of different architectures. If a
79DBM cache is used, access is serialized using the `gnutls-cache`
80mutex.
81
82`dbm` (Requires Berkeley DBM)
83:   Uses the default Berkeley DB backend of APR DBM to cache SSL
84    Sessions results.  The argument is a relative or absolute path to
85    be used as the DBM Cache file. This is compatible with most
86    operating systems, but needs the Apache Runtime to be compiled
87    with Berkeley DBM support.
88
89`gdbm`
90:   Uses the GDBM backend of APR DBM to cache SSL Sessions results.
91
92    The argument is a relative or absolute path to be used as the DBM Cache
93    file.  This is the recommended option.
94
95`memcache`
96:   Uses a memcached server to cache the SSL Session.
97
98    The argument is a space separated list of servers. If no port
99    number is supplied, the default of 11211 is used.  This can be
100    used to share a session cache between all servers in a cluster.
101
102`none`
103:   Turns off all caching of SSL Sessions.
104
105    This can significantly reduce the performance of `mod_gnutls` since
106    even followup connections by a client must renegotiate parameters
107    instead of reusing old ones.  This is the default, since it
108    requires no configuration.
109
110`GnuTLSCacheTimeout`
111--------------------
112
113Timeout for SSL Session Cache expiration
114
115    GnuTLSCacheTimeout SECONDS
116
117Default: `GnuTLSCacheTimeout 300`\
118Context: server config
119
120Sets the timeout for SSL Session Cache entries expiration.  This
121directive is valid even if Session Tickets are used, and indicates the
122expiration time of the ticket in seconds.
123
124`GnuTLSSessionTickets`
125----------------------
126
127Enable Session Tickets for the server
128
129    GnuTLSSessionTickets [on|off]
130
131Default: `off`\
132Context: server config, virtual host
133
134To avoid storing data for TLS session resumption it is allowed to
135provide client with a ticket, to use on return.  Use for servers with
136limited storage, and don't combine with GnuTLSCache. For a pool of
137servers this option is not recommended since the tickets are unique
138for the issuing server only.
139
140
141`GnuTLSCertificateFile`
142-----------------------
143
144Set to the PEM Encoded Server Certificate
145
146    GnuTLSCertificateFile FILEPATH
147
148Default: *none*\
149Context: server config, virtual host
150
151Takes an absolute or relative path to a PEM-encoded X.509 certificate to
152use as this Server's End Entity (EE) certificate. If you need to supply
153certificates for intermediate Certificate Authorities (iCAs), they
154should be listed in sequence in the file, from EE to the iCA closest to
155the root CA. Optionally, you can also include the root CA's certificate
156as the last certificate in the list.
157
158Since version 0.7 this can be a PKCS #11 URL.
159
160`GnuTLSKeyFile`
161---------------
162
163Set to the PEM Encoded Server Private Key
164
165    GnuTLSKeyFile FILEPATH
166
167Default: *none*\
168Context: server config, virtual host
169
170Takes an absolute or relative path to the Server Private Key. Set
171`GnuTLSPIN` if the key file is encrypted.
172
173Since version 0.7 this can be a PKCS #11 URL.
174
175**Security Warning:**\
176This private key must be protected. It is read while Apache is still
177running as root, and does not need to be readable by the nobody or
178apache user.
179
180`GnuTLSPGPCertificateFile`
181--------------------------
182
183Set to a base64 Encoded Server OpenPGP Certificate
184
185    GnuTLSPGPCertificateFile FILEPATH
186
187Default: *none*\
188Context: server config, virtual host
189
190Takes an absolute or relative path to a base64 Encoded OpenPGP
191Certificate to use as this Server's Certificate.
192
193`GnuTLSPGPKeyFile`
194------------------
195
196Set to the Server OpenPGP Secret Key
197
198    GnuTLSPGPKeyFile FILEPATH
199
200Default: *none*\
201Context: server config, virtual host
202
203Takes an absolute or relative path to the Server Private Key. This key
204cannot currently be password protected.
205
206**Security Warning:**\
207 This private key must be protected. It is read while Apache is still
208running as root, and does not need to be readable by the nobody or
209apache user.
210
211`GnuTLSClientVerify`
212--------------------
213
214Enable Client Certificate Verification\
215
216    GnuTLSClientVerify [ignore|request|require]
217
218Default: `ignore`\
219Context: server config, virtual host, directory, .htaccess
220
221This directive controls the use of SSL Client Certificate
222Authentication. If used in the .htaccess context, it can force TLS
223re-negotiation.
224
225`ignore`
226:   `mod_gnutls` will ignore the contents of any SSL Client Certificates
227    sent. It will not request that the client sends a certificate.
228
229`request`
230:   The client certificate will be requested, but not required.
231    The Certificate will be validated if sent.  The output of the
232    validation status will be stored in the `SSL_CLIENT_VERIFY`
233    environment variable and can be `SUCCESS`, `FAILED` or `NONE`.
234
235`require`
236:   A Client certificate will be required. Any requests without a valid
237    client certificate will be denied.  The `SSL_CLIENT_VERIFY`
238    environment variable will only be set to `SUCCESS`.
239
240`GnuTLSClientCAFile`
241--------------------
242
243Set to the PEM Encoded Certificate Authority Certificate
244
245    GnuTLSClientCAFile FILEPATH
246
247Default: *none*
248Context: server config, virtual host
249
250Takes an absolute or relative path to a PEM Encoded Certificate to use
251as a Certificate Authority with Client Certificate Authentication.
252This file may contain a list of trusted authorities.
253
254`GnuTLSPGPKeyringFile`
255----------------------
256
257Set to a base64 Encoded key ring
258
259    GnuTLSPGPKeyringFile FILEPATH
260
261Default: *none*\
262Context: server config, virtual host
263
264Takes an absolute or relative path to a base64 Encoded Certificate
265list (key ring) to use as a means of verification of Client
266Certificates.  This file should contain a list of trusted signers.
267
268`GnuTLSDHFile`
269--------------
270
271Set to the PKCS \#3 encoded Diffie Hellman parameters
272
273    GnuTLSDHFile FILEPATH
274
275Default: *none*\
276Context: server config, virtual host
277
278Takes an absolute or relative path to a PKCS \#3 encoded DH
279parameters.Those are used when the DHE key exchange method is enabled.
280You can generate this file using `certtool --generate-dh-params --bits
2812048`.  If not set `mod_gnutls` will use the included parameters.
282
283`GnuTLSSRPPasswdFile`
284---------------------
285
286Set to the SRP password file for SRP ciphersuites
287
288    GnuTLSSRPPasswdFile FILEPATH
289
290Default: *none*\
291Context: server config, virtual host
292
293Takes an absolute or relative path to an SRP password file. This is
294the same format as used in libsrp.  You can generate such file using
295the command `srptool --passwd /etc/tpasswd --passwd-conf
296/etc/tpasswd.conf -u test` to set a password for user test.  This
297password file holds the username, a password verifier and the
298dependency to the SRP parameters.
299
300`GnuTLSSRPPasswdConfFile`
301-------------------------
302
303Set to the SRP password.conf file for SRP ciphersuites
304
305    GnuTLSSRPPasswdConfFile FILEPATH
306
307Default: *none*\
308Context: server config, virtual host
309
310Takes an absolute or relative path to an SRP password.conf file. This
311is the same format as used in `libsrp`.  You can generate such file
312using the command `srptool --create-conf /etc/tpasswd.conf`.  This
313file holds the SRP parameters and is associate with the password file
314(the verifiers depends on these parameters).
315
316`GnuTLSPriorities`
317------------------
318
319Set the allowed ciphers, key exchange algorithms, MACs and compression
320methods
321
322    GnuTLSPriorities NORMAL:+CIPHER_0:+CIPHER_1:...:+CIPHER_N
323
324Default: *none*\
325Context: server config, virtual host
326
327Takes a semi-colon separated list of ciphers, key exchange methods
328Message authentication codes and compression methods to enable.
329The allowed keywords are specified in the `gnutls_priority_init()`
330function of GnuTLS.
331
332Full details can be found at [the GnuTLS documentation](http://gnutls.org/manual/html_node/Priority-Strings.html#Priority-Strings).
333In brief you can specify a set of ciphersuites from the choices:
334
335`NONE`
336:   The empty list.
337
338`EXPORT`
339:   A list with all the supported cipher combinations
340    including the `EXPORT` strength algorithms.
341
342`PERFORMANCE`
343:   A list with all the secure cipher combinations sorted in terms of performance.
344
345`NORMAL`
346:   A list with all the secure cipher combinations sorted
347    with respect to security margin (subjective term).
348
349`SECURE`
350:   A list with all the secure cipher combinations including
351    the 256-bit ciphers sorted with respect to security margin.
352
353Additionally you can add or remove algorithms using the `+` and `!`
354prefixes respectively.
355
356For example, in order to disable the `ARCFOUR` cipher from the `NORMAL` set
357you can use the string `NORMAL:!ARCFOUR-128`
358
359Other options such as the protocol version and the compression method
360can be specified using the `VERS-` and `COMP-` prefixes.
361
362So in order to remove or add a specific TLS version from the `NORMAL`
363set, use `NORMAL:!VERS-SSL3.0`.  And to enable zlib compression use
364`NORMAL:+COMP-DEFLATE`.
365
366
367However it is recommended not to add compression at this level.  With
368the `NONE` set, in order to be usable, you have to specify a complete
369set of combinations of protocol versions, cipher algorithms
370(`AES-128-CBC`), key exchange algorithms (`RSA`), message
371authentication codes (`SHA1`) and compression methods (`COMP-NULL`).
372
373You can find a list of all supported Ciphers, Versions, MACs, etc.  by
374running `gnutls-cli --list`.
375
376The special keyword `%COMPAT` will disable some security features such
377as protection against statistical attacks to ciphertext data in order to
378achieve maximum compatibility (some broken mobile clients need this).
379
380`GnuTLSP11Module`
381------------------
382
383Load this PKCS #11 module.
384
385    GnuTLSP11Module PATH_TO_LIBRARY
386
387Default: *none*\
388Context: server config
389
390Load this PKCS #11 provider module, instead of the system
391defaults. May occur multiple times to load multiple modules.
392
393`GnuTLSPIN`
394------------------
395
396Set the PIN to be used to access encrypted key files or PKCS #11 objects.
397
398    GnuTLSPIN XXXXXX
399
400Default: *none*\
401Context: server config, virtual host
402
403Takes a string to be used as a PIN for the protected objects in
404a security module, or as a key to be used to decrypt PKCS #8, PKCS #12,
405or openssl encrypted keys.
406
407`GnuTLSSRKPIN`
408------------------
409
410Set the SRK PIN to be used to unlaccess the TPM.
411
412    GnuTLSSRKPIN XXXXXX
413
414Default: *none*\
415Context: server config, virtual host
416
417Takes a string to be used as a PIN for the protected objects in
418the TPM module.
419
420`GnuTLSExportCertificates`
421--------------------------
422
423Export the PEM encoded certificates to CGIs
424
425    GnuTLSExportCertificates [off|on|SIZE]
426
427Default: `off`\
428Context: server config, virtual host
429
430This directive configures exporting the full certificates of the
431server and the client to CGI scripts via the `SSL_SERVER_CERT` and
432`SSL_CLIENT_CERT` environment variables. The exported certificates
433will be PEM-encoded (if X.509) or ASCII-armored (if OpenPGP) up to the
434size given.  The type of the certificate will be exported in
435`SSL_SERVER_CERT_TYPE` and `SSL_CLIENT_CERT_TYPE`.
436
437SIZE should be an integer number of bytes, or may be written with a
438trailing `K` to indicate kibibytes.  `off` means the same thing as
439`0`, in which case the certificates will not be exported to the
440environment.  `on` is an alias for `16K`.  If a non-zero size is
441specified for this directive, but a certificate is too large to fit in
442the buffer, then the corresponding environment variable will contain
443the fixed string `GNUTLS_CERTIFICATE_SIZE_LIMIT_EXCEEDED`.
444
445With GnuTLSExportCertificates enabled, `mod_gnutls` exports the same
446environment variables to the CGI process as `mod_ssl`.
447
448
449`GnuTLSProxyEngine`
450--------------
451
452Enable TLS proxy connections for this virtual host
453
454    GnuTLSProxyEngine [on|off]
455
456Default: *off*\
457Context: virtual host
458
459This directive enables support for TLS proxy connections for a virtual
460host.
461
462`GnuTLSProxyCAFile`
463--------------------
464
465Set to the PEM encoded Certificate Authority Certificate
466
467    GnuTLSProxyCAFile FILEPATH
468
469Default: *none*\
470Context: server config, virtual host
471
472Takes an absolute or relative path to a PEM encoded certificate to use
473as a Certificate Authority when verifying certificates provided by
474proxy back end servers. This file may contain a list of trusted
475authorities. If not set, verification of TLS back end servers will
476always fail due to lack of a trusted CA.
477
478`GnuTLSProxyCRLFile`
479--------------------
480
481Set to the PEM encoded Certificate Revocation List
482
483    GnuTLSProxyCRLFile FILEPATH
484
485Default: *none*\
486Context: server config, virtual host
487
488Takes an absolute or relative path to a PEM encoded Certificate
489Revocation List to use when verifying certificates provided by proxy
490back end servers. The file may contain a list of CRLs.
491
492`GnuTLSProxyCertificateFile`
493-----------------------
494
495Set to the PEM encoded Client Certificate
496
497    GnuTLSProxyCertificateFile FILEPATH
498
499Default: *none*\
500Context: server config, virtual host
501
502Takes an absolute or relative path to a PEM encoded X.509 certificate
503to use as this Server's End Entity (EE) client certificate for TLS
504client authentication in proxy TLS connections. If you need to supply
505certificates for intermediate Certificate Authorities (iCAs), they
506should be listed in sequence in the file, from EE to the iCA closest
507to the root CA. Optionally, you can also include the root CA's
508certificate as the last certificate in the list.
509
510If not set, TLS client authentication will be disabled for TLS proxy
511connections. If set, `GnuTLSProxyKeyFile` must be set as well to
512provide the matching private key.
513
514`GnuTLSProxyKeyFile`
515---------------
516
517Set to the PEM encoded Private Key
518
519    GnuTLSProxyKeyFile FILEPATH
520
521Default: *none*\
522Context: server config, virtual host
523
524Takes an absolute or relative path to the Private Key matching the
525certificate configured using the `GnuTLSProxyCertificateFile`
526directive. This key cannot currently be password protected.
527
528**Security Warning:**\
529This private key must be protected. It is read while Apache is still
530running as root, and does not need to be readable by the nobody or
531apache user.
532
533`GnuTLSProxyPriorities`
534------------------
535
536Set the allowed ciphers, key exchange algorithms, MACs and compression
537methods for proxy connections
538
539    GnuTLSProxyPriorities NORMAL:+CIPHER_0:+CIPHER_1:...:+CIPHER_N
540
541Default: *none*\
542Context: server config, virtual host
543
544This option is used to set the allowed ciphers, key exchange
545algorithms, MACs and compression methods for proxy connections. It
546takes the same parameters as `GnuTLSPriorities`. Required if
547`GnuTLSProxyEngine` is `On`.
548
549`GnuTLSOCSPStapling`
550------------------
551
552EXPERIMENTAL: Enable OCSP stapling for this (virtual) host.
553
554    GnuTLSOCSPStapling [On|Off]
555
556Default: *off*\
557Context: server config, virtual host
558
559OCSP stapling, formally known as the TLS Certificate Status Request
560extension, allows the server to provide the client with an OCSP
561response for its certificate during the handshake. This way the client
562does not have to send an OCSP request to the CA to check the
563certificate status, which offers privacy and performance advantages.
564
565Using OCSP stapling has a few requirements:
566
567* Caching OCSP responses requires a cache, so `GnuTLSCache` must not
568  be `none`.
569* `GnuTLSCertificateFile` must contain the issuer CA certificate in
570  addition to the server certificate so responses can be verified.
571* The certificate must either contain an OCSP access URI using HTTP,
572  or `GnuTLSOCSPResponseFile` must be set.
573
574OCSP cache updates are serialized using the `gnutls-ocsp` mutex.
575
576`GnuTLSOCSPResponseFile`
577------------------
578
579EXPERIMENTAL: Read the OCSP response for stapling from this file
580instead of sending a request over HTTP
581
582    GnuTLSOCSPResponseFile /path/to/response.der
583
584Default: *empty*\
585Context: server config, virtual host
586
587The response file must be updated externally, for example using a cron
588job. This option is an alternative to the server fetching OCSP
589responses over HTTP. Reasons to use this option include:
590
591* Performing OCSP requests separate from the web server, to prevent slow
592  responses from stalling handshakes.
593* The issuer CA uses an access method other than HTTP.
594* Testing
595
596`GnuTLSOCSPGraceTime`
597------------------
598
599EXPERIMENTAL: Replace cached OCSP responses this many seconds before
600they expire.
601
602    GnuTLSOCSPGraceTime SECONDS
603
604Default: *60*\
605Context: server config, virtual host
606
607A cached OCSP response should be updated a little before it expires to
608account for potential clock skew between server, CA, and client, as
609well as transmission time in corner cases.
610
611* * * * *
612
613Configuration Examples
614======================
615
616Simple Standard SSL Example
617---------------------------
618
619The following is an example of standard SSL Hosting, using one IP
620Addresses for each virtual host
621
622     # Load the module into Apache.
623     LoadModule gnutls_module modules/mod_gnutls.so
624     GnuTLSCache gdbm /var/cache/www-tls-cache
625     GnuTLSCacheTimeout 500
626     # With normal SSL Websites, you need one IP Address per-site.
627     Listen 1.2.3.1:443
628     Listen 1.2.3.2:443
629     Listen 1.2.3.3:443
630     Listen 1.2.3.4:443
631     <VirtualHost 1.2.3.1:443>
632     GnuTLSEnable on
633     GnuTLSPriorities NONE:+AES-128-CBC:+3DES-CBC:+ARCFOUR-128:+RSA:+DHE-RSA:+DHE-DSS:+SHA1:+MD5:+COMP-NULL
634     DocumentRoot /www/site1.example.com/html
635     ServerName site1.example.com:443
636     GnuTLSCertificateFile conf/ssl/site1.crt
637     GnuTLSKeyFile conf/ss/site1.key
638     </VirtualHost>
639     <VirtualHost 1.2.3.2:443>
640     # This virtual host enables SRP authentication
641     GnuTLSEnable on
642     GnuTLSPriorities NORMAL:+SRP
643     DocumentRoot /www/site2.example.com/html
644     ServerName site2.example.com:443
645     GnuTLSSRPPasswdFile conf/ssl/tpasswd.site2
646     GnuTLSSRPPasswdConfFile conf/ssl/tpasswd.site2.conf
647     </VirtualHost>
648     <VirtualHost 1.2.3.3:443>
649     # This server enables SRP, OpenPGP and X.509 authentication.
650     GnuTLSEnable on
651     GnuTLSPriorities NORMAL:+SRP:+SRP-RSA:+SRP-DSS
652     DocumentRoot /www/site3.example.com/html
653     ServerName site3.example.com:443
654     GnuTLSCertificateFile conf/ssl/site3.crt
655     GnuTLSKeyFile conf/ss/site3.key
656     GnuTLSClientVerify ignore
657     GnuTLSPGPCertificateFile conf/ss/site3.pub.asc
658     GnuTLSPGPKeyFile conf/ss/site3.sec.asc
659     GnuTLSSRPPasswdFile conf/ssl/tpasswd.site3
660     GnuTLSSRPPasswdConfFile conf/ssl/tpasswd.site3.conf
661     </VirtualHost>
662     <VirtualHost 1.2.3.4:443>
663     GnuTLSEnable on
664     # %COMPAT disables some security features to enable maximum compatibility with clients.
665     GnuTLSPriorities NONE:+AES-128-CBC:+ARCFOUR-128:+RSA:+SHA1:+MD5:+COMP-NULL:%COMPAT
666     DocumentRoot /www/site4.example.com/html
667     ServerName site4.example.com:443
668     GnuTLSCertificateFile conf/ssl/site4.crt
669     GnuTLSKeyFile conf/ss/site4.key
670     </VirtualHost>
671
672Server Name Indication Example
673------------------------------
674
675`mod_gnutls` can also use "Server Name Indication", as specified in
676RFC 3546.  This allows hosting many SSL Websites, with a Single IP
677Address.  Currently all the recent browsers support this
678standard. Here is an example, using SNI: ` `
679
680
681     # Load the module into Apache.
682     LoadModule gnutls_module modules/mod_gnutls.so
683     # With normal SSL Websites, you need one IP Address per-site.
684     Listen 1.2.3.1:443
685     # This could also be 'Listen *:443',
686     # just like '*:80' is common for non-https
687     # No caching. Enable session tickets. Timeout is still used for
688     # ticket expiration.
689     GnuTLSCacheTimeout 600
690     # This tells apache, that for this IP/Port combination, we want to use
691     # Name Based Virtual Hosting. In the case of Server Name Indication,
692     # it lets mod_gnutls pick the correct Server Certificate.
693     NameVirtualHost 1.2.3.1:443
694     <VirtualHost 1.2.3.1:443>
695     GnuTLSEnable on
696     GnuTLSSessionTickets on
697     GnuTLSPriorities NORMAL
698     DocumentRoot /www/site1.example.com/html
699     ServerName site1.example.com:443
700     GnuTLSCertificateFile conf/ssl/site1.crt
701     GnuTLSKeyFile conf/ss/site1.key
702     </VirtualHost>
703     <VirtualHost 1.2.3.1:443>
704     GnuTLSEnable on
705     GnuTLSPriorities NORMAL
706     DocumentRoot /www/site2.example.com/html
707     ServerName site2.example.com:443
708     GnuTLSCertificateFile conf/ssl/site2.crt
709     GnuTLSKeyFile conf/ss/site2.key
710     </VirtualHost>
711     <VirtualHost 1.2.3.1:443>
712     GnuTLSEnable on
713     GnuTLSPriorities NORMAL
714     DocumentRoot /www/site3.example.com/html
715     ServerName site3.example.com:443
716     GnuTLSCertificateFile conf/ssl/site3.crt
717     GnuTLSKeyFile conf/ss/site3.key
718     </VirtualHost>
719     <VirtualHost 1.2.3.1:443>
720     GnuTLSEnable on
721     GnuTLSPriorities NORMAL
722     DocumentRoot /www/site4.example.com/html
723     ServerName site4.example.com:443
724     GnuTLSCertificateFile conf/ssl/site4.crt
725     GnuTLSKeyFile conf/ss/site4.key
726     </VirtualHost>
727
728
729* * * * *
730
731Performance Issues
732==================
733
734`mod_gnutls` by default uses conservative settings for the server.
735You can fine tune the configuration to reduce the load on a busy
736server.  The following examples do exactly this:
737
738
739     # Load the module into Apache.
740     LoadModule gnutls_module modules/mod_gnutls.so
741     # Using 4 memcache servers to distribute the SSL Session Cache.
742     GnuTLSCache memcache "mc1.example.com mc2.example.com mc3.example.com mc4.example.com"
743     GnuTLSCacheTimeout 600
744     Listen 1.2.3.1:443
745     NameVirtualHost 1.2.3.1:443
746     <VirtualHost 1.2.3.1:443>
747     GnuTLSEnable on
748     # Here we disable the Perfect forward secrecy ciphersuites (DHE)
749     # and disallow AES-256 since AES-128 is just fine.
750     GnuTLSPriorities NORMAL:!DHE-RSA:!DHE-DSS:!AES-256-CBC:%COMPAT
751     DocumentRoot /www/site1.example.com/html
752     ServerName site1.example.com:443
753     GnuTLSCertificateFile conf/ssl/site1.crt
754     GnuTLSKeyFile conf/ss/site1.key
755     </VirtualHost>
756     <VirtualHost 1.2.3.1:443>
757     GnuTLSEnable on
758     # Here we instead of disabling the DHE ciphersuites we use
759     # Diffie Hellman parameters of smaller size than the default (2048 bits).
760     # Using small numbers from 768 to 1024 bits should be ok once they are
761     # regenerated every few hours.
762     # Use "certtool --generate-dh-params --bits 1024" to get those
763     GnuTLSDHFile /etc/apache2/dh.params
764     GnuTLSPriorities NORMAL:!AES-256-CBC:%COMPAT
765     DocumentRoot /www/site2.example.com/html
766     ServerName site2.example.com:443
767     GnuTLSCertificateFile conf/ssl/site2.crt
768     GnuTLSKeyFile conf/ss/site2.key
769     </VirtualHost>
770
771* * * * *
772
773Environment Variables
774=====================
775
776`mod_gnutls` exports the following environment variables to scripts.
777These are compatible with `mod_ssl`.
778
779`HTTPS`
780-------
781
782Can be `on` or `off`
783
784`SSL_VERSION_LIBRARY`
785---------------------
786
787The version of the GnuTLS library
788
789`SSL_VERSION_INTERFACE`
790-----------------------
791
792The version of this module
793
794`SSL_PROTOCOL`
795--------------
796
797The SSL or TLS protocol name (such as `TLS 1.0` etc.)
798
799`SSL_CIPHER`
800------------
801
802The SSL or TLS cipher suite name
803
804`SSL_COMPRESS_METHOD`
805---------------------
806
807The negotiated compression method (`NULL` or `DEFLATE`)
808
809`SSL_SRP_USER`
810--------------
811
812The SRP username used for authentication (only set when
813`GnuTLSSRPPasswdFile` and `GnuTLSSRPPasswdConfFile` are configured).
814
815`SSL_CIPHER_USEKEYSIZE` & `SSL_CIPHER_ALGKEYSIZE`
816-------------------------------------------------
817
818The number if bits used in the used cipher algorithm.
819
820This does not fully reflect the security level since the size of
821RSA or DHE key exchange parameters affect the security level too.
822
823`SSL_DH_PRIME_BITS`
824-------------------
825
826The number if bits in the modulus for the DH group, if DHE or static
827DH is used.
828
829This will not be set if DH is not used.
830
831`SSL_CIPHER_EXPORT`
832-------------------
833
834`True` or `False`. Whether the cipher suite negotiated is an export one.
835
836`SSL_SESSION_ID`
837----------------
838
839The session ID negotiated in this session. Can be the same during client
840reloads.
841
842`SSL_CLIENT_V_REMAIN`
843---------------------
844
845The number of days until the client's certificate is expired.
846
847`SSL_CLIENT_V_START`
848--------------------
849
850The activation time of client's certificate.
851
852`SSL_CLIENT_V_END`
853------------------
854
855The expiration time of client's certificate.
856
857`SSL_CLIENT_S_DN`
858-----------------
859
860The distinguished name of client's certificate in RFC2253 format.
861
862`SSL_CLIENT_I_DN`
863-----------------
864
865The SSL or TLS cipher suite name
866
867`SSL_CLIENT_S_AN%`
868------------------
869
870These will contain the alternative names of the client certificate (`%` is
871a number starting from zero).
872
873The values will be prepended by `DNSNAME:`, `RFC822NAME:` or `URI:`
874depending on the type.
875
876If it is not supported the value `UNSUPPORTED` will be set.
877
878`SSL_SERVER_M_SERIAL`
879---------------------
880
881The serial number of the server's certificate.
882
883`SSL_SERVER_M_VERSION`
884----------------------
885
886The version of the server's certificate.
887
888`SSL_SERVER_A_SIG`
889------------------
890
891The algorithm used for the signature in server's certificate.
892
893`SSL_SERVER_A_KEY`
894------------------
895
896The public key algorithm in server's certificate.
897
898`SSL_SERVER_CERT`
899------------------
900
901The PEM-encoded (X.509) or ASCII-armored (OpenPGP) server certificate
902(see the `GnuTLSExportCertificates` directive).
903
904`SSL_SERVER_CERT_TYPE`
905----------------------
906
907The certificate type can be `X.509` or `OPENPGP`.
908
909`SSL_CLIENT_CERT`
910------------------
911
912The PEM-encoded (X.509) or ASCII-armored (OpenPGP) client certificate
913(see the `GnuTLSExportCertificates` directive).
914
915`SSL_CLIENT_CERT_TYPE`
916----------------------
917
918The certificate type can be `X.509` or `OPENPGP`.
Note: See TracBrowser for help on using the repository browser.