Configuration de la TSA

En un coup d’œil

NextPDF ne contacte une autorité d’horodatage (TSA) que lorsque vous signez à PAdES B-T ou au-dessus. À B-B, il n’y a ni horodatage ni appel réseau, donc cette page ne s’applique pas à une signature B-B.

Pour que B-T fonctionne dès l’installation, NextPDF embarque une TSA par défaut intégrée. Ce défaut est une commodité : il permet à une signature horodatée d’aboutir sans configuration supplémentaire. Il n’est pas publiquement reconnu et pas qualifié eIDAS, il n’est donc pas adapté à un usage en production ou de conformité sans un choix délibéré. Cette page explique exactement ce qu’est ce défaut, comment pointer NextPDF vers votre propre TSA, comment désactiver l’horodatage, et les deux voies de mise à niveau.

Trois propriétés sont indépendantes et ne doivent pas être confondues :

auto-hébergé — qui exploite le serveur et vers quelle racine son certificat s’enchaîne ;
publiquement reconnu — si l’écosystème de validation qu’utilisent vos parties utilisatrices (leur magasin de confiance ou leur liste de confiance) fait déjà confiance à cette racine sans configuration manuelle, plutôt que d’exiger l’installation manuelle d’une racine privée. Il s’agit ici des ancres de confiance de la partie utilisatrice, et non d’un programme particulier tel que la Web PKI ;
qualifié eIDAS — si l’horodatage produit un effet juridique qualifié dans l’UE.

Le défaut livré est uniquement auto-hébergé. Une TSA publiquement reconnue ajoute la deuxième propriété. Une TSA qualifiée eIDAS porte en outre un statut juridique qualifié, validé via les listes de confiance de l’UE, et peut être exploitée par un QTSP tiers. Les trois propriétés sont indépendantes — l’une n’implique pas l’autre.

La TSA par défaut intégrée

Le point d’accès par défaut est https://timestamp.pateon.com.tw, le propre serveur d’horodatage RFC 3161 de NextPDF. Il est auto-hébergé : le certificat de son unité d’horodatage s’enchaîne vers une racine PATEON privée, et non vers un programme de confiance public. Une partie utilisatrice ne peut donc pas valider un horodatage émis par le défaut à moins d’avoir installé et approuvé cette racine PATEON hors bande.

Comme un jeton RFC 3161 ne porte aucune preuve externe que l’instant affirmé est correct, la confiance accordée à un tel horodatage repose entièrement sur la confiance accordée à la TSA émettrice (ISO/IEC 18014-2 §7.3). Pour le défaut livré, cette ancre de confiance est privée, ce qui explique pourquoi le défaut est un défaut de commodité et de développement, et non un défaut de qualité conformité.

Lorsque le point d’accès par défaut est utilisé et que votre framework dispose d’un logger configuré, NextPDF émet un avertissement unique au démarrage du processus indiquant que le défaut n’est pas publiquement reconnu et renvoyant vers cette configuration. L’avertissement est informatif ; la signature aboutit malgré tout.

Surcharger le défaut

Définissez le point d’accès de la TSA dans la configuration de votre adaptateur de framework. La clé exacte diffère selon l’adaptateur (voir le tableau par framework) : dans Laravel, c’est la variable d’environnement NEXTPDF_TSA_URL, dans Symfony, le nœud de bundle nextpdf.tsa.url, et dans CodeIgniter, la clé d’environnement nextPdf.tsa.url.

La TSA effective est résolue selon cette priorité, de la plus élevée à la plus basse :

Un TsaClient explicite que vous construisez et injectez vous-même — il l’emporte toujours.
L’URL configurée dans votre adaptateur — utilisée lorsque vous n’injectez pas de client.
Le défaut intégré — utilisé uniquement lorsqu’aucun des deux précédents n’est défini.

# Laravel (.env): use your own publicly-trusted TSA instead of the shipped default.
NEXTPDF_TSA_URL=http://timestamp.digicert.com

Désactiver l’horodatage

Laisser l’url de la TSA de votre adaptateur à sa valeur par défaut (non configurée) conserve le point d’accès par défaut intégré. Définir cette url à une valeur vide est différent : cela désactive l’horodatage. Sans TSA configurée, une signature demandée à B-T ou au-dessus échoue de façon fermée avec une erreur « TSA required », plutôt que de retomber silencieusement à B-B.

# Laravel (.env):
# NEXTPDF_TSA_URL unset -> use the built-in default (timestamp succeeds against pateon).
# NEXTPDF_TSA_URL empty -> no TSA; a B-T+ request fails closed.
NEXTPDF_TSA_URL=

Choisir l’algorithme de condensat du messageImprint

Une requête d’horodatage RFC 3161 porte un messageImprint — une empreinte des données horodatées — et NextPDF utilise SHA-256 pour cette empreinte par défaut. Ce défaut est un choix délibéré et interopérable ; vous avez rarement besoin de le changer.

Lorsque vous construisez un TsaClient à la main, vous pouvez sélectionner un condensat d’empreinte différent via le paramètre de constructeur imprintHashAlgorithm, qui prend un cas TsaImprintHashAlgorithm : Sha256 (le défaut), Sha384, Sha512, Sha3_256, Sha3_384 ou Sha3_512. Le défaut conserve chaque requête émise octet pour octet identique aux versions antérieures, de sorte que la mise à niveau ne change rien à moins que vous ne l’activiez explicitement.

