nginx

Module ngx_mail_ssl_module


english
русский

简体中文
עברית
日本語
türkçe
italiano

news
about
download
security advisories
documentation
pgp keys
faq
links
books
support
donation

trac
wiki
twitter
nginx.com
blog
Directives
     ssl
     ssl_certificate
     ssl_certificate_key
     ssl_prefer_server_ciphers
     ssl_protocols
     ssl_session_cache
     ssl_session_ticket_key
     ssl_session_timeout
     starttls

The ngx_mail_ssl_module module provides the necessary support for a mail proxy server to work with the SSL/TLS protocol.

This module is not built by default, it should be enabled with the --with-mail_ssl_module configuration parameter.

This module requires the OpenSSL library.

Directives

syntax: ssl on | off;
default:
ssl off;
context: mail, server

Enables the SSL/TLS protocol for the given server.

syntax: ssl_certificate file;
default:
context: mail, server

Specifies a file with the certificate in the PEM format for the given server. If intermediate certificates should be specified in addition to a primary certificate, they should be specified in the same file in the following order: the primary certificate comes first, then the intermediate certificates. A secret key in the PEM format may be placed in the same file.

syntax: ssl_certificate_key file;
default:
context: mail, server

Specifies a file with the secret key in the PEM format for the given server.

syntax: ssl_prefer_server_ciphers on | off;
default:
ssl_prefer_server_ciphers off;
context: mail, server

Specifies that server ciphers should be preferred over client ciphers when the SSLv3 and TLS protocols are used.

syntax: ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2];
default:
ssl_protocols SSLv3 TLSv1 TLSv1.1 TLSv1.2;
context: mail, server

Enables the specified protocols. The TLSv1.1 and TLSv1.2 parameters work only when the OpenSSL library of version 1.0.1 or higher is used.

The TLSv1.1 and TLSv1.2 parameters are supported starting from versions 1.1.13 and 1.0.12 so when the OpenSSL version 1.0.1 or higher is used on older nginx versions, these protocols work, but cannot be disabled.

syntax: ssl_session_cache off | none | [builtin[:size]] [shared:name:size];
default:
ssl_session_cache none;
context: mail, server

Sets the types and sizes of caches that store session parameters. A cache can be of any of the following types:

off
the use of a session cache is strictly prohibited: nginx explicitly tells a client that sessions may not be reused.
none
the use of a session cache is gently disallowed: nginx tells a client that sessions may be reused, but does not actually store session parameters in the cache.
builtin
a cache built in OpenSSL; used by one worker process only. The cache size is specified in sessions. If size is not given, it is equal to 20480 sessions. Use of the built-in cache can cause memory fragmentation.
shared
a cache shared between all worker processes. The cache size is specified in bytes; one megabyte can store about 4000 sessions. Each shared cache should have an arbitrary name. A cache with the same name can be used in several servers.

Both cache types can be used simultaneously, for example:

ssl_session_cache builtin:1000 shared:SSL:10m;

but using only shared cache without the built-in cache should be more efficient.

syntax: ssl_session_ticket_key file;
default:
context: mail, server

This directive appeared in version 1.5.7.

Sets a file with the secret key used to encrypt and decrypt TLS session tickets. The directive is necessary if the same key has to be shared between multiple servers. By default, a randomly generated key is used.

If several keys are specified, only the first key is used to encrypt TLS session tickets. This allows configuring key rotation, for example:

ssl_session_ticket_key current.key;
ssl_session_ticket_key previous.key;

The file must contain 48 bytes of random data and can be created using the following command:

openssl rand 48 > ticket.key

syntax: ssl_session_timeout time;
default:
ssl_session_timeout 5m;
context: mail, server

Specifies a time during which a client may reuse the session parameters stored in a cache.

syntax: starttls on | off | only;
default:
starttls off;
context: mail, server

on
allow usage of the STLS command for the POP3 and the STARTTLS command for the IMAP;
off
deny usage of the STLS and STARTTLS commands;
only
require preliminary TLS transition.