odf-crypto
LibreOffice-faithful ODF package encryption: detect it, decrypt it, write it.
odf-crypto reads and writes the encryption LibreOffice actually produces for
OpenDocument packages (.odt, .ods, .odp, …) — not an approximation of the
ODF specification, but the behaviour of the implementation that made the files.
Where the spec is ambiguous and LibreOffice picked an interpretation, this crate
follows LibreOffice.
That fidelity is the whole point. classify mirrors LibreOffice's package/
accept predicates, so a package this crate calls encrypted is one LibreOffice
would prompt for, and a package it refuses is one LibreOffice would refuse to
open.
Stable. This is
0.1.1;0.1.0was the first stable release. Its public API follows semantic versioning: a breaking change waits for0.2.0.
What it does
| What you have | Detect | Decrypt | Encrypt |
|---|---|---|---|
| AES-256-GCM + Argon2id — what current LibreOffice writes | ✅ | ✅ | ✅ |
| AES-CBC + PBKDF2 — older LibreOffice | ✅ | ✅ | ❌ |
| Blowfish-CFB + PBKDF2 — ODF 1.1 | ✅ | ✅ | ❌ |
| PGP-wrapped package | ✅ | ❌ | ❌ |
| Unencrypted package | ✅ | n/a | ✅ |
| Needs | the default build | crypto-ops |
crypto-ops |
Detection is the entire default build and links no cryptography at all; the cipher stack is opt-in. See Features.
Every operation streams. decrypt_to, encrypt_to and reencrypt_to read
from any Read + Seek and write to a writer, a chunk at a time within a
member, so a package of any size -- one with a 4 GiB video in it, say -- costs
the same few hundred KiB of heap as a small one. Measured, not estimated: peak
heap stays flat as the payload grows sixteenfold (see
How it's verified). The whole-buffer decrypt and
encrypt run the same code and return exactly what they did before.
reencrypt_to changes a password without the plaintext being written anywhere.
This crate reads three profiles and writes one. The grid above is what
decrypt accepts; encrypt always writes the first row, whatever the input
was. That asymmetry is an effort gap rather than a judgement — wholesome
Argon2id/AES-GCM is what current LibreOffice saves by default, so it is what a
new file should be, and nothing has yet needed a writer for the older two. If
you need one, say so on the tracker; the primitives are already here,
because decrypt uses them.
An effort gap in both rows, Blowfish included — which is worth saying,
because a 64-bit block cipher looks like something a writer ought to decline.
Current LibreOffice still writes BLOWFISH_CFB_8: objstor.cxx:356-362 sets
it, SHA-1 and PBKDF2 under the comment "the default values, that should be used
for ODF1.1 and older formats", and the write path admits exactly three ciphers
with Blowfish among them (ZipPackage.cxx:1875-1878). Pick ODF 1.1 as your save
format and that is what you get. A refusal here would refuse what the reference
implementation writes from its own Save dialog — and this crate takes its
definition of correct from that implementation, so it is not ours to declare.
The 64-bit block is a property of the cipher and a reason to weigh it, not a
reason for this crate to decide for you.
PGP-encrypted packages are detected and reported (Classification::pgp_keys) but
not decrypted — DecryptError::UnsupportedPgp. That one is not an effort
gap. decrypt(bytes, password) has no surface a private key could arrive
through: PGP unwrapping needs a keyring, an agent socket or a smartcard PIN, not
a password string, and an OpenPGP stack would dwarf the 25-crate default this
crate is built around. classify hands you the wrapped key material so a caller
who already has an OpenPGP implementation can do the unwrap.
Writing a profile is not the same as LibreOffice opening the result. Those are two claims, and the second is the one that matters to whoever has to read the file afterwards. It is evidenced separately — see How it's verified.
Install
[]
# Detection only — no cryptographic dependency.
= "0.1.1"
# Detection, reading and writing.
= { = "0.1.1", = ["crypto-ops"] }
Supported algorithms
Cipher (Cipher) |
KDF (Kdf) |
Start key (StartKeyAlg) |
Typical producer |
|---|---|---|---|
AesGcmW3c — AES-GCM |
Argon2id { t, m, p } |
Sha256 |
Current LibreOffice |
AesCbcW3c — AES-CBC |
Pbkdf2 { iterations, salt } |
Sha256 / Sha1 |
Legacy LibreOffice |
BlowfishCfb8 — Blowfish-CFB |
Pbkdf2 { iterations, salt } |
Sha1 |
Apache OpenOffice, older ODF |
Derived key length (128/192/256) is carried on EntryEncryption::derived_key_len.
Entry integrity is Checksum::Sha1_1K or Checksum::Sha256_1K over the first
1 KiB, matching LibreOffice.
On a SHA-1 row whose password fails, decrypt walks LibreOffice's legacy
retry ladder, as LibreOffice does: the StarOffice digest of the UTF-8 password,
a forced SHA-256, then the StarOffice digest of the MS-1252 password. The
StarOffice digest is rtl_digest_SHA1, a deliberately non-conforming SHA-1 that
LibreOffice keeps for compatibility (tdf#114939). Files from OpenOffice.org
1.x, StarOffice and LibreOffice before 3.5 need it. Since 0.1.0-rc.9:
earlier versions of this README claimed the ladder while decrypt tried only
the correct key.
Usage
Classify
classify answers whether the bytes are an ODF package, whether it is
encrypted, in which zip shape, and with which algorithm tuple.
use ;
Classification also carries package_encrypted (LibreOffice's
HasEncryptedEntries latch), has_non_encrypted_entries (its
HasNonEncryptedEntries), odf_version, media_type, and any PGP
encrypted-key material found in the manifest.
Decrypt
use decrypt;
DecryptError distinguishes the cases worth handling separately — WrongPassword,
NotEncrypted, EmptyPassword, Odf12Fatal and UnsupportedPgp among them —
so a caller can tell "bad password" from "we will not touch this package".
Stream it
The same three operations, from a reader to a writer, in bounded memory:
use File;
use ;
Nothing is written before the file has been accepted. An AES-GCM member is
read twice: the first pass checks its tag and decrypts nothing, the second
writes. An AES-CBC or Blowfish member is held back until its first 1 KiB matches
the manifest's checksum -- the only part LibreOffice checks either, which is
what IntegrityOutcome::PasswordCheckOnly tells you. On any error, discard
what the writer received: damage found late in a member follows output
already written.
reencrypt_to refuses an older per-entry file that holds listed content it does
not encrypt, or members its manifest does not list
(ReencryptError::PartiallyEncrypted, UnexpectedStreams): re-keying would seal
that plaintext under the new password's authentication. That is this crate's
policy, not LibreOffice's -- decrypt_to still opens such a file, as LibreOffice
does.
Encrypt
use encrypt;
Output is validated against a real LibreOffice: the repository carries a golden
(tests/goldens/lo-opens-our-encrypt-output.odt) and a UNO-driven checker
(tests/goldens/validate_encrypt.py) that bootstraps LibreOffice and confirms it
opens what this crate wrote.
Choosing the Argon2id cost
encrypt uses LibreOffice's (t=3, m=65536, p=4). That m is 64 MiB of
working memory per call, which some hardware cannot spend — and since the
parameters are stored in the file, a device that cannot afford 64 MiB to write
cannot afford it to read the document back either.
use ;
Argon2Params::new never refuses a tuple for being merely weak. Whose document
it is, and what its owner can afford to run, is not this crate's decision; it
reports the trade instead of overruling it.
When it does refuse, the error carries a typed ParamsReason naming whose rule
was broken, because those need different things from a caller:
| reason | means | what to tell a user |
|---|---|---|
OutOfRange |
a policy bound of this crate | the OpenDocument format permits this value; the library is stricter than the format |
CipherRejects |
argon2 cannot run it (m < 8p, or p above its MAX_P_COST) |
not a setting any library could relax |
The read side has the same shape. A package whose own settings decrypt will
not act on returns DecryptError::BadParameters(BadParameter): the setting, the
value the file declares, the range allowed, and whose rule it is
(OutOfRange for this crate's DecryptLimits or a format floor,
CipherRejects for argon2's or a cipher's own). It carries no text from the
file, so its numbers can be quoted in your own words.
The distinction is not cosmetic, and the Argon2 attributes make it sharp: they
are defined by LibreOffice's own extension schema
(OpenDocument-v1.4+libreoffice-manifest-schema.rng) and appear in no OASIS
schema at all, typed there as unbounded positiveInteger; LibreOffice then
validates the triple only as 0 < t && 0 < m && 0 < p. So the only authority
that defines them imposes no ceiling, and a tuple OutOfRange refuses may be
entirely legal and openable elsewhere. Reporting it as a format violation would
be false, and falsely authoritative.
Each reason carries an Argon2Axis (T / MKib / P) and the offending value
with its bounds — enums and integers, never interpolated text, so the payload
needs no sanitising before it reaches a user. Both types are #[non_exhaustive];
match with a _ arm.
The cost travels with the file, so it is not a local performance setting. A document written cheaply stays cheap to attack for every future reader, on any hardware.
LibreOffice honours whatever is written — checked in its source, not just
sampled. ManifestImport.cxx:257 validates the three attributes for positivity
and nothing else, ZipFile.cxx:184-186 passes the file's own values into
argon2_context, and :192 says why there is no range check there either:
"libargon2 validates all the arguments so don't need to do it here." What this
crate will write is a strict subset of what libargon2 accepts.
Command line
cli is not a default feature: a library consumer should not pay for an
argument parser or a terminal crate to link classify.
# Argon2id cost, for hardware that cannot spend 64 MiB. Each axis defaults
# independently, so this keeps LibreOffice's t=3 and p=4.
A tuple weaker than LibreOffice's prints a warning on stderr and still writes
the file — the cost is the caller's decision. A tuple argon2 cannot run
(m < 8p) is refused with exit 1, because that is a mistyped flag rather than a
damaged document.
$ odf-crypto classify report.odt
package: ODF
mode: wholesome
encrypted: yes
odf-version: 1.4
media-type: application/vnd.oasis.opendocument.text
cipher: AES-GCM (W3C)
kdf: Argon2id t=3 m=65536KiB p=4
start-key: SHA-256
checksum: none
key-size: 32
Passwords never come from the command line
There is deliberately no --password VALUE flag. argv is world-readable
in a process listing for the lifetime of the run — ps aux, or Task Manager's
command-line column. Four sources instead, exactly one per invocation:
| Flag | Source |
|---|---|
--password-env NAME |
that environment variable |
--password-file PATH |
first line of the file |
--password-stdin |
one line from stdin |
| (none) | non-echoing terminal prompt |
ODF_PW=...
|
Giving two sources is an error rather than a silent precedence win. With none of them and no terminal, the command fails telling you which flags exist instead of blocking on a prompt nobody can see.
rekey takes the old password from those flags and the new one from
--new-password-env NAME, --new-password-file PATH or a second prompt.
Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | usage error |
| 2 | I/O error |
| 3 | not an ODF package |
| 4 | wrong password |
| 5 | refused — not encrypted, already encrypted, PGP, one LibreOffice would not open, or a rekey that would seal plaintext |
| 6 | malformed or hostile package |
| 7 | internal invariant violated |
| 8 | this machine could not supply the memory -- the same file may work on a larger one |
| 130 | cancelled with Ctrl-C |
4 and 5 are the distinction that earns the table: 4 means try again, 5 means
you had the wrong file. An unencrypted package passed to classify is exit 0
with encrypted: no — an answer, not a failure.
Output files
With no -o, output lands beside the input as report.decrypted.odt,
report.encrypted.odt or report.rekeyed.odt. An existing file is never
overwritten without --force. Input and output both stream, so the only size
limit is the disk.
Output goes to a temporary file in the destination directory, given the
target's permissions before a byte is written, and is renamed over the target
only once the run succeeds. On any failure the temporary file is deleted --
a wrong password, a refusal, a damaged member found halfway through, a full
disk -- because for decrypt it holds plaintext. Ctrl-C cancels the run the
same way and exits 130; a second Ctrl-C deletes the file and exits at once,
since key derivation cannot be interrupted.
Known limit: a hard kill (kill -9, a power cut) can leave the temporary
.<name>.odf-crypto.tmp beside the target. Having the operating system delete
it would take a raw platform call, and this crate is unsafe_code = "forbid".
-o - writes to stdout: decrypt streams straight through; encrypt and
rekey, whose output must seek, go through a scratch file of ciphertext that is
removed afterwards.
Features
There are two builds, and no feature flag turns anything off — the default is simply the smaller one.
| Build | How | What you get |
|---|---|---|
| Detection-only | odf-crypto = "0.1.1" |
classify alone. No cryptographic dependency. 25 crates on Windows, 24 on Linux, 27 on macOS. |
| Full | features = ["crypto-ops"] |
classify, decrypt and encrypt. 64 crates on Windows, 63 on Linux, 66 on macOS. |
| CLI | features = ["cli"] |
The odf-crypto binary. Implies crypto-ops; adds clap, serde_json, rpassword for the prompt and ctrlc for a clean Ctrl-C. 76 crates on Windows, 78 on Linux, 82 on macOS. |
Detection is the default because it is cheap. classify parses
META-INF/manifest.xml and the zip central directory; it never derives a key or
touches a cipher. Enabling crypto-ops adds aes, ctr, ghash, cbc,
argon2, blowfish, pbkdf2, sha1, sha2, hmac and their transitive
graph. Nobody should pay for that to ask whether a file is encrypted.
The feature is named for what it gates, which is not only ciphers: pbkdf2 and
argon2 are KDFs, sha1/sha2 are hashes, hmac is a MAC, and miniz_oxide
is compression.
Reading and writing were once separate features. They are not any more: both
pulled an identical dependency graph, so the split cost a build configuration
and bought nothing a linker does not already do for a consumer that never calls
encrypt.
How it's verified
Fidelity to LibreOffice is this crate's only substantive claim, so the evidence for it ships with the crate rather than living in a CI log.
Seven goldens, every one real LibreOffice output. tests/goldens/*.odt were
produced by a local LibreOffice — check meta:generator: six read 26.2.1.2 and
lo-legacy-aes-cbc-image.odt reads 26.8.0.3 —
and they ship inside the published tarball, so the crate can verify its own
fidelity claim from the artifact a consumer actually downloads. That includes
aoo-blowfish-pbkdf2.odt, whose aoo- prefix names the ODF 1.1 Blowfish format
family rather than its producer; there is no Apache OpenOffice-produced evidence
here, so the corpus proves fidelity to LibreOffice and to the format, not
agreement between two independent writers.
Four ladder fixtures, LibreOffice-accepted rather than LibreOffice-written.
No LibreOffice that runs today writes the legacy start keys, so
tests/ladder/*.odt were synthesized from a golden, one per ladder rung plus a
control on no rung. A current LibreOffice opens the three rungs and refuses the
control. They ship too.
A round trip through LibreOffice, not merely through us.
lo-opens-our-encrypt-output.odt is what LibreOffice saved after being handed a
package this crate wrote. That is the difference between we can read what we
write and the reference implementation can.
A human opened the artifacts by double-click. The UNO harness that drives
LibreOffice is not the path a double-click takes — no password dialog, no
recovery prompt — so tests/artifacts/ exists to be opened by hand, with a
manifest naming the password and expected text for each. Recorded verdict:
2026-09-20, LibreOffice 26.2.1.2 on Windows 11 build 26200, all six prompted for
a password, accepted it, rendered the expected text, and raised no recovery bar.
That verdict outranks the harness.
Streaming is measured, not asserted. tests/streaming_memory.rs installs a
counting allocator and runs every operation at two payload sizes, sixteen times
apart: peak heap does not move. decrypt_to holds 171 KiB for a wholesome
package and 444 KiB for a per-entry one, encrypt_to 570 KiB, reencrypt_to
347 KiB and 949 KiB -- against a 4 MiB bound that holding a 256 MiB member
would pass sixty times over, which each guard was broken to confirm. The
whole-buffer decrypt is pinned to the exact bytes it returned before it moved
onto the streaming code, and LibreOffice 26.8.0.3 opens what decrypt_to,
encrypt_to and reencrypt_to write (tests/goldens/validate_decrypt_to.py,
validate_encrypted_outputs.py), refusing each with a wrong password. Re-run
for rc.15, which changed the bytes inside a per-entry decrypt_to output's
deflated members and the DEFLATE inside encrypt_to's payload.
322 tests, passing in every feature configuration — 231 library, 21 CLI unit, 41 CLI end-to-end, 2 memory-bound, 27 doctests. All three builds run in CI, not just the two that are cheap.
The examples below are among those doctests. Every ```rust block in this
file is compiled on each CI run, so an example naming an item that has since
moved fails the build instead of reaching you.
A 54-finding audit against LibreOffice source — 39 confirmed, 2 refuted, the rest narrowed. The record carries the upstream citation and a reproduction for each, including the two it could not substantiate.
Security
Key material zeroizes on drop. The password digest and every derived key are
held in secure-gate wrappers, which is
this crate's only zeroizing primitive; no bare Vec<u8> holds a key between
derivation and use. Plaintext crosses the public API as a plain Vec<u8> on
purpose — a wrapper in the signature would conscript an exact dependency version
on every consumer, and the caller receives the bytes either way.
The library does not abort your process. No panic!, unwrap or expect
on any non-test path — and, the part that is easy to miss, an allocation sized
from an untrusted manifest field goes through Vec::try_reserve_exact and
returns DecryptError::HostCannotAllocate rather than reaching
handle_alloc_error. That is not tidiness: an abort skips unwinding, so Drop
never runs, so the keys above are not wiped. One allocation site remains
outside this -- zip's central-directory preallocation -- named in the source
with the reason it stays open.
Plaintext in flight is wiped too. The streaming code moves plaintext only through fixed buffers that cannot grow and are zeroized on drop, so no reallocation leaves a copy behind. The one residue it cannot reach is miniz's compressor and decompressor state, which holds dictionary bytes and offers no way to wipe them; an application that must close that installs a zero-on-deallocate global allocator.
The file chooses what opening it costs. decrypt has to derive the key
before it can tell whether the password was even right, so a manifest's Argon2
and PBKDF2 parameters are acted on before anything about the file is trusted.
Measured: a 7 KiB package rewritten to ask for 8 GiB of Argon2 memory took 29
minutes to report a wrong password. So decrypt applies default ceilings —
chosen to refuse nothing any real producer writes — and decrypt_with_limits
lets a caller who knows their input raise them, up to DecryptLimits::PERMISSIVE.
Passwords never reach argv. There is deliberately no --password VALUE
flag; a process listing is world-readable. See
Passwords never come from the command line.
What this does not do. It will not tell you a password is weak. It cannot
distinguish a wrong password from tampered ciphertext — both surface as
WrongPassword, and on the AES-CBC and Blowfish profiles the checksum covers
only the first 1 KiB, so damage past that appears as an inflate failure instead.
And it is not a hardened implementation of the ciphers themselves: those are the
RustCrypto crates, and inherit their properties rather than this crate's.
MSRV
Rust 1.88, set by zip's own rust-version: 1.88 in 9.0.4 and 9.1.3 alike (1.85 through rc.10).
Sibling crate
msoffice-crypto does for
Microsoft Office what this crate does for OpenDocument — same method, same
author, different format family. The two READMEs share a section order so that
knowing one file tells you where to look in the other.
Acknowledgements
This crate is an independent implementation. Its behaviour was derived from the published OpenDocument format and from studying how existing implementations behave; no code was copied from either project below. They are credited because the work would have been substantially harder without them.
LibreOffice — MPL-2.0. The behavioural
reference throughout. This crate follows LibreOffice's package/ accept
predicates rather than a spec-literal reading, and the plan documents in docs/
cite specific upstream source locations for each decision so a disagreement
points at a paragraph rather than a guess. tests/goldens/sha1_star.py quotes a
short explanatory comment from LibreOffice's sal/rtl/digest.cxx when
documenting the rtl_digest_SHA1 quirk.
Horsmann/odfdecrypt — Apache-2.0.
Prior art covering the same problem in Python, and useful for confirming that a
reading of the format was not idiosyncratic. This crate's classification
deliberately diverges from it: classify follows LibreOffice's accept predicates,
not odfdecrypt's origin detector.
The .odt fixtures under tests/goldens/ were generated for this project.
License
Dual-licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual-licensed as above, without any additional terms or conditions.