source: mod_gnutls/doc/mod_gnutls_manual.mdwn @ 04addef

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

Mutex for DBM cache access

I noticed that with a DBM cache enabled and session tickets disabled
even a handful of parallel connections trashed the cache database, and
consequently the error log. According to comments and documentation on
mod_socache_dbm the APR DBM module is not thread or multi-process
safe, so a global mutex is necessary. With the mutex the cache
corruption disappears in my benchmarks.

  • Property mode set to 100644
File size: 25.0 KB
RevLine 
[e7527b9]1% `mod_gnutls` Manual
[4ee45a1]2
3* * * * *
4
[bce7907]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/).
[4ee45a1]9
10* * * * *
11
12Compilation & Installation
[2b16350]13==========================
[4ee45a1]14
[e7527b9]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
[dc058b8]27`--with-apu-config=PATH`
28:   Path to APR Utility Library config tool (`apu-1-config`)
[e7527b9]29
30`--help`
31:   Provides a list of all available configure options.
[4ee45a1]32
[dff57b4]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`
[dc058b8]37environment variables when running `./configure` to make the test
38suite work correctly.
39
[4ee45a1]40* * * * *
41
42Integration
[2b16350]43===========
[4ee45a1]44
[2b16350]45To activate `mod_gnutls` just add the following line to your httpd.conf
[4ee45a1]46and restart Apache:
47
[2b16350]48    LoadModule gnutls_module modules/mod_gnutls.so
[4ee45a1]49
50* * * * *
51
[2b16350]52Configuration Directives
53========================
[4ee45a1]54
[2b16350]55`GnuTLSEnable`
56--------------
[4ee45a1]57
[2b16350]58Enable GnuTLS for this virtual host
[4ee45a1]59
[2b16350]60    GnuTLSEnable [on|off]
[4ee45a1]61
[2b16350]62Default: *off*\
63Context: virtual host
[4ee45a1]64
[2b16350]65This directive enables SSL/TLS Encryption for a Virtual Host.
[4ee45a1]66
[2b16350]67`GnuTLSCache`
68-------------
[4ee45a1]69
[2b16350]70Configure SSL Session Cache
[4ee45a1]71
[2b16350]72    GnuTLSCache [dbm|gdbm|memcache|none] [PATH|SERVERLIST|-]
[4ee45a1]73
[2b16350]74Default: `GnuTLSCache none`\
75Context: server config
[4ee45a1]76
[2b16350]77This directive configures the SSL Session Cache for `mod_gnutls`.
[c005645]78This could be shared between machines of different architectures. If a
79DBM cache is used, access is serialized using the `gnutls-cache`
80mutex.
[4ee45a1]81
[2b16350]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.
[4ee45a1]88
[2b16350]89`gdbm`
90:   Uses the GDBM backend of APR DBM to cache SSL Sessions results.
[4ee45a1]91
[2b16350]92    The argument is a relative or absolute path to be used as the DBM Cache
93    file.  This is the recommended option.
[4ee45a1]94
[2b16350]95`memcache`
96:   Uses a memcached server to cache the SSL Session.
[4ee45a1]97
[2b16350]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.
[4ee45a1]101
[2b16350]102`none`
103:   Turns off all caching of SSL Sessions.
[4ee45a1]104
[2b16350]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.
[4ee45a1]109
[2b16350]110`GnuTLSCacheTimeout`
111--------------------
[4ee45a1]112
[2b16350]113Timeout for SSL Session Cache expiration
[4ee45a1]114
[2b16350]115    GnuTLSCacheTimeout SECONDS
[4ee45a1]116
[2b16350]117Default: `GnuTLSCacheTimeout 300`\
118Context: server config
[4ee45a1]119
[2b16350]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.
[4ee45a1]123
[2b16350]124`GnuTLSSessionTickets`
125----------------------
[4ee45a1]126
[2b16350]127Enable Session Tickets for the server
[4ee45a1]128
[2b16350]129    GnuTLSSessionTickets [on|off]
[4ee45a1]130
[2b16350]131Default: `off`\
132Context: server config, virtual host
[4ee45a1]133
134To avoid storing data for TLS session resumption it is allowed to
[2b16350]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.
[4ee45a1]139
140
[2b16350]141`GnuTLSCertificateFile`
142-----------------------
[4ee45a1]143
[2b16350]144Set to the PEM Encoded Server Certificate
[4ee45a1]145
[2b16350]146    GnuTLSCertificateFile FILEPATH
[4ee45a1]147
[2b16350]148Default: *none*\
149Context: server config, virtual host
[4ee45a1]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
[97c930f]158Since version 0.7 this can be a PKCS #11 URL.
159
[2b16350]160`GnuTLSKeyFile`
161---------------
[4ee45a1]162
[eebc960]163Set to the PEM Encoded Server Private Key
[4ee45a1]164
[eebc960]165    GnuTLSKeyFile FILEPATH
[4ee45a1]166
[2b16350]167Default: *none*\
168Context: server config, virtual host
[4ee45a1]169
[97c930f]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.
[4ee45a1]174
175**Security Warning:**\
[97c930f]176This private key must be protected. It is read while Apache is still
[4ee45a1]177running as root, and does not need to be readable by the nobody or
178apache user.
179
[2b16350]180`GnuTLSPGPCertificateFile`
181--------------------------
[4ee45a1]182
[2b16350]183Set to a base64 Encoded Server OpenPGP Certificate
[4ee45a1]184
[2b16350]185    GnuTLSPGPCertificateFile FILEPATH
[4ee45a1]186
[2b16350]187Default: *none*\
188Context: server config, virtual host
[4ee45a1]189
190Takes an absolute or relative path to a base64 Encoded OpenPGP
191Certificate to use as this Server's Certificate.
192
[2b16350]193`GnuTLSPGPKeyFile`
194------------------
[4ee45a1]195
[2b16350]196Set to the Server OpenPGP Secret Key
[4ee45a1]197
[2b16350]198    GnuTLSPGPKeyFile FILEPATH
[4ee45a1]199
[2b16350]200Default: *none*\
201Context: server config, virtual host
[4ee45a1]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
[2b16350]211`GnuTLSClientVerify`
212--------------------
[4ee45a1]213
214Enable Client Certificate Verification\
215
[2b16350]216    GnuTLSClientVerify [ignore|request|require]
[4ee45a1]217
[2b16350]218Default: `ignore`\
219Context: server config, virtual host, directory, .htaccess
[4ee45a1]220
221This directive controls the use of SSL Client Certificate
[2b16350]222Authentication. If used in the .htaccess context, it can force TLS
223re-negotiation.
[4ee45a1]224
[2b16350]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.
[4ee45a1]228
[2b16350]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`.
[4ee45a1]234
[2b16350]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`.
[4ee45a1]239
[2b16350]240`GnuTLSClientCAFile`
241--------------------
[4ee45a1]242
[2b16350]243Set to the PEM Encoded Certificate Authority Certificate
[4ee45a1]244
[2b16350]245    GnuTLSClientCAFile FILEPATH
[4ee45a1]246
[2b16350]247Default: *none*
248Context: server config, virtual host
[4ee45a1]249
250Takes an absolute or relative path to a PEM Encoded Certificate to use
[2b16350]251as a Certificate Authority with Client Certificate Authentication.
252This file may contain a list of trusted authorities.
[4ee45a1]253
[2b16350]254`GnuTLSPGPKeyringFile`
255----------------------
[4ee45a1]256
[2b16350]257Set to a base64 Encoded key ring
[4ee45a1]258
[2b16350]259    GnuTLSPGPKeyringFile FILEPATH
[4ee45a1]260
[2b16350]261Default: *none*\
262Context: server config, virtual host
[4ee45a1]263
[2b16350]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.
[4ee45a1]267
[2b16350]268`GnuTLSDHFile`
269--------------
[4ee45a1]270
[2b16350]271Set to the PKCS \#3 encoded Diffie Hellman parameters
[4ee45a1]272
[2b16350]273    GnuTLSDHFile FILEPATH
[4ee45a1]274
[2b16350]275Default: *none*\
276Context: server config, virtual host
[4ee45a1]277
[2b16350]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.
[4ee45a1]282
[2b16350]283`GnuTLSSRPPasswdFile`
284---------------------
[4ee45a1]285
[2b16350]286Set to the SRP password file for SRP ciphersuites
[4ee45a1]287
[2b16350]288    GnuTLSSRPPasswdFile FILEPATH
[4ee45a1]289
[2b16350]290Default: *none*\
291Context: server config, virtual host
[4ee45a1]292
[2b16350]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.
[4ee45a1]299
[2b16350]300`GnuTLSSRPPasswdConfFile`
301-------------------------
[4ee45a1]302
[2b16350]303Set to the SRP password.conf file for SRP ciphersuites
[4ee45a1]304
[2b16350]305    GnuTLSSRPPasswdConfFile FILEPATH
[4ee45a1]306
[2b16350]307Default: *none*\
308Context: server config, virtual host
[4ee45a1]309
[2b16350]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).
[4ee45a1]315
[2b16350]316`GnuTLSPriorities`
317------------------
[4ee45a1]318
[2b16350]319Set the allowed ciphers, key exchange algorithms, MACs and compression
320methods
[4ee45a1]321
[5409165]322    GnuTLSPriorities NORMAL:+CIPHER_0:+CIPHER_1:...:+CIPHER_N
[4ee45a1]323
[2b16350]324Default: *none*\
325Context: server config, virtual host
[4ee45a1]326
[2b16350]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.
[4ee45a1]331
[5409165]332Full details can be found at [the GnuTLS documentation](http://gnutls.org/manual/html_node/Priority-Strings.html#Priority-Strings).
[2b16350]333In brief you can specify a set of ciphersuites from the choices:
[4ee45a1]334
[2b16350]335`NONE`
336:   The empty list.
[4ee45a1]337
[2b16350]338`EXPORT`
339:   A list with all the supported cipher combinations
340    including the `EXPORT` strength algorithms.
[4ee45a1]341
[2b16350]342`PERFORMANCE`
343:   A list with all the secure cipher combinations sorted in terms of performance.
[4ee45a1]344
[2b16350]345`NORMAL`
346:   A list with all the secure cipher combinations sorted
347    with respect to security margin (subjective term).
[4ee45a1]348
[2b16350]349`SECURE`
350:   A list with all the secure cipher combinations including
351    the 256-bit ciphers sorted with respect to security margin.
[4ee45a1]352
[2b16350]353Additionally you can add or remove algorithms using the `+` and `!`
354prefixes respectively.
[4ee45a1]355
[2b16350]356For example, in order to disable the `ARCFOUR` cipher from the `NORMAL` set
357you can use the string `NORMAL:!ARCFOUR-128`
[4ee45a1]358
[2b16350]359Other options such as the protocol version and the compression method
360can be specified using the `VERS-` and `COMP-` prefixes.
[4ee45a1]361
[2b16350]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`.
[4ee45a1]365
366
[2b16350]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`).
[4ee45a1]372
[2b16350]373You can find a list of all supported Ciphers, Versions, MACs, etc.  by
374running `gnutls-cli --list`.
[4ee45a1]375
[2b16350]376The special keyword `%COMPAT` will disable some security features such
[4ee45a1]377as protection against statistical attacks to ciphertext data in order to
378achieve maximum compatibility (some broken mobile clients need this).
379
[8873a06]380`GnuTLSP11Module`
381------------------
382
[7764015]383Load this PKCS #11 module.
[8873a06]384
385    GnuTLSP11Module PATH_TO_LIBRARY
386
387Default: *none*\
388Context: server config
389
[9ca1f21]390Load this PKCS #11 provider module, instead of the system
391defaults. May occur multiple times to load multiple modules.
[8873a06]392
[031acac]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
[2b16350]420`GnuTLSExportCertificates`
421--------------------------
[4ee45a1]422
[2b16350]423Export the PEM encoded certificates to CGIs
[4ee45a1]424
[999cdec]425    GnuTLSExportCertificates [off|on|SIZE]
[4ee45a1]426
[2b16350]427Default: `off`\
428Context: server config, virtual host
[4ee45a1]429
[999cdec]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
[2b16350]445With GnuTLSExportCertificates enabled, `mod_gnutls` exports the same
446environment variables to the CGI process as `mod_ssl`.
[4ee45a1]447
[d8ae2a0]448
[a2e3c33]449`GnuTLSProxyEngine`
[d8ae2a0]450--------------
451
452Enable TLS proxy connections for this virtual host
453
[a2e3c33]454    GnuTLSProxyEngine [on|off]
[d8ae2a0]455
456Default: *off*\
457Context: virtual host
458
459This directive enables support for TLS proxy connections for a virtual
460host.
461
462`GnuTLSProxyCAFile`
463--------------------
464
[809c422]465Set to the PEM encoded Certificate Authority Certificate
[d8ae2a0]466
467    GnuTLSProxyCAFile FILEPATH
468
469Default: *none*\
470Context: server config, virtual host
471
[809c422]472Takes an absolute or relative path to a PEM encoded certificate to use
[d8ae2a0]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
[809c422]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
[d8ae2a0]492`GnuTLSProxyCertificateFile`
493-----------------------
494
[809c422]495Set to the PEM encoded Client Certificate
[d8ae2a0]496
497    GnuTLSProxyCertificateFile FILEPATH
498
499Default: *none*\
500Context: server config, virtual host
501
[809c422]502Takes an absolute or relative path to a PEM encoded X.509 certificate
[d8ae2a0]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
[809c422]517Set to the PEM encoded Private Key
[d8ae2a0]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
[f030883]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
[a2e3c33]547`GnuTLSProxyEngine` is `On`.
[f030883]548
[4ee45a1]549* * * * *
550
551Configuration Examples
[2b16350]552======================
[4ee45a1]553
[2b16350]554Simple Standard SSL Example
555---------------------------
[4ee45a1]556
557The following is an example of standard SSL Hosting, using one IP
558Addresses for each virtual host
559
[2b16350]560     # Load the module into Apache.
561     LoadModule gnutls_module modules/mod_gnutls.so
562     GnuTLSCache gdbm /var/cache/www-tls-cache
563     GnuTLSCacheTimeout 500
564     # With normal SSL Websites, you need one IP Address per-site.
565     Listen 1.2.3.1:443
566     Listen 1.2.3.2:443
567     Listen 1.2.3.3:443
568     Listen 1.2.3.4:443
569     <VirtualHost 1.2.3.1:443>
570     GnuTLSEnable on
571     GnuTLSPriorities NONE:+AES-128-CBC:+3DES-CBC:+ARCFOUR-128:+RSA:+DHE-RSA:+DHE-DSS:+SHA1:+MD5:+COMP-NULL
572     DocumentRoot /www/site1.example.com/html
573     ServerName site1.example.com:443
574     GnuTLSCertificateFile conf/ssl/site1.crt
575     GnuTLSKeyFile conf/ss/site1.key
576     </VirtualHost>
577     <VirtualHost 1.2.3.2:443>
578     # This virtual host enables SRP authentication
579     GnuTLSEnable on
580     GnuTLSPriorities NORMAL:+SRP
581     DocumentRoot /www/site2.example.com/html
582     ServerName site2.example.com:443
583     GnuTLSSRPPasswdFile conf/ssl/tpasswd.site2
584     GnuTLSSRPPasswdConfFile conf/ssl/tpasswd.site2.conf
585     </VirtualHost>
586     <VirtualHost 1.2.3.3:443>
587     # This server enables SRP, OpenPGP and X.509 authentication.
588     GnuTLSEnable on
589     GnuTLSPriorities NORMAL:+SRP:+SRP-RSA:+SRP-DSS
590     DocumentRoot /www/site3.example.com/html
591     ServerName site3.example.com:443
592     GnuTLSCertificateFile conf/ssl/site3.crt
593     GnuTLSKeyFile conf/ss/site3.key
594     GnuTLSClientVerify ignore
595     GnuTLSPGPCertificateFile conf/ss/site3.pub.asc
596     GnuTLSPGPKeyFile conf/ss/site3.sec.asc
597     GnuTLSSRPPasswdFile conf/ssl/tpasswd.site3
598     GnuTLSSRPPasswdConfFile conf/ssl/tpasswd.site3.conf
599     </VirtualHost>
600     <VirtualHost 1.2.3.4:443>
601     GnuTLSEnable on
602     # %COMPAT disables some security features to enable maximum compatibility with clients.
603     GnuTLSPriorities NONE:+AES-128-CBC:+ARCFOUR-128:+RSA:+SHA1:+MD5:+COMP-NULL:%COMPAT
604     DocumentRoot /www/site4.example.com/html
605     ServerName site4.example.com:443
606     GnuTLSCertificateFile conf/ssl/site4.crt
607     GnuTLSKeyFile conf/ss/site4.key
608     </VirtualHost>
609
610Server Name Indication Example
611------------------------------
612
613`mod_gnutls` can also use "Server Name Indication", as specified in
614RFC 3546.  This allows hosting many SSL Websites, with a Single IP
615Address.  Currently all the recent browsers support this
616standard. Here is an example, using SNI: ` `
617
618
619     # Load the module into Apache.
620     LoadModule gnutls_module modules/mod_gnutls.so
621     # With normal SSL Websites, you need one IP Address per-site.
622     Listen 1.2.3.1:443
623     # This could also be 'Listen *:443',
624     # just like '*:80' is common for non-https
625     # No caching. Enable session tickets. Timeout is still used for
626     # ticket expiration.
627     GnuTLSCacheTimeout 600
628     # This tells apache, that for this IP/Port combination, we want to use
629     # Name Based Virtual Hosting. In the case of Server Name Indication,
630     # it lets mod_gnutls pick the correct Server Certificate.
631     NameVirtualHost 1.2.3.1:443
632     <VirtualHost 1.2.3.1:443>
633     GnuTLSEnable on
634     GnuTLSSessionTickets on
635     GnuTLSPriorities NORMAL
636     DocumentRoot /www/site1.example.com/html
637     ServerName site1.example.com:443
638     GnuTLSCertificateFile conf/ssl/site1.crt
639     GnuTLSKeyFile conf/ss/site1.key
640     </VirtualHost>
641     <VirtualHost 1.2.3.1:443>
642     GnuTLSEnable on
643     GnuTLSPriorities NORMAL
644     DocumentRoot /www/site2.example.com/html
645     ServerName site2.example.com:443
646     GnuTLSCertificateFile conf/ssl/site2.crt
647     GnuTLSKeyFile conf/ss/site2.key
648     </VirtualHost>
649     <VirtualHost 1.2.3.1:443>
650     GnuTLSEnable on
651     GnuTLSPriorities NORMAL
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     </VirtualHost>
657     <VirtualHost 1.2.3.1:443>
658     GnuTLSEnable on
659     GnuTLSPriorities NORMAL
660     DocumentRoot /www/site4.example.com/html
661     ServerName site4.example.com:443
662     GnuTLSCertificateFile conf/ssl/site4.crt
663     GnuTLSKeyFile conf/ss/site4.key
664     </VirtualHost>
[4ee45a1]665
666
[2b16350]667* * * * *
[4ee45a1]668
[2b16350]669Performance Issues
670==================
671
672`mod_gnutls` by default uses conservative settings for the server.
673You can fine tune the configuration to reduce the load on a busy
674server.  The following examples do exactly this:
675
676
677     # Load the module into Apache.
678     LoadModule gnutls_module modules/mod_gnutls.so
679     # Using 4 memcache servers to distribute the SSL Session Cache.
680     GnuTLSCache memcache "mc1.example.com mc2.example.com mc3.example.com mc4.example.com"
681     GnuTLSCacheTimeout 600
682     Listen 1.2.3.1:443
683     NameVirtualHost 1.2.3.1:443
684     <VirtualHost 1.2.3.1:443>
685     GnuTLSEnable on
686     # Here we disable the Perfect forward secrecy ciphersuites (DHE)
687     # and disallow AES-256 since AES-128 is just fine.
688     GnuTLSPriorities NORMAL:!DHE-RSA:!DHE-DSS:!AES-256-CBC:%COMPAT
689     DocumentRoot /www/site1.example.com/html
690     ServerName site1.example.com:443
691     GnuTLSCertificateFile conf/ssl/site1.crt
692     GnuTLSKeyFile conf/ss/site1.key
693     </VirtualHost>
694     <VirtualHost 1.2.3.1:443>
695     GnuTLSEnable on
696     # Here we instead of disabling the DHE ciphersuites we use
697     # Diffie Hellman parameters of smaller size than the default (2048 bits).
698     # Using small numbers from 768 to 1024 bits should be ok once they are
699     # regenerated every few hours.
700     # Use "certtool --generate-dh-params --bits 1024" to get those
701     GnuTLSDHFile /etc/apache2/dh.params
702     GnuTLSPriorities NORMAL:!AES-256-CBC:%COMPAT
703     DocumentRoot /www/site2.example.com/html
704     ServerName site2.example.com:443
705     GnuTLSCertificateFile conf/ssl/site2.crt
706     GnuTLSKeyFile conf/ss/site2.key
707     </VirtualHost>
[4ee45a1]708
709* * * * *
710
[2b16350]711Environment Variables
712=====================
[4ee45a1]713
[2b16350]714`mod_gnutls` exports the following environment variables to scripts.
715These are compatible with `mod_ssl`.
[4ee45a1]716
[2b16350]717`HTTPS`
718-------
[4ee45a1]719
[2b16350]720Can be `on` or `off`
[4ee45a1]721
[2b16350]722`SSL_VERSION_LIBRARY`
723---------------------
[4ee45a1]724
[2b16350]725The version of the GnuTLS library
[4ee45a1]726
[2b16350]727`SSL_VERSION_INTERFACE`
728-----------------------
[4ee45a1]729
730The version of this module
731
[2b16350]732`SSL_PROTOCOL`
733--------------
[4ee45a1]734
[2b16350]735The SSL or TLS protocol name (such as `TLS 1.0` etc.)
[4ee45a1]736
[2b16350]737`SSL_CIPHER`
738------------
[4ee45a1]739
740The SSL or TLS cipher suite name
741
[2b16350]742`SSL_COMPRESS_METHOD`
743---------------------
[4ee45a1]744
[2b16350]745The negotiated compression method (`NULL` or `DEFLATE`)
[4ee45a1]746
[2b16350]747`SSL_SRP_USER`
748--------------
[4ee45a1]749
750The SRP username used for authentication (only set when
[2b16350]751`GnuTLSSRPPasswdFile` and `GnuTLSSRPPasswdConfFile` are configured).
[4ee45a1]752
[2b16350]753`SSL_CIPHER_USEKEYSIZE` & `SSL_CIPHER_ALGKEYSIZE`
754-------------------------------------------------
[4ee45a1]755
756The number if bits used in the used cipher algorithm.
757
758This does not fully reflect the security level since the size of
759RSA or DHE key exchange parameters affect the security level too.
760
[5674676]761`SSL_DH_PRIME_BITS`
762-------------------
763
764The number if bits in the modulus for the DH group, if DHE or static
765DH is used.
766
767This will not be set if DH is not used.
768
[2b16350]769`SSL_CIPHER_EXPORT`
770-------------------
[4ee45a1]771
[2b16350]772`True` or `False`. Whether the cipher suite negotiated is an export one.
[4ee45a1]773
[2b16350]774`SSL_SESSION_ID`
775----------------
[4ee45a1]776
777The session ID negotiated in this session. Can be the same during client
778reloads.
779
[2b16350]780`SSL_CLIENT_V_REMAIN`
781---------------------
[4ee45a1]782
783The number of days until the client's certificate is expired.
784
[2b16350]785`SSL_CLIENT_V_START`
786--------------------
[4ee45a1]787
788The activation time of client's certificate.
789
[2b16350]790`SSL_CLIENT_V_END`
791------------------
[4ee45a1]792
793The expiration time of client's certificate.
794
[2b16350]795`SSL_CLIENT_S_DN`
796-----------------
[4ee45a1]797
798The distinguished name of client's certificate in RFC2253 format.
799
[2b16350]800`SSL_CLIENT_I_DN`
801-----------------
[4ee45a1]802
803The SSL or TLS cipher suite name
804
[2b16350]805`SSL_CLIENT_S_AN%`
806------------------
[4ee45a1]807
[2b16350]808These will contain the alternative names of the client certificate (`%` is
[4ee45a1]809a number starting from zero).
810
[2b16350]811The values will be prepended by `DNSNAME:`, `RFC822NAME:` or `URI:`
[4ee45a1]812depending on the type.
813
[2b16350]814If it is not supported the value `UNSUPPORTED` will be set.
[4ee45a1]815
[2b16350]816`SSL_SERVER_M_SERIAL`
817---------------------
[4ee45a1]818
819The serial number of the server's certificate.
820
[2b16350]821`SSL_SERVER_M_VERSION`
822----------------------
[4ee45a1]823
824The version of the server's certificate.
825
[2b16350]826`SSL_SERVER_A_SIG`
827------------------
[4ee45a1]828
829The algorithm used for the signature in server's certificate.
830
[2b16350]831`SSL_SERVER_A_KEY`
832------------------
[4ee45a1]833
834The public key algorithm in server's certificate.
835
[999cdec]836`SSL_SERVER_CERT`
[2b16350]837------------------
[4ee45a1]838
[999cdec]839The PEM-encoded (X.509) or ASCII-armored (OpenPGP) server certificate
840(see the `GnuTLSExportCertificates` directive).
[4ee45a1]841
[2b16350]842`SSL_SERVER_CERT_TYPE`
843----------------------
[4ee45a1]844
[2b16350]845The certificate type can be `X.509` or `OPENPGP`.
[ac32bb5]846
[999cdec]847`SSL_CLIENT_CERT`
848------------------
849
850The PEM-encoded (X.509) or ASCII-armored (OpenPGP) client certificate
851(see the `GnuTLSExportCertificates` directive).
852
[ac32bb5]853`SSL_CLIENT_CERT_TYPE`
854----------------------
855
856The certificate type can be `X.509` or `OPENPGP`.
Note: See TracBrowser for help on using the repository browser.