Evidency Documentation

Overview

Welcome to Evidency, your trusted partner in timestamping and sealing services. Here's a brief introduction to our key offerings:

Timestamping: Evidency provides a certified timestamping service that allows you to create irrefutable proof of the existence and integrity of your digital documents. By timestamping your files using our API, you can ensure they are legally recognized and protected against tampering.

Sealing: Our sealing service enables you to digitally seal PDF documents, enhancing their integrity and authenticity. With Evidency, you can securely seal your PDF files to ensure they remain unchanged over time, suitable for legal and compliance purposes.

Explore our developer documentation to learn how to integrate these powerful features into your applications seamlessly. Get started with Evidency today to enhance the security and reliability of your digital assets.

For more information, visit Evidency.

Getting started

  • Create an account on the Evidency Portal
  • Subscribe and activate your account by contacting the customer service team at contact@evidency.io
  • Generate an API key from the account settings
  • Create a project and retrieve it's project_key
  • Request the API

Environments

Evidency provides a sandbox and a production environment.

Sandbox Environment

This environment is intended to test and validate any changes made to your application before it goes live in production.

Portal URL: 

https://app-sandbox.evidency.io/

API URL: 

https://api-sandbox.evidency.io/

Production Environment (eIDAS)

This environment is eIDAS-compliant, providing both timestamp tokens and digital seals.

Portal URL: 

https://app.evidency.io

API URLs 

https://api.evidency.io/
https://api2.evidency.io/

Timestamping

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

Request

  • Endpoint: /v2/timestamp/projects/{project_key}
  • Method: POST
  • Path parameter:
    • {project_key}: the unique identifier of the project
  • Headers:
    • Content-Type: application/json
    • X-API-KEY: YOUR_API_KEY
  • Request Body: 
    {
    "hashAlgorithm": "SHA-512",
    "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.

Response

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

{
    "hashAlgorithm": "SHA-512",
    "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).

Sealing

You can integrate with our standard API to securely seal PDF files. This functionality allows you to digitally seal PDF documents for integrity and authenticity.

Request

To seal a PDF file with the V2 API, send a POST request to the sealing endpoint (/v2/projects/{project_key}/seal) with the following details:

  • Endpoint: /v2/seal/projects/{project_key}
  • Method: POST
  • Path parameter:
    • {project_key}: the unique identifier of the project
  • Headers:
    • Content-Type: multipart/form-data
    • X-API-KEY: YOUR_API_KEY
  • Request Body: a pdf file within the form-data parameter file

Response

Upon successful sealing, you will receive a response containing the sealed PDF file in the file form param.

Try it out

Download service's OpenApi specification

Code examples

Timestamp JSON request

The JSON API is meant to simplify the creation of timestamp tokens. It is based on the RFC3161 protocol but uses JSON documents instead of binary files. At the very minimum, you can send the hash of the file you want to timestamp along with the algorithm used.

Example:

curl -v -X POST https://ENVIRONMENT_URL/v1/timestamp/request \
-H "Accept: application/json" \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"hashedMessage": "YOUR_FILE_SHA512_HASH", "hashAlgorithm": "SHA512"}'

Parameters:

  • hashAlgorithm: (String) hash algorithm used to produce the 'hashedMessage' (both the common name and the OID dot notation are accepted)
  • hashedMessage: (String) hash of the timestamped data
  • certReq: (Boolean) flag indicating if the timestamp token should include the timestamp authority's certificate.

Response:

{
"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"
}

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.

Example (Bash):

# 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/v1/timestamp/request \
-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 Please refer to the following links for more information on published certificates : On the sandbox environment, you can use the following certificates: