flpdf 0.1.8

A pure-Rust PDF toolkit modeled on qpdf — read, rewrite, linearize, and inspect PDFs.
Documentation
//! User-facing encryption parameters for the writer side.
//!
//! Callers populate [`EncryptParams`] from CLI flags (or library API
//! arguments) and pass it through [`crate::WriteOptions::encrypt`]; the
//! writer takes care of resolving `/ID[0]`, deriving the file encryption
//! key, building the `/Encrypt` dictionary, emitting it as an indirect
//! object, encrypting every string and stream payload at emission time,
//! and exempting `/Metadata` when `encrypt_metadata == false`.
//!
//! # Algorithm coverage
//!
//! Wired through end to end: `V=4 R=4 Length=128 /CFM AESV2` (AES-128),
//! `V=5 R=6 Length=256 /CFM AESV3` (AES-256), and
//! `V=5 R=5 Length=256 /CFM AESV3` (deprecated pre-ISO 32000-2 AES-256).
//! The remaining Standard handler revisions (V=1, V=2, V=4 RC4) have their
//! dictionary builders shipped already but no writer integration yet.
//!
//! # Randomness
//!
//! AES-CBC stream/string encryption requires a fresh IV per ciphertext
//! (IV reuse with the same key under CBC leaks plaintext XORs — a well-
//! known weakness). The writer fills IVs via [`getrandom::getrandom`]
//! (OS CSPRNG). The deterministic-IV opt-in for byte-identical CI
//! testing is the separate `--static-aes-iv` flag.

use crate::object::Dictionary;
use crate::permissions::PermissionsConfig;
use crate::security::standard::ObjectKeyAlg;

/// Encryption method to apply at write time.
///
/// The Standard handler V/R/Length/CFM tuple is encoded as one enum
/// variant per (algorithm × key-length × cipher) combination, so callers
/// pick a method rather than threading three integers and a CFM name
/// separately.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum EncryptMethod {
    /// V=4 R=4 Length=128 with `/CFM AESV2` (AES-128 CBC). Default for
    /// `qpdf --encrypt … 128 --use-aes=y --`.
    V4Aes128,
    /// V=5 R=6 Length=256 with `/CFM AESV3` (AES-256 CBC, ISO 32000-2).
    /// Selected by `qpdf --encrypt … 256 --`. The 32-byte file key is used
    /// directly for every object (no Algorithm-1 per-object derivation).
    V5R6Aes256,
    /// V=5 R=5 Length=256 with `/CFM AESV3` (AES-256 CBC, pre-ISO 32000-2, deprecated).
    /// Selected by `qpdf --encrypt … 256 --force-R5 --`. The 32-byte file key is used
    /// directly. Deprecated in favour of R=6; discouraged by qpdf itself.
    V5R5Aes256,
    /// V=1 R=2 Length=40 RC4-40. Selected by `qpdf --encrypt … 40 --`.
    /// Weak crypto — gated behind `--allow-weak-crypto` at the CLI.
    V1Rc440,
    /// V=2 R=3 Length=128 RC4-128. qpdf's default for `--encrypt … 128 --`
    /// without `--use-aes=y`. Weak crypto.
    V2Rc4128,
    /// V=4 R=4 Length=128 with `/CFM V2` (RC4-128 crypt filter). Selected by
    /// `qpdf --encrypt … 128 --force-V4 --` without `--use-aes=y`. Weak crypto.
    V4Rc4128,
}

