Demo
Demo

Knowledge base

PMTA knowledge base›Block <domain-key-list>›Directive§ 3.3.19.1

domain-key

<domain-key-list>

The same signing key, but inside a named list
in the configuration this is a linedomain-keyinside the block <domain-key-list>
The same name 3:<domain-key-list>Global<virtual-mta><virtual-mta-pool>— some of them are other settings, some are the same one
A key chosen by the submitting side

The same line as at the node level, declared inside a <domain-key-list> block. The definition is on the common page; what matters here is how this location differs.

The list is chosen by the message, not by the configuration. The submitting side sets the x-dkim-options header with the list name — and the node looks for a key only in it. If none is found, the message is not signed at all; the search does not move on to the general declarations.

Without the list being named, it does not take part. A message without this header is signed by the usual rule: first the stream’s declarations, then the node level’s.

The block itself can be declared only at the node level.

The main trap is that the search does not go beyond the list. Regular declarations work as a chain: if one does not match, the next is tried. A list does not: if no match is found in it, the message goes out unsigned, although a suitable key exists on the node.
What the Hub does. It does not use it: the Hub separates clients by streams, not by key lists. The mechanism will come in handy if the submitting side must choose the key itself — for example, when sending on behalf of several clients through one node.
Recommended values

Put the full set into the list. The search does not go beyond it, so a fallback declaration with a wildcard is appropriate in it — unlike the general level, where it intercepts everything.

The list name is part of the agreement with the submitting side. It goes into the message header, so it does not change in the configuration alone.

One list per sender. Then its name reads in the message header without explanation.

The advice about the full set and the list name is ours. From the manual here come the syntax of the list selection header, the limitation of the search to the list and the fact that the block is declared only at the node level.
Example configuration
# one client's set of keys, together with a fallback
<domain-key-list keylist-customer-one>
    domain-key m, mail.port25.com, /etc/pmta/m.pem    domain-key base, *, /etc/pmta/base.pem</domain-key-list>
A message with the header x-dkim-options: s=m;key-list=keylist-customer-one will look for a key only here. If it finds none, it will go out without a signature.
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 a fallback to the general declarations

§ 3.3.19

What it costsThe search does not go beyond the named list. The message goes out unsigned, although a suitable key is declared on the node — just elsewhere.
How to spot itMessages with the list selection header are not signed; the rest are.
How to do it rightAdd the missing declaration to the list — or a fallback with a wildcard.

Renaming the list without warning the submitting side

our experience

What it costsThe list name is in the message header. After renaming, messages name a list that does not exist and stop being signed.
How to spot itThe signature disappeared for one sender right after a configuration edit.
How to do it rightChange the name together with the submitting side or keep the old name as a second list.
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
domain-key <key-entry>
Values
three comma-separated values — a selector, a domain or an asterisk, a file path or a reference to a secrets vault
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<domain-key-list>
How many times
may be repeated
Everything here comes from the manual, with the section.
Inheritance
Declarations inside a list do not take part in the regular search: they are available only to messages that named this list in the x-dkim-options header. The list has no inheritance — the <domain-key-list> block itself is declared only at the node level. It is picked up by pmta reload.
⇄

Related directives

2 relations

Does not work without

process-x-dkim-options<source>The list is chosen by a message header, and processing of that header is enabled by that line on the source. § 3.3.7.45

Same name in other blocks

domain-keyGlobalThe full definition of the line — composition, selection rule, working with a secrets vault. § 3.3.1.55.1

How to check on the node
Which list the message named and whether a key was found in it is visible from its headers:
grep -n 'domain-key-list' /etc/pmta/config
grep -i 'DKIM-Signature' /var/log/pmta/pmta.log | tail -5
The absence of a signature header with a list set means no match was found in it: the search does not move on to the general declarations. The Hub does not use key lists.
◇

What else to read

3 articles

◇A license for a fleet, not for a serverThe license is not bound to a server: it is installed on as many machines as the instance limit allows, and the nodes send volume statistics to the vendor every hour.◇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.◇Address lists — named and unnamedA list of addresses, domains, patterns or hashes; a named one is attached by directives such as suppression, an unnamed one lives inside an inbound mail processor.

In the Hub
Managed at
DNS → Signing keys
Cost of a mistake
reversible: harms only while it is set
Scenarios
Message signing and authentication · Sender isolation