- GNUPG - The GNU Privacy Guard
- -------------------------------
- Version 0.3
+ The GNU Privacy Guard 2
+ =========================
+ Version 1.9.x
- WARNING: IF YOU ARE ALREADY USING GNUPG YOU SHOULD NOW MAKE A BACKUP
- OF "gpg" BECAUSE YOU NEED IT TO CONVERT YOUR PASSPHRASE AND OTHER
- THINGS - SEE "NEWS"!
+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.
- As you can see from the version number, the program may have some
- bugs and some features may not work at all - please report this to
- the mailing list.
- 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 2 key is well known and published in
- the "Global Trust Register for 1998", ISBN 0-9532397-0-5.
+BUILD INSTRUCTIONS
+==================
- I have included my pubring as "g10/pubring.asc", which contains
- the key used to make GNUPG signatures:
- "pub 1024D/57548DCD 1998-07-07 Werner Koch (gnupg sig) <dd9jn@gnu.org>"
- "Key fingerprint = 6BD9 050F D8FC 941B 4341 2DCC 68B7 AB89 5754 8DCD"
+GnuPG 1.9 depends on the following packages:
- Old version of gnupg are signed with this key:
- "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"
+ 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/ .
- My usual key is now:
- "pub 1024D/621CC013 1998-07-07 Werner Koch <werner.koch@guug.de>"
- "Key fingerprint = ECAF 7590 EB34 43B5 C7CF 3ACB 6C7E E1B8 621C C013"
+You should get the latest versions of course, the GnuPG configure
+script complains if a version is not sufficient.
- You may add it to your GNUPG pubring and use it in the future to
- verify new releases. Because you verified this README file and
- _checked_that_it_is_really_my PGP2 key 0C9857A5, you can be sure
- that the above fingerprints are correct.
+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).
- 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".
- This mailing is closed (only subscribers can post) to avoid spam.
+As with all packages, you just have to do
- See the file COPYING for copyright and warranty information.
+ ./configure
+ make
+ make install
- 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).
+(Before doing install you might need to become root.)
- GNUPG is in almost all aspects compatible with other OpenPGP
- implementations.
+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.
- The default algorithms are now DSA and ELGamal. ELGamal for signing
- is still available, but due to the larger size of such signatures it
- is depreciated (Please note that the GNUPG implementation of ElGamal
- signatures is *not* insecure). Symmetric algorithms are: Blowfish
- and CAST5, Digest algorithms are MD5, RIPEMD160, SHA1 and TIGER/192.
+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.
+A texinfo manual named `gnupg.info' will get installed. Some commands
+and options given below. See also the section `SMARTCARD INTRO'.
- Installation
- ------------
+COMMANDS
+========
- See the file INSTALL. Here is a quick summary:
+gpgsm:
+------
- 1) "./configure"
+--learn-card
- 2) "make"
+ Read information about the private keys from the smartcard and
+ import the certificates from there.
- 3) "make install"
+--export
- 4) You end up with a binary "gpg" in /usr/local/bin
+ 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.
- 5) Optional, but suggested: install the program "gpg" as suid root.
+gpg2:
+-----
+--card-status
- Key Generation
- --------------
+ Show information pertaining smartcards implementing the OpenPGP
+ application.
- gpg --gen-key
+--change-pin
- 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.
+ 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.
- If you decided to create a DSA key, you should add an ElGamal
- for encryption:
+OPTIONS
+=======
- gpg --add-key user_id_of_your_key
+gpgsm:
+------
- and follow the displayed instructions (select "ElGamal using v4 packets").
+--include-certs <n>
+ 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>
- You can sign a key with this command:
+ Chnage the deault name of the policy file
- gpg --sign-key Donald
+--enable-policy-checks
+--disable-policy-checks
- This let you sign the key of "Donald" with your default userid.
+ By default policy checks are enabled. These options may be used to
+ change it.
- gpg --sign-key -u Karl -u Joe Donald
+--enable-crl-checks
+--disable-crl-checks
- 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.
+ 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.
- 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.
+--agent-program <path_to_agent_program>
+ 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>
+ 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.
+--no-secmem-warning
- Sign
- ----
+ Don't print the warning "no secure memory"
- gpg -s file
+--armor
- This creates a file file.gpg which is compressed and has a signature
- attached.
+ Create PEM ecoded output. Default is binary output.
- gpg -sa file
+--base64
- Same as above, but file.gpg is ascii armored.
+ Create Base-64 encoded output; i.e. PEM without the header lines.
- gpg -s -o out file
+--assume-armor
- Creates a signature of file, but writes the output to the file "out".
+ Assume the input data is PEM encoded. Default is to autodetect the
+ encoding but this is may fail.
- If you use the option "--rfc1991", gnupg tries to me more compatible
- to RFC1991 (pgp 2.x).
+--assume-base64
+ Assume the input data is plain base-64 encoded.
- Encrypt
- -------
+--assume-binary
- gpg -e -r heine file
+ Assume the input data is binary encoded.
- This encrypts files with the public key of "heine" and writes it
- to "file.gpg"
+--server
- echo "hallo" | gpg -ea -r heine | mail heine
+ 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.
- Ditto, but encrypts "hallo\n" and mails it as ascii armored message.
+--local-user <user_id>
+ Set the user to be used for signing. The default is the first
+ secret key found in the database.
- Sign and Encrypt
- ----------------
+--with-key-data
- gpg -se -r heine file
+ 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.
- 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
+gpg-agent:
+---------
- Ditto, but sign the file with the user id "Suttner"
+--pinentry-program <path_to_pinentry_program>
+ Specify the PINentry program. The default value is
+ "<prefix>/bin/pinentry" so you most likely want to specify it.
- Keyring Management
- ------------------
- To export your complete keyring(s) do this:
+--no-grab
- gpg --export
+ 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.
- To export only some user ids do this:
+
+scdaemon:
+--------
- gpg --export userids
+--ctapi-driver <libraryname>
- Use "-a" or "--armor" to create ASCII armored output.
+ 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).
- Importing keys is done with the option, you guessed it, "--import":
+--reader-port <portname>
- gpg --import [filenames]
+ 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).
- New keys are appended to the default keyring and already existing
- keys are merged. Keys without a self-signature are ignored.
+--disable-ccid
+ 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.
- 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):
+FILES
+=====
- "234567C4"
- "0F34E556E"
- "01347A56A"
- "0xAB123456
+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:
- * By a complete keyid:
+gpgsm.conf
- "234AABBCC34567C4"
- "0F323456784E56EAB"
- "01AB3FED1347A5612"
- "0x234AABBCC34567C4"
+ 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.
- * By a fingerprint:
+gpg-agent.conf
+
+ Options for gpg-agent
- "1234343434343434C434343434343434"
- "123434343434343C3434343434343734349A3434"
- "0E12343434343434343434EAB3484343434343434"
+scdaemon.conf
- The first one is MD5 the others are ripemd160 or sha1.
+ Options for scdaemon.
- * By an exact string (not yet implemented):
+dirmngr.conf
- "=Heinrich Heine <heinrichh@uni-duesseldorf.de>"
+ Options for the DirMngr which is not part of this package and
+ the option file wilol most likely be moved to /etc
- * By an email address:
+gpg.conf
+
+ Options for gpg. Note that old versions of gpg use the
+ filename `options' instead of `gpg.conf'.
- "<heinrichh@uni-duesseldorf.de>"
+gpg.conf-1.9.x
- This can be used by a keyserver instead of a substring to
- find this key faster.
+ Options for gpg; tried before gpg.conf
- * By the Local ID (from the trustdb):
- "#34"
+policies.txt
- 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)
+ 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
+ ++++++++++
- * Or by the usual substring:
+trustlist.txt
- "Heine"
- "*Heine"
+ 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.
- The '*' indicates substring search explicitly.
+random_seed
+ Used internally for keeping the state of the RNG over
+ invocations.
+pubring.kbx
+ The database file with the certificates.
- 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.
+pubring.gpg
- Batch mode also causes GNUPG to terminate as soon as a BAD signature is
- detected.
+ The database file with the OpenPGP public keys. This will
+ eventually be merged with pubring.kbx
+secring.gpg
- 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 OpenPGP secret keys. This will be
+ removed when gpg is changed to make use of the gpg-agent.
- Esoteric commands
- -----------------
+private-keys-v1.d/
- gpg --list-packets datafile
+ 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.
- 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 --list-trustdb
+SOURCE FILES
+============
- List the contents of the trustdb in a human readable format
+Here is a list of directories with source files:
- gpgm --list-trustdb <usernames>
+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 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 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.
+HOW TO SPECIFY A USER ID
+========================
- gpgm --print-mds filenames
+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:
- List all available message digest values for the fiven filenames
+ * By keyID.
- For more options/commands see the file g10/OPTIONS, or use "gpg --help"
+ 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.
+ 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.
- 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.
+ Examples:
- 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
+ 234567C4
+ 0F34E556E
+ 01347A56A
+ 0xAB123456
+ 234AABBCC34567C4
+ 0F323456784E56EAB
+ 01AB3FED1347A5612
+ 0x234AABBCC34567C4
+
+ * By fingerprint
+
+ 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:
+
+ 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]
- Other Notes
- -----------
- This is work in progress, so you may find duplicated code fragments,
- ugly data structures, weird usage of filenames and other things.
- 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@gnu.org> or better
- post them to the mailing list <g10@net.lut.ac.uk> (this is a closed list,
- please subscribe before posting).
projects / gnupg.git / blobdiff