Cifrar un PDF con AES-256 y establecer permisos

De un vistazo

Esta recipe cifra un documento con AES-256. Define una contraseña de usuario y una contraseña de propietario, y restringe las operaciones mediante una máscara de bits de permisos. La recipe se basa en examples/22-protection.php.

Reproducibilidad: por qué esta recipe es structural, no bitwise. Un PDF cifrado con AES-256 nunca puede ser idéntico byte a byte entre dos ejecuciones, ni siquiera con la misma entrada y las mismas contraseñas. El gestor de seguridad estándar de revisión 6 genera 16 bytes aleatorios nuevos (las sales de validación y de clave de user/owner) en cada cifrado con un generador de números aleatorios robusto antes de derivar la clave de cifrado del archivo (ISO 32000-2 §7.6.4, Algoritmo 2.B). AES-256-CBC usa un vector de inicialización aleatorio por cada objeto. El tráiler /ID también es un arreglo de dos cadenas de bytes cuyo primer elemento es un identificador permanente derivado del archivo en el momento de su creación (ISO 32000-2 §14.4). Por lo tanto, el perfil de reproducibilidad es structural: el arnés de pruebas canonicaliza las sales de cifrado y el IV, el orden de los objetos y el /ID del tráiler antes de comparar dos ejecuciones, en vez de afirmar una coincidencia de bytes imposible.

Requisitos previos

Núcleo instalado: composer require nextpdf/core:^3.
La extensión de PHP openssl, utilizada por el cifrador AES-256.

Recipe

Crear el documento.
Llamar a setEncryption() antes de addPage(). El cifrador debe existir antes de que se escriba cualquier objeto de contenido.
Pasar una contraseña de usuario (necesaria para abrir el documento), una contraseña de propietario (acceso completo) y una máscara de bits de permisos.
Agregar contenido y guardar. El escritor cifra el cuerpo de cada objeto.

Ejemplo completo

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

// Permission bits (ISO 32000-2, encryption dictionary P entry):
//   bit 3  (4)  allow printing
//   bit 4  (8)  allow content modification
//   bit 5  (16) allow text extraction / copying
//   bit 6  (32) allow annotation and form editing
// Grant printing only:
$permissions = 4;

$doc = Document::createStandalone();
$doc->setTitle('Encrypted Document');

// setEncryption() MUST run before addPage(). Order matters.
$doc->setEncryption(
    userPassword: 'open-me',
    ownerPassword: 'owner-secret',
    permissions: $permissions,
);

$doc->addPage();
$doc->setFont('helvetica', '', 12);
$doc->cell(0, 10, 'This document is encrypted with AES-256.', newLine: true);

$doc->save(__DIR__ . '/encrypted.pdf');

echo "Wrote encrypted.pdf (AES-256, printing only)\n";

Salida esperada

Wrote encrypted.pdf (AES-256, printing only)

Al abrir encrypted.pdf se solicita una contraseña. La contraseña de usuario permite abrirlo con el conjunto de permisos restringido. La contraseña de propietario permite abrirlo con acceso completo.

Casos límite

Orden de las llamadas. Llamar a setEncryption() después de addPage() no cifra retroactivamente el contenido anterior. Configurar siempre primero el cifrado.
Valor predeterminado de la contraseña de propietario. Cuando la contraseña de propietario se deja vacía, el motor reutiliza la contraseña de usuario como contraseña de propietario. Establecer contraseñas distintas cuando los dos roles deban diferir.
Semántica de los permisos: límite. Los lectores conformes respetan los bits de permisos. No se hacen cumplir criptográficamente: un lector que ignore los bits, o una herramienta utilizada con la contraseña de propietario, puede realizar operaciones restringidas. Tratar los permisos como una señal de política para el software cooperante, no como un control de acceso capaz de resistir a una parte decidida.
Conflicto con PDF/A. PDF/A prohíbe la clave de tráiler Encrypt. Llamar a setEncryption() en un documento PDF/A, en cualquier orden, lanza una excepción de incompatibilidad. Consultar Compuerta de conformidad PDF/A-4.
AES-256-GCM. useAesGcm() opta por el cifrado masivo GCM de ISO/TS 32003 cuando OpenSSL o libsodium del host ofrecen el cifrador. De lo contrario, lanza InvalidConfigException.

Conformidad

Declaración	Especificación	Cláusula	reference_id
El gestor de seguridad estándar define el algoritmo de cifrado y la longitud de la clave.	ISO 32000-2	§7.6
La entrada `P` del diccionario de cifrado contiene los bits de permisos.	ISO 32000-2	§7.6

El cifrado protege la confidencialidad del contenido frente a las partes que no tienen la contraseña. Los bits de permisos son indicativos para los lectores y, por sí solos, no impiden que actúe una herramienta no conforme.