pdfboss_core/

crypt.rs

//! Decryption for the Standard security handler (ISO 32000 §7.6), opened
//! with the user or the owner password (the empty user password opens
//! transparently).
//!
//! Handles RC4 (`/V` 1–2, `/R` 2–3, 40–128-bit), AESV2 (`/V` 4, 128-bit
//! AES-CBC) and AESV3 (`/V` 5, `/R` 5–6, 256-bit AES-CBC). Documents whose
//! password the caller does not supply are reported as encrypted. The
//! primitives — MD5, RC4, AES and the SHA-2 family — are implemented here from
//! their published specifications so the crate needs no cryptographic
//! dependency.
//!
//! This is low-level API: [`crate::Document`] applies it automatically when
//! opening an encrypted file, and most callers never name [`Decryptor`]
//! directly. It is public for code that drives object reads itself, as the
//! asynchronous API does.
//!
//! [`Encryptor`] is the write side, AES-256 (`/V` 5, `/R` 6) only: it builds
//! the complete `/Encrypt` dictionary and encrypts an object's strings and
//! stream data in place, the exact inverse of [`Decryptor::decrypt_object`].

use crate::object::{Dict, Name, Object};

/// Password padding string (ISO 32000 §7.6.3.3, Algorithm 2, step (a)).
const PAD: [u8; 32] = [
    0x28, 0xBF, 0x4E, 0x5E, 0x4E, 0x75, 0x8A, 0x41, 0x64, 0x00, 0x4E, 0x56, 0xFF, 0xFA, 0x01, 0x08,
    0x2E, 0x2E, 0x00, 0xB6, 0xD0, 0x68, 0x3E, 0x80, 0x2F, 0x0C, 0xA9, 0xFE, 0x64, 0x53, 0x69, 0x7A,
];

/// Which cipher a configured [`Decryptor`] applies to strings and streams.
#[derive(Clone, Copy, PartialEq)]
enum Cipher {
    /// RC4 stream cipher, per-object key (V1/V2, and V4 with `/CFM /V2`).
    Rc4,
    /// AES-128-CBC, per-object key with the `sAlT` suffix (V4, `/CFM /AESV2`).
    Aesv2,
    /// AES-256-CBC, the file key applied directly (V5, `/CFM /AESV3`).
    Aesv3,
}

/// A configured Standard-handler decryptor for an opened document.
#[derive(Clone)]
pub struct Decryptor {
    /// The file key (`n` bytes for RC4/AESV2, 32 for AESV3).
    key: Vec<u8>,
    cipher: Cipher,
    /// The `/Encrypt` dictionary's `/EncryptMetadata` value (default true
    /// when absent): when false, a stream whose own dictionary says
    /// `/Type /Metadata` was stored in plaintext and must not be decrypted.
    encrypt_metadata: bool,
}

/// The `/Encrypt` dictionary's `/EncryptMetadata` flag, true when absent
/// (ISO 32000-2 §7.6.4.2, Table 20).
fn encrypt_metadata_flag(enc: &Dict) -> bool {
    enc.get("EncryptMetadata")
        .and_then(Object::as_bool)
        .unwrap_or(true)
}

impl Decryptor {
    /// Builds a decryptor from the resolved `/Encrypt` dictionary and the first
    /// `/ID` element, assuming the empty user password. Returns `None` when the
    /// handler or its parameters are unsupported, or the empty password does
    /// not open the file (so the caller can report it as unsupported).
    ///
    /// This is low-level: [`crate::Document`] configures decryption itself, and
    /// a caller only reaches for this when driving object reads directly — as
    /// the asynchronous API does.
    ///
    /// ```
    /// use pdfboss_core::{Decryptor, Dict};
    ///
    /// // An empty dictionary names no handler, so there is nothing to build.
    /// assert!(Decryptor::from_standard(&Dict::default(), &[]).is_none());
    /// ```
    pub fn from_standard(enc: &Dict, id0: &[u8]) -> Option<Decryptor> {
        Decryptor::from_standard_with_password(enc, id0, b"")
    }

    /// [`Decryptor::from_standard_with_password`] for a text password: the
    /// UTF-8 bytes are tried first and, when they differ and every char
    /// fits, the Latin-1 bytes as well — the legacy revisions hash raw
    /// bytes without naming an encoding, and real files use both.
    pub fn from_standard_with_password_str(
        enc: &Dict,
        id0: &[u8],
        password: &str,
    ) -> Option<Decryptor> {
        let dec = Decryptor::from_standard_with_password(enc, id0, password.as_bytes());
        if dec.is_some() || password.is_ascii() || password.chars().any(|c| (c as u32) > 255) {
            return dec;
        }
        let latin1: Vec<u8> = password.chars().map(|c| c as u8).collect();
        Decryptor::from_standard_with_password(enc, id0, &latin1)
    }

    /// [`Decryptor::from_standard`] with a caller-supplied password, tried
    /// first as the user password and then as the owner password (which
    /// recovers the user-level key, ISO 32000 §7.6.3.4 Algorithm 7 for the
    /// RC4/AES-128 revisions, §7.6.4.3.3 for AES-256). `None` when the
    /// password opens nothing.
    pub fn from_standard_with_password(
        enc: &Dict,
        id0: &[u8],
        password: &[u8],
    ) -> Option<Decryptor> {
        if enc.get_name("Filter").map(|n| n.0.as_str()) != Some("Standard") {
            return None;
        }
        let v = enc.get_int("V").unwrap_or(0);
        let r = enc.get_int("R").unwrap_or(0);
        let encrypt_metadata = encrypt_metadata_flag(enc);
        match (v, r) {
            // RC4: V1 (40-bit) and V2 (up to 128-bit).
            (1 | 2, 2 | 3) => {
                let n = if v == 1 {
                    5
                } else {
                    (enc.get_int("Length").unwrap_or(40) / 8).clamp(5, 16) as usize
                };
                let key = rc4_family_key(enc, id0, r, n, password)?;
                Some(Decryptor {
                    key,
                    cipher: Cipher::Rc4,
                    encrypt_metadata,
                })
            }
            // V4: 128-bit key, cipher chosen by the standard crypt filter.
            (4, 4) => {
                let key = rc4_family_key(enc, id0, r, 16, password)?;
                let cipher = match crypt_filter_method(enc)?.as_str() {
                    "AESV2" => Cipher::Aesv2,
                    "V2" => Cipher::Rc4,
                    _ => return None, // Identity or unknown
                };
                Some(Decryptor {
                    key,
                    cipher,
                    encrypt_metadata,
                })
            }
            // V5: AES-256 with SHA-2-based key derivation.
            (5, 5 | 6) => aesv3_key(enc, r, password).map(|key| Decryptor {
                key,
                cipher: Cipher::Aesv3,
                encrypt_metadata,
            }),
            _ => None,
        }
    }

    /// Decrypts one indirect object's strings and stream data in place. Objects
    /// extracted from object streams are already plaintext and must not be
    /// passed here.
    ///
    /// Low-level, like [`Decryptor::from_standard`]: [`crate::Document`] applies
    /// this itself as it loads objects, and a caller only reaches for it when
    /// driving object reads directly — as the asynchronous API does.
    ///
    /// ```
    /// use pdfboss_core::{Decryptor, Object};
    ///
    /// // Reachable from outside the crate; exercising it needs an encrypted
    /// // document, so this only pins the signature and the visibility.
    /// let apply: fn(&Decryptor, &mut Object, u32, u16) = Decryptor::decrypt_object;
    /// let _ = apply;
    /// ```
    pub fn decrypt_object(&self, obj: &mut Object, num: u32, gen: u16) {
        let key = match self.cipher {
            Cipher::Aesv3 => self.key.clone(), // one file key for every object
            Cipher::Rc4 | Cipher::Aesv2 => self.object_key(num, gen),
        };
        decrypt_in_place(obj, &key, self.cipher, self.encrypt_metadata);
    }

    /// Per-object key: `MD5(filekey ++ num[0..3] ++ gen[0..2] [++ "sAlT"])`
    /// truncated to `min(n + 5, 16)` bytes (ISO 32000 §7.6.2, Algorithm 1). The
    /// `sAlT` suffix is added for AES crypt filters.
    fn object_key(&self, num: u32, gen: u16) -> Vec<u8> {
        let mut input = Vec::with_capacity(self.key.len() + 9);
        input.extend_from_slice(&self.key);
        input.extend_from_slice(&num.to_le_bytes()[..3]);
        input.extend_from_slice(&gen.to_le_bytes()[..2]);
        if self.cipher == Cipher::Aesv2 {
            input.extend_from_slice(b"sAlT");
        }
        let digest = md5(&input);
        let n = (self.key.len() + 5).min(16);
        digest[..n].to_vec()
    }
}

/// Recursively decrypts every string and stream body reachable from `obj` with
/// the per-object `key` under `cipher`. When `encrypt_metadata` is false, a
/// stream whose own dictionary says `/Type /Metadata` was stored in
/// plaintext (ISO 32000-2 §7.6.4.2, Table 20) and its data is left alone;
/// the dictionary's own values still walk normally.
fn decrypt_in_place(obj: &mut Object, key: &[u8], cipher: Cipher, encrypt_metadata: bool) {
    match obj {
        Object::String(bytes) => *bytes = decrypt_bytes(cipher, key, bytes),
        Object::Array(items) => items
            .iter_mut()
            .for_each(|it| decrypt_in_place(it, key, cipher, encrypt_metadata)),
        Object::Dict(dict) => dict
            .values_mut()
            .for_each(|v| decrypt_in_place(v, key, cipher, encrypt_metadata)),
        Object::Stream(stream) => {
            stream
                .dict
                .values_mut()
                .for_each(|v| decrypt_in_place(v, key, cipher, encrypt_metadata));
            if !encrypt_metadata && is_metadata_stream(&stream.dict) {
                return;
            }
            stream.data = decrypt_bytes(cipher, key, &stream.data);
        }
        _ => {}
    }
}

/// Whether `dict` names `/Type /Metadata`.
fn is_metadata_stream(dict: &Dict) -> bool {
    dict.get_name("Type").map(|n| n.0.as_str()) == Some("Metadata")
}

/// Applies `cipher` to one string or stream body with the given `key`.
fn decrypt_bytes(cipher: Cipher, key: &[u8], data: &[u8]) -> Vec<u8> {
    match cipher {
        Cipher::Rc4 => rc4(key, data),
        Cipher::Aesv2 | Cipher::Aesv3 => aes_cbc_decrypt(key, data),
    }
}

/// The Standard stream crypt filter's method (`/CF` → `/StmF` → `/CFM`):
/// `V2`, `AESV2`, or `Identity`.
fn crypt_filter_method(enc: &Dict) -> Option<String> {
    let stmf = enc
        .get_name("StmF")
        .map(|n| n.0.as_str())
        .unwrap_or("StdCF");
    let filter = enc.get_dict("CF")?.get_dict(stmf)?;
    Some(filter.get_name("CFM")?.0.clone())
}

/// Pads or truncates a password to the 32 bytes every legacy algorithm
/// hashes (ISO 32000 §7.6.3.3, Algorithm 2 step (a)). The empty password
/// pads to [`PAD`] itself.
fn pad_password(password: &[u8]) -> [u8; 32] {
    let mut out = [0u8; 32];
    let n = password.len().min(32);
    out[..n].copy_from_slice(&password[..n]);
    out[n..].copy_from_slice(&PAD[..32 - n]);
    out
}

/// The RC4/AESV2 file key `password` actually opens: tried as the user
/// password (Algorithm 2 + the `/U` check), then as the owner password
/// (Algorithm 7: the owner key decrypts `/O` back into the padded user
/// password, which must then verify like any user password).
fn rc4_family_key(enc: &Dict, id0: &[u8], r: i64, n: usize, password: &[u8]) -> Option<Vec<u8>> {
    let u = enc.get("U").and_then(Object::as_str_bytes)?;
    if let Some(key) = md5_file_key(enc, id0, r, n, &pad_password(password)) {
        if verify_user_password(&key, r, id0, u) {
            return Some(key);
        }
    }
    // Owner attempt. The owner key comes from the owner password alone
    // (Algorithm 3 steps (a)-(d)); what it decrypts out of `/O` is the
    // padded user password, ready for Algorithm 2 verbatim.
    let o = enc.get("O").and_then(Object::as_str_bytes)?;
    if o.len() < 32 {
        return None;
    }
    let mut d = md5(&pad_password(password));
    if r >= 3 {
        for _ in 0..50 {
            d = md5(&d[..n]);
        }
    }
    let okey = &d[..n];
    let recovered = if r == 2 {
        rc4(okey, &o[..32])
    } else {
        let mut x = o[..32].to_vec();
        for i in (1u8..=19).rev() {
            let keyed: Vec<u8> = okey.iter().map(|b| b ^ i).collect();
            x = rc4(&keyed, &x);
        }
        rc4(okey, &x)
    };
    let padded: [u8; 32] = recovered.get(..32)?.try_into().ok()?;
    let key = md5_file_key(enc, id0, r, n, &padded)?;
    verify_user_password(&key, r, id0, u).then_some(key)
}

/// Algorithm 2: derive the RC4/AESV2 file key from a padded user password.
fn md5_file_key(enc: &Dict, id0: &[u8], r: i64, n: usize, padded: &[u8; 32]) -> Option<Vec<u8>> {
    let o = enc.get("O").and_then(Object::as_str_bytes)?;
    if o.len() < 32 {
        return None;
    }
    let p = enc.get_int("P")?;
    let mut input = Vec::with_capacity(32 + 32 + 4 + id0.len() + 4);
    input.extend_from_slice(padded);
    input.extend_from_slice(&o[..32]);
    input.extend_from_slice(&(p as i32 as u32).to_le_bytes()); // /P low 32 bits, LE
    input.extend_from_slice(id0);
    // Revision 4 with /EncryptMetadata false hashes an extra 0xFFFFFFFF.
    if r >= 4 && !encrypt_metadata_flag(enc) {
        input.extend_from_slice(&[0xFF, 0xFF, 0xFF, 0xFF]);
    }
    let mut digest = md5(&input);
    if r >= 3 {
        for _ in 0..50 {
            digest = md5(&digest[..n]);
        }
    }
    Some(digest[..n].to_vec())
}

