95.1.9. pepsi-dkim

hold the DKIM and ARC signing keys and sign

Manual section:

1

95.1.9.1.1. Name

pepsi-dkim - the signing daemon that holds the DKIM and ARC private keys, rotates them and reports the DNS records that they need.

95.1.9.1.2. Synopsis

pepsi-dkim [GLOBAL-OPTIONS] serve

pepsi-dkim [GLOBAL-OPTIONS] status [–json]

pepsi-dkim [GLOBAL-OPTIONS] records [DOMAIN]

pepsi-dkim [GLOBAL-OPTIONS] rotate [–hard] [DOMAIN…]

pepsi-dkim [GLOBAL-OPTIONS] sync-domains DOMAIN…

95.1.9.1.3. Description

pepsi-dkim keeps the private keys that pepsi-stage-dkim-sign(1) and pepsi-stage-arc(1) use for signing. It runs as its own account, pepsi-dkim, and keeps the keys in its state directory (STATE_DIR, default /var/lib/pepsi-dkim, mode 0700), where each key is a file of mode 0600. No stage worker can read a key. The stages hash the body and build the signature field themselves. They then send the canonicalised header block to the daemon over a UNIX socket (SOCKET, default /run/pepsi-dkim/sign.sock, mode 0660, group pepsi), and the daemon signs it and returns the signature value. When the daemon cannot be reached, the stages retry the message later; they never send it unsigned.

This protects the keys from disclosure. It does not restrict their use beyond the policy below: any process of group pepsi can ask the socket for a signature for a served domain, and any pipeline stage can rewrite a queued From: and have pepsi-stage-dkim-sign sign the result. A compromised stage can therefore obtain signatures while it runs, but cannot take a key away with it.

95.1.9.1.3.1. Keys and selectors

Every signing domain has keys for the algorithms that [pepsi] DKIM_ALGORITHMS names (RSA, Ed25519 or both); the [pepsi] ARC_DOMAIN also gets a key of [pepsi] ARC_ALGORITHM. RSA keys have RSA_BITS bits and are generated by AWS-LC. Keys that are made together form a generation; its selectors are <DKIM_SELECTOR>-YYYYMM for RSA and <DKIM_SELECTOR>-YYYYMM-ed25519 for Ed25519 ([pepsi] DKIM_SELECTOR, default pepsi, and the month the generation was made, in UTC). A second generation in the same month gets a letter after the date: pepsi-202610b. Every key thus has a record name of its own, <selector>._domainkey.<domain>.

95.1.9.1.3.2. Lifecycle

A generation moves through four states:

next

Made ahead of a rotation; signs nothing. Its records have to be published before it may take over.

current

Signs. A domain has exactly one current generation.

retiring

Replaced by a newer generation; signs nothing, but its records stay in DNS for RETIRE_AFTER_DAYS, so the signatures it made in the days before the switch still verify.

retired

The private keys are deleted (or, with PUBLISH_RETIRED_KEYS, published once DNS no longer serves their records) and the records may be removed. The generation stays on record for 90 days, then is dropped.

A served domain without a current generation (a fresh installation, a domain added to the configuration, a state directory lost or not restored) gets one at once, and it signs at once: until its records are published, receivers cannot verify its signatures. Every interface described below reports the records that are still owed.

Rotation is off unless ROTATION_DAYS is set. With it, a next generation is made ROTATION_LEAD_DAYS before the switch is due. With WAIT_FOR_DNS (the default) the switch waits until every authoritative server of the zone serves every record of the next generation; the current keys go on signing meanwhile, and the delay is reported. rotate asks for a switch now, and rotate –hard switches without looking at DNS. For ten minutes after a switch, the selector that was current until then still signs, for the messages in flight; a stage that asks for an older selector is told to ask for the current one.

When a domain is removed from the configuration, its current generation is retired in the same way, and a next generation of it, which never signed, is retired at once.

95.1.9.1.3.3. DNS

Every DNS_CHECK_INTERVAL the daemon asks every authoritative server of the zone for the record of each key that has to be in DNS, and classifies it as visible (every server serves it with the key), missing (none does), disagree (some do, some do not: a secondary that has not caught up) or unknown (no answer could be established).

