Seguridad — Referencia detallada

De un vistazo

Esta es la referencia detallada de la superficie de seguridad de NextPDF Pro: enmascaramiento en tiempo de generación, detección de PII en la capa de texto, la sesión de firma remota y con KMS en la nube, la firma secuencial multifirmante, la vía de incorporación de CAdES y XAdES, el nivel de línea base PAdES B-B y el soporte de firma PAdES B-T (una firma B-B más un signature-time-stamp de RFC 3161 sobre el valor de la firma). Indica el contrato de la API pública, el comportamiento observable externamente y el límite Enterprise B-LT/B-LTA. Se mantiene a nivel de comportamiento; no cita ninguna ruta de implementación interna.

Disponibilidad y licencias

Esta capacidad se distribuye en NextPDF Pro (nextpdf/pro) y se activa con un envoltorio de licencia de nivel Pro. Una implementación sin ese derecho de uso no carga las clases de la capacidad. Compare ediciones y obtenga una licencia.

Core incluye el firmante CMS por software, el cliente de marca de tiempo RFC 3161, la validación de ruta RFC 5280 y la comprobación de revocación por OCSP y CRL. Pro añade el enmascaramiento, la detección de PII, la superficie de firma remota y con KMS en la nube, y el soporte de firma PAdES B-T (compone la pila RFC 3161 de Core para añadir un signature-time-stamp) que se describe aquí. El indicador de capacidad de esta superficie es pro: una implementación sin un derecho de uso de Pro activo no carga estas clases, el contrato de firma de Core sigue funcionando sin cambios, y el código que depende del contrato de Core no se rompe cuando el derecho de uso está ausente.

Instalación

composer require nextpdf/pro:^3

Contrato de comportamiento

El motor de enmascaramiento aplica una lista ordenada de reglas al texto antes de escribir la página. Una regla coincide con un patrón PCRE y reemplaza una coincidencia en uno de tres modos:

• BlackBox — elimina el texto coincidente del flujo de contenido y reserva una región de relleno. Este modo elimina los objetos de texto subyacentes según lo probado.
• Asterisks — reemplaza cada carácter coincidente por un asterisco, conservando el número de caracteres.
• FixedLabel — reemplaza toda la coincidencia por una etiqueta configurable, [REDACTED] de forma predeterminada.

Una regla se construye a partir de un literal exacto mediante MaskingRule::exactMatch (el literal se escapa como regex) o a partir de un patrón PCRE personalizado mediante MaskingRule::regex. MaskingConfig contiene la lista ordenada de reglas, un modo predeterminado y el color de relleno. MaskingConfig::fromArray analiza un mapa de configuración y descarta silenciosamente una entrada de regla que no tiene un patrón de cadena utilizable, en lugar de hacer fallar toda la importación.

La superficie de PII extrae la capa de texto del PDF y luego aplica patrones integrados para direcciones de correo electrónico, números de teléfono, números de la Seguridad Social de Estados Unidos y números de tarjeta de crédito. Devuelve un resultado estructurado: un booleano que indica si se encontró alguna coincidencia, un recuento de coincidencias, la vista enmascarada del texto y la lista de tipos escaneados. El llamante puede restringir el escaneo a un subconjunto de los cuatro tipos. La superficie no sobrescribe los glifos renderizados de la página; una página escaneada sin capa de texto no produce coincidencias. Trate el resultado como detección por patrones en la capa de texto de los tipos configurados, no como una eliminación completa de datos personales ni como una declaración de cumplimiento normativo.

La sesión de firma es en dos fases. RemoteSigningSession::create abre una sesión. prepare calcula el resumen del documento sobre las dos regiones ByteRange y luego construye los atributos firmados CMS. complete invoca la estrategia e incrusta el resultado; suspend serializa la sesión para que un worker pueda reanudarla más tarde con resume y completeWithRawSignature. La sesión ensambla un CMS SignedData y lo almacena codificado en DER en la entrada Contents del diccionario de firma — ISO 32000-2 §12.8.1. Cuando se suministra un certificado X.509 analizable, la sesión emite el conjunto completo de atributos firmados obligatorios de PAdES B-B: content-type, message-digest, signing-time, signing-certificate-v2 y un atributo de protección de algoritmo — RFC 5652 §5.3 y RFC 5652 §5. El verificador vuelve a calcular el resumen del contenido y lo compara con el atributo message-digest; la comparación debe coincidir para que la firma sea válida — RFC 5652 §5.4.

