Mercurial > hg > nginx-site
comparison xml/en/docs/stream/ngx_stream_ssl_module.xml @ 1450:f5b5eefc43cb
Updated commercial docs for the upcoming release.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Thu, 09 Apr 2015 19:18:54 +0300 |
parents | |
children | acba294382d6 |
comparison
equal
deleted
inserted
replaced
1449:c79501e16e26 | 1450:f5b5eefc43cb |
---|---|
1 <?xml version="1.0"?> | |
2 | |
3 <!-- | |
4 Copyright (C) Nginx, Inc. | |
5 --> | |
6 | |
7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> | |
8 | |
9 <module name="Module ngx_stream_ssl_module" | |
10 link="/en/docs/stream/ngx_stream_ssl_module.html" | |
11 lang="en" | |
12 rev="1"> | |
13 | |
14 <section id="summary"> | |
15 | |
16 <para> | |
17 The <literal>ngx_stream_ssl_module</literal> module (1.7.10) | |
18 provides the necessary support for a stream proxy server to work with | |
19 the SSL/TLS protocol. | |
20 </para> | |
21 | |
22 <para> | |
23 <note> | |
24 This module is available as part of our | |
25 <commercial_version>commercial subscription</commercial_version>. | |
26 </note> | |
27 </para> | |
28 | |
29 </section> | |
30 | |
31 | |
32 <section id="directives" name="Directives"> | |
33 | |
34 <directive name="ssl_certificate"> | |
35 <syntax><value>file</value></syntax> | |
36 <default/> | |
37 <context>stream</context> | |
38 <context>server</context> | |
39 | |
40 <para> | |
41 Specifies a file with the certificate in the PEM format for the given | |
42 server. | |
43 If intermediate certificates should be specified in addition to a primary | |
44 certificate, they should be specified in the same file in the following | |
45 order: the primary certificate comes first, then the intermediate certificates. | |
46 A secret key in the PEM format may be placed in the same file. | |
47 </para> | |
48 | |
49 </directive> | |
50 | |
51 | |
52 <directive name="ssl_certificate_key"> | |
53 <syntax><value>file</value></syntax> | |
54 <default/> | |
55 <context>stream</context> | |
56 <context>server</context> | |
57 | |
58 <para> | |
59 Specifies a file with the secret key in the PEM format for the given | |
60 server. | |
61 </para> | |
62 | |
63 </directive> | |
64 | |
65 | |
66 <directive name="ssl_ciphers"> | |
67 <syntax><value>ciphers</value></syntax> | |
68 <default>HIGH:!aNULL:!MD5</default> | |
69 <context>stream</context> | |
70 <context>server</context> | |
71 | |
72 <para> | |
73 Specifies the enabled ciphers. | |
74 The ciphers are specified in the format understood by the | |
75 OpenSSL library, for example: | |
76 <example> | |
77 ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP; | |
78 </example> | |
79 </para> | |
80 | |
81 <para> | |
82 The full list can be viewed using the | |
83 “<command>openssl ciphers</command>” command. | |
84 </para> | |
85 | |
86 </directive> | |
87 | |
88 | |
89 <directive name="ssl_dhparam"> | |
90 <syntax><value>file</value></syntax> | |
91 <default/> | |
92 <context>stream</context> | |
93 <context>server</context> | |
94 | |
95 <para> | |
96 Specifies a <value>file</value> with DH parameters for EDH ciphers. | |
97 </para> | |
98 | |
99 </directive> | |
100 | |
101 | |
102 <directive name="ssl_ecdh_curve"> | |
103 <syntax><value>curve</value></syntax> | |
104 <default>prime256v1</default> | |
105 <context>stream</context> | |
106 <context>server</context> | |
107 | |
108 <para> | |
109 Specifies a <value>curve</value> for ECDHE ciphers. | |
110 </para> | |
111 | |
112 </directive> | |
113 | |
114 | |
115 <directive name="ssl_handshake_timeout"> | |
116 <syntax><value>time</value></syntax> | |
117 <default>60s</default> | |
118 <context>stream</context> | |
119 <context>server</context> | |
120 | |
121 <para> | |
122 Specifies a timeout for the SSL handshake to complete. | |
123 </para> | |
124 | |
125 </directive> | |
126 | |
127 | |
128 <directive name="ssl_password_file"> | |
129 <syntax><value>file</value></syntax> | |
130 <default/> | |
131 <context>stream</context> | |
132 <context>server</context> | |
133 | |
134 <para> | |
135 Specifies a <value>file</value> with passphrases for | |
136 <link id="ssl_certificate_key">secret keys</link> | |
137 where each passphrase is specified on a separate line. | |
138 Passphrases are tried in turn when loading the key. | |
139 </para> | |
140 | |
141 <para> | |
142 Example: | |
143 <example> | |
144 stream { | |
145 ssl_password_file /etc/keys/global.pass; | |
146 ... | |
147 | |
148 server { | |
149 listen 127.0.0.1:12345; | |
150 ssl_certificate_key /etc/keys/first.key; | |
151 } | |
152 | |
153 server { | |
154 listen 127.0.0.1:12346; | |
155 | |
156 # named pipe can also be used instead of a file | |
157 ssl_password_file /etc/keys/fifo; | |
158 ssl_certificate_key /etc/keys/second.key; | |
159 } | |
160 } | |
161 </example> | |
162 </para> | |
163 | |
164 </directive> | |
165 | |
166 | |
167 <directive name="ssl_prefer_server_ciphers"> | |
168 <syntax><literal>on</literal> | <literal>off</literal></syntax> | |
169 <default>off</default> | |
170 <context>stream</context> | |
171 <context>server</context> | |
172 | |
173 <para> | |
174 Specifies that server ciphers should be preferred over client ciphers | |
175 when the SSLv3 and TLS protocols are used. | |
176 </para> | |
177 | |
178 </directive> | |
179 | |
180 | |
181 <directive name="ssl_protocols"> | |
182 <syntax> | |
183 [<literal>SSLv2</literal>] | |
184 [<literal>SSLv3</literal>] | |
185 [<literal>TLSv1</literal>] | |
186 [<literal>TLSv1.1</literal>] | |
187 [<literal>TLSv1.2</literal>]</syntax> | |
188 <default>SSLv3 TLSv1 TLSv1.1 TLSv1.2</default> | |
189 <context>stream</context> | |
190 <context>server</context> | |
191 | |
192 <para> | |
193 Enables the specified protocols. | |
194 The <literal>TLSv1.1</literal> and <literal>TLSv1.2</literal> parameters work | |
195 only when the OpenSSL library of version 1.0.1 or higher is used. | |
196 </para> | |
197 | |
198 </directive> | |
199 | |
200 | |
201 <directive name="ssl_session_cache"> | |
202 <syntax> | |
203 <literal>off</literal> | | |
204 <literal>none</literal> | | |
205 [<literal>builtin</literal>[:<value>size</value>]] | |
206 [<literal>shared</literal>:<value>name</value>:<value>size</value>]</syntax> | |
207 <default>none</default> | |
208 <context>stream</context> | |
209 <context>server</context> | |
210 | |
211 <para> | |
212 Sets the types and sizes of caches that store session parameters. | |
213 A cache can be of any of the following types: | |
214 <list type="tag"> | |
215 | |
216 <tag-name><literal>off</literal></tag-name> | |
217 <tag-desc> | |
218 the use of a session cache is strictly prohibited: | |
219 nginx explicitly tells a client that sessions may not be reused. | |
220 </tag-desc> | |
221 | |
222 <tag-name><literal>none</literal></tag-name> | |
223 <tag-desc> | |
224 the use of a session cache is gently disallowed: | |
225 nginx tells a client that sessions may be reused, but does not | |
226 actually store session parameters in the cache. | |
227 </tag-desc> | |
228 | |
229 <tag-name><literal>builtin</literal></tag-name> | |
230 <tag-desc> | |
231 a cache built in OpenSSL; used by one worker process only. | |
232 The cache size is specified in sessions. | |
233 If size is not given, it is equal to 20480 sessions. | |
234 Use of the built-in cache can cause memory fragmentation. | |
235 </tag-desc> | |
236 | |
237 <tag-name><literal>shared</literal></tag-name> | |
238 <tag-desc> | |
239 a cache shared between all worker processes. | |
240 The cache size is specified in bytes; one megabyte can store | |
241 about 4000 sessions. | |
242 Each shared cache should have an arbitrary name. | |
243 A cache with the same name can be used in several | |
244 servers. | |
245 </tag-desc> | |
246 | |
247 </list> | |
248 </para> | |
249 | |
250 <para> | |
251 Both cache types can be used simultaneously, for example: | |
252 <example> | |
253 ssl_session_cache builtin:1000 shared:SSL:10m; | |
254 </example> | |
255 but using only shared cache without the built-in cache should | |
256 be more efficient. | |
257 </para> | |
258 | |
259 </directive> | |
260 | |
261 | |
262 <directive name="ssl_session_ticket_key"> | |
263 <syntax><value>file</value></syntax> | |
264 <default/> | |
265 <context>stream</context> | |
266 <context>server</context> | |
267 | |
268 <para> | |
269 Sets a <value>file</value> with the secret key used to encrypt | |
270 and decrypt TLS session tickets. | |
271 The directive is necessary if the same key has to be shared between | |
272 multiple servers. | |
273 By default, a randomly generated key is used. | |
274 </para> | |
275 | |
276 <para> | |
277 If several keys are specified, only the first key is | |
278 used to encrypt TLS session tickets. | |
279 This allows configuring key rotation, for example: | |
280 <example> | |
281 ssl_session_ticket_key current.key; | |
282 ssl_session_ticket_key previous.key; | |
283 </example> | |
284 </para> | |
285 | |
286 <para> | |
287 The <value>file</value> must contain 48 bytes of random data and can | |
288 be created using the following command: | |
289 <example> | |
290 openssl rand 48 > ticket.key | |
291 </example> | |
292 </para> | |
293 | |
294 </directive> | |
295 | |
296 | |
297 <directive name="ssl_session_tickets"> | |
298 <syntax><literal>on</literal> | <literal>off</literal></syntax> | |
299 <default>on</default> | |
300 <context>stream</context> | |
301 <context>server</context> | |
302 | |
303 <para> | |
304 Enables or disables session resumption through | |
305 <link url="http://tools.ietf.org/html/rfc5077">TLS session tickets</link>. | |
306 </para> | |
307 | |
308 </directive> | |
309 | |
310 | |
311 <directive name="ssl_session_timeout"> | |
312 <syntax><value>time</value></syntax> | |
313 <default>5m</default> | |
314 <context>stream</context> | |
315 <context>server</context> | |
316 | |
317 <para> | |
318 Specifies a time during which a client may reuse the | |
319 session parameters stored in a cache. | |
320 </para> | |
321 | |
322 </directive> | |
323 | |
324 </section> | |
325 | |
326 </module> |