Module identity 

Node identity: load or generate a persistent ed25519 SecretKey.

The key is stored as 32 raw bytes at <data_dir>/node.secret. On Unix the temp file is opened with mode 0600 from creation (no umask-window where the key material is world-readable) and atomically renamed into place.

On Unix, permissions are validated on every load to block key-replacement attacks: data_dir must be a directory with no group or world permission bits (e.g. 0o700), and node.secret must be a regular file with no group or world permission bits (e.g. 0o600). Setuid/setgid/sticky bits are not inspected. A world- or group-writable data_dir would let any local process replace node.secret between load and use. On first run the directory is created with 0o700 via DirBuilder::mode (no umask window). Non-Unix platforms skip these checks — POSIX mode bits do not map meaningfully to NTFS ACLs.

New keys are built via SecretKey::generate, which draws from the auto-seeded thread-local CSPRNG backed by OS entropy.

Structs

LoadedKey

A node key from load_or_create, and whether that call created it.

StagedNodeKey

A freshly-generated node key written to a temp file in data_dir, not yet committed to node.secret.

Functions

ensure_data_dir

Validate (or create+validate) data_dir with 0o700 semantics: if it exists, the permission policy is enforced; if it’s NotFound, it’s created securely and then validated. Other stat errors propagate.

fresh_secret_key

A newly generated node secret key, drawn from the OS RNG. The caller owns persisting it; nothing here touches disk.

install_staged

Install the staged temp file tmp at target, archiving any existing target first. Shared commit primitive for the staged-key types (StagedNodeKey and decdn_incentive’s StagedKeystore) so their archive → rename → fail-safe-rollback logic stays in one place.

key_path

Location of the persistent node key within data_dir.

load

Load the node’s SecretKey from disk without generating one when it is absent — the read-only counterpart of load_or_generate, used by decdn whoami to report the existing identity without minting a new key.

load_or_create

Load the node’s SecretKey from disk, generating and persisting one if absent, and report which of the two happened.

load_or_generate

Load the node’s SecretKey from disk, generating and persisting one if absent.

move_aside

Rename path to <filename>.bak.<unix_ts> so an in-place key rotation preserves the prior key material rather than destroying it. Required by appendix-operator-key-rotation.md §1 step 9 (“Archive the old iroh keystore offline. Retain it for at least MAX_EVIDENCE_AGE_US”) and the §5 rollback path (“Repoint config at old keystore”). The operator can later move the .bak file offline; deleting it is up to them.

stage_node_key

Generate a fresh node key and write it to a temp file in data_dir (mode 0o600 on Unix) without touching node.secret. Validates or securely creates data_dir with the same 0o700 semantics as load_or_create.