[Pkg-gnupg-commit] [gpgme] 196/412: Doc: Document pinentry mode

[Daniel Kahn Gillmor]

This is an automated email from the git hooks/post-receive script.

dkg pushed a commit to branch master
in repository gpgme.

commit 329ab93f7ed862d7f4c0501fca5355936a74ac52
Author: Andre Heinecke <aheinecke at intevation.de>
Date:   Mon Jul 4 11:23:12 2016 +0200

    Doc: Document pinentry mode
    
    * doc/gpgme.texi (Passphrase Callback): Document as context
    attribute.
    (gpgme_set_passphrase_cb): Note that this requires LOOPBACK mode
    with GnuPG 2.1.
---
 doc/gpgme.texi | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/doc/gpgme.texi b/doc/gpgme.texi
index 8d666c3..87322b0 100644
--- a/doc/gpgme.texi
+++ b/doc/gpgme.texi
@@ -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
 
 
+ at node Pinentry Mode
+ at subsection Pinentry Mode
+ at cindex context, pinentry mode
+ at cindex pinentry mode
+
+ at deftypefun gpgme_error_t gpgme_set_pinentry_mode (@w{gpgme_ctx_t @var{ctx}},
+ at 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
+ at code{GPGME_PINENTRY_MODE_LOOPBACK} to enable the passphrase callback
+mechanism in GPGME through @code{gpgme_set_passphrase_cb}.
+ at end deftypefun
+
+ at 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.
+ at end deftypefun
+
+ at deftp {Data type} {enum gpgme_pinentry_mode_t}
+ at 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:
+
+ at table @code
+ at item GPGME_PINENTRY_MODE_DEFAULT
+Use the default of the agent, which is ask.
+
+ at item GPGME_PINENTRY_MODE_ASK
+Force the use of the Pinentry.
+
+ at item GPGME_PINENTRY_MODE_CANCEL
+Emulate use of Pinentry's cancel button.
+
+ at item GPGME_PINENTRY_MODE_ERROR
+Return a Pinentry error @code{No Pinentry}.
+
+ at 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.
+
+ at end table
+ at 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
+ at 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}.

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-gnupg/gpgme.git