API reference

Het ene endpoint van de Timestamping-API, met de velden die Cleverbase accepteert en de waarden die het vereist. Waar de dienst voor is en hoe de uitwisseling verloopt staat op Timestamping; deze pagina is om in op te zoeken terwijl je code schrijft.

Hosts

Omgeving	Host
Sandbox	https://tsa.sandbox.uanataca.com/tsa/tss03
Productie	https://tsa.uanataca.com/tsa/tss03

Timestamp-verzoek

POST /tsa/tss03

Omschrijving

Geeft een gekwalificeerd timestamp-token uit voor de hash in het verzoek. De request body is een DER-gecodeerde TimeStampReq en de response body een DER-gecodeerde TimeStampResp, zoals gespecificeerd in RFC 3161 sectie 2.4 en over HTTP vervoerd zoals beschreven in sectie 3.4.

Input headers

Header	Aanwezigheid	Waarde	Omschrijving
Authorization	REQUIRED	String	Moet van het type `Basic` zijn, met de timestamping-gebruikersnaam en het wachtwoord van Cleverbase.
Content-Type	REQUIRED	`application/timestamp-query`	Mediatype van de request body.

Input body

Een DER-gecodeerde TimeStampReq:

Veld	Aanwezigheid	Type	Omschrijving
`version`	REQUIRED	Integer	Moet `1` zijn.
`messageImprint.hashAlgorithm`	REQUIRED	AlgorithmIdentifier	OID van het gebruikte hash-algoritme. Zie ondersteunde hash-algoritmes.
`messageImprint.hashedMessage`	REQUIRED	Octet String	Hash van de gegevens die een timestamp krijgen. De lengte moet overeenkomen met de uitvoerlengte van `hashAlgorithm`.
`reqPolicy`	OPTIONAL	OID	Gevraagde timestamp policy. Als die meegestuurd wordt, moet het `0.4.0.2023.1.1` zijn. Zonder deze waarde wordt diezelfde policy toegepast.
`nonce`	OPTIONAL	Integer	Grote willekeurige waarde, gekozen door de client. Komt onveranderd terug in het token, zodat de client het antwoord aan het verzoek kan koppelen en replay ziet.
`certReq`	OPTIONAL	Boolean	Bij `true` zit het ondertekencertificaat van de TSA in het token. AANBEVOLEN voor handtekeningen die offline of op lange termijn gevalideerd moeten worden. Standaard `false`.
`extensions`	OPTIONAL	Extensions	Niet ondersteund.

Ondersteunde hash-algoritmes

Algoritme	OID	Hash-lengte (bytes)
SHA-256	`2.16.840.1.101.3.4.2.1`	32

SHA-1 en MD5 worden niet geaccepteerd.

Antwoord: 200 OK

Een DER-gecodeerde TimeStampResp met Content-Type: application/timestamp-reply. Let op: een HTTP-status 200 OK betekent alleen dat het verzoek verwerkt is. De uitkomst staat in status.status in de body.

Veld	Aanwezigheid	Type	Omschrijving
`status.status`	REQUIRED	PKIStatus	`0` (`granted`) als het token is uitgegeven. Zie statuswaarden voor de rest.
`status.statusString`	OPTIONAL	UTF8String	Uitleg van de status, leesbaar voor mensen.
`status.failInfo`	OPTIONAL	PKIFailureInfo	Reden van het mislukken. Alleen aanwezig als het verzoek is afgewezen.
`timeStampToken`	CONDITIONAL	ContentInfo	CMS `SignedData` met de `TSTInfo` erin. Alleen aanwezig als `status.status` `0` of `1` is.

De TSTInfo in het token bevat:

Veld	Type	Omschrijving
`version`	Integer	`1`.
`policy`	OID	`0.4.0.2023.1.1`.
`messageImprint`	MessageImprint	Kopie van de `messageImprint` uit het verzoek. Clients MOETEN controleren dat die overeenkomt.
`serialNumber`	Integer	Uniek serienummer van het token.
`genTime`	GeneralizedTime	Het moment waarop het token is gemaakt, in UTC.
`accuracy`	Accuracy	Nauwkeurigheid van `genTime`.
`nonce`	Integer	Kopie van de `nonce` uit het verzoek, alleen aanwezig als er een nonce is meegestuurd. Clients MOETEN controleren dat die overeenkomt.
`tsa`	GeneralName	Naam van de time-stamping unit die het token heeft uitgegeven.

Statuswaarden

`status`	Naam	Omschrijving
`0`	`granted`	Token uitgegeven precies zoals gevraagd.
`1`	`grantedWithMods`	Token uitgegeven met aanpassingen.
`2`	`rejection`	Verzoek afgewezen. Zie `failInfo`.
`3`	`waiting`	Wordt door deze dienst niet gebruikt.
`4`	`revocationWarning`	Wordt door deze dienst niet gebruikt.
`5`	`revocationNotification`	Wordt door deze dienst niet gebruikt.

`failInfo`-bit	Naam	Oorzaak
`0`	`badAlg`	Niet-ondersteund of onbekend hash-algoritme.
`2`	`badRequest`	Het verzoek is niet toegestaan.
`5`	`badDataFormat`	Het verzoek kon niet als `TimeStampReq` gedecodeerd worden, of de hash-lengte past niet bij het algoritme.
`14`	`timeNotAvailable`	De vertrouwde tijdsbron is tijdelijk niet beschikbaar. Probeer het later opnieuw.
`15`	`unacceptedPolicy`	`reqPolicy` wordt niet ondersteund.
`16`	`unacceptedExtension`	Het verzoek bevat een niet-ondersteunde extension.
`17`	`addInfoNotAvailable`	De gevraagde aanvullende informatie is niet beschikbaar.
`25`	`systemFailure`	Onverwachte interne fout.

HTTP-foutantwoorden

Fouten die optreden voordat de request body verwerkt is, komen terug als HTTP-fout zonder TimeStampResp in de body.

Status	Oorzaak
`400`	De `Content-Type`-header is niet `application/timestamp-query`, of de request body is leeg.
`401`	De `Authorization`-header ontbreekt, of de credentials zijn ongeldig.
`500`	Onverwachte interne fout.

Voorbeelden

Een verzoek maken (OpenSSL)

# Hash het document met SHA-256 en vraag het TSA-certificaat op
openssl ts -query -data document.pdf -sha256 -cert -out request.tsq

# Bekijk het verzoek
openssl ts -query -in request.tsq -text

Voorbeeldverzoek

POST /tsa/tss03 HTTP/1.1
Host: tsa.uanataca.com
Authorization: Basic <base64(username:password)>
Content-Type: application/timestamp-query
Content-Length: 59

<DER-encoded TimeStampReq>

Het verzoek versturen (curl)

curl --silent --fail \
  --user "<username>:<password>" \
  --header "Content-Type: application/timestamp-query" \
  --data-binary @request.tsq \
  --output response.tsr \
  https://tsa.uanataca.com/tsa/tss03

Voorbeeldantwoord

HTTP/1.1 200 OK
Content-Type: application/timestamp-reply

<DER-encoded TimeStampResp>

Het token bekijken en verifiëren (OpenSSL)

# Toon de inhoud van het token
openssl ts -reply -in response.tsr -text

# Verifieer het token tegen het oorspronkelijke verzoek en de TSA-certificaatketen
openssl ts -verify -in response.tsr -queryfile request.tsq -CAfile tsa-chain.pem

Bij een geslaagde verificatie verschijnt Verification: OK. De uitvoer van -text toont Status: Granted., de Policy OID, het Hash Algorithm, de Message data, het Serial number, de Time stamp en, als die is meegestuurd, de Nonce uit het verzoek.

Het token in een handtekening opnemen

Handtekeningbibliotheken zoals Digital Signature Service (DSS), iText, PDFBox of Bouncy Castle accepteren de host hierboven als RFC 3161-TSA-URL, met de gebruikersnaam en het wachtwoord als HTTP Basic-credentials. Stel die in als tijdstempelbron voor de -T-niveaus van de AdES-formaten (PAdES-T, XAdES-T, CAdES-T) en voor de archieftijdstempels van de -LTA-niveaus. Wat elk van die niveaus toevoegt, en waarom je verder zou gaan dan B-B, staat in De PAdES-niveaus.