Assinatura com Cloud KMS (AWS KMS, Azure Key Vault, GCP KMS)

Visão geral

O NextPDF Pro assina um PDF com uma chave mantida em um serviço de gerenciamento de chaves (key-management service, KMS) na nuvem. Os provedores suportados são o Amazon Web Services (AWS) KMS, o Microsoft Azure Key Vault e o Google Cloud Platform (GCP) Cloud KMS. Cada provedor implementa um único contrato de assinatura, então a sua aplicação depende do contrato, e não de uma classe de provedor. Apenas o digest dos atributos assinados é enviado ao provedor; o documento nunca sai do seu host para a operação de assinatura. Esta página descreve o comportamento: ela afirma o que cada provedor envia e recebe, como as versões de chave são resolvidas e onde a custódia de chaves deixa de ser responsabilidade do NextPDF.

O contrato estende o contrato de signatário de hardware e nuvem do Core, então uma estratégia de Cloud KMS se conecta ao mesmo caminho de assinatura que o signatário do Core usa.

Os pré-requisitos estão indicados no front matter e repetidos em Pré-requisitos.

Edição e licenciamento

As estratégias de assinatura com Cloud KMS fazem parte do pacote nextpdf/pro e são restritas pelo sinalizador de recurso de licença pro. O NextPDF Core fornece um signatário CMS por software; o NextPDF Enterprise acrescenta custódia de chaves em hardware por meio de PKCS#11. A assinatura com Cloud KMS é um recurso do Pro e também é acessível no Enterprise, já que o Enterprise depende do Pro. Uma implantação sem um direito de uso Pro ativo não carrega essas classes de estratégia; o contrato de assinatura do Core continua funcionando sem alterações. Comparar edições.

O que este recurso faz

Cada signatário de Cloud KMS implementa um único contrato de provedor que estende o contrato de signatário do Core. O contrato acrescenta três coisas: um identificador de provedor estável para busca no registro, um método de assinatura que reconhece a versão da chave e a autodescrição dos algoritmos que um provedor suporta, para que o orquestrador possa escolher um provedor compatível antes de assinar.

O fluxo de assinatura mantém o documento no seu host:

1. A sessão de assinatura do Pro calcula o digest do documento e monta os atributos assinados CMS.
2. A sessão faz o hash dos atributos assinados e envia apenas esse digest ao provedor. Um serviço de assinatura externo que aceita um message-digest fornecido pelo chamador e retorna a assinatura é o padrão estabelecido para manter o documento dentro do seu limite, conforme descrito no framework de referência do Digital Signature Service (DSS) da UE.
3. O provedor assina o digest com a versão de chave que ele resolve e retorna a assinatura bruta.
4. A sessão monta o SignedData CMS e o incorpora no PDF.

Os provedores são implementados sobre chamadas Hypertext Transfer Protocol (HTTP) PSR-18 puras — sem dependência de software development kit (SDK) de fornecedor de nuvem. A autenticação é delegada à sua aplicação: você fornece um bearer token (AWS, GCP) ou um token ou credencial de service principal (Azure). Cada provedor normaliza sua saída para CMS: AWS e GCP retornam assinaturas Rivest–Shamir–Adleman (RSA) em forma DER prontas para CMS; uma assinatura Elliptic Curve Digital Signature Algorithm (ECDSA) que um provedor retorna como um par de inteiros brutos (Azure) é convertida para a forma codificada em DER, enquanto o GCP retorna ECDSA já codificada em DER. A curva ECDSA e o digest são pareados de forma convencional — P-256 com SHA-256, P-384 com SHA-384, P-521 com SHA-512 — conforme o pareamento recomendado na RFC 5480.

Um registro PSR-11 resolve provedores por identificador e oferece suporte a fábricas preguiçosas (lazy). Clientes self-host do Enterprise registram um driver de HSM ou KMS proprietário implementando o contrato de provedor e vinculando-o no registro — sem fazer fork do NextPDF Pro.

Semântica de versão de chave por provedor

Os provedores expõem primitivas de “versão ativa” diferentes, então o comportamento padrão de versão de chave difere:

