Dies ist gpgme.info, hergestellt von Makeinfo Version 4.2 aus
gpgme.texi.

   This file documents the GPGME library.

   This is Edition 0.4.0, last updated 22 December 2002, of `The `GnuPG
Made Easy' Reference Manual', for Version 0.4.0.

   Copyright (C) 2002 g10 Code GmbH.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Free Software Needs Free Documentation" and
"GNU Lesser General Public License", the Front-Cover texts being (a)
(see below), and with the Back-Cover Texts being (b) (see below).  A
copy of the license is included in the section entitled "GNU Free
Documentation License".

Text Mode
---------

 - Funktion: void gpgme_set_textmode (GpgmeCtx CTX, int YES)
     The function `gpgme_set_textmode' specifies if canonical text mode
     should be used.  By default, text mode is not used.

     Text mode is for example used for the RFC2015 signatures; note that
     the updated RFC 3156 mandates that the mail user agent does some
     preparations so that text mode is not needed anymore.

     This option is only relevant to the OpenPGP crypto engine, and
     ignored by all other engines.

     Canonical text mode is disabled if YES is zero, and enabled
     otherwise.

 - Funktion: int gpgme_get_textmode (GpgmeCtx CTX)
     The function `gpgme_get_textmode' returns 1 if canonical text mode
     is enabled, and `0' if it is not, or if CTX is not a valid pointer.

Included Certificates
---------------------

 - Funktion: void gpgme_set_include_certs (GpgmeCtx CTX,
          int NR_OF_CERTS)
     The function `gpgme_set_include_certs' specifies how many
     certificates should be included in an S/MIME signed message.  By
     default, only the sender's certificate is included.  The possible
     values of NR_OF_CERTS are:

    `-2'
          Include all certificates except the root certificate.

    `-1'
          Include all certificates.

    `0'
          Include no certificates.

    `1'
          Include the sender's certificate only.

    `n'
          Include the first n certificates of the certificates path,
          starting from the sender's certificate.  The number `n' must
          be positive.

     Values of NR_OF_CERTS smaller than -2 are undefined.

     This option is only relevant to the CMS crypto engine, and ignored
     by all other engines.

 - Funktion: int gpgme_get_include_certs (GpgmeCtx CTX)
     The function `gpgme_get_include_certs' returns the number of
     certificates to include into an S/MIME signed message.

Key Listing Mode
----------------

 - Funktion: void gpgme_set_keylist_mode (GpgmeCtx CTX, int MODE)
     The function `gpgme_set_keylist_mode' changes the default
     behaviour of the key listing functions.  The value in MODE is a
     bitwise-or combination of one or multiple of the following bit
     values:

    `GPGME_KEYLIST_MODE_LOCAL'
          The `GPGME_KEYLIST_MODE_LOCAL' symbol specifies that the local
          keyring should be searched for keys in the keylisting
          operation.  This is the default.

    `GPGME_KEYLIST_MODE_EXTERN'
          The `GPGME_KEYLIST_MODE_EXTERN' symbol specifies that an
          external source should be should be searched for keys in the
          keylisting operation.  The type of external source is
          dependant on the crypto engine used.  For example, it can be
          a remote keyserver or LDAP certificate server.

     At least one of `GPGME_KEYLIST_MODE_LOCAL' and
     `GPGME_KEYLIST_MODE_EXTERN' must be specified.  For future binary
     compatibility, you should get the current mode with
     `gpgme_get_keylist_mode' and modify it by setting or clearing the
     appropriate bits, and then using that calulcated value in the
     `gpgme_set_keylisting_mode' operation.  This will leave all other
     bits in the mode value intact (in particular those that are not
     used in the current version of the library).

     The function returns `GPGME_No_Error' if the mode could be set
     correctly, and `GPGME_Invalid_Value' if CTX is not a valid pointer
     or MODE is not a valid mode.

 - Funktion: int gpgme_get_keylist_mode (GpgmeCtx CTX)
     The function `gpgme_get_keylist_mode' returns the current key
     listing mode of the context CTX.  This value can then be modified
     and used in a subsequent `gpgme_set_keylist_mode' operation to
     only affect the desired bits (and leave all others intact).

     The function returns 0 if CTX is not a valid pointer, and the
     current mode otherwise.  Note that 0 is not a valid mode value.

