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

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 form
openssl dgst -sha256 filename
which returns a result similar to the following
SHA256(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.

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

POST /api/stamps HTTP/1.1
Authorization: Token token="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
Content-Type: application/json
Host: www.originstamp.org
Connection: close
User-Agent: Paw/2.2.2 (Macintosh; OS X/10.10.4) GCDHTTPRequest
Content-Length: 82
{"hash_sha256":"957a6e55a72c516a734fe53236dcc97880c9999d558939db5745395765cf4263"}

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:

GET /api/stamps/957a6e55a72c516a734fe53236dcc97880c9999d558939db5745395765cf4263 HTTP/1.1
Authorization: Token token="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
Host: www.originstamp.org
Connection: close
User-Agent: Paw/2.2.2 (Macintosh; OS X/10.10.4) GCDHTTPRequest

Send this, and you should receive a 200 OK response containing 5 items, the original SHA-256 digest as confirmation, and its created_at and updated_at timestamps.

The API also details:

• a GET method to search for and return multiple timestamps,
• a GET method to return transaction records on given dates,
• a GET method to return a single transaction record.

As ever, these are easy to explore using Paw, which can then generate code for each in a range of languages including Python and Swift.

Fuller technical details of OriginStamp are here.