Demo
Demo

Knowledge base

PMTA knowledge base›Block <smtp-user>›Directive§ 3.3.8.3

tls-certificate

<smtp-user>

The specific certificate that confirms this login
in the configuration this is a linetls-certificateinside the block <smtp-user>
The same name 2:<smtp-listener><smtp-user><transmissions-api-listener>— some of them are other settings, some are the same one
One login — one certificate

The line names that very certificate file the client must present during authentication. Not “a certificate from such-and-such authority,” but exactly this one.

It works only with authentication-method set to certificate. And it requires an encrypted connection — the certificate is presented during the TLS negotiation.

The certificate can be issued with the tool from the distribution — pmtakeytool — or with ordinary OpenSSL.

The difference from the trusted authority method. Here the check is literal: one file will do. There, any certificate that chains up; more convenient when there are many logins, and weaker when there is one login.

The main trap is the validity period. The certificate expires, and on that day submission stops. Unlike a password, the date is visible in advance — but only if someone looks at it.
What the Hub does. It does not write it: submission goes by login and password. Certificate verification will be needed for a platform that insists on it; along with it you need to decide who issues the certificate and who keeps track of its expiry.
Recommended values

The value is a path to a file. What is decided along with it:

What Note
who issues it pmtakeytool from the distribution or OpenSSL
validity period submission will stop on the expiry date
where the client’s private key lives with the submitting side, not with us
connection encryption mandatory, otherwise the method does not work
The requirement of the “certificate” method, the need for TLS and the mention of pmtakeytool come from the manual (§ 3.3.8.3). The remarks about expiry and responsibility are ours.
Example configuration
# the login is confirmed by a specific file, not by a password
<smtp-user foo>
    authentication-method certificate
    tls-certificate /etc/pmta/bar-cert.pem</smtp-user>
The manual’s example. Both lines are needed together: without the first, the second plays no part. And the connection must be encrypted.
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▶

Not watching the expiration date

our experience

What it costsOn the expiry date the login stops authenticating. The configuration has not changed, and the cause is sought everywhere else.
How to spot itSubmission for one login stops on a specific date.
How to do it rightKnow notAfter and renew in advance. The check is a single command.

Setting the file without choosing the verification method

§ 3.3.8.3

What it costsWith the default authentication-method the node checks a password, not a certificate. The line is there and plays no part in anything.
How to spot itThe client presents a certificate, the node asks for a password.
How to do it rightSet authentication-method certificate in the same block.
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 <path>
Values
a path to the certificate file
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<smtp-user>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The directive lives in <smtp-user> and applies to one login; it has no inheritance. The encryption requirement is set separately, in <source>, and applies to the connection before the login is given.
⇄

Related directives

1 relation

Does not work without

authentication-method<smtp-user>The line works with the “certificate” method and only with it. § 3.3.8.3

How to check on the node
The certificate’s validity period is worth checking before it runs out:
openssl x509 -in /etc/pmta/bar-cert.pem -noout -subject -enddate
The notAfter date is the day submission for this login will stop. It is worth setting a reminder right when it is issued.
◇

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 <smtp-user>:tls-ca-filetls-certificate-san-or-cnauthentication-methodpasswordsourceAll 6 directives of the block →