7.4.13 Context Flags

Function: gpgme_error_t gpgme_set_ctx_flag (gpgme_ctx_t ctx, const char *name, const char *value)

SINCE: 1.7.0

Some minor properties of the context can be controlled with flags set by this function. The properties are identified by the following values for name:

"redraw"

This flag is normally not changed by the caller because GPGME sets and clears it automatically: The flag is cleared before an operation and set if an operation noticed that the engine has launched a Pinentry. A Curses based application may use this information to redraw the screen; for example:

    err = gpgme_op_keylist_start (ctx, "[email protected]", 0);
    while (!err)
      {
        err = gpgme_op_keylist_next (ctx, &key);
        if (err)
          break;
        show_key (key);
        gpgme_key_release (key);
      }
    if ((s = gpgme_get_ctx_flag (ctx, "redraw")) && *s)
      redraw_screen ();
    gpgme_release (ctx);

"full-status"

Using a value of "1" the status callback set by gpgme_set_status_cb returns all status lines with the exception of PROGRESS lines. With the default of "0" the status callback is only called in certain situations.

"raw-description"

Setting the value to "1" returns human readable strings in a raw format. For example the non breaking space characters ("~") will not be removed from the description field of the gpgme_tofu_info_t object.

"export-session-key"

Using a value of "1" specifies that the context should try to export the symmetric session key when decrypting data. By default, or when using an empty string or "0" for value, session keys are not exported.

"override-session-key"

The string given in value is passed to the GnuPG engine to override the session key for decryption. The format of that session key is specific to GnuPG and can be retrieved during a decrypt operation when the context flag "export-session-key" is enabled. Please be aware that using this feature with GnuPG < 2.1.16 will leak the session key on many platforms via ps(1).

"auto-key-retrieve"

Setting the value to "1" asks the backend to automatically retrieve a key for signature verification if possible. 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.

"auto-key-import"

Setting the value to "1" forces the GPG backend to automatically import a missing key for signature verification from the signature.

"include-key-block"

Setting the value to "1" forces the GPG backend to embed the signing key as well as an encryption subkey into the the signature.

"request-origin"

The string given in value is passed to the GnuPG engines to request restrictions based on the origin of the request. Valid values are documented in the GnuPG manual and the gpg man page under the option --request-origin. Requires at least GnuPG 2.2.6 to have an effect.

"no-symkey-cache"

For OpenPGP disable the passphrase cache used for symmetrical en- and decryption. This cache is based on the message specific salt value. Requires at least GnuPG 2.2.7 to have an effect.

"ignore-mdc-error"

This flag passes the option --ignore-mdc-error to gpg. This can be used to force decryption of a message which failed due to a missing integrity check. This flag must be used with great caution and only if it is a known non-corrupted old message and the decryption result of the former try had the decryption result flag legacy_cipher_nomdc set. For failsafe reasons this flag is reset after each operation.

"auto-key-locate"

The string given in value is passed to gpg. This can be used to change the behavior of a GPGME_KEYLIST_MODE_LOCATE keylisting. Valid values are documented in the GnuPG manual and the gpg man page under the option --auto-key-locate. Requires at least GnuPG 2.1.18.

Note: Keys retrieved through auto-key-locate are automatically imported in the keyring.

trust-model

SINCE: 1.11.2

Change the trust-model for all GnuPG engine operations. An empty string sets the trust-model back to the users default. If the trust-model is not supported by GnuPG the behavior is undefined and will likely cause all operations to fail. Example: "tofu+pgp".

This options should be used carefully with a strict version requirement. In some versions of GnuPG setting the trust-model changes the default trust-model for future operations. A change in the trust-model also can have unintended side effects, like rebuilding the trust-db.

"extended-edit"

This flag passes the option --expert to gpg key edit. This can be used to get additional callbacks in gpgme_op_edit.

"cert-expire"

SINCE: 1.15.2 The string given in value is passed to the GnuPG engine to set the expiration time to use for key signature expiration. Valid values are documented in the GnuPG manual and the gpg man page under the option --default-cert-expire.

"key-origin"

SINCE: 1.16.1 The string given in value is passed to the GnuPG engine to set the origin of imported keys. Valid values are documented in the GnuPG manual and the gpg man page under the option --key-origin.

"import-filter"

SINCE: 1.16.1 The string given in value is passed to the GnuPG engine to use as filter when importing keys. Valid values are documented in the GnuPG manual and the gpg man page under the option --import-filter.

This function returns 0 on success.

Function: const char * gpgme_get_ctx_flag (gpgme_ctx_t ctx, const char *name)

SINCE: 1.8.0

The value of flags settable by gpgme_set_ctx_flag can be retrieved by this function. If name is unknown the function returns NULL. For boolean flags an empty string is returned for False and the string "1" is returned for True; either atoi(3) or a test for an empty string can be used to get the boolean value.