/// Checks the empty user password by recomputing `/U` and comparing.
fn verify_user_password(key: &[u8], r: i64, id0: &[u8], u: &[u8]) -> bool {
    if r == 2 {
        // Algorithm 4: U = RC4(key, PAD).
        let computed = rc4(key, &PAD);
        u.len() >= 32 && computed == u[..32]
    } else {
        // Algorithm 5: U = MD5(PAD ++ ID[0]) encrypted with 20 keyed RC4 passes.
        let mut input = Vec::with_capacity(32 + id0.len());
        input.extend_from_slice(&PAD);
        input.extend_from_slice(id0);
        let mut x = md5(&input).to_vec();
        x = rc4(key, &x);
        for i in 1u8..=19 {
            let keyed: Vec<u8> = key.iter().map(|b| b ^ i).collect();
            x = rc4(&keyed, &x);
        }
        // Only the first 16 bytes are defined; the rest of /U is arbitrary padding.
        u.len() >= 16 && x[..16] == u[..16]
    }
}

/// RC4 stream cipher (symmetric: the same call encrypts and decrypts).
fn rc4(key: &[u8], data: &[u8]) -> Vec<u8> {
    debug_assert!(!key.is_empty());
    let mut s: [u8; 256] = core::array::from_fn(|i| i as u8);
    let mut j = 0u8;
    for i in 0..256 {
        j = j.wrapping_add(s[i]).wrapping_add(key[i % key.len()]);
        s.swap(i, j as usize);
    }
    let mut out = Vec::with_capacity(data.len());
    let (mut i, mut j) = (0u8, 0u8);
    for &byte in data {
        i = i.wrapping_add(1);
        j = j.wrapping_add(s[i as usize]);
        s.swap(i as usize, j as usize);
        let k = s[s[i as usize].wrapping_add(s[j as usize]) as usize];
        out.push(byte ^ k);
    }
    out
}

// --- AES (FIPS-197) and CBC mode -----------------------------------------

/// AES substitution box.
#[rustfmt::skip]
const AES_SBOX: [u8; 256] = [
    0x63,0x7c,0x77,0x7b,0xf2,0x6b,0x6f,0xc5,0x30,0x01,0x67,0x2b,0xfe,0xd7,0xab,0x76,
    0xca,0x82,0xc9,0x7d,0xfa,0x59,0x47,0xf0,0xad,0xd4,0xa2,0xaf,0x9c,0xa4,0x72,0xc0,
    0xb7,0xfd,0x93,0x26,0x36,0x3f,0xf7,0xcc,0x34,0xa5,0xe5,0xf1,0x71,0xd8,0x31,0x15,
    0x04,0xc7,0x23,0xc3,0x18,0x96,0x05,0x9a,0x07,0x12,0x80,0xe2,0xeb,0x27,0xb2,0x75,
    0x09,0x83,0x2c,0x1a,0x1b,0x6e,0x5a,0xa0,0x52,0x3b,0xd6,0xb3,0x29,0xe3,0x2f,0x84,
    0x53,0xd1,0x00,0xed,0x20,0xfc,0xb1,0x5b,0x6a,0xcb,0xbe,0x39,0x4a,0x4c,0x58,0xcf,
    0xd0,0xef,0xaa,0xfb,0x43,0x4d,0x33,0x85,0x45,0xf9,0x02,0x7f,0x50,0x3c,0x9f,0xa8,
    0x51,0xa3,0x40,0x8f,0x92,0x9d,0x38,0xf5,0xbc,0xb6,0xda,0x21,0x10,0xff,0xf3,0xd2,
    0xcd,0x0c,0x13,0xec,0x5f,0x97,0x44,0x17,0xc4,0xa7,0x7e,0x3d,0x64,0x5d,0x19,0x73,
    0x60,0x81,0x4f,0xdc,0x22,0x2a,0x90,0x88,0x46,0xee,0xb8,0x14,0xde,0x5e,0x0b,0xdb,
    0xe0,0x32,0x3a,0x0a,0x49,0x06,0x24,0x5c,0xc2,0xd3,0xac,0x62,0x91,0x95,0xe4,0x79,
    0xe7,0xc8,0x37,0x6d,0x8d,0xd5,0x4e,0xa9,0x6c,0x56,0xf4,0xea,0x65,0x7a,0xae,0x08,
    0xba,0x78,0x25,0x2e,0x1c,0xa6,0xb4,0xc6,0xe8,0xdd,0x74,0x1f,0x4b,0xbd,0x8b,0x8a,
    0x70,0x3e,0xb5,0x66,0x48,0x03,0xf6,0x0e,0x61,0x35,0x57,0xb9,0x86,0xc1,0x1d,0x9e,
    0xe1,0xf8,0x98,0x11,0x69,0xd9,0x8e,0x94,0x9b,0x1e,0x87,0xe9,0xce,0x55,0x28,0xdf,
    0x8c,0xa1,0x89,0x0d,0xbf,0xe6,0x42,0x68,0x41,0x99,0x2d,0x0f,0xb0,0x54,0xbb,0x16,
];

/// Round constants for key expansion (`RCON[j]` used when `i % Nk == 0`).
const AES_RCON: [u8; 11] = [
    0x00, 0x01, 0x02, 0x04, 0x08, 0x10, 0x20, 0x40, 0x80, 0x1b, 0x36,
];

/// The inverse S-box, derived once from `AES_SBOX`.
fn aes_inv_sbox() -> [u8; 256] {
    let mut inv = [0u8; 256];
    for (i, &s) in AES_SBOX.iter().enumerate() {
        inv[s as usize] = i as u8;
    }
    inv
}

/// Multiplies two elements of GF(2^8) with the AES reduction polynomial.
fn gmul(mut a: u8, mut b: u8) -> u8 {
    let mut p = 0u8;
    for _ in 0..8 {
        if b & 1 != 0 {
            p ^= a;
        }
        let hi = a & 0x80;
        a <<= 1;
        if hi != 0 {
            a ^= 0x1b;
        }
        b >>= 1;
    }
    p
}

/// Expands a 16- or 32-byte key into `Nr + 1` round keys (state is stored
/// column-major, so byte `r + 4c` is row `r`, column `c`).
fn aes_expand_key(key: &[u8]) -> Vec<[u8; 16]> {
    let nk = key.len() / 4; // 4 (AES-128) or 8 (AES-256)
    let nr = nk + 6;
    let total = 4 * (nr + 1);
    let mut w: Vec<[u8; 4]> = Vec::with_capacity(total);
    for i in 0..nk {
        w.push([key[4 * i], key[4 * i + 1], key[4 * i + 2], key[4 * i + 3]]);
    }
    for i in nk..total {
        let mut t = w[i - 1];
        if i.is_multiple_of(nk) {
            t = [t[1], t[2], t[3], t[0]]; // RotWord
            for b in &mut t {
                *b = AES_SBOX[*b as usize]; // SubWord
            }
            t[0] ^= AES_RCON[i / nk];
        } else if nk > 6 && i % nk == 4 {
            for b in &mut t {
                *b = AES_SBOX[*b as usize];
            }
        }
        let prev = w[i - nk];
        w.push([
            prev[0] ^ t[0],
            prev[1] ^ t[1],
            prev[2] ^ t[2],
            prev[3] ^ t[3],
        ]);
    }
    (0..=nr)
        .map(|round| {
            let mut rk = [0u8; 16];
            for c in 0..4 {
                rk[4 * c..4 * c + 4].copy_from_slice(&w[4 * round + c]);
            }
            rk
        })
        .collect()
}

fn add_round_key(s: &mut [u8; 16], rk: &[u8; 16]) {
    for (b, k) in s.iter_mut().zip(rk) {
        *b ^= k;
    }
}

fn shift_rows(s: &mut [u8; 16]) {
    let o = *s;
    for r in 1..4 {
        for c in 0..4 {
            s[r + 4 * c] = o[r + 4 * ((c + r) % 4)];
        }
    }
}

fn inv_shift_rows(s: &mut [u8; 16]) {
    let o = *s;
    for r in 1..4 {
        for c in 0..4 {
            s[r + 4 * c] = o[r + 4 * ((c + 4 - r) % 4)];
        }
    }
}

fn mix_columns(s: &mut [u8; 16]) {
    for c in 0..4 {
        let i = 4 * c;
        let (a0, a1, a2, a3) = (s[i], s[i + 1], s[i + 2], s[i + 3]);
        s[i] = gmul(a0, 2) ^ gmul(a1, 3) ^ a2 ^ a3;
        s[i + 1] = a0 ^ gmul(a1, 2) ^ gmul(a2, 3) ^ a3;
        s[i + 2] = a0 ^ a1 ^ gmul(a2, 2) ^ gmul(a3, 3);
        s[i + 3] = gmul(a0, 3) ^ a1 ^ a2 ^ gmul(a3, 2);
    }
}

fn inv_mix_columns(s: &mut [u8; 16]) {
    for c in 0..4 {
        let i = 4 * c;
        let (a0, a1, a2, a3) = (s[i], s[i + 1], s[i + 2], s[i + 3]);
        s[i] = gmul(a0, 14) ^ gmul(a1, 11) ^ gmul(a2, 13) ^ gmul(a3, 9);
        s[i + 1] = gmul(a0, 9) ^ gmul(a1, 14) ^ gmul(a2, 11) ^ gmul(a3, 13);
        s[i + 2] = gmul(a0, 13) ^ gmul(a1, 9) ^ gmul(a2, 14) ^ gmul(a3, 11);
        s[i + 3] = gmul(a0, 11) ^ gmul(a1, 13) ^ gmul(a2, 9) ^ gmul(a3, 14);
    }
}

fn aes_encrypt_block(s: &mut [u8; 16], rks: &[[u8; 16]]) {
    #[cfg(target_arch = "aarch64")]
    if std::arch::is_aarch64_feature_detected!("aes") {
        // SAFETY: the `aes` target feature was just detected at runtime.
        unsafe { aes_hw::encrypt_block(s, rks) };
        return;
    }
    #[cfg(target_arch = "x86_64")]
    if std::arch::is_x86_feature_detected!("aes") {
        // SAFETY: the `aes` target feature was just detected at runtime.
        unsafe { aes_hw::encrypt_block(s, rks) };
        return;
    }
    aes_encrypt_block_soft(s, rks);
}

/// The portable byte-oriented rounds, for CPUs without AES instructions.
fn aes_encrypt_block_soft(s: &mut [u8; 16], rks: &[[u8; 16]]) {
    let nr = rks.len() - 1;
    add_round_key(s, &rks[0]);
    for rk in &rks[1..nr] {
        s.iter_mut().for_each(|b| *b = AES_SBOX[*b as usize]);
        shift_rows(s);
        mix_columns(s);
        add_round_key(s, rk);
    }
    s.iter_mut().for_each(|b| *b = AES_SBOX[*b as usize]);
    shift_rows(s);
    add_round_key(s, &rks[nr]);
}

fn aes_decrypt_block(s: &mut [u8; 16], rks: &[[u8; 16]], inv_sbox: &[u8; 256]) {
    #[cfg(target_arch = "aarch64")]
    if std::arch::is_aarch64_feature_detected!("aes") {
        // SAFETY: the `aes` target feature was just detected at runtime.
        unsafe { aes_hw::decrypt_block(s, rks) };
        return;
    }
    #[cfg(target_arch = "x86_64")]
    if std::arch::is_x86_feature_detected!("aes") {
        // SAFETY: the `aes` target feature was just detected at runtime.
        unsafe { aes_hw::decrypt_block(s, rks) };
        return;
    }
    aes_decrypt_block_soft(s, rks, inv_sbox);
}

/// The portable byte-oriented rounds, for CPUs without AES instructions.
fn aes_decrypt_block_soft(s: &mut [u8; 16], rks: &[[u8; 16]], inv_sbox: &[u8; 256]) {
    let nr = rks.len() - 1;
    add_round_key(s, &rks[nr]);
    for rk in rks[1..nr].iter().rev() {
        inv_shift_rows(s);
        s.iter_mut().for_each(|b| *b = inv_sbox[*b as usize]);
        add_round_key(s, rk);
        inv_mix_columns(s);
    }
    inv_shift_rows(s);
    s.iter_mut().for_each(|b| *b = inv_sbox[*b as usize]);
    add_round_key(s, &rks[0]);
}

/// AES block rounds on the CPU's AES instructions. The R6 password hash
/// CBC-encrypts about a megabyte per key derivation (Algorithm 2.B runs
/// 64+ rounds over a 64-fold repeated block), which the byte-oriented
/// software rounds above turn into ~500ms per encrypted document; these
/// paths bring that under a millisecond. Callers detect the `aes` feature
/// before entering; every function must produce bytes identical to the
/// software rounds (pinned by the FIPS-197 vectors in the tests below).
#[cfg(target_arch = "aarch64")]
mod aes_hw {
    use core::arch::aarch64::{
        vaesdq_u8, vaeseq_u8, vaesimcq_u8, vaesmcq_u8, veorq_u8, vld1q_u8, vmovq_n_u8, vst1q_u8,
    };

    /// # Safety
    /// Requires the `aes` target feature.
    #[target_feature(enable = "aes")]
    pub unsafe fn encrypt_block(s: &mut [u8; 16], rks: &[[u8; 16]]) {
        let nr = rks.len() - 1;
        // AESE folds AddRoundKey into SubBytes+ShiftRows, so the loop
        // consumes rks[0..nr-1] and the last round's key lands as a plain
        // XOR after the final AESE.
        let mut x = vld1q_u8(s.as_ptr());
        for rk in &rks[..nr - 1] {
            x = vaesmcq_u8(vaeseq_u8(x, vld1q_u8(rk.as_ptr())));
        }
        x = vaeseq_u8(x, vld1q_u8(rks[nr - 1].as_ptr()));
        x = veorq_u8(x, vld1q_u8(rks[nr].as_ptr()));
        vst1q_u8(s.as_mut_ptr(), x);
    }

