1.2.1 How to change the configuration

These options are used to change the configuration and are usually found in the option file.

--default-key name

Use name as the default key to sign with. If this option is not used, the default key is the first key found in the secret keyring. Note that ‘-u’ or ‘--local-user’ overrides this option.

--default-recipient name

Use name as default recipient if option ‘--recipient’ is not used and don’t ask if this is a valid one. name must be non-empty.

--default-recipient-self

Use the default key as default recipient if option ‘--recipient’ is not used and don’t ask if this is a valid one. The default key is the first one from the secret keyring or the one set with ‘--default-key’.

--no-default-recipient

Reset ‘--default-recipient’ and ‘--default-recipient-self’.

-v, --verbose

Give more information during processing. If used twice, the input data is listed in detail.

--no-verbose

Reset verbose level to 0.

-q, --quiet

Try to be as quiet as possible.

--batch

--no-batch

Use batch mode. Never ask, do not allow interactive commands. ‘--no-batch’ disables this option. Note that even with a filename given on the command line, gpg might still need to read from STDIN (in particular if gpg figures that the input is a detached signature and no data file has been specified). Thus if you do not want to feed data via STDIN, you should connect STDIN to ‘/dev/null’.

--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 even if ‘--batch’ is used.

--yes

Assume "yes" on most questions.

--no

Assume "no" on most questions.

--list-options parameters

This is a space or comma delimited string that gives options used when listing keys and signatures (that is, ‘--list-keys’, ‘--list-sigs’, ‘--list-public-keys’, ‘--list-secret-keys’, and the ‘--edit-key’ functions). Options can be prepended with a ‘no-’ (after the two dashes) to give the opposite meaning. The options are:

show-photos

Causes ‘--list-keys’, ‘--list-sigs’, ‘--list-public-keys’, and ‘--list-secret-keys’ to display any photo IDs attached to the key. Defaults to no. See also ‘--photo-viewer’. Does not work with ‘--with-colons’: see ‘--attribute-fd’ for the appropriate way to get photo data for scripts and other frontends.

show-policy-urls

Show policy URLs in the ‘--list-sigs’ or ‘--check-sigs’ listings. Defaults to no.

show-notations

show-std-notations

show-user-notations

Show all, IETF standard, or user-defined signature notations in the ‘--list-sigs’ or ‘--check-sigs’ listings. Defaults to no.

show-keyserver-urls

Show any preferred keyserver URL in the ‘--list-sigs’ or ‘--check-sigs’ listings. Defaults to no.

show-uid-validity

Display the calculated validity of user IDs during key listings. Defaults to no.

show-unusable-uids

Show revoked and expired user IDs in key listings. Defaults to no.

show-unusable-subkeys

Show revoked and expired subkeys in key listings. Defaults to no.

show-keyring

Display the keyring name at the head of key listings to show which keyring a given key resides on. Defaults to no.

show-sig-expire

Show signature expiration dates (if any) during ‘--list-sigs’ or ‘--check-sigs’ listings. Defaults to no.

show-sig-subpackets

Include signature subpackets in the key listing. This option can take an optional argument list of the subpackets to list. If no argument is passed, list all subpackets. Defaults to no. This option is only meaningful when using ‘--with-colons’ along with ‘--list-sigs’ or ‘--check-sigs’.

--verify-options parameters

This is a space or comma delimited string that gives options used when verifying signatures. Options can be prepended with a ‘no-’ to give the opposite meaning. The options are:

show-photos

Display any photo IDs present on the key that issued the signature. Defaults to no. See also ‘--photo-viewer’.

show-policy-urls

Show policy URLs in the signature being verified. Defaults to no.

show-notations

show-std-notations

show-user-notations

Show all, IETF standard, or user-defined signature notations in the signature being verified. Defaults to IETF standard.

show-keyserver-urls

Show any preferred keyserver URL in the signature being verified. Defaults to no.

show-uid-validity

Display the calculated validity of the user IDs on the key that issued the signature. Defaults to no.

show-unusable-uids

Show revoked and expired user IDs during signature verification. Defaults to no.

show-primary-uid-only

Show only the primary user ID during signature verification. That is all the AKA lines as well as photo Ids are not shown with the signature verification status.