Cuando el nivel PAdES configurado es B-T (RemoteSigningConfig::default->withLevel(SignatureLevel::PAdES_B_T), o mediante SequentialSigner::withTimestamping) y hay un proveedor de marca de tiempo conectado, la sesión incrusta además exactamente un signature-time-stamp de RFC 3161 como atributo no firmado CMS sobre el primer SignerInfo. Un signature-time-stamp es un atributo no firmado que transporta un token de marca de tiempo calculado sobre el valor de la firma digital de un firmante — ETSI EN 319 122-1 §5.3; su MessageImprint es el hash del valor del campo de firma del SignerInfo, con la etiqueta y la longitud ASN.1 excluidas — ETSI EN 319 122-1 §5.3 y RFC 3161 Appendix A (OID id-aa-timeStampToken = 1.2.840.113549.1.9.16.2.14). Como la marca de tiempo es un atributo no firmado, los atributos firmados B-B, el message-digest, el valor de la firma del SignerInfo y el /ByteRange del PDF son idénticos byte a byte a la salida B-B; solo el CMS crece por el atributo no firmado, y el espacio reservado /Contents de B-T se amplía para que quepa. El token se solicita al proveedor de marca de tiempo configurado (el cliente RFC 3161 de Core predeterminado, o un proveedor suministrado por el llamante). En la vía del proveedor predeterminado, el resumen de la huella es SHA-256; la forma heredada ESSCertID v1 ligada a SHA-1 se rechaza y se requiere ESSCertIDv2 — RFC 5816 §1. Un fallo de la TSA, una solicitud rechazada, un eco incorrecto del nonce o de la huella de mensaje, un token mal formado o de algoritmo no admitido, o un token que falla la verificación criptográfica se manifiestan como una excepción tipada PadesBt con la excepción de Core originaria conservada como el throwable previo. NextPDF Pro implementa el soporte de firma PAdES B-T según ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652 y RFC 5816, y está verificado con fixtures; no afirma una certificación independiente ETSI EN 319 142-1 ni afirma la validez legal del documento.

SequentialSigner coordina la firma multifirmante. Cada firmante es una revisión de actualización incremental separada. El primer firmante puede ser una firma de certificación con una restricción DocMDP establecida mediante certifyFirst. PadesWrapper incorpora una firma existente: fromCades incrusta una estructura CMS directamente, fromXades analiza un documento XAdES y reutiliza su material de firma principal, y detect selecciona automáticamente según el formato. La vía XAdES reutiliza el certificado, la cadena, el valor de la firma y el algoritmo; no transfiere las propiedades cualificadoras de XAdES.

Superficie de la API pública

composer require nextpdf/pro:^3

Tipo	Clase	Función	Estabilidad	Desde
RemoteSigningSession	clase	Sesión de firma remota o asíncrona en dos fases	estable	1.9.0
RemoteSigningConfig	clase	Configuración de sesión inmutable, incluido el nivel PAdES y el algoritmo	estable	1.9.0
SequentialSigner	clase	Firma secuencial multifirmante con soporte DocMDP	estable	1.9.0
SequentialSigningResult	clase	Resultado de una ejecución secuencial: bytes del PDF, cadena, recuento, completitud	estable	1.9.0
SigningStrategy	interfaz	El contrato del mecanismo de firma que invoca una sesión	estable	1.9.0
PadesWrapper	clase	Envuelve una firma CAdES o XAdES existente para incrustación PAdES	estable	1.9.0
KmsSignerInterface	interfaz (SPI)	Contrato de controlador HSM y KMS de terceros; extiende el contrato del firmante HSM de Core	estable	2.1.0
SignatureAlgorithm	enum	OID de algoritmo de firma y nombres de resumen de Pro	estable	2.1.0
GenerationTimeMasker	clase	Enmascaramiento dirigido por reglas aplicado antes de escribir la página	estable	1.9.0
MaskingConfig	clase	Configuración de enmascaramiento inmutable	estable	1.9.0
MaskingRule	clase	Una única regla de enmascaramiento (literal o PCRE)	estable	1.9.0
MaskingMode	enum	BlackBox, Asterisks, FixedLabel	estable	1.9.0

Contrato SigningStrategy

