doc: Move description of most deprecated functions to a new appendix.
authorWerner Koch <wk@gnupg.org>
Fri, 16 Sep 2016 10:20:33 +0000 (12:20 +0200)
committerWerner Koch <wk@gnupg.org>
Fri, 16 Sep 2016 10:20:55 +0000 (12:20 +0200)
--
Signed-off-by: Werner Koch <wk@gnupg.org>
doc/gpgme.texi

index ad1a23a..dc5a140 100644 (file)
@@ -14,8 +14,7 @@
 @syncodeindex pg fn
 
 @copying
-Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007,
-2008, 2010, 2012, 2013, 2014, 2016 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ü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'.
@@ -201,7 +201,6 @@ 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.
@@ -215,7 +214,6 @@ Key Management
 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
@@ -1984,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
@@ -2122,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
@@ -2967,7 +2924,6 @@ section describes how such keys can be selected and manipulated.
 * 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.
@@ -3505,750 +3461,470 @@ 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}});
 
-@item GPGME_ATTR_OTRUST
-XXX FIXME  (also for trust items)
+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_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.
+@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.
 
-For trust items, this is the user ID associated with this trust item.
+@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).
 
-@item GPGME_ATTR_NAME
-This is the name belonging to a user ID.  It is representable as a string.
+@var{reserved} must be set to zero.
 
-@item GPGME_ATTR_EMAIL
-This is the email address belonging to a user ID.  It is representable
-as a string.
+@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.
 
-@item GPGME_ATTR_COMMENT
-This is the comment belonging to a user ID.  It is representable as a
-string.
+@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.
 
-@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.
+@var{flags} can be set to the bit-wise OR of the following flags:
 
-For trust items, this is the validity that is associated with this
-trust item.
+@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.
 
-@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.
+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_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_CREATE_NOPASSWD
+Request generation of the key without password protection.
 
-@item GPGME_ATTR_LEVEL
-This is the trust level of a trust item.
+@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_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_CREATE_NOSTORE
+Do not store the created key in the local key database.
+This has not yet been implemented.
 
-@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_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_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_CREATE_FORCE
+The engine does not allow the creation of a key with a user ID
+already existing in the local key database.  This flag can be used to
+override this check.
 
-@item GPGME_ATTR_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.
+@end table
 
-@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.
+After the operation completed successfully, information about the
+created key can be retrieved with @code{gpgme_op_genkey_result}.
 
-@item GPGME_ATTR_KEY_DISABLED
-This specifies if a sub key is disabled.  It is representable as a
-number, and is @code{1} if the key is disabled, and @code{0} otherwise.
+The function returns zero on success, @code{GPG_ERR_NOT_SUPPORTED} if
+the engine does not support the command, or a bunch of other error
+codes.
 
-@item GPGME_ATTR_KEY_CAPS
-This is a description of the capabilities of a sub key.  It is
-representable as a string.  The string contains the letter ``e'' if
-the key can be used for encryption, ``s'' if the key can be used for
-signatures, and ``c'' if the key can be used for certifications.
+@end deftypefun
 
-@item GPGME_ATTR_CAN_ENCRYPT
-This specifies if a sub key can be used for encryption.  It is
-representable as a number, and is @code{1} if the sub key can be used
-for encryption, and @code{0} otherwise.
 
-@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.
+@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_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.
+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_SERIAL
-The X.509 issuer serial attribute of the key.  It is representable as
-a string.
+@end deftypefun
 
-@item GPGME_ATTR_ISSUE
-The X.509 issuer name attribute of the key.  It is representable as a
-string.
+@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_CHAINID
-The X.509 chain ID can be used to build the certification chain.  It
-is representable as a string.
-@end table
-@end deftp
+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.
 
