Demo
Demo

Knowledge base

PMTA knowledge base›Mechanism§ 10.3.3

A message header with which the submitting side adjusts the signature

X-DKIM-Options header
A signing decision made by the submitter

Normally the node’s configuration decides everything about signing. This mechanism hands some decisions over to the message: the submitting side sets the X-DKIM-Options header, and it overrides the settings for that one message.

There are five parameters, separated by semicolons, like the tags in the signature itself: s — the selector, d — the domain, i — the signing identity, q — the key query method, key-list — the name of the list to take the key from.

The override is not unlimited. The header chooses among the declared keys rather than bringing its own: the specified selector or domain must exist in the configuration, otherwise the message is not signed. And the mechanism itself works only if processing of this header is enabled on the source.

The main trap is that the header comes from outside. By enabling its processing you let the submitting side choose which key to sign a message with. If the submission source is open wider than it should be, this is a way to sign someone else’s message with any of your keys — the very one recipients trust.
What the Hub does. It does not use it: its signature is determined by the sending stream, not by a message header. The mechanism will be useful if mail from several clients goes through one node and the submitting side chooses the key.
Example configuration
# two keys for one domain — the message chooses the second
domain-key key1, example.com, /etc/pmta/key1.example.com.pem
domain-key key2, example.com, /etc/pmta/key2.example.com.pem

# and in the message itself:
X-DKIM-Options: s=key2
The choice is made among the declared keys: the header will not create a selector that is not in the configuration — the message will simply stay unsigned.
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 processing on a broad source

our experience

What it costsThe submitting side gets the right to choose the signing key. On a source open wider than needed, this is a way to sign someone else’s message with a key your recipients trust.
How to spot itProcessing is enabled in a source block covering the whole network.
How to do it rightEnable it only for sources you trust as much as yourself.

Expecting the header to bring its own key

§ 10.3.3

What it costsIt only chooses among the declared ones. A selector or domain that is not in the configuration leads to the message going out unsigned.
How to spot itMessages with the header are unsigned, the rest are signed.
How to do it rightDeclare the needed key in the configuration or in the list named by the key-list parameter.
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

2 relations

Does not work without

process-x-dkim-options<source>The line on the source without which the header is not processed at all. § 10.3.3

Overrides

How the node signs messages and chooses a keyOverrides the automatic key choice — but within the keys already declared. § 10.3.3

Referenced from

A signing key that came along with the messageA neighboring mechanism: that one chooses a key among the declared ones, this one brings the key right in the message. § 10.3.5

How to check on the node
Whether header processing is enabled is set on the source; the result is visible from the selector in the signature itself:
grep -n process-x-dkim-options /etc/pmta/config
grep -i 'DKIM-Signature' /var/log/pmta/pmta.log | tail -3
The s= field in the signature shows the selected selector: that is how you see whether the message header took effect. The Hub does not use this mechanism.
◇

What else to read

3 articles

◇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.◇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.◇A second signature on the same messageTwelve lines with the second- prefix: the message is signed twice, with different keys and under different identities.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Message signing and authentication