PKS-INTRO(8)

NAME
pks-intro - introduction to the public key server system

DESCRIPTION
The public key server system is a set of programs which manages and provides general access to a database of PGP public keys.

The database itself is not a standard PGP keyring. Instead, the keys which are managed by the server are stored in a set of Berkeley DB 2.x format database files. Most operations only take a fraction of a second, and even large operations involving tens of thousands of keys usually take only a few minutes.

  Programs

pksd(8)
    This is the public key server daemon. It processes HTTP requests and mail requests to add keys to the database and query the database contents.

pksclient(8)
    This is a command-line program for managing the database. It supports All the operations of the daemon, and a few more.

pks-mail.sh
    This script is run for each mail message received to queue the message and send it to pksd(8) for processing.

pks-queue-run.sh
    When pksd(8) exits unexpectedly, this program can be used to scan the queue and resubmit any messages which have not yet been processed.

pksdctl(8)
    This is a helper program used by pksd-mail.sh and pksd-queue-run.sh.

  Configuration files and data files

pksd.conf(5)
    This file contains all the configuration data needed to run the system.

<db_dir>/num_keydb
    This file contains the number of key database files. In order to handle very large databases on operating systems with limited file sizes, the key database can be split into up to 1000 separate files.

<db_dir>/keydbXXX, <db_dir>/worddb, <db_dir>/timedb
    These files contain the actual database. The first files contain the PGP key information, indexed by the key ID. The XXX is 000, 001, 002, up to the number of key database files minus 1. The second file indexes the key ID's by the words in the key's user ID's. The third file indexes the key ID's by the time they were added to the database.

SEARCHING
The search engine is not the same as that used by the pgp program. It will return information for all keys which contain all the words in the search string. A ``word'' in this context is a string of consecutive alphabetic characters. For example, in the string marc@mit.edu, the words are marc, mit, and edu.

DATABASE ADMINISTRATION
In this release, the pgp keyserver software now uses the locking, logging, and transaction facilities of Berkeley DB. This provides for added safety in the event of a server crash, and also allows for multiple pksd and/or pksclient processes to access the database at the same time. This does make management of a keyserver a little more complicated. The Berkeley DB reference section on Berkeley DB Transactional Access Methods Applications
<http://www.sleepycat.com/docs/ref/toc.html#transapp>
describes the procedures and commands which are used for checkpointing, archive (backup), and recovery. You should familiarize yourself with this information before running a key server.

DESIGN
The key server was my Advanced Undergraduate Project (which is really a thesis, but with a different name) for my Bachelor's degree in Computer Science and Engineering at the Massachusetts Institute of Technology. You can read detailed discussion of the internals of this key server, you can read my AUP at
<http://www.mit.edu/people/marc/pks/thesis.html>.

SEE ALSO
pksd(8), pksclient(8), pks-mail.sh(8), pks-queue-run(8), pksdctl(8), pksd.conf(5), pgp(1)

BUGS
The timedb will grow without bound. This database should be automatically pruned. Not all operating systems can open 1000 files at once.

AUTHOR
Marc Horowitz, Massachusetts Institute of Technology