Expand description
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.
use odf_crypto::{classify, Mode};
let bytes = include_bytes!("../tests/goldens/lo-unencrypted.odt");
let class = classify(bytes)?;
assert_eq!(class.mode, Mode::Plain);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.
decryptreads 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. SeeDecryptError::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.
Modules§
- troubleshooting
crypto-ops - Troubleshooting, organised by symptom.
Structs§
- Argon2
Params crypto-ops - Argon2id cost parameters for
encrypt_with_params. - Classification
- Result of
crate::classify. - Decrypt
Limits crypto-ops - Ceilings
decryptapplies to cost parameters a package chose. - Decrypt
Outcome crypto-ops - The result of a successful
decrypt_to. - Encrypted
Key - One
encrypted-keycollected by Stage A. - Entry
Encryption - One complete encryption-data tuple after Stage B.
Enums§
- Allocation
Site crypto-ops - Which allocation a
DecryptError::HostCannotAllocaterefers to. - Argon2
Axis crypto-ops - Which axis of an Argon2id tuple a
ParamsReasonis about. - BadParameter
crypto-ops - Why a package’s own encryption settings were refused, and whose rule they broke. Every field is an enum or an integer; nothing in it came from the file as text.
- Checksum
- Checksum on a complete row. GCM (and PGP+GCM) may omit it.
- Cipher
- LibreOffice
CipherID: three values. 128/192/256 survives only asEntryEncryption::derived_key_len(sal_Int32). - Decrypt
Error crypto-ops - Failures from
decrypt. - Detect
Error - Failures that stop
classifybefore aClassification. - Encrypt
Error crypto-ops - Failures from
encrypt. - Integrity
Outcome crypto-ops - What
decrypt_tocan say about the integrity of what it wrote. - Kdf
- Key-derivation function recorded on a complete row.
- Manifest
Field crypto-ops - Which manifest setting a
BadParameteris about. - Member
Fault crypto-ops - A member’s bytes disagree with its manifest row.
- Mode
- Zip-shape outcome. PGP is a
Kdf, not a mode. - Params
Reason crypto-ops - Why an
Argon2Paramstuple was refused — specifically, whose rule it broke. - Primitive
crypto-ops - The primitive whose own requirement a
BadParameter::CipherRejectsnames: not a bound of this crate’s, and not adjustable. - Reencrypt
Error crypto-ops - Failures from
reencrypt_to. - Start
KeyAlg - Start-key digest. Omitted
start-key-generationdefaults to SHA-1 on the password path. PGP clamps to SHA-256 (ZipPackage.cxx339).
Functions§
- classify
- Classify an ODF package’s encryption. Does not derive keys or decrypt.
- classify_
reader classify, reading the package fromreaderinstead of a slice.- decrypt
crypto-ops - Decrypt an LO-encrypted ODF package to the plaintext ODF zip LibreOffice would open after a correct password.
- decrypt_
to crypto-ops crate::decrypt, reading the package fromreaderand writing the plaintext package towriter, in bounded memory.- decrypt_
with_ limits crypto-ops decrypt, with the ceilings on what a package may ask for under the caller’s control. SeeDecryptLimits.- decrypt_
with_ limits_ to crypto-ops decrypt_to, with the ceilings on what a package may ask for under the caller’s control. SeeDecryptLimits.- encrypt
crypto-ops - Encrypt a plaintext ODF package with
password, producing what current LibreOffice writes for that input under that password. - encrypt_
to crypto-ops crate::encrypt, reading the plaintext package fromreaderand writing the encrypted package towriter, in bounded memory.- encrypt_
with_ params crypto-ops encryptwith the Argon2id cost chosen by the caller.- encrypt_
with_ params_ to crypto-ops encrypt_towith a caller-chosen Argon2id cost. Seecrate::encrypt_with_paramsfor what that trades.- reencrypt_
to crypto-ops - Decrypt
readerwitholdand write it towriterencrypted withnew, in bounded memory and with no plaintext written anywhere.