Demo
Demo

Knowledge base

PMTA knowledge base›Block <domain>›Directive§ 3.3.10.108.14

smtp-tls-ca-file

<domain>

The list of trusted root certificates for verifying the receiver
in the configuration this is a linesmtp-tls-ca-fileinside the block <domain>
Whom to trust when verifying the receiver’s certificate

Ordinary STARTTLS does not verify authenticity — the receiver can present any certificate, even a self-signed one. Verification is enabled by this line: it names the file with root certificates against which the presented chain is checked.

What happens when verification fails depends on the neighbor. With opportunistic encryption the node falls back to plain text; with require-starttls enabled it returns a temporary 4xx refusal, and the message stays in the queue.

By default the list from the distribution is used — the Mozilla CA set. This line replaces it rather than extending it.

The MTA-STS and DANE mechanisms verify the certificate themselves, but differently: MTA-STS by the chain and the name, that is, with the same list; DANE by the fingerprint from DNS, and it does not need the list at all.

The main trap is the silent fallback. Without require-starttls a failed verification is not a refusal but sending in plain text: that is, a line added for security leaves the message with no encryption at all in the worst case. Certificate verification makes sense only together with mandatory encryption.
What the Hub does. It does not write it — it keeps the list from the distribution. It is updated together with PowerMTA and covers all the large receivers; a custom list is needed where the receiver presents a certificate from an internal certificate authority. Verification at large receivers is provided by use-mta-sts, which does it itself.
Recommended values

The value is a path to a file. Only one thing is decided here: whose list to use:

What When
do not set (default) always: the Mozilla list from the distribution covers public authorities
your own file the receiver presents a certificate from an internal authority

And always next to it — require-starttls. Without it a failed verification silently turns into unencrypted delivery.

The behavior on failed verification in the two modes and the list from the distribution come from the manual (§ 3.3.10.108.14 and § 10.6). The advice to pair it with mandatory encryption is ours.
Example configuration
# certificate verification makes sense only together with mandatory encryption
<domain internal.example.com>
    use-starttls yes
    require-starttls yes
    smtp-tls-ca-file /etc/pmta/certchain.pem</domain>
Remove the second line — and a failed verification will lead not to a refusal but to sending in plain text. A custom list is needed exactly here: the internal receiver has a certificate from its own authority.
yellow — — directive names, blue — blocks. They are highlighted the same way in the text of the card.
▲

Common mistakes and problems

what people get wrong and how it ends2 mistakes▶

Enabling verification without mandatory encryption

§ 3.3.10.108.14

What it costsWith opportunistic encryption a failed verification leads to a fallback to plain text. A setting added for security makes the result worse.
How to spot itAfter verification is enabled, messages without a protocol version appear for the receiver in accounting.
How to do it rightPut require-starttls next to it. Then a failed verification is a temporary refusal, not unencrypted delivery.

Replacing the distribution list with your own for the sake of one receiver

our experience

What it costsThe line replaces the set entirely. Your own file with one internal authority, placed in <domain *>, leaves the node without public root certificates.
How to spot itVerification stops passing for all receivers at once.
How to do it rightPut the line in the specific receiver’s block — or include the public roots in the file too.
Compatibility
PowerMTA 6.0
described in the manual of this version · platform: any
The vendor does not state the first version for every directive — there is no note here. The name also appears in the 5.0 edition of the manual.
Reference data
Syntax
smtp-tls-ca-file <path>
Values
a path to a file with one or more root certificates
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<domain>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The directive lives in <domain> and merges by the usual recipient block rule: the most precise match on the receiver’s name wins. The same three levels apply by sending address — node, <virtual-mta-pool>, <virtual-mta>. The list replaces the set from the distribution rather than extending it.
⇄

Related directives

2 relations

Does not work without

use-starttls<domain>A certificate chain can be verified only on an encrypted connection. § 3.3.10.108.14

Affects

require-starttls<domain>Mandatory encryption decides what a failed verification turns into: a temporary refusal or sending in plain text. § 3.3.10.108.14

Referenced from

use-dane<domain>DANE checks the fingerprint from DNS, not a chain of certificate authorities — it does not need a trusted list. § 3.3.10.108.14

How to check on the node
What the receiver presents and whether the chain checks out is easier to verify from outside:
openssl s_client -starttls smtp -connect mx.example.com:25 -CAfile /etc/pmta/certchain.pem
The line Verify return code: 0 (ok) means the chain checks out. A non-zero code means verification will fail on the node too: with mandatory encryption that is a temporary refusal, without it delivery in plain text.
◇

What else to read

3 articles

◇Submission over HTTPS on its own listener, modeled on SparkPostA separate entry point: its own listener with a certificate, its own keys and a reserved source name through which the usual submission settings apply to such mail.◇The receiver declares an encryption requirement on its websiteThe node fetches the recipient domain’s policy over HTTPS and, if it is in enforce mode, delivers only when the MX matches, the connection is encrypted and the certificate is verified.◇The receiver declares an encryption requirement in its DNS zoneThe node looks at the recipient domain’s DANE records and, if STARTTLS is required, sends only over an encrypted channel with a certificate verified by fingerprint.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Connection encryption
Neighboring settings of the block <domain>:use-starttlsuse-danesmtp-tls-min-versionuse-mta-stsrequire-starttlsAll 135 directives of the block →