PGPlib 0.96 - Open PGP toolkit

NEWS

DOCUMENTATION! opgplib/libpgp5.doc briefly describes each call.

Malloc is now used.  Several core routines have changed (e.g. hashes now
store the algorithm prepended to the CTX structure which is malloced).
Now I have to search for memory leaks :).

Ciphers now use a context structure holding the gory details (and will allow
multithreading and such).

Dearmor has been optimized.

There is new pgpv program that does not quite do what the PGP pgpv does,
but is about twice as fast.  Also clearsig and testsig programs have replaced
the awk scripts.
_____________________________

See the README in pgplib for OpenPGP compliance issues.

This is a collection of cryptography utilities, mainly to access PGP files and
to demonstrate certain techniques.

opgplib is a set of routines designed to demonstrate how to implement the
OpenPGP specification.

minipgp5 is a simple pgp5.0/OpenPGP implementation - shows how to bolt the
library routines together to actually work.

Everything works under Linux 2.0 and later.  Free BSD compiles might need to
edit /usr/share/mk/sys.mk to have LDFLAGS as the last thing in the .c rule in
both posix and non posix sections, and the shared lib needs gmake or change $^
to $?, and it needs a trailing digit, e.g. libpgp.so.0 to work.  And using
gmake instead of make helps.

I don't know why, but FreeBSD searches objects in the precise order, so if
-lpgp preceeds x.o, it won't work.

Many of these are works in progress, and only one set of eyes has looked at
these programs, so there are probably lots of security holes.  I am not
scrupulous about cleaning memory beyond the library free calls.  Anyone who can
examine core dumps or access the kernel image can also pick out passphrases
from tty traffic, and until there are ways of secureing that, I am not going to
worry about thoroughly wiping memory.  Although I am not going to do it, I
welcome any modifications that will increase the security of these routines.

All of these programs are freely redistributable with the only condition is
that if you make modifications, you either have to indicate what changed from
the original, or clearly disassociate it with this package, and that you use
these at your own risk - there is no warranty of any kind.

You can freely use any of these in commercial or non-commercial products
(though they are dependent on libraries with different licensing terms, and
various patents and copyright apply to the algorithms), and you can even
integrate them into other libraries and place them under new licensing terms
(subject to the above provision).

For the unmungers out there, all the source has been run through indent with
the following parameters:
-i2 -ts0 -npro -br -ce -npcs -npsl -l80 -v

==================================================
USAGE NOTES (badly out of date, look at the source or the scripts)

pgpv is a not-quite compatible version of the 5.0 version.  It
automatically forks and pipes itself as necessary to go from encrypted to
plaintext with signature verification.

./minipgp5 <textfile >sigfile [-k keyid] [-r secring] [-p pp] [-t type] [-4]
./minipgp5 >ophdr -1 -t 1 ...

Produce DSA/SHA signature of textfile, saving detached signature into sigfile,
using secringfile (usually secring.skr), and key with 8 byte id of keyid8, and
optional pp (passphrase) to unlock.  Use -t 1 for onepass, and 24 for DH
subkey.  The -1 writes the onepass header to stdout.  Appending -4 to the first
form will generate V4 signatures.

"./minipgp5 < cipher.pgp [-r keyring [-p pp]]" does PGP5 decryption.

./minipgp5 cipher.pgp [-r secring [-p pp]] | ./minipgp5 | ./minipgp5 >plain.txt
decrypt cipher.pgp, using optional secring, and passphrase to plain.txt

The first instance decrypts, the second decompresses, and the third removes the
literal and checks signatures.  In all cases, secring and pubring default as
per environment or in the .pgp directory, and use .pkr and .skr extensions See
the test.sh file for an example of usage and testnp.sh for a test on systems
that don't have PGP.

new5key generates a new public key to pubnew.pkr and a new secret key to
secnew.skr using an existing set of key parameters.  Adding a "-g numbits"
parameter will generate any parameter not found in the keyring.  Note: you must
use at least -g 768 for PGP to work with it, and the the DH size will be the
number you specify, and the DSA size will be 512 (minimum) or half of the DH
size up to 1024. With "-G DSAnumbits", it will force the DSA size, but PGP will
not accept DSA signatures if this is greater than 1024 (See the top of
pgpDSAkey.c).  If no -g numbits is specified, the DH key will be twice the size
of the -G value.  The DH generator has been adjusted to avoid an attack on El
Gamal signatures, so will use a generator of 5.