Una estrategia opera sobre los atributos firmados codificados en DER y devuelve los bytes de la firma en bruto. La sesión, no la estrategia, ensambla el CMS SignedData. Una estrategia expone el DER del certificado del firmante, el DER de la cadena ordenada de hoja a raíz, el OID del algoritmo de firma, el nombre del algoritmo de resumen y un indicador isAsync que marca una estrategia cuya sesión puede serializarse y reanudarse.

SPI KmsSignerInterface

KmsSignerInterface extiende el contrato del firmante HSM de Core. Añade un providerId estable para la búsqueda en el registro, un método signWithVersion con un parámetro explícito de versión de clave por llamada, y supportsAlgorithm y supportedAlgorithms para que el llamante descubra la compatibilidad de algoritmos antes de la llamada de firma. Los identificadores de proveedor integrados reservados son aws-kms, azure-keyvault, gcp-kms, pkcs11, openssl-cli y openssl-engine. Un controlador de terceros debe asignar un espacio de nombres a su identificador para evitar una colisión. La semántica predeterminada de versión de clave varía según el proveedor: un proveedor que resuelve alias resuelve la clave activa a partir del alias cuando la versión es null; un proveedor que selecciona la última versión habilitada lo hace a través de su transporte; un proveedor que no tiene un concepto de versión activa del lado del servidor debe usar una versión fijada en su configuración, y debe lanzar un error de gestión de claves cuando ni la llamada ni la configuración fijan una versión. Una versión no vacía fija esa versión, y el proveedor debe lanzar un error de gestión de claves cuando la versión es desconocida, está deshabilitada o ha sido revocada.

Casos límite y trampas

• Una firma producida no es una firma verificada. La validación de ruta se ejecuta en el verificador con los anclajes de confianza y las comprobaciones de restricciones básicas de ese verificador — RFC 5280 §6.1. El productor no puede afirmar el resultado.
• La sesión tiene un mecanismo de reserva heredado de tres atributos para bytes de certificado sintético que no son X.509. Las estrategias de producción siempre suministran DER X.509 real, por lo que el conjunto completo de atributos B-B es la vía de producción. El mecanismo de reserva existe únicamente para la superficie de prueba histórica de mecánica DER.
• La estructura CMS debe caber en el espacio Contents reservado. El SignedData B-B con una cadena de certificados completa tiene un tamaño; la sesión lanza un error de desbordamiento cuando el CMS ensamblado supera el espacio hexadecimal reservado. Dimensione el espacio reservado en consecuencia. Para B-T, el token RFC 3161 incrustado (dominado por la cadena de certificados de la TSA) agranda el CMS; el espacio reservado de B-T se amplía automáticamente, y un espacio configurado insuficiente falla de forma cerrada con un error de configuración tipado en lugar de truncar.
• MaskingConfig::fromArray descarta una entrada que no tiene un patrón de cadena utilizable en lugar de hacer fallar la importación. Valide la fuente de configuración si un descarte silencioso es inaceptable.
• El modo de caja negra del enmascaramiento emite un reemplazo vacío para la secuencia coincidente y elimina el texto subyacente. Una regla que no coincide con un valor no lo enmascara; el motor no afirma que se encuentre todo el contenido sensible.
• B-T requiere un proveedor de marca de tiempo conectado. En la vía del proveedor RFC 3161 de Core predeterminado, el resumen de la huella es SHA-256; un resumen de huella distinto de SHA-256 en esa vía se rechaza con un error de configuración tipado en lugar de degradarse silenciosamente, y un proveedor personalizado suministrado por el llamante puede usar legítimamente otro resumen aprobado. Un serialNumber de marca de tiempo es único por token de una autoridad de marcado de tiempo dada, y genTime es el instante UTC en que se creó el token — RFC 3161 §2.4.1, §2.4.2. El material de validación a largo plazo B-LT/B-LTA sigue siendo una cuestión del límite de Enterprise; Pro no produce ningún DSS, ninguna VRI ni ninguna marca de tiempo de documento.
• OCSP unknown no es good, y la frescura del estado está acotada por thisUpdate y nextUpdate — RFC 6960 §2.2, §4.2.

Comportamiento en modo FIPS

