Zum Inhalt springen
NextPDF
getnextpdf.com

Pro Edition

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

Auf einen Blick

Abschnitt betitelt „Auf einen Blick“

NextPDF Pro signiert ein PDF mit einem Schlüssel, der in einem Cloud-Key-Management-Service (KMS) gehalten wird. Die unterstützten Provider sind Amazon Web Services (AWS) KMS, Microsoft Azure Key Vault und Google Cloud Platform (GCP) Cloud KMS. Jeder Provider implementiert einen einzigen Signier-Contract, sodass Ihre Anwendung vom Contract abhängt und nicht von einer Provider-Klasse. Nur der Digest der signierten Attribute wird an den Provider gesendet; das Dokument verlässt Ihren Host für den Signiervorgang niemals. Diese Seite beschreibt das Verhalten: Sie benennt, was jeder Provider sendet und empfängt, wie Schlüsselversionen aufgelöst werden und wo die Schlüsselverwahrung aufhört, in der Verantwortung von NextPDF zu liegen.

Der Contract erweitert den Hardware-und-Cloud-Signier-Contract von Core, sodass sich eine Cloud-KMS-Strategie in denselben Signierpfad einklinkt, den der Core-Signierer verwendet.

Die Voraussetzungen sind im Front Matter aufgeführt und unter Voraussetzungen wiederholt.

Edition und Lizenzierung

Abschnitt betitelt „Edition und Lizenzierung“

Cloud-KMS-Signierstrategien werden im Paket nextpdf/pro ausgeliefert und durch das Lizenz-Feature-Flag pro freigeschaltet. NextPDF Core liefert einen Software-CMS-Signierer; NextPDF Enterprise ergänzt die Schlüsselverwahrung in Hardware über PKCS#11. Cloud-KMS-Signierung ist eine Pro-Fähigkeit und ist auch in Enterprise erreichbar, da Enterprise von Pro abhängt. Ein Deployment ohne aktive Pro-Berechtigung lädt diese Strategieklassen nicht; der Core-Signier-Contract funktioniert unverändert weiter. Editionen vergleichen.

Was diese Fähigkeit leistet

Abschnitt betitelt „Was diese Fähigkeit leistet“

Jeder Cloud-KMS-Signierer implementiert einen einzigen Provider-Contract, der den Core-Signier-Contract erweitert. Der Contract ergänzt drei Dinge: einen stabilen Provider-Identifikator für die Registry-Suche, eine schlüsselversionsbewusste Signiermethode und eine Selbstbeschreibung der von einem Provider unterstützten Algorithmen, damit der Orchestrator vor dem Signieren einen kompatiblen Provider auswählen kann.

Der Signierablauf hält das Dokument auf Ihrem Host:

  1. Die Pro-Signiersitzung berechnet den Dokument-Digest und erstellt die signierten CMS-Attribute.
  2. Die Sitzung hasht die signierten Attribute und sendet nur diesen Digest an den Provider. Ein externer Signierdienst, der einen vom Aufrufer bereitgestellten Message-Digest akzeptiert und die Signatur zurückgibt, ist das etablierte Muster, um das Dokument innerhalb Ihrer Grenze zu halten, wie es im EU Digital Signature Service (DSS) Reference Framework beschrieben ist.
  3. Der Provider signiert den Digest mit der von ihm aufgelösten Schlüsselversion und gibt die Rohsignatur zurück.
  4. Die Sitzung setzt die CMS-SignedData zusammen und bettet sie in das PDF ein.

Die Provider sind über reine PSR-18-Hypertext-Transfer-Protocol-(HTTP-)Aufrufe implementiert — keine Abhängigkeit von einem Cloud-Anbieter-Software-Development-Kit (SDK). Die Authentifizierung wird an Ihre Anwendung delegiert: Sie liefern ein Bearer-Token (AWS, GCP) oder ein Token bzw. ein Service-Principal-Credential (Azure). Jeder Provider normalisiert seine Ausgabe für CMS: AWS und GCP geben Rivest–Shamir–Adleman-(RSA-)Signaturen in DER-Form zurück, bereit für CMS; eine Elliptic-Curve-Digital-Signature-Algorithm-(ECDSA-)Signatur, die ein Provider als rohes Integer-Paar zurückgibt (Azure), wird in die DER-codierte Form umgewandelt, während GCP ECDSA bereits DER-codiert zurückgibt. Kurve und Digest für ECDSA werden konventionell gepaart — P-256 mit SHA-256, P-384 mit SHA-384, P-521 mit SHA-512 — gemäß der empfohlenen Paarung in RFC 5480.

