Mercurial > hg > nginx-site

changeset 379:f13435414ed8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Revision.
author Ruslan Ermilov <ru@nginx.com>
date Mon, 30 Jan 2012 19:11:58 +0000
parents 9cb58efe09e8
children 41d1602b6bb7
files xml/ru/docs/http/ngx_http_ssl_module.xml
diffstat 1 files changed, 199 insertions(+), 160 deletions(-) [+]
line wrap: on
line diff
--- a/xml/ru/docs/http/ngx_http_ssl_module.xml	Mon Jan 30 14:20:05 2012 +0000
+++ b/xml/ru/docs/http/ngx_http_ssl_module.xml	Mon Jan 30 19:11:58 2012 +0000
@@ -2,14 +2,15 @@
 
 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
 
-<module name="Директивы модуля ngx_http_ssl_module"
+<module name="Модуль ngx_http_ssl_module"
         link="/ru/docs/http/ngx_http_ssl_module.html"
         lang="ru">
 
 <section id="summary">
 
 <para>
-Модуль ngx_http_ssl_module обеспечивает работу по протоколу HTTPS.
+Модуль <literal>ngx_http_ssl_module</literal> обеспечивает работу
+по протоколу HTTPS.
 Поддерживается проверка сертификатов клиентов с ограничением —
 если в файле, заданном директивой <link id="ssl_certificate"/>,
 указана цепочка сертификатов, то при проверке клиентских сертификатов
@@ -17,17 +18,19 @@
 </para>
 
 <para>
-По умолчанию модуль не собирается, нужно разрешить его сборку
-при конфигурировании параметром
+По умолчанию этот модуль не собирается, его сборку необходимо
+разрешить с помощью конфигурационного параметра
 <literal>--with-http_ssl_module</literal>.
+<note>
 Для сборки и работы этого модуля нужна библиотека
 <link url="http://www.openssl.org">OpenSSL</link>.
+</note>
 </para>
 
 </section>
 
 
-<section name="Пример конфигурации" id="example">
+<section id="example" name="Пример конфигурации">
 
 <para>
 Для уменьшения загрузки процессора рекомендуется
@@ -56,23 +59,23 @@
 </list>
 
 <example>
