Mercurial > hg > nginx-site
changeset 379:f13435414ed8
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 +++ b/xml/ru/docs/http/ngx_http_ssl_module.xml @@ -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 @@ nginx также будет использовать и сертификаты этих промежуточных CA. </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 @@ nginx также будет использовать и сертификаты этих промежуточных CA. </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 @@ http { </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 @@ http { <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 @@ http { <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 @@ http { <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 @@ OpenSSL, например: </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 @@ OpenSSL, например: <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 @@ OpenSSL, например: <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 @@ OpenSSL, например: [<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 @@ OpenSSL, например: </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 @@ shared — разделяемый между всеми рабочими процессами. <para> Можно использовать одновременно оба типа кэша, например: <example> -ssl_session_cache builtin:1000 shared:SSL:10m; +ssl_session_cache builtin:1000 shared:SSL:10m; </example> однако использование только разделяемого кэша без встроенного должно быть более эффективным. @@ -333,100 +325,147 @@ ssl_session_cache builtin:1000 shared: <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>