source: mod_gnutls/doc/mod_gnutls_manual.mdwn @ a2e3c33

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

Rename option SSLProxyEngine to GnuTLSProxyEngine

This matches the general option naming scheme and avoids confusion with
mod_ssl. TLS proxy support was not implemented in earlier releases of
mod_gnutls, so the change should not cause problems.

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