DKIM explained: selectors, keys and rotation

DomainKeys Identified Mail (DKIM) lets a signing domain attach a cryptographic signature to a message. The receiver fetches the public key from DNS and verifies it. The protocol is defined in RFC 6376, and later updated by RFC 8301 and RFC 8463.

Signature and selector

A signing server adds a DKIM-Signature header. The tags that matter when you look for the key are:

• d= is the signing domain.
• s= is the selector, a label that names one key of that domain.
• h= lists the header fields that are covered, and bh= and b= hold the body hash and the signature.

The public key is a TXT record at <selector>._domainkey.<d>. A domain can have many selectors at the same time, for example one per mail provider, or one per rotation period. DKIM authenticates the signing domain d=. It says nothing about the From address unless DMARC requires the two to align; see DMARC explained.

The key record

The record is a list of tag=value pairs separated by semicolons.

Tag	Meaning
v	Version. If present it must be DKIM1 and come first.
k	Key type. The default is rsa. RFC 8463 adds ed25519.
p	The public key, base64-encoded. Required. An empty value means the key is revoked.
t	Flags. y means the domain is testing DKIM. s means the i= identity of a signature must not be a subdomain of d=.
h, s, n	Optional restrictions on hash algorithms and service types, and a human-readable note.

If a selector has no record the signature cannot be verified (DKIM_NOT_FOUND). More than one record for the selector is an error (DKIM_MULTIPLE_RECORDS). A record with unparsable tags or bad values is reported as DKIM_SYNTAX_ERROR, and a p value that is not valid base64 as DKIM_INVALID_KEY.

Key size and algorithms

RFC 6376 section 3.3.3 required at least 1024 bits only for long-lived keys, and verifiers had to accept keys from 512 bits. RFC 8301 made 1024 bits the minimum for all signing keys, forbids verifiers to accept signatures from shorter keys, and says signers should use at least 2048 bits. RFC 8301 also removed rsa-sha1 as a signing algorithm; rsa-sha256 is what remains for RSA.

The DKIM check reads the key length from the record and reports RSA keys shorter than 1024 bits as DKIM_WEAK_KEY. It does not report 1024-bit keys, although 2048 bits is the recommended size. Many DNS providers need the key split into several quoted strings because a single TXT string is limited to 255 bytes; the check works on the joined value.

RFC 8463 defines the ed25519-sha256 algorithm. Its key is the raw 32-byte public key in base64 in p, with k=ed25519. Ed25519 keys are much shorter than RSA keys, but not every verifier supports them, so such signatures are normally added next to an RSA signature rather than instead of it.

Testing mode

t=y tells verifiers the domain is still testing DKIM. RFC 6376 says verifiers must not treat messages from a signer in testing mode differently from unsigned mail. It is meant for the first days of a rollout, and it should be removed afterwards. The check reports it as DKIM_TESTING_MODE.

Rotation and revocation

Rotate keys on a schedule and whenever a private key may have leaked:

1. Generate a new key pair and publish the public key under a new selector.
2. Switch the signer to the new selector.
3. Keep the old record for some time, since messages in transit are verified after delivery.
4. Retire the old selector. To say explicitly that it must not be used, publish the record with an empty p=; or delete the record.

An empty p= is a deliberate revocation (DKIM_KEY_REVOKED). It is reported as a warning because it is only a problem if the selector is still in use.

What the check covers

The DKIM check fetches the key record for one domain and one selector that you supply, and analyses the record. It does not verify a signature, because that needs the message itself. It also cannot discover which selectors a domain uses. The mail check accepts up to five selectors in addition to SPF, DMARC and MX.