7.4.9 Key Listing Mode

Function: gpgme_error_t gpgme_set_keylist_mode (gpgme_ctx_t ctx, gpgme_keylist_mode_t mode)

The function gpgme_set_keylist_mode changes the default behaviour of the key listing functions. The value in mode is a bitwise-or combination of one or multiple of the following bit values:

GPGME_KEYLIST_MODE_LOCAL

The GPGME_KEYLIST_MODE_LOCAL symbol specifies that the local keyring should be searched for keys in the keylisting operation. This is the default.

Using only this option results in a --list-keys.

GPGME_KEYLIST_MODE_EXTERN

The GPGME_KEYLIST_MODE_EXTERN symbol specifies that an external source should be searched for keys in the keylisting operation. The type of external source is dependent on the crypto engine used and whether it is combined with GPGME_KEYLIST_MODE_LOCAL. For example, it can be a remote keyserver or LDAP certificate server.

Using only this option results in a --search-keys for GPGME_PROTOCOL_OpenPGP and something similar to --list-external-keys for GPGME_PROTOCOL_CMS.

GPGME_KEYLIST_MODE_LOCATE

This is a shortcut for the combination of GPGME_KEYLIST_MODE_LOCAL and GPGME_KEYLIST_MODE_EXTERN, which results in a --locate-keys for GPGME_PROTOCOL_OpenPGP.

GPGME_KEYLIST_MODE_SIGS

The GPGME_KEYLIST_MODE_SIGS symbol specifies that the key signatures should be included in the listed keys.

GPGME_KEYLIST_MODE_SIG_NOTATIONS

SINCE: 1.1.1

The GPGME_KEYLIST_MODE_SIG_NOTATIONS symbol specifies that the signature notations on key signatures should be included in the listed keys. This only works if GPGME_KEYLIST_MODE_SIGS is also enabled.

GPGME_KEYLIST_MODE_WITH_TOFU

SINCE: 1.7.0

The GPGME_KEYLIST_MODE_WITH_TOFU symbol specifies that information pertaining to the TOFU trust model should be included in the listed keys.

GPGME_KEYLIST_MODE_WITH_KEYGRIP

SINCE: 1.14.0

The GPGME_KEYLIST_MODE_WITH_KEYRIP symbol specifies that the keygrip is always included in the listing. The default depends on the version of the backend and the used protocol.

GPGME_KEYLIST_MODE_WITH_SECRET

SINCE: 1.5.1

The GPGME_KEYLIST_MODE_WITH_SECRET returns information about the presence of a corresponding secret key in a public key listing. A public key listing with this mode is slower than a standard listing but can be used instead of a second run to list the secret keys. This is only supported for GnuPG versions >= 2.1. Note that using this option also makes sure that the keygrip is available in the output.

GPGME_KEYLIST_MODE_EPHEMERAL

SINCE: 1.2.0

The GPGME_KEYLIST_MODE_EPHEMERAL symbol specifies that keys flagged as ephemeral are included in the listing.

GPGME_KEYLIST_MODE_VALIDATE

SINCE: 0.4.5

The GPGME_KEYLIST_MODE_VALIDATE symbol specifies that the backend should do key or certificate validation and not just get the validity information from an internal cache. This might be an expensive operation and is in general not useful. Currently only implemented for the S/MIME backend and ignored for other backends.

GPGME_KEYLIST_MODE_FORCE_EXTERN

SINCE: 1.18.0

The GPGME_KEYLIST_MODE_FORCE_EXTERN symbol specifies that only external sources should be searched for keys in the keylisting operation. If used in combination with GPGME_KEYLIST_MODE_LOCATE, the keylisting results in a --locate-external-keys for GPGME_PROTOCOL_OpenPGP. The combination with GPGME_KEYLIST_MODE_LOCAL, but without GPGME_KEYLIST_MODE_EXTERN is not allowed. Currently only implemented for the OpenPGP backend and ignored for other backends.

GPGME_KEYLIST_MODE_LOCATE_EXTERNAL

SINCE: 1.18.0

This is a shortcut for the combination of GPGME_KEYLIST_MODE_LOCATE and GPGME_KEYLIST_MODE_FORCE_EXTERN, which results in a --locate-external-keys for GPGME_PROTOCOL_OpenPGP.

At least one of GPGME_KEYLIST_MODE_LOCAL and GPGME_KEYLIST_MODE_EXTERN must be specified. For future binary compatibility, you should get the current mode with gpgme_get_keylist_mode and modify it by setting or clearing the appropriate bits, and then using that calculated value in the gpgme_set_keylisting_mode operation. This will leave all other bits in the mode value intact (in particular those that are not used in the current version of the library).

The function returns the error code GPG_ERR_NO_ERROR if the mode could be set correctly, and GPG_ERR_INV_VALUE if ctx is not a valid pointer or mode is not a valid mode.

Function: gpgme_keylist_mode_t gpgme_get_keylist_mode (gpgme_ctx_t ctx)

The function gpgme_get_keylist_mode returns the current key listing mode of the context ctx. This value can then be modified and used in a subsequent gpgme_set_keylist_mode operation to only affect the desired bits (and leave all others intact).

The function returns 0 if ctx is not a valid pointer, and the current mode otherwise. Note that 0 is not a valid mode value.