pka-lookups

Enable PKA lookups to verify sender addresses. Note that PKA is based on DNS, and so enabling this option may disclose information on when and what signatures are verified or to whom data is encrypted. This is similar to the "web bug" described for the auto-key-retrieve feature.

pka-trust-increase

Raise the trust in a signature to full if the signature passes PKA validation. This option is only meaningful if pka-lookups is set.

--enable-dsa2

--disable-dsa2

Enable hash truncation for all DSA keys even for old DSA Keys up to 1024 bit. This is also the default with ‘--openpgp’. Note that older versions of GnuPG also required this flag to allow the generation of DSA larger than 1024 bit.

--photo-viewer string

This is the command line that should be run to view a photo ID. "%i" will be expanded to a filename containing the photo. "%I" does the same, except the file will not be deleted once the viewer exits. Other flags are "%k" for the key ID, "%K" for the long key ID, "%f" for the key fingerprint, "%t" for the extension of the image type (e.g. "jpg"), "%T" for the MIME type of the image (e.g. "image/jpeg"), "%v" for the single-character calculated validity of the image being viewed (e.g. "f"), "%V" for the calculated validity as a string (e.g. "full"), and "%%" for an actual percent sign. If neither %i or %I are present, then the photo will be supplied to the viewer on standard input.

The default viewer is "xloadimage -fork -quiet -title ’KeyID 0x%k’ STDIN". Note that if your image viewer program is not secure, then executing it from GnuPG does not make it secure.

--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 environment variable. Note, that on W32 system this value is ignored when searching for keyserver helpers.

--keyring file

Add file to the current list of keyrings. If file begins with a tilde and a slash, these are replaced by the $HOME directory. If the filename does not contain a slash, it is assumed to be in the GnuPG home directory ("~/.gnupg" if ‘--homedir’ or $GNUPGHOME is not used).

Note that this adds a keyring to the current list. If the intent is to use the specified keyring alone, use ‘--keyring’ along with ‘--no-default-keyring’.

--secret-keyring file

Same as ‘--keyring’ but for the secret keyrings.

--primary-keyring file

Designate file as the primary public keyring. This means that newly imported keys (via ‘--import’ or keyserver ‘--recv-from’) will go to this keyring.

--trustdb-name file

Use file instead of the default trustdb. If file begins with a tilde and a slash, these are replaced by the $HOME directory. If the filename does not contain a slash, it is assumed to be in the GnuPG home directory (‘~/.gnupg’ if ‘--homedir’ or $GNUPGHOME is not used).

--homedir dir

Set the name of the home directory to dir. If this option is not used, the home directory defaults to ‘~/.gnupg’. It is only recognized when given on the command line. It also overrides any home directory stated through the environment variable GNUPGHOME or (on W32 systems) by means of the Registry entry HKCU\Software\GNU\GnuPG:HomeDir.

--display-charset name

Set the name of the native character set. This is used to convert some informational strings like user IDs to the proper UTF-8 encoding. Note that this has nothing to do with the character set of data to be encrypted or signed; GnuPG does not recode user-supplied data. If this option is not used, the default character set is determined from the current locale. A verbosity level of 3 shows the chosen set. Valid values for name are:

iso-8859-1

This is the Latin 1 set.

iso-8859-2

The Latin 2 set.

iso-8859-15

This is currently an alias for the Latin 1 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 command line arguments are given as UTF8 strings. The default (‘--no-utf8-strings’) is to assume that arguments are encoded in the character set as specified by ‘--display-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.

-z n

--compress-level n

--bzip2-compress-level n

Set compression level to n for the ZIP and ZLIB compression algorithms. The default is to use the default compression level of zlib (normally 6). ‘--bzip2-compress-level’ sets the compression level for the BZIP2 compression algorithm (defaulting to 6 as well). This is a different option from ‘--compress-level’ since BZIP2 uses a significant amount of memory for each additional compression level. ‘-z’ sets both. A value of 0 for n disables compression.

--bzip2-decompress-lowmem

Use a different decompression method for BZIP2 compressed files. This alternate method uses a bit more than half the memory, but also runs at half the speed. This is useful under extreme low memory circumstances when the file was originally compressed at a high ‘--bzip2-compress-level’.