    /// # Safety
    /// Requires the `aes` target feature.
    #[target_feature(enable = "aes")]
    pub unsafe fn decrypt_block(s: &mut [u8; 16], rks: &[[u8; 16]]) {
        let nr = rks.len() - 1;
        // AESD with a zero key is exactly InvSubBytes(InvShiftRows(x)),
        // which lets the loop mirror the software inverse cipher's
        // operation order with the round keys untransformed.
        let zero = vmovq_n_u8(0);
        let mut x = vld1q_u8(s.as_ptr());
        x = veorq_u8(x, vld1q_u8(rks[nr].as_ptr()));
        for rk in rks[1..nr].iter().rev() {
            x = vaesdq_u8(x, zero);
            x = veorq_u8(x, vld1q_u8(rk.as_ptr()));
            x = vaesimcq_u8(x);
        }
        x = vaesdq_u8(x, zero);
        x = veorq_u8(x, vld1q_u8(rks[0].as_ptr()));
        vst1q_u8(s.as_mut_ptr(), x);
    }
}

/// See the aarch64 twin above; same contract, AES-NI instructions.
#[cfg(target_arch = "x86_64")]
mod aes_hw {
    use core::arch::x86_64::{
        __m128i, _mm_aesdec_si128, _mm_aesdeclast_si128, _mm_aesenc_si128, _mm_aesenclast_si128,
        _mm_aesimc_si128, _mm_loadu_si128, _mm_storeu_si128, _mm_xor_si128,
    };

    /// # Safety
    /// Requires the `aes` target feature.
    #[target_feature(enable = "aes")]
    pub unsafe fn encrypt_block(s: &mut [u8; 16], rks: &[[u8; 16]]) {
        let nr = rks.len() - 1;
        let mut x = _mm_loadu_si128(s.as_ptr().cast::<__m128i>());
        x = _mm_xor_si128(x, _mm_loadu_si128(rks[0].as_ptr().cast::<__m128i>()));
        for rk in &rks[1..nr] {
            x = _mm_aesenc_si128(x, _mm_loadu_si128(rk.as_ptr().cast::<__m128i>()));
        }
        x = _mm_aesenclast_si128(x, _mm_loadu_si128(rks[nr].as_ptr().cast::<__m128i>()));
        _mm_storeu_si128(s.as_mut_ptr().cast::<__m128i>(), x);
    }

    /// # Safety
    /// Requires the `aes` target feature.
    #[target_feature(enable = "aes")]
    pub unsafe fn decrypt_block(s: &mut [u8; 16], rks: &[[u8; 16]]) {
        let nr = rks.len() - 1;
        // AESDEC applies InvMixColumns before its key XOR, so the middle
        // round keys go through AESIMC (the equivalent inverse cipher).
        let mut x = _mm_loadu_si128(s.as_ptr().cast::<__m128i>());
        x = _mm_xor_si128(x, _mm_loadu_si128(rks[nr].as_ptr().cast::<__m128i>()));
        for rk in rks[1..nr].iter().rev() {
            let dk = _mm_aesimc_si128(_mm_loadu_si128(rk.as_ptr().cast::<__m128i>()));
            x = _mm_aesdec_si128(x, dk);
        }
        x = _mm_aesdeclast_si128(x, _mm_loadu_si128(rks[0].as_ptr().cast::<__m128i>()));
        _mm_storeu_si128(s.as_mut_ptr().cast::<__m128i>(), x);
    }
}

/// AES-CBC decryption of whole blocks (no IV prefix, no padding removal).
/// Returns an empty vector when the input is not a positive multiple of 16.
fn aes_cbc_decrypt_blocks(key: &[u8], iv: &[u8], data: &[u8]) -> Vec<u8> {
    if data.is_empty() || !data.len().is_multiple_of(16) || iv.len() < 16 {
        return Vec::new();
    }
    let rks = aes_expand_key(key);
    let inv_sbox = aes_inv_sbox();
    let mut prev = [0u8; 16];
    prev.copy_from_slice(&iv[..16]);
    let mut out = Vec::with_capacity(data.len());
    for chunk in data.as_chunks::<16>().0 {
        let mut block = [0u8; 16];
        block.copy_from_slice(chunk);
        let cipher = block;
        aes_decrypt_block(&mut block, &rks, &inv_sbox);
        for (b, p) in block.iter_mut().zip(&prev) {
            *b ^= p;
        }
        out.extend_from_slice(&block);
        prev = cipher;
    }
    out
}

/// AES-CBC encryption of whole blocks (no IV prefix, no padding). Used only by
/// the R6 key-derivation hash.
fn aes_cbc_encrypt_blocks(key: &[u8], iv: &[u8], data: &[u8]) -> Vec<u8> {
    let rks = aes_expand_key(key);
    let mut prev = [0u8; 16];
    prev.copy_from_slice(&iv[..16]);
    let mut out = Vec::with_capacity(data.len());
    for chunk in data.as_chunks::<16>().0 {
        let mut block = [0u8; 16];
        for ((b, c), p) in block.iter_mut().zip(chunk).zip(&prev) {
            *b = c ^ p;
        }
        aes_encrypt_block(&mut block, &rks);
        out.extend_from_slice(&block);
        prev = block;
    }
    out
}

/// Decrypts a PDF AES value: the first 16 bytes are the IV, the rest is
/// CBC-encrypted with PKCS#7 padding. Malformed input yields empty output
/// rather than garbage.
fn aes_cbc_decrypt(key: &[u8], data: &[u8]) -> Vec<u8> {
    if data.len() < 16 {
        return Vec::new();
    }
    let (iv, ct) = data.split_at(16);
    let mut out = aes_cbc_decrypt_blocks(key, iv, ct);
    strip_pkcs7(&mut out);
    out
}

/// Removes PKCS#7 padding in place if present and well-formed.
fn strip_pkcs7(data: &mut Vec<u8>) {
    let Some(&pad) = data.last() else {
        return;
    };
    let pad = pad as usize;
    if (1..=16).contains(&pad) && pad <= data.len() {
        let start = data.len() - pad;
        if data[start..].iter().all(|&b| b as usize == pad) {
            data.truncate(start);
        }
    }
}

/// Pads `data` to a whole number of 16-byte blocks with PKCS#7: a full
/// extra block of `0x10` bytes when `data` is already block-aligned, so
/// [`strip_pkcs7`] always has a marker to remove.
fn pkcs7_pad(data: &[u8]) -> Vec<u8> {
    let pad = 16 - data.len() % 16;
    let mut out = data.to_vec();
    out.resize(data.len() + pad, pad as u8);
    out
}

/// Encrypts a PDF AES value: a fresh 16-byte IV from `rng` followed by the
/// PKCS#7-padded plaintext under AES-256-CBC, the exact inverse of
/// [`aes_cbc_decrypt`].
fn aes_cbc_encrypt(key: &[u8], rng: &mut dyn FnMut(&mut [u8]), data: &[u8]) -> Vec<u8> {
    let mut iv = [0u8; 16];
    rng(&mut iv);
    let mut out = iv.to_vec();
    out.extend_from_slice(&aes_cbc_encrypt_blocks(key, &iv, &pkcs7_pad(data)));
    out
}

// --- SHA-2 (FIPS 180-4): 256, 512 and 384 --------------------------------

#[rustfmt::skip]
const SHA256_K: [u32; 64] = [
    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
];

/// Streaming SHA-256 (FIPS 180-4): feed bytes with [`Sha256::update`],
/// close with [`Sha256::finalize`]. Public so the writer can hash a file's
/// body as it emits it, without holding the whole file in memory; the
/// one-shot [`sha256`] delegates here.
#[derive(Debug, Clone)]
pub struct Sha256 {
    h: [u32; 8],
    tail: [u8; 64],
    tail_len: usize,
    total: u64,
}

impl Default for Sha256 {
    fn default() -> Sha256 {
        Sha256::new()
    }
}

impl Sha256 {
    /// A hasher in the FIPS 180-4 initial state.
    pub fn new() -> Sha256 {
        Sha256 {
            h: [
                0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab,
                0x5be0cd19,
            ],
            tail: [0u8; 64],
            tail_len: 0,
            total: 0,
        }
    }

    /// Absorbs `input`. Slice boundaries do not affect the digest: any
    /// sequence of updates whose concatenation is the same message yields
    /// the same [`Sha256::finalize`] result. Whole blocks are compressed
    /// straight from `input`; only a partial trailing block is buffered.
    pub fn update(&mut self, input: &[u8]) {
        self.total = self.total.wrapping_add(input.len() as u64);
        let mut input = input;
        if self.tail_len > 0 {
            let take = input.len().min(64 - self.tail_len);
            self.tail[self.tail_len..self.tail_len + take].copy_from_slice(&input[..take]);
            self.tail_len += take;
            input = &input[take..];
            if self.tail_len < 64 {
                return;
            }
            let block = self.tail;
            sha256_compress(&mut self.h, &block);
            self.tail_len = 0;
        }
        let (blocks, rest) = input.as_chunks::<64>();
        for block in blocks {
            sha256_compress(&mut self.h, block);
        }
        self.tail[..rest.len()].copy_from_slice(rest);
        self.tail_len = rest.len();
    }

    /// Pads and returns the digest of everything absorbed so far.
    pub fn finalize(mut self) -> [u8; 32] {
        // Final padding touches at most two blocks: 0x80, zeros, and the
        // bit length in the last 8 bytes (FIPS 180-4).
        let mut pad = [0u8; 128];
        pad[..self.tail_len].copy_from_slice(&self.tail[..self.tail_len]);
        pad[self.tail_len] = 0x80;
        let padded = if self.tail_len < 56 { 64 } else { 128 };
        let bitlen = self.total.wrapping_mul(8);
        pad[padded - 8..padded].copy_from_slice(&bitlen.to_be_bytes());
        for block in pad[..padded].as_chunks::<64>().0 {
            sha256_compress(&mut self.h, block);
        }
        let mut out = [0u8; 32];
        for (i, word) in self.h.iter().enumerate() {
            out[4 * i..4 * i + 4].copy_from_slice(&word.to_be_bytes());
        }
        out
    }
}

/// SHA-256 of `input` (FIPS 180-4); public so the writer can derive its `/ID`.
pub fn sha256(input: &[u8]) -> [u8; 32] {
    let mut hasher = Sha256::new();
    hasher.update(input);
    hasher.finalize()
}

fn sha256_compress(h: &mut [u32; 8], block: &[u8; 64]) {
    #[cfg(target_arch = "aarch64")]
    if std::arch::is_aarch64_feature_detected!("sha2") {
        // SAFETY: the `sha2` target feature was just detected at runtime.
        unsafe { sha_hw::compress256(h, block) };
        return;
    }
    sha256_compress_soft(h, block);
}

/// The portable compression, for CPUs without SHA-256 instructions.
fn sha256_compress_soft(h: &mut [u32; 8], block: &[u8; 64]) {
    let mut w = [0u32; 64];
    for (word, bytes) in w.iter_mut().zip(block.as_chunks::<4>().0) {
        *word = u32::from_be_bytes(*bytes);
    }
    for i in 16..64 {
        let s0 = w[i - 15].rotate_right(7) ^ w[i - 15].rotate_right(18) ^ (w[i - 15] >> 3);
        let s1 = w[i - 2].rotate_right(17) ^ w[i - 2].rotate_right(19) ^ (w[i - 2] >> 10);
        w[i] = w[i - 16]
            .wrapping_add(s0)
            .wrapping_add(w[i - 7])
            .wrapping_add(s1);
    }
    let [mut a, mut b, mut c, mut d, mut e, mut f, mut g, mut hh] = *h;
    for (k, wi) in SHA256_K.iter().zip(&w) {
        let s1 = e.rotate_right(6) ^ e.rotate_right(11) ^ e.rotate_right(25);
        let ch = (e & f) ^ ((!e) & g);
        let t1 = hh
            .wrapping_add(s1)
            .wrapping_add(ch)
            .wrapping_add(*k)
            .wrapping_add(*wi);
        let s0 = a.rotate_right(2) ^ a.rotate_right(13) ^ a.rotate_right(22);
        let maj = (a & b) ^ (a & c) ^ (b & c);
        let t2 = s0.wrapping_add(maj);
        hh = g;
        g = f;
        f = e;
        e = d.wrapping_add(t1);
        d = c;
        c = b;
        b = a;
        a = t1.wrapping_add(t2);
    }
    for (hv, v) in h.iter_mut().zip([a, b, c, d, e, f, g, hh]) {
        *hv = hv.wrapping_add(v);
    }
}

#[rustfmt::skip]
const SHA512_K: [u64; 80] = [
    0x428a2f98d728ae22, 0x7137449123ef65cd, 0xb5c0fbcfec4d3b2f, 0xe9b5dba58189dbbc,
    0x3956c25bf348b538, 0x59f111f1b605d019, 0x923f82a4af194f9b, 0xab1c5ed5da6d8118,
    0xd807aa98a3030242, 0x12835b0145706fbe, 0x243185be4ee4b28c, 0x550c7dc3d5ffb4e2,
    0x72be5d74f27b896f, 0x80deb1fe3b1696b1, 0x9bdc06a725c71235, 0xc19bf174cf692694,
    0xe49b69c19ef14ad2, 0xefbe4786384f25e3, 0x0fc19dc68b8cd5b5, 0x240ca1cc77ac9c65,
    0x2de92c6f592b0275, 0x4a7484aa6ea6e483, 0x5cb0a9dcbd41fbd4, 0x76f988da831153b5,
    0x983e5152ee66dfab, 0xa831c66d2db43210, 0xb00327c898fb213f, 0xbf597fc7beef0ee4,
    0xc6e00bf33da88fc2, 0xd5a79147930aa725, 0x06ca6351e003826f, 0x142929670a0e6e70,
    0x27b70a8546d22ffc, 0x2e1b21385c26c926, 0x4d2c6dfc5ac42aed, 0x53380d139d95b3df,
    0x650a73548baf63de, 0x766a0abb3c77b2a8, 0x81c2c92e47edaee6, 0x92722c851482353b,
    0xa2bfe8a14cf10364, 0xa81a664bbc423001, 0xc24b8b70d0f89791, 0xc76c51a30654be30,
    0xd192e819d6ef5218, 0xd69906245565a910, 0xf40e35855771202a, 0x106aa07032bbd1b8,
    0x19a4c116b8d2d0c8, 0x1e376c085141ab53, 0x2748774cdf8eeb99, 0x34b0bcb5e19b48a8,
    0x391c0cb3c5c95a63, 0x4ed8aa4ae3418acb, 0x5b9cca4f7763e373, 0x682e6ff3d6b2b8a3,
    0x748f82ee5defb2fc, 0x78a5636f43172f60, 0x84c87814a1f0ab72, 0x8cc702081a6439ec,
    0x90befffa23631e28, 0xa4506cebde82bde9, 0xbef9a3f7b2c67915, 0xc67178f2e372532b,
    0xca273eceea26619c, 0xd186b8c721c0c207, 0xeada7dd6cde0eb1e, 0xf57d4f7fee6ed178,
    0x06f067aa72176fba, 0x0a637dc5a2c898a6, 0x113f9804bef90dae, 0x1b710b35131c471b,
    0x28db77f523047d84, 0x32caab7b40c72493, 0x3c9ebe0a15c9bebc, 0x431d67c49c100d4c,
    0x4cc5d4becb3e42b6, 0x597f299cfc657e2a, 0x5fcb6fab3ad6faec, 0x6c44198c4a475817,
];

