Enterprise edição

FIPS 140 — Referência Profunda

Visão geral

Esta página é a referência detalhada do módulo FIPS 140 do NextPDF Enterprise. O módulo é uma capacidade de política e autoteste. Ele restringe as escolhas criptográficas a uma allow-list alinhada ao FIPS, executa uma bateria de known-answer-test na inicialização e inibe a saída criptográfica quando a bateria falha. O NextPDF não é um módulo criptográfico validado por FIPS 140, não possui certificação e não concede nenhuma. Suporte não equivale a conformidade, e conformidade não equivale a certificação. Uma implantação compatível com FIPS exige adicionalmente um provedor criptográfico validado por FIPS fornecido pelo operador.

Disponibilidade e licenciamento

Esta capacidade é distribuída no NextPDF Enterprise (nextpdf/enterprise) e é ativada com um envelope de licença de nível Enterprise. Uma implantação sem essa habilitação não carrega as classes da capacidade. Compare as edições e obtenha uma licença.

Superfície pública da API

Todos os símbolos residem em NextPDF\Enterprise\Security\Fips, exceto FipsBootstrap em NextPDF\Enterprise\Bootstrap.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
`FipsBootstrap::boot()`	`?CryptoPolicyInterface $policy`, `?FipsSelfTest $selfTest`, `?LoggerInterface $auditLogger` (todos com padrão `null`)	Executa a bateria de inicialização uma vez na partida; usa por padrão a política strict	`FipsModeGuard`	`FipsModuleErrorStateException` em qualquer falha de teste de inicialização	Raiz de composição; trilha de auditoria desativada quando `$auditLogger` é `null`
`FipsBootstrap::lazy()`	Igual a `boot()`	Adia a bateria para a primeira asserção de fronteira	`FipsModeGuard`	Nenhuma no momento da chamada; a primeira asserção pode lançar `FipsModuleErrorStateException`	O módulo permanece `PRE_OPERATIONAL` até a primeira asserção
`FipsBootstrap::signatureEnforcer()`	`?CryptoPolicyInterface $policy = null`, `?FipsSelfTest $selfTest = null`	Inicializa o módulo e então envolve o guard para os chokepoints do signatário	`FipsSignatureEnforcer`	`FipsModuleErrorStateException` em qualquer falha de teste de inicialização	Delega a `boot()`
`FipsBootstrap::selfTestReport()`	`?FipsSelfTest $selfTest = null`	Executa a bateria sob demanda e a resume	`array{status: FipsSelfTestStatus, operational: bool, failed: list<string>}`	Não lança; as falhas aparecem em `failed`	Para endpoints de health de admin e uso via CLI
`FipsCryptoPolicy::strict()`	`?FipsSelfTest $selfTest = null`	Preset FIPS 140-3: SHA-256/384/512; OIDs aprovados de RSA, RSASSA-PSS, ECDSA; `aes-256-cbc`, `aes-256-gcm`; RSA >= 2048, EC >= 256	`self`	Nenhuma	O construtor é privado; os presets são a única entrada
`FipsCryptoPolicy::standard()`	`?FipsSelfTest $selfTest = null`	Preset FIPS 140-2: conjunto strict mais `aes-128-cbc`	`self`	Nenhuma	Apenas para interoperabilidade legada
`FipsCryptoPolicy::assertPreOperational()`	Nenhum	Executa, ou reproduz o resultado travado da, bateria de inicialização	`void`	`FipsModuleErrorStateException` quando qualquer teste de inicialização falha	Acionado pelo seam de enforcement do Core antes da primeira operação
Superfície de consulta de `FipsCryptoPolicy`	Entradas `string` / `int`	Verificações de pertencimento à allow-list; tipo de chave desconhecido é negado	`bool` / `string`	Nenhuma	`isHashAlgorithmAllowed`, `isSignatureAlgorithmAllowed`, `isEncryptionAlgorithmAllowed`, `isKeyStrengthAllowed`, `getPreferredHashAlgorithm`, `getName`
`FipsModeGuard::__construct()`	`CryptoPolicyInterface $policy`, `?FipsBootGuard $bootGuard = null`, `?FipsAuditLogger $auditLogger = null`	Envolve uma política com fronteiras estilo assert	—	Nenhuma	Sem `$bootGuard` não há gate de autoteste; a composição de produção o fornece
`FipsModeGuard::assertHashAllowed()`	`string $algorithm`	Catálogo de deny primeiro, depois a allow-list	`void`	`FipsViolationException`; `FipsModuleErrorStateException` quando um boot guard está conectado	O registro de auditoria precede qualquer `FipsViolationException`
`FipsModeGuard::assertSignatureAlgorithmAllowed()`	`string $oid`	Catálogo de deny primeiro, depois a allow-list	`void`	Igual ao acima	Os OIDs são comparados exatamente
`FipsModeGuard::assertEncryptionAllowed()`	`string $algorithm`	Catálogo de deny primeiro, depois a allow-list	`void`	Igual ao acima	Os nomes são comparados em minúsculas
`FipsModeGuard::assertKeyStrengthAllowed()`	`string $keyType`, `int $bitLength`	Catálogo de deny primeiro, depois os mínimos da política	`void`	Igual ao acima	Tipo de chave desconhecido é negado
`FipsModeGuard::getPolicy()`	Nenhum	Retorna a política envolvida	`CryptoPolicyInterface`	Nenhuma	—
`FipsBootGuard::__construct()`	`FipsSelfTest $selfTest`	Mantém a bateria; não a executa	—	Nenhuma	Um ciclo de inicialização por instância
`FipsBootGuard::report()`	Nenhum	Executa a bateria uma vez, faz cache do relatório, trava em caso de erro	`FipsSelfTestReport`	Nenhuma	A primeira chamada executa os testes
`FipsBootGuard::rerun()`	Nenhum	Força uma nova execução; uma execução com erro trava o processo	`FipsSelfTestReport`	Nenhuma	Autoteste sob demanda; não é um caminho de recuperação de erro
`FipsBootGuard::assertOperational()`	Nenhum	Afirma que o módulo está operacional; fixado ao longo do processo	`void`	`FipsModuleErrorStateException`	Uma instância limpa ainda lança quando o processo travou um erro
`FipsBootGuard::status()`	Nenhum	Reporta o status em cache	`FipsSelfTestStatus`	Nenhuma	`ERROR` quando travado; `PRE_OPERATIONAL` quando nunca executado
`FipsSelfTest::__construct()`	`?callable $randomBytesProvider = null`, `?callable $hashProvider = null`	Usa `hash()` e `random_bytes()` da plataforma	—	Nenhuma	Existem overrides para testes de falha determinísticos
`FipsSelfTest::run()`	Nenhum	Executa a bateria completa; nunca faz short-circuit	`FipsSelfTestReport`	Nenhuma	As falhas caem no relatório, não em exceções
`FipsSelfTestReport`	`FipsSelfTestStatus $status`, `array $results`, `array $failedResults`	Agregado imutável de uma execução	—	`assertOperational()` lança `FipsModuleErrorStateException` no estado de erro	Também `isOperational()`, `isError()`
`FipsSelfTestResult`	`string $algorithm`, `string $kind`, `bool $passed`, `string $message = ''`	Resultado imutável por teste	—	Nenhuma	`kind` é `KAT`, `PWCT` ou `HEALTH`; também `isPassed()`, `isFailed()`
`FipsSelfTestStatus`	—	Enum respaldado por string	—	Nenhuma	Casos `PRE_OPERATIONAL`, `OPERATIONAL`, `ERROR`
`FipsSignatureEnforcer::__construct()`	`FipsModeGuard $guard`	Envolve um guard com boot gate para os chokepoints de assinatura	—	Nenhuma	—
`FipsSignatureEnforcer::assertSignatureGenerationAllowed()`	`string $algorithm`, `string $certificatePem`	Resolve o OID e a força da chave, depois delega ao guard	`void`	`FipsViolationException` (algoritmo desconhecido, digest PSS não aprovado, chave não comprovável ou negação de política); `FipsModuleErrorStateException` via o guard	Apenas o caminho de geração; a verificação nunca passa por aqui
`FipsAuditLogger::__construct()`	`CryptoPolicyInterface $policy`, `LoggerInterface $logger`	Envolve um logger PSR-3 e a mesma política que o guard aplica	—	Nenhuma	As decisões registradas não podem divergir das aplicadas
`FipsAuditLogger::logHashOperation()` / `logSignatureOperation()` / `logEncryptionOperation()` / `logKeyStrengthCheck()`	Entradas `string` / `int` por decisão	Registra ALLOW em INFO e DENY em WARNING	`bool` (true quando permitido)	Nenhuma	Contexto estruturado: nome da política, item, decisão
`FipsTransitioningAlgorithms`	Entradas `string` / `int`	Catálogo de deny estático do SP 800-131A Rev.2	`bool` / `list<string>`	Nenhuma	`isHashDisallowed`, `isSignatureOidDisallowed`, `isEncryptionDisallowed`, `isKeyStrengthDisallowed`, além de `disallowedHashes`, `disallowedSignatureOids`, `disallowedEncryption`
`FipsViolationException`	`string $policyName`, `string $violatingItem`, `string $reason`	Violação de política tipada com campos públicos readonly	—	—	Subtipo de `NextPDF\Exception\NextPdfException`
`FipsModuleErrorStateException`	`array $failedResults`, `?string $message = null`	Recusa em estado de erro carregando os resultados de teste que falharam	—	—	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 comportamento

