GnuPG - Command Reference
(by Eric L. Howes)

Main Index
   
On this page...
   
  Introduction
  Options vs. Commands
  File Types (.asc, .gpg, et al)
  Specifying User IDs & Key IDs
  Conventions for GnuPG Examples
  Other Useful Documentation
  "Nullify" Build of GPG 1.0.7
  GnuPG Releases
  Credits & Acknowledgements
  GNU Free Documentation Licence
   
Message Operations
   
Commands
   
Encryption / Decryption
Signing / Verifying
   
Options
   
General
Comments & Versions
Special
   
Key Management
   
Commands
   
Key Generation
Export & Importing Keys
Listing Keys
Editing Keys
Signing Keys
Removing/Revoking Keys
Keyservers
Trust Management
   
Options
   
General
Keys & Keyrings
Algorithms / Hashes
Compatibility
Key Signatures / Certification
Keyservers
Trust Management
Notation Policy URLs
Photo IDs
   
Advanced / Gen / Misc
   
Commands
   
Advanced
General
   
Options
   
Advanced
General Operations
Program / Environment Settings
Misc
Agent
   
Notes
   
How to Specify a User ID
Return Value
Examples
Environment
Files
Warnings
Bugs
   
  Other
   
  Installing the IDEA Module in GnuPG
   
Examples
   
Encryption/Decryption
Signing/Verifying
Combining Commands
Key Management
   
Links
   
GnuPG Info
   
GnuPG Docs page:
   
  GnuPG FAQ
  GnuPG Man Page
  GnuPG Mini Howto (English)
  GNU Privacy Handbook (html)
  GNU Privacy Handbook (pdf)
  Replacing PGP 2.x with GPG (html)
  Replacing PGP 2.x with GPG (pdf)
   
GnuPG Mailing List:
   
  Archives
 
Other GnuPG pages:
   
  Building GnuPG for Win32 using MinGW
  enCrypted Mail Transport
  Getting Started with GPG
  GPG-PGP Basics
  Installation of GPG - The Fast Way
  Installing & Using GnuPG On 
     a Windows 9x/NT System
 
  An Introduction to GnuPG (Part 1) 
  An Introduction to GnuPG (Part 2) 
  Moving from PGP to GnuPG
  A Practical Guide to GPG
  Using GnuPG
  Using GnuPG
  Using Multiple Subkeys in GPG
   
 Steve Butler:
  Implementation Guide
  Installation & Setup Guide
  Personal & Corporate Email Encryption
  Usage Guide
   
Crypto Info
 
  Counterpane
  Peter Gutman - Security & Encryption Links 
  The PGP Attack FAQ
  PGP vs. X.509 Certificates
  Practical Attacks on PGP
  Ron Rivest - Cryptography 
     & Security Links
  RSA Labs Cryptography FAQ
  Sam Simpson's PGP DH 
     vs. RSA FAQ
  sci.crypt Cryptography FAQ 
  The Security & Encryption FAQ
  SSH - Cryptography A-Z
  S/MIME & PGP Products
     Interoperability
  Tom McCune's PGP Questions
     & Answers
  The Web of Trust of PGP
  Why Should I Sign My Own
     Public Key?
   
   
Document History
   
2005
   
Jul 30 Updated the info on front page again to reflect latest GPG versions & information.
   
2004
   
Dec 17 Updated the info on front page again to reflect latest GPG versions & information.
   
Jan 1 Updated the info on front page again to reflect latest GPG versions & information.
   
2003
   
Nov 27 Added notice about flaw in ElGamal signing keys.
   
Oct 19 Updated the info on front page again to reflect latest GPG versions & information.
   
Sep 18 Updated the info on front page again to reflect latest GPG versions & information.
   
Aug 28 Updated the info on front page again to reflect latest GPG versions & information.
   
May 19 Updated the info on front page again to reflect latest GPG versions & information.
   
May 6 Updated the info on front page again to reflect latest GPG versions & information.
   
May 3 Updated the info on front page again to reflect latest GPG versions.
   
Apr 16 Updated the info on front page again to reflect latest GPG versions.
   
2002
   
Oct 26 Updated the info on front page again to reflect latest GPG versions.
   
Oct 8 Updated the info on front page to reflect latest GPG versions.
   
Aug 10 Minor tweaks to the commands pages.
   
Aug 7 Updated commands to reflect changes through GPG 1.1.91. 
   
Aug 6 Reformatted pages & updated commands to GPG 1.1.90. Merged "Advanced" and "General/Misc" commands into one page.
   
May 26 More updates to the examples page, but no major new additions.
   
May 24 Still more additions, incl. a note on Migrating Keys from PGP.
   
May 23 Several important additions, incl. example section notes on signature verifications, "encrypt-to-self," and exporting secret keys.
   
May 21 Added info about patches and modules used by "Nullify" build of GPG 1.0.7 
   
May 20 Several updates, incl. A Note on Subkeys, and an ex. of Setting Preferences, among others. 
   
May 19 1st release of this document.
   

   
   

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
Indicates text typed or entered by the user.
   
Enter passphrase:
Indicates output from GPG.
   
trust:  -/f
Indicates output from GPG that is 
mentioned or noted in the text.
   
My_31337_Passphrase
Indicates text typed by the user but not 
"echoed" or displayed by GPG.

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:  
 

GnuPG Documentation RFCs

"Nullify" Build of GPG 1.0.7

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:

"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:

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:

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:

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:

Page Title Page File
   
GnuPG Command Reference (Index) gpg-com-0.htm
GnuPG Commands - Message Operations gpg-com-1.htm
GnuPG Commands - Key Management gpg-com-2.htm
GnuPG Commands - Advanced/General/Misc gpg-com-3.htm
GnuPG Commands - Examples gpg-com-4.htm
GnuPG Commands  (Redirect) gpg-com-5.htm
"GNU Free Documentation Licence" gpg-com-lic.htm

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."

 

Home [frames]        Home [no frames]

2000-2004 Eric L. Howes (eburger68@myrealbox.com)