Main navigation

Who was first: 2 using OriginStamp via its RESTful interface

Paw makes it easy to supply the SHA-256 digest in JSON format.

My first article of this pair showed how creatives and anyone else who needs to prove the time of creation of a document can do so, at no cost or complexity, using Bela Gipp’s OriginStamp service. This second explores how this works in more detail, and how it can be accessed using its API.

There is further information about using RESTful APIs and Paw in this article, and more about timestamping systems in Wikipedia.

OriginStamp is based on a combination of two mechanisms.

One is the creation of a hash key, which is a unique identifier for the document. The regular method uses the SHA-2 algorithm to generate a 256-bit hash value (digest), often known as SHA-256. This is the standard digest used in the Bitcoin system, and should be ample for this purpose.

The other mechanism is the incorporation of that digest into the public distributed ledger of the Bitcoin currency system, its block chain, in a timed transaction. Because of the systems in place to ensure the integrity of the block chain, notably its incorporation of digests of sections of the block chain, this forms a robust and public record of the document’s digest, associated with the transaction time.

This is an imaginative and extremely elegant use of existing tools to solve a common problem.

Obtaining an authorisation token

You need an authorisation token from the OriginStamp API page before you can use its RESTful API.

The first step before you can start using OriginStamp’s API is to obtain a key, which will be good for a million stamps. Do this in the Setup section of the API Documentation. Copy and save the SHA-256 digest which it provides, as you will need to supply that authorisation token when you use the RESTful interface. In the code below, I will substitute a string of a characters for my token.

Creating a stamp

You do this using a POST method, supplying either a digest for the document which you wish to stamp, or the raw document content. As OS X includes OpenSSL, which can readily produce SHA-256 and many other digests, it is more efficient to create the digest locally, using a shell command of the formopenssl dgst -sha256 filename
which returns a result similar to the followingSHA256(filename)= 957a6e55a72c516a734fe53236dcc97880c9999d558939db5745395765cf4263

We then supply that digest as the data for the key hash_sha256. You do not have to use a SHA-256 digest, but that is probably the best choice for robustness.

Using POST to create a stamp for a document’s SHA-256 digest.

The actual POST command in HTTP format should then read something like

Send this, and you should receive a 200 OK response containing 5 items, the original SHA-256 digest as confirmation, a created_at timestamp such as 2015-07-19T11:00:04.566Z, and an identical updated_at timestamp.

Of course you cannot insert the digest or timestamp into the original document, as that would alter the digest and invalidate the timestamp. Probably the best solution to attaching these to the document is in its metadata, and you should ensure that the original document file is then securely locked.

Retrieving a stamp

Given the digest of any document for which you have created a stamp, it is simple to query OriginStamp to return its timestamp using a GET method thus: