source: mod_gnutls/doc/mod_gnutls_manual.mdwn @ dfd5837

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

Update documentation for use of X.509 keys and certificates

GnuTLSCertificateFile and GnuTLSKeyFile now accept PKCS #11 URLs, and a
key file may be encrypted if GnuTLSPIN is set to the key.

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