/// User-facing encryption parameters for the writer.
///
/// Set via [`crate::WriteOptions::encrypt`]. The CLI populates these from
/// `--encrypt user-pw owner-pw key-len -- [--print …] [--modify …] [...]`;
/// library callers can construct one directly.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct EncryptParams {
    /// Standard handler V/R/Length/CFM tuple to emit.
    pub method: EncryptMethod,
    /// User-password bytes, already normalized per the appropriate
    /// [`PasswordMode`](crate::PasswordMode). For V=4 (this PR) the bytes
    /// mode is the spec-defined `Bytes` interpretation.
    pub user_password: Vec<u8>,
    /// Owner-password bytes, already normalized. Empty falls back to the
    /// user password per Algorithm 3 step 1 inside the dict builder.
    pub owner_password: Vec<u8>,
    /// Capability flags encoded into `/P` via
    /// [`PermissionsConfig::to_p_bits`].
    pub permissions: PermissionsConfig,
    /// Whether the `/Metadata` stream is encrypted alongside the rest of
    /// the document. When `false`, the writer:
    ///
    /// 1. Emits `/EncryptMetadata false` in the `/Encrypt` dictionary.
    /// 2. Appends the `0xFF×4` tail to the Algorithm 2 file-key MD5 input.
    /// 3. Skips encryption on the `/Metadata` stream payload and prepends
    ///    `/Crypt` + `/DecodeParms <</Name /Identity>>` to its filter
    ///    chain so readers know not to decrypt those bytes.
    pub encrypt_metadata: bool,
}

impl EncryptParams {
    /// Convenience constructor for the V=4 AES-128 case
    /// with the default "all permissions granted" permission set and
    /// `encrypt_metadata = true`.
    pub fn v4_aes128(
        user_password: impl Into<Vec<u8>>,
        owner_password: impl Into<Vec<u8>>,
    ) -> Self {
        Self {
            method: EncryptMethod::V4Aes128,
            user_password: user_password.into(),
            owner_password: owner_password.into(),
            permissions: PermissionsConfig::default(),
            encrypt_metadata: true,
        }
    }

    /// Convenience constructor for the V=5 R=6 AES-256 case with the default
    /// "all permissions granted" permission set and `encrypt_metadata = true`.
    ///
    /// Unlike V<5 there is no empty-owner fallback to the user password — the
    /// owner password is passed through verbatim.
    pub fn v5_r6(user_password: impl Into<Vec<u8>>, owner_password: impl Into<Vec<u8>>) -> Self {
        Self {
            method: EncryptMethod::V5R6Aes256,
            user_password: user_password.into(),
            owner_password: owner_password.into(),
            permissions: PermissionsConfig::default(),
            encrypt_metadata: true,
        }
    }

    /// Convenience constructor for the V=5 R=5 AES-256 case (deprecated pre-ISO 32000-2).
    /// Selected by `--force-R5`. Same password / permissions / metadata semantics as
    /// `v5_r6` — only the revision and hash algorithm differ.
    pub fn v5_r5(user_password: impl Into<Vec<u8>>, owner_password: impl Into<Vec<u8>>) -> Self {
        Self {
            method: EncryptMethod::V5R5Aes256,
            user_password: user_password.into(),
            owner_password: owner_password.into(),
            permissions: PermissionsConfig::default(),
            encrypt_metadata: true,
        }
    }

    /// Convenience constructor for an RC4 method (V=1 RC4-40, V=2 RC4-128, or
    /// V=4 RC4-128) with the default "all permissions granted" set. RC4 has no
    /// `/EncryptMetadata` concept for V=1/V=2 (the field is ignored there);
    /// `encrypt_metadata = true` is kept for the V=4 RC4 case.
    pub fn rc4(
        method: EncryptMethod,
        user_password: impl Into<Vec<u8>>,
        owner_password: impl Into<Vec<u8>>,
    ) -> Self {
        debug_assert!(
            matches!(
                method,
                EncryptMethod::V1Rc440 | EncryptMethod::V2Rc4128 | EncryptMethod::V4Rc4128
            ),
            "EncryptParams::rc4 requires an RC4 method"
        );
        Self {
            method,
            user_password: user_password.into(),
            owner_password: owner_password.into(),
            permissions: PermissionsConfig::default(),
            encrypt_metadata: true,
        }
    }

    /// True when this method uses RC4 (a weak cipher gated behind
    /// `--allow-weak-crypto` at the CLI): V=1, V=2, or V=4 with `/CFM V2`.
    pub fn is_weak_rc4(&self) -> bool {
        matches!(
            self.method,
            EncryptMethod::V1Rc440 | EncryptMethod::V2Rc4128 | EncryptMethod::V4Rc4128
        )
    }

