Next: Progress Meter Callback, Previous: Key Listing Mode, Up: Context Attributes [Contents][Index]
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.
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.
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.
Next: Progress Meter Callback, Previous: Key Listing Mode, Up: Context Attributes [Contents][Index]