A allow-list da política é a decisão autoritativa. FipsTransitioningAlgorithms adiciona uma camada de deny explícita do SP 800-131A Rev.2 acima dela, para mensagens de rejeição claras em auditoria. A camada de deny nunca amplia nem sobrepõe a allow-list.
FipsCryptoPolicy::strict() permite SHA-256, SHA-384 e SHA-512; RSA PKCS#1 v1.5, RSASSA-PSS e OIDs de assinatura ECDSA vinculados a esses hashes; aes-256-cbc e aes-256-gcm; e pisos de chave de RSA 2048, EC 256, Ed25519 256. standard() permite adicionalmente aes-128-cbc.
A bateria de inicialização cobre: KATs de digest SHA-256/384/512, um KAT de HMAC-SHA-256, um KAT de encriptação-e-decriptação AES-256-CBC, um KAT de tag AES-256-GCM, um teste de consistência pareada ECDSA P-256 e uma verificação de health do DRBG. FipsSelfTest::run() sempre executa todos os testes e nunca faz short-circuit, de modo que o relatório é completo como evidência de auditoria.
A linha do DRBG é um teste contínuo de health (comprimento do sorteio mais sorteios sucessivos distintos), não um known-answer test. A obrigação de known-answer do DRBG é delegada ao provedor validado por FIPS subjacente que o operador fornece.
O estado de erro é fixado ao processo. O primeiro relatório ERROR observado por qualquer FipsBootGuard trava o processo inteiro. Uma nova instância de guard ou política não pode limpar o erro, e uma execução posterior bem-sucedida não o remove. Apenas um reinício do processo (um verdadeiro ciclo de energia) redefine o estado.
FipsCryptoPolicy implementa NextPDF\Contracts\CryptoPolicyInterface e NextPDF\Contracts\PreOperationalSelfTestInterface. Quando configurado como a política criptográfica do Core, o seam de enforcement do Core aciona assertPreOperational() antes que a primeira assinatura ou texto cifrado seja produzido.
FipsSignatureEnforcer protege apenas o caminho de geração. A verificação de assinaturas já geradas é uso legado sob o SP 800-131A Rev.2 e nunca passa pelo enforcer.
Quando um audit logger está conectado, cada fronteira de assert emite um registro ALLOW (INFO) ou DENY (WARNING) antes de qualquer lançamento de violação de política. Toda negação por FipsViolationException fica, portanto, evidenciada na trilha. O gate do boot guard executa primeiro, então uma recusa em estado de erro é levantada antes do registro de auditoria. O FipsAuditLogger consulta a mesma política que o guard aplica, de modo que as decisões registradas não podem divergir das aplicadas.

