Pro editie

Cloud-KMS-ondertekening (AWS KMS, Azure Key Vault, GCP KMS)

In het kort

NextPDF Pro ondertekent een PDF met een sleutel die in een cloud-key-management-service (KMS) wordt bewaard. De ondersteunde providers zijn Amazon Web Services (AWS) KMS, Microsoft Azure Key Vault en Google Cloud Platform (GCP) Cloud KMS. Elke provider implementeert één ondertekeningscontract, zodat je applicatie afhangt van het contract en niet van een providerklasse. Alleen de digest van de ondertekende attributen wordt naar de provider gestuurd; het document verlaat je host nooit voor de ondertekeningsbewerking. Deze pagina is op gedragsniveau: ze beschrijft wat elke provider verstuurt en ontvangt, hoe sleutelversies worden geresolved en waar sleutelbewaring ophoudt de verantwoordelijkheid van NextPDF te zijn.

Het contract breidt het Core-contract voor hardware- en cloud-ondertekening uit, zodat een cloud-KMS-strategie inplugt op hetzelfde ondertekeningspad dat de Core-ondertekenaar gebruikt.

De vereisten staan in de front matter en worden herhaald onder Vereisten.

Editie en licenties

Cloud-KMS-ondertekeningsstrategieën worden geleverd in het pakket nextpdf/pro en worden bewaakt door de pro-licentie-feature-flag. NextPDF Core levert een software-CMS-ondertekenaar; NextPDF Enterprise voegt sleutelbewaring in hardware toe via PKCS#11. Cloud-KMS-ondertekening is een Pro-capaciteit en is ook bereikbaar in Enterprise, omdat Enterprise afhangt van Pro. Een implementatie zonder actieve Pro-entitlement laadt deze strategieklassen niet; het Core-ondertekeningscontract blijft ongewijzigd werken. Vergelijk edities.

Wat deze capaciteit doet

Elke cloud-KMS-ondertekenaar implementeert één providercontract dat het Core-ondertekenaarscontract uitbreidt. Het contract voegt drie dingen toe: een stabiele provider-identifier voor registry-lookup, een sleutelversie-bewuste ondertekeningsmethode en zelfbeschrijving van de algoritmen die een provider ondersteunt, zodat de orchestrator vóór het ondertekenen een compatibele provider kan kiezen.

De ondertekeningsflow houdt het document op je host:

De Pro-ondertekeningssessie berekent de documentdigest en bouwt de ondertekende CMS-attributen op.
De sessie hasht de ondertekende attributen en stuurt alleen die digest naar de provider. Een externe ondertekeningsservice die een door de caller aangeleverde message-digest accepteert en de handtekening retourneert, is het gevestigde patroon om het document binnen je grens te houden, zoals beschreven in het referentiekader van de EU Digital Signature Service (DSS).
De provider ondertekent de digest met de sleutelversie die deze resolveert en retourneert de ruwe handtekening.
De sessie stelt de CMS-SignedData samen en bedt deze in de PDF in.

De providers zijn geïmplementeerd over pure PSR-18 Hypertext Transfer Protocol (HTTP)-aanroepen — geen afhankelijkheid van een software development kit (SDK) van een cloudleverancier. Authenticatie wordt gedelegeerd aan je applicatie: je levert een bearer token (AWS, GCP) of een token of service-principal-credential (Azure). Elke provider normaliseert zijn uitvoer voor CMS: AWS en GCP retourneren Rivest–Shamir–Adleman (RSA)-handtekeningen in DER-vorm, klaar voor CMS; een Elliptic Curve Digital Signature Algorithm (ECDSA)-handtekening die een provider als een ruw integerpaar retourneert (Azure) wordt geconverteerd naar de DER-gecodeerde vorm, terwijl GCP ECDSA al DER-gecodeerd retourneert. De ECDSA-curve en de digest worden conventioneel gepaard — P-256 met SHA-256, P-384 met SHA-384, P-521 met SHA-512 — volgens de aanbevolen paring in RFC 5480.

Een PSR-11-registry resolveert providers op identifier en ondersteunt lazy factories. Enterprise-self-hostklanten registreren een eigen HSM- of KMS-driver door het providercontract te implementeren en het in de registry te binden — zonder NextPDF Pro te forken.

Per-provider sleutelversie-semantiek

De providers stellen verschillende “active version”-primitieven beschikbaar, dus het standaard sleutelversiegedrag verschilt:

AWS KMS — een null sleutelversie gebruikt de sleutel-alias, die AWS aan de providerkant resolveert naar de huidige sleutelversie.
Azure Key Vault — een null sleutelversie gebruikt de niet-geversioneerde sleutel-URL, die Azure resolveert naar de laatste ingeschakelde versie. Een expliciete override moet een hexadecimale identifier van 32 tekens zijn; elke andere waarde wordt afgewezen om URL-segmentinjectie te voorkomen.
GCP Cloud KMS — het asymmetric-sign-endpoint werkt alleen op een specifieke crypto-key-versie; er is geen “active version” aan de serverkant. Je moet een versie in de configuratie pinnen of er expliciet een doorgeven. Met geen van beide ingesteld werpt de ondertekenaar een sleutelbeheerfout in plaats van te gokken.

Documenteer welke modus je implementatie gebruikt, zodat het gedrag deterministisch is.

Vereisten

Installeer NextPDF Core en het Pro-pakket, en houd een actieve Pro-licentie.
Provision een ondertekeningssleutel in je gekozen provider en noteer de identifiers ervan (sleutel-alias of Amazon Resource Name voor AWS; vault en sleutelnaam voor Azure; project, locatie, key ring, crypto key en versie voor GCP).
Lever een PSR-18 HTTP-client en PSR-17 request- en stream-factories.
Verkrijg de provider-credential in je applicatie: een bearer token voor AWS of GCP, of een vooraf verkregen token of service-principal-credentials voor Azure. Het verkrijgen van tokens is de verantwoordelijkheid van je applicatie; lever geheimen vanuit je secret manager, nooit vanuit de broncode.

