info gnupg

File: gnupg.info, Node: GPG Esoteric Options, Next: Deprecated Options, Prev: Compliance Options, Up: GPG Options

4.2.6 Doing things one usually doesn't want to do
-------------------------------------------------

'-n'
'--dry-run'
Don't make any changes (this is not completely implemented).

'--list-only'
Changes the behaviour of some commands. This is like '--dry-run'
but different in some cases. The semantic of this option may be
extended in the future. Currently it only skips the actual
decryption pass and therefore enables a fast listing of the
encryption keys.

'-i'
'--interactive'
Prompt before overwriting any files.

'--compatibility-flags FLAGS'
Set compatibility flags to work around problems due to
non-compliant keys or data. The FLAGS are given as a comma
separated list of flag names and are OR-ed together. The special
flag "none" clears the list and allows one to start over with an
empty list. To get a list of available flags the sole word "help"
can be used.

'--debug-level LEVEL'
Select the debug level for investigating problems. LEVEL may be a
numeric value or by a keyword:

'none'
No debugging at all. A value of less than 1 may be used
instead of the keyword.
'basic'
Some basic debug messages. A value between 1 and 2 may be
used instead of the keyword.
'advanced'
More verbose debug messages. A value between 3 and 5 may be
used instead of the keyword.
'expert'
Even more detailed messages. A value between 6 and 8 may be
used instead of the keyword.
'guru'
All of the debug messages you can get. A value greater than 8
may be used instead of the keyword. The creation of hash
tracing files is only enabled if the keyword is used.

How these messages are mapped to the actual debugging flags is not
specified and may change with newer releases of this program. They
are however carefully selected to best aid in debugging.

'--debug FLAGS'
Set debug flags. All flags are or-ed and FLAGS may be given in C
syntax (e.g. 0x0042) or as a comma separated list of flag names.
To get a list of all supported flags the single word "help" can be
used. This option is only useful for debugging and the behavior
may change at any time without notice.

'--debug-all'
Set all useful debugging flags.

'--debug-iolbf'
Set stdout into line buffered mode. This option is only honored
when given on the command line.

'--debug-set-iobuf-size N'
Change the buffer size of the IOBUFs to N kilobyte. Using 0 prints
the current size. Note well: This is a maintainer only option and
may thus be changed or removed at any time without notice.

'--debug-allow-large-chunks'
To facilitate software tests and experiments this option allows one
to specify a limit of up to 4 EiB ('--chunk-size 62').

'--debug-ignore-expiration'
This option tries to override certain key expiration dates. It is
only useful for certain regression tests.

'--faked-system-time EPOCH'
This option is only useful for testing; it sets the system time
back or forth to EPOCH which is the number of seconds elapsed since
the year 1970. Alternatively EPOCH may be given as a full ISO time
string (e.g. "20070924T154812").

If you suffix EPOCH with an exclamation mark (!), the system time
will appear to be frozen at the specified time.

'--full-timestrings'
Change the format of printed creation and expiration times from
just the date to the date and time. This is in general not useful
and the same information is anyway available in '--with-colons'
mode. These longer strings are also not well aligned with other
printed data.

'--enable-progress-filter'
Enable certain PROGRESS status outputs. This option allows
frontends to display a progress indicator while gpg is processing
larger files. There is a slight performance overhead using it.

'--status-fd N'
Write special status strings to the file descriptor N. See the
file DETAILS in the documentation for a listing of them.

'--status-file FILE'
Same as '--status-fd', except the status data is written to file
FILE.

'--logger-fd N'
Write log output to file descriptor N and not to STDERR.

'--log-file FILE'
'--logger-file FILE'
Same as '--logger-fd', except the logger data is written to file
FILE. Use 'socket://' to log to s socket.

'--log-time'
Prefix all log output with a timestamp even if no log file is used.

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

'--attribute-file FILE'
Same as '--attribute-fd', except the attribute data is written to
file FILE.

