\input texinfo
@c                            -*- Mode: Texinfo -*- 
@c 
@c pgplib.texi -- TeXinfo documentation for PGPlib.
@c 
@c Author          : Magne Rasmussen
@c Created On      : 6-May-1997
@c Last Modified By: Magne Rasmussen
@c Last Modified On: Tue May  6 13:15:40 1997
@c Update count    : 13
@c Status          : Unknown, Use with caution!
@c 
@c Copyright (C) Magne Rasmussen 1997  Email: <magner@stud.cs.uit.no>
@c 

@c %**start of header
@setfilename pgplib.info
@settitle PGPlib
@c %**end of header

@set VERSION 0.2

@c @setchapternewpage odd

@ifinfo
This WAS the same as the README

Copyright @copyright{} 1997 Magne Rasmussen.
@end ifinfo

@titlepage
@title PGPlib
@subtitle Version @value{VERSION}
@author Tage Stabell-Kul@o{}
@author Magne Rasmussen
@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1997 Tage Stabell-Kul@o{} (@code{tage@@acm.org}).
 All rights reserved.

This is a package, containing a library, that makes it possible for
programmers to include security functionality in their programs, in a
format compatible with RFC1991.

This library is free for commercial and non-commercial use as long as
the following conditions are aheared to:

Copyright remains Tage Stabell-Kul@o{}'s, and as such any Copyright
notices in the code are not to be removed. If this package is used in a
product, Tage Stabell-Kul@o{} should be given attribution as the author
of the parts of the library used. This can be in the form of a textual
message at program startup or in documentation (online or textual)
provided with the package.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
@enumerate
@item Redistributions of source code must retain the copyright notice,
this list of conditions and the following disclaimer.
@item Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
@item All advertising materials mentioning features or use of this
software must display the following acknowledgement:
 "This product includes software written by Tage Stabell-Kul@o{}
(@code{tage@@acm.org})"
@end enumerate

@sc{This software is provided by Tage Stabell-Kul@o{} ``as is'' and any
express or implied warranties, including, but not limited to, the
implied warranties of merchantability and fitness for a particular
purpose are disclaimed.  In no event shall the author or contributors be
liable for any direct, indirect, incidental, special, exemplary, or
consequential damages (including, but not limited to, procurement of
substitute goods or services; loss of use, data, or profits; or business
interruption) however caused and on any theory of liability, whether in
contract, strict liability, or tort (including negligence or otherwise)
arising in any way out of the use of this software, even if advised of
the possibility of such damage.}

The licence and distribution terms for any publically available version
or derivative of this code cannot be changed.  i.e. this code cannot
simply be copied and put under another distribution licence [including
the GNU Public Licence.]

The reason behind this being stated in this direct manner is past
experience in code simply being copied and the attribution removed from
it and then being distributed as part of other packages. This
implementation was a non-trivial and unpaid effort.

Notice that inluced in this release is software copyrighted by
others. The fact that it is present here does not alter the copyright
provided by the original authors.  See each file for details.
@end titlepage

@node    Top,       Introduction, (dir),    (dir)
@comment node-name, next,          previous, up

@menu
* Introduction::                
* Data structures::             
* Concept index::               

 --- The Detailed Node Listing ---

Introduction

* Caveat emptor::               
* Overview::                    
* Limitations::                 
* Regarding PGP::               
* Your feedback::               
* Where to get PGPlib::         
* Installing::                  
* Porting::                     
@end menu

@node Introduction, Caveat emptor, Top, Top
@chapter Introduction

Welcome to PGPlib.
The purpose of this library is to let programs either generate packets
that can then later be digested by PGP, or digest packets earlier
generated by PGP.
In addition, since the library known of all the packets PGP generate
(and accepts) quite a few interesting things can be done.

In addition to the library proper the package includes a few
applications.
Some of them are useful in their own right, most are included to show
how to use the library and to verify that it works correct.

The library is, as far as I know, compatible with RFC-1991, which
describes versions 2.x of PGP.  Specifically, versions 2.6 and 2.7
conform to this specification.  Version 2.3 conforms to this
specification with minor differences. 
@cindex RFC1991

@menu
* Caveat emptor::               
* Overview::                    
* Limitations::                 
* Regarding PGP::               
* Your feedback::               
* Where to get PGPlib::         
* Installing::                  
* Porting::                     
@end menu

@c ==================================================
@node Caveat emptor,  Overview, Introduction, Introduction
@section Caveat emptor
This library can be used to enhance security in computer systems.
However, obtaining security (be it privacy, secrecy, integrety or what
have you) is non-trivial.
This library can help with the simplest of all tasks in connection to
this, storing data in a well known format.
There are a few things you probably would like to know before looking
further.

@itemize @bullet
@item his is version @value{VERSION} for the benefit of those interested
in a PGP libray without sufficient documentation for end users.  The
goal of this release is to obtain feedback on the overall design and
usability. The ultimate documentation aside (source code), there is
almost no documentation 

@item This software is certainly not written with your privacy in mind;
don't trust it without first reading the sources carefully.  Not that
you can't trust me, but if you don't know me, you shouldn't.

@item (De)Compression is done the way PGP does it.  It will probably
leave private data on disk.  Use it with extreme care.
@end itemize


@c ==================================================
@node Overview, Limitations, Caveat emptor, Introduction
@section Overview

The purpose of PGPlib is to enable programs to either produce or consume
data in a format compatible with RFC1991.
Below is a short tour through the functionality provided by PGPlib:

@itemize @bullet
@item PGPlib understands literal packets with filename, mode, etc.  A
literal packet is what PGP uses to store infomation about which file you
have wncrypted (signed or whatever).  You can create literate packages
from files, or from buffers, and create files from literate packets;

