This plugin enables the use of TLS (via
STARTTLS) in Haraka.
For this plugin to work you must have SSL certificates installed correctly.
Key and certificate chain default locations are as follows. The paths
can be overridden in the
config/tls.ini file using
If you have a purchased certificate, append any intermediate/chained/ca-cert files to the certificate in this order:
- The CA signed SSL cert
- Any intermediate certificates
- The CA root certificate
cat mail.example.com.crt intermediary_cert.crt ca-cert.crt > config/tls_cert.pem
See also Setting Up TLS
Self Issued (unsigned) Certificate
Create a certificate and key file in the config directory with the following command:
openssl req -x509 -nodes -days 2190 -newkey rsa:2048 \ -keyout config/tls_key.pem -out config/tls_cert.pem
You will be prompted to provide details of your organization. Make sure the
Common Name is set to your servers Fully Qualified Domain Name, which should
be the same as the contents of your
The following settings can be specified in
Specifies an alternative location for the key file. If multiple keys are to be
key= assignment for each of them. Non-absolute paths are relative
For example, to configure single key and cert chain files, located in the
directory, use the following in
If multiple pairs of key and cert chain files should be used, outside of the haraka
config/ directory, configure instead:
key=/etc/ssl/private/example.com.rsa.key.pem cert=/etc/ssl/private/example.com.rsa.crt-chain.pem key=/etc/ssl/private/example.com.ecdsa.key.pem cert=/etc/ssl/private/example.com.ecdsa.crt-chain.pem
Specifies an alternative location for the certificate chain file. If multiple
certificate chains are to be used, use
cert= assignment for each of them.
Non-absolute paths are relative to the
config/ directory. See the description of
key parameter for specific use.
If needed, add this section to the
config/tls.ini file and list any IP ranges that have
broken TLS. Ex:
[no_tls_hosts] 192.168.1.3 172.16.0.0/16
The Node.js TLS page has additional information about the following options.
A list of allowable ciphers to use. Example:
If specified, the list of configured ciphers is treated as the cipher priority from
highest to lowest. The first matching cipher will be used, instead of letting the
client choose the cipher. The default is
Specifies the elliptic curve used for ECDH or ECDHE ciphers.
Only one curve can be specified. The default is
prime256v1 (NIST P-256).
Specifies the file containing the diffie-hellman parameters to
use for DH or DHE key exchange. Create such a file using
No DH ciphers can be used without this parameter given.
openssl dhparam -out config/dhparams.pem 2048
Whether Haraka should request a certificate from a connecting client.
requestCert=[true|false] (default: true)
Reject connections from clients without a CA validated TLS certificate.
rejectUnauthorized=[true|false] (default: false)
Specifies the OpenSSL API function used for handling the TLS session. Choose
one of the methods described at the
OpenSSL API page.
The default is
Inbound Specific Configuration
By default the above options are shared with outbound mail (either
smtp_proxy or plain outbound mail heading to
an external destination). To make these options specific to inbound
mail, put them under an
[inbound] parameter group. Outbound options
can go under an
[outbound] parameter group, and plugins that use
SMTP tls for queueing such as
use that plugin name for plugin specific options.