    /// True when this method writes deprecated revision-5 (V=5 R=5,
    /// pre-ISO 32000-2) AES-256 output. R=5 was dropped from the published
    /// standard in favour of R=6, so the CLI gates *creating* R=5 files
    /// behind `--allow-weak-crypto`, mirroring the reader, which rejects R=5
    /// input unless the same opt-in is given.
    ///
    /// This is disjoint from [`is_weak_rc4`](Self::is_weak_rc4): R=5 still
    /// uses AES-256, not RC4. Both classify methods the CLI refuses to write
    /// without the explicit weak-crypto opt-in.
    pub fn is_deprecated_r5(&self) -> bool {
        matches!(self.method, EncryptMethod::V5R5Aes256)
    }
}

/// Donor `/Encrypt` dictionary and derived file key for the
/// `--copy-encryption-from` write path.
///
/// Built by the CLI layer from the donor PDF's on-disk state (opened with
/// [`crate::Pdf::open_with_options`]) and stored in
/// [`crate::WriteOptions::copy_encryption`].  The writer uses it to construct
/// an `EncryptionContext` directly, bypassing the normal
/// password-derivation path.
///
/// **Scope:** Only V=4 AES-128 donors are supported in this release.
/// Donors using other schemes (V=1/V=2/V=4 RC4/V=5 R=6) are rejected at the
/// CLI layer with a clear "not yet supported" diagnostic.
#[derive(Debug, Clone)]
pub struct CopyEncryptionSource {
    /// The donor's `/Encrypt` dictionary, copied verbatim.  The writer emits
    /// it as a new indirect object in the output, referencing it from the
    /// trailer's `/Encrypt` entry.
    pub encrypt_dict: Dictionary,
    /// The donor's recovered file encryption key (from
    /// [`crate::Pdf::encryption_file_key`]).  The writer uses it directly
    /// instead of re-deriving a key from a password, so that encrypted strings
    /// and streams are consistent with the copied `/O` / `/U` / `/P` entries.
    pub file_key: Vec<u8>,
    /// The donor's `/ID[0]` bytes.  Copied into the output trailer's `/ID[0]`
    /// position; Algorithm 2 key derivation is pinned to this value.
    pub id0: Vec<u8>,
    /// Per-object key derivation algorithm implied by the donor's crypt filter.
    /// Always [`ObjectKeyAlg::Aes`] for the V=4 AES-128 scope.
    pub object_key_alg: ObjectKeyAlg,
}

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

    #[test]
    fn is_deprecated_r5_only_true_for_v5_r5() {
        assert!(EncryptParams::v5_r5(b"u".to_vec(), b"o".to_vec()).is_deprecated_r5());
        assert!(!EncryptParams::v5_r6(b"u".to_vec(), b"o".to_vec()).is_deprecated_r5());
        assert!(!EncryptParams::v4_aes128(b"u".to_vec(), b"o".to_vec()).is_deprecated_r5());
        assert!(
            !EncryptParams::rc4(EncryptMethod::V1Rc440, b"u".to_vec(), b"o".to_vec())
                .is_deprecated_r5()
        );
    }

    #[test]
    fn weak_rc4_and_deprecated_r5_classify_disjoint_methods() {
        // R=5 is deprecated but AES-256, not RC4: the two weak-write
        // classifiers must never both fire for one method.
        let r5 = EncryptParams::v5_r5(b"u".to_vec(), b"o".to_vec());
        assert!(r5.is_deprecated_r5() && !r5.is_weak_rc4());
        let rc4 = EncryptParams::rc4(EncryptMethod::V2Rc4128, b"u".to_vec(), b"o".to_vec());
        assert!(rc4.is_weak_rc4() && !rc4.is_deprecated_r5());
        // The default 256-bit method (R=6) is neither.
        let r6 = EncryptParams::v5_r6(b"u".to_vec(), b"o".to_vec());
        assert!(!r6.is_deprecated_r5() && !r6.is_weak_rc4());
    }
}