aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorGravatar Edward Rudd 2011-07-13 08:51:26 -0400
committerGravatar Edward Rudd 2011-07-13 08:52:00 -0400
commit874e7a7761cfb4895f45b1344fa5ad7dc1163a7f (patch)
tree27079c3bb4307993b8838351d045045c52575dfc /docs
parent09bce31abf08e3d0a24aedc58d6512c9b514137e (diff)
add in manual from outoforder.cc websiteHEADmaster
Diffstat (limited to 'docs')
-rw-r--r--docs/index.xml915
1 files changed, 915 insertions, 0 deletions
diff --git a/docs/index.xml b/docs/index.xml
new file mode 100644
index 0000000..5e150d1
--- /dev/null
+++ b/docs/index.xml
@@ -0,0 +1,915 @@
1<?xml version="1.0"?>
2<?xml-stylesheet type="text/xsl" href="../../../../../xsl/projects.xsl"?>
3<ooo title="mod_gnutls Documentation" path="/projects/apache/mod_gnutls/docs/">
4 <section title="Documentation">
5 <content type="xhtml">
6 <div xmlns="http://www.w3.org/1999/xhtml">
7 <div id="compilation">
8 <h3>Compilation</h3>
9 <p>
10 <code>mod_gnutls</code> uses the "<code>configure/make/make install</code>"
11 mechanism common to many Open Source programs.
12 Most of the dirty work is handled by either configure or
13 Apache's apxs utility. If you have built Apache modules before, there
14 shouldn't be any surprises for you.
15 </p>
16 <p>
17 The interesting options you can pass to configure are:</p>
18 <ul>
19 <li><code>--with-apxs=/path/to/apache/dir/bin/apxs</code>
20 <p>
21 This option is used to specify the location of the
22 apxs utility that was installed as part of apache.
23 Specify the location of the binary, not the directory
24 it is located in.
25 </p>
26 </li>
27 <li><code>--with-libgnutls=PATH</code>
28 <p>Full path to the <code>libgnutls-config</code> program.</p>
29 </li>
30 <li><code>--with-apr-memcache=PREFIX</code>
31 <p>Prefix to where <code><a href="/projects/libs/apr_memcache">apr_memcache</a></code> is installed.</p>
32 </li>
33 <li><code>--help</code>
34 <p>Provides a list of available configure options.</p>
35 </li>
36 </ul>
37<pre class="example">./configure --with-apxs=/usr/sbin/apxs2 --with-libgnutls=/usr
38make
39make install
40</pre>
41 </div>
42 <div id="integration">
43 <h3>Integration into Apache</h3>
44 <p>To activate <code>mod_gnutls</code> Just add<br /><br />
45 <code>LoadModule gnutls_module modules/mod_gnutls.so</code>
46 to your <code>httpd.conf</code> and restart Apache.
47 </p>
48 </div>
49 <div id="index">
50 <h3>Examples</h3>
51<p>Some example configuration and the exported variables to scripts can be
52 found in the following sections:</p>
53 <ul>
54 <li><a href="#example">Simple example</a></li>
55 <li><a href="#sni-example">Example with Server Name Indication</a></li>
56 <li><a href="#performance-example">Performance Issues</a></li>
57 <li><a href="#environment-variables">Environment variables</a></li>
58 </ul>
59 </div>
60 <div id="configuration">
61 <h3>Configuring with Apache</h3>
62<p><code>mod_gnutls</code> has the following directives:</p>
63 <ul>
64 <li><a href="#GnuTLSCache">GnuTLSCache</a></li>
65 <li><a href="#GnuTLSCacheTimeout">GnuTLSCacheTimeout</a></li>
66 <li><a href="#GnuTLSSessionTickets">GnuTLSSessionTickets</a></li>
67 <li><a href="#GnuTLSCertificateFile">GnuTLSCertificateFile</a></li>
68 <li><a href="#GnuTLSKeyFile">GnuTLSKeyFile</a></li>
69 <li><a href="#GnuTLSPGPCertificateFile">GnuTLSPGPCertificateFile</a></li>
70 <li><a href="#GnuTLSPGPKeyFile">GnuTLSPGPKeyFile</a></li>
71 <li><a href="#GnuTLSClientVerify">GnuTLSClientVerify</a></li>
72 <li><a href="#GnuTLSClientCAFile">GnuTLSClientCAFile</a></li>
73 <li><a href="#GnuTLSPGPKeyringFile">GnuTLSPGPKeyringFile</a></li>
74 <li><a href="#GnuTLSEnable">GnuTLSEnable</a></li>
75 <li><a href="#GnuTLSDHFile">GnuTLSDHFile</a></li>
76 <li><a href="#GnuTLSRSAFile">GnuTLSRSAFile</a></li>
77 <li><a href="#GnuTLSSRPPasswdFile">GnuTLSSRPPasswdFile</a></li>
78 <li><a href="#GnuTLSSRPPasswdConfFile">GnuTLSSRPPasswdConfFile</a></li>
79 <li><a href="#GnuTLSPriorities">GnuTLSPriorities</a></li>
80 <li><a href="#GnuTLSExportCertificates">GnuTLSExportCertificates</a></li>
81 </ul>
82 </div>
83 <div id="example">
84 <h3>Standard SSL Example</h3>
85<p>The following is an example of standard SSL Hosting, using one IP Addresses for each virtual host:</p>
86<pre class="example">
87# Load the module into Apache.
88LoadModule gnutls_module modules/mod_gnutls.so
89
90GnuTLSCache dbm /var/cache/www-tls-cache
91GnuTLSCacheTimeout 500
92
93# With normal SSL Websites, you need one IP Address per-site.
94Listen 1.2.3.1:443
95Listen 1.2.3.2:443
96Listen 1.2.3.3:443
97Listen 1.2.3.4:443
98
99&lt;VirtualHost 1.2.3.1:443&gt;
100 GnuTLSEnable on
101 GnuTLSPriorities NONE:+AES-128-CBC:+3DES-CBC:+ARCFOUR-128:+RSA:+DHE-RSA:+DHE-DSS:+SHA1:+MD5:+COMP-NULL
102 DocumentRoot /www/site1.example.com/html
103 ServerName site1.example.com:443
104 GnuTLSCertificateFile conf/ssl/site1.crt
105 GnuTLSKeyFile conf/ss/site1.key
106&lt;/VirtualHost&gt;
107&lt;VirtualHost 1.2.3.2:443&gt;
108# This virtual host enables SRP authentication
109 GnuTLSEnable on
110 GnuTLSPriorities NORMAL:+SRP
111 DocumentRoot /www/site2.example.com/html
112 ServerName site2.example.com:443
113 GnuTLSSRPPasswdFile conf/ssl/tpasswd.site2
114 GnuTLSSRPPasswdConfFile conf/ssl/tpasswd.site2.conf
115&lt;/VirtualHost&gt;
116&lt;VirtualHost 1.2.3.3:443&gt;
117# This server enables SRP, OpenPGP and X.509 authentication.
118 GnuTLSEnable on
119 GnuTLSPriorities NORMAL:+SRP:+SRP-RSA:+SRP-DSS
120 DocumentRoot /www/site3.example.com/html
121 ServerName site3.example.com:443
122 GnuTLSCertificateFile conf/ssl/site3.crt
123 GnuTLSKeyFile conf/ss/site3.key
124 GnuTLSClientVerify ignore
125 GnuTLSPGPCertificateFile conf/ss/site3.pub.asc
126 GnuTLSPGPKeyFile conf/ss/site3.sec.asc
127 GnuTLSSRPPasswdFile conf/ssl/tpasswd.site3
128 GnuTLSSRPPasswdConfFile conf/ssl/tpasswd.site3.conf
129&lt;/VirtualHost&gt;
130&lt;VirtualHost 1.2.3.4:443&gt;
131 GnuTLSEnable on
132# %COMPAT disables some security features to enable maximum compatibility with clients.
133 GnuTLSPriorities NONE:+AES-128-CBC:+ARCFOUR-128:+RSA:+SHA1:+MD5:+COMP-NULL:%COMPAT
134 DocumentRoot /www/site4.example.com/html
135 ServerName site4.example.com:443
136 GnuTLSCertificateFile conf/ssl/site4.crt
137 GnuTLSKeyFile conf/ss/site4.key
138&lt;/VirtualHost&gt;
139</pre>
140</div>
141 <div id="sni-example">
142 <h3>Server Name Indication Example</h3>
143<p><code>mod_gnutls</code> can also use 'Server Name Indication', as specified in
144<a href="http://www.zvon.org/tmRFC/RFC3546/Output/chapter3.html#sub1">RFC 3546</a>. This allows hosting many SSL Websites, with a Single IP Address. Currently all the recent
145browsers support this standard. Here is an example, using SNI:
146</p>
147<pre class="example">
148# Load the module into Apache.
149LoadModule gnutls_module modules/mod_gnutls.so
150
151# With normal SSL Websites, you need one IP Address per-site.
152Listen 1.2.3.1:443
153# This could also be 'Listen *:443',
154# just like '*:80' is common for non-https
155
156# No caching. Enable session tickets. Timeout is still used for
157# ticket expiration.
158GnuTLSCacheTimeout 600
159
160# This tells apache, that for this IP/Port combination, we want to use
161# Name Based Virtual Hosting. In the case of Server Name Indication,
162# it lets mod_gnutls pick the correct Server Certificate.
163NameVirtualHost 1.2.3.1:443
164
165&lt;VirtualHost 1.2.3.1:443&gt;
166 GnuTLSEnable on
167 GnuTLSSessionTickets on
168 GnuTLSPriorities NORMAL
169 DocumentRoot /www/site1.example.com/html
170 ServerName site1.example.com:443
171 GnuTLSCertificateFile conf/ssl/site1.crt
172 GnuTLSKeyFile conf/ss/site1.key
173&lt;/VirtualHost&gt;
174&lt;VirtualHost 1.2.3.1:443&gt;
175 GnuTLSEnable on
176 GnuTLSPriorities NORMAL
177 DocumentRoot /www/site2.example.com/html
178 ServerName site2.example.com:443
179 GnuTLSCertificateFile conf/ssl/site2.crt
180 GnuTLSKeyFile conf/ss/site2.key
181&lt;/VirtualHost&gt;
182&lt;VirtualHost 1.2.3.1:443&gt;
183 GnuTLSEnable on
184 GnuTLSPriorities NORMAL
185 DocumentRoot /www/site3.example.com/html
186 ServerName site3.example.com:443
187 GnuTLSCertificateFile conf/ssl/site3.crt
188 GnuTLSKeyFile conf/ss/site3.key
189&lt;/VirtualHost&gt;
190&lt;VirtualHost 1.2.3.1:443&gt;
191 GnuTLSEnable on
192 GnuTLSPriorities NORMAL
193 DocumentRoot /www/site4.example.com/html
194 ServerName site4.example.com:443
195 GnuTLSCertificateFile conf/ssl/site4.crt
196 GnuTLSKeyFile conf/ss/site4.key
197&lt;/VirtualHost&gt;
198</pre>
199 </div>
200 <div id="performance-example">
201 <h3>Performance Issues</h3>
202<p><code>mod_gnutls</code> by default uses conservative settings for the
203 server. You can fine tune the configuration to reduce the load on a busy
204 server. The following examples do exactly this.
205</p>
206<pre class="example">
207# Load the module into Apache.
208LoadModule gnutls_module modules/mod_gnutls.so
209
210# Using 4 memcache servers to distribute the SSL Session Cache.
211GnuTLSCache memcache "mc1.example.com mc2.example.com mc3.example.com mc4.example.com"
212GnuTLSCacheTimeout 600
213
214Listen 1.2.3.1:443
215NameVirtualHost 1.2.3.1:443
216
217&lt;VirtualHost 1.2.3.1:443&gt;
218 GnuTLSEnable on
219# Here we disable the Perfect forward secrecy ciphersuites (DHE)
220# and disallow AES-256 since AES-128 is just fine.
221 GnuTLSPriorities NORMAL:!DHE-RSA:!DHE-DSS:!AES-256-CBC:%COMPAT
222 DocumentRoot /www/site1.example.com/html
223 ServerName site1.example.com:443
224 GnuTLSCertificateFile conf/ssl/site1.crt
225 GnuTLSKeyFile conf/ss/site1.key
226&lt;/VirtualHost&gt;
227&lt;VirtualHost 1.2.3.1:443&gt;
228 GnuTLSEnable on
229# Here we instead of disabling the DHE ciphersuites we use
230# Diffie Hellman parameters of smaller size than the default (2048 bits).
231# Using small numbers from 768 to 1024 bits should be ok once they are
232# regenerated every few hours.
233# Use "certtool --generate-dh-params --bits 1024" to get those
234 GnuTLSDHFile /etc/apache2/dh.params
235 GnuTLSPriorities NORMAL:!AES-256-CBC:%COMPAT
236 DocumentRoot /www/site2.example.com/html
237 ServerName site2.example.com:443
238 GnuTLSCertificateFile conf/ssl/site2.crt
239 GnuTLSKeyFile conf/ss/site2.key
240&lt;/VirtualHost&gt;
241</pre>
242 </div>
243
244 <div id="environment-variables">
245 <h3>Environment variables</h3>
246<p><code>mod_gnutls</code> exports the following environment variables to
247 scripts.
248</p>
249
250<table class="directive">
251<tr><th>HTTPS:</th><td>can be "on" or "off"</td></tr>
252<tr><th>SSL_VERSION_LIBRARY:</th><td> The version of the gnutls library</td></tr>
253<tr><th>SSL_VERSION_INTERFACE:</th><td> The version of this module</td></tr>
254<tr><th>SSL_PROTOCOL:</th><td> The SSL or TLS protocol name (such as "TLS 1.0" etc.)</td></tr>
255<tr><th>SSL_CIPHER:</th><td> The SSL or TLS cipher suite name.</td></tr>
256<tr><th>SSL_COMPRESS_METHOD:</th><td> The negotiated compression method (NULL or DEFLATE)</td></tr>
257<tr><th>SSL_SRP_USER:</th><td> The SRP username used for authentication.</td></tr>
258<tr><th>SSL_CIPHER_USEKEYSIZE and SSL_CIPHER_ALGKEYSIZE:</th><td> The number if bits used in the used cipher
259 algorithm. This does not fully reflect the security level since the size of
260 RSA or DHE key exchange parameters affect the security level too.</td></tr>
261<tr><th>SSL_CIPHER_EXPORT:</th><td> true or false. Whether the cipher suite negotiated is an export one.</td></tr>
262<tr><th>SSL_SESSION_ID:</th><td> The session ID negotiated in this session. Can be the same during
263 client reloads.</td></tr>
264<tr><th>SSL_CLIENT_V_REMAIN:</th><td> The number of days until the client's certificate is expired.</td></tr>
265<tr><th>SSL_CLIENT_V_START:</th><td> The activation time of client's certificate.</td></tr>
266<tr><th>SSL_CLIENT_V_END:</th><td> The expiration time of client's certificate.</td></tr>
267<tr><th>SSL_CLIENT_S_DN:</th><td> The distinguished name of client's certificate in RFC2253 format.</td></tr>
268<tr><th>SSL_CLIENT_I_DN:</th><td> The distinguished name of client's issuer certificate in RFC2253 format.</td></tr>
269<tr><th>SSL_CLIENT_S_AN%:</th><td> These will contain the alternative names of the client certificate
270 (% is a number starting from zero). The values will be prepended by "DNSNAME:",
271 "RFC822NAME:" or "URI:" depending on the type. If it is not supported the value
272 "UNSUPPORTED" will be set.</td></tr>
273<tr><th>SSL_CLIENT_M_SERIAL:</th><td> The serial number of the client's certificate.</td></tr>
274<tr><th>SSL_CLIENT_M_VERSION:</th><td> The version of the client's certificate.</td></tr>
275<tr><th>SSL_CLIENT_A_SIG:</th><td> The algorithm used for the signature in client's certificate.</td></tr>
276<tr><th>SSL_CLIENT_A_KEY:</th><td> The public key algorithm in client's certificate.</td></tr>
277<tr><th>SSL_CLIENT_CERT:</th><td> The PEM-encoded client certificate</td></tr>
278<tr><th>SSL_CLIENT_VERIFY:</th><td> whether the client's certificate was verified. (NONE if none was sent, or SUCCESS or FAILED)</td></tr>
279<tr><th>SSL_CLIENT_CERT_TYPE:</th><td> The certificate type can be X.509 or OPENPGP.</td></tr>
280<tr><th>SSL_SERVER_V_START:</th><td> The activation time of server's certificate.</td></tr>
281<tr><th>SSL_SERVER_V_END:</th><td> The expiration time of server's certificate.</td></tr>
282<tr><th>SSL_SERVER_S_DN:</th><td> The distinguished name of the server's certificate in RFC2253 format.</td></tr>
283<tr><th>SSL_SERVER_I_DN:</th><td> The distinguished name of the server's issuer certificate in RFC2253 format.</td></tr>
284<tr><th>SSL_SERVER_S_AN%:</th><td> These will contain the alternative names of the server certificate
285 (% is a number starting from zero). The values will be prepended by "DNSNAME:",
286 "RFC822NAME:" or "URI:" depending on the type. If it is not supported the value
287 "UNSUPPORTED" will be set.</td></tr>
288<tr><th>SSL_SERVER_M_SERIAL:</th><td> The serial number of the server's certificate.</td></tr>
289<tr><th>SSL_SERVER_M_VERSION:</th><td> The version of the server's certificate.</td></tr>
290<tr><th>SSL_SERVER_A_SIG:</th><td> The algorithm used for the signature in server's certificate.</td></tr>
291<tr><th>SSL_SERVER_A_KEY:</th><td> The public key algorithm in server's certificate.</td></tr>
292<tr><th>SSL_SERVER_CERT:</th><td> The PEM-encoded server certificate</td></tr>
293<tr><th>SSL_SERVER_CERT_TYPE:</th><td> The certificate type can be X.509 or
294OPENPGP.</td></tr>
295</table>
296 </div>
297
298 <div id="GnuTLSCache" class="apache_directive">
299 <h3>GnuTLSCache</h3>
300 <table class="directive">
301 <tr>
302 <th>Description:</th>
303 <td>Configure SSL Session Cache</td>
304 </tr>
305 <tr>
306 <th>Syntax:</th>
307 <td><code>GnuTLSCache <var>[dbm|gdbm|memcache|none]</var> <var>[path|server list|-]</var></code></td>
308 </tr>
309 <tr>
310 <th>Default:</th>
311 <td><code>dbm "conf/gnutls_cache"</code></td>
312 </tr>
313 <tr>
314 <th>Context:</th>
315 <td>
316 global config
317 </td>
318 </tr>
319 </table>
320 <p>This directive configures the SSL Session Cache for <code>mod_gnutls</code>.
321 This could be shared between machines of different architectures.
322 </p>
323 <dl>
324 <dt>dbm</dt>
325 <dd>
326 Uses the default Berkeley DB backend of APR DBM to cache SSL Sessions results. The argument is a relative or absolute path to be used
327 as the DBM Cache file. This is compatible with most operating systems.
328 </dd>
329
330 <dt>gdbm</dt>
331 <dd>
332 Uses the GDBM backend of APR DBM to cache SSL Sessions results. The argument is a relative or absolute path to be used
333 as the DBM Cache file.
334 </dd>
335
336 <dt>memcache</dt>
337 <dd>
338 Uses a <a href="http://www.danga.com/memcached/">memcached</a> server to cache the SSL Session.
339 The argument is a space separated list of servers. If no port number is supplied,
340 the default of 11211 is used. This can be used to share a session cache between all servers in a cluster.
341 </dd>
342
343 <dt>None</dt>
344 <dd>
345 Turns off all caching of SSL Sessions. This can significantly reduce the performance of <code>mod_gnutls</code>
346 since even followup connections by a client must renegotiate
347 parameters instead of reusing old ones.
348 </dd>
349 </dl>
350Example Usage:
351<pre class="example">GnuTLSCache memcache "10.0.0.1 10.0.0.2 10.0.0.3"</pre>
352 </div>
353
354 <div id="GnuTLSCacheTimeout" class="apache_directive">
355 <h3>GnuTLSCacheTimeout</h3>
356 <table class="directive">
357 <tr>
358 <th>Description:</th>
359 <td>Timeout for SSL Session Cache expiration.</td>
360 </tr>
361 <tr>
362 <th>Syntax:</th>
363 <td><code>GnuTLSCacheTimeout <var>seconds</var></code></td>
364 </tr>
365 <tr>
366 <th>Default:</th>
367 <td><code>300</code></td>
368 </tr>
369 <tr>
370 <th>Context:</th>
371 <td>
372 global config
373 </td>
374 </tr>
375 </table>
376 <p>
377 Sets the timeout for SSL Session Cache entries expiration. This directive
378 is valid even if Session Tickets are used, and indicates the
379 expiration time of the ticket.
380 </p>
381 </div>
382
383 <div id="GnuTLSSessionTickets" class="apache_directive">
384 <h3>GnuTLSSessionTickets</h3>
385 <table class="directive">
386 <tr>
387 <th>Description:</th>
388 <td>Enable Session Tickets for the server.</td>
389 </tr>
390 <tr>
391 <th>Syntax:</th>
392 <td><code>GnuTLSSessionTickets <var>[on|off]</var></code></td>
393 </tr>
394 <tr>
395 <th>Default:</th>
396 <td><code>off</code></td>
397 </tr>
398 <tr>
399 <th>Context:</th>
400 <td>
401 server config,
402 virtual host.
403 </td>
404 </tr>
405 </table>
406 <p>
407 To avoid storing data for TLS session resumption it is allowed
408 to provide client with a ticket, to use on return. Use for servers
409 with limited storage, and don't combine with GnuTLSCache. For a pool
410 of servers this option is not recommended since the tickets are
411 unique for the issuing server only.
412 </p>
413 </div>
414
415 <div id="GnuTLSCertificateFile" class="apache_directive">
416 <h3>GnuTLSCertificateFile</h3>
417 <table class="directive">
418 <tr>
419 <th>Description:</th>
420 <td>Set to the PEM Encoded Server Certificate.</td>
421 </tr>
422 <tr>
423 <th>Syntax:</th>
424 <td><code>GnuTLSCertificateFile <var>file-path</var></code></td>
425 </tr>
426 <tr>
427 <th>Default:</th>
428 <td><code>none</code></td>
429 </tr>
430 <tr>
431 <th>Context:</th>
432 <td>
433 server config,
434 virtual host.
435 </td>
436 </tr>
437 </table>
438 <p>Takes an absolute or relative path to a PEM Encoded Certificate to use as this Server's
439 Certificate.
440 </p>
441Example Usage:
442<pre class="example">GnuTLSCertificateFile conf/ssl/server.crt</pre>
443 </div>
444
445 <div id="GnuTLSPGPCertificateFile" class="apache_directive">
446 <h3>GnuTLSPGPCertificateFile</h3>
447 <table class="directive">
448 <tr>
449 <th>Description:</th>
450 <td>Set to a base64 Encoded Server OpenPGP Certificate.</td>
451 </tr>
452 <tr>
453 <th>Syntax:</th>
454 <td><code>GnuTLSPGPCertificateFile <var>file-path</var></code></td>
455 </tr>
456 <tr>
457 <th>Default:</th>
458 <td><code>none</code></td>
459 </tr>
460 <tr>
461 <th>Context:</th>
462 <td>
463 server config,
464 virtual host.
465 </td>
466 </tr>
467 </table>
468 <p>Takes an absolute or relative path to a base64 Encoded OpenPGP Certificate to use as this Server's
469 Certificate.
470 </p>
471Example Usage:
472<pre class="example">GnuTLSPGPCertificateFile conf/ssl/server.asc</pre>
473 </div>
474
475
476 <div id="GnuTLSClientVerify" class="apache_directive">
477 <h3>GnuTLSClientVerify</h3>
478 <table class="directive">
479 <tr>
480 <th>Description:</th>
481 <td>Enable Client Certificate Verification </td>
482 </tr>
483 <tr>
484 <th>Syntax:</th>
485 <td><code>GnuTLSClientVerify <var>[ignore|request|require|</var></code></td>
486 </tr>
487 <tr>
488 <th>Default:</th>
489 <td><code>ignore</code></td>
490 </tr>
491 <tr>
492 <th>Context:</th>
493 <td>
494 server config,
495 virtual host,
496 directory,
497 .htaccess
498 </td>
499 </tr>
500 </table>
501 <p>This directive controls the use of SSL Client Certificate Authentication. If used in the <code>.htaccess</code>
502 context, it can force TLS re-negotiation.
503 </p>
504 <dl>
505 <dt>ignore</dt>
506 <dd><code>mod_gnutls</code> will ignore the contents of any SSL Client Certificates sent.
507 It will not request that the client sends a certificate.
508 </dd>
509
510 <dt>request</dt>
511 <dd>The client certificate will be requested, but not required. The Certificate will be validated if sent. The output of the validation status will be stored in the <code>SSL_CLIENT_VERIFY</code> environment variable and can be "SUCCESS", "FAILED" or "NONE".</dd>
512
513 <dt>require</dt>
514 <dd>A Client certificate will be required. Any requests without a valid client certificate will be denied. The <code>SSL_CLIENT_VERIFY</code> environment variable will only be set to "SUCCESS".</dd>
515 </dl>
516 <pre class="example">&lt;Directory "/path/to/my/docroot"&gt;
517 GnuTLSClientVerify require
518&lt;/Directory&gt;</pre>
519 </div>
520
521 <div id="GnuTLSClientCAFile" class="apache_directive">
522 <h3>GnuTLSClientCAFile</h3>
523 <table class="directive">
524 <tr>
525 <th>Description:</th>
526 <td>Set to the PEM Encoded Certificate Authority Certificate.</td>
527 </tr>
528 <tr>
529 <th>Syntax:</th>
530 <td><code>GnuTLSClientCAFile <var>file-path</var></code></td>
531 </tr>
532 <tr>
533 <th>Default:</th>
534 <td><code>none</code></td>
535 </tr>
536 <tr>
537 <th>Context:</th>
538 <td>
539 server config,
540 virtual host.
541 </td>
542 </tr>
543 </table>
544 <p>Takes an absolute or relative path to a PEM Encoded Certificate to use as a Certificate Authority with Client Certificate Authentication. This file may contain a list of trusted authorities.
545 </p>
546Example Usage:
547<pre class="example">GnuTLSClientCAFile conf/ssl/ca.crt</pre>
548 </div>
549
550 <div id="GnuTLSPGPKeyringFile" class="apache_directive">
551 <h3>GnuTLSPGPKeyringFile</h3>
552 <table class="directive">
553 <tr>
554 <th>Description:</th>
555 <td>Set to a base64 Encoded key ring.</td>
556 </tr>
557 <tr>
558 <th>Syntax:</th>
559 <td><code>GnuTLSPGPKeyringFile <var>file-path</var></code></td>
560 </tr>
561 <tr>
562 <th>Default:</th>
563 <td><code>none</code></td>
564 </tr>
565 <tr>
566 <th>Context:</th>
567 <td>
568 server config,
569 virtual host.
570 </td>
571 </tr>
572 </table>
573 <p>Takes an absolute or relative path to a base64 Encoded Certificate
574 list (key ring) to use as a means of verification of Client
575 Certificates. This file should contain a list of trusted signers.
576 </p>
577Example Usage:
578<pre class="example">GnuTLSPGPKeyringFile conf/ssl/ring.asc</pre>
579 </div>
580
581 <div id="GnuTLSEnable" class="apache_directive">
582 <h3>GnuTLSEnable</h3>
583 <table class="directive">
584 <tr>
585 <th>Description:</th>
586 <td>Enable GnuTLS for this virtual host.</td>
587 </tr>
588 <tr>
589 <th>Syntax:</th>
590 <td><code>GnuTLSEnable <var>[on|off]</var></code></td>
591 </tr>
592 <tr>
593 <th>Default:</th>
594 <td><code>off</code></td>
595 </tr>
596 <tr>
597 <th>Context:</th>
598 <td>
599 virtual host
600 </td>
601 </tr>
602 </table>
603 <p>This directive enables SSL/TLS Encryption for a Virtual Host.
604 </p>
605<pre class="example">&lt;VirtualHost 1.2.3.4:443&gt;
606 GnuTLSEnable on
607 # other directives for the Virtual Host.
608&lt;/VirtualHost&gt;</pre>
609 </div>
610
611 <div id="GnuTLSExportCertificates" class="apache_directive">
612 <h3>GnuTLSExportCertificates</h3>
613 <table class="directive">
614 <tr>
615 <th>Description:</th>
616 <td>Export the PEM encoded certificates to CGIs.</td>
617 </tr>
618 <tr>
619 <th>Syntax:</th>
620 <td><code>GnuTLSExportCertificates <var>[on|off]</var></code></td>
621 </tr>
622 <tr>
623 <th>Default:</th>
624 <td><code>off</code></td>
625 </tr>
626 <tr>
627 <th>Context:</th>
628 <td>
629 virtual host
630 </td>
631 </tr>
632 </table>
633 <p>This directive enables exporting the full PEM encoded certificates of
634 the server and the client to CGIs. This makes <code>mod_gnutls</code> export exactly the same environment variables as <code>mod_ssl</code>.
635 </p>
636<pre class="example">&lt;VirtualHost 1.2.3.4:443&gt;
637 GnuTLSExportCertificates on
638 # other directives for the Virtual Host.
639&lt;/VirtualHost&gt;</pre>
640 </div>
641
642
643 <div id="GnuTLSKeyFile" class="apache_directive">
644 <h3>GnuTLSKeyFile</h3>
645 <table class="directive">
646 <tr>
647 <th>Description:</th>
648 <td>Set to the Server Private Key.</td>
649 </tr>
650 <tr>
651 <th>Syntax:</th>
652 <td><code>GnuTLSKeyFile <var>file-path</var></code></td>
653 </tr>
654 <tr>
655 <th>Default:</th>
656 <td><code>none</code></td>
657 </tr>
658 <tr>
659 <th>Context:</th>
660 <td>
661 server config,
662 virtual host.
663 </td>
664 </tr>
665 </table>
666 <p>Takes an absolute or relative path to the Server Private Key. This key cannot currently be password protected.
667 </p>
668Example Usage:
669<pre class="example">GnuTLSKeyFile conf/ssl/server.key</pre>
670 <div class="warning">
671 <strong>Security Warning</strong>: This private key must be protected. It is read while Apache is still running as root,
672 and does not need to be readable by the <code>nobody</code> or <code>apache</code> user.
673 </div>
674 </div>
675
676 <div id="GnuTLSPGPKeyFile" class="apache_directive">
677 <h3>GnuTLSPGPKeyFile</h3>
678 <table class="directive">
679 <tr>
680 <th>Description:</th>
681 <td>Set to the Server OpenPGP Secret Key.</td>
682 </tr>
683 <tr>
684 <th>Syntax:</th>
685 <td><code>GnuTLSPGPKeyFile <var>file-path</var></code></td>
686 </tr>
687 <tr>
688 <th>Default:</th>
689 <td><code>none</code></td>
690 </tr>
691 <tr>
692 <th>Context:</th>
693 <td>
694 server config,
695 virtual host.
696 </td>
697 </tr>
698 </table>
699 <p>Takes an absolute or relative path to the Server Private Key. This key cannot currently be password protected.
700 </p>
701Example Usage:
702<pre class="example">GnuTLSPGPKeyFile conf/ssl/server.asc</pre>
703 <div class="warning">
704 <strong>Security Warning</strong>: This private key must be protected. It is read while Apache is still running as root,
705 and does not need to be readable by the <code>nobody</code> or <code>apache</code> user.
706 </div>
707 </div>
708
709
710 <div id="GnuTLSDHFile" class="apache_directive">
711 <h3>GnuTLSDHFile</h3>
712 <table class="directive">
713 <tr>
714 <th>Description:</th>
715 <td>Set to the PKCS #3 encoded Diffie Hellman parameters.</td>
716 </tr>
717 <tr>
718 <th>Syntax:</th>
719 <td><code>GnuTLSDHFile <var>file-path</var></code></td>
720 </tr>
721 <tr>
722 <th>Default:</th>
723 <td><code>none</code></td>
724 </tr>
725 <tr>
726 <th>Context:</th>
727 <td>
728 server config,
729 virtual host.
730 </td>
731 </tr>
732 </table>
733 <p>Takes an absolute or relative path to a PKCS #3 encoded DH parameters. Those are used when the DHE key exchange method is enabled. You can generate this file using
734 "certtool --generate-dh-params --bits 2048". If not set <code>mod_gnutls</code> will use the included parameters.
735 </p>
736Example Usage:
737<pre class="example">GnuTLSDHFile conf/ssl/dhparams</pre>
738 </div>
739
740 <div id="GnuTLSRSAFile" class="apache_directive">
741 <h3>GnuTLSRSAFile</h3>
742 <table class="directive">
743 <tr>
744 <th>Description:</th>
745 <td>Set to the PKCS #1 encoded RSA parameters for 'EXPORT' ciphersuites.</td>
746 </tr>
747 <tr>
748 <th>Syntax:</th>
749 <td><code>GnuTLSRSAFile <var>file-path</var></code></td>
750 </tr>
751 <tr>
752 <th>Default:</th>
753 <td><code>none</code></td>
754 </tr>
755 <tr>
756 <th>Context:</th>
757 <td>
758 server config,
759 virtual host.
760 </td>
761 </tr>
762 </table>
763 <p>Takes an absolute or relative path to a PKCS #1 encoded RSA parameters. Those are used when the RSA-EXPORT key exchange method is enabled. You can generate this file using "certtool --generate-privkey --bits 512". These parameters should not contain key of longer of 512 bits (due to the export restrictions). If not set <code>mod_gnutls</code> will not negotiate the 'EXPORT' ciphersuites. It is recommended not to enable those ciphersuites. If you do make sure you regenerate this file at every few hours.
764 </p>
765Example Usage:
766<pre class="example">GnuTLSRSAFile conf/ssl/rsaparams</pre>
767 </div>
768
769 <div id="GnuTLSSRPPasswdFile" class="apache_directive">
770 <h3>GnuTLSSRPPasswdFile</h3>
771 <table class="directive">
772 <tr>
773 <th>Description:</th>
774 <td>Set to the SRP password file for SRP ciphersuites.</td>
775 </tr>
776 <tr>
777 <th>Syntax:</th>
778 <td><code>GnuTLSSRPPasswdFile <var>file-path</var></code></td>
779 </tr>
780 <tr>
781 <th>Default:</th>
782 <td><code>none</code></td>
783 </tr>
784 <tr>
785 <th>Context:</th>
786 <td>
787 server config,
788 virtual host.
789 </td>
790 </tr>
791 </table>
792 <p>Takes an absolute or relative path to an SRP password file. This is the same format as used in libsrp. 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. This password file holds the username, a password verifier and the dependency to the SRP parameters.
793 </p>
794Example Usage:
795<pre class="example">GnuTLSSRPPasswdFile conf/ssl/tpasswd</pre>
796 </div>
797
798 <div id="GnuTLSSRPPasswdConfFile" class="apache_directive">
799 <h3>GnuTLSSRPPasswdConfFile</h3>
800 <table class="directive">
801 <tr>
802 <th>Description:</th>
803 <td>Set to the SRP password.conf file for SRP ciphersuites.</td>
804 </tr>
805 <tr>
806 <th>Syntax:</th>
807 <td><code>GnuTLSSRPPasswdConfFile <var>file-path</var></code></td>
808 </tr>
809 <tr>
810 <th>Default:</th>
811 <td><code>none</code></td>
812 </tr>
813 <tr>
814 <th>Context:</th>
815 <td>
816 server config,
817 virtual host.
818 </td>
819 </tr>
820 </table>
821 <p>Takes an absolute or relative path to an SRP password.conf file. This is the same format as used in libsrp. You can generate such file using the command "srptool --create-conf /etc/tpasswd.conf". This file holds the SRP parameters and is associate with the password file (the verifiers depends on these parameters).
822 </p>
823Example Usage:
824<pre class="example">GnuTLSSRPPasswdConfFile conf/ssl/tpasswd.conf</pre>
825 </div>
826
827 <div id="GnuTLSPriorities" class="apache_directive">
828 <h3>GnuTLSPriorities</h3>
829 <table class="directive">
830 <tr>
831 <th>Description:</th>
832 <td>Set the allowed ciphers, key exchange algorithms, MACs and
833 compression methods.</td>
834 </tr>
835 <tr>
836 <th>Syntax:</th>
837 <td><code>GnuTLSPriorities <var>+cipher0:+cipher1:...:+cipherN</var></code></td>
838 </tr>
839 <tr>
840 <th>Default:</th>
841 <td><code>none</code></td>
842 </tr>
843 <tr>
844 <th>Context:</th>
845 <td>
846 server config,
847 virtual host.
848 </td>
849 </tr>
850 </table>
851 <p>Takes a semi-colon separated list of ciphers, key exchange methods
852 Message authentication codes and compression methods to enable. The
853 allowed keywords are specified in the <code>gnutls_priority_init()</code>
854 function of <code>GnuTLS</code>. It's documentation can be found at
855 <a
856 href="http://www.gnu.org/software/gnutls/manual/html_node/Core-functions.html#Core-functions">Core
857 GnuTLS functions.</a>
858 </p><p>
859 In brief you can specify a set of ciphersuites from the choices:
860 <ul>
861 <li>NONE: The empty list.</li>
862 <li>EXPORT: A list with all the supported cipher combinations
863 including the "EXPORT" strength algorithms.</li>
864 <li>PERFORMANCE: A list with all the secure cipher combinations
865 sorted in terms of performance.</li>
866 <li>NORMAL: A list with all the secure cipher combinations
867 sorted with respect to security margin (subjective term).</li>
868 <li>SECURE: A list with all the secure cipher combinations including the
869 256-bit ciphers sorted with respect to security margin.</li>
870 </ul>
871 Additionally you can add or remove algorithms using the "+" and "!"
872 prefixes respectively. That is in order to disable the ARCFOUR cipher
873 from the "NORMAL" set you can use the string
874 <code>NORMAL:!ARCFOUR-128</code>. Other options such as the protocol
875 version and the compression method can be specified using the
876 <code>VERS-</code> and <code>COMP-</code> prefixes. So in order to
877 remove or add a specific TLS version from the "NORMAL" set use
878 <code>NORMAL:!VERS-SSL3.0</code>. To enable
879 zlib compression use <code>NORMAL:+COMP-DEFLATE</code>.
880 However it is recommended not to add compression at this level.
881 With the "NONE" set, in order to be usable, you have to specify a complete
882 set of combinations of protocol versions, cipher algorithms
883 (AES-128-CBC), key exchange algorithms (RSA), message authentication
884 codes (SHA1) and compression methods (COMP-NULL).
885 </p><p>
886 All the supported algorithms are:
887 <ul>
888 <li>Ciphers: AES-256-CBC, AES-128-CBC, CAMELLIA-256-CBC,
889 CAMELLIA-128-CBC, ARCFOUR-128, 3DES-CBC, ARCFOUR-40</li>
890 <li>Key exchange methods: RSA, DHE-RSA, DHE-DSS, SRP, SRP-RSA,
891 SRP-DSS, ANON-DH</li>
892 <li>Message authentication codes: SHA1, MD5</li>
893 <li>Compression methods: COMP-DEFLATE, COMP-NULL</li>
894 <li>Protocol versions: VERS-TLS1.1, VERS-TLS1.0, VERS-SSL3.0</li>
895 </ul>
896 </p>
897 <p>The special keyword "%COMPAT" will disable some security features
898 such as protection against statistical attacks to ciphertext data in
899 order to achieve maximum compatibility (some broken mobile clients need
900 this).
901 </p>
902Example Usage:
903<pre class="example">GnuTLSPriorities NORMAL:!AES-256-CBC:!DHE-RSA</pre>
904<pre class="example">GnuTLSPriorities EXPORT:!VERS-TLS1.0:+COMP-DEFLATE:+CTYPE-OPENPGP</pre>
905<pre class="example">GnuTLSPriorities NONE:+VERS-TLS1.0:+AES-128-CBC:+RSA:+SHA1:+COMP-NULL</pre>
906<pre class="example">GnuTLSPriorities NORMAL:+COMP-DEFLATE</pre>
907<pre class="example">GnuTLSPriorities NORMAL:%COMPAT</pre>
908<pre class="example">GnuTLSPriorities NORMAL:+ANON-DH</pre>
909</div>
910
911 </div>
912 </content>
913 </section>
914</ooo>
915
generated by cgit (git 2.34.1) at 2024-11-24 02:11:36 +0000