-<emphasis>worker_processes  2;</emphasis>
+<emphasis>worker_processes 2;</emphasis>
 
 http {
 
     ...
 
     server {
-        listen               443;
-        <emphasis>keepalive_timeout    70;</emphasis>
+        listen              443;
+        <emphasis>keepalive_timeout   70;</emphasis>
 
-        ssl                  on;
-        ssl_protocols        SSLv3 TLSv1 TLSv1.1 TLSv1.2;
-        ssl_ciphers          AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
-        ssl_certificate      /usr/local/nginx/conf/cert.pem;
-        ssl_certificate_key  /usr/local/nginx/conf/cert.key;
-        <emphasis>ssl_session_cache    shared:SSL:10m;</emphasis>
-        <emphasis>ssl_session_timeout  10m;</emphasis>
+        ssl                 on;
+        ssl_protocols       SSLv3 TLSv1 TLSv1.1 TLSv1.2;
+        ssl_ciphers         AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
+        ssl_certificate     /usr/local/nginx/conf/cert.pem;
+        ssl_certificate_key /usr/local/nginx/conf/cert.key;
+        <emphasis>ssl_session_cache   shared:SSL:10m;</emphasis>
+        <emphasis>ssl_session_timeout 10m;</emphasis>
 
         ...
     }
@@ -82,15 +85,16 @@
 </section>
 
 
-<section name="Директивы" id="directives">
+<section id="directives" name="Директивы">
 
 <directive name="ssl">
 <syntax><literal>on</literal> | <literal>off</literal></syntax>
 <default>off</default>
-<context>http, server</context>
+<context>http</context>
+<context>server</context>
 
 <para>
-Директива разрешает протокол HTTPS для данного виртуального сервера.
+Разрешает протокол HTTPS для данного виртуального сервера.
 </para>
 
 </directive>
@@ -99,10 +103,11 @@
 <directive name="ssl_certificate">
 <syntax><value>файл</value></syntax>
 <default/>
-<context>http, server</context>
+<context>http</context>
+<context>server</context>
 
 <para>
-Директива указывает файл с сертификатом в формате PEM
+Указывает файл с сертификатом в формате PEM
 для данного виртуального сервера.
 Если вместе с основным сертификатом нужно указать промежуточные,
 то они должны находиться в этом же файле в следующем порядке — сначала
@@ -112,25 +117,25 @@
 
 <para>
 Нужно иметь в виду, что из-за ограничения протокола HTTPS
-виртуальные сервера должны слушать на разных IP-адресах:
+виртуальные серверы должны слушать на разных IP-адресах:
 <example>
-     server {
-         listen           192.168.1.1:443;
-         server_name      one.example.com;
-         ssl_certificate  /usr/local/nginx/conf/one.example.com.cert;
-         ...
-     }
+server {
+    listen          192.168.1.1:443;
+    server_name     one.example.com;
+    ssl_certificate /usr/local/nginx/conf/one.example.com.cert;
+    ...
+}
 
-     server {
-         listen           192.168.1.2:443;
-         server_name      two.example.com;
-         ssl_certificate  /usr/local/nginx/conf/two.example.com.cert;
-         ...
-     }
+server {
+    listen          192.168.1.2:443;
+    server_name     two.example.com;
+    ssl_certificate /usr/local/nginx/conf/two.example.com.cert;
+    ...
+}
 </example>
 иначе для второго сайта будет выдаваться
-<link doc="../faq.xml" id="name_based_vhost_ssl">сертификат
-первого сервера</link>.
+<link doc="configuring_https_servers.xml"
+    id="name_based_https_servers">сертификат первого сервера</link>.
 </para>
 
 </directive>
@@ -139,40 +144,29 @@
 <directive name="ssl_certificate_key">
 <syntax><value>файл</value></syntax>
 <default/>
-<context>http, server</context>
+<context>http</context>
+<context>server</context>
 
 <para>
-Директива указывает файл с секретным ключом в формате PEM
+Указывает файл с секретным ключом в формате PEM
 для данного виртуального сервера.
 </para>
 
 </directive>
 
 
-<directive name="ssl_client_certificate">
-<syntax><value>файл</value></syntax>
-<default/>
-<context>http, server</context>
-
-<para>
-Директива указывает файл с сертификатами CA в формате PEM, используемыми для
-для проверки клиентских сертификатов.
-</para>
-
-</directive>
-
-
 <directive name="ssl_ciphers">
 <syntax><value>шифры</value></syntax>
 <default>HIGH:!ADH:!MD5</default>
-<context>http, server</context>
+<context>http</context>
+<context>server</context>
 
 <para>
-Директива описывает разрешённые шифры.
+Описывает разрешённые шифры.
 Шифры задаются в формате, поддерживаемом библиотекой
 OpenSSL, например:
 <example>
-    ssl_ciphers  ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
+ssl_ciphers ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
 </example>
 </para>
 
@@ -184,14 +178,30 @@
 </directive>
 
 
+<directive name="ssl_client_certificate">
+<syntax><value>файл</value></syntax>
+<default/>
+<context>http</context>
+<context>server</context>
+
+<para>
+Указывает файл с сертификатами CA в формате PEM, используемыми для
+для проверки клиентских сертификатов.
+</para>
+
+</directive>
+
+
 <directive name="ssl_crl">
 <syntax><value>файл</value></syntax>
 <default/>
-<context>http, server</context>
+<context>http</context>
+<context>server</context>
+<appeared-in>0.8.7</appeared-in>
 
 <para>
-Директива (0.8.7) указывает файл с отозванными сертификатами (CRL)
-в формате PEM, используемыми для для проверки клиентских сертификатов.
+Указывает файл с отозванными сертификатами (CRL)
+в формате PEM, используемыми для проверки клиентских сертификатов.
 </para>
 
 </directive>
@@ -200,10 +210,12 @@
 <directive name="ssl_dhparam">
 <syntax><value>файл</value></syntax>
 <default/>
-<context>http, server</context>
+<context>http</context>
+<context>server</context>
+<appeared-in>0.7.2</appeared-in>
 
 <para>
-Директива (0.7.2) указывает файл с параметрами для шифров с обменом EDH-ключами.
+Указывает файл с параметрами для шифров с обменом EDH-ключами.
 </para>
 
 </directive>
@@ -212,10 +224,11 @@
 <directive name="ssl_prefer_server_ciphers">
 <syntax><literal>on</literal> | <literal>off</literal></syntax>
 <default>off</default>
-<context>http, server</context>
+<context>http</context>
+<context>server</context>
 
 <para>
-Директива указывает, чтобы при использовании протоколов SSLv3 и TLS
+Указывает, чтобы при использовании протоколов SSLv3 и TLS
 серверные шифры были более приоритетны, чем клиентские.
 </para>
 
@@ -230,10 +243,11 @@
     [<literal>TLSv1.1</literal>]
     [<literal>TLSv1.2</literal>]</syntax>
 <default>SSLv3 TLSv1 TLSv1.1 TLSv1.2</default>
-<context>http, server</context>
+<context>http</context>
+<context>server</context>
 
 <para>
-Директива разрешает указанные протоколы.
+Разрешает указанные протоколы.
 Параметры <literal>TLSv1.1</literal> и <literal>TLSv1.2</literal> работают
 только при использовании библиотеки OpenSSL версии 1.0.1 и выше.
 <note>
@@ -247,73 +261,51 @@
 </directive>
 
 
-<directive name="ssl_verify_client">
-<syntax><literal>on</literal> | <literal>off</literal> | <literal>optional</literal></syntax>
-<default>off</default>
-<context>http, server</context>
-
-<para>
-Директива разрешает проверку клиентских сертификатов.
-Параметр optional (0.8.7+) запрашивает сертификат клиента
-и проверяет его, если он предоставлен.
-Результат проверки можно узнать в переменной $ssl_client_verify.
-</para>
-
-</directive>
-
-
-<directive name="ssl_verify_depth">
-<syntax><value>число</value></syntax>
-<default>1</default>
-<context>http, server</context>
-
-<para>
-Директива устанавливает глубину проверку в цепочке клиентских сертификатов.
-</para>
-
-</directive>
-
-
 <directive name="ssl_session_cache">
 <syntax>
-  <literal>off</literal> |
-  <literal>none</literal> |
-  [<literal>builtin</literal>[:<value>размер</value>]]
-  [<literal>shared</literal>:<value>название</value>:<value>размер</value>]</syntax>
+    <literal>off</literal> |
+    <literal>none</literal> |
+    [<literal>builtin</literal>[:<value>размер</value>]]
+    [<literal>shared</literal>:<value>название</value>:<value>размер</value>]</syntax>
 <default>none</default>
-<context>http, server</context>
+<context>http</context>
+<context>server</context>
 
 <para>
-Директива задаёт тип и размеры кэшей для хранения параметров сессий.
+Задаёт тип и размеры кэшей для хранения параметров сессий.
 Тип кэша может быть следующим:
-<list type="bullet">
+<list type="tag">
 
-<listitem>
-off — жёсткое запрещение использования кэша сессий:
+<tag-name><literal>off</literal></tag-name>
+<tag-desc>
+жёсткое запрещение использования кэша сессий:
 nginx явно говорит клиенту, что сессии не могут использоваться повторно.
-</listitem>
+</tag-desc>
 
-<listitem>
-none — мягкое запрещение использования кэша сессий:
+<tag-name><literal>none</literal></tag-name>
+<tag-desc>
+мягкое запрещение использования кэша сессий:
 nginx говорит клиенту, что сессии могут использоваться повторно, но
 на самом деле не используются.
-</listitem>
+</tag-desc>
 
-<listitem>
-builtin — встроенный в OpenSSL кэш, используется в рамках только
-одного рабочего процесса. Размер кэша задаётся в сессиях.
+<tag-name><literal>builtin</literal></tag-name>
+<tag-desc>
+встроенный в OpenSSL кэш, используется в рамках только одного рабочего процесса.
+Размер кэша задаётся в сессиях.
 Если размер не задан, то он равен 20480 сессиям.
 Использование встроенного кэша может вести к фрагментации памяти.
-</listitem>
+</tag-desc>
 
-<listitem>
-shared — разделяемый между всеми рабочими процессами.
+<tag-name><literal>shared</literal></tag-name>
+<tag-desc>
+разделяемый между всеми рабочими процессами.
 Размер кэша задаётся в байтах, в 1 мегабайт может поместиться
 около 4000 сессий.
 У каждого разделяемого кэша должно быть произвольное название.
 Кэш с одинаковым названием может использоваться в нескольких
 виртуальных серверах.
-</listitem>
+</tag-desc>
 
 </list>
 </para>
@@ -321,7 +313,7 @@
 <para>
 Можно использовать одновременно оба типа кэша, например:
 <example>
-ssl_session_cache  builtin:1000  shared:SSL:10m;
+ssl_session_cache builtin:1000 shared:SSL:10m;
 </example>
 однако использование только разделяемого кэша без встроенного должно
 быть более эффективным.
@@ -333,100 +325,147 @@
 <directive name="ssl_session_timeout">
 <syntax><value>время</value></syntax>
 <default>5m</default>
-<context>http, server</context>
+<context>http</context>
+<context>server</context>
 
 <para>
-Директива задаёт время, в течение которого клиент может повторно
+Задаёт время, в течение которого клиент может повторно
 использовать параметры сессии, хранящейся в кэше.
 </para>
 
 </directive>
 
+
+<directive name="ssl_verify_client">
+<syntax>
+    <literal>on</literal> | <literal>off</literal> |
+    <literal>optional</literal></syntax>
+<default>off</default>
+<context>http</context>
+<context>server</context>
+
+<para>
+Разрешает проверку клиентских сертификатов.
+Параметр <literal>optional</literal> (0.8.7+) запрашивает сертификат клиента
+и проверяет его, если он предоставлен.
+Результат проверки можно узнать в переменной <var>$ssl_client_verify</var>.
+</para>
+
+</directive>
+
+
+<directive name="ssl_verify_depth">
+<syntax><value>число</value></syntax>
+<default>1</default>
+<context>http</context>
+<context>server</context>
+
+<para>
+Устанавливает глубину проверки в цепочке клиентских сертификатов.
+</para>
+
+</directive>
+
 </section>
 
 
-<section name="Обработка ошибок" id="errors">
+<section id="errors" name="Обработка ошибок">
 
 <para>
-Модуль ngx_http_ssl_module поддерживает несколько нестандартных кодов ошибок,
-которые можно использовать для перенаправления с помощью директивы
+Модуль <literal>ngx_http_ssl_module</literal> поддерживает несколько
+нестандартных кодов ошибок, которые можно использовать для
+перенаправления с помощью директивы
 <link doc="ngx_http_core_module.xml" id="error_page"/>:
-<list type="bullet">
+<list type="tag">
 
-<listitem>
-495 — при проверке клиентского сертификата произошла ошибка;
-</listitem>
+<tag-name>495</tag-name>
+<tag-desc>
+при проверке клиентского сертификата произошла ошибка;
+</tag-desc>
 
-<listitem>
-496 — клиент не предоставил требуемый сертификат;
-</listitem>
+<tag-name>496</tag-name>
+<tag-desc>
+клиент не предоставил требуемый сертификат;
+</tag-desc>
 
-<listitem>
-497 — обычный запрос был послан на порт HTTPS.
-</listitem>
+<tag-name>497</tag-name>
+<tag-desc>
+обычный запрос был послан на порт HTTPS.
+</tag-desc>
 
 </list>
 </para>
 
 <para>
 Перенаправление делается после того, как запрос полностью разобран
-и доступны такие переменные, как $request_uri, $uri, $arg и прочие.
+и доступны такие переменные, как <var>$request_uri</var>,
+<var>$uri</var>, <var>$args</var> и прочие.
 </para>
 
 </section>
 
 
-<section name="Встроенные переменные" id="variables">
+<section id="variables" name="Встроенные переменные">
 
 <para>
-Модуль ngx_http_ssl_module поддерживает несколько встроенных переменных:
-<list type="bullet">
+Модуль <literal>ngx_http_ssl_module</literal> поддерживает
+несколько встроенных переменных:
+<list type="tag">
 
-<listitem>
-$ssl_cipher возвращает строку используемых шифров для установленного
-SSL-соединения;
-</listitem>
+<tag-name><var>$ssl_cipher</var></tag-name>
+<tag-desc>
+возвращает строку используемых шифров для установленного SSL-соединения;
+</tag-desc>
 
-<listitem>
-$ssl_client_cert возвращает клиентский сертификат
+<tag-name><var>$ssl_client_cert</var></tag-name>
+<tag-desc>
+возвращает клиентский сертификат
 для установленного SSL-соединения в формате PEM
 перед каждой строкой которого, кроме первой, вставляется символ табуляции;
 предназначен для использования в директиве
-<link doc="ngx_http_proxy_module.xml" id="proxy_set_header"/>.
-</listitem>
+<link doc="ngx_http_proxy_module.xml" id="proxy_set_header"/>;
+</tag-desc>
 
-<listitem>
-$ssl_client_raw_cert возвращает клиентский сертификат
+<tag-name><var>$ssl_client_raw_cert</var></tag-name>
+<tag-desc>
+возвращает клиентский сертификат
 для установленного SSL-соединения в формате PEM;
-</listitem>
+</tag-desc>
 
-<listitem>
-$ssl_client_serial возвращает серийный номер клиентского сертификата
+<tag-name><var>$ssl_client_serial</var></tag-name>
+<tag-desc>
+возвращает серийный номер клиентского сертификата
 для установленного SSL-соединения;
-</listitem>
+</tag-desc>
 
-<listitem>
-$ssl_client_s_dn возвращает строку subject DN клиентского сертификата
+<tag-name><var>$ssl_client_s_dn</var></tag-name>
+<tag-desc>
+возвращает строку “subject DN” клиентского сертификата
 для установленного SSL-соединения;
-</listitem>
+</tag-desc>
 
-<listitem>
-$ssl_client_i_dn возвращает строку issuer DN клиентского сертификата
-для установленного SSL-соединения.
-</listitem>
+<tag-name><var>$ssl_client_i_dn</var></tag-name>
+<tag-desc>
+возвращает строку “issuer DN” клиентского сертификата
+для установленного SSL-соединения;
+</tag-desc>
 
-<listitem>
-$ssl_client_verify возвращает результат проверки клиентского сертификата:
-"SUCCESS", "FAILED" и, если серфтикат не был предоставлен - "NONE".
-</listitem>
+<tag-name><var>$ssl_client_verify</var></tag-name>
+<tag-desc>
+возвращает результат проверки клиентского сертификата:
+“<literal>SUCCESS</literal>”, “<literal>FAILED</literal>” и,
+если сертификат не был предоставлен — “<literal>NONE</literal>”;
+</tag-desc>
 
-<listitem>
-$ssl_protocol возвращает протокол установленного SSL-соединения;
-</listitem>
+<tag-name><var>$ssl_protocol</var></tag-name>
+<tag-desc>
+возвращает протокол установленного SSL-соединения;
+</tag-desc>
 
-<listitem>
-$ssl_session_id возвращает идентификатор сессии установленного SSL-соединения;
-</listitem>
+<tag-name><var>$ssl_session_id</var></tag-name>
+<tag-desc>
+возвращает идентификатор сессии установленного SSL-соединения.
+</tag-desc>
 
 </list>
 </para>