KMS-Provider-Vertrag

Auf einen Blick

HsmSignerInterface ist der öffentliche Vertrag, den Drittanbieter implementieren, um NextPDF die Schlüsselverwahrung bereitzustellen. Ihr Code verwahrt den privaten Schlüssel. Die Engine baut die CMS-Struktur auf.

Installation

composer require nextpdf/core:^3

Konzeptioneller Überblick

NextPDF trennt den Aufbau der Signatur von der Schlüsselverwahrung. Die Engine bereitet den Byte Range vor und baut die CMS-Struktur SignedData zusammen. Sie hält den privaten Schlüssel nicht; die Schlüsselverwahrung wird über einen öffentlichen Vertrag an ein Signatur-Back-End delegiert.

Sie implementieren einen von drei öffentlichen Verträgen:

SignerInterface. Der Basisvertrag. Er liefert für gegebene Daten ein SignatureResult, fügt einen Zeitstempel hinzu und meldet die Unterstützung für die Langzeitvalidierung. Verwenden Sie diesen Vertrag, wenn die Signaturlogik im Prozess läuft.
HsmSignerInterface. Der Vertrag für die Schlüsselverwahrung. Die Implementierung muss den Signaturvorgang innerhalb der Hardwaregrenze ausführen. Der private Schlüssel darf diese Grenze nicht verlassen. Ein Key-Management-System-Provider implementiert diesen Vertrag.
DeferredSignerInterface. Eine Erweiterung von SignerInterface für asynchrone Back-Ends. Die aufrufende Komponente reicht die Daten ein, erhält eine Job-Kennung und ruft das Ergebnis später ab.

Diese Seite spezifiziert den öffentlichen Vertrag. Sie beschreibt keine interne Implementierung von NextPDF Pro oder NextPDF Enterprise. Eine kostenpflichtige Edition kann eine unterstützte Implementierung dieses Vertrags bereitstellen. Sie bauen auf dem Vertrag auf, nicht auf der Implementierung.

Anforderung an die Schlüsselverwahrung

Der Vertrag verlangt, dass der private Schlüssel die sichere Grenze niemals verlässt. Diese Anforderung entspricht gängiger Praxis. NIST SP 800-57 Part 1 Revision 5 definiert Schlüsselverwaltung als Handhabung eines Schlüssels über seinen gesamten Lebenszyklus. Dieser Lebenszyklus umfasst sichere Erzeugung, Speicherung, Verteilung, Nutzung und Vernichtung. PKCS#11 v3.1 macht die Grenze technisch durchsetzbar. Wenn ein Objekt für einen privaten Schlüssel CKA_SENSITIVE auf true oder CKA_EXTRACTABLE auf false setzt, darf das Token den Schlüsselwert nicht im Klartext außerhalb des Tokens preisgeben.

Ihre Implementierung ist dafür verantwortlich, diese Anforderung einzuhalten. Die Engine kann sie nicht für Sie durchsetzen. Wenn Ihre Methode sign() rohe Schlüssel-Bytes in den Prozessspeicher lesen kann, geht die Sicherheitseigenschaft des Vertrags verloren.

API-Oberfläche

NextPDF\Contracts\HsmSignerInterface (stabil, seit 1.0.0):

Methode	Rückgabe	Zweck
`sign(string $data, string $algorithm)`	`string`	Signiert Daten innerhalb der Hardwaregrenze, gibt rohe Signatur-Bytes zurück und wirft bei einem Fehler eine `RuntimeException`.
`getCertificateDer()`	`string`	Gibt das X.509-Zertifikat des Signierers in DER-Form zurück.
`getCertificateChainDer()`	`array<string>`	Gibt die Zwischenzertifikate vom Aussteller bis zur Wurzel zurück, ohne das Signiererzertifikat.
`getPublicKeyAlgorithm()`	`string`	Gibt die Kennung des Public-Key-Algorithmus zurück.

NextPDF\Contracts\SignerInterface (stabil, seit 1.0.0):

Methode	Rückgabe	Zweck
`sign(string $data)`	`SignatureResult`	Gibt das DER-codierte CMS `SignedData` zurück.
`timestamp(string $signatureValue)`	`string`	Gibt ein DER-codiertes RFC 3161-Zeitstempel-Token zurück.
`supportsLtv()`	`bool`	Gibt an, ob Daten für die Langzeitvalidierung eingebettet werden können.

