source: mod_gnutls/doc/mod_gnutls_manual.mdwn @ 27ca1e9

asyncioproxy-ticket
Last change on this file since 27ca1e9 was 27ca1e9, checked in by Fiona Klute <fiona.klute@…>, 21 months ago

Manual: Use YAML metadata instead of embedded title for all formats

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