Verbose Description of VSD Registry Settings

This document describes the Registry Setting for GnuPG VS-Desktop and GnuPG Desktop in a more verbose manner. In particular the actual used options of the GnuPG engine are described.

We first describe the Registry setting and then the corresponding option used to implement this in GnuPG. The description of the defaults for the engine option may be different from the one used in the installed global configuration files (and thus the Registry).

Keep in mind that some settings can be customized by the user. Below those ones for which this is true in the standard configuration are marked with «option[user]».

OpenPGP related settings

NewKeyAlgo

Used to change the default algorithm for new keys. Valid values are:

  • rsa3072
  • rsa4096
  • brainpoolP256r1
  • brainpoolP384r1
  • brainpoolP512r1
  • none

The value "none" disallows the generation of new keys.

This Registry setting is read by gpg.conf and implemented using the options default-new-key-algo and forbid-gen-key:

default-new-key-algo

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.

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.

DisableWKD

Any value interpreted as non-zero (e.g. "1") disables the use of the Web Key Directory for automatic key lookup.

This Registry setting is read by gpg.conf and implemented using the option auto-key-locate. If not set the value for this option is "local,keyserver,wkd"; if set the value is "local,keyserver".

auto-key-locate mechanisms

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 mechanisms listed below, in the order they are to be tried. Instead of listing the mechanisms as comma delimited arguments, the option may also be given several times to add more mechanism. The option –no-auto-key-locate or the mechanism "clear" resets the list. The default is "local,wkd".

cert
Locate a key using DNS CERT, as specified in RFC-4398.
pka
Locate a key using DNS PKA.
dane
Locate a key using DANE, as specified in draft-ietf-dane-openpgpkey-05.txt.
wkd
Locate a key using the Web Key Directory protocol.
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)’.
ntds
Locate the key using the Active Directory (Windows only). This method also allows to search by fingerprint using the command –locate-external-key. Note that this mechanism is actually a shortcut for the mechanism ‘keyserver’ but using "ldap:///" as the keyserver.
keyserver
Locate a key using a keyserver. This method also allows to search by fingerprint using the command –locate-external-key if any of the configured keyservers is an LDAP server.
keyserver-URL
In addition, a keyserver URL as used in the dirmngr configuration may be used here to query that particular keyserver. This method also allows to search by fingerprint using the command –locate-external-key if the URL specifies an LDAP server.
local
Locate the key using the local keyrings. This mechanism allows the user 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.
clear
Clear all defined mechanisms. This is useful to override mechanisms given in a config file. Note that a nodefault in mechanisms will also be cleared unless it is given after the clear.

DisableAKR

Any value interpreted as non-zero (e.g. "1") disables the use of automatic key retrieval from key servers when checking signatures. Default value is 1.

This Registry setting is read by gpg.conf and implemented using the option auto-key-retrieve. A new installation of VSD disables this option using the registry (i.e. sets the value for the Registry key to "1").

auto-key-retrieve[user]

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

The order of methods tried to lookup the key is:

  1. If the option --auto-key-import is set and the signatures includes an embedded key, that key is used to verify the signature and on verification success that key is imported.

  2. If a preferred keyserver is specified in the signature and the option honor-keyserver-url is active (which is not the default), that keyserver is tried. Note that the creator of the signature uses the option sig-keyserver-url to specify the preferred keyserver for data signatures.

  3. If the signature has the Signer's UID set (e.g. using --sender while creating the signature) a Web Key Directory (WKD) lookup is done. This is the default configuration but can be disabled by removing WKD from the auto-key-locate list or by using the option --disable-signer-uid.

    1. If the option honor-pka-record is active, the legacy PKA method is used.
    2. If any keyserver is configured and the Issuer Fingerprint is part of the signature (since GnuPG 2.1.16), the configured keyservers are tried.

Note that this option makes a “web bug” like behavior possible. Keyserver or Web Key Directory 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.

AutoKeyImport

Any value interpreted as non-zero (e.g. "1") nables an offline mechanism to get a missing public key for signature verification and for later encryption to this key. If this option is enabled and a signature includes an embedded key, that key is used to verify the signature and on verification success the key is imported. Used together with IncludeKeyBlock. [since 3.1.24.0]

