Enterprise édition

Contracts — Référence approfondie

En un coup d’œil

Le module Contracts est le point d’intégration Enterprise pour les clients d’autorité d’horodatage (Time Stamp Authority) RFC 3161.

TsaClientInterface déclare une seule opération : demander un TimeStampToken encodé en DER pour un condensé de document pré-calculé.
TsaClientAdapter relie le client d’horodatage Core, une classe final, à cette interface sans en changer le comportement.
Les composants Enterprise tels que LtvManager et DocumentTimestamp acceptent l’interface, de sorte que le comportement TSA est injectable et substituable dans les tests.
Seul un hachage de document franchit ce point d’accroche ; le contenu du document ne le franchit jamais.

Pour des conseils sur les workflows, lis d’abord la page de capacité Contracts.

Disponibilité et licence

Cette capacité est fournie dans NextPDF Enterprise (nextpdf/enterprise) et s’active avec une enveloppe de licence de niveau Enterprise. Un déploiement sans ce droit ne charge pas les classes de la capacité. Comparer les éditions et obtenir une licence.

L’interface n’effectue aucun travail et ne conditionne rien par elle-même. Les surfaces Enterprise consommatrices appliquent leurs propres codes de capacité, comme enterprise.compliance.evidence sur la surface de preuve de conformité.

Niveau	Fournit
Core	`TsaClient` concret (`final`) qui effectue les requêtes RFC 3161
Pro	Pas d’équivalent du module Contracts
Enterprise	Le point d’accroche `TsaClientInterface` et le pont `TsaClientAdapter`

composer require nextpdf/enterprise:^3

Surface d’API publique

Symbole	Paramètres	Comportement par défaut	Retourne	Lève ou échoue avec	Notes
`TsaClientInterface::getDocumentTimestamp()`	`string $documentHash`	Déclare une demande de jeton d’horodatage pour un condensé de document pré-calculé	`string` — TimeStampToken encodé en DER	Défini par l’implémentation ; l’interface ne déclare aucune exception	Unique opération ; la source documente une entrée de condensé SHA-256
`TsaClientAdapter::__construct()`	`TsaClient $client`	Stocke le client d’horodatage Core	`TsaClientAdapter`	Rien de déclaré	`final readonly` ; promotion de constructeur
`TsaClientAdapter::getDocumentTimestamp()`	`string $documentHash`	Transmet à `TsaClient::getDocumentTimestamp()` sans modification	`string` — TimeStampToken encodé en DER	`TsaException` du client Core, transmise sans modification	N’ajoute aucun comportement ; n’avale rien

namespace NextPDF\Enterprise\Contracts;

interface TsaClientInterface
{
    /**
     * Request a timestamp token for a document hash.
     *
     * @param string $documentHash SHA-256 digest of the document content
     *
     * @return string DER-encoded TimeStampToken
     */
    public function getDocumentTimestamp(string $documentHash): string;
}

namespace NextPDF\Enterprise\Contracts;

use NextPDF\Security\Timestamp\TsaClient;

final readonly class TsaClientAdapter implements TsaClientInterface
{
    public function __construct(
        private TsaClient $client,
    )

    public function getDocumentTimestamp(string $documentHash): string
}

Contrat de comportement

TsaClientInterface::getDocumentTimestamp(string $documentHash): string retourne un TimeStampToken RFC 3161 encodé en DER pour un hachage de document. Règles observables de l’extérieur :

L’interface déclare une seule opération ; elle ne valide pas le jeton, ne se porte pas garante de la TSA et n’affirme aucun effet juridique.
TsaClientAdapter transmet l’appel au client d’horodatage Core sans modification — aucun comportement ajouté, aucune nouvelle tentative, aucune exception avalée, aucune garantie supplémentaire. Son unique but est de permettre à un client Core final de satisfaire une interface orientée Enterprise, pour l’inversion de dépendances et les tests.
Seul un hachage de document franchit la frontière ; aucun contenu de document n’est transmis.
Derrière l’adaptateur, le client Core rejette avec TsaException un condensé dont la longueur ne correspond pas à son algorithme d’empreinte configuré, en mode fail-closed, avant toute activité réseau. Une empreinte mal étiquetée produirait autrement un jeton qu’aucun validateur conforme ne peut lier.
Surfaces consommatrices : LtvManager accepte un TsaClientInterface optionnel et en exige un pour PAdES B-LTA. DocumentTimestamp utilise le contrat pour remplir le /Contents d’un dictionnaire de signature /DocTimeStamp. L’exécuteur de renouvellement d’archive LTV (LtvaRenewalExecutor) branche un TsaClientAdapter autour du client Core lors du renouvellement des horodatages de document.

Cas limites et modes de défaillance

L’adaptateur transmet sans modification les exceptions du client sous-jacent ; les défaillances de la TSA doivent être gérées sur le site d’appel.
Le condensé doit être en binaire brut selon l’algorithme d’empreinte configuré du client concret (SHA-256 par défaut, 32 octets). Un condensé encodé en hexadécimal a une longueur incorrecte et est rejeté avant l’envoi de toute requête.
Un jeton retourné est constitué d’octets, pas d’un verdict ; valide-le là où c’est nécessaire.
Une implémentation personnalisée est responsable de sa propre surface de défaillance. Le contrat ne fixe que la forme de retour : un TimeStampToken encodé en DER.

Comportement en mode FIPS

Ce module n’effectue aucune opération cryptographique. Le choix de l’algorithme et le comportement en mode FIPS sont régis par le client TSA concret et le module Security. Consulte la référence approfondie FIPS 140.

Conformité

Comportement	Référence
Demande de jeton d’horodatage et liaison	IETF RFC 3161 §2
Un TimeStampReq contient un MessageImprint : un identifiant d’algorithme de hachage et le hachage des données à horodater	IETF RFC 3161 §2.4.1
Le messageImprint du jeton doit être égal à la valeur de la requête, la taille du hachage correspondant à l’algorithme identifié	IETF RFC 3161 §2.4.2

Le contrat est modelé autour de RFC 3161 ; la demande de jeton proprement dite et toute vérification sont effectuées par le client concret et les surfaces Evidence/Signature. L’interface ne formule aucune revendication de conformité ou d’attestation. NextPDF ne formule aucune revendication de certification.

Notes de développement

Les deux types portent @since 3.0.0 ; cette référence documente la surface telle que livrée dans nextpdf/enterprise 3.1.0.
Injecte TsaClientInterface dans les composants qui ont besoin d’horodatages ; branche TsaClientAdapter, ou une implémentation personnalisée, à la racine de composition. Substitue un double de test dans les tests unitaires plutôt qu’une TSA réelle.
L’opérateur est responsable du client TSA concret derrière l’adaptateur : la résidence, la frontière de confiance du point de terminaison TSA et la vérification de la chaîne de certificats s’appliquent à ce client, pas à cette interface.
Aucune restriction de contrôle des exportations ne s’applique à cette surface de contrat. L’obtention d’un jeton d’horodatage prend en charge les workflows d’audit et de validation à long terme ; ce n’est ni une attestation juridique ni une certification. Cette référence n’est pas un avis juridique.
Les détails du mécanisme interne restent dans la documentation interne du dépôt source et sortent du périmètre de ce manuel.

Limite de publication

Cette page documente uniquement le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins de namespace internes, les classes utilitaires, les tables de mécanisme, les noms de fichiers de runbook et les préfixes de ticket sortent du périmètre.