Enterprise edição

Segurança — HSM, PKCS#11 e modo FIPS

Em resumo

O NextPDF Enterprise acrescenta um caminho de assinatura com token de hardware PKCS#11 e uma política criptográfica em modo FIPS sobre a superfície de segurança do Core e do Pro. Esta página declara comportamento, limites e a postura explícita de certificação FIPS e de custódia de chaves.

Disponibilidade e licenciamento

Este recurso é fornecido no NextPDF Enterprise (nextpdf/enterprise) e é ativado com um envelope de licença de nível Enterprise. Uma implantação sem essa habilitação não carrega as classes do recurso. Compare edições e obtenha uma licença.

Visão conceitual

A superfície de segurança do Enterprise tem três partes: um signatário com token de hardware, uma política criptográfica em modo FIPS e um guard de autoteste na inicialização.

O signatário com token de hardware adapta um token PKCS#11 — um cartão inteligente, um dispositivo USB ou um HSM conectado à rede. O signatário localiza o certificado e a chave privada no token por rótulo. Em seguida, ele pede ao token que calcule a assinatura. A chave privada não sai do limite do token; a operação é executada dentro do token. A operação de assinatura do token, a sessão e o login do usuário seguem PKCS#11 v3.1 §5. O caminho do HSM precisa da extensão PHP ext-pkcs11. Essa extensão não faz parte do PHP padrão. Instale-a separadamente. Use a verificação de disponibilidade antes de construir o signatário.

A política criptográfica em modo FIPS restringe as escolhas criptográficas a um conjunto aprovado. Ela tem dois presets. O preset estrito permite hashes SHA-256, SHA-384 e SHA-512; OIDs de assinatura RSA e ECDSA com esses hashes; criptografia AES-256-CBC; e tamanhos mínimos de chave de RSA 2048 e EC 256. O preset padrão é o mesmo, mas também permite AES-128-CBC para interoperabilidade mais antiga. Um guard de tempo de execução envolve a política. O guard verifica cada hash, OID de assinatura, algoritmo de criptografia e força de chave antes de a operação ser executada. Uma escolha não permitida lança uma violação tipada e interrompe a operação. O caminho é fail-closed: a política nunca se relaxa e nunca substitui por um algoritmo mais fraco. O comprimento mínimo de chave RSA segue NIST SP 800-131A Rev.2 §3. O par de curva e hash ECDSA segue FIPS 186-5 §6.1.1.

O guard de autoteste na inicialização executa uma bateria de testes de resposta conhecida (known-answer test) uma vez no início do processo. A bateria cobre as funções aprovadas de hash, MAC, criptografia, assinatura e bits aleatórios. Se algum teste falhar, o guard FIPS do Enterprise entra em estado de erro e recusa os serviços criptográficos até a redefinição. O resultado é armazenado em cache pela duração do processo; uma reexecução sob demanda está disponível. A categoria de autoteste e o gatilho de teste condicional seguem ISO/IEC 19790:2025 §7.10 e §7.10.3.

Por que funciona assim

A decisão de sustentação é manter a chave privada dentro do limite do token e tornar a política criptográfica fail-closed. Um signatário que pudesse exportar uma chave, ou recorrer silenciosamente a um algoritmo mais fraco, anularia a garantia que um HSM existe para fornecer. Assim, o signatário pede ao token que calcule a assinatura no local, e o guard de modo FIPS rejeita qualquer hash, OID ou força de chave fora do preset aprovado antes de a operação ser executada. O autoteste na inicialização estende a mesma postura à inicialização: um módulo não verificado recusa o serviço em vez de assinar sobre primitivas não testadas. O resultado é um limite sobre o qual você consegue raciocinar, no qual a custódia de chaves pertence ao operador e ao token, não a este software.

Contexto de projeto: Assinatura baseada em HSM.

Superfície da API

