[Pkg-gnupg-commit] [gpgme] 369/412: doc: Move description of most deprecated functions to a new appendix.
Daniel Kahn Gillmor
dkg at fifthhorseman.net
Thu Sep 22 21:27:22 UTC 2016
This is an automated email from the git hooks/post-receive script.
dkg pushed a commit to branch master
in repository gpgme.
commit 00f95e0fad2ef438f78eabb7881b56568466f666
Author: Werner Koch <wk at gnupg.org>
Date: Fri Sep 16 12:20:33 2016 +0200
doc: Move description of most deprecated functions to a new appendix.
--
Signed-off-by: Werner Koch <wk at gnupg.org>
---
doc/gpgme.texi | 2226 ++++++++++++++++++++++++++++----------------------------
1 file changed, 1101 insertions(+), 1125 deletions(-)
diff --git a/doc/gpgme.texi b/doc/gpgme.texi
index ad1a23a..dc5a140 100644
--- a/doc/gpgme.texi
+++ b/doc/gpgme.texi
@@ -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}.
-
- at 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
- at 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
- at 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
- at var{buffer}, and return the number of bytes actually read in
- at 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
- at code{0}. The callback function may support to reset its internal
-read pointer if it is invoked with @var{buffer} and @var{nread} being
- at 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
- at var{dh} or @var{readfunc} is not a valid pointer, and
- at code{GPG_ERR_ENOMEM} if not enough memory is available.
- at 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}.
-
- at deftypefun gpgme_error_t gpgme_data_rewind (@w{gpgme_data_t @var{dh}})
-The function @code{gpgme_data_rewind} is equivalent to:
-
- at example
- return (gpgme_data_seek (dh, 0, SEEK_SET) == -1)
- ? gpgme_error_from_errno (errno) : 0;
- at end example
- at 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}.
- at 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:
- at table @code
- at item GPGME_ATTR_KEYID
-This is the key ID of a sub key. It is representable as a string.
+ at node Manipulating Keys
+ at subsection Manipulating Keys
+ at cindex key, manipulation
-For trust items, the trust item refers to the key with this ID.
+ at 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}.
+ at end deftypefun
- at item GPGME_ATTR_FPR
-This is the fingerprint of a sub key. It is representable as a
-string.
+ at deftypefun void gpgme_key_unref (@w{gpgme_key_t @var{key}})
+The function @code{gpgme_key_unref} releases a reference for the key
+ at var{key}. If this was the last reference, the key will be destroyed
+and all resources associated to it will be released.
+ at end deftypefun
- at 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.
- at item GPGME_ATTR_LEN
-This is the key length of a sub key. It is representable as a
-number.
+ at node Generating Keys
+ at subsection Generating Keys
+ at cindex key, creation
+ at cindex key ring, add
- at 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
+ at code{GPG_ERR_NOT_SUPPORTED} is received.
- at item GPGME_ATTR_EXPIRE
-This is the expiration time of a sub key. It is representable as a
-number.
+ at c
+ at c gpgme_op_createkey
+ at c
+ at 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}});
- at 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.
- at item GPGME_ATTR_USERID
-This is a user ID. There can be more than one user IDs in a
- at var{gpgme_key_t} object. The first one (with index 0) is the primary
-user ID. The user ID is representable as a number.
+ at 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.
+ at 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).
- at item GPGME_ATTR_NAME
-This is the name belonging to a user ID. It is representable as a string.
+ at var{reserved} must be set to zero.
- at item GPGME_ATTR_EMAIL
-This is the email address belonging to a user ID. It is representable
-as a string.
+ at 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.
- at item GPGME_ATTR_COMMENT
-This is the comment belonging to a user ID. It is representable as a
-string.
+ at 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.
- at 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.
+ at 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.
+ at table @code
+ at item GPGME_CREATE_SIGN
+ at itemx GPGME_CREATE_ENCR
+ at itemx GPGME_CREATE_CERT
+ at 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.
- at 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.
- at 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.
+ at item GPGME_CREATE_NOPASSWD
+Request generation of the key without password protection.
- at item GPGME_ATTR_LEVEL
-This is the trust level of a trust item.
+ at 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.
- at 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.
+ at item GPGME_CREATE_NOSTORE
+Do not store the created key in the local key database.
+This has not yet been implemented.
- at 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.
+ at item GPGME_CREATE_WANTPUB
+ at itemx GPGME_CREATE_WANTSEC
+Return the public or secret key as part of the result structure.
+This has not yet been implemented.
- at 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.
+ at 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.
- at 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.
+ at end table
- at 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}.
- at 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.
- at 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.
+ at end deftypefun
- at 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.
- at 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.
+ at 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}});
- at 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
+ at code{gpgme_op_createkey} operation; see there for details. It must
+be completed by calling @code{gpgme_wait} on the context.
+ at xref{Waiting For Completion}.
- at item GPGME_ATTR_SERIAL
-The X.509 issuer serial attribute of the key. It is representable as
-a string.
+ at end deftypefun
- at item GPGME_ATTR_ISSUE
-The X.509 issuer name attribute of the key. It is representable as a
-string.
+ at c
+ at c gpgme_op_createsubkey
+ at c
+ at 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}});
- at item GPGME_ATTR_CHAINID
-The X.509 chain ID can be used to build the certification chain. It
-is representable as a string.
- at end table
- at 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.
- at 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}.
+ at var{key} specifies the key to operate on.
-The string returned is only valid as long as the key is valid.
+ at var{algo} specifies the algorithm for the new subkey. For a list of
+supported algorithms, see the GnuPG manual. If @var{algo} is
+ at 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}.
- at end deftypefun
+ at var{reserved} must be set to zero.
- at 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}.
+ at 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
- at var{reserved} not @code{NULL}.
- at end deftypefun
+ at var{flags} takes the same values as described above for
+ at code{gpgme_op_createkey}.
+After the operation completed successfully, information about the
+created key can be retrieved with @code{gpgme_op_genkey_result}.
- at node Key Signatures
- at subsection Key Signatures
- at cindex key, signatures
- at 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.
+ at 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}.
+ at 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}});
- at 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
+ at code{gpgme_op_createsubkey} operation; see there for details. It must
+be completed by calling @code{gpgme_wait} on the context.
+ at xref{Waiting For Completion}.
- at table @code
- at item GPGME_ATTR_KEYID
-This is the key ID of the key which was used for the signature. It is
-representable as a string.
+ at end deftypefun
- at 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.
- at item GPGME_ATTR_CREATED
-This is the timestamp at creation time of the signature. It is
-representable as a number.
+ at c
+ at c gpgme_op_adduid
+ at c
+ at 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}});
- at 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.
- at item GPGME_ATTR_USERID
-This is the user ID associated with the signing key. The user ID is
-representable as a number.
+ at var{key} specifies the key to operate on.
- at item GPGME_ATTR_NAME
-This is the name belonging to a user ID. It is representable as a string.
+ at 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.
- at item GPGME_ATTR_EMAIL
-This is the email address belonging to a user ID. It is representable
-as a string.
+ at var{flags} are currently not used and must be set to zero.
- at 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.
- at 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
- at code{0} otherwise.
+ at end deftypefun
- at c @item GPGME_ATTR_KEY_EXPIRED
- at c This specifies if a key signature is expired. It is representable as
- at c a number, and is @code{1} if the key is revoked, and @code{0}
- at c otherwise.
- at c
- at 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.
+ at 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}});
- at 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
+ at code{gpgme_op_adduid} operation; see there for details. It must
+be completed by calling @code{gpgme_wait} on the context.
+ at xref{Waiting For Completion}.
- at item GPGME_ATTR_SIG_STATUS
-This is the same value as returned by @code{gpgme_get_sig_status}.
- at end table
- at end deftp
+ at end deftypefun
- at 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
- at 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
- at code{NULL}.
-The string returned is only valid as long as the key is valid.
+ at c
+ at c gpgme_op_revuid
+ at c
+ at 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}.
- at 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
+ at var{ctx} must be set to OpenPGP. As of now this function requires at
+least version 2.1.13 of GnuPG.
- at 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
- at 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
- at code{NULL}.
+ at 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}.
- at end deftypefun
+ at 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.
+ at var{flags} are currently not used and must be set to zero.
- at node Manipulating Keys
- at subsection Manipulating Keys
- at 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.
- at 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}.
- at 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.
- at deftypefun void gpgme_key_unref (@w{gpgme_key_t @var{key}})
-The function @code{gpgme_key_unref} releases a reference for the key
- at var{key}. If this was the last reference, the key will be destroyed
-and all resources associated to it will be released.
@end deftypefun
+ at 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
+ at code{gpgme_op_revuid} operation; see there for details. It must
+be completed by calling @code{gpgme_wait} on the context.
+ at xref{Waiting For Completion}.
- at deftypefun void gpgme_key_release (@w{gpgme_key_t @var{key}})
-The function @code{gpgme_key_release} is equivalent to
- at code{gpgme_key_unref}.
@end deftypefun
- at node Generating Keys
- at subsection Generating Keys
- at cindex key, creation
- at 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
- at code{GPG_ERR_NOT_SUPPORTED} is received.
-
@c
- at c gpgme_op_createkey
+ at c gpgme_op_genkey
@c
- at deftypefun gpgme_error_t gpgme_op_createkey @
+ at 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.
-
- at 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.
-
- at 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).
-
- at var{reserved} must be set to zero.
-
- at 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.
-
- at 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.
-
- at var{flags} can be set to the bit-wise OR of the following flags:
-
- at table @code
- at item GPGME_CREATE_SIGN
- at itemx GPGME_CREATE_ENCR
- at itemx GPGME_CREATE_CERT
- at 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.
- at item GPGME_CREATE_NOPASSWD
-Request generation of the key without password protection.
+GPG does not support @var{public} and @var{secret}, they should be
+ at 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}.
- at 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.
- at 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):
- at item GPGME_CREATE_WANTPUB
- at itemx GPGME_CREATE_WANTSEC
-Return the public or secret key as part of the result structure.
-This has not yet been implemented.
+ at 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>
+ at end example
- at 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):
- at end table
+ at 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>
+ at 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
+ at var{parms} is not a valid XML string, @code{GPG_ERR_NOT_SUPPORTED} if
+ at var{public} or @var{secret} is not valid, and @code{GPG_ERR_GENERAL}
+if no key was created by the backend.
@end deftypefun
+ at 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}})
- at 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
- at code{gpgme_op_createkey} operation; see there for details. It must
-be completed by calling @code{gpgme_wait} on the context.
- at xref{Waiting For Completion}.
+The function @code{gpgme_op_genkey_start} initiates a
+ at code{gpgme_op_genkey} operation. It can be completed by calling
+ at 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
+ at var{parms} is not a valid XML string, and
+ at code{GPG_ERR_NOT_SUPPORTED} if @var{public} or @var{secret} is not
+ at code{NULL}.
@end deftypefun
+
@c
- at c gpgme_op_createsubkey
+ at c gpgme_op_genkey_result
@c
- at 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}});
+ at 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
+ at code{gpgme_op_genkey} operation. After successfully generating a
+key, you can retrieve the pointer to the result with
+ at code{gpgme_op_genkey_result}. The structure contains the following
+members:
- at var{key} specifies the key to operate on.
+ at table @code
+ at item unsigned int primary : 1
+This flag is set to 1 if a primary key was created and to 0
+if not.
- at var{algo} specifies the algorithm for the new subkey. For a list of
-supported algorithms, see the GnuPG manual. If @var{algo} is
- at 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.
+ at item unsigned int sub : 1
+This flag is set to 1 if a subkey was created and to 0 if not.
- at var{reserved} must be set to zero.
+ at item unsigned int uid : 1
+This flag is set to 1 if a user ID was created and to 0 if not.
- at 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.
+ at 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.
- at var{flags} takes the same values as described above for
- at code{gpgme_op_createkey}.
+ at 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}.
+ at 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.
+ at end table
+ at end deftp
+ at deftypefun gpgme_genkey_result_t gpgme_op_genkey_result (@w{gpgme_ctx_t @var{ctx}})
+
+The function @code{gpgme_op_genkey_result} returns a
+ at 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
+ at 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
- at 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
- at code{gpgme_op_createsubkey} operation; see there for details. It must
-be completed by calling @code{gpgme_wait} on the context.
- at xref{Waiting For Completion}.
+ at c
+ at c SIGNING KEYS
+ at c
+ at node Signing Keys
+ at subsection Signing Keys
+ at cindex key, signing
- at 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
- at c gpgme_op_adduid
+ at c gpgme_op_keysign
@c
- at deftypefun gpgme_error_t gpgme_op_adduid @
+ at 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.
-
- at var{key} specifies the key to operate on.
-
- at 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.
-
- at 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.
-
- at end deftypefun
-
- at 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
- at code{gpgme_op_adduid} operation; see there for details. It must
-be completed by calling @code{gpgme_wait} on the context.
- at xref{Waiting For Completion}.
-
- at end deftypefun
-
-
- at c
- at c gpgme_op_revuid
- at c
- at 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
- at var{ctx} must be set to OpenPGP. As of now this function requires at
-least version 2.1.13 of GnuPG.
-
- at var{key} specifies the key to operate on.
-
- at 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.
-
- at 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.
-
- at end deftypefun
-
- at 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
- at code{gpgme_op_revuid} operation; see there for details. It must
-be completed by calling @code{gpgme_wait} on the context.
- at xref{Waiting For Completion}.
-
- at end deftypefun
-
-
- at c
- at c gpgme_op_genkey
- at c
- at 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
- at 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):
-
- at 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>
- at end example
-
-Here is an example for GpgSM as the crypto engine (all parameters of
-OpenPGP key generation are documented in the GPGSM manual):
-
- at 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>
- at 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
- at var{parms} is not a valid XML string, @code{GPG_ERR_NOT_SUPPORTED} if
- at var{public} or @var{secret} is not valid, and @code{GPG_ERR_GENERAL}
-if no key was created by the backend.
- at end deftypefun
-
- at 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
- at code{gpgme_op_genkey} operation. It can be completed by calling
- at 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
- at var{parms} is not a valid XML string, and
- at code{GPG_ERR_NOT_SUPPORTED} if @var{public} or @var{secret} is not
- at code{NULL}.
- at end deftypefun
-
-
- at c
- at c gpgme_op_genkey_result
- at c
- at deftp {Data type} {gpgme_genkey_result_t}
-
-This is a pointer to a structure used to store the result of a
- at code{gpgme_op_genkey} operation. After successfully generating a
-key, you can retrieve the pointer to the result with
- at code{gpgme_op_genkey_result}. The structure contains the following
-members:
-
- at table @code
- at item unsigned int primary : 1
-This flag is set to 1 if a primary key was created and to 0
-if not.
-
- at item unsigned int sub : 1
-This flag is set to 1 if a subkey was created and to 0 if not.
-
- at item unsigned int uid : 1
-This flag is set to 1 if a user ID was created and to 0 if not.
-
- at 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.
-
- at item gpgme_data_t pubkey
-This will eventually be used to return the public key. It is
-currently not used.
-
- at item gpgme_data_t seckey
-This will eventually be used to return the secret key. It is
-currently not used.
-
- at end table
- at end deftp
-
- at deftypefun gpgme_genkey_result_t gpgme_op_genkey_result (@w{gpgme_ctx_t @var{ctx}})
-
-The function @code{gpgme_op_genkey_result} returns a
- at 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
- at 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.
-
- at end deftypefun
-
-
- at c
- at c SIGNING KEYS
- at c
- at node Signing Keys
- at subsection Signing Keys
- at 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.
-
-
- at c
- at c gpgme_op_keysign
- at c
- at 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}.
-
- at 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:
-
- at 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;
- @}
- at end example
- at end deftypefun
-
-
@node Deleting Keys
@subsection Deleting Keys
@cindex key, delete
@@ -4866,80 +4524,6 @@ is not a valid pointer.
@end deftypefun
- at 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}})}
- at tindex gpgme_edit_cb_t
-The @code{gpgme_edit_cb_t} type is the type of functions which
- at 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.
- at end deftp
-
- at 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
- at 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
- at var{ctx} or @var{key} is not a valid pointer, and any error returned
-by the crypto engine or the edit callback handler.
- at end deftypefun
-
- at 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
- at code{gpgme_op_interact_start} instead.
-
-The function @code{gpgme_op_edit_start} initiates a
- at code{gpgme_op_edit} operation. It can be completed by calling
- at 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
- at var{ctx} or @var{key} is not a valid pointer.
- at end deftypefun
-
-
- at 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
- at code{gpgme_op_edit}, but should be used to process the smart card corresponding to the key @var{key}.
- at end deftypefun
-
- at 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
- at code{gpgme_op_card_edit} operation. It can be completed by calling
- at 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
- at var{ctx} or @var{key} is not a valid pointer.
- at 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
- at node Information About Trust Items
- at subsection Information About Trust Items
- at cindex trust item, information about
- at cindex trust item, attributes
- at 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}.
-
- at 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
- at 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}.
- at end deftypefun
-
- at 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
- at 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
- at 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}.
- at 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}.
-
- at deftypefun void gpgme_trust_item_release (@w{gpgme_trust_item_t @var{item}})
-The function @code{gpgme_trust_item_release} is an alias for
- at code{gpgme_trust_item_unref}.
- at 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}.
-
- at deftp {Data type} {enum gpgme_sig_stat_t}
- at 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:
+ at node Decrypt and Verify
+ at subsection Decrypt and Verify
+ at cindex decryption and verification
+ at cindex verification and decryption
+ at cindex signature check
+ at cindex cryptographic operation, decryption and verification
- at table @code
- at item GPGME_SIG_STAT_NONE
-This status should not occur in normal operation.
+ at 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
+ at var{plain}. If @var{cipher} contains signatures, they will be
+verified.
- at 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
+ at code{gpgme_op_verify_result} can be used to retrieve more information
+about the signatures.
- at 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
+ at code{gpgme_op_verify_result} in this case.
- at 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,
+ at 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.
+ at end deftypefun
- at 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.
+ at 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
+ at code{gpgme_op_decrypt_verify} operation. It can be completed by
+calling @code{gpgme_wait} on the context. @xref{Waiting For
+Completion}.
- at 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
+ at 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.
+ at end deftypefun
- at item GPGME_SIG_STAT_NOSIG
-This status indicates that the signature data provided was not a real
-signature.
- at item GPGME_SIG_STAT_ERROR
-This status indicates that there was some other error which prevented
-the signature verification.
+ at node Sign
+ at subsection Sign
+ at cindex signature, creation
+ at cindex sign
+ at cindex cryptographic operation, signing
- at 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
- at code{gpgme_get_sig_status}.
- at end table
- at 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).
- at 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:
+ at 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.
+ at end menu
- at example
- gpgme_verify_result_t result;
- gpgme_signature_t sig;
- result = gpgme_op_verify_result (ctx);
- sig = result->signatures;
+ at node Selecting Signers
+ at subsubsection Selecting Signers
+ at cindex signature, selecting signers
+ at 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;
+ at 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.
+ at end deftypefun
- case GPG_ERR_NO_PUBKEY:
- *r_stat = GPGME_SIG_STAT_NOKEY;
- break;
+ at 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;
- at end example
- at end deftypefun
-
- at 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:
-
- at 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;
- at end example
- at end deftypefun
-
- at 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:
-
- at 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;
- at end example
- at end deftypefun
-
- at 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:
-
- at 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);
- at end example
- at end deftypefun
-
-
- at node Decrypt and Verify
- at subsection Decrypt and Verify
- at cindex decryption and verification
- at cindex verification and decryption
- at cindex signature check
- at cindex cryptographic operation, decryption and verification
-
- at 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
- at var{plain}. If @var{cipher} contains signatures, they will be
-verified.
-
-After the operation completed, @code{gpgme_op_decrypt_result} and
- at 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
- at 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,
- at 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.
- at end deftypefun
-
- at 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
- at 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
- at 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.
- at end deftypefun
-
-
- at node Sign
- at subsection Sign
- at cindex signature, creation
- at cindex sign
- at 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).
-
- at 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.
- at end menu
-
-
- at node Selecting Signers
- at subsubsection Selecting Signers
- at cindex signature, selecting signers
- at 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.
-
- at 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.
- at end deftypefun
-
- at 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.
- at end deftypefun
+Calling this function acquires an additional reference for the key.
+ at 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.
+ at node Deprecated Functions
+ at appendix Deprecated Functions
+ at 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.
+
+ at strong{Warning:} These interfaces will be removed in a future version
+of @acronym{GPGME}.
+
+ at deftypefun void gpgme_key_release (@w{gpgme_key_t @var{key}})
+The function @code{gpgme_key_release} is equivalent to
+ at code{gpgme_key_unref}.
+ at end deftypefun
+
+ at deftypefun void gpgme_trust_item_release (@w{gpgme_trust_item_t @var{item}})
+The function @code{gpgme_trust_item_release} is an alias for
+ at code{gpgme_trust_item_unref}.
+ at end deftypefun
+
+
+ at 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:
+
+ at 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;
+ @}
+ at end example
+ at end deftypefun
+
+
+ at 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}})}
+ at tindex gpgme_edit_cb_t
+The @code{gpgme_edit_cb_t} type is the type of functions which
+ at 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.
+ at end deftp
+
+ at 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
+ at 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
+ at var{ctx} or @var{key} is not a valid pointer, and any error returned
+by the crypto engine or the edit callback handler.
+ at end deftypefun
+
+ at 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
+ at code{gpgme_op_interact_start} instead.
+
+The function @code{gpgme_op_edit_start} initiates a
+ at code{gpgme_op_edit} operation. It can be completed by calling
+ at 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
+ at var{ctx} or @var{key} is not a valid pointer.
+ at end deftypefun
+
+
+ at 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
+ at code{gpgme_op_edit}, but should be used to process the smart card corresponding to the key @var{key}.
+ at end deftypefun
+
+ at 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
+ at code{gpgme_op_card_edit} operation. It can be completed by calling
+ at 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
+ at var{ctx} or @var{key} is not a valid pointer.
+ at end deftypefun
+
+
+
+ at 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
+ at 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
+ at 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
+ at var{buffer}, and return the number of bytes actually read in
+ at 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
+ at code{0}. The callback function may support to reset its internal
+read pointer if it is invoked with @var{buffer} and @var{nread} being
+ at 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
+ at var{dh} or @var{readfunc} is not a valid pointer, and
+ at code{GPG_ERR_ENOMEM} if not enough memory is available.
+ at end deftypefun
+
+ at deftypefun gpgme_error_t gpgme_data_rewind (@w{gpgme_data_t @var{dh}})
+The function @code{gpgme_data_rewind} is equivalent to:
+
+ at example
+ return (gpgme_data_seek (dh, 0, SEEK_SET) == -1)
+ ? gpgme_error_from_errno (errno) : 0;
+ at end example
+ at end deftypefun
+
+
+ at 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:
+
+ at table @code
+ at 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.
+
+ at item GPGME_ATTR_FPR
+This is the fingerprint of a sub key. It is representable as a
+string.
+
+ at 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.
+
+ at item GPGME_ATTR_LEN
+This is the key length of a sub key. It is representable as a
+number.
+
+ at item GPGME_ATTR_CREATED
+This is the timestamp at creation time of a sub key. It is
+representable as a number.
+
+ at item GPGME_ATTR_EXPIRE
+This is the expiration time of a sub key. It is representable as a
+number.
+
+ at item GPGME_ATTR_OTRUST
+XXX FIXME (also for trust items)
+
+ at item GPGME_ATTR_USERID
+This is a user ID. There can be more than one user IDs in a
+ at 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.
+
+ at item GPGME_ATTR_NAME
+This is the name belonging to a user ID. It is representable as a string.
+
+ at item GPGME_ATTR_EMAIL
+This is the email address belonging to a user ID. It is representable
+as a string.
+
+ at item GPGME_ATTR_COMMENT
+This is the comment belonging to a user ID. It is representable as a
+string.
+
+ at 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.
+
+ at 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.
+
+ at 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.
+
+ at item GPGME_ATTR_LEVEL
+This is the trust level of a trust item.
+
+ at 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.
+
+ at 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.
+
+ at 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.
+
+ at 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.
+
+ at 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.
+
+ at 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.
+
+ at 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.
+
+ at 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.
+
+ at 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.
+
+ at 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.
+
+ at item GPGME_ATTR_SERIAL
+The X.509 issuer serial attribute of the key. It is representable as
+a string.
+
+ at item GPGME_ATTR_ISSUE
+The X.509 issuer name attribute of the key. It is representable as a
+string.
+
+ at item GPGME_ATTR_CHAINID
+The X.509 chain ID can be used to build the certification chain. It
+is representable as a string.
+ at end table
+ at end deftp
+
+ at 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}.
+ at end deftypefun
+
+ at 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
+ at var{reserved} not @code{NULL}.
+ at end deftypefun
+
+
+ at c
+ at c Key Signatures
+ at 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}.
+
+ at 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:
+
+ at table @code
+ at item GPGME_ATTR_KEYID
+This is the key ID of the key which was used for the signature. It is
+representable as a string.
+
+ at 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.
+
+ at item GPGME_ATTR_CREATED
+This is the timestamp at creation time of the signature. It is
+representable as a number.
+
+ at item GPGME_ATTR_EXPIRE
+This is the expiration time of the signature. It is representable as
+a number.
+
+ at item GPGME_ATTR_USERID
+This is the user ID associated with the signing key. The user ID is
+representable as a number.
+
+ at item GPGME_ATTR_NAME
+This is the name belonging to a user ID. It is representable as a string.
+
+ at item GPGME_ATTR_EMAIL
+This is the email address belonging to a user ID. It is representable
+as a string.
+
+ at item GPGME_ATTR_COMMENT
+This is the comment belonging to a user ID. It is representable as a
+string.
+
+ at 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
+ at code{0} otherwise.
+
+ at c @item GPGME_ATTR_KEY_EXPIRED
+ at c This specifies if a key signature is expired. It is representable as
+ at c a number, and is @code{1} if the key is revoked, and @code{0}
+ at c otherwise.
+ at c
+ at 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.
+
+ at 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.
+
+ at item GPGME_ATTR_SIG_STATUS
+This is the same value as returned by @code{gpgme_get_sig_status}.
+ at end table
+ at end deftp
+
+ at 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
+ at 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
+ at 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}.
+ at end deftypefun
+
+ at 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
+ at 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
+ at 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}.
+ at end deftypefun
+
+
+ at c node Information About Trust Items
+ at c subsection Information About Trust Items
+ at c cindex trust item, information about
+ at c cindex trust item, attributes
+ at 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}.
+
+ at 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
+ at 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}.
+ at end deftypefun
+
+ at 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
+ at 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
+ at 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}.
+ at end deftypefun
+
+
+ at deftp {Data type} {enum gpgme_sig_stat_t}
+ at 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:
+
+ at table @code
+ at item GPGME_SIG_STAT_NONE
+This status should not occur in normal operation.
+
+ at 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.
+
+ at 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.
+
+ at 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.
+
+ at 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.
+
+ at 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.
+
+ at item GPGME_SIG_STAT_NOSIG
+This status indicates that the signature data provided was not a real
+signature.
+
+ at item GPGME_SIG_STAT_ERROR
+This status indicates that there was some other error which prevented
+the signature verification.
+
+ at 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
+ at code{gpgme_get_sig_status}.
+ at end table
+ at end deftp
+
+ at 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:
+
+ at 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;
+ at end example
+ at end deftypefun
+
+ at 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:
+
+ at 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;
+ at end example
+ at end deftypefun
+
+ at 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:
+
+ at 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;
+ at end example
+ at end deftypefun
+
+ at 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:
+
+ at 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);
+ at end example
+ at end deftypefun
+
+
+
+
@include lesser.texi
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-gnupg/gpgme.git
More information about the Pkg-gnupg-commit
mailing list