Enterprise ediçãoestabilidade: Experimental

Preview de assinatura pós-quântica — Referência Profunda

Visão geral

Esta página é a referência em nível de contrato da superfície de preview de assinatura pós-quântica (PQS) no NextPDF Enterprise. Ela cobre três símbolos públicos: o enum de conjuntos de parâmetros Pkcs11PqsAlgorithm, o gate de processo PqsPreviewFeature e o descritor PqsCapabilityStatus. Ela também documenta o gate de ambiente NEXTPDF_FEATURE_PREVIEW_PQS_HSM.

A superfície é experimental e desativada por padrão. Ela reconhece identificadores de algoritmo, conjuntos de parâmetros e comprimentos de assinatura de ML-DSA (FIPS 204) e SLH-DSA (FIPS 205). Reconhecimento não é um veredito de validação. Não há caminho de verificação pós-quântica. Nenhuma alegação de AdES, de validação FIPS ou de conformidade é feita, e a flag de preview não pode criar uma. O ponto de entrada de assinatura consumidor, Pkcs11Signer::signPqs(), é descrito na página de capacidade.

Disponibilidade e licenciamento

Esta capacidade vem no NextPDF Enterprise (nextpdf/enterprise) e ativa com um envelope de licença de tier Enterprise. Uma implantação sem essa titularidade não carrega as classes da capacidade. Compare edições e obtenha uma licença.

A licença ativa a superfície PKCS#11 do Enterprise como um todo. O caminho pós-quântico dentro dela permanece um preview independentemente do tier de licença. Dois opt-ins independentes ainda são exigidos: o gate de processo documentado aqui e a flag de construtor por signatário no Pkcs11Signer.

Superfície de API pública

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
`Pkcs11PqsAlgorithm`	enum lastreado em string, 15 casos	Nomeia um conjunto de parâmetros FIPS 204 / FIPS 205 por caso	caso do enum	Nada no acesso ao caso	Os valores dos casos são os nomes dos conjuntos de parâmetros, por exemplo `ML-DSA-65`.
`Pkcs11PqsAlgorithm::isMlDsa()`	nenhum	Teste de família	`bool`	Não lança	`true` para `MlDsa44`, `MlDsa65`, `MlDsa87`.
`Pkcs11PqsAlgorithm::isSlhDsa()`	nenhum	Negação de `isMlDsa()`	`bool`	Não lança	`true` para os doze casos SLH-DSA.
`Pkcs11PqsAlgorithm::mechanismId()`	nenhum	Mapeia a família para o id de mecanismo PQ candidato do PKCS#11 v3.1	`int`	`Error` do PHP quando o runtime não tem as constantes PQ provisórias do `Pkcs11`	`CKM_ML_DSA` ou `CKM_SLH_DSA`; ambos os ids são provisórios.
`Pkcs11PqsAlgorithm::parameterSetId()`	nenhum	Mapeia o caso para o discriminador de conjunto de parâmetros da OASIS	`int`	`Error` do PHP quando o runtime não tem as constantes PQ provisórias do `Pkcs11`	Valores `CKP_*`; provisórios.
`Pkcs11PqsAlgorithm::signatureLength()`	nenhum	Comprimento em bytes da assinatura mandatado pelo FIPS para o caso	`int` (positivo)	Não lança	Consumido pelo caminho de assinatura para rejeitar uma assinatura retornada de comprimento inesperado.
`Pkcs11PqsAlgorithm::nistCategory()`	nenhum	Categoria de força de segurança NIST alegada	`int`	Não lança	Retorna 1, 2, 3 ou 5.
`PqsPreviewFeature`	enum lastreado em string, 1 caso	Caso único `PREVIEW_PQS_HSM`; constante `ENV_PREVIEW_PQS_HSM`	caso do enum	Nada no acesso ao caso	O gate de preview em nível de processo.
`PqsPreviewFeature::isEnabled()`	nenhum	Lê `getenv()` ao vivo; comparação estrita contra a string `1`	`bool`	Não lança	Variável ausente ou qualquer outro valor, incluindo `0`, `true`, `yes`, está desativado.
`PqsCapabilityStatus::__construct()`	nove campos readonly nomeados	Constrói uma instância arbitrária de descritor	`PqsCapabilityStatus`	Não lança	`current()` é o construtor canônico.
`PqsCapabilityStatus::current()`	nenhum	Constrói o descritor para o processo envolvente	`PqsCapabilityStatus`	Não lança	Todo booleano de alegação é fixo; apenas `hsmRoundtripPreviewEnabled` varia com o gate.
`PqsCapabilityStatus::summary()`	nenhum	Texto de status de uma linha	`string`	Não lança	A formulação não carrega nenhuma alegação de disponibilidade, arquivamento ou validação.

enum Pkcs11PqsAlgorithm: string

case MlDsa44 = 'ML-DSA-44';
case MlDsa65 = 'ML-DSA-65';
case MlDsa87 = 'ML-DSA-87';

