Demo
Demo

Knowledge base

PMTA knowledge base›Block Global›Directive§ 3.3.1.55.1

domain-key

Globalcritical

DKIM or ARC signing key for a sending domain
in the configuration this is a linedomain-keyinside the block Global
The same name 3:<domain-key-list>Global<virtual-mta><virtual-mta-pool>— some of them are other settings, some are the same one
Signing key for a sending domain

It links three things: a selector, a sending domain and a private key — from a file or from a secrets vault. There can be any number of declarations, and they form a set from which the node chooses when signing.

The first matching declaration wins. The node goes down the list from top to bottom and takes the first key whose domain matches the signing domain or is its parent. A key for example.com will fit messages from mail.example.com; the reverse is not true. Keys inside <virtual-mta> are stronger than general ones.

The selector is the name of the DNS record. The public part is published as <selector>._domainkey.<domain>, and that is how the receiver finds the key. The “selector and domain” pair must match down to the character.

The main trap is key rotation. You cannot replace the file under the same selector: messages sitting in the queue are signed with the old key, and removing the record from DNS breaks their verification at the receiver. Rotation means a new selector, waiting, and only then removing the old one.
What the Hub does. It writes it — but not at the root of the file, rather in the sending address block: each stream has its own key. It keeps the keys themselves on the domain card in the “DNS → Domains and zones” section, publishes the records and distributes the declarations across the nodes. Rotation follows the rules: a new selector, waiting for the queues to drain, removing the old one. The waiting period is counted from bounce-after.
Recommended values

The asterisk goes last. A declaration with the * domain fits any message, and the search goes from top to bottom: placed higher, it will intercept messages for which an exact key lies further down. The manual advises exactly this.

A key from the vault goes after the exact declarations. A wildcard path in the vault is checked by querying it; the vendor advises keeping such entries lower so there are fewer queries.

Two limitations of the wildcard path. It does not catch subdomains, and the selector and domain in it are converted to lowercase — the vault is case-sensitive, and the path in it must be created in lowercase.

The order of declarations follows the manual’s recommendations; the rotation rule is ours. From the manual here are the line’s composition, the first-match rule, the priority of stream keys and both limitations of the wildcard path.
Example configuration
# exact domains higher, the asterisk last
domain-key m, mail.port25.com, /etc/pmta/m.pem
domain-key k1, example.org, /etc/pmta/k1.example.org.pemdomain-key base, *, /etc/pmta/base.pem
The first two lines are from the manual, with paths adapted to our platform. The order here is the setting itself: the first matching declaration wins.
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 ends3 mistakes▶

Placing the asterisk above the exact declarations

§ 3.3.1.55.1

What it costsIt fits any message and intercepts everything: the exact keys below never run even once. All mail is signed with one key, and this is noticeable only in the signature header.
How to spot itAll messages have the same selector in the signature.
How to do it rightMove the asterisk declaration to the end of the list.

Replacing the file under the same selector

our experience

What it costsMessages sitting in the queue are signed with the old key. A new public part under the same name breaks their verification at the receiver — retroactively, after they have already been sent.
How to spot itSignature verification failures in reports right after rotation.
How to do it rightRotation means a new selector, waiting for the queues to drain and only then removing the old record.

Relying on a wildcard vault path for subdomains

§ 3.3.1.55.1

What it costsSuch a path does not catch subdomains — the manual says so separately. Messages from subdomains are left without a key, even though one is found for the parent domain.
How to spot itMessages from the main domain are signed, those from subdomains are not.
How to do it rightCreate separate declarations for subdomains or use a regular file path.
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 SELECTOR, { DOMAIN | * }, { FILENAME | {vault}:PATH:KEY }
domain-key {selector}, {domain}, {vault}:/path/with/${selector}/and/${domain}
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
Global, <virtual-mta>
How many times
may be repeated
Everything here comes from the manual, with the section.
Inheritance
A node-level line: written at the root of the file, it applies to all mail. Declarations inside <virtual-mta> take priority over general ones: when both levels match, the stream’s keys win. The same declaration can be gathered into a named list — a <domain-key-list> block — and chosen by a message header. It is picked up by pmta reload.
⇄

Related directives

4 relations

Works together with

domain-macroGlobalOne declaration can cover many domains — through a macro. § 3.3.1.55.1

Can be replaced by

An external secrets vaultThe key may be stored not on disk but in a secrets vault. Then a reference is written instead of a path, including one with selector and domain substitution. § 3.3.1.55.1

Applies to

Change a signing key without interrupting sendingThe line that the key rotation procedure adds and removes. § 1.6.2How the node signs messages and chooses a keyThe key selection rule in full — together with stream priority and the behavior when nothing matches. § 3.3.1.55.1

Referenced from

Headers the sender uses to control deliveryA header with a signing key replaces the declared keys for one message. § 3.3.7.46process-x-dkim-options<source>The header chooses among the keys declared with this directive and cannot name a key that does not exist. § 3.3.7.45dkim-sign<domain>Keys must be configured, otherwise enabling signing achieves nothing — the manual says so plainly. § 3.3.10.18dkim-identity<domain>The declaration’s domain is the signing domain; the signing identity must match it or be its subdomain. § 3.3.10.27arc-sign<domain>Keys must be configured, otherwise enabling it achieves nothing. § 3.3.10.30domain-key<virtual-mta>The full definition of the line — composition, selection rule, working with a secrets vault. § 3.3.1.55.1

How to check on the node
Whether the public part is published is checked with a DNS query; which key a message got — by the signature header:
dig +short TXT k1._domainkey.example.org
grep -i 'DKIM-Signature' /var/log/pmta/pmta.log | tail -5
In the signature header the selector is in the s= field and the domain in d=: that is how you check whether the right declaration won. The Hub arranges the order of declarations itself.
◇

What else to read

3 articles

◇How the node signs messages and chooses a keyThe key is chosen by the sending domain from the headers, going through the declarations from top to bottom.◇Headers the sender uses to control deliverySix control headers let the submitting side choose a stream, tag a message with a job, set signing options and the key, the envelope identifier and the schedule; each is allowed separately and per source.◇Backoff mode — the queue's second personalityA queue that a receiver has started refusing switches to a parallel set of limits, retries and routes — ten directives that act only in this mode.

In the Hub
Managed at
DNS → Signing keys
Cost of a mistake
dangerous: effects outlast a rollback
Scenarios
Sending address rotation · Key rotation · Message signing and authentication
Priority
critical
Neighboring settings of the block Global:http-accesshost-namesmtp-source-hostpostmastersmtp-proxy-source-hostAll 108 directives of the block →