source: mod_gnutls/doc/mod_gnutls_manual.mdwn @ e796121

debian/master
Last change on this file since e796121 was e796121, checked in by Fiona Klute <fiona.klute@…>, 14 months ago

Remove documentation on OpenPGP authentication

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