Demo
Demo

Knowledge base

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

tls-max-version

<transmissions-api-listener>

The upper bound of the TLS version on the Transmissions API input
in the configuration this is a linetls-max-version none, which behaves as tlsv1.3inside the block <transmissions-api-listener>
The same name 1:<smtp-listener><transmissions-api-listener>— some of them are other settings, some are the same one
Version ceiling on the second submission method

The second bound of the same range as tls-min-version. There is no default — the ceiling is unlimited, and the input negotiates the newest version the client offers.

There is one reason to set a ceiling: the library in the submitting program announces a modern version and fails on it. For the API this is a common case — people write the client themselves, and its HTTP library may be old.

This is a workaround for someone else’s breakage, not a security setting.

The main trap is setting a ceiling and forgetting it. The library gets updated, the reason disappears, and the input stays on the old version — together with the submission key passed through it.
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

Set it only for a specific reason:

Value When
do not set (default) always
tlsv1.2 the submitting client’s library breaks 1.3

The line is accompanied by a comment with the reason and a date — otherwise it will outlive the cause it appeared for.

The values and the absence of a default come from the manual (§ 3.3.21.8). The advice to write down the reason and date is ours.
Example configuration
# a workaround for a breakage in the client, not a security setting
<transmissions-api-listener 1.2.3.4:8585>
    tls-certificate /etc/pmta/transmissions-api-certificate.pem
    tls-max-version tlsv1.2   # client X's library breaks 1.3; recheck in 2027</transmissions-api-listener>
A comment with the reason and a deadline is part of the line. The second input can be left without a ceiling: the inputs’ bounds are independent.
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▶

Lowering the ceiling “just in case”

our experience

What it costsA ceiling protects nothing — it only forbids the new. On an input through which the submission key goes, this is a pure loss.
How to spot itThe input negotiates 1.2 even though clients support 1.3.
How to do it rightRemove the line. Limiting from below is the job of tls-min-version.

Setting a ceiling instead of investigating the client's breakage

our experience

What it costsThe cause — the library in the submitting program — remains, and the same breakage will surface on any other input this program goes to.
How to spot itThe client works with your API and does not work anywhere else.
How to do it rightSet the ceiling as a temporary measure and open a task to update the client.
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-max-version { tlsv1 | tlsv1.1 | tlsv1.2 | tlsv1.3 }
Values
tlsv1 | tlsv1.1 | tlsv1.2 | tlsv1.3
Default
none, which behaves as tlsv1.3 § 3.3.21.8
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 bound, and the mail listener’s settings do not reach here.
⇄

Related directives

1 relation

Same name in other blocks

tls-max-version<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.8

Referenced from

tls-min-version<transmissions-api-listener>The other bound of the same range on this entry point. § 3.3.21.8

How to check on the node
We ask the input for the newest version — it should be negotiated if no ceiling was set:
openssl s_client -connect NODE:8585 -tls1_3 -brief </dev/null
Protocol version: TLSv1.3 — there is no ceiling. alert protocol version instead means a ceiling is set and lowered below 1.3.
◇

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-certificatetls-cipherstls-ca-filetls-cipher-server-preferenceAll 15 directives of the block →