Skip to main content

Crate odf_crypto

Crate odf_crypto 

Source
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. 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.

Modules§

troubleshootingcrypto-ops
Troubleshooting, organised by symptom.

Structs§

Argon2Paramscrypto-ops
Argon2id cost parameters for encrypt_with_params.
Classification
Result of crate::classify.
DecryptLimitscrypto-ops
Ceilings decrypt applies to cost parameters a package chose.
DecryptOutcomecrypto-ops
The result of a successful decrypt_to.
EncryptedKey
One encrypted-key collected by Stage A.
EntryEncryption
One complete encryption-data tuple after Stage B.

Enums§

AllocationSitecrypto-ops
Which allocation a DecryptError::HostCannotAllocate refers to.
Argon2Axiscrypto-ops
Which axis of an Argon2id tuple a ParamsReason is about.
BadParametercrypto-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 as EntryEncryption::derived_key_len (sal_Int32).
DecryptErrorcrypto-ops
Failures from decrypt.
DetectError
Failures that stop classify before a Classification.
EncryptErrorcrypto-ops
Failures from encrypt.
IntegrityOutcomecrypto-ops
What decrypt_to can say about the integrity of what it wrote.
Kdf
Key-derivation function recorded on a complete row.
ManifestFieldcrypto-ops
Which manifest setting a BadParameter is about.
MemberFaultcrypto-ops
A member’s bytes disagree with its manifest row.
Mode
Zip-shape outcome. PGP is a Kdf, not a mode.
ParamsReasoncrypto-ops
Why an Argon2Params tuple was refused — specifically, whose rule it broke.
Primitivecrypto-ops
The primitive whose own requirement a BadParameter::CipherRejects names: not a bound of this crate’s, and not adjustable.
ReencryptErrorcrypto-ops
Failures from reencrypt_to.
StartKeyAlg
Start-key digest. Omitted start-key-generation defaults to SHA-1 on the password path. PGP clamps to SHA-256 (ZipPackage.cxx 339).

Functions§

classify
Classify an ODF package’s encryption. Does not derive keys or decrypt.
classify_reader
classify, reading the package from reader instead of a slice.
decryptcrypto-ops
Decrypt an LO-encrypted ODF package to the plaintext ODF zip LibreOffice would open after a correct password.
decrypt_tocrypto-ops
crate::decrypt, reading the package from reader and writing the plaintext package to writer, in bounded memory.
decrypt_with_limitscrypto-ops
decrypt, with the ceilings on what a package may ask for under the caller’s control. See DecryptLimits.
decrypt_with_limits_tocrypto-ops
decrypt_to, with the ceilings on what a package may ask for under the caller’s control. See DecryptLimits.
encryptcrypto-ops
Encrypt a plaintext ODF package with password, producing what current LibreOffice writes for that input under that password.
encrypt_tocrypto-ops
crate::encrypt, reading the plaintext package from reader and writing the encrypted package to writer, in bounded memory.
encrypt_with_paramscrypto-ops
encrypt with the Argon2id cost chosen by the caller.
encrypt_with_params_tocrypto-ops
encrypt_to with a caller-chosen Argon2id cost. See crate::encrypt_with_params for what that trades.
reencrypt_tocrypto-ops
Decrypt reader with old and write it to writer encrypted with new, in bounded memory and with no plaintext written anywhere.