Signer une empreinte avec l’API v1

Le mode digest transmet une empreinte du document au lieu de son contenu complet. Il nécessite la licence API Premium pour la signature de hash, ainsi que les droits spécifiques convenus pour le format choisi. Votre application reste responsable du calcul et de la conservation des données référencées.

Choisir la route

Le packaging est detached pour ces opérations. Pour XAdES, les autres valeurs éventuellement décrites par le schéma sont refusées par le moteur digest.

Encoder l’empreinte

digest_base64 contient le Base64 des octets binaires de l’empreinte. Pour SHA-256 : 32 octets avant encodage. Il ne contient ni une chaîne hexadécimale de 64 caractères, ni le Base64 de cette chaîne hexadécimale.

import base64
import hashlib
import json
from pathlib import Path

digest = hashlib.sha256(Path("document.bin").read_bytes()).digest()
payload = {
    "certificate_uid": "REMPLACER_PAR_UID_CERTIFICAT",
    "digest_base64": base64.b64encode(digest).decode("ascii"),
    "filename": "document.bin",
    "signature_level": "B-T",
    "packaging": "detached",
    "digest_algorithm": "sha256",
}
Path("demande-digest.json").write_text(json.dumps(payload), encoding="utf-8")

Cet exemple convient à une demande CAdES digest. Envoyez ce JSON à /api/clickncert/v1/digest/cades/sign avec les accès Basic, puis décodez le document_base64 retourné pour obtenir la signature. Conservez document.bin séparément.

filename ou reference_uri doit être renseigné. Les longueurs binaires attendues sont 32, 48 et 64 octets pour SHA-256, SHA-384 et SHA-512. Seul XAdES expose ces trois algorithmes ; les autres formats documentés utilisent SHA-256.

Cas particulier PAdES

flowchart TD
  A["Préparer le PDF et la réserve de signature"] --> B["Calculer le digest du ByteRange"]
  B --> C["API digest PAdES"]
  C --> D["Recevoir le conteneur CMS"]
  D --> E["Insérer dans la réserve sans modifier les octets couverts"]
  E --> F["Valider le PDF assemblé"]
  classDef default fill:#EDF4FF,stroke:#2B61B5,color:#172F55

N’utilisez pas le hash global d’un PDF non préparé pour ce parcours. La préparation du ByteRange et l’insertion du CMS nécessitent une bibliothèque PDF adaptée. La réponse n’est pas un PDF final. Pour recevoir directement le document final, utilisez PAdES document.

Confidentialité et preuve

Ce mode évite le téléversement du contenu original dans la requête de création, mais les métadonnées envoyées restent transmises au service. Choisissez des références métier sobres. Validez ensuite le conteneur avec les données détachées exactes et la politique de confiance appropriée.

Les anciennes routes de signature de hash renvoient une autre structure ; voir Compatibilité legacy.