# HG changeset patch
# User Yaroslav Zhuravlev <yar@nginx.com>
# Date 1482264138 -10800
# Node ID e1d0b56c0310c240e17b80239e18a377be88c872
# Parent  c6b5826b64f7e201693791cf55cf3ab2ad22f1ab
Documented support for client certificate verification in stream.

diff -r c6b5826b64f7 -r e1d0b56c0310 xml/en/docs/stream/ngx_stream_ssl_module.xml
--- a/xml/en/docs/stream/ngx_stream_ssl_module.xml	Tue Dec 20 22:53:03 2016 +0300
+++ b/xml/en/docs/stream/ngx_stream_ssl_module.xml	Tue Dec 20 23:02:18 2016 +0300
@@ -9,7 +9,7 @@
 <module name="Module ngx_stream_ssl_module"
         link="/en/docs/stream/ngx_stream_ssl_module.html"
         lang="en"
-        rev="12">
+        rev="13">
 
 <section id="summary">
 
@@ -163,6 +163,43 @@
 </directive>
 
 
+<directive name="ssl_client_certificate">
+<syntax><value>file</value></syntax>
+<default/>
+<context>stream</context>
+<context>server</context>
+<appeared-in>1.11.8</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>stream</context>
+<context>server</context>
+<appeared-in>1.11.8</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/>
@@ -419,6 +456,73 @@
 
 </directive>
 
+
+<directive name="ssl_trusted_certificate">
+<syntax><value>file</value></syntax>
+<default/>
+<context>stream</context>
+<context>server</context>
+<appeared-in>1.11.8</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>stream</context>
+<context>server</context>
+<appeared-in>1.11.8</appeared-in>
+
+<para>
+Enables verification of client certificates.
+The verification result is stored in the
+<link id="var_ssl_client_verify">$ssl_client_verify</link> variable.
+</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 the
+<link id="var_ssl_client_cert">$ssl_client_cert</link> variable.
+</para>
+
+</directive>
+
+
+<directive name="ssl_verify_depth">
+<syntax><value>number</value></syntax>
+<default>1</default>
+<context>stream</context>
+<context>server</context>
+<appeared-in>1.11.8</appeared-in>
+
+<para>
+Sets the verification depth in the client certificates chain.
+</para>
+
+</directive>
+
 </section>
 
 
@@ -450,6 +554,69 @@
 </note>
 </tag-desc>
 
+<tag-name id="var_ssl_client_cert"><var>$ssl_client_cert</var></tag-name>
+<tag-desc>
+returns the client certificate in the PEM format
+for an established SSL connection, with each line except the first
+prepended with the tab character (1.11.8);
+</tag-desc>
+
+<tag-name id="var_ssl_client_fingerprint"><var>$ssl_client_fingerprint</var></tag-name>
+<tag-desc>
+returns the SHA1 fingerprint of the client certificate
+for an established SSL connection (1.11.8);
+</tag-desc>
+
+<tag-name id="var_ssl_client_i_dn"><var>$ssl_client_i_dn</var></tag-name>
+<tag-desc>
+returns the “issuer DN” string of the client certificate
+for an established SSL connection according to
+<link url="https://tools.ietf.org/html/rfc2253">RFC 2253</link> (1.11.8);
+</tag-desc>
+
+<tag-name id="var_ssl_client_raw_cert"><var>$ssl_client_raw_cert</var>
+</tag-name>
+<tag-desc>
+returns the client certificate in the PEM format
+for an established SSL connection (1.11.8);
+</tag-desc>
+
+<tag-name id="var_ssl_client_s_dn"><var>$ssl_client_s_dn</var></tag-name>
+<tag-desc>
+returns the “subject DN” string of the client certificate
+for an established SSL connection according to
+<link url="https://tools.ietf.org/html/rfc2253">RFC 2253</link> (1.11.8);
+</tag-desc>
+
+<tag-name id="var_ssl_client_serial"><var>$ssl_client_serial</var></tag-name>
+<tag-desc>
+returns the serial number of the client certificate
+for an established SSL connection (1.11.8);
+</tag-desc>
+
+<tag-name id="var_ssl_client_v_end"><var>$ssl_client_v_end</var></tag-name>
+<tag-desc>
+returns the end date of the client certificate (1.11.8);
+</tag-desc>
+
+<tag-name id="var_ssl_client_v_remain"><var>$ssl_client_v_remain</var></tag-name>
+<tag-desc>
+returns the number of days
+until the client certificate expires (1.11.8);
+</tag-desc>
+
+<tag-name id="var_ssl_client_v_start"><var>$ssl_client_v_start</var></tag-name>
+<tag-desc>
+returns the start date of the client certificate (1.11.8);
+</tag-desc>
+
+<tag-name id="var_ssl_client_verify"><var>$ssl_client_verify</var></tag-name>
+<tag-desc>
+returns the result of client certificate verification (1.11.8):
+“<literal>SUCCESS</literal>”, “<literal>FAILED:</literal><value>reason</value>”,
+and “<literal>NONE</literal>” if a certificate was not present;
+</tag-desc>
+
 <tag-name id="var_ssl_curves"><var>$ssl_curves</var></tag-name>
 <tag-desc>
 returns the list of curves supported by the client (1.11.7).
diff -r c6b5826b64f7 -r e1d0b56c0310 xml/ru/docs/stream/ngx_stream_ssl_module.xml
--- a/xml/ru/docs/stream/ngx_stream_ssl_module.xml	Tue Dec 20 22:53:03 2016 +0300
+++ b/xml/ru/docs/stream/ngx_stream_ssl_module.xml	Tue Dec 20 23:02:18 2016 +0300
@@ -9,7 +9,7 @@
 <module name="Модуль ngx_stream_ssl_module"
         link="/ru/docs/stream/ngx_stream_ssl_module.html"
         lang="ru"