--mangle-dos-filenames

--no-mangle-dos-filenames

Older version of Windows cannot handle filenames with more than one dot. ‘--mangle-dos-filenames’ causes GnuPG to replace (rather than add to) the extension of an output filename to avoid this problem. This option is off by default and has no effect on non-Windows platforms.

--ask-cert-level

--no-ask-cert-level

When making a key signature, prompt for a certification level. If this option is not specified, the certification level used is set via ‘--default-cert-level’. See ‘--default-cert-level’ for information on the specific levels and how they are used. ‘--no-ask-cert-level’ disables this option. This option defaults to no.

--default-cert-level n

The default to use for the check level when signing a key.

0 means you make no particular claim as to how carefully you verified the key.

1 means you believe the key is owned by the person who claims to own it but you could not, or did not verify the key at all. This is useful for a "persona" verification, where you sign the key of a pseudonymous user.

2 means you did casual verification of the key. For example, this could mean that you verified that the key fingerprint and checked the user ID on the key against a photo ID.

3 means you did extensive verification of the key. For example, this could mean that you verified the key fingerprint with the owner of the key in person, and that you checked, by means of a hard to forge document with a photo ID (such as a passport) that the name of the key owner matches the name in the user ID on the key, and finally that you verified (by exchange of email) that the email address on the key belongs to the key owner.

Note that the examples given above for levels 2 and 3 are just that: examples. In the end, it is up to you to decide just what "casual" and "extensive" mean to you.

This option defaults to 0 (no particular claim).

--min-cert-level

When building the trust database, treat any signatures with a certification level below this as invalid. Defaults to 2, which disregards level 1 signatures. Note that level 0 "no particular claim" signatures are always accepted.

--trusted-key long key ID

Assume that the specified key (which must be given as a full 8 byte key ID) is as trustworthy as one of your own secret keys. This option is useful if you don’t want to keep your secret keys (or one of them) online but still want to be able to check the validity of a given recipient’s or signator’s key.

--trust-model pgp|classic|direct|always|auto

Set what trust model GnuPG should follow. The models are:

pgp

This is the Web of Trust combined with trust signatures as used in PGP 5.x and later. This is the default trust model when creating a new trust database.

classic

This is the standard Web of Trust as used in PGP 2.x and earlier.

direct

Key validity is set directly by the user and not calculated via the Web of Trust.

always

Skip key validation and assume that used keys are always fully trusted. You generally won’t use this unless you are using some external validation scheme. This option also suppresses the "[uncertain]" tag printed with signature checks when there is no evidence that the user ID is bound to the key.

auto

Select the trust model depending on whatever the internal trust database says. This is the default model if such a database already exists.

--auto-key-locate parameters

--no-auto-key-locate

GnuPG can automatically locate and retrieve keys as needed using this option. This happens when encrypting to an email address (in the "user@example.com" form), and there are no user@example.com keys on the local keyring. This option takes any number of the following mechanisms, in the order they are to be tried:

cert

Locate a key using DNS CERT, as specified in rfc4398.

pka

Locate a key using DNS PKA.

ldap

Using DNS Service Discovery, check the domain in question for any LDAP keyservers to use. If this fails, attempt to locate the key using the PGP Universal method of checking ‘ldap://keys.(thedomain)’.

keyserver

Locate a key using whatever keyserver is defined using the ‘--keyserver’ option.

keyserver-URL

In addition, a keyserver URL as used in the ‘--keyserver’ option may be used here to query that particular keyserver.

local

Locate the key using the local keyrings. This mechanism allows to select the order a local key lookup is done. Thus using ‘--auto-key-locate local’ is identical to ‘--no-auto-key-locate’.

nodefault

This flag disables the standard local key lookup, done before any of the mechanisms defined by the ‘--auto-key-locate’ are tried. The position of this mechanism in the list does not matter. It is not required if local is also used.

--keyid-format short|0xshort|long|0xlong

Select how to display key IDs. "short" is the traditional 8-character key ID. "long" is the more accurate (but less convenient) 16-character key ID. Add an "0x" to either to include an "0x" at the beginning of the key ID, as in 0x99242560. Note that this option is ignored if the option –with-colons is used.

