core: Map GPGME_STATUS_EOF to the empty string.
[gpgme.git] / doc / gpgme.texi
index c2bb309..18fb6d5 100644 (file)
@@ -1,6 +1,7 @@
-\input texinfo                   @c -*- mode: texinfo; coding: latin-1; -*-
-@documentencoding ISO-8859-1
+\input texinfo                   @c -*- mode: texinfo; coding: utf-8; -*-
+@documentencoding UTF-8
 @setfilename gpgme.info
+@include defs.inc
 @settitle The `GnuPG Made Easy' Reference Manual
 
 @dircategory GNU Libraries
@@ -13,8 +14,7 @@
 @syncodeindex pg fn
 
 @copying
-Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007,
-2008, 2010 g10 Code GmbH.
+Copyright @copyright{} 2002--2008, 2010, 2012--2016 g10 Code GmbH.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -30,8 +30,6 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 General Public License for more details.
 @end copying
 
-@include version.texi
-
 @c Macros used by the description of the UI server protocol
 @macro clnt
   @sc{c:} @c
@@ -41,7 +39,7 @@ General Public License for more details.
 @end macro
 
 
-@c 
+@c
 @c  T I T L E  P A G E
 @c
 @ifinfo
@@ -72,7 +70,7 @@ This is Edition @value{EDITION}, last updated @value{UPDATED}, of
 @center for version @value{VERSION}
 @page
 @vskip 0pt plus 1filll
-Published by g10 Code GmbH@* Hüttenstr. 61@* 40699 Erkrath, Germany
+Published by The GnuPG Project@* c/o g10 Code GmbH@* Hüttenstr. 61@* 40699 Erkrath, Germany
 
 @insertcopying
 @end titlepage
@@ -101,6 +99,8 @@ This is Edition @value{EDITION}, last updated @value{UPDATED}, of
 Appendices
 
 * UI Server Protocol::            The GnuPG UI Server Protocol.
+* Debugging::                     How to solve problems.
+* Deprecated Functions::          Documentation of deprecated functions.
 
 * Library Copying::               The GNU Lesser General Public License says
                                   how you can copy and share `GnuPG Made Easy'.
@@ -112,7 +112,6 @@ Indices
 * Concept Index::                 Index of concepts and programs.
 * Function and Data Index::       Index of functions, variables and data types.
 
-
 @detailmenu
  --- The Detailed Node Listing ---
 
@@ -153,7 +152,7 @@ Error Handling
 * Error Sources::                 A list of important error sources.
 * Error Strings::                 How to get a descriptive string from a value.
 
-Exchanging Data 
+Exchanging Data
 
 * Creating Data Buffers::         Creating new data buffers.
 * Destroying Data Buffers::       Releasing data buffers.
@@ -169,6 +168,7 @@ Manipulating Data Buffers
 
 * Data Buffer I/O Operations::    I/O operations on data buffers.
 * Data Buffer Meta-Data::         Meta-data manipulation of data buffers.
+* Data Buffer Convenience::       Convenience function for data buffers.
 
 Contexts
 
@@ -179,6 +179,7 @@ Contexts
 * Key Management::                Managing keys with @acronym{GPGME}.
 * Trust Item Management::         Managing trust items with @acronym{GPGME}.
 * Crypto Operations::             Using a context for cryptography.
+* Miscellaneous::                 Miscellaneous operations.
 * Run Control::                   Controlling how operations are run.
 
 Context Attributes
@@ -187,28 +188,32 @@ Context Attributes
 * Crypto Engine::                 Configuring the crypto engine.
 * ASCII Armor::                   Requesting @acronym{ASCII} armored output.
 * Text Mode::                     Choosing canonical text mode.
+* Offline Mode::                  Choosing offline mode.
 * Included Certificates::         Including a number of certificates.
 * Key Listing Mode::              Selecting key listing mode.
 * Passphrase Callback::           Getting the passphrase from the user.
 * Progress Meter Callback::       Being informed about the progress.
+* Status Message Callback::       Status messages received from gpg.
 * Locale::                        Setting the locale of a context.
 
 Key Management
 
+* Key objects::                   Description of the key structures.
 * Listing Keys::                  Browsing the list of available keys.
 * Information About Keys::        Requesting detailed information about keys.
-* Key Signatures::                Listing the signatures on a key.
 * Manipulating Keys::             Operations on keys.
 * Generating Keys::               Creating new key pairs.
+* Signing Keys::                  Adding key signatures to public keys.
 * Exporting Keys::                Retrieving key data from the key ring.
 * Importing Keys::                Adding keys to the key ring.
 * Deleting Keys::                 Removing keys from the key ring.
+* Changing Passphrases::          Change the passphrase of a key.
+* Changing TOFU Data::            Changing data pertaining to TOFU.
 * Advanced Key Editing::          Advanced key edit operation.
 
 Trust Item Management
 
 * Listing Trust Items::           Browsing the list of available trust items.
-* Information About Trust Items:: Requesting information about trust items.
 * Manipulating Trust Items::      Operations on trust items.
 
 Crypto Operations
@@ -229,6 +234,10 @@ Encrypt
 
 * Encrypting a Plaintext::        How to encrypt a plaintext.
 
+Miscellaneous
+
+* Running other Programs::        Running other Programs
+
 Run Control
 
 * Waiting For Completion::        Waiting until an operation is completed.
@@ -384,8 +393,8 @@ to @acronym{GPGME} take the form @code{_gpgme_*} and @code{_GPGME_*}.
 
 Because @acronym{GPGME} makes use of the GPG Error library, using
 @acronym{GPGME} will also use the @code{GPG_ERR_*} name space
-directly, and the @code{gpg_err*} and @code{gpg_str*} name space
-indirectly.
+directly, and the @code{gpg_err*}, @code{gpg_str*}, and @code{gpgrt_*}
+name space indirectly.
 
 
 @node Building the Source
@@ -442,6 +451,19 @@ any other option to select the thread package you want to link with.
 Supported thread packages are @option{--thread=pth} and
 @option{--thread=pthread}.
 
+If you need to detect the installed language bindings you can use list
+them using:
+
+@example
+gpgme-config --print-lang
+@end example
+
+or test for the availability using
+
+@example
+gpgme-config --have-lang=python && echo 'Bindings for Pythons available'
+@end example
+
 
 @node Largefile Support (LFS)
 @section Largefile Support (LFS)
@@ -492,18 +514,42 @@ support by default and just use that.  The compatibility modes (small
 file sizes or dual mode) can be considered an historic artefact, only
 useful to allow for a transitional period.
 
-@acronym{GPGME} is compiled using largefile support by default.  This
-means that your application must do the same, at least as far as it is
-relevant for using the @file{gpgme.h} header file.  All types in this
-header files refer to their largefile counterparts, if they are
-different from any default types on the system.
-
-You can enable largefile support, if it is different from the default
-on the system the application is compiled on, by using the Autoconf
-macro @code{AC_SYS_LARGEFILE}.  If you do this, then you don't need to
-worry about anything else: It will just work.  In this case you might
-also want to use @code{AC_FUNC_FSEEKO} to take advantage of some new
-interfaces, and @code{AC_TYPE_OFF_T} (just in case).
+On POSIX platforms @acronym{GPGME} is compiled using largefile support
+by default.  This means that your application must do the same, at
+least as far as it is relevant for using the @file{gpgme.h} header
+file.  All types in this header files refer to their largefile
+counterparts, if they are different from any default types on the
+system.
+
+On 32 and 64 bit Windows platforms @code{off_t} is declared as 32 bit
+signed integer.  There is no specific support for LFS in the C
+library.  The recommendation from Microsoft is to use the native
+interface (@code{CreateFile} et al.) for large files.  Released binary
+versions of @acronym{GPGME} (libgpgme-11.dll) have always been build
+with a 32 bit @code{off_t}.  To avoid an ABI break we stick to this
+convention for 32 bit Windows by using @code{long} there.
+@acronym{GPGME} versions for 64 bit Windows have never been released
+and thus we are able to use @code{int64_t} instead of @code{off_t}
+there.  For easier migration the typedef @code{gpgme_off_t} has been
+defined.  The reason we cannot use @code{off_t} directly is that some
+toolchains (e.g. mingw64) introduce a POSIX compatible hack for
+@code{off_t}.  Some widely used toolkits make use of this hack and in
+turn @acronym{GPGME} would need to use it also.  However, this would
+introduce an ABI break and existing software making use of libgpgme
+might suffer from a severe break.  Thus with version 1.4.2 we
+redefined all functions using @code{off_t} to use @code{gpgme_off_t}
+which is defined as explained above.  This way we keep the ABI well
+defined and independent of any toolchain hacks.  The bottom line is
+that LFS support in @acronym{GPGME} is only available on 64 bit
+versions of Windows.
+
+On POSIX platforms you can enable largefile support, if it is
+different from the default on the system the application is compiled
+on, by using the Autoconf macro @code{AC_SYS_LARGEFILE}.  If you do
+this, then you don't need to worry about anything else: It will just
+work.  In this case you might also want to use @code{AC_FUNC_FSEEKO}
+to take advantage of some new interfaces, and @code{AC_TYPE_OFF_T}
+(just in case).
 
 If you do not use Autoconf, you can define the preprocessor symbol
 @code{_FILE_OFFSET_BITS} to 64 @emph{before} including any header
@@ -544,7 +590,10 @@ given.
 Additionally, the function defines @code{GPGME_CFLAGS} to the flags
 needed for compilation of the program to find the @file{gpgme.h}
 header file, and @code{GPGME_LIBS} to the linker flags needed to link
-the program to the @acronym{GPGME} library.
+the program to the @acronym{GPGME} library.  If the used helper script
+does not match the target type you are building for a warning is
+printed and the string @code{libgcrypt} is appended to the variable
+@code{gpg_config_script_warn}.
 
 @code{AM_PATH_GPGME_PTH} checks for the version of @acronym{GPGME}
 that can be used with GNU Pth, and defines @code{GPGME_PTH_CFLAGS} and
@@ -553,6 +602,16 @@ that can be used with GNU Pth, and defines @code{GPGME_PTH_CFLAGS} and
 @code{AM_PATH_GPGME_PTHREAD} checks for the version of @acronym{GPGME}
 that can be used with the native pthread implementation, and defines
 @code{GPGME_PTHREAD_CFLAGS} and @code{GPGME_PTHREAD_LIBS}.
+
+This macro searches for @command{gpgme-config} along the PATH.  If
+you are cross-compiling, it is useful to set the environment variable
+@code{SYSROOT} to the top directory of your target.  The macro will
+then first look for the helper program in the @file{bin} directory
+below that top directory.  An absolute directory name must be used for
+@code{SYSROOT}.  Finally, if the configure command line option
+@code{--with-gpgme-prefix} is used, only its value is used for the top
+directory below which the helper script is expected.
+
 @end defmac
 
 You can use the defined Autoconf variables like this in your
@@ -616,6 +675,71 @@ does not return a detailed error code).
 @end deftypefun
 
 
+@deftypefun {int} gpgme_set_global_flag  @
+            (@w{const char *@var{name}}, @
+            @w{const char *@var{value}})
+
+On some systems it is not easy to set environment variables and thus
+hard to use @acronym{GPGME}'s internal trace facility for debugging.
+This function has been introduced as an alternative way to enable
+debugging and for a couple of other rarely used tweaks.  It is
+important to assure that only one thread accesses @acronym{GPGME}
+functions between a call to this function and after the return from
+the call to @code{gpgme_check_version}.
+
+All currently supported features require that this function is called
+as early as possible --- even before @code{gpgme_check_version}.  The
+features are identified by the following values for @var{name}:
+
+@table @code
+@item debug
+To enable debugging use the string ``debug'' for @var{name} and
+@var{value} identical to the value used with the environment variable
+@code{GPGME_DEBUG}.
+
+@item disable-gpgconf
+Using this feature with any @var{value} disables the detection of the
+gpgconf program and thus forces GPGME to fallback into the simple
+OpenPGP only mode.  It may be used to force the use of GnuPG-1 on
+systems which have both GPG versions installed.  Note that in general
+the use of @code{gpgme_set_engine_info} is a better way to select a
+specific engine version.
+
+@item gpgconf-name
+@itemx gpg-name
+Set the name of the gpgconf respective gpg binary.  The defaults are
+@code{GNU/GnuPG/gpgconf} and @code{GNU/GnuPG/gpg}.  Under Unix the
+leading directory part is ignored.  Under Windows the leading
+directory part is used as the default installation directory; the
+@code{.exe} suffix is added by GPGME.  Use forward slashed even under
+Windows.
+
+@item require-gnupg
+Set the mimimum version of the required GnuPG engine.  If that version
+is not met, GPGME fails early instead of trying to use the existant
+version.  The given version must be a string with major, minor, and
+micro number.  Example: "2.1.0".
+
+@item w32-inst-dir
+On Windows GPGME needs to know its installation directory to find its
+spawn helper.  This is in general no problem because a DLL has this
+information.  Some applications however link statically to GPGME and
+thus GPGME can only figure out the installation directory of this
+application which may be wrong in certain cases.  By supplying an
+installation directory as value to this flag, GPGME will assume that
+that directory is the installation directory.  This flag has no effect
+on non-Windows platforms.
+
+@end table
+
+This function returns @code{0} on success.  In contrast to other
+functions the non-zero return value on failure does not convey any
+error code.  For setting ``debug'' the only possible error cause is an
+out of memory condition; which would exhibit itself later anyway.
+Thus the return value may be ignored.
+@end deftypefun
+
+
 After initializing @acronym{GPGME}, you should set the locale
 information to the locale required for your output terminal.  This
 locale information is needed for example for the curses and Gtk
@@ -767,15 +891,21 @@ This specifies the OpenPGP protocol.
 @item GPGME_PROTOCOL_CMS
 This specifies the Cryptographic Message Syntax.
 
-@item GPGME_PROTOCOL_ASSUAN
+@item GPGME_PROTOCOL_GPGCONF
 Under development.  Please ask on @email{gnupg-devel@@gnupg.org} for help.
 
+@item GPGME_PROTOCOL_ASSUAN
+This specifies the raw Assuan protocol.
+
 @item GPGME_PROTOCOL_G13
 Under development.  Please ask on @email{gnupg-devel@@gnupg.org} for help.
 
 @item GPGME_PROTOCOL_UISERVER
 Under development.  Please ask on @email{gnupg-devel@@gnupg.org} for help.
 
+@item GPGME_PROTOCOL_SPAWN
+Special protocol for use with @code{gpgme_op_spawn}.
+
 @item GPGME_PROTOCOL_UNKNOWN
 Reserved for future extension.  You may use this to indicate that the
 used protocol is not known to the application.  Currently,
@@ -797,6 +927,7 @@ allocated string describing the protocol @var{protocol}, or
 * Engine Configuration::          Changing the engine configuration.
 * OpenPGP::                       Support for the OpenPGP protocol.
 * Cryptographic Message Syntax::  Support for the CMS.
+* Assuan::                        Support for the raw Assuan protocol.
 @end menu
 
 
@@ -804,6 +935,66 @@ allocated string describing the protocol @var{protocol}, or
 @section Engine Version Check
 @cindex version check, of the engines
 
+@deftypefun @w{const char *} gpgme_get_dirinfo (@w{cons char *@var{what}})
+The function @code{gpgme_get_dirinfo} returns a statically allocated
+string with the value associated to @var{what}.  The returned values
+are the defaults and won't change even after
+@code{gpgme_set_engine_info} has been used to configure a different
+engine.  @code{NULL} is returned if no value is available.  Commonly
+supported values for @var{what} are:
+
+@table @code
+@item homedir
+Return the default home directory.
+
+@item sysconfdir
+Return the name of the system configuration directory
+
+@item bindir
+Return the name of the directory with GnuPG program files.
+
+@item libdir
+Return the name of the directory with GnuPG related library files.
+
+@item libexecdir
+Return the name of the directory with GnuPG helper program files.
+
+@item datadir
+Return the name of the directory with GnuPG shared data.
+
+@item localedir
+Return the name of the directory with GnuPG locale data.
+
+@item agent-socket
+Return the name of the socket to connect to the gpg-agent.
+
+@item agent-ssh-socket
+Return the name of the socket to connect to the ssh-agent component of
+gpg-agent.
+
+@item dirmngr-socket
+Return the name of the socket to connect to the dirmngr.
+
+@item uiserver-socket
+Return the name of the socket to connect to the user interface server.
+
+@item gpgconf-name
+Return the file name of the engine configuration tool.
+
+@item gpg-name
+Return the file name of the OpenPGP engine.
+
+@item gpgsm-name
+Return the file name of the CMS engine.
+
+@item g13-name
+Return the name of the file container encryption engine.
+
+@end table
+
+@end deftypefun
+
+
 @deftypefun gpgme_error_t gpgme_engine_check_version (@w{gpgme_protocol_t @var{protocol}})
 The function @code{gpgme_engine_check_version} verifies that the
 engine implementing the protocol @var{PROTOCOL} is installed in the
@@ -842,7 +1033,8 @@ reserved for future use, so always check before you use it.
 @item const char *home_dir
 This is a string holding the directory name of the crypto engine's
 configuration directory.  If it is @code{NULL}, then the default
-directory is used.
+directory is used.  See @code{gpgme_get_dirinfo} on how to get the
+default directory.
 
 @item const char *version
 This is a string containing the version number of the crypto engine.
@@ -965,6 +1157,20 @@ GnuPG.
 The @acronym{CMS} protocol is specified by @code{GPGME_PROTOCOL_CMS}.
 
 
+@node Assuan
+@section Assuan
+@cindex ASSUAN
+@cindex protocol, ASSUAN
+@cindex engine, ASSUAN
+
+Assuan is the RPC library used by the various @acronym{GnuPG}
+components.  The Assuan protocol allows one to talk to arbitrary
+Assuan servers using @acronym{GPGME}.  @xref{Using the Assuan
+protocol}.
+
+The ASSUAN protocol is specified by @code{GPGME_PROTOCOL_ASSUAN}.
+
+
 @node Algorithms
 @chapter Algorithms
 @cindex algorithms
@@ -1016,16 +1222,19 @@ This value indicates ElGamal.
 @item GPGME_PK_ELG_E
 This value also indicates ElGamal and is used specifically in GnuPG.
 
-@item GPGME_PK_ELG_E
-This value also indicates ElGamal and is used specifically in GnuPG.
+@item GPGME_PK_ECC
+This value is a generic indicator for ellipic curve algorithms.
 
 @item GPGME_PK_ECDSA
 This value indicates ECDSA, the Elliptic Curve Digital Signature
-Algorithm as defined by FIPS 186-2.
+Algorithm as defined by FIPS 186-2 and RFC-6637.
 
 @item GPGME_PK_ECDH
-This value indicates ECDH, the Eliptic Curve Diffie-Hellmann encryption
-algorithm as defined by the ECC in OpenPGP draft.
+This value indicates ECDH, the Eliptic Curve Diffie-Hellmann
+encryption algorithm as defined by RFC-6637.
+
+@item GPGME_PK_EDDSA
+This value indicates the EdDSA algorithm.
 
 @end table
 @end deftp
@@ -1040,6 +1249,14 @@ If @var{algo} is not a valid public key algorithm, @code{NULL} is
 returned.
 @end deftypefun
 
+@deftypefun {char *} gpgme_pubkey_algo_string (@w{gpgme_subkey_t @var{key}})
+The function @code{gpgme_pubkey_algo_string} is a convenience function
+to build and return an algorithm string in the same way GnuPG does
+(e.g. ``rsa2048'' or ``ed25519'').  The caller must free the result
+using @code{gpgme_free}.  On error (e.g. invalid argument or memory
+exhausted), the function returns NULL and sets @code{ERRNO}.
+@end deftypefun
+
 
 @node Hash Algorithms
 @section Hash Algorithms
