Introduction

This is an enhanced, HTML version of the standard "man page" which is distributed with the Gnu Privacy Guard (GnuPG) and which appears in HTML form on the official GnuPG web site. The commands and options for GnuPG have been grouped into sections to let users see related commands and options together. In addition, a page of examples of key commands and options has been added to allow users to see these important commands and options in use. The examples use the "Nullify" build of GnuPG 1.0.7. 

This document is not intended as replacement for the "official" GnuPG documentation found on the GnuPG Documentation page. You should consult that documentation for "official" information on GnuPG command usage. Moreover, if you're new to GnuPG, you would be highly advised to read the excellent GNU Privacy Handbook, which can be downloaded in HTML form or PDF form. See the Links section on this page for links to still more information and documentation on GnuPG.

What follows is a discussion of several important aspects of using GnuPG and understanding the examples of GnuPG usage that are presented.

Options vs. Commands

GPG (gpg.exe) is the main program for the GnuPG system. GPG uses two types of switches: options and commands. Options always precede commands. You can use multiple options in conjunction with one another. Most commands, however, cannot be combined with other commands, though there are exceptions.

Here is typical use of GPG which employs multiple options and commands:

This combination of options and commands will encrypt the file my-file.txt using the public key of recipient Bob, sign the file my-file.txt with the user's default signing key, and produce an ASCII Armored output file (my-file.asc). 

Some options and commands have "short" versions. Short versions of commands and options take a single " - " instead of the standard " -- " that "long" options and commands do. For example, we could have performed the same operation with the following:

Not all options and commands have "short versions," though.

Please remember that option parsing stops as soon as a non option is encountered, you can explicitly stop option parsing by using the special option "--". 

File Types (.asc, .gpg, et al)

GnuPG uses two main file types:

ASCII Armored files (.ASC): These are simple text files with the extension .ASC that can be opened up in any text editor. ASCII Armor is a special text format that GPG (and PGP) use to convert binary data into ASCII text. ASCII Armored data is especially suitable for use in email messages.

Binary files (.GPG): By default most GPG operations produce binary files with the extension .GPG. The contents of binary .GPG files are designed to be used directly by GPG (or PGP) and are not suitable for use in email messages. 

For many GPG commands, you can produce .GPG or .ASC files, though most commands will produce .GPG files by default unless you use the --armor option.

Specifying User IDs & Key IDs

Many commands require you to specify a User ID or Key ID. For example, when encrypting a file to someone's public key, you can specify a User ID or Key ID with the --recipient option. If you have multiple secret keys, you can use the --local-user option to designate which key you want to use to sign. There are several different ways to specify User IDs or Key IDs.

• Use the email address specified in the key's User ID
   
  gpg --recipient bobbone@cowtownu.edu --encrypt my-file.txt
  gpg --local-user bobbone@cowtownu.edu --sign my-file.txt
   
  This is an effective way to designate keys, unless you have multiple keys from the same person, each using the same email address in its User ID.
   
• Use the name specified in the key's User ID
   
  gpg --recipient Bob --encrypt my-file.txt
  gpg --local-user Bob --sign my-file.txt
   
  If there are multiple "Bobs" on your keyring, you very likely won't be using the particular "Bob" you had in mind.
   
• Use the key's Key ID
   
  gpg --recipient 49B58839 --encrypt my-file.txt
  gpg --local-user 49B58839 --sign my-file.txt
   
  The is a relatively precise way to specify keys. In the examples above we've used the "short version" of the Key ID. There is the remote chance that several keys will have the same "short" Key ID. The "long" Key ID decreases the risk of a collision, but can be more unwieldy to use.

See the section titled How to Specify a User ID for more detailed suggestions on specifying keys.

Conventions for GnuPG Examples

Several different font styles and effects are used in the Examples section:

gpg --encrypt my-file.txt

Enter passphrase:

trust:  -/f

My_31337_Passphrase

The examples use the "Nullify" build of GnuPG 1.0.7, which is a Win32 build. So far as I known, most of the examples presented should be identical to earlier versions of GnuPG and versions of GnuPG available on other platforms.

Other Useful Documentation

GnuPG users may also wish to consult these other helpful documents regarding GnuPG:  
 

