GnuPG - Advanced / General / Misc

Table of Contents
   
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
 
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 http://www.gnupg.org/documentation/ .
 
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 "--".
 
 

Commands

 
 
GPG recognizes these commands:  
   
 
 

Advanced

 
           
  --list-packets        
         
  List only the sequence of packets. This is mainly useful for debugging.  
           
  --store        
         
  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.   
           
 
 
General  
           
  --version        
         
  Print version information along with a list of supported algorithms.  
           
  --warranty        
         
  Print warranty information.  
           
  -h, --help        
         
  Print usage information. This is a really long list even though it doesn't list all options.   
           
 

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: 

 
   
 
 

Advanced

 
           
  --debug flags        
         
  Set debugging flags. All flags are or-ed and flags may be given in C syntax (e.g. 0x0042).  
           
  --debug-all        
         
  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.   
           
  --emulate-md-encode-bug        
         
  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.  
           
  --show-session-key        
         
  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.  
           
  --no-tty        
         
  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.  
           
  --batch        
         
  Use batch mode. Never ask, do not allow interactive commands.  
           
  --no-batch        
         
  Disable batch mode. This may be of use if --batch is enabled from an options file.  
           
  --no-greeting        
         
  Suppress the initial copyright message but do not enter batch mode.  
           
  --yes        
         
  Assume "yes" on most questions.  
           
  --no        
         
  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.
 
           
  --utf8-strings
--no-utf8-strings
       
         
  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.  
           
  --no-options        
         
  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.  
           
 
 

Misc

 
           
  --lock-once        
         
  Lock the databases the first time a lock is requested and do not release the lock until the process terminates.  
           
  --lock-multiple        
         
  Release the locks every time a lock is no longer needed. Use this to override a previous --lock-once from a config file.  
           
  --lock-never        
         
  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.  
           
  --no-random-seed-file        
         
  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.  
           
  --no-secmem-warning        
         
  Suppress the warning about "using insecure memory."  
           
  --no-permission-warning        
         
  Suppress the warning about unsafe file permissions.  
           
  --no-literal        
         
  This is not for normal use. Use the source to see for what it might be useful.  
           
  --set-filesize        
         
  This is not for normal use. Use the source to see for what it might be useful.   
           
 
 

Agent

 
           
  --use-agent        
         
  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.  
           
  --gpg-agent-info        
         
  Override the value of the environment variable `GPG_AGENT_INFO'. This is only used when --use-agent has been given.  
           
 

Notes

   
 

How to Specify a User ID

 
           
  There are different ways on how to specify a user ID to GnuPG; here are some examples:  
    
 
234567C4
0F34E556E
01347A56A
0xAB123456
 
  Here the key ID is given in the usual short form.  
   
 
234AABBCC34567C4
0F323456784E56EAB
01AB3FED1347A5612
0x234AABBCC34567C4
 
  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).  
   
 
1234343434343434C434343434343434
123434343434343C3434343434343734349A3434
0E12343434343434343434EAB3484343434343434
0xE12343434343434343434EAB3484343434343434
 
  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 <heinrichh@uni-duesseldorf.de>
 
  Using an exact to match string. The equal sign indicates this.  
 
 
<heinrichh@uni-duesseldorf.de>
 
  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.  
 
 
Heine
*Heine
 
  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.  
           
 
 

Examples

 
           
  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.   
           
 
 

Environment

 
           
  HOME        
         
  Used to locate the default home directory.  
           
  GNUPGHOME        
         
  If set directory used instead of "~/.gnupg".  
           
  GPG_AGENT_INFO        
         
  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.  
           
  http_proxy        
         
  Only honored when the option --honor-http-proxy is set.   
           
 
 

Files

 
           
  ~/.gnupg/secring.gpg        
         
  The secret keyring  
           
  ~/.gnupg/secring.gpg.lock        
         
  and the lock file  
           
  ~/.gnupg/pubring.gpg        
         
  The public keyring  
           
  ~/.gnupg/pubring.gpg.lock        
         
  and the lock file  
           
  ~/.gnupg/trustdb.gpg        
         
  The trust database  
           
  ~/.gnupg/trustdb.gpg.lock        
         
  and the lock file  
           
  ~/.gnupg/random_seed        
         
  used to preserve the internal random pool  
           
  ~/.gnupg/gpg.conf        
         
  Default configuration file (GnuPG 1.1.92 & later)  
           
  ~/.gnupg/options        
         
  Old style configuration file; only used when gpg.conf is not found (GnuPG 1.1.91 and earlier)  
           
  /usr[/local]/share/gnupg/options.skel    
         
  Skeleton options file  
           
  /usr[/local]/lib/gnupg/        
         
  Default location for extensions  
           
 
 

Warnings

 
           
  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.
 
           
 
 

Bugs

 
           
  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 (eburger68@myrealbox.com)