This Registry setting is read by gpg.conf and implemented using the option auto-key-import

auto-key-import[user]

This is an offline mechanism to get a missing key for signature verification and for later encryption to this key. If this option is enabled and a signature includes an embedded key, that key is used to verify the signature and on verification success that key is imported. The option is by default disabled.

On the sender (signing) site the option --include-key-block needs to be used to put the public part of the signing key as “Key Block Subpacket” into the signature.

IncludeKeyBlock

Any value interpreted as non-zero (e.g. "1") puts the used public key into a data signature. This embedded key is stripped down to a single user id and includes only the signing subkey and all valid encryption subkeys. This option is the OpenPGP counterpart to the S/MIME feature of embedding the certificates into signatures. It allows the recipient of a signed message to reply encrypted to the sender without first using any online directories to lookup the key. Used together with AutoKeyImport. [since 3.1.24.0]

This Registry setting is read by gpg.conf and implemented using the option include-key-block

include-key-block[user]

This option is used to embed the actual signing key into a data signature. The embedded key is stripped down to a single user id and includes only the signing subkey used to create the signature as well as as valid encryption subkeys. All other info is removed from the key to keep it and thus the signature small. This option is the OpenPGP counterpart to the gpgsm option --include-certs.

TrustedKey1

The value specifies a fixed trust root (trusted-key). If more than one trust root is required, the entries TrustedKey2, TrustedKey3, TrustedKey4, TrustedKey5 may also be used. Take care to specify the 40 hex-digit fingerprint of those trusted keys.

This Registry setting is read by gpg.conf and implemented using the option trusted-key.

trusted-key

One argument with a long key-ID or a fingerprint is required.

Assume that the specified key (which should be given as fingerprint) 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. If the given key is not locally available but an LDAP keyserver is configured the missing key is imported from that server.

EncryptTo1

The value specifies a key wich is always used in addition to the specified recipient keys. This may be used for an archival key. A second such key may be given using EncryptTo2. Please use the 40 hex-digit fingerprint as value and not a user name or the shorter key-id. [since 3.1.20.7]

This Registry setting is read by gpg.conf and implemented using the option encrypt-to

encrypt-to

One argument with a name is expected.

Same as --recipient but this one is intended for use in the options file and may be used with your own user-id as an “encrypt-to-self”. These keys are only used when there are other recipients given either by use of --recipient or by the asked user id. No trust checking is performed for these user ids and even disabled keys can be used.

S/MIME related settings

DisableUserTrustlist

Any value interpreted as non-zero (e.g. "1") entirely ignores the users trustlist.txt and considers only the global trustlist. [since 3.1.24.0]

This Registry setting is read by gpg-agent.conf and implemented using the option no-user-trustlist

no-user-trustlist

Entirely ignore the user trust list and consider only the global trustlist. This implies the option –no-allow-mark-trusted which is anyway set in GnuPG VS-Desktop.

SysTrustlistFile

The list of trusted root certificates are distributed in a file named trustlist.txt. This option allows to specify another file for this list. This is needed to avoid overwriting a custom version of the list by a software update. [since 3.1.24.0]

This Registry setting is read by gpg-agent.conf and implemented using the option sys-trustlist-name (note that the gpg-agent options ends in "name").

sys-trustlist-name

A file name is expected as argument.

Changes the default name for the global trustlist from trustlist.txt to the give file. If the given file does not contain any slashes and does not start with ~/ it is searched in the global configuration directory.

GpgsmCompatibility

Set compatibility flags to work around problems due to non-compliant certificates or data. The flags are given as a comma separated list of flag names and are OR-ed together. Please ask for advise. [since 3.1.23.0]

This Registry setting is read by gpgsm.conf and implemented using the option compatibility-flags

compatibility-flags

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

Private key related settings

Note: These settings do not affect smart card PINs.

CacheTime

The number of seconds a password is cached after its last use. Re-triggered with each use. Defaults to 900 (15 minutes).

This Registry setting is read by gpg-agent.conf and implemented using the option default-cache-ttl

default-cache-ttl[user]

The required argument is a number with the TTL given in seconds.

