msoffice-crypto
MS-OFFCRYPTO-faithful Microsoft Office encryption: detect it, decrypt it, write it.
Every encryption format the specification defines — OOXML and the 97-2003 binary documents alike — with key material that zeroizes on drop. What it writes is a subset of what it reads, and the table below says which.
Status: stable since 0.1.0. The public API follows semantic versioning: 0.1.x releases are compatible with each other, and a breaking change waits for 0.2.0. The badge above is the newest on the registry; the version this tree builds is the one in
Cargo.toml.
What it does
| Format | Detect | Decrypt | Encrypt | Needs |
|---|---|---|---|---|
| ECMA-376 Agile (Office 2010+) | ✅ | ✅ AES-128/192/256 × SHA-1/256/384/512 | ✅ the same set (SHA-1 at 128 only); default AES-256/SHA-512 | crypto-ops |
| ECMA-376 Standard (Office 2007) | ✅ | ✅ AES-128/192/256 | ✅ AES-128/192/256; default AES-128 | crypto-ops |
| RC4 CryptoAPI (Office XP–2003, and what Office 16 writes into a binary file) | ✅ | ✅ .doc .xls .ppt |
❌ | legacy-binary |
| Office 97/2000 RC4 (MD5) | ✅ | ✅ .doc .xls |
❌ | legacy-binary |
| XOR obfuscation (Method 1) | ✅ | ✅ .xls |
❌ | legacy-binary |
| Unencrypted OOXML or binary | ✅ | n/a | this is what encrypt takes in | (default) |
Writable is not the same as externally accepted. Every encrypt cell above is what this
crate emits. What other readers do with it is measured, not claimed: the default agile tuple
and standard AES-128 open in all four readers of the acceptance gate;
the rest are recorded reader by reader, cell by cell, in CHANGELOG.md.
The three ❌ are a refusal, not a backlog. RC4 and XOR obfuscation are broken by any modern standard — XOR is not encryption at all. Reading them is not optional: a 2026 Office build still writes RC4 CryptoAPI when you save as 97-2003, so these are current files, not museum pieces. Writing them is optional, and this crate declines — nothing obliges a writer to emit every format a specification defines, and emitting one would produce a newly weak document. See Security.
Out of scope, permanently: password recovery and cracking.
Why this one
Aimed at callers who handle documents they did not create — vaults, backup and archival tools, mail and upload gateways, DLP scanners, indexing pipelines that keep hitting files they cannot open.
- One API across detect, decrypt and encrypt.
office-cryptodecrypts but does not encrypt;ms-offcrypto-writerencrypts agile but does not decrypt;msoffcrypto-toolis Python andherumi/msofficeis C++. A complete picture otherwise means several dependencies with several postures toward the same key bytes. - Key material is wrapped. Those four all hold the spin hash, block keys and session key
in bare
Vec<u8>/std::string. This crate wraps them insecure-gate: zeroized on drop,[REDACTED]inDebug, reachable only inside awith_secretclosure, and comparable only in constant time — noPartialEqat all, so a verifier or HMAC cannot be compared with==by accident. Scope is honest: this is the key material this crate holds.SECURITY.mdsays which dependency state is wiped and which is not. - Detection costs nothing. What is this file, is it encrypted, how strongly is the
common case, and it pulls in no cryptography.
cargo tree --no-default-featuresis the claim. - It fails closed, and says which failure happened. The agile
dataIntegrityHMAC is computed over ciphertext, so it is checked before any plaintext is returned;IntegrityPolicy::Requireis the default andSkipcomes back labelled.WrongPassword,IntegrityCheckFailedandUnsupportedAlgorithmare three variants, because telling someone their password is wrong when the file was modified is actively misleading. - The claims are checkable rather than assertable. Fixtures ship with their generators,
so evidence is re-run rather than taken on faith. Where an encrypt path exists the bar is
that real Word opens what it wrote and that independent implementations recover the same
bytes — not that it round-trips against itself.
CHANGELOG.mdrecords what was run and what each reader answered, against the artifact's hash.
Install
[]
# Detection only — no cryptographic dependency.
= "0.1.0"
# Detection, decryption and encryption.
= { = "0.1.0", = ["crypto-ops"] }
The CLI is a separate install; see Command line.
Usage
Three builds, and you pay only for the one you take.
Detection is free. classify answers what a file is — container shape, encryption
family, the algorithm tuple it declares, whether it carries a dataIntegrity element — with
no cipher, hash, MAC, RNG or key-wrapping crate in the graph at all, a property CI asserts on
every push. It returns no Result and never panics: an unreadable file classifies as
Unknown, and a malformed one is never called unencrypted.
use ;
crypto-ops adds the ciphers, hashes, secure-gate and a CSPRNG:
use ;
That default is a default, not a limit. encrypt_ooxml_with_params takes an EncryptParams
— spin count, hash, and keyBits/saltSize for the package key and the password key
separately, as MS-OFFCRYPTO treats them — and validate() refuses only what the format or
AES actually forbids, saying which of the two it was:
use ;
Ten (hash, keyBits) combinations are writable: SHA-1 carries 128 only, because a key cannot
be longer than the digest it is derived from, and SHA-256/384/512 each carry all three.
EncryptParams::default() is byte-for-byte what encrypt_ooxml writes.
For a reader that predates agile encryption, encrypt_ooxml_standard writes the Office 2007
format — AES-ECB under a SHA-1-derived key, and no integrity element at all, so a
modified ciphertext decrypts silently to a modified document. It is named for the format so
that choosing it is a decision.
Large files stream. Each decrypt and encrypt function above has a _to form that
reads from an io::Read + Seek and writes to an io::Write, holding one 4096-byte segment
of the document at a time, so a package is never whole in memory; classify_from reads
only the headers. What does grow is cfb's sector
table, measured at 46 MiB for a 1 GiB file. A verified decrypt reads its input twice, and
checks the HMAC before releasing any plaintext. On any Err, discard what the writer
received:
use ;
use ;
The whole-buffer functions stop at 1 GiB; the streaming encrypt at 2 GiB less 16 bytes, the
most the container Office writes can hold. Both refuse with Error::PackageTooLarge.
legacy-binary is a superset of crypto-ops adding RC4 and MD5, and decrypts a
97-2003 document in place — the same CFB container with its encrypted streams replaced,
pictures and encrypted document properties included, which is what Word, Excel and
PowerPoint open. Nothing the password covers is left encrypted: content of a kind it does
not decrypt, and rights-managed (IRM) documents, are refused by name:
use ;
Command line
Behind the opt-in cli feature, so no library consumer builds an argument parser to ask
whether a file is encrypted.
cargo install msoffice-crypto --features cli
cargo install msoffice-crypto --features cli,legacy-binary # also opens 97-2003 files
classify cannot fail. An unencrypted package, sixteen bytes of junk and a container
this crate has never seen all exit 0, because all three are answers; only a file that cannot
be read exits 2. --json prints one object with the same key set for every input — an
unencrypted file carries key_data and password_key as null rather than dropping them,
so a script can index the result without checking first.
$ msoffice-crypto classify protected.docx
container: cfb
container-read: opened
document: ooxml-package
version: 4.4
family: agile
encrypted: yes
supported: yes
integrity: declared
key-cipher: AES key-hash: SHA-512 key-bits: 256
pw-cipher: AES pw-hash: SHA-512 pw-bits: 256
pw-spin: 100000
decrypt says what it verified. The output path is derived from the input unless -o
gives one, an existing file is never overwritten without --force, and the write is a
temporary file renamed over the target, so an interrupted run cannot leave a half-written
.docx that looks complete. Both commands stream: a .docx, .xlsx or .pptx passes
through a segment at a time, whatever its size, and a tampered one is refused before
anything is written. Only a 97-2003 document is read whole. On Linux and Windows the
temporary vanishes with the process, so even a killed decrypt leaves no plaintext behind. The integrity: line goes to stderr after every successful
decrypt — including after --integrity skip — so -o - into a pipe is unaffected and
nobody holds unauthenticated bytes without being told.
$ msoffice-crypto decrypt protected.docx --password-env MSOFFICE_CRYPTO_PASSWORD
msoffice-crypto: wrote protected.decrypted.docx
integrity: verified
--integrity takes require, require-where-defined, verify-if-present or skip; the
default is rendered from the library's own IntegrityPolicy::default() rather than typed
into the help text, because it has already moved once. A file with nothing to decrypt is
refused rather than copied, with exit 5.
encrypt defaults to --format agile. --format standard writes the Office 2007
format and says what that costs rather than leaving it to folklore:
$ msoffice-crypto encrypt report.docx --format standard --password-env MSOFFICE_CRYPTO_PASSWORD
msoffice-crypto: wrote report.encrypted.docx
integrity: not-applicable
msoffice-crypto: Office 2007 standard encryption defines no dataIntegrity element: a file modified after it was encrypted decrypts without complaint. `--format agile` writes one.
Passwords never come from argv
argv is world-readable in a process listing for the lifetime of the run — ps aux,
Task Manager. There is deliberately no --password VALUE flag, and adding one later would
be a regression rather than a feature. --password is registered hidden, so reaching for
it is answered with that reason instead of clap's generic "unexpected argument". Exactly one
source may be given; two is a usage error rather than a silent precedence win.
| Flag | Source | For |
|---|---|---|
--password-env NAME |
that environment variable | scripts, CI |
--password-file PATH |
first line, one trailing CR-LF or LF stripped | secret managers, /dev/stdin |
--password-stdin |
one line from stdin | pipelines |
| (none) | a non-echoing terminal prompt | interactive use |
--password-env takes the variable's name: naming it is the only way this tool reads it,
because a password that applies without being asked for is how the wrong file gets decrypted
in a loop.
Exit codes
A CLI that returns 1 for everything cannot be scripted.
| Code | Meaning | Maps from |
|---|---|---|
| 0 | success | — |
| 1 | usage error | bad flags, missing operand, two password sources, output exists without --force; also Error::EncryptParams, which no CLI flag can produce today |
| 2 | I/O error | unreadable input, unwritable output, Error::Io |
| 3 | not a Microsoft Office file | Error::NotACfbFile |
| 4 | wrong password | Error::WrongPassword |
| 5 | refused: nothing to do | decrypt of an unencrypted file, encrypt of an already-encrypted one, Error::NotEncrypted |
| 6 | malformed or hostile file | MissingStream, XmlParse, BadParameters, CipherError |
| 7 | internal invariant violated | RandomSource, InvariantViolated |
| 8 | integrity | IntegrityCheckFailed, IntegrityElementMissing, IntegrityUnavailable |
| 9 | unsupported encryption | UnsupportedEncryptionVersion, UnsupportedAlgorithm, UnsupportedEncryptedContent, Family::Unsupported, Family::Irm, a Word 6.0/95 or Excel 5.0/95 document, a legacy family without legacy-binary |
8 is not folded into 4 or 6, and 9 is not folded into 5, for the reason the library keeps
WrongPassword and IntegrityCheckFailed apart: at a process boundary the number is all a
script gets, and "try again", "this file was changed after it was encrypted" and "rebuild
with --features cli,legacy-binary" are three different next steps. One is a retry, one is a
support ticket, one is an incident.
Features
| Feature | Adds crypto? | Enables | Dependencies |
|---|---|---|---|
| (none — default) | no | classify, is_cfb_office |
cfb, quick-xml, thiserror — 13 crates |
crypto-ops |
yes | decrypt_ooxml, decrypt_ooxml_with_policy, encrypt_ooxml, encrypt_ooxml_with_params, encrypt_ooxml_standard, encrypt_ooxml_standard_with_key_bits, check_encryptable, EncryptParams, IntegrityPolicy / IntegrityOutcome |
+ aes, cbc, ecb, sha1, sha2, hmac, base64, rand, secure-gate — 36 crates |
legacy-binary |
superset of crypto-ops |
decrypt_binary_office |
+ rc4, md-5 — 38 crates |
cli |
via crypto-ops |
the msoffice-crypto binary |
+ clap, serde_json, rpassword/rtoolbox (Apache-2.0-only) — 49 crates |
Everything reachable from a library build is dual MIT/Apache-2.0 or more permissive.
rpassword and rtoolbox are Apache-2.0-only and arrive with the CLI's non-echoing
prompt under cli; CI fails if either reaches the default graph. It matters because this
crate is offered as MIT OR Apache-2.0 and the point of a dual offer is that you may take
either. deny.toml records the same finding beside the allow-list.
How it's verified
A round-trip through this crate's own decrypt proves only that it agrees with itself.
What it writes is held to four readers instead — two shipping products, two implementations
sharing no code with this one:
| Reader | Driver | Bar |
|---|---|---|
| Word / Excel / PowerPoint 16 | COM, tools/office_com_check.ps1 |
opens, content matches, wrong password refused for the password reason (0x800A1520) |
| LibreOffice 26.2 | UNO, tools/libreoffice_uno_check.py |
opens, content matches, wrong password refused by its verifier |
msoffcrypto-tool |
CLI, and the library for the HMAC | plaintext byte-identical; dataIntegrity verifies; wrong password refused |
office-crypto |
examples/office_crypto_check.rs |
plaintext byte-identical; wrong password does not yield it |
tools/acceptance_gate.py runs all four. The two implementations run in CI on every push
with two mutation runs beside them — --tamper, one flipped ciphertext bit, and
--corrupt-integrity — which must each produce GATE: FAIL, because a gate that cannot fail
is not a gate. The two applications need an interactive Windows desktop, so they are the
local gate, run before a change to the encrypt path merges and recorded in
CHANGELOG.md against the artifact's SHA-256.
That gate reads MSOFFICE_CRYPTO_ARTIFACT_DIR, and it must be set to a private
directory. Every cargo test writes the artifact under one fixed name, so a gate
pointed at shared system temp can measure whichever build wrote it last — which has
happened, and is why the evidence is recorded against a hash rather than a path.
Security
Report privately through Report a vulnerability on this repository's Security tab.
SECURITY.md is the policy, and its useful half is what does not count:
RC4 and XOR obfuscation are broken by any modern standard — XOR is not encryption at all.
They live behind the off-by-default legacy-binary feature so those files can be
read — including ones a current Office writes when you choose the 97-2003 format —
and nothing here writes them.
Two properties are enforced rather than claimed: no unsafe (#![forbid(unsafe_code)] at
the crate root, which also refuses an #[allow] override), and cargo deny over licences,
advisories, bans and sources on every push. The first thing that job found was a reachable
quadratic-time denial of service in this crate's XML parser — RUSTSEC-2026-0194,
remediated by the quick-xml floor in Cargo.toml.
MSRV
Rust 1.87, checked by a dedicated CI job rather than declared and hoped for. It was 1.85 until 0.1.0-rc.12, which took secure-gate 0.9.0-rc.16 and the 1.87 that release requires.
The newest releases of some dependencies need a newer compiler than this crate does: on
2026-11-14, aes 0.9.4 needs 1.89 and sha2 0.11.1 needs 1.88. On Rust 1.87, let Cargo's
MSRV-aware resolver choose (resolver = "3" in the workspace manifest, or
CARGO_RESOLVER_INCOMPATIBLE_RUST_VERSIONS=fallback in the environment), and it picks
the newest versions that build on 1.87.
Sibling crate
odf-crypto does for OpenDocument what this
crate does for Microsoft Office — same method, same author, different format family.
Compatibility: this crate tracks secure-gate 0.9.x, and no secure-gate type crosses
its public API — the password is &str and the plaintext is Vec<u8>, by design. A plan
to put its types on the boundary was withdrawn as a design error, so a consumer on a
different secure-gate range (0.8.x, say) resolves both side by side without conflict. Within
0.9.x the requirement here is a caret, "0.9", so a consumer that also depends on
secure-gate 0.9 directly shares one copy with this crate, whichever 0.9.x it names. Through
the release candidates the pin was exact, and such a consumer had to name the same rc.
Trademarks
Microsoft, Microsoft Office, Word, Excel and PowerPoint are trademarks of Microsoft Corporation. This project is not affiliated with, endorsed by, or sponsored by Microsoft. It is an independent implementation of the MS-OFFCRYPTO file formats — published by Microsoft under the Open Specification Promise, which is a patent promise and grants no trademark rights — and uses those names only to describe the formats it reads and writes.
Acknowledgements
None of this is legally required beyond what NOTICE records. It is here because
the work would have been substantially harder without them.
- herumi/msoffice (BSD-3, Cybozu Labs) — the
encryption reference;
resource.hppis the entire\x06DataSpacessubtree in four constants. - office-crypto (MIT) — the differential oracle in dev-dependencies, and the source the RC4 families and the Word 97 walk were ported from.
- ms-offcrypto-writer (MIT/Apache)
— proof that the
cfbcrate builds containers Office accepts. - msoffcrypto-tool (MIT) — fixtures and known-answer vectors that caught two real bugs in this crate's standard-encryption key derivation, and the source of the Excel 97 and PowerPoint 97 walks.
- LibreOffice (MPL-2.0) and excelize (BSD-3) — behavioural references, consulted and cited, never copied.
- cfb (MIT) — the container layer, so this crate does not hand-roll a third implementation of FAT chains and red-black directory trees.
The arc of the work is in
docs/plans/msoffice-crypto-foundation-2026-09-04.md
and the issues it indexes.
License
MIT OR Apache-2.0, at your option. See LICENSE-MIT,
LICENSE-APACHE and NOTICE.