Enterprise edición

FIPS 140 — Referencia detallada

De un vistazo

Esta página es la referencia detallada del módulo FIPS 140 de NextPDF Enterprise. El módulo es una capacidad de política y de autoprueba. Restringe las elecciones criptográficas a una lista de permitidos alineada con FIPS, ejecuta una batería de pruebas de respuesta conocida (known-answer) en el arranque e inhibe la salida criptográfica cuando la batería falla. NextPDF no es un módulo criptográfico validado por FIPS 140, no posee ninguna certificación y no otorga ninguna. Soporte no equivale a conformidad, y conformidad no equivale a certificación. Un despliegue compatible con FIPS requiere además un proveedor criptográfico validado por FIPS suministrado por el operador.

Disponibilidad y licenciamiento

Esta capacidad se incluye en NextPDF Enterprise (nextpdf/enterprise) y se activa con un sobre de licencia de nivel Enterprise. Un despliegue sin ese derecho no carga las clases de la capacidad. Compara ediciones y obtén una licencia.

Superficie de API pública

Todos los símbolos residen en NextPDF\Enterprise\Security\Fips, excepto FipsBootstrap en NextPDF\Enterprise\Bootstrap.

Símbolo	Parámetros	Comportamiento por defecto	Devuelve	Lanza o falla con	Notas
`FipsBootstrap::boot()`	`?CryptoPolicyInterface $policy`, `?FipsSelfTest $selfTest`, `?LoggerInterface $auditLogger` (todos por defecto `null`)	Ejecuta la batería de arranque una vez al iniciar; usa por defecto la política estricta	`FipsModeGuard`	`FipsModuleErrorStateException` ante cualquier fallo de prueba de arranque	Raíz de composición; traza de auditoría desactivada cuando `$auditLogger` es `null`
`FipsBootstrap::lazy()`	Igual que `boot()`	Difiere la batería hasta la primera aserción de frontera	`FipsModeGuard`	Ninguno en el momento de la llamada; la primera aserción puede lanzar `FipsModuleErrorStateException`	El módulo permanece en `PRE_OPERATIONAL` hasta la primera aserción
`FipsBootstrap::signatureEnforcer()`	`?CryptoPolicyInterface $policy = null`, `?FipsSelfTest $selfTest = null`	Arranca el módulo y luego envuelve el guardián para los puntos de estrangulamiento del firmante	`FipsSignatureEnforcer`	`FipsModuleErrorStateException` ante cualquier fallo de prueba de arranque	Delega en `boot()`
`FipsBootstrap::selfTestReport()`	`?FipsSelfTest $selfTest = null`	Ejecuta la batería bajo demanda y la resume	`array{status: FipsSelfTestStatus, operational: bool, failed: list<string>}`	No lanza; los fallos aparecen en `failed`	Para endpoints de salud de administración y uso por CLI
`FipsCryptoPolicy::strict()`	`?FipsSelfTest $selfTest = null`	Preajuste FIPS 140-3: SHA-256/384/512; OID aprobados de RSA, RSASSA-PSS, ECDSA; `aes-256-cbc`, `aes-256-gcm`; RSA >= 2048, EC >= 256	`self`	Ninguno	El constructor es privado; los preajustes son la única entrada
`FipsCryptoPolicy::standard()`	`?FipsSelfTest $selfTest = null`	Preajuste FIPS 140-2: el conjunto estricto más `aes-128-cbc`	`self`	Ninguno	Solo para interoperabilidad heredada
`FipsCryptoPolicy::assertPreOperational()`	Ninguno	Ejecuta, o reproduce el resultado enclavado de, la batería de arranque	`void`	`FipsModuleErrorStateException` cuando cualquier prueba de arranque falla	Impulsado por la costura de aplicación de Core antes de la primera operación
Superficie de consulta de `FipsCryptoPolicy`	Entradas `string` / `int`	Comprobaciones de pertenencia a la lista de permitidos; un tipo de clave desconocido se deniega	`bool` / `string`	Ninguno	`isHashAlgorithmAllowed`, `isSignatureAlgorithmAllowed`, `isEncryptionAlgorithmAllowed`, `isKeyStrengthAllowed`, `getPreferredHashAlgorithm`, `getName`
`FipsModeGuard::__construct()`	`CryptoPolicyInterface $policy`, `?FipsBootGuard $bootGuard = null`, `?FipsAuditLogger $auditLogger = null`	Envuelve una política con fronteras de estilo assert	—	Ninguno	Sin `$bootGuard` no hay puerta de autoprueba; la composición de producción la proporciona
`FipsModeGuard::assertHashAllowed()`	`string $algorithm`	El catálogo de denegación primero, luego la lista de permitidos	`void`	`FipsViolationException`; `FipsModuleErrorStateException` cuando hay un guardián de arranque conectado	El registro de auditoría precede a cualquier `FipsViolationException`
`FipsModeGuard::assertSignatureAlgorithmAllowed()`	`string $oid`	El catálogo de denegación primero, luego la lista de permitidos	`void`	Igual que arriba	Los OID se comparan de forma exacta
`FipsModeGuard::assertEncryptionAllowed()`	`string $algorithm`	El catálogo de denegación primero, luego la lista de permitidos	`void`	Igual que arriba	Los nombres se comparan en minúsculas
`FipsModeGuard::assertKeyStrengthAllowed()`	`string $keyType`, `int $bitLength`	El catálogo de denegación primero, luego los mínimos de la política	`void`	Igual que arriba	Un tipo de clave desconocido se deniega
`FipsModeGuard::getPolicy()`	Ninguno	Devuelve la política envuelta	`CryptoPolicyInterface`	Ninguno	—
`FipsBootGuard::__construct()`	`FipsSelfTest $selfTest`	Retiene la batería; no la ejecuta	—	Ninguno	Un ciclo de arranque por instancia
`FipsBootGuard::report()`	Ninguno	Ejecuta la batería una vez, cachea el informe, se enclava ante un error	`FipsSelfTestReport`	Ninguno	La primera llamada ejecuta las pruebas
`FipsBootGuard::rerun()`	Ninguno	Fuerza una ejecución nueva; una ejecución con error enclava el proceso	`FipsSelfTestReport`	Ninguno	Autoprueba bajo demanda; no es una vía de recuperación de errores
`FipsBootGuard::assertOperational()`	Ninguno	Afirma que el módulo está operativo; persistente a lo largo del proceso	`void`	`FipsModuleErrorStateException`	Una instancia limpia sigue lanzando cuando el proceso enclavó un error
`FipsBootGuard::status()`	Ninguno	Informa el estado cacheado	`FipsSelfTestStatus`	Ninguno	`ERROR` cuando está enclavado; `PRE_OPERATIONAL` cuando nunca se ejecutó
`FipsSelfTest::__construct()`	`?callable $randomBytesProvider = null`, `?callable $hashProvider = null`	Usa las funciones de plataforma `hash()` y `random_bytes()`	—	Ninguno	Existen sobrescrituras para pruebas de fallo deterministas
`FipsSelfTest::run()`	Ninguno	Ejecuta la batería completa; nunca hace cortocircuito	`FipsSelfTestReport`	Ninguno	Los fallos quedan en el informe, no en excepciones
`FipsSelfTestReport`	`FipsSelfTestStatus $status`, `array $results`, `array $failedResults`	Agregado inmutable de una ejecución	—	`assertOperational()` lanza `FipsModuleErrorStateException` en el estado de error	También `isOperational()`, `isError()`
`FipsSelfTestResult`	`string $algorithm`, `string $kind`, `bool $passed`, `string $message = ''`	Resultado inmutable por prueba	—	Ninguno	`kind` es `KAT`, `PWCT` o `HEALTH`; también `isPassed()`, `isFailed()`
`FipsSelfTestStatus`	—	Enum respaldado por cadena	—	Ninguno	Casos `PRE_OPERATIONAL`, `OPERATIONAL`, `ERROR`
`FipsSignatureEnforcer::__construct()`	`FipsModeGuard $guard`	Envuelve un guardián con puerta de arranque para los puntos de estrangulamiento de firma	—	Ninguno	—
`FipsSignatureEnforcer::assertSignatureGenerationAllowed()`	`string $algorithm`, `string $certificatePem`	Resuelve el OID y la fortaleza de clave, luego delega en el guardián	`void`	`FipsViolationException` (algoritmo desconocido, digest PSS no aprobado, clave no demostrable o denegación de política); `FipsModuleErrorStateException` a través del guardián	Solo la vía de generación; la verificación nunca pasa por aquí
`FipsAuditLogger::__construct()`	`CryptoPolicyInterface $policy`, `LoggerInterface $logger`	Envuelve un logger PSR-3 y la misma política que aplica el guardián	—	Ninguno	Las decisiones registradas no pueden divergir de las aplicadas
`FipsAuditLogger::logHashOperation()` / `logSignatureOperation()` / `logEncryptionOperation()` / `logKeyStrengthCheck()`	Entradas `string` / `int` según la decisión	Registra ALLOW en INFO y DENY en WARNING	`bool` (true cuando se permite)	Ninguno	Contexto estructurado: nombre de política, elemento, decisión
`FipsTransitioningAlgorithms`	Entradas `string` / `int`	Catálogo de denegación estático SP 800-131A Rev.2	`bool` / `list<string>`	Ninguno	`isHashDisallowed`, `isSignatureOidDisallowed`, `isEncryptionDisallowed`, `isKeyStrengthDisallowed`, más `disallowedHashes`, `disallowedSignatureOids`, `disallowedEncryption`
`FipsViolationException`	`string $policyName`, `string $violatingItem`, `string $reason`	Violación de política tipada con campos públicos de solo lectura	—	—	Subtipo de `NextPDF\Exception\NextPdfException`
`FipsModuleErrorStateException`	`array $failedResults`, `?string $message = null`	Rechazo por estado de error que porta los resultados de prueba fallidos	—	—	Subtipo de `NextPDF\Exception\NextPdfException`

