API reference

The one endpoint of the Timestamping API, with the fields Cleverbase accepts and the values it requires. What the service is for and how the exchange runs is on Timestamping; this page is for looking things up while you write code.

Hosts

Environment	Host
Sandbox	https://tsa.sandbox.uanataca.com/tsa/tss03
Production	https://tsa.uanataca.com/tsa/tss03

Time-stamp request

POST /tsa/tss03

Description

Issues a qualified timestamp token for the hash supplied in the request. The request body is a DER-encoded TimeStampReq and the response body is a DER-encoded TimeStampResp, as specified in RFC 3161 section 2.4 and transported over HTTP as described in section 3.4.

Input headers

Header	Presence	Value	Description
Authorization	REQUIRED	String	Must be of type `Basic`, with the timestamping username and password from Cleverbase.
Content-Type	REQUIRED	`application/timestamp-query`	Media type of the request body.

Input body

A DER-encoded TimeStampReq:

Field	Presence	Type	Description
`version`	REQUIRED	Integer	Must be `1`.
`messageImprint.hashAlgorithm`	REQUIRED	AlgorithmIdentifier	OID of the hash algorithm used. See supported hash algorithms.
`messageImprint.hashedMessage`	REQUIRED	Octet String	Hash of the data to be timestamped. Its length must match the output length of `hashAlgorithm`.
`reqPolicy`	OPTIONAL	OID	Requested timestamp policy. When present, must be `0.4.0.2023.1.1`. When absent, this policy is applied.
`nonce`	OPTIONAL	Integer	Large random value chosen by the client. Echoed unchanged in the token, so the client can match the response to the request and detect replay.
`certReq`	OPTIONAL	Boolean	When `true`, the TSA signing certificate is included in the token. RECOMMENDED for signatures that must be validated offline or in the long term. Default `false`.
`extensions`	OPTIONAL	Extensions	Not supported.

Supported hash algorithms

Algorithm	OID	Hash length (bytes)
SHA-256	`2.16.840.1.101.3.4.2.1`	32

SHA-1 and MD5 are not accepted.

Response: 200 OK

A DER-encoded TimeStampResp with Content-Type: application/timestamp-reply. Note that a 200 OK HTTP status only means the request was processed. The outcome is indicated by status.status in the body.

Field	Presence	Type	Description
`status.status`	REQUIRED	PKIStatus	`0` (`granted`) when the token was issued. See status values for the other values.
`status.statusString`	OPTIONAL	UTF8String	Human-readable explanation of the status.
`status.failInfo`	OPTIONAL	PKIFailureInfo	Reason for failure. Present only when the request was rejected.
`timeStampToken`	CONDITIONAL	ContentInfo	CMS `SignedData` containing the `TSTInfo`. Present only when `status.status` is `0` or `1`.

The TSTInfo inside the token contains:

Field	Type	Description
`version`	Integer	`1`.
`policy`	OID	`0.4.0.2023.1.1`.
`messageImprint`	MessageImprint	Copy of the `messageImprint` from the request. Clients MUST verify it matches.
`serialNumber`	Integer	Unique serial number of the token.
`genTime`	GeneralizedTime	Time at which the token was created, in UTC.
`accuracy`	Accuracy	Accuracy of `genTime`.
`nonce`	Integer	Copy of the `nonce` from the request, present only when a nonce was supplied. Clients MUST verify it matches.
`tsa`	GeneralName	Name of the time-stamping unit that issued the token.

Status values

`status`	Name	Description
`0`	`granted`	Token issued exactly as requested.
`1`	`grantedWithMods`	Token issued with modifications.
`2`	`rejection`	Request rejected. See `failInfo`.
`3`	`waiting`	Not used by this service.
`4`	`revocationWarning`	Not used by this service.
`5`	`revocationNotification`	Not used by this service.

`failInfo` bit	Name	Cause
`0`	`badAlg`	Unsupported or unrecognised hash algorithm.
`2`	`badRequest`	The request is not permitted.
`5`	`badDataFormat`	The request could not be decoded as a `TimeStampReq`, or the hash length does not match the algorithm.
`14`	`timeNotAvailable`	The trusted time source is temporarily unavailable. Retry later.
`15`	`unacceptedPolicy`	`reqPolicy` is not supported.
`16`	`unacceptedExtension`	The request contains an unsupported extension.
`17`	`addInfoNotAvailable`	Requested additional information is not available.
`25`	`systemFailure`	Unexpected internal error.

HTTP error responses

Errors that occur before the request body is processed are returned as HTTP errors without a TimeStampResp body.

Status	Cause
`400`	The `Content-Type` header is not `application/timestamp-query`, or the request body is empty.
`401`	The `Authorization` header is absent or the credentials are invalid.
`500`	Unexpected internal error.

Examples

Create a request (OpenSSL)

# Hash the document with SHA-256 and request the TSA certificate
openssl ts -query -data document.pdf -sha256 -cert -out request.tsq

# Inspect the request
openssl ts -query -in request.tsq -text

Sample request

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>

Send the request (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

Sample response

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

<DER-encoded TimeStampResp>

Inspect and verify the token (OpenSSL)

# Print the token contents
openssl ts -reply -in response.tsr -text

# Verify the token against the original request and the TSA certificate chain
openssl ts -verify -in response.tsr -queryfile request.tsq -CAfile tsa-chain.pem

A successful verification prints Verification: OK. The output of -text shows Status: Granted., the Policy OID, the Hash Algorithm, the Message data, the Serial number, the Time stamp and, when supplied, the Nonce echoed from the request.

Embed the token in a signature

Signature libraries such as Digital Signature Service (DSS), iText, PDFBox or Bouncy Castle accept the host above as an RFC 3161 TSA URL, with the username and password as HTTP Basic credentials. Configure it as the timestamp source for the -T levels of the AdES formats (PAdES-T, XAdES-T, CAdES-T) and for the archive timestamps of the -LTA levels. What each of those levels adds, and why you would go past B-B, is in The PAdES levels.