Mercurial > hg > nginx-site
comparison xml/en/docs/http/configuring_https_servers.xml @ 0:61e04fc01027
Initial import of the nginx.org website.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Thu, 11 Aug 2011 12:19:13 +0000 |
parents | |
children | b33866d80056 |
comparison
equal
deleted
inserted
replaced
-1:000000000000 | 0:61e04fc01027 |
---|---|
1 <!DOCTYPE digest SYSTEM "../../../../dtd/article.dtd"> | |
2 | |
3 <article title="Configuring HTTPS servers" | |
4 link="/en/docs/http/configuring_https_servers.html" | |
5 lang="en" | |
6 author="Igor Sysoev" | |
7 editor="Brian Mercer"> | |
8 | |
9 <section> | |
10 | |
11 <para> | |
12 To configure an HTTPS server you must enable the SSL protocol | |
13 in the server block, and specify the locations of the server certificate | |
14 and private key files: | |
15 | |
16 <programlisting> | |
17 server { | |
18 listen 443; | |
19 server_name www.nginx.com; | |
20 ssl on; | |
21 ssl_certificate www.nginx.com.crt; | |
22 ssl_certificate_key www.nginx.com.key; | |
23 ssl_protocols SSLv3 TLSv1; | |
24 ssl_ciphers HIGH:!ADH:!MD5; | |
25 ... | |
26 } | |
27 </programlisting> | |
28 | |
29 The server certificate is a public entity. | |
30 It is sent to every client that connects to the server. | |
31 The private key is a secure entity and should be stored in a file with | |
32 restricted access, however, it must be readable by nginx’s master process. | |
33 The private key may alternately be stored in the same file as the certificate: | |
34 | |
35 <programlisting> | |
36 ssl_certificate www.nginx.com.cert; | |
37 ssl_certificate_key www.nginx.com.cert; | |
38 </programlisting> | |
39 | |
40 in which case the file access rights should also be restricted. | |
41 Although the certificate and the key are stored in one file, | |
42 only the certificate is sent to a client. | |
43 </para> | |
44 | |
45 <para> | |
46 The directives <dirname>ssl_protocols</dirname> and | |
47 <dirname>ssl_ciphers</dirname> may be used to limit connections | |
48 to strong SSL protocol versions and ciphers. | |
49 Since version 0.8.20, nginx uses <dirname>ssl_protocols SSLv3 TLSv1</dirname> | |
50 and <dirname>ssl_ciphers HIGH:!ADH:!MD5</dirname> by default, | |
51 so they should only be set for earlier nginx versions. | |
52 </para> | |
53 | |
54 </section> | |
55 | |
56 | |
57 <section name="optimization" title="HTTPS server optimization"> | |
58 | |
59 <para> | |
60 SSL operations consume extra CPU resources. | |
61 On multi-processor systems you should run several worker processes: | |
62 no less than the number of available CPU cores. | |
63 The most CPU-intensive operation is the SSL handshake. | |
64 There are two ways to minimize the number of these operations per client: | |
65 the first is by enabling keepalive connections to send several | |
66 requests via one connection and the second is to reuse SSL session | |
67 parameters to avoid SSL handshakes for parallel and subsequent connections. | |
68 The sessions are stored in an SSL session cache shared between workers | |
69 and configured by an <dirname>ssl_session_cache</dirname> directive. | |
70 One megabyte of the cache contains about 4000 sessions. | |
71 The default cache timeout is 5 minutes. It can be increased by using | |
72 the <dirname>ssl_session_timeout</dirname> directive. | |
73 Here is a sample configuration optimized for a quad core system | |
74 with 10M shared session cache: | |
75 | |
76 <programlisting> | |
77 <b>worker_processes 4</b>; | |
78 | |
79 http { | |
80 <b>ssl_session_cache shared:SSL:10m</b>; | |
81 <b>ssl_session_timeout 10m</b>; | |
82 | |
83 server { | |
84 listen 443; | |
85 server_name www.nginx.com; | |
86 <b>keepalive_timeout 70</b>; | |
87 | |
88 ssl on; | |
89 ssl_certificate www.nginx.com.crt; | |
90 ssl_certificate_key www.nginx.com.key; | |
91 ssl_protocols SSLv3 TLSv1; | |
92 ssl_ciphers HIGH:!ADH:!MD5; | |
93 ... | |
94 </programlisting> | |
95 </para> | |
96 | |
97 </section> | |
98 | |
99 | |
100 <section name="chains" title="SSL certificate chains"> | |
101 | |
102 <para> | |
103 Some browsers may complain about a certificate signed by a well-known | |
104 certificate authority, while other browsers may accept the certificate | |
105 without issues. | |
106 This occurs because the issuing authority has signed the server certificate | |
107 using an intermediate certificate that is not present in the certificate | |
108 base of well-known trusted certificate authorities which is distributed | |
109 with a particular browser. | |
110 In this case the authority provides a bundle of chained certificates | |
111 which should be concatenated to the signed server certificate. | |
112 The server certificate must appear before the chained certificates | |
113 in the combined file: | |
114 | |
115 <programlisting> | |
116 $ cat www.nginx.com.crt bundle.crt > www.nginx.com.chained.crt | |
117 </programlisting> | |
118 | |
119 The resulting file should be used in the <dirname>ssl_certificate</dirname> | |
120 directive: | |
121 | |
122 <programlisting> | |
123 server { | |
124 listen 443; | |
125 server_name www.nginx.com; | |
126 ssl on; | |
127 ssl_certificate www.nginx.com.chained.crt; | |
128 ssl_certificate_key www.nginx.com.key; | |
129 ... | |
130 } | |
131 </programlisting> | |
132 | |
133 If the server certificate and the bundle have been concatenated in the wrong | |
134 order, nginx will fail to start and will display the error message: | |
135 | |
136 <programlisting> | |
137 SSL_CTX_use_PrivateKey_file(" ... /www.nginx.com.key") failed | |
138 (SSL: error:0B080074:x509 certificate routines: | |
139 X509_check_private_key:key values mismatch) | |
140 </programlisting> | |
141 | |
142 because nginx has tried to use the private key with the bundle’s | |
143 first certificate instead of the server certificate. | |
144 </para> | |
145 | |
146 <para> | |
147 Browsers usually store intermediate certificates which they receive | |
148 and which are signed by trusted authorities, so actively used browsers | |
149 may already have the required intermediate certificates and | |
150 may not complain about a certificate sent without a chained bundle. | |
151 To ensure the server sends the complete certificate chain, | |
152 you may use the <path>openssl</path> command line utility, for example: | |
153 | |
154 <programlisting> | |
155 $ openssl s_client -connect www.godaddy.com:443 | |
156 ... | |
157 Certificate chain | |
158 0 s:/C=US/ST=Arizona/L=Scottsdale/1.3.6.1.4.1.311.60.2.1.3=US | |
159 /1.3.6.1.4.1.311.60.2.1.2=AZ/O=GoDaddy.com, Inc | |
160 /OU=MIS Department/<b>CN=www.GoDaddy.com</b> | |
161 /serialNumber=0796928-7/2.5.4.15=V1.0, Clause 5.(b) | |
162 i:/C=US/ST=Arizona/L=Scottsdale/O=GoDaddy.com, Inc. | |
163 /OU=http://certificates.godaddy.com/repository | |
164 /CN=Go Daddy Secure Certification Authority | |
165 /serialNumber=07969287 | |
166 1 s:/C=US/ST=Arizona/L=Scottsdale/O=GoDaddy.com, Inc. | |
167 /OU=http://certificates.godaddy.com/repository | |
168 /CN=Go Daddy Secure Certification Authority | |
169 /serialNumber=07969287 | |
170 i:/C=US/O=The Go Daddy Group, Inc. | |
171 /OU=Go Daddy Class 2 Certification Authority | |
172 2 s:/C=US/O=The Go Daddy Group, Inc. | |
173 /OU=Go Daddy Class 2 Certification Authority | |
174 i:/L=ValiCert Validation Network/O=<b>ValiCert, Inc.</b> | |
175 /OU=ValiCert Class 2 Policy Validation Authority | |
176 /CN=http://www.valicert.com//emailAddress=info@valicert.com | |
177 ... | |
178 </programlisting> | |
179 | |
180 In this example the subject (“<i>s</i>”) of the | |
181 <url>www.GoDaddy.com</url> server certificate #0 is signed by an issuer | |
182 (“<i>i</i>”) which itself is the subject of the certificate #1, | |
183 which is signed by an issuer which itself is the subject of the certificate #2, | |
184 which signed by the well-known issuer <i>ValiCert, Inc.</i> | |
185 whose certificate is stored in the browsers’ built-in | |
186 certificate base (that lay in the house that Jack built). | |
187 </para> | |
188 | |
189 <para> | |
190 If you have not added the certificates bundle, you will see only your server | |
191 certificate #0. | |
192 </para> | |
193 | |
194 </section> | |
195 | |
196 | |
197 <section name="single_http_https_server" title="A single HTTP/HTTPS server"> | |
198 | |
199 <para> | |
200 It is good practice to configure separate servers for HTTP and HTTPS | |
201 protocols from the very start. Although their functionalities currently | |
202 seem equal, this may change significantly in the future | |
203 and using a consolidated server may become problematic. | |
204 However, if HTTP and HTTPS servers are equal, | |
205 and you prefer not to think about the future, | |
206 you may configure a single server that handles both HTTP and HTTPS requests | |
207 by deleting the directive <dirname>ssl on</dirname> | |
208 and adding the <dirname>ssl</dirname> parameter for *:443 port: | |
209 | |
210 <programlisting> | |
211 server { | |
212 listen 80; | |
213 listen 443 ssl; | |
214 server_name www.nginx.com; | |
215 ssl_certificate www.nginx.com.crt; | |
216 ssl_certificate_key www.nginx.com.key; | |
217 ... | |
218 } | |
219 </programlisting> | |
220 | |
221 <note> | |
222 Prior to 0.8.21, nginx only allows the <dirname>ssl</dirname> parameter | |
223 to be set on listen sockets with the <dirname>default</dirname> parameter: | |
224 <programlisting> | |
225 listen 443 default ssl; | |
226 </programlisting> | |
227 </note> | |
228 </para> | |
229 | |
230 </section> | |
231 | |
232 | |
233 <section name="name_based_https_servers" title="Name-based HTTPS servers"> | |
234 | |
235 <para> | |
236 A common issue arises when configuring two or more HTTPS servers | |
237 listening on a single IP address: | |
238 | |
239 <programlisting> | |
240 server { | |
241 listen 443; | |
242 server_name www.nginx.com; | |
243 ssl on; | |
244 ssl_certificate www.nginx.com.crt; | |
245 ... | |
246 } | |
247 | |
248 server { | |
249 listen 443; | |
250 server_name www.nginx.org; | |
251 ssl on; | |
252 ssl_certificate www.nginx.org.crt; | |
253 ... | |
254 } | |
255 </programlisting> | |
256 | |
257 With this configuration a browser receives the certificate of the default | |
258 server, i.e., <url>www.nginx.com</url> regardless of the requested server name. | |
259 This is caused by SSL protocol behaviour. The SSL connection is established | |
260 before the browser sends an HTTP request and nginx does not know | |
261 the name of the requested server. Therefore, it may only offer the certificate | |
262 of the default server. | |
263 </para> | |
264 | |
265 <para> | |
266 The oldest and most robust method to resolve the issue | |
267 is to assign a separate IP address for every HTTPS server: | |
268 | |
269 <programlisting> | |
270 server { | |
271 listen 192.168.1.1:443; | |
272 server_name www.nginx.com; | |
273 ssl on; | |
274 ssl_certificate www.nginx.com.crt; | |
275 ... | |
276 } | |
277 | |
278 server { | |
279 listen 192.168.1.2:443; | |
280 server_name www.nginx.org; | |
281 ssl on; | |
282 ssl_certificate www.nginx.org.crt; | |
283 ... | |
284 } | |
285 </programlisting> | |
286 </para> | |
287 | |
288 </section> | |
289 | |
290 | |
291 <section name="certificate_with_several_names" | |
292 title="A SSL certificate with several names"> | |
293 | |
294 <para> | |
295 There are other ways to share a single IP address between several | |
296 HTTPS servers, however, all of them have drawbacks. | |
297 One way is to use a certificate with several names in | |
298 the SubjectAltName certificate field, for example, <url>www.nginx.com</url> | |
299 and <url>www.nginx.org</url>. | |
300 However, the SubjectAltName field length is limited. | |
301 </para> | |
302 | |
303 <para> | |
304 Another way is to use a certificate with a wildcard name, for example, | |
305 <url>*.nginx.org</url>. This certificate matches | |
306 <url>www.nginx.org</url>, but does not match <url>nginx.org</url> | |
307 and <url>www.sub.nginx.org</url>. These two methods can also be combined. | |
308 A certificate may contain exact and wildcard names in the SubjectAltName field, | |
309 for example, <url>nginx.org</url> and <url>*.nginx.org</url>. | |
310 </para> | |
311 | |
312 <para> | |
313 It is better to place a certificate file with several names and | |
314 its private key file at the <i>http</i> level of configuration | |
315 to inherit their single memory copy in all servers: | |
316 | |
317 <programlisting> | |
318 ssl_certificate common.crt; | |
319 ssl_certificate_key common.key; | |
320 | |
321 server { | |
322 listen 443; | |
323 server_name www.nginx.com; | |
324 ssl on; | |
325 ... | |
326 } | |
327 | |
328 server { | |
329 listen 443; | |
330 server_name www.nginx.org; | |
331 ssl on; | |
332 ... | |
333 } | |
334 </programlisting> | |
335 </para> | |
336 | |
337 </section> | |
338 | |
339 | |
340 <section name="sni" title="Server Name Indication"> | |
341 | |
342 <para> | |
343 A more generic solution for running several HTTPS servers on a single | |
344 IP address is | |
345 <a href="http://en.wikipedia.org/wiki/Server_Name_Indication">TLSv1.1 | |
346 Server Name Indication extension</a> (SNI, RFC3546), | |
347 which allows a browser to pass a requested server name during the SSL handshake | |
348 and, therefore, the server will know which certificate it should use | |
349 for the connection. | |
350 However, SNI has limited browser support. | |
351 Currently it is supported starting with the following browsers versions: | |
352 </para> | |
353 | |
354 <list> | |
355 | |
356 <item> | |
357 Opera 8.0; | |
358 </item> | |
359 | |
360 <item> | |
361 MSIE 7.0 (but only on Windows Vista or higher); | |
362 </item> | |
363 | |
364 <item> | |
365 Firefox 2.0 and other browsers using Mozilla Platform rv:1.8.1; | |
366 </item> | |
367 | |
368 <item> | |
369 Safari 3.2.1 (Windows version supports SNI on Vista or higher); | |
370 </item> | |
371 | |
372 <item> | |
373 and Chrome (Windows version supports SNI on Vista or higher, too). | |
374 </item> | |
375 | |
376 </list> | |
377 | |
378 <para> | |
379 In order to use SNI in nginx, it must be supported in both the | |
380 OpenSSL library with which the nginx binary has been built as well as | |
381 the library to which it is being dynamically linked at run time. | |
382 OpenSSL supports SNI since 0.9.8f version if it was built with config option | |
383 <nobr>“--enable-tlsext”.</nobr> | |
384 Since OpenSSL 0.9.8j this option is enabled by default. | |
385 If nginx was built with SNI support, then nginx will show this | |
386 when run with the “-V” switch: | |
387 | |
388 <programlisting> | |
389 $ nginx -V | |
390 ... | |
391 TLS SNI support enabled | |
392 ... | |
393 </programlisting> | |
394 | |
395 However, if the SNI-enabled nginx is linked dynamically to | |
396 an OpenSSL library without SNI support, nginx displays the warning: | |
397 | |
398 <programlisting> | |
399 nginx was built with SNI support, however, now it is linked | |
400 dynamically to an OpenSSL library which has no tlsext support, | |
401 therefore SNI is not available | |
402 </programlisting> | |
403 </para> | |
404 | |
405 </section> | |
406 | |
407 | |
408 <section name="compatibility" title="Compatibility"> | |
409 | |
410 <para> | |
411 <list> | |
412 | |
413 <item> | |
414 The SNI support status has been shown by the “-V” switch | |
415 since 0.8.21 and 0.7.62. | |
416 </item> | |
417 | |
418 <item> | |
419 The <dirname>ssl</dirname> parameter of the <dirname>listen</dirname> | |
420 directive has been supported since 0.7.14. | |
421 </item> | |
422 | |
423 <item> | |
424 SNI has been supported since 0.5.32. | |
425 </item> | |
426 | |
427 <item> | |
428 The shared SSL session cache has been supported since 0.5.6. | |
429 </item> | |
430 | |
431 </list> | |
432 </para> | |
433 | |
434 <para> | |
435 <list> | |
436 | |
437 <item> | |
438 Version 0.7.65, 0.8.19 and later: the default SSL protocols are SSLv3 and TLSv1. | |
439 </item> | |
440 | |
441 <item> | |
442 Version 0.7.64, 0.8.18 and earlier: the default SSL protocols are SSLv2, | |
443 SSLv3, and TLSv1. | |
444 </item> | |
445 | |
446 </list> | |
447 </para> | |
448 | |
449 <para> | |
450 <list> | |
451 | |
452 <item> | |
453 Version 0.7.65, 0.8.20 and later: the default SSL ciphers are | |
454 <dirname>HIGH:!ADH:!MD5</dirname>. | |
455 </item> | |
456 | |
457 <item> | |
458 Version 0.8.19: the default SSL ciphers are | |
459 <dirname>ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM</dirname>. | |
460 </item> | |
461 | |
462 <item> | |
463 Version 0.7.64, 0.8.18 and earlier: the default SSL ciphers are<br/> | |
464 <dirname>ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</dirname>. | |
465 </item> | |
466 | |
467 </list> | |
468 </para> | |
469 | |
470 | |
471 </section> | |
472 | |
473 | |
474 </article> |