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

Last change on this file was 1726:a0bc284941f6, checked in by Maxim Dounin <mdounin@…>, 3 months ago

Documented multiple certificates support.

File size: 20.2 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="23">
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       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 to a primary
143certificate, they should be specified in the same file in the following
144order: the primary certificate comes first, then the intermediate certificates.
145A secret key in the PEM format may be placed in the same file.
146</para>
147
148<para>
149Since version 1.11.0,
150this directive can be specified multiple times
151to load certificates of different types, for example, RSA and ECDSA:
152<example>
153server {
154    listen              443 ssl;
155    server_name         example.com;
156
157    ssl_certificate     example.com.rsa.crt;
158    ssl_certificate_key example.com.rsa.key;
159
160    ssl_certificate     example.com.ecdsa.crt;
161    ssl_certificate_key example.com.ecdsa.key;
162
163    ...
164}
165</example>
166<note>
167Only OpenSSL 1.0.2 or higher supports separate
168<link doc="configuring_https_servers.xml" id="chains">certificate chains</link>
169for different certificates.
170With older versions, only one certificate chain can be used.
171</note>
172</para>
173
174<para>
175It should be kept in mind that due to the HTTPS protocol limitations
176virtual servers should listen on different IP addresses:
177<example>
178server {
179    listen          192.168.1.1:443;
180    server_name     one.example.com;
181    ssl_certificate one.example.com.crt;
182    ...
183}
184
185server {
186    listen          192.168.1.2:443;
187    server_name     two.example.com;
188    ssl_certificate two.example.com.crt;
189    ...
190}
191</example>
192otherwise
193<link doc="configuring_https_servers.xml"
194    id="name_based_https_servers">the first server’s certificate</link>
195will be issued for the second site.
196</para>
197
198</directive>
199
200
201<directive name="ssl_certificate_key">
202<syntax><value>file</value></syntax>
203<default/>
204<context>http</context>
205<context>server</context>
206
207<para>
208Specifies a <value>file</value> with the secret key in the PEM format
209for the given virtual server.
210</para>
211
212<para>
213The value
214<literal>engine</literal>:<value>name</value>:<value>id</value>
215can be specified instead of the <value>file</value> (1.7.9),
216which loads a secret key with a specified <value>id</value>
217from the OpenSSL engine <value>name</value>.
218</para>
219
220</directive>
221
222
223<directive name="ssl_ciphers">
224<syntax><value>ciphers</value></syntax>
225<default>HIGH:!aNULL:!MD5</default>
226<context>http</context>
227<context>server</context>
228
229<para>
230Specifies the enabled ciphers.
231The ciphers are specified in the format understood by the
232OpenSSL library, for example:
233<example>
234ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
235</example>
236</para>
237
238<para>
239The full list can be viewed using the
240<command>openssl ciphers</command>” command.
241</para>
242
243<para>
244<note>
245The previous versions of nginx used
246<link doc="configuring_https_servers.xml" id="compatibility">different</link>
247ciphers by default.
248</note>
249</para>
250
251</directive>
252
253
254<directive name="ssl_client_certificate">
255<syntax><value>file</value></syntax>
256<default/>
257<context>http</context>
258<context>server</context>
259
260<para>
261Specifies a <value>file</value> with trusted CA certificates in the PEM format
262used to <link id="ssl_verify_client">verify</link> client certificates and
263OCSP responses if <link id="ssl_stapling"/> is enabled.
264</para>
265
266<para>
267The list of certificates will be sent to clients.
268If this is not desired, the <link id="ssl_trusted_certificate"/>
269directive can be used.
270</para>
271
272</directive>
273
274
275<directive name="ssl_crl">
276<syntax><value>file</value></syntax>
277<default/>
278<context>http</context>
279<context>server</context>
280<appeared-in>0.8.7</appeared-in>
281
282<para>
283Specifies a <value>file</value> with revoked certificates (CRL)
284in the PEM format used to <link id="ssl_verify_client">verify</link>
285client certificates.
286</para>
287
288</directive>
289
290
291<directive name="ssl_dhparam">
292<syntax><value>file</value></syntax>
293<default/>
294<context>http</context>
295<context>server</context>
296<appeared-in>0.7.2</appeared-in>
297
298<para>
299Specifies a <value>file</value> with DH parameters for DHE ciphers.
300</para>
301
302</directive>
303
304
305<directive name="ssl_ecdh_curve">
306<syntax><value>curve</value></syntax>
307<default>auto</default>
308<context>http</context>
309<context>server</context>
310<appeared-in>1.1.0</appeared-in>
311<appeared-in>1.0.6</appeared-in>
312
313<para>
314Specifies a <value>curve</value> for ECDHE ciphers.
315</para>
316
317<para>
318When using OpenSSL 1.0.2 or higher,
319it is possible to specify multiple curves (1.11.0), for example:
320<example>
321ssl_ecdh_curve prime256v1:secp384r1;
322</example>
323</para>
324
325<para>
326The special value <literal>auto</literal> (1.11.0) instructs nginx to use
327a list built into the OpenSSL library when using OpenSSL 1.0.2 or higher,
328or <literal>prime256v1</literal> with older versions.
329</para>
330
331<para>
332<note>
333Prior to version 1.11.0,
334the <literal>prime256v1</literal> curve was used by default.
335</note>
336</para>
337
338</directive>
339
340
341<directive name="ssl_password_file">
342<syntax><value>file</value></syntax>
343<default/>
344<context>http</context>
345<context>server</context>
346<appeared-in>1.7.3</appeared-in>
347
348<para>
349Specifies a <value>file</value> with passphrases for
350<link id="ssl_certificate_key">secret keys</link>
351where each passphrase is specified on a separate line.
352Passphrases are tried in turn when loading the key.
353</para>
354
355<para>
356Example:
357<example>
358http {
359    ssl_password_file /etc/keys/global.pass;
360    ...
361
362    server {
363        server_name www1.example.com;
364        ssl_certificate_key /etc/keys/first.key;
365    }
366
367    server {
368        server_name www2.example.com;
369
370        # named pipe can also be used instead of a file
371        ssl_password_file /etc/keys/fifo;
372        ssl_certificate_key /etc/keys/second.key;
373    }
374}
375</example>
376</para>
377
378</directive>
379
380
381<directive name="ssl_prefer_server_ciphers">
382<syntax><literal>on</literal> | <literal>off</literal></syntax>
383<default>off</default>
384<context>http</context>
385<context>server</context>
386
387<para>
388Specifies that server ciphers should be preferred over client
389ciphers when using the SSLv3 and TLS protocols.
390</para>
391
392</directive>
393
394
395<directive name="ssl_protocols">
396<syntax>
397    [<literal>SSLv2</literal>]
398    [<literal>SSLv3</literal>]
399    [<literal>TLSv1</literal>]
400    [<literal>TLSv1.1</literal>]
401    [<literal>TLSv1.2</literal>]</syntax>
402<default>TLSv1 TLSv1.1 TLSv1.2</default>
403<context>http</context>
404<context>server</context>
405
406<para>
407Enables the specified protocols.
408The <literal>TLSv1.1</literal> and <literal>TLSv1.2</literal> parameters work
409only when the OpenSSL library of version 1.0.1 or higher is used.
410<note>
411The <literal>TLSv1.1</literal> and <literal>TLSv1.2</literal> parameters are
412supported starting from versions 1.1.13 and 1.0.12,
413so when the OpenSSL version 1.0.1 or higher
414is used on older nginx versions, these protocols work, but cannot
415be disabled.
416</note>
417</para>
418
419</directive>
420
421
422<directive name="ssl_session_cache">
423<syntax>
424    <literal>off</literal> |
425    <literal>none</literal> |
426    [<literal>builtin</literal>[:<value>size</value>]]
427    [<literal>shared</literal>:<value>name</value>:<value>size</value>]</syntax>
428<default>none</default>
429<context>http</context>
430<context>server</context>
431
432<para>
433Sets the types and sizes of caches that store session parameters.
434A cache can be of any of the following types:
435<list type="tag">
436
437<tag-name><literal>off</literal></tag-name>
438<tag-desc>
439the use of a session cache is strictly prohibited:
440nginx explicitly tells a client that sessions may not be reused.
441</tag-desc>
442
443<tag-name><literal>none</literal></tag-name>
444<tag-desc>
445the use of a session cache is gently disallowed:
446nginx tells a client that sessions may be reused, but does not
447actually store session parameters in the cache.
448</tag-desc>
449
450<tag-name><literal>builtin</literal></tag-name>
451<tag-desc>
452a cache built in OpenSSL; used by one worker process only.
453The cache size is specified in sessions.
454If size is not given, it is equal to 20480 sessions.
455Use of the built-in cache can cause memory fragmentation.
456</tag-desc>
457
458<tag-name><literal>shared</literal></tag-name>
459<tag-desc>
460a cache shared between all worker processes.
461The cache size is specified in bytes; one megabyte can store
462about 4000 sessions.
463Each shared cache should have an arbitrary name.
464A cache with the same name can be used in several virtual servers.
465</tag-desc>
466
467</list>
468</para>
469
470<para>
471Both cache types can be used simultaneously, for example:
472<example>
473ssl_session_cache builtin:1000 shared:SSL:10m;
474</example>
475but using only shared cache without the built-in cache should
476be more efficient.
477</para>
478
479</directive>
480
481
482<directive name="ssl_session_ticket_key">
483<syntax><value>file</value></syntax>
484<default/>
485<context>http</context>
486<context>server</context>
487<appeared-in>1.5.7</appeared-in>
488
489<para>
490Sets a <value>file</value> with the secret key used to encrypt
491and decrypt TLS session tickets.
492The directive is necessary if the same key has to be shared between
493multiple servers.
494By default, a randomly generated key is used.
495</para>
496
497<para>
498If several keys are specified, only the first key is
499used to encrypt TLS session tickets.
500This allows configuring key rotation, for example:
501<example>
502ssl_session_ticket_key current.key;
503ssl_session_ticket_key previous.key;
504</example>
505</para>
506
507<para>
508The <value>file</value> must contain 48 bytes of random data and can
509be created using the following command:
510<example>
511openssl rand 48 > ticket.key
512</example>
513</para>
514
515</directive>
516
517
518<directive name="ssl_session_tickets">
519<syntax><literal>on</literal> | <literal>off</literal></syntax>
520<default>on</default>
521<context>http</context>
522<context>server</context>
523<appeared-in>1.5.9</appeared-in>
524
525<para>
526Enables or disables session resumption through
527<link url="http://tools.ietf.org/html/rfc5077">TLS session tickets</link>.
528</para>
529
530</directive>
531
532
533<directive name="ssl_session_timeout">
534<syntax><value>time</value></syntax>
535<default>5m</default>
536<context>http</context>
537<context>server</context>
538
539<para>
540Specifies a time during which a client may reuse the
541session parameters stored in a cache.
542</para>
543
544</directive>
545
546
547<directive name="ssl_stapling">
548<syntax><literal>on</literal> | <literal>off</literal></syntax>
549<default>off</default>
550<context>http</context>
551<context>server</context>
552<appeared-in>1.3.7</appeared-in>
553
554<para>
555Enables or disables
556<link url="http://tools.ietf.org/html/rfc4366#section-3.6">stapling
557of OCSP responses</link> by the server.
558Example:
559<example>
560ssl_stapling on;
561resolver 192.0.2.1;
562</example>
563</para>
564
565<para>
566For the OCSP stapling to work, the certificate of the server certificate
567issuer should be known.
568If the <link id="ssl_certificate"/> file does
569not contain intermediate certificates,
570the certificate of the server certificate issuer should be
571present in the
572<link id="ssl_trusted_certificate"/> file.
573</para>
574
575<para>
576For a resolution of the OCSP responder hostname,
577the <link doc="ngx_http_core_module.xml" id="resolver"/> directive
578should also be specified.
579</para>
580
581</directive>
582
583
584<directive name="ssl_stapling_file">
585<syntax><value>file</value></syntax>
586<default/>
587<context>http</context>
588<context>server</context>
589<appeared-in>1.3.7</appeared-in>
590
591<para>
592When set, the stapled OCSP response will be taken from the
593specified <value>file</value> instead of querying
594the OCSP responder specified in the server certificate.
595</para>
596
597<para>
598The file should be in the DER format as produced by the
599<literal>openssl ocsp</literal>” command.
600</para>
601
602</directive>
603
604
605<directive name="ssl_stapling_responder">
606<syntax><value>url</value></syntax>
607<default/>
608<context>http</context>
609<context>server</context>
610<appeared-in>1.3.7</appeared-in>
611
612<para>
613Overrides the URL of the OCSP responder specified in the
614<link url="http://tools.ietf.org/html/rfc5280#section-4.2.2.1">Authority
615Information Access</link>” certificate extension.
616</para>
617
618<para>
619Only “<literal>http://</literal>” OCSP responders are supported:
620<example>
621ssl_stapling_responder http://ocsp.example.com/;
622</example>
623</para>
624
625</directive>
626
627
628<directive name="ssl_stapling_verify">
629<syntax><literal>on</literal> | <literal>off</literal></syntax>
630<default>off</default>
631<context>http</context>
632<context>server</context>
633<appeared-in>1.3.7</appeared-in>
634
635<para>
636Enables or disables verification of OCSP responses by the server.
637</para>
638
639<para>
640For verification to work, the certificate of the server certificate
641issuer, the root certificate, and all intermediate certificates
642should be configured as trusted using the
643<link id="ssl_trusted_certificate"/> directive.
644</para>
645
646</directive>
647
648
649<directive name="ssl_trusted_certificate">
650<syntax><value>file</value></syntax>
651<default/>
652<context>http</context>
653<context>server</context>
654<appeared-in>1.3.7</appeared-in>
655
656<para>
657Specifies a <value>file</value> with trusted CA certificates in the PEM format
658used to <link id="ssl_verify_client">verify</link> client certificates and
659OCSP responses if <link id="ssl_stapling"/> is enabled.
660</para>
661
662<para>
663In contrast to the certificate set by <link id="ssl_client_certificate"/>,
664the list of these certificates will not be sent to clients.
665</para>
666
667</directive>
668
669
670<directive name="ssl_verify_client">
671<syntax>
672    <literal>on</literal> | <literal>off</literal> |
673    <literal>optional</literal> | <literal>optional_no_ca</literal></syntax>
674<default>off</default>
675<context>http</context>
676<context>server</context>
677
678<para>
679Enables verification of client certificates.
680The verification result is stored in the
681<var>$ssl_client_verify</var> variable.
682</para>
683
684<para>
685The <literal>optional</literal> parameter (0.8.7+) requests the client
686certificate and verifies it if the certificate is present.
687</para>
688
689<para>
690The <literal>optional_no_ca</literal> parameter (1.3.8, 1.2.5)
691requests the client
692certificate but does not require it to be signed by a trusted CA certificate.
693This is intended for the use in cases when a service that is external to nginx
694performs the actual certificate verification.
695The contents of the certificate is accessible through the
696<var>$ssl_client_cert</var> variable.
697</para>
698
699</directive>
700
701
702<directive name="ssl_verify_depth">
703<syntax><value>number</value></syntax>
704<default>1</default>
705<context>http</context>
706<context>server</context>
707
708<para>
709Sets the verification depth in the client certificates chain.
710</para>
711
712</directive>
713
714</section>
715
716
717<section id="errors" name="Error Processing">
718
719<para>
720The <literal>ngx_http_ssl_module</literal> module supports several
721non-standard error codes that can be used for redirects using the
722<link doc="ngx_http_core_module.xml" id="error_page"/> directive:
723<list type="tag">
724
725<tag-name>495</tag-name>
726<tag-desc>
727an error has occurred during the client certificate verification;
728</tag-desc>
729
730<tag-name>496</tag-name>
731<tag-desc>
732a client has not presented the required certificate;
733</tag-desc>
734
735<tag-name>497</tag-name>
736<tag-desc>
737a regular request has been sent to the HTTPS port.
738</tag-desc>
739
740</list>
741</para>
742
743<para>
744The redirection happens after the request is fully parsed and
745the variables, such as <var>$request_uri</var>,
746<var>$uri</var>, <var>$args</var> and others, are available.
747</para>
748
749</section>
750
751
752<section id="variables" name="Embedded Variables">
753
754<para>
755The <literal>ngx_http_ssl_module</literal> module supports
756several embedded variables:
757<list type="tag">
758
759<tag-name id="var_ssl_cipher"><var>$ssl_cipher</var></tag-name>
760<tag-desc>
761returns the string of ciphers used
762for an established SSL connection;
763</tag-desc>
764
765<tag-name id="var_ssl_client_cert"><var>$ssl_client_cert</var></tag-name>
766<tag-desc>
767returns the client certificate in the PEM format
768for an established SSL connection, with each line except the first
769prepended with the tab character;
770this is intended for the use in the
771<link doc="ngx_http_proxy_module.xml" id="proxy_set_header"/> directive;
772</tag-desc>
773
774<tag-name id="var_ssl_client_fingerprint"><var>$ssl_client_fingerprint</var></tag-name>
775<tag-desc>
776returns the SHA1 fingerprint of the client certificate
777for an established SSL connection (1.7.1);
778</tag-desc>
779
780<tag-name id="var_ssl_client_raw_cert"><var>$ssl_client_raw_cert</var>
781</tag-name>
782<tag-desc>
783returns the client certificate in the PEM format
784for an established SSL connection;
785</tag-desc>
786
787<tag-name id="var_ssl_client_serial"><var>$ssl_client_serial</var></tag-name>
788<tag-desc>
789returns the serial number of the client certificate
790for an established SSL connection;
791</tag-desc>
792
793<tag-name id="var_ssl_client_s_dn"><var>$ssl_client_s_dn</var></tag-name>
794<tag-desc>
795returns the “subject DN” string of the client certificate
796for an established SSL connection;
797</tag-desc>
798
799<tag-name id="var_ssl_client_i_dn"><var>$ssl_client_i_dn</var></tag-name>
800<tag-desc>
801returns the “issuer DN” string of the client certificate
802for an established SSL connection;
803</tag-desc>
804
805<tag-name id="var_ssl_client_verify"><var>$ssl_client_verify</var></tag-name>
806<tag-desc>
807returns the result of client certificate verification:
808<literal>SUCCESS</literal>”, “<literal>FAILED</literal>”, and
809<literal>NONE</literal>” if a certificate was not present;
810</tag-desc>
811
812<tag-name id="var_ssl_protocol"><var>$ssl_protocol</var></tag-name>
813<tag-desc>
814returns the protocol of an established SSL connection;
815</tag-desc>
816
817<tag-name id="var_ssl_server_name"><var>$ssl_server_name</var></tag-name>
818<tag-desc>
819returns the server name requested through
820<link url="http://en.wikipedia.org/wiki/Server_Name_Indication">SNI</link>
821(1.7.0);
822</tag-desc>
823
824<tag-name id="var_ssl_session_id"><var>$ssl_session_id</var></tag-name>
825<tag-desc>
826returns the session identifier of an established SSL connection;
827</tag-desc>
828
829<tag-name id="var_ssl_session_reused"><var>$ssl_session_reused</var></tag-name>
830<tag-desc>
831returns “<literal>r</literal>” if an SSL session was reused,
832or “<literal>.</literal>” otherwise (1.5.11).
833</tag-desc>
834
835</list>
836</para>
837
838</section>
839
840</module>
Note: See TracBrowser for help on using the repository browser.