Mercurial > hg > nginx-site
changeset 1429:06322891b4e3
Client certificate directives in mail_ssl_module and associates.
author | Sergey Kandaurov <pluknet@nginx.com> |
---|---|
date | Sat, 28 Feb 2015 00:31:18 +0300 |
parents | 933831d7bf0b |
children | 0eb8e261f349 |
files | xml/en/docs/mail/ngx_mail_auth_http_module.xml xml/en/docs/mail/ngx_mail_ssl_module.xml xml/ru/docs/mail/ngx_mail_auth_http_module.xml xml/ru/docs/mail/ngx_mail_ssl_module.xml |
diffstat | 4 files changed, 323 insertions(+), 4 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/docs/mail/ngx_mail_auth_http_module.xml Sat Feb 28 00:31:16 2015 +0300 +++ b/xml/en/docs/mail/ngx_mail_auth_http_module.xml Sat Feb 28 00:31:18 2015 +0300 @@ -10,7 +10,7 @@ <module name="Module ngx_mail_auth_http_module" link="/en/docs/mail/ngx_mail_auth_http_module.html" lang="en" - rev="5"> + rev="6"> <section id="directives" name="Directives"> @@ -47,6 +47,23 @@ </directive> +<directive name="auth_http_pass_client_cert"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>mail</context> +<context>server</context> +<appeared-in>1.7.11</appeared-in> + +<para> +Appends the <header>Auth-SSL-Cert</header> header with the +<link doc="ngx_mail_ssl_module.xml" id="ssl_verify_client">client</link> +certificate in the PEM format (urlencoded) +to requests sent to the authentication server. +</para> + +</directive> + + <directive name="auth_http_timeout"> <syntax><value>time</value></syntax> <default>60s</default> @@ -185,6 +202,40 @@ </example> </para> +<para> +For the SSL/TLS client connection (1.7.11), +the <header>Auth-SSL</header> header is added, and +<header>Auth-SSL-Verify</header> will contain +the result of client certificate verification, if +<link doc="ngx_mail_ssl_module.xml" id="ssl_verify_client">enabled</link>: +“<literal>SUCCESS</literal>”, “<literal>FAILED</literal>”, and +“<literal>NONE</literal>” if a certificate was not present. +When the client certificate was present, +its details are passed in the following request headers: +<header>Auth-SSL-Subject</header>, <header>Auth-SSL-Issuer</header>, +<header>Auth-SSL-Serial</header>, and <header>Auth-SSL-Fingerprint</header>. +If <link id="auth_http_pass_client_cert"/> is enabled, +the certificate itself is passed in the +<header>Auth-SSL-Cert</header> header. +The request will look as follows: +<example> +GET /auth HTTP/1.0 +Host: localhost +Auth-Method: plain +Auth-User: user +Auth-Pass: password +Auth-Protocol: imap +Auth-Login-Attempt: 1 +Client-IP: 192.0.2.42 +Auth-SSL: on +Auth-SSL-Verify: SUCCESS +Auth-SSL-Subject: /CN=example.com +Auth-SSL-Issuer: /CN=example.com +Auth-SSL-Serial: C07AD56B846B5BFF +Auth-SSL-Fingerprint: 29d6a80a123d13355ed16b4b04605e29cb55a5ad +</example> +</para> + </section> </module>
--- a/xml/en/docs/mail/ngx_mail_ssl_module.xml Sat Feb 28 00:31:16 2015 +0300 +++ b/xml/en/docs/mail/ngx_mail_ssl_module.xml Sat Feb 28 00:31:18 2015 +0300 @@ -10,7 +10,7 @@ <module name="Module ngx_mail_ssl_module" link="/en/docs/mail/ngx_mail_ssl_module.html" lang="en" - rev="4"> + rev="5"> <section id="summary"> @@ -110,6 +110,43 @@ </directive> +<directive name="ssl_client_certificate"> +<syntax><value>file</value></syntax> +<default/> +<context>mail</context> +<context>server</context> +<appeared-in>1.7.11</appeared-in> + +<para> +Specifies a <value>file</value> with trusted CA certificates in the PEM format +used to <link id="ssl_verify_client">verify</link> client certificates. +</para> + +<para> +The list of certificates will be sent to clients. +If this is not desired, the <link id="ssl_trusted_certificate"/> +directive can be used. +</para> + +</directive> + + +<directive name="ssl_crl"> +<syntax><value>file</value></syntax> +<default/> +<context>mail</context> +<context>server</context> +<appeared-in>1.7.11</appeared-in> + +<para> +Specifies a <value>file</value> with revoked certificates (CRL) +in the PEM format used to <link id="ssl_verify_client">verify</link> +client certificates. +</para> + +</directive> + + <directive name="ssl_dhparam"> <syntax><value>file</value></syntax> <default/> @@ -346,6 +383,77 @@ </directive> +<directive name="ssl_trusted_certificate"> +<syntax><value>file</value></syntax> +<default/> +<context>mail</context> +<context>server</context> +<appeared-in>1.7.11</appeared-in> + +<para> +Specifies a <value>file</value> with trusted CA certificates in the PEM format +used to <link id="ssl_verify_client">verify</link> client certificates. +</para> + +<para> +In contrast to the certificate set by <link id="ssl_client_certificate"/>, +the list of these certificates will not be sent to clients. +</para> + +</directive> + + +<directive name="ssl_verify_client"> +<syntax> + <literal>on</literal> | <literal>off</literal> | + <literal>optional</literal> | <literal>optional_no_ca</literal></syntax> +<default>off</default> +<context>mail</context> +<context>server</context> +<appeared-in>1.7.11</appeared-in> + +<para> +Enables verification of client certificates. +The verification result is passed in the +<header>Auth-SSL-Verify</header> header of the +<link doc="ngx_mail_auth_http_module.xml" id="auth_http">authentication</link> +request. +</para> + +<para> +The <literal>optional</literal> parameter requests the client +certificate and verifies it if the certificate is present. +</para> + +<para> +The <literal>optional_no_ca</literal> parameter +requests the client +certificate but does not require it to be signed by a trusted CA certificate. +This is intended for the use in cases when a service that is external to nginx +performs the actual certificate verification. +The contents of the certificate is accessible through requests +<link doc="ngx_mail_auth_http_module.xml" + id="auth_http_pass_client_cert">sent</link> +to the authentication server. +</para> + +</directive> + + +<directive name="ssl_verify_depth"> +<syntax><value>number</value></syntax> +<default>1</default> +<context>mail</context> +<context>server</context> +<appeared-in>1.7.11</appeared-in> + +<para> +Sets the verification depth in the client certificates chain. +</para> + +</directive> + + <directive name="starttls"> <syntax> <literal>on</literal> |
--- a/xml/ru/docs/mail/ngx_mail_auth_http_module.xml Sat Feb 28 00:31:16 2015 +0300 +++ b/xml/ru/docs/mail/ngx_mail_auth_http_module.xml Sat Feb 28 00:31:18 2015 +0300 @@ -10,7 +10,7 @@ <module name="Модуль ngx_mail_auth_http_module" link="/ru/docs/mail/ngx_mail_auth_http_module.html" lang="ru" - rev="5"> + rev="6"> <section id="directives" name="Директивы"> @@ -47,6 +47,23 @@ </directive> +<directive name="auth_http_pass_client_cert"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>mail</context> +<context>server</context> +<appeared-in>1.7.11</appeared-in> + +<para> +Добавляет заголовок <header>Auth-SSL-Cert</header> с +<link doc="ngx_mail_ssl_module.xml" id="ssl_verify_client">клиентским</link> +сертификатом в формате PEM (закодирован в формате urlencode) +к запросам, посылаемым на сервер аутентификации. +</para> + +</directive> + + <directive name="auth_http_timeout"> <syntax><value>время</value></syntax> <default>60s</default> @@ -183,6 +200,40 @@ </example> </para> +<para> +Для клиентского соединения по протоколу SSL/TLS (1.7.11) +добавляется заголовок <header>Auth-SSL</header>, и если директива +<link doc="ngx_mail_ssl_module.xml" id="ssl_verify_client"/> включена, +заголовок <header>Auth-SSL-Verify</header> содержит +результат проверки клиентского сертификата: +“<literal>SUCCESS</literal>”, “<literal>FAILED</literal>” и, +если сертификат не был предоставлен — “<literal>NONE</literal>”. +Если клиентский сертификат был предоставлен, +информация о нём передаётся в следующих заголовках запроса: +<header>Auth-SSL-Subject</header>, <header>Auth-SSL-Issuer</header>, +<header>Auth-SSL-Serial</header> и <header>Auth-SSL-Fingerprint</header>. +Если директива <link id="auth_http_pass_client_cert"/> включена, +сам сертификат передаётся в заголовке +<header>Auth-SSL-Cert</header>. +Запрос будет выглядеть так: +<example> +GET /auth HTTP/1.0 +Host: localhost +Auth-Method: plain +Auth-User: user +Auth-Pass: password +Auth-Protocol: imap +Auth-Login-Attempt: 1 +Client-IP: 192.0.2.42 +Auth-SSL: on +Auth-SSL-Verify: SUCCESS +Auth-SSL-Subject: /CN=example.com +Auth-SSL-Issuer: /CN=example.com +Auth-SSL-Serial: C07AD56B846B5BFF +Auth-SSL-Fingerprint: 29d6a80a123d13355ed16b4b04605e29cb55a5ad +</example> +</para> + </section> </module>
--- a/xml/ru/docs/mail/ngx_mail_ssl_module.xml Sat Feb 28 00:31:16 2015 +0300 +++ b/xml/ru/docs/mail/ngx_mail_ssl_module.xml Sat Feb 28 00:31:18 2015 +0300 @@ -10,7 +10,7 @@ <module name="Модуль ngx_mail_ssl_module" link="/ru/docs/mail/ngx_mail_ssl_module.html" lang="ru" - rev="4"> + rev="5"> <section id="summary"> @@ -110,6 +110,44 @@ </directive> +<directive name="ssl_client_certificate"> +<syntax><value>файл</value></syntax> +<default/> +<context>mail</context> +<context>server</context> +<appeared-in>1.7.11</appeared-in> + +<para> +Указывает <value>файл</value> с доверенными сертификатами CA в формате +PEM, которые используются для +<link id="ssl_verify_client">проверки</link> клиентских сертификатов. +</para> + +<para> +Список сертификатов будет отправляться клиентам. +Если это нежелательно, можно воспользоваться директивой +<link id="ssl_trusted_certificate"/>. +</para> + +</directive> + + +<directive name="ssl_crl"> +<syntax><value>файл</value></syntax> +<default/> +<context>mail</context> +<context>server</context> +<appeared-in>1.7.11</appeared-in> + +<para> +Указывает <value>файл</value> с отозванными сертификатами (CRL) +в формате PEM, используемыми для +<link id="ssl_verify_client">проверки</link> клиентских сертификатов. +</para> + +</directive> + + <directive name="ssl_dhparam"> <syntax><value>файл</value></syntax> <default/> @@ -346,6 +384,77 @@ </directive> +<directive name="ssl_trusted_certificate"> +<syntax><value>файл</value></syntax> +<default/> +<context>mail</context> +<context>server</context> +<appeared-in>1.7.11</appeared-in> + +<para> +Задаёт <value>файл</value> с доверенными сертификатами CA в формате PEM, +которые используются для +<link id="ssl_verify_client">проверки</link> клиентских сертификатов. +</para> + +<para> +В отличие от <link id="ssl_client_certificate"/>, список этих сертификатов +не будет отправляться клиентам. +</para> + +</directive> + + +<directive name="ssl_verify_client"> +<syntax> + <literal>on</literal> | <literal>off</literal> | + <literal>optional</literal> | <literal>optional_no_ca</literal></syntax> +<default>off</default> +<context>mail</context> +<context>server</context> +<appeared-in>1.7.11</appeared-in> + +<para> +Разрешает проверку клиентских сертификатов. +Результат проверки передаётся в заголовке +<header>Auth-SSL-Verify</header> в запросе +<link doc="ngx_mail_auth_http_module.xml" id="auth_http">аутентификации</link>. +</para> + +<para> +Параметр <literal>optional</literal> запрашивает клиентский +сертификат, и если сертификат был предоставлен, проверяет его. +</para> + +<para> +Параметр <literal>optional_no_ca</literal> +запрашивает сертификат +клиента, но не требует, чтобы он был подписан доверенным сертификатом CA. +Это предназначено для случаев, когда фактическая проверка сертификата +осуществляется внешним по отношению к nginx’у сервисом. +Содержимое сертификата доступно в запросах, +<link doc="ngx_mail_auth_http_module.xml" + id="auth_http_pass_client_cert">посылаемых</link> +на сервер аутентификации. +</para> + +</directive> + + +<directive name="ssl_verify_depth"> +<syntax><value>число</value></syntax> +<default>1</default> +<context>mail</context> +<context>server</context> +<appeared-in>1.7.11</appeared-in> + +<para> +Устанавливает глубину проверки в цепочке клиентских сертификатов. +</para> + +</directive> + + <directive name="starttls"> <syntax> <literal>on</literal> |