diff options
| -rw-r--r-- | doc/gpgme.texi | 1382 |
1 files changed, 679 insertions, 703 deletions
diff --git a/doc/gpgme.texi b/doc/gpgme.texi index ad1a23a1..dc5a1407 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}. - -@deftypefun gpgme_error_t gpgme_data_new_with_read_cb (@w{gpgme_data_t *@var{dh}}, @w{int (*@var{readfunc})} (@w{void *@var{hook}}, @w{char *@var{buffer}}, @w{size_t @var{count}}, @w{size_t *@var{nread}}), @w{void *@var{hook_value}}) -The function @code{gpgme_data_new_with_read_cb} creates a new -@code{gpgme_data_t} object and uses the callback function @var{readfunc} -to retrieve the data on demand. As the callback function can supply -the data in any way it wants, this is the most flexible data type -@acronym{GPGME} provides. However, it can not be used to write data. - -The callback function receives @var{hook_value} as its first argument -whenever it is invoked. It should return up to @var{count} bytes in -@var{buffer}, and return the number of bytes actually read in -@var{nread}. It may return @code{0} in @var{nread} if no data is -currently available. To indicate @code{EOF} the function should -return with an error code of @code{-1} and set @var{nread} to -@code{0}. The callback function may support to reset its internal -read pointer if it is invoked with @var{buffer} and @var{nread} being -@code{NULL} and @var{count} being @code{0}. - -The function returns the error code @code{GPG_ERR_NO_ERROR} if the -data object was successfully created, @code{GPG_ERR_INV_VALUE} if -@var{dh} or @var{readfunc} is not a valid pointer, and -@code{GPG_ERR_ENOMEM} if not enough memory is available. -@end deftypefun - @node Destroying Data Buffers @section Destroying Data Buffers @@ -2122,20 +2093,6 @@ read/write position. If the function fails, -1 is returned and @var{errno} is set. @end deftypefun -The following function is deprecated and should not be used. It will -be removed in a future version of @acronym{GPGME}. - -@deftypefun gpgme_error_t gpgme_data_rewind (@w{gpgme_data_t @var{dh}}) -The function @code{gpgme_data_rewind} is equivalent to: - -@example - return (gpgme_data_seek (dh, 0, SEEK_SET) == -1) - ? gpgme_error_from_errno (errno) : 0; -@end example -@end deftypefun - - - @node Data Buffer Meta-Data @subsection Data Buffer Meta-Data @@ -2967,7 +2924,6 @@ section describes how such keys can be selected and manipulated. * Key objects:: Description of the key structures. * Listing Keys:: Browsing the list of available keys. * Information About Keys:: Requesting detailed information about keys. -* Key Signatures:: Listing the signatures on a key. * Manipulating Keys:: Operations on keys. * Generating Keys:: Creating new key pairs. * Signing Keys:: Adding key signatures to public keys. @@ -3505,276 +3461,6 @@ validity is ``u''. @end deftp -The following interfaces are deprecated and only provided for backward -compatibility. Don't use them. They will be removed in a future -version of @acronym{GPGME}. - -@deftp {Data type} gpgme_attr_t -The @code{gpgme_attr_t} type is used to specify a key or trust item -attribute. The following attributes are defined: - -@table @code -@item GPGME_ATTR_KEYID -This is the key ID of a sub key. It is representable as a string. - -For trust items, the trust item refers to the key with this ID. - -@item GPGME_ATTR_FPR -This is the fingerprint of a sub key. It is representable as a -string. - -@item GPGME_ATTR_ALGO -This is the crypto algorithm for which the sub key can be used. It -is representable as a string and as a number. The numbers correspond -to the @code{enum gcry_pk_algos} values in the gcrypt library. - -@item GPGME_ATTR_LEN -This is the key length of a sub key. It is representable as a -number. - -@item GPGME_ATTR_CREATED -This is the timestamp at creation time of a sub key. It is -representable as a number. - -@item GPGME_ATTR_EXPIRE -This is the expiration time of a sub key. It is representable as a -number. - -@item GPGME_ATTR_OTRUST -XXX FIXME (also for trust items) - -@item GPGME_ATTR_USERID -This is a user ID. There can be more than one user IDs in a -@var{gpgme_key_t} object. The first one (with index 0) is the primary -user ID. The user ID is representable as a number. - -For trust items, this is the user ID associated with this trust item. - -@item GPGME_ATTR_NAME -This is the name belonging to a user ID. It is representable as a string. - -@item GPGME_ATTR_EMAIL -This is the email address belonging to a user ID. It is representable -as a string. - -@item GPGME_ATTR_COMMENT -This is the comment belonging to a user ID. It is representable as a -string. - -@item GPGME_ATTR_VALIDITY -This is the validity belonging to a user ID. It is representable as a -string and as a number. See below for a list of available validities. - -For trust items, this is the validity that is associated with this -trust item. - -@item GPGME_ATTR_UID_REVOKED -This specifies if a user ID is revoked. It is representable as a -number, and is @code{1} if the user ID is revoked, and @code{0} -otherwise. - -@item GPGME_ATTR_UID_INVALID -This specifies if a user ID is invalid. It is representable as a -number, and is @code{1} if the user ID is invalid, and @code{0} -otherwise. - -@item GPGME_ATTR_LEVEL -This is the trust level of a trust item. - -@item GPGME_ATTR_TYPE -This returns information about the type of key. For the string function -this will eother be "PGP" or "X.509". The integer function returns 0 -for PGP and 1 for X.509. It is also used for the type of a trust item. - -@item GPGME_ATTR_IS_SECRET -This specifies if the key is a secret key. It is representable as a -number, and is @code{1} if the key is revoked, and @code{0} otherwise. - -@item GPGME_ATTR_KEY_REVOKED -This specifies if a sub key is revoked. It is representable as a -number, and is @code{1} if the key is revoked, and @code{0} otherwise. - -@item GPGME_ATTR_KEY_INVALID -This specifies if a sub key is invalid. It is representable as a -number, and is @code{1} if the key is invalid, and @code{0} otherwise. - -@item GPGME_ATTR_KEY_EXPIRED -This specifies if a sub key is expired. It is representable as a -number, and is @code{1} if the key is expired, and @code{0} otherwise. - -@item GPGME_ATTR_KEY_DISABLED -This specifies if a sub key is disabled. It is representable as a -number, and is @code{1} if the key is disabled, and @code{0} otherwise. - -@item GPGME_ATTR_KEY_CAPS -This is a description of the capabilities of a sub key. It is -representable as a string. The string contains the letter ``e'' if -the key can be used for encryption, ``s'' if the key can be used for -signatures, and ``c'' if the key can be used for certifications. - -@item GPGME_ATTR_CAN_ENCRYPT -This specifies if a sub key can be used for encryption. It is -representable as a number, and is @code{1} if the sub key can be used -for encryption, and @code{0} otherwise. - -@item GPGME_ATTR_CAN_SIGN -This specifies if a sub key can be used to create data signatures. It -is representable as a number, and is @code{1} if the sub key can be -used for signatures, and @code{0} otherwise. - -@item GPGME_ATTR_CAN_CERTIFY -This specifies if a sub key can be used to create key certificates. -It is representable as a number, and is @code{1} if the sub key can be -used for certifications, and @code{0} otherwise. - -@item GPGME_ATTR_SERIAL -The X.509 issuer serial attribute of the key. It is representable as -a string. - -@item GPGME_ATTR_ISSUE -The X.509 issuer name attribute of the key. It is representable as a -string. - -@item GPGME_ATTR_CHAINID -The X.509 chain ID can be used to build the certification chain. It -is representable as a string. -@end table -@end deftp - -@deftypefun {const char *} gpgme_key_get_string_attr (@w{gpgme_key_t @var{key}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) -The function @code{gpgme_key_get_string_attr} returns the value of the -string-representable attribute @var{what} of key @var{key}. If the -attribute is an attribute of a sub key or an user ID, @var{idx} -specifies the sub key or user ID of which the attribute value is -returned. The argument @var{reserved} is reserved for later use and -should be @code{NULL}. - -The string returned is only valid as long as the key is valid. - -The function returns @code{0} if an attribute can't be returned as a -string, @var{key} is not a valid pointer, @var{idx} out of range, -or @var{reserved} not @code{NULL}. -@end deftypefun - -@deftypefun {unsigned long} gpgme_key_get_ulong_attr (@w{gpgme_key_t @var{key}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) -The function @code{gpgme_key_get_ulong_attr} returns the value of the -number-representable attribute @var{what} of key @var{key}. If the -attribute is an attribute of a sub key or an user ID, @var{idx} -specifies the sub key or user ID of which the attribute value is -returned. The argument @var{reserved} is reserved for later use and -should be @code{NULL}. - -The function returns @code{0} if the attribute can't be returned as a -number, @var{key} is not a valid pointer, @var{idx} out of range, or -@var{reserved} not @code{NULL}. -@end deftypefun - - -@node Key Signatures -@subsection Key Signatures -@cindex key, signatures -@cindex signatures, on a key - -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. - -So, before using the below interfaces to retrieve the signatures on a -key, you have to make sure that the key was listed with signatures -enabled. One convenient, but blocking, way to do this is to use the -function @code{gpgme_get_key}. - -@deftp {Data type} gpgme_attr_t -The @code{gpgme_attr_t} type is used to specify a key signature -attribute. The following attributes are defined: - -@table @code -@item GPGME_ATTR_KEYID -This is the key ID of the key which was used for the signature. It is -representable as a string. - -@item GPGME_ATTR_ALGO -This is the crypto algorithm used to create the signature. It is -representable as a string and as a number. The numbers correspond to -the @code{enum gcry_pk_algos} values in the gcrypt library. - -@item GPGME_ATTR_CREATED -This is the timestamp at creation time of the signature. It is -representable as a number. - -@item GPGME_ATTR_EXPIRE -This is the expiration time of the signature. It is representable as -a number. - -@item GPGME_ATTR_USERID -This is the user ID associated with the signing key. The user ID is -representable as a number. - -@item GPGME_ATTR_NAME -This is the name belonging to a user ID. It is representable as a string. - -@item GPGME_ATTR_EMAIL -This is the email address belonging to a user ID. It is representable -as a string. - -@item GPGME_ATTR_COMMENT -This is the comment belonging to a user ID. It is representable as a -string. - -@item GPGME_ATTR_KEY_REVOKED -This specifies if a key signature is a revocation signature. It is -representable as a number, and is @code{1} if the key is revoked, and -@code{0} otherwise. - -@c @item GPGME_ATTR_KEY_EXPIRED -@c This specifies if a key signature is expired. It is representable as -@c a number, and is @code{1} if the key is revoked, and @code{0} -@c otherwise. -@c -@item GPGME_ATTR_SIG_CLASS -This specifies the signature class of a key signature. It is -representable as a number. The meaning is specific to the crypto -engine. - -@item GPGME_ATTR_SIG_CLASS -This specifies the signature class of a key signature. It is -representable as a number. The meaning is specific to the crypto -engine. - -@item GPGME_ATTR_SIG_STATUS -This is the same value as returned by @code{gpgme_get_sig_status}. -@end table -@end deftp - -@deftypefun {const char *} gpgme_key_sig_get_string_attr (@w{gpgme_key_t @var{key}}, @w{int @var{uid_idx}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) -The function @code{gpgme_key_sig_get_string_attr} returns the value of -the string-representable attribute @var{what} of the signature -@var{idx} on the user ID @var{uid_idx} in the key @var{key}. The -argument @var{reserved} is reserved for later use and should be -@code{NULL}. - -The string returned is only valid as long as the key is valid. - -The function returns @code{0} if an attribute can't be returned as a -string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx} -out of range, or @var{reserved} not @code{NULL}. -@end deftypefun - -@deftypefun {unsigned long} gpgme_key_sig_get_ulong_attr (@w{gpgme_key_t @var{key}}, @w{int @var{uid_idx}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) -The function @code{gpgme_key_sig_get_ulong_attr} returns the value of -the number-representable attribute @var{what} of the signature -@var{idx} on the user ID @var{uid_idx} in the key @var{key}. The -argument @var{reserved} is reserved for later use and should be -@code{NULL}. - -The function returns @code{0} if an attribute can't be returned as a -string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx} -out of range, or @var{reserved} not @code{NULL}. -@end deftypefun @node Manipulating Keys @@ -3793,16 +3479,6 @@ and all resources associated to it will be released. @end deftypefun -The following interface is deprecated and only provided for backward -compatibility. Don't use it. It will be removed in a future version -of @acronym{GPGME}. - -@deftypefun void gpgme_key_release (@w{gpgme_key_t @var{key}}) -The function @code{gpgme_key_release} is equivalent to -@code{gpgme_key_unref}. -@end deftypefun - - @node Generating Keys @subsection Generating Keys @cindex key, creation @@ -4644,24 +4320,6 @@ successfully. The returned pointer is only valid until the next operation is started on the context. @end deftypefun -The following interface is deprecated and only provided for backward -compatibility. Don't use it. It will be removed in a future version -of @acronym{GPGME}. - -@deftypefun gpgme_error_t gpgme_op_import_ext (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}}, @w{int *@var{nr}}) -The function @code{gpgme_op_import_ext} is equivalent to: - -@example - gpgme_error_t err = gpgme_op_import (ctx, keydata); - if (!err) - @{ - gpgme_import_result_t result = gpgme_op_import_result (ctx); - *nr = result->considered; - @} -@end example -@end deftypefun - - @node Deleting Keys @subsection Deleting Keys @cindex key, delete @@ -4866,80 +4524,6 @@ is not a valid pointer. @end deftypefun -@deftp {Data type} {gpgme_error_t (*gpgme_edit_cb_t) @ - (@w{void *@var{handle}}, @ - @w{gpgme_status_code_t @var{status}}, @ - @w{const char *@var{args}}, @ - @w{int @var{fd}})} -@tindex gpgme_edit_cb_t -The @code{gpgme_edit_cb_t} type is the type of functions which -@acronym{GPGME} calls if it a key edit operation is on-going. The -status code @var{status} and the argument line @var{args} are passed -through by @acronym{GPGME} from the crypto engine. The file -descriptor @var{fd} is -1 for normal status messages. If @var{status} -indicates a command rather than a status message, the response to the -command should be written to @var{fd}. The @var{handle} is provided -by the user at start of operation. - -The function should return @code{GPG_ERR_FALSE} if it did not handle -the status code, @code{0} for success, or any other error value. -@end deftp - -@deftypefun gpgme_error_t gpgme_op_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}}) -Note: This function is deprecated, please use -@code{gpgme_op_interact} instead. - -The function @code{gpgme_op_edit} processes the key @var{KEY} -interactively, using the edit callback function @var{FNC} with the -handle @var{HANDLE}. The callback is invoked for every status and -command request from the crypto engine. The output of the crypto -engine is written to the data object @var{out}. - -Note that the protocol between the callback function and the crypto -engine is specific to the crypto engine and no further support in -implementing this protocol correctly is provided by @acronym{GPGME}. - -The function returns the error code @code{GPG_ERR_NO_ERROR} if the -edit operation completes successfully, @code{GPG_ERR_INV_VALUE} if -@var{ctx} or @var{key} is not a valid pointer, and any error returned -by the crypto engine or the edit callback handler. -@end deftypefun - -@deftypefun gpgme_error_t gpgme_op_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}}) -Note: This function is deprecated, please use -@code{gpgme_op_interact_start} instead. - -The function @code{gpgme_op_edit_start} initiates a -@code{gpgme_op_edit} operation. It can be completed by calling -@code{gpgme_wait} on the context. @xref{Waiting For Completion}. - -The function returns the error code @code{GPG_ERR_NO_ERROR} if the -operation was started successfully, and @code{GPG_ERR_INV_VALUE} if -@var{ctx} or @var{key} is not a valid pointer. -@end deftypefun - - -@deftypefun gpgme_error_t gpgme_op_card_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}}) -Note: This function is deprecated, please use @code{gpgme_op_interact} -with the flag @code{GPGME_INTERACT_CARD} instead. - -The function @code{gpgme_op_card_edit} is analogous to -@code{gpgme_op_edit}, but should be used to process the smart card corresponding to the key @var{key}. -@end deftypefun - -@deftypefun gpgme_error_t gpgme_op_card_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}}) -Note: This function is deprecated, please use @code{gpgme_op_interact_start} -with the flag @code{GPGME_INTERACT_CARD} instead. - -The function @code{gpgme_op_card_edit_start} initiates a -@code{gpgme_op_card_edit} operation. It can be completed by calling -@code{gpgme_wait} on the context. @xref{Waiting For Completion}. - -The function returns the error code @code{GPG_ERR_NO_ERROR} if the -operation was started successfully, and @code{GPG_ERR_INV_VALUE} if -@var{ctx} or @var{key} is not a valid pointer. -@end deftypefun - @node Trust Item Management @section Trust Item Management @@ -4975,7 +4559,6 @@ The user name if @code{type} is 2. @menu * Listing Trust Items:: Browsing the list of available trust items. -* Information About Trust Items:: Requesting information about trust items. * Manipulating Trust Items:: Operations on trust items. @end menu @@ -5032,47 +4615,6 @@ time during the operation there was not enough memory available. @end deftypefun -@node Information About Trust Items -@subsection Information About Trust Items -@cindex trust item, information about -@cindex trust item, attributes -@cindex attributes, of a trust item - -The following interfaces are deprecated and only provided for backward -compatibility. Don't use them. They will be removed in a future -version of @acronym{GPGME}. - -Trust items have attributes which can be queried using the interfaces -below. The attribute identifiers are shared with those for key -attributes. @xref{Information About Keys}. - -@deftypefun {const char *} gpgme_trust_item_get_string_attr (@w{gpgme_trust_item_t @var{item}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) -The function @code{gpgme_trust_item_get_string_attr} returns the value -of the string-representable attribute @var{what} of trust item -@var{item}. The arguments @var{idx} and @var{reserved} are reserved -for later use and should be @code{0} and @code{NULL} respectively. - -The string returned is only valid as long as the key is valid. - -The function returns @code{0} if an attribute can't be returned as a -string, @var{key} is not a valid pointer, @var{idx} out of range, -or @var{reserved} not @code{NULL}. -@end deftypefun - -@deftypefun int gpgme_trust_item_get_int_attr (@w{gpgme_trust_item_t @var{item}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) -The function @code{gpgme_trust_item_get_int_attr} returns the value of -the number-representable attribute @var{what} of trust item -@var{item}. If the attribute occurs more than once in the trust item, -the index is specified by @var{idx}. However, currently no such -attribute exists, so @var{idx} should be @code{0}. The argument -@var{reserved} is reserved for later use and should be @code{NULL}. - -The function returns @code{0} if the attribute can't be returned as a -number, @var{key} is not a valid pointer, @var{idx} out of range, -or @var{reserved} not @code{NULL}. -@end deftypefun - - @node Manipulating Trust Items @subsection Manipulating Trust Items @cindex trust item, manipulation @@ -5090,16 +4632,6 @@ released. @end deftypefun -The following interface is deprecated and only provided for backward -compatibility. Don't use it. It will be removed in a future version -of @acronym{GPGME}. - -@deftypefun void gpgme_trust_item_release (@w{gpgme_trust_item_t @var{item}}) -The function @code{gpgme_trust_item_release} is an alias for -@code{gpgme_trust_item_unref}. -@end deftypefun - - @node Crypto Operations @section Crypto Operations @cindex cryptographic operation @@ -5521,238 +5053,6 @@ the context. @end deftypefun -The following interfaces are deprecated and only provided for backward -compatibility. Don't use them. They will be removed in a future -version of @acronym{GPGME}. - -@deftp {Data type} {enum gpgme_sig_stat_t} -@tindex gpgme_sig_stat_t -The @code{gpgme_sig_stat_t} type holds the result of a signature check, or -the combined result of all signatures. The following results are -possible: - -@table @code -@item GPGME_SIG_STAT_NONE -This status should not occur in normal operation. - -@item GPGME_SIG_STAT_GOOD -This status indicates that the signature is valid. For the combined -result this status means that all signatures are valid. - -@item GPGME_SIG_STAT_GOOD_EXP -This status indicates that the signature is valid but expired. For -the combined result this status means that all signatures are valid -and expired. - -@item GPGME_SIG_STAT_GOOD_EXPKEY -This status indicates that the signature is valid but the key used to -verify the signature has expired. For the combined result this status -means that all signatures are valid and all keys are expired. - -@item GPGME_SIG_STAT_BAD -This status indicates that the signature is invalid. For the combined -result this status means that all signatures are invalid. - -@item GPGME_SIG_STAT_NOKEY -This status indicates that the signature could not be verified due to -a missing key. For the combined result this status means that all -signatures could not be checked due to missing keys. - -@item GPGME_SIG_STAT_NOSIG -This status indicates that the signature data provided was not a real -signature. - -@item GPGME_SIG_STAT_ERROR -This status indicates that there was some other error which prevented -the signature verification. - -@item GPGME_SIG_STAT_DIFF -For the combined result this status means that at least two signatures -have a different status. You can get each key's status with -@code{gpgme_get_sig_status}. -@end table -@end deftp - -@deftypefun {const char *} gpgme_get_sig_status (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_sig_stat_t *@var{r_stat}}, @w{time_t *@var{r_created}}) -The function @code{gpgme_get_sig_status} is equivalent to: - -@example - gpgme_verify_result_t result; - gpgme_signature_t sig; - - result = gpgme_op_verify_result (ctx); - sig = result->signatures; - - while (sig && idx) - @{ - sig = sig->next; - idx--; - @} - if (!sig || idx) - return NULL; - - if (r_stat) - @{ - switch (gpg_err_code (sig->status)) - @{ - case GPG_ERR_NO_ERROR: - *r_stat = GPGME_SIG_STAT_GOOD; - break; - - case GPG_ERR_BAD_SIGNATURE: - *r_stat = GPGME_SIG_STAT_BAD; - break; - - case GPG_ERR_NO_PUBKEY: - *r_stat = GPGME_SIG_STAT_NOKEY; - break; - - case GPG_ERR_NO_DATA: - *r_stat = GPGME_SIG_STAT_NOSIG; - break; - - case GPG_ERR_SIG_EXPIRED: - *r_stat = GPGME_SIG_STAT_GOOD_EXP; - break; - - case GPG_ERR_KEY_EXPIRED: - *r_stat = GPGME_SIG_STAT_GOOD_EXPKEY; - break; - - default: - *r_stat = GPGME_SIG_STAT_ERROR; - break; - @} - @} - if (r_created) - *r_created = sig->timestamp; - return sig->fpr; -@end example -@end deftypefun - -@deftypefun {const char *} gpgme_get_sig_string_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{what}}, @w{int @var{whatidx}}) -The function @code{gpgme_get_sig_string_attr} is equivalent to: - -@example - gpgme_verify_result_t result; - gpgme_signature_t sig; - - result = gpgme_op_verify_result (ctx); - sig = result->signatures; - - while (sig && idx) - @{ - sig = sig->next; - idx--; - @} - if (!sig || idx) - return NULL; - - switch (what) - @{ - case GPGME_ATTR_FPR: - return sig->fpr; - - case GPGME_ATTR_ERRTOK: - if (whatidx == 1) - return sig->wrong_key_usage ? "Wrong_Key_Usage" : ""; - else - return ""; - default: - break; - @} - - return NULL; -@end example -@end deftypefun - -@deftypefun {const char *} gpgme_get_sig_ulong_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{waht}}, @w{int @var{whatidx}}) -The function @code{gpgme_get_sig_ulong_attr} is equivalent to: - -@example - gpgme_verify_result_t result; - gpgme_signature_t sig; - - result = gpgme_op_verify_result (ctx); - sig = result->signatures; - - while (sig && idx) - @{ - sig = sig->next; - idx--; - @} - if (!sig || idx) - return 0; - - switch (what) - @{ - case GPGME_ATTR_CREATED: - return sig->timestamp; - - case GPGME_ATTR_EXPIRE: - return sig->exp_timestamp; - - case GPGME_ATTR_VALIDITY: - return (unsigned long) sig->validity; - - case GPGME_ATTR_SIG_STATUS: - switch (sig->status) - @{ - case GPG_ERR_NO_ERROR: - return GPGME_SIG_STAT_GOOD; - - case GPG_ERR_BAD_SIGNATURE: - return GPGME_SIG_STAT_BAD; - - case GPG_ERR_NO_PUBKEY: - return GPGME_SIG_STAT_NOKEY; - - case GPG_ERR_NO_DATA: - return GPGME_SIG_STAT_NOSIG; - - case GPG_ERR_SIG_EXPIRED: - return GPGME_SIG_STAT_GOOD_EXP; - - case GPG_ERR_KEY_EXPIRED: - return GPGME_SIG_STAT_GOOD_EXPKEY; - - default: - return GPGME_SIG_STAT_ERROR; - @} - - case GPGME_ATTR_SIG_SUMMARY: - return sig->summary; - - default: - break; - @} - return 0; -@end example -@end deftypefun - -@deftypefun {const char *} gpgme_get_sig_key (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_key_t *@var{r_key}}) -The function @code{gpgme_get_sig_key} is equivalent to: - -@example - gpgme_verify_result_t result; - gpgme_signature_t sig; - - result = gpgme_op_verify_result (ctx); - sig = result->signatures; - - while (sig && idx) - @{ - sig = sig->next; - idx--; - @} - if (!sig || idx) - return gpg_error (GPG_ERR_EOF); - - return gpgme_get_key (ctx, sig->fpr, r_key, 0); -@end example -@end deftypefun - - @node Decrypt and Verify @subsection Decrypt and Verify @cindex decryption and verification @@ -7096,6 +6396,682 @@ your application. If you are asked to send a log file, make sure that you run your tests only with play data. +@node Deprecated Functions +@appendix Deprecated Functions +@cindex deprecated + +For backward compatibility @acronym{GPGME} has a number of functions, +data types and constants which are deprecated and should not be used +anymore. We document here those which are really old to help +understanding old code and to allow migration to their modern +counterparts. + +@strong{Warning:} These interfaces will be removed in a future version +of @acronym{GPGME}. + +@deftypefun void gpgme_key_release (@w{gpgme_key_t @var{key}}) +The function @code{gpgme_key_release} is equivalent to +@code{gpgme_key_unref}. +@end deftypefun + +@deftypefun void gpgme_trust_item_release (@w{gpgme_trust_item_t @var{item}}) +The function @code{gpgme_trust_item_release} is an alias for +@code{gpgme_trust_item_unref}. +@end deftypefun + + +@deftypefun gpgme_error_t gpgme_op_import_ext (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}}, @w{int *@var{nr}}) +The function @code{gpgme_op_import_ext} is equivalent to: + +@example + gpgme_error_t err = gpgme_op_import (ctx, keydata); + if (!err) + @{ + gpgme_import_result_t result = gpgme_op_import_result (ctx); + *nr = result->considered; + @} +@end example +@end deftypefun + + +@deftp {Data type} {gpgme_error_t (*gpgme_edit_cb_t) @ + (@w{void *@var{handle}}, @ + @w{gpgme_status_code_t @var{status}}, @ + @w{const char *@var{args}}, @ + @w{int @var{fd}})} +@tindex gpgme_edit_cb_t +The @code{gpgme_edit_cb_t} type is the type of functions which +@acronym{GPGME} calls if it a key edit operation is on-going. The +status code @var{status} and the argument line @var{args} are passed +through by @acronym{GPGME} from the crypto engine. The file +descriptor @var{fd} is -1 for normal status messages. If @var{status} +indicates a command rather than a status message, the response to the +command should be written to @var{fd}. The @var{handle} is provided +by the user at start of operation. + +The function should return @code{GPG_ERR_FALSE} if it did not handle +the status code, @code{0} for success, or any other error value. +@end deftp + +@deftypefun gpgme_error_t gpgme_op_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}}) +Note: This function is deprecated, please use +@code{gpgme_op_interact} instead. + +The function @code{gpgme_op_edit} processes the key @var{KEY} +interactively, using the edit callback function @var{FNC} with the +handle @var{HANDLE}. The callback is invoked for every status and +command request from the crypto engine. The output of the crypto +engine is written to the data object @var{out}. + +Note that the protocol between the callback function and the crypto +engine is specific to the crypto engine and no further support in +implementing this protocol correctly is provided by @acronym{GPGME}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +edit operation completes successfully, @code{GPG_ERR_INV_VALUE} if +@var{ctx} or @var{key} is not a valid pointer, and any error returned +by the crypto engine or the edit callback handler. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}}) +Note: This function is deprecated, please use +@code{gpgme_op_interact_start} instead. + +The function @code{gpgme_op_edit_start} initiates a +@code{gpgme_op_edit} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +operation was started successfully, and @code{GPG_ERR_INV_VALUE} if +@var{ctx} or @var{key} is not a valid pointer. +@end deftypefun + + +@deftypefun gpgme_error_t gpgme_op_card_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}}) +Note: This function is deprecated, please use @code{gpgme_op_interact} +with the flag @code{GPGME_INTERACT_CARD} instead. + +The function @code{gpgme_op_card_edit} is analogous to +@code{gpgme_op_edit}, but should be used to process the smart card corresponding to the key @var{key}. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_card_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}}) +Note: This function is deprecated, please use @code{gpgme_op_interact_start} +with the flag @code{GPGME_INTERACT_CARD} instead. + +The function @code{gpgme_op_card_edit_start} initiates a +@code{gpgme_op_card_edit} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +operation was started successfully, and @code{GPG_ERR_INV_VALUE} if +@var{ctx} or @var{key} is not a valid pointer. +@end deftypefun + + + +@deftypefun gpgme_error_t gpgme_data_new_with_read_cb (@w{gpgme_data_t *@var{dh}}, @w{int (*@var{readfunc})} (@w{void *@var{hook}}, @w{char *@var{buffer}}, @w{size_t @var{count}}, @w{size_t *@var{nread}}), @w{void *@var{hook_value}}) +The function @code{gpgme_data_new_with_read_cb} creates a new +@code{gpgme_data_t} object and uses the callback function @var{readfunc} +to retrieve the data on demand. As the callback function can supply +the data in any way it wants, this is the most flexible data type +@acronym{GPGME} provides. However, it can not be used to write data. + +The callback function receives @var{hook_value} as its first argument +whenever it is invoked. It should return up to @var{count} bytes in +@var{buffer}, and return the number of bytes actually read in +@var{nread}. It may return @code{0} in @var{nread} if no data is +currently available. To indicate @code{EOF} the function should +return with an error code of @code{-1} and set @var{nread} to +@code{0}. The callback function may support to reset its internal +read pointer if it is invoked with @var{buffer} and @var{nread} being +@code{NULL} and @var{count} being @code{0}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +data object was successfully created, @code{GPG_ERR_INV_VALUE} if +@var{dh} or @var{readfunc} is not a valid pointer, and +@code{GPG_ERR_ENOMEM} if not enough memory is available. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_data_rewind (@w{gpgme_data_t @var{dh}}) +The function @code{gpgme_data_rewind} is equivalent to: + +@example + return (gpgme_data_seek (dh, 0, SEEK_SET) == -1) + ? gpgme_error_from_errno (errno) : 0; +@end example +@end deftypefun + + +@deftp {Data type} gpgme_attr_t +The @code{gpgme_attr_t} type is used to specify a key or trust item +attribute. The following attributes are defined: + +@table @code +@item GPGME_ATTR_KEYID +This is the key ID of a sub key. It is representable as a string. + +For trust items, the trust item refers to the key with this ID. + +@item GPGME_ATTR_FPR +This is the fingerprint of a sub key. It is representable as a +string. + +@item GPGME_ATTR_ALGO +This is the crypto algorithm for which the sub key can be used. It +is representable as a string and as a number. The numbers correspond +to the @code{enum gcry_pk_algos} values in the gcrypt library. + +@item GPGME_ATTR_LEN +This is the key length of a sub key. It is representable as a +number. + +@item GPGME_ATTR_CREATED +This is the timestamp at creation time of a sub key. It is +representable as a number. + +@item GPGME_ATTR_EXPIRE +This is the expiration time of a sub key. It is representable as a +number. + +@item GPGME_ATTR_OTRUST +XXX FIXME (also for trust items) + +@item GPGME_ATTR_USERID +This is a user ID. There can be more than one user IDs in a +@var{gpgme_key_t} object. The first one (with index 0) is the primary +user ID. The user ID is representable as a number. + +For trust items, this is the user ID associated with this trust item. + +@item GPGME_ATTR_NAME +This is the name belonging to a user ID. It is representable as a string. + +@item GPGME_ATTR_EMAIL +This is the email address belonging to a user ID. It is representable +as a string. + +@item GPGME_ATTR_COMMENT +This is the comment belonging to a user ID. It is representable as a +string. + +@item GPGME_ATTR_VALIDITY +This is the validity belonging to a user ID. It is representable as a +string and as a number. See below for a list of available validities. + +For trust items, this is the validity that is associated with this +trust item. + +@item GPGME_ATTR_UID_REVOKED +This specifies if a user ID is revoked. It is representable as a +number, and is @code{1} if the user ID is revoked, and @code{0} +otherwise. + +@item GPGME_ATTR_UID_INVALID +This specifies if a user ID is invalid. It is representable as a +number, and is @code{1} if the user ID is invalid, and @code{0} +otherwise. + +@item GPGME_ATTR_LEVEL +This is the trust level of a trust item. + +@item GPGME_ATTR_TYPE +This returns information about the type of key. For the string function +this will eother be "PGP" or "X.509". The integer function returns 0 +for PGP and 1 for X.509. It is also used for the type of a trust item. + +@item GPGME_ATTR_IS_SECRET +This specifies if the key is a secret key. It is representable as a +number, and is @code{1} if the key is revoked, and @code{0} otherwise. + +@item GPGME_ATTR_KEY_REVOKED +This specifies if a sub key is revoked. It is representable as a +number, and is @code{1} if the key is revoked, and @code{0} otherwise. + +@item GPGME_ATTR_KEY_INVALID +This specifies if a sub key is invalid. It is representable as a +number, and is @code{1} if the key is invalid, and @code{0} otherwise. + +@item GPGME_ATTR_KEY_EXPIRED +This specifies if a sub key is expired. It is representable as a +number, and is @code{1} if the key is expired, and @code{0} otherwise. + +@item GPGME_ATTR_KEY_DISABLED +This specifies if a sub key is disabled. It is representable as a +number, and is @code{1} if the key is disabled, and @code{0} otherwise. + +@item GPGME_ATTR_KEY_CAPS +This is a description of the capabilities of a sub key. It is +representable as a string. The string contains the letter ``e'' if +the key can be used for encryption, ``s'' if the key can be used for +signatures, and ``c'' if the key can be used for certifications. + +@item GPGME_ATTR_CAN_ENCRYPT +This specifies if a sub key can be used for encryption. It is +representable as a number, and is @code{1} if the sub key can be used +for encryption, and @code{0} otherwise. + +@item GPGME_ATTR_CAN_SIGN +This specifies if a sub key can be used to create data signatures. It +is representable as a number, and is @code{1} if the sub key can be +used for signatures, and @code{0} otherwise. + +@item GPGME_ATTR_CAN_CERTIFY +This specifies if a sub key can be used to create key certificates. +It is representable as a number, and is @code{1} if the sub key can be +used for certifications, and @code{0} otherwise. + +@item GPGME_ATTR_SERIAL +The X.509 issuer serial attribute of the key. It is representable as +a string. + +@item GPGME_ATTR_ISSUE +The X.509 issuer name attribute of the key. It is representable as a +string. + +@item GPGME_ATTR_CHAINID +The X.509 chain ID can be used to build the certification chain. It +is representable as a string. +@end table +@end deftp + +@deftypefun {const char *} gpgme_key_get_string_attr (@w{gpgme_key_t @var{key}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) +The function @code{gpgme_key_get_string_attr} returns the value of the +string-representable attribute @var{what} of key @var{key}. If the +attribute is an attribute of a sub key or an user ID, @var{idx} +specifies the sub key or user ID of which the attribute value is +returned. The argument @var{reserved} is reserved for later use and +should be @code{NULL}. + +The string returned is only valid as long as the key is valid. + +The function returns @code{0} if an attribute can't be returned as a +string, @var{key} is not a valid pointer, @var{idx} out of range, +or @var{reserved} not @code{NULL}. +@end deftypefun + +@deftypefun {unsigned long} gpgme_key_get_ulong_attr (@w{gpgme_key_t @var{key}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) +The function @code{gpgme_key_get_ulong_attr} returns the value of the +number-representable attribute @var{what} of key @var{key}. If the +attribute is an attribute of a sub key or an user ID, @var{idx} +specifies the sub key or user ID of which the attribute value is +returned. The argument @var{reserved} is reserved for later use and +should be @code{NULL}. + +The function returns @code{0} if the attribute can't be returned as a +number, @var{key} is not a valid pointer, @var{idx} out of range, or +@var{reserved} not @code{NULL}. +@end deftypefun + + +@c +@c Key Signatures +@c +The signatures on a key are only available if the key was retrieved +via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode +enabled, because it is expensive to retrieve all signatures of a key. + +So, before using the below interfaces to retrieve the signatures on a +key, you have to make sure that the key was listed with signatures +enabled. One convenient, but blocking, way to do this is to use the +function @code{gpgme_get_key}. + +@deftp {Data type} gpgme_attr_t +The @code{gpgme_attr_t} type is used to specify a key signature +attribute. The following attributes are defined: + +@table @code +@item GPGME_ATTR_KEYID +This is the key ID of the key which was used for the signature. It is +representable as a string. + +@item GPGME_ATTR_ALGO +This is the crypto algorithm used to create the signature. It is +representable as a string and as a number. The numbers correspond to +the @code{enum gcry_pk_algos} values in the gcrypt library. + +@item GPGME_ATTR_CREATED +This is the timestamp at creation time of the signature. It is +representable as a number. + +@item GPGME_ATTR_EXPIRE +This is the expiration time of the signature. It is representable as +a number. + +@item GPGME_ATTR_USERID +This is the user ID associated with the signing key. The user ID is +representable as a number. + +@item GPGME_ATTR_NAME +This is the name belonging to a user ID. It is representable as a string. + +@item GPGME_ATTR_EMAIL +This is the email address belonging to a user ID. It is representable +as a string. + +@item GPGME_ATTR_COMMENT +This is the comment belonging to a user ID. It is representable as a +string. + +@item GPGME_ATTR_KEY_REVOKED +This specifies if a key signature is a revocation signature. It is +representable as a number, and is @code{1} if the key is revoked, and +@code{0} otherwise. + +@c @item GPGME_ATTR_KEY_EXPIRED +@c This specifies if a key signature is expired. It is representable as +@c a number, and is @code{1} if the key is revoked, and @code{0} +@c otherwise. +@c +@item GPGME_ATTR_SIG_CLASS +This specifies the signature class of a key signature. It is +representable as a number. The meaning is specific to the crypto +engine. + +@item GPGME_ATTR_SIG_CLASS +This specifies the signature class of a key signature. It is +representable as a number. The meaning is specific to the crypto +engine. + +@item GPGME_ATTR_SIG_STATUS +This is the same value as returned by @code{gpgme_get_sig_status}. +@end table +@end deftp + +@deftypefun {const char *} gpgme_key_sig_get_string_attr (@w{gpgme_key_t @var{key}}, @w{int @var{uid_idx}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) +The function @code{gpgme_key_sig_get_string_attr} returns the value of +the string-representable attribute @var{what} of the signature +@var{idx} on the user ID @var{uid_idx} in the key @var{key}. The +argument @var{reserved} is reserved for later use and should be +@code{NULL}. + +The string returned is only valid as long as the key is valid. + +The function returns @code{0} if an attribute can't be returned as a +string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx} +out of range, or @var{reserved} not @code{NULL}. +@end deftypefun + +@deftypefun {unsigned long} gpgme_key_sig_get_ulong_attr (@w{gpgme_key_t @var{key}}, @w{int @var{uid_idx}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) +The function @code{gpgme_key_sig_get_ulong_attr} returns the value of +the number-representable attribute @var{what} of the signature +@var{idx} on the user ID @var{uid_idx} in the key @var{key}. The +argument @var{reserved} is reserved for later use and should be +@code{NULL}. + +The function returns @code{0} if an attribute can't be returned as a +string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx} +out of range, or @var{reserved} not @code{NULL}. +@end deftypefun + + +@c node Information About Trust Items +@c subsection Information About Trust Items +@c cindex trust item, information about +@c cindex trust item, attributes +@c cindex attributes, of a trust item + +Trust items have attributes which can be queried using the interfaces +below. The attribute identifiers are shared with those for key +attributes. @xref{Information About Keys}. + +@deftypefun {const char *} gpgme_trust_item_get_string_attr (@w{gpgme_trust_item_t @var{item}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) +The function @code{gpgme_trust_item_get_string_attr} returns the value +of the string-representable attribute @var{what} of trust item +@var{item}. The arguments @var{idx} and @var{reserved} are reserved +for later use and should be @code{0} and @code{NULL} respectively. + +The string returned is only valid as long as the key is valid. + +The function returns @code{0} if an attribute can't be returned as a +string, @var{key} is not a valid pointer, @var{idx} out of range, +or @var{reserved} not @code{NULL}. +@end deftypefun + +@deftypefun int gpgme_trust_item_get_int_attr (@w{gpgme_trust_item_t @var{item}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) +The function @code{gpgme_trust_item_get_int_attr} returns the value of +the number-representable attribute @var{what} of trust item +@var{item}. If the attribute occurs more than once in the trust item, +the index is specified by @var{idx}. However, currently no such +attribute exists, so @var{idx} should be @code{0}. The argument +@var{reserved} is reserved for later use and should be @code{NULL}. + +The function returns @code{0} if the attribute can't be returned as a +number, @var{key} is not a valid pointer, @var{idx} out of range, +or @var{reserved} not @code{NULL}. +@end deftypefun + + +@deftp {Data type} {enum gpgme_sig_stat_t} +@tindex gpgme_sig_stat_t +The @code{gpgme_sig_stat_t} type holds the result of a signature check, or +the combined result of all signatures. The following results are +possible: + +@table @code +@item GPGME_SIG_STAT_NONE +This status should not occur in normal operation. + +@item GPGME_SIG_STAT_GOOD +This status indicates that the signature is valid. For the combined +result this status means that all signatures are valid. + +@item GPGME_SIG_STAT_GOOD_EXP +This status indicates that the signature is valid but expired. For +the combined result this status means that all signatures are valid +and expired. + +@item GPGME_SIG_STAT_GOOD_EXPKEY +This status indicates that the signature is valid but the key used to +verify the signature has expired. For the combined result this status +means that all signatures are valid and all keys are expired. + +@item GPGME_SIG_STAT_BAD +This status indicates that the signature is invalid. For the combined +result this status means that all signatures are invalid. + +@item GPGME_SIG_STAT_NOKEY +This status indicates that the signature could not be verified due to +a missing key. For the combined result this status means that all +signatures could not be checked due to missing keys. + +@item GPGME_SIG_STAT_NOSIG +This status indicates that the signature data provided was not a real +signature. + +@item GPGME_SIG_STAT_ERROR +This status indicates that there was some other error which prevented +the signature verification. + +@item GPGME_SIG_STAT_DIFF +For the combined result this status means that at least two signatures +have a different status. You can get each key's status with +@code{gpgme_get_sig_status}. +@end table +@end deftp + +@deftypefun {const char *} gpgme_get_sig_status (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_sig_stat_t *@var{r_stat}}, @w{time_t *@var{r_created}}) +The function @code{gpgme_get_sig_status} is equivalent to: + +@example + gpgme_verify_result_t result; + gpgme_signature_t sig; + + result = gpgme_op_verify_result (ctx); + sig = result->signatures; + + while (sig && idx) + @{ + sig = sig->next; + idx--; + @} + if (!sig || idx) + return NULL; + + if (r_stat) + @{ + switch (gpg_err_code (sig->status)) + @{ + case GPG_ERR_NO_ERROR: + *r_stat = GPGME_SIG_STAT_GOOD; + break; + + case GPG_ERR_BAD_SIGNATURE: + *r_stat = GPGME_SIG_STAT_BAD; + break; + + case GPG_ERR_NO_PUBKEY: + *r_stat = GPGME_SIG_STAT_NOKEY; + break; + + case GPG_ERR_NO_DATA: + *r_stat = GPGME_SIG_STAT_NOSIG; + break; + + case GPG_ERR_SIG_EXPIRED: + *r_stat = GPGME_SIG_STAT_GOOD_EXP; + break; + + case GPG_ERR_KEY_EXPIRED: + *r_stat = GPGME_SIG_STAT_GOOD_EXPKEY; + break; + + default: + *r_stat = GPGME_SIG_STAT_ERROR; + break; + @} + @} + if (r_created) + *r_created = sig->timestamp; + return sig->fpr; +@end example +@end deftypefun + +@deftypefun {const char *} gpgme_get_sig_string_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{what}}, @w{int @var{whatidx}}) +The function @code{gpgme_get_sig_string_attr} is equivalent to: + +@example + gpgme_verify_result_t result; + gpgme_signature_t sig; + + result = gpgme_op_verify_result (ctx); + sig = result->signatures; + + while (sig && idx) + @{ + sig = sig->next; + idx--; + @} + if (!sig || idx) + return NULL; + + switch (what) + @{ + case GPGME_ATTR_FPR: + return sig->fpr; + + case GPGME_ATTR_ERRTOK: + if (whatidx == 1) + return sig->wrong_key_usage ? "Wrong_Key_Usage" : ""; + else + return ""; + default: + break; + @} + + return NULL; +@end example +@end deftypefun + +@deftypefun {const char *} gpgme_get_sig_ulong_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{waht}}, @w{int @var{whatidx}}) +The function @code{gpgme_get_sig_ulong_attr} is equivalent to: + +@example + gpgme_verify_result_t result; + gpgme_signature_t sig; + + result = gpgme_op_verify_result (ctx); + sig = result->signatures; + + while (sig && idx) + @{ + sig = sig->next; + idx--; + @} + if (!sig || idx) + return 0; + + switch (what) + @{ + case GPGME_ATTR_CREATED: + return sig->timestamp; + + case GPGME_ATTR_EXPIRE: + return sig->exp_timestamp; + + case GPGME_ATTR_VALIDITY: + return (unsigned long) sig->validity; + + case GPGME_ATTR_SIG_STATUS: + switch (sig->status) + @{ + case GPG_ERR_NO_ERROR: + return GPGME_SIG_STAT_GOOD; + + case GPG_ERR_BAD_SIGNATURE: + return GPGME_SIG_STAT_BAD; + + case GPG_ERR_NO_PUBKEY: + return GPGME_SIG_STAT_NOKEY; + + case GPG_ERR_NO_DATA: + return GPGME_SIG_STAT_NOSIG; + + case GPG_ERR_SIG_EXPIRED: + return GPGME_SIG_STAT_GOOD_EXP; + + case GPG_ERR_KEY_EXPIRED: + return GPGME_SIG_STAT_GOOD_EXPKEY; + + default: + return GPGME_SIG_STAT_ERROR; + @} + + case GPGME_ATTR_SIG_SUMMARY: + return sig->summary; + + default: + break; + @} + return 0; +@end example +@end deftypefun + +@deftypefun {const char *} gpgme_get_sig_key (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_key_t *@var{r_key}}) +The function @code{gpgme_get_sig_key} is equivalent to: + +@example + gpgme_verify_result_t result; + gpgme_signature_t sig; + + result = gpgme_op_verify_result (ctx); + sig = result->signatures; + + while (sig && idx) + @{ + sig = sig->next; + idx--; + @} + if (!sig || idx) + return gpg_error (GPG_ERR_EOF); + + return gpgme_get_key (ctx, sig->fpr, r_key, 0); +@end example +@end deftypefun + + + + @include lesser.texi |