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
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
use String;
use Vec;
use Zeroizing;
use ;
/// Type-state marker selecting [`EncryptedFile`]'s build-time
/// embedded-key mode -- the default, so plain `EncryptedFile` means
/// `EncryptedFile<EmbeddedKey>`. See the [type-level docs](EncryptedFile)
/// for what that means and its obfuscation-not-security caveat.
;
/// Type-state marker selecting [`EncryptedFile`]'s runtime-key mode. See
/// the [type-level docs](EncryptedFile) for what that means.
;
/// The set of [`EncryptedFile`] key modes: [`EmbeddedKey`] and
/// [`RuntimeKey`], and nothing else.
///
/// Sealed on purpose — the two modes differ in what an `EncryptedFile`
/// actually stores, which [`KeySource`](KeyMode::KeySource) names, and the
/// crate relies on that being exactly these two.
/// An encrypted, embedded file, produced by [`embed_crypt!`](crate::embed_crypt)
/// or `#[embark(encrypt)]`.
///
/// `embark` supports two distinct encryption modes, kept apart **at the
/// type level** by the `K` type parameter -- [`EmbeddedKey`] (the default)
/// or [`RuntimeKey`] -- so they cannot be confused. Each mode exposes only
/// the methods that make sense for it: calling the wrong decrypt method
/// for a handle's mode is a **compile error**, not a runtime panic.
///
/// - **`EncryptedFile<EmbeddedKey>`** (the default; plain `EncryptedFile`
/// means this) — built with
/// [`with_embedded_key`](EncryptedFile::with_embedded_key). The key is
/// generated at build time and reassembled at runtime by a
/// reconstruction function the macro generates **fresh for every build**:
/// a randomized, straight-line sequence of invertible byte operations
/// (XORs, additions, rotations, permutations, reversals) over scattered
/// key shares, different on each compile. [`decrypt`](EncryptedFile::decrypt)
/// / [`decrypt_str`](EncryptedFile::decrypt_str) call it to recover the
/// key; both are infallible by construction. This is
/// **obfuscation, not security**: the key ships inside the binary, and
/// anyone with the binary (a reverser, a disassembler, a memory dump) can
/// recover it and decrypt the payload. The per-build randomization only
/// raises the bar against casual static extraction — grepping the binary
/// for plaintext strings, or writing one generic extractor that works on
/// every `embark` binary — not against a determined attacker willing to
/// reverse an individual binary.
/// - **`EncryptedFile<RuntimeKey>`** (opt in with
/// `embed_crypt!(..., key = runtime)`) — built with
/// [`with_runtime_key`](EncryptedFile::with_runtime_key). No key is ever
/// embedded in the binary; the caller supplies the key at runtime via
/// [`decrypt_with`](EncryptedFile::decrypt_with), giving real
/// confidentiality (as strong as the caller's own key management).
/// There is no `decrypt()` on this mode: there is no embedded key to
/// decrypt with, so the method simply does not exist for this type
/// rather than failing at runtime. The handle stores nothing but the
/// sealed entry — the mode's [`KeySource`](KeyMode::KeySource) is `()`,
/// so there is no field key material could occupy.
///
/// Use the build-time mode for casual tamper-resistance (e.g. keeping a
/// default config out of a quick `strings` scan); use the runtime-key mode
/// whenever the embedded content actually needs to stay confidential.
///
/// # Examples
///
/// Build-time embedded key (the default). Note the plain `EncryptedFile`
/// type and the infallible `decrypt`:
///
/// ```
/// # #[cfg(all(feature = "derive", feature = "std"))] {
/// static SECRET: embark::EncryptedFile =
/// embark::embed_crypt!("examples/assets/secret.txt");
///
/// assert!(SECRET.decrypt_str().unwrap().starts_with("the launch codes"));
/// assert_eq!(SECRET.decrypt(), SECRET.decrypt_str().unwrap().as_bytes());
/// # }
/// ```
///
/// `embed_crypt!` takes `codec` and `cipher` as **bare identifiers**, never
/// as strings. (The `#[derive(Embed)]` attribute is the opposite: it takes
/// the string forms, shown below.)
///
/// ```
/// # #[cfg(all(feature = "derive", feature = "std"))] {
/// static SEALED: embark::EncryptedFile = embark::embed_crypt!(
/// "examples/assets/secret.txt",
/// codec = deflate,
/// cipher = chacha
/// );
/// assert!(SEALED.decrypt_str().unwrap().starts_with("the launch codes"));
///
/// // `cipher = aes` requires embark's `aes` feature; naming it without
/// // that feature is a build error, not a silent fallback.
/// # #[cfg(feature = "aes")] {
/// static AES: embark::EncryptedFile =
/// embark::embed_crypt!("examples/assets/secret.txt", cipher = aes);
/// assert_eq!(AES.decrypt(), SEALED.decrypt());
/// # }
/// # }
/// ```
///
/// The derive spells the same choices as strings, and seals every file in
/// the folder under one shared build-time key:
///
/// ```
/// # #[cfg(all(feature = "derive", feature = "std"))] {
/// use embark::Embed as _;
///
/// #[derive(embark::Embed)]
/// #[embark(folder = "examples/assets/docs", encrypt, cipher = "chacha")]
/// struct Secrets;
///
/// assert!(Secrets::get("license.txt").unwrap().data().starts_with(b"MIT"));
/// # }
/// ```
///
/// Runtime key. The binding must be explicitly typed
/// `EncryptedFile<RuntimeKey>`, and `decrypt_with` is the only way to open
/// it. This one is not run as a doctest: `key = runtime` reads the key from
/// the `EMBARK_KEY` environment variable at *build* time, so it cannot be
/// expanded from within a test that does not control the compiler's
/// environment.
///
/// ```ignore
/// // Built with EMBARK_KEY=<64 hex chars> in the environment.
/// static SEALED: embark::EncryptedFile<embark::RuntimeKey> =
/// embark::embed_crypt!("examples/assets/secret.txt", key = runtime);
///
/// let key: [u8; 32] = load_key_from_somewhere();
/// let plaintext = SEALED.decrypt_with(&key).unwrap();
/// ```
// The key field is deliberately left out. Under [`EmbeddedKey`] it is the
// address of the generated key-reconstruction routine, which is the one
// thing about this handle that should not end up in a log line, and the
// sealed entry is ciphertext nobody can read from a debug dump anyway.