source: mod_gnutls/doc/mod_gnutls_manual.mdwn @ fdd3bf0

asynciodebian/masterproxy-ticket
Last change on this file since fdd3bf0 was fdd3bf0, checked in by Fiona Klute <fiona.klute@…>, 2 years ago

Enable session tickets by default if GnuTLS version >= 3.6.4

GnuTLS 3.6.4 introduced automatic master key rotation, and TLS 1.3
takes care of other reasons not to use tickets while requiring them
for session resumption.

  • Property mode set to 100644
File size: 28.0 KB
RevLine 
[e7527b9]1% `mod_gnutls` Manual
[4ee45a1]2
3* * * * *
4
[bce7907]5`mod_gnutls` is a module for the Apache web server that provides HTTPS
[2246a84]6(HTTP over Transport Layer Security (TLS)) using the GnuTLS library.
7More information about the module can be found at
8[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
[df49a2d]55General Options
56---------------
57
58### GnuTLSEnable
[4ee45a1]59
[2b16350]60Enable GnuTLS for this virtual host
[4ee45a1]61
[2b16350]62    GnuTLSEnable [on|off]
[4ee45a1]63
[2b16350]64Default: *off*\
65Context: virtual host
[4ee45a1]66
[2b16350]67This directive enables SSL/TLS Encryption for a Virtual Host.
[4ee45a1]68
[df49a2d]69### GnuTLSCache
[4ee45a1]70
[743e31f]71Configure TLS Session Cache
[4ee45a1]72
[7105869]73    GnuTLSCache (shmcb|dbm|memcache|...|none)[:PARAMETERS]
[4ee45a1]74
[2b16350]75Default: `GnuTLSCache none`\
76Context: server config
[4ee45a1]77
[7105869]78This directive configures the TLS Session Cache for `mod_gnutls`. This
79could be shared between machines of different architectures. If the
80selected cache implementation is not thread-safe, access is serialized
81using the `gnutls-cache` mutex.
[4ee45a1]82
[7105869]83Which cache implementations are available depends on your Apache
84installation and configuration, `mod_gnutls` can use any socache
85provider. In general you will need to load a `mod_socache_PROVIDER`
86module. Common options are described below, please check the Apache
87HTTPD documentation for details on available providers and their
88configuration.
[4ee45a1]89
[7105869]90`shmcb`
91:   Uses a shared memory segment. This is a high performance local
92    cache. The parameter is a relative or absolute path to be used if
93    the local shared memory implementation requires one, followed by
94    the cache size in bytes enclosed in parentheses.
[c22af3a]95
[7105869]96    Example: `shmcb:cache/gnutls_cache(65536)`
[4ee45a1]97
[7105869]98`dbm`
99:   Uses a DBM cache file. The parameter is a relative or absolute
100    path to be used as the DBM cache file.
101
102    Example: `dbm:cache/gnutls_cache`
[4ee45a1]103
[2b16350]104`memcache`
[7105869]105:   Uses memcached server(s) to cache TLS session data. The parameter
106    is a comma separated list of servers (host:port). This can be used
107    to share a session cache between all servers in a cluster.
[4ee45a1]108
[7105869]109    Example: `memcache:memcache.example.com:12345,memcache2.example.com:12345`
[4ee45a1]110
[2b16350]111`none`
[7105869]112:   Turns off all caching of TLS sessions.
113
114    This can significantly reduce the performance of `mod_gnutls`
115    since even followup connections by a client must renegotiate
116    parameters instead of reusing old ones. This is the default, since
117    it requires no configuration.
[4ee45a1]118
[7105869]119    Session tickets are an alternative to using a session cache,
120    please see `GnuTLSSessionTickets`. Note that for TLS 1.3 GnuTLS
121    supports resumption using session tickets only as of version
122    3.6.4.
[4ee45a1]123
[df49a2d]124### GnuTLSCacheTimeout
[4ee45a1]125
[743e31f]126Timeout for TLS Session Cache expiration
[4ee45a1]127
[2b16350]128    GnuTLSCacheTimeout SECONDS
[4ee45a1]129
[2b16350]130Default: `GnuTLSCacheTimeout 300`\
[f52f1b4]131Context: server config, virtual host
[4ee45a1]132
[ed5d2b8]133Sets the expiration timeout for cached TLS sessions.
[4ee45a1]134
[df49a2d]135### GnuTLSSessionTickets
[4ee45a1]136
[2b16350]137Enable Session Tickets for the server
[4ee45a1]138
[2b16350]139    GnuTLSSessionTickets [on|off]
[4ee45a1]140
[fdd3bf0]141Default: `on` with GnuTLS 3.6.4 and newer, `off` otherwise\
[2b16350]142Context: server config, virtual host
[4ee45a1]143
[fdd3bf0]144Session tickets allow TLS session resumption without session state
145stored on the server, using encrypted tickets provided to the clients
146instead. Tickets are an alternative to using a session cache, and
147currently the only session resumption mechanism in TLS 1.3. For a pool
148of servers this option is not recommended since the tickets are bound
149to the issuing server only.
[4ee45a1]150
[e9ef72c]151If this option is set in the global configuration, virtual hosts
152without a `GnuTLSSessionTickets` setting will use the global setting.
153
[fdd3bf0]154*Warning:* With GnuTLS version before 3.6.4 the master key that
155protects the tickets is generated only on server start, and there is
156no mechanism to roll over the key. If session tickets are enabled it
157is highly recommended to restart the server regularly to protect past
158sessions in case an attacker gains access to server memory. GnuTLS
1593.6.4 introduced an automatic TOTP-based key rollover, so this warning
160does not apply any more and tickets are enabled by default.
[4ee45a1]161
[df49a2d]162### GnuTLSClientVerify
[4ee45a1]163
[df49a2d]164Enable Client Certificate Verification
[4ee45a1]165
[2b16350]166    GnuTLSClientVerify [ignore|request|require]
[4ee45a1]167
[2b16350]168Default: `ignore`\
169Context: server config, virtual host, directory, .htaccess
[4ee45a1]170
[743e31f]171This directive controls the use of TLS Client Certificate
[2b16350]172Authentication. If used in the .htaccess context, it can force TLS
173re-negotiation.
[4ee45a1]174
[2b16350]175`ignore`
[743e31f]176:   `mod_gnutls` will ignore the contents of any TLS Client Certificates
[2b16350]177    sent. It will not request that the client sends a certificate.
[4ee45a1]178
[2b16350]179`request`
180:   The client certificate will be requested, but not required.
181    The Certificate will be validated if sent.  The output of the
182    validation status will be stored in the `SSL_CLIENT_VERIFY`
183    environment variable and can be `SUCCESS`, `FAILED` or `NONE`.
[4ee45a1]184
[2b16350]185`require`
186:   A Client certificate will be required. Any requests without a valid
187    client certificate will be denied.  The `SSL_CLIENT_VERIFY`
188    environment variable will only be set to `SUCCESS`.
[4ee45a1]189
[df49a2d]190### GnuTLSDHFile
[4ee45a1]191
[bd6591f]192Use the provided PKCS \#3 encoded Diffie-Hellman parameters
[4ee45a1]193
[2b16350]194    GnuTLSDHFile FILEPATH
[4ee45a1]195
[2b16350]196Default: *none*\
197Context: server config, virtual host
[4ee45a1]198
[bd6591f]199By default, `mod_gnutls` uses the DH parameters included with GnuTLS
200corresponding to the security level of the configured private keys if
201compiled with GnuTLS 3.5.6 or newer, and the ffdhe2048 DH group as
202defined in RFC 7919, Appendix A.1 otherwise.
203
204If you need to use different DH parameters, you can provide a PEM file
205containing them in PKCS \#3 encoding using this option. Please see the
206"[Parameter
207generation](https://gnutls.org/manual/html_node/Parameter-generation.html)"
208section of the GnuTLS documentation for a short discussion of the
209security implications.
[4ee45a1]210
[df49a2d]211### GnuTLSPriorities
[4ee45a1]212
[c3c96ca]213Set the allowed protocol versions, ciphers, key exchange algorithms,
214MACs and compression methods
[4ee45a1]215
[5409165]216    GnuTLSPriorities NORMAL:+CIPHER_0:+CIPHER_1:...:+CIPHER_N
[4ee45a1]217
[60868d2]218Default: `NORMAL`\
[2b16350]219Context: server config, virtual host
[4ee45a1]220
[60868d2]221Sets the allowed protocol version(s), ciphers, key exchange methods,
222message authentication codes, and other TLS parameters for the server.
223The parameter is a GnuTLS priority string as described in the
224[the GnuTLS documentation](https://gnutls.org/manual/html_node/Priority-Strings.html).
[4ee45a1]225
[60868d2]226For example, to disable TLS 1.0 use `NORMAL:-VERS-TLS1.0`.
[4ee45a1]227
[df49a2d]228### GnuTLSP11Module
[8873a06]229
[7764015]230Load this PKCS #11 module.
[8873a06]231
232    GnuTLSP11Module PATH_TO_LIBRARY
233
234Default: *none*\
235Context: server config
236
[9ca1f21]237Load this PKCS #11 provider module, instead of the system
238defaults. May occur multiple times to load multiple modules.
[8873a06]239
[df49a2d]240### GnuTLSPIN
[031acac]241
242Set the PIN to be used to access encrypted key files or PKCS #11 objects.
243
244    GnuTLSPIN XXXXXX
245
246Default: *none*\
247Context: server config, virtual host
248
249Takes a string to be used as a PIN for the protected objects in
250a security module, or as a key to be used to decrypt PKCS #8, PKCS #12,
251or openssl encrypted keys.
252
[df49a2d]253### GnuTLSSRKPIN
[031acac]254
[df49a2d]255Set the SRK PIN to be used to access the TPM.
[031acac]256
257    GnuTLSSRKPIN XXXXXX
258
259Default: *none*\
260Context: server config, virtual host
261
262Takes a string to be used as a PIN for the protected objects in
263the TPM module.
264
[df49a2d]265### GnuTLSExportCertificates
[4ee45a1]266
[2b16350]267Export the PEM encoded certificates to CGIs
[4ee45a1]268
[999cdec]269    GnuTLSExportCertificates [off|on|SIZE]
[4ee45a1]270
[2b16350]271Default: `off`\
272Context: server config, virtual host
[4ee45a1]273
[999cdec]274This directive configures exporting the full certificates of the
275server and the client to CGI scripts via the `SSL_SERVER_CERT` and
276`SSL_CLIENT_CERT` environment variables. The exported certificates
[e796121]277will be PEM-encoded, limited to the given size. The type of the
278certificate will be exported in `SSL_SERVER_CERT_TYPE` and
279`SSL_CLIENT_CERT_TYPE`.
[999cdec]280
281SIZE should be an integer number of bytes, or may be written with a
282trailing `K` to indicate kibibytes.  `off` means the same thing as
283`0`, in which case the certificates will not be exported to the
[e796121]284environment. `on` is an alias for `16K`. If a non-zero size is
[999cdec]285specified for this directive, but a certificate is too large to fit in
286the buffer, then the corresponding environment variable will contain
287the fixed string `GNUTLS_CERTIFICATE_SIZE_LIMIT_EXCEEDED`.
288
[2b16350]289With GnuTLSExportCertificates enabled, `mod_gnutls` exports the same
290environment variables to the CGI process as `mod_ssl`.
[4ee45a1]291
[df49a2d]292X.509 Certificate Authentication
293--------------------------------
294
295### GnuTLSCertificateFile
[d8ae2a0]296
[df49a2d]297Set to the PEM Encoded Server Certificate
298
299    GnuTLSCertificateFile FILEPATH
300
301Default: *none*\
302Context: server config, virtual host
303
304Takes an absolute or relative path to a PEM-encoded X.509 certificate to
305use as this Server's End Entity (EE) certificate. If you need to supply
306certificates for intermediate Certificate Authorities (iCAs), they
307should be listed in sequence in the file, from EE to the iCA closest to
308the root CA. Optionally, you can also include the root CA's certificate
309as the last certificate in the list.
310
311Since version 0.7 this can be a PKCS #11 URL.
312
313### GnuTLSKeyFile
314
315Set to the PEM Encoded Server Private Key
316
317    GnuTLSKeyFile FILEPATH
318
319Default: *none*\
320Context: server config, virtual host
321
322Takes an absolute or relative path to the Server Private Key. Set
323`GnuTLSPIN` if the key file is encrypted.
324
325Since version 0.7 this can be a PKCS #11 URL.
326
327**Security Warning:**\
328This private key must be protected. It is read while Apache is still
329running as root, and does not need to be readable by the nobody or
330apache user.
331
332### GnuTLSClientCAFile
333
334Set the PEM encoded Certificate Authority list to use for X.509 base
335client authentication
336
337    GnuTLSClientCAFile FILEPATH
338
339Default: *none*
340Context: server config, virtual host
341
342Takes an absolute or relative path to a PEM Encoded Certificate to use
343as a Certificate Authority with Client Certificate Authentication.
344This file may contain a list of trusted authorities.
345
346SRP Authentication
347------------------
348
349### GnuTLSSRPPasswdFile
350
351Set to the SRP password file for SRP ciphersuites
352
353    GnuTLSSRPPasswdFile FILEPATH
354
355Default: *none*\
356Context: server config, virtual host
357
358Takes an absolute or relative path to an SRP password file. This is
359the same format as used in libsrp.  You can generate such file using
360the command `srptool --passwd /etc/tpasswd --passwd-conf
361/etc/tpasswd.conf -u test` to set a password for user test.  This
362password file holds the username, a password verifier and the
363dependency to the SRP parameters.
364
365### GnuTLSSRPPasswdConfFile
366
367Set to the SRP password.conf file for SRP ciphersuites
368
369    GnuTLSSRPPasswdConfFile FILEPATH
370
371Default: *none*\
372Context: server config, virtual host
373
374Takes an absolute or relative path to an SRP password.conf file. This
375is the same format as used in `libsrp`.  You can generate such file
376using the command `srptool --create-conf /etc/tpasswd.conf`.  This
377file holds the SRP parameters and is associate with the password file
378(the verifiers depends on these parameters).
379
380TLS Proxy Configuration
381-----------------------
382
383### GnuTLSProxyEngine
[d8ae2a0]384
385Enable TLS proxy connections for this virtual host
386
[a2e3c33]387    GnuTLSProxyEngine [on|off]
[d8ae2a0]388
389Default: *off*\
390Context: virtual host
391
392This directive enables support for TLS proxy connections for a virtual
393host.
394
[df49a2d]395### GnuTLSProxyCAFile
[d8ae2a0]396
[809c422]397Set to the PEM encoded Certificate Authority Certificate
[d8ae2a0]398
399    GnuTLSProxyCAFile FILEPATH
400
401Default: *none*\
402Context: server config, virtual host
403
[809c422]404Takes an absolute or relative path to a PEM encoded certificate to use
[d8ae2a0]405as a Certificate Authority when verifying certificates provided by
406proxy back end servers. This file may contain a list of trusted
407authorities. If not set, verification of TLS back end servers will
408always fail due to lack of a trusted CA.
409
[df49a2d]410### GnuTLSProxyCRLFile
[809c422]411
412Set to the PEM encoded Certificate Revocation List
413
414    GnuTLSProxyCRLFile FILEPATH
415
416Default: *none*\
417Context: server config, virtual host
418
419Takes an absolute or relative path to a PEM encoded Certificate
420Revocation List to use when verifying certificates provided by proxy
421back end servers. The file may contain a list of CRLs.
422
[df49a2d]423### GnuTLSProxyCertificateFile
[d8ae2a0]424
[809c422]425Set to the PEM encoded Client Certificate
[d8ae2a0]426
427    GnuTLSProxyCertificateFile FILEPATH
428
429Default: *none*\
430Context: server config, virtual host
431
[809c422]432Takes an absolute or relative path to a PEM encoded X.509 certificate
[d8ae2a0]433to use as this Server's End Entity (EE) client certificate for TLS
434client authentication in proxy TLS connections. If you need to supply
435certificates for intermediate Certificate Authorities (iCAs), they
436should be listed in sequence in the file, from EE to the iCA closest
437to the root CA. Optionally, you can also include the root CA's
438certificate as the last certificate in the list.
439
440If not set, TLS client authentication will be disabled for TLS proxy
441connections. If set, `GnuTLSProxyKeyFile` must be set as well to
442provide the matching private key.
443
[df49a2d]444### GnuTLSProxyKeyFile
[d8ae2a0]445
[809c422]446Set to the PEM encoded Private Key
[d8ae2a0]447
448    GnuTLSProxyKeyFile FILEPATH
449
450Default: *none*\
451Context: server config, virtual host
452
453Takes an absolute or relative path to the Private Key matching the
454certificate configured using the `GnuTLSProxyCertificateFile`
455directive. This key cannot currently be password protected.
456
457**Security Warning:**\
458This private key must be protected. It is read while Apache is still
459running as root, and does not need to be readable by the nobody or
460apache user.
461
[df49a2d]462### GnuTLSProxyPriorities
[f030883]463
464Set the allowed ciphers, key exchange algorithms, MACs and compression
465methods for proxy connections
466
467    GnuTLSProxyPriorities NORMAL:+CIPHER_0:+CIPHER_1:...:+CIPHER_N
468
[60868d2]469Default: `NORMAL`\
[f030883]470Context: server config, virtual host
471
[60868d2]472Sets the allowed protocol version(s), ciphers, key exchange methods,
473message authentication codes, and other TLS parameters for TLS proxy
474connections. Like for `GnuTLSPriorities` the parameter is a GnuTLS
475priority string as described in the
476[the GnuTLS documentation](https://gnutls.org/manual/html_node/Priority-Strings.html).
[f030883]477
[df49a2d]478OCSP Stapling Configuration
479---------------------------
480
481### GnuTLSOCSPStapling
[5a5032f]482
[0cd8f3d]483Enable OCSP stapling for this (virtual) host.
[5a5032f]484
485    GnuTLSOCSPStapling [On|Off]
486
487Default: *off*\
488Context: server config, virtual host
489
490OCSP stapling, formally known as the TLS Certificate Status Request
491extension, allows the server to provide the client with an OCSP
492response for its certificate during the handshake. This way the client
493does not have to send an OCSP request to the CA to check the
494certificate status, which offers privacy and performance advantages.
495
496Using OCSP stapling has a few requirements:
497
498* Caching OCSP responses requires a cache, so `GnuTLSCache` must not
499  be `none`.
500* `GnuTLSCertificateFile` must contain the issuer CA certificate in
501  addition to the server certificate so responses can be verified.
502* The certificate must either contain an OCSP access URI using HTTP,
503  or `GnuTLSOCSPResponseFile` must be set.
504
505OCSP cache updates are serialized using the `gnutls-ocsp` mutex.
506
[2246a84]507### GnuTLSOCSPAutoRefresh
508
509Regularly refresh cached OCSP response independent of TLS handshakes?
510
511    GnuTLSOCSPAutoRefresh [On|Off]
512
513Default: *on*\
514Context: server config, virtual host
515
516By default `mod_gnutls` will regularly refresh the cached OCSP
517response for hosts that have OCSP stapling enabled, regardless of
518whether it is used. This has advantages over updating the OCSP
519response only if a TLS handshake needs it:
520
521* Updating the cached response before it expires can hide short
522  unavailability of the OCSP responder, if a repeated request is
523  successful before the cache expires (see below).
524
525* Handshakes are not slowed down by fetching responses.
526
527The interval to the next request is determined as follows: After a
528successful OCSP request the next one is scheduled for a random period
529between `GnuTLSOCSPFuzzTime` and half of it before
530`GnuTLSOCSPCacheTimeout` expires. For example, if the cache timeout is
5313600 seconds and the fuzz time 600 seconds, the next request will be
532sent after 3000 to 3300 seconds. If the validity period of the
533response expires before then, the selected interval is halved until it
534is smaller than the time until expiry. If an OCSP request fails, it is
535retried after `GnuTLSOCSPFailureTimeout`.
536
537Regularly updating the OCSP cache requires `mod_watchdog`,
538`mod_gnutls` will fall back to updating the OCSP cache during
539handshakes if `mod_watchdog` is not available or this option is set to
540`Off`.
541
[b888e8b]542### GnuTLSOCSPCheckNonce
543
544Check the nonce in OCSP responses?
545
546    GnuTLSOCSPCheckNonce [On|Off]
547
548Default: *on*\
549Context: server config, virtual host
550
551Some CAs refuse to send nonces in their OCSP responses, probably
552because that way they can cache responses. If your CA is one of them
553you can use this flag to disable nonce verification. Note that
554`mod_gnutls` will _send_ a nonce either way.
555
[df49a2d]556### GnuTLSOCSPResponseFile
[5a5032f]557
[0cd8f3d]558Read the OCSP response for stapling from this file instead of sending
559a request over HTTP.
[5a5032f]560
561    GnuTLSOCSPResponseFile /path/to/response.der
562
563Default: *empty*\
564Context: server config, virtual host
565
566The response file must be updated externally, for example using a cron
567job. This option is an alternative to the server fetching OCSP
568responses over HTTP. Reasons to use this option include:
569
570* Performing OCSP requests separate from the web server, to prevent slow
571  responses from stalling handshakes.
572* The issuer CA uses an access method other than HTTP.
573* Testing
574
[b34a67e]575You can use a GnuTLS `ocsptool` command like the following to create
576and update the response file:
577
578    ocsptool --ask --nonce --load-issuer ca_cert.pem \
579        --load-cert server_cert.pem --outfile ocsp_response.der
580
581Additional error checking is highly recommended. You may have to
582remove the `--nonce` option if the OCSP responder of your CA does not
583support nonces.
584
[e1c094c]585### GnuTLSOCSPCacheTimeout
[5a5032f]586
[e1c094c]587Cache timeout for OCSP responses
[5a5032f]588
[e1c094c]589    GnuTLSOCSPCacheTimeout SECONDS
[5a5032f]590
[e1c094c]591Default: *3600*\
[5a5032f]592Context: server config, virtual host
593
[e1c094c]594Cached OCSP responses will be refreshed after the configured number of
595seconds. How long this timeout should reasonably be depends on your
596CA, namely how often its OCSP responder is updated and how long
597responses are valid. Note that a response will not be cached beyond
598its lifetime as denoted in the `nextUpdate` field of the response.
[5a5032f]599
[c6dda6d]600### GnuTLSOCSPFailureTimeout
601
[0cd8f3d]602Wait this many seconds before retrying a failed OCSP request.
[c6dda6d]603
604    GnuTLSOCSPFailureTimeout SECONDS
605
606Default: *300*\
607Context: server config, virtual host
608
609Retries of failed OCSP requests must be rate limited to avoid
610overloading both the server using mod_gnutls and the CA's OCSP
611responder. A shorter value increases the load on both sides, a longer
612one means that stapling will remain disabled for longer after a failed
613request.
614
[2246a84]615### GnuTLSOCSPFuzzTime
616
617Update the cached OCSP response up to this time before the cache expires
618
619    GnuTLSOCSPFuzzTime SECONDS
620
621Default: *larger of GnuTLSOCSPCacheTimeout / 8 and GnuTLSOCSPFailureTimeout \* 2*\
622Context: server config, virtual host
623
624Refreshing the cached response before it expires hides short OCSP
625responder unavailability. See `GnuTLSOCSPAutoRefresh` for how this
626value is used, using at least twice `GnuTLSOCSPFailureTimeout` is
627recommended.
628
[333bbc7]629### GnuTLSOCSPSocketTimeout
630
[0cd8f3d]631Timeout for TCP sockets used to send OCSP requests
[333bbc7]632
633    GnuTLSOCSPFailureTimeout SECONDS
634
635Default: *6*\
636Context: server config, virtual host
637
638Stalled OCSP requests must time out after a while to prevent stalling
639the server too much. However, if the timeout is too short requests may
640fail with a slow OCSP responder or high latency network
641connection. This parameter allows you to adjust the timeout if
642necessary.
643
644Note that this is not an upper limit for the completion of an OCSP
645request but a socket timeout. The connection will time out if there is
646no activity (successful send or receive) at all for the configured
647time.
648
[4ee45a1]649* * * * *
650
651Configuration Examples
[2b16350]652======================
[4ee45a1]653
[743e31f]654Simple Standard TLS Example
[2b16350]655---------------------------
[4ee45a1]656
[fc124e9]657The following is an example of simple TLS hosting, using one IP
658Addresses for each virtual host.
[4ee45a1]659
[2b16350]660     # Load the module into Apache.
661     LoadModule gnutls_module modules/mod_gnutls.so
[7105869]662     GnuTLSCache dbm:/var/cache/www-tls-cache
[2b16350]663     GnuTLSCacheTimeout 500
[fc124e9]664
665     # Without SNI you need one IP Address per-site.
666     Listen 192.0.2.1:443
667     Listen 192.0.2.2:443
668     Listen 192.0.2.3:443
669     Listen 192.0.2.4:443
670
671     <VirtualHost 192.0.2.1:443>
672         GnuTLSEnable on
673         GnuTLSPriorities SECURE128
674         DocumentRoot /www/site1.example.com/html
675         ServerName site1.example.com:443
676         GnuTLSCertificateFile conf/tls/site1.crt
677         GnuTLSKeyFile conf/tls/site1.key
[2b16350]678     </VirtualHost>
[fc124e9]679
680     <VirtualHost 192.0.2.2:443>
681         # This virtual host enables SRP authentication
682         GnuTLSEnable on
683         GnuTLSPriorities NORMAL:+SRP
684         DocumentRoot /www/site2.example.com/html
685         ServerName site2.example.com:443
686         GnuTLSSRPPasswdFile conf/tls/tpasswd.site2
687         GnuTLSSRPPasswdConfFile conf/tls/tpasswd.site2.conf
[2b16350]688     </VirtualHost>
[fc124e9]689
690     <VirtualHost 192.0.2.3:443>
[e796121]691         # This server enables SRP and X.509 authentication.
[fc124e9]692         GnuTLSEnable on
[e796121]693         GnuTLSPriorities NORMAL:+SRP:+SRP-RSA:+SRP-DSS
[fc124e9]694         DocumentRoot /www/site3.example.com/html
695         ServerName site3.example.com:443
696         GnuTLSCertificateFile conf/tls/site3.crt
697         GnuTLSKeyFile conf/tls/site3.key
698         GnuTLSClientVerify ignore
699         GnuTLSSRPPasswdFile conf/tls/tpasswd.site3
700         GnuTLSSRPPasswdConfFile conf/tls/tpasswd.site3.conf
[2b16350]701     </VirtualHost>
[fc124e9]702
703     <VirtualHost 192.0.2.4:443>
704         GnuTLSEnable on
705         # %COMPAT disables some security features to enable maximum
706         # compatibility with clients. Don't use this if you need strong
707         # security.
708         GnuTLSPriorities NORMAL:%COMPAT
709         DocumentRoot /www/site4.example.com/html
710         ServerName site4.example.com:443
711         GnuTLSCertificateFile conf/tls/site4.crt
712         GnuTLSKeyFile conf/tls/site4.key
[2b16350]713     </VirtualHost>
714
715Server Name Indication Example
716------------------------------
717
[fc124e9]718`mod_gnutls` supports "Server Name Indication", as specified in
[a09df8c]719[RFC 6066, Section 3](https://tools.ietf.org/html/rfc6066#section-3). This
720allows hosting many TLS websites with a single IP address. All recent
721browsers support this standard. Here is an example using SNI:
[2b16350]722
723     # Load the module into Apache.
724     LoadModule gnutls_module modules/mod_gnutls.so
[fc124e9]725
726     # SNI allows hosting multiple sites using one IP address. This
727     # could also be 'Listen *:443', just like '*:80' is common for
728     # non-HTTPS
729     Listen 198.51.100.1:443
730
731     <VirtualHost _default_:443>
732         GnuTLSEnable on
733         GnuTLSSessionTickets on
734         DocumentRoot /www/site1.example.com/html
735         ServerName site1.example.com:443
736         GnuTLSCertificateFile conf/tls/site1.crt
737         GnuTLSKeyFile conf/tls/site1.key
[2b16350]738     </VirtualHost>
[4ee45a1]739
[fc124e9]740     <VirtualHost _default_:443>
741         GnuTLSEnable on
742         DocumentRoot /www/site2.example.com/html
743         ServerName site2.example.com:443
744         GnuTLSCertificateFile conf/tls/site2.crt
745         GnuTLSKeyFile conf/tls/site2.key
746     </VirtualHost>
[4ee45a1]747
[fc124e9]748     <VirtualHost _default_:443>
749         GnuTLSEnable on
750         DocumentRoot /www/site3.example.com/html
751         ServerName site3.example.com:443
752         GnuTLSCertificateFile conf/tls/site3.crt
753         GnuTLSKeyFile conf/tls/site3.key
754     </VirtualHost>
[4ee45a1]755
[fc124e9]756     <VirtualHost _default_:443>
757         GnuTLSEnable on
758         DocumentRoot /www/site4.example.com/html
759         ServerName site4.example.com:443
760         GnuTLSCertificateFile conf/tls/site4.crt
761         GnuTLSKeyFile conf/tls/site4.key
762     </VirtualHost>
[2b16350]763
[fc124e9]764OCSP Stapling Example
765---------------------
[2b16350]766
[fc124e9]767This example uses an X.509 server certificate. The server will fetch
768OCSP responses from the responder listed in the certificate and store
769them im a memcached cache shared with another server.
[2b16350]770
771     # Load the module into Apache.
772     LoadModule gnutls_module modules/mod_gnutls.so
[7105869]773     GnuTLSCache memcache:192.0.2.1:11211,192.0.2.2:11211
[2b16350]774     GnuTLSCacheTimeout 600
[fc124e9]775
776     Listen 192.0.2.1:443
777
778     <VirtualHost _default_:443>
779         GnuTLSEnable          On
780         DocumentRoot          /www/site1.example.com/html
781         ServerName            site1.example.com:443
782         GnuTLSCertificateFile conf/tls/site1.crt
783         GnuTLSKeyFile         conf/tls/site1.key
784         GnuTLSOCSPStapling    On
[2b16350]785     </VirtualHost>
[4ee45a1]786
787* * * * *
788
[2b16350]789Environment Variables
790=====================
[4ee45a1]791
[2b16350]792`mod_gnutls` exports the following environment variables to scripts.
793These are compatible with `mod_ssl`.
[4ee45a1]794
[2b16350]795`HTTPS`
796-------
[4ee45a1]797
[2b16350]798Can be `on` or `off`
[4ee45a1]799
[2b16350]800`SSL_VERSION_LIBRARY`
801---------------------
[4ee45a1]802
[2b16350]803The version of the GnuTLS library
[4ee45a1]804
[2b16350]805`SSL_VERSION_INTERFACE`
806-----------------------
[4ee45a1]807
808The version of this module
809
[2b16350]810`SSL_PROTOCOL`
811--------------
[4ee45a1]812
[2b16350]813The SSL or TLS protocol name (such as `TLS 1.0` etc.)
[4ee45a1]814
[2b16350]815`SSL_CIPHER`
816------------
[4ee45a1]817
818The SSL or TLS cipher suite name
819
[2b16350]820`SSL_COMPRESS_METHOD`
821---------------------
[4ee45a1]822
[2b16350]823The negotiated compression method (`NULL` or `DEFLATE`)
[4ee45a1]824
[2b16350]825`SSL_SRP_USER`
826--------------
[4ee45a1]827
828The SRP username used for authentication (only set when
[2b16350]829`GnuTLSSRPPasswdFile` and `GnuTLSSRPPasswdConfFile` are configured).
[4ee45a1]830
[2b16350]831`SSL_CIPHER_USEKEYSIZE` & `SSL_CIPHER_ALGKEYSIZE`
832-------------------------------------------------
[4ee45a1]833
834The number if bits used in the used cipher algorithm.
835
836This does not fully reflect the security level since the size of
837RSA or DHE key exchange parameters affect the security level too.
838
[5674676]839`SSL_DH_PRIME_BITS`
840-------------------
841
842The number if bits in the modulus for the DH group, if DHE or static
843DH is used.
844
845This will not be set if DH is not used.
846
[2b16350]847`SSL_CIPHER_EXPORT`
848-------------------
[4ee45a1]849
[2b16350]850`True` or `False`. Whether the cipher suite negotiated is an export one.
[4ee45a1]851
[2b16350]852`SSL_SESSION_ID`
853----------------
[4ee45a1]854
855The session ID negotiated in this session. Can be the same during client
856reloads.
857
[2b16350]858`SSL_CLIENT_V_REMAIN`
859---------------------
[4ee45a1]860
861The number of days until the client's certificate is expired.
862
[2b16350]863`SSL_CLIENT_V_START`
864--------------------
[4ee45a1]865
866The activation time of client's certificate.
867
[2b16350]868`SSL_CLIENT_V_END`
869------------------
[4ee45a1]870
871The expiration time of client's certificate.
872
[2b16350]873`SSL_CLIENT_S_DN`
874-----------------
[4ee45a1]875
876The distinguished name of client's certificate in RFC2253 format.
877
[2b16350]878`SSL_CLIENT_I_DN`
879-----------------
[4ee45a1]880
[732c5733]881The distinguished name of the issuer of the client's certificate in
882RFC2253 format.
[4ee45a1]883
[2b16350]884`SSL_CLIENT_S_AN%`
885------------------
[4ee45a1]886
[2b16350]887These will contain the alternative names of the client certificate (`%` is
[4ee45a1]888a number starting from zero).
889
[2b16350]890The values will be prepended by `DNSNAME:`, `RFC822NAME:` or `URI:`
[4ee45a1]891depending on the type.
892
[2b16350]893If it is not supported the value `UNSUPPORTED` will be set.
[4ee45a1]894
[2b16350]895`SSL_SERVER_M_SERIAL`
896---------------------
[4ee45a1]897
898The serial number of the server's certificate.
899
[2b16350]900`SSL_SERVER_M_VERSION`
901----------------------
[4ee45a1]902
903The version of the server's certificate.
904
[2b16350]905`SSL_SERVER_A_SIG`
906------------------
[4ee45a1]907
908The algorithm used for the signature in server's certificate.
909
[2b16350]910`SSL_SERVER_A_KEY`
911------------------
[4ee45a1]912
913The public key algorithm in server's certificate.
914
[999cdec]915`SSL_SERVER_CERT`
[2b16350]916------------------
[4ee45a1]917
[e796121]918The PEM-encoded (X.509) server certificate (see the
919`GnuTLSExportCertificates` directive).
[4ee45a1]920
[2b16350]921`SSL_SERVER_CERT_TYPE`
922----------------------
[4ee45a1]923
[e796121]924The certificate type will be `X.509`.
[ac32bb5]925
[999cdec]926`SSL_CLIENT_CERT`
927------------------
928
[e796121]929PEM-encoded (X.509) client certificate, if any (see the
930`GnuTLSExportCertificates` directive).
[999cdec]931
[ac32bb5]932`SSL_CLIENT_CERT_TYPE`
933----------------------
934
[e796121]935The certificate type will be `X.509`, if any.
Note: See TracBrowser for help on using the repository browser.