Casos de borda e modos de falha

Um tipo de chave desconhecido é negado por ambas as camadas: a política retorna false e o catálogo o trata como não permitido.
Um identificador de algoritmo de assinatura que o enforcer não consegue mapear para um OID de assinatura é recusado fail-closed com FipsViolationException.
Toda variante de RSASSA-PSS compartilha o OID 1.2.840.113549.1.1.10, então o OID sozinho não pode comprovar o digest. O enforcer vincula o digest efetivo explicitamente e nega qualquer token PSS cujo digest não seja SHA-256/384/512.
Um certificado que não pode ser analisado, ou cujo comprimento em bits da chave pública está indisponível, é negado como key:unprovable.
Em um runtime sem os primitivos assimétricos do OpenSSL, o teste de consistência pareada ECDSA registra uma falha, não um skip, e o módulo entra em ERROR.
Dois sorteios aleatórios sucessivos idênticos de 32 bytes falham na verificação de health do DRBG (detecção de saída travada) e forçam ERROR.
Um FipsModeGuard construído sem um boot guard realiza apenas verificações de política e não tem gate de autoteste. A composição de produção passa pelo FipsBootstrap, que sempre conecta o gate.
Nomes de hash e de cifra são comparados em minúsculas; OIDs de assinatura são comparados exatamente, sem normalização.
Após FipsBootstrap::lazy(), o módulo permanece PRE_OPERATIONAL até que a primeira fronteira de assert execute a bateria. PRE_OPERATIONAL é tratado como não operacional no momento da asserção.