-        rev="12">
+        rev="13">
 
 <section id="summary">
 
@@ -162,6 +162,44 @@
 </directive>
 
 
+<directive name="ssl_client_certificate">
+<syntax><value>файл</value></syntax>
+<default/>
+<context>stream</context>
+<context>server</context>
+<appeared-in>1.11.8</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>stream</context>
+<context>server</context>
+<appeared-in>1.11.8</appeared-in>
+
+<para>
+Указывает <value>файл</value> с отозванными сертификатами (CRL)
+в формате PEM, используемыми для
+<link id="ssl_verify_client">проверки</link> клиентских сертификатов.
+</para>
+
+</directive>
+
+
 <directive name="ssl_dhparam">
 <syntax><value>файл</value></syntax>
 <default/>
@@ -418,6 +456,75 @@
 
 </directive>
 
+
+<directive name="ssl_trusted_certificate">
+<syntax><value>файл</value></syntax>
+<default/>
+<context>stream</context>
+<context>server</context>
+<appeared-in>1.11.8</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>stream</context>
+<context>server</context>
+<appeared-in>1.11.8</appeared-in>
+
+
+<para>
+Разрешает проверку клиентских сертификатов.
+Результат проверки доступен через переменную
+<link id="var_ssl_client_verify">$ssl_client_verify</link>.
+</para>
+
+<para>
+Параметр <literal>optional</literal> запрашивает клиентский
+сертификат, и если сертификат был предоставлен, проверяет его.
+</para>
+
+<para>
+Параметр <literal>optional_no_ca</literal>
+запрашивает сертификат
+клиента, но не требует, чтобы он был подписан доверенным сертификатом CA.
+Это предназначено для случаев, когда фактическая проверка сертификата
+осуществляется внешним по отношению к nginx’у сервисом.
+Содержимое сертификата доступно через переменную
+<link id="var_ssl_client_cert">$ssl_client_cert</link>.
+</para>
+
+</directive>
+
+
+<directive name="ssl_verify_depth">
+<syntax><value>число</value></syntax>
+<default>1</default>
+<context>stream</context>
+<context>server</context>
+<appeared-in>1.11.8</appeared-in>
+
+<para>
+Устанавливает глубину проверки в цепочке клиентских сертификатов.
+</para>
+
+</directive>
+
 </section>
 
 
@@ -449,6 +556,69 @@
 </note>
 </tag-desc>
 
+<tag-name id="var_ssl_client_cert"><var>$ssl_client_cert</var></tag-name>
+<tag-desc>
+возвращает клиентский сертификат
+для установленного SSL-соединения в формате PEM
+перед каждой строкой которого, кроме первой, вставляется символ табуляции(1.11.8);
+</tag-desc>
+
+<tag-name id="var_ssl_client_fingerprint"><var>$ssl_client_fingerprint</var></tag-name>
+<tag-desc>
+возвращает SHA1-отпечаток клиентского сертификата
+для установленного SSL-соединения (1.11.8);
+</tag-desc>
+
+<tag-name id="var_ssl_client_i_dn"><var>$ssl_client_i_dn</var></tag-name>
+<tag-desc>
+возвращает строку “issuer DN” клиентского сертификата
+для установленного SSL-соединения согласно
+<link url="https://tools.ietf.org/html/rfc2253">RFC 2253</link> (1.11.8);
+</tag-desc>
+
+<tag-name id="var_ssl_client_raw_cert"><var>$ssl_client_raw_cert</var>
+</tag-name>
+<tag-desc>
+возвращает клиентский сертификат
+для установленного SSL-соединения в формате PEM (1.11.8);
+</tag-desc>
+
+<tag-name id="var_ssl_client_s_dn"><var>$ssl_client_s_dn</var></tag-name>
+<tag-desc>
+возвращает строку “subject DN” клиентского сертификата
+для установленного SSL-соединения согласно
+<link url="https://tools.ietf.org/html/rfc2253">RFC 2253</link> (1.11.8);
+</tag-desc>
+
+<tag-name id="var_ssl_client_serial"><var>$ssl_client_serial</var></tag-name>
+<tag-desc>
+возвращает серийный номер клиентского сертификата
+для установленного SSL-соединения (1.11.8);
+</tag-desc>
+
+<tag-name id="var_ssl_client_v_end"><var>$ssl_client_v_end</var></tag-name>
+<tag-desc>
+возвращает дату окончания срока действия клиентского сертификата (1.11.8);
+</tag-desc>
+
+<tag-name id="var_ssl_client_v_remain"><var>$ssl_client_v_remain</var></tag-name>
+<tag-desc>
+возвращает число дней,
+оставшихся до истечения срока действия клиентского сертификата (1.11.8);
+</tag-desc>
+
+<tag-name id="var_ssl_client_v_start"><var>$ssl_client_v_start</var></tag-name>
+<tag-desc>
+возвращает дату начала срока действия клиентского сертификата (1.11.8);
+</tag-desc>
+
+<tag-name id="var_ssl_client_verify"><var>$ssl_client_verify</var></tag-name>
+<tag-desc>
+возвращает результат проверки клиентского сертификата (1.11.8):
+“<literal>SUCCESS</literal>”, “<literal>FAILED:</literal><value>reason</value>”
+и, если сертификат не был предоставлен, “<literal>NONE</literal>”;
+</tag-desc>
+
 <tag-name id="var_ssl_curves"><var>$ssl_curves</var></tag-name>
 <tag-desc>
 возвращает список кривых, поддерживаемых клиентом (1.11.7).