NAME

HammerServer - the HTTP API


INTRODUCTION

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.


BASICS OF THE API

The transport layer of HammerServer's protocol is just plain HTTP (over TCP/IP). The server accepts clients' requests with the following properties:

URL's:

Clients must request services at specific URL's. E.g, data insertion is requested through /insert, retrieval through /retrieve.

CGI Requests:

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.

Server Replies:

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


CATALOG OF CALLS

This section describes the possible calls. Per call the following information is provided:

URL:

At which URL must the server be contacted?

Input Data:

Which data must the client send?

Result Root Tag:

What is the root tag of the returned XML document?

Result Fields:

What is the meaning of fields f0, f1, f2 etc. that are encapsulated in l tags in the returned XML document?

Data Insertion

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.

URL:
 /insert
Input Data

data, the data to insert

Result Root Tag:

insertresult

Fields:

The returned document has one l tag inside the root tag. Contained fields are:

f0

Timestamp of the insertion

f1

ID where the data was inserted

Data Retrieval

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.

URL:
 /retrieve
Input Data

id, a previously obtained identifier (during insertion or search)

Result Root Tag:

retrieveresult

Fields:

The returned document has one l tag inside the root tag. Contained fields are:

f0

Timestamp of the insertion

f1

Retrieved data

Bulk Insertion

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.

URL:
 /insertlines
Input Data

data, A string of \n-separated records

Result Root Tag:

insertlineresult

Fields:

The returned document has one or more l tags inside the root tag. Contained fields are:

f0

Timestamp of the record insertion

f1

Key (id) at which the record was inserted

Searching

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

URL:
 /search
Input Data

term, a substring to search for

Result Root Tag:

searchresult

Fields:

The returned document has zero or more l tags inside the root tag. Contained fields are:

f0

Timestamp of the record insertion

f1

Key (id) at which the record was found

f2

The data itself

Verification

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.

URL:
 /verify
Input Data
Result Root Tag:

verifyresult

Fields:

The returned document has zero or more l tags inside the root tag. Contained fields are:

f0

Timestamp of the record insertion

f1

Key (id) of the record

f2

Verification status: 1 when the data integrity is OK, 0 when crypto verification of the record's signature fails

Offloading

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.

URL:
 /offload
Input Data
Result Root Tag:

offloadresult

Fields:

The returned document has zero or more l tags inside the root tag. Contained fields are:

f0

Timestamp of the record insertion

f1

Key (id) of the record