Appliquer une signature numérique PAdES avec NextPDF Connect (Pro)

En bref

Applique à un PDF une signature numérique PAdES de base via NextPDF Connect. Après revérification auprès du fournisseur d’outils Pro, l’outil est bien sign_pdf : ce fournisseur enregistre new SignPdfTool(), dont le nom de protocole est sign_pdf. sign_pdf est un outil de niveau Pro. Le serveur le sonde avec class_exists() au démarrage et ne l’enregistre que lorsque le paquet Pro est installé.

Par défaut, l’outil produit du PAdES B-B. Il peut produire du PAdES B-T (B-B plus un RFC 3161 signature-time-stamp) uniquement lorsque l’hôte a raccordé un fournisseur d’horodatage à l’outil ; la requête ne peut pas pointer vers une TSA. Les niveaux à long terme (B-LT, B-LTA) et leur matériel de validation (DSS, VRI, LTV) ne font pas partie de cet outil et restent hors périmètre ici.

Mise en garde U-1. NextPDF ne revendique aucune certification ETSI EN 319 142-1 indépendante pour le PAdES B-T. EN 319 142-1 ne figure pas dans le corpus de vérification. L’exigence B-T relative à signature-time-stamp est vérifiée par rapport à ETSI EN 319 122-1 §5.3 (la base CAdES qu’EN 319 142-1/-2 importent par référence), conjointement avec RFC 3161, RFC 5652, RFC 5816 et ISO 32000-2 §12.8. La prise en charge du profil B-T n’est ni une certification de conformité ni une garantie de validité juridique ; un validateur indépendant tranche ce point.

Installation

composer require nextpdf/server
composer require nextpdf/pro

Configure un transport. Vérifie que sign_pdf existe avec diagnostic.capabilities. Pour B-T, l’hôte doit instancier l’outil avec un fournisseur d’horodatage. Sans cela, une requête pades_b_t: true échoue avec une erreur typée au lieu d’être rétrogradée silencieusement.

Vue d’ensemble conceptuelle

sign_pdf calcule un condensé de plage d’octets sur le fichier, en excluant l’emplacement réservé à la valeur de signature (ISO 32000-2 §12.8.1). Il écrit ensuite un CMS SignedData encodé en DER dans le dictionnaire de signature Contents (ISO 32000-2 §12.8.1). Algorithmes pris en charge : RSA-SHA256 (par défaut), RSA + SHA-3 (256/384/512) et Ed25519. Une enveloppe AES-GCM optionnelle peut encapsuler la charge utile private_key entrante pour les transports qui ne sont pas confidentiels de bout en bout.

Passage à B-T. Avec pades_b_t: true et un fournisseur d’horodatage raccordé par l’hôte, la signature est mise à niveau vers PAdES B-T : le hachage de plage d’octets est envoyé à une TSA et un TimeStampToken est intégré (ISO 32000-2 §12.8.5). B-T correspond exactement à B-B plus un RFC 3161 signature-time-stamp porté sous forme d’attribut non signé sur le CMS SignerInfo (RFC 5652 §5.3). Les attributs non signés ne sont pas couverts par la signature ; le condensé signé B-B et sa validité restent donc inchangés (RFC 5652 §5.3). La valeur de l’attribut est un SignatureTimeStampToken (ETSI EN 319 122-1 §5.3). B-T n’ajoute aucun dictionnaire DSS, aucun VRI, aucun matériel de validation et aucune boucle d’horodatage d’archive : ceux-ci constituent le delta Enterprise B-LT/B-LTA et sont hors du périmètre de cet outil.

Mise en garde U-1 (répétée au niveau de la revendication B-T). La prise en charge de B-T ici n’est ni une certification de conformité EN 319 142-1 ni une garantie de validité juridique ; un validateur indépendant en décide. EN 319 142-1 ne figure pas dans le corpus de vérification. B-T est fondé sur ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652, RFC 5816 et ISO 32000-2 §12.8.

Le flux de l’outil — y compris le raccordement à la TSA contrôlé par l’hôte (la requête ne peut pas pointer vers une TSA) et la branche B-T à échec fermé (jamais de rétrogradation silencieuse) — est illustré ci-dessous.

