Skip to content

0010: External registry enrollment and transactional checkpoints

Date: 2026-10-20. Status: implemented software contract, pending owner protocol adoption and operational REGISTRY-ROOT approval. Implements W08 / #9. No existing experiment, transcript, policy or model result is reused as v1 evidence.

Decision

hallmark.enrollment implements the RFC-0002 records and actual Ed25519 signature verification. W08 needs this verification to reject an unsigned history; W09 retains snapshot authoring, immutable retained history and dual-authorized key transitions. There is no signing-key generation or operational authoring API here.

RegistryBody uses hallmark/registry/1 and H("registry", complete_body). Signatures cover u32be(len(tag)) || tag || canonical_body, where tag = "hallmark/v1/sign/registry". RegistrySignature and RegistryEntry are nested unversioned records. SignedRegistry, TrustPolicy and RegistryState use hallmark/signed-registry/1, hallmark/trust/1 and hallmark/registry-state/1, including when nested. Trust identity hashes the complete trust record. No new hash domain is introduced.

Signers must be distinct, externally authorized and individually valid, including any extra signature beyond the threshold. Duplicate trust identities and a threshold outside 1..key-count fail. A+B requires explicit hardware roots and measurements; B2 additionally requires A+B. Empty B1/B hardware lists are allowed. This checks the trust configuration, not hardware evidence.

enroll(snapshot, trust, state, now, *, history=()) has no default trust, clock or checkpoint. Its history contains every successor after the checkpoint and before the final snapshot, in sequence order. A direct successor needs no history; an equal-sequence snapshot must have the exact retained digest and empty history. Each link and signature is verified. Histories cannot exceed 1,024 intermediate records. New owner provisioning is needed beyond that cap.

Intermediate snapshots may have expired at the current clock; their signatures and links remain checked. All supplied issuance times must be nondecreasing and not in the future. The final snapshot must reach the trust minimum, satisfy issued_at <= now < expires_at, and have age no greater than max_age_seconds. The retained checkpoint alone contains no prior issuance time or entries, so it cannot establish first-link entry retention or time monotonicity against the checkpoint body. W09's retained authoring history covers that separate obligation.

Enrollment is a frozen process-local result with no public constructor or decoder. It is not a transferable credential; Python object access is not an isolation boundary. Re-enroll for each verification clock. admitted contains signed, nonretired identities: model/policy/backend identities intersect external allowlists; measurements intersect the external measurement list; classifier identities remain subject to resolution against the externally pinned Policy. Enrollment is possible when only some allowlisted alternatives are present. The full verifier must require each artifact actually used.

require_entry(kind, digest, issued_at=...) checks membership and valid_from <= receipt_issued_at < valid_until at the enrollment clock. Expired artifact validity does not erase historical validity. Retirement at or before the enrollment clock excludes an identity even for an older receipt. RegistryEntry.validate_time can report ARTIFACT_RETIRED separately; absence from the result reports TRUST_MISSING. No enrollment result establishes a valid receipt, classifier execution, hardware provenance, ZK proof or policy quality.

Persistence

hallmark.registry_store uses standard-library SQLite transactions instead of a handwritten temporary-file/rename protocol. provision_state exclusively creates a 0600 database from an external RegistryState. It refuses existing files. read_state and enroll_and_store never create missing databases. The database has an application ID and exactly one bounded canonical state record.

The update acquires an immediate write transaction, compares the caller's expected checkpoint, validates enrollment, writes and reads back the new record, and commits before returning the result. A stale caller or concurrent writer fails; busy retries are not implicit. Statement and commit failures roll back. Rollback-journal mode and synchronous=EXTRA request SQLite atomic commit under its documented filesystem and hardware assumptions. Tests include update rejection, deferred-constraint commit failure, suppressed updates and process exit before commit. These are not physical power-loss tests.

Use owner-controlled local POSIX storage with trustworthy locking and fsync. Final-path links, hard links, nonregular files, wrong ownership and modes other than 0600 are rejected. The parent directory and all ancestors are caller-trusted; this is not an untrusted-path resolver. Do not put the database in a bundle, network filesystem, shared writable directory or repository. OS account compromise, malicious replacement by the owner, disk corruption and rollback of the entire trusted storage are outside this local monotonicity claim. Keep an independent checkpoint backup. Failed initialization may leave an unusable file for inspection; it never overwrites a prior checkpoint.

Dependencies and bounds

The pre-install dependency review pins cryptography 50.0.2, cffi 2.1.1 and pycparser 3.11 with distribution hashes, published licence metadata and primary security-review sources. Ed25519 uses raw public keys and detached signatures. The fixtures use explicitly public, deterministic test seeds, never operational roots. Upstream-library selection and fixture verification are not owner approval for operational key custody.

Limits only lower 64 MiB total encoded registry/history bytes, 16 MiB per proof, 16 nesting levels, 60 seconds and a 2 GiB worker-memory ceiling. Enrollment checks encoded bytes, nesting and elapsed time between bounded cryptographic operations. It does not allocate a worker or enforce RSS/process termination; that remains the full verifier's worker obligation. Signature checks never fetch a network resource. The generic parser's item/byte limits still apply before enrollment.

Schemas and golden signed fixtures are in docs/schemas/*registry*-v1.json, docs/schemas/trust-v1.json and fixtures/wire/enrollment-v1.json. Existing v0 hashes and APIs are unchanged. A local hash chain detects divergent roots only when compared against retained checkpoints; it provides no global transparency or protection against a registry giving different relying parties different views.