@@ -1066,6 +1283,7 @@ that are supported by @acronym{GPGME}.  Possible values are:
 @item GPGME_MD_SHA256
 @item GPGME_MD_SHA384
 @item GPGME_MD_SHA512
+@item GPGME_MD_SHA224
 @item GPGME_MD_MD4
 @item GPGME_MD_CRC32
 @item GPGME_MD_CRC32_RFC1510
@@ -1513,6 +1731,20 @@ by using memory buffers or files rather than pipes or sockets.  This
 might be relevant, for example, if the external event loop mechanism
 is used.
 
+@deftp {Data type} {gpgme_off_t}
+On POSIX platforms the @code{gpgme_off_t} type is an alias for
+@code{off_t}; it may be used interchangeable.  On Windows platforms
+@code{gpgme_off_t} is defined as a long (i.e. 32 bit) for 32 bit
+Windows and as a 64 bit signed integer for 64 bit Windows.
+@end deftp
+
+@deftp {Data type} {gpgme_ssize_t}
+The @code{gpgme_ssize_t} type is an alias for @code{ssize_t}.  It has
+only been introduced to overcome portability problems pertaining to
+the declaration of @code{ssize_t} by different toolchains.
+@end deftp
+
+
 @menu
 * Creating Data Buffers::         Creating new data buffers.
 * Destroying Data Buffers::       Releasing data buffers.
@@ -1543,7 +1775,7 @@ Memory based data objects store all data in allocated memory.  This is
 convenient, but only practical for an amount of data that is a
 fraction of the available physical memory.  The data has to be copied
 from its source and to its destination, which can often be avoided by
-using one of the other data object 
+using one of the other data object
 
 @deftypefun gpgme_error_t gpgme_data_new (@w{gpgme_data_t *@var{dh}})
 The function @code{gpgme_data_new} creates a new @code{gpgme_data_t}
@@ -1750,33 +1982,6 @@ data object was successfully created, and @code{GPG_ERR_ENOMEM} if not
 enough memory is available.
 @end deftypefun
 
-The following interface is deprecated and only provided for backward
-compatibility.  Don't use it.  It will be removed in a future version
-of @acronym{GPGME}.
-
-@deftypefun gpgme_error_t gpgme_data_new_with_read_cb (@w{gpgme_data_t *@var{dh}}, @w{int (*@var{readfunc})} (@w{void *@var{hook}}, @w{char *@var{buffer}}, @w{size_t @var{count}}, @w{size_t *@var{nread}}), @w{void *@var{hook_value}})
-The function @code{gpgme_data_new_with_read_cb} creates a new
-@code{gpgme_data_t} object and uses the callback function @var{readfunc}
-to retrieve the data on demand.  As the callback function can supply
-the data in any way it wants, this is the most flexible data type
-@acronym{GPGME} provides.  However, it can not be used to write data.
-
-The callback function receives @var{hook_value} as its first argument
-whenever it is invoked.  It should return up to @var{count} bytes in
-@var{buffer}, and return the number of bytes actually read in
-@var{nread}.  It may return @code{0} in @var{nread} if no data is
-currently available.  To indicate @code{EOF} the function should
-return with an error code of @code{-1} and set @var{nread} to
-@code{0}.  The callback function may support to reset its internal
-read pointer if it is invoked with @var{buffer} and @var{nread} being
-@code{NULL} and @var{count} being @code{0}.
-
-The function returns the error code @code{GPG_ERR_NO_ERROR} if the
-data object was successfully created, @code{GPG_ERR_INV_VALUE} if
-@var{dh} or @var{readfunc} is not a valid pointer, and
-@code{GPG_ERR_ENOMEM} if not enough memory is available.
-@end deftypefun
-
 
 @node Destroying Data Buffers
 @section Destroying Data Buffers
@@ -1805,9 +2010,11 @@ case, the data object @var{dh} is destroyed.
 
 @deftypefun void gpgme_free (@w{void *@var{buffer}})
 The function @code{gpgme_free} releases the memory returned by
-@code{gpgme_data_release_and_get_mem}.  It should be used instead of
-the system libraries @code{free} function in case different allocators
-are used in a single program.
+@code{gpgme_data_release_and_get_mem} and
+@code{gpgme_pubkey_algo_string}.  It should be used instead of the
+system libraries @code{free} function in case different allocators are
+used by a program.  This is often the case if gpgme is used under
+Windows as a DLL.
 @end deftypefun
 
 
@@ -1822,6 +2029,7 @@ be used to manipulate both.
 @menu
 * Data Buffer I/O Operations::    I/O operations on data buffers.
 * Data Buffer Meta-Data::         Meta-data manipulation of data buffers.
+* Data Buffer Convenience::       Convenience function for data buffers.
 @end menu
 
 
@@ -1885,20 +2093,6 @@ read/write position.
 If the function fails, -1 is returned and @var{errno} is set.
 @end deftypefun
 
-The following function is deprecated and should not be used.  It will
-be removed in a future version of @acronym{GPGME}.
-
-@deftypefun gpgme_error_t gpgme_data_rewind (@w{gpgme_data_t @var{dh}})
-The function @code{gpgme_data_rewind} is equivalent to:
-
-@example
-  return (gpgme_data_seek (dh, 0, SEEK_SET) == -1)
-    ? gpgme_error_from_errno (errno) : 0;
-@end example
-@end deftypefun
-
-
-
 
 @node Data Buffer Meta-Data
 @subsection Data Buffer Meta-Data
@@ -1957,6 +2151,9 @@ scheme as used by @acronym{MIME} and other protocols.
 This specifies that the data is encoded in an armored form as used by
 OpenPGP and PEM.
 
+@item GPGME_DATA_ENCODING_MIME
+This specifies that the data is encoded as a MIME part.
+
 @item GPGME_DATA_ENCODING_URL
 The data is a list of linefeed delimited URLs.  This is only useful with
 @code{gpgme_op_import}.
@@ -1984,10 +2181,84 @@ The function @code{gpgme_data_set_encoding} changes the encoding of
 the data object with the handle @var{dh} to @var{enc}.
 @end deftypefun
 
+@deftypefun {gpgme_error_t} gpgme_data_set_flag  @
+            (@w{gpgme_data_t @var{dh}}, @
+            @w{const char *@var{name}}, @
+            @w{const char *@var{value}})
+
+Some minor properties of the data object can be controlled with flags
+set by this function.  The properties are identified by the following
+values for @var{name}:
+
+@table @code
+@item size-hint
+The value is a decimal number with the length gpgme shall assume for
+this data object.  This is useful if the data is provided by callbacks
+or via file descriptors but the applications knows the total size of
+the data.  If this is set the OpenPGP engine may use this to decide on
+buffer allocation strategies and to provide a total value for its
+progress information.
+
+@end table
+
+This function returns @code{0} on success.
+@end deftypefun
+
+
+@node Data Buffer Convenience
+@subsection Data Buffer Convenience Functions
+@cindex data buffer, convenience
+@cindex type of data
+@cindex identify
+
+@deftp {Data type} {enum gpgme_data_type_t}
+@tindex gpgme_data_type_t
+The @code{gpgme_data_type_t} type is used to return the detected type
+of the content of a data buffer.
+@end deftp
+
+@table @code
+@item GPGME_DATA_TYPE_INVALID
+This is returned by @code{gpgme_data_identify} if it was not possible
+to identify the data.  Reasons for this might be a non-seekable stream
+or a memory problem.  The value is 0.
+@item GPGME_DATA_TYPE_UNKNOWN
+The type of the data is not known.
+@item GPGME_DATA_TYPE_PGP_SIGNED
+The data is an OpenPGP signed message.  This may be a binary
+signature, a detached one or a cleartext signature.
+@item GPGME_DATA_TYPE_PGP_OTHER
+This is a generic OpenPGP message.  In most cases this will be
+encrypted data.
+@item GPGME_DATA_TYPE_PGP_KEY
+This is an OpenPGP key (private or public).
+@item GPGME_DATA_TYPE_CMS_SIGNED
+This is a CMS signed message.
+@item GPGME_DATA_TYPE_CMS_ENCRYPTED
+This is a CMS encrypted (enveloped data) message.
+@item GPGME_DATA_TYPE_CMS_OTHER
+This is used for other CMS message types.
+@item GPGME_DATA_TYPE_X509_CERT
+The data is a X.509 certificate
+@item GPGME_DATA_TYPE_PKCS12
+The data is a PKCS#12 message.  This is commonly used to exchange
+private keys for X.509.
+@end table
+
+@deftypefun gpgme_data_type_t gpgme_data_identify (@w{gpgme_data_t @var{dh}})
+The function @code{gpgme_data_identify} returns the type of the data
+with the handle @var{dh}.  If it is not possible to perform the
+identification, the function returns zero
+(@code{GPGME_DATA_TYPE_INVALID}).  Note that depending on how the data
+object has been created the identification may not be possible or the
+data object may change its internal state (file pointer moved).  For
+file or memory based data object, the state should not change.
+@end deftypefun
+
 
 @c
 @c    Chapter Contexts
-@c 
+@c
 @node Contexts
 @chapter Contexts
 @cindex context
@@ -2012,6 +2283,7 @@ cryptographic operations.
 * Key Management::                Managing keys with @acronym{GPGME}.
 * Trust Item Management::         Managing trust items with @acronym{GPGME}.
 * Crypto Operations::             Using a context for cryptography.
+* Miscellaneous::                 Miscellaneous operations
 * Run Control::                   Controlling how operations are run.
 @end menu
 
@@ -2086,10 +2358,13 @@ started.  In fact, these references are accessed through the
 * Crypto Engine::                 Configuring the crypto engine.
 * ASCII Armor::                   Requesting @acronym{ASCII} armored output.
 * Text Mode::                     Choosing canonical text mode.
-* Included Certificates::       Including a number of certificates.
+* 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.
 * Progress Meter Callback::       Being informed about the progress.
+* Status Message Callback::       Status messages received from gpg.
 * Locale::                        Setting the locale of a context.
 @end menu
 
@@ -2214,6 +2489,88 @@ valid pointer.
 @end deftypefun
 
 
+@node Offline Mode
+@subsection Offline Mode
+@cindex context, offline mode
+@cindex offline mode
+
+@deftypefun void gpgme_set_offline (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{yes}})
+The function @code{gpgme_set_offline} specifies if offline mode
+should be used.  By default, offline mode is not used.
+
+The offline mode specifies if dirmngr should be used to do additional
+validation that might require connections to external services.
+(e.g. CRL / OCSP checks).
+
+Offline mode only affects the keylist mode @code{GPGME_KEYLIST_MODE_VALIDATE}
+and is only relevant to the CMS crypto engine. Offline mode
+is ignored otherwise.
+
+This option may be extended in the future to completely disable
+the use of dirmngr for any engine.
+
+Offline mode is disabled if @var{yes} is zero, and enabled
+otherwise.
+@end deftypefun
+
+@deftypefun int gpgme_get_offline (@w{gpgme_ctx_t @var{ctx}})
+The function @code{gpgme_get_offline} returns 1 if offline
+mode is enabled, and @code{0} if it is not, or if @var{ctx} is not a
+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
@@ -2286,6 +2643,18 @@ signature notations on key signatures should be included in the listed
 keys.  This only works if @code{GPGME_KEYLIST_MODE_SIGS} is also
 enabled.
 
+@item GPGME_KEYLIST_MODE_WITH_TOFU
+The @code{GPGME_KEYLIST_MODE_WITH_TOFU} symbol specifies that
+information pertaining to the TOFU trust model should be included in
+the listed keys.
+
+@item GPGME_KEYLIST_MODE_WITH_SECRET
+The @code{GPGME_KEYLIST_MODE_WITH_SECRET} returns information about
+the presence of a corresponding secret key in a public key listing.  A
+public key listing with this mode is slower than a standard listing
+but can be used instead of a second run to list the secret keys.  This
+is only supported for GnuPG versions >= 2.1.
+
 @item GPGME_KEYLIST_MODE_EPHEMERAL
 The @code{GPGME_KEYLIST_MODE_EPHEMERAL} symbol specifies that keys
 flagged as ephemeral are included in the listing.
@@ -2350,9 +2719,10 @@ previous attempts failed, then @var{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 @var{fd}.  If the user returns 0 indicating
-success, the user must at least write a newline character before
-returning from the callback.
+to the file descriptor @var{fd}.  The function @code{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 @code{gpgme_error_t}
 value.  You can use the error code @code{GPG_ERR_CANCELED} to abort
@@ -2374,6 +2744,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}.
@@ -2435,6 +2809,70 @@ the corresponding value will not be returned.
 @end deftypefun
 
 
+@node Status Message Callback
+@subsection Status Message Callback
+@cindex callback, status message
+@cindex status message callback
+
+@deftp {Data type} {gpgme_error_t (*gpgme_status_cb_t)(void *@var{hook}, const char *@var{keyword}, const char *@var{args})}
+@tindex gpgme_status_cb_t
+The @code{gpgme_status_cb_t} type is the type of function usable as
+a status message callback function.
+
+The argument @var{keyword} is the name of the status message while the
+@var{args} argument contains any arguments for the status message.
+
+If an error occurs, return the corresponding @code{gpgme_error_t}
+value. Otherwise, return @code{0}.
+@end deftp
+
+@deftypefun void gpgme_set_status_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_status_cb_t @var{statusfunc}}, @w{void *@var{hook_value}})
+The function @code{gpgme_set_status_cb} sets the function that is used when a
+status message is received from gpg to @var{statusfunc}. The function
+@var{statusfunc} needs to be implemented by the user, and whenever it is
+called, it is called with its first argument being @var{hook_value}.  By
+default, no status message callback function is set.
+
+The user can disable the use of a status message callback function by calling
+@code{gpgme_set_status_cb} with @var{statusfunc} being @code{NULL}.
+@end deftypefun
+
+@deftypefun void gpgme_get_status_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_status_cb_t *@var{statusfunc}}, @w{void **@var{hook_value}})
+The function @code{gpgme_get_status_cb} returns the function that is used to
+process status messages from gpg in @var{*statusfunc}, and the first argument
+for this function in @var{*hook_value}.  If no status message callback is set,
+or @var{ctx} is not a valid pointer, @code{NULL} is returned in both
+variables.
+@end deftypefun
+
+@deftypefun {gpgme_error_t} gpgme_set_ctx_flag  @
+            (@w{gpgme_ctx_t @var{ctx}}, @
+            @w{const char *@var{name}}, @
+            @w{const char *@var{value}})
+
+Some minor properties of the context can be controlled with flags set
+by this function.  The properties are identified by the following
+values for @var{name}:
+
+@table @code
+@item "full-status"
+Using a @var{value} of "1" the status callback set by
+gpgme_set_status_cb returns all status lines with the exception of
+PROGRESS lines.  With the default of "0" the status callback is only
+called in certain situations.
+
+@item "raw-description"
+Setting the @var{value} to "1" returns human readable strings in a raw
+format.  For example the non breaking space characters ("~") will not
+be removed from the @code{description} field of the
+@code{gpgme_tofu_info_t} object.
+
+@end table
+
+This function returns @code{0} on success.
+@end deftypefun
+
+
 @node Locale
 @subsection Locale
 @cindex locale, default
@@ -2481,152 +2919,206 @@ signers are specified.  This is always done by specifying the
 respective keys that should be used for the operation.  The following
 section describes how such keys can be selected and manipulated.
 
-@deftp {Data type} gpgme_sub_key_t
-The @code{gpgme_sub_key_t} type is a pointer to a subkey structure.
-Sub keys are one component of a @code{gpgme_key_t} object.  In fact,
-subkeys are those parts that contains the real information about the
-individual cryptographic keys that belong to the same key object.  One
-@code{gpgme_key_t} can contain several subkeys.  The first subkey in
-the linked list is also called the primary key.
 
-The subkey structure has the following members:
+@menu
+* Key objects::                   Description of the key structures.
+* Listing Keys::                  Browsing the list of available keys.
+* Information About Keys::        Requesting detailed information about keys.
+* Manipulating Keys::             Operations on keys.
+* Generating Keys::               Creating new key pairs.
+* Signing Keys::                  Adding key signatures to public keys.
+* Exporting Keys::                Retrieving key data from the key ring.
+* Importing Keys::                Adding keys to the key ring.
+* Deleting Keys::                 Removing keys from the key ring.
+* Changing Passphrases::          Change the passphrase of a key.
+* Changing TOFU Data::            Changing data pertaining to TOFU.
+* Advanced Key Editing::          Advanced key edit operation.
+@end menu
+
+@node Key objects
+@subsection Key objects
+
+The keys are represented in GPGME by structures which may only be read
+by the application but never be allocated or changed.  They are valid
+as long as the key object itself is valid.
+
+@deftp {Data type} gpgme_key_t
+
+The @code{gpgme_key_t} type is a pointer to a key object.  It has the
+following members:
 
 @table @code
-@item gpgme_sub_key_t next
-This is a pointer to the next subkey structure in the linked list, or
-@code{NULL} if this is the last element.
+@item gpgme_keylist_mode_t keylist_mode
+The keylist mode that was active when the key was retrieved.
 
 @item unsigned int revoked : 1
-This is true if the subkey is revoked.
+This is true if the key is revoked.
 
 @item unsigned int expired : 1
-This is true if the subkey is expired.
+This is true if the key is expired.
 
 @item unsigned int disabled : 1
-This is true if the subkey is disabled.
+This is true if the key is disabled.
 
 @item unsigned int invalid : 1
-This is true if the subkey is invalid.
+This is true if the key is invalid. This might have several reasons,
+for a example for the S/MIME backend, it will be set during key
+listings if the key could not be validated due to missing
+certificates or unmatched policies.
 
 @item unsigned int can_encrypt : 1
-This is true if the subkey can be used for encryption.
+This is true if the key (ie one of its subkeys) can be used for
+encryption.
 
 @item unsigned int can_sign : 1
-This is true if the subkey can be used to create data signatures.
+This is true if the key (ie one of its subkeys) can be used to create
+data signatures.
 
 @item unsigned int can_certify : 1
-This is true if the subkey can be used to create key certificates.
+This is true if the key (ie one of its subkeys) can be used to create
+key certificates.
 
 @item unsigned int can_authenticate : 1
-This is true if the subkey can be used for authentication.
+This is true if the key (ie one of its subkeys) can be used for
+authentication.
 
 @item unsigned int is_qualified : 1
-This is true if the subkey can be used for qualified signatures
-according to local government regulations.
+This is true if the key can be used for qualified signatures according
+to local government regulations.
 
 @item unsigned int secret : 1
-This is true if the subkey is a secret key.  Note that it will be false
-if the key is actually a stub key; i.e. a secret key operation is
-currently not possible (offline-key).
+This is true if the key is a secret key.  Note, that this will always
+be true even if the corresponding subkey flag may be false
+(offline/stub keys).  This is only set if a listing of secret keys has
+been requested or if @code{GPGME_KEYLIST_MODE_WITH_SECRET} is active.
 
-@item gpgme_pubkey_algo_t pubkey_algo
-This is the public key algorithm supported by this subkey.
+@item gpgme_protocol_t protocol
+This is the protocol supported by this key.
 
-@item unsigned int length
-This is the length of the subkey (in bits).
+@item char *issuer_serial
+If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
+issuer serial.
 
-@item char *keyid
-This is the key ID of the subkey in hexadecimal digits.
+@item char *issuer_name
+If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
+issuer name.
 
-@item char *fpr
-This is the fingerprint of the subkey in hexadecimal digits, if
-available.
+@item char *chain_id
+If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
+chain ID, which can be used to built the certificate chain.
 
