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