Eine PSR-11-Registry löst Provider anhand ihres Identifikators auf und unterstützt Lazy Factories. Enterprise-Self-Host-Kunden registrieren einen proprietären HSM- oder KMS-Treiber, indem sie den Provider-Contract implementieren und ihn in der Registry binden — ohne NextPDF Pro zu forken.

Providerspezifische Schlüsselversions-Semantik

Abschnitt betitelt „Providerspezifische Schlüsselversions-Semantik“

Die Provider stellen unterschiedliche „Active-Version“-Primitive bereit, sodass sich das Standardverhalten der Schlüsselversion unterscheidet:

  • AWS KMS — eine null-Schlüsselversion verwendet den Schlüssel-Alias, den AWS auf der Provider-Seite zur aktuellen Schlüsselversion auflöst.
  • Azure Key Vault — eine null-Schlüsselversion verwendet die unversionierte Schlüssel-URL, die Azure zur neuesten aktivierten Version auflöst. Eine explizite Übersteuerung muss ein 32-stelliger hexadezimaler Identifikator sein; jeder andere Wert wird abgelehnt, um eine Injektion in das URL-Segment zu verhindern.
  • GCP Cloud KMS — der Asymmetric-Sign-Endpunkt arbeitet ausschließlich mit einer bestimmten Crypto-Key-Version; es gibt keine serverseitige „Active Version“. Sie müssen eine Version in der Konfiguration fixieren oder explizit übergeben. Ist weder das eine noch das andere gesetzt, löst der Signierer einen Schlüsselverwaltungsfehler aus, statt zu raten.

Dokumentieren Sie, welchen Modus Ihr Deployment verwendet, damit das Verhalten deterministisch ist.

Voraussetzungen

Abschnitt betitelt „Voraussetzungen“
  1. Installieren Sie NextPDF Core und das Pro-Paket und halten Sie eine aktive Pro-Lizenz.
  2. Stellen Sie einen Signierschlüssel bei Ihrem gewählten Provider bereit und notieren Sie seine Identifikatoren (Schlüssel-Alias oder Amazon Resource Name für AWS; Vault- und Schlüsselname für Azure; Projekt, Standort, Key Ring, Crypto Key und Version für GCP).
  3. Stellen Sie einen PSR-18-HTTP-Client sowie PSR-17-Request- und Stream-Factories bereit.
  4. Beschaffen Sie das Provider-Credential in Ihrer Anwendung: ein Bearer-Token für AWS oder GCP oder ein vorab beschafftes Token bzw. Service-Principal-Credentials für Azure. Die Token-Beschaffung liegt in der Verantwortung Ihrer Anwendung; liefern Sie Geheimnisse aus Ihrem Secret Manager, niemals aus dem Quellcode.

Konfiguration

Abschnitt betitelt „Konfiguration“

Jeder Provider hat ein unveränderliches Konfigurationsobjekt, das aus Ihren Identifikatoren und Credentials erstellt wird. Gemeinsame Konfigurationsaspekte:

  • Provider-Identifikator — aws-kms, azure-keyvault oder gcp-kms, verwendet als Suchschlüssel der Registry.
  • Algorithmus — pro Aufruf aus dem Algorithmusnamen ausgewählt, den Ihre Signiersitzung übergibt; der Provider lehnt einen Algorithmus ab, den er nicht unterstützt.
  • Schlüsselversion — in der Konfiguration fixiert oder pro Aufruf übergeben, mit der oben beschriebenen providerspezifischen Semantik.
  • Credential — ein Bearer-Token oder Service-Principal-Credentials, die Ihre Anwendung aus ihrem Secret Manager bereitstellt.

Schritt für Schritt

Abschnitt betitelt „Schritt für Schritt“
  1. Erstellen Sie die Provider-Konfiguration aus Ihren Identifikatoren und einem aus Ihrem Secret Manager gelesenen Credential.
  2. Konstruieren Sie den Provider-Signierer mit der Konfiguration, dem Signierzertifikat in DER-Form, der Kette, dem PSR-18-Client und den PSR-17-Factories.
  3. Registrieren Sie den Provider optional in der PSR-11-Registry unter seinem Identifikator, damit der Orchestrator ihn anhand des Namens auflöst.
  4. Führen Sie die Pro-Signiersitzung aus: Sie berechnet den Digest, erstellt die signierten Attribute und ruft den Provider nur mit dem Digest auf.
  5. Fangen Sie den spezifischsten Fehler ab — Schlüsselverwaltung, nicht unterstützter Algorithmus oder fehlgeschlagene Signatur —, protokollieren Sie eine strukturelle Meldung ohne Geheimnisse und werfen Sie ihn erneut.
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;
        }
    }
}