-@item long int timestamp
-This is the creation timestamp of the subkey.  This is -1 if the
-timestamp is invalid, and 0 if it is not available.
+@item gpgme_validity_t owner_trust
+If @code{protocol} is @code{GPGME_PROTOCOL_OpenPGP}, then this is the
+owner trust.
+
+@item gpgme_subkey_t subkeys
+This is a linked list with the subkeys of the key.  The first subkey
+in the list is the primary key and usually available.
+
+@item gpgme_user_id_t uids
+This is a linked list with the user IDs of the key.  The first user ID
+in the list is the main (or primary) user ID.
+
+@item char *fpr
+This field gives the fingerprint of the primary key.  Note that
+this is a copy of the fingerprint of the first subkey.  For an
+incomplete key (for example from a verification result) a subkey may
+be missing but this field may be set nevertheless.
 
-@item long int expires
-This is the expiration timestamp of the subkey, or 0 if the subkey
-does not expire.
 @end table
 @end deftp
 
-@deftp {Data type} gpgme_key_sig_t
-The @code{gpgme_key_sig_t} type is a pointer to a key signature structure.
-Key signatures are one component of a @code{gpgme_key_t} object, and
-validate user IDs on the key.
 
-The signatures on a key are only available if the key was retrieved
-via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode
-enabled, because it can be expensive to retrieve all signatures of a
-key.
+@deftp {Data type} gpgme_subkey_t
 
-The signature notations on a key signature are only available if the
-key was retrieved via a listing operation with the
-@code{GPGME_KEYLIST_MODE_SIG_NOTATIONS} mode enabled, because it can
-be expensive to retrieve all signature notations.
+The @code{gpgme_subkey_t} type is a pointer to a subkey structure.
+Subkeys are one component of a @code{gpgme_key_t} object.  In fact,
+subkeys are those parts that contains the real information about the
+individual cryptographic keys that belong to the same key object.  One
+@code{gpgme_key_t} can contain several subkeys.  The first subkey in
+the linked list is also called the primary key.
 
-The key signature structure has the following members:
+The subkey structure has the following members:
 
 @table @code
-@item gpgme_key_sig_t next
-This is a pointer to the next key signature structure in the linked
-list, or @code{NULL} if this is the last element.
+@item gpgme_subkey_t next
+This is a pointer to the next subkey structure in the linked list, or
+@code{NULL} if this is the last element.
 
 @item unsigned int revoked : 1
-This is true if the key signature is a revocation signature.
+This is true if the subkey is revoked.
 
 @item unsigned int expired : 1
-This is true if the key signature is expired.
+This is true if the subkey is expired.
+
+@item unsigned int disabled : 1
+This is true if the subkey is disabled.
 
 @item unsigned int invalid : 1
-This is true if the key signature is invalid.
+This is true if the subkey is invalid.
 
-@item unsigned int exportable : 1
-This is true if the key signature is exportable.
+@item unsigned int can_encrypt : 1
+This is true if the subkey can be used for encryption.
+
+@item unsigned int can_sign : 1
+This is true if the subkey can be used to create data signatures.
+
+@item unsigned int can_certify : 1
+This is true if the subkey can be used to create key certificates.
+
+@item unsigned int can_authenticate : 1
+This is true if the subkey can be used for authentication.
+
+@item unsigned int is_qualified : 1
+This is true if the subkey can be used for qualified signatures
+according to local government regulations.
+
+@item unsigned int secret : 1
+This is true if the subkey is a secret key.  Note that it will be
+false if the key is actually a stub key; i.e. a secret key operation
+is currently not possible (offline-key).  This is only set if a
+listing of secret keys has been requested or if
+@code{GPGME_KEYLIST_MODE_WITH_SECRET} is active.
 
 @item gpgme_pubkey_algo_t pubkey_algo
-This is the public key algorithm used to create the signature.
+This is the public key algorithm supported by this subkey.
 
-@item char *keyid
-This is the key ID of the key (in hexadecimal digits) used to create
-the signature.
+@item unsigned int length
+This is the length of the subkey (in bits).
 
-@item long int timestamp
-This is the creation timestamp of the key signature.  This is -1 if
-the timestamp is invalid, and 0 if it is not available.
+@item char *keyid
+This is the key ID of the subkey in hexadecimal digits.
 
-@item long int expires
-This is the expiration timestamp of the key signature, or 0 if the key
-signature does not expire.
+@item char *fpr
+This is the fingerprint of the subkey in hexadecimal digits, if
+available.
 
-@item gpgme_error_t status
-This is the status of the signature and has the same meaning as the
-member of the same name in a @code{gpgme_signature_t} object.
+@item char *keygrip
+The keygrip of the subkey in hex digit form or @code{NULL} if not
+availabale.
 
-@item unsigned int sig_class
-This specifies the signature class of the key signature.  The meaning
-is specific to the crypto engine.
+@item long int timestamp
+This is the creation timestamp of the subkey.  This is -1 if the
+timestamp is invalid, and 0 if it is not available.
 
-@item char *uid
-This is the main user ID of the key used to create the signature.
+@item long int expires
+This is the expiration timestamp of the subkey, or 0 if the subkey
+does not expire.
 
-@item char *name
-This is the name component of @code{uid}, if available.
+@item unsigned int is_cardkey : 1
+True if the secret key is stored on a smart card.
 
-@item char *comment
-This is the comment component of @code{uid}, if available.
+@item char *card_number
+The serial number of a smart card holding this key or @code{NULL}.
 
-@item char *email
-This is the email component of @code{uid}, if available.
+@item char *curve
+For ECC algorithms the name of the curve.
 
-@item gpgme_sig_notation_t notations
-This is a linked list with the notation data and policy URLs.
 @end table
 @end deftp
 
 @deftp {Data type} gpgme_user_id_t
+
 A user ID is a component of a @code{gpgme_key_t} object.  One key can
 have many user IDs.  The first one in the list is the main (or
 primary) user ID.
@@ -2659,100 +3151,97 @@ This is the comment component of @code{uid}, if available.
 @item char *email
 This is the email component of @code{uid}, if available.
 
+@item char *address;
+The mail address (addr-spec from RFC-5322) of the user ID string.
+This is general the same as the @code{email} part of this structure
+but might be slightly different.  If no mail address is available
+@code{NULL} is stored.
+
+@item gpgme_tofu_info_t tofu
+If not @code{NULL} information from the TOFU database pertaining to
+this user id.
+
 @item gpgme_key_sig_t signatures
 This is a linked list with the signatures on this user ID.
 @end table
 @end deftp
 
-@deftp {Data type} gpgme_key_t
-The @code{gpgme_key_t} type is a pointer to a key object.  It has the
-following members:
+
+@deftp {Data type} gpgme_key_sig_t
+
+The @code{gpgme_key_sig_t} type is a pointer to a key signature structure.
+Key signatures are one component of a @code{gpgme_key_t} object, and
+validate user IDs on the key in the OpenPGP protocol.
+
+The signatures on a key are only available if the key was retrieved
+via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode
+enabled, because it can be expensive to retrieve all signatures of a
+key.
+
+The signature notations on a key signature are only available if the
+key was retrieved via a listing operation with the
+@code{GPGME_KEYLIST_MODE_SIG_NOTATIONS} mode enabled, because it can
+be expensive to retrieve all signature notations.
+
+The key signature structure has the following members:
 
 @table @code
-@item gpgme_keylist_mode_t keylist_mode
-The keylist mode that was active when the key was retrieved.
+@item gpgme_key_sig_t next
+This is a pointer to the next key signature structure in the linked
+list, or @code{NULL} if this is the last element.
 
 @item unsigned int revoked : 1
-This is true if the key is revoked.
+This is true if the key signature is a revocation signature.
 
 @item unsigned int expired : 1
-This is true if the key is expired.
-
-@item unsigned int disabled : 1
-This is true if the key is disabled.
+This is true if the key signature is expired.
 
 @item unsigned int invalid : 1
-This is true if the key is invalid. This might have several reasons,
-for a example for the S/MIME backend, it will be set in during key
-listsing if the key could not be validated due to a missing
-certificates or unmatched policies.
+This is true if the key signature is invalid.
 
-@item unsigned int can_encrypt : 1
-This is true if the key (ie one of its subkeys) can be used for
-encryption.
+@item unsigned int exportable : 1
+This is true if the key signature is exportable.
 
-@item unsigned int can_sign : 1
-This is true if the key (ie one of its subkeys) can be used to create
-data signatures.
+@item gpgme_pubkey_algo_t pubkey_algo
+This is the public key algorithm used to create the signature.
 
-@item unsigned int can_certify : 1
-This is true if the key (ie one of its subkeys) can be used to create
-key certificates.
+@item char *keyid
+This is the key ID of the key (in hexadecimal digits) used to create
+the signature.
 
-@item unsigned int can_authenticate : 1
-This is true if the key (ie one of its subkeys) can be used for
-authentication.
+@item long int timestamp
+This is the creation timestamp of the key signature.  This is -1 if
+the timestamp is invalid, and 0 if it is not available.
 
-@item unsigned int is_qualified : 1
-This is true if the key can be used for qualified signatures according
-to local government regulations.
+@item long int expires
+This is the expiration timestamp of the key signature, or 0 if the key
+signature does not expire.
 
-@item unsigned int secret : 1
-This is true if the key is a secret key.  Note, that this will always be
-true even if the corresponding subkey flag may be false (offline/stub
-keys).
+@item gpgme_error_t status
+This is the status of the signature and has the same meaning as the
+member of the same name in a @code{gpgme_signature_t} object.
 
-@item gpgme_protocol_t protocol
-This is the protocol supported by this key.
+@item unsigned int sig_class
+This specifies the signature class of the key signature.  The meaning
+is specific to the crypto engine.
 
-@item char *issuer_serial
-If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
-issuer serial.
+@item char *uid
+This is the main user ID of the key used to create the signature.
 
-@item char *issuer_name
-If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
-issuer name.
+@item char *name
+This is the name component of @code{uid}, if available.
 
-@item char *chain_id
-If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
-chain ID, which can be used to built the certificate chain.
-@item gpgme_validity_t owner_trust
-If @code{protocol} is @code{GPGME_PROTOCOL_OpenPGP}, then this is the
-owner trust.
+@item char *comment
+This is the comment component of @code{uid}, if available.
 
-@item gpgme_sub_key_t subkeys
-This is a linked list with the subkeys of the key.  The first subkey
-in the list is the primary key and usually available.
+@item char *email
+This is the email component of @code{uid}, if available.
 
-@item gpgme_user_id_t uids
-This is a linked list with the user IDs of the key.  The first user ID
-in the list is the main (or primary) user ID.
+@item gpgme_sig_notation_t notations
+This is a linked list with the notation data and policy URLs.
 @end table
 @end deftp
 
-@menu
-* Listing Keys::                  Browsing the list of available keys.
-* Information About Keys::        Requesting detailed information about keys.
-* Key Signatures::                Listing the signatures on a key.
-* Manipulating Keys::             Operations on keys.
-* Generating Keys::               Creating new key pairs.
-* Exporting Keys::                Retrieving key data from the key ring.
-* Importing Keys::                Adding keys to the key ring.
-* Deleting Keys::                 Removing keys from the key ring.
-* Changing Passphrases::          Change the passphrase of a key.
-* Advanced Key Editing::          Advanced key edit operation.
-@end menu
 
 
 @node Listing Keys
@@ -2972,315 +3461,326 @@ validity is ``u''.
 @end deftp
 
 
-The following interfaces are deprecated and only provided for backward
-compatibility.  Don't use them.  They will be removed in a future
-version of @acronym{GPGME}.
-
-@deftp {Data type} gpgme_attr_t
-The @code{gpgme_attr_t} type is used to specify a key or trust item
-attribute.  The following attributes are defined:
 
-@table @code
-@item GPGME_ATTR_KEYID
-This is the key ID of a sub key.  It is representable as a string.
 
-For trust items, the trust item refers to the key with this ID.
+@node Manipulating Keys
+@subsection Manipulating Keys
+@cindex key, manipulation
 
-@item GPGME_ATTR_FPR
-This is the fingerprint of a sub key.  It is representable as a
-string.
+@deftypefun void gpgme_key_ref (@w{gpgme_key_t @var{key}})
+The function @code{gpgme_key_ref} acquires an additional reference for
+the key @var{key}.
+@end deftypefun
 
-@item GPGME_ATTR_ALGO
-This is the crypto algorithm for which the sub key can be used.  It
-is representable as a string and as a number.  The numbers correspond
-to the @code{enum gcry_pk_algos} values in the gcrypt library.
+@deftypefun void gpgme_key_unref (@w{gpgme_key_t @var{key}})
+The function @code{gpgme_key_unref} releases a reference for the key
+@var{key}.  If this was the last reference, the key will be destroyed
+and all resources associated to it will be released.
+@end deftypefun
 
-@item GPGME_ATTR_LEN
-This is the key length of a sub key.  It is representable as a
-number.
 
-@item GPGME_ATTR_CREATED
-This is the timestamp at creation time of a sub key.  It is
-representable as a number.
+@node Generating Keys
+@subsection Generating Keys
+@cindex key, creation
+@cindex key ring, add
 
-@item GPGME_ATTR_EXPIRE
-This is the expiration time of a sub key.  It is representable as a
-number.
+GPGME provides a set of functions to create public key pairs.  Most of
+these functions require the use of GnuPG 2.1 and later; for older
+GnuPG versions the @code{gpgme_op_genkey} function can be used.
+Existing code which wants to update to the new functions or new code
+which shall supports older GnuPG versions may try the new functions
+first and provide a fallback to the old function if the error code
+@code{GPG_ERR_NOT_SUPPORTED} is received.
 
-@item GPGME_ATTR_OTRUST
-XXX FIXME  (also for trust items)
-
-@item GPGME_ATTR_USERID
-This is a user ID.  There can be more than one user IDs in a
-@var{gpgme_key_t} object.  The first one (with index 0) is the primary
-user ID.  The user ID is representable as a number.
-
-For trust items, this is the user ID associated with this trust item.
-
-@item GPGME_ATTR_NAME
-This is the name belonging to a user ID.  It is representable as a string.
-
-@item GPGME_ATTR_EMAIL
-This is the email address belonging to a user ID.  It is representable
-as a string.
-
-@item GPGME_ATTR_COMMENT
-This is the comment belonging to a user ID.  It is representable as a
-string.
-
-@item GPGME_ATTR_VALIDITY
-This is the validity belonging to a user ID.  It is representable as a
-string and as a number.  See below for a list of available validities.
-
-For trust items, this is the validity that is associated with this
-trust item.
+@c
+@c  gpgme_op_createkey
+@c
+@deftypefun gpgme_error_t gpgme_op_createkey @
+      (@w{gpgme_ctx_t @var{ctx}}, @
+       @w{const char *@var{userid}}, @
+       @w{const char *@var{algo}}, @
+       @w{unsigned long @var{reserved}}, @
+       @w{unsigned long @var{expires}}, @
+       @w{gpgme_key_t @var{extrakey}}, @
+       @w{unsigned int @var{flags}});
+
+The function @code{gpgme_op_createkey} generates a new key for the
+procotol active in the context @var{ctx}.  As of now this function
+does only work for OpenPGP and requires at least version 2.1.13 of
+GnuPG.
 
-@item GPGME_ATTR_UID_REVOKED
-This specifies if a user ID is revoked.  It is representable as a
-number, and is @code{1} if the user ID is revoked, and @code{0}
-otherwise.
+@var{userid} is commonly the mail address associated with the key.
+GPGME does not require a specificy syntax but if more than a mail
+address is given, RFC-822 style format is suggested.  The value is
+expected to be in UTF-8 encoding (i.e. no IDN encoding for mail
+addresses).  This is a required parameter.
+
+@var{algo} specifies the algorithm for the new key (actually a keypair
+of public and private key).  For a list of supported algorithms, see
+the GnuPG manual.  If @var{algo} is @code{NULL} or the string
+"default", the key is generated using the default algorithm of the
+engine.  If the string "future-default" is used the engine may use an
+algorithm which is planned to be the default in a future release of
+the engine; however existing implementation of the protocol may not be
+able to already handle such future algorithms.  For the OpenPGP
+protocol, the specification of a default algorithm, without requesting
+a non-default usage via @var{flags}, triggers the creation of a
+primary key plus a secondary key (subkey).
+
+@var{reserved} must be set to zero.
+
+@var{expires} can be set to the number of seconds since Epoch of the
+desired expiration date in UTC for the new key.   Using 0 does not
+set an expiration date.  Note that this parameter takes an unsigned long
+value and not a @code{time_t} to avoid problems on systems which use a
+signed 32 bit @code{time_t}.  Note further that the OpenPGP protocol
+uses 32 bit values for timestamps and thus can only encode dates up to
+the year 2106.
+
+@var{extrakey} is currently not used and must be set to @code{NULL}.
+A future version of GPGME may use this parameter to create X.509 keys.
+
+@var{flags} can be set to the bit-wise OR of the following flags:
 
-@item GPGME_ATTR_UID_INVALID
-This specifies if a user ID is invalid.  It is representable as a
-number, and is @code{1} if the user ID is invalid, and @code{0}
-otherwise.
+@table @code
+@item GPGME_CREATE_SIGN
+@itemx GPGME_CREATE_ENCR
+@itemx GPGME_CREATE_CERT
+@itemx GPGME_CREATE_AUTH
+Do not create the key with the default capabilities (key usage) of the
+requested algorithm but use those explicitly given by these flags:
+``signing'', ``encryption'', ``certification'', or ``authentication''.
+The allowed combinations depend on the algorithm.
+
+If any of these flags are set and a default algorithm has been
+selected only one key is created in the case of the OpenPGP
+protocol.
+
+@item GPGME_CREATE_NOPASSWD
+Request generation of the key without password protection.
+
+@item GPGME_CREATE_SELFSIGNED
+For an X.509 key do not create a CSR but a self-signed certificate.
+This has not yet been implemented.
+
+@item GPGME_CREATE_NOSTORE
+Do not store the created key in the local key database.
+This has not yet been implemented.
+
+@item GPGME_CREATE_WANTPUB
+@itemx GPGME_CREATE_WANTSEC
+Return the public or secret key as part of the result structure.
+This has not yet been implemented.
+
+@item GPGME_CREATE_FORCE
+The engine does not allow the creation of a key with a user ID
+already existing in the local key database.  This flag can be used to
+override this check.
 
-@item GPGME_ATTR_LEVEL
-This is the trust level of a trust item.
+@end table
 
-@item GPGME_ATTR_TYPE
-This returns information about the type of key.  For the string function
-this will eother be "PGP" or "X.509".  The integer function returns 0
-for PGP and 1 for X.509.  It is also used for the type of a trust item.
+After the operation completed successfully, information about the
+created key can be retrieved with @code{gpgme_op_genkey_result}.
 
-@item GPGME_ATTR_IS_SECRET
-This specifies if the key is a secret key.  It is representable as a
-number, and is @code{1} if the key is revoked, and @code{0} otherwise.
+The function returns zero on success, @code{GPG_ERR_NOT_SUPPORTED} if
+the engine does not support the command, or a bunch of other error
+codes.
 
-@item GPGME_ATTR_KEY_REVOKED
-This specifies if a sub key is revoked.  It is representable as a
-number, and is @code{1} if the key is revoked, and @code{0} otherwise.
+@end deftypefun
 
-@item GPGME_ATTR_KEY_INVALID
-This specifies if a sub key is invalid.  It is representable as a
-number, and is @code{1} if the key is invalid, and @code{0} otherwise.
 
