Timestamping service
How to create a request compliant with RFC 3161 Time-Stamp Protocol (TSP)
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.pemopenssl 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
Updated 26 days ago