Contents |
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 [4]
or with 2 commands in one request:
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
- 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:
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.
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 [8] - 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 [9]
Development-Interface
http://publictimestamp.org/DEVEL/rest/v1.0/publictimestamp-rest-v1.0.pl [10]
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 [11] - this should be a completely different IP-Address, on some server somewhere else in the world which does above job :)