1 ()\input texinfo @c -*- Texinfo -*-
2 @setfilename gpgme.info
3 @settitle The `GnuPG Made Easy' Reference Manual
5 @dircategory GNU Libraries
7 * @acronym{GPGME}: (gpgme). Adding support for cryptography to your program.
12 @c Unify some of the indices.
17 This file documents the @acronym{GPGME} library.
19 This is Edition @value{EDITION}, last updated @value{UPDATED}, of
20 @cite{The `GnuPG Made Easy' Reference Manual}, for Version
23 @c NOTE: Don't forget to update the year for the TeX version, too.
24 Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007 g10 Code GmbH.
26 The GPGME reference manual is free software; you can redistribute it
27 and/or modify it under the terms of the GNU Lesser General Public
28 License as published by the Free Software Foundation; either version
29 2.1 of the License, or (at your option) any later version.
31 The GPGME reference manual is distributed in the hope that it will be
32 useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
33 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
34 Lesser General Public License for more details.
36 You should have received a copy of the GNU Lesser General Public
37 License along with this program; if not, write to the Free Software
38 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
43 @shorttitlepage The `GnuPG Made Easy' Reference Manual
46 @center @titlefont{The `GnuPG Made Easy'}
48 @center @titlefont{Reference Manual}
50 @center Edition @value{EDITION}
52 @center last updated @value{UPDATED}
54 @center for version @value{VERSION}
56 @vskip 0pt plus 1filll
57 Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007 g10 Code GmbH.
60 The GPGME reference manual is free software; you can redistribute it
61 and/or modify it under the terms of the GNU Lesser General Public
62 License as published by the Free Software Foundation; either version
63 2.1 of the License, or (at your option) any later version.
65 The GPGME reference manual is distributed in the hope that it will be
66 useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
67 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
68 Lesser General Public License for more details.
70 You should have received a copy of the GNU Lesser General Public
71 License along with this program; if not, write to the Free Software
72 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
79 This is Edition @value{EDITION}, last updated @value{UPDATED}, of
80 @cite{The `GnuPG Made Easy' Reference Manual}, for Version
81 @value{VERSION} of the @acronym{GPGME} library.
85 * Introduction:: How to use this manual.
86 * Preparation:: What you should do before using the library.
87 * Protocols and Engines:: Supported crypto protocols.
88 * Algorithms:: Supported algorithms.
89 * Error Handling:: Error numbers and their meanings.
90 * Exchanging Data:: Passing data to and from @acronym{GPGME}.
91 * Contexts:: Handling @acronym{GPGME} contexts.
95 * Library Copying:: The GNU Lesser General Public License says
96 how you can copy and share `GnuPG Made Easy'.
100 * Concept Index:: Index of concepts and programs.
101 * Function and Data Index:: Index of functions, variables and data types.
105 --- The Detailed Node Listing ---
109 * Getting Started:: Purpose of the manual, and how to use it.
110 * Features:: Reasons to install and use @acronym{GPGME}.
111 * Overview:: Basic architecture of the @acronym{GPGME} library.
115 * Header:: What header file you need to include.
116 * Building the Source:: Compiler options to be used.
117 * Largefile Support (LFS):: How to use @acronym{GPGME} with LFS.
118 * Using Automake:: Compiler options to be used the easy way.
119 * Using Libtool:: Avoiding compiler options entirely.
120 * Library Version Check:: Getting and verifying the library version.
121 * Signal Handling:: How @acronym{GPGME} affects signal handling.
122 * Multi Threading:: How @acronym{GPGME} can be used in an MT environment.
124 Protocols and Engines
126 * Engine Version Check:: Verifying the engine version.
127 * Engine Information:: Obtaining more information about the engines.
128 * Engine Configuration:: Changing the engine configuration.
129 * OpenPGP:: Support for the OpenPGP protocol.
130 * Cryptographic Message Syntax:: Support for the CMS.
134 * Public Key Algorithms:: A list of all public key algorithms.
135 * Hash Algorithms:: A list of all hash algorithms.
139 * Error Values:: The error value and what it means.
140 * Error Codes:: A list of important error codes.
141 * Error Sources:: A list of important error sources.
142 * Error Strings:: How to get a descriptive string from a value.
146 * Creating Data Buffers:: Creating new data buffers.
147 * Destroying Data Buffers:: Releasing data buffers.
148 * Manipulating Data Buffers:: Operations on data buffers.
150 Creating Data Buffers
152 * Memory Based Data Buffers:: Creating memory based data buffers.
153 * File Based Data Buffers:: Creating file based data buffers.
154 * Callback Based Data Buffers:: Creating callback based data buffers.
156 Manipulating Data Buffers
158 * Data Buffer I/O Operations:: I/O operations on data buffers.
159 * Data Buffer Meta-Data:: Meta-data manipulation of data buffers.
163 * Creating Contexts:: Creating new @acronym{GPGME} contexts.
164 * Destroying Contexts:: Releasing @acronym{GPGME} contexts.
165 * Context Attributes:: Setting properties of a context.
166 * Key Management:: Managing keys with @acronym{GPGME}.
167 * Trust Item Management:: Managing trust items with @acronym{GPGME}.
168 * Crypto Operations:: Using a context for cryptography.
169 * Run Control:: Controlling how operations are run.
173 * Protocol Selection:: Selecting the protocol used by a context.
174 * Crypto Engine:: Configuring the crypto engine.
175 * ASCII Armor:: Requesting @acronym{ASCII} armored output.
176 * Text Mode:: Choosing canonical text mode.
177 * Included Certificates:: Including a number of certificates.
178 * Key Listing Mode:: Selecting key listing mode.
179 * Passphrase Callback:: Getting the passphrase from the user.
180 * Progress Meter Callback:: Being informed about the progress.
181 * Locale:: Setting the locale of a context.
185 * Listing Keys:: Browsing the list of available keys.
186 * Information About Keys:: Requesting detailed information about keys.
187 * Key Signatures:: Listing the signatures on a key.
188 * Manipulating Keys:: Operations on keys.
189 * Generating Keys:: Creating new key pairs.
190 * Exporting Keys:: Retrieving key data from the key ring.
191 * Importing Keys:: Adding keys to the key ring.
192 * Deleting Keys:: Removing keys from the key ring.
193 * Advanced Key Editing:: Advanced key edit operation.
195 Trust Item Management
197 * Listing Trust Items:: Browsing the list of available trust items.
198 * Information About Trust Items:: Requesting information about trust items.
199 * Manipulating Trust Items:: Operations on trust items.
203 * Decrypt:: Decrypting a ciphertext.
204 * Verify:: Verifying a signature.
205 * Decrypt and Verify:: Decrypting a signed ciphertext.
206 * Sign:: Creating a signature.
207 * Encrypt:: Encrypting a plaintext.
211 * Selecting Signers:: How to choose the keys to sign with.
212 * Creating a Signature:: How to create a signature.
213 * Signature Notation Data:: How to add notation data to a signature.
217 * Encrypting a Plaintext:: How to encrypt a plaintext.
221 * Waiting For Completion:: Waiting until an operation is completed.
222 * Using External Event Loops:: Advanced control over what happens when.
223 * Cancellation:: How to end pending operations prematurely.
225 Using External Event Loops
227 * I/O Callback Interface:: How I/O callbacks are registered.
228 * Registering I/O Callbacks:: How to use I/O callbacks for a context.
229 * I/O Callback Example:: An example how to use I/O callbacks.
230 * I/O Callback Example GTK+:: How to integrate @acronym{GPGME} in GTK+.
231 * I/O Callback Example GDK:: How to integrate @acronym{GPGME} in GDK.
232 * I/O Callback Example Qt:: How to integrate @acronym{GPGME} in Qt.
238 @chapter Introduction
240 `GnuPG Made Easy' (@acronym{GPGME}) is a C language library that
241 allows to add support for cryptography to a program. It is designed
242 to make access to public key crypto engines like GnuPG or GpgSM easier
243 for applications. @acronym{GPGME} provides a high-level crypto API
244 for encryption, decryption, signing, signature verification and key
247 @acronym{GPGME} uses GnuPG and GpgSM as its backends to support
248 OpenPGP and the Cryptographic Message Syntax (CMS).
251 * Getting Started:: Purpose of the manual, and how to use it.
252 * Features:: Reasons to install and use @acronym{GPGME}.
253 * Overview:: Basic architecture of the @acronym{GPGME} library.
257 @node Getting Started
258 @section Getting Started
260 This manual documents the @acronym{GPGME} library programming
261 interface. All functions and data types provided by the library are
264 The reader is assumed to possess basic knowledge about cryptography in
265 general, and public key cryptography in particular. The underlying
266 cryptographic engines that are used by the library are not explained,
267 but where necessary, special features or requirements by an engine are
268 mentioned as far as they are relevant to @acronym{GPGME} or its users.
270 This manual can be used in several ways. If read from the beginning
271 to the end, it gives a good introduction into the library and how it
272 can be used in an application. Forward references are included where
273 necessary. Later on, the manual can be used as a reference manual to
274 get just the information needed about any particular interface of the
275 library. Experienced programmers might want to start looking at the
276 examples at the end of the manual, and then only read up those parts
277 of the interface which are unclear.
283 @acronym{GPGME} has a couple of advantages over other libraries doing
284 a similar job, and over implementing support for GnuPG or other crypto
285 engines into your application directly.
288 @item it's free software
289 Anybody can use, modify, and redistribute it under the terms of the GNU
290 Lesser General Public License (@pxref{Library Copying}).
293 @acronym{GPGME} provides transparent support for several cryptographic
294 protocols by different engines. Currently, @acronym{GPGME} supports
295 the OpenPGP protocol using GnuPG as the backend, and the Cryptographic
296 Message Syntax using GpgSM as the backend.
299 @acronym{GPGME} hides the differences between the protocols and
300 engines from the programmer behind an easy-to-use interface. This way
301 the programmer can focus on the other parts of the program, and still
302 integrate strong cryptography in his application. Once support for
303 @acronym{GPGME} has been added to a program, it is easy to add support
304 for other crypto protocols once @acronym{GPGME} backends provide them.
311 @acronym{GPGME} provides a data abstraction that is used to pass data
312 to the crypto engine, and receive returned data from it. Data can be
313 read from memory or from files, but it can also be provided by a
316 The actual cryptographic operations are always set within a context.
317 A context provides configuration parameters that define the behaviour
318 of all operations performed within it. Only one operation per context
319 is allowed at any time, but when one operation is finished, you can
320 run the next operation in the same context. There can be more than
321 one context, and all can run different operations at the same time.
323 Furthermore, @acronym{GPGME} has rich key management facilities
324 including listing keys, querying their attributes, generating,
325 importing, exporting and deleting keys, and acquiring information
326 about the trust path.
328 With some precautions, @acronym{GPGME} can be used in a multi-threaded
329 environment, although it is not completely thread safe and thus needs
330 the support of the application.
336 To use @acronym{GPGME}, you have to perform some changes to your
337 sources and the build system. The necessary changes are small and
338 explained in the following sections. At the end of this chapter, it
339 is described how the library is initialized, and how the requirements
340 of the library are verified.
343 * Header:: What header file you need to include.
344 * Building the Source:: Compiler options to be used.
345 * Largefile Support (LFS):: How to use @acronym{GPGME} with LFS.
346 * Using Automake:: Compiler options to be used the easy way.
347 * Using Libtool:: Avoiding compiler options entirely.
348 * Library Version Check:: Getting and verifying the library version.
349 * Signal Handling:: How @acronym{GPGME} affects signal handling.
350 * Multi Threading:: How @acronym{GPGME} can be used in an MT environment.
359 All interfaces (data types and functions) of the library are defined
360 in the header file `gpgme.h'. You must include this in all programs
361 using the library, either directly or through some other header file,
368 The name space of @acronym{GPGME} is @code{gpgme_*} for function names
369 and data types and @code{GPGME_*} for other symbols. Symbols internal
370 to @acronym{GPGME} take the form @code{_gpgme_*} and @code{_GPGME_*}.
372 Because @acronym{GPGME} makes use of the GPG Error library, using
373 @acronym{GPGME} will also use the @code{GPG_ERR_*} name space
374 directly, and the @code{gpg_err*} and @code{gpg_str*} name space
378 @node Building the Source
379 @section Building the Source
380 @cindex compiler options
381 @cindex compiler flags
383 If you want to compile a source file including the `gpgme.h' header
384 file, you must make sure that the compiler can find it in the
385 directory hierarchy. This is accomplished by adding the path to the
386 directory in which the header file is located to the compilers include
387 file search path (via the @option{-I} option).
389 However, the path to the include file is determined at the time the
390 source is configured. To solve this problem, gpgme ships with a small
391 helper program @command{gpgme-config} that knows about the path to the
392 include file and other configuration options. The options that need
393 to be added to the compiler invocation at compile time are output by
394 the @option{--cflags} option to @command{gpgme-config}. The following
395 example shows how it can be used at the command line:
398 gcc -c foo.c `gpgme-config --cflags`
401 Adding the output of @samp{gpgme-config --cflags} to the compiler
402 command line will ensure that the compiler can find the
403 @acronym{GPGME} header file.
405 A similar problem occurs when linking the program with the library.
406 Again, the compiler has to find the library files. For this to work,
407 the path to the library files has to be added to the library search
408 path (via the @option{-L} option). For this, the option
409 @option{--libs} to @command{gpgme-config} can be used. For
410 convenience, this option also outputs all other options that are
411 required to link the program with @acronym{GPGME} (in particular, the
412 @samp{-lgpgme} option). The example shows how to link @file{foo.o}
413 with the @acronym{GPGME} library to a program @command{foo}.
416 gcc -o foo foo.o `gpgme-config --libs`
419 Of course you can also combine both examples to a single command by
420 specifying both options to @command{gpgme-config}:
423 gcc -o foo foo.c `gpgme-config --cflags --libs`
426 If you want to link to one of the thread-safe versions of
427 @acronym{GPGME}, you must specify the @option{--thread} option before
428 any other option to select the thread package you want to link with.
429 Supported thread packages are @option{--thread=pth} and
430 @option{--thread=pthread}.
433 @node Largefile Support (LFS)
434 @section Largefile Support (LFS)
435 @cindex largefile support
438 @acronym{GPGME} is compiled with largefile support by default, if it
439 is available on the system. This means that GPGME supports files
440 larger than two gigabyte in size, if the underlying operating system
441 can. On some systems, largefile support is already the default. On
442 such systems, nothing special is required. However, some systems
443 provide only support for files up to two gigabyte in size by default.
444 Support for larger file sizes has to be specifically enabled.
446 To make a difficult situation even more complex, such systems provide
447 two different types of largefile support. You can either get all
448 relevant functions replaced with alternatives that are largefile
449 capable, or you can get new functions and data types for largefile
450 support added. Those new functions have the same name as their
451 smallfile counterparts, but with a suffix of 64.
453 An example: The data type @code{off_t} is 32 bit wide on GNU/Linux PC
454 systems. To address offsets in large files, you can either enable
455 largefile support add-on. Then a new data type @code{off64_t} is
456 provided, which is 64 bit wide. Or you can replace the existing
457 @code{off_t} data type with its 64 bit wide counterpart. All
458 occurences of @code{off_t} are then automagically replaced.
460 As if matters were not complex enough, there are also two different
461 types of file descriptors in such systems. This is important because
462 if file descriptors are exchanged between programs that use a
463 different maximum file size, certain errors must be produced on some
464 file descriptors to prevent subtle overflow bugs from occuring.
466 As you can see, supporting two different maximum file sizes at the
467 same time is not at all an easy task. However, the maximum file size
468 does matter for @acronym{GPGME}, because some data types it uses in
469 its interfaces are affected by that. For example, the @code{off_t}
470 data type is used in the @code{gpgme_data_seek} function, to match its
471 @acronym{POSIX} counterpart. This affects the call-frame of the
472 function, and thus the ABI of the library. Furthermore, file
473 descriptors can be exchanged between GPGME and the application.
475 For you as the user of the library, this means that your program must
476 be compiled in the same file size mode as the library. Luckily, there
477 is absolutely no valid reason for new programs to not enable largefile
478 support by default and just use that. The compatibility modes (small
479 file sizes or dual mode) can be considered an historic artefact, only
480 useful to allow for a transitional period.
482 @acronym{GPGME} is compiled using largefile support by default. This
483 means that your application must do the same, at least as far as it is
484 relevant for using the @file{gpgme.h} header file. All types in this
485 header files refer to their largefile counterparts, if they are
486 different from any default types on the system.
488 You can enable largefile support, if it is different from the default
489 on the system the application is compiled on, by using the Autoconf
490 macro @code{AC_SYS_LARGEFILE}. If you do this, then you don't need to
491 worry about anything else: It will just work. In this case you might
492 also want to use @code{AC_FUNC_FSEEKO} to take advantage of some new
493 interfaces, and @code{AC_TYPE_OFF_T} (just in case).
495 If you do not use Autoconf, you can define the preprocessor symbol
496 @code{_FILE_OFFSET_BITS} to 64 @emph{before} including any header
497 files, for example by specifying the option
498 @code{-D_FILE_OFFSET_BITS=64} on the compiler command line. You will
499 also want to define the preprocessor symbol @code{LARGEFILE_SOURCE} to
500 1 in this case, to take advantage of some new interfaces.
502 If you do not want to do either of the above, you probably know enough
503 about the issue to invent your own solution. Just keep in mind that
504 the @acronym{GPGME} header file expects that largefile support is
505 enabled, if it is available. In particular, we do not support dual
506 mode (@code{_LARGEFILE64_SOURCE}).
510 @section Using Automake
514 It is much easier if you use GNU Automake instead of writing your own
515 Makefiles. If you do that you do not have to worry about finding and
516 invoking the @command{gpgme-config} script at all. @acronym{GPGME}
517 provides an extension to Automake that does all the work for you.
519 @c A simple macro for optional variables.
521 @r{[}@var{\varname\}@r{]}
523 @defmac AM_PATH_GPGME (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
524 @defmacx AM_PATH_GPGME_PTH (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
525 @defmacx AM_PATH_GPGME_PTHREAD (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
526 Check whether @acronym{GPGME} (at least version @var{minimum-version},
527 if given) exists on the host system. If it is found, execute
528 @var{action-if-found}, otherwise do @var{action-if-not-found}, if
531 Additionally, the function defines @code{GPGME_CFLAGS} to the flags
532 needed for compilation of the program to find the @file{gpgme.h}
533 header file, and @code{GPGME_LIBS} to the linker flags needed to link
534 the program to the @acronym{GPGME} library.
536 @code{AM_PATH_GPGME_PTH} checks for the version of @acronym{GPGME}
537 that can be used with GNU Pth, and defines @code{GPGME_PTH_CFLAGS} and
538 @code{GPGME_PTH_LIBS}.
540 @code{AM_PATH_GPGME_PTHREAD} checks for the version of @acronym{GPGME}
541 that can be used with the native pthread implementation, and defines
542 @code{GPGME_PTHREAD_CFLAGS} and @code{GPGME_PTHREAD_LIBS}.
545 You can use the defined Autoconf variables like this in your
549 AM_CPPFLAGS = $(GPGME_CFLAGS)
550 LDADD = $(GPGME_LIBS)
555 @section Using Libtool
558 The easiest way is to just use GNU Libtool. If you use libtool, and
559 link to @code{libgpgme.la}, @code{libgpgme-pth.la} or
560 @code{libgpgme-pthread.la} respectively, everything will be done
561 automatically by Libtool.
564 @node Library Version Check
565 @section Library Version Check
566 @cindex version check, of the library
568 @deftypefun {const char *} gpgme_check_version (@w{const char *@var{required_version}})
569 The function @code{gpgme_check_version} has three purposes. It can be
570 used to retrieve the version number of the library. In addition it
571 can verify that the version number is higher than a certain required
572 version number. In either case, the function initializes some
573 sub-systems, and for this reason alone it must be invoked early in
574 your program, before you make use of the other functions in
577 If @var{required_version} is @code{NULL}, the function returns a
578 pointer to a statically allocated string containing the version number
581 If @var{required_version} is not @code{NULL}, it should point to a
582 string containing a version number, and the function checks that the
583 version of the library is at least as high as the version number
584 provided. In this case, the function returns a pointer to a
585 statically allocated string containing the version number of the
586 library. If @var{REQUIRED_VERSION} is not a valid version number, or
587 if the version requirement is not met, the function returns
590 If you use a version of a library that is backwards compatible with
591 older releases, but contains additional interfaces which your program
592 uses, this function provides a run-time check if the necessary
593 features are provided by the installed version of the library.
597 After initializing @acronym{GPGME}, you should set the locale
598 information to the locale required for your output terminal. This
599 locale information is needed for example for the curses and Gtk
600 pinentry. Here is an example of a complete initialization:
609 /* Initialize the locale environment. */
610 setlocale (LC_ALL, "");
611 gpgme_check_version (NULL);
612 gpgme_set_locale (NULL, LC_CTYPE, setlocale (LC_CTYPE, NULL));
614 gpgme_set_locale (NULL, LC_MESSAGES, setlocale (LC_MESSAGES, NULL));
619 Note that you are highly recommended to initialize the locale settings
620 like this. @acronym{GPGME} can not do this for you because it would
621 not be thread safe. The conditional on LC_MESSAGES is only necessary
622 for portability to W32 systems.
625 @node Signal Handling
626 @section Signal Handling
628 @cindex signal handling
630 The @acronym{GPGME} library communicates with child processes (the
631 crypto engines). If a child process dies unexpectedly, for example
632 due to a bug, or system problem, a @code{SIGPIPE} signal will be
633 delivered to the application. The default action is to abort the
634 program. To protect against this, @code{gpgme_check_version} sets the
635 @code{SIGPIPE} signal action to @code{SIG_IGN}, which means that the
636 signal will be ignored.
638 @acronym{GPGME} will only do that if the signal action for
639 @code{SIGPIPE} is @code{SIG_DEF} at the time
640 @code{gpgme_check_version} is called. If it is something different,
641 @code{GPGME} will take no action.
643 This means that if your application does not install any signal
644 handler for @code{SIGPIPE}, you don't need to take any precautions.
645 If you do install a signal handler for @code{SIGPIPE}, you must be
646 prepared to handle any @code{SIGPIPE} events that occur due to
647 @acronym{GPGME} writing to a defunct pipe. Furthermore, if your
648 application is multi-threaded, and you install a signal action for
649 @code{SIGPIPE}, you must make sure you do this either before
650 @code{gpgme_check_version} is called or afterwards.
653 @node Multi Threading
654 @section Multi Threading
655 @cindex thread-safeness
656 @cindex multi-threading
658 The @acronym{GPGME} library is not entirely thread-safe, but it can
659 still be used in a multi-threaded environment if some care is taken.
660 If the following requirements are met, there should be no race
661 conditions to worry about:
665 @acronym{GPGME} supports the thread libraries pthread and GNU Pth.
666 The support for this has to be enabled at compile time.
667 @acronym{GPGME} will automatically detect the location in which the
668 thread libraries are installed and activate the support for them at
671 Support for other thread libraries is very easy to add. Please
672 contact us if you have the need.
675 If you want to use @acronym{GPGME} with threads, you must link to the
676 right version of the library. The name of the right library is
677 @code{libgpgme-} followed by the name of the thread package you use.
678 For example, if you use GNU Pth, the right name is
679 @code{libgpgme-pth}. Use the Automake macros or
680 @command{gpgme-config} program for simplicity.
684 The function @code{gpgme_check_version} must be called before any
685 other function in the library, because it initializes the thread
686 support subsystem in @acronym{GPGME}. To achieve this in
687 multi-threaded programs, you must synchronize the memory with respect
688 to other threads that also want to use @acronym{GPGME}. For this, it
689 is sufficient to call @code{gpgme_check_version} before creating the
690 other threads using @acronym{GPGME}@footnote{At least this is true for
691 POSIX threads, as @code{pthread_create} is a function that
692 synchronizes memory with respects to other threads. There are many
693 functions which have this property, a complete list can be found in
694 POSIX, IEEE Std 1003.1-2003, Base Definitions, Issue 6, in the
695 definition of the term ``Memory Synchronization''. For other thread
696 packages other, more relaxed or more strict rules may apply.}.
699 Any @code{gpgme_data_t} and @code{gpgme_ctx_t} object must only be
700 accessed by one thread at a time. If multiple threads want to deal
701 with the same object, the caller has to make sure that operations on
702 that object are fully synchronized.
705 Only one thread at any time is allowed to call @code{gpgme_wait}. If
706 multiple threads call this function, the caller must make sure that
707 all invocations are fully synchronized. It is safe to start
708 asynchronous operations while a thread is running in gpgme_wait.
711 The function @code{gpgme_strerror} is not thread safe. You have to
712 use @code{gpgme_strerror_r} instead.
716 @node Protocols and Engines
717 @chapter Protocols and Engines
720 @cindex crypto engine
722 @cindex crypto backend
724 @acronym{GPGME} supports several cryptographic protocols, however, it
725 does not implement them. Rather it uses backends (also called
726 engines) which implement the protocol. @acronym{GPGME} uses
727 inter-process communication to pass data back and forth between the
728 application and the backend, but the details of the communication
729 protocol and invocation of the backend is completely hidden by the
730 interface. All complexity is handled by @acronym{GPGME}. Where an
731 exchange of information between the application and the backend is
732 necessary, @acronym{GPGME} provides the necessary callback function
733 hooks and further interfaces.
735 @deftp {Data type} {enum gpgme_protocol_t}
736 @tindex gpgme_protocol_t
737 The @code{gpgme_protocol_t} type specifies the set of possible protocol
738 values that are supported by @acronym{GPGME}. The following protocols
742 @item GPGME_PROTOCOL_OpenPGP
743 This specifies the OpenPGP protocol.
745 @item GPGME_PROTOCOL_CMS
746 This specifies the Cryptographic Message Syntax.
751 @deftypefun {const char *} gpgme_get_protocol_name (@w{gpgme_protocol_t @var{protocol}})
752 The function @code{gpgme_get_protocol_name} returns a statically
753 allocated string describing the protocol @var{protocol}, or
754 @code{NULL} if the protocol number is not valid.
758 * Engine Version Check:: Verifying the engine version.
759 * Engine Information:: Obtaining more information about the engines.
760 * Engine Configuration:: Changing the engine configuration.
761 * OpenPGP:: Support for the OpenPGP protocol.
762 * Cryptographic Message Syntax:: Support for the CMS.
766 @node Engine Version Check
767 @section Engine Version Check
768 @cindex version check, of the engines
770 @deftypefun gpgme_error_t gpgme_engine_check_version (@w{gpgme_protocol_t @var{protocol}})
771 The function @code{gpgme_engine_check_version} verifies that the
772 engine implementing the protocol @var{PROTOCOL} is installed in the
773 expected path and meets the version requirement of @acronym{GPGME}.
775 This function returns the error code @code{GPG_ERR_NO_ERROR} if the
776 engine is available and @code{GPG_ERR_INV_ENGINE} if it is not.
780 @node Engine Information
781 @section Engine Information
782 @cindex engine, information about
784 @deftp {Data type} {gpgme_engine_info_t}
785 @tindex gpgme_protocol_t
786 The @code{gpgme_engine_info_t} type specifies a pointer to a structure
787 describing a crypto engine. The structure contains the following
791 @item gpgme_engine_info_t next
792 This is a pointer to the next engine info structure in the linked
793 list, or @code{NULL} if this is the last element.
795 @item gpgme_protocol_t protocol
796 This is the protocol for which the crypto engine is used. You can
797 convert this to a string with @code{gpgme_get_protocol_name} for
800 @item const char *file_name
801 This is a string holding the file name of the executable of the crypto
802 engine. Currently, it is never @code{NULL}, but using @code{NULL} is
803 reserved for future use, so always check before you use it.
805 @item const char *home_dir
806 This is a string holding the directory name of the crypto engine's
807 configuration directory. If it is @code{NULL}, then the default
810 @item const char *version
811 This is a string containing the version number of the crypto engine.
812 It might be @code{NULL} if the version number can not be determined,
813 for example because the executable doesn't exist or is invalid.
815 @item const char *req_version
816 This is a string containing the minimum required version number of the
817 crypto engine for @acronym{GPGME} to work correctly. This is the
818 version number that @code{gpgme_engine_check_version} verifies
819 against. Currently, it is never @code{NULL}, but using @code{NULL} is
820 reserved for future use, so always check before you use it.
824 @deftypefun gpgme_error_t gpgme_get_engine_info (@w{gpgme_engine_info_t *@var{info}})
825 The function @code{gpgme_get_engine_info} returns a linked list of
826 engine info structures in @var{info}. Each info structure describes
827 the defaults of one configured backend.
829 The memory for the info structures is allocated the first time this
830 function is invoked, and must not be freed by the caller.
832 This function returns the error code @code{GPG_ERR_NO_ERROR} if
833 successful, and a system error if the memory could not be allocated.
836 Here is an example how you can provide more diagnostics if you receive
837 an error message which indicates that the crypto engine is invalid.
845 if (gpgme_err_code (err) == GPG_ERR_INV_ENGINE)
847 gpgme_engine_info_t info;
848 err = gpgme_get_engine_info (&info);
851 while (info && info->protocol != gpgme_get_protocol (ctx))
854 fprintf (stderr, "GPGME compiled without support for protocol %s",
855 gpgme_get_protocol_name (info->protocol));
856 else if (info->path && !info->version)
857 fprintf (stderr, "Engine %s not installed properly",
859 else if (info->path && info->version && info->req_version)
860 fprintf (stderr, "Engine %s version %s installed, "
861 "but at least version %s required", info->path,
862 info->version, info->req_version);
864 fprintf (stderr, "Unknown problem with engine for protocol %s",
865 gpgme_get_protocol_name (info->protocol));
871 @node Engine Configuration
872 @section Engine Configuration
873 @cindex engine, configuration of
874 @cindex configuration of crypto backend
876 You can change the configuration of a backend engine, and thus change
877 the executable program and configuration directory to be used. You
878 can make these changes the default or set them for some contexts
881 @deftypefun gpgme_error_t gpgme_set_engine_info (@w{gpgme_protocol_t @var{proto}}, @w{const char *@var{file_name}}, @w{const char *@var{home_dir}})
882 The function @code{gpgme_set_engine_info} changes the default
883 configuration of the crypto engine implementing the protocol
886 @var{file_name} is the file name of the executable program
887 implementing this protocol, and @var{home_dir} is the directory name
888 of the configuration directory for this crypto engine. If
889 @var{home_dir} is @code{NULL}, the engine's default will be used.
891 The new defaults are not applied to already created GPGME contexts.
893 This function returns the error code @code{GPG_ERR_NO_ERROR} if
894 successful, or an eror code on failure.
897 The functions @code{gpgme_ctx_get_engine_info} and
898 @code{gpgme_ctx_set_engine_info} can be used to change the engine
899 configuration per context. @xref{Crypto Engine}.
906 @cindex protocol, GnuPG
907 @cindex engine, GnuPG
909 OpenPGP is implemented by GnuPG, the @acronym{GNU} Privacy Guard.
910 This is the first protocol that was supported by @acronym{GPGME}.
912 The OpenPGP protocol is specified by @code{GPGME_PROTOCOL_OpenPGP}.
915 @node Cryptographic Message Syntax
916 @section Cryptographic Message Syntax
918 @cindex cryptographic message syntax
920 @cindex protocol, CMS
921 @cindex engine, GpgSM
923 @cindex protocol, S/MIME
925 @acronym{CMS} is implemented by GpgSM, the S/MIME implementation for
928 The @acronym{CMS} protocol is specified by @code{GPGME_PROTOCOL_CMS}.
935 The crypto backends support a variety of algorithms used in public key
936 cryptography. The following sections list the identifiers used to
937 denote such an algorithm.
940 * Public Key Algorithms:: A list of all public key algorithms.
941 * Hash Algorithms:: A list of all hash algorithms.
945 @node Public Key Algorithms
946 @section Public Key Algorithms
947 @cindex algorithms, public key
948 @cindex public key algorithms
950 Public key algorithms are used for encryption, decryption, signing and
951 verification of signatures.
953 @deftp {Data type} {enum gpgme_pubkey_algo_t}
954 @tindex gpgme_pubkey_algo_t
955 The @code{gpgme_pubkey_algo_t} type specifies the set of all public key
956 algorithms that are supported by @acronym{GPGME}. Possible values
961 This value indicates the RSA (Rivest, Shamir, Adleman) algorithm.
964 Deprecated. This value indicates the RSA (Rivest, Shamir, Adleman)
965 algorithm for encryption and decryption only.
968 Deprecated. This value indicates the RSA (Rivest, Shamir, Adleman)
969 algorithm for signing and verification only.
972 This value indicates DSA, the Digital Signature Algorithm.
975 This value indicates ElGamal.
978 This value also indicates ElGamal and is used specifically in GnuPG.
982 @deftypefun {const char *} gpgme_pubkey_algo_name (@w{gpgme_pubkey_algo_t @var{algo}})
983 The function @code{gpgme_pubkey_algo_name} returns a pointer to a
984 statically allocated string containing a description of the public key
985 algorithm @var{algo}. This string can be used to output the name of
986 the public key algorithm to the user.
988 If @var{algo} is not a valid public key algorithm, @code{NULL} is
993 @node Hash Algorithms
994 @section Hash Algorithms
995 @cindex algorithms, hash
996 @cindex algorithms, message digest
997 @cindex hash algorithms
998 @cindex message digest algorithms
1000 Hash (message digest) algorithms are used to compress a long message
1001 to make it suitable for public key cryptography.
1003 @deftp {Data type} {enum gpgme_hash_algo_t}
1004 @tindex gpgme_hash_algo_t
1005 The @code{gpgme_hash_algo_t} type specifies the set of all hash algorithms
1006 that are supported by @acronym{GPGME}. Possible values are:
1011 @item GPGME_MD_RMD160
1013 @item GPGME_MD_TIGER
1014 @item GPGME_MD_HAVAL
1015 @item GPGME_MD_SHA256
1016 @item GPGME_MD_SHA384
1017 @item GPGME_MD_SHA512
1019 @item GPGME_MD_CRC32
1020 @item GPGME_MD_CRC32_RFC1510
1021 @item GPGME_MD_CRC24_RFC2440
1025 @deftypefun {const char *} gpgme_hash_algo_name (@w{gpgme_hash_algo_t @var{algo}})
1026 The function @code{gpgme_hash_algo_name} returns a pointer to a
1027 statically allocated string containing a description of the hash
1028 algorithm @var{algo}. This string can be used to output the name of
1029 the hash algorithm to the user.
1031 If @var{algo} is not a valid hash algorithm, @code{NULL} is returned.
1035 @node Error Handling
1036 @chapter Error Handling
1037 @cindex error handling
1039 Many functions in @acronym{GPGME} can return an error if they fail.
1040 For this reason, the application should always catch the error
1041 condition and take appropriate measures, for example by releasing the
1042 resources and passing the error up to the caller, or by displaying a
1043 descriptive message to the user and cancelling the operation.
1045 Some error values do not indicate a system error or an error in the
1046 operation, but the result of an operation that failed properly. For
1047 example, if you try to decrypt a tempered message, the decryption will
1048 fail. Another error value actually means that the end of a data
1049 buffer or list has been reached. The following descriptions explain
1050 for many error codes what they mean usually. Some error values have
1051 specific meanings if returned by a certain functions. Such cases are
1052 described in the documentation of those functions.
1054 @acronym{GPGME} uses the @code{libgpg-error} library. This allows to
1055 share the error codes with other components of the GnuPG system, and
1056 thus pass error values transparently from the crypto engine, or some
1057 helper application of the crypto engine, to the user. This way no
1058 information is lost. As a consequence, @acronym{GPGME} does not use
1059 its own identifiers for error codes, but uses those provided by
1060 @code{libgpg-error}. They usually start with @code{GPG_ERR_}.
1062 However, @acronym{GPGME} does provide aliases for the functions
1063 defined in libgpg-error, which might be preferred for name space
1067 * Error Values:: The error value and what it means.
1068 * Error Sources:: A list of important error sources.
1069 * Error Codes:: A list of important error codes.
1070 * Error Strings:: How to get a descriptive string from a value.
1075 @section Error Values
1076 @cindex error values
1078 @cindex error sources
1080 @deftp {Data type} {gpgme_err_code_t}
1081 The @code{gpgme_err_code_t} type is an alias for the @code{libgpg-error}
1082 type @code{gpg_err_code_t}. The error code indicates the type of an
1083 error, or the reason why an operation failed.
1085 A list of important error codes can be found in the next section.
1088 @deftp {Data type} {gpgme_err_source_t}
1089 The @code{gpgme_err_source_t} type is an alias for the
1090 @code{libgpg-error} type @code{gpg_err_source_t}. The error source
1091 has not a precisely defined meaning. Sometimes it is the place where
1092 the error happened, sometimes it is the place where an error was
1093 encoded into an error value. Usually the error source will give an
1094 indication to where to look for the problem. This is not always true,
1095 but it is attempted to achieve this goal.
1097 A list of important error sources can be found in the next section.
1100 @deftp {Data type} {gpgme_error_t}
1101 The @code{gpgme_error_t} type is an alias for the @code{libgpg-error}
1102 type @code{gpg_error_t}. An error value like this has always two
1103 components, an error code and an error source. Both together form the
1106 Thus, the error value can not be directly compared against an error
1107 code, but the accessor functions described below must be used.
1108 However, it is guaranteed that only 0 is used to indicate success
1109 (@code{GPG_ERR_NO_ERROR}), and that in this case all other parts of
1110 the error value are set to 0, too.
1112 Note that in @acronym{GPGME}, the error source is used purely for
1113 diagnostical purposes. Only the error code should be checked to test
1114 for a certain outcome of a function. The manual only documents the
1115 error code part of an error value. The error source is left
1116 unspecified and might be anything.
1119 @deftypefun {static inline gpgme_err_code_t} gpgme_err_code (@w{gpgme_error_t @var{err}})
1120 The static inline function @code{gpgme_err_code} returns the
1121 @code{gpgme_err_code_t} component of the error value @var{err}. This
1122 function must be used to extract the error code from an error value in
1123 order to compare it with the @code{GPG_ERR_*} error code macros.
1126 @deftypefun {static inline gpgme_err_source_t} gpgme_err_source (@w{gpgme_error_t @var{err}})
1127 The static inline function @code{gpgme_err_source} returns the
1128 @code{gpgme_err_source_t} component of the error value @var{err}. This
1129 function must be used to extract the error source from an error value in
1130 order to compare it with the @code{GPG_ERR_SOURCE_*} error source macros.
1133 @deftypefun {static inline gpgme_error_t} gpgme_err_make (@w{gpgme_err_source_t @var{source}}, @w{gpgme_err_code_t @var{code}})
1134 The static inline function @code{gpgme_err_make} returns the error
1135 value consisting of the error source @var{source} and the error code
1138 This function can be used in callback functions to construct an error
1139 value to return it to the library.
1142 @deftypefun {static inline gpgme_error_t} gpgme_error (@w{gpgme_err_code_t @var{code}})
1143 The static inline function @code{gpgme_error} returns the error value
1144 consisting of the default error source and the error code @var{code}.
1146 For @acronym{GPGME} applications, the default error source is
1147 @code{GPG_ERR_SOURCE_USER_1}. You can define
1148 @code{GPGME_ERR_SOURCE_DEFAULT} before including @file{gpgme.h} to
1149 change this default.
1151 This function can be used in callback functions to construct an error
1152 value to return it to the library.
1155 The @code{libgpg-error} library provides error codes for all system
1156 error numbers it knows about. If @var{err} is an unknown error
1157 number, the error code @code{GPG_ERR_UNKNOWN_ERRNO} is used. The
1158 following functions can be used to construct error values from system
1161 @deftypefun {gpgme_error_t} gpgme_err_make_from_errno (@w{gpgme_err_source_t @var{source}}, @w{int @var{err}})
1162 The function @code{gpgme_err_make_from_errno} is like
1163 @code{gpgme_err_make}, but it takes a system error like @code{errno}
1164 instead of a @code{gpgme_err_code_t} error code.
1167 @deftypefun {gpgme_error_t} gpgme_error_from_errno (@w{int @var{err}})
1168 The function @code{gpgme_error_from_errno} is like @code{gpgme_error},
1169 but it takes a system error like @code{errno} instead of a
1170 @code{gpgme_err_code_t} error code.
1173 Sometimes you might want to map system error numbers to error codes
1174 directly, or map an error code representing a system error back to the
1175 system error number. The following functions can be used to do that.
1177 @deftypefun {gpgme_err_code_t} gpgme_err_code_from_errno (@w{int @var{err}})
1178 The function @code{gpgme_err_code_from_errno} returns the error code
1179 for the system error @var{err}. If @var{err} is not a known system
1180 error, the function returns @code{GPG_ERR_UNKNOWN_ERRNO}.
1183 @deftypefun {int} gpgme_err_code_to_errno (@w{gpgme_err_code_t @var{err}})
1184 The function @code{gpgme_err_code_to_errno} returns the system error
1185 for the error code @var{err}. If @var{err} is not an error code
1186 representing a system error, or if this system error is not defined on
1187 this system, the function returns @code{0}.
1192 @section Error Sources
1193 @cindex error codes, list of
1195 The library @code{libgpg-error} defines an error source for every
1196 component of the GnuPG system. The error source part of an error
1197 value is not well defined. As such it is mainly useful to improve the
1198 diagnostic error message for the user.
1200 If the error code part of an error value is @code{0}, the whole error
1201 value will be @code{0}. In this case the error source part is of
1202 course @code{GPG_ERR_SOURCE_UNKNOWN}.
1204 The list of error sources that might occur in applications using
1208 @item GPG_ERR_SOURCE_UNKNOWN
1209 The error source is not known. The value of this error source is
1212 @item GPG_ERR_SOURCE_GPGME
1213 The error source is @acronym{GPGME} itself. This is the default for
1214 errors that occur in the @acronym{GPGME} library.
1216 @item GPG_ERR_SOURCE_GPG
1217 The error source is GnuPG, which is the crypto engine used for the
1220 @item GPG_ERR_SOURCE_GPGSM
1221 The error source is GPGSM, which is the crypto engine used for the
1224 @item GPG_ERR_SOURCE_GCRYPT
1225 The error source is @code{libgcrypt}, which is used by crypto engines
1226 to perform cryptographic operations.
1228 @item GPG_ERR_SOURCE_GPGAGENT
1229 The error source is @command{gpg-agent}, which is used by crypto
1230 engines to perform operations with the secret key.
1232 @item GPG_ERR_SOURCE_PINENTRY
1233 The error source is @command{pinentry}, which is used by
1234 @command{gpg-agent} to query the passphrase to unlock a secret key.
1236 @item GPG_ERR_SOURCE_SCD
1237 The error source is the SmartCard Daemon, which is used by
1238 @command{gpg-agent} to delegate operations with the secret key to a
1241 @item GPG_ERR_SOURCE_KEYBOX
1242 The error source is @code{libkbx}, a library used by the crypto
1243 engines to manage local keyrings.
1245 @item GPG_ERR_SOURCE_USER_1
1246 @item GPG_ERR_SOURCE_USER_2
1247 @item GPG_ERR_SOURCE_USER_3
1248 @item GPG_ERR_SOURCE_USER_4
1249 These error sources are not used by any GnuPG component and can be
1250 used by other software. For example, applications using
1251 @acronym{GPGME} can use them to mark error values coming from callback
1252 handlers. Thus @code{GPG_ERR_SOURCE_USER_1} is the default for errors
1253 created with @code{gpgme_error} and @code{gpgme_error_from_errno},
1254 unless you define @code{GPGME_ERR_SOURCE_DEFAULT} before including
1260 @section Error Codes
1261 @cindex error codes, list of
1263 The library @code{libgpg-error} defines many error values. Most of
1264 them are not used by @code{GPGME} directly, but might be returned by
1265 @acronym{GPGME} because it received them from the crypto engine. The
1266 below list only includes such error codes that have a specific meaning
1267 in @code{GPGME}, or which are so common that you should know about
1272 This value indicates the end of a list, buffer or file.
1274 @item GPG_ERR_NO_ERROR
1275 This value indicates success. The value of this error code is
1276 @code{0}. Also, it is guaranteed that an error value made from the
1277 error code @code{0} will be @code{0} itself (as a whole). This means
1278 that the error source information is lost for this error code,
1279 however, as this error code indicates that no error occured, this is
1280 generally not a problem.
1282 @item GPG_ERR_GENERAL
1283 This value means that something went wrong, but either there is not
1284 enough information about the problem to return a more useful error
1285 value, or there is no separate error value for this type of problem.
1287 @item GPG_ERR_ENOMEM
1288 This value means that an out-of-memory condition occurred.
1291 System errors are mapped to GPG_ERR_FOO where FOO is the symbol for
1294 @item GPG_ERR_INV_VALUE
1295 This value means that some user provided data was out of range. This
1296 can also refer to objects. For example, if an empty
1297 @code{gpgme_data_t} object was expected, but one containing data was
1298 provided, this error value is returned.
1300 @item GPG_ERR_UNUSABLE_PUBKEY
1301 This value means that some recipients for a message were invalid.
1303 @item GPG_ERR_UNUSABLE_SECKEY
1304 This value means that some signers were invalid.
1306 @item GPG_ERR_NO_DATA
1307 This value means that a @code{gpgme_data_t} object which was expected
1308 to have content was found empty.
1310 @item GPG_ERR_CONFLICT
1311 This value means that a conflict of some sort occurred.
1313 @item GPG_ERR_NOT_IMPLEMENTED
1314 This value indicates that the specific function (or operation) is not
1315 implemented. This error should never happen. It can only occur if
1316 you use certain values or configuration options which do not work,
1317 but for which we think that they should work at some later time.
1319 @item GPG_ERR_DECRYPT_FAILED
1320 This value indicates that a decryption operation was unsuccessful.
1322 @item GPG_ERR_BAD_PASSPHRASE
1323 This value means that the user did not provide a correct passphrase
1326 @item GPG_ERR_CANCELED
1327 This value means that the operation was canceled.
1329 @item GPG_ERR_INV_ENGINE
1330 This value means that the engine that implements the desired protocol
1331 is currently not available. This can either be because the sources
1332 were configured to exclude support for this engine, or because the
1333 engine is not installed properly.
1335 @item GPG_ERR_AMBIGUOUS_NAME
1336 This value indicates that a user ID or other specifier did not specify
1339 @item GPG_ERR_WRONG_KEY_USAGE
1340 This value indicates that a key is not used appropriately.
1342 @item GPG_ERR_CERT_REVOKED
1343 This value indicates that a key signature was revoced.
1345 @item GPG_ERR_CERT_EXPIRED
1346 This value indicates that a key signature expired.
1348 @item GPG_ERR_NO_CRL_KNOWN
1349 This value indicates that no certificate revocation list is known for
1352 @item GPG_ERR_NO_POLICY_MATCH
1353 This value indicates that a policy issue occured.
1355 @item GPG_ERR_NO_SECKEY
1356 This value indicates that no secret key for the user ID is available.
1358 @item GPG_ERR_MISSING_CERT
1359 This value indicates that a key could not be imported because the
1360 issuer certificate is missing.
1362 @item GPG_ERR_BAD_CERT_CHAIN
1363 This value indicates that a key could not be imported because its
1364 certificate chain is not good, for example it could be too long.
1366 @item GPG_ERR_UNSUPPORTED_ALGORITHM
1367 This value means a verification failed because the cryptographic
1368 algorithm is not supported by the crypto backend.
1370 @item GPG_ERR_BAD_SIGNATURE
1371 This value means a verification failed because the signature is bad.
1373 @item GPG_ERR_NO_PUBKEY
1374 This value means a verification failed because the public key is not
1377 @item GPG_ERR_USER_1
1378 @item GPG_ERR_USER_2
1380 @item GPG_ERR_USER_16
1381 These error codes are not used by any GnuPG component and can be
1382 freely used by other software. Applications using @acronym{GPGME}
1383 might use them to mark specific errors returned by callback handlers
1384 if no suitable error codes (including the system errors) for
1385 these errors exist already.
1390 @section Error Strings
1391 @cindex error values, printing of
1392 @cindex error codes, printing of
1393 @cindex error sources, printing of
1394 @cindex error strings
1396 @deftypefun {const char *} gpgme_strerror (@w{gpgme_error_t @var{err}})
1397 The function @code{gpgme_strerror} returns a pointer to a statically
1398 allocated string containing a description of the error code contained
1399 in the error value @var{err}. This string can be used to output a
1400 diagnostic message to the user.
1402 This function is not thread safe. Use @code{gpgme_strerror_r} in
1403 multi-threaded programs.
1407 @deftypefun {int} gpgme_strerror_r (@w{gpgme_error_t @var{err}}, @w{char *@var{buf}}, @w{size_t @var{buflen}})
1408 The function @code{gpgme_strerror_r} returns the error string for
1409 @var{err} in the user-supplied buffer @var{buf} of size @var{buflen}.
1410 This function is, in contrast to @code{gpgme_strerror}, thread-safe if
1411 a thread-safe @code{strerror_r} function is provided by the system.
1412 If the function succeeds, 0 is returned and @var{buf} contains the
1413 string describing the error. If the buffer was not large enough,
1414 ERANGE is returned and @var{buf} contains as much of the beginning of
1415 the error string as fits into the buffer.
1419 @deftypefun {const char *} gpgme_strsource (@w{gpgme_error_t @var{err}})
1420 The function @code{gpgme_strerror} returns a pointer to a statically
1421 allocated string containing a description of the error source
1422 contained in the error value @var{err}. This string can be used to
1423 output a diagnostic message to the user.
1426 The following example illustrates the use of @code{gpgme_strerror}:
1430 gpgme_error_t err = gpgme_new (&ctx);
1433 fprintf (stderr, "%s: creating GpgME context failed: %s: %s\n",
1434 argv[0], gpgme_strsource (err), gpgme_strerror (err));
1440 @node Exchanging Data
1441 @chapter Exchanging Data
1442 @cindex data, exchanging
1444 A lot of data has to be exchanged between the user and the crypto
1445 engine, like plaintext messages, ciphertext, signatures and
1446 information about the keys. The technical details about exchanging
1447 the data information are completely abstracted by @acronym{GPGME}.
1448 The user provides and receives the data via @code{gpgme_data_t} objects,
1449 regardless of the communication protocol between @acronym{GPGME} and
1450 the crypto engine in use.
1452 @deftp {Data type} {gpgme_data_t}
1453 The @code{gpgme_data_t} type is a handle for a container for generic
1454 data, which is used by @acronym{GPGME} to exchange data with the user.
1458 * Creating Data Buffers:: Creating new data buffers.
1459 * Destroying Data Buffers:: Releasing data buffers.
1460 * Manipulating Data Buffers:: Operations on data buffers.
1464 @node Creating Data Buffers
1465 @section Creating Data Buffers
1466 @cindex data buffer, creation
1468 Data objects can be based on memory, files, or callback functions
1469 provided by the user. Not all operations are supported by all
1474 * Memory Based Data Buffers:: Creating memory based data buffers.
1475 * File Based Data Buffers:: Creating file based data buffers.
1476 * Callback Based Data Buffers:: Creating callback based data buffers.
1480 @node Memory Based Data Buffers
1481 @subsection Memory Based Data Buffers
1483 Memory based data objects store all data in allocated memory. This is
1484 convenient, but only practical for an amount of data that is a
1485 fraction of the available physical memory. The data has to be copied
1486 from its source and to its destination, which can often be avoided by
1487 using one of the other data object
1489 @deftypefun gpgme_error_t gpgme_data_new (@w{gpgme_data_t *@var{dh}})
1490 The function @code{gpgme_data_new} creates a new @code{gpgme_data_t}
1491 object and returns a handle for it in @var{dh}. The data object is
1492 memory based and initially empty.
1494 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1495 data object was successfully created, @code{GPG_ERR_INV_VALUE} if
1496 @var{dh} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if not
1497 enough memory is available.
1500 @deftypefun gpgme_error_t gpgme_data_new_from_mem (@w{gpgme_data_t *@var{dh}}, @w{const char *@var{buffer}}, @w{size_t @var{size}}, @w{int @var{copy}})
1501 The function @code{gpgme_data_new_from_mem} creates a new
1502 @code{gpgme_data_t} object and fills it with @var{size} bytes starting
1505 If @var{copy} is not zero, a private copy of the data is made. If
1506 @var{copy} is zero, the data is taken from the specified buffer as
1507 needed, and the user has to ensure that the buffer remains valid for
1508 the whole life span of the data object.
1510 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1511 data object was successfully created, @code{GPG_ERR_INV_VALUE} if
1512 @var{dh} or @var{buffer} is not a valid pointer, and
1513 @code{GPG_ERR_ENOMEM} if not enough memory is available.
1516 @deftypefun gpgme_error_t gpgme_data_new_from_file (@w{gpgme_data_t *@var{dh}}, @w{const char *@var{filename}}, @w{int @var{copy}})
1517 The function @code{gpgme_data_new_from_file} creates a new
1518 @code{gpgme_data_t} object and fills it with the content of the file
1521 If @var{copy} is not zero, the whole file is read in at initialization
1522 time and the file is not used anymore after that. This is the only
1523 mode supported currently. Later, a value of zero for @var{copy} might
1524 cause all reads to be delayed until the data is needed, but this is
1525 not yet implemented.
1527 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1528 data object was successfully created, @code{GPG_ERR_INV_VALUE} if
1529 @var{dh} or @var{filename} is not a valid pointer,
1530 @code{GPG_ERR_NOT_IMPLEMENTED} if @var{code} is zero, and
1531 @code{GPG_ERR_ENOMEM} if not enough memory is available.
1534 @deftypefun gpgme_error_t gpgme_data_new_from_filepart (@w{gpgme_data_t *@var{dh}}, @w{const char *@var{filename}}, @w{FILE *@var{fp}}, @w{off_t @var{offset}}, @w{size_t @var{length}})
1535 The function @code{gpgme_data_new_from_filepart} creates a new
1536 @code{gpgme_data_t} object and fills it with a part of the file specified
1537 by @var{filename} or @var{fp}.
1539 Exactly one of @var{filename} and @var{fp} must be non-zero, the other
1540 must be zero. The argument that is not zero specifies the file from
1541 which @var{length} bytes are read into the data object, starting from
1544 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1545 data object was successfully created, @code{GPG_ERR_INV_VALUE} if
1546 @var{dh} and exactly one of @var{filename} and @var{fp} is not a valid
1547 pointer, and @code{GPG_ERR_ENOMEM} if not enough memory is available.
1551 @node File Based Data Buffers
1552 @subsection File Based Data Buffers
1554 File based data objects operate directly on file descriptors or
1555 streams. Only a small amount of data is stored in core at any time,
1556 so the size of the data objects is not limited by @acronym{GPGME}.
1558 @deftypefun gpgme_error_t gpgme_data_new_from_fd (@w{gpgme_data_t *@var{dh}}, @w{int @var{fd}})
1559 The function @code{gpgme_data_new_from_fd} creates a new
1560 @code{gpgme_data_t} object and uses the file descriptor @var{fd} to read
1561 from (if used as an input data object) and write to (if used as an
1562 output data object).
1564 When using the data object as an input buffer, the function might read
1565 a bit more from the file descriptor than is actually needed by the
1566 crypto engine in the desired operation because of internal buffering.
1568 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1569 data object was successfully created, and @code{GPG_ERR_ENOMEM} if not
1570 enough memory is available.
1573 @deftypefun gpgme_error_t gpgme_data_new_from_stream (@w{gpgme_data_t *@var{dh}}, @w{FILE *@var{stream}})
1574 The function @code{gpgme_data_new_from_stream} creates a new
1575 @code{gpgme_data_t} object and uses the I/O stream @var{stream} to read
1576 from (if used as an input data object) and write to (if used as an
1577 output data object).
1579 When using the data object as an input buffer, the function might read
1580 a bit more from the stream than is actually needed by the crypto
1581 engine in the desired operation because of internal buffering.
1583 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1584 data object was successfully created, and @code{GPG_ERR_ENOMEM} if not
1585 enough memory is available.
1589 @node Callback Based Data Buffers
1590 @subsection Callback Based Data Buffers
1592 If neither memory nor file based data objects are a good fit for your
1593 application, you can implement the functions a data object provides
1594 yourself and create a data object from these callback functions.
1596 @deftp {Data type} {ssize_t (*gpgme_data_read_cb_t) (@w{void *@var{handle}}, @w{void @var{*buffer}}, @w{size_t @var{size}})}
1597 @tindex gpgme_data_read_cb_t
1598 The @code{gpgme_data_read_cb_t} type is the type of functions which
1599 @acronym{GPGME} calls if it wants to read data from a user-implemented
1600 data object. The function should read up to @var{size} bytes from the
1601 current read position into the space starting at @var{buffer}. The
1602 @var{handle} is provided by the user at data object creation time.
1604 The function should return the number of bytes read, 0 on EOF, and -1
1605 on error. If an error occurs, @var{errno} should be set to describe
1606 the type of the error.
1609 @deftp {Data type} {ssize_t (*gpgme_data_write_cb_t) (@w{void *@var{handle}}, @w{const void @var{*buffer}}, @w{size_t @var{size}})}
1610 @tindex gpgme_data_write_cb_t
1611 The @code{gpgme_data_write_cb_t} type is the type of functions which
1612 @acronym{GPGME} calls if it wants to write data to a user-implemented
1613 data object. The function should write up to @var{size} bytes to the
1614 current write position from the space starting at @var{buffer}. The
1615 @var{handle} is provided by the user at data object creation time.
1617 The function should return the number of bytes written, and -1 on
1618 error. If an error occurs, @var{errno} should be set to describe the
1622 @deftp {Data type} {off_t (*gpgme_data_seek_cb_t) (@w{void *@var{handle}}, @w{off_t @var{offset}}, @w{int @var{whence}})}
1623 @tindex gpgme_data_seek_cb_t
1624 The @code{gpgme_data_seek_cb_t} type is the type of functions which
1625 @acronym{GPGME} calls if it wants to change the current read/write
1626 position in a user-implemented data object, just like the @code{lseek}
1629 The function should return the new read/write position, and -1 on
1630 error. If an error occurs, @var{errno} should be set to describe the
1634 @deftp {Data type} {void (*gpgme_data_release_cb_t) (@w{void *@var{handle}})}
1635 @tindex gpgme_data_release_cb_t
1636 The @code{gpgme_data_release_cb_t} type is the type of functions which
1637 @acronym{GPGME} calls if it wants to destroy a user-implemented data
1638 object. The @var{handle} is provided by the user at data object
1642 @deftp {Data type} {struct gpgme_data_cbs}
1643 This structure is used to store the data callback interface functions
1644 described above. It has the following members:
1647 @item gpgme_data_read_cb_t read
1648 This is the function called by @acronym{GPGME} to read data from the
1649 data object. It is only required for input data object.
1651 @item gpgme_data_write_cb_t write
1652 This is the function called by @acronym{GPGME} to write data to the
1653 data object. It is only required for output data object.
1655 @item gpgme_data_seek_cb_t seek
1656 This is the function called by @acronym{GPGME} to change the current
1657 read/write pointer in the data object (if available). It is optional.
1659 @item gpgme_data_release_cb_t release
1660 This is the function called by @acronym{GPGME} to release a data
1661 object. It is optional.
1665 @deftypefun gpgme_error_t gpgme_data_new_from_cbs (@w{gpgme_data_t *@var{dh}}, @w{gpgme_data_cbs_t @var{cbs}}, @w{void *@var{handle}})
1666 The function @code{gpgme_data_new_from_cbs} creates a new
1667 @code{gpgme_data_t} object and uses the user-provided callback functions
1668 to operate on the data object.
1670 The handle @var{handle} is passed as first argument to the callback
1671 functions. This can be used to identify this data object.
1673 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1674 data object was successfully created, and @code{GPG_ERR_ENOMEM} if not
1675 enough memory is available.
1678 The following interface is deprecated and only provided for backward
1679 compatibility. Don't use it. It will be removed in a future version
1682 @deftypefun gpgme_error_t gpgme_data_new_with_read_cb (@w{gpgme_data_t *@var{dh}}, @w{int (*@var{readfunc})} (@w{void *@var{hook}}, @w{char *@var{buffer}}, @w{size_t @var{count}}, @w{size_t *@var{nread}}), @w{void *@var{hook_value}})
1683 The function @code{gpgme_data_new_with_read_cb} creates a new
1684 @code{gpgme_data_t} object and uses the callback function @var{readfunc}
1685 to retrieve the data on demand. As the callback function can supply
1686 the data in any way it wants, this is the most flexible data type
1687 @acronym{GPGME} provides. However, it can not be used to write data.
1689 The callback function receives @var{hook_value} as its first argument
1690 whenever it is invoked. It should return up to @var{count} bytes in
1691 @var{buffer}, and return the number of bytes actually read in
1692 @var{nread}. It may return @code{0} in @var{nread} if no data is
1693 currently available. To indicate @code{EOF} the function should
1694 return with an error code of @code{-1} and set @var{nread} to
1695 @code{0}. The callback function may support to reset its internal
1696 read pointer if it is invoked with @var{buffer} and @var{nread} being
1697 @code{NULL} and @var{count} being @code{0}.
1699 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1700 data object was successfully created, @code{GPG_ERR_INV_VALUE} if
1701 @var{dh} or @var{readfunc} is not a valid pointer, and
1702 @code{GPG_ERR_ENOMEM} if not enough memory is available.
1706 @node Destroying Data Buffers
1707 @section Destroying Data Buffers
1708 @cindex data buffer, destruction
1710 @deftypefun void gpgme_data_release (@w{gpgme_data_t @var{dh}})
1711 The function @code{gpgme_data_release} destroys the data object with
1712 the handle @var{dh}. It releases all associated resources that were
1713 not provided by the user in the first place.
1716 @deftypefun {char *} gpgme_data_release_and_get_mem (@w{gpgme_data_t @var{dh}}, @w{size_t *@var{length}})
1717 The function @code{gpgme_data_release_and_get_mem} is like
1718 @code{gpgme_data_release}, except that it returns the data buffer and
1719 its length that was provided by the object.
1721 The user has to release the buffer with @code{gpgme_free}. In case
1722 the user provided the data buffer in non-copy mode, a copy will be
1723 made for this purpose.
1725 In case an error returns, or there is no suitable data buffer that can
1726 be returned to the user, the function will return @code{NULL}. In any
1727 case, the data object @var{dh} is destroyed.
1731 @deftypefun void gpgme_free (@w{void *@var{buffer}})
1732 The function @code{gpgme_free} releases the memory returned by
1733 @code{gpgme_data_release_and_get_mem}. It should be used instead of
1734 the system libraries @code{free} function in case different allocators
1735 are used in a single program.
1739 @node Manipulating Data Buffers
1740 @section Manipulating Data Buffers
1741 @cindex data buffer, manipulation
1743 Data buffers contain data and meta-data. The following operations can
1744 be used to manipulate both.
1748 * Data Buffer I/O Operations:: I/O operations on data buffers.
1749 * Data Buffer Meta-Data:: Meta-data manipulation of data buffers.
1753 @node Data Buffer I/O Operations
1754 @subsection Data Buffer I/O Operations
1755 @cindex data buffer, I/O operations
1756 @cindex data buffer, read
1757 @cindex data buffer, write
1758 @cindex data buffer, seek
1760 @deftypefun ssize_t gpgme_data_read (@w{gpgme_data_t @var{dh}}, @w{void *@var{buffer}}, @w{size_t @var{length}})
1761 The function @code{gpgme_data_read} reads up to @var{length} bytes
1762 from the data object with the handle @var{dh} into the space starting
1765 If no error occurs, the actual amount read is returned. If the end of
1766 the data object is reached, the function returns 0.
1768 In all other cases, the function returns -1 and sets @var{errno}.
1771 @deftypefun ssize_t gpgme_data_write (@w{gpgme_data_t @var{dh}}, @w{const void *@var{buffer}}, @w{size_t @var{size}})
1772 The function @code{gpgme_data_write} writes up to @var{size} bytes
1773 starting from @var{buffer} into the data object with the handle
1774 @var{dh} at the current write position.
1776 The function returns the number of bytes actually written, or -1 if an
1777 error occurs. If an error occurs, @var{errno} is set.
1780 @deftypefun off_t gpgme_data_seek (@w{gpgme_data_t @var{dh}}, @w{off_t @var{offset}}, @w{int @var{whence}})
1781 The function @code{gpgme_data_seek} changes the current read/write
1784 The @var{whence} argument specifies how the @var{offset} should be
1785 interpreted. It must be one of the following symbolic constants:
1789 Specifies that @var{offset} is a count of characters from the
1790 beginning of the data object.
1793 Specifies that @var{offset} is a count of characters from the current
1794 file position. This count may be positive or negative.
1797 Specifies that @var{offset} is a count of characters from the end of
1798 the data object. A negative count specifies a position within the
1799 current extent of the data object; a positive count specifies a
1800 position past the current end. If you set the position past the
1801 current end, and actually write data, you will extend the data object
1802 with zeros up to that position.
1805 If successful, the function returns the resulting file position,
1806 measured in bytes from the beginning of the data object. You can use
1807 this feature together with @code{SEEK_CUR} to read the current
1808 read/write position.
1810 If the function fails, -1 is returned and @var{errno} is set.
1813 The following function is deprecated and should not be used. It will
1814 be removed in a future version of @acronym{GPGME}.
1816 @deftypefun gpgme_error_t gpgme_data_rewind (@w{gpgme_data_t @var{dh}})
1817 The function @code{gpgme_data_rewind} is equivalent to:
1820 return (gpgme_data_seek (dh, 0, SEEK_SET) == -1)
1821 ? gpgme_error_from_errno (errno) : 0;
1828 @node Data Buffer Meta-Data
1829 @subsection Data Buffer Meta-Data
1830 @cindex data buffer, meta-data
1831 @cindex data buffer, file name
1832 @cindex data buffer, encoding
1834 @deftypefun {char *} gpgme_data_get_file_name (@w{gpgme_data_t @var{dh}})
1835 The function @code{gpgme_data_get_file_name} returns a pointer to a
1836 string containing the file name associated with the data object. The
1837 file name will be stored in the output when encrypting or signing the
1838 data and will be returned to the user when decrypting or verifying the
1841 If no error occurs, the string containing the file name is returned.
1842 Otherwise, @code{NULL} will be returned.
1846 @deftypefun gpgme_error_t gpgme_data_set_file_name (@w{gpgme_data_t @var{dh}}, @w{const char *@var{file_name}})
1847 The function @code{gpgme_data_set_file_name} sets the file name
1848 associated with the data object. The file name will be stored in the
1849 output when encrypting or signing the data and will be returned to the
1850 user when decrypting or verifying the output data.
1852 The function returns the error code @code{GPG_ERR_INV_VALUE} if
1853 @var{dh} is not a valid pointer and @code{GPG_ERR_ENOMEM} if not
1854 enough memory is available.
1858 @deftp {Data type} {enum gpgme_data_encoding_t}
1859 @tindex gpgme_data_encoding_t
1860 The @code{gpgme_data_encoding_t} type specifies the encoding of a
1861 @code{gpgme_data_t} object. This encoding is useful to give the backend
1862 a hint on the type of data. The following data types are available:
1865 @item GPGME_DATA_ENCODING_NONE
1866 This specifies that the encoding is not known. This is the default
1867 for a new data object. The backend will try its best to detect the
1868 encoding automatically.
1870 @item GPGME_DATA_ENCODING_BINARY
1871 This specifies that the data is encoding in binary form; i.e. there is
1872 no special encoding.
1874 @item GPGME_DATA_ENCODING_BASE64
1875 This specifies that the data is encoded using the Base-64 encoding
1876 scheme as used by @acronym{MIME} and other protocols.
1878 @item GPGME_DATA_ENCODING_ARMOR
1879 This specifies that the data is encoded in an armored form as used by
1884 @deftypefun gpgme_data_encoding_t gpgme_data_get_encoding (@w{gpgme_data_t @var{dh}})
1885 The function @code{gpgme_data_get_encoding} returns the encoding of
1886 the data object with the handle @var{dh}. If @var{dh} is not a valid
1887 pointer (e.g. @code{NULL}) @code{GPGME_DATA_ENCODING_NONE} is
1891 @deftypefun gpgme_error_t gpgme_data_set_encoding (@w{gpgme_data_t @var{dh}, gpgme_data_encoding_t @var{enc}})
1892 The function @code{gpgme_data_set_encoding} changes the encoding of
1893 the data object with the handle @var{dh} to @var{enc}.
1904 All cryptographic operations in @acronym{GPGME} are performed within a
1905 context, which contains the internal state of the operation as well as
1906 configuration parameters. By using several contexts you can run
1907 several cryptographic operations in parallel, with different
1910 @deftp {Data type} {gpgme_ctx_t}
1911 The @code{gpgme_ctx_t} type is a handle for a @acronym{GPGME} context,
1912 which is used to hold the configuration, status and result of
1913 cryptographic operations.
1917 * Creating Contexts:: Creating new @acronym{GPGME} contexts.
1918 * Destroying Contexts:: Releasing @acronym{GPGME} contexts.
1919 * Context Attributes:: Setting properties of a context.
1920 * Key Management:: Managing keys with @acronym{GPGME}.
1921 * Trust Item Management:: Managing trust items with @acronym{GPGME}.
1922 * Crypto Operations:: Using a context for cryptography.
1923 * Run Control:: Controlling how operations are run.
1927 @node Creating Contexts
1928 @section Creating Contexts
1929 @cindex context, creation
1931 @deftypefun gpgme_error_t gpgme_new (@w{gpgme_ctx_t *@var{ctx}})
1932 The function @code{gpgme_new} creates a new @code{gpgme_ctx_t} object
1933 and returns a handle for it in @var{ctx}.
1935 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1936 context was successfully created, @code{GPG_ERR_INV_VALUE} if
1937 @var{ctx} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if not
1938 enough memory is available.
1942 @node Destroying Contexts
1943 @section Destroying Contexts
1944 @cindex context, destruction
1946 @deftypefun void gpgme_release (@w{gpgme_ctx_t @var{ctx}})
1947 The function @code{gpgme_release} destroys the context with the handle
1948 @var{ctx} and releases all associated resources.
1952 @node Context Attributes
1953 @section Context Attributes
1954 @cindex context, attributes
1957 * Protocol Selection:: Selecting the protocol used by a context.
1958 * Crypto Engine:: Configuring the crypto engine.
1959 * ASCII Armor:: Requesting @acronym{ASCII} armored output.
1960 * Text Mode:: Choosing canonical text mode.
1961 * Included Certificates:: Including a number of certificates.
1962 * Key Listing Mode:: Selecting key listing mode.
1963 * Passphrase Callback:: Getting the passphrase from the user.
1964 * Progress Meter Callback:: Being informed about the progress.
1965 * Locale:: Setting the locale of a context.
1969 @node Protocol Selection
1970 @subsection Protocol Selection
1971 @cindex context, selecting protocol
1972 @cindex protocol, selecting
1974 @deftypefun gpgme_error_t gpgme_set_protocol (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_protocol_t @var{proto}})
1975 The function @code{gpgme_set_protocol} sets the protocol used within
1976 the context @var{ctx} to @var{proto}. All crypto operations will be
1977 performed by the crypto engine configured for that protocol.
1978 @xref{Protocols and Engines}.
1980 Setting the protocol with @code{gpgme_set_protocol} does not check if
1981 the crypto engine for that protocol is available and installed
1982 correctly. @xref{Engine Version Check}.
1984 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1985 protocol could be set successfully, and @code{GPG_ERR_INV_VALUE} if
1986 @var{protocol} is not a valid protocol.
1989 @deftypefun gpgme_protocol_t gpgme_get_protocol (@w{gpgme_ctx_t @var{ctx}})
1990 The function @code{gpgme_get_protocol} retrieves the protocol currently
1991 use with the context @var{ctx}.
1996 @subsection Crypto Engine
1997 @cindex context, configuring engine
1998 @cindex engine, configuration per context
2000 The following functions can be used to set and retrieve the
2001 configuration of the crypto engines of a specific context. The
2002 default can also be retrieved without any particular context.
2003 @xref{Engine Information}. The default can also be changed globally.
2004 @xref{Engine Configuration}.
2006 @deftypefun gpgme_engine_info_t gpgme_ctx_get_engine_info (@w{gpgme_ctx_t @var{ctx}})
2007 The function @code{gpgme_ctx_get_engine_info} returns a linked list of
2008 engine info structures. Each info structure describes the
2009 configuration of one configured backend, as used by the context
2012 The result is valid until the next invocation of
2013 @code{gpgme_ctx_set_engine_info} for this particular context.
2015 This function can not fail.
2018 @deftypefun gpgme_error_t gpgme_ctx_set_engine_info (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_protocol_t @var{proto}}, @w{const char *@var{file_name}}, @w{const char *@var{home_dir}})
2019 The function @code{gpgme_ctx_set_engine_info} changes the
2020 configuration of the crypto engine implementing the protocol
2021 @var{proto} for the context @var{ctx}.
2023 @var{file_name} is the file name of the executable program
2024 implementing this protocol, and @var{home_dir} is the directory name
2025 of the configuration directory for this crypto engine. If
2026 @var{home_dir} is @code{NULL}, the engine's default will be used.
2028 Currently this function must be used before starting the first crypto
2029 operation. It is unspecified if and when the changes will take effect
2030 if the function is called after starting the first operation on the
2033 This function returns the error code @code{GPG_ERR_NO_ERROR} if
2034 successful, or an eror code on failure.
2038 @c FIXME: Unfortunately, using @acronym here breaks texi2dvi.
2040 @subsection @acronym{ASCII} Armor
2041 @cindex context, armor mode
2042 @cindex @acronym{ASCII} armor
2045 @deftypefun void gpgme_set_armor (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{yes}})
2046 The function @code{gpgme_set_armor} specifies if the output should be
2047 @acronym{ASCII} armored. By default, output is not @acronym{ASCII}
2050 @acronym{ASCII} armored output is disabled if @var{yes} is zero, and
2054 @deftypefun int gpgme_get_armor (@w{gpgme_ctx_t @var{ctx}})
2055 The function @code{gpgme_get_armor} returns 1 if the output is
2056 @acronym{ASCII} armored, and @code{0} if it is not, or if @var{ctx} is
2057 not a valid pointer.
2062 @subsection Text Mode
2063 @cindex context, text mode
2065 @cindex canonical text mode
2067 @deftypefun void gpgme_set_textmode (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{yes}})
2068 The function @code{gpgme_set_textmode} specifies if canonical text mode
2069 should be used. By default, text mode is not used.
2071 Text mode is for example used for the RFC2015 signatures; note that
2072 the updated RFC 3156 mandates that the mail user agent does some
2073 preparations so that text mode is not needed anymore.
2075 This option is only relevant to the OpenPGP crypto engine, and ignored
2076 by all other engines.
2078 Canonical text mode is disabled if @var{yes} is zero, and enabled
2082 @deftypefun int gpgme_get_textmode (@w{gpgme_ctx_t @var{ctx}})
2083 The function @code{gpgme_get_textmode} returns 1 if canonical text
2084 mode is enabled, and @code{0} if it is not, or if @var{ctx} is not a
2089 @node Included Certificates
2090 @subsection Included Certificates
2091 @cindex certificates, included
2093 @deftypefun void gpgme_set_include_certs (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{nr_of_certs}})
2094 The function @code{gpgme_set_include_certs} specifies how many
2095 certificates should be included in an S/MIME signed message. By
2096 default, only the sender's certificate is included. The possible
2097 values of @var{nr_of_certs} are:
2100 @item GPGME_INCLUDE_CERTS_DEFAULT
2101 Fall back to the default of the crypto backend. This is the default
2104 Include all certificates except the root certificate.
2106 Include all certificates.
2108 Include no certificates.
2110 Include the sender's certificate only.
2112 Include the first n certificates of the certificates path, starting
2113 from the sender's certificate. The number @code{n} must be positive.
2116 Values of @var{nr_of_certs} smaller than -2 are undefined.
2118 This option is only relevant to the CMS crypto engine, and ignored by
2122 @deftypefun int gpgme_get_include_certs (@w{gpgme_ctx_t @var{ctx}})
2123 The function @code{gpgme_get_include_certs} returns the number of
2124 certificates to include into an S/MIME signed message.
2128 @node Key Listing Mode
2129 @subsection Key Listing Mode
2130 @cindex key listing mode
2131 @cindex key listing, mode of
2133 @deftypefun gpgme_error_t gpgme_set_keylist_mode (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_keylist_mode_t @var{mode}})
2134 The function @code{gpgme_set_keylist_mode} changes the default
2135 behaviour of the key listing functions. The value in @var{mode} is a
2136 bitwise-or combination of one or multiple of the following bit values:
2139 @item GPGME_KEYLIST_MODE_LOCAL
2140 The @code{GPGME_KEYLIST_MODE_LOCAL} symbol specifies that the local
2141 keyring should be searched for keys in the keylisting operation. This
2144 @item GPGME_KEYLIST_MODE_EXTERN
2145 The @code{GPGME_KEYLIST_MODE_EXTERN} symbol specifies that an external
2146 source should be searched for keys in the keylisting
2147 operation. The type of external source is dependant on the crypto
2148 engine used. For example, it can be a remote keyserver or LDAP
2151 @item GPGME_KEYLIST_MODE_SIGS
2152 The @code{GPGME_KEYLIST_MODE_SIGS} symbol specifies that the key
2153 signatures should be included in the listed keys.
2155 @item GPGME_KEYLIST_MODE_SIG_NOTATIONS
2156 The @code{GPGME_KEYLIST_MODE_SIG_NOTATIONS} symbol specifies that the
2157 signature notations on key signatures should be included in the listed
2158 keys. This only works if @code{GPGME_KEYLIST_MODE_SIGS} is also
2161 @item GPGME_KEYLIST_MODE_VALIDATE
2162 The @code{GPGME_KEYLIST_MODE_VALIDATE} symbol specifies that the
2163 backend should do key or certificate validation and not just get the
2164 validity information from an internal cache. This might be an
2165 expensive operation and is in general not useful. Currently only
2166 implemented for the S/MIME backend and ignored for other backends.
2170 At least one of @code{GPGME_KEYLIST_MODE_LOCAL} and
2171 @code{GPGME_KEYLIST_MODE_EXTERN} must be specified. For future binary
2172 compatibility, you should get the current mode with
2173 @code{gpgme_get_keylist_mode} and modify it by setting or clearing the
2174 appropriate bits, and then using that calulcated value in the
2175 @code{gpgme_set_keylisting_mode} operation. This will leave all other
2176 bits in the mode value intact (in particular those that are not used
2177 in the current version of the library).
2179 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
2180 mode could be set correctly, and @code{GPG_ERR_INV_VALUE} if @var{ctx}
2181 is not a valid pointer or @var{mode} is not a valid mode.
2185 @deftypefun gpgme_keylist_mode_t gpgme_get_keylist_mode (@w{gpgme_ctx_t @var{ctx}})
2186 The function @code{gpgme_get_keylist_mode} returns the current key
2187 listing mode of the context @var{ctx}. This value can then be
2188 modified and used in a subsequent @code{gpgme_set_keylist_mode}
2189 operation to only affect the desired bits (and leave all others
2192 The function returns 0 if @var{ctx} is not a valid pointer, and the
2193 current mode otherwise. Note that 0 is not a valid mode value.
2197 @node Passphrase Callback
2198 @subsection Passphrase Callback
2199 @cindex callback, passphrase
2200 @cindex passphrase callback
2202 @deftp {Data type} {gpgme_error_t (*gpgme_passphrase_cb_t)(void *@var{hook}, const char *@var{uid_hint}, const char *@var{passphrase_info}, @w{int @var{prev_was_bad}}, @w{int @var{fd}})}
2203 @tindex gpgme_passphrase_cb_t
2204 The @code{gpgme_passphrase_cb_t} type is the type of functions usable as
2205 passphrase callback function.
2207 The argument @var{uid_hint} might contain a string that gives an
2208 indication for which user ID the passphrase is required. If this is
2209 not available, or not applicable (in the case of symmetric encryption,
2210 for example), @var{uid_hint} will be @code{NULL}.
2212 The argument @var{passphrase_info}, if not @code{NULL}, will give
2213 further information about the context in which the passphrase is
2214 required. This information is engine and operation specific.
2216 If this is the repeated attempt to get the passphrase, because
2217 previous attempts failed, then @var{prev_was_bad} is 1, otherwise it
2220 The user must write the passphrase, followed by a newline character,
2221 to the file descriptor @var{fd}. If the user returns 0 indicating
2222 success, the user must at least write a newline character before
2223 returning from the callback.
2225 If an error occurs, return the corresponding @code{gpgme_error_t}
2226 value. You can use the error code @code{GPG_ERR_CANCELED} to abort
2227 the operation. Otherwise, return @code{0}.
2230 @deftypefun void gpgme_set_passphrase_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_passphrase_cb_t @var{passfunc}}, @w{void *@var{hook_value}})
2231 The function @code{gpgme_set_passphrase_cb} sets the function that is
2232 used when a passphrase needs to be provided by the user to
2233 @var{passfunc}. The function @var{passfunc} needs to implemented by
2234 the user, and whenever it is called, it is called with its first
2235 argument being @var{hook_value}. By default, no passphrase callback
2238 Not all crypto engines require this callback to retrieve the
2239 passphrase. It is better if the engine retrieves the passphrase from
2240 a trusted agent (a daemon process), rather than having each user to
2241 implement their own passphrase query. Some engines do not even
2242 support an external passphrase callback at all, in this case the error
2243 code @code{GPG_ERR_NOT_SUPPORTED} is returned.
2245 The user can disable the use of a passphrase callback function by
2246 calling @code{gpgme_set_passphrase_cb} with @var{passfunc} being
2250 @deftypefun void gpgme_get_passphrase_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_passphrase_cb_t *@var{passfunc}}, @w{void **@var{hook_value}})
2251 The function @code{gpgme_get_passphrase_cb} returns the function that
2252 is used when a passphrase needs to be provided by the user in
2253 @var{*passfunc}, and the first argument for this function in
2254 @var{*hook_value}. If no passphrase callback is set, or @var{ctx} is
2255 not a valid pointer, @code{NULL} is returned in both variables.
2257 @var{passfunc} or @var{hook_value} can be @code{NULL}. In this case,
2258 the corresponding value will not be returned.
2262 @node Progress Meter Callback
2263 @subsection Progress Meter Callback
2264 @cindex callback, progress meter
2265 @cindex progress meter callback
2267 @deftp {Data type} {void (*gpgme_progress_cb_t)(void *@var{hook}, const char *@var{what}, int @var{type}, int @var{current}, int @var{total})}
2268 @tindex gpgme_progress_cb_t
2269 The @code{gpgme_progress_cb_t} type is the type of functions usable as
2270 progress callback function.
2272 The arguments are specific to the crypto engine. More information
2273 about the progress information returned from the GnuPG engine can be
2274 found in the GnuPG source code in the file @file{doc/DETAILS} in the
2278 @deftypefun void gpgme_set_progress_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_progress_cb_t @var{progfunc}}, @w{void *@var{hook_value}})
2279 The function @code{gpgme_set_progress_cb} sets the function that is
2280 used when progress information about a cryptographic operation is
2281 available. The function @var{progfunc} needs to implemented by the
2282 user, and whenever it is called, it is called with its first argument
2283 being @var{hook_value}. By default, no progress callback function
2286 Setting a callback function allows an interactive program to display
2287 progress information about a long operation to the user.
2289 The user can disable the use of a progress callback function by
2290 calling @code{gpgme_set_progress_cb} with @var{progfunc} being
2294 @deftypefun void gpgme_get_progress_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_progress_cb_t *@var{progfunc}}, @w{void **@var{hook_value}})
2295 The function @code{gpgme_get_progress_cb} returns the function that is
2296 used to inform the user about the progress made in @var{*progfunc},
2297 and the first argument for this function in @var{*hook_value}. If no
2298 progress callback is set, or @var{ctx} is not a valid pointer,
2299 @code{NULL} is returned in both variables.
2301 @var{progfunc} or @var{hook_value} can be @code{NULL}. In this case,
2302 the corresponding value will not be returned.
2308 @cindex locale, default
2309 @cindex locale, of a context
2311 A locale setting can be associated with a context. This locale is
2312 passed to the crypto engine, and used for applications like the PIN
2313 entry, which is displayed to the user when entering a passphrase is
2316 The default locale is used to initialize the locale setting of all
2317 contexts created afterwards.
2319 @deftypefun gpgme_error_t gpgme_set_locale (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{category}}, @w{const char *@var{value}})
2320 The function @code{gpgme_set_locale} sets the locale of the context
2321 @var{ctx}, or the default locale if @var{ctx} is a null pointer.
2323 The locale settings that should be changed are specified by
2324 @var{category}. Supported categories are @code{LC_CTYPE},
2325 @code{LC_MESSAGES}, and @code{LC_ALL}, which is a wildcard you can use
2326 if you want to change all the categories at once.
2328 The value to be used for the locale setting is @var{value}, which will
2329 be copied to @acronym{GPGME}'s internal data structures. @var{value}
2330 can be a null pointer, which disables setting the locale, and will
2331 make PIN entry and other applications use their default setting, which
2332 is usually not what you want.
2334 Note that the settings are only used if the application runs on a text
2335 terminal, and that the settings should fit the configuration of the
2336 output terminal. Normally, it is sufficient to initialize the default
2339 The function returns an error if not enough memory is available.
2343 @node Key Management
2344 @section Key Management
2345 @cindex key management
2347 Some of the cryptographic operations require that recipients or
2348 signers are specified. This is always done by specifying the
2349 respective keys that should be used for the operation. The following
2350 section describes how such keys can be selected and manipulated.
2352 @deftp {Data type} gpgme_sub_key_t
2353 The @code{gpgme_sub_key_t} type is a pointer to a subkey structure.
2354 Sub keys are one component of a @code{gpgme_key_t} object. In fact,
2355 subkeys are those parts that contains the real information about the
2356 individual cryptographic keys that belong to the same key object. One
2357 @code{gpgme_key_t} can contain several subkeys. The first subkey in
2358 the linked list is also called the primary key.
2360 The subkey structure has the following members:
2363 @item gpgme_sub_key_t next
2364 This is a pointer to the next subkey structure in the linked list, or
2365 @code{NULL} if this is the last element.
2367 @item unsigned int revoked : 1
2368 This is true if the subkey is revoked.
2370 @item unsigned int expired : 1
2371 This is true if the subkey is expired.
2373 @item unsigned int disabled : 1
2374 This is true if the subkey is disabled.
2376 @item unsigned int invalid : 1
2377 This is true if the subkey is invalid.
2379 @item unsigned int can_encrypt : 1
2380 This is true if the subkey can be used for encryption.
2382 @item unsigned int can_sign : 1
2383 This is true if the subkey can be used to create data signatures.
2385 @item unsigned int can_certify : 1
2386 This is true if the subkey can be used to create key certificates.
2388 @item unsigned int can_authenticate : 1
2389 This is true if the subkey can be used for authentication.
2391 @item unsigned int is_qualified : 1
2392 This is true if the subkey can be used for qualified signatures
2393 according to local government regulations.
2395 @item unsigned int secret : 1
2396 This is true if the subkey is a secret key. Note that it will be false
2397 if the key is actually a stub key; i.e. a secret key operation is
2398 currently not possible (offline-key).
2400 @item gpgme_pubkey_algo_t pubkey_algo
2401 This is the public key algorithm supported by this subkey.
2403 @item unsigned int length
2404 This is the length of the subkey (in bits).
2407 This is the key ID of the subkey in hexadecimal digits.
2410 This is the fingerprint of the subkey in hexadecimal digits, if
2413 @item long int timestamp
2414 This is the creation timestamp of the subkey. This is -1 if the
2415 timestamp is invalid, and 0 if it is not available.
2417 @item long int expires
2418 This is the expiration timestamp of the subkey, or 0 if the subkey
2423 @deftp {Data type} gpgme_key_sig_t
2424 The @code{gpgme_key_sig_t} type is a pointer to a key signature structure.
2425 Key signatures are one component of a @code{gpgme_key_t} object, and
2426 validate user IDs on the key.
2428 The signatures on a key are only available if the key was retrieved
2429 via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode
2430 enabled, because it can be expensive to retrieve all signatures of a
2433 The signature notations on a key signature are only available if the
2434 key was retrieved via a listing operation with the
2435 @code{GPGME_KEYLIST_MODE_SIG_NOTATIONS} mode enabled, because it can
2436 be expensive to retrieve all signature notations.
2438 The key signature structure has the following members:
2441 @item gpgme_key_sig_t next
2442 This is a pointer to the next key signature structure in the linked
2443 list, or @code{NULL} if this is the last element.
2445 @item unsigned int revoked : 1
2446 This is true if the key signature is a revocation signature.
2448 @item unsigned int expired : 1
2449 This is true if the key signature is expired.
2451 @item unsigned int invalid : 1
2452 This is true if the key signature is invalid.
2454 @item unsigned int exportable : 1
2455 This is true if the key signature is exportable.
2457 @item gpgme_pubkey_algo_t pubkey_algo
2458 This is the public key algorithm used to create the signature.
2461 This is the key ID of the key (in hexadecimal digits) used to create
2464 @item long int timestamp
2465 This is the creation timestamp of the key signature. This is -1 if
2466 the timestamp is invalid, and 0 if it is not available.
2468 @item long int expires
2469 This is the expiration timestamp of the key signature, or 0 if the key
2470 signature does not expire.
2472 @item gpgme_error_t status
2473 This is the status of the signature and has the same meaning as the
2474 member of the same name in a @code{gpgme_signature_t} object.
2476 @item unsigned int sig_class
2477 This specifies the signature class of the key signature. The meaning
2478 is specific to the crypto engine.
2481 This is the main user ID of the key used to create the signature.
2484 This is the name component of @code{uid}, if available.
2487 This is the comment component of @code{uid}, if available.
2490 This is the email component of @code{uid}, if available.
2492 @item gpgme_sig_notation_t notations
2493 This is a linked list with the notation data and policy URLs.
2497 @deftp {Data type} gpgme_user_id_t
2498 A user ID is a component of a @code{gpgme_key_t} object. One key can
2499 have many user IDs. The first one in the list is the main (or
2502 The user ID structure has the following members.
2505 @item gpgme_user_id_t next
2506 This is a pointer to the next user ID structure in the linked list, or
2507 @code{NULL} if this is the last element.
2509 @item unsigned int revoked : 1
2510 This is true if the user ID is revoked.
2512 @item unsigned int invalid : 1
2513 This is true if the user ID is invalid.
2515 @item gpgme_validity_t validity
2516 This specifies the validity of the user ID.
2519 This is the user ID string.
2522 This is the name component of @code{uid}, if available.
2525 This is the comment component of @code{uid}, if available.
2528 This is the email component of @code{uid}, if available.
2530 @item gpgme_key_sig_t signatures
2531 This is a linked list with the signatures on this user ID.
2535 @deftp {Data type} gpgme_key_t
2536 The @code{gpgme_key_t} type is a pointer to a key object. It has the
2540 @item gpgme_keylist_mode_t keylist_mode
2541 The keylist mode that was active when the key was retrieved.
2543 @item unsigned int revoked : 1
2544 This is true if the key is revoked.
2546 @item unsigned int expired : 1
2547 This is true if the key is expired.
2549 @item unsigned int disabled : 1
2550 This is true if the key is disabled.
2552 @item unsigned int invalid : 1
2553 This is true if the key is invalid. This might have several reasons,
2554 for a example for the S/MIME backend, it will be set in during key
2555 listsing if the key could not be validated due to a missing
2556 certificates or unmatched policies.
2558 @item unsigned int can_encrypt : 1
2559 This is true if the key (ie one of its subkeys) can be used for
2562 @item unsigned int can_sign : 1
2563 This is true if the key (ie one of its subkeys) can be used to create
2566 @item unsigned int can_certify : 1
2567 This is true if the key (ie one of its subkeys) can be used to create
2570 @item unsigned int can_authenticate : 1
2571 This is true if the key (ie one of its subkeys) can be used for
2574 @item unsigned int is_qualified : 1
2575 This is true if the key can be used for qualified signatures according
2576 to local government regulations.
2578 @item unsigned int secret : 1
2579 This is true if the key is a secret key. Note, that this will always be
2580 true even if the corresponding subkey flag may be false (offline/stub
2583 @item gpgme_protocol_t protocol
2584 This is the protocol supported by this key.
2586 @item char *issuer_serial
2587 If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
2590 @item char *issuer_name
2591 If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
2594 @item char *chain_id
2595 If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
2596 chain ID, which can be used to built the certificate chain.
2598 @item gpgme_validity_t owner_trust
2599 If @code{protocol} is @code{GPGME_PROTOCOL_OpenPGP}, then this is the
2602 @item gpgme_sub_key_t subkeys
2603 This is a linked list with the subkeys of the key. The first subkey
2604 in the list is the primary key and usually available.
2606 @item gpgme_user_id_t uids
2607 This is a linked list with the user IDs of the key. The first user ID
2608 in the list is the main (or primary) user ID.
2613 * Listing Keys:: Browsing the list of available keys.
2614 * Information About Keys:: Requesting detailed information about keys.
2615 * Key Signatures:: Listing the signatures on a key.
2616 * Manipulating Keys:: Operations on keys.
2617 * Generating Keys:: Creating new key pairs.
2618 * Exporting Keys:: Retrieving key data from the key ring.
2619 * Importing Keys:: Adding keys to the key ring.
2620 * Deleting Keys:: Removing keys from the key ring.
2621 * Advanced Key Editing:: Advanced key edit operation.
2626 @subsection Listing Keys
2627 @cindex listing keys
2629 @cindex key listing, start
2630 @cindex key ring, list
2631 @cindex key ring, search
2633 @deftypefun gpgme_error_t gpgme_op_keylist_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}})
2634 The function @code{gpgme_op_keylist_start} initiates a key listing
2635 operation inside the context @var{ctx}. It sets everything up so that
2636 subsequent invocations of @code{gpgme_op_keylist_next} return the keys
2639 If @var{pattern} is @code{NULL}, all available keys are returned.
2640 Otherwise, @var{pattern} contains an engine specific expression that
2641 is used to limit the list to all keys matching the pattern. Note that
2642 the total length of the pattern is restricted to an engine-specific
2643 maximum (a couple of hundred characters are usually accepted). The
2644 pattern should be used to restrict the search to a certain common name
2645 or user, not to list many specific keys at once by listing their
2646 fingerprints or key IDs.
2648 If @var{secret_only} is not @code{0}, the list is restricted to secret
2651 The context will be busy until either all keys are received (and
2652 @code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}), or
2653 @code{gpgme_op_keylist_end} is called to finish the operation.
2655 The function returns the error code @code{GPG_ERR_INV_VALUE} if
2656 @var{ctx} is not a valid pointer, and passes through any errors that
2657 are reported by the crypto engine support routines.
2660 @deftypefun gpgme_error_t gpgme_op_keylist_ext_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}[]}, @w{int @var{secret_only}}, @w{int @var{reserved}})
2661 The function @code{gpgme_op_keylist_ext_start} initiates an extended
2662 key listing operation inside the context @var{ctx}. It sets
2663 everything up so that subsequent invocations of
2664 @code{gpgme_op_keylist_next} return the keys in the list.
2666 If @var{pattern} or @var{*pattern} is @code{NULL}, all available keys
2667 are returned. Otherwise, @var{pattern} is a @code{NULL} terminated
2668 array of strings that are used to limit the list to all keys matching
2669 at least one of the patterns verbatim. Note that the total length of
2670 all patterns is restricted to an engine-specific maximum (the exact
2671 limit also depends on the number of patterns and amount of quoting
2672 required, but a couple of hundred characters are usually accepted).
2673 Patterns should be used to restrict the search to a certain common
2674 name or user, not to list many specific keys at once by listing their
2675 fingerprints or key IDs.
2677 If @var{secret_only} is not @code{0}, the list is restricted to secret
2680 The value of @var{reserved} must be @code{0}.
2682 The context will be busy until either all keys are received (and
2683 @code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}), or
2684 @code{gpgme_op_keylist_end} is called to finish the operation.
2686 The function returns the error code @code{GPG_ERR_INV_VALUE} if
2687 @var{ctx} is not a valid pointer, and passes through any errors that
2688 are reported by the crypto engine support routines.
2691 @deftypefun gpgme_error_t gpgme_op_keylist_next (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t *@var{r_key}})
2692 The function @code{gpgme_op_keylist_next} returns the next key in the
2693 list created by a previous @code{gpgme_op_keylist_start} operation in
2694 the context @var{ctx}. The key will have one reference for the user.
2695 @xref{Manipulating Keys}.
2697 This is the only way to get at @code{gpgme_key_t} objects in
2700 If the last key in the list has already been returned,
2701 @code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}.
2703 The function returns the error code @code{GPG_ERR_INV_VALUE} if
2704 @var{ctx} or @var{r_key} is not a valid pointer, and
2705 @code{GPG_ERR_ENOMEM} if there is not enough memory for the operation.
2708 @deftypefun gpgme_error_t gpgme_op_keylist_end (@w{gpgme_ctx_t @var{ctx}})
2709 The function @code{gpgme_op_keylist_next} ends a pending key list
2710 operation in the context @var{ctx}.
2712 After the operation completed successfully, the result of the key
2713 listing operation can be retrieved with
2714 @code{gpgme_op_keylist_result}.
2716 The function returns the error code @code{GPG_ERR_INV_VALUE} if
2717 @var{ctx} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if at some
2718 time during the operation there was not enough memory available.
2721 The following example illustrates how all keys containing a certain
2722 string (@code{g10code}) can be listed with their key ID and the name
2723 and e-mail address of the main user ID:
2727 gpgme_error_t err = gpgme_new (&ctx);
2731 err = gpgme_op_keylist_start (ctx, "g10code", 0);
2734 err = gpgme_op_keylist_next (ctx, &key);
2737 printf ("%s: %s <%s>\n", key->keyid, key->name, key->email);
2738 gpgme_key_release (key);
2740 gpgme_release (ctx);
2742 if (gpg_err_code (err) != GPG_ERR_EOF)
2744 fprintf (stderr, "%s: can not list keys: %s\n",
2745 argv[0], gpgme_strerror (err));
2750 @deftp {Data type} {gpgme_keylist_result_t}
2751 This is a pointer to a structure used to store the result of a
2752 @code{gpgme_op_keylist_*} operation. After successfully ending a key
2753 listing operation, you can retrieve the pointer to the result with
2754 @code{gpgme_op_keylist_result}. The structure contains the following
2758 @item unsigned int truncated : 1
2759 This is true if the crypto backend had to truncate the result, and
2760 less than the desired keys could be listed.
2764 @deftypefun gpgme_keylist_result_t gpgme_op_keylist_result (@w{gpgme_ctx_t @var{ctx}})
2765 The function @code{gpgme_op_keylist_result} returns a
2766 @code{gpgme_keylist_result_t} pointer to a structure holding the
2767 result of a @code{gpgme_op_keylist_*} operation. The pointer is only
2768 valid if the last operation on the context was a key listing
2769 operation, and if this operation finished successfully. The returned
2770 pointer is only valid until the next operation is started on the
2774 In a simple program, for which a blocking operation is acceptable, the
2775 following function can be used to retrieve a single key.
2777 @deftypefun gpgme_error_t gpgme_get_key (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{fpr}}, @w{gpgme_key_t *@var{r_key}}, @w{int @var{secret}})
2778 The function @code{gpgme_get_key} gets the key with the fingerprint
2779 (or key ID) @var{fpr} from the crypto backend and return it in
2780 @var{r_key}. If @var{secret} is true, get the secret key. The
2781 currently active keylist mode is used to retrieve the key. The key
2782 will have one reference for the user.
2784 If the key is not found in the keyring, @code{gpgme_get_key} returns
2785 the error code @code{GPG_ERR_NO_ERROR} and *@var{r_key} will be set to
2788 The function returns the error code @code{GPG_ERR_INV_VALUE} if
2789 @var{ctx} or @var{r_key} is not a valid pointer or @var{fpr} is not a
2790 fingerprint or key ID, @code{GPG_ERR_AMBIGUOUS_NAME} if the key ID was
2791 not a unique specifier for a key, and @code{GPG_ERR_ENOMEM} if at some
2792 time during the operation there was not enough memory available.
2796 @node Information About Keys
2797 @subsection Information About Keys
2798 @cindex key, information about
2799 @cindex key, attributes
2800 @cindex attributes, of a key
2802 Please see the beginning of this section for more information about
2803 @code{gpgme_key_t} objects.
2805 @deftp {Data type} gpgme_validity_t
2806 The @code{gpgme_validity_t} type is used to specify the validity of a user ID
2807 in a key. The following validities are defined:
2810 @item GPGME_VALIDITY_UNKNOWN
2811 The user ID is of unknown validity. The string representation of this
2814 @item GPGME_VALIDITY_UNDEFINED
2815 The validity of the user ID is undefined. The string representation of this
2818 @item GPGME_VALIDITY_NEVER
2819 The user ID is never valid. The string representation of this
2822 @item GPGME_VALIDITY_MARGINAL
2823 The user ID is marginally valid. The string representation of this
2826 @item GPGME_VALIDITY_FULL
2827 The user ID is fully valid. The string representation of this
2830 @item GPGME_VALIDITY_ULTIMATE
2831 The user ID is ultimately valid. The string representation of this
2837 The following interfaces are deprecated and only provided for backward
2838 compatibility. Don't use them. They will be removed in a future
2839 version of @acronym{GPGME}.
2841 @deftp {Data type} gpgme_attr_t
2842 The @code{gpgme_attr_t} type is used to specify a key or trust item
2843 attribute. The following attributes are defined:
2846 @item GPGME_ATTR_KEYID
2847 This is the key ID of a sub key. It is representable as a string.
2849 For trust items, the trust item refers to the key with this ID.
2851 @item GPGME_ATTR_FPR
2852 This is the fingerprint of a sub key. It is representable as a
2855 @item GPGME_ATTR_ALGO
2856 This is the crypto algorithm for which the sub key can be used. It
2857 is representable as a string and as a number. The numbers correspond
2858 to the @code{enum gcry_pk_algos} values in the gcrypt library.
2860 @item GPGME_ATTR_LEN
2861 This is the key length of a sub key. It is representable as a
2864 @item GPGME_ATTR_CREATED
2865 This is the timestamp at creation time of a sub key. It is
2866 representable as a number.
2868 @item GPGME_ATTR_EXPIRE
2869 This is the expiration time of a sub key. It is representable as a
2872 @item GPGME_ATTR_OTRUST
2873 XXX FIXME (also for trust items)
2875 @item GPGME_ATTR_USERID
2876 This is a user ID. There can be more than one user IDs in a
2877 @var{gpgme_key_t} object. The first one (with index 0) is the primary
2878 user ID. The user ID is representable as a number.
2880 For trust items, this is the user ID associated with this trust item.
2882 @item GPGME_ATTR_NAME
2883 This is the name belonging to a user ID. It is representable as a string.
2885 @item GPGME_ATTR_EMAIL
2886 This is the email address belonging to a user ID. It is representable
2889 @item GPGME_ATTR_COMMENT
2890 This is the comment belonging to a user ID. It is representable as a
2893 @item GPGME_ATTR_VALIDITY
2894 This is the validity belonging to a user ID. It is representable as a
2895 string and as a number. See below for a list of available validities.
2897 For trust items, this is the validity that is associated with this
2900 @item GPGME_ATTR_UID_REVOKED
2901 This specifies if a user ID is revoked. It is representable as a
2902 number, and is @code{1} if the user ID is revoked, and @code{0}
2905 @item GPGME_ATTR_UID_INVALID
2906 This specifies if a user ID is invalid. It is representable as a
2907 number, and is @code{1} if the user ID is invalid, and @code{0}
2910 @item GPGME_ATTR_LEVEL
2911 This is the trust level of a trust item.
2913 @item GPGME_ATTR_TYPE
2914 This returns information about the type of key. For the string function
2915 this will eother be "PGP" or "X.509". The integer function returns 0
2916 for PGP and 1 for X.509. It is also used for the type of a trust item.
2918 @item GPGME_ATTR_IS_SECRET
2919 This specifies if the key is a secret key. It is representable as a
2920 number, and is @code{1} if the key is revoked, and @code{0} otherwise.
2922 @item GPGME_ATTR_KEY_REVOKED
2923 This specifies if a sub key is revoked. It is representable as a
2924 number, and is @code{1} if the key is revoked, and @code{0} otherwise.
2926 @item GPGME_ATTR_KEY_INVALID
2927 This specifies if a sub key is invalid. It is representable as a
2928 number, and is @code{1} if the key is invalid, and @code{0} otherwise.
2930 @item GPGME_ATTR_KEY_EXPIRED
2931 This specifies if a sub key is expired. It is representable as a
2932 number, and is @code{1} if the key is expired, and @code{0} otherwise.
2934 @item GPGME_ATTR_KEY_DISABLED
2935 This specifies if a sub key is disabled. It is representable as a
2936 number, and is @code{1} if the key is disabled, and @code{0} otherwise.
2938 @item GPGME_ATTR_KEY_CAPS
2939 This is a description of the capabilities of a sub key. It is
2940 representable as a string. The string contains the letter ``e'' if
2941 the key can be used for encryption, ``s'' if the key can be used for
2942 signatures, and ``c'' if the key can be used for certifications.
2944 @item GPGME_ATTR_CAN_ENCRYPT
2945 This specifies if a sub key can be used for encryption. It is
2946 representable as a number, and is @code{1} if the sub key can be used
2947 for encryption, and @code{0} otherwise.
2949 @item GPGME_ATTR_CAN_SIGN
2950 This specifies if a sub key can be used to create data signatures. It
2951 is representable as a number, and is @code{1} if the sub key can be
2952 used for signatures, and @code{0} otherwise.
2954 @item GPGME_ATTR_CAN_CERTIFY
2955 This specifies if a sub key can be used to create key certificates.
2956 It is representable as a number, and is @code{1} if the sub key can be
2957 used for certifications, and @code{0} otherwise.
2959 @item GPGME_ATTR_SERIAL
2960 The X.509 issuer serial attribute of the key. It is representable as
2963 @item GPGME_ATTR_ISSUE
2964 The X.509 issuer name attribute of the key. It is representable as a
2967 @item GPGME_ATTR_CHAINID
2968 The X.509 chain ID can be used to build the certification chain. It
2969 is representable as a string.
2973 @deftypefun {const char *} gpgme_key_get_string_attr (@w{gpgme_key_t @var{key}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
2974 The function @code{gpgme_key_get_string_attr} returns the value of the
2975 string-representable attribute @var{what} of key @var{key}. If the
2976 attribute is an attribute of a sub key or an user ID, @var{idx}
2977 specifies the sub key or user ID of which the attribute value is
2978 returned. The argument @var{reserved} is reserved for later use and
2979 should be @code{NULL}.
2981 The string returned is only valid as long as the key is valid.
2983 The function returns @code{0} if an attribute can't be returned as a
2984 string, @var{key} is not a valid pointer, @var{idx} out of range,
2985 or @var{reserved} not @code{NULL}.
2988 @deftypefun {unsigned long} gpgme_key_get_ulong_attr (@w{gpgme_key_t @var{key}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
2989 The function @code{gpgme_key_get_ulong_attr} returns the value of the
2990 number-representable attribute @var{what} of key @var{key}. If the
2991 attribute is an attribute of a sub key or an user ID, @var{idx}
2992 specifies the sub key or user ID of which the attribute value is
2993 returned. The argument @var{reserved} is reserved for later use and
2994 should be @code{NULL}.
2996 The function returns @code{0} if the attribute can't be returned as a
2997 number, @var{key} is not a valid pointer, @var{idx} out of range, or
2998 @var{reserved} not @code{NULL}.
3002 @node Key Signatures
3003 @subsection Key Signatures
3004 @cindex key, signatures
3005 @cindex signatures, on a key
3007 The following interfaces are deprecated and only provided for backward
3008 compatibility. Don't use them. They will be removed in a future
3009 version of @acronym{GPGME}.
3011 The signatures on a key are only available if the key was retrieved
3012 via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode
3013 enabled, because it is expensive to retrieve all signatures of a key.
3015 So, before using the below interfaces to retrieve the signatures on a
3016 key, you have to make sure that the key was listed with signatures
3017 enabled. One convenient, but blocking, way to do this is to use the
3018 function @code{gpgme_get_key}.
3020 @deftp {Data type} gpgme_attr_t
3021 The @code{gpgme_attr_t} type is used to specify a key signature
3022 attribute. The following attributes are defined:
3025 @item GPGME_ATTR_KEYID
3026 This is the key ID of the key which was used for the signature. It is
3027 representable as a string.
3029 @item GPGME_ATTR_ALGO
3030 This is the crypto algorithm used to create the signature. It is
3031 representable as a string and as a number. The numbers correspond to
3032 the @code{enum gcry_pk_algos} values in the gcrypt library.
3034 @item GPGME_ATTR_CREATED
3035 This is the timestamp at creation time of the signature. It is
3036 representable as a number.
3038 @item GPGME_ATTR_EXPIRE
3039 This is the expiration time of the signature. It is representable as
3042 @item GPGME_ATTR_USERID
3043 This is the user ID associated with the signing key. The user ID is
3044 representable as a number.
3046 @item GPGME_ATTR_NAME
3047 This is the name belonging to a user ID. It is representable as a string.
3049 @item GPGME_ATTR_EMAIL
3050 This is the email address belonging to a user ID. It is representable
3053 @item GPGME_ATTR_COMMENT
3054 This is the comment belonging to a user ID. It is representable as a
3057 @item GPGME_ATTR_KEY_REVOKED
3058 This specifies if a key signature is a revocation signature. It is
3059 representable as a number, and is @code{1} if the key is revoked, and
3062 @c @item GPGME_ATTR_KEY_EXPIRED
3063 @c This specifies if a key signature is expired. It is representable as
3064 @c a number, and is @code{1} if the key is revoked, and @code{0}
3067 @item GPGME_ATTR_SIG_CLASS
3068 This specifies the signature class of a key signature. It is
3069 representable as a number. The meaning is specific to the crypto
3072 @item GPGME_ATTR_SIG_CLASS
3073 This specifies the signature class of a key signature. It is
3074 representable as a number. The meaning is specific to the crypto
3077 @item GPGME_ATTR_SIG_STATUS
3078 This is the same value as returned by @code{gpgme_get_sig_status}.
3082 @deftypefun {const char *} gpgme_key_sig_get_string_attr (@w{gpgme_key_t @var{key}}, @w{int @var{uid_idx}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
3083 The function @code{gpgme_key_sig_get_string_attr} returns the value of
3084 the string-representable attribute @var{what} of the signature
3085 @var{idx} on the user ID @var{uid_idx} in the key @var{key}. The
3086 argument @var{reserved} is reserved for later use and should be
3089 The string returned is only valid as long as the key is valid.
3091 The function returns @code{0} if an attribute can't be returned as a
3092 string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx}
3093 out of range, or @var{reserved} not @code{NULL}.
3096 @deftypefun {unsigned long} gpgme_key_sig_get_ulong_attr (@w{gpgme_key_t @var{key}}, @w{int @var{uid_idx}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
3097 The function @code{gpgme_key_sig_get_ulong_attr} returns the value of
3098 the number-representable attribute @var{what} of the signature
3099 @var{idx} on the user ID @var{uid_idx} in the key @var{key}. The
3100 argument @var{reserved} is reserved for later use and should be
3103 The function returns @code{0} if an attribute can't be returned as a
3104 string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx}
3105 out of range, or @var{reserved} not @code{NULL}.
3109 @node Manipulating Keys
3110 @subsection Manipulating Keys
3111 @cindex key, manipulation
3113 @deftypefun void gpgme_key_ref (@w{gpgme_key_t @var{key}})
3114 The function @code{gpgme_key_ref} acquires an additional reference for
3118 @deftypefun void gpgme_key_unref (@w{gpgme_key_t @var{key}})
3119 The function @code{gpgme_key_unref} releases a reference for the key
3120 @var{key}. If this was the last reference, the key will be destroyed
3121 and all resources associated to it will be released.
3125 The following interface is deprecated and only provided for backward
3126 compatibility. Don't use it. It will be removed in a future version
3129 @deftypefun void gpgme_key_release (@w{gpgme_key_t @var{key}})
3130 The function @code{gpgme_key_release} is equivalent to
3131 @code{gpgme_key_unref}.
3135 @node Generating Keys
3136 @subsection Generating Keys
3137 @cindex key, creation
3138 @cindex key ring, add
3140 @deftypefun gpgme_error_t gpgme_op_genkey (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{parms}}, @w{gpgme_data_t @var{public}}, @w{gpgme_data_t @var{secret}})
3141 The function @code{gpgme_op_genkey} generates a new key pair in the
3142 context @var{ctx}. The meaning of @var{public} and @var{secret}
3143 depends on the crypto backend.
3145 GnuPG does not support @var{public} and @var{secret}, they should be
3146 @code{NULL}. GnuPG will generate a key pair and add it to the
3147 standard key ring. The fingerprint of the generated key is available
3148 with @code{gpgme_op_genkey_result}.
3150 GpgSM requires @var{public} to be a writable data object. GpgSM will
3151 generate a secret key (which will be stored by @command{gpg-agent},
3152 and return a certificate request in @var{public}, which then needs to
3153 be signed by the certification authority and imported before it can be
3154 used. GpgSM does not make the fingerprint available.
3156 The argument @var{parms} specifies parameters for the key in an XML
3157 string. The details about the format of @var{parms} are specific to
3158 the crypto engine used by @var{ctx}. Here is an example for GnuPG as
3162 <GnupgKeyParms format="internal">
3167 Name-Real: Joe Tester
3168 Name-Comment: with stupid passphrase
3169 Name-Email: joe@@foo.bar
3175 Here is an example for GpgSM as the crypto engine:
3178 <GnupgKeyParms format="internal">
3181 Name-DN: C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester
3182 Name-Email: joe@@foo.bar
3186 Strings should be given in UTF-8 encoding. The only format supported
3187 for now is ``internal''. The content of the @code{GnupgKeyParms}
3188 container is passed verbatim to the crypto backend. Control
3189 statements are not allowed.
3191 After the operation completed successfully, the result can be
3192 retrieved with @code{gpgme_op_genkey_result}.
3194 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3195 operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
3196 @var{parms} is not a valid XML string, @code{GPG_ERR_NOT_SUPPORTED} if
3197 @var{public} or @var{secret} is not valid, and @code{GPG_ERR_GENERAL}
3198 if no key was created by the backend.
3201 @deftypefun gpgme_error_t gpgme_op_genkey_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{parms}}, @w{gpgme_data_t @var{public}}, @w{gpgme_data_t @var{secret}})
3202 The function @code{gpgme_op_genkey_start} initiates a
3203 @code{gpgme_op_genkey} operation. It can be completed by calling
3204 @code{gpgme_wait} on the context. @xref{Waiting For Completion}.
3206 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3207 operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
3208 @var{parms} is not a valid XML string, and
3209 @code{GPG_ERR_NOT_SUPPORTED} if @var{public} or @var{secret} is not
3213 @deftp {Data type} {gpgme_genkey_result_t}
3214 This is a pointer to a structure used to store the result of a
3215 @code{gpgme_op_genkey} operation. After successfully generating a
3216 key, you can retrieve the pointer to the result with
3217 @code{gpgme_op_genkey_result}. The structure contains the following
3221 @item unsigned int primary : 1
3222 This is a flag that is set to 1 if a primary key was created and to 0
3225 @item unsigned int sub : 1
3226 This is a flag that is set to 1 if a subkey was created and to 0
3230 This is the fingerprint of the key that was created. If both a
3231 primary and a sub key were generated, the fingerprint of the primary
3232 key will be returned. If the crypto engine does not provide the
3233 fingerprint, @code{fpr} will be a null pointer.
3237 @deftypefun gpgme_genkey_result_t gpgme_op_genkey_result (@w{gpgme_ctx_t @var{ctx}})
3238 The function @code{gpgme_op_genkey_result} returns a
3239 @code{gpgme_genkey_result_t} pointer to a structure holding the result of
3240 a @code{gpgme_op_genkey} operation. The pointer is only valid if the
3241 last operation on the context was a @code{gpgme_op_genkey} or
3242 @code{gpgme_op_genkey_start} operation, and if this operation finished
3243 successfully. The returned pointer is only valid until the next
3244 operation is started on the context.
3248 @node Exporting Keys
3249 @subsection Exporting Keys
3251 @cindex key ring, export from
3253 @deftypefun gpgme_error_t gpgme_op_export (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{unsigned int @var{reserved}}, @w{gpgme_data_t @var{keydata}})
3254 The function @code{gpgme_op_export} extracts public keys and returns
3255 them in the data buffer @var{keydata}. The output format of the key
3256 data returned is determined by the @acronym{ASCII} armor attribute set
3257 for the context @var{ctx}.
3259 If @var{pattern} is @code{NULL}, all available keys are returned.
3260 Otherwise, @var{pattern} contains an engine specific expression that
3261 is used to limit the list to all keys matching the pattern.
3263 @var{reserved} is reserved for future use and must be @code{0}.
3265 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3266 operation completed successfully, @code{GPG_ERR_INV_VALUE} if
3267 @var{keydata} is not a valid empty data buffer, and passes through any
3268 errors that are reported by the crypto engine support routines.
3271 @deftypefun gpgme_error_t gpgme_op_export_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{unsigned int @var{reserved}}, @w{gpgme_data_t @var{keydata}})
3272 The function @code{gpgme_op_export_start} initiates a
3273 @code{gpgme_op_export} operation. It can be completed by calling
3274 @code{gpgme_wait} on the context. @xref{Waiting For Completion}.
3276 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3277 operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
3278 if @var{keydata} is not a valid empty data buffer.
3281 @deftypefun gpgme_error_t gpgme_op_export_ext (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}[]}, @w{unsigned int @var{reserved}}, @w{gpgme_data_t @var{keydata}})
3282 The function @code{gpgme_op_export} extracts public keys and returns
3283 them in the data buffer @var{keydata}. The output format of the key
3284 data returned is determined by the @acronym{ASCII} armor attribute set
3285 for the context @var{ctx}.
3287 If @var{pattern} or @var{*pattern} is @code{NULL}, all available keys
3288 are returned. Otherwise, @var{pattern} is a @code{NULL} terminated
3289 array of strings that are used to limit the list to all keys matching
3290 at least one of the patterns verbatim.
3292 @var{reserved} is reserved for future use and must be @code{0}.
3294 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3295 operation completed successfully, @code{GPG_ERR_INV_VALUE} if
3296 @var{keydata} is not a valid empty data buffer, and passes through any
3297 errors that are reported by the crypto engine support routines.
3300 @deftypefun gpgme_error_t gpgme_op_export_ext_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}[]}, @w{unsigned int @var{reserved}}, @w{gpgme_data_t @var{keydata}})
3301 The function @code{gpgme_op_export_ext_start} initiates a
3302 @code{gpgme_op_export_ext} operation. It can be completed by calling
3303 @code{gpgme_wait} on the context. @xref{Waiting For Completion}.
3305 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3306 operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
3307 if @var{keydata} is not a valid empty data buffer.
3311 @node Importing Keys
3312 @subsection Importing Keys
3314 @cindex key ring, import to
3316 @deftypefun gpgme_error_t gpgme_op_import (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}})
3317 The function @code{gpgme_op_import} adds the keys in the data buffer
3318 @var{keydata} to the key ring of the crypto engine used by @var{ctx}.
3319 The format of @var{keydata} can be @acronym{ASCII} armored, for example,
3320 but the details are specific to the crypto engine.
3322 After the operation completed successfully, the result can be
3323 retrieved with @code{gpgme_op_import_result}.
3325 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3326 import was completed successfully, @code{GPG_ERR_INV_VALUE} if
3327 @var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer,
3328 and @code{GPG_ERR_NO_DATA} if @var{keydata} is an empty data buffer.
3331 @deftypefun gpgme_error_t gpgme_op_import_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}})
3332 The function @code{gpgme_op_import_start} initiates a
3333 @code{gpgme_op_import} operation. It can be completed by calling
3334 @code{gpgme_wait} on the context. @xref{Waiting For Completion}.
3336 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3337 import could be started successfully, @code{GPG_ERR_INV_VALUE} if
3338 @var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer,
3339 and @code{GPG_ERR_NO_DATA} if @var{keydata} is an empty data buffer.
3342 @deftp {Data type} {gpgme_import_status_t}
3343 This is a pointer to a structure used to store a part of the result of
3344 a @code{gpgme_op_import} operation. For each considered key one
3345 status is added that contains information about the result of the
3346 import. The structure contains the following members:
3349 @item gpgme_import_status_t next
3350 This is a pointer to the next status structure in the linked list, or
3351 @code{NULL} if this is the last element.
3354 This is the fingerprint of the key that was considered.
3356 @item gpgme_error_t result
3357 If the import was not successful, this is the error value that caused
3358 the import to fail. Otherwise the error code is
3359 @code{GPG_ERR_NO_ERROR}.
3361 @item unsigned int status
3362 This is a bit-wise OR of the following flags that give more
3363 information about what part of the key was imported. If the key was
3364 already known, this might be 0.
3367 @item GPGME_IMPORT_NEW
3370 @item GPGME_IMPORT_UID
3371 The key contained new user IDs.
3373 @item GPGME_IMPORT_SIG
3374 The key contained new signatures.
3376 @item GPGME_IMPORT_SUBKEY
3377 The key contained new sub keys.
3379 @item GPGME_IMPORT_SECRET
3380 The key contained a secret key.
3385 @deftp {Data type} {gpgme_import_result_t}
3386 This is a pointer to a structure used to store the result of a
3387 @code{gpgme_op_import} operation. After a successful import
3388 operation, you can retrieve the pointer to the result with
3389 @code{gpgme_op_import_result}. The structure contains the following
3393 @item int considered
3394 The total number of considered keys.
3396 @item int no_user_id
3397 The number of keys without user ID.
3400 The total number of imported keys.
3403 The number of imported RSA keys.
3406 The number of unchanged keys.
3409 The number of new user IDs.
3412 The number of new sub keys.
3414 @item new_signatures
3415 The number of new signatures.
3417 @item new_revocations
3418 The number of new revocations.
3421 The total number of secret keys read.
3423 @item secret_imported
3424 The number of imported secret keys.
3426 @item secret_unchanged
3427 The number of unchanged secret keys.
3430 The number of keys not imported.
3432 @item gpgme_import_status_t imports
3433 A list of gpgme_import_status_t objects which contain more information
3434 about the keys for which an import was attempted.
3438 @deftypefun gpgme_import_result_t gpgme_op_import_result (@w{gpgme_ctx_t @var{ctx}})
3439 The function @code{gpgme_op_import_result} returns a
3440 @code{gpgme_import_result_t} pointer to a structure holding the result
3441 of a @code{gpgme_op_import} operation. The pointer is only valid if
3442 the last operation on the context was a @code{gpgme_op_import} or
3443 @code{gpgme_op_import_start} operation, and if this operation finished
3444 successfully. The returned pointer is only valid until the next
3445 operation is started on the context.
3448 The following interface is deprecated and only provided for backward
3449 compatibility. Don't use it. It will be removed in a future version
3452 @deftypefun gpgme_error_t gpgme_op_import_ext (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}}, @w{int *@var{nr}})
3453 The function @code{gpgme_op_import_ext} is equivalent to:
3456 gpgme_error_t err = gpgme_op_import (ctx, keydata);
3459 gpgme_import_result_t result = gpgme_op_import_result (ctx);
3460 *nr = result->considered;
3467 @subsection Deleting Keys
3469 @cindex key ring, delete from
3471 @deftypefun gpgme_error_t gpgme_op_delete (@w{gpgme_ctx_t @var{ctx}}, @w{const gpgme_key_t @var{key}}, @w{int @var{allow_secret}})
3472 The function @code{gpgme_op_delete} deletes the key @var{key} from the
3473 key ring of the crypto engine used by @var{ctx}. If
3474 @var{allow_secret} is @code{0}, only public keys are deleted,
3475 otherwise secret keys are deleted as well, if that is supported.
3477 The function returns the error code @code{GPG_ERR_NO_ERROR} if the key
3478 was deleted successfully, @code{GPG_ERR_INV_VALUE} if @var{ctx} or
3479 @var{key} is not a valid pointer, @code{GPG_ERR_NO_PUBKEY} if
3480 @var{key} could not be found in the keyring,
3481 @code{GPG_ERR_AMBIGUOUS_NAME} if the key was not specified
3482 unambiguously, and @code{GPG_ERR_CONFLICT} if the secret key for
3483 @var{key} is available, but @var{allow_secret} is zero.
3486 @deftypefun gpgme_error_t gpgme_op_delete_start (@w{gpgme_ctx_t @var{ctx}}, @w{const gpgme_key_t @var{key}}, @w{int @var{allow_secret}})
3487 The function @code{gpgme_op_delete_start} initiates a
3488 @code{gpgme_op_delete} operation. It can be completed by calling
3489 @code{gpgme_wait} on the context. @xref{Waiting For Completion}.
3491 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3492 operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
3493 @var{ctx} or @var{key} is not a valid pointer.
3497 @node Advanced Key Editing
3498 @subsection Advanced Key Editing
3501 @deftp {Data type} {gpgme_error_t (*gpgme_edit_cb_t) (@w{void *@var{handle}}, @w{gpgme_status_code_t @var{status}}, @w{const char *@var{args}}, @w{int @var{fd}})}
3502 @tindex gpgme_edit_cb_t
3503 The @code{gpgme_edit_cb_t} type is the type of functions which
3504 @acronym{GPGME} calls if it a key edit operation is on-going. The
3505 status code @var{status} and the argument line @var{args} are passed
3506 through by @acronym{GPGME} from the crypto engine. The file
3507 descriptor @var{fd} is -1 for normal status messages. If @var{status}
3508 indicates a command rather than a status message, the response to the
3509 command should be written to @var{fd}. The @var{handle} is provided
3510 by the user at start of operation.
3512 The function should return @code{GPG_ERR_NO_ERROR} or an error value.
3515 @deftypefun gpgme_error_t gpgme_op_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
3516 The function @code{gpgme_op_edit} processes the key @var{KEY}
3517 interactively, using the edit callback function @var{FNC} with the
3518 handle @var{HANDLE}. The callback is invoked for every status and
3519 command request from the crypto engine. The output of the crypto
3520 engine is written to the data object @var{out}.
3522 Note that the protocol between the callback function and the crypto
3523 engine is specific to the crypto engine and no further support in
3524 implementing this protocol correctly is provided by @acronym{GPGME}.
3526 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3527 edit operation completes successfully, @code{GPG_ERR_INV_VALUE} if
3528 @var{ctx} or @var{key} is not a valid pointer, and any error returned
3529 by the crypto engine or the edit callback handler.
3532 @deftypefun gpgme_error_t gpgme_op_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
3533 The function @code{gpgme_op_edit_start} initiates a
3534 @code{gpgme_op_edit} operation. It can be completed by calling
3535 @code{gpgme_wait} on the context. @xref{Waiting For Completion}.
3537 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3538 operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
3539 @var{ctx} or @var{key} is not a valid pointer.
3543 @deftypefun gpgme_error_t gpgme_op_card_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
3544 The function @code{gpgme_op_card_edit} is analogous to
3545 @code{gpgme_op_edit}, but should be used to process the smart card corresponding to the key @var{key}.
3548 @deftypefun gpgme_error_t gpgme_op_card_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
3549 The function @code{gpgme_op_card_edit_start} initiates a
3550 @code{gpgme_op_card_edit} operation. It can be completed by calling
3551 @code{gpgme_wait} on the context. @xref{Waiting For Completion}.
3553 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3554 operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
3555 @var{ctx} or @var{key} is not a valid pointer.
3559 @node Trust Item Management
3560 @section Trust Item Management
3563 @strong{Caution:} The trust items interface is experimental.
3565 @deftp {Data type} gpgme_trust_item_t
3566 The @code{gpgme_trust_item_t} type is a pointer to a trust item object.
3567 It has the following members:
3571 This is a string describing the key to which this trust items belongs.
3574 This is the type of the trust item. A value of 1 refers to a key, a
3575 value of 2 refers to a user ID.
3578 This is the trust level.
3580 @item char *owner_trust
3581 The owner trust if @code{type} is 1.
3583 @item char *validity
3584 The calculated validity.
3587 The user name if @code{type} is 2.
3592 * Listing Trust Items:: Browsing the list of available trust items.
3593 * Information About Trust Items:: Requesting information about trust items.
3594 * Manipulating Trust Items:: Operations on trust items.
3598 @node Listing Trust Items
3599 @subsection Listing Trust Items
3600 @cindex trust item list
3602 @deftypefun gpgme_error_t gpgme_op_trustlist_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{max_level}})
3603 The function @code{gpgme_op_trustlist_start} initiates a trust item
3604 listing operation inside the context @var{ctx}. It sets everything up
3605 so that subsequent invocations of @code{gpgme_op_trustlist_next} return
3606 the trust items in the list.
3608 The string @var{pattern} contains an engine specific expression that
3609 is used to limit the list to all trust items matching the pattern. It
3610 can not be the empty string.
3612 The argument @var{max_level} is currently ignored.
3614 The context will be busy until either all trust items are received
3615 (and @code{gpgme_op_trustlist_next} returns @code{GPG_ERR_EOF}), or
3616 @code{gpgme_op_trustlist_end} is called to finish the operation.
3618 The function returns the error code @code{GPG_ERR_INV_VALUE} if
3619 @var{ctx} is not a valid pointer, and passes through any errors that
3620 are reported by the crypto engine support routines.
3623 @deftypefun gpgme_error_t gpgme_op_trustlist_next (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_trust_item_t *@var{r_item}})
3624 The function @code{gpgme_op_trustlist_next} returns the next trust
3625 item in the list created by a previous @code{gpgme_op_trustlist_start}
3626 operation in the context @var{ctx}. The trust item can be destroyed
3627 with @code{gpgme_trust_item_release}. @xref{Manipulating Trust Items}.
3629 This is the only way to get at @code{gpgme_trust_item_t} objects in
3632 If the last trust item in the list has already been returned,
3633 @code{gpgme_op_trustlist_next} returns @code{GPG_ERR_EOF}.
3635 The function returns the error code @code{GPG_ERR_INV_VALUE} if @var{ctx} or
3636 @var{r_item} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if
3637 there is not enough memory for the operation.
3640 @deftypefun gpgme_error_t gpgme_op_trustlist_end (@w{gpgme_ctx_t @var{ctx}})
3641 The function @code{gpgme_op_trustlist_next} ends a pending key list
3642 operation in the context @var{ctx}.
3644 The function returns the error code @code{GPG_ERR_INV_VALUE} if
3645 @var{ctx} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if at some
3646 time during the operation there was not enough memory available.
3650 @node Information About Trust Items
3651 @subsection Information About Trust Items
3652 @cindex trust item, information about
3653 @cindex trust item, attributes
3654 @cindex attributes, of a trust item
3656 The following interfaces are deprecated and only provided for backward
3657 compatibility. Don't use them. They will be removed in a future
3658 version of @acronym{GPGME}.
3660 Trust items have attributes which can be queried using the interfaces
3661 below. The attribute identifiers are shared with those for key
3662 attributes. @xref{Information About Keys}.
3664 @deftypefun {const char *} gpgme_trust_item_get_string_attr (@w{gpgme_trust_item_t @var{item}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
3665 The function @code{gpgme_trust_item_get_string_attr} returns the value
3666 of the string-representable attribute @var{what} of trust item
3667 @var{item}. The arguments @var{idx} and @var{reserved} are reserved
3668 for later use and should be @code{0} and @code{NULL} respectively.
3670 The string returned is only valid as long as the key is valid.
3672 The function returns @code{0} if an attribute can't be returned as a
3673 string, @var{key} is not a valid pointer, @var{idx} out of range,
3674 or @var{reserved} not @code{NULL}.
3677 @deftypefun int gpgme_trust_item_get_int_attr (@w{gpgme_trust_item_t @var{item}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
3678 The function @code{gpgme_trust_item_get_int_attr} returns the value of
3679 the number-representable attribute @var{what} of trust item
3680 @var{item}. If the attribute occurs more than once in the trust item,
3681 the index is specified by @var{idx}. However, currently no such
3682 attribute exists, so @var{idx} should be @code{0}. The argument
3683 @var{reserved} is reserved for later use and should be @code{NULL}.
3685 The function returns @code{0} if the attribute can't be returned as a
3686 number, @var{key} is not a valid pointer, @var{idx} out of range,
3687 or @var{reserved} not @code{NULL}.
3691 @node Manipulating Trust Items
3692 @subsection Manipulating Trust Items
3693 @cindex trust item, manipulation
3695 @deftypefun void gpgme_trust_item_ref (@w{gpgme_trust_item_t @var{item}})
3696 The function @code{gpgme_trust_item_ref} acquires an additional
3697 reference for the trust item @var{item}.
3700 @deftypefun void gpgme_trust_item_unref (@w{gpgme_trust_item_t @var{item}})
3701 The function @code{gpgme_trust_item_unref} releases a reference for
3702 the trust item @var{item}. If this was the last reference, the trust
3703 item will be destroyed and all resources associated to it will be
3708 The following interface is deprecated and only provided for backward
3709 compatibility. Don't use it. It will be removed in a future version
3712 @deftypefun void gpgme_trust_item_release (@w{gpgme_trust_item_t @var{item}})
3713 The function @code{gpgme_trust_item_release} is an alias for
3714 @code{gpgme_trust_item_unref}.
3718 @node Crypto Operations
3719 @section Crypto Operations
3720 @cindex cryptographic operation
3722 Sometimes, the result of a crypto operation returns a list of invalid
3723 keys encountered in processing the request. The following structure
3724 is used to hold information about such a key.
3726 @deftp {Data type} {gpgme_invalid_key_t}
3727 This is a pointer to a structure used to store a part of the result of
3728 a crypto operation which takes user IDs as one input parameter. The
3729 structure contains the following members:
3732 @item gpgme_invalid_key_t next
3733 This is a pointer to the next invalid key structure in the linked
3734 list, or @code{NULL} if this is the last element.
3737 The fingerprint or key ID of the invalid key encountered.
3739 @item gpgme_error_t reason
3740 An error code describing the reason why the key was found invalid.
3746 * Decrypt:: Decrypting a ciphertext.
3747 * Verify:: Verifying a signature.
3748 * Decrypt and Verify:: Decrypting a signed ciphertext.
3749 * Sign:: Creating a signature.
3750 * Encrypt:: Encrypting a plaintext.
3757 @cindex cryptographic operation, decryption
3759 @deftypefun gpgme_error_t gpgme_op_decrypt (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
3760 The function @code{gpgme_op_decrypt} decrypts the ciphertext in the
3761 data object @var{cipher} and stores it into the data object
3764 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3765 ciphertext could be decrypted successfully, @code{GPG_ERR_INV_VALUE}
3766 if @var{ctx}, @var{cipher} or @var{plain} is not a valid pointer,
3767 @code{GPG_ERR_NO_DATA} if @var{cipher} does not contain any data to
3768 decrypt, @code{GPG_ERR_DECRYPT_FAILED} if @var{cipher} is not a valid
3769 cipher text, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the
3770 secret key could not be retrieved, and passes through any errors that
3771 are reported by the crypto engine support routines.
3774 @deftypefun gpgme_error_t gpgme_op_decrypt_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
3775 The function @code{gpgme_op_decrypt_start} initiates a
3776 @code{gpgme_op_decrypt} operation. It can be completed by calling
3777 @code{gpgme_wait} on the context. @xref{Waiting For Completion}.
3779 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3780 operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
3781 if @var{cipher} or @var{plain} is not a valid pointer.
3784 @deftp {Data type} {gpgme_recipient_t}
3785 This is a pointer to a structure used to store information about the
3786 recipient of an encrypted text which is decrypted in a
3787 @code{gpgme_op_decrypt} operation. This information (except for the
3788 status field) is even available before the operation finished
3789 successfully, for example in a passphrase callback. The structure
3790 contains the following members:
3793 @item gpgme_recipient_t next
3794 This is a pointer to the next recipient structure in the linked list,
3795 or @code{NULL} if this is the last element.
3797 @item gpgme_pubkey_algo_t
3798 The public key algorithm used in the encryption.
3800 @item unsigned int wrong_key_usage : 1
3801 This is true if the key was not used according to its policy.
3804 This is the key ID of the key (in hexadecimal digits) used as
3807 @item gpgme_error_t status
3808 This is an error number with the error code GPG_ERR_NO_SECKEY if the
3809 secret key for this recipient is not available, and 0 otherwise.
3813 @deftp {Data type} {gpgme_decrypt_result_t}
3814 This is a pointer to a structure used to store the result of a
3815 @code{gpgme_op_decrypt} operation. After successfully decrypting
3816 data, you can retrieve the pointer to the result with
3817 @code{gpgme_op_decrypt_result}. The structure contains the following
3821 @item char *unsupported_algorithm
3822 If an unsupported algorithm was encountered, this string describes the
3823 algorithm that is not supported.
3825 @item unsigned int wrong_key_usage : 1
3826 This is true if the key was not used according to its policy.
3828 @item gpgme_recipient_t recipient
3829 This is a linked list of recipients to which this message was encrypted.
3831 @item char *file_name
3832 This is the filename of the original plaintext message file if it is
3833 known, otherwise this is a null pointer.
3837 @deftypefun gpgme_decrypt_result_t gpgme_op_decrypt_result (@w{gpgme_ctx_t @var{ctx}})
3838 The function @code{gpgme_op_decrypt_result} returns a
3839 @code{gpgme_decrypt_result_t} pointer to a structure holding the
3840 result of a @code{gpgme_op_decrypt} operation. The pointer is only
3841 valid if the last operation on the context was a
3842 @code{gpgme_op_decrypt} or @code{gpgme_op_decrypt_start} operation.
3843 If the operation failed this might be a @code{NULL} pointer. The
3844 returned pointer is only valid until the next operation is started on
3851 @cindex verification
3852 @cindex signature, verification
3853 @cindex cryptographic operation, verification
3854 @cindex cryptographic operation, signature check
3855 @cindex signature notation data
3856 @cindex notation data
3858 @deftypefun gpgme_error_t gpgme_op_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{sig}}, @w{gpgme_data_t @var{signed_text}}, @w{gpgme_data_t @var{plain}})
3859 The function @code{gpgme_op_verify} verifies that the signature in the
3860 data object @var{sig} is a valid signature. If @var{sig} is a
3861 detached signature, then the signed text should be provided in
3862 @var{signed_text} and @var{plain} should be a null pointer.
3863 Otherwise, if @var{sig} is a normal (or cleartext) signature,
3864 @var{signed_text} should be a null pointer and @var{plain} should be a
3865 writable data object that will contain the plaintext after successful
3868 The results of the individual signature verifications can be retrieved
3869 with @code{gpgme_op_verify_result}.
3871 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3872 operation could be completed successfully, @code{GPG_ERR_INV_VALUE} if
3873 @var{ctx}, @var{sig} or @var{plain} is not a valid pointer,
3874 @code{GPG_ERR_NO_DATA} if @var{sig} does not contain any data to
3875 verify, and passes through any errors that are reported by the crypto
3876 engine support routines.
3879 @deftypefun gpgme_error_t gpgme_op_verify_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{sig}}, @w{gpgme_data_t @var{signed_text}}, @w{gpgme_data_t @var{plain}})
3880 The function @code{gpgme_op_verify_start} initiates a
3881 @code{gpgme_op_verify} operation. It can be completed by calling
3882 @code{gpgme_wait} on the context. @xref{Waiting For Completion}.
3884 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3885 operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
3886 @var{ctx}, @var{sig} or @var{plain} is not a valid pointer, and
3887 @code{GPG_ERR_NO_DATA} if @var{sig} or @var{plain} does not contain
3891 @deftp {Data type} {gpgme_sig_notation_t}
3892 This is a pointer to a structure used to store a part of the result of
3893 a @code{gpgme_op_verify} operation. The structure contains the
3897 @item gpgme_sig_notation_t next
3898 This is a pointer to the next new signature notation structure in the
3899 linked list, or @code{NULL} if this is the last element.
3902 The name of the notation field. If this is @code{NULL}, then the
3903 member @code{value} will contain a policy URL.
3906 The length of the @code{name} field. For strings the length is
3907 counted without the trailing binary zero.
3910 The value of the notation field. If @code{name} is @code{NULL}, then
3911 this is a policy URL.
3914 The length of the @code{value} field. For strings the length is
3915 counted without the trailing binary zero.
3917 @item gpgme_sig_notation_flags_t flags
3918 The accumulated flags field. This field contains the flags associated
3919 with the notation data in an accumulated form which can be used as an
3920 argument to the function @code{gpgme_sig_notation_add}. The value
3921 @code{flags} is a bitwise-or combination of one or multiple of the
3922 following bit values:
3925 @item GPGME_SIG_NOTATION_HUMAN_READABLE
3926 The @code{GPGME_SIG_NOTATION_HUMAN_READABLE} symbol specifies that the
3927 notation data is in human readable form
3929 @item GPGME_SIG_NOTATION_CRITICAL
3930 The @code{GPGME_SIG_NOTATION_CRITICAL} symbol specifies that the
3931 notation data is critical.
3935 @item unsigned int human_readable : 1
3936 This is true if the @code{GPGME_SIG_NOTATION_HUMAN_READABLE} flag is
3937 set and false otherwise. This flag is only valid for notation data,
3938 not for policy URLs.
3940 @item unsigned int critical : 1
3941 This is true if the @code{GPGME_SIG_NOTATION_CRITICAL} flag is set and
3942 false otherwise. This flag is valid for notation data and policy URLs.
3947 @deftp {Data type} {gpgme_signature_t}
3948 This is a pointer to a structure used to store a part of the result of
3949 a @code{gpgme_op_verify} operation. The structure contains the
3953 @item gpgme_signature_t next
3954 This is a pointer to the next new signature structure in the linked
3955 list, or @code{NULL} if this is the last element.
3957 @item gpgme_sigsum_t summary
3958 This is a bit vector giving a summary of the signature status. It
3959 provides an easy interface to a defined semantic of the signature
3960 status. Checking just one bit is sufficient to see whether a
3961 signature is valid without any restrictions.
3963 The defined bits are:
3965 @item GPGME_SIGSUM_VALID
3966 The signature is fully valid.
3968 @item GPGME_SIGSUM_GREEN
3969 The signature is good but one might want to display some extra
3970 information. Check the other bits.
3972 @item GPGME_SIGSUM_RED
3973 The signature is bad. It might be useful to check other bits and
3974 display more information, i.e. a revoked certificate might not render a
3975 signature invalid when the message was received prior to the cause for
3978 @item GPGME_SIGSUM_KEY_REVOKED
3979 The key or at least one certificate has been revoked.
3981 @item GPGME_SIGSUM_KEY_EXPIRED
3982 The key or one of the certificates has expired. It is probably a good
3983 idea to display the date of the expiration.
3985 @item GPGME_SIGSUM_SIG_EXPIRED
3986 The signature has expired.
3988 @item GPGME_SIGSUM_KEY_MISSING
3989 Can't verify due to a missing key or certificate.
3991 @item GPGME_SIGSUM_CRL_MISSING
3992 The CRL (or an equivalent mechanism) is not available.
3994 @item GPGME_SIGSUM_CRL_TOO_OLD
3995 Available CRL is too old.
3997 @item GPGME_SIGSUM_BAD_POLICY
3998 A policy requirement was not met.
4000 @item GPGME_SIGSUM_SYS_ERROR
4001 A system error occured.
4005 This is the fingerprint or key ID of the signature.
4007 @item gpgme_error_t status
4008 This is the status of the signature. In particular, the following
4009 status codes are of interest:
4012 @item GPG_ERR_NO_ERROR
4013 This status indicates that the signature is valid. For the combined
4014 result this status means that all signatures are valid.
4016 @item GPG_ERR_SIG_EXPIRED
4017 This status indicates that the signature is valid but expired. For
4018 the combined result this status means that all signatures are valid
4021 @item GPG_ERR_KEY_EXPIRED
4022 This status indicates that the signature is valid but the key used to
4023 verify the signature has expired. For the combined result this status
4024 means that all signatures are valid and all keys are expired.
4026 @item GPG_ERR_CERT_REVOKED
4027 This status indicates that the signature is valid but the key used
4028 to verify the signature has been revoked. For the combined result
4029 this status means that all signatures are valid and all keys are
4032 @item GPG_ERR_BAD_SIGNATURE
4033 This status indicates that the signature is invalid. For the combined
4034 result this status means that all signatures are invalid.
4036 @item GPG_ERR_NO_PUBKEY
4037 This status indicates that the signature could not be verified due to
4038 a missing key. For the combined result this status means that all
4039 signatures could not be checked due to missing keys.
4041 @item GPG_ERR_GENERAL
4042 This status indicates that there was some other error which prevented
4043 the signature verification.
4046 @item gpgme_sig_notation_t notations
4047 This is a linked list with the notation data and policy URLs.
4049 @item unsigned long timestamp
4050 The creation timestamp of this signature.
4052 @item unsigned long exp_timestamp
4053 The expiration timestamp of this signature, or 0 if the signature does
4056 @item unsigned int wrong_key_usage : 1
4057 This is true if the key was not used according to its policy.
4059 @item unsigned int pka_trust : 2
4060 This is set to the trust information gained by means of the PKA system.
4064 No PKA information available or verification not possible.
4066 PKA verification failed.
4068 PKA verification succeeded.
4070 Reserved for future use.
4072 Depending on the configuration of the engine, this metric may also be
4073 reflected by the validity of the signature.
4075 @item gpgme_validity_t validity
4076 The validity of the signature.
4078 @item gpgme_error_t validity_reason
4079 If a signature is not valid, this provides a reason why.
4081 @item gpgme_pubkey_algo_t
4082 The public key algorithm used to create this signature.
4084 @item gpgme_hash_algo_t
4085 The hash algorithm used to create this signature.
4089 @deftp {Data type} {gpgme_verify_result_t}
4090 This is a pointer to a structure used to store the result of a
4091 @code{gpgme_op_verify} operation. After verifying a signature, you
4092 can retrieve the pointer to the result with
4093 @code{gpgme_op_verify_result}. If the operation failed this might be
4094 a @code{NULL} pointer. The structure contains the following member:
4097 @item gpgme_signature_t signatures
4098 A linked list with information about all signatures for which a
4099 verification was attempted.
4101 @item char *file_name
4102 This is the filename of the original plaintext message file if it is
4103 known, otherwise this is a null pointer.
4107 @deftypefun gpgme_verify_result_t gpgme_op_verify_result (@w{gpgme_ctx_t @var{ctx}})
4108 The function @code{gpgme_op_verify_result} returns a
4109 @code{gpgme_verify_result_t} pointer to a structure holding the result
4110 of a @code{gpgme_op_verify} operation. The pointer is only valid if
4111 the last operation on the context was a @code{gpgme_op_verify},
4112 @code{gpgme_op_verify_start}, @code{gpgme_op_decrypt_verify} or
4113 @code{gpgme_op_decrypt_verify_start} operation, and if this operation
4114 finished successfully (for @code{gpgme_op_decrypt_verify} and
4115 @code{gpgme_op_decrypt_verify_start}, the error code
4116 @code{GPG_ERR_NO_DATA} counts as successful in this context). The
4117 returned pointer is only valid until the next operation is started on
4122 The following interfaces are deprecated and only provided for backward
4123 compatibility. Don't use them. They will be removed in a future
4124 version of @acronym{GPGME}.
4126 @deftp {Data type} {enum gpgme_sig_stat_t}
4127 @tindex gpgme_sig_stat_t
4128 The @code{gpgme_sig_stat_t} type holds the result of a signature check, or
4129 the combined result of all signatures. The following results are
4133 @item GPGME_SIG_STAT_NONE
4134 This status should not occur in normal operation.
4136 @item GPGME_SIG_STAT_GOOD
4137 This status indicates that the signature is valid. For the combined
4138 result this status means that all signatures are valid.
4140 @item GPGME_SIG_STAT_GOOD_EXP
4141 This status indicates that the signature is valid but expired. For
4142 the combined result this status means that all signatures are valid
4145 @item GPGME_SIG_STAT_GOOD_EXPKEY
4146 This status indicates that the signature is valid but the key used to
4147 verify the signature has expired. For the combined result this status
4148 means that all signatures are valid and all keys are expired.
4150 @item GPGME_SIG_STAT_BAD
4151 This status indicates that the signature is invalid. For the combined
4152 result this status means that all signatures are invalid.
4154 @item GPGME_SIG_STAT_NOKEY
4155 This status indicates that the signature could not be verified due to
4156 a missing key. For the combined result this status means that all
4157 signatures could not be checked due to missing keys.
4159 @item GPGME_SIG_STAT_NOSIG
4160 This status indicates that the signature data provided was not a real
4163 @item GPGME_SIG_STAT_ERROR
4164 This status indicates that there was some other error which prevented
4165 the signature verification.
4167 @item GPGME_SIG_STAT_DIFF
4168 For the combined result this status means that at least two signatures
4169 have a different status. You can get each key's status with
4170 @code{gpgme_get_sig_status}.
4174 @deftypefun {const char *} gpgme_get_sig_status (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_sig_stat_t *@var{r_stat}}, @w{time_t *@var{r_created}})
4175 The function @code{gpgme_get_sig_status} is equivalent to:
4178 gpgme_verify_result_t result;
4179 gpgme_signature_t sig;
4181 result = gpgme_op_verify_result (ctx);
4182 sig = result->signatures;
4194 switch (gpg_err_code (sig->status))
4196 case GPG_ERR_NO_ERROR:
4197 *r_stat = GPGME_SIG_STAT_GOOD;
4200 case GPG_ERR_BAD_SIGNATURE:
4201 *r_stat = GPGME_SIG_STAT_BAD;
4204 case GPG_ERR_NO_PUBKEY:
4205 *r_stat = GPGME_SIG_STAT_NOKEY;
4208 case GPG_ERR_NO_DATA:
4209 *r_stat = GPGME_SIG_STAT_NOSIG;
4212 case GPG_ERR_SIG_EXPIRED:
4213 *r_stat = GPGME_SIG_STAT_GOOD_EXP;
4216 case GPG_ERR_KEY_EXPIRED:
4217 *r_stat = GPGME_SIG_STAT_GOOD_EXPKEY;
4221 *r_stat = GPGME_SIG_STAT_ERROR;
4226 *r_created = sig->timestamp;
4231 @deftypefun {const char *} gpgme_get_sig_string_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{what}}, @w{int @var{whatidx}})
4232 The function @code{gpgme_get_sig_string_attr} is equivalent to:
4235 gpgme_verify_result_t result;
4236 gpgme_signature_t sig;
4238 result = gpgme_op_verify_result (ctx);
4239 sig = result->signatures;
4251 case GPGME_ATTR_FPR:
4254 case GPGME_ATTR_ERRTOK:
4256 return sig->wrong_key_usage ? "Wrong_Key_Usage" : "";
4267 @deftypefun {const char *} gpgme_get_sig_ulong_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{waht}}, @w{int @var{whatidx}})
4268 The function @code{gpgme_get_sig_ulong_attr} is equivalent to:
4271 gpgme_verify_result_t result;
4272 gpgme_signature_t sig;
4274 result = gpgme_op_verify_result (ctx);
4275 sig = result->signatures;
4287 case GPGME_ATTR_CREATED:
4288 return sig->timestamp;
4290 case GPGME_ATTR_EXPIRE:
4291 return sig->exp_timestamp;
4293 case GPGME_ATTR_VALIDITY:
4294 return (unsigned long) sig->validity;
4296 case GPGME_ATTR_SIG_STATUS:
4297 switch (sig->status)
4299 case GPG_ERR_NO_ERROR:
4300 return GPGME_SIG_STAT_GOOD;
4302 case GPG_ERR_BAD_SIGNATURE:
4303 return GPGME_SIG_STAT_BAD;
4305 case GPG_ERR_NO_PUBKEY:
4306 return GPGME_SIG_STAT_NOKEY;
4308 case GPG_ERR_NO_DATA:
4309 return GPGME_SIG_STAT_NOSIG;
4311 case GPG_ERR_SIG_EXPIRED:
4312 return GPGME_SIG_STAT_GOOD_EXP;
4314 case GPG_ERR_KEY_EXPIRED:
4315 return GPGME_SIG_STAT_GOOD_EXPKEY;
4318 return GPGME_SIG_STAT_ERROR;
4321 case GPGME_ATTR_SIG_SUMMARY:
4322 return sig->summary;
4331 @deftypefun {const char *} gpgme_get_sig_key (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_key_t *@var{r_key}})
4332 The function @code{gpgme_get_sig_key} is equivalent to:
4335 gpgme_verify_result_t result;
4336 gpgme_signature_t sig;
4338 result = gpgme_op_verify_result (ctx);
4339 sig = result->signatures;
4347 return gpg_error (GPG_ERR_EOF);
4349 return gpgme_get_key (ctx, sig->fpr, r_key, 0);
4354 @node Decrypt and Verify
4355 @subsection Decrypt and Verify
4356 @cindex decryption and verification
4357 @cindex verification and decryption
4358 @cindex signature check
4359 @cindex cryptographic operation, decryption and verification
4361 @deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
4362 The function @code{gpgme_op_decrypt_verify} decrypts the ciphertext in
4363 the data object @var{cipher} and stores it into the data object
4364 @var{plain}. If @var{cipher} contains signatures, they will be
4367 After the operation completed, @code{gpgme_op_decrypt_result} and
4368 @code{gpgme_op_verify_result} can be used to retrieve more information
4369 about the signatures.
4371 If the error code @code{GPG_ERR_NO_DATA} is returned, @var{cipher}
4372 does not contain any data to decrypt. However, it might still be
4373 signed. The information about detected signatures is available with
4374 @code{gpgme_op_verify_result} in this case.
4376 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
4377 ciphertext could be decrypted successfully, @code{GPG_ERR_INV_VALUE}
4378 if @var{ctx}, @var{cipher} or @var{plain} is not a valid pointer,
4379 @code{GPG_ERR_NO_DATA} if @var{cipher} does not contain any data to
4380 decrypt, @code{GPG_ERR_DECRYPT_FAILED} if @var{cipher} is not a valid
4381 cipher text, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the
4382 secret key could not be retrieved, and passes through any errors that
4383 are reported by the crypto engine support routines.
4386 @deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
4387 The function @code{gpgme_op_decrypt_verify_start} initiates a
4388 @code{gpgme_op_decrypt_verify} operation. It can be completed by
4389 calling @code{gpgme_wait} on the context. @xref{Waiting For
4392 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
4393 operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
4394 @var{ctx}, @var{cipher}, @var{plain} or @var{r_stat} is not a valid
4395 pointer, and @code{GPG_ERR_NO_DATA} if @var{cipher} does not contain
4396 any data to decrypt.
4402 @cindex signature, creation
4404 @cindex cryptographic operation, signing
4406 A signature can contain signatures by one or more keys. The set of
4407 keys used to create a signatures is contained in a context, and is
4408 applied to all following signing operations in this context (until the
4412 * Selecting Signers:: How to choose the keys to sign with.
4413 * Creating a Signature:: How to create a signature.
4414 * Signature Notation Data:: How to add notation data to a signature.
4418 @node Selecting Signers
4419 @subsubsection Selecting Signers
4420 @cindex signature, selecting signers
4421 @cindex signers, selecting
4423 @deftypefun void gpgme_signers_clear (@w{gpgme_ctx_t @var{ctx}})
4424 The function @code{gpgme_signers_clear} releases a reference for each
4425 key on the signers list and removes the list of signers from the
4428 Every context starts with an empty list.
4431 @deftypefun gpgme_error_t gpgme_signers_add (@w{gpgme_ctx_t @var{ctx}}, @w{const gpgme_key_t @var{key}})
4432 The function @code{gpgme_signers_add} adds the key @var{key} to the
4433 list of signers in the context @var{ctx}.
4435 Calling this function acquires an additional reference for the key.
4438 @deftypefun gpgme_key_t gpgme_signers_enum (@w{const gpgme_ctx_t @var{ctx}}, @w{int @var{seq}})
4439 The function @code{gpgme_signers_enum} returns the @var{seq}th key in
4440 the list of signers in the context @var{ctx}. An additional reference
4441 is acquired for the user.
4443 If @var{seq} is out of range, @code{NULL} is returned.
4447 @node Creating a Signature
4448 @subsubsection Creating a Signature
4450 @deftp {Data type} {enum gpgme_sig_mode_t}
4451 @tindex gpgme_sig_mode_t
4452 The @code{gpgme_sig_mode_t} type is used to specify the desired type of a
4453 signature. The following modes are available:
4456 @item GPGME_SIG_MODE_NORMAL
4457 A normal signature is made, the output includes the plaintext and the
4460 @item GPGME_SIG_MODE_DETACH
4461 A detached signature is made.
4463 @item GPGME_SIG_MODE_CLEAR
4464 A clear text signature is made. The @acronym{ASCII} armor and text
4465 mode settings of the context are ignored.
4469 @deftypefun gpgme_error_t gpgme_op_sign (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{sig}}, @w{gpgme_sig_mode_t @var{mode}})
4470 The function @code{gpgme_op_sign} creates a signature for the text in
4471 the data object @var{plain} and returns it in the data object
4472 @var{sig}. The type of the signature created is determined by the
4473 @acronym{ASCII} armor and text mode attributes set for the context
4474 @var{ctx} and the requested signature mode @var{mode}.
4476 After the operation completed successfully, the result can be
4477 retrieved with @code{gpgme_op_sign_result}.
4479 If an S/MIME signed message is created using the CMS crypto engine,
4480 the number of certificates to include in the message can be specified
4481 with @code{gpgme_set_include_certs}. @xref{Included Certificates}.
4483 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
4484 signature could be created successfully, @code{GPG_ERR_INV_VALUE} if
4485 @var{ctx}, @var{plain} or @var{sig} is not a valid pointer,
4486 @code{GPG_ERR_NO_DATA} if the signature could not be created,
4487 @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the secret key
4488 could not be retrieved, @code{GPG_ERR_UNUSABLE_SECKEY} if there are
4489 invalid signers, and passes through any errors that are reported by the
4490 crypto engine support routines.
4493 @deftypefun gpgme_error_t gpgme_op_sign_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{sig}}, @w{gpgme_sig_mode_t @var{mode}})
4494 The function @code{gpgme_op_sign_start} initiates a
4495 @code{gpgme_op_sign} operation. It can be completed by calling
4496 @code{gpgme_wait} on the context. @xref{Waiting For Completion}.
4498 The function returns the error code @code{GPG_ERR_NO_ERROR} if the operation could be
4499 started successfully, and @code{GPG_ERR_INV_VALUE} if @var{ctx},
4500 @var{plain} or @var{sig} is not a valid pointer.
4503 @deftp {Data type} {gpgme_new_signature_t}
4504 This is a pointer to a structure used to store a part of the result of
4505 a @code{gpgme_op_sign} operation. The structure contains the
4509 @item gpgme_new_signature_t next
4510 This is a pointer to the next new signature structure in the linked
4511 list, or @code{NULL} if this is the last element.
4513 @item gpgme_sig_mode_t type
4514 The type of this signature.
4516 @item gpgme_pubkey_algo_t
4517 The public key algorithm used to create this signature.
4519 @item gpgme_hash_algo_t
4520 The hash algorithm used to create this signature.
4522 @item unsigned int sig_class
4523 The signature class of this signature.
4525 @item long int timestamp
4526 The creation timestamp of this signature.
4529 The fingerprint of the key which was used to create this signature.
4533 @deftp {Data type} {gpgme_sign_result_t}
4534 This is a pointer to a structure used to store the result of a
4535 @code{gpgme_op_sign} operation. After successfully generating a
4536 signature, you can retrieve the pointer to the result with
4537 @code{gpgme_op_sign_result}. The structure contains the following
4541 @item gpgme_invalid_key_t invalid_signers
4542 A linked list with information about all invalid keys for which a
4543 signature could not be created.
4545 @item gpgme_new_signature_t signatures
4546 A linked list with information about all signatures created.
4550 @deftypefun gpgme_sign_result_t gpgme_op_sign_result (@w{gpgme_ctx_t @var{ctx}})
4551 The function @code{gpgme_op_sign_result} returns a
4552 @code{gpgme_sign_result_t} pointer to a structure holding the result
4553 of a @code{gpgme_op_sign} operation. The pointer is only valid if the
4554 last operation on the context was a @code{gpgme_op_sign},
4555 @code{gpgme_op_sign_start}, @code{gpgme_op_encrypt_sign} or
4556 @code{gpgme_op_encrypt_sign_start} operation. If that operation
4557 failed, the function might return a @code{NULL} pointer, The returned
4558 pointer is only valid until the next operation is started on the
4563 @node Signature Notation Data
4564 @subsubsection Signature Notation Data
4565 @cindex notation data
4566 @cindex signature notation data
4569 Using the following functions, you can attach arbitrary notation data
4570 to a signature. This information is then available to the user when
4571 the signature is verified.
4573 @deftypefun void gpgme_sig_notation_clear (@w{gpgme_ctx_t @var{ctx}})
4574 The function @code{gpgme_sig_notation_clear} removes the notation data
4575 from the context @var{ctx}. Subsequent signing operations from this
4576 context will not include any notation data.
4578 Every context starts with an empty notation data list.
4581 @deftypefun gpgme_error_t gpgme_sig_notation_add (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{name}}, @w{const char *@var{value}}, @w{gpgme_sig_notation_flags_t @var{flags}})
4582 The function @code{gpgme_sig_notation_add} adds the notation data with
4583 the name @var{name} and the value @var{value} to the context
4586 Subsequent signing operations will include this notation data, as well
4587 as any other notation data that was added since the creation of the
4588 context or the last @code{gpgme_sig_notation_clear} operation.
4590 The arguments @var{name} and @var{value} must be @code{NUL}-terminated
4591 strings in human-readable form. The flag
4592 @code{GPGME_SIG_NOTATION_HUMAN_READABLE} is implied
4593 (non-human-readable notation data is currently not supported). The
4594 strings must be in UTF-8 encoding.
4596 If @var{name} is @code{NULL}, then @var{value} should be a policy URL.
4598 The function @code{gpgme_sig_notation_add} returns the error code
4599 @code{GPG_ERR_NO_ERROR} if the notation data could be added
4600 successfully, @code{GPG_ERR_INV_VALUE} if @var{ctx} is not a valid
4601 pointer, or if @var{name}, @var{value} and @var{flags} are an invalid
4602 combination. The function also passes through any errors that are
4603 reported by the crypto engine support routines.
4606 @deftypefun gpgme_sig_notation_t gpgme_sig_notation_get (@w{const gpgme_ctx_t @var{ctx}})
4607 The function @code{gpgme_sig_notation_get} returns the linked list of
4608 notation data structures that are contained in the context @var{ctx}.
4610 If @var{ctx} is not a valid pointer, or there is no notation data
4611 added for this context, @code{NULL} is returned.
4618 @cindex cryptographic operation, encryption
4620 One plaintext can be encrypted for several recipients at the same
4621 time. The list of recipients is created independently of any context,
4622 and then passed to the encryption operation.
4625 * Encrypting a Plaintext:: How to encrypt a plaintext.
4629 @node Encrypting a Plaintext
4630 @subsubsection Encrypting a Plaintext
4632 @deftypefun gpgme_error_t gpgme_op_encrypt (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}[]}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
4633 The function @code{gpgme_op_encrypt} encrypts the plaintext in the data
4634 object @var{plain} for the recipients @var{recp} and stores the
4635 ciphertext in the data object @var{cipher}. The type of the
4636 ciphertext created is determined by the @acronym{ASCII} armor and text
4637 mode attributes set for the context @var{ctx}.
4639 @var{key} must be a @code{NULL}-terminated array of keys. The user
4640 must keep references for all keys during the whole duration of the
4641 call (but see @code{gpgme_op_encrypt_start} for the requirements with
4642 the asynchronous variant).
4644 The value in @var{flags} is a bitwise-or combination of one or
4645 multiple of the following bit values:
4648 @item GPGME_ENCRYPT_ALWAYS_TRUST
4649 The @code{GPGME_ENCRYPT_ALWAYS_TRUST} symbol specifies that all the
4650 recipients in @var{recp} should be trusted, even if the keys do not
4651 have a high enough validity in the keyring. This flag should be used
4652 with care; in general it is not a good idea to use any untrusted keys.
4655 If @code{GPG_ERR_UNUSABLE_PUBKEY} is returned, some recipients in
4656 @var{recp} are invalid, but not all. In this case the plaintext might
4657 be encrypted for all valid recipients and returned in @var{cipher} (if
4658 this happens depends on the crypto engine). More information about
4659 the invalid recipients is available with
4660 @code{gpgme_op_encrypt_result}.
4662 If @var{recp} is @code{NULL}, symmetric rather than public key
4663 encryption is performed. Symmetrically encrypted cipher text can be
4664 deciphered with @code{gpgme_op_decrypt}. Note that in this case the
4665 crypto backend needs to retrieve a passphrase from the user.
4666 Symmetric encryption is currently only supported for the OpenPGP
4669 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
4670 ciphertext could be created successfully, @code{GPG_ERR_INV_VALUE} if
4671 @var{ctx}, @var{recp}, @var{plain} or @var{cipher} is not a valid
4672 pointer, @code{GPG_ERR_UNUSABLE_PUBKEY} if @var{recp} contains some
4673 invalid recipients, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase
4674 for the symmetric key could not be retrieved, and passes through any
4675 errors that are reported by the crypto engine support routines.
4678 @deftypefun gpgme_error_t gpgme_op_encrypt_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}[]}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
4679 The function @code{gpgme_op_encrypt_start} initiates a
4680 @code{gpgme_op_encrypt} operation. It can be completed by calling
4681 @code{gpgme_wait} on the context. @xref{Waiting For Completion}.
4683 References to the keys only need to be held for the duration of this
4684 call. The user can release its references to the keys after this
4685 function returns, even if the operation is not yet finished.
4687 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
4688 operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
4689 @var{ctx}, @var{rset}, @var{plain} or @var{cipher} is not a valid
4690 pointer, and @code{GPG_ERR_UNUSABLE_PUBKEY} if @var{rset} does not
4691 contain any valid recipients.
4694 @deftp {Data type} {gpgme_encrypt_result_t}
4695 This is a pointer to a structure used to store the result of a
4696 @code{gpgme_op_encrypt} operation. After successfully encrypting
4697 data, you can retrieve the pointer to the result with
4698 @code{gpgme_op_encrypt_result}. The structure contains the following
4702 @item gpgme_invalid_key_t invalid_recipients
4703 A linked list with information about all invalid keys for which
4704 the data could not be encrypted.
4708 @deftypefun gpgme_encrypt_result_t gpgme_op_encrypt_result (@w{gpgme_ctx_t @var{ctx}})
4709 The function @code{gpgme_op_encrypt_result} returns a
4710 @code{gpgme_encrypt_result_t} pointer to a structure holding the
4711 result of a @code{gpgme_op_encrypt} operation. The pointer is only
4712 valid if the last operation on the context was a
4713 @code{gpgme_op_encrypt}, @code{gpgme_op_encrypt_start},
4714 @code{gpgme_op_sign} or @code{gpgme_op_sign_start} operation. If this
4715 operation failed, this might be a @code{NULL} pointer. The returned
4716 pointer is only valid until the next operation is started on the
4721 @deftypefun gpgme_error_t gpgme_op_encrypt_sign (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}[]}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
4722 The function @code{gpgme_op_encrypt_sign} does a combined encrypt and
4723 sign operation. It is used like @code{gpgme_op_encrypt}, but the
4724 ciphertext also contains signatures for the signers listed in
4727 The combined encrypt and sign operation is currently only available
4728 for the OpenPGP crypto engine.
4731 @deftypefun gpgme_error_t gpgme_op_encrypt_sign_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
4732 The function @code{gpgme_op_encrypt_sign_start} initiates a
4733 @code{gpgme_op_encrypt_sign} operation. It can be completed by
4734 calling @code{gpgme_wait} on the context. @xref{Waiting For
4737 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
4738 operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
4739 if @var{ctx}, @var{rset}, @var{plain} or @var{cipher} is not a valid
4745 @section Run Control
4747 @cindex cryptographic operation, running
4749 @acronym{GPGME} supports running operations synchronously and
4750 asynchronously. You can use asynchronous operation to set up a
4751 context up to initiating the desired operation, but delay performing
4752 it to a later point.
4754 Furthermore, you can use an external event loop to control exactly
4755 when @acronym{GPGME} runs. This ensures that @acronym{GPGME} only
4756 runs when necessary and also prevents it from blocking for a long
4760 * Waiting For Completion:: Waiting until an operation is completed.
4761 * Using External Event Loops:: Advanced control over what happens when.
4762 * Cancellation:: How to end pending operations prematurely.
4766 @node Waiting For Completion
4767 @subsection Waiting For Completion
4768 @cindex cryptographic operation, wait for
4769 @cindex wait for completion
4771 @deftypefun gpgme_ctx_t gpgme_wait (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_error_t *@var{status}}, @w{int @var{hang}})
4772 The function @code{gpgme_wait} continues the pending operation within
4773 the context @var{ctx}. In particular, it ensures the data exchange
4774 between @acronym{GPGME} and the crypto backend and watches over the
4775 run time status of the backend process.
4777 If @var{hang} is true, the function does not return until the
4778 operation is completed or cancelled. Otherwise the function will not
4779 block for a long time.
4781 The error status of the finished operation is returned in @var{status}
4782 if @code{gpgme_wait} does not return @code{NULL}.
4784 The @var{ctx} argument can be @code{NULL}. In that case,
4785 @code{gpgme_wait} waits for any context to complete its operation.
4787 @code{gpgme_wait} can be used only in conjunction with any context
4788 that has a pending operation initiated with one of the
4789 @code{gpgme_op_*_start} functions except @code{gpgme_op_keylist_start}
4790 and @code{gpgme_op_trustlist_start} (for which you should use the
4791 corresponding @code{gpgme_op_*_next} functions). If @var{ctx} is
4792 @code{NULL}, all of such contexts are waited upon and possibly
4793 returned. Synchronous operations running in parallel, as well as key
4794 and trust item list operations, do not affect @code{gpgme_wait}.
4796 In a multi-threaded environment, only one thread should ever call
4797 @code{gpgme_wait} at any time, irregardless if @var{ctx} is specified
4798 or not. This means that all calls to this function should be fully
4799 synchronized by locking primitives. It is safe to start asynchronous
4800 operations while a thread is running in @code{gpgme_wait}.
4802 The function returns the @var{ctx} of the context which has finished
4803 the operation. If @var{hang} is false, and the timeout expires,
4804 @code{NULL} is returned and @code{*status} will be set to 0. If an
4805 error occurs, @code{NULL} is returned and the error is returned in
4810 @node Using External Event Loops
4811 @subsection Using External Event Loops
4812 @cindex event loop, external
4814 @acronym{GPGME} hides the complexity of the communication between the
4815 library and the crypto engine. The price of this convenience is that
4816 the calling thread can block arbitrary long waiting for the data
4817 returned by the crypto engine. In single-threaded programs, in
4818 particular if they are interactive, this is an unwanted side-effect.
4819 OTOH, if @code{gpgme_wait} is used without the @var{hang} option being
4820 enabled, it might be called unnecessarily often, wasting CPU time that
4821 could be used otherwise.
4823 The I/O callback interface described in this section lets the user
4824 take control over what happens when. @acronym{GPGME} will provide the
4825 user with the file descriptors that should be monitored, and the
4826 callback functions that should be invoked when a file descriptor is
4827 ready for reading or writing. It is then the user's responsibility to
4828 decide when to check the file descriptors and when to invoke the
4829 callback functions. Usually this is done in an event loop, that also
4830 checks for events in other parts of the program. If the callback
4831 functions are only called when the file descriptors are ready,
4832 @acronym{GPGME} will never block. This gives the user more control
4833 over the program flow, and allows to perform other tasks when
4834 @acronym{GPGME} would block otherwise.
4836 By using this advanced mechanism, @acronym{GPGME} can be integrated
4837 smoothly into GUI toolkits like GTK+ even for single-threaded
4841 * I/O Callback Interface:: How I/O callbacks are registered.
4842 * Registering I/O Callbacks:: How to use I/O callbacks for a context.
4843 * I/O Callback Example:: An example how to use I/O callbacks.
4844 * I/O Callback Example GTK+:: How to use @acronym{GPGME} with GTK+.
4845 * I/O Callback Example GDK:: How to use @acronym{GPGME} with GDK.
4846 * I/O Callback Example Qt:: How to use @acronym{GPGME} with Qt.
4850 @node I/O Callback Interface
4851 @subsubsection I/O Callback Interface
4853 @deftp {Data type} {gpgme_error_t (*gpgme_io_cb_t) (@w{void *@var{data}}, @w{int @var{fd}})}
4854 @tindex gpgme_io_cb_t
4855 The @code{gpgme_io_cb_t} type is the type of functions which
4856 @acronym{GPGME} wants to register as I/O callback handlers using the
4857 @code{gpgme_register_io_cb_t} functions provided by the user.
4859 @var{data} and @var{fd} are provided by @acronym{GPGME} when the I/O
4860 callback handler is registered, and should be passed through to the
4861 handler when it is invoked by the user because it noticed activity on
4862 the file descriptor @var{fd}.
4864 The callback handler always returns @code{0}, but you should consider
4865 the return value to be reserved for later use.
4868 @deftp {Data type} {gpgme_error_t (*gpgme_register_io_cb_t) (@w{void *@var{data}}, @w{int @var{fd}}, @w{int @var{dir}}, @w{gpgme_io_cb_t @var{fnc}}, @w{void *@var{fnc_data}}, @w{void **@var{tag}})}
4869 @tindex gpgme_register_io_cb_t
4870 The @code{gpgme_register_io_cb_t} type is the type of functions which can
4871 be called by @acronym{GPGME} to register an I/O callback function
4872 @var{fnc} for the file descriptor @var{fd} with the user.
4873 @var{fnc_data} should be passed as the first argument to @var{fnc}
4874 when the handler is invoked (the second argument should be @var{fd}).
4875 If @var{dir} is 0, @var{fnc} should be called by the user when
4876 @var{fd} is ready for writing. If @var{dir} is 1, @var{fnc} should be
4877 called when @var{fd} is ready for reading.
4879 @var{data} was provided by the user when registering the
4880 @code{gpgme_register_io_cb_t} function with @acronym{GPGME} and will always
4881 be passed as the first argument when registering a callback function.
4882 For example, the user can use this to determine the event loop to
4883 which the file descriptor should be added.
4885 @acronym{GPGME} will call this function when a crypto operation is
4886 initiated in a context for which the user has registered I/O callback
4887 handler functions with @code{gpgme_set_io_cbs}. It can also call this
4888 function when it is in an I/O callback handler for a file descriptor
4889 associated to this context.
4891 The user should return a unique handle in @var{tag} identifying this
4892 I/O callback registration, which will be passed to the
4893 @code{gpgme_register_io_cb_t} function without interpretation when the file
4894 descriptor should not be monitored anymore.
4897 @deftp {Data type} {void (*gpgme_remove_io_cb_t) (@w{void *@var{tag}})}
4898 The @code{gpgme_remove_io_cb_t} type is the type of functions which can be
4899 called by @acronym{GPGME} to remove an I/O callback handler that was
4900 registered before. @var{tag} is the handle that was returned by the
4901 @code{gpgme_register_io_cb_t} for this I/O callback.
4903 @acronym{GPGME} can call this function when a crypto operation is in
4904 an I/O callback. It will also call this function when the context is
4905 destroyed while an operation is pending.
4908 @deftp {Data type} {enum gpgme_event_io_t}
4909 @tindex gpgme_event_io_t
4910 The @code{gpgme_event_io_t} type specifies the type of an event that is
4911 reported to the user by @acronym{GPGME} as a consequence of an I/O
4912 operation. The following events are defined:
4915 @item GPGME_EVENT_START
4916 The operation is fully initialized now, and you can start to run the
4917 registered I/O callback handlers now. Note that registered I/O
4918 callback handlers must not be run before this event is signalled.
4919 @var{type_data} is @code{NULL} and reserved for later use.
4921 @item GPGME_EVENT_DONE
4922 The operation is finished, the last I/O callback for this operation
4923 was removed. The accompanying @var{type_data} points to a
4924 @code{gpgme_error_t} variable that contains the status of the operation
4925 that finished. This event is signalled after the last I/O callback
4928 @item GPGME_EVENT_NEXT_KEY
4929 In a @code{gpgme_op_keylist_start} operation, the next key was
4930 received from the crypto engine. The accompanying @var{type_data} is
4931 a @code{gpgme_key_t} variable that contains the key with one reference
4934 @item GPGME_EVENT_NEXT_TRUSTITEM
4935 In a @code{gpgme_op_trustlist_start} operation, the next trust item
4936 was received from the crypto engine. The accompanying @var{type_data}
4937 is a @code{gpgme_trust_item_t} variable that contains the trust item with
4938 one reference for the user.
4942 @deftp {Data type} {void (*gpgme_event_io_cb_t) (@w{void *@var{data}}, @w{gpgme_event_io_t @var{type}}, @w{void *@var{type_data}})}
4943 The @code{gpgme_event_io_cb_t} type is the type of functions which can be
4944 called by @acronym{GPGME} to signal an event for an operation running
4945 in a context which has I/O callback functions registered by the user.
4947 @var{data} was provided by the user when registering the
4948 @code{gpgme_event_io_cb_t} function with @acronym{GPGME} and will always be
4949 passed as the first argument when registering a callback function.
4950 For example, the user can use this to determine the context in which
4951 this event has occured.
4953 @var{type} will specify the type of event that has occured.
4954 @var{type_data} specifies the event further, as described in the above
4955 list of possible @code{gpgme_event_io_t} types.
4957 @acronym{GPGME} can call this function in an I/O callback handler.
4961 @node Registering I/O Callbacks
4962 @subsubsection Registering I/O Callbacks
4964 @deftp {Data type} {struct gpgme_io_cb_ts}
4965 @tindex gpgme_event_io_t
4966 This structure is used to store the I/O callback interface functions
4967 described in the previous section. It has the following members:
4970 @item gpgme_register_io_cb_t add
4971 This is the function called by @acronym{GPGME} to register an I/O
4972 callback handler. It must be specified.
4974 @item void *add_data
4975 This is passed as the first argument to the @code{add} function when
4976 it is called by @acronym{GPGME}. For example, it can be used to
4977 determine the event loop to which the file descriptor should be added.
4979 @item gpgme_remove_io_cb_t remove
4980 This is the function called by @acronym{GPGME} to remove an I/O
4981 callback handler. It must be specified.
4983 @item gpgme_event_io_cb_t event
4984 This is the function called by @acronym{GPGME} to signal an event for
4985 an operation. It must be specified, because at least the start event
4988 @item void *event_data
4989 This is passed as the first argument to the @code{event} function when
4990 it is called by @acronym{GPGME}. For example, it can be used to
4991 determine the context in which the event has occured.
4995 @deftypefun void gpgme_set_io_cbs (@w{gpgme_ctx_t @var{ctx}}, @w{struct gpgme_io_cb_ts *@var{io_cbs}})
4996 The function @code{gpgme_set_io_cbs} enables the I/O callback
4997 interface for the context @var{ctx}. The I/O callback functions are
4998 specified by @var{io_cbs}.
5000 If @var{io_cbs}->@code{add} is @code{NULL}, the I/O callback interface
5001 is disabled for the context, and normal operation is restored.
5004 @deftypefun void gpgme_get_io_cbs (@w{gpgme_ctx_t @var{ctx}}, @w{struct gpgme_io_cb_ts *@var{io_cbs}})
5005 The function @code{gpgme_get_io_cbs} returns the I/O callback
5006 functions set with @code{gpgme_set_io_cbs} in @var{io_cbs}.
5010 @node I/O Callback Example
5011 @subsubsection I/O Callback Example
5013 To actually use an external event loop, you have to implement the I/O
5014 callback functions that are used by @acronym{GPGME} to register and
5015 unregister file descriptors. Furthermore, you have to actually
5016 monitor these file descriptors for activity and call the appropriate
5019 The following example illustrates how to do that. The example uses
5020 locking to show in which way the the callbacks and the event loop can
5021 run concurrently. For the event loop, we use a fixed array. For a
5022 real-world implementation, you should use a dynamically sized
5023 structure because the number of file descriptors needed for a crypto
5024 operation in @acronym{GPGME} is not predictable.
5027 #include <pthread.h>
5028 #include <sys/types.h>
5031 /* The following structure holds the result of a crypto operation. */
5038 /* The following structure holds the data associated with one I/O
5050 pthread_mutex_t lock;
5052 /* Unused slots are marked with FD being -1. */
5053 struct one_fd fds[MAX_FDS];
5057 The following functions implement the I/O callback interface.
5061 add_io_cb (void *data, int fd, int dir, gpgme_io_cb_t fnc, void *fnc_data,
5064 struct event_loop *loop = data;
5065 struct one_fd *fds = loop->fds;
5068 pthread_mutex_lock (&loop->lock);
5069 for (i = 0; i < MAX_FDS; i++)
5071 if (fds[i].fd == -1)
5076 fds[i].fnc_data = fnc_data;
5080 pthread_mutex_unlock (&loop->lock);
5082 return gpg_error (GPG_ERR_GENERAL);
5088 remove_io_cb (void *tag)
5090 struct one_fd *fd = tag;
5092 pthread_mutex_lock (&loop->lock);
5094 pthread_mutex_unlock (&loop->lock);
5098 event_io_cb (void *data, gpgme_event_io_t type, void *type_data)
5100 struct op_result *result = data;
5102 /* We don't support list operations here. */
5103 if (type == GPGME_EVENT_DONE)
5106 result->err = *type_data;
5111 The final missing piece is the event loop, which will be presented
5112 next. We only support waiting for the success of a single operation.
5116 do_select (struct event_loop *loop)
5123 pthread_mutex_lock (&loop->lock);
5126 for (i = 0; i < FDLIST_MAX; i++)
5127 if (fdlist[i].fd != -1)
5128 FD_SET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds);
5129 pthread_mutex_unlock (&loop->unlock);
5133 n = select (FD_SETSIZE, &rfds, &wfds, NULL, 0);
5135 while (n < 0 && errno == EINTR);
5138 return n; /* Error or timeout. */
5140 pthread_mutex_lock (&loop->lock);
5141 for (i = 0; i < FDLIST_MAX && n; i++)
5143 if (fdlist[i].fd != -1)
5145 if (FD_ISSET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds))
5150 /* The I/O callback handler can register/remove callbacks,
5151 so we have to unlock the file descriptor list. */
5152 pthread_mutex_unlock (&loop->lock);
5153 (*fdlist[i].fnc) (fdlist[i].fnc_data, fdlist[i].fd);
5154 pthread_mutex_lock (&loop->lock);
5158 pthread_mutex_unlock (&loop->lock);
5163 wait_for_op (struct event_loop *loop, struct op_result *result)
5169 ret = do_select (loop);
5171 while (ret >= 0 && !result->done);
5176 The main function shows how to put it all together.
5180 main (int argc, char *argv[])
5182 struct event_loop loop;
5183 struct op_result result;
5186 gpgme_data_t sig, text;
5187 gpgme_sig_stat_t status;
5189 struct gpgme_io_cb_ts io_cbs =
5198 /* Initialize the loop structure. */
5199 loop.lock = PTHREAD_MUTEX_INITIALIZER;
5200 for (i = 0; i < MAX_FDS; i++)
5201 loop->fds[i].fd = -1;
5203 /* Initialize the result structure. */
5206 err = gpgme_data_new_from_file (&sig, "signature", 1);
5208 err = gpgme_data_new_from_file (&text, "text", 1);
5210 err = gpgme_new (&ctx);
5213 gpgme_set_io_cbs (ctx, &io_cbs);
5214 err = gpgme_op_verify_start (ctx, sig, text, &status);
5218 fprintf (stderr, "gpgme error: %s: %s\n",
5219 gpgme_strsource (err), gpgme_strerror (err));
5223 wait_for_op (&loop, &result);
5226 fprintf (stderr, "select error\n");
5231 fprintf (stderr, "verification failed: %s: %s\n",
5232 gpgme_strsource (result.err), gpgme_strerror (result.err));
5235 /* Evaluate STATUS. */
5242 @node I/O Callback Example GTK+
5243 @subsubsection I/O Callback Example GTK+
5244 @cindex GTK+, using @acronym{GPGME} with
5246 The I/O callback interface can be used to integrate @acronym{GPGME}
5247 with the GTK+ event loop. The following code snippets shows how this
5248 can be done using the appropriate register and remove I/O callback
5249 functions. In this example, the private data of the register I/O
5250 callback function is unused. The event notifications is missing
5251 because it does not require any GTK+ specific setup.
5254 #include <gtk/gtk.h>
5256 struct my_gpgme_io_cb
5260 guint input_handler_id
5264 my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition)
5266 struct my_gpgme_io_cb *iocb = data;
5267 (*(iocb->fnc)) (iocb->data, source);
5271 my_gpgme_remove_io_cb (void *data)
5273 struct my_gpgme_io_cb *iocb = data;
5274 gtk_input_remove (data->input_handler_id);
5278 my_gpgme_register_io_callback (void *data, int fd, int dir, gpgme_io_cb_t fnc,
5279 void *fnc_data, void **tag)
5281 struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb));
5283 iocb->data = fnc_data;
5284 iocb->input_handler_id = gtk_input_add_full (fd, dir
5287 my_gpgme_io_callback,
5295 @node I/O Callback Example GDK
5296 @subsubsection I/O Callback Example GDK
5297 @cindex GDK, using @acronym{GPGME} with
5299 The I/O callback interface can also be used to integrate
5300 @acronym{GPGME} with the GDK event loop. The following code snippets
5301 shows how this can be done using the appropriate register and remove
5302 I/O callback functions. In this example, the private data of the
5303 register I/O callback function is unused. The event notifications is
5304 missing because it does not require any GDK specific setup.
5306 It is very similar to the GTK+ example in the previous section.
5309 #include <gdk/gdk.h>
5311 struct my_gpgme_io_cb
5319 my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition)
5321 struct my_gpgme_io_cb *iocb = data;
5322 (*(iocb->fnc)) (iocb->data, source);
5326 my_gpgme_remove_io_cb (void *data)
5328 struct my_gpgme_io_cb *iocb = data;
5329 gdk_input_remove (data->tag);
5333 my_gpgme_register_io_callback (void *data, int fd, int dir, gpgme_io_cb_t fnc,
5334 void *fnc_data, void **tag)
5336 struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb));
5338 iocb->data = fnc_data;
5339 iocb->tag = gtk_input_add_full (fd, dir ? GDK_INPUT_READ : GDK_INPUT_WRITE,
5340 my_gpgme_io_callback, iocb, NULL);
5347 @node I/O Callback Example Qt
5348 @subsubsection I/O Callback Example Qt
5349 @cindex Qt, using @acronym{GPGME} with
5351 The I/O callback interface can also be used to integrate
5352 @acronym{GPGME} with the Qt event loop. The following code snippets
5353 show how this can be done using the appropriate register and remove
5354 I/O callback functions. In this example, the private data of the
5355 register I/O callback function is unused. The event notifications is
5356 missing because it does not require any Qt specific setup.
5359 #include <qsocketnotifier.h>
5360 #include <qapplication.h>
5363 IOCB( GpgmeIOCb f, void * d, QSocketNotifier * n )
5364 : func( f ), data( d ), notifier( n ) @{@}
5367 QSocketNotifier * notifier;
5370 class MyApp : public QApplication @{
5374 static void registerGpgmeIOCallback( void * data, int fd, int dir,
5375 GpgmeIOCb func, void * func_data,
5377 QSocketNotifier * n =
5378 new QSocketNotifier( fd, dir ? QSocketNotifier::Read
5379 : QSocketNotifier::Write );
5380 connect( n, SIGNAL(activated(int)),
5381 qApp, SLOT(slotGpgmeIOCallback(int)) );
5382 qApp->mIOCBs.push_back( IOCB( func, func_data, n ) );
5386 static void removeGpgmeIOCallback( void * tag ) @{
5388 QSocketNotifier * n = static_cast<QSocketNotifier*>( tag );
5389 for ( QValueList<IOCB>::iterator it = qApp->mIOCBs.begin() ;
5390 it != qApp->mIOCBs.end() ; ++it )
5391 if ( it->notifier == n ) @{
5392 delete it->notifier;
5393 qApp->mIOCBs.erase( it );
5399 void slotGpgmeIOCallback( int fd ) @{
5400 for ( QValueList<IOCB>::const_iterator it = mIOCBs.begin() ;
5401 it != mIOCBs.end() ; ++it )
5402 if ( it->notifier && it->notifier->socket() == fd )
5403 (*(it->func)) ( it->func_data, fd );
5409 QValueList<IOCB> mIOCBs;
5416 @subsection Cancellation
5417 @cindex cryptographic operation, aborting
5418 @cindex cryptographic operation, cancelling
5419 @cindex aborting operations
5420 @cindex cancelling operations
5422 Sometimes you do not want to wait for an operation to finish. If you
5423 use external I/O callbacks, you can cancel a pending operation.
5424 However, you must ensure that no other thread is currently using the
5425 context in which the operation you want to cancel runs. This includes
5426 callback handlers. So your external event loop must either be halted
5427 or otherwise it must be guaranteed that no installed I/O callbacks are
5428 run for this context.
5430 @deftypefun gpgme_ctx_t gpgme_cancel (@w{gpgme_ctx_t @var{ctx}})
5431 The function @code{gpgme_cancel} attempts to cancel a pending
5432 operation in the context @var{ctx}. This only works if you use the
5433 global event loop or your own event loop.
5435 If you use the global event loop, you must not call @code{gpgme_wait}
5436 or @code{gpgme_wait} during cancellation. After successful
5437 cancellation, you can call @code{gpgme_wait} (optionally waiting on
5438 @var{ctx}), and the context @var{ctx} will appear as if it had
5439 finished with the error code @code{GPG_ERR_CANCEL}.
5441 If you use your an external event loop, you must ensure that no I/O
5442 callbacks are invoked for this context (for example by halting the
5443 event loop). On successful cancellation, all registered I/O callbacks
5444 for this context will be unregistered, and a @code{GPGME_EVENT_DONE}
5445 event with the error code @code{GPG_ERR_CANCEL} will be signaled.
5447 The function returns an error code if the cancellation failed (in this
5448 case the state of @var{ctx} is not modified).
5452 @include lesser.texi
5456 @unnumbered Concept Index
5461 @node Function and Data Index
5462 @unnumbered Function and Data Index