public static function boot(?CryptoPolicyInterface $policy = null, ?FipsSelfTest $selfTest = null, ?LoggerInterface $auditLogger = null): FipsModeGuard
public static function lazy(?CryptoPolicyInterface $policy = null, ?FipsSelfTest $selfTest = null, ?LoggerInterface $auditLogger = null): FipsModeGuard
public static function signatureEnforcer(?CryptoPolicyInterface $policy = null, ?FipsSelfTest $selfTest = null): FipsSignatureEnforcer
public static function selfTestReport(?FipsSelfTest $selfTest = null): array

public static function strict(?FipsSelfTest $selfTest = null): self
public static function standard(?FipsSelfTest $selfTest = null): self
public function assertPreOperational(): void
public function isHashAlgorithmAllowed(string $algorithm): bool
public function isSignatureAlgorithmAllowed(string $oid): bool
public function isEncryptionAlgorithmAllowed(string $algorithm): bool
public function isKeyStrengthAllowed(string $keyType, int $bitLength): bool
public function getPreferredHashAlgorithm(): string
public function getName(): string

public function __construct(private CryptoPolicyInterface $policy, private ?FipsBootGuard $bootGuard = null, private ?FipsAuditLogger $auditLogger = null)
public function assertHashAllowed(string $algorithm): void
public function assertSignatureAlgorithmAllowed(string $oid): void
public function assertEncryptionAllowed(string $algorithm): void
public function assertKeyStrengthAllowed(string $keyType, int $bitLength): void
public function getPolicy(): CryptoPolicyInterface

