dkim2d

command module
v0.0.0-...-89e479d Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 6, 2026 License: Apache-2.0 Imports: 2 Imported by: 0

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:

  • strict accepts PASS, rejects FAIL and PERMERROR, and temporarily defers TEMPERROR;
  • permissive accepts FAIL and PERMERROR for rollout compatibility while preserving temporary deferral for TEMPERROR; and
  • testing returns non-terminal continue for every coherent verification state so the daemon can report results without controlling delivery; when reporting is enabled, the response still carries the exact daemon-owned Authentication-Results action.

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, or server.batch_revision.max_aggregate_message_bytes (DKIM2D_SERVER_BATCH_REVISION_MAX_AGGREGATE_MESSAGE_BYTES, at least server.message_bytes, at most 536,870,912). Each message still obeys server.message_bytes.
  • max_request_bytes, the JSON body: by default the shared single-message ceiling 2 * 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.

  • reject keeps the fail-closed behavior: the operation answers permerror/reject and the Postfix DSN adapter refuses the bounce.
  • continue answers bodyless HTTP 204 with X-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.

  • reject keeps the fail-closed behavior: a sign request with smtp.mail_from <> is an invalid contract (HTTP 400) before any datastore access, whether or not it carries a declaration.
  • header_from admits a null reverse path only when the request also carries null_sender: header_from and its context.domain equals 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 the originator profile for that tenant and domain as for any other sender (an absent or inactive profile answers 204) and signs mf=<> with rt= 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 a DKIM2-Signature or Message-Instance field, or whose top-level Content-Type is multipart/report with report-type=delivery-status (or is repeated or unparsable), is refused as an invalid contract: delivery-status notifications are signed only on POST /v1/dsn/sign. The declaration is refused with a non-null reverse path, and /v1/revise and 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 250 reply, 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.generation value;
  • is mode 0500 and 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

Documentation

Overview

Package main provides the dkim2d process entry point.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL