Avant de pouvoir demander l’horodatage d’un document, assurez-vous que cette fonctionnalité est activée sur votre compte.
Universign exploite une autorité d’horodatage qualifiée et propose deux moyens d’obtenir un horodatage : dans le cadre d’un processus de signature PAdES (ci-dessous), ou sous la forme d’un jeton RFC 3161 autonome pour toute donnée, indépendamment d’un processus de signature (voir Demander un horodatage RFC 3161).
Demander un horodatage PAdES
Pour demander un horodatage, envoyez une requête multipart/form-data à POST /v1/timestamp/pades et transmettez le document dans l’argument file.
Veuillez noter que nous n’acceptons que les formats PDF d’une taille maximale de 25 Mo.
curl
https://api.universign.com/v1/timestamp/pades \
-F [email protected]
La requête renvoie une réponse 200 contenant un horodatage de document PAdES conforme à la norme ETSI TS 119 142-3.
L’accès à cet endpoint nécessite le droit d’usage du service d’horodatage.
Demander un horodatage RFC 3161
L’endpoint RFC 3161 vous permet d’obtenir un jeton d’horodatage pour toute donnée, indépendamment d’un processus de signature : vous envoyez l’empreinte (hash) de votre donnée, vous recevez en retour un jeton signé prouvant que cette donnée exacte existait à cet instant précis. Cet endpoint implémente le protocole standard Time-Stamp Protocol défini par la RFC 3161 : tout outil ou bibliothèque compatible RFC 3161 peut donc construire la requête et vérifier la réponse.
L’accès à cet endpoint nécessite le droit d’usage du service d’horodatage RFC 3161.
Ce que vous pouvez en faire
- Horodater un document sans le signer.
- Prouver la date d’existence de toute donnée à un instant donné - journaux, archives, code source, extraits de base de données.
- Ajouter une date de confiance à un processus piloté par votre propre application.
Votre donnée ne quitte jamais votre système : vous n’en envoyez que l’empreinte.
Envoyer la requête
POST /v1/timestamp/rfc3161
| Authentification | Clé API du workspace |
| Content-Type | application/timestamp-query |
| Accept | application/timestamp-reply |
| Corps de la requête | Un TimeStampReq RFC 3161 encodé en DER |
Le corps de la requête doit être un TimeStampReq binaire contenant :
| Champ | Description |
|---|---|
version |
Toujours 1 |
messageImprint |
L’identifiant de l’algorithme de hachage et l’empreinte de votre donnée |
nonce |
Optionnel. Une valeur aléatoire renvoyée telle quelle dans la réponse, pour se prémunir contre le rejeu |
certReq |
À true pour recevoir la chaîne de certificats dans la réponse. Recommandé - elle est nécessaire pour vérifier le jeton hors ligne |
Algorithmes de hachage supportés :
- SHA-1
- SHA-256
- SHA-384
- SHA-512
Construire une requête avec OpenSSL :
openssl ts -query -data mydocument.pdf -sha256 -cert -out request.tsq
Puis l’envoyer :
curl -X POST https://api.universign.com/v1/timestamp/rfc3161 \
-H "Content-Type: application/timestamp-query" \
-H "Accept: application/timestamp-reply" \
-u "your-api-key:" \
--data-binary @request.tsq \
--output response.tsr
Lire la réponse
Le corps de la réponse est toujours un TimeStampResp encodé en DER, même lorsque la requête est refusée. Il contient :
- un
PKIStatusInfoindiquant le résultat, - lorsque la requête est acceptée, un
TimeStampToken- une structure CMSSignedDatacontenant l’horodatage lui-même et, sicertReqétait àtrue, la chaîne de certificats.
Inspecter la réponse avec OpenSSL :
openssl ts -reply -in response.tsr -text
Erreurs
Le corps de la réponse n’est jamais au format JSON. Chaque résultat, y compris les erreurs, est renvoyé sous la forme d’un TimeStampResp ASN.1. Le statut HTTP indique la catégorie du problème :
| Statut HTTP | Signification | Que faire |
|---|---|---|
200 |
L’horodatage a été accordé | Conserver le jeton |
401 |
Aucun identifiant valide n’a été fourni | Vérifier votre clé API |
403 |
Votre workspace ne dispose pas du droit d’usage du service d’horodatage RFC 3161 | Contacter votre chargé de compte |
400 |
La requête n’a pas pu être lue, ou l’autorité d’horodatage l’a rejetée comme invalide | Vérifier que votre TimeStampReq est bien formé et utilise un algorithme de hachage supporté |
500 |
L’autorité d’horodatage est indisponible ou a renvoyé une réponse inexploitable | Réessayer plus tard |
Dans tous les cas, le PKIStatusInfo de la réponse contient un code PKIFailureInfo et un message en texte libre décrivant la cause.
Vérifier un jeton d’horodatage
Un jeton émis par cet endpoint est un jeton RFC 3161 standard. Vous pouvez le vérifier hors ligne, avec tout outil compatible RFC 3161, à condition d’avoir demandé certReq=true.
Suivre votre consommation
Chaque horodatage accordé compte pour une unité de consommation d’horodatage RFC 3161. Les requêtes refusées - mal formées, non autorisées, ou rejetées par l’autorité d’horodatage - ne sont jamais comptabilisées.
Les horodatages RFC 3161 sont indiqués sur une ligne dédiée de votre rapport de consommation, et sont également inclus dans votre consommation totale d’horodatage, aux côtés des horodatages produits par des processus de signature. Voir Récupérer le rapport de consommation.
