Timestamping service

Timestamp JSON request

You can integrate with our standard API to securely timestamp documents. This functionality allows you to digitally timestamp documents, ensuring integrity and anteriority.

Check the getting started guide to set up your account, API key, and project before making API calls.

Request

• Path parameter:
  • {project_key}: the unique identifier of the project
• Headers:
  • Content-Type: application/json
  • X-API-KEY: YOUR_API_KEY
• Request Body:

{
    "hashAlgorithm": "SHA512",
    "hashedMessage": "YOUR_FILE_SHA512_HASH",
    "certReq": false
}

Ensure that hashAlgorithm specifies a robust algorithm compliant with current standards. hashedMessage should contain the hash of the data intended for timestamping.

ℹ️

It is essential to specify a robust hash algorithm.

The following hash algorithms are supported: "SHA256", "SHA384", "SHA512". SHA256 is the minimum and default requirement, ensuring compliance with current standards.

Response

Upon successful submission, you will receive a JSON response containing the timestamp token and relevant details:

{
    "hashAlgorithm": "SHA512",
    "hashedMessage": "YOUR_FILE_SHA512_HASH",
    "certReq": false
}

Note: The token field in the response contains a Base64-encoded timestamp token, which serves as irrefutable proof of the existence and integrity of the timestamped data at the specified time (timestamp). This token can be used to verify the authenticity of the timestamp. The timestamp field in the response represents the timestamp in milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC).

{
  "status": 0,
  "hashAlgorithm": "2.16.840.1.101.3.4.2.3",
  "hashedMessage": "YOUR_FILE_SHA512_HASH",
  "serialNumber": "1b23d65d7b2cc8cca76795fc805de23888de53f",
  "timestamp": 1704067200000,
  "token": "BASE64_ENCODED_TOKEN",
  "tsaPolicyId": "1.3.6.1.4.1.60053.2.1.1.1.1"
}

Please refer to the Certificates page for more information on published certificates.

Timestamp RFC3161 request

To use the service according to the RFC3161 specifications, you have to create files with OpenSSL or any RFC3161-compliant library. Once created, simply send a timestamp-query file to our service with the proper credentials and headers. If everything is ok, the returned response is a valid timestamp reply binary file that you can parse using openssl or a compliant library.

# Create the request file

openssl ts -query -data data.txt -cert -no_nonce -sha512 -out request.tsq

# Send the file using cURL

curl https://ENVIRONMENT_URL/v2/timestamp/projects/PROJECT_ID \
-X POST \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-type: application/timestamp-query" \
--data-binary "@request.tsq" > reply.tsr

# Check the content of the reply

openssl ts -reply -in reply.tsr -text

# Retrieve the bundled certificates from the trust chain

curl -O http://pub.evidency.io/cer/bundle.pem

# Verify the timestamp token

openssl ts -verify -data data.txt -in reply.tsr -CAfile bundle.pem

# Verification: OK

In-depth Certificate Verification

In the previous example, the openssl "-cert" option indicates the response includes the timestamp unit certificate. You can omit this option and provide the certificate in the openssl verify command.

# Retrieve the certificate trust chain 

curl -O http://pub.evidency.io/cer/root-ca.cer
curl -O http://pub.evidency.io/cer/timestamp-ca.cer
curl -O http://pub.evidency.io/cer/tsu-01.cer

# The certificates are published with DER format, convert them to PEM

openssl x509 -in root-ca.cer -inform DER -outform PEM -out root-ca.pem
openssl x509 -in timestamp-ca.cer -inform DER -outform PEM -out timestamp-ca.pem
openssl x509 -in tsu-01.cer -inform DER -outform PEM -out tsu-01.pem

# Create the bundle with the pem certificates

cat root-ca.pem timestamp-ca.pem > bundle.pem

# Verify the timestamp token

openssl ts -verify -data data.txt -in reply.tsr -CAfile bundle.pem -untrusted tsu-01.pem

# Verification: OK