-@item GPGME_ATTR_KEY_EXPIRED
-This specifies if a sub key is expired.  It is representable as a
-number, and is @code{1} if the key is expired, and @code{0} otherwise.
+@deftypefun gpgme_error_t gpgme_op_createkey_start @
+      (@w{gpgme_ctx_t @var{ctx}}, @
+       @w{const char *@var{userid}}, @
+       @w{const char *@var{algo}}, @
+       @w{unsigned long @var{reserved}}, @
+       @w{unsigned long @var{expires}}, @
+       @w{gpgme_key_t @var{extrakey}}, @
+       @w{unsigned int @var{flags}});
 
-@item GPGME_ATTR_KEY_DISABLED
-This specifies if a sub key is disabled.  It is representable as a
-number, and is @code{1} if the key is disabled, and @code{0} otherwise.
+The function @code{gpgme_op_createkey_start} initiates a
+@code{gpgme_op_createkey} operation; see there for details.  It must
+be completed by calling @code{gpgme_wait} on the context.
+@xref{Waiting For Completion}.
 
-@item GPGME_ATTR_KEY_CAPS
-This is a description of the capabilities of a sub key.  It is
-representable as a string.  The string contains the letter ``e'' if
-the key can be used for encryption, ``s'' if the key can be used for
-signatures, and ``c'' if the key can be used for certifications.
+@end deftypefun
 
-@item GPGME_ATTR_CAN_ENCRYPT
-This specifies if a sub key can be used for encryption.  It is
-representable as a number, and is @code{1} if the sub key can be used
-for encryption, and @code{0} otherwise.
+@c
+@c  gpgme_op_createsubkey
+@c
+@deftypefun gpgme_error_t gpgme_op_createsubkey @
+      (@w{gpgme_ctx_t @var{ctx}}, @
+       @w{gpgme_key_t @var{key}}, @
+       @w{const char *@var{algo}}, @
+       @w{unsigned long @var{reserved}}, @
+       @w{unsigned long @var{expires}}, @
+       @w{unsigned int @var{flags}});
 
-@item GPGME_ATTR_CAN_SIGN
-This specifies if a sub key can be used to create data signatures.  It
-is representable as a number, and is @code{1} if the sub key can be
-used for signatures, and @code{0} otherwise.
+The function @code{gpgme_op_createsubkey} creates and adds a new
+subkey to the primary OpenPGP key given by @var{KEY}.  The only
+allowed protocol in @var{ctx} is @code{GPGME_PROTOCOL_OPENPGP}.
+Subkeys (aka secondary keys) are a concept in the OpenPGP protocol to
+bind several keys to a primary key.  As of now this function requires
+at least version 2.1.13 of GnuPG.
 
-@item GPGME_ATTR_CAN_CERTIFY
-This specifies if a sub key can be used to create key certificates.
-It is representable as a number, and is @code{1} if the sub key can be
-used for certifications, and @code{0} otherwise.
+@var{key} specifies the key to operate on.
 
-@item GPGME_ATTR_SERIAL
-The X.509 issuer serial attribute of the key.  It is representable as
-a string.
+@var{algo} specifies the algorithm for the new subkey.  For a list of
+supported algorithms, see the GnuPG manual.  If @var{algo} is
+@code{NULL} or the string "default", the subkey is generated using the
+default algorithm for an encryption subkey of the engine.  If the
+string "future-default" is used the engine may use an encryption
+algorithm which is planned to be the default in a future release of
+the engine; however existing implementation of the protocol may not be
+able to already handle such future algorithms.
 
-@item GPGME_ATTR_ISSUE
-The X.509 issuer name attribute of the key.  It is representable as a
-string.
+@var{reserved} must be set to zero.
 
-@item GPGME_ATTR_CHAINID
-The X.509 chain ID can be used to build the certification chain.  It
-is representable as a string.
-@end table
-@end deftp
+@var{expires} can be set to the number of seconds since Epoch of the
+desired expiration date in UTC for the new subkey.   Using 0 does not
+set an expiration date.  Note that this parameter takes an unsigned long
+value and not a @code{time_t} to avoid problems on systems which use a
+signed 32 bit @code{time_t}.  Note further that the OpenPGP protocol
+uses 32 bit values for timestamps and thus can only encode dates up to
+the year 2106.
 
-@deftypefun {const char *} gpgme_key_get_string_attr (@w{gpgme_key_t @var{key}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
-The function @code{gpgme_key_get_string_attr} returns the value of the
-string-representable attribute @var{what} of key @var{key}.  If the
-attribute is an attribute of a sub key or an user ID, @var{idx}
-specifies the sub key or user ID of which the attribute value is
-returned.  The argument @var{reserved} is reserved for later use and
-should be @code{NULL}.
+@var{flags} takes the same values as described above for
+@code{gpgme_op_createkey}.
 
-The string returned is only valid as long as the key is valid.
+After the operation completed successfully, information about the
+created key can be retrieved with @code{gpgme_op_genkey_result}.
 
-The function returns @code{0} if an attribute can't be returned as a
-string, @var{key} is not a valid pointer, @var{idx} out of range,
-or @var{reserved} not @code{NULL}.
-@end deftypefun
+The function returns zero on success, @code{GPG_ERR_NOT_SUPPORTED} if
+the engine does not support the command, or a bunch of other error
+codes.
 
-@deftypefun {unsigned long} gpgme_key_get_ulong_attr (@w{gpgme_key_t @var{key}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
-The function @code{gpgme_key_get_ulong_attr} returns the value of the
-number-representable attribute @var{what} of key @var{key}.  If the
-attribute is an attribute of a sub key or an user ID, @var{idx}
-specifies the sub key or user ID of which the attribute value is
-returned.  The argument @var{reserved} is reserved for later use and
-should be @code{NULL}.
 
-The function returns @code{0} if the attribute can't be returned as a
-number, @var{key} is not a valid pointer, @var{idx} out of range, or
-@var{reserved} not @code{NULL}.
 @end deftypefun
 
+@deftypefun gpgme_error_t gpgme_op_createsubkey_start @
+      (@w{gpgme_ctx_t @var{ctx}}, @
+       @w{gpgme_key_t @var{key}}, @
+       @w{const char *@var{algo}}, @
+       @w{unsigned long @var{reserved}}, @
+       @w{unsigned long @var{expires}}, @
+       @w{unsigned int @var{flags}});
 
-@node Key Signatures
-@subsection Key Signatures
-@cindex key, signatures
-@cindex signatures, on a key
+The function @code{gpgme_op_createsubkey_start} initiates a
+@code{gpgme_op_createsubkey} operation; see there for details.  It must
+be completed by calling @code{gpgme_wait} on the context.
+@xref{Waiting For Completion}.
 
-The following interfaces are deprecated and only provided for backward
-compatibility.  Don't use them.  They will be removed in a future
-version of @acronym{GPGME}.
+@end deftypefun
 
-The signatures on a key are only available if the key was retrieved
-via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode
-enabled, because it is expensive to retrieve all signatures of a key.
 
-So, before using the below interfaces to retrieve the signatures on a
-key, you have to make sure that the key was listed with signatures
-enabled.  One convenient, but blocking, way to do this is to use the
-function @code{gpgme_get_key}.
+@c
+@c  gpgme_op_adduid
+@c
+@deftypefun gpgme_error_t gpgme_op_adduid @
+      (@w{gpgme_ctx_t @var{ctx}}, @
+       @w{gpgme_key_t @var{key}}, @
+       @w{const char *@var{userid}}, @
+       @w{unsigned int @var{flags}});
 
-@deftp {Data type} gpgme_attr_t
-The @code{gpgme_attr_t} type is used to specify a key signature
-attribute.  The following attributes are defined:
+The function @code{gpgme_op_adduid} adds a new user ID to the OpenPGP
+key given by @var{KEY}.  Adding additional user IDs after key creation
+is a feature of the OpenPGP protocol and thus the protocol for the
+context @var{ctx} must be set to OpenPGP.  As of now this function
+requires at least version 2.1.13 of GnuPG.
 
-@table @code
-@item GPGME_ATTR_KEYID
-This is the key ID of the key which was used for the signature.  It is
-representable as a string.
+@var{key} specifies the key to operate on.
 
-@item GPGME_ATTR_ALGO
-This is the crypto algorithm used to create the signature.  It is
-representable as a string and as a number.  The numbers correspond to
-the @code{enum gcry_pk_algos} values in the gcrypt library.
+@var{userid} is the user ID to add to the key.  A user ID is commonly
+the mail address to be associated with the key.  GPGME does not
+require a specificy syntax but if more than a mail address is given,
+RFC-822 style format is suggested.  The value is expected to be in
+UTF-8 encoding (i.e. no IDN encoding for mail addresses).  This is a
+required parameter.
 
-@item GPGME_ATTR_CREATED
-This is the timestamp at creation time of the signature.  It is
-representable as a number.
+@var{flags} are currently not used and must be set to zero.
 
-@item GPGME_ATTR_EXPIRE
-This is the expiration time of the signature.  It is representable as
-a number.
+The function returns zero on success, @code{GPG_ERR_NOT_SUPPORTED} if
+the engine does not support the command, or a bunch of other error
+codes.
 
-@item GPGME_ATTR_USERID
-This is the user ID associated with the signing key.  The user ID is
-representable as a number.
+@end deftypefun
 
-@item GPGME_ATTR_NAME
-This is the name belonging to a user ID.  It is representable as a string.
+@deftypefun gpgme_error_t gpgme_op_adduid_start @
+      (@w{gpgme_ctx_t @var{ctx}}, @
+       @w{gpgme_key_t @var{key}}, @
+       @w{const char *@var{userid}}, @
+       @w{unsigned int @var{flags}});
 
-@item GPGME_ATTR_EMAIL
-This is the email address belonging to a user ID.  It is representable
-as a string.
+The function @code{gpgme_op_adduid_start} initiates a
+@code{gpgme_op_adduid} operation; see there for details.  It must
+be completed by calling @code{gpgme_wait} on the context.
+@xref{Waiting For Completion}.
 
-@item GPGME_ATTR_COMMENT
-This is the comment belonging to a user ID.  It is representable as a
-string.
+@end deftypefun
 
-@item GPGME_ATTR_KEY_REVOKED
-This specifies if a key signature is a revocation signature.  It is
-representable as a number, and is @code{1} if the key is revoked, and
-@code{0} otherwise.
 
-@c @item GPGME_ATTR_KEY_EXPIRED
-@c This specifies if a key signature is expired.  It is representable as
-@c a number, and is @code{1} if the key is revoked, and @code{0}
-@c otherwise.
 @c
-@item GPGME_ATTR_SIG_CLASS
-This specifies the signature class of a key signature.  It is
-representable as a number.  The meaning is specific to the crypto
-engine.
-
-@item GPGME_ATTR_SIG_CLASS
-This specifies the signature class of a key signature.  It is
-representable as a number.  The meaning is specific to the crypto
-engine.
-
-@item GPGME_ATTR_SIG_STATUS
-This is the same value as returned by @code{gpgme_get_sig_status}.
-@end table
-@end deftp
-
-@deftypefun {const char *} gpgme_key_sig_get_string_attr (@w{gpgme_key_t @var{key}}, @w{int @var{uid_idx}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
-The function @code{gpgme_key_sig_get_string_attr} returns the value of
-the string-representable attribute @var{what} of the signature
-@var{idx} on the user ID @var{uid_idx} in the key @var{key}.  The
-argument @var{reserved} is reserved for later use and should be
-@code{NULL}.
-
-The string returned is only valid as long as the key is valid.
+@c  gpgme_op_revuid
+@c
+@deftypefun gpgme_error_t gpgme_op_revuid @
+      (@w{gpgme_ctx_t @var{ctx}}, @
+       @w{gpgme_key_t @var{key}}, @
+       @w{const char *@var{userid}}, @
+       @w{unsigned int @var{flags}});
 
-The function returns @code{0} if an attribute can't be returned as a
-string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx}
-out of range, or @var{reserved} not @code{NULL}.
-@end deftypefun
+The function @code{gpgme_op_revuid} revokes a user ID from the OpenPGP
+key given by @var{KEY}.  Revoking user IDs after key creation is a
+feature of the OpenPGP protocol and thus the protocol for the context
+@var{ctx} must be set to OpenPGP.  As of now this function requires at
+least version 2.1.13 of GnuPG.
 
-@deftypefun {unsigned long} gpgme_key_sig_get_ulong_attr (@w{gpgme_key_t @var{key}}, @w{int @var{uid_idx}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
-The function @code{gpgme_key_sig_get_ulong_attr} returns the value of
-the number-representable attribute @var{what} of the signature
-@var{idx} on the user ID @var{uid_idx} in the key @var{key}.  The
-argument @var{reserved} is reserved for later use and should be
-@code{NULL}.
+@var{key} specifies the key to operate on.
 
-The function returns @code{0} if an attribute can't be returned as a
-string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx}
-out of range, or @var{reserved} not @code{NULL}.
-@end deftypefun
+@var{userid} is the user ID to be revoked from the key.  The user ID
+must be given verbatim because the engine does an exact and case
+sensitive match.  Thus the @code{uid} field from the user ID object
+(@code{gpgme_user_id_t}) is to be used.  This is a required parameter.
 
+@var{flags} are currently not used and must be set to zero.
 
-@node Manipulating Keys
-@subsection Manipulating Keys
-@cindex key, manipulation
+Note that the engine won't allow to revoke the last valid user ID.  To
+change a user ID is better to first add the new user ID, then revoke
+the old one, and finally publish the key.
 
-@deftypefun void gpgme_key_ref (@w{gpgme_key_t @var{key}})
-The function @code{gpgme_key_ref} acquires an additional reference for
-the key @var{key}.
-@end deftypefun
+The function returns zero on success, @code{GPG_ERR_NOT_SUPPORTED} if
+the engine does not support the command, or a bunch of other error
+codes.
 
-@deftypefun void gpgme_key_unref (@w{gpgme_key_t @var{key}})
-The function @code{gpgme_key_unref} releases a reference for the key
-@var{key}.  If this was the last reference, the key will be destroyed
-and all resources associated to it will be released.
 @end deftypefun
 
+@deftypefun gpgme_error_t gpgme_op_revuid_start @
+      (@w{gpgme_ctx_t @var{ctx}}, @
+       @w{gpgme_key_t @var{key}}, @
+       @w{const char *@var{userid}}, @
+       @w{unsigned int @var{flags}});
 
-The following interface is deprecated and only provided for backward
-compatibility.  Don't use it.  It will be removed in a future version
-of @acronym{GPGME}.
+The function @code{gpgme_op_revuid_start} initiates a
+@code{gpgme_op_revuid} operation; see there for details.  It must
+be completed by calling @code{gpgme_wait} on the context.
+@xref{Waiting For Completion}.
 
-@deftypefun void gpgme_key_release (@w{gpgme_key_t @var{key}})
-The function @code{gpgme_key_release} is equivalent to
-@code{gpgme_key_unref}.
 @end deftypefun
 
 
-@node Generating Keys
-@subsection Generating Keys
-@cindex key, creation
-@cindex key ring, add
+@c
+@c  gpgme_op_genkey
+@c
+@deftypefun gpgme_error_t gpgme_op_genkey @
+      (@w{gpgme_ctx_t @var{ctx}}, @
+       @w{const char *@var{parms}}, @
+       @w{gpgme_data_t @var{public}}, @
+       @w{gpgme_data_t @var{secret}})
 
-@deftypefun gpgme_error_t gpgme_op_genkey (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{parms}}, @w{gpgme_data_t @var{public}}, @w{gpgme_data_t @var{secret}})
 The function @code{gpgme_op_genkey} generates a new key pair in the
 context @var{ctx}.  The meaning of @var{public} and @var{secret}
 depends on the crypto backend.
 
-GnuPG does not support @var{public} and @var{secret}, they should be
+GPG does not support @var{public} and @var{secret}, they should be
 @code{NULL}.  GnuPG will generate a key pair and add it to the
 standard key ring.  The fingerprint of the generated key is available
 with @code{gpgme_op_genkey_result}.
@@ -3337,6 +3837,7 @@ if no key was created by the backend.
 @end deftypefun
 
 @deftypefun gpgme_error_t gpgme_op_genkey_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{parms}}, @w{gpgme_data_t @var{public}}, @w{gpgme_data_t @var{secret}})
+
 The function @code{gpgme_op_genkey_start} initiates a
 @code{gpgme_op_genkey} operation.  It can be completed by calling
 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
@@ -3348,7 +3849,12 @@ operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
 @code{NULL}.
 @end deftypefun
 
+
+@c
+@c  gpgme_op_genkey_result
+@c
 @deftp {Data type} {gpgme_genkey_result_t}
+
 This is a pointer to a structure used to store the result of a
 @code{gpgme_op_genkey} operation.  After successfully generating a
 key, you can retrieve the pointer to the result with
@@ -3357,22 +3863,34 @@ members:
 
 @table @code
 @item unsigned int primary : 1
-This is a flag that is set to 1 if a primary key was created and to 0
+This flag is set to 1 if a primary key was created and to 0
 if not.
 
 @item unsigned int sub : 1
-This is a flag that is set to 1 if a subkey was created and to 0
-if not.
+This flag is set to 1 if a subkey was created and to 0 if not.
+
+@item unsigned int uid : 1
+This flag is set to 1 if a user ID was created and to 0 if not.
 
 @item char *fpr
 This is the fingerprint of the key that was created.  If both a
-primary and a sub key were generated, the fingerprint of the primary
+primary and a subkey were generated, the fingerprint of the primary
 key will be returned.  If the crypto engine does not provide the
 fingerprint, @code{fpr} will be a null pointer.
+
+@item gpgme_data_t pubkey
+This will eventually be used to return the public key.  It is
+currently not used.
+
+@item gpgme_data_t seckey
+This will eventually be used to return the secret key.  It is
+currently not used.
+
 @end table
 @end deftp
 
 @deftypefun gpgme_genkey_result_t gpgme_op_genkey_result (@w{gpgme_ctx_t @var{ctx}})
+
 The function @code{gpgme_op_genkey_result} returns a
 @code{gpgme_genkey_result_t} pointer to a structure holding the result of
 a @code{gpgme_op_genkey} operation.  The pointer is only valid if the
@@ -3380,34 +3898,150 @@ last operation on the context was a @code{gpgme_op_genkey} or
 @code{gpgme_op_genkey_start} operation, and if this operation finished
 successfully.  The returned pointer is only valid until the next
 operation is started on the context.
+
 @end deftypefun
 
 
-@node Exporting Keys
-@subsection Exporting Keys
-@cindex key, export
-@cindex key ring, export from
+@c
+@c  SIGNING KEYS
+@c
+@node Signing Keys
+@subsection Signing Keys
+@cindex key, signing
 
-Exporting keys means the same as running @command{gpg} with the command
-@option{--export}.  However, a mode flag can be used to change the way
-the export works.  The available mode flags are described below, they
-may be or-ed together.
+Key signatures are a unique concept of the OpenPGP protocol.  They can
+be used to certify the validity of a key and are used to create the
+Web-of-Trust (WoT).  Instead of using the @code{gpgme_op_interact}
+function along with a finite state machine, GPGME provides a
+convenient function to create key signatures when using modern GnuPG
+versions.
+
+
+@c
+@c  gpgme_op_keysign
+@c
+@deftypefun gpgme_error_t gpgme_op_keysign @
+      (@w{gpgme_ctx_t @var{ctx}}, @
+       @w{gpgme_key_t @var{key}}, @
+       @w{const char *@var{userid}}, @
+       @w{unsigned long @var{expires}}, @
+       @w{unsigned int @var{flags}});
+
+The function @code{gpgme_op_keysign} adds a new key signature to the
+public key @var{KEY}.   This function requires at least version 2.1.12 of
+GnuPG.
+
+@var{CTX} is the usual context which describes the protocol to use
+(which must be OpenPGP) and has also the list of signer keys to be
+used for the signature.  The common case is to use the default key for
+signing other keys.  If another key or more than one key shall be used
+for a key signature, @code{gpgme_signers_add} can be used.
+@xref{Selecting Signers}.
+
+@var{key} specifies the key to operate on.
+
+@var{userid} selects the user ID or user IDs to be signed.  If
+@var{userid} is set to @code{NULL} all valid user IDs are signed.  The
+user ID must be given verbatim because the engine does an exact and
+case sensitive match.  Thus the @code{uid} field from the user ID
+object (@code{gpgme_user_id_t}) is to be used.  To select more than
+one user ID put them all into one string separated by linefeeds
+characters (@code{\n}) and set the flag @code{GPGME_KEYSIGN_LFSEP}.
+
+@var{expires} can be set to the number of seconds since Epoch of the
+desired expiration date in UTC for the new signature.  The common case
+is to use 0 to not set an expiration date.  However, if the
+configuration of the engine defines a default expiration for key
+signatures, that is still used unless the flag
+@code{GPGME_KEYSIGN_NOEXPIRE} is used.  Note that this parameter takes
+an unsigned long value and not a @code{time_t} to avoid problems on
+systems which use a signed 32 bit @code{time_t}.  Note further that
+the OpenPGP protocol uses 32 bit values for timestamps and thus can
+only encode dates up to the year 2106.
+
+@var{flags} can be set to the bit-wise OR of the following flags:
 
 @table @code
+@item GPGME_KEYSIGN_LOCAL
+Instead of creating an exportable key signature, create a key
+signature which is is marked as non-exportable.
 
-@item GPGME_EXPORT_MODE_EXTERN
-If this bit is set, the output is send directly to the default
-keyserver. This is currently only allowed for OpenPGP keys.  It is good
-practise to not send more than a few dozens key to a keyserver at one
-time.  Using this flag requires that the @var{keydata} argument of the
-export function is set to @code{NULL}.
+@item GPGME_KEYSIGN_LFSEP
+Although linefeeds are uncommon in user IDs this flag is required to
+explicitly declare that @var{userid} may contain several linefeed
+separated user IDs.
 
-@item GPGME_EXPORT_MODE_MINIMAL
+@item GPGME_KEYSIGN_NOEXPIRE
+Force the creation of a key signature without an expiration date.  This
+overrides @var{expire} and any local configuration of the engine.
+
+@end table
+
+The function returns zero on success, @code{GPG_ERR_NOT_SUPPORTED} if
+the engine does not support the command, or a bunch of other error
+codes.
+
+@end deftypefun
+
+
+@deftypefun gpgme_error_t gpgme_op_keysign_start @
+      (@w{gpgme_ctx_t @var{ctx}}, @
+       @w{gpgme_key_t @var{key}}, @
+       @w{const char *@var{userid}}, @
+       @w{unsigned long @var{expires}}, @
+       @w{unsigned int @var{flags}});
+
+The function @code{gpgme_op_keysign_start} initiates a
+@code{gpgme_op_keysign} operation; see there for details.  It must
+be completed by calling @code{gpgme_wait} on the context.
+@xref{Waiting For Completion}.
+
+@end deftypefun
+
+
+@c
+@c  EXPORTING KEYS
+@c
+@node Exporting Keys
+@subsection Exporting Keys
+@cindex key, export
+@cindex key ring, export from
+
+Exporting keys means the same as running @command{gpg} with the command
+@option{--export}.  However, a mode flag can be used to change the way
+the export works.  The available mode flags are described below, they
+may be or-ed together.
+
+@table @code
+
+@item GPGME_EXPORT_MODE_EXTERN
+If this bit is set, the output is send directly to the default
+keyserver. This is currently only allowed for OpenPGP keys.  It is good
+practise to not send more than a few dozens key to a keyserver at one
+time.  Using this flag requires that the @var{keydata} argument of the
+export function is set to @code{NULL}.
+
+@item GPGME_EXPORT_MODE_MINIMAL
 If this bit is set, the smallest possible key is exported.  For OpenPGP
 keys it removes all signatures except for the latest self-signatures.
 For X.509 keys it has no effect.
 
 
+@item GPGME_EXPORT_MODE_SECRET
+Instead of exporting the public key, the secret key is exported.  This
+may not be combined with @code{GPGME_EXPORT_MODE_EXTERN}.  For X.509
+the export format is PKCS#8.
+
+@item GPGME_EXPORT_MODE_RAW
+If this flag is used with @code{GPGME_EXPORT_MODE_SECRET} for an X.509
+key the export format will be changed to PKCS#1.  This flag may not be
+used with OpenPGP.
+
+@item GPGME_EXPORT_MODE_PKCS12
+If this flag is used with @code{GPGME_EXPORT_MODE_SECRET} for an X.509
+key the export format will be changed to PKCS#12 which also includes
+the certificate.  This flag may not be used with OpenPGP.
+
 @end table
 
 
@@ -3480,7 +4114,7 @@ for the context @var{ctx}, or, if that is not set, by the encoding
 specified for @var{keydata}.
 
 The keys to export are taken form the @code{NULL} terminated array
-@var{keys}.  Only keys of the the currently selected protocol of
+@var{keys}.  Only keys of the currently selected protocol of
 @var{ctx} which do have a fingerprint set are considered for export.
 Other keys specified by the @var{keys} are ignored.  In particular
 OpenPGP keys retrieved via an external key listing are not included.
@@ -3513,7 +4147,7 @@ are reported by the crypto engine support routines.
 @cindex key ring, import to
 
 Importing keys means the same as running @command{gpg} with the command
-@option{--import}. 
+@option{--import}.
 
 
 @deftypefun gpgme_error_t gpgme_op_import (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}})
@@ -3553,7 +4187,7 @@ permanent which have been retrieved from an external source (i.e. using
 for the usual workaround of exporting and then importing a key to make
 an X.509 key permanent.}
 
-Only keys of the the currently selected protocol of @var{ctx} are
+Only keys of the currently selected protocol of @var{ctx} are
 considered for import.  Other keys specified by the @var{keys} are
 ignored.  As of now all considered keys must have been retrieved using
 the same method, that is the used key listing mode must be identical.
@@ -3640,34 +4274,34 @@ The number of keys without user ID.
 @item int imported
 The total number of imported keys.
 
-@item imported_rsa
+@item int imported_rsa
 The number of imported RSA keys.
 
-@item unchanged
+@item int unchanged
 The number of unchanged keys.
 
-@item new_user_ids
+@item int new_user_ids
 The number of new user IDs.
 
-@item new_sub_keys
+@item int new_sub_keys
 The number of new sub keys.
 
-@item new_signatures
+@item int new_signatures
 The number of new signatures.
 
-@item new_revocations
+@item int new_revocations
 The number of new revocations.
 
-@item secret_read
+@item int secret_read
 The total number of secret keys read.
 
-@item secret_imported
+@item int secret_imported
 The number of imported secret keys.
 
-@item secret_unchanged
+@item int secret_unchanged
 The number of unchanged secret keys.
 
-@item not_imported
+@item int not_imported
 The number of keys not imported.
 
 @item gpgme_import_status_t imports
@@ -3686,24 +4320,6 @@ successfully.  The returned pointer is only valid until the next
 operation is started on the context.
 @end deftypefun
 
-The following interface is deprecated and only provided for backward
-compatibility.  Don't use it.  It will be removed in a future version
-of @acronym{GPGME}.
-
-@deftypefun gpgme_error_t gpgme_op_import_ext (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}}, @w{int *@var{nr}})
-The function @code{gpgme_op_import_ext} is equivalent to:
-
-@example
-  gpgme_error_t err = gpgme_op_import (ctx, keydata);
-  if (!err)
-    @{
-      gpgme_import_result_t result = gpgme_op_import_result (ctx);
-      *nr = result->considered;
-    @}
-@end example
-@end deftypefun
-
-
 @node Deleting Keys
 @subsection Deleting Keys
 @cindex key, delete
