REST Interface

All requests are made via HTTP GET or POST parameters, and the server always answers with XML

All requests to the server contain

version=1
This is the interface-version, let's start with one here

pt=xyz
This is the command that we want to execute at the server. If several commands need to be executed with one request, then just chain those pt=xyz&pt=abc.

pre=myprefix
This are the prefixes to all command-parameters that I wanna use for this request. If there are e.g. 3 commands issued at once, than there also need to be 3 different pre parameters.

Example-Request

<a href=“http://publictimestamp.org/?pt=search&filename=vim” class=“external free” title=“http://publictimestamp.org/?pt=search&filename=vim” rel=“nofollow”>http://publictimestamp.org/?pt=search&filename=vim</a>

or with 2 commands in one request:

<a href=“http://publictimestamp.org/?pt=search&pre=myone&myonefilename=vim&pt=search&pre=mysecond&mysecondfilename=emacs” class=“external free” title=“http://publictimestamp.org/?pt=search&pre=myone&myonefilename=vim&pt=search&pre=mysecond&mysecondfilename=emacs” rel=“nofollow”>http://publictimestamp.org/?pt=search&pre=myone&myonefilename=vim&pt=search&pre=mysecond&mysecondfilename=emacs</a>

All answers from the server contain

publictimestamp
our root xml tag, enclosing the complete xml-answer

pt
each executed command creates its own command sub-tree. Depending on the command itself, this contains all the response for this one.

command-name
repeats the executed command in the answer. this is a child within command

params
a child within each command-subtree repeats the request for this command incl. all parameters

params-prefix
the used prefix for this command

return-value
the return-code

return-description
the return-code description

return
enclosing the command-specific xml-answer

<?xml version=“1.0” encoding=“ISO-8859-1”?>
the encoding

<?xml-stylesheet type=“text/xsl” href=“transform.xsl”?>
the XSLT link, enabling browsers to make a website out of this xml

version
the version-number of the interface that created the response

latest-version
the latest available interface-version

too-old-version
this version is too old and should be upgraded as soon as possible (mostly due to security reasons)

timestamps-total
quick statistics for total number of timestamps

timestamps-today
quick statistics for number of today's new timestamps

return values

1
invalid or missing parameters

2
unknown command

XML Blocks

All XML-Answers are combinations of these xml-blocks

basic structure

<?xml version="1.0" encoding="ISO-8859-1"?>
<?xml-stylesheet type="text/xsl" href="transform.xsl"?>

<publictimestamp>

  <xsltpassthrough2/>
  <xsltpassthrough>homepage</xsltpassthrough>
  
  <pt>
    <return>
      .. command specific part
    </return>
    <params>
      .. all detected parameters
    </params>
    <return-description/>
    <return-value/>
    <params-prefix></params-prefix>
    <command-name>search</command-name>
  </pt>

</publictimestamp>

ptb

<ptb>
        <tstamp>2007-04-12 15:00:03</tstamp>
        <ptid>72</ptid>
        <last_ptid>71</last_ptid>
        <first_ptid>71</first_ptid>
        <id>68</id>
</ptb>

ptid

<ptid>
        <ripemd320>5B18C925912D43CB5B6E7B9BB3714FAC2807E89CF83EF5387CE7FFFDD386EB808F9FE225C06BE254</ripemd320>
        <ripemd256>9FFC89E8C2DB90A5FC89DE254D1E924711C53D12403D549D6A6D9FFE67417F39</ripemd256>
        <whirlpool2>4C7FE9B48CD2AA69CE9300017911B3CFC52358052B320BE6C255A3BE1C8C87A0BD119787FDB6F979BF4E9B980C64C6B8FBE0C11E0A7D47D5A0C7275ADCFEA81E</whirlpool2>
        <whirlpool0>78466D1CF7D83A776B109F2581AF256E2561677AB4FBC7CF5A08C83F66D5BA86BA20C0D3CC087F53BF420AFB6ADAF60EAC464662CDB612A8E8B493FBF7F40A55</whirlpool0>
        <tiger2>3FF9B848425933237087D4BCF92C0A065DDEAA1FAF1645F4</tiger2>
        <tiger160>B3A05C67BCF152639765370873AF9949AD8B3EDC</tiger160>
        <tiger128>B3A05C67BCF152639765370873AF9949</tiger128>
        <sha224>0E15AC08F56C60EB8F357D468218B9009E59CD4977B6294CBBA76C2D</sha224>
        <sha0>D628C7052EBF25442798389228A288623480A213</sha0>
        <sha160>51CE7693564D88A90CD702397E06CE1E62BA02FB</sha160>
        <fcs32>FB109ADE	2157</fcs32>
        <md5sum>9B59B20315853FD4B272C3E00C46DD1A</md5sum>
        <cksum>72C52F1D	2157</cksum>
        <adler32>79510CB3	2157</adler32>
        <crc32mpeg2>D69E012F	2157</crc32mpeg2>
        <sha256>158DBD0D834F957EDB20E223EC912BF7FCADA05BE1475EB94EECE8442BA8A2D7</sha256>
        <sha384>4298FE9F4FEDD6B82AEF273A14585C38B0C096E8D2EC661DDA539006AE27689B7A7BC535502248000EAD83E4D2A8B366</sha384>
        <sha512>59AAC8E1B2B255C1359BEDDB51FDE50AF62E3D53E0A85B33E37C88B520E8435012A89CEBBD9A76E5226D235462D7FA06F7D65FDDF79B3CE0691723359880FE44</sha512>
        <tiger>B3A05C67BCF152639765370873AF9949AD8B3EDC366B1ED7</tiger>
        <haval>B239F85B890D696D3241504A90BB298D</haval>
        <crc16>D35A	2157</crc16>
        <ripemd160>73F3BD294B09F159A021B01D1F92574D394B60D5</ripemd160>
        <ripemd128>B9FF8EE4289EBE681284E5D13EFD03A2</ripemd128>
        <whirlpool>21BE3FC65F7CC80883AEB23994F6C3FEEFD1A109DCD1C7607B1A8828E380D85990C38DD67B892D79C8C0D1EF52A44B0B3B1D6831C7EE5E32244F477F8CF3EBB4</whirlpool>
        <crc64>7E41CDE62147393D	2157</crc64>
        <md4sum>158F06F68B8FACAFAFE6C8C1C1896DF4</md4sum>
        <md2sum>D2520D3C2DF65DD7BA2882C2534C7B6D</md2sum>
        <elf32>02CF71DA	2157</elf32>
        <fcs16>7EC8	2157</fcs16>
        <sum32>00020C94	2157</sum32>
        <filesize>2157</filesize>
        <ptid>72</ptid>