Verifizierung

Abschnitt betitelt „Verifizierung“
  1. Stellen Sie sicher, dass der Provider den Algorithmus, den Sie verwenden möchten, vor dem Signieren selbst beschreibt, damit ein nicht unterstützter Algorithmus bei der Auswahl statt beim Provider-Aufruf abgefangen wird.
  2. Stellen Sie sicher, dass nur der Digest übertragen wird: Die Dokumentbytes dürfen nicht im Anfragerumpf des Providers erscheinen. Die Anfrage trägt einen base64-codierten Digest, nicht die Datei.
  3. Bestätigen Sie für ECDSA, dass die eingebettete Signatur DER-codiert ist — der Signierer wandelt eine Signatur aus einem rohen Integer-Paar für Sie um.
  4. Öffnen Sie das signierte PDF in einem Validierer, der mit Ihren Vertrauensankern konfiguriert ist, und bestätigen Sie, dass die Signatur als kryptografisch intakt gemeldet wird. Eine erzeugte Signatur ist keine verifizierte Signatur; die Vertrauensentscheidung liegt beim Prüfer.
  5. Stellen Sie sicher, dass kein Token, kein Credential und kein Schlüsselmaterial in Ihren Anwendungslogs erscheint.

Sicherheit und Compliance

Abschnitt betitelt „Sicherheit und Compliance“
  • Der Schlüssel bleibt beim Provider. Eine Cloud-KMS-Strategie ist ein Integrationspunkt, kein Schlüsselspeicher. NextPDF Pro hält den privaten Schlüssel für eine KMS-Strategie nicht.
  • Nur der Digest überschreitet die Grenze. Die Sitzung sendet den Digest der signierten Attribute an den Provider, nicht das Dokument — das im EU DSS Reference Framework beschriebene Message-Digest-Input-Muster.
  • Der Byte Range wird von der Engine berechnet. Er wird niemals vom Aufrufer entgegengenommen.
  • Fail-closed. Ein Provider-, Netzwerk-, Schlüsselversions- oder nicht-unterstützter-Algorithmus-Fehler löst eine typisierte Ausnahme aus. Die Sitzung erzeugt nicht stillschweigend ein unsigniertes Dokument und ersetzt niemals einen schwächeren Algorithmus.
  • Credentials sind Geheimnisse. Tokens und Service-Principal-Credentials stammen aus Ihrem Secret Manager und sind von Logs ausgeschlossen.

Diese Seite betrifft kryptografisches Signieren. Jede normative Quelle ist paraphrasiert; kein normativer Text wird wiedergegeben. ### Schlüsselverwahrungsgrenze

Der Schlüsselschutz hängt von der Schlüsselbehandlung, dem konfigurierten KMS und dem Deployment ab. NextPDF Pro stellt die KMS-Integration bereit, nicht den Schlüsselspeicher. NextPDF Pro ist nur dann FIPS-kompatibel, wenn es gegen ein FIPS-validiertes KMS oder HSM konfiguriert ist; es ist selbst kein FIPS-validiertes kryptografisches Modul und erhebt keinen FIPS-Zertifizierungsanspruch.

Fehlerbehandlung

Abschnitt betitelt „Fehlerbehandlung“
  • Unbekannte oder deaktivierte Schlüsselversion. Der Provider bildet eine Not-Found- oder Disabled-Version-Antwort auf eine Schlüsselverwaltungsausnahme ab, die den Provider und den Schlüssel benennt.
  • GCP ohne fixierte Version. Der GCP-Signierer löst einen Schlüsselverwaltungsfehler aus, wenn weder die Konfiguration noch der Aufruf eine Version liefert, weil der Asymmetric-Sign-Endpunkt ausschließlich mit einer bestimmten Version arbeitet.
  • Nicht unterstützter Algorithmus. Die Anforderung eines Algorithmus, den der Provider nicht unterstützt, löst vor jedem Netzwerkaufruf eine Unsupported-Algorithm-Ausnahme aus.
  • Transportfehler. Ein PSR-18-Client-Fehler wird auf eine Signature-Failed-Ausnahme abgebildet; die Sitzung erzeugt kein Teilergebnis.
  • Fehlendes Credential. Ein Signierer ohne Token und ohne Service-Principal-Credentials löst einen typisierten Fehler aus, statt den Provider unauthentifiziert aufzurufen.

Siehe auch

Abschnitt betitelt „Siehe auch“