README
¶
dkim2d
dkim2d is the local HTTP/JSON daemon around the standalone DKIM2 library.
The current API performs inbound verification, local policy evaluation, replay
coordination, and disposition projection, and also performs datasource-backed
originator signing and ordinary-transit revision.
The daemon is a thin adapter. Raw RFC 5322/RFC 6532 message bytes, SMTP
envelope evidence, DKIM2 verification, policy, and replay semantics remain
owned by github.com/croessner/dkim2. The authoritative REST contract is
docs/specs/openapi/dkim2d.yaml.
The production navigation and container trust topology start in
docs/operator/postfix-compose.md.
A conceptual, example-driven introduction to the daemon is
How dkim2d works.
LDAP/PostgreSQL/MySQL/MariaDB installation and migration are documented in
docs/operator/datasource-backends.md
and
docs/operator/opendkim-migration.md.
HTTP Security Boundary
Run one daemon instance under a dedicated, unprivileged service UID. The effective UID, local root, and the kernel are trusted. Other local UIDs and processes that can merely reach localhost are not trusted.
The default server.listener_mode: loopback accepts exactly one canonical
loopback IP literal and nonzero port. The default is 127.0.0.1:8080.
The explicit server.listener_mode: tls_private_network accepts only one
canonical private unicast IP and port and requires a protected server certificate,
private key, internal-PKI CA bundle, and canonical lowercase DNS server name.
Startup verifies the key pair, validity interval, SAN, ServerAuth usage, and
chain to that CA. The leaf must contain exactly that one DNS SAN; wildcard,
alternate DNS, IP, email, and URI identities are rejected. The listener permits
only TLS 1.3 and HTTP/1.1. Its only accepted HTTP Host authority is the exact
certificate DNS name plus the listener port. Deploy it on
a dedicated internal container network with no published or proxied port and
only the approved adapter as another application participant. There is no
plaintext private-network compatibility mode.
Both modes reject hostnames as listener addresses, IPv4-mapped IPv6, zone identifiers, Unix sockets, port zero, and multiple listeners.
/v1/process, /v1/sign, and /v1/revise each require
X-DKIM2-Capability. The value is the canonical unpadded Base64url encoding
of the exact 32 raw bytes in that route's current-generation capability file.
Process, sign, and revise capabilities must be distinct. Missing, duplicate,
malformed, noncanonical, or mismatching values all receive the same closed
403 response before readiness, body, DNS, policy, replay, or signing work.
/healthz, /readyz, and /metrics do not use this header.
Grant capability-file access only to the daemon UID and approved local
adapters. Do not place capability bytes or their encoded form in arguments,
environment variables, logs, traces, metrics, diagnostics, or ordinary
configuration. dkim2-milter and dkim2ctl provide protected-file loaders for
the capabilities they use; they never receive private keys or datasource
records.
Loopback HTTP is deliberately plaintext and HTTP/1-only. Private-network mode terminates TLS natively. Do not put a reverse proxy, TCP forwarder, TLS terminator, container port publication, or other reachability expansion in front of either mode.
Command And Exit Status
Run:
dkim2d serve --config /absolute/path/to/dkim2d.yaml
Before activation, validate the same configuration and complete protected generation without opening a listener:
dkim2d validate --config /absolute/path/to/dkim2d.yaml
dkim2d datasource key generate creates one flat-file custody key offline;
see "Flat-file signing, revision, and delivery status".
Validation performs the production descriptor-confined load, including the selected replay, tracing, datasource, signing-manifest, and PKCS#8 children, then releases all protected values. It is silent on success and never creates, repairs, changes ownership of, or rewrites protected state.
The loopback container readiness probe is:
dkim2d probe
It performs one non-proxied, non-retrying, two-second GET of the fixed
http://127.0.0.1:8080/readyz endpoint, discards bounded response bytes, and
succeeds only on 200. Deployments using the product image health check
therefore keep the daemon on its default container-local authority. A TLS
private-network deployment overrides the health check with:
dkim2d probe --tls-server-name dkim2d-inbound \
--tls-ca-file /var/lib/dkim2d/protected/<generation>/server-ca.pem \
--connect-address 10.73.0.2 \
--port 8443
The TLS probe dials the exact configured private listener IP; the DNS name is used only for certificate verification. It neither resolves nor follows a remote endpoint.
The command accepts no positional arguments. The only configuration flags are:
--listen
--policy-mode
--replay-backend
Exit status is 0 for help or a clean shutdown, 2 for command-shape and flag
errors, and 1 for configuration, startup, dependency, serve, or shutdown
failure. Runtime diagnostics are stable and content-free; the daemon does not
print an effective configuration or raw dependency errors.
Offline datasource administration uses separate commands and authorities:
dkim2d datasource bootstrap-opendkim --config /absolute/migration.yaml
dkim2d datasource bootstrap-opendkim --config /absolute/migration.yaml --apply
dkim2d datasource rollback --config /absolute/migration.yaml --generation 43
These commands never start the ordinary daemon graph. Dry-run is the default;
mutation requires --apply or the explicit rollback command.
Native domain onboarding
Native domain onboarding is a separate one-shot offline workflow. Its complete stable command tree is:
dkim2d datasource domain plan --config /abs/admin.yaml --intent /abs/domain.yaml --operation /abs/op.json
dkim2d datasource domain prepare --config /abs/admin.yaml --operation /abs/op.json
dkim2d datasource domain dns export --config /abs/admin.yaml --operation /abs/op.json --output /abs/records.txt [--domain-policy-strict]
dkim2d datasource domain prove --config /abs/admin.yaml --operation /abs/op.json
dkim2d datasource domain activate --config /abs/admin.yaml --operation /abs/op.json --apply
dkim2d datasource domain status --config /abs/admin.yaml --operation /abs/op.json
dkim2d datasource domain reconcile --config /abs/admin.yaml --operation /abs/op.json
dkim2d datasource domain abort --config /abs/admin.yaml --operation /abs/op.json
The complete operator sequence, recovery matrix, backup requirements,
higher-generation rollback, and parser-checked configuration and intent
examples are in
docs/operator/native-domain-onboarding.md.
Only the single bare token --apply authorizes activation. Missing --apply,
--apply=false, --apply=true, aliases, short forms, repeated forms, and
tokens after -- fail as command-shape errors. status does not update the
journal or backend and opens only an already-existing operation lock. A status
request for a missing operation therefore creates neither a journal nor a lock
artifact. reconcile is the sole command that may update journal knowledge
from an exact backend inspection. There is no verify command and no persisted
verified state.
All paths must be clean absolute paths beneath trusted owner-only directories.
The administration document, intent, operation journal, DNS export, CA bundle,
and three credential files must not overlap. Protected documents and secrets
are regular owner-only 0600 files with no links. DNS material is written only
to the explicitly requested protected export artifact and never to stdout,
logs, traces, or metrics. Export is create-only: an exact existing artifact is
an idempotent success, while any different existing content is a conflict and
is never replaced. A create whose final outcome cannot be proved exactly fails
as ambiguous and must be retried against the same path.
The administration schema is dkim2-domain-admin-v1. It requires a random,
deployment-unique, nonzero 128-bit authority_id in canonical lower-case
unpadded Base32, one direct verified-TLS endpoint, one protected CA bundle,
and distinct snapshot, staging, and activation identities and credential
files. LDAP uses ldap plus a canonical base DN and three canonical service
DNs. PostgreSQL uses postgresql, database plus the fixed
dkim2_datasource schema, and three roles. MySQL and MariaDB use their exact
backend class, and schema must equal database. The legacy
dkim2_publisher role is never a v3 administration authority. Generic DSNs,
shared roles, shared credential contents, insecure transport, and provider
fallbacks are rejected.
Scalar values support one nonrecursive ${NAME} environment expansion pass
before typed validation. Plain whole placeholders are resolved through native
YAML scalar typing; quoted placeholders remain strings. Missing or malformed
variables fail closed, map keys are never expanded, and secret bytes remain in
their protected files.
dns export produces DNS-02 records for operator publication. With the
explicit per-invocation flag --domain-policy-strict it also exports, after
the key records, the Draft-09 Section 3.8 Domain Policy Record
_domainkey.<domain>. TXT "v=DKIM1; f=strict" of the onboarded domain, proven
through the production policy parser. The record forbids subdomains from
making From header fields of the domain Authentic (Sections 11.1 and 20); it
affects every Draft-09 verifier, so publish it only after inventorying the
third parties that sign with subdomain keys. The flag is not stored in the
datasource or journal; a retry against the same artifact must repeat the same
flag, because a different export is a conflict. prove and
activate use a fresh configured recursive resolver path and compare exact
SPKI material. This is not a direct authoritative-server observation and does
not claim recursive-cache bypass. After activation, whether completed directly
by activate or recovered authoritatively by reconcile, the successful
report says runtime_smoke_required=true: operators must perform the existing
external runtime signing and mailflow smoke. The flag is mandatory for exactly
those two successful activated results and forbidden everywhere else. The
offline command never claims that runtime behavior is verified.
Complete human and --machine operation reports contain only bounded state,
backend, phase, result, failure, boolean classes, expected/candidate generation
numbers, total/RSA/Ed25519 credential counts, and a current generation only
when it is authoritatively known. Expected, candidate, and credential-count
facts remain present for every complete-plan result. A known zero current for
first publication remains explicit, while a failure without authoritative
current evidence omits the entire current field rather than printing zero. A
successful terminal-conflict reconcile is the sole nonactivated success that
reports a current different from the expected generation: it preserves the
authoritatively observed third-party value, distinct from both expected and
candidate. All other successful nonactivated workflows report the exact
expected current. A bounded workflow failure report is written before the fixed
content-free runtime diagnostic, while the process still exits 1.
Receipt reports are a distinct projection and expose no state, generation,
credential count, revision, operation identity, authority, paths, selectors,
DNS content, or digests. release_required and unresolved direct the operator
to status and explicit reconcile; repeated abort of a closed receipt is an
idempotent success.
Every offline domain command constructs one command-local, exporter-free observer. Exactly one bounded event must match the command result or status; missing, duplicate, invalid, or contradictory evidence fails the command. This path does not construct the daemon Fx graph, listeners, OpenTelemetry exporters, or Prometheus endpoints and emits no observation payload to stdout or stderr.
The first publication into a proven-empty backend uses the exact
expected_current: "0" administrative fence and a nonzero candidate. LDAP
proves the subtree empty and publishes current only at Activate through one
atomic LDAP Add with no placeholder current. PostgreSQL proves all datasource
tables empty in the serializable activation transaction and uniquely inserts
the singleton current row. Zero is never runtime-loadable, a nonempty
pointerless backend fails closed, and later publication requires the exact
nonzero current generation.
The internal receipt-before-Claim boundary is recovery evidence, not another
public state. release_required is write-ahead authorization for explicit
reconcile only: ownerless unchanged revision does not close it. An unresolved
receipt may close directly only from authoritative ownerless exact-revision
evidence and performs no Release. Receipt or journal ambiguity never
authorizes another backend mutation from an in-memory result.
Configuration Sources
The required YAML version is:
config:
version: dkim2d-config-v1
Configuration precedence is typed defaults, YAML, explicitly bound
environment variables, then the three flags above.
config.version and protected.generation are YAML-only. Every other stable
path has one explicit DKIM2D_... environment name, for example
DKIM2D_SERVER_LISTEN, DKIM2D_SERVER_LISTENER_MODE,
DKIM2D_SERVER_TLS_CERTIFICATE_FILE, and DKIM2D_REPLAY_HMAC_KEY_FILE. Arbitrary
environment names are ignored.
Scalar string values may contain one nonrecursive ${NAME} expansion pass.
Map keys are never expanded. Missing variables fail closed. Secret bytes are
never configuration or environment values; only protected absolute paths may
be supplied.
DNS key cache
The daemon retains DNS TTLs and caches public-key lookup outcomes in process. Cache lifetimes are the shorter of authoritative DNS TTL evidence and the configured cap; the daemon does not invent a fallback TTL. CNAME chains use their shortest TTL, while NXDOMAIN and NODATA use the RFC 2308 SOA rule.
dns:
lookup_timeout: 5s
max_concurrent_lookups: 64
cache:
max_entries: 4096
positive_ttl_cap: 1h
negative_ttl_cap: 5m
stable_error_ttl_cap: 1m
max_entries accepts 0 through 65,536. The TTL caps accept zero to disable
their respective cache class and are bounded at 24 hours, 1 hour, and 5
minutes. The corresponding environment variables are
DKIM2D_DNS_CACHE_MAX_ENTRIES, DKIM2D_DNS_CACHE_POSITIVE_TTL_CAP,
DKIM2D_DNS_CACHE_NEGATIVE_TTL_CAP, and
DKIM2D_DNS_CACHE_STABLE_ERROR_TTL_CAP.
Subdomain From authorization
verification:
domain_policy:
allow_subdomain_from: true
verification.domain_policy.allow_subdomain_from is a stable boolean path,
default true, with the environment name
DKIM2D_VERIFICATION_DOMAIN_POLICY_ALLOW_SUBDOMAIN_FROM; ${NAME}
placeholders follow the usual scalar rules and a missing variable fails
closed. With true the verifier applies Draft-09 Sections 7.1 item 3 and
11.1: when d= is a subdomain of the From domain, the From header field is
Authentic unless the From domain publishes a Domain Policy Record with
f=strict at _domainkey.<domain> (Section 3.8). The record is looked up
through the same bounded DNS resolver, cache, and limits as keys, only for
messages whose every signature already passed. A strict record yields FAIL
from_subdomain_forbidden; more than one or an invalid record yields
PERMERROR domain_policy_ambiguous or domain_policy_invalid; a temporary
DNS failure yields TEMPERROR domain_policy_temporary, which the policy
modes treat like any TEMPERROR. Setting false selects the documented local
downward-only policy: no Domain Policy Record is ever queried and such
messages are FAIL from_not_authentic, which rejects messages that Draft-09
defines as PASS. Signers built by the daemon verify incoming chains with the
same choice; their own d= choice is always downward only.
Inbound policy mode
policy.mode defaults to strict; omitting it enables enforcement. Operators
must select a compatibility policy explicitly when the Draft-09 verifier is
introduced beside an existing inbound path:
strictacceptsPASS, rejectsFAILandPERMERROR, and temporarily defersTEMPERROR;permissiveacceptsFAILandPERMERRORfor rollout compatibility while preserving temporary deferral forTEMPERROR; andtestingreturns non-terminalcontinuefor every coherent verification state so the daemon can report results without controlling delivery; when reporting is enabled, the response still carries the exact daemon-ownedAuthentication-Resultsaction.
These modes apply only when at least one DKIM2 protocol field family is
present. A syntactically valid message with neither Message-Instance nor
DKIM2-Signature is not a failed verification: it is the Draft-09 Section
14.1 NONE state. /v1/process returns HTTP 200 with verification and
authentication state NONE, policy verdict continue with reason none,
replay not_checked, and disposition continue. It performs no DNS lookup,
policy evaluation, replay check, or signing work in any policy mode, including
strict. The only possible action is the daemon-owned
Authentication-Results: <authserv-id>; dkim2=none report, without a comment,
when the request carries a reporting authority; otherwise the action plan is
empty. The process metric and log verdict label records none.
Independently, an enabled Milter trust boundary still removes forged local
Authentication-Results fields as required by RFC 8601. A message
containing only one field family, malformed fields, missing referenced fields, or
inconsistent sequences remains an applicable PERMERROR; strict may reject
it. There is no domain-wide DNS participation probe because the selector and
signing domain needed for key lookup come from a present DKIM2 signature.
The verification state remains unchanged in every mode. testing is the
delivery-neutral pilot choice and reports applicable results on its accepting
non-terminal continue disposition. permissive is useful when failed or
permanently erroneous verification should receive an accepting terminal
disposition. Neither mode converts local daemon ambiguity, invalid responses,
unavailable dependencies, or Milter fidelity failures into success.
Originator signing has a separate authorization boundary and does not inherit the inbound policy mode. A healthy authoritative absent or inactive exact signing policy returns bodyless HTTP 204: signing is not applicable and the caller continues without mutation. An unavailable, degraded, ambiguous, or inconsistent datasource remains temporary; malformed active configuration remains permanent. HTTP 204 is never an availability fallback.
Null senders are classified by the originator Milter before daemon I/O and
continue to tempfail there. The separate postfix_dsn adapter may call the DSN
route only after exact Postfix-only internal origin validation. The body has
no caller-selected fidelity; the dedicated DSN capability is the server-side
provenance attestation and must not be shared. The adapter requires the corresponding Postfix
patch before deployment. Address literals and otherwise unsupported valid
SMTPUTF8 envelopes remain not applicable and continue unchanged. Malformed
Milter callback syntax remains fail-closed. The implementation does not infer
DSN signing authority from message headers, HELO, recipients, suffixes,
wildcards, tenant defaults, or caller-selected domains. It verifies the
embedded DKIM2 object first and then chooses the signing domain under
draft-ietf-dkim-dkim2-spec-09 Section 16.2: only a local delivery_status
profile domain that relaxed-matches an rt= address of the highest
DKIM2-Signature of the returned original, and whose domain makes the report
From Authentic, can sign (see below). Otherwise the report leaves unsigned
with HTTP 204 and an X-DKIM2-Unsigned-Reason.
A returned original that carries no DKIM2-Signature header field at all is
outside draft-ietf-dkim-dkim2-spec Section 16, which defines DSN handling only
for DKIM2-signed originals. Such a report is refused by default exactly like
failed embedded evidence (permerror/reject, evidence stage
embedded_unsigned). The explicit compatibility policy
signing.policy.delivery_status.unsigned_original: continue instead answers
/v1/dsn/sign with bodyless HTTP 204: the report leaves unsigned and unchanged
as a classic RFC 3464 notification, without profile resolution or key access.
See Flat-file signing, revision, and delivery status
for the rationale and limits.
Complete-fanout revision
server.batch_revise_capability_file explicitly enables
POST /v1/revise/batch and its authenticated read-only discovery route
GET /v1/revise/batch/capabilities. Its private 32-byte credential belongs to
the selected protected generation and must differ from every other enabled
route capability and replay key. The canonical unpadded base64url credential
is sent only in X-DKIM2-Batch-Revise-Capability. The environment path override
is DKIM2D_SERVER_BATCH_REVISE_CAPABILITY_FILE; never put credential bytes
in configuration, environment values, arguments or logs.
The route needs a configured signing backend and exact ordinary_transit
policies for each external signing context. It accepts exact original SMTP
evidence and the complete actual local/external fanout. Optional same-tenant
controlled intermediate hops require both transit policies and local authority
over the intermediate recipient domain. Only library-verified unrestricted
external signatures are returned. A local delivery may stand if the external
batch fails. The service performs no SMTP delivery or SRS encoding.
Bounds are 32 actual copies, 262,144 response bytes, one optional controlled hop per external copy, at most three generated header fields per output, and two size bounds that the capability route advertises as configured:
max_aggregate_message_bytes, the decoded original plus every copy: 268,435,456 by default, orserver.batch_revision.max_aggregate_message_bytes(DKIM2D_SERVER_BATCH_REVISION_MAX_AGGREGATE_MESSAGE_BYTES, at leastserver.message_bytes, at most 536,870,912). Each message still obeysserver.message_bytes.max_request_bytes, the JSON body: by default the shared single-message ceiling2 * base64(server.message_bytes) + 3,139,072; with a configured aggregate the separately padded Base64 of the aggregate plus 3,139,072 bytes, at most 718,967,044.
A configured aggregate gives /v1/revise/batch its own working-set sizing and
admission pool with server.batch_revision.max_in_flight permits (default 1,
at most 8). Every shared permit and every batch permit must fit
server.working_set_bytes (DKIM2D_SERVER_WORKING_SET_BYTES, default
8,589,934,592, 1 GiB to 64 GiB) at the same time, or the daemon refuses to
start. The aggregate requires server.batch_revise_capability_file. See
message size for memory figures and the
recommended production values. Clients must stop an oversized plan without
omitting actual copies.
Ordinary external null-sender revision is unsupported. Received signed DSNs
use the existing separately authorized propagation API and replay contract.
The batch revision contract
contains the generated DTO shape, exact-byte insertion procedure and return
workflow. Existing Milter clients do not acquire this capability implicitly.
Explicitly disabled replay
This is the smallest valid document:
config:
version: dkim2d-config-v1
protected:
generation: 0123456789abcdef0123456789abcdef
server:
capability_file: /var/lib/dkim2d/protected/0123456789abcdef0123456789abcdef/capability
replay:
backend: disabled
Disabled replay is explicit local policy. It loads no replay HMAC, constructs
no replay deriver, and does not silently fall back to another backend. It
cannot be combined with server.dsn_propagate_capability_file: the
propagation routes need a stored replay coordinate and the loader refuses that
matrix (see "Received delivery-status evaluation and propagation").
For one private container-network listener, the same generation must also own the internal-PKI identity:
server:
listen: 10.73.0.2:8443
listener_mode: tls_private_network
tls:
certificate_file: /var/lib/dkim2d/protected/0123456789abcdef0123456789abcdef/server-cert.pem
private_key_file: /var/lib/dkim2d/protected/0123456789abcdef0123456789abcdef/server-key.pem
ca_file: /var/lib/dkim2d/protected/0123456789abcdef0123456789abcdef/server-ca.pem
server_name: dkim2d-inbound
capability_file: /var/lib/dkim2d/protected/0123456789abcdef0123456789abcdef/capability
All four protected files are distinct children of the selected generation.
The certificate must contain only dkim2d-inbound as its DNS SAN, contain no
other SAN identity type, and chain to the configured internal CA. Wildcard and
alternate identities are rejected. The private key and certificate are loaded
only through the descriptor-confined protected-generation owner.
Certificate renewal selects a new complete immutable generation. It need not rotate the route capabilities or replay HMAC: the secret-management authority may publish those exact existing bytes into the new generation while replacing only the TLS identity. Active generation files are never edited in place.
Flat-file signing, revision, and delivery status
Signing is disabled by default. Enabling the flat-file backend requires one or more distinct signing-route capabilities and a datasource, private-key manifest, and referenced PKCS#8 children from the same protected generation:
config:
version: dkim2d-config-v1
protected:
generation: 0123456789abcdef0123456789abcdef
server:
capability_file: /var/lib/dkim2d/protected/0123456789abcdef0123456789abcdef/capability
sign_capability_file: /var/lib/dkim2d/protected/0123456789abcdef0123456789abcdef/sign-capability
revise_capability_file: /var/lib/dkim2d/protected/0123456789abcdef0123456789abcdef/revise-capability
dsn_sign_capability_file: /var/lib/dkim2d/protected/0123456789abcdef0123456789abcdef/dsn-sign-capability
replay:
backend: disabled
signing:
backend: flat_file
datasource_file: /var/lib/dkim2d/protected/0123456789abcdef0123456789abcdef/datasource
private_manifest_file: /var/lib/dkim2d/protected/0123456789abcdef0123456789abcdef/private-manifest
policy:
originator:
null_sender: reject
delivery_status:
unsigned_original: reject
The daemon requests no signing flags. Draft-07 Section 10.10 removed the
donotmodify and donotexplode flags, so the former six
signing.policy.<use>.donotmodify and signing.policy.<use>.donotexplode
keys (<use> is originator, ordinary_transit, or delivery_status) and
their DKIM2D_SIGNING_POLICY_<USE>_DONOTMODIFY and
DKIM2D_SIGNING_POLICY_<USE>_DONOTEXPLODE environment variables are no longer
accepted. If any of them is present, even set to false, dkim2d validate and
dkim2d serve exit with status 1 and print, for example:
dkim2d: configuration key signing.policy.originator.donotmodify was removed in Draft-07 because the donotmodify and donotexplode flags no longer exist and have no effect; delete this setting
Delete the setting (or unset the environment variable) to migrate; there is no
replacement. exploded is never configuration: signing derives it only from a
sealed multi-copy route plan.
signing.policy.delivery_status.reporting_domain is optional and absent by
default. It is the preferred Section 16.2 candidate of POST /v1/dsn/sign,
not a signing identity of its own. The daemon signs a bounce only under a
local delivery_status profile domain that relaxed-matches (Section 7.1 item
4: the rt= address is Parameter1, d= is Parameter2) an rt= address of
the highest DKIM2-Signature of the returned original and that makes the
report's own From Authentic (Sections 11 and 12.4). Candidates are tried with
RFC 3464-linked recipients first, then reporting_domain when it is itself a
candidate, then the most specific domain, then octet order. A configured
domain that does not match is never used. When no candidate has a profile,
or none makes the From Authentic, the report leaves unsigned and unchanged
(HTTP 204 with X-DKIM2-Unsigned-Reason: delivery_status_identity_unavailable
or delivery_status_from_not_authentic) instead of failing. The value must be
one canonical lowercase DNS domain with at least two labels and a non-numeric
top label. Any other value is refused at load time, and the key is invalid
with signing.backend: disabled. The environment override is
DKIM2D_SIGNING_POLICY_DELIVERY_STATUS_REPORTING_DOMAIN.
Behavior change of a stable path (Draft-08 migration): reporting_domain used
to be the signing identity of every Postfix bounce and was signed even when it
did not match the returned original's rt=; Draft-09 Section 16.2 forbids
that. The path, its type, and its validation are unchanged; its meaning is now
"preferred candidate when matching". Migration: keep the setting only if the
domain is the recipient domain (or a parent) of the bounced mail you want
signed under it, give every recipient domain whose bounces should be signed a
delivery_status profile at or above that domain, and make sure the Postfix
bounce From (MAILER-DAEMON@$myorigin) lies at or below that profile domain.
See docs/operator/postfix-compose.md for the expected unsigned share and the
dkim2d_dsn_unsigned_total{unsigned_reason} counter.
signing.policy.delivery_status.unsigned_original is the explicit
compatibility policy of POST /v1/dsn/sign for a returned original that carries
no DKIM2-Signature header field at all. It accepts exactly reject (the
default) or continue; any other value is refused at load time, and continue
is invalid with signing.backend: disabled. The environment override is
DKIM2D_SIGNING_POLICY_DELIVERY_STATUS_UNSIGNED_ORIGINAL.
rejectkeeps the fail-closed behavior: the operation answerspermerror/rejectand the Postfix DSN adapter refuses the bounce.continueanswers bodyless HTTP 204 withX-DKIM2-Unsigned-Reason: unsigned_original. The adapter continues without mutation and Postfix delivers the bounce unsigned and unchanged, as a classic RFC 3464 notification.
The rationale is transitional: draft-ietf-dkim-dkim2-spec Section 16 defines
DSNs only for DKIM2-signed originals and is silent about originals without a
DKIM2 signature. While inbound mail is accepted without DKIM2, a bounce for
such mail must still reach its sender; refusing it keeps the original message
queued at the MTA and the sender never learns about the failure. The policy
is scoped strictly to the absence of every DKIM2-Signature field, compared
case-insensitively, in either the message/rfc822 or the
text/rfc822-headers representation. An original that carries any
DKIM2-Signature field, valid, failing, or malformed, is never relaxed: it
is verified and signed, or refused, exactly as without the policy. Every other
evidence failure is also unaffected. Each outcome is counted in
dkim2d_dsn_evidence_total with evidence_stage="embedded_unsigned" and
result="failure" (refused) or result="not_applicable" (left unsigned);
a report left unsigned is also counted in
dkim2d_dsn_unsigned_total{unsigned_reason="unsigned_original"}.
Optional interoperability header
Set signing.interop_info.enabled: true (environment override:
DKIM2D_SIGNING_INTEROP_INFO_ENABLED=true) to append one X-DKIM2-Info
field after successful /v1/sign, /v1/revise, and /v1/dsn/sign operations.
The default is false; scalar environment placeholders follow the normal
configuration rules. The path is stable for the dkim2d-config-v1 window.
signing:
interop_info:
enabled: true
For example, an RSA signing operation produces:
X-DKIM2-Info: draft=ietf-dkim-dkim2-spec-09;
repo=github.com/croessner/dkim2; date=2026-11-02; sw=dkim2d;
action=sign d=example.test a=rsa-sha256;
sw identifies the software. repo points to this implementation, and date
is the date the emitted DKIM2 behavior last changed, a code version stamp as
draft-gondwana-dkim2-debug-header-02 Section 5 defines it, not the signature
timestamp or the draft date. The field keeps the established hop block order
(Message-Instance, DKIM2-Signature, X-DKIM2-Info) rather than the
placement the companion draft suggests, because the companion is
non-normative and adapters insert the block contiguously.
d and the comma-separated, deduplicated a list come from the generated
signature, including both algorithms for dual signing. action=sign describes
signature creation, including a transit or delivery-status signature.
This is a local diagnostic convention, not a DKIM2 requirement. Draft-09
Section 4 excludes X- fields from authentication. Never trust this header as
an authentication result. Existing informational headers are preserved; each
successful local operation adds its own. Failure, unsigned/no-op, and inbound
verification paths do not add it. The standalone library, batch revision, and
received-DSN propagation interfaces retain their existing output contracts.
Upgrade the daemon and adapters together before enabling this option: older
strict clients reject the additional action. Current Milter, Exim, and
dkim2ctl clients admit exactly one trailing informational field on successful
outgoing action plans. The API sends unfolded field values; transport framing
remains owned by the adapter.
signing.policy.originator.null_sender decides whether POST /v1/sign
admits a null reverse path. It accepts exactly reject (the default) or
header_from; any other value is refused at load time, and header_from is
invalid with signing.backend: disabled. The environment override is
DKIM2D_SIGNING_POLICY_ORIGINATOR_NULL_SENDER.
rejectkeeps the fail-closed behavior: a sign request withsmtp.mail_from<>is an invalid contract (HTTP 400) before any datastore access, whether or not it carries a declaration.header_fromadmits a null reverse path only when the request also carriesnull_sender: header_fromand itscontext.domainequals the domain of the single RFC 5322 From mailbox: exactly one From field holding exactly one ASCII mailbox with a canonical DNS domain; groups, several mailboxes, address literals, and SMTPUTF8 authors are refused. The daemon resolves theoriginatorprofile for that tenant and domain as for any other sender (an absent or inactive profile answers 204) and signsmf=<>withrt=equal to the actual recipients. The library refuses the signature again if the profile domain is not the From domain. A message that already carries aDKIM2-SignatureorMessage-Instancefield, or whose top-levelContent-Typeismultipart/reportwithreport-type=delivery-status(or is repeated or unparsable), is refused as an invalid contract: delivery-status notifications are signed only onPOST /v1/dsn/sign. The declaration is refused with a non-null reverse path, and/v1/reviseand batch revision never admit a null reverse path.
The rationale is draft-ietf-dkim-dkim2-spec Section 10.5, which allows mf=<>,
and Section 10.8, under which a null mf= requires no d= match. Automatic
replies, Sieve notifications, and RFC 8098 disposition notifications from our
own systems use the null reverse path and would otherwise leave without
DKIM2. A null sender is trivial to forge, so the trust decision belongs to
the MTA listener: enable header_from only on a daemon whose originator
callers sit exclusively on trusted egress routes (authenticated submission,
own relay hubs, internal application sockets), never for an adapter attached
to an inbound or MX-facing listener. Bounces keep their dedicated
POST /v1/dsn/sign route.
Received donotmodify or donotexplode spellings are inert unknown flags
under Draft-09: they never restrict revision, fanout, or external release.
Existing fail-closed authorization remains authoritative.
Received delivery-status evaluation and propagation
Three stable configuration paths govern received delivery-status notifications. All three are optional and all three default to today's behavior.
server:
dsn_propagate_capability_file: /var/lib/dkim2d/protected/0123456789abcdef0123456789abcdef/dsn-propagate-capability
process:
default_tenant: tenant-a
dsn_propagation:
pending_lease: 120s
server.dsn_propagate_capability_file is the protected 32-byte credential of
/v1/dsn/propagate and /v1/dsn/propagate/commit. Its presence enables both
routes. It belongs to the same protected generation as every other capability,
must be distinct from all of them, and is accepted on no other route; no other
capability is accepted on these two. It does not require
dsn_sign_capability_file: propagation signs with the tenant's
delivery_status datasource profile, not through the /v1/dsn/sign route,
and a local domain without that profile is answered permerror/discard
with propagation_failure: unprovisioned_domain.
server.dsn_propagate_capability_file is refused together with
replay.backend: disabled; the loader answers
config_invalid_backend_matrix, and the daemon lifecycle refuses to compose
the route over the disabled backend even if a loader were bypassed. The
two-phase propagation coordinate is the only bound on how many signed
notifications one captured DSN can extract from this daemon, so a propagation
route without replay storage would be an unbounded signing oracle. There is no
opt-out; propagation requires the memory or redis backend.
process.default_tenant names the administrative tenant that /v1/process
uses when a request carries no context.tenant. Locality of a received
delivery-status notification is tenant-keyed, so without a tenant the
delivery_status projection reports local_hop: not_evaluated and
propagation: not_evaluated and the policy accepts it, which is exactly the
behavior of a daemon that never configured one. The inbound Milter sends no
tenant and relies on this value. Two tenants on one daemon are isolated by
this key: a domain that is local for tenant A is not_local for tenant B.
dsn_propagation.pending_lease is how long one reserved propagation
coordinate stays pending before another attempt may re-serve it. It defaults
to 120 seconds, is only meaningful together with the propagation capability,
and must exceed the adapter's daemon call timeout plus its re-injection and
commit timeouts. A live lease answers temperror/tempfail, an expired lease
re-serves with a fresh rebuild and a fresh commit token, and a committed
coordinate answers pass/discard. Issued commit tokens are held in a
bounded process-local ledger for the lease plus a small fixed margin; they do
not survive a restart, and an unresolvable token is answered 409 so the
caller defers rather than leaving a coordinate uncommitted.
Readiness and latency: /v1/process reads the signing datasource whenever an
inbound message is classified as a received delivery-status notification and a
tenant is available. This is the only datasource dependency on the process
path. It runs after canonical domain-syntax validation, uses the same bounded
lease and read path as the signing routes, and is served from a bounded
per-tenant negative cache shared by /v1/process and /v1/dsn/propagate, so
a stream of foreign notifications does not turn every inbound message into a
datasource read. A foreign domain costs one bounded read per profile use
before it is cached; a local domain usually costs one. Readiness is unchanged:
the datasource is already a readiness dependency whenever signing is enabled,
and ordinary inbound messages that are not delivery-status notifications never
reach this lookup. A datasource outage is reported as local_hop: temperror
with a tempfail disposition, never as not_local.
Datasource consumers and the valid capability matrix
A configured signing.backend needs at least one consumer. Exactly three
shapes are valid, and a datasource that nothing consumes is refused with
config_invalid_backend_matrix rather than loaded as a silent no-op.
| Shape | Route capabilities | process.default_tenant |
Datasource | Registered signing routes |
|---|---|---|---|---|
| Verification with locality | none | required | read-only, for locality | none; /v1/sign, /v1/revise, /v1/dsn/sign, /v1/dsn/propagate answer 403 |
| Propagation only | dsn_propagate_capability_file |
optional | read plus delivery_status signing |
/v1/dsn/propagate, /v1/dsn/propagate/commit |
| Full signing | any of sign, revise, dsn_sign, dsn_propagate |
optional | read plus signing | the configured routes only |
The verification shape is the correct one for an internet-facing inbound
daemon that must classify a received delivery-status notification as local or
foreign: locality is a datasource read keyed by process.default_tenant, it
never reaches a private key, and the daemon constructs no signer at all. Do
not add an unused dsn_sign or dsn_propagate capability to make the
datasource acceptable.
The propagation shape needs no dsn_sign_capability_file. Both shapes are
accepted by the protected-generation loader with exactly the capability
children they declare; a generation carrying a capability the document does
not configure, or missing one it does, stays refused with
config_protected_content.
Readiness is identical in all three shapes: whenever signing.backend is
configured, the datasource runtime is a readiness dependency, so a
verification daemon whose datasource is unavailable at startup does not become
ready. A later outage is reported as local_hop: temperror, never as
not_local.
Omit every unused route capability. dsn_sign_capability_file authorizes only
the Postfix-exclusive /v1/dsn/sign; possession attests that its sole adapter
established trusted internal origin. It is distinct from process, sign,
revise, replay, and all other protected material and must not be shared with a
diagnostic client or another adapter. The datasource is the closed
dkim2-datasource-v1 format documented in
docs/specs/implementation/datasource-providers.md.
The private manifest is dkim2-private-keys-v1; every entry binds one exact
tenant, domain, originator, ordinary_transit, or delivery_status use, opaque datasource
handle, rsa-sha256, ed25519-sha256, or mldsa44 algorithm, canonical Base64 SHA-256
digest of the public SPKI, and direct-child private-key filename. A
private-key child is one unencrypted PKCS#8 PRIVATE KEY PEM whose derived
public key matches that digest, algorithm, datasource credential, and handle.
An mldsa44 key is the seed-only PKCS#8 form (OID 2.16.840.1.101.3.4.3.17,
the 32-byte seed, 54 octets of DER) that crypto/x509 and
opendkim-manage-go produce; any other encoding, parameter set, or an
all-zero seed fails the load. A flat-file profile lists its credentials in
canonical order rsa-sha256, ed25519-sha256, mldsa44 and holds at most
three. The Draft-07 composite mldsa44-ed25519-sha512 is not supported (see
docs/reference/known-limitations.md);
a manifest entry, datasource credential, or key that declares it fails the
complete load.
Generate a custody key and its public credential offline:
dkim2d datasource key generate --algorithm ed25519-sha256 \
--domain example.test --selector ed-20261021 \
--private-key /absolute/staging/path/ed-20261021.pem [--ttl 3600] [--machine]
The command creates the PEM file with mode 0600 and never replaces an
existing path. Standard output carries only public material: the
public_key_spki value for the datasource credential, the
public_spki_sha256 value for the manifest entry, and the zone-file TXT
record from the same record owner and DNS-02 parser round trip as the domain
DNS export. --algorithm accepts rsa-sha256, ed25519-sha256, or
mldsa44; --rsa-bits selects 2048, 3072, or 4096 for rsa-sha256. An
mldsa44 record is v=DKIM1; k=mldsa44; p=<raw 1312-octet key> without
h= (local interpretation DKIM2-ISSUE-0020, the same form
opendkim-manage-go publishes); its 1752-character p= value is split into
TXT strings of at most 255 octets. The OpenDKIM
bootstrap imports only legacy rsa and ed25519 keys. RSA signing keys
below 2048 bits are rejected everywhere (signing floor). Unknown fields, duplicate
bindings, aliasing children, mixed identities, encrypted or legacy PEM, and
partial generations fail the complete load. Documentation and test fixtures
use reserved .test identities; operators supply only their own authorized
production policy.
The reload interval revalidates the same descriptor-confined snapshot; it does not authorize editing an active protected generation or switching generation selectors. A complete valid candidate is published atomically. An invalid candidate is never published: the prior snapshot remains retained only for owned in-flight work while the runtime becomes degraded and readiness withdraws.
LDAP, PostgreSQL, MySQL, and MariaDB signing
The ldap, postgresql, and mysql signing backends replace the flat-file
datasource with one verified-TLS immutable committed generation containing the
canonical PKCS#8 DER keys for its opaque handles. LDAP, PostgreSQL, MySQL, and
MariaDB accept an exact complete dkim2-datasource-v2 or
dkim2-datasource-v3 generation. These backends reject
private_manifest_file; no local private-key tree is mounted. The public
dataset and native keys must validate as one exact generation. Initial-load failure
prevents readiness; a linearized refresh failure makes new leases unavailable
until a complete higher generation loads. Exact configuration examples,
schema/DDL installation, role separation, backup, and recovery are in the
datasource operator guide linked above. MariaDB uses the mysql selector and
the same typed, verified-TLS provider contract.
The LDAP tree and attributes are documented in the
LDAP schema reference; normal
generation replacement and retirement are documented in the
key-rotation runbook.
Offline global rotation campaigns
dkim2d datasource rotation is a closed offline command surface. A scheduled
normal run always means the complete frozen active-binding inventory: it creates
one immutable candidate and moves current once only after every bounded DNS
batch has fresh proof. It never creates one generation per domain.
dkim2d datasource rotation run --config /path/to/rotation.yaml --journal /path/to/campaign.json --automatic
dkim2d datasource rotation run --config /path/to/rotation.yaml --journal /path/to/campaign.json --automatic --apply
dkim2d datasource rotation emergency --config /path/to/rotation.yaml --journal /path/to/campaign.json --tenant <exact> --domain <exact> --use <exact> --profile <exact> --reason <bounded-class> --apply
dkim2d datasource rotation abort --config /path/to/rotation.yaml --journal /path/to/campaign.json --apply
dkim2d datasource rotation purge plan --config /path/to/rotation.yaml --journal /path/to/campaign.json --output /path/to/purge.json
dkim2d datasource rotation purge apply --config /path/to/rotation.yaml --journal /path/to/campaign.json --plan /path/to/purge.json --apply
--automatic is mandatory for a normal campaign. Emergency selection, pointer
mutation, and purge destruction are never defaults: they require their explicit
subcommand and one exact bare --apply. The normal command defaults to
read-only --dry-run; --dry-run and --apply are mutually exclusive.
Human and machine reports contain only counts, backend class, command, state,
and closed result classes; they never contain domains, DNs, selectors, plan
digests, DNS content, provider errors, or key material.
The protected campaign configuration uses five distinct role credentials:
snapshot, staging, activation, purge, and the terminal-only closer. All configured limits are finite and
below compiled maxima. The selected public compatibility contract is
admincontract, whose strict synthetic fixture is
checked by make check-admin-contract before a consumer binds the owner API.
Process-local memory replay
config:
version: dkim2d-config-v1
protected:
generation: 0123456789abcdef0123456789abcdef
server:
capability_file: /var/lib/dkim2d/protected/0123456789abcdef0123456789abcdef/capability
replay:
backend: memory
hmac_key_file: /var/lib/dkim2d/protected/0123456789abcdef0123456789abcdef/hmac
epoch: 1
Memory replay is bounded but process-local. Restart, multiple daemon instances, and failover do not share its state.
By default replay counting follows Draft-09 Section 15.1: a message carrying
only the originator's i=1 DKIM2-Signature is a direct delivery, reports the
replay class not_eligible, and touches no store. A receiver that acts on
every accepted message, such as a public reflector, may set
replay.count_direct_deliveries: true (DKIM2D_REPLAY_COUNT_DIRECT_DELIVERIES)
with the memory or Redis backend. Direct deliveries are then counted like
re-sent messages: the first is first_seen, an identical later one is
replayed. The key is rejected with replay.backend: disabled.
The option is meant for single-shot services such as a reflector, not for ordinary mailbox receivers. With it enabled:
- a legitimate SMTP retransmission of a direct message, for example after a
lost
250reply, is rejected as a replay; - when a sending MTA splits recipients into separate transactions, only the first transaction is delivered.
Production Redis replay
redis is the default backend and the production choice. It talks to a
Redis 7.0+ or Valkey 7.2+ server through go-redis v9 in standalone,
sentinel, or cluster mode. Missing mode-specific keys fail configuration;
there is no fallback. A standalone shape with TLS and an ACL user is:
config:
version: dkim2d-config-v1
protected:
generation: 0123456789abcdef0123456789abcdef
server:
capability_file: /var/lib/dkim2d/protected/0123456789abcdef0123456789abcdef/capability
replay:
hmac_key_file: /var/lib/dkim2d/protected/0123456789abcdef0123456789abcdef/hmac
epoch: 1
redis:
mode: standalone
standalone:
address: 127.0.0.1:6380
auth:
username: application
password_file: /var/lib/dkim2d/protected/0123456789abcdef0123456789abcdef/redis-password
tls:
ca_file: /var/lib/dkim2d/protected/0123456789abcdef0123456789abcdef/ca
server_name: replay.example
Sentinel uses sentinel.master_name, a comma-separated
sentinel.addresses scalar, and optional sentinel.username and
sentinel.password_file; cluster uses a comma-separated cluster.addresses
scalar and cluster.max_redirects. TLS is on by default (minimum TLS 1.2,
tls.min_tls_version: TLS1.3 available) and may be disabled with
tls.enabled: false for a private network. Passwords, the CA bundle, and an
optional client certificate pair (tls.cert, tls.key) are protected
generation children. key_prefix namespaces the keys on a shared instance.
Pool, timeouts, retries.*, health.*, and require_noeviction have bounded
defaults.
Writes may be retried and may follow failover or redirects: each write embeds
a per-operation nonce, so a retried attempt recognizes its own earlier commit,
and an unprovable outcome stays a temporary failure. Startup refuses a server
below the version floor or a primary without maxmemory-policy noeviction.
See docs/replay-store-redis.md for every
key, the ACLs, eviction, persistence, the loss window, TLS, credentials, and
rotation, and
docs/operator/replay-redis-migration.md
for moving from the removed valkey backend. replay.valkey.*,
replay.revalidate_interval, and replay.backend: valkey fail with
config_removed_field.
Protected Generation
The YAML file and every protected object are owned by the daemon's effective
UID. The YAML file is mode 0400 or 0600, is outside the generation
directory, has one link, and is inode-distinct from every protected child.
The generation directory:
- is absolute and ends with the exact 32-character lowercase hexadecimal
protected.generationvalue; - is mode
0500and owned by the daemon UID; - contains every selected protected path as a direct child; and
- is immutable after publication and never reused.
The capability and HMAC files contain exactly 32 raw nonzero bytes, with no
hex, Base64, delimiter, or stripped newline. Password files contain 1 through
1,024 opaque bytes with no NUL, CR, or LF. Secret files are mode 0400 or
0600. The CA file contains only the bounded accepted PEM CA set and may use
the documented read-only modes.
Protected loading uses portable descriptor-native ownership, mode, link, size, regular-file, no-follow, and stable-read checks on Linux and Darwin. The application does not classify filesystems, mounts, ACLs, or xattrs; deployment and container policy own that surrounding boundary.
Create a complete new read-only generation directory, then atomically replace only the YAML file that selects it. There is no hot reload. Activation requires a process restart.
HTTP API
Exactly these paths are routable:
| Method | Path | Purpose |
|---|---|---|
GET |
/metrics |
Bounded process-local Prometheus exposition |
GET, HEAD |
/healthz |
In-process liveness; no dependency I/O |
GET, HEAD |
/readyz |
No-I/O readiness snapshot |
POST |
/v1/process |
Verification, policy, replay, disposition |
POST |
/v1/sign |
Originator signing and ordered append-only actions |
POST |
/v1/revise |
Ordinary-transit verification, revision, and ordered actions |
POST |
/v1/dsn/sign |
Postfix-exclusive authenticated delivery-status signing |
POST |
/v1/dsn/propagate |
Received delivery-status evaluation, rebuild, and propagation signing |
POST |
/v1/dsn/propagate/commit |
Commit of one reserved propagation coordinate |
Health and readiness support their declared strong-ETag conditional behavior.
Readiness is 200 only after immutable configuration and protected loading,
dependency construction, listener and serve ownership, open process
admission, and replay authority are ready. Redis readiness reads the
provider's recovery state, which the startup checks and the health probe
maintain, and performs no Redis call.
The process request carries bounded Base64 message bytes and separate SMTP reverse/forward path spellings. After JSON and Base64 validation, the adapter passes the exact decoded message and UTF-8 envelope spellings to the library; it does not normalize headers, MIME, EAI, SMTPUTF8, or envelope values. Malformed mail-domain evidence is represented by the library's bounded domain result rather than repaired by the HTTP layer.
Sign requests carry the exact outgoing message and SMTP envelope plus a server-owned tenant/domain selector. Revise requests additionally carry exact incoming SMTP envelope evidence. The daemon resolves policy and private-key handles from its current signing snapshot and returns only a closed ordered append-only header action plan; it never exposes a private key, capability, datasource record, or handle. Generated OpenAPI DTOs remain at this HTTP boundary and are not a second protocol model.
Every application response has Connection: close. Connection reuse,
pipelining, HTTP/2, h2c, generic path cleaning, and redirects are not supported.
All request, connection, body, JSON, envelope, DNS, replay, admission, and
shutdown work is bounded. Error output uses closed status/code mappings and
does not include request bytes, protected values, endpoints, or raw errors.
Observability
Every daemon instance owns one central JSON slog provider, one fresh
Prometheus registry, and one OpenTelemetry provider. None of these use global
registration. Telemetry is nonnormative and cannot change protocol, policy,
replay, HTTP, health, or readiness results.
The secure default uses info logging, all debug modules disabled, and no
trace exporter:
observability:
logging:
level: info
debug:
message_shape: false
dns: false
replay: false
tracing:
exporter: none
OTLP/HTTP tracing is explicit and may use a direct local or remote HTTPS collector:
observability:
tracing:
exporter: otlp_http
endpoint: https://collector.example:4318/v1/traces
ca_file: /var/lib/dkim2d/protected/0123456789abcdef0123456789abcdef/otlp-ca
sample_per_million: 10000
export_timeout: 5s
The endpoint must use a canonical lowercase ASCII DNS name or canonical IP
literal, an explicit nonzero decimal port, HTTPS, and exactly /v1/traces.
The CA is a protected generation child. The URL hostname is the sole TLS peer
identity; normal certificate and hostname/IP verification applies, so there is
no separate server_name override. Exactly TLS 1.3 is permitted. Proxies,
redirects, arbitrary headers, environment-driven exporter configuration,
compression overrides, userinfo, queries, and fragments remain rejected.
Loopback HTTPS endpoints remain supported. Remote export does not relax the
daemon HTTP listener's separate inbound transport contract.
GET /metrics is public on the same daemon listener and does not require
readiness or the process capability. It accepts no body, query, conditional,
trace, or capability input. Scrapes are untraced and nonrecursive, use the
Prometheus 0.0.4 text format, and are capped at 256 KiB. HEAD /metrics
returns 405 with Allow: GET.
Logs, trace attributes, and metric labels use closed allowlists. They never contain message bytes, headers, identities, domains, selectors, recipients, client addresses, request/session/trace IDs, endpoints, DNS payloads, replay keys, protected paths or values, certificates, credentials, hashes, or raw errors. Debug modules add only documented bucket or result classes; they do not enable payload logging. Prometheus labels are fixed low-cardinality enums, and the registry deliberately omits standard process/runtime collectors.
Lifecycle And Recovery
Startup publishes readiness only after all selected owners and loops are live. The outer startup bound is 115 seconds, including a 100-second acquisition budget, ten-second reverse rollback budget, and five-second orchestration margin. Any ambiguous or incomplete startup fails without readiness.
Shutdown first withdraws readiness and closes admission, then joins the listener and serve loop, performs the configured graceful drain, and uses a bounded forced close when graceful drain or handler quiescence is not proven. Only after handlers join does it stop the replay health probe, cancel DNS, close replay, flush the instance telemetry provider within five seconds, and release protected material. If an accept or handler owner cannot be joined, the daemon reports failure and deliberately retains dependencies rather than tearing them down underneath live work.
The Redis store passes PING, the version floor, and the noeviction check
on every primary before readiness is published. A start-to-start health loop
then sends PING to every primary every replay.redis.health.interval
(1 to 60 seconds, default 5) with health.timeout; calls do not overlap.
health.failure_threshold consecutive failures, or a replay operation that
fails with a recoverable condition, withdraw readiness; the next successful
probe or operation restores it without a restart. Authentication, permission,
grammar, and internal contract failures are sticky until process restart.
Deliberately Unsupported
The current daemon does not provide:
- Milter or Exim action application;
- public HTTP exposure, proxy trust, Unix sockets, multiple listeners, or a plaintext private-network mode;
- OAuth, bearer tokens, request-selected policy, or remote authentication;
- HTTP/2, h2c, persistent connections, or effective-config output;
- hot configuration, secret, certificate, capability, or replay-key reload;
- replica reads, client-side caching, or global exactly-once replay claims (asynchronous replication and failover keep a documented loss window).
Verification
From the repository root:
make test
make vet
make lint
make race
make check-openapi
make check-vendor
make test-redis
make guardrails
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
app
Package app will compose the dkim2d runtime through dependency injection.
|
Package app will compose the dkim2d runtime through dependency injection. |
|
app/outcome
Package outcome owns transport-neutral daemon outcome vocabularies.
|
Package outcome owns transport-neutral daemon outcome vocabularies. |
|
command
Package command owns the dkim2d Cobra process surface and process exits.
|
Package command owns the dkim2d Cobra process surface and process exits. |
|
config
Package config will load, expand, validate, and expose dkim2d configuration.
|
Package config will load, expand, validate, and expose dkim2d configuration. |
|
datasource/ldap
Package ldap maps bounded LDAP records into storage-neutral datasets.
|
Package ldap maps bounded LDAP records into storage-neutral datasets. |
|
datasource/mysql
Package mysql implements the verified MySQL and MariaDB datasource adapter.
|
Package mysql implements the verified MySQL and MariaDB datasource adapter. |
|
datasource/runtime
Package runtime owns joined datasource and protected-registry generations.
|
Package runtime owns joined datasource and protected-registry generations. |
|
datasource/sqlsnapshot
Package sqlsnapshot maps fixed SQL rows into storage-neutral datasets.
|
Package sqlsnapshot maps fixed SQL rows into storage-neutral datasets. |
|
datasourceadmin
Package datasourceadmin owns provider-neutral offline datasource administration.
|
Package datasourceadmin owns provider-neutral offline datasource administration. |
|
dnstxt
Package dnstxt provides the daemon-owned TTL-aware DNS TXT transport.
|
Package dnstxt provides the daemon-owned TTL-aware DNS TXT transport. |
|
domainadmin
Package domainadmin owns the offline native-domain onboarding state machine.
|
Package domainadmin owns the offline native-domain onboarding state machine. |
|
domainruntime
Package domainruntime owns concrete one-shot offline domain administration construction.
|
Package domainruntime owns concrete one-shot offline domain administration construction. |
|
httpjson
Package httpjson will expose DKIM2 service operations over HTTP and JSON.
|
Package httpjson will expose DKIM2 service operations over HTTP and JSON. |
|
httpjson/generated
Package generated provides primitives to interact with the openapi HTTP API.
|
Package generated provides primitives to interact with the openapi HTTP API. |
|
migration
Package migration owns offline legacy OpenDKIM inventory and publication.
|
Package migration owns offline legacy OpenDKIM inventory and publication. |
|
observability
Package observability owns daemon-local structured logging, tracing, and metrics without defining protocol semantics.
|
Package observability owns daemon-local structured logging, tracing, and metrics without defining protocol semantics. |
|
propagationtest
Package propagationtest provides test-only fixtures for the daemon's received-DSN and propagation paths: the frozen library propagation corpus, a static public-key provider over its published keys, deterministic Ed25519 delivery-status profiles, and a tenant-keyed signing-authority double that reports local authority, resolves profiles, and signs.
|
Package propagationtest provides test-only fixtures for the daemon's received-DSN and propagation paths: the frozen library propagation corpus, a static public-key provider over its published keys, deterministic Ed25519 delivery-status profiles, and a tenant-keyed signing-authority double that reports local authority, resolves profiles, and signs. |
|
replay/redisgrammar
Package redisgrammar is the single authority for the syntactic rules of the Redis-compatible replay backend settings.
|
Package redisgrammar is the single authority for the syntactic rules of the Redis-compatible replay backend settings. |
|
replay/redisstore
Package redisstore implements the daemon-owned Redis-compatible replay-store provider for standalone, Sentinel, and cluster deployments.
|
Package redisstore implements the daemon-owned Redis-compatible replay-store provider for standalone, Sentinel, and cluster deployments. |
|
rotationruntime
Package rotationruntime owns the thin offline campaign-command runtime boundary.
|
Package rotationruntime owns the thin offline campaign-command runtime boundary. |
|
signingstore
Package signingstore owns descriptor-confined private signing generations for the daemon.
|
Package signingstore owns descriptor-confined private signing generations for the daemon. |
|
testsupport
Package testsupport owns shared test-only infrastructure.
|
Package testsupport owns shared test-only infrastructure. |