Assinatura com HSM

Spec: ISO 32000-2, §12.8 Spec: FIPS 140-3 Evidence: Standard-backed

Visão geral

Um módulo de segurança de hardware (HSM) tira a chave de assinatura do processo e a coloca atrás de um dispositivo que assina sob demanda, mas nunca devolve a chave. Esta página explica a costura PKCS#11 pela qual o NextPDF assina, onde exatamente fica o limite da chave e quais partes do resultado são responsabilidade do motor, não do dispositivo nem sua.

Por que isso importa

Uma chave de assinatura na memória do processo fica exposta a qualquer coisa capaz de ler esse processo: um despejo de heap, um depurador, um erro de log ou uma dependência vulnerável. Depois que uma chave privada é copiada, toda assinatura que ela já produziu fica em xeque, e você não consegue torná-la secreta novamente. O objetivo de um HSM é não deixar existir uma cópia a ser capturada.

Errar o limite custa caro de forma silenciosa. Um fluxo de trabalho que parece respaldado por hardware, mas puxa a chave para a memória para assinar, tem o custo operacional de um HSM e o perfil de risco de uma chave em software. A distinção não aparece no PDF finalizado; portanto, precisa ser projetada e verificada, não presumida.

A versão curta

O padrão PKCS#11 define um objeto de chave marcado como sensível e não extraível. Seu valor privado não pode ser revelado em texto claro fora do token. Spec: PKCS#11, v3.1 §10.9
O NextPDF constrói a estrutura de assinatura do PDF e o contêiner CMS. Ele entrega os bytes a serem assinados por meio da costura PKCS#11 e recebe a assinatura de volta. A chave nunca cruza essa costura.
A costura é um contrato estável. O mesmo contrato é cumprido por um token de cartão inteligente, um HSM USB, um HSM de rede e um KMS em nuvem. O código do motor não muda entre eles.
O NextPDF é um software de motor de assinatura. A garantia de hardware do dispositivo, seu status de validação, a política de PIN e a implantação não são coisas que o motor certifica. Ele usa o dispositivo; não responde por ele.

Como o NextPDF aborda isso

A costura, com precisão

O NextPDF separa montar uma assinatura de computar o valor da assinatura. A montagem é tarefa do motor: posicionar o campo de assinatura, reservar espaço no arquivo, computar o intervalo de bytes e construir o SignedData do CMS com os atributos assinados. Spec: ISO 32000-2, §12.8

Computar o valor da assinatura é uma tarefa delegada. O motor define um pequeno contrato de provedor de assinatura: ele recebe uma sequência opaca de bytes (na prática, os atributos assinados codificados em DER) e retorna os octetos brutos da assinatura. Esse contrato é a costura. O conhecimento de PDF e CMS fica de um lado; a chave fica do outro. Um provedor pode manter essa chave no processo para uma chave de software local, em um KMS em nuvem ou em um token de hardware via PKCS#11. O código do motor acima da costura é idêntico em todos os casos. Só o provedor por trás dela muda.

Onde o limite realmente fica

PKCS#11 — a OASIS Cryptographic Token Interface, historicamente “Cryptoki” — é a interface C padrão para tokens de hardware. O caminho de hardware do NextPDF fala PKCS#11 (diretamente ou por meio de uma ponte de linha de comando OpenSSL para implantações de engine ou provider em que a vinculação em processo não consegue carregar um token).

O objeto de chave no token é criado com dois atributos que definem o limite. Quando a chave é marcada como sensível ou como não extraível, certos atributos privados não podem ser revelados em texto claro fora do token. Spec: PKCS#11, v3.1 §10.9 A própria operação de assinatura é uma única chamada ao token — C_SignInit e depois C_Sign — realizada pelo dispositivo. Spec: PKCS#11, v3.1 §5.10 O texto claro que o NextPDF manipula para a operação de assinatura são os bytes a serem assinados. O que volta é a assinatura e o certificado. A chave privada não está em nenhum desses caminhos. Esse é o limite, e quem o impõe é o token, não a biblioteca.