'--comment STRING'
'--no-comments'
Use STRING as a comment string in cleartext signatures and ASCII
armored messages or keys (see '--armor'). The default behavior is
not to use a comment string. '--comment' may be repeated multiple
times to get multiple comment strings. '--no-comments' removes all
comments. It is a good idea to keep the length of a single comment
below 60 characters to avoid problems with mail programs wrapping
such lines. Note that comment lines, like all other header lines,
are not protected by the signature.

'--emit-version'
'--no-emit-version'
Force inclusion of the version string in ASCII armored output. If
given once only the name of the program and the major number is
emitted, given twice the minor is also emitted, given thrice the
micro is added, and given four times an operating system
identification is also emitted. '--no-emit-version' (default)
disables the version line.

'--sig-notation {NAME=VALUE}'
'--cert-notation {NAME=VALUE}'
'-N, --set-notation {NAME=VALUE}'
Put the name value pair into the signature as notation data. NAME
must consist only of printable characters or spaces, and must
contain a '@' character in the form keyname@domain.example.com
(substituting the appropriate keyname and domain name, of course).
This is to help prevent pollution of the IETF reserved notation
namespace. The '--expert' flag overrides the '@' check. VALUE may
be any printable string; it will be encoded in UTF-8, so you should
check that your '--display-charset' is set correctly. If you
prefix NAME with an exclamation mark (!), the notation data will be
flagged as critical (rfc4880:5.2.3.16). '--sig-notation' sets a
notation for data signatures. '--cert-notation' sets a notation
for key signatures (certifications). '--set-notation' sets both.

There are special codes that may be used in notation names. "%k"
will be expanded into the key ID of the key being signed, "%K" into
the long key ID of the key being signed, "%f" into the fingerprint
of the key being signed, "%s" into the key ID of the key making the
signature, "%S" into the long key ID of the key making the
signature, "%g" into the fingerprint of the key making the
signature (which might be a subkey), "%p" into the fingerprint of
the primary key of the key making the signature, "%c" into the
signature count from the OpenPGP smartcard, and "%%" results in a
single "%". %k, %K, and %f are only meaningful when making a key
signature (certification), and %c is only meaningful when using the
OpenPGP smartcard.

'--known-notation NAME'
Adds NAME to a list of known critical signature notations. The
effect of this is that gpg will not mark a signature with a
critical signature notation of that name as bad. Note that gpg
already knows by default about a few critical signatures notation
names.

'--sig-policy-url STRING'
'--cert-policy-url STRING'
'--set-policy-url STRING'
Use STRING as a Policy URL for signatures (rfc4880:5.2.3.20). If
you prefix it with an exclamation mark (!), the policy URL packet
will be flagged as critical. '--sig-policy-url' sets a policy url
for data signatures. '--cert-policy-url' sets a policy url for key
signatures (certifications). '--set-policy-url' sets both.

The same %-expandos used for notation data are available here as
well.

'--sig-keyserver-url STRING'
Use STRING as a preferred keyserver URL for data signatures. If
you prefix it with an exclamation mark (!), the keyserver URL
packet will be flagged as critical.

The same %-expandos used for notation data are available here as
well.

'--set-filename STRING'
Use STRING as the filename which is stored inside messages. This
overrides the default, which is to use the actual filename of the
file being encrypted. Using the empty string for STRING
effectively removes the filename from the output.

'--for-your-eyes-only'
'--no-for-your-eyes-only'
Set the 'for your eyes only' flag in the message. This causes
GnuPG to refuse to save the file unless the '--output' option is
given, and PGP to use a "secure viewer" with a claimed
Tempest-resistant font to display the message. This option
overrides '--set-filename'. '--no-for-your-eyes-only' disables
this option.

'--use-embedded-filename'
'--no-use-embedded-filename'
Try to create a file with a name as embedded in the data. This can
be a dangerous option as it enables overwriting files by giving the
sender control on how to store files. Defaults to no. Note that
the option '--output' overrides this option.

