\input texinfo @c -*- mode: texinfo; coding: utf-8; -*-
@documentencoding UTF-8
@setfilename gpgme.info
+@include defs.inc
@settitle The `GnuPG Made Easy' Reference Manual
@dircategory GNU Libraries
@syncodeindex pg fn
@copying
-Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007,
-2008, 2010, 2012, 2013, 2014 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
General Public License for more details.
@end copying
-@include version.texi
-
@c Macros used by the description of the UI server protocol
@macro clnt
@sc{c:} @c
@center for version @value{VERSION}
@page
@vskip 0pt plus 1filll
-Published by g10 Code GmbH@* HÃ\83¼ttenstr. 61@* 40699 Erkrath, Germany
+Published by The GnuPG Project@* c/o g10 Code GmbH@* Hüttenstr. 61@* 40699 Erkrath, Germany
@insertcopying
@end titlepage
* 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'.
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.
* Exporting Keys:: Retrieving key data from the key ring.
* Importing Keys:: Adding keys to the key ring.
* Deleting Keys:: Removing keys from the key ring.
* Changing Passphrases:: Change the passphrase of a key.
+* Changing TOFU Data:: Changing data pertaining to TOFU.
* Advanced Key Editing:: Advanced key edit operation.
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
Supported thread packages are @option{--thread=pth} and
@option{--thread=pthread}.
+If you need to detect the installed language bindings you can use list
+them using:
+
+@example
+gpgme-config --print-lang
+@end example
+
+or test for the availability using
+
+@example
+gpgme-config --have-lang=python && echo 'Bindings for Pythons available'
+@end example
+
@node Largefile Support (LFS)
@section Largefile Support (LFS)
features are identified by the following values for @var{name}:
@table @code
-@item "debug"
+@item debug
To enable debugging use the string ``debug'' for @var{name} and
@var{value} identical to the value used with the environment variable
@code{GPGME_DEBUG}.
-@item "disable-gpgconf"
+@item disable-gpgconf
Using this feature with any @var{value} disables the detection of the
gpgconf program and thus forces GPGME to fallback into the simple
OpenPGP only mode. It may be used to force the use of GnuPG-1 on
the use of @code{gpgme_set_engine_info} is a better way to select a
specific engine version.
-@item "gpgconf-name"
-@itemx "gpg-name"
+@item gpgconf-name
+@itemx gpg-name
Set the name of the gpgconf respective gpg binary. The defaults are
@code{GNU/GnuPG/gpgconf} and @code{GNU/GnuPG/gpg}. Under Unix the
leading directory part is ignored. Under Windows the leading
@code{.exe} suffix is added by GPGME. Use forward slashed even under
Windows.
-@item "w32-inst-dir"
+@item require-gnupg
+Set the mimimum version of the required GnuPG engine. If that version
+is not met, GPGME fails early instead of trying to use the existant
+version. The given version must be a string with major, minor, and
+micro number. Example: "2.1.0".
+
+@item w32-inst-dir
On Windows GPGME needs to know its installation directory to find its
spawn helper. This is in general no problem because a DLL has this
information. Some applications however link statically to GPGME and
@item homedir
Return the default home directory.
+@item sysconfdir
+Return the name of the system configuration directory
+
+@item bindir
+Return the name of the directory with GnuPG program files.
+
+@item libdir
+Return the name of the directory with GnuPG related library files.
+
+@item libexecdir
+Return the name of the directory with GnuPG helper program files.
+
+@item datadir
+Return the name of the directory with GnuPG shared data.
+
+@item localedir
+Return the name of the directory with GnuPG locale data.
+
@item agent-socket
Return the name of the socket to connect to the gpg-agent.
+@item agent-ssh-socket
+Return the name of the socket to connect to the ssh-agent component of
+gpg-agent.
+
+@item dirmngr-socket
+Return the name of the socket to connect to the dirmngr.
+
@item uiserver-socket
Return the name of the socket to connect to the user interface server.
enough memory is available.
@end deftypefun
-The following interface is deprecated and only provided for backward
-compatibility. Don't use it. It will be removed in a future version
-of @acronym{GPGME}.
-
-@deftypefun gpgme_error_t gpgme_data_new_with_read_cb (@w{gpgme_data_t *@var{dh}}, @w{int (*@var{readfunc})} (@w{void *@var{hook}}, @w{char *@var{buffer}}, @w{size_t @var{count}}, @w{size_t *@var{nread}}), @w{void *@var{hook_value}})
-The function @code{gpgme_data_new_with_read_cb} creates a new
-@code{gpgme_data_t} object and uses the callback function @var{readfunc}
-to retrieve the data on demand. As the callback function can supply
-the data in any way it wants, this is the most flexible data type
-@acronym{GPGME} provides. However, it can not be used to write data.
-
-The callback function receives @var{hook_value} as its first argument
-whenever it is invoked. It should return up to @var{count} bytes in
-@var{buffer}, and return the number of bytes actually read in
-@var{nread}. It may return @code{0} in @var{nread} if no data is
-currently available. To indicate @code{EOF} the function should
-return with an error code of @code{-1} and set @var{nread} to
-@code{0}. The callback function may support to reset its internal
-read pointer if it is invoked with @var{buffer} and @var{nread} being
-@code{NULL} and @var{count} being @code{0}.
-
-The function returns the error code @code{GPG_ERR_NO_ERROR} if the
-data object was successfully created, @code{GPG_ERR_INV_VALUE} if
-@var{dh} or @var{readfunc} is not a valid pointer, and
-@code{GPG_ERR_ENOMEM} if not enough memory is available.
-@end deftypefun
-
@node Destroying Data Buffers
@section Destroying Data Buffers
If the function fails, -1 is returned and @var{errno} is set.
@end deftypefun
-The following function is deprecated and should not be used. It will
-be removed in a future version of @acronym{GPGME}.
-
-@deftypefun gpgme_error_t gpgme_data_rewind (@w{gpgme_data_t @var{dh}})
-The function @code{gpgme_data_rewind} is equivalent to:
-
-@example
- return (gpgme_data_seek (dh, 0, SEEK_SET) == -1)
- ? gpgme_error_from_errno (errno) : 0;
-@end example
-@end deftypefun
-
-
-
@node Data Buffer Meta-Data
@subsection Data Buffer Meta-Data
the data object with the handle @var{dh} to @var{enc}.
@end deftypefun
+@deftypefun {gpgme_error_t} gpgme_data_set_flag @
+ (@w{gpgme_data_t @var{dh}}, @
+ @w{const char *@var{name}}, @
+ @w{const char *@var{value}})
+
+Some minor properties of the data object can be controlled with flags
+set by this function. The properties are identified by the following
+values for @var{name}:
+
+@table @code
+@item size-hint
+The value is a decimal number with the length gpgme shall assume for
+this data object. This is useful if the data is provided by callbacks
+or via file descriptors but the applications knows the total size of
+the data. If this is set the OpenPGP engine may use this to decide on
+buffer allocation strategies and to provide a total value for its
+progress information.
+
+@end table
+
+This function returns @code{0} on success.
+@end deftypefun
+
+
@node Data Buffer Convenience
@subsection Data Buffer Convenience Functions
@cindex data buffer, convenience
keys. This only works if @code{GPGME_KEYLIST_MODE_SIGS} is also
enabled.
+@item GPGME_KEYLIST_MODE_WITH_TOFU
+The @code{GPGME_KEYLIST_MODE_WITH_TOFU} symbol specifies that
+information pertaining to the TOFU trust model should be included in
+the listed keys.
+
@item GPGME_KEYLIST_MODE_WITH_SECRET
The @code{GPGME_KEYLIST_MODE_WITH_SECRET} returns information about
the presence of a corresponding secret key in a public key listing. A
respective keys that should be used for the operation. The following
section describes how such keys can be selected and manipulated.
+
+@menu
+* Key objects:: Description of the key structures.
+* Listing Keys:: Browsing the list of available keys.
+* Information About Keys:: Requesting detailed information about keys.
+* Manipulating Keys:: Operations on keys.
+* Generating Keys:: Creating new key pairs.
+* Signing Keys:: Adding key signatures to public keys.
+* Exporting Keys:: Retrieving key data from the key ring.
+* Importing Keys:: Adding keys to the key ring.
+* Deleting Keys:: Removing keys from the key ring.
+* Changing Passphrases:: Change the passphrase of a key.
+* Changing TOFU Data:: Changing data pertaining to TOFU.
+* Advanced Key Editing:: Advanced key edit operation.
+@end menu
+
+@node Key objects
+@subsection Key objects
+
+The keys are represented in GPGME by structures which may only be read
+by the application but never be allocated or changed. They are valid
+as long as the key object itself is valid.
+
+@deftp {Data type} gpgme_key_t
+
+The @code{gpgme_key_t} type is a pointer to a key object. It has the
+following members:
+
+@table @code
+@item gpgme_keylist_mode_t keylist_mode
+The keylist mode that was active when the key was retrieved.
+
+@item unsigned int revoked : 1
+This is true if the key is revoked.
+
+@item unsigned int expired : 1
+This is true if the key is expired.
+
+@item unsigned int disabled : 1
+This is true if the key is disabled.
+
+@item unsigned int invalid : 1
+This is true if the key is invalid. This might have several reasons,
+for a example for the S/MIME backend, it will be set during key
+listings if the key could not be validated due to missing
+certificates or unmatched policies.
+
+@item unsigned int can_encrypt : 1
+This is true if the key (ie one of its subkeys) can be used for
+encryption.
+
+@item unsigned int can_sign : 1
+This is true if the key (ie one of its subkeys) can be used to create
+data signatures.
+
+@item unsigned int can_certify : 1
+This is true if the key (ie one of its subkeys) can be used to create
+key certificates.
+
+@item unsigned int can_authenticate : 1
+This is true if the key (ie one of its subkeys) can be used for
+authentication.
+
+@item unsigned int is_qualified : 1
+This is true if the key can be used for qualified signatures according
+to local government regulations.
+
+@item unsigned int secret : 1
+This is true if the key is a secret key. Note, that this will always
+be true even if the corresponding subkey flag may be false
+(offline/stub keys). This is only set if a listing of secret keys has
+been requested or if @code{GPGME_KEYLIST_MODE_WITH_SECRET} is active.
+
+@item gpgme_protocol_t protocol
+This is the protocol supported by this key.
+
+@item char *issuer_serial
+If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
+issuer serial.
+
+@item char *issuer_name
+If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
+issuer name.
+
+@item char *chain_id
+If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
+chain ID, which can be used to built the certificate chain.
+
+@item gpgme_validity_t owner_trust
+If @code{protocol} is @code{GPGME_PROTOCOL_OpenPGP}, then this is the
+owner trust.
+
+@item gpgme_subkey_t subkeys
+This is a linked list with the subkeys of the key. The first subkey
+in the list is the primary key and usually available.
+
+@item gpgme_user_id_t uids
+This is a linked list with the user IDs of the key. The first user ID
+in the list is the main (or primary) user ID.
+
+@item char *fpr
+This field gives the fingerprint of the primary key. Note that
+this is a copy of the fingerprint of the first subkey. For an
+incomplete key (for example from a verification result) a subkey may
+be missing but this field may be set nevertheless.
+
+@end table
+@end deftp
+
+
@deftp {Data type} gpgme_subkey_t
+
The @code{gpgme_subkey_t} type is a pointer to a subkey structure.
-Sub keys are one component of a @code{gpgme_key_t} object. In fact,
+Subkeys are one component of a @code{gpgme_key_t} object. In fact,
subkeys are those parts that contains the real information about the
individual cryptographic keys that belong to the same key object. One
@code{gpgme_key_t} can contain several subkeys. The first subkey in
This is the fingerprint of the subkey in hexadecimal digits, if
available.
+@item char *keygrip
+The keygrip of the subkey in hex digit form or @code{NULL} if not
+availabale.
+
@item long int timestamp
This is the creation timestamp of the subkey. This is -1 if the
timestamp is invalid, and 0 if it is not available.
@end table
@end deftp
+@deftp {Data type} gpgme_user_id_t
+
+A user ID is a component of a @code{gpgme_key_t} object. One key can
+have many user IDs. The first one in the list is the main (or
+primary) user ID.
+
+The user ID structure has the following members.
+
+@table @code
+@item gpgme_user_id_t next
+This is a pointer to the next user ID structure in the linked list, or
+@code{NULL} if this is the last element.
+
+@item unsigned int revoked : 1
+This is true if the user ID is revoked.
+
+@item unsigned int invalid : 1
+This is true if the user ID is invalid.
+
+@item gpgme_validity_t validity
+This specifies the validity of the user ID.
+
+@item char *uid
+This is the user ID string.
+
+@item char *name
+This is the name component of @code{uid}, if available.
+
+@item char *comment
+This is the comment component of @code{uid}, if available.
+
+@item char *email
+This is the email component of @code{uid}, if available.
+
+@item char *address;
+The mail address (addr-spec from RFC-5322) of the user ID string.
+This is general the same as the @code{email} part of this structure
+but might be slightly different. If no mail address is available
+@code{NULL} is stored.
+
+@item gpgme_tofu_info_t tofu
+If not @code{NULL} information from the TOFU database pertaining to
+this user id.
+
+@item gpgme_key_sig_t signatures
+This is a linked list with the signatures on this user ID.
+@end table
+@end deftp
+
+
@deftp {Data type} gpgme_key_sig_t
+
The @code{gpgme_key_sig_t} type is a pointer to a key signature structure.
Key signatures are one component of a @code{gpgme_key_t} object, and
-validate user IDs on the key.
+validate user IDs on the key in the OpenPGP protocol.
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
@end table
@end deftp
-@deftp {Data type} gpgme_user_id_t
-A user ID is a component of a @code{gpgme_key_t} object. One key can
-have many user IDs. The first one in the list is the main (or
-primary) user ID.
-
-The user ID structure has the following members.
-@table @code
-@item gpgme_user_id_t next
-This is a pointer to the next user ID structure in the linked list, or
-@code{NULL} if this is the last element.
-@item unsigned int revoked : 1
-This is true if the user ID is revoked.
+@node Listing Keys
+@subsection Listing Keys
+@cindex listing keys
+@cindex key listing
+@cindex key listing, start
+@cindex key ring, list
+@cindex key ring, search
-@item unsigned int invalid : 1
-This is true if the user ID is invalid.
+@deftypefun gpgme_error_t gpgme_op_keylist_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}})
+The function @code{gpgme_op_keylist_start} initiates a key listing
+operation inside the context @var{ctx}. It sets everything up so that
+subsequent invocations of @code{gpgme_op_keylist_next} return the keys
+in the list.
-@item gpgme_validity_t validity
-This specifies the validity of the user ID.
+If @var{pattern} is @code{NULL}, all available keys are returned.
+Otherwise, @var{pattern} contains an engine specific expression that
+is used to limit the list to all keys matching the pattern. Note that
+the total length of the pattern is restricted to an engine-specific
+maximum (a couple of hundred characters are usually accepted). The
+pattern should be used to restrict the search to a certain common name
+or user, not to list many specific keys at once by listing their
+fingerprints or key IDs.
-@item char *uid
-This is the user ID string.
+If @var{secret_only} is not @code{0}, the list is restricted to secret
+keys only.
-@item char *name
-This is the name component of @code{uid}, if available.
-
-@item char *comment
-This is the comment component of @code{uid}, if available.
-
-@item char *email
-This is the email component of @code{uid}, if available.
-
-@item gpgme_key_sig_t signatures
-This is a linked list with the signatures on this user ID.
-@end table
-@end deftp
-
-@deftp {Data type} gpgme_key_t
-The @code{gpgme_key_t} type is a pointer to a key object. It has the
-following members:
-
-@table @code
-@item gpgme_keylist_mode_t keylist_mode
-The keylist mode that was active when the key was retrieved.
-
-@item unsigned int revoked : 1
-This is true if the key is revoked.
-
-@item unsigned int expired : 1
-This is true if the key is expired.
-
-@item unsigned int disabled : 1
-This is true if the key is disabled.
-
-@item unsigned int invalid : 1
-This is true if the key is invalid. This might have several reasons,
-for a example for the S/MIME backend, it will be set in during key
-listsing if the key could not be validated due to a missing
-certificates or unmatched policies.
-
-@item unsigned int can_encrypt : 1
-This is true if the key (ie one of its subkeys) can be used for
-encryption.
-
-@item unsigned int can_sign : 1
-This is true if the key (ie one of its subkeys) can be used to create
-data signatures.
-
-@item unsigned int can_certify : 1
-This is true if the key (ie one of its subkeys) can be used to create
-key certificates.
-
-@item unsigned int can_authenticate : 1
-This is true if the key (ie one of its subkeys) can be used for
-authentication.
-
-@item unsigned int is_qualified : 1
-This is true if the key can be used for qualified signatures according
-to local government regulations.
-
-@item unsigned int secret : 1
-This is true if the key is a secret key. Note, that this will always
-be true even if the corresponding subkey flag may be false
-(offline/stub keys). This is only set if a listing of secret keys has
-been requested or if @code{GPGME_KEYLIST_MODE_WITH_SECRET} is active.
-
-@item gpgme_protocol_t protocol
-This is the protocol supported by this key.
-
-@item char *issuer_serial
-If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
-issuer serial.
-
-@item char *issuer_name
-If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
-issuer name.
-
-@item char *chain_id
-If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
-chain ID, which can be used to built the certificate chain.
-
-@item gpgme_validity_t owner_trust
-If @code{protocol} is @code{GPGME_PROTOCOL_OpenPGP}, then this is the
-owner trust.
-
-@item gpgme_subkey_t subkeys
-This is a linked list with the subkeys of the key. The first subkey
-in the list is the primary key and usually available.
-
-@item gpgme_user_id_t uids
-This is a linked list with the user IDs of the key. The first user ID
-in the list is the main (or primary) user ID.
-@end table
-@end deftp
-
-@menu
-* 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.
-* Exporting Keys:: Retrieving key data from the key ring.
-* Importing Keys:: Adding keys to the key ring.
-* Deleting Keys:: Removing keys from the key ring.
-* Changing Passphrases:: Change the passphrase of a key.
-* Advanced Key Editing:: Advanced key edit operation.
-@end menu
-
-
-@node Listing Keys
-@subsection Listing Keys
-@cindex listing keys
-@cindex key listing
-@cindex key listing, start
-@cindex key ring, list
-@cindex key ring, search
-
-@deftypefun gpgme_error_t gpgme_op_keylist_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}})
-The function @code{gpgme_op_keylist_start} initiates a key listing
-operation inside the context @var{ctx}. It sets everything up so that
-subsequent invocations of @code{gpgme_op_keylist_next} return the keys
-in the list.
-
-If @var{pattern} is @code{NULL}, all available keys are returned.
-Otherwise, @var{pattern} contains an engine specific expression that
-is used to limit the list to all keys matching the pattern. Note that
-the total length of the pattern is restricted to an engine-specific
-maximum (a couple of hundred characters are usually accepted). The
-pattern should be used to restrict the search to a certain common name
-or user, not to list many specific keys at once by listing their
-fingerprints or key IDs.
-
-If @var{secret_only} is not @code{0}, the list is restricted to secret
-keys only.
-
-The context will be busy until either all keys are received (and
-@code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}), or
-@code{gpgme_op_keylist_end} is called to finish the operation.
+The context will be busy until either all keys are received (and
+@code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}), or
+@code{gpgme_op_keylist_end} is called to finish the operation.
The function returns the error code @code{GPG_ERR_INV_VALUE} if
@var{ctx} is not a valid pointer, and passes through any errors that
@end deftp
-The following interfaces are deprecated and only provided for backward
-compatibility. Don't use them. They will be removed in a future
-version of @acronym{GPGME}.
-@deftp {Data type} gpgme_attr_t
-The @code{gpgme_attr_t} type is used to specify a key or trust item
-attribute. The following attributes are defined:
-@table @code
-@item GPGME_ATTR_KEYID
-This is the key ID of a sub key. It is representable as a string.
+@node Manipulating Keys
+@subsection Manipulating Keys
+@cindex key, manipulation
-For trust items, the trust item refers to the key with this ID.
+@deftypefun void gpgme_key_ref (@w{gpgme_key_t @var{key}})
+The function @code{gpgme_key_ref} acquires an additional reference for
+the key @var{key}.
+@end deftypefun
-@item GPGME_ATTR_FPR
-This is the fingerprint of a sub key. It is representable as a
-string.
+@deftypefun void gpgme_key_unref (@w{gpgme_key_t @var{key}})
+The function @code{gpgme_key_unref} releases a reference for the key
+@var{key}. If this was the last reference, the key will be destroyed
+and all resources associated to it will be released.
+@end deftypefun
-@item GPGME_ATTR_ALGO
-This is the crypto algorithm for which the sub key can be used. It
-is representable as a string and as a number. The numbers correspond
-to the @code{enum gcry_pk_algos} values in the gcrypt library.
-@item GPGME_ATTR_LEN
-This is the key length of a sub key. It is representable as a
-number.
+@node Generating Keys
+@subsection Generating Keys
+@cindex key, creation
+@cindex key ring, add
-@item GPGME_ATTR_CREATED
-This is the timestamp at creation time of a sub key. It is
-representable as a number.
+GPGME provides a set of functions to create public key pairs. Most of
+these functions require the use of GnuPG 2.1 and later; for older
+GnuPG versions the @code{gpgme_op_genkey} function can be used.
+Existing code which wants to update to the new functions or new code
+which shall supports older GnuPG versions may try the new functions
+first and provide a fallback to the old function if the error code
+@code{GPG_ERR_NOT_SUPPORTED} is received.
-@item GPGME_ATTR_EXPIRE
-This is the expiration time of a sub key. It is representable as a
-number.
+@c
+@c gpgme_op_createkey
+@c
+@deftypefun gpgme_error_t gpgme_op_createkey @
+ (@w{gpgme_ctx_t @var{ctx}}, @
+ @w{const char *@var{userid}}, @
+ @w{const char *@var{algo}}, @
+ @w{unsigned long @var{reserved}}, @
+ @w{unsigned long @var{expires}}, @
+ @w{gpgme_key_t @var{extrakey}}, @
+ @w{unsigned int @var{flags}});
+
+The function @code{gpgme_op_createkey} generates a new key for the
+procotol active in the context @var{ctx}. As of now this function
+does only work for OpenPGP and requires at least version 2.1.13 of
+GnuPG.
-@item GPGME_ATTR_OTRUST
-XXX FIXME (also for trust items)
+@var{userid} is commonly the mail address associated with the key.
+GPGME does not require a specificy syntax but if more than a mail
+address is given, RFC-822 style format is suggested. The value is
+expected to be in UTF-8 encoding (i.e. no IDN encoding for mail
+addresses). This is a required parameter.
+
+@var{algo} specifies the algorithm for the new key (actually a keypair
+of public and private key). For a list of supported algorithms, see
+the GnuPG manual. If @var{algo} is @code{NULL} or the string
+"default", the key is generated using the default algorithm of the
+engine. If the string "future-default" is used the engine may use an
+algorithm which is planned to be the default in a future release of
+the engine; however existing implementation of the protocol may not be
+able to already handle such future algorithms. For the OpenPGP
+protocol, the specification of a default algorithm, without requesting
+a non-default usage via @var{flags}, triggers the creation of a
+primary key plus a secondary key (subkey).
+
+@var{reserved} must be set to zero.
+
+@var{expires} can be set to the number of seconds since Epoch of the
+desired expiration date in UTC for the new key. Using 0 does not
+set an expiration date. Note that this parameter takes an unsigned long
+value and not a @code{time_t} to avoid problems on systems which use a
+signed 32 bit @code{time_t}. Note further that the OpenPGP protocol
+uses 32 bit values for timestamps and thus can only encode dates up to
+the year 2106.
+
+@var{extrakey} is currently not used and must be set to @code{NULL}.
+A future version of GPGME may use this parameter to create X.509 keys.
+
+@var{flags} can be set to the bit-wise OR of the following flags:
-@item GPGME_ATTR_USERID
-This is a user ID. There can be more than one user IDs in a
-@var{gpgme_key_t} object. The first one (with index 0) is the primary
-user ID. The user ID is representable as a number.
+@table @code
+@item GPGME_CREATE_SIGN
+@itemx GPGME_CREATE_ENCR
+@itemx GPGME_CREATE_CERT
+@itemx GPGME_CREATE_AUTH
+Do not create the key with the default capabilities (key usage) of the
+requested algorithm but use those explicitly given by these flags:
+``signing'', ``encryption'', ``certification'', or ``authentication''.
+The allowed combinations depend on the algorithm.
+
+If any of these flags are set and a default algorithm has been
+selected only one key is created in the case of the OpenPGP
+protocol.
+
+@item GPGME_CREATE_NOPASSWD
+Request generation of the key without password protection.
+
+@item GPGME_CREATE_SELFSIGNED
+For an X.509 key do not create a CSR but a self-signed certificate.
+This has not yet been implemented.
+
+@item GPGME_CREATE_NOSTORE
+Do not store the created key in the local key database.
+This has not yet been implemented.
+
+@item GPGME_CREATE_WANTPUB
+@itemx GPGME_CREATE_WANTSEC
+Return the public or secret key as part of the result structure.
+This has not yet been implemented.
+
+@item GPGME_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.
-For trust items, this is the user ID associated with this trust item.
+@end table
-@item GPGME_ATTR_NAME
-This is the name belonging to a user ID. It is representable as a string.
+After the operation completed successfully, information about the
+created key can be retrieved with @code{gpgme_op_genkey_result}.
-@item GPGME_ATTR_EMAIL
-This is the email address belonging to a user ID. It is representable
-as a string.
+The function returns zero on success, @code{GPG_ERR_NOT_SUPPORTED} if
+the engine does not support the command, or a bunch of other error
+codes.
-@item GPGME_ATTR_COMMENT
-This is the comment belonging to a user ID. It is representable as a
-string.
+@end deftypefun
-@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.
+@deftypefun gpgme_error_t gpgme_op_createkey_start @
+ (@w{gpgme_ctx_t @var{ctx}}, @
+ @w{const char *@var{userid}}, @
+ @w{const char *@var{algo}}, @
+ @w{unsigned long @var{reserved}}, @
+ @w{unsigned long @var{expires}}, @
+ @w{gpgme_key_t @var{extrakey}}, @
+ @w{unsigned int @var{flags}});
-@item GPGME_ATTR_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.
+The function @code{gpgme_op_createkey_start} initiates a
+@code{gpgme_op_createkey} operation; see there for details. It must
+be completed by calling @code{gpgme_wait} on the context.
+@xref{Waiting For Completion}.
-@item GPGME_ATTR_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.
+@end deftypefun
-@item GPGME_ATTR_LEVEL
-This is the trust level of a trust item.
+@c
+@c gpgme_op_createsubkey
+@c
+@deftypefun gpgme_error_t gpgme_op_createsubkey @
+ (@w{gpgme_ctx_t @var{ctx}}, @
+ @w{gpgme_key_t @var{key}}, @
+ @w{const char *@var{algo}}, @
+ @w{unsigned long @var{reserved}}, @
+ @w{unsigned long @var{expires}}, @
+ @w{unsigned int @var{flags}});
-@item GPGME_ATTR_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.
+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.
-@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.
+@var{key} specifies the key to operate on.
-@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.
+@var{algo} specifies the algorithm for the new subkey. For a list of
+supported algorithms, see the GnuPG manual. If @var{algo} is
+@code{NULL} or the string "default", the subkey is generated using the
+default algorithm for an encryption subkey of the engine. If the
+string "future-default" is used the engine may use an encryption
+algorithm which is planned to be the default in a future release of
+the engine; however existing implementation of the protocol may not be
+able to already handle such future algorithms.
-@item 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.
+@var{reserved} must be set to zero.
-@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.
+@var{expires} can be set to the number of seconds since Epoch of the
+desired expiration date in UTC for the new subkey. Using 0 does not
+set an expiration date. Note that this parameter takes an unsigned long
+value and not a @code{time_t} to avoid problems on systems which use a
+signed 32 bit @code{time_t}. Note further that the OpenPGP protocol
+uses 32 bit values for timestamps and thus can only encode dates up to
+the year 2106.
-@item 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.
+@var{flags} takes the same values as described above for
+@code{gpgme_op_createkey}.
-@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.
+After the operation completed successfully, information about the
+created key can be retrieved with @code{gpgme_op_genkey_result}.
-@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.
+The function returns zero on success, @code{GPG_ERR_NOT_SUPPORTED} if
+the engine does not support the command, or a bunch of other error
+codes.
-@item GPGME_ATTR_CAN_SIGN
-This specifies if a sub key can be used to create data signatures. It
-is representable as a number, and is @code{1} if the sub key can be
-used for signatures, and @code{0} otherwise.
-@item GPGME_ATTR_CAN_CERTIFY
-This specifies if a sub key can be used to create key certificates.
-It is representable as a number, and is @code{1} if the sub key can be
-used for certifications, and @code{0} otherwise.
+@end deftypefun
-@item GPGME_ATTR_SERIAL
-The X.509 issuer serial attribute of the key. It is representable as
-a string.
+@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}});
-@item GPGME_ATTR_ISSUE
-The X.509 issuer name attribute of the key. It is representable as a
-string.
+The function @code{gpgme_op_createsubkey_start} initiates a
+@code{gpgme_op_createsubkey} operation; see there for details. It must
+be completed by calling @code{gpgme_wait} on the context.
+@xref{Waiting For Completion}.
-@item GPGME_ATTR_CHAINID
-The X.509 chain ID can be used to build the certification chain. It
-is representable as a string.
-@end table
-@end deftp
-
-@deftypefun {const char *} gpgme_key_get_string_attr (@w{gpgme_key_t @var{key}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
-The function @code{gpgme_key_get_string_attr} returns the value of the
-string-representable attribute @var{what} of key @var{key}. If the
-attribute is an attribute of a sub key or an user ID, @var{idx}
-specifies the sub key or user ID of which the attribute value is
-returned. The argument @var{reserved} is reserved for later use and
-should be @code{NULL}.
-
-The string returned is only valid as long as the key is valid.
-
-The function returns @code{0} if an attribute can't be returned as a
-string, @var{key} is not a valid pointer, @var{idx} out of range,
-or @var{reserved} not @code{NULL}.
-@end deftypefun
-
-@deftypefun {unsigned long} gpgme_key_get_ulong_attr (@w{gpgme_key_t @var{key}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
-The function @code{gpgme_key_get_ulong_attr} returns the value of the
-number-representable attribute @var{what} of key @var{key}. If the
-attribute is an attribute of a sub key or an user ID, @var{idx}
-specifies the sub key or user ID of which the attribute value is
-returned. The argument @var{reserved} is reserved for later use and
-should be @code{NULL}.
-
-The function returns @code{0} if the attribute can't be returned as a
-number, @var{key} is not a valid pointer, @var{idx} out of range, or
-@var{reserved} not @code{NULL}.
@end deftypefun
-@node Key Signatures
-@subsection Key Signatures
-@cindex key, signatures
-@cindex signatures, on a key
-
-The following interfaces are deprecated and only provided for backward
-compatibility. Don't use them. They will be removed in a future
-version of @acronym{GPGME}.
-
-The signatures on a key are only available if the key was retrieved
-via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode
-enabled, because it is expensive to retrieve all signatures of a key.
-
-So, before using the below interfaces to retrieve the signatures on a
-key, you have to make sure that the key was listed with signatures
-enabled. One convenient, but blocking, way to do this is to use the
-function @code{gpgme_get_key}.
+@c
+@c gpgme_op_adduid
+@c
+@deftypefun gpgme_error_t gpgme_op_adduid @
+ (@w{gpgme_ctx_t @var{ctx}}, @
+ @w{gpgme_key_t @var{key}}, @
+ @w{const char *@var{userid}}, @
+ @w{unsigned int @var{flags}});
-@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_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.
-@table @code
-@item GPGME_ATTR_KEYID
-This is the key ID of the key which was used for the signature. It is
-representable as a string.
+@var{key} specifies the key to operate on.
-@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.
+@var{userid} is the user ID to add to the key. A user ID is commonly
+the mail address to be associated with the key. GPGME does not
+require a specificy syntax but if more than a mail address is given,
+RFC-822 style format is suggested. The value is expected to be in
+UTF-8 encoding (i.e. no IDN encoding for mail addresses). This is a
+required parameter.
-@item GPGME_ATTR_CREATED
-This is the timestamp at creation time of the signature. It is
-representable as a number.
+@var{flags} are currently not used and must be set to zero.
-@item GPGME_ATTR_EXPIRE
-This is the expiration time of the signature. It is representable as
-a number.
+The function returns zero on success, @code{GPG_ERR_NOT_SUPPORTED} if
+the engine does not support the command, or a bunch of other error
+codes.
-@item GPGME_ATTR_USERID
-This is the user ID associated with the signing key. The user ID is
-representable as a number.
+@end deftypefun
-@item GPGME_ATTR_NAME
-This is the name belonging to a user ID. It is representable as a string.
+@deftypefun gpgme_error_t gpgme_op_adduid_start @
+ (@w{gpgme_ctx_t @var{ctx}}, @
+ @w{gpgme_key_t @var{key}}, @
+ @w{const char *@var{userid}}, @
+ @w{unsigned int @var{flags}});
-@item GPGME_ATTR_EMAIL
-This is the email address belonging to a user ID. It is representable
-as a string.
+The function @code{gpgme_op_adduid_start} initiates a
+@code{gpgme_op_adduid} operation; see there for details. It must
+be completed by calling @code{gpgme_wait} on the context.
+@xref{Waiting For Completion}.
-@item GPGME_ATTR_COMMENT
-This is the comment belonging to a user ID. It is representable as a
-string.
+@end deftypefun
-@item GPGME_ATTR_KEY_REVOKED
-This specifies if a key signature is a revocation signature. It is
-representable as a number, and is @code{1} if the key is revoked, and
-@code{0} otherwise.
-@c @item GPGME_ATTR_KEY_EXPIRED
-@c This specifies if a key signature is expired. It is representable as
-@c a number, and is @code{1} if the key is revoked, and @code{0}
-@c otherwise.
@c
-@item GPGME_ATTR_SIG_CLASS
-This specifies the signature class of a key signature. It is
-representable as a number. The meaning is specific to the crypto
-engine.
-
-@item GPGME_ATTR_SIG_CLASS
-This specifies the signature class of a key signature. It is
-representable as a number. The meaning is specific to the crypto
-engine.
-
-@item GPGME_ATTR_SIG_STATUS
-This is the same value as returned by @code{gpgme_get_sig_status}.
-@end table
-@end deftp
-
-@deftypefun {const char *} gpgme_key_sig_get_string_attr (@w{gpgme_key_t @var{key}}, @w{int @var{uid_idx}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
-The function @code{gpgme_key_sig_get_string_attr} returns the value of
-the string-representable attribute @var{what} of the signature
-@var{idx} on the user ID @var{uid_idx} in the key @var{key}. The
-argument @var{reserved} is reserved for later use and should be
-@code{NULL}.
-
-The string returned is only valid as long as the key is valid.
+@c gpgme_op_revuid
+@c
+@deftypefun gpgme_error_t gpgme_op_revuid @
+ (@w{gpgme_ctx_t @var{ctx}}, @
+ @w{gpgme_key_t @var{key}}, @
+ @w{const char *@var{userid}}, @
+ @w{unsigned int @var{flags}});
-The function returns @code{0} if an attribute can't be returned as a
-string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx}
-out of range, or @var{reserved} not @code{NULL}.
-@end deftypefun
+The function @code{gpgme_op_revuid} revokes a user ID from the OpenPGP
+key given by @var{KEY}. Revoking user IDs after key creation is a
+feature of the OpenPGP protocol and thus the protocol for the context
+@var{ctx} must be set to OpenPGP. As of now this function requires at
+least version 2.1.13 of GnuPG.
-@deftypefun {unsigned long} gpgme_key_sig_get_ulong_attr (@w{gpgme_key_t @var{key}}, @w{int @var{uid_idx}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
-The function @code{gpgme_key_sig_get_ulong_attr} returns the value of
-the number-representable attribute @var{what} of the signature
-@var{idx} on the user ID @var{uid_idx} in the key @var{key}. The
-argument @var{reserved} is reserved for later use and should be
-@code{NULL}.
+@var{key} specifies the key to operate on.
-The function returns @code{0} if an attribute can't be returned as a
-string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx}
-out of range, or @var{reserved} not @code{NULL}.
-@end deftypefun
+@var{userid} is the user ID to be revoked from the key. The user ID
+must be given verbatim because the engine does an exact and case
+sensitive match. Thus the @code{uid} field from the user ID object
+(@code{gpgme_user_id_t}) is to be used. This is a required parameter.
+@var{flags} are currently not used and must be set to zero.
-@node Manipulating Keys
-@subsection Manipulating Keys
-@cindex key, manipulation
+Note that the engine won't allow to revoke the last valid user ID. To
+change a user ID is better to first add the new user ID, then revoke
+the old one, and finally publish the key.
-@deftypefun void gpgme_key_ref (@w{gpgme_key_t @var{key}})
-The function @code{gpgme_key_ref} acquires an additional reference for
-the key @var{key}.
-@end deftypefun
+The function returns zero on success, @code{GPG_ERR_NOT_SUPPORTED} if
+the engine does not support the command, or a bunch of other error
+codes.
-@deftypefun void gpgme_key_unref (@w{gpgme_key_t @var{key}})
-The function @code{gpgme_key_unref} releases a reference for the key
-@var{key}. If this was the last reference, the key will be destroyed
-and all resources associated to it will be released.
@end deftypefun
+@deftypefun gpgme_error_t gpgme_op_revuid_start @
+ (@w{gpgme_ctx_t @var{ctx}}, @
+ @w{gpgme_key_t @var{key}}, @
+ @w{const char *@var{userid}}, @
+ @w{unsigned int @var{flags}});
-The following interface is deprecated and only provided for backward
-compatibility. Don't use it. It will be removed in a future version
-of @acronym{GPGME}.
+The function @code{gpgme_op_revuid_start} initiates a
+@code{gpgme_op_revuid} operation; see there for details. It must
+be completed by calling @code{gpgme_wait} on the context.
+@xref{Waiting For Completion}.
-@deftypefun void gpgme_key_release (@w{gpgme_key_t @var{key}})
-The function @code{gpgme_key_release} is equivalent to
-@code{gpgme_key_unref}.
@end deftypefun
-@node Generating Keys
-@subsection Generating Keys
-@cindex key, creation
-@cindex key ring, add
+@c
+@c gpgme_op_genkey
+@c
+@deftypefun gpgme_error_t gpgme_op_genkey @
+ (@w{gpgme_ctx_t @var{ctx}}, @
+ @w{const char *@var{parms}}, @
+ @w{gpgme_data_t @var{public}}, @
+ @w{gpgme_data_t @var{secret}})
-@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.
-GnuPG does not support @var{public} and @var{secret}, they should be
+GPG does not support @var{public} and @var{secret}, they should be
@code{NULL}. GnuPG will generate a key pair and add it to the
standard key ring. The fingerprint of the generated key is available
with @code{gpgme_op_genkey_result}.
@end deftypefun
@deftypefun gpgme_error_t gpgme_op_genkey_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{parms}}, @w{gpgme_data_t @var{public}}, @w{gpgme_data_t @var{secret}})
+
The function @code{gpgme_op_genkey_start} initiates a
@code{gpgme_op_genkey} operation. It can be completed by calling
@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
@code{NULL}.
@end deftypefun
+
+@c
+@c gpgme_op_genkey_result
+@c
@deftp {Data type} {gpgme_genkey_result_t}
+
This is a pointer to a structure used to store the result of a
@code{gpgme_op_genkey} operation. After successfully generating a
key, you can retrieve the pointer to the result with
@table @code
@item unsigned int primary : 1
-This is a flag that is set to 1 if a primary key was created and to 0
+This flag is set to 1 if a primary key was created and to 0
if not.
@item unsigned int sub : 1
-This is a flag that is set to 1 if a subkey was created and to 0
-if not.
+This flag is set to 1 if a subkey was created and to 0 if not.
+
+@item unsigned int uid : 1
+This flag is set to 1 if a user ID was created and to 0 if not.
@item char *fpr
This is the fingerprint of the key that was created. If both a
-primary and a sub key were generated, the fingerprint of the primary
+primary and a subkey were generated, the fingerprint of the primary
key will be returned. If the crypto engine does not provide the
fingerprint, @code{fpr} will be a null pointer.
+
+@item gpgme_data_t pubkey
+This will eventually be used to return the public key. It is
+currently not used.
+
+@item gpgme_data_t seckey
+This will eventually be used to return the secret key. It is
+currently not used.
+
@end table
@end deftp
@deftypefun gpgme_genkey_result_t gpgme_op_genkey_result (@w{gpgme_ctx_t @var{ctx}})
+
The function @code{gpgme_op_genkey_result} returns a
@code{gpgme_genkey_result_t} pointer to a structure holding the result of
a @code{gpgme_op_genkey} operation. The pointer is only valid if the
@code{gpgme_op_genkey_start} operation, and if this operation finished
successfully. The returned pointer is only valid until the next
operation is started on the context.
+
+@end deftypefun
+
+
+@c
+@c SIGNING KEYS
+@c
+@node Signing Keys
+@subsection Signing Keys
+@cindex key, signing
+
+Key signatures are a unique concept of the OpenPGP protocol. They can
+be used to certify the validity of a key and are used to create the
+Web-of-Trust (WoT). Instead of using the @code{gpgme_op_interact}
+function along with a finite state machine, GPGME provides a
+convenient function to create key signatures when using modern GnuPG
+versions.
+
+
+@c
+@c gpgme_op_keysign
+@c
+@deftypefun gpgme_error_t gpgme_op_keysign @
+ (@w{gpgme_ctx_t @var{ctx}}, @
+ @w{gpgme_key_t @var{key}}, @
+ @w{const char *@var{userid}}, @
+ @w{unsigned long @var{expires}}, @
+ @w{unsigned int @var{flags}});
+
+The function @code{gpgme_op_keysign} adds a new key signature to the
+public key @var{KEY}. This function requires at least version 2.1.12 of
+GnuPG.
+
+@var{CTX} is the usual context which describes the protocol to use
+(which must be OpenPGP) and has also the list of signer keys to be
+used for the signature. The common case is to use the default key for
+signing other keys. If another key or more than one key shall be used
+for a key signature, @code{gpgme_signers_add} can be used.
+@xref{Selecting Signers}.
+
+@var{key} specifies the key to operate on.
+
+@var{userid} selects the user ID or user IDs to be signed. If
+@var{userid} is set to @code{NULL} all valid user IDs are signed. 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. To select more than
+one user ID put them all into one string separated by linefeeds
+characters (@code{\n}) and set the flag @code{GPGME_KEYSIGN_LFSEP}.
+
+@var{expires} can be set to the number of seconds since Epoch of the
+desired expiration date in UTC for the new signature. The common case
+is to use 0 to not set an expiration date. However, if the
+configuration of the engine defines a default expiration for key
+signatures, that is still used unless the flag
+@code{GPGME_KEYSIGN_NOEXPIRE} is used. Note that this parameter takes
+an unsigned long value and not a @code{time_t} to avoid problems on
+systems which use a signed 32 bit @code{time_t}. Note further that
+the OpenPGP protocol uses 32 bit values for timestamps and thus can
+only encode dates up to the year 2106.
+
+@var{flags} can be set to the bit-wise OR of the following flags:
+
+@table @code
+@item GPGME_KEYSIGN_LOCAL
+Instead of creating an exportable key signature, create a key
+signature which is is marked as non-exportable.
+
+@item GPGME_KEYSIGN_LFSEP
+Although linefeeds are uncommon in user IDs this flag is required to
+explicitly declare that @var{userid} may contain several linefeed
+separated user IDs.
+
+@item GPGME_KEYSIGN_NOEXPIRE
+Force the creation of a key signature without an expiration date. This
+overrides @var{expire} and any local configuration of the engine.
+
+@end table
+
+The function returns zero on success, @code{GPG_ERR_NOT_SUPPORTED} if
+the engine does not support the command, or a bunch of other error
+codes.
+
@end deftypefun
+@deftypefun gpgme_error_t gpgme_op_keysign_start @
+ (@w{gpgme_ctx_t @var{ctx}}, @
+ @w{gpgme_key_t @var{key}}, @
+ @w{const char *@var{userid}}, @
+ @w{unsigned long @var{expires}}, @
+ @w{unsigned int @var{flags}});
+
+The function @code{gpgme_op_keysign_start} initiates a
+@code{gpgme_op_keysign} operation; see there for details. It must
+be completed by calling @code{gpgme_wait} on the context.
+@xref{Waiting For Completion}.
+
+@end deftypefun
+
+
+@c
+@c EXPORTING KEYS
+@c
@node Exporting Keys
@subsection Exporting Keys
@cindex key, export
operation is started on the context.
@end deftypefun
-The following interface is deprecated and only provided for backward
-compatibility. Don't use it. It will be removed in a future version
-of @acronym{GPGME}.
-
-@deftypefun gpgme_error_t gpgme_op_import_ext (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}}, @w{int *@var{nr}})
-The function @code{gpgme_op_import_ext} is equivalent to:
-
-@example
- gpgme_error_t err = gpgme_op_import (ctx, keydata);
- if (!err)
- @{
- gpgme_import_result_t result = gpgme_op_import_result (ctx);
- *nr = result->considered;
- @}
-@end example
-@end deftypefun
-
-
@node Deleting Keys
@subsection Deleting Keys
@cindex key, delete
@node Changing Passphrases
-@subsection Changing Passphrases
+@subsection Changing Passphrases
@cindex passphrase, change
@deftypefun gpgme_error_t gpgme_op_passwd @
@end deftypefun
+@c
+@c CHANGING TOFU DATA
+@c
+@node Changing TOFU Data
+@subsection Changing TOFU Data
+@cindex validity, TOFU
+
+The OpenPGP engine features a Trust-On-First-Use (TOFU) key validation
+model. For resolving clonflics it is necessary to declare the policy
+for a key. See the GnuPG manual for details on the TOFU
+implementation.
+
+@deftp {Data type} {enum gpgme_tofu_policy_t}
+@tindex gpgme_tofu_policy_t
+The @code{gpgme_tofu_policy_t} type specifies the set of possible
+policy values that are supported by @acronym{GPGME}:
+
+@table @code
+@item GPGME_TOFU_POLICY_AUTO
+Set the policy to ``auto''.
+@item GPGME_TOFU_POLICY_GOOD
+Set the policy to ``goog''.
+@item GPGME_TOFU_POLICY_BAD
+Set the policy to ``bad''.
+@item GPGME_TOFU_POLICY_ASK
+Set the policy to ``ask''.
+@item GPGME_TOFU_POLICY_UNKNOWN
+Set the policy to ``unknown''.
+@end table
+
+@end deftp
+
+To change the policy for a key the following functions can be used:
+
+@deftypefun gpgme_error_t gpgme_op_tofu_policy @
+ (@w{gpgme_ctx_t @var{ctx}}, @
+ @w{const gpgme_key_t @var{key}}, @
+ @w{gpgme_tofu_policy_t @var{policy}})
+
+The function @code{gpgme_op_tofu_policy} changes the TOFU policy of
+@var{key}. The valid values for @var{policy} are listed above. As of
+now this function does only work for OpenPGP and requires at least
+version 2.1.10 of GnuPG.
+
+The function returns zero on success, @code{GPG_ERR_NOT_SUPPORTED} if
+the engine does not support the command, or a bunch of other error
+codes.
+
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_tofu_policy_start @
+ (@w{gpgme_ctx_t @var{ctx}}, @
+ @w{const gpgme_key_t @var{key}}, @
+ @w{gpgme_tofu_policy_t @var{policy}})
+
+The function @code{gpgme_op_tofu_policy_start} initiates a
+@code{gpgme_op_tofu_policy} operation. It can be completed by calling
+@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
+
+The function returns @code{0} if the operation was started successfully,
+and an error code if one of the arguments is not valid or the oepration
+could not be started.
+
+@end deftypefun
+
+
@node Advanced Key Editing
@subsection Advanced Key Editing
@cindex key, edit
-@deftp {Data type} {gpgme_error_t (*gpgme_edit_cb_t) (@w{void *@var{handle}}, @w{gpgme_status_code_t @var{status}}, @w{const char *@var{args}}, @w{int @var{fd}})}
-@tindex gpgme_edit_cb_t
-The @code{gpgme_edit_cb_t} type is the type of functions which
-@acronym{GPGME} calls if it a key edit operation is on-going. The
-status code @var{status} and the argument line @var{args} are passed
-through by @acronym{GPGME} from the crypto engine. The file
-descriptor @var{fd} is -1 for normal status messages. If @var{status}
-indicates a command rather than a status message, the response to the
-command should be written to @var{fd}. The @var{handle} is provided
-by the user at start of operation.
-
-The function should return @code{GPG_ERR_NO_ERROR} or an error value.
+@deftp {Data type} {gpgme_error_t (*gpgme_interact_cb_t) @
+ (@w{void *@var{handle}}, @
+ @w{const char *@var{status}}, @
+ @w{const char *@var{args}}, @
+ @w{int @var{fd}})}
+@tindex gpgme_interact_cb_t
+The @code{gpgme_interact_cb_t} type is the type of functions which
+@acronym{GPGME} calls if it a key interact operation is on-going. The
+status keyword @var{status} and the argument line @var{args} are
+passed through by @acronym{GPGME} from the crypto engine. An empty
+string represents EOF. The file descriptor @var{fd} is -1 for normal
+status messages. If @var{status} indicates a command rather than a
+status message, the response to the command should be written to
+@var{fd}. The @var{handle} is provided by the user at start of
+operation.
+
+The function should return @code{GPG_ERR_FALSE} if it did not handle
+the status code, @code{0} for success, or any other error value.
@end deftp
-@deftypefun gpgme_error_t gpgme_op_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
-The function @code{gpgme_op_edit} processes the key @var{KEY}
-interactively, using the edit callback function @var{FNC} with the
+@deftypefun gpgme_error_t gpgme_op_interact (@w{gpgme_ctx_t @var{ctx}}, @
+ @w{gpgme_key_t @var{key}}, @
+ @w{unsigned int @var{flags}}, @
+ @w{gpgme_interact_cb_t @var{fnc}}, @
+ @w{void *@var{handle}}, @
+ @w{gpgme_data_t @var{out}})
+The function @code{gpgme_op_interact} processes the key @var{KEY}
+interactively, using the interact 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}.
engine is specific to the crypto engine and no further support in
implementing this protocol correctly is provided by @acronym{GPGME}.
-The function returns the error code @code{GPG_ERR_NO_ERROR} if the
-edit operation completes successfully, @code{GPG_ERR_INV_VALUE} if
-@var{ctx} or @var{key} is not a valid pointer, and any error returned
-by the crypto engine or the edit callback handler.
+@var{flags} modifies the behaviour of the function; the only defined
+bit value is:
+
+@table @code
+@item GPGME_INTERACT_CARD
+This is used for smartcard based keys and uses gpg’s
+@code{--card-edit} command.
+
+@end table
+
+The function returns @code{0} if the edit operation completes
+successfully, @code{GPG_ERR_INV_VALUE} if @var{ctx} or @var{key} is
+not a valid pointer, and any error returned by the crypto engine or
+the edit callback handler.
@end deftypefun
-@deftypefun gpgme_error_t gpgme_op_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
-The function @code{gpgme_op_edit_start} initiates a
-@code{gpgme_op_edit} operation. It can be completed by calling
+
+@deftypefun gpgme_error_t gpgme_op_interact_start (@w{gpgme_ctx_t @var{ctx}}, @
+ @w{gpgme_key_t @var{key}}, @
+ @w{unsigned int @var{flags}}, @
+ @w{gpgme_interact_cb_t @var{fnc}}, @
+ @w{void *@var{handle}}, @
+ @w{gpgme_data_t @var{out}})
+The function @code{gpgme_op_interact_start} initiates a
+@code{gpgme_op_interact} operation. It can be completed by calling
@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
-The function returns the error code @code{GPG_ERR_NO_ERROR} if the
-operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
-@var{ctx} or @var{key} is not a valid pointer.
+The function returns @code{0} if the operation was started
+successfully, and @code{GPG_ERR_INV_VALUE} if @var{ctx} or @var{key}
+is not a valid pointer.
@end deftypefun
-@deftypefun gpgme_error_t gpgme_op_card_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
-The function @code{gpgme_op_card_edit} is analogous to
-@code{gpgme_op_edit}, but should be used to process the smart card corresponding to the key @var{key}.
-@end deftypefun
-
-@deftypefun gpgme_error_t gpgme_op_card_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
-The function @code{gpgme_op_card_edit_start} initiates a
-@code{gpgme_op_card_edit} operation. It can be completed by calling
-@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
-
-The function returns the error code @code{GPG_ERR_NO_ERROR} if the
-operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
-@var{ctx} or @var{key} is not a valid pointer.
-@end deftypefun
-
@node Trust Item Management
@section Trust Item Management
@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
@end deftypefun
-@node Information About Trust Items
-@subsection Information About Trust Items
-@cindex trust item, information about
-@cindex trust item, attributes
-@cindex attributes, of a trust item
-
-The following interfaces are deprecated and only provided for backward
-compatibility. Don't use them. They will be removed in a future
-version of @acronym{GPGME}.
-
-Trust items have attributes which can be queried using the interfaces
-below. The attribute identifiers are shared with those for key
-attributes. @xref{Information About Keys}.
-
-@deftypefun {const char *} gpgme_trust_item_get_string_attr (@w{gpgme_trust_item_t @var{item}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
-The function @code{gpgme_trust_item_get_string_attr} returns the value
-of the string-representable attribute @var{what} of trust item
-@var{item}. The arguments @var{idx} and @var{reserved} are reserved
-for later use and should be @code{0} and @code{NULL} respectively.
-
-The string returned is only valid as long as the key is valid.
-
-The function returns @code{0} if an attribute can't be returned as a
-string, @var{key} is not a valid pointer, @var{idx} out of range,
-or @var{reserved} not @code{NULL}.
-@end deftypefun
-
-@deftypefun int gpgme_trust_item_get_int_attr (@w{gpgme_trust_item_t @var{item}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
-The function @code{gpgme_trust_item_get_int_attr} returns the value of
-the number-representable attribute @var{what} of trust item
-@var{item}. If the attribute occurs more than once in the trust item,
-the index is specified by @var{idx}. However, currently no such
-attribute exists, so @var{idx} should be @code{0}. The argument
-@var{reserved} is reserved for later use and should be @code{NULL}.
-
-The function returns @code{0} if the attribute can't be returned as a
-number, @var{key} is not a valid pointer, @var{idx} out of range,
-or @var{reserved} not @code{NULL}.
-@end deftypefun
-
-
@node Manipulating Trust Items
@subsection Manipulating Trust Items
@cindex trust item, manipulation
@end deftypefun
-The following interface is deprecated and only provided for backward
-compatibility. Don't use it. It will be removed in a future version
-of @acronym{GPGME}.
-
-@deftypefun void gpgme_trust_item_release (@w{gpgme_trust_item_t @var{item}})
-The function @code{gpgme_trust_item_release} is an alias for
-@code{gpgme_trust_item_unref}.
-@end deftypefun
-
-
@node Crypto Operations
@section Crypto Operations
@cindex cryptographic operation
@item char *pka_address
The mailbox from the PKA information or @code{NULL}.
+
+@item gpgme_key_t key
+An object describing the key used to create the signature. This key
+object may be incomplete in that it only conveys information
+availabale directly with a signature. It may also be @code{NULL} if
+such information is not readily available.
+
@end table
@end deftp
@end deftypefun
-The following interfaces are deprecated and only provided for backward
-compatibility. Don't use them. They will be removed in a future
-version of @acronym{GPGME}.
-
-@deftp {Data type} {enum gpgme_sig_stat_t}
-@tindex gpgme_sig_stat_t
-The @code{gpgme_sig_stat_t} type holds the result of a signature check, or
-the combined result of all signatures. The following results are
-possible:
+@node Decrypt and Verify
+@subsection Decrypt and Verify
+@cindex decryption and verification
+@cindex verification and decryption
+@cindex signature check
+@cindex cryptographic operation, decryption and verification
-@table @code
-@item GPGME_SIG_STAT_NONE
-This status should not occur in normal operation.
+@deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
+The function @code{gpgme_op_decrypt_verify} decrypts the ciphertext in
+the data object @var{cipher} and stores it into the data object
+@var{plain}. If @var{cipher} contains signatures, they will be
+verified.
-@item GPGME_SIG_STAT_GOOD
-This status indicates that the signature is valid. For the combined
-result this status means that all signatures are valid.
+After the operation completed, @code{gpgme_op_decrypt_result} and
+@code{gpgme_op_verify_result} can be used to retrieve more information
+about the signatures.
-@item GPGME_SIG_STAT_GOOD_EXP
-This status indicates that the signature is valid but expired. For
-the combined result this status means that all signatures are valid
-and expired.
+If the error code @code{GPG_ERR_NO_DATA} is returned, @var{cipher}
+does not contain any data to decrypt. However, it might still be
+signed. The information about detected signatures is available with
+@code{gpgme_op_verify_result} in this case.
-@item GPGME_SIG_STAT_GOOD_EXPKEY
-This status indicates that the signature is valid but the key used to
-verify the signature has expired. For the combined result this status
-means that all signatures are valid and all keys are expired.
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+ciphertext could be decrypted successfully, @code{GPG_ERR_INV_VALUE}
+if @var{ctx}, @var{cipher} or @var{plain} is not a valid pointer,
+@code{GPG_ERR_NO_DATA} if @var{cipher} does not contain any data to
+decrypt, @code{GPG_ERR_DECRYPT_FAILED} if @var{cipher} is not a valid
+cipher text, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the
+secret key could not be retrieved, and passes through any errors that
+are reported by the crypto engine support routines.
+@end deftypefun
-@item GPGME_SIG_STAT_BAD
-This status indicates that the signature is invalid. For the combined
-result this status means that all signatures are invalid.
+@deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
+The function @code{gpgme_op_decrypt_verify_start} initiates a
+@code{gpgme_op_decrypt_verify} operation. It can be completed by
+calling @code{gpgme_wait} on the context. @xref{Waiting For
+Completion}.
-@item GPGME_SIG_STAT_NOKEY
-This status indicates that the signature could not be verified due to
-a missing key. For the combined result this status means that all
-signatures could not be checked due to missing keys.
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
+@var{ctx}, @var{cipher}, @var{plain} or @var{r_stat} is not a valid
+pointer, and @code{GPG_ERR_NO_DATA} if @var{cipher} does not contain
+any data to decrypt.
+@end deftypefun
-@item GPGME_SIG_STAT_NOSIG
-This status indicates that the signature data provided was not a real
-signature.
-@item GPGME_SIG_STAT_ERROR
-This status indicates that there was some other error which prevented
-the signature verification.
+@node Sign
+@subsection Sign
+@cindex signature, creation
+@cindex sign
+@cindex cryptographic operation, signing
-@item GPGME_SIG_STAT_DIFF
-For the combined result this status means that at least two signatures
-have a different status. You can get each key's status with
-@code{gpgme_get_sig_status}.
-@end table
-@end deftp
+A signature can contain signatures by one or more keys. The set of
+keys used to create a signatures is contained in a context, and is
+applied to all following signing operations in this context (until the
+set is changed).
-@deftypefun {const char *} gpgme_get_sig_status (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_sig_stat_t *@var{r_stat}}, @w{time_t *@var{r_created}})
-The function @code{gpgme_get_sig_status} is equivalent to:
+@menu
+* Selecting Signers:: How to choose the keys to sign with.
+* Creating a Signature:: How to create a signature.
+* Signature Notation Data:: How to add notation data to a signature.
+@end menu
-@example
- gpgme_verify_result_t result;
- gpgme_signature_t sig;
- result = gpgme_op_verify_result (ctx);
- sig = result->signatures;
+@node Selecting Signers
+@subsubsection Selecting Signers
+@cindex signature, selecting signers
+@cindex signers, selecting
- while (sig && idx)
- @{
- sig = sig->next;
- idx--;
- @}
- if (!sig || idx)
- return NULL;
+The key or the keys used to create a signature are stored in the
+context. The following functions can be used to manipulate this list.
+If no signer has been set into the context a default key is used for
+signing.
- if (r_stat)
- @{
- switch (gpg_err_code (sig->status))
- @{
- case GPG_ERR_NO_ERROR:
- *r_stat = GPGME_SIG_STAT_GOOD;
- break;
+@deftypefun void gpgme_signers_clear (@w{gpgme_ctx_t @var{ctx}})
+The function @code{gpgme_signers_clear} releases a reference for each
+key on the signers list and removes the list of signers from the
+context @var{ctx}.
- case GPG_ERR_BAD_SIGNATURE:
- *r_stat = GPGME_SIG_STAT_BAD;
- break;
+Every context starts with an empty list.
+@end deftypefun
- case GPG_ERR_NO_PUBKEY:
- *r_stat = GPGME_SIG_STAT_NOKEY;
- break;
+@deftypefun gpgme_error_t gpgme_signers_add (@w{gpgme_ctx_t @var{ctx}}, @w{const gpgme_key_t @var{key}})
+The function @code{gpgme_signers_add} adds the key @var{key} to the
+list of signers in the context @var{ctx}.
- case GPG_ERR_NO_DATA:
- *r_stat = GPGME_SIG_STAT_NOSIG;
- break;
+Calling this function acquires an additional reference for the key.
+@end deftypefun
- case GPG_ERR_SIG_EXPIRED:
- *r_stat = GPGME_SIG_STAT_GOOD_EXP;
- break;
+@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
+the context @var{ctx}.
+@end deftypefun
- case GPG_ERR_KEY_EXPIRED:
- *r_stat = GPGME_SIG_STAT_GOOD_EXPKEY;
- break;
+@deftypefun gpgme_key_t gpgme_signers_enum (@w{const gpgme_ctx_t @var{ctx}}, @w{int @var{seq}})
+The function @code{gpgme_signers_enum} returns the @var{seq}th key in
+the list of signers in the context @var{ctx}. An additional reference
+is acquired for the user.
- default:
- *r_stat = GPGME_SIG_STAT_ERROR;
- break;
- @}
- @}
- if (r_created)
- *r_created = sig->timestamp;
- return sig->fpr;
-@end example
+If @var{seq} is out of range, @code{NULL} is returned.
@end deftypefun
-@deftypefun {const char *} gpgme_get_sig_string_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{what}}, @w{int @var{whatidx}})
-The function @code{gpgme_get_sig_string_attr} is equivalent to:
-@example
- gpgme_verify_result_t result;
- gpgme_signature_t sig;
+@node Creating a Signature
+@subsubsection Creating a Signature
- result = gpgme_op_verify_result (ctx);
- sig = result->signatures;
+@deftp {Data type} {enum gpgme_sig_mode_t}
+@tindex gpgme_sig_mode_t
+The @code{gpgme_sig_mode_t} type is used to specify the desired type of a
+signature. The following modes are available:
- while (sig && idx)
- @{
- sig = sig->next;
- idx--;
- @}
- if (!sig || idx)
- return NULL;
+@table @code
+@item GPGME_SIG_MODE_NORMAL
+A normal signature is made, the output includes the plaintext and the
+signature.
- switch (what)
- @{
- case GPGME_ATTR_FPR:
- return sig->fpr;
+@item GPGME_SIG_MODE_DETACH
+A detached signature is made.
- case GPGME_ATTR_ERRTOK:
- if (whatidx == 1)
- return sig->wrong_key_usage ? "Wrong_Key_Usage" : "";
- else
- return "";
- default:
- break;
- @}
-
- return NULL;
-@end example
-@end deftypefun
-
-@deftypefun {const char *} gpgme_get_sig_ulong_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{waht}}, @w{int @var{whatidx}})
-The function @code{gpgme_get_sig_ulong_attr} is equivalent to:
-
-@example
- gpgme_verify_result_t result;
- gpgme_signature_t sig;
-
- result = gpgme_op_verify_result (ctx);
- sig = result->signatures;
-
- while (sig && idx)
- @{
- sig = sig->next;
- idx--;
- @}
- if (!sig || idx)
- return 0;
-
- switch (what)
- @{
- case GPGME_ATTR_CREATED:
- return sig->timestamp;
-
- case GPGME_ATTR_EXPIRE:
- return sig->exp_timestamp;
-
- case GPGME_ATTR_VALIDITY:
- return (unsigned long) sig->validity;
-
- case GPGME_ATTR_SIG_STATUS:
- switch (sig->status)
- @{
- case GPG_ERR_NO_ERROR:
- return GPGME_SIG_STAT_GOOD;
-
- case GPG_ERR_BAD_SIGNATURE:
- return GPGME_SIG_STAT_BAD;
-
- case GPG_ERR_NO_PUBKEY:
- return GPGME_SIG_STAT_NOKEY;
-
- case GPG_ERR_NO_DATA:
- return GPGME_SIG_STAT_NOSIG;
-
- case GPG_ERR_SIG_EXPIRED:
- return GPGME_SIG_STAT_GOOD_EXP;
-
- case GPG_ERR_KEY_EXPIRED:
- return GPGME_SIG_STAT_GOOD_EXPKEY;
-
- default:
- return GPGME_SIG_STAT_ERROR;
- @}
-
- case GPGME_ATTR_SIG_SUMMARY:
- return sig->summary;
-
- default:
- break;
- @}
- return 0;
-@end example
-@end deftypefun
-
-@deftypefun {const char *} gpgme_get_sig_key (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_key_t *@var{r_key}})
-The function @code{gpgme_get_sig_key} is equivalent to:
-
-@example
- gpgme_verify_result_t result;
- gpgme_signature_t sig;
-
- result = gpgme_op_verify_result (ctx);
- sig = result->signatures;
-
- while (sig && idx)
- @{
- sig = sig->next;
- idx--;
- @}
- if (!sig || idx)
- return gpg_error (GPG_ERR_EOF);
-
- return gpgme_get_key (ctx, sig->fpr, r_key, 0);
-@end example
-@end deftypefun
-
-
-@node Decrypt and Verify
-@subsection Decrypt and Verify
-@cindex decryption and verification
-@cindex verification and decryption
-@cindex signature check
-@cindex cryptographic operation, decryption and verification
-
-@deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
-The function @code{gpgme_op_decrypt_verify} decrypts the ciphertext in
-the data object @var{cipher} and stores it into the data object
-@var{plain}. If @var{cipher} contains signatures, they will be
-verified.
-
-After the operation completed, @code{gpgme_op_decrypt_result} and
-@code{gpgme_op_verify_result} can be used to retrieve more information
-about the signatures.
-
-If the error code @code{GPG_ERR_NO_DATA} is returned, @var{cipher}
-does not contain any data to decrypt. However, it might still be
-signed. The information about detected signatures is available with
-@code{gpgme_op_verify_result} in this case.
-
-The function returns the error code @code{GPG_ERR_NO_ERROR} if the
-ciphertext could be decrypted successfully, @code{GPG_ERR_INV_VALUE}
-if @var{ctx}, @var{cipher} or @var{plain} is not a valid pointer,
-@code{GPG_ERR_NO_DATA} if @var{cipher} does not contain any data to
-decrypt, @code{GPG_ERR_DECRYPT_FAILED} if @var{cipher} is not a valid
-cipher text, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the
-secret key could not be retrieved, and passes through any errors that
-are reported by the crypto engine support routines.
-@end deftypefun
-
-@deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
-The function @code{gpgme_op_decrypt_verify_start} initiates a
-@code{gpgme_op_decrypt_verify} operation. It can be completed by
-calling @code{gpgme_wait} on the context. @xref{Waiting For
-Completion}.
-
-The function returns the error code @code{GPG_ERR_NO_ERROR} if the
-operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
-@var{ctx}, @var{cipher}, @var{plain} or @var{r_stat} is not a valid
-pointer, and @code{GPG_ERR_NO_DATA} if @var{cipher} does not contain
-any data to decrypt.
-@end deftypefun
-
-
-@node Sign
-@subsection Sign
-@cindex signature, creation
-@cindex sign
-@cindex cryptographic operation, signing
-
-A signature can contain signatures by one or more keys. The set of
-keys used to create a signatures is contained in a context, and is
-applied to all following signing operations in this context (until the
-set is changed).
-
-@menu
-* Selecting Signers:: How to choose the keys to sign with.
-* Creating a Signature:: How to create a signature.
-* Signature Notation Data:: How to add notation data to a signature.
-@end menu
-
-
-@node Selecting Signers
-@subsubsection Selecting Signers
-@cindex signature, selecting signers
-@cindex signers, selecting
-
-@deftypefun void gpgme_signers_clear (@w{gpgme_ctx_t @var{ctx}})
-The function @code{gpgme_signers_clear} releases a reference for each
-key on the signers list and removes the list of signers from the
-context @var{ctx}.
-
-Every context starts with an empty list.
-@end deftypefun
-
-@deftypefun gpgme_error_t gpgme_signers_add (@w{gpgme_ctx_t @var{ctx}}, @w{const gpgme_key_t @var{key}})
-The function @code{gpgme_signers_add} adds the key @var{key} to the
-list of signers in the context @var{ctx}.
-
-Calling this function acquires an additional reference for the key.
-@end deftypefun
-
-@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
-the context @var{ctx}.
-@end deftypefun
-
-@deftypefun gpgme_key_t gpgme_signers_enum (@w{const gpgme_ctx_t @var{ctx}}, @w{int @var{seq}})
-The function @code{gpgme_signers_enum} returns the @var{seq}th key in
-the list of signers in the context @var{ctx}. An additional reference
-is acquired for the user.
-
-If @var{seq} is out of range, @code{NULL} is returned.
-@end deftypefun
-
-
-@node Creating a Signature
-@subsubsection Creating a Signature
-
-@deftp {Data type} {enum gpgme_sig_mode_t}
-@tindex gpgme_sig_mode_t
-The @code{gpgme_sig_mode_t} type is used to specify the desired type of a
-signature. The following modes are available:
-
-@table @code
-@item GPGME_SIG_MODE_NORMAL
-A normal signature is made, the output includes the plaintext and the
-signature.
-
-@item GPGME_SIG_MODE_DETACH
-A detached signature is made.
-
-@item GPGME_SIG_MODE_CLEAR
-A clear text signature is made. The @acronym{ASCII} armor and text
-mode settings of the context are ignored.
-@end table
-@end deftp
+@item GPGME_SIG_MODE_CLEAR
+A clear text signature is made. The @acronym{ASCII} armor and text
+mode settings of the context are ignored.
+@end table
+@end deftp
@deftypefun gpgme_error_t gpgme_op_sign (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{sig}}, @w{gpgme_sig_mode_t @var{mode}})
The function @code{gpgme_op_sign} creates a signature for the text in
you run your tests only with play data.
+@node Deprecated Functions
+@appendix Deprecated Functions
+@cindex deprecated
+
+For backward compatibility @acronym{GPGME} has a number of functions,
+data types and constants which are deprecated and should not be used
+anymore. We document here those which are really old to help
+understanding old code and to allow migration to their modern
+counterparts.
+
+@strong{Warning:} These interfaces will be removed in a future version
+of @acronym{GPGME}.
+
+@deftypefun void gpgme_key_release (@w{gpgme_key_t @var{key}})
+The function @code{gpgme_key_release} is equivalent to
+@code{gpgme_key_unref}.
+@end deftypefun
+
+@deftypefun void gpgme_trust_item_release (@w{gpgme_trust_item_t @var{item}})
+The function @code{gpgme_trust_item_release} is an alias for
+@code{gpgme_trust_item_unref}.
+@end deftypefun
+
+
+@deftypefun gpgme_error_t gpgme_op_import_ext (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}}, @w{int *@var{nr}})
+The function @code{gpgme_op_import_ext} is equivalent to:
+
+@example
+ gpgme_error_t err = gpgme_op_import (ctx, keydata);
+ if (!err)
+ @{
+ gpgme_import_result_t result = gpgme_op_import_result (ctx);
+ *nr = result->considered;
+ @}
+@end example
+@end deftypefun
+
+
+@deftp {Data type} {gpgme_error_t (*gpgme_edit_cb_t) @
+ (@w{void *@var{handle}}, @
+ @w{gpgme_status_code_t @var{status}}, @
+ @w{const char *@var{args}}, @
+ @w{int @var{fd}})}
+@tindex gpgme_edit_cb_t
+The @code{gpgme_edit_cb_t} type is the type of functions which
+@acronym{GPGME} calls if it a key edit operation is on-going. The
+status code @var{status} and the argument line @var{args} are passed
+through by @acronym{GPGME} from the crypto engine. The file
+descriptor @var{fd} is -1 for normal status messages. If @var{status}
+indicates a command rather than a status message, the response to the
+command should be written to @var{fd}. The @var{handle} is provided
+by the user at start of operation.
+
+The function should return @code{GPG_ERR_FALSE} if it did not handle
+the status code, @code{0} for success, or any other error value.
+@end deftp
+
+@deftypefun gpgme_error_t gpgme_op_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
+Note: This function is deprecated, please use
+@code{gpgme_op_interact} instead.
+
+The function @code{gpgme_op_edit} processes the key @var{KEY}
+interactively, using the edit callback function @var{FNC} with the
+handle @var{HANDLE}. The callback is invoked for every status and
+command request from the crypto engine. The output of the crypto
+engine is written to the data object @var{out}.
+
+Note that the protocol between the callback function and the crypto
+engine is specific to the crypto engine and no further support in
+implementing this protocol correctly is provided by @acronym{GPGME}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+edit operation completes successfully, @code{GPG_ERR_INV_VALUE} if
+@var{ctx} or @var{key} is not a valid pointer, and any error returned
+by the crypto engine or the edit callback handler.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
+Note: This function is deprecated, please use
+@code{gpgme_op_interact_start} instead.
+
+The function @code{gpgme_op_edit_start} initiates a
+@code{gpgme_op_edit} operation. It can be completed by calling
+@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
+@var{ctx} or @var{key} is not a valid pointer.
+@end deftypefun
+
+
+@deftypefun gpgme_error_t gpgme_op_card_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
+Note: This function is deprecated, please use @code{gpgme_op_interact}
+with the flag @code{GPGME_INTERACT_CARD} instead.
+
+The function @code{gpgme_op_card_edit} is analogous to
+@code{gpgme_op_edit}, but should be used to process the smart card corresponding to the key @var{key}.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_card_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
+Note: This function is deprecated, please use @code{gpgme_op_interact_start}
+with the flag @code{GPGME_INTERACT_CARD} instead.
+
+The function @code{gpgme_op_card_edit_start} initiates a
+@code{gpgme_op_card_edit} operation. It can be completed by calling
+@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
+@var{ctx} or @var{key} is not a valid pointer.
+@end deftypefun
+
+
+
+@deftypefun gpgme_error_t gpgme_data_new_with_read_cb (@w{gpgme_data_t *@var{dh}}, @w{int (*@var{readfunc})} (@w{void *@var{hook}}, @w{char *@var{buffer}}, @w{size_t @var{count}}, @w{size_t *@var{nread}}), @w{void *@var{hook_value}})
+The function @code{gpgme_data_new_with_read_cb} creates a new
+@code{gpgme_data_t} object and uses the callback function @var{readfunc}
+to retrieve the data on demand. As the callback function can supply
+the data in any way it wants, this is the most flexible data type
+@acronym{GPGME} provides. However, it can not be used to write data.
+
+The callback function receives @var{hook_value} as its first argument
+whenever it is invoked. It should return up to @var{count} bytes in
+@var{buffer}, and return the number of bytes actually read in
+@var{nread}. It may return @code{0} in @var{nread} if no data is
+currently available. To indicate @code{EOF} the function should
+return with an error code of @code{-1} and set @var{nread} to
+@code{0}. The callback function may support to reset its internal
+read pointer if it is invoked with @var{buffer} and @var{nread} being
+@code{NULL} and @var{count} being @code{0}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+data object was successfully created, @code{GPG_ERR_INV_VALUE} if
+@var{dh} or @var{readfunc} is not a valid pointer, and
+@code{GPG_ERR_ENOMEM} if not enough memory is available.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_data_rewind (@w{gpgme_data_t @var{dh}})
+The function @code{gpgme_data_rewind} is equivalent to:
+
+@example
+ return (gpgme_data_seek (dh, 0, SEEK_SET) == -1)
+ ? gpgme_error_from_errno (errno) : 0;
+@end example
+@end deftypefun
+
+
+@deftp {Data type} gpgme_attr_t
+The @code{gpgme_attr_t} type is used to specify a key or trust item
+attribute. The following attributes are defined:
+
+@table @code
+@item GPGME_ATTR_KEYID
+This is the key ID of a sub key. It is representable as a string.
+
+For trust items, the trust item refers to the key with this ID.
+
+@item GPGME_ATTR_FPR
+This is the fingerprint of a sub key. It is representable as a
+string.
+
+@item GPGME_ATTR_ALGO
+This is the crypto algorithm for which the sub key can be used. It
+is representable as a string and as a number. The numbers correspond
+to the @code{enum gcry_pk_algos} values in the gcrypt library.
+
+@item GPGME_ATTR_LEN
+This is the key length of a sub key. It is representable as a
+number.
+
+@item GPGME_ATTR_CREATED
+This is the timestamp at creation time of a sub key. It is
+representable as a number.
+
+@item GPGME_ATTR_EXPIRE
+This is the expiration time of a sub key. It is representable as a
+number.
+
+@item GPGME_ATTR_OTRUST
+XXX FIXME (also for trust items)
+
+@item GPGME_ATTR_USERID
+This is a user ID. There can be more than one user IDs in a
+@var{gpgme_key_t} object. The first one (with index 0) is the primary
+user ID. The user ID is representable as a number.
+
+For trust items, this is the user ID associated with this trust item.
+
+@item GPGME_ATTR_NAME
+This is the name belonging to a user ID. It is representable as a string.
+
+@item GPGME_ATTR_EMAIL
+This is the email address belonging to a user ID. It is representable
+as a string.
+
+@item GPGME_ATTR_COMMENT
+This is the comment belonging to a user ID. It is representable as a
+string.
+
+@item GPGME_ATTR_VALIDITY
+This is the validity belonging to a user ID. It is representable as a
+string and as a number. See below for a list of available validities.
+
+For trust items, this is the validity that is associated with this
+trust item.
+
+@item GPGME_ATTR_UID_REVOKED
+This specifies if a user ID is revoked. It is representable as a
+number, and is @code{1} if the user ID is revoked, and @code{0}
+otherwise.
+
+@item GPGME_ATTR_UID_INVALID
+This specifies if a user ID is invalid. It is representable as a
+number, and is @code{1} if the user ID is invalid, and @code{0}
+otherwise.
+
+@item GPGME_ATTR_LEVEL
+This is the trust level of a trust item.
+
+@item GPGME_ATTR_TYPE
+This returns information about the type of key. For the string function
+this will eother be "PGP" or "X.509". The integer function returns 0
+for PGP and 1 for X.509. It is also used for the type of a trust item.
+
+@item GPGME_ATTR_IS_SECRET
+This specifies if the key is a secret key. It is representable as a
+number, and is @code{1} if the key is revoked, and @code{0} otherwise.
+
+@item GPGME_ATTR_KEY_REVOKED
+This specifies if a sub key is revoked. It is representable as a
+number, and is @code{1} if the key is revoked, and @code{0} otherwise.
+
+@item GPGME_ATTR_KEY_INVALID
+This specifies if a sub key is invalid. It is representable as a
+number, and is @code{1} if the key is invalid, and @code{0} otherwise.
+
+@item GPGME_ATTR_KEY_EXPIRED
+This specifies if a sub key is expired. It is representable as a
+number, and is @code{1} if the key is expired, and @code{0} otherwise.
+
+@item GPGME_ATTR_KEY_DISABLED
+This specifies if a sub key is disabled. It is representable as a
+number, and is @code{1} if the key is disabled, and @code{0} otherwise.
+
+@item GPGME_ATTR_KEY_CAPS
+This is a description of the capabilities of a sub key. It is
+representable as a string. The string contains the letter ``e'' if
+the key can be used for encryption, ``s'' if the key can be used for
+signatures, and ``c'' if the key can be used for certifications.
+
+@item GPGME_ATTR_CAN_ENCRYPT
+This specifies if a sub key can be used for encryption. It is
+representable as a number, and is @code{1} if the sub key can be used
+for encryption, and @code{0} otherwise.
+
+@item GPGME_ATTR_CAN_SIGN
+This specifies if a sub key can be used to create data signatures. It
+is representable as a number, and is @code{1} if the sub key can be
+used for signatures, and @code{0} otherwise.
+
+@item GPGME_ATTR_CAN_CERTIFY
+This specifies if a sub key can be used to create key certificates.
+It is representable as a number, and is @code{1} if the sub key can be
+used for certifications, and @code{0} otherwise.
+
+@item GPGME_ATTR_SERIAL
+The X.509 issuer serial attribute of the key. It is representable as
+a string.
+
+@item GPGME_ATTR_ISSUE
+The X.509 issuer name attribute of the key. It is representable as a
+string.
+
+@item GPGME_ATTR_CHAINID
+The X.509 chain ID can be used to build the certification chain. It
+is representable as a string.
+@end table
+@end deftp
+
+@deftypefun {const char *} gpgme_key_get_string_attr (@w{gpgme_key_t @var{key}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
+The function @code{gpgme_key_get_string_attr} returns the value of the
+string-representable attribute @var{what} of key @var{key}. If the
+attribute is an attribute of a sub key or an user ID, @var{idx}
+specifies the sub key or user ID of which the attribute value is
+returned. The argument @var{reserved} is reserved for later use and
+should be @code{NULL}.
+
+The string returned is only valid as long as the key is valid.
+
+The function returns @code{0} if an attribute can't be returned as a
+string, @var{key} is not a valid pointer, @var{idx} out of range,
+or @var{reserved} not @code{NULL}.
+@end deftypefun
+
+@deftypefun {unsigned long} gpgme_key_get_ulong_attr (@w{gpgme_key_t @var{key}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
+The function @code{gpgme_key_get_ulong_attr} returns the value of the
+number-representable attribute @var{what} of key @var{key}. If the
+attribute is an attribute of a sub key or an user ID, @var{idx}
+specifies the sub key or user ID of which the attribute value is
+returned. The argument @var{reserved} is reserved for later use and
+should be @code{NULL}.
+
+The function returns @code{0} if the attribute can't be returned as a
+number, @var{key} is not a valid pointer, @var{idx} out of range, or
+@var{reserved} not @code{NULL}.
+@end deftypefun
+
+
+@c
+@c Key Signatures
+@c
+The signatures on a key are only available if the key was retrieved
+via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode
+enabled, because it is expensive to retrieve all signatures of a key.
+
+So, before using the below interfaces to retrieve the signatures on a
+key, you have to make sure that the key was listed with signatures
+enabled. One convenient, but blocking, way to do this is to use the
+function @code{gpgme_get_key}.
+
+@deftp {Data type} gpgme_attr_t
+The @code{gpgme_attr_t} type is used to specify a key signature
+attribute. The following attributes are defined:
+
+@table @code
+@item GPGME_ATTR_KEYID
+This is the key ID of the key which was used for the signature. It is
+representable as a string.
+
+@item GPGME_ATTR_ALGO
+This is the crypto algorithm used to create the signature. It is
+representable as a string and as a number. The numbers correspond to
+the @code{enum gcry_pk_algos} values in the gcrypt library.
+
+@item GPGME_ATTR_CREATED
+This is the timestamp at creation time of the signature. It is
+representable as a number.
+
+@item GPGME_ATTR_EXPIRE
+This is the expiration time of the signature. It is representable as
+a number.
+
+@item GPGME_ATTR_USERID
+This is the user ID associated with the signing key. The user ID is
+representable as a number.
+
+@item GPGME_ATTR_NAME
+This is the name belonging to a user ID. It is representable as a string.
+
+@item GPGME_ATTR_EMAIL
+This is the email address belonging to a user ID. It is representable
+as a string.
+
+@item GPGME_ATTR_COMMENT
+This is the comment belonging to a user ID. It is representable as a
+string.
+
+@item GPGME_ATTR_KEY_REVOKED
+This specifies if a key signature is a revocation signature. It is
+representable as a number, and is @code{1} if the key is revoked, and
+@code{0} otherwise.
+
+@c @item GPGME_ATTR_KEY_EXPIRED
+@c This specifies if a key signature is expired. It is representable as
+@c a number, and is @code{1} if the key is revoked, and @code{0}
+@c otherwise.
+@c
+@item GPGME_ATTR_SIG_CLASS
+This specifies the signature class of a key signature. It is
+representable as a number. The meaning is specific to the crypto
+engine.
+
+@item GPGME_ATTR_SIG_CLASS
+This specifies the signature class of a key signature. It is
+representable as a number. The meaning is specific to the crypto
+engine.
+
+@item GPGME_ATTR_SIG_STATUS
+This is the same value as returned by @code{gpgme_get_sig_status}.
+@end table
+@end deftp
+
+@deftypefun {const char *} gpgme_key_sig_get_string_attr (@w{gpgme_key_t @var{key}}, @w{int @var{uid_idx}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
+The function @code{gpgme_key_sig_get_string_attr} returns the value of
+the string-representable attribute @var{what} of the signature
+@var{idx} on the user ID @var{uid_idx} in the key @var{key}. The
+argument @var{reserved} is reserved for later use and should be
+@code{NULL}.
+
+The string returned is only valid as long as the key is valid.
+
+The function returns @code{0} if an attribute can't be returned as a
+string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx}
+out of range, or @var{reserved} not @code{NULL}.
+@end deftypefun
+
+@deftypefun {unsigned long} gpgme_key_sig_get_ulong_attr (@w{gpgme_key_t @var{key}}, @w{int @var{uid_idx}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
+The function @code{gpgme_key_sig_get_ulong_attr} returns the value of
+the number-representable attribute @var{what} of the signature
+@var{idx} on the user ID @var{uid_idx} in the key @var{key}. The
+argument @var{reserved} is reserved for later use and should be
+@code{NULL}.
+
+The function returns @code{0} if an attribute can't be returned as a
+string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx}
+out of range, or @var{reserved} not @code{NULL}.
+@end deftypefun
+
+
+@c node Information About Trust Items
+@c subsection Information About Trust Items
+@c cindex trust item, information about
+@c cindex trust item, attributes
+@c cindex attributes, of a trust item
+
+Trust items have attributes which can be queried using the interfaces
+below. The attribute identifiers are shared with those for key
+attributes. @xref{Information About Keys}.
+
+@deftypefun {const char *} gpgme_trust_item_get_string_attr (@w{gpgme_trust_item_t @var{item}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
+The function @code{gpgme_trust_item_get_string_attr} returns the value
+of the string-representable attribute @var{what} of trust item
+@var{item}. The arguments @var{idx} and @var{reserved} are reserved
+for later use and should be @code{0} and @code{NULL} respectively.
+
+The string returned is only valid as long as the key is valid.
+
+The function returns @code{0} if an attribute can't be returned as a
+string, @var{key} is not a valid pointer, @var{idx} out of range,
+or @var{reserved} not @code{NULL}.
+@end deftypefun
+
+@deftypefun int gpgme_trust_item_get_int_attr (@w{gpgme_trust_item_t @var{item}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
+The function @code{gpgme_trust_item_get_int_attr} returns the value of
+the number-representable attribute @var{what} of trust item
+@var{item}. If the attribute occurs more than once in the trust item,
+the index is specified by @var{idx}. However, currently no such
+attribute exists, so @var{idx} should be @code{0}. The argument
+@var{reserved} is reserved for later use and should be @code{NULL}.
+
+The function returns @code{0} if the attribute can't be returned as a
+number, @var{key} is not a valid pointer, @var{idx} out of range,
+or @var{reserved} not @code{NULL}.
+@end deftypefun
+
+
+@deftp {Data type} {enum gpgme_sig_stat_t}
+@tindex gpgme_sig_stat_t
+The @code{gpgme_sig_stat_t} type holds the result of a signature check, or
+the combined result of all signatures. The following results are
+possible:
+
+@table @code
+@item GPGME_SIG_STAT_NONE
+This status should not occur in normal operation.
+
+@item GPGME_SIG_STAT_GOOD
+This status indicates that the signature is valid. For the combined
+result this status means that all signatures are valid.
+
+@item GPGME_SIG_STAT_GOOD_EXP
+This status indicates that the signature is valid but expired. For
+the combined result this status means that all signatures are valid
+and expired.
+
+@item GPGME_SIG_STAT_GOOD_EXPKEY
+This status indicates that the signature is valid but the key used to
+verify the signature has expired. For the combined result this status
+means that all signatures are valid and all keys are expired.
+
+@item GPGME_SIG_STAT_BAD
+This status indicates that the signature is invalid. For the combined
+result this status means that all signatures are invalid.
+
+@item GPGME_SIG_STAT_NOKEY
+This status indicates that the signature could not be verified due to
+a missing key. For the combined result this status means that all
+signatures could not be checked due to missing keys.
+
+@item GPGME_SIG_STAT_NOSIG
+This status indicates that the signature data provided was not a real
+signature.
+
+@item GPGME_SIG_STAT_ERROR
+This status indicates that there was some other error which prevented
+the signature verification.
+
+@item GPGME_SIG_STAT_DIFF
+For the combined result this status means that at least two signatures
+have a different status. You can get each key's status with
+@code{gpgme_get_sig_status}.
+@end table
+@end deftp
+
+@deftypefun {const char *} gpgme_get_sig_status (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_sig_stat_t *@var{r_stat}}, @w{time_t *@var{r_created}})
+The function @code{gpgme_get_sig_status} is equivalent to:
+
+@example
+ gpgme_verify_result_t result;
+ gpgme_signature_t sig;
+
+ result = gpgme_op_verify_result (ctx);
+ sig = result->signatures;
+
+ while (sig && idx)
+ @{
+ sig = sig->next;
+ idx--;
+ @}
+ if (!sig || idx)
+ return NULL;
+
+ if (r_stat)
+ @{
+ switch (gpg_err_code (sig->status))
+ @{
+ case GPG_ERR_NO_ERROR:
+ *r_stat = GPGME_SIG_STAT_GOOD;
+ break;
+
+ case GPG_ERR_BAD_SIGNATURE:
+ *r_stat = GPGME_SIG_STAT_BAD;
+ break;
+
+ case GPG_ERR_NO_PUBKEY:
+ *r_stat = GPGME_SIG_STAT_NOKEY;
+ break;
+
+ case GPG_ERR_NO_DATA:
+ *r_stat = GPGME_SIG_STAT_NOSIG;
+ break;
+
+ case GPG_ERR_SIG_EXPIRED:
+ *r_stat = GPGME_SIG_STAT_GOOD_EXP;
+ break;
+
+ case GPG_ERR_KEY_EXPIRED:
+ *r_stat = GPGME_SIG_STAT_GOOD_EXPKEY;
+ break;
+
+ default:
+ *r_stat = GPGME_SIG_STAT_ERROR;
+ break;
+ @}
+ @}
+ if (r_created)
+ *r_created = sig->timestamp;
+ return sig->fpr;
+@end example
+@end deftypefun
+
+@deftypefun {const char *} gpgme_get_sig_string_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{what}}, @w{int @var{whatidx}})
+The function @code{gpgme_get_sig_string_attr} is equivalent to:
+
+@example
+ gpgme_verify_result_t result;
+ gpgme_signature_t sig;
+
+ result = gpgme_op_verify_result (ctx);
+ sig = result->signatures;
+
+ while (sig && idx)
+ @{
+ sig = sig->next;
+ idx--;
+ @}
+ if (!sig || idx)
+ return NULL;
+
+ switch (what)
+ @{
+ case GPGME_ATTR_FPR:
+ return sig->fpr;
+
+ case GPGME_ATTR_ERRTOK:
+ if (whatidx == 1)
+ return sig->wrong_key_usage ? "Wrong_Key_Usage" : "";
+ else
+ return "";
+ default:
+ break;
+ @}
+
+ return NULL;
+@end example
+@end deftypefun
+
+@deftypefun {const char *} gpgme_get_sig_ulong_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{waht}}, @w{int @var{whatidx}})
+The function @code{gpgme_get_sig_ulong_attr} is equivalent to:
+
+@example
+ gpgme_verify_result_t result;
+ gpgme_signature_t sig;
+
+ result = gpgme_op_verify_result (ctx);
+ sig = result->signatures;
+
+ while (sig && idx)
+ @{
+ sig = sig->next;
+ idx--;
+ @}
+ if (!sig || idx)
+ return 0;
+
+ switch (what)
+ @{
+ case GPGME_ATTR_CREATED:
+ return sig->timestamp;
+
+ case GPGME_ATTR_EXPIRE:
+ return sig->exp_timestamp;
+
+ case GPGME_ATTR_VALIDITY:
+ return (unsigned long) sig->validity;
+
+ case GPGME_ATTR_SIG_STATUS:
+ switch (sig->status)
+ @{
+ case GPG_ERR_NO_ERROR:
+ return GPGME_SIG_STAT_GOOD;
+
+ case GPG_ERR_BAD_SIGNATURE:
+ return GPGME_SIG_STAT_BAD;
+
+ case GPG_ERR_NO_PUBKEY:
+ return GPGME_SIG_STAT_NOKEY;
+
+ case GPG_ERR_NO_DATA:
+ return GPGME_SIG_STAT_NOSIG;
+
+ case GPG_ERR_SIG_EXPIRED:
+ return GPGME_SIG_STAT_GOOD_EXP;
+
+ case GPG_ERR_KEY_EXPIRED:
+ return GPGME_SIG_STAT_GOOD_EXPKEY;
+
+ default:
+ return GPGME_SIG_STAT_ERROR;
+ @}
+
+ case GPGME_ATTR_SIG_SUMMARY:
+ return sig->summary;
+
+ default:
+ break;
+ @}
+ return 0;
+@end example
+@end deftypefun
+
+@deftypefun {const char *} gpgme_get_sig_key (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_key_t *@var{r_key}})
+The function @code{gpgme_get_sig_key} is equivalent to:
+
+@example
+ gpgme_verify_result_t result;
+ gpgme_signature_t sig;
+
+ result = gpgme_op_verify_result (ctx);
+ sig = result->signatures;
+
+ while (sig && idx)
+ @{
+ sig = sig->next;
+ idx--;
+ @}
+ if (!sig || idx)
+ return gpg_error (GPG_ERR_EOF);
+
+ return gpgme_get_key (ctx, sig->fpr, r_key, 0);
+@end example
+@end deftypefun
+
+
+
+
@include lesser.texi
projects / gpgme.git / blobdiff