@@ -3736,7 +4352,7 @@ operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
 
 
 @node Changing Passphrases
-@subsection  Changing Passphrases
+@subsection Changing Passphrases
 @cindex passphrase, change
 
 @deftypefun gpgme_error_t gpgme_op_passwd      @
@@ -3770,27 +4386,104 @@ could not be started.
 @end deftypefun
 
 
+@c
+@c  CHANGING TOFU DATA
+@c
+@node Changing TOFU Data
+@subsection Changing TOFU Data
+@cindex validity, TOFU
+
+The OpenPGP engine features a Trust-On-First-Use (TOFU) key validation
+model.  For resolving clonflics it is necessary to declare the policy
+for a key.  See the GnuPG manual for details on the TOFU
+implementation.
+
+@deftp {Data type} {enum gpgme_tofu_policy_t}
+@tindex gpgme_tofu_policy_t
+The @code{gpgme_tofu_policy_t} type specifies the set of possible
+policy values that are supported by @acronym{GPGME}:
+
+@table @code
+@item GPGME_TOFU_POLICY_AUTO
+Set the policy to ``auto''.
+@item GPGME_TOFU_POLICY_GOOD
+Set the policy to ``goog''.
+@item GPGME_TOFU_POLICY_BAD
+Set the policy to ``bad''.
+@item GPGME_TOFU_POLICY_ASK
+Set the policy to ``ask''.
+@item GPGME_TOFU_POLICY_UNKNOWN
+Set the policy to ``unknown''.
+@end table
+
+@end deftp
+
+To change the policy for a key the following functions can be used:
+
+@deftypefun gpgme_error_t gpgme_op_tofu_policy @
+             (@w{gpgme_ctx_t @var{ctx}},       @
+              @w{const gpgme_key_t @var{key}}, @
+              @w{gpgme_tofu_policy_t @var{policy}})
+
+The function @code{gpgme_op_tofu_policy} changes the TOFU policy of
+@var{key}.  The valid values for @var{policy} are listed above.  As of
+now this function does only work for OpenPGP and requires at least
+version 2.1.10 of GnuPG.
+
+The function returns zero on success, @code{GPG_ERR_NOT_SUPPORTED} if
+the engine does not support the command, or a bunch of other error
+codes.
+
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_tofu_policy_start @
+             (@w{gpgme_ctx_t @var{ctx}},       @
+              @w{const gpgme_key_t @var{key}}, @
+              @w{gpgme_tofu_policy_t @var{policy}})
+
+The function @code{gpgme_op_tofu_policy_start} initiates a
+@code{gpgme_op_tofu_policy} operation.    It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns @code{0} if the operation was started successfully,
+and an error code if one of the arguments is not valid or the oepration
+could not be started.
+
+@end deftypefun
+
+
 @node Advanced Key Editing
 @subsection Advanced Key Editing
 @cindex key, edit
 
-@deftp {Data type} {gpgme_error_t (*gpgme_edit_cb_t) (@w{void *@var{handle}}, @w{gpgme_status_code_t @var{status}}, @w{const char *@var{args}}, @w{int @var{fd}})}
-@tindex gpgme_edit_cb_t
-The @code{gpgme_edit_cb_t} type is the type of functions which
-@acronym{GPGME} calls if it a key edit operation is on-going.  The
-status code @var{status} and the argument line @var{args} are passed
-through by @acronym{GPGME} from the crypto engine.  The file
-descriptor @var{fd} is -1 for normal status messages.  If @var{status}
-indicates a command rather than a status message, the response to the
-command should be written to @var{fd}.  The @var{handle} is provided
-by the user at start of operation.
-
-The function should return @code{GPG_ERR_NO_ERROR} or an error value.
+@deftp {Data type} {gpgme_error_t (*gpgme_interact_cb_t) @
+   (@w{void *@var{handle}}, @
+    @w{const char *@var{status}}, @
+    @w{const char *@var{args}}, @
+    @w{int @var{fd}})}
+@tindex gpgme_interact_cb_t
+The @code{gpgme_interact_cb_t} type is the type of functions which
+@acronym{GPGME} calls if it a key interact operation is on-going.  The
+status keyword @var{status} and the argument line @var{args} are
+passed through by @acronym{GPGME} from the crypto engine.  An empty
+string represents EOF.  The file descriptor @var{fd} is -1 for normal
+status messages.  If @var{status} indicates a command rather than a
+status message, the response to the command should be written to
+@var{fd}.  The @var{handle} is provided by the user at start of
+operation.
+
+The function should return @code{GPG_ERR_FALSE} if it did not handle
+the status code, @code{0} for success, or any other error value.
 @end deftp
 
-@deftypefun gpgme_error_t gpgme_op_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
-The function @code{gpgme_op_edit} processes the key @var{KEY}
-interactively, using the edit callback function @var{FNC} with the
+@deftypefun gpgme_error_t gpgme_op_interact (@w{gpgme_ctx_t @var{ctx}}, @
+   @w{gpgme_key_t @var{key}}, @
+   @w{unsigned int @var{flags}}, @
+   @w{gpgme_interact_cb_t @var{fnc}}, @
+   @w{void *@var{handle}}, @
+   @w{gpgme_data_t @var{out}})
+The function @code{gpgme_op_interact} processes the key @var{KEY}
+interactively, using the interact callback function @var{FNC} with the
 handle @var{HANDLE}.  The callback is invoked for every status and
 command request from the crypto engine.  The output of the crypto
 engine is written to the data object @var{out}.
@@ -3799,39 +4492,40 @@ Note that the protocol between the callback function and the crypto
 engine is specific to the crypto engine and no further support in
 implementing this protocol correctly is provided by @acronym{GPGME}.
 
-The function returns the error code @code{GPG_ERR_NO_ERROR} if the
-edit operation completes successfully, @code{GPG_ERR_INV_VALUE} if
-@var{ctx} or @var{key} is not a valid pointer, and any error returned
-by the crypto engine or the edit callback handler.
-@end deftypefun
-
-@deftypefun gpgme_error_t gpgme_op_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
-The function @code{gpgme_op_edit_start} initiates a
-@code{gpgme_op_edit} operation.  It can be completed by calling
-@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+@var{flags} modifies the behaviour of the function; the only defined
+bit value is:
 
-The function returns the error code @code{GPG_ERR_NO_ERROR} if the
-operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
-@var{ctx} or @var{key} is not a valid pointer.
-@end deftypefun
+@table @code
+@item GPGME_INTERACT_CARD
+This is used for smartcard based keys and uses gpg’s
+@code{--card-edit} command.
 
+@end table
 
-@deftypefun gpgme_error_t gpgme_op_card_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
-The function @code{gpgme_op_card_edit} is analogous to
-@code{gpgme_op_edit}, but should be used to process the smart card corresponding to the key @var{key}.
+The function returns @code{0} if the edit operation completes
+successfully, @code{GPG_ERR_INV_VALUE} if @var{ctx} or @var{key} is
+not a valid pointer, and any error returned by the crypto engine or
+the edit callback handler.
 @end deftypefun
 
-@deftypefun gpgme_error_t gpgme_op_card_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
-The function @code{gpgme_op_card_edit_start} initiates a
-@code{gpgme_op_card_edit} operation.  It can be completed by calling
+
+@deftypefun gpgme_error_t gpgme_op_interact_start (@w{gpgme_ctx_t @var{ctx}}, @
+   @w{gpgme_key_t @var{key}}, @
+   @w{unsigned int @var{flags}}, @
+   @w{gpgme_interact_cb_t @var{fnc}}, @
+   @w{void *@var{handle}}, @
+   @w{gpgme_data_t @var{out}})
+The function @code{gpgme_op_interact_start} initiates a
+@code{gpgme_op_interact} operation.  It can be completed by calling
 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
 
-The function returns the error code @code{GPG_ERR_NO_ERROR} if the
-operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
-@var{ctx} or @var{key} is not a valid pointer.
+The function returns @code{0} if the operation was started
+successfully, and @code{GPG_ERR_INV_VALUE} if @var{ctx} or @var{key}
+is not a valid pointer.
 @end deftypefun
 
 
+
 @node Trust Item Management
 @section Trust Item Management
 @cindex trust item
@@ -3866,7 +4560,6 @@ The user name if @code{type} is 2.
 
 @menu
 * Listing Trust Items::           Browsing the list of available trust items.
-* Information About Trust Items:: Requesting information about trust items.
 * Manipulating Trust Items::      Operations on trust items.
 @end menu
 
@@ -3923,47 +4616,6 @@ time during the operation there was not enough memory available.
 @end deftypefun
 
 
