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

tip
Last change on this file was 1428:933831d7bf0b, checked in by Sergey Kandaurov <pluknet@…>, 5 weeks ago

Link to "ssl_verify_client" from client certificate directives.

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