• AWS KMS — uma versão de chave null usa o alias da chave, que a AWS resolve para a versão de chave atual no lado do provedor.
• Azure Key Vault — uma versão de chave null usa a URL de chave sem versão, que o Azure resolve para a versão mais recente habilitada. Uma substituição explícita deve ser um identificador hexadecimal de 32 caracteres; qualquer outro valor é rejeitado para evitar injeção de segmento de URL.
• GCP Cloud KMS — o endpoint de assinatura assimétrica opera somente em uma versão específica de chave criptográfica; não há “versão ativa” no lado do servidor. Você deve fixar uma versão na configuração ou passar uma explicitamente. Sem nenhuma das duas definidas, o signatário levanta um erro de gerenciamento de chaves em vez de adivinhar.

Documente qual modo a sua implantação usa para que o comportamento seja determinístico.

Pré-requisitos

1. Instale o NextPDF Core e o pacote Pro, e mantenha uma licença Pro ativa.
2. Provisione uma chave de assinatura no provedor escolhido e anote seus identificadores (alias da chave ou Amazon Resource Name para AWS; vault e nome da chave para Azure; projeto, localização, key ring, crypto key e versão para GCP).
3. Forneça um cliente HTTP PSR-18 e fábricas de requisição e stream PSR-17.
4. Obtenha a credencial do provedor na sua aplicação: um bearer token para AWS ou GCP, ou um token previamente obtido ou credenciais de service principal para Azure. A obtenção do token é responsabilidade da sua aplicação; forneça os segredos a partir do seu gerenciador de segredos, nunca a partir do código-fonte.

Configuração

Cada provedor tem um objeto de configuração imutável montado a partir dos seus identificadores e credenciais. Preocupações comuns de configuração:

• Identificador do provedor — aws-kms, azure-keyvault ou gcp-kms, usado como chave de busca no registro.
• Algoritmo — selecionado por chamada a partir do nome de algoritmo que a sua sessão de assinatura passa; o provedor rejeita um algoritmo que não suporta.
• Versão da chave — fixada na configuração ou passada por chamada, com a semântica por provedor descrita acima.
• Credencial — um bearer token ou credenciais de service principal que a sua aplicação fornece a partir do seu gerenciador de segredos.

Passo a passo

1. Monte a configuração do provedor a partir dos seus identificadores e de uma credencial lida do seu gerenciador de segredos.
2. Construa o signatário do provedor com a configuração, o certificado do signatário em forma DER, a cadeia, o cliente PSR-18 e as fábricas PSR-17.
3. Opcionalmente, registre o provedor no registro PSR-11 sob seu identificador, para que o orquestrador o resolva pelo nome.
4. Execute a sessão de assinatura do Pro: ela calcula o digest, monta os atributos assinados e chama o provedor apenas com o digest.
5. Capture a falha mais específica — gerenciamento de chaves, algoritmo não suportado ou falha de assinatura —, registre uma mensagem estrutural sem segredos e relance.

examples/pro/kms-provider-registry.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Pro\Security\Signing\Kms\KeyManagementProviderRegistry;
use NextPDF\Pro\Security\Signing\Kms\KmsSignerInterface;

/**
 * Register cloud-KMS providers behind one registry resolved by identifier.
 *
 * Each provider is supplied as a lazy factory so a provider is only
 * constructed when first resolved. The caller depends on the registry and
 * the provider contract, not on a concrete provider class.
 *
 * @param array<non-empty-string, callable(): KmsSignerInterface> $factories
 *        Provider factories keyed by provider identifier.
 *
 * @return KeyManagementProviderRegistry The populated registry.
 */
function buildKmsRegistry(array $factories): KeyManagementProviderRegistry
{
    $registry = new KeyManagementProviderRegistry();

    foreach ($factories as $providerId => $factory) {
        $registry->registerFactory($providerId, $factory);
    }

    return $registry;
}

examples/pro/kms-sign-guarded.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Pro\Security\Signing\Kms\KmsSignerInterface;
use NextPDF\Pro\Security\Exception\KeyManagementException;
use NextPDF\Pro\Security\Exception\SignatureFailedException;
use NextPDF\Pro\Security\Exception\UnsupportedAlgorithmException;
use Psr\Log\LoggerInterface;

