Mercurial > hg > nginx-site

comparison xml/en/docs/stream/ngx_stream_ssl_module.xml @ 1869:e1d0b56c0310

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Documented support for client certificate verification in stream.
author Yaroslav Zhuravlev <yar@nginx.com>
date Tue, 20 Dec 2016 23:02:18 +0300
parents 0882ccb0c00f
children b451f03e0a4b
comparison
equal deleted inserted replaced
1868:c6b5826b64f7 1869:e1d0b56c0310
7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> 7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
8 8
9 <module name="Module ngx_stream_ssl_module" 9 <module name="Module ngx_stream_ssl_module"
10 link="/en/docs/stream/ngx_stream_ssl_module.html" 10 link="/en/docs/stream/ngx_stream_ssl_module.html"
11 lang="en" 11 lang="en"
12 rev="12"> 12 rev="13">
13 13
14 <section id="summary"> 14 <section id="summary">
15 15
16 <para> 16 <para>
17 The <literal>ngx_stream_ssl_module</literal> module (1.9.0) 17 The <literal>ngx_stream_ssl_module</literal> module (1.9.0)
156 </para> 156 </para>
157 157
158 <para> 158 <para>
159 The full list can be viewed using the 159 The full list can be viewed using the
160 “<command>openssl ciphers</command>” command. 160 “<command>openssl ciphers</command>” command.
161 </para>
162
163 </directive>
164
165
166 <directive name="ssl_client_certificate">
167 <syntax><value>file</value></syntax>
168 <default/>
169 <context>stream</context>
170 <context>server</context>
171 <appeared-in>1.11.8</appeared-in>
172
173 <para>
174 Specifies a <value>file</value> with trusted CA certificates in the PEM format
175 used to <link id="ssl_verify_client">verify</link> client certificates.
176 </para>
177
178 <para>
179 The list of certificates will be sent to clients.
180 If this is not desired, the <link id="ssl_trusted_certificate"/>
181 directive can be used.
182 </para>
183
184 </directive>
185
186
187 <directive name="ssl_crl">
188 <syntax><value>file</value></syntax>
189 <default/>
190 <context>stream</context>
191 <context>server</context>
192 <appeared-in>1.11.8</appeared-in>
193
194 <para>
195 Specifies a <value>file</value> with revoked certificates (CRL)
196 in the PEM format used to <link id="ssl_verify_client">verify</link>
197 client certificates.
161 </para> 198 </para>
162 199
163 </directive> 200 </directive>
164 201
165 202
417 session parameters. 454 session parameters.
418 </para> 455 </para>
419 456
420 </directive> 457 </directive>
421 458
459
460 <directive name="ssl_trusted_certificate">
461 <syntax><value>file</value></syntax>
462 <default/>
463 <context>stream</context>
464 <context>server</context>
465 <appeared-in>1.11.8</appeared-in>
466
467 <para>
468 Specifies a <value>file</value> with trusted CA certificates in the PEM format
469 used to <link id="ssl_verify_client">verify</link> client certificates.
470 </para>
471
472 <para>
473 In contrast to the certificate set by <link id="ssl_client_certificate"/>,
474 the list of these certificates will not be sent to clients.
475 </para>
476
477 </directive>
478
479
480 <directive name="ssl_verify_client">
481 <syntax>
482 <literal>on</literal> | <literal>off</literal> |
483 <literal>optional</literal> | <literal>optional_no_ca</literal></syntax>
484 <default>off</default>
485 <context>stream</context>
486 <context>server</context>
487 <appeared-in>1.11.8</appeared-in>
488
489 <para>
490 Enables verification of client certificates.
491 The verification result is stored in the
492 <link id="var_ssl_client_verify">$ssl_client_verify</link> variable.
493 </para>
494
495 <para>
496 The <literal>optional</literal> parameter requests the client
497 certificate and verifies it if the certificate is present.
498 </para>
499
500 <para>
501 The <literal>optional_no_ca</literal> parameter
502 requests the client
503 certificate but does not require it to be signed by a trusted CA certificate.
504 This is intended for the use in cases when a service that is external to nginx
505 performs the actual certificate verification.
506 The contents of the certificate is accessible through the
507 <link id="var_ssl_client_cert">$ssl_client_cert</link> variable.
508 </para>
509
510 </directive>
511
512
513 <directive name="ssl_verify_depth">
514 <syntax><value>number</value></syntax>
515 <default>1</default>
516 <context>stream</context>
517 <context>server</context>
518 <appeared-in>1.11.8</appeared-in>
519
520 <para>
521 Sets the verification depth in the client certificates chain.
522 </para>
523
524 </directive>
525
422 </section> 526 </section>
423 527
424 528
425 <section id="variables" name="Embedded Variables"> 529 <section id="variables" name="Embedded Variables">
426 530
446 <note> 550 <note>
447 The variable is fully supported only when using OpenSSL version 1.0.2 or higher. 551 The variable is fully supported only when using OpenSSL version 1.0.2 or higher.
448 With older versions, the variable is available 552 With older versions, the variable is available
449 only for new sessions and lists only known ciphers. 553 only for new sessions and lists only known ciphers.
450 </note> 554 </note>
555 </tag-desc>
556
557 <tag-name id="var_ssl_client_cert"><var>$ssl_client_cert</var></tag-name>
558 <tag-desc>
559 returns the client certificate in the PEM format
560 for an established SSL connection, with each line except the first
561 prepended with the tab character (1.11.8);
562 </tag-desc>
563
564 <tag-name id="var_ssl_client_fingerprint"><var>$ssl_client_fingerprint</var></tag-name>
565 <tag-desc>
566 returns the SHA1 fingerprint of the client certificate
567 for an established SSL connection (1.11.8);
568 </tag-desc>
569
570 <tag-name id="var_ssl_client_i_dn"><var>$ssl_client_i_dn</var></tag-name>
571 <tag-desc>
572 returns the “issuer DN” string of the client certificate
573 for an established SSL connection according to
574 <link url="https://tools.ietf.org/html/rfc2253">RFC 2253</link> (1.11.8);
575 </tag-desc>
576
577 <tag-name id="var_ssl_client_raw_cert"><var>$ssl_client_raw_cert</var>
578 </tag-name>
579 <tag-desc>
580 returns the client certificate in the PEM format
581 for an established SSL connection (1.11.8);
582 </tag-desc>
583
584 <tag-name id="var_ssl_client_s_dn"><var>$ssl_client_s_dn</var></tag-name>
585 <tag-desc>
586 returns the “subject DN” string of the client certificate
587 for an established SSL connection according to
588 <link url="https://tools.ietf.org/html/rfc2253">RFC 2253</link> (1.11.8);
589 </tag-desc>
590
591 <tag-name id="var_ssl_client_serial"><var>$ssl_client_serial</var></tag-name>
592 <tag-desc>
593 returns the serial number of the client certificate
594 for an established SSL connection (1.11.8);
595 </tag-desc>
596
597 <tag-name id="var_ssl_client_v_end"><var>$ssl_client_v_end</var></tag-name>
598 <tag-desc>
599 returns the end date of the client certificate (1.11.8);
600 </tag-desc>
601
602 <tag-name id="var_ssl_client_v_remain"><var>$ssl_client_v_remain</var></tag-name>
603 <tag-desc>
604 returns the number of days
605 until the client certificate expires (1.11.8);
606 </tag-desc>
607
608 <tag-name id="var_ssl_client_v_start"><var>$ssl_client_v_start</var></tag-name>
609 <tag-desc>
610 returns the start date of the client certificate (1.11.8);
611 </tag-desc>
612
613 <tag-name id="var_ssl_client_verify"><var>$ssl_client_verify</var></tag-name>
614 <tag-desc>
615 returns the result of client certificate verification (1.11.8):
616 “<literal>SUCCESS</literal>”, “<literal>FAILED:</literal><value>reason</value>”,
617 and “<literal>NONE</literal>” if a certificate was not present;
451 </tag-desc> 618 </tag-desc>
452 619
453 <tag-name id="var_ssl_curves"><var>$ssl_curves</var></tag-name> 620 <tag-name id="var_ssl_curves"><var>$ssl_curves</var></tag-name>
454 <tag-desc> 621 <tag-desc>
455 returns the list of curves supported by the client (1.11.7). 622 returns the list of curves supported by the client (1.11.7).