fn sha512_core(input: &[u8], mut h: [u64; 8]) -> [u64; 8] {
    let (blocks, tail) = input.as_chunks::<128>();
    for block in blocks {
        sha512_compress(&mut h, block);
    }
    // Final padding touches at most two blocks: 0x80, zeros, and the bit
    // length in the last 16 bytes (FIPS 180-4) — the message itself is
    // hashed in place above, never copied.
    let mut pad = [0u8; 256];
    pad[..tail.len()].copy_from_slice(tail);
    pad[tail.len()] = 0x80;
    let padded = if tail.len() < 112 { 128 } else { 256 };
    let bitlen = (input.len() as u128).wrapping_mul(8);
    pad[padded - 16..padded].copy_from_slice(&bitlen.to_be_bytes());
    for block in pad[..padded].as_chunks::<128>().0 {
        sha512_compress(&mut h, block);
    }
    h
}

fn sha512_compress(h: &mut [u64; 8], block: &[u8; 128]) {
    #[cfg(target_arch = "aarch64")]
    if std::arch::is_aarch64_feature_detected!("sha3") {
        // SAFETY: the `sha3` target feature (SHA-512 instructions) was
        // just detected at runtime.
        unsafe { sha_hw::compress512(h, block) };
        return;
    }
    sha512_compress_soft(h, block);
}

/// The portable compression, for CPUs without SHA-512 instructions.
fn sha512_compress_soft(h: &mut [u64; 8], block: &[u8; 128]) {
    let mut w = [0u64; 80];
    for (word, bytes) in w.iter_mut().zip(block.as_chunks::<8>().0) {
        *word = u64::from_be_bytes(*bytes);
    }
    for i in 16..80 {
        let s0 = w[i - 15].rotate_right(1) ^ w[i - 15].rotate_right(8) ^ (w[i - 15] >> 7);
        let s1 = w[i - 2].rotate_right(19) ^ w[i - 2].rotate_right(61) ^ (w[i - 2] >> 6);
        w[i] = w[i - 16]
            .wrapping_add(s0)
            .wrapping_add(w[i - 7])
            .wrapping_add(s1);
    }
    let [mut a, mut b, mut c, mut d, mut e, mut f, mut g, mut hh] = *h;
    for (k, wi) in SHA512_K.iter().zip(&w) {
        let s1 = e.rotate_right(14) ^ e.rotate_right(18) ^ e.rotate_right(41);
        let ch = (e & f) ^ ((!e) & g);
        let t1 = hh
            .wrapping_add(s1)
            .wrapping_add(ch)
            .wrapping_add(*k)
            .wrapping_add(*wi);
        let s0 = a.rotate_right(28) ^ a.rotate_right(34) ^ a.rotate_right(39);
        let maj = (a & b) ^ (a & c) ^ (b & c);
        let t2 = s0.wrapping_add(maj);
        hh = g;
        g = f;
        f = e;
        e = d.wrapping_add(t1);
        d = c;
        c = b;
        b = a;
        a = t1.wrapping_add(t2);
    }
    for (hv, v) in h.iter_mut().zip([a, b, c, d, e, f, g, hh]) {
        *hv = hv.wrapping_add(v);
    }
}

/// SHA-2 compressions on the CPU's SHA instructions. Algorithm 2.B hashes
/// roughly a megabyte per key derivation across its rounds — after the AES
/// rounds moved to hardware this hashing was the remaining ~1-3ms of every
/// encrypted-document open (PMU counters put it 60x below the memory-bound
/// probe and at the ALU probe's branch signature: a pure serial dependency
/// chain, which is exactly what the SHA instructions collapse). Callers
/// detect `sha2`/`sha3` before entering; results are pinned to the FIPS
/// 180 vectors in the tests below.
#[cfg(target_arch = "aarch64")]
mod sha_hw {
    use core::arch::aarch64::{
        uint32x4_t, uint64x2_t, vaddq_u32, vaddq_u64, vextq_u64, vld1q_u32, vld1q_u64, vld1q_u8,
        vreinterpretq_u32_u8, vreinterpretq_u64_u8, vrev32q_u8, vrev64q_u8, vsha256h2q_u32,
        vsha256hq_u32, vsha256su0q_u32, vsha256su1q_u32, vsha512h2q_u64, vsha512hq_u64,
        vsha512su0q_u64, vsha512su1q_u64, vst1q_u32,
    };

    use super::{SHA256_K, SHA512_K};

    /// # Safety
    /// Requires the `sha2` target feature.
    #[target_feature(enable = "sha2")]
    pub unsafe fn compress256(h: &mut [u32; 8], block: &[u8; 64]) {
        let mut abcd = vld1q_u32(h.as_ptr());
        let mut efgh = vld1q_u32(h.as_ptr().add(4));
        let saved = (abcd, efgh);
        let mut w: [uint32x4_t; 4] = [
            vreinterpretq_u32_u8(vrev32q_u8(vld1q_u8(block.as_ptr()))),
            vreinterpretq_u32_u8(vrev32q_u8(vld1q_u8(block.as_ptr().add(16)))),
            vreinterpretq_u32_u8(vrev32q_u8(vld1q_u8(block.as_ptr().add(32)))),
            vreinterpretq_u32_u8(vrev32q_u8(vld1q_u8(block.as_ptr().add(48)))),
        ];
        for step in 0..16 {
            let wk = vaddq_u32(w[step % 4], vld1q_u32(SHA256_K.as_ptr().add(4 * step)));
            // The last three windows feed no further schedule.
            if step < 12 {
                w[step % 4] = vsha256su1q_u32(
                    vsha256su0q_u32(w[step % 4], w[(step + 1) % 4]),
                    w[(step + 2) % 4],
                    w[(step + 3) % 4],
                );
            }
            let prev = abcd;
            abcd = vsha256hq_u32(abcd, efgh, wk);
            efgh = vsha256h2q_u32(efgh, prev, wk);
        }
        vst1q_u32(h.as_mut_ptr(), vaddq_u32(abcd, saved.0));
        vst1q_u32(h.as_mut_ptr().add(4), vaddq_u32(efgh, saved.1));
    }

    /// # Safety
    /// Requires the `sha3` target feature (the SHA-512 instructions).
    #[target_feature(enable = "sha2,sha3")]
    pub unsafe fn compress512(h: &mut [u64; 8], block: &[u8; 128]) {
        // State as register pairs s = [ab, cd, ef, gh]. Each step covers
        // two rounds; the register playing the "gh" role rotates
        // gh -> ef -> cd -> ab, which the r index tracks.
        let mut s: [uint64x2_t; 4] = [
            vld1q_u64(h.as_ptr()),
            vld1q_u64(h.as_ptr().add(2)),
            vld1q_u64(h.as_ptr().add(4)),
            vld1q_u64(h.as_ptr().add(6)),
        ];
        let saved = s;
        let mut w: [uint64x2_t; 8] = [core::mem::zeroed(); 8];
        for (pair, bytes) in w.iter_mut().zip(block.as_chunks::<16>().0) {
            *pair = vreinterpretq_u64_u8(vrev64q_u8(vld1q_u8(bytes.as_ptr())));
        }
        for step in 0..40 {
            let r = 3 - (step % 4);
            let wk = vaddq_u64(w[step % 8], vld1q_u64(SHA512_K.as_ptr().add(2 * step)));
            let sum = vaddq_u64(vextq_u64::<1>(wk, wk), s[r]);
            let im = vsha512hq_u64(
                sum,
                vextq_u64::<1>(s[(r + 3) % 4], s[r]),
                vextq_u64::<1>(s[(r + 2) % 4], s[(r + 3) % 4]),
            );
            let updated = vsha512h2q_u64(im, s[(r + 2) % 4], s[(r + 1) % 4]);
            s[(r + 2) % 4] = vaddq_u64(s[(r + 2) % 4], im);
            s[r] = updated;
            // The last four windows feed no further schedule.
            if step < 32 {
                let i = step % 8;
                w[i] = vsha512su1q_u64(
                    vsha512su0q_u64(w[i], w[(i + 1) % 8]),
                    w[(i + 7) % 8],
                    vextq_u64::<1>(w[(i + 4) % 8], w[(i + 5) % 8]),
                );
            }
        }
        for (i, (out, kept)) in s.iter().zip(saved).enumerate() {
            let summed = vaddq_u64(*out, kept);
            core::arch::aarch64::vst1q_u64(h.as_mut_ptr().add(2 * i), summed);
        }
    }
}

fn sha512(input: &[u8]) -> Vec<u8> {
    let h = sha512_core(
        input,
        [
            0x6a09e667f3bcc908,
            0xbb67ae8584caa73b,
            0x3c6ef372fe94f82b,
            0xa54ff53a5f1d36f1,
            0x510e527fade682d1,
            0x9b05688c2b3e6c1f,
            0x1f83d9abfb41bd6b,
            0x5be0cd19137e2179,
        ],
    );
    h.iter().flat_map(|w| w.to_be_bytes()).collect()
}

fn sha384(input: &[u8]) -> Vec<u8> {
    let h = sha512_core(
        input,
        [
            0xcbbb9d5dc1059ed8,
            0x629a292a367cd507,
            0x9159015a3070dd17,
            0x152fecd8f70e5939,
            0x67332667ffc00b31,
            0x8eb44a8768581511,
            0xdb0c2e0d64f98fa7,
            0x47b5481dbefa4fa4,
        ],
    );
    h.iter().take(6).flat_map(|w| w.to_be_bytes()).collect()
}

/// Recovers the AES-256 file key `password` opens (ISO 32000-2 §7.6.4.3.3,
/// Algorithm 2.A) for revisions 5 and 6: as the user password against
/// `/U`+`/UE`, then as the owner password against `/O`+`/OE` (whose hashes
/// additionally salt in the first 48 bytes of `/U`). Passwords longer than
/// the 127 UTF-8 bytes the algorithm defines are truncated.
fn aesv3_key(enc: &Dict, r: i64, password: &[u8]) -> Option<Vec<u8>> {
    let pw = &password[..password.len().min(127)];
    let u = enc.get("U").and_then(Object::as_str_bytes)?;
    if u.len() < 48 {
        return None;
    }
    // Fast paths: derive each candidate file key straight from its key
    // salt and let the encrypted /Perms confirm it (ISO 32000-2 Algorithm
    // 2.A step g validates exactly this way) — one Algorithm 2.B hash per
    // path instead of two. Algorithm 2.B is the whole cost of opening an
    // encrypted document, so this halves it for every file whose /Perms
    // is intact; a wrong password decrypts /Perms to garbage and falls
    // through to the full U/O validation below, unchanged.
    let perms = enc.get("Perms").and_then(Object::as_str_bytes);
    let o = enc.get("O").and_then(Object::as_str_bytes);
    if let Some(perms) = perms.filter(|p| p.len() >= 16) {
        if let Some(ue) = enc.get("UE").and_then(Object::as_str_bytes) {
            if ue.len() >= 32 {
                let intermediate = hash_2b(r, pw, &u[40..48], &[]);
                let file_key = aes_cbc_decrypt_blocks(&intermediate, &[0u8; 16], &ue[..32]);
                if file_key.len() == 32 && perms_marker_valid(&file_key, perms) {
                    return Some(file_key);
                }
            }
        }
        if let (Some(o), Some(oe)) = (o, enc.get("OE").and_then(Object::as_str_bytes)) {
            if o.len() >= 48 && oe.len() >= 32 {
                let intermediate = hash_2b(r, pw, &o[40..48], &u[..48]);
                let file_key = aes_cbc_decrypt_blocks(&intermediate, &[0u8; 16], &oe[..32]);
                if file_key.len() == 32 && perms_marker_valid(&file_key, perms) {
                    return Some(file_key);
                }
            }
        }
    }
    if let Some(ue) = enc.get("UE").and_then(Object::as_str_bytes) {
        if ue.len() >= 32 && hash_2b(r, pw, &u[32..40], &[])[..32] == u[..32] {
            let intermediate = hash_2b(r, pw, &u[40..48], &[]);
            let file_key = aes_cbc_decrypt_blocks(&intermediate, &[0u8; 16], &ue[..32]);
            if file_key.len() == 32 {
                return Some(file_key);
            }
        }
    }
    let o = o?;
    let oe = enc.get("OE").and_then(Object::as_str_bytes)?;
    if o.len() < 48 || oe.len() < 32 {
        return None;
    }
    if hash_2b(r, pw, &o[32..40], &u[..48])[..32] != o[..32] {
        return None;
    }
    let intermediate = hash_2b(r, pw, &o[40..48], &u[..48]);
    let file_key = aes_cbc_decrypt_blocks(&intermediate, &[0u8; 16], &oe[..32]);
    (file_key.len() == 32).then_some(file_key)
}

