source: mod_gnutls/docs/mod_gnutls_manual-0.1.html @ bb24ee8

debian/masterdebian/stretch-backportsjessie-backportsmsvaupstream
Last change on this file since bb24ee8 was bb24ee8, checked in by Dash Shendy <neuromancer@…>, 8 years ago

Added PDF & HTML Manuals

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