Mercurial > hg > nginx-site

comparison xml/en/docs/mail/ngx_mail_ssl_module.xml @ 664:8283b1048b27

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Translated mail modules into English.
author Vladimir Homutov <vl@nginx.com>
date Wed, 05 Sep 2012 14:07:43 +0000
parents
children 9c1ffd02f1b7
comparison
equal deleted inserted replaced
663:639bbb0c9d05 664:8283b1048b27
1 <?xml version="1.0"?>
2
3 <!--
4 Copyright (C) 2006, 2007 Anton Yuzhaninov
5 Copyright (C) Nginx, Inc.
6 -->
7
8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
9
10 <module name="Module ngx_mail_ssl_module"
11 link="/en/docs/mail/ngx_mail_ssl_module.html"
12 lang="en"
13 rev="1">
14
15 <section id="summary">
16
17 <para>
18 The <literal>ngx_mail_ssl_module</literal> provides the necessary
19 support for mail proxy server for the SSL/TLS protocol.
20 </para>
21
22 <para>
23 This module is not built by default, it should be enabled with
24 the <literal>--with-mail_ssl_module</literal>
25 configuration parameter.
26 <note>
27 This module requires the <link url="http://www.openssl.org">OpenSSL</link>
28 library.
29 </note>
30 </para>
31
32 </section>
33
34
35 <section id="directives" name="Directives">
36
37 <directive name="ssl">
38 <syntax><literal>on</literal> | <literal>off</literal></syntax>
39 <default>off</default>
40 <context>mail</context>
41 <context>server</context>
42
43 <para>
44 Enables the HTTPS protocol for the given virtual server.
45 </para>
46
47 </directive>
48
49
50 <directive name="ssl_certificate">
51 <syntax><value>file</value></syntax>
52 <default/>
53 <context>mail</context>
54 <context>server</context>
55
56 <para>
57 Specifies a file with a certificate in the PEM format for the given
58 virtual server.
59 If intermediate certificates should be specified in addition to a primary
60 certificate, they should be specified in the same file in the following
61 order: the primary certificate comes first, then the intermediate certificates.
62 A secret key in the PEM format may be placed in the same file.
63 </para>
64
65 </directive>
66
67
68 <directive name="ssl_certificate_key">
69 <syntax><value>file</value></syntax>
70 <default/>
71 <context>mail</context>
72 <context>server</context>
73
74 <para>
75 Specifies a file with a secret key in the PEM format for the given virtual
76 server.
77 </para>
78
79 </directive>
80
81
82 <directive name="ssl_prefer_server_ciphers">
83 <syntax><literal>on</literal> | <literal>off</literal></syntax>
84 <default>off</default>
85 <context>mail</context>
86 <context>server</context>
87
88 <para>
89 Specifies that server ciphers should be preferred over client ciphers
90 when using the SSLv3 and TLS protocols.
91 </para>
92
93 </directive>
94
95
96 <directive name="ssl_protocols">
97 <syntax>
98 [<literal>SSLv2</literal>]
99 [<literal>SSLv3</literal>]
100 [<literal>TLSv1</literal>]
101 [<literal>TLSv1.1</literal>]
102 [<literal>TLSv1.2</literal>]</syntax>
103 <default>SSLv3 TLSv1 TLSv1.1 TLSv1.2</default>
104 <context>mail</context>
105 <context>server</context>
106
107 <para>
108 Enables the specified protocols.
109 The parameters <literal>TLSv1.1</literal> and <literal>TLSv1.2</literal> work
110 only when using the OpenSSL library version 1.0.1 and higher.
111 <note>
112 The parameters <literal>TLSv1.1</literal> and <literal>TLSv1.2</literal> are
113 supported starting from versions 1.1.13 and 1.0.12
114 so when using OpenSSL version 1.0.1
115 and higher on older nginx versions these protocols will work but could not
116 be disabled.
117 </note>
118 </para>
119
120 </directive>
121
122
123 <directive name="ssl_session_cache">
124 <syntax>
125 <literal>off</literal> |
126 <literal>none</literal> |
127 [<literal>builtin</literal>[:<value>size</value>]]
128 [<literal>shared</literal>:<value>name</value>:<value>size</value>]</syntax>
129 <default>none</default>
130 <context>mail</context>
131 <context>server</context>
132
133 <para>
134 Sets types and sizes of caches that store session parameters.
135 A cache can be any of the following types:
136 <list type="tag">
137
138 <tag-name><literal>off</literal></tag-name>
139 <tag-desc>
140 the use of session cache is strictly prohibited:
141 nginx explicitly tells a client that sessions may not be reused.
142 </tag-desc>
143
144 <tag-name><literal>none</literal></tag-name>
145 <tag-desc>
146 the use of session cache is gently disallowed:
147 nginx tells a client that sessions may be reused, but does not
148 actually do that.
149 </tag-desc>
150
151 <tag-name><literal>builtin</literal></tag-name>
152 <tag-desc>
153 a cache built in OpenSSL; used by one worker process only.
154 The cache size is specified in sessions.
155 If size is not given, it is equal to 20480 sessions.
156 Use of the built-in cache can cause memory fragmentation.
157 </tag-desc>
158
159 <tag-name><literal>shared</literal></tag-name>
160 <tag-desc>
161 shared between all worker processes.
162 The cache size is specified in bytes; one megabyte can store
163 about 4000 sessions.
164 Each shared cache should have an arbitrary name.
165 A cache with the same name can be used in several
166 virtual servers.
167 </tag-desc>
168
169 </list>
170 </para>
171
172 <para>
173 Both cache types can be used simultaneously, for example:
174 <example>
175 ssl_session_cache builtin:1000 shared:SSL:10m;
176 </example>
177 but using only shared cache without the built-in cache should
178 be more efficient.
179 </para>
180
181 </directive>
182
183
184 <directive name="ssl_session_timeout">
185 <syntax><value>time</value></syntax>
186 <default>5m</default>
187 <context>mail</context>
188 <context>server</context>
189
190 <para>
191 Specifies a time during which a client may reuse the
192 session parameters stored in a cache.
193 </para>
194
195 </directive>
196
197
198 <directive name="starttls">
199 <syntax>
200 <literal>on</literal> |
201 <literal>off</literal> |
202 <literal>only</literal></syntax>
203 <default>off</default>
204 <context>mail</context>
205 <context>server</context>
206
207 <para>
208 <list type="tag">
209
210 <tag-name><literal>on</literal></tag-name>
211 <tag-desc>
212 Allow usage of <literal>STLS</literal> command for the POP3
213 and <literal>STARTTLS</literal> command for the IMAP;
214 </tag-desc>
215
216 <tag-name><literal>off</literal></tag-name>
217 <tag-desc>
218 Deny usage of <literal>STLS</literal>
219 and <literal>STARTTLS</literal> commands;
220 </tag-desc>
221
222 <tag-name><literal>only</literal></tag-name>
223 <tag-desc>
224 require preliminary TLS transition.
225 </tag-desc>
226
227 </list>
228 </para>
229
230 </directive>
231
232 </section>
233
234 </module>