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]