krypton_core/
lib.rs

1//! # krypton
2//!
3//! Encrypted vaults and single-file encryption with full metadata
4//! protection, built on AES-256-GCM and Argon2id.
5//!
6//! ## Highlights
7//!
8//! * **Authenticated encryption** — every byte of ciphertext is covered by a
9//!   GCM tag; headers are bound through key derivation and AAD.
10//! * **Memory-hard key derivation** — Argon2id (64 MiB, t=4) with parameters
11//!   stored inside each container so they can evolve without breaking old
12//!   files.
13//! * **Per-object subkeys** — HKDF-SHA256 derives an independent content key
14//!   per file; deterministic counter nonces eliminate random-nonce collision
15//!   risk on large files.
16//! * **Streaming** — 64 KiB chunks with constant memory use for files of any
17//!   size.
18//! * **Metadata privacy** — original filenames never appear unencrypted,
19//!   neither in `.krf` containers nor inside vaults.
20//! * **Crash safety** — vault configs, manifests and outputs are written via
21//!   temp file + rename; interrupted operations never leave half-written
22//!   plaintext or bricked containers.
23//! * **Hardened memory** — keys live in [`zeroize::Zeroizing`] buffers and
24//!   are scrubbed on drop.
25//!
26//! ## Quick start
27//!
28//! ```no_run
29//! use std::path::Path;
30//!
31//! // Single file round trip.
32//! let out = krypton::encrypt_file("correct horse", Path::new("document.pdf"), None).unwrap();
33//! let name = krypton::decrypt_file("correct horse", &out, Path::new("restored.pdf")).unwrap();
34//! assert_eq!(name, "document.pdf");
35//!
36//! // Multi-file vault.
37//! let mut vault = krypton::Vault::new("myvault".into());
38//! vault.init("correct horse").unwrap();
39//! vault.unlock("correct horse").unwrap();
40//! vault.add(Path::new("secret.pdf"), None).unwrap();
41//! for e in vault.list().unwrap() {
42//!     println!("{} ({} bytes)", e.name, e.size);
43//! }
44//! vault.lock();
45//! ```
46//!
47//! ## Choosing an API
48//!
49//! * **One file in, one file out?** Use [`encrypt_file`] / [`decrypt_file`].
50//!   The container is self-contained: it carries the KDF parameters and the
51//!   original filename inside the encryption boundary.
52//! * **Many files with one password?** Use [`Vault`]. Entries keep their
53//!   names encrypted, whole directory trees can be stored and restored, and
54//!   the password can be changed later without re-encrypting data.
55//! * **Building blocks only?** The [`crypto`] module exposes the AEAD, key
56//!   type and derivation functions used internally.
57//!
58//! ## Error handling
59//!
60//! All fallible operations return [`Result`] with a small [`Error`] enum.
61//! Wrong passwords and tampered ciphertext deliberately map to the same
62//! [`Error::Authentication`] variant so error messages never leak which one
63//! occurred:
64//!
65//!
66//! ```
67//! use krypton::{decrypt_file, Error};
68//! use std::path::Path;
69//!
70//! match decrypt_file("pw", Path::new("backup.krf"), Path::new("out.bin")) {
71//!     Ok(original_name) => println!("restored {original_name}"),
72//!     Err(Error::Authentication) => eprintln!("wrong password or corrupted data"),
73//!     Err(e) => eprintln!("failed: {e}"),
74//! }
75//! ```
76//!
77//! ## Security model
78//!
79//! See `SECURITY.md` in the repository for the full write-up including
80//! threat model and known limitations. In short: confidentiality and
81//! integrity against attackers with read/write access to the stored files,
82//! as long as the password remains secret. The tool does not hide file sizes
83//! beyond filename padding, does not provide plausible deniability, and — as
84//! with all password-based encryption — security ultimately rests on password
85//! strength.
86
87#![forbid(unsafe_code)]
88#![deny(missing_docs)]
89#![deny(rustdoc::broken_intra_doc_links)]
90
91/// Universal encrypted container format shared by all objects.
92pub(crate) mod container;
93/// Cryptographic primitives: keys, AEAD, KDF.
94pub mod crypto;
95/// Error types.
96pub mod error;
97mod fsutil;
98/// Argon2id parameter types.
99pub mod kdf;
100/// Entry-name validation helpers.
101pub mod sanitize;
102/// Single-file `.krf` containers.
103mod single_file;
104/// Chunked streaming encryption engine.
105mod stream;
106/// Multi-file encrypted vaults.
107pub mod vault;
108
109/// Convenience re-exports covering everyday use.
110pub mod prelude {
111    pub use crate::crypto::Key;
112    pub use crate::error::{Error, Result};
113    pub use crate::single_file::{decrypt_file, encrypt_file};
114    pub use crate::vault::{EntryInfo, IntegrityReport, Vault};
115}
116
117pub use error::{Error, Result};
118pub use single_file::{decrypt_file, encrypt_file};
119pub use vault::{EntryInfo, IntegrityReport, Vault};
120
121/// Crate version, handy for CLI `--version` output.
122pub const VERSION: &str = env!("CARGO_PKG_VERSION");
krypton_core/lib.rs

krypton_core/
lib.rs