case SlhDsaSha2_128s = 'SLH-DSA-SHA2-128s';
case SlhDsaShake_128s = 'SLH-DSA-SHAKE-128s';
case SlhDsaSha2_128f = 'SLH-DSA-SHA2-128f';
case SlhDsaShake_128f = 'SLH-DSA-SHAKE-128f';

case SlhDsaSha2_192s = 'SLH-DSA-SHA2-192s';
case SlhDsaShake_192s = 'SLH-DSA-SHAKE-192s';
case SlhDsaSha2_192f = 'SLH-DSA-SHA2-192f';
case SlhDsaShake_192f = 'SLH-DSA-SHAKE-192f';

case SlhDsaSha2_256s = 'SLH-DSA-SHA2-256s';
case SlhDsaShake_256s = 'SLH-DSA-SHAKE-256s';
case SlhDsaSha2_256f = 'SLH-DSA-SHA2-256f';
case SlhDsaShake_256f = 'SLH-DSA-SHAKE-256f';

public function isMlDsa(): bool
public function isSlhDsa(): bool
public function mechanismId(): int
public function parameterSetId(): int
public function signatureLength(): int
public function nistCategory(): int

enum PqsPreviewFeature: string

case PREVIEW_PQS_HSM = 'preview_pqs_hsm';

public const string ENV_PREVIEW_PQS_HSM = 'NEXTPDF_FEATURE_PREVIEW_PQS_HSM';

public function isEnabled(): bool

final readonly class PqsCapabilityStatus

public const string MATURITY_PREVIEW_EXPERIMENTAL = 'preview-experimental';
public const string MECHANISM_STATUS_PROVISIONAL = 'provisional';

public function __construct(
    public bool $hsmRoundtripPreviewEnabled,
    public bool $generallyAvailable,
    public bool $adesCompliant,
    public bool $verificationAvailable,
    public bool $conformanceClaimed,
    public bool $recognitionOnly,
    public string $maturity,
    public string $mechanismIdStatus,
    public string $envGate,
)

public static function current(): self
public function summary(): string

Contrato de comportamento

Catálogo de conjuntos de parâmetros. NextPDF\Enterprise\Security\Signature\Hsm\Pkcs11PqsAlgorithm enumera três conjuntos ML-DSA (FIPS 204) e doze conjuntos SLH-DSA (FIPS 205 §11.p12, Table 2). Cada caso mapeia para um id de mecanismo provisório, um discriminador de conjunto de parâmetros, um comprimento em bytes de assinatura mandatado pelo FIPS e uma categoria NIST alegada.
Comprimentos de assinatura. signatureLength() retorna 2420, 3309 e 4627 bytes para MlDsa44, MlDsa65 e MlDsa87, conforme FIPS 204 §4.p15 (Table 2). Os casos SLH-DSA retornam 7856, 17088, 16224, 35664, 29792 e 49856 bytes por nível e variante, conforme FIPS 205 §11 (Table 2). O signatário consumidor lança HsmOperationException quando uma assinatura retornada tem comprimento diferente, espelhando a disciplina de rejeição por comprimento do FIPS 204 §x34.
Categorias. nistCategory() retorna 2, 3 e 5 para os casos ML-DSA, conforme FIPS 204 §4.p9. Os casos SLH-DSA retornam 1, 3 e 5 por nível de parâmetro de segurança.
Gate de processo. PqsPreviewFeature::PREVIEW_PQS_HSM vem desativado por padrão. isEnabled() retorna true apenas quando a variável de ambiente NEXTPDF_FEATURE_PREVIEW_PQS_HSM é exatamente igual à string 1. A leitura é ao vivo a cada chamada; nada é memoizado.
Gating complementar. O gate de processo é separado do opt-in de construtor por signatário $enablePostQuantum no Pkcs11Signer. A chamada de assinatura falha fechada sem o opt-in por signatário. O gate de processo existe como uma única fronteira auditável para qualquer comportamento futuro de round-trip ou arquivamento.
Invariante de honestidade. NextPDF\Enterprise\Security\Signature\Hsm\PqsCapabilityStatus::current() fixa em código generallyAvailable, adesCompliant, verificationAvailable e conformanceClaimed como false, e recognitionOnly como true. Nenhuma configuração, opção de construtor ou flag de ambiente vira uma alegação para ativada. Apenas hsmRoundtripPreviewEnabled reflete o gate.
Sem caminho de verificação. O NextPDF não tem caminho de verificação pós-quântica. Um identificador de algoritmo reconhecido ou um comprimento de assinatura bem formado nunca é um veredito de aceitação.

Casos extremos e modos de falha

