Demo
Demo

Knowledge base

PMTA knowledge base›Block <transmissions-api-listener>›Directive§ 3.3.21.12

tls-ca-file

<transmissions-api-listener>

File of trusted authorities for API input client certificates
in the configuration this is a linetls-ca-fileinside the block <transmissions-api-listener>
The same name 2:<smtp-listener><smtp-user><transmissions-api-listener>— some of them are other settings, some are the same one
Whom the API input trusts at the entrance

A PEM file with certificate authority certificates. The input uses them to verify the certificate sent by the submitting client. There is no default.

The input does not take its own certificate from here — there is tls-certificate for that. This line is about other parties’ certificates.

The manual contradicts itself about where to write the line. Section § 8.1.2 says to put it “inside the <transmissions-api> tag”, while the reference § 3.3.21.12 and the chapter 15 index — inside <transmissions-api-listener>. The latter two are right: the setting belongs to the input. Written in the wrong block, it silently does nothing.

A client certificate is not a substitute for the key. The right to submit messages is given by api-key in the header; certificate verification is an additional layer on top.

The main trap is writing the line in the <transmissions-api> block, as § 8.1.2 advises. There will be no error, and no verification either. It belongs in the input block.
What the Hub does. It does not write it: our submission goes over SMTP, and there is no API entry point block in the configuration.
Recommended values

The line is needed only where clients identify themselves with a certificate:

Value When
do not set (default) clients submit with a key
path to PEM the submitting client identifies itself with its own certificate

The file goes in the input block, not in <transmissions-api>.

The PEM format and the purpose come from the manual (§ 3.3.21.12). The discrepancy with § 8.1.2 about which block to write the line in is our finding; the chapter 15 index confirms the input block.
Example configuration
# trusted authorities for client certificates — in the INPUT block
<transmissions-api-listener 1.2.3.4:8585>
    tls-certificate /etc/pmta/transmissions-api-certificate.pem
    tls-ca-file /etc/pmta/certchain.pem</transmissions-api-listener>
Section § 8.1.2 shows this line inside <transmissions-api> — it will not work there.
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▶

Writing the line in the transmissions-api block on chapter 8's advice

§ 8.1.2

What it costsThe setting belongs to the input, not to the general API block. In the general block it silently does nothing — neither an error nor verification.
How to spot itThe file is set, but client certificates are not verified.
How to do it rightMove the line to <transmissions-api-listener>.

Putting the input's own certificate into the line

our experience

What it costsThe input will not pick it up: the line sets trusted authorities for other parties’ certificates, and its own is taken from tls-certificate.
How to spot itThe line is set, and the client still complains about the input’s certificate.
How to do it rightYour own certificate — into tls-certificate, other parties’ authorities — here.
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
tls-ca-file <path>
Values
path to a PEM file
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<transmissions-api-listener>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
No inheritance: the line applies inside its own <transmissions-api-listener>. Each input has its own list of trusted authorities.
⇄

Related directives

2 relations

Same name in other blocks

tls-ca-file<smtp-listener>The same-named line of the mail listener; here it is about a separate entry point, the API’s own. § 3.3.21.12

Works together with

tls-certificate<transmissions-api-listener>One line says who this input is; the other — whose client certificates it trusts. inference

How to check on the node
First we look at what the input presents and requests at all:
openssl s_client -connect NODE:8585 -msg </dev/null | grep -c CertificateRequest
1 — the input requests a client certificate, so the file has something to verify; 0 — it does not request one, and the line is useless. The file itself is parsed with the command openssl crl2pkcs7 -nocrl -certfile FILE | openssl pkcs7 -print_certs -noout.
◇

What else to read

3 articles

◇Who is allowed to submit mail and for whom to accept itOut of the box, the node accepts submission only from the machine itself; two different questions — “who can send through us” and “for whose addresses we accept mail” — are answered by different directives.◇The group that grants management rightsMembership in the pmta group gives an unprivileged user the right to call the node’s commands and use submission.◇How the node selects a source and combines its settingsA connection falls under all source blocks whose addresses cover it, and they act merged — the narrow one overrides the wide one; named blocks are attached only by direct reference.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Node security
Neighboring settings of the block <transmissions-api-listener>:tls-certificatetls-min-versiontls-max-versiontls-cipher-server-preferencetls-ciphersAll 15 directives of the block →