GpgFrontend/gpgme
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Doc: Document pinentry mode

Browse Source 
* doc/gpgme.texi (Passphrase Callback): Document as context
attribute.
(gpgme_set_passphrase_cb): Note that this requires LOOPBACK mode
with GnuPG 2.1.
This commit is contained in:
Andre Heinecke 2016-07-04 11:23:12 +02:00
parent 8fa9b5696c
commit 329ab93f7e
1 changed files with 56 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
doc/gpgme.texi
View File

@ -2311,6 +2311,7 @@ started. In fact, these references are accessed through the
* ASCII Armor:: Requesting @acronym{ASCII} armored output.
* Text Mode:: Choosing canonical text mode.
* Offline Mode:: Choosing offline mode.
* Pinentry Mode:: Choosing the pinentry mode.
* Included Certificates:: Including a number of certificates.
* Key Listing Mode:: Selecting key listing mode.
* Passphrase Callback:: Getting the passphrase from the user.
@ -2471,6 +2472,57 @@ valid pointer.
@end deftypefun
@node Pinentry Mode
@subsection Pinentry Mode
@cindex context, pinentry mode
@cindex pinentry mode
@deftypefun gpgme_error_t gpgme_set_pinentry_mode (@w{gpgme_ctx_t @var{ctx}},
@w{gpgme_pinentry_mode_t @var{mode}})
The function @code{gpgme_set_pinentry_mode} specifies the pinentry mode
to be used.
For GnuPG >= 2.1 this option is required to be set to
@code{GPGME_PINENTRY_MODE_LOOPBACK} to enable the passphrase callback
mechanism in GPGME through @code{gpgme_set_passphrase_cb}.
@end deftypefun
@deftypefun gpgme_pinentry_mode_t gpgme_get_pinentry_mode (@w{gpgme_ctx_t @var{ctx}})
The function @code{gpgme_get_pinenty_mode} returns the
mode set for the context.
@end deftypefun
@deftp {Data type} {enum gpgme_pinentry_mode_t}
@tindex gpgme_pinentry_mode_t
The @code{gpgme_minentry_mode_t} type specifies the set of possible pinentry
modes that are supported by @acronym{GPGME} if GnuPG >= 2.1 is used.
The following modes are supported:
@table @code
@item GPGME_PINENTRY_MODE_DEFAULT
Use the default of the agent, which is ask.
@item GPGME_PINENTRY_MODE_ASK
Force the use of the Pinentry.
@item GPGME_PINENTRY_MODE_CANCEL
Emulate use of Pinentry's cancel button.
@item GPGME_PINENTRY_MODE_ERROR
Return a Pinentry error @code{No Pinentry}.
@item GPGME_PINENTRY_MODE_LOOPBACK
Redirect Pinentry queries to the caller.
This enables the use of @code{gpgme_set_passphrase_cb} whis pinentry
queries redirected to gpgme.
Note: This mode requires @code{allow-loopback-pinentry} to be enabled
in the @file{gpg-agent.conf} or an agent started with that option.
@end table
@end deftp
@node Included Certificates
@subsection Included Certificates
@cindex certificates, included
@ -2639,6 +2691,10 @@ implement their own passphrase query. Some engines do not even
support an external passphrase callback at all, in this case the error
code @code{GPG_ERR_NOT_SUPPORTED} is returned.
For GnuPG >= 2.1 the pinentry mode has to be set to
@code{GPGME_PINENTRY_MODE_LOOPBACK} to enable the passphrase callback.
See @code{gpgme_set_pinentry_mode}.
The user can disable the use of a passphrase callback function by
calling @code{gpgme_set_passphrase_cb} with @var{passfunc} being
@code{NULL}.