• 1 REST Interface
  • 1.1 All requests to the server contain
  • 1.2 All answers from the server contain
  • 1.3 return values
• 2 XML Blocks
  • 2.1 basic structure
  • 2.2 ptb
  • 2.3 ptid
  • 2.4 ptid_info
• 3 Functions
  • 3.1 search_ptid_info
  • 3.2 search_ptid_hash
  • 3.3 search_ptid
    • 3.3.1 search response
  • 3.4 gettimestamp
  • 3.5 getptb
  • 3.6 getlatestptb
  • 3.7 addtimestamp
• 4 Addresses
  • 4.1 Web-Site
  • 4.2 REST Interface
    • 4.2.1 Well defined interface address
    • 4.2.2 Testing-Interface
    • 4.2.3 Development-Interface
    • 4.2.4 Server redundancy

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

• 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>

• 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

• 0
• OK

• 1
• invalid or missing parameters

• 2
• unknown command

All XML-Answers are combinations of these xml-blocks

<?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>
        <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>
        <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>
        <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)

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.

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.

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

<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>

Returns details to one specific timestamp.

Returns details to one specific PTB

Special command to easy optain latest PTB

returns:

• ptb
• ptid of latest ptb
• ptid_info of latest ptb

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

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.

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

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, 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

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

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

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