mirror of git://git.gnupg.org/gnupg.git
362 lines
11 KiB
Plaintext
362 lines
11 KiB
Plaintext
|
|
GNUPG - The GNU Privacy Guard
|
|
-------------------------------
|
|
|
|
THIS IS ALPHA SOFTWARE, EXPECT BUGS AND UNIMPLEMENTED STUFF.
|
|
IT MAY HAPPEN THAT SOME DATA FORMATS OR PROGRAMM OPTIONS
|
|
CHANGE WITH THE NEXT VERSION.
|
|
|
|
On a Linux box (version 2.x.x, alpha or x86 CPU) it should
|
|
work reliable. You may create your key on such a machine and
|
|
use it. Please verify the tar file; there is a PGP and a GNUPG
|
|
signature available. My PGP key is well known and published in
|
|
the "Global Trust Register for 1998", ISBN 0-9532397-0-5.
|
|
|
|
I have included my pubring as "g10/pubring.asc", which contains
|
|
the key used to make GNUPG signatures:
|
|
"pub 1312G/FF3EAA0B 1998-02-09 Werner Koch <wk@isil.d.shuttle.de>"
|
|
"Key fingerprint = 8489 6CD0 1851 0E33 45DA CD67 036F 11B8 FF3E AA0B"
|
|
|
|
You may add it to your GNUPG pubring and use it in the future to
|
|
verify new releases. Because you verified the tar file containing
|
|
this file here, you can be sure that the above fingerprint is correct.
|
|
|
|
|
|
Please subscribe to g10@net.lut.ac.uk by sending a mail with
|
|
the word "subscribe" in the body to "g10-request@net.lut.ac.uk".
|
|
|
|
See the file COPYING for copyright and warranty information.
|
|
|
|
Due to the fact that GNUPG does not use use any patented algorithm,
|
|
it cannot be compatible to old PGP versions, because those use
|
|
IDEA (which is worldwide patented) and RSA (which is patented in
|
|
the United States until Sep 20, 2000). I'm sorry about this, but
|
|
this is the world we have created (e.g. by using proprietary software).
|
|
|
|
|
|
Because the OpenPGP standard is still a draft, GNUPG is not yet
|
|
compatible to it (or PGP 5) - but it will. The data structures
|
|
used are compatible with PGP 2.x, so it can parse an list such files
|
|
and PGP should be able to parse data created by GNUPG and complain
|
|
about unsupported algorithms.
|
|
|
|
The default algorithms used by GNUPG are ElGamal for public-key
|
|
encryption and signing; Blowfish with a 160 bit key for protecting
|
|
the secret-key components, conventional and session encryption;
|
|
RIPE MD-160 to create message digest. DSA, SHA-1 and CAST are
|
|
also implemented, but not used on default. I decided not
|
|
to use DSA as default signing algorithm, because it allows only for
|
|
1024 bit keys and this may be not enough in a couple of years.
|
|
|
|
|
|
|
|
Installation
|
|
------------
|
|
|
|
See the file INSTALL. Here is a quick summary:
|
|
|
|
1) "./configure"
|
|
|
|
2) "make"
|
|
|
|
3) "make install"
|
|
|
|
4) You end up with a binary "gpg" in /usr/local/bin
|
|
|
|
5) Optional, but suggested: install the program "gpg" as suid root.
|
|
|
|
|
|
|
|
Key Generation
|
|
--------------
|
|
|
|
gpg --gen-key
|
|
|
|
This asks some questions and then starts key generation. To create
|
|
good random numbers for prime number generation, it uses a /dev/random
|
|
which will emit only bytes if the kernel can gather enough entropy.
|
|
If you see no progress, you should start some other activities such
|
|
as mouse moves, "find /" or using the keyboard (on another window).
|
|
Because we have no hardware device to generate random we have to use
|
|
this method.
|
|
|
|
Key generation shows progress by printing different characters to
|
|
stderr:
|
|
"." Last 10 Miller-Rabin tests failed.
|
|
"+" Miller-Rabin test succeeded.
|
|
"!" Reloading the pool with fresh prime numbers
|
|
"^" Checking a new value for the generator
|
|
"<" Size of one factor decreased
|
|
">" Size of one factor increased
|
|
|
|
The prime number for ElGamal is generated this way:
|
|
|
|
1) Make a prime number q of 160, 200, 240 bits (depending on the keysize).
|
|
2) Select the length of the other prime factors to be at least the size
|
|
of q and calculate the number of prime factors needed
|
|
3) Make a pool of prime number, each of the length determined in step 2
|
|
4) Get a new permutation out of the pool or continue with step 3
|
|
if we have tested all permutations.
|
|
5) Calculate a candidate prime p = 2 * q * p[1] * ... * p[n] + 1
|
|
6) Check that this prime has the correct length (this may change q if
|
|
it seems not to be possible to make a prime of the desired length)
|
|
7) Check whether this is a prime using trial divisions and the
|
|
Miller-Rabin test.
|
|
8) Continue with step 4 if we did not find a prime in step 7.
|
|
9) Find a generator for that prime.
|
|
|
|
You should make a revocation certificate in cases someone gets
|
|
knowledge of your secret key or you forgot your passphrase:
|
|
|
|
gpg --gen-revoke your_user_id
|
|
|
|
Run this command and store it away; output is always ASCII armored,
|
|
so that you can print it and (hopefully never) re-create it if
|
|
your electronic media fails.
|
|
|
|
|
|
You can sign a key with this command:
|
|
|
|
gpg --sign-key Donald
|
|
|
|
This let you sign the key of "Donald" with your default userid.
|
|
|
|
gpg --sign-key -u Karl -u Joe Donald
|
|
|
|
This let you sign the key of of "Donald" with the userids of "Karl"
|
|
and "Joe".
|
|
All existing signatures are checked, if some are invalid, a menu is
|
|
offered to delete some of them, and the you are asked for every user
|
|
wether you want to sign this key.
|
|
|
|
You may remove a signature at any time using the option "--edit-sig",
|
|
which asks for the sigs to remove. Self-signatures are not removable.
|
|
|
|
|
|
|
|
|
|
Sign
|
|
----
|
|
|
|
gpg -s file
|
|
|
|
This creates a file file.gpg which is compressed and has a signature
|
|
attached.
|
|
|
|
gpg -sa file
|
|
|
|
Same as above, but file.gpg is ascii armored.
|
|
|
|
gpg -s -o out file
|
|
|
|
Creates a signature of file, but writes the output to the file "out".
|
|
|
|
|
|
Encrypt
|
|
-------
|
|
|
|
gpg -e -r heine file
|
|
|
|
This encrypts files with the public key of "heine" and writes it
|
|
to "file.gpg"
|
|
|
|
echo "hallo" | gpg -ea -r heine | mail heine
|
|
|
|
Ditto, but encrypts "hallo\n" and mails it as ascii armored message.
|
|
|
|
|
|
Sign and Encrypt
|
|
----------------
|
|
|
|
gpg -se -r heine file
|
|
|
|
This encrypts files with the public key of "heine" and writes it
|
|
to "file.gpg" after signing it with the default user id.
|
|
|
|
|
|
gpg -se -r heine -u Suttner file
|
|
|
|
Ditto, but sign the file with the user id "Suttner"
|
|
|
|
|
|
Keyring Management
|
|
------------------
|
|
To export your complete keyring(s) do this:
|
|
|
|
gpg --export
|
|
|
|
To export only some user ids do this:
|
|
|
|
gpg --export userids
|
|
|
|
Use "-a" or "--armor" to create ASCII armored output.
|
|
|
|
Importing keys is done with the option, you guessed it, "--import":
|
|
|
|
gpg --import [filenames]
|
|
|
|
New keys are appended to the default keyring and already existing
|
|
keys are merged. Keys without a self-signature are ignored.
|
|
|
|
|
|
How to Specify a UserID
|
|
-----------------------
|
|
There are several ways to specify a userID, here are some examples:
|
|
|
|
* Only by the short keyid (prepend a zero if it begins with A..F):
|
|
|
|
"234567C4"
|
|
"0F34E556E"
|
|
"01347A56A"
|
|
|
|
* By a complete keyid:
|
|
|
|
"234AABBCC34567C4"
|
|
"0F323456784E56EAB"
|
|
"01AB3FED1347A5612"
|
|
|
|
* By a fingerprint (not yet implemented):
|
|
|
|
"1234343434343434C434343434343434"
|
|
"123434343434343C3434343434343734349A3434"
|
|
"0E12343434343434343434EAB3484343434343434"
|
|
|
|
The first one is MD5 the others are ripemd160 or sha1.
|
|
|
|
* By an exact string (not yet implemented):
|
|
|
|
"=Heinrich Heine <heinrichh@uni-duesseldorf.de>"
|
|
|
|
* By an email address:
|
|
|
|
"<heinrichh@uni-duesseldorf.de>"
|
|
|
|
This can be used by a keyserver instead of a substring to
|
|
find this key faster.
|
|
|
|
* By the Local ID (from the trustdb):
|
|
|
|
"#34"
|
|
|
|
This can be used by a MUA to specify an exact key after selecting
|
|
a key from GNUPG (by the use of a special option or an extra utility)
|
|
|
|
|
|
* Or by the usual substring:
|
|
|
|
"Heine"
|
|
"*Heine"
|
|
|
|
The '*' indicates substring search explicitly.
|
|
|
|
|
|
|
|
|
|
Batch mode
|
|
----------
|
|
If you use the option "--batch", GNUPG runs in non-interactive mode and
|
|
never prompts for input data. This even does not allow to enter
|
|
passphrase; until we have a better solution (something like ssh-agent),
|
|
you can use the option "--passhrase-fd n", which works like PGPs
|
|
PGPPASSFD.
|
|
|
|
Batch mode also causes GNUPG to terminate as soon as a BAD signature is
|
|
detected.
|
|
|
|
|
|
Exit status
|
|
-----------
|
|
GNUPG returns with an exit status of 1 if in batch mode and a bad signature
|
|
has been detected or 2 or higher for all other errors. You should parse
|
|
stderr to get detailed informations about the errors.
|
|
|
|
|
|
Esoteric commands
|
|
-----------------
|
|
|
|
gpg --list-packets datafile
|
|
|
|
Use this to list the contents of a data file. If the file is encrypted
|
|
you are asked for the passphrase, so that GNUPG is able to look at the
|
|
inner structure of a encrypted packet.
|
|
|
|
gpgm --quick-random
|
|
|
|
Do not use the stroing random generator but a faster one. This can be
|
|
used to generate keys for tests; those are marked as insecure.
|
|
|
|
gpgm --list-trustdb
|
|
|
|
List the contents of the trustdb in a human readable format
|
|
|
|
gpgm --list-trustdb <usernames>
|
|
|
|
List the tree of certificates for the given usernames
|
|
|
|
gpgm --list-trust-path depth username
|
|
|
|
List the possible trust paths for the given username, up to the specified
|
|
depth. If depth is negative, duplicate introducers are not listed,
|
|
because those would increase the trust probabilty only minimal.
|
|
(you must use the special option "--" to stop option parsing when
|
|
using a negative number). This option may create new entries in the
|
|
trustdb.
|
|
|
|
gpgm --print-mds filenames
|
|
|
|
List all available message digest values for the fiven filenames
|
|
|
|
gpgm --gen-prime n
|
|
|
|
Generate and print a simple prime number of size n
|
|
|
|
gpgm --gen-prime n q
|
|
|
|
Generate a prime number suitable for ElGamal signatures of size n with
|
|
a q as largest primefactor of n-1.
|
|
|
|
gpgm --gen-prime n q 1
|
|
|
|
Ditto, but calculate a generator too.
|
|
|
|
|
|
For more options/commands see the file g10/OPTIONS, or use "gpg --help"
|
|
|
|
|
|
Debug Flags
|
|
-----------
|
|
Use the option "--debug n" to output debug informations. This option
|
|
can be used multiple times, all values are ORed; n maybe prefixed with
|
|
0x to use hex-values.
|
|
|
|
value used for
|
|
----- ----------------------------------------------
|
|
1 packet reading/writing
|
|
2 MPI details
|
|
4 ciphers and primes (may reveal sensitive data)
|
|
8 iobuf filter functions
|
|
16 iobuf stuff
|
|
32 memory allocation stuff
|
|
64 caching
|
|
128 show memory statistics at exit
|
|
256 trust verification stuff
|
|
|
|
|
|
Other Notes
|
|
-----------
|
|
This is work in progress, so you may find duplicated code fragments,
|
|
ugly data structures, weird usage of filenames and other thinks.
|
|
I will run "indent" over the source when making a real distribution,
|
|
but for now I stick to my own formatting rules.
|
|
|
|
The primary FTP site is "ftp://ftp.guug.de/pub/gcrypt/"
|
|
The primary WWW page is "http://www.d.shuttle.de/isil/crypt/gnupg.html"
|
|
|
|
If you like, send your keys to <gnupg-keys@isil.d.shuttle.de>; use
|
|
"gnupg --export --armor | mail gnupg-keys@isil.d.shuttle.de" to do this.
|
|
|
|
Please direct bug reports to <gnupg-bugs@isil.d.shuttle.de> or better
|
|
post them to the mailing list <g10@net.lut.ac.uk>.
|
|
|
|
|