     [file version.texi not included]

This file documents the GPGME library.

This is Edition EDITION, last updated UPDATED, of The `GnuPG Made Easy' Reference Manual, for Version VERSION.

Copyright © 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''.

Main Menu
*********

This is Edition EDITION, last updated UPDATED, of The `GnuPG Made Easy' Reference Manual, for Version VERSION of the GPGME library.

Introduction
************

`GnuPG Made Easy' (GPGME) is a C language library that allows to add support for cryptography to a program.  It is designed to make access to crypto engines like GnuPG or GpgSM easier for applications.  GPGME provides a high-level crypto API for encryption, decryption, signing, signature verification and key management.

GPGME uses GnuPG and GpgSM as its backends to support OpenPGP and the Cryptographic Message Syntax (CMS).

Getting Started
===============

This library documents the GPGME library programming interface.  All functions and data types provided by the library are explained.

The reader is assumed to possess basic knowledge about cryptography in general, and public key cryptography in particular.  The underlying cryptographic engines that are used by the library are not explained, but where necessary, special features or requirements by an engine are mentioned as far as they are relevant to GPGME or its users.

This manual can be used in several ways.  If read from the beginning to the end, it gives a good introduction into the library and how it can be used in an application.  Forward references are included where necessary.  Later on, the manual can be used as a reference manual to get just the information needed about any particular interface of the library.  Experienced programmers might want to start looking at the examples at the end of the manual, and then only read up those parts of the interface which are unclear.

Features
========

GPGME has a couple of advantages over other libraries doing a similar job, and over implementing support for GnuPG or other crypto engines into your application directly.

it's free software
     Anybody can use, modify, and redistribute it under the terms of the GNU General Public License (see Copying).

it's flexible
     GPGME provides transparent support for several cryptographic protocols by different engines.  Currently, GPGME supports the OpenPGP protocol using GnuPG as the backend, and the Cryptographic Message Syntax using GpgSM as the backend.

it's easy
     GPGME hides the differences between the protocols and engines from the programmer behind an easy-to-use interface.  This way the programmer can focus on the other parts of the program, and still integrate strong cryptography in his application.  Once support for GPGME has been added to a program, it is easy to add support for other crypto protocols once GPGME backends provide them.

Overview
========

GPGME provides a data abstraction that is used to pass data to the crypto engine, and receive returned data from it.  Data can be read from memory or from files, but it can also be provided by a callback function.

The actual cryptographic operations are always set within a context. A context provides configuration parameters that define the behaviour of all operations performed within it.  Only one operation per context is allowed at any time, but when one operation is finished, you can run the next operation in the same context.  There can be more than one context, and all can run different operations at the same time.

Furthermore, GPGME has rich key management facilities including listing keys, querying their attributes, generating, importing, exporting and deleting keys, and acquiring information about the trust path.

Caution: The GPGME library is not thread-safe.  It will be to some extent in the future, but currently great care has to be taken if GPGME is used in a multi-threaded environment.

Preparation
***********

To use GPGME, you have to perform some changes to your sources and the build system.  The necessary changes are small and explained in the following sections.  At the end of this chapter, it is described how the library is initialized, and how the requirements of the library are verified.

Header
======

All interfaces (data types and functions) of the library are defined in the header file `gpgme.h'.  You must include this in all programs using the library, either directly or through some other header file, like this:

     #include <gpgme.h>

The name space of GPGME is gpgme_* for function names, Gpgme* for data types and GPGME_* for other symbols.

Building the Source
===================