By default the operator publishes the records. With DNS_UPDATE = rfc2136 the daemon adds the records of the next and current generations and removes those of retired ones itself, by RFC 2136 UPDATE signed with TSIG (RFC 8945), sent to DNS_UPDATE_SERVER or else to the zone’s primary (the SOA MNAME). A failure to reach the server is retried at the next tick; a refusal (a wrong key, a zone policy that forbids the name) is recorded on the key, not retried until the daemon restarts, and mailed to the postmaster.

With NOTIFY (the default), the daemon mails NOTIFY_ADDRESS (default postmaster@ the first served domain) when a record must be added, a record of a retired key may be removed, a rotation waits for its records, or a DNS update was refused. The notices go through the local submission socket. Each condition is mailed at most once a day while it lasts.

95.1.9.1.3.4. The status document

After every change, the daemon writes everything public about the keys to PUBLIC_DIR/status.json (world-readable): the selectors, the states, the TXT records, what the authoritative servers serve, the DNS changes owed and a rotation that waits for DNS. pepsi-status(1) (section “DKIM keys”), pepsi-setup(1) (run, check), GET /api/v1/keys/dkim and the console’s DKIM page read it; none of them reads a key.

95.1.9.1.4. Commands

serve

Run the daemon: bind the socket, advance the lifecycle once a minute, check DNS, write the status document and mail the postmaster. pepsi-dkim.service runs it as pepsi-dkim; started as root, it becomes that account itself.

status [–json]

Print every key with its algorithm, state, DNS verdict and date, a rotation that waits for DNS, and the DNS changes owed. –json prints the status document instead. The running daemon answers; when none does, the status file is read.

records [DOMAIN]

Print, as zone-file lines, every record that has to be in DNS (of one DOMAIN, or of all), and, as comments, the records of retired keys that may be removed.

rotate [–hard] [DOMAIN…]

Make a next generation for each DOMAIN (every served domain when none is named) and switch to it: as soon as its records are visible (with WAIT_FOR_DNS), or at once with –hard or without WAIT_FOR_DNS. Use –hard after a key may have been exposed; the records of the new generation have to be published at once, since DKIM fails at receivers until they are. Needs root or the pepsi-dkim account. The console’s rotate now asks the root applier (pepsi-setup apply) to run this.

sync-domains DOMAIN…

Record DOMAIN… as the set of signing domains, make keys for any of them that has none, retire the keys of any domain not named, and print the status document as JSON (nothing else) on standard output. pepsi-setup run calls it with every domain that the deployment signs for, and takes from the result the DKIM records that it prints for the zone.

rotate and sync-domains ask the running daemon. When none answers, they take the state directory’s lock and do the work on the files themselves, without DNS checks; run as root, they create the directories when absent and continue as pepsi-dkim.

95.1.9.1.5. Socket protocol and policy

One JSON object per line in each direction; a connection may carry many requests, and a request line is at most 256 KiB. The requests are selectors (the current selectors of a domain), sign, status, and the administrative reload and rotate, which the daemon takes only from root and its own account (checked with SO_PEERCRED). A sign request carries the exact bytes to sign: the canonicalised header fields that the signature covers, then the signature field with an empty b=. The daemon refuses:

  • a domain it does not serve (unserved-domain), or any domain while pepsi-setup run has not yet handed it a list of domains (not-configured, which the stages treat as temporary and retry);

  • a last field that is not the signature field of the request’s kind (DKIM-Signature, ARC-Message-Signature or ARC-Seal), a d=, s= or a= that differs from the request, a non-empty b=, a duplicated tag, or more than 512 fields (policy:..., malformed);

  • for DKIM: an h= that does not name from, no From: field, or a From: field with a mailbox whose domain is not aligned with d= (same organisational domain);

  • for ARC: a d= other than [pepsi] ARC_DOMAIN;

  • a selector that is not current, nor current within the last ten minutes (stale-selector).

With PUBLISH_RETIRED_KEYS, a retired key is published only once DNS no longer serves its record: until then it is kept, unpublished, because a published private key whose record still resolves would let anybody sign for the domain. If its record is still served when the generation is dropped (90 days after retirement), the key is deleted instead.

Every signature and every refusal is logged with the requesting process id.

95.1.9.1.6. Configuration

The daemon reads [pepsi-dkim], [pepsi] DKIM_SELECTOR, DKIM_ALGORITHMS, ARC_DOMAIN and ARC_ALGORITHM, and the [pepsi-sendmail] socket that its notices go through. pepsi-setup validate checks the section.

[pepsi-dkim]
SOCKET

