Mercurial > hg > nginx-site
comparison xml/ru/docs/http/ngx_http_ssl_module.xml @ 76:4a4caa566120
Russian documentation import.
Changes in module.dtd: <example> now allowed to contain <value> and
<emphasis> elements (we need this to show important parts in examples),
less strict checking of <directive> syntax (we don't want to fully
document some directives, notably deprecated ones).
Known issues:
1. <syntax> elements are preserved as is, they will require manual conversion
(likely to some not-yet-existed format a la DocBook cmdsynopsis, as
currently used one seems to be incomplete);
2. <value> no longer corresponds to replaceable content, and it's use in
examples isn't correct;
3. <link doc="document#fragment"> doesn't work with current xslt, either
should be supported or changed to <link doc="document" id="fragment">.
The following files are intentionally omitted: maillists.xml (support.xml
should be used instead), experimental.xml (obsolete), faq.xml (conflicts
with existing one, needs discussion).
Not yet linked to site.
author | Maxim Dounin <mdounin@mdounin.ru> |
---|---|
date | Tue, 11 Oct 2011 12:57:50 +0000 |
parents | |
children | 0a45870d0160 |
comparison
equal
deleted
inserted
replaced
75:2bf4cd2787c5 | 76:4a4caa566120 |
---|---|
1 <?xml version="1.0" encoding="utf-8"?> | |
2 | |
3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> | |
4 | |
5 <module name="Директивы модуля ngx_http_ssl_module" | |
6 link="/ru/docs/http/ngx_http_ssl_module.html" | |
7 lang="ru"> | |
8 | |
9 <section name="" id="summary"> | |
10 | |
11 <para> | |
12 Модуль ngx_http_ssl_module обеспечивает работу по протоколу HTTPS. | |
13 Поддерживается проверка сертификатов клиентов с ограничением — | |
14 если в файле, заданном директивой <link id="ssl_certificate"/>, | |
15 указана цепочка сертификатов, то при проверке клиентских сертификатов | |
16 nginx также будет использовать и сертификаты этих промежуточных CA. | |
17 </para> | |
18 | |
19 <para> | |
20 По умолчанию модуль не собирается, нужно разрешить его сборку | |
21 при конфигурировании параметром | |
22 <command>--with-http_ssl_module</command>. | |
23 Для сборки и работы этого модуля нужна библиотека | |
24 <link url="http://www.openssl.org">OpenSSL</link>. | |
25 </para> | |
26 | |
27 </section> | |
28 | |
29 | |
30 <section name="Пример конфигурации" id="example"> | |
31 | |
32 <para> | |
33 Для уменьшения загрузки процессора рекомендуется | |
34 <list type="bullet"> | |
35 | |
36 <listitem> | |
37 установить число рабочих процессов равным числу процессоров, | |
38 </listitem> | |
39 | |
40 <listitem> | |
41 разрешить keep-alive соединения, | |
42 </listitem> | |
43 | |
44 <listitem> | |
45 включить разделяемый кэш сессий, | |
46 </listitem> | |
47 | |
48 <listitem> | |
49 выключить встроенный кэш сессий | |
50 </listitem> | |
51 | |
52 <listitem> | |
53 и, возможно, увеличить время жизни сессии (по умолчанию 5 минут): | |
54 </listitem> | |
55 | |
56 </list> | |
57 | |
58 <example> | |
59 <emphasis>worker_processes 2;</emphasis> | |
60 | |
61 http { | |
62 | |
63 ... | |
64 | |
65 server { | |
66 listen 443; | |
67 <emphasis>keepalive_timeout 70;</emphasis> | |
68 | |
69 ssl on; | |
70 ssl_protocols SSLv3 TLSv1; | |
71 ssl_ciphers AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5; | |
72 ssl_certificate /usr/local/nginx/conf/cert.pem; | |
73 ssl_certificate_key /usr/local/nginx/conf/cert.key; | |
74 <emphasis>ssl_session_cache shared:SSL:10m;</emphasis> | |
75 <emphasis>ssl_session_timeout 10m;</emphasis> | |
76 | |
77 ... | |
78 } | |
79 </example> | |
80 </para> | |
81 | |
82 </section> | |
83 | |
84 | |
85 <section name="Директивы" id="directives"> | |
86 | |
87 <directive name="ssl"> | |
88 <syntax>ssl <value>[on|off]</value></syntax> | |
89 <default>ssl off</default> | |
90 <context>http, server</context> | |
91 | |
92 <para> | |
93 Директива разрешает протокол HTTPS для данного виртуального сервера. | |
94 </para> | |
95 | |
96 </directive> | |
97 | |
98 | |
99 <directive name="ssl_certificate"> | |
100 <syntax>ssl_certificate <value>файл</value></syntax> | |
101 <default>нет</default> | |
102 <context>http, server</context> | |
103 | |
104 <para> | |
105 Директива указывает файл с сертификатом в формате PEM | |
106 для данного виртуального сервера. | |
107 Если вместе с основным сертификатом нужно указать промежуточные, | |
108 то они должны находиться в этом же файле в следующем порядке — сначала | |
109 основной сертификат, а затем промежуточные. | |
110 В этом же файле может находиться секретный ключ в формате PEM. | |
111 </para> | |
112 | |
113 <para> | |
114 Нужно иметь ввиду, что из-за ограничения протокола HTTPS | |
115 виртуальные сервера должны слушать на разных IP-адресах: | |
116 <example> | |
117 server { | |
118 listen 192.168.1.1:443; | |
119 server_name one.example.com; | |
120 ssl_certificate /usr/local/nginx/conf/one.example.com.cert; | |
121 ... | |
122 } | |
123 | |
124 server { | |
125 listen 192.168.1.2:443; | |
126 server_name two.example.com; | |
127 ssl_certificate /usr/local/nginx/conf/two.example.com.cert; | |
128 ... | |
129 } | |
130 </example> | |
131 иначе для второго сайта будет выдаваться | |
132 <link doc="../faq.xml#name_based_vhost_ssl">сертификат | |
133 первого сервера</link>. | |
134 </para> | |
135 | |
136 </directive> | |
137 | |
138 | |
139 <directive name="ssl_certificate_key"> | |
140 <syntax>ssl_certificate_key <value>файл</value></syntax> | |
141 <default>нет</default> | |
142 <context>http, server</context> | |
143 | |
144 <para> | |
145 Директива указывает файл с секретным ключом в формате PEM | |
146 для данного виртуального сервера. | |
147 </para> | |
148 | |
149 </directive> | |
150 | |
151 | |
152 <directive name="ssl_client_certificate"> | |
153 <syntax>ssl_client_certificate <value>файл</value></syntax> | |
154 <default>нет</default> | |
155 <context>http, server</context> | |
156 | |
157 <para> | |
158 Директива указывает файл с сертификатами CA в формате PEM, используемыми для | |
159 для проверки клиентских сертификатов. | |
160 </para> | |
161 | |
162 </directive> | |
163 | |
164 | |
165 <directive name="ssl_ciphers"> | |
166 <syntax>ssl_ciphers <value>шифры</value></syntax> | |
167 <default>ssl_ciphers HIGH:!ADH:!MD5</default> | |
168 <context>http, server</context> | |
169 | |
170 <para> | |
171 Директива описывает разрешённые шифры. | |
172 Шифры задаются в формате, поддерживаемом библиотекой | |
173 OpenSSL, например: | |
174 <example> | |
175 ssl_ciphers ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP; | |
176 </example> | |
177 </para> | |
178 | |
179 <para> | |
180 Полный список можно посмотреть с помощью команды | |
181 <command>openssl ciphers</command>. | |
182 </para> | |
183 | |
184 </directive> | |
185 | |
186 | |
187 <directive name="ssl_crl"> | |
188 <syntax>ssl_crl <value>файл</value></syntax> | |
189 <default>нет</default> | |
190 <context>http, server</context> | |
191 | |
192 <para> | |
193 Директива (0.8.7) указывает файл с отозванными сертификатами (CRL) | |
194 в формате PEM, используемыми для для проверки клиентских сертификатов. | |
195 </para> | |
196 | |
197 </directive> | |
198 | |
199 | |
200 <directive name="ssl_dhparam"> | |
201 <syntax>ssl_dhparam <value>файл</value></syntax> | |
202 <default>нет</default> | |
203 <context>http, server</context> | |
204 | |
205 <para> | |
206 Директива (0.7.2) указывает файл с параметрами для шифров с обменом EDH-ключами. | |
207 </para> | |
208 | |
209 </directive> | |
210 | |
211 | |
212 <directive name="ssl_prefer_server_ciphers"> | |
213 <syntax>ssl_prefer_server_ciphers <value>[on|off]</value></syntax> | |
214 <default>ssl_prefer_server_ciphers off</default> | |
215 <context>http, server</context> | |
216 | |
217 <para> | |
218 Директива указывает, чтобы при использовании протоколов SSLv3 и TLSv1 | |
219 серверные шифры были более приоритетны, чем клиентские. | |
220 </para> | |
221 | |
222 </directive> | |
223 | |
224 | |
225 <directive name="ssl_protocols"> | |
226 <syntax>ssl_protocols <value>[SSLv2] [SSLv3] [TLSv1]</value></syntax> | |
227 <default>ssl_protocols SSLv3 TLSv1</default> | |
228 <context>http, server</context> | |
229 | |
230 <para> | |
231 Директива разрешает указанные протоколы. | |
232 </para> | |
233 | |
234 </directive> | |
235 | |
236 | |
237 <directive name="ssl_verify_client"> | |
238 <syntax>ssl_verify_client <value>on|off|optional</value></syntax> | |
239 <default>ssl_verify_client off</default> | |
240 <context>http, server</context> | |
241 | |
242 <para> | |
243 Директива разрешает проверку клиентских сертификатов. | |
244 Параметр optional (0.8.7+) запрашивает сертификат клиента | |
245 и проверяет его, если он предоставлен. | |
246 Результат проверки можно узнать в переменной $ssl_client_verify. | |
247 </para> | |
248 | |
249 </directive> | |
250 | |
251 | |
252 <directive name="ssl_verify_depth"> | |
253 <syntax>ssl_verify_depth <value>число</value></syntax> | |
254 <default>ssl_verify_depth 1</default> | |
255 <context>http, server</context> | |
256 | |
257 <para> | |
258 Директива устанавливает глубину проверку в цепочке клиентских сертификатов. | |
259 </para> | |
260 | |
261 </directive> | |
262 | |
263 | |
264 <directive name="ssl_session_cache"> | |
265 <syntax>ssl_session_cache <value>off|none|[builtin[:размер]] [shared:название:размер] | |
266 </value></syntax> | |
267 <default>ssl_session_cache none</default> | |
268 <context>http, server</context> | |
269 | |
270 <para> | |
271 Директива задаёт тип и размеры кэшей для хранения параметров сессий. | |
272 Тип кэша может быть следующим: | |
273 <list type="bullet"> | |
274 | |
275 <listitem> | |
276 off — жёсткое запрещение использования кэша сессий: | |
277 nginx явно говорит клиенту, что сессии не могут использоваться повторно. | |
278 </listitem> | |
279 | |
280 <listitem> | |
281 none — мягкое запрещение использования кэша сессий: | |
282 nginx говорит клиенту, что сессии могут использоваться повторно, но | |
283 на самом деле не используются. | |
284 </listitem> | |
285 | |
286 <listitem> | |
287 builtin — встроенный в OpenSSL кэш, используется в рамках только | |
288 одного рабочего процесса. Размер кэша задаётся в сессиях. | |
289 Если размер не задан, то он равен 20480 сессиям. | |
290 Использование встроенного кэша может вести к фрагментации памяти. | |
291 </listitem> | |
292 | |
293 <listitem> | |
294 shared — разделяемый между всеми рабочими процессами. | |
295 Размер кэша задаётся в байтах, в 1 мегабайт может поместиться | |
296 около 4000 сессий. | |
297 У каждого разделяемого кэша должно быть произвольное название. | |
298 Кэш с одинаковым названием может использоваться в нескольких | |
299 виртуальных серверах. | |
300 </listitem> | |
301 | |
302 </list> | |
303 </para> | |
304 | |
305 <para> | |
306 Можно использовать одновременно оба типа кэша, например: | |
307 <example> | |
308 ssl_session_cache builtin:1000 shared:SSL:10m; | |
309 </example> | |
310 однако использование только разделяемого кэша без встроенного должно | |
311 быть более эффективным. | |
312 </para> | |
313 | |
314 </directive> | |
315 | |
316 | |
317 <directive name="ssl_session_timeout"> | |
318 <syntax>ssl_session_timeout <value>время</value></syntax> | |
319 <default>ssl_session_timeout 5m</default> | |
320 <context>http, server</context> | |
321 | |
322 <para> | |
323 Директива задаёт время, в течение которого клиент может повторно | |
324 использовать параметры сессии, хранящейся в кэше. | |
325 </para> | |
326 | |
327 </directive> | |
328 | |
329 </section> | |
330 | |
331 | |
332 <section name="Обработка ошибок" id="errors"> | |
333 | |
334 <para> | |
335 Модуль ngx_http_ssl_module поддерживает несколько нестандартных кодов ошибок, | |
336 которые можно использовать для перенаправления с помощью директивы <link doc="ngx_http_core_module.xml#error_page">error_page</link>: | |
337 <list type="bullet"> | |
338 | |
339 <listitem> | |
340 495 — при проверке клиентского сертификата произошла ошибка; | |
341 </listitem> | |
342 | |
343 <listitem> | |
344 496 — клиент не предоставил требуемый сертификат; | |
345 </listitem> | |
346 | |
347 <listitem> | |
348 497 — обычный запрос был послан на порт HTTPS. | |
349 </listitem> | |
350 | |
351 </list> | |
352 </para> | |
353 | |
354 <para> | |
355 Перенаправление делается после того, как запрос полностью разобран | |
356 и доступны такие переменные, как $request_uri, $uri, $arg и прочие. | |
357 </para> | |
358 | |
359 </section> | |
360 | |
361 | |
362 <section name="Встроенные переменные" id="variables"> | |
363 | |
364 <para> | |
365 Модуль ngx_http_ssl_module поддерживает несколько встроенных переменных: | |
366 <list type="bullet"> | |
367 | |
368 <listitem> | |
369 $ssl_cipher возвращает строку используемых шифров для установленного | |
370 SSL-соединения; | |
371 </listitem> | |
372 | |
373 <listitem> | |
374 $ssl_client_cert возвращает клиентский сертификат | |
375 для установленного SSL-соединения в формате PEM | |
376 перед каждой строкой которого, кроме первой, вставляется символ табуляции; | |
377 предназачен для использования в директиве <link doc="ngx_http_proxy_module.xml#proxy_set_header">proxy_set_header</link>. | |
378 </listitem> | |
379 | |
380 <listitem> | |
381 $ssl_client_raw_cert возвращает клиентский сертификат | |
382 для установленного SSL-соединения в формате PEM; | |
383 </listitem> | |
384 | |
385 <listitem> | |
386 $ssl_client_serial возвращает серийный номер клиентского сертификата | |
387 для установленного SSL-соединения; | |
388 </listitem> | |
389 | |
390 <listitem> | |
391 $ssl_client_s_dn возвращает строку subject DN клиентского сертификата | |
392 для установленного SSL-соединения; | |
393 </listitem> | |
394 | |
395 <listitem> | |
396 $ssl_client_i_dn возвращает строку issuer DN клиентского сертификата | |
397 для установленного SSL-соединения. | |
398 </listitem> | |
399 | |
400 <listitem> | |
401 $ssl_client_verify возвращает результат проверки клиентского сертификата: | |
402 "SUCCESS", "FAILED" и, если серфтикат не был предоставлен - "NONE". | |
403 </listitem> | |
404 | |
405 <listitem> | |
406 $ssl_protocol возвращает протокол установленного SSL-соединения; | |
407 </listitem> | |
408 | |
409 <listitem> | |
410 $ssl_session_id возвращает идентификатор сессии установленного SSL-соединения; | |
411 </listitem> | |
412 | |
413 </list> | |
414 </para> | |
415 | |
416 </section> | |
417 | |
418 </module> |