Contracts / Signing

In een oogopslag

Het ondertekeningsdomein omvat zes contracten. Ze bepalen hoe je een handtekening volgens de Cryptographic Message Syntax (CMS) produceert, een tijdstempel volgens Request for Comments (RFC) 3161 aanbrengt, met een sleutel uit een hardwarebeveiligingsmodule (HSM) ondertekent en langdurige validatie (LTV) inschakelt. Core publiceert de contracten; de Pro- en Enterprise-edities leveren de productie-implementaties.

Installatie

composer require nextpdf/core:^3

Conceptueel overzicht

Een digitale handtekening in het Portable Document Format (PDF) is een CMS SignedData-structuur die in het handtekeningwoordenboek is opgeslagen. De vermelding Contents bevat de structuur die volgens de Distinguished Encoding Rules (DER) is gecodeerd. De vermelding ByteRange benoemt de bytebereiken die door de digest worden gedekt. De digest omvat het hele bestand en sluit de handtekeningwaarde zelf uit; zie International Organization for Standardization (ISO) 32000-2 §12.8.1. De CMS-structuur volgt RFC 5652 §5.1: versie, digest-algoritmen, ingekapselde inhoud en ondertekenaarsinformatie.

SignerInterface is het core-contract. Het produceert CMS SignedData voor een bytebereik, brengt een tijdstempel aan op een handtekeningwaarde en meldt of het LTV ondersteunt. Het bestrijkt de baseline-niveaus B-B tot en met B-LTA van PDF Advanced Electronic Signatures (PAdES), zoals gedefinieerd door het European Telecommunications Standards Institute (ETSI) EN 319 142. Elk hoger niveau voegt validatiemateriaal toe. B-B bevat de basishandtekening. B-T voegt een handtekeningtijdstempel toe. B-LT voegt herroepingsgegevens toe. B-LTA voegt een archiveringstijdstempel toe.

HsmSignerInterface ondertekent met een sleutel die in een hardwarebeveiligingsmodule is opgeslagen. De privésleutel verlaat de hardwaregrens nooit. Het contract geeft het ondertekenaarscertificaat en de certificaatketen in DER-vorm terug, zodat de CMS-laag de structuur kan opbouwen. DeferredSignerInterface breidt SignerInterface uit voor asynchrone ondertekening. De aanroeper dient gegevens in, ontvangt een taakidentificatie, controleert periodiek of de taak is voltooid en haalt het resultaat op. Gebruik dit wanneer een externe HSM of cloudsleuteldienst niet meteen een resultaat retourneert.

TimestampProviderInterface vraagt een tijdstempeltoken volgens RFC 3161 aan. Het protocol is een verzoek-antwoorduitwisseling met een Time-Stamping Authority (TSA); zie RFC 3161 §2.4. De messageImprint in het token is een hash van de handtekeningwaarde; zie RFC 3161 §2.4.2. LtvManagerInterface schakelt LTV in. Het verzamelt de certificaatketen, haalt antwoorden op via het Online Certificate Status Protocol (OCSP) en via de certificaatherroepingslijst (CRL), bouwt de Document Security Store (DSS) op en voegt een documenttijdstempel toe voor B-LTA. CryptoPolicyInterface beperkt de toegestane hash-, handtekening- en versleutelingsalgoritmen, evenals sleutelsterktes, voordat een cryptografische bewerking wordt uitgevoerd.

API-oppervlak

Type	Soort	Belangrijkste leden	Stabiliteit	Sinds
`SignerInterface`	interface	`sign(string): SignatureResult`, `timestamp(string): string`, `supportsLtv(): bool`	stabiel	1.0.0
`HsmSignerInterface`	interface	`sign(string, string): string`, `getCertificateDer()`, `getCertificateChainDer()`, `getPublicKeyAlgorithm()`	stabiel	1.0.0
`DeferredSignerInterface`	interface	`submitForSigning(string): string`, `retrieveSignature(string)`, `isComplete(string)` (breidt `SignerInterface` uit)	experimenteel	3.0.0
`TimestampProviderInterface`	interface	`getTimestamp(string): string`	experimenteel	3.0.0
`LtvManagerInterface`	interface	`enableLtv(...)`, `addDocumentTimestamp(...)`	stabiel	1.10.0
`CryptoPolicyInterface`	interface	`isHashAlgorithmAllowed()`, `isSignatureAlgorithmAllowed()`, `isEncryptionAlgorithmAllowed()`, `isKeyStrengthAllowed()`, `getPreferredHashAlgorithm()`, `getName()`	stabiel	1.9.0

