source: mod_gnutls/docs/mod_gnutls_manual.mdwn @ 5674676

Last change on this file since 5674676 was 5674676, checked in by Daniel Kahn Gillmor <dkg@…>, 8 years ago

add SSL_DH_PRIME_BITS to expose the size of the DH modulus to CGI

  • Property mode set to 100644
File size: 19.8 KB
[e7527b9]1% `mod_gnutls` Manual
3* * * * *
[e7527b9]5`mod_gnutls` is a module for the Apache web server that provides
6HTTPS (HTTP over Transport Layer Security (TLS) or the older Secure
7Sockets Layer (SSL)) using the GnuTLS library.
9* * * * *
11Compilation & Installation
[e7527b9]14`mod_gnutls` uses the `./configure && make && make install` mechanism
15common to many Open Source programs.  Most of the dirty work is
16handled by either `./configure` or Apache's `apxs` utility. If you have
17built Apache modules before, there shouldn't be any surprises for you.
19The interesting options you can pass to configure are:
22:   This option is used to specify the location of the apxs utility that
23    was installed as part of apache. Specify the location of the
24    binary, not the directory it is located in.
27:   Full path to the libgnutls-config program.
30:   Prefix to where apr\_memcache is installed.
33:   Provides a list of all available configure options.
35* * * * *
[2b16350]40To activate `mod_gnutls` just add the following line to your httpd.conf
[4ee45a1]41and restart Apache:
[2b16350]43    LoadModule gnutls_module modules/
45* * * * *
[2b16350]47Configuration Directives
[2b16350]53Enable GnuTLS for this virtual host
[2b16350]55    GnuTLSEnable [on|off]
[2b16350]57Default: *off*\
58Context: virtual host
[2b16350]60This directive enables SSL/TLS Encryption for a Virtual Host.
[2b16350]65Configure SSL Session Cache
[2b16350]67    GnuTLSCache [dbm|gdbm|memcache|none] [PATH|SERVERLIST|-]
[2b16350]69Default: `GnuTLSCache none`\
70Context: server config
[2b16350]72This directive configures the SSL Session Cache for `mod_gnutls`.
73This could be shared between machines of different architectures.
[2b16350]75`dbm` (Requires Berkeley DBM)
76:   Uses the default Berkeley DB backend of APR DBM to cache SSL
77    Sessions results.  The argument is a relative or absolute path to
78    be used as the DBM Cache file. This is compatible with most
79    operating systems, but needs the Apache Runtime to be compiled
80    with Berkeley DBM support.
83:   Uses the GDBM backend of APR DBM to cache SSL Sessions results.
[2b16350]85    The argument is a relative or absolute path to be used as the DBM Cache
86    file.  This is the recommended option.
89:   Uses a memcached server to cache the SSL Session.
[2b16350]91    The argument is a space separated list of servers. If no port
92    number is supplied, the default of 11211 is used.  This can be
93    used to share a session cache between all servers in a cluster.
96:   Turns off all caching of SSL Sessions.
[2b16350]98    This can significantly reduce the performance of `mod_gnutls` since
99    even followup connections by a client must renegotiate parameters
100    instead of reusing old ones.  This is the default, since it
101    requires no configuration.
[2b16350]106Timeout for SSL Session Cache expiration
[2b16350]108    GnuTLSCacheTimeout SECONDS
[2b16350]110Default: `GnuTLSCacheTimeout 300`\
111Context: server config
[2b16350]113Sets the timeout for SSL Session Cache entries expiration.  This
114directive is valid even if Session Tickets are used, and indicates the
115expiration time of the ticket in seconds.
[2b16350]120Enable Session Tickets for the server
[2b16350]122    GnuTLSSessionTickets [on|off]
[2b16350]124Default: `off`\
125Context: server config, virtual host
127To avoid storing data for TLS session resumption it is allowed to
[2b16350]128provide client with a ticket, to use on return.  Use for servers with
129limited storage, and don't combine with GnuTLSCache. For a pool of
130servers this option is not recommended since the tickets are unique
131for the issuing server only.
[2b16350]137Set to the PEM Encoded Server Certificate
[2b16350]139    GnuTLSCertificateFile FILEPATH
[2b16350]141Default: *none*\
142Context: server config, virtual host
144Takes an absolute or relative path to a PEM-encoded X.509 certificate to
145use as this Server's End Entity (EE) certificate. If you need to supply
146certificates for intermediate Certificate Authorities (iCAs), they
147should be listed in sequence in the file, from EE to the iCA closest to
148the root CA. Optionally, you can also include the root CA's certificate
149as the last certificate in the list.
[2b16350]154Set to the PEM Encoded Server Certificate
[2b16350]156    GnuTLSCertificateFile FILEPATH
[2b16350]158Default: *none*\
159Context: server config, virtual host
[2b16350]161Takes an absolute or relative path to the Server Private Key.  This
162key cannot currently be password protected.
164**Security Warning:**\
165 This private key must be protected. It is read while Apache is still
166running as root, and does not need to be readable by the nobody or
167apache user.
[2b16350]172Set to a base64 Encoded Server OpenPGP Certificate
[2b16350]174    GnuTLSPGPCertificateFile FILEPATH
[2b16350]176Default: *none*\
177Context: server config, virtual host
179Takes an absolute or relative path to a base64 Encoded OpenPGP
180Certificate to use as this Server's Certificate.
[2b16350]185Set to the Server OpenPGP Secret Key
[2b16350]187    GnuTLSPGPKeyFile FILEPATH
[2b16350]189Default: *none*\
190Context: server config, virtual host
192Takes an absolute or relative path to the Server Private Key. This key
193cannot currently be password protected.
195**Security Warning:**\
196 This private key must be protected. It is read while Apache is still
197running as root, and does not need to be readable by the nobody or
198apache user.
203Enable Client Certificate Verification\
[2b16350]205    GnuTLSClientVerify [ignore|request|require]
[2b16350]207Default: `ignore`\
208Context: server config, virtual host, directory, .htaccess
210This directive controls the use of SSL Client Certificate
[2b16350]211Authentication. If used in the .htaccess context, it can force TLS
215:   `mod_gnutls` will ignore the contents of any SSL Client Certificates
216    sent. It will not request that the client sends a certificate.
219:   The client certificate will be requested, but not required.
220    The Certificate will be validated if sent.  The output of the
221    validation status will be stored in the `SSL_CLIENT_VERIFY`
222    environment variable and can be `SUCCESS`, `FAILED` or `NONE`.
225:   A Client certificate will be required. Any requests without a valid
226    client certificate will be denied.  The `SSL_CLIENT_VERIFY`
227    environment variable will only be set to `SUCCESS`.
[2b16350]232Set to the PEM Encoded Certificate Authority Certificate
[2b16350]234    GnuTLSClientCAFile FILEPATH
[2b16350]236Default: *none*
237Context: server config, virtual host
239Takes an absolute or relative path to a PEM Encoded Certificate to use
[2b16350]240as a Certificate Authority with Client Certificate Authentication.
241This file may contain a list of trusted authorities.
[2b16350]246Set to a base64 Encoded key ring
[2b16350]248    GnuTLSPGPKeyringFile FILEPATH
[2b16350]250Default: *none*\
251Context: server config, virtual host
[2b16350]253Takes an absolute or relative path to a base64 Encoded Certificate
254list (key ring) to use as a means of verification of Client
255Certificates.  This file should contain a list of trusted signers.
[2b16350]260Set to the PKCS \#3 encoded Diffie Hellman parameters
[2b16350]262    GnuTLSDHFile FILEPATH
[2b16350]264Default: *none*\
265Context: server config, virtual host
[2b16350]267Takes an absolute or relative path to a PKCS \#3 encoded DH
268parameters.Those are used when the DHE key exchange method is enabled.
269You can generate this file using `certtool --generate-dh-params --bits
2702048`.  If not set `mod_gnutls` will use the included parameters.
[2b16350]275Set to the SRP password file for SRP ciphersuites
[2b16350]277    GnuTLSSRPPasswdFile FILEPATH
[2b16350]279Default: *none*\
280Context: server config, virtual host
[2b16350]282Takes an absolute or relative path to an SRP password file. This is
283the same format as used in libsrp.  You can generate such file using
284the command `srptool --passwd /etc/tpasswd --passwd-conf
285/etc/tpasswd.conf -u test` to set a password for user test.  This
286password file holds the username, a password verifier and the
287dependency to the SRP parameters.
[2b16350]292Set to the SRP password.conf file for SRP ciphersuites
[2b16350]294    GnuTLSSRPPasswdConfFile FILEPATH
[2b16350]296Default: *none*\
297Context: server config, virtual host
[2b16350]299Takes an absolute or relative path to an SRP password.conf file. This
300is the same format as used in `libsrp`.  You can generate such file
301using the command `srptool --create-conf /etc/tpasswd.conf`.  This
302file holds the SRP parameters and is associate with the password file
303(the verifiers depends on these parameters).
[2b16350]308Set the allowed ciphers, key exchange algorithms, MACs and compression
[2b16350]311    GnuTLSPriorities +CIPHER_0:+CIPHER_1:...:+CIPHER_N
[2b16350]313Default: *none*\
314Context: server config, virtual host
[2b16350]316Takes a semi-colon separated list of ciphers, key exchange methods
317Message authentication codes and compression methods to enable.
318The allowed keywords are specified in the `gnutls_priority_init()`
319function of GnuTLS.
[2b16350]321Its documentation can be found at [Core GnuTLS functions](
322In brief you can specify a set of ciphersuites from the choices:
325:   The empty list.
328:   A list with all the supported cipher combinations
329    including the `EXPORT` strength algorithms.
332:   A list with all the secure cipher combinations sorted in terms of performance.
335:   A list with all the secure cipher combinations sorted
336    with respect to security margin (subjective term).
339:   A list with all the secure cipher combinations including
340    the 256-bit ciphers sorted with respect to security margin.
[2b16350]342Additionally you can add or remove algorithms using the `+` and `!`
343prefixes respectively.
[2b16350]345For example, in order to disable the `ARCFOUR` cipher from the `NORMAL` set
346you can use the string `NORMAL:!ARCFOUR-128`
[2b16350]348Other options such as the protocol version and the compression method
349can be specified using the `VERS-` and `COMP-` prefixes.
[2b16350]351So in order to remove or add a specific TLS version from the `NORMAL`
352set, use `NORMAL:!VERS-SSL3.0`.  And to enable zlib compression use
[2b16350]356However it is recommended not to add compression at this level.  With
357the `NONE` set, in order to be usable, you have to specify a complete
358set of combinations of protocol versions, cipher algorithms
359(`AES-128-CBC`), key exchange algorithms (`RSA`), message
360authentication codes (`SHA1`) and compression methods (`COMP-NULL`).
[2b16350]362You can find a list of all supported Ciphers, Versions, MACs, etc.  by
363running `gnutls-cli --list`.
[2b16350]365The special keyword `%COMPAT` will disable some security features such
[4ee45a1]366as protection against statistical attacks to ciphertext data in order to
367achieve maximum compatibility (some broken mobile clients need this).
[2b16350]372Export the PEM encoded certificates to CGIs
[2b16350]374    GnuTLSExportCertificates [on|off]
[2b16350]376Default: `off`\
377Context: server config, virtual host
379This directive enables exporting the full certificates of the server and
380the client to CGI scripts. The exported certificates will be PEM-encoded
[2b16350]381(if X.509) or ASCII-armored (if OpenPGP).
382With GnuTLSExportCertificates enabled, `mod_gnutls` exports the same
383environment variables to the CGI process as `mod_ssl`.
385* * * * *
387Configuration Examples
[2b16350]390Simple Standard SSL Example
393The following is an example of standard SSL Hosting, using one IP
394Addresses for each virtual host
[2b16350]396     # Load the module into Apache.
397     LoadModule gnutls_module modules/
398     GnuTLSCache gdbm /var/cache/www-tls-cache
399     GnuTLSCacheTimeout 500
400     # With normal SSL Websites, you need one IP Address per-site.
401     Listen
402     Listen
403     Listen
404     Listen
405     <VirtualHost>
406     GnuTLSEnable on
408     DocumentRoot /www/
409     ServerName
410     GnuTLSCertificateFile conf/ssl/site1.crt
411     GnuTLSKeyFile conf/ss/site1.key
412     </VirtualHost>
413     <VirtualHost>
414     # This virtual host enables SRP authentication
415     GnuTLSEnable on
416     GnuTLSPriorities NORMAL:+SRP
417     DocumentRoot /www/
418     ServerName
419     GnuTLSSRPPasswdFile conf/ssl/tpasswd.site2
420     GnuTLSSRPPasswdConfFile conf/ssl/tpasswd.site2.conf
421     </VirtualHost>
422     <VirtualHost>
423     # This server enables SRP, OpenPGP and X.509 authentication.
424     GnuTLSEnable on
425     GnuTLSPriorities NORMAL:+SRP:+SRP-RSA:+SRP-DSS
426     DocumentRoot /www/
427     ServerName
428     GnuTLSCertificateFile conf/ssl/site3.crt
429     GnuTLSKeyFile conf/ss/site3.key
430     GnuTLSClientVerify ignore
431     GnuTLSPGPCertificateFile conf/ss/
432     GnuTLSPGPKeyFile conf/ss/site3.sec.asc
433     GnuTLSSRPPasswdFile conf/ssl/tpasswd.site3
434     GnuTLSSRPPasswdConfFile conf/ssl/tpasswd.site3.conf
435     </VirtualHost>
436     <VirtualHost>
437     GnuTLSEnable on
438     # %COMPAT disables some security features to enable maximum compatibility with clients.
439     GnuTLSPriorities NONE:+AES-128-CBC:+ARCFOUR-128:+RSA:+SHA1:+MD5:+COMP-NULL:%COMPAT
440     DocumentRoot /www/
441     ServerName
442     GnuTLSCertificateFile conf/ssl/site4.crt
443     GnuTLSKeyFile conf/ss/site4.key
444     </VirtualHost>
446Server Name Indication Example
449`mod_gnutls` can also use "Server Name Indication", as specified in
450RFC 3546.  This allows hosting many SSL Websites, with a Single IP
451Address.  Currently all the recent browsers support this
452standard. Here is an example, using SNI: ` `
455     # Load the module into Apache.
456     LoadModule gnutls_module modules/
457     # With normal SSL Websites, you need one IP Address per-site.
458     Listen
459     # This could also be 'Listen *:443',
460     # just like '*:80' is common for non-https
461     # No caching. Enable session tickets. Timeout is still used for
462     # ticket expiration.
463     GnuTLSCacheTimeout 600
464     # This tells apache, that for this IP/Port combination, we want to use
465     # Name Based Virtual Hosting. In the case of Server Name Indication,
466     # it lets mod_gnutls pick the correct Server Certificate.
467     NameVirtualHost
468     <VirtualHost>
469     GnuTLSEnable on
470     GnuTLSSessionTickets on
471     GnuTLSPriorities NORMAL
472     DocumentRoot /www/
473     ServerName
474     GnuTLSCertificateFile conf/ssl/site1.crt
475     GnuTLSKeyFile conf/ss/site1.key
476     </VirtualHost>
477     <VirtualHost>
478     GnuTLSEnable on
479     GnuTLSPriorities NORMAL
480     DocumentRoot /www/
481     ServerName
482     GnuTLSCertificateFile conf/ssl/site2.crt
483     GnuTLSKeyFile conf/ss/site2.key
484     </VirtualHost>
485     <VirtualHost>
486     GnuTLSEnable on
487     GnuTLSPriorities NORMAL
488     DocumentRoot /www/
489     ServerName
490     GnuTLSCertificateFile conf/ssl/site3.crt
491     GnuTLSKeyFile conf/ss/site3.key
492     </VirtualHost>
493     <VirtualHost>
494     GnuTLSEnable on
495     GnuTLSPriorities NORMAL
496     DocumentRoot /www/
497     ServerName
498     GnuTLSCertificateFile conf/ssl/site4.crt
499     GnuTLSKeyFile conf/ss/site4.key
500     </VirtualHost>
[2b16350]503* * * * *
[2b16350]505Performance Issues
508`mod_gnutls` by default uses conservative settings for the server.
509You can fine tune the configuration to reduce the load on a busy
510server.  The following examples do exactly this:
513     # Load the module into Apache.
514     LoadModule gnutls_module modules/
515     # Using 4 memcache servers to distribute the SSL Session Cache.
516     GnuTLSCache memcache ""
517     GnuTLSCacheTimeout 600
518     Listen
519     NameVirtualHost
520     <VirtualHost>
521     GnuTLSEnable on
522     # Here we disable the Perfect forward secrecy ciphersuites (DHE)
523     # and disallow AES-256 since AES-128 is just fine.
524     GnuTLSPriorities NORMAL:!DHE-RSA:!DHE-DSS:!AES-256-CBC:%COMPAT
525     DocumentRoot /www/
526     ServerName
527     GnuTLSCertificateFile conf/ssl/site1.crt
528     GnuTLSKeyFile conf/ss/site1.key
529     </VirtualHost>
530     <VirtualHost>
531     GnuTLSEnable on
532     # Here we instead of disabling the DHE ciphersuites we use
533     # Diffie Hellman parameters of smaller size than the default (2048 bits).
534     # Using small numbers from 768 to 1024 bits should be ok once they are
535     # regenerated every few hours.
536     # Use "certtool --generate-dh-params --bits 1024" to get those
537     GnuTLSDHFile /etc/apache2/dh.params
538     GnuTLSPriorities NORMAL:!AES-256-CBC:%COMPAT
539     DocumentRoot /www/
540     ServerName
541     GnuTLSCertificateFile conf/ssl/site2.crt
542     GnuTLSKeyFile conf/ss/site2.key
543     </VirtualHost>
545* * * * *
[2b16350]547Environment Variables
[2b16350]550`mod_gnutls` exports the following environment variables to scripts.
551These are compatible with `mod_ssl`.
[2b16350]556Can be `on` or `off`
[2b16350]561The version of the GnuTLS library
566The version of this module
[2b16350]571The SSL or TLS protocol name (such as `TLS 1.0` etc.)
576The SSL or TLS cipher suite name
[2b16350]581The negotiated compression method (`NULL` or `DEFLATE`)
586The SRP username used for authentication (only set when
[2b16350]587`GnuTLSSRPPasswdFile` and `GnuTLSSRPPasswdConfFile` are configured).
592The number if bits used in the used cipher algorithm.
594This does not fully reflect the security level since the size of
595RSA or DHE key exchange parameters affect the security level too.
600The number if bits in the modulus for the DH group, if DHE or static
601DH is used.
603This will not be set if DH is not used.
[2b16350]608`True` or `False`. Whether the cipher suite negotiated is an export one.
613The session ID negotiated in this session. Can be the same during client
619The number of days until the client's certificate is expired.
624The activation time of client's certificate.
629The expiration time of client's certificate.
634The distinguished name of client's certificate in RFC2253 format.
639The SSL or TLS cipher suite name
[2b16350]644These will contain the alternative names of the client certificate (`%` is
[4ee45a1]645a number starting from zero).
[2b16350]647The values will be prepended by `DNSNAME:`, `RFC822NAME:` or `URI:`
[4ee45a1]648depending on the type.
[2b16350]650If it is not supported the value `UNSUPPORTED` will be set.
655The serial number of the server's certificate.
660The version of the server's certificate.
665The algorithm used for the signature in server's certificate.
670The public key algorithm in server's certificate.
675The PEM-encoded server certificate.
[2b16350]680The certificate type can be `X.509` or `OPENPGP`.
Note: See TracBrowser for help on using the repository browser.