A better approach than using this option is to decrypt to a
temporary filename and then rename that file to the embedded file
name after checking that the embedded filename is harmless. When
using the '--status-fd' option gpg tells the filename as part of
the PLAINTEXT status message. If the filename is important, the
use of 'gpgtar' is another option because gpgtar will never
overwrite a file but decrypt the files to a new directory.

Note also that unless a modern version 5 signature is used the
embedded filename is not part of the signed data.

'--cipher-algo NAME'
Use NAME as cipher algorithm. Running the program with the command
'--version' yields a list of supported algorithms. If this is not
used the cipher algorithm is selected from the preferences stored
with the key. In general, you do not want to use this option as it
allows you to violate the OpenPGP standard. The option
'--personal-cipher-preferences' is the safe way to accomplish the
same thing.

'--digest-algo NAME'
Use NAME as the message digest algorithm. Running the program with
the command '--version' yields a list of supported algorithms. In
general, you do not want to use this option as it allows you to
violate the OpenPGP standard. The option
'--personal-digest-preferences' is the safe way to accomplish the
same thing.

'--compress-algo NAME'
Use compression algorithm NAME. "zlib" is RFC-1950 ZLIB
compression. "zip" is RFC-1951 ZIP compression which is used by
PGP. "bzip2" is a more modern compression scheme that can compress
some things better than zip or zlib, but at the cost of more memory
used during compression and decompression. "uncompressed" or
"none" disables compression. If this option is not used, the
default behavior is to examine the recipient key preferences to see
which algorithms the recipient supports. If all else fails, ZIP is
used for maximum compatibility.

ZLIB may give better compression results than ZIP, as the
compression window size is not limited to 8k. BZIP2 may give even
better compression results than that, but will use a significantly
larger amount of memory while compressing and decompressing. This
may be significant in low memory situations. Note, however, that
PGP (all versions) only supports ZIP compression. Using any
algorithm other than ZIP or "none" will make the message unreadable
with PGP. In general, you do not want to use this option as it
allows you to violate the OpenPGP standard. The option
'--personal-compress-preferences' is the safe way to accomplish the
same thing.

'--cert-digest-algo NAME'
Use NAME as the message digest algorithm used when signing a key.
Running the program with the command '--version' yields a list of
supported algorithms. Be aware that if you choose an algorithm
that GnuPG supports but other OpenPGP implementations do not, then
some users will not be able to use the key signatures you make, or
quite possibly your entire key. Note also that a public key
algorithm must be compatible with the specified digest algorithm;
thus selecting an arbitrary digest algorithm may result in error
messages from lower crypto layers or lead to security flaws.

'--disable-cipher-algo NAME'
Never allow the use of NAME as cipher algorithm. The given name
will not be checked so that a later loaded algorithm will still get
disabled.

'--disable-pubkey-algo NAME'
Never allow the use of NAME as public key algorithm. The given
name will not be checked so that a later loaded algorithm will
still get disabled.

'--throw-keyids'
'--no-throw-keyids'
Do not put the recipient key IDs into encrypted messages. This
helps to hide the receivers of the message and is a limited
countermeasure against traffic analysis.(1) On the receiving side,
it may slow down the decryption process because all available
secret keys must be tried. '--no-throw-keyids' disables this
option. This option is essentially the same as using
'--hidden-recipient' for all recipients.

'--not-dash-escaped'
This option changes the behavior of cleartext signatures so that
they can be used for patch files. You should not send such an
armored file via email because all spaces and line endings are
hashed too. You can not use this option for data which has 5
dashes at the beginning of a line, patch files don't have this. A
special armor header line tells GnuPG about this cleartext
signature option.

'--escape-from-lines'
'--no-escape-from-lines'
Because some mailers change lines starting with "From " to ">From "
it is good to handle such lines in a special way when creating
cleartext signatures to prevent the mail system from breaking the
signature. Note that all other PGP versions do it this way too.
Enabled by default. '--no-escape-from-lines' disables this option.

