RemoteHashStore Documentation

Ben Tasker

2013-05-21 22:23

RemoteHashStore is an API designed for use by the PHP Changed Binaries monitoring script. It's function is to simply maintain a database of file hashes and compare those hashes against those submitted when checking files. This documentation relates to the client included in the PHP Changed Binaries system. See the relevant documentation if you're attempting to build a client for the RemoteHashStore API (Coming Soon!).

Configuration

When subscribing to the RemoteHashStore API, you'll have been provided with a security key and your configuration settings.

Using the CLI

Add the security key with the following command

php /path/to/install/bin/remote_admin.php --addkey yourkey

Manual Configuration

The security key simply needs to be saved as config/authkey. The other configuration details need to be added to config/remotehashes.php, which has the following format

$remote_store_enabled = true; // Setting this to false disables use of the API
$config['api_server'] = 'example.com'; // This is the URL used to access the API
$config['api_key'] = '9ee82cdd69c32aad0ed16598c034ede2625a0eae';// This is your unique API Key
$config['api_secret'] = '6789'; // This is the authentication token used when checking hashes
$config['server_ident'] = 'myserver'; // This is the identification string for the current server
$config['processblock'] = 100; // Max 250. Dictates how many hashes should be generated before the request is sent to the server
$config['server_email'] = true; // tells the local notification system not to send emails as the server will be doing it

The security key is simply a shared secret encrypted with your password. When performing an administration operation (or updating hashes) the client will prompt for your password, decrypt the key and send the secret to the server. The server then performs some additional processing to verify the key and proceeds once it has authenticated you.

Administration Client

The administration client resides in the same directory as the PHPChangedBinaries system. Every request will require you to enter the password you set when subscribing to the service.

Adding a Server

To add a server, you need to provide an Identification name and a contact email. Check reports will be sent to the email address specified.

php /path/to/install/bin/remote_admin.php --addserver MyServer1 --email ben@example.com --checkin 7

You will then be prompted to enter your update password. Checkin specifies the time period in which the server must perform a check (defaults to 7 if not specified). As we've specified 7, If the server doesn't perform a check every 7 days, an alert email will be sent automatically.

Listing Servers

You can list the servers you have assigned to your API Key with the command

php /path/to/install/bin/remote_admin.php --listservers

Deleting a Server

You may want to remove a server if it's no longer in use, or you don't want to continue checking it's files. To do so, you simply call --rmserver followed by the server name.

php /path/to/install/bin/remote_admin.php --rmserver myserver

Multiple Commands

You can pass the client multiple commands (one of each type) so that all are completed within the same audit session. Processing happens in the following order

rmservers
addserver
listservers

So to remove 'Server1' and add 'Server2' the following commands are essentially identical

php /path/to/install/bin/remote_admin.php --rmserver Server2 --addserver Server1 --email ben@example.com
php /path/to/install/bin/remote_admin.php --addserver Server1 --email ben@example.com --rmserver Server2

Audit Logs

Viewing checks

Full details of checks are retained for two weeks, after this only a summary is available. It's recommended that you list checks first to see whether the check has further details available

TODO: The client is still in the early stages of development, so doesn't support this just yet. However the check report will be emailed through to you by the API.