-@node Information About Trust Items
-@subsection Information About Trust Items
-@cindex trust item, information about
-@cindex trust item, attributes
-@cindex attributes, of a trust item
-
-The following interfaces are deprecated and only provided for backward
-compatibility.  Don't use them.  They will be removed in a future
-version of @acronym{GPGME}.
-
-Trust items have attributes which can be queried using the interfaces
-below.  The attribute identifiers are shared with those for key
-attributes.  @xref{Information About Keys}.
-
-@deftypefun {const char *} gpgme_trust_item_get_string_attr (@w{gpgme_trust_item_t @var{item}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
-The function @code{gpgme_trust_item_get_string_attr} returns the value
-of the string-representable attribute @var{what} of trust item
-@var{item}.  The arguments @var{idx} and @var{reserved} are reserved
-for later use and should be @code{0} and @code{NULL} respectively.
-
-The string returned is only valid as long as the key is valid.
-
-The function returns @code{0} if an attribute can't be returned as a
-string, @var{key} is not a valid pointer, @var{idx} out of range,
-or @var{reserved} not @code{NULL}.
-@end deftypefun
-
-@deftypefun int gpgme_trust_item_get_int_attr (@w{gpgme_trust_item_t @var{item}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
-The function @code{gpgme_trust_item_get_int_attr} returns the value of
-the number-representable attribute @var{what} of trust item
-@var{item}.  If the attribute occurs more than once in the trust item,
-the index is specified by @var{idx}.  However, currently no such
-attribute exists, so @var{idx} should be @code{0}.  The argument
-@var{reserved} is reserved for later use and should be @code{NULL}.
-
-The function returns @code{0} if the attribute can't be returned as a
-number, @var{key} is not a valid pointer, @var{idx} out of range,
-or @var{reserved} not @code{NULL}.
-@end deftypefun
-
-
 @node Manipulating Trust Items
 @subsection Manipulating Trust Items
 @cindex trust item, manipulation
@@ -3981,16 +4633,6 @@ released.
 @end deftypefun
 
 
-The following interface is deprecated and only provided for backward
-compatibility.  Don't use it.  It will be removed in a future version
-of @acronym{GPGME}.
-
-@deftypefun void gpgme_trust_item_release (@w{gpgme_trust_item_t @var{item}})
-The function @code{gpgme_trust_item_release} is an alias for
-@code{gpgme_trust_item_unref}.
-@end deftypefun
-
-
 @node Crypto Operations
 @section Crypto Operations
 @cindex cryptographic operation
@@ -4073,9 +4715,6 @@ or @code{NULL} if this is the last element.
 @item gpgme_pubkey_algo_t
 The public key algorithm used in the encryption.
 
-@item unsigned int wrong_key_usage : 1
-This is true if the key was not used according to its policy.
-
 @item char *keyid
 This is the key ID of the key (in hexadecimal digits) used as
 recipient.
@@ -4101,7 +4740,7 @@ algorithm that is not supported.
 @item unsigned int wrong_key_usage : 1
 This is true if the key was not used according to its policy.
 
-@item gpgme_recipient_t recipient
+@item gpgme_recipient_t recipients
 This is a linked list of recipients to which this message was encrypted.
 
 @item char *file_name
@@ -4265,16 +4904,16 @@ The defined bits are:
   Can't verify due to a missing key or certificate.
 
   @item GPGME_SIGSUM_CRL_MISSING
-  The CRL (or an equivalent mechanism) is not available. 
+  The CRL (or an equivalent mechanism) is not available.
 
   @item GPGME_SIGSUM_CRL_TOO_OLD
   Available CRL is too old.
 
   @item GPGME_SIGSUM_BAD_POLICY
-  A policy requirement was not met. 
+  A policy requirement was not met.
 
   @item GPGME_SIGSUM_SYS_ERROR
-  A system error occured. 
+  A system error occured.
   @end table
 
 @item char *fpr
@@ -4339,7 +4978,7 @@ Values are:
   @item 0
         No PKA information available or verification not possible.
   @item 1
-        PKA verification failed. 
+        PKA verification failed.
   @item 2
         PKA verification succeeded.
   @item 3
@@ -4369,6 +5008,16 @@ The public key algorithm used to create this signature.
 
 @item gpgme_hash_algo_t
 The hash algorithm used to create this signature.
+
+@item char *pka_address
+The mailbox from the PKA information or @code{NULL}.
+
+@item gpgme_key_t key
+An object describing the key used to create the signature.  This key
+object may be incomplete in that it only conveys information
+availabale directly with a signature.  It may also be @code{NULL} if
+such information is not readily available.
+
 @end table
 @end deftp
 
@@ -4405,294 +5054,62 @@ the context.
 @end deftypefun
 
 
-The following interfaces are deprecated and only provided for backward
-compatibility.  Don't use them.  They will be removed in a future
-version of @acronym{GPGME}.
-
-@deftp {Data type} {enum gpgme_sig_stat_t}
-@tindex gpgme_sig_stat_t
-The @code{gpgme_sig_stat_t} type holds the result of a signature check, or
-the combined result of all signatures.  The following results are
-possible:
+@node Decrypt and Verify
+@subsection Decrypt and Verify
+@cindex decryption and verification
+@cindex verification and decryption
+@cindex signature check
+@cindex cryptographic operation, decryption and verification
 
-@table @code
-@item GPGME_SIG_STAT_NONE
-This status should not occur in normal operation.
+@deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
+The function @code{gpgme_op_decrypt_verify} decrypts the ciphertext in
+the data object @var{cipher} and stores it into the data object
+@var{plain}.  If @var{cipher} contains signatures, they will be
+verified.
 
-@item GPGME_SIG_STAT_GOOD
-This status indicates that the signature is valid.  For the combined
-result this status means that all signatures are valid.
+After the operation completed, @code{gpgme_op_decrypt_result} and
+@code{gpgme_op_verify_result} can be used to retrieve more information
+about the signatures.
 
-@item GPGME_SIG_STAT_GOOD_EXP
-This status indicates that the signature is valid but expired.  For
-the combined result this status means that all signatures are valid
-and expired.
+If the error code @code{GPG_ERR_NO_DATA} is returned, @var{cipher}
+does not contain any data to decrypt.  However, it might still be
+signed.  The information about detected signatures is available with
+@code{gpgme_op_verify_result} in this case.
 
-@item GPGME_SIG_STAT_GOOD_EXPKEY
-This status indicates that the signature is valid but the key used to
-verify the signature has expired.  For the combined result this status
-means that all signatures are valid and all keys are expired.
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+ciphertext could be decrypted successfully, @code{GPG_ERR_INV_VALUE}
+if @var{ctx}, @var{cipher} or @var{plain} is not a valid pointer,
+@code{GPG_ERR_NO_DATA} if @var{cipher} does not contain any data to
+decrypt, @code{GPG_ERR_DECRYPT_FAILED} if @var{cipher} is not a valid
+cipher text, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the
+secret key could not be retrieved, and passes through any errors that
+are reported by the crypto engine support routines.
+@end deftypefun
 
-@item GPGME_SIG_STAT_BAD
-This status indicates that the signature is invalid.  For the combined
-result this status means that all signatures are invalid.
+@deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
+The function @code{gpgme_op_decrypt_verify_start} initiates a
+@code{gpgme_op_decrypt_verify} operation.  It can be completed by
+calling @code{gpgme_wait} on the context.  @xref{Waiting For
+Completion}.
 
-@item GPGME_SIG_STAT_NOKEY
-This status indicates that the signature could not be verified due to
-a missing key.  For the combined result this status means that all
-signatures could not be checked due to missing keys.
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
+@var{ctx}, @var{cipher}, @var{plain} or @var{r_stat} is not a valid
+pointer, and @code{GPG_ERR_NO_DATA} if @var{cipher} does not contain
+any data to decrypt.
+@end deftypefun
 
-@item GPGME_SIG_STAT_NOSIG
-This status indicates that the signature data provided was not a real
-signature.
 
-@item GPGME_SIG_STAT_ERROR
-This status indicates that there was some other error which prevented
-the signature verification.
+@node Sign
+@subsection Sign
+@cindex signature, creation
+@cindex sign
+@cindex cryptographic operation, signing
 
-@item GPGME_SIG_STAT_DIFF
-For the combined result this status means that at least two signatures
-have a different status.  You can get each key's status with
-@code{gpgme_get_sig_status}.
-@end table
-@end deftp
-
-@deftypefun {const char *} gpgme_get_sig_status (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_sig_stat_t *@var{r_stat}}, @w{time_t *@var{r_created}})
-The function @code{gpgme_get_sig_status} is equivalent to:
-@example
-  gpgme_verify_result_t result;
-  gpgme_signature_t sig;
-
-  result = gpgme_op_verify_result (ctx);
-  sig = result->signatures;
-
-  while (sig && idx)
-    @{
-      sig = sig->next;
-      idx--;
-    @}
-  if (!sig || idx)
-    return NULL;
-
-  if (r_stat)
-    @{
-      switch (gpg_err_code (sig->status))
-       @{
-       case GPG_ERR_NO_ERROR:
-         *r_stat = GPGME_SIG_STAT_GOOD;
-         break;
-         
-       case GPG_ERR_BAD_SIGNATURE:
-         *r_stat = GPGME_SIG_STAT_BAD;
-         break;
-         
-       case GPG_ERR_NO_PUBKEY:
-         *r_stat = GPGME_SIG_STAT_NOKEY;
-         break;
-         
-       case GPG_ERR_NO_DATA:
-         *r_stat = GPGME_SIG_STAT_NOSIG;
-         break;
-         
-       case GPG_ERR_SIG_EXPIRED:
-         *r_stat = GPGME_SIG_STAT_GOOD_EXP;
-         break;
-         
-       case GPG_ERR_KEY_EXPIRED:
-         *r_stat = GPGME_SIG_STAT_GOOD_EXPKEY;
-         break;
-         
-       default:
-         *r_stat = GPGME_SIG_STAT_ERROR;
-         break;
-       @}
-    @}
-  if (r_created)
-    *r_created = sig->timestamp;
-  return sig->fpr;
-@end example
-@end deftypefun
-
-@deftypefun {const char *} gpgme_get_sig_string_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{what}}, @w{int @var{whatidx}})
-The function @code{gpgme_get_sig_string_attr} is equivalent to:
-@example
-  gpgme_verify_result_t result;
-  gpgme_signature_t sig;
-
-  result = gpgme_op_verify_result (ctx);
-  sig = result->signatures;
-
-  while (sig && idx)
-    @{
-      sig = sig->next;
-      idx--;
-    @}
-  if (!sig || idx)
-    return NULL;
-
-  switch (what)
-    @{
-    case GPGME_ATTR_FPR:
-      return sig->fpr;
-
-    case GPGME_ATTR_ERRTOK:
-      if (whatidx == 1)
-        return sig->wrong_key_usage ? "Wrong_Key_Usage" : "";
-      else
-       return "";
-    default:
-      break;
-    @}
-
-  return NULL;
-@end example
-@end deftypefun
-
-@deftypefun {const char *} gpgme_get_sig_ulong_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{waht}}, @w{int @var{whatidx}})
-The function @code{gpgme_get_sig_ulong_attr} is equivalent to:
-@example
-  gpgme_verify_result_t result;
-  gpgme_signature_t sig;
-
-  result = gpgme_op_verify_result (ctx);
-  sig = result->signatures;
-
-  while (sig && idx)
-    @{
-      sig = sig->next;
-      idx--;
-    @}
-  if (!sig || idx)
-    return 0;
-
-  switch (what)
-    @{
-    case GPGME_ATTR_CREATED:
-      return sig->timestamp;
-
-    case GPGME_ATTR_EXPIRE:
-      return sig->exp_timestamp;
-
-    case GPGME_ATTR_VALIDITY:
-      return (unsigned long) sig->validity;
-
-    case GPGME_ATTR_SIG_STATUS:
-      switch (sig->status)
-       @{
-       case GPG_ERR_NO_ERROR:
-         return GPGME_SIG_STAT_GOOD;
-         
-       case GPG_ERR_BAD_SIGNATURE:
-         return GPGME_SIG_STAT_BAD;
-         
-       case GPG_ERR_NO_PUBKEY:
-         return GPGME_SIG_STAT_NOKEY;
-         
-       case GPG_ERR_NO_DATA:
-         return GPGME_SIG_STAT_NOSIG;
-         
-       case GPG_ERR_SIG_EXPIRED:
-         return GPGME_SIG_STAT_GOOD_EXP;
-         
-       case GPG_ERR_KEY_EXPIRED:
-         return GPGME_SIG_STAT_GOOD_EXPKEY;
-         
-       default:
-         return GPGME_SIG_STAT_ERROR;
-       @}
-
-    case GPGME_ATTR_SIG_SUMMARY:
-      return sig->summary;
-
-    default:
-      break;
-    @}
-  return 0;
-@end example
-@end deftypefun
-
-@deftypefun {const char *} gpgme_get_sig_key (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_key_t *@var{r_key}})
-The function @code{gpgme_get_sig_key} is equivalent to:
-
-@example
-  gpgme_verify_result_t result;
-  gpgme_signature_t sig;
-
-  result = gpgme_op_verify_result (ctx);
-  sig = result->signatures;
-
-  while (sig && idx)
-    @{
-      sig = sig->next;
-      idx--;
-    @}
-  if (!sig || idx)
-    return gpg_error (GPG_ERR_EOF);
-
-  return gpgme_get_key (ctx, sig->fpr, r_key, 0);
-@end example
-@end deftypefun
-
-
-@node Decrypt and Verify
-@subsection Decrypt and Verify
-@cindex decryption and verification
-@cindex verification and decryption
-@cindex signature check
-@cindex cryptographic operation, decryption and verification
-
-@deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
-The function @code{gpgme_op_decrypt_verify} decrypts the ciphertext in
-the data object @var{cipher} and stores it into the data object
-@var{plain}.  If @var{cipher} contains signatures, they will be
-verified.
-
-After the operation completed, @code{gpgme_op_decrypt_result} and
-@code{gpgme_op_verify_result} can be used to retrieve more information
-about the signatures.
-
-If the error code @code{GPG_ERR_NO_DATA} is returned, @var{cipher}
-does not contain any data to decrypt.  However, it might still be
-signed.  The information about detected signatures is available with
-@code{gpgme_op_verify_result} in this case.
-
-The function returns the error code @code{GPG_ERR_NO_ERROR} if the
-ciphertext could be decrypted successfully, @code{GPG_ERR_INV_VALUE}
-if @var{ctx}, @var{cipher} or @var{plain} is not a valid pointer,
-@code{GPG_ERR_NO_DATA} if @var{cipher} does not contain any data to
-decrypt, @code{GPG_ERR_DECRYPT_FAILED} if @var{cipher} is not a valid
-cipher text, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the
-secret key could not be retrieved, and passes through any errors that
-are reported by the crypto engine support routines.
-@end deftypefun
-
-@deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
-The function @code{gpgme_op_decrypt_verify_start} initiates a
-@code{gpgme_op_decrypt_verify} operation.  It can be completed by
-calling @code{gpgme_wait} on the context.  @xref{Waiting For
-Completion}.
-
-The function returns the error code @code{GPG_ERR_NO_ERROR} if the
-operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
-@var{ctx}, @var{cipher}, @var{plain} or @var{r_stat} is not a valid
-pointer, and @code{GPG_ERR_NO_DATA} if @var{cipher} does not contain
-any data to decrypt.
-@end deftypefun
-
-
-@node Sign
-@subsection Sign
-@cindex signature, creation
-@cindex sign
-@cindex cryptographic operation, signing
-
-A signature can contain signatures by one or more keys.  The set of
-keys used to create a signatures is contained in a context, and is
-applied to all following signing operations in this context (until the
-set is changed).
+A signature can contain signatures by one or more keys.  The set of
+keys used to create a signatures is contained in a context, and is
+applied to all following signing operations in this context (until the
+set is changed).
 
 @menu
 * Selecting Signers::             How to choose the keys to sign with.
@@ -4706,6 +5123,11 @@ set is changed).
 @cindex signature, selecting signers
 @cindex signers, selecting
 
+The key or the keys used to create a signature are stored in the
+context.  The following functions can be used to manipulate this list.
+If no signer has been set into the context a default key is used for
+signing.
+
 @deftypefun void gpgme_signers_clear (@w{gpgme_ctx_t @var{ctx}})
 The function @code{gpgme_signers_clear} releases a reference for each
 key on the signers list and removes the list of signers from the
@@ -4721,6 +5143,11 @@ list of signers in the context @var{ctx}.
 Calling this function acquires an additional reference for the key.
 @end deftypefun
 
+@deftypefun @w{unsigned int} gpgme_signers_count (@w{const gpgme_ctx_t @var{ctx}})
+The function @code{gpgme_signers_count} returns the number of signer keys in
+the context @var{ctx}.
+@end deftypefun
+
 @deftypefun gpgme_key_t gpgme_signers_enum (@w{const gpgme_ctx_t @var{ctx}}, @w{int @var{seq}})
 The function @code{gpgme_signers_enum} returns the @var{seq}th key in
 the list of signers in the context @var{ctx}.  An additional reference
@@ -4800,10 +5227,10 @@ list, or @code{NULL} if this is the last element.
 @item gpgme_sig_mode_t type
 The type of this signature.
 
-@item gpgme_pubkey_algo_t
+@item gpgme_pubkey_algo_t pubkey_algo
 The public key algorithm used to create this signature.
 
-@item gpgme_hash_algo_t
+@item gpgme_hash_algo_t hash_algo
 The hash algorithm used to create this signature.
 
 @item unsigned int sig_class
@@ -4924,7 +5351,7 @@ ciphertext created is determined by the @acronym{ASCII} armor (or, if
 that is not set, by the encoding specified for @var{cipher}) and the
 text mode attributes set for the context @var{ctx}.
 
-@var{key} must be a @code{NULL}-terminated array of keys.  The user
+@var{recp} must be a @code{NULL}-terminated array of keys.  The user
 must keep references for all keys during the whole duration of the
 call (but see @code{gpgme_op_encrypt_start} for the requirements with
 the asynchronous variant).
@@ -4944,6 +5371,27 @@ The @code{GPGME_ENCRYPT_NO_ENCRYPT_TO} symbol specifies that no
 default or hidden default recipients as configured in the crypto
 backend should be included.  This can be useful for managing different
 user profiles.
+
+@item GPGME_ENCRYPT_NO_COMPRESS
+The @code{GPGME_ENCRYPT_NO_COMPRESS} symbol specifies that the
+plaintext shall not be compressed before it is encrypted.  This is
+in some cases useful if the length of the encrypted message
+may reveal information about the plaintext.
+
+@item GPGME_ENCRYPT_PREPARE
+@itemx GPGME_ENCRYPT_EXPECT_SIGN
+The @code{GPGME_ENCRYPT_PREPARE} symbol is used with the UI Server
+protocol to prepare an encryption (i.e. sending the
+@code{PREP_ENCRYPT} command).  With the
+@code{GPGME_ENCRYPT_EXPECT_SIGN} symbol the UI Server is advised to
+also expect a sign command.
+
+@item GPGME_ENCRYPT_SYMMETRIC
+The @code{GPGME_ENCRYPT_SYMMETRIC} symbol specifies that the
+output should be additionally encrypted symmetically even
+if recipients are provided. This feature is only supported for
+for the OpenPGP crypto engine.
+
 @end table
 
 If @code{GPG_ERR_UNUSABLE_PUBKEY} is returned, some recipients in
@@ -5035,38 +5483,177 @@ pointer.
 @end deftypefun
 
 
-@node Run Control
-@section Run Control
-@cindex run control
-@cindex cryptographic operation, running
-
-@acronym{GPGME} supports running operations synchronously and
-asynchronously.  You can use asynchronous operation to set up a
-context up to initiating the desired operation, but delay performing
-it to a later point.
+@node Miscellaneous
+@section Miscellaneous operations
 
-Furthermore, you can use an external event loop to control exactly
-when @acronym{GPGME} runs.  This ensures that @acronym{GPGME} only
-runs when necessary and also prevents it from blocking for a long
-time.
+Here are some support functions which are sometimes useful.
 
 @menu
-* Waiting For Completion::        Waiting until an operation is completed.
-* Using External Event Loops::    Advanced control over what happens when.
-* Cancellation::                  How to end pending operations prematurely.
+* Running other Programs::      Running other Programs
+* Using the Assuan protocol::   Using the Assuan protocol
 @end menu
 
 
-@node Waiting For Completion
-@subsection Waiting For Completion
-@cindex cryptographic operation, wait for
-@cindex wait for completion
+@node Running other Programs
+@subsection Running other Programs
 
-@deftypefun gpgme_ctx_t gpgme_wait (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_error_t *@var{status}}, @w{int @var{hang}})
-The function @code{gpgme_wait} continues the pending operation within
-the context @var{ctx}.  In particular, it ensures the data exchange
-between @acronym{GPGME} and the crypto backend and watches over the
-run time status of the backend process.
+GPGME features an internal subsystem to run the actual backend
+engines.  Along with data abstraction object this subsystem can be
+used to run arbitrary simple programs which even need not be related
+to cryptographic features.  It may for example be used to run tools
+which are part of the GnuPG system but are not directly accessible
+with the GPGME API.
+
+
+@deftypefun gpgme_error_t gpgme_op_spawn @
+            (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{file}}, @
+             @w{const char *@var{argv}[]}, @w{gpgme_data_t @var{datain}}, @
+             @w{gpgme_data_t @var{dataout}}, @w{gpgme_data_t @var{dataerr}}, @
+             @w{unsigned int @var{flags}})
+
+The function @code{gpgme_op_spawn} runs the program @var{file} with
+the arguments taken from the NULL terminated array @var{argv}.  If no
+arguments are required @var{argv} may be given as @code{NULL}.  In the
+latter case or if @code{argv[0]} is the empty string, GPGME uses the
+basename of @var{file} for @code{argv[0]}.  The file descriptors
+@code{stdin}, @code{stdout}, and @code{stderr} are connected to the
+data objects @var{datain}, @var{dataout}, and @var{dataerr}.  If NULL
+is passed for one of these data objects the corresponding file
+descriptor is connected to @file{/dev/null}.
+
+The value in @var{flags} is a bitwise-or combination of one or
+multiple of the following bit values:
+
+@table @code
+@item GPGME_SPAWN_DETACHED
+Under Windows this flag inhibits the allocation of a new console for
+the program.  This is useful for a GUI application which needs to call
+a command line helper tool.
+@item GPGME_SPAWN_ALLOW_SET_FG
+Under Windows this flag allows the called program to put itself into
+the foreground.
+@end table
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_spawn_start @
+            (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{file}}, @
+             @w{const char *@var{argv}[]}, @w{gpgme_data_t @var{datain}}, @
+             @w{gpgme_data_t @var{dataout}}, @w{gpgme_data_t @var{dataerr}}, @
+             @w{unsigned int @var{flags}})
+
+This is the asynchronous variant of @code{gpgme_op_spawn}.
+@end deftypefun
+
+
+@node Using the Assuan protocol
+@subsection Using the Assuan protocol
+
+The Assuan protocol can be used to talk to arbitrary Assuan servers.
+By default it is connected to the GnuPG agent, but it may be connected
+to arbitrary servers by using @code{gpgme_ctx_set_engine_info},
+passing the location of the servers socket as @var{file_name}
+argument, and an empty string as @var{home_dir} argument.
+
+The Assuan protocol functions use three kinds of callbacks to transfer
+data:
+
+@deftp {Data type} {gpgme_error_t (*gpgme_assuan_data_cb_t) @
+       (@w{void *@var{opaque}}, @w{const void *@var{data}}, @
+        @w{size_t @var{datalen}})}
+
+This callback receives any data sent by the server.  @var{opaque} is
+the pointer passed to @code{gpgme_op_assuan_transact_start},
+@var{data} of length @var{datalen} refers to the data sent.
+@end deftp
+
+@deftp {Data type} {gpgme_error_t (*gpgme_assuan_inquire_cb_t) @
+       (@w{void *@var{opaque}}, @w{const char *@var{name}}, @
+        @w{const char *@var{args}}, @w{gpgme_data_t *@var{r_data}})}
+
+This callback is used to provide additional data to the Assuan server.
+@var{opaque} is the pointer passed to
+@code{gpgme_op_assuan_transact_start}, @var{name} and @var{args}
+specify what kind of data the server requested, and @var{r_data} is
+used to return the actual data.
+
+Note: Returning data is currently not implemented in @acronym{GPGME}.
+@end deftp
+
+@deftp {Data type} {gpgme_error_t (*gpgme_assuan_status_cb_t) @
+       (@w{void *@var{opaque}}, @w{const char *@var{status}}, @
+        @w{const char *@var{args}})}
+
+This callback receives any status lines sent by the server.
+@var{opaque} is the pointer passed to
+@code{gpgme_op_assuan_transact_start}, @var{status} and @var{args}
+denote the status update sent.
+@end deftp
+
+@deftypefun gpgme_error_t gpgme_op_assuan_transact_start @
+            (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{command}}, @
+             @w{gpgme_assuan_data_cb_t @var{data_cb}}, @
+             @w{void * @var{data_cb_value}}, @
+             @w{gpgme_assuan_inquire_cb_t @var{inquire_cb}}, @
+             @w{void * @var{inquire_cb_value}}, @
+             @w{gpgme_assuan_status_cb_t @var{status_cb}}, @
+             @w{void * @var{status_cb_value}})
+
+Send the Assuan @var{command} and return results via the callbacks.
+Any callback may be @code{NULL}.  The result of the operation may be
+retrieved using @code{gpgme_wait_ext}.
+
+Asynchronous variant.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_assuan_transact_ext @
+            (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{command}}, @
+             @w{gpgme_assuan_data_cb_t @var{data_cb}}, @
+             @w{void * @var{data_cb_value}}, @
+             @w{gpgme_assuan_inquire_cb_t @var{inquire_cb}}, @
+             @w{void * @var{inquire_cb_value}}, @
+             @w{gpgme_assuan_status_cb_t @var{status_cb}}, @
+             @w{void * @var{status_cb_value}}, @
+             @w{gpgme_error_t *@var{op_err}})
+
+Send the Assuan @var{command} and return results via the callbacks.
+The result of the operation is returned in @var{op_err}.
+
+Synchronous variant.
+@end deftypefun
+
+
+@node Run Control
+@section Run Control
+@cindex run control
+@cindex cryptographic operation, running
+
+@acronym{GPGME} supports running operations synchronously and
+asynchronously.  You can use asynchronous operation to set up a
+context up to initiating the desired operation, but delay performing
+it to a later point.
+
+Furthermore, you can use an external event loop to control exactly
+when @acronym{GPGME} runs.  This ensures that @acronym{GPGME} only
+runs when necessary and also prevents it from blocking for a long
+time.
+
+@menu
+* Waiting For Completion::        Waiting until an operation is completed.
+* Using External Event Loops::    Advanced control over what happens when.
+* Cancellation::                  How to end pending operations prematurely.
+@end menu
+
+
+@node Waiting For Completion
+@subsection Waiting For Completion
+@cindex cryptographic operation, wait for
+@cindex wait for completion
+
+@deftypefun gpgme_ctx_t gpgme_wait (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_error_t *@var{status}}, @w{int @var{hang}})
+The function @code{gpgme_wait} continues the pending operation within
+the context @var{ctx}.  In particular, it ensures the data exchange
+between @acronym{GPGME} and the crypto backend and watches over the
+run time status of the backend process.
 
 If @var{hang} is true, the function does not return until the
 operation is completed or cancelled.  Otherwise the function will not
@@ -5215,9 +5802,9 @@ callback handlers must not be run before this event is signalled.
 @item GPGME_EVENT_DONE
 The operation is finished, the last I/O callback for this operation
 was removed.  The accompanying @var{type_data} points to a
-@code{gpgme_error_t} variable that contains the status of the operation
-that finished.  This event is signalled after the last I/O callback
-has been removed.
+@code{struct gpgme_io_event_done_data} variable that contains the
+status of the operation that finished.  This event is signalled after
+the last I/O callback has been removed.
 
 @item GPGME_EVENT_NEXT_KEY
 In a @code{gpgme_op_keylist_start} operation, the next key was
@@ -5255,7 +5842,7 @@ list of possible @code{gpgme_event_io_t} types.
 @node Registering I/O Callbacks
 @subsubsection Registering I/O Callbacks
 
-@deftp {Data type} {struct gpgme_io_cb_ts}
+@deftp {Data type} {struct gpgme_io_cbs}
 @tindex gpgme_event_io_t
 This structure is used to store the I/O callback interface functions
 described in the previous section.  It has the following members:
@@ -5265,7 +5852,7 @@ described in the previous section.  It has the following members:
 This is the function called by @acronym{GPGME} to register an I/O
 callback handler.  It must be specified.
 
-@item void *add_data
+@item void *add_priv
 This is passed as the first argument to the @code{add} function when
 it is called by @acronym{GPGME}.  For example, it can be used to
 determine the event loop to which the file descriptor should be added.
@@ -5279,14 +5866,14 @@ This is the function called by @acronym{GPGME} to signal an event for
 an operation.  It must be specified, because at least the start event
 must be processed.
 
-@item void *event_data
+@item void *event_priv
 This is passed as the first argument to the @code{event} function when
 it is called by @acronym{GPGME}.  For example, it can be used to
 determine the context in which the event has occured.
 @end table
 @end deftp
 
-@deftypefun void gpgme_set_io_cbs (@w{gpgme_ctx_t @var{ctx}}, @w{struct gpgme_io_cb_ts *@var{io_cbs}})
+@deftypefun void gpgme_set_io_cbs (@w{gpgme_ctx_t @var{ctx}}, @w{struct gpgme_io_cbs *@var{io_cbs}})
 The function @code{gpgme_set_io_cbs} enables the I/O callback
 interface for the context @var{ctx}.  The I/O callback functions are
 specified by @var{io_cbs}.
@@ -5295,7 +5882,7 @@ If @var{io_cbs}->@code{add} is @code{NULL}, the I/O callback interface
 is disabled for the context, and normal operation is restored.
 @end deftypefun
 
-@deftypefun void gpgme_get_io_cbs (@w{gpgme_ctx_t @var{ctx}}, @w{struct gpgme_io_cb_ts *@var{io_cbs}})
+@deftypefun void gpgme_get_io_cbs (@w{gpgme_ctx_t @var{ctx}}, @w{struct gpgme_io_cbs *@var{io_cbs}})
 The function @code{gpgme_get_io_cbs} returns the I/O callback
 functions set with @code{gpgme_set_io_cbs} in @var{io_cbs}.
 @end deftypefun
@@ -5318,6 +5905,9 @@ structure because the number of file descriptors needed for a crypto
 operation in @acronym{GPGME} is not predictable.
 
 @example
+#include <assert.h>
+#include <errno.h>
+#include <stdlib.h>
 #include <pthread.h>
 #include <sys/types.h>
 #include <gpgme.h>
@@ -5337,6 +5927,7 @@ struct one_fd
   int dir;
   gpgme_io_cb_t fnc;
   void *fnc_data;
+  void *loop;
 @};
 
 struct event_loop
@@ -5368,6 +5959,7 @@ add_io_cb (void *data, int fd, int dir, gpgme_io_cb_t fnc, void *fnc_data,
          fds[i].dir = dir;
          fds[i].fnc = fnc;
          fds[i].fnc_data = fnc_data;
+         fds[i].loop = loop;
          break;
        @}
     @}
@@ -5382,6 +5974,7 @@ void
 remove_io_cb (void *tag)
 @{
   struct one_fd *fd = tag;
+  struct event_loop *loop = fd->loop;
 
   pthread_mutex_lock (&loop->lock);
   fd->fd = -1;
@@ -5413,11 +6006,12 @@ do_select (struct event_loop *loop)
   fd_set wfds;
   int i, n;
   int any = 0;
+  struct one_fd *fdlist = loop->fds;
 
   pthread_mutex_lock (&loop->lock);
   FD_ZERO (&rfds);
   FD_ZERO (&wfds);
-  for (i = 0; i < FDLIST_MAX; i++)
+  for (i = 0; i < MAX_FDS; i++)
     if (fdlist[i].fd != -1)
       FD_SET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds);
   pthread_mutex_unlock (&loop->unlock);
@@ -5432,7 +6026,7 @@ do_select (struct event_loop *loop)
     return n;  /* Error or timeout.  */
 
   pthread_mutex_lock (&loop->lock);
-  for (i = 0; i < FDLIST_MAX && n; i++)
+  for (i = 0; i < MAX_FDS && n; i++)
     @{
       if (fdlist[i].fd != -1)
        @{
@@ -5463,7 +6057,6 @@ wait_for_op (struct event_loop *loop, struct op_result *result)
       ret = do_select (loop);
     @}
   while (ret >= 0 && !result->done);
-  return ret;
 @}
 @end example
 
@@ -5478,9 +6071,8 @@ main (int argc, char *argv[])
   gpgme_ctx_t ctx;
   gpgme_error_t err;
   gpgme_data_t sig, text;
-  gpgme_sig_stat_t status;
   int i;
-  struct gpgme_io_cb_ts io_cbs =
+  struct gpgme_io_cbs io_cbs =
   @{
     add_io_cb,
     &loop,
@@ -5492,7 +6084,7 @@ main (int argc, char *argv[])
   init_gpgme (void);
 
   /* Initialize the loop structure.  */
-  loop.lock = PTHREAD_MUTEX_INITIALIZER;
+  pthread_mutex_init (&loop.lock, NULL);
   for (i = 0; i < MAX_FDS; i++)
     loop->fds[i].fd = -1;
 
@@ -5507,7 +6099,7 @@ main (int argc, char *argv[])
   if (!err)
     @{
        gpgme_set_io_cbs (ctx, &io_cbs);
-       err = gpgme_op_verify_start (ctx, sig, text, &status);
+       err = gpgme_op_verify_start (ctx, sig, text, NULL);
     @}
   if (err)
     @{
@@ -5528,7 +6120,7 @@ main (int argc, char *argv[])
                gpgme_strsource (result.err), gpgme_strerror (result.err));
       exit (1);
     @}
-  /* Evaluate STATUS.  */
+  /* Evaluate verify result.  */
   @dots{}
   return 0;
 @}
@@ -5666,7 +6258,7 @@ struct IOCB @{
 class MyApp : public QApplication @{
 
   // ...
-  
+
   static void registerGpgmeIOCallback( void * data, int fd, int dir,
                                        GpgmeIOCb func, void * func_data,
                                        void ** tag ) @{
@@ -5731,16 +6323,16 @@ operation in the context @var{ctx}.  This only works if you use the
 global event loop or your own event loop.
 
 If you use the global event loop, you must not call @code{gpgme_wait}
-or @code{gpgme_wait} during cancellation.  After successful
+during cancellation.  After successful
 cancellation, you can call @code{gpgme_wait} (optionally waiting on
 @var{ctx}), and the context @var{ctx} will appear as if it had
 finished with the error code @code{GPG_ERR_CANCEL}.
 
-If you use your an external event loop, you must ensure that no I/O
+If you use an external event loop, you must ensure that no I/O
 callbacks are invoked for this context (for example by halting the
 event loop).  On successful cancellation, all registered I/O callbacks
 for this context will be unregistered, and a @code{GPGME_EVENT_DONE}
-event with the error code @code{GPG_ERR_CANCEL} will be signaled.
+event with the error code @code{GPG_ERR_CANCEL} will be signalled.
 
 The function returns an error code if the cancellation failed (in this
 case the state of @var{ctx} is not modified).
@@ -5764,19 +6356,737 @@ case the state of @var{ctx} is not modified).
 
 @include uiserver.texi
 
-@include lesser.texi
+@node Debugging
+@appendix How to solve problems
+@cindex debug
+@cindex GPGME_DEBUG
+
+Everyone knows that software often does not do what it should do and thus
+there is a need to track down problems.  This is in particular true
+for applications using a complex library like @acronym{GPGME} and of
+course also for the library itself.  Here we give a few hints on how
+to solve such problems.
+
+First of all you should make sure that the keys you want to use are
+installed in the GnuPG engine and are usable.  Thus the first test is
+to run the desired operation using @command{gpg} or @command{gpgsm} on
+the command line.  If you can't figure out why things don't work, you
+may use @acronym{GPGME}'s built in trace feature.  This feature is
+either enabled using the environment variable @code{GPGME_DEBUG} or,
+if this is not possible, by calling the function
+@code{gpgme_set_global_flag}.  The value is the trace level and
+an optional file name.  If no file name is given the trace output is
+printed to @code{stderr}.
+
+@noindent
+For example
+@smallexample
+GPGME_DEBUG=9:/home/user/mygpgme.log
+@end smallexample
+@noindent
+(Note that under Windows you use a semicolon in place of the colon to
+separate the fields.)
+
+A trace level of 9 is pretty verbose and thus you may want to start
+off with a lower level.  The exact definition of the trace levels and
+the output format may change with any release; you need to check the
+source code for details.  In any case the trace log should be helpful
+to understand what is going going on.  Warning: The trace log may
+reveal sensitive details like passphrases or other data you use in
+your application.  If you are asked to send a log file, make sure that
+you run your tests only with play data.
+
+
+@node Deprecated Functions
+@appendix Deprecated Functions
+@cindex deprecated
+
+For backward compatibility @acronym{GPGME} has a number of functions,
+data types and constants which are deprecated and should not be used
+anymore.  We document here those which are really old to help
+understanding old code and to allow migration to their modern
+counterparts.
+
+@strong{Warning:} These interfaces will be removed in a future version
+of @acronym{GPGME}.
 
-@include gpl.texi
+@deftypefun void gpgme_key_release (@w{gpgme_key_t @var{key}})
+The function @code{gpgme_key_release} is equivalent to
+@code{gpgme_key_unref}.
+@end deftypefun
 
-@node Function and Data Index
-@unnumbered Function and Data Index
+@deftypefun void gpgme_trust_item_release (@w{gpgme_trust_item_t @var{item}})
+The function @code{gpgme_trust_item_release} is an alias for
+@code{gpgme_trust_item_unref}.
+@end deftypefun
 
-@printindex fn
 
-@node Concept Index
-@unnumbered Concept Index
+@deftypefun gpgme_error_t gpgme_op_import_ext (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}}, @w{int *@var{nr}})
+The function @code{gpgme_op_import_ext} is equivalent to:
 
