Context Navigation

mod_gnutls_manual-0.1.html @ 480aba1

Visit:

asynciodebian/masterdebian/stretch-backportsjessie-backportsmsvaproxy-ticketupstream

Last change on this file since 480aba1 was 480aba1, checked in by Daniel Kahn Gillmor <dkg@…>, 8 years ago

correct context terminology for GnuTLSCache configurations

"global config" is not one of the four standard directive contexts as
seen at:

https://httpd.apache.org/docs/2.2/mod/directive-dict.html#Context

The intent was clearly "server config"

Property mode set to 100644

File size: 32.6 KB

Line
1	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2	<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
3	<head>
4	<title>mod_gnutls Manual 0.1</title>
5	<meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
6	<style type="text/css" media="all">
7	h1{text-align:center;}
8	p{margin-left:2%;}
9	code{color:#000000;background-color:cyan;}
10	h4{text-align:center;color:#000000;background-color:cyan;width:100%;}
11	.directive{margin-left:5%;margin-right:5%;border:#000000 solid 1px;}
12	h5{display:inline;margin-right:10%;}
13	.warn{color:inherit;background-color:#FF0000}
14	h6{margin-left:2%;font-weight:bold;display:inline;}
15	</style>
16	</head>
17	<body>
18	<h1>mod_gnutls Manual 0.1<br /><small>July 2011</small></h1>
19	<hr />
20	<div id="Contents">
21	<h2>Contents</h2>
22	<ol>
23	<li>Compilation & Installation</li>
24	<li>Integration</li>
25	<li>Configuration Directives<br />
26	<ul>
27	<li>GnuTLSCache</li>
28	<li>GnuTLSCacheTimeout</li>
29	<li>GnuTLSSessionTickets</li>
30	<li>GnuTLSCertificateFile</li>
31	<li>GnuTLSKeyFile</li>
32	<li>GnuTLSPGPCertificateFile</li>
33	<li>GnuTLSPGPKeyFile</li>
34	<li>GnuTLSClientVerify</li>
35	<li>GnuTLSClientCAFile</li>
36	<li>GnuTLSPGPKeyringFile</li>
37	<li>GnuTLSEnable</li>
38	<li>GnuTLSDHFile</li>
39	<li>GnuTLSRSAFile</li>
40	<li>GnuTLSSRPPasswdFile</li>
41	<li>GnuTLSSRPPasswdConfFile</li>
42	<li>GnuTLSPriorities</li>
43	<li>GnuTLSExportCertificates</li>
44	</ul>
45	</li>
46	<li>Configuration Examples<br />
47	<ul>
48	<li>Simple Standard SSL Example</li>
49	<li>Server Name Indication Example</li>
50	</ul>
51	</li>
52	<li>Performance Issues</li>
53	<li>Environment Variables</li>
54	<li>Credits</li>
55	</ol>
56	</div>
57	<hr />
58	<div id="Installation">
59	<h2>Compilation & 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>

Note: See TracBrowser for help on using the repository browser.

Context Navigation

source: mod_gnutls/docs/mod_gnutls_manual-0.1.html @ 480aba1

Download in other formats: