Demo
Demo

Knowledge base

PMTA knowledge base›Procedure§ 10.3.2

How to enable DKIM signing from scratch

critical

Setting up DKIM signing
Eight steps from an empty configuration to a signed message

DKIM signing works like this: you have a key pair, the public part is in DNS, the private part is on the node, and the node adds a signature header to the message. The receiver takes the public part from DNS and verifies.

Hence the order of steps. It is not arbitrary: the DNS record is published before signing is enabled. Otherwise messages go out with a signature there is nothing to verify against — and that is worse than messages with no signature at all.

The eight steps below come from the manual. The last one is not needed by everyone: it covers the case where the key is declared inside a sending stream rather than at the node level.

The main trap is the order of the fifth and seventh steps. Enabling signing before the record has propagated through DNS means sending messages for a while with a signature the receiver cannot verify. A failed verification is worse than none: a signature without a key in DNS results in permerror, and receiving servers treat that more strictly than an unsigned message.
What the Hub does. It does everything except the final verification step: it generates the pair, publishes the record through its DNS module and distributes the declarations across the nodes. Waiting for the record to propagate through caches and making sure the signature verifies is still a human’s job.
Example configuration
# 3. generation: produces two files — .pem and .dns
pmtakeytool newdk k1 example.org 2048

# 4. permissions: only the node may read it
install -o pmta -g pmta -m 600 k1.example.org.pem /etc/pmta/

# 6. declaring the key and 7. enabling signing
domain-key k1, example.org, /etc/pmta/k1.example.org.pem
<domain *>
    dkim-sign yes</domain>
Between the sixth and seventh lines the fifth step must fit in — publishing the DNS record and waiting for it to propagate.
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▶

Enabling signing before the record is published

our experience

What it costsMessages go out with a signature the receiver cannot verify. The verification result is a permanent error, and receiving servers treat such a message more strictly than an unsigned one.
How to spot itReceiver reports mark the signature as an error rather than as absent.
How to do it rightPublish the record and wait for it to propagate through caches before enabling signing.

Declaring a key inside a stream without routing mail into it

§ 10.3.2

What it costsThe key exists, signing is on, but messages leave through another stream that has no key. The node simply does not sign them — silently, with no error in the log.
How to spot itSigning is on, but messages have no header.
How to do it rightEither declare the key at the node level or route mail from this domain into the right stream.

Leaving the private key readable

our experience

What it costsAny user on the node can read the signing key. Having taken it, one can sign messages in your name, and receivers will trust them — the signature will be valid.
How to spot itThe permissions on the .pem file are wider than the service user’s.
How to do it rightOwner — the service user, permissions 600.
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

3 relations

Depends on

Six ways to choose a stream and the order among themA key inside a stream signs only the mail that actually got into that stream. § 10.3.2

Works together with

Change a signing key without interrupting sendingChanging a key is the same procedure under a new selector, with the old key kept until the queues drain. inference

Where you can see it

How the node signs messages and chooses a keyThe mechanism this procedure configures. § 10.3.2

How to check on the node
That the record is actually published is checked before enabling signing; that signing works — by the header in a sent message:
dig +short TXT k1._domainkey.example.org
pmta show settings example.com/vmta1 | grep -i dkim-sign
An empty answer from the first command means it is too early to enable signing: the record is not yet visible from outside. The Hub publishes records itself, but you still have to wait for caches to catch up.
◇

What else to read

3 articles

◇The activation key is a prerequisite for installation, not a step after itWithout an activation key from SparkPost support the engine neither installs nor runs, and the license tier sets the outbound connection ceiling: on Standard everything above 200 is ignored.◇Cloud restrictionsClouds restrict outbound mail on port 25 until you ask them to lift the limit, and mailbox providers treat their address ranges with suspicion.◇How to turn a sending plan into hardwareTwo constants for sizing any node: about 2 KB of memory per queued recipient and spool space proportional to the total size of the messages.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Message signing and authentication · Prepare a node for sending
Priority
critical