public function __construct(private readonly FipsSelfTest $selfTest)
public function report(): FipsSelfTestReport
public function rerun(): FipsSelfTestReport
public function assertOperational(): void
public function status(): FipsSelfTestStatus

public function __construct(?callable $randomBytesProvider = null, ?callable $hashProvider = null)
public function run(): FipsSelfTestReport

public function __construct(private readonly FipsModeGuard $guard)
public function assertSignatureGenerationAllowed(string $algorithm, string $certificatePem): void

public function __construct(private CryptoPolicyInterface $policy, private LoggerInterface $logger)
public function logHashOperation(string $algorithm): bool
public function logSignatureOperation(string $oid): bool
public function logEncryptionOperation(string $algorithm): bool
public function logKeyStrengthCheck(string $keyType, int $bitLength): bool

public static function isHashDisallowed(string $algorithm): bool
public static function isSignatureOidDisallowed(string $oid): bool
public static function isEncryptionDisallowed(string $algorithm): bool
public static function isKeyStrengthDisallowed(string $keyType, int $bitLength): bool
public static function disallowedHashes(): array
public static function disallowedSignatureOids(): array
public static function disallowedEncryption(): array

public function __construct(public FipsSelfTestStatus $status, public array $results, public array $failedResults)
public function isOperational(): bool
public function isError(): bool
public function assertOperational(): void

// FipsSelfTestResult
public function __construct(public string $algorithm, public string $kind, public bool $passed, public string $message = '')
public function isPassed(): bool
public function isFailed(): bool