final readonly class KmsSigningService
{
    public function __construct(
        private KmsSignerInterface $provider,
        private LoggerInterface $logger,
    ) {}

    /**
     * Sign a signed-attributes digest with a pinned key version.
     *
     * Only the digest is sent to the provider; the document stays on the
     * host. Each failure mode is caught as its most specific type so the
     * caller can distinguish a key-version problem from a transport failure.
     *
     * @param string      $digest     The signed-attributes digest to sign.
     * @param string      $algorithm  The OpenSSL-style algorithm name.
     * @param string|null $keyVersion The pinned key version, or null for the
     *                                 provider default (per-provider semantics).
     *
     * @throws KeyManagementException        When the key version is unknown or required and absent.
     * @throws UnsupportedAlgorithmException When the provider does not support the algorithm.
     * @throws SignatureFailedException      When the provider sign operation fails.
     *
     * @return string The raw signature bytes (DER for RSA and ECDSA per CMS rules).
     */
    public function sign(string $digest, string $algorithm, ?string $keyVersion): string
    {
        try {
            return $this->provider->signWithVersion($digest, $algorithm, $keyVersion);
        } catch (KeyManagementException | UnsupportedAlgorithmException | SignatureFailedException $e) {
            $this->logger->error('KMS signing failed', [
                'provider' => $this->provider->providerId(),
                'reason'   => $e->getMessage(),
            ]);

            throw $e;
        }
    }
}

Verificação

1. Confirme que o provedor autodescreve o algoritmo que você pretende usar antes de assinar, para que um algoritmo não suportado seja detectado na seleção, e não na chamada ao provedor.
2. Confirme que apenas o digest é transmitido: os bytes do documento não devem aparecer no corpo da requisição ao provedor. A requisição carrega um digest codificado em base64, não o arquivo.
3. Para ECDSA, confirme que a assinatura incorporada está codificada em DER — o signatário converte um par de inteiros brutos para você.
4. Abra o PDF assinado em um validador configurado com suas âncoras de confiança e confirme que a assinatura é relatada como criptograficamente íntegra. Uma assinatura produzida não é uma assinatura verificada; a decisão de confiança é do verificador.
5. Confirme que nenhum token, credencial ou material de chave aparece nos logs da sua aplicação.

Segurança e conformidade

• A chave permanece no provedor. Uma estratégia de Cloud KMS é um ponto de integração, não um repositório de chaves. O NextPDF Pro não mantém a chave privada de uma estratégia de KMS.
• Apenas o digest cruza o limite. A sessão envia o digest dos atributos assinados ao provedor, não o documento — o padrão de entrada por message-digest descrito no framework de referência do DSS da UE.
• O byte range é calculado pelo motor. Ele nunca é aceito do chamador.
• Fail-closed. Uma falha de provedor, de rede, de versão de chave ou de algoritmo não suportado levanta uma exceção tipada. A sessão não produz silenciosamente um documento não assinado e nunca substitui por um algoritmo mais fraco.
• Credenciais são segredos. Tokens e credenciais de service principal vêm do seu gerenciador de segredos e são excluídos dos logs.

Esta página trata de assinatura criptográfica. Toda fonte normativa é parafraseada; nenhum texto normativo é reproduzido. ### Limite de custódia de chaves

A proteção da chave depende do manuseio da chave, do KMS configurado e da implantação. O NextPDF Pro fornece a integração com o KMS, não o repositório de chaves. O NextPDF Pro é compatível com FIPS apenas quando configurado contra um KMS ou HSM validado por FIPS; ele próprio não é um módulo criptográfico validado por FIPS e não faz nenhuma declaração de certificação FIPS.

Tratamento de falhas

• Versão de chave desconhecida ou desabilitada. O provedor mapeia uma resposta de não encontrado ou de versão desabilitada para uma exceção de gerenciamento de chaves que nomeia o provedor e a chave.
• GCP sem uma versão fixada. O signatário do GCP levanta um erro de gerenciamento de chaves quando nem a configuração nem a chamada fornecem uma versão, porque o endpoint de assinatura assimétrica opera somente em uma versão específica.
• Algoritmo não suportado. Solicitar um algoritmo que o provedor não suporta levanta uma exceção de algoritmo não suportado antes de qualquer chamada de rede.
• Falha de transporte. Um erro de cliente PSR-18 é mapeado para uma exceção de falha de assinatura; a sessão não produz um resultado parcial.
• Credencial ausente. Um signatário sem token e sem credenciais de service principal levanta um erro tipado em vez de chamar o provedor sem autenticação.

Veja também

• Segurança — NextPDF Pro — mascaramento, detecção de PII e a superfície completa de assinatura do Pro.
• Assinatura com HSM — NextPDF Enterprise — custódia de chaves em hardware via PKCS#11.
• Assinatura — NextPDF Enterprise — o produtor de longo prazo PAdES B-LT e B-LTA.
• Segurança / Assinatura (Core) — o signatário CMS do Core e o contrato de estratégia de assinatura.
• KMS · CMS · ECDSA · HSM — termos do glossário.