Mercurial > hg > nginx-site

comparison xml/en/docs/http/configuring_https_servers.xml @ 0:61e04fc01027

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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&rsquo;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&rsquo;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 (&ldquo;<i>s</i>&rdquo;) of the
181 <url>www.GoDaddy.com</url> server certificate #0 is signed by an issuer
182 (&ldquo;<i>i</i>&rdquo;) 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&rsquo; 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>&ldquo;--enable-tlsext&rdquo;.</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 &ldquo;-V&rdquo; 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 &ldquo;-V&rdquo; 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>