// FipsSelfTestStatus
enum FipsSelfTestStatus: string
{
    case PRE_OPERATIONAL = 'pre_operational';
    case OPERATIONAL = 'operational';
    case ERROR = 'error';
}

Contrato de comportamiento

La lista de permitidos de la política es la decisión autoritativa. FipsTransitioningAlgorithms añade por encima una capa de denegación explícita SP 800-131A Rev.2, para mensajes de rechazo claros a efectos de auditoría. La capa de denegación nunca amplía ni anula la lista de permitidos.
FipsCryptoPolicy::strict() permite SHA-256, SHA-384 y SHA-512; RSA PKCS#1 v1.5, RSASSA-PSS y OID de firma ECDSA vinculados a esos hashes; aes-256-cbc y aes-256-gcm; y pisos de clave de RSA 2048, EC 256, Ed25519 256. standard() permite además aes-128-cbc.
La batería de arranque cubre: KAT de digest SHA-256/384/512, un KAT de HMAC-SHA-256, un KAT de cifrado y descifrado AES-256-CBC, un KAT de etiqueta AES-256-GCM, una prueba de consistencia por pares ECDSA P-256 y una comprobación de salud del DRBG. FipsSelfTest::run() siempre ejecuta todas las pruebas y nunca hace cortocircuito, de modo que el informe queda completo como evidencia de auditoría.
La fila del DRBG es una prueba de salud continua (longitud del sorteo más sorteos sucesivos distintos), no una prueba de respuesta conocida. La obligación de respuesta conocida del DRBG se delega en el proveedor validado por FIPS subyacente que suministra el operador.
El estado de error es persistente en el proceso. El primer informe ERROR observado por cualquier FipsBootGuard enclava el proceso entero. Una instancia nueva de guardián o de política no puede lavar el error, y una reejecución posterior que pase no lo despeja. Solo un reinicio del proceso (un verdadero ciclo de apagado y encendido) restablece el estado.
FipsCryptoPolicy implementa NextPDF\Contracts\CryptoPolicyInterface y NextPDF\Contracts\PreOperationalSelfTestInterface. Cuando se configura como la política criptográfica de Core, la costura de aplicación de Core impulsa assertPreOperational() antes de que se produzca la primera firma o texto cifrado.
FipsSignatureEnforcer controla únicamente la vía de generación. La verificación de firmas ya generadas es uso heredado bajo SP 800-131A Rev.2 y nunca pasa por el enforcer.
Cuando hay un registrador de auditoría conectado, cada frontera de aserción emite un registro ALLOW (INFO) o DENY (WARNING) antes de cualquier lanzamiento por violación de política. Por lo tanto, cada denegación con FipsViolationException queda evidenciada en la traza. La puerta del guardián de arranque se ejecuta primero, de modo que un rechazo por estado de error se produce antes del registro de auditoría. El FipsAuditLogger consulta la misma política que aplica el guardián, de modo que las decisiones registradas no pueden divergir de las aplicadas.

Casos límite y modos de fallo

Un tipo de clave desconocido se deniega en ambas capas: la política devuelve false y el catálogo lo trata como no permitido.
Un identificador de algoritmo de firma que el enforcer no puede mapear a un OID de firma se rechaza fail-closed con FipsViolationException.
Cada variante RSASSA-PSS comparte el OID 1.2.840.113549.1.1.10, de modo que el OID por sí solo no puede demostrar el digest. El enforcer vincula el digest efectivo de forma explícita y deniega cualquier token PSS cuyo digest no sea SHA-256/384/512.
Un certificado que no puede analizarse, o cuya longitud en bits de la clave pública no está disponible, se deniega como key:unprovable.
En un entorno de ejecución sin las primitivas asimétricas de OpenSSL, la prueba de consistencia por pares ECDSA registra un fallo, no una omisión, y el módulo entra en ERROR.
Dos sorteos aleatorios sucesivos idénticos de 32 bytes fallan la comprobación de salud del DRBG (detección de salida atascada) y fuerzan ERROR.
Un FipsModeGuard construido sin un guardián de arranque realiza únicamente comprobaciones de política y no tiene puerta de autoprueba. La composición de producción pasa por FipsBootstrap, que siempre conecta la puerta.
Los nombres de hash y de cifrado se comparan en minúsculas; los OID de firma se comparan de forma exacta, sin normalización.
Tras FipsBootstrap::lazy(), el módulo permanece en PRE_OPERATIONAL hasta que la primera frontera de aserción ejecute la batería. PRE_OPERATIONAL se trata como no operativo en el momento de la aserción.