Passphrase Callback
-------------------

 - Data type: const char *(*GpgmePassphraseCb)(void *HOOK, const char
*DESC, void **R_HD)
     The `GpgmePassphraseCb' type is the type of functions usable as
     passphrase callback function.

     The string DESC contains a text usable to be displayed to the user
     of the application.  The function should return a passphrase for
     the context when invoked with DESC not being `NULL'.

     The user may store information about the resources associated with
     the returned passphrase in *R_HD.  When the passphrase is no longer
     needed by GPGME, the passphrase callback function will be called
     with DESC being NULL, and R_HD being the same as at the first
     invocation.

 - Funktion: void gpgme_set_passphrase_cb (GpgmeCtx CTX,
          GpgmePassphraseCb PASSFUNC, void *HOOK_VALUE)
     The function `gpgme_set_passphrase_cb' sets the function that is
     used when a passphrase needs to be provided by the user to
     PASSFUNC.  The function PASSFUNC needs to implemented by the user,
     and whenever it is called, it is called with its first argument
     being HOOK_VALUE.  By default, no passphrase callback function is
     set.

     Not all crypto engines require this callback to retrieve the
     passphrase.  It is better if the engine retrieves the passphrase
     from a trusted agent (a daemon process), rather than having each
     user to implement their own passphrase query.

     The user can disable the use of a passphrase callback function by
     calling `gpgme_set_passphrase_cb' with PASSFUNC being `NULL'.

 - Funktion: void gpgme_get_passphrase_cb (GpgmeCtx CTX,
          GpgmePassphraseCb *PASSFUNC, void **HOOK_VALUE)
     The function `gpgme_get_passphrase_cb' returns the function that
     is used when a passphrase needs to be provided by the user in
     *PASSFUNC, and the first argument for this function in
     *HOOK_VALUE.  If no passphrase callback is set, or CTX is not a
     valid pointer, `NULL' is returned in both variables.

     PASSFUNC or HOOK_VALUE can be `NULL'.  In this case, the
     corresponding value will not be returned.

Progress Meter Callback
-----------------------

 - Data type: const char *(*GpgmeProgressCb)(void *HOOK, const char
*WHAT, int TYPE, int CURRENT, int TOTAL)
     The `GpgmeProgressCb' type is the type of functions usable as
     progress callback function.

     The arguments are specific to the crypto engine.  More information
     about the progress information returned from the GnuPG engine can
     be found in the GnuPG source code in the file `doc/DETAILS' in the
     section PROGRESS.

 - Funktion: void gpgme_set_progress_cb (GpgmeCtx CTX,
          GpgmeProgressCb PROGFUNC, void *HOOK_VALUE)
     The function `gpgme_set_progress_cb' sets the function that is
     used when progress information about a cryptographic operation is
     available.  The function PROGFUNC needs to implemented by the
     user, and whenever it is called, it is called with its first
     argument being HOOK_VALUE.  By default, no progress callback
     function is set.

     Setting a callback function allows an interactive program to
     display progress information about a long operation to the user.

     The user can disable the use of a progress callback function by
     calling `gpgme_set_progress_cb' with PROGFUNC being `NULL'.

 - Funktion: void gpgme_get_progress_cb (GpgmeCtx CTX,
          GpgmeProgressCb *PROGFUNC, void **HOOK_VALUE)
     The function `gpgme_get_progress_cb' returns the function that is
     used to inform the user about the progress made in *PROGFUNC, and
     the first argument for this function in *HOOK_VALUE.  If no
     progress callback is set, or CTX is not a valid pointer, `NULL' is
     returned in both variables.

     PROGFUNC or HOOK_VALUE can be `NULL'.  In this case, the
     corresponding value will not be returned.

Key Management
==============

   Some of the cryptographic operations require that recipients or
signers are specified.  This is always done by specifying the
respective keys that should be used for the operation.  The following
section describes how such keys can be selected and manipulated.

 - Data type: GpgmeKey
     The `GpgmeKey' type is a handle for a public or secret key, and is
     used to select the key for operations involving it.

     A key can contain several user IDs and sub keys.

