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 & 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> |
---|
91 | GnuTLSCache [<i>dbm</i>|<i>gdbm</i>|<i>memcache</i>|<i>none</i>] [path|server list|-]<br /> |
---|
92 | <h5>Default:</h5> |
---|
93 | GnuTLSCache none<br /> |
---|
94 | <h5>Context:</h5> |
---|
95 | server 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 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 |
---|
115 | mod_gnutls since even followup connections by a client |
---|
116 | must renegotiate parameters instead of reusing old |
---|
117 | ones.<br /> |
---|
118 | This is the default, since it requires no configuration.<br /> |
---|
119 | </p> |
---|
120 | <h4>GnuTLSCacheTimeout</h4> |
---|
121 | <div class="directive"> |
---|
122 | <h5>Description:</h5>Timeout for SSL Session Cache expiration<br /> |
---|
123 | <h5>Syntax:</h5> |
---|
124 | GnuTLSCacheTimeout <i>seconds</i><br /> |
---|
125 | <h5>Default:</h5> |
---|
126 | GnuTLSCacheTimeout 300<br /> |
---|
127 | <h5>Context:</h5> |
---|
128 | server config<br /> |
---|
129 | </div> |
---|
130 | <p>Sets the timeout for SSL Session Cache entries expiration.<br /> |
---|
131 | This directive is valid even if Session Tickets are used, and indicates the expiration time of the ticket in seconds.</p> |
---|
132 | <h4>GnuTLSSessionTickets</h4> |
---|
133 | <div class="directive"> |
---|
134 | <h5>Description:</h5>Enable Session Tickets for the server<br /> |
---|
135 | <h5>Syntax:</h5> |
---|
136 | GnuTLSSessionTickets [ <i>on</i> | <i>off</i> ]<br /> |
---|
137 | <h5>Default:</h5> |
---|
138 | <i>off</i><br /> |
---|
139 | <h5>Context:</h5> |
---|
140 | server config, virtual host<br /> |
---|
141 | </div> |
---|
142 | <p>To avoid storing data for TLS session resumption it is allowed to provide client with a ticket, to use on return.<br /> |
---|
143 | Use for servers with limited storage, and don't combine with GnuTLSCache.<br /> |
---|
144 | For a pool of servers this option is not recommended since the tickets are unique for the issuing server only.</p> |
---|
145 | <h4>GnuTLSCertificateFile</h4> |
---|
146 | <div class="directive"> |
---|
147 | <h5>Description:</h5>Set to the PEM Encoded Server Certificate<br /> |
---|
148 | <h5>Syntax:</h5> |
---|
149 | GnuTLSCertificateFile <i>file-path</i><br /> |
---|
150 | <h5>Default:</h5> |
---|
151 | <i>none</i><br /> |
---|
152 | <h5>Context:</h5> |
---|
153 | server config, virtual host<br /> |
---|
154 | </div> |
---|
155 | <p>Takes an absolute or relative path to a PEM-encoded |
---|
156 | X.509 certificate to use as this Server's End Entity (EE) |
---|
157 | certificate. If you need to supply certificates for |
---|
158 | intermediate Certificate Authorities (iCAs), they should |
---|
159 | be listed in sequence in the file, from EE to the iCA |
---|
160 | closest to the root CA. Optionally, you can also include |
---|
161 | the root CA's certificate as the last certificate in the |
---|
162 | list.</p> |
---|
163 | <h4>GnuTLSKeyFile</h4> |
---|
164 | <div class="directive"> |
---|
165 | <h5>Description:</h5>Set to the PEM Encoded Server Certificate<br /> |
---|
166 | <h5>Syntax:</h5> |
---|
167 | GnuTLSCertificateFile <i>file-path</i><br /> |
---|
168 | <h5>Default:</h5> |
---|
169 | <i>none</i><br /> |
---|
170 | <h5>Context:</h5> |
---|
171 | server config, virtual host<br /> |
---|
172 | </div> |
---|
173 | <p>Takes an absolute or relative path to the Server Private Key.<br /> |
---|
174 | This key cannot currently be password protected.</p> |
---|
175 | <p class="warn"> |
---|
176 | <b>Security Warning:</b><br /> |
---|
177 | 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. |
---|
178 | </p> |
---|
179 | <h4>GnuTLSPGPCertificateFile</h4> |
---|
180 | <div class="directive"> |
---|
181 | <h5>Description:</h5>Set to a base64 Encoded Server OpenPGP Certificate<br /> |
---|
182 | <h5>Syntax:</h5> |
---|
183 | GnuTLSPGPCertificateFile <i>file-path</i><br /> |
---|
184 | <h5>Default:</h5> |
---|
185 | <i>none</i><br /> |
---|
186 | <h5>Context:</h5> |
---|
187 | server config, virtual host<br /> |
---|
188 | </div> |
---|
189 | <p>Takes an absolute or relative path to a base64 Encoded OpenPGP Certificate to use as this Server's Certificate.</p> |
---|
190 | <h4>GnuTLSPGPKeyFile</h4> |
---|
191 | <div class="directive"> |
---|
192 | <h5>Description:</h5>Set to the Server OpenPGP Secret Key<br /> |
---|
193 | <h5>Syntax:</h5> |
---|
194 | GnuTLSPGPKeyFile <i>file-path</i><br /> |
---|
195 | <h5>Default:</h5> |
---|
196 | <i>none</i><br /> |
---|
197 | <h5>Context:</h5> |
---|
198 | server config, virtual host<br /> |
---|
199 | </div> |
---|
200 | <p>Takes an absolute or relative path to the Server Private Key. This key cannot currently be password protected.</p> |
---|
201 | <p class="warn"> |
---|
202 | <b>Security Warning:</b><br /> |
---|
203 | 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. |
---|
204 | </p> |
---|
205 | <h4>GnuTLSClientVerify</h4> |
---|
206 | <div class="directive"> |
---|
207 | <h5>Description:</h5>Enable Client Certificate Verification<br /> |
---|
208 | <h5>Syntax:</h5> |
---|
209 | GnuTLSClientVerify [ <i>ignore</i> | <i>request</i> | <i>require</i> ]<br /> |
---|
210 | <h5>Default:</h5> |
---|
211 | <i>ignore</i><br /> |
---|
212 | <h5>Context:</h5> |
---|
213 | server config, virtual host, directory, .htaccess<br /> |
---|
214 | </div> |
---|
215 | <p>This directive controls the use of SSL Client Certificate Authentication.<br /> |
---|
216 | If used in the .htaccess context, it can force TLS re-negotiation.</p> |
---|
217 | <p> |
---|
218 | <b>ignore</b><br /> |
---|
219 | mod_gnutls will ignore the contents of any SSL Client Certificates sent.<br /> |
---|
220 | It will not request that the client sends a certificate.<br /> |
---|
221 | <b>request</b><br /> |
---|
222 | The client certificate will be requested, but not required.<br /> |
---|
223 | The Certificate will be validated if sent.<br /> |
---|
224 | The output of the validation status will be stored in the SSL_CLIENT_VERIFY environment variable and can be "SUCCESS", "FAILED" or "NONE".<br /> |
---|
225 | <b>require</b><br /> |
---|
226 | A Client certificate will be required. Any requests without a valid client certificate will be denied.<br /> |
---|
227 | The SSL_CLIENT_VERIFY environment variable will only be set to "SUCCESS". |
---|
228 | </p> |
---|
229 | <h4>GnuTLSClientCAFile</h4> |
---|
230 | <div class="directive"> |
---|
231 | <h5>Description:</h5>Set to the PEM Encoded Certificate Authority Certificate<br /> |
---|
232 | <h5>Syntax:</h5> |
---|
233 | GnuTLSClientCAFile <i>file-path</i><br /> |
---|
234 | <h5>Default:</h5> |
---|
235 | <i>none</i><br /> |
---|
236 | <h5>Context:</h5> |
---|
237 | server config, virtual host<br /> |
---|
238 | </div> |
---|
239 | <p> |
---|
240 | Takes an absolute or relative path to a PEM Encoded Certificate to use as a Certificate Authority with Client Certificate Authentication.<br /> |
---|
241 | This file may contain a list of trusted authorities.<br /> |
---|
242 | </p> |
---|
243 | <h4>GnuTLSPGPKeyringFile</h4> |
---|
244 | <div class="directive"> |
---|
245 | <h5>Description:</h5>Set to a base64 Encoded key ring<br /> |
---|
246 | <h5>Syntax:</h5> |
---|
247 | GnuTLSPGPKeyringFile <i>file-path</i><br /> |
---|
248 | <h5>Default:</h5> |
---|
249 | <i>none</i><br /> |
---|
250 | <h5>Context:</h5> |
---|
251 | server config, virtual host<br /> |
---|
252 | </div> |
---|
253 | <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 /> |
---|
254 | This file should contain a list of trusted signers.</p> |
---|
255 | <h4>GnuTLSEnable</h4> |
---|
256 | <div class="directive"> |
---|
257 | <h5>Description:</h5>Enable GnuTLS for this virtual host<br /> |
---|
258 | <h5>Syntax:</h5> |
---|
259 | GnuTLSEnable [ <i>on</i> | <i>off</i> ] <br /> |
---|
260 | <h5>Default:</h5> |
---|
261 | <i>off</i><br /> |
---|
262 | <h5>Context:</h5> |
---|
263 | virtual host<br /> |
---|
264 | </div> |
---|
265 | <p>This directive enables SSL/TLS Encryption for a Virtual Host.</p> |
---|
266 | <h4>GnuTLSDHFile</h4> |
---|
267 | <div class="directive"> |
---|
268 | <h5>Description:</h5>Set to the PKCS #3 encoded Diffie Hellman parameters<br /> |
---|
269 | <h5>Syntax:</h5> |
---|
270 | GnuTLSDHFile <i>file-path</i> <br /> |
---|
271 | <h5>Default:</h5> |
---|
272 | <i>none</i><br /> |
---|
273 | <h5>Context:</h5> |
---|
274 | server config, virtual host<br /> |
---|
275 | </div> |
---|
276 | <p>Takes an absolute or relative path to a PKCS #3 encoded DH parameters.<br /> |
---|
277 | Those are used when the DHE key exchange method is enabled.<br /> |
---|
278 | You can generate this file using "certtool --generate-dh-params --bits 2048".<br /> |
---|
279 | If not set mod_gnutls will use the included parameters.</p> |
---|
280 | <h4>GnuTLSSRPPasswdFile</h4> |
---|
281 | <div class="directive"> |
---|
282 | <h5>Description:</h5>Set to the SRP password file for SRP ciphersuites<br /> |
---|
283 | <h5>Syntax:</h5> |
---|
284 | GnuTLSSRPPasswdFile <i>file-path</i> <br /> |
---|
285 | <h5>Default:</h5> |
---|
286 | <i>none</i><br /> |
---|
287 | <h5>Context:</h5> |
---|
288 | server config, virtual host<br /> |
---|
289 | </div> |
---|
290 | <p>Takes an absolute or relative path to an SRP password file. This is the same format as used in libsrp.<br /> |
---|
291 | 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 /> |
---|
292 | This password file holds the username, a password verifier and the dependency to the SRP parameters.</p> |
---|
293 | <h4>GnuTLSSRPPasswdConfFile</h4> |
---|
294 | <div class="directive"> |
---|
295 | <h5>Description:</h5>Set to the SRP password.conf file for SRP ciphersuites<br /> |
---|
296 | <h5>Syntax:</h5> |
---|
297 | GnuTLSSRPPasswdConfFile <i>file-path</i> <br /> |
---|
298 | <h5>Default:</h5> |
---|
299 | <i>none</i><br /> |
---|
300 | <h5>Context:</h5> |
---|
301 | server config, virtual host<br /> |
---|
302 | </div> |
---|
303 | <p>Takes an absolute or relative path to an SRP password.conf file. This is the same format as used in libsrp.<br /> |
---|
304 | You can generate such file using the command "srptool --create-conf /etc/tpasswd.conf".<br /> |
---|
305 | This file holds the SRP parameters and is associate with the password file (the verifiers depends on these parameters).</p> |
---|
306 | <h4>GnuTLSPriorities</h4> |
---|
307 | <div class="directive"> |
---|
308 | <h5>Description:</h5>Set the allowed ciphers, key exchange algorithms, MACs and compression methods<br /> |
---|
309 | <h5>Syntax:</h5> |
---|
310 | GnuTLSPriorities <i>+cipher0:+cipher1:...:+cipherN</i><br /> |
---|
311 | <h5>Default:</h5> |
---|
312 | <i>none</i><br /> |
---|
313 | <h5>Context:</h5> |
---|
314 | server config, virtual host<br /> |
---|
315 | </div> |
---|
316 | <p> |
---|
317 | Takes a semi-colon separated list of ciphers, key exchange methods<br /> |
---|
318 | Message authentication codes and compression methods to enable.<br /> |
---|
319 | The allowed keywords are specified in the gnutls_priority_init() function of GnuTLS.<br /> |
---|
320 | 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 /> |
---|
321 | In brief you can specify a set of ciphersuites from the choices:<br /> |
---|
322 | <ul> |
---|
323 | <li><b>NONE</b>: The empty list.</li> |
---|
324 | <li><b>EXPORT</b>: A list with all the supported cipher combinations including the "EXPORT" strength algorithms.</li> |
---|
325 | <li><b>PERFORMANCE</b>: A list with all the secure cipher combinations sorted in terms of performance.</li> |
---|
326 | <li><b>NORMAL</b>: A list with all the secure cipher combinations sorted with respect to security margin (subjective term).</li> |
---|
327 | <li><b>SECURE</b>: A list with all the secure cipher combinations including the 256-bit ciphers sorted with respect to security margin.</li> |
---|
328 | </ul> |
---|
329 | </p> |
---|
330 | <p> |
---|
331 | Additionally you can add or remove algorithms using the "+" and "!" prefixes respectively.<br /> |
---|
332 | That is in order to disable the ARCFOUR cipher from the "NORMAL" set you can use the string <b>NORMAL</b>:!ARCFOUR-128<br /> |
---|
333 | 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 /> |
---|
334 | So in order to remove or add a specific TLS version from the "NORMAL" set use <b>NORMAL:!VERS-SSL3.0</b>.<br /> |
---|
335 | To enable zlib compression use <b>NORMAL:+COMP-DEFLATE</b>.<br /> |
---|
336 | However it is recommended not to add compression at this level.<br /> |
---|
337 | With the "NONE" set, in order to be usable, you have to specify a complete set of combinations of protocol versions,<br /> |
---|
338 | 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 /> |
---|
339 | <br /> |
---|
340 | All the supported algorithms are:<br /> |
---|
341 | <ul> |
---|
342 | <li><b>Ciphers</b>: AES-256-CBC, AES-128-CBC, CAMELLIA-256-CBC, CAMELLIA-128-CBC, ARCFOUR-128, 3DES-CBC, ARCFOUR-40</li> |
---|
343 | <li><b>Key exchange methods</b>: RSA, DHE-RSA, DHE-DSS, SRP, SRP-RSA, SRP-DSS, ANON-DH</li> |
---|
344 | <li><b>Message authentication codes</b>: SHA1, MD5</li> |
---|
345 | <li><b>Compression methods</b>: COMP-DEFLATE, COMP-NULL</li> |
---|
346 | <li><b>Protocol versions</b>: VERS-TLS1.1, VERS-TLS1.0, VERS-SSL3.0</li> |
---|
347 | </ul> |
---|
348 | </p> |
---|
349 | <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> |
---|
350 | <h4>GnuTLSExportCertificates</h4> |
---|
351 | <div class="directive"> |
---|
352 | <h5>Description:</h5>Export the PEM encoded certificates to CGIs<br /> |
---|
353 | <h5>Syntax:</h5> |
---|
354 | GnuTLSExportCertificates [ <i>on</i> | <i>off</i> ]<br /> |
---|
355 | <h5>Default:</h5> |
---|
356 | <i>off</i><br /> |
---|
357 | <h5>Context:</h5> |
---|
358 | server config, virtual host<br /> |
---|
359 | </div> |
---|
360 | <p>This directive enables exporting the full PEM encoded certificates of the server and the client to CGIs.<br /> |
---|
361 | This makes mod_gnutls export exactly the same environment variables as mod_ssl.</p> |
---|
362 | </div> |
---|
363 | <hr /> |
---|
364 | <div id="Examples"> |
---|
365 | <h2>Configuration Examples</h2> |
---|
366 | <h4>Simple Standard SSL Example:</h4> |
---|
367 | <p>The following is an example of standard SSL Hosting, using one IP Addresses for each virtual host</p> |
---|
368 | <p> |
---|
369 | <code> |
---|
370 | # Load the module into Apache.<br /> |
---|
371 | LoadModule gnutls_module modules/mod_gnutls.so<br /> |
---|
372 | GnuTLSCache gdbm /var/cache/www-tls-cache<br /> |
---|
373 | GnuTLSCacheTimeout 500<br /> |
---|
374 | # With normal SSL Websites, you need one IP Address per-site.<br /> |
---|
375 | Listen 1.2.3.1:443<br /> |
---|
376 | Listen 1.2.3.2:443<br /> |
---|
377 | Listen 1.2.3.3:443<br /> |
---|
378 | Listen 1.2.3.4:443<br /> |
---|
379 | <VirtualHost 1.2.3.1:443><br /> |
---|
380 | GnuTLSEnable on<br /> |
---|
381 | GnuTLSPriorities NONE:+AES-128-CBC:+3DES-CBC:+ARCFOUR-128:+RSA:+DHE-RSA:+DHE-DSS:+SHA1:+MD5:+COMP-NULL<br /> |
---|
382 | DocumentRoot /www/site1.example.com/html<br /> |
---|
383 | ServerName site1.example.com:443<br /> |
---|
384 | GnuTLSCertificateFile conf/ssl/site1.crt<br /> |
---|
385 | GnuTLSKeyFile conf/ss/site1.key<br /> |
---|
386 | </VirtualHost><br /> |
---|
387 | <VirtualHost 1.2.3.2:443><br /> |
---|
388 | # This virtual host enables SRP authentication<br /> |
---|
389 | GnuTLSEnable on<br /> |
---|
390 | GnuTLSPriorities NORMAL:+SRP<br /> |
---|
391 | DocumentRoot /www/site2.example.com/html<br /> |
---|
392 | ServerName site2.example.com:443<br /> |
---|
393 | GnuTLSSRPPasswdFile conf/ssl/tpasswd.site2<br /> |
---|
394 | GnuTLSSRPPasswdConfFile conf/ssl/tpasswd.site2.conf<br /> |
---|
395 | </VirtualHost><br /> |
---|
396 | <VirtualHost 1.2.3.3:443><br /> |
---|
397 | # This server enables SRP, OpenPGP and X.509 authentication.<br /> |
---|
398 | GnuTLSEnable on<br /> |
---|
399 | GnuTLSPriorities NORMAL:+SRP:+SRP-RSA:+SRP-DSS<br /> |
---|
400 | DocumentRoot /www/site3.example.com/html<br /> |
---|
401 | ServerName site3.example.com:443<br /> |
---|
402 | GnuTLSCertificateFile conf/ssl/site3.crt<br /> |
---|
403 | GnuTLSKeyFile conf/ss/site3.key<br /> |
---|
404 | GnuTLSClientVerify ignore<br /> |
---|
405 | GnuTLSPGPCertificateFile conf/ss/site3.pub.asc<br /> |
---|
406 | GnuTLSPGPKeyFile conf/ss/site3.sec.asc<br /> |
---|
407 | GnuTLSSRPPasswdFile conf/ssl/tpasswd.site3<br /> |
---|
408 | GnuTLSSRPPasswdConfFile conf/ssl/tpasswd.site3.conf<br /> |
---|
409 | </VirtualHost><br /> |
---|
410 | <VirtualHost 1.2.3.4:443><br /> |
---|
411 | GnuTLSEnable on<br /> |
---|
412 | # %COMPAT disables some security features to enable maximum compatibility with clients.<br /> |
---|
413 | GnuTLSPriorities NONE:+AES-128-CBC:+ARCFOUR-128:+RSA:+SHA1:+MD5:+COMP-NULL:%COMPAT<br /> |
---|
414 | DocumentRoot /www/site4.example.com/html<br /> |
---|
415 | ServerName site4.example.com:443<br /> |
---|
416 | GnuTLSCertificateFile conf/ssl/site4.crt<br /> |
---|
417 | GnuTLSKeyFile conf/ss/site4.key<br /> |
---|
418 | </VirtualHost><br /> |
---|
419 | </code> |
---|
420 | </p> |
---|
421 | <h4>Server Name Indication Example:</h4> |
---|
422 | <p> |
---|
423 | mod_gnutls can also use 'Server Name Indication', as specified in RFC 3546.<br /> |
---|
424 | This allows hosting many SSL Websites, with a Single IP Address.<br /> |
---|
425 | Currently all the recent browsers support this standard.<br /> |
---|
426 | Here is an example, using SNI:<br /> |
---|
427 | <code> |
---|
428 | <p> |
---|
429 | # Load the module into Apache.<br /> |
---|
430 | LoadModule gnutls_module modules/mod_gnutls.so<br /> |
---|
431 | # With normal SSL Websites, you need one IP Address per-site.<br /> |
---|
432 | Listen 1.2.3.1:443<br /> |
---|
433 | # This could also be 'Listen *:443',<br /> |
---|
434 | # just like '*:80' is common for non-https<br /> |
---|
435 | # No caching. Enable session tickets. Timeout is still used for<br /> |
---|
436 | # ticket expiration.<br /> |
---|
437 | GnuTLSCacheTimeout 600<br /> |
---|
438 | # This tells apache, that for this IP/Port combination, we want to use<br /> |
---|
439 | # Name Based Virtual Hosting. In the case of Server Name Indication,<br /> |
---|
440 | # it lets mod_gnutls pick the correct Server Certificate.<br /> |
---|
441 | NameVirtualHost 1.2.3.1:443<br /> |
---|
442 | <VirtualHost 1.2.3.1:443><br /> |
---|
443 | GnuTLSEnable on<br /> |
---|
444 | GnuTLSSessionTickets on<br /> |
---|
445 | GnuTLSPriorities NORMAL<br /> |
---|
446 | DocumentRoot /www/site1.example.com/html<br /> |
---|
447 | ServerName site1.example.com:443<br /> |
---|
448 | GnuTLSCertificateFile conf/ssl/site1.crt<br /> |
---|
449 | GnuTLSKeyFile conf/ss/site1.key<br /> |
---|
450 | </VirtualHost><br /> |
---|
451 | <VirtualHost 1.2.3.1:443><br /> |
---|
452 | GnuTLSEnable on<br /> |
---|
453 | GnuTLSPriorities NORMAL<br /> |
---|
454 | DocumentRoot /www/site2.example.com/html<br /> |
---|
455 | ServerName site2.example.com:443<br /> |
---|
456 | GnuTLSCertificateFile conf/ssl/site2.crt<br /> |
---|
457 | GnuTLSKeyFile conf/ss/site2.key<br /> |
---|
458 | </VirtualHost><br /> |
---|
459 | <VirtualHost 1.2.3.1:443><br /> |
---|
460 | GnuTLSEnable on<br /> |
---|
461 | GnuTLSPriorities NORMAL<br /> |
---|
462 | DocumentRoot /www/site3.example.com/html<br /> |
---|
463 | ServerName site3.example.com:443<br /> |
---|
464 | GnuTLSCertificateFile conf/ssl/site3.crt<br /> |
---|
465 | GnuTLSKeyFile conf/ss/site3.key<br /> |
---|
466 | </VirtualHost><br /> |
---|
467 | <VirtualHost 1.2.3.1:443><br /> |
---|
468 | GnuTLSEnable on<br /> |
---|
469 | GnuTLSPriorities NORMAL<br /> |
---|
470 | DocumentRoot /www/site4.example.com/html<br /> |
---|
471 | ServerName site4.example.com:443<br /> |
---|
472 | GnuTLSCertificateFile conf/ssl/site4.crt<br /> |
---|
473 | GnuTLSKeyFile conf/ss/site4.key<br /> |
---|
474 | </VirtualHost><br /> |
---|
475 | </p> |
---|
476 | </code> |
---|
477 | </p> |
---|
478 | </div> |
---|
479 | <hr /> |
---|
480 | <div id="Performance"> |
---|
481 | <h2>Performance Issues:</h2> |
---|
482 | <p> |
---|
483 | mod_gnutls by default uses conservative settings for the server.<br /> |
---|
484 | You can fine tune the configuration to reduce the load on a busy server.<br /> |
---|
485 | The following examples do exactly this:<br /> |
---|
486 | <code> |
---|
487 | # Load the module into Apache.<br /> |
---|
488 | LoadModule gnutls_module modules/mod_gnutls.so<br /> |
---|
489 | # Using 4 memcache servers to distribute the SSL Session Cache.<br /> |
---|
490 | GnuTLSCache memcache "mc1.example.com mc2.example.com mc3.example.com mc4.example.com"<br /> |
---|
491 | GnuTLSCacheTimeout 600<br /> |
---|
492 | Listen 1.2.3.1:443<br /> |
---|
493 | NameVirtualHost 1.2.3.1:443<br /> |
---|
494 | <VirtualHost 1.2.3.1:443><br /> |
---|
495 | GnuTLSEnable on<br /> |
---|
496 | # Here we disable the Perfect forward secrecy ciphersuites (DHE)<br /> |
---|
497 | # and disallow AES-256 since AES-128 is just fine.<br /> |
---|
498 | GnuTLSPriorities NORMAL:!DHE-RSA:!DHE-DSS:!AES-256-CBC:%COMPAT<br /> |
---|
499 | DocumentRoot /www/site1.example.com/html<br /> |
---|
500 | ServerName site1.example.com:443<br /> |
---|
501 | GnuTLSCertificateFile conf/ssl/site1.crt<br /> |
---|
502 | GnuTLSKeyFile conf/ss/site1.key<br /> |
---|
503 | </VirtualHost><br /> |
---|
504 | <VirtualHost 1.2.3.1:443><br /> |
---|
505 | GnuTLSEnable on<br /> |
---|
506 | # Here we instead of disabling the DHE ciphersuites we use<br /> |
---|
507 | # Diffie Hellman parameters of smaller size than the default (2048 bits).<br /> |
---|
508 | # Using small numbers from 768 to 1024 bits should be ok once they are<br /> |
---|
509 | # regenerated every few hours.<br /> |
---|
510 | # Use "certtool --generate-dh-params --bits 1024" to get those<br /> |
---|
511 | GnuTLSDHFile /etc/apache2/dh.params<br /> |
---|
512 | GnuTLSPriorities NORMAL:!AES-256-CBC:%COMPAT<br /> |
---|
513 | DocumentRoot /www/site2.example.com/html<br /> |
---|
514 | ServerName site2.example.com:443<br /> |
---|
515 | GnuTLSCertificateFile conf/ssl/site2.crt<br /> |
---|
516 | GnuTLSKeyFile conf/ss/site2.key<br /> |
---|
517 | </VirtualHost><br /> |
---|
518 | </code> |
---|
519 | </p> |
---|
520 | </div> |
---|
521 | <hr /> |
---|
522 | <div id="EnvironmentVars"> |
---|
523 | <h2>Environment Variables:</h2> |
---|
524 | <p>mod_gnutls exports the following environment variables to scripts.<br /> |
---|
525 | These are compatible with mod_ssl.</p> |
---|
526 | <h6>HTTPS</h6> |
---|
527 | <p>Can be "on" or "off"</p> |
---|
528 | <h6>SSL_VERSION_LIBRARY</h6> |
---|
529 | <p>The version of the gnutls library</p> |
---|
530 | <h6>SSL_VERSION_INTERFACE</h6> |
---|
531 | <p>The version of this module</p> |
---|
532 | <h6>SSL_PROTOCOL</h6> |
---|
533 | <p>The SSL or TLS protocol name (such as "TLS 1.0" etc.)</p> |
---|
534 | <h6>SSL_CIPHER</h6> |
---|
535 | <p>The SSL or TLS cipher suite name</p> |
---|
536 | <h6>SSL_COMPRESS_METHOD</h6> |
---|
537 | <p>The negotiated compression method (NULL or DEFLATE)</p> |
---|
538 | <h6>SSL_SRP_USER</h6> |
---|
539 | <p>The SRP username used for authentication (only set when GnuTLSSRPPasswdFile and GnuTLSSRPPasswdConfFile are configured).</p> |
---|
540 | <h6>SSL_CIPHER_USEKEYSIZE & SSL_CIPHER_ALGKEYSIZE</h6> |
---|
541 | <p>The number if bits used in the used cipher algorithm.</p> |
---|
542 | <p>This does not fully reflect the security level since the size of</p> |
---|
543 | <p>RSA or DHE key exchange parameters affect the security level too.</p> |
---|
544 | <h6>SSL_CIPHER_EXPORT</h6> |
---|
545 | <p>True or False. Whether the cipher suite negotiated is an export one.</p> |
---|
546 | <h6>SSL_SESSION_ID</h6> |
---|
547 | <p>The session ID negotiated in this session. Can be the same during client reloads.</p> |
---|
548 | <h6>SSL_CLIENT_V_REMAIN</h6> |
---|
549 | <p>The number of days until the client's certificate is expired.</p> |
---|
550 | <h6>SSL_CLIENT_V_START</h6> |
---|
551 | <p>The activation time of client's certificate.</p> |
---|
552 | <h6>SSL_CLIENT_V_END</h6> |
---|
553 | <p>The expiration time of client's certificate.</p> |
---|
554 | <h6>SSL_CLIENT_S_DN</h6> |
---|
555 | <p>The distinguished name of client's certificate in RFC2253 format.</p> |
---|
556 | <h6>SSL_CLIENT_I_DN</h6> |
---|
557 | <p>The SSL or TLS cipher suite name</p> |
---|
558 | <h6>SSL_CLIENT_S_AN%</h6> |
---|
559 | <p>These will contain the alternative names of the client certificate (% is a number starting from zero).</p> |
---|
560 | <p>The values will be prepended by "DNSNAME:", "RFC822NAME:" or "URI:" depending on the type.</p> |
---|
561 | <p>If it is not supported the value "UNSUPPORTED" will be set.</p> |
---|
562 | <h6>SSL_SERVER_M_SERIAL</h6> |
---|
563 | <p>The serial number of the server's certificate.</p> |
---|
564 | <h6>SSL_SERVER_M_VERSION</h6> |
---|
565 | <p>The version of the server's certificate.</p> |
---|
566 | <h6>SSL_SERVER_A_SIG</h6> |
---|
567 | <p>The algorithm used for the signature in server's certificate.</p> |
---|
568 | <h6>SSL_SERVER_A_KEY</h6> |
---|
569 | <p>The public key algorithm in server's certificate.</p> |
---|
570 | <h6>SSL_SERVER_CERT</h6> |
---|
571 | <p>The PEM-encoded server certificate.</p> |
---|
572 | <h6>SSL_SERVER_CERT_TYPE</h6> |
---|
573 | <p>The certificate type can be X.509 or OPENPGP.</p> |
---|
574 | </div> |
---|
575 | </body> |
---|
576 | </html> |
---|