Demo
Demo

Knowledge base

PMTA knowledge base›Block <domain>›Directive§ 3.3.10.18

dkim-sign

<domain>criticalset by the Hub

Whether to sign messages to this receiver
in the configuration this is a linedkim-sign falseinside the block <domain>
Signing is switched on per receiver, the key is chosen per message

This line decides whether messages going to this receiver are signed. It does not name the key: the key is chosen by the sending domain from the message headers, among the domain-key declarations.

Without keys the line does nothing. The manual says it plainly: keys must be configured for enabling to take effect. There is no error and no warning when they are missing — the message simply leaves unsigned.

A third value besides yes and no. if-x-dkim-options-present enables signing only for messages that carry the X-DKIM-Options header. This is how you sign selectively — by decision of the submitting side rather than by receiver.

The main trap is that enabling without a key passes silently. The line is applied, the settings output shows yes, and messages leave unsigned because no matching domain-key declaration was found. The only way to notice is to look at the headers of a sent message or at receiver reports.
What the Hub does. It writes it: signing is enabled for all receivers, and the keys are kept on the domain card in “DNS → Domains and zones” and deployed to the nodes. Selective signing by the X-DKIM-Options header is not used — all mail is signed.
Recommended values

Enable it for all receivers. An unsigned message looks suspicious to any large receiving server today; selective signing makes no sense.

Key first, then enabling. The order matters: messages signed with a key that is not in DNS are worse than unsigned ones.

The third value is for someone else’s submission. It hands the signing decision to the submitting application; in your own mailing it is just one more way to make a mistake.

The advice to enable it for all receivers and the “key first” order are ours. From the manual here are the default, all three values and the requirement for configured keys.
Example configuration
# the key is declared and the DNS record is published — only now do we enable signing
domain-key k1, example.org, /etc/pmta/k1.example.org.pem

<domain *>
    dkim-sign yes</domain>
The order of lines in the file does not matter, but the order of actions does: the DNS record must propagate before signing is enabled.
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 without declaring a key

§ 3.3.10.18

What it costsThe line applies without an error, and messages leave unsigned. You cannot notice it from the configuration — only from message headers or receiver reports.
How to spot itThe settings show dkim-sign yes, but the messages carry no signature header.
How to do it rightDeclare domain-key for the sending domain and check that it was picked up.

Enabling signing before the DNS record is published

our experience

What it costsThe receiver sees the signature but cannot verify it: the public part is not in DNS yet. The verification result is a permanent error, and that is worse than an unsigned message.
How to spot itReceiver reports mark the signature as failed.
How to do it rightPublish the record and wait for it to propagate before enabling.

Enabling it selectively, by header

our experience

What it costsSome messages leave unsigned. Receiving servers see two different behaviors from one sender, and that alone is a reason to treat it more warily.
How to spot itThe share of signed messages is below one.
How to do it rightSign everything; selective signing is justified only for someone else’s submission with its own keys.
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
dkim-sign <enumeration>
Values
yes, no or if-x-dkim-options-present — sign only messages with the X-DKIM-Options header
Default
false § 3.3.10.18
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<domain>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The value merges across <domain> blocks from general to specific: the best-matching block wins, not the last one in the file. A <domain> block can be nested inside <virtual-mta> — then signing is enabled only for that stream. It is picked up by pmta reload; for messages already in the queue it takes effect from the next attempt — the signature is applied at sending, not at submission.
⇄

Related directives

3 relations

Does not work without

domain-keyGlobalKeys must be configured, otherwise enabling signing achieves nothing — the manual says so plainly. § 3.3.10.18

Works together with

process-x-dkim-options<source>The third value hands the signing decision to a message header, and processing that header is enabled by this line on the source. § 3.3.7.45

Affects

dkim-identity<domain>Decides on whose behalf the signature is made — and the key is chosen by that same name. § 3.3.10.27

Referenced from

dkim-add-body-limit<domain>Does nothing until signing is enabled. § 3.3.10.19dkim-add-timestamp<domain>Does nothing until signing is enabled. § 3.3.10.20dkim-algorithm<domain>Does nothing until signing is enabled. § 3.3.10.21dkim-body-canon<domain>Does nothing until signing is enabled. § 3.3.10.22dkim-headers-canon<domain>Does nothing until signing is enabled. § 3.3.10.23dkim-expire-after<domain>Does nothing until signing is enabled. § 3.3.10.24

How to check on the node
The queue settings command prints the effective value; whether a message was actually signed shows in the header in the log:
pmta show settings gmail.com/vmta1 | grep -i dkim-sign
grep -i 'DKIM-Signature' /var/log/pmta/pmta.log | tail -5
A value of yes with an empty second output means the key was not picked up: signing is enabled, but there is no declaration for the sending domain. The Hub enables signing for all receivers.
◇

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
Managed at
DNS → Signing keys
Value
The Hub picks it itself — pace, warm-up stage, metrics
Cost of a mistake
reversible: harms only while it is set
Scenarios
Key rotation · Message signing and authentication
Priority
critical
Neighboring settings of the block <domain>:dkim-identitycheck-spf-outboundarc-signdkim-disallow-adding-headersdkim-add-body-limitAll 135 directives of the block →