[DSA and DH only need one integer to be private, the rest are special primes or
other numbers and can be used among a group of people].

"new5key -R [-g len]" will generate a new version 4 rsa key, "new5key -3 [-g
len]" will generate a version 3 rsa key, also to secnew.skr and pubnew.pkr.

The keyids can be dumped with lookup5, which works on both secret and public
keyrings, and can also be used to lookup keys, e.g.  ./lookup5 -m prz will find
any key with the string "prz".  For batch files, ... -k `./lookup5 -e -m prz`
... will return the hex encryption key to be entered as a parameter, and -s
would return the signing key instead.  ./lookup5 -r secring.skr -u "user id" -x
is used to extract key material for signing.

Going the other way, use:

./minipgp5 -l plain.txt <plain.txt | ./minipgp5 -z | \
 ./minipgp5 -k DHkeyid [-r keyring]

the first minipgp5 encapsulates the file in a literal packet with the new
format.  minipgp5 -z does the compression, and the final ./minipgp5 -k keyid
does the actual encryption.

TESTING

testnp.sh does a feedback selftest on every algorithm.

test.sh tests the code against "normal" pgp5.0, i.e. without RSA, RIPEMD-160,
and only DSA signatures.

testwrsa.sh tests against a full PGP5.0 with RIPEMD-160, RSA, and
ElGamal signatures, including DSA/MD5 and DSA/RIPEMD-160

testnp.sh is standalone to check algorithms that PGP5 doesn't support.

twv4rsa.sh tries V4 rsa keys, and test262 tests for old pgp compatibility.

test262.sh checks for V3 compatability.

The tests do not include looking for failures on intentionally bad encryptions
or signatures.

OTHER NOTES

minipgp5 has an [-a algorithm] parameter, which is the numeric representation
of the algorithm.  Warning: I don't bounds check everywhere so you may get
SIGSEGV if you specify an invalid value.  For pgp5enc, 1=IDEA, 2=DES, 3=CAST.
For minipgp5, 1=MD5, 2=SHA, 3=RIPEM.  The defaults are IDEA and SHA.  minipgp5
also has "-A alg", 1 is for RSA, 16 is for El Gamal (-A 17 is DSA, the
default). minipgp5 has -A with 1 doing RSA if it is compiled to do so.

Other numbers can be found in the OpenPGP spec.

Note: With a weakness reported in El Gamal signatures, I have altered the
generators and the signature checking code to try to avoid this, but it will
create different values or may reject signatures from PGP based DH parameters.

Added are -x salt-alg -y hash-alg -s pp-conv-alg, for use in conventional
encryption (-C for passphrase encrypted key, -c to use the passphrase as the
key).  Look at the source or use -h for more details as this README isn't
updated as often.

The PGP5.0b8 version of pgpv will report a bad signature with anything except
SHA, since that is part of the Digital Signature Standard.  (pgp has a test in
dsaVerify rejecting everything except SHA for the hash algorithm, otherwise
DSA/MD5 or DSA/RIPEMD would work).

I haven't been as careful about wiping memory and preventing memory leaks and
other things to make the code robust.  Nor have I tried to make any of my code
thread safe, since I currently don't have such applications and would leave
that to the experts.

The keyring structure has been complicated further, so I don't do anything with
that internally (but can extract and sign key material for compatibility), but
assume you can use pgpk or manually examine the signatures or be careful what
you put on the keyring.

BACKWARDS (2.6.x) COMPATIBILITY:

tooldctb changes the Cipher Type format from new "to old ctb" format.  Note
that while it uses stdin/out, except for compression it must be in the form of
a file (to seek and insert the length back at the beginning of the packet).

For PGP2,

literal:
./minipgp5 -i plain -l plain -o step.1
./tooldctb <step.1 >step.2

(optional signature steps):
./minipgp5 -i plain -3 -A 1 -a 1 -t 1 -o step.sig
(at this point step.sig is a correct 2.x detached sig)
cat step.2 >> step.sig #append literal to sig
mv step.sig step.2

compression:
./minipgp5 -i step.2 -z -o step.3
./tooldctb <step.3 >step.4

conventional:
#the following combination omits the SKESK as everything is the default
./minipgp5 -i step.4 -x 0 -y 1 -s 1 -a 1 -c -p testpass -o step.5
./tooldctb <step.5 >cipher.pgp

or, PK, rsa:
./minipgp5 -i step.4 -A 1 -a 1 -k <rsakey> -o step.5
./tooldctb <step.5 >cipher.pgp
