Signature Cloud KMS (AWS KMS, Azure Key Vault, GCP KMS)

En bref

NextPDF Pro signe un PDF avec une clé conservée dans un service cloud de gestion de clés (KMS). Les fournisseurs pris en charge sont Amazon Web Services (AWS) KMS, Microsoft Azure Key Vault et Google Cloud Platform (GCP) Cloud KMS. Chaque fournisseur implémente un seul contrat de signature, si bien que ton application dépend du contrat, et non d’une classe de fournisseur. Seule l’empreinte des attributs signés est envoyée au fournisseur ; le document ne quitte jamais ton hôte pour l’opération de signature. Cette page se place au niveau du comportement : elle énonce ce que chaque fournisseur envoie et reçoit, comment les versions de clé sont résolues, et où la garde des clés cesse d’être la responsabilité de NextPDF.

Le contrat étend le contrat de signataire matériel-et-cloud du Core, si bien qu’une stratégie cloud-KMS s’enfiche dans le même chemin de signature que celui qu’utilise le signataire du Core.

Les prérequis sont énoncés dans le front matter et repris sous Prérequis.

Édition et licence

Les stratégies de signature cloud-KMS sont livrées dans le paquet nextpdf/pro et sont restreintes par l’indicateur de fonctionnalité de licence pro. NextPDF Core livre un signataire CMS logiciel ; NextPDF Enterprise ajoute la garde matérielle des clés via PKCS#11. La signature cloud-KMS est une capacité Pro et est également accessible dans Enterprise, puisque Enterprise dépend de Pro. Un déploiement sans droit Pro actif ne charge pas ces classes de stratégie ; le contrat de signature du Core continue de fonctionner sans changement. Comparer les éditions.

Ce que fait cette capacité

Chaque signataire cloud-KMS implémente un seul contrat de fournisseur qui étend le contrat de signataire du Core. Le contrat ajoute trois choses : un identifiant de fournisseur stable pour la recherche au registre, une méthode de signature consciente de la version de clé, et l’auto-description des algorithmes qu’un fournisseur prend en charge afin que l’orchestrateur puisse choisir un fournisseur compatible avant de signer.

Le flux de signature garde le document sur ton hôte :

1. La session de signature Pro calcule l’empreinte du document et construit les attributs signés CMS.
2. La session hache les attributs signés et n’envoie que cette empreinte au fournisseur. Un service de signature externe qui accepte une empreinte de message fournie par l’appelant et renvoie la signature est le motif établi pour garder le document à l’intérieur de ta frontière, comme le décrit le cadre de référence EU Digital Signature Service (DSS).
3. Le fournisseur signe l’empreinte avec la version de clé qu’il résout et renvoie la signature brute.
4. La session assemble le CMS SignedData et l’incorpore dans le PDF.

Les fournisseurs sont implémentés sur de purs appels Hypertext Transfer Protocol (HTTP) PSR-18 — sans dépendance à un kit de développement logiciel (SDK) de fournisseur cloud. L’authentification est déléguée à ton application : tu fournis un jeton porteur (AWS, GCP) ou un jeton ou des identifiants de service-principal (Azure). Chaque fournisseur normalise sa sortie pour CMS : AWS et GCP renvoient des signatures Rivest–Shamir–Adleman (RSA) sous forme DER prêtes pour CMS ; une signature Elliptic Curve Digital Signature Algorithm (ECDSA) qu’un fournisseur renvoie sous la forme d’une paire d’entiers bruts (Azure) est convertie vers la forme encodée en DER, tandis que GCP renvoie l’ECDSA déjà encodée en DER. La courbe ECDSA et l’empreinte sont appariées de manière conventionnelle — P-256 avec SHA-256, P-384 avec SHA-384, P-521 avec SHA-512 — selon l’appariement recommandé dans le RFC 5480.

Un registre PSR-11 résout les fournisseurs par identifiant et prend en charge les fabriques paresseuses. Les clients Enterprise auto-hébergés enregistrent un pilote HSM ou KMS propriétaire en implémentant le contrat de fournisseur et en le liant dans le registre — sans forker NextPDF Pro.

Sémantique de version de clé propre à chaque fournisseur

Les fournisseurs exposent des primitives de « version active » différentes, si bien que le comportement par défaut de version de clé diffère :

• AWS KMS — une version de clé null utilise l’alias de clé, qu’AWS résout vers la version de clé courante côté fournisseur.
• Azure Key Vault — une version de clé null utilise l’URL de clé sans version, qu’Azure résout vers la dernière version activée. Un remplacement explicite doit être un identifiant hexadécimal de 32 caractères ; toute autre valeur est rejetée pour empêcher l’injection de segment d’URL.
• GCP Cloud KMS — le point de terminaison de signature asymétrique n’opère que sur une version de clé cryptographique spécifique ; il n’existe pas de « version active » côté serveur. Tu dois épingler une version dans la configuration ou en passer une explicitement. Si aucune des deux n’est définie, le signataire lève une erreur de gestion de clés plutôt que de deviner.

Documente le mode utilisé par ton déploiement afin que le comportement soit déterministe.

Prérequis

1. Installe NextPDF Core et le paquet Pro, et détiens une licence Pro active.
2. Approvisionne une clé de signature dans le fournisseur que tu as choisi et note ses identifiants (alias de clé ou Amazon Resource Name pour AWS ; vault et nom de clé pour Azure ; projet, emplacement, trousseau de clés, clé cryptographique et version pour GCP).
3. Fournis un client HTTP PSR-18 et des fabriques de requête et de flux PSR-17.
4. Obtiens l’identifiant du fournisseur dans ton application : un jeton porteur pour AWS ou GCP, ou un jeton pré-obtenu ou des identifiants de service-principal pour Azure. L’acquisition du jeton relève de la responsabilité de ton application ; fournis les secrets depuis ton gestionnaire de secrets, jamais depuis les sources.