Step 1 of 4: ISO 32000-2 §12.8 — signature dictionary, ByteRange, Contents
Step 2 of 4: RFC 5652 CMS SignedData — the signature container
Step 4 of 4: FIPS 140-3 / ISO/IEC 19790 cryptographic module assurance (device-level, deployment-dependent)

Onde uma assinatura de PDF respaldada por hardware se ancora, em ordem: o portador PDF (ISO 32000-2 §12.8), o contêiner CMS que ele contém, a interface de token pela qual o NextPDF assina (PKCS#11) e os padrões de garantia de módulo que descrevem — mas não garantem por si sós — o dispositivo por trás dela.

Um PIN, uma reautenticação

PKCS#11 permite que uma chave exija reautenticação a cada uso: quando o atributo CKA_ALWAYS_AUTHENTICATE está definido, o usuário deve apresentar o PIN novamente para cada operação criptográfica, não uma vez por sessão. Spec: PKCS#11, v3.1 §10.9 O caminho PKCS#11 do NextPDF foi escrito para isso. O PIN é um parâmetro sensível. Ele não é registrado em log nem serializado. Quando uma sessão reporta um login existente, o NextPDF a retorna a um estado limpo, para que a próxima assinatura receba uma nova verificação de PIN. Isso é importante para tokens no estilo PIV, cuja política exige um PIN por assinatura. É comportamento do motor que respeita a política do dispositivo; não a flexibiliza.

O que as evidências dizem

Evidence: Standard-backed A propriedade de chave não extraível não é uma afirmação do NextPDF. É o modelo PKCS#11: um objeto de chave cujo CKA_SENSITIVE é verdadeiro ou CKA_EXTRACTABLE é falso não entrega seu valor privado em texto claro fora do token. Spec: PKCS#11, v3.1 §10.9 A contribuição do NextPDF é nunca precisar desse valor: ele assina por meio da operação C_Sign do token, em vez de pedir o material da chave.

Evidence: Standard-backed O lado do PDF está ancorado em Spec: ISO 32000-2, §12.8 . O resumo (digest) do intervalo de bytes é computado sobre o arquivo, excluindo o valor da assinatura. O valor da assinatura colocado na entrada Contents é um objeto SignedData CMS codificado em DER para assinaturas de chave pública. O HSM produz apenas os octetos mais internos da assinatura. O NextPDF constrói tudo ao redor deles e os escreve na estrutura que o padrão define.

Evidence: Standard-backed A garantia do dispositivo é descrita pelo Spec: FIPS 140-3 e seu padrão base ISO/IEC 19790, que definem quatro níveis qualitativos crescentes de segurança em onze áreas de requisito — da especificação de algoritmo à evidência física de violação. Esses padrões descrevem o que um módulo deve satisfazer para reivindicar um nível. São uma propriedade do dispositivo e de sua validação, não do NextPDF e — nas palavras da própria ISO/IEC 19790 — a conformidade por si só não é suficiente para garantir que um módulo seja seguro em uma dada implantação.

Exemplo prático

O formato abaixo é ilustrativo. Ele mostra a costura, não uma implantação pronta para copiar e colar. O ponto é que o motor recebe um signatário e nunca vê uma chave: o sign() do signatário é uma chamada ao dispositivo.

<?php

declare(strict_types=1);

use NextPDF\Contracts\HsmSignerInterface;

/**
 * Sign a PDF where the private key lives on a PKCS#11 token.
 *
 * `$hsm` is a hardware-backed signer. Its sign() delegates to the token;
 * the key never enters this process. Everything that makes the bytes a
 * valid PDF signature — field, byte range, CMS SignedData — is built by
 * the engine around the value the device returns.
 *
 * Token wiring (library path, slot, PIN, key label) is deployment
 * configuration and is intentionally out of scope here: those values are
 * operator-owned secrets, not library inputs to hardcode.
 */
function signWithToken(
    string $pdfPath,
    HsmSignerInterface $hsm,
): string {
    // The engine asks the signer only for: the certificate (to embed in
    // the CMS) and a signature over the bytes it computes. It never asks
    // for, and the contract never exposes, the private key.
    $certificateDer = $hsm->getCertificateDer();
    $chainDer       = $hsm->getCertificateChainDer();

    // Pseudocode for the engine's own assembly step: build the signature
    // dictionary + CMS SignedData, then hand the signed-attributes bytes
    // to $hsm->sign(...) and place the returned octets in /Contents.
    return nextpdf_sign_pdf(
        pdfPath: $pdfPath,
        signer: $hsm,
        certificateDer: $certificateDer,
        chainDer: $chainDer,
    );
}

Duas notas honestas sobre este formato. A vinculação PKCS#11 em processo é uma extensão PHP separada que as compilações padrão do PHP não incluem. Uma implantação de hardware a instala e verifica (ou usa a ponte de linha de comando OpenSSL) como parte da plataforma, não como uma providência tardia. E o algoritmo solicitado ao dispositivo deve ser um que a chave consiga de fato executar. O motor recusa cedo quando o algoritmo configurado não tem mapeamento para o provedor escolhido, em vez de falhar no fundo de uma chamada ao token.

Equívoco comum

“Usar um HSM significa que a assinatura é validada por FIPS.”

Não. Confundir os dois é a armadilha. Um HSM é o lugar onde a chave vive e a operação ocorre. A validação FIPS 140-3 / ISO/IEC 19790 é uma propriedade que o dispositivo (ou uma configuração específica de módulo) pode ter, estabelecida por um programa de validação — não algo que uma biblioteca chamadora confere nem algo que o NextPDF afirma em nome de um dispositivo. O NextPDF é compatível com a assinatura por meio de um dispositivo PKCS#11, e seu caminho de assinatura foi testado com tokens representativos de cada categoria. Se uma dada implantação é validada no nível de módulo FIPS depende inteiramente do hardware, de seu certificado e de como ele é configurado e operado. Use a palavra precisa para o que você realmente tem.

Limites e fronteiras

Esta página descreve a costura e os padrões nos quais ela se apoia. Não é uma garantia de implantação, e vale a pena declarar essa linha com clareza:

Responsabilidade do motor. Construir o campo de assinatura, reservar espaço, computar o intervalo de bytes, montar o SignedData CMS, chamar o provedor de assinatura e escrever uma assinatura estruturalmente correta conforme a Spec: ISO 32000-2, §12.8 . O caminho de hardware do NextPDF está em conformidade com a interface de assinatura PKCS#11 para esse fim.
Responsabilidade do dispositivo e do operador. A resistência à violação do hardware, seu status de validação FIPS 140-3 / ISO/IEC 19790, a geração e custódia de chaves, a política de PIN, a configuração de slots, o firmware e a segurança física. Nada disso é algo que o motor certifica.
Testado com não é certificado. O fato de o NextPDF ter um caminho verificado contra categorias representativas de tokens — formatos de cartão inteligente, USB, rede e KMS em nuvem alcançados pelo mesmo contrato PKCS#11 — é uma declaração de compatibilidade. Não é uma certificação, uma contagem de módulos validados nem uma afirmação sobre seu dispositivo específico. As categorias de hardware abaixo são formatos de integração por uma interface padrão. Trate-as como “onde a costura foi exercitada”, nunca como uma garantia para um modelo que você mesmo não testou.
A assinatura pós-quântica é experimental. Quando o motor expõe a assinatura pós-quântica por meio de um token, ela é opcional, restrita e validada contra mocks, e não contra firmware de HSM pós-quântico. Os catálogos de suítes criptográficas PAdES e AdES ainda não reconhecem essas suítes para arquivamento de longo prazo. Não a trate como pronta para produção.

HSM-backed signing via PKCS#11 — edition availability
Edition	Availability
Core	Não nesta edição. O Core fornece o motor de assinatura e a costura de provedor de assinatura, com um provedor local de chave em software.
Pro	O gerenciamento de chaves em nuvem — assinatura por meio de chaves KMS gerenciadas — é um recurso Pro descrito apenas no nível de comportamento.
Enterprise	Disponível. A assinatura com token de hardware por meio da interface PKCS#11 (e uma ponte de linha de comando OpenSSL para implantações engine/provider) é um recurso Enterprise. A disponibilidade é uma declaração de recurso, não uma certificação de qualquer dispositivo ou implantação.

Formatos de integração por uma interface

Estes são formatos contra os quais a costura PKCS#11 foi exercitada. A coluna mostra “como a integração se parece”, não “uma lista de dispositivos validados, certificados ou contados”.

Formato de integração	Como é alcançado	Limite da chave	A garantia é uma propriedade de
Token de cartão inteligente / PIV	PKCS#11 módulo; PIN por uso comum	No cartão; não extraível	O cartão e seu operador
HSM USB	PKCS#11 módulo	No dispositivo; não extraível	O dispositivo e seu operador
HSM de rede / appliance	PKCS#11 módulo para um dispositivo de rede	No appliance; não extraível	O appliance, sua configuração, o operador
Cloud KMS	Provedor de chave gerenciada (Pro)	No serviço em nuvem; nunca é retornada	O provedor de nuvem e suas atestações
Ponte de provedor OpenSSL	PKCS#11 via uma ponte OpenSSL	No token; não extraível	O token e seu operador

Mini-FAQ

A chave chega a entrar no processo PHP? Não. Para uma chave PKCS#11 não extraível, o valor privado não pode ser revelado em texto claro fora do token. O NextPDF assina por meio da operação do token e só vê os bytes a assinar e a assinatura retornada.

Uma assinatura respaldada por HSM é diferente dentro do PDF? Não. A estrutura de assinatura é o mesmo SignedData CMS na mesma entrada Contents sobre o mesmo intervalo de bytes. O HSM muda onde a assinatura ocorre, não o formato em disco.

Posso reivindicar conformidade com FIPS porque usei um HSM por meio do NextPDF? Apenas com cautela. O NextPDF não afirma nada sobre o status FIPS de um dispositivo. Qualquer afirmação desse tipo deve vir da própria validação do dispositivo e de como ele é implantado, não do fato de o NextPDF tê-lo chamado.

E se a vinculação PKCS#11 em processo estiver indisponível? O motor reporta que a assinatura por hardware está indisponível, em vez de silenciosamente recorrer a uma chave em software. Existe um caminho de ponte de linha de comando OpenSSL para implantações em que a vinculação em processo não consegue carregar um token.

Documentos relacionados

Assinaturas qualificadas, explicadas — por que uma chave de hardware é necessária, mas não suficiente, e quais papéis o NextPDF não desempenha.
Como as assinaturas ficam em um PDF — o mecanismo de intervalo de bytes e dicionário de assinatura no qual o resultado do HSM é escrito.
Operando o NextPDF em produção — a superfície operacional que uma implantação de assinatura por hardware assume.

Glossário

HSM (módulo de segurança de hardware) — um dispositivo reforçado que guarda chaves e realiza operações criptográficas para que o material da chave nunca o deixe.
PKCS#11 — o padrão OASIS Cryptographic Token Interface (historicamente “Cryptoki”); a interface C que o NextPDF usa para conversar com tokens de hardware.
Chave não extraível — um objeto de chave PKCS#11 cujo valor privado não pode ser revelado em texto claro fora do token (CKA_SENSITIVE verdadeiro ou CKA_EXTRACTABLE falso).
A costura — o limite de provedor de assinatura no NextPDF: bytes opacos entram, octetos de assinatura saem. O conhecimento de PDF e CMS fica acima dela; a chave fica atrás dela.
CMS SignedData — a estrutura Cryptographic Message Syntax (RFC 5652) que carrega a assinatura e os certificados dentro do PDF.
FIPS 140-3 / ISO/IEC 19790 — padrões de segurança de módulo criptográfico que definem quatro níveis qualitativos; uma propriedade de um dispositivo e de sua validação, não de uma biblioteca chamadora.