HammerServer - the HTTP API
The HammerServer is a networked daemon, providing tamper-resistant logging to remote clients. This document describes how such remote clients may connect to the HammerServer.
Note that there are wrapper libraries for the client API, such as the Perl client HSClient. They generally provide a much easier way to contact the server (as opposed to hand-crafting your interface code). This document is therefore more a reference, than programmer's guide.
The transport layer of HammerServer's protocol is just plain HTTP (over TCP/IP). The server accepts clients' requests with the following properties:
Clients must request services at specific URL's. E.g, data insertion is requested through /insert, retrieval through /retrieve.
A client that requests a service normally supplies data (this holds true for all actions, except for the browser index page, and the areyouthere call). Data are supplied using the standard Common Gateway Interface (CGI) protocol. For example, data insertion must supply a CGI variable data, stating the data to insert.
Upon succesful completion the server returns an XML document stating the results. The format of the returned XML message is fairly simple and straight-forward. E.g, data insertion returns an XML document that states the key at which the data was inserted.
Unsuccesful (error) replies are signaled with a HTTP 500 ``server error'' code. In this case there the server does not send an XML return document, but states the error as plain content.
As an example, here's the transmission of a request to insert the data ``test string''. The client contacts the server at the URL /insert and posts a CGI variable data with the value test string:
POST /insert HTTP/1.1 TE: deflate,gzip;q=0.3 Connection: TE, close Host: hammerserver:10000 User-Agent: libwww-perl/5.805 Content-Length: 16 Content-Type: application/x-www-form-urlencoded
data=test+string
The server replies with an XML document with the root tag insertresult. The next inner tag designate a line l, with two fields. The first field f0 has the value 2009/08/28-01:25:06.068, which is the timestamp of the insertion. The second field f1 is the key where the data was inserted, in this example U2FsdGVkX1/lr+aoZnRdsHxO06D8DiPVDpUlRT2FQhg=:
HTTP/1.1 200 OK Date: Thu, 27 Aug 2009 23:25:06 GMT Server: libwww-perl-daemon/1.36 Connection: close Server: HammerServer Content-Length: 217
<?xml version="1.0" encoding="UTF-8"?> <?xml-stylesheet type="text/xsl" href="/xslt"?> <insertresult> <l> <f0>2009/08/28-01:25:06.068</f0> <f1>U2FsdGVkX1/lr+aoZnRdsHxO06D8DiPVDpUlRT2FQhg=</f1> </l> </insertresult>
As a second example, here is an erroneous call. The client requests the retrieval of data at a given ID, but due to data tampering, verification fails. The request is:
POST /retrieve HTTP/1.1 TE: deflate,gzip;q=0.3 Connection: TE, close Host: hammerserver:10000 User-Agent: HSClient Content-Length: 51 Content-Type: application/x-www-form-urlencoded
id=U2FsdGVkX1%2FuwYrGES3gehsl2vZn8sej1EfQN4GdO9U%3D
The error is signaled by the server as follows:
HTTP/1.1 500 Internal Server Error Date: Sat, 05 Dec 2009 19:58:35 GMT Server: libwww-perl-daemon/1.36 Connection: close Server: HammerServer Content-Length: 43
FATAL ERROR: Datastore: validation failed
This section describes the possible calls. Per call the following information is provided:
At which URL must the server be contacted?
Which data must the client send?
What is the root tag of the returned XML document?
What is the meaning of fields f0, f1, f2 etc. that are encapsulated in l tags in the returned XML document?
Data are added to the tamper-resistant log. The server returns a timestamp of insertion and a key (ID) where the data can be retrieved.
/insert
data, the data to insert
insertresult
The returned document has one l tag inside the root tag. Contained fields are:
Timestamp of the insertion
ID where the data was inserted
Using a key, the client requests to retrieve data from the tamper-resistant audit log. The server returns the timestamp of insertion and the data.
/retrieve
id, a previously obtained identifier (during insertion or search)
retrieveresult
The returned document has one l tag inside the root tag. Contained fields are:
Timestamp of the insertion
Retrieved data
The client sends bulk data to be inserted. The sent data must consist of newline-separated records. The server responds with a list of keys where separate records are inserted.
/insertlines
data, A string of \n-separated records
insertlineresult
The returned document has one or more l tags inside the root tag. Contained fields are:
Timestamp of the record insertion
Key (id) at which the record was inserted
The client sends a substring to be searched in the back end database. The server responds with 0 or more matches (but does not verify the matching records, use verify or retrieve for that purpose).
/search
term, a substring to search for
searchresult
The returned document has zero or more l tags inside the root tag. Contained fields are:
Timestamp of the record insertion
Key (id) at which the record was found
The data itself
The client sends a two timestamps, a starting and ending time. The server verifies all entries that were inserted between the stated times and reports back on the data integrity.
/verify
start, the starting time stamp
end, the ending time stamp
verifyresult
The returned document has zero or more l tags inside the root tag. Contained fields are:
Timestamp of the record insertion
Key (id) of the record
Verification status: 1 when the data integrity is OK, 0 when crypto verification of the record's signature fails
The client sends a two timestamps, a starting and ending time. The server offloads all records between the timestamps to a flatfile on the server, thereby cleaning the database.
/offload
start, the starting time stamp
end, the ending time stamp
offloadresult
The returned document has zero or more l tags inside the root tag. Contained fields are:
Timestamp of the record insertion
Key (id) of the record