Expand description
Persistent file-based credential storage.
This module provides atomic read/write of secret key material to a
configurable directory (secrets.path in config, or the systemd
credentials directory when running under systemd).
§Design
- Centralized directory resolution — callers use
credentials_dir()so all secret-bearing paths fail closed consistently. - Atomic writes — secrets are written via tempfile + rename so partial writes are never visible.
- Mode 0600 / 0700 — secret files and their parent directory are created with restrictive permissions on Unix.
- Read-only detection — when the secrets directory is not writable (e.g. the systemd credentials ramfs), missing secrets are a hard error rather than triggering key generation.
Structs§
- Bootstrap
Pubkey - One
bootstrap-pubkeysentry: the Ed25519 anchor plus an optional bound ML-DSA-65 verifying key. - Installed
Identity Backup - Paths of any prior key files displaced by an adopt, so the caller can report the backup(s).
- User
Identity Keys - A user’s client identity key material: the Ed25519 anchor plus an optional
bound ML-DSA-65 key (present under [
CryptoPolicy::Hybrid], absent underClassical). The fingerprint / kid is always the Ed25519 anchor’s — the PQ key is bound to it, never fingerprinted itself.
Enums§
- Secrets
Profile - Describes how a service’s credentials directory is scoped.
Constants§
- BOOTSTRAP_
PUBKEYS_ ENROLLMENT_ DIR - Directory sibling to
bootstrap-pubkeysholding the per-service chain-signed enrollment attestations (hyprstream#1562 H3):{service}.jsonper allowlisted service. - SECRETS_
PROFILE_ ENV - Explicit deployment signal for credential-directory layout.
- SERVICE_
PUBKEY_ HYBRID_ NAME - File name of the public hybrid (Ed25519 ‖ ML-DSA-65) sidecar written
alongside a service’s
signing-keyseed. - SIGNING_
KEY_ PUB_ NAME - File name of the public Ed25519 sidecar written alongside a service’s
signing-keyseed: the raw 32-byte verifying key.
Functions§
- credentials_
dir - Resolve the credentials/secrets directory via the unified config resolver.
- credentials_
dir_ for_ config - Resolve credentials from an already-loaded config handle.
- decode_
jwt_ exp_ raw - Decode the
expclaim from a JWT without signature verification. ReturnsNoneon any parse error (invalid base64, not JSON, missing exp). - ensure_
bootstrap_ pubkeys_ enrolled - Fail-closed enrollment check for OS-owned deployments (hyprstream#1562 H3).
- ensure_
bootstrap_ pubkeys_ hybrid - Reject a
bootstrap-pubkeysmap that still carries Ed25519-only service entries. - ensure_
service_ key_ sidecars - Write the public sidecars for a service signing key next to its seed:
- install_
user_ identity - Install adopted identity key material (the
--ssh/--keypath), backing up any displaced key files first. - install_
user_ signing_ key - Install
skas the client’s user-signing-key (the fileload_or_generate_user_signing_keyreads), backing up any existing key first. - is_
writable - Returns
trueifdirexists and is writable (or can be created). - load_
bootstrap_ pubkeys - Bootstrap pubkeys — the pubkeys of services needed before discovery is available.
- load_
bootstrap_ pubkeys_ hybrid - Load bootstrap pubkeys, preserving any bound post-quantum key material.
- load_
ca_ ml_ dsa_ verifying_ key - Load the CA’s derived ML-DSA-65 verifying key (public, distributed to all services).
- load_
ca_ signing_ key - Load the CA signing key (PolicyService only).
- load_
ca_ verifying_ key - Load the CA verifying key (public, distributed to all services).
- load_
existing_ service_ signing_ key - Load a provisioned service identity without ever generating a replacement.
- load_
or_ generate_ node_ signing_ key - Load or generate the Ed25519 node signing key (the root-of-trust key that identifies this Hyprstream instance).
- load_
or_ generate_ rsa_ key - Load or generate an RSA 2048 keypair for RS256 JWT signing.
- load_
or_ generate_ service_ signing_ key - load_
or_ generate_ tls_ materials - Load or generate TLS materials using the default secret names (
tls-key,tls-cert). - load_
or_ generate_ tls_ materials_ named - Load or generate TLS materials (ECDSA P-256 key + self-signed cert) using caller-specified secret names.
- load_
or_ generate_ user_ identity - Load (or, under
Hybrid, generate) the user’s identity key material for the given [CryptoPolicy]. - load_
or_ generate_ user_ signing_ key - Load or generate the user signing key (Ed25519).
- load_
service_ jwt - Load a service JWT from the shared-directory credential layout.
- load_
service_ jwt_ for_ profile - Load a service JWT using the active credential layout.
- node_
signing_ key_ mtime - Return the Unix mtime of
secrets_dir/signing-key, ornowif missing. Used to populate thenbffield in JWKS entries (key was valid since written). - read_
secret - Read a named secret from
dir. ReturnsNoneif the file does not exist. - resolve_
service_ signing_ key - Resolve the Ed25519 signing key a service process should use to sign its
own RPC responses in
--ipc(multi-process) deployment. - seed_
service_ jwt_ into_ trust_ store - Seed a provisioned service JWT under the key selected by startup.
- service_
signing_ key_ dir - The directory holding
service_name’s signing key undersecrets_dirfor the given profile. - validate_
service_ name - Per-service credential directory layout:
- write_
bootstrap_ pubkeys - Write bootstrap pubkeys to the credentials directory.
- write_
bootstrap_ pubkeys_ hybrid - Write bootstrap pubkeys, encoding hybrid entries in their concatenated form.
- write_
ca_ ml_ dsa_ verifying_ key - Write the CA’s derived ML-DSA-65 verifying key to the credentials directory.
- write_
ca_ signing_ key - Write the CA signing key to the credentials directory.
- write_
ca_ verifying_ key - Write the CA verifying key to the credentials directory.
- write_
public - Write a named public trust artifact to
diratomically (tempfile + rename). - write_
secret - Write a named secret to
diratomically (tempfile + rename). - write_
secret_ exclusive - Write a secret only if the file does not already exist (atomic O_EXCL).
- write_
service_ jwt - Write a service JWT to the shared-directory credential layout.
- write_
service_ jwt_ for_ profile - Persist a service JWT using the same profile-aware path startup reads.