Demo
Demo

Knowledge base

PMTA knowledge base›Block <source>›Directive§ 3.3.7.47

retain-x-dkim-key

<source>critical

Whether to keep the private signing key in the sent message
in the configuration this is a lineretain-x-dkim-key falseinside the block <source>
A line that is not enabled

The default is false. The point of the directive is to keep the X-DKIM-Key header in the message when sending to an outside server, that is, to send the private signing key to the recipient.

The manual accompanies it with a warning set in bold: with true the private key ends up in the delivered message, this is a security risk, and keeping false is strongly recommended. No other source block directive carries such a warning.

Formally the directive is independent of the permission to read the header — the manual stresses this separately. In practice this independence gives nothing useful here: the combinations where true would be appropriate have no use.

The main trap is not the line itself but the fact that people forget about it. It gets enabled for the duration of an investigation, to see which key a message arrived with — and left on. From then on every message from this source carries the private key to the recipient.

This cannot be undone: a key that left in a delivered message counts as compromised, and the only cure is rotation — with the accompanying delay in the receiving servers’ DNS caches.

What the Hub does. It does not write it: the Hub does not use the mechanism of passing a key in a message at all, so there is nothing to strip. The Hub distributes keys across nodes itself and names them in the stream configuration.
Recommended values

What to set. There is essentially no choice here:

Value When
no (default) always
yes there is no such case

If you need to see the key a message arrived with, look at it on the submitting side — where the message was assembled — rather than letting it out to the recipient.

The false default, the risk warning and the recommendation to keep false come from the manual, § 3.3.7.47. The assessment “there is no case for yes” is ours.
Example configuration
# the default value, and there is no reason to change it
<source 0/0>
    retain-x-dkim-key false</source>
The line is written for explicitness: it repeats the default. There is only one reason to keep it in the configuration — so that during the next review nobody enables the opposite without noticing.
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▶

Enabling it temporarily and leaving it on

§ 3.3.7.47

What it costsEvery message from this source carries the private key away to the recipient. After that the key is compromised, and there is no getting it back — only issuing a new one and replacing the DNS record.
How to spot itA message with X-DKIM-Key is visible in the seed mailbox.
How to do it rightRemove the line, issue a new key, change the selector in DNS and wait for the receiving servers’ cache of the old record to expire.

Relying on the directives being independent

§ 3.3.7.47

What it costsThe manual does call processing and retention independent, but that is useful only for the neighboring headers. Here any combination with true means a key in the delivered message.
How to spot itThe configuration has true, on the assumption that the other directive will balance it out.
How to do it rightKeep false regardless of what the other line says.
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
retain-x-dkim-key <boolean>
Values
yes | no | true | false
Default
false § 3.3.7.47
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<source>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The directive lives in <source> and obeys source merging: a connection falls under all the address blocks that cover it, and the narrow one overrides the wide one. Here merging is useful too: false in the 0/0 block goes to all blocks that have not said otherwise themselves.
⇄

Related directives

2 relations

Works together with

process-x-dkim-key<source>The first half of the pair: that one decides whether to read the key, this one whether to keep it in the message. § 3.3.7.47

Applies to

Headers the sender uses to control deliveryThe “keep or strip” half of the most dangerous of the six control headers. § 3.3.7.47

Referenced from

retain-x-dkim-options<source>The same setting for the neighboring header, only the price of a mistake there is incomparably higher: the private key stays in the message. § 3.3.7.60

How to check on the node
It is worth checking not only the setting but also what actually arrived:
grep -rn 'retain-x-dkim-key' /etc/pmta/
Empty output means the vendor default — and it is correct. A line found with the value true requires an immediate investigation: the keys that signed already sent messages will have to be considered compromised.
◇

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
dangerous: effects outlast a rollback
Scenarios
Node security
Priority
critical
Neighboring settings of the block <source>:process-x-dkim-keysmtp-servicesmtp-max-auth-failure-rateallowed-sender-listsallow-unencrypted-plain-authAll 74 directives of the block →