-@deftypefun {const char *} gpgme_key_get_string_attr (@w{gpgme_key_t @var{key}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
-The function @code{gpgme_key_get_string_attr} returns the value of the
-string-representable attribute @var{what} of key @var{key}.  If the
-attribute is an attribute of a sub key or an user ID, @var{idx}
-specifies the sub key or user ID of which the attribute value is
-returned.  The argument @var{reserved} is reserved for later use and
-should be @code{NULL}.
+@var{key} specifies the key to operate on.
 
-The string returned is only valid as long as the key is valid.
+@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.
 
-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
+@var{reserved} must be set to zero.
 
-@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}.
+@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.
 
-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
+@var{flags} takes the same values as described above for
+@code{gpgme_op_createkey}.
 
+After the operation completed successfully, information about the
+created key can be retrieved with @code{gpgme_op_genkey_result}.
 
-@node Key Signatures
-@subsection Key Signatures
-@cindex key, signatures
-@cindex signatures, on a key
+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.
 
-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}.
 
-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.
+@end deftypefun
 
-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}.
+@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}});
 
-@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_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}.
 
-@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.
+@end deftypefun
 
-@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.
+@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}});
 
-@item GPGME_ATTR_EXPIRE
-This is the expiration time of the signature.  It is representable as
-a number.
+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.
 
-@item GPGME_ATTR_USERID
-This is the user ID associated with the signing key.  The user ID is
-representable as a number.
+@var{key} specifies the key to operate on.
 
-@item GPGME_ATTR_NAME
-This is the name belonging to a user ID.  It is representable as a string.
+@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_EMAIL
-This is the email address belonging to a user ID.  It is representable
-as a string.
+@var{flags} are currently not used and must be set to zero.
 
-@item GPGME_ATTR_COMMENT
-This is the comment 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_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.
+@end deftypefun
 
-@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.
+@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_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.
+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_SIG_STATUS
-This is the same value as returned by @code{gpgme_get_sig_status}.
-@end table
-@end deftp
+@end deftypefun
 
-@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
+@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
-
-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.
-
 @c
-@c  gpgme_op_createkey
+@c  gpgme_op_genkey
 @c
-@deftypefun gpgme_error_t gpgme_op_createkey @
+@deftypefun gpgme_error_t gpgme_op_genkey @
       (@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.
-
-@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:
-
-@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.
+       @w{const char *@var{parms}}, @
+       @w{gpgme_data_t @var{public}}, @
+       @w{gpgme_data_t @var{secret}})
 
-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.
+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.
 
-@item GPGME_CREATE_NOPASSWD
-Request generation of the key without password protection.
+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}.
 
-@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.
+GpgSM requires @var{public} to be a writable data object.  GpgSM will
+generate a secret key (which will be stored by @command{gpg-agent},
+and return a certificate request in @var{public}, which then needs to
+be signed by the certification authority and imported before it can be
+used.  GpgSM does not make the fingerprint available.
 
-@item GPGME_CREATE_NOSTORE
-Do not store the created key in the local key database.
-This has not yet been implemented.
+The argument @var{parms} specifies parameters for the key in an XML
+string.  The details about the format of @var{parms} are specific to
+the crypto engine used by @var{ctx}.  Here is an example for GnuPG as
+the crypto engine (all parameters of OpenPGP key generation are
+documented in the GPG manual):
 
-@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.
+@example
+<GnupgKeyParms format="internal">
+Key-Type: default
+Subkey-Type: default
+Name-Real: Joe Tester
+Name-Comment: with stupid passphrase
+Name-Email: joe@@foo.bar
+Expire-Date: 0
+Passphrase: abc
+</GnupgKeyParms>
+@end example
 
-@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.
+Here is an example for GpgSM as the crypto engine (all parameters of
+OpenPGP key generation are documented in the GPGSM manual):
 
-@end table
+@example
+<GnupgKeyParms format="internal">
+Key-Type: RSA
+Key-Length: 1024
+Name-DN: C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester
+Name-Email: joe@@foo.bar
+</GnupgKeyParms>
+@end example
 
-After the operation completed successfully, information about the
-created key can be retrieved with @code{gpgme_op_genkey_result}.
+Strings should be given in UTF-8 encoding.  The only format supported
+for now is ``internal''.  The content of the @code{GnupgKeyParms}
+container is passed verbatim to the crypto backend.  Control
+statements are not allowed.
 
-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.
+After the operation completed successfully, the result can be
+retrieved with @code{gpgme_op_genkey_result}.
 
+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{parms} is not a valid XML string, @code{GPG_ERR_NOT_SUPPORTED} if
+@var{public} or @var{secret} is not valid, and @code{GPG_ERR_GENERAL}
+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}})
 
