diff options
| author | Anas Nashif <anas.nashif@intel.com> | 2013-02-19 08:22:18 -0800 |
|---|---|---|
| committer | Anas Nashif <anas.nashif@intel.com> | 2013-02-19 08:22:18 -0800 |
| commit | 26fb537f9cf011eaeaf975adcad5e8e9154d04fd (patch) | |
| tree | ddc2171273fca8b730b9c496e1b5ed3b01878577 /doc/gpgme.info-1 | |
| download | gpgme-26fb537f9cf011eaeaf975adcad5e8e9154d04fd.tar.gz gpgme-26fb537f9cf011eaeaf975adcad5e8e9154d04fd.tar.bz2 gpgme-26fb537f9cf011eaeaf975adcad5e8e9154d04fd.zip | |
Imported Upstream version 1.3.2upstream/1.3.2
Diffstat (limited to 'doc/gpgme.info-1')
| -rw-r--r-- | doc/gpgme.info-1 | 6615 |
1 files changed, 6615 insertions, 0 deletions
diff --git a/doc/gpgme.info-1 b/doc/gpgme.info-1 new file mode 100644 index 0000000..35b948a --- /dev/null +++ b/doc/gpgme.info-1 @@ -0,0 +1,6615 @@ +This is /home/wk/w/gpgme/doc/gpgme.info, produced by makeinfo version +4.13 from /home/wk/w/gpgme/doc/gpgme.texi. + +INFO-DIR-SECTION GNU Libraries +START-INFO-DIR-ENTRY +* GPGME: (gpgme). Adding support for cryptography to your program. +END-INFO-DIR-ENTRY + + Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2010 g10 +Code GmbH. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 3 of the + License, or (at your option) any later version. The text of the + license can be found in the section entitled "Copying". + + This document is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + + This file documents the GPGME library. + + This is Edition 1.3.2, last updated 2 May 2012, of `The `GnuPG Made +Easy' Reference Manual', for Version 1.3.2. + + Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2010 g10 +Code GmbH. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 3 of the + License, or (at your option) any later version. The text of the + license can be found in the section entitled "Copying". + + This document is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + + +File: gpgme.info, Node: Top, Next: Introduction, Up: (dir) + +Main Menu +********* + +This is Edition 1.3.2, last updated 2 May 2012, of `The `GnuPG Made +Easy' Reference Manual', for Version 1.3.2 of the GPGME library. + +* Menu: + +* Introduction:: How to use this manual. +* Preparation:: What you should do before using the library. +* Protocols and Engines:: Supported crypto protocols. +* Algorithms:: Supported algorithms. +* Error Handling:: Error numbers and their meanings. +* Exchanging Data:: Passing data to and from GPGME. +* Contexts:: Handling GPGME contexts. + +Appendices + +* UI Server Protocol:: The GnuPG UI Server Protocol. + +* Library Copying:: The GNU Lesser General Public License says + how you can copy and share `GnuPG Made Easy'. +* Copying:: The GNU General Public License says how you + can copy and share this manual. + +Indices + +* Concept Index:: Index of concepts and programs. +* Function and Data Index:: Index of functions, variables and data types. + + + --- The Detailed Node Listing --- + +Introduction + +* Getting Started:: Purpose of the manual, and how to use it. +* Features:: Reasons to install and use GPGME. +* Overview:: Basic architecture of the GPGME library. + +Preparation + +* Header:: What header file you need to include. +* Building the Source:: Compiler options to be used. +* Largefile Support (LFS):: How to use GPGME with LFS. +* Using Automake:: Compiler options to be used the easy way. +* Using Libtool:: Avoiding compiler options entirely. +* Library Version Check:: Getting and verifying the library version. +* Signal Handling:: How GPGME affects signal handling. +* Multi Threading:: How GPGME can be used in an MT environment. + +Protocols and Engines + +* Engine Version Check:: Verifying the engine version. +* Engine Information:: Obtaining more information about the engines. +* Engine Configuration:: Changing the engine configuration. +* OpenPGP:: Support for the OpenPGP protocol. +* Cryptographic Message Syntax:: Support for the CMS. + +Algorithms + +* Public Key Algorithms:: A list of all public key algorithms. +* Hash Algorithms:: A list of all hash algorithms. + +Error Handling + +* Error Values:: The error value and what it means. +* Error Codes:: A list of important error codes. +* Error Sources:: A list of important error sources. +* Error Strings:: How to get a descriptive string from a value. + +Exchanging Data + +* Creating Data Buffers:: Creating new data buffers. +* Destroying Data Buffers:: Releasing data buffers. +* Manipulating Data Buffers:: Operations on data buffers. + +Creating Data Buffers + +* Memory Based Data Buffers:: Creating memory based data buffers. +* File Based Data Buffers:: Creating file based data buffers. +* Callback Based Data Buffers:: Creating callback based data buffers. + +Manipulating Data Buffers + +* Data Buffer I/O Operations:: I/O operations on data buffers. +* Data Buffer Meta-Data:: Meta-data manipulation of data buffers. + +Contexts + +* Creating Contexts:: Creating new GPGME contexts. +* Destroying Contexts:: Releasing GPGME contexts. +* Result Management:: Managing the result of crypto operations. +* Context Attributes:: Setting properties of a context. +* Key Management:: Managing keys with GPGME. +* Trust Item Management:: Managing trust items with GPGME. +* Crypto Operations:: Using a context for cryptography. +* Run Control:: Controlling how operations are run. + +Context Attributes + +* Protocol Selection:: Selecting the protocol used by a context. +* Crypto Engine:: Configuring the crypto engine. +* ASCII Armor:: Requesting ASCII armored output. +* Text Mode:: Choosing canonical text mode. +* Included Certificates:: Including a number of certificates. +* Key Listing Mode:: Selecting key listing mode. +* Passphrase Callback:: Getting the passphrase from the user. +* Progress Meter Callback:: Being informed about the progress. +* Locale:: Setting the locale of a context. + +Key Management + +* Listing Keys:: Browsing the list of available keys. +* Information About Keys:: Requesting detailed information about keys. +* Key Signatures:: Listing the signatures on a key. +* Manipulating Keys:: Operations on keys. +* Generating Keys:: Creating new key pairs. +* Exporting Keys:: Retrieving key data from the key ring. +* Importing Keys:: Adding keys to the key ring. +* Deleting Keys:: Removing keys from the key ring. +* Advanced Key Editing:: Advanced key edit operation. + +Trust Item Management + +* Listing Trust Items:: Browsing the list of available trust items. +* Information About Trust Items:: Requesting information about trust items. +* Manipulating Trust Items:: Operations on trust items. + +Crypto Operations + +* Decrypt:: Decrypting a ciphertext. +* Verify:: Verifying a signature. +* Decrypt and Verify:: Decrypting a signed ciphertext. +* Sign:: Creating a signature. +* Encrypt:: Encrypting a plaintext. + +Sign + +* Selecting Signers:: How to choose the keys to sign with. +* Creating a Signature:: How to create a signature. +* Signature Notation Data:: How to add notation data to a signature. + +Encrypt + +* Encrypting a Plaintext:: How to encrypt a plaintext. + +Run Control + +* Waiting For Completion:: Waiting until an operation is completed. +* Using External Event Loops:: Advanced control over what happens when. +* Cancellation:: How to end pending operations prematurely. + +Using External Event Loops + +* I/O Callback Interface:: How I/O callbacks are registered. +* Registering I/O Callbacks:: How to use I/O callbacks for a context. +* I/O Callback Example:: An example how to use I/O callbacks. +* I/O Callback Example GTK+:: How to integrate GPGME in GTK+. +* I/O Callback Example GDK:: How to integrate GPGME in GDK. +* I/O Callback Example Qt:: How to integrate GPGME in Qt. + + +File: gpgme.info, Node: Introduction, Next: Preparation, Prev: Top, Up: Top + +1 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 public key 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). + +* Menu: + +* Getting Started:: Purpose of the manual, and how to use it. +* Features:: Reasons to install and use GPGME. +* Overview:: Basic architecture of the GPGME library. + + +File: gpgme.info, Node: Getting Started, Next: Features, Up: Introduction + +1.1 Getting Started +=================== + +This manual 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. + + +File: gpgme.info, Node: Features, Next: Overview, Prev: Getting Started, Up: Introduction + +1.2 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 Lesser General Public License (*note Library 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. + + +File: gpgme.info, Node: Overview, Prev: Features, Up: Introduction + +1.3 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. + + With some precautions, GPGME can be used in a multi-threaded +environment, although it is not completely thread safe and thus needs +the support of the application. + + +File: gpgme.info, Node: Preparation, Next: Protocols and Engines, Prev: Introduction, Up: Top + +2 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. + +* Menu: + +* Header:: What header file you need to include. +* Building the Source:: Compiler options to be used. +* Largefile Support (LFS):: How to use GPGME with LFS. +* Using Automake:: Compiler options to be used the easy way. +* Using Libtool:: Avoiding compiler options entirely. +* Library Version Check:: Getting and verifying the library version. +* Signal Handling:: How GPGME affects signal handling. +* Multi Threading:: How GPGME can be used in an MT environment. + + +File: gpgme.info, Node: Header, Next: Building the Source, Up: Preparation + +2.1 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 and data +types and `GPGME_*' for other symbols. Symbols internal to GPGME take +the form `_gpgme_*' and `_GPGME_*'. + + Because GPGME makes use of the GPG Error library, using GPGME will +also use the `GPG_ERR_*' name space directly, and the `gpg_err*' and +`gpg_str*' name space indirectly. + + +File: gpgme.info, Node: Building the Source, Next: Largefile Support (LFS), Prev: Header, Up: Preparation + +2.2 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 compiler 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` + + If you want to link to one of the thread-safe versions of GPGME, you +must specify the `--thread' option before any other option to select +the thread package you want to link with. Supported thread packages +are `--thread=pth' and `--thread=pthread'. + + +File: gpgme.info, Node: Largefile Support (LFS), Next: Using Automake, Prev: Building the Source, Up: Preparation + +2.3 Largefile Support (LFS) +=========================== + +GPGME is compiled with largefile support by default, if it is available +on the system. This means that GPGME supports files larger than two +gigabyte in size, if the underlying operating system can. On some +systems, largefile support is already the default. On such systems, +nothing special is required. However, some systems provide only +support for files up to two gigabyte in size by default. Support for +larger file sizes has to be specifically enabled. + + To make a difficult situation even more complex, such systems provide +two different types of largefile support. You can either get all +relevant functions replaced with alternatives that are largefile +capable, or you can get new functions and data types for largefile +support added. Those new functions have the same name as their +smallfile counterparts, but with a suffix of 64. + + An example: The data type `off_t' is 32 bit wide on GNU/Linux PC +systems. To address offsets in large files, you can either enable +largefile support add-on. Then a new data type `off64_t' is provided, +which is 64 bit wide. Or you can replace the existing `off_t' data +type with its 64 bit wide counterpart. All occurences of `off_t' are +then automagically replaced. + + As if matters were not complex enough, there are also two different +types of file descriptors in such systems. This is important because +if file descriptors are exchanged between programs that use a different +maximum file size, certain errors must be produced on some file +descriptors to prevent subtle overflow bugs from occuring. + + As you can see, supporting two different maximum file sizes at the +same time is not at all an easy task. However, the maximum file size +does matter for GPGME, because some data types it uses in its +interfaces are affected by that. For example, the `off_t' data type is +used in the `gpgme_data_seek' function, to match its POSIX counterpart. +This affects the call-frame of the function, and thus the ABI of the +library. Furthermore, file descriptors can be exchanged between GPGME +and the application. + + For you as the user of the library, this means that your program must +be compiled in the same file size mode as the library. Luckily, there +is absolutely no valid reason for new programs to not enable largefile +support by default and just use that. The compatibility modes (small +file sizes or dual mode) can be considered an historic artefact, only +useful to allow for a transitional period. + + GPGME is compiled using largefile support by default. This means +that your application must do the same, at least as far as it is +relevant for using the `gpgme.h' header file. All types in this header +files refer to their largefile counterparts, if they are different from +any default types on the system. + + You can enable largefile support, if it is different from the default +on the system the application is compiled on, by using the Autoconf +macro `AC_SYS_LARGEFILE'. If you do this, then you don't need to worry +about anything else: It will just work. In this case you might also +want to use `AC_FUNC_FSEEKO' to take advantage of some new interfaces, +and `AC_TYPE_OFF_T' (just in case). + + If you do not use Autoconf, you can define the preprocessor symbol +`_FILE_OFFSET_BITS' to 64 _before_ including any header files, for +example by specifying the option `-D_FILE_OFFSET_BITS=64' on the +compiler command line. You will also want to define the preprocessor +symbol `LARGEFILE_SOURCE' to 1 in this case, to take advantage of some +new interfaces. + + If you do not want to do either of the above, you probably know +enough about the issue to invent your own solution. Just keep in mind +that the GPGME header file expects that largefile support is enabled, +if it is available. In particular, we do not support dual mode +(`_LARGEFILE64_SOURCE'). + + +File: gpgme.info, Node: Using Automake, Next: Using Libtool, Prev: Largefile Support (LFS), Up: Preparation + +2.4 Using Automake +================== + +It is much easier if you use GNU Automake instead of writing your own +Makefiles. If you do that you do not have to worry about finding and +invoking the `gpgme-config' script at all. GPGME provides an extension +to Automake that does all the work for you. + + -- Macro: AM_PATH_GPGME ([MINIMUM-VERSION], [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND]) + -- Macro: AM_PATH_GPGME_PTH ([MINIMUM-VERSION], [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND]) + -- Macro: AM_PATH_GPGME_PTHREAD ([MINIMUM-VERSION], [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND]) + Check whether GPGME (at least version MINIMUM-VERSION, if given) + exists on the host system. If it is found, execute + ACTION-IF-FOUND, otherwise do ACTION-IF-NOT-FOUND, if given. + + Additionally, the function defines `GPGME_CFLAGS' to the flags + needed for compilation of the program to find the `gpgme.h' header + file, and `GPGME_LIBS' to the linker flags needed to link the + program to the GPGME library. + + `AM_PATH_GPGME_PTH' checks for the version of GPGME that can be + used with GNU Pth, and defines `GPGME_PTH_CFLAGS' and + `GPGME_PTH_LIBS'. + + `AM_PATH_GPGME_PTHREAD' checks for the version of GPGME that can + be used with the native pthread implementation, and defines + `GPGME_PTHREAD_CFLAGS' and `GPGME_PTHREAD_LIBS'. + + You can use the defined Autoconf variables like this in your +`Makefile.am': + + AM_CPPFLAGS = $(GPGME_CFLAGS) + LDADD = $(GPGME_LIBS) + + +File: gpgme.info, Node: Using Libtool, Next: Library Version Check, Prev: Using Automake, Up: Preparation + +2.5 Using Libtool +================= + +The easiest way is to just use GNU Libtool. If you use libtool, and +link to `libgpgme.la', `libgpgme-pth.la' or `libgpgme-pthread.la' +respectively, everything will be done automatically by Libtool. + + +File: gpgme.info, Node: Library Version Check, Next: Signal Handling, Prev: Using Libtool, Up: Preparation + +2.6 Library Version Check +========================= + + -- Function: const char * gpgme_check_version + (const char *REQUIRED_VERSION) + The function `gpgme_check_version' has four 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. The last purpose is to run selftests. + + As a side effect for W32 based systems, the socket layer will get + initialized. + + 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. + + If a selftest fails, the function may still succeed. Selftest + errors are returned later when invoking `gpgme_new', so that a + detailed error code can be returned (historically, + `gpgme_check_version' does not return a detailed error code). + + After initializing GPGME, you should set the locale information to +the locale required for your output terminal. This locale information +is needed for example for the curses and Gtk pinentry. Here is an +example of a complete initialization: + + #include <locale.h> + #include <gpgme.h> + + void + init_gpgme (void) + { + /* Initialize the locale environment. */ + setlocale (LC_ALL, ""); + gpgme_check_version (NULL); + gpgme_set_locale (NULL, LC_CTYPE, setlocale (LC_CTYPE, NULL)); + #ifdef LC_MESSAGES + gpgme_set_locale (NULL, LC_MESSAGES, setlocale (LC_MESSAGES, NULL)); + #endif + } + + Note that you are highly recommended to initialize the locale +settings like this. GPGME can not do this for you because it would not +be thread safe. The conditional on LC_MESSAGES is only necessary for +portability to W32 systems. + + +File: gpgme.info, Node: Signal Handling, Next: Multi Threading, Prev: Library Version Check, Up: Preparation + +2.7 Signal Handling +=================== + +The GPGME library communicates with child processes (the crypto +engines). If a child process dies unexpectedly, for example due to a +bug, or system problem, a `SIGPIPE' signal will be delivered to the +application. The default action is to abort the program. To protect +against this, `gpgme_check_version' sets the `SIGPIPE' signal action to +`SIG_IGN', which means that the signal will be ignored. + + GPGME will only do that if the signal action for `SIGPIPE' is +`SIG_DEF' at the time `gpgme_check_version' is called. If it is +something different, `GPGME' will take no action. + + This means that if your application does not install any signal +handler for `SIGPIPE', you don't need to take any precautions. If you +do install a signal handler for `SIGPIPE', you must be prepared to +handle any `SIGPIPE' events that occur due to GPGME writing to a +defunct pipe. Furthermore, if your application is multi-threaded, and +you install a signal action for `SIGPIPE', you must make sure you do +this either before `gpgme_check_version' is called or afterwards. + + +File: gpgme.info, Node: Multi Threading, Prev: Signal Handling, Up: Preparation + +2.8 Multi Threading +=================== + +The GPGME library is not entirely thread-safe, but it can still be used +in a multi-threaded environment if some care is taken. If the +following requirements are met, there should be no race conditions to +worry about: + + * GPGME supports the thread libraries pthread and GNU Pth. The + support for this has to be enabled at compile time. GPGME will + automatically detect the location in which the thread libraries + are installed and activate the support for them at build time. + + Support for other thread libraries is very easy to add. Please + contact us if you have the need. + + * If you want to use GPGME with threads, you must link to the right + version of the library. The name of the right library is + `libgpgme-' followed by the name of the thread package you use. + For example, if you use GNU Pth, the right name is `libgpgme-pth'. + Use the Automake macros or `gpgme-config' program for simplicity. + + * The function `gpgme_check_version' must be called before any other + function in the library, because it initializes the thread support + subsystem in GPGME. To achieve this in multi-threaded programs, + you must synchronize the memory with respect to other threads that + also want to use GPGME. For this, it is sufficient to call + `gpgme_check_version' before creating the other threads using + GPGME(1). + + * Any `gpgme_data_t' and `gpgme_ctx_t' object must only be accessed + by one thread at a time. If multiple threads want to deal with + the same object, the caller has to make sure that operations on + that object are fully synchronized. + + * Only one thread at any time is allowed to call `gpgme_wait'. If + multiple threads call this function, the caller must make sure that + all invocations are fully synchronized. It is safe to start + asynchronous operations while a thread is running in gpgme_wait. + + * The function `gpgme_strerror' is not thread safe. You have to use + `gpgme_strerror_r' instead. + + ---------- Footnotes ---------- + + (1) At least this is true for POSIX threads, as `pthread_create' is +a function that synchronizes memory with respects to other threads. +There are many functions which have this property, a complete list can +be found in POSIX, IEEE Std 1003.1-2003, Base Definitions, Issue 6, in +the definition of the term "Memory Synchronization". For other thread +packages other, more relaxed or more strict rules may apply. + + +File: gpgme.info, Node: Protocols and Engines, Next: Algorithms, Prev: Preparation, Up: Top + +3 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 backend 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 gpgme_protocol_t + The `gpgme_protocol_t' 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. + + `GPGME_PROTOCOL_ASSUAN' + Under development. Please ask on <gnupg-devel@gnupg.org> for + help. + + `GPGME_PROTOCOL_G13' + Under development. Please ask on <gnupg-devel@gnupg.org> for + help. + + `GPGME_PROTOCOL_UISERVER' + Under development. Please ask on <gnupg-devel@gnupg.org> for + help. + + `GPGME_PROTOCOL_UNKNOWN' + Reserved for future extension. You may use this to indicate + that the used protocol is not known to the application. + Currently, GPGME does not accept this value in any operation, + though, except for `gpgme_get_protocol_name'. + + -- Function: const char * gpgme_get_protocol_name + (gpgme_protocol_t PROTOCOL) + The function `gpgme_get_protocol_name' returns a statically + allocated string describing the protocol PROTOCOL, or `NULL' if + the protocol number is not valid. + +* Menu: + +* Engine Version Check:: Verifying the engine version. +* Engine Information:: Obtaining more information about the engines. +* Engine Configuration:: Changing the engine configuration. +* OpenPGP:: Support for the OpenPGP protocol. +* Cryptographic Message Syntax:: Support for the CMS. + + +File: gpgme.info, Node: Engine Version Check, Next: Engine Information, Up: Protocols and Engines + +3.1 Engine Version Check +======================== + + -- Function: gpgme_error_t gpgme_engine_check_version + (gpgme_protocol_t 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 the error code `GPG_ERR_NO_ERROR' if the + engine is available and `GPG_ERR_INV_ENGINE' if it is not. + + +File: gpgme.info, Node: Engine Information, Next: Engine Configuration, Prev: Engine Version Check, Up: Protocols and Engines + +3.2 Engine Information +====================== + + -- Data type: gpgme_engine_info_t + The `gpgme_engine_info_t' type specifies a pointer to a structure + describing a crypto engine. The structure contains the following + elements: + + `gpgme_engine_info_t next' + This is a pointer to the next engine info structure in the + linked list, or `NULL' if this is the last element. + + `gpgme_protocol_t protocol' + This is the protocol for which the crypto engine is used. + You can convert this to a string with + `gpgme_get_protocol_name' for printing. + + `const char *file_name' + This is a string holding the file name of the executable of + the crypto engine. Currently, it is never `NULL', but using + `NULL' is reserved for future use, so always check before you + use it. + + `const char *home_dir' + This is a string holding the directory name of the crypto + engine's configuration directory. If it is `NULL', then the + default directory is used. + + `const char *version' + This is a string containing the version number of the crypto + engine. It might be `NULL' if the version number can not be + determined, for example because the executable doesn't exist + or is invalid. + + `const char *req_version' + This is a string containing the minimum required version + number of the crypto engine for GPGME to work correctly. + This is the version number that `gpgme_engine_check_version' + verifies against. Currently, it is never `NULL', but using + `NULL' is reserved for future use, so always check before you + use it. + + -- Function: gpgme_error_t gpgme_get_engine_info + (gpgme_engine_info_t *INFO) + The function `gpgme_get_engine_info' returns a linked list of + engine info structures in INFO. Each info structure describes the + defaults of one configured backend. + + The memory for the info structures is allocated the first time this + function is invoked, and must not be freed by the caller. + + This function returns the error code `GPG_ERR_NO_ERROR' if + successful, and a system error if the memory could not be + allocated. + + Here is an example how you can provide more diagnostics if you +receive an error message which indicates that the crypto engine is +invalid. + + gpgme_ctx_t ctx; + gpgme_error_t err; + + [...] + + if (gpgme_err_code (err) == GPG_ERR_INV_ENGINE) + { + gpgme_engine_info_t info; + err = gpgme_get_engine_info (&info); + if (!err) + { + while (info && info->protocol != gpgme_get_protocol (ctx)) + info = info->next; + if (!info) + fprintf (stderr, "GPGME compiled without support for protocol %s", + gpgme_get_protocol_name (info->protocol)); + else if (info->file_name && !info->version) + fprintf (stderr, "Engine %s not installed properly", + info->file_name); + else if (info->file_name && info->version && info->req_version) + fprintf (stderr, "Engine %s version %s installed, " + "but at least version %s required", info->file_name, + info->version, info->req_version); + else + fprintf (stderr, "Unknown problem with engine for protocol %s", + gpgme_get_protocol_name (info->protocol)); + } + } + + +File: gpgme.info, Node: Engine Configuration, Next: OpenPGP, Prev: Engine Information, Up: Protocols and Engines + +3.3 Engine Configuration +======================== + +You can change the configuration of a backend engine, and thus change +the executable program and configuration directory to be used. You can +make these changes the default or set them for some contexts +individually. + + -- Function: gpgme_error_t gpgme_set_engine_info + (gpgme_protocol_t PROTO, const char *FILE_NAME, + const char *HOME_DIR) + The function `gpgme_set_engine_info' changes the default + configuration of the crypto engine implementing the protocol PROTO. + + FILE_NAME is the file name of the executable program implementing + this protocol, and HOME_DIR is the directory name of the + configuration directory for this crypto engine. If HOME_DIR is + `NULL', the engine's default will be used. + + The new defaults are not applied to already created GPGME contexts. + + This function returns the error code `GPG_ERR_NO_ERROR' if + successful, or an eror code on failure. + + The functions `gpgme_ctx_get_engine_info' and +`gpgme_ctx_set_engine_info' can be used to change the engine +configuration per context. *Note Crypto Engine::. + + +File: gpgme.info, Node: OpenPGP, Next: Cryptographic Message Syntax, Prev: Engine Configuration, Up: Protocols and Engines + +3.4 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'. + + +File: gpgme.info, Node: Cryptographic Message Syntax, Prev: OpenPGP, Up: Protocols and Engines + +3.5 Cryptographic Message Syntax +================================ + +CMS is implemented by GpgSM, the S/MIME implementation for GnuPG. + + The CMS protocol is specified by `GPGME_PROTOCOL_CMS'. + + +File: gpgme.info, Node: Algorithms, Next: Error Handling, Prev: Protocols and Engines, Up: Top + +4 Algorithms +************ + +The crypto backends support a variety of algorithms used in public key +cryptography.(1) The following sections list the identifiers used to +denote such an algorithm. + +* Menu: + +* Public Key Algorithms:: A list of all public key algorithms. +* Hash Algorithms:: A list of all hash algorithms. + + ---------- Footnotes ---------- + + (1) Some engines also provide symmetric only encryption; see the +description of the encryption function on how to use this. + + +File: gpgme.info, Node: Public Key Algorithms, Next: Hash Algorithms, Up: Algorithms + +4.1 Public Key Algorithms +========================= + +Public key algorithms are used for encryption, decryption, signing and +verification of signatures. + + -- Data type: enum gpgme_pubkey_algo_t + The `gpgme_pubkey_algo_t' type specifies the set of all public key + algorithms that are supported by GPGME. Possible values are: + + `GPGME_PK_RSA' + This value indicates the RSA (Rivest, Shamir, Adleman) + algorithm. + + `GPGME_PK_RSA_E' + Deprecated. This value indicates the RSA (Rivest, Shamir, + Adleman) algorithm for encryption and decryption only. + + `GPGME_PK_RSA_S' + Deprecated. This value indicates the RSA (Rivest, Shamir, + Adleman) algorithm for signing and verification only. + + `GPGME_PK_DSA' + This value indicates DSA, the Digital Signature Algorithm. + + `GPGME_PK_ELG' + This value indicates ElGamal. + + `GPGME_PK_ELG_E' + This value also indicates ElGamal and is used specifically in + GnuPG. + + `GPGME_PK_ELG_E' + This value also indicates ElGamal and is used specifically in + GnuPG. + + `GPGME_PK_ECDSA' + This value indicates ECDSA, the Elliptic Curve Digital + Signature Algorithm as defined by FIPS 186-2. + + `GPGME_PK_ECDH' + This value indicates ECDH, the Eliptic Curve Diffie-Hellmann + encryption algorithm as defined by the ECC in OpenPGP draft. + + + -- Function: const char * gpgme_pubkey_algo_name + (gpgme_pubkey_algo_t ALGO) + The function `gpgme_pubkey_algo_name' returns a pointer to a + statically allocated string containing a description of the public + key algorithm ALGO. This string can be used to output the name of + the public key algorithm to the user. + + If ALGO is not a valid public key algorithm, `NULL' is returned. + + +File: gpgme.info, Node: Hash Algorithms, Prev: Public Key Algorithms, Up: Algorithms + +4.2 Hash Algorithms +=================== + +Hash (message digest) algorithms are used to compress a long message to +make it suitable for public key cryptography. + + -- Data type: enum gpgme_hash_algo_t + The `gpgme_hash_algo_t' type specifies the set of all hash + algorithms that are supported by GPGME. Possible values are: + + `GPGME_MD_MD5' + + `GPGME_MD_SHA1' + + `GPGME_MD_RMD160' + + `GPGME_MD_MD2' + + `GPGME_MD_TIGER' + + `GPGME_MD_HAVAL' + + `GPGME_MD_SHA256' + + `GPGME_MD_SHA384' + + `GPGME_MD_SHA512' + + `GPGME_MD_MD4' + + `GPGME_MD_CRC32' + + `GPGME_MD_CRC32_RFC1510' + + `GPGME_MD_CRC24_RFC2440' + + -- Function: const char * gpgme_hash_algo_name (gpgme_hash_algo_t ALGO) + The function `gpgme_hash_algo_name' returns a pointer to a + statically allocated string containing a description of the hash + algorithm ALGO. This string can be used to output the name of the + hash algorithm to the user. + + If ALGO is not a valid hash algorithm, `NULL' is returned. + + +File: gpgme.info, Node: Error Handling, Next: Exchanging Data, Prev: Algorithms, Up: Top + +5 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 for many +error codes what they mean usually. Some error values have specific +meanings if returned by a certain functions. Such cases are described +in the documentation of those functions. + + GPGME uses the `libgpg-error' library. This allows to share the +error codes with other components of the GnuPG system, and thus pass +error values transparently from the crypto engine, or some helper +application of the crypto engine, to the user. This way no information +is lost. As a consequence, GPGME does not use its own identifiers for +error codes, but uses those provided by `libgpg-error'. They usually +start with `GPG_ERR_'. + + However, GPGME does provide aliases for the functions defined in +libgpg-error, which might be preferred for name space consistency. + +* Menu: + +* Error Values:: The error value and what it means. +* Error Sources:: A list of important error sources. +* Error Codes:: A list of important error codes. +* Error Strings:: How to get a descriptive string from a value. + + +File: gpgme.info, Node: Error Values, Next: Error Sources, Up: Error Handling + +5.1 Error Values +================ + + -- Data type: gpgme_err_code_t + The `gpgme_err_code_t' type is an alias for the `libgpg-error' + type `gpg_err_code_t'. The error code indicates the type of an + error, or the reason why an operation failed. + + A list of important error codes can be found in the next section. + + -- Data type: gpgme_err_source_t + The `gpgme_err_source_t' type is an alias for the `libgpg-error' + type `gpg_err_source_t'. The error source has not a precisely + defined meaning. Sometimes it is the place where the error + happened, sometimes it is the place where an error was encoded + into an error value. Usually the error source will give an + indication to where to look for the problem. This is not always + true, but it is attempted to achieve this goal. + + A list of important error sources can be found in the next section. + + -- Data type: gpgme_error_t + The `gpgme_error_t' type is an alias for the `libgpg-error' type + `gpg_error_t'. An error value like this has always two + components, an error code and an error source. Both together form + the error value. + + Thus, the error value can not be directly compared against an error + code, but the accessor functions described below must be used. + However, it is guaranteed that only 0 is used to indicate success + (`GPG_ERR_NO_ERROR'), and that in this case all other parts of the + error value are set to 0, too. + + Note that in GPGME, the error source is used purely for + diagnostical purposes. Only the error code should be checked to + test for a certain outcome of a function. The manual only + documents the error code part of an error value. The error source + is left unspecified and might be anything. + + -- Function: static inline gpgme_err_code_t gpgme_err_code + (gpgme_error_t ERR) + The static inline function `gpgme_err_code' returns the + `gpgme_err_code_t' component of the error value ERR. This + function must be used to extract the error code from an error + value in order to compare it with the `GPG_ERR_*' error code + macros. + + -- Function: static inline gpgme_err_source_t gpgme_err_source + (gpgme_error_t ERR) + The static inline function `gpgme_err_source' returns the + `gpgme_err_source_t' component of the error value ERR. This + function must be used to extract the error source from an error + value in order to compare it with the `GPG_ERR_SOURCE_*' error + source macros. + + -- Function: static inline gpgme_error_t gpgme_err_make + (gpgme_err_source_t SOURCE, gpgme_err_code_t CODE) + The static inline function `gpgme_err_make' returns the error + value consisting of the error source SOURCE and the error code + CODE. + + This function can be used in callback functions to construct an + error value to return it to the library. + + -- Function: static inline gpgme_error_t gpgme_error + (gpgme_err_code_t CODE) + The static inline function `gpgme_error' returns the error value + consisting of the default error source and the error code CODE. + + For GPGME applications, the default error source is + `GPG_ERR_SOURCE_USER_1'. You can define + `GPGME_ERR_SOURCE_DEFAULT' before including `gpgme.h' to change + this default. + + This function can be used in callback functions to construct an + error value to return it to the library. + + The `libgpg-error' library provides error codes for all system error +numbers it knows about. If ERR is an unknown error number, the error +code `GPG_ERR_UNKNOWN_ERRNO' is used. The following functions can be +used to construct error values from system errnor numbers. + + -- Function: gpgme_error_t gpgme_err_make_from_errno + (gpgme_err_source_t SOURCE, int ERR) + The function `gpgme_err_make_from_errno' is like `gpgme_err_make', + but it takes a system error like `errno' instead of a + `gpgme_err_code_t' error code. + + -- Function: gpgme_error_t gpgme_error_from_errno (int ERR) + The function `gpgme_error_from_errno' is like `gpgme_error', but + it takes a system error like `errno' instead of a + `gpgme_err_code_t' error code. + + Sometimes you might want to map system error numbers to error codes +directly, or map an error code representing a system error back to the +system error number. The following functions can be used to do that. + + -- Function: gpgme_err_code_t gpgme_err_code_from_errno (int ERR) + The function `gpgme_err_code_from_errno' returns the error code + for the system error ERR. If ERR is not a known system error, the + function returns `GPG_ERR_UNKNOWN_ERRNO'. + + -- Function: int gpgme_err_code_to_errno (gpgme_err_code_t ERR) + The function `gpgme_err_code_to_errno' returns the system error + for the error code ERR. If ERR is not an error code representing + a system error, or if this system error is not defined on this + system, the function returns `0'. + + +File: gpgme.info, Node: Error Sources, Next: Error Codes, Prev: Error Values, Up: Error Handling + +5.2 Error Sources +================= + +The library `libgpg-error' defines an error source for every component +of the GnuPG system. The error source part of an error value is not +well defined. As such it is mainly useful to improve the diagnostic +error message for the user. + + If the error code part of an error value is `0', the whole error +value will be `0'. In this case the error source part is of course +`GPG_ERR_SOURCE_UNKNOWN'. + + The list of error sources that might occur in applications using +GPGME is: + +`GPG_ERR_SOURCE_UNKNOWN' + The error source is not known. The value of this error source is + `0'. + +`GPG_ERR_SOURCE_GPGME' + The error source is GPGME itself. This is the default for errors + that occur in the GPGME library. + +`GPG_ERR_SOURCE_GPG' + The error source is GnuPG, which is the crypto engine used for the + OpenPGP protocol. + +`GPG_ERR_SOURCE_GPGSM' + The error source is GPGSM, which is the crypto engine used for the + CMS protocol. + +`GPG_ERR_SOURCE_GCRYPT' + The error source is `libgcrypt', which is used by crypto engines + to perform cryptographic operations. + +`GPG_ERR_SOURCE_GPGAGENT' + The error source is `gpg-agent', which is used by crypto engines + to perform operations with the secret key. + +`GPG_ERR_SOURCE_PINENTRY' + The error source is `pinentry', which is used by `gpg-agent' to + query the passphrase to unlock a secret key. + +`GPG_ERR_SOURCE_SCD' + The error source is the SmartCard Daemon, which is used by + `gpg-agent' to delegate operations with the secret key to a + SmartCard. + +`GPG_ERR_SOURCE_KEYBOX' + The error source is `libkbx', a library used by the crypto engines + to manage local keyrings. + +`GPG_ERR_SOURCE_USER_1' + +`GPG_ERR_SOURCE_USER_2' + +`GPG_ERR_SOURCE_USER_3' + +`GPG_ERR_SOURCE_USER_4' + These error sources are not used by any GnuPG component and can be + used by other software. For example, applications using GPGME can + use them to mark error values coming from callback handlers. Thus + `GPG_ERR_SOURCE_USER_1' is the default for errors created with + `gpgme_error' and `gpgme_error_from_errno', unless you define + `GPGME_ERR_SOURCE_DEFAULT' before including `gpgme.h'. + + +File: gpgme.info, Node: Error Codes, Next: Error Strings, Prev: Error Sources, Up: Error Handling + +5.3 Error Codes +=============== + +The library `libgpg-error' defines many error values. Most of them are +not used by `GPGME' directly, but might be returned by GPGME because it +received them from the crypto engine. The below list only includes +such error codes that have a specific meaning in `GPGME', or which are +so common that you should know about them. + +`GPG_ERR_EOF' + This value indicates the end of a list, buffer or file. + +`GPG_ERR_NO_ERROR' + This value indicates success. The value of this error code is + `0'. Also, it is guaranteed that an error value made from the + error code `0' will be `0' itself (as a whole). This means that + the error source information is lost for this error code, however, + as this error code indicates that no error occured, this is + generally not a problem. + +`GPG_ERR_GENERAL' + 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. + +`GPG_ERR_ENOMEM' + This value means that an out-of-memory condition occurred. + +`GPG_ERR_E...' + System errors are mapped to GPG_ERR_FOO where FOO is the symbol for + the system error. + +`GPG_ERR_INV_VALUE' + This value means that some user provided data was out of range. + This can also refer to objects. For example, if an empty + `gpgme_data_t' object was expected, but one containing data was + provided, this error value is returned. + +`GPG_ERR_UNUSABLE_PUBKEY' + This value means that some recipients for a message were invalid. + +`GPG_ERR_UNUSABLE_SECKEY' + This value means that some signers were invalid. + +`GPG_ERR_NO_DATA' + This value means that a `gpgme_data_t' object which was expected + to have content was found empty. + +`GPG_ERR_CONFLICT' + This value means that a conflict of some sort occurred. + +`GPG_ERR_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. + +`GPG_ERR_DECRYPT_FAILED' + This value indicates that a decryption operation was unsuccessful. + +`GPG_ERR_BAD_PASSPHRASE' + This value means that the user did not provide a correct passphrase + when requested. + +`GPG_ERR_CANCELED' + This value means that the operation was canceled. + +`GPG_ERR_INV_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. + +`GPG_ERR_AMBIGUOUS_NAME' + This value indicates that a user ID or other specifier did not + specify a unique key. + +`GPG_ERR_WRONG_KEY_USAGE' + This value indicates that a key is not used appropriately. + +`GPG_ERR_CERT_REVOKED' + This value indicates that a key signature was revoced. + +`GPG_ERR_CERT_EXPIRED' + This value indicates that a key signature expired. + +`GPG_ERR_NO_CRL_KNOWN' + This value indicates that no certificate revocation list is known + for the certificate. + +`GPG_ERR_NO_POLICY_MATCH' + This value indicates that a policy issue occured. + +`GPG_ERR_NO_SECKEY' + This value indicates that no secret key for the user ID is + available. + +`GPG_ERR_MISSING_CERT' + This value indicates that a key could not be imported because the + issuer certificate is missing. + +`GPG_ERR_BAD_CERT_CHAIN' + This value indicates that a key could not be imported because its + certificate chain is not good, for example it could be too long. + +`GPG_ERR_UNSUPPORTED_ALGORITHM' + This value means a verification failed because the cryptographic + algorithm is not supported by the crypto backend. + +`GPG_ERR_BAD_SIGNATURE' + This value means a verification failed because the signature is + bad. + +`GPG_ERR_NO_PUBKEY' + This value means a verification failed because the public key is + not available. + +`GPG_ERR_USER_1' + +`GPG_ERR_USER_2' + +`...' + +`GPG_ERR_USER_16' + These error codes are not used by any GnuPG component and can be + freely used by other software. Applications using GPGME might use + them to mark specific errors returned by callback handlers if no + suitable error codes (including the system errors) for these + errors exist already. + + +File: gpgme.info, Node: Error Strings, Prev: Error Codes, Up: Error Handling + +5.4 Error Strings +================= + + -- Function: const char * gpgme_strerror (gpgme_error_t ERR) + The function `gpgme_strerror' returns a pointer to a statically + allocated string containing a description of the error code + contained in the error value ERR. This string can be used to + output a diagnostic message to the user. + + This function is not thread safe. Use `gpgme_strerror_r' in + multi-threaded programs. + + -- Function: int gpgme_strerror_r (gpgme_error_t ERR, char *BUF, + size_t BUFLEN) + The function `gpgme_strerror_r' returns the error string for ERR + in the user-supplied buffer BUF of size BUFLEN. This function is, + in contrast to `gpgme_strerror', thread-safe if a thread-safe + `strerror_r' function is provided by the system. If the function + succeeds, 0 is returned and BUF contains the string describing the + error. If the buffer was not large enough, ERANGE is returned and + BUF contains as much of the beginning of the error string as fits + into the buffer. + + -- Function: const char * gpgme_strsource (gpgme_error_t ERR) + The function `gpgme_strerror' returns a pointer to a statically + allocated string containing a description of the error source + contained in 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': + + gpgme_ctx_t ctx; + gpgme_error_t err = gpgme_new (&ctx); + if (err) + { + fprintf (stderr, "%s: creating GpgME context failed: %s: %s\n", + argv[0], gpgme_strsource (err), gpgme_strerror (err)); + exit (1); + } + + +File: gpgme.info, Node: Exchanging Data, Next: Contexts, Prev: Error Handling, Up: Top + +6 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 `gpgme_data_t' objects, regardless of the +communication protocol between GPGME and the crypto engine in use. + + -- Data type: gpgme_data_t + The `gpgme_data_t' type is a handle for a container for generic + data, which is used by GPGME to exchange data with the user. + + `gpgme_data_t' objects do not provide notifications on events. It +is assumed that read and write operations are blocking until data is +available. If this is undesirable, the application must ensure that +all GPGME data operations always have data available, for example by +using memory buffers or files rather than pipes or sockets. This might +be relevant, for example, if the external event loop mechanism is used. + +* Menu: + +* Creating Data Buffers:: Creating new data buffers. +* Destroying Data Buffers:: Releasing data buffers. +* Manipulating Data Buffers:: Operations on data buffers. + + +File: gpgme.info, Node: Creating Data Buffers, Next: Destroying Data Buffers, Up: Exchanging Data + +6.1 Creating Data Buffers +========================= + +Data objects can be based on memory, files, or callback functions +provided by the user. Not all operations are supported by all objects. + +* Menu: + +* Memory Based Data Buffers:: Creating memory based data buffers. +* File Based Data Buffers:: Creating file based data buffers. +* Callback Based Data Buffers:: Creating callback based data buffers. + + +File: gpgme.info, Node: Memory Based Data Buffers, Next: File Based Data Buffers, Up: Creating Data Buffers + +6.1.1 Memory Based Data Buffers +------------------------------- + +Memory based data objects store all data in allocated memory. This is +convenient, but only practical for an amount of data that is a fraction +of the available physical memory. The data has to be copied from its +source and to its destination, which can often be avoided by using one +of the other data object + + -- Function: gpgme_error_t gpgme_data_new (gpgme_data_t *DH) + The function `gpgme_data_new' creates a new `gpgme_data_t' object + and returns a handle for it in DH. The data object is memory + based and initially empty. + + The function returns the error code `GPG_ERR_NO_ERROR' if the data + object was successfully created, `GPG_ERR_INV_VALUE' if DH is not + a valid pointer, and `GPG_ERR_ENOMEM' if not enough memory is + available. + + -- Function: gpgme_error_t gpgme_data_new_from_mem (gpgme_data_t *DH, + const char *BUFFER, size_t SIZE, int COPY) + The function `gpgme_data_new_from_mem' creates a new + `gpgme_data_t' 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 the error code `GPG_ERR_NO_ERROR' if the data + object was successfully created, `GPG_ERR_INV_VALUE' if DH or + BUFFER is not a valid pointer, and `GPG_ERR_ENOMEM' if not enough + memory is available. + + -- Function: gpgme_error_t gpgme_data_new_from_file (gpgme_data_t *DH, + const char *FILENAME, int COPY) + The function `gpgme_data_new_from_file' creates a new + `gpgme_data_t' 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 the error code `GPG_ERR_NO_ERROR' if the data + object was successfully created, `GPG_ERR_INV_VALUE' if DH or + FILENAME is not a valid pointer, `GPG_ERR_NOT_IMPLEMENTED' if CODE + is zero, and `GPG_ERR_ENOMEM' if not enough memory is available. + + -- Function: gpgme_error_t gpgme_data_new_from_filepart + (gpgme_data_t *DH, const char *FILENAME, FILE *FP, + off_t OFFSET, size_t LENGTH) + The function `gpgme_data_new_from_filepart' creates a new + `gpgme_data_t' 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 the error code `GPG_ERR_NO_ERROR' if the data + object was successfully created, `GPG_ERR_INV_VALUE' if DH and + exactly one of FILENAME and FP is not a valid pointer, and + `GPG_ERR_ENOMEM' if not enough memory is available. + + +File: gpgme.info, Node: File Based Data Buffers, Next: Callback Based Data Buffers, Prev: Memory Based Data Buffers, Up: Creating Data Buffers + +6.1.2 File Based Data Buffers +----------------------------- + +File based data objects operate directly on file descriptors or +streams. Only a small amount of data is stored in core at any time, so +the size of the data objects is not limited by GPGME. + + -- Function: gpgme_error_t gpgme_data_new_from_fd (gpgme_data_t *DH, + int FD) + The function `gpgme_data_new_from_fd' creates a new `gpgme_data_t' + object and uses the file descriptor FD to read from (if used as an + input data object) and write to (if used as an output data object). + + When using the data object as an input buffer, the function might + read a bit more from the file descriptor than is actually needed + by the crypto engine in the desired operation because of internal + buffering. + + Note that GPGME assumes that the file descriptor is set to blocking + mode. Errors during I/O operations, except for EINTR, are usually + fatal for crypto operations. + + The function returns the error code `GPG_ERR_NO_ERROR' if the data + object was successfully created, and `GPG_ERR_ENOMEM' if not + enough memory is available. + + -- Function: gpgme_error_t gpgme_data_new_from_stream + (gpgme_data_t *DH, FILE *STREAM) + The function `gpgme_data_new_from_stream' creates a new + `gpgme_data_t' object and uses the I/O stream STREAM to read from + (if used as an input data object) and write to (if used as an + output data object). + + When using the data object as an input buffer, the function might + read a bit more from the stream than is actually needed by the + crypto engine in the desired operation because of internal + buffering. + + Note that GPGME assumes that the stream is in blocking mode. + Errors during I/O operations, except for EINTR, are usually fatal + for crypto operations. + + The function returns the error code `GPG_ERR_NO_ERROR' if the data + object was successfully created, and `GPG_ERR_ENOMEM' if not + enough memory is available. + + +File: gpgme.info, Node: Callback Based Data Buffers, Prev: File Based Data Buffers, Up: Creating Data Buffers + +6.1.3 Callback Based Data Buffers +--------------------------------- + +If neither memory nor file based data objects are a good fit for your +application, you can implement the functions a data object provides +yourself and create a data object from these callback functions. + + -- Data type: ssize_t (*gpgme_data_read_cb_t) (void *HANDLE, +void *BUFFER, size_t SIZE) + The `gpgme_data_read_cb_t' type is the type of functions which + GPGME calls if it wants to read data from a user-implemented data + object. The function should read up to SIZE bytes from the + current read position into the space starting at BUFFER. The + HANDLE is provided by the user at data object creation time. + + Note that GPGME assumes that the read blocks until data is + available. Errors during I/O operations, except for EINTR, are + usually fatal for crypto operations. + + The function should return the number of bytes read, 0 on EOF, and + -1 on error. If an error occurs, ERRNO should be set to describe + the type of the error. + + -- Data type: ssize_t (*gpgme_data_write_cb_t) (void *HANDLE, +const void *BUFFER, size_t SIZE) + The `gpgme_data_write_cb_t' type is the type of functions which + GPGME calls if it wants to write data to a user-implemented data + object. The function should write up to SIZE bytes to the current + write position from the space starting at BUFFER. The HANDLE is + provided by the user at data object creation time. + + Note that GPGME assumes that the write blocks until data is + available. Errors during I/O operations, except for EINTR, are + usually fatal for crypto operations. + + The function should return the number of bytes written, and -1 on + error. If an error occurs, ERRNO should be set to describe the + type of the error. + + -- Data type: off_t (*gpgme_data_seek_cb_t) (void *HANDLE, +off_t OFFSET, int WHENCE) + The `gpgme_data_seek_cb_t' type is the type of functions which + GPGME calls if it wants to change the current read/write position + in a user-implemented data object, just like the `lseek' function. + + The function should return the new read/write position, and -1 on + error. If an error occurs, ERRNO should be set to describe the + type of the error. + + -- Data type: void (*gpgme_data_release_cb_t) (void *HANDLE) + The `gpgme_data_release_cb_t' type is the type of functions which + GPGME calls if it wants to destroy a user-implemented data object. + The HANDLE is provided by the user at data object creation time. + + -- Data type: struct gpgme_data_cbs + This structure is used to store the data callback interface + functions described above. It has the following members: + + `gpgme_data_read_cb_t read' + This is the function called by GPGME to read data from the + data object. It is only required for input data object. + + `gpgme_data_write_cb_t write' + This is the function called by GPGME to write data to the + data object. It is only required for output data object. + + `gpgme_data_seek_cb_t seek' + This is the function called by GPGME to change the current + read/write pointer in the data object (if available). It is + optional. + + `gpgme_data_release_cb_t release' + This is the function called by GPGME to release a data + object. It is optional. + + -- Function: gpgme_error_t gpgme_data_new_from_cbs (gpgme_data_t *DH, + gpgme_data_cbs_t CBS, void *HANDLE) + The function `gpgme_data_new_from_cbs' creates a new + `gpgme_data_t' object and uses the user-provided callback functions + to operate on the data object. + + The handle HANDLE is passed as first argument to the callback + functions. This can be used to identify this data object. + + The function returns the error code `GPG_ERR_NO_ERROR' if the data + object was successfully created, and `GPG_ERR_ENOMEM' if not + enough memory is available. + + The following interface is deprecated and only provided for backward +compatibility. Don't use it. It will be removed in a future version +of GPGME. + + -- Function: gpgme_error_t gpgme_data_new_with_read_cb + (gpgme_data_t *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 + `gpgme_data_t' 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 the error code `GPG_ERR_NO_ERROR' if the data + object was successfully created, `GPG_ERR_INV_VALUE' if DH or + READFUNC is not a valid pointer, and `GPG_ERR_ENOMEM' if not + enough memory is available. + + +File: gpgme.info, Node: Destroying Data Buffers, Next: Manipulating Data Buffers, Prev: Creating Data Buffers, Up: Exchanging Data + +6.2 Destroying Data Buffers +=========================== + + -- Function: void gpgme_data_release (gpgme_data_t 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 (gpgme_data_t 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 `gpgme_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'. In + any case, the data object DH is destroyed. + + -- Function: void gpgme_free (void *BUFFER) + The function `gpgme_free' releases the memory returned by + `gpgme_data_release_and_get_mem'. It should be used instead of + the system libraries `free' function in case different allocators + are used in a single program. + + +File: gpgme.info, Node: Manipulating Data Buffers, Prev: Destroying Data Buffers, Up: Exchanging Data + +6.3 Manipulating Data Buffers +============================= + +Data buffers contain data and meta-data. The following operations can +be used to manipulate both. + +* Menu: + +* Data Buffer I/O Operations:: I/O operations on data buffers. +* Data Buffer Meta-Data:: Meta-data manipulation of data buffers. + + +File: gpgme.info, Node: Data Buffer I/O Operations, Next: Data Buffer Meta-Data, Up: Manipulating Data Buffers + +6.3.1 Data Buffer I/O Operations +-------------------------------- + + -- Function: ssize_t gpgme_data_read (gpgme_data_t DH, void *BUFFER, + size_t LENGTH) + The function `gpgme_data_read' reads up to LENGTH bytes from the + data object with the handle DH into the space starting at BUFFER. + + If no error occurs, the actual amount read is returned. If the + end of the data object is reached, the function returns 0. + + In all other cases, the function returns -1 and sets ERRNO. + + -- Function: ssize_t gpgme_data_write (gpgme_data_t DH, + const void *BUFFER, size_t SIZE) + The function `gpgme_data_write' writes up to SIZE bytes starting + from BUFFER into the data object with the handle DH at the current + write position. + + The function returns the number of bytes actually written, or -1 + if an error occurs. If an error occurs, ERRNO is set. + + -- Function: off_t gpgme_data_seek (gpgme_data_t DH, off_t OFFSET, + int WHENCE) + The function `gpgme_data_seek' changes the current read/write + position. + + The WHENCE argument specifies how the OFFSET should be + interpreted. It must be one of the following symbolic constants: + + `SEEK_SET' + Specifies that OFFSET is a count of characters from the + beginning of the data object. + + `SEEK_CUR' + Specifies that OFFSET is a count of characters from the + current file position. This count may be positive or + negative. + + `SEEK_END' + Specifies that OFFSET is a count of characters from the end of + the data object. A negative count specifies a position + within the current extent of the data object; a positive + count specifies a position past the current end. If you set + the position past the current end, and actually write data, + you will extend the data object with zeros up to that + position. + + If successful, the function returns the resulting file position, + measured in bytes from the beginning of the data object. You can + use this feature together with `SEEK_CUR' to read the current + read/write position. + + If the function fails, -1 is returned and ERRNO is set. + + The following function is deprecated and should not be used. It will +be removed in a future version of GPGME. + + -- Function: gpgme_error_t gpgme_data_rewind (gpgme_data_t DH) + The function `gpgme_data_rewind' is equivalent to: + + return (gpgme_data_seek (dh, 0, SEEK_SET) == -1) + ? gpgme_error_from_errno (errno) : 0; + + +File: gpgme.info, Node: Data Buffer Meta-Data, Prev: Data Buffer I/O Operations, Up: Manipulating Data Buffers + +6.3.2 Data Buffer Meta-Data +--------------------------- + + -- Function: char * gpgme_data_get_file_name (gpgme_data_t DH) + The function `gpgme_data_get_file_name' returns a pointer to a + string containing the file name associated with the data object. + The file name will be stored in the output when encrypting or + signing the data and will be returned to the user when decrypting + or verifying the output data. + + If no error occurs, the string containing the file name is + returned. Otherwise, `NULL' will be returned. + + -- Function: gpgme_error_t gpgme_data_set_file_name (gpgme_data_t DH, + const char *FILE_NAME) + The function `gpgme_data_set_file_name' sets the file name + associated with the data object. The file name will be stored in + the output when encrypting or signing the data and will be + returned to the user when decrypting or verifying the output data. + + The function returns the error code `GPG_ERR_INV_VALUE' if DH is + not a valid pointer and `GPG_ERR_ENOMEM' if not enough memory is + available. + + -- Data type: enum gpgme_data_encoding_t + The `gpgme_data_encoding_t' type specifies the encoding of a + `gpgme_data_t' object. For input data objects, the encoding is + useful to give the backend a hint on the type of data. For output + data objects, the encoding can specify the output data format on + certain operations. Please note that not all backends support all + encodings on all operations. The following data types are + available: + + `GPGME_DATA_ENCODING_NONE' + This specifies that the encoding is not known. This is the + default for a new data object. The backend will try its best + to detect the encoding automatically. + + `GPGME_DATA_ENCODING_BINARY' + This specifies that the data is encoding in binary form; i.e. + there is no special encoding. + + `GPGME_DATA_ENCODING_BASE64' + This specifies that the data is encoded using the Base-64 + encoding scheme as used by MIME and other protocols. + + `GPGME_DATA_ENCODING_ARMOR' + This specifies that the data is encoded in an armored form as + used by OpenPGP and PEM. + + `GPGME_DATA_ENCODING_URL' + The data is a list of linefeed delimited URLs. This is only + useful with `gpgme_op_import'. + + `GPGME_DATA_ENCODING_URL0' + The data is a list of binary zero delimited URLs. This is + only useful with `gpgme_op_import'. + + `GPGME_DATA_ENCODING_URLESC' + The data is a list of linefeed delimited URLs with all + control and space characters percent escaped. This mode is + is not yet implemented. + + + -- Function: gpgme_data_encoding_t gpgme_data_get_encoding + (gpgme_data_t DH) + The function `gpgme_data_get_encoding' returns the encoding of the + data object with the handle DH. If DH is not a valid pointer + (e.g. `NULL') `GPGME_DATA_ENCODING_NONE' is returned. + + -- Function: gpgme_error_t gpgme_data_set_encoding + (gpgme_data_t DH, gpgme_data_encoding_t ENC) + The function `gpgme_data_set_encoding' changes the encoding of the + data object with the handle DH to ENC. + + +File: gpgme.info, Node: Contexts, Next: UI Server Protocol, Prev: Exchanging Data, Up: Top + +7 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: gpgme_ctx_t + The `gpgme_ctx_t' type is a handle for a GPGME context, which is + used to hold the configuration, status and result of cryptographic + operations. + +* Menu: + +* Creating Contexts:: Creating new GPGME contexts. +* Destroying Contexts:: Releasing GPGME contexts. +* Result Management:: Managing the result of crypto operations. +* Context Attributes:: Setting properties of a context. +* Key Management:: Managing keys with GPGME. +* Trust Item Management:: Managing trust items with GPGME. +* Crypto Operations:: Using a context for cryptography. +* Run Control:: Controlling how operations are run. + + +File: gpgme.info, Node: Creating Contexts, Next: Destroying Contexts, Up: Contexts + +7.1 Creating Contexts +===================== + + -- Function: gpgme_error_t gpgme_new (gpgme_ctx_t *CTX) + The function `gpgme_new' creates a new `gpgme_ctx_t' object and + returns a handle for it in CTX. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + context was successfully created, `GPG_ERR_INV_VALUE' if CTX is + not a valid pointer, and `GPG_ERR_ENOMEM' if not enough memory is + available. Also, it returns `GPG_ERR_NOT_OPERATIONAL' if + `gpgme_check_version' was not called to initialize GPGME, and + `GPG_ERR_SELFTEST_FAILED' if a selftest failed. Currently, the + only selftest is for Windows MingW32 targets to see if + `-mms-bitfields' was used (as required). + + +File: gpgme.info, Node: Destroying Contexts, Next: Result Management, Prev: Creating Contexts, Up: Contexts + +7.2 Destroying Contexts +======================= + + -- Function: void gpgme_release (gpgme_ctx_t CTX) + The function `gpgme_release' destroys the context with the handle + CTX and releases all associated resources. + + +File: gpgme.info, Node: Result Management, Next: Context Attributes, Prev: Destroying Contexts, Up: Contexts + +7.3 Result Management +===================== + +The detailed result of an operation is returned in operation-specific +structures such as `gpgme_decrypt_result_t'. The corresponding +retrieval functions such as `gpgme_op_decrypt_result' provide static +access to the results after an operation completes. The following +interfaces make it possible to detach a result structure from its +associated context and give it a lifetime beyond that of the current +operation or context. + + -- Function: void gpgme_result_ref (void *RESULT) + The function `gpgme_result_ref' acquires an additional reference + for the result RESULT, which may be of any type + `gpgme_*_result_t'. As long as the user holds a reference, the + result structure is guaranteed to be valid and unmodified. + + -- Function: void gpgme_result_unref (void *RESULT) + The function `gpgme_result_unref' releases a reference for the + result RESULT. If this was the last reference, the result + structure will be destroyed and all resources associated to it + will be released. + + Note that a context may hold its own references to result structures, +typically until the context is destroyed or the next operation is +started. In fact, these references are accessed through the +`gpgme_op_*_result' functions. + + +File: gpgme.info, Node: Context Attributes, Next: Key Management, Prev: Result Management, Up: Contexts + +7.4 Context Attributes +====================== + +* Menu: + +* Protocol Selection:: Selecting the protocol used by a context. +* Crypto Engine:: Configuring the crypto engine. +* ASCII Armor:: Requesting ASCII armored output. +* Text Mode:: Choosing canonical text mode. +* Included Certificates:: Including a number of certificates. +* Key Listing Mode:: Selecting key listing mode. +* Passphrase Callback:: Getting the passphrase from the user. +* Progress Meter Callback:: Being informed about the progress. +* Locale:: Setting the locale of a context. + + +File: gpgme.info, Node: Protocol Selection, Next: Crypto Engine, Up: Context Attributes + +7.4.1 Protocol Selection +------------------------ + + -- Function: gpgme_error_t gpgme_set_protocol (gpgme_ctx_t CTX, + gpgme_protocol_t 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. *Note + 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. *Note Engine Version Check::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + protocol could be set successfully, and `GPG_ERR_INV_VALUE' if + PROTOCOL is not a valid protocol. + + -- Function: gpgme_protocol_t gpgme_get_protocol (gpgme_ctx_t CTX) + The function `gpgme_get_protocol' retrieves the protocol currently + use with the context CTX. + + +File: gpgme.info, Node: Crypto Engine, Next: ASCII Armor, Prev: Protocol Selection, Up: Context Attributes + +7.4.2 Crypto Engine +------------------- + +The following functions can be used to set and retrieve the +configuration of the crypto engines of a specific context. The default +can also be retrieved without any particular context. *Note Engine +Information::. The default can also be changed globally. *Note Engine +Configuration::. + + -- Function: gpgme_engine_info_t gpgme_ctx_get_engine_info + (gpgme_ctx_t CTX) + The function `gpgme_ctx_get_engine_info' returns a linked list of + engine info structures. Each info structure describes the + configuration of one configured backend, as used by the context + CTX. + + The result is valid until the next invocation of + `gpgme_ctx_set_engine_info' for this particular context. + + This function can not fail. + + -- Function: gpgme_error_t gpgme_ctx_set_engine_info (gpgme_ctx_t CTX, + gpgme_protocol_t PROTO, const char *FILE_NAME, + const char *HOME_DIR) + The function `gpgme_ctx_set_engine_info' changes the configuration + of the crypto engine implementing the protocol PROTO for the + context CTX. + + FILE_NAME is the file name of the executable program implementing + this protocol, and HOME_DIR is the directory name of the + configuration directory for this crypto engine. If HOME_DIR is + `NULL', the engine's default will be used. + + Currently this function must be used before starting the first + crypto operation. It is unspecified if and when the changes will + take effect if the function is called after starting the first + operation on the context CTX. + + This function returns the error code `GPG_ERR_NO_ERROR' if + successful, or an eror code on failure. + + +File: gpgme.info, Node: ASCII Armor, Next: Text Mode, Prev: Crypto Engine, Up: Context Attributes + +7.4.3 ASCII Armor +----------------- + + -- Function: void gpgme_set_armor (gpgme_ctx_t 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 (gpgme_ctx_t 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. + + +File: gpgme.info, Node: Text Mode, Next: Included Certificates, Prev: ASCII Armor, Up: Context Attributes + +7.4.4 Text Mode +--------------- + + -- Function: void gpgme_set_textmode (gpgme_ctx_t 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 (gpgme_ctx_t 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. + + +File: gpgme.info, Node: Included Certificates, Next: Key Listing Mode, Prev: Text Mode, Up: Context Attributes + +7.4.5 Included Certificates +--------------------------- + + -- Function: void gpgme_set_include_certs (gpgme_ctx_t 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: + + `GPGME_INCLUDE_CERTS_DEFAULT' + Fall back to the default of the crypto backend. This is the + default for GPGME. + + `-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 (gpgme_ctx_t CTX) + The function `gpgme_get_include_certs' returns the number of + certificates to include into an S/MIME signed message. + + +File: gpgme.info, Node: Key Listing Mode, Next: Passphrase Callback, Prev: Included Certificates, Up: Context Attributes + +7.4.6 Key Listing Mode +---------------------- + + -- Function: gpgme_error_t gpgme_set_keylist_mode (gpgme_ctx_t CTX, + gpgme_keylist_mode_t 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 searched for keys in the keylisting + operation. The type of external source is dependant on the + crypto engine used and whether it is combined with + `GPGME_KEYLIST_MODE_LOCAL'. For example, it can be a remote + keyserver or LDAP certificate server. + + `GPGME_KEYLIST_MODE_SIGS' + The `GPGME_KEYLIST_MODE_SIGS' symbol specifies that the key + signatures should be included in the listed keys. + + `GPGME_KEYLIST_MODE_SIG_NOTATIONS' + The `GPGME_KEYLIST_MODE_SIG_NOTATIONS' symbol specifies that + the signature notations on key signatures should be included + in the listed keys. This only works if + `GPGME_KEYLIST_MODE_SIGS' is also enabled. + + `GPGME_KEYLIST_MODE_EPHEMERAL' + The `GPGME_KEYLIST_MODE_EPHEMERAL' symbol specifies that keys + flagged as ephemeral are included in the listing. + + `GPGME_KEYLIST_MODE_VALIDATE' + The `GPGME_KEYLIST_MODE_VALIDATE' symbol specifies that the + backend should do key or certificate validation and not just + get the validity information from an internal cache. This + might be an expensive operation and is in general not useful. + Currently only implemented for the S/MIME backend and ignored + for other backends. + + + 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 calculated 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 the error code `GPG_ERR_NO_ERROR' if the mode + could be set correctly, and `GPG_ERR_INV_VALUE' if CTX is not a + valid pointer or MODE is not a valid mode. + + -- Function: gpgme_keylist_mode_t gpgme_get_keylist_mode + (gpgme_ctx_t 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. + + +File: gpgme.info, Node: Passphrase Callback, Next: Progress Meter Callback, Prev: Key Listing Mode, Up: Context Attributes + +7.4.7 Passphrase Callback +------------------------- + + -- Data type: gpgme_error_t (*gpgme_passphrase_cb_t)(void *HOOK, const +char *UID_HINT, const char *PASSPHRASE_INFO, int PREV_WAS_BAD, int FD) + The `gpgme_passphrase_cb_t' type is the type of functions usable as + passphrase callback function. + + The argument UID_HINT might contain a string that gives an + indication for which user ID the passphrase is required. If this + is not available, or not applicable (in the case of symmetric + encryption, for example), UID_HINT will be `NULL'. + + The argument PASSPHRASE_INFO, if not `NULL', will give further + information about the context in which the passphrase is required. + This information is engine and operation specific. + + If this is the repeated attempt to get the passphrase, because + previous attempts failed, then PREV_WAS_BAD is 1, otherwise it + will be 0. + + The user must write the passphrase, followed by a newline + character, to the file descriptor FD. If the user returns 0 + indicating success, the user must at least write a newline + character before returning from the callback. + + If an error occurs, return the corresponding `gpgme_error_t' + value. You can use the error code `GPG_ERR_CANCELED' to abort the + operation. Otherwise, return `0'. + + -- Function: void gpgme_set_passphrase_cb (gpgme_ctx_t CTX, + gpgme_passphrase_cb_t 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. Some engines do not + even support an external passphrase callback at all, in this case + the error code `GPG_ERR_NOT_SUPPORTED' is returned. + + The user can disable the use of a passphrase callback function by + calling `gpgme_set_passphrase_cb' with PASSFUNC being `NULL'. + + -- Function: void gpgme_get_passphrase_cb (gpgme_ctx_t CTX, + gpgme_passphrase_cb_t *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. + + +File: gpgme.info, Node: Progress Meter Callback, Next: Locale, Prev: Passphrase Callback, Up: Context Attributes + +7.4.8 Progress Meter Callback +----------------------------- + + -- Data type: void (*gpgme_progress_cb_t)(void *HOOK, const char +*WHAT, int TYPE, int CURRENT, int TOTAL) + The `gpgme_progress_cb_t' 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 (gpgme_ctx_t CTX, + gpgme_progress_cb_t 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'. + + -- Function: void gpgme_get_progress_cb (gpgme_ctx_t CTX, + gpgme_progress_cb_t *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. + + +File: gpgme.info, Node: Locale, Prev: Progress Meter Callback, Up: Context Attributes + +7.4.9 Locale +------------ + +A locale setting can be associated with a context. This locale is +passed to the crypto engine, and used for applications like the PIN +entry, which is displayed to the user when entering a passphrase is +required. + + The default locale is used to initialize the locale setting of all +contexts created afterwards. + + -- Function: gpgme_error_t gpgme_set_locale (gpgme_ctx_t CTX, + int CATEGORY, const char *VALUE) + The function `gpgme_set_locale' sets the locale of the context + CTX, or the default locale if CTX is a null pointer. + + The locale settings that should be changed are specified by + CATEGORY. Supported categories are `LC_CTYPE', `LC_MESSAGES', and + `LC_ALL', which is a wildcard you can use if you want to change + all the categories at once. + + The value to be used for the locale setting is VALUE, which will + be copied to GPGME's internal data structures. VALUE can be a + null pointer, which disables setting the locale, and will make PIN + entry and other applications use their default setting, which is + usually not what you want. + + Note that the settings are only used if the application runs on a + text terminal, and that the settings should fit the configuration + of the output terminal. Normally, it is sufficient to initialize + the default value at startup. + + The function returns an error if not enough memory is available. + + +File: gpgme.info, Node: Key Management, Next: Trust Item Management, Prev: Context Attributes, Up: Contexts + +7.5 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: gpgme_sub_key_t + The `gpgme_sub_key_t' type is a pointer to a subkey structure. + Sub keys are one component of a `gpgme_key_t' object. In fact, + subkeys are those parts that contains the real information about + the individual cryptographic keys that belong to the same key + object. One `gpgme_key_t' can contain several subkeys. The first + subkey in the linked list is also called the primary key. + + The subkey structure has the following members: + + `gpgme_sub_key_t next' + This is a pointer to the next subkey structure in the linked + list, or `NULL' if this is the last element. + + `unsigned int revoked : 1' + This is true if the subkey is revoked. + + `unsigned int expired : 1' + This is true if the subkey is expired. + + `unsigned int disabled : 1' + This is true if the subkey is disabled. + + `unsigned int invalid : 1' + This is true if the subkey is invalid. + + `unsigned int can_encrypt : 1' + This is true if the subkey can be used for encryption. + + `unsigned int can_sign : 1' + This is true if the subkey can be used to create data + signatures. + + `unsigned int can_certify : 1' + This is true if the subkey can be used to create key + certificates. + + `unsigned int can_authenticate : 1' + This is true if the subkey can be used for authentication. + + `unsigned int is_qualified : 1' + This is true if the subkey can be used for qualified + signatures according to local government regulations. + + `unsigned int secret : 1' + This is true if the subkey is a secret key. Note that it + will be false if the key is actually a stub key; i.e. a + secret key operation is currently not possible (offline-key). + + `gpgme_pubkey_algo_t pubkey_algo' + This is the public key algorithm supported by this subkey. + + `unsigned int length' + This is the length of the subkey (in bits). + + `char *keyid' + This is the key ID of the subkey in hexadecimal digits. + + `char *fpr' + This is the fingerprint of the subkey in hexadecimal digits, + if available. + + `long int timestamp' + This is the creation timestamp of the subkey. This is -1 if + the timestamp is invalid, and 0 if it is not available. + + `long int expires' + This is the expiration timestamp of the subkey, or 0 if the + subkey does not expire. + + -- Data type: gpgme_key_sig_t + The `gpgme_key_sig_t' type is a pointer to a key signature + structure. Key signatures are one component of a `gpgme_key_t' + object, and validate user IDs on the key. + + 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 can be expensive to retrieve all signatures of + a key. + + The signature notations on a key signature are only available if + the key was retrieved via a listing operation with the + `GPGME_KEYLIST_MODE_SIG_NOTATIONS' mode enabled, because it can be + expensive to retrieve all signature notations. + + The key signature structure has the following members: + + `gpgme_key_sig_t next' + This is a pointer to the next key signature structure in the + linked list, or `NULL' if this is the last element. + + `unsigned int revoked : 1' + This is true if the key signature is a revocation signature. + + `unsigned int expired : 1' + This is true if the key signature is expired. + + `unsigned int invalid : 1' + This is true if the key signature is invalid. + + `unsigned int exportable : 1' + This is true if the key signature is exportable. + + `gpgme_pubkey_algo_t pubkey_algo' + This is the public key algorithm used to create the signature. + + `char *keyid' + This is the key ID of the key (in hexadecimal digits) used to + create the signature. + + `long int timestamp' + This is the creation timestamp of the key signature. This is + -1 if the timestamp is invalid, and 0 if it is not available. + + `long int expires' + This is the expiration timestamp of the key signature, or 0 + if the key signature does not expire. + + `gpgme_error_t status' + This is the status of the signature and has the same meaning + as the member of the same name in a `gpgme_signature_t' + object. + + `unsigned int sig_class' + This specifies the signature class of the key signature. The + meaning is specific to the crypto engine. + + `char *uid' + This is the main user ID of the key used to create the + signature. + + `char *name' + This is the name component of `uid', if available. + + `char *comment' + This is the comment component of `uid', if available. + + `char *email' + This is the email component of `uid', if available. + + `gpgme_sig_notation_t notations' + This is a linked list with the notation data and policy URLs. + + -- Data type: gpgme_user_id_t + A user ID is a component of a `gpgme_key_t' object. One key can + have many user IDs. The first one in the list is the main (or + primary) user ID. + + The user ID structure has the following members. + + `gpgme_user_id_t next' + This is a pointer to the next user ID structure in the linked + list, or `NULL' if this is the last element. + + `unsigned int revoked : 1' + This is true if the user ID is revoked. + + `unsigned int invalid : 1' + This is true if the user ID is invalid. + + `gpgme_validity_t validity' + This specifies the validity of the user ID. + + `char *uid' + This is the user ID string. + + `char *name' + This is the name component of `uid', if available. + + `char *comment' + This is the comment component of `uid', if available. + + `char *email' + This is the email component of `uid', if available. + + `gpgme_key_sig_t signatures' + This is a linked list with the signatures on this user ID. + + -- Data type: gpgme_key_t + The `gpgme_key_t' type is a pointer to a key object. It has the + following members: + + `gpgme_keylist_mode_t keylist_mode' + The keylist mode that was active when the key was retrieved. + + `unsigned int revoked : 1' + This is true if the key is revoked. + + `unsigned int expired : 1' + This is true if the key is expired. + + `unsigned int disabled : 1' + This is true if the key is disabled. + + `unsigned int invalid : 1' + This is true if the key is invalid. This might have several + reasons, for a example for the S/MIME backend, it will be set + in during key listsing if the key could not be validated due + to a missing certificates or unmatched policies. + + `unsigned int can_encrypt : 1' + This is true if the key (ie one of its subkeys) can be used + for encryption. + + `unsigned int can_sign : 1' + This is true if the key (ie one of its subkeys) can be used + to create data signatures. + + `unsigned int can_certify : 1' + This is true if the key (ie one of its subkeys) can be used + to create key certificates. + + `unsigned int can_authenticate : 1' + This is true if the key (ie one of its subkeys) can be used + for authentication. + + `unsigned int is_qualified : 1' + This is true if the key can be used for qualified signatures + according to local government regulations. + + `unsigned int secret : 1' + This is true if the key is a secret key. Note, that this + will always be true even if the corresponding subkey flag may + be false (offline/stub keys). + + `gpgme_protocol_t protocol' + This is the protocol supported by this key. + + `char *issuer_serial' + If `protocol' is `GPGME_PROTOCOL_CMS', then this is the + issuer serial. + + `char *issuer_name' + If `protocol' is `GPGME_PROTOCOL_CMS', then this is the + issuer name. + + `char *chain_id' + If `protocol' is `GPGME_PROTOCOL_CMS', then this is the chain + ID, which can be used to built the certificate chain. + + `gpgme_validity_t owner_trust' + If `protocol' is `GPGME_PROTOCOL_OpenPGP', then this is the + owner trust. + + `gpgme_sub_key_t subkeys' + This is a linked list with the subkeys of the key. The first + subkey in the list is the primary key and usually available. + + `gpgme_user_id_t uids' + This is a linked list with the user IDs of the key. The + first user ID in the list is the main (or primary) user ID. + +* Menu: + +* Listing Keys:: Browsing the list of available keys. +* Information About Keys:: Requesting detailed information about keys. +* Key Signatures:: Listing the signatures on a key. +* Manipulating Keys:: Operations on keys. +* Generating Keys:: Creating new key pairs. +* Exporting Keys:: Retrieving key data from the key ring. +* Importing Keys:: Adding keys to the key ring. +* Deleting Keys:: Removing keys from the key ring. +* Changing Passphrases:: Change the passphrase of a key. +* Advanced Key Editing:: Advanced key edit operation. + + +File: gpgme.info, Node: Listing Keys, Next: Information About Keys, Up: Key Management + +7.5.1 Listing Keys +------------------ + + -- Function: gpgme_error_t gpgme_op_keylist_start (gpgme_ctx_t 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. Note that the + total length of the pattern is restricted to an engine-specific + maximum (a couple of hundred characters are usually accepted). The + pattern should be used to restrict the search to a certain common + name or user, not to list many specific keys at once by listing + their fingerprints or key IDs. + + If 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 `GPG_ERR_EOF'), or + `gpgme_op_keylist_end' is called to finish the operation. + + The function returns the error code `GPG_ERR_INV_VALUE' if CTX is + not a valid pointer, and passes through any errors that are + reported by the crypto engine support routines. + + -- Function: gpgme_error_t gpgme_op_keylist_ext_start + (gpgme_ctx_t 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. Note that the total length of all patterns + is restricted to an engine-specific maximum (the exact limit also + depends on the number of patterns and amount of quoting required, + but a couple of hundred characters are usually accepted). + Patterns should be used to restrict the search to a certain common + name or user, not to list many specific keys at once by listing + their fingerprints or key IDs. + + If 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 `GPG_ERR_EOF'), or + `gpgme_op_keylist_end' is called to finish the operation. + + The function returns the error code `GPG_ERR_INV_VALUE' if CTX is + not a valid pointer, and passes through any errors that are + reported by the crypto engine support routines. + + -- Function: gpgme_error_t gpgme_op_keylist_next (gpgme_ctx_t CTX, + gpgme_key_t *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. + *Note Manipulating Keys::. + + This is the only way to get at `gpgme_key_t' objects in GPGME. + + If the last key in the list has already been returned, + `gpgme_op_keylist_next' returns `GPG_ERR_EOF'. + + The function returns the error code `GPG_ERR_INV_VALUE' if CTX or + R_KEY is not a valid pointer, and `GPG_ERR_ENOMEM' if there is not + enough memory for the operation. + + -- Function: gpgme_error_t gpgme_op_keylist_end (gpgme_ctx_t CTX) + The function `gpgme_op_keylist_end' ends a pending key list + operation in the context CTX. + + After the operation completed successfully, the result of the key + listing operation can be retrieved with `gpgme_op_keylist_result'. + + The function returns the error code `GPG_ERR_INV_VALUE' if CTX is + not a valid pointer, and `GPG_ERR_ENOMEM' 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: + + gpgme_ctx_t ctx; + gpgme_key_t key; + gpgme_error_t err = gpgme_new (&ctx); + + if (!err) + { + err = gpgme_op_keylist_start (ctx, "g10code", 0); + while (!err) + { + err = gpgme_op_keylist_next (ctx, &key); + if (err) + break; + printf ("%s:", key->subkeys->keyid); + if (key->uids && key->uids->name) + printf (" %s", key->uids->name); + if (key->uids && key->uids->email) + printf (" <%s>", key->uids->email); + putchar ('\n'); + gpgme_key_release (key); + } + gpgme_release (ctx); + } + if (gpg_err_code (err) != GPG_ERR_EOF) + { + fprintf (stderr, "can not list keys: %s\n", gpgme_strerror (err)); + exit (1); + } + + -- Data type: gpgme_keylist_result_t + This is a pointer to a structure used to store the result of a + `gpgme_op_keylist_*' operation. After successfully ending a key + listing operation, you can retrieve the pointer to the result with + `gpgme_op_keylist_result'. The structure contains the following + member: + + `unsigned int truncated : 1' + This is true if the crypto backend had to truncate the + result, and less than the desired keys could be listed. + + -- Function: gpgme_keylist_result_t gpgme_op_keylist_result + (gpgme_ctx_t CTX) + The function `gpgme_op_keylist_result' returns a + `gpgme_keylist_result_t' pointer to a structure holding the result + of a `gpgme_op_keylist_*' operation. The pointer is only valid if + the last operation on the context was a key listing operation, and + if this operation finished successfully. The returned pointer is + only valid until the next operation is started on the context. + + In a simple program, for which a blocking operation is acceptable, +the following function can be used to retrieve a single key. + + -- Function: gpgme_error_t gpgme_get_key (gpgme_ctx_t CTX, + const char *FPR, gpgme_key_t *R_KEY, int SECRET) + The function `gpgme_get_key' gets the key with the fingerprint (or + key ID) FPR from the crypto backend and return it in R_KEY. If + SECRET is true, get the secret key. The currently active keylist + mode is used to retrieve the key. The key will have one reference + for the user. + + If the key is not found in the keyring, `gpgme_get_key' returns + the error code `GPG_ERR_EOF' and *R_KEY will be set to `NULL'. + + The function returns the error code `GPG_ERR_INV_VALUE' if CTX or + R_KEY is not a valid pointer or FPR is not a fingerprint or key + ID, `GPG_ERR_AMBIGUOUS_NAME' if the key ID was not a unique + specifier for a key, and `GPG_ERR_ENOMEM' if at some time during + the operation there was not enough memory available. + + +File: gpgme.info, Node: Information About Keys, Next: Key Signatures, Prev: Listing Keys, Up: Key Management + +7.5.2 Information About Keys +---------------------------- + +Please see the beginning of this section for more information about +`gpgme_key_t' objects. + + -- Data type: gpgme_validity_t + The `gpgme_validity_t' 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". + + The following interfaces are deprecated and only provided for +backward compatibility. Don't use them. They will be removed in a +future version of GPGME. + + -- Data type: gpgme_attr_t + The `gpgme_attr_t' 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 + GPGME_KEY_T object. The first one (with index 0) is the + primary user ID. The user ID is representable as a number. + + For trust items, this is the user ID associated with this + trust item. + + `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 number, and is `1' if the key is revoked, + and `0' otherwise. + + `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 to create data + 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 to create key + certificates. 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. + + -- Function: const char * gpgme_key_get_string_attr (gpgme_key_t KEY, + gpgme_attr_t 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'. + + -- Function: unsigned long gpgme_key_get_ulong_attr (gpgme_key_t KEY, + gpgme_attr_t 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'. + + +File: gpgme.info, Node: Key Signatures, Next: Manipulating Keys, Prev: Information About Keys, Up: Key Management + +7.5.3 Key Signatures +-------------------- + +The following interfaces are deprecated and only provided for backward +compatibility. Don't use them. They will be removed in a future +version of GPGME. + + 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: gpgme_attr_t + The `gpgme_attr_t' 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'. + + -- Function: const char * gpgme_key_sig_get_string_attr + (gpgme_key_t KEY, int UID_IDX, gpgme_attr_t 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'. + + -- Function: unsigned long gpgme_key_sig_get_ulong_attr + (gpgme_key_t KEY, int UID_IDX, gpgme_attr_t 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'. + + +File: gpgme.info, Node: Manipulating Keys, Next: Generating Keys, Prev: Key Signatures, Up: Key Management + +7.5.4 Manipulating Keys +----------------------- + + -- Function: void gpgme_key_ref (gpgme_key_t KEY) + The function `gpgme_key_ref' acquires an additional reference for + the key KEY. + + -- Function: void gpgme_key_unref (gpgme_key_t KEY) + The function `gpgme_key_unref' 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 following interface is deprecated and only provided for backward +compatibility. Don't use it. It will be removed in a future version +of GPGME. + + -- Function: void gpgme_key_release (gpgme_key_t KEY) + The function `gpgme_key_release' is equivalent to + `gpgme_key_unref'. + + +File: gpgme.info, Node: Generating Keys, Next: Exporting Keys, Prev: Manipulating Keys, Up: Key Management + +7.5.5 Generating Keys +--------------------- + + -- Function: gpgme_error_t gpgme_op_genkey (gpgme_ctx_t CTX, + const char *PARMS, gpgme_data_t PUBLIC, gpgme_data_t SECRET) + The function `gpgme_op_genkey' generates a new key pair in the + context CTX. The meaning of PUBLIC and SECRET depends on the + crypto backend. + + GnuPG does not support PUBLIC and SECRET, they should be `NULL'. + GnuPG will generate a key pair and add it to the standard key + ring. The fingerprint of the generated key is available with + `gpgme_op_genkey_result'. + + GpgSM requires PUBLIC to be a writable data object. GpgSM will + generate a secret key (which will be stored by `gpg-agent', and + return a certificate request in PUBLIC, which then needs to be + signed by the certification authority and imported before it can be + used. GpgSM does not make the fingerprint available. + + The argument 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 (all parameters of OpenPGP key generation are + documented in the GPG manual): + + <GnupgKeyParms format="internal"> + Key-Type: default + Subkey-Type: default + Name-Real: Joe Tester + Name-Comment: with stupid passphrase + Name-Email: joe@foo.bar + Expire-Date: 0 + Passphrase: abc + </GnupgKeyParms> + + Here is an example for GpgSM as the crypto engine (all parameters + of OpenPGP key generation are documented in the GPGSM manual): + + <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 the crypto + backend. Control statements are not allowed. + + After the operation completed successfully, the result can be + retrieved with `gpgme_op_genkey_result'. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation could be started successfully, `GPG_ERR_INV_VALUE' if + PARMS is not a valid XML string, `GPG_ERR_NOT_SUPPORTED' if PUBLIC + or SECRET is not valid, and `GPG_ERR_GENERAL' if no key was + created by the backend. + + -- Function: gpgme_error_t gpgme_op_genkey_start (gpgme_ctx_t CTX, + const char *PARMS, gpgme_data_t PUBLIC, gpgme_data_t SECRET) + The function `gpgme_op_genkey_start' initiates a `gpgme_op_genkey' + operation. It can be completed by calling `gpgme_wait' on the + context. *Note Waiting For Completion::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation could be started successfully, `GPG_ERR_INV_VALUE' if + PARMS is not a valid XML string, and `GPG_ERR_NOT_SUPPORTED' if + PUBLIC or SECRET is not `NULL'. + + -- Data type: gpgme_genkey_result_t + This is a pointer to a structure used to store the result of a + `gpgme_op_genkey' operation. After successfully generating a key, + you can retrieve the pointer to the result with + `gpgme_op_genkey_result'. The structure contains the following + members: + + `unsigned int primary : 1' + This is a flag that is set to 1 if a primary key was created + and to 0 if not. + + `unsigned int sub : 1' + This is a flag that is set to 1 if a subkey was created and + to 0 if not. + + `char *fpr' + This is the fingerprint of the key that was created. If both + a primary and a sub key were generated, the fingerprint of + the primary key will be returned. If the crypto engine does + not provide the fingerprint, `fpr' will be a null pointer. + + -- Function: gpgme_genkey_result_t gpgme_op_genkey_result + (gpgme_ctx_t CTX) + The function `gpgme_op_genkey_result' returns a + `gpgme_genkey_result_t' pointer to a structure holding the result + of a `gpgme_op_genkey' operation. The pointer is only valid if the + last operation on the context was a `gpgme_op_genkey' or + `gpgme_op_genkey_start' operation, and if this operation finished + successfully. The returned pointer is only valid until the next + operation is started on the context. + + +File: gpgme.info, Node: Exporting Keys, Next: Importing Keys, Prev: Generating Keys, Up: Key Management + +7.5.6 Exporting Keys +-------------------- + +Exporting keys means the same as running `gpg' with the command +`--export'. However, a mode flag can be used to change the way the +export works. The available mode flags are described below, they may +be or-ed together. + +`GPGME_EXPORT_MODE_EXTERN' + If this bit is set, the output is send directly to the default + keyserver. This is currently only allowed for OpenPGP keys. It is + good practise to not send more than a few dozens key to a + keyserver at one time. Using this flag requires that the KEYDATA + argument of the export function is set to `NULL'. + +`GPGME_EXPORT_MODE_MINIMAL' + If this bit is set, the smallest possible key is exported. For + OpenPGP keys it removes all signatures except for the latest + self-signatures. For X.509 keys it has no effect. + + + -- Function: gpgme_error_t gpgme_op_export (gpgme_ctx_t CTX, + const char *PATTERN, gpgme_export_mode_t MODE, + gpgme_data_t KEYDATA) + The function `gpgme_op_export' extracts public keys and returns + them in the data buffer KEYDATA. The output format of the key + data returned is determined by the ASCII armor attribute set for + the context CTX, or, if that is not set, by the encoding specified + for KEYDATA. + + 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. + + MODE is usually 0; other values are described above. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation completed successfully, `GPG_ERR_INV_VALUE' if KEYDATA + is not a valid empty data buffer, and passes through any errors + that are reported by the crypto engine support routines. + + -- Function: gpgme_error_t gpgme_op_export_start (gpgme_ctx_t CTX, + const char *PATTERN, gpgme_export_mode_t MODE, + gpgme_data_t KEYDATA) + The function `gpgme_op_export_start' initiates a `gpgme_op_export' + operation. It can be completed by calling `gpgme_wait' on the + context. *Note Waiting For Completion::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation could be started successfully, and `GPG_ERR_INV_VALUE' + if KEYDATA is not a valid empty data buffer. + + -- Function: gpgme_error_t gpgme_op_export_ext (gpgme_ctx_t CTX, + const char *PATTERN[], gpgme_export_mode_t MODE, + gpgme_data_t KEYDATA) + The function `gpgme_op_export' extracts public keys and returns + them in the data buffer KEYDATA. The output format of the key + data returned is determined by the ASCII armor attribute set for + the context CTX, or, if that is not set, by the encoding specified + for KEYDATA. + + 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. + + MODE is usually 0; other values are described above. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation completed successfully, `GPG_ERR_INV_VALUE' if KEYDATA + is not a valid empty data buffer, and passes through any errors + that are reported by the crypto engine support routines. + + -- Function: gpgme_error_t gpgme_op_export_ext_start (gpgme_ctx_t CTX, + const char *PATTERN[], gpgme_export_mode_t MODE, + gpgme_data_t KEYDATA) + The function `gpgme_op_export_ext_start' initiates a + `gpgme_op_export_ext' operation. It can be completed by calling + `gpgme_wait' on the context. *Note Waiting For Completion::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation could be started successfully, and `GPG_ERR_INV_VALUE' + if KEYDATA is not a valid empty data buffer. + + -- Function: gpgme_error_t gpgme_op_export_keys (gpgme_ctx_t CTX, + gpgme_key_t keys[], gpgme_export_mode_t MODE, + gpgme_data_t KEYDATA) + The function `gpgme_op_export_keys' extracts public keys and + returns them in the data buffer KEYDATA. The output format of the + key data returned is determined by the ASCII armor attribute set + for the context CTX, or, if that is not set, by the encoding + specified for KEYDATA. + + The keys to export are taken form the `NULL' terminated array + KEYS. Only keys of the the currently selected protocol of CTX + which do have a fingerprint set are considered for export. Other + keys specified by the KEYS are ignored. In particular OpenPGP + keys retrieved via an external key listing are not included. + + MODE is usually 0; other values are described above. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation completed successfully, `GPG_ERR_INV_VALUE' if KEYDATA + is not a valid empty data buffer, `GPG_ERR_NO_DATA' if no useful + keys are in KEYS and passes through any errors that are reported + by the crypto engine support routines. + + -- Function: gpgme_error_t gpgme_op_export_keys_start + (gpgme_ctx_t CTX, gpgme_key_t KEYS[], + gpgme_export_mode_t MODE, gpgme_data_t KEYDATA) + The function `gpgme_op_export_keys_start' initiates a + `gpgme_op_export_ext' operation. It can be completed by calling + `gpgme_wait' on the context. *Note Waiting For Completion::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation could be started successfully, and `GPG_ERR_INV_VALUE' + if KEYDATA is not a valid empty data buffer, `GPG_ERR_NO_DATA' if + no useful keys are in KEYS and passes through any errors that are + reported by the crypto engine support routines. + + +File: gpgme.info, Node: Importing Keys, Next: Deleting Keys, Prev: Exporting Keys, Up: Key Management + +7.5.7 Importing Keys +-------------------- + +Importing keys means the same as running `gpg' with the command +`--import'. + + -- Function: gpgme_error_t gpgme_op_import (gpgme_ctx_t CTX, + gpgme_data_t 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. + + After the operation completed successfully, the result can be + retrieved with `gpgme_op_import_result'. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + import was completed successfully, `GPG_ERR_INV_VALUE' if KEYDATA + if CTX or KEYDATA is not a valid pointer, and `GPG_ERR_NO_DATA' if + KEYDATA is an empty data buffer. + + -- Function: gpgme_error_t gpgme_op_import_start (gpgme_ctx_t CTX, + gpgme_data_t KEYDATA) + The function `gpgme_op_import_start' initiates a `gpgme_op_import' + operation. It can be completed by calling `gpgme_wait' on the + context. *Note Waiting For Completion::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + import could be started successfully, `GPG_ERR_INV_VALUE' if + KEYDATA if CTX or KEYDATA is not a valid pointer, and + `GPG_ERR_NO_DATA' if KEYDATA is an empty data buffer. + + -- Function: gpgme_error_t gpgme_op_import_keys (gpgme_ctx_t CTX, + gpgme_key_t *KEYS) + The function `gpgme_op_import_keys' adds the keys described by the + `NULL' terminated array KEYS to the key ring of the crypto engine + used by CTX. This function is the general interface to move a key + from one crypto engine to another as long as they are compatible. + In particular it is used to actually import and make keys + permanent which have been retrieved from an external source (i.e. + using `GPGME_KEYLIST_MODE_EXTERN'). (1) + + Only keys of the the currently selected protocol of CTX are + considered for import. Other keys specified by the KEYS are + ignored. As of now all considered keys must have been retrieved + using the same method, that is the used key listing mode must be + identical. + + After the operation completed successfully, the result can be + retrieved with `gpgme_op_import_result'. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + import was completed successfully, `GPG_ERR_INV_VALUE' if KEYDATA + if CTX or KEYDATA is not a valid pointer, `GPG_ERR_CONFLICT' if + the key listing mode does not match, and `GPG_ERR_NO_DATA' if no + keys are considered for export. + + -- Function: gpgme_error_t gpgme_op_import_keys_start + (gpgme_ctx_t CTX, gpgme_key_t *KEYS) + The function `gpgme_op_import_keys_start' initiates a + `gpgme_op_import_keys' operation. It can be completed by calling + `gpgme_wait' on the context. *Note Waiting For Completion::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + import was completed successfully, `GPG_ERR_INV_VALUE' if KEYDATA + if CTX or KEYDATA is not a valid pointer, `GPG_ERR_CONFLICT' if + the key listing mode does not match, and `GPG_ERR_NO_DATA' if no + keys are considered for export. + + -- Data type: gpgme_import_status_t + This is a pointer to a structure used to store a part of the + result of a `gpgme_op_import' operation. For each considered key + one status is added that contains information about the result of + the import. The structure contains the following members: + + `gpgme_import_status_t next' + This is a pointer to the next status structure in the linked + list, or `NULL' if this is the last element. + + `char *fpr' + This is the fingerprint of the key that was considered. + + `gpgme_error_t result' + If the import was not successful, this is the error value + that caused the import to fail. Otherwise the error code is + `GPG_ERR_NO_ERROR'. + + `unsigned int status' + This is a bit-wise OR of the following flags that give more + information about what part of the key was imported. If the + key was already known, this might be 0. + + `GPGME_IMPORT_NEW' + The key was new. + + `GPGME_IMPORT_UID' + The key contained new user IDs. + + `GPGME_IMPORT_SIG' + The key contained new signatures. + + `GPGME_IMPORT_SUBKEY' + The key contained new sub keys. + + `GPGME_IMPORT_SECRET' + The key contained a secret key. + + -- Data type: gpgme_import_result_t + This is a pointer to a structure used to store the result of a + `gpgme_op_import' operation. After a successful import operation, + you can retrieve the pointer to the result with + `gpgme_op_import_result'. The structure contains the following + members: + + `int considered' + The total number of considered keys. + + `int no_user_id' + The number of keys without user ID. + + `int imported' + The total number of imported keys. + + `imported_rsa' + The number of imported RSA keys. + + `unchanged' + The number of unchanged keys. + + `new_user_ids' + The number of new user IDs. + + `new_sub_keys' + The number of new sub keys. + + `new_signatures' + The number of new signatures. + + `new_revocations' + The number of new revocations. + + `secret_read' + The total number of secret keys read. + + `secret_imported' + The number of imported secret keys. + + `secret_unchanged' + The number of unchanged secret keys. + + `not_imported' + The number of keys not imported. + + `gpgme_import_status_t imports' + A list of gpgme_import_status_t objects which contain more + information about the keys for which an import was attempted. + + -- Function: gpgme_import_result_t gpgme_op_import_result + (gpgme_ctx_t CTX) + The function `gpgme_op_import_result' returns a + `gpgme_import_result_t' pointer to a structure holding the result + of a `gpgme_op_import' operation. The pointer is only valid if + the last operation on the context was a `gpgme_op_import' or + `gpgme_op_import_start' operation, and if this operation finished + successfully. The returned pointer is only valid until the next + operation is started on the context. + + The following interface is deprecated and only provided for backward +compatibility. Don't use it. It will be removed in a future version +of GPGME. + + -- Function: gpgme_error_t gpgme_op_import_ext (gpgme_ctx_t CTX, + gpgme_data_t KEYDATA, int *NR) + The function `gpgme_op_import_ext' is equivalent to: + + gpgme_error_t err = gpgme_op_import (ctx, keydata); + if (!err) + { + gpgme_import_result_t result = gpgme_op_import_result (ctx); + *nr = result->considered; + } + + ---------- Footnotes ---------- + + (1) Thus it is a replacement for the usual workaround of exporting +and then importing a key to make an X.509 key permanent. + + +File: gpgme.info, Node: Deleting Keys, Next: Changing Passphrases, Prev: Importing Keys, Up: Key Management + +7.5.8 Deleting Keys +------------------- + + -- Function: gpgme_error_t gpgme_op_delete (gpgme_ctx_t CTX, + const gpgme_key_t 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 the error code `GPG_ERR_NO_ERROR' if the key + was deleted successfully, `GPG_ERR_INV_VALUE' if CTX or KEY is not + a valid pointer, `GPG_ERR_NO_PUBKEY' if KEY could not be found in + the keyring, `GPG_ERR_AMBIGUOUS_NAME' if the key was not specified + unambiguously, and `GPG_ERR_CONFLICT' if the secret key for KEY is + available, but ALLOW_SECRET is zero. + + -- Function: gpgme_error_t gpgme_op_delete_start (gpgme_ctx_t CTX, + const gpgme_key_t 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. *Note Waiting For Completion::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation was started successfully, and `GPG_ERR_INV_VALUE' if CTX + or KEY is not a valid pointer. + + +File: gpgme.info, Node: Changing Passphrases, Next: Advanced Key Editing, Prev: Deleting Keys, Up: Key Management + +7.5.9 Changing Passphrases +-------------------------- + + -- Function: gpgme_error_t gpgme_op_passwd (gpgme_ctx_t CTX, + const gpgme_key_t KEY, unsigned int FLAGS) + The function `gpgme_op_passwd' changes the passphrase of the + private key associated with KEY. The only allowed value for FLAGS + is `0'. The backend engine will usually popup a window to ask for + the old and the new passphrase. Thus this function is not useful + in a server application (where passphrases are not required + anyway). + + Note that old `gpg' engines (before version 2.0.15) do not support + this command and will silently ignore it. + + -- Function: gpgme_error_t gpgme_op_passwd_start (gpgme_ctx_t CTX, + const gpgme_key_t KEY, unsigned int FLAGS) + The function `gpgme_op_passwd_start' initiates a `gpgme_op_passwd' + operation. It can be completed by calling `gpgme_wait' on the + context. *Note Waiting For Completion::. + + The function returns `0' if the operation was started successfully, + and an error code if one of the arguments is not valid or the + oepration could not be started. + + +File: gpgme.info, Node: Advanced Key Editing, Prev: Changing Passphrases, Up: Key Management + +7.5.10 Advanced Key Editing +--------------------------- + + -- Data type: gpgme_error_t (*gpgme_edit_cb_t) (void *HANDLE, +gpgme_status_code_t STATUS, const char *ARGS, int FD) + The `gpgme_edit_cb_t' type is the type of functions which GPGME + calls if it a key edit operation is on-going. The status code + STATUS and the argument line ARGS are passed through by GPGME from + the crypto engine. The file descriptor FD is -1 for normal status + messages. If STATUS indicates a command rather than a status + message, the response to the command should be written to FD. The + HANDLE is provided by the user at start of operation. + + The function should return `GPG_ERR_NO_ERROR' or an error value. + + -- Function: gpgme_error_t gpgme_op_edit (gpgme_ctx_t CTX, + gpgme_key_t KEY, gpgme_edit_cb_t FNC, void *HANDLE, + gpgme_data_t OUT) + The function `gpgme_op_edit' processes the key KEY interactively, + using the edit callback function FNC with the handle HANDLE. The + callback is invoked for every status and command request from the + crypto engine. The output of the crypto engine is written to the + data object OUT. + + Note that the protocol between the callback function and the crypto + engine is specific to the crypto engine and no further support in + implementing this protocol correctly is provided by GPGME. + + The function returns the error code `GPG_ERR_NO_ERROR' if the edit + operation completes successfully, `GPG_ERR_INV_VALUE' if CTX or + KEY is not a valid pointer, and any error returned by the crypto + engine or the edit callback handler. + + -- Function: gpgme_error_t gpgme_op_edit_start (gpgme_ctx_t CTX, + gpgme_key_t KEY, gpgme_edit_cb_t FNC, void *HANDLE, + gpgme_data_t OUT) + The function `gpgme_op_edit_start' initiates a `gpgme_op_edit' + operation. It can be completed by calling `gpgme_wait' on the + context. *Note Waiting For Completion::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation was started successfully, and `GPG_ERR_INV_VALUE' if CTX + or KEY is not a valid pointer. + + -- Function: gpgme_error_t gpgme_op_card_edit (gpgme_ctx_t CTX, + gpgme_key_t KEY, gpgme_edit_cb_t FNC, void *HANDLE, + gpgme_data_t OUT) + The function `gpgme_op_card_edit' is analogous to `gpgme_op_edit', + but should be used to process the smart card corresponding to the + key KEY. + + -- Function: gpgme_error_t gpgme_op_card_edit_start (gpgme_ctx_t CTX, + gpgme_key_t KEY, gpgme_edit_cb_t FNC, void *HANDLE, + gpgme_data_t OUT) + The function `gpgme_op_card_edit_start' initiates a + `gpgme_op_card_edit' operation. It can be completed by calling + `gpgme_wait' on the context. *Note Waiting For Completion::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation was started successfully, and `GPG_ERR_INV_VALUE' if CTX + or KEY is not a valid pointer. + + +File: gpgme.info, Node: Trust Item Management, Next: Crypto Operations, Prev: Key Management, Up: Contexts + +7.6 Trust Item Management +========================= + +*Caution:* The trust items interface is experimental. + + -- Data type: gpgme_trust_item_t + The `gpgme_trust_item_t' type is a pointer to a trust item object. + It has the following members: + + `char *keyid' + This is a string describing the key to which this trust items + belongs. + + `int type' + This is the type of the trust item. A value of 1 refers to a + key, a value of 2 refers to a user ID. + + `int level' + This is the trust level. + + `char *owner_trust' + The owner trust if `type' is 1. + + `char *validity' + The calculated validity. + + `char *name' + The user name if `type' is 2. + +* Menu: + +* Listing Trust Items:: Browsing the list of available trust items. +* Information About Trust Items:: Requesting information about trust items. +* Manipulating Trust Items:: Operations on trust items. + + +File: gpgme.info, Node: Listing Trust Items, Next: Information About Trust Items, Up: Trust Item Management + +7.6.1 Listing Trust Items +------------------------- + + -- Function: gpgme_error_t gpgme_op_trustlist_start (gpgme_ctx_t 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 `GPG_ERR_EOF'), or + `gpgme_op_trustlist_end' is called to finish the operation. + + The function returns the error code `GPG_ERR_INV_VALUE' if CTX is + not a valid pointer, and passes through any errors that are + reported by the crypto engine support routines. + + -- Function: gpgme_error_t gpgme_op_trustlist_next (gpgme_ctx_t CTX, + gpgme_trust_item_t *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'. *Note Manipulating Trust Items::. + + This is the only way to get at `gpgme_trust_item_t' objects in + GPGME. + + If the last trust item in the list has already been returned, + `gpgme_op_trustlist_next' returns `GPG_ERR_EOF'. + + The function returns the error code `GPG_ERR_INV_VALUE' if CTX or + R_ITEM is not a valid pointer, and `GPG_ERR_ENOMEM' if there is + not enough memory for the operation. + + -- Function: gpgme_error_t gpgme_op_trustlist_end (gpgme_ctx_t CTX) + The function `gpgme_op_trustlist_end' ends a pending trust list + operation in the context CTX. + + The function returns the error code `GPG_ERR_INV_VALUE' if CTX is + not a valid pointer, and `GPG_ERR_ENOMEM' if at some time during + the operation there was not enough memory available. + + +File: gpgme.info, Node: Information About Trust Items, Next: Manipulating Trust Items, Prev: Listing Trust Items, Up: Trust Item Management + +7.6.2 Information About Trust Items +----------------------------------- + +The following interfaces are deprecated and only provided for backward +compatibility. Don't use them. They will be removed in a future +version of GPGME. + + Trust items have attributes which can be queried using the interfaces +below. The attribute identifiers are shared with those for key +attributes. *Note Information About Keys::. + + -- Function: const char * gpgme_trust_item_get_string_attr + (gpgme_trust_item_t ITEM, gpgme_attr_t 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'. + + -- Function: int gpgme_trust_item_get_int_attr + (gpgme_trust_item_t ITEM, gpgme_attr_t 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'. + + +File: gpgme.info, Node: Manipulating Trust Items, Prev: Information About Trust Items, Up: Trust Item Management + +7.6.3 Manipulating Trust Items +------------------------------ + + -- Function: void gpgme_trust_item_ref (gpgme_trust_item_t ITEM) + The function `gpgme_trust_item_ref' acquires an additional + reference for the trust item ITEM. + + -- Function: void gpgme_trust_item_unref (gpgme_trust_item_t ITEM) + The function `gpgme_trust_item_unref' releases a reference for the + trust item ITEM. If this was the last reference, the trust item + will be destroyed and all resources associated to it will be + released. + + The following interface is deprecated and only provided for backward +compatibility. Don't use it. It will be removed in a future version +of GPGME. + + -- Function: void gpgme_trust_item_release (gpgme_trust_item_t ITEM) + The function `gpgme_trust_item_release' is an alias for + `gpgme_trust_item_unref'. + + +File: gpgme.info, Node: Crypto Operations, Next: Run Control, Prev: Trust Item Management, Up: Contexts + +7.7 Crypto Operations +===================== + +Sometimes, the result of a crypto operation returns a list of invalid +keys encountered in processing the request. The following structure is +used to hold information about such a key. + + -- Data type: gpgme_invalid_key_t + This is a pointer to a structure used to store a part of the + result of a crypto operation which takes user IDs as one input + parameter. The structure contains the following members: + + `gpgme_invalid_key_t next' + This is a pointer to the next invalid key structure in the + linked list, or `NULL' if this is the last element. + + `char *fpr' + The fingerprint or key ID of the invalid key encountered. + + `gpgme_error_t reason' + An error code describing the reason why the key was found + invalid. + +* Menu: + +* Decrypt:: Decrypting a ciphertext. +* Verify:: Verifying a signature. +* Decrypt and Verify:: Decrypting a signed ciphertext. +* Sign:: Creating a signature. +* Encrypt:: Encrypting a plaintext. + + +File: gpgme.info, Node: Decrypt, Next: Verify, Up: Crypto Operations + +7.7.1 Decrypt +------------- + + -- Function: gpgme_error_t gpgme_op_decrypt (gpgme_ctx_t CTX, + gpgme_data_t CIPHER, gpgme_data_t 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 the error code `GPG_ERR_NO_ERROR' if the + ciphertext could be decrypted successfully, `GPG_ERR_INV_VALUE' if + CTX, CIPHER or PLAIN is not a valid pointer, `GPG_ERR_NO_DATA' if + CIPHER does not contain any data to decrypt, + `GPG_ERR_DECRYPT_FAILED' if CIPHER is not a valid cipher text, + `GPG_ERR_BAD_PASSPHRASE' if the passphrase for the secret key + could not be retrieved, and passes through any errors that are + reported by the crypto engine support routines. + + -- Function: gpgme_error_t gpgme_op_decrypt_start (gpgme_ctx_t CTX, + gpgme_data_t CIPHER, gpgme_data_t PLAIN) + The function `gpgme_op_decrypt_start' initiates a + `gpgme_op_decrypt' operation. It can be completed by calling + `gpgme_wait' on the context. *Note Waiting For Completion::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation could be started successfully, and `GPG_ERR_INV_VALUE' + if CIPHER or PLAIN is not a valid pointer. + + -- Data type: gpgme_recipient_t + This is a pointer to a structure used to store information about + the recipient of an encrypted text which is decrypted in a + `gpgme_op_decrypt' operation. This information (except for the + status field) is even available before the operation finished + successfully, for example in a passphrase callback. The structure + contains the following members: + + `gpgme_recipient_t next' + This is a pointer to the next recipient structure in the + linked list, or `NULL' if this is the last element. + + `gpgme_pubkey_algo_t' + The public key algorithm used in the encryption. + + `unsigned int wrong_key_usage : 1' + This is true if the key was not used according to its policy. + + `char *keyid' + This is the key ID of the key (in hexadecimal digits) used as + recipient. + + `gpgme_error_t status' + This is an error number with the error code GPG_ERR_NO_SECKEY + if the secret key for this recipient is not available, and 0 + otherwise. + + -- Data type: gpgme_decrypt_result_t + This is a pointer to a structure used to store the result of a + `gpgme_op_decrypt' operation. After successfully decrypting data, + you can retrieve the pointer to the result with + `gpgme_op_decrypt_result'. The structure contains the following + members: + + `char *unsupported_algorithm' + If an unsupported algorithm was encountered, this string + describes the algorithm that is not supported. + + `unsigned int wrong_key_usage : 1' + This is true if the key was not used according to its policy. + + `gpgme_recipient_t recipients' + This is a linked list of recipients to which this message was + encrypted. + + `char *file_name' + This is the filename of the original plaintext message file + if it is known, otherwise this is a null pointer. + + -- Function: gpgme_decrypt_result_t gpgme_op_decrypt_result + (gpgme_ctx_t CTX) + The function `gpgme_op_decrypt_result' returns a + `gpgme_decrypt_result_t' pointer to a structure holding the result + of a `gpgme_op_decrypt' operation. The pointer is only valid if + the last operation on the context was a `gpgme_op_decrypt' or + `gpgme_op_decrypt_start' operation. If the operation failed this + might be a `NULL' pointer. The returned pointer is only valid + until the next operation is started on the context. + + +File: gpgme.info, Node: Verify, Next: Decrypt and Verify, Prev: Decrypt, Up: Crypto Operations + +7.7.2 Verify +------------ + + -- Function: gpgme_error_t gpgme_op_verify (gpgme_ctx_t CTX, + gpgme_data_t SIG, gpgme_data_t SIGNED_TEXT, + gpgme_data_t PLAIN) + The function `gpgme_op_verify' verifies that the signature in the + data object SIG is a valid signature. If SIG is a detached + signature, then the signed text should be provided in SIGNED_TEXT + and PLAIN should be a null pointer. Otherwise, if SIG is a normal + (or cleartext) signature, SIGNED_TEXT should be a null pointer and + PLAIN should be a writable data object that will contain the + plaintext after successful verification. + + The results of the individual signature verifications can be + retrieved with `gpgme_op_verify_result'. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation could be completed successfully, `GPG_ERR_INV_VALUE' if + CTX, SIG or PLAIN is not a valid pointer, `GPG_ERR_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: gpgme_error_t gpgme_op_verify_start (gpgme_ctx_t CTX, + gpgme_data_t SIG, gpgme_data_t SIGNED_TEXT, + gpgme_data_t PLAIN) + The function `gpgme_op_verify_start' initiates a `gpgme_op_verify' + operation. It can be completed by calling `gpgme_wait' on the + context. *Note Waiting For Completion::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation could be started successfully, `GPG_ERR_INV_VALUE' if + CTX, SIG or PLAIN is not a valid pointer, and `GPG_ERR_NO_DATA' if + SIG or PLAIN does not contain any data to verify. + + -- Data type: gpgme_sig_notation_t + This is a pointer to a structure used to store a part of the + result of a `gpgme_op_verify' operation. The structure contains + the following members: + + `gpgme_sig_notation_t next' + This is a pointer to the next new signature notation + structure in the linked list, or `NULL' if this is the last + element. + + `char *name' + The name of the notation field. If this is `NULL', then the + member `value' will contain a policy URL. + + `int name_len' + The length of the `name' field. For strings the length is + counted without the trailing binary zero. + + `char *value' + The value of the notation field. If `name' is `NULL', then + this is a policy URL. + + `int value_len' + The length of the `value' field. For strings the length is + counted without the trailing binary zero. + + `gpgme_sig_notation_flags_t flags' + The accumulated flags field. This field contains the flags + associated with the notation data in an accumulated form + which can be used as an argument to the function + `gpgme_sig_notation_add'. The value `flags' is a bitwise-or + combination of one or multiple of the following bit values: + + `GPGME_SIG_NOTATION_HUMAN_READABLE' + The `GPGME_SIG_NOTATION_HUMAN_READABLE' symbol specifies + that the notation data is in human readable form + + `GPGME_SIG_NOTATION_CRITICAL' + The `GPGME_SIG_NOTATION_CRITICAL' symbol specifies that + the notation data is critical. + + + `unsigned int human_readable : 1' + This is true if the `GPGME_SIG_NOTATION_HUMAN_READABLE' flag + is set and false otherwise. This flag is only valid for + notation data, not for policy URLs. + + `unsigned int critical : 1' + This is true if the `GPGME_SIG_NOTATION_CRITICAL' flag is set + and false otherwise. This flag is valid for notation data + and policy URLs. + + + -- Data type: gpgme_signature_t + This is a pointer to a structure used to store a part of the + result of a `gpgme_op_verify' operation. The structure contains + the following members: + + `gpgme_signature_t next' + This is a pointer to the next new signature structure in the + linked list, or `NULL' if this is the last element. + + `gpgme_sigsum_t summary' + This is a bit vector giving a summary of the signature + status. It provides an easy interface to a defined semantic + of the signature status. Checking just one bit is sufficient + to see whether a signature is valid without any restrictions. + + The defined bits are: + `GPGME_SIGSUM_VALID' + The signature is fully valid. + + `GPGME_SIGSUM_GREEN' + The signature is good but one might want to display some + extra information. Check the other bits. + + `GPGME_SIGSUM_RED' + The signature is bad. It might be useful to check other + bits and display more information, i.e. a revoked + certificate might not render a signature invalid when + the message was received prior to the cause for the + revocation. + + `GPGME_SIGSUM_KEY_REVOKED' + The key or at least one certificate has been revoked. + + `GPGME_SIGSUM_KEY_EXPIRED' + The key or one of the certificates has expired. It is + probably a good idea to display the date of the + expiration. + + `GPGME_SIGSUM_SIG_EXPIRED' + The signature has expired. + + `GPGME_SIGSUM_KEY_MISSING' + Can't verify due to a missing key or certificate. + + `GPGME_SIGSUM_CRL_MISSING' + The CRL (or an equivalent mechanism) is not available. + + `GPGME_SIGSUM_CRL_TOO_OLD' + Available CRL is too old. + + `GPGME_SIGSUM_BAD_POLICY' + A policy requirement was not met. + + `GPGME_SIGSUM_SYS_ERROR' + A system error occured. + + `char *fpr' + This is the fingerprint or key ID of the signature. + + `gpgme_error_t status' + This is the status of the signature. In particular, the + following status codes are of interest: + + `GPG_ERR_NO_ERROR' + This status indicates that the signature is valid. For + the combined result this status means that all + signatures are valid. + + `GPG_ERR_SIG_EXPIRED' + This status indicates that the signature is valid but + expired. For the combined result this status means + that all signatures are valid and expired. + + `GPG_ERR_KEY_EXPIRED' + This status indicates that the signature is valid but + the key used to verify the signature has expired. For + the combined result this status means that all + signatures are valid and all keys are expired. + + `GPG_ERR_CERT_REVOKED' + This status indicates that the signature is valid but + the key used to verify the signature has been revoked. + For the combined result this status means that all + signatures are valid and all keys are revoked. + + `GPG_ERR_BAD_SIGNATURE' + This status indicates that the signature is invalid. + For the combined result this status means that all + signatures are invalid. + + `GPG_ERR_NO_PUBKEY' + 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. + + `GPG_ERR_GENERAL' + This status indicates that there was some other error + which prevented the signature verification. + + `gpgme_sig_notation_t notations' + This is a linked list with the notation data and policy URLs. + + `unsigned long timestamp' + The creation timestamp of this signature. + + `unsigned long exp_timestamp' + The expiration timestamp of this signature, or 0 if the + signature does not expire. + + `unsigned int wrong_key_usage : 1' + This is true if the key was not used according to its policy. + + `unsigned int pka_trust : 2' + This is set to the trust information gained by means of the + PKA system. Values are: + `0' + No PKA information available or verification not + possible. + + `1' + PKA verification failed. + + `2' + PKA verification succeeded. + + `3' + Reserved for future use. + Depending on the configuration of the engine, this metric may + also be reflected by the validity of the signature. + + `unsigned int chain_model : 1' + This is true if the validity of the signature has been + checked using the chain model. In the chain model the time + the signature has been created must be within the validity + period of the certificate and the time the certificate itself + has been created must be within the validity period of the + issuing certificate. In contrast the default validation model + checks the validity of signature as well at the entire + certificate chain at the current time. + + `gpgme_validity_t validity' + The validity of the signature. + + `gpgme_error_t validity_reason' + If a signature is not valid, this provides a reason why. + + `gpgme_pubkey_algo_t' + The public key algorithm used to create this signature. + + `gpgme_hash_algo_t' + The hash algorithm used to create this signature. + + -- Data type: gpgme_verify_result_t + This is a pointer to a structure used to store the result of a + `gpgme_op_verify' operation. After verifying a signature, you can + retrieve the pointer to the result with `gpgme_op_verify_result'. + If the operation failed this might be a `NULL' pointer. The + structure contains the following member: + + `gpgme_signature_t signatures' + A linked list with information about all signatures for which + a verification was attempted. + + `char *file_name' + This is the filename of the original plaintext message file + if it is known, otherwise this is a null pointer. + + -- Function: gpgme_verify_result_t gpgme_op_verify_result + (gpgme_ctx_t CTX) + The function `gpgme_op_verify_result' returns a + `gpgme_verify_result_t' pointer to a structure holding the result + of a `gpgme_op_verify' operation. The pointer is only valid if + the last operation on the context was a `gpgme_op_verify', + `gpgme_op_verify_start', `gpgme_op_decrypt_verify' or + `gpgme_op_decrypt_verify_start' operation, and if this operation + finished successfully (for `gpgme_op_decrypt_verify' and + `gpgme_op_decrypt_verify_start', the error code `GPG_ERR_NO_DATA' + counts as successful in this context). The returned pointer is + only valid until the next operation is started on the context. + + The following interfaces are deprecated and only provided for +backward compatibility. Don't use them. They will be removed in a +future version of GPGME. + + -- Data type: enum gpgme_sig_stat_t + The `gpgme_sig_stat_t' 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_GOOD_EXP' + This status indicates that the signature is valid but + expired. For the combined result this status means that all + signatures are valid and expired. + + `GPGME_SIG_STAT_GOOD_EXPKEY' + This status indicates that the signature is valid but the key + used to verify the signature has expired. For the combined + result this status means that all signatures are valid and + all keys are expired. + + `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: const char * gpgme_get_sig_status (gpgme_ctx_t CTX, + int IDX, gpgme_sig_stat_t *R_STAT, time_t *R_CREATED) + The function `gpgme_get_sig_status' is equivalent to: + + gpgme_verify_result_t result; + gpgme_signature_t sig; + + result = gpgme_op_verify_result (ctx); + sig = result->signatures; + + while (sig && idx) + { + sig = sig->next; + idx--; + } + if (!sig || idx) + return NULL; + + if (r_stat) + { + switch (gpg_err_code (sig->status)) + { + case GPG_ERR_NO_ERROR: + *r_stat = GPGME_SIG_STAT_GOOD; + break; + + case GPG_ERR_BAD_SIGNATURE: + *r_stat = GPGME_SIG_STAT_BAD; + break; + + case GPG_ERR_NO_PUBKEY: + *r_stat = GPGME_SIG_STAT_NOKEY; + break; + + case GPG_ERR_NO_DATA: + *r_stat = GPGME_SIG_STAT_NOSIG; + break; + + case GPG_ERR_SIG_EXPIRED: + *r_stat = GPGME_SIG_STAT_GOOD_EXP; + break; + + case GPG_ERR_KEY_EXPIRED: + *r_stat = GPGME_SIG_STAT_GOOD_EXPKEY; + break; + + default: + *r_stat = GPGME_SIG_STAT_ERROR; + break; + } + } + if (r_created) + *r_created = sig->timestamp; + return sig->fpr; + + -- Function: const char * gpgme_get_sig_string_attr (gpgme_ctx_t CTX, + int IDX, gpgme_attr_t WHAT, int WHATIDX) + The function `gpgme_get_sig_string_attr' is equivalent to: + + gpgme_verify_result_t result; + gpgme_signature_t sig; + + result = gpgme_op_verify_result (ctx); + sig = result->signatures; + + while (sig && idx) + { + sig = sig->next; + idx--; + } + if (!sig || idx) + return NULL; + + switch (what) + { + case GPGME_ATTR_FPR: + return sig->fpr; + + case GPGME_ATTR_ERRTOK: + if (whatidx == 1) + return sig->wrong_key_usage ? "Wrong_Key_Usage" : ""; + else + return ""; + default: + break; + } + + return NULL; + + -- Function: const char * gpgme_get_sig_ulong_attr (gpgme_ctx_t CTX, + int IDX, gpgme_attr_t WAHT, int WHATIDX) + The function `gpgme_get_sig_ulong_attr' is equivalent to: + + gpgme_verify_result_t result; + gpgme_signature_t sig; + + result = gpgme_op_verify_result (ctx); + sig = result->signatures; + + while (sig && idx) + { + sig = sig->next; + idx--; + } + if (!sig || idx) + return 0; + + switch (what) + { + case GPGME_ATTR_CREATED: + return sig->timestamp; + + case GPGME_ATTR_EXPIRE: + return sig->exp_timestamp; + + case GPGME_ATTR_VALIDITY: + return (unsigned long) sig->validity; + + case GPGME_ATTR_SIG_STATUS: + switch (sig->status) + { + case GPG_ERR_NO_ERROR: + return GPGME_SIG_STAT_GOOD; + + case GPG_ERR_BAD_SIGNATURE: + return GPGME_SIG_STAT_BAD; + + case GPG_ERR_NO_PUBKEY: + return GPGME_SIG_STAT_NOKEY; + + case GPG_ERR_NO_DATA: + return GPGME_SIG_STAT_NOSIG; + + case GPG_ERR_SIG_EXPIRED: + return GPGME_SIG_STAT_GOOD_EXP; + + case GPG_ERR_KEY_EXPIRED: + return GPGME_SIG_STAT_GOOD_EXPKEY; + + default: + return GPGME_SIG_STAT_ERROR; + } + + case GPGME_ATTR_SIG_SUMMARY: + return sig->summary; + + default: + break; + } + return 0; + + -- Function: const char * gpgme_get_sig_key (gpgme_ctx_t CTX, int IDX, + gpgme_key_t *R_KEY) + The function `gpgme_get_sig_key' is equivalent to: + + gpgme_verify_result_t result; + gpgme_signature_t sig; + + result = gpgme_op_verify_result (ctx); + sig = result->signatures; + + while (sig && idx) + { + sig = sig->next; + idx--; + } + if (!sig || idx) + return gpg_error (GPG_ERR_EOF); + + return gpgme_get_key (ctx, sig->fpr, r_key, 0); + + +File: gpgme.info, Node: Decrypt and Verify, Next: Sign, Prev: Verify, Up: Crypto Operations + +7.7.3 Decrypt and Verify +------------------------ + + -- Function: gpgme_error_t gpgme_op_decrypt_verify (gpgme_ctx_t CTX, + gpgme_data_t CIPHER, gpgme_data_t PLAIN) + 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. + + After the operation completed, `gpgme_op_decrypt_result' and + `gpgme_op_verify_result' can be used to retrieve more information + about the signatures. + + If the error code `GPG_ERR_NO_DATA' is returned, CIPHER does not + contain any data to decrypt. However, it might still be signed. + The information about detected signatures is available with + `gpgme_op_verify_result' in this case. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + ciphertext could be decrypted successfully, `GPG_ERR_INV_VALUE' if + CTX, CIPHER or PLAIN is not a valid pointer, `GPG_ERR_NO_DATA' if + CIPHER does not contain any data to decrypt, + `GPG_ERR_DECRYPT_FAILED' if CIPHER is not a valid cipher text, + `GPG_ERR_BAD_PASSPHRASE' if the passphrase for the secret key + could not be retrieved, and passes through any errors that are + reported by the crypto engine support routines. + + -- Function: gpgme_error_t gpgme_op_decrypt_verify (gpgme_ctx_t CTX, + gpgme_data_t CIPHER, gpgme_data_t 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. *Note Waiting For + Completion::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation could be started successfully, `GPG_ERR_INV_VALUE' if + CTX, CIPHER, PLAIN or R_STAT is not a valid pointer, and + `GPG_ERR_NO_DATA' if CIPHER does not contain any data to decrypt. + + +File: gpgme.info, Node: Sign, Next: Encrypt, Prev: Decrypt and Verify, Up: Crypto Operations + +7.7.4 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). + +* Menu: + +* Selecting Signers:: How to choose the keys to sign with. +* Creating a Signature:: How to create a signature. +* Signature Notation Data:: How to add notation data to a signature. + + +File: gpgme.info, Node: Selecting Signers, Next: Creating a Signature, Up: Sign + +7.7.4.1 Selecting Signers +......................... + + -- Function: void gpgme_signers_clear (gpgme_ctx_t 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: gpgme_error_t gpgme_signers_add (gpgme_ctx_t CTX, + const gpgme_key_t KEY) + The function `gpgme_signers_add' adds the key KEY to the list of + signers in the context CTX. + + Calling this function acquires an additional reference for the key. + + -- Function: gpgme_key_t gpgme_signers_enum (const gpgme_ctx_t 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. + + +File: gpgme.info, Node: Creating a Signature, Next: Signature Notation Data, Prev: Selecting Signers, Up: Sign + +7.7.4.2 Creating a Signature +............................ + + -- Data type: enum gpgme_sig_mode_t + The `gpgme_sig_mode_t' 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: gpgme_error_t gpgme_op_sign (gpgme_ctx_t CTX, + gpgme_data_t PLAIN, gpgme_data_t SIG, gpgme_sig_mode_t 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 + (or, if that is not set, by the encoding specified for SIG), the + text mode attributes set for the context CTX and the requested + signature mode MODE. + + After the operation completed successfully, the result can be + retrieved with `gpgme_op_sign_result'. + + 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'. *Note Included + Certificates::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + signature could be created successfully, `GPG_ERR_INV_VALUE' if + CTX, PLAIN or SIG is not a valid pointer, `GPG_ERR_NO_DATA' if the + signature could not be created, `GPG_ERR_BAD_PASSPHRASE' if the + passphrase for the secret key could not be retrieved, + `GPG_ERR_UNUSABLE_SECKEY' if there are invalid signers, and passes + through any errors that are reported by the crypto engine support + routines. + + -- Function: gpgme_error_t gpgme_op_sign_start (gpgme_ctx_t CTX, + gpgme_data_t PLAIN, gpgme_data_t SIG, gpgme_sig_mode_t MODE) + The function `gpgme_op_sign_start' initiates a `gpgme_op_sign' + operation. It can be completed by calling `gpgme_wait' on the + context. *Note Waiting For Completion::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation could be started successfully, and `GPG_ERR_INV_VALUE' + if CTX, PLAIN or SIG is not a valid pointer. + + -- Data type: gpgme_new_signature_t + This is a pointer to a structure used to store a part of the + result of a `gpgme_op_sign' operation. The structure contains the + following members: + + `gpgme_new_signature_t next' + This is a pointer to the next new signature structure in the + linked list, or `NULL' if this is the last element. + + `gpgme_sig_mode_t type' + The type of this signature. + + `gpgme_pubkey_algo_t' + The public key algorithm used to create this signature. + + `gpgme_hash_algo_t' + The hash algorithm used to create this signature. + + `unsigned int sig_class' + The signature class of this signature. + + `long int timestamp' + The creation timestamp of this signature. + + `char *fpr' + The fingerprint of the key which was used to create this + signature. + + -- Data type: gpgme_sign_result_t + This is a pointer to a structure used to store the result of a + `gpgme_op_sign' operation. After successfully generating a + signature, you can retrieve the pointer to the result with + `gpgme_op_sign_result'. The structure contains the following + members: + + `gpgme_invalid_key_t invalid_signers' + A linked list with information about all invalid keys for + which a signature could not be created. + + `gpgme_new_signature_t signatures' + A linked list with information about all signatures created. + + -- Function: gpgme_sign_result_t gpgme_op_sign_result (gpgme_ctx_t CTX) + The function `gpgme_op_sign_result' returns a + `gpgme_sign_result_t' pointer to a structure holding the result of + a `gpgme_op_sign' operation. The pointer is only valid if the + last operation on the context was a `gpgme_op_sign', + `gpgme_op_sign_start', `gpgme_op_encrypt_sign' or + `gpgme_op_encrypt_sign_start' operation. If that operation + failed, the function might return a `NULL' pointer. The returned + pointer is only valid until the next operation is started on the + context. + + +File: gpgme.info, Node: Signature Notation Data, Prev: Creating a Signature, Up: Sign + +7.7.4.3 Signature Notation Data +............................... + +Using the following functions, you can attach arbitrary notation data +to a signature. This information is then available to the user when +the signature is verified. + + -- Function: void gpgme_sig_notation_clear (gpgme_ctx_t CTX) + The function `gpgme_sig_notation_clear' removes the notation data + from the context CTX. Subsequent signing operations from this + context will not include any notation data. + + Every context starts with an empty notation data list. + + -- Function: gpgme_error_t gpgme_sig_notation_add (gpgme_ctx_t CTX, + const char *NAME, const char *VALUE, + gpgme_sig_notation_flags_t FLAGS) + The function `gpgme_sig_notation_add' adds the notation data with + the name NAME and the value VALUE to the context CTX. + + Subsequent signing operations will include this notation data, as + well as any other notation data that was added since the creation + of the context or the last `gpgme_sig_notation_clear' operation. + + The arguments NAME and VALUE must be `NUL'-terminated strings in + human-readable form. The flag `GPGME_SIG_NOTATION_HUMAN_READABLE' + is implied (non-human-readable notation data is currently not + supported). The strings must be in UTF-8 encoding. + + If NAME is `NULL', then VALUE should be a policy URL. + + The function `gpgme_sig_notation_add' returns the error code + `GPG_ERR_NO_ERROR' if the notation data could be added + successfully, `GPG_ERR_INV_VALUE' if CTX is not a valid pointer, + or if NAME, VALUE and FLAGS are an invalid combination. The + function also passes through any errors that are reported by the + crypto engine support routines. + + -- Function: gpgme_sig_notation_t gpgme_sig_notation_get + (const gpgme_ctx_t CTX) + The function `gpgme_sig_notation_get' returns the linked list of + notation data structures that are contained in the context CTX. + + If CTX is not a valid pointer, or there is no notation data added + for this context, `NULL' is returned. + + +File: gpgme.info, Node: Encrypt, Prev: Sign, Up: Crypto Operations + +7.7.5 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. + +* Menu: + +* Encrypting a Plaintext:: How to encrypt a plaintext. + + +File: gpgme.info, Node: Encrypting a Plaintext, Up: Encrypt + +7.7.5.1 Encrypting a Plaintext +.............................. + + -- Function: gpgme_error_t gpgme_op_encrypt (gpgme_ctx_t CTX, + gpgme_key_t RECP[], gpgme_encrypt_flags_t FLAGS, + gpgme_data_t PLAIN, gpgme_data_t CIPHER) + The function `gpgme_op_encrypt' encrypts the plaintext in the data + object PLAIN for the recipients RECP and stores the ciphertext in + the data object CIPHER. The type of the ciphertext created is + determined by the ASCII armor (or, if that is not set, by the + encoding specified for CIPHER) and the text mode attributes set + for the context CTX. + + KEY must be a `NULL'-terminated array of keys. The user must keep + references for all keys during the whole duration of the call (but + see `gpgme_op_encrypt_start' for the requirements with the + asynchronous variant). + + The value in FLAGS is a bitwise-or combination of one or multiple + of the following bit values: + + `GPGME_ENCRYPT_ALWAYS_TRUST' + The `GPGME_ENCRYPT_ALWAYS_TRUST' symbol specifies that all the + recipients in RECP should be trusted, even if the keys do not + have a high enough validity in the keyring. This flag should + be used with care; in general it is not a good idea to use + any untrusted keys. + + `GPGME_ENCRYPT_NO_ENCRYPT_TO' + The `GPGME_ENCRYPT_NO_ENCRYPT_TO' symbol specifies that no + default or hidden default recipients as configured in the + crypto backend should be included. This can be useful for + managing different user profiles. + + If `GPG_ERR_UNUSABLE_PUBKEY' is returned, some recipients in RECP + are invalid, but not all. In this case the plaintext might be + encrypted for all valid recipients and returned in CIPHER (if this + happens depends on the crypto engine). More information about the + invalid recipients is available with `gpgme_op_encrypt_result'. + + 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 the error code `GPG_ERR_NO_ERROR' if the + ciphertext could be created successfully, `GPG_ERR_INV_VALUE' if + CTX, RECP, PLAIN or CIPHER is not a valid pointer, + `GPG_ERR_UNUSABLE_PUBKEY' if RECP contains some invalid + recipients, `GPG_ERR_BAD_PASSPHRASE' if the passphrase for the + symmetric key could not be retrieved, and passes through any + errors that are reported by the crypto engine support routines. + + -- Function: gpgme_error_t gpgme_op_encrypt_start (gpgme_ctx_t CTX, + gpgme_key_t RECP[], gpgme_encrypt_flags_t FLAGS, + gpgme_data_t PLAIN, gpgme_data_t CIPHER) + The function `gpgme_op_encrypt_start' initiates a + `gpgme_op_encrypt' operation. It can be completed by calling + `gpgme_wait' on the context. *Note Waiting For Completion::. + + References to the keys only need to be held for the duration of + this call. The user can release its references to the keys after + this function returns, even if the operation is not yet finished. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation could be started successfully, `GPG_ERR_INV_VALUE' if + CTX, RSET, PLAIN or CIPHER is not a valid pointer, and + `GPG_ERR_UNUSABLE_PUBKEY' if RSET does not contain any valid + recipients. + + -- Data type: gpgme_encrypt_result_t + This is a pointer to a structure used to store the result of a + `gpgme_op_encrypt' operation. After successfully encrypting data, + you can retrieve the pointer to the result with + `gpgme_op_encrypt_result'. The structure contains the following + members: + + `gpgme_invalid_key_t invalid_recipients' + A linked list with information about all invalid keys for + which the data could not be encrypted. + + -- Function: gpgme_encrypt_result_t gpgme_op_encrypt_result + (gpgme_ctx_t CTX) + The function `gpgme_op_encrypt_result' returns a + `gpgme_encrypt_result_t' pointer to a structure holding the result + of a `gpgme_op_encrypt' operation. The pointer is only valid if + the last operation on the context was a `gpgme_op_encrypt', + `gpgme_op_encrypt_start', `gpgme_op_sign' or `gpgme_op_sign_start' + operation. If this operation failed, this might be a `NULL' + pointer. The returned pointer is only valid until the next + operation is started on the context. + + -- Function: gpgme_error_t gpgme_op_encrypt_sign (gpgme_ctx_t CTX, + gpgme_key_t RECP[], gpgme_encrypt_flags_t FLAGS, + gpgme_data_t PLAIN, gpgme_data_t 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: gpgme_error_t gpgme_op_encrypt_sign_start + (gpgme_ctx_t CTX, gpgme_key_t RECP, + gpgme_encrypt_flags_t FLAGS, gpgme_data_t PLAIN, + gpgme_data_t 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. *Note Waiting For Completion::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation could be started successfully, and `GPG_ERR_INV_VALUE' + if CTX, RSET, PLAIN or CIPHER is not a valid pointer. + + +File: gpgme.info, Node: Run Control, Prev: Crypto Operations, Up: Contexts + +7.8 Run Control +=============== + +GPGME supports running operations synchronously and asynchronously. +You can use asynchronous operation to set up a context up to initiating +the desired operation, but delay performing it to a later point. + + Furthermore, you can use an external event loop to control exactly +when GPGME runs. This ensures that GPGME only runs when necessary and +also prevents it from blocking for a long time. + +* Menu: + +* Waiting For Completion:: Waiting until an operation is completed. +* Using External Event Loops:: Advanced control over what happens when. +* Cancellation:: How to end pending operations prematurely. + + +File: gpgme.info, Node: Waiting For Completion, Next: Using External Event Loops, Up: Run Control + +7.8.1 Waiting For Completion +---------------------------- + + -- Function: gpgme_ctx_t gpgme_wait (gpgme_ctx_t CTX, + gpgme_error_t *STATUS, int HANG) + The function `gpgme_wait' continues 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 + if `gpgme_wait' does not return `NULL'. + + The CTX argument can be `NULL'. In that case, `gpgme_wait' waits + for any context to complete its operation. + + `gpgme_wait' can be used only in conjunction with any context that + has a pending operation initiated with one of the + `gpgme_op_*_start' functions except `gpgme_op_keylist_start' and + `gpgme_op_trustlist_start' (for which you should use the + corresponding `gpgme_op_*_next' functions). If CTX is `NULL', all + of such contexts are waited upon and possibly returned. + Synchronous operations running in parallel, as well as key and + trust item list operations, do not affect `gpgme_wait'. + + In a multi-threaded environment, only one thread should ever call + `gpgme_wait' at any time, irregardless if CTX is specified or not. + This means that all calls to this function should be fully + synchronized by locking primitives. It is safe to start + asynchronous operations while a thread is running in `gpgme_wait'. + + The function returns the CTX of the context which has finished the + operation. If HANG is false, and the timeout expires, `NULL' is + returned and `*status' will be set to 0. If an error occurs, + `NULL' is returned and the error is returned in `*status'. + + +File: gpgme.info, Node: Using External Event Loops, Next: Cancellation, Prev: Waiting For Completion, Up: Run Control + +7.8.2 Using External Event Loops +-------------------------------- + +GPGME hides the complexity of the communication between the library and +the crypto engine. The price of this convenience is that the calling +thread can block arbitrary long waiting for the data returned by the +crypto engine. In single-threaded programs, in particular if they are +interactive, this is an unwanted side-effect. OTOH, if `gpgme_wait' is +used without the HANG option being enabled, it might be called +unnecessarily often, wasting CPU time that could be used otherwise. + + The I/O callback interface described in this section lets the user +take control over what happens when. GPGME will provide the user with +the file descriptors that should be monitored, and the callback +functions that should be invoked when a file descriptor is ready for +reading or writing. It is then the user's responsibility to decide +when to check the file descriptors and when to invoke the callback +functions. Usually this is done in an event loop, that also checks for +events in other parts of the program. If the callback functions are +only called when the file descriptors are ready, GPGME will never +block. This gives the user more control over the program flow, and +allows to perform other tasks when GPGME would block otherwise. + + By using this advanced mechanism, GPGME can be integrated smoothly +into GUI toolkits like GTK+ even for single-threaded programs. + +* Menu: + +* I/O Callback Interface:: How I/O callbacks are registered. +* Registering I/O Callbacks:: How to use I/O callbacks for a context. +* I/O Callback Example:: An example how to use I/O callbacks. +* I/O Callback Example GTK+:: How to use GPGME with GTK+. +* I/O Callback Example GDK:: How to use GPGME with GDK. +* I/O Callback Example Qt:: How to use GPGME with Qt. + + +File: gpgme.info, Node: I/O Callback Interface, Next: Registering I/O Callbacks, Up: Using External Event Loops + +7.8.2.1 I/O Callback Interface +.............................. + + -- Data type: gpgme_error_t (*gpgme_io_cb_t) (void *DATA, int FD) + The `gpgme_io_cb_t' type is the type of functions which GPGME + wants to register as I/O callback handlers using the + `gpgme_register_io_cb_t' functions provided by the user. + + DATA and FD are provided by GPGME when the I/O callback handler is + registered, and should be passed through to the handler when it is + invoked by the user because it noticed activity on the file + descriptor FD. + + The callback handler always returns `0', but you should consider + the return value to be reserved for later use. + + -- Data type: gpgme_error_t (*gpgme_register_io_cb_t) (void *DATA, +int FD, int DIR, gpgme_io_cb_t FNC, void *FNC_DATA, void **TAG) + The `gpgme_register_io_cb_t' type is the type of functions which + can be called by GPGME to register an I/O callback function FNC + for the file descriptor FD with the user. FNC_DATA should be + passed as the first argument to FNC when the handler is invoked + (the second argument should be FD). If DIR is 0, FNC should be + called by the user when FD is ready for writing. If DIR is 1, FNC + should be called when FD is ready for reading. + + DATA was provided by the user when registering the + `gpgme_register_io_cb_t' function with GPGME and will always be + passed as the first argument when registering a callback function. + For example, the user can use this to determine the event loop to + which the file descriptor should be added. + + GPGME will call this function when a crypto operation is initiated + in a context for which the user has registered I/O callback + handler functions with `gpgme_set_io_cbs'. It can also call this + function when it is in an I/O callback handler for a file + descriptor associated to this context. + + The user should return a unique handle in TAG identifying this I/O + callback registration, which will be passed to the + `gpgme_register_io_cb_t' function without interpretation when the + file descriptor should not be monitored anymore. + + -- Data type: void (*gpgme_remove_io_cb_t) (void *TAG) + The `gpgme_remove_io_cb_t' type is the type of functions which can + be called by GPGME to remove an I/O callback handler that was + registered before. TAG is the handle that was returned by the + `gpgme_register_io_cb_t' for this I/O callback. + + GPGME can call this function when a crypto operation is in an I/O + callback. It will also call this function when the context is + destroyed while an operation is pending. + + -- Data type: enum gpgme_event_io_t + The `gpgme_event_io_t' type specifies the type of an event that is + reported to the user by GPGME as a consequence of an I/O + operation. The following events are defined: + + `GPGME_EVENT_START' + The operation is fully initialized now, and you can start to + run the registered I/O callback handlers now. Note that + registered I/O callback handlers must not be run before this + event is signalled. TYPE_DATA is `NULL' and reserved for + later use. + + `GPGME_EVENT_DONE' + The operation is finished, the last I/O callback for this + operation was removed. The accompanying TYPE_DATA points to a + `gpgme_error_t' variable that contains the status of the + operation that finished. This event is signalled after the + last I/O callback has been removed. + + `GPGME_EVENT_NEXT_KEY' + In a `gpgme_op_keylist_start' operation, the next key was + received from the crypto engine. The accompanying TYPE_DATA + is a `gpgme_key_t' variable that contains the key with one + reference for the user. + + `GPGME_EVENT_NEXT_TRUSTITEM' + In a `gpgme_op_trustlist_start' operation, the next trust item + was received from the crypto engine. The accompanying + TYPE_DATA is a `gpgme_trust_item_t' variable that contains + the trust item with one reference for the user. + + -- Data type: void (*gpgme_event_io_cb_t) (void *DATA, +gpgme_event_io_t TYPE, void *TYPE_DATA) + The `gpgme_event_io_cb_t' type is the type of functions which can + be called by GPGME to signal an event for an operation running in + a context which has I/O callback functions registered by the user. + + DATA was provided by the user when registering the + `gpgme_event_io_cb_t' function with GPGME and will always be + passed as the first argument when registering a callback function. + For example, the user can use this to determine the context in + which this event has occured. + + TYPE will specify the type of event that has occured. TYPE_DATA + specifies the event further, as described in the above list of + possible `gpgme_event_io_t' types. + + GPGME can call this function in an I/O callback handler. + + +File: gpgme.info, Node: Registering I/O Callbacks, Next: I/O Callback Example, Prev: I/O Callback Interface, Up: Using External Event Loops + +7.8.2.2 Registering I/O Callbacks +................................. + + -- Data type: struct gpgme_io_cb_ts + This structure is used to store the I/O callback interface + functions described in the previous section. It has the following + members: + + `gpgme_register_io_cb_t add' + This is the function called by GPGME to register an I/O + callback handler. It must be specified. + + `void *add_data' + This is passed as the first argument to the `add' function + when it is called by GPGME. For example, it can be used to + determine the event loop to which the file descriptor should + be added. + + `gpgme_remove_io_cb_t remove' + This is the function called by GPGME to remove an I/O + callback handler. It must be specified. + + `gpgme_event_io_cb_t event' + This is the function called by GPGME to signal an event for + an operation. It must be specified, because at least the + start event must be processed. + + `void *event_data' + This is passed as the first argument to the `event' function + when it is called by GPGME. For example, it can be used to + determine the context in which the event has occured. + + -- Function: void gpgme_set_io_cbs (gpgme_ctx_t CTX, + struct gpgme_io_cb_ts *IO_CBS) + The function `gpgme_set_io_cbs' enables the I/O callback interface + for the context CTX. The I/O callback functions are specified by + IO_CBS. + + If IO_CBS->`add' is `NULL', the I/O callback interface is disabled + for the context, and normal operation is restored. + + -- Function: void gpgme_get_io_cbs (gpgme_ctx_t CTX, + struct gpgme_io_cb_ts *IO_CBS) + The function `gpgme_get_io_cbs' returns the I/O callback functions + set with `gpgme_set_io_cbs' in IO_CBS. + + +File: gpgme.info, Node: I/O Callback Example, Next: I/O Callback Example GTK+, Prev: Registering I/O Callbacks, Up: Using External Event Loops + +7.8.2.3 I/O Callback Example +............................ + +To actually use an external event loop, you have to implement the I/O +callback functions that are used by GPGME to register and unregister +file descriptors. Furthermore, you have to actually monitor these file +descriptors for activity and call the appropriate I/O callbacks. + + The following example illustrates how to do that. The example uses +locking to show in which way the callbacks and the event loop can run +concurrently. For the event loop, we use a fixed array. For a +real-world implementation, you should use a dynamically sized structure +because the number of file descriptors needed for a crypto operation in +GPGME is not predictable. + + #include <assert.h> + #include <errno.h> + #include <stdlib.h> + #include <pthread.h> + #include <sys/types.h> + #include <gpgme.h> + + /* The following structure holds the result of a crypto operation. */ + struct op_result + { + int done; + gpgme_error_t err; + }; + + /* The following structure holds the data associated with one I/O + callback. */ + struct one_fd + { + int fd; + int dir; + gpgme_io_cb_t fnc; + void *fnc_data; + void *loop; + }; + + struct event_loop + { + pthread_mutex_t lock; + #define MAX_FDS 32 + /* Unused slots are marked with FD being -1. */ + struct one_fd fds[MAX_FDS]; + }; + + The following functions implement the I/O callback interface. + + gpgme_error_t + add_io_cb (void *data, int fd, int dir, gpgme_io_cb_t fnc, void *fnc_data, + void **r_tag) + { + struct event_loop *loop = data; + struct one_fd *fds = loop->fds; + int i; + + pthread_mutex_lock (&loop->lock); + for (i = 0; i < MAX_FDS; i++) + { + if (fds[i].fd == -1) + { + fds[i].fd = fd; + fds[i].dir = dir; + fds[i].fnc = fnc; + fds[i].fnc_data = fnc_data; + fds[i].loop = loop; + break; + } + } + pthread_mutex_unlock (&loop->lock); + if (i == MAX_FDS) + return gpg_error (GPG_ERR_GENERAL); + *r_tag = &fds[i]; + return 0; + } + + void + remove_io_cb (void *tag) + { + struct one_fd *fd = tag; + struct event_loop *loop = fd->loop; + + pthread_mutex_lock (&loop->lock); + fd->fd = -1; + pthread_mutex_unlock (&loop->lock); + } + + void + event_io_cb (void *data, gpgme_event_io_t type, void *type_data) + { + struct op_result *result = data; + + /* We don't support list operations here. */ + if (type == GPGME_EVENT_DONE) + { + result->done = 1; + result->err = *type_data; + } + } + + The final missing piece is the event loop, which will be presented +next. We only support waiting for the success of a single operation. + + int + do_select (struct event_loop *loop) + { + fd_set rfds; + fd_set wfds; + int i, n; + int any = 0; + struct one_fd *fdlist = loop->fds; + + pthread_mutex_lock (&loop->lock); + FD_ZERO (&rfds); + FD_ZERO (&wfds); + for (i = 0; i < MAX_FDS; i++) + if (fdlist[i].fd != -1) + FD_SET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds); + pthread_mutex_unlock (&loop->unlock); + + do + { + n = select (FD_SETSIZE, &rfds, &wfds, NULL, 0); + } + while (n < 0 && errno == EINTR); + + if (n < 0) + return n; /* Error or timeout. */ + + pthread_mutex_lock (&loop->lock); + for (i = 0; i < MAX_FDS && n; i++) + { + if (fdlist[i].fd != -1) + { + if (FD_ISSET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds)) + { + assert (n); + n--; + any = 1; + /* The I/O callback handler can register/remove callbacks, + so we have to unlock the file descriptor list. */ + pthread_mutex_unlock (&loop->lock); + (*fdlist[i].fnc) (fdlist[i].fnc_data, fdlist[i].fd); + pthread_mutex_lock (&loop->lock); + } + } + } + pthread_mutex_unlock (&loop->lock); + return any; + } + + void + wait_for_op (struct event_loop *loop, struct op_result *result) + { + int ret; + + do + { + ret = do_select (loop); + } + while (ret >= 0 && !result->done); + } + + The main function shows how to put it all together. + + int + main (int argc, char *argv[]) + { + struct event_loop loop; + struct op_result result; + gpgme_ctx_t ctx; + gpgme_error_t err; + gpgme_data_t sig, text; + int i; + struct gpgme_io_cb_ts io_cbs = + { + add_io_cb, + &loop, + remove_io_cb, + event_io_cb, + &result + }; + + init_gpgme (void); + + /* Initialize the loop structure. */ + pthread_mutex_init (&loop.lock, NULL); + for (i = 0; i < MAX_FDS; i++) + loop->fds[i].fd = -1; + + /* Initialize the result structure. */ + result.done = 0; + + err = gpgme_data_new_from_file (&sig, "signature", 1); + if (!err) + err = gpgme_data_new_from_file (&text, "text", 1); + if (!err) + err = gpgme_new (&ctx); + if (!err) + { + gpgme_set_io_cbs (ctx, &io_cbs); + err = gpgme_op_verify_start (ctx, sig, text, NULL); + } + if (err) + { + fprintf (stderr, "gpgme error: %s: %s\n", + gpgme_strsource (err), gpgme_strerror (err)); + exit (1); + } + + wait_for_op (&loop, &result); + if (!result.done) + { + fprintf (stderr, "select error\n"); + exit (1); + } + if (!result.err) + { + fprintf (stderr, "verification failed: %s: %s\n", + gpgme_strsource (result.err), gpgme_strerror (result.err)); + exit (1); + } + /* Evaluate verify result. */ + ... + return 0; + } + + +File: gpgme.info, Node: I/O Callback Example GTK+, Next: I/O Callback Example GDK, Prev: I/O Callback Example, Up: Using External Event Loops + +7.8.2.4 I/O Callback Example GTK+ +................................. + +The I/O callback interface can be used to integrate GPGME with the GTK+ +event loop. The following code snippets shows how this can be done +using the appropriate register and remove I/O callback functions. In +this example, the private data of the register I/O callback function is +unused. The event notifications is missing because it does not require +any GTK+ specific setup. + + #include <gtk/gtk.h> + + struct my_gpgme_io_cb + { + gpgme_io_cb_t fnc; + void *fnc_data; + guint input_handler_id + }; + + void + my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition) + { + struct my_gpgme_io_cb *iocb = data; + (*(iocb->fnc)) (iocb->data, source); + } + + void + my_gpgme_remove_io_cb (void *data) + { + struct my_gpgme_io_cb *iocb = data; + gtk_input_remove (data->input_handler_id); + } + + void + my_gpgme_register_io_callback (void *data, int fd, int dir, gpgme_io_cb_t fnc, + void *fnc_data, void **tag) + { + struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb)); + iocb->fnc = fnc; + iocb->data = fnc_data; + iocb->input_handler_id = gtk_input_add_full (fd, dir + ? GDK_INPUT_READ + : GDK_INPUT_WRITE, + my_gpgme_io_callback, + 0, iocb, NULL); + *tag = iocb; + return 0; + } + + +File: gpgme.info, Node: I/O Callback Example GDK, Next: I/O Callback Example Qt, Prev: I/O Callback Example GTK+, Up: Using External Event Loops + +7.8.2.5 I/O Callback Example GDK +................................ + +The I/O callback interface can also be used to integrate GPGME with the +GDK event loop. The following code snippets shows how this can be done +using the appropriate register and remove I/O callback functions. In +this example, the private data of the register I/O callback function is +unused. The event notifications is missing because it does not require +any GDK specific setup. + + It is very similar to the GTK+ example in the previous section. + + #include <gdk/gdk.h> + + struct my_gpgme_io_cb + { + gpgme_io_cb_t fnc; + void *fnc_data; + gint tag; + }; + + void + my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition) + { + struct my_gpgme_io_cb *iocb = data; + (*(iocb->fnc)) (iocb->data, source); + } + + void + my_gpgme_remove_io_cb (void *data) + { + struct my_gpgme_io_cb *iocb = data; + gdk_input_remove (data->tag); + } + + void + my_gpgme_register_io_callback (void *data, int fd, int dir, gpgme_io_cb_t fnc, + void *fnc_data, void **tag) + { + struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb)); + iocb->fnc = fnc; + iocb->data = fnc_data; + iocb->tag = gtk_input_add_full (fd, dir ? GDK_INPUT_READ : GDK_INPUT_WRITE, + my_gpgme_io_callback, iocb, NULL); + *tag = iocb; + return 0; + } + + +File: gpgme.info, Node: I/O Callback Example Qt, Prev: I/O Callback Example GDK, Up: Using External Event Loops + +7.8.2.6 I/O Callback Example Qt +............................... + +The I/O callback interface can also be used to integrate GPGME with the +Qt event loop. The following code snippets show how this can be done +using the appropriate register and remove I/O callback functions. In +this example, the private data of the register I/O callback function is +unused. The event notifications is missing because it does not require +any Qt specific setup. + + #include <qsocketnotifier.h> + #include <qapplication.h> + + struct IOCB { + IOCB( GpgmeIOCb f, void * d, QSocketNotifier * n ) + : func( f ), data( d ), notifier( n ) {} + GpgmeIOCb func; + void * data; + QSocketNotifier * notifier; + } + + class MyApp : public QApplication { + + // ... + + static void registerGpgmeIOCallback( void * data, int fd, int dir, + GpgmeIOCb func, void * func_data, + void ** tag ) { + QSocketNotifier * n = + new QSocketNotifier( fd, dir ? QSocketNotifier::Read + : QSocketNotifier::Write ); + connect( n, SIGNAL(activated(int)), + qApp, SLOT(slotGpgmeIOCallback(int)) ); + qApp->mIOCBs.push_back( IOCB( func, func_data, n ) ); + *tag = (void*)n; + } + + static void removeGpgmeIOCallback( void * tag ) { + if ( !tag ) return; + QSocketNotifier * n = static_cast<QSocketNotifier*>( tag ); + for ( QValueList<IOCB>::iterator it = qApp->mIOCBs.begin() ; + it != qApp->mIOCBs.end() ; ++it ) + if ( it->notifier == n ) { + delete it->notifier; + qApp->mIOCBs.erase( it ); + return; + } + } + + public slots: + void slotGpgmeIOCallback( int fd ) { + for ( QValueList<IOCB>::const_iterator it = mIOCBs.begin() ; + it != mIOCBs.end() ; ++it ) + if ( it->notifier && it->notifier->socket() == fd ) + (*(it->func)) ( it->func_data, fd ); + } + + // ... + + private: + QValueList<IOCB> mIOCBs; + // ... + }; + + +File: gpgme.info, Node: Cancellation, Prev: Using External Event Loops, Up: Run Control + +7.8.3 Cancellation +------------------ + +Sometimes you do not want to wait for an operation to finish. GPGME +provides two different functions to achieve that. The function +`gpgme_cancel' takes effect immediately. When it returns, the +operation is effectively canceled. However, it has some limitations +and can not be used with synchronous operations. In contrast, the +function `gpgme_cancel_async' can be used with any context and from any +thread, but it is not guaranteed to take effect immediately. Instead, +cancellation occurs at the next possible time (typically the next time +I/O occurs in the target context). + + -- Function: gpgme_ctx_t gpgme_cancel (gpgme_ctx_t CTX) + The function `gpgme_cancel' attempts to cancel a pending operation + in the context CTX. This only works if you use the global event + loop or your own event loop. + + If you use the global event loop, you must not call `gpgme_wait' + or `gpgme_wait' during cancellation. After successful + cancellation, you can call `gpgme_wait' (optionally waiting on + CTX), and the context CTX will appear as if it had finished with + the error code `GPG_ERR_CANCEL'. + + If you use your an external event loop, you must ensure that no I/O + callbacks are invoked for this context (for example by halting the + event loop). On successful cancellation, all registered I/O + callbacks for this context will be unregistered, and a + `GPGME_EVENT_DONE' event with the error code `GPG_ERR_CANCEL' will + be signaled. + + The function returns an error code if the cancellation failed (in + this case the state of CTX is not modified). + + -- Function: gpgme_ctx_t gpgme_cancel_async (gpgme_ctx_t CTX) + The function `gpgme_cancel' attempts to cancel a pending operation + in the context CTX. This can be called by any thread at any time + after starting an operation on the context, but will not take + effect immediately. The actual cancellation happens at the next + time GPGME processes I/O in that context. + + The function returns an error code if the cancellation failed (in + this case the state of CTX is not modified). + + +File: gpgme.info, Node: UI Server Protocol, Next: Library Copying, Prev: Contexts, Up: Top + +Appendix A The GnuPG UI Server Protocol +*************************************** + +This section specifies the protocol used between clients and a User +Interface Server (UI server). This protocol helps to build a system +where all cryptographic operations are done by a server and the server +is responsible for all dialogs. Although GPGME has no direct support +for this protocol it is believed that servers will utilize the GPGME +library; thus having the specification included in this manual is an +appropriate choice. This protocol should be referenced as `The GnuPG +UI Server Protocol'. + +A server needs to implement these commands:(1) + +* Menu: + +* UI Server Encrypt:: Encrypt a message. +* UI Server Sign:: Sign a message. +* UI Server Decrypt:: Decrypt a message. +* UI Server Verify:: Verify a message. +* UI Server Set Input Files:: Specifying the input files to operate on. +* UI Server Sign/Encrypt Files:: Encrypting and signing files. +* UI Server Verify/Decrypt Files:: Decrypting and verifying files. +* UI Server Import/Export Keys:: Managing certificates. +* UI Server Checksum Files:: Create and verify checksums for files. +* Miscellaneous UI Server Commands:: Commands not related to a specific operation. + + ---------- Footnotes ---------- + + (1) In all examples we assume that the connection has already been +established; see the Assuan manual for details. + + +File: gpgme.info, Node: UI Server Encrypt, Next: UI Server Sign, Up: UI Server Protocol + +A.1 UI Server: Encrypt a Message +================================ + +Before encryption can be done the recipients must be set using the +command: + + -- Command: RECIPIENT STRING + Set the recipient for the encryption. STRING is an RFC-2822 + recipient name ("mailbox" as per section 3.4). This command may + or may not check the recipient for validity right away; if it does + not all recipients are expected to be checked at the time of the + `ENCRYPT' command. All `RECIPIENT' commands are cumulative until a + successful `ENCRYPT' command or until a `RESET' command. + Linefeeds are obviously not allowed in STRING and should be folded + into spaces (which are equivalent). + +To tell the server the source and destination of the data, the next two +commands are to be used: + + -- Command: INPUT FD=N + Set the file descriptor for the message to be encrypted to N. The + message send to the server is binary encoded. + + GpgOL is a Windows only program, thus N is not a libc file + descriptor but a regular system handle. Given that the Assuan + connection works over a socket, it is not possible to use regular + inheritance to make the file descriptor available to the server. + Thus `DuplicateHandle' needs to be used to duplicate a handle to + the server process. This is the reason that the server needs to + implement the `GETINFO pid' command. Sending this command a second + time replaces the file descriptor set by the last one. + + -- Command: OUTPUT FD=N + Set the file descriptor to be used for the output (i.e. the + encrypted message) to N. For OpenPGP, the output needs to be + ASCII armored; for CMS, the output needs to be Base-64 encoded. + For details on the file descriptor, see the `INPUT' command. + +The setting of the recipients, the data source and destination may +happen in any order, even intermixed. If this has been done the actual +encryption operation is called using: + + -- Command: ENCRYPT --protocol=NAME + This command reads the plaintext from the file descriptor set by + the `INPUT' command, encrypts it and writes the ciphertext to the + file descriptor set by the `OUTPUT' command. The server may (and + should) overlap reading and writing. The recipients used for the + encryption are all the recipients set so far. If any recipient is + not usable the server should take appropriate measures to notify + the user about the problem and may cancel the operation by + returning an error code. The used file descriptors are void after + this command; the recipient list is only cleared if the server + returns success. + + Because GpgOL uses a streaming mode of operation the server is not + allowed to auto select the protocol and must obey to the mandatory + PROTOCOL parameter: + + `OpenPGP' + Use the OpenPGP protocol (RFC-2440). + + `CMS' + Use the CMS (PKCS#7) protocol (RFC-3852). + + + To support automagically selection of the protocol depending on the +selected keys, the server MAY implement the command: + + -- Command: PREP_ENCRYPT [--protocol=NAME] [--expect-sign] + This commands considers all recipients set so far and decides + whether it is able to take input and start the actual encryption. + This is kind of a dry-run `ENCRYPT' without requiring or using the + input and output file descriptors. The server shall cache the + result of any user selection to avoid asking this again when the + actual `ENCRYPT' command is send. The `--protocol' option is + optional; if it is not given, the server should allow the user to + select the protocol to be used based on the recipients given or by + any other means. + + If `--expect-sign' is given the server should expect that the + message will also be signed and use this hint to present a unified + recipient and signer selection dialog if possible and desired. A + selected signer should then be cached for the expected SIGN command + (which is expected in the same session but possible on another + connection). + + If this command is given again before a successful `ENCRYPT' + command, the second one takes effect. + + Before sending the OK response the server shall tell the client the + protocol to be used (either the one given by the argument or the + one selected by the user) by means of a status line: + + -- Status line: PROTOCOL NAME + Advise the client to use the protocol NAME for the `ENCRYPT' + command. The valid protocol names are listed under the + description of the `ENCRYPT' command. The server shall emit + exactly one PROTOCOL status line. + +Here is an example of a complete encryption sequence; client lines are +indicated by a C:, server responses by C:: + + C: RESET + S: OK + C: RECIPIENT foo@example.net + S: OK + C: RECIPIENT bar@example.com + S: OK + C: PREP_ENCRYPT + S: S PROTOCOL OpenPGP + S: OK + C: INPUT FD=17 + S: OK + C: OUTPUT FD=18 + S: OK + C: ENCRYPT + S: OK + + +File: gpgme.info, Node: UI Server Sign, Next: UI Server Decrypt, Prev: UI Server Encrypt, Up: UI Server Protocol + +A.2 UI Server: Sign a Message +============================= + +The server needs to implement opaque signing as well as detached +signing. Due to the nature of OpenPGP messages it is always required to +send the entire message to the server; sending just the hash is not +possible. The following two commands are required to set the input and +output file descriptors: + + -- Command: INPUT FD=N + Set the file descriptor for the message to be signed to N. The + message send to the server is binary encoded. For details on the + file descriptor, see the description of `INPUT' in the `ENCRYPT' + section. + + -- Command: OUTPUT FD=N + Set the file descriptor to be used for the output. The output is + either the complete signed message or in case of a detached + signature just that detached signature. For OpenPGP, the output + needs to be ASCII armored; for CMS, the output needs to be Base-64 + encoded. For details on the file descriptor, see the `INPUT' + command. + +To allow the server the selection of a non-default signing key the +client may optionally use the `SENDER' command, see *note command +SENDER::. + +The signing operation is then initiated by: + + -- Command: SIGN --protocol=NAME [--detached] + Sign the data set with the `INPUT' command and write it to the sink + set by OUTPUT. NAME is the signing protocol used for the message. + For a description of the allowed protocols see the `ENCRYPT' + command. With option `--detached' given, a detached signature is + created; this is actually the usual way the command is used. + +The client expects the server to send at least this status information +before the final OK response: + + -- Status line: MICALG STRING + The STRING represents the hash algorithm used to create the + signature. It is used with MOSS style signature messages and + defined by PGP/MIME (RFC-3156) and S/MIME (RFC-3851). The GPGME + library has a supporting function `gpgme_hash_algo_name' to return + the algorithm name as a string. This string needs to be + lowercased and for OpenPGP prefixed with "`pgp-'". + + +File: gpgme.info, Node: UI Server Decrypt, Next: UI Server Verify, Prev: UI Server Sign, Up: UI Server Protocol + +A.3 UI Server: Decrypt a Message +================================ + +Decryption may include the verification of OpenPGP messages. This is +due to the often used combined signing/encryption modus of OpenPGP. The +client may pass an option to the server to inhibit the signature +verification. The following two commands are required to set the input +and output file descriptors: + + -- Command: INPUT FD=N + Set the file descriptor for the message to be decrypted to N. The + message send to the server is either binary encoded or -- in the + case of OpenPGP -- ASCII armored. For details on the file + descriptor, see the description of `INPUT' in the `ENCRYPT' + section. + + -- Command: OUTPUT FD=N + Set the file descriptor to be used for the output. The output is + binary encoded. For details on the file descriptor, see the + description of `INPUT' in the `ENCRYPT' section. + +The decryption is started with the command: + + -- Command: DECRYPT --protocol=NAME [--no-verify] + NAME is the encryption protocol used for the message. For a + description of the allowed protocols see the `ENCRYPT' command. + This argument is mandatory. If the option `--no-verify' is given, + the server should not try to verify a signature, in case the input + data is an OpenPGP combined message. + + +File: gpgme.info, Node: UI Server Verify, Next: UI Server Set Input Files, Prev: UI Server Decrypt, Up: UI Server Protocol + +A.4 UI Server: Verify a Message +=============================== + +The server needs to support the verification of opaque signatures as +well as detached signatures. The kind of input sources controls what +kind message is to be verified. + + -- Command: MESSAGE FD=N + This command is used with detached signatures to set the file + descriptor for the signed data to N. The data is binary encoded + (used verbatim). For details on the file descriptor, see the + description of `INPUT' in the `ENCRYPT' section. + + -- Command: INPUT FD=N + Set the file descriptor for the opaque message or the signature + part of a detached signature to N. The message send to the server + is either binary encoded or - in the case of OpenPGP - ASCII + armored. For details on the file descriptor, see the description + of `INPUT' in the `ENCRYPT' section. + + -- Command: OUTPUT FD=N + Set the file descriptor to be used for the output. The output is + binary encoded and only used for opaque signatures. For details + on the file descriptor, see the description of `INPUT' in the + `ENCRYPT' section. + +The verification is then started using: + + -- Command: VERIFY --protocol=NAME [--silent] + NAME is the signing protocol used for the message. For a + description of the allowed protocols see the `ENCRYPT' command. + This argument is mandatory. Depending on the combination of + `MESSAGE' `INPUT' and `OUTPUT' commands, the server needs to + select the appropriate verification mode: + + MESSAGE and INPUT + This indicates a detached signature. Output data is not + applicable. + + INPUT + This indicates an opaque signature. As no output command has + been given, the server is only required to check the + signature. + + INPUT and OUTPUT + This indicates an opaque signature. The server shall write + the signed data to the file descriptor set by the output + command. This data shall even be written if the signatures + can't be verified. + + With `--silent' the server shall not display any dialog; this is for +example used by the client to get the content of opaque signed +messages. The client expects the server to send at least this status +information before the final OK response: + + -- Status line: SIGSTATUS FLAG DISPLAYSTRING + Returns the status for the signature and a short string explaining + the status. Valid values for FLAG are: + + `none' + The message has a signature but it could not not be verified + due to a missing key. + + `green' + The signature is fully valid. + + `yellow' + The signature is valid but additional information was shown + regarding the validity of the key. + + `red' + The signature is not valid. + + DISPLAYSTRING is a percent-and-plus-encoded string with a short + human readable description of the status. For example + + S SIGSTATUS green Good+signature+from+Keith+Moon+<keith@example.net> + + Note that this string needs to fit into an Assuan line and should + be short enough to be displayed as short one-liner on the clients + window. As usual the encoding of this string is UTF-8 and it + should be send in its translated form. + + The server shall send one status line for every signature found on + the message. + + + +File: gpgme.info, Node: UI Server Set Input Files, Next: UI Server Sign/Encrypt Files, Prev: UI Server Verify, Up: UI Server Protocol + +A.5 UI Server: Specifying the input files to operate on. +======================================================== + +All file related UI server commands operate on a number of input files +or directories, specified by one or more `FILE' commands: + + -- Command: FILE NAME [-continued] + Add the file or directory NAME to the list of pathnames to be + processed by the server. The parameter NAME must be an absolute + path name (including the drive letter) and is percent espaced (in + particular, the characters %, = and white space characters are + always escaped). The option `--continued' is present for all but + the last `FILE' command. + + +File: gpgme.info, Node: UI Server Sign/Encrypt Files, Next: UI Server Verify/Decrypt Files, Prev: UI Server Set Input Files, Up: UI Server Protocol + +A.6 UI Server: Encrypting and signing files. +============================================ + +First, the input files need to be specified by one or more `FILE' +commands. Afterwards, the actual operation is requested: + + -- Command: ENCRYPT_FILES -nohup + -- Command: SIGN_FILES -nohup + -- Command: ENCRYPT_SIGN_FILES -nohup + Request that the files specified by `FILE' are encrypted and/or + signed. The command selects the default action. The UI server may + allow the user to change this default afterwards interactively, and + even abort the operation or complete it only on some of the + selected files and directories. + + What it means to encrypt or sign a file or directory is specific to + the preferences of the user, the functionality the UI server + provides, and the selected protocol. Typically, for each input + file a new file is created under the original filename plus a + protocol specific extension (like `.gpg' or `.sig'), which contain + the encrypted/signed file or a detached signature. For + directories, the server may offer multiple options to the user + (for example ignore or process recursively). + + The `ENCRYPT_SIGN_FILES' command requests a combined sign and + encrypt operation. It may not be available for all protocols (for + example, it is available for OpenPGP but not for CMS). + + The option `--nohup' is mandatory. It is currently unspecified + what should happen if `--nohup' is not present. Because `--nohup' + is present, the server always returns `OK' promptly, and completes + the operation asynchronously. + + +File: gpgme.info, Node: UI Server Verify/Decrypt Files, Next: UI Server Import/Export Keys, Prev: UI Server Sign/Encrypt Files, Up: UI Server Protocol + +A.7 UI Server: Decrypting and verifying files. +============================================== + +First, the input files need to be specified by one or more `FILE' +commands. Afterwards, the actual operation is requested: + + -- Command: DECRYPT_FILES -nohup + -- Command: VERIFY_FILES -nohup + -- Command: DECRYPT_VERIFY_FILES -nohup + Request that the files specified by `FILE' are decrypted and/or + verified. The command selects the default action. The UI server + may allow the user to change this default afterwards + interactively, and even abort the operation or complete it only on + some of the selected files and directories. + + What it means to decrypt or verify a file or directory is specific + to the preferences of the user, the functionality the UI server + provides, and the selected protocol. Typically, for decryption, a + new file is created for each input file under the original + filename minus a protocol specific extension (like `.gpg') which + contains the original plaintext. For verification a status is + displayed for each signed input file, indicating if it is signed, + and if yes, if the signature is valid. For files that are signed + and encrypted, the `VERIFY' command transiently decrypts the file + to verify the enclosed signature. For directories, the server may + offer multiple options to the user (for example ignore or process + recursively). + + The option `--nohup' is mandatory. It is currently unspecified + what should happen if `--nohup' is not present. Because `--nohup' + is present, the server always returns `OK' promptly, and completes + the operation asynchronously. + + +File: gpgme.info, Node: UI Server Import/Export Keys, Next: UI Server Checksum Files, Prev: UI Server Verify/Decrypt Files, Up: UI Server Protocol + +A.8 UI Server: Managing certificates. +===================================== + +First, the input files need to be specified by one or more `FILE' +commands. Afterwards, the actual operation is requested: + + -- Command: IMPORT_FILES -nohup + Request that the certificates contained in the files specified by + `FILE' are imported into the local certificate databases. + + For directories, the server may offer multiple options to the user + (for example ignore or process recursively). + + The option `--nohup' is mandatory. It is currently unspecified + what should happen if `--nohup' is not present. Because `--nohup' + is present, the server always returns `OK' promptly, and completes + the operation asynchronously. + + FIXME: It may be nice to support an `EXPORT' command as well, which +is enabled by the context menu of the background of a directory. + + +File: gpgme.info, Node: UI Server Checksum Files, Next: Miscellaneous UI Server Commands, Prev: UI Server Import/Export Keys, Up: UI Server Protocol + +A.9 UI Server: Create and verify checksums for files. +===================================================== + +First, the input files need to be specified by one or more `FILE' +commands. Afterwards, the actual operation is requested: + + -- Command: CHECKSUM_CREATE_FILES -nohup + Request that checksums are created for the files specifed by + `FILE'. The choice of checksum algorithm and the destination + storage and format for the created checksums depend on the + preferences of the user and the functionality provided by the UI + server. For directories, the server may offer multiple options to + the user (for example ignore or process recursively). + + The option `--nohup' is mandatory. It is currently unspecified + what should happen if `--nohup' is not present. Because `--nohup' + is present, the server always returns `OK' promptly, and completes + the operation asynchronously. + + -- Command: CHECKSUM_VERIFY_FILES -nohup + Request that checksums are created for the files specifed by + `FILE' and verified against previously created and stored + checksums. The choice of checksum algorithm and the source storage + and format for previously created checksums depend on the + preferences of the user and the functionality provided by the UI + server. For directories, the server may offer multiple options to + the user (for example ignore or process recursively). + + If the source storage of previously created checksums is available + to the user through the Windows shell, this command may also + accept such checksum files as `FILE' arguments. In this case, the + UI server should instead verify the checksum of the referenced + files as if they were given as INPUT files. + + The option `--nohup' is mandatory. It is currently unspecified + what should happen if `--nohup' is not present. Because `--nohup' + is present, the server always returns `OK' promptly, and completes + the operation asynchronously. + + +File: gpgme.info, Node: Miscellaneous UI Server Commands, Prev: UI Server Checksum Files, Up: UI Server Protocol + +A.10 Miscellaneous UI Server Commands +===================================== + +The server needs to implement the following commands which are not +related to a specific command: + + -- Command: GETINFO WHAT + This is a multi purpose command, commonly used to return a variety + of information. The required subcommands as described by the WHAT + parameter are: + + `pid' + Return the process id of the server in decimal notation using + an Assuan data line. + +To allow the server to pop up the windows in the correct relation to the +client, the client is advised to tell the server by sending the option: + + -- Command option: window-id NUMBER + The NUMBER represents the native window ID of the clients current + window. On Windows systems this is a windows handle (`HWND') and + on X11 systems it is the `X Window ID'. The number needs to be + given as a hexadecimal value so that it is easier to convey pointer + values (e.g. `HWND'). + +A client may want to fire up the certificate manager of the server. To +do this it uses the Assuan command: + + -- Command: START_KEYMANAGER + The server shall pop up the main window of the key manager (aka + certificate manager). The client expects that the key manager is + brought into the foregound and that this command immediatley + returns (does not wait until the key manager has been fully + brought up). + +A client may want to fire up the configuration dialog of the server. To +do this it uses the Assuan command: + + -- Command: START_CONFDIALOG + The server shall pop up its configuration dialog. The client + expects that this dialog is brought into the foregound and that + this command immediatley returns (i.e. it does not wait until the + dialog has been fully brought up). + +When doing an operation on a mail, it is useful to let the server know +the address of the sender: + + -- Command: SENDER [--info] [--protocol=NAME] EMAIL + EMAIL is the plain ASCII encoded address ("addr-spec" as per + RFC-2822) enclosed in angle brackets. The address set with this + command is valid until a successful completion of the operation or + until a `RESET' command. A second command overrides the effect of + the first one; if EMAIL is not given and `--info' is not used, the + server shall use the default signing key. + + If option `--info' is not given, the server shall also suggest a + protocol to use for signing. The client may use this suggested + protocol on its own discretion. The same status line as with + PREP_ENCRYPT is used for this. + + The option `--protocol' may be used to give the server a hint on + which signing protocol should be preferred. + +To allow the UI-server to visually identify a running operation or to +associate operations the server MAY support the command: + + -- Command: SESSION NUMBER [STRING] + The NUMBER is an arbitrary value, a server may use to associate + simultaneous running sessions. It is a 32 bit unsigned integer + with `0' as a special value indicating that no session association + shall be done. + + If STRING is given, the server may use this as the title of a + window or, in the case of an email operation, to extract the + sender's address. The string may contain spaces; thus no + plus-escaping is used. + + This command may be used at any time and overrides the effect of + the last command. A `RESET' undoes the effect of this command. + + + +File: gpgme.info, Node: Library Copying, Next: Copying, Prev: UI Server Protocol, Up: Top + +GNU Lesser General Public License +********************************* + + Version 2.1, February 1999 + + Copyright (C) 1991, 1999 Free Software Foundation, Inc. + 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + [This is the first released version of the Lesser GPL. It also counts + as the successor of the GNU Library Public License, version 2, hence the + version number 2.1.] + +Preamble +======== + +The licenses for most software are designed to take away your freedom +to share and change it. By contrast, the GNU General Public Licenses +are intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. + + This license, the Lesser General Public License, applies to some +specially designated software--typically libraries--of the Free +Software Foundation and other authors who decide to use it. You can use +it too, but we suggest you first think carefully about whether this +license or the ordinary General Public License is the better strategy to +use in any particular case, based on the explanations below. + + When we speak of free software, we are referring to freedom of use, +not price. Our General Public Licenses are designed to make sure that +you have the freedom to distribute copies of free software (and charge +for this service if you wish); that you receive source code or can get +it if you want it; that you can change the software and use pieces of it +in new free programs; and that you are informed that you can do these +things. + + To protect your rights, we need to make restrictions that forbid +distributors to deny you these rights or to ask you to surrender these +rights. These restrictions translate to certain responsibilities for +you if you distribute copies of the library or if you modify it. + + For example, if you distribute copies of the library, whether gratis +or for a fee, you must give the recipients all the rights that we gave +you. You must make sure that they, too, receive or can get the source +code. If you link other code with the library, you must provide +complete object files to the recipients, so that they can relink them +with the library after making changes to the library and recompiling +it. And you must show them these terms so they know their rights. + + We protect your rights with a two-step method: (1) we copyright the +library, and (2) we offer you this license, which gives you legal +permission to copy, distribute and/or modify the library. + + To protect each distributor, we want to make it very clear that +there is no warranty for the free library. Also, if the library is +modified by someone else and passed on, the recipients should know that +what they have is not the original version, so that the original +author's reputation will not be affected by problems that might be +introduced by others. + + Finally, software patents pose a constant threat to the existence of +any free program. We wish to make sure that a company cannot +effectively restrict the users of a free program by obtaining a +restrictive license from a patent holder. Therefore, we insist that +any patent license obtained for a version of the library must be +consistent with the full freedom of use specified in this license. + + Most GNU software, including some libraries, is covered by the +ordinary GNU General Public License. This license, the GNU Lesser +General Public License, applies to certain designated libraries, and is +quite different from the ordinary General Public License. We use this +license for certain libraries in order to permit linking those +libraries into non-free programs. + + When a program is linked with a library, whether statically or using +a shared library, the combination of the two is legally speaking a +combined work, a derivative of the original library. The ordinary +General Public License therefore permits such linking only if the +entire combination fits its criteria of freedom. The Lesser General +Public License permits more lax criteria for linking other code with +the library. + + We call this license the "Lesser" General Public License because it +does _Less_ to protect the user's freedom than the ordinary General +Public License. It also provides other free software developers Less +of an advantage over competing non-free programs. These disadvantages +are the reason we use the ordinary General Public License for many +libraries. However, the Lesser license provides advantages in certain +special circumstances. + + For example, on rare occasions, there may be a special need to +encourage the widest possible use of a certain library, so that it +becomes a de-facto standard. To achieve this, non-free programs must be +allowed to use the library. A more frequent case is that a free +library does the same job as widely used non-free libraries. In this +case, there is little to gain by limiting the free library to free +software only, so we use the Lesser General Public License. + + In other cases, permission to use a particular library in non-free +programs enables a greater number of people to use a large body of free +software. For example, permission to use the GNU C Library in non-free +programs enables many more people to use the whole GNU operating +system, as well as its variant, the GNU/Linux operating system. + + Although the Lesser General Public License is Less protective of the +users' freedom, it does ensure that the user of a program that is +linked with the Library has the freedom and the wherewithal to run that +program using a modified version of the Library. + + The precise terms and conditions for copying, distribution and +modification follow. Pay close attention to the difference between a +"work based on the library" and a "work that uses the library". The +former contains code derived from the library, whereas the latter must +be combined with the library in order to run. + + GNU LESSER GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + 0. This License Agreement applies to any software library or other + program which contains a notice placed by the copyright holder or + other authorized party saying it may be distributed under the + terms of this Lesser General Public License (also called "this + License"). Each licensee is addressed as "you". + + A "library" means a collection of software functions and/or data + prepared so as to be conveniently linked with application programs + (which use some of those functions and data) to form executables. + + The "Library", below, refers to any such software library or work + which has been distributed under these terms. A "work based on the + Library" means either the Library or any derivative work under + copyright law: that is to say, a work containing the Library or a + portion of it, either verbatim or with modifications and/or + translated straightforwardly into another language. (Hereinafter, + translation is included without limitation in the term + "modification".) + + "Source code" for a work means the preferred form of the work for + making modifications to it. For a library, complete source code + means all the source code for all modules it contains, plus any + associated interface definition files, plus the scripts used to + control compilation and installation of the library. + + Activities other than copying, distribution and modification are + not covered by this License; they are outside its scope. The act + of running a program using the Library is not restricted, and + output from such a program is covered only if its contents + constitute a work based on the Library (independent of the use of + the Library in a tool for writing it). Whether that is true + depends on what the Library does and what the program that uses + the Library does. + + 1. You may copy and distribute verbatim copies of the Library's + complete source code as you receive it, in any medium, provided + that you conspicuously and appropriately publish on each copy an + appropriate copyright notice and disclaimer of warranty; keep + intact all the notices that refer to this License and to the + absence of any warranty; and distribute a copy of this License + along with the Library. + + You may charge a fee for the physical act of transferring a copy, + and you may at your option offer warranty protection in exchange + for a fee. + + 2. You may modify your copy or copies of the Library or any portion + of it, thus forming a work based on the Library, and copy and + distribute such modifications or work under the terms of Section 1 + above, provided that you also meet all of these conditions: + + a. The modified work must itself be a software library. + + b. You must cause the files modified to carry prominent notices + stating that you changed the files and the date of any change. + + c. You must cause the whole of the work to be licensed at no + charge to all third parties under the terms of this License. + + d. If a facility in the modified Library refers to a function or + a table of data to be supplied by an application program that + uses the facility, other than as an argument passed when the + facility is invoked, then you must make a good faith effort + to ensure that, in the event an application does not supply + such function or table, the facility still operates, and + performs whatever part of its purpose remains meaningful. + + (For example, a function in a library to compute square roots + has a purpose that is entirely well-defined independent of the + application. Therefore, Subsection 2d requires that any + application-supplied function or table used by this function + must be optional: if the application does not supply it, the + square root function must still compute square roots.) + + These requirements apply to the modified work as a whole. If + identifiable sections of that work are not derived from the + Library, and can be reasonably considered independent and separate + works in themselves, then this License, and its terms, do not + apply to those sections when you distribute them as separate + works. But when you distribute the same sections as part of a + whole which is a work based on the Library, the distribution of + the whole must be on the terms of this License, whose permissions + for other licensees extend to the entire whole, and thus to each + and every part regardless of who wrote it. + + Thus, it is not the intent of this section to claim rights or + contest your rights to work written entirely by you; rather, the + intent is to exercise the right to control the distribution of + derivative or collective works based on the Library. + + In addition, mere aggregation of another work not based on the + Library with the Library (or with a work based on the Library) on + a volume of a storage or distribution medium does not bring the + other work under the scope of this License. + + 3. You may opt to apply the terms of the ordinary GNU General Public + License instead of this License to a given copy of the Library. + To do this, you must alter all the notices that refer to this + License, so that they refer to the ordinary GNU General Public + License, version 2, instead of to this License. (If a newer + version than version 2 of the ordinary GNU General Public License + has appeared, then you can specify that version instead if you + wish.) Do not make any other change in these notices. + + Once this change is made in a given copy, it is irreversible for + that copy, so the ordinary GNU General Public License applies to + all subsequent copies and derivative works made from that copy. + + This option is useful when you wish to copy part of the code of + the Library into a program that is not a library. + + 4. You may copy and distribute the Library (or a portion or + derivative of it, under Section 2) in object code or executable + form under the terms of Sections 1 and 2 above provided that you + accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software + interchange. + + If distribution of object code is made by offering access to copy + from a designated place, then offering equivalent access to copy + the source code from the same place satisfies the requirement to + distribute the source code, even though third parties are not + compelled to copy the source along with the object code. + + 5. A program that contains no derivative of any portion of the + Library, but is designed to work with the Library by being + compiled or linked with it, is called a "work that uses the + Library". Such a work, in isolation, is not a derivative work of + the Library, and therefore falls outside the scope of this License. + + However, linking a "work that uses the Library" with the Library + creates an executable that is a derivative of the Library (because + it contains portions of the Library), rather than a "work that + uses the library". The executable is therefore covered by this + License. Section 6 states terms for distribution of such + executables. + + When a "work that uses the Library" uses material from a header + file that is part of the Library, the object code for the work may + be a derivative work of the Library even though the source code is + not. Whether this is true is especially significant if the work + can be linked without the Library, or if the work is itself a + library. The threshold for this to be true is not precisely + defined by law. + + If such an object file uses only numerical parameters, data + structure layouts and accessors, and small macros and small inline + functions (ten lines or less in length), then the use of the object + file is unrestricted, regardless of whether it is legally a + derivative work. (Executables containing this object code plus + portions of the Library will still fall under Section 6.) + + Otherwise, if the work is a derivative of the Library, you may + distribute the object code for the work under the terms of Section + 6. Any executables containing that work also fall under Section 6, + whether or not they are linked directly with the Library itself. + + 6. As an exception to the Sections above, you may also combine or + link a "work that uses the Library" with the Library to produce a + work containing portions of the Library, and distribute that work + under terms of your choice, provided that the terms permit + modification of the work for the customer's own use and reverse + engineering for debugging such modifications. + + You must give prominent notice with each copy of the work that the + Library is used in it and that the Library and its use are covered + by this License. You must supply a copy of this License. If the + work during execution displays copyright notices, you must include + the copyright notice for the Library among them, as well as a + reference directing the user to the copy of this License. Also, + you must do one of these things: + + a. Accompany the work with the complete corresponding + machine-readable source code for the Library including + whatever changes were used in the work (which must be + distributed under Sections 1 and 2 above); and, if the work + is an executable linked with the Library, with the complete + machine-readable "work that uses the Library", as object code + and/or source code, so that the user can modify the Library + and then relink to produce a modified executable containing + the modified Library. (It is understood that the user who + changes the contents of definitions files in the Library will + not necessarily be able to recompile the application to use + the modified definitions.) + + b. Use a suitable shared library mechanism for linking with the + Library. A suitable mechanism is one that (1) uses at run + time a copy of the library already present on the user's + computer system, rather than copying library functions into + the executable, and (2) will operate properly with a modified + version of the library, if the user installs one, as long as + the modified version is interface-compatible with the version + that the work was made with. + + c. Accompany the work with a written offer, valid for at least + three years, to give the same user the materials specified in + Subsection 6a, above, for a charge no more than the cost of + performing this distribution. + + d. If distribution of the work is made by offering access to copy + from a designated place, offer equivalent access to copy the + above specified materials from the same place. + + e. Verify that the user has already received a copy of these + materials or that you have already sent this user a copy. + + For an executable, the required form of the "work that uses the + Library" must include any data and utility programs needed for + reproducing the executable from it. However, as a special + exception, the materials to be distributed need not include + anything that is normally distributed (in either source or binary + form) with the major components (compiler, kernel, and so on) of + the operating system on which the executable runs, unless that + component itself accompanies the executable. + + It may happen that this requirement contradicts the license + restrictions of other proprietary libraries that do not normally + accompany the operating system. Such a contradiction means you + cannot use both them and the Library together in an executable + that you distribute. + + 7. You may place library facilities that are a work based on the + Library side-by-side in a single library together with other + library facilities not covered by this License, and distribute + such a combined library, provided that the separate distribution + of the work based on the Library and of the other library + facilities is otherwise permitted, and provided that you do these + two things: + + a. Accompany the combined library with a copy of the same work + based on the Library, uncombined with any other library + facilities. This must be distributed under the terms of the + Sections above. + + b. Give prominent notice with the combined library of the fact + that part of it is a work based on the Library, and explaining + where to find the accompanying uncombined form of the same + work. + + 8. You may not copy, modify, sublicense, link with, or distribute the + Library except as expressly provided under this License. Any + attempt otherwise to copy, modify, sublicense, link with, or + distribute the Library is void, and will automatically terminate + your rights under this License. However, parties who have + received copies, or rights, from you under this License will not + have their licenses terminated so long as such parties remain in + full compliance. + + 9. You are not required to accept this License, since you have not + signed it. However, nothing else grants you permission to modify + or distribute the Library or its derivative works. These actions + are prohibited by law if you do not accept this License. + Therefore, by modifying or distributing the Library (or any work + based on the Library), you indicate your acceptance of this + License to do so, and all its terms and conditions for copying, + distributing or modifying the Library or works based on it. + + 10. Each time you redistribute the Library (or any work based on the + Library), the recipient automatically receives a license from the + original licensor to copy, distribute, link with or modify the + Library subject to these terms and conditions. You may not impose + any further restrictions on the recipients' exercise of the rights + granted herein. You are not responsible for enforcing compliance + by third parties with this License. + + 11. If, as a consequence of a court judgment or allegation of patent + infringement or for any other reason (not limited to patent + issues), conditions are imposed on you (whether by court order, + agreement or otherwise) that contradict the conditions of this + License, they do not excuse you from the conditions of this + License. If you cannot distribute so as to satisfy simultaneously + your obligations under this License and any other pertinent + obligations, then as a consequence you may not distribute the + Library at all. For example, if a patent license would not permit + royalty-free redistribution of the Library by all those who + receive copies directly or indirectly through you, then the only + way you could satisfy both it and this License would be to refrain + entirely from distribution of the Library. + + If any portion of this section is held invalid or unenforceable + under any particular circumstance, the balance of the section is + intended to apply, and the section as a whole is intended to apply + in other circumstances. + + It is not the purpose of this section to induce you to infringe any + patents or other property right claims or to contest validity of + any such claims; this section has the sole purpose of protecting + the integrity of the free software distribution system which is + implemented by public license practices. Many people have made + generous contributions to the wide range of software distributed + through that system in reliance on consistent application of that + system; it is up to the author/donor to decide if he or she is + willing to distribute software through any other system and a + licensee cannot impose that choice. + + This section is intended to make thoroughly clear what is believed + to be a consequence of the rest of this License. + + 12. If the distribution and/or use of the Library is restricted in + certain countries either by patents or by copyrighted interfaces, + the original copyright holder who places the Library under this + License may add an explicit geographical distribution limitation + excluding those countries, so that distribution is permitted only + in or among countries not thus excluded. In such case, this + License incorporates the limitation as if written in the body of + this License. + + 13. The Free Software Foundation may publish revised and/or new + versions of the Lesser General Public License from time to time. + Such new versions will be similar in spirit to the present version, + but may differ in detail to address new problems or concerns. + + Each version is given a distinguishing version number. If the + Library specifies a version number of this License which applies + to it and "any later version", you have the option of following + the terms and conditions either of that version or of any later + version published by the Free Software Foundation. If the Library + does not specify a license version number, you may choose any + version ever published by the Free Software Foundation. + + 14. If you wish to incorporate parts of the Library into other free + programs whose distribution conditions are incompatible with these, + write to the author to ask for permission. For software which is + copyrighted by the Free Software Foundation, write to the Free + Software Foundation; we sometimes make exceptions for this. Our + decision will be guided by the two goals of preserving the free + status of all derivatives of our free software and of promoting + the sharing and reuse of software generally. + + NO WARRANTY + 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO + WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE + LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT + HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT + WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT + NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND + FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE + QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE + LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY + SERVICING, REPAIR OR CORRECTION. + + 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN + WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY + MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE + LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, + INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR + INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF + DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU + OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY + OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS +How to Apply These Terms to Your New Libraries +============================================== + +If you develop a new library, and you want it to be of the greatest +possible use to the public, we recommend making it free software that +everyone can redistribute and change. You can do so by permitting +redistribution under these terms (or, alternatively, under the terms of +the ordinary General Public License). + + To apply these terms, attach the following notices to the library. +It is safest to attach them to the start of each source file to most +effectively convey the exclusion of warranty; and each file should have +at least the "copyright" line and a pointer to where the full notice is +found. + + ONE LINE TO GIVE THE LIBRARY'S NAME AND AN IDEA OF WHAT IT DOES. + Copyright (C) YEAR NAME OF AUTHOR + + This library is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or (at + your option) any later version. + + This library is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, + USA. + + Also add information on how to contact you by electronic and paper +mail. + + You should also get your employer (if you work as a programmer) or +your school, if any, to sign a "copyright disclaimer" for the library, +if necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the library + `Frob' (a library for tweaking knobs) written by James Random Hacker. + + SIGNATURE OF TY COON, 1 April 1990 + Ty Coon, President of Vice + + That's all there is to it! + |