'--passphrase-repeat N'
Specify how many times 'gpg' will request a new passphrase be
repeated. This is useful for helping memorize a passphrase.
Defaults to 1 repetition; can be set to 0 to disable any passphrase
repetition. Note that a N greater than 1 will pop up the pinentry
window N+1 times even if a modern pinentry with two entry fields is
used.

'--passphrase-fd N'
Read the passphrase from file descriptor N. Only the first line
will be read 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.

Note that since Version 2.0 this passphrase is only used if the
option '--batch' has also been given. Since Version 2.1 the
'--pinentry-mode' also needs to be set to 'loopback'.

'--passphrase-file FILE'
Read the passphrase from file FILE. Only the first line will be
read from file FILE. This can only be used if only one passphrase
is supplied. Obviously, a passphrase stored in a file is of
questionable security if other users can read this file. Don't use
this option if you can avoid it.

Note that since Version 2.0 this passphrase is only used if the
option '--batch' has also been given. Since Version 2.1 the
'--pinentry-mode' also needs to be set to 'loopback'.

'--passphrase STRING'
Use STRING as the passphrase. This can only be used if only one
passphrase is supplied. Obviously, this is of very questionable
security on a multi-user system. Don't use this option if you can
avoid it.

Note that since Version 2.0 this passphrase is only used if the
option '--batch' has also been given. Since Version 2.1 the
'--pinentry-mode' also needs to be set to 'loopback'.

'--pinentry-mode MODE'
Set the pinentry mode to MODE. Allowed values for MODE are:
default
Use the default of the agent, which is 'ask'.
ask
Force the use of the Pinentry.
cancel
Emulate use of Pinentry's cancel button.
error
Return a Pinentry error ("No Pinentry").
loopback
Redirect Pinentry queries to the caller. Note that in
contrast to Pinentry the user is not prompted again if he
enters a bad password.

'--no-symkey-cache'
Disable the passphrase cache used for symmetrical en- and
decryption. This cache is based on the message specific salt value
(cf. '--s2k-mode').

'--request-origin ORIGIN'
Tell gpg to assume that the operation ultimately originated at
ORIGIN. Depending on the origin certain restrictions are applied
and the Pinentry may include an extra note on the origin.
Supported values for ORIGIN are: 'local' which is the default,
'remote' to indicate a remote origin or 'browser' for an operation
requested by a web browser.

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

'--command-file FILE'
Same as '--command-fd', except the commands are read out of file
FILE

'--allow-non-selfsigned-uid'
'--no-allow-non-selfsigned-uid'
Allow the import and use of keys with user IDs which are not
self-signed. This is not recommended, as a non self-signed user ID
is trivial to forge. '--no-allow-non-selfsigned-uid' disables.

'--allow-freeform-uid'
Disable all checks on the form of the user ID while generating a
new one. This option should only be used in very special
environments as it does not ensure the de-facto standard format of
user IDs.

'--ignore-time-conflict'
GnuPG normally checks that the timestamps associated with keys and
signatures have plausible values. However, sometimes a signature
seems to be older than the key due to clock problems. This option
makes these checks just a warning. See also '--ignore-valid-from'
for timestamp issues on subkeys.

'--ignore-valid-from'
GnuPG normally does not select and use subkeys created in the
future. This option allows the use of such keys and thus exhibits
the pre-1.0.7 behaviour. You should not use this option unless
there is some clock problem. See also '--ignore-time-conflict' for
timestamp issues with signatures.

'--ignore-crc-error'
The ASCII armor used by OpenPGP is protected by a CRC checksum
against transmission errors. Occasionally the CRC gets mangled
somewhere on the transmission channel but the actual content (which
is protected by the OpenPGP protocol anyway) is still okay. This
option allows GnuPG to ignore CRC errors.