Diagram

Surface d’API

Outil	Niveau	Rôle	Niveau de risque
`create_pdf`, `add_text`	Core	Construire le contenu	Sûr / Prudence
`sign_pdf`	Pro	Appliquer PAdES B-B (ou B-T contrôlé par l’hôte)	Approbation requise
`output_pdf`	Core	Rendre et renvoyer le PDF	Approbation requise / Revue (base64)

Les noms d’outils correspondent aux noms de protocole du registre ; le catalogue d’outils sert de référence. Les outils disponibles dépendent du niveau installé, et les outils des niveaux à long terme ne sont pas présents dans Pro.

Exemple de code — Démarrage rapide

create_pdf → construis le contenu avec add_text.
sign_pdf avec certificate (PEM), private_key (PKCS#8 PEM), signer_name, reason et, éventuellement, algorithm. Omets pades_b_t (ou règle-le sur false) pour B-B.
output_pdf.

L’outil renvoie cette enveloppe de résultat :

{
  "pdf": "<base64 of the signed PDF>",
  "signature_count": 1,
  "is_complete": true,
  "algorithm": "RSA_SHA256",
  "oid": "<algorithm OID>",
  "digest": "<digest algorithm>",
  "level": "PAdES-B-B",
  "timestamped": false
}

Pour une signature B-T contrôlée par l’hôte, envoie pades_b_t: true ; level devient "PAdES-B-T" et timestamped vaut true.

Exemple de code — Production

Effectue la signature en dernière opération sur le contenu. Tout add_text/add_image après sign_pdf invalide la signature. Sur un transport non confidentiel, encapsule private_key dans l’enveloppe AES-GCM transport_encryption (nonce de 12 octets ; clé de 16/24/32 octets). Vérifie que le level du résultat correspond à ce que tu as demandé. Une requête pades_b_t: true adressée à un outil sans fournisseur échoue explicitement : gère cette erreur et ne réessaie pas silencieusement en B-B.

Cas limites & pièges

Non-concordance certificat/clé. Rejetée avec une erreur claire ; la clé privée doit correspondre à la clé publique du certificat.
PEM malformé / certificat expiré. Rejetés ; par défaut, l’outil ne signe pas avec un certificat illisible ou expiré.
Contenu après la signature. Rejeté — signe en dernier.
B-T demandé, aucun fournisseur. Une erreur typée est renvoyée : la signature n’est pas produite et n’est pas silencieusement rétrogradée en B-B.
Certificat auto-signé. La signature est appliquée, mais les lecteurs affichent une confiance inconnue : c’est attendu et ce n’est pas un défaut de l’outil.
Pro absent. Avec Core seul, sign_pdf n’est pas enregistré.

Performance

La signature ajoute la construction du CMS et, pour B-T, un aller-retour TSA ; le budget en tient compte. Le profil est semantic : un jeton RFC 3161 est intrinsèquement non reproductible, et le condensé de plage d’octets §12.8.1 exclut la valeur de signature ; la comparaison honnête porte donc uniquement sur l’AST + les métadonnées de signature.

Notes de sécurité

Une signature fournit l’intégrité et l’authentification associées à la clé de signature. Elle ne rend pas à elle seule un document « sécurisé » ou « juridiquement valide », et ne garantit pas non plus la non-répudiation : cela dépend du certificat, de son ancre de confiance, de la protection de la clé et de la politique du vérificateur, tous hors du périmètre de cet outil. Le chiffrement de la charge utile de la clé (enveloppe AES-GCM) protège la confidentialité en transit, pas l’intégrité. Traite la clé privée comme un secret et privilégie l’enveloppe de chiffrement de transport sur tout canal non confidentiel.

Conformité

Énoncé	Spécification	Clause
Le condensé de plage d’octets couvre le fichier et exclut la valeur de signature.	ISO 32000-2	§12.8.1
`Contents` contient le CMS SignedData encodé en DER.	ISO 32000-2	§12.8.1
Pour un horodatage, le hachage de plage d’octets est envoyé à une TSA et le jeton est placé dans `Contents`.	ISO 32000-2	§12.8.5
L’horodatage B-T est un attribut non signé sur SignerInfo.	RFC 5652	§5.3
Les attributs non signés ne modifient pas le condensé signé B-B ni sa validité.	RFC 5652	§5.3
La valeur du signature-time-stamp est un SignatureTimeStampToken.	ETSI EN 319 122-1	§5.3

NextPDF produit la structure de signature. Il n’affirme pas que la signature résultante est conforme ou juridiquement valide : un validateur indépendant en décide. B-LT/B-LTA ne sont pas produits par cet outil.

Contexte commercial

sign_pdf est un outil de niveau Pro, enregistré uniquement lorsque le paquet Pro est résolu au démarrage du serveur. Les niveaux à long terme PAdES (B-LT, B-LTA) et leur matériel de validation (DSS, VRI, LTV) sont réservés à Enterprise et ne sont exposés ni par cet outil ni par cette recette.

Résidence des données & mesures d’atténuation des PII

Le certificat et la clé privée transitent dans la requête. Utilise l’enveloppe AES-GCM transport_encryption sur tout canal qui n’est pas confidentiel de bout en bout. Le PDF signé et l’identité du signataire (signer_name, reason) font partie du contenu du document ; conserve-les donc dans ta frontière de résidence des données. La résidence des données au niveau du déploiement relève de la responsabilité de l’intégrateur.

Télémétrie sûre & nettoyage des journaux

Ne journalise jamais la charge utile private_key, ni la clé ni le nonce AES-GCM, ni le jeton de confirmation. Journalise l’algorithme, le level résultant et signature_count : pas le matériel de clé. L’outil n’émet aucun octet de clé dans son résultat.

Modèle de menaces

Menaces considérées : divulgation de la clé en transit (atténuée par l’enveloppe AES-GCM et le fournisseur TSA injecté par l’hôte, non configurable via la requête) ; un appelant MCP qui pointe l’horodatage vers un point de terminaison arbitraire (empêché — le fournisseur est injecté par l’hôte, non configurable via la requête) ; et altération après signature (le condensé de plage d’octets détecte les modifications). Un modèle de menaces documente les menaces prises en compte et les mesures d’atténuation ; il n’affirme pas l’absence de vulnérabilités.

Comportement en mode FIPS

La sélection de l’algorithme (RSA-SHA256, RSA + SHA-3, Ed25519) est pilotée par la requête ; OpenSSL côté hôte fournit les primitives cryptographiques. Dans un déploiement contraint par FIPS, restreins l’algorithme par politique et appuie-toi sur le module validé de l’hôte. Cet outil n’affirme pas lui-même de validation FIPS.

Disponibilité des transports

Transport	Disponible	Notes
MCP (stdio)	Oui (Pro)	Utilise l’enveloppe de clé AES-GCM sur stdio.
REST	Oui (Pro)	Privilégie TLS avec l’enveloppe de clé.
gRPC	Oui (Pro)	Privilégie TLS avec l’enveloppe de clé.

Niveau de risque HITL

sign_pdf relève de l’Approbation requise (opération destructive et irréversible : l’outil annonce un indice destructif). La barrière de confirmation s’applique comme pour tout outil en Approbation requise. output_pdf vers un fichier relève aussi de l’Approbation requise ; le mode base64 relève de la Revue (niveaux de risque HITL).

Enveloppe JSON de la barrière de confirmation

sign_pdf sans jeton valide renvoie l’enveloppe de défi :

{
  "allowed": false,
  "challenge": "⚠️ CONFIRMATION REQUIRED\n\nOperation: sign_pdf\nDescription: <tool description>\n\nTo proceed, call sign_pdf again with parameter _confirmation_token: \"confirm_<single-use-hex>\"\nExpires in 300 seconds.",
  "token": "confirm_<single-use-hex>"
}

Réappelle l’outil avec _confirmation_token réglé sur le jeton → { "allowed": true }. Flux complet : output-approval.