NextPDF\Contracts\DeferredSignerInterface (experimentell, seit 3.0.0) erweitert SignerInterface um submitForSigning(), retrieveSignature() und isComplete() für asynchrone Back-Ends.

Die von der Engine erzeugten Signaturstufen folgen den PAdES-Profilen. ETSI EN 319 142-2 definiert erweiterte PAdES-Profile, die auf den Basis-Bausteinen in EN 319 142-1 aufbauen. Die Engine bildet die Stufen B-B, B-T, B-LT und B-LTA auf diese Bausteine ab. Ihr Signierer liefert den kryptografischen Vorgang und das Zertifikatsmaterial, das die Engine braucht.

Codebeispiel — Schnellstart

Dies ist ein minimaler Provider im PKCS#11-Stil. Der Signieraufruf delegiert die Operation an das Token. Der Schlüsselwert wird niemals in PHP eingelesen.

<?php

declare(strict_types=1);

use NextPDF\Contracts\HsmSignerInterface;

final class TokenSigner implements HsmSignerInterface
{
    public function __construct(private readonly TokenSession $session) {}

    public function sign(string $data, string $algorithm = 'sha256WithRSAEncryption'): string
    {
        // The token computes the signature. The key stays inside the token.
        return $this->session->c_sign($data, $algorithm);
    }

    public function getCertificateDer(): string
    {
        return $this->session->readCertificate();
    }

    /** @return array<string> */
    public function getCertificateChainDer(): array
    {
        return $this->session->readChain();
    }

    public function getPublicKeyAlgorithm(): string
    {
        return 'rsaEncryption';
    }
}

Codebeispiel — Produktion

Ein Produktions-Provider validiert Eingaben, fällt bei einem Token-Fehler nach dem Fail-closed-Prinzip aus und protokolliert niemals Schlüssel- oder Signaturmaterial.

<?php

declare(strict_types=1);

use NextPDF\Contracts\HsmSignerInterface;
use Psr\Log\LoggerInterface;
use RuntimeException;

final class KmsSigner implements HsmSignerInterface
{
    public function __construct(
        private readonly RemoteKmsClient $kms,
        private readonly string $keyId,
        private readonly LoggerInterface $logger,
    ) {}

    public function sign(string $data, string $algorithm = 'sha256WithRSAEncryption'): string
    {
        if ($data === '') {
            throw new RuntimeException('Refusing to sign empty data');
        }

        try {
            // The KMS performs the operation. The key never reaches this process.
            return $this->kms->sign($this->keyId, $data, $algorithm);
        } catch (\Throwable $error) {
            // Fail closed. Do not log key material or signature bytes.
            $this->logger->error('kms.sign.failed', ['key' => $this->keyId]);

            throw new RuntimeException('KMS signing failed', previous: $error);
        }
    }

    public function getCertificateDer(): string
    {
        return $this->kms->certificate($this->keyId);
    }

    /** @return array<string> */
    public function getCertificateChainDer(): array
    {
        return $this->kms->chain($this->keyId);
    }

    public function getPublicKeyAlgorithm(): string
    {
        return $this->kms->algorithm($this->keyId);
    }
}

Sonderfälle & Fallstricke

Format der Signatur-Bytes. Geben Sie rohe Signatur-Bytes zurück. Bei RSA sind die Bytes DER. Bei ECDSA sind die Bytes der rohe Wert r, gefolgt vom Wert s.
Reihenfolge der Kette. getCertificateChainDer() schließt das Signiererzertifikat aus. Ordnen Sie die Zwischenzertifikate vom Aussteller bis zur Wurzel.
Algorithmus-Kennungen. sign() verwendet Kennungen im OpenSSL-Stil. getPublicKeyAlgorithm() gibt den X.509-Algorithmusnamen zurück.
Fehler folgen dem Fail-closed-Prinzip. Werfen Sie bei jedem Token- oder KMS-Fehler eine RuntimeException. Geben Sie keine teilweise oder leere Signatur zurück.
Vernichtung von Schlüsseln. Wenn ein Schlüssel das Ende seiner Kryptoperiode erreicht, vernichten Sie ihn gemäß Ihrer Schlüsselverwaltungsprozedur. NIST SP 800-57 Part 1 Revision 5 §8.2.1.2 besagt, dass ein Schlüssel vernichtet werden sollte, sobald er nicht mehr benötigt wird. Die Vernichtung selbst folgt §8.3.4.

