Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_ssl_module.xml @ 384:331a86bc51ff

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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>