source: mod_gnutls/doc/mod_gnutls_manual.mdwn @ e9ef72c

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

Disable GnuTLSSessionTickets by default as described in handbook

The handbook clearly states that the default value for
GnuTLSSessionTickets is "off", but the actual setting in post config
was the opposite (which matched mod_ssl behavior). The code has been
changed to match documentation.

Additionally the handbook has been expanded regarding session ticket
use and security. The comment about the cache timeout being used for
session ticket expiration has been removed for being plainly wrong.

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