Pro selecciona el algoritmo a partir del algoritmo de firma configurado y de la estrategia. Cuando se configura contra un KMS o HSM validado con FIPS, la operación criptográfica se ejecuta en ese límite validado, y el conjunto de algoritmos es el que permita ese límite. NextPDF Pro realiza el ensamblaje estructural del CMS y el cálculo del resumen; no es un módulo criptográfico validado con FIPS y no hace ninguna declaración de certificación FIPS. Una implementación que requiere una postura FIPS debe configurar un KMS o HSM validado con FIPS, y el perfil de política criptográfica FIPS 140-3 es una capacidad de Enterprise.

Postura de control de exportaciones

Este módulo concierne a funcionalidad criptográfica; trátelo como sensible desde el punto de vista de la seguridad en su propia revisión.

Límite de Enterprise

NextPDF Pro produce la línea base B-B y el nivel B-T. Para B-B la sesión ensambla un CMS SignedData con el conjunto de atributos firmados B-B y no aplica ninguna marca de tiempo. Para B-T añade exactamente un signature-time-stamp de RFC 3161 como atributo no firmado CMS calculado sobre el valor de la firma digital de un firmante — ETSI EN 319 122-1 §5.3. NextPDF Pro implementa esto según ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652 y RFC 5816, y está verificado con fixtures; no afirma una certificación, conformidad o cumplimiento independientes de ETSI EN 319 142-1, ni afirma la validez legal del documento.

Los niveles B-LT y B-LTA son capacidades de Enterprise y no los produce Pro. B-LT y B-LTA añaden un almacén de seguridad de documento y marcas de tiempo de documento para la validación de archivado a largo plazo — ETSI EN 319 142-2 §5.5. Un controlador de firma que produce esos niveles da soporte a entradas DSS y marcas de tiempo de documento — ETSI EN 319 142-2 §6.3.3.3. El RemoteSigningConfig de Pro puede transportar un nivel superior a B-T (B-LT o B-LTA) que solicita un almacén de seguridad de documento, pero Pro no incluye ese productor y no actúa sobre él; tal nivel es un valor declarado por adelantado. El flujo de firma de Core resuelve el productor de largo plazo en tiempo de ejecución a través del contrato de Core, y ese productor se distribuye en el paquete nextpdf/enterprise. En una implementación solo con Pro, una solicitud de B-LT o B-LTA falla de forma cerrada con un mensaje que nombra el componente de Enterprise ausente. Pro no produce ningún DSS, ningún diccionario VRI, ninguna marca de tiempo de documento ni ningún bucle de archivado, y no hace ninguna declaración de validación a largo plazo (LTV). La custodia de claves en hardware mediante PKCS#11, y el perfil de política criptográfica FIPS 140-3, también son capacidades de Enterprise. Esta página no documenta la implementación de validación a largo plazo de Enterprise; indica únicamente el límite y el nombre del paquete público.

Nivel PAdES	Añade	Edición del productor
B-B	Firma CMS con atributos firmados	Core, Pro
B-T	Un atributo no firmado signature-time-stamp de RFC 3161 sobre el valor de la firma	Core, Pro
B-LT	Almacén de seguridad de documento con material de validación	Enterprise (nextpdf/enterprise)
B-LTA	Marcas de tiempo de documento para la validez de archivado	Enterprise (nextpdf/enterprise)

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie de la API pública admitida. Las rutas de espacio de nombres internas, las clases de ayuda, las tablas de mecanismos, los nombres de archivo de runbook y los prefijos de ticket quedan fuera del alcance.

Alternativa de Core

Una implementación sin el derecho de uso de Pro conserva el contrato de firma de Core. El código que depende del contrato SignerInterface de Core sigue firmando con el firmante CMS por software en la línea base B-B. El enmascaramiento, la detección de PII y las estrategias de firma remota y con KMS en la nube no están presentes sin el paquete de Pro, y una llamada a esos tipos es un error de dependencia duro, no una operación silenciosa sin efecto.

Residencia de datos y mitigaciones de PII

Las superficies de enmascaramiento y de PII se ejecutan en el proceso. Ningún contenido del documento sale del host para el enmascaramiento ni la detección de PII. Una estrategia de KMS en la nube envía el resumen de los atributos firmados, no el documento, al proveedor para la operación de firma. La detección de PII coincide por patrones sobre los tipos configurados y elimina los objetos de texto subyacentes en el modo de caja negra según lo probado. No es una garantía de eliminación completa de datos personales y no es una declaración de cumplimiento normativo.