Comportamento no modo FIPS

Este módulo é a própria superfície do modo FIPS. Enquanto o módulo está no estado de erro, e enquanto os autotestes pré-operacionais executam, a saída criptográfica é inibida: cada fronteira de assert lança FipsModuleErrorStateException antes que qualquer assinatura ou texto cifrado seja produzido (ISO/IEC 19790:2025 §7.3.3 b), AS03.07). FipsBootGuard::status() e FipsBootstrap::selfTestReport() expõem o estado para que um operador possa determinar que o módulo entrou no estado de erro (ISO/IEC 19790:2025 §7.10.3). Esses comportamentos são declarações de capacidade sobre o código do NextPDF, não uma declaração de validação: a fronteira do módulo que o FIPS 140 valida é o provedor criptográfico fornecido pelo operador, não o NextPDF.

Conformidade

Declaração	Padrão	Cláusula
FIPS 140-3 é baseado no ISO/IEC 19790 e no ISO/IEC 24759; esta página, portanto, cita cláusulas do ISO/IEC 19790.	FIPS 140-3	Introduction (fips_140_3#x26.x2)
A saída é inibida no estado de erro e durante os autotestes pré-operacionais.	ISO/IEC 19790:2025	§7.3.3 b) [AS03.07]
Um known-answer test compara um resultado computado com uma saída esperada conhecida; a bateria implementa esse formato.	ISO/IEC 19790:2025	§7.10.4
O operador pode determinar o estado de erro por meio de uma saída de status.	ISO/IEC 19790:2025	§7.10.3 [AS10.10]
Os operadores podem iniciar os autotestes sob demanda para testes periódicos; `rerun()` e `selfTestReport()` fornecem isso.	ISO/IEC 19790:2025	§7.10.5 [AS10.54]
SHA-1 não é permitido para nova geração de assinatura digital; o catálogo de deny o rejeita.	NIST SP 800-131A Rev.2	§9
A geração de assinatura abaixo de 112 bits de força (RSA < 2048, ordem ECDSA < 224) não é permitida; os pisos de chave aplicam isso.	NIST SP 800-131A Rev.2	§3 Table 2
A verificação de assinaturas SHA-1 já geradas é uso legado; ela não passa pelo gate de geração.	NIST SP 800-131A Rev.2	Change summary (9.x4.p12)

Todas as cláusulas são parafraseadas; nenhum texto normativo é reproduzido. O NextPDF não faz nenhuma declaração de certificação FIPS 140. O módulo alinha seu comportamento às cláusulas citadas como uma capacidade de assistência à conformidade. Se uma implantação é ou não compatível com FIPS depende do provedor validado do operador, da definição da fronteira do módulo e do programa de conformidade — não do NextPDF sozinho.

Notas de desenvolvimento

Os testes de falha determinísticos injetam provedores quebrados através do construtor de FipsSelfTest, ou através dos parâmetros $selfTest em FipsCryptoPolicy::strict(), standard() e nos métodos de FipsBootstrap.
O latch de estado de erro fixado ao processo tem um hook de reset interno, apenas para testes. Ele não faz parte da API suportada, e o código de produção não deve chamá-lo.
Cada processo worker do PHP executa sua própria bateria de inicialização. O relatório é armazenado em cache por instância, de modo que as asserções no hot-path são verificações de status em tempo constante.
Não capture FipsModuleErrorStateException e continue. A exceção significa que o módulo recusa os serviços criptográficos; a resposta correta é parar e reiniciar o processo após a remediação.
FipsBootstrap::selfTestReport() atende necessidades de autoteste sob demanda e periódicas, como endpoints de health. Uma execução sob demanda bem-sucedida nunca limpa um erro travado.

Veja também

Política criptográfica e autoteste FIPS 140-2/3 — a página da capacidade com configuração e exemplos.
Segurança — Referência Detalhada — os controles de segurança combinados do Enterprise.
Assinatura — Referência Detalhada — o produtor PAdES de longo prazo e sua nota sobre o modo FIPS.
Segurança — NextPDF Core — a superfície de encriptação e assinatura do Core à qual a política se vincula.

Fronteira de publicação

Esta página documenta apenas o comportamento externamente observável e a superfície pública suportada da API. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismos, nomes de arquivos de runbook e prefixos de tickets estão fora de escopo.