(emacs, please switch to -*-indented-text-*- mode)

Welcome to version 0.1 of PGPlib. 


What is there for you
=====================

PGPlib is a library that lets you generate (and manipulate) PGP
packets without having to run PGP.  In particular there is code to
generate and understand the following types of PGP packets:

   - Literal with filename, mode, etc.  You can create literate
     packages from files, or from buffers, and create files from
     literate packets;
   - Convential encrypted (IDEA with Zimmermann's context sensitive
     feedback).  The library can both read (decrypt) and write
     (encrypt) convential packets (in PGP format);
   - Armor.  You can (de)armor a buffer or a file into a buffer or a
     file;
   - UserID packets are read and written in a variety of formats;
   - Keys can be obtained from a databsae (which is provided) or by
     parsing keyrings.  Keys can be kept in buffers or on files;
   - You can maintain a PGP public-key database (I use this library to
     maintain a database with ~40.000 keys).  There is code to use DBM
     as supplied from Berkeley or, if you prefer, GDBM from GNU;
   - You can verify RSA signatures on public keys and on buffers
     (files);
   - You can encrypt data (file or buffer) with public keys.  The DEK
     is naturally written as a separate packet;
   - With a secret key you can sign other keys and buffers.  Keys can
     be read from databases or files; they are decrypted on the fly.

I have made a small program that will (de)armor anything, a parser to
parse PGP files (including decryption and so on), a shell to
manipulate a keydatabase, a keyserver to run on top of such a
database, a program to verify signatures on keys and/or files, a
program to split keyrings in smaller parts and a program that will
sign files for you.  You will find all these (and more) in the
applications/ directory.  None of these uses PGP, the library provides
all the functionality you need.


What is not there for you
=========================

   - Sufficient documentation.

I have written this library because I need it.  In order to make life
less hard for my students, I will have to provide some documentation.
Possibly even on-line.  However, note that the directory doc/ was
created.  Documentation has now moved up to the top of the list, so
you can expect some to be written.


What you need 
=============

   - You must have the SSLeay library as I have not implemented any
     cryptographic functionality; I hope SSLeay is a good choice. I
     did not major in mathematics and can thus not judge the quality
     of their work, although it looks solid (to me).  I link with their
     version 0.6.6.  I rely on SSLeay for great many things, in
     particular their BIGNUMs, RSA encryption and IDEA.  I use
     "fprintf(stderr" when problems occur, but integration into the
     SSLeay "error-system" might happen.  You can obtain SSLeay from:
        * ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL/ - SSLeay source
        * ftp://ftp.psy.uq.oz.au/pub/Crypto/SSLapps/ - SSL applications
        * http://www.psy.uq.oz.au/~ftp/Crypto/ssl.html - SSLeay Programmer
          Reference
     SSLeay is quite large and I only use a fraction of it.  On the
     other hand, SSLeay seems to be well maintained and their
     crypto-library might very well shrink or become more modular as
     time passes.


Porting
=======

PGPlib has been developed on NetBSD 1.2.  The major obstacle for
porting is probably that "unsigned long long" must be 64 bits long,
and that support for this datatype must be in the c-library (that is,
if you can't so sscanf(arg, "%qx", &key_id) to get a 64-bit thing into
key_id you will have to find yourself a new c-library).  Also, your
compiler must support assignmets like x=0x0123456789abcdefLL where x is
unsigned long long.

If you port PGPlib to some other platform, I would be greatful if you
would send me patches.  autoconf (that is ./configure) is forthcoming.


Regarding PGP
=============

 - It is not possible to be fully compatible with PGP without access
   to the sources of PGP.  This is so since the document describing
   the PGP format in the PGP release (PGFORMAT.DOC) is incomplete
   (buggy is probably more correct).  Furthermore, in order to be
   compatible with PGP I had to use the same constants and bitmasks
   (not defined in PGFORMAT.DOC).  I found them in the PGP sources in
   the file src/pgp.h and that file appears in this package under the
   name src/pgp_m.h ('m' for modified, although I have only removed
   parts I did not use, not altered the remaining contents).  I have
   included it for your convenience; if you prefer, you can use pgp.h
   from the PGP sources instead.  Furthermore, I had to look at the
   PGP sources in order to understand how the armored format is
   designed.  Also, the "checksum" provided on signatures is not
   described (I haven't used it anyway). 
 
 - It seems as if the compression performed by PGP is not supported by
   zlib-1.0.4.  I don't have the time to figure out why this is the
   case.  Thus, I have copied the files PGP/src/z* into the directory
   pgpzip in this release.  I have also edited them sligthly to make
   them compile smoothly into a library.  I will send some (virtual)
   flowers to the person(s) that provides me with a (de)compression
   library that is compatible with the way PGP does it, and works on
   buffers rather than on files.  I have included libz-1.0.4 as a hint
   to everyone.

 - I have based this library on the format(s) read and written by PGP
   2.6.3i and (small) parts of PGP 2.6.3i can be found herein.  I
   sincerely hope I haven't infringed the rights of anyone,
   Zimmermann's in particular, by including parts of PGP in this
   release.  If so, "I am sorry; the intention was good".

 - Copyright issue: If you know anything about these things, please
   take a look at the #include near the top of armor.c and tell me how
   I can include code from PGP and still sleep well at night.


What I would like
=================

 - A nice library that does compression in a PGP-compatible manner,
   without using FILEs (see above).  I have included libz-1.0.4 as a
   hint to everyone.
 - The keyserver should produce output identical to the ones based on
   PGP.  Then you could drop this one in (trade some memory for an order
   of magnitude increase in performance).  It should also write HTML,
   controlled by an command-line option;
 - An expert opinion on whether the bug, documented in the routine
   verify_keysig (in file src/signature.c), is relevant in any way;


Your Feedback
============

   Your feedback is solicited.  Send your comments to tage@acm.org.  
   I will try my best, but I was flooded by e-mail after release 0.0 so 
   please don't hold your breath while you wait for a reply.

   If you write a nice application based on this library (the ultimate
   feedback :-), please feel free to send it to  me and I will include
   it in the next release; 


Where to get PGPlib
===================

	ftp://dslab1.cs.uit.no/pub/PGPlib-0.1.tar

