Pro edizione

Firma con KMS cloud (AWS KMS, Azure Key Vault, GCP KMS)

In breve

NextPDF Pro firma un PDF con una chiave custodita in un servizio cloud di gestione delle chiavi (KMS). I provider supportati sono Amazon Web Services (AWS) KMS, Microsoft Azure Key Vault e Google Cloud Platform (GCP) Cloud KMS. Ogni provider implementa un unico contratto di firma, così l’applicazione dipende dal contratto e non da una classe di provider. Al provider viene inviato soltanto il digest degli attributi firmati; il documento non lascia mai il proprio host per l’operazione di firma. Questa pagina è a livello di comportamento: dichiara che cosa ciascun provider invia e riceve, come si risolvono le versioni della chiave e dove la custodia delle chiavi smette di essere responsabilità di NextPDF.

Il contratto estende il contratto del signer hardware-e-cloud di Core, così una strategia con KMS cloud si innesta sullo stesso percorso di firma utilizzato dal signer di Core.

I prerequisiti sono dichiarati nel front matter e ripetuti in Prerequisiti.

Edizione e licenze

Le strategie di firma con KMS cloud sono incluse nel pacchetto nextpdf/pro e sono soggette a gate dal flag di funzionalità della licenza pro. NextPDF Core include un signer CMS software; NextPDF Enterprise aggiunge la custodia delle chiavi su hardware tramite PKCS#11. La firma con KMS cloud è una capability di Pro ed è raggiungibile anche in Enterprise, poiché Enterprise dipende da Pro. Un deployment privo di un entitlement Pro attivo non carica queste classi di strategia; il contratto di firma di Core continua a funzionare invariato. Confronta le edizioni.

Cosa fa questa capability

Ogni signer con KMS cloud implementa un unico contratto di provider che estende il contratto del signer di Core. Il contratto aggiunge tre elementi: un identificatore di provider stabile per la ricerca nel registro, un metodo di firma consapevole della versione della chiave e l’autodescrizione degli algoritmi supportati da un provider, così che l’orchestratore possa scegliere un provider compatibile prima di firmare.

Il flusso di firma mantiene il documento sul proprio host:

La sessione di firma di Pro calcola il digest del documento e costruisce gli attributi firmati CMS.
La sessione esegue l’hash degli attributi firmati e invia al provider soltanto quel digest. Un servizio di firma esterno che accetta un message-digest fornito dal chiamante e restituisce la firma è il modello consolidato per mantenere il documento all’interno del proprio confine, come descritto nel framework di riferimento EU Digital Signature Service (DSS).
Il provider firma il digest con la versione della chiave che risolve e restituisce la firma grezza.
La sessione assembla il CMS SignedData e lo incorpora nel PDF.

I provider sono implementati con chiamate Hypertext Transfer Protocol (HTTP) PSR-18 pure — senza alcuna dipendenza dal software development kit (SDK) del vendor cloud. L’autenticazione è delegata all’applicazione: si fornisce un bearer token (AWS, GCP) oppure un token o una credenziale service-principal (Azure). Ogni provider normalizza il proprio output per il CMS: AWS e GCP restituiscono firme Rivest–Shamir–Adleman (RSA) in forma DER pronte per il CMS; una firma Elliptic Curve Digital Signature Algorithm (ECDSA) che un provider restituisce come coppia di interi grezza (Azure) viene convertita nella forma codificata in DER, mentre GCP restituisce l’ECDSA già codificata in DER. La curva ECDSA e il digest sono accoppiati per convenzione — P-256 con SHA-256, P-384 con SHA-384, P-521 con SHA-512 — secondo l’accoppiamento raccomandato in RFC 5480.

Un registro PSR-11 risolve i provider per identificatore e supporta factory lazy. I clienti Enterprise self-host registrano un driver HSM o KMS proprietario implementando il contratto di provider e collegandolo nel registro — senza eseguire un fork di NextPDF Pro.

Semantica della versione della chiave per ciascun provider

I provider espongono primitive di «versione attiva» differenti, quindi il comportamento predefinito della versione della chiave varia:

AWS KMS — una versione della chiave null usa l’alias della chiave, che AWS risolve nella versione corrente della chiave lato provider.
Azure Key Vault — una versione della chiave null usa l’URL della chiave senza versione, che Azure risolve nell’ultima versione abilitata. Un override esplicito deve essere un identificatore esadecimale di 32 caratteri; qualsiasi altro valore viene rifiutato per prevenire l’injection di segmenti URL.
GCP Cloud KMS — l’endpoint di firma asimmetrica opera esclusivamente su una specifica versione della chiave crittografica; non esiste una «versione attiva» lato server. Occorre fissare (pin) una versione nella configurazione oppure passarla esplicitamente. In assenza di entrambe, il signer solleva un errore di gestione delle chiavi anziché tirare a indovinare.

Documentare quale modalità usa il proprio deployment, così che il comportamento sia deterministico.

Prerequisiti

Installare NextPDF Core e il pacchetto Pro e disporre di una licenza Pro attiva.
Effettuare il provisioning di una chiave di firma nel provider scelto e annotarne gli identificatori (alias della chiave o Amazon Resource Name per AWS; vault e nome della chiave per Azure; project, location, key ring, crypto key e versione per GCP).
Fornire un client HTTP PSR-18 e le factory PSR-17 di request e stream.
Ottenere la credenziale del provider nella propria applicazione: un bearer token per AWS o GCP, oppure un token preacquisito o credenziali service-principal per Azure. L’acquisizione del token è responsabilità dell’applicazione; fornire i segreti dal proprio secret manager, mai dal codice sorgente.

