doc/README

   1 onak 0.5.0
   2 Copyright 2003-2016 Jonathan McDowell
   3 http://www.earth.li/projectpurple/progs/onak.html
   4
   5
   6 Introduction:
   7
   8 onak is an OpenPGP compatible keyserver. It's primary purpose is the
   9 storage and retrieval of OpenPGP keys but it also has features that make
  10 use of the stored keys for various other purposes. The most useful of
  11 these is probably the pathfinder. This takes two keys, a & b, and
  12 attempts to find a path of trust from a to b in the key database. I
  13 started work on it because at the time there was no DFSG compliant
  14 server that supported multiple subkeys and could act as a drop in
  15 replacement for pksd, which I was running at the time.
  16
  17
  18 Installation:
  19
  20 onak has been mainly developed under Linux with a bit of work on FreeBSD
  21 at times also. It should run on all architectures, but has only been
  22 tested on i386, AMD64 and PowerPC so far.
  23
  24 Typing "./configure && make" should produce a version of onak with
  25 support for the DB4 backend. If you want to choose a different backend
  26 (see below for a discussion about the options) you'll need to pass the
  27 appropriate option to ./configure.
  28
  29 Once make has completed you'll end up with various binaries:
  30
  31 * onak
  32   This is the main program. It's intended to be run from the command
  33   line and allows the addition, deletion and searching of keys in the
  34   database.
  35
  36 * onak-mail.pl
  37   The mail processor. Takes incoming mail (usually to
  38   pgp-public-keys@host) and calls onak to do the necessary work.
  39   Currently only supports INCREMENTAL mails for syncing with other
  40   keyservers and INDEX mails from users.
  41
  42 * add, lookup & gpgwww
  43   The CGI programs. add & lookup are common to all PGP keyservers while
  44   gpgwww is the pathfinder component of onak. To get a keyserver that
  45   clients such as GPG can sync with you'll need to put these in a /pks
  46   directory on a web server running on port 11371. There's an example
  47   mathopd.conf file provided that I used for testing, but I'm now using
  48   Apache for the public test rig as it's already present on the host
  49   running it.
  50
  51 * splitkeys
  52   Utility to take a keyring and split it up into a bunch of smaller ones.
  53
  54
  55 Config:
  56
  57 I've finally added config file support. onak.ini is an example config;
  58 the main thing to change is the location in the backend section to
  59 whereever you want to put your database files. The configure script allows
  60 you to specific where it should live; by default it'll be PREFIX/etc/onak.ini.
  61
  62
  63 Backends:
  64
  65 Currently there is support for 6 different database backends:
  66
  67 * file
  68   The original backend. Very simple and ideal for testing. Stores each
  69   key as a separate file. Doesn't support searching based on key text.
  70
  71 * pg (PostgreSQL)
  72   Once the preferred backend. Use onak.sql to create the tables
  73   necessary to run with this. Unfortunately although suitable for the
  74   keyserver side it was found to be too slow for running the pathfinder
  75   with a large number of keys. This may well be due to my use of it - if
  76   you can help speed it up info would be appreciated.
  77
  78 * db4 (Berkeley libdb4)
  79   The currently preferred backend. Supports the full range of functions
  80   like the pg backend but is considerably faster. Also easier to setup
  81   assuming you have libdb4 installed; there's no need to have an SQL
  82   database running and configured.
  83
  84 * fs (file backend)
  85   A fuller featured file based backend. Doesn't need any external
  86   libraries and supports the full range of operations (such as text and
  87   subkey searching). Needs a good filesystem to get good performance
  88   though as it creates many, many files and links.
  89
  90 * hkp
  91   A proxying backend. No keys are stored locally; all fetch and store
  92   requests are forwarded to the provided keyserver.
  93
  94
  95 Other keyservers:
  96
  97 I'm aware of the following other keyservers. If you know of any more
  98 please let me know and I'll add them.
  99
 100 * pks
 101   http://sf.net/projects/pks/
 102   The original mainstream keyserver; what I used to run on
 103   wwwkeys.uk.pgp.net. Died off due to lack of support for more modern
 104   key features such as multiple subkeys, to the extent that it would
 105   manage them. Largely replaced by SKS.
 106
 107 * CryptNET Keyserver
 108   http://www.cryptnet.net/fsp/cks/
 109   A GPLed server with support for multiple subkeys, but unfortunately
 110   when I looked at it there was no support for syncing via email which
 111   means it can't replace a pks server to act as part of pgp.net.
 112
 113 * Hockeypuck
 114   https://hockeypuck.io/
 115   Written in Go and with support for the SKS synchronisation protocol.
 116
 117 * OpenPKSD
 118   http://openpksd.org/
 119   Don't really know a lot about this. Primarily Japanese development
 120   AFAICT.
 121
 122 * SKS
 123   https://github.com/SKS-Keyserver/sks-keyserver
 124   Probably the most popular keyserver currently. Improves dramatically
 125   on the email synchronisation method by using an HTTP based set
 126   reconciliation approach ensuring the keyserver network eventually
 127   reaches consistency.
 128
 129
 130 Contacting the author:
 131
 132 I can be reached via email as noodles@earth.li. I'm usually on IRC on
 133 OFTC (irc.oftc.net) as Noodles.
 134
 135 All constructive criticism, bugs reports, patches and ideas are welcome.
 136
 137
 138 Obtaining later versions:
 139
 140 onak lives at:
 141
 142 http://www.earth.li/projectpurple/progs/onak.html
 143
 144 Development is carried out using git; you can access the repository
 145 with something like:
 146
 147 git clone git://the.earth.li/onak.git
 148
 149 or it can be browsed via gitweb at:
 150
 151 http://the.earth.li/gitweb/?p=onak.git;a=summary
 152
 153
 154 License:
 155
 156 onak is distributed under the GNU Public License version 2, a copy of
 157 which should have been provided with this archive as LICENSE.