Configuration

Chaque fournisseur possède un objet de configuration immuable construit à partir de tes identifiants et de tes identifiants d’accès. Préoccupations de configuration courantes :

• Identifiant de fournisseur — aws-kms, azure-keyvault ou gcp-kms, utilisé comme clé de recherche au registre.
• Algorithme — sélectionné par appel à partir du nom d’algorithme que ta session de signature transmet ; le fournisseur rejette un algorithme qu’il ne prend pas en charge.
• Version de clé — épinglée dans la configuration ou passée par appel, avec la sémantique propre à chaque fournisseur décrite ci-dessus.
• Identifiant d’accès — un jeton porteur ou des identifiants de service-principal que ton application fournit depuis son gestionnaire de secrets.

Étape par étape

1. Construis la configuration du fournisseur à partir de tes identifiants et d’un identifiant d’accès lu depuis ton gestionnaire de secrets.
2. Construis le signataire du fournisseur avec la configuration, le certificat du signataire sous forme DER, la chaîne, le client PSR-18 et les fabriques PSR-17.
3. Enregistre éventuellement le fournisseur dans le registre PSR-11 sous son identifiant afin que l’orchestrateur le résolve par son nom.
4. Lance la session de signature Pro : elle calcule l’empreinte, construit les attributs signés et appelle le fournisseur avec uniquement l’empreinte.
5. Capture l’échec le plus spécifique — gestion de clés, algorithme non pris en charge ou échec de signature — journalise un message structurel sans secrets, et 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;
        }
    }
}

Vérification

1. Confirme que le fournisseur s’auto-décrit comme prenant en charge l’algorithme que tu comptes utiliser avant de signer, afin qu’un algorithme non pris en charge soit capturé à la sélection plutôt qu’à l’appel du fournisseur.
2. Confirme que seule l’empreinte est transmise : les octets du document ne doivent pas apparaître dans le corps de la requête au fournisseur. La requête transporte une empreinte encodée en base64, pas le fichier.
3. Pour ECDSA, confirme que la signature incorporée est encodée en DER — le signataire convertit pour toi une signature en paire d’entiers bruts.
4. Ouvre le PDF signé dans un validateur configuré avec tes ancres de confiance et confirme que la signature est rapportée comme cryptographiquement intacte. Une signature produite n’est pas une signature vérifiée ; la décision de confiance appartient au vérificateur.
5. Confirme qu’aucun jeton, identifiant ou matériel de clé n’apparaît dans les journaux de ton application.

Sécurité et conformité

• La clé reste dans le fournisseur. Une stratégie cloud-KMS est un point d’intégration, pas un magasin de clés. NextPDF Pro ne détient pas la clé privée pour une stratégie KMS.
• Seule l’empreinte franchit la frontière. La session envoie l’empreinte des attributs signés au fournisseur, pas le document — le motif d’entrée par empreinte de message décrit dans le cadre de référence EU DSS.
• La plage d’octets est calculée par le moteur. Elle n’est jamais acceptée depuis l’appelant.
• Échec verrouillé. Un échec de fournisseur, de réseau, de version de clé ou d’algorithme non pris en charge lève une exception typée. La session ne produit pas silencieusement un document non signé et ne substitue jamais un algorithme plus faible.
• Les identifiants sont des secrets. Les jetons et les identifiants de service-principal proviennent de ton gestionnaire de secrets et sont exclus des journaux.

Cette page concerne la signature cryptographique. Chaque source normative est paraphrasée ; aucun texte normatif n’est reproduit. ### Frontière de garde des clés

La protection des clés dépend de la manipulation des clés, du KMS configuré et du déploiement. NextPDF Pro fournit l’intégration KMS, pas le magasin de clés. NextPDF Pro n’est compatible FIPS que lorsqu’il est configuré avec un KMS ou un HSM validé FIPS ; il n’est pas lui-même un module cryptographique validé FIPS et ne formule aucune revendication de certification FIPS.

Gestion des échecs

• Version de clé inconnue ou désactivée. Le fournisseur mappe une réponse de version introuvable ou désactivée vers une exception de gestion de clés qui nomme le fournisseur et la clé.
• GCP sans version épinglée. Le signataire GCP lève une erreur de gestion de clés lorsque ni la configuration ni l’appel ne fournissent de version, parce que le point de terminaison de signature asymétrique n’opère que sur une version spécifique.
• Algorithme non pris en charge. Demander un algorithme que le fournisseur ne prend pas en charge lève une exception d’algorithme non pris en charge avant tout appel réseau.
• Échec de transport. Une erreur du client PSR-18 est mappée vers une exception d’échec de signature ; la session ne produit pas de résultat partiel.
• Identifiant manquant. Un signataire sans jeton et sans identifiants de service-principal lève une erreur typée plutôt que d’appeler le fournisseur sans authentification.

Voir aussi

• Security — NextPDF Pro — masquage, détection de PII et l’ensemble de la surface de signature Pro.
• HSM signing — NextPDF Enterprise — garde matérielle des clés PKCS#11.
• Signature — NextPDF Enterprise — le producteur d’archivage à long terme PAdES B-LT et B-LTA.
• Security / Signing (Core) — le signataire CMS du Core et le contrat de stratégie de signature.
• KMS · CMS · ECDSA · HSM — termes du glossaire.