'--ignore-mdc-error'
This option changes a MDC integrity protection failure into a
warning. It is required to decrypt old messages which did not use
an MDC. It may also be useful if a message is partially garbled,
but it is necessary to get as much data as possible out of that
garbled message. Be aware that a missing or failed MDC can be an
indication of an attack. Use with great caution; see also option
'--rfc2440'.

'--allow-old-cipher-algos'
Old cipher algorithms like 3DES, IDEA, or CAST5 encrypt data using
blocks of 64 bits; modern algorithms use blocks of 128 bit instead.
To avoid certain attack on these old algorithms it is suggested not
to encrypt more than 150 MiByte using the same key. For this
reason gpg does not allow the use of 64 bit block size algorithms
for encryption unless this option is specified.

'--allow-weak-digest-algos'
Signatures made with known-weak digest algorithms are normally
rejected with an "invalid digest algorithm" message. This option
allows the verification of signatures made with such weak
algorithms. MD5 is the only digest algorithm considered weak by
default. See also '--weak-digest' to reject other digest
algorithms.

'--weak-digest NAME'
Treat the specified digest algorithm as weak. Signatures made over
weak digests algorithms are normally rejected. This option can be
supplied multiple times if multiple algorithms should be considered
weak. See also '--allow-weak-digest-algos' to disable rejection of
weak digests. MD5 is always considered weak, and does not need to
be listed explicitly.

'--allow-weak-key-signatures'
To avoid a minor risk of collision attacks on third-party key
signatures made using SHA-1, those key signatures are considered
invalid. This options allows one to override this restriction.

'--override-compliance-check'
This was a temporary introduced option and has no more effect.

'--no-default-keyring'
Do not add the default keyring to the list of keyrings. Note that
GnuPG needs for almost all operations a keyring. Thus if you use
this option and do not provide alternate keyrings via '--keyring',
then GnuPG will still use the default keyring.

Note that if the option 'use-keyboxd' is enabled in 'common.conf',
no keyrings are used at all and keys are all maintained by the
keyboxd process in its own database.

'--no-keyring'
Do not use any keyring at all. This overrides the default and all
options which specify keyrings.

'--skip-verify'
Skip the signature verification step. This may be used to make the
decryption faster if the signature verification is not needed.

'--with-key-data'
Print key listings delimited by colons (like '--with-colons') and
print the public key data.

'--list-signatures'
'--list-sigs'
Same as '--list-keys', but the signatures are listed too. This
command has the same effect as using '--list-keys' with
'--with-sig-list'. Note that in contrast to '--check-signatures'
the key signatures are not verified. This command can be used to
create a list of signing keys missing in the local keyring; for
example:

gpg --list-sigs --with-colons USERID | \
awk -F: '$1=="sig" && $2=="?" {if($13){print $13}else{print $5}}'

'--fast-list-mode'
Changes the output of the list commands to work faster; this is
achieved by leaving some parts empty. Some applications don't need
the user ID and the trust information given in the listings. By
using this options they can get a faster listing. The exact
behaviour of this option may change in future versions. If you are
missing some information, don't use this option.

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

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

You can also use this option if you receive an encrypted message
which is abusive or offensive, to prove to the administrators of
the messaging system that the ciphertext transmitted corresponds to
an inappropriate plaintext so they can take action against the
offending user.

'--override-session-key STRING'
'--override-session-key-fd FD'
Don't use the public key but the session key STRING respective the
session key taken from the first line read from file descriptor FD.
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. Note that using
'--override-session-key' may reveal the session key to all local
users via the global process table. Often it is useful to combine
this option with '--no-keyring'.

'--ask-sig-expire'
'--no-ask-sig-expire'
When making a data signature, prompt for an expiration time. If
this option is not specified, the expiration time set via
'--default-sig-expire' is used. '--no-ask-sig-expire' disables
this option.