Comportamiento en modo FIPS

Este módulo es la propia superficie del modo FIPS. Mientras el módulo está en el estado de error, y mientras se ejecutan las autopruebas preoperacionales, la salida criptográfica queda inhibida: cada frontera de aserción lanza FipsModuleErrorStateException antes de que se produzca cualquier firma o texto cifrado (ISO/IEC 19790:2025 §7.3.3 b), AS03.07). FipsBootGuard::status() y FipsBootstrap::selfTestReport() exponen el estado para que un operador pueda determinar que el módulo entró en el estado de error (ISO/IEC 19790:2025 §7.10.3). Estos comportamientos son declaraciones de capacidad sobre el código de NextPDF, no una declaración de validación: la frontera de módulo que valida FIPS 140 es el proveedor criptográfico suministrado por el operador, no NextPDF.

Conformidad

Declaración	Estándar	Cláusula
FIPS 140-3 se basa en ISO/IEC 19790 e ISO/IEC 24759; por eso esta página cita cláusulas de ISO/IEC 19790.	FIPS 140-3	Introduction (fips_140_3#x26.x2)
La salida queda inhibida en el estado de error y durante las autopruebas preoperacionales.	ISO/IEC 19790:2025	§7.3.3 b) [AS03.07]
Una prueba de respuesta conocida compara un resultado calculado con una salida esperada conocida; la batería implementa esta forma.	ISO/IEC 19790:2025	§7.10.4
El operador puede determinar el estado de error a través de una salida de estado.	ISO/IEC 19790:2025	§7.10.3 [AS10.10]
Los operadores pueden iniciar las autopruebas bajo demanda para pruebas periódicas; `rerun()` y `selfTestReport()` lo proporcionan.	ISO/IEC 19790:2025	§7.10.5 [AS10.54]
SHA-1 no se permite para la generación de nuevas firmas digitales; el catálogo de denegación lo rechaza.	NIST SP 800-131A Rev.2	§9
La generación de firmas por debajo de 112 bits de fortaleza (RSA < 2048, orden ECDSA < 224) no se permite; los pisos de clave lo aplican.	NIST SP 800-131A Rev.2	§3 Table 2
La verificación de firmas SHA-1 ya generadas es uso heredado; no pasa por la puerta de generación.	NIST SP 800-131A Rev.2	Change summary (9.x4.p12)

Todas las cláusulas están parafraseadas; no se reproduce texto normativo. NextPDF no hace ninguna declaración de certificación FIPS 140. El módulo alinea su comportamiento con las cláusulas citadas como una capacidad de asistencia a la conformidad. Que un despliegue sea conforme a FIPS depende del proveedor validado del operador, de la definición de la frontera del módulo y del programa de conformidad, no de NextPDF por sí solo.

Notas de desarrollo

Las pruebas de fallo deterministas inyectan proveedores rotos a través del constructor de FipsSelfTest, o a través de los parámetros $selfTest en FipsCryptoPolicy::strict(), standard() y los métodos de FipsBootstrap.
El enclavamiento persistente del estado de error tiene un gancho de restablecimiento interno, solo para pruebas. No forma parte de la API soportada, y el código de producción no debe invocarlo.
Cada proceso worker de PHP ejecuta su propia batería de arranque. El informe se cachea por instancia, de modo que las aserciones en la ruta caliente son comprobaciones de estado de tiempo constante.
No captures FipsModuleErrorStateException y continúes. La excepción significa que el módulo rechaza los servicios criptográficos; la respuesta correcta es detener y reiniciar el proceso tras la remediación.
FipsBootstrap::selfTestReport() cubre necesidades de autoprueba bajo demanda y periódicas, como los endpoints de salud. Una ejecución bajo demanda que pase nunca despeja un error enclavado.

Véase también

Política criptográfica FIPS 140-2/3 y autoprueba — la página de capacidad con configuración y ejemplos.
Seguridad — Referencia detallada — los controles de seguridad Enterprise combinados.
Firma — Referencia detallada — el productor PAdES de largo plazo y su nota sobre el modo FIPS.
Seguridad — NextPDF Core — la superficie de cifrado y firma de Core a la que se vincula la política.

Límite de publicación

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