GnuPG - Advanced / General / Misc

Table of Contents
General Operations
Program / Environment Settings
How to Specify a User ID
Return Value
Return to Index
GPG is the main program for the GnuPG system.
This man page only lists the commands and options available. For more verbose documentation get the GNU Privacy Handbook (GPH) or one of the other documents at .
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 "--".


GPG recognizes these commands:  


  List only the sequence of packets. This is mainly useful for debugging.  
  Store only (make a simple RFC1991 packet).  
  --print-md algo files
--print-mds files
  Print message digest of algorithm ALGO for all given files or stdin. With the second form (or a deprecated "*" as algo) digests for all available algorithms are printed.  
  --gen-random 0|1|2 count        
  Emit COUNT random bytes of the given quality level. If count is not given or zero, an endless sequence of random bytes will be emitted. PLEASE, don't use this command unless you know what you are doing; it may remove precious entropy from the system!  
  --gen-prime mode bits qbits        
  Use the source, Luke :-). The output format is still subject to change.   
  Print version information along with a list of supported algorithms.  
  Print warranty information.  
  -h, --help        
  Print usage information. This is a really long list even though it doesn't list all options.   


Starting with GnuPG 1.1.92 (incl. GnuPG 1.2.1, 1.2.0 and 1.1.92), long options can be put in an options file (default "~/.gnupg/gpg.conf"). In GnuPG versions up through GnuPG 1.1.91 (incl. 1.0.6, 1.0.7, and 1.1.91), long options can be put in an "old style" configuration file (default "~/.gnupg/options"). 

Short option names will not work -- for example, armor is a valid option for the options file, while a is not. Do not write the 2 dashes, but simply the name of the option and any required arguments. Lines with a hash as the first non-white-space character are ignored. Commands may be put in this file too, but that does not make sense.

GPG recognizes these options: 



  --debug flags        
  Set debugging flags. All flags are or-ed and flags may be given in C syntax (e.g. 0x0042).  
  Set all useful debugging flags.  
  --status-fd n        
  Write special status strings to the file descriptor n. See the file DETAILS in the documentation for a listing of them.  
  --attribute-fd n        
  Write attribute subpackets to the file descriptor n. This is most useful for use with --status-fd, since the status messages are needed to separate out the various subpackets from the stream delivered to the file descriptor.  
  --logger-fd n        
  Write log output to file descriptor n and not to stderr.   
  --passphrase-fd n        
  Read the passphrase from file descriptor n. If you use 0 for n, the passphrase will be read from stdin. This can only be used if only one passphrase is supplied. Don't use this option if you can avoid it.  
  --command-fd n        
  This is a replacement for the deprecated shared-memory IPC mode. If this option is enabled, user input on questions is not expected from the TTY but from the given file descriptor. It should be used together with --status-fd. See the file doc/DETAILS in the source distribution for details on how to use it.   
  GnuPG versions prior to 1.0.2 had a bug in the way a signature was encoded. This options enables a workaround by checking faulty signatures again with the encoding used in old versions. This may only happen for ElGamal signatures which are not widely used.  
  Display the session key used for one message. See --override-session-key for the counterpart of this option.

We think that Key-Escrow is a Bad Thing; however the user should have the freedom to decide whether to go to prison or to reveal the content of one specific message without compromising all messages ever encrypted for one secret key. DON'T USE IT UNLESS YOU ARE REALLY FORCED TO DO SO.
  --override-session-key string        
  Don't use the public key but the session key string. The format of this string is the same as the one printed by --show-session-key. This option is normally not used but comes handy in case someone forces you to reveal the content of an encrypted message; using this option you can do this without handing out the secret key.   

General Operations

  -v, --verbose        
  Give more information during processing. If used twice, the input data is listed in detail.  
  -q, --quiet        
  Try to be as quiet as possible.  
  -n, --dry-run        
  Don't make any changes (this is not completely implemented).  
  -i, --interactive        
  Prompt before overwriting any files.  
  Make sure that the TTY (terminal) is never used for any output. This option is needed in some cases because GnuPG sometimes prints warnings to the TTY if --batch is used.  
  Use batch mode. Never ask, do not allow interactive commands.  
  Disable batch mode. This may be of use if --batch is enabled from an options file.  
  Suppress the initial copyright message but do not enter batch mode.  
  Assume "yes" on most questions.  
  Assume "no" on most questions.   

Program\Environment Settings

  --homedir directory        
  Set the name of the home directory to "directory" If this option is not used it defaults to "~/.gnupg". It does not make sense to use this in a options file. This also overrides the environment variable GNUPGHOME.  
  --charset name        
  Set the name of the native character set. This is used to convert some strings to proper UTF-8 encoding. Valid values for name are:  
