Paul Barry > keyserver-1.04 > keyserver

Download:
keyserver-1.04.tar.gz

Annotate this POD

View/Report Bugs
Source  

NAME ^

keyserver - an RSA-based public keyserver for use with Devel::Scooby (which includes HTTP monitoring facility at port 8080).

VERSION ^

1.04

SYNOPSIS ^

Create a ".keyserverrc" configuration file (see FILES), set-up the required database (see ENVIRONMENT), then invoke the keyserver:

    ./keyserver

DESCRIPTION ^

This keyserver provides three services to clients that communicate with it.

1. The "Responder Service" runs on port RESPONDER_PPORT and listens for requests from clients. These take the form of an IP address in dotted-decimal notation, followed by a protocol port number. The IP address/port-number are looked-up in the SCOOBY.publics table (see ENVIRONMENT), and - if found - the associated public key is extracted from the table and signed using this keyserver's private key. Both the signature and the public key are then sent to the client.

If the lookup fails, the strings "NOSIG" followed by "NOTFOUND" are returned to the client.

If the IP address is LOCALHOST (which defaults to 127.0.0.1) and the protocol port number is RESPONDER_PPORT (which defaults to 30001), then this program returns the string "SELFSIG" followed by an UNSIGNED copy of this keyserver's public key. In this way, a client can retrieve the public key to use when verifying signatures.

2. The "Registration Service" runs on port REGISTRATION_PPORT and listens for connections from clients. When on arrives, it is immediately followed by a protocol port number, then a public key. This key is added to the SCOOBY.publics table (see ENVIRONMENT) together with the clients IP address in dotted-decimal notation and the protocol port number. For obvious reasons, the received public key is NOT signed by the client.

Note that changing the defined constant values for REGISTRATION_PPORT and RESPONDER_PPORT from their defaults will require source code changes to programs that interact with this keyserver (which includes the Devel::Scooby, Mobile::Executive and Mobile::Location modules). So, don't change these constant values unless you really have to.

3. The "HTTP-based Monitoring Service" runs on port HTTP_PORT (which defaults to 8080), and provides a mechanism to remotely check the status of the keyserver via the world-wide-web. The LOGFILE can be viewed and (optionally) reset via the web-based interface. Resetting the LOGFILE results in an archived copy of the LOGFILE-to-date being created on the keyserver's local storage.

ENVIRONMENT ^

It is assumed that the MySQL RDBMS is executing on the same machine as this keyserver. Here's a quick list of MySQL-specific instructions for creating a database and table required to support this program:

    mysql -u root -p

    mysql> create database SCOOBY;
    mysql> use mysql;
    mysql> grant all on SCOOBY.* to perlagent identified by 'passwordhere';
    mysql> quit

    mysql -u perlagent -p SCOOBY < create_publics.sql

If you use a different user-id/password combo to that shown above, be sure to change the two constants defined at the start of the source code (KEYDB_USER and KEYDB_PASS).

where the create_publics.sql disk-file contains:

    create table publics
    (
        ip_address       varchar (16)  not null,
        protocol_port    varchar (6)   not null,
        public_key       text          not null 
    )

FILES ^

A configuration file, called ".keyserverrc", needs to exist in the same directory as this keyserver. Its contents detail the IP address and protocol port numbers that connections will be allowed from. Typically, it will look something like this:

    127.0.0.1:*
    192.168.22.14:*

which allows any connection (on any port) from both 127.0.0.1 and 192.168.22.14. Note that (at the moment), specifying a protocol port number in place of "*" has no effect. Connection from all ports on the specified IP address are allowed. This will change in a future release.

When first executed, this keyserver creates two disk-files:

    "LOCALHOST.RESPONDER_PPORT.public", and
    "LOCALHOST.RESPONDER_PPORT.private".  

These contain this keyserver's RSA public and private keys, respectively. The public key is also added to the MySQL database.

DO NOT remove these files from the directory that runs this keyserver.

DO NOT edit these files, either.

The keyserver also logs all communication with it (in a disk-file called "keyserver.log"). The contents of this log can be viewed (and archives of it created) using the "HTTP-based Monitoring Service" (see DESCRIPTION).

FOUR IMPORTANT CONSTANTS ^

Near the start of the keyserver's source code, four constants are defined as follows:

    use constant KEYSRV_PASSWD       => 'keyserver';
    use constant KEY_SIZE            => 1024;

    use constant ENABLED_LOGGING     => 1;
    use constant ENABLED_PRINTS      => 1; 

Change the first two constants to values of your choosing to set the password (KEYSRV_PASSWD) and the key size (KEY_SIZE) to use during the PK+/PK- generation. Note: the larger the key size, the stronger the encryption, but, the slower this software will run. The default value for KEY_SIZE should suffice for most situations.

Set ENABLED_LOGGING to 0 switch off disk-based logging and the HTTP-based Monitoring Service.

Set ENABLED_PRINTS to 0 to disable the the display of status messages on STDOUT.

SEE ALSO ^

The Devel::Scooby, Mobile::Executive and Mobile::Location modules.

The following CPAN modules are assumed to be installed: Net::MySQL and Crypt::RSA. The HTTP server requires HTTP::Daemon and HTTP::Status, which are installed as part of the libwww-perl library (also available on CPAN).

The Scooby Website: http://glasnost.itcarlow.ie/~scooby/.

AUTHOR ^

Paul Barry, Institute of Technology, Carlow in Ireland, paul.barry@itcarlow.ie, http://glasnost.itcarlow.ie/~barryp/.

COPYRIGHT ^

Copyright (c) 2003, Paul Barry. All Rights Reserved.

This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.

syntax highlighting: