NAME

HSClient - Perl client package to contact the HammerServer


SYNOPSIS

 use HSClient;
 # Initialization: URL and optional timeout
 my $cli = HSCLient->new('http://server:10000');
 my $cli = HSClient->new('http://server:10000', 30);
 # Timeout access
 $cli->timeout(3);
 my $current = $cli->timeout();
 # Verify that the HammerServer is alive
 $cli->areyouthere()
   or die ("server offline?\n");
 # Data insertion
 my $res = $cli->insert('new data');   
 print ('Inserted at ID ', $res->{id},
        'on date ',        $res->{stamp}, "\n");
 # Bulk data insertion, \n-separated records
 for my $res ($cli->insertlines("data \n more data")) {
    print ('Inserted: id=', $res->{id},
           ' stamp='      , $res->{stamp}, "\n");
 }
 # Data retrieval
 my $res = $cli->retrieve('ID');
 print ('Data ',             $res->{data},
        ' was inserted on ', $res->{stamp}, "\n");
 # Searching
 for my $res ($cli->search('pattern')) {
    print ('Found data ',   $res->{data},
           ' at ID ',       $res->{id},
           ' inserted on ', $res->{stamp}, "\n");
 }
 # Tamper verification
 for my $res ($cli->verify($stamp1, $stamp2)) {
    print ('ID ', $res->{id}, ' dated ', $res->{stamp},
           $res->{verified} ? ' ok ' : ' WARNING: TAMPERED', "\n");
 }
 # Offloading to flat file
 for my $res ($cli->offload($stamp1, $stamp2)) {
    print ('ID ',    $res->{id},
          ' dated ', $res->{stamp},
           " successfully offloaded to flatfile\n");
 }


DESCRIPTION

Module HSClient implements client-side access in Perl to a HammerServer. Initialization will always consist of calling the method new() with the URL of the server. Then, depending on the configuration of the server, the following actions can be taken:

Data insertion:

Methods insert() and insertlines() add information to the tamper resistant log;

Retrieval:

Methods retrieve() and search() search for contents;

Verification:

Method verify() checks the integrity of the tamper-resistant log;

Clean up:

Method offload() removes data from the back end database onto a flat file.

This package respects the proxy settings as stated in the environment variables http_proxy and https_proxy. Domains stated in no_proxy will not be proxied. When no proxy environment variables are present, then HSClient will assume a direct connection (without a proxy) to the target URL.


METHODS

Initialization and Live Checks

 my $cli = HSClient->new($url)
 my $cli = HSClient->new($url, $timeout)

This method initializes a new client object. The hammer server at $url will be contacted for further operations. The optional timeout argument is in seconds. The default is 180 seconds.

In order to check whether the server is online, use

 $cli->areyouthere()

Return value undef signals that the server is offline, or that the URL doesn't point to a valid server.

Timeouts

 $cli->timeout($t);
 my $t = $cli->timeout()

Sets or retrieves the current timeout for HTTP connections.

Insertion of single values

 my $res = $cli->insert($data)

The data are added to the tamper-resistant log. The returned result states the timestamp of insertion and the ID, as follows:

$res->{id}

is the ID where the data is inserted. The ID can be used to retrieve. This value is a base64-encoded SHA512 value having a length of 86 characters.

$res->{stamp}

is the timestamp. The time stamp can be used as a time delimter in verifications. It states the year, month, day, hour, minute, second and microsecond, e.g., 2009/08/25-13:58:06.776.

Bulk insertion of newline-separated values

 my @results = $cli->insertlines("data\nmore data")

The argument is split by newline characters, and its subparts are inserted. The return value is an array, containing references to hashes. Each hashref in the array has a field id and a field stamp, as follows:

 for my $r (@results) {
    print ("Inserted at id: ", $r->{id},
           " on timestamp   ", $r->{stamp}, "\n");
 }

Retrieval of a value

 my $res = $cli->retrieve($id)

The data at the stated ID is verified and returned (with a timestamp). When the data fails tampering checks, an error occurs. Here is an example.

 my $insertres = $cli->insert('test data');
 print ("Data inserted at id ", $insertres->{id},
        " stamped ",            $insertres->{stamp},
        "\n");
 eval {
     my $retrieveres = $cli->retrieve($insertres->{id});
 }; 
 die ("Integrity checks failed (or technical error)\n") if ($@);
 print ("Data at id ",    $insertres->{id},
        " retrieved as ", $retrieveres->{data}, "\n");

Searching

Method search() takes as argument a substring, and searches the tamper-resistant log for occurrences. Matching is done by substring only, case-sensitive.

The return value is an array of hash references. Each hashref has the fields id, stamp and data. For example:

 for my $r ($cli->search('fox')) {
    print ("Substring 'fox' found in data ",
           $r->{data}, " at id ", $cli->{id}, "\n");
 }

Searching for a substring does not verify data integrity in the same way as retrieve() does. It only matches substrings. If integrity verification is required, then the client application must call retrieve() to verify data integrity of the returned results.

Verification of the Tamper-resistant Log

Method verify() is typically an administrator-run routine to periodically verify the log. Its two input arguments are a starting timestamp and an ending stamp. Stamps are compared alphabetically with the datastore; so that all entries for the year 2008 could be verified using the start stamp 2008 and the end stamp 2008/12/31:23:59:59.999. (Note that the ending stamp 2009 would select two whole years for verification.).

This method doesn't throw an error when verification fails (as opposed to retrieve()). In contrast, the return value is an array of hash references, where each reference has the keys: id, stamp, and verified. The last field is 0 when verification fails. for example:

 for my $r ($cli->verify($start, $end)) {
    warn ("Tampered data at id ", $r->{id},
          " stamped ",            $r->{stamp}, !!\n")
      unless($r->{verify});
 }

Data Cleaning

Method offload() is typically administrator-run. It offloads data from the back end database onto a flat file. Similar to verify(), it has two timestamps - start and end. For example, the following code snippet offloads data of the first quarter of 2009:

 for my $r ($cli->offload('2009/01', '2009/03')) {
    print('Offloaded ID ', $r->{id}, ' stamped ', $r->{stamp}, "\n");
 }


SEE ALSO

The command line script hsclient uses this module. See the documentation of hsclient for information.


AUTHOR

The tamper-resistant server, the client-side API's, and the documentaion were written by Karel Kubat / karel@e-tunity.com. Copyright (c) 2009 ff. Distributed under GPLV3.