KMS-providercontract

In een oogopslag

HsmSignerInterface is het openbare contract dat een derde partij implementeert om sleutelbeheer voor NextPDF te verzorgen. Uw provider houdt het beheer over de private sleutel. De engine bouwt de Cryptographic Message Syntax-structuur (CMS) op.

Installatie

composer require nextpdf/core:^3

Conceptueel overzicht

NextPDF scheidt het samenstellen van de handtekening van het sleutelbeheer. De engine bereidt de byte range voor en stelt de CMS SignedData-structuur samen. De engine houdt de private sleutel niet vast. In plaats daarvan delegeert de engine het sleutelbeheer via een openbaar contract aan een ondertekenings-back-end.

U implementeert een van de drie openbare contracten:

SignerInterface. Het basiscontract. Het retourneert een SignatureResult voor de aangeleverde gegevens, voegt een tijdstempel toe en rapporteert de ondersteuning voor langetermijnvalidatie. Gebruik dit contract wanneer de ondertekeningslogica in het proces zelf draait.
HsmSignerInterface. Het sleutelbeheercontract. De implementatie moet de ondertekening binnen de hardwaregrens uitvoeren. De private sleutel mag die grens niet verlaten. Een provider van een sleutelbeheersysteem implementeert dit contract.
DeferredSignerInterface. Een uitbreiding van SignerInterface voor asynchrone back-ends. De aanroeper levert gegevens aan, ontvangt een taakidentificatie en haalt het resultaat later op.

Deze pagina specificeert het openbare contract. De pagina beschrijft geen interne implementatie van NextPDF Pro of NextPDF Enterprise. Een betaalde editie kan een ondersteunde implementatie van dit contract leveren. U vertrouwt op het contract, niet op de implementatie.

Vereiste voor sleutelbeheer

Het contract vereist dat de private sleutel de beveiligde grens nooit verlaat. Gevestigde praktijk voor sleutelbeheer ondersteunt deze vereiste. Het National Institute of Standards and Technology (NIST) behandelt sleutelbeheer in SP 800-57 Part 1 Revision 5 als levenscyclusbeheer voor veilig genereren, opslaan, distribueren, gebruiken en vernietigen. Public-Key Cryptography Standards #11 (PKCS#11) v3.1 maakt de grens afdwingbaar. Wanneer voor een private-sleutelobject CKA_SENSITIVE op true staat of CKA_EXTRACTABLE op false, mag het token de sleutelwaarde niet in platte tekst buiten het token prijsgeven.

Uw implementatie is verantwoordelijk voor naleving van deze vereiste. De engine kan dit niet voor u afdwingen. Als uw sign()-methode ruwe sleutelbytes in het procesgeheugen kan laden, verliest het contract zijn beveiligingseigenschap.

API-oppervlak

NextPDF\Contracts\HsmSignerInterface (stabiel, sinds 1.0.0):

Methode	Retourneert	Doel
`sign(string $data, string $algorithm)`	`string`	Onderteken gegevens binnen de hardwaregrens. Retourneer de ruwe handtekeningbytes. Werp een `RuntimeException` bij een fout.
`getCertificateDer()`	`string`	Retourneer het X.509-certificaat van de ondertekenaar in Distinguished Encoding Rules-vorm (DER).
`getCertificateChainDer()`	`array<string>`	Retourneer de tussenliggende certificaten, van uitgever tot hoofdcertificaat, exclusief het certificaat van de ondertekenaar.
`getPublicKeyAlgorithm()`	`string`	Retourneer de identificatie van het algoritme voor de publieke sleutel.

NextPDF\Contracts\SignerInterface (stabiel, sinds 1.0.0):

Methode	Retourneert	Doel
`sign(string $data)`	`SignatureResult`	Retourneer de DER-gecodeerde CMS `SignedData`.
`timestamp(string $signatureValue)`	`string`	Retourneer een DER-gecodeerd Request for Comments (RFC) 3161-tijdstempeltoken.
`supportsLtv()`	`bool`	Rapporteer of er gegevens voor langetermijnvalidatie (LTV) kunnen worden ingebed.

NextPDF\Contracts\DeferredSignerInterface (experimenteel, sinds 3.0.0) breidt SignerInterface uit met submitForSigning(), retrieveSignature() en isComplete() voor asynchrone back-ends.

De handtekeningniveaus die de engine produceert, volgen de profielen voor PDF Advanced Electronic Signatures (PAdES). Het European Telecommunications Standards Institute (ETSI) definieert in EN 319 142-2 uitgebreide PAdES-profielen die voortbouwen op de basisbouwstenen in EN 319 142-1. De engine wijst de niveaus B-B, B-T, B-LT en B-LTA toe aan die bouwstenen. Uw ondertekenaar levert de cryptografische bewerking en het certificaatmateriaal dat de engine nodig heeft.

Codevoorbeeld — Snelstart

Deze minimale provider in PKCS#11-stijl delegeert de ondertekening aan het token. PHP leest de sleutelwaarde nooit.

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

Codevoorbeeld — Productie

Een productieprovider valideert invoer, faalt veilig bij een tokenfout en logt nooit sleutel- of handtekeningmateriaal.

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

Randgevallen en valkuilen