Set the time a cache entry is valid to N seconds. The default is 600 seconds. Each time a cache entry is accessed, the entry's timer is reset. To set an entry's maximum lifetime, use max-cache-ttl. Note that a cached passphrase may not be evicted immediately from memory if no client requests a cache operation. This is due to an internal housekeeping function which is only run every few seconds.

CacheTimeMax

The number of seconds a password is cached after its first use. Defaults to 3600 (1 hour).

This Registry setting is read by gpg-agent.conf and implemented using the option max-cache-ttl

max-cache-ttl[user]

The required argument is a number with the TTL given in seconds.

Set the maximum time a cache entry is valid to N seconds. After this time a cache entry will be expired even if it has been accessed recently or has been set using gpg-preset-passphrase. The default are 2 hours (7200 seconds).

MinPasswordLen

The minimum number of characters required for a password. The default is 9. Note that in addition to this value the regular expressions in asymrules.txt and symrules.txt also take effect. [since 3.1.21.1]

This Registry setting is read by gpg-agent.conf and implemented using the option min-passphrase-len.

min-passphrase-len

The required argument is a non-negative number.

Set the minimal length of a passphrase. When entering a new passphrase shorter than this value a warning will be displayed. Defaults to 8.

AsymrulesFile

The pattern defining the rules for passwords to protect private keys are distributed in a file named asymrules.txt. This option allows to specify another file for these pattern. Use only if advised to do so. [since 3.1.21.3]

This Registry setting is read by gpg-agent.conf and implemented using the option check-passphrase-pattern.

check-passphrase-pattern=

The required argument is a file name.

Check the passphrase against the pattern given in the file. When entering a new passphrase matching one of these pattern a warning will be displayed. If the file name does not contain any slashes and does not start with ~/ it is searched in the global configuration directory. The default is not to use any pattern file.

Security note: It is known that checking a passphrase against a list of pattern or even against a complete dictionary is not very effective to enforce good passphrases. Users will soon figure up ways to bypass such a policy. A better policy is to educate users on good security behavior and optionally to run a passphrase cracker regularly on all users passphrases to catch the very simple ones.

SymrulesFile

The pattern defining the rules for symmetric passwords are distributed in a file named symrules.txt. This option allows to specify another file for these pattern. Use only if advised to do so. [since 3.1.21.3]

This Registry setting is read by gpg-agent.conf and implemented using the option check-sym-passphrase-pattern.

check-sym-passphrase-pattern

This is the same as sym-passphrase-pattern but is only used when creating a new symmetric key to allow the use of different patterns for such passphrases.

Network related settings

NtdsKeyserver

The value specifies an Active Directory authenticated LDS server name for OpenPGP keys. If a non-standard port is used it must be given delimited by a colon. Examples: "openpgp-lds", "keyserver.example.com:8389".

This Registry setting is read by dirmngr.conf and implemented using the option keyserver. The value from the registy is expanded using the patterm "ldap://$value/????gpgNtds=1". Thus this a shortcut for the Registry setting Keyserver; see below for details.

Keyserver

A full keyserver specification string; used only if NtdsKeyserver is not set. The default is "ldap:///" to specify an OpenPGP keyserver as part of the AD. In case of initial delays in name resolution with LDAP servers on Windows, it is often useful to use a value like 

openpgp-lds:::::starttls,ntds,areconly

instead of NtdsKeyserver or the URL format.

This Registry setting is read by dirmngr.conf and implemented using the option keyserver.

keyserver

The required argument is a string (name).

Use name as your keyserver. This is the server that gpg communicates with to receive keys, send keys, and search for keys. The format of name is an URI: 

