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
//! LibreOffice-faithful ODF package encryption detection, decryption and encryption.
//!
//! [`classify`] answers whether a file is an ODF package, whether it is encrypted,
//! in which zip-shape [`Mode`], and with which algorithm tuple. It follows
//! LibreOffice `package/` accept predicates, not the origin-detection approach of
//! [Horsmann/odfdecrypt](https://github.com/Horsmann/odfdecrypt).
//!
//! ```
//! use odf_crypto::{classify, Mode};
//!
//! let bytes = include_bytes!("../tests/goldens/lo-unencrypted.odt");
//! let class = classify(bytes)?;
//! assert_eq!(class.mode, Mode::Plain);
//! # Ok::<(), odf_crypto::DetectError>(())
//! ```
//!
//! Detection is the default build: [`classify`] needs no cryptographic
//! dependency. Everything past it is behind the `crypto-ops` feature.
//!
//! With `crypto-ops` enabled, [`decrypt`] turns an LO-encrypted package into the
//! plaintext ODF zip LibreOffice would open after a correct password. Packages
//! `classify` reports as `odf12_fatal` are refused: LO would not open them, so
//! neither does this crate.
//!
//! [`encrypt`] is the reverse: it turns a plaintext ([`Mode::Plain`]) ODF package
//! into what current LibreOffice writes for that input under a password.
//!
//! # Scope
//!
//! [`encrypt`] writes one profile: a single `encrypted-package` member, Argon2id
//! `t=3, m=65536, p=4`, AES-256-GCM, a SHA-256 start key, no checksum, and
//! `manifest:version="1.4"`. Per-entry writing and PGP wrapping are out of scope,
//! and the two are out for different reasons worth stating on the surface rather
//! than only in the plans:
//!
//! - **Per-entry write** is unbuilt, not impossible. `decrypt` reads AES-CBC and
//! Blowfish-CFB packages and this crate ships goldens of both, so the crate
//! can read three profiles and write one. That asymmetry is an effort gap.
//! - **PGP wrapping** cannot be expressed by this API at all: a private key does
//! not arrive through `password: &str`. See [`DecryptError::UnsupportedPgp`].
//!
//! The Argon2id cost is the one part of that profile a caller may change, with
//! [`encrypt_with_params`] and [`Argon2Params`] — `m=65536` is 64 MiB of working
//! memory per call, which some hardware cannot spend. A weaker tuple is accepted
//! rather than refused: the cost is the caller's decision, and this crate reports
//! it instead of overruling it. But it is stored *in the file*, so it binds every
//! future reader on every device, and real LibreOffice honours whatever is
//! written — verified against 26.2.1.2 down to `(1, 1024, 1)`.
//!
//! [`decrypt`] reads all three algorithm families LibreOffice and Apache
//! OpenOffice produce — AES-GCM + Argon2id, AES-CBC + PBKDF2, and Blowfish-CFB +
//! PBKDF2. PGP-wrapped packages are classified, and their wrapped material is
//! reported in [`Classification::pgp_keys`], but decryption refuses them.
//!
//! # Untrusted input
//!
//! Every bound a hostile package could push on is capped before any allocation
//! or key derivation: the manifest is read at most 8 MiB, at most 4096 complete
//! `encryption-data` rows get a KDF run, and `iteration-count`, Argon2
//! `t`/`m`/`p` and `key-size` each carry a floor and a ceiling. The whole-buffer
//! [`decrypt`] and [`encrypt`] also hold each inflated member and the input to
//! 1 GiB, because they hold them in memory; the streaming entry points do not,
//! and bound inflated output by [`DecryptLimits::max_output_bytes`] instead.
//!
//! # Streaming
//!
//! [`decrypt_to`], [`encrypt_to`] and [`reencrypt_to`] read from any
//! `Read + Seek` and write to a writer a chunk at a time, so peak memory does
//! not grow with the package. Nothing is written before a member has been
//! accepted -- an AES-GCM tag checked in a first pass, or an AES-CBC/Blowfish
//! member's checked first 1 KiB -- and on any error the writer's contents must
//! be discarded. The whole-buffer functions run the same code.
//!
//! At the API boundary: `password` is a `&str` and [`decrypt`] returns plaintext
//! as a plain `Vec<u8>`. Key material derived inside the crate is zeroized on
//! drop; the password you pass and the plaintext you receive are yours to wipe.
//!
//! # Stability
//!
//! Pre-1.0 — the API may change between releases. Requires Rust 1.88.
// Scoped to the one config where `decrypt`/`encrypt` genuinely are not compiled.
// doc_auto_cfg merged into doc_cfg in 1.92; docs.rs sets `docsrs` for us.
// A doc-only module: `//!` docs, no items, no runtime cost. Gated on
// `crypto-ops` because five of its six symptoms are about `decrypt` and
// `encrypt`, whose types do not exist in a detection-only build -- an
// intra-doc link to `DecryptError` there would not resolve. docs.rs builds
// `--all-features`, so it is on the published page regardless.
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
// Compiles every ```rust block in README.md, and renders none of it.
//
// `cfg(doctest)` is set only while rustdoc COLLECTS doctests, never while it
// BUILDS documentation -- so `cargo test --doc` checks the examples and no part
// of README.md reaches the rendered API pages. `cfg(test)` would be wrong: it is
// not set during collection, so the examples would never run.
//
// Precisely: the struct is absent from every page under `doc/odf_crypto/`, but
// the NAME appears once in `doc/src/odf_crypto/lib.rs.html`, because rustdoc's
// source viewer renders the file verbatim including items it compiled out. That
// is expected and harmless -- the README's prose is what must not escape, and it
// appears nowhere. So verify by grepping a README-only SENTENCE, not this
// identifier: grepping the identifier reports a correct setup as broken.
//
// Gated on `crypto-ops` because that is the smallest feature set under which
// all four examples compile: one needs only `classify`, the other three need
// `decrypt`, `encrypt` and `encrypt_with_params`. CI's `test (crypto-ops)` and
// `test (cli)` jobs both reach it, which matters -- an inert check reads
// exactly like a passing one.
//
// The examples are `no_run`: they are complete `fn main()` programs that read
// `document.odt`, so collecting them without running them is the point. A
// doctest that opens a file no machine has fails everywhere.
//
// A fence with NO language tag is Rust to rustdoc, and is not `no_run` --
// README.md:195's sample terminal output ran as a doctest and failed until it
// was tagged ```text. Tag every new fence; an untagged one is a live test.
//
// Proved by breaking it: `odf12_fatal` -> `odf12_fatl` in the README gave
// test src\lib.rs - ReadmeDoctests (line 180) - compile ... FAILED
// error[E0609]: no field `odf12_fatl` on type `Classification`
// which is the defect class this catches -- a README naming a field that moved.
;