/// Whether `file_key` decrypts `/Perms` to its mandated marker: bytes 9-11
/// spell "adb" (ISO 32000-2 Algorithm 2.A step g; AES-256 ECB, no IV).
fn perms_marker_valid(file_key: &[u8], perms: &[u8]) -> bool {
    let rks = aes_expand_key(file_key);
    let inv_sbox = aes_inv_sbox();
    let mut block = [0u8; 16];
    block.copy_from_slice(&perms[..16]);
    aes_decrypt_block(&mut block, &rks, &inv_sbox);
    &block[9..12] == b"adb"
}

/// The revision-6 password hash (ISO 32000-2, Algorithm 2.B); a plain SHA-256
/// for revision 5.
fn hash_2b(r: i64, password: &[u8], salt: &[u8], udata: &[u8]) -> Vec<u8> {
    let mut seed = Vec::with_capacity(password.len() + salt.len() + udata.len());
    seed.extend_from_slice(password);
    seed.extend_from_slice(salt);
    seed.extend_from_slice(udata);
    let mut k = sha256(&seed).to_vec();
    if r < 6 {
        return k; // revision 5: a single SHA-256
    }
    let mut round = 0usize;
    let mut k1 = Vec::with_capacity(64 * (password.len() + 64 + udata.len()));
    loop {
        k1.clear();
        for _ in 0..64 {
            k1.extend_from_slice(password);
            k1.extend_from_slice(&k);
            k1.extend_from_slice(udata);
        }
        let e = aes_cbc_encrypt_blocks(&k[..16], &k[16..32], &k1);
        let modulus = e[..16].iter().map(|&b| u32::from(b)).sum::<u32>() % 3;
        k = match modulus {
            0 => sha256(&e).to_vec(),
            1 => sha384(&e),
            _ => sha512(&e),
        };
        round += 1;
        if round >= 64 && usize::from(*e.last().unwrap()) <= round - 32 {
            break;
        }
    }
    k.truncate(32);
    k
}

/// Freshly generated key material for a revision-6 `/Encrypt` dictionary:
/// the random file key plus `/U`, `/UE`, `/O`, `/OE` and `/Perms` derived
/// from it (ISO 32000-2 §7.6.4.3.4-3.6, Algorithms 8, 9 and 10).
pub(crate) struct KeyMaterial {
    file_key: [u8; 32],
    u: Vec<u8>,
    ue: Vec<u8>,
    o: Vec<u8>,
    oe: Vec<u8>,
    perms: Vec<u8>,
}

/// Builds a [`KeyMaterial`] for `user_pw`/`owner_pw` at permission bits `p`
/// (ISO 32000-2 §7.6.4.2, Table 22), recording whether metadata is left
/// unencrypted. `rng` fills the random bytes Algorithms 8-10 call for: the
/// 32-byte file key, the user and owner validation/key salts, and the
/// 4-byte `/Perms` pad. Passwords longer than the 127 UTF-8 bytes the
/// algorithm defines are truncated, matching the validation side.
pub(crate) fn r6_key_material(
    user_pw: &[u8],
    owner_pw: &[u8],
    p: i32,
    encrypt_metadata: bool,
    rng: &mut dyn FnMut(&mut [u8]),
) -> KeyMaterial {
    let user_pw = &user_pw[..user_pw.len().min(127)];
    let owner_pw = &owner_pw[..owner_pw.len().min(127)];

    let mut file_key = [0u8; 32];
    rng(&mut file_key);

    // Algorithm 8: /U and /UE from a 16-byte random pad, the first 8
    // bytes the validation salt and the last 8 the key salt.
    let mut user_salt = [0u8; 16];
    rng(&mut user_salt);
    let mut u = hash_2b(6, user_pw, &user_salt[..8], &[]);
    u.extend_from_slice(&user_salt);
    let user_intermediate = hash_2b(6, user_pw, &user_salt[8..], &[]);
    let ue = aes_cbc_encrypt_blocks(&user_intermediate, &[0u8; 16], &file_key);

    // Algorithm 9: /O and /OE, the same derivation but hashing in the
    // first 48 bytes of /U as well.
    let mut owner_salt = [0u8; 16];
    rng(&mut owner_salt);
    let mut o = hash_2b(6, owner_pw, &owner_salt[..8], &u[..48]);
    o.extend_from_slice(&owner_salt);
    let owner_intermediate = hash_2b(6, owner_pw, &owner_salt[8..], &u[..48]);
    let oe = aes_cbc_encrypt_blocks(&owner_intermediate, &[0u8; 16], &file_key);

    // Algorithm 10: /Perms, the file key applied to a single AES-256 ECB
    // block (not CBC).
    let mut perms_block = [0u8; 16];
    perms_block[..4].copy_from_slice(&p.to_le_bytes());
    perms_block[4..8].copy_from_slice(&[0xff; 4]);
    perms_block[8] = if encrypt_metadata { b'T' } else { b'F' };
    perms_block[9..12].copy_from_slice(b"adb");
    rng(&mut perms_block[12..]);
    aes_encrypt_block(&mut perms_block, &aes_expand_key(&file_key));

    KeyMaterial {
        file_key,
        u,
        ue,
        o,
        oe,
        perms: perms_block.to_vec(),
    }
}

/// Fills `buf` with operating-system random bytes. Not available on
/// `wasm32-unknown-unknown`, where `getrandom` is not a dependency at all;
/// use [`Encryptor::aes256_with_rng`] there with a caller-supplied source.
#[cfg(not(all(target_arch = "wasm32", target_os = "unknown")))]
pub(crate) fn fill_os_random(buf: &mut [u8]) {
    getrandom::fill(buf).expect("OS random number generator unavailable");
}

/// The eight standard-handler permission bits a document opened under the
/// user password (rather than the owner password) is granted (ISO 32000-2
/// §7.6.4.2, Table 22). Bits the standard reserves are not represented
/// here; `p_value` fixes them to the values it mandates.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Permissions {
    /// Print the document, at full quality only when `print_hires` is also
    /// set (Table 22 bit 3).
    pub print: bool,
    /// Modify the document's contents, beyond what `annotate`,
    /// `fill_forms` and `assemble` separately cover (Table 22 bit 4).
    pub modify: bool,
    /// Copy or otherwise extract text and graphics (Table 22 bit 5).
    pub copy: bool,
    /// Add or modify text annotations and fill form fields (Table 22 bit
    /// 6).
    pub annotate: bool,
    /// Fill in existing form fields even without `annotate` (Table 22 bit
    /// 9).
    pub fill_forms: bool,
    /// Extract text and graphics for accessibility (Table 22 bit 10).
    pub accessibility: bool,
    /// Assemble the document: insert, rotate or delete pages, create
    /// bookmarks or thumbnails (Table 22 bit 11).
    pub assemble: bool,
    /// Print at full quality; without it, printing (if `print` allows it)
    /// may be limited to a low-resolution rasterization (Table 22 bit 12).
    pub print_hires: bool,
}

/// The permission names [`Permissions::from_names`] accepts, in the order
/// named in `--allow`/`allow` help text and error messages: `print`,
/// `modify`, `copy`, `annotate`, `fill-forms`, `accessibility`, `assemble`,
/// `print-hires`.
pub const PERMISSION_NAMES: [&str; 8] = [
    "print",
    "modify",
    "copy",
    "annotate",
    "fill-forms",
    "accessibility",
    "assemble",
    "print-hires",
];

impl Permissions {
    /// Every permission granted.
    pub fn all() -> Permissions {
        Permissions {
            print: true,
            modify: true,
            copy: true,
            annotate: true,
            fill_forms: true,
            accessibility: true,
            assemble: true,
            print_hires: true,
        }
    }

    /// Every permission named in `names` granted, everything else denied.
    /// The first name not in [`PERMISSION_NAMES`] comes back as `Err`,
    /// carrying that name alone: the CLI and the Python bindings each wrap
    /// it in their own error type and message text.
    pub fn from_names<'a>(names: impl IntoIterator<Item = &'a str>) -> Result<Permissions, String> {
        let mut permissions = Permissions {
            print: false,
            modify: false,
            copy: false,
            annotate: false,
            fill_forms: false,
            accessibility: false,
            assemble: false,
            print_hires: false,
        };
        for name in names {
            match name {
                "print" => permissions.print = true,
                "modify" => permissions.modify = true,
                "copy" => permissions.copy = true,
                "annotate" => permissions.annotate = true,
                "fill-forms" => permissions.fill_forms = true,
                "accessibility" => permissions.accessibility = true,
                "assemble" => permissions.assemble = true,
                "print-hires" => permissions.print_hires = true,
                other => return Err(other.to_string()),
            }
        }
        Ok(permissions)
    }

    /// The `/P` integer this set of permissions encodes (ISO 32000-2
    /// §7.6.4.2, Table 22): bits 1 and 2 are reserved and always cleared;
    /// bits 3, 4, 5, 6, 9, 10, 11 and 12 carry `print`, `modify`, `copy`,
    /// `annotate`, `fill_forms`, `accessibility`, `assemble` and
    /// `print_hires` in that order; every other bit is reserved and always
    /// set. Granting everything therefore yields `-4`.
    pub(crate) fn p_value(&self) -> i32 {
        let flags: [(u32, bool); 8] = [
            (3, self.print),
            (4, self.modify),
            (5, self.copy),
            (6, self.annotate),
            (9, self.fill_forms),
            (10, self.accessibility),
            (11, self.assemble),
            (12, self.print_hires),
        ];
        let mut bits: u32 = !0b11; // every bit set, then clear the two reserved low bits
        for (bit, granted) in flags {
            if !granted {
                bits &= !(1u32 << (bit - 1));
            }
        }
        bits as i32
    }
}

impl Default for Permissions {
    /// Every permission granted, same as [`Permissions::all`].
    fn default() -> Permissions {
        Permissions::all()
    }
}

/// Builds the complete AES-256, revision 6 `/Encrypt` dictionary
/// (ISO 32000-2 §7.6.4.2) from generated key material: `/Filter /Standard`,
/// `/V 5`, `/R 6`, `/Length 256`, a `/CF` naming the standard crypt filter
/// as `/AESV3` with a 32-byte key, `/StmF` and `/StrF` both pointing at it,
/// and the `/U`, `/UE`, `/O`, `/OE`, `/P` and `/Perms` entries.
fn aes256_encrypt_dict(material: &KeyMaterial, p: i32) -> Dict {
    let mut std_cf = Dict::new();
    std_cf.insert(
        Name("CFM".to_string()),
        Object::Name(Name("AESV3".to_string())),
    );
    std_cf.insert(Name("Length".to_string()), Object::Int(32));
    let mut cf = Dict::new();
    cf.insert(Name("StdCF".to_string()), Object::Dict(std_cf));

    let mut dict = Dict::new();
    dict.insert(
        Name("Filter".to_string()),
        Object::Name(Name("Standard".to_string())),
    );
    dict.insert(Name("V".to_string()), Object::Int(5));
    dict.insert(Name("R".to_string()), Object::Int(6));
    dict.insert(Name("Length".to_string()), Object::Int(256));
    dict.insert(Name("CF".to_string()), Object::Dict(cf));
    dict.insert(
        Name("StmF".to_string()),
        Object::Name(Name("StdCF".to_string())),
    );
    dict.insert(
        Name("StrF".to_string()),
        Object::Name(Name("StdCF".to_string())),
    );
    dict.insert(Name("P".to_string()), Object::Int(i64::from(p)));
    dict.insert(Name("U".to_string()), Object::String(material.u.clone()));
    dict.insert(Name("UE".to_string()), Object::String(material.ue.clone()));
    dict.insert(Name("O".to_string()), Object::String(material.o.clone()));
    dict.insert(Name("OE".to_string()), Object::String(material.oe.clone()));
    dict.insert(
        Name("Perms".to_string()),
        Object::String(material.perms.clone()),
    );
    dict
}

/// A configured Standard-handler encryptor: AES-256, revision 6, the write
/// side of [`Decryptor`]. Built by [`Encryptor::aes256`] or
/// [`Encryptor::aes256_with_rng`], which also return the complete
/// `/Encrypt` dictionary for the trailer.
#[allow(
    clippy::type_complexity,
    reason = "Box<dyn FnMut(&mut [u8]) + Send> names the one random-byte source the write path takes; a type alias would only rename it"
)]
pub struct Encryptor {
    file_key: [u8; 32],
    rng: Box<dyn FnMut(&mut [u8]) + Send>,
}

impl Encryptor {
    /// AES-256 (`/V` 5, `/R` 6) key material from the operating system's
    /// random source (ISO 32000-2 §7.6.4.3). Returns the encryptor plus the
    /// complete `/Encrypt` dictionary to place in the trailer. Passwords
    /// encode as UTF-8 and are truncated to 127 bytes, matching the reader.
    ///
    /// Not available on `wasm32-unknown-unknown`: there is no operating
    /// system random source to draw from there. Use
    /// [`Encryptor::aes256_with_rng`] instead, with caller-supplied
    /// randomness (for example from the host's `crypto.getRandomValues`).
    #[cfg(not(all(target_arch = "wasm32", target_os = "unknown")))]
    pub fn aes256(
        user_password: &str,
        owner_password: &str,
        permissions: Permissions,
    ) -> (Encryptor, Dict) {
        Encryptor::aes256_with_rng(
            user_password,
            owner_password,
            permissions,
            Box::new(fill_os_random),
        )
    }

    /// [`Encryptor::aes256`] with a caller-supplied source of random bytes
    /// in place of the operating system's, for reproducible tests.
    #[allow(clippy::type_complexity, reason = "see Encryptor's rng field")]
    pub fn aes256_with_rng(
        user_password: &str,
        owner_password: &str,
        permissions: Permissions,
        rng: Box<dyn FnMut(&mut [u8]) + Send>,
    ) -> (Encryptor, Dict) {
        let mut rng = rng;
        let p = permissions.p_value();
        let material = r6_key_material(
            user_password.as_bytes(),
            owner_password.as_bytes(),
            p,
            true,
            &mut *rng,
        );
        let dict = aes256_encrypt_dict(&material, p);
        let encryptor = Encryptor {
            file_key: material.file_key,
            rng,
        };
        (encryptor, dict)
    }

