In rkrug/ROriginStamp: Interface to OriginStamp API to Obtain Trusted Time Stamps

knitr::opts_chunk$set(
    eval = FALSE,
    echo = TRUE,
    cache = FALSE,
    comment = ""
)
library(ROriginStamp)

valid_key <- openssl::sha1(api_key()) == "4a0b1541d679c18ed81b2ee79052984cd6ab5597"

Prerequisites

Before you can use the package, you have to get an API key from OriginStamp. For details, see their Get an API key documentation.

Installation

ROriginStamp is momentarily only available on github, so you have to install it by using devtools:

if (!require(devtools)) {
  install.packages("devtools")
  library(devtools)
}
if (!require(ROriginStamp)) {
  devtools::install_github("rkrug/ROriginStamp")
  library(ROriginStamp)
}

library(ROriginStamp)

How to use it

Hashing

This package is based on sha256 hashes as calculated by the openssl package by @opensslR as OriginStamp is using sha256 hashes.

The function hash(x) is the workhorse for calculating hashes. It calculates sha256 from files. It returns an object of class hash, which is simply a character vector of length 1 with the class hash assigned.

The hash is calculated when

1. x is a character vector,
2. if the length(x) is one, and
3. x points to an existing file.

If you want to calculate the hash of an character vector of length one which is also a file name to an existing file,

hash(system.file("DESCRIPTION", package = "ROriginStamp"))

returns the hash of the file. This is identical to directly call the hash method which calculates the hash of the file:

hash_file(system.file("DESCRIPTION", package = "ROriginStamp"))

Provide API Key to the Functions

If you want to do anything more than hashing with this package, you have to register with OriginStamp and get an API key. You can register for a free account and still use all the functionality of this package. To get an API key is described in the Get an API key section of the documentation.

To make this key available to the package, you have to

1. either set it as an environmental variable, by e.g. using

Sys.setenv(ROriginStamp_api_key = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")

or

1. use the api_key() function to set the api key by running

api_key("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")

or

1. specify it in each call by using the key argument.

get_key_usage() - Getting infomation about your OriginStamp account

To get the key usage statistics is accomplished by using

get_key_usage()

This gives an overview over your usage of your credits. The actual numbers depend on the plan you are on and the number of credits used already.

For a detailed description of the return value see the Default«UsageResponse» in the models section of the API documentation.

get_currencies() - Getting infomation about your OriginStamp account

OriginStamp can work with different blockchain based currencies. The list of the currencies supported can be retrieved by using

get_currencies()

For a detailed description of the return value see the DefaultOfListOfCurrencyModel in the models section of the API documentation.

create_timestamp() - Create a new timestamp

Let's create a new timestamp.

As an example, let's create a dummy file contining a data.frame with 26 random numbers, to make sure, that the hash has not been timestamped by OriginStamp already.

tf <- tempfile()
write.csv(data.frame(letters, LETTERS, 1:26, runif(26)), tf)

create_timestamp(
  x = tf, 
  comment = "This is a dummy test for creating a timestamp."
)

Now let's submit the same hash again and see what happens:

create_timestamp(
  x = tf, 
  comment = "This is a dummy test for creating a timestamp a second time."
)

The difference is in $content$data$created which is TRUE when the submitted hash has not been timestamped already and subsequently created, and FALSE when it already exists. This is an easy way to check if the submission was successful.

It is important to note, that the timestamps are not created immediately, but put in a cue, which is submitted at certain intervals, depending on the currency used. See the documentation on currencies for details.

get_hash_status() - Getting the status of a submitted hash

Let's get information about the status of some hashes submitted. We start with the status of the just submitted hash of obj

get_hash_status(
  x = tf
)

Now lets look at the status of a hash submitted in the past and which is already processed and timestamped:

get_hash_status(
  x = as.hash("2c5d36be542f8f0e7345d77753a5d7ea61a443ba6a9a86bb060332ad56dba38e")
)

The difference is in $content$data$timestamps which is in the case of a submitted hash but not yet created timestamp an essentially empty table, while in the case of a created timestamp, a table lie=sting the timestamp information.

But this information is neither particularly useful, nor userfriendly if one wan's to proof the timestamp. For this, let's move the final command.

get_proof() - Downloading proof of a created timestamp

The structure of the command is very similar to the previous one, only that one can specify the type of the proof. This can be either in the form of a pdf file (a 'certificate'), or as an xml file (a 'proof').

get_proof(
  x = as.hash("2c5d36be542f8f0e7345d77753a5d7ea61a443ba6a9a86bb060332ad56dba38e"), 
  proof_type = "pdf"
)

or

get_proof(
  x = as.hash("2c5d36be542f8f0e7345d77753a5d7ea61a443ba6a9a86bb060332ad56dba38e"), 
  proof_type = "xml"
)

The function returns an object containing the url where the document can be downloaded ($content$data$download_url) which is automatically processed further and the document is downloaded. As file name, the argument file is used. If it is not provided, the file name in the return value is used, which is of the format \code{proof.CURRENCY.HASH.xml} for \code{proof_type == "xml"} or \code{certificate.CURRENCY.HASH.pdf} for \code{proof_type == "pdf"}

To see the downloaded files, click here for the pdf or here for the xml.

References

rkrug/ROriginStamp documentation built on Aug. 16, 2022, 5:45 p.m.