scheme:[//]keyservername[:port]

The scheme is the type of the keyserver: "hkp" for the HTTP (or compatible) keyservers or "ldap" for the LDAP keyservers. 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 --keyserver-options of gpg, but apply only to this particular keyserver.

Some keyservers synchronize with each other, so there is not always a need to send keys to more than one server. Somes keyservers use round robin DNS to give a different keyserver each time you use it.

If exactly two keyservers are configured and only one is a Tor hidden service (.onion), Dirmngr selects the keyserver to use depending on whether Tor is locally running or not. The check for a running Tor is done for each new connection.

If no keyserver is explicitly configured, dirmngr will use the built-in default of @code{https://keyserver.ubuntu.com}.

Windows users with a keyserver running on their Active Directory may use the short form @code{ldap:///} for @var{name} to access this directory.

For accessing anonymous LDAP keyservers name is in general just a ldaps://ldap.example.com. A BaseDN parameter should never be specified. If authentication is required things are more complicated and two methods are available:

The modern method (since version 2.2.28) is to use the very same syntax as used with the option --ldapserver. Please see over there for details; here is an example: 

keyserver ldap:ldap.example.com::uid=USERNAME,ou=GnuPG Users,
    dc=example,dc=com:PASSWORD::starttls

The older method is to use a full URL for name; for example: 

keyserver ldaps://ldap.example.com/????bindname=uid=USERNAME
     %2Cou=GnuPG%20Users%2Cdc=example%2Cdc=com,password=PASSWORD

Put this all on one line without any spaces and keep the '%2C' as given. Replace USERNAME, PASSWORD, and the 'dc' parts according to the instructions received from your LDAP administrator. Note that only simple authentication (i.e. cleartext passwords) is supported and thus using ldaps is strongly suggested (since 2.2.28 "ldaps" defaults to port 389 and uses STARTTLS). On Windows authentication via AD can be requested by adding gpgNtds=1 after the fourth question mark instead of the bindname and password parameter.

Ldapserver

A full LDAP server specification string. This will be used as the default LDAP server for X.509 certificate lookup. For example 

ldap.example.com:::::starttls,ntds

uses the given server in StartTLS mode with AD authentication. To use password based authentication this might be used 

ldap.example.com::username:mypassword::starttls

[since 3.1.21.1]

This Registry setting is read by dirmngr.conf and implemented using the option ldapserver.

ldapserver[user]

The required argument is a string (spec).

This is an alternative way to specify LDAP servers for CRL and X.509 certificate retrieval. If this option is used the servers configured in dirmngr_ldapservers.conf (or the file given by --ldapserverlist-file) are cleared. Note that dirmngr_ldapservers.conf is not read again by a reload signal. However, --ldapserver options are read again.

spec is either a proper LDAP URL or a colon delimited list of the form 

hostname:port:username:password:base_dn:flags:

with an optional prefix of ldap: (but without the two slashes which would turn this into a proper LDAP URL). flags is a list of one or more comma delimited keywords:

plain
The default: Do not use a TLS secured connection at all; the default port is 389.
starttls
Use STARTTLS to secure the connection; the default port is 389.
ldaptls
Tunnel LDAP through a TLS connection; the default port is 636.
ntds
On Windows authenticate the LDAP connection using the Active Directory with the current user.
areconly
On Windows use only the A or AAAA record when resolving the LDAP server name.

Note that in an URL style specification the scheme ldaps:// refers to STARTTLS and not to LDAP-over-TLS.

HttpProxy

If set specifies a proxy for HTTP. For example "proxy.local:8080".

This Registry setting is read by dirmngr.conf and implemented using the option http-proxy.

http-proxy[user]

The required argument is a string with host and optionally a colon delimited port number (host, port).

Use host and port to access HTTP servers. The use of this option overrides the environment variable http_proxy regardless whether --honor-http-proxy has been set.

LdapProxy

If set specifies a proxy for LDAP. For example "proxy.local:8389".

This Registry setting is read by dirmngr.conf and implemented using the option ldap-proxy.

ldap-proxy[user]

The required argument is a string with host and optionally a colon delimited port number (host, port).

Use host and port to connect to LDAP servers. If port is omitted, port 389 (standard LDAP port) is used. This overrides any specified host and port part in a LDAP URL and will also be used if host and port have been omitted from the URL.

IgnoreHttpDP

Any value interpreted as non-zero (e.g. "1") disables the use of HTTP CRL distribution points.

This Registry setting is read by dirmngr.conf and implemented using the option ignore-http-dp.

ignore-http-dp[user]

When looking for the location of a CRL, the to be tested certificate usually contains so called CRL Distribution Point (DP) entries which are URLs describing the way to access the CRL. The first found DP entry is used. With this option all entries using the HTTP scheme are ignored when looking for a suitable DP.

IgnoreLdapDP

Any value interpreted as non-zero (e.g. "1") disables the use of LDAP CRL distribution points.

This Registry setting is read by dirmngr.conf and implemented using the option ignore-ldap-dp.

ignore-ldap-dp[user]

This is similar to ignore-http-dp but ignores entries using the LDAP scheme. Both options may be combined resulting in ignoring DPs entirely.

DisableIPv4

Any value interpreted as non-zero (e.g. "1") disables the use of the IPv4 protocol. Used in case of problems with IPv4 connections. [since 3.1.24.0]

This Registry setting is read by dirmngr.conf and implemented using the option disable-ipv4.[user]

DisableIPv6

Any value interpreted as non-zero (e.g. "1") disables the use of the IPv6 protocol. Used in case of problems with IPv6 connections. [since 3.1.24.0]

This Registry setting is read by dirmngr.conf and implemented using the option disable-ipv6.[user]

ResolverTimeout

The timeout value in seconds for DNS requests. The default is 30 seconds. [since 3.1.24.0]

This Registry setting is read by dirmngr.conf and implemented using the option resolver-timeout.[user]

resolver-timeout

Set the timeout for the DNS resolver to N seconds. The default are 30 seconds.

ConnectTimeout

The timeout value in seconds for all HTTP, HTTPS, and other TCP connection attempts. The default is 15 seconds. For LDAP connections the native Windows settings must be used. [since 3.1.24.0]

This Registry setting is read by dirmngr.conf and implemented using the option connect-timeout.

connect-[quick-]timeout[user]

Set the timeout for HTTP and generic TCP connection attempts to N seconds. The value set with the quick variant is used when the –quick option has been given to certain Assuan commands. The quick value is capped at the value of the regular connect timeout. The default values are 15 and 2 seconds. Note that the timeout values are for each connection attempt; the connection code will attempt to connect all addresses listed for a server.

ConnectQuickTimeout

Like ConnectTimeout but for connection attempts which are required to happen fast. The default is 2 seconds. [since 3.1.24.0]

This Registry setting is read by dirmngr.conf and implemented using the option connect-quick-timeout. See above.

Smart card related settings

ReaderPort

The smart card reader to use. The GUI has an option to show all detected readers in the settings menu. The exact string needs to be entered. If this entry is not set and there is no local override the reader to use is determined by a simple heuristic.

This Registry setting is read by scdaemon.conf and implemented using the option reader-port. Note that the user may want to select its own reader-port which is supported by a dedicated GUI dialog in Kleopatra.

reader-port[user]

The require argument is a string.

This option may be used to specify the port of the card terminal. A value of 0 refers to the first serial device; add 32768 to access USB devices. The default is 32768 (first USB device). PC/SC or CCID readers might need a string here; run the program in verbose mode to get a list of available readers. The default is the first reader found.

To get a list of available CCID readers you may use this command: 

echo scd getinfo reader_list \
  | gpg-connect-agent --decode | awk '/^D/ @{print $2@}'

SharePort

Any value interpreted as non-zero (e.g. "1") enables the option pcsc-shared. This allows GnuPG VS-Desktop and the other software to access the same card.

This Registry setting is read by scdaemon.conf and implemented using the option pcsc-shared. Only the RSCS version the default is set to enabled if the Registry entry does not exist.

pcsc-shared[user]

Use shared mode to access the card via PC/SC. This is a somewhat dangerous option because scdaemon assumes exclusivbe access to the card and for example caches certain information from the card. Use this option only if you know what you are doing.

DisableSCD

Any value interpreted as non-zero (e.g. "1") entirely disables smart card support. [since 3.1.20.7]

This Registry setting is read by gpg-agent.conf and implemented using the option disable-scdaemon.

disable-scdaemon[user]

Do not make use of the scdaemon component. This option has the effect of disabling the ability to do smart card operations. Note, that enabling this option at runtime does not kill an already started scdaemon.

Option[user]: This option can be customized by the user in the standard configuration of GnuPG VS-Desktop.

Unless otherwise noted, these web pages are: Copyright 2024 g10 Code GmbH. Verbatim copying and distribution is permitted in any medium, provided this notice is preserved. See the Legal Notice & Privacy Policy for details. This page was last changed on 2023-08-17.