Contrato de provedor de KMS

Resumo

HsmSignerInterface é o contrato público que um terceiro implementa para fornecer custódia de chaves ao NextPDF. O provedor mantém a custódia da chave privada. O motor constrói a estrutura Cryptographic Message Syntax (CMS).

Instalação

composer require nextpdf/core:^3

Visão geral conceitual

NextPDF separa a montagem da assinatura da custódia de chaves. O motor prepara o intervalo de bytes e monta a estrutura CMS SignedData. Ele não detém a chave privada. Em vez disso, delega a custódia de chaves a um back-end de assinatura por meio de um contrato público.

Você implementa um de três contratos públicos:

• SignerInterface. O contrato base. Ele retorna um SignatureResult para os dados fornecidos, aplica um carimbo de tempo e informa o suporte à validação de longo prazo. Use este contrato quando a lógica de assinatura for executada no processo.
• HsmSignerInterface. O contrato de custódia de chaves. A implementação deve realizar a assinatura dentro do limite de hardware. A chave privada não deve sair desse limite. Um provedor de sistema de gerenciamento de chaves implementa este contrato.
• DeferredSignerInterface. Uma extensão de SignerInterface para back-ends assíncronos. O chamador envia os dados, recebe um identificador de tarefa e recupera o resultado mais tarde.

Esta página especifica o contrato público. Ela não descreve nenhuma implementação interna do NextPDF Pro ou do NextPDF Enterprise. Uma edição paga pode fornecer uma implementação suportada deste contrato. Você depende do contrato, não da implementação.

Requisito de custódia de chaves

O contrato exige que a chave privada nunca saia do limite seguro. A prática consolidada de gerenciamento de chaves dá suporte a esse requisito. O National Institute of Standards and Technology (NIST) SP 800-57 Part 1 Revision 5 trata o gerenciamento de chaves como a gestão do ciclo de vida para geração, armazenamento, distribuição, uso e destruição seguros. O Public-Key Cryptography Standards #11 (PKCS#11) v3.1 torna esse limite aplicável. Quando um objeto de chave privada define CKA_SENSITIVE como true ou CKA_EXTRACTABLE como false, o token não deve revelar o valor da chave em texto puro fora do token.

A sua implementação é responsável por cumprir esse requisito. O motor não pode impô-lo por você. Se o método sign() conseguir ler os bytes brutos da chave na memória do processo, o contrato perde sua propriedade de segurança.

Superfície da API

NextPDF\Contracts\HsmSignerInterface (estável, desde 1.0.0):

Método	Retorna	Propósito
sign(string $data, string $algorithm)	string	Assinar dados dentro do limite de hardware. Retorna os bytes brutos da assinatura. Lança RuntimeException em caso de falha.
getCertificateDer()	string	Retornar o certificado X.509 do signatário no formato Distinguished Encoding Rules (DER).
getCertificateChainDer()	array<string>	Retornar os certificados intermediários, do emissor até a raiz, excluindo o certificado do signatário.
getPublicKeyAlgorithm()	string	Retornar o identificador do algoritmo de chave pública.

NextPDF\Contracts\SignerInterface (estável, desde 1.0.0):

Método	Retorna	Propósito
sign(string $data)	SignatureResult	Retornar o CMS SignedData codificado em DER.
timestamp(string $signatureValue)	string	Retornar um token de carimbo de tempo Request for Comments (RFC) 3161 codificado em DER.
supportsLtv()	bool	Informar se os dados de validação de longo prazo (LTV) podem ser incorporados.

NextPDF\Contracts\DeferredSignerInterface (experimental, desde 3.0.0) estende SignerInterface com submitForSigning(), retrieveSignature() e isComplete() para back-ends assíncronos.

Os níveis de assinatura produzidos pelo motor seguem os perfis PDF Advanced Electronic Signatures (PAdES). O European Telecommunications Standards Institute (ETSI) EN 319 142-2 define perfis PAdES estendidos que se baseiam nos blocos de construção da EN 319 142-1. O motor mapeia os níveis B-B, B-T, B-LT e B-LTA para esses blocos de construção. O seu signatário fornece a operação criptográfica e o material de certificado de que o motor precisa.

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

Este provedor mínimo no estilo PKCS#11 delega a assinatura ao token. O PHP nunca lê o valor da chave.

<?php

declare(strict_types=1);

use NextPDF\Contracts\HsmSignerInterface;

final class TokenSigner implements HsmSignerInterface
{
    public function __construct(private readonly TokenSession $session) {}

    public function sign(string $data, string $algorithm = 'sha256WithRSAEncryption'): string
    {
        // The token computes the signature. The key stays inside the token.
        return $this->session->c_sign($data, $algorithm);
    }

    public function getCertificateDer(): string
    {
        return $this->session->readCertificate();
    }

    /** @return array<string> */
    public function getCertificateChainDer(): array
    {
        return $this->session->readChain();
    }

    public function getPublicKeyAlgorithm(): string
    {
        return 'rsaEncryption';
    }
}

Exemplo de código — Produção

Um provedor de produção valida as entradas, falha de forma fechada diante de um erro do token e nunca registra material de chave ou de assinatura.

<?php

declare(strict_types=1);

use NextPDF\Contracts\HsmSignerInterface;
use Psr\Log\LoggerInterface;
use RuntimeException;

final class KmsSigner implements HsmSignerInterface
{
    public function __construct(
        private readonly RemoteKmsClient $kms,
        private readonly string $keyId,
        private readonly LoggerInterface $logger,
    ) {}

