55 lines
3.0 KiB
Markdown
55 lines
3.0 KiB
Markdown
# Secure secret storage
|
|
|
|
`crates/storage` owns the complete secret-storage contract. Configuration,
|
|
password-store repositories, Git configuration, command arguments, and logs
|
|
contain only opaque identifiers; passphrases, tokens, and HTTPS passwords are
|
|
stored by the operating system.
|
|
|
|
`SecretReference` has two validated forms. OpenPGP passphrases are keyed by the
|
|
primary fingerprint. HTTPS Git credentials are keyed by purpose, server ID,
|
|
application ID, and account. The account is kept inside the protected record,
|
|
so a configured server/application pair can retrieve it without adding an
|
|
account or secret value to TOML. References, locators, store state, and errors
|
|
all use redacted `Debug` output.
|
|
|
|
Stored values use a small versioned binary envelope containing their reference
|
|
and secret bytes. Retrieval validates the envelope and exact reference before
|
|
release. Malformed or ambiguous records produce a typed `Corrupted` error;
|
|
asking for another account at the same Git locator produces `Missing` without
|
|
altering the stored account. `create` refuses to overwrite, `replace` requires
|
|
an exact existing record, and missing, denied, cancelled, locked, corrupted,
|
|
unsupported-policy, and unavailable-store results remain distinct. Returned
|
|
and cached bytes use `SecretBytes`, which zeroizes its allocation when dropped.
|
|
|
|
## Operating-system adapters
|
|
|
|
The platform-selection code is isolated in
|
|
`crates/storage/src/secret_store/platform.rs` and calls only safe Rust APIs:
|
|
|
|
- macOS uses legacy Keychain for command-line-compatible device-unlocked
|
|
credentials and Protected Data for `RequireUserPresence`; iOS uses Protected
|
|
Data. User cancellation is mapped from the native Security Framework status.
|
|
- Windows uses Credential Manager. Store operations are serialized because the
|
|
upstream adapter documents unreliable same-entry sequencing across threads.
|
|
- Linux uses Secret Service through zbus with the Rust cryptography feature. It
|
|
does not launch `secret-tool`, a shell, or any other helper. A missing session
|
|
service is a typed `Unavailable` result.
|
|
|
|
IronStorage contains no direct platform FFI or unsafe Rust. The selected adapter
|
|
crates own their OS calls, so there is no project-local FFI safety contract
|
|
beyond providing validated UTF-8 identifiers and bounded byte slices.
|
|
|
|
## Locking and caching
|
|
|
|
A new store starts logically locked. `unlock` must succeed before create,
|
|
retrieve, replace, or delete; `lock` immediately clears all cached values even
|
|
if the platform lock operation reports an error. Caching is disabled unless a
|
|
caller explicitly selects `SecretCachePolicy::Timed`. Timed policies are capped
|
|
at 128 entries and 15 minutes, expire lazily, and are always cleared on lock.
|
|
|
|
The same unlocked store implements the OpenPGP `SecretProvider` and HTTPS Git
|
|
`GitCredentialProvider`. The CLI uses it for terminal `show` and embedded `git
|
|
fetch`, proving that protected keys and remote authentication are resolved only
|
|
through opaque references. Tests inject a memory backend and never access a
|
|
developer or CI user keyring.
|