Mercurial > hg > nginx-site
comparison xml/en/docs/http/configuring_https_servers.xml @ 660:ba45bd0fc71e
configuring_https_servers: markup changes (mostly).
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Tue, 28 Aug 2012 09:59:56 +0000 |
parents | 77a3314c74a7 |
children | e1579b244800 |
comparison
equal
deleted
inserted
replaced
659:77a3314c74a7 | 660:ba45bd0fc71e |
---|---|
19 in the server block, and the locations of the server certificate | 19 in the server block, and the locations of the server certificate |
20 and private key files should be specified: | 20 and private key files should be specified: |
21 | 21 |
22 <programlisting> | 22 <programlisting> |
23 server { | 23 server { |
24 listen 443; | 24 listen 443; |
25 server_name www.example.com; | 25 server_name www.example.com; |
26 ssl on; | 26 ssl <b>on</b>; |
27 ssl_certificate www.example.com.crt; | 27 ssl_certificate <b>www.example.com.crt</b>; |
28 ssl_certificate_key www.example.com.key; | 28 ssl_certificate_key <b>www.example.com.key</b>; |
29 ssl_protocols SSLv3 TLSv1 TLSv1.1 TLSv1.2; | 29 ssl_protocols SSLv3 TLSv1 TLSv1.1 TLSv1.2; |
30 ssl_ciphers HIGH:!aNULL:!MD5; | 30 ssl_ciphers HIGH:!aNULL:!MD5; |
31 ... | 31 ... |
32 } | 32 } |
33 </programlisting> | 33 </programlisting> |
34 | 34 |
35 The server certificate is a public entity. | 35 The server certificate is a public entity. |
36 It is sent to every client that connects to the server. | 36 It is sent to every client that connects to the server. |
37 The private key is a secure entity and should be stored in a file with | 37 The private key is a secure entity and should be stored in a file with |
38 restricted access, however, it must be readable by nginx’s master process. | 38 restricted access, however, it must be readable by nginx’s master process. |
39 The private key may alternately be stored in the same file as the certificate: | 39 The private key may alternately be stored in the same file as the certificate: |
40 | 40 |
41 <programlisting> | 41 <programlisting> |
42 ssl_certificate www.example.com.cert; | 42 ssl_certificate www.example.com.cert; |
43 ssl_certificate_key www.example.com.cert; | 43 ssl_certificate_key www.example.com.cert; |
44 </programlisting> | 44 </programlisting> |
45 | 45 |
46 in which case the file access rights should also be restricted. | 46 in which case the file access rights should also be restricted. |
47 Although the certificate and the key are stored in one file, | 47 Although the certificate and the key are stored in one file, |
48 only the certificate is sent to a client. | 48 only the certificate is sent to a client. |
51 <para> | 51 <para> |
52 The directives <link doc="ngx_http_ssl_module.xml" id="ssl_protocols"/> and | 52 The directives <link doc="ngx_http_ssl_module.xml" id="ssl_protocols"/> and |
53 <link doc="ngx_http_ssl_module.xml" id="ssl_ciphers"/> | 53 <link doc="ngx_http_ssl_module.xml" id="ssl_ciphers"/> |
54 can be used to limit connections | 54 can be used to limit connections |
55 to include only the strong versions and ciphers of SSL/TLS. | 55 to include only the strong versions and ciphers of SSL/TLS. |
56 Since version 1.0.5, nginx uses “<literal>ssl_protocols SSLv3 TLSv1</literal>” | 56 Since version 1.0.5, nginx uses |
57 “<literal>ssl_protocols SSLv3 TLSv1</literal>” | |
57 and “<literal>ssl_ciphers HIGH:!aNULL:!MD5</literal>” by default, | 58 and “<literal>ssl_ciphers HIGH:!aNULL:!MD5</literal>” by default, |
58 so configuring them explicitly only makes sense for the earlier nginx versions. | 59 so configuring them explicitly only makes sense for the earlier nginx versions. |
59 Since versions 1.1.13 and 1.0.12, nginx uses | 60 Since versions 1.1.13 and 1.0.12, nginx uses |
60 “<literal>ssl_protocols SSLv3 TLSv1 TLSv1.1 TLSv1.2</literal>” by default. | 61 “<literal>ssl_protocols SSLv3 TLSv1 TLSv1.1 TLSv1.2</literal>” by default. |
61 </para> | 62 </para> |
94 The default cache timeout is 5 minutes. | 95 The default cache timeout is 5 minutes. |
95 It can be increased by using the | 96 It can be increased by using the |
96 <link doc="ngx_http_ssl_module.xml" id="ssl_session_timeout"/> | 97 <link doc="ngx_http_ssl_module.xml" id="ssl_session_timeout"/> |
97 directive. | 98 directive. |
98 Here is a sample configuration optimized for a quad core system | 99 Here is a sample configuration optimized for a quad core system |
99 with 10M shared session cache: | 100 with 10 megabyte shared session cache: |
100 | 101 |
101 <programlisting> | 102 <programlisting> |
102 <b>worker_processes 4</b>; | 103 <b>worker_processes 4</b>; |
103 | 104 |
104 http { | 105 http { |
105 <b>ssl_session_cache shared:SSL:10m</b>; | 106 <b>ssl_session_cache shared:SSL:10m</b>; |
106 <b>ssl_session_timeout 10m</b>; | 107 <b>ssl_session_timeout 10m</b>; |
107 | 108 |
108 server { | 109 server { |
109 listen 443; | 110 listen 443; |
110 server_name www.example.com; | 111 server_name www.example.com; |
111 <b>keepalive_timeout 70</b>; | 112 <b>keepalive_timeout 70</b>; |
112 | 113 |
113 ssl on; | 114 ssl on; |
114 ssl_certificate www.example.com.crt; | 115 ssl_certificate www.example.com.crt; |
115 ssl_certificate_key www.example.com.key; | 116 ssl_certificate_key www.example.com.key; |
116 ssl_protocols SSLv3 TLSv1 TLSv1.1 TLSv1.2; | 117 ssl_protocols SSLv3 TLSv1 TLSv1.1 TLSv1.2; |
117 ssl_ciphers HIGH:!aNULL:!MD5; | 118 ssl_ciphers HIGH:!aNULL:!MD5; |
118 ... | 119 ... |
119 </programlisting> | 120 </programlisting> |
120 </para> | 121 </para> |
121 | 122 |
122 </section> | 123 </section> |
140 <programlisting> | 141 <programlisting> |
141 $ cat www.example.com.crt bundle.crt > www.example.com.chained.crt | 142 $ cat www.example.com.crt bundle.crt > www.example.com.chained.crt |
142 </programlisting> | 143 </programlisting> |
143 | 144 |
144 The resulting file should be used in the | 145 The resulting file should be used in the |
145 <link doc="ngx_http_ssl_module.xml" id="ssl_certificate"/> | 146 <link doc="ngx_http_ssl_module.xml" id="ssl_certificate"/> directive: |
146 directive: | 147 |
147 | 148 <programlisting> |
148 <programlisting> | 149 server { |
149 server { | 150 listen 443; |
150 listen 443; | 151 server_name www.example.com; |
151 server_name www.example.com; | 152 ssl on; |
152 ssl on; | 153 ssl_certificate www.example.com.chained.crt; |
153 ssl_certificate www.example.com.chained.crt; | 154 ssl_certificate_key www.example.com.key; |
154 ssl_certificate_key www.example.com.key; | |
155 ... | 155 ... |
156 } | 156 } |
157 </programlisting> | 157 </programlisting> |
158 | 158 |
159 If the server certificate and the bundle have been concatenated in the wrong | 159 If the server certificate and the bundle have been concatenated in the wrong |
163 SSL_CTX_use_PrivateKey_file(" ... /www.example.com.key") failed | 163 SSL_CTX_use_PrivateKey_file(" ... /www.example.com.key") failed |
164 (SSL: error:0B080074:x509 certificate routines: | 164 (SSL: error:0B080074:x509 certificate routines: |
165 X509_check_private_key:key values mismatch) | 165 X509_check_private_key:key values mismatch) |
166 </programlisting> | 166 </programlisting> |
167 | 167 |
168 because nginx has tried to use the private key with the bundle’s | 168 because nginx has tried to use the private key with the bundle’s |
169 first certificate instead of the server certificate. | 169 first certificate instead of the server certificate. |
170 </para> | 170 </para> |
171 | 171 |
172 <para> | 172 <para> |
173 Browsers usually store intermediate certificates which they receive | 173 Browsers usually store intermediate certificates which they receive |
201 /OU=ValiCert Class 2 Policy Validation Authority | 201 /OU=ValiCert Class 2 Policy Validation Authority |
202 /CN=http://www.valicert.com//emailAddress=info@valicert.com | 202 /CN=http://www.valicert.com//emailAddress=info@valicert.com |
203 ... | 203 ... |
204 </programlisting> | 204 </programlisting> |
205 | 205 |
206 In this example the subject (“<i>s</i>”) of the | 206 In this example the subject (“<i>s</i>”) of the |
207 <literal>www.GoDaddy.com</literal> server certificate #0 is signed by an issuer | 207 <literal>www.GoDaddy.com</literal> server certificate #0 is signed by an issuer |
208 (“<i>i</i>”) which itself is the subject of the certificate #1, | 208 (“<i>i</i>”) which itself is the subject of the certificate #1, |
209 which is signed by an issuer which itself is the subject of the certificate #2, | 209 which is signed by an issuer which itself is the subject of the certificate #2, |
210 which signed by the well-known issuer <i>ValiCert, Inc.</i> | 210 which signed by the well-known issuer <i>ValiCert, Inc.</i> |
211 whose certificate is stored in the browsers’ built-in | 211 whose certificate is stored in the browsers’ built-in |
212 certificate base (that lay in the house that Jack built). | 212 certificate base (that lay in the house that Jack built). |
213 </para> | 213 </para> |
214 | 214 |
215 <para> | 215 <para> |
216 If a certificate bundle has not been added, only the server certificate #0 | 216 If a certificate bundle has not been added, only the server certificate #0 |
228 by deleting the directive “<literal>ssl on</literal>” | 228 by deleting the directive “<literal>ssl on</literal>” |
229 and adding the <literal>ssl</literal> parameter for *:443 port: | 229 and adding the <literal>ssl</literal> parameter for *:443 port: |
230 | 230 |
231 <programlisting> | 231 <programlisting> |
232 server { | 232 server { |
233 listen 80; | 233 listen 80; |
234 listen 443 ssl; | 234 listen 443 ssl; |
235 server_name www.example.com; | 235 server_name www.example.com; |
236 ssl_certificate www.example.com.crt; | 236 ssl_certificate www.example.com.crt; |
237 ssl_certificate_key www.example.com.key; | 237 ssl_certificate_key www.example.com.key; |
238 ... | 238 ... |
239 } | 239 } |
240 </programlisting> | 240 </programlisting> |
241 | 241 |
242 <note> | 242 <note> |
243 Prior to 0.8.21, nginx only allows the <literal>ssl</literal> parameter | 243 Prior to 0.8.21, nginx only allows the <literal>ssl</literal> parameter |
244 to be set on listen sockets with the <literal>default</literal> parameter: | 244 to be set on listen sockets with the <literal>default</literal> parameter: |
245 <programlisting> | 245 <programlisting> |
246 listen 443 default ssl; | 246 listen 443 default ssl; |
247 </programlisting> | 247 </programlisting> |
248 </note> | 248 </note> |
249 </para> | 249 </para> |
250 | 250 |
251 </section> | 251 </section> |
257 A common issue arises when configuring two or more HTTPS servers | 257 A common issue arises when configuring two or more HTTPS servers |
258 listening on a single IP address: | 258 listening on a single IP address: |
259 | 259 |
260 <programlisting> | 260 <programlisting> |
261 server { | 261 server { |
262 listen 443; | 262 listen 443; |
263 server_name www.example.com; | 263 server_name www.example.com; |
264 ssl on; | 264 ssl on; |
265 ssl_certificate www.example.com.crt; | 265 ssl_certificate www.example.com.crt; |
266 ... | 266 ... |
267 } | 267 } |
268 | 268 |
269 server { | 269 server { |
270 listen 443; | 270 listen 443; |
271 server_name www.example.org; | 271 server_name www.example.org; |
272 ssl on; | 272 ssl on; |
273 ssl_certificate www.example.org.crt; | 273 ssl_certificate www.example.org.crt; |
274 ... | 274 ... |
275 } | 275 } |
276 </programlisting> | 276 </programlisting> |
277 | 277 |
278 With this configuration a browser receives the certificate of the default | 278 With this configuration a browser receives the default server’s certificate, |
279 server, i.e., <literal>www.example.com</literal> regardless of the requested server name. | 279 i.e. <literal>www.example.com</literal> regardless of the requested server name. |
280 This is caused by SSL protocol behaviour. The SSL connection is established | 280 This is caused by SSL protocol behaviour. |
281 before the browser sends an HTTP request and nginx does not know | 281 The SSL connection is established before the browser sends an HTTP request |
282 the name of the requested server. Therefore, it may only offer the certificate | 282 and nginx does not know the name of the requested server. |
283 of the default server. | 283 Therefore, it may only offer the default server’s certificate. |
284 </para> | 284 </para> |
285 | 285 |
286 <para> | 286 <para> |
287 The oldest and most robust method to resolve the issue | 287 The oldest and most robust method to resolve the issue |
288 is to assign a separate IP address for every HTTPS server: | 288 is to assign a separate IP address for every HTTPS server: |
289 | 289 |
290 <programlisting> | 290 <programlisting> |
291 server { | 291 server { |
292 listen 192.168.1.1:443; | 292 listen 192.168.1.1:443; |
293 server_name www.example.com; | 293 server_name www.example.com; |
294 ssl on; | 294 ssl on; |
295 ssl_certificate www.example.com.crt; | 295 ssl_certificate www.example.com.crt; |
296 ... | 296 ... |
297 } | 297 } |
298 | 298 |
299 server { | 299 server { |
300 listen 192.168.1.2:443; | 300 listen 192.168.1.2:443; |
301 server_name www.example.org; | 301 server_name www.example.org; |
302 ssl on; | 302 ssl on; |
303 ssl_certificate www.example.org.crt; | 303 ssl_certificate www.example.org.crt; |
304 ... | 304 ... |
305 } | 305 } |
306 </programlisting> | 306 </programlisting> |
307 </para> | 307 </para> |
308 | 308 |
309 </section> | 309 </section> |
310 | 310 |
311 | 311 |
312 <section id="certificate_with_several_names" | 312 <section id="certificate_with_several_names" |
313 name="A SSL certificate with several names"> | 313 name="An SSL certificate with several names"> |
314 | 314 |
315 <para> | 315 <para> |
316 There are other ways to share a single IP address between several | 316 There are other ways to share a single IP address between several |
317 HTTPS servers, however, all of them have drawbacks. | 317 HTTPS servers, however, all of them have drawbacks. |
318 One way is to use a certificate with several names in | 318 One way is to use a certificate with several names in |
319 the SubjectAltName certificate field, for example, <literal>www.example.com</literal> | 319 the SubjectAltName certificate field, for example, |
320 and <literal>www.example.org</literal>. | 320 <literal>www.example.com</literal> and <literal>www.example.org</literal>. |
321 However, the SubjectAltName field length is limited. | 321 However, the SubjectAltName field length is limited. |
322 </para> | 322 </para> |
323 | 323 |
324 <para> | 324 <para> |
325 Another way is to use a certificate with a wildcard name, for example, | 325 Another way is to use a certificate with a wildcard name, for example, |
326 <literal>*.example.org</literal>. This certificate matches | 326 <literal>*.example.org</literal>. |
327 <literal>www.example.org</literal>, but does not match <literal>example.org</literal> | 327 This certificate matches <literal>www.example.org</literal>, but does not match |
328 and <literal>www.sub.example.org</literal>. These two methods can also be combined. | 328 <literal>example.org</literal> and <literal>www.sub.example.org</literal>. |
329 A certificate may contain exact and wildcard names in the SubjectAltName field, | 329 These two methods can also be combined. |
330 for example, <literal>example.org</literal> and <literal>*.example.org</literal>. | 330 A certificate may contain exact and wildcard names in the |
331 SubjectAltName field, for example, | |
332 <literal>example.org</literal> and <literal>*.example.org</literal>. | |
331 </para> | 333 </para> |
332 | 334 |
333 <para> | 335 <para> |
334 It is better to place a certificate file with several names and | 336 It is better to place a certificate file with several names and |
335 its private key file at the <i>http</i> level of configuration | 337 its private key file at the <i>http</i> level of configuration |
336 to inherit their single memory copy in all servers: | 338 to inherit their single memory copy in all servers: |
337 | 339 |
338 <programlisting> | 340 <programlisting> |
339 ssl_certificate common.crt; | 341 ssl_certificate common.crt; |
340 ssl_certificate_key common.key; | 342 ssl_certificate_key common.key; |
341 | 343 |
342 server { | 344 server { |
343 listen 443; | 345 listen 443; |
344 server_name www.example.com; | 346 server_name www.example.com; |
345 ssl on; | 347 ssl on; |
346 ... | 348 ... |
347 } | 349 } |
348 | 350 |
349 server { | 351 server { |
350 listen 443; | 352 listen 443; |
351 server_name www.example.org; | 353 server_name www.example.org; |
352 ssl on; | 354 ssl on; |
353 ... | 355 ... |
354 } | 356 } |
355 </programlisting> | 357 </programlisting> |
356 </para> | 358 </para> |
357 | 359 |
405 <para> | 407 <para> |
406 In order to use SNI in nginx, it must be supported in both the | 408 In order to use SNI in nginx, it must be supported in both the |
407 OpenSSL library with which the nginx binary has been built as well as | 409 OpenSSL library with which the nginx binary has been built as well as |
408 the library to which it is being dynamically linked at run time. | 410 the library to which it is being dynamically linked at run time. |
409 OpenSSL supports SNI since 0.9.8f version if it was built with config option | 411 OpenSSL supports SNI since 0.9.8f version if it was built with config option |
410 <nobr>“--enable-tlsext”.</nobr> | 412 <nobr>“--enable-tlsext”.</nobr> |
411 Since OpenSSL 0.9.8j this option is enabled by default. | 413 Since OpenSSL 0.9.8j this option is enabled by default. |
412 If nginx was built with SNI support, then nginx will show this | 414 If nginx was built with SNI support, then nginx will show this |
413 when run with the “-V” switch: | 415 when run with the “-V” switch: |
414 | 416 |
415 <programlisting> | 417 <programlisting> |
416 $ nginx -V | 418 $ nginx -V |
417 ... | 419 ... |
418 TLS SNI support enabled | 420 TLS SNI support enabled |
436 | 438 |
437 <para> | 439 <para> |
438 <list type="bullet"> | 440 <list type="bullet"> |
439 | 441 |
440 <listitem> | 442 <listitem> |
441 The SNI support status has been shown by the “-V” switch | 443 The SNI support status has been shown by the “-V” switch |
442 since 0.8.21 and 0.7.62. | 444 since 0.8.21 and 0.7.62. |
443 </listitem> | 445 </listitem> |
444 | 446 |
445 <listitem> | 447 <listitem> |
446 The <literal>ssl</literal> parameter of the | 448 The <literal>ssl</literal> parameter of the |