Demo
Demo

Knowledge base

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

tls-min-version

<transmissions-api-listener>

The lower bound of the TLS version on the Transmissions API entry point
in the configuration this is a linetls-min-version tlsv1.2inside 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
A version floor on the second submission method

The line sets the protocol version below which the API entry point will not go. The default is tlsv1.2, the manual names it directly (§ 3.3.21.7).

This entry point is not a level of the mail listener but a separate entry point. The line names match <smtp-listener>, which makes it seem that one setting overrides the other. Not at all: each entry point has its own values, and there is neither inheritance nor precedence between them.

There are fewer compatibility arguments here than with mail. At the other end there are not a thousand foreign receivers but your own clients submitting messages — you know their version and can update it.

The main trap is looking for this bound in the node’s general settings. It lives inside the entry point block, not at the root of the file, and grep over the root will not find it. With several entry points each has its own bound.
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 default is sensible; lower it only for a specific client:

Value When
tlsv1.2 (default) always
tlsv1.3 all submitting clients are your own and modern
tlsv1.1 and lower an old client that cannot be updated

The submission key travels in the Authorization header — that is, inside the encrypted conversation. Lowering the bound weakens exactly its protection.

The values and the tlsv1.2 default come from the manual (§ 3.3.21.7). That the key travels in the Authorization header is from there too (§ 8.1.1). The remark about there being no inheritance from the mail listener is ours.
Example configuration
# each entry point has its own bounds; there is no inheritance between entry points
<transmissions-api-listener 1.2.3.4:8585>
    tls-certificate /etc/pmta/transmissions-api-certificate.pem
    tls-min-version tlsv1.2</transmissions-api-listener>
The default, written explicitly. There is a reason to write it down when there are several entry points and their bounds differ.
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▶

Expecting the mail listener setting to carry over to the API entry point

our experience

What it costsThe line names match, the blocks are different. The mail entry point setting does not affect the API entry point in any way, and vice versa.
How to spot itThe bound is set on the listener, but the API entry point negotiates something else.
How to do it rightSet it in the block in question. These two entry points have no common level.

Lowering the bound “to make the old client work”

§ 3.3.21.7

What it costsThe submission key travels inside the same encrypted conversation. Lowering the bound weakens the protection of the key that grants the right to send messages on your behalf.
How to spot itThe entry point block has tlsv1 or tlsv1.1.
How to do it rightUpdate the client. Lowering is a temporary measure with a recorded deadline.
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-min-version { tlsv1 | tlsv1.1 | tlsv1.2 | tlsv1.3 }
Values
tlsv1 | tlsv1.1 | tlsv1.2 | tlsv1.3
Default
tlsv1.2 § 3.3.21.7
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>. There is no level above this entry point — neither the node settings nor the mail listener settings affect it.
⇄

Related directives

3 relations

Same name in other blocks

tls-min-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.7

Works together with

log-tls<transmissions-api>The switch that shows why the handshake on this entry point failed lives in the neighboring block. inferencetls-max-version<transmissions-api-listener>The other bound of the same range on this entry point. § 3.3.21.8

Referenced from

tls-allow-tlsv1.3<transmissions-api-listener>Replaced the whole set of five switches: the version range on this input is set by a pair of bounds. § 3.3.21.2tls-allow-tlsv1.2<transmissions-api-listener>Replaced the whole set of five switches: the version range on this input is set by a pair of bounds. § 3.3.21.3tls-allow-tlsv1.1<transmissions-api-listener>Replaced the whole set of five switches: the version range on this input is set by a pair of bounds. § 3.3.21.4tls-allow-tlsv1<transmissions-api-listener>Replaced the whole set of five switches: the version range on this input is set by a pair of bounds. § 3.3.21.5tls-allow-sslv3<transmissions-api-listener>It sets the lower bound on this input; separate switches are no longer needed. § 3.3.21.6

How to check on the node
Query the entry point from the client side; the version that should be negotiated:
openssl s_client -connect NODE:8585 -tls1_2 -brief </dev/null
Protocol version: TLSv1.2 means the floor is no higher. To ask for a forbidden version, first allow it on your own client: -tls1_1 -cipher ‘DEFAULT:@SECLEVEL=0’; the response tlsv1 alert protocol version means a refusal by the node, not by your client.
◇

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