From 00f95e0fad2ef438f78eabb7881b56568466f666 Mon Sep 17 00:00:00 2001 From: Werner Koch Date: Fri, 16 Sep 2016 12:20:33 +0200 Subject: doc: Move description of most deprecated functions to a new appendix. -- Signed-off-by: Werner Koch --- doc/gpgme.texi | 2226 ++++++++++++++++++++++++++++---------------------------- 1 file changed, 1101 insertions(+), 1125 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,750 +3461,470 @@ validity is ``u''. @end deftp -The following interfaces are deprecated and only provided for backward -compatibility. Don't use them. They will be removed in a future -version of @acronym{GPGME}. -@deftp {Data type} gpgme_attr_t -The @code{gpgme_attr_t} type is used to specify a key or trust item -attribute. The following attributes are defined: -@table @code -@item GPGME_ATTR_KEYID -This is the key ID of a sub key. It is representable as a string. +@node Manipulating Keys +@subsection Manipulating Keys +@cindex key, manipulation -For trust items, the trust item refers to the key with this ID. +@deftypefun void gpgme_key_ref (@w{gpgme_key_t @var{key}}) +The function @code{gpgme_key_ref} acquires an additional reference for +the key @var{key}. +@end deftypefun -@item GPGME_ATTR_FPR -This is the fingerprint of a sub key. It is representable as a -string. +@deftypefun void gpgme_key_unref (@w{gpgme_key_t @var{key}}) +The function @code{gpgme_key_unref} releases a reference for the key +@var{key}. If this was the last reference, the key will be destroyed +and all resources associated to it will be released. +@end deftypefun -@item GPGME_ATTR_ALGO -This is the crypto algorithm for which the sub key can be used. It -is representable as a string and as a number. The numbers correspond -to the @code{enum gcry_pk_algos} values in the gcrypt library. -@item GPGME_ATTR_LEN -This is the key length of a sub key. It is representable as a -number. +@node Generating Keys +@subsection Generating Keys +@cindex key, creation +@cindex key ring, add -@item GPGME_ATTR_CREATED -This is the timestamp at creation time of a sub key. It is -representable as a number. +GPGME provides a set of functions to create public key pairs. Most of +these functions require the use of GnuPG 2.1 and later; for older +GnuPG versions the @code{gpgme_op_genkey} function can be used. +Existing code which wants to update to the new functions or new code +which shall supports older GnuPG versions may try the new functions +first and provide a fallback to the old function if the error code +@code{GPG_ERR_NOT_SUPPORTED} is received. -@item GPGME_ATTR_EXPIRE -This is the expiration time of a sub key. It is representable as a -number. +@c +@c gpgme_op_createkey +@c +@deftypefun gpgme_error_t gpgme_op_createkey @ + (@w{gpgme_ctx_t @var{ctx}}, @ + @w{const char *@var{userid}}, @ + @w{const char *@var{algo}}, @ + @w{unsigned long @var{reserved}}, @ + @w{unsigned long @var{expires}}, @ + @w{gpgme_key_t @var{extrakey}}, @ + @w{unsigned int @var{flags}}); -@item GPGME_ATTR_OTRUST -XXX FIXME (also for trust items) +The function @code{gpgme_op_createkey} generates a new key for the +procotol active in the context @var{ctx}. As of now this function +does only work for OpenPGP and requires at least version 2.1.13 of +GnuPG. -@item GPGME_ATTR_USERID -This is a user ID. There can be more than one user IDs in a -@var{gpgme_key_t} object. The first one (with index 0) is the primary -user ID. The user ID is representable as a number. +@var{userid} is commonly the mail address associated with the key. +GPGME does not require a specificy syntax but if more than a mail +address is given, RFC-822 style format is suggested. The value is +expected to be in UTF-8 encoding (i.e. no IDN encoding for mail +addresses). This is a required parameter. -For trust items, this is the user ID associated with this trust item. +@var{algo} specifies the algorithm for the new key (actually a keypair +of public and private key). For a list of supported algorithms, see +the GnuPG manual. If @var{algo} is @code{NULL} or the string +"default", the key is generated using the default algorithm of the +engine. If the string "future-default" is used the engine may use an +algorithm which is planned to be the default in a future release of +the engine; however existing implementation of the protocol may not be +able to already handle such future algorithms. For the OpenPGP +protocol, the specification of a default algorithm, without requesting +a non-default usage via @var{flags}, triggers the creation of a +primary key plus a secondary key (subkey). -@item GPGME_ATTR_NAME -This is the name belonging to a user ID. It is representable as a string. +@var{reserved} must be set to zero. -@item GPGME_ATTR_EMAIL -This is the email address belonging to a user ID. It is representable -as a string. +@var{expires} can be set to the number of seconds since Epoch of the +desired expiration date in UTC for the new key. Using 0 does not +set an expiration date. Note that this parameter takes an unsigned long +value and not a @code{time_t} to avoid problems on systems which use a +signed 32 bit @code{time_t}. Note further that the OpenPGP protocol +uses 32 bit values for timestamps and thus can only encode dates up to +the year 2106. -@item GPGME_ATTR_COMMENT -This is the comment belonging to a user ID. It is representable as a -string. +@var{extrakey} is currently not used and must be set to @code{NULL}. +A future version of GPGME may use this parameter to create X.509 keys. -@item GPGME_ATTR_VALIDITY -This is the validity belonging to a user ID. It is representable as a -string and as a number. See below for a list of available validities. +@var{flags} can be set to the bit-wise OR of the following flags: -For trust items, this is the validity that is associated with this -trust item. +@table @code +@item GPGME_CREATE_SIGN +@itemx GPGME_CREATE_ENCR +@itemx GPGME_CREATE_CERT +@itemx GPGME_CREATE_AUTH +Do not create the key with the default capabilities (key usage) of the +requested algorithm but use those explicitly given by these flags: +``signing'', ``encryption'', ``certification'', or ``authentication''. +The allowed combinations depend on the algorithm. -@item GPGME_ATTR_UID_REVOKED -This specifies if a user ID is revoked. It is representable as a -number, and is @code{1} if the user ID is revoked, and @code{0} -otherwise. +If any of these flags are set and a default algorithm has been +selected only one key is created in the case of the OpenPGP +protocol. -@item GPGME_ATTR_UID_INVALID -This specifies if a user ID is invalid. It is representable as a -number, and is @code{1} if the user ID is invalid, and @code{0} -otherwise. +@item GPGME_CREATE_NOPASSWD +Request generation of the key without password protection. -@item GPGME_ATTR_LEVEL -This is the trust level of a trust item. +@item GPGME_CREATE_SELFSIGNED +For an X.509 key do not create a CSR but a self-signed certificate. +This has not yet been implemented. -@item GPGME_ATTR_TYPE -This returns information about the type of key. For the string function -this will eother be "PGP" or "X.509". The integer function returns 0 -for PGP and 1 for X.509. It is also used for the type of a trust item. +@item GPGME_CREATE_NOSTORE +Do not store the created key in the local key database. +This has not yet been implemented. -@item GPGME_ATTR_IS_SECRET -This specifies if the key is a secret key. It is representable as a -number, and is @code{1} if the key is revoked, and @code{0} otherwise. +@item GPGME_CREATE_WANTPUB +@itemx GPGME_CREATE_WANTSEC +Return the public or secret key as part of the result structure. +This has not yet been implemented. -@item GPGME_ATTR_KEY_REVOKED -This specifies if a sub key is revoked. It is representable as a -number, and is @code{1} if the key is revoked, and @code{0} otherwise. +@item GPGME_CREATE_FORCE +The engine does not allow the creation of a key with a user ID +already existing in the local key database. This flag can be used to +override this check. -@item GPGME_ATTR_KEY_INVALID -This specifies if a sub key is invalid. It is representable as a -number, and is @code{1} if the key is invalid, and @code{0} otherwise. +@end table -@item GPGME_ATTR_KEY_EXPIRED -This specifies if a sub key is expired. It is representable as a -number, and is @code{1} if the key is expired, and @code{0} otherwise. +After the operation completed successfully, information about the +created key can be retrieved with @code{gpgme_op_genkey_result}. -@item GPGME_ATTR_KEY_DISABLED -This specifies if a sub key is disabled. It is representable as a -number, and is @code{1} if the key is disabled, and @code{0} otherwise. +The function returns zero on success, @code{GPG_ERR_NOT_SUPPORTED} if +the engine does not support the command, or a bunch of other error +codes. -@item GPGME_ATTR_KEY_CAPS -This is a description of the capabilities of a sub key. It is -representable as a string. The string contains the letter ``e'' if -the key can be used for encryption, ``s'' if the key can be used for -signatures, and ``c'' if the key can be used for certifications. +@end deftypefun -@item GPGME_ATTR_CAN_ENCRYPT -This specifies if a sub key can be used for encryption. It is -representable as a number, and is @code{1} if the sub key can be used -for encryption, and @code{0} otherwise. -@item GPGME_ATTR_CAN_SIGN -This specifies if a sub key can be used to create data signatures. It -is representable as a number, and is @code{1} if the sub key can be -used for signatures, and @code{0} otherwise. +@deftypefun gpgme_error_t gpgme_op_createkey_start @ + (@w{gpgme_ctx_t @var{ctx}}, @ + @w{const char *@var{userid}}, @ + @w{const char *@var{algo}}, @ + @w{unsigned long @var{reserved}}, @ + @w{unsigned long @var{expires}}, @ + @w{gpgme_key_t @var{extrakey}}, @ + @w{unsigned int @var{flags}}); -@item GPGME_ATTR_CAN_CERTIFY -This specifies if a sub key can be used to create key certificates. -It is representable as a number, and is @code{1} if the sub key can be -used for certifications, and @code{0} otherwise. +The function @code{gpgme_op_createkey_start} initiates a +@code{gpgme_op_createkey} operation; see there for details. It must +be completed by calling @code{gpgme_wait} on the context. +@xref{Waiting For Completion}. -@item GPGME_ATTR_SERIAL -The X.509 issuer serial attribute of the key. It is representable as -a string. +@end deftypefun -@item GPGME_ATTR_ISSUE -The X.509 issuer name attribute of the key. It is representable as a -string. +@c +@c gpgme_op_createsubkey +@c +@deftypefun gpgme_error_t gpgme_op_createsubkey @ + (@w{gpgme_ctx_t @var{ctx}}, @ + @w{gpgme_key_t @var{key}}, @ + @w{const char *@var{algo}}, @ + @w{unsigned long @var{reserved}}, @ + @w{unsigned long @var{expires}}, @ + @w{unsigned int @var{flags}}); -@item GPGME_ATTR_CHAINID -The X.509 chain ID can be used to build the certification chain. It -is representable as a string. -@end table -@end deftp +The function @code{gpgme_op_createsubkey} creates and adds a new +subkey to the primary OpenPGP key given by @var{KEY}. The only +allowed protocol in @var{ctx} is @code{GPGME_PROTOCOL_OPENPGP}. +Subkeys (aka secondary keys) are a concept in the OpenPGP protocol to +bind several keys to a primary key. As of now this function requires +at least version 2.1.13 of GnuPG. -@deftypefun {const char *} gpgme_key_get_string_attr (@w{gpgme_key_t @var{key}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) -The function @code{gpgme_key_get_string_attr} returns the value of the -string-representable attribute @var{what} of key @var{key}. If the -attribute is an attribute of a sub key or an user ID, @var{idx} -specifies the sub key or user ID of which the attribute value is -returned. The argument @var{reserved} is reserved for later use and -should be @code{NULL}. +@var{key} specifies the key to operate on. -The string returned is only valid as long as the key is valid. +@var{algo} specifies the algorithm for the new subkey. For a list of +supported algorithms, see the GnuPG manual. If @var{algo} is +@code{NULL} or the string "default", the subkey is generated using the +default algorithm for an encryption subkey of the engine. If the +string "future-default" is used the engine may use an encryption +algorithm which is planned to be the default in a future release of +the engine; however existing implementation of the protocol may not be +able to already handle such future algorithms. -The function returns @code{0} if an attribute can't be returned as a -string, @var{key} is not a valid pointer, @var{idx} out of range, -or @var{reserved} not @code{NULL}. -@end deftypefun +@var{reserved} must be set to zero. -@deftypefun {unsigned long} gpgme_key_get_ulong_attr (@w{gpgme_key_t @var{key}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) -The function @code{gpgme_key_get_ulong_attr} returns the value of the -number-representable attribute @var{what} of key @var{key}. If the -attribute is an attribute of a sub key or an user ID, @var{idx} -specifies the sub key or user ID of which the attribute value is -returned. The argument @var{reserved} is reserved for later use and -should be @code{NULL}. +@var{expires} can be set to the number of seconds since Epoch of the +desired expiration date in UTC for the new subkey. Using 0 does not +set an expiration date. Note that this parameter takes an unsigned long +value and not a @code{time_t} to avoid problems on systems which use a +signed 32 bit @code{time_t}. Note further that the OpenPGP protocol +uses 32 bit values for timestamps and thus can only encode dates up to +the year 2106. -The function returns @code{0} if the attribute can't be returned as a -number, @var{key} is not a valid pointer, @var{idx} out of range, or -@var{reserved} not @code{NULL}. -@end deftypefun +@var{flags} takes the same values as described above for +@code{gpgme_op_createkey}. +After the operation completed successfully, information about the +created key can be retrieved with @code{gpgme_op_genkey_result}. -@node Key Signatures -@subsection Key Signatures -@cindex key, signatures -@cindex signatures, on a key +The function returns zero on success, @code{GPG_ERR_NOT_SUPPORTED} if +the engine does not support the command, or a bunch of other error +codes. -The following interfaces are deprecated and only provided for backward -compatibility. Don't use them. They will be removed in a future -version of @acronym{GPGME}. -The signatures on a key are only available if the key was retrieved -via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode -enabled, because it is expensive to retrieve all signatures of a key. +@end deftypefun -So, before using the below interfaces to retrieve the signatures on a -key, you have to make sure that the key was listed with signatures -enabled. One convenient, but blocking, way to do this is to use the -function @code{gpgme_get_key}. +@deftypefun gpgme_error_t gpgme_op_createsubkey_start @ + (@w{gpgme_ctx_t @var{ctx}}, @ + @w{gpgme_key_t @var{key}}, @ + @w{const char *@var{algo}}, @ + @w{unsigned long @var{reserved}}, @ + @w{unsigned long @var{expires}}, @ + @w{unsigned int @var{flags}}); -@deftp {Data type} gpgme_attr_t -The @code{gpgme_attr_t} type is used to specify a key signature -attribute. The following attributes are defined: +The function @code{gpgme_op_createsubkey_start} initiates a +@code{gpgme_op_createsubkey} operation; see there for details. It must +be completed by calling @code{gpgme_wait} on the context. +@xref{Waiting For Completion}. -@table @code -@item GPGME_ATTR_KEYID -This is the key ID of the key which was used for the signature. It is -representable as a string. +@end deftypefun -@item GPGME_ATTR_ALGO -This is the crypto algorithm used to create the signature. It is -representable as a string and as a number. The numbers correspond to -the @code{enum gcry_pk_algos} values in the gcrypt library. -@item GPGME_ATTR_CREATED -This is the timestamp at creation time of the signature. It is -representable as a number. +@c +@c gpgme_op_adduid +@c +@deftypefun gpgme_error_t gpgme_op_adduid @ + (@w{gpgme_ctx_t @var{ctx}}, @ + @w{gpgme_key_t @var{key}}, @ + @w{const char *@var{userid}}, @ + @w{unsigned int @var{flags}}); -@item GPGME_ATTR_EXPIRE -This is the expiration time of the signature. It is representable as -a number. +The function @code{gpgme_op_adduid} adds a new user ID to the OpenPGP +key given by @var{KEY}. Adding additional user IDs after key creation +is a feature of the OpenPGP protocol and thus the protocol for the +context @var{ctx} must be set to OpenPGP. As of now this function +requires at least version 2.1.13 of GnuPG. -@item GPGME_ATTR_USERID -This is the user ID associated with the signing key. The user ID is -representable as a number. +@var{key} specifies the key to operate on. -@item GPGME_ATTR_NAME -This is the name belonging to a user ID. It is representable as a string. +@var{userid} is the user ID to add to the key. A user ID is commonly +the mail address to be associated with the key. GPGME does not +require a specificy syntax but if more than a mail address is given, +RFC-822 style format is suggested. The value is expected to be in +UTF-8 encoding (i.e. no IDN encoding for mail addresses). This is a +required parameter. -@item GPGME_ATTR_EMAIL -This is the email address belonging to a user ID. It is representable -as a string. +@var{flags} are currently not used and must be set to zero. -@item GPGME_ATTR_COMMENT -This is the comment belonging to a user ID. It is representable as a -string. +The function returns zero on success, @code{GPG_ERR_NOT_SUPPORTED} if +the engine does not support the command, or a bunch of other error +codes. -@item GPGME_ATTR_KEY_REVOKED -This specifies if a key signature is a revocation signature. It is -representable as a number, and is @code{1} if the key is revoked, and -@code{0} otherwise. +@end deftypefun -@c @item GPGME_ATTR_KEY_EXPIRED -@c This specifies if a key signature is expired. It is representable as -@c a number, and is @code{1} if the key is revoked, and @code{0} -@c otherwise. -@c -@item GPGME_ATTR_SIG_CLASS -This specifies the signature class of a key signature. It is -representable as a number. The meaning is specific to the crypto -engine. +@deftypefun gpgme_error_t gpgme_op_adduid_start @ + (@w{gpgme_ctx_t @var{ctx}}, @ + @w{gpgme_key_t @var{key}}, @ + @w{const char *@var{userid}}, @ + @w{unsigned int @var{flags}}); -@item GPGME_ATTR_SIG_CLASS -This specifies the signature class of a key signature. It is -representable as a number. The meaning is specific to the crypto -engine. +The function @code{gpgme_op_adduid_start} initiates a +@code{gpgme_op_adduid} operation; see there for details. It must +be completed by calling @code{gpgme_wait} on the context. +@xref{Waiting For Completion}. -@item GPGME_ATTR_SIG_STATUS -This is the same value as returned by @code{gpgme_get_sig_status}. -@end table -@end deftp +@end deftypefun -@deftypefun {const char *} gpgme_key_sig_get_string_attr (@w{gpgme_key_t @var{key}}, @w{int @var{uid_idx}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) -The function @code{gpgme_key_sig_get_string_attr} returns the value of -the string-representable attribute @var{what} of the signature -@var{idx} on the user ID @var{uid_idx} in the key @var{key}. The -argument @var{reserved} is reserved for later use and should be -@code{NULL}. -The string returned is only valid as long as the key is valid. +@c +@c gpgme_op_revuid +@c +@deftypefun gpgme_error_t gpgme_op_revuid @ + (@w{gpgme_ctx_t @var{ctx}}, @ + @w{gpgme_key_t @var{key}}, @ + @w{const char *@var{userid}}, @ + @w{unsigned int @var{flags}}); -The function returns @code{0} if an attribute can't be returned as a -string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx} -out of range, or @var{reserved} not @code{NULL}. -@end deftypefun +The function @code{gpgme_op_revuid} revokes a user ID from the OpenPGP +key given by @var{KEY}. Revoking user IDs after key creation is a +feature of the OpenPGP protocol and thus the protocol for the context +@var{ctx} must be set to OpenPGP. As of now this function requires at +least version 2.1.13 of GnuPG. -@deftypefun {unsigned long} gpgme_key_sig_get_ulong_attr (@w{gpgme_key_t @var{key}}, @w{int @var{uid_idx}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) -The function @code{gpgme_key_sig_get_ulong_attr} returns the value of -the number-representable attribute @var{what} of the signature -@var{idx} on the user ID @var{uid_idx} in the key @var{key}. The -argument @var{reserved} is reserved for later use and should be -@code{NULL}. +@var{key} specifies the key to operate on. -The function returns @code{0} if an attribute can't be returned as a -string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx} -out of range, or @var{reserved} not @code{NULL}. -@end deftypefun +@var{userid} is the user ID to be revoked from the key. The user ID +must be given verbatim because the engine does an exact and case +sensitive match. Thus the @code{uid} field from the user ID object +(@code{gpgme_user_id_t}) is to be used. This is a required parameter. +@var{flags} are currently not used and must be set to zero. -@node Manipulating Keys -@subsection Manipulating Keys -@cindex key, manipulation +Note that the engine won't allow to revoke the last valid user ID. To +change a user ID is better to first add the new user ID, then revoke +the old one, and finally publish the key. -@deftypefun void gpgme_key_ref (@w{gpgme_key_t @var{key}}) -The function @code{gpgme_key_ref} acquires an additional reference for -the key @var{key}. -@end deftypefun +The function returns zero on success, @code{GPG_ERR_NOT_SUPPORTED} if +the engine does not support the command, or a bunch of other error +codes. -@deftypefun void gpgme_key_unref (@w{gpgme_key_t @var{key}}) -The function @code{gpgme_key_unref} releases a reference for the key -@var{key}. If this was the last reference, the key will be destroyed -and all resources associated to it will be released. @end deftypefun +@deftypefun gpgme_error_t gpgme_op_revuid_start @ + (@w{gpgme_ctx_t @var{ctx}}, @ + @w{gpgme_key_t @var{key}}, @ + @w{const char *@var{userid}}, @ + @w{unsigned int @var{flags}}); -The following interface is deprecated and only provided for backward -compatibility. Don't use it. It will be removed in a future version -of @acronym{GPGME}. +The function @code{gpgme_op_revuid_start} initiates a +@code{gpgme_op_revuid} operation; see there for details. It must +be completed by calling @code{gpgme_wait} on the context. +@xref{Waiting For Completion}. -@deftypefun void gpgme_key_release (@w{gpgme_key_t @var{key}}) -The function @code{gpgme_key_release} is equivalent to -@code{gpgme_key_unref}. @end deftypefun -@node Generating Keys -@subsection Generating Keys -@cindex key, creation -@cindex key ring, add - -GPGME provides a set of functions to create public key pairs. Most of -these functions require the use of GnuPG 2.1 and later; for older -GnuPG versions the @code{gpgme_op_genkey} function can be used. -Existing code which wants to update to the new functions or new code -which shall supports older GnuPG versions may try the new functions -first and provide a fallback to the old function if the error code -@code{GPG_ERR_NOT_SUPPORTED} is received. - @c -@c gpgme_op_createkey +@c gpgme_op_genkey @c -@deftypefun gpgme_error_t gpgme_op_createkey @ +@deftypefun gpgme_error_t gpgme_op_genkey @ (@w{gpgme_ctx_t @var{ctx}}, @ - @w{const char *@var{userid}}, @ - @w{const char *@var{algo}}, @ - @w{unsigned long @var{reserved}}, @ - @w{unsigned long @var{expires}}, @ - @w{gpgme_key_t @var{extrakey}}, @ - @w{unsigned int @var{flags}}); - -The function @code{gpgme_op_createkey} generates a new key for the -procotol active in the context @var{ctx}. As of now this function -does only work for OpenPGP and requires at least version 2.1.13 of -GnuPG. - -@var{userid} is commonly the mail address associated with the key. -GPGME does not require a specificy syntax but if more than a mail -address is given, RFC-822 style format is suggested. The value is -expected to be in UTF-8 encoding (i.e. no IDN encoding for mail -addresses). This is a required parameter. - -@var{algo} specifies the algorithm for the new key (actually a keypair -of public and private key). For a list of supported algorithms, see -the GnuPG manual. If @var{algo} is @code{NULL} or the string -"default", the key is generated using the default algorithm of the -engine. If the string "future-default" is used the engine may use an -algorithm which is planned to be the default in a future release of -the engine; however existing implementation of the protocol may not be -able to already handle such future algorithms. For the OpenPGP -protocol, the specification of a default algorithm, without requesting -a non-default usage via @var{flags}, triggers the creation of a -primary key plus a secondary key (subkey). - -@var{reserved} must be set to zero. - -@var{expires} can be set to the number of seconds since Epoch of the -desired expiration date in UTC for the new key. Using 0 does not -set an expiration date. Note that this parameter takes an unsigned long -value and not a @code{time_t} to avoid problems on systems which use a -signed 32 bit @code{time_t}. Note further that the OpenPGP protocol -uses 32 bit values for timestamps and thus can only encode dates up to -the year 2106. - -@var{extrakey} is currently not used and must be set to @code{NULL}. -A future version of GPGME may use this parameter to create X.509 keys. - -@var{flags} can be set to the bit-wise OR of the following flags: - -@table @code -@item GPGME_CREATE_SIGN -@itemx GPGME_CREATE_ENCR -@itemx GPGME_CREATE_CERT -@itemx GPGME_CREATE_AUTH -Do not create the key with the default capabilities (key usage) of the -requested algorithm but use those explicitly given by these flags: -``signing'', ``encryption'', ``certification'', or ``authentication''. -The allowed combinations depend on the algorithm. + @w{const char *@var{parms}}, @ + @w{gpgme_data_t @var{public}}, @ + @w{gpgme_data_t @var{secret}}) -If any of these flags are set and a default algorithm has been -selected only one key is created in the case of the OpenPGP -protocol. +The function @code{gpgme_op_genkey} generates a new key pair in the +context @var{ctx}. The meaning of @var{public} and @var{secret} +depends on the crypto backend. -@item GPGME_CREATE_NOPASSWD -Request generation of the key without password protection. +GPG does not support @var{public} and @var{secret}, they should be +@code{NULL}. GnuPG will generate a key pair and add it to the +standard key ring. The fingerprint of the generated key is available +with @code{gpgme_op_genkey_result}. -@item GPGME_CREATE_SELFSIGNED -For an X.509 key do not create a CSR but a self-signed certificate. -This has not yet been implemented. +GpgSM requires @var{public} to be a writable data object. GpgSM will +generate a secret key (which will be stored by @command{gpg-agent}, +and return a certificate request in @var{public}, which then needs to +be signed by the certification authority and imported before it can be +used. GpgSM does not make the fingerprint available. -@item GPGME_CREATE_NOSTORE -Do not store the created key in the local key database. -This has not yet been implemented. +The argument @var{parms} specifies parameters for the key in an XML +string. The details about the format of @var{parms} are specific to +the crypto engine used by @var{ctx}. Here is an example for GnuPG as +the crypto engine (all parameters of OpenPGP key generation are +documented in the GPG manual): -@item GPGME_CREATE_WANTPUB -@itemx GPGME_CREATE_WANTSEC -Return the public or secret key as part of the result structure. -This has not yet been implemented. +@example + +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 + +@end example -@item GPGME_CREATE_FORCE -The engine does not allow the creation of a key with a user ID -already existing in the local key database. This flag can be used to -override this check. +Here is an example for GpgSM as the crypto engine (all parameters of +OpenPGP key generation are documented in the GPGSM manual): -@end table +@example + +Key-Type: RSA +Key-Length: 1024 +Name-DN: C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester +Name-Email: joe@@foo.bar + +@end example -After the operation completed successfully, information about the -created key can be retrieved with @code{gpgme_op_genkey_result}. +Strings should be given in UTF-8 encoding. The only format supported +for now is ``internal''. The content of the @code{GnupgKeyParms} +container is passed verbatim to the crypto backend. Control +statements are not allowed. -The function returns zero on success, @code{GPG_ERR_NOT_SUPPORTED} if -the engine does not support the command, or a bunch of other error -codes. +After the operation completed successfully, the result can be +retrieved with @code{gpgme_op_genkey_result}. +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +operation could be started successfully, @code{GPG_ERR_INV_VALUE} if +@var{parms} is not a valid XML string, @code{GPG_ERR_NOT_SUPPORTED} if +@var{public} or @var{secret} is not valid, and @code{GPG_ERR_GENERAL} +if no key was created by the backend. @end deftypefun +@deftypefun gpgme_error_t gpgme_op_genkey_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{parms}}, @w{gpgme_data_t @var{public}}, @w{gpgme_data_t @var{secret}}) -@deftypefun gpgme_error_t gpgme_op_createkey_start @ - (@w{gpgme_ctx_t @var{ctx}}, @ - @w{const char *@var{userid}}, @ - @w{const char *@var{algo}}, @ - @w{unsigned long @var{reserved}}, @ - @w{unsigned long @var{expires}}, @ - @w{gpgme_key_t @var{extrakey}}, @ - @w{unsigned int @var{flags}}); - -The function @code{gpgme_op_createkey_start} initiates a -@code{gpgme_op_createkey} operation; see there for details. It must -be completed by calling @code{gpgme_wait} on the context. -@xref{Waiting For Completion}. +The function @code{gpgme_op_genkey_start} initiates a +@code{gpgme_op_genkey} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +operation could be started successfully, @code{GPG_ERR_INV_VALUE} if +@var{parms} is not a valid XML string, and +@code{GPG_ERR_NOT_SUPPORTED} if @var{public} or @var{secret} is not +@code{NULL}. @end deftypefun + @c -@c gpgme_op_createsubkey +@c gpgme_op_genkey_result @c -@deftypefun gpgme_error_t gpgme_op_createsubkey @ - (@w{gpgme_ctx_t @var{ctx}}, @ - @w{gpgme_key_t @var{key}}, @ - @w{const char *@var{algo}}, @ - @w{unsigned long @var{reserved}}, @ - @w{unsigned long @var{expires}}, @ - @w{unsigned int @var{flags}}); +@deftp {Data type} {gpgme_genkey_result_t} -The function @code{gpgme_op_createsubkey} creates and adds a new -subkey to the primary OpenPGP key given by @var{KEY}. The only -allowed protocol in @var{ctx} is @code{GPGME_PROTOCOL_OPENPGP}. -Subkeys (aka secondary keys) are a concept in the OpenPGP protocol to -bind several keys to a primary key. As of now this function requires -at least version 2.1.13 of GnuPG. +This is a pointer to a structure used to store the result of a +@code{gpgme_op_genkey} operation. After successfully generating a +key, you can retrieve the pointer to the result with +@code{gpgme_op_genkey_result}. The structure contains the following +members: -@var{key} specifies the key to operate on. +@table @code +@item unsigned int primary : 1 +This flag is set to 1 if a primary key was created and to 0 +if not. -@var{algo} specifies the algorithm for the new subkey. For a list of -supported algorithms, see the GnuPG manual. If @var{algo} is -@code{NULL} or the string "default", the subkey is generated using the -default algorithm for an encryption subkey of the engine. If the -string "future-default" is used the engine may use an encryption -algorithm which is planned to be the default in a future release of -the engine; however existing implementation of the protocol may not be -able to already handle such future algorithms. +@item unsigned int sub : 1 +This flag is set to 1 if a subkey was created and to 0 if not. -@var{reserved} must be set to zero. +@item unsigned int uid : 1 +This flag is set to 1 if a user ID was created and to 0 if not. -@var{expires} can be set to the number of seconds since Epoch of the -desired expiration date in UTC for the new subkey. Using 0 does not -set an expiration date. Note that this parameter takes an unsigned long -value and not a @code{time_t} to avoid problems on systems which use a -signed 32 bit @code{time_t}. Note further that the OpenPGP protocol -uses 32 bit values for timestamps and thus can only encode dates up to -the year 2106. +@item char *fpr +This is the fingerprint of the key that was created. If both a +primary and a subkey were generated, the fingerprint of the primary +key will be returned. If the crypto engine does not provide the +fingerprint, @code{fpr} will be a null pointer. -@var{flags} takes the same values as described above for -@code{gpgme_op_createkey}. +@item gpgme_data_t pubkey +This will eventually be used to return the public key. It is +currently not used. -After the operation completed successfully, information about the -created key can be retrieved with @code{gpgme_op_genkey_result}. +@item gpgme_data_t seckey +This will eventually be used to return the secret key. It is +currently not used. -The function returns zero on success, @code{GPG_ERR_NOT_SUPPORTED} if -the engine does not support the command, or a bunch of other error -codes. +@end table +@end deftp +@deftypefun gpgme_genkey_result_t gpgme_op_genkey_result (@w{gpgme_ctx_t @var{ctx}}) + +The function @code{gpgme_op_genkey_result} returns a +@code{gpgme_genkey_result_t} pointer to a structure holding the result of +a @code{gpgme_op_genkey} operation. The pointer is only valid if the +last operation on the context was a @code{gpgme_op_genkey} or +@code{gpgme_op_genkey_start} operation, and if this operation finished +successfully. The returned pointer is only valid until the next +operation is started on the context. @end deftypefun -@deftypefun gpgme_error_t gpgme_op_createsubkey_start @ - (@w{gpgme_ctx_t @var{ctx}}, @ - @w{gpgme_key_t @var{key}}, @ - @w{const char *@var{algo}}, @ - @w{unsigned long @var{reserved}}, @ - @w{unsigned long @var{expires}}, @ - @w{unsigned int @var{flags}}); -The function @code{gpgme_op_createsubkey_start} initiates a -@code{gpgme_op_createsubkey} operation; see there for details. It must -be completed by calling @code{gpgme_wait} on the context. -@xref{Waiting For Completion}. +@c +@c SIGNING KEYS +@c +@node Signing Keys +@subsection Signing Keys +@cindex key, signing -@end deftypefun +Key signatures are a unique concept of the OpenPGP protocol. They can +be used to certify the validity of a key and are used to create the +Web-of-Trust (WoT). Instead of using the @code{gpgme_op_interact} +function along with a finite state machine, GPGME provides a +convenient function to create key signatures when using modern GnuPG +versions. @c -@c gpgme_op_adduid +@c gpgme_op_keysign @c -@deftypefun gpgme_error_t gpgme_op_adduid @ +@deftypefun gpgme_error_t gpgme_op_keysign @ (@w{gpgme_ctx_t @var{ctx}}, @ @w{gpgme_key_t @var{key}}, @ @w{const char *@var{userid}}, @ - @w{unsigned int @var{flags}}); - -The function @code{gpgme_op_adduid} adds a new user ID to the OpenPGP -key given by @var{KEY}. Adding additional user IDs after key creation -is a feature of the OpenPGP protocol and thus the protocol for the -context @var{ctx} must be set to OpenPGP. As of now this function -requires at least version 2.1.13 of GnuPG. - -@var{key} specifies the key to operate on. - -@var{userid} is the user ID to add to the key. A user ID is commonly -the mail address to be associated with the key. GPGME does not -require a specificy syntax but if more than a mail address is given, -RFC-822 style format is suggested. The value is expected to be in -UTF-8 encoding (i.e. no IDN encoding for mail addresses). This is a -required parameter. - -@var{flags} are currently not used and must be set to zero. - -The function returns zero on success, @code{GPG_ERR_NOT_SUPPORTED} if -the engine does not support the command, or a bunch of other error -codes. - -@end deftypefun - -@deftypefun gpgme_error_t gpgme_op_adduid_start @ - (@w{gpgme_ctx_t @var{ctx}}, @ - @w{gpgme_key_t @var{key}}, @ - @w{const char *@var{userid}}, @ - @w{unsigned int @var{flags}}); - -The function @code{gpgme_op_adduid_start} initiates a -@code{gpgme_op_adduid} operation; see there for details. It must -be completed by calling @code{gpgme_wait} on the context. -@xref{Waiting For Completion}. - -@end deftypefun - - -@c -@c gpgme_op_revuid -@c -@deftypefun gpgme_error_t gpgme_op_revuid @ - (@w{gpgme_ctx_t @var{ctx}}, @ - @w{gpgme_key_t @var{key}}, @ - @w{const char *@var{userid}}, @ - @w{unsigned int @var{flags}}); - -The function @code{gpgme_op_revuid} revokes a user ID from the OpenPGP -key given by @var{KEY}. Revoking user IDs after key creation is a -feature of the OpenPGP protocol and thus the protocol for the context -@var{ctx} must be set to OpenPGP. As of now this function requires at -least version 2.1.13 of GnuPG. - -@var{key} specifies the key to operate on. - -@var{userid} is the user ID to be revoked from the key. The user ID -must be given verbatim because the engine does an exact and case -sensitive match. Thus the @code{uid} field from the user ID object -(@code{gpgme_user_id_t}) is to be used. This is a required parameter. - -@var{flags} are currently not used and must be set to zero. - -Note that the engine won't allow to revoke the last valid user ID. To -change a user ID is better to first add the new user ID, then revoke -the old one, and finally publish the key. - -The function returns zero on success, @code{GPG_ERR_NOT_SUPPORTED} if -the engine does not support the command, or a bunch of other error -codes. - -@end deftypefun - -@deftypefun gpgme_error_t gpgme_op_revuid_start @ - (@w{gpgme_ctx_t @var{ctx}}, @ - @w{gpgme_key_t @var{key}}, @ - @w{const char *@var{userid}}, @ - @w{unsigned int @var{flags}}); - -The function @code{gpgme_op_revuid_start} initiates a -@code{gpgme_op_revuid} operation; see there for details. It must -be completed by calling @code{gpgme_wait} on the context. -@xref{Waiting For Completion}. - -@end deftypefun - - -@c -@c gpgme_op_genkey -@c -@deftypefun gpgme_error_t gpgme_op_genkey @ - (@w{gpgme_ctx_t @var{ctx}}, @ - @w{const char *@var{parms}}, @ - @w{gpgme_data_t @var{public}}, @ - @w{gpgme_data_t @var{secret}}) - -The function @code{gpgme_op_genkey} generates a new key pair in the -context @var{ctx}. The meaning of @var{public} and @var{secret} -depends on the crypto backend. - -GPG does not support @var{public} and @var{secret}, they should be -@code{NULL}. GnuPG will generate a key pair and add it to the -standard key ring. The fingerprint of the generated key is available -with @code{gpgme_op_genkey_result}. - -GpgSM requires @var{public} to be a writable data object. GpgSM will -generate a secret key (which will be stored by @command{gpg-agent}, -and return a certificate request in @var{public}, which then needs to -be signed by the certification authority and imported before it can be -used. GpgSM does not make the fingerprint available. - -The argument @var{parms} specifies parameters for the key in an XML -string. The details about the format of @var{parms} are specific to -the crypto engine used by @var{ctx}. Here is an example for GnuPG as -the crypto engine (all parameters of OpenPGP key generation are -documented in the GPG manual): - -@example - -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 - -@end example - -Here is an example for GpgSM as the crypto engine (all parameters of -OpenPGP key generation are documented in the GPGSM manual): - -@example - -Key-Type: RSA -Key-Length: 1024 -Name-DN: C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester -Name-Email: joe@@foo.bar - -@end example - -Strings should be given in UTF-8 encoding. The only format supported -for now is ``internal''. The content of the @code{GnupgKeyParms} -container is passed verbatim to the crypto backend. Control -statements are not allowed. - -After the operation completed successfully, the result can be -retrieved with @code{gpgme_op_genkey_result}. - -The function returns the error code @code{GPG_ERR_NO_ERROR} if the -operation could be started successfully, @code{GPG_ERR_INV_VALUE} if -@var{parms} is not a valid XML string, @code{GPG_ERR_NOT_SUPPORTED} if -@var{public} or @var{secret} is not valid, and @code{GPG_ERR_GENERAL} -if no key was created by the backend. -@end deftypefun - -@deftypefun gpgme_error_t gpgme_op_genkey_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{parms}}, @w{gpgme_data_t @var{public}}, @w{gpgme_data_t @var{secret}}) - -The function @code{gpgme_op_genkey_start} initiates a -@code{gpgme_op_genkey} operation. It can be completed by calling -@code{gpgme_wait} on the context. @xref{Waiting For Completion}. - -The function returns the error code @code{GPG_ERR_NO_ERROR} if the -operation could be started successfully, @code{GPG_ERR_INV_VALUE} if -@var{parms} is not a valid XML string, and -@code{GPG_ERR_NOT_SUPPORTED} if @var{public} or @var{secret} is not -@code{NULL}. -@end deftypefun - - -@c -@c gpgme_op_genkey_result -@c -@deftp {Data type} {gpgme_genkey_result_t} - -This is a pointer to a structure used to store the result of a -@code{gpgme_op_genkey} operation. After successfully generating a -key, you can retrieve the pointer to the result with -@code{gpgme_op_genkey_result}. The structure contains the following -members: - -@table @code -@item unsigned int primary : 1 -This flag is set to 1 if a primary key was created and to 0 -if not. - -@item unsigned int sub : 1 -This flag is set to 1 if a subkey was created and to 0 if not. - -@item unsigned int uid : 1 -This flag is set to 1 if a user ID was created and to 0 if not. - -@item char *fpr -This is the fingerprint of the key that was created. If both a -primary and a subkey were generated, the fingerprint of the primary -key will be returned. If the crypto engine does not provide the -fingerprint, @code{fpr} will be a null pointer. - -@item gpgme_data_t pubkey -This will eventually be used to return the public key. It is -currently not used. - -@item gpgme_data_t seckey -This will eventually be used to return the secret key. It is -currently not used. - -@end table -@end deftp - -@deftypefun gpgme_genkey_result_t gpgme_op_genkey_result (@w{gpgme_ctx_t @var{ctx}}) - -The function @code{gpgme_op_genkey_result} returns a -@code{gpgme_genkey_result_t} pointer to a structure holding the result of -a @code{gpgme_op_genkey} operation. The pointer is only valid if the -last operation on the context was a @code{gpgme_op_genkey} or -@code{gpgme_op_genkey_start} operation, and if this operation finished -successfully. The returned pointer is only valid until the next -operation is started on the context. - -@end deftypefun - - -@c -@c SIGNING KEYS -@c -@node Signing Keys -@subsection Signing Keys -@cindex key, signing - -Key signatures are a unique concept of the OpenPGP protocol. They can -be used to certify the validity of a key and are used to create the -Web-of-Trust (WoT). Instead of using the @code{gpgme_op_interact} -function along with a finite state machine, GPGME provides a -convenient function to create key signatures when using modern GnuPG -versions. - - -@c -@c gpgme_op_keysign -@c -@deftypefun gpgme_error_t gpgme_op_keysign @ - (@w{gpgme_ctx_t @var{ctx}}, @ - @w{gpgme_key_t @var{key}}, @ - @w{const char *@var{userid}}, @ - @w{unsigned long @var{expires}}, @ + @w{unsigned long @var{expires}}, @ @w{unsigned int @var{flags}}); The function @code{gpgme_op_keysign} adds a new key signature to the @@ -4644,24 +4320,6 @@ successfully. The returned pointer is only valid until the next operation is started on the context. @end deftypefun -The following interface is deprecated and only provided for backward -compatibility. Don't use it. It will be removed in a future version -of @acronym{GPGME}. - -@deftypefun gpgme_error_t gpgme_op_import_ext (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}}, @w{int *@var{nr}}) -The function @code{gpgme_op_import_ext} is equivalent to: - -@example - gpgme_error_t err = gpgme_op_import (ctx, keydata); - if (!err) - @{ - gpgme_import_result_t result = gpgme_op_import_result (ctx); - *nr = result->considered; - @} -@end example -@end deftypefun - - @node Deleting Keys @subsection Deleting Keys @cindex key, delete @@ -4866,80 +4524,6 @@ is not a valid pointer. @end deftypefun -@deftp {Data type} {gpgme_error_t (*gpgme_edit_cb_t) @ - (@w{void *@var{handle}}, @ - @w{gpgme_status_code_t @var{status}}, @ - @w{const char *@var{args}}, @ - @w{int @var{fd}})} -@tindex gpgme_edit_cb_t -The @code{gpgme_edit_cb_t} type is the type of functions which -@acronym{GPGME} calls if it a key edit operation is on-going. The -status code @var{status} and the argument line @var{args} are passed -through by @acronym{GPGME} from the crypto engine. The file -descriptor @var{fd} is -1 for normal status messages. If @var{status} -indicates a command rather than a status message, the response to the -command should be written to @var{fd}. The @var{handle} is provided -by the user at start of operation. - -The function should return @code{GPG_ERR_FALSE} if it did not handle -the status code, @code{0} for success, or any other error value. -@end deftp - -@deftypefun gpgme_error_t gpgme_op_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}}) -Note: This function is deprecated, please use -@code{gpgme_op_interact} instead. - -The function @code{gpgme_op_edit} processes the key @var{KEY} -interactively, using the edit callback function @var{FNC} with the -handle @var{HANDLE}. The callback is invoked for every status and -command request from the crypto engine. The output of the crypto -engine is written to the data object @var{out}. - -Note that the protocol between the callback function and the crypto -engine is specific to the crypto engine and no further support in -implementing this protocol correctly is provided by @acronym{GPGME}. - -The function returns the error code @code{GPG_ERR_NO_ERROR} if the -edit operation completes successfully, @code{GPG_ERR_INV_VALUE} if -@var{ctx} or @var{key} is not a valid pointer, and any error returned -by the crypto engine or the edit callback handler. -@end deftypefun - -@deftypefun gpgme_error_t gpgme_op_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}}) -Note: This function is deprecated, please use -@code{gpgme_op_interact_start} instead. - -The function @code{gpgme_op_edit_start} initiates a -@code{gpgme_op_edit} operation. It can be completed by calling -@code{gpgme_wait} on the context. @xref{Waiting For Completion}. - -The function returns the error code @code{GPG_ERR_NO_ERROR} if the -operation was started successfully, and @code{GPG_ERR_INV_VALUE} if -@var{ctx} or @var{key} is not a valid pointer. -@end deftypefun - - -@deftypefun gpgme_error_t gpgme_op_card_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}}) -Note: This function is deprecated, please use @code{gpgme_op_interact} -with the flag @code{GPGME_INTERACT_CARD} instead. - -The function @code{gpgme_op_card_edit} is analogous to -@code{gpgme_op_edit}, but should be used to process the smart card corresponding to the key @var{key}. -@end deftypefun - -@deftypefun gpgme_error_t gpgme_op_card_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}}) -Note: This function is deprecated, please use @code{gpgme_op_interact_start} -with the flag @code{GPGME_INTERACT_CARD} instead. - -The function @code{gpgme_op_card_edit_start} initiates a -@code{gpgme_op_card_edit} operation. It can be completed by calling -@code{gpgme_wait} on the context. @xref{Waiting For Completion}. - -The function returns the error code @code{GPG_ERR_NO_ERROR} if the -operation was started successfully, and @code{GPG_ERR_INV_VALUE} if -@var{ctx} or @var{key} is not a valid pointer. -@end deftypefun - @node Trust Item Management @section Trust Item Management @@ -4975,7 +4559,6 @@ The user name if @code{type} is 2. @menu * Listing Trust Items:: Browsing the list of available trust items. -* Information About Trust Items:: Requesting information about trust items. * Manipulating Trust Items:: Operations on trust items. @end menu @@ -5032,47 +4615,6 @@ time during the operation there was not enough memory available. @end deftypefun -@node Information About Trust Items -@subsection Information About Trust Items -@cindex trust item, information about -@cindex trust item, attributes -@cindex attributes, of a trust item - -The following interfaces are deprecated and only provided for backward -compatibility. Don't use them. They will be removed in a future -version of @acronym{GPGME}. - -Trust items have attributes which can be queried using the interfaces -below. The attribute identifiers are shared with those for key -attributes. @xref{Information About Keys}. - -@deftypefun {const char *} gpgme_trust_item_get_string_attr (@w{gpgme_trust_item_t @var{item}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) -The function @code{gpgme_trust_item_get_string_attr} returns the value -of the string-representable attribute @var{what} of trust item -@var{item}. The arguments @var{idx} and @var{reserved} are reserved -for later use and should be @code{0} and @code{NULL} respectively. - -The string returned is only valid as long as the key is valid. - -The function returns @code{0} if an attribute can't be returned as a -string, @var{key} is not a valid pointer, @var{idx} out of range, -or @var{reserved} not @code{NULL}. -@end deftypefun - -@deftypefun int gpgme_trust_item_get_int_attr (@w{gpgme_trust_item_t @var{item}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) -The function @code{gpgme_trust_item_get_int_attr} returns the value of -the number-representable attribute @var{what} of trust item -@var{item}. If the attribute occurs more than once in the trust item, -the index is specified by @var{idx}. However, currently no such -attribute exists, so @var{idx} should be @code{0}. The argument -@var{reserved} is reserved for later use and should be @code{NULL}. - -The function returns @code{0} if the attribute can't be returned as a -number, @var{key} is not a valid pointer, @var{idx} out of range, -or @var{reserved} not @code{NULL}. -@end deftypefun - - @node Manipulating Trust Items @subsection Manipulating Trust Items @cindex trust item, manipulation @@ -5090,16 +4632,6 @@ released. @end deftypefun -The following interface is deprecated and only provided for backward -compatibility. Don't use it. It will be removed in a future version -of @acronym{GPGME}. - -@deftypefun void gpgme_trust_item_release (@w{gpgme_trust_item_t @var{item}}) -The function @code{gpgme_trust_item_release} is an alias for -@code{gpgme_trust_item_unref}. -@end deftypefun - - @node Crypto Operations @section Crypto Operations @cindex cryptographic operation @@ -5521,326 +5053,94 @@ the context. @end deftypefun -The following interfaces are deprecated and only provided for backward -compatibility. Don't use them. They will be removed in a future -version of @acronym{GPGME}. - -@deftp {Data type} {enum gpgme_sig_stat_t} -@tindex gpgme_sig_stat_t -The @code{gpgme_sig_stat_t} type holds the result of a signature check, or -the combined result of all signatures. The following results are -possible: +@node Decrypt and Verify +@subsection Decrypt and Verify +@cindex decryption and verification +@cindex verification and decryption +@cindex signature check +@cindex cryptographic operation, decryption and verification -@table @code -@item GPGME_SIG_STAT_NONE -This status should not occur in normal operation. +@deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}}) +The function @code{gpgme_op_decrypt_verify} decrypts the ciphertext in +the data object @var{cipher} and stores it into the data object +@var{plain}. If @var{cipher} contains signatures, they will be +verified. -@item GPGME_SIG_STAT_GOOD -This status indicates that the signature is valid. For the combined -result this status means that all signatures are valid. +After the operation completed, @code{gpgme_op_decrypt_result} and +@code{gpgme_op_verify_result} can be used to retrieve more information +about the signatures. -@item GPGME_SIG_STAT_GOOD_EXP -This status indicates that the signature is valid but expired. For -the combined result this status means that all signatures are valid -and expired. +If the error code @code{GPG_ERR_NO_DATA} is returned, @var{cipher} +does not contain any data to decrypt. However, it might still be +signed. The information about detected signatures is available with +@code{gpgme_op_verify_result} in this case. -@item GPGME_SIG_STAT_GOOD_EXPKEY -This status indicates that the signature is valid but the key used to -verify the signature has expired. For the combined result this status -means that all signatures are valid and all keys are expired. +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +ciphertext could be decrypted successfully, @code{GPG_ERR_INV_VALUE} +if @var{ctx}, @var{cipher} or @var{plain} is not a valid pointer, +@code{GPG_ERR_NO_DATA} if @var{cipher} does not contain any data to +decrypt, @code{GPG_ERR_DECRYPT_FAILED} if @var{cipher} is not a valid +cipher text, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the +secret key could not be retrieved, and passes through any errors that +are reported by the crypto engine support routines. +@end deftypefun -@item GPGME_SIG_STAT_BAD -This status indicates that the signature is invalid. For the combined -result this status means that all signatures are invalid. +@deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}}) +The function @code{gpgme_op_decrypt_verify_start} initiates a +@code{gpgme_op_decrypt_verify} operation. It can be completed by +calling @code{gpgme_wait} on the context. @xref{Waiting For +Completion}. -@item GPGME_SIG_STAT_NOKEY -This status indicates that the signature could not be verified due to -a missing key. For the combined result this status means that all -signatures could not be checked due to missing keys. +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +operation could be started successfully, @code{GPG_ERR_INV_VALUE} if +@var{ctx}, @var{cipher}, @var{plain} or @var{r_stat} is not a valid +pointer, and @code{GPG_ERR_NO_DATA} if @var{cipher} does not contain +any data to decrypt. +@end deftypefun -@item GPGME_SIG_STAT_NOSIG -This status indicates that the signature data provided was not a real -signature. -@item GPGME_SIG_STAT_ERROR -This status indicates that there was some other error which prevented -the signature verification. +@node Sign +@subsection Sign +@cindex signature, creation +@cindex sign +@cindex cryptographic operation, signing -@item GPGME_SIG_STAT_DIFF -For the combined result this status means that at least two signatures -have a different status. You can get each key's status with -@code{gpgme_get_sig_status}. -@end table -@end deftp +A signature can contain signatures by one or more keys. The set of +keys used to create a signatures is contained in a context, and is +applied to all following signing operations in this context (until the +set is changed). -@deftypefun {const char *} gpgme_get_sig_status (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_sig_stat_t *@var{r_stat}}, @w{time_t *@var{r_created}}) -The function @code{gpgme_get_sig_status} is equivalent to: +@menu +* Selecting Signers:: How to choose the keys to sign with. +* Creating a Signature:: How to create a signature. +* Signature Notation Data:: How to add notation data to a signature. +@end menu -@example - gpgme_verify_result_t result; - gpgme_signature_t sig; - result = gpgme_op_verify_result (ctx); - sig = result->signatures; +@node Selecting Signers +@subsubsection Selecting Signers +@cindex signature, selecting signers +@cindex signers, selecting - while (sig && idx) - @{ - sig = sig->next; - idx--; - @} - if (!sig || idx) - return NULL; +The key or the keys used to create a signature are stored in the +context. The following functions can be used to manipulate this list. +If no signer has been set into the context a default key is used for +signing. - if (r_stat) - @{ - switch (gpg_err_code (sig->status)) - @{ - case GPG_ERR_NO_ERROR: - *r_stat = GPGME_SIG_STAT_GOOD; - break; +@deftypefun void gpgme_signers_clear (@w{gpgme_ctx_t @var{ctx}}) +The function @code{gpgme_signers_clear} releases a reference for each +key on the signers list and removes the list of signers from the +context @var{ctx}. - case GPG_ERR_BAD_SIGNATURE: - *r_stat = GPGME_SIG_STAT_BAD; - break; +Every context starts with an empty list. +@end deftypefun - case GPG_ERR_NO_PUBKEY: - *r_stat = GPGME_SIG_STAT_NOKEY; - break; +@deftypefun gpgme_error_t gpgme_signers_add (@w{gpgme_ctx_t @var{ctx}}, @w{const gpgme_key_t @var{key}}) +The function @code{gpgme_signers_add} adds the key @var{key} to the +list of signers in the context @var{ctx}. - case GPG_ERR_NO_DATA: - *r_stat = GPGME_SIG_STAT_NOSIG; - break; - - case GPG_ERR_SIG_EXPIRED: - *r_stat = GPGME_SIG_STAT_GOOD_EXP; - break; - - case GPG_ERR_KEY_EXPIRED: - *r_stat = GPGME_SIG_STAT_GOOD_EXPKEY; - break; - - default: - *r_stat = GPGME_SIG_STAT_ERROR; - break; - @} - @} - if (r_created) - *r_created = sig->timestamp; - return sig->fpr; -@end example -@end deftypefun - -@deftypefun {const char *} gpgme_get_sig_string_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{what}}, @w{int @var{whatidx}}) -The function @code{gpgme_get_sig_string_attr} is equivalent to: - -@example - gpgme_verify_result_t result; - gpgme_signature_t sig; - - result = gpgme_op_verify_result (ctx); - sig = result->signatures; - - while (sig && idx) - @{ - sig = sig->next; - idx--; - @} - if (!sig || idx) - return NULL; - - switch (what) - @{ - case GPGME_ATTR_FPR: - return sig->fpr; - - case GPGME_ATTR_ERRTOK: - if (whatidx == 1) - return sig->wrong_key_usage ? "Wrong_Key_Usage" : ""; - else - return ""; - default: - break; - @} - - return NULL; -@end example -@end deftypefun - -@deftypefun {const char *} gpgme_get_sig_ulong_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{waht}}, @w{int @var{whatidx}}) -The function @code{gpgme_get_sig_ulong_attr} is equivalent to: - -@example - gpgme_verify_result_t result; - gpgme_signature_t sig; - - result = gpgme_op_verify_result (ctx); - sig = result->signatures; - - while (sig && idx) - @{ - sig = sig->next; - idx--; - @} - if (!sig || idx) - return 0; - - switch (what) - @{ - case GPGME_ATTR_CREATED: - return sig->timestamp; - - case GPGME_ATTR_EXPIRE: - return sig->exp_timestamp; - - case GPGME_ATTR_VALIDITY: - return (unsigned long) sig->validity; - - case GPGME_ATTR_SIG_STATUS: - switch (sig->status) - @{ - case GPG_ERR_NO_ERROR: - return GPGME_SIG_STAT_GOOD; - - case GPG_ERR_BAD_SIGNATURE: - return GPGME_SIG_STAT_BAD; - - case GPG_ERR_NO_PUBKEY: - return GPGME_SIG_STAT_NOKEY; - - case GPG_ERR_NO_DATA: - return GPGME_SIG_STAT_NOSIG; - - case GPG_ERR_SIG_EXPIRED: - return GPGME_SIG_STAT_GOOD_EXP; - - case GPG_ERR_KEY_EXPIRED: - return GPGME_SIG_STAT_GOOD_EXPKEY; - - default: - return GPGME_SIG_STAT_ERROR; - @} - - case GPGME_ATTR_SIG_SUMMARY: - return sig->summary; - - default: - break; - @} - return 0; -@end example -@end deftypefun - -@deftypefun {const char *} gpgme_get_sig_key (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_key_t *@var{r_key}}) -The function @code{gpgme_get_sig_key} is equivalent to: - -@example - gpgme_verify_result_t result; - gpgme_signature_t sig; - - result = gpgme_op_verify_result (ctx); - sig = result->signatures; - - while (sig && idx) - @{ - sig = sig->next; - idx--; - @} - if (!sig || idx) - return gpg_error (GPG_ERR_EOF); - - return gpgme_get_key (ctx, sig->fpr, r_key, 0); -@end example -@end deftypefun - - -@node Decrypt and Verify -@subsection Decrypt and Verify -@cindex decryption and verification -@cindex verification and decryption -@cindex signature check -@cindex cryptographic operation, decryption and verification - -@deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}}) -The function @code{gpgme_op_decrypt_verify} decrypts the ciphertext in -the data object @var{cipher} and stores it into the data object -@var{plain}. If @var{cipher} contains signatures, they will be -verified. - -After the operation completed, @code{gpgme_op_decrypt_result} and -@code{gpgme_op_verify_result} can be used to retrieve more information -about the signatures. - -If the error code @code{GPG_ERR_NO_DATA} is returned, @var{cipher} -does not contain any data to decrypt. However, it might still be -signed. The information about detected signatures is available with -@code{gpgme_op_verify_result} in this case. - -The function returns the error code @code{GPG_ERR_NO_ERROR} if the -ciphertext could be decrypted successfully, @code{GPG_ERR_INV_VALUE} -if @var{ctx}, @var{cipher} or @var{plain} is not a valid pointer, -@code{GPG_ERR_NO_DATA} if @var{cipher} does not contain any data to -decrypt, @code{GPG_ERR_DECRYPT_FAILED} if @var{cipher} is not a valid -cipher text, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the -secret key could not be retrieved, and passes through any errors that -are reported by the crypto engine support routines. -@end deftypefun - -@deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}}) -The function @code{gpgme_op_decrypt_verify_start} initiates a -@code{gpgme_op_decrypt_verify} operation. It can be completed by -calling @code{gpgme_wait} on the context. @xref{Waiting For -Completion}. - -The function returns the error code @code{GPG_ERR_NO_ERROR} if the -operation could be started successfully, @code{GPG_ERR_INV_VALUE} if -@var{ctx}, @var{cipher}, @var{plain} or @var{r_stat} is not a valid -pointer, and @code{GPG_ERR_NO_DATA} if @var{cipher} does not contain -any data to decrypt. -@end deftypefun - - -@node Sign -@subsection Sign -@cindex signature, creation -@cindex sign -@cindex cryptographic operation, signing - -A signature can contain signatures by one or more keys. The set of -keys used to create a signatures is contained in a context, and is -applied to all following signing operations in this context (until the -set is changed). - -@menu -* Selecting Signers:: How to choose the keys to sign with. -* Creating a Signature:: How to create a signature. -* Signature Notation Data:: How to add notation data to a signature. -@end menu - - -@node Selecting Signers -@subsubsection Selecting Signers -@cindex signature, selecting signers -@cindex signers, selecting - -The key or the keys used to create a signature are stored in the -context. The following functions can be used to manipulate this list. -If no signer has been set into the context a default key is used for -signing. - -@deftypefun void gpgme_signers_clear (@w{gpgme_ctx_t @var{ctx}}) -The function @code{gpgme_signers_clear} releases a reference for each -key on the signers list and removes the list of signers from the -context @var{ctx}. - -Every context starts with an empty list. -@end deftypefun - -@deftypefun gpgme_error_t gpgme_signers_add (@w{gpgme_ctx_t @var{ctx}}, @w{const gpgme_key_t @var{key}}) -The function @code{gpgme_signers_add} adds the key @var{key} to the -list of signers in the context @var{ctx}. - -Calling this function acquires an additional reference for the key. -@end deftypefun +Calling this function acquires an additional reference for the key. +@end deftypefun @deftypefun @w{unsigned int} gpgme_signers_count (@w{const gpgme_ctx_t @var{ctx}}) The function @code{gpgme_signers_count} returns the number of signer keys in @@ -7096,6 +6396,682 @@ your application. If you are asked to send a log file, make sure that you run your tests only with play data. +@node Deprecated Functions +@appendix Deprecated Functions +@cindex deprecated + +For backward compatibility @acronym{GPGME} has a number of functions, +data types and constants which are deprecated and should not be used +anymore. We document here those which are really old to help +understanding old code and to allow migration to their modern +counterparts. + +@strong{Warning:} These interfaces will be removed in a future version +of @acronym{GPGME}. + +@deftypefun void gpgme_key_release (@w{gpgme_key_t @var{key}}) +The function @code{gpgme_key_release} is equivalent to +@code{gpgme_key_unref}. +@end deftypefun + +@deftypefun void gpgme_trust_item_release (@w{gpgme_trust_item_t @var{item}}) +The function @code{gpgme_trust_item_release} is an alias for +@code{gpgme_trust_item_unref}. +@end deftypefun + + +@deftypefun gpgme_error_t gpgme_op_import_ext (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}}, @w{int *@var{nr}}) +The function @code{gpgme_op_import_ext} is equivalent to: + +@example + gpgme_error_t err = gpgme_op_import (ctx, keydata); + if (!err) + @{ + gpgme_import_result_t result = gpgme_op_import_result (ctx); + *nr = result->considered; + @} +@end example +@end deftypefun + + +@deftp {Data type} {gpgme_error_t (*gpgme_edit_cb_t) @ + (@w{void *@var{handle}}, @ + @w{gpgme_status_code_t @var{status}}, @ + @w{const char *@var{args}}, @ + @w{int @var{fd}})} +@tindex gpgme_edit_cb_t +The @code{gpgme_edit_cb_t} type is the type of functions which +@acronym{GPGME} calls if it a key edit operation is on-going. The +status code @var{status} and the argument line @var{args} are passed +through by @acronym{GPGME} from the crypto engine. The file +descriptor @var{fd} is -1 for normal status messages. If @var{status} +indicates a command rather than a status message, the response to the +command should be written to @var{fd}. The @var{handle} is provided +by the user at start of operation. + +The function should return @code{GPG_ERR_FALSE} if it did not handle +the status code, @code{0} for success, or any other error value. +@end deftp + +@deftypefun gpgme_error_t gpgme_op_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}}) +Note: This function is deprecated, please use +@code{gpgme_op_interact} instead. + +The function @code{gpgme_op_edit} processes the key @var{KEY} +interactively, using the edit callback function @var{FNC} with the +handle @var{HANDLE}. The callback is invoked for every status and +command request from the crypto engine. The output of the crypto +engine is written to the data object @var{out}. + +Note that the protocol between the callback function and the crypto +engine is specific to the crypto engine and no further support in +implementing this protocol correctly is provided by @acronym{GPGME}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +edit operation completes successfully, @code{GPG_ERR_INV_VALUE} if +@var{ctx} or @var{key} is not a valid pointer, and any error returned +by the crypto engine or the edit callback handler. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}}) +Note: This function is deprecated, please use +@code{gpgme_op_interact_start} instead. + +The function @code{gpgme_op_edit_start} initiates a +@code{gpgme_op_edit} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +operation was started successfully, and @code{GPG_ERR_INV_VALUE} if +@var{ctx} or @var{key} is not a valid pointer. +@end deftypefun + + +@deftypefun gpgme_error_t gpgme_op_card_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}}) +Note: This function is deprecated, please use @code{gpgme_op_interact} +with the flag @code{GPGME_INTERACT_CARD} instead. + +The function @code{gpgme_op_card_edit} is analogous to +@code{gpgme_op_edit}, but should be used to process the smart card corresponding to the key @var{key}. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_card_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}}) +Note: This function is deprecated, please use @code{gpgme_op_interact_start} +with the flag @code{GPGME_INTERACT_CARD} instead. + +The function @code{gpgme_op_card_edit_start} initiates a +@code{gpgme_op_card_edit} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +operation was started successfully, and @code{GPG_ERR_INV_VALUE} if +@var{ctx} or @var{key} is not a valid pointer. +@end deftypefun + + + +@deftypefun gpgme_error_t gpgme_data_new_with_read_cb (@w{gpgme_data_t *@var{dh}}, @w{int (*@var{readfunc})} (@w{void *@var{hook}}, @w{char *@var{buffer}}, @w{size_t @var{count}}, @w{size_t *@var{nread}}), @w{void *@var{hook_value}}) +The function @code{gpgme_data_new_with_read_cb} creates a new +@code{gpgme_data_t} object and uses the callback function @var{readfunc} +to retrieve the data on demand. As the callback function can supply +the data in any way it wants, this is the most flexible data type +@acronym{GPGME} provides. However, it can not be used to write data. + +The callback function receives @var{hook_value} as its first argument +whenever it is invoked. It should return up to @var{count} bytes in +@var{buffer}, and return the number of bytes actually read in +@var{nread}. It may return @code{0} in @var{nread} if no data is +currently available. To indicate @code{EOF} the function should +return with an error code of @code{-1} and set @var{nread} to +@code{0}. The callback function may support to reset its internal +read pointer if it is invoked with @var{buffer} and @var{nread} being +@code{NULL} and @var{count} being @code{0}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +data object was successfully created, @code{GPG_ERR_INV_VALUE} if +@var{dh} or @var{readfunc} is not a valid pointer, and +@code{GPG_ERR_ENOMEM} if not enough memory is available. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_data_rewind (@w{gpgme_data_t @var{dh}}) +The function @code{gpgme_data_rewind} is equivalent to: + +@example + return (gpgme_data_seek (dh, 0, SEEK_SET) == -1) + ? gpgme_error_from_errno (errno) : 0; +@end example +@end deftypefun + + +@deftp {Data type} gpgme_attr_t +The @code{gpgme_attr_t} type is used to specify a key or trust item +attribute. The following attributes are defined: + +@table @code +@item GPGME_ATTR_KEYID +This is the key ID of a sub key. It is representable as a string. + +For trust items, the trust item refers to the key with this ID. + +@item GPGME_ATTR_FPR +This is the fingerprint of a sub key. It is representable as a +string. + +@item GPGME_ATTR_ALGO +This is the crypto algorithm for which the sub key can be used. It +is representable as a string and as a number. The numbers correspond +to the @code{enum gcry_pk_algos} values in the gcrypt library. + +@item GPGME_ATTR_LEN +This is the key length of a sub key. It is representable as a +number. + +@item GPGME_ATTR_CREATED +This is the timestamp at creation time of a sub key. It is +representable as a number. + +@item GPGME_ATTR_EXPIRE +This is the expiration time of a sub key. It is representable as a +number. + +@item GPGME_ATTR_OTRUST +XXX FIXME (also for trust items) + +@item GPGME_ATTR_USERID +This is a user ID. There can be more than one user IDs in a +@var{gpgme_key_t} object. The first one (with index 0) is the primary +user ID. The user ID is representable as a number. + +For trust items, this is the user ID associated with this trust item. + +@item GPGME_ATTR_NAME +This is the name belonging to a user ID. It is representable as a string. + +@item GPGME_ATTR_EMAIL +This is the email address belonging to a user ID. It is representable +as a string. + +@item GPGME_ATTR_COMMENT +This is the comment belonging to a user ID. It is representable as a +string. + +@item GPGME_ATTR_VALIDITY +This is the validity belonging to a user ID. It is representable as a +string and as a number. See below for a list of available validities. + +For trust items, this is the validity that is associated with this +trust item. + +@item GPGME_ATTR_UID_REVOKED +This specifies if a user ID is revoked. It is representable as a +number, and is @code{1} if the user ID is revoked, and @code{0} +otherwise. + +@item GPGME_ATTR_UID_INVALID +This specifies if a user ID is invalid. It is representable as a +number, and is @code{1} if the user ID is invalid, and @code{0} +otherwise. + +@item GPGME_ATTR_LEVEL +This is the trust level of a trust item. + +@item GPGME_ATTR_TYPE +This returns information about the type of key. For the string function +this will eother be "PGP" or "X.509". The integer function returns 0 +for PGP and 1 for X.509. It is also used for the type of a trust item. + +@item GPGME_ATTR_IS_SECRET +This specifies if the key is a secret key. It is representable as a +number, and is @code{1} if the key is revoked, and @code{0} otherwise. + +@item GPGME_ATTR_KEY_REVOKED +This specifies if a sub key is revoked. It is representable as a +number, and is @code{1} if the key is revoked, and @code{0} otherwise. + +@item GPGME_ATTR_KEY_INVALID +This specifies if a sub key is invalid. It is representable as a +number, and is @code{1} if the key is invalid, and @code{0} otherwise. + +@item GPGME_ATTR_KEY_EXPIRED +This specifies if a sub key is expired. It is representable as a +number, and is @code{1} if the key is expired, and @code{0} otherwise. + +@item GPGME_ATTR_KEY_DISABLED +This specifies if a sub key is disabled. It is representable as a +number, and is @code{1} if the key is disabled, and @code{0} otherwise. + +@item GPGME_ATTR_KEY_CAPS +This is a description of the capabilities of a sub key. It is +representable as a string. The string contains the letter ``e'' if +the key can be used for encryption, ``s'' if the key can be used for +signatures, and ``c'' if the key can be used for certifications. + +@item GPGME_ATTR_CAN_ENCRYPT +This specifies if a sub key can be used for encryption. It is +representable as a number, and is @code{1} if the sub key can be used +for encryption, and @code{0} otherwise. + +@item GPGME_ATTR_CAN_SIGN +This specifies if a sub key can be used to create data signatures. It +is representable as a number, and is @code{1} if the sub key can be +used for signatures, and @code{0} otherwise. + +@item GPGME_ATTR_CAN_CERTIFY +This specifies if a sub key can be used to create key certificates. +It is representable as a number, and is @code{1} if the sub key can be +used for certifications, and @code{0} otherwise. + +@item GPGME_ATTR_SERIAL +The X.509 issuer serial attribute of the key. It is representable as +a string. + +@item GPGME_ATTR_ISSUE +The X.509 issuer name attribute of the key. It is representable as a +string. + +@item GPGME_ATTR_CHAINID +The X.509 chain ID can be used to build the certification chain. It +is representable as a string. +@end table +@end deftp + +@deftypefun {const char *} gpgme_key_get_string_attr (@w{gpgme_key_t @var{key}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) +The function @code{gpgme_key_get_string_attr} returns the value of the +string-representable attribute @var{what} of key @var{key}. If the +attribute is an attribute of a sub key or an user ID, @var{idx} +specifies the sub key or user ID of which the attribute value is +returned. The argument @var{reserved} is reserved for later use and +should be @code{NULL}. + +The string returned is only valid as long as the key is valid. + +The function returns @code{0} if an attribute can't be returned as a +string, @var{key} is not a valid pointer, @var{idx} out of range, +or @var{reserved} not @code{NULL}. +@end deftypefun + +@deftypefun {unsigned long} gpgme_key_get_ulong_attr (@w{gpgme_key_t @var{key}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) +The function @code{gpgme_key_get_ulong_attr} returns the value of the +number-representable attribute @var{what} of key @var{key}. If the +attribute is an attribute of a sub key or an user ID, @var{idx} +specifies the sub key or user ID of which the attribute value is +returned. The argument @var{reserved} is reserved for later use and +should be @code{NULL}. + +The function returns @code{0} if the attribute can't be returned as a +number, @var{key} is not a valid pointer, @var{idx} out of range, or +@var{reserved} not @code{NULL}. +@end deftypefun + + +@c +@c Key Signatures +@c +The signatures on a key are only available if the key was retrieved +via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode +enabled, because it is expensive to retrieve all signatures of a key. + +So, before using the below interfaces to retrieve the signatures on a +key, you have to make sure that the key was listed with signatures +enabled. One convenient, but blocking, way to do this is to use the +function @code{gpgme_get_key}. + +@deftp {Data type} gpgme_attr_t +The @code{gpgme_attr_t} type is used to specify a key signature +attribute. The following attributes are defined: + +@table @code +@item GPGME_ATTR_KEYID +This is the key ID of the key which was used for the signature. It is +representable as a string. + +@item GPGME_ATTR_ALGO +This is the crypto algorithm used to create the signature. It is +representable as a string and as a number. The numbers correspond to +the @code{enum gcry_pk_algos} values in the gcrypt library. + +@item GPGME_ATTR_CREATED +This is the timestamp at creation time of the signature. It is +representable as a number. + +@item GPGME_ATTR_EXPIRE +This is the expiration time of the signature. It is representable as +a number. + +@item GPGME_ATTR_USERID +This is the user ID associated with the signing key. The user ID is +representable as a number. + +@item GPGME_ATTR_NAME +This is the name belonging to a user ID. It is representable as a string. + +@item GPGME_ATTR_EMAIL +This is the email address belonging to a user ID. It is representable +as a string. + +@item GPGME_ATTR_COMMENT +This is the comment belonging to a user ID. It is representable as a +string. + +@item GPGME_ATTR_KEY_REVOKED +This specifies if a key signature is a revocation signature. It is +representable as a number, and is @code{1} if the key is revoked, and +@code{0} otherwise. + +@c @item GPGME_ATTR_KEY_EXPIRED +@c This specifies if a key signature is expired. It is representable as +@c a number, and is @code{1} if the key is revoked, and @code{0} +@c otherwise. +@c +@item GPGME_ATTR_SIG_CLASS +This specifies the signature class of a key signature. It is +representable as a number. The meaning is specific to the crypto +engine. + +@item GPGME_ATTR_SIG_CLASS +This specifies the signature class of a key signature. It is +representable as a number. The meaning is specific to the crypto +engine. + +@item GPGME_ATTR_SIG_STATUS +This is the same value as returned by @code{gpgme_get_sig_status}. +@end table +@end deftp + +@deftypefun {const char *} gpgme_key_sig_get_string_attr (@w{gpgme_key_t @var{key}}, @w{int @var{uid_idx}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) +The function @code{gpgme_key_sig_get_string_attr} returns the value of +the string-representable attribute @var{what} of the signature +@var{idx} on the user ID @var{uid_idx} in the key @var{key}. The +argument @var{reserved} is reserved for later use and should be +@code{NULL}. + +The string returned is only valid as long as the key is valid. + +The function returns @code{0} if an attribute can't be returned as a +string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx} +out of range, or @var{reserved} not @code{NULL}. +@end deftypefun + +@deftypefun {unsigned long} gpgme_key_sig_get_ulong_attr (@w{gpgme_key_t @var{key}}, @w{int @var{uid_idx}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) +The function @code{gpgme_key_sig_get_ulong_attr} returns the value of +the number-representable attribute @var{what} of the signature +@var{idx} on the user ID @var{uid_idx} in the key @var{key}. The +argument @var{reserved} is reserved for later use and should be +@code{NULL}. + +The function returns @code{0} if an attribute can't be returned as a +string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx} +out of range, or @var{reserved} not @code{NULL}. +@end deftypefun + + +@c node Information About Trust Items +@c subsection Information About Trust Items +@c cindex trust item, information about +@c cindex trust item, attributes +@c cindex attributes, of a trust item + +Trust items have attributes which can be queried using the interfaces +below. The attribute identifiers are shared with those for key +attributes. @xref{Information About Keys}. + +@deftypefun {const char *} gpgme_trust_item_get_string_attr (@w{gpgme_trust_item_t @var{item}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) +The function @code{gpgme_trust_item_get_string_attr} returns the value +of the string-representable attribute @var{what} of trust item +@var{item}. The arguments @var{idx} and @var{reserved} are reserved +for later use and should be @code{0} and @code{NULL} respectively. + +The string returned is only valid as long as the key is valid. + +The function returns @code{0} if an attribute can't be returned as a +string, @var{key} is not a valid pointer, @var{idx} out of range, +or @var{reserved} not @code{NULL}. +@end deftypefun + +@deftypefun int gpgme_trust_item_get_int_attr (@w{gpgme_trust_item_t @var{item}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) +The function @code{gpgme_trust_item_get_int_attr} returns the value of +the number-representable attribute @var{what} of trust item +@var{item}. If the attribute occurs more than once in the trust item, +the index is specified by @var{idx}. However, currently no such +attribute exists, so @var{idx} should be @code{0}. The argument +@var{reserved} is reserved for later use and should be @code{NULL}. + +The function returns @code{0} if the attribute can't be returned as a +number, @var{key} is not a valid pointer, @var{idx} out of range, +or @var{reserved} not @code{NULL}. +@end deftypefun + + +@deftp {Data type} {enum gpgme_sig_stat_t} +@tindex gpgme_sig_stat_t +The @code{gpgme_sig_stat_t} type holds the result of a signature check, or +the combined result of all signatures. The following results are +possible: + +@table @code +@item GPGME_SIG_STAT_NONE +This status should not occur in normal operation. + +@item GPGME_SIG_STAT_GOOD +This status indicates that the signature is valid. For the combined +result this status means that all signatures are valid. + +@item GPGME_SIG_STAT_GOOD_EXP +This status indicates that the signature is valid but expired. For +the combined result this status means that all signatures are valid +and expired. + +@item GPGME_SIG_STAT_GOOD_EXPKEY +This status indicates that the signature is valid but the key used to +verify the signature has expired. For the combined result this status +means that all signatures are valid and all keys are expired. + +@item GPGME_SIG_STAT_BAD +This status indicates that the signature is invalid. For the combined +result this status means that all signatures are invalid. + +@item GPGME_SIG_STAT_NOKEY +This status indicates that the signature could not be verified due to +a missing key. For the combined result this status means that all +signatures could not be checked due to missing keys. + +@item GPGME_SIG_STAT_NOSIG +This status indicates that the signature data provided was not a real +signature. + +@item GPGME_SIG_STAT_ERROR +This status indicates that there was some other error which prevented +the signature verification. + +@item GPGME_SIG_STAT_DIFF +For the combined result this status means that at least two signatures +have a different status. You can get each key's status with +@code{gpgme_get_sig_status}. +@end table +@end deftp + +@deftypefun {const char *} gpgme_get_sig_status (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_sig_stat_t *@var{r_stat}}, @w{time_t *@var{r_created}}) +The function @code{gpgme_get_sig_status} is equivalent to: + +@example + gpgme_verify_result_t result; + gpgme_signature_t sig; + + result = gpgme_op_verify_result (ctx); + sig = result->signatures; + + while (sig && idx) + @{ + sig = sig->next; + idx--; + @} + if (!sig || idx) + return NULL; + + if (r_stat) + @{ + switch (gpg_err_code (sig->status)) + @{ + case GPG_ERR_NO_ERROR: + *r_stat = GPGME_SIG_STAT_GOOD; + break; + + case GPG_ERR_BAD_SIGNATURE: + *r_stat = GPGME_SIG_STAT_BAD; + break; + + case GPG_ERR_NO_PUBKEY: + *r_stat = GPGME_SIG_STAT_NOKEY; + break; + + case GPG_ERR_NO_DATA: + *r_stat = GPGME_SIG_STAT_NOSIG; + break; + + case GPG_ERR_SIG_EXPIRED: + *r_stat = GPGME_SIG_STAT_GOOD_EXP; + break; + + case GPG_ERR_KEY_EXPIRED: + *r_stat = GPGME_SIG_STAT_GOOD_EXPKEY; + break; + + default: + *r_stat = GPGME_SIG_STAT_ERROR; + break; + @} + @} + if (r_created) + *r_created = sig->timestamp; + return sig->fpr; +@end example +@end deftypefun + +@deftypefun {const char *} gpgme_get_sig_string_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{what}}, @w{int @var{whatidx}}) +The function @code{gpgme_get_sig_string_attr} is equivalent to: + +@example + gpgme_verify_result_t result; + gpgme_signature_t sig; + + result = gpgme_op_verify_result (ctx); + sig = result->signatures; + + while (sig && idx) + @{ + sig = sig->next; + idx--; + @} + if (!sig || idx) + return NULL; + + switch (what) + @{ + case GPGME_ATTR_FPR: + return sig->fpr; + + case GPGME_ATTR_ERRTOK: + if (whatidx == 1) + return sig->wrong_key_usage ? "Wrong_Key_Usage" : ""; + else + return ""; + default: + break; + @} + + return NULL; +@end example +@end deftypefun + +@deftypefun {const char *} gpgme_get_sig_ulong_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{waht}}, @w{int @var{whatidx}}) +The function @code{gpgme_get_sig_ulong_attr} is equivalent to: + +@example + gpgme_verify_result_t result; + gpgme_signature_t sig; + + result = gpgme_op_verify_result (ctx); + sig = result->signatures; + + while (sig && idx) + @{ + sig = sig->next; + idx--; + @} + if (!sig || idx) + return 0; + + switch (what) + @{ + case GPGME_ATTR_CREATED: + return sig->timestamp; + + case GPGME_ATTR_EXPIRE: + return sig->exp_timestamp; + + case GPGME_ATTR_VALIDITY: + return (unsigned long) sig->validity; + + case GPGME_ATTR_SIG_STATUS: + switch (sig->status) + @{ + case GPG_ERR_NO_ERROR: + return GPGME_SIG_STAT_GOOD; + + case GPG_ERR_BAD_SIGNATURE: + return GPGME_SIG_STAT_BAD; + + case GPG_ERR_NO_PUBKEY: + return GPGME_SIG_STAT_NOKEY; + + case GPG_ERR_NO_DATA: + return GPGME_SIG_STAT_NOSIG; + + case GPG_ERR_SIG_EXPIRED: + return GPGME_SIG_STAT_GOOD_EXP; + + case GPG_ERR_KEY_EXPIRED: + return GPGME_SIG_STAT_GOOD_EXPKEY; + + default: + return GPGME_SIG_STAT_ERROR; + @} + + case GPGME_ATTR_SIG_SUMMARY: + return sig->summary; + + default: + break; + @} + return 0; +@end example +@end deftypefun + +@deftypefun {const char *} gpgme_get_sig_key (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_key_t *@var{r_key}}) +The function @code{gpgme_get_sig_key} is equivalent to: + +@example + gpgme_verify_result_t result; + gpgme_signature_t sig; + + result = gpgme_op_verify_result (ctx); + sig = result->signatures; + + while (sig && idx) + @{ + sig = sig->next; + idx--; + @} + if (!sig || idx) + return gpg_error (GPG_ERR_EOF); + + return gpgme_get_key (ctx, sig->fpr, r_key, 0); +@end example +@end deftypefun + + + + @include lesser.texi -- cgit v1.2.3