Skip to main content

Module identity_store

Module identity_store 

Source
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§

BootstrapPubkey
One bootstrap-pubkeys entry: the Ed25519 anchor plus an optional bound ML-DSA-65 verifying key.
InstalledIdentityBackup
Paths of any prior key files displaced by an adopt, so the caller can report the backup(s).
UserIdentityKeys
A user’s client identity key material: the Ed25519 anchor plus an optional bound ML-DSA-65 key (present under [CryptoPolicy::Hybrid], absent under Classical). The fingerprint / kid is always the Ed25519 anchor’s — the PQ key is bound to it, never fingerprinted itself.

Enums§

SecretsProfile
Describes how a service’s credentials directory is scoped.

Constants§

BOOTSTRAP_PUBKEYS_ENROLLMENT_DIR
Directory sibling to bootstrap-pubkeys holding the per-service chain-signed enrollment attestations (hyprstream#1562 H3): {service}.json per 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-key seed.
SIGNING_KEY_PUB_NAME
File name of the public Ed25519 sidecar written alongside a service’s signing-key seed: 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 exp claim from a JWT without signature verification. Returns None on 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-pubkeys map 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/--key path), backing up any displaced key files first.
install_user_signing_key
Install sk as the client’s user-signing-key (the file load_or_generate_user_signing_key reads), backing up any existing key first.
is_writable
Returns true if dir exists 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, or now if missing. Used to populate the nbf field in JWKS entries (key was valid since written).
read_secret
Read a named secret from dir. Returns None if 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 under secrets_dir for 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 dir atomically (tempfile + rename).
write_secret
Write a named secret to dir atomically (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.