--keyserver name

Use name as your keyserver. This is the server that ‘--recv-keys’, ‘--send-keys’, and ‘--search-keys’ will communicate with to receive keys from, send keys to, and search for keys on. The format of the name is a URI: ‘scheme:[//]keyservername[:port]’ The scheme is the type of keyserver: "hkp" for the HTTP (or compatible) keyservers, "ldap" for the LDAP keyservers, or "mailto" for the Graff email keyserver. Note that your particular installation of GnuPG may have other keyserver types available as well. Keyserver schemes are case-insensitive. After the keyserver name, optional keyserver configuration options may be provided. These are the same as the global ‘--keyserver-options’ from below, but apply only to this particular keyserver.

Most keyservers synchronize with each other, so there is generally no need to send keys to more than one server. The keyserver hkp://keys.gnupg.net uses round robin DNS to give a different keyserver each time you use it.

--keyserver-options name=value1

This is a space or comma delimited string that gives options for the keyserver. Options can be prefixed with a ‘no-’ to give the opposite meaning. Valid import-options or export-options may be used here as well to apply to importing (‘--recv-key’) or exporting (‘--send-key’) a key from a keyserver. While not all options are available for all keyserver types, some common options are:

include-revoked

When searching for a key with ‘--search-keys’, include keys that are marked on the keyserver as revoked. Note that not all keyservers differentiate between revoked and unrevoked keys, and for such keyservers this option is meaningless. Note also that most keyservers do not have cryptographic verification of key revocations, and so turning this option off may result in skipping keys that are incorrectly marked as revoked.

include-disabled

When searching for a key with ‘--search-keys’, include keys that are marked on the keyserver as disabled. Note that this option is not used with HKP keyservers.

auto-key-retrieve

This option enables the automatic retrieving of keys from a keyserver when verifying signatures made by keys that are not on the local keyring.

Note that this option makes a "web bug" like behavior possible. Keyserver operators can see which keys you request, so by sending you a message signed by a brand new key (which you naturally will not have on your local keyring), the operator can tell both your IP address and the time when you verified the signature.

honor-keyserver-url

When using ‘--refresh-keys’, if the key in question has a preferred keyserver URL, then use that preferred keyserver to refresh the key from. In addition, if auto-key-retrieve is set, and the signature being verified has a preferred keyserver URL, then use that preferred keyserver to fetch the key from. Defaults to yes.

honor-pka-record

If auto-key-retrieve is set, and the signature being verified has a PKA record, then use the PKA information to fetch the key. Defaults to yes.

include-subkeys

When receiving a key, include subkeys as potential targets. Note that this option is not used with HKP keyservers, as they do not support retrieving keys by subkey id.

use-temp-files

On most Unix-like platforms, GnuPG communicates with the keyserver helper program via pipes, which is the most efficient method. This option forces GnuPG to use temporary files to communicate. On some platforms (such as Win32 and RISC OS), this option is always enabled.

keep-temp-files

If using ‘use-temp-files’, do not delete the temp files after using them. This option is useful to learn the keyserver communication protocol by reading the temporary files.

verbose

Tell the keyserver helper program to be more verbose. This option can be repeated multiple times to increase the verbosity level.

timeout

Tell the keyserver helper program how long (in seconds) to try and perform a keyserver action before giving up. Note that performing multiple actions at the same time uses this timeout value per action. For example, when retrieving multiple keys via ‘--recv-keys’, the timeout applies separately to each key retrieval, and not to the ‘--recv-keys’ command as a whole. Defaults to 30 seconds.

http-proxy=value

Set the proxy to use for HTTP and HKP keyservers. This overrides the "http_proxy" environment variable, if any.

max-cert-size

When retrieving a key via DNS CERT, only accept keys up to this size. Defaults to 16384 bytes.

debug

Turn on debug output in the keyserver helper program. Note that the details of debug output depends on which keyserver helper program is being used, and in turn, on any libraries that the keyserver helper program uses internally (libcurl, openldap, etc).

check-cert

Enable certificate checking if the keyserver presents one (for hkps or ldaps). Defaults to on.

ca-cert-file

Provide a certificate store to override the system default. Only necessary if check-cert is enabled, and the keyserver is using a certificate that is not present in a system default certificate list.

Note that depending on the SSL library that the keyserver helper is built with, this may actually be a directory or a file.

--completes-needed n

Number of completely trusted users to introduce a new key signer (defaults to 1).

--marginals-needed n

Number of marginally trusted users to introduce a new key signer (defaults to 3)

--max-cert-depth n

Maximum depth of a certification chain (default is 5).

--simple-sk-checksum

Secret keys are integrity protected by using a SHA-1 checksum. This method is part of the upcoming enhanced OpenPGP specification but GnuPG already uses it as a countermeasure against certain attacks. Old applications don’t understand this new format, so this option may be used to switch back to the old behaviour. Using this option bears a security risk. Note that using this option only takes effect when the secret key is encrypted - the simplest way to make this happen is to change the passphrase on the key (even changing it to the same value is acceptable).

--no-sig-cache

Do not cache the verification status of key signatures. Caching gives a much better performance in key listings. However, if you suspect that your public keyring is not save against write modifications, you can use this option to disable the caching. It probably does not make sense to disable it because all kind of damage can be done if someone else has write access to your public keyring.

--no-sig-create-check

GnuPG normally verifies each signature right after creation to protect against bugs and hardware malfunctions which could leak out bits from the secret key. This extra verification needs some time (about 115% for DSA keys), and so this option can be used to disable it. However, due to the fact that the signature creation needs manual interaction, this performance penalty does not matter in most settings.

--auto-check-trustdb

--no-auto-check-trustdb

If GnuPG feels that its information about the Web of Trust has to be updated, it automatically runs the ‘--check-trustdb’ command internally. This may be a time consuming process. ‘--no-auto-check-trustdb’ disables this option.

--use-agent

--no-use-agent

This is dummy option. gpg2 always requires the agent.

--gpg-agent-info

This is dummy option. It has no effect when used with gpg2.

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

--exit-on-status-write-error

This option will cause write errors on the status FD to immediately terminate the process. That should in fact be the default but it never worked this way and thus we need an option to enable this, so that the change won’t break applications which close their end of a status fd connected pipe too early. Using this option along with ‘--enable-progress-filter’ may be used to cleanly cancel long running gpg operations.

--limit-card-insert-tries n

With n greater than 0 the number of prompts asking to insert a smartcard gets limited to N-1. Thus with a value of 1 gpg won’t at all ask to insert a card if none has been inserted at startup. This option is useful in the configuration file in case an application does not know about the smartcard support and waits ad infinitum for an inserted card.

--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-greeting

Suppress the initial copyright message.

--no-secmem-warning

Suppress the warning about "using insecure memory".

--no-permission-warning

Suppress the warning about unsafe file and home directory (‘--homedir’) permissions. Note that the permission checks that GnuPG performs are not intended to be authoritative, but rather they simply warn about certain common permission problems. Do not assume that the lack of a warning means that your system is secure.

Note that the warning for unsafe ‘--homedir’ permissions cannot be suppressed in the gpg.conf file, as this would allow an attacker to place an unsafe gpg.conf file in place, and use this file to suppress warnings about itself. The ‘--homedir’ permissions warning may only be suppressed on the command line.

--no-mdc-warning

Suppress the warning about missing MDC integrity protection.

--require-secmem

--no-require-secmem

Refuse to run if GnuPG cannot get secure memory. Defaults to no (i.e. run, but give a warning).

--require-cross-certification

--no-require-cross-certification

When verifying a signature made from a subkey, ensure that the cross certification "back signature" on the subkey is present and valid. This protects against a subtle attack against subkeys that can sign. Defaults to ‘--require-cross-certification’ for gpg2.

--expert

--no-expert

Allow the user to do certain nonsensical or "silly" things like signing an expired or revoked key, or certain potentially incompatible things like generating unusual key types. This also disables certain warning messages about potentially incompatible actions. As the name implies, this option is for experts only. If you don’t fully understand the implications of what it allows you to do, leave this off. ‘--no-expert’ disables this option.

This document was generated on February 1, 2012 using texi2html 5.0.