asimov_keyring/lib.rs
1// This is free and unencumbered software released into the public domain.
2
3//! Keyring support for ASIMOV.
4//!
5//! Public keys are read from `$HOME/.asimov/keyring/<user>` without accessing
6//! the secret-key backend. The backend is opened only to initialize a missing
7//! identity or perform an explicit secret-key operation.
8//!
9//! On Linux, the default backend uses private files when access to the kernel
10//! keyrings is unavailable, including under Docker's default seccomp policy.
11//! No environment configuration is needed. Once the file store exists, it is
12//! reused even if kernel keyrings later become available, preserving identity.
13//! Other platforms default to their native backend.
14//!
15//! File secrets are stored in `$HOME/.asimov/.keyring/<user>/secret` as
16//! unencrypted key bytes, protected by directory mode 0700 and file mode 0600.
17//! Mount the user's `.asimov` directory on persistent storage to retain the
18//! identity across container recreation. Like the native keyring's public-key
19//! cache, this path uses the home directory, not `ASIMOV_ROOT`.
20//!
21//! `ASIMOV_KEYRING_BACKEND=native` forces the platform backend without fallback;
22//! `ASIMOV_KEYRING_BACKEND=file` forces file storage on Unix. Native and file
23//! secrets are separate; initializing an empty backend creates a new identity.
24//! Automatic fallback only handles unavailable kernel-keyring access on opening;
25//! subsequent secret-read, corruption, and write errors are returned as errors.
26
27#![no_std]
28#![forbid(unsafe_code)]
29#![cfg_attr(docsrs, feature(doc_cfg))]
30
31extern crate alloc;
32
33#[cfg(feature = "std")]
34extern crate std;
35
36#[cfg(feature = "std")]
37mod keyring;
38#[cfg(feature = "std")]
39pub use keyring::*;
40
41#[cfg(feature = "std")]
42mod store;
43
44#[cfg(all(feature = "std", unix))]
45mod file_store;
46
47mod keyring_error;
48pub use keyring_error::*;