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

tip
Last change on this file was 1155:07402a11fd8d, checked in by Vladimir Homutov <vl@…>, 3 days ago

Assigned IDs to tags describing variables.

File size: 17.5 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="13">
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_prefer_server_ciphers">
287<syntax><literal>on</literal> | <literal>off</literal></syntax>
288<default>off</default>
289<context>http</context>
290<context>server</context>
291
292<para>
293Specifies that server ciphers should be preferred over client
294ciphers when using the SSLv3 and TLS protocols.
295</para>
296
297</directive>
298
299
300<directive name="ssl_protocols">
301<syntax>
302    [<literal>SSLv2</literal>]
303    [<literal>SSLv3</literal>]
304    [<literal>TLSv1</literal>]
305    [<literal>TLSv1.1</literal>]
306    [<literal>TLSv1.2</literal>]</syntax>
307<default>SSLv3 TLSv1 TLSv1.1 TLSv1.2</default>
308<context>http</context>
309<context>server</context>
310
311<para>
312Enables the specified protocols.
313The <literal>TLSv1.1</literal> and <literal>TLSv1.2</literal> parameters work
314only when the OpenSSL library of version 1.0.1 or higher is used.
315<note>
316The <literal>TLSv1.1</literal> and <literal>TLSv1.2</literal> parameters are
317supported starting from versions 1.1.13 and 1.0.12,
318so when the OpenSSL version 1.0.1 or higher
319is used on older nginx versions, these protocols work, but cannot
320be disabled.
321</note>
322</para>
323
324</directive>
325
326
327<directive name="ssl_session_cache">
328<syntax>
329    <literal>off</literal> |
330    <literal>none</literal> |
331    [<literal>builtin</literal>[:<value>size</value>]]
332    [<literal>shared</literal>:<value>name</value>:<value>size</value>]</syntax>
333<default>none</default>
334<context>http</context>
335<context>server</context>
336
337<para>
338Sets the types and sizes of caches that store session parameters.
339A cache can be of any of the following types:
340<list type="tag">
341
342<tag-name><literal>off</literal></tag-name>
343<tag-desc>
344the use of a session cache is strictly prohibited:
345nginx explicitly tells a client that sessions may not be reused.
346</tag-desc>
347
348<tag-name><literal>none</literal></tag-name>
349<tag-desc>
350the use of a session cache is gently disallowed:
351nginx tells a client that sessions may be reused, but does not
352actually store session parameters in the cache.
353</tag-desc>
354
355<tag-name><literal>builtin</literal></tag-name>
356<tag-desc>
357a cache built in OpenSSL; used by one worker process only.
358The cache size is specified in sessions.
359If size is not given, it is equal to 20480 sessions.
360Use of the built-in cache can cause memory fragmentation.
361</tag-desc>
362
363<tag-name><literal>shared</literal></tag-name>
364<tag-desc>
365a cache shared between all worker processes.
366The cache size is specified in bytes; one megabyte can store
367about 4000 sessions.
368Each shared cache should have an arbitrary name.
369A cache with the same name can be used in several virtual servers.
370</tag-desc>
371
372</list>
373</para>
374
375<para>
376Both cache types can be used simultaneously, for example:
377<example>
378ssl_session_cache builtin:1000 shared:SSL:10m;
379</example>
380but using only shared cache without the built-in cache should
381be more efficient.
382</para>
383
384</directive>
385
386
387<directive name="ssl_session_ticket_key">
388<syntax><value>file</value></syntax>
389<default/>
390<context>http</context>
391<context>server</context>
392<appeared-in>1.5.7</appeared-in>
393
394<para>
395Sets a <value>file</value> with the secret key used to encrypt
396and decrypt TLS session tickets.
397The directive is necessary if the same key has to be shared between
398multiple servers.
399By default, a randomly generated key is used.
400</para>
401
402<para>
403If several keys are specified, only the first key is
404used to encrypt TLS session tickets.
405This allows configuring key rotation, for example:
406<example>
407ssl_session_ticket_key current.key;
408ssl_session_ticket_key previous.key;
409</example>
410</para>
411
412<para>
413The <value>file</value> must contain 48 bytes of random data and can
414be created using the following command:
415<example>
416openssl rand 48 > ticket.key
417</example>
418</para>
419
420</directive>
421
422
423<directive name="ssl_session_tickets">
424<syntax><literal>on</literal> | <literal>off</literal></syntax>
425<default>on</default>
426<context>http</context>
427<context>server</context>
428<appeared-in>1.5.9</appeared-in>
429
430<para>
431Enables or disables session resumption through
432<link url="http://tools.ietf.org/html/rfc5077">TLS session tickets</link>.
433</para>
434
435</directive>
436
437
438<directive name="ssl_session_timeout">
439<syntax><value>time</value></syntax>
440<default>5m</default>
441<context>http</context>
442<context>server</context>
443
444<para>
445Specifies a time during which a client may reuse the
446session parameters stored in a cache.
447</para>
448
449</directive>
450
451
452<directive name="ssl_stapling">
453<syntax><literal>on</literal> | <literal>off</literal></syntax>
454<default>off</default>
455<context>http</context>
456<context>server</context>
457<appeared-in>1.3.7</appeared-in>
458
459<para>
460Enables or disables
461<link url="http://tools.ietf.org/html/rfc4366#section-3.6">stapling
462of OCSP responses</link> by the server.
463Example:
464<example>
465ssl_stapling on;
466resolver 192.0.2.1;
467</example>
468</para>
469
470<para>
471For the OCSP stapling to work, the certificate of the server certificate
472issuer should be known.
473If the <link id="ssl_certificate"/> file does
474not contain intermediate certificates,
475the certificate of the server certificate issuer should be
476present in the
477<link id="ssl_trusted_certificate"/> file.
478</para>
479
480<para>
481For a resolution of the OCSP responder hostname,
482the <link doc="ngx_http_core_module.xml" id="resolver"/> directive
483should also be specified.
484</para>
485
486</directive>
487
488
489<directive name="ssl_stapling_file">
490<syntax><value>file</value></syntax>
491<default/>
492<context>http</context>
493<context>server</context>
494<appeared-in>1.3.7</appeared-in>
495
496<para>
497When set, the stapled OCSP response will be taken from the
498specified <value>file</value> instead of querying
499the OCSP responder specified in the server certificate.
500</para>
501
502<para>
503The file should be in the DER format as produced by the
504<literal>openssl ocsp</literal>” command.
505</para>
506
507</directive>
508
509
510<directive name="ssl_stapling_responder">
511<syntax><value>url</value></syntax>
512<default/>
513<context>http</context>
514<context>server</context>
515<appeared-in>1.3.7</appeared-in>
516
517<para>
518Overrides the URL of the OCSP responder specified in the
519<link url="http://tools.ietf.org/html/rfc5280#section-4.2.2.1">Authority
520Information Access</link>” certificate extension.
521</para>
522
523<para>
524Only “<literal>http://</literal>” OCSP responders are supported:
525<example>
526ssl_stapling_responder http://ocsp.example.com/;
527</example>
528</para>
529
530</directive>
531
532
533<directive name="ssl_stapling_verify">
534<syntax><literal>on</literal> | <literal>off</literal></syntax>
535<default>off</default>
536<context>http</context>
537<context>server</context>
538<appeared-in>1.3.7</appeared-in>
539
540<para>
541Enables or disables verification of OCSP responses by the server.
542</para>
543
544<para>
545For verification to work, the certificate of the server certificate
546issuer, the root certificate, and all intermediate certificates
547should be configured as trusted using the
548<link id="ssl_trusted_certificate"/> directive.
549</para>
550
551</directive>
552
553
554<directive name="ssl_trusted_certificate">
555<syntax><value>file</value></syntax>
556<default/>
557<context>http</context>
558<context>server</context>
559<appeared-in>1.3.7</appeared-in>
560
561<para>
562Specifies a <value>file</value> with trusted CA certificates in the PEM format
563used to verify client certificates and
564OCSP responses if <link id="ssl_stapling"/> is enabled.
565</para>
566
567<para>
568In contrast to the certificate set by <link id="ssl_client_certificate"/>,
569the list of these certificates will not be sent to clients.
570</para>
571
572</directive>
573
574
575<directive name="ssl_verify_client">
576<syntax>
577    <literal>on</literal> | <literal>off</literal> |
578    <literal>optional</literal> | <literal>optional_no_ca</literal></syntax>
579<default>off</default>
580<context>http</context>
581<context>server</context>
582
583<para>
584Enables verification of client certificates.
585The verification result is stored in the
586<var>$ssl_client_verify</var> variable.
587</para>
588
589<para>
590The <literal>optional</literal> parameter (0.8.7+) requests the client
591certificate and verifies it if the certificate is present.
592</para>
593
594<para>
595The <literal>optional_no_ca</literal> parameter (1.3.8, 1.2.5)
596requests the client
597certificate but does not require it to be signed by a trusted CA certificate.
598This is intended for the use in cases when a service that is external to nginx
599performs the actual certificate verification.
600The contents of the certificate is accessible through the
601<var>$ssl_client_cert</var> variable.
602</para>
603
604</directive>
605
606
607<directive name="ssl_verify_depth">
608<syntax><value>number</value></syntax>
609<default>1</default>
610<context>http</context>
611<context>server</context>
612
613<para>
614Sets the verification depth in the client certificates chain.
615</para>
616
617</directive>
618
619</section>
620
621
622<section id="errors" name="Error Processing">
623
624<para>
625The <literal>ngx_http_ssl_module</literal> module supports several
626non-standard error codes that can be used for redirects using the
627<link doc="ngx_http_core_module.xml" id="error_page"/> directive:
628<list type="tag">
629
630<tag-name>495</tag-name>
631<tag-desc>
632an error has occurred during the client certificate verification;
633</tag-desc>
634
635<tag-name>496</tag-name>
636<tag-desc>
637a client has not presented the required certificate;
638</tag-desc>
639
640<tag-name>497</tag-name>
641<tag-desc>
642a regular request has been sent to the HTTPS port.
643</tag-desc>
644
645</list>
646</para>
647
648<para>
649The redirection happens after the request is fully parsed and
650the variables, such as <var>$request_uri</var>,
651<var>$uri</var>, <var>$args</var> and others, are available.
652</para>
653
654</section>
655
656
657<section id="variables" name="Embedded Variables">
658
659<para>
660The <literal>ngx_http_ssl_module</literal> module supports
661several embedded variables:
662<list type="tag">
663
664<tag-name id="var_ssl_cipher"><var>$ssl_cipher</var></tag-name>
665<tag-desc>
666returns the string of ciphers used
667for an established SSL connection;
668</tag-desc>
669
670<tag-name id="var_ssl_client_cert"><var>$ssl_client_cert</var></tag-name>
671<tag-desc>
672returns the client certificate in the PEM format
673for an established SSL connection, with each line except the first
674prepended with the tab character;
675this is intended for the use in the
676<link doc="ngx_http_proxy_module.xml" id="proxy_set_header"/> directive;
677</tag-desc>
678
679<tag-name id="var_ssl_client_raw_cert"><var>$ssl_client_raw_cert</var>
680</tag-name>
681<tag-desc>
682returns the client certificate in the PEM format
683for an established SSL connection;
684</tag-desc>
685
686<tag-name id="var_ssl_client_serial"><var>$ssl_client_serial</var></tag-name>
687<tag-desc>
688returns the serial number of the client certificate
689for an established SSL connection;
690</tag-desc>
691
692<tag-name id="var_ssl_client_s_dn"><var>$ssl_client_s_dn</var></tag-name>
693<tag-desc>
694returns the “subject DN” string of the client certificate
695for an established SSL connection;
696</tag-desc>
697
698<tag-name id="var_ssl_client_i_dn"><var>$ssl_client_i_dn</var></tag-name>
699<tag-desc>
700returns the “issuer DN” string of the client certificate
701for an established SSL connection;
702</tag-desc>
703
704<tag-name id="var_ssl_client_verify"><var>$ssl_client_verify</var></tag-name>
705<tag-desc>
706returns the result of client certificate verification:
707<literal>SUCCESS</literal>”, “<literal>FAILED</literal>”, and
708<literal>NONE</literal>” if a certificate was not present;
709</tag-desc>
710
711<tag-name id="var_ssl_protocol"><var>$ssl_protocol</var></tag-name>
712<tag-desc>
713returns the protocol of an established SSL connection;
714</tag-desc>
715
716<tag-name id="var_ssl_session_id"><var>$ssl_session_id</var></tag-name>
717<tag-desc>
718returns the session identifier of an established SSL connection;
719</tag-desc>
720
721<tag-name id="var_ssl_session_reused"><var>$ssl_session_reused</var></tag-name>
722<tag-desc>
723returns “<literal>r</literal>” if an SSL session was reused,
724or “<literal>.</literal>” otherwise (1.5.11).
725</tag-desc>
726
727</list>
728</para>
729
730</section>
731
732</module>
Note: See TracBrowser for help on using the repository browser.