Mercurial > hg > nginx-site

comparison xml/en/docs/stream/ngx_stream_ssl_module.xml @ 1450:f5b5eefc43cb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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>