source: mod_gnutls/docs/mod_gnutls_manual.mdwn @ fa45dcb

debian/masterdebian/stretch-backportsjessie-backportsproxy-ticketupstream
Last change on this file since fa45dcb was 2b16350, checked in by Daniel Kahn Gillmor <dkg@…>, 7 years ago

clean up documentation, list GnuTLSEnable as the first option

  • Property mode set to 100644
File size: 19.6 KB
Line 
1% `mod_gnutls` Manual
2
3* * * * *
4
5`mod_gnutls` is a module for the Apache web server that provides
6HTTPS (HTTP over Transport Layer Security (TLS) or the older Secure
7Sockets Layer (SSL)) using the GnuTLS library.
8
9* * * * *
10
11Compilation & Installation
12==========================
13
14`mod_gnutls` uses the `./configure && make && make install` mechanism
15common to many Open Source programs.  Most of the dirty work is
16handled by either `./configure` or Apache's `apxs` utility. If you have
17built Apache modules before, there shouldn't be any surprises for you.
18
19The interesting options you can pass to configure are:
20
21`--with-apxs=PATH`
22:   This option is used to specify the location of the apxs utility that
23    was installed as part of apache. Specify the location of the
24    binary, not the directory it is located in.
25
26`--with-libgnutls=PATH`
27:   Full path to the libgnutls-config program.
28
29`--with-apr-memcache=PREFIX`
30:   Prefix to where apr\_memcache is installed.
31
32`--help`
33:   Provides a list of all available configure options.
34
35* * * * *
36
37Integration
38===========
39
40To activate `mod_gnutls` just add the following line to your httpd.conf
41and restart Apache:
42
43    LoadModule gnutls_module modules/mod_gnutls.so
44
45* * * * *
46
47Configuration Directives
48========================
49
50`GnuTLSEnable`
51--------------
52
53Enable GnuTLS for this virtual host
54
55    GnuTLSEnable [on|off]
56
57Default: *off*\
58Context: virtual host
59
60This directive enables SSL/TLS Encryption for a Virtual Host.
61
62`GnuTLSCache`
63-------------
64
65Configure SSL Session Cache
66
67    GnuTLSCache [dbm|gdbm|memcache|none] [PATH|SERVERLIST|-]
68
69Default: `GnuTLSCache none`\
70Context: server config
71
72This directive configures the SSL Session Cache for `mod_gnutls`.
73This could be shared between machines of different architectures.
74
75`dbm` (Requires Berkeley DBM)
76:   Uses the default Berkeley DB backend of APR DBM to cache SSL
77    Sessions results.  The argument is a relative or absolute path to
78    be used as the DBM Cache file. This is compatible with most
79    operating systems, but needs the Apache Runtime to be compiled
80    with Berkeley DBM support.
81
82`gdbm`
83:   Uses the GDBM backend of APR DBM to cache SSL Sessions results.
84
85    The argument is a relative or absolute path to be used as the DBM Cache
86    file.  This is the recommended option.
87
88`memcache`
89:   Uses a memcached server to cache the SSL Session.
90
91    The argument is a space separated list of servers. If no port
92    number is supplied, the default of 11211 is used.  This can be
93    used to share a session cache between all servers in a cluster.
94
95`none`
96:   Turns off all caching of SSL Sessions.
97
98    This can significantly reduce the performance of `mod_gnutls` since
99    even followup connections by a client must renegotiate parameters
100    instead of reusing old ones.  This is the default, since it
101    requires no configuration.
102
103`GnuTLSCacheTimeout`
104--------------------
105
106Timeout for SSL Session Cache expiration
107
108    GnuTLSCacheTimeout SECONDS
109
110Default: `GnuTLSCacheTimeout 300`\
111Context: server config
112
113Sets the timeout for SSL Session Cache entries expiration.  This
114directive is valid even if Session Tickets are used, and indicates the
115expiration time of the ticket in seconds.
116
117`GnuTLSSessionTickets`
118----------------------
119
120Enable Session Tickets for the server
121
122    GnuTLSSessionTickets [on|off]
123
124Default: `off`\
125Context: server config, virtual host
126
127To avoid storing data for TLS session resumption it is allowed to
128provide client with a ticket, to use on return.  Use for servers with
129limited storage, and don't combine with GnuTLSCache. For a pool of
130servers this option is not recommended since the tickets are unique
131for the issuing server only.
132
133
134`GnuTLSCertificateFile`
135-----------------------
136
137Set to the PEM Encoded Server Certificate
138
139    GnuTLSCertificateFile FILEPATH
140
141Default: *none*\
142Context: server config, virtual host
143
144Takes an absolute or relative path to a PEM-encoded X.509 certificate to
145use as this Server's End Entity (EE) certificate. If you need to supply
146certificates for intermediate Certificate Authorities (iCAs), they
147should be listed in sequence in the file, from EE to the iCA closest to
148the root CA. Optionally, you can also include the root CA's certificate
149as the last certificate in the list.
150
151`GnuTLSKeyFile`
152---------------
153
154Set to the PEM Encoded Server Certificate
155
156    GnuTLSCertificateFile FILEPATH
157
158Default: *none*\
159Context: server config, virtual host
160
161Takes an absolute or relative path to the Server Private Key.  This
162key cannot currently be password protected.
163
164**Security Warning:**\
165 This private key must be protected. It is read while Apache is still
166running as root, and does not need to be readable by the nobody or
167apache user.
168
169`GnuTLSPGPCertificateFile`
170--------------------------
171
172Set to a base64 Encoded Server OpenPGP Certificate
173
174    GnuTLSPGPCertificateFile FILEPATH
175
176Default: *none*\
177Context: server config, virtual host
178
179Takes an absolute or relative path to a base64 Encoded OpenPGP
180Certificate to use as this Server's Certificate.
181
182`GnuTLSPGPKeyFile`
183------------------
184
185Set to the Server OpenPGP Secret Key
186
187    GnuTLSPGPKeyFile FILEPATH
188
189Default: *none*\
190Context: server config, virtual host
191
192Takes an absolute or relative path to the Server Private Key. This key
193cannot currently be password protected.
194
195**Security Warning:**\
196 This private key must be protected. It is read while Apache is still
197running as root, and does not need to be readable by the nobody or
198apache user.
199
200`GnuTLSClientVerify`
201--------------------
202
203Enable Client Certificate Verification\
204
205    GnuTLSClientVerify [ignore|request|require]
206
207Default: `ignore`\
208Context: server config, virtual host, directory, .htaccess
209
210This directive controls the use of SSL Client Certificate
211Authentication. If used in the .htaccess context, it can force TLS
212re-negotiation.
213
214`ignore`
215:   `mod_gnutls` will ignore the contents of any SSL Client Certificates
216    sent. It will not request that the client sends a certificate.
217
218`request`
219:   The client certificate will be requested, but not required.
220    The Certificate will be validated if sent.  The output of the
221    validation status will be stored in the `SSL_CLIENT_VERIFY`
222    environment variable and can be `SUCCESS`, `FAILED` or `NONE`.
223
224`require`
225:   A Client certificate will be required. Any requests without a valid
226    client certificate will be denied.  The `SSL_CLIENT_VERIFY`
227    environment variable will only be set to `SUCCESS`.
228
229`GnuTLSClientCAFile`
230--------------------
231
232Set to the PEM Encoded Certificate Authority Certificate
233
234    GnuTLSClientCAFile FILEPATH
235
236Default: *none*
237Context: server config, virtual host
238
239Takes an absolute or relative path to a PEM Encoded Certificate to use
240as a Certificate Authority with Client Certificate Authentication.
241This file may contain a list of trusted authorities.
242
243`GnuTLSPGPKeyringFile`
244----------------------
245
246Set to a base64 Encoded key ring
247
248    GnuTLSPGPKeyringFile FILEPATH
249
250Default: *none*\
251Context: server config, virtual host
252
253Takes an absolute or relative path to a base64 Encoded Certificate
254list (key ring) to use as a means of verification of Client
255Certificates.  This file should contain a list of trusted signers.
256
257`GnuTLSDHFile`
258--------------
259
260Set to the PKCS \#3 encoded Diffie Hellman parameters
261
262    GnuTLSDHFile FILEPATH
263
264Default: *none*\
265Context: server config, virtual host
266
267Takes an absolute or relative path to a PKCS \#3 encoded DH
268parameters.Those are used when the DHE key exchange method is enabled.
269You can generate this file using `certtool --generate-dh-params --bits
2702048`.  If not set `mod_gnutls` will use the included parameters.
271
272`GnuTLSSRPPasswdFile`
273---------------------
274
275Set to the SRP password file for SRP ciphersuites
276
277    GnuTLSSRPPasswdFile FILEPATH
278
279Default: *none*\
280Context: server config, virtual host
281
282Takes an absolute or relative path to an SRP password file. This is
283the same format as used in libsrp.  You can generate such file using
284the command `srptool --passwd /etc/tpasswd --passwd-conf
285/etc/tpasswd.conf -u test` to set a password for user test.  This
286password file holds the username, a password verifier and the
287dependency to the SRP parameters.
288
289`GnuTLSSRPPasswdConfFile`
290-------------------------
291
292Set to the SRP password.conf file for SRP ciphersuites
293
294    GnuTLSSRPPasswdConfFile FILEPATH
295
296Default: *none*\
297Context: server config, virtual host
298
299Takes an absolute or relative path to an SRP password.conf file. This
300is the same format as used in `libsrp`.  You can generate such file
301using the command `srptool --create-conf /etc/tpasswd.conf`.  This
302file holds the SRP parameters and is associate with the password file
303(the verifiers depends on these parameters).
304
305`GnuTLSPriorities`
306------------------
307
308Set the allowed ciphers, key exchange algorithms, MACs and compression
309methods
310
311    GnuTLSPriorities +CIPHER_0:+CIPHER_1:...:+CIPHER_N
312
313Default: *none*\
314Context: server config, virtual host
315
316Takes a semi-colon separated list of ciphers, key exchange methods
317Message authentication codes and compression methods to enable.
318The allowed keywords are specified in the `gnutls_priority_init()`
319function of GnuTLS.
320
321Its documentation can be found at [Core GnuTLS functions](http://www.gnu.org/software/gnutls/manual/html_node/Core-functions.html#Core-functions).
322In brief you can specify a set of ciphersuites from the choices:
323
324`NONE`
325:   The empty list.
326
327`EXPORT`
328:   A list with all the supported cipher combinations
329    including the `EXPORT` strength algorithms.
330
331`PERFORMANCE`
332:   A list with all the secure cipher combinations sorted in terms of performance.
333
334`NORMAL`
335:   A list with all the secure cipher combinations sorted
336    with respect to security margin (subjective term).
337
338`SECURE`
339:   A list with all the secure cipher combinations including
340    the 256-bit ciphers sorted with respect to security margin.
341
342Additionally you can add or remove algorithms using the `+` and `!`
343prefixes respectively.
344
345For example, in order to disable the `ARCFOUR` cipher from the `NORMAL` set
346you can use the string `NORMAL:!ARCFOUR-128`
347
348Other options such as the protocol version and the compression method
349can be specified using the `VERS-` and `COMP-` prefixes.
350
351So in order to remove or add a specific TLS version from the `NORMAL`
352set, use `NORMAL:!VERS-SSL3.0`.  And to enable zlib compression use
353`NORMAL:+COMP-DEFLATE`.
354
355
356However it is recommended not to add compression at this level.  With
357the `NONE` set, in order to be usable, you have to specify a complete
358set of combinations of protocol versions, cipher algorithms
359(`AES-128-CBC`), key exchange algorithms (`RSA`), message
360authentication codes (`SHA1`) and compression methods (`COMP-NULL`).
361
362You can find a list of all supported Ciphers, Versions, MACs, etc.  by
363running `gnutls-cli --list`.
364
365The special keyword `%COMPAT` will disable some security features such
366as protection against statistical attacks to ciphertext data in order to
367achieve maximum compatibility (some broken mobile clients need this).
368
369`GnuTLSExportCertificates`
370--------------------------
371
372Export the PEM encoded certificates to CGIs
373
374    GnuTLSExportCertificates [on|off]
375
376Default: `off`\
377Context: server config, virtual host
378
379This directive enables exporting the full certificates of the server and
380the client to CGI scripts. The exported certificates will be PEM-encoded
381(if X.509) or ASCII-armored (if OpenPGP).
382With GnuTLSExportCertificates enabled, `mod_gnutls` exports the same
383environment variables to the CGI process as `mod_ssl`.
384
385* * * * *
386
387Configuration Examples
388======================
389
390Simple Standard SSL Example
391---------------------------
392
393The following is an example of standard SSL Hosting, using one IP
394Addresses for each virtual host
395
396     # Load the module into Apache.
397     LoadModule gnutls_module modules/mod_gnutls.so
398     GnuTLSCache gdbm /var/cache/www-tls-cache
399     GnuTLSCacheTimeout 500
400     # With normal SSL Websites, you need one IP Address per-site.
401     Listen 1.2.3.1:443
402     Listen 1.2.3.2:443
403     Listen 1.2.3.3:443
404     Listen 1.2.3.4:443
405     <VirtualHost 1.2.3.1:443>
406     GnuTLSEnable on
407     GnuTLSPriorities NONE:+AES-128-CBC:+3DES-CBC:+ARCFOUR-128:+RSA:+DHE-RSA:+DHE-DSS:+SHA1:+MD5:+COMP-NULL
408     DocumentRoot /www/site1.example.com/html
409     ServerName site1.example.com:443
410     GnuTLSCertificateFile conf/ssl/site1.crt
411     GnuTLSKeyFile conf/ss/site1.key
412     </VirtualHost>
413     <VirtualHost 1.2.3.2:443>
414     # This virtual host enables SRP authentication
415     GnuTLSEnable on
416     GnuTLSPriorities NORMAL:+SRP
417     DocumentRoot /www/site2.example.com/html
418     ServerName site2.example.com:443
419     GnuTLSSRPPasswdFile conf/ssl/tpasswd.site2
420     GnuTLSSRPPasswdConfFile conf/ssl/tpasswd.site2.conf
421     </VirtualHost>
422     <VirtualHost 1.2.3.3:443>
423     # This server enables SRP, OpenPGP and X.509 authentication.
424     GnuTLSEnable on
425     GnuTLSPriorities NORMAL:+SRP:+SRP-RSA:+SRP-DSS
426     DocumentRoot /www/site3.example.com/html
427     ServerName site3.example.com:443
428     GnuTLSCertificateFile conf/ssl/site3.crt
429     GnuTLSKeyFile conf/ss/site3.key
430     GnuTLSClientVerify ignore
431     GnuTLSPGPCertificateFile conf/ss/site3.pub.asc
432     GnuTLSPGPKeyFile conf/ss/site3.sec.asc
433     GnuTLSSRPPasswdFile conf/ssl/tpasswd.site3
434     GnuTLSSRPPasswdConfFile conf/ssl/tpasswd.site3.conf
435     </VirtualHost>
436     <VirtualHost 1.2.3.4:443>
437     GnuTLSEnable on
438     # %COMPAT disables some security features to enable maximum compatibility with clients.
439     GnuTLSPriorities NONE:+AES-128-CBC:+ARCFOUR-128:+RSA:+SHA1:+MD5:+COMP-NULL:%COMPAT
440     DocumentRoot /www/site4.example.com/html
441     ServerName site4.example.com:443
442     GnuTLSCertificateFile conf/ssl/site4.crt
443     GnuTLSKeyFile conf/ss/site4.key
444     </VirtualHost>
445
446Server Name Indication Example
447------------------------------
448
449`mod_gnutls` can also use "Server Name Indication", as specified in
450RFC 3546.  This allows hosting many SSL Websites, with a Single IP
451Address.  Currently all the recent browsers support this
452standard. Here is an example, using SNI: ` `
453
454
455     # Load the module into Apache.
456     LoadModule gnutls_module modules/mod_gnutls.so
457     # With normal SSL Websites, you need one IP Address per-site.
458     Listen 1.2.3.1:443
459     # This could also be 'Listen *:443',
460     # just like '*:80' is common for non-https
461     # No caching. Enable session tickets. Timeout is still used for
462     # ticket expiration.
463     GnuTLSCacheTimeout 600
464     # This tells apache, that for this IP/Port combination, we want to use
465     # Name Based Virtual Hosting. In the case of Server Name Indication,
466     # it lets mod_gnutls pick the correct Server Certificate.
467     NameVirtualHost 1.2.3.1:443
468     <VirtualHost 1.2.3.1:443>
469     GnuTLSEnable on
470     GnuTLSSessionTickets on
471     GnuTLSPriorities NORMAL
472     DocumentRoot /www/site1.example.com/html
473     ServerName site1.example.com:443
474     GnuTLSCertificateFile conf/ssl/site1.crt
475     GnuTLSKeyFile conf/ss/site1.key
476     </VirtualHost>
477     <VirtualHost 1.2.3.1:443>
478     GnuTLSEnable on
479     GnuTLSPriorities NORMAL
480     DocumentRoot /www/site2.example.com/html
481     ServerName site2.example.com:443
482     GnuTLSCertificateFile conf/ssl/site2.crt
483     GnuTLSKeyFile conf/ss/site2.key
484     </VirtualHost>
485     <VirtualHost 1.2.3.1:443>
486     GnuTLSEnable on
487     GnuTLSPriorities NORMAL
488     DocumentRoot /www/site3.example.com/html
489     ServerName site3.example.com:443
490     GnuTLSCertificateFile conf/ssl/site3.crt
491     GnuTLSKeyFile conf/ss/site3.key
492     </VirtualHost>
493     <VirtualHost 1.2.3.1:443>
494     GnuTLSEnable on
495     GnuTLSPriorities NORMAL
496     DocumentRoot /www/site4.example.com/html
497     ServerName site4.example.com:443
498     GnuTLSCertificateFile conf/ssl/site4.crt
499     GnuTLSKeyFile conf/ss/site4.key
500     </VirtualHost>
501
502
503* * * * *
504
505Performance Issues
506==================
507
508`mod_gnutls` by default uses conservative settings for the server.
509You can fine tune the configuration to reduce the load on a busy
510server.  The following examples do exactly this:
511
512
513     # Load the module into Apache.
514     LoadModule gnutls_module modules/mod_gnutls.so
515     # Using 4 memcache servers to distribute the SSL Session Cache.
516     GnuTLSCache memcache "mc1.example.com mc2.example.com mc3.example.com mc4.example.com"
517     GnuTLSCacheTimeout 600
518     Listen 1.2.3.1:443
519     NameVirtualHost 1.2.3.1:443
520     <VirtualHost 1.2.3.1:443>
521     GnuTLSEnable on
522     # Here we disable the Perfect forward secrecy ciphersuites (DHE)
523     # and disallow AES-256 since AES-128 is just fine.
524     GnuTLSPriorities NORMAL:!DHE-RSA:!DHE-DSS:!AES-256-CBC:%COMPAT
525     DocumentRoot /www/site1.example.com/html
526     ServerName site1.example.com:443
527     GnuTLSCertificateFile conf/ssl/site1.crt
528     GnuTLSKeyFile conf/ss/site1.key
529     </VirtualHost>
530     <VirtualHost 1.2.3.1:443>
531     GnuTLSEnable on
532     # Here we instead of disabling the DHE ciphersuites we use
533     # Diffie Hellman parameters of smaller size than the default (2048 bits).
534     # Using small numbers from 768 to 1024 bits should be ok once they are
535     # regenerated every few hours.
536     # Use "certtool --generate-dh-params --bits 1024" to get those
537     GnuTLSDHFile /etc/apache2/dh.params
538     GnuTLSPriorities NORMAL:!AES-256-CBC:%COMPAT
539     DocumentRoot /www/site2.example.com/html
540     ServerName site2.example.com:443
541     GnuTLSCertificateFile conf/ssl/site2.crt
542     GnuTLSKeyFile conf/ss/site2.key
543     </VirtualHost>
544
545* * * * *
546
547Environment Variables
548=====================
549
550`mod_gnutls` exports the following environment variables to scripts.
551These are compatible with `mod_ssl`.
552
553`HTTPS`
554-------
555
556Can be `on` or `off`
557
558`SSL_VERSION_LIBRARY`
559---------------------
560
561The version of the GnuTLS library
562
563`SSL_VERSION_INTERFACE`
564-----------------------
565
566The version of this module
567
568`SSL_PROTOCOL`
569--------------
570
571The SSL or TLS protocol name (such as `TLS 1.0` etc.)
572
573`SSL_CIPHER`
574------------
575
576The SSL or TLS cipher suite name
577
578`SSL_COMPRESS_METHOD`
579---------------------
580
581The negotiated compression method (`NULL` or `DEFLATE`)
582
583`SSL_SRP_USER`
584--------------
585
586The SRP username used for authentication (only set when
587`GnuTLSSRPPasswdFile` and `GnuTLSSRPPasswdConfFile` are configured).
588
589`SSL_CIPHER_USEKEYSIZE` & `SSL_CIPHER_ALGKEYSIZE`
590-------------------------------------------------
591
592The number if bits used in the used cipher algorithm.
593
594This does not fully reflect the security level since the size of
595RSA or DHE key exchange parameters affect the security level too.
596
597`SSL_CIPHER_EXPORT`
598-------------------
599
600`True` or `False`. Whether the cipher suite negotiated is an export one.
601
602`SSL_SESSION_ID`
603----------------
604
605The session ID negotiated in this session. Can be the same during client
606reloads.
607
608`SSL_CLIENT_V_REMAIN`
609---------------------
610
611The number of days until the client's certificate is expired.
612
613`SSL_CLIENT_V_START`
614--------------------
615
616The activation time of client's certificate.
617
618`SSL_CLIENT_V_END`
619------------------
620
621The expiration time of client's certificate.
622
623`SSL_CLIENT_S_DN`
624-----------------
625
626The distinguished name of client's certificate in RFC2253 format.
627
628`SSL_CLIENT_I_DN`
629-----------------
630
631The SSL or TLS cipher suite name
632
633`SSL_CLIENT_S_AN%`
634------------------
635
636These will contain the alternative names of the client certificate (`%` is
637a number starting from zero).
638
639The values will be prepended by `DNSNAME:`, `RFC822NAME:` or `URI:`
640depending on the type.
641
642If it is not supported the value `UNSUPPORTED` will be set.
643
644`SSL_SERVER_M_SERIAL`
645---------------------
646
647The serial number of the server's certificate.
648
649`SSL_SERVER_M_VERSION`
650----------------------
651
652The version of the server's certificate.
653
654`SSL_SERVER_A_SIG`
655------------------
656
657The algorithm used for the signature in server's certificate.
658
659`SSL_SERVER_A_KEY`
660------------------
661
662The public key algorithm in server's certificate.
663
664`SSL_SERVER1_CERT`
665------------------
666
667The PEM-encoded server certificate.
668
669`SSL_SERVER_CERT_TYPE`
670----------------------
671
672The certificate type can be `X.509` or `OPENPGP`.
Note: See TracBrowser for help on using the repository browser.