iso-8859-1 This is the default Latin 1 set.
iso-8859-2 The Latin 2 set.
koi8-r The usual Russian set (rfc1489).
utf-8 Bypass all translations and assume that the OS uses native UTF-8 encoding.
  Assume that the arguments are already given as UTF8 strings. The default (--no-utf8-strings) is to assume that arguments are encoded in the character set as specified by --charset. These options affect all following arguments. Both options may be used multiple times.  
  --options file        
  Read options from file and do not try to read them from the default options file in the homedir (see --homedir). This option is ignored if used in an options file.  
  Shortcut for "--options /dev/null". This option is detected before an attempt to open an option file. Using this option will also prevent the creation of a "~./gnupg" homedir.  
  --load-extension name        
  Load an extension module. If name does not contain a slash it is searched in "/usr/local/lib/gnupg" Extension are in general not useful anymore; the use of this option is deprecated.  
  --exec-path string        
  Sets a list of directories to search for photo viewers and keyserver helpers. If not provided, keyserver helpers use the compiled-in default directory, and photo viewers use the $PATH envi­ ronment variable.  


  Lock the databases the first time a lock is requested and do not release the lock until the process terminates.  
  Release the locks every time a lock is no longer needed. Use this to override a previous --lock-once from a config file.  
  Disable locking entirely. This option should be used only in very special environments, where it can be assured that only one process is accessing those files. A bootable floppy with a stand-alone encryption system will probably use this. Improper usage of this option may lead to data and key corruption.  
  GnuPG uses a file to store its internal random pool over invocations. This makes random generation faster; however sometimes write operations are not desired. This option can be used to achieve that with the cost of slower random generation.  
  Suppress the warning about "using insecure memory."  
  Suppress the warning about unsafe file permissions.  
  This is not for normal use. Use the source to see for what it might be useful.  
  This is not for normal use. Use the source to see for what it might be useful.   


  Try to use the GnuPG-Agent. Please note that this agent is still under development. With this option, GnuPG first tries to connect to the agent before it asks for a passphrase.  
  Override the value of the environment variable `GPG_AGENT_INFO'. This is only used when --use-agent has been given.  



How to Specify a User ID

  There are different ways on how to specify a user ID to GnuPG; here are some examples:  
  Here the key ID is given in the usual short form.  
  Here the key ID is given in the long form as used by OpenPGP (you can get the long key ID using the option --with-colons).  
  The best way to specify a key ID is by using the fingerprint of the key. This avoids any ambiguities in case that there are duplicated key IDs (which are really rare for the long key IDs).  
=Heinrich Heine <>
  Using an exact to match string. The equal sign indicates this.  
  Using the email address part which must match exactly. The left angle bracket indicates this email address mode.  
+Heinrich Heine duesseldorf
  All words must match exactly (not case sensitive) but can appear in any order in the user ID. Words are any sequences of letters, digits, the underscore and all characters with bit 7 set.  
  By case insensitive substring matching. This is the default mode but applications may want to explicitly indicate this by putting the asterisk in front.

Note that you can append an exclamation mark to key IDs or fingerprints. This flag tells GnuPG to use exactly the given primary or secondary key and not to try to figure out which secondary or primary key to use.
Return Value  
  The program returns 0 if everything was fine, 1 if at least a signature was bad, and other error codes for fatal errors.  


  gpg -se -r `Bob' file        
  sign and encrypt for user Bob  
  gpg --clearsign file        
  make a clear text signature  
  gpg -sb file        
  make a detached signature  
  gpg --list-keys user_ID        
  show keys  
  gpg --fingerprint user_ID        
  show fingerprint  
  gpg --verify pgpfile
gpg --verify sigfile files
  Verify the signature of the file but do not output the data. The second form is used for detached signatures, where `sigfile' is the detached signature (either ASCII armored of binary) and files are the signed data; if this is not given the name of the file holding the signed data is constructed by cutting off the extension (".asc" or ".sig") of `sigfile' or by asking the user for the filename.   


  Used to locate the default home directory.  
  If set directory used instead of "~/.gnupg".  
  Used to locate the gpg-agent; only honred when --use-agent is set. The value constist of 3 colon delimited fields: The first is the path to the Unix Domain Socket, the second the PID of the gpg-agent and the protocol version which should be set to 1. When starting the gpg-agent as described in its documentation, this variable is set to the correct value. The option --gpg-agent-info can be used to overide it.  
  Only honored when the option --honor-http-proxy is set.   


  The secret keyring  
  and the lock file  
  The public keyring  
  and the lock file  
  The trust database  
  and the lock file  
  used to preserve the internal random pool  
  Default configuration file (GnuPG 1.1.92 & later)  
  Old style configuration file; only used when gpg.conf is not found (GnuPG 1.1.91 and earlier)  
  Skeleton options file  
  Default location for extensions  


  Use a *good* password for your user account and a *good* passphrase to protect your secret key. This passphrase is the weakest part of the whole system. Programs to do dictionary attacks on your secret keyring are very easy to write and so you should protect your "~/.gnupg/" directory very well.

Keep in mind that, if this program is used over a network (telnet), it is *very* easy to spy out your passphrase!

If you are going to verify detached signatures, make sure that the program knows about it; either be giving both filenames on the commandline or using `-' to specify stdin.


  On many systems this program should be installed as setuid(root). This is necessary to lock memory pages. Locking memory pages prevents the operating system from writing memory pages to disk. If you get no warning message about insecure memory your operating system supports locking without being root. The program drops root privileges as soon as locked memory is allocated.   

Home [frames]        Home [no frames]

© 2000, 2001, 2002 Eric L. Howes (