Flujo de trabajo para acuerdos firmados

Spec Spec: ETSI EN 319 142-2, §5.1 ETSI EN 319 142-2 §5.1 Spec Spec: ISO 32000-2:2020, §12.8 ISO 32000-2:2020 §12.8 Evidence ⊕ Mixed evidence Evidence: Mixed evidence

De un vistazo

Un acuerdo firmado no es «un PDF con una firma encima». Es un documento preparado para que la firma proteja los bytes correctos. Está firmado en un nivel que corresponde a la obligación. Está empaquetado para que siga siendo verificable después de que caduque el certificado de firma. Esta página recorre ese escenario desde el documento en blanco hasta el contrato de larga duración. También indica con claridad qué pasos cablea hoy el motor y cuáles expone como una superficie congelada.

Por qué importa

Un contrato que se verifica el día en que se firma y falla tres años después en una disputa es peor que no tener firma alguna, porque alguien confió en él. El fallo rara vez está en la criptografía. Suele faltar una marca de tiempo o evidencia de revocación, algo que se descubre mucho después de que el firmante haya seguido adelante.

Elegir de antemano la obligación de firma y producir, en el momento de la firma, la evidencia que esa obligación necesita marca la diferencia entre un acuerdo que se sostiene y uno que se deteriora en silencio. Es una decisión que se toma una vez, dentro del flujo de trabajo, en lugar de redescubrirla con cada disputa.

La versión breve

• Preparar y luego firmar. Una firma cubre exactamente el rango de bytes sobre el que se calculó. El documento debe estar definido como final —incluidas las revisiones añadidas más adelante— antes de firmar, no después.
• Elegir el nivel para la obligación, no al revés. PAdES define una progresión: una firma básica, una con marca de tiempo, una con material de validación incrustado y otra que puede volver a sellarse para una validez de archivo indefinida (ETSI EN 319 142-2 §5.1).
• La validez a largo plazo es una estructura, no una propiedad. Es un Document Security Store más una marca de tiempo de documento, ambos escritos en el archivo (ISO 32000-2:2020 §12.8).
• Ser preciso sobre la junta. El Document::setSignature() de alto nivel de NextPDF congela la API pública, pero falla rápido en lugar de emitir un archivo sin firmar. La ruta cableada es el orquestador de nivel inferior. Esta página no finge lo contrario.

Cómo lo aborda NextPDF

NextPDF separa la decisión del mecanismo. La decisión es qué nivel PAdES necesita la obligación. El mecanismo es cómo se firman los bytes y cómo se transporta el material de validación. Tratarlo como una sola cosa es la forma en que los equipos acaban con una firma válida, pero no duradera.

El escenario tiene cuatro etapas.

1. Prepare the document Compose the agreement and treat it as final. The signature will protect this exact byte range and nothing added outside it without a new revision.
2. Choose the obligation B-B proves who. B-T adds trusted time. B-LT embeds the material to validate later. B-LTA re-stamps for indefinite validity.
3. Sign A CMS signature is embedded in the signature dictionary over the byte range; a timestamp is requested from a TSA if the level needs one.
4. Preserve For long-term levels, the Document Security Store and a document timestamp are written so the signature outlives its certificate.

El escenario de acuerdo firmado de principio a fin: cada etapa añade una garantía, y el nivel que elija en la segunda etapa determina cuánta evidencia deben producir las etapas tres y cuatro.

La enumeración de niveles existe de verdad y codifica la obligación con precisión. B-B prueba la identidad del firmante. B-T añade una marca de tiempo de confianza. Permite responder al «cuándo» con la misma solidez que al «quién». B-LT incrusta los certificados y las respuestas de revocación necesarios para validar la firma después de que caduque el certificado de firma. B-LTA añade marcas de tiempo de documento para que la cadena de confianza pueda extenderse indefinidamente volviendo a sellar antes de que caduque cada certificado de marca de tiempo. La enumeración sabe qué niveles requieren una marca de tiempo y cuáles requieren material de validación incrustado, de modo que el motor puede rechazar una combinación imposible en lugar de producir un archivo «firmado» de forma engañosa.

