Trusted Timestamp verification

This document describes the principles of verifying a Trusted Timestamp.

We do offer examples of basic verification in our example clients repo.

Overview

Trusted Timestamps are always created against a file or some data.

Verifying Trusted Timestamps is similarly done against a file or data. When Verifying a Trusted Timestamp, you are verifying whether the verification file is the same file against which the Trusted Timestamp was created.

Verification involves a set of steps. If any step fails, then verification fails. If all steps pass, then the Trusted Timestamp is verified, and the verification file is known to have existed at the time of the Trusted Timestamp.

Steps

Steps do not necessarily need to happen in a specific order. Your application may dictate that a particular ordering of steps is better or worse.

Compare the hash digests

In this step, the verification file is hashed using the same algorithm as in the Trusted Timestamp (sha256 / sha512 etc.).

If the resulting hash digest matches the one from the Trusted Timestamp then this step passes (the verification file is the same file against which the Trusted Timestamp was created).

If the resulting hash digest does not exactly match, then verification fails. This is not the same file against which the Trusted Timestamp was created.

Verify the signature of the Trusted Timestamp

In this step we are ensuring the Trusted Timestamp is an authentic Trusted Timestamp that was produced by TimestampIt!. If signature verification fails, then the Trusted Timestamp is likely a forgery with some data altered from what was created by TimestampIt!.

To verify a signature:

Step 1: Split the Trusted Timestamp by line. The first line is the message, the second line is the signature. Caution: strip newlines from the message and the signature when splitting them out. Signature verification will fail if the message ends with a newline.

Step 2: Acquire the verification key from a trusted source. The verification key URL is a field in the message and it looks like: https://timestampit.com/key/a0d3cua1993r.

The best way to get the key is to simply execute a GET https://timestampit.com/key/a0d3cua1993r.

You can also get the key from our official backup key repo by using the key ID which is the final part of the path (a0d3cua1993r in this case).

Step 3: Using the message, the signature, and the key, perform an ED25519 signature verification. There are many implementations available to do this. Any correct and standard ED25519 implementation will work.

To perform a verification with openssl which is widely available, use a command like this one:

openssl pkeyutl \
  -verify -pubin \
  -inkey "$key_filename" \
  -rawin -in "$message_file" \
  -sigfile "$signature_file"

Step 4: Optional: Compare the activation and retirement timestamps of the verification key and ensure the timestamp falls in between them. These timestamps are available in the keychain, or in the JSON representation of the key (see API docs).

Perform any custom verifications using the ext field.

If all the above verification steps have passed, then verification has generally succeeded and we have assurance that the verification file is the exact same file that was the Trusted Timestamp was created against. We know this file has existed since at least the timestamped time.

Users may add additional data into the ext field, and use that data in any way they want. For example, you include data about the filename and verify the verification file has the same filename as was recorded in the Trusted Timestamp.