Superfície pública	Tipo	Finalidade	Estabilidade	Desde
Signatário com token PKCS#11	classe (implementa o `HsmSignerInterface` do Core)	Assina com um token PKCS#11; a chave permanece no token	stable	1.0.0
Política criptográfica FIPS	classe (implementa o `CryptoPolicyInterface` do Core)	Um preset de algoritmos permitidos e de força de chave	stable	1.9.0
Guard de modo FIPS	classe	Verifica se um hash, OID de assinatura, algoritmo de criptografia ou força de chave é permitido	stable	1.9.0
Guard de boot FIPS	classe	Executa e armazena em cache o autoteste na inicialização; verifica se o módulo está operacional	stable	3.2.0
Signatário OpenSSL CLI / engine	classe (implementa `HsmSignerInterface`)	Assina por meio de um engine OpenSSL ou da CLI do OpenSSL para tokens baseados em engine	stable	1.0.0

O construtor do signatário de token recebe o caminho da biblioteca PKCS#11, o número do slot, o PIN do token, o rótulo do certificado e um rótulo de chave separado opcional. O parâmetro de PIN é marcado como sensível; ele não é registrado em log nem serializado. O signatário também expõe o certificado de signatário e a cadeia de certificados na forma DER. O contrato autoritativo de parâmetros e tipos é a referência de API publicada do pacote nextpdf/enterprise; trate essa referência — não esta página — como o contrato.

Exemplo de código — Início rápido

composer require nextpdf/core
composer require nextpdf/enterprise:^3

use NextPDF\Enterprise\Security\Fips\FipsCryptoPolicy;
use NextPDF\Enterprise\Security\Fips\FipsModeGuard;

$guard = new FipsModeGuard(FipsCryptoPolicy::strict());

// Throws a typed FIPS violation if the algorithm is not approved.
$guard->assertHashAllowed('sha256');
$guard->assertKeyStrengthAllowed('rsa', 2048);

Exemplo de código — Produção

use NextPDF\Enterprise\Security\Fips\FipsBootGuard;
use NextPDF\Enterprise\Security\Fips\FipsSelfTest;

// At application bootstrap (one self-test cycle per worker process):
$bootGuard = new FipsBootGuard(new FipsSelfTest());
$bootGuard->assertOperational(); // throws on a known-answer-test failure
$container->set(FipsBootGuard::class, $bootGuard);

// The PKCS#11 token signer is only available when ext-pkcs11 is loaded.
// Check availability before you construct the signer. The PIN is a secret;
// supply it from your secret manager, never from source or logs.

A lista completa de argumentos do construtor, os tipos de exceção e a construção do signatário com token PKCS#11 estão documentados na referência profunda de segurança do Enterprise.

Casos extremos e armadilhas

O construtor do signatário com token PKCS#11 lança uma exceção de operação tipada quando ext-pkcs11 não está carregada. Verifique a disponibilidade primeiro.
O signatário de token armazena em cache um módulo PKCS#11 por caminho de biblioteca por processo. Isso satisfaz a regra de “inicializar uma vez por módulo” da interface de token.
Os mecanismos de token ECDSA retornam uma assinatura bruta. O signatário a converte para a forma codificada em DER para interoperabilidade com PDF e OpenSSL.
O guard FIPS nega um tipo de chave desconhecido por padrão. Um tipo de chave não reconhecido não é aceito silenciosamente.
O caminho de assinatura pós-quântico é experimental, opt-in e desativado por padrão. Os perfis padrão de arquivamento de longo prazo PAdES ainda não reconhecem suítes pós-quânticas. Não o ative para assinaturas AdES de produção.

Desempenho

As verificações do guard FIPS são consultas de hash-map de tempo constante. O autoteste na inicialização é executado uma vez por processo; seu custo é amortizado pela duração do processo, não por chamada de assinatura. Uma operação de assinatura PKCS#11 acrescenta uma ida e volta ao token. Um HSM conectado à rede acrescenta a latência de rede dessa ida e volta.

