Trusted Timestamp design

This document describes the overall design of our Trusted Timestamp.

Basics

Trusted Timestamps from TimestampIt! are plain text UTF-8 files. They are designed to be both human readable and easy to parse in any programming language. They are always two lines, with the first line having all the fields/data, and the second line being the signature of the first line. The final field on the first line is the "ext" field which is a place for any user defined data thus allowing for extensibility and a wide variety of applications.

Example

Trusted Timestamps from TimestampIt! look like this:

1.0|5zjs99o2lq09|2024-08-02T17:45:13Z|sha256|9cdb1e33a011491a5ebd140fa094f6cd88652dfd148df5feceb9ca0c77aa4e19|https://timestampit.com/key/a0d3cua1993r|filename: Real-World_Cryptography.pdf; size: 35235089; creator: bob
5oz3OSkRzdfMB2L5e94LTPoMhmwG02yfa3kt07rkpKGskPNb3ZA9gV0goi+tOoIS4WjfXC7IkjYmilvGDlCJDw==

Message

The first line is the "message":
1.0|5zjs99o2lq09|2024-08-02T17:45:13Z|sha256|9cdb1e33a011491a5ebd140fa094f6cd88652dfd148df5feceb9ca0c77aa4e19|https://timestampit.com/key/a0d3cua1993r|filename: Real-World_Cryptography.pdf; size: 35235089; creator: bob


The message is always one single line.

It is a list of fields separated by '|' (pipe) characters. The fields are described below.

Signature

The second line is the "signature" of the first line:
5oz3OSkRzdfMB2L5e94LTPoMhmwG02yfa3kt07rkpKGskPNb3ZA9gV0goi+tOoIS4WjfXC7IkjYmilvGDlCJDw==


The signature is used to verify that the message has not been altered. If any character or field is changed on the message line, then the Trusted Timestamp will fail verification.

Similarly, if the signature is changed, the Trusted Timestamp will fail verification.

The only way for a Trusted Timestamp to successfully verify is for the Trusted Timestamp to be completely unaltered from what was created and delivered by TimestampIt!.

ED25519 implementation

We use the ED25519 digital signature algorithm, as specified by RFC8032, for our Trusted Timestamps. We are currently using the Supercop ref10 implementation for signing via the ed25519 RubyGem.

Fields

Version

This denotes the version of the Trusted Timestamp format. In the future, we may adjust the design and format of Trusted Timestamps, and in doing so this version number will be increased. For now there is only one version: 1.0.

ID

Every Trusted Timestamp has a unique ID. These IDs are random and non-sequential. They are currently 12 characters in length consisting of characters [0-9a-z].

Timestamp

This is the time at which the Trusted Timestamp was created. This timestamp is formatted per RFC3339. Timestamps are always in Universal Coordinated Time (UTC).

Hash algorithm

This is the algorithm which the underlying file was hashed with. When creating a Trusted Timestamp, you do not send in the actual file you want timestamped. Instead, you "hash" the file and send in the resulting "hash digest". This preserves the privacy of your files since they are never sent to the TimestampIt! server.

See the /create API docs for a list of valid values for hash algorithm.

Hash Digest

This is the hash of the underlying file.

When verifying a Trusted Timestamp against a file, one should hash the file using the algorithm from the Trusted Timestamp, and compare the resulting hash digest to the one in the Trusted Timestamp. If they match, then you have the same file against which the Trusted Timestamp was created.

Verification key URL

This is the URL at which you can obtain the official verification key for the Trusted Timestamp.

The final part of the URL is the Key ID. This ID can be used to retrieve the key from a trusted backup source such as our official verification key repo. This allows for the verification of Trusted Timestamps in the event the TimestampIt! website is not functioning or has ceased to exist.

Extended data

This is optional field. Users can put anything they like in here*, up to 1 KB of text (1024 characters).

Users can add data that allows for extended verifications or for any other purpose.

For example, if one is created Trusted Timestamps for images, one could put the PDQ image hash into the ext field to enable detection of cropped images based on an original.

*This field may not contain any '|' or newline ('\n') characters.