keystory

Introduction

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.

Usage

keystory is used in two steps.

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.
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]

options

-q
--quiet: surpress non-fatal messages
-o file
--output file: redirect any standard output to file
-h
--help: print help

Commands

report addr: print an XHTML report on addr
import-mbox: import a Unix mbox-style files from standard input (stdin)
reset-db: reset the database, clearing all current data
import-csv: import CSV format on standard input (stdin) See the CSV format for details.
export-csv: 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

Command options are dependent on the command used.

import-mbox

--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
* ^-----BEGIN PGP SIGNATURE-----
| /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.

Details

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.

Bugs

Duplicately-inserted information is handled as is. It could either be retrieved with distinctiveness, or be prevented from being imported twice.

Examples

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 - \
  http://lists.gnupg.org/pipermail/gnupg-users.mbox/gnupg-users.mbox \
  | keystory import-mbox --forum gnupg-users

Generating a report on Werner Koch's signature history:

keystory report wk@gnupg.org

Files

~/.keystory: default directory for database information

Author

Frank J. Tobin, ftobin@neverending.org

OpenPGP key fingerprint:

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

Copyright

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.