nigig-org/REVIEWS/adr/0005-pdf-encryption.md

ADR 0005: PDF encryption — audited crates, decrypt-on-read, never write

• Status: Accepted
• Date: 2026-07-28
• Review item: Phase 8, DART_PDF_VS_MAKEPAD_PDF_GAP_ANALYSIS.md
• Supersedes: nothing
• Related: ADR 0003 (incremental save refuses encrypted documents)

Context

An encrypted PDF today does something worse than fail: it succeeds.

Probing a structurally valid RC4-encrypted file through the current parser:

parsed OK: pages=1
page 0 content bytes=44
  content parsed into 0 ops

No error, no warning. The document reports one page, the page reports content, and the content interprets to nothing because it is ciphertext. The user sees a blank page and is told the file is fine.

That is precisely the defect class Phase 0 existed to remove — an API claiming a capability it does not deliver — and it is the worst remaining example in the PDF stack, because it is silent.

The gap analysis lists Encryption (RC4/AES-128/256) with prerequisites "real crypto crates (ring, aes), byte-range tests". Phase 0 also explicitly deleted the previous hand-rolled MD5/SHA/AES/RC4 implementation, calling it a "CVE factory", and required that it be replaced with audited crates when signatures or encryption were actually needed. That time is now.

Decision

Implement the standard security handler (PDF 32000-1 §7.6) for reading, using audited RustCrypto crates, and never write encryption.

Dependencies

aes, cbc, rc4, md-5, sha2 — all RustCrypto, all MIT/Apache-2.0, which deny.toml already permits. No hand-rolled primitives: the repository has a standing rule against them and a documented history of getting it wrong.

These are added to pdf-cos only. The crate already parses untrusted bytes; adding decryption there keeps the trust boundary in one place rather than spreading key material through the document and graphics layers.

Supported

• V1/R2 — RC4 40-bit.
• V2/R3 — RC4 40–128-bit.
• V4/R4 — crypt filters selecting RC4 or AES-128 (/AESV2).
• V5/R6 — AES-256 (/AESV3), the SHA-256-based revision 6 algorithm.

Both the empty user password (the overwhelmingly common case: a document encrypted only to set permissions) and an explicitly supplied user or owner password.

Not supported, and refused rather than guessed

• Public-key security handlers (/Filter /Adobe.PubSec). Certificate handling is a separate problem.
• Any non-standard /Filter. A handler this code does not implement means the bytes cannot be trusted, so the document is refused.
• Writing encryption. ADR 0003 already refuses to save an encrypted document; this ADR keeps that refusal rather than relaxing it. Saving a decrypted document as plaintext would silently strip the protection its author applied, which is a security decision no library should make on a user's behalf.

Permissions are reported, not enforced

/P permission bits are parsed and exposed. They are not enforced by this crate, and the code says so. Permission bits are advisory in any reader that has already decrypted the content — enforcing them here would give a false impression of security while a caller can read the plaintext anyway. The honest position is to surface them and let the host decide.

Non-negotiable rules

1. No hand-rolled cryptography. Standing repository rule; Phase 0 deleted the previous attempt for cause.
2. A document whose handler is unsupported is refused, never partially decrypted. A blank page is what the current bug produces and is exactly what must not happen.
3. A wrong password is a typed error, distinguishable from a corrupt file, so a caller can prompt again rather than reporting damage.
4. Decryption is per object. The key is derived once; each string and stream is decrypted with its own object and generation number, as the spec requires. Reusing one keystream across objects is a real break.
5. The /Encrypt dictionary itself is never decrypted, and neither are the strings inside it. Doing so corrupts the key derivation.
6. Saving stays refused. ADR 0003's SaveError::Encrypted remains.

Merge criteria

• An RC4-encrypted document with an empty user password opens and its content stream decrypts to real operators.
• An AES-128 (/AESV2) document opens likewise.
• An AES-256 (/R 6) document opens likewise.
• A wrong password returns WrongPassword, not a corrupt-file error.
• An unsupported handler returns UnsupportedHandler naming it.
• Strings as well as streams are decrypted.
• Permission bits are parsed and exposed.
• Corpus fixtures for each of the above, generated by the checked-in script.
• Malformed encrypted fixtures never panic.
• Saving an encrypted document is still refused.
• TEST_TARGET=pdf ./tools/test-rust-clean.sh passes, rustfmt and clippy -D warnings clean.

All criteria met as of the follow-up commit that added the AES-256 and malformed-encryption fixtures. The original encryption commit shipped with the revision 6 code path unit-tested but never run against a real file, which is the gap that follow-up closed.

Consequences

Positive. The silent-blank-page bug is gone. A large class of real-world documents — anything encrypted merely to set print permissions — becomes readable. The crypto dependency is confined to one crate behind one module.

Negative. Five new dependencies in a crate that previously had one. They are audited and permissively licensed, but they are still supply chain.

Risk. The likeliest defect is a key-derivation error that happens to produce plausible output for one algorithm and garbage for another. The mitigation is a fixture per algorithm whose decrypted content is asserted to contain known operators, rather than merely asserting that parsing returned Ok.