</ptid>

ptid_info

<ptid_info>
        <info_show>0</info_show>
        <reported>0</reported>
        <documenttype>3</documenttype>
        <filename>PTB-68</filename>
        <url>http://publictimestamp.org/ptb</url>
        <project_name></project_name>
        <person></person>
        <homepage>http://publictimestamp.org</homepage>
        <email></email>
        <document_title>Public Timestamp Block 68</document_title>
        <ptid>72</ptid>
</ptid_info>

documenttype
1 = source code
2 = object code (executable)
3 = text (website, text document, open office file)

Functions

search_ptid_info

Allows to search for ptid_info entries.

pt=search_ptid_info
name of this command

offset=0
optional, skips the first # of results

count=10
optional, sets the max number of returned results

Just use whatever you want to search for:

ptid
document_title
homepage
project_name
url
filename
documenttype
reported
info_show

boolean=and
default is and, can be 'and', 'or', 'xor', 'nand', etc.

search_ptid_hash

Allows to search for ptid_info entries by hash-value or filesize.

pt=search_ptid_hash
name of this command

algorithm
name of hash-algorithm to compare for. special case: 'filesize'
one of

 'filesize',
 'sum32', 'fcs16', 'elf32', 'md2sum', 'md4sum', 'crc64',
 'whirlpool', 'ripemd128', 'ripemd160', 'crc16', 'haval',
 'tiger', 'sha512', 'sha384', 'sha256', 'crc32mpeg2',
 'adler32', 'cksum', 'md5sum', 'fcs32', 'sha160', 'sha0',
 'sha224', 'tiger128', 'tiger160', 'tiger2', 'whirlpool0',
 'whirlpool2', 'ripemd256', 'ripemd320')

hashvalue
the hash-value to search (must be at least 5 chars long, only hex-numbers allowed)

This function returns ptid_info blocks, even if it compares the values in the ptid table. This is because this seems to be the more convenient way to use this.

search_ptid

Allows to search for one exact ptid

pt=search_ptid
name of this command

ptid
the ptid

returns the ptid info incl. all hash-values, the corresponding ptid_info blocks as well as the ptb info

search response

<pt>
   <command-name>search_ptid_info</command-name>
   <params>
     .. list of used parameters
   </params>
   <return-value>0</return-value>
   <return-description>OK</return-description>
   <return>
      .. list of ptid_info blocks
   </return>
</pt>

gettimestamp

Returns details to one specific timestamp.

getptb

Returns details to one specific PTB

getlatestptb

Special command to easy optain latest PTB

returns:

ptb
ptid of latest ptb
ptid_info of latest ptb

addtimestamp

Allows a user to submit new Hash-Values and Meta-Information. This is the command to actually timestamp a file.

Parameters:

meta-information as required for ptid_info
hash-values as required for ptid

Addresses

To make this service as reliable as possible, several precautions should be addressed. This section defines some addresses, to make this goal at least as easy as possible.

Web-Site

OK, the web-site itself is not one of the things I would consider as important for high availability.

REST Interface

Jupp, this is important, as we don't want to distract people that actually try to upload the hashes of a file! We also don't want to have any problems with automated timestamping (as e.g. by sf.net).

Well defined interface address

Well defined interface address, but slightly different for each version

http://publictimestamp.org/rest/v1.0/publictimestamp-rest-v1.0.pl - this is for version 1.0, other version-numbers work accordingly

Testing-Interface

For testing purposes, there should be a well-defined testing-interface. It should also have a database backend (but which might e.g. be deleted once a day) to fully try and test all features of this service without being able to damage anything or to bloat the nice and shiny timestamp-database :)

http://publictimestamp.org/TESTINGONLY/rest/v1.0/publictimestamp-rest-v1.0.pl

Development-Interface

http://publictimestamp.org/DEVEL/rest/v1.0/publictimestamp-rest-v1.0.pl

Server redundancy

Actually this is not so easy, as we need a single incremental id for each timestamp. So what can we do? → We will run a second server, that receives hash-values just like the real server does, but which only queues those until the real server is restored. Then all queued items will be send by this server, transparent to the original sender.

http://fallback.publictimestamp.org/rest/v1.0/publictimestamp-rest-v1.0.pl - this should be a completely different IP-Address, on some server somewhere else in the world which does above job :)

<< Public Timestamp

Table of Contents

Contents

REST Interface

All requests to the server contain

All answers from the server contain

return values

XML Blocks

basic structure

ptb

ptid

ptid_info

Functions

search_ptid_info

search_ptid_hash

search_ptid

search response

gettimestamp

getptb

getlatestptb

addtimestamp

Addresses

Web-Site

REST Interface

Well defined interface address

Testing-Interface

Development-Interface

Server redundancy