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 over the
9//! payload and whatever associated data is passed; `embark` passes the
10//! entry header, so its codec and claimed length are bound into the tag.
11//!
12//! [`gen_key_nonce`] draws a fresh key and nonce for one entry from the
13//! operating system generator, and [`xor32`] is the masking primitive behind
14//! the build-time key obfuscation that `embark-macros` emits.
15//!
16//! # What this crate does not promise
17//!
18//! Nothing here decides *where the key lives*, and that is what determines
19//! whether an embedded file is actually confidential. `embark`'s default
20//! mode reconstructs the key from material compiled into the binary, which
21//! is obfuscation against a casual reader and not security against anyone
22//! willing to reverse the binary. Real confidentiality needs a key supplied
23//! at runtime. See `embark::EncryptedFile` for that distinction.
24//!
25//! # Features
26//!
27//! `enc` compiles the build-time sealing half (and the OS key generator with
28//! it), `dec` the runtime opening half. `aes` adds AES-256-GCM alongside the
29//! always-present ChaCha20-Poly1305.
30
31// docs.rs builds with `--cfg docsrs` (see each manifest's
32// `[package.metadata.docs.rs]`), which turns this on and makes rustdoc label
33// every item with the feature that gates it. Nearly all of this API is
34// behind one, so without the label the rendered docs read as though it were
35// all unconditional. Inert on stable, where `docsrs` is never set.
36#![cfg_attr(docsrs, feature(doc_cfg))]
37#![cfg_attr(not(feature = "std"), no_std)]
38
39// Every cipher body sits behind `enc` or `dec`. With neither, these modules
40// would be dead code, so they are not compiled at all.
41#[cfg(any(feature = "enc", feature = "dec"))]
42mod aead;
43
44#[cfg(all(feature = "aes", any(feature = "enc", feature = "dec")))]
45mod aes;
46
47mod aead_trait;
48#[cfg(feature = "aes")]
49pub use aead_trait::Aes256Gcm;
50pub use aead_trait::{Aead, ChaCha20Poly1305};
51
52#[cfg(any(feature = "enc", feature = "dec"))]
53mod dispatch;
54#[cfg(feature = "dec")]
55pub use dispatch::open;
56#[cfg(feature = "enc")]
57pub use dispatch::seal;
58
59mod keygen;
60#[cfg(feature = "enc")]
61pub use keygen::gen_key_nonce;
62pub use keygen::xor32;
63
64/// A wrapper that wipes its contents on drop, from the `zeroize` crate.
65///
66/// Re-exported so a caller holding a key only for the length of one
67/// [`open`] call can keep it in one of these without naming `zeroize` in
68/// its own manifest. [`gen_key_nonce`] and [`xor32`] hand back plain arrays
69/// for the reasons their docs give; this is the wrapper to put those in.
70pub use zeroize::Zeroizing;