    /// Encrypts one indirect object's strings and stream data in place, the
    /// exact inverse of [`Decryptor::decrypt_object`]: every string and
    /// stream body gets a fresh random IV and PKCS#7 padding before
    /// AES-256-CBC under the file key. AESV3 applies the same key to every
    /// object, so `num` and `gen` are accepted and ignored here, purely for
    /// signature symmetry with `decrypt_object`; a future per-object write
    /// cipher (an AESV2 write path, say) would need to start deriving its
    /// key from them instead of discarding them.
    pub fn encrypt_object(&mut self, obj: &mut Object, num: u32, gen: u16) {
        let _ = (num, gen);
        encrypt_in_place(obj, &self.file_key, &mut *self.rng);
    }
}

/// Recursively encrypts every string and stream body reachable from `obj`
/// with the file `key`, mirroring [`decrypt_in_place`]'s walk exactly:
/// `String`, `Array`, `Dict` values and `Stream` (dict values plus data);
/// every other object type is left untouched.
fn encrypt_in_place(obj: &mut Object, key: &[u8], rng: &mut dyn FnMut(&mut [u8])) {
    match obj {
        Object::String(bytes) => *bytes = aes_cbc_encrypt(key, rng, bytes),
        Object::Array(items) => {
            for it in items {
                encrypt_in_place(it, key, &mut *rng);
            }
        }
        Object::Dict(dict) => {
            for v in dict.values_mut() {
                encrypt_in_place(v, key, &mut *rng);
            }
        }
        Object::Stream(stream) => {
            for v in stream.dict.values_mut() {
                encrypt_in_place(v, key, &mut *rng);
            }
            stream.data = aes_cbc_encrypt(key, rng, &stream.data);
        }
        _ => {}
    }
}

/// Per-round left-rotation amounts (RFC 1321).
#[rustfmt::skip]
const MD5_S: [u32; 64] = [
    7, 12, 17, 22, 7, 12, 17, 22, 7, 12, 17, 22, 7, 12, 17, 22,
    5, 9, 14, 20, 5, 9, 14, 20, 5, 9, 14, 20, 5, 9, 14, 20,
    4, 11, 16, 23, 4, 11, 16, 23, 4, 11, 16, 23, 4, 11, 16, 23,
    6, 10, 15, 21, 6, 10, 15, 21, 6, 10, 15, 21, 6, 10, 15, 21,
];

/// Per-round additive constants `floor(2^32 * abs(sin(i + 1)))` (RFC 1321).
#[rustfmt::skip]
const MD5_K: [u32; 64] = [
    0xd76aa478, 0xe8c7b756, 0x242070db, 0xc1bdceee, 0xf57c0faf, 0x4787c62a, 0xa8304613, 0xfd469501,
    0x698098d8, 0x8b44f7af, 0xffff5bb1, 0x895cd7be, 0x6b901122, 0xfd987193, 0xa679438e, 0x49b40821,
    0xf61e2562, 0xc040b340, 0x265e5a51, 0xe9b6c7aa, 0xd62f105d, 0x02441453, 0xd8a1e681, 0xe7d3fbc8,
    0x21e1cde6, 0xc33707d6, 0xf4d50d87, 0x455a14ed, 0xa9e3e905, 0xfcefa3f8, 0x676f02d9, 0x8d2a4c8a,
    0xfffa3942, 0x8771f681, 0x6d9d6122, 0xfde5380c, 0xa4beea44, 0x4bdecfa9, 0xf6bb4b60, 0xbebfbc70,
    0x289b7ec6, 0xeaa127fa, 0xd4ef3085, 0x04881d05, 0xd9d4d039, 0xe6db99e5, 0x1fa27cf8, 0xc4ac5665,
    0xf4292244, 0x432aff97, 0xab9423a7, 0xfc93a039, 0x655b59c3, 0x8f0ccc92, 0xffeff47d, 0x85845dd1,
    0x6fa87e4f, 0xfe2ce6e0, 0xa3014314, 0x4e0811a1, 0xf7537e82, 0xbd3af235, 0x2ad7d2bb, 0xeb86d391,
];

