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 gdbm "conf/gnutls_cache"<br /> |
---|
94 | <h5>Context:</h5> |
---|
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> |
---|
120 | GnuTLSCacheTimeout <i>seconds</i><br /> |
---|
121 | <h5>Default:</h5> |
---|
122 | GnuTLSCache gdbm "conf/gnutls_cache"<br /> |
---|
123 | <h5>Context:</h5> |
---|
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> |
---|
132 | GnuTLSSessionTickets [ <i>on</i> | <i>off</i> ]<br /> |
---|
133 | <h5>Default:</h5> |
---|
134 | <i>off</i><br /> |
---|
135 | <h5>Context:</h5> |
---|
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> |
---|
145 | GnuTLSCertificateFile <i>file-path</i><br /> |
---|
146 | <h5>Default:</h5> |
---|
147 | <i>none</i><br /> |
---|
148 | <h5>Context:</h5> |
---|
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> |
---|
156 | GnuTLSCertificateFile <i>file-path</i><br /> |
---|
157 | <h5>Default:</h5> |
---|
158 | <i>none</i><br /> |
---|
159 | <h5>Context:</h5> |
---|
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> |
---|
172 | GnuTLSPGPCertificateFile <i>file-path</i><br /> |
---|
173 | <h5>Default:</h5> |
---|
174 | <i>none</i><br /> |
---|
175 | <h5>Context:</h5> |
---|
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> |
---|
183 | GnuTLSPGPKeyFile <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 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> |
---|
198 | GnuTLSClientVerify [ <i>ignore</i> | <i>request</i> | <i>require</i> ]<br /> |
---|
199 | <h5>Default:</h5> |
---|
200 | <i>ignore</i><br /> |
---|
201 | <h5>Context:</h5> |
---|
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> |
---|
222 | GnuTLSClientCAFile <i>file-path</i><br /> |
---|
223 | <h5>Default:</h5> |
---|
224 | <i>none</i><br /> |
---|
225 | <h5>Context:</h5> |
---|
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> |
---|
236 | GnuTLSPGPKeyringFile <i>file-path</i><br /> |
---|
237 | <h5>Default:</h5> |
---|
238 | <i>none</i><br /> |
---|
239 | <h5>Context:</h5> |
---|
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> |
---|
248 | GnuTLSEnable [ <i>on</i> | <i>off</i> ] <br /> |
---|
249 | <h5>Default:</h5> |
---|
250 | <i>off</i><br /> |
---|
251 | <h5>Context:</h5> |
---|
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> |
---|
259 | GnuTLSDHFile <i>file-path</i> <br /> |
---|
260 | <h5>Default:</h5> |
---|
261 | <i>none</i><br /> |
---|
262 | <h5>Context:</h5> |
---|
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>GnuTLSSRPPasswdFile</h4> |
---|
270 | <div class="directive"> |
---|
271 | <h5>Description:</h5>Set to the SRP password file for SRP ciphersuites<br /> |
---|
272 | <h5>Syntax:</h5> |
---|
273 | GnuTLSSRPPasswdFile <i>file-path</i> <br /> |
---|
274 | <h5>Default:</h5> |
---|
275 | <i>none</i><br /> |
---|
276 | <h5>Context:</h5> |
---|
277 | server config, virtual host<br /> |
---|
278 | </div> |
---|
279 | <p>Takes an absolute or relative path to an SRP password file. This is the same format as used in libsrp.<br /> |
---|
280 | 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 /> |
---|
281 | This password file holds the username, a password verifier and the dependency to the SRP parameters.</p> |
---|
282 | <h4>GnuTLSSRPPasswdConfFile</h4> |
---|
283 | <div class="directive"> |
---|
284 | <h5>Description:</h5>Set to the SRP password.conf file for SRP ciphersuites<br /> |
---|
285 | <h5>Syntax:</h5> |
---|
286 | GnuTLSSRPPasswdConfFile <i>file-path</i> <br /> |
---|
287 | <h5>Default:</h5> |
---|
288 | <i>none</i><br /> |
---|
289 | <h5>Context:</h5> |
---|
290 | server config, virtual host<br /> |
---|
291 | </div> |
---|
292 | <p>Takes an absolute or relative path to an SRP password.conf file. This is the same format as used in libsrp.<br /> |
---|
293 | You can generate such file using the command "srptool --create-conf /etc/tpasswd.conf".<br /> |
---|
294 | This file holds the SRP parameters and is associate with the password file (the verifiers depends on these parameters).</p> |
---|
295 | <h4>GnuTLSPriorities</h4> |
---|
296 | <div class="directive"> |
---|
297 | <h5>Description:</h5>Set the allowed ciphers, key exchange algorithms, MACs and compression methods<br /> |
---|
298 | <h5>Syntax:</h5> |
---|
299 | GnuTLSPriorities <i>+cipher0:+cipher1:...:+cipherN</i><br /> |
---|
300 | <h5>Default:</h5> |
---|
301 | <i>none</i><br /> |
---|
302 | <h5>Context:</h5> |
---|
303 | server config, virtual host<br /> |
---|
304 | </div> |
---|
305 | <p> |
---|
306 | Takes a semi-colon separated list of ciphers, key exchange methods<br /> |
---|
307 | Message authentication codes and compression methods to enable.<br /> |
---|
308 | The allowed keywords are specified in the gnutls_priority_init() function of GnuTLS.<br /> |
---|
309 | 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 /> |
---|
310 | In brief you can specify a set of ciphersuites from the choices:<br /> |
---|
311 | <ul> |
---|
312 | <li><b>NONE</b>: The empty list.</li> |
---|
313 | <li><b>EXPORT</b>: A list with all the supported cipher combinations including the "EXPORT" strength algorithms.</li> |
---|
314 | <li><b>PERFORMANCE</b>: A list with all the secure cipher combinations sorted in terms of performance.</li> |
---|
315 | <li><b>NORMAL</b>: A list with all the secure cipher combinations sorted with respect to security margin (subjective term).</li> |
---|
316 | <li><b>SECURE</b>: A list with all the secure cipher combinations including the 256-bit ciphers sorted with respect to security margin.</li> |
---|
317 | </ul> |
---|
318 | </p> |
---|
319 | <p> |
---|
320 | Additionally you can add or remove algorithms using the "+" and "!" prefixes respectively.<br /> |
---|
321 | That is in order to disable the ARCFOUR cipher from the "NORMAL" set you can use the string <b>NORMAL</b>:!ARCFOUR-128<br /> |
---|
322 | 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 /> |
---|
323 | So in order to remove or add a specific TLS version from the "NORMAL" set use <b>NORMAL:!VERS-SSL3.0</b>.<br /> |
---|
324 | To enable zlib compression use <b>NORMAL:+COMP-DEFLATE</b>.<br /> |
---|
325 | However it is recommended not to add compression at this level.<br /> |
---|
326 | With the "NONE" set, in order to be usable, you have to specify a complete set of combinations of protocol versions,<br /> |
---|
327 | 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 /> |
---|
328 | <br /> |
---|
329 | All the supported algorithms are:<br /> |
---|
330 | <ul> |
---|
331 | <li><b>Ciphers</b>: AES-256-CBC, AES-128-CBC, CAMELLIA-256-CBC, CAMELLIA-128-CBC, ARCFOUR-128, 3DES-CBC, ARCFOUR-40</li> |
---|
332 | <li><b>Key exchange methods</b>: RSA, DHE-RSA, DHE-DSS, SRP, SRP-RSA, SRP-DSS, ANON-DH</li> |
---|
333 | <li><b>Message authentication codes</b>: SHA1, MD5</li> |
---|
334 | <li><b>Compression methods</b>: COMP-DEFLATE, COMP-NULL</li> |
---|
335 | <li><b>Protocol versions</b>: VERS-TLS1.1, VERS-TLS1.0, VERS-SSL3.0</li> |
---|
336 | </ul> |
---|
337 | </p> |
---|
338 | <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> |
---|
339 | <h4>GnuTLSExportCertificates</h4> |
---|
340 | <div class="directive"> |
---|
341 | <h5>Description:</h5>Export the PEM encoded certificates to CGIs<br /> |
---|
342 | <h5>Syntax:</h5> |
---|
343 | GnuTLSExportCertificates [ <i>on</i> | <i>off</i> ]<br /> |
---|
344 | <h5>Default:</h5> |
---|
345 | <i>off</i><br /> |
---|
346 | <h5>Context:</h5> |
---|
347 | server config, virtual host<br /> |
---|
348 | </div> |
---|
349 | <p>This directive enables exporting the full PEM encoded certificates of the server and the client to CGIs.<br /> |
---|
350 | This makes mod_gnutls export exactly the same environment variables as mod_ssl.</p> |
---|
351 | </div> |
---|
352 | <hr /> |
---|
353 | <div id="Examples"> |
---|
354 | <h2>Configuration Examples</h2> |
---|
355 | <h4>Simple Standard SSL Example:</h4> |
---|
356 | <p>The following is an example of standard SSL Hosting, using one IP Addresses for each virtual host</p> |
---|
357 | <p> |
---|
358 | <code> |
---|
359 | # Load the module into Apache.<br /> |
---|
360 | LoadModule gnutls_module modules/mod_gnutls.so<br /> |
---|
361 | GnuTLSCache gdbm /var/cache/www-tls-cache<br /> |
---|
362 | GnuTLSCacheTimeout 500<br /> |
---|
363 | # With normal SSL Websites, you need one IP Address per-site.<br /> |
---|
364 | Listen 1.2.3.1:443<br /> |
---|
365 | Listen 1.2.3.2:443<br /> |
---|
366 | Listen 1.2.3.3:443<br /> |
---|
367 | Listen 1.2.3.4:443<br /> |
---|
368 | <VirtualHost 1.2.3.1:443><br /> |
---|
369 | GnuTLSEnable on<br /> |
---|
370 | GnuTLSPriorities NONE:+AES-128-CBC:+3DES-CBC:+ARCFOUR-128:+RSA:+DHE-RSA:+DHE-DSS:+SHA1:+MD5:+COMP-NULL<br /> |
---|
371 | DocumentRoot /www/site1.example.com/html<br /> |
---|
372 | ServerName site1.example.com:443<br /> |
---|
373 | GnuTLSCertificateFile conf/ssl/site1.crt<br /> |
---|
374 | GnuTLSKeyFile conf/ss/site1.key<br /> |
---|
375 | </VirtualHost><br /> |
---|
376 | <VirtualHost 1.2.3.2:443><br /> |
---|
377 | # This virtual host enables SRP authentication<br /> |
---|
378 | GnuTLSEnable on<br /> |
---|
379 | GnuTLSPriorities NORMAL:+SRP<br /> |
---|
380 | DocumentRoot /www/site2.example.com/html<br /> |
---|
381 | ServerName site2.example.com:443<br /> |
---|
382 | GnuTLSSRPPasswdFile conf/ssl/tpasswd.site2<br /> |
---|
383 | GnuTLSSRPPasswdConfFile conf/ssl/tpasswd.site2.conf<br /> |
---|
384 | </VirtualHost><br /> |
---|
385 | <VirtualHost 1.2.3.3:443><br /> |
---|
386 | # This server enables SRP, OpenPGP and X.509 authentication.<br /> |
---|
387 | GnuTLSEnable on<br /> |
---|
388 | GnuTLSPriorities NORMAL:+SRP:+SRP-RSA:+SRP-DSS<br /> |
---|
389 | DocumentRoot /www/site3.example.com/html<br /> |
---|
390 | ServerName site3.example.com:443<br /> |
---|
391 | GnuTLSCertificateFile conf/ssl/site3.crt<br /> |
---|
392 | GnuTLSKeyFile conf/ss/site3.key<br /> |
---|
393 | GnuTLSClientVerify ignore<br /> |
---|
394 | GnuTLSPGPCertificateFile conf/ss/site3.pub.asc<br /> |
---|
395 | GnuTLSPGPKeyFile conf/ss/site3.sec.asc<br /> |
---|
396 | GnuTLSSRPPasswdFile conf/ssl/tpasswd.site3<br /> |
---|
397 | GnuTLSSRPPasswdConfFile conf/ssl/tpasswd.site3.conf<br /> |
---|
398 | </VirtualHost><br /> |
---|
399 | <VirtualHost 1.2.3.4:443><br /> |
---|
400 | GnuTLSEnable on<br /> |
---|
401 | # %COMPAT disables some security features to enable maximum compatibility with clients.<br /> |
---|
402 | GnuTLSPriorities NONE:+AES-128-CBC:+ARCFOUR-128:+RSA:+SHA1:+MD5:+COMP-NULL:%COMPAT<br /> |
---|
403 | DocumentRoot /www/site4.example.com/html<br /> |
---|
404 | ServerName site4.example.com:443<br /> |
---|
405 | GnuTLSCertificateFile conf/ssl/site4.crt<br /> |
---|
406 | GnuTLSKeyFile conf/ss/site4.key<br /> |
---|
407 | </VirtualHost><br /> |
---|
408 | </code> |
---|
409 | </p> |
---|
410 | <h4>Server Name Indication Example:</h4> |
---|
411 | <p> |
---|
412 | mod_gnutls can also use 'Server Name Indication', as specified in RFC 3546.<br /> |
---|
413 | This allows hosting many SSL Websites, with a Single IP Address.M<br /> |
---|
414 | Currently all the recent browsers support this standard.<br /> |
---|
415 | Here is an example, using SNI:<br /> |
---|
416 | <code> |
---|
417 | <p> |
---|
418 | # Load the module into Apache.<br /> |
---|
419 | LoadModule gnutls_module modules/mod_gnutls.so<br /> |
---|
420 | # With normal SSL Websites, you need one IP Address per-site.<br /> |
---|
421 | Listen 1.2.3.1:443<br /> |
---|
422 | # This could also be 'Listen *:443',<br /> |
---|
423 | # just like '*:80' is common for non-https<br /> |
---|
424 | # No caching. Enable session tickets. Timeout is still used for<br /> |
---|
425 | # ticket expiration.<br /> |
---|
426 | GnuTLSCacheTimeout 600<br /> |
---|
427 | # This tells apache, that for this IP/Port combination, we want to use<br /> |
---|
428 | # Name Based Virtual Hosting. In the case of Server Name Indication,<br /> |
---|
429 | # it lets mod_gnutls pick the correct Server Certificate.<br /> |
---|
430 | NameVirtualHost 1.2.3.1:443<br /> |
---|
431 | <VirtualHost 1.2.3.1:443><br /> |
---|
432 | GnuTLSEnable on<br /> |
---|
433 | GnuTLSSessionTickets on<br /> |
---|
434 | GnuTLSPriorities NORMAL<br /> |
---|
435 | DocumentRoot /www/site1.example.com/html<br /> |
---|
436 | ServerName site1.example.com:443<br /> |
---|
437 | GnuTLSCertificateFile conf/ssl/site1.crt<br /> |
---|
438 | GnuTLSKeyFile conf/ss/site1.key<br /> |
---|
439 | </VirtualHost><br /> |
---|
440 | <VirtualHost 1.2.3.1:443><br /> |
---|
441 | GnuTLSEnable on<br /> |
---|
442 | GnuTLSPriorities NORMAL<br /> |
---|
443 | DocumentRoot /www/site2.example.com/html<br /> |
---|
444 | ServerName site2.example.com:443<br /> |
---|
445 | GnuTLSCertificateFile conf/ssl/site2.crt<br /> |
---|
446 | GnuTLSKeyFile conf/ss/site2.key<br /> |
---|
447 | </VirtualHost><br /> |
---|
448 | <VirtualHost 1.2.3.1:443><br /> |
---|
449 | GnuTLSEnable on<br /> |
---|
450 | GnuTLSPriorities NORMAL<br /> |
---|
451 | DocumentRoot /www/site3.example.com/html<br /> |
---|
452 | ServerName site3.example.com:443<br /> |
---|
453 | GnuTLSCertificateFile conf/ssl/site3.crt<br /> |
---|
454 | GnuTLSKeyFile conf/ss/site3.key<br /> |
---|
455 | </VirtualHost><br /> |
---|
456 | <VirtualHost 1.2.3.1:443><br /> |
---|
457 | GnuTLSEnable on<br /> |
---|
458 | GnuTLSPriorities NORMAL<br /> |
---|
459 | DocumentRoot /www/site4.example.com/html<br /> |
---|
460 | ServerName site4.example.com:443<br /> |
---|
461 | GnuTLSCertificateFile conf/ssl/site4.crt<br /> |
---|
462 | GnuTLSKeyFile conf/ss/site4.key<br /> |
---|
463 | </VirtualHost><br /> |
---|
464 | </p> |
---|
465 | </code> |
---|
466 | </p> |
---|
467 | </div> |
---|
468 | <hr /> |
---|
469 | <div id="Performance"> |
---|
470 | <h2>Performance Issues:</h2> |
---|
471 | <p> |
---|
472 | mod_gnutls by default uses conservative settings for the server.<br /> |
---|
473 | You can fine tune the configuration to reduce the load on a busy server.<br /> |
---|
474 | The following examples do exactly this:<br /> |
---|
475 | <code> |
---|
476 | # Load the module into Apache.<br /> |
---|
477 | LoadModule gnutls_module modules/mod_gnutls.so<br /> |
---|
478 | # Using 4 memcache servers to distribute the SSL Session Cache.<br /> |
---|
479 | GnuTLSCache memcache "mc1.example.com mc2.example.com mc3.example.com mc4.example.com"<br /> |
---|
480 | GnuTLSCacheTimeout 600<br /> |
---|
481 | Listen 1.2.3.1:443<br /> |
---|
482 | NameVirtualHost 1.2.3.1:443<br /> |
---|
483 | <VirtualHost 1.2.3.1:443><br /> |
---|
484 | GnuTLSEnable on<br /> |
---|
485 | # Here we disable the Perfect forward secrecy ciphersuites (DHE)<br /> |
---|
486 | # and disallow AES-256 since AES-128 is just fine.<br /> |
---|
487 | GnuTLSPriorities NORMAL:!DHE-RSA:!DHE-DSS:!AES-256-CBC:%COMPAT<br /> |
---|
488 | DocumentRoot /www/site1.example.com/html<br /> |
---|
489 | ServerName site1.example.com:443<br /> |
---|
490 | GnuTLSCertificateFile conf/ssl/site1.crt<br /> |
---|
491 | GnuTLSKeyFile conf/ss/site1.key<br /> |
---|
492 | </VirtualHost><br /> |
---|
493 | <VirtualHost 1.2.3.1:443><br /> |
---|
494 | GnuTLSEnable on<br /> |
---|
495 | # Here we instead of disabling the DHE ciphersuites we use<br /> |
---|
496 | # Diffie Hellman parameters of smaller size than the default (2048 bits).<br /> |
---|
497 | # Using small numbers from 768 to 1024 bits should be ok once they are<br /> |
---|
498 | # regenerated every few hours.<br /> |
---|
499 | # Use "certtool --generate-dh-params --bits 1024" to get those<br /> |
---|
500 | GnuTLSDHFile /etc/apache2/dh.params<br /> |
---|
501 | GnuTLSPriorities NORMAL:!AES-256-CBC:%COMPAT<br /> |
---|
502 | DocumentRoot /www/site2.example.com/html<br /> |
---|
503 | ServerName site2.example.com:443<br /> |
---|
504 | GnuTLSCertificateFile conf/ssl/site2.crt<br /> |
---|
505 | GnuTLSKeyFile conf/ss/site2.key<br /> |
---|
506 | </VirtualHost><br /> |
---|
507 | </code> |
---|
508 | </p> |
---|
509 | </div> |
---|
510 | <hr /> |
---|
511 | <div id="EnvironmentVars"> |
---|
512 | <h2>Environment Variables:</h2> |
---|
513 | <p>mod_gnutls exports the following environment variables to scripts.<br /> |
---|
514 | These are compatible with mod_ssl.</p> |
---|
515 | <h6>HTTPS</h6> |
---|
516 | <p>Can be "on" or "off"</p> |
---|
517 | <h6>SSL_VERSION_LIBRARY</h6> |
---|
518 | <p>The version of the gnutls library</p> |
---|
519 | <h6>SSL_VERSION_INTERFACE</h6> |
---|
520 | <p>The version of this module</p> |
---|
521 | <h6>SSL_PROTOCOL</h6> |
---|
522 | <p>The SSL or TLS protocol name (such as "TLS 1.0" etc.)</p> |
---|
523 | <h6>SSL_CIPHER</h6> |
---|
524 | <p>The SSL or TLS cipher suite name</p> |
---|
525 | <h6>SSL_COMPRESS_METHOD</h6> |
---|
526 | <p>The negotiated compression method (NULL or DEFLATE)</p> |
---|
527 | <h6>SSL_SRP_USER</h6> |
---|
528 | <p>The SRP username used for authentication.</p> |
---|
529 | <h6>SSL_CIPHER_USEKEYSIZE & SSL_CIPHER_ALGKEYSIZE</h6> |
---|
530 | <p>The number if bits used in the used cipher algorithm.</p> |
---|
531 | <p>This does not fully reflect the security level since the size of</p> |
---|
532 | <p>RSA or DHE key exchange parameters affect the security level too.</p> |
---|
533 | <h6>SSL_CIPHER_EXPORT</h6> |
---|
534 | <p>True or False. Whether the cipher suite negotiated is an export one.</p> |
---|
535 | <h6>SSL_SESSION_ID</h6> |
---|
536 | <p>The session ID negotiated in this session. Can be the same during client reloads.</p> |
---|
537 | <h6>SSL_CLIENT_V_REMAIN</h6> |
---|
538 | <p>The number of days until the client's certificate is expired.</p> |
---|
539 | <h6>SSL_CLIENT_V_START</h6> |
---|
540 | <p>The activation time of client's certificate.</p> |
---|
541 | <h6>SSL_CLIENT_V_END</h6> |
---|
542 | <p>The expiration time of client's certificate.</p> |
---|
543 | <h6>SSL_CLIENT_S_DN</h6> |
---|
544 | <p>The distinguished name of client's certificate in RFC2253 format.</p> |
---|
545 | <h6>SSL_CLIENT_I_DN</h6> |
---|
546 | <p>The SSL or TLS cipher suite name</p> |
---|
547 | <h6>SSL_CLIENT_S_AN%</h6> |
---|
548 | <p>These will contain the alternative names of the client certificate (% is a number starting from zero).</p> |
---|
549 | <p>The values will be prepended by "DNSNAME:", "RFC822NAME:" or "URI:" depending on the type.</p> |
---|
550 | <p>If it is not supported the value "UNSUPPORTED" will be set.</p> |
---|
551 | <h6>SSL_SERVER_M_SERIAL</h6> |
---|
552 | <p>The serial number of the server's certificate.</p> |
---|
553 | <h6>SSL_SERVER_M_VERSION</h6> |
---|
554 | <p>The version of the server's certificate.</p> |
---|
555 | <h6>SSL_SERVER_A_SIG</h6> |
---|
556 | <p>The algorithm used for the signature in server's certificate.</p> |
---|
557 | <h6>SSL_SERVER_A_KEY</h6> |
---|
558 | <p>The public key algorithm in server's certificate.</p> |
---|
559 | <h6>SSL_SERVER_CERT</h6> |
---|
560 | <p>The PEM-encoded server certificate.</p> |
---|
561 | <h6>SSL_SERVER_CERT_TYPE</h6> |
---|
562 | <p>The certificate type can be X.509 or OPENPGP.</p> |
---|
563 | </div> |
---|
564 | </body> |
---|
565 | </html> |
---|