core: Map GPGME_STATUS_EOF to the empty string.
[gpgme.git] / doc / gpgme.texi
index dfc9548..18fb6d5 100644 (file)
@@ -14,8 +14,7 @@
 @syncodeindex pg fn
 
 @copying
-Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007,
-2008, 2010, 2012, 2013, 2014 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
@@ -71,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Ã\83¼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 +100,7 @@ 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'.
@@ -198,21 +198,22 @@ Context Attributes
 
 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
@@ -1981,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
@@ -2119,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
@@ -2959,9 +2919,120 @@ 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.
 
+
+@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_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 key is revoked.
+
+@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.
+
+@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 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 key (ie one of its subkeys) can be used for
+encryption.
+
+@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 unsigned int can_certify : 1
+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 key (ie one of its subkeys) can be used for
+authentication.
+
+@item unsigned int is_qualified : 1
+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 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_protocol_t protocol
+This is the protocol supported by this key.
+
+@item char *issuer_serial
+If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
+issuer serial.
+
+@item char *issuer_name
+If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
+issuer name.
+
+@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 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.
+
+@end table
+@end deftp
+
+
 @deftp {Data type} gpgme_subkey_t
+
 The @code{gpgme_subkey_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 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
@@ -3046,10 +3117,61 @@ For ECC algorithms the name of the curve.
 @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.
+
+The user ID structure has the following members.
+
+@table @code
+@item gpgme_user_id_t next
+This is a pointer to the next user ID structure in the linked list, or
+@code{NULL} if this is the last element.
+
+@item unsigned int revoked : 1
+This is true if the user ID is revoked.
+
+@item unsigned int invalid : 1
+This is true if the user ID is invalid.
+
+@item gpgme_validity_t validity
+This specifies the validity of the user ID.
+
+@item char *uid
+This is the user ID string.
+
+@item char *name
+This is the name component of @code{uid}, if available.
+
+@item char *comment
+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_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.
+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
@@ -3120,193 +3242,48 @@ 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.
-
-The user ID structure has the following members.
-
-@table @code
-@item gpgme_user_id_t next
-This is a pointer to the next user ID structure in the linked list, or
-@code{NULL} if this is the last element.
 
-@item unsigned int revoked : 1
-This is true if the user ID is revoked.
 
-@item unsigned int invalid : 1
-This is true if the user ID is invalid.
+@node Listing Keys
+@subsection Listing Keys
+@cindex listing keys
+@cindex key listing
+@cindex key listing, start
+@cindex key ring, list
+@cindex key ring, search
 
-@item gpgme_validity_t validity
-This specifies the validity of the user ID.
+@deftypefun gpgme_error_t gpgme_op_keylist_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}})
+The function @code{gpgme_op_keylist_start} initiates a key listing
+operation inside the context @var{ctx}.  It sets everything up so that
+subsequent invocations of @code{gpgme_op_keylist_next} return the keys
+in the list.
 
-@item char *uid
-This is the user ID string.
+If @var{pattern} is @code{NULL}, all available keys are returned.
+Otherwise, @var{pattern} contains an engine specific expression that
+is used to limit the list to all keys matching the pattern.  Note that
+the total length of the pattern is restricted to an engine-specific
+maximum (a couple of hundred characters are usually accepted).  The
+pattern should be used to restrict the search to a certain common name
+or user, not to list many specific keys at once by listing their
+fingerprints or key IDs.
 
-@item char *name
-This is the name component of @code{uid}, if available.
+If @var{secret_only} is not @code{0}, the list is restricted to secret
+keys only.
 
-@item char *comment
-This is the comment component of @code{uid}, if available.
+The context will be busy until either all keys are received (and
+@code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}), or
+@code{gpgme_op_keylist_end} is called to finish the operation.
 
-@item char *email
-This is the email component of @code{uid}, if available.
+The function returns the error code @code{GPG_ERR_INV_VALUE} if
+@var{ctx} is not a valid pointer, and passes through any errors that
+are reported by the crypto engine support routines.
+@end deftypefun
 