/// One-shot MD5 (RFC 1321). Sufficient for the small key-derivation inputs; not
/// a streaming API.
fn md5(input: &[u8]) -> [u8; 16] {
    let (mut a0, mut b0, mut c0, mut d0) = (
        0x6745_2301u32,
        0xefcd_ab89u32,
        0x98ba_dcfeu32,
        0x1032_5476u32,
    );

    let mut msg = input.to_vec();
    let bitlen = (input.len() as u64).wrapping_mul(8);
    msg.push(0x80);
    while msg.len() % 64 != 56 {
        msg.push(0);
    }
    msg.extend_from_slice(&bitlen.to_le_bytes());

    for chunk in msg.as_chunks::<64>().0 {
        let mut m = [0u32; 16];
        for (word, bytes) in m.iter_mut().zip(chunk.as_chunks::<4>().0) {
            *word = u32::from_le_bytes(*bytes);
        }
        let (mut a, mut b, mut c, mut d) = (a0, b0, c0, d0);
        for i in 0..64 {
            let (f, g) = match i {
                0..=15 => ((b & c) | (!b & d), i),
                16..=31 => ((d & b) | (!d & c), (5 * i + 1) % 16),
                32..=47 => (b ^ c ^ d, (3 * i + 5) % 16),
                _ => (c ^ (b | !d), (7 * i) % 16),
            };
            let f = f.wrapping_add(a).wrapping_add(MD5_K[i]).wrapping_add(m[g]);
            a = d;
            d = c;
            c = b;
            b = b.wrapping_add(f.rotate_left(MD5_S[i]));
        }
        a0 = a0.wrapping_add(a);
        b0 = b0.wrapping_add(b);
        c0 = c0.wrapping_add(c);
        d0 = d0.wrapping_add(d);
    }

    let mut out = [0u8; 16];
    out[0..4].copy_from_slice(&a0.to_le_bytes());
    out[4..8].copy_from_slice(&b0.to_le_bytes());
    out[8..12].copy_from_slice(&c0.to_le_bytes());
    out[12..16].copy_from_slice(&d0.to_le_bytes());
    out
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::object::Name;

    fn hex(bytes: &[u8]) -> String {
        bytes.iter().map(|b| format!("{b:02x}")).collect()
    }

    #[test]
    fn md5_known_vectors() {
        assert_eq!(hex(&md5(b"")), "d41d8cd98f00b204e9800998ecf8427e");
        assert_eq!(hex(&md5(b"abc")), "900150983cd24fb0d6963f7d28e17f72");
        assert_eq!(
            hex(&md5(b"The quick brown fox jumps over the lazy dog")),
            "9e107d9d372bb6826bd81d3542a419d6"
        );
    }

    #[test]
    fn md5_spans_block_boundary() {
        // 56 bytes forces a second padded block.
        let input = [b'a'; 56];
        assert_eq!(hex(&md5(&input)), "3b0c8ac703f828b04c6c197006d17218");
    }

    /// FIPS-197 Appendix C block vectors, both key sizes and both
    /// directions, held against the dispatching entry (the hardware path
    /// wherever this test runs on a CPU with AES instructions) AND the
    /// portable rounds directly, so neither path can drift.
    #[test]
    fn aes_block_known_vectors() {
        let plain: [u8; 16] = core::array::from_fn(|i| (i as u8) * 0x11);
        let key128: [u8; 16] = core::array::from_fn(|i| i as u8);
        let key256: [u8; 32] = core::array::from_fn(|i| i as u8);

        type Encrypt = fn(&mut [u8; 16], &[[u8; 16]]);
        type Decrypt = fn(&mut [u8; 16], &[[u8; 16]], &[u8; 256]);
        let paths: [(Encrypt, Decrypt); 2] = [
            (aes_encrypt_block, aes_decrypt_block),
            (aes_encrypt_block_soft, aes_decrypt_block_soft),
        ];
        for (encrypt, decrypt) in paths {
            let mut s = plain;
            encrypt(&mut s, &aes_expand_key(&key128));
            assert_eq!(hex(&s), "69c4e0d86a7b0430d8cdb78070b4c55a");
            decrypt(&mut s, &aes_expand_key(&key128), &aes_inv_sbox());
            assert_eq!(s, plain);

            let mut s = plain;
            encrypt(&mut s, &aes_expand_key(&key256));
            assert_eq!(hex(&s), "8ea2b7ca516745bfeafc49904b496089");
            decrypt(&mut s, &aes_expand_key(&key256), &aes_inv_sbox());
            assert_eq!(s, plain);
        }
    }

    /// Multi-block CBC round-trips through the block paths, chaining
    /// included: what the R6 hash encrypts, decryption must invert.
    #[test]
    fn aes_cbc_round_trips_multiple_blocks() {
        let key: [u8; 16] = core::array::from_fn(|i| (i as u8).wrapping_mul(7));
        let iv: [u8; 16] = core::array::from_fn(|i| 0xa5 ^ (i as u8));
        let data: Vec<u8> = (0..64u8).collect();
        let ct = aes_cbc_encrypt_blocks(&key, &iv, &data);
        assert_eq!(ct.len(), data.len());
        assert_ne!(ct, data);
        assert_eq!(aes_cbc_decrypt_blocks(&key, &iv, &ct), data);
    }

    /// NIST FIPS 180 vectors for the SHA-2 family, spanning the empty
    /// input, one block, and inputs long enough to cross block
    /// boundaries — the contract the hardware compressions must match.
    #[test]
    fn sha2_known_vectors() {
        assert_eq!(
            hex(&sha256(b"")),
            "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
        );
        assert_eq!(
            hex(&sha256(b"abc")),
            "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
        );
        assert_eq!(
            hex(&sha256(&[b'a'; 200])),
            "c2a908d98f5df987ade41b5fce213067efbcc21ef2240212a41e54b5e7c28ae5"
        );
        assert_eq!(
            hex(&sha384(b"abc")),
            "cb00753f45a35e8bb5a03d699ac65007272c32ab0eded1631a8b605a43ff5bed\
             8086072ba1e7cc2358baeca134c825a7"
        );
        assert_eq!(
            hex(&sha512(b"abc")),
            "ddaf35a193617abacc417349ae20413112e6fa4e89a97ea20a9eeee64b55d39a\
             2192992a274fc1a836ba3c23a3feebbd454d4423643ce80e2a9ac94fa54ca49f"
        );
        assert_eq!(
            hex(&sha512(&[b'a'; 300])),
            "a6a77010dd9696c23831e6549de51724df332c2075039b75fcfe6c2e6de42fbd\
             3c80ed4073267e00c8c320712c3cdd9d65a96f90a3fe4a58a6b70a103be08e83"
        );
    }

    /// The portable compressions must evolve state identically to the
    /// dispatching entries (the hardware path wherever this runs on a CPU
    /// with SHA instructions), block by block.
    #[test]
    fn sha2_soft_compressions_match_the_dispatch() {
        let block64: [u8; 64] = core::array::from_fn(|i| (i as u8).wrapping_mul(31));
        let mut via_dispatch = [0x6a09e667u32; 8];
        let mut via_soft = via_dispatch;
        sha256_compress(&mut via_dispatch, &block64);
        sha256_compress_soft(&mut via_soft, &block64);
        assert_eq!(via_dispatch, via_soft);

        let block128: [u8; 128] = core::array::from_fn(|i| (i as u8).wrapping_mul(29));
        let mut via_dispatch = [0x6a09e667f3bcc908u64; 8];
        let mut via_soft = via_dispatch;
        sha512_compress(&mut via_dispatch, &block128);
        sha512_compress_soft(&mut via_soft, &block128);
        assert_eq!(via_dispatch, via_soft);
    }

    /// The incremental hasher must match the one-shot digest whatever the
    /// slice boundaries: odd sizes, block-straddling feeds, empty updates.
    #[test]
    fn incremental_sha256_matches_the_one_shot() {
        let input: Vec<u8> = (0..300u16).map(|i| (i % 251) as u8).collect();
        for splits in [
            vec![0, 1, 3, 7, 60, 63, 64, 65, 37],
            vec![300],
            vec![128, 128, 44],
            vec![55, 9, 236],
        ] {
            let mut hasher = Sha256::new();
            let mut fed = 0usize;
            for len in splits {
                hasher.update(&input[fed..fed + len]);
                fed += len;
            }
            hasher.update(&input[fed..]);
            assert_eq!(hasher.finalize(), sha256(&input));
        }
        assert_eq!(Sha256::new().finalize(), sha256(b""));
        assert_eq!(Sha256::default().finalize(), sha256(b""));
    }

    #[test]
    fn rc4_known_vector() {
        // Classic RC4 test vector: key "Key", plaintext "Plaintext".
        let ct = rc4(b"Key", b"Plaintext");
        assert_eq!(hex(&ct), "bbf316e8d940af0ad3");
        // Symmetric: decrypting the ciphertext returns the plaintext.
        assert_eq!(rc4(b"Key", &ct), b"Plaintext");
    }

    // --- End-to-end fixture: build a V2/R3 (128-bit RC4) file encrypted under
    // caller-chosen user and owner passwords, then confirm the loader
    // decrypts it — transparently for the empty user password, and through
    // the password APIs for real ones. ---

    const N: usize = 16; // 128-bit key
    const P: i32 = -44;
    const ID0: &[u8] = b"0123456789abcdef";

    /// `/O` for the given owner and user passwords (Algorithm 3, R3).
    fn owner_entry(owner_pw: &[u8], user_pw: &[u8]) -> Vec<u8> {
        let mut d = md5(&pad_password(owner_pw));
        for _ in 0..50 {
            d = md5(&d[..N]);
        }
        let rc4key = d[..N].to_vec();
        let mut o = rc4(&rc4key, &pad_password(user_pw));
        for i in 1u8..=19 {
            let k: Vec<u8> = rc4key.iter().map(|b| b ^ i).collect();
            o = rc4(&k, &o);
        }
        o
    }

    /// File key from `/O` for the given user password (Algorithm 2, R3).
    fn file_key(o: &[u8], user_pw: &[u8]) -> Vec<u8> {
        let mut input = Vec::new();
        input.extend_from_slice(&pad_password(user_pw));
        input.extend_from_slice(o);
        input.extend_from_slice(&(P as u32).to_le_bytes());
        input.extend_from_slice(ID0);
        let mut d = md5(&input);
        for _ in 0..50 {
            d = md5(&d[..N]);
        }
        d[..N].to_vec()
    }

    /// `/U` for the given file key (Algorithm 5, R3).
    fn user_entry(key: &[u8]) -> Vec<u8> {
        let mut input = Vec::new();
        input.extend_from_slice(&PAD);
        input.extend_from_slice(ID0);
        let mut x = md5(&input).to_vec();
        x = rc4(key, &x);
        for i in 1u8..=19 {
            let k: Vec<u8> = key.iter().map(|b| b ^ i).collect();
            x = rc4(&k, &x);
        }
        x.resize(32, 0); // trailing padding is arbitrary
        x
    }

    fn obj_key(key: &[u8], num: u32, gen: u16) -> Vec<u8> {
        let mut input = key.to_vec();
        input.extend_from_slice(&num.to_le_bytes()[..3]);
        input.extend_from_slice(&gen.to_le_bytes()[..2]);
        md5(&input)[..(key.len() + 5).min(16)].to_vec()
    }

    fn hexstr(b: &[u8]) -> String {
        let mut s = String::from("<");
        for x in b {
            s.push_str(&format!("{x:02x}"));
        }
        s.push('>');
        s
    }

    fn encrypted_fixture(u_override: Option<Vec<u8>>) -> Vec<u8> {
        encrypted_fixture_with(b"", b"", u_override)
    }

    fn encrypted_fixture_with(
        user_pw: &[u8],
        owner_pw: &[u8],
        u_override: Option<Vec<u8>>,
    ) -> Vec<u8> {
        use pdfboss_testkit::PdfBuilder;
        let o = owner_entry(owner_pw, user_pw);
        let key = file_key(&o, user_pw);
        let u = u_override.unwrap_or_else(|| user_entry(&key));

        let msg = rc4(&obj_key(&key, 3, 0), b"Top secret message");
        let stream = rc4(&obj_key(&key, 4, 0), b"decrypted stream body");

        let mut b = PdfBuilder::new().version(1, 4);
        b.object(1, "<< /Type /Catalog /Pages 2 0 R >>");
        b.object(2, "<< /Type /Pages /Kids [] /Count 0 >>");
        b.object(3, &format!("<< /Msg {} >>", hexstr(&msg)));
        b.stream(4, "", &stream);
        b.object(
            9,
            &format!(
                "<< /Filter /Standard /V 2 /R 3 /Length 128 /P {P} /O {} /U {} >>",
                hexstr(&o),
                hexstr(&u)
            ),
        );
        let trailer = format!("/Encrypt 9 0 R /ID [{}{}]", hexstr(ID0), hexstr(ID0));
        b.trailer_extra(&trailer).build(1)
    }

    #[test]
    fn document_load_decrypts_standard_rc4() {
        use crate::object::ObjRef;
        use crate::Document;

        let doc = Document::load(encrypted_fixture(None)).expect("empty password opens the file");

        let obj3 = doc.get(ObjRef { num: 3, gen: 0 }).unwrap();
        let msg = obj3
            .as_dict()
            .unwrap()
            .get("Msg")
            .unwrap()
            .as_str_bytes()
            .unwrap();
        assert_eq!(msg, b"Top secret message", "string decrypted");

        let obj4 = doc.get(ObjRef { num: 4, gen: 0 }).unwrap();
        let data = doc.stream_data(obj4.as_stream().unwrap()).unwrap();
        assert_eq!(data, b"decrypted stream body", "stream decrypted");
    }

    #[test]
    fn document_load_rejects_when_password_does_not_verify() {
        use crate::error::Error;
        use crate::Document;

        // A `/U` that will not verify under the empty password stands in for a
        // real password-protected file: the loader must decline, not decrypt.
        let bad_u = vec![0u8; 32];
        let err = Document::load(encrypted_fixture(Some(bad_u)));
        assert!(matches!(err, Err(Error::Encrypted)));
    }

    #[test]
    fn real_user_password_opens_an_rc4_file() {
        use crate::error::Error;
        use crate::object::ObjRef;
        use crate::Document;

        let bytes = encrypted_fixture_with(b"hunter2", b"owner-secret", None);
        assert!(
            matches!(Document::load(bytes.clone()), Err(Error::Encrypted)),
            "without the password the file stays closed"
        );
        let doc = Document::load_with_password(bytes, "hunter2").expect("user password opens");
        let obj3 = doc.get(ObjRef { num: 3, gen: 0 }).unwrap();
        let msg = obj3.as_dict().unwrap().get("Msg").unwrap();
        assert_eq!(msg.as_str_bytes().unwrap(), b"Top secret message");
    }

    #[test]
    fn owner_password_opens_an_rc4_file() {
        use crate::object::ObjRef;
        use crate::Document;

        let bytes = encrypted_fixture_with(b"hunter2", b"owner-secret", None);
        let doc =
            Document::load_with_password(bytes, "owner-secret").expect("owner password opens");
        let obj3 = doc.get(ObjRef { num: 3, gen: 0 }).unwrap();
        let msg = obj3.as_dict().unwrap().get("Msg").unwrap();
        assert_eq!(msg.as_str_bytes().unwrap(), b"Top secret message");
    }

    #[test]
    fn wrong_password_stays_encrypted() {
        use crate::error::Error;
        use crate::Document;

        let bytes = encrypted_fixture_with(b"hunter2", b"owner-secret", None);
        let err = Document::load_with_password(bytes, "letmein");
        assert!(matches!(err, Err(Error::Encrypted)));
    }

    #[test]
    fn real_passwords_open_an_aes256_r6_file() {
        use crate::error::Error;
        use crate::object::ObjRef;
        use crate::Document;

        let bytes = encrypted_fixture_aesv3_with(6, "pässword".as_bytes(), b"owner-secret");
        assert!(
            matches!(Document::load(bytes.clone()), Err(Error::Encrypted)),
            "without the password the file stays closed"
        );
        for pw in ["pässword", "owner-secret"] {
            let doc = Document::load_with_password(bytes.clone(), pw)
                .unwrap_or_else(|_| panic!("{pw:?} opens the file"));
            let obj3 = doc.get(ObjRef { num: 3, gen: 0 }).unwrap();
            let msg = obj3.as_dict().unwrap().get("Msg").unwrap();
            assert_eq!(msg.as_str_bytes().unwrap(), b"AES-256 secret");
        }
        assert!(matches!(
            Document::load_with_password(bytes, "letmein"),
            Err(Error::Encrypted)
        ));
    }

    #[test]
    fn empty_password_files_still_open_through_the_password_api() {
        use crate::object::ObjRef;
        use crate::Document;

        // Passing a password to an empty-password file must not break it:
        // the empty user password still verifies... only if the caller's
        // password IS empty; a random one is simply wrong for this file.
        let doc = Document::load_with_password(encrypted_fixture(None), "")
            .expect("the empty password opens through the password API too");
        let obj3 = doc.get(ObjRef { num: 3, gen: 0 }).unwrap();
        let msg = obj3.as_dict().unwrap().get("Msg").unwrap();
        assert_eq!(msg.as_str_bytes().unwrap(), b"Top secret message");
    }

    #[test]
    fn unsupported_handler_is_declined() {
        // A future/unknown handler version is declined so the caller reports the
        // file as encrypted-and-unsupported.
        let mut enc = Dict::new();
        enc.insert(Name("Filter".into()), Object::Name(Name("Standard".into())));
        enc.insert(Name("V".into()), Object::Int(6));
        enc.insert(Name("R".into()), Object::Int(7));
        enc.insert(Name("O".into()), Object::String(vec![0; 48]));
        enc.insert(Name("U".into()), Object::String(vec![0; 48]));
        enc.insert(Name("P".into()), Object::Int(-4));
        assert!(Decryptor::from_standard(&enc, ID0).is_none());
    }

    // --- AES / SHA-2 known-answer vectors ---

    #[test]
    fn aes_fips197_block_vectors() {
        // FIPS-197 Appendix C.1 (AES-128) and C.3 (AES-256), same plaintext.
        let pt: [u8; 16] = [
            0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd,
            0xee, 0xff,
        ];
        let key128: Vec<u8> = (0u8..16).collect();
        let rks = aes_expand_key(&key128);
        let mut b = pt;
        aes_encrypt_block(&mut b, &rks);
        assert_eq!(hex(&b), "69c4e0d86a7b0430d8cdb78070b4c55a");
        aes_decrypt_block(&mut b, &rks, &aes_inv_sbox());
        assert_eq!(b, pt, "AES-128 decrypt inverts encrypt");

        let key256: Vec<u8> = (0u8..32).collect();
        let rks = aes_expand_key(&key256);
        let mut b = pt;
        aes_encrypt_block(&mut b, &rks);
        assert_eq!(hex(&b), "8ea2b7ca516745bfeafc49904b496089");
    }

    #[test]
    fn sha2_vectors() {
        assert_eq!(
            hex(&sha256(b"abc")),
            "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
        );
        assert_eq!(
            hex(&sha512(b"abc")),
            "ddaf35a193617abacc417349ae20413112e6fa4e89a97ea20a9eeee64b55d39a\
             2192992a274fc1a836ba3c23a3feebbd454d4423643ce80e2a9ac94fa54ca49f"
        );
        assert_eq!(
            hex(&sha384(b"abc")),
            "cb00753f45a35e8bb5a03d699ac65007272c32ab0eded1631a8b605a43ff5bed\
             8086072ba1e7cc2358baeca134c825a7"
        );
    }

    #[test]
    fn aes_cbc_roundtrip() {
        let key: Vec<u8> = (0u8..16).collect();
        let iv = [0x24u8; 16];
        let pt = b"a message spanning several AES blocks exactly?!!";
        let ct = aes_cbc_encrypt_blocks(&key, &iv, &pkcs7_pad(pt));
        let mut val = iv.to_vec(); // PDF format: IV followed by ciphertext
        val.extend_from_slice(&ct);
        assert_eq!(aes_cbc_decrypt(&key, &val), pt);
    }

    // --- AESV2 (V4/R4) end-to-end fixture ---

    fn obj_key_aes(key: &[u8], num: u32, gen: u16) -> Vec<u8> {
        let mut input = key.to_vec();
        input.extend_from_slice(&num.to_le_bytes()[..3]);
        input.extend_from_slice(&gen.to_le_bytes()[..2]);
        input.extend_from_slice(b"sAlT");
        md5(&input)[..(key.len() + 5).min(16)].to_vec()
    }

    /// Encrypts as a PDF AES value: a 16-byte IV followed by CBC ciphertext of
    /// the PKCS#7-padded plaintext.
    fn aes_encrypt_pdf(key: &[u8], pt: &[u8], iv: &[u8; 16]) -> Vec<u8> {
        let mut out = iv.to_vec();
        out.extend_from_slice(&aes_cbc_encrypt_blocks(key, iv, &pkcs7_pad(pt)));
        out
    }

    fn encrypted_fixture_aesv2() -> Vec<u8> {
        use pdfboss_testkit::PdfBuilder;
        let o = owner_entry(b"", b"");
        let key = file_key(&o, b""); // R4 derivation matches R3 (EncryptMetadata true)
        let u = user_entry(&key);
        let iv = [0x11u8; 16];
        let msg = aes_encrypt_pdf(&obj_key_aes(&key, 3, 0), b"Top secret message", &iv);
        let stream = aes_encrypt_pdf(&obj_key_aes(&key, 4, 0), b"decrypted stream body", &iv);

        let mut b = PdfBuilder::new().version(1, 5);
        b.object(1, "<< /Type /Catalog /Pages 2 0 R >>");
        b.object(2, "<< /Type /Pages /Kids [] /Count 0 >>");
        b.object(3, &format!("<< /Msg {} >>", hexstr(&msg)));
        b.stream(4, "", &stream);
        b.object(
            9,
            &format!(
                "<< /Filter /Standard /V 4 /R 4 /Length 128 /P {P} /O {} /U {} \
                 /CF << /StdCF << /CFM /AESV2 /Length 16 >> >> /StmF /StdCF /StrF /StdCF >>",
                hexstr(&o),
                hexstr(&u)
            ),
        );
        let trailer = format!("/Encrypt 9 0 R /ID [{}{}]", hexstr(ID0), hexstr(ID0));
        b.trailer_extra(&trailer).build(1)
    }

    #[test]
    fn document_load_decrypts_aesv2() {
        use crate::object::ObjRef;
        use crate::Document;
        let doc = Document::load(encrypted_fixture_aesv2()).expect("AESV2 empty password opens");
        let obj3 = doc.get(ObjRef { num: 3, gen: 0 }).unwrap();
        let msg = obj3
            .as_dict()
            .unwrap()
            .get("Msg")
            .unwrap()
            .as_str_bytes()
            .unwrap();
        assert_eq!(msg, b"Top secret message");
        let obj4 = doc.get(ObjRef { num: 4, gen: 0 }).unwrap();
        assert_eq!(
            doc.stream_data(obj4.as_stream().unwrap()).unwrap(),
            b"decrypted stream body"
        );
    }

    // --- AESV3 (V5/R5 and R6) end-to-end fixture ---

    fn encrypted_fixture_aesv3(r: i64) -> Vec<u8> {
        encrypted_fixture_aesv3_with(r, b"", b"")
    }

    fn encrypted_fixture_aesv3_with(r: i64, user_pw: &[u8], owner_pw: &[u8]) -> Vec<u8> {
        encrypted_fixture_aesv3_with_metadata(r, user_pw, owner_pw, true, None)
    }

    /// [`encrypted_fixture_aesv3_with`], plus an `/EncryptMetadata` entry
    /// and, when `metadata` is given, object 5 as a `/Type /Metadata`
    /// stream holding its bytes verbatim (never encrypted here, since a
    /// real writer with `encrypt_metadata` false stores it in plaintext
    /// too): the fixture a reader must not corrupt.
    fn encrypted_fixture_aesv3_with_metadata(
        r: i64,
        user_pw: &[u8],
        owner_pw: &[u8],
        encrypt_metadata: bool,
        metadata: Option<&[u8]>,
    ) -> Vec<u8> {
        use pdfboss_testkit::PdfBuilder;
        let key: Vec<u8> = (0u8..32).map(|i| i ^ 0x5a).collect(); // arbitrary 256-bit file key
        let vsalt: [u8; 8] = [1, 2, 3, 4, 5, 6, 7, 8];
        let ksalt: [u8; 8] = [9, 10, 11, 12, 13, 14, 15, 16];
        let mut u = hash_2b(r, user_pw, &vsalt, &[]); // 32-byte validation hash
        u.extend_from_slice(&vsalt);
        u.extend_from_slice(&ksalt);
        let intermediate = hash_2b(r, user_pw, &ksalt, &[]);
        let ue = aes_cbc_encrypt_blocks(&intermediate, &[0u8; 16], &key);
        // The owner hashes additionally salt in the first 48 bytes of /U.
        let ovsalt: [u8; 8] = [21, 22, 23, 24, 25, 26, 27, 28];
        let oksalt: [u8; 8] = [31, 32, 33, 34, 35, 36, 37, 38];
        let mut o = hash_2b(r, owner_pw, &ovsalt, &u[..48]);
        o.extend_from_slice(&ovsalt);
        o.extend_from_slice(&oksalt);
        let ointermediate = hash_2b(r, owner_pw, &oksalt, &u[..48]);
        let oe = aes_cbc_encrypt_blocks(&ointermediate, &[0u8; 16], &key);
        let iv = [0x22u8; 16];
        let msg = aes_encrypt_pdf(&key, b"AES-256 secret", &iv);
        let stream = aes_encrypt_pdf(&key, b"AES-256 stream body", &iv);

        let mut b = PdfBuilder::new().version(1, 7);
        let catalog = match metadata {
            Some(_) => "<< /Type /Catalog /Pages 2 0 R /Metadata 5 0 R >>",
            None => "<< /Type /Catalog /Pages 2 0 R >>",
        };
        b.object(1, catalog);
        b.object(2, "<< /Type /Pages /Kids [] /Count 0 >>");
        b.object(3, &format!("<< /Msg {} >>", hexstr(&msg)));
        b.stream(4, "", &stream);
        if let Some(metadata) = metadata {
            b.stream(5, "<< /Type /Metadata /Subtype /XML >>", metadata);
        }
        let encrypt_metadata_entry = if encrypt_metadata {
            ""
        } else {
            " /EncryptMetadata false"
        };
        b.object(
            9,
            &format!(
                "<< /Filter /Standard /V 5 /R {r} /Length 256 /P {P} /U {} /UE {} \
                 /O {} /OE {}{encrypt_metadata_entry} \
                 /CF << /StdCF << /CFM /AESV3 /Length 32 >> >> /StmF /StdCF /StrF /StdCF >>",
                hexstr(&u),
                hexstr(&ue),
                hexstr(&o),
                hexstr(&oe)
            ),
        );
        let trailer = format!("/Encrypt 9 0 R /ID [{}{}]", hexstr(ID0), hexstr(ID0));
        b.trailer_extra(&trailer).build(1)
    }

    fn assert_aesv3_decrypts(r: i64) {
        use crate::object::ObjRef;
        use crate::Document;
        let doc = Document::load(encrypted_fixture_aesv3(r)).expect("AESV3 empty password opens");
        let obj3 = doc.get(ObjRef { num: 3, gen: 0 }).unwrap();
        let msg = obj3
            .as_dict()
            .unwrap()
            .get("Msg")
            .unwrap()
            .as_str_bytes()
            .unwrap();
        assert_eq!(msg, b"AES-256 secret", "R{r} string");
        let obj4 = doc.get(ObjRef { num: 4, gen: 0 }).unwrap();
        assert_eq!(
            doc.stream_data(obj4.as_stream().unwrap()).unwrap(),
            b"AES-256 stream body",
            "R{r} stream"
        );
    }

    #[test]
    fn document_load_decrypts_aesv3_r5() {
        assert_aesv3_decrypts(5);
    }

    #[test]
    fn document_load_decrypts_aesv3_r6() {
        assert_aesv3_decrypts(6); // exercises the iterated Algorithm 2.B hash
    }

    #[test]
    fn encrypt_metadata_false_leaves_the_metadata_stream_plaintext() {
        use crate::object::ObjRef;
        use crate::Document;

        const XMP: &[u8] = b"<?xpacket begin='' id='W5M0MpCehiHzreSzNTczkc9d'?>\
            <x:xmpmeta xmlns:x='adobe:ns:meta/'><rdf:RDF \
            xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#'><rdf:Description \
            xmlns:dc='http://purl.org/dc/elements/1.1/'><dc:title>XMP Secret \
            Title</dc:title></rdf:Description></rdf:RDF></x:xmpmeta><?xpacket end='w'?>";

        let bytes =
            encrypted_fixture_aesv3_with_metadata(6, b"user-pw", b"owner-pw", false, Some(XMP));
        let doc = Document::load_with_password(bytes, "user-pw").expect("user password opens");

        let obj3 = doc.get(ObjRef { num: 3, gen: 0 }).unwrap();
        let msg = obj3.as_dict().unwrap().get("Msg").unwrap();
        assert_eq!(
            msg.as_str_bytes().unwrap(),
            b"AES-256 secret",
            "an ordinary string still decrypts under EncryptMetadata false"
        );

        let obj5 = doc.get(ObjRef { num: 5, gen: 0 }).unwrap();
        let metadata = doc.stream_data(obj5.as_stream().unwrap()).unwrap();
        assert_eq!(
            metadata, XMP,
            "the metadata stream was stored in plaintext and must not be decrypted"
        );
    }

    // --- R6 key material (write side): the existing validation code above
    // is the oracle everything generated here must open under. ---

    /// Generated key material must open through the same `aesv3_key`
    /// validation a real reader runs, for both passwords, and reject a
    /// wrong one; the embedded `/Perms` must decrypt to its marker under
    /// the generated file key. The dict comes from `aes256_encrypt_dict`,
    /// the same builder `Encryptor::aes256_with_rng` ships, so this test
    /// exercises the real production layout rather than a hand-built one.
    #[test]
    fn r6_key_material_opens_under_aesv3_key() {
        let mut c = 0u8;
        let mut rng = |b: &mut [u8]| {
            for x in b {
                c = c.wrapping_add(1);
                *x = c;
            }
        };
        let material = r6_key_material(b"user-pw", b"owner-pw", P, true, &mut rng);
        let dict = aes256_encrypt_dict(&material, P);

        let user_key = aesv3_key(&dict, 6, b"user-pw").expect("user password opens");
        assert_eq!(user_key, material.file_key.to_vec());

        let owner_key = aesv3_key(&dict, 6, b"owner-pw").expect("owner password opens");
        assert_eq!(owner_key, material.file_key.to_vec());

        assert!(aesv3_key(&dict, 6, b"wrong-pw").is_none());

        assert!(perms_marker_valid(&material.file_key, &material.perms));

        // With /Perms absent, aesv3_key skips the fast path and falls
        // through to comparing the /U and /O validation hashes directly,
        // proving those 32 bytes (not just the key-salt derivation the
        // fast path above exercised) are correct too.
        let mut without_perms = dict.clone();
        without_perms.remove("Perms");
        assert_eq!(
            aesv3_key(&without_perms, 6, b"user-pw"),
            Some(material.file_key.to_vec())
        );
        assert_eq!(
            aesv3_key(&without_perms, 6, b"owner-pw"),
            Some(material.file_key.to_vec())
        );
    }

    // --- Permissions: the /P bit layout (ISO 32000-2 Table 22) ---

    #[test]
    fn permissions_all_grants_every_bit() {
        // Bits 1-2 reserved and cleared, every other bit set: -4.
        assert_eq!(Permissions::all().p_value(), -4);
        assert_eq!(Permissions::default().p_value(), -4);
    }

    #[test]
    fn permissions_p_value_clears_exactly_its_own_bit() {
        let base = Permissions::all().p_value();
        assert_eq!(
            Permissions {
                print: false,
                ..Permissions::all()
            }
            .p_value(),
            base & !(1 << 2), // bit 3
        );
        assert_eq!(
            Permissions {
                modify: false,
                ..Permissions::all()
            }
            .p_value(),
            base & !(1 << 3), // bit 4
        );
        assert_eq!(
            Permissions {
                copy: false,
                ..Permissions::all()
            }
            .p_value(),
            base & !(1 << 4), // bit 5
        );
        assert_eq!(
            Permissions {
                annotate: false,
                ..Permissions::all()
            }
            .p_value(),
            base & !(1 << 5), // bit 6
        );
        assert_eq!(
            Permissions {
                fill_forms: false,
                ..Permissions::all()
            }
            .p_value(),
            base & !(1 << 8), // bit 9
        );
        assert_eq!(
            Permissions {
                accessibility: false,
                ..Permissions::all()
            }
            .p_value(),
            base & !(1 << 9), // bit 10
        );
        assert_eq!(
            Permissions {
                assemble: false,
                ..Permissions::all()
            }
            .p_value(),
            base & !(1 << 10), // bit 11
        );
        assert_eq!(
            Permissions {
                print_hires: false,
                ..Permissions::all()
            }
            .p_value(),
            base & !(1 << 11), // bit 12
        );
    }

    // --- Encryptor (write side): the round-trip proof for Task 2 ---

    /// A `FnMut(&mut [u8])` filling buffers from an incrementing counter,
    /// so key material and IVs are reproducible without touching the OS
    /// random source.
    #[allow(clippy::type_complexity, reason = "see Encryptor's rng field")]
    fn counter_rng() -> Box<dyn FnMut(&mut [u8]) + Send> {
        let mut c = 0u8;
        Box::new(move |buf: &mut [u8]| {
            for b in buf {
                c = c.wrapping_add(1);
                *b = c;
            }
        })
    }

    /// Recovers the file key from a produced `/Encrypt` dict through the
    /// same `aesv3_key` validation a real reader runs, and builds the
    /// matching `Decryptor`: the oracle every encrypted object must open
    /// under.
    fn decryptor_for(dict: &Dict, password: &[u8]) -> Decryptor {
        let key = aesv3_key(dict, 6, password).expect("password opens the produced dict");
        Decryptor {
            key,
            cipher: Cipher::Aesv3,
            encrypt_metadata: true,
        }
    }

    #[test]
    fn encrypt_object_round_trips_dict_array_and_leaves_other_types_untouched() {
        use crate::object::ObjRef;

        let (mut enc, dict) =
            Encryptor::aes256_with_rng("user-pw", "owner-pw", Permissions::all(), counter_rng());

        let mut d = Dict::new();
        d.insert(
            Name("Msg".to_string()),
            Object::String(b"Top secret message".to_vec()),
        );
        d.insert(
            Name("List".to_string()),
            Object::Array(vec![
                Object::String(b"first".to_vec()),
                Object::String(b"second".to_vec()),
            ]),
        );
        d.insert(
            Name("Ref".to_string()),
            Object::Ref(ObjRef { num: 7, gen: 0 }),
        );
        d.insert(
            Name("Kind".to_string()),
            Object::Name(Name("Example".to_string())),
        );
        d.insert(Name("Count".to_string()), Object::Int(42));
        d.insert(Name("Scale".to_string()), Object::Real(1.5));
        d.insert(Name("On".to_string()), Object::Bool(true));
        d.insert(Name("Missing".to_string()), Object::Null);
        let original = Object::Dict(d);

        let mut obj = original.clone();
        enc.encrypt_object(&mut obj, 3, 0);
        assert_ne!(obj, original, "encryption must change the strings");

        // Ref, Name, numbers, bools and null pass through untouched, even
        // in the still-encrypted object.
        let (enc_dict, orig_dict) = (obj.as_dict().unwrap(), original.as_dict().unwrap());
        for key in ["Ref", "Kind", "Count", "Scale", "On", "Missing"] {
            assert_eq!(
                enc_dict.get(key),
                orig_dict.get(key),
                "{key} passes through untouched"
            );
        }

        let decryptor = decryptor_for(&dict, b"user-pw");
        let mut roundtripped = obj.clone();
        decryptor.decrypt_object(&mut roundtripped, 3, 0);
        assert_eq!(roundtripped, original);

        // The owner password recovers the same file key.
        let owner_decryptor = decryptor_for(&dict, b"owner-pw");
        let mut via_owner = obj;
        owner_decryptor.decrypt_object(&mut via_owner, 3, 0);
        assert_eq!(via_owner, original);
    }

    #[test]
    fn encrypt_object_round_trips_a_stream_and_its_dict() {
        use crate::object::Stream;

        let (mut enc, dict) =
            Encryptor::aes256_with_rng("", "owner-pw", Permissions::all(), counter_rng());

        let mut stream_dict = Dict::new();
        stream_dict.insert(
            Name("Producer".to_string()),
            Object::String(b"pdfboss".to_vec()),
        );
        let original = Object::Stream(Stream {
            dict: stream_dict,
            data: b"decrypted stream body".to_vec(),
        });
        let mut obj = original.clone();
        enc.encrypt_object(&mut obj, 4, 0);
        let encrypted = obj.as_stream().unwrap();
        assert_ne!(encrypted.data, original.as_stream().unwrap().data);
        assert_ne!(
            encrypted.dict.get("Producer"),
            original.as_stream().unwrap().dict.get("Producer"),
            "the stream dict's own strings are encrypted too"
        );

        let decryptor = decryptor_for(&dict, b"");
        let mut roundtripped = obj;
        decryptor.decrypt_object(&mut roundtripped, 4, 0);
        assert_eq!(roundtripped, original);
    }

    #[test]
    fn encrypt_object_round_trips_padding_edge_lengths() {
        let (mut enc, dict) =
            Encryptor::aes256_with_rng("pw", "owner", Permissions::all(), counter_rng());
        let decryptor = decryptor_for(&dict, b"pw");

        for plaintext in [Vec::new(), vec![0x41], vec![0x42; 16]] {
            let original = Object::String(plaintext.clone());
            let mut obj = original.clone();
            enc.encrypt_object(&mut obj, 1, 0);
            let mut roundtripped = obj;
            decryptor.decrypt_object(&mut roundtripped, 1, 0);
            assert_eq!(roundtripped, original, "{} bytes", plaintext.len());
        }
    }
}