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:
nextMade ahead of a rotation; signs nothing. Its records have to be published before it may take over.
currentSigns. A domain has exactly one current generation.
retiringReplaced 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.retiredThe 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.serviceruns it aspepsi-dkim; started asroot, 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
nextgeneration for each DOMAIN (every served domain when none is named) and switch to it: as soon as its records are visible (withWAIT_FOR_DNS), or at once with –hard or withoutWAIT_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. Needsrootor thepepsi-dkimaccount. 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 whilepepsi-setup runhas 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-SignatureorARC-Seal), ad=,s=ora=that differs from the request, a non-emptyb=, a duplicated tag, or more than 512 fields (policy:...,malformed);for DKIM: an
h=that does not namefrom, noFrom:field, or aFrom:field with a mailbox whose domain is not aligned withd=(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]SOCKETThe signing socket (default
/run/pepsi-dkim/sign.sock). The stages read the same option to find it.STATE_DIRThe private keys and the private state (default
/var/lib/pepsi-dkim).PUBLIC_DIRThe status document and the published retired keys (default
/var/lib/pepsi-dkim-public).RSA_BITSThe 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_DAYSHow long a generation signs before the next takes over (default 0: never by itself).
ROTATION_LEAD_DAYSHow long before the switch the
nextgeneration is made, so its records can be published (default 28; must be shorter thanROTATION_DAYS).RETIRE_AFTER_DAYSHow long the records of a retiring generation stay before its keys are retired (default 14, at least 1). It must exceed the
SIGNATURE_EXPIRATION_DAYSof every pepsi-stage-dkim-sign and pepsi-stage-arc stage, which pepsi-setup validate checks.WAIT_FOR_DNSWhether a scheduled or soft switch waits until every authoritative server serves the
nextgeneration’s records (defaultyes).DNS_CHECK_INTERVALHow often each record is looked up (default
1 h, at least1 min).DNS_UPDATEnone(default: the operator publishes) orrfc2136.DNS_UPDATE_SERVERWith
rfc2136: the server that the updates go to, as a host name or address with an optional port (default: the zone’s SOAMNAME).DNS_UPDATE_TTLThe TTL of the records added (default 3600 seconds).
TSIG_KEY_NAMEWith
rfc2136: the TSIG key’s name (required).TSIG_ALGORITHMhmac-sha256(default),hmac-sha384orhmac-sha512.TSIG_SECRETWith
rfc2136: the TSIG key, base64 (required). A secret: pepsi-setup keeps it insecrets.d/pepsi-dkim.secret, readable bypepsi-dkimalone. Whoever has it can change whatever the key may update in the zone, so grant the key updates of_domainkeynames only.PUBLISH_RETIRED_KEYSPublish 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 whenROTATION_DAYSis 0 or no listener serves HTTPS to the public.NOTIFYMail the postmaster about DNS changes owed (default
yes).NOTIFY_ADDRESSWhere 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,debugortrace(default:[pepsi] LOG, elseinfo).
95.1.9.1.8. Files¶
/var/lib/pepsi-dkim/keys/<domain>/<selector>.keyThe 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,lockThe lifecycle state (0600), the served domains and the lock held by whoever changes them.
/var/lib/pepsi-dkim-public/status.jsonThe public status document (0644).
/var/lib/pepsi-dkim-public/retired/<domain>/<selector>.pemRetired 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.sockThe signing socket (0660, group
pepsi; the directory is the daemon’s, 0711)./etc/pepsi/secrets.d/pepsi-dkim.secretTSIG_SECRET, readable bypepsi-dkimalone.
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)