If you want to compile a source file including the `gpgme.h' header file, you must make sure that the compiler can find it in the directory hierarchy.  This is accomplished by adding the path to the directory in which the header file is located to the compilers include file search path (via the -I option).

However, the path to the include file is determined at the time the source is configured.  To solve this problem, gpgme ships with a small helper program gpgme-config that knows about the path to the include file and other configuration options.  The options that need to be added to the compiler invocation at compile time are output by the --cflags option to gpgme-config.  The following example shows how it can be used at the command line:

     gcc -c foo.c `gpgme-config --cflags`

Adding the output of gpgme-config --cflags to the compilers command line will ensure that the compiler can find the GPGME header file.

A similar problem occurs when linking the program with the library. Again, the compiler has to find the library files.  For this to work, the path to the library files has to be added to the library search path (via the -L option).  For this, the option --libs to gpgme-config can be used.  For convenience, this option also outputs all other options that are required to link the program with GPGME (in particular, the -lgpgme option).  The example shows how to link foo.o with the GPGME library to a program foo.

     gcc -o foo foo.o `gpgme-config --libs`

Of course you can also combine both examples to a single command by specifying both options to gpgme-config:

     gcc -o foo foo.c `gpgme-config --cflags --libs`

Library Version Check
=====================

 -- Function: const char * gpgme_check_version (const char *REQUIRED_VERSION)
     The function gpgme_check_version has three purposes.  It can be used to retrieve the version number of the library.  In addition it can verify that the version number is higher than a certain required version number.  In either case, the function initializes some sub-systems, and for this reason alone it must be invoked early in your program, before you make use of the other functions in GPGME.

     If REQUIRED_VERSION is NULL, the function returns a pointer to a statically allocated string containing the version number of the library.

     If REQUIRED_VERSION is not NULL, it should point to a string containing a version number, and the function checks that the version of the library is at least as high as the version number provided.  In this case, the function returns a pointer to a statically allocated string containing the version number of the library.  If REQUIRED_VERSION is not a valid version number, or if the version requirement is not met, the function returns NULL.

     If you use a version of a library that is backwards compatible with older releases, but contains additional interfaces which your program uses, this function provides a run-time check if the necessary features are provided by the installed version of the library.

Protocols and Engines
*********************

GPGME supports several cryptographic protocols, however, it does not implement them.  Rather it uses backends (also called engines) which implement the protocol.  GPGME uses inter-process communication to pass data back and forth between the application and the backend, but the details of the communication protocol and invocation of the backends is completely hidden by the interface.  All complexity is handled by GPGME.  Where an exchange of information between the application and the backend is necessary, GPGME provides the necessary callback function hooks and further interfaces.

 -- Data type: enum GpgmeProtocol
     The GpgmeProtocol type specifies the set of possible protocol values that are supported by GPGME.  The following protocols are supported:

     GPGME_PROTOCOL_OpenPGP
          This specifies the OpenPGP protocol.

     GPGME_PROTOCOL_CMS
          This specifies the Cryptographic Message Syntax.

Engine Version Check
====================

 -- Function: GpgmeError gpgme_engine_check_version (GpgmeProtocol PROTOCOL)
     The function gpgme_engine_check_version verifies that the engine implementing the protocol PROTOCOL is installed in the expected path and meets the version requirement of GPGME.

     This function returns GPGME_No_Error if the engine is available and GPGME_Invalid_Engine if it is not.

 -- Function: GpgmeError gpgme_check_engine (void)
     The function gpgme_check_engine is equivalent to

          gpgme_engine_check_version (GPGME_PROTOCOL_OpenPGP);

     This function is deprecated and provided for backwards compatibility only.  It is obsoleted by gpgme_engine_check_version.

Engine Information
==================

 -- Function: const char * gpgme_get_engine_info (void)
     The function gpgme_get_engine_info returns an XML string containing information about the available protocols and the engine which implement them.  The following information is returned for each engine:

     <protocol>
          The name of the protocol.

     <version>
          The version of the engine.

     <path>
          The path to the engine binary.

     A string is always returned.  If an error occurs, the string will contain an <error> tag with a description of the failure.

Here is the example output of what gpgme_get_engine_info might return on your system:

     <EngineInfo>
      <engine>
       <protocol>OpenPGP</protocol>
       <version>1.0.6</version>
       <path>/usr/bin/gpg</path>
      </engine>
      <engine>
       <protocol>CMS</protocol>
       <version>0.0.0</version>
       <path>/usr/bin/gpgsm</path>
      </engine>
     </EngineInfo>

OpenPGP
=======

OpenPGP is implemented by GnuPG, the GNU Privacy Guard. This is the first protocol that was supported by GPGME.

The OpenPGP protocol is specified by GPGME_PROTOCOL_OpenPGP.

Cryptographic Message Syntax
============================

CMS is implemented by GpgSM, the S/MIME implementation for GnuPG.

The CMS protocol is specified by GPGME_PROTOCOL_CMS.

Error Handling
**************

Many functions in GPGME can return an error if they fail. For this reason, the application should always catch the error condition and take appropriate measures, for example by releasing the resources and passing the error up to the caller, or by displaying a descriptive message to the user and cancelling the operation.

Some error values do not indicate a system error or an error in the operation, but the result of an operation that failed properly.  For example, if you try to decrypt a tempered message, the decryption will fail.  Another error value actually means that the end of a data buffer or list has been reached.  The following descriptions explain what each error message means in general.  Some error values have specific meanings if returned by a specific function.  Such cases are described in the documentation of those functions.

Error Values
============

 -- Data type: enum GpgmeError
     The GpgmeError type specifies the set of all error values that are used by GPGME.  Possible values are:

     GPGME_EOF
          This value indicates the end of a list, buffer or file.

     GPGME_No_Error
          This value indicates success.  The value of this error is 0.

     GPGME_General_Error
          This value means that something went wrong, but either there is not enough information about the problem to return a more useful error value, or there is no separate error value for this type of problem.

     GPGME_Out_Of_Core
          This value means that an out-of-memory condition occurred.

     GPGME_Invalid_Value
          This value means that some user provided data was out of range.  This can also refer to objects.  For example, if an empty GpgmeData object was expected, but one containing data was provided, this error value is returned.

     GPGME_Busy
          This value is returned if you try to start a new operation in a context that is already busy with some earlier operation which was not cancelled or finished yet.

     GPGME_No_Request
          This value is in some sense the opposite of GPGME_Busy.  There is no pending operation, but it is required for the function to succeed.

     GPGME_Exec_Error
          This value means that an error occurred when trying to spawn a child process.

     GPGME_Too_Many_Procs
          This value means that there are too many active backend processes.

     GPGME_Pipe_Error
          This value means that the creation of a pipe failed.

     GPGME_No_Recipients
          This value means that no valid recipients for a message have been set.

     GPGME_Invalid_Recipients
          This value means that some, but not all, recipients for a message have been invalid.

     GPGME_No_Data
          This value means that a GpgmeData object which was expected to have content was found empty.

     GPGME_Conflict
          This value means that a conflict of some sort occurred.

     GPGME_Not_Implemented
          This value indicates that the specific function (or operation) is not implemented.  This error should never happen.  It can only occur if you use certain values or configuration options which do not work, but for which we think that they should work at some later time.

     GPGME_Read_Error
          This value means that an I/O read operation failed.

     GPGME_Write_Error
          This value means that an I/O write operation failed.

     GPGME_Invalid_Type
          This value means that a user provided object was of a wrong or incompatible type.  Usually this refers to the type of a GpgmeData object.

     GPGME_Invalid_Mode
          This value means that a GpgmeData object has an incorrect mode of operation (for example, doesn't support output although it is attempted to use it as an output buffer).

     GPGME_File_Error
          This value means that a file I/O operation failed.  The value of errno contains the system error value.

     GPGME_Decryption_Failed
          This value indicates that a decryption operation was unsuccessful.

     GPGME_No_Passphrase
          This value means that the user did not provide a passphrase when requested.

     GPGME_Canceled
          This value means that the operation was canceled.

     GPGME_Invalid_Key
          This value means that a key was invalid.

     GPGME_Invalid_Engine
          This value means that the engine that implements the desired protocol is currently not available.  This can either be because the sources were configured to exclude support for this engine, or because the engine is not installed properly.

Error Strings
=============

 -- Function: const char * gpgme_strerror (GpgmeError ERR)
     The function gpgme_strerror returns a pointer to a statically allocated string containing a description of the error with the error value ERR.  This string can be used to output a diagnostic message to the user.

     The following example illustrates the use of gpgme_strerror:

          GpgmeCtx ctx;
          GpgmeError err = gpgme_new (&ctx);
          if (err)
            {
              fprintf (stderr, "%s: creating GpgME context failed: %s\n",
                       argv[0], gpgme_strerror (err));
              exit (1);
            }

Exchanging Data
***************

A lot of data has to be exchanged between the user and the crypto engine, like plaintext messages, ciphertext, signatures and information about the keys.  The technical details about exchanging the data information are completely abstracted by GPGME. The user provides and receives the data via GpgmeData objects, regardless of the communication protocol between GPGME and the crypto engine in use.

 -- Data type: GpgmeData
     The GpgmeData type is a handle for a container for generic data, which is used by GPGME to exchange data with the user.

Creating Data Buffers
=====================

 -- Function: GpgmeError gpgme_data_new (GpgmeData *DH)
     The function gpgme_data_new creates a new GpgmeData object and returns a handle for it in DH.  The data object is initially empty.

     The function returns GPGME_No_Error if the data object was successfully created, GPGME_Invalid_Value if DH is not a valid pointer, and GPGME_Out_Of_Core if not enough memory is available.

 -- Function: GpgmeError gpgme_data_new_from_mem (GpgmeData *DH, const char *BUFFER, size_t SIZE, int COPY)
     The function gpgme_data_new_from_mem creates a new GpgmeData object and fills it with SIZE bytes starting from BUFFER.

     If COPY is not zero, a private copy of the data is made.  If COPY is zero, the data is taken from the specified buffer as needed, and the user has to ensure that the buffer remains valid for the whole life span of the data object.

     The function returns GPGME_No_Error if the data object was successfully created, GPGME_Invalid_Value if DH or BUFFER is not a valid pointer, and GPGME_Out_Of_Core if not enough memory is available.

 -- Function: GpgmeError gpgme_data_new_from_file (GpgmeData *DH, const char *FILENAME, int COPY)
     The function gpgme_data_new_from_file creates a new GpgmeData object and fills it with the content of the file FILENAME.

     If COPY is not zero, the whole file is read in at initialization time and the file is not used anymore after that.  This is the only mode supported currently.  Later, a value of zero for COPY might cause all reads to be delayed until the data is needed, but this is not yet implemented.

     The function returns GPGME_No_Error if the data object was successfully created, GPGME_Invalid_Value if DH or FILENAME is not a valid pointer, GPGME_File_Error if an I/O operation fails, GPGME_Not_Implemented if CODE is zero, and GPGME_Out_Of_Core if not enough memory is available.

 -- Function: GpgmeError gpgme_data_new_from_filepart (GpgmeData *DH, const char *FILENAME, FILE *FP, off_t OFFSET, size_t LENGTH)
     The function gpgme_data_new_from_filepart creates a new GpgmeData object and fills it with a part of the file specified by FILENAME or FP.

     Exactly one of FILENAME and FP must be non-zero, the other must be zero.  The argument that is not zero specifies the file from which LENGTH bytes are read into the data object, starting from OFFSET.

     The function returns GPGME_No_Error if the data object was successfully created, GPGME_Invalid_Value if DH and exactly one of FILENAME and FP is not a valid pointer, GPGME_File_Error if an I/O operation fails, and GPGME_Out_Of_Core if not enough memory is available.

 -- Function: GpgmeError gpgme_data_new_with_read_cb (GpgmeData *DH, int (*READFUNC) (void *HOOK, char *BUFFER, size_t COUNT, size_t *NREAD), void *HOOK_VALUE)
     The function gpgme_data_new_with_read_cb creates a new GpgmeData object and uses the callback function 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 GPGME provides.  However, it can not be used to write data.

     The callback function receives HOOK_VALUE as its first argument whenever it is invoked.  It should return up to COUNT bytes in BUFFER, and return the number of bytes actually read in NREAD.  It may return 0 in NREAD if no data is currently available.  To indicate EOF the function should return with an error code of -1 and set NREAD to 0.  The callback function may support to reset its internal read pointer if it is invoked with BUFFER and NREAD being NULL and COUNT being 0.

     The function returns GPGME_No_Error if the data object was successfully created, GPGME_Invalid_Value if DH or READFUNC is not a valid pointer, and GPGME_Out_Of_Core if not enough memory is available.

Destroying Data Buffers
=======================

 -- Function: void gpgme_data_release (GpgmeData DH)
     The function gpgme_data_release destroys the data object with the handle DH.  It releases all associated resources that were not provided by the user in the first place.

 -- Function: char * gpgme_data_release_and_get_mem (GpgmeData DH, size_t *LENGTH)
     The function gpgme_data_release_and_get_mem is like gpgme_data_release, except that it returns the data buffer and its length that was provided by the object.

     The user has to release the buffer with free.  In case the user provided the data buffer in non-copy mode, a copy will be made for this purpose.

     In case an error returns, or there is no suitable data buffer that can be returned to the user, the function will return NULL.

Manipulating Data Buffers
=========================

 -- Function: GpgmeError gpgme_data_read (GpgmeData DH, char *BUFFER, size_t LENGTH, size_t *NREAD)
     The function gpgme_data_read reads up to LENGTH bytes from the data object with the handle DH into the space starting at BUFFER.  The actual amount read is returned in NREAD.

     If BUFFER is NULL, the function returns the amount of bytes available in NREAD without changing the read pointer. This is not supported by all types of data objects.  If this function is not supported, GPGME_Invalid_Type is returned.

     If the end of the data object is reached, the function returns GPGME_EOF and sets NREAD to zero.

     In all other cases, the function returns GPGME_No_Error if the operation was successfully performed and GPGME_Invalid_Value if DH is not a valid pointer.

 -- Function: GpgmeError gpgme_data_rewind (GpgmeData DH)
     The function gpgme_data_rewind resets the read pointer of the data object with the handle DH, so that a subsequent gpgme_data_read operation starts at the beginning of the data.

     The function returns GPGME_No_Error if the operation was successfully performed, GPGME_Not_Implemented if the operation is not supported (for example, by a read callback function supplied by the user) and GPGME_Invalid_Value if DH is not a valid pointer.

 -- Function: GpgmeError gpgme_data_write (GpgmeData DH, const char *BUFFER, size_t LENGTH)
     The function gpgme_data_write writes LENGTH bytes starting from BUFFER into the data object with the handle DH at the current write position.

     The function returns GPGME_No_Error if the operation was successfully performed, GPGME_Invalid_Value if DH or BUFFER is not a valid pointer, GPGME_Invalid_Type or GPGME_Invalid_Mode if the data object type does not support writing, and GPGME_Out_Of_Core if not enough memory is available.

 -- Data type: enum GpgmeDataType
     The GpgmeDataType type specifies the type of a GpgmeData object. The following data types are available:

     GPGME_DATA_TYPE_NONE
          This specifies that the type is not yet determined.

     GPGME_DATA_TYPE_MEM
          This specifies that the data is stored in memory.

     GPGME_DATA_TYPE_FD
          This type is not implemented.

     GPGME_DATA_TYPE_FILE
          This type is not implemented.

     GPGME_DATA_TYPE_CB
          This type specifies that the data is provided by a callback function implemented by the user.

 -- Function: GpgmeDataType gpgme_data_get_type (GpgmeData DH)
     The function gpgme_data_get_type returns the type of the data object with the handle DH.  If DH is not a valid pointer, GPGME_DATA_TYPE_NONE is returned.

Contexts
********

All cryptographic operations in GPGME are performed within a context, which contains the internal state of the operation as well as configuration parameters.  By using several contexts you can run several cryptographic operations in parallel, with different configuration.

 -- Data type: GpgmeCtx
     The GpgmeCtx type is a handle for a GPGME context, which is used to hold the configuration, status and result of cryptographic operations.

Creating Contexts
=================

 -- Function: GpgmeError gpgme_new (GpgmeCtx *CTX)
     The function gpgme_data_new creates a new GpgmeCtx object and returns a handle for it in CTX.

     The function returns GPGME_No_Error if the context was successfully created, GPGME_Invalid_Value if CTX is not a valid pointer, and GPGME_Out_Of_Core if not enough memory is available.

Destroying Contexts
===================

 -- Function: void gpgme_release (GpgmeCtx CTX)
     The function gpgme_release destroys the context with the handle CTX and releases all associated resources.

Context Attributes
==================

Protocol Selection
------------------

 -- Function: GpgmeError gpgme_set_protocol (GpgmeCtx CTX, GpgmeProtocol PROTO)
     The function gpgme_set_protocol sets the protocol used within the context CTX to PROTO.  All crypto operations will be performed by the crypto engine configured for that protocol. See Protocols and Engines.

     Setting the protocol with gpgme_set_protocol does not check if the crypto engine for that protocol is available and installed correctly.  See Engine Version Check.

     The function returns GPGME_No_Error if the protocol could be set successfully, and GPGME_Invalid_Value if PROTOCOL is not a valid protocol.

ASCII Armor
-----------

 -- Function: void gpgme_set_armor (GpgmeCtx CTX, int YES)
     The function gpgme_set_armor specifies if the output should be ASCII armored.  By default, output is not ASCII armored.

     ASCII armored output is disabled if YES is zero, and enabled otherwise.

 -- Function: int gpgme_get_armor (GpgmeCtx CTX)
     The function gpgme_get_armor returns 1 if the output is ASCII armored, and 0 if it is not, or if CTX is not a valid pointer.

Text Mode
---------

 -- Function: 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.

 -- Function: 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
---------------------

 -- Function: 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.

 -- Function: 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
----------------

 -- Function: 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.

 -- Function: 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 test 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.

 -- Function: 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.

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.

 -- Function: 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.

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

 -- Function: 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.

 -- Function: 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.

 -- Function: 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.

 -- Function: 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);
       }

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

 -- Function: 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 is 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.

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

 -- Function: 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 occurs more than once in the key, the index is specified by IDX.  This applies to attributes of sub keys and user IDs.  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.

 -- Function: 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 occurs more than once in the key, the index is specified by IDX.  This applies to attributes of sub keys and user IDs.  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 Keys
-----------------

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

 -- Function: void gpgme_key_unref (GpgmeKey KEY)
 -- Function: 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
---------------

 -- Function: GpgmeError gpgme_op_genkey (GpgmeCtx CTX, const char *PARMS, GpgmeData PUBKEY, GpgmeData SECKEY)
     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.

     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.

 -- Function: 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
--------------

 -- Function: 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.

 -- Function: 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
--------------

 -- Function: 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.

 -- Function: 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.

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

 -- Function: 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.

     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.

 -- Function: 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
-------------------

 -- Function: 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.

 -- Function: 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.

 -- Function: 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.

 -- Function: 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.  If the attribute occurs more than once in the trust items, the index is specified by IDX.  However, currently no such attributes exists, so IDX should be 0.  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.

 -- Function: 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
------------------------

 -- Function: 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
-------

 -- Function: 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.

 -- Function: 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.

Verify
------

 -- Data type: enum GpgmeSigStat
     The GpgmeSigStat type holds the result of a signature check, or the combined result of all signatures.  The following results are possible:

     GPGME_SIG_STAT_NONE
          This status should not occur in normal operation.

     GPGME_SIG_STAT_GOOD
          This status indicates that the signature is valid.  For the combined result this status means that all signatures are valid.

     GPGME_SIG_STAT_BAD
          This status indicates that the signature is invalid.  For the combined result this status means that all signatures are invalid.

     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.

     GPGME_SIG_STAT_NOSIG
          This status indicates that the signature data provided was not a real signature.

     GPGME_SIG_STAT_ERROR
          This status indicates that there was some other error which prevented the signature verification.

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

 -- Function: GpgmeError gpgme_op_verify (GpgmeCtx CTX, GpgmeData SIG, GpgmeData PLAIN, GpgmeSigStat *R_STAT)
     The function gpgme_op_verify verifies that the signature in the data object SIG is a valid signature.  If PLAIN is initialized with plaintext data, it is assumed that SIG is a detached signature, and its validity for the plaintext given in PLAIN is verified.  If PLAIN is an uninitialized data object, it is assumed that SIG is a normal (or cleartext) signature, and the plaintext is available in PLAIN after successful verification.

     The combined status of all signatures is returned in R_STAT. The results of the individual signature verifications can be retrieved with gpgme_get_sig_status and gpgme_get_sig_key.

     The function returns GPGME_No_Error if the operation could be completed successfully, GPGME_Invalid_Value if CTX, SIG, PLAIN or R_STAT is not a valid pointer, GPGME_No_Data if SIG does not contain any data to verify, and passes through any errors that are reported by the crypto engine support routines.

 -- Function: GpgmeError gpgme_op_verify_start (GpgmeCtx CTX, GpgmeData SIG, GpgmeData PLAIN)
     The function gpgme_op_verify_start initiates a gpgme_op_verify 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 CTX, SIG, PLAIN or R_STAT is not a valid pointer, and GPGME_No_Data if SIG or PLAIN does not contain any data to verify.

 -- Function: const char * gpgme_get_sig_status (GpgmeCtx CTX, int IDX, GpgmeSigStat *R_STAT, time_t *R_CREATED)
     The function gpgme_get_sig_status receives information about a signature after the gpgme_op_verify or gpgme_op_verify_decrypt operation.  A single detached signature can contain signatures by more than one key.  The IDX specifies which signature's information should be retrieved, starting from 0.

     The status of the signature will be returned in R_STAT if it is not NULL.  The creation time stamp of the signature will be returned in R_CREATED if it is not NULL.

     The function returns a statically allocated string that contains the fingerprint of the key which signed the plaintext, or NULL if CTX is not a valid pointer, the operation is still pending, or no verification could be performed.

 -- Function: const char * gpgme_get_sig_key (GpgmeCtx CTX, int IDX, GpgmeSigKey *R_STAT)
     The function gpgme_get_sig_status receives a GpgmeKey object for the key which was used to verify the signature after the gpgme_op_verify or gpgme_op_verify_decrypt operation.  A single detached signature can contain signatures by more than one key. The IDX specifies which signature's information should be retrieved, starting from 0.  The key will have on reference for the user.

     The function is a convenient way to retrieve the keys belonging to the fingerprints returned by gpgme_get_sig_status.

     The function returns GPGME_No_Error if the key could be returned, GPGME_Invalid_Value if R_KEY is not a valid pointer, GPGME_Invalid_Key if the fingerprint is not valid, GPGME_EOF if IDX is too large, or some other error value if a problem occurred requesting the key.

 -- Function: char * gpgme_get_notation (GpgmeCtx CTX)
     The function gpgme_get_notation can be used to retrieve notation data from the last signature check in the context CTX.

     If there is notation data available from the last signature check, this function may be used to return this notation data as a string. The string is an XML representation of that data embedded in a <notation> container.  The user has to release the string with free.

     The function returns a string if the notation data is available or NULL if there is no such data available.

Decrypt and Verify
------------------

 -- Function: GpgmeError gpgme_op_decrypt_verify (GpgmeCtx CTX, GpgmeData CIPHER, GpgmeData PLAIN, GpgmeSigStat *R_STAT)
     The function gpgme_op_decrypt_verify decrypts the ciphertext in the data object CIPHER and stores it into the data object PLAIN.  If CIPHER contains signatures, they will be verified and their combined status will be returned in R_STAT.

     After the operation completed, gpgme_op_get_sig_status and gpgme_op_get_sig_key can be used to retrieve more information about the signatures.

     The function returns GPGME_No_Error if the ciphertext could be decrypted successfully, GPGME_Invalid_Value if CTX, CIPHER, PLAIN or R_STAT 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.

 -- Function: GpgmeError gpgme_op_decrypt_verify (GpgmeCtx CTX, GpgmeData CIPHER, GpgmeData PLAIN)
     The function gpgme_op_decrypt_verify_start initiates a gpgme_op_decrypt_verify 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 CTX, CIPHER, PLAIN or R_STAT is not a valid pointer, and GPGME_No_Data if CIPHER does not contain any data to decrypt.

Sign
----

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

Selecting Signers
.................

 -- Function: void gpgme_signers_clear (GpgmeCtx CTX)
     The function gpgme_signers_clear releases a reference for each key on the signers list and removes the list of signers from the context CTX.

     Every context starts with an empty list.

 -- Function: GpgmeError gpgme_signers_add (GpgmeCtx CTX, const GpgmeKey KEY)
     The function gpgme_signers_add adds the key KEY to the list of signers in the context CTX.

     One reference for the key is consumed.

 -- Function: GpgmeKey gpgme_signers_enum (const GpgmeCtx CTX, int SEQ)
     The function gpgme_signers_enum returns the SEQth key in the list of signers in the context CTX.  An additional reference is acquired for the user.

     If SEQ is out of range, NULL is returned.

Creating a Signature
....................

 -- Data type: enum GpgmeSigMode
     The GpgmeSigMode type is used to specify the desired type of a signature.  The following modes are available:

     GPGME_SIG_MODE_NORMAL
          A normal signature is made, the output includes the plaintext and the signature.

     GPGME_SIG_MODE_DETACH
          A detached signature is made.

     GPGME_SIG_MODE_CLEAR
          A clear text signature is made.  The ASCII armor and text mode settings of the context are ignored.

 -- Function: GpgmeError gpgme_op_sign (GpgmeCtx CTX, GpgmeData PLAIN, GpgmeData SIG, GpgmeSigMode MODE)
     The function gpgme_op_sign creates a signature for the text in the data object PLAIN and returns it in the data object SIG.  The type of the signature created is determined by the ASCII armor and text mode attributes set for the context CTX and the requested signature mode MODE.

     More information about the signatures is available with gpgme_get_op_info.  See Detailed Results.

     If an S/MIME signed message is created using the CMS crypto engine, the number of certificates to include in the message can be specified with gpgme_set_include_certs.  See Included Certificates.

     The function returns GPGME_No_Error if the signature could be created successfully, GPGME_Invalid_Value if CTX, PLAIN or SIG is not a valid pointer, GPGME_No_Data if the signature could not be created, 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.

 -- Function: GpgmeError gpgme_op_sign (GpgmeCtx CTX, GpgmeData PLAIN, GpgmeData SIG, GpgmeSigMode MODE)
     The function gpgme_op_sign_start initiates a gpgme_op_sign 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 CTX, PLAIN or SIG is not a valid pointer.

Encrypt
-------

One plaintext can be encrypted for several recipients at the same time.  The list of recipients is created independently of any context, and then passed to the encryption operation.

Selecting Recipients
....................

 -- Data type: GpgmeRecipients
     The GpgmeRecipients type is a handle for a set of recipients that can be used in an encryption process.

 -- Function: GpgmeError gpgme_recipients_new (GpgmeRecipients *R_RSET)
     The function gpgme_recipients_new creates a new, empty set of recipients and returns a handle for it in R_RSET.

     The function returns GPGME_No_Error if the recipient set could be created successfully, and GPGME_Out_Of_Core if not enough memory was available.

 -- Function: void gpgme_recipients_release (GpgmeRecipients RSET)
     The function gpgme_recipients_release destroys the set of recipients RSET and releases all associated resources.

 -- Function: GpgmeError gpgme_recipients_add_name (GpgmeRecipients RSET, const char *NAME)
     The function gpgme_recipients_add_name adds the recipient NAME to the set of recipients RSET.  This is equivalent to gpgme_recipients_add_name_with_validity with a validity of GPGME_VALIDITY_UNKNOWN.

     The function returns GPGME_No_Error if the recipient was added successfully, GPGME_Invalid_Value if RSET or NAME is not a valid pointer, and GPGME_Out_Of_Core if not enough memory is available.

 -- Function: GpgmeError gpgme_recipients_add_name_with_validity (GpgmeRecipients RSET, const char *NAME, GpgmeValidity VAL)
     The function gpgme_recipients_add_name_with_validity adds the recipient NAME with the validity VAL to the set of recipients RSET.  If the validity is not known, the function gpgme_recipients_add_name can be used. See Information About Keys, for the possible values for VAL.

     The function returns GPGME_No_Error if the recipient was added successfully, GPGME_Invalid_Value if RSET or NAME is not a valid pointer, and GPGME_Out_Of_Core if not enough memory is available.

 -- Function: unsigned int gpgme_recipients_count (const GPGMERECIPIENTS RSET)
     The function gpgme_recipients_count returns the number of recipients in the set RSET.

 -- Function: GpgmeError gpgme_recipients_enum_open (const GpgmeRecipients RSET, void **ITER)
     The function gpgme_recipients_enum_open creates a new iterator ITER that can be used to walk through the set of recipients in RSET, using gpgme_recipients_enum_read.

     If the iterator is not needed anymore, it can be closed with gpgme_recipients_enum_close.

     The function returns GPGME_No_Error if the enumerator was successfully created and GPGME_Invalid_Value if RSET or ITER is not a valid pointer.

 -- Function: const char * gpgme_recipients_enum_read (const GpgmeRecipients RSET, void **ITER)
     The function gpgme_recipients_enum_read returns a string containing the name of the next recipient in the set RSET for the iterator ITER.  The string is valid as long as RSET is valid or the function is called the next time with the same recipient set and iterator, whatever is earlier.

 -- Function: GpgmeError gpgme_recipients_enum_close (const GpgmeRecipients RSET, void **ITER)
     The function gpgme_recipients_enum_close releases the iterator ITER for the recipient set RSET.

Encrypting a Plaintext
......................

 -- Function: GpgmeError gpgme_op_encrypt (GpgmeCtx CTX, GpgmeRecipients RSET, GpgmeData PLAIN, GpgmeData CIPHER)
     The function gpgme_op_encrypt encrypts the plaintext in the data object PLAIN for the recipients RSET and stores the ciphertext in the data object CIPHER.  The type of the ciphertext created is determined by the ASCII armor and text mode attributes set for the context CTX.

     If GPGME_Invalid_Recipients is returned, some recipients in RSET are invalid, but not all.  In this case the plaintext is encrypted for all valid recipients and returned in CIPHER.  More information about the invalid recipients is available with gpgme_get_op_info.  See Detailed Results.

     If RECP is NULL, symmetric rather than public key encryption is performed.  Symmetrically encrypted cipher text can be deciphered with gpgme_op_decrypt.  Note that in this case the crypto backend needs to retrieve a passphrase from the user. Symmetric encryption is currently only supported for the OpenPGP crypto backend.

     The function returns GPGME_No_Error if the ciphertext could be created successfully, GPGME_Invalid_Value if CTX, RSET, PLAIN or CIPHER is not a valid pointer, GPGME_No_Recipients if RSET does not contain any valid recipients, GPGME_Invalid_Recipients if RSET contains some invalid recipients, 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.

 -- Function: GpgmeError gpgme_op_encrypt_start (GpgmeCtx CTX, GpgmeRecipients RSET, GpgmeData PLAIN, GpgmeData CIPHER)
     The function gpgme_op_encrypt_start initiates a gpgme_op_encrypt 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 CTX, RSET, PLAIN or CIPHER is not a valid pointer, and GPGME_No_Recipients if RSET does not contain any valid recipients.

 -- Function: GpgmeError gpgme_op_encrypt_sign (GpgmeCtx CTX, GpgmeRecipients RSET, GpgmeData PLAIN, GpgmeData CIPHER)
     The function gpgme_op_encrypt_sign does a combined encrypt and sign operation.  It is used like gpgme_op_encrypt, but the ciphertext also contains signatures for the signers listed in CTX.

     The combined encrypt and sign operation is currently only available for the OpenPGP crypto engine.

 -- Function: GpgmeError gpgme_op_encrypt_sign_start (GpgmeCtx CTX, GpgmeRecipients RSET, GpgmeData PLAIN, GpgmeData CIPHER)
     The function gpgme_op_encrypt_sign_start initiates a gpgme_op_encrypt_sign 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 CTX, RSET, PLAIN or CIPHER is not a valid pointer, and GPGME_No_Recipients if RSET does not contain any valid recipients.

Detailed Results
----------------

 -- Function: char * gpgme_get_op_info (GpgmeCtx CTX, int RESERVED)
     The function gpgme_get_op_info retrieves more information about the last crypto operation.

     The function returns a string in the XML format.  The user has to release the string with free.

     Here is a sample of the information that might be returned:

          <GnupgOperationInfo>
            <signature>
              <detached/> <!-- or cleartext or standard -->
              <algo>17</algo>
              <hashalgo>2</hashalgo>
              <micalg>pgp-sha1</micalg>
              <sigclass>01</sigclass>
              <created>9222222</created>
              <fpr>121212121212121212</fpr>
            </signature>
          </GnupgOperationInfo>

     Currently, the only operations that return additional information are encrypt, sign and import.  See Encrypt, see Sign, (Importing Keys.

     The function returns a string or NULL if no such data is available.

Run Control
===========

Some basic support for running operations asynchronously is available in GPGME.  You can use it to set up a context completely up to initiating the desired operation, but delay performing it to a later point.

Waiting For Completion
----------------------

 -- Function: GpgmeCtx gpgme_wait (GpgmeCtx CTX, GpgmeError *STATUS, int HANG)
     The function gpgme_wait does continue the pending operation within the context CTX.  In particular, it ensures the data exchange between GPGME and the crypto backend and watches over the run time status of the backend process.

     If HANG is true, the function does not return until the operation is completed or cancelled.  Otherwise the function will not block for a long time.

     The error status of the finished operation is returned in STATUS.

     The CTX argument can be NULL.  In that case, gpgme_wait waits for any context to complete its operation.

     The function returns the CTX of the context which has finished the operation.

Cancelling an Operation
-----------------------

 -- Function: void gpgme_cancel (GpgmeCtx CTX)
     The function gpgme_cancel tries to cancel the pending operation.  The function gpgme_wait might notice the cancellation flag and return.  It is currently not guaranteed to work under all circumstances.  It's current primary purpose is to prevent asking for a passphrase again in the passphrase callback.

Hooking Up Into Idle Time
-------------------------

 -- Data type: void (*GpgmeIdleFunc) (void)
     The GpgmeIdleFunc type is the type of functions usable as an idle function that can be registered with gpgme_register_idle.

 -- Function: GpgmeIdleFunc gpgme_register_idle (GpgmeIdleFunc IDLE)
     The function gpgme_register_idle can be used to register IDLE as the idle function.

     IDLE will be called whenever GPGME thinks that it is idle and time can better be spent elsewhere.  Setting IDLE to NULL disables use of the idle function (this is the default).

     The function returns the old idle function, or NULL if none was registered yet.

     [file gpl.texi not included]

     [file fdl.texi not included]