SignerInterface::sign() retourneert een NextPDF\Security\Signature\SignatureResult. De publieke eigenschap $cmsSignedData bevat de DER-gecodeerde CMS. De publieke eigenschap $digestHex bevat de SHA-256-digest. De publieke eigenschap $timestampToken bevat het optionele TSA-token. De accessors zijn toHex() / toHexPadded(int) / getSize() / hasTimestamp(). HsmSignerInterface::sign() retourneert DER-gecodeerde bytes voor Rivest-Shamir-Adleman (RSA) en ruwe r‖s-bytes voor het Elliptic Curve Digital Signature Algorithm (ECDSA). Het algoritme-argument gebruikt OpenSSL-identifiers.

Codevoorbeeld — Snelstart

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Contracts\SignerInterface;

/**
 * Sign a byte range with any SignerInterface implementation.
 *
 * @param SignerInterface $signer    A core or Premium signer.
 * @param string          $byteRange The PDF byte range to sign.
 *
 * @return string Hex-encoded CMS SignedData for the PDF /Contents field.
 */
function signByteRange(SignerInterface $signer, string $byteRange): string
{
    $result = $signer->sign($byteRange);

    return $result->toHex();
}

SignerInterface::sign() retourneert een SignatureResult. toHex() levert de hex-tekenreeks die de writer in het veld /Contents plaatst; de ruwe DER-bytes zijn beschikbaar via de publieke eigenschap $cmsSignedData. De functie hangt af van het contract, niet van een concrete klasse. Een Core-testondertekenaar en een Premium HSM-ondertekenaar voldoen allebei aan dit contract.

Codevoorbeeld — Productie

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Contracts\CryptoPolicyInterface;
use NextPDF\Contracts\SignerInterface;
use NextPDF\Contracts\TimestampProviderInterface;
use NextPDF\Exception\NextPdfException;
use Psr\Log\LoggerInterface;

final readonly class TimestampedSigningService
{
    public function __construct(
        private SignerInterface $signer,
        private TimestampProviderInterface $timestamps,
        private CryptoPolicyInterface $policy,
        private LoggerInterface $logger,
    ) {}

    /**
     * Sign a byte range, then timestamp the CMS structure.
     *
     * @param string $byteRange The PDF byte range to sign.
     *
     * @return array{cms: string, digest: string, tst: string}
     */
    public function sign(string $byteRange): array
    {
        if (!$this->policy->isHashAlgorithmAllowed($this->policy->getPreferredHashAlgorithm())) {
            throw new \LogicException('Preferred hash rejected by crypto policy.');
        }

        try {
            $signature = $this->signer->sign($byteRange);
            $token = $this->timestamps->getTimestamp($signature->cmsSignedData);

            return [
                'cms' => $signature->toHex(),
                'digest' => $signature->digestHex,
                'tst' => $token,
            ];
        } catch (NextPdfException $e) {
            $this->logger->error('Signing failed', [
                'policy' => $this->policy->getName(),
                'error' => $e->getMessage(),
            ]);

            throw $e;
        }
    }
}

De service injecteert drie contracten. De service controleert het cryptobeleid voordat de ondertekening plaatsvindt. SignatureResult stelt de CMS-bytes beschikbaar via de publieke eigenschap $cmsSignedData, de SHA-256-digest via $digestHex en de hex-tekenreeks voor /Contents via toHex(). De tijdstempelprovider ontvangt de CMS-bytes en retourneert een DER-gecodeerd token. Het catch-blok logt de beleidsnaam en gooit de uitzondering opnieuw. Het verzwijgt de fout nooit.

Randgevallen en valkuilen

De digest van het bytebereik moet de handtekeningwaarde uitsluiten. Een digest die de vermelding Contents dekt, produceert een handtekening die nooit kan worden geverifieerd; zie ISO 32000-2 §12.8.1.
SignerInterface::supportsLtv() meldt wat mogelijk is, niet de huidige toestand. Een ondertekenaar kan LTV ondersteunen en toch een B-B-handtekening produceren wanneer er geen tijdstempeldienst is geconfigureerd.
DeferredSignerInterface::retrieveSignature() retourneert null totdat de taak is voltooid. Controleer eerst isComplete(), zodat je niet bij elke controle de payload overdraagt. Ophalen is idempotent zodra er een resultaat bestaat.
LtvManagerInterface::addDocumentTimestamp() moet worden uitgevoerd nadat de Document Security Store is geschreven. Als je dit eerder aanroept, ontstaat een ongeldige B-LTA-structuur.
CryptoPolicyInterface retourneert true voor elk algoritme wanneer er geen beleid is ingesteld. Stel in een gereguleerde omgeving een expliciet beleid in; vertrouw niet op de open standaardinstelling.
HsmSignerInterface::getCertificateChainDer() sluit het ondertekenaarscertificaat uit. Gebruik getCertificateDer() voor het ondertekenaarscertificaat en de ketenmethode voor tussenliggende certificaten.

Prestaties