The Examples page uses the "Nullify" build of GnuPG 1.0.7 (though the man pages have been updated to incorporate changes through 1.1.91). GPG 1.0.7 "Nullify" includes these modules and patches:

Note that IDEA is patented in many countries, including the U.S., and may be used for non-commercial purposes. For commercial uses you'll need to buy a license from MediaCrypt. You can get instructions for using the IDEA module and download various versions of the IDEA module for GnuPG HERE.

TIGER and SHA-2 are not supported by most versions of PGP. See Disastry's GPG page for more details.

The command reference pages are current through GnuPG 1.1.91 (Aug 5 '02). 

The command reference pages and the Examples page will be updated in the near future to reflect the latest version of the Gnu Privacy Guard: GnuPG 1.4.0 (Dec 16 '04).

GnuPG Releases

Official Releases

The Examples page uses the "Nullify" build of GnuPG 1.0.7. GnuPG 1.0.7 was an "official" release of GnuPG. The latest official release is GnuPG 1.4.2 (Jul 26 '05).

GnuPG 1.4.2 can be downloaded from:

• http://www.gnupg.org/download/
• ftp://ftp.gnupg.org/GnuPG/

"Official" Windows binaries of GnuPG 1.4.0 can be found here:

• http://www.gnupg.org/download/
• ftp://ftp.gnupg.org/GnuPG/binary/

"Nullify" Win32 builds of GnuPG 1.2.3 (the latest available "Nullify" version) can be obtained from:

• http://www.nullify.org/

Please note that GnuPG 1.2.1 and earlier have a "key validity bug," which you can read about HERE. This bug is fixed in GnuPG 1.2.2.

Note also that the "official" Windows binary for GnuPG 1.2.0 (Sep 20 '02) contains a bug that prevents proper importing of revocation certificates.

GnuPG 1.0.7, another previous "official" GnuPG release (Apr 29 '02), can be downloaded from:

• ftp://ftp.gnupg.org/GnuPG/

There is no "official" Win32 build of GnuPG 1.0.7, only the "Nullify" build that used to be available from Nullify.org.

Development Releases

The command reference pages are current through GnuPG 1.1.91 (Aug 5 '02). The command pages also reflect additions and changes in GnuPG 1.1.90 (Jul 1 '02). Both GnuPG 1.1.91 and GnuPG 1.1.90 are development releases and are not intended for production use. 

Further development release have appeared since then. All of these development releases can be downloaded from:

• ftp://ftp.gnupg.org/GnuPG/alpha/gnupg/
  or ftp://ftp.gnupg.org/gcrypt/alpha/gnupg/

Windows binaries of some of these development builds can be found here:

• ftp://ftp.gnupg.org/GnuPG/alpha/binary/
  or ftp://ftp.gnupg.org/gcrypt/alpha/binary/

There is a "Nullify" Win32 build of GnuPG 1.2.2 RC1 currently available.

ElGamal Signing Keys Compromised

On Nov. 27, 2003, Werner Koch announced the discovery of a severe flaw in ElGamal signing keys generated by GnuPG. Note that this flaw does not affect standard ElGamal encrypting keys that are generated in tandem with DSA signing keys. You can read the text of Werner Koch's announcement HERE. And a patch for GnuPG 1.2.3 can be found HERE.

Credits & Acknowledgements

This set of web pages is, at its heart, an enhanced version of the GnuPG "man page" which is distributed in text form with GnuPG and in HTML form on the "official" GnuPG Documentation page here:

GPG "man" page

While the entries for the GPG commands and options themselves have essentially been reproduced from the "man page" "as-is," those entries have been grouped into separate sections and pages by the author of this set of web pages. Moreover, hyperlinks have been added throughout all the pages. Also, a page of GPG command and option usage examples has been added. Finally, an index page (this page) has been included.

GNU Free Documentation Licence

This set of web pages, collectively titled "GnuPG Command Reference (by Eric L. Howes)," is distributed under the "GNU Free Documentation License." For the purposes of this license, this set of web pages (also referred to as "the document") shall consist of the following:

No other web pages or files on this web site (http://www.spywarewarrior.com/uiuc/) are covered by this license unless specifically noted on those pages or in those files. You can read the full text of the "GNU Free Documentation License" here:

"GNU Free Documentation Licence"

Copyright (c) 2002 Eric L. Howes. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being "GnuPG Command Reference (Index)," and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License."