'--default-sig-expire'
The default expiration time to use for signature expiration. Valid
values are "0" for no expiration, a number followed by the letter d
(for days), w (for weeks), m (for months), or y (for years) (for
example "2m" for two months, or "5y" for five years), or an
absolute date in the form YYYY-MM-DD. Defaults to "0".

'--ask-cert-expire'
'--no-ask-cert-expire'
When making a key signature, prompt for an expiration time. If
this option is not specified, the expiration time set via
'--default-cert-expire' is used. '--no-ask-cert-expire' disables
this option.

'--default-cert-expire'
The default expiration time to use for key signature expiration.
Valid values are "0" for no expiration, a number followed by the
letter d (for days), w (for weeks), m (for months), or y (for
years) (for example "2m" for two months, or "5y" for five years),
or an absolute date in the form YYYY-MM-DD. Defaults to "0".

'--default-new-key-algo STRING'
This option can be used to change the default algorithms for key
generation. The STRING is similar to the arguments required for
the command '--quick-add-key' but slightly different. For example
the current default of '"rsa2048/cert,sign+rsa2048/encr"' (or
'"rsa3072"') can be changed to the value of what we currently call
future default, which is '"ed25519/cert,sign+cv25519/encr"'. You
need to consult the source code to learn the details. Note that
the advanced key generation commands can always be used to specify
a key algorithm directly.

'--no-auto-trust-new-key'
When creating a new key the ownertrust of the new key is set to
ultimate. This option disables this and the user needs to manually
assign an ownertrust value.

'--force-sign-key'
This option modifies the behaviour of the commands
'--quick-sign-key', '--quick-lsign-key', and the "sign"
sub-commands of '--edit-key' by forcing the creation of a key
signature, even if one already exists.

'--forbid-gen-key'
This option is intended for use in the global config file to
disallow the use of generate key commands. Those commands will
then fail with the error code for Not Enabled.

'--allow-secret-key-import'
This is an obsolete option and is not used anywhere.

'--allow-multiple-messages'
'--no-allow-multiple-messages'
These are obsolete options; they have no more effect since GnuPG
2.2.8.

'--enable-special-filenames'
This option enables a mode in which filenames of the form '-&n',
where n is a non-negative decimal number, refer to the file
descriptor n and not to a file with that name.

'--no-expensive-trust-checks'
Experimental use only.

'--preserve-permissions'
Don't change the permissions of a secret keyring back to user
read/write only. Use this option only if you really know what you
are doing.

'--default-preference-list STRING'
Set the list of default preferences to STRING. This preference
list is used for new keys and becomes the default for "setpref" in
the '--edit-key' menu.

'--default-keyserver-url NAME'
Set the default keyserver URL to NAME. This keyserver will be used
as the keyserver URL when writing a new self-signature on a key,
which includes key generation and changing preferences.

'--list-config'
Display various internal configuration parameters of GnuPG. This
option is intended for external programs that call GnuPG to perform
tasks, and is thus not generally useful. See the file
'doc/DETAILS' in the source distribution for the details of which
configuration items may be listed. '--list-config' is only usable
with '--with-colons' set.

'--list-gcrypt-config'
Display various internal configuration parameters of Libgcrypt.

'--gpgconf-list'
This command is similar to '--list-config' but in general only
internally used by the 'gpgconf' tool.

'--gpgconf-test'
This is more or less dummy action. However it parses the
configuration file and returns with failure if the configuration
file would prevent 'gpg' from startup. Thus it may be used to run
a syntax check on the configuration file.

'--chuid UID'
Change the current user to UID which may either be a number or a
name. This can be used from the root account to run gpg for
another user. If UID is not the current UID a standard PATH is set
and the envvar GNUPGHOME is unset. To override the latter the
option '--homedir' can be used. This option has only an effect
when used on the command line. This option has currently no effect
at all on Windows.

---------- Footnotes ----------

(1) Using a little social engineering anyone who is able to decrypt
the message can check whether one of the other recipients is the one he
suspects.