Human-factors note: Human-factors note

La parte honesta: Document::setSignature() existe para que la superficie de la API pública quede congelada para los consumidores posteriores, pero la junta del escritor que la convierte en una revisión realmente firmada aún no está cableada. Llamarlo y luego save() no emite un PDF sin firmar ni da el trabajo por terminado. Falla rápido con un diagnóstico bloqueante que nombra la ruta admitida. Fallar rápido frente a un artefacto silenciosamente incorrecto es la decisión de diseño. Un contrato con aspecto de firmado pero sin firmar es el fallo exacto que esto evita. La ruta cableada hoy es el orquestador de dos fases de nivel inferior, y las capacidades de archivo a largo plazo son de nivel Premium.

Lo que dice la evidencia

La progresión está respaldada por estándares. Evidence § Standard-backed Evidence: Standard-backed Spec Spec: ETSI EN 319 142-2, §5.1 ETSI EN 319 142-2 §5.1 describe los niveles PAdES superpuestos sobre los bloques de construcción de EN 319 142-1, desde una firma incrustada básica en adelante. La estructura a largo plazo la fija Spec Spec: ISO 32000-2:2020, §12.8 ISO 32000-2:2020 §12.8 : la validación a largo plazo se apoya en un Document Security Store y en un diccionario de marca de tiempo de documento escritos en el archivo.

El modelo de niveles está respaldado por código. Evidence { } Code-backed Evidence: Code-backed La enumeración SignatureLevel tiene los cuatro casos PAdES (B-B, B-T, B-LT, B-LTA) con métodos predicado para «requiere marca de tiempo», «requiere material de validación incrustado» y «requiere marcas de tiempo de documento». El Document::setSignature() de alto nivel está cableado a una protección de fallo rápido que lanza un diagnóstico bloqueante y accionable en vez de emitir un documento sin firmar: un comportamiento verificable, no una afirmación.

El mantenimiento a largo plazo está documentado a nivel de capacidad para el nivel Premium: la superficie de archivo escribe el DSS y la VRI por firma, inspecciona la integridad del archivo con una comprobación de estado y vuelve a sellar con una marca de tiempo de documento antes de que caduque el certificado de marca de tiempo. La documentación indica con claridad que el verificador sigue decidiendo.

Ejemplo práctico

Este ejemplo muestra la decisión —seleccionar la obligación— usando la enumeración real. La ruta de firma cableada es el orquestador de nivel inferior. La llamada de alto nivel se muestra solo para hacer explícito el comportamiento de fallo rápido.

<?php

declare(strict_types=1);

use NextPDF\Security\Signature\SignatureLevel;

/**
 * Map a business obligation to a PAdES level.
 *
 * The obligation drives the level, not the reverse — choosing B-B for a
 * 10-year contract is a decision you do not want to make implicitly.
 */
function levelForObligation(string $obligation): SignatureLevel
{
    return match ($obligation) {
        // Internal sign-off, short retention, signer identity is enough.
        'internal_approval' => SignatureLevel::PAdES_B_B,

        // Counterparty agreement: prove the moment of signing.
        'counterparty_agreement' => SignatureLevel::PAdES_B_T,

        // Regulated contract that must verify after cert expiry.
        'regulated_contract' => SignatureLevel::PAdES_B_LT,

        // Long-lived legal record: indefinite, re-stampable validity.
        'long_term_legal_record' => SignatureLevel::PAdES_B_LTA,

        default => throw new \InvalidArgumentException(
            "Unknown obligation: {$obligation}",
        ),
    };
}

$level = levelForObligation('regulated_contract');

// The enum carries the obligation's implications with it.
$needsTsa     = $level->requiresTimestamp();         // true for B-T+
$needsDss     = $level->requiresDss();               // true for B-LT+
$needsArchive = $level->requiresDocumentTimestamp(); // true only for B-LTA

El objeto de nivel no es una etiqueta. Responde a lo que implica la obligación, de modo que el cableado posterior no tenga que derivarlo de nuevo.

Concepto erróneo común

