[[:osapa:public_timestamp|<< Public Timestamp]]
=====Contents=====

  * [[https://www.linuxfoundation.org/#REST_Interface|1 REST Interface]]
    * [[https://www.linuxfoundation.org/#All_requests_to_the_server_contain|1.1 All requests to the server contain]]
    * [[https://www.linuxfoundation.org/#All_answers_from_the_server_contain|1.2 All answers from the server contain]]
    * [[https://www.linuxfoundation.org/#return_values|1.3 return values]]
  * [[https://www.linuxfoundation.org/#XML_Blocks|2 XML Blocks]]
    * [[https://www.linuxfoundation.org/#basic_structure|2.1 basic structure]]
    * [[https://www.linuxfoundation.org/#ptb|2.2 ptb]]
    * [[https://www.linuxfoundation.org/#ptid|2.3 ptid]]
    * [[https://www.linuxfoundation.org/#ptid_info|2.4 ptid_info]]
  * [[https://www.linuxfoundation.org/#Functions|3 Functions]]
    * [[https://www.linuxfoundation.org/#search_ptid_info|3.1 search_ptid_info]]
    * [[https://www.linuxfoundation.org/#search_ptid_hash|3.2 search_ptid_hash]]
    * [[https://www.linuxfoundation.org/#search_ptid|3.3 search_ptid]]
      * [[https://www.linuxfoundation.org/#search_response|3.3.1 search response]]
    * [[https://www.linuxfoundation.org/#gettimestamp|3.4 gettimestamp]]
    * [[https://www.linuxfoundation.org/#getptb|3.5 getptb]]
    * [[https://www.linuxfoundation.org/#getlatestptb|3.6 getlatestptb]]
    * [[https://www.linuxfoundation.org/#addtimestamp|3.7 addtimestamp]]
  * [[https://www.linuxfoundation.org/#Addresses|4 Addresses]]
    * [[https://www.linuxfoundation.org/#Web-Site|4.1 Web-Site]]
    * [[https://www.linuxfoundation.org/#REST_Interface_2|4.2 REST Interface]]
      * [[https://www.linuxfoundation.org/#Well_defined_interface_address|4.2.1 Well defined interface address]]
      * [[https://www.linuxfoundation.org/#Testing-Interface|4.2.2 Testing-Interface]]
      * [[https://www.linuxfoundation.org/#Development-Interface|4.2.3 Development-Interface]]
      * [[https://www.linuxfoundation.org/#Server_redundancy|4.2.4 Server redundancy]]

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

  * **0**
  * OK

  * **1**
  * invalid or missing parameters

  * **2**
  * unknown command
======  XML Blocks ======

All XML-Answers are combinations of these xml-blocks
=====  basic structure =====
<code>
<?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></code>
=====  ptb =====
<code>
<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></code>
=====  ptid =====
<code>
<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></code>
=====  ptid_info =====
<code>
<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></code>

  * **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
<code> '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')</code>

  * **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 ====
<code>
<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></code>
=====  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 [[https://www.linuxfoundation.org/collaborate/workgroups/osapa/pt_interface#ptid_info|ptid_info]]
  *  hash-values as required for [[https://www.linuxfoundation.org/collaborate/workgroups/osapa/pt_interface#ptid|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|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|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|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|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 :)

\\ [[:osapa:public_timestamp|<< Public Timestamp]]