# HG changeset patch
# User Sergey Kandaurov <pluknet@nginx.com>
# Date 1425072678 -10800
# Node ID 06322891b4e3c276f6eecd2ecea79a35488a7e8b
# Parent  933831d7bf0ba140aec253badffcdc12320ff214
Client certificate directives in mail_ssl_module and associates.

diff -r 933831d7bf0b -r 06322891b4e3 xml/en/docs/mail/ngx_mail_auth_http_module.xml
--- 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>
diff -r 933831d7bf0b -r 06322891b4e3 xml/en/docs/mail/ngx_mail_ssl_module.xml
--- 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> |
diff -r 933831d7bf0b -r 06322891b4e3 xml/ru/docs/mail/ngx_mail_auth_http_module.xml
--- 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>
diff -r 933831d7bf0b -r 06322891b4e3 xml/ru/docs/mail/ngx_mail_ssl_module.xml
--- 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> |