+ The GNU Privacy Guard 2
+ =========================
+ Version 1.9.x
- GNUPG - The GNU Privacy Guard
- -------------------------------
- THIS IS ALPHA SOFTWARE, YOU MAY ENCOUNTER SOOME BUGS.
+GnuPG 1.9 is the future version of GnuPG; it is based on the gnupg-1.3
+code and the previous newpg package. It will eventually lead to a
+GnuPG 2.0 release. Note that GnuPG 1.3 and 1.9 are not always in sync
+and thus features and bug fixes done in 1.3 are not necessary
+available in 1.9.
- On a Linux box (version 2.x.x, alpha or x86 CPU) it should
- work reliably. 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"
+BUILD INSTRUCTIONS
+==================
- 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.
+GnuPG 1.9 depends on the following packages:
- 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".
+ libgpg-error (ftp://ftp.gnupg.org/gcrypt/alpha/libgpg-error/)
+ libgcrypt (ftp://ftp.gnupg.org/gcrypt/alpha/libgcrypt/)
+ libassuan (ftp://ftp.gnupg.org/gcrypt/alpha/libassuan/)
+ libksba (ftp://ftp.gnupg.org/gcrypt/alpha/libksba/)
+
+You also need the pinentry package for most function of GnupG; however
+it is not a build requirement. pinentry is available at
+ftp://ftp.gnupg.org/gcrypt/pinentry/ .
- See the file COPYING for copyright and warranty information.
+You should get the latest versions of course, the GnuPG configure
+script complains if a version is not sufficient.
- Due to the fact that GNUPG does not use use any patented algorithm,
- it cannot be compatible with old PGP versions, because those use
- IDEA (which is patented worldwide) 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).
+After building and installing the above packages in the order as given
+above, you may now continue with GnupG installation (you may also just
+try to build GnuPG to see whether your already installed versions are
+sufficient).
- Because the OpenPGP standard is still a draft, GNUPG is not yet
- compatible with it (or PGP 5) - but it will be. The data structures
- used are compatible with PGP 2.x, so it can parse and list such files
- and PGP should be able to parse data created by GNUPG and complain
- about unsupported algorithms.
+As with all packages, you just have to do
- The default algorithms used by GNUPG are ElGamal for public-key
- encryption and signing; Blowfish with a 128 bit key for protecting
- the secret-key components, conventional and session encryption;
- RIPE MD-160 to create message digest. DSA, SHA-1, CAST and TIGER are
- also implemented, but not used by default. I decided not
- to use DSA as the default signing algorithm, because it allows only
- for 1024 bit keys and this may not be enough in a couple of years.
+ ./configure
+ make
+ make install
+(Before doing install you might need to become root.)
+If everything succeeds, you have a working GnuPG with support for
+S/MIME and smartcards. Note that there is no binary gpg but a gpg2 so
+that this package won't confict with a GnuPG 1.2 or1.3
+installation. gpg2 behaves just like gpg and it is possible to symlink
+oto gpg if you want to use gpg 1.9.
- Installation
- ------------
+In case of problem please ask on gpa-dev@gnupg.org for advise. Note
+that this release is only expected to build on GNU and *BSD systems.
- See the file INSTALL. Here is a quick summary:
+A texinfo manual named `gnupg.info' will get installed. Some commands
+and options given below. See also the section `SMARTCARD INTRO'.
- 1) "./configure"
- 2) "make"
+COMMANDS
+========
- 3) "make install"
+gpgsm:
+------
- 4) You end up with a binary "gpg" in /usr/local/bin
+--learn-card
- 5) Optional, but suggested: install the program "gpg" as suid root.
+ Read information about the private keys from the smartcard and
+ import the certificates from there.
+--export
+ Export all certificates stored in the Keybox or those specified on
+ the command line. When using --armor a few informational lines are
+ prepended before each block.
- Key Generation
- --------------
- gpg --gen-key
+gpg2:
+-----
- 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 only emit 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 (in another window).
- Because we have no hardware device to generate randomness we have to
- use this method.
+--card-status
- 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
+ Show information pertaining smartcards implementing the OpenPGP
+ application.
- The prime number for ElGamal is generated this way:
+--change-pin
- 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 numbers, 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.
+ Offers a menu to change the PIN of OpenPGP smartcards and to reset
+ the retry counters.
- You should make a revocation certificate in case someone gets
- knowledge of your secret key or you forgot your passphrase:
+--card-edit
- gpg --gen-revoke your_user_id
+ Offers a menu to change any data object on the card and to generate
+ the keys.
- 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.
+OPTIONS
+=======
- You can sign a key with this command:
+gpgsm:
+------
- gpg --sign-key Donald
+--include-certs <n>
- This let you sign the key of "Donald" with your default userid.
+ Using N of -2 includes all certificate except for the Root cert,
+ -1 includes all certs, 0 does not include any certs, 1 includes only
+ the signers cert (this is the default) and all other positives
+ values include up to N certs starting with the signer cert.
+
+--policy-file <filename>
- gpg --sign-key -u Karl -u Joe Donald
+ Chnage the deault name of the policy file
- 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 then you are asked for every user
- whether you want to sign this key.
+--enable-policy-checks
+--disable-policy-checks
- 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.
+ By default policy checks are enabled. These options may be used to
+ change it.
+--enable-crl-checks
+--disable-crl-checks
+ By default the CRL checks are enabled and the DirMngr is used to
+ check for revoked certificates. The disable option is most useful
+ with a off-line connection to suppres this check.
+--agent-program <path_to_agent_program>
- Sign
- ----
+ Specify an agent program to be used for secret key operations. The
+ default value is "../agent/gpg-agent". This is only used as a
+ fallback when the envrionment varaibale GPG_AGENT_INFO is not set or
+ a running agent can't be connected.
+
+--dirmngr-program <path_to_dirmgr_program>
- gpg -s file
+ Specify a dirmngr program to be used for CRL checks. The default
+ value is "/usr/sbin/dirmngr". This is only used as a fallback when
+ the environment varaibale DIRMNGR_INFO is not set or a running
+ dirmngr can't be connected.
- This creates a file file.gpg which is compressed and has a signature
- attached.
+--no-secmem-warning
- gpg -sa file
+ Don't print the warning "no secure memory"
- Same as above, but file.gpg is ascii armored.
+--armor
- gpg -s -o out file
+ Create PEM ecoded output. Default is binary output.
- Creates a signature of file, but writes the output to the file "out".
+--base64
+ Create Base-64 encoded output; i.e. PEM without the header lines.
- Encrypt
- -------
+--assume-armor
- gpg -e -r heine file
+ Assume the input data is PEM encoded. Default is to autodetect the
+ encoding but this is may fail.
- This encrypts files with the public key of "heine" and writes it
- to "file.gpg"
+--assume-base64
- echo "hallo" | gpg -ea -r heine | mail heine
+ Assume the input data is plain base-64 encoded.
- Ditto, but encrypts "hallo\n" and mails it as ascii armored message.
+--assume-binary
+ Assume the input data is binary encoded.
- Sign and Encrypt
- ----------------
+--server
- gpg -se -r heine file
+ Run in server mode. This is used by GPGME to control gpgsm. See
+ the assuan specification regarding gpgsm about the used protocol.
+ Some options are ignored in server mode.
- This encrypts files with the public key of "heine" and writes it
- to "file.gpg" after signing it with the default user id.
+--local-user <user_id>
+ Set the user to be used for signing. The default is the first
+ secret key found in the database.
- gpg -se -r heine -u Suttner file
+--with-key-data
- Ditto, but sign the file with the user id "Suttner"
+ Displays extra information with the --list-keys commands. Especially
+ a line tagged "grp" is printed which tells you the keygrip of a
+ key. This is string is for example used as the filename of the
+ secret key.
- Keyring Management
- ------------------
- To export your complete keyring(s) do this:
- gpg --export
+gpg-agent:
+---------
- To export only some user ids do this:
+--pinentry-program <path_to_pinentry_program>
- gpg --export userids
+ Specify the PINentry program. The default value is
+ "<prefix>/bin/pinentry" so you most likely want to specify it.
- Use "-a" or "--armor" to create ASCII armored output.
+--no-grab
- Importing keys is done with the option, you guessed it, "--import":
+ Tell the pinentry not to grab keybourd and mouse. You most likely
+ want to give this option during testing and development to avoid
+ lockups in case of bugs.
- gpg --import [filenames]
+
+scdaemon:
+--------
- New keys are appended to the default keyring and already existing
- keys are merged. Keys without a self-signature are ignored.
+--ctapi-driver <libraryname>
+ The default for Scdaemon is to use the PC/SC API currently provided
+ by libpcsclite.so. As an alternative the ctAPI can be used by
+ specify this option with the appropriate driver name
+ (e.g. libtowitoko.so).
- How to Specify a UserID
- -----------------------
- There are several ways to specify a userID, here are some examples:
+--reader-port <portname>
- * Only by the short keyid (prepend a zero if it begins with A..F):
+ This specifies the port of the chipcard reader. For PC/SC this is
+ currently ignored and the first PC/SC reader is used. For the
+ ctAPI, a number must be specified (the default is 32768 for the
+ first USB port).
- "234567C4"
- "0F34E556E"
- "01347A56A"
- "0xAB123456
+--disable-ccid
- * By a complete keyid:
+ Disable the integrated support for CCID compliant readers. This
+ allows to fall back to one of the other drivers even if the internal
+ CCID driver can handle the reader. Note, that CCID support is only
+ available if libusb was available at build time.
- "234AABBCC34567C4"
- "0F323456784E56EAB"
- "01AB3FED1347A5612"
- "0x234AABBCC34567C4"
- * By a fingerprint:
+FILES
+=====
- "1234343434343434C434343434343434"
- "123434343434343C3434343434343734349A3434"
- "0E12343434343434343434EAB3484343434343434"
+The default home directory is ~/.gnupg. It can be changed by
+either the --homedir option or by seting the environment variable
+GNUPGHOME. This is a list of files usually found in this directory:
- The first one is MD5 the others are ripemd160 or sha1.
+gpgsm.conf
- * By an exact string (not yet implemented):
+ Options for gpgsm. Options are the same as the command line
+ options but don't enter the leading dashes and give arguments
+ without an equal sign. Blank lines and lines starting with a
+ hash mark as the first non whitye space character are ignored.
- "=Heinrich Heine <heinrichh@uni-duesseldorf.de>"
+gpg-agent.conf
+
+ Options for gpg-agent
- * By an email address:
+scdaemon.conf
- "<heinrichh@uni-duesseldorf.de>"
+ Options for scdaemon.
- This can be used by a keyserver instead of a substring to
- find this key faster.
+dirmngr.conf
- * By the Local ID (from the trustdb):
+ Options for the DirMngr which is not part of this package and
+ the option file wilol most likely be moved to /etc
- "#34"
+gpg.conf
+
+ Options for gpg. Note that old versions of gpg use the
+ filename `options' instead of `gpg.conf'.
- 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)
+gpg.conf-1.9.x
+ Options for gpg; tried before gpg.conf
- * Or by the usual substring:
- "Heine"
- "*Heine"
+policies.txt
- The '*' indicates substring search explicitly.
+ A list of allowed CA policies. This file should give the
+ object identifiers of the policies line by line. Empty lines
+ and lines startung with a hash mark are ignored.
+ ++++++++++
+ 2.289.9.9
+ ++++++++++
+trustlist.txt
+ A list of trusted certificates usually maintained by
+ gpg-agent. It can however be edited manually. The file will
+ be created automagically with some explaining comments.
- Batch mode
- ----------
- If you use the option "--batch", GNUPG runs in non-interactive mode and
- never prompts for input data. This does not even allow entering the
- passphrase; until we have a better solution (something like ssh-agent),
- you can use the option "--passhrase-fd n", which works like PGPs
- PGPPASSFD.
+random_seed
- Batch mode also causes GNUPG to terminate as soon as a BAD signature is
- detected.
+ Used internally for keeping the state of the RNG over
+ invocations.
+pubring.kbx
- 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 or the output of the fd specified with --status-fd to get detailed
- information about the errors.
+ The database file with the certificates.
+pubring.gpg
- Esoteric commands
- -----------------
+ The database file with the OpenPGP public keys. This will
+ eventually be merged with pubring.kbx
- gpg --list-packets datafile
+secring.gpg
- 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.
+ The database file with the OpenPGP secret keys. This will be
+ removed when gpg is changed to make use of the gpg-agent.
- gpgm --list-trustdb
- List the contents of the trustdb in a human readable format
+private-keys-v1.d/
- gpgm --list-trustdb <usernames>
+ Directory holding the private keys maintained by gpg-agent.
+ For detailed info see agent/keyformat.txt. Note that there is
+ a helper tool gpg-protect-tool which may be used to protect or
+ unprotect keys. This is however nothing a user should care
+ about.
- List the tree of certificates for the given usernames
- gpgm --list-trust-path depth username
+SOURCE FILES
+============
- 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 probability only minimally.
- (you must use the special option "--" to stop option parsing when
- using a negative number). This option may create new entries in the
- trustdb.
+Here is a list of directories with source files:
- gpgm --print-mds filenames
+jnlib/ utility functions
+kbx/ keybox library
+g10/ the gpg program here called gpg2
+sm/ the gpgsm program
+agent/ the gpg-agent
+scd/ the smartcard daemon
+doc/ documentation
- List all available message digest values for the fiven filenames
- gpgm --gen-prime n
- Generate and print a simple prime number of size n
+HOW TO SPECIFY A USER ID
+========================
- gpgm --gen-prime n q
+Due to the way X.509 certificates are made up we need a few new ways
+to specify a certificate (aka key in OpenPGP). In addition to the
+ways a user ID can be specified with gpg, I have implemented 3 new
+modes for gpgsm, here is the entire list of ways to specify a key:
- Generate a prime number suitable for ElGamal signatures of size n with
- a q as largest prime factor of n-1.
+ * By keyID.
- gpgm --gen-prime n q 1
+ This format is deducded from the length of the string and its
+ content or "0x" prefix. For use with OpenPGP a exclamation mark may
+ be appended to force use of the specified (sub)key.
- Ditto, but calculate a generator too.
+ As with v34 OpenPGP keys, the keyID of an X509 certificate are the
+ low 64 bits of the SHA-1 fingerprint. The use of keyIDs is just a
+ shortcut, for all automated processing the fingerprint should be
+ used.
+ Examples:
- For more options/commands see the file g10/OPTIONS, or use "gpg --help"
+ 234567C4
+ 0F34E556E
+ 01347A56A
+ 0xAB123456
+ 234AABBCC34567C4
+ 0F323456784E56EAB
+ 01AB3FED1347A5612
+ 0x234AABBCC34567C4
- Debug Flags
- -----------
- Use the option "--debug n" to output debug information. This option
- can be used multiple times, all values are ORed; n maybe prefixed with
- 0x to use hex-values.
+ * By fingerprint
- 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
+ This is format is deduced from the length of the string and its
+ content or "0x" prefix. Note, that only the 20 byte fingerprint is
+ used with GPGSM (SHA-1 hash of the certificate). For use with
+ OpenPGP a exclamation mark may be appended to force use of the
+ specified (sub)key.
+ Examples:
- Other Notes
- -----------
- This is work in progress, so you may find duplicated code fragments,
- ugly data structures, weird usage of filenames and other things.
- I will run "indent" over the source when making a real distribution,
- but for now I stick to my own formatting rules.
+ 1234343434343434C434343434343434
+ 123434343434343C3434343434343734349A3434
+ 0E12343434343434343434EAB3484343434343434
+ 0xE12343434343434343434EAB3484343434343434
+
+ * Exact match on OpenPGP user ID
+
+ This is denoted by a leading equal sign. It does not make much
+ sense for X.509.
+
+ Example:
+
+ =Heinrich Heine <heinrichh@uni-duesseldorf.de>
+
+ * Exact match on an email address.
+
+ This is indicated by enclosing the email address in the usual way
+ with left and right angles
+
+ Example:
+
+ <heinrichh@uni-duesseldorf.de>
+
+ * Word match
+
+ All words must match exactly (not case sensitive) but can appear in
+ any order in the user ID or a subjects name. Words are any
+ sequences of letters, digits, the underscore and all characters
+ with bit 7 set.
+
+ Example:
+
+ +Heinrich Heine duesseldorf
+
+ * [NEW] Exact match by subject's DN
+
+ This is indicated by a leading slash, directly followed by the
+ rfc2253 encoded DN of the subject. Note that you can't use the
+ string printed by "gpgsm --list-keys" because that one as been
+ reordered and modified for better readability; use --with-colons to
+ print the raw (but standard escaped) rfc2253 string
+
+ Example:
+
+ /CN=Heinrich Heine,O=Poets,L=Paris,C=FR
+
+ * [NEW] Excact match by issuer's DN
+
+ This is indicated by a leading hash mark, directly followed by a
+ slash and then directly followed by the rfc2253 encoded DN of the
+ issuer. This should return the Root cert of the issuer. See note
+ above.
+
+ Example:
+
+ #/CN=Root Cert,O=Poets,L=Paris,C=FR
+
+ * [NEW] Exact match by serial number and subject's DN
+
+ This is indicated by a hash mark, followed by the hexadecmal
+ representation of the serial number, the followed by a slahs and
+ the RFC2253 encoded DN of the issuer. See note above.
+
+ Example:
+
+ #4F03/CN=Root Cert,O=Poets,L=Paris,C=FR
+
+ * Substring match
+
+ By case insensitive substring matching. This is the default mode
+ but applications may want to explicitly indicate this by putting
+ the asterisk in front.
+
+ Example:
+
+ Heine
+ *Heine
+
+
+Please note that we have reused the hash mark indentifier which was
+used in old GnuPG versions to indicate the so called local-id. It is
+not anymore used and there should be no conflict when used with X.509
+stuff.
+
+Using the rfc2253 format of DNs has the drawback that it is not
+possible to map them back to the original encoding, however we don't
+have to do this, because our key database stores this encoding as meta
+data.
+
+Some of the search modes are not yet implemented ;-)
+
+
+HOW TO IMPORT A PRIVATE KEY
+===========================
+There is some limited support to import a private key from a PKCS-12
+file.
+
+ gpgsm --import foo.p12
+
+This require that the gpg-agent is running.
+
+
+HOW TO EXPORT A PRIVATE KEY
+===========================
+There is also limited support to export a private key in PKCS-12
+format. However the certificate is not stored and there is no MAC applied.
+
+ gpgsm --call-protect-tool --p12-export foo.key >foo.p12
+
+
+SMARTCARD INTRO
+===============
+
+GPG, the OpenPGP part of GnuPG, supports the OpenPGP smartcard
+(surprise!); see http://g10code.com/p-card.html.
+
+[Fixme: We need to explain this further]
+
+
+GPGSM, the CMS (S/MIME) part of GnuPG, supports two kinds of
+smartcards. The most flexible way is to use PKCS#15 compliant cards,
+however you must have build GnuPG with support for the OpenSC library.
+The build process automagically detects the presence of this library
+and will include support for these cards.
+
+The other card we currently support is the Telesec NetKey card with
+the NKS 2.0 card application.
+
+Before GPGSM can make use of a new card it must gather some
+information, like the card's serial number, the public keys and the
+certificates stored on the card. Thus for a new card you need to run
+the command
+
+ gpgsm --learn-card
+
+once. This is also a good test to see whether your card reader is
+properly installed. See below in case of error. Once this has been
+done you may use the keys stored on the card in the same way you use
+keys stored on the disk. gpgsm automagically knows whether a card is
+required and will pop up the pinentry to ask you to insert the
+correct card.
+
+For selecting the driver, see the options of scdaemon. A useful
+debugging flag is "--debug 2048" showing the communication between
+scdaemon and the reader.
+
+[fixme: write more stuff]
- 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
- "gpg --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>.
projects / gnupg.git / blobdiff