Datenresidenz und PII-Minderungsmaßnahmen

Der Vertrag überträgt nur die zu signierenden Daten und das Zertifikatsmaterial. Er überträgt keine Dokumentinhalte und keine personenbezogenen Daten an das Signatur-Back-End. Halten Sie den Byte Range minimal. Platzieren Sie keine personenbezogenen Daten in den Feldern für Signaturgrund oder -ort; diese Felder sind in der signierten Datei einsehbar.

Sichere Telemetrie und Log-Bereinigung

Protokollieren Sie niemals die an sign() übergebenen Daten, die zurückgegebenen Signatur-Bytes, die Schlüsselkennung in wiederherstellbarer Form oder eine private Zertifikatskomponente. Protokollieren Sie nur das Ergebnis des Vorgangs und eine nicht umkehrbare Referenz. Der Hook SignatureAppliedEvent ist der unterstützte Audit-Anker. Siehe Action-Trigger.

Bedrohungsmodell

Asset	Bedrohung	Minderung
Privater Schlüssel	Abfluss in den Prozessspeicher	Der Vertrag verlangt das Signieren innerhalb der Hardwaregrenze; PKCS#11 `CKA_SENSITIVE` / `CKA_EXTRACTABLE` erzwingen die Nicht-Extrahierbarkeit
Signaturorakel	Unbegrenzte Signieranfragen	Die Implementierung begrenzt die Rate und authentifiziert Aufrufer
Zertifikatskette	Substitution	Die Implementierung gibt eine Kette zurück, die bis zu einer vertrauenswürdigen Wurzel führt
Signatur-Bytes	Offenlegung über Logs	Fail-closed-Fehlerpfad; kein Signaturmaterial in der Telemetrie
Schlüssel über die Kryptoperiode hinaus	Fortgesetzte Nutzung	Schlüsselvernichtung gemäß NIST SP 800-57 Part 1 Revision 5 §8.2.1.2

Konformität

Die Signaturstufen entsprechen den PAdES-Profilen. ETSI EN 319 142-2 §5.1 definiert erweiterte PAdES-Profile auf den Basis-Bausteinen von EN 319 142-1. Die Engine setzt diese Bausteine aus dem Material zusammen, das Ihr Signierer liefert. Die Schlüsselverwaltung richtet sich nach dem Lebenszyklus aus NIST SP 800-57 Part 1 Revision 5, einschließlich der Vernichtungsanforderung aus §8.2.1.2. Die Hardware-Schlüsselverwahrung richtet sich nach den Attributen für nicht extrahierbare Schlüssel aus PKCS#11 v3.1. Die Zitate sind im Front Matter der Seite vermerkt.

Exportkontrolle und Review-Governance

Diese Seite behandelt die Schlüsselverwahrung über PKCS#11 und Hardware-Sicherheitsmodule; deshalb setzt ihr Front Matter export_control_class: legal-review-required. Gemäß der Review-Richtlinie für die Dokumentation (Plan §17 Gate 6) erfordert jede Seite mit einem Sicherheitsmodus oder einem Pfad oder Inhalt, der auf PAdES, FIPS, HSM oder PKCS#11 passt, die Freigabe durch das GitHub-Team @nextpdf-labs/crypto-reviewers, bevor sie veröffentlicht werden kann. Diese CODEOWNERS-Freigabe ist ein hartes Merge-Gate: Die Seite bleibt publish: false, bis sowohl das rechtliche Exportkontroll-Review als auch das Review durch @nextpdf-labs/crypto-reviewers abgeschlossen sind.

Kommerzieller Kontext

NextPDF Enterprise bietet eine unterstützte Implementierung dieses Vertrags mit Schlüsselverwahrung über ein Key-Management-System, Zusammenbau der Zertifikatskette und Audit-Integration. Sie implementieren HsmSignerInterface in Core selbst oder nutzen die Enterprise-Implementierung über denselben öffentlichen Vertrag ohne Codeänderung.