Notas de segurança

O caminho de assinatura é fail-closed. Uma falha de primitiva ou uma lacuna de política lança uma exceção tipada. O caminho nunca faz downgrade silencioso para um algoritmo mais fraco.
O parâmetro de PIN do token é marcado como sensível. Ele não é registrado em log nem serializado.
A chave privada de um token PKCS#11 permanece no token. A operação de assinatura é executada dentro do limite do token.
O autoteste na inicialização coloca o guard FIPS do Enterprise em estado de erro em uma divergência de teste de resposta conhecida e recusa os serviços criptográficos até a redefinição.
O uso de AES-GCM exige um vetor de inicialização único por chave, conforme NIST SP 800-38D §5.

Residência de dados e mitigações de PII

O código de assinatura e de política FIPS é executado em processo. Nenhum conteúdo de documento sai do host para a verificação de política FIPS ou para o autoteste na inicialização. Um token PKCS#11 recebe os dados a assinar, não conteúdo de documento não relacionado. Um HSM conectado à rede recebe esses dados pelo canal de rede que você configura. O material de chave permanece dentro do limite do token ou do HSM.

Telemetria segura e limpeza de logs

O PIN do token é um parâmetro de construtor sensível e é excluído de logs e da serialização. Não adicione o PIN, o rótulo do token nem material de chave aos logs do seu próprio aplicativo. Trate todas as credenciais de token como segredos na sua política de log e de rastreamento.

Modelo de ameaças

Este é um limite criptográfico, portanto o modelo de ameaças é explícito. Os dados a assinar são entregues ao token; o token detém a chave. Um erro de token ou HSM lança uma exceção tipada; o signatário não produz um resultado não assinado ou parcialmente assinado. A proteção de chave depende do token ou do HSM, da implantação e do operador — não deste software sozinho. Consulte o limite de implantação.

Conformidade

O modelo de autoteste na inicialização e condicional alinha-se com ISO/IEC 19790:2025 §7.10 e §7.10.3.
O comprimento mínimo de chave de assinatura RSA alinha-se com NIST SP 800-131A Rev.2 §3.
O par aprovado de curva e hash ECDSA alinha-se com FIPS 186-5 §6.1.1.
A operação de assinatura do token PKCS#11 e o login de sessão alinham-se com PKCS#11 v3.1 §5.
A responsabilidade de proteção de chave alinha-se com NIST SP 800-57 Part 1 Rev.5 §5.5.2.
A unicidade do vetor de inicialização do AES-GCM alinha-se com NIST SP 800-38D §5.

Toda fonte normativa é parafraseada. Nenhum texto normativo é reproduzido nesta página. Esta página trata de assinatura criptográfica.

Comportamento em modo FIPS

A política de modo FIPS restringe as escolhas criptográficas ao conjunto aprovado descrito acima. Quando configurada contra um provedor OpenSSL validado por FIPS, a primitiva subjacente é executada dentro desse limite validado. O próprio NextPDF Enterprise realiza a montagem estrutural, o cálculo de resumo e a imposição de política.

O NextPDF Enterprise não é um módulo criptográfico validado por FIPS e não faz nenhuma declaração de certificação FIPS. O NextPDF Enterprise opera em um modo compatível com FIPS apenas quando é configurado com um provedor de criptografia validado por FIPS — por exemplo, um provedor OpenSSL validado por FIPS — ou um HSM validado por FIPS. A política de modo FIPS auxilia a conformidade; ela não é uma certificação.

Limite de edição

