source: mod_gnutls/doc/mod_gnutls_manual.mdwn @ fc124e9

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

Handbook: Update configuration examples

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