Skip to main content

Module trust_ceremony

Module trust_ceremony 

Source
Expand description

Deployment-trust ceremony automation for the setup wizard.

Node bootstrap (directories, node root key, per-service keypairs, CA-signed service JWTs) and deployment trust are separate concerns and stay separate: this module is opt-in and additive. Nothing here runs unless the operator asks for the ceremony.

What it adds is the decision an operator would otherwise make by reading [docs/deployment-trust-ceremony.md]: is a hardware token attached, does its firmware confine an Ed25519 key to the token, and — when nothing is attached — is the operator willing to accept a software root that is only fit for development.

Hardware access sits behind TokenDetector and AgeYubikeyPlugin so the decision logic can be exercised without a token. The decision logic itself is pure: plan_ceremony, select_mode_for_token, validate_break_glass and ceremony_commands take values and return values.

Structs§

CeremonyInputs
Every value the four trust invocations need.
CeremonyModeRecord
Machine-readable record of which mode ran, written beside the artifacts.
CeremonyPaths
Absolute paths of every ceremony input and output.
CeremonyRequest
Everything the plan depends on that does not come from the token itself.
DetectedToken
A token the detector reported as attached.
FirmwareVersion
A three-part YubiKey firmware version.
SystemAgeYubikeyPlugin
Drives age-plugin-yubikey, which needs a real TTY for PIN entry.
SystemTokenDetector
Enumerates tokens with ykman list.

Enums§

BreakGlass
The recovery half of the root recipient ring.
CeremonyMode
How the deployment root will be protected.
CeremonyPlan
What the wizard decided to do about deployment trust.
DetectionError
Why the wizard could not learn whether a token is attached.
IdentityFileKind
What a candidate break-glass identity file actually is.
PlaintextPolicy
Whether an unprotected break-glass is tolerable for the root being minted.
UnlockIdentity
The identity that unlocks the authority bundle during the delegation step.

Constants§

CEREMONY_MODE_SCHEMA
Schema of the mode record written beside the ceremony artifacts.
DEFAULT_PIV_SLOT
PIV digital-signature slot: PIN is demanded for every signature.
DEV_GRADE_LABEL
Human-visible grade of a software root. Deliberately shouty.
PIV_ED25519_MIN_FIRMWARE
First firmware generation that can hold an Ed25519 key in a PIV slot.

Traits§

AgeYubikeyPlugin
Creates and exports the PIV-backed age identity on an attached token.
TokenDetector
Enumerates attached hardware tokens.

Functions§

ceremony_commands
Build the ceremony as the exact sequence of trust commands it runs.
classify_identity_file
Classify a candidate break-glass file without decrypting it.
create_ceremony_dir
Create the ceremony directory, owner-only.
generate_passphrase_encrypted_identity
Generate a passphrase-encrypted break-glass identity, returning its recipient.
generate_software_identity
Generate a native age identity at out, returning its recipient.
missing_tools
Names from required_tools that probe reports as absent.
mode_record
Summarise a completed selection for the emitted record.
parse_age_keygen_recipient
Pull the public recipient out of age-keygen output.
parse_age_plugin_recipient
Pull the age1yubikey1… recipient out of age-plugin-yubikey output.
parse_ykman_list
Parse ykman list output.
plan_ceremony
Decide what to do, given a detection result.
required_tools
External programs a mode needs on PATH.
select_mode_for_token
Resolve a chosen token to a mode, or block when no human can drive it.
tool_on_path
True when tool resolves through PATH.
validate_break_glass
Reject a recipient ring that would leave the root weaker than it looks.
write_registry_public_key
Write the raw 32-byte registry-service public key the JWT mint binds to.