SSL#
Provides the necessary support for a mail proxy server to work with the SSL/TLS protocol.
When building from the source code,
this module isn't built by default;
it should be enabled with the
‑‑with‑mail_ssl_module
build option.
In packages and images from our repos, the module is included in the build.
Important
This module requires the OpenSSL library.
Configuration Example#
To reduce the processor load it is recommended to
set the number of worker processes equal to the number of processors,
enable the shared session cache,
disable the built-in session cache,
and possibly increase the session lifetime (by default, 5 minutes):
mail {
...
server {
listen 993 ssl;
ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;
ssl_ciphers AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
ssl_certificate /usr/local/angie/conf/cert.pem;
ssl_certificate_key /usr/local/angie/conf/cert.key;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;
# ...
}
Directives#
ssl_certificate#
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.
This directive can be specified multiple times to load certificates of different types, for example, RSA and ECDSA:
server {
listen 993 ssl;
ssl_certificate example.com.rsa.crt;
ssl_certificate_key example.com.rsa.key;
ssl_certificate example.com.ecdsa.crt;
ssl_certificate_key example.com.ecdsa.key;
# ...
}
Only OpenSSL 1.0.2 or higher supports separate certificate chains for different certificates. With older versions, only one certificate chain can be used.
Important
Variables can be used in the file name when using OpenSSL 1.0.2 or higher:
ssl_certificate $ssl_server_name.crt;
ssl_certificate_key $ssl_server_name.key;
Note that using variables implies that a certificate will be loaded for each SSL handshake, and this may have a negative impact on performance.
The value "data:certificate" can be specified instead of the file, which loads a certificate without using intermediate files.
Note that inappropriate use of this syntax may have its security implications, such as writing secret key data to error log.
ssl_certificate_key#
Specifies a file with the secret key in the PEM format for the given server.
Important
Variables can be used in the file name when using OpenSSL 1.0.2 or higher.
The value "engine:name:id" can be specified instead of the file, which loads a secret key with a specified id from the OpenSSL engine name.
The value "data:key" can be specified instead of the file, which loads a secret key without using intermediate files. Note that inappropriate use of this syntax may have its security implications, such as writing secret key data to error log.
ssl_ciphers#
Specifies the enabled ciphers. The ciphers are specified in the format understood by the OpenSSL library, for example:
ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
The full list can be viewed using the "openssl ciphers" command.
ssl_client_certificate#
Specifies a file with trusted CA certificates in the PEM format used to verify client certificates.
The list of certificates will be sent to clients. If this is not desired, the ssl_trusted_certificate directive can be used.
ssl_conf_command#
Sets arbitrary OpenSSL configuration commands.
Important
The directive is supported when using OpenSSL 1.0.2 or higher.
Several ssl_conf_command directives can be specified on the same level:
ssl_conf_command Options PrioritizeChaCha;
ssl_conf_command Ciphersuites TLS_CHACHA20_POLY1305_SHA256;
These directives are inherited from the previous configuration level if and only if there are no ssl_conf_command directives defined on the current level.
Caution
Note that configuring OpenSSL directly might result in unexpected behavior.
ssl_crl#
Specifies a file with revoked certificates (CRL) in the PEM format used to verify client certificates.
ssl_dhparam#
Specifies a file with DH parameters for DHE ciphers.
Caution
By default no parameters are set, and therefore DHE ciphers will not be used.
ssl_ecdh_curve#
Specifies a curve for ECDHE ciphers.
Important
When using OpenSSL 1.0.2 or higher, it is possible to specify multiple curves, for example:
ssl_ecdh_curve prime256v1:secp384r1;
The special value auto instructs Angie to use a list built into the OpenSSL library when using OpenSSL 1.0.2 or higher, or prime256v1 with older versions.
Important
When using OpenSSL 1.0.2 or higher, this directive sets the list of curves supported by the server. Thus, in order for ECDSA certificates to work, it is important to include the curves used in the certificates.
ssl_password_file#
Specifies a file with passphrases for secret keys where each passphrase is specified on a separate line. Passphrases are tried in turn when loading the key.
Example:
mail {
ssl_password_file /etc/keys/global.pass;
...
server {
server_name mail1.example.com;
ssl_certificate_key /etc/keys/first.key;
}
server {
server_name mail2.example.com;
# named pipe can also be used instead of a file
ssl_password_file /etc/keys/fifo;
ssl_certificate_key /etc/keys/second.key;
}
}
ssl_prefer_server_ciphers#
|
|
Default |
|
mail, server |
Specifies that server ciphers should be preferred over client ciphers when the SSLv3 and TLS protocols are used.
ssl_protocols#
|
|
Default |
|
mail, server |
Changed in version 1.2.0: TLSv1.3 parameter added to default set.
Enables the specified protocols.
Important
The TLSv1.1 and TLSv1.2 parameters work only when OpenSSL 1.0.1 or higher is used.
The TLSv1.3 parameters works only when OpenSSL 1.1.1 or higher is used.
ssl_session_cache#
|
|
Default |
|
mail, server |
Sets the types and sizes of caches that store session parameters. A cache can be of any of the following types:
|
the use of a session cache is strictly prohibited: Angie explicitly tells a client that sessions may not be reused. |
|
the use of a session cache is gently disallowed: Angie tells a client that sessions may be reused, but does not actually store session parameters in the cache. |
|
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. |
|
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. It is also used to automatically generate, store, and periodically rotate TLS session ticket keys unless configured explicitly using the ssl_session_ticket_key directive. |
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.
ssl_session_ticket_key#
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 80 or 48 bytes of random data and can be created using the following command:
openssl rand 80 > ticket.key
Depending on the file size either AES256 (for 80-byte keys) or AES128 (for 48-byte keys) is used for encryption.
ssl_session_tickets#
Enables or disables session resumption through TLS session tickets.
ssl_session_timeout#
Specifies a time during which a client may reuse the session parameters.
ssl_trusted_certificate#
Specifies a file with trusted CA certificates in the PEM format used to verify client certificates.
In contrast to the certificate set by ssl_client_certificate, the list of these certificates will not be sent to clients.
ssl_verify_client#
|
|
Default |
|
mail, server |
Enables verification of client certificates. The verification result is passed in the "Auth-SSL-Verify" header of the authentication request.
|
requests the client certificate and verifies it if the certificate is present. |
|
requests the client certificate but does not require it to be signed by a trusted CA certificate. This is intended for the use in cases when a service that is external to Angie performs the actual certificate verification. The contents of the certificate is accessible through requests sent to the authentication server. |
ssl_verify_depth#
Sets the verification depth in the client certificates chain.
starttls#
Sets the verification depth in the client certificates chain.
|
allow usage of the STLS command for the POP3 and the STARTTLS command for the IMAP and SMTP; |
|
deny usage of the STLS and STARTTLS commands; |
|
require preliminary TLS transition. |