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