Telemetría segura y depuración de registros

La biblioteca lanza excepciones tipadas con mensajes estructurales. No escribe contenido del documento ni valores de PII detectados en los mensajes de excepción ni en los registros. Una implementación que registra en torno a la vía de firma debe registrar campos estructurales, no bytes del documento.

Conformidad

Declaración	Estándar	Cláusula
La firma CMS se almacena codificada en DER en la entrada Contents del diccionario de firma.	ISO 32000-2	§12.8.1
El proceso de cálculo del resumen del mensaje; los atributos firmados transportan content-type y message-digest.	RFC 5652	§5.4
El verificador no debe confiar en los resúmenes calculados por el originador; los vuelve a calcular de forma independiente y los compara (proceso de verificación de firma).	RFC 5652	§5.6
El SignerInfo transporta el identificador del algoritmo de resumen y el bloque de atributos firmados.	RFC 5652	§5
Una solicitud de marca de tiempo devuelve una estructura TSTInfo.	RFC 3161	§2.4.1
Un serialNumber de marca de tiempo es único por token de una TSA dada.	RFC 3161	§2.4.2
El genTime de la marca de tiempo es el instante UTC en que se creó el token.	RFC 3161	§2.4.2
Un signature-time-stamp PAdES B-T es un atributo no firmado que transporta un token de marca de tiempo calculado sobre el valor de la firma digital de un firmante (Pro produce B-T).	ETSI EN 319 122-1	§5.3
La huella del signature-time-stamp es el hash del valor del campo de firma del SignerInfo, con la etiqueta y la longitud ASN.1 excluidas.	ETSI EN 319 122-1	§5.3
El token signature-time-stamp usa el OID id-aa-timeStampToken; su MessageImprint es un hash del valor del campo de firma del SignerInfo.	RFC 3161	Appendix A
En el lado de verificación, NextPDF vincula el MessageImprint de un signature-time-stamp al valor de la firma del SignerInfo y falla de forma cerrada ante una discrepancia, un token ausente/duplicado o una huella SHA-1 (verificación estricta, no una certificación).	RFC 3161	Appendix A
ESSCertIDv2 reemplaza al ESSCertID heredado ligado a SHA-1; la vía estricta de B-T requiere ESSCertIDv2.	RFC 5816	§1
La validación de la ruta de certificación comprueba las restricciones básicas y las entradas de la ruta hasta un anclaje de confianza.	RFC 5280	§6.1
OCSP informa certStatus como good, revoked o unknown.	RFC 6960	§2.2
La frescura del estado OCSP está acotada por thisUpdate y nextUpdate.	RFC 6960	§4.2
B-LT y B-LTA añaden un almacén de seguridad de documento y marcas de tiempo de documento para la validación a largo plazo (límite de Enterprise).	ETSI EN 319 142-2	§5.5
Un controlador de firma que produce niveles a largo plazo da soporte a entradas DSS y marcas de tiempo de documento (límite de Enterprise).	ETSI EN 319 142-2	§6.3.3.3

Todas las cláusulas están parafraseadas. NextPDF no reproduce el texto normativo. Consulte los estándares publicados para conocer la redacción autorizada. NextPDF Pro implementa el soporte de firma PAdES B-T según ETSI EN 319 122-1 §5.3 (signature-time-stamp), RFC 3161, RFC 5652 y RFC 5816, y está verificado con fixtures. ETSI EN 319 142-1 (la parte de niveles de línea base de PAdES) queda fuera del conjunto de evidencia citado; por tanto, NextPDF Pro no afirma una certificación, conformidad o cumplimiento independientes de ETSI EN 319 142-1, ni afirma la validez legal del documento. Esta página indica la estructura producida, los estándares que implementa el soporte de B-T y el límite Enterprise B-LT/B-LTA, no un nivel de conformidad certificado.

Véase también

• Firma de Core — el firmante CMS, la marca de tiempo RFC 3161, la validación de ruta RFC 5280, OCSP y CRL.
• Mapeo de línea base PAdES — B-B, B-T, B-LT, B-LTA entre ediciones.
• Seguridad (presentación de la capacidad) — la página pública de la capacidad de seguridad de Pro.
• CMS · PAdES · Marca de tiempo RFC 3161 · KMS · DSS — términos del glosario.