El concepto erróneo recurrente es «la firma es válida, así que ya hemos terminado». La validez de hoy es necesaria, pero no suficiente. Una firma se calcula sobre un rango de bytes. Cualquier cosa añadida fuera de ese rango en una revisión posterior no queda cubierta por ella; por eso la preparación precede a la firma. Y una firma que se verifica ahora puede fallar más tarde, cuando caduque su certificado, salvo que el material de validación se haya incrustado en el momento de la firma. «Válida» y «duradera» son garantías distintas, y solo la obligación indica cuál se necesita realmente.

Una trampa relacionada y específica de este motor: suponer que el setSignature() de alto nivel produce un archivo firmado hoy. No lo hace. Falla rápido a propósito. Hay que tratar el diagnóstico como el contrato.

Límites y fronteras

• Document::setSignature() es una superficie pública congelada, no un firmante cableado. Falla rápido con un diagnóstico bloqueante. Nunca emite un PDF sin firmar en lugar de uno firmado. La ruta cableada es el orquestador de dos fases de nivel inferior.
• El mantenimiento de la validación a largo plazo (DSS/VRI, comprobación de estado y bucle de marca de tiempo de archivo) es una capacidad de nivel Premium. Core no proporciona el bucle de archivo. Ver el límite a continuación.
• Una firma protege exactamente su rango de bytes. Las revisiones añadidas más adelante son independientes. El motor no extiende retroactivamente la cobertura.
• NextPDF produce y mantiene las estructuras; no dictamina. Que una firma sea de confianza depende de los anclajes de confianza y la política del verificador, que están fuera del motor.
• B-LTA no hace eterna una firma por sí mismo. Solo habilita una validez indefinida si el bucle de resellado se ejecuta a tiempo antes de que caduque cada certificado de marca de tiempo.
• Esta página describe el comportamiento de la superficie de archivo Premium. No afirma aceptación alguna por parte de ningún tribunal o autoridad concretos.

PAdES signing and long-term validity — edition availability

Edition	Availability
Core	○ Core expone la enumeración SignatureLevel y la superficie congelada Document::setSignature() (fallo rápido). El orquestador de nivel inferior cableado cubre la firma de línea base. El mantenimiento de archivo a largo plazo no está en Core.
Pro	○ La firma de línea base PAdES (B-B / B-T) mediante el orquestador está disponible.
Enterprise	○ Añade B-LT / B-LTA, el Document Security Store y el mantenimiento de la VRI por firma, la comprobación de estado LTV y el bucle de archivo de marca de tiempo de documento para una validez indefinida.

Documentos relacionados

• Perfiles de línea base PAdES — B-B, B-T, B-LT, B-LTA explicados como una progresión y cómo elegir.
• Validación a largo plazo — por qué una firma que se verifica hoy puede fallar dentro de diez años y cómo la LTV incrusta la evidencia.
• La guía de decisión de integración — qué paquete del ecosistema encaja con un flujo de trabajo de firma, incluida la junta de aprobación humana en NextPDF Connect.

Glosario

• PAdES — PDF Advanced Electronic Signatures: la familia de perfiles de ETSI que define cómo se transporta una firma electrónica avanzada en un PDF.
• Rango de bytes — el tramo contiguo de bytes del archivo sobre el que se calcula una firma; el contenido fuera de él no queda protegido por esa firma.
• Nivel de firma (B-B / B-T / B-LT / B-LTA) — la progresión PAdES: quién firmó, cuándo, con material de validación incrustado y resellable para una validez de archivo indefinida.
• TSA — Time-Stamping Authority (autoridad de marca de tiempo): un servicio RFC 3161 que afirma que un estado del documento existió en un instante UTC determinado.
• DSS (Document Security Store) — el almacén en el archivo de certificados, respuestas OCSP y CRL necesarios para validar una firma después de que caduque su certificado.
• LTV (Long-Term Validation) — mantener una firma verificable a lo largo del tiempo incrustando la evidencia de validación y volviéndola a sellar.
• Fail-fast — negarse a producir un artefacto engañoso y lanzar en su lugar un error accionable en vez de emitir un archivo silenciosamente incorrecto.