    public function sign(string $data, string $algorithm = 'sha256WithRSAEncryption'): string
    {
        if ($data === '') {
            throw new RuntimeException('Refusing to sign empty data');
        }

        try {
            // The KMS performs the operation. The key never reaches this process.
            return $this->kms->sign($this->keyId, $data, $algorithm);
        } catch (\Throwable $error) {
            // Fail closed. Do not log key material or signature bytes.
            $this->logger->error('kms.sign.failed', ['key' => $this->keyId]);

            throw new RuntimeException('KMS signing failed', previous: $error);
        }
    }

    public function getCertificateDer(): string
    {
        return $this->kms->certificate($this->keyId);
    }

    /** @return array<string> */
    public function getCertificateChainDer(): array
    {
        return $this->kms->chain($this->keyId);
    }

    public function getPublicKeyAlgorithm(): string
    {
        return $this->kms->algorithm($this->keyId);
    }
}

Casos extremos e armadilhas

• Formato dos bytes da assinatura. Retorne os bytes brutos da assinatura. Para Rivest-Shamir-Adleman (RSA), os bytes são DER. Para Elliptic Curve Digital Signature Algorithm (ECDSA), os bytes são o valor bruto r seguido pelo valor s.
• Ordem da cadeia. getCertificateChainDer() exclui o certificado do signatário. Ordene os intermediários do emissor até a raiz.
• Identificadores de algoritmo. sign() usa identificadores no estilo OpenSSL. getPublicKeyAlgorithm() retorna o nome do algoritmo X.509.
• Falha de forma fechada. Lance RuntimeException em qualquer erro do token ou do KMS. Não retorne uma assinatura parcial ou vazia.
• Destruição da chave. Quando uma chave atinge o fim do seu criptoperíodo, destrua-a de acordo com o procedimento de gerenciamento de chaves. O NIST SP 800-57 Part 1 Revision 5 §8.2.1.2 afirma que uma chave deve ser destruída assim que não for mais necessária. A própria destruição segue o §8.3.4.

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

O contrato transfere apenas os dados a serem assinados e o material de certificado. Ele não transfere o conteúdo do documento nem dados pessoais para o back-end de assinatura. Mantenha o intervalo de bytes no mínimo necessário. Não coloque dados pessoais nos campos de motivo ou localização da assinatura. Esses campos permanecem observáveis no arquivo assinado.

Telemetria segura e limpeza de logs

Nunca registre os dados passados para sign(), os bytes de assinatura retornados, o identificador da chave de forma recuperável nem qualquer componente privado do certificado. Registre apenas o resultado da operação e uma referência não reversível. O hook SignatureAppliedEvent é a âncora de auditoria suportada. Consulte Gatilhos de ação.

Modelo de ameaças

Ativo	Ameaça	Mitigação
Chave privada	Saída para a memória do processo	O contrato exige assinatura dentro do limite; PKCS#11 CKA_SENSITIVE / CKA_EXTRACTABLE impõem a não extração
Oráculo de assinatura	Solicitações de assinatura ilimitadas	A implementação limita a taxa e autentica os chamadores
Cadeia de certificados	Substituição	A implementação retorna uma cadeia que se constrói até uma raiz confiável
Bytes da assinatura	Divulgação por meio de logs	Caminho de erro de forma fechada; nenhum material de assinatura na telemetria
Chave além do criptoperíodo	Uso continuado	Destruição da chave conforme NIST SP 800-57 Part 1 Revision 5 §8.2.1.2

Conformidade

Os níveis de assinatura estão em conformidade com os perfis PAdES. A ETSI EN 319 142-2 §5.1 define perfis PAdES estendidos sobre os blocos de construção da EN 319 142-1. O motor monta esses blocos de construção a partir do material que o seu signatário fornece. O gerenciamento de chaves está alinhado ao ciclo de vida do NIST SP 800-57 Part 1 Revision 5, incluindo o requisito de destruição do §8.2.1.2. A custódia de chaves em hardware está alinhada aos atributos de chave não extraível do PKCS#11 v3.1. As citações estão registradas no front matter da página.

Controle de exportação e governança de revisão

Esta página cobre a custódia de chaves PKCS#11 e de módulo de segurança de hardware (HSM); portanto, o seu front matter define export_control_class: legal-review-required. De acordo com a política de revisão de documentação (plano §17 gate 6), qualquer página com modo de segurança, caminho ou conteúdo que corresponda a PAdES, FIPS, HSM ou PKCS#11 exige aprovação da equipe do GitHub @nextpdf-labs/crypto-reviewers antes de poder ser publicada. Essa aprovação do CODEOWNERS é um gate de merge obrigatório: a página permanece com publish: false até que tanto a revisão legal de controle de exportação quanto a revisão de @nextpdf-labs/crypto-reviewers sejam concluídas.

Contexto comercial

NextPDF Enterprise fornece uma implementação suportada deste contrato com custódia por sistema de gerenciamento de chaves, montagem de cadeia de certificados e integração de auditoria. Você pode implementar HsmSignerInterface por conta própria no Core ou consumir a implementação do Enterprise por meio do mesmo contrato público, sem alterações de código.

Veja também

• Visão geral da criação de extensões
• Regras de estabilidade da SPI
• Gatilhos de ação e ouvintes de eventos

Contratos e módulos relacionados

• Referência dos contratos de assinatura — SignerInterface, HsmSignerInterface, DeferredSignerInterface e o provedor de carimbo de tempo.
• Referência do contrato de política de segurança — superfície irmã de Service Provider Interface (SPI) sensível à segurança.
• Regras de estabilidade da SPI — a promessa de interface por trás dos contratos de assinatura stable.
• Gatilhos de ação e ouvintes de eventos — SignatureAppliedEvent, a âncora de auditoria suportada.
• Visão geral da criação de extensões — toda a superfície pública da SPI.

O glossário define sistema de gerenciamento de chaves, criptoperíodo e HSM; consulte o glossário publicado para cada definição canônica.