Definir a variável do gate como 0, true, yes, on ou uma string vazia deixa o gate desativado. Apenas a string exata 1 o ativa.
Alterações via putenv() entram em vigor na próxima chamada a isEnabled() porque a leitura é ao vivo. Um gate alternado no meio do processo é observado imediatamente.
mechanismId() e parameterSetId() resolvem constantes do namespace da extensão Pkcs11. Um runtime sem as constantes provisórias da extensão pós-quântica falha com um Error do PHP (constante indefinida) no momento da chamada.
Os ids de mecanismo e de conjunto de parâmetros são provisórios. A OASIS não finalizou o registro pós-quântico do PKCS#11 v3.1. Um token cujo firmware atribui ids diferentes falhará na camada PKCS#11; os operadores devem confirmar os ids do firmware antes de ativar o preview.
O contexto de assinatura aceito pelo signatário consumidor é limitado a 255 bytes, correspondendo ao contrato de entrada de assinatura do FIPS 204 (§x43.p2). Um contexto mais longo lança InvalidArgumentException antes de qualquer chamada ao token.
PqsCapabilityStatus::__construct() é público, então uma instância construída à mão pode carregar booleanos arbitrários. Tal instância é apenas um value object. Ela não altera nenhum comportamento de assinatura. current() é o construtor canônico, fixado em código.
A escolha entre randomizado e determinístico no signatário consumidor segue a semântica do FIPS 205 §x65.p7: a assinatura hedged é o padrão. A flag é ignorada para ML-DSA, que sempre randomiza via seu próprio nonce.

Comportamento no modo FIPS

ML-DSA e SLH-DSA são algoritmos do FIPS 204 e FIPS 205, mas este preview não carrega nenhuma alegação de validação FIPS 140-3. Nenhum round-trip de HSM pós-quântico validado por FIPS foi estabelecido para este caminho. O perfil de crypto-policy do modo FIPS do Enterprise, documentado na referência aprofundada de Segurança, faz o gating dos algoritmos de assinatura clássicos; ele não admite a superfície PQS em um conjunto validado. Ativar o modo FIPS não torna a assinatura pós-quântica validada por FIPS. Não implante o preview onde uma assinatura validada por FIPS seja exigida.

Conformidade

Alegação	Padrão	Cláusula
ML-DSA-44/65/87 carregam categorias NIST alegadas 2, 3, 5.	FIPS 204	§4.p9
Os tamanhos de assinatura ML-DSA são 2420, 3309, 4627 bytes.	FIPS 204	§4.p15 (Table 2)
A string de bytes de contexto de assinatura é limitada a 255 bytes.	FIPS 204	§x43.p2
Uma assinatura ou chave de comprimento incorreto deve ser rejeitada.	FIPS 204	§x34
Doze conjuntos de parâmetros SLH-DSA são aprovados.	FIPS 205	§11.p12 (Table 2)
Os tamanhos de assinatura SLH-DSA seguem a Table 2 (7856 bytes para 128s).	FIPS 205	§11.p6
A assinatura hedged é o padrão; existe uma variante determinística.	FIPS 205	§x65.p7
O catálogo de suítes CAdES/PAdES perfila apenas RSA e EC-DSA.	ETSI TS 119 312 V1.5.1	§7.x7.p10 (Table A.1)
Os ids de mecanismo PQ do PKCS#11 são provisórios.	OASIS PKCS#11 v3.1	fundamentado no código-fonte do produto

Todas as cláusulas são parafraseadas. O NextPDF não reproduz texto normativo. O NextPDF não detém nenhuma certificação e não concede nenhuma. As declarações acima são declarações de alinhamento estrutural sobre identificadores, comprimentos e limites. Elas não são resultados de teste de conformidade, não são atestações de terceiros e não são uma alegação de conformidade FIPS, OASIS ou ETSI. PqsCapabilityStatus codifica essa postura no código: conformanceClaimed é false, adesCompliant é false e verificationAvailable é false, em toda configuração. Uma assinatura produzida por este preview não é compatível com AdES para arquivamento de longo prazo, e a maioria dos visualizadores de PDF a rejeita no momento da validação.

Notas de desenvolvimento

O registro de mecanismos pós-quânticos do OASIS PKCS#11 não está finalizado; os ids CKM_ML_DSA / CKM_SLH_DSA e as constantes de conjunto de parâmetros usados aqui são provisórios e fundamentados no código-fonte do produto, não em uma citação de especificação.
O marco atual é a prontidão testada com mocks. Nenhum round-trip real de HSM com firmware pós-quântico foi validado ainda.
Mantenha ambos os gates desativados em produção. O preview não adiciona nenhuma capacidade de produção que o caminho PKCS#11 clássico RSA/ECDSA não tenha.
Antes de qualquer avaliação com hardware real, confirme os ids de mecanismo e de conjunto de parâmetros do firmware do token contra os valores provisórios. Uma incompatibilidade falha na camada PKCS#11, não dentro do NextPDF.
Trate PqsCapabilityStatus::current() como a única fonte de verdade ao expor o status PQS em ferramentas ou UI. Não reafirme seus booleanos manualmente.
A saída de summary() é segura para logs e endpoints de status; ela é formulada para não carregar nenhuma alegação de disponibilidade ou validação.

Veja também

Fronteira de publicação

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