Demo
Demo

Knowledge base

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

tls-certificate-san-or-cn

<smtp-user>

The name that must appear in the submitter's certificate
in the configuration this is a linetls-certificate-san-or-cninside the block <smtp-user>
Not just “from our authority,” but “from exactly this client”

Chain verification answers the question “did our own authority issue the certificate.” This line answers the second, much more important one: is it the right client.

The value is a fully qualified domain name without wildcards. It is matched against the SAN or CN field of the client certificate.

A wildcard is allowed on the certificate side. The manual gives an example: a certificate with SAN *.messagebird.com will match the configured name pmta.messagebird.com. That is, the asterisk is set by the client, not by us, and it covers only the first label.

It works with authentication-method set to ca-file, on top of tls-ca-file.

The main trap is a wildcard on the client side. A certificate with SAN *.example.com will pass the check for any first-level name in that domain. If the authority issues such certificates, the name check narrows the circle down to the domain, not to a specific machine.
What the Hub does. It does not write it: submission goes by login and password. The line is worth remembering as a mandatory part of certificate verification: without it the chain only answers “is it our authority.”
Recommended values

The value is a fully qualified domain name. What it gives and what it does not:

Client certificate Configured name Passes
SAN pmta.example.com pmta.example.com yes
SAN *.example.com pmta.example.com yes — the wildcard is set by the client
SAN pmta.other.com pmta.example.com no
a wildcard in our line — not allowed: the name is set in full
The matching rule, the ban on wildcards in the value and the permission for wildcards in the certificate come from the manual (§ 3.3.8.5). The remark about what a client wildcard gives is ours.
Example configuration
# the chain answers “our authority,” this line — “the right client”
<smtp-user foo>
    authentication-method ca-file
    tls-ca-file /etc/pmta/ca-certs.pem
    tls-certificate-san-or-cn pmta.messagebird.com</smtp-user>
The manual’s example. A certificate with SAN *.messagebird.com will pass this check: the wildcard is set by the client, and it covers the first label.
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 ends1 mistake▶

Writing a wildcard in the value

§ 3.3.8.5

What it costsThe name is set in full, without wildcards. A line with an asterisk will match nothing, and the login will stop authenticating.
How to spot itA client with a correct certificate gets a refusal.
How to do it rightSpecify the full name. A wildcard is acceptable only in the certificate itself, on the client side.
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-san-or-cn <domain>
Values
a fully qualified domain name without wildcards
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. It works on top of tls-ca-file and does not apply without it.
⇄

Related directives

1 relation

Does not work without

tls-ca-file<smtp-user>The name check works on top of chain verification and does not apply without it. § 3.3.8.5

How to check on the node
Which names are in the client’s certificate is visible before setup:
openssl x509 -in client.pem -noout -text | grep -A1 "Subject Alternative Name"
If the SAN has a wildcard, the check will narrow the circle to the domain, not to a machine. It is worth knowing this in advance and, if you need it stricter, asking the client for a certificate without a wildcard.
◇

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-certificateauthentication-methodpasswordsourceAll 6 directives of the block →