The signing socket (default /run/pepsi-dkim/sign.sock). The stages read the same option to find it.

STATE_DIR

The private keys and the private state (default /var/lib/pepsi-dkim).

PUBLIC_DIR

The status document and the published retired keys (default /var/lib/pepsi-dkim-public).

RSA_BITS

The size of the RSA keys that the daemon makes: 2048, 3072 or 4096 (default 2048). Existing keys keep their size until the next rotation. Keys above 2048 bits need a TXT record split into several strings, which some DNS hosting panels mangle; pepsi-setup check reports a record that is served truncated.

ROTATION_DAYS

How long a generation signs before the next takes over (default 0: never by itself).

ROTATION_LEAD_DAYS

How long before the switch the next generation is made, so its records can be published (default 28; must be shorter than ROTATION_DAYS).

RETIRE_AFTER_DAYS

How long the records of a retiring generation stay before its keys are retired (default 14, at least 1). It must exceed the SIGNATURE_EXPIRATION_DAYS of every pepsi-stage-dkim-sign and pepsi-stage-arc stage, which pepsi-setup validate checks.

WAIT_FOR_DNS

Whether a scheduled or soft switch waits until every authoritative server serves the next generation’s records (default yes).

DNS_CHECK_INTERVAL

How often each record is looked up (default 1 h, at least 1 min).

DNS_UPDATE

none (default: the operator publishes) or rfc2136.

DNS_UPDATE_SERVER

With rfc2136: the server that the updates go to, as a host name or address with an optional port (default: the zone’s SOA MNAME).

DNS_UPDATE_TTL

The TTL of the records added (default 3600 seconds).

TSIG_KEY_NAME

With rfc2136: the TSIG key’s name (required).

TSIG_ALGORITHM

hmac-sha256 (default), hmac-sha384 or hmac-sha512.

TSIG_SECRET

With rfc2136: the TSIG key, base64 (required). A secret: pepsi-setup keeps it in secrets.d/pepsi-dkim.secret, readable by pepsi-dkim alone. Whoever has it can change whatever the key may update in the zone, so grant the key updates of _domainkey names only.

PUBLISH_RETIRED_KEYS

Publish a retired private key instead of deleting it, once DNS no longer serves its records (default no): once anybody can make a signature with it, an old signature no longer proves who made it. pepsi-httpd(1) serves the files. The option is meaningful with rotation; pepsi-setup validate warns when ROTATION_DAYS is 0 or no listener serves HTTPS to the public.

NOTIFY

Mail the postmaster about DNS changes owed (default yes).

NOTIFY_ADDRESS

Where the notices go (default postmaster@ the first served domain).

95.1.9.1.7. Global Options

-c FILE, –config FILE

Read the configuration from FILE instead of searching the default locations.

-L LOGLEVEL, –log LOGLEVEL

Set the logging verbosity. LOGLEVEL is one of error, warn, info, debug or trace (default: [pepsi] LOG, else info).

95.1.9.1.8. Files

/var/lib/pepsi-dkim/keys/<domain>/<selector>.key

The private keys: PKCS#8 PEM, mode 0600, owner pepsi-dkim, in 0700 directories. Do not back them up: after a restore without them the daemon makes fresh keys, which is a rotation whose records have to be published.

/var/lib/pepsi-dkim/state.json, domains, lock

The lifecycle state (0600), the served domains and the lock held by whoever changes them.

/var/lib/pepsi-dkim-public/status.json

The public status document (0644).

/var/lib/pepsi-dkim-public/retired/<domain>/<selector>.pem

Retired private keys, with PUBLISH_RETIRED_KEYS (0644); pepsi-httpd(1) serves them at /.well-known/pepsi-dkim-retired/<domain>/<selector>.pem.

/run/pepsi-dkim/sign.sock

The signing socket (0660, group pepsi; the directory is the daemon’s, 0711).

/etc/pepsi/secrets.d/pepsi-dkim.secret

TSIG_SECRET, readable by pepsi-dkim alone.

95.1.9.1.9. Exit Status

0 on success; 1 when the configuration cannot be read, the socket cannot be bound, the state directory cannot be used, or a command fails.

95.1.9.1.10. See Also

pepsi-stage-dkim-sign(1), pepsi-stage-arc(1), pepsi-setup(1), pepsi-status(1), pepsi-httpd(1), pepsi.conf(5)