Indeling van handtekeningbytes. Retourneer de ruwe handtekeningbytes. Voor Rivest-Shamir-Adleman (RSA) zijn de bytes DER. Voor Elliptic Curve Digital Signature Algorithm (ECDSA) zijn de bytes de ruwe r-waarde gevolgd door de s-waarde.
Volgorde van de keten. getCertificateChainDer() sluit het certificaat van de ondertekenaar uit. Orden de tussenliggende certificaten van uitgever tot hoofdcertificaat.
Algoritme-identificaties. sign() gebruikt identificaties in OpenSSL-stijl. getPublicKeyAlgorithm() retourneert de X.509-algoritmenaam.
Falen is fail-closed. Werp een RuntimeException bij elke token- of KMS-fout. Retourneer geen gedeeltelijke of lege handtekening.
Vernietiging van sleutels. Wanneer een sleutel het einde van zijn cryptoperiode bereikt, vernietig de sleutel dan volgens uw sleutelbeheerprocedure. NIST SP 800-57 Part 1 Revision 5 §8.2.1.2 stelt dat een sleutel moet worden vernietigd zodra deze niet langer nodig is. De vernietiging zelf volgt §8.3.4.

Gegevenslocatie en PII-maatregelen

Het contract draagt alleen de te ondertekenen gegevens en het certificaatmateriaal over. Het contract draagt geen documentinhoud of persoonsgegevens over naar de ondertekenings-back-end. Houd de byte range zo klein mogelijk. Plaats geen persoonsgegevens in de reden- of locatievelden van de ondertekening. Die velden blijven zichtbaar in het ondertekende bestand.

Veilige telemetrie en het schonen van logs

Log nooit de gegevens die aan sign() worden doorgegeven, de geretourneerde handtekeningbytes, de sleutelidentificatie in omkeerbare vorm of een private certificaatcomponent. Log alleen het resultaat van de bewerking en een onomkeerbare referentie. De SignatureAppliedEvent-hook is het ondersteunde audit-anker. Zie Action triggers.

Dreigingsmodel

Asset	Dreiging	Maatregel
Private sleutel	Uitlekken naar het procesgeheugen	Het contract vereist ondertekening binnen de grens; PKCS#11 `CKA_SENSITIVE` / `CKA_EXTRACTABLE` dwingen niet-onttrekbaarheid af
Ondertekeningsorakel	Onbegrensde ondertekeningsverzoeken	De implementatie beperkt de frequentie en authenticeert aanroepers
Certificaatketen	Vervanging	De implementatie retourneert een keten die kan worden opgebouwd tot een vertrouwd hoofdcertificaat
Handtekeningbytes	Openbaarmaking via logs	Fail-closed foutpad; geen handtekeningmateriaal in telemetrie
Sleutel voorbij de cryptoperiode	Voortgezet gebruik	Sleutelvernietiging volgens NIST SP 800-57 Part 1 Revision 5 §8.2.1.2

Conformiteit

De handtekeningniveaus voldoen aan de PAdES-profielen. ETSI EN 319 142-2 §5.1 definieert uitgebreide PAdES-profielen op basis van de basisbouwstenen van EN 319 142-1. De engine stelt die bouwstenen samen uit het materiaal dat uw ondertekenaar levert. Het sleutelbeheer sluit aan op de levenscyclus van NIST SP 800-57 Part 1 Revision 5, inclusief de vernietigingsvereiste in §8.2.1.2. Hardwarematig sleutelbeheer sluit aan op de attributen voor niet-onttrekbare sleutels van PKCS#11 v3.1. De citaten zijn vastgelegd in de frontmatter van de pagina.

Exportcontrole en reviewbeheer

Deze pagina behandelt PKCS#11- en hardware security module-sleutelbeheer (HSM), dus de frontmatter zet export_control_class: legal-review-required op deze waarde. Volgens het reviewbeleid voor documentatie (plan §17 gate 6) vereist elke pagina met een beveiligingsmodus, -pad of -inhoud die overeenkomt met PAdES, FIPS, HSM of PKCS#11 goedkeuring van het GitHub-team @nextpdf-labs/crypto-reviewers voordat de pagina kan worden gepubliceerd. Die CODEOWNERS-goedkeuring is een harde merge-gate: de pagina blijft publish: false totdat zowel de juridische exportcontrole-review als de review door @nextpdf-labs/crypto-reviewers is afgerond.

Commerciële context

NextPDF Enterprise levert een ondersteunde implementatie van dit contract met sleutelbeheer via een sleutelbeheersysteem, het samenstellen van de certificaatketen en audit-integratie. U kunt HsmSignerInterface zelf implementeren in Core of de Enterprise-implementatie via hetzelfde openbare contract gebruiken zonder codewijzigingen.

Zie ook

Gerelateerde contracten en modules

Referentie voor ondertekeningscontracten — SignerInterface, HsmSignerInterface, DeferredSignerInterface en de tijdstempelprovider.
Referentie voor het security-policy-contract — verwant, beveiligingsgevoelig Service Provider Interface-oppervlak (SPI).
Stabiliteitsregels voor de SPI — de interfacebelofte achter de stable ondertekeningscontracten.
Action triggers en event listeners — SignatureAppliedEvent, het ondersteunde audit-anker.
Overzicht van extensieontwikkeling — het volledige openbare SPI-oppervlak.

De woordenlijst definieert key management system, cryptoperiod en HSM; raadpleeg de gepubliceerde woordenlijst voor de canonieke definities.