Keystory gathers data on people's signature usage, and generates XHTML reports based upon this data to help determine what key an email address uses. The idea is to practically complement the web of trust.

Web-based Demonstration

You might be interested in seeing a CGI-driven demonstration of keystory.


keystory is used in two steps.

  1. The first step of keystory is the gathering of signature information. This can be done by a variety of means, but most likely you will want to hook it into procmail(1) to gather signature information from incoming mail (keystory support both PGP/MIME and cleartext sigs), or to insert an entire mailbox at one time (e.g., download a mailing list's archive in mbox format, and process it in bulk). The keystory command most likely used for this setup is import-mbox.

  2. The second step of keystory is generating reports. The keystory report command generates an XHTML report, and prints it to stdout (or to whatever --output specifies).

Command-line usage

keystory options COMMAND [command-options] [command-args]


surpress non-fatal messages
-o file
--output file
redirect any standard output to file
print help


report addr
print an XHTML report on addr
import a Unix mbox-style files from standard input (stdin)
reset the database, clearing all current data
import CSV format on standard input (stdin) See the CSV format for details.
export the database in CSV format to standard output (stdout).

Import commands will print to their standard output a copy of what is being inserted, in CSV format. Use --quiet to disable this feature.


Command options are dependent on the command used.

--forum forum
associate signatures in the mailbox with forum. (optional).

procmail(1) setup

It may be desirable to setup keystory as a procmail filter, intercepting every signed message and noting that datapoint in its database. Here is a hopefully useful procmail filter to do that:

:0 BDhbc
| /usr/bin/nice -10 /usr/local/bin/keystory import-mbox

If you wanted to get fancy, you could setup a system which first determined which forum (e.g., mailing list) the imported message is destined for.


What is recorded

Each data point recorded is a tuple of (keyid, addr, time, sigid, forum). The address (addr) is gatherered from the 'From' of a messages. The forum is a user-specified piece of information about where the signature was seen; this can be a mailing list, newsgroup, or similar.

CSV format

When imformation is printed or gathered in csv-style format, the order of the data is: (keyid, addr, time, sigid, forum). Key id's are the full 16 character hexidecimal representation of the key id.



Many mailing lists offer mbox-style archives. Here is a simple way to import all of a mailing list's archives in one batch:

wget --quiet -O - \ \
  | keystory import-mbox --forum gnupg-users

Generating a report on Werner Koch's signature history:

keystory report


default directory for database information


Frank J. Tobin,

OpenPGP key fingerprint:

4F86 3BBB A816 6F0A 340F  6003 56FF D10A 260C 4FA3

Copyright (C) 2001 Frank J. Tobin,

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.