-@printindex cp
+@example
+  gpgme_error_t err = gpgme_op_import (ctx, keydata);
+  if (!err)
+    @{
+      gpgme_import_result_t result = gpgme_op_import_result (ctx);
+      *nr = result->considered;
+    @}
+@end example
+@end deftypefun
+
+
+@deftp {Data type} {gpgme_error_t (*gpgme_edit_cb_t) @
+   (@w{void *@var{handle}}, @
+    @w{gpgme_status_code_t @var{status}}, @
+    @w{const char *@var{args}}, @
+    @w{int @var{fd}})}
+@tindex gpgme_edit_cb_t
+The @code{gpgme_edit_cb_t} type is the type of functions which
+@acronym{GPGME} calls if it a key edit operation is on-going.  The
+status code @var{status} and the argument line @var{args} are passed
+through by @acronym{GPGME} from the crypto engine.  The file
+descriptor @var{fd} is -1 for normal status messages.  If @var{status}
+indicates a command rather than a status message, the response to the
+command should be written to @var{fd}.  The @var{handle} is provided
+by the user at start of operation.
+
+The function should return @code{GPG_ERR_FALSE} if it did not handle
+the status code, @code{0} for success, or any other error value.
+@end deftp
+
+@deftypefun gpgme_error_t gpgme_op_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
+Note: This function is deprecated, please use
+@code{gpgme_op_interact} instead.
+
+The function @code{gpgme_op_edit} processes the key @var{KEY}
+interactively, using the edit callback function @var{FNC} with the
+handle @var{HANDLE}.  The callback is invoked for every status and
+command request from the crypto engine.  The output of the crypto
+engine is written to the data object @var{out}.
+
+Note that the protocol between the callback function and the crypto
+engine is specific to the crypto engine and no further support in
+implementing this protocol correctly is provided by @acronym{GPGME}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+edit operation completes successfully, @code{GPG_ERR_INV_VALUE} if
+@var{ctx} or @var{key} is not a valid pointer, and any error returned
+by the crypto engine or the edit callback handler.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
+Note: This function is deprecated, please use
+@code{gpgme_op_interact_start} instead.
+
+The function @code{gpgme_op_edit_start} initiates a
+@code{gpgme_op_edit} operation.  It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
+@var{ctx} or @var{key} is not a valid pointer.
+@end deftypefun
+
+
+@deftypefun gpgme_error_t gpgme_op_card_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
+Note: This function is deprecated, please use @code{gpgme_op_interact}
+with the flag @code{GPGME_INTERACT_CARD} instead.
+
+The function @code{gpgme_op_card_edit} is analogous to
+@code{gpgme_op_edit}, but should be used to process the smart card corresponding to the key @var{key}.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_card_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
+Note: This function is deprecated, please use @code{gpgme_op_interact_start}
+with the flag @code{GPGME_INTERACT_CARD} instead.
+
+The function @code{gpgme_op_card_edit_start} initiates a
+@code{gpgme_op_card_edit} operation.  It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
+@var{ctx} or @var{key} is not a valid pointer.
+@end deftypefun
+
+
+
+@deftypefun gpgme_error_t gpgme_data_new_with_read_cb (@w{gpgme_data_t *@var{dh}}, @w{int (*@var{readfunc})} (@w{void *@var{hook}}, @w{char *@var{buffer}}, @w{size_t @var{count}}, @w{size_t *@var{nread}}), @w{void *@var{hook_value}})
+The function @code{gpgme_data_new_with_read_cb} creates a new
+@code{gpgme_data_t} object and uses the callback function @var{readfunc}
+to retrieve the data on demand.  As the callback function can supply
+the data in any way it wants, this is the most flexible data type
+@acronym{GPGME} provides.  However, it can not be used to write data.
+
+The callback function receives @var{hook_value} as its first argument
+whenever it is invoked.  It should return up to @var{count} bytes in
+@var{buffer}, and return the number of bytes actually read in
+@var{nread}.  It may return @code{0} in @var{nread} if no data is
+currently available.  To indicate @code{EOF} the function should
+return with an error code of @code{-1} and set @var{nread} to
+@code{0}.  The callback function may support to reset its internal
+read pointer if it is invoked with @var{buffer} and @var{nread} being
+@code{NULL} and @var{count} being @code{0}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+data object was successfully created, @code{GPG_ERR_INV_VALUE} if
+@var{dh} or @var{readfunc} is not a valid pointer, and
+@code{GPG_ERR_ENOMEM} if not enough memory is available.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_data_rewind (@w{gpgme_data_t @var{dh}})
+The function @code{gpgme_data_rewind} is equivalent to:
+
+@example
+  return (gpgme_data_seek (dh, 0, SEEK_SET) == -1)
+    ? gpgme_error_from_errno (errno) : 0;
+@end example
+@end deftypefun
+
+
+@deftp {Data type} gpgme_attr_t
+The @code{gpgme_attr_t} type is used to specify a key or trust item
+attribute.  The following attributes are defined:
+
+@table @code
+@item GPGME_ATTR_KEYID
+This is the key ID of a sub key.  It is representable as a string.
+
+For trust items, the trust item refers to the key with this ID.
+
+@item GPGME_ATTR_FPR
+This is the fingerprint of a sub key.  It is representable as a
+string.
+
+@item GPGME_ATTR_ALGO
+This is the crypto algorithm for which the sub key can be used.  It
+is representable as a string and as a number.  The numbers correspond
+to the @code{enum gcry_pk_algos} values in the gcrypt library.
+
+@item GPGME_ATTR_LEN
+This is the key length of a sub key.  It is representable as a
+number.
+
+@item GPGME_ATTR_CREATED
+This is the timestamp at creation time of a sub key.  It is
+representable as a number.
+
+@item GPGME_ATTR_EXPIRE
+This is the expiration time of a sub key.  It is representable as a
+number.
+
+@item GPGME_ATTR_OTRUST
+XXX FIXME  (also for trust items)
+
+@item GPGME_ATTR_USERID
+This is a user ID.  There can be more than one user IDs in a
+@var{gpgme_key_t} object.  The first one (with index 0) is the primary
+user ID.  The user ID is representable as a number.
+
+For trust items, this is the user ID associated with this trust item.
+
+@item GPGME_ATTR_NAME
+This is the name belonging to a user ID.  It is representable as a string.
+
+@item GPGME_ATTR_EMAIL
+This is the email address belonging to a user ID.  It is representable
+as a string.
+
+@item GPGME_ATTR_COMMENT
+This is the comment belonging to a user ID.  It is representable as a
+string.
+
+@item GPGME_ATTR_VALIDITY
+This is the validity belonging to a user ID.  It is representable as a
+string and as a number.  See below for a list of available validities.
+
+For trust items, this is the validity that is associated with this
+trust item.
+
+@item GPGME_ATTR_UID_REVOKED
+This specifies if a user ID is revoked.  It is representable as a
+number, and is @code{1} if the user ID is revoked, and @code{0}
+otherwise.
+
+@item GPGME_ATTR_UID_INVALID
+This specifies if a user ID is invalid.  It is representable as a
+number, and is @code{1} if the user ID is invalid, and @code{0}
+otherwise.
+
+@item GPGME_ATTR_LEVEL
+This is the trust level of a trust item.
+
+@item GPGME_ATTR_TYPE
+This returns information about the type of key.  For the string function
+this will eother be "PGP" or "X.509".  The integer function returns 0
+for PGP and 1 for X.509.  It is also used for the type of a trust item.
+
+@item GPGME_ATTR_IS_SECRET
+This specifies if the key is a secret key.  It is representable as a
+number, and is @code{1} if the key is revoked, and @code{0} otherwise.
+
+@item GPGME_ATTR_KEY_REVOKED
+This specifies if a sub key is revoked.  It is representable as a
+number, and is @code{1} if the key is revoked, and @code{0} otherwise.
+
+@item GPGME_ATTR_KEY_INVALID
+This specifies if a sub key is invalid.  It is representable as a
+number, and is @code{1} if the key is invalid, and @code{0} otherwise.
+
+@item GPGME_ATTR_KEY_EXPIRED
+This specifies if a sub key is expired.  It is representable as a
+number, and is @code{1} if the key is expired, and @code{0} otherwise.
+
+@item GPGME_ATTR_KEY_DISABLED
+This specifies if a sub key is disabled.  It is representable as a
+number, and is @code{1} if the key is disabled, and @code{0} otherwise.
+
+@item GPGME_ATTR_KEY_CAPS
+This is a description of the capabilities of a sub key.  It is
+representable as a string.  The string contains the letter ``e'' if
+the key can be used for encryption, ``s'' if the key can be used for
+signatures, and ``c'' if the key can be used for certifications.
+
+@item GPGME_ATTR_CAN_ENCRYPT
+This specifies if a sub key can be used for encryption.  It is
+representable as a number, and is @code{1} if the sub key can be used
+for encryption, and @code{0} otherwise.
+
+@item GPGME_ATTR_CAN_SIGN
+This specifies if a sub key can be used to create data signatures.  It
+is representable as a number, and is @code{1} if the sub key can be
+used for signatures, and @code{0} otherwise.
+
+@item GPGME_ATTR_CAN_CERTIFY
+This specifies if a sub key can be used to create key certificates.
+It is representable as a number, and is @code{1} if the sub key can be
+used for certifications, and @code{0} otherwise.
+
+@item GPGME_ATTR_SERIAL
+The X.509 issuer serial attribute of the key.  It is representable as
+a string.
+
+@item GPGME_ATTR_ISSUE
+The X.509 issuer name attribute of the key.  It is representable as a
+string.
+
+@item GPGME_ATTR_CHAINID
+The X.509 chain ID can be used to build the certification chain.  It
+is representable as a string.
+@end table
+@end deftp
+
+@deftypefun {const char *} gpgme_key_get_string_attr (@w{gpgme_key_t @var{key}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
+The function @code{gpgme_key_get_string_attr} returns the value of the
+string-representable attribute @var{what} of key @var{key}.  If the
+attribute is an attribute of a sub key or an user ID, @var{idx}
+specifies the sub key or user ID of which the attribute value is
+returned.  The argument @var{reserved} is reserved for later use and
+should be @code{NULL}.
+
+The string returned is only valid as long as the key is valid.
+
+The function returns @code{0} if an attribute can't be returned as a
+string, @var{key} is not a valid pointer, @var{idx} out of range,
+or @var{reserved} not @code{NULL}.
+@end deftypefun
+
+@deftypefun {unsigned long} gpgme_key_get_ulong_attr (@w{gpgme_key_t @var{key}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
+The function @code{gpgme_key_get_ulong_attr} returns the value of the
+number-representable attribute @var{what} of key @var{key}.  If the
+attribute is an attribute of a sub key or an user ID, @var{idx}
+specifies the sub key or user ID of which the attribute value is
+returned.  The argument @var{reserved} is reserved for later use and
+should be @code{NULL}.
+
+The function returns @code{0} if the attribute can't be returned as a
+number, @var{key} is not a valid pointer, @var{idx} out of range, or
+@var{reserved} not @code{NULL}.
+@end deftypefun
+
+
+@c
+@c Key Signatures
+@c
+The signatures on a key are only available if the key was retrieved
+via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode
+enabled, because it is expensive to retrieve all signatures of a key.
+
+So, before using the below interfaces to retrieve the signatures on a
+key, you have to make sure that the key was listed with signatures
+enabled.  One convenient, but blocking, way to do this is to use the
+function @code{gpgme_get_key}.
+
+@deftp {Data type} gpgme_attr_t
+The @code{gpgme_attr_t} type is used to specify a key signature
+attribute.  The following attributes are defined:
+
+@table @code
+@item GPGME_ATTR_KEYID
+This is the key ID of the key which was used for the signature.  It is
+representable as a string.
+
+@item GPGME_ATTR_ALGO
+This is the crypto algorithm used to create the signature.  It is
+representable as a string and as a number.  The numbers correspond to
+the @code{enum gcry_pk_algos} values in the gcrypt library.
+
+@item GPGME_ATTR_CREATED
+This is the timestamp at creation time of the signature.  It is
+representable as a number.
+
+@item GPGME_ATTR_EXPIRE
+This is the expiration time of the signature.  It is representable as
+a number.
+
+@item GPGME_ATTR_USERID
+This is the user ID associated with the signing key.  The user ID is
+representable as a number.
+
+@item GPGME_ATTR_NAME
+This is the name belonging to a user ID.  It is representable as a string.
+
+@item GPGME_ATTR_EMAIL
+This is the email address belonging to a user ID.  It is representable
+as a string.
+
+@item GPGME_ATTR_COMMENT
+This is the comment belonging to a user ID.  It is representable as a
+string.
+
+@item GPGME_ATTR_KEY_REVOKED
+This specifies if a key signature is a revocation signature.  It is
+representable as a number, and is @code{1} if the key is revoked, and
+@code{0} otherwise.
+
+@c @item GPGME_ATTR_KEY_EXPIRED
+@c This specifies if a key signature is expired.  It is representable as
+@c a number, and is @code{1} if the key is revoked, and @code{0}
+@c otherwise.
+@c
+@item GPGME_ATTR_SIG_CLASS
+This specifies the signature class of a key signature.  It is
+representable as a number.  The meaning is specific to the crypto
+engine.
+
+@item GPGME_ATTR_SIG_CLASS
+This specifies the signature class of a key signature.  It is
+representable as a number.  The meaning is specific to the crypto
+engine.
+
+@item GPGME_ATTR_SIG_STATUS
+This is the same value as returned by @code{gpgme_get_sig_status}.
+@end table
+@end deftp
+
+@deftypefun {const char *} gpgme_key_sig_get_string_attr (@w{gpgme_key_t @var{key}}, @w{int @var{uid_idx}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
+The function @code{gpgme_key_sig_get_string_attr} returns the value of
+the string-representable attribute @var{what} of the signature
+@var{idx} on the user ID @var{uid_idx} in the key @var{key}.  The
+argument @var{reserved} is reserved for later use and should be
+@code{NULL}.
+
+The string returned is only valid as long as the key is valid.
+
+The function returns @code{0} if an attribute can't be returned as a
+string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx}
+out of range, or @var{reserved} not @code{NULL}.
+@end deftypefun
+
+@deftypefun {unsigned long} gpgme_key_sig_get_ulong_attr (@w{gpgme_key_t @var{key}}, @w{int @var{uid_idx}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
+The function @code{gpgme_key_sig_get_ulong_attr} returns the value of
+the number-representable attribute @var{what} of the signature
+@var{idx} on the user ID @var{uid_idx} in the key @var{key}.  The
+argument @var{reserved} is reserved for later use and should be
+@code{NULL}.
+
+The function returns @code{0} if an attribute can't be returned as a
+string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx}
+out of range, or @var{reserved} not @code{NULL}.
+@end deftypefun
+
+
+@c node Information About Trust Items
+@c subsection Information About Trust Items
+@c cindex trust item, information about
+@c cindex trust item, attributes
+@c cindex attributes, of a trust item
+
+Trust items have attributes which can be queried using the interfaces
+below.  The attribute identifiers are shared with those for key
+attributes.  @xref{Information About Keys}.
+
+@deftypefun {const char *} gpgme_trust_item_get_string_attr (@w{gpgme_trust_item_t @var{item}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
+The function @code{gpgme_trust_item_get_string_attr} returns the value
+of the string-representable attribute @var{what} of trust item
+@var{item}.  The arguments @var{idx} and @var{reserved} are reserved
+for later use and should be @code{0} and @code{NULL} respectively.
+
+The string returned is only valid as long as the key is valid.
+
+The function returns @code{0} if an attribute can't be returned as a
+string, @var{key} is not a valid pointer, @var{idx} out of range,
+or @var{reserved} not @code{NULL}.
+@end deftypefun
+
+@deftypefun int gpgme_trust_item_get_int_attr (@w{gpgme_trust_item_t @var{item}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
+The function @code{gpgme_trust_item_get_int_attr} returns the value of
+the number-representable attribute @var{what} of trust item
+@var{item}.  If the attribute occurs more than once in the trust item,
+the index is specified by @var{idx}.  However, currently no such
+attribute exists, so @var{idx} should be @code{0}.  The argument
+@var{reserved} is reserved for later use and should be @code{NULL}.
+
+The function returns @code{0} if the attribute can't be returned as a
+number, @var{key} is not a valid pointer, @var{idx} out of range,
+or @var{reserved} not @code{NULL}.
+@end deftypefun
+
+
+@deftp {Data type} {enum gpgme_sig_stat_t}
+@tindex gpgme_sig_stat_t
+The @code{gpgme_sig_stat_t} type holds the result of a signature check, or
+the combined result of all signatures.  The following results are
+possible:
+
+@table @code
+@item GPGME_SIG_STAT_NONE
+This status should not occur in normal operation.
+
+@item GPGME_SIG_STAT_GOOD
+This status indicates that the signature is valid.  For the combined
+result this status means that all signatures are valid.
+
+@item GPGME_SIG_STAT_GOOD_EXP
+This status indicates that the signature is valid but expired.  For
+the combined result this status means that all signatures are valid
+and expired.
+
+@item GPGME_SIG_STAT_GOOD_EXPKEY
+This status indicates that the signature is valid but the key used to
+verify the signature has expired.  For the combined result this status
+means that all signatures are valid and all keys are expired.
+
+@item GPGME_SIG_STAT_BAD
+This status indicates that the signature is invalid.  For the combined
+result this status means that all signatures are invalid.
+
+@item GPGME_SIG_STAT_NOKEY
+This status indicates that the signature could not be verified due to
+a missing key.  For the combined result this status means that all
+signatures could not be checked due to missing keys.
+
+@item GPGME_SIG_STAT_NOSIG
+This status indicates that the signature data provided was not a real
+signature.
+
+@item GPGME_SIG_STAT_ERROR
+This status indicates that there was some other error which prevented
+the signature verification.
+
+@item GPGME_SIG_STAT_DIFF
+For the combined result this status means that at least two signatures
+have a different status.  You can get each key's status with
+@code{gpgme_get_sig_status}.
+@end table
+@end deftp
+
+@deftypefun {const char *} gpgme_get_sig_status (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_sig_stat_t *@var{r_stat}}, @w{time_t *@var{r_created}})
+The function @code{gpgme_get_sig_status} is equivalent to:
+
+@example
+  gpgme_verify_result_t result;
+  gpgme_signature_t sig;
+
+  result = gpgme_op_verify_result (ctx);
+  sig = result->signatures;
+
+  while (sig && idx)
+    @{
+      sig = sig->next;
+      idx--;
+    @}
+  if (!sig || idx)
+    return NULL;
+
+  if (r_stat)
+    @{
+      switch (gpg_err_code (sig->status))
+       @{
+       case GPG_ERR_NO_ERROR:
+         *r_stat = GPGME_SIG_STAT_GOOD;
+         break;
+
+       case GPG_ERR_BAD_SIGNATURE:
+         *r_stat = GPGME_SIG_STAT_BAD;
+         break;
+
+       case GPG_ERR_NO_PUBKEY:
+         *r_stat = GPGME_SIG_STAT_NOKEY;
+         break;
+
+       case GPG_ERR_NO_DATA:
+         *r_stat = GPGME_SIG_STAT_NOSIG;
+         break;
+
+       case GPG_ERR_SIG_EXPIRED:
+         *r_stat = GPGME_SIG_STAT_GOOD_EXP;
+         break;
+
+       case GPG_ERR_KEY_EXPIRED:
+         *r_stat = GPGME_SIG_STAT_GOOD_EXPKEY;
+         break;
+
+       default:
+         *r_stat = GPGME_SIG_STAT_ERROR;
+         break;
+       @}
+    @}
+  if (r_created)
+    *r_created = sig->timestamp;
+  return sig->fpr;
+@end example
+@end deftypefun
+
+@deftypefun {const char *} gpgme_get_sig_string_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{what}}, @w{int @var{whatidx}})
+The function @code{gpgme_get_sig_string_attr} is equivalent to:
+
+@example
+  gpgme_verify_result_t result;
+  gpgme_signature_t sig;
+
+  result = gpgme_op_verify_result (ctx);
+  sig = result->signatures;
+
+  while (sig && idx)
+    @{
+      sig = sig->next;
+      idx--;
+    @}
+  if (!sig || idx)
+    return NULL;
+
+  switch (what)
+    @{
+    case GPGME_ATTR_FPR:
+      return sig->fpr;
+
+    case GPGME_ATTR_ERRTOK:
+      if (whatidx == 1)
+        return sig->wrong_key_usage ? "Wrong_Key_Usage" : "";
+      else
+       return "";
+    default:
+      break;
+    @}
+
+  return NULL;
+@end example
+@end deftypefun
+
+@deftypefun {const char *} gpgme_get_sig_ulong_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{waht}}, @w{int @var{whatidx}})
+The function @code{gpgme_get_sig_ulong_attr} is equivalent to:
+
+@example
+  gpgme_verify_result_t result;
+  gpgme_signature_t sig;
+
+  result = gpgme_op_verify_result (ctx);
+  sig = result->signatures;
+
+  while (sig && idx)
+    @{
+      sig = sig->next;
+      idx--;
+    @}
+  if (!sig || idx)
+    return 0;
+
+  switch (what)
+    @{
+    case GPGME_ATTR_CREATED:
+      return sig->timestamp;
+
+    case GPGME_ATTR_EXPIRE:
+      return sig->exp_timestamp;
+
+    case GPGME_ATTR_VALIDITY:
+      return (unsigned long) sig->validity;
+
+    case GPGME_ATTR_SIG_STATUS:
+      switch (sig->status)
+       @{
+       case GPG_ERR_NO_ERROR:
+         return GPGME_SIG_STAT_GOOD;
+
+       case GPG_ERR_BAD_SIGNATURE:
+         return GPGME_SIG_STAT_BAD;
+
+       case GPG_ERR_NO_PUBKEY:
+         return GPGME_SIG_STAT_NOKEY;
+
+       case GPG_ERR_NO_DATA:
+         return GPGME_SIG_STAT_NOSIG;
+
+       case GPG_ERR_SIG_EXPIRED:
+         return GPGME_SIG_STAT_GOOD_EXP;
+
+       case GPG_ERR_KEY_EXPIRED:
+         return GPGME_SIG_STAT_GOOD_EXPKEY;
+
+       default:
+         return GPGME_SIG_STAT_ERROR;
+       @}
+
+    case GPGME_ATTR_SIG_SUMMARY:
+      return sig->summary;
+
+    default:
+      break;
+    @}
+  return 0;
+@end example
+@end deftypefun
+
+@deftypefun {const char *} gpgme_get_sig_key (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_key_t *@var{r_key}})
+The function @code{gpgme_get_sig_key} is equivalent to:
+
+@example
+  gpgme_verify_result_t result;
+  gpgme_signature_t sig;
+
+  result = gpgme_op_verify_result (ctx);
+  sig = result->signatures;
+
+  while (sig && idx)
+    @{
+      sig = sig->next;
+      idx--;
+    @}
+  if (!sig || idx)
+    return gpg_error (GPG_ERR_EOF);
+
+  return gpgme_get_key (ctx, sig->fpr, r_key, 0);
+@end example
+@end deftypefun
+
+
+
+
+
+@include lesser.texi
+
+@include gpl.texi
+
+@node Concept Index
+@unnumbered Concept Index
+
+@printindex cp
+
+@node Function and Data Index
+@unnumbered Function and Data Index
+
+@printindex fn
 
 
 @bye