Pegwit v8 manual
================

Introduction
============

Pegwit is a program for performing public key file encryption
and authentication.

Encryption means that pegwit allows you to keep the information
in files you send by email (or other means) confidential.
Eavesdroppers will not be able to read the email.

Authentication allows you to check that a file has not been
tampered with (changed) since it was signed.

Installation
============
There is no installation process - all you need is an
executable, e.g. pegwit.exe. Pegwit is a 'command line'
program - if you are using Windows 95 you first need
to start a DOS shell. Running pegwit with no parameters
will cause a brief summary of the command syntax to be
output.

The summary reads:

Pegwit v8.x
Usage (init/encrypt/decrypt/sign/verify) :
-i <secret-key >public-key
-e public-key plain cipher <random-junk
-d cipher plain <secret-key
-s plain <secret-key >signature
-v public-key plain <signature
-E plain cipher <key
-D cipher plain <key
-S plain <secret-key >clearsigned-text
-V public-key clearsigned-text
-f[operation] [type pegwit -f for details]


This summary is also output if you supply the wrong
number of parameters, or if the first parameter is not
correct. Note that -E,-D,-S,-V are distinct from -e,-d,-s,-v.

The '<' and '>' characters indicate where pegwit
requires standard input, and where it generates
standard output.

Choosing a secret key
=====================
To start with you need decide on a secret key. Your secret
key needs to be unguessable by a cracking program even with
a very large number of attempts. For the purpose of this
manual, the secret key "hello there" (plus a newline) will
be used. Obviously "hello there" is a rotten choice for a
secret key, it is far too easy to guess. You should use a
much better key than this.

Note that pegwit (unlike for instance PGP) does not generate
secret random keys internally - the secret key is *not* just
a pass phrase which protects a stored key. Your secret key
should be at least 10 characters, and more if the characters
are not random (for example words), or if you might be up
against a determined snooper with considerable computing
resources.

Pegwit reads secret values from standard input.
If standard input is not redirected, you will need to
terminate input by using CTRL-Z (this may vary on different
operating systems). After using your secret key, you should 
clear the screen, for example by using the cls clear screen 
command (on DOS/Win95) or by entering several blank lines.

Creating your public key
========================
Your public key is created using the pegwit -i command.
For example, at a command prompt, try:

pegwit -i > my.pub
hello there
CTRL-Z

Now inspect the file my.pub (e.g. type my.pub)
It should contain the text

pegwit v8 public key =cc23ea8bc28aac71ee19befcb2beba4b349cbdc020965e2411d48f6dfa
28f4fd

Encryption
==========
To encrypt a file, you need a public key. Normally this will
not be your own public key, but for example the public key
of a friend who you are emailing a confidential file.

There are many possible ways you could obtain this, but
it is important to guard against forgery, that is a
public key which claims to be for your friend, but
actually is generated by someone who wishes to snoop
on your mail.

If in doubt ( when there is a lot at stake ) check the public
key by making telephone call. This should be good enough for
most purposes, provided you can recognise your friend over
the telephone. If possible, check using multiple methods and
sources.

There are also more sophisticated ways of checking, using
digital signatures of trusted third parties.

For the moment though, create a text file which contains the
text (say) 'I love you', and try

pegwit -e my.pub test.txt text.tx0
any old random junk
CTRL-Z

Notice that pegwit reads some random input as well as
a public key. The reason is that pegwit does not have
access to good random numbers (for portability reasons).
The junk you type does not have to be different on every
occasion, but must be unguessable by an adversary.
An attacker needs to guess the junk, the time of encryption
and the entire contents of the file being encrypted for a
successful 'crack'. [ He may make a very large number of
guesses, using a 'cracking' program, possibly aided by
well-educated human guesses ]. Alternatively he can
guess (or steal) the private key of your friend.

Decryption
==========
To decrypt a file, you use your secret key, for example
pegwit -d test.tx0 test.chk
hello there
CTRL-Z

The contents of test.chk should now be be identical
to the contents of test.txt.

Signing a file
==============
To sign a file, you use your secret key. This means that
nobody else can forge your signatures.

For example try

pegwit -s test.txt >test.sig
hello there
CTRL-Z

Verifying a signature
=====================
To verify a signature, you use the public key of the signer.
As for encryption (the other public key operation) you need
to be sure the public key is not a forgery.

For example try

pegwit -v my.pub test.txt <test.sig

Pegwit should just return quietly (this means the signature is OK).

Now make a small modification to test.txt, and try again.
Now pegwit should output 'signature did not verify'

Utilities
=========
If you are using Win95, pwkey and pwjunk are simple
utilities intended to be used for entering secret keys 
and random junk. 

pwkey has the advantage that keys are not echoed to the
screen, for example use

pwkey | pegwit -s test.txt >test.sig

pwjunk uses key timings to increase the randomness of 
the output.

For example, you can use
pwjunk | pegwit -e my.pub test.txt test.tx0

pwjunk estimates how much 'randomness' has been
generated, and does not allow input to be terminated
until the estimate reachs 128 bits.

More security considerations ( getting paranoid )
=================================================
You should not use your secret key on a computer to
which an enemy may have had access, either physically
or remotely via modems, networks, viruses etc. In practice
this is a risk you may have to live with. You may choose
to have several secret keys, using the highest grade secret
key only under the most secure conditions. There is no
substitute for keeping the computer(s) you use physically
secure.

Symmetric encryption
====================
-E and -D can be used for conventional (non public-key) encryption. 
These commands are slightly faster, and the encrypted file is 32 bytes 
smaller. 

-E can be useful for distributing a large file to several people.
Use pegwit -s to generate a signature for the large file, then 
use -E to encrypt the file using the signature as the key. 
The encrypted large file can now be put in a public FTP area.
Now send the signature to each person, encrypted with their public key. 

Note that keys have to be larger to achieve the same level of 
security as -e, so the use of -E is not recommended for keys 
which are entered manually.

Signing text files
==================
When using pegwit with email and usenet, the -S and -V commands
may be more convenient. -S reads the input file as text lines,
and outputs text with delimiters and the signature appended to
the text.

Filtering and ascii armoring of encrypted files
===============================================
pegwit -fX where X is a normal command gives a set of
commands which act as filters. In addition, encrypted
output is converted to ascii, and encrypted input is
also expected to be in ascii form. Secret values are
read from a file, rather than standard input.

The manual for the -f variants is output when pegwit 
is run with just -f, and is as follows:

Pegwit v8.x [filter sub-mode]
Usage (encrypt/decrypt/sign/verify) :
-fe public-key random-junk <plain >ascii-cipher
-fd secret-key <ascii-cipher >plain
-fE key <plain >ascii-cipher
-fD key <ascii-cipher >plain
-fS secret-key <plain >clearsigned-text
-fV public-key <clearsigned-text >plain

Note that 'plain' files read from standard input
should not be binary ( this also applies to 
the -S command ), although on some UNIX-like systems
binary files may work OK (but the result will not
be portable, especially to Windows/MSDOS, due to
CR/LF translation ).

George Barwood