Mercurial > hg > nginx-site
changeset 1869:e1d0b56c0310
Documented support for client certificate verification in stream.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Tue, 20 Dec 2016 23:02:18 +0300 |
parents | c6b5826b64f7 |
children | fa7542e40381 |
files | xml/en/docs/stream/ngx_stream_ssl_module.xml xml/ru/docs/stream/ngx_stream_ssl_module.xml |
diffstat | 2 files changed, 339 insertions(+), 2 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/docs/stream/ngx_stream_ssl_module.xml +++ b/xml/en/docs/stream/ngx_stream_ssl_module.xml @@ -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 @@ The full list can be viewed using the </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 @@ session parameters. </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 @@ only for new sessions and lists only kno </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).
--- a/xml/ru/docs/stream/ngx_stream_ssl_module.xml +++ b/xml/ru/docs/stream/ngx_stream_ssl_module.xml @@ -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 @@ ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA </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 @@ openssl rand 48 > ticket.key </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 @@ AES128-SHA:AES256-SHA:0x00ff </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).