odf-crypto 0.1.1

LibreOffice-faithful encryption for ODF packages (.odt, .ods, .odp): detect it, decrypt it, write it
Documentation
//! 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.
#![cfg_attr(not(feature = "crypto-ops"), allow(rustdoc::broken_intra_doc_links))]
// doc_auto_cfg merged into doc_cfg in 1.92; docs.rs sets `docsrs` for us.
#![cfg_attr(docsrs, feature(doc_cfg))]

mod classify;
mod io_latch;
mod limits;
mod manifest;
mod types;
mod uris;
mod zip_err;
mod zip_tree;

#[cfg(test)]
mod test_support;

#[cfg(feature = "crypto-ops")]
mod bad_parameter;
#[cfg(feature = "crypto-ops")]
mod decrypt;
#[cfg(feature = "crypto-ops")]
mod decrypt_entries;
#[cfg(feature = "crypto-ops")]
mod decrypt_stream;
#[cfg(feature = "crypto-ops")]
mod encrypt;
#[cfg(feature = "crypto-ops")]
mod encrypt_stream;
#[cfg(feature = "crypto-ops")]
mod kdf;
#[cfg(feature = "crypto-ops")]
mod ms1252;
#[cfg(feature = "crypto-ops")]
mod reencrypt;
#[cfg(feature = "crypto-ops")]
mod sensitive;
#[cfg(feature = "crypto-ops")]
mod stream;
#[cfg(feature = "crypto-ops")]
mod zip_stream;

// 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.
#[cfg(feature = "crypto-ops")]
#[cfg_attr(docsrs, doc(cfg(feature = "crypto-ops")))]
pub mod troubleshooting;

pub use classify::{classify, classify_reader};
pub use types::{
    Checksum, Cipher, Classification, DetectError, EncryptedKey, EntryEncryption, Kdf, Mode,
    StartKeyAlg,
};

#[cfg(feature = "crypto-ops")]
pub use bad_parameter::{BadParameter, ManifestField, MemberFault, Primitive};
#[cfg(feature = "crypto-ops")]
pub use decrypt::{decrypt, decrypt_with_limits, AllocationSite, DecryptError, DecryptLimits};
#[cfg(feature = "crypto-ops")]
pub use decrypt_stream::{decrypt_to, decrypt_with_limits_to, DecryptOutcome, IntegrityOutcome};
#[cfg(feature = "crypto-ops")]
pub use encrypt::{
    encrypt, encrypt_with_params, Argon2Axis, Argon2Params, EncryptError, ParamsReason,
};
#[cfg(feature = "crypto-ops")]
pub use encrypt_stream::{encrypt_to, encrypt_with_params_to};
#[cfg(feature = "crypto-ops")]
pub use reencrypt::{reencrypt_to, ReencryptError};

// 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.
#[cfg(all(doctest, feature = "crypto-ops"))]
#[doc = include_str!("../README.md")]
pub struct ReadmeDoctests;