pt_interface

<< Public Timestamp

Contents


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

http://publictimestamp.org/?pt=search&filename=vim

or with 2 commands in one request:

http://publictimestamp.org/?pt=search&pre=myone&myonefilename=vim&pt=search&pre=mysecond&mysecondfilename=emacs


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

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

Groups: