7.4.10 Passphrase Callback

Data type: gpgme_error_t (*gpgme_passphrase_cb_t)(void *hook, const char *uid_hint, const char *passphrase_info, int prev_was_bad, int fd)

The gpgme_passphrase_cb_t type is the type of functions usable as passphrase callback function.

The argument uid_hint might contain a string that gives an indication for which user ID the passphrase is required. If this is not available, or not applicable (in the case of symmetric encryption, for example), uid_hint will be NULL.

The argument passphrase_info, if not NULL, will give further information about the context in which the passphrase is required. This information is engine and operation specific.

If this is the repeated attempt to get the passphrase, because previous attempts failed, then prev_was_bad is 1, otherwise it will be 0.

The user must write the passphrase, followed by a newline character, to the file descriptor fd. The function gpgme_io_writen should be used for the write operation. Note that if the user returns 0 to indicate success, the user must at least write a newline character before returning from the callback.

If an error occurs, return the corresponding gpgme_error_t value. You can use the error code GPG_ERR_CANCELED to abort the operation. Otherwise, return 0.

Note: The passphrase_cb only works with GnuPG 1.x and 2.1.x and not with the 2.0.x series. See gpgme_set_pinentry_mode for more details on 2.1.x usage.

Function: void gpgme_set_passphrase_cb (gpgme_ctx_t ctx, gpgme_passphrase_cb_t passfunc, void *hook_value)

The function gpgme_set_passphrase_cb sets the function that is used when a passphrase needs to be provided by the user to passfunc. The function passfunc needs to implemented by the user, and whenever it is called, it is called with its first argument being hook_value. By default, no passphrase callback function is set.

Not all crypto engines require this callback to retrieve the passphrase. It is better if the engine retrieves the passphrase from a trusted agent (a daemon process), rather than having each user to implement their own passphrase query. Some engines do not even support an external passphrase callback at all, in this case the error code GPG_ERR_NOT_SUPPORTED is returned.

For GnuPG >= 2.1 the pinentry mode has to be set to GPGME_PINENTRY_MODE_LOOPBACK to enable the passphrase callback. See gpgme_set_pinentry_mode.

The user can disable the use of a passphrase callback function by calling gpgme_set_passphrase_cb with passfunc being NULL.

Function: void gpgme_get_passphrase_cb (gpgme_ctx_t ctx, gpgme_passphrase_cb_t *passfunc, void **hook_value)

The function gpgme_get_passphrase_cb returns the function that is used when a passphrase needs to be provided by the user in *passfunc, and the first argument for this function in *hook_value. If no passphrase callback is set, or ctx is not a valid pointer, NULL is returned in both variables.

passfunc or hook_value can be NULL. In this case, the corresponding value will not be returned.