Configuratie

Elke provider heeft een onveranderlijk configuratieobject dat is opgebouwd uit je identifiers en credentials. Gemeenschappelijke configuratieaspecten:

Provider-identifier — aws-kms, azure-keyvault of gcp-kms, gebruikt als de registry-lookupsleutel.
Algoritme — per aanroep geselecteerd op basis van de algoritmenaam die je ondertekeningssessie doorgeeft; de provider wijst een algoritme af dat deze niet ondersteunt.
Sleutelversie — gepind in de configuratie of per aanroep doorgegeven, met de hierboven beschreven per-provider semantiek.
Credential — een bearer token of service-principal-credentials die je applicatie aanlevert vanuit haar secret manager.

Stap voor stap

Bouw de providerconfiguratie op uit je identifiers en een credential die uit je secret manager wordt gelezen.
Construeer de provider-ondertekenaar met de configuratie, het ondertekenaarscertificaat in DER-vorm, de keten, de PSR-18-client en de PSR-17-factories.
Registreer de provider optioneel in de PSR-11-registry onder zijn identifier, zodat de orchestrator deze op naam resolveert.
Voer de Pro-ondertekeningssessie uit: deze berekent de digest, bouwt ondertekende attributen op en roept de provider aan met alleen de digest.
Vang de meest specifieke fout op — sleutelbeheer, niet-ondersteund-algoritme of handtekening-mislukt — log een structureel bericht zonder geheimen, en gooi opnieuw.

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

Verificatie

Bevestig dat de provider het algoritme dat je wilt gebruiken zelf beschrijft vóór het ondertekenen, zodat een niet-ondersteund algoritme bij de selectie wordt opgevangen en niet bij de provideraanroep.
Bevestig dat alleen de digest wordt verzonden: de documentbytes mogen niet in de body van het providerverzoek verschijnen. Het verzoek draagt een base64-gecodeerde digest, niet het bestand.
Bevestig voor ECDSA dat de ingebedde handtekening DER-gecodeerd is — de ondertekenaar converteert een ruw integerpaar voor je.
Open de ondertekende PDF in een validator die is geconfigureerd met je trust anchors en bevestig dat de handtekening als cryptografisch intact wordt gerapporteerd. Een geproduceerde handtekening is geen geverifieerde handtekening; de vertrouwensbeslissing is die van de verifier.
Bevestig dat er geen token, credential of sleutelmateriaal in je applicatielogs verschijnt.

Beveiliging en compliance

De sleutel blijft in de provider. Een cloud-KMS-strategie is een integratiepunt, geen sleutelopslag. NextPDF Pro houdt de privésleutel voor een KMS-strategie niet vast.
Alleen de digest passeert de grens. De sessie stuurt de digest van de ondertekende attributen naar de provider, niet het document — het message-digest-input-patroon dat in het referentiekader van de EU DSS wordt beschreven.
De byte range wordt door de engine berekend. Deze wordt nooit van de caller geaccepteerd.
Fail-closed. Een provider-, netwerk-, sleutelversie- of niet-ondersteund-algoritmefout werpt een getypeerde uitzondering. De sessie produceert niet stilzwijgend een niet-ondertekend document en vervangt nooit een zwakker algoritme.
Credentials zijn geheimen. Tokens en service-principal-credentials komen uit je secret manager en worden uitgesloten van logs.

Deze pagina betreft cryptografisch ondertekenen. Elke normatieve bron is geparafraseerd; er wordt geen normatieve tekst gereproduceerd. ### Grens voor sleutelbewaring

Sleutelbescherming hangt af van de sleutelverwerking, de geconfigureerde KMS en de implementatie. NextPDF Pro levert KMS-integratie, niet de sleutelopslag. NextPDF Pro is alleen FIPS-compatibel wanneer het wordt geconfigureerd tegen een FIPS-gevalideerde KMS of HSM; het is zelf geen FIPS-gevalideerde cryptografische module en maakt geen FIPS-certificeringsclaim.

Foutafhandeling

Onbekende of uitgeschakelde sleutelversie. De provider mapt een not-found- of disabled-version-respons naar een sleutelbeheeruitzondering die de provider en de sleutel benoemt.
GCP zonder gepinde versie. De GCP-ondertekenaar werpt een sleutelbeheerfout wanneer noch de configuratie noch de aanroep een versie aanlevert, omdat het asymmetric-sign-endpoint alleen op een specifieke versie werkt.
Niet-ondersteund algoritme. Het aanvragen van een algoritme dat de provider niet ondersteunt, werpt een niet-ondersteund-algoritme-uitzondering vóór elke netwerkaanroep.
Transportfout. Een PSR-18-clientfout wordt gemapt naar een handtekening-mislukt-uitzondering; de sessie produceert geen gedeeltelijk resultaat.
Ontbrekende credential. Een ondertekenaar zonder token en zonder service-principal-credentials werpt een getypeerde fout in plaats van de provider niet-geauthenticeerd aan te roepen.

Zie ook

Security — NextPDF Pro — maskering, PII-detectie en het volledige Pro-ondertekeningsoppervlak.
HSM-ondertekening — NextPDF Enterprise — PKCS#11-sleutelbewaring in hardware.
Signature — NextPDF Enterprise — de PAdES B-LT- en B-LTA-langetermijnproducer.
Security / Signing (Core) — de Core-CMS-ondertekenaar en het ondertekeningsstrategiecontract.
KMS · CMS · ECDSA · HSM — woordenlijsttermen.