Demo
Demo

Knowledge base

PMTA knowledge base›Block Global›Directive§ 3.3.1.10

smtp-server-tls-certificate

Globalset by the Hub

The certificate the node presents when receiving mail
in the configuration this is a linesmtp-server-tls-certificateinside the block Global
How the node introduces itself to those who submit mail to it

The line names the certificate the node presents when a client starts encryption on an inbound connection. Everything discussed so far on the TLS pages was about the outbound side; here the node acts as the server.

Two storage locations. A PEM file is the usual case; the other is a secrets store, referenced with a {vault}:path/key entry. The private key password is optional and is given as the second word — also either as a string or as a reference to the store.

Four combinations, and the manual gives three of them as examples: a file plus a plain password, the store plus a plain password, the store for both.

Without this line encryption on receiving does not work at all — there is nothing to present. Allowing a client to start encryption is a separate line, allow-starttls in the source.

The main trap is a plain-text password in the configuration. It is the second part of the line and ends up in backups together with the file. If the key is encrypted, the password is worth keeping in a secrets store; if there is no store, understand that protecting the key with a password gives nothing here.
What the Hub does. It writes it — in the node’s base configuration, and issues a self-signed certificate itself. This is enough for submission: the platform connects to its own node and has no need to verify anyone’s authenticity. The user can replace it with their own, and then the password is worth moving to the store — the Hub does not do this yet.
Recommended values

The notation and what is stored where:

Certificate Password When
file not set the key is not encrypted — the simplest case
file as a string the password ends up in the configuration in plain text
file {vault}:path/key the password is in the store, only a reference is in the configuration
{vault}:path/key {vault}:path/key neither the certificate nor the password is in the node’s files

What to watch is the expiration date. An expired certificate means submission stops being encrypted, and with strict platform settings the platform stops connecting altogether.

The notation, the four combinations and the PEM requirement come from the manual (§ 3.3.1.10). The advice to keep the password in the store and watch the expiration date is ours.
Example configuration
# this is how the Hub writes the base configuration — self-signed, no password
smtp-server-tls-certificate /etc/pmta/mtahub-smtp.pem
# both values from the secrets store — the manual's example
smtp-server-tls-certificate {vault}:/v1/kv/data/tlsCerts:smtp-cert {vault}:/v1/kv/data/tlsCerts:smtp-password
The first option is enough for submission from your own platform. The second is needed when the certificate is a real one and its private key must not sit as a file on the node.
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▶

Putting the key password in the configuration in plain text

§ 3.3.1.10

What it costsThe password can be read by anyone with access to the configuration file, and it ends up in backups. An encrypted key next to a plain-text password is protected exactly as well as the file itself.
How to spot itIt is discovered during an access review, not in operation.
How to do it rightKeep the password in a secrets store and reference it with a {vault}:path/key entry. If there is no store, do not consider the password a protection.

Not watching the expiration date

our experience

What it costsAn expired certificate means submission stops being encrypted, and a platform with strict verification stops connecting altogether. The failure shows up on the platform side, and the search for the cause starts somewhere other than the node.
How to spot itSubmission stops on a particular day with no configuration changes.
How to do it rightCheck notAfter with the command from the reference and set a reminder. The Hub’s self-signed certificate also has an expiration date.
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-server-tls-certificate { FILENAME | {vault}:PATH/KEY } [PASSWORD | {vault}:PATH/KEY]
Values
a path to a PEM file or a reference to the secrets store, with the password as the second word if needed
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
Global
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The directive is written at the root of the file, in the Global section, and applies to the whole node. It has no levels; for an individual listener there is a line of its own — tls-certificate in <smtp-listener>, and it overrides the common certificate for connections to that address and port.
⇄

Related directives

3 relations

Depends on

openssl-security-levelGlobalThe library’s security level may reject a certificate key that is too weak — and then the node will not start. § 3.3.1.51

Can be replaced by

An external secrets vaultBoth the certificate and its password can be kept not as a file but in a secrets store. § 3.3.1.10

Often used with

Change a signing key without interrupting sendingA neighboring task with the same rhythm: the validity period runs out, and the replacement has to be prepared in advance. § 1.6.2

Referenced from

smtp-server-tls-ca-fileGlobalThat certificate the node presents itself; this list is for verifying certificates presented to it. § 3.3.1.11allow-starttls<source>Permission to start encryption is pointless without a certificate: there will be nothing to present. § 3.3.1.10tls-certificate<smtp-listener>The same setting at the node level: if not set on the listener, it is inherited from there. § 3.3.17.4

How to check on the node
What the node presents and whether it has expired is easiest to check from outside:
openssl s_client -starttls smtp -connect localhost:25 -showcerts 2>/dev/null | openssl x509 -noout -subject -enddate
An empty result means encryption on receiving does not come up: either there is no certificate, or the client is not allowed to start encryption — allow-starttls in the source. The notAfter date is what to watch.
◇

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
Value
The Hub picks it itself — pace, warm-up stage, metrics
Cost of a mistake
reversible: harms only while it is set
Scenarios
Node security · Connection encryption
Neighboring settings of the block Global:openssl-security-levelsmtp-server-tls-min-versionhttp-tls-min-versionsmtp-server-tls-cipherssmtp-server-tls-cipher-server-preferenceAll 108 directives of the block →