source: nginx_org/xml/en/docs/http/ngx_http_ssl_module.xml

tip
Last change on this file was 1239:35cf5dca5fa4, checked in by Yaroslav Zhuravlev <yar@…>, 5 months ago

SSL: added the ssl_password_file directive.

File size: 18.7 KB
Line 
1<?xml version="1.0"?>
2
3<!--
4  Copyright (C) Igor Sysoev
5  Copyright (C) Nginx, Inc.
6  -->
7
8<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
9
10<module name="Module ngx_http_ssl_module"
11        link="/en/docs/http/ngx_http_ssl_module.html"
12        lang="en"
13        rev="16">
14
15<section id="summary">
16
17<para>
18The <literal>ngx_http_ssl_module</literal> module provides the
19necessary support for HTTPS.
20</para>
21
22<para>
23This module is not built by default, it should be enabled with the
24<literal>--with-http_ssl_module</literal>
25configuration parameter.
26<note>
27This module requires the
28<link url="http://www.openssl.org">OpenSSL</link> library.
29</note>
30</para>
31
32</section>
33
34
35<section id="example" name="Example Configuration">
36
37<para>
38To reduce the processor load it is recommended to
39<list type="bullet">
40
41<listitem>
42set the number of worker processes equal to the number of processors,
43</listitem>
44
45<listitem>
46enable keep-alive connections,
47</listitem>
48
49<listitem>
50enable the shared session cache,
51</listitem>
52
53<listitem>
54disable the built-in session cache,
55</listitem>
56
57<listitem>
58and possibly increase the session lifetime (by default, 5 minutes):
59</listitem>
60
61</list>
62
63<example>
64<emphasis>worker_processes auto;</emphasis>
65
66http {
67
68    ...
69
70    server {
71        listen              443 ssl;
72        <emphasis>keepalive_timeout   70;</emphasis>
73
74        ssl_protocols       SSLv3 TLSv1 TLSv1.1 TLSv1.2;
75        ssl_ciphers         AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
76        ssl_certificate     /usr/local/nginx/conf/cert.pem;
77        ssl_certificate_key /usr/local/nginx/conf/cert.key;
78        <emphasis>ssl_session_cache   shared:SSL:10m;</emphasis>
79        <emphasis>ssl_session_timeout 10m;</emphasis>
80
81        ...
82    }
83</example>
84</para>
85
86</section>
87
88
89<section id="directives" name="Directives">
90
91<directive name="ssl">
92<syntax><literal>on</literal> | <literal>off</literal></syntax>
93<default>off</default>
94<context>http</context>
95<context>server</context>
96
97<para>
98Enables the HTTPS protocol for the given virtual server.
99<note>
100It is recommended to use the <literal>ssl</literal> parameter of the
101<link doc="ngx_http_core_module.xml" id="listen"/> directive instead
102of this directive.
103</note>
104</para>
105
106</directive>
107
108
109<directive name="ssl_buffer_size">
110<syntax><value>size</value></syntax>
111<default>16k</default>
112<context>http</context>
113<context>server</context>
114<appeared-in>1.5.9</appeared-in>
115
116<para>
117Sets the size of the buffer used for sending data.
118</para>
119
120<para>
121By default, the buffer size is 16k, which corresponds to minimal
122overhead when sending big responses.
123To minimize Time To First Byte it may be beneficial to use smaller values,
124for example:
125<example>
126ssl_buffer_size 4k;
127</example>
128</para>
129
130</directive>
131
132
133<directive name="ssl_certificate">
134<syntax><value>file</value></syntax>
135<default/>
136<context>http</context>
137<context>server</context>
138
139<para>
140Specifies a <value>file</value> with the certificate in the PEM format
141for the given virtual server.
142If intermediate certificates should be specified in addition
143to a primary certificate, they should be specified in the same file
144in the following order: the primary certificate comes first, then
145the intermediate certificates.
146A secret key in the PEM format may be placed in the same file.
147</para>
148
149<para>
150It should be kept in mind that due to the HTTPS protocol limitations
151virtual servers should listen on different IP addresses:
152<example>
153server {
154    listen          192.168.1.1:443;
155    server_name     one.example.com;
156    ssl_certificate /usr/local/nginx/conf/one.example.com.cert;
157    ...
158}
159
160server {
161    listen          192.168.1.2:443;
162    server_name     two.example.com;
163    ssl_certificate /usr/local/nginx/conf/two.example.com.cert;
164    ...
165}
166</example>
167otherwise
168<link doc="configuring_https_servers.xml"
169    id="name_based_https_servers">the first server’s certificate</link>
170will be issued for the second site.
171</para>
172
173</directive>
174
175
176<directive name="ssl_certificate_key">
177<syntax><value>file</value></syntax>
178<default/>
179<context>http</context>
180<context>server</context>
181
182<para>
183Specifies a <value>file</value> with the secret key in the PEM format
184for the given virtual server.
185</para>
186
187</directive>
188
189
190<directive name="ssl_ciphers">
191<syntax><value>ciphers</value></syntax>
192<default>HIGH:!aNULL:!MD5</default>
193<context>http</context>
194<context>server</context>
195
196<para>
197Specifies the enabled ciphers.
198The ciphers are specified in the format understood by the
199OpenSSL library, for example:
200<example>
201ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
202</example>
203</para>
204
205<para>
206The full list can be viewed using the
207<command>openssl ciphers</command>” command.
208</para>
209
210<para>
211<note>
212The previous versions of nginx used
213<link doc="configuring_https_servers.xml" id="compatibility">different</link>
214ciphers by default.
215</note>
216</para>
217
218</directive>
219
220
221<directive name="ssl_client_certificate">
222<syntax><value>file</value></syntax>
223<default/>
224<context>http</context>
225<context>server</context>
226
227<para>
228Specifies a <value>file</value> with trusted CA certificates in the PEM format
229used to verify client certificates and
230OCSP responses if <link id="ssl_stapling"/> is enabled.
231</para>
232
233<para>
234The list of certificates will be sent to clients.
235If this is not desired, the <link id="ssl_trusted_certificate"/>
236directive can be used.
237</para>
238
239</directive>
240
241
242<directive name="ssl_crl">
243<syntax><value>file</value></syntax>
244<default/>
245<context>http</context>
246<context>server</context>
247<appeared-in>0.8.7</appeared-in>
248
249<para>
250Specifies a <value>file</value> with revoked certificates (CRL)
251in the PEM format used to verify client certificates.
252</para>
253
254</directive>
255
256
257<directive name="ssl_dhparam">
258<syntax><value>file</value></syntax>
259<default/>
260<context>http</context>
261<context>server</context>
262<appeared-in>0.7.2</appeared-in>
263
264<para>
265Specifies a <value>file</value> with DH parameters for EDH ciphers.
266</para>
267
268</directive>
269
270
271<directive name="ssl_ecdh_curve">
272<syntax><value>curve</value></syntax>
273<default>prime256v1</default>
274<context>http</context>
275<context>server</context>
276<appeared-in>1.1.0</appeared-in>
277<appeared-in>1.0.6</appeared-in>
278
279<para>
280Specifies a <value>curve</value> for ECDHE ciphers.
281</para>
282
283</directive>
284
285
286<directive name="ssl_password_file">
287<syntax><value>file</value></syntax>
288<default/>
289<context>http</context>
290<context>server</context>
291<appeared-in>1.7.3</appeared-in>
292
293<para>
294Specifies a <value>file</value> with passphrases for
295<link id="ssl_certificate_key">secret keys</link>
296where each passphrase is specified on a separate line.
297Passphrases are tried in turn when loading the key.
298</para>
299
300<para>
301Example:
302<example>
303http {
304    ssl_password_file /etc/keys/global.pass;
305    ...
306
307    server {
308        server_name www1.example.com;
309        ssl_certificate_key /etc/keys/first.key;
310    }
311
312    server {
313        server_name www2.example.com;
314
315        # named pipe can also be used instead of a file
316        ssl_password_file /etc/keys/fifo;
317        ssl_certificate_key /etc/keys/second.key;
318    }
319}
320</example>
321</para>
322
323</directive>
324
325
326<directive name="ssl_prefer_server_ciphers">
327<syntax><literal>on</literal> | <literal>off</literal></syntax>
328<default>off</default>
329<context>http</context>
330<context>server</context>
331
332<para>
333Specifies that server ciphers should be preferred over client
334ciphers when using the SSLv3 and TLS protocols.
335</para>
336
337</directive>
338
339
340<directive name="ssl_protocols">
341<syntax>
342    [<literal>SSLv2</literal>]
343    [<literal>SSLv3</literal>]
344    [<literal>TLSv1</literal>]
345    [<literal>TLSv1.1</literal>]
346    [<literal>TLSv1.2</literal>]</syntax>
347<default>SSLv3 TLSv1 TLSv1.1 TLSv1.2</default>
348<context>http</context>
349<context>server</context>
350
351<para>
352Enables the specified protocols.
353The <literal>TLSv1.1</literal> and <literal>TLSv1.2</literal> parameters work
354only when the OpenSSL library of version 1.0.1 or higher is used.
355<note>
356The <literal>TLSv1.1</literal> and <literal>TLSv1.2</literal> parameters are
357supported starting from versions 1.1.13 and 1.0.12,
358so when the OpenSSL version 1.0.1 or higher
359is used on older nginx versions, these protocols work, but cannot
360be disabled.
361</note>
362</para>
363
364</directive>
365
366
367<directive name="ssl_session_cache">
368<syntax>
369    <literal>off</literal> |
370    <literal>none</literal> |
371    [<literal>builtin</literal>[:<value>size</value>]]
372    [<literal>shared</literal>:<value>name</value>:<value>size</value>]</syntax>
373<default>none</default>
374<context>http</context>
375<context>server</context>
376
377<para>
378Sets the types and sizes of caches that store session parameters.
379A cache can be of any of the following types:
380<list type="tag">
381
382<tag-name><literal>off</literal></tag-name>
383<tag-desc>
384the use of a session cache is strictly prohibited:
385nginx explicitly tells a client that sessions may not be reused.
386</tag-desc>
387
388<tag-name><literal>none</literal></tag-name>
389<tag-desc>
390the use of a session cache is gently disallowed:
391nginx tells a client that sessions may be reused, but does not
392actually store session parameters in the cache.
393</tag-desc>
394
395<tag-name><literal>builtin</literal></tag-name>
396<tag-desc>
397a cache built in OpenSSL; used by one worker process only.
398The cache size is specified in sessions.
399If size is not given, it is equal to 20480 sessions.
400Use of the built-in cache can cause memory fragmentation.
401</tag-desc>
402
403<tag-name><literal>shared</literal></tag-name>
404<tag-desc>
405a cache shared between all worker processes.
406The cache size is specified in bytes; one megabyte can store
407about 4000 sessions.
408Each shared cache should have an arbitrary name.
409A cache with the same name can be used in several virtual servers.
410</tag-desc>
411
412</list>
413</para>
414
415<para>
416Both cache types can be used simultaneously, for example:
417<example>
418ssl_session_cache builtin:1000 shared:SSL:10m;
419</example>
420but using only shared cache without the built-in cache should
421be more efficient.
422</para>
423
424</directive>
425
426
427<directive name="ssl_session_ticket_key">
428<syntax><value>file</value></syntax>
429<default/>
430<context>http</context>
431<context>server</context>
432<appeared-in>1.5.7</appeared-in>
433
434<para>
435Sets a <value>file</value> with the secret key used to encrypt
436and decrypt TLS session tickets.
437The directive is necessary if the same key has to be shared between
438multiple servers.
439By default, a randomly generated key is used.
440</para>
441
442<para>
443If several keys are specified, only the first key is
444used to encrypt TLS session tickets.
445This allows configuring key rotation, for example:
446<example>
447ssl_session_ticket_key current.key;
448ssl_session_ticket_key previous.key;
449</example>
450</para>
451
452<para>
453The <value>file</value> must contain 48 bytes of random data and can
454be created using the following command:
455<example>
456openssl rand 48 > ticket.key
457</example>
458</para>
459
460</directive>
461
462
463<directive name="ssl_session_tickets">
464<syntax><literal>on</literal> | <literal>off</literal></syntax>
465<default>on</default>
466<context>http</context>
467<context>server</context>
468<appeared-in>1.5.9</appeared-in>
469
470<para>
471Enables or disables session resumption through
472<link url="http://tools.ietf.org/html/rfc5077">TLS session tickets</link>.
473</para>
474
475</directive>
476
477
478<directive name="ssl_session_timeout">
479<syntax><value>time</value></syntax>
480<default>5m</default>
481<context>http</context>
482<context>server</context>
483
484<para>
485Specifies a time during which a client may reuse the
486session parameters stored in a cache.
487</para>
488
489</directive>
490
491
492<directive name="ssl_stapling">
493<syntax><literal>on</literal> | <literal>off</literal></syntax>
494<default>off</default>
495<context>http</context>
496<context>server</context>
497<appeared-in>1.3.7</appeared-in>
498
499<para>
500Enables or disables
501<link url="http://tools.ietf.org/html/rfc4366#section-3.6">stapling
502of OCSP responses</link> by the server.
503Example:
504<example>
505ssl_stapling on;
506resolver 192.0.2.1;
507</example>
508</para>
509
510<para>
511For the OCSP stapling to work, the certificate of the server certificate
512issuer should be known.
513If the <link id="ssl_certificate"/> file does
514not contain intermediate certificates,
515the certificate of the server certificate issuer should be
516present in the
517<link id="ssl_trusted_certificate"/> file.
518</para>
519
520<para>
521For a resolution of the OCSP responder hostname,
522the <link doc="ngx_http_core_module.xml" id="resolver"/> directive
523should also be specified.
524</para>
525
526</directive>
527
528
529<directive name="ssl_stapling_file">
530<syntax><value>file</value></syntax>
531<default/>
532<context>http</context>
533<context>server</context>
534<appeared-in>1.3.7</appeared-in>
535
536<para>
537When set, the stapled OCSP response will be taken from the
538specified <value>file</value> instead of querying
539the OCSP responder specified in the server certificate.
540</para>
541
542<para>
543The file should be in the DER format as produced by the
544<literal>openssl ocsp</literal>” command.
545</para>
546
547</directive>
548
549
550<directive name="ssl_stapling_responder">
551<syntax><value>url</value></syntax>
552<default/>
553<context>http</context>
554<context>server</context>
555<appeared-in>1.3.7</appeared-in>
556
557<para>
558Overrides the URL of the OCSP responder specified in the
559<link url="http://tools.ietf.org/html/rfc5280#section-4.2.2.1">Authority
560Information Access</link>” certificate extension.
561</para>
562
563<para>
564Only “<literal>http://</literal>” OCSP responders are supported:
565<example>
566ssl_stapling_responder http://ocsp.example.com/;
567</example>
568</para>
569
570</directive>
571
572
573<directive name="ssl_stapling_verify">
574<syntax><literal>on</literal> | <literal>off</literal></syntax>
575<default>off</default>
576<context>http</context>
577<context>server</context>
578<appeared-in>1.3.7</appeared-in>
579
580<para>
581Enables or disables verification of OCSP responses by the server.
582</para>
583
584<para>
585For verification to work, the certificate of the server certificate
586issuer, the root certificate, and all intermediate certificates
587should be configured as trusted using the
588<link id="ssl_trusted_certificate"/> directive.
589</para>
590
591</directive>
592
593
594<directive name="ssl_trusted_certificate">
595<syntax><value>file</value></syntax>
596<default/>
597<context>http</context>
598<context>server</context>
599<appeared-in>1.3.7</appeared-in>
600
601<para>
602Specifies a <value>file</value> with trusted CA certificates in the PEM format
603used to verify client certificates and
604OCSP responses if <link id="ssl_stapling"/> is enabled.
605</para>
606
607<para>
608In contrast to the certificate set by <link id="ssl_client_certificate"/>,
609the list of these certificates will not be sent to clients.
610</para>
611
612</directive>
613
614
615<directive name="ssl_verify_client">
616<syntax>
617    <literal>on</literal> | <literal>off</literal> |
618    <literal>optional</literal> | <literal>optional_no_ca</literal></syntax>
619<default>off</default>
620<context>http</context>
621<context>server</context>
622
623<para>
624Enables verification of client certificates.
625The verification result is stored in the
626<var>$ssl_client_verify</var> variable.
627</para>
628
629<para>
630The <literal>optional</literal> parameter (0.8.7+) requests the client
631certificate and verifies it if the certificate is present.
632</para>
633
634<para>
635The <literal>optional_no_ca</literal> parameter (1.3.8, 1.2.5)
636requests the client
637certificate but does not require it to be signed by a trusted CA certificate.
638This is intended for the use in cases when a service that is external to nginx
639performs the actual certificate verification.
640The contents of the certificate is accessible through the
641<var>$ssl_client_cert</var> variable.
642</para>
643
644</directive>
645
646
647<directive name="ssl_verify_depth">
648<syntax><value>number</value></syntax>
649<default>1</default>
650<context>http</context>
651<context>server</context>
652
653<para>
654Sets the verification depth in the client certificates chain.
655</para>
656
657</directive>
658
659</section>
660
661
662<section id="errors" name="Error Processing">
663
664<para>
665The <literal>ngx_http_ssl_module</literal> module supports several
666non-standard error codes that can be used for redirects using the
667<link doc="ngx_http_core_module.xml" id="error_page"/> directive:
668<list type="tag">
669
670<tag-name>495</tag-name>
671<tag-desc>
672an error has occurred during the client certificate verification;
673</tag-desc>
674
675<tag-name>496</tag-name>
676<tag-desc>
677a client has not presented the required certificate;
678</tag-desc>
679
680<tag-name>497</tag-name>
681<tag-desc>
682a regular request has been sent to the HTTPS port.
683</tag-desc>
684
685</list>
686</para>
687
688<para>
689The redirection happens after the request is fully parsed and
690the variables, such as <var>$request_uri</var>,
691<var>$uri</var>, <var>$args</var> and others, are available.
692</para>
693
694</section>
695
696
697<section id="variables" name="Embedded Variables">
698
699<para>
700The <literal>ngx_http_ssl_module</literal> module supports
701several embedded variables:
702<list type="tag">
703
704<tag-name id="var_ssl_cipher"><var>$ssl_cipher</var></tag-name>
705<tag-desc>
706returns the string of ciphers used
707for an established SSL connection;
708</tag-desc>
709
710<tag-name id="var_ssl_client_cert"><var>$ssl_client_cert</var></tag-name>
711<tag-desc>
712returns the client certificate in the PEM format
713for an established SSL connection, with each line except the first
714prepended with the tab character;
715this is intended for the use in the
716<link doc="ngx_http_proxy_module.xml" id="proxy_set_header"/> directive;
717</tag-desc>
718
719<tag-name id="var_ssl_client_fingerprint"><var>$ssl_client_fingerprint</var></tag-name>
720<tag-desc>
721returns the SHA1 fingerprint of the client certificate
722for an established SSL connection (1.7.1);
723</tag-desc>
724
725<tag-name id="var_ssl_client_raw_cert"><var>$ssl_client_raw_cert</var>
726</tag-name>
727<tag-desc>
728returns the client certificate in the PEM format
729for an established SSL connection;
730</tag-desc>
731
732<tag-name id="var_ssl_client_serial"><var>$ssl_client_serial</var></tag-name>
733<tag-desc>
734returns the serial number of the client certificate
735for an established SSL connection;
736</tag-desc>
737
738<tag-name id="var_ssl_client_s_dn"><var>$ssl_client_s_dn</var></tag-name>
739<tag-desc>
740returns the “subject DN” string of the client certificate
741for an established SSL connection;
742</tag-desc>
743
744<tag-name id="var_ssl_client_i_dn"><var>$ssl_client_i_dn</var></tag-name>
745<tag-desc>
746returns the “issuer DN” string of the client certificate
747for an established SSL connection;
748</tag-desc>
749
750<tag-name id="var_ssl_client_verify"><var>$ssl_client_verify</var></tag-name>
751<tag-desc>
752returns the result of client certificate verification:
753<literal>SUCCESS</literal>”, “<literal>FAILED</literal>”, and
754<literal>NONE</literal>” if a certificate was not present;
755</tag-desc>
756
757<tag-name id="var_ssl_protocol"><var>$ssl_protocol</var></tag-name>
758<tag-desc>
759returns the protocol of an established SSL connection;
760</tag-desc>
761
762<tag-name id="var_ssl_server_name"><var>$ssl_server_name</var></tag-name>
763<tag-desc>
764returns the server name requested through
765<link url="http://en.wikipedia.org/wiki/Server_Name_Indication">SNI</link>
766(1.7.0);
767</tag-desc>
768
769<tag-name id="var_ssl_session_id"><var>$ssl_session_id</var></tag-name>
770<tag-desc>
771returns the session identifier of an established SSL connection;
772</tag-desc>
773
774<tag-name id="var_ssl_session_reused"><var>$ssl_session_reused</var></tag-name>
775<tag-desc>
776returns “<literal>r</literal>” if an SSL session was reused,
777or “<literal>.</literal>” otherwise (1.5.11).
778</tag-desc>
779
780</list>
781</para>
782
783</section>
784
785</module>
Note: See TracBrowser for help on using the repository browser.