-@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:
-
-@table @code
-@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 key is revoked.
-
-@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.
-
-@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 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 key (ie one of its subkeys) can be used for
-encryption.
-
-@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 unsigned int can_certify : 1
-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 key (ie one of its subkeys) can be used for
-authentication.
-
-@item unsigned int is_qualified : 1
-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 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_protocol_t protocol
-This is the protocol supported by this key.
-
-@item char *issuer_serial
-If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
-issuer serial.
-
-@item char *issuer_name
-If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
-issuer name.
-
-@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 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.
-
-@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
-@subsection Listing Keys
-@cindex listing keys
-@cindex key listing
-@cindex key listing, start
-@cindex key ring, list
-@cindex key ring, search
-
-@deftypefun gpgme_error_t gpgme_op_keylist_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}})
-The function @code{gpgme_op_keylist_start} initiates a key listing
-operation inside the context @var{ctx}.  It sets everything up so that
-subsequent invocations of @code{gpgme_op_keylist_next} return the keys
-in the list.
-
-If @var{pattern} is @code{NULL}, all available keys are returned.
-Otherwise, @var{pattern} contains an engine specific expression that
-is used to limit the list to all keys matching the pattern.  Note that
-the total length of the pattern is restricted to an engine-specific
-maximum (a couple of hundred characters are usually accepted).  The
-pattern should be used to restrict the search to a certain common name
-or user, not to list many specific keys at once by listing their
-fingerprints or key IDs.
-
-If @var{secret_only} is not @code{0}, the list is restricted to secret
-keys only.
-
-The context will be busy until either all keys are received (and
-@code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}), or
-@code{gpgme_op_keylist_end} is called to finish the operation.
-
-The function returns the error code @code{GPG_ERR_INV_VALUE} if
-@var{ctx} is not a valid pointer, and passes through any errors that
-are reported by the crypto engine support routines.
-@end deftypefun
-
-@deftypefun gpgme_error_t gpgme_op_keylist_ext_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}[]}, @w{int @var{secret_only}}, @w{int @var{reserved}})
-The function @code{gpgme_op_keylist_ext_start} initiates an extended
-key listing operation inside the context @var{ctx}.  It sets
-everything up so that subsequent invocations of
-@code{gpgme_op_keylist_next} return the keys in the list.
+@deftypefun gpgme_error_t gpgme_op_keylist_ext_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}[]}, @w{int @var{secret_only}}, @w{int @var{reserved}})
+The function @code{gpgme_op_keylist_ext_start} initiates an extended
+key listing operation inside the context @var{ctx}.  It sets
+everything up so that subsequent invocations of
+@code{gpgme_op_keylist_next} return the keys in the list.
 
 If @var{pattern} or @var{*pattern} is @code{NULL}, all available keys
 are returned.  Otherwise, @var{pattern} is a @code{NULL} terminated
@@ -3484,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.
+@node Manipulating Keys
+@subsection Manipulating Keys
+@cindex key, manipulation
 
-For trust items, the trust item refers to the key with this ID.
+@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_FPR
-This is the fingerprint of a sub key.  It is representable as a
-string.
+@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_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.
+@node Generating Keys
+@subsection Generating Keys
+@cindex key, creation
+@cindex key ring, add
 
-@item GPGME_ATTR_CREATED
-This is the timestamp at creation 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_EXPIRE
-This is the expiration time of a sub key.  It is representable as a
-number.
+@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_OTRUST
-XXX FIXME  (also for trust items)
+@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_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.
+@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.
 
-For trust items, this is the user ID associated with this trust item.
+@end table
 
-@item GPGME_ATTR_NAME
-This is the name belonging to a user ID.  It is representable as a string.
+After the operation completed successfully, information about the
+created key can be retrieved with @code{gpgme_op_genkey_result}.
 
-@item GPGME_ATTR_EMAIL
-This is the email address belonging to a user ID.  It is representable
-as a string.
+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_COMMENT
-This is the comment belonging to a user ID.  It is representable as a
-string.
+@end deftypefun
 
-@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.
+@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_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.
+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_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.
+@end deftypefun
 
-@item GPGME_ATTR_LEVEL
-This is the trust level of a trust item.
+@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_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.
+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_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.
+@var{key} specifies the key to operate on.
 
-@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.
+@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_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.
+@var{reserved} must be set to zero.
 
-@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.
+@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.
 
-@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.
+@var{flags} takes the same values as described above for
+@code{gpgme_op_createkey}.
 
-@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.
+After the operation completed successfully, information about the
+created key can be retrieved with @code{gpgme_op_genkey_result}.
 
-@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.
+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_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
 
+@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}.
@@ -3849,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}.
@@ -3860,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
@@ -3869,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
@@ -3892,9 +3898,110 @@ 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
+
+
+@c
+@c  SIGNING KEYS
+@c
+@node Signing Keys
+@subsection Signing Keys
+@cindex key, signing
+
+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_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_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
@@ -4213,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
@@ -4263,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      @
@@ -4297,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}.
@@ -4326,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
+@var{flags} modifies the behaviour of the function; the only defined
+bit value is:
 
-@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}.
-
-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
@@ -4393,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
 
@@ -4450,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
@@ -4508,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
@@ -4939,351 +5054,124 @@ 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
+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).
 
