Demo
Demo

Knowledge base

PMTA knowledge base›Procedure§ 1.6.2

Change a signing key without interrupting sending

Rotating cryptographic keys
Both keys live side by side until the queue empties

The order of actions matters more than the actions themselves. It exists in this form because settings are applied without stopping the node: both keys can sit in the configuration at the same time, and the transition costs nothing.

The new key is added and enabled before the old one is touched. Not the other way around. First it appears in the configuration under a different selector, the settings are applied, and signing switches to it.

Removal waits for the queue. The old key is removed only when no queued message relies on it anymore. The manual gives an example: a message that chose a key with its header — you have to wait until such messages are delivered or bounced.

The same order works for other cryptographic material too. The manual names the TLS certificate: the form of the procedure is the same — add, switch, wait, remove.

The main trap is not in the configuration but in DNS. The public part of the new key is published as a record that has a cache lifetime. A receiver that queried the record before publication will keep using the old answer until that time expires — and the new key’s signature will not verify for it. The error looks like “bad signature,” but it is really the cache. The record has to be published in advance, not on the same day as the switch.
What the Hub does. It follows exactly this order. Rotation in the DNS module creates a key under a new selector, while the previous one stays published until its record’s lifetime expires. Revoking the old one is a separate action, not part of creation.

The Hub puts the private parts on the node itself, into a locked-down directory (/etc/pmta/dkim, permissions 700, keys 600), and edits the signing line in the sending address block.

⚠️ A “bad signature” error right after rotation is almost always the DNS cache, not a defect. This has happened before: check the record’s lifetime instead of looking for a signature malfunction.

Recommended values

Order and timing:

Step When
publish the public part in DNS in advance, one record lifetime before the switch
add the key to the configuration under a new selector after publication
apply the settings with a reload, not a restart
switch signing to the new key right after applying
remove the old key when the queue holds no messages depending on it

The selector must be different. Two keys under one selector are not rotation but replacement: the old signature will stop verifying instantly.

How to tell the wait is over. There should be no messages in the queue that chose the old key with a header; the simplest is to wait until this domain’s queue empties or the messages bounce on expiry.

The publication timing and the advice about the cache are ours — from our own rotation experience. From the manual here come the order of steps itself, the requirement of a different selector, waiting for messages to leave and the note that the same form works for a TLS certificate.
Example configuration
# both keys sit side by side until the queue empties
<virtual-mta mta-news-1>
    domain-key sel2,example.com,/etc/pmta/dkim/private_key_example.com.txt    domain-key sel1,example.com,/etc/pmta/dkim/private_key_old.txt
</virtual-mta>
The highlighted line is the new key, added first. The bottom one is removed later, when no messages depending on it remain in the queue.
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▶

Removing the old key right after the switch

§ 1.6.2

What it costsMessages already queued that chose the old key will be left unsigned or get a wrong signature. They may bounce a day later, and linking that to the rotation will be hard by then.
How to spot itAfter rotation some messages arrive with an unverifiable signature, and all of them are older than the switch moment.
How to do it rightKeep both keys until the queue empties. Remove the old one as a separate step, not in the same edit.

Publishing the DNS record on the day of the switch

§ 1.6.2

What it costsThe record has a cache lifetime. A receiver that queried it earlier will keep using the old answer — and the new key’s signature will not verify for it. It looks like a signature malfunction and is cured by waiting.
How to spot itRight after rotation some receivers report a bad signature, others do not.
How to do it rightPublish the public part in advance, one record lifetime before the switch. When complaints come in, check the cache first, not the signature.

Keeping the same selector

§ 1.6.2

What it costsTwo keys under one selector are not rotation but replacement: the old signature stops verifying instantly, and all queued messages end up with an unverifiable signature at once.
How to spot itSignature verification fails immediately at all receivers.
How to do it rightChange the selector together with the key. It is precisely different selectors that let two keys live side by 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.
⇄

Related entries

4 relations

Does not work without

domain-keyGlobalThe line that attaches the key; during rotation there are temporarily two of them. § 1.6.2Apply a changed configuration without stoppingOne and the same command applies both adding the new key and removing the old one. § 1.6.2

Depends on

How to enable DKIM signing from scratchThe initial signing setup: rotation repeats its order, but with two keys at once. § 10.3.2

Affects

The node's main configuration fileBoth edits — adding and removing the key — are made in the main file or in an included one. § 1.6.2

Referenced from

smtp-server-tls-certificateGlobalA neighboring task with the same rhythm: the validity period runs out, and the replacement has to be prepared in advance. § 1.6.2http-api-keyGlobalChanging the key works the same way as changing a signing key: the new one is written, and the old one stops working on apply. inferenceFlush the name cacheThe procedure in which this command is one of the steps. inferenceHow the node signs messages and chooses a keyChanging a key means a new selector, which is why the selector is a separate value in the declaration. § 10.3.2

How to check on the node
Check both the signature and whether the record has propagated through caches:
dig +short sel2._domainkey.example.com TXT
pmta show queues '*/mta-news-1'
The first shows whether the public part of the new selector is published. The second shows whether the sending address that signs with this domain still has messages: the old key is removed after its queues have emptied.
◇

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.◇Do not send what will fail the check at the receiverThe node checks the SPF of its own mail before sending: if it fails, it bounces the message without waiting for someone else’s refusal.◇A message header with which the submitting side adjusts the signatureFive parameters in X-DKIM-Options: selector, domain, signing identity, query method and key list.

In the Hub
Cost of a mistake
dangerous: effects outlast a rollback
Scenarios
Key rotation · Message signing and authentication