O NextPDF Core fornece o signatário por software, o consumo de carimbo de data/hora RFC 3161, a validação de caminho RFC 5280 e a verificação de revogação OCSP e CRL. O Core produz os níveis PAdES B-B e B-T. O NextPDF Pro acrescenta mascaramento, detecção de PII na camada de texto, assinatura sequencial multiparte e estratégias de assinatura remota e em cloud-KMS (AWS KMS, GCP Cloud KMS, Azure Key Vault). O NextPDF Pro não fornece um caminho de token de hardware PKCS#11 e não fornece um perfil de política criptográfica em modo FIPS. O signatário com token de hardware PKCS#11, o perfil de política criptográfica em modo FIPS, o guard de autoteste na inicialização e o produtor PAdES B-LT e B-LTA são fornecidos apenas no pacote nextpdf/enterprise. Uma implantação sem a habilitação do Enterprise não carrega as classes do Enterprise.

Alternativa do Pro

Em uma implantação somente Pro, o caminho de assinatura baseado em hardware e em nuvem suportado é a estratégia em cloud-KMS do Pro: um KMS em nuvem ou um KMS baseado em HSM detém a chave, e o Pro envia o resumo dos atributos assinados, não o documento, ao provedor. O Pro fornece integração com KMS, não a fábrica de token PKCS#11 do Enterprise nem o perfil de modo FIPS. Uma configuração que solicita B-LT, B-LTA, um token PKCS#11 ou o perfil de modo FIPS em uma implantação somente Pro falha de forma segura com uma mensagem que nomeia o componente Enterprise ausente. Consulte Security — NextPDF Pro para a superfície de assinatura do Pro.

Alternativa do Core

Em uma implantação somente Core, o signatário por software produz PAdES B-B e B-T com uma chave local ou uma chave fornecida por meio do contrato de estratégia de assinatura do Core. O Core não tem caminho de token de hardware nem perfil de modo FIPS. Consulte Security — NextPDF Core.

Nota sobre o limite do Enterprise

A integração com o token PKCS#11, seu mapeamento de mecanismo e seu tratamento de sessão são descritos apenas no nível de comportamento. A tabela interna de mapeamento de mecanismo, a lógica interna de recuperação de sessão e o material de migração pós-quântica estão fora do escopo da superfície pública e não são reproduzidos aqui.

Limite de implantação

O NextPDF Enterprise integra-se a um token PKCS#11, a um HSM ou a um KMS. Ele não armazena, gera nem garante por si só a segurança da chave de assinatura. A segurança da chave depende do token, do HSM ou do KMS, da implantação e do operador — não do NextPDF Enterprise sozinho. O operador é responsável pelo provisionamento de token, pelo tratamento de PIN, pela configuração de slot, pela proteção de rede de um HSM conectado à rede e pela configuração de confiança. A responsabilidade de proteção de chave segue NIST SP 800-57 Part 1 Rev.5 §5.5.2. O NextPDF Enterprise não expõe o tratamento de PIN de token, os detalhes internos de configuração de slot nem material de credencial de fornecedor nesta documentação.

Limite jurídico de conformidade

Ela trata de assinatura criptográfica e de integração com módulo de segurança de hardware. A política de modo FIPS é um recurso de assistência à conformidade. Ela não é um parecer jurídico nem uma certificação. Consulte seus próprios assessores de conformidade e jurídicos para conhecer suas obrigações regulatórias.

Limite de publicação

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

Contrato de comportamento

O guard FIPS verifica cada hash, OID de assinatura, algoritmo de criptografia e força de chave contra o preset ativo e lança uma violação tipada em uma escolha não permitida.
O autoteste na inicialização é executado uma vez por processo e recusa os serviços criptográficos em uma falha de teste de resposta conhecida até a redefinição.
O signatário com token PKCS#11 requer ext-pkcs11; ele lança uma exceção de operação tipada quando a extensão está ausente.
O caminho de assinatura é fail-closed e nunca substitui por um algoritmo mais fraco.

Consulte também

Security — NextPDF Enterprise (referência profunda)
Security — NextPDF Pro
Signature — NextPDF Enterprise
Accelerator — NextPDF Enterprise
Security — NextPDF Core
PAdES · HSM · PKCS#11 · FIPS mode · KMS — termos do glossário.