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

tip
Last change on this file was 1457:78ccd1af1400, checked in by Ruslan Ermilov <ru@…>, 7 days ago

Minimized diffs between http, mail, and stream.

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