Mercurial > hg > nginx-site
comparison xml/en/docs/http/ngx_http_ssl_module.xml @ 384:331a86bc51ff
English translation of ngx_http_ssl_module.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Wed, 01 Feb 2012 06:00:57 +0000 |
parents | |
children | b83d332fbdaa |
comparison
equal
deleted
inserted
replaced
383:a73fa21add8a | 384:331a86bc51ff |
---|---|
1 <?xml version="1.0"?> | |
2 | |
3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> | |
4 | |
5 <module name="Module ngx_http_ssl_module" | |
6 link="/en/docs/http/ngx_http_ssl_module.html" | |
7 lang="en"> | |
8 | |
9 <section id="summary"> | |
10 | |
11 <para> | |
12 The <literal>ngx_http_ssl_module</literal> module provides the | |
13 necessary support for HTTPS. | |
14 </para> | |
15 | |
16 <para> | |
17 This module is not built by default, it should be enabled with the | |
18 <literal>--with-http_ssl_module</literal> | |
19 configuration parameter. | |
20 <note> | |
21 This module requires the | |
22 <link url="http://www.openssl.org">OpenSSL</link> library. | |
23 </note> | |
24 </para> | |
25 | |
26 </section> | |
27 | |
28 | |
29 <section id="example" name="Example Configuration"> | |
30 | |
31 <para> | |
32 To reduce the processor load it is recommended to | |
33 <list type="bullet"> | |
34 | |
35 <listitem> | |
36 set the number of worker processes equal to the number of processors, | |
37 </listitem> | |
38 | |
39 <listitem> | |
40 enable keep-alive connections, | |
41 </listitem> | |
42 | |
43 <listitem> | |
44 enable shared session cache, | |
45 </listitem> | |
46 | |
47 <listitem> | |
48 disable built-in session cache, | |
49 </listitem> | |
50 | |
51 <listitem> | |
52 and possibly increase the session lifetime (by default, 5 minutes): | |
53 </listitem> | |
54 | |
55 </list> | |
56 | |
57 <example> | |
58 <emphasis>worker_processes 2;</emphasis> | |
59 | |
60 http { | |
61 | |
62 ... | |
63 | |
64 server { | |
65 listen 443; | |
66 <emphasis>keepalive_timeout 70;</emphasis> | |
67 | |
68 ssl on; | |
69 ssl_protocols SSLv3 TLSv1 TLSv1.1 TLSv1.2; | |
70 ssl_ciphers AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5; | |
71 ssl_certificate /usr/local/nginx/conf/cert.pem; | |
72 ssl_certificate_key /usr/local/nginx/conf/cert.key; | |
73 <emphasis>ssl_session_cache shared:SSL:10m;</emphasis> | |
74 <emphasis>ssl_session_timeout 10m;</emphasis> | |
75 | |
76 ... | |
77 } | |
78 </example> | |
79 </para> | |
80 | |
81 </section> | |
82 | |
83 | |
84 <section id="directives" name="Directives"> | |
85 | |
86 <directive name="ssl"> | |
87 <syntax><literal>on</literal> | <literal>off</literal></syntax> | |
88 <default>off</default> | |
89 <context>http</context> | |
90 <context>server</context> | |
91 | |
92 <para> | |
93 Enables the HTTPS protocol for the given virtual server. | |
94 </para> | |
95 | |
96 </directive> | |
97 | |
98 | |
99 <directive name="ssl_certificate"> | |
100 <syntax><value>file</value></syntax> | |
101 <default/> | |
102 <context>http</context> | |
103 <context>server</context> | |
104 | |
105 <para> | |
106 Specifies a file with a certificate in the PEM format | |
107 for the given virtual server. | |
108 If intermediate certificates should be specified in addition | |
109 to a primary certificate, they should be specified in the same file | |
110 in the following order: the primary certificate comes first, then | |
111 the intermediate certificates. | |
112 A secret key in the PEM format may be placed in the same file. | |
113 </para> | |
114 | |
115 <para> | |
116 It should be kept in mind that due to the HTTPS protocol limitations | |
117 virtual servers should listen on different IP addresses: | |
118 <example> | |
119 server { | |
120 listen 192.168.1.1:443; | |
121 server_name one.example.com; | |
122 ssl_certificate /usr/local/nginx/conf/one.example.com.cert; | |
123 ... | |
124 } | |
125 | |
126 server { | |
127 listen 192.168.1.2:443; | |
128 server_name two.example.com; | |
129 ssl_certificate /usr/local/nginx/conf/two.example.com.cert; | |
130 ... | |
131 } | |
132 </example> | |
133 otherwise | |
134 <link doc="configuring_https_servers.xml" | |
135 id="name_based_https_servers">the first server’s certificate</link> | |
136 will be issued for the second site. | |
137 </para> | |
138 | |
139 </directive> | |
140 | |
141 | |
142 <directive name="ssl_certificate_key"> | |
143 <syntax><value>file</value></syntax> | |
144 <default/> | |
145 <context>http</context> | |
146 <context>server</context> | |
147 | |
148 <para> | |
149 Specifies a file with a secret key in the PEM format | |
150 for the given virtual server. | |
151 </para> | |
152 | |
153 </directive> | |
154 | |
155 | |
156 <directive name="ssl_ciphers"> | |
157 <syntax><value>ciphers</value></syntax> | |
158 <default>HIGH:!ADH:!MD5</default> | |
159 <context>http</context> | |
160 <context>server</context> | |
161 | |
162 <para> | |
163 Specifies the enabled ciphers. | |
164 The ciphers are specified in the format understood by the | |
165 OpenSSL library, for example: | |
166 <example> | |
167 ssl_ciphers ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP; | |
168 </example> | |
169 </para> | |
170 | |
171 <para> | |
172 The full list can be viewed using the | |
173 “<command>openssl ciphers</command>” command. | |
174 </para> | |
175 | |
176 </directive> | |
177 | |
178 | |
179 <directive name="ssl_client_certificate"> | |
180 <syntax><value>file</value></syntax> | |
181 <default/> | |
182 <context>http</context> | |
183 <context>server</context> | |
184 | |
185 <para> | |
186 Specifies a file with CA certificates in the PEM format | |
187 used for client certificate verification. | |
188 </para> | |
189 | |
190 </directive> | |
191 | |
192 | |
193 <directive name="ssl_crl"> | |
194 <syntax><value>file</value></syntax> | |
195 <default/> | |
196 <context>http</context> | |
197 <context>server</context> | |
198 <appeared-in>0.8.7</appeared-in> | |
199 | |
200 <para> | |
201 Specifies a file with revoked certificates (CRL) | |
202 in the PEM format, used to client certificate verification. | |
203 </para> | |
204 | |
205 </directive> | |
206 | |
207 | |
208 <directive name="ssl_dhparam"> | |
209 <syntax><value>file</value></syntax> | |
210 <default/> | |
211 <context>http</context> | |
212 <context>server</context> | |
213 <appeared-in>0.7.2</appeared-in> | |
214 | |
215 <para> | |
216 Specifies a file with DH parameters for EDH ciphers. | |
217 </para> | |
218 | |
219 </directive> | |
220 | |
221 | |
222 <directive name="ssl_prefer_server_ciphers"> | |
223 <syntax><literal>on</literal> | <literal>off</literal></syntax> | |
224 <default>off</default> | |
225 <context>http</context> | |
226 <context>server</context> | |
227 | |
228 <para> | |
229 Specifies that server ciphers should be preferred over client | |
230 ciphers when using the SSLv3 and TLS protocols. | |
231 </para> | |
232 | |
233 </directive> | |
234 | |
235 | |
236 <directive name="ssl_protocols"> | |
237 <syntax> | |
238 [<literal>SSLv2</literal>] | |
239 [<literal>SSLv3</literal>] | |
240 [<literal>TLSv1</literal>] | |
241 [<literal>TLSv1.1</literal>] | |
242 [<literal>TLSv1.2</literal>]</syntax> | |
243 <default>SSLv3 TLSv1 TLSv1.1 TLSv1.2</default> | |
244 <context>http</context> | |
245 <context>server</context> | |
246 | |
247 <para> | |
248 Enables the specified protocols. | |
249 The parameters <literal>TLSv1.1</literal> and <literal>TLSv1.2</literal> work | |
250 only when using the OpenSSL library version 1.0.1 and higher. | |
251 <note> | |
252 The parameters <literal>TLSv1.1</literal> and <literal>TLSv1.2</literal> are | |
253 supported starting from version 1.1.13 so when using OpenSSL version 1.0.1 | |
254 and higher on older nginx versions these protocols will work but could not | |
255 be disabled. | |
256 </note> | |
257 </para> | |
258 | |
259 </directive> | |
260 | |
261 | |
262 <directive name="ssl_session_cache"> | |
263 <syntax> | |
264 <literal>off</literal> | | |
265 <literal>none</literal> | | |
266 [<literal>builtin</literal>[:<value>size</value>]] | |
267 [<literal>shared</literal>:<value>name</value>:<value>size</value>]</syntax> | |
268 <default>none</default> | |
269 <context>http</context> | |
270 <context>server</context> | |
271 | |
272 <para> | |
273 Sets types and sizes of caches that store session parameters. | |
274 A cache can be any of the following types: | |
275 <list type="tag"> | |
276 | |
277 <tag-name><literal>off</literal></tag-name> | |
278 <tag-desc> | |
279 the use of session cache is strictly prohibited: | |
280 nginx explicitly tells a client that sessions may not be reused. | |
281 </tag-desc> | |
282 | |
283 <tag-name><literal>none</literal></tag-name> | |
284 <tag-desc> | |
285 the use of session cache is gently disallowed: | |
286 nginx tells a client that sessions may be reused, but does not | |
287 actually do that. | |
288 </tag-desc> | |
289 | |
290 <tag-name><literal>builtin</literal></tag-name> | |
291 <tag-desc> | |
292 a cache built in OpenSSL; used by one worker process only. | |
293 The cache size is specified in sessions. | |
294 If size is not given, it is equal to 20480 sessions. | |
295 Use of the built-in cache can cause memory fragmentation. | |
296 </tag-desc> | |
297 | |
298 <tag-name><literal>shared</literal></tag-name> | |
299 <tag-desc> | |
300 shared between all worker processes. | |
301 The cache size is specified in bytes; one megabyte can store | |
302 about 4000 sessions. | |
303 Each shared cache should have an arbitrary name. | |
304 A cache with the same name can be used in several virtual servers. | |
305 </tag-desc> | |
306 | |
307 </list> | |
308 </para> | |
309 | |
310 <para> | |
311 Both cache types can be used simultaneously, for example: | |
312 <example> | |
313 ssl_session_cache builtin:1000 shared:SSL:10m; | |
314 </example> | |
315 but using only shared cache without the built-in cache should | |
316 be more efficient. | |
317 </para> | |
318 | |
319 </directive> | |
320 | |
321 | |
322 <directive name="ssl_session_timeout"> | |
323 <syntax><value>time</value></syntax> | |
324 <default>5m</default> | |
325 <context>http</context> | |
326 <context>server</context> | |
327 | |
328 <para> | |
329 Specifies a time during which a client may reuse the | |
330 session parameters stored in a cache. | |
331 </para> | |
332 | |
333 </directive> | |
334 | |
335 | |
336 <directive name="ssl_verify_client"> | |
337 <syntax> | |
338 <literal>on</literal> | <literal>off</literal> | | |
339 <literal>optional</literal></syntax> | |
340 <default>off</default> | |
341 <context>http</context> | |
342 <context>server</context> | |
343 | |
344 <para> | |
345 Enables the client certificate verification. | |
346 The <literal>optional</literal> parameter (0.8.7+) requests the client | |
347 certificate and verifies it if it was present. | |
348 The result of verification is stored in the | |
349 <var>$ssl_client_verify</var> variable. | |
350 </para> | |
351 | |
352 </directive> | |
353 | |
354 | |
355 <directive name="ssl_verify_depth"> | |
356 <syntax><value>number</value></syntax> | |
357 <default>1</default> | |
358 <context>http</context> | |
359 <context>server</context> | |
360 | |
361 <para> | |
362 Sets a verification depth in the client certificates chain. | |
363 </para> | |
364 | |
365 </directive> | |
366 | |
367 </section> | |
368 | |
369 | |
370 <section id="errors" name="Error Processing"> | |
371 | |
372 <para> | |
373 The <literal>ngx_http_ssl_module</literal> module supports several | |
374 non-standard error codes that can be used for redirects using the | |
375 <link doc="ngx_http_core_module.xml" id="error_page"/> directive: | |
376 <list type="tag"> | |
377 | |
378 <tag-name>495</tag-name> | |
379 <tag-desc> | |
380 an error has occurred during the client certificate verification; | |
381 </tag-desc> | |
382 | |
383 <tag-name>496</tag-name> | |
384 <tag-desc> | |
385 a client did not present the required certificate; | |
386 </tag-desc> | |
387 | |
388 <tag-name>497</tag-name> | |
389 <tag-desc> | |
390 a regular request was sent to the HTTPS port. | |
391 </tag-desc> | |
392 | |
393 </list> | |
394 </para> | |
395 | |
396 <para> | |
397 A redirection happens after the request was fully parsed and | |
398 variables such as <var>$request_uri</var>, | |
399 <var>$uri</var>, <var>$args</var> and others were made available. | |
400 </para> | |
401 | |
402 </section> | |
403 | |
404 | |
405 <section id="variables" name="Embedded Variables"> | |
406 | |
407 <para> | |
408 The <literal>ngx_http_ssl_module</literal> module supports | |
409 several embedded variables: | |
410 <list type="tag"> | |
411 | |
412 <tag-name><var>$ssl_cipher</var></tag-name> | |
413 <tag-desc> | |
414 returns the string of ciphers used | |
415 for an established SSL connection; | |
416 </tag-desc> | |
417 | |
418 <tag-name><var>$ssl_client_cert</var></tag-name> | |
419 <tag-desc> | |
420 returns the client certificate in the PEM format | |
421 for an established SSL connection, with each line except the first | |
422 prepended with the tab character; | |
423 this is intended for the use in the | |
424 <link doc="ngx_http_proxy_module.xml" id="proxy_set_header"/> directive; | |
425 </tag-desc> | |
426 | |
427 <tag-name><var>$ssl_client_raw_cert</var></tag-name> | |
428 <tag-desc> | |
429 returns the client certificate in the PEM format | |
430 for an established SSL connection; | |
431 </tag-desc> | |
432 | |
433 <tag-name><var>$ssl_client_serial</var></tag-name> | |
434 <tag-desc> | |
435 returns the serial number of the client certificate | |
436 for an established SSL connection; | |
437 </tag-desc> | |
438 | |
439 <tag-name><var>$ssl_client_s_dn</var></tag-name> | |
440 <tag-desc> | |
441 returns the “subject DN” string of the client certificate | |
442 for an established SSL connection; | |
443 </tag-desc> | |
444 | |
445 <tag-name><var>$ssl_client_i_dn</var></tag-name> | |
446 <tag-desc> | |
447 returns the “issuer DN” string of the client certificate | |
448 for an established SSL connection; | |
449 </tag-desc> | |
450 | |
451 <tag-name><var>$ssl_client_verify</var></tag-name> | |
452 <tag-desc> | |
453 returns the result of client certificate verification: | |
454 “<literal>SUCCESS</literal>”, “<literal>FAILED</literal>”, and | |
455 “<literal>NONE</literal>” if a certificate was not present; | |
456 </tag-desc> | |
457 | |
458 <tag-name><var>$ssl_protocol</var></tag-name> | |
459 <tag-desc> | |
460 returns the protocol of an established SSL connection; | |
461 </tag-desc> | |
462 | |
463 <tag-name><var>$ssl_session_id</var></tag-name> | |
464 <tag-desc> | |
465 returns the session identifier of an established SSL connection. | |
466 </tag-desc> | |
467 | |
468 </list> | |
469 </para> | |
470 | |
471 </section> | |
472 | |
473 </module> |