Listing Keys
------------

 - Funktion: GpgmeError gpgme_op_keylist_start (GpgmeCtx CTX,
          const char *PATTERN, int SECRET_ONLY)
     The function `gpgme_op_keylist_start' initiates a key listing
     operation inside the context CTX.  It sets everything up so that
     subsequent invocations of `gpgme_op_keylist_next' return the keys
     in the list.

     If PATTERN is `NULL', all available keys are returned.  Otherwise,
     PATTERN contains an engine specific expression that is used to
     limit the list to all keys matching the pattern.

     If SECRET_ONLY is not `0', the list is restricted to secret keys
     only.

     The context will be busy until either all keys are received (and
     `gpgme_op_keylist_next' returns `GPGME_EOF'), or
     `gpgme_op_keylist_end' is called to finish the operation.

     The function returns `GPGME_Invalid_Value' if CTX is not a valid
     pointer, and passes through any errors that are reported by the
     crypto engine support routines.

 - Funktion: GpgmeError gpgme_op_keylist_ext_start (GpgmeCtx CTX,
          const char *PATTERN[], int SECRET_ONLY, int RESERVED)
     The function `gpgme_op_keylist_ext_start' initiates an extended
     key listing operation inside the context CTX.  It sets everything
     up so that subsequent invocations of `gpgme_op_keylist_next'
     return the keys in the list.

     If PATTERN or *PATTERN is `NULL', all available keys are returned.
     Otherwise, PATTERN is a `NULL' terminated array of strings that
     are used to limit the list to all keys matching at least one of
     the patterns verbatim.

     If SECRET_ONLY is not `0', the list is restricted to secret keys
     only.

     The value of RESERVED must be `0'.

     The context will be busy until either all keys are received (and
     `gpgme_op_keylist_next' returns `GPGME_EOF'), or
     `gpgme_op_keylist_end' is called to finish the operation.

     The function returns `GPGME_Invalid_Value' if CTX is not a valid
     pointer, and passes through any errors that are reported by the
     crypto engine support routines.

 - Funktion: GpgmeError gpgme_op_keylist_next (GpgmeCtx CTX,
          GpgmeKey *R_KEY)
     The function `gpgme_op_keylist_next' returns the next key in the
     list created by a previous `gpgme_op_keylist_start' operation in
     the context CTX.  The key will have one reference for the user.
     See Manipulating Keys.

     This is the only way to get at `GpgmeKey' objects in GPGME.

     If the last key in the list has already been returned,
     `gpgme_op_keylist_next' returns `GPGME_EOF'.

     The function returns `GPGME_Invalid_Value' if CTX or R_KEY is not
     a valid pointer, `GPGME_No_Request' if there is no pending
     operation, `GPGME_Out_Of_Core' if there is not enough memory for
     the operation.

 - Funktion: GpgmeError gpgme_op_keylist_end (GpgmeCtx CTX)
     The function `gpgme_op_keylist_next' ends a pending key list
     operation in the context CTX.

     The function returns `GPGME_Invalid_Value' if CTX is not a valid
     pointer, `GPGME_No_Request' if there is no pending operation,
     `GPGME_Out_Of_Core' if at some time during the operation there was
     not enough memory available.

   The following example illustrates how all keys containing a certain
string (`g10code') can be listed with their key ID and the name and
e-mail address of the main user ID:

     GpgmeCtx ctx;
     GpgmeError err = gpgme_new (&ctx);

     if (!err)
       {
         err = gpgme_op_keylist_start (ctx, "g10code", 0);
         while (!err && (err = gpgme_op_keylist_next (ctx, &key)) != GPGME_EOF)
           {
             printf ("%s: %s <%s>\n",
                     gpgme_key_get_string_attr (key, GPGME_ATTR_KEYID, 0, 0),
     	        gpgme_key_get_string_attr (key, GPGME_ATTR_NAME, 0, 0),
     	        gpgme_key_get_string_attr (key, GPGME_ATTR_EMAIL, 0, 0));
             gpgme_key_release (key);
           }
         gpgme_release (ctx);
       }
     if (err)
       {
         fprintf (stderr, "%s: can not list keys: %s\n",
                  argv[0], gpgme_strerror (err));
         exit (1);
       }

   In a simple program, for which a blocking operation is acceptable,
the following function can be used to retrieve a single key.

 - Funktion: GpgmeError gpgme_get_key (GpgmeCtx CTX, const char *FPR,
          GpgmeKey *R_KEY, int SECRET, int FORCE_UPDATE)
     The function `gpgme_get_key' gets the key with the fingerprint (or
     key ID) FPR from the key cache or from the crypto backend and
     return it in R_KEY.  If FORCE_UPDATE is true, force a refresh of
     the key from the crypto backend and replace the key in the cache,
     if any.  If SECRET is true, get the secret key.

     If the `GPGME_KEYLIST_MODE_SIGS' mode is active, the key will be
     retrieved with the key signatures (and updated if necessary).

     The function returns `GPGME_Invalid_Value' if CTX or R_KEY is not
     a valid pointer, `GPGME_Busy' if there is a pending operation,
     `GPGME_Invalid_Key' if FPR is not a fingerprint or key ID,
     `GPGME_Out_Of_Core' if at some time during the operation there was
     not enough memory available.

Information About Keys
----------------------

 - Funktion: char * gpgme_key_get_as_xml (GpgmeKey KEY)
     The function `gpgme_key_get_as_xml' returns a string in XML format
     describing the key KEY.  The user has to release the string with
     `free'.

     The function returns `NULL' if KEY is not a valid pointer, or
     there is not enough memory available.

 - Data type: GpgmeAttr
     The `GpgmeAttr' type is used to specify a key or trust item
     attribute.  The following attributes are defined:

    `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.

    `GPGME_ATTR_FPR'
          This is the fingerprint of a sub key.  It is representable as
          a string.

    `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 `enum gcry_pk_algos' values in the
          gcrypt library.

    `GPGME_ATTR_LEN'
          This is the key length of a sub key.  It is representable as a
          number.

    `GPGME_ATTR_CREATED'
          This is the timestamp at creation time of a sub key.  It is
          representable as a number.

    `GPGME_ATTR_EXPIRE'
          This is the expiration time of a sub key.  It is
          representable as a number.

    `GPGME_ATTR_OTRUST'
          XXX FIXME  (also for trust items)

    `GPGME_ATTR_USERID'
          This is a user ID.  There can be more than one user IDs in a
          GPGMEKEY 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.

    `GPGME_ATTR_NAME'
          This is the name belonging to a user ID.  It is representable
          as a string.

    `GPGME_ATTR_EMAIL'
          This is the email address belonging to a user ID.  It is
          representable as a string.

    `GPGME_ATTR_COMMENT'
          This is the comment belonging to a user ID.  It is
          representable as a string.

    `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.

    `GPGME_ATTR_UID_REVOKED'
          This specifies if a user ID is revoked.  It is representable
          as a number, and is `1' if the user ID is revoked, and `0'
          otherwise.

    `GPGME_ATTR_UID_INVALID'
          This specifies if a user ID is invalid.  It is representable
          as a number, and is `1' if the user ID is invalid, and `0'
          otherwise.

    `GPGME_ATTR_LEVEL'
          This is the trust level of a trust 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.

    `GPGME_ATTR_IS_SECRET'
          This specifies if the key is a secret key.  It is
          representable as a string or a number.  If the key is a
          secret key, the representation is "1" or `1', otherwise it is
          `NULL' or `0'.

    `GPGME_ATTR_KEY_REVOKED'
          This specifies if a sub key is revoked.  It is representable
          as a number, and is `1' if the key is revoked, and `0'
          otherwise.

    `GPGME_ATTR_KEY_INVALID'
          This specifies if a sub key is invalid.  It is representable
          as a number, and is `1' if the key is invalid, and `0'
          otherwise.

    `GPGME_ATTR_KEY_EXPIRED'
          This specifies if a sub key is expired.  It is representable
          as a number, and is `1' if the key is expired, and `0'
          otherwise.

    `GPGME_ATTR_KEY_DISABLED'
          This specifies if a sub key is disabled.  It is representable
          as a number, and is `1' if the key is disabled, and `0'
          otherwise.

    `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.

    `GPGME_ATTR_CAN_ENCRYPT'
          This specifies if a sub key can be used for encryption.  It is
          representable as a number, and is `1' if the sub key can be
          used for encryption, and `0' otherwise.

    `GPGME_ATTR_CAN_SIGN'
          This specifies if a sub key can be used for signatures.  It is
          representable as a number, and is `1' if the sub key can be
          used for signatures, and `0' otherwise.

    `GPGME_ATTR_CAN_CERTIFY'
          This specifies if a sub key can be used for certifications.
          It is representable as a number, and is `1' if the sub key
          can be used for certifications, and `0' otherwise.

    `GPGME_ATTR_SERIAL'
          The X.509 issuer serial attribute of the key.  It is
          representable as a string.

    `GPGME_ATTR_ISSUE'
          The X.509 issuer name attribute of the key.  It is
          representable as a string.

    `GPGME_ATTR_CHAINID'
          The X.509 chain ID can be used to build the certification
          chain.  It is representable as a string.

 - Data type: GpgmeValidity
     The `GpgmeValidity' type is used to specify the validity of a user
     ID in a key.  The following validities are defined:

    `GPGME_VALIDITY_UNKNOWN'
          The user ID is of unknown validity.  The string
          representation of this validity is "?".

    `GPGME_VALIDITY_UNDEFINED'
          The validity of the user ID is undefined.  The string
          representation of this validity is "q".

    `GPGME_VALIDITY_NEVER'
          The user ID is never valid.  The string representation of this
          validity is "n".

    `GPGME_VALIDITY_MARGINAL'
          The user ID is marginally valid.  The string representation
          of this validity is "m".

    `GPGME_VALIDITY_FULL'
          The user ID is fully valid.  The string representation of this
          validity is "f".

    `GPGME_VALIDITY_ULTIMATE'
          The user ID is ultimately valid.  The string representation
          of this validity is "u".

 - Funktion: const char * gpgme_key_get_string_attr (GpgmeKey KEY,
          GpgmeAttr WHAT, const void *RESERVED, int IDX)
     The function `gpgme_key_get_string_attr' returns the value of the
     string-representable attribute WHAT of key KEY.  If the attribute
     is an attribute of a sub key or an user ID, IDX specifies the sub
     key or user ID of which the attribute value is returned.  The
     argument RESERVED is reserved for later use and should be `NULL'.

     The string returned is only valid as long as the key is valid.

     The function returns `0' if an attribute can't be returned as a
     string, KEY is not a valid pointer, IDX out of range, or RESERVED
     not `NULL'.

 - Funktion: unsigned long gpgme_key_get_ulong_attr (GpgmeKey KEY,
          GpgmeAttr WHAT, const void *RESERVED, int IDX)
     The function `gpgme_key_get_ulong_attr' returns the value of the
     number-representable attribute WHAT of key KEY.  If the attribute
     is an attribute of a sub key or an user ID, IDX specifies the sub
     key or user ID of which the attribute value is returned.  The
     argument RESERVED is reserved for later use and should be `NULL'.

     The function returns `0' if the attribute can't be returned as a
     number, KEY is not a valid pointer, IDX out of range, or RESERVED
     not `NULL'.

Key Signatures
--------------

   The signatures on a key are only available if the key was retrieved
via a listing operation with the `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 `gpgme_get_key'.

 - Data type: GpgmeAttr
     The `GpgmeAttr' type is used to specify a key signature attribute.
     The following attributes are defined:

    `GPGME_ATTR_KEYID'
          This is the key ID of the key which was used for the
          signature.  It is representable as a string.

    `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 `enum gcry_pk_algos' values in the gcrypt
          library.

    `GPGME_ATTR_CREATED'
          This is the timestamp at creation time of the signature.  It
          is representable as a number.

    `GPGME_ATTR_EXPIRE'
          This is the expiration time of the signature.  It is
          representable as a number.

    `GPGME_ATTR_USERID'
          This is the user ID associated with the signing key.  The
          user ID is representable as a number.

    `GPGME_ATTR_NAME'
          This is the name belonging to a user ID.  It is representable
          as a string.

    `GPGME_ATTR_EMAIL'
          This is the email address belonging to a user ID.  It is
          representable as a string.

    `GPGME_ATTR_COMMENT'
          This is the comment belonging to a user ID.  It is
          representable as a string.

    `GPGME_ATTR_KEY_REVOKED'
          This specifies if a key signature is a revocation signature.
          It is representable as a number, and is `1' if the key is
          revoked, and `0' otherwise.

    `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.

    `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.

    `GPGME_ATTR_SIG_STATUS'
          This is the same value as returned by `gpgme_get_sig_status'.

 - Funktion: const char * gpgme_key_sig_get_string_attr (GpgmeKey KEY,
          int UID_IDX, GpgmeAttr WHAT, const void *RESERVED, int IDX)
     The function `gpgme_key_sig_get_string_attr' returns the value of
     the string-representable attribute WHAT of the signature IDX on
     the user ID UID_IDX in the key KEY.  The argument RESERVED is
     reserved for later use and should be `NULL'.

     The string returned is only valid as long as the key is valid.

     The function returns `0' if an attribute can't be returned as a
     string, KEY is not a valid pointer, UID_IDX or IDX out of range,
     or RESERVED not `NULL'.

 - Funktion: unsigned long gpgme_key_sig_get_ulong_attr (GpgmeKey KEY,
          int UID_IDX, GpgmeAttr WHAT, const void *RESERVED, int IDX)
     The function `gpgme_key_sig_get_ulong_attr' returns the value of
     the number-representable attribute WHAT of the signature IDX on
     the user ID UID_IDX in the key KEY.  The argument RESERVED is
     reserved for later use and should be `NULL'.

     The function returns `0' if an attribute can't be returned as a
     string, KEY is not a valid pointer, UID_IDX or IDX out of range,
     or RESERVED not `NULL'.

Manipulating Keys
-----------------

 - Funktion: void gpgme_key_ref (GpgmeKey KEY)
     The function `gpgme_key_ref' acquires an additional reference for
     the key KEY.

 - Funktion: void gpgme_key_unref (GpgmeKey KEY)
 - Funktion: void gpgme_key_release (GpgmeKey KEY)
     The function `gpgme_key_ref' releases a reference for the key KEY.
     If this was the last reference, the key will be destroyed and all
     resources associated to it will be released.

     The function `gpgme_key_release' is an alias for `gpgme_key_unref'.

Generating Keys
---------------

 - Funktion: GpgmeError gpgme_op_genkey (GpgmeCtx CTX,
          const char *PARMS, GpgmeData PUBKEY, GpgmeData SECKEY,
          char **FPR)
     The function `gpgme_op_genkey' generates a new key pair in the
     context CTX and puts it into the standard key ring if both PUBKEY
     and SECKEY are `NULL'.  In this case the function returns
     immediately after starting the operation, and does not wait for it
     to complete.  If PUBKEY is not `NULL' it should be the handle for
     an empty (newly created) data object, and upon successful
     completion the data object will contain the public key.  If SECKEY
     is not `NULL' it should be the handle for an empty (newly created)
     data object, and upon successful completion the data object will
     contain the secret key.

     Note that not all crypto engines support this interface equally.
     GnuPG does not support PUBKEY and SUBKEY, they should be both
     `NULL', and the key pair will be added to the standard key ring.
     GpgSM does only support PUBKEY, the secret key will be stored by
     `gpg-agent'.  GpgSM expects PUBKEY being not `NULL'.

     The argument PARMS specifies parameters for the key in an XML
     string.  The details about the format of PARMS are specific to the
     crypto engine used by CTX.  Here is an example for GnuPG as the
     crypto engine:

          <GnupgKeyParms format="internal">
          Key-Type: DSA
          Key-Length: 1024
          Subkey-Type: ELG-E
          Subkey-Length: 1024
          Name-Real: Joe Tester
          Name-Comment: with stupid passphrase
          Name-Email: joe@foo.bar
          Expire-Date: 0
          Passphrase: abc
          </GnupgKeyParms>

     Here is an example for GpgSM as the crypto engine:
          <GnupgKeyParms format="internal">
          Key-Type: RSA
          Key-Length: 1024
          Name-DN: C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester
          Name-Email: joe@foo.bar
          </GnupgKeyParms>

     Strings should be given in UTF-8 encoding.  The only format
     supported for now is "internal".  The content of the
     `GnupgKeyParms' container is passed verbatim to GnuPG.  Control
     statements are not allowed.

     If FPR is not a null pointer, the function succeeds, and the
     crypto engine supports it, *FPR will contain a string with the
     fingerprint of the key, allocated with `malloc'.  If both a
     primary and a sub key was generated, the fingerprint of the primary
     key will be returned.  If the crypto engine does not provide the
     fingerprint, *FPR will be a null pointer.

     The function returns `GPGME_No_Error' if the operation could be
     started successfully, `GPGME_Invalid_Value' if PARMS is not a
     valid XML string, `GPGME_Not_Supported' if PUBKEY or SECKEY is not
     valid, and `GPGME_General_Error' if no key was created by the
     backend.

 - Funktion: GpgmeError gpgme_op_genkey_start (GpgmeCtx CTX,
          const char *PARMS, GpgmeData PUBKEY, GpgmeData SECKEY)
     The function `gpgme_op_genkey_start' initiates a `gpgme_op_genkey'
     operation.  It can be completed by calling `gpgme_wait' on the
     context.  See Waiting For Completion.

     The function returns `GPGME_No_Error' if the operation could be
     started successfully, `GPGME_Invalid_Value' if PARMS is not a
     valid XML string, and `GPGME_Not_Supported' if PUBKEY or SECKEY is
     not `NULL'.

Exporting Keys
--------------

 - Funktion: GpgmeError gpgme_op_export (GpgmeCtx CTX,
          GpgmeRecipients RECIPIENTS, GpgmeData KEYDATA)
     The function `gpgme_op_export' extracts the public keys of the
     user IDs in RECIPIENTS and returns them in the data buffer
     KEYDATA.  The type of the public keys returned is determined by
     the ASCII armor attribute set for the context CTX.

     The function returns `GPGME_No_Error' if the operation completed
     successfully, `GPGME_Invalid_Value' if RECIPIENTS is `NULL' or
     KEYDATA is not a valid empty data buffer, and passes through any
     errors that are reported by the crypto engine support routines.

 - Funktion: GpgmeError gpgme_op_export_start (GpgmeCtx CTX,
          GpgmeRecipients RECIPIENTS, GpgmeData KEYDATA)
     The function `gpgme_op_export_start' initiates a `gpgme_op_export'
     operation.  It can be completed by calling `gpgme_wait' on the
     context.  See Waiting For Completion.

     The function returns `GPGME_No_Error' if the operation could be
     started successfully, and `GPGME_Invalid_Value' if RECIPIENTS is
     `NULL' or KEYDATA is not a valid empty data buffer.

Importing Keys
--------------

 - Funktion: GpgmeError gpgme_op_import (GpgmeCtx CTX,
          GpgmeData KEYDATA)
     The function `gpgme_op_import' adds the keys in the data buffer
     KEYDATA to the key ring of the crypto engine used by CTX.  The
     format of KEYDATA can be ASCII armored, for example, but the
     details are specific to the crypto engine.

     More information about the import is available with
     `gpgme_get_op_info'.  See Detailed Results.

     The function returns `GPGME_No_Error' if the import was completed
     successfully, `GPGME_Invalid_Value' if KEYDATA if CTX or KEYDATA
     is not a valid pointer, and `GPGME_No_Data' if KEYDATA is an empty
     data buffer.

 - Funktion: GpgmeError gpgme_op_import_start (GpgmeCtx CTX,
          GpgmeData KEYDATA)
     The function `gpgme_op_import_start' initiates a `gpgme_op_import'
     operation.  It can be completed by calling `gpgme_wait' on the
     context.  See Waiting For Completion.

     The function returns `GPGME_No_Error' if the import could be
     started successfully, `GPGME_Invalid_Value' if KEYDATA if CTX or
     KEYDATA is not a valid pointer, and `GPGME_No_Data' if KEYDATA is
     an empty data buffer.

 - Funktion: GpgmeError gpgme_op_import_ext (GpgmeCtx CTX,
          GpgmeData KEYDATA, int *NR)
     The function `gpgme_op_import_ext' is like `gpgme_op_import', but
     also returns the number of processed keys in NR.  This is the same
     as the `count' information in the detailed results available with
     `gpgme_get_op_info'.

Deleting Keys
-------------

 - Funktion: GpgmeError gpgme_op_delete (GpgmeCtx CTX,
          const GpgmeKey KEY, int ALLOW_SECRET)
     The function `gpgme_op_delete' deletes the key KEY from the key
     ring of the crypto engine used by CTX.  If ALLOW_SECRET is `0',
     only public keys are deleted, otherwise secret keys are deleted as
     well, if that is supported.

     The function returns `GPGME_No_Error' if the key was deleted
     successfully, `GPGME_Invalid_Value' if CTX or KEY is not a valid
     pointer, `GPGME_Invalid_Key' if KEY could not be found in the
     keyring, and `GPGME_Conflict' if the secret key for KEY is
     available, but ALLOW_SECRET is zero.

 - Funktion: GpgmeError gpgme_op_delete_start (GpgmeCtx CTX,
          const GpgmeKey KEY, int ALLOW_SECRET)
     The function `gpgme_op_delete_start' initiates a `gpgme_op_delete'
     operation.  It can be completed by calling `gpgme_wait' on the
     context.  See Waiting For Completion.

     The function returns `GPGME_No_Error' if the operation was started
     successfully, and `GPGME_Invalid_Value' if CTX or KEY is not a
     valid pointer.

Trust Item Management
=====================

   *Caution:* The trust items interface is experimental.

 - Data type: GpgmeTrustItem
     The `GpgmeTrustItem' type is a handle for a trust item.

Listing Trust Items
-------------------

 - Funktion: GpgmeError gpgme_op_trustlist_start (GpgmeCtx CTX,
          const char *PATTERN, int MAX_LEVEL)
     The function `gpgme_op_trustlist_start' initiates a trust item
     listing operation inside the context CTX.  It sets everything up
     so that subsequent invocations of `gpgme_op_trustlist_next' return
     the trust items in the list.

     The string PATTERN contains an engine specific expression that is
     used to limit the list to all trust items matching the pattern.  It
     can not be the empty string.

     The argument MAX_LEVEL is currently ignored.

     The context will be busy until either all trust items are received
     (and `gpgme_op_trustlist_next' returns `GPGME_EOF'), or
     `gpgme_op_trustlist_end' is called to finish the operation.

     The function returns `GPGME_Invalid_Value' if CTX is not a valid
     pointer, and passes through any errors that are reported by the
     crypto engine support routines.

 - Funktion: GpgmeError gpgme_op_trustlist_next (GpgmeCtx CTX,
          GpgmeTrustItem *R_ITEM)
     The function `gpgme_op_trustlist_next' returns the next trust item
     in the list created by a previous `gpgme_op_trustlist_start'
     operation in the context CTX.  The trust item can be destroyed
     with `gpgme_trust_item_release'.  See Manipulating Trust Items.

     This is the only way to get at `GpgmeTrustItem' objects in GPGME.

     If the last trust item in the list has already been returned,
     `gpgme_op_trustlist_next' returns `GPGME_EOF'.

     The function returns `GPGME_Invalid_Value' if CTX or R_ITEM is not
     a valid pointer, `GPGME_No_Request' if there is no pending
     operation, `GPGME_Out_Of_Core' if there is not enough memory for
     the operation.

 - Funktion: GpgmeError gpgme_op_trustlist_end (GpgmeCtx CTX)
     The function `gpgme_op_trustlist_next' ends a pending key list
     operation in the context CTX.

     The function returns `GPGME_Invalid_Value' if CTX is not a valid
     pointer, `GPGME_No_Request' if there is no pending operation,
     `GPGME_Out_Of_Core' if at some time during the operation there was
     not enough memory available.

Information About Trust Items
-----------------------------

   Trust items have attributes which can be queried using the interfaces
below.  The attribute identifiers are shared with those for key
attributes.  See Information About Keys.

 - Funktion: const char * gpgme_trust_item_get_string_attr
          (GpgmeTrustItem ITEM, GpgmeAttr WHAT, const void *RESERVED,
          int IDX)
     The function `gpgme_trust_item_get_string_attr' returns the value
     of the string-representable attribute WHAT of trust item ITEM.
     The arguments IDX and RESERVED are reserved for later use and
     should be `0' and `NULL' respectively.

     The string returned is only valid as long as the key is valid.

     The function returns `0' if an attribute can't be returned as a
     string, KEY is not a valid pointer, IDX out of range, or RESERVED
     not `NULL'.

 - Funktion: int gpgme_trust_item_get_int_attr (GpgmeTrustItem ITEM,
          GpgmeAttr WHAT, const void *RESERVED, int IDX)
     The function `gpgme_trust_item_get_int_attr' returns the value of
     the number-representable attribute WHAT of trust item ITEM.  If
     the attribute occurs more than once in the trust item, the index
     is specified by IDX.  However, currently no such attribute exists,
     so IDX should be `0'.  The argument RESERVED is reserved for later
     use and should be `NULL'.

     The function returns `0' if the attribute can't be returned as a
     number, KEY is not a valid pointer, IDX out of range, or RESERVED
     not `NULL'.

Manipulating Trust Items
------------------------

 - Funktion: void gpgme_trust_item_release (GpgmeTrustItem ITEM)
     The function `gpgme_trust_item_release' destroys a
     `GpgmeTrustItem' object and releases all associated resources.

Crypto Operations
=================

Decrypt
-------

 - Funktion: GpgmeError gpgme_op_decrypt (GpgmeCtx CTX,
          GpgmeData CIPHER, GpgmeData PLAIN)
     The function `gpgme_op_decrypt' decrypts the ciphertext in the
     data object CIPHER and stores it into the data object PLAIN.

     The function returns `GPGME_No_Error' if the ciphertext could be
     decrypted successfully, `GPGME_Invalid_Value' if CTX, CIPHER or
     PLAIN is not a valid pointer, `GPGME_No_Data' if CIPHER does not
     contain any data to decrypt, `GPGME_Decryption_Failed' if CIPHER
     is not a valid cipher text, `GPGME_No_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.

 - Funktion: GpgmeError gpgme_op_decrypt_start (GpgmeCtx CTX,
          GpgmeData CIPHER, GpgmeData PLAIN)
     The function `gpgme_op_decrypt_start' initiates a
     `gpgme_op_decrypt' operation.  It can be completed by calling
     `gpgme_wait' on the context.  See Waiting For Completion.

     The function returns `GPGME_No_Error' if the operation could be
     started successfully, and `GPGME_Invalid_Value' if CIPHER or PLAIN
     is not a valid pointer.