README

PDF encryption primitives for password protection and permission control.

💖 Part of the tc-lib-pdf / TCPDF ecosystem (100M+ installs). Sponsor its maintenance →

Overview

tc-lib-pdf-encrypt implements core encryption routines used by PDF generation and processing stacks, including password handling and permission flags.

The package encapsulates PDF security mechanics behind a focused API so consuming libraries can apply encryption policies without reimplementing cryptographic details. It is built for interoperability with standard PDF readers and for clear separation between document logic and security concerns.

Security Notice

RC4 modes (0 and 1) are cryptographically broken and deprecated. RC4-40 (mode 0) and RC4-128 (mode 1) are no longer considered secure. Both modes emit an E_USER_DEPRECATED notice at runtime. Use AES-128 (mode 2), AES-256 R5 (mode 3), or AES-256 R6 / PDF 2.0 (mode 4) for all new documents.

Features

Encryption

• RC4 and AES variants for PDF object/string encryption (modes 0–4; see Security Notice above)
• AES-256 R6 (PDF 2.0 / ISO 32000-2, mode 4) support with Algorithm 2.B (ISO 32000-2 §7.6.4.3.4) key derivation
• User and owner password workflows
• Permission flag handling for document operations
• Optional metadata encryption control ($encryptMetadata)
• Optional embedded-file stream encryption ($encryptEmbeddedFiles, /EFF dictionary entry)
• Public-key (certificate) encryption for multiple recipients

Decryption

• Password authentication for all encryption modes (RC4-40, RC4-128, AES-128, AES-256 R5/R6)
• Public-key (PKCS#7 / S/MIME) decryption for recipient private keys
• Per-object key derivation for AES-128 streams
• Round-trip decryptString() companion to encryptString()

Integration

• Designed for direct use by PDF writer and reader components
• Helpers for PDF date formatting and hex/string transforms
• Exception-driven error handling

Requirements

• PHP 8.2 or later
• Extensions: hash, openssl
• Composer

Installation

composer require tecnickcom/tc-lib-pdf-encrypt

Quick Start

Encrypting a string

<?php

require_once __DIR__ . '/vendor/autoload.php';

// AES-256 R6 (mode 4 — recommended)
$encrypt = new \Com\Tecnick\Pdf\Encrypt\Encrypt(
    enabled: true,
    file_id: md5('unique-file-id'),
    mode: 4,
    permissions: ['print', 'copy'],
    user_pass: 'userpassword',
    owner_pass: 'ownerpassword',
);

$cipher = $encrypt->encryptString('secret payload', $objectNumber = 1);
echo bin2hex($cipher);

Decrypting a string

<?php

require_once __DIR__ . '/vendor/autoload.php';

// Pass the encryption dictionary produced by the Encrypt instance.
$decrypt = new \Com\Tecnick\Pdf\Encrypt\Decrypt($encrypt->getEncryptionData());

if ($decrypt->authenticate('userpassword')) {
    // For AES modes the PKCS#7 padding is stripped automatically, so the
    // exact original plaintext is returned. RC4 modes are symmetric.
    $plain = $decrypt->decryptString($cipher, $objectNumber = 1);
    echo $plain;
}

OpenSSL 3 Note

On OpenSSL 3 systems, legacy providers may be disabled by default. Enable legacy support when required by your runtime policy.

Development

make deps
make help
make qa

Packaging

make rpm
make deb

For system packages, bootstrap with:

require_once '/usr/share/php/Com/Tecnick/Pdf/Encrypt/autoload.php';

Contributing

Contributions are welcome. Please review CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md.