embark_crypt/lib.rs
1//! The encryption layer of the `embark` toolkit: AEAD sealing and opening
2//! for embedded entries, keyed by the [`CryptoId`](embark_format::CryptoId)
3//! that `embark-format` writes into every entry header.
4//!
5//! [`seal`] and [`open`] dispatch on that id at runtime; [`ChaCha20Poly1305`]
6//! and, behind the `aes` feature, [`Aes256Gcm`] are the same two ciphers
7//! named as types, through the sealed [`Aead`] trait. Both take a 32-byte
8//! key and a 12-byte nonce and produce a detached 16-byte tag, and both are
9//! always used with empty associated data.
10//!
11//! [`gen_key_nonce`] draws a fresh key and nonce for one entry from the
12//! operating system generator, and [`xor32`] is the masking primitive behind
13//! the build-time key obfuscation that `embark-macros` emits.
14//!
15//! # What this crate does not promise
16//!
17//! Nothing here decides *where the key lives*, and that is what determines
18//! whether an embedded file is actually confidential. `embark`'s default
19//! mode reconstructs the key from material compiled into the binary, which
20//! is obfuscation against a casual reader and not security against anyone
21//! willing to reverse the binary. Real confidentiality needs a key supplied
22//! at runtime. See `embark::EncryptedFile` for that distinction.
23//!
24//! # Features
25//!
26//! `enc` compiles the build-time sealing half (and the OS key generator with
27//! it), `dec` the runtime opening half. `aes` adds AES-256-GCM alongside the
28//! always-present ChaCha20-Poly1305.
29
30// docs.rs builds with `--cfg docsrs` (see each manifest's
31// `[package.metadata.docs.rs]`), which turns this on and makes rustdoc label
32// every item with the feature that gates it. Nearly all of this API is
33// behind one, so without the label the rendered docs read as though it were
34// all unconditional. Inert on stable, where `docsrs` is never set.
35#![cfg_attr(docsrs, feature(doc_cfg))]
36#![cfg_attr(not(feature = "std"), no_std)]
37
38// Every cipher body sits behind `enc` or `dec`. With neither, these modules
39// would be dead code, so they are not compiled at all.
40#[cfg(any(feature = "enc", feature = "dec"))]
41mod aead;
42
43#[cfg(all(feature = "aes", any(feature = "enc", feature = "dec")))]
44mod aes;
45
46mod aead_trait;
47#[cfg(feature = "aes")]
48pub use aead_trait::Aes256Gcm;
49pub use aead_trait::{Aead, ChaCha20Poly1305};
50
51#[cfg(any(feature = "enc", feature = "dec"))]
52mod dispatch;
53#[cfg(feature = "dec")]
54pub use dispatch::open;
55#[cfg(feature = "enc")]
56pub use dispatch::seal;
57
58mod keygen;
59#[cfg(feature = "enc")]
60pub use keygen::gen_key_nonce;
61pub use keygen::xor32;