use NextPDF\Security\Timestamp\TsaClient;
use NextPDF\Security\Timestamp\TsaImprintHashAlgorithm;

// Default — SHA-256 imprint, unchanged from earlier releases:
$tsa = new TsaClient('https://timestamp.example.com/tsa');

// Opt in to a stronger imprint digest:
$tsa = new TsaClient(
    'https://timestamp.example.com/tsa',
    imprintHashAlgorithm: TsaImprintHashAlgorithm::Sha512,
);

Deux contraintes méritent d’être connues avant de vous éloigner du défaut :

La prise en charge par l’écosystème se limite à SHA-256 aujourd’hui. Une empreinte autre que SHA-256 interopère avec le vérificateur de jetons de Core, mais le point de contrôle de preuve PAdES B-T de nextpdf-server et la table des condensats de validation de Premium ne reconnaissent pour l’instant que les empreintes SHA-256. Un horodatage de signature construit avec un condensat d’empreinte différent ne prouvera donc pas encore B-T sur ces surfaces. Conservez le défaut à moins que chaque consommateur de vos horodatages soit connu pour accepter le condensat que vous choisissez.
Les condensats pré-calculés doivent correspondre à l’algorithme. getDocumentTimestamp() prend une empreinte de document déjà calculée ; il échoue de façon fermée, avant tout appel réseau, lorsque la longueur de cette empreinte ne correspond pas à l’algorithme d’empreinte configuré, plutôt que d’envoyer une requête incohérente.

Voies de mise à niveau

Pour tout usage au-delà du développement ou de l’usage interne, remplacez le défaut par l’une des deux options plus robustes.

TSA publiquement reconnue

Pointez l’url de la TSA de votre adaptateur vers une TSA dont le certificat s’enchaîne vers une racine publique à laquelle vos parties utilisatrices font déjà confiance — par exemple http://timestamp.digicert.com. Aucune racine privée n’a besoin d’être distribuée. Une TSA de qualité production déclarera généralement sa conformité à une politique d’horodatage telle que ETSI EN 319 421 §5 et suivra le profil de protocole RFC 3161 décrit dans ETSI EN 319 422 §7 ; vérifiez-le auprès de la politique publiée de l’exploitant plutôt que de le présumer de la seule confiance publique.

TSA qualifiée eIDAS

Pour des horodatages qui doivent produire un effet juridique qualifié dans l’Union européenne, utilisez un service d’horodatage qualifié fourni par un prestataire de services de confiance qualifié (QTSP) inscrit sur une liste de confiance de l’UE. Un horodatage électronique qualifié lie l’instant aux données de manière à empêcher raisonnablement toute altération indétectable, repose sur une source de temps exacte liée au temps universel coordonné, et est protégé par une signature électronique avancée ou un cachet électronique avancé du QTSP, ou par une méthode équivalente (Regulation (EU) 910/2014, Art 42). C’est l’option la plus robuste et celle à choisir lorsqu’une réglementation nomme explicitement des horodatages qualifiés.

Configuration par framework

Le défaut réside dans la configuration de chaque adaptateur de framework, et non dans le moteur du noyau. Le noyau n’invente jamais d’URL : un TsaClient que vous construisez à la main exige un point d’accès explicite et lève une exception s’il est vide. Les niveaux à long terme (B-LT et B-LTA) réutilisent la même TSA configurée que B-T.

Intégration	Où réside le défaut	Comment surcharger
Laravel	`config/nextpdf.php` -> `tsa.url`	définissez `NEXTPDF_TSA_URL` dans `.env`
Symfony	config de bundle `nextpdf.tsa.url`	définissez le nœud, ou liez-le à une variable d’environnement
CodeIgniter	`Config\NextPdf::$tsa['url']`	surchargez via la clé d’environnement `nextPdf.tsa.url`
Plain core	aucun défaut implicite	construisez un `TsaClient` avec une URL explicite + un client PSR-18 durci

Dans chaque adaptateur, B-B ne construit jamais de client TSA, donc une signature non horodatée n’est affectée par aucun de ces réglages.

Modèle de confiance et standards

La valeur d’un horodatage tient à la chaîne de confiance qui le soutient, et non aux octets eux-mêmes. Le jeton RFC 3161 affirme seulement un instant ; que cette affirmation soit crédible est une propriété de la TSA qui l’a signé (RFC 3161 §2 ; ISO/IEC 18014-2 §7.3). Lorsque vous conservez le défaut livré, vous choisissez une ancre de confiance auto-hébergée et privée — convenable pour le développement et les flux internes où chaque partie utilisatrice peut installer la racine PATEON, mais pas pour des documents validés par des tiers. Pour ceux-ci, passez à une TSA publiquement reconnue, ou à une TSA qualifiée eIDAS lorsqu’un effet juridique qualifié est requis.

Si vous exploitez vous-même le défaut, vous pouvez épingler la clé publique de la TSA dans votre propre client PSR-18 injecté. N’épinglez pas le défaut livré dans du code partagé : une rotation de clé du côté de l’exploitant casserait alors tous les utilisateurs du défaut d’un coup. La confiance dans un horodatage tient à la chaîne de certificats et à la racine PATEON, et non à un épinglage au niveau du transport.