Configurazione

Ogni provider dispone di un oggetto di configurazione immutabile costruito dai propri identificatori e dalle proprie credenziali. Aspetti comuni di configurazione:

Identificatore del provider — aws-kms, azure-keyvault o gcp-kms, usato come chiave di ricerca nel registro.
Algoritmo — selezionato per ogni chiamata a partire dal nome di algoritmo che la sessione di firma passa; il provider rifiuta un algoritmo che non supporta.
Versione della chiave — fissata nella configurazione o passata per chiamata, con la semantica per ciascun provider descritta sopra.
Credenziale — un bearer token o credenziali service-principal che l’applicazione fornisce dal proprio secret manager.

Passo dopo passo

Costruire la configurazione del provider a partire dai propri identificatori e da una credenziale letta dal proprio secret manager.
Costruire il signer del provider con la configurazione, il certificato del firmatario in forma DER, la catena, il client PSR-18 e le factory PSR-17.
Facoltativamente, registrare il provider nel registro PSR-11 sotto il suo identificatore, così che l’orchestratore lo risolva per nome.
Eseguire la sessione di firma di Pro: calcola il digest, costruisce gli attributi firmati e chiama il provider con il solo digest.
Catturare l’errore più specifico — gestione delle chiavi, algoritmo non supportato o firma fallita — registrare un messaggio strutturale privo di segreti e rilanciare l’eccezione.

<?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;
}

<?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

Confermare che il provider autodescriva l’algoritmo che si intende usare prima di firmare, così che un algoritmo non supportato venga intercettato in fase di selezione anziché alla chiamata del provider.
Confermare che venga trasmesso soltanto il digest: i byte del documento non devono comparire nel corpo della richiesta al provider. La richiesta trasporta un digest codificato in base64, non il file.
Per ECDSA, confermare che la firma incorporata sia codificata in DER — il signer converte per conto dell’utente una firma a coppia di interi grezza.
Aprire il PDF firmato in un validatore configurato con i propri trust anchor e confermare che la firma sia riportata come crittograficamente integra. Una firma prodotta non è una firma verificata; la decisione di fiducia spetta al verificatore.
Confermare che nessun token, credenziale o materiale di chiave compaia nei log dell’applicazione.

Sicurezza e compliance

La chiave resta nel provider. Una strategia con KMS cloud è un punto di integrazione, non un archivio di chiavi. NextPDF Pro non detiene la chiave privata per una strategia KMS.
Solo il digest attraversa il confine. La sessione invia al provider il digest degli attributi firmati, non il documento — il modello del message-digest in input descritto nel framework di riferimento EU DSS.
L’intervallo di byte è calcolato dal motore. Non viene mai accettato dal chiamante.
Fail-closed. Un errore di provider, di rete, di versione della chiave o di algoritmo non supportato solleva un’eccezione tipizzata. La sessione non produce silenziosamente un documento non firmato e non sostituisce mai un algoritmo più debole.
Le credenziali sono segreti. I token e le credenziali service-principal provengono dal proprio secret manager e sono esclusi dai log.

Questa pagina riguarda la firma crittografica. Ogni fonte normativa è parafrasata; nessun testo normativo è riprodotto. ### Confine della custodia delle chiavi

La protezione della chiave dipende dalla gestione della chiave, dal KMS configurato e dal deployment. NextPDF Pro fornisce l’integrazione con il KMS, non l’archivio di chiavi. NextPDF Pro è compatibile con FIPS solo quando è configurato contro un KMS o un HSM convalidato FIPS; non è esso stesso un modulo crittografico convalidato FIPS e non avanza alcuna pretesa di certificazione FIPS.

Gestione degli errori

Versione della chiave sconosciuta o disabilitata. Il provider mappa una risposta di versione non trovata o disabilitata su un’eccezione di gestione delle chiavi che nomina il provider e la chiave.
GCP senza una versione fissata. Il signer GCP solleva un errore di gestione delle chiavi quando né la configurazione né la chiamata forniscono una versione, perché l’endpoint di firma asimmetrica opera esclusivamente su una versione specifica.
Algoritmo non supportato. Richiedere un algoritmo che il provider non supporta solleva un’eccezione di algoritmo non supportato prima di qualsiasi chiamata di rete.
Errore di trasporto. Un errore del client PSR-18 viene mappato su un’eccezione di firma fallita; la sessione non produce un risultato parziale.
Credenziale mancante. Un signer privo di token e di credenziali service-principal solleva un errore tipizzato anziché chiamare il provider in modo non autenticato.

Vedere anche

Security — NextPDF Pro — mascheramento, rilevamento dei dati sensibili e l’intera superficie di firma di Pro.
HSM signing — NextPDF Enterprise — custodia delle chiavi su hardware PKCS#11.
Signature — NextPDF Enterprise — il produttore a lungo termine PAdES B-LT e B-LTA.
Security / Signing (Core) — il signer CMS di Core e il contratto di strategia di firma.
KMS · CMS · ECDSA · HSM — voci di glossario.