Mercurial > hg > nginx-site

comparison xml/ru/docs/http/ngx_http_ssl_module.xml @ 76:4a4caa566120

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