Mercurial > hg > nginx-site

annotate xml/en/docs/stream/ngx_stream_ssl_module.xml @ 2769:16f6fa718be2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated TLSv1.3 support notes. Previous notes described some early development snapshot of OpenSSL 1.1.1 with disabled TLSv1.3 by default. It was then enabled in the first alpha. Further, the updated text covers later major releases such as OpenSSL 3.0.
author Sergey Kandaurov <pluknet@nginx.com>
date Thu, 30 Sep 2021 16:29:20 +0300
parents 78161967514f
children d16409187314
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
1 <?xml version="1.0"?>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
2
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
3 <!--
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
4 Copyright (C) Nginx, Inc.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
5 -->
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
6
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
8
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
9 <module name="Module ngx_stream_ssl_module"
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
10 link="/en/docs/stream/ngx_stream_ssl_module.html"
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
11 lang="en"
2769
16f6fa718be2 Updated TLSv1.3 support notes.
Sergey Kandaurov <pluknet@nginx.com>
parents: 2648
diff changeset
12 rev="25">
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
13
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
14 <section id="summary">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
15
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
16 <para>
1462
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1456
diff changeset
17 The <literal>ngx_stream_ssl_module</literal> module (1.9.0)
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
18 provides the necessary support for a stream proxy server to work with
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
19 the SSL/TLS protocol.
1462
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1456
diff changeset
20 This module is not built by default, it should be enabled with the
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1456
diff changeset
21 <literal>--with-stream_ssl_module</literal>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1456
diff changeset
22 configuration parameter.
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
23 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
24
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
25 </section>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
26
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
27
1521
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
28 <section id="example" name="Example Configuration">
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
29
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
30 <para>
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
31 To reduce the processor load, it is recommended to
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
32 <list type="bullet">
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
33
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
34 <listitem>
2068
3d9e7993c201 Added links to directives in the example of ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1978
diff changeset
35 set the number of
3d9e7993c201 Added links to directives in the example of ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1978
diff changeset
36 <link doc="../ngx_core_module.xml" id="worker_processes">worker processes</link>
3d9e7993c201 Added links to directives in the example of ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1978
diff changeset
37 equal to the number of processors,
1521
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
38 </listitem>
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
39
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
40 <listitem>
2068
3d9e7993c201 Added links to directives in the example of ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1978
diff changeset
41 enable the <link id="ssl_session_cache_shared">shared</link> session cache,
1521
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
42 </listitem>
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
43
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
44 <listitem>
2068
3d9e7993c201 Added links to directives in the example of ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1978
diff changeset
45 disable the <link id="ssl_session_cache_builtin">built-in</link> session cache,
1521
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
46 </listitem>
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
47
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
48 <listitem>
2068
3d9e7993c201 Added links to directives in the example of ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1978
diff changeset
49 and possibly increase the session <link id="ssl_session_timeout">lifetime</link>
3d9e7993c201 Added links to directives in the example of ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1978
diff changeset
50 (by default, 5 minutes):
1521
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
51 </listitem>
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
52
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
53 </list>
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
54
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
55 <example>
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
56 <emphasis>worker_processes auto;</emphasis>
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
57
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
58 stream {
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
59
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
60 ...
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
61
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
62 server {
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
63 listen 12345 ssl;
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
64
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
65 ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
66 ssl_ciphers AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
67 ssl_certificate /usr/local/nginx/conf/cert.pem;
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
68 ssl_certificate_key /usr/local/nginx/conf/cert.key;
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
69 <emphasis>ssl_session_cache shared:SSL:10m;</emphasis>
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
70 <emphasis>ssl_session_timeout 10m;</emphasis>
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
71
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
72 ...
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
73 }
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
74 </example>
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
75 </para>
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
76
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
77 </section>
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
78
e3d3e2ed4275 Added example configuration to mail and stream ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1499
diff changeset
79
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
80 <section id="directives" name="Directives">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
81
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
82 <directive name="ssl_certificate">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
83 <syntax><value>file</value></syntax>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
84 <default/>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
85 <context>stream</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
86 <context>server</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
87
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
88 <para>
1456
acba294382d6 Documented engine support in ssl_certificate_key and friends.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1450
diff changeset
89 Specifies a <value>file</value> with the certificate in the PEM format
acba294382d6 Documented engine support in ssl_certificate_key and friends.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1450
diff changeset
90 for the given server.
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
91 If intermediate certificates should be specified in addition to a primary
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
92 certificate, they should be specified in the same file in the following
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
93 order: the primary certificate comes first, then the intermediate certificates.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
94 A secret key in the PEM format may be placed in the same file.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
95 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
96
1726
a0bc284941f6 Documented multiple certificates support.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1711
diff changeset
97 <para>
a0bc284941f6 Documented multiple certificates support.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1711
diff changeset
98 Since version 1.11.0,
a0bc284941f6 Documented multiple certificates support.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1711
diff changeset
99 this directive can be specified multiple times
a0bc284941f6 Documented multiple certificates support.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1711
diff changeset
100 to load certificates of different types, for example, RSA and ECDSA:
a0bc284941f6 Documented multiple certificates support.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1711
diff changeset
101 <example>
a0bc284941f6 Documented multiple certificates support.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1711
diff changeset
102 server {
a0bc284941f6 Documented multiple certificates support.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1711
diff changeset
103 listen 12345 ssl;
a0bc284941f6 Documented multiple certificates support.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1711
diff changeset
104
a0bc284941f6 Documented multiple certificates support.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1711
diff changeset
105 ssl_certificate example.com.rsa.crt;
a0bc284941f6 Documented multiple certificates support.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1711
diff changeset
106 ssl_certificate_key example.com.rsa.key;
a0bc284941f6 Documented multiple certificates support.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1711
diff changeset
107
a0bc284941f6 Documented multiple certificates support.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1711
diff changeset
108 ssl_certificate example.com.ecdsa.crt;
a0bc284941f6 Documented multiple certificates support.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1711
diff changeset
109 ssl_certificate_key example.com.ecdsa.key;
a0bc284941f6 Documented multiple certificates support.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1711
diff changeset
110
a0bc284941f6 Documented multiple certificates support.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1711
diff changeset
111 ...
a0bc284941f6 Documented multiple certificates support.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1711
diff changeset
112 }
a0bc284941f6 Documented multiple certificates support.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1711
diff changeset
113 </example>
a0bc284941f6 Documented multiple certificates support.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1711
diff changeset
114 <note>
a0bc284941f6 Documented multiple certificates support.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1711
diff changeset
115 Only OpenSSL 1.0.2 or higher supports separate certificate chains
a0bc284941f6 Documented multiple certificates support.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1711
diff changeset
116 for different certificates.
a0bc284941f6 Documented multiple certificates support.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1711
diff changeset
117 With older versions, only one certificate chain can be used.
a0bc284941f6 Documented multiple certificates support.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1711
diff changeset
118 </note>
a0bc284941f6 Documented multiple certificates support.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1711
diff changeset
119 </para>
a0bc284941f6 Documented multiple certificates support.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1711
diff changeset
120
2334
dbe55598d3f6 Added variables support in ssl_certificate and ssl_certificate_key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2296
diff changeset
121 <para>
dbe55598d3f6 Added variables support in ssl_certificate and ssl_certificate_key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2296
diff changeset
122 Since version 1.15.9, variables can be used in the <value>file</value> name
dbe55598d3f6 Added variables support in ssl_certificate and ssl_certificate_key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2296
diff changeset
123 when using OpenSSL 1.0.2 or higher:
dbe55598d3f6 Added variables support in ssl_certificate and ssl_certificate_key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2296
diff changeset
124 <example>
dbe55598d3f6 Added variables support in ssl_certificate and ssl_certificate_key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2296
diff changeset
125 ssl_certificate $ssl_server_name.crt;
dbe55598d3f6 Added variables support in ssl_certificate and ssl_certificate_key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2296
diff changeset
126 ssl_certificate_key $ssl_server_name.key;
dbe55598d3f6 Added variables support in ssl_certificate and ssl_certificate_key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2296
diff changeset
127 </example>
dbe55598d3f6 Added variables support in ssl_certificate and ssl_certificate_key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2296
diff changeset
128 Note that using variables implies that
dbe55598d3f6 Added variables support in ssl_certificate and ssl_certificate_key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2296
diff changeset
129 a certificate will be loaded for each SSL handshake,
dbe55598d3f6 Added variables support in ssl_certificate and ssl_certificate_key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2296
diff changeset
130 and this may have a negative impact on performance.
dbe55598d3f6 Added variables support in ssl_certificate and ssl_certificate_key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2296
diff changeset
131 </para>
dbe55598d3f6 Added variables support in ssl_certificate and ssl_certificate_key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2296
diff changeset
132
2350
8e35f3af574b Documented the "data:" syntax for ssl_certificate and key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2334
diff changeset
133 <para id="ssl_certificate_data">
8e35f3af574b Documented the "data:" syntax for ssl_certificate and key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2334
diff changeset
134 The value
8e35f3af574b Documented the "data:" syntax for ssl_certificate and key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2334
diff changeset
135 <literal>data</literal>:<value>$variable</value>
8e35f3af574b Documented the "data:" syntax for ssl_certificate and key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2334
diff changeset
136 can be specified instead of the <value>file</value> (1.15.10),
8e35f3af574b Documented the "data:" syntax for ssl_certificate and key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2334
diff changeset
137 which loads a certificate from a variable without using intermediate files.
8e35f3af574b Documented the "data:" syntax for ssl_certificate and key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2334
diff changeset
138 Note that inappropriate use of this syntax may have its security implications,
8e35f3af574b Documented the "data:" syntax for ssl_certificate and key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2334
diff changeset
139 such as writing secret key data to
8e35f3af574b Documented the "data:" syntax for ssl_certificate and key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2334
diff changeset
140 <link doc="../ngx_core_module.xml" id="error_log">error log</link>.
8e35f3af574b Documented the "data:" syntax for ssl_certificate and key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2334
diff changeset
141 </para>
8e35f3af574b Documented the "data:" syntax for ssl_certificate and key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2334
diff changeset
142
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
143 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
144
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
145
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
146 <directive name="ssl_certificate_key">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
147 <syntax><value>file</value></syntax>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
148 <default/>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
149 <context>stream</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
150 <context>server</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
151
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
152 <para>
1456
acba294382d6 Documented engine support in ssl_certificate_key and friends.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1450
diff changeset
153 Specifies a <value>file</value> with the secret key in the PEM format
acba294382d6 Documented engine support in ssl_certificate_key and friends.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1450
diff changeset
154 for the given server.
acba294382d6 Documented engine support in ssl_certificate_key and friends.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1450
diff changeset
155 </para>
acba294382d6 Documented engine support in ssl_certificate_key and friends.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1450
diff changeset
156
acba294382d6 Documented engine support in ssl_certificate_key and friends.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1450
diff changeset
157 <para>
acba294382d6 Documented engine support in ssl_certificate_key and friends.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1450
diff changeset
158 The value
acba294382d6 Documented engine support in ssl_certificate_key and friends.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1450
diff changeset
159 <literal>engine</literal>:<value>name</value>:<value>id</value>
1462
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1456
diff changeset
160 can be specified instead of the <value>file</value>,
1456
acba294382d6 Documented engine support in ssl_certificate_key and friends.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1450
diff changeset
161 which loads a secret key with a specified <value>id</value>
acba294382d6 Documented engine support in ssl_certificate_key and friends.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1450
diff changeset
162 from the OpenSSL engine <value>name</value>.
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
163 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
164
2350
8e35f3af574b Documented the "data:" syntax for ssl_certificate and key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2334
diff changeset
165 <para id="ssl_certificate_key_data">
8e35f3af574b Documented the "data:" syntax for ssl_certificate and key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2334
diff changeset
166 The value
8e35f3af574b Documented the "data:" syntax for ssl_certificate and key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2334
diff changeset
167 <literal>data</literal>:<value>$variable</value>
8e35f3af574b Documented the "data:" syntax for ssl_certificate and key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2334
diff changeset
168 can be specified instead of the <value>file</value> (1.15.10),
8e35f3af574b Documented the "data:" syntax for ssl_certificate and key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2334
diff changeset
169 which loads a secret key from a variable without using intermediate files.
8e35f3af574b Documented the "data:" syntax for ssl_certificate and key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2334
diff changeset
170 Note that inappropriate use of this syntax may have its security implications,
8e35f3af574b Documented the "data:" syntax for ssl_certificate and key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2334
diff changeset
171 such as writing secret key data to
8e35f3af574b Documented the "data:" syntax for ssl_certificate and key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2334
diff changeset
172 <link doc="../ngx_core_module.xml" id="error_log">error log</link>.
8e35f3af574b Documented the "data:" syntax for ssl_certificate and key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2334
diff changeset
173 </para>
8e35f3af574b Documented the "data:" syntax for ssl_certificate and key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2334
diff changeset
174
2334
dbe55598d3f6 Added variables support in ssl_certificate and ssl_certificate_key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2296
diff changeset
175 <para>
dbe55598d3f6 Added variables support in ssl_certificate and ssl_certificate_key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2296
diff changeset
176 Since version 1.15.9, variables can be used in the <value>file</value> name
dbe55598d3f6 Added variables support in ssl_certificate and ssl_certificate_key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2296
diff changeset
177 when using OpenSSL 1.0.2 or higher.
dbe55598d3f6 Added variables support in ssl_certificate and ssl_certificate_key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2296
diff changeset
178 </para>
dbe55598d3f6 Added variables support in ssl_certificate and ssl_certificate_key.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2296
diff changeset
179
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
180 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
181
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
182
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
183 <directive name="ssl_ciphers">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
184 <syntax><value>ciphers</value></syntax>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
185 <default>HIGH:!aNULL:!MD5</default>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
186 <context>stream</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
187 <context>server</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
188
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
189 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
190 Specifies the enabled ciphers.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
191 The ciphers are specified in the format understood by the
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
192 OpenSSL library, for example:
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
193 <example>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
194 ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
195 </example>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
196 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
197
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
198 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
199 The full list can be viewed using the
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
200 “<command>openssl ciphers</command>” command.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
201 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
202
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
203 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
204
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
205
1869
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
206 <directive name="ssl_client_certificate">
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
207 <syntax><value>file</value></syntax>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
208 <default/>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
209 <context>stream</context>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
210 <context>server</context>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
211 <appeared-in>1.11.8</appeared-in>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
212
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
213 <para>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
214 Specifies a <value>file</value> with trusted CA certificates in the PEM format
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
215 used to <link id="ssl_verify_client">verify</link> client certificates.
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
216 </para>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
217
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
218 <para>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
219 The list of certificates will be sent to clients.
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
220 If this is not desired, the <link id="ssl_trusted_certificate"/>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
221 directive can be used.
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
222 </para>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
223
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
224 </directive>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
225
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
226
2616
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
227 <directive name="ssl_conf_command">
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
228 <syntax><value>command</value></syntax>
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
229 <default/>
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
230 <context>stream</context>
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
231 <context>server</context>
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
232 <appeared-in>1.19.4</appeared-in>
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
233
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
234 <para>
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
235 Sets arbitrary OpenSSL configuration
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
236 <link url="https://www.openssl.org/docs/man1.1.1/man3/SSL_CONF_cmd.html">commands</link>.
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
237 <note>
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
238 The directive is supported when using OpenSSL 1.0.2 or higher.
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
239 </note>
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
240 </para>
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
241
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
242 <para>
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
243 Several <literal>ssl_conf_command</literal> directives
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
244 can be specified on the same level:
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
245 <example>
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
246 ssl_conf_command Options PrioritizeChaCha;
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
247 ssl_conf_command Ciphersuites TLS_CHACHA20_POLY1305_SHA256;
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
248 </example>
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
249 These directives are inherited from the previous configuration level
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
250 if and only if there are no <literal>ssl_conf_command</literal> directives
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
251 defined on the current level.
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
252 </para>
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
253
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
254 <para>
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
255 <note>
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
256 Note that configuring OpenSSL directly
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
257 might result in unexpected behavior.
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
258 </note>
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
259 </para>
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
260
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
261 </directive>
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
262
d8bf37d20449 Documented the ssl_conf_command directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2460
diff changeset
263
1869
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
264 <directive name="ssl_crl">
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
265 <syntax><value>file</value></syntax>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
266 <default/>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
267 <context>stream</context>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
268 <context>server</context>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
269 <appeared-in>1.11.8</appeared-in>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
270
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
271 <para>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
272 Specifies a <value>file</value> with revoked certificates (CRL)
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
273 in the PEM format used to <link id="ssl_verify_client">verify</link>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
274 client certificates.
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
275 </para>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
276
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
277 </directive>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
278
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
279
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
280 <directive name="ssl_dhparam">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
281 <syntax><value>file</value></syntax>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
282 <default/>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
283 <context>stream</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
284 <context>server</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
285
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
286 <para>
1706
6f5497797cde Changed "EDH ciphers" to "DHE ciphers".
Maxim Dounin <mdounin@mdounin.ru>
parents: 1521
diff changeset
287 Specifies a <value>file</value> with DH parameters for DHE ciphers.
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
288 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
289
2296
e2e71f9477a8 Added note about ssl_dhparam defaults.
Sergey Kandaurov <pluknet@nginx.com>
parents: 2068
diff changeset
290 <para>
e2e71f9477a8 Added note about ssl_dhparam defaults.
Sergey Kandaurov <pluknet@nginx.com>
parents: 2068
diff changeset
291 By default no parameters are set,
e2e71f9477a8 Added note about ssl_dhparam defaults.
Sergey Kandaurov <pluknet@nginx.com>
parents: 2068
diff changeset
292 and therefore DHE ciphers will not be used.
e2e71f9477a8 Added note about ssl_dhparam defaults.
Sergey Kandaurov <pluknet@nginx.com>
parents: 2068
diff changeset
293 <note>
e2e71f9477a8 Added note about ssl_dhparam defaults.
Sergey Kandaurov <pluknet@nginx.com>
parents: 2068
diff changeset
294 Prior to version 1.11.0, builtin parameters were used by default.
e2e71f9477a8 Added note about ssl_dhparam defaults.
Sergey Kandaurov <pluknet@nginx.com>
parents: 2068
diff changeset
295 </note>
e2e71f9477a8 Added note about ssl_dhparam defaults.
Sergey Kandaurov <pluknet@nginx.com>
parents: 2068
diff changeset
296 </para>
e2e71f9477a8 Added note about ssl_dhparam defaults.
Sergey Kandaurov <pluknet@nginx.com>
parents: 2068
diff changeset
297
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
298 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
299
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
300
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
301 <directive name="ssl_ecdh_curve">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
302 <syntax><value>curve</value></syntax>
1711
38fb3e6b71e8 Documented ssl_ecdh_curve changes in 1.11.0.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1706
diff changeset
303 <default>auto</default>
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
304 <context>stream</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
305 <context>server</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
306
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
307 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
308 Specifies a <value>curve</value> for ECDHE ciphers.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
309 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
310
1711
38fb3e6b71e8 Documented ssl_ecdh_curve changes in 1.11.0.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1706
diff changeset
311 <para>
38fb3e6b71e8 Documented ssl_ecdh_curve changes in 1.11.0.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1706
diff changeset
312 When using OpenSSL 1.0.2 or higher,
38fb3e6b71e8 Documented ssl_ecdh_curve changes in 1.11.0.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1706
diff changeset
313 it is possible to specify multiple curves (1.11.0), for example:
38fb3e6b71e8 Documented ssl_ecdh_curve changes in 1.11.0.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1706
diff changeset
314 <example>
38fb3e6b71e8 Documented ssl_ecdh_curve changes in 1.11.0.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1706
diff changeset
315 ssl_ecdh_curve prime256v1:secp384r1;
38fb3e6b71e8 Documented ssl_ecdh_curve changes in 1.11.0.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1706
diff changeset
316 </example>
38fb3e6b71e8 Documented ssl_ecdh_curve changes in 1.11.0.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1706
diff changeset
317 </para>
38fb3e6b71e8 Documented ssl_ecdh_curve changes in 1.11.0.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1706
diff changeset
318
38fb3e6b71e8 Documented ssl_ecdh_curve changes in 1.11.0.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1706
diff changeset
319 <para>
38fb3e6b71e8 Documented ssl_ecdh_curve changes in 1.11.0.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1706
diff changeset
320 The special value <literal>auto</literal> (1.11.0) instructs nginx to use
38fb3e6b71e8 Documented ssl_ecdh_curve changes in 1.11.0.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1706
diff changeset
321 a list built into the OpenSSL library when using OpenSSL 1.0.2 or higher,
38fb3e6b71e8 Documented ssl_ecdh_curve changes in 1.11.0.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1706
diff changeset
322 or <literal>prime256v1</literal> with older versions.
38fb3e6b71e8 Documented ssl_ecdh_curve changes in 1.11.0.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1706
diff changeset
323 </para>
38fb3e6b71e8 Documented ssl_ecdh_curve changes in 1.11.0.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1706
diff changeset
324
38fb3e6b71e8 Documented ssl_ecdh_curve changes in 1.11.0.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1706
diff changeset
325 <para>
38fb3e6b71e8 Documented ssl_ecdh_curve changes in 1.11.0.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1706
diff changeset
326 <note>
38fb3e6b71e8 Documented ssl_ecdh_curve changes in 1.11.0.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1706
diff changeset
327 Prior to version 1.11.0,
38fb3e6b71e8 Documented ssl_ecdh_curve changes in 1.11.0.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1706
diff changeset
328 the <literal>prime256v1</literal> curve was used by default.
38fb3e6b71e8 Documented ssl_ecdh_curve changes in 1.11.0.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1706
diff changeset
329 </note>
38fb3e6b71e8 Documented ssl_ecdh_curve changes in 1.11.0.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1706
diff changeset
330 </para>
38fb3e6b71e8 Documented ssl_ecdh_curve changes in 1.11.0.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1706
diff changeset
331
2648
78161967514f Mentioned ECDSA in ssl_ecdh_curve.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2616
diff changeset
332 <para>
78161967514f Mentioned ECDSA in ssl_ecdh_curve.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2616
diff changeset
333 <note>
78161967514f Mentioned ECDSA in ssl_ecdh_curve.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2616
diff changeset
334 When using OpenSSL 1.0.2 or higher,
78161967514f Mentioned ECDSA in ssl_ecdh_curve.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2616
diff changeset
335 this directive sets the list of curves supported by the server.
78161967514f Mentioned ECDSA in ssl_ecdh_curve.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2616
diff changeset
336 Thus, in order for ECDSA certificates to work,
78161967514f Mentioned ECDSA in ssl_ecdh_curve.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2616
diff changeset
337 it is important to include the curves used in the certificates.
78161967514f Mentioned ECDSA in ssl_ecdh_curve.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2616
diff changeset
338 </note>
78161967514f Mentioned ECDSA in ssl_ecdh_curve.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2616
diff changeset
339 </para>
78161967514f Mentioned ECDSA in ssl_ecdh_curve.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2616
diff changeset
340
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
341 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
342
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
343
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
344 <directive name="ssl_handshake_timeout">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
345 <syntax><value>time</value></syntax>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
346 <default>60s</default>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
347 <context>stream</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
348 <context>server</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
349
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
350 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
351 Specifies a timeout for the SSL handshake to complete.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
352 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
353
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
354 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
355
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
356
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
357 <directive name="ssl_password_file">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
358 <syntax><value>file</value></syntax>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
359 <default/>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
360 <context>stream</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
361 <context>server</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
362
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
363 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
364 Specifies a <value>file</value> with passphrases for
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
365 <link id="ssl_certificate_key">secret keys</link>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
366 where each passphrase is specified on a separate line.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
367 Passphrases are tried in turn when loading the key.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
368 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
369
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
370 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
371 Example:
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
372 <example>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
373 stream {
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
374 ssl_password_file /etc/keys/global.pass;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
375 ...
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
376
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
377 server {
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
378 listen 127.0.0.1:12345;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
379 ssl_certificate_key /etc/keys/first.key;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
380 }
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
381
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
382 server {
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
383 listen 127.0.0.1:12346;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
384
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
385 # named pipe can also be used instead of a file
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
386 ssl_password_file /etc/keys/fifo;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
387 ssl_certificate_key /etc/keys/second.key;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
388 }
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
389 }
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
390 </example>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
391 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
392
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
393 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
394
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
395
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
396 <directive name="ssl_prefer_server_ciphers">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
397 <syntax><literal>on</literal> | <literal>off</literal></syntax>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
398 <default>off</default>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
399 <context>stream</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
400 <context>server</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
401
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
402 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
403 Specifies that server ciphers should be preferred over client ciphers
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
404 when the SSLv3 and TLS protocols are used.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
405 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
406
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
407 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
408
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
409
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
410 <directive name="ssl_protocols">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
411 <syntax>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
412 [<literal>SSLv2</literal>]
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
413 [<literal>SSLv3</literal>]
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
414 [<literal>TLSv1</literal>]
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
415 [<literal>TLSv1.1</literal>]
1978
8f1a568a8bbf Documented "TLSv1.3" parameter of the "ssl_protocols" directive.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1923
diff changeset
416 [<literal>TLSv1.2</literal>]
8f1a568a8bbf Documented "TLSv1.3" parameter of the "ssl_protocols" directive.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1923
diff changeset
417 [<literal>TLSv1.3</literal>]</syntax>
1499
3687cc9a3592 Removed SSLv3 from the default value of ssl_protocols and friends.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1462
diff changeset
418 <default>TLSv1 TLSv1.1 TLSv1.2</default>
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
419 <context>stream</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
420 <context>server</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
421
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
422 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
423 Enables the specified protocols.
1978
8f1a568a8bbf Documented "TLSv1.3" parameter of the "ssl_protocols" directive.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1923
diff changeset
424 <note>
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
425 The <literal>TLSv1.1</literal> and <literal>TLSv1.2</literal> parameters work
1978
8f1a568a8bbf Documented "TLSv1.3" parameter of the "ssl_protocols" directive.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1923
diff changeset
426 only when OpenSSL 1.0.1 or higher is used.
8f1a568a8bbf Documented "TLSv1.3" parameter of the "ssl_protocols" directive.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1923
diff changeset
427 </note>
8f1a568a8bbf Documented "TLSv1.3" parameter of the "ssl_protocols" directive.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1923
diff changeset
428 <note>
8f1a568a8bbf Documented "TLSv1.3" parameter of the "ssl_protocols" directive.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1923
diff changeset
429 The <literal>TLSv1.3</literal> parameter (1.13.0) works only when
2769
16f6fa718be2 Updated TLSv1.3 support notes.
Sergey Kandaurov <pluknet@nginx.com>
parents: 2648
diff changeset
430 OpenSSL 1.1.1 or higher is used.
1978
8f1a568a8bbf Documented "TLSv1.3" parameter of the "ssl_protocols" directive.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1923
diff changeset
431 </note>
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
432 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
433
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
434 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
435
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
436
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
437 <directive name="ssl_session_cache">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
438 <syntax>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
439 <literal>off</literal> |
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
440 <literal>none</literal> |
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
441 [<literal>builtin</literal>[:<value>size</value>]]
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
442 [<literal>shared</literal>:<value>name</value>:<value>size</value>]</syntax>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
443 <default>none</default>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
444 <context>stream</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
445 <context>server</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
446
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
447 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
448 Sets the types and sizes of caches that store session parameters.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
449 A cache can be of any of the following types:
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
450 <list type="tag">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
451
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
452 <tag-name><literal>off</literal></tag-name>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
453 <tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
454 the use of a session cache is strictly prohibited:
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
455 nginx explicitly tells a client that sessions may not be reused.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
456 </tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
457
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
458 <tag-name><literal>none</literal></tag-name>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
459 <tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
460 the use of a session cache is gently disallowed:
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
461 nginx tells a client that sessions may be reused, but does not
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
462 actually store session parameters in the cache.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
463 </tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
464
2068
3d9e7993c201 Added links to directives in the example of ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1978
diff changeset
465 <tag-name id="ssl_session_cache_builtin"><literal>builtin</literal></tag-name>
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
466 <tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
467 a cache built in OpenSSL; used by one worker process only.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
468 The cache size is specified in sessions.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
469 If size is not given, it is equal to 20480 sessions.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
470 Use of the built-in cache can cause memory fragmentation.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
471 </tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
472
2068
3d9e7993c201 Added links to directives in the example of ssl modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1978
diff changeset
473 <tag-name id="ssl_session_cache_shared"><literal>shared</literal></tag-name>
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
474 <tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
475 a cache shared between all worker processes.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
476 The cache size is specified in bytes; one megabyte can store
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
477 about 4000 sessions.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
478 Each shared cache should have an arbitrary name.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
479 A cache with the same name can be used in several
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
480 servers.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
481 </tag-desc>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
482
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
483 </list>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
484 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
485
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
486 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
487 Both cache types can be used simultaneously, for example:
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
488 <example>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
489 ssl_session_cache builtin:1000 shared:SSL:10m;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
490 </example>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
491 but using only shared cache without the built-in cache should
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
492 be more efficient.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
493 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
494
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
495 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
496
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
497
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
498 <directive name="ssl_session_ticket_key">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
499 <syntax><value>file</value></syntax>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
500 <default/>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
501 <context>stream</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
502 <context>server</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
503
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
504 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
505 Sets a <value>file</value> with the secret key used to encrypt
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
506 and decrypt TLS session tickets.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
507 The directive is necessary if the same key has to be shared between
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
508 multiple servers.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
509 By default, a randomly generated key is used.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
510 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
511
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
512 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
513 If several keys are specified, only the first key is
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
514 used to encrypt TLS session tickets.
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
515 This allows configuring key rotation, for example:
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
516 <example>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
517 ssl_session_ticket_key current.key;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
518 ssl_session_ticket_key previous.key;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
519 </example>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
520 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
521
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
522 <para>
1877
aa29a64a5e9d Documented ssl_session_ticket_key 80-byte keys.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1876
diff changeset
523 The <value>file</value> must contain 80 or 48 bytes
aa29a64a5e9d Documented ssl_session_ticket_key 80-byte keys.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1876
diff changeset
524 of random data and can be created using the following command:
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
525 <example>
1877
aa29a64a5e9d Documented ssl_session_ticket_key 80-byte keys.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1876
diff changeset
526 openssl rand 80 > ticket.key
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
527 </example>
1877
aa29a64a5e9d Documented ssl_session_ticket_key 80-byte keys.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1876
diff changeset
528 Depending on the file size either AES256 (for 80-byte keys, 1.11.8)
aa29a64a5e9d Documented ssl_session_ticket_key 80-byte keys.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1876
diff changeset
529 or AES128 (for 48-byte keys) is used for encryption.
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
530 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
531
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
532 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
533
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
534
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
535 <directive name="ssl_session_tickets">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
536 <syntax><literal>on</literal> | <literal>off</literal></syntax>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
537 <default>on</default>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
538 <context>stream</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
539 <context>server</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
540
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
541 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
542 Enables or disables session resumption through
1923
66a30a380fba Fixed links to tools.ietf.org.
Ruslan Ermilov <ru@nginx.com>
parents: 1877
diff changeset
543 <link url="https://tools.ietf.org/html/rfc5077">TLS session tickets</link>.
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
544 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
545
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
546 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
547
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
548
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
549 <directive name="ssl_session_timeout">
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
550 <syntax><value>time</value></syntax>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
551 <default>5m</default>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
552 <context>stream</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
553 <context>server</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
554
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
555 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
556 Specifies a time during which a client may reuse the
1785
3fa0944ddc6a Removed info about session cache from ssl_session_timeout.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1745
diff changeset
557 session parameters.
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
558 </para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
559
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
560 </directive>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
561
1869
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
562
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
563 <directive name="ssl_trusted_certificate">
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
564 <syntax><value>file</value></syntax>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
565 <default/>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
566 <context>stream</context>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
567 <context>server</context>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
568 <appeared-in>1.11.8</appeared-in>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
569
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
570 <para>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
571 Specifies a <value>file</value> with trusted CA certificates in the PEM format
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
572 used to <link id="ssl_verify_client">verify</link> client certificates.
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
573 </para>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
574
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
575 <para>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
576 In contrast to the certificate set by <link id="ssl_client_certificate"/>,
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
577 the list of these certificates will not be sent to clients.
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
578 </para>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
579
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
580 </directive>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
581
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
582
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
583 <directive name="ssl_verify_client">
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
584 <syntax>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
585 <literal>on</literal> | <literal>off</literal> |
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
586 <literal>optional</literal> | <literal>optional_no_ca</literal></syntax>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
587 <default>off</default>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
588 <context>stream</context>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
589 <context>server</context>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
590 <appeared-in>1.11.8</appeared-in>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
591
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
592 <para>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
593 Enables verification of client certificates.
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
594 The verification result is stored in the
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
595 <link id="var_ssl_client_verify">$ssl_client_verify</link> variable.
1876
b451f03e0a4b Described behavior of stream ssl_verify_client in case of error.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1869
diff changeset
596 If an error has occurred during the client certificate verification
b451f03e0a4b Described behavior of stream ssl_verify_client in case of error.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1869
diff changeset
597 or a client has not presented the required certificate,
b451f03e0a4b Described behavior of stream ssl_verify_client in case of error.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1869
diff changeset
598 the connection is closed.
1869
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
599 </para>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
600
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
601 <para>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
602 The <literal>optional</literal> parameter requests the client
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
603 certificate and verifies it if the certificate is present.
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
604 </para>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
605
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
606 <para>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
607 The <literal>optional_no_ca</literal> parameter
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
608 requests the client
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
609 certificate but does not require it to be signed by a trusted CA certificate.
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
610 This is intended for the use in cases when a service that is external to nginx
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
611 performs the actual certificate verification.
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
612 The contents of the certificate is accessible through the
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
613 <link id="var_ssl_client_cert">$ssl_client_cert</link> variable.
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
614 </para>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
615
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
616 </directive>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
617
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
618
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
619 <directive name="ssl_verify_depth">
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
620 <syntax><value>number</value></syntax>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
621 <default>1</default>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
622 <context>stream</context>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
623 <context>server</context>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
624 <appeared-in>1.11.8</appeared-in>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
625
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
626 <para>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
627 Sets the verification depth in the client certificates chain.
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
628 </para>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
629
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
630 </directive>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
631
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
632 </section>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
633
1745
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
634
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
635 <section id="variables" name="Embedded Variables">
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
636
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
637 <para>
1790
6da8d19f89c0 Corrected module name in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1785
diff changeset
638 The <literal>ngx_stream_ssl_module</literal> module supports variables
1745
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
639 since 1.11.2.
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
640 <list type="tag">
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
641
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
642 <tag-name id="var_ssl_cipher"><var>$ssl_cipher</var></tag-name>
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
643 <tag-desc>
2460
c60a8a15010c Clarified description of the $ssl_cipher variable.
Sergey Kandaurov <pluknet@nginx.com>
parents: 2350
diff changeset
644 returns the name of the cipher used
1745
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
645 for an established SSL connection;
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
646 </tag-desc>
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
647
1857
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
648 <tag-name id="var_ssl_ciphers"><var>$ssl_ciphers</var></tag-name>
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
649 <tag-desc>
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
650 returns the list of ciphers supported by the client (1.11.7).
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
651 Known ciphers are listed by names, unknown are shown in hexadecimal,
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
652 for example:
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
653 <example>
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
654 AES128-SHA:AES256-SHA:0x00ff
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
655 </example>
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
656 <note>
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
657 The variable is fully supported only when using OpenSSL version 1.0.2 or higher.
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
658 With older versions, the variable is available
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
659 only for new sessions and lists only known ciphers.
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
660 </note>
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
661 </tag-desc>
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
662
1869
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
663 <tag-name id="var_ssl_client_cert"><var>$ssl_client_cert</var></tag-name>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
664 <tag-desc>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
665 returns the client certificate in the PEM format
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
666 for an established SSL connection, with each line except the first
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
667 prepended with the tab character (1.11.8);
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
668 </tag-desc>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
669
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
670 <tag-name id="var_ssl_client_fingerprint"><var>$ssl_client_fingerprint</var></tag-name>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
671 <tag-desc>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
672 returns the SHA1 fingerprint of the client certificate
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
673 for an established SSL connection (1.11.8);
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
674 </tag-desc>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
675
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
676 <tag-name id="var_ssl_client_i_dn"><var>$ssl_client_i_dn</var></tag-name>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
677 <tag-desc>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
678 returns the “issuer DN” string of the client certificate
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
679 for an established SSL connection according to
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
680 <link url="https://tools.ietf.org/html/rfc2253">RFC 2253</link> (1.11.8);
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
681 </tag-desc>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
682
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
683 <tag-name id="var_ssl_client_raw_cert"><var>$ssl_client_raw_cert</var>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
684 </tag-name>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
685 <tag-desc>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
686 returns the client certificate in the PEM format
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
687 for an established SSL connection (1.11.8);
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
688 </tag-desc>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
689
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
690 <tag-name id="var_ssl_client_s_dn"><var>$ssl_client_s_dn</var></tag-name>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
691 <tag-desc>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
692 returns the “subject DN” string of the client certificate
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
693 for an established SSL connection according to
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
694 <link url="https://tools.ietf.org/html/rfc2253">RFC 2253</link> (1.11.8);
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
695 </tag-desc>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
696
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
697 <tag-name id="var_ssl_client_serial"><var>$ssl_client_serial</var></tag-name>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
698 <tag-desc>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
699 returns the serial number of the client certificate
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
700 for an established SSL connection (1.11.8);
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
701 </tag-desc>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
702
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
703 <tag-name id="var_ssl_client_v_end"><var>$ssl_client_v_end</var></tag-name>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
704 <tag-desc>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
705 returns the end date of the client certificate (1.11.8);
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
706 </tag-desc>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
707
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
708 <tag-name id="var_ssl_client_v_remain"><var>$ssl_client_v_remain</var></tag-name>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
709 <tag-desc>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
710 returns the number of days
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
711 until the client certificate expires (1.11.8);
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
712 </tag-desc>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
713
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
714 <tag-name id="var_ssl_client_v_start"><var>$ssl_client_v_start</var></tag-name>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
715 <tag-desc>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
716 returns the start date of the client certificate (1.11.8);
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
717 </tag-desc>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
718
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
719 <tag-name id="var_ssl_client_verify"><var>$ssl_client_verify</var></tag-name>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
720 <tag-desc>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
721 returns the result of client certificate verification (1.11.8):
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
722 “<literal>SUCCESS</literal>”, “<literal>FAILED:</literal><value>reason</value>”,
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
723 and “<literal>NONE</literal>” if a certificate was not present;
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
724 </tag-desc>
e1d0b56c0310 Documented support for client certificate verification in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1857
diff changeset
725
1857
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
726 <tag-name id="var_ssl_curves"><var>$ssl_curves</var></tag-name>
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
727 <tag-desc>
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
728 returns the list of curves supported by the client (1.11.7).
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
729 Known curves are listed by names, unknown are shown in hexadecimal,
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
730 for example:
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
731 <example>
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
732 0x001d:prime256v1:secp521r1:secp384r1
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
733 </example>
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
734 <note>
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
735 The variable is supported only when using OpenSSL version 1.0.2 or higher.
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
736 With older versions, the variable value will be an empty string.
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
737 </note>
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
738 <note>
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
739 The variable is available only for new sessions.
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
740 </note>
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
741 </tag-desc>
0882ccb0c00f Documented the $ssl_curves and $ssl_ciphers variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1790
diff changeset
742
1745
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
743 <tag-name id="var_ssl_protocol"><var>$ssl_protocol</var></tag-name>
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
744 <tag-desc>
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
745 returns the protocol of an established SSL connection;
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
746 </tag-desc>
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
747
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
748 <tag-name id="var_ssl_server_name"><var>$ssl_server_name</var></tag-name>
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
749 <tag-desc>
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
750 returns the server name requested through
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
751 <link url="http://en.wikipedia.org/wiki/Server_Name_Indication">SNI</link>;
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
752 </tag-desc>
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
753
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
754 <tag-name id="var_ssl_session_id"><var>$ssl_session_id</var></tag-name>
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
755 <tag-desc>
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
756 returns the session identifier of an established SSL connection;
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
757 </tag-desc>
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
758
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
759 <tag-name id="var_ssl_session_reused"><var>$ssl_session_reused</var></tag-name>
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
760 <tag-desc>
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
761 returns “<literal>r</literal>” if an SSL session was reused,
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
762 or “<literal>.</literal>” otherwise.
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
763 </tag-desc>
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
764
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
765 </list>
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
766 </para>
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
767
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
768 </section>
0dfb7628bfee Documented variables in ngx_stream_ssl_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1726
diff changeset
769
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
770 </module>