-@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:
+@menu
+* Selecting Signers::             How to choose the keys to sign with.
+* Creating a Signature::          How to create a signature.
+* Signature Notation Data::       How to add notation data to a signature.
+@end menu
 
-@example
-  gpgme_verify_result_t result;
-  gpgme_signature_t sig;
 
-  result = gpgme_op_verify_result (ctx);
-  sig = result->signatures;
+@node Selecting Signers
+@subsubsection Selecting Signers
+@cindex signature, selecting signers
+@cindex signers, selecting
 
-  while (sig && idx)
-    @{
-      sig = sig->next;
-      idx--;
-    @}
-  if (!sig || idx)
-    return NULL;
+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.
 
-  if (r_stat)
-    @{
-      switch (gpg_err_code (sig->status))
-       @{
-       case GPG_ERR_NO_ERROR:
-         *r_stat = GPGME_SIG_STAT_GOOD;
-         break;
+@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
+context @var{ctx}.
 
-       case GPG_ERR_BAD_SIGNATURE:
-         *r_stat = GPGME_SIG_STAT_BAD;
-         break;
+Every context starts with an empty list.
+@end deftypefun
 
-       case GPG_ERR_NO_PUBKEY:
-         *r_stat = GPGME_SIG_STAT_NOKEY;
-         break;
+@deftypefun gpgme_error_t gpgme_signers_add (@w{gpgme_ctx_t @var{ctx}}, @w{const gpgme_key_t @var{key}})
+The function @code{gpgme_signers_add} adds the key @var{key} to the
+list of signers in the context @var{ctx}.
 
-       case GPG_ERR_NO_DATA:
-         *r_stat = GPGME_SIG_STAT_NOSIG;
-         break;
+Calling this function acquires an additional reference for the key.
+@end deftypefun
 
-       case GPG_ERR_SIG_EXPIRED:
-         *r_stat = GPGME_SIG_STAT_GOOD_EXP;
-         break;
+@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
 
-       case GPG_ERR_KEY_EXPIRED:
-         *r_stat = GPGME_SIG_STAT_GOOD_EXPKEY;
-         break;
+@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
+is acquired for the user.
 
-       default:
-         *r_stat = GPGME_SIG_STAT_ERROR;
-         break;
-       @}
-    @}
-  if (r_created)
-    *r_created = sig->timestamp;
-  return sig->fpr;
-@end example
+If @var{seq} is out of range, @code{NULL} is returned.
 @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;
+@node Creating a Signature
+@subsubsection Creating a Signature
 
-  result = gpgme_op_verify_result (ctx);
-  sig = result->signatures;
+@deftp {Data type} {enum gpgme_sig_mode_t}
+@tindex gpgme_sig_mode_t
+The @code{gpgme_sig_mode_t} type is used to specify the desired type of a
+signature.  The following modes are available:
 
-  while (sig && idx)
-    @{
-      sig = sig->next;
-      idx--;
-    @}
-  if (!sig || idx)
-    return NULL;
+@table @code
+@item GPGME_SIG_MODE_NORMAL
+A normal signature is made, the output includes the plaintext and the
+signature.
 
-  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).
-
-@menu
-* Selecting Signers::             How to choose the keys to sign with.
-* Creating a Signature::          How to create a signature.
-* Signature Notation Data::       How to add notation data to a signature.
-@end menu
-
-
-@node Selecting Signers
-@subsubsection Selecting Signers
-@cindex signature, selecting signers
-@cindex signers, selecting
-
-@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
-context @var{ctx}.
-
-Every context starts with an empty list.
-@end deftypefun
-
-@deftypefun gpgme_error_t gpgme_signers_add (@w{gpgme_ctx_t @var{ctx}}, @w{const gpgme_key_t @var{key}})
-The function @code{gpgme_signers_add} adds the key @var{key} to the
-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
-is acquired for the user.
-
-If @var{seq} is out of range, @code{NULL} is returned.
-@end deftypefun
-
-
-@node Creating a Signature
-@subsubsection Creating a Signature
-
-@deftp {Data type} {enum gpgme_sig_mode_t}
-@tindex gpgme_sig_mode_t
-The @code{gpgme_sig_mode_t} type is used to specify the desired type of a
-signature.  The following modes are available:
-
-@table @code
-@item GPGME_SIG_MODE_NORMAL
-A normal signature is made, the output includes the plaintext and the
-signature.
-
-@item GPGME_SIG_MODE_DETACH
-A detached signature is made.
+@item GPGME_SIG_MODE_DETACH
+A detached signature is made.
 
 @item GPGME_SIG_MODE_CLEAR
 A clear text signature is made.  The @acronym{ASCII} armor and text
@@ -6509,6 +6397,682 @@ 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}.
+
+@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
+
+@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
+
+
+@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
+
+
+@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