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