Demo
Demo

Knowledge base

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

tls-certificate

<transmissions-api-listener>

The certificate the Transmissions API entry point presents to clients
in the configuration this is a linetls-certificateinside 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
The only mandatory line of the API entry point

The Transmissions API is the second way to submit a message to the engine, besides SMTP: the client sends a POST with a JSON body. The entry point is declared with a <transmissions-api-listener> block on its own address and port, and this line sets the certificate it presents.

The line is mandatory, and that is the main difference from SMTP submission. The manual says directly: the conversation with clients goes over HTTPS, and every entry point needs a certificate (§ 8.1.1); the example there marks it accordingly — only this line is mandatory, the rest of the block is optional. This entry point has no unencrypted path at all — unlike SMTP submission, where STARTTLS may not be started.

A self-signed one is made with the engine’s own tool: pmtakeytool newcert > /etc/pmta/transmissions-api-certificate.pem. A real one from a certificate authority goes into the same line.

The password and the certificate itself can live in the vault — a {vault}:PATH/KEY entry instead of a file path, as for smtp-server-tls-certificate.

The main trap is forgetting about the password as the second part of the line. The engine will not read a certificate with an encrypted key without a password, while a password written next to it ends up in the configuration in plain text and in its backups. Either a key without a password plus file permissions, or the vault.
What the Hub does. It does not write it: our submission goes over SMTP to a separate port, and there is no API entry point block in the configuration at all.

Worth keeping in mind when discussing the second submission method: with the API, encryption is not optional — it is always there. The hole found in SMTP submission (a password may go out in plain text) cannot be created here.

Recommended values

The choice is where the certificate comes from:

Value When
a path to a PEM the usual case
a path to a PEM plus a password the key is encrypted, there is no vault
{vault} the fleet’s keys are revoked in one place

There is no default: without this line the API entry point will not come up.

The vault syntax comes from the manual (§ 3.3.21.1), the line being mandatory and the pmtakeytool recipe from chapter 8 (§ 8.1.1, § 8.1.2). The remark about the password in backups is ours.
Example configuration
# API entry point: one line is mandatory, the rest are optional
<transmissions-api-listener 1.2.3.4:8585>
    tls-certificate /etc/pmta/transmissions-api-certificate.pem</transmissions-api-listener>

<transmissions-api>
    api-key 14ac5499cfdd2bb2859e4476d2e5b1d2bad079bf
</transmissions-api>
The two blocks work only together: the entry point provides encryption, the key the right to submit. The port in the manual’s example is 8585, but it is arbitrary.
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 ends3 mistakes▶

Bringing up the API entry point without a certificate

§ 8.1.1

What it costsThe conversation goes over HTTPS, and without a certificate there is nothing to present. The entry point will not work — this is not “encryption turned off” but a broken entry point.
How to spot itThe block is in the configuration, but the client does not connect.
How to do it rightSet a certificate — your own or a self-signed one via pmtakeytool newcert.

Writing the key password as the second part of the line

our experience

What it costsThe password ends up in the configuration in plain text and gets into its backups along with everything else. File permissions start to matter more than intended.
How to spot itIn the file, next to the path, there is a word that looks like a password.
How to do it rightKeep the key without a password with file permissions, or move both the certificate and the password to the vault.

Checking a self-signed certificate with an ordinary client

§ 8.1.4

What it costsThe client refuses: the chain cannot be verified. It looks like a broken entry point, even though the entry point works fine.
How to spot itA certificate verification error instead of an API response.
How to do it rightFor the duration of the check, use –insecure with curl, as in the manual’s example. The permanent solution is a certificate from an authority.
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-certificate { FILENAME | {vault}:PATH/KEY } [PASSWORD | {vault}:PATH/KEY]
Values
a path to a PEM file or a vault key, with the password as the second word
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
There is no inheritance: the line applies inside its <transmissions-api-listener> — to its address and port. There can be several entry points, and each has its own certificate. There is no link with the mail listener block at all: these are different entry points, not levels of one.
⇄

Related directives

2 relations

Same name in other blocks

tls-certificate<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.1

Works together with

api-key<transmissions-api>Encryption proves who the listener is; the key proves who the client is. The API entry point requires both. § 8.1

Referenced from

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

How to check on the node
Look at which certificate the entry point presents — take the port from its block:
openssl s_client -connect NODE:8585 -brief </dev/null
Peer certificate: CN=… shows the presented certificate, verify error:num=18 that it is self-signed. Full submission is checked with a request: curl –insecure -H “Authorization: KEY” -H “Content-Type: application/json” –data @msg.json https://NODE:8585/api/v1/transmissions.
◇

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-min-versiontls-max-versiontls-ca-filetls-cipher-server-preferencetls-ciphersAll 15 directives of the block →