De kosten van ondertekening komen vooral voort uit de cryptografische bewerking en eventuele netwerkroundtrips, niet uit het contract. Een lokale softwarehandtekening duurt doorgaans een paar milliseconden. Een HSM-handtekening voegt de roundtrip naar het apparaat toe. Een tijdstempel voegt een netwerkroundtrip naar de Time-Stamping Authority toe. Langdurige validatie voegt één OCSP- of CRL-ophaalactie per certificaat in de keten toe. Het performance_budget van 1500 ms wandtijd dekt één getijdstempelde handtekening met een externe TSA op een warme verbinding. Langdurige validatie tegen een traag herroepingseindpunt overschrijdt dit en zou buiten het verzoekpad moeten worden uitgevoerd. Het reproduceerbaarheidsprofiel is structural, niet bitwise. Een tijdstempel bevat het ondertekeningsmoment, dus twee uitvoeringen verschillen in tijdstempelbytes terwijl de documentstructuur identiek blijft.

Beveiligingsnotities

De ondertekeningscontracten vormen de primaire cryptografische grens van de engine, dus het bedreigingsmodel is expliciet. Sleutelbewaring is het eerste aandachtspunt: HsmSignerInterface houdt de privésleutel binnen de hardwaregrens en het contract stelt nooit sleutelmateriaal beschikbaar. Algoritmedowngrade is het tweede: CryptoPolicyInterface blokkeert zwakke hashes en korte sleutels vóór de bewerking, waardoor een implementatie een profiel volgens de Federal Information Processing Standards (FIPS) 140-3 of volgens electronic identification, authentication, and trust services (eIDAS) kan afdwingen zonder de engine te forken. Vertrouwen in tijdstempels is het derde: een RFC 3161-token is alleen zo betrouwbaar als de Time-Stamping Authority, dus het providercontract is injecteerbaar en een implementatie legt de eigen autoriteit vast. Langdurige validatie is het vierde: herroepingsmateriaal wordt op het moment van ondertekenen opgehaald en in de Document Security Store opgeslagen, zodat verificatie mogelijk blijft nadat een certificaat is verlopen. Behandel elke invoer van een ondertekenaar als niet-vertrouwd. De engine berekent het bytebereik; het wordt nooit van de aanroeper geaccepteerd. Deze pagina is gemarkeerd als export_control_class: legal-review-required omdat de contracten cryptografische ondertekening regelen. De doorlopende tekst parafraseert alle normatieve bronnen en citeert er geen, volgens de regels voor bronvermeldingen.

Conformiteit

Bewering	Standaard	Clausule	Bewijs
De vermelding `Contents` in het handtekeningwoordenboek slaat de handtekeningwaarde op als DER-gecodeerde CMS SignedData of als een TimeStampToken.	ISO 32000-2	§12.8.1
De digest wordt berekend over het bytebereik dat door de array `ByteRange` wordt gedefinieerd, en sluit de handtekeningwaarde uit.	ISO 32000-2	§12.8.1	,
De Document Security Store bevat langdurig validatiemateriaal met validation-related information (VRI), OCSP, CRL en certificaatvermeldingen.	ISO 32000-2	§12.8.4.3	,
PAdES-langdurige validatie plaatst validatiegegevens in de woordenboeken DSS en VRI.	ETSI EN 319 142-2	§6.3	,
Een tijdstempeltoken volgens RFC 3161 bindt een hash van de handtekeningwaarde via `messageImprint` in een verzoek-antwoorduitwisseling met een TSA.	RFC 3161	§2.4.2, §2.4	,
De CMS SignedData-reeks bevat versie, digest-algoritmen, ingekapselde inhoud en ondertekenaarsinformatie.	RFC 5652	§5.1

Alle clausules zijn geparafraseerd. NextPDF reproduceert geen normatieve tekst. Raadpleeg de gepubliceerde standaarden voor de gezaghebbende formulering.

Commerciële context

Core publiceert en bevriest de ondertekeningscontracten. De Pro- en Enterprise-edities leveren de productie-implementaties achter HsmSignerInterface, LtvManagerInterface en de uitgestelde ondertekenaar, inclusief hardware-integratie volgens Public-Key Cryptography Standards #11 (PKCS#11) en PAdES B-LT en B-LTA. Core lost deze implementaties tijdens runtime op met class_exists() en cast ze naar het contract, zodat de open-source-engine geen commerciële afhankelijkheid krijgt en de API niet verandert bij een upgrade.

Zie ook

Contracts: 41 publieke interfaces (SPI): overzicht van de service provider interface en stabiliteitsniveaus.
Contracts / Security Policy: algoritme- en sleutelbeperking van CryptoPolicyInterface.
Contracts / Extraction: PDF/A-handhaving die samengaat met ondertekende archivering.
Security: implementatie-oppervlak voor versleuteling en handtekeningen.
Audit: auditlogging van beleidsnamen en ondertekeningsgebeurtenissen.
Exception: hiërarchie van NextPdfException die door ondertekenaars wordt gegooid.