@item Convential encrypted packets, that is IDEA with Zimmermann's
 context sensitive feedback.  The library can both read (decrypt) and
write (encrypt) convential packets;
@cindex IDEA

@item Armored files.  You can (de)armor a buffer or a file into a buffer
or a file.

@item UserID packets are read and written from keyrings and buffers;

@item Keys can be obtained from a database or by parsing keyrings.  Both
private and public keys are understood.  There is code to use
DBM as supplied from Berkeley or, if you prefer, GDBM from GNU;;

@item Keys can be kept in buffers or on files.  The secret parts of
private keys are decrypted by a dedicated routine;

@item You can verify signatures on public keys and on buffers or
files; 

@item You can encrypt data (file or buffer) with public keys.  The DEK
is naturally written as a separate packet as specified by RFC1991;

@item With a secret key you can sign other keys and buffers.
@end itemize

You will find included 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.

@c ==================================================
@node Limitations, Regarding PGP, Overview, top
@section Limitations

This documentation was provied with version @value{VERSION}.
Until we reach version 1.0 you can expect documentation to be poor.


@c ==================================================
@node Regarding PGP, Your feedback, Limitations, Top
@section Regarding PGP

PGPlib is @emph{not} part of PGP or endorsed by the author of PGP.
The name has not been choosen to indicate that the library is part of
PGP, rather to indicate that it makes PGP even more useful.



@c ==================================================
@node Your feedback, Where to get PGPlib, Regarding PGP, Top
@section Your feedback

In general, your feedback is solicited.
Since version @value{VERSION} is regarded as an evaluation release bugs
and problems are to be expected.
A mailing list has been set up (by Peter Simons
<Peter.Simons@@gmd.de>).
To subscribe, send an e-mail to the address
@code{pgplib-dev-request@@petium.rhein.de} and write the command
@code{SUBSCRIBE} into the body. 
If you want to be subscribed under a different address than
the one you're mailing from, you can also use @
@code{SUBSCRIBE tage@@somewhere.else} to do the trick. 
To post to the list, send an e-mail to @code{pgplib-dev@@petium.rhein.de}
as usual.

If you have comments regarding PGPlib in general send me an e-mail at
@code{tage@@acm.org}.

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.


@c ==================================================
@node Where to get PGPlib, Installing, Your feedback, Introduction
@section Where to get PGPlib

You can get PGPlib by means of FTP from @code{dslab1.cs.uit.no} in
directory @code{pub}.  
To get the latest version, retreieve the file @code{PGPlib.tar.gz}.
In other words, click on 
@code{ftp://dslab1.cs.uit.no/pub/PGPlib.tar.gz}.
In order to unpack and verify the code you obtained, follow the
following steps
First, uncompressing and un-tar'in the file will create four files in
the @emph{current directory}:
@table @code
@item README 
This is a text file containing, more or less, the text in this section

@item PGPlib-X.tar 
This is the actual source in a tar-file.  It contains the directory
@code{./PGPlib-X}.  Note that it creates a new directory.
The letter @code{X} will be substistuted for the version number. 

@item PGPlib-X.tar.asc
A detached signature, made with my public key on the tar-file above.

@item pubring.pgp
My public key.
@end table

Then, to verify that your copy hasn't been tampered with, first run the 
command 
@example
	pgp pubring.pgp
@end example
to add my key to you keyring. Then, to verify the signature, invoke PGP
as follows
@example
	pgp PGPlib-X.tar.asc PGPlib-X.tar
@end example
The output from PGP should be something along the lines of
@example
Good signature from user "Tage Stabell-Kulo <tage@@cs.uit.no>".
Signature made 1997/05/09 23:26 GMT using 1024-bit key, key ID 71FBD469
@end example
When you are done, you can remove my key from your keyring by running
@example
	pgp -kr tage@@acm.org
@end example
I am confident you are fully aware that you should obtain a copy of my 
key (and the associated signatures) from some trusted third party.
You can now remove @code{pubring.pgp} and @code{PGPlib-X.tar.asc} and
proceed by un-tar'ing the library.
In the (newly created) directory @code{PGPlib-X} you will find file file
@code{INSTALL} which explain, well, yes.


@c ==================================================
@node Installing, Porting, Where to get PGPlib, Introduction
@section Installing

In order to install PGPlib you have to perform two unrelated tasks.
First, recall that PGPlib provides packaging of data in a format PGP
understands.
Thus, PGPlib does not perform any encryption.
For this, I have choosen SSLeay, and you must have the SSLeay library
installed. 
I hope SSLeay is a good choice. I did not
major in mathematics and can 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.  Integration into the SSLeay "error-system" might
happen.  You can obtain SSLeay from
@code{ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL/}.
There is a programmers reference on
@code{http://www.psy.uq.oz.au/~ftp/Crypto/ssl.html}.

SSLeay is quite large and I only use a fraction of it.  On the other
hand, SSLeay seems to be well maintained.
I will look into providing a tailored version of SSLeay with PGPlib.


@c ==================================================
@node Porting, Data structures, Installing, Introduction
@section Porting

PGPlib has been developed on NetBSD 1.2.  The major obstacle for porting
is probably that @code{unsigned long long} must be 64 bits long.
That is, your compiler must support assignmets like
@code{x=0x0123456789abcdefLL} where @code{x} is @code{unsigned long
long}.
Notice that this is a feature of the compiler, not the underlying
architecture. 

A port to @code{Win32} is planned.
If you port PGPlib to some other platform, I would be greatful if you
would send me patches.

@c ==================================================
@node Data structures, Concept index, Porting, Top
@chapter Data structures


@c ==================================================
@node Concept index, , Data structures, Top
@unnumbered Concept Index

@printindex cp

@contents
@bye
