GnuPG - Command Reference
(by Eric L. Howes)
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.
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:
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
"Nullify" Build of GPG 1.0.7
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 1.4.2 can be downloaded from:
"Official" Windows binaries of GnuPG 1.4.0 can be found here:
"Nullify" Win32 builds of GnuPG 1.2.3 (the latest available "Nullify" version) can be obtained from:
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:
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:
Windows binaries of some of these development builds can be found here:
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:
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:
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."
Home [frames] Home [no frames]
© 2000-2004 Eric L. Howes (firstname.lastname@example.org)