-@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}});
-
-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}.
+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}.
 
+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{parms} is not a valid XML string, and
+@code{GPG_ERR_NOT_SUPPORTED} if @var{public} or @var{secret} is not
+@code{NULL}.
 @end deftypefun
 
+
 @c
-@c  gpgme_op_createsubkey
+@c  gpgme_op_genkey_result
 @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}});
+@deftp {Data type} {gpgme_genkey_result_t}
 
-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.
+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
+@code{gpgme_op_genkey_result}.  The structure contains the following
+members:
 
-@var{key} specifies the key to operate on.
+@table @code
+@item unsigned int primary : 1
+This flag is set to 1 if a primary key was created and to 0
+if not.
 
-@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 unsigned int sub : 1
+This flag is set to 1 if a subkey was created and to 0 if not.
 
-@var{reserved} must be set to zero.
+@item unsigned int uid : 1
+This flag is set to 1 if a user ID was created and to 0 if not.
 
-@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 char *fpr
+This is the fingerprint of the key that was created.  If both a
+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.
 
-@var{flags} takes the same values as described above for
-@code{gpgme_op_createkey}.
+@item gpgme_data_t pubkey
+This will eventually be used to return the public key.  It is
+currently not used.
 
-After the operation completed successfully, information about the
-created key can be retrieved with @code{gpgme_op_genkey_result}.
+@item gpgme_data_t seckey
+This will eventually be used to return the secret key.  It is
+currently not used.
 
-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 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
+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
 
-@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}});
 
-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}.
+@c
+@c  SIGNING KEYS
+@c
+@node Signing Keys
+@subsection Signing Keys
+@cindex key, signing
 
-@end deftypefun
+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_adduid
+@c  gpgme_op_keysign
 @c
-@deftypefun gpgme_error_t gpgme_op_adduid @
+@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 int @var{flags}});
-
-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.
-
-@var{key} specifies the key to operate on.
-
-@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.
-
-@var{flags} are currently not used and must be set to zero.
-
-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_adduid_start @
-      (@w{gpgme_ctx_t @var{ctx}}, @
-       @w{gpgme_key_t @var{key}}, @
-       @w{const char *@var{userid}}, @
-       @w{unsigned int @var{flags}});
-
-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}.
-
-@end deftypefun
-
-
-@c
-@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 @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.
-
-@var{key} specifies the key to operate on.
-
-@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.
-
-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.
-
-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_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 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}.
-
-@end deftypefun
-
-
-@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}})
-
-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.
-
-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}.
-
-GpgSM requires @var{public} to be a writable data object.  GpgSM will
-generate a secret key (which will be stored by @command{gpg-agent},
-and return a certificate request in @var{public}, which then needs to
-be signed by the certification authority and imported before it can be
-used.  GpgSM does not make the fingerprint available.
-
-The argument @var{parms} specifies parameters for the key in an XML
-string.  The details about the format of @var{parms} are specific to
-the crypto engine used by @var{ctx}.  Here is an example for GnuPG as
-the crypto engine (all parameters of OpenPGP key generation are
-documented in the GPG manual):
-
-@example
-<GnupgKeyParms format="internal">
-Key-Type: default
-Subkey-Type: default
-Name-Real: Joe Tester
-Name-Comment: with stupid passphrase
-Name-Email: joe@@foo.bar
-Expire-Date: 0
-Passphrase: abc
-</GnupgKeyParms>
-@end example
-
-Here is an example for GpgSM as the crypto engine (all parameters of
-OpenPGP key generation are documented in the GPGSM manual):
-
-@example
-<GnupgKeyParms format="internal">
-Key-Type: RSA
-Key-Length: 1024
-Name-DN: C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester
-Name-Email: joe@@foo.bar
-</GnupgKeyParms>
-@end example
-
-Strings should be given in UTF-8 encoding.  The only format supported
-for now is ``internal''.  The content of the @code{GnupgKeyParms}
-container is passed verbatim to the crypto backend.  Control
-statements are not allowed.
-
-After the operation completed successfully, the result can be
-retrieved with @code{gpgme_op_genkey_result}.
-
-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{parms} is not a valid XML string, @code{GPG_ERR_NOT_SUPPORTED} if
-@var{public} or @var{secret} is not valid, and @code{GPG_ERR_GENERAL}
-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}.
-
-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{parms} is not a valid XML string, and
-@code{GPG_ERR_NOT_SUPPORTED} if @var{public} or @var{secret} is not
-@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
-@code{gpgme_op_genkey_result}.  The structure contains the following
-members:
-
-@table @code
-@item unsigned int primary : 1
-This flag is set to 1 if a primary key was created and to 0
-if not.
-
-@item unsigned int sub : 1
-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 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
-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 long @var{expires}}, @
        @w{unsigned int @var{flags}});
 
 The function @code{gpgme_op_keysign} adds a new key signature to the
@@ -4644,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
@@ -4866,80 +4524,6 @@ is not a valid pointer.
 @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
-
 
 @node Trust Item Management
 @section Trust Item Management
@@ -4975,7 +4559,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
 
@@ -5032,47 +4615,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
@@ -5090,16 +4632,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
@@ -5521,326 +5053,94 @@ 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;
-
-       case GPG_ERR_SIG_EXPIRED:
-         *r_stat = GPGME_SIG_STAT_GOOD_EXP;
-         break;
-
-       case GPG_ERR_KEY_EXPIRED:
-         *r_stat = GPGME_SIG_STAT_GOOD_EXPKEY;
-         break;
-
-       default:
-         *r_stat = GPGME_SIG_STAT_ERROR;
-         break;
-       @}
-    @}
-  if (r_created)
-    *r_created = sig->timestamp;
-  return sig->fpr;
-@end example
-@end deftypefun
-
-@deftypefun {const char *} gpgme_get_sig_string_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{what}}, @w{int @var{whatidx}})
-The function @code{gpgme_get_sig_string_attr} is equivalent to:
-
-@example
-  gpgme_verify_result_t result;
-  gpgme_signature_t sig;
-
-  result = gpgme_op_verify_result (ctx);
-  sig = result->signatures;
-
-  while (sig && idx)
-    @{
-      sig = sig->next;
-      idx--;
-    @}
-  if (!sig || idx)
-    return NULL;
-
-  switch (what)
-    @{
-    case GPGME_ATTR_FPR:
-      return sig->fpr;
-
-    case GPGME_ATTR_ERRTOK:
-      if (whatidx == 1)
-        return sig->wrong_key_usage ? "Wrong_Key_Usage" : "";
-      else
-       return "";
-    default:
-      break;
-    @}
-
-  return NULL;
-@end example
-@end deftypefun
-
-@deftypefun {const char *} gpgme_get_sig_ulong_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{waht}}, @w{int @var{whatidx}})
-The function @code{gpgme_get_sig_ulong_attr} is equivalent to:
-
-@example
-  gpgme_verify_result_t result;
-  gpgme_signature_t sig;
-
-  result = gpgme_op_verify_result (ctx);
-  sig = result->signatures;
-
-  while (sig && idx)
-    @{
-      sig = sig->next;
-      idx--;
-    @}
-  if (!sig || idx)
-    return 0;
-
-  switch (what)
-    @{
-    case GPGME_ATTR_CREATED:
-      return sig->timestamp;
-
-    case GPGME_ATTR_EXPIRE:
-      return sig->exp_timestamp;
-
-    case GPGME_ATTR_VALIDITY:
-      return (unsigned long) sig->validity;
-
-    case GPGME_ATTR_SIG_STATUS:
-      switch (sig->status)
-       @{
-       case GPG_ERR_NO_ERROR:
-         return GPGME_SIG_STAT_GOOD;
-
-       case GPG_ERR_BAD_SIGNATURE:
-         return GPGME_SIG_STAT_BAD;
-
-       case GPG_ERR_NO_PUBKEY:
-         return GPGME_SIG_STAT_NOKEY;
-
-       case GPG_ERR_NO_DATA:
-         return GPGME_SIG_STAT_NOSIG;
-
-       case GPG_ERR_SIG_EXPIRED:
-         return GPGME_SIG_STAT_GOOD_EXP;
-
-       case GPG_ERR_KEY_EXPIRED:
-         return GPGME_SIG_STAT_GOOD_EXPKEY;
-
-       default:
-         return GPGME_SIG_STAT_ERROR;
-       @}
-
-    case GPGME_ATTR_SIG_SUMMARY:
-      return sig->summary;
-
-    default:
-      break;
-    @}
-  return 0;
-@end example
-@end deftypefun
-
-@deftypefun {const char *} gpgme_get_sig_key (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_key_t *@var{r_key}})
-The function @code{gpgme_get_sig_key} is equivalent to:
-
-@example
-  gpgme_verify_result_t result;
-  gpgme_signature_t sig;
-
-  result = gpgme_op_verify_result (ctx);
-  sig = result->signatures;
-
-  while (sig && idx)
-    @{
-      sig = sig->next;
-      idx--;
-    @}
-  if (!sig || idx)
-    return gpg_error (GPG_ERR_EOF);
-
-  return gpgme_get_key (ctx, sig->fpr, r_key, 0);
-@end example
-@end deftypefun
-
-
-@node Decrypt and Verify
-@subsection Decrypt and Verify
-@cindex decryption and verification
-@cindex verification and decryption
-@cindex signature check
-@cindex cryptographic operation, decryption and verification
-
-@deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
-The function @code{gpgme_op_decrypt_verify} decrypts the ciphertext in
-the data object @var{cipher} and stores it into the data object
-@var{plain}.  If @var{cipher} contains signatures, they will be
-verified.
-
-After the operation completed, @code{gpgme_op_decrypt_result} and
-@code{gpgme_op_verify_result} can be used to retrieve more information
-about the signatures.
-
-If the error code @code{GPG_ERR_NO_DATA} is returned, @var{cipher}
-does not contain any data to decrypt.  However, it might still be
-signed.  The information about detected signatures is available with
-@code{gpgme_op_verify_result} in this case.
-
-The function returns the error code @code{GPG_ERR_NO_ERROR} if the
-ciphertext could be decrypted successfully, @code{GPG_ERR_INV_VALUE}
-if @var{ctx}, @var{cipher} or @var{plain} is not a valid pointer,
-@code{GPG_ERR_NO_DATA} if @var{cipher} does not contain any data to
-decrypt, @code{GPG_ERR_DECRYPT_FAILED} if @var{cipher} is not a valid
-cipher text, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the
-secret key could not be retrieved, and passes through any errors that
-are reported by the crypto engine support routines.
-@end deftypefun
-
-@deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
-The function @code{gpgme_op_decrypt_verify_start} initiates a
-@code{gpgme_op_decrypt_verify} operation.  It can be completed by
-calling @code{gpgme_wait} on the context.  @xref{Waiting For
-Completion}.
-
-The function returns the error code @code{GPG_ERR_NO_ERROR} if the
-operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
-@var{ctx}, @var{cipher}, @var{plain} or @var{r_stat} is not a valid
-pointer, and @code{GPG_ERR_NO_DATA} if @var{cipher} does not contain
-any data to decrypt.
-@end deftypefun
-
-
-@node Sign
-@subsection Sign
-@cindex signature, creation
-@cindex sign
-@cindex cryptographic operation, signing
-
-A signature can contain signatures by one or more keys.  The set of
-keys used to create a signatures is contained in a context, and is
-applied to all following signing operations in this context (until the
-set is changed).
-
-@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
-
-The key or the keys used to create a signature are stored in the
-context.  The following functions can be used to manipulate this list.
-If no signer has been set into the context a default key is used for
-signing.
-
-@deftypefun void gpgme_signers_clear (@w{gpgme_ctx_t @var{ctx}})
-The function @code{gpgme_signers_clear} releases a reference for each
-key on the signers list and removes the list of signers from the
-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
+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
@@ -7096,6 +6396,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