source: mod_gnutls/docs/mod_gnutls_manual.mdwn @ e7527b9

asynciodebian/masterdebian/stretch-backportsjessie-backportsproxy-ticketupstream
Last change on this file since e7527b9 was e7527b9, checked in by Daniel Kahn Gillmor <dkg@…>, 8 years ago

automate generation of other manual formats.

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