File: gpgme.info,  Node: Passphrase Callback,  Next: Progress Meter Callback,  Prev: Key Listing Mode,  Up: Context Attributes

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.