1 This is gpgme.info, produced by makeinfo version 5.2 from gpgme.texi.
3 Copyright © 2002–2008, 2010, 2012–2016 g10 Code GmbH.
5 Permission is granted to copy, distribute and/or modify this
6 document under the terms of the GNU General Public License as
7 published by the Free Software Foundation; either version 3 of the
8 License, or (at your option) any later version. The text of the
9 license can be found in the section entitled “Copying”.
11 This document is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
14 Public License for more details.
15 INFO-DIR-SECTION GNU Libraries
17 * GPGME: (gpgme). Adding support for cryptography to your program.
20 This file documents the GPGME library.
22 This is Edition 1.7.1, last updated 26 August 2015, of ‘The ‘GnuPG
23 Made Easy’ Reference Manual’, for Version 1.7.1.
25 Copyright © 2002–2008, 2010, 2012–2016 g10 Code GmbH.
27 Permission is granted to copy, distribute and/or modify this
28 document under the terms of the GNU General Public License as
29 published by the Free Software Foundation; either version 3 of the
30 License, or (at your option) any later version. The text of the
31 license can be found in the section entitled “Copying”.
33 This document is distributed in the hope that it will be useful, but
34 WITHOUT ANY WARRANTY; without even the implied warranty of
35 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
36 Public License for more details.
39 File: gpgme.info, Node: Top, Next: Introduction, Up: (dir)
44 This is Edition 1.7.1, last updated 26 August 2015, of ‘The ‘GnuPG Made
45 Easy’ Reference Manual’, for Version 1.7.1 of the GPGME library.
49 * Introduction:: How to use this manual.
50 * Preparation:: What you should do before using the library.
51 * Protocols and Engines:: Supported crypto protocols.
52 * Algorithms:: Supported algorithms.
53 * Error Handling:: Error numbers and their meanings.
54 * Exchanging Data:: Passing data to and from GPGME.
55 * Contexts:: Handling GPGME contexts.
59 * UI Server Protocol:: The GnuPG UI Server Protocol.
60 * Debugging:: How to solve problems.
61 * Deprecated Functions:: Documentation of deprecated functions.
63 * Library Copying:: The GNU Lesser General Public License says
64 how you can copy and share ‘GnuPG Made Easy’.
65 * Copying:: The GNU General Public License says how you
66 can copy and share this manual.
70 * Concept Index:: Index of concepts and programs.
71 * Function and Data Index:: Index of functions, variables and data types.
73 — The Detailed Node Listing —
77 * Getting Started:: Purpose of the manual, and how to use it.
78 * Features:: Reasons to install and use GPGME.
79 * Overview:: Basic architecture of the GPGME library.
83 * Header:: What header file you need to include.
84 * Building the Source:: Compiler options to be used.
85 * Largefile Support (LFS):: How to use GPGME with LFS.
86 * Using Automake:: Compiler options to be used the easy way.
87 * Using Libtool:: Avoiding compiler options entirely.
88 * Library Version Check:: Getting and verifying the library version.
89 * Signal Handling:: How GPGME affects signal handling.
90 * Multi Threading:: How GPGME can be used in an MT environment.
94 * Engine Version Check:: Verifying the engine version.
95 * Engine Information:: Obtaining more information about the engines.
96 * Engine Configuration:: Changing the engine configuration.
97 * OpenPGP:: Support for the OpenPGP protocol.
98 * Cryptographic Message Syntax:: Support for the CMS.
102 * Public Key Algorithms:: A list of all public key algorithms.
103 * Hash Algorithms:: A list of all hash algorithms.
107 * Error Values:: The error value and what it means.
108 * Error Codes:: A list of important error codes.
109 * Error Sources:: A list of important error sources.
110 * Error Strings:: How to get a descriptive string from a value.
114 * Creating Data Buffers:: Creating new data buffers.
115 * Destroying Data Buffers:: Releasing data buffers.
116 * Manipulating Data Buffers:: Operations on data buffers.
118 Creating Data Buffers
120 * Memory Based Data Buffers:: Creating memory based data buffers.
121 * File Based Data Buffers:: Creating file based data buffers.
122 * Callback Based Data Buffers:: Creating callback based data buffers.
124 Manipulating Data Buffers
126 * Data Buffer I/O Operations:: I/O operations on data buffers.
127 * Data Buffer Meta-Data:: Meta-data manipulation of data buffers.
128 * Data Buffer Convenience:: Convenience function for data buffers.
132 * Creating Contexts:: Creating new GPGME contexts.
133 * Destroying Contexts:: Releasing GPGME contexts.
134 * Result Management:: Managing the result of crypto operations.
135 * Context Attributes:: Setting properties of a context.
136 * Key Management:: Managing keys with GPGME.
137 * Trust Item Management:: Managing trust items with GPGME.
138 * Crypto Operations:: Using a context for cryptography.
139 * Miscellaneous:: Miscellaneous operations.
140 * Run Control:: Controlling how operations are run.
144 * Protocol Selection:: Selecting the protocol used by a context.
145 * Crypto Engine:: Configuring the crypto engine.
146 * ASCII Armor:: Requesting ASCII armored output.
147 * Text Mode:: Choosing canonical text mode.
148 * Offline Mode:: Choosing offline mode.
149 * Included Certificates:: Including a number of certificates.
150 * Key Listing Mode:: Selecting key listing mode.
151 * Passphrase Callback:: Getting the passphrase from the user.
152 * Progress Meter Callback:: Being informed about the progress.
153 * Status Message Callback:: Status messages received from gpg.
154 * Locale:: Setting the locale of a context.
158 * Key objects:: Description of the key structures.
159 * Listing Keys:: Browsing the list of available keys.
160 * Information About Keys:: Requesting detailed information about keys.
161 * Manipulating Keys:: Operations on keys.
162 * Generating Keys:: Creating new key pairs.
163 * Signing Keys:: Adding key signatures to public keys.
164 * Exporting Keys:: Retrieving key data from the key ring.
165 * Importing Keys:: Adding keys to the key ring.
166 * Deleting Keys:: Removing keys from the key ring.
167 * Changing Passphrases:: Change the passphrase of a key.
168 * Changing TOFU Data:: Changing data pertaining to TOFU.
169 * Advanced Key Editing:: Advanced key edit operation.
171 Trust Item Management
173 * Listing Trust Items:: Browsing the list of available trust items.
174 * Manipulating Trust Items:: Operations on trust items.
178 * Decrypt:: Decrypting a ciphertext.
179 * Verify:: Verifying a signature.
180 * Decrypt and Verify:: Decrypting a signed ciphertext.
181 * Sign:: Creating a signature.
182 * Encrypt:: Encrypting a plaintext.
186 * Selecting Signers:: How to choose the keys to sign with.
187 * Creating a Signature:: How to create a signature.
188 * Signature Notation Data:: How to add notation data to a signature.
192 * Encrypting a Plaintext:: How to encrypt a plaintext.
196 * Running other Programs:: Running other Programs
200 * Waiting For Completion:: Waiting until an operation is completed.
201 * Using External Event Loops:: Advanced control over what happens when.
202 * Cancellation:: How to end pending operations prematurely.
204 Using External Event Loops
206 * I/O Callback Interface:: How I/O callbacks are registered.
207 * Registering I/O Callbacks:: How to use I/O callbacks for a context.
208 * I/O Callback Example:: An example how to use I/O callbacks.
209 * I/O Callback Example GTK+:: How to integrate GPGME in GTK+.
210 * I/O Callback Example GDK:: How to integrate GPGME in GDK.
211 * I/O Callback Example Qt:: How to integrate GPGME in Qt.
215 File: gpgme.info, Node: Introduction, Next: Preparation, Prev: Top, Up: Top
220 ‘GnuPG Made Easy’ (GPGME) is a C language library that allows to add
221 support for cryptography to a program. It is designed to make access to
222 public key crypto engines like GnuPG or GpgSM easier for applications.
223 GPGME provides a high-level crypto API for encryption, decryption,
224 signing, signature verification and key management.
226 GPGME uses GnuPG and GpgSM as its backends to support OpenPGP and the
227 Cryptographic Message Syntax (CMS).
231 * Getting Started:: Purpose of the manual, and how to use it.
232 * Features:: Reasons to install and use GPGME.
233 * Overview:: Basic architecture of the GPGME library.
236 File: gpgme.info, Node: Getting Started, Next: Features, Up: Introduction
241 This manual documents the GPGME library programming interface. All
242 functions and data types provided by the library are explained.
244 The reader is assumed to possess basic knowledge about cryptography
245 in general, and public key cryptography in particular. The underlying
246 cryptographic engines that are used by the library are not explained,
247 but where necessary, special features or requirements by an engine are
248 mentioned as far as they are relevant to GPGME or its users.
250 This manual can be used in several ways. If read from the beginning
251 to the end, it gives a good introduction into the library and how it can
252 be used in an application. Forward references are included where
253 necessary. Later on, the manual can be used as a reference manual to
254 get just the information needed about any particular interface of the
255 library. Experienced programmers might want to start looking at the
256 examples at the end of the manual, and then only read up those parts of
257 the interface which are unclear.
259 The documentation for the language bindings is currently not included
260 in this manual. Those languages bindings follow the general programming
261 model of GPGME but may provide some extra high level abstraction on top
262 of the GPGME style API. For now please see the README files in the
263 ‘lang/’ directory of the source distribution.
266 File: gpgme.info, Node: Features, Next: Overview, Prev: Getting Started, Up: Introduction
271 GPGME has a couple of advantages over other libraries doing a similar
272 job, and over implementing support for GnuPG or other crypto engines
273 into your application directly.
276 Anybody can use, modify, and redistribute it under the terms of the
277 GNU Lesser General Public License (*note Library Copying::).
280 GPGME provides transparent support for several cryptographic
281 protocols by different engines. Currently, GPGME supports the
282 OpenPGP protocol using GnuPG as the backend, and the Cryptographic
283 Message Syntax using GpgSM as the backend.
286 GPGME hides the differences between the protocols and engines from
287 the programmer behind an easy-to-use interface. This way the
288 programmer can focus on the other parts of the program, and still
289 integrate strong cryptography in his application. Once support for
290 GPGME has been added to a program, it is easy to add support for
291 other crypto protocols once GPGME backends provide them.
293 it’s language friendly
294 GPGME comes with languages bindings for several common programming
295 languages: Common Lisp, C++, Python 2, and Python 3.
298 File: gpgme.info, Node: Overview, Prev: Features, Up: Introduction
303 GPGME provides a data abstraction that is used to pass data to the
304 crypto engine, and receive returned data from it. Data can be read from
305 memory or from files, but it can also be provided by a callback
308 The actual cryptographic operations are always set within a context.
309 A context provides configuration parameters that define the behaviour of
310 all operations performed within it. Only one operation per context is
311 allowed at any time, but when one operation is finished, you can run the
312 next operation in the same context. There can be more than one context,
313 and all can run different operations at the same time.
315 Furthermore, GPGME has rich key management facilities including
316 listing keys, querying their attributes, generating, importing,
317 exporting and deleting keys, and acquiring information about the trust
320 With some precautions, GPGME can be used in a multi-threaded
321 environment, although it is not completely thread safe and thus needs
322 the support of the application.
325 File: gpgme.info, Node: Preparation, Next: Protocols and Engines, Prev: Introduction, Up: Top
330 To use GPGME, you have to perform some changes to your sources and the
331 build system. The necessary changes are small and explained in the
332 following sections. At the end of this chapter, it is described how the
333 library is initialized, and how the requirements of the library are
338 * Header:: What header file you need to include.
339 * Building the Source:: Compiler options to be used.
340 * Largefile Support (LFS):: How to use GPGME with LFS.
341 * Using Automake:: Compiler options to be used the easy way.
342 * Using Libtool:: Avoiding compiler options entirely.
343 * Library Version Check:: Getting and verifying the library version.
344 * Signal Handling:: How GPGME affects signal handling.
345 * Multi Threading:: How GPGME can be used in an MT environment.
348 File: gpgme.info, Node: Header, Next: Building the Source, Up: Preparation
353 All interfaces (data types and functions) of the library are defined in
354 the header file ‘gpgme.h’. You must include this in all programs using
355 the library, either directly or through some other header file, like
360 The name space of GPGME is ‘gpgme_*’ for function names and data
361 types and ‘GPGME_*’ for other symbols. Symbols internal to GPGME take
362 the form ‘_gpgme_*’ and ‘_GPGME_*’.
364 Because GPGME makes use of the GPG Error library, using GPGME will
365 also use the ‘GPG_ERR_*’ name space directly, and the ‘gpg_err*’,
366 ‘gpg_str*’, and ‘gpgrt_*’ name space indirectly.
369 File: gpgme.info, Node: Building the Source, Next: Largefile Support (LFS), Prev: Header, Up: Preparation
371 2.2 Building the Source
372 =======================
374 If you want to compile a source file including the ‘gpgme.h’ header
375 file, you must make sure that the compiler can find it in the directory
376 hierarchy. This is accomplished by adding the path to the directory in
377 which the header file is located to the compilers include file search
378 path (via the ‘-I’ option).
380 However, the path to the include file is determined at the time the
381 source is configured. To solve this problem, gpgme ships with a small
382 helper program ‘gpgme-config’ that knows about the path to the include
383 file and other configuration options. The options that need to be added
384 to the compiler invocation at compile time are output by the ‘--cflags’
385 option to ‘gpgme-config’. The following example shows how it can be
386 used at the command line:
388 gcc -c foo.c `gpgme-config --cflags`
390 Adding the output of ‘gpgme-config --cflags’ to the compiler command
391 line will ensure that the compiler can find the GPGME header file.
393 A similar problem occurs when linking the program with the library.
394 Again, the compiler has to find the library files. For this to work,
395 the path to the library files has to be added to the library search path
396 (via the ‘-L’ option). For this, the option ‘--libs’ to ‘gpgme-config’
397 can be used. For convenience, this option also outputs all other
398 options that are required to link the program with GPGME (in particular,
399 the ‘-lgpgme’ option). The example shows how to link ‘foo.o’ with the
400 GPGME library to a program ‘foo’.
402 gcc -o foo foo.o `gpgme-config --libs`
404 Of course you can also combine both examples to a single command by
405 specifying both options to ‘gpgme-config’:
407 gcc -o foo foo.c `gpgme-config --cflags --libs`
409 If you want to link to one of the thread-safe versions of GPGME, you
410 must specify the ‘--thread’ option before any other option to select the
411 thread package you want to link with. Supported thread packages are
412 ‘--thread=pth’ and ‘--thread=pthread’.
414 If you need to detect the installed language bindings you can use
417 gpgme-config --print-lang
419 or test for the availability using
421 gpgme-config --have-lang=python && echo 'Bindings for Pythons available'
424 File: gpgme.info, Node: Largefile Support (LFS), Next: Using Automake, Prev: Building the Source, Up: Preparation
426 2.3 Largefile Support (LFS)
427 ===========================
429 GPGME is compiled with largefile support by default, if it is available
430 on the system. This means that GPGME supports files larger than two
431 gigabyte in size, if the underlying operating system can. On some
432 systems, largefile support is already the default. On such systems,
433 nothing special is required. However, some systems provide only support
434 for files up to two gigabyte in size by default. Support for larger
435 file sizes has to be specifically enabled.
437 To make a difficult situation even more complex, such systems provide
438 two different types of largefile support. You can either get all
439 relevant functions replaced with alternatives that are largefile
440 capable, or you can get new functions and data types for largefile
441 support added. Those new functions have the same name as their
442 smallfile counterparts, but with a suffix of 64.
444 An example: The data type ‘off_t’ is 32 bit wide on GNU/Linux PC
445 systems. To address offsets in large files, you can either enable
446 largefile support add-on. Then a new data type ‘off64_t’ is provided,
447 which is 64 bit wide. Or you can replace the existing ‘off_t’ data type
448 with its 64 bit wide counterpart. All occurences of ‘off_t’ are then
449 automagically replaced.
451 As if matters were not complex enough, there are also two different
452 types of file descriptors in such systems. This is important because if
453 file descriptors are exchanged between programs that use a different
454 maximum file size, certain errors must be produced on some file
455 descriptors to prevent subtle overflow bugs from occuring.
457 As you can see, supporting two different maximum file sizes at the
458 same time is not at all an easy task. However, the maximum file size
459 does matter for GPGME, because some data types it uses in its interfaces
460 are affected by that. For example, the ‘off_t’ data type is used in the
461 ‘gpgme_data_seek’ function, to match its POSIX counterpart. This
462 affects the call-frame of the function, and thus the ABI of the library.
463 Furthermore, file descriptors can be exchanged between GPGME and the
466 For you as the user of the library, this means that your program must
467 be compiled in the same file size mode as the library. Luckily, there
468 is absolutely no valid reason for new programs to not enable largefile
469 support by default and just use that. The compatibility modes (small
470 file sizes or dual mode) can be considered an historic artefact, only
471 useful to allow for a transitional period.
473 On POSIX platforms GPGME is compiled using largefile support by
474 default. This means that your application must do the same, at least as
475 far as it is relevant for using the ‘gpgme.h’ header file. All types in
476 this header files refer to their largefile counterparts, if they are
477 different from any default types on the system.
479 On 32 and 64 bit Windows platforms ‘off_t’ is declared as 32 bit
480 signed integer. There is no specific support for LFS in the C library.
481 The recommendation from Microsoft is to use the native interface
482 (‘CreateFile’ et al.) for large files. Released binary versions of
483 GPGME (libgpgme-11.dll) have always been build with a 32 bit ‘off_t’.
484 To avoid an ABI break we stick to this convention for 32 bit Windows by
485 using ‘long’ there. GPGME versions for 64 bit Windows have never been
486 released and thus we are able to use ‘int64_t’ instead of ‘off_t’ there.
487 For easier migration the typedef ‘gpgme_off_t’ has been defined. The
488 reason we cannot use ‘off_t’ directly is that some toolchains (e.g.
489 mingw64) introduce a POSIX compatible hack for ‘off_t’. Some widely
490 used toolkits make use of this hack and in turn GPGME would need to use
491 it also. However, this would introduce an ABI break and existing
492 software making use of libgpgme might suffer from a severe break. Thus
493 with version 1.4.2 we redefined all functions using ‘off_t’ to use
494 ‘gpgme_off_t’ which is defined as explained above. This way we keep the
495 ABI well defined and independent of any toolchain hacks. The bottom
496 line is that LFS support in GPGME is only available on 64 bit versions
499 On POSIX platforms you can enable largefile support, if it is
500 different from the default on the system the application is compiled on,
501 by using the Autoconf macro ‘AC_SYS_LARGEFILE’. If you do this, then
502 you don’t need to worry about anything else: It will just work. In this
503 case you might also want to use ‘AC_FUNC_FSEEKO’ to take advantage of
504 some new interfaces, and ‘AC_TYPE_OFF_T’ (just in case).
506 If you do not use Autoconf, you can define the preprocessor symbol
507 ‘_FILE_OFFSET_BITS’ to 64 _before_ including any header files, for
508 example by specifying the option ‘-D_FILE_OFFSET_BITS=64’ on the
509 compiler command line. You will also want to define the preprocessor
510 symbol ‘LARGEFILE_SOURCE’ to 1 in this case, to take advantage of some
513 If you do not want to do either of the above, you probably know
514 enough about the issue to invent your own solution. Just keep in mind
515 that the GPGME header file expects that largefile support is enabled, if
516 it is available. In particular, we do not support dual mode
517 (‘_LARGEFILE64_SOURCE’).
520 File: gpgme.info, Node: Using Automake, Next: Using Libtool, Prev: Largefile Support (LFS), Up: Preparation
525 It is much easier if you use GNU Automake instead of writing your own
526 Makefiles. If you do that you do not have to worry about finding and
527 invoking the ‘gpgme-config’ script at all. GPGME provides an extension
528 to Automake that does all the work for you.
530 -- Macro: AM_PATH_GPGME ([MINIMUM-VERSION], [ACTION-IF-FOUND],
531 [ACTION-IF-NOT-FOUND])
532 -- Macro: AM_PATH_GPGME_PTH ([MINIMUM-VERSION], [ACTION-IF-FOUND],
533 [ACTION-IF-NOT-FOUND])
534 -- Macro: AM_PATH_GPGME_PTHREAD ([MINIMUM-VERSION], [ACTION-IF-FOUND],
535 [ACTION-IF-NOT-FOUND])
536 Check whether GPGME (at least version MINIMUM-VERSION, if given)
537 exists on the host system. If it is found, execute
538 ACTION-IF-FOUND, otherwise do ACTION-IF-NOT-FOUND, if given.
540 Additionally, the function defines ‘GPGME_CFLAGS’ to the flags
541 needed for compilation of the program to find the ‘gpgme.h’ header
542 file, and ‘GPGME_LIBS’ to the linker flags needed to link the
543 program to the GPGME library. If the used helper script does not
544 match the target type you are building for a warning is printed and
545 the string ‘libgcrypt’ is appended to the variable
546 ‘gpg_config_script_warn’.
548 ‘AM_PATH_GPGME_PTH’ checks for the version of GPGME that can be
549 used with GNU Pth, and defines ‘GPGME_PTH_CFLAGS’ and
552 ‘AM_PATH_GPGME_PTHREAD’ checks for the version of GPGME that can be
553 used with the native pthread implementation, and defines
554 ‘GPGME_PTHREAD_CFLAGS’ and ‘GPGME_PTHREAD_LIBS’.
556 This macro searches for ‘gpgme-config’ along the PATH. If you are
557 cross-compiling, it is useful to set the environment variable
558 ‘SYSROOT’ to the top directory of your target. The macro will then
559 first look for the helper program in the ‘bin’ directory below that
560 top directory. An absolute directory name must be used for
561 ‘SYSROOT’. Finally, if the configure command line option
562 ‘--with-gpgme-prefix’ is used, only its value is used for the top
563 directory below which the helper script is expected.
565 You can use the defined Autoconf variables like this in your
568 AM_CPPFLAGS = $(GPGME_CFLAGS)
569 LDADD = $(GPGME_LIBS)
572 File: gpgme.info, Node: Using Libtool, Next: Library Version Check, Prev: Using Automake, Up: Preparation
577 The easiest way is to just use GNU Libtool. If you use libtool, and
578 link to ‘libgpgme.la’, ‘libgpgme-pth.la’ or ‘libgpgme-pthread.la’
579 respectively, everything will be done automatically by Libtool.
582 File: gpgme.info, Node: Library Version Check, Next: Signal Handling, Prev: Using Libtool, Up: Preparation
584 2.6 Library Version Check
585 =========================
587 -- Function: const char * gpgme_check_version
588 (const char *REQUIRED_VERSION)
589 The function ‘gpgme_check_version’ has four purposes. It can be
590 used to retrieve the version number of the library. In addition it
591 can verify that the version number is higher than a certain
592 required version number. In either case, the function initializes
593 some sub-systems, and for this reason alone it must be invoked
594 early in your program, before you make use of the other functions
595 in GPGME. The last purpose is to run selftests.
597 As a side effect for W32 based systems, the socket layer will get
600 If REQUIRED_VERSION is ‘NULL’, the function returns a pointer to a
601 statically allocated string containing the version number of the
604 If REQUIRED_VERSION is not ‘NULL’, it should point to a string
605 containing a version number, and the function checks that the
606 version of the library is at least as high as the version number
607 provided. In this case, the function returns a pointer to a
608 statically allocated string containing the version number of the
609 library. If REQUIRED_VERSION is not a valid version number, or if
610 the version requirement is not met, the function returns ‘NULL’.
612 If you use a version of a library that is backwards compatible with
613 older releases, but contains additional interfaces which your
614 program uses, this function provides a run-time check if the
615 necessary features are provided by the installed version of the
618 If a selftest fails, the function may still succeed. Selftest
619 errors are returned later when invoking ‘gpgme_new’, so that a
620 detailed error code can be returned (historically,
621 ‘gpgme_check_version’ does not return a detailed error code).
623 -- Function: int gpgme_set_global_flag (const char *NAME,
626 On some systems it is not easy to set environment variables and
627 thus hard to use GPGME’s internal trace facility for debugging.
628 This function has been introduced as an alternative way to enable
629 debugging and for a couple of other rarely used tweaks. It is
630 important to assure that only one thread accesses GPGME functions
631 between a call to this function and after the return from the call
632 to ‘gpgme_check_version’.
634 All currently supported features require that this function is
635 called as early as possible — even before ‘gpgme_check_version’.
636 The features are identified by the following values for NAME:
639 To enable debugging use the string “debug” for NAME and VALUE
640 identical to the value used with the environment variable
644 Using this feature with any VALUE disables the detection of
645 the gpgconf program and thus forces GPGME to fallback into the
646 simple OpenPGP only mode. It may be used to force the use of
647 GnuPG-1 on systems which have both GPG versions installed.
648 Note that in general the use of ‘gpgme_set_engine_info’ is a
649 better way to select a specific engine version.
653 Set the name of the gpgconf respective gpg binary. The
654 defaults are ‘GNU/GnuPG/gpgconf’ and ‘GNU/GnuPG/gpg’. Under
655 Unix the leading directory part is ignored. Under Windows the
656 leading directory part is used as the default installation
657 directory; the ‘.exe’ suffix is added by GPGME. Use forward
658 slashed even under Windows.
661 Set the mimimum version of the required GnuPG engine. If that
662 version is not met, GPGME fails early instead of trying to use
663 the existant version. The given version must be a string with
664 major, minor, and micro number. Example: "2.1.0".
667 On Windows GPGME needs to know its installation directory to
668 find its spawn helper. This is in general no problem because
669 a DLL has this information. Some applications however link
670 statically to GPGME and thus GPGME can only figure out the
671 installation directory of this application which may be wrong
672 in certain cases. By supplying an installation directory as
673 value to this flag, GPGME will assume that that directory is
674 the installation directory. This flag has no effect on
675 non-Windows platforms.
677 This function returns ‘0’ on success. In contrast to other
678 functions the non-zero return value on failure does not convey any
679 error code. For setting “debug” the only possible error cause is
680 an out of memory condition; which would exhibit itself later
681 anyway. Thus the return value may be ignored.
683 After initializing GPGME, you should set the locale information to
684 the locale required for your output terminal. This locale information
685 is needed for example for the curses and Gtk pinentry. Here is an
686 example of a complete initialization:
694 /* Initialize the locale environment. */
695 setlocale (LC_ALL, "");
696 gpgme_check_version (NULL);
697 gpgme_set_locale (NULL, LC_CTYPE, setlocale (LC_CTYPE, NULL));
699 gpgme_set_locale (NULL, LC_MESSAGES, setlocale (LC_MESSAGES, NULL));
703 Note that you are highly recommended to initialize the locale
704 settings like this. GPGME can not do this for you because it would not
705 be thread safe. The conditional on LC_MESSAGES is only necessary for
706 portability to W32 systems.
709 File: gpgme.info, Node: Signal Handling, Next: Multi Threading, Prev: Library Version Check, Up: Preparation
714 The GPGME library communicates with child processes (the crypto
715 engines). If a child process dies unexpectedly, for example due to a
716 bug, or system problem, a ‘SIGPIPE’ signal will be delivered to the
717 application. The default action is to abort the program. To protect
718 against this, ‘gpgme_check_version’ sets the ‘SIGPIPE’ signal action to
719 ‘SIG_IGN’, which means that the signal will be ignored.
721 GPGME will only do that if the signal action for ‘SIGPIPE’ is
722 ‘SIG_DEF’ at the time ‘gpgme_check_version’ is called. If it is
723 something different, ‘GPGME’ will take no action.
725 This means that if your application does not install any signal
726 handler for ‘SIGPIPE’, you don’t need to take any precautions. If you
727 do install a signal handler for ‘SIGPIPE’, you must be prepared to
728 handle any ‘SIGPIPE’ events that occur due to GPGME writing to a defunct
729 pipe. Furthermore, if your application is multi-threaded, and you
730 install a signal action for ‘SIGPIPE’, you must make sure you do this
731 either before ‘gpgme_check_version’ is called or afterwards.
734 File: gpgme.info, Node: Multi Threading, Prev: Signal Handling, Up: Preparation
739 The GPGME library is not entirely thread-safe, but it can still be used
740 in a multi-threaded environment if some care is taken. If the following
741 requirements are met, there should be no race conditions to worry about:
743 • GPGME supports the thread libraries pthread and GNU Pth. The
744 support for this has to be enabled at compile time. GPGME will
745 automatically detect the location in which the thread libraries are
746 installed and activate the support for them at build time.
748 Support for other thread libraries is very easy to add. Please
749 contact us if you have the need.
751 • If you want to use GPGME with threads, you must link to the right
752 version of the library. The name of the right library is
753 ‘libgpgme-’ followed by the name of the thread package you use.
754 For example, if you use GNU Pth, the right name is ‘libgpgme-pth’.
755 Use the Automake macros or ‘gpgme-config’ program for simplicity.
757 • The function ‘gpgme_check_version’ must be called before any other
758 function in the library, because it initializes the thread support
759 subsystem in GPGME. To achieve this in multi-threaded programs,
760 you must synchronize the memory with respect to other threads that
761 also want to use GPGME. For this, it is sufficient to call
762 ‘gpgme_check_version’ before creating the other threads using
765 • Any ‘gpgme_data_t’ and ‘gpgme_ctx_t’ object must only be accessed
766 by one thread at a time. If multiple threads want to deal with the
767 same object, the caller has to make sure that operations on that
768 object are fully synchronized.
770 • Only one thread at any time is allowed to call ‘gpgme_wait’. If
771 multiple threads call this function, the caller must make sure that
772 all invocations are fully synchronized. It is safe to start
773 asynchronous operations while a thread is running in gpgme_wait.
775 • The function ‘gpgme_strerror’ is not thread safe. You have to use
776 ‘gpgme_strerror_r’ instead.
778 ---------- Footnotes ----------
780 (1) At least this is true for POSIX threads, as ‘pthread_create’ is a
781 function that synchronizes memory with respects to other threads. There
782 are many functions which have this property, a complete list can be
783 found in POSIX, IEEE Std 1003.1-2003, Base Definitions, Issue 6, in the
784 definition of the term “Memory Synchronization”. For other thread
785 packages other, more relaxed or more strict rules may apply.
788 File: gpgme.info, Node: Protocols and Engines, Next: Algorithms, Prev: Preparation, Up: Top
790 3 Protocols and Engines
791 ***********************
793 GPGME supports several cryptographic protocols, however, it does not
794 implement them. Rather it uses backends (also called engines) which
795 implement the protocol. GPGME uses inter-process communication to pass
796 data back and forth between the application and the backend, but the
797 details of the communication protocol and invocation of the backend is
798 completely hidden by the interface. All complexity is handled by GPGME.
799 Where an exchange of information between the application and the backend
800 is necessary, GPGME provides the necessary callback function hooks and
803 -- Data type: enum gpgme_protocol_t
804 The ‘gpgme_protocol_t’ type specifies the set of possible protocol
805 values that are supported by GPGME. The following protocols are
808 ‘GPGME_PROTOCOL_OpenPGP’
809 This specifies the OpenPGP protocol.
812 This specifies the Cryptographic Message Syntax.
814 ‘GPGME_PROTOCOL_GPGCONF’
815 Under development. Please ask on <gnupg-devel@gnupg.org> for
818 ‘GPGME_PROTOCOL_ASSUAN’
819 This specifies the raw Assuan protocol.
822 Under development. Please ask on <gnupg-devel@gnupg.org> for
825 ‘GPGME_PROTOCOL_UISERVER’
826 Under development. Please ask on <gnupg-devel@gnupg.org> for
829 ‘GPGME_PROTOCOL_SPAWN’
830 Special protocol for use with ‘gpgme_op_spawn’.
832 ‘GPGME_PROTOCOL_UNKNOWN’
833 Reserved for future extension. You may use this to indicate
834 that the used protocol is not known to the application.
835 Currently, GPGME does not accept this value in any operation,
836 though, except for ‘gpgme_get_protocol_name’.
838 -- Function: const char * gpgme_get_protocol_name
839 (gpgme_protocol_t PROTOCOL)
840 The function ‘gpgme_get_protocol_name’ returns a statically
841 allocated string describing the protocol PROTOCOL, or ‘NULL’ if the
842 protocol number is not valid.
846 * Engine Version Check:: Verifying the engine version.
847 * Engine Information:: Obtaining more information about the engines.
848 * Engine Configuration:: Changing the engine configuration.
849 * OpenPGP:: Support for the OpenPGP protocol.
850 * Cryptographic Message Syntax:: Support for the CMS.
851 * Assuan:: Support for the raw Assuan protocol.
854 File: gpgme.info, Node: Engine Version Check, Next: Engine Information, Up: Protocols and Engines
856 3.1 Engine Version Check
857 ========================
859 -- Function: const char * gpgme_get_dirinfo (cons char *WHAT)
860 The function ‘gpgme_get_dirinfo’ returns a statically allocated
861 string with the value associated to WHAT. The returned values are
862 the defaults and won’t change even after ‘gpgme_set_engine_info’
863 has been used to configure a different engine. ‘NULL’ is returned
864 if no value is available. Commonly supported values for WHAT are:
867 Return the default home directory.
870 Return the name of the system configuration directory
873 Return the name of the directory with GnuPG program files.
876 Return the name of the directory with GnuPG related library
880 Return the name of the directory with GnuPG helper program
884 Return the name of the directory with GnuPG shared data.
887 Return the name of the directory with GnuPG locale data.
890 Return the name of the socket to connect to the gpg-agent.
893 Return the name of the socket to connect to the ssh-agent
894 component of gpg-agent.
897 Return the name of the socket to connect to the dirmngr.
900 Return the name of the socket to connect to the user interface
904 Return the file name of the engine configuration tool.
907 Return the file name of the OpenPGP engine.
910 Return the file name of the CMS engine.
913 Return the name of the file container encryption engine.
915 -- Function: gpgme_error_t gpgme_engine_check_version
916 (gpgme_protocol_t PROTOCOL)
917 The function ‘gpgme_engine_check_version’ verifies that the engine
918 implementing the protocol PROTOCOL is installed in the expected
919 path and meets the version requirement of GPGME.
921 This function returns the error code ‘GPG_ERR_NO_ERROR’ if the
922 engine is available and ‘GPG_ERR_INV_ENGINE’ if it is not.
925 File: gpgme.info, Node: Engine Information, Next: Engine Configuration, Prev: Engine Version Check, Up: Protocols and Engines
927 3.2 Engine Information
928 ======================
930 -- Data type: gpgme_engine_info_t
931 The ‘gpgme_engine_info_t’ type specifies a pointer to a structure
932 describing a crypto engine. The structure contains the following
935 ‘gpgme_engine_info_t next’
936 This is a pointer to the next engine info structure in the
937 linked list, or ‘NULL’ if this is the last element.
939 ‘gpgme_protocol_t protocol’
940 This is the protocol for which the crypto engine is used. You
941 can convert this to a string with ‘gpgme_get_protocol_name’
944 ‘const char *file_name’
945 This is a string holding the file name of the executable of
946 the crypto engine. Currently, it is never ‘NULL’, but using
947 ‘NULL’ is reserved for future use, so always check before you
950 ‘const char *home_dir’
951 This is a string holding the directory name of the crypto
952 engine’s configuration directory. If it is ‘NULL’, then the
953 default directory is used. See ‘gpgme_get_dirinfo’ on how to
954 get the default directory.
956 ‘const char *version’
957 This is a string containing the version number of the crypto
958 engine. It might be ‘NULL’ if the version number can not be
959 determined, for example because the executable doesn’t exist
962 ‘const char *req_version’
963 This is a string containing the minimum required version
964 number of the crypto engine for GPGME to work correctly. This
965 is the version number that ‘gpgme_engine_check_version’
966 verifies against. Currently, it is never ‘NULL’, but using
967 ‘NULL’ is reserved for future use, so always check before you
970 -- Function: gpgme_error_t gpgme_get_engine_info
971 (gpgme_engine_info_t *INFO)
972 The function ‘gpgme_get_engine_info’ returns a linked list of
973 engine info structures in INFO. Each info structure describes the
974 defaults of one configured backend.
976 The memory for the info structures is allocated the first time this
977 function is invoked, and must not be freed by the caller.
979 This function returns the error code ‘GPG_ERR_NO_ERROR’ if
980 successful, and a system error if the memory could not be
983 Here is an example how you can provide more diagnostics if you
984 receive an error message which indicates that the crypto engine is
992 if (gpgme_err_code (err) == GPG_ERR_INV_ENGINE)
994 gpgme_engine_info_t info;
995 err = gpgme_get_engine_info (&info);
998 while (info && info->protocol != gpgme_get_protocol (ctx))
1001 fprintf (stderr, "GPGME compiled without support for protocol %s",
1002 gpgme_get_protocol_name (info->protocol));
1003 else if (info->file_name && !info->version)
1004 fprintf (stderr, "Engine %s not installed properly",
1006 else if (info->file_name && info->version && info->req_version)
1007 fprintf (stderr, "Engine %s version %s installed, "
1008 "but at least version %s required", info->file_name,
1009 info->version, info->req_version);
1011 fprintf (stderr, "Unknown problem with engine for protocol %s",
1012 gpgme_get_protocol_name (info->protocol));
1017 File: gpgme.info, Node: Engine Configuration, Next: OpenPGP, Prev: Engine Information, Up: Protocols and Engines
1019 3.3 Engine Configuration
1020 ========================
1022 You can change the configuration of a backend engine, and thus change
1023 the executable program and configuration directory to be used. You can
1024 make these changes the default or set them for some contexts
1027 -- Function: gpgme_error_t gpgme_set_engine_info
1028 (gpgme_protocol_t PROTO, const char *FILE_NAME,
1029 const char *HOME_DIR)
1030 The function ‘gpgme_set_engine_info’ changes the default
1031 configuration of the crypto engine implementing the protocol PROTO.
1033 FILE_NAME is the file name of the executable program implementing
1034 this protocol, and HOME_DIR is the directory name of the
1035 configuration directory for this crypto engine. If HOME_DIR is
1036 ‘NULL’, the engine’s default will be used.
1038 The new defaults are not applied to already created GPGME contexts.
1040 This function returns the error code ‘GPG_ERR_NO_ERROR’ if
1041 successful, or an eror code on failure.
1043 The functions ‘gpgme_ctx_get_engine_info’ and
1044 ‘gpgme_ctx_set_engine_info’ can be used to change the engine
1045 configuration per context. *Note Crypto Engine::.
1048 File: gpgme.info, Node: OpenPGP, Next: Cryptographic Message Syntax, Prev: Engine Configuration, Up: Protocols and Engines
1053 OpenPGP is implemented by GnuPG, the GNU Privacy Guard. This is the
1054 first protocol that was supported by GPGME.
1056 The OpenPGP protocol is specified by ‘GPGME_PROTOCOL_OpenPGP’.
1059 File: gpgme.info, Node: Cryptographic Message Syntax, Next: Assuan, Prev: OpenPGP, Up: Protocols and Engines
1061 3.5 Cryptographic Message Syntax
1062 ================================
1064 CMS is implemented by GpgSM, the S/MIME implementation for GnuPG.
1066 The CMS protocol is specified by ‘GPGME_PROTOCOL_CMS’.
1069 File: gpgme.info, Node: Assuan, Prev: Cryptographic Message Syntax, Up: Protocols and Engines
1074 Assuan is the RPC library used by the various GnuPG components. The
1075 Assuan protocol allows one to talk to arbitrary Assuan servers using
1076 GPGME. *Note Using the Assuan protocol::.
1078 The ASSUAN protocol is specified by ‘GPGME_PROTOCOL_ASSUAN’.
1081 File: gpgme.info, Node: Algorithms, Next: Error Handling, Prev: Protocols and Engines, Up: Top
1086 The crypto backends support a variety of algorithms used in public key
1087 cryptography.(1) The following sections list the identifiers used to
1088 denote such an algorithm.
1092 * Public Key Algorithms:: A list of all public key algorithms.
1093 * Hash Algorithms:: A list of all hash algorithms.
1095 ---------- Footnotes ----------
1097 (1) Some engines also provide symmetric only encryption; see the
1098 description of the encryption function on how to use this.
1101 File: gpgme.info, Node: Public Key Algorithms, Next: Hash Algorithms, Up: Algorithms
1103 4.1 Public Key Algorithms
1104 =========================
1106 Public key algorithms are used for encryption, decryption, signing and
1107 verification of signatures.
1109 -- Data type: enum gpgme_pubkey_algo_t
1110 The ‘gpgme_pubkey_algo_t’ type specifies the set of all public key
1111 algorithms that are supported by GPGME. Possible values are:
1114 This value indicates the RSA (Rivest, Shamir, Adleman)
1118 Deprecated. This value indicates the RSA (Rivest, Shamir,
1119 Adleman) algorithm for encryption and decryption only.
1122 Deprecated. This value indicates the RSA (Rivest, Shamir,
1123 Adleman) algorithm for signing and verification only.
1126 This value indicates DSA, the Digital Signature Algorithm.
1129 This value indicates ElGamal.
1132 This value also indicates ElGamal and is used specifically in
1136 This value is a generic indicator for ellipic curve
1140 This value indicates ECDSA, the Elliptic Curve Digital
1141 Signature Algorithm as defined by FIPS 186-2 and RFC-6637.
1144 This value indicates ECDH, the Eliptic Curve Diffie-Hellmann
1145 encryption algorithm as defined by RFC-6637.
1148 This value indicates the EdDSA algorithm.
1150 -- Function: const char * gpgme_pubkey_algo_name
1151 (gpgme_pubkey_algo_t ALGO)
1152 The function ‘gpgme_pubkey_algo_name’ returns a pointer to a
1153 statically allocated string containing a description of the public
1154 key algorithm ALGO. This string can be used to output the name of
1155 the public key algorithm to the user.
1157 If ALGO is not a valid public key algorithm, ‘NULL’ is returned.
1159 -- Function: char * gpgme_pubkey_algo_string (gpgme_subkey_t KEY)
1160 The function ‘gpgme_pubkey_algo_string’ is a convenience function
1161 to build and return an algorithm string in the same way GnuPG does
1162 (e.g. “rsa2048” or “ed25519”). The caller must free the result
1163 using ‘gpgme_free’. On error (e.g. invalid argument or memory
1164 exhausted), the function returns NULL and sets ‘ERRNO’.
1167 File: gpgme.info, Node: Hash Algorithms, Prev: Public Key Algorithms, Up: Algorithms
1172 Hash (message digest) algorithms are used to compress a long message to
1173 make it suitable for public key cryptography.
1175 -- Data type: enum gpgme_hash_algo_t
1176 The ‘gpgme_hash_algo_t’ type specifies the set of all hash
1177 algorithms that are supported by GPGME. Possible values are:
1191 ‘GPGME_MD_CRC32_RFC1510’
1192 ‘GPGME_MD_CRC24_RFC2440’
1194 -- Function: const char * gpgme_hash_algo_name (gpgme_hash_algo_t ALGO)
1195 The function ‘gpgme_hash_algo_name’ returns a pointer to a
1196 statically allocated string containing a description of the hash
1197 algorithm ALGO. This string can be used to output the name of the
1198 hash algorithm to the user.
1200 If ALGO is not a valid hash algorithm, ‘NULL’ is returned.
1203 File: gpgme.info, Node: Error Handling, Next: Exchanging Data, Prev: Algorithms, Up: Top
1208 Many functions in GPGME can return an error if they fail. For this
1209 reason, the application should always catch the error condition and take
1210 appropriate measures, for example by releasing the resources and passing
1211 the error up to the caller, or by displaying a descriptive message to
1212 the user and cancelling the operation.
1214 Some error values do not indicate a system error or an error in the
1215 operation, but the result of an operation that failed properly. For
1216 example, if you try to decrypt a tempered message, the decryption will
1217 fail. Another error value actually means that the end of a data buffer
1218 or list has been reached. The following descriptions explain for many
1219 error codes what they mean usually. Some error values have specific
1220 meanings if returned by a certain functions. Such cases are described
1221 in the documentation of those functions.
1223 GPGME uses the ‘libgpg-error’ library. This allows to share the
1224 error codes with other components of the GnuPG system, and thus pass
1225 error values transparently from the crypto engine, or some helper
1226 application of the crypto engine, to the user. This way no information
1227 is lost. As a consequence, GPGME does not use its own identifiers for
1228 error codes, but uses those provided by ‘libgpg-error’. They usually
1229 start with ‘GPG_ERR_’.
1231 However, GPGME does provide aliases for the functions defined in
1232 libgpg-error, which might be preferred for name space consistency.
1236 * Error Values:: The error value and what it means.
1237 * Error Sources:: A list of important error sources.
1238 * Error Codes:: A list of important error codes.
1239 * Error Strings:: How to get a descriptive string from a value.
1242 File: gpgme.info, Node: Error Values, Next: Error Sources, Up: Error Handling
1247 -- Data type: gpgme_err_code_t
1248 The ‘gpgme_err_code_t’ type is an alias for the ‘libgpg-error’ type
1249 ‘gpg_err_code_t’. The error code indicates the type of an error,
1250 or the reason why an operation failed.
1252 A list of important error codes can be found in the next section.
1254 -- Data type: gpgme_err_source_t
1255 The ‘gpgme_err_source_t’ type is an alias for the ‘libgpg-error’
1256 type ‘gpg_err_source_t’. The error source has not a precisely
1257 defined meaning. Sometimes it is the place where the error
1258 happened, sometimes it is the place where an error was encoded into
1259 an error value. Usually the error source will give an indication
1260 to where to look for the problem. This is not always true, but it
1261 is attempted to achieve this goal.
1263 A list of important error sources can be found in the next section.
1265 -- Data type: gpgme_error_t
1266 The ‘gpgme_error_t’ type is an alias for the ‘libgpg-error’ type
1267 ‘gpg_error_t’. An error value like this has always two components,
1268 an error code and an error source. Both together form the error
1271 Thus, the error value can not be directly compared against an error
1272 code, but the accessor functions described below must be used.
1273 However, it is guaranteed that only 0 is used to indicate success
1274 (‘GPG_ERR_NO_ERROR’), and that in this case all other parts of the
1275 error value are set to 0, too.
1277 Note that in GPGME, the error source is used purely for
1278 diagnostical purposes. Only the error code should be checked to
1279 test for a certain outcome of a function. The manual only
1280 documents the error code part of an error value. The error source
1281 is left unspecified and might be anything.
1283 -- Function: static inline gpgme_err_code_t gpgme_err_code
1285 The static inline function ‘gpgme_err_code’ returns the
1286 ‘gpgme_err_code_t’ component of the error value ERR. This function
1287 must be used to extract the error code from an error value in order
1288 to compare it with the ‘GPG_ERR_*’ error code macros.
1290 -- Function: static inline gpgme_err_source_t gpgme_err_source
1292 The static inline function ‘gpgme_err_source’ returns the
1293 ‘gpgme_err_source_t’ component of the error value ERR. This
1294 function must be used to extract the error source from an error
1295 value in order to compare it with the ‘GPG_ERR_SOURCE_*’ error
1298 -- Function: static inline gpgme_error_t gpgme_err_make
1299 (gpgme_err_source_t SOURCE, gpgme_err_code_t CODE)
1300 The static inline function ‘gpgme_err_make’ returns the error value
1301 consisting of the error source SOURCE and the error code CODE.
1303 This function can be used in callback functions to construct an
1304 error value to return it to the library.
1306 -- Function: static inline gpgme_error_t gpgme_error
1307 (gpgme_err_code_t CODE)
1308 The static inline function ‘gpgme_error’ returns the error value
1309 consisting of the default error source and the error code CODE.
1311 For GPGME applications, the default error source is
1312 ‘GPG_ERR_SOURCE_USER_1’. You can define ‘GPGME_ERR_SOURCE_DEFAULT’
1313 before including ‘gpgme.h’ to change this default.
1315 This function can be used in callback functions to construct an
1316 error value to return it to the library.
1318 The ‘libgpg-error’ library provides error codes for all system error
1319 numbers it knows about. If ERR is an unknown error number, the error
1320 code ‘GPG_ERR_UNKNOWN_ERRNO’ is used. The following functions can be
1321 used to construct error values from system errnor numbers.
1323 -- Function: gpgme_error_t gpgme_err_make_from_errno
1324 (gpgme_err_source_t SOURCE, int ERR)
1325 The function ‘gpgme_err_make_from_errno’ is like ‘gpgme_err_make’,
1326 but it takes a system error like ‘errno’ instead of a
1327 ‘gpgme_err_code_t’ error code.
1329 -- Function: gpgme_error_t gpgme_error_from_errno (int ERR)
1330 The function ‘gpgme_error_from_errno’ is like ‘gpgme_error’, but it
1331 takes a system error like ‘errno’ instead of a ‘gpgme_err_code_t’
1334 Sometimes you might want to map system error numbers to error codes
1335 directly, or map an error code representing a system error back to the
1336 system error number. The following functions can be used to do that.
1338 -- Function: gpgme_err_code_t gpgme_err_code_from_errno (int ERR)
1339 The function ‘gpgme_err_code_from_errno’ returns the error code for
1340 the system error ERR. If ERR is not a known system error, the
1341 function returns ‘GPG_ERR_UNKNOWN_ERRNO’.
1343 -- Function: int gpgme_err_code_to_errno (gpgme_err_code_t ERR)
1344 The function ‘gpgme_err_code_to_errno’ returns the system error for
1345 the error code ERR. If ERR is not an error code representing a
1346 system error, or if this system error is not defined on this
1347 system, the function returns ‘0’.
1350 File: gpgme.info, Node: Error Sources, Next: Error Codes, Prev: Error Values, Up: Error Handling
1355 The library ‘libgpg-error’ defines an error source for every component
1356 of the GnuPG system. The error source part of an error value is not
1357 well defined. As such it is mainly useful to improve the diagnostic
1358 error message for the user.
1360 If the error code part of an error value is ‘0’, the whole error
1361 value will be ‘0’. In this case the error source part is of course
1362 ‘GPG_ERR_SOURCE_UNKNOWN’.
1364 The list of error sources that might occur in applications using
1367 ‘GPG_ERR_SOURCE_UNKNOWN’
1368 The error source is not known. The value of this error source is
1371 ‘GPG_ERR_SOURCE_GPGME’
1372 The error source is GPGME itself. This is the default for errors
1373 that occur in the GPGME library.
1375 ‘GPG_ERR_SOURCE_GPG’
1376 The error source is GnuPG, which is the crypto engine used for the
1379 ‘GPG_ERR_SOURCE_GPGSM’
1380 The error source is GPGSM, which is the crypto engine used for the
1383 ‘GPG_ERR_SOURCE_GCRYPT’
1384 The error source is ‘libgcrypt’, which is used by crypto engines to
1385 perform cryptographic operations.
1387 ‘GPG_ERR_SOURCE_GPGAGENT’
1388 The error source is ‘gpg-agent’, which is used by crypto engines to
1389 perform operations with the secret key.
1391 ‘GPG_ERR_SOURCE_PINENTRY’
1392 The error source is ‘pinentry’, which is used by ‘gpg-agent’ to
1393 query the passphrase to unlock a secret key.
1395 ‘GPG_ERR_SOURCE_SCD’
1396 The error source is the SmartCard Daemon, which is used by
1397 ‘gpg-agent’ to delegate operations with the secret key to a
1400 ‘GPG_ERR_SOURCE_KEYBOX’
1401 The error source is ‘libkbx’, a library used by the crypto engines
1402 to manage local keyrings.
1404 ‘GPG_ERR_SOURCE_USER_1’
1405 ‘GPG_ERR_SOURCE_USER_2’
1406 ‘GPG_ERR_SOURCE_USER_3’
1407 ‘GPG_ERR_SOURCE_USER_4’
1408 These error sources are not used by any GnuPG component and can be
1409 used by other software. For example, applications using GPGME can
1410 use them to mark error values coming from callback handlers. Thus
1411 ‘GPG_ERR_SOURCE_USER_1’ is the default for errors created with
1412 ‘gpgme_error’ and ‘gpgme_error_from_errno’, unless you define
1413 ‘GPGME_ERR_SOURCE_DEFAULT’ before including ‘gpgme.h’.
1416 File: gpgme.info, Node: Error Codes, Next: Error Strings, Prev: Error Sources, Up: Error Handling
1421 The library ‘libgpg-error’ defines many error values. Most of them are
1422 not used by ‘GPGME’ directly, but might be returned by GPGME because it
1423 received them from the crypto engine. The below list only includes such
1424 error codes that have a specific meaning in ‘GPGME’, or which are so
1425 common that you should know about them.
1428 This value indicates the end of a list, buffer or file.
1431 This value indicates success. The value of this error code is ‘0’.
1432 Also, it is guaranteed that an error value made from the error code
1433 ‘0’ will be ‘0’ itself (as a whole). This means that the error
1434 source information is lost for this error code, however, as this
1435 error code indicates that no error occured, this is generally not a
1439 This value means that something went wrong, but either there is not
1440 enough information about the problem to return a more useful error
1441 value, or there is no separate error value for this type of
1445 This value means that an out-of-memory condition occurred.
1448 System errors are mapped to GPG_ERR_FOO where FOO is the symbol for
1452 This value means that some user provided data was out of range.
1453 This can also refer to objects. For example, if an empty
1454 ‘gpgme_data_t’ object was expected, but one containing data was
1455 provided, this error value is returned.
1457 ‘GPG_ERR_UNUSABLE_PUBKEY’
1458 This value means that some recipients for a message were invalid.
1460 ‘GPG_ERR_UNUSABLE_SECKEY’
1461 This value means that some signers were invalid.
1464 This value means that a ‘gpgme_data_t’ object which was expected to
1465 have content was found empty.
1468 This value means that a conflict of some sort occurred.
1470 ‘GPG_ERR_NOT_IMPLEMENTED’
1471 This value indicates that the specific function (or operation) is
1472 not implemented. This error should never happen. It can only
1473 occur if you use certain values or configuration options which do
1474 not work, but for which we think that they should work at some
1477 ‘GPG_ERR_DECRYPT_FAILED’
1478 This value indicates that a decryption operation was unsuccessful.
1480 ‘GPG_ERR_BAD_PASSPHRASE’
1481 This value means that the user did not provide a correct passphrase
1485 This value means that the operation was canceled.
1487 ‘GPG_ERR_INV_ENGINE’
1488 This value means that the engine that implements the desired
1489 protocol is currently not available. This can either be because
1490 the sources were configured to exclude support for this engine, or
1491 because the engine is not installed properly.
1493 ‘GPG_ERR_AMBIGUOUS_NAME’
1494 This value indicates that a user ID or other specifier did not
1495 specify a unique key.
1497 ‘GPG_ERR_WRONG_KEY_USAGE’
1498 This value indicates that a key is not used appropriately.
1500 ‘GPG_ERR_CERT_REVOKED’
1501 This value indicates that a key signature was revoced.
1503 ‘GPG_ERR_CERT_EXPIRED’
1504 This value indicates that a key signature expired.
1506 ‘GPG_ERR_NO_CRL_KNOWN’
1507 This value indicates that no certificate revocation list is known
1508 for the certificate.
1510 ‘GPG_ERR_NO_POLICY_MATCH’
1511 This value indicates that a policy issue occured.
1514 This value indicates that no secret key for the user ID is
1517 ‘GPG_ERR_MISSING_CERT’
1518 This value indicates that a key could not be imported because the
1519 issuer certificate is missing.
1521 ‘GPG_ERR_BAD_CERT_CHAIN’
1522 This value indicates that a key could not be imported because its
1523 certificate chain is not good, for example it could be too long.
1525 ‘GPG_ERR_UNSUPPORTED_ALGORITHM’
1526 This value means a verification failed because the cryptographic
1527 algorithm is not supported by the crypto backend.
1529 ‘GPG_ERR_BAD_SIGNATURE’
1530 This value means a verification failed because the signature is
1534 This value means a verification failed because the public key is
1541 These error codes are not used by any GnuPG component and can be
1542 freely used by other software. Applications using GPGME might use
1543 them to mark specific errors returned by callback handlers if no
1544 suitable error codes (including the system errors) for these errors
1548 File: gpgme.info, Node: Error Strings, Prev: Error Codes, Up: Error Handling
1553 -- Function: const char * gpgme_strerror (gpgme_error_t ERR)
1554 The function ‘gpgme_strerror’ returns a pointer to a statically
1555 allocated string containing a description of the error code
1556 contained in the error value ERR. This string can be used to
1557 output a diagnostic message to the user.
1559 This function is not thread safe. Use ‘gpgme_strerror_r’ in
1560 multi-threaded programs.
1562 -- Function: int gpgme_strerror_r (gpgme_error_t ERR, char *BUF,
1564 The function ‘gpgme_strerror_r’ returns the error string for ERR in
1565 the user-supplied buffer BUF of size BUFLEN. This function is, in
1566 contrast to ‘gpgme_strerror’, thread-safe if a thread-safe
1567 ‘strerror_r’ function is provided by the system. If the function
1568 succeeds, 0 is returned and BUF contains the string describing the
1569 error. If the buffer was not large enough, ERANGE is returned and
1570 BUF contains as much of the beginning of the error string as fits
1573 -- Function: const char * gpgme_strsource (gpgme_error_t ERR)
1574 The function ‘gpgme_strerror’ returns a pointer to a statically
1575 allocated string containing a description of the error source
1576 contained in the error value ERR. This string can be used to
1577 output a diagnostic message to the user.
1579 The following example illustrates the use of ‘gpgme_strerror’:
1582 gpgme_error_t err = gpgme_new (&ctx);
1585 fprintf (stderr, "%s: creating GpgME context failed: %s: %s\n",
1586 argv[0], gpgme_strsource (err), gpgme_strerror (err));
1591 File: gpgme.info, Node: Exchanging Data, Next: Contexts, Prev: Error Handling, Up: Top
1596 A lot of data has to be exchanged between the user and the crypto
1597 engine, like plaintext messages, ciphertext, signatures and information
1598 about the keys. The technical details about exchanging the data
1599 information are completely abstracted by GPGME. The user provides and
1600 receives the data via ‘gpgme_data_t’ objects, regardless of the
1601 communication protocol between GPGME and the crypto engine in use.
1603 -- Data type: gpgme_data_t
1604 The ‘gpgme_data_t’ type is a handle for a container for generic
1605 data, which is used by GPGME to exchange data with the user.
1607 ‘gpgme_data_t’ objects do not provide notifications on events. It is
1608 assumed that read and write operations are blocking until data is
1609 available. If this is undesirable, the application must ensure that all
1610 GPGME data operations always have data available, for example by using
1611 memory buffers or files rather than pipes or sockets. This might be
1612 relevant, for example, if the external event loop mechanism is used.
1614 -- Data type: gpgme_off_t
1615 On POSIX platforms the ‘gpgme_off_t’ type is an alias for ‘off_t’;
1616 it may be used interchangeable. On Windows platforms ‘gpgme_off_t’
1617 is defined as a long (i.e. 32 bit) for 32 bit Windows and as a 64
1618 bit signed integer for 64 bit Windows.
1620 -- Data type: gpgme_ssize_t
1621 The ‘gpgme_ssize_t’ type is an alias for ‘ssize_t’. It has only
1622 been introduced to overcome portability problems pertaining to the
1623 declaration of ‘ssize_t’ by different toolchains.
1627 * Creating Data Buffers:: Creating new data buffers.
1628 * Destroying Data Buffers:: Releasing data buffers.
1629 * Manipulating Data Buffers:: Operations on data buffers.
1632 File: gpgme.info, Node: Creating Data Buffers, Next: Destroying Data Buffers, Up: Exchanging Data
1634 6.1 Creating Data Buffers
1635 =========================
1637 Data objects can be based on memory, files, or callback functions
1638 provided by the user. Not all operations are supported by all objects.
1642 * Memory Based Data Buffers:: Creating memory based data buffers.
1643 * File Based Data Buffers:: Creating file based data buffers.
1644 * Callback Based Data Buffers:: Creating callback based data buffers.
1647 File: gpgme.info, Node: Memory Based Data Buffers, Next: File Based Data Buffers, Up: Creating Data Buffers
1649 6.1.1 Memory Based Data Buffers
1650 -------------------------------
1652 Memory based data objects store all data in allocated memory. This is
1653 convenient, but only practical for an amount of data that is a fraction
1654 of the available physical memory. The data has to be copied from its
1655 source and to its destination, which can often be avoided by using one
1656 of the other data object
1658 -- Function: gpgme_error_t gpgme_data_new (gpgme_data_t *DH)
1659 The function ‘gpgme_data_new’ creates a new ‘gpgme_data_t’ object
1660 and returns a handle for it in DH. The data object is memory based
1661 and initially empty.
1663 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data
1664 object was successfully created, ‘GPG_ERR_INV_VALUE’ if DH is not a
1665 valid pointer, and ‘GPG_ERR_ENOMEM’ if not enough memory is
1668 -- Function: gpgme_error_t gpgme_data_new_from_mem (gpgme_data_t *DH,
1669 const char *BUFFER, size_t SIZE, int COPY)
1670 The function ‘gpgme_data_new_from_mem’ creates a new ‘gpgme_data_t’
1671 object and fills it with SIZE bytes starting from BUFFER.
1673 If COPY is not zero, a private copy of the data is made. If COPY
1674 is zero, the data is taken from the specified buffer as needed, and
1675 the user has to ensure that the buffer remains valid for the whole
1676 life span of the data object.
1678 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data
1679 object was successfully created, ‘GPG_ERR_INV_VALUE’ if DH or
1680 BUFFER is not a valid pointer, and ‘GPG_ERR_ENOMEM’ if not enough
1681 memory is available.
1683 -- Function: gpgme_error_t gpgme_data_new_from_file (gpgme_data_t *DH,
1684 const char *FILENAME, int COPY)
1685 The function ‘gpgme_data_new_from_file’ creates a new
1686 ‘gpgme_data_t’ object and fills it with the content of the file
1689 If COPY is not zero, the whole file is read in at initialization
1690 time and the file is not used anymore after that. This is the only
1691 mode supported currently. Later, a value of zero for COPY might
1692 cause all reads to be delayed until the data is needed, but this is
1693 not yet implemented.
1695 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data
1696 object was successfully created, ‘GPG_ERR_INV_VALUE’ if DH or
1697 FILENAME is not a valid pointer, ‘GPG_ERR_NOT_IMPLEMENTED’ if CODE
1698 is zero, and ‘GPG_ERR_ENOMEM’ if not enough memory is available.
1700 -- Function: gpgme_error_t gpgme_data_new_from_filepart
1701 (gpgme_data_t *DH, const char *FILENAME, FILE *FP,
1702 off_t OFFSET, size_t LENGTH)
1703 The function ‘gpgme_data_new_from_filepart’ creates a new
1704 ‘gpgme_data_t’ object and fills it with a part of the file
1705 specified by FILENAME or FP.
1707 Exactly one of FILENAME and FP must be non-zero, the other must be
1708 zero. The argument that is not zero specifies the file from which
1709 LENGTH bytes are read into the data object, starting from OFFSET.
1711 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data
1712 object was successfully created, ‘GPG_ERR_INV_VALUE’ if DH and
1713 exactly one of FILENAME and FP is not a valid pointer, and
1714 ‘GPG_ERR_ENOMEM’ if not enough memory is available.
1717 File: gpgme.info, Node: File Based Data Buffers, Next: Callback Based Data Buffers, Prev: Memory Based Data Buffers, Up: Creating Data Buffers
1719 6.1.2 File Based Data Buffers
1720 -----------------------------
1722 File based data objects operate directly on file descriptors or streams.
1723 Only a small amount of data is stored in core at any time, so the size
1724 of the data objects is not limited by GPGME.
1726 -- Function: gpgme_error_t gpgme_data_new_from_fd (gpgme_data_t *DH,
1728 The function ‘gpgme_data_new_from_fd’ creates a new ‘gpgme_data_t’
1729 object and uses the file descriptor FD to read from (if used as an
1730 input data object) and write to (if used as an output data object).
1732 When using the data object as an input buffer, the function might
1733 read a bit more from the file descriptor than is actually needed by
1734 the crypto engine in the desired operation because of internal
1737 Note that GPGME assumes that the file descriptor is set to blocking
1738 mode. Errors during I/O operations, except for EINTR, are usually
1739 fatal for crypto operations.
1741 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data
1742 object was successfully created, and ‘GPG_ERR_ENOMEM’ if not enough
1743 memory is available.
1745 -- Function: gpgme_error_t gpgme_data_new_from_stream
1746 (gpgme_data_t *DH, FILE *STREAM)
1747 The function ‘gpgme_data_new_from_stream’ creates a new
1748 ‘gpgme_data_t’ object and uses the I/O stream STREAM to read from
1749 (if used as an input data object) and write to (if used as an
1750 output data object).
1752 When using the data object as an input buffer, the function might
1753 read a bit more from the stream than is actually needed by the
1754 crypto engine in the desired operation because of internal
1757 Note that GPGME assumes that the stream is in blocking mode.
1758 Errors during I/O operations, except for EINTR, are usually fatal
1759 for crypto operations.
1761 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data
1762 object was successfully created, and ‘GPG_ERR_ENOMEM’ if not enough
1763 memory is available.
1766 File: gpgme.info, Node: Callback Based Data Buffers, Prev: File Based Data Buffers, Up: Creating Data Buffers
1768 6.1.3 Callback Based Data Buffers
1769 ---------------------------------
1771 If neither memory nor file based data objects are a good fit for your
1772 application, you can implement the functions a data object provides
1773 yourself and create a data object from these callback functions.
1775 -- Data type: ssize_t (*gpgme_data_read_cb_t) (void *HANDLE,
1776 void *BUFFER, size_t SIZE)
1777 The ‘gpgme_data_read_cb_t’ type is the type of functions which
1778 GPGME calls if it wants to read data from a user-implemented data
1779 object. The function should read up to SIZE bytes from the current
1780 read position into the space starting at BUFFER. The HANDLE is
1781 provided by the user at data object creation time.
1783 Note that GPGME assumes that the read blocks until data is
1784 available. Errors during I/O operations, except for EINTR, are
1785 usually fatal for crypto operations.
1787 The function should return the number of bytes read, 0 on EOF, and
1788 -1 on error. If an error occurs, ERRNO should be set to describe
1789 the type of the error.
1791 -- Data type: ssize_t (*gpgme_data_write_cb_t) (void *HANDLE,
1792 const void *BUFFER, size_t SIZE)
1793 The ‘gpgme_data_write_cb_t’ type is the type of functions which
1794 GPGME calls if it wants to write data to a user-implemented data
1795 object. The function should write up to SIZE bytes to the current
1796 write position from the space starting at BUFFER. The HANDLE is
1797 provided by the user at data object creation time.
1799 Note that GPGME assumes that the write blocks until data is
1800 available. Errors during I/O operations, except for EINTR, are
1801 usually fatal for crypto operations.
1803 The function should return the number of bytes written, and -1 on
1804 error. If an error occurs, ERRNO should be set to describe the
1807 -- Data type: off_t (*gpgme_data_seek_cb_t) (void *HANDLE,
1808 off_t OFFSET, int WHENCE)
1809 The ‘gpgme_data_seek_cb_t’ type is the type of functions which
1810 GPGME calls if it wants to change the current read/write position
1811 in a user-implemented data object, just like the ‘lseek’ function.
1813 The function should return the new read/write position, and -1 on
1814 error. If an error occurs, ERRNO should be set to describe the
1817 -- Data type: void (*gpgme_data_release_cb_t) (void *HANDLE)
1818 The ‘gpgme_data_release_cb_t’ type is the type of functions which
1819 GPGME calls if it wants to destroy a user-implemented data object.
1820 The HANDLE is provided by the user at data object creation time.
1822 -- Data type: struct gpgme_data_cbs
1823 This structure is used to store the data callback interface
1824 functions described above. It has the following members:
1826 ‘gpgme_data_read_cb_t read’
1827 This is the function called by GPGME to read data from the
1828 data object. It is only required for input data object.
1830 ‘gpgme_data_write_cb_t write’
1831 This is the function called by GPGME to write data to the data
1832 object. It is only required for output data object.
1834 ‘gpgme_data_seek_cb_t seek’
1835 This is the function called by GPGME to change the current
1836 read/write pointer in the data object (if available). It is
1839 ‘gpgme_data_release_cb_t release’
1840 This is the function called by GPGME to release a data object.
1843 -- Function: gpgme_error_t gpgme_data_new_from_cbs (gpgme_data_t *DH,
1844 gpgme_data_cbs_t CBS, void *HANDLE)
1845 The function ‘gpgme_data_new_from_cbs’ creates a new ‘gpgme_data_t’
1846 object and uses the user-provided callback functions to operate on
1849 The handle HANDLE is passed as first argument to the callback
1850 functions. This can be used to identify this data object.
1852 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data
1853 object was successfully created, and ‘GPG_ERR_ENOMEM’ if not enough
1854 memory is available.
1857 File: gpgme.info, Node: Destroying Data Buffers, Next: Manipulating Data Buffers, Prev: Creating Data Buffers, Up: Exchanging Data
1859 6.2 Destroying Data Buffers
1860 ===========================
1862 -- Function: void gpgme_data_release (gpgme_data_t DH)
1863 The function ‘gpgme_data_release’ destroys the data object with the
1864 handle DH. It releases all associated resources that were not
1865 provided by the user in the first place.
1867 -- Function: char * gpgme_data_release_and_get_mem (gpgme_data_t DH,
1869 The function ‘gpgme_data_release_and_get_mem’ is like
1870 ‘gpgme_data_release’, except that it returns the data buffer and
1871 its length that was provided by the object.
1873 The user has to release the buffer with ‘gpgme_free’. In case the
1874 user provided the data buffer in non-copy mode, a copy will be made
1877 In case an error returns, or there is no suitable data buffer that
1878 can be returned to the user, the function will return ‘NULL’. In
1879 any case, the data object DH is destroyed.
1881 -- Function: void gpgme_free (void *BUFFER)
1882 The function ‘gpgme_free’ releases the memory returned by
1883 ‘gpgme_data_release_and_get_mem’ and ‘gpgme_pubkey_algo_string’.
1884 It should be used instead of the system libraries ‘free’ function
1885 in case different allocators are used by a program. This is often
1886 the case if gpgme is used under Windows as a DLL.
1889 File: gpgme.info, Node: Manipulating Data Buffers, Prev: Destroying Data Buffers, Up: Exchanging Data
1891 6.3 Manipulating Data Buffers
1892 =============================
1894 Data buffers contain data and meta-data. The following operations can
1895 be used to manipulate both.
1899 * Data Buffer I/O Operations:: I/O operations on data buffers.
1900 * Data Buffer Meta-Data:: Meta-data manipulation of data buffers.
1901 * Data Buffer Convenience:: Convenience function for data buffers.
1904 File: gpgme.info, Node: Data Buffer I/O Operations, Next: Data Buffer Meta-Data, Up: Manipulating Data Buffers
1906 6.3.1 Data Buffer I/O Operations
1907 --------------------------------
1909 -- Function: ssize_t gpgme_data_read (gpgme_data_t DH, void *BUFFER,
1911 The function ‘gpgme_data_read’ reads up to LENGTH bytes from the
1912 data object with the handle DH into the space starting at BUFFER.
1914 If no error occurs, the actual amount read is returned. If the end
1915 of the data object is reached, the function returns 0.
1917 In all other cases, the function returns -1 and sets ERRNO.
1919 -- Function: ssize_t gpgme_data_write (gpgme_data_t DH,
1920 const void *BUFFER, size_t SIZE)
1921 The function ‘gpgme_data_write’ writes up to SIZE bytes starting
1922 from BUFFER into the data object with the handle DH at the current
1925 The function returns the number of bytes actually written, or -1 if
1926 an error occurs. If an error occurs, ERRNO is set.
1928 -- Function: off_t gpgme_data_seek (gpgme_data_t DH, off_t OFFSET,
1930 The function ‘gpgme_data_seek’ changes the current read/write
1933 The WHENCE argument specifies how the OFFSET should be interpreted.
1934 It must be one of the following symbolic constants:
1937 Specifies that OFFSET is a count of characters from the
1938 beginning of the data object.
1941 Specifies that OFFSET is a count of characters from the
1942 current file position. This count may be positive or
1946 Specifies that OFFSET is a count of characters from the end of
1947 the data object. A negative count specifies a position within
1948 the current extent of the data object; a positive count
1949 specifies a position past the current end. If you set the
1950 position past the current end, and actually write data, you
1951 will extend the data object with zeros up to that position.
1953 If successful, the function returns the resulting file position,
1954 measured in bytes from the beginning of the data object. You can
1955 use this feature together with ‘SEEK_CUR’ to read the current
1956 read/write position.
1958 If the function fails, -1 is returned and ERRNO is set.
1961 File: gpgme.info, Node: Data Buffer Meta-Data, Next: Data Buffer Convenience, Prev: Data Buffer I/O Operations, Up: Manipulating Data Buffers
1963 6.3.2 Data Buffer Meta-Data
1964 ---------------------------
1966 -- Function: char * gpgme_data_get_file_name (gpgme_data_t DH)
1967 The function ‘gpgme_data_get_file_name’ returns a pointer to a
1968 string containing the file name associated with the data object.
1969 The file name will be stored in the output when encrypting or
1970 signing the data and will be returned to the user when decrypting
1971 or verifying the output data.
1973 If no error occurs, the string containing the file name is
1974 returned. Otherwise, ‘NULL’ will be returned.
1976 -- Function: gpgme_error_t gpgme_data_set_file_name (gpgme_data_t DH,
1977 const char *FILE_NAME)
1978 The function ‘gpgme_data_set_file_name’ sets the file name
1979 associated with the data object. The file name will be stored in
1980 the output when encrypting or signing the data and will be returned
1981 to the user when decrypting or verifying the output data.
1983 The function returns the error code ‘GPG_ERR_INV_VALUE’ if DH is
1984 not a valid pointer and ‘GPG_ERR_ENOMEM’ if not enough memory is
1987 -- Data type: enum gpgme_data_encoding_t
1988 The ‘gpgme_data_encoding_t’ type specifies the encoding of a
1989 ‘gpgme_data_t’ object. For input data objects, the encoding is
1990 useful to give the backend a hint on the type of data. For output
1991 data objects, the encoding can specify the output data format on
1992 certain operations. Please note that not all backends support all
1993 encodings on all operations. The following data types are
1996 ‘GPGME_DATA_ENCODING_NONE’
1997 This specifies that the encoding is not known. This is the
1998 default for a new data object. The backend will try its best
1999 to detect the encoding automatically.
2001 ‘GPGME_DATA_ENCODING_BINARY’
2002 This specifies that the data is encoding in binary form; i.e.
2003 there is no special encoding.
2005 ‘GPGME_DATA_ENCODING_BASE64’
2006 This specifies that the data is encoded using the Base-64
2007 encoding scheme as used by MIME and other protocols.
2009 ‘GPGME_DATA_ENCODING_ARMOR’
2010 This specifies that the data is encoded in an armored form as
2011 used by OpenPGP and PEM.
2013 ‘GPGME_DATA_ENCODING_MIME’
2014 This specifies that the data is encoded as a MIME part.
2016 ‘GPGME_DATA_ENCODING_URL’
2017 The data is a list of linefeed delimited URLs. This is only
2018 useful with ‘gpgme_op_import’.
2020 ‘GPGME_DATA_ENCODING_URL0’
2021 The data is a list of binary zero delimited URLs. This is
2022 only useful with ‘gpgme_op_import’.
2024 ‘GPGME_DATA_ENCODING_URLESC’
2025 The data is a list of linefeed delimited URLs with all control
2026 and space characters percent escaped. This mode is is not yet
2029 -- Function: gpgme_data_encoding_t gpgme_data_get_encoding
2031 The function ‘gpgme_data_get_encoding’ returns the encoding of the
2032 data object with the handle DH. If DH is not a valid pointer (e.g.
2033 ‘NULL’) ‘GPGME_DATA_ENCODING_NONE’ is returned.
2035 -- Function: gpgme_error_t gpgme_data_set_encoding
2036 (gpgme_data_t DH, gpgme_data_encoding_t ENC)
2037 The function ‘gpgme_data_set_encoding’ changes the encoding of the
2038 data object with the handle DH to ENC.
2040 -- Function: gpgme_error_t gpgme_data_set_flag (gpgme_data_t DH,
2041 const char *NAME, const char *VALUE)
2043 Some minor properties of the data object can be controlled with
2044 flags set by this function. The properties are identified by the
2045 following values for NAME:
2048 The value is a decimal number with the length gpgme shall
2049 assume for this data object. This is useful if the data is
2050 provided by callbacks or via file descriptors but the
2051 applications knows the total size of the data. If this is set
2052 the OpenPGP engine may use this to decide on buffer allocation
2053 strategies and to provide a total value for its progress
2056 This function returns ‘0’ on success.
2059 File: gpgme.info, Node: Data Buffer Convenience, Prev: Data Buffer Meta-Data, Up: Manipulating Data Buffers
2061 6.3.3 Data Buffer Convenience Functions
2062 ---------------------------------------
2064 -- Data type: enum gpgme_data_type_t
2065 The ‘gpgme_data_type_t’ type is used to return the detected type of
2066 the content of a data buffer.
2068 ‘GPGME_DATA_TYPE_INVALID’
2069 This is returned by ‘gpgme_data_identify’ if it was not possible to
2070 identify the data. Reasons for this might be a non-seekable stream
2071 or a memory problem. The value is 0.
2072 ‘GPGME_DATA_TYPE_UNKNOWN’
2073 The type of the data is not known.
2074 ‘GPGME_DATA_TYPE_PGP_SIGNED’
2075 The data is an OpenPGP signed message. This may be a binary
2076 signature, a detached one or a cleartext signature.
2077 ‘GPGME_DATA_TYPE_PGP_OTHER’
2078 This is a generic OpenPGP message. In most cases this will be
2080 ‘GPGME_DATA_TYPE_PGP_KEY’
2081 This is an OpenPGP key (private or public).
2082 ‘GPGME_DATA_TYPE_CMS_SIGNED’
2083 This is a CMS signed message.
2084 ‘GPGME_DATA_TYPE_CMS_ENCRYPTED’
2085 This is a CMS encrypted (enveloped data) message.
2086 ‘GPGME_DATA_TYPE_CMS_OTHER’
2087 This is used for other CMS message types.
2088 ‘GPGME_DATA_TYPE_X509_CERT’
2089 The data is a X.509 certificate
2090 ‘GPGME_DATA_TYPE_PKCS12’
2091 The data is a PKCS#12 message. This is commonly used to exchange
2092 private keys for X.509.
2094 -- Function: gpgme_data_type_t gpgme_data_identify (gpgme_data_t DH)
2095 The function ‘gpgme_data_identify’ returns the type of the data
2096 with the handle DH. If it is not possible to perform the
2097 identification, the function returns zero
2098 (‘GPGME_DATA_TYPE_INVALID’). Note that depending on how the data
2099 object has been created the identification may not be possible or
2100 the data object may change its internal state (file pointer moved).
2101 For file or memory based data object, the state should not change.
2104 File: gpgme.info, Node: Contexts, Next: UI Server Protocol, Prev: Exchanging Data, Up: Top
2109 All cryptographic operations in GPGME are performed within a context,
2110 which contains the internal state of the operation as well as
2111 configuration parameters. By using several contexts you can run several
2112 cryptographic operations in parallel, with different configuration.
2114 -- Data type: gpgme_ctx_t
2115 The ‘gpgme_ctx_t’ type is a handle for a GPGME context, which is
2116 used to hold the configuration, status and result of cryptographic
2121 * Creating Contexts:: Creating new GPGME contexts.
2122 * Destroying Contexts:: Releasing GPGME contexts.
2123 * Result Management:: Managing the result of crypto operations.
2124 * Context Attributes:: Setting properties of a context.
2125 * Key Management:: Managing keys with GPGME.
2126 * Trust Item Management:: Managing trust items with GPGME.
2127 * Crypto Operations:: Using a context for cryptography.
2128 * Miscellaneous:: Miscellaneous operations
2129 * Run Control:: Controlling how operations are run.
2132 File: gpgme.info, Node: Creating Contexts, Next: Destroying Contexts, Up: Contexts
2134 7.1 Creating Contexts
2135 =====================
2137 -- Function: gpgme_error_t gpgme_new (gpgme_ctx_t *CTX)
2138 The function ‘gpgme_new’ creates a new ‘gpgme_ctx_t’ object and
2139 returns a handle for it in CTX.
2141 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
2142 context was successfully created, ‘GPG_ERR_INV_VALUE’ if CTX is not
2143 a valid pointer, and ‘GPG_ERR_ENOMEM’ if not enough memory is
2144 available. Also, it returns ‘GPG_ERR_NOT_OPERATIONAL’ if
2145 ‘gpgme_check_version’ was not called to initialize GPGME, and
2146 ‘GPG_ERR_SELFTEST_FAILED’ if a selftest failed. Currently, the
2147 only selftest is for Windows MingW32 targets to see if
2148 ‘-mms-bitfields’ was used (as required).
2151 File: gpgme.info, Node: Destroying Contexts, Next: Result Management, Prev: Creating Contexts, Up: Contexts
2153 7.2 Destroying Contexts
2154 =======================
2156 -- Function: void gpgme_release (gpgme_ctx_t CTX)
2157 The function ‘gpgme_release’ destroys the context with the handle
2158 CTX and releases all associated resources.
2161 File: gpgme.info, Node: Result Management, Next: Context Attributes, Prev: Destroying Contexts, Up: Contexts
2163 7.3 Result Management
2164 =====================
2166 The detailed result of an operation is returned in operation-specific
2167 structures such as ‘gpgme_decrypt_result_t’. The corresponding
2168 retrieval functions such as ‘gpgme_op_decrypt_result’ provide static
2169 access to the results after an operation completes. The following
2170 interfaces make it possible to detach a result structure from its
2171 associated context and give it a lifetime beyond that of the current
2172 operation or context.
2174 -- Function: void gpgme_result_ref (void *RESULT)
2175 The function ‘gpgme_result_ref’ acquires an additional reference
2176 for the result RESULT, which may be of any type ‘gpgme_*_result_t’.
2177 As long as the user holds a reference, the result structure is
2178 guaranteed to be valid and unmodified.
2180 -- Function: void gpgme_result_unref (void *RESULT)
2181 The function ‘gpgme_result_unref’ releases a reference for the
2182 result RESULT. If this was the last reference, the result
2183 structure will be destroyed and all resources associated to it will
2186 Note that a context may hold its own references to result structures,
2187 typically until the context is destroyed or the next operation is
2188 started. In fact, these references are accessed through the
2189 ‘gpgme_op_*_result’ functions.
2192 File: gpgme.info, Node: Context Attributes, Next: Key Management, Prev: Result Management, Up: Contexts
2194 7.4 Context Attributes
2195 ======================
2199 * Protocol Selection:: Selecting the protocol used by a context.
2200 * Crypto Engine:: Configuring the crypto engine.
2201 * ASCII Armor:: Requesting ASCII armored output.
2202 * Text Mode:: Choosing canonical text mode.
2203 * Offline Mode:: Choosing offline mode.
2204 * Pinentry Mode:: Choosing the pinentry mode.
2205 * Included Certificates:: Including a number of certificates.
2206 * Key Listing Mode:: Selecting key listing mode.
2207 * Passphrase Callback:: Getting the passphrase from the user.
2208 * Progress Meter Callback:: Being informed about the progress.
2209 * Status Message Callback:: Status messages received from gpg.
2210 * Locale:: Setting the locale of a context.
2213 File: gpgme.info, Node: Protocol Selection, Next: Crypto Engine, Up: Context Attributes
2215 7.4.1 Protocol Selection
2216 ------------------------
2218 -- Function: gpgme_error_t gpgme_set_protocol (gpgme_ctx_t CTX,
2219 gpgme_protocol_t PROTO)
2220 The function ‘gpgme_set_protocol’ sets the protocol used within the
2221 context CTX to PROTO. All crypto operations will be performed by
2222 the crypto engine configured for that protocol. *Note Protocols
2225 Setting the protocol with ‘gpgme_set_protocol’ does not check if
2226 the crypto engine for that protocol is available and installed
2227 correctly. *Note Engine Version Check::.
2229 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
2230 protocol could be set successfully, and ‘GPG_ERR_INV_VALUE’ if
2231 PROTOCOL is not a valid protocol.
2233 -- Function: gpgme_protocol_t gpgme_get_protocol (gpgme_ctx_t CTX)
2234 The function ‘gpgme_get_protocol’ retrieves the protocol currently
2235 use with the context CTX.
2238 File: gpgme.info, Node: Crypto Engine, Next: ASCII Armor, Prev: Protocol Selection, Up: Context Attributes
2243 The following functions can be used to set and retrieve the
2244 configuration of the crypto engines of a specific context. The default
2245 can also be retrieved without any particular context. *Note Engine
2246 Information::. The default can also be changed globally. *Note Engine
2249 -- Function: gpgme_engine_info_t gpgme_ctx_get_engine_info
2251 The function ‘gpgme_ctx_get_engine_info’ returns a linked list of
2252 engine info structures. Each info structure describes the
2253 configuration of one configured backend, as used by the context
2256 The result is valid until the next invocation of
2257 ‘gpgme_ctx_set_engine_info’ for this particular context.
2259 This function can not fail.
2261 -- Function: gpgme_error_t gpgme_ctx_set_engine_info (gpgme_ctx_t CTX,
2262 gpgme_protocol_t PROTO, const char *FILE_NAME,
2263 const char *HOME_DIR)
2264 The function ‘gpgme_ctx_set_engine_info’ changes the configuration
2265 of the crypto engine implementing the protocol PROTO for the
2268 FILE_NAME is the file name of the executable program implementing
2269 this protocol, and HOME_DIR is the directory name of the
2270 configuration directory for this crypto engine. If HOME_DIR is
2271 ‘NULL’, the engine’s default will be used.
2273 Currently this function must be used before starting the first
2274 crypto operation. It is unspecified if and when the changes will
2275 take effect if the function is called after starting the first
2276 operation on the context CTX.
2278 This function returns the error code ‘GPG_ERR_NO_ERROR’ if
2279 successful, or an eror code on failure.
2282 File: gpgme.info, Node: ASCII Armor, Next: Text Mode, Prev: Crypto Engine, Up: Context Attributes
2287 -- Function: void gpgme_set_armor (gpgme_ctx_t CTX, int YES)
2288 The function ‘gpgme_set_armor’ specifies if the output should be
2289 ASCII armored. By default, output is not ASCII armored.
2291 ASCII armored output is disabled if YES is zero, and enabled
2294 -- Function: int gpgme_get_armor (gpgme_ctx_t CTX)
2295 The function ‘gpgme_get_armor’ returns 1 if the output is ASCII
2296 armored, and ‘0’ if it is not, or if CTX is not a valid pointer.
2299 File: gpgme.info, Node: Text Mode, Next: Offline Mode, Prev: ASCII Armor, Up: Context Attributes
2304 -- Function: void gpgme_set_textmode (gpgme_ctx_t CTX, int YES)
2305 The function ‘gpgme_set_textmode’ specifies if canonical text mode
2306 should be used. By default, text mode is not used.
2308 Text mode is for example used for the RFC2015 signatures; note that
2309 the updated RFC 3156 mandates that the mail user agent does some
2310 preparations so that text mode is not needed anymore.
2312 This option is only relevant to the OpenPGP crypto engine, and
2313 ignored by all other engines.
2315 Canonical text mode is disabled if YES is zero, and enabled
2318 -- Function: int gpgme_get_textmode (gpgme_ctx_t CTX)
2319 The function ‘gpgme_get_textmode’ returns 1 if canonical text mode
2320 is enabled, and ‘0’ if it is not, or if CTX is not a valid pointer.
2323 File: gpgme.info, Node: Offline Mode, Next: Pinentry Mode, Prev: Text Mode, Up: Context Attributes
2328 -- Function: void gpgme_set_offline (gpgme_ctx_t CTX, int YES)
2329 The function ‘gpgme_set_offline’ specifies if offline mode should
2330 be used. By default, offline mode is not used.
2332 The offline mode specifies if dirmngr should be used to do
2333 additional validation that might require connections to external
2334 services. (e.g. CRL / OCSP checks).
2336 Offline mode only affects the keylist mode
2337 ‘GPGME_KEYLIST_MODE_VALIDATE’ and is only relevant to the CMS
2338 crypto engine. Offline mode is ignored otherwise.
2340 This option may be extended in the future to completely disable the
2341 use of dirmngr for any engine.
2343 Offline mode is disabled if YES is zero, and enabled otherwise.
2345 -- Function: int gpgme_get_offline (gpgme_ctx_t CTX)
2346 The function ‘gpgme_get_offline’ returns 1 if offline mode is
2347 enabled, and ‘0’ if it is not, or if CTX is not a valid pointer.
2350 File: gpgme.info, Node: Pinentry Mode, Next: Included Certificates, Prev: Offline Mode, Up: Context Attributes
2355 -- Function: gpgme_error_t gpgme_set_pinentry_mode (gpgme_ctx_t CTX,
2356 gpgme_pinentry_mode_t MODE) The function ‘gpgme_set_pinentry_mode’
2357 specifies the pinentry mode to be used.
2359 For GnuPG >= 2.1 this option is required to be set to
2360 ‘GPGME_PINENTRY_MODE_LOOPBACK’ to enable the passphrase callback
2361 mechanism in GPGME through ‘gpgme_set_passphrase_cb’.
2363 -- Function: gpgme_pinentry_mode_t gpgme_get_pinentry_mode
2365 The function ‘gpgme_get_pinenty_mode’ returns the mode set for the
2368 -- Data type: enum gpgme_pinentry_mode_t
2369 The ‘gpgme_minentry_mode_t’ type specifies the set of possible
2370 pinentry modes that are supported by GPGME if GnuPG >= 2.1 is used.
2371 The following modes are supported:
2373 ‘GPGME_PINENTRY_MODE_DEFAULT’
2374 Use the default of the agent, which is ask.
2376 ‘GPGME_PINENTRY_MODE_ASK’
2377 Force the use of the Pinentry.
2379 ‘GPGME_PINENTRY_MODE_CANCEL’
2380 Emulate use of Pinentry’s cancel button.
2382 ‘GPGME_PINENTRY_MODE_ERROR’
2383 Return a Pinentry error ‘No Pinentry’.
2385 ‘GPGME_PINENTRY_MODE_LOOPBACK’
2386 Redirect Pinentry queries to the caller. This enables the use
2387 of ‘gpgme_set_passphrase_cb’ whis pinentry queries redirected
2390 Note: This mode requires ‘allow-loopback-pinentry’ to be
2391 enabled in the ‘gpg-agent.conf’ or an agent started with that
2395 File: gpgme.info, Node: Included Certificates, Next: Key Listing Mode, Prev: Pinentry Mode, Up: Context Attributes
2397 7.4.7 Included Certificates
2398 ---------------------------
2400 -- Function: void gpgme_set_include_certs (gpgme_ctx_t CTX,
2402 The function ‘gpgme_set_include_certs’ specifies how many
2403 certificates should be included in an S/MIME signed message. By
2404 default, only the sender’s certificate is included. The possible
2405 values of NR_OF_CERTS are:
2407 ‘GPGME_INCLUDE_CERTS_DEFAULT’
2408 Fall back to the default of the crypto backend. This is the
2411 Include all certificates except the root certificate.
2413 Include all certificates.
2415 Include no certificates.
2417 Include the sender’s certificate only.
2419 Include the first n certificates of the certificates path,
2420 starting from the sender’s certificate. The number ‘n’ must
2423 Values of NR_OF_CERTS smaller than -2 are undefined.
2425 This option is only relevant to the CMS crypto engine, and ignored
2426 by all other engines.
2428 -- Function: int gpgme_get_include_certs (gpgme_ctx_t CTX)
2429 The function ‘gpgme_get_include_certs’ returns the number of
2430 certificates to include into an S/MIME signed message.
2433 File: gpgme.info, Node: Key Listing Mode, Next: Passphrase Callback, Prev: Included Certificates, Up: Context Attributes
2435 7.4.8 Key Listing Mode
2436 ----------------------
2438 -- Function: gpgme_error_t gpgme_set_keylist_mode (gpgme_ctx_t CTX,
2439 gpgme_keylist_mode_t MODE)
2440 The function ‘gpgme_set_keylist_mode’ changes the default behaviour
2441 of the key listing functions. The value in MODE is a bitwise-or
2442 combination of one or multiple of the following bit values:
2444 ‘GPGME_KEYLIST_MODE_LOCAL’
2445 The ‘GPGME_KEYLIST_MODE_LOCAL’ symbol specifies that the local
2446 keyring should be searched for keys in the keylisting
2447 operation. This is the default.
2449 ‘GPGME_KEYLIST_MODE_EXTERN’
2450 The ‘GPGME_KEYLIST_MODE_EXTERN’ symbol specifies that an
2451 external source should be searched for keys in the keylisting
2452 operation. The type of external source is dependant on the
2453 crypto engine used and whether it is combined with
2454 ‘GPGME_KEYLIST_MODE_LOCAL’. For example, it can be a remote
2455 keyserver or LDAP certificate server.
2457 ‘GPGME_KEYLIST_MODE_SIGS’
2458 The ‘GPGME_KEYLIST_MODE_SIGS’ symbol specifies that the key
2459 signatures should be included in the listed keys.
2461 ‘GPGME_KEYLIST_MODE_SIG_NOTATIONS’
2462 The ‘GPGME_KEYLIST_MODE_SIG_NOTATIONS’ symbol specifies that
2463 the signature notations on key signatures should be included
2464 in the listed keys. This only works if
2465 ‘GPGME_KEYLIST_MODE_SIGS’ is also enabled.
2467 ‘GPGME_KEYLIST_MODE_WITH_TOFU’
2468 The ‘GPGME_KEYLIST_MODE_WITH_TOFU’ symbol specifies that
2469 information pertaining to the TOFU trust model should be
2470 included in the listed keys.
2472 ‘GPGME_KEYLIST_MODE_WITH_SECRET’
2473 The ‘GPGME_KEYLIST_MODE_WITH_SECRET’ returns information about
2474 the presence of a corresponding secret key in a public key
2475 listing. A public key listing with this mode is slower than a
2476 standard listing but can be used instead of a second run to
2477 list the secret keys. This is only supported for GnuPG
2480 ‘GPGME_KEYLIST_MODE_EPHEMERAL’
2481 The ‘GPGME_KEYLIST_MODE_EPHEMERAL’ symbol specifies that keys
2482 flagged as ephemeral are included in the listing.
2484 ‘GPGME_KEYLIST_MODE_VALIDATE’
2485 The ‘GPGME_KEYLIST_MODE_VALIDATE’ symbol specifies that the
2486 backend should do key or certificate validation and not just
2487 get the validity information from an internal cache. This
2488 might be an expensive operation and is in general not useful.
2489 Currently only implemented for the S/MIME backend and ignored
2492 At least one of ‘GPGME_KEYLIST_MODE_LOCAL’ and
2493 ‘GPGME_KEYLIST_MODE_EXTERN’ must be specified. For future binary
2494 compatibility, you should get the current mode with
2495 ‘gpgme_get_keylist_mode’ and modify it by setting or clearing the
2496 appropriate bits, and then using that calculated value in the
2497 ‘gpgme_set_keylisting_mode’ operation. This will leave all other
2498 bits in the mode value intact (in particular those that are not
2499 used in the current version of the library).
2501 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the mode
2502 could be set correctly, and ‘GPG_ERR_INV_VALUE’ if CTX is not a
2503 valid pointer or MODE is not a valid mode.
2505 -- Function: gpgme_keylist_mode_t gpgme_get_keylist_mode
2507 The function ‘gpgme_get_keylist_mode’ returns the current key
2508 listing mode of the context CTX. This value can then be modified
2509 and used in a subsequent ‘gpgme_set_keylist_mode’ operation to only
2510 affect the desired bits (and leave all others intact).
2512 The function returns 0 if CTX is not a valid pointer, and the
2513 current mode otherwise. Note that 0 is not a valid mode value.
2516 File: gpgme.info, Node: Passphrase Callback, Next: Progress Meter Callback, Prev: Key Listing Mode, Up: Context Attributes
2518 7.4.9 Passphrase Callback
2519 -------------------------
2521 -- Data type: gpgme_error_t (*gpgme_passphrase_cb_t)(void *HOOK, const
2522 char *UID_HINT, const char *PASSPHRASE_INFO, int PREV_WAS_BAD,
2524 The ‘gpgme_passphrase_cb_t’ type is the type of functions usable as
2525 passphrase callback function.
2527 The argument UID_HINT might contain a string that gives an
2528 indication for which user ID the passphrase is required. If this
2529 is not available, or not applicable (in the case of symmetric
2530 encryption, for example), UID_HINT will be ‘NULL’.
2532 The argument PASSPHRASE_INFO, if not ‘NULL’, will give further
2533 information about the context in which the passphrase is required.
2534 This information is engine and operation specific.
2536 If this is the repeated attempt to get the passphrase, because
2537 previous attempts failed, then PREV_WAS_BAD is 1, otherwise it will
2540 The user must write the passphrase, followed by a newline
2541 character, to the file descriptor FD. The function
2542 ‘gpgme_io_writen’ should be used for the write operation. Note
2543 that if the user returns 0 to indicate success, the user must at
2544 least write a newline character before returning from the callback.
2546 If an error occurs, return the corresponding ‘gpgme_error_t’ value.
2547 You can use the error code ‘GPG_ERR_CANCELED’ to abort the
2548 operation. Otherwise, return ‘0’.
2550 -- Function: void gpgme_set_passphrase_cb (gpgme_ctx_t CTX,
2551 gpgme_passphrase_cb_t PASSFUNC, void *HOOK_VALUE)
2552 The function ‘gpgme_set_passphrase_cb’ sets the function that is
2553 used when a passphrase needs to be provided by the user to
2554 PASSFUNC. The function PASSFUNC needs to implemented by the user,
2555 and whenever it is called, it is called with its first argument
2556 being HOOK_VALUE. By default, no passphrase callback function is
2559 Not all crypto engines require this callback to retrieve the
2560 passphrase. It is better if the engine retrieves the passphrase
2561 from a trusted agent (a daemon process), rather than having each
2562 user to implement their own passphrase query. Some engines do not
2563 even support an external passphrase callback at all, in this case
2564 the error code ‘GPG_ERR_NOT_SUPPORTED’ is returned.
2566 For GnuPG >= 2.1 the pinentry mode has to be set to
2567 ‘GPGME_PINENTRY_MODE_LOOPBACK’ to enable the passphrase callback.
2568 See ‘gpgme_set_pinentry_mode’.
2570 The user can disable the use of a passphrase callback function by
2571 calling ‘gpgme_set_passphrase_cb’ with PASSFUNC being ‘NULL’.
2573 -- Function: void gpgme_get_passphrase_cb (gpgme_ctx_t CTX,
2574 gpgme_passphrase_cb_t *PASSFUNC, void **HOOK_VALUE)
2575 The function ‘gpgme_get_passphrase_cb’ returns the function that is
2576 used when a passphrase needs to be provided by the user in
2577 *PASSFUNC, and the first argument for this function in *HOOK_VALUE.
2578 If no passphrase callback is set, or CTX is not a valid pointer,
2579 ‘NULL’ is returned in both variables.
2581 PASSFUNC or HOOK_VALUE can be ‘NULL’. In this case, the
2582 corresponding value will not be returned.
2585 File: gpgme.info, Node: Progress Meter Callback, Next: Status Message Callback, Prev: Passphrase Callback, Up: Context Attributes
2587 7.4.10 Progress Meter Callback
2588 ------------------------------
2590 -- Data type: void (*gpgme_progress_cb_t)(void *HOOK, const char *WHAT,
2591 int TYPE, int CURRENT, int TOTAL)
2592 The ‘gpgme_progress_cb_t’ type is the type of functions usable as
2593 progress callback function.
2595 The arguments are specific to the crypto engine. More information
2596 about the progress information returned from the GnuPG engine can
2597 be found in the GnuPG source code in the file ‘doc/DETAILS’ in the
2600 -- Function: void gpgme_set_progress_cb (gpgme_ctx_t CTX,
2601 gpgme_progress_cb_t PROGFUNC, void *HOOK_VALUE)
2602 The function ‘gpgme_set_progress_cb’ sets the function that is used
2603 when progress information about a cryptographic operation is
2604 available. The function PROGFUNC needs to implemented by the user,
2605 and whenever it is called, it is called with its first argument
2606 being HOOK_VALUE. By default, no progress callback function is
2609 Setting a callback function allows an interactive program to
2610 display progress information about a long operation to the user.
2612 The user can disable the use of a progress callback function by
2613 calling ‘gpgme_set_progress_cb’ with PROGFUNC being ‘NULL’.
2615 -- Function: void gpgme_get_progress_cb (gpgme_ctx_t CTX,
2616 gpgme_progress_cb_t *PROGFUNC, void **HOOK_VALUE)
2617 The function ‘gpgme_get_progress_cb’ returns the function that is
2618 used to inform the user about the progress made in *PROGFUNC, and
2619 the first argument for this function in *HOOK_VALUE. If no
2620 progress callback is set, or CTX is not a valid pointer, ‘NULL’ is
2621 returned in both variables.
2623 PROGFUNC or HOOK_VALUE can be ‘NULL’. In this case, the
2624 corresponding value will not be returned.
2627 File: gpgme.info, Node: Status Message Callback, Next: Locale, Prev: Progress Meter Callback, Up: Context Attributes
2629 7.4.11 Status Message Callback
2630 ------------------------------
2632 -- Data type: gpgme_error_t (*gpgme_status_cb_t)(void *HOOK, const char
2633 *KEYWORD, const char *ARGS)
2634 The ‘gpgme_status_cb_t’ type is the type of function usable as a
2635 status message callback function.
2637 The argument KEYWORD is the name of the status message while the
2638 ARGS argument contains any arguments for the status message.
2640 If an error occurs, return the corresponding ‘gpgme_error_t’ value.
2641 Otherwise, return ‘0’.
2643 -- Function: void gpgme_set_status_cb (gpgme_ctx_t CTX,
2644 gpgme_status_cb_t STATUSFUNC, void *HOOK_VALUE)
2645 The function ‘gpgme_set_status_cb’ sets the function that is used
2646 when a status message is received from gpg to STATUSFUNC. The
2647 function STATUSFUNC needs to be implemented by the user, and
2648 whenever it is called, it is called with its first argument being
2649 HOOK_VALUE. By default, no status message callback function is
2652 The user can disable the use of a status message callback function
2653 by calling ‘gpgme_set_status_cb’ with STATUSFUNC being ‘NULL’.
2655 -- Function: void gpgme_get_status_cb (gpgme_ctx_t CTX,
2656 gpgme_status_cb_t *STATUSFUNC, void **HOOK_VALUE)
2657 The function ‘gpgme_get_status_cb’ returns the function that is
2658 used to process status messages from gpg in *STATUSFUNC, and the
2659 first argument for this function in *HOOK_VALUE. If no status
2660 message callback is set, or CTX is not a valid pointer, ‘NULL’ is
2661 returned in both variables.
2663 -- Function: gpgme_error_t gpgme_set_ctx_flag (gpgme_ctx_t CTX,
2664 const char *NAME, const char *VALUE)
2666 Some minor properties of the context can be controlled with flags
2667 set by this function. The properties are identified by the
2668 following values for NAME:
2671 Using a VALUE of "1" the status callback set by
2672 gpgme_set_status_cb returns all status lines with the
2673 exception of PROGRESS lines. With the default of "0" the
2674 status callback is only called in certain situations.
2677 Setting the VALUE to "1" returns human readable strings in a
2678 raw format. For example the non breaking space characters
2679 ("~") will not be removed from the ‘description’ field of the
2680 ‘gpgme_tofu_info_t’ object.
2682 This function returns ‘0’ on success.
2685 File: gpgme.info, Node: Locale, Prev: Status Message Callback, Up: Context Attributes
2690 A locale setting can be associated with a context. This locale is
2691 passed to the crypto engine, and used for applications like the PIN
2692 entry, which is displayed to the user when entering a passphrase is
2695 The default locale is used to initialize the locale setting of all
2696 contexts created afterwards.
2698 -- Function: gpgme_error_t gpgme_set_locale (gpgme_ctx_t CTX,
2699 int CATEGORY, const char *VALUE)
2700 The function ‘gpgme_set_locale’ sets the locale of the context CTX,
2701 or the default locale if CTX is a null pointer.
2703 The locale settings that should be changed are specified by
2704 CATEGORY. Supported categories are ‘LC_CTYPE’, ‘LC_MESSAGES’, and
2705 ‘LC_ALL’, which is a wildcard you can use if you want to change all
2706 the categories at once.
2708 The value to be used for the locale setting is VALUE, which will be
2709 copied to GPGME’s internal data structures. VALUE can be a null
2710 pointer, which disables setting the locale, and will make PIN entry
2711 and other applications use their default setting, which is usually
2714 Note that the settings are only used if the application runs on a
2715 text terminal, and that the settings should fit the configuration
2716 of the output terminal. Normally, it is sufficient to initialize
2717 the default value at startup.
2719 The function returns an error if not enough memory is available.
2722 File: gpgme.info, Node: Key Management, Next: Trust Item Management, Prev: Context Attributes, Up: Contexts
2727 Some of the cryptographic operations require that recipients or signers
2728 are specified. This is always done by specifying the respective keys
2729 that should be used for the operation. The following section describes
2730 how such keys can be selected and manipulated.
2734 * Key objects:: Description of the key structures.
2735 * Listing Keys:: Browsing the list of available keys.
2736 * Information About Keys:: Requesting detailed information about keys.
2737 * Manipulating Keys:: Operations on keys.
2738 * Generating Keys:: Creating new key pairs.
2739 * Signing Keys:: Adding key signatures to public keys.
2740 * Exporting Keys:: Retrieving key data from the key ring.
2741 * Importing Keys:: Adding keys to the key ring.
2742 * Deleting Keys:: Removing keys from the key ring.
2743 * Changing Passphrases:: Change the passphrase of a key.
2744 * Changing TOFU Data:: Changing data pertaining to TOFU.
2745 * Advanced Key Editing:: Advanced key edit operation.
2748 File: gpgme.info, Node: Key objects, Next: Listing Keys, Up: Key Management
2753 The keys are represented in GPGME by structures which may only be read
2754 by the application but never be allocated or changed. They are valid as
2755 long as the key object itself is valid.
2757 -- Data type: gpgme_key_t
2759 The ‘gpgme_key_t’ type is a pointer to a key object. It has the
2762 ‘gpgme_keylist_mode_t keylist_mode’
2763 The keylist mode that was active when the key was retrieved.
2765 ‘unsigned int revoked : 1’
2766 This is true if the key is revoked.
2768 ‘unsigned int expired : 1’
2769 This is true if the key is expired.
2771 ‘unsigned int disabled : 1’
2772 This is true if the key is disabled.
2774 ‘unsigned int invalid : 1’
2775 This is true if the key is invalid. This might have several
2776 reasons, for a example for the S/MIME backend, it will be set
2777 during key listings if the key could not be validated due to
2778 missing certificates or unmatched policies.
2780 ‘unsigned int can_encrypt : 1’
2781 This is true if the key (ie one of its subkeys) can be used
2784 ‘unsigned int can_sign : 1’
2785 This is true if the key (ie one of its subkeys) can be used to
2786 create data signatures.
2788 ‘unsigned int can_certify : 1’
2789 This is true if the key (ie one of its subkeys) can be used to
2790 create key certificates.
2792 ‘unsigned int can_authenticate : 1’
2793 This is true if the key (ie one of its subkeys) can be used
2796 ‘unsigned int is_qualified : 1’
2797 This is true if the key can be used for qualified signatures
2798 according to local government regulations.
2800 ‘unsigned int secret : 1’
2801 This is true if the key is a secret key. Note, that this will
2802 always be true even if the corresponding subkey flag may be
2803 false (offline/stub keys). This is only set if a listing of
2804 secret keys has been requested or if
2805 ‘GPGME_KEYLIST_MODE_WITH_SECRET’ is active.
2807 ‘gpgme_protocol_t protocol’
2808 This is the protocol supported by this key.
2810 ‘char *issuer_serial’
2811 If ‘protocol’ is ‘GPGME_PROTOCOL_CMS’, then this is the issuer
2815 If ‘protocol’ is ‘GPGME_PROTOCOL_CMS’, then this is the issuer
2819 If ‘protocol’ is ‘GPGME_PROTOCOL_CMS’, then this is the chain
2820 ID, which can be used to built the certificate chain.
2822 ‘gpgme_validity_t owner_trust’
2823 If ‘protocol’ is ‘GPGME_PROTOCOL_OpenPGP’, then this is the
2826 ‘gpgme_subkey_t subkeys’
2827 This is a linked list with the subkeys of the key. The first
2828 subkey in the list is the primary key and usually available.
2830 ‘gpgme_user_id_t uids’
2831 This is a linked list with the user IDs of the key. The first
2832 user ID in the list is the main (or primary) user ID.
2835 This field gives the fingerprint of the primary key. Note
2836 that this is a copy of the fingerprint of the first subkey.
2837 For an incomplete key (for example from a verification result)
2838 a subkey may be missing but this field may be set
2841 -- Data type: gpgme_subkey_t
2843 The ‘gpgme_subkey_t’ type is a pointer to a subkey structure.
2844 Subkeys are one component of a ‘gpgme_key_t’ object. In fact,
2845 subkeys are those parts that contains the real information about
2846 the individual cryptographic keys that belong to the same key
2847 object. One ‘gpgme_key_t’ can contain several subkeys. The first
2848 subkey in the linked list is also called the primary key.
2850 The subkey structure has the following members:
2852 ‘gpgme_subkey_t next’
2853 This is a pointer to the next subkey structure in the linked
2854 list, or ‘NULL’ if this is the last element.
2856 ‘unsigned int revoked : 1’
2857 This is true if the subkey is revoked.
2859 ‘unsigned int expired : 1’
2860 This is true if the subkey is expired.
2862 ‘unsigned int disabled : 1’
2863 This is true if the subkey is disabled.
2865 ‘unsigned int invalid : 1’
2866 This is true if the subkey is invalid.
2868 ‘unsigned int can_encrypt : 1’
2869 This is true if the subkey can be used for encryption.
2871 ‘unsigned int can_sign : 1’
2872 This is true if the subkey can be used to create data
2875 ‘unsigned int can_certify : 1’
2876 This is true if the subkey can be used to create key
2879 ‘unsigned int can_authenticate : 1’
2880 This is true if the subkey can be used for authentication.
2882 ‘unsigned int is_qualified : 1’
2883 This is true if the subkey can be used for qualified
2884 signatures according to local government regulations.
2886 ‘unsigned int secret : 1’
2887 This is true if the subkey is a secret key. Note that it will
2888 be false if the key is actually a stub key; i.e. a secret key
2889 operation is currently not possible (offline-key). This is
2890 only set if a listing of secret keys has been requested or if
2891 ‘GPGME_KEYLIST_MODE_WITH_SECRET’ is active.
2893 ‘gpgme_pubkey_algo_t pubkey_algo’
2894 This is the public key algorithm supported by this subkey.
2896 ‘unsigned int length’
2897 This is the length of the subkey (in bits).
2900 This is the key ID of the subkey in hexadecimal digits.
2903 This is the fingerprint of the subkey in hexadecimal digits,
2907 The keygrip of the subkey in hex digit form or ‘NULL’ if not
2910 ‘long int timestamp’
2911 This is the creation timestamp of the subkey. This is -1 if
2912 the timestamp is invalid, and 0 if it is not available.
2915 This is the expiration timestamp of the subkey, or 0 if the
2916 subkey does not expire.
2918 ‘unsigned int is_cardkey : 1’
2919 True if the secret key is stored on a smart card.
2922 The serial number of a smart card holding this key or ‘NULL’.
2925 For ECC algorithms the name of the curve.
2927 -- Data type: gpgme_user_id_t
2929 A user ID is a component of a ‘gpgme_key_t’ object. One key can
2930 have many user IDs. The first one in the list is the main (or
2933 The user ID structure has the following members.
2935 ‘gpgme_user_id_t next’
2936 This is a pointer to the next user ID structure in the linked
2937 list, or ‘NULL’ if this is the last element.
2939 ‘unsigned int revoked : 1’
2940 This is true if the user ID is revoked.
2942 ‘unsigned int invalid : 1’
2943 This is true if the user ID is invalid.
2945 ‘gpgme_validity_t validity’
2946 This specifies the validity of the user ID.
2949 This is the user ID string.
2952 This is the name component of ‘uid’, if available.
2955 This is the comment component of ‘uid’, if available.
2958 This is the email component of ‘uid’, if available.
2961 The mail address (addr-spec from RFC-5322) of the user ID
2962 string. This is general the same as the ‘email’ part of this
2963 structure but might be slightly different. If no mail address
2964 is available ‘NULL’ is stored.
2966 ‘gpgme_tofu_info_t tofu’
2967 If not ‘NULL’ information from the TOFU database pertaining to
2970 ‘gpgme_key_sig_t signatures’
2971 This is a linked list with the signatures on this user ID.
2973 -- Data type: gpgme_key_sig_t
2975 The ‘gpgme_key_sig_t’ type is a pointer to a key signature
2976 structure. Key signatures are one component of a ‘gpgme_key_t’
2977 object, and validate user IDs on the key in the OpenPGP protocol.
2979 The signatures on a key are only available if the key was retrieved
2980 via a listing operation with the ‘GPGME_KEYLIST_MODE_SIGS’ mode
2981 enabled, because it can be expensive to retrieve all signatures of
2984 The signature notations on a key signature are only available if
2985 the key was retrieved via a listing operation with the
2986 ‘GPGME_KEYLIST_MODE_SIG_NOTATIONS’ mode enabled, because it can be
2987 expensive to retrieve all signature notations.
2989 The key signature structure has the following members:
2991 ‘gpgme_key_sig_t next’
2992 This is a pointer to the next key signature structure in the
2993 linked list, or ‘NULL’ if this is the last element.
2995 ‘unsigned int revoked : 1’
2996 This is true if the key signature is a revocation signature.
2998 ‘unsigned int expired : 1’
2999 This is true if the key signature is expired.
3001 ‘unsigned int invalid : 1’
3002 This is true if the key signature is invalid.
3004 ‘unsigned int exportable : 1’
3005 This is true if the key signature is exportable.
3007 ‘gpgme_pubkey_algo_t pubkey_algo’
3008 This is the public key algorithm used to create the signature.
3011 This is the key ID of the key (in hexadecimal digits) used to
3012 create the signature.
3014 ‘long int timestamp’
3015 This is the creation timestamp of the key signature. This is
3016 -1 if the timestamp is invalid, and 0 if it is not available.
3019 This is the expiration timestamp of the key signature, or 0 if
3020 the key signature does not expire.
3022 ‘gpgme_error_t status’
3023 This is the status of the signature and has the same meaning
3024 as the member of the same name in a ‘gpgme_signature_t’
3027 ‘unsigned int sig_class’
3028 This specifies the signature class of the key signature. The
3029 meaning is specific to the crypto engine.
3032 This is the main user ID of the key used to create the
3036 This is the name component of ‘uid’, if available.
3039 This is the comment component of ‘uid’, if available.
3042 This is the email component of ‘uid’, if available.
3044 ‘gpgme_sig_notation_t notations’
3045 This is a linked list with the notation data and policy URLs.
3048 File: gpgme.info, Node: Listing Keys, Next: Information About Keys, Prev: Key objects, Up: Key Management
3053 -- Function: gpgme_error_t gpgme_op_keylist_start (gpgme_ctx_t CTX,
3054 const char *PATTERN, int SECRET_ONLY)
3055 The function ‘gpgme_op_keylist_start’ initiates a key listing
3056 operation inside the context CTX. It sets everything up so that
3057 subsequent invocations of ‘gpgme_op_keylist_next’ return the keys
3060 If PATTERN is ‘NULL’, all available keys are returned. Otherwise,
3061 PATTERN contains an engine specific expression that is used to
3062 limit the list to all keys matching the pattern. Note that the
3063 total length of the pattern is restricted to an engine-specific
3064 maximum (a couple of hundred characters are usually accepted). The
3065 pattern should be used to restrict the search to a certain common
3066 name or user, not to list many specific keys at once by listing
3067 their fingerprints or key IDs.
3069 If SECRET_ONLY is not ‘0’, the list is restricted to secret keys
3072 The context will be busy until either all keys are received (and
3073 ‘gpgme_op_keylist_next’ returns ‘GPG_ERR_EOF’), or
3074 ‘gpgme_op_keylist_end’ is called to finish the operation.
3076 The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX is
3077 not a valid pointer, and passes through any errors that are
3078 reported by the crypto engine support routines.
3080 -- Function: gpgme_error_t gpgme_op_keylist_ext_start (gpgme_ctx_t CTX,
3081 const char *PATTERN[], int SECRET_ONLY, int RESERVED)
3082 The function ‘gpgme_op_keylist_ext_start’ initiates an extended key
3083 listing operation inside the context CTX. It sets everything up so
3084 that subsequent invocations of ‘gpgme_op_keylist_next’ return the
3087 If PATTERN or *PATTERN is ‘NULL’, all available keys are returned.
3088 Otherwise, PATTERN is a ‘NULL’ terminated array of strings that are
3089 used to limit the list to all keys matching at least one of the
3090 patterns verbatim. Note that the total length of all patterns is
3091 restricted to an engine-specific maximum (the exact limit also
3092 depends on the number of patterns and amount of quoting required,
3093 but a couple of hundred characters are usually accepted). Patterns
3094 should be used to restrict the search to a certain common name or
3095 user, not to list many specific keys at once by listing their
3096 fingerprints or key IDs.
3098 If SECRET_ONLY is not ‘0’, the list is restricted to secret keys
3101 The value of RESERVED must be ‘0’.
3103 The context will be busy until either all keys are received (and
3104 ‘gpgme_op_keylist_next’ returns ‘GPG_ERR_EOF’), or
3105 ‘gpgme_op_keylist_end’ is called to finish the operation.
3107 The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX is
3108 not a valid pointer, and passes through any errors that are
3109 reported by the crypto engine support routines.
3111 -- Function: gpgme_error_t gpgme_op_keylist_next (gpgme_ctx_t CTX,
3113 The function ‘gpgme_op_keylist_next’ returns the next key in the
3114 list created by a previous ‘gpgme_op_keylist_start’ operation in
3115 the context CTX. The key will have one reference for the user.
3116 *Note Manipulating Keys::.
3118 This is the only way to get at ‘gpgme_key_t’ objects in GPGME.
3120 If the last key in the list has already been returned,
3121 ‘gpgme_op_keylist_next’ returns ‘GPG_ERR_EOF’.
3123 The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX or
3124 R_KEY is not a valid pointer, and ‘GPG_ERR_ENOMEM’ if there is not
3125 enough memory for the operation.
3127 -- Function: gpgme_error_t gpgme_op_keylist_end (gpgme_ctx_t CTX)
3128 The function ‘gpgme_op_keylist_end’ ends a pending key list
3129 operation in the context CTX.
3131 After the operation completed successfully, the result of the key
3132 listing operation can be retrieved with ‘gpgme_op_keylist_result’.
3134 The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX is
3135 not a valid pointer, and ‘GPG_ERR_ENOMEM’ if at some time during
3136 the operation there was not enough memory available.
3138 The following example illustrates how all keys containing a certain
3139 string (‘g10code’) can be listed with their key ID and the name and
3140 e-mail address of the main user ID:
3144 gpgme_error_t err = gpgme_new (&ctx);
3148 err = gpgme_op_keylist_start (ctx, "g10code", 0);
3151 err = gpgme_op_keylist_next (ctx, &key);
3154 printf ("%s:", key->subkeys->keyid);
3155 if (key->uids && key->uids->name)
3156 printf (" %s", key->uids->name);
3157 if (key->uids && key->uids->email)
3158 printf (" <%s>", key->uids->email);
3160 gpgme_key_release (key);
3162 gpgme_release (ctx);
3164 if (gpg_err_code (err) != GPG_ERR_EOF)
3166 fprintf (stderr, "can not list keys: %s\n", gpgme_strerror (err));
3170 -- Data type: gpgme_keylist_result_t
3171 This is a pointer to a structure used to store the result of a
3172 ‘gpgme_op_keylist_*’ operation. After successfully ending a key
3173 listing operation, you can retrieve the pointer to the result with
3174 ‘gpgme_op_keylist_result’. The structure contains the following
3177 ‘unsigned int truncated : 1’
3178 This is true if the crypto backend had to truncate the result,
3179 and less than the desired keys could be listed.
3181 -- Function: gpgme_keylist_result_t gpgme_op_keylist_result
3183 The function ‘gpgme_op_keylist_result’ returns a
3184 ‘gpgme_keylist_result_t’ pointer to a structure holding the result
3185 of a ‘gpgme_op_keylist_*’ operation. The pointer is only valid if
3186 the last operation on the context was a key listing operation, and
3187 if this operation finished successfully. The returned pointer is
3188 only valid until the next operation is started on the context.
3190 In a simple program, for which a blocking operation is acceptable,
3191 the following function can be used to retrieve a single key.
3193 -- Function: gpgme_error_t gpgme_get_key (gpgme_ctx_t CTX,
3194 const char *FPR, gpgme_key_t *R_KEY, int SECRET)
3195 The function ‘gpgme_get_key’ gets the key with the fingerprint (or
3196 key ID) FPR from the crypto backend and return it in R_KEY. If
3197 SECRET is true, get the secret key. The currently active keylist
3198 mode is used to retrieve the key. The key will have one reference
3201 If the key is not found in the keyring, ‘gpgme_get_key’ returns the
3202 error code ‘GPG_ERR_EOF’ and *R_KEY will be set to ‘NULL’.
3204 The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX or
3205 R_KEY is not a valid pointer or FPR is not a fingerprint or key ID,
3206 ‘GPG_ERR_AMBIGUOUS_NAME’ if the key ID was not a unique specifier
3207 for a key, and ‘GPG_ERR_ENOMEM’ if at some time during the
3208 operation there was not enough memory available.
3211 File: gpgme.info, Node: Information About Keys, Next: Manipulating Keys, Prev: Listing Keys, Up: Key Management
3213 7.5.3 Information About Keys
3214 ----------------------------
3216 Please see the beginning of this section for more information about
3217 ‘gpgme_key_t’ objects.
3219 -- Data type: gpgme_validity_t
3220 The ‘gpgme_validity_t’ type is used to specify the validity of a
3221 user ID in a key. The following validities are defined:
3223 ‘GPGME_VALIDITY_UNKNOWN’
3224 The user ID is of unknown validity. The string representation
3225 of this validity is “?”.
3227 ‘GPGME_VALIDITY_UNDEFINED’
3228 The validity of the user ID is undefined. The string
3229 representation of this validity is “q”.
3231 ‘GPGME_VALIDITY_NEVER’
3232 The user ID is never valid. The string representation of this
3235 ‘GPGME_VALIDITY_MARGINAL’
3236 The user ID is marginally valid. The string representation of
3237 this validity is “m”.
3239 ‘GPGME_VALIDITY_FULL’
3240 The user ID is fully valid. The string representation of this
3243 ‘GPGME_VALIDITY_ULTIMATE’
3244 The user ID is ultimately valid. The string representation of
3245 this validity is “u”.
3248 File: gpgme.info, Node: Manipulating Keys, Next: Generating Keys, Prev: Information About Keys, Up: Key Management
3250 7.5.4 Manipulating Keys
3251 -----------------------
3253 -- Function: void gpgme_key_ref (gpgme_key_t KEY)
3254 The function ‘gpgme_key_ref’ acquires an additional reference for
3257 -- Function: void gpgme_key_unref (gpgme_key_t KEY)
3258 The function ‘gpgme_key_unref’ releases a reference for the key
3259 KEY. If this was the last reference, the key will be destroyed and
3260 all resources associated to it will be released.
3263 File: gpgme.info, Node: Generating Keys, Next: Signing Keys, Prev: Manipulating Keys, Up: Key Management
3265 7.5.5 Generating Keys
3266 ---------------------
3268 GPGME provides a set of functions to create public key pairs. Most of
3269 these functions require the use of GnuPG 2.1 and later; for older GnuPG
3270 versions the ‘gpgme_op_genkey’ function can be used. Existing code
3271 which wants to update to the new functions or new code which shall
3272 supports older GnuPG versions may try the new functions first and
3273 provide a fallback to the old function if the error code
3274 ‘GPG_ERR_NOT_SUPPORTED’ is received.
3276 -- Function: gpgme_error_t gpgme_op_createkey (gpgme_ctx_t CTX,
3277 const char *USERID, const char *ALGO, unsigned long RESERVED,
3278 unsigned long EXPIRES, gpgme_key_t EXTRAKEY,
3279 unsigned int FLAGS);
3281 The function ‘gpgme_op_createkey’ generates a new key for the
3282 procotol active in the context CTX. As of now this function does
3283 only work for OpenPGP and requires at least version 2.1.13 of
3286 USERID is commonly the mail address associated with the key. GPGME
3287 does not require a specificy syntax but if more than a mail address
3288 is given, RFC-822 style format is suggested. The value is expected
3289 to be in UTF-8 encoding (i.e. no IDN encoding for mail addresses).
3290 This is a required parameter.
3292 ALGO specifies the algorithm for the new key (actually a keypair of
3293 public and private key). For a list of supported algorithms, see
3294 the GnuPG manual. If ALGO is ‘NULL’ or the string "default", the
3295 key is generated using the default algorithm of the engine. If the
3296 string "future-default" is used the engine may use an algorithm
3297 which is planned to be the default in a future release of the
3298 engine; however existing implementation of the protocol may not be
3299 able to already handle such future algorithms. For the OpenPGP
3300 protocol, the specification of a default algorithm, without
3301 requesting a non-default usage via FLAGS, triggers the creation of
3302 a primary key plus a secondary key (subkey).
3304 RESERVED must be set to zero.
3306 EXPIRES can be set to the number of seconds since Epoch of the
3307 desired expiration date in UTC for the new key. Using 0 does not
3308 set an expiration date. Note that this parameter takes an unsigned
3309 long value and not a ‘time_t’ to avoid problems on systems which
3310 use a signed 32 bit ‘time_t’. Note further that the OpenPGP
3311 protocol uses 32 bit values for timestamps and thus can only encode
3312 dates up to the year 2106.
3314 EXTRAKEY is currently not used and must be set to ‘NULL’. A future
3315 version of GPGME may use this parameter to create X.509 keys.
3317 FLAGS can be set to the bit-wise OR of the following flags:
3323 Do not create the key with the default capabilities (key
3324 usage) of the requested algorithm but use those explicitly
3325 given by these flags: “signing”, “encryption”,
3326 “certification”, or “authentication”. The allowed
3327 combinations depend on the algorithm.
3329 If any of these flags are set and a default algorithm has been
3330 selected only one key is created in the case of the OpenPGP
3333 ‘GPGME_CREATE_NOPASSWD’
3334 Request generation of the key without password protection.
3336 ‘GPGME_CREATE_SELFSIGNED’
3337 For an X.509 key do not create a CSR but a self-signed
3338 certificate. This has not yet been implemented.
3340 ‘GPGME_CREATE_NOSTORE’
3341 Do not store the created key in the local key database. This
3342 has not yet been implemented.
3344 ‘GPGME_CREATE_WANTPUB’
3345 ‘GPGME_CREATE_WANTSEC’
3346 Return the public or secret key as part of the result
3347 structure. This has not yet been implemented.
3349 ‘GPGME_CREATE_FORCE’
3350 The engine does not allow the creation of a key with a user ID
3351 already existing in the local key database. This flag can be
3352 used to override this check.
3354 After the operation completed successfully, information about the
3355 created key can be retrieved with ‘gpgme_op_genkey_result’.
3357 The function returns zero on success, ‘GPG_ERR_NOT_SUPPORTED’ if
3358 the engine does not support the command, or a bunch of other error
3361 -- Function: gpgme_error_t gpgme_op_createkey_start (gpgme_ctx_t CTX,
3362 const char *USERID, const char *ALGO, unsigned long RESERVED,
3363 unsigned long EXPIRES, gpgme_key_t EXTRAKEY,
3364 unsigned int FLAGS);
3366 The function ‘gpgme_op_createkey_start’ initiates a
3367 ‘gpgme_op_createkey’ operation; see there for details. It must be
3368 completed by calling ‘gpgme_wait’ on the context. *Note Waiting
3371 -- Function: gpgme_error_t gpgme_op_createsubkey (gpgme_ctx_t CTX,
3372 gpgme_key_t KEY, const char *ALGO, unsigned long RESERVED,
3373 unsigned long EXPIRES, unsigned int FLAGS);
3375 The function ‘gpgme_op_createsubkey’ creates and adds a new subkey
3376 to the primary OpenPGP key given by KEY. The only allowed protocol
3377 in CTX is ‘GPGME_PROTOCOL_OPENPGP’. Subkeys (aka secondary keys)
3378 are a concept in the OpenPGP protocol to bind several keys to a
3379 primary key. As of now this function requires at least version
3382 KEY specifies the key to operate on.
3384 ALGO specifies the algorithm for the new subkey. For a list of
3385 supported algorithms, see the GnuPG manual. If ALGO is ‘NULL’ or
3386 the string "default", the subkey is generated using the default
3387 algorithm for an encryption subkey of the engine. If the string
3388 "future-default" is used the engine may use an encryption algorithm
3389 which is planned to be the default in a future release of the
3390 engine; however existing implementation of the protocol may not be
3391 able to already handle such future algorithms.
3393 RESERVED must be set to zero.
3395 EXPIRES can be set to the number of seconds since Epoch of the
3396 desired expiration date in UTC for the new subkey. Using 0 does
3397 not set an expiration date. Note that this parameter takes an
3398 unsigned long value and not a ‘time_t’ to avoid problems on systems
3399 which use a signed 32 bit ‘time_t’. Note further that the OpenPGP
3400 protocol uses 32 bit values for timestamps and thus can only encode
3401 dates up to the year 2106.
3403 FLAGS takes the same values as described above for
3404 ‘gpgme_op_createkey’.
3406 After the operation completed successfully, information about the
3407 created key can be retrieved with ‘gpgme_op_genkey_result’.
3409 The function returns zero on success, ‘GPG_ERR_NOT_SUPPORTED’ if
3410 the engine does not support the command, or a bunch of other error
3413 -- Function: gpgme_error_t gpgme_op_createsubkey_start
3414 (gpgme_ctx_t CTX, gpgme_key_t KEY, const char *ALGO,
3415 unsigned long RESERVED, unsigned long EXPIRES,
3416 unsigned int FLAGS);
3418 The function ‘gpgme_op_createsubkey_start’ initiates a
3419 ‘gpgme_op_createsubkey’ operation; see there for details. It must
3420 be completed by calling ‘gpgme_wait’ on the context. *Note Waiting
3423 -- Function: gpgme_error_t gpgme_op_adduid (gpgme_ctx_t CTX,
3424 gpgme_key_t KEY, const char *USERID, unsigned int FLAGS);
3426 The function ‘gpgme_op_adduid’ adds a new user ID to the OpenPGP
3427 key given by KEY. Adding additional user IDs after key creation is
3428 a feature of the OpenPGP protocol and thus the protocol for the
3429 context CTX must be set to OpenPGP. As of now this function
3430 requires at least version 2.1.13 of GnuPG.
3432 KEY specifies the key to operate on.
3434 USERID is the user ID to add to the key. A user ID is commonly the
3435 mail address to be associated with the key. GPGME does not require
3436 a specificy syntax but if more than a mail address is given,
3437 RFC-822 style format is suggested. The value is expected to be in
3438 UTF-8 encoding (i.e. no IDN encoding for mail addresses). This is
3439 a required parameter.
3441 FLAGS are currently not used and must be set to zero.
3443 The function returns zero on success, ‘GPG_ERR_NOT_SUPPORTED’ if
3444 the engine does not support the command, or a bunch of other error
3447 -- Function: gpgme_error_t gpgme_op_adduid_start (gpgme_ctx_t CTX,
3448 gpgme_key_t KEY, const char *USERID, unsigned int FLAGS);
3450 The function ‘gpgme_op_adduid_start’ initiates a ‘gpgme_op_adduid’
3451 operation; see there for details. It must be completed by calling
3452 ‘gpgme_wait’ on the context. *Note Waiting For Completion::.
3454 -- Function: gpgme_error_t gpgme_op_revuid (gpgme_ctx_t CTX,
3455 gpgme_key_t KEY, const char *USERID, unsigned int FLAGS);
3457 The function ‘gpgme_op_revuid’ revokes a user ID from the OpenPGP
3458 key given by KEY. Revoking user IDs after key creation is a
3459 feature of the OpenPGP protocol and thus the protocol for the
3460 context CTX must be set to OpenPGP. As of now this function
3461 requires at least version 2.1.13 of GnuPG.
3463 KEY specifies the key to operate on.
3465 USERID is the user ID to be revoked from the key. The user ID must
3466 be given verbatim because the engine does an exact and case
3467 sensitive match. Thus the ‘uid’ field from the user ID object
3468 (‘gpgme_user_id_t’) is to be used. This is a required parameter.
3470 FLAGS are currently not used and must be set to zero.
3472 Note that the engine won’t allow to revoke the last valid user ID.
3473 To change a user ID is better to first add the new user ID, then
3474 revoke the old one, and finally publish the key.
3476 The function returns zero on success, ‘GPG_ERR_NOT_SUPPORTED’ if
3477 the engine does not support the command, or a bunch of other error
3480 -- Function: gpgme_error_t gpgme_op_revuid_start (gpgme_ctx_t CTX,
3481 gpgme_key_t KEY, const char *USERID, unsigned int FLAGS);
3483 The function ‘gpgme_op_revuid_start’ initiates a ‘gpgme_op_revuid’
3484 operation; see there for details. It must be completed by calling
3485 ‘gpgme_wait’ on the context. *Note Waiting For Completion::.
3487 -- Function: gpgme_error_t gpgme_op_genkey (gpgme_ctx_t CTX,
3488 const char *PARMS, gpgme_data_t PUBLIC, gpgme_data_t SECRET)
3490 The function ‘gpgme_op_genkey’ generates a new key pair in the
3491 context CTX. The meaning of PUBLIC and SECRET depends on the
3494 GPG does not support PUBLIC and SECRET, they should be ‘NULL’.
3495 GnuPG will generate a key pair and add it to the standard key ring.
3496 The fingerprint of the generated key is available with
3497 ‘gpgme_op_genkey_result’.
3499 GpgSM requires PUBLIC to be a writable data object. GpgSM will
3500 generate a secret key (which will be stored by ‘gpg-agent’, and
3501 return a certificate request in PUBLIC, which then needs to be
3502 signed by the certification authority and imported before it can be
3503 used. GpgSM does not make the fingerprint available.
3505 The argument PARMS specifies parameters for the key in an XML
3506 string. The details about the format of PARMS are specific to the
3507 crypto engine used by CTX. Here is an example for GnuPG as the
3508 crypto engine (all parameters of OpenPGP key generation are
3509 documented in the GPG manual):
3511 <GnupgKeyParms format="internal">
3513 Subkey-Type: default
3514 Name-Real: Joe Tester
3515 Name-Comment: with stupid passphrase
3516 Name-Email: joe@foo.bar
3521 Here is an example for GpgSM as the crypto engine (all parameters
3522 of OpenPGP key generation are documented in the GPGSM manual):
3524 <GnupgKeyParms format="internal">
3527 Name-DN: C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester
3528 Name-Email: joe@foo.bar
3531 Strings should be given in UTF-8 encoding. The only format
3532 supported for now is “internal”. The content of the
3533 ‘GnupgKeyParms’ container is passed verbatim to the crypto backend.
3534 Control statements are not allowed.
3536 After the operation completed successfully, the result can be
3537 retrieved with ‘gpgme_op_genkey_result’.
3539 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
3540 operation could be started successfully, ‘GPG_ERR_INV_VALUE’ if
3541 PARMS is not a valid XML string, ‘GPG_ERR_NOT_SUPPORTED’ if PUBLIC
3542 or SECRET is not valid, and ‘GPG_ERR_GENERAL’ if no key was created
3545 -- Function: gpgme_error_t gpgme_op_genkey_start (gpgme_ctx_t CTX,
3546 const char *PARMS, gpgme_data_t PUBLIC, gpgme_data_t SECRET)
3548 The function ‘gpgme_op_genkey_start’ initiates a ‘gpgme_op_genkey’
3549 operation. It can be completed by calling ‘gpgme_wait’ on the
3550 context. *Note Waiting For Completion::.
3552 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
3553 operation could be started successfully, ‘GPG_ERR_INV_VALUE’ if
3554 PARMS is not a valid XML string, and ‘GPG_ERR_NOT_SUPPORTED’ if
3555 PUBLIC or SECRET is not ‘NULL’.
3557 -- Data type: gpgme_genkey_result_t
3559 This is a pointer to a structure used to store the result of a
3560 ‘gpgme_op_genkey’ operation. After successfully generating a key,
3561 you can retrieve the pointer to the result with
3562 ‘gpgme_op_genkey_result’. The structure contains the following
3565 ‘unsigned int primary : 1’
3566 This flag is set to 1 if a primary key was created and to 0 if
3569 ‘unsigned int sub : 1’
3570 This flag is set to 1 if a subkey was created and to 0 if not.
3572 ‘unsigned int uid : 1’
3573 This flag is set to 1 if a user ID was created and to 0 if
3577 This is the fingerprint of the key that was created. If both
3578 a primary and a subkey were generated, the fingerprint of the
3579 primary key will be returned. If the crypto engine does not
3580 provide the fingerprint, ‘fpr’ will be a null pointer.
3582 ‘gpgme_data_t pubkey’
3583 This will eventually be used to return the public key. It is
3586 ‘gpgme_data_t seckey’
3587 This will eventually be used to return the secret key. It is
3590 -- Function: gpgme_genkey_result_t gpgme_op_genkey_result
3593 The function ‘gpgme_op_genkey_result’ returns a
3594 ‘gpgme_genkey_result_t’ pointer to a structure holding the result
3595 of a ‘gpgme_op_genkey’ operation. The pointer is only valid if the
3596 last operation on the context was a ‘gpgme_op_genkey’ or
3597 ‘gpgme_op_genkey_start’ operation, and if this operation finished
3598 successfully. The returned pointer is only valid until the next
3599 operation is started on the context.
3602 File: gpgme.info, Node: Signing Keys, Next: Exporting Keys, Prev: Generating Keys, Up: Key Management
3607 Key signatures are a unique concept of the OpenPGP protocol. They can
3608 be used to certify the validity of a key and are used to create the
3609 Web-of-Trust (WoT). Instead of using the ‘gpgme_op_interact’ function
3610 along with a finite state machine, GPGME provides a convenient function
3611 to create key signatures when using modern GnuPG versions.
3613 -- Function: gpgme_error_t gpgme_op_keysign (gpgme_ctx_t CTX,
3614 gpgme_key_t KEY, const char *USERID, unsigned long EXPIRES,
3615 unsigned int FLAGS);
3617 The function ‘gpgme_op_keysign’ adds a new key signature to the
3618 public key KEY. This function requires at least version 2.1.12 of
3621 CTX is the usual context which describes the protocol to use (which
3622 must be OpenPGP) and has also the list of signer keys to be used
3623 for the signature. The common case is to use the default key for
3624 signing other keys. If another key or more than one key shall be
3625 used for a key signature, ‘gpgme_signers_add’ can be used. *Note
3626 Selecting Signers::.
3628 KEY specifies the key to operate on.
3630 USERID selects the user ID or user IDs to be signed. If USERID is
3631 set to ‘NULL’ all valid user IDs are signed. The user ID must be
3632 given verbatim because the engine does an exact and case sensitive
3633 match. Thus the ‘uid’ field from the user ID object
3634 (‘gpgme_user_id_t’) is to be used. To select more than one user ID
3635 put them all into one string separated by linefeeds characters
3636 (‘\n’) and set the flag ‘GPGME_KEYSIGN_LFSEP’.
3638 EXPIRES can be set to the number of seconds since Epoch of the
3639 desired expiration date in UTC for the new signature. The common
3640 case is to use 0 to not set an expiration date. However, if the
3641 configuration of the engine defines a default expiration for key
3642 signatures, that is still used unless the flag
3643 ‘GPGME_KEYSIGN_NOEXPIRE’ is used. Note that this parameter takes
3644 an unsigned long value and not a ‘time_t’ to avoid problems on
3645 systems which use a signed 32 bit ‘time_t’. Note further that the
3646 OpenPGP protocol uses 32 bit values for timestamps and thus can
3647 only encode dates up to the year 2106.
3649 FLAGS can be set to the bit-wise OR of the following flags:
3651 ‘GPGME_KEYSIGN_LOCAL’
3652 Instead of creating an exportable key signature, create a key
3653 signature which is is marked as non-exportable.
3655 ‘GPGME_KEYSIGN_LFSEP’
3656 Although linefeeds are uncommon in user IDs this flag is
3657 required to explicitly declare that USERID may contain several
3658 linefeed separated user IDs.
3660 ‘GPGME_KEYSIGN_NOEXPIRE’
3661 Force the creation of a key signature without an expiration
3662 date. This overrides EXPIRE and any local configuration of
3665 The function returns zero on success, ‘GPG_ERR_NOT_SUPPORTED’ if
3666 the engine does not support the command, or a bunch of other error
3669 -- Function: gpgme_error_t gpgme_op_keysign_start (gpgme_ctx_t CTX,
3670 gpgme_key_t KEY, const char *USERID, unsigned long EXPIRES,
3671 unsigned int FLAGS);
3673 The function ‘gpgme_op_keysign_start’ initiates a
3674 ‘gpgme_op_keysign’ operation; see there for details. It must be
3675 completed by calling ‘gpgme_wait’ on the context. *Note Waiting
3679 File: gpgme.info, Node: Exporting Keys, Next: Importing Keys, Prev: Signing Keys, Up: Key Management
3681 7.5.7 Exporting Keys
3682 --------------------
3684 Exporting keys means the same as running ‘gpg’ with the command
3685 ‘--export’. However, a mode flag can be used to change the way the
3686 export works. The available mode flags are described below, they may be
3689 ‘GPGME_EXPORT_MODE_EXTERN’
3690 If this bit is set, the output is send directly to the default
3691 keyserver. This is currently only allowed for OpenPGP keys. It is
3692 good practise to not send more than a few dozens key to a keyserver
3693 at one time. Using this flag requires that the KEYDATA argument of
3694 the export function is set to ‘NULL’.
3696 ‘GPGME_EXPORT_MODE_MINIMAL’
3697 If this bit is set, the smallest possible key is exported. For
3698 OpenPGP keys it removes all signatures except for the latest
3699 self-signatures. For X.509 keys it has no effect.
3701 ‘GPGME_EXPORT_MODE_SECRET’
3702 Instead of exporting the public key, the secret key is exported.
3703 This may not be combined with ‘GPGME_EXPORT_MODE_EXTERN’. For
3704 X.509 the export format is PKCS#8.
3706 ‘GPGME_EXPORT_MODE_RAW’
3707 If this flag is used with ‘GPGME_EXPORT_MODE_SECRET’ for an X.509
3708 key the export format will be changed to PKCS#1. This flag may not
3709 be used with OpenPGP.
3711 ‘GPGME_EXPORT_MODE_PKCS12’
3712 If this flag is used with ‘GPGME_EXPORT_MODE_SECRET’ for an X.509
3713 key the export format will be changed to PKCS#12 which also
3714 includes the certificate. This flag may not be used with OpenPGP.
3716 -- Function: gpgme_error_t gpgme_op_export (gpgme_ctx_t CTX,
3717 const char *PATTERN, gpgme_export_mode_t MODE,
3718 gpgme_data_t KEYDATA)
3719 The function ‘gpgme_op_export’ extracts public keys and returns
3720 them in the data buffer KEYDATA. The output format of the key data
3721 returned is determined by the ASCII armor attribute set for the
3722 context CTX, or, if that is not set, by the encoding specified for
3725 If PATTERN is ‘NULL’, all available keys are returned. Otherwise,
3726 PATTERN contains an engine specific expression that is used to
3727 limit the list to all keys matching the pattern.
3729 MODE is usually 0; other values are described above.
3731 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
3732 operation completed successfully, ‘GPG_ERR_INV_VALUE’ if KEYDATA is
3733 not a valid empty data buffer, and passes through any errors that
3734 are reported by the crypto engine support routines.
3736 -- Function: gpgme_error_t gpgme_op_export_start (gpgme_ctx_t CTX,
3737 const char *PATTERN, gpgme_export_mode_t MODE,
3738 gpgme_data_t KEYDATA)
3739 The function ‘gpgme_op_export_start’ initiates a ‘gpgme_op_export’
3740 operation. It can be completed by calling ‘gpgme_wait’ on the
3741 context. *Note Waiting For Completion::.
3743 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
3744 operation could be started successfully, and ‘GPG_ERR_INV_VALUE’ if
3745 KEYDATA is not a valid empty data buffer.
3747 -- Function: gpgme_error_t gpgme_op_export_ext (gpgme_ctx_t CTX,
3748 const char *PATTERN[], gpgme_export_mode_t MODE,
3749 gpgme_data_t KEYDATA)
3750 The function ‘gpgme_op_export’ extracts public keys and returns
3751 them in the data buffer KEYDATA. The output format of the key data
3752 returned is determined by the ASCII armor attribute set for the
3753 context CTX, or, if that is not set, by the encoding specified for
3756 If PATTERN or *PATTERN is ‘NULL’, all available keys are returned.
3757 Otherwise, PATTERN is a ‘NULL’ terminated array of strings that are
3758 used to limit the list to all keys matching at least one of the
3761 MODE is usually 0; other values are described above.
3763 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
3764 operation completed successfully, ‘GPG_ERR_INV_VALUE’ if KEYDATA is
3765 not a valid empty data buffer, and passes through any errors that
3766 are reported by the crypto engine support routines.
3768 -- Function: gpgme_error_t gpgme_op_export_ext_start (gpgme_ctx_t CTX,
3769 const char *PATTERN[], gpgme_export_mode_t MODE,
3770 gpgme_data_t KEYDATA)
3771 The function ‘gpgme_op_export_ext_start’ initiates a
3772 ‘gpgme_op_export_ext’ operation. It can be completed by calling
3773 ‘gpgme_wait’ on the context. *Note Waiting For Completion::.
3775 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
3776 operation could be started successfully, and ‘GPG_ERR_INV_VALUE’ if
3777 KEYDATA is not a valid empty data buffer.
3779 -- Function: gpgme_error_t gpgme_op_export_keys (gpgme_ctx_t CTX,
3780 gpgme_key_t keys[], gpgme_export_mode_t MODE,
3781 gpgme_data_t KEYDATA)
3782 The function ‘gpgme_op_export_keys’ extracts public keys and
3783 returns them in the data buffer KEYDATA. The output format of the
3784 key data returned is determined by the ASCII armor attribute set
3785 for the context CTX, or, if that is not set, by the encoding
3786 specified for KEYDATA.
3788 The keys to export are taken form the ‘NULL’ terminated array KEYS.
3789 Only keys of the currently selected protocol of CTX which do have a
3790 fingerprint set are considered for export. Other keys specified by
3791 the KEYS are ignored. In particular OpenPGP keys retrieved via an
3792 external key listing are not included.
3794 MODE is usually 0; other values are described above.
3796 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
3797 operation completed successfully, ‘GPG_ERR_INV_VALUE’ if KEYDATA is
3798 not a valid empty data buffer, ‘GPG_ERR_NO_DATA’ if no useful keys
3799 are in KEYS and passes through any errors that are reported by the
3800 crypto engine support routines.
3802 -- Function: gpgme_error_t gpgme_op_export_keys_start (gpgme_ctx_t CTX,
3803 gpgme_key_t KEYS[], gpgme_export_mode_t MODE,
3804 gpgme_data_t KEYDATA)
3805 The function ‘gpgme_op_export_keys_start’ initiates a
3806 ‘gpgme_op_export_ext’ operation. It can be completed by calling
3807 ‘gpgme_wait’ on the context. *Note Waiting For Completion::.
3809 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
3810 operation could be started successfully, and ‘GPG_ERR_INV_VALUE’ if
3811 KEYDATA is not a valid empty data buffer, ‘GPG_ERR_NO_DATA’ if no
3812 useful keys are in KEYS and passes through any errors that are
3813 reported by the crypto engine support routines.
3816 File: gpgme.info, Node: Importing Keys, Next: Deleting Keys, Prev: Exporting Keys, Up: Key Management
3818 7.5.8 Importing Keys
3819 --------------------
3821 Importing keys means the same as running ‘gpg’ with the command
3824 -- Function: gpgme_error_t gpgme_op_import (gpgme_ctx_t CTX,
3825 gpgme_data_t KEYDATA)
3826 The function ‘gpgme_op_import’ adds the keys in the data buffer
3827 KEYDATA to the key ring of the crypto engine used by CTX. The
3828 format of KEYDATA can be ASCII armored, for example, but the
3829 details are specific to the crypto engine.
3831 After the operation completed successfully, the result can be
3832 retrieved with ‘gpgme_op_import_result’.
3834 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
3835 import was completed successfully, ‘GPG_ERR_INV_VALUE’ if KEYDATA
3836 if CTX or KEYDATA is not a valid pointer, and ‘GPG_ERR_NO_DATA’ if
3837 KEYDATA is an empty data buffer.
3839 -- Function: gpgme_error_t gpgme_op_import_start (gpgme_ctx_t CTX,
3840 gpgme_data_t KEYDATA)
3841 The function ‘gpgme_op_import_start’ initiates a ‘gpgme_op_import’
3842 operation. It can be completed by calling ‘gpgme_wait’ on the
3843 context. *Note Waiting For Completion::.
3845 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
3846 import could be started successfully, ‘GPG_ERR_INV_VALUE’ if
3847 KEYDATA if CTX or KEYDATA is not a valid pointer, and
3848 ‘GPG_ERR_NO_DATA’ if KEYDATA is an empty data buffer.
3850 -- Function: gpgme_error_t gpgme_op_import_keys (gpgme_ctx_t CTX,
3852 The function ‘gpgme_op_import_keys’ adds the keys described by the
3853 ‘NULL’ terminated array KEYS to the key ring of the crypto engine
3854 used by CTX. This function is the general interface to move a key
3855 from one crypto engine to another as long as they are compatible.
3856 In particular it is used to actually import and make keys permanent
3857 which have been retrieved from an external source (i.e. using
3858 ‘GPGME_KEYLIST_MODE_EXTERN’). (1)
3860 Only keys of the currently selected protocol of CTX are considered
3861 for import. Other keys specified by the KEYS are ignored. As of
3862 now all considered keys must have been retrieved using the same
3863 method, that is the used key listing mode must be identical.
3865 After the operation completed successfully, the result can be
3866 retrieved with ‘gpgme_op_import_result’.
3868 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
3869 import was completed successfully, ‘GPG_ERR_INV_VALUE’ if KEYDATA
3870 if CTX or KEYDATA is not a valid pointer, ‘GPG_ERR_CONFLICT’ if the
3871 key listing mode does not match, and ‘GPG_ERR_NO_DATA’ if no keys
3872 are considered for export.
3874 -- Function: gpgme_error_t gpgme_op_import_keys_start (gpgme_ctx_t CTX,
3876 The function ‘gpgme_op_import_keys_start’ initiates a
3877 ‘gpgme_op_import_keys’ operation. It can be completed by calling
3878 ‘gpgme_wait’ on the context. *Note Waiting For Completion::.
3880 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
3881 import was completed successfully, ‘GPG_ERR_INV_VALUE’ if KEYDATA
3882 if CTX or KEYDATA is not a valid pointer, ‘GPG_ERR_CONFLICT’ if the
3883 key listing mode does not match, and ‘GPG_ERR_NO_DATA’ if no keys
3884 are considered for export.
3886 -- Data type: gpgme_import_status_t
3887 This is a pointer to a structure used to store a part of the result
3888 of a ‘gpgme_op_import’ operation. For each considered key one
3889 status is added that contains information about the result of the
3890 import. The structure contains the following members:
3892 ‘gpgme_import_status_t next’
3893 This is a pointer to the next status structure in the linked
3894 list, or ‘NULL’ if this is the last element.
3897 This is the fingerprint of the key that was considered.
3899 ‘gpgme_error_t result’
3900 If the import was not successful, this is the error value that
3901 caused the import to fail. Otherwise the error code is
3904 ‘unsigned int status’
3905 This is a bit-wise OR of the following flags that give more
3906 information about what part of the key was imported. If the
3907 key was already known, this might be 0.
3913 The key contained new user IDs.
3916 The key contained new signatures.
3918 ‘GPGME_IMPORT_SUBKEY’
3919 The key contained new sub keys.
3921 ‘GPGME_IMPORT_SECRET’
3922 The key contained a secret key.
3924 -- Data type: gpgme_import_result_t
3925 This is a pointer to a structure used to store the result of a
3926 ‘gpgme_op_import’ operation. After a successful import operation,
3927 you can retrieve the pointer to the result with
3928 ‘gpgme_op_import_result’. The structure contains the following
3932 The total number of considered keys.
3935 The number of keys without user ID.
3938 The total number of imported keys.
3941 The number of imported RSA keys.
3944 The number of unchanged keys.
3947 The number of new user IDs.
3950 The number of new sub keys.
3952 ‘int new_signatures’
3953 The number of new signatures.
3955 ‘int new_revocations’
3956 The number of new revocations.
3959 The total number of secret keys read.
3961 ‘int secret_imported’
3962 The number of imported secret keys.
3964 ‘int secret_unchanged’
3965 The number of unchanged secret keys.
3968 The number of keys not imported.
3970 ‘gpgme_import_status_t imports’
3971 A list of gpgme_import_status_t objects which contain more
3972 information about the keys for which an import was attempted.
3974 -- Function: gpgme_import_result_t gpgme_op_import_result
3976 The function ‘gpgme_op_import_result’ returns a
3977 ‘gpgme_import_result_t’ pointer to a structure holding the result
3978 of a ‘gpgme_op_import’ operation. The pointer is only valid if the
3979 last operation on the context was a ‘gpgme_op_import’ or
3980 ‘gpgme_op_import_start’ operation, and if this operation finished
3981 successfully. The returned pointer is only valid until the next
3982 operation is started on the context.
3984 ---------- Footnotes ----------
3986 (1) Thus it is a replacement for the usual workaround of exporting
3987 and then importing a key to make an X.509 key permanent.
3990 File: gpgme.info, Node: Deleting Keys, Next: Changing Passphrases, Prev: Importing Keys, Up: Key Management
3995 -- Function: gpgme_error_t gpgme_op_delete (gpgme_ctx_t CTX,
3996 const gpgme_key_t KEY, int ALLOW_SECRET)
3997 The function ‘gpgme_op_delete’ deletes the key KEY from the key
3998 ring of the crypto engine used by CTX. If ALLOW_SECRET is ‘0’,
3999 only public keys are deleted, otherwise secret keys are deleted as
4000 well, if that is supported.
4002 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the key
4003 was deleted successfully, ‘GPG_ERR_INV_VALUE’ if CTX or KEY is not
4004 a valid pointer, ‘GPG_ERR_NO_PUBKEY’ if KEY could not be found in
4005 the keyring, ‘GPG_ERR_AMBIGUOUS_NAME’ if the key was not specified
4006 unambiguously, and ‘GPG_ERR_CONFLICT’ if the secret key for KEY is
4007 available, but ALLOW_SECRET is zero.
4009 -- Function: gpgme_error_t gpgme_op_delete_start (gpgme_ctx_t CTX,
4010 const gpgme_key_t KEY, int ALLOW_SECRET)
4011 The function ‘gpgme_op_delete_start’ initiates a ‘gpgme_op_delete’
4012 operation. It can be completed by calling ‘gpgme_wait’ on the
4013 context. *Note Waiting For Completion::.
4015 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
4016 operation was started successfully, and ‘GPG_ERR_INV_VALUE’ if CTX
4017 or KEY is not a valid pointer.
4020 File: gpgme.info, Node: Changing Passphrases, Next: Changing TOFU Data, Prev: Deleting Keys, Up: Key Management
4022 7.5.10 Changing Passphrases
4023 ---------------------------
4025 -- Function: gpgme_error_t gpgme_op_passwd (gpgme_ctx_t CTX,
4026 const gpgme_key_t KEY, unsigned int FLAGS)
4028 The function ‘gpgme_op_passwd’ changes the passphrase of the
4029 private key associated with KEY. The only allowed value for FLAGS
4030 is ‘0’. The backend engine will usually popup a window to ask for
4031 the old and the new passphrase. Thus this function is not useful
4032 in a server application (where passphrases are not required
4035 Note that old ‘gpg’ engines (before version 2.0.15) do not support
4036 this command and will silently ignore it.
4038 -- Function: gpgme_error_t gpgme_op_passwd_start (gpgme_ctx_t CTX,
4039 const gpgme_key_t KEY, unsigned int FLAGS)
4041 The function ‘gpgme_op_passwd_start’ initiates a ‘gpgme_op_passwd’
4042 operation. It can be completed by calling ‘gpgme_wait’ on the
4043 context. *Note Waiting For Completion::.
4045 The function returns ‘0’ if the operation was started successfully,
4046 and an error code if one of the arguments is not valid or the
4047 oepration could not be started.
4050 File: gpgme.info, Node: Changing TOFU Data, Next: Advanced Key Editing, Prev: Changing Passphrases, Up: Key Management
4052 7.5.11 Changing TOFU Data
4053 -------------------------
4055 The OpenPGP engine features a Trust-On-First-Use (TOFU) key validation
4056 model. For resolving clonflics it is necessary to declare the policy
4057 for a key. See the GnuPG manual for details on the TOFU implementation.
4059 -- Data type: enum gpgme_tofu_policy_t
4060 The ‘gpgme_tofu_policy_t’ type specifies the set of possible policy
4061 values that are supported by GPGME:
4063 ‘GPGME_TOFU_POLICY_AUTO’
4064 Set the policy to “auto”.
4065 ‘GPGME_TOFU_POLICY_GOOD’
4066 Set the policy to “goog”.
4067 ‘GPGME_TOFU_POLICY_BAD’
4068 Set the policy to “bad”.
4069 ‘GPGME_TOFU_POLICY_ASK’
4070 Set the policy to “ask”.
4071 ‘GPGME_TOFU_POLICY_UNKNOWN’
4072 Set the policy to “unknown”.
4074 To change the policy for a key the following functions can be used:
4076 -- Function: gpgme_error_t gpgme_op_tofu_policy (gpgme_ctx_t CTX,
4077 const gpgme_key_t KEY, gpgme_tofu_policy_t POLICY)
4079 The function ‘gpgme_op_tofu_policy’ changes the TOFU policy of KEY.
4080 The valid values for POLICY are listed above. As of now this
4081 function does only work for OpenPGP and requires at least version
4084 The function returns zero on success, ‘GPG_ERR_NOT_SUPPORTED’ if
4085 the engine does not support the command, or a bunch of other error
4088 -- Function: gpgme_error_t gpgme_op_tofu_policy_start (gpgme_ctx_t CTX,
4089 const gpgme_key_t KEY, gpgme_tofu_policy_t POLICY)
4091 The function ‘gpgme_op_tofu_policy_start’ initiates a
4092 ‘gpgme_op_tofu_policy’ operation. It can be completed by calling
4093 ‘gpgme_wait’ on the context. *Note Waiting For Completion::.
4095 The function returns ‘0’ if the operation was started successfully,
4096 and an error code if one of the arguments is not valid or the
4097 oepration could not be started.
4100 File: gpgme.info, Node: Advanced Key Editing, Prev: Changing TOFU Data, Up: Key Management
4102 7.5.12 Advanced Key Editing
4103 ---------------------------
4105 -- Data type: gpgme_error_t (*gpgme_interact_cb_t) (void *HANDLE,
4106 const char *STATUS, const char *ARGS, int FD)
4107 The ‘gpgme_interact_cb_t’ type is the type of functions which GPGME
4108 calls if it a key interact operation is on-going. The status
4109 keyword STATUS and the argument line ARGS are passed through by
4110 GPGME from the crypto engine. An empty string represents EOF. The
4111 file descriptor FD is -1 for normal status messages. If STATUS
4112 indicates a command rather than a status message, the response to
4113 the command should be written to FD. The HANDLE is provided by the
4114 user at start of operation.
4116 The function should return ‘GPG_ERR_FALSE’ if it did not handle the
4117 status code, ‘0’ for success, or any other error value.
4119 -- Function: gpgme_error_t gpgme_op_interact (gpgme_ctx_t CTX,
4120 gpgme_key_t KEY, unsigned int FLAGS, gpgme_interact_cb_t FNC,
4121 void *HANDLE, gpgme_data_t OUT)
4122 The function ‘gpgme_op_interact’ processes the key KEY
4123 interactively, using the interact callback function FNC with the
4124 handle HANDLE. The callback is invoked for every status and
4125 command request from the crypto engine. The output of the crypto
4126 engine is written to the data object OUT.
4128 Note that the protocol between the callback function and the crypto
4129 engine is specific to the crypto engine and no further support in
4130 implementing this protocol correctly is provided by GPGME.
4132 FLAGS modifies the behaviour of the function; the only defined bit
4135 ‘GPGME_INTERACT_CARD’
4136 This is used for smartcard based keys and uses gpg’s
4137 ‘--card-edit’ command.
4139 The function returns ‘0’ if the edit operation completes
4140 successfully, ‘GPG_ERR_INV_VALUE’ if CTX or KEY is not a valid
4141 pointer, and any error returned by the crypto engine or the edit
4144 -- Function: gpgme_error_t gpgme_op_interact_start (gpgme_ctx_t CTX,
4145 gpgme_key_t KEY, unsigned int FLAGS, gpgme_interact_cb_t FNC,
4146 void *HANDLE, gpgme_data_t OUT)
4147 The function ‘gpgme_op_interact_start’ initiates a
4148 ‘gpgme_op_interact’ operation. It can be completed by calling
4149 ‘gpgme_wait’ on the context. *Note Waiting For Completion::.
4151 The function returns ‘0’ if the operation was started successfully,
4152 and ‘GPG_ERR_INV_VALUE’ if CTX or KEY is not a valid pointer.
4155 File: gpgme.info, Node: Trust Item Management, Next: Crypto Operations, Prev: Key Management, Up: Contexts
4157 7.6 Trust Item Management
4158 =========================
4160 *Caution:* The trust items interface is experimental.
4162 -- Data type: gpgme_trust_item_t
4163 The ‘gpgme_trust_item_t’ type is a pointer to a trust item object.
4164 It has the following members:
4167 This is a string describing the key to which this trust items
4171 This is the type of the trust item. A value of 1 refers to a
4172 key, a value of 2 refers to a user ID.
4175 This is the trust level.
4178 The owner trust if ‘type’ is 1.
4181 The calculated validity.
4184 The user name if ‘type’ is 2.
4188 * Listing Trust Items:: Browsing the list of available trust items.
4189 * Manipulating Trust Items:: Operations on trust items.
4192 File: gpgme.info, Node: Listing Trust Items, Next: Manipulating Trust Items, Up: Trust Item Management
4194 7.6.1 Listing Trust Items
4195 -------------------------
4197 -- Function: gpgme_error_t gpgme_op_trustlist_start (gpgme_ctx_t CTX,
4198 const char *PATTERN, int MAX_LEVEL)
4199 The function ‘gpgme_op_trustlist_start’ initiates a trust item
4200 listing operation inside the context CTX. It sets everything up so
4201 that subsequent invocations of ‘gpgme_op_trustlist_next’ return the
4202 trust items in the list.
4204 The string PATTERN contains an engine specific expression that is
4205 used to limit the list to all trust items matching the pattern. It
4206 can not be the empty string.
4208 The argument MAX_LEVEL is currently ignored.
4210 The context will be busy until either all trust items are received
4211 (and ‘gpgme_op_trustlist_next’ returns ‘GPG_ERR_EOF’), or
4212 ‘gpgme_op_trustlist_end’ is called to finish the operation.
4214 The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX is
4215 not a valid pointer, and passes through any errors that are
4216 reported by the crypto engine support routines.
4218 -- Function: gpgme_error_t gpgme_op_trustlist_next (gpgme_ctx_t CTX,
4219 gpgme_trust_item_t *R_ITEM)
4220 The function ‘gpgme_op_trustlist_next’ returns the next trust item
4221 in the list created by a previous ‘gpgme_op_trustlist_start’
4222 operation in the context CTX. The trust item can be destroyed with
4223 ‘gpgme_trust_item_release’. *Note Manipulating Trust Items::.
4225 This is the only way to get at ‘gpgme_trust_item_t’ objects in
4228 If the last trust item in the list has already been returned,
4229 ‘gpgme_op_trustlist_next’ returns ‘GPG_ERR_EOF’.
4231 The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX or
4232 R_ITEM is not a valid pointer, and ‘GPG_ERR_ENOMEM’ if there is not
4233 enough memory for the operation.
4235 -- Function: gpgme_error_t gpgme_op_trustlist_end (gpgme_ctx_t CTX)
4236 The function ‘gpgme_op_trustlist_end’ ends a pending trust list
4237 operation in the context CTX.
4239 The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX is
4240 not a valid pointer, and ‘GPG_ERR_ENOMEM’ if at some time during
4241 the operation there was not enough memory available.
4244 File: gpgme.info, Node: Manipulating Trust Items, Prev: Listing Trust Items, Up: Trust Item Management
4246 7.6.2 Manipulating Trust Items
4247 ------------------------------
4249 -- Function: void gpgme_trust_item_ref (gpgme_trust_item_t ITEM)
4250 The function ‘gpgme_trust_item_ref’ acquires an additional
4251 reference for the trust item ITEM.
4253 -- Function: void gpgme_trust_item_unref (gpgme_trust_item_t ITEM)
4254 The function ‘gpgme_trust_item_unref’ releases a reference for the
4255 trust item ITEM. If this was the last reference, the trust item
4256 will be destroyed and all resources associated to it will be
4260 File: gpgme.info, Node: Crypto Operations, Next: Miscellaneous, Prev: Trust Item Management, Up: Contexts
4262 7.7 Crypto Operations
4263 =====================
4265 Sometimes, the result of a crypto operation returns a list of invalid
4266 keys encountered in processing the request. The following structure is
4267 used to hold information about such a key.
4269 -- Data type: gpgme_invalid_key_t
4270 This is a pointer to a structure used to store a part of the result
4271 of a crypto operation which takes user IDs as one input parameter.
4272 The structure contains the following members:
4274 ‘gpgme_invalid_key_t next’
4275 This is a pointer to the next invalid key structure in the
4276 linked list, or ‘NULL’ if this is the last element.
4279 The fingerprint or key ID of the invalid key encountered.
4281 ‘gpgme_error_t reason’
4282 An error code describing the reason why the key was found
4287 * Decrypt:: Decrypting a ciphertext.
4288 * Verify:: Verifying a signature.
4289 * Decrypt and Verify:: Decrypting a signed ciphertext.
4290 * Sign:: Creating a signature.
4291 * Encrypt:: Encrypting a plaintext.
4294 File: gpgme.info, Node: Decrypt, Next: Verify, Up: Crypto Operations
4299 -- Function: gpgme_error_t gpgme_op_decrypt (gpgme_ctx_t CTX,
4300 gpgme_data_t CIPHER, gpgme_data_t PLAIN)
4301 The function ‘gpgme_op_decrypt’ decrypts the ciphertext in the data
4302 object CIPHER and stores it into the data object PLAIN.
4304 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
4305 ciphertext could be decrypted successfully, ‘GPG_ERR_INV_VALUE’ if
4306 CTX, CIPHER or PLAIN is not a valid pointer, ‘GPG_ERR_NO_DATA’ if
4307 CIPHER does not contain any data to decrypt,
4308 ‘GPG_ERR_DECRYPT_FAILED’ if CIPHER is not a valid cipher text,
4309 ‘GPG_ERR_BAD_PASSPHRASE’ if the passphrase for the secret key could
4310 not be retrieved, and passes through any errors that are reported
4311 by the crypto engine support routines.
4313 -- Function: gpgme_error_t gpgme_op_decrypt_start (gpgme_ctx_t CTX,
4314 gpgme_data_t CIPHER, gpgme_data_t PLAIN)
4315 The function ‘gpgme_op_decrypt_start’ initiates a
4316 ‘gpgme_op_decrypt’ operation. It can be completed by calling
4317 ‘gpgme_wait’ on the context. *Note Waiting For Completion::.
4319 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
4320 operation could be started successfully, and ‘GPG_ERR_INV_VALUE’ if
4321 CIPHER or PLAIN is not a valid pointer.
4323 -- Data type: gpgme_recipient_t
4324 This is a pointer to a structure used to store information about
4325 the recipient of an encrypted text which is decrypted in a
4326 ‘gpgme_op_decrypt’ operation. This information (except for the
4327 status field) is even available before the operation finished
4328 successfully, for example in a passphrase callback. The structure
4329 contains the following members:
4331 ‘gpgme_recipient_t next’
4332 This is a pointer to the next recipient structure in the
4333 linked list, or ‘NULL’ if this is the last element.
4335 ‘gpgme_pubkey_algo_t’
4336 The public key algorithm used in the encryption.
4339 This is the key ID of the key (in hexadecimal digits) used as
4342 ‘gpgme_error_t status’
4343 This is an error number with the error code GPG_ERR_NO_SECKEY
4344 if the secret key for this recipient is not available, and 0
4347 -- Data type: gpgme_decrypt_result_t
4348 This is a pointer to a structure used to store the result of a
4349 ‘gpgme_op_decrypt’ operation. After successfully decrypting data,
4350 you can retrieve the pointer to the result with
4351 ‘gpgme_op_decrypt_result’. The structure contains the following
4354 ‘char *unsupported_algorithm’
4355 If an unsupported algorithm was encountered, this string
4356 describes the algorithm that is not supported.
4358 ‘unsigned int wrong_key_usage : 1’
4359 This is true if the key was not used according to its policy.
4361 ‘gpgme_recipient_t recipients’
4362 This is a linked list of recipients to which this message was
4366 This is the filename of the original plaintext message file if
4367 it is known, otherwise this is a null pointer.
4369 -- Function: gpgme_decrypt_result_t gpgme_op_decrypt_result
4371 The function ‘gpgme_op_decrypt_result’ returns a
4372 ‘gpgme_decrypt_result_t’ pointer to a structure holding the result
4373 of a ‘gpgme_op_decrypt’ operation. The pointer is only valid if
4374 the last operation on the context was a ‘gpgme_op_decrypt’ or
4375 ‘gpgme_op_decrypt_start’ operation. If the operation failed this
4376 might be a ‘NULL’ pointer. The returned pointer is only valid
4377 until the next operation is started on the context.
4380 File: gpgme.info, Node: Verify, Next: Decrypt and Verify, Prev: Decrypt, Up: Crypto Operations
4385 -- Function: gpgme_error_t gpgme_op_verify (gpgme_ctx_t CTX,
4386 gpgme_data_t SIG, gpgme_data_t SIGNED_TEXT,
4388 The function ‘gpgme_op_verify’ verifies that the signature in the
4389 data object SIG is a valid signature. If SIG is a detached
4390 signature, then the signed text should be provided in SIGNED_TEXT
4391 and PLAIN should be a null pointer. Otherwise, if SIG is a normal
4392 (or cleartext) signature, SIGNED_TEXT should be a null pointer and
4393 PLAIN should be a writable data object that will contain the
4394 plaintext after successful verification.
4396 The results of the individual signature verifications can be
4397 retrieved with ‘gpgme_op_verify_result’.
4399 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
4400 operation could be completed successfully, ‘GPG_ERR_INV_VALUE’ if
4401 CTX, SIG or PLAIN is not a valid pointer, ‘GPG_ERR_NO_DATA’ if SIG
4402 does not contain any data to verify, and passes through any errors
4403 that are reported by the crypto engine support routines.
4405 -- Function: gpgme_error_t gpgme_op_verify_start (gpgme_ctx_t CTX,
4406 gpgme_data_t SIG, gpgme_data_t SIGNED_TEXT,
4408 The function ‘gpgme_op_verify_start’ initiates a ‘gpgme_op_verify’
4409 operation. It can be completed by calling ‘gpgme_wait’ on the
4410 context. *Note Waiting For Completion::.
4412 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
4413 operation could be started successfully, ‘GPG_ERR_INV_VALUE’ if
4414 CTX, SIG or PLAIN is not a valid pointer, and ‘GPG_ERR_NO_DATA’ if
4415 SIG or PLAIN does not contain any data to verify.
4417 -- Data type: gpgme_sig_notation_t
4418 This is a pointer to a structure used to store a part of the result
4419 of a ‘gpgme_op_verify’ operation. The structure contains the
4422 ‘gpgme_sig_notation_t next’
4423 This is a pointer to the next new signature notation structure
4424 in the linked list, or ‘NULL’ if this is the last element.
4427 The name of the notation field. If this is ‘NULL’, then the
4428 member ‘value’ will contain a policy URL.
4431 The length of the ‘name’ field. For strings the length is
4432 counted without the trailing binary zero.
4435 The value of the notation field. If ‘name’ is ‘NULL’, then
4436 this is a policy URL.
4439 The length of the ‘value’ field. For strings the length is
4440 counted without the trailing binary zero.
4442 ‘gpgme_sig_notation_flags_t flags’
4443 The accumulated flags field. This field contains the flags
4444 associated with the notation data in an accumulated form which
4445 can be used as an argument to the function
4446 ‘gpgme_sig_notation_add’. The value ‘flags’ is a bitwise-or
4447 combination of one or multiple of the following bit values:
4449 ‘GPGME_SIG_NOTATION_HUMAN_READABLE’
4450 The ‘GPGME_SIG_NOTATION_HUMAN_READABLE’ symbol specifies
4451 that the notation data is in human readable form
4453 ‘GPGME_SIG_NOTATION_CRITICAL’
4454 The ‘GPGME_SIG_NOTATION_CRITICAL’ symbol specifies that
4455 the notation data is critical.
4457 ‘unsigned int human_readable : 1’
4458 This is true if the ‘GPGME_SIG_NOTATION_HUMAN_READABLE’ flag
4459 is set and false otherwise. This flag is only valid for
4460 notation data, not for policy URLs.
4462 ‘unsigned int critical : 1’
4463 This is true if the ‘GPGME_SIG_NOTATION_CRITICAL’ flag is set
4464 and false otherwise. This flag is valid for notation data and
4467 -- Data type: gpgme_signature_t
4468 This is a pointer to a structure used to store a part of the result
4469 of a ‘gpgme_op_verify’ operation. The structure contains the
4472 ‘gpgme_signature_t next’
4473 This is a pointer to the next new signature structure in the
4474 linked list, or ‘NULL’ if this is the last element.
4476 ‘gpgme_sigsum_t summary’
4477 This is a bit vector giving a summary of the signature status.
4478 It provides an easy interface to a defined semantic of the
4479 signature status. Checking just one bit is sufficient to see
4480 whether a signature is valid without any restrictions.
4482 The defined bits are:
4483 ‘GPGME_SIGSUM_VALID’
4484 The signature is fully valid.
4486 ‘GPGME_SIGSUM_GREEN’
4487 The signature is good but one might want to display some
4488 extra information. Check the other bits.
4491 The signature is bad. It might be useful to check other
4492 bits and display more information, i.e. a revoked
4493 certificate might not render a signature invalid when the
4494 message was received prior to the cause for the
4497 ‘GPGME_SIGSUM_KEY_REVOKED’
4498 The key or at least one certificate has been revoked.
4500 ‘GPGME_SIGSUM_KEY_EXPIRED’
4501 The key or one of the certificates has expired. It is
4502 probably a good idea to display the date of the
4505 ‘GPGME_SIGSUM_SIG_EXPIRED’
4506 The signature has expired.
4508 ‘GPGME_SIGSUM_KEY_MISSING’
4509 Can’t verify due to a missing key or certificate.
4511 ‘GPGME_SIGSUM_CRL_MISSING’
4512 The CRL (or an equivalent mechanism) is not available.
4514 ‘GPGME_SIGSUM_CRL_TOO_OLD’
4515 Available CRL is too old.
4517 ‘GPGME_SIGSUM_BAD_POLICY’
4518 A policy requirement was not met.
4520 ‘GPGME_SIGSUM_SYS_ERROR’
4521 A system error occured.
4524 This is the fingerprint or key ID of the signature.
4526 ‘gpgme_error_t status’
4527 This is the status of the signature. In particular, the
4528 following status codes are of interest:
4531 This status indicates that the signature is valid. For
4532 the combined result this status means that all signatures
4535 ‘GPG_ERR_SIG_EXPIRED’
4536 This status indicates that the signature is valid but
4537 expired. For the combined result this status means that
4538 all signatures are valid and expired.
4540 ‘GPG_ERR_KEY_EXPIRED’
4541 This status indicates that the signature is valid but the
4542 key used to verify the signature has expired. For the
4543 combined result this status means that all signatures are
4544 valid and all keys are expired.
4546 ‘GPG_ERR_CERT_REVOKED’
4547 This status indicates that the signature is valid but the
4548 key used to verify the signature has been revoked. For
4549 the combined result this status means that all signatures
4550 are valid and all keys are revoked.
4552 ‘GPG_ERR_BAD_SIGNATURE’
4553 This status indicates that the signature is invalid. For
4554 the combined result this status means that all signatures
4558 This status indicates that the signature could not be
4559 verified due to a missing key. For the combined result
4560 this status means that all signatures could not be
4561 checked due to missing keys.
4564 This status indicates that there was some other error
4565 which prevented the signature verification.
4567 ‘gpgme_sig_notation_t notations’
4568 This is a linked list with the notation data and policy URLs.
4570 ‘unsigned long timestamp’
4571 The creation timestamp of this signature.
4573 ‘unsigned long exp_timestamp’
4574 The expiration timestamp of this signature, or 0 if the
4575 signature does not expire.
4577 ‘unsigned int wrong_key_usage : 1’
4578 This is true if the key was not used according to its policy.
4580 ‘unsigned int pka_trust : 2’
4581 This is set to the trust information gained by means of the
4582 PKA system. Values are:
4584 No PKA information available or verification not
4587 PKA verification failed.
4589 PKA verification succeeded.
4591 Reserved for future use.
4592 Depending on the configuration of the engine, this metric may
4593 also be reflected by the validity of the signature.
4595 ‘unsigned int chain_model : 1’
4596 This is true if the validity of the signature has been checked
4597 using the chain model. In the chain model the time the
4598 signature has been created must be within the validity period
4599 of the certificate and the time the certificate itself has
4600 been created must be within the validity period of the issuing
4601 certificate. In contrast the default validation model checks
4602 the validity of signature as well at the entire certificate
4603 chain at the current time.
4605 ‘gpgme_validity_t validity’
4606 The validity of the signature.
4608 ‘gpgme_error_t validity_reason’
4609 If a signature is not valid, this provides a reason why.
4611 ‘gpgme_pubkey_algo_t’
4612 The public key algorithm used to create this signature.
4615 The hash algorithm used to create this signature.
4618 The mailbox from the PKA information or ‘NULL’.
4621 An object describing the key used to create the signature.
4622 This key object may be incomplete in that it only conveys
4623 information availabale directly with a signature. It may also
4624 be ‘NULL’ if such information is not readily available.
4626 -- Data type: gpgme_verify_result_t
4627 This is a pointer to a structure used to store the result of a
4628 ‘gpgme_op_verify’ operation. After verifying a signature, you can
4629 retrieve the pointer to the result with ‘gpgme_op_verify_result’.
4630 If the operation failed this might be a ‘NULL’ pointer. The
4631 structure contains the following member:
4633 ‘gpgme_signature_t signatures’
4634 A linked list with information about all signatures for which
4635 a verification was attempted.
4638 This is the filename of the original plaintext message file if
4639 it is known, otherwise this is a null pointer.
4641 -- Function: gpgme_verify_result_t gpgme_op_verify_result
4643 The function ‘gpgme_op_verify_result’ returns a
4644 ‘gpgme_verify_result_t’ pointer to a structure holding the result
4645 of a ‘gpgme_op_verify’ operation. The pointer is only valid if the
4646 last operation on the context was a ‘gpgme_op_verify’,
4647 ‘gpgme_op_verify_start’, ‘gpgme_op_decrypt_verify’ or
4648 ‘gpgme_op_decrypt_verify_start’ operation, and if this operation
4649 finished successfully (for ‘gpgme_op_decrypt_verify’ and
4650 ‘gpgme_op_decrypt_verify_start’, the error code ‘GPG_ERR_NO_DATA’
4651 counts as successful in this context). The returned pointer is
4652 only valid until the next operation is started on the context.
4655 File: gpgme.info, Node: Decrypt and Verify, Next: Sign, Prev: Verify, Up: Crypto Operations
4657 7.7.3 Decrypt and Verify
4658 ------------------------
4660 -- Function: gpgme_error_t gpgme_op_decrypt_verify (gpgme_ctx_t CTX,
4661 gpgme_data_t CIPHER, gpgme_data_t PLAIN)
4662 The function ‘gpgme_op_decrypt_verify’ decrypts the ciphertext in
4663 the data object CIPHER and stores it into the data object PLAIN.
4664 If CIPHER contains signatures, they will be verified.
4666 After the operation completed, ‘gpgme_op_decrypt_result’ and
4667 ‘gpgme_op_verify_result’ can be used to retrieve more information
4668 about the signatures.
4670 If the error code ‘GPG_ERR_NO_DATA’ is returned, CIPHER does not
4671 contain any data to decrypt. However, it might still be signed.
4672 The information about detected signatures is available with
4673 ‘gpgme_op_verify_result’ in this case.
4675 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
4676 ciphertext could be decrypted successfully, ‘GPG_ERR_INV_VALUE’ if
4677 CTX, CIPHER or PLAIN is not a valid pointer, ‘GPG_ERR_NO_DATA’ if
4678 CIPHER does not contain any data to decrypt,
4679 ‘GPG_ERR_DECRYPT_FAILED’ if CIPHER is not a valid cipher text,
4680 ‘GPG_ERR_BAD_PASSPHRASE’ if the passphrase for the secret key could
4681 not be retrieved, and passes through any errors that are reported
4682 by the crypto engine support routines.
4684 -- Function: gpgme_error_t gpgme_op_decrypt_verify (gpgme_ctx_t CTX,
4685 gpgme_data_t CIPHER, gpgme_data_t PLAIN)
4686 The function ‘gpgme_op_decrypt_verify_start’ initiates a
4687 ‘gpgme_op_decrypt_verify’ operation. It can be completed by
4688 calling ‘gpgme_wait’ on the context. *Note Waiting For
4691 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
4692 operation could be started successfully, ‘GPG_ERR_INV_VALUE’ if
4693 CTX, CIPHER, PLAIN or R_STAT is not a valid pointer, and
4694 ‘GPG_ERR_NO_DATA’ if CIPHER does not contain any data to decrypt.
4696 When processing mails it is sometimes useful to extract the actual
4697 mail address (the “addr-spec”) from a string. GPGME provides this
4698 helper function which uses the same semantics as the internal functions
4701 -- Function: char * gpgme_addrspec_from_uid (const char *UID)
4703 Return the mail address (called “addr-spec” in RFC-5322) from the
4704 string UID which is assumed to be a user id (called “address” in
4705 RFC-5322). All plain ASCII characters (i.e. those with bit 7
4706 cleared) in the result are converted to lowercase. Caller must
4707 free the result using ‘gpgme_free’. Returns ‘NULL’ if no valid
4708 address was found (in which case ‘ERRNO’ is set to ‘EINVAL’) or for
4712 File: gpgme.info, Node: Sign, Next: Encrypt, Prev: Decrypt and Verify, Up: Crypto Operations
4717 A signature can contain signatures by one or more keys. The set of keys
4718 used to create a signatures is contained in a context, and is applied to
4719 all following signing operations in this context (until the set is
4724 * Selecting Signers:: How to choose the keys to sign with.
4725 * Creating a Signature:: How to create a signature.
4726 * Signature Notation Data:: How to add notation data to a signature.
4729 File: gpgme.info, Node: Selecting Signers, Next: Creating a Signature, Up: Sign
4731 7.7.4.1 Selecting Signers
4732 .........................
4734 The key or the keys used to create a signature are stored in the
4735 context. The following functions can be used to manipulate this list.
4736 If no signer has been set into the context a default key is used for
4739 -- Function: void gpgme_signers_clear (gpgme_ctx_t CTX)
4740 The function ‘gpgme_signers_clear’ releases a reference for each
4741 key on the signers list and removes the list of signers from the
4744 Every context starts with an empty list.
4746 -- Function: gpgme_error_t gpgme_signers_add (gpgme_ctx_t CTX,
4747 const gpgme_key_t KEY)
4748 The function ‘gpgme_signers_add’ adds the key KEY to the list of
4749 signers in the context CTX.
4751 Calling this function acquires an additional reference for the key.
4753 -- Function: unsigned int gpgme_signers_count (const gpgme_ctx_t CTX)
4754 The function ‘gpgme_signers_count’ returns the number of signer
4755 keys in the context CTX.
4757 -- Function: gpgme_key_t gpgme_signers_enum (const gpgme_ctx_t CTX,
4759 The function ‘gpgme_signers_enum’ returns the SEQth key in the list
4760 of signers in the context CTX. An additional reference is acquired
4763 If SEQ is out of range, ‘NULL’ is returned.
4766 File: gpgme.info, Node: Creating a Signature, Next: Signature Notation Data, Prev: Selecting Signers, Up: Sign
4768 7.7.4.2 Creating a Signature
4769 ............................
4771 -- Data type: enum gpgme_sig_mode_t
4772 The ‘gpgme_sig_mode_t’ type is used to specify the desired type of
4773 a signature. The following modes are available:
4775 ‘GPGME_SIG_MODE_NORMAL’
4776 A normal signature is made, the output includes the plaintext
4779 ‘GPGME_SIG_MODE_DETACH’
4780 A detached signature is made.
4782 ‘GPGME_SIG_MODE_CLEAR’
4783 A clear text signature is made. The ASCII armor and text mode
4784 settings of the context are ignored.
4786 -- Function: gpgme_error_t gpgme_op_sign (gpgme_ctx_t CTX,
4787 gpgme_data_t PLAIN, gpgme_data_t SIG, gpgme_sig_mode_t MODE)
4788 The function ‘gpgme_op_sign’ creates a signature for the text in
4789 the data object PLAIN and returns it in the data object SIG. The
4790 type of the signature created is determined by the ASCII armor (or,
4791 if that is not set, by the encoding specified for SIG), the text
4792 mode attributes set for the context CTX and the requested signature
4795 After the operation completed successfully, the result can be
4796 retrieved with ‘gpgme_op_sign_result’.
4798 If an S/MIME signed message is created using the CMS crypto engine,
4799 the number of certificates to include in the message can be
4800 specified with ‘gpgme_set_include_certs’. *Note Included
4803 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
4804 signature could be created successfully, ‘GPG_ERR_INV_VALUE’ if
4805 CTX, PLAIN or SIG is not a valid pointer, ‘GPG_ERR_NO_DATA’ if the
4806 signature could not be created, ‘GPG_ERR_BAD_PASSPHRASE’ if the
4807 passphrase for the secret key could not be retrieved,
4808 ‘GPG_ERR_UNUSABLE_SECKEY’ if there are invalid signers, and passes
4809 through any errors that are reported by the crypto engine support
4812 -- Function: gpgme_error_t gpgme_op_sign_start (gpgme_ctx_t CTX,
4813 gpgme_data_t PLAIN, gpgme_data_t SIG, gpgme_sig_mode_t MODE)
4814 The function ‘gpgme_op_sign_start’ initiates a ‘gpgme_op_sign’
4815 operation. It can be completed by calling ‘gpgme_wait’ on the
4816 context. *Note Waiting For Completion::.
4818 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
4819 operation could be started successfully, and ‘GPG_ERR_INV_VALUE’ if
4820 CTX, PLAIN or SIG is not a valid pointer.
4822 -- Data type: gpgme_new_signature_t
4823 This is a pointer to a structure used to store a part of the result
4824 of a ‘gpgme_op_sign’ operation. The structure contains the
4827 ‘gpgme_new_signature_t next’
4828 This is a pointer to the next new signature structure in the
4829 linked list, or ‘NULL’ if this is the last element.
4831 ‘gpgme_sig_mode_t type’
4832 The type of this signature.
4834 ‘gpgme_pubkey_algo_t pubkey_algo’
4835 The public key algorithm used to create this signature.
4837 ‘gpgme_hash_algo_t hash_algo’
4838 The hash algorithm used to create this signature.
4840 ‘unsigned int sig_class’
4841 The signature class of this signature.
4843 ‘long int timestamp’
4844 The creation timestamp of this signature.
4847 The fingerprint of the key which was used to create this
4850 -- Data type: gpgme_sign_result_t
4851 This is a pointer to a structure used to store the result of a
4852 ‘gpgme_op_sign’ operation. After successfully generating a
4853 signature, you can retrieve the pointer to the result with
4854 ‘gpgme_op_sign_result’. The structure contains the following
4857 ‘gpgme_invalid_key_t invalid_signers’
4858 A linked list with information about all invalid keys for
4859 which a signature could not be created.
4861 ‘gpgme_new_signature_t signatures’
4862 A linked list with information about all signatures created.
4864 -- Function: gpgme_sign_result_t gpgme_op_sign_result (gpgme_ctx_t CTX)
4865 The function ‘gpgme_op_sign_result’ returns a ‘gpgme_sign_result_t’
4866 pointer to a structure holding the result of a ‘gpgme_op_sign’
4867 operation. The pointer is only valid if the last operation on the
4868 context was a ‘gpgme_op_sign’, ‘gpgme_op_sign_start’,
4869 ‘gpgme_op_encrypt_sign’ or ‘gpgme_op_encrypt_sign_start’ operation.
4870 If that operation failed, the function might return a ‘NULL’
4871 pointer. The returned pointer is only valid until the next
4872 operation is started on the context.
4875 File: gpgme.info, Node: Signature Notation Data, Prev: Creating a Signature, Up: Sign
4877 7.7.4.3 Signature Notation Data
4878 ...............................
4880 Using the following functions, you can attach arbitrary notation data to
4881 a signature. This information is then available to the user when the
4882 signature is verified.
4884 -- Function: void gpgme_sig_notation_clear (gpgme_ctx_t CTX)
4885 The function ‘gpgme_sig_notation_clear’ removes the notation data
4886 from the context CTX. Subsequent signing operations from this
4887 context will not include any notation data.
4889 Every context starts with an empty notation data list.
4891 -- Function: gpgme_error_t gpgme_sig_notation_add (gpgme_ctx_t CTX,
4892 const char *NAME, const char *VALUE,
4893 gpgme_sig_notation_flags_t FLAGS)
4894 The function ‘gpgme_sig_notation_add’ adds the notation data with
4895 the name NAME and the value VALUE to the context CTX.
4897 Subsequent signing operations will include this notation data, as
4898 well as any other notation data that was added since the creation
4899 of the context or the last ‘gpgme_sig_notation_clear’ operation.
4901 The arguments NAME and VALUE must be ‘NUL’-terminated strings in
4902 human-readable form. The flag ‘GPGME_SIG_NOTATION_HUMAN_READABLE’
4903 is implied (non-human-readable notation data is currently not
4904 supported). The strings must be in UTF-8 encoding.
4906 If NAME is ‘NULL’, then VALUE should be a policy URL.
4908 The function ‘gpgme_sig_notation_add’ returns the error code
4909 ‘GPG_ERR_NO_ERROR’ if the notation data could be added
4910 successfully, ‘GPG_ERR_INV_VALUE’ if CTX is not a valid pointer, or
4911 if NAME, VALUE and FLAGS are an invalid combination. The function
4912 also passes through any errors that are reported by the crypto
4913 engine support routines.
4915 -- Function: gpgme_sig_notation_t gpgme_sig_notation_get
4916 (const gpgme_ctx_t CTX)
4917 The function ‘gpgme_sig_notation_get’ returns the linked list of
4918 notation data structures that are contained in the context CTX.
4920 If CTX is not a valid pointer, or there is no notation data added
4921 for this context, ‘NULL’ is returned.
4924 File: gpgme.info, Node: Encrypt, Prev: Sign, Up: Crypto Operations
4929 One plaintext can be encrypted for several recipients at the same time.
4930 The list of recipients is created independently of any context, and then
4931 passed to the encryption operation.
4935 * Encrypting a Plaintext:: How to encrypt a plaintext.
4938 File: gpgme.info, Node: Encrypting a Plaintext, Up: Encrypt
4940 7.7.5.1 Encrypting a Plaintext
4941 ..............................
4943 -- Function: gpgme_error_t gpgme_op_encrypt (gpgme_ctx_t CTX,
4944 gpgme_key_t RECP[], gpgme_encrypt_flags_t FLAGS,
4945 gpgme_data_t PLAIN, gpgme_data_t CIPHER)
4946 The function ‘gpgme_op_encrypt’ encrypts the plaintext in the data
4947 object PLAIN for the recipients RECP and stores the ciphertext in
4948 the data object CIPHER. The type of the ciphertext created is
4949 determined by the ASCII armor (or, if that is not set, by the
4950 encoding specified for CIPHER) and the text mode attributes set for
4953 RECP must be a ‘NULL’-terminated array of keys. The user must keep
4954 references for all keys during the whole duration of the call (but
4955 see ‘gpgme_op_encrypt_start’ for the requirements with the
4956 asynchronous variant).
4958 The value in FLAGS is a bitwise-or combination of one or multiple
4959 of the following bit values:
4961 ‘GPGME_ENCRYPT_ALWAYS_TRUST’
4962 The ‘GPGME_ENCRYPT_ALWAYS_TRUST’ symbol specifies that all the
4963 recipients in RECP should be trusted, even if the keys do not
4964 have a high enough validity in the keyring. This flag should
4965 be used with care; in general it is not a good idea to use any
4968 ‘GPGME_ENCRYPT_NO_ENCRYPT_TO’
4969 The ‘GPGME_ENCRYPT_NO_ENCRYPT_TO’ symbol specifies that no
4970 default or hidden default recipients as configured in the
4971 crypto backend should be included. This can be useful for
4972 managing different user profiles.
4974 ‘GPGME_ENCRYPT_NO_COMPRESS’
4975 The ‘GPGME_ENCRYPT_NO_COMPRESS’ symbol specifies that the
4976 plaintext shall not be compressed before it is encrypted.
4977 This is in some cases useful if the length of the encrypted
4978 message may reveal information about the plaintext.
4980 ‘GPGME_ENCRYPT_PREPARE’
4981 ‘GPGME_ENCRYPT_EXPECT_SIGN’
4982 The ‘GPGME_ENCRYPT_PREPARE’ symbol is used with the UI Server
4983 protocol to prepare an encryption (i.e. sending the
4984 ‘PREP_ENCRYPT’ command). With the ‘GPGME_ENCRYPT_EXPECT_SIGN’
4985 symbol the UI Server is advised to also expect a sign command.
4987 ‘GPGME_ENCRYPT_SYMMETRIC’
4988 The ‘GPGME_ENCRYPT_SYMMETRIC’ symbol specifies that the output
4989 should be additionally encrypted symmetically even if
4990 recipients are provided. This feature is only supported for
4991 for the OpenPGP crypto engine.
4993 If ‘GPG_ERR_UNUSABLE_PUBKEY’ is returned, some recipients in RECP
4994 are invalid, but not all. In this case the plaintext might be
4995 encrypted for all valid recipients and returned in CIPHER (if this
4996 happens depends on the crypto engine). More information about the
4997 invalid recipients is available with ‘gpgme_op_encrypt_result’.
4999 If RECP is ‘NULL’, symmetric rather than public key encryption is
5000 performed. Symmetrically encrypted cipher text can be deciphered
5001 with ‘gpgme_op_decrypt’. Note that in this case the crypto backend
5002 needs to retrieve a passphrase from the user. Symmetric encryption
5003 is currently only supported for the OpenPGP crypto backend.
5005 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
5006 ciphertext could be created successfully, ‘GPG_ERR_INV_VALUE’ if
5007 CTX, RECP, PLAIN or CIPHER is not a valid pointer,
5008 ‘GPG_ERR_UNUSABLE_PUBKEY’ if RECP contains some invalid recipients,
5009 ‘GPG_ERR_BAD_PASSPHRASE’ if the passphrase for the symmetric key
5010 could not be retrieved, and passes through any errors that are
5011 reported by the crypto engine support routines.
5013 -- Function: gpgme_error_t gpgme_op_encrypt_start (gpgme_ctx_t CTX,
5014 gpgme_key_t RECP[], gpgme_encrypt_flags_t FLAGS,
5015 gpgme_data_t PLAIN, gpgme_data_t CIPHER)
5016 The function ‘gpgme_op_encrypt_start’ initiates a
5017 ‘gpgme_op_encrypt’ operation. It can be completed by calling
5018 ‘gpgme_wait’ on the context. *Note Waiting For Completion::.
5020 References to the keys only need to be held for the duration of
5021 this call. The user can release its references to the keys after
5022 this function returns, even if the operation is not yet finished.
5024 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
5025 operation could be started successfully, ‘GPG_ERR_INV_VALUE’ if
5026 CTX, RSET, PLAIN or CIPHER is not a valid pointer, and
5027 ‘GPG_ERR_UNUSABLE_PUBKEY’ if RSET does not contain any valid
5030 -- Data type: gpgme_encrypt_result_t
5031 This is a pointer to a structure used to store the result of a
5032 ‘gpgme_op_encrypt’ operation. After successfully encrypting data,
5033 you can retrieve the pointer to the result with
5034 ‘gpgme_op_encrypt_result’. The structure contains the following
5037 ‘gpgme_invalid_key_t invalid_recipients’
5038 A linked list with information about all invalid keys for
5039 which the data could not be encrypted.
5041 -- Function: gpgme_encrypt_result_t gpgme_op_encrypt_result
5043 The function ‘gpgme_op_encrypt_result’ returns a
5044 ‘gpgme_encrypt_result_t’ pointer to a structure holding the result
5045 of a ‘gpgme_op_encrypt’ operation. The pointer is only valid if
5046 the last operation on the context was a ‘gpgme_op_encrypt’,
5047 ‘gpgme_op_encrypt_start’, ‘gpgme_op_sign’ or ‘gpgme_op_sign_start’
5048 operation. If this operation failed, this might be a ‘NULL’
5049 pointer. The returned pointer is only valid until the next
5050 operation is started on the context.
5052 -- Function: gpgme_error_t gpgme_op_encrypt_sign (gpgme_ctx_t CTX,
5053 gpgme_key_t RECP[], gpgme_encrypt_flags_t FLAGS,
5054 gpgme_data_t PLAIN, gpgme_data_t CIPHER)
5055 The function ‘gpgme_op_encrypt_sign’ does a combined encrypt and
5056 sign operation. It is used like ‘gpgme_op_encrypt’, but the
5057 ciphertext also contains signatures for the signers listed in CTX.
5059 The combined encrypt and sign operation is currently only available
5060 for the OpenPGP crypto engine.
5062 -- Function: gpgme_error_t gpgme_op_encrypt_sign_start
5063 (gpgme_ctx_t CTX, gpgme_key_t RECP,
5064 gpgme_encrypt_flags_t FLAGS, gpgme_data_t PLAIN,
5065 gpgme_data_t CIPHER)
5066 The function ‘gpgme_op_encrypt_sign_start’ initiates a
5067 ‘gpgme_op_encrypt_sign’ operation. It can be completed by calling
5068 ‘gpgme_wait’ on the context. *Note Waiting For Completion::.
5070 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
5071 operation could be started successfully, and ‘GPG_ERR_INV_VALUE’ if
5072 CTX, RSET, PLAIN or CIPHER is not a valid pointer.
5075 File: gpgme.info, Node: Miscellaneous, Next: Run Control, Prev: Crypto Operations, Up: Contexts
5077 7.8 Miscellaneous operations
5078 ============================
5080 Here are some support functions which are sometimes useful.
5084 * Running other Programs:: Running other Programs
5085 * Using the Assuan protocol:: Using the Assuan protocol
5088 File: gpgme.info, Node: Running other Programs, Next: Using the Assuan protocol, Up: Miscellaneous
5090 7.8.1 Running other Programs
5091 ----------------------------
5093 GPGME features an internal subsystem to run the actual backend engines.
5094 Along with data abstraction object this subsystem can be used to run
5095 arbitrary simple programs which even need not be related to
5096 cryptographic features. It may for example be used to run tools which
5097 are part of the GnuPG system but are not directly accessible with the
5100 -- Function: gpgme_error_t gpgme_op_spawn (gpgme_ctx_t CTX,
5101 const char *FILE, const char *ARGV[], gpgme_data_t DATAIN,
5102 gpgme_data_t DATAOUT, gpgme_data_t DATAERR,
5105 The function ‘gpgme_op_spawn’ runs the program FILE with the
5106 arguments taken from the NULL terminated array ARGV. If no
5107 arguments are required ARGV may be given as ‘NULL’. In the latter
5108 case or if ‘argv[0]’ is the empty string, GPGME uses the basename
5109 of FILE for ‘argv[0]’. The file descriptors ‘stdin’, ‘stdout’, and
5110 ‘stderr’ are connected to the data objects DATAIN, DATAOUT, and
5111 DATAERR. If NULL is passed for one of these data objects the
5112 corresponding file descriptor is connected to ‘/dev/null’.
5114 The value in FLAGS is a bitwise-or combination of one or multiple
5115 of the following bit values:
5117 ‘GPGME_SPAWN_DETACHED’
5118 Under Windows this flag inhibits the allocation of a new
5119 console for the program. This is useful for a GUI application
5120 which needs to call a command line helper tool.
5121 ‘GPGME_SPAWN_ALLOW_SET_FG’
5122 Under Windows this flag allows the called program to put
5123 itself into the foreground.
5125 -- Function: gpgme_error_t gpgme_op_spawn_start (gpgme_ctx_t CTX,
5126 const char *FILE, const char *ARGV[], gpgme_data_t DATAIN,
5127 gpgme_data_t DATAOUT, gpgme_data_t DATAERR,
5130 This is the asynchronous variant of ‘gpgme_op_spawn’.
5133 File: gpgme.info, Node: Using the Assuan protocol, Prev: Running other Programs, Up: Miscellaneous
5135 7.8.2 Using the Assuan protocol
5136 -------------------------------
5138 The Assuan protocol can be used to talk to arbitrary Assuan servers. By
5139 default it is connected to the GnuPG agent, but it may be connected to
5140 arbitrary servers by using ‘gpgme_ctx_set_engine_info’, passing the
5141 location of the servers socket as FILE_NAME argument, and an empty
5142 string as HOME_DIR argument.
5144 The Assuan protocol functions use three kinds of callbacks to
5147 -- Data type: gpgme_error_t (*gpgme_assuan_data_cb_t) (void *OPAQUE,
5148 const void *DATA, size_t DATALEN)
5150 This callback receives any data sent by the server. OPAQUE is the
5151 pointer passed to ‘gpgme_op_assuan_transact_start’, DATA of length
5152 DATALEN refers to the data sent.
5154 -- Data type: gpgme_error_t (*gpgme_assuan_inquire_cb_t) (void *OPAQUE,
5155 const char *NAME, const char *ARGS, gpgme_data_t *R_DATA)
5157 This callback is used to provide additional data to the Assuan
5158 server. OPAQUE is the pointer passed to
5159 ‘gpgme_op_assuan_transact_start’, NAME and ARGS specify what kind
5160 of data the server requested, and R_DATA is used to return the
5163 Note: Returning data is currently not implemented in GPGME.
5165 -- Data type: gpgme_error_t (*gpgme_assuan_status_cb_t) (void *OPAQUE,
5166 const char *STATUS, const char *ARGS)
5168 This callback receives any status lines sent by the server. OPAQUE
5169 is the pointer passed to ‘gpgme_op_assuan_transact_start’, STATUS
5170 and ARGS denote the status update sent.
5172 -- Function: gpgme_error_t gpgme_op_assuan_transact_start
5173 (gpgme_ctx_t CTX, const char *COMMAND,
5174 gpgme_assuan_data_cb_t DATA_CB, void * DATA_CB_VALUE,
5175 gpgme_assuan_inquire_cb_t INQUIRE_CB, void * INQUIRE_CB_VALUE,
5176 gpgme_assuan_status_cb_t STATUS_CB, void * STATUS_CB_VALUE)
5178 Send the Assuan COMMAND and return results via the callbacks. Any
5179 callback may be ‘NULL’. The result of the operation may be
5180 retrieved using ‘gpgme_wait_ext’.
5182 Asynchronous variant.
5184 -- Function: gpgme_error_t gpgme_op_assuan_transact_ext
5185 (gpgme_ctx_t CTX, const char *COMMAND,
5186 gpgme_assuan_data_cb_t DATA_CB, void * DATA_CB_VALUE,
5187 gpgme_assuan_inquire_cb_t INQUIRE_CB, void * INQUIRE_CB_VALUE,
5188 gpgme_assuan_status_cb_t STATUS_CB, void * STATUS_CB_VALUE,
5189 gpgme_error_t *OP_ERR)
5191 Send the Assuan COMMAND and return results via the callbacks. The
5192 result of the operation is returned in OP_ERR.
5194 Synchronous variant.
5197 File: gpgme.info, Node: Run Control, Prev: Miscellaneous, Up: Contexts
5202 GPGME supports running operations synchronously and asynchronously. You
5203 can use asynchronous operation to set up a context up to initiating the
5204 desired operation, but delay performing it to a later point.
5206 Furthermore, you can use an external event loop to control exactly
5207 when GPGME runs. This ensures that GPGME only runs when necessary and
5208 also prevents it from blocking for a long time.
5212 * Waiting For Completion:: Waiting until an operation is completed.
5213 * Using External Event Loops:: Advanced control over what happens when.
5214 * Cancellation:: How to end pending operations prematurely.
5217 File: gpgme.info, Node: Waiting For Completion, Next: Using External Event Loops, Up: Run Control
5219 7.9.1 Waiting For Completion
5220 ----------------------------
5222 -- Function: gpgme_ctx_t gpgme_wait (gpgme_ctx_t CTX,
5223 gpgme_error_t *STATUS, int HANG)
5224 The function ‘gpgme_wait’ continues the pending operation within
5225 the context CTX. In particular, it ensures the data exchange
5226 between GPGME and the crypto backend and watches over the run time
5227 status of the backend process.
5229 If HANG is true, the function does not return until the operation
5230 is completed or cancelled. Otherwise the function will not block
5233 The error status of the finished operation is returned in STATUS if
5234 ‘gpgme_wait’ does not return ‘NULL’.
5236 The CTX argument can be ‘NULL’. In that case, ‘gpgme_wait’ waits
5237 for any context to complete its operation.
5239 ‘gpgme_wait’ can be used only in conjunction with any context that
5240 has a pending operation initiated with one of the
5241 ‘gpgme_op_*_start’ functions except ‘gpgme_op_keylist_start’ and
5242 ‘gpgme_op_trustlist_start’ (for which you should use the
5243 corresponding ‘gpgme_op_*_next’ functions). If CTX is ‘NULL’, all
5244 of such contexts are waited upon and possibly returned.
5245 Synchronous operations running in parallel, as well as key and
5246 trust item list operations, do not affect ‘gpgme_wait’.
5248 In a multi-threaded environment, only one thread should ever call
5249 ‘gpgme_wait’ at any time, irregardless if CTX is specified or not.
5250 This means that all calls to this function should be fully
5251 synchronized by locking primitives. It is safe to start
5252 asynchronous operations while a thread is running in ‘gpgme_wait’.
5254 The function returns the CTX of the context which has finished the
5255 operation. If HANG is false, and the timeout expires, ‘NULL’ is
5256 returned and ‘*status’ will be set to 0. If an error occurs,
5257 ‘NULL’ is returned and the error is returned in ‘*status’.
5260 File: gpgme.info, Node: Using External Event Loops, Next: Cancellation, Prev: Waiting For Completion, Up: Run Control
5262 7.9.2 Using External Event Loops
5263 --------------------------------
5265 GPGME hides the complexity of the communication between the library and
5266 the crypto engine. The price of this convenience is that the calling
5267 thread can block arbitrary long waiting for the data returned by the
5268 crypto engine. In single-threaded programs, in particular if they are
5269 interactive, this is an unwanted side-effect. OTOH, if ‘gpgme_wait’ is
5270 used without the HANG option being enabled, it might be called
5271 unnecessarily often, wasting CPU time that could be used otherwise.
5273 The I/O callback interface described in this section lets the user
5274 take control over what happens when. GPGME will provide the user with
5275 the file descriptors that should be monitored, and the callback
5276 functions that should be invoked when a file descriptor is ready for
5277 reading or writing. It is then the user’s responsibility to decide when
5278 to check the file descriptors and when to invoke the callback functions.
5279 Usually this is done in an event loop, that also checks for events in
5280 other parts of the program. If the callback functions are only called
5281 when the file descriptors are ready, GPGME will never block. This gives
5282 the user more control over the program flow, and allows to perform other
5283 tasks when GPGME would block otherwise.
5285 By using this advanced mechanism, GPGME can be integrated smoothly
5286 into GUI toolkits like GTK+ even for single-threaded programs.
5290 * I/O Callback Interface:: How I/O callbacks are registered.
5291 * Registering I/O Callbacks:: How to use I/O callbacks for a context.
5292 * I/O Callback Example:: An example how to use I/O callbacks.
5293 * I/O Callback Example GTK+:: How to use GPGME with GTK+.
5294 * I/O Callback Example GDK:: How to use GPGME with GDK.
5295 * I/O Callback Example Qt:: How to use GPGME with Qt.
5298 File: gpgme.info, Node: I/O Callback Interface, Next: Registering I/O Callbacks, Up: Using External Event Loops
5300 7.9.2.1 I/O Callback Interface
5301 ..............................
5303 -- Data type: gpgme_error_t (*gpgme_io_cb_t) (void *DATA, int FD)
5304 The ‘gpgme_io_cb_t’ type is the type of functions which GPGME wants
5305 to register as I/O callback handlers using the
5306 ‘gpgme_register_io_cb_t’ functions provided by the user.
5308 DATA and FD are provided by GPGME when the I/O callback handler is
5309 registered, and should be passed through to the handler when it is
5310 invoked by the user because it noticed activity on the file
5313 The callback handler always returns ‘0’, but you should consider
5314 the return value to be reserved for later use.
5316 -- Data type: gpgme_error_t (*gpgme_register_io_cb_t) (void *DATA,
5317 int FD, int DIR, gpgme_io_cb_t FNC, void *FNC_DATA,
5319 The ‘gpgme_register_io_cb_t’ type is the type of functions which
5320 can be called by GPGME to register an I/O callback function FNC for
5321 the file descriptor FD with the user. FNC_DATA should be passed as
5322 the first argument to FNC when the handler is invoked (the second
5323 argument should be FD). If DIR is 0, FNC should be called by the
5324 user when FD is ready for writing. If DIR is 1, FNC should be
5325 called when FD is ready for reading.
5327 DATA was provided by the user when registering the
5328 ‘gpgme_register_io_cb_t’ function with GPGME and will always be
5329 passed as the first argument when registering a callback function.
5330 For example, the user can use this to determine the event loop to
5331 which the file descriptor should be added.
5333 GPGME will call this function when a crypto operation is initiated
5334 in a context for which the user has registered I/O callback handler
5335 functions with ‘gpgme_set_io_cbs’. It can also call this function
5336 when it is in an I/O callback handler for a file descriptor
5337 associated to this context.
5339 The user should return a unique handle in TAG identifying this I/O
5340 callback registration, which will be passed to the
5341 ‘gpgme_register_io_cb_t’ function without interpretation when the
5342 file descriptor should not be monitored anymore.
5344 -- Data type: void (*gpgme_remove_io_cb_t) (void *TAG)
5345 The ‘gpgme_remove_io_cb_t’ type is the type of functions which can
5346 be called by GPGME to remove an I/O callback handler that was
5347 registered before. TAG is the handle that was returned by the
5348 ‘gpgme_register_io_cb_t’ for this I/O callback.
5350 GPGME can call this function when a crypto operation is in an I/O
5351 callback. It will also call this function when the context is
5352 destroyed while an operation is pending.
5354 -- Data type: enum gpgme_event_io_t
5355 The ‘gpgme_event_io_t’ type specifies the type of an event that is
5356 reported to the user by GPGME as a consequence of an I/O operation.
5357 The following events are defined:
5360 The operation is fully initialized now, and you can start to
5361 run the registered I/O callback handlers now. Note that
5362 registered I/O callback handlers must not be run before this
5363 event is signalled. TYPE_DATA is ‘NULL’ and reserved for
5367 The operation is finished, the last I/O callback for this
5368 operation was removed. The accompanying TYPE_DATA points to a
5369 ‘struct gpgme_io_event_done_data’ variable that contains the
5370 status of the operation that finished. This event is
5371 signalled after the last I/O callback has been removed.
5373 ‘GPGME_EVENT_NEXT_KEY’
5374 In a ‘gpgme_op_keylist_start’ operation, the next key was
5375 received from the crypto engine. The accompanying TYPE_DATA
5376 is a ‘gpgme_key_t’ variable that contains the key with one
5377 reference for the user.
5379 ‘GPGME_EVENT_NEXT_TRUSTITEM’
5380 In a ‘gpgme_op_trustlist_start’ operation, the next trust item
5381 was received from the crypto engine. The accompanying
5382 TYPE_DATA is a ‘gpgme_trust_item_t’ variable that contains the
5383 trust item with one reference for the user.
5385 -- Data type: void (*gpgme_event_io_cb_t) (void *DATA,
5386 gpgme_event_io_t TYPE, void *TYPE_DATA)
5387 The ‘gpgme_event_io_cb_t’ type is the type of functions which can
5388 be called by GPGME to signal an event for an operation running in a
5389 context which has I/O callback functions registered by the user.
5391 DATA was provided by the user when registering the
5392 ‘gpgme_event_io_cb_t’ function with GPGME and will always be passed
5393 as the first argument when registering a callback function. For
5394 example, the user can use this to determine the context in which
5395 this event has occured.
5397 TYPE will specify the type of event that has occured. TYPE_DATA
5398 specifies the event further, as described in the above list of
5399 possible ‘gpgme_event_io_t’ types.
5401 GPGME can call this function in an I/O callback handler.
5404 File: gpgme.info, Node: Registering I/O Callbacks, Next: I/O Callback Example, Prev: I/O Callback Interface, Up: Using External Event Loops
5406 7.9.2.2 Registering I/O Callbacks
5407 .................................
5409 -- Data type: struct gpgme_io_cbs
5410 This structure is used to store the I/O callback interface
5411 functions described in the previous section. It has the following
5414 ‘gpgme_register_io_cb_t add’
5415 This is the function called by GPGME to register an I/O
5416 callback handler. It must be specified.
5419 This is passed as the first argument to the ‘add’ function
5420 when it is called by GPGME. For example, it can be used to
5421 determine the event loop to which the file descriptor should
5424 ‘gpgme_remove_io_cb_t remove’
5425 This is the function called by GPGME to remove an I/O callback
5426 handler. It must be specified.
5428 ‘gpgme_event_io_cb_t event’
5429 This is the function called by GPGME to signal an event for an
5430 operation. It must be specified, because at least the start
5431 event must be processed.
5434 This is passed as the first argument to the ‘event’ function
5435 when it is called by GPGME. For example, it can be used to
5436 determine the context in which the event has occured.
5438 -- Function: void gpgme_set_io_cbs (gpgme_ctx_t CTX,
5439 struct gpgme_io_cbs *IO_CBS)
5440 The function ‘gpgme_set_io_cbs’ enables the I/O callback interface
5441 for the context CTX. The I/O callback functions are specified by
5444 If IO_CBS->‘add’ is ‘NULL’, the I/O callback interface is disabled
5445 for the context, and normal operation is restored.
5447 -- Function: void gpgme_get_io_cbs (gpgme_ctx_t CTX,
5448 struct gpgme_io_cbs *IO_CBS)
5449 The function ‘gpgme_get_io_cbs’ returns the I/O callback functions
5450 set with ‘gpgme_set_io_cbs’ in IO_CBS.
5453 File: gpgme.info, Node: I/O Callback Example, Next: I/O Callback Example GTK+, Prev: Registering I/O Callbacks, Up: Using External Event Loops
5455 7.9.2.3 I/O Callback Example
5456 ............................
5458 To actually use an external event loop, you have to implement the I/O
5459 callback functions that are used by GPGME to register and unregister
5460 file descriptors. Furthermore, you have to actually monitor these file
5461 descriptors for activity and call the appropriate I/O callbacks.
5463 The following example illustrates how to do that. The example uses
5464 locking to show in which way the callbacks and the event loop can run
5465 concurrently. For the event loop, we use a fixed array. For a
5466 real-world implementation, you should use a dynamically sized structure
5467 because the number of file descriptors needed for a crypto operation in
5468 GPGME is not predictable.
5473 #include <pthread.h>
5474 #include <sys/types.h>
5477 /* The following structure holds the result of a crypto operation. */
5484 /* The following structure holds the data associated with one I/O
5497 pthread_mutex_t lock;
5499 /* Unused slots are marked with FD being -1. */
5500 struct one_fd fds[MAX_FDS];
5503 The following functions implement the I/O callback interface.
5506 add_io_cb (void *data, int fd, int dir, gpgme_io_cb_t fnc, void *fnc_data,
5509 struct event_loop *loop = data;
5510 struct one_fd *fds = loop->fds;
5513 pthread_mutex_lock (&loop->lock);
5514 for (i = 0; i < MAX_FDS; i++)
5516 if (fds[i].fd == -1)
5521 fds[i].fnc_data = fnc_data;
5526 pthread_mutex_unlock (&loop->lock);
5528 return gpg_error (GPG_ERR_GENERAL);
5534 remove_io_cb (void *tag)
5536 struct one_fd *fd = tag;
5537 struct event_loop *loop = fd->loop;
5539 pthread_mutex_lock (&loop->lock);
5541 pthread_mutex_unlock (&loop->lock);
5545 event_io_cb (void *data, gpgme_event_io_t type, void *type_data)
5547 struct op_result *result = data;
5549 /* We don't support list operations here. */
5550 if (type == GPGME_EVENT_DONE)
5553 result->err = *type_data;
5557 The final missing piece is the event loop, which will be presented
5558 next. We only support waiting for the success of a single operation.
5561 do_select (struct event_loop *loop)
5568 struct one_fd *fdlist = loop->fds;
5570 pthread_mutex_lock (&loop->lock);
5573 for (i = 0; i < MAX_FDS; i++)
5574 if (fdlist[i].fd != -1)
5575 FD_SET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds);
5576 pthread_mutex_unlock (&loop->lock);
5583 n = select (FD_SETSIZE, &rfds, &wfds, NULL, &tv);
5585 while (n < 0 && errno == EINTR);
5588 return n; /* Error or timeout. */
5590 pthread_mutex_lock (&loop->lock);
5591 for (i = 0; i < MAX_FDS && n; i++)
5593 if (fdlist[i].fd != -1)
5595 if (FD_ISSET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds))
5600 /* The I/O callback handler can register/remove callbacks,
5601 so we have to unlock the file descriptor list. */
5602 pthread_mutex_unlock (&loop->lock);
5603 (*fdlist[i].fnc) (fdlist[i].fnc_data, fdlist[i].fd);
5604 pthread_mutex_lock (&loop->lock);
5608 pthread_mutex_unlock (&loop->lock);
5613 wait_for_op (struct event_loop *loop, struct op_result *result)
5619 ret = do_select (loop);
5621 while (ret >= 0 && !result->done);
5624 The main function shows how to put it all together.
5627 main (int argc, char *argv[])
5629 struct event_loop loop;
5630 struct op_result result;
5633 gpgme_data_t sig, text;
5635 pthread_mutexattr_t attr;
5636 struct gpgme_io_cbs io_cbs =
5647 /* Initialize the loop structure. */
5649 /* The mutex must be recursive, since remove_io_cb (which acquires a
5650 lock) can be called while holding a lock acquired in do_select. */
5651 pthread_mutexattr_init (&attr);
5652 pthread_mutexattr_settype (&attr, PTHREAD_MUTEX_RECURSIVE);
5653 pthread_mutex_init (&loop.lock, &attr);
5654 pthread_mutexattr_destroy (&attr);
5656 for (i = 0; i < MAX_FDS; i++)
5657 loop.fds[i].fd = -1;
5659 /* Initialize the result structure. */
5662 err = gpgme_data_new_from_file (&sig, "signature", 1);
5664 err = gpgme_data_new_from_file (&text, "text", 1);
5666 err = gpgme_new (&ctx);
5669 gpgme_set_io_cbs (ctx, &io_cbs);
5670 err = gpgme_op_verify_start (ctx, sig, text, NULL);
5674 fprintf (stderr, "gpgme error: %s: %s\n",
5675 gpgme_strsource (err), gpgme_strerror (err));
5679 wait_for_op (&loop, &result);
5682 fprintf (stderr, "select error\n");
5687 fprintf (stderr, "verification failed: %s: %s\n",
5688 gpgme_strsource (result.err), gpgme_strerror (result.err));
5691 /* Evaluate verify result. */
5697 File: gpgme.info, Node: I/O Callback Example GTK+, Next: I/O Callback Example GDK, Prev: I/O Callback Example, Up: Using External Event Loops
5699 7.9.2.4 I/O Callback Example GTK+
5700 .................................
5702 The I/O callback interface can be used to integrate GPGME with the GTK+
5703 event loop. The following code snippets shows how this can be done
5704 using the appropriate register and remove I/O callback functions. In
5705 this example, the private data of the register I/O callback function is
5706 unused. The event notifications is missing because it does not require
5707 any GTK+ specific setup.
5709 #include <gtk/gtk.h>
5711 struct my_gpgme_io_cb
5715 guint input_handler_id
5719 my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition)
5721 struct my_gpgme_io_cb *iocb = data;
5722 (*(iocb->fnc)) (iocb->data, source);
5726 my_gpgme_remove_io_cb (void *data)
5728 struct my_gpgme_io_cb *iocb = data;
5729 gtk_input_remove (data->input_handler_id);
5733 my_gpgme_register_io_callback (void *data, int fd, int dir, gpgme_io_cb_t fnc,
5734 void *fnc_data, void **tag)
5736 struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb));
5738 iocb->data = fnc_data;
5739 iocb->input_handler_id = gtk_input_add_full (fd, dir
5742 my_gpgme_io_callback,
5749 File: gpgme.info, Node: I/O Callback Example GDK, Next: I/O Callback Example Qt, Prev: I/O Callback Example GTK+, Up: Using External Event Loops
5751 7.9.2.5 I/O Callback Example GDK
5752 ................................
5754 The I/O callback interface can also be used to integrate GPGME with the
5755 GDK event loop. The following code snippets shows how this can be done
5756 using the appropriate register and remove I/O callback functions. In
5757 this example, the private data of the register I/O callback function is
5758 unused. The event notifications is missing because it does not require
5759 any GDK specific setup.
5761 It is very similar to the GTK+ example in the previous section.
5763 #include <gdk/gdk.h>
5765 struct my_gpgme_io_cb
5773 my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition)
5775 struct my_gpgme_io_cb *iocb = data;
5776 (*(iocb->fnc)) (iocb->data, source);
5780 my_gpgme_remove_io_cb (void *data)
5782 struct my_gpgme_io_cb *iocb = data;
5783 gdk_input_remove (data->tag);
5787 my_gpgme_register_io_callback (void *data, int fd, int dir, gpgme_io_cb_t fnc,
5788 void *fnc_data, void **tag)
5790 struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb));
5792 iocb->data = fnc_data;
5793 iocb->tag = gtk_input_add_full (fd, dir ? GDK_INPUT_READ : GDK_INPUT_WRITE,
5794 my_gpgme_io_callback, iocb, NULL);
5800 File: gpgme.info, Node: I/O Callback Example Qt, Prev: I/O Callback Example GDK, Up: Using External Event Loops
5802 7.9.2.6 I/O Callback Example Qt
5803 ...............................
5805 The I/O callback interface can also be used to integrate GPGME with the
5806 Qt event loop. The following code snippets show how this can be done
5807 using the appropriate register and remove I/O callback functions. In
5808 this example, the private data of the register I/O callback function is
5809 unused. The event notifications is missing because it does not require
5810 any Qt specific setup.
5812 #include <qsocketnotifier.h>
5813 #include <qapplication.h>
5816 IOCB( GpgmeIOCb f, void * d, QSocketNotifier * n )
5817 : func( f ), data( d ), notifier( n ) {}
5820 QSocketNotifier * notifier;
5823 class MyApp : public QApplication {
5827 static void registerGpgmeIOCallback( void * data, int fd, int dir,
5828 GpgmeIOCb func, void * func_data,
5830 QSocketNotifier * n =
5831 new QSocketNotifier( fd, dir ? QSocketNotifier::Read
5832 : QSocketNotifier::Write );
5833 connect( n, SIGNAL(activated(int)),
5834 qApp, SLOT(slotGpgmeIOCallback(int)) );
5835 qApp->mIOCBs.push_back( IOCB( func, func_data, n ) );
5839 static void removeGpgmeIOCallback( void * tag ) {
5841 QSocketNotifier * n = static_cast<QSocketNotifier*>( tag );
5842 for ( QValueList<IOCB>::iterator it = qApp->mIOCBs.begin() ;
5843 it != qApp->mIOCBs.end() ; ++it )
5844 if ( it->notifier == n ) {
5845 delete it->notifier;
5846 qApp->mIOCBs.erase( it );
5852 void slotGpgmeIOCallback( int fd ) {
5853 for ( QValueList<IOCB>::const_iterator it = mIOCBs.begin() ;
5854 it != mIOCBs.end() ; ++it )
5855 if ( it->notifier && it->notifier->socket() == fd )
5856 (*(it->func)) ( it->func_data, fd );
5862 QValueList<IOCB> mIOCBs;
5867 File: gpgme.info, Node: Cancellation, Prev: Using External Event Loops, Up: Run Control
5872 Sometimes you do not want to wait for an operation to finish. GPGME
5873 provides two different functions to achieve that. The function
5874 ‘gpgme_cancel’ takes effect immediately. When it returns, the operation
5875 is effectively canceled. However, it has some limitations and can not
5876 be used with synchronous operations. In contrast, the function
5877 ‘gpgme_cancel_async’ can be used with any context and from any thread,
5878 but it is not guaranteed to take effect immediately. Instead,
5879 cancellation occurs at the next possible time (typically the next time
5880 I/O occurs in the target context).
5882 -- Function: gpgme_ctx_t gpgme_cancel (gpgme_ctx_t CTX)
5883 The function ‘gpgme_cancel’ attempts to cancel a pending operation
5884 in the context CTX. This only works if you use the global event
5885 loop or your own event loop.
5887 If you use the global event loop, you must not call ‘gpgme_wait’
5888 during cancellation. After successful cancellation, you can call
5889 ‘gpgme_wait’ (optionally waiting on CTX), and the context CTX will
5890 appear as if it had finished with the error code ‘GPG_ERR_CANCEL’.
5892 If you use an external event loop, you must ensure that no I/O
5893 callbacks are invoked for this context (for example by halting the
5894 event loop). On successful cancellation, all registered I/O
5895 callbacks for this context will be unregistered, and a
5896 ‘GPGME_EVENT_DONE’ event with the error code ‘GPG_ERR_CANCEL’ will
5899 The function returns an error code if the cancellation failed (in
5900 this case the state of CTX is not modified).
5902 -- Function: gpgme_ctx_t gpgme_cancel_async (gpgme_ctx_t CTX)
5903 The function ‘gpgme_cancel’ attempts to cancel a pending operation
5904 in the context CTX. This can be called by any thread at any time
5905 after starting an operation on the context, but will not take
5906 effect immediately. The actual cancellation happens at the next
5907 time GPGME processes I/O in that context.
5909 The function returns an error code if the cancellation failed (in
5910 this case the state of CTX is not modified).
5913 File: gpgme.info, Node: UI Server Protocol, Next: Debugging, Prev: Contexts, Up: Top
5915 Appendix A The GnuPG UI Server Protocol
5916 ***************************************
5918 This section specifies the protocol used between clients and a User
5919 Interface Server (UI server). This protocol helps to build a system
5920 where all cryptographic operations are done by a server and the server
5921 is responsible for all dialogs. Although GPGME has no direct support
5922 for this protocol it is believed that servers will utilize the GPGME
5923 library; thus having the specification included in this manual is an
5924 appropriate choice. This protocol should be referenced as ‘The GnuPG UI
5927 A server needs to implement these commands:(1)
5931 * UI Server Encrypt:: Encrypt a message.
5932 * UI Server Sign:: Sign a message.
5933 * UI Server Decrypt:: Decrypt a message.
5934 * UI Server Verify:: Verify a message.
5935 * UI Server Set Input Files:: Specifying the input files to operate on.
5936 * UI Server Sign/Encrypt Files:: Encrypting and signing files.
5937 * UI Server Verify/Decrypt Files:: Decrypting and verifying files.
5938 * UI Server Import/Export Keys:: Managing certificates.
5939 * UI Server Checksum Files:: Create and verify checksums for files.
5940 * Miscellaneous UI Server Commands:: Commands not related to a specific operation.
5942 ---------- Footnotes ----------
5944 (1) In all examples we assume that the connection has already been
5945 established; see the Assuan manual for details.
5948 File: gpgme.info, Node: UI Server Encrypt, Next: UI Server Sign, Up: UI Server Protocol
5950 A.1 UI Server: Encrypt a Message
5951 ================================
5953 Before encryption can be done the recipients must be set using the
5956 -- Command: RECIPIENT STRING
5958 Set the recipient for the encryption. STRING is an RFC-2822
5959 recipient name ("mailbox" as per section 3.4). This command may or
5960 may not check the recipient for validity right away; if it does not
5961 all recipients are expected to be checked at the time of the
5962 ‘ENCRYPT’ command. All ‘RECIPIENT’ commands are cumulative until a
5963 successful ‘ENCRYPT’ command or until a ‘RESET’ command. Linefeeds
5964 are obviously not allowed in STRING and should be folded into
5965 spaces (which are equivalent).
5967 To tell the server the source and destination of the data, the next two
5968 commands are to be used:
5970 -- Command: INPUT FD=N
5971 Set the file descriptor for the message to be encrypted to N. The
5972 message send to the server is binary encoded.
5974 GpgOL is a Windows only program, thus N is not a libc file
5975 descriptor but a regular system handle. Given that the Assuan
5976 connection works over a socket, it is not possible to use regular
5977 inheritance to make the file descriptor available to the server.
5978 Thus ‘DuplicateHandle’ needs to be used to duplicate a handle to
5979 the server process. This is the reason that the server needs to
5980 implement the ‘GETINFO pid’ command. Sending this command a second
5981 time replaces the file descriptor set by the last one.
5983 -- Command: OUTPUT FD=N [--binary]
5984 Set the file descriptor to be used for the output (i.e. the
5985 encrypted message) to N. If the option ‘--binary’ is given the
5986 output shall be in binary format; if not given, the output for
5987 OpenPGP needs to be ASCII armored and for CMS Base-64 encoded. For
5988 details on the file descriptor, see the ‘INPUT’ command.
5990 The setting of the recipients, the data source and destination may
5991 happen in any order, even intermixed. If this has been done the actual
5992 encryption operation is called using:
5994 -- Command: ENCRYPT --protocol=NAME
5996 This command reads the plaintext from the file descriptor set by
5997 the ‘INPUT’ command, encrypts it and writes the ciphertext to the
5998 file descriptor set by the ‘OUTPUT’ command. The server may (and
5999 should) overlap reading and writing. The recipients used for the
6000 encryption are all the recipients set so far. If any recipient is
6001 not usable the server should take appropriate measures to notify
6002 the user about the problem and may cancel the operation by
6003 returning an error code. The used file descriptors are void after
6004 this command; the recipient list is only cleared if the server
6007 Because GpgOL uses a streaming mode of operation the server is not
6008 allowed to auto select the protocol and must obey to the mandatory
6012 Use the OpenPGP protocol (RFC-2440).
6014 Use the CMS (PKCS#7) protocol (RFC-3852).
6016 To support automagically selection of the protocol depending on the
6017 selected keys, the server MAY implement the command:
6019 -- Command: PREP_ENCRYPT [--protocol=NAME] [--expect-sign]
6021 This commands considers all recipients set so far and decides
6022 whether it is able to take input and start the actual encryption.
6023 This is kind of a dry-run ‘ENCRYPT’ without requiring or using the
6024 input and output file descriptors. The server shall cache the
6025 result of any user selection to avoid asking this again when the
6026 actual ‘ENCRYPT’ command is send. The ‘--protocol’ option is
6027 optional; if it is not given, the server should allow the user to
6028 select the protocol to be used based on the recipients given or by
6031 If ‘--expect-sign’ is given the server should expect that the
6032 message will also be signed and use this hint to present a unified
6033 recipient and signer selection dialog if possible and desired. A
6034 selected signer should then be cached for the expected SIGN command
6035 (which is expected in the same session but possible on another
6038 If this command is given again before a successful ‘ENCRYPT’
6039 command, the second one takes effect.
6041 Before sending the OK response the server shall tell the client the
6042 protocol to be used (either the one given by the argument or the
6043 one selected by the user) by means of a status line:
6045 -- Status line: PROTOCOL NAME
6046 Advise the client to use the protocol NAME for the ‘ENCRYPT’
6047 command. The valid protocol names are listed under the description
6048 of the ‘ENCRYPT’ command. The server shall emit exactly one
6049 PROTOCOL status line.
6051 Here is an example of a complete encryption sequence; client lines are
6052 indicated by a C:, server responses by C::
6054 C: S: C: S: C: S: C: S: S: C: S: C: S: C: S:
6057 File: gpgme.info, Node: UI Server Sign, Next: UI Server Decrypt, Prev: UI Server Encrypt, Up: UI Server Protocol
6059 A.2 UI Server: Sign a Message
6060 =============================
6062 The server needs to implement opaque signing as well as detached
6063 signing. Due to the nature of OpenPGP messages it is always required to
6064 send the entire message to the server; sending just the hash is not
6065 possible. The following two commands are required to set the input and
6066 output file descriptors:
6068 -- Command: INPUT FD=N
6069 Set the file descriptor for the message to be signed to N. The
6070 message send to the server is binary encoded. For details on the
6071 file descriptor, see the description of ‘INPUT’ in the ‘ENCRYPT’
6074 -- Command: OUTPUT FD=N [--binary]
6075 Set the file descriptor to be used for the output. The output is
6076 either the complete signed message or in case of a detached
6077 signature just that detached signature. If the option ‘--binary’
6078 is given the output shall be in binary format; if not given, the
6079 output for OpenPGP needs to be ASCII armored and for CMS Base-64
6080 encoded. For details on the file descriptor, see the ‘INPUT’
6083 To allow the server the selection of a non-default signing key the
6084 client may optionally use the ‘SENDER’ command, see *note command
6087 The signing operation is then initiated by:
6089 -- Command: SIGN --protocol=NAME [--detached]
6090 Sign the data set with the ‘INPUT’ command and write it to the sink
6091 set by OUTPUT. NAME is the signing protocol used for the message.
6092 For a description of the allowed protocols see the ‘ENCRYPT’
6093 command. With option ‘--detached’ given, a detached signature is
6094 created; this is actually the usual way the command is used.
6096 The client expects the server to send at least this status information
6097 before the final OK response:
6099 -- Status line: MICALG STRING
6100 The STRING represents the hash algorithm used to create the
6101 signature. It is used with RFC-1847 style signature messages and
6102 defined by PGP/MIME (RFC-3156) and S/MIME (RFC-3851). The GPGME
6103 library has a supporting function ‘gpgme_hash_algo_name’ to return
6104 the algorithm name as a string. This string needs to be lowercased
6105 and for OpenPGP prefixed with "‘pgp-’".
6108 File: gpgme.info, Node: UI Server Decrypt, Next: UI Server Verify, Prev: UI Server Sign, Up: UI Server Protocol
6110 A.3 UI Server: Decrypt a Message
6111 ================================
6113 Decryption may include the verification of OpenPGP messages. This is
6114 due to the often used combined signing/encryption modus of OpenPGP. The
6115 client may pass an option to the server to inhibit the signature
6116 verification. The following two commands are required to set the input
6117 and output file descriptors:
6119 -- Command: INPUT FD=N
6120 Set the file descriptor for the message to be decrypted to N. The
6121 message send to the server is either binary encoded or — in the
6122 case of OpenPGP — ASCII armored. For details on the file
6123 descriptor, see the description of ‘INPUT’ in the ‘ENCRYPT’
6126 -- Command: OUTPUT FD=N
6127 Set the file descriptor to be used for the output. The output is
6128 binary encoded. For details on the file descriptor, see the
6129 description of ‘INPUT’ in the ‘ENCRYPT’ section.
6131 The decryption is started with the command:
6133 -- Command: DECRYPT --protocol=NAME [--no-verify]
6134 NAME is the encryption protocol used for the message. For a
6135 description of the allowed protocols see the ‘ENCRYPT’ command.
6136 This argument is mandatory. If the option ‘--no-verify’ is given,
6137 the server should not try to verify a signature, in case the input
6138 data is an OpenPGP combined message.
6141 File: gpgme.info, Node: UI Server Verify, Next: UI Server Set Input Files, Prev: UI Server Decrypt, Up: UI Server Protocol
6143 A.4 UI Server: Verify a Message
6144 ===============================
6146 The server needs to support the verification of opaque signatures as
6147 well as detached signatures. The kind of input sources controls what
6148 kind message is to be verified.
6150 -- Command: MESSAGE FD=N
6151 This command is used with detached signatures to set the file
6152 descriptor for the signed data to N. The data is binary encoded
6153 (used verbatim). For details on the file descriptor, see the
6154 description of ‘INPUT’ in the ‘ENCRYPT’ section.
6156 -- Command: INPUT FD=N
6157 Set the file descriptor for the opaque message or the signature
6158 part of a detached signature to N. The message send to the server
6159 is either binary encoded or – in the case of OpenPGP – ASCII
6160 armored. For details on the file descriptor, see the description
6161 of ‘INPUT’ in the ‘ENCRYPT’ section.
6163 -- Command: OUTPUT FD=N
6164 Set the file descriptor to be used for the output. The output is
6165 binary encoded and only used for opaque signatures. For details on
6166 the file descriptor, see the description of ‘INPUT’ in the
6169 The verification is then started using:
6171 -- Command: VERIFY --protocol=NAME [--silent]
6172 NAME is the signing protocol used for the message. For a
6173 description of the allowed protocols see the ‘ENCRYPT’ command.
6174 This argument is mandatory. Depending on the combination of
6175 ‘MESSAGE’ ‘INPUT’ and ‘OUTPUT’ commands, the server needs to select
6176 the appropriate verification mode:
6179 This indicates a detached signature. Output data is not
6182 This indicates an opaque signature. As no output command has
6183 been given, the server is only required to check the
6186 This indicates an opaque signature. The server shall write
6187 the signed data to the file descriptor set by the output
6188 command. This data shall even be written if the signatures
6191 With ‘--silent’ the server shall not display any dialog; this is for
6192 example used by the client to get the content of opaque signed messages.
6193 The client expects the server to send at least this status information
6194 before the final OK response:
6196 -- Status line: SIGSTATUS FLAG DISPLAYSTRING
6197 Returns the status for the signature and a short string explaining
6198 the status. Valid values for FLAG are:
6201 The message has a signature but it could not not be verified
6202 due to a missing key.
6204 The signature is fully valid.
6206 The signature is valid but additional information was shown
6207 regarding the validity of the key.
6209 The signature is not valid.
6211 DISPLAYSTRING is a percent-and-plus-encoded string with a short
6212 human readable description of the status. For example
6214 S SIGSTATUS green Good+signature+from+Keith+Moon+<keith@example.net>
6216 Note that this string needs to fit into an Assuan line and should
6217 be short enough to be displayed as short one-liner on the clients
6218 window. As usual the encoding of this string is UTF-8 and it
6219 should be send in its translated form.
6221 The server shall send one status line for every signature found on
6225 File: gpgme.info, Node: UI Server Set Input Files, Next: UI Server Sign/Encrypt Files, Prev: UI Server Verify, Up: UI Server Protocol
6227 A.5 UI Server: Specifying the input files to operate on.
6228 ========================================================
6230 All file related UI server commands operate on a number of input files
6231 or directories, specified by one or more ‘FILE’ commands:
6233 -- Command: FILE [--clear] NAME
6234 Add the file or directory NAME to the list of pathnames to be
6235 processed by the server. The parameter NAME must be an absolute
6236 path name (including the drive letter) and is percent espaced (in
6237 particular, the characters %, = and white space characters are
6238 always escaped). If the option ‘--clear’ is given, the list of
6239 files is cleared before adding NAME.
6241 Historical note: The original spec did not define ‘--clear’ but the
6242 keyword ‘--continued’ after the file name to indicate that more
6243 files are to be expected. However, this has never been used and
6244 thus removed from the specs.
6247 File: gpgme.info, Node: UI Server Sign/Encrypt Files, Next: UI Server Verify/Decrypt Files, Prev: UI Server Set Input Files, Up: UI Server Protocol
6249 A.6 UI Server: Encrypting and signing files.
6250 ============================================
6252 First, the input files need to be specified by one or more ‘FILE’
6253 commands. Afterwards, the actual operation is requested:
6255 -- Command: ENCRYPT_FILES --nohup
6256 -- Command: SIGN_FILES --nohup
6257 -- Command: ENCRYPT_SIGN_FILES --nohup
6258 Request that the files specified by ‘FILE’ are encrypted and/or
6259 signed. The command selects the default action. The UI server may
6260 allow the user to change this default afterwards interactively, and
6261 even abort the operation or complete it only on some of the
6262 selected files and directories.
6264 What it means to encrypt or sign a file or directory is specific to
6265 the preferences of the user, the functionality the UI server
6266 provides, and the selected protocol. Typically, for each input
6267 file a new file is created under the original filename plus a
6268 protocol specific extension (like ‘.gpg’ or ‘.sig’), which contain
6269 the encrypted/signed file or a detached signature. For
6270 directories, the server may offer multiple options to the user (for
6271 example ignore or process recursively).
6273 The ‘ENCRYPT_SIGN_FILES’ command requests a combined sign and
6274 encrypt operation. It may not be available for all protocols (for
6275 example, it is available for OpenPGP but not for CMS).
6277 The option ‘--nohup’ is mandatory. It is currently unspecified
6278 what should happen if ‘--nohup’ is not present. Because ‘--nohup’
6279 is present, the server always returns ‘OK’ promptly, and completes
6280 the operation asynchronously.
6283 File: gpgme.info, Node: UI Server Verify/Decrypt Files, Next: UI Server Import/Export Keys, Prev: UI Server Sign/Encrypt Files, Up: UI Server Protocol
6285 A.7 UI Server: Decrypting and verifying files.
6286 ==============================================
6288 First, the input files need to be specified by one or more ‘FILE’
6289 commands. Afterwards, the actual operation is requested:
6291 -- Command: DECRYPT_FILES --nohup
6292 -- Command: VERIFY_FILES --nohup
6293 -- Command: DECRYPT_VERIFY_FILES --nohup
6294 Request that the files specified by ‘FILE’ are decrypted and/or
6295 verified. The command selects the default action. The UI server
6296 may allow the user to change this default afterwards interactively,
6297 and even abort the operation or complete it only on some of the
6298 selected files and directories.
6300 What it means to decrypt or verify a file or directory is specific
6301 to the preferences of the user, the functionality the UI server
6302 provides, and the selected protocol. Typically, for decryption, a
6303 new file is created for each input file under the original filename
6304 minus a protocol specific extension (like ‘.gpg’) which contains
6305 the original plaintext. For verification a status is displayed for
6306 each signed input file, indicating if it is signed, and if yes, if
6307 the signature is valid. For files that are signed and encrypted,
6308 the ‘VERIFY’ command transiently decrypts the file to verify the
6309 enclosed signature. For directories, the server may offer multiple
6310 options to the user (for example ignore or process recursively).
6312 The option ‘--nohup’ is mandatory. It is currently unspecified
6313 what should happen if ‘--nohup’ is not present. Because ‘--nohup’
6314 is present, the server always returns ‘OK’ promptly, and completes
6315 the operation asynchronously.
6318 File: gpgme.info, Node: UI Server Import/Export Keys, Next: UI Server Checksum Files, Prev: UI Server Verify/Decrypt Files, Up: UI Server Protocol
6320 A.8 UI Server: Managing certificates.
6321 =====================================
6323 First, the input files need to be specified by one or more ‘FILE’
6324 commands. Afterwards, the actual operation is requested:
6326 -- Command: IMPORT_FILES --nohup
6327 Request that the certificates contained in the files specified by
6328 ‘FILE’ are imported into the local certificate databases.
6330 For directories, the server may offer multiple options to the user
6331 (for example ignore or process recursively).
6333 The option ‘--nohup’ is mandatory. It is currently unspecified
6334 what should happen if ‘--nohup’ is not present. Because ‘--nohup’
6335 is present, the server always returns ‘OK’ promptly, and completes
6336 the operation asynchronously.
6338 FIXME: It may be nice to support an ‘EXPORT’ command as well, which
6339 is enabled by the context menu of the background of a directory.
6342 File: gpgme.info, Node: UI Server Checksum Files, Next: Miscellaneous UI Server Commands, Prev: UI Server Import/Export Keys, Up: UI Server Protocol
6344 A.9 UI Server: Create and verify checksums for files.
6345 =====================================================
6347 First, the input files need to be specified by one or more ‘FILE’
6348 commands. Afterwards, the actual operation is requested:
6350 -- Command: CHECKSUM_CREATE_FILES --nohup
6351 Request that checksums are created for the files specifed by
6352 ‘FILE’. The choice of checksum algorithm and the destination
6353 storage and format for the created checksums depend on the
6354 preferences of the user and the functionality provided by the UI
6355 server. For directories, the server may offer multiple options to
6356 the user (for example ignore or process recursively).
6358 The option ‘--nohup’ is mandatory. It is currently unspecified
6359 what should happen if ‘--nohup’ is not present. Because ‘--nohup’
6360 is present, the server always returns ‘OK’ promptly, and completes
6361 the operation asynchronously.
6363 -- Command: CHECKSUM_VERIFY_FILES --nohup
6364 Request that checksums are created for the files specifed by ‘FILE’
6365 and verified against previously created and stored checksums. The
6366 choice of checksum algorithm and the source storage and format for
6367 previously created checksums depend on the preferences of the user
6368 and the functionality provided by the UI server. For directories,
6369 the server may offer multiple options to the user (for example
6370 ignore or process recursively).
6372 If the source storage of previously created checksums is available
6373 to the user through the Windows shell, this command may also accept
6374 such checksum files as ‘FILE’ arguments. In this case, the UI
6375 server should instead verify the checksum of the referenced files
6376 as if they were given as INPUT files.
6378 The option ‘--nohup’ is mandatory. It is currently unspecified
6379 what should happen if ‘--nohup’ is not present. Because ‘--nohup’
6380 is present, the server always returns ‘OK’ promptly, and completes
6381 the operation asynchronously.
6384 File: gpgme.info, Node: Miscellaneous UI Server Commands, Prev: UI Server Checksum Files, Up: UI Server Protocol
6386 A.10 Miscellaneous UI Server Commands
6387 =====================================
6389 The server needs to implement the following commands which are not
6390 related to a specific command:
6392 -- Command: GETINFO WHAT
6393 This is a multi purpose command, commonly used to return a variety
6394 of information. The required subcommands as described by the WHAT
6398 Return the process id of the server in decimal notation using
6399 an Assuan data line.
6401 To allow the server to pop up the windows in the correct relation to the
6402 client, the client is advised to tell the server by sending the option:
6404 -- Command option: window-id NUMBER
6405 The NUMBER represents the native window ID of the clients current
6406 window. On Windows systems this is a windows handle (‘HWND’) and
6407 on X11 systems it is the ‘X Window ID’. The number needs to be
6408 given as a hexadecimal value so that it is easier to convey pointer
6409 values (e.g. ‘HWND’).
6411 A client may want to fire up the certificate manager of the server. To
6412 do this it uses the Assuan command:
6414 -- Command: START_KEYMANAGER
6415 The server shall pop up the main window of the key manager (aka
6416 certificate manager). The client expects that the key manager is
6417 brought into the foregound and that this command immediatley
6418 returns (does not wait until the key manager has been fully brought
6421 A client may want to fire up the configuration dialog of the server. To
6422 do this it uses the Assuan command:
6424 -- Command: START_CONFDIALOG
6425 The server shall pop up its configuration dialog. The client
6426 expects that this dialog is brought into the foregound and that
6427 this command immediatley returns (i.e. it does not wait until the
6428 dialog has been fully brought up).
6430 When doing an operation on a mail, it is useful to let the server know
6431 the address of the sender:
6433 -- Command: SENDER [--info] [--protocol=NAME] EMAIL
6434 EMAIL is the plain ASCII encoded address ("addr-spec" as per
6435 RFC-2822) enclosed in angle brackets. The address set with this
6436 command is valid until a successful completion of the operation or
6437 until a ‘RESET’ command. A second command overrides the effect of
6438 the first one; if EMAIL is not given and ‘--info’ is not used, the
6439 server shall use the default signing key.
6441 If option ‘--info’ is not given, the server shall also suggest a
6442 protocol to use for signing. The client may use this suggested
6443 protocol on its own discretion. The same status line as with
6444 PREP_ENCRYPT is used for this.
6446 The option ‘--protocol’ may be used to give the server a hint on
6447 which signing protocol should be preferred.
6449 To allow the UI-server to visually identify a running operation or to
6450 associate operations the server MAY support the command:
6452 -- Command: SESSION NUMBER [STRING]
6453 The NUMBER is an arbitrary value, a server may use to associate
6454 simultaneous running sessions. It is a 32 bit unsigned integer
6455 with ‘0’ as a special value indicating that no session association
6458 If STRING is given, the server may use this as the title of a
6459 window or, in the case of an email operation, to extract the
6460 sender’s address. The string may contain spaces; thus no
6461 plus-escaping is used.
6463 This command may be used at any time and overrides the effect of
6464 the last command. A ‘RESET’ undoes the effect of this command.
6467 File: gpgme.info, Node: Debugging, Next: Deprecated Functions, Prev: UI Server Protocol, Up: Top
6469 Appendix B How to solve problems
6470 ********************************
6472 Everyone knows that software often does not do what it should do and
6473 thus there is a need to track down problems. This is in particular true
6474 for applications using a complex library like GPGME and of course also
6475 for the library itself. Here we give a few hints on how to solve such
6478 First of all you should make sure that the keys you want to use are
6479 installed in the GnuPG engine and are usable. Thus the first test is to
6480 run the desired operation using ‘gpg’ or ‘gpgsm’ on the command line.
6481 If you can’t figure out why things don’t work, you may use GPGME’s built
6482 in trace feature. This feature is either enabled using the environment
6483 variable ‘GPGME_DEBUG’ or, if this is not possible, by calling the
6484 function ‘gpgme_set_global_flag’. The value is the trace level and an
6485 optional file name. If no file name is given the trace output is
6486 printed to ‘stderr’.
6489 GPGME_DEBUG=9:/home/user/mygpgme.log
6490 (Note that under Windows you use a semicolon in place of the colon to
6491 separate the fields.)
6493 A trace level of 9 is pretty verbose and thus you may want to start
6494 off with a lower level. The exact definition of the trace levels and
6495 the output format may change with any release; you need to check the
6496 source code for details. In any case the trace log should be helpful to
6497 understand what is going going on. Warning: The trace log may reveal
6498 sensitive details like passphrases or other data you use in your
6499 application. If you are asked to send a log file, make sure that you
6500 run your tests only with play data.
6503 File: gpgme.info, Node: Deprecated Functions, Next: Library Copying, Prev: Debugging, Up: Top
6505 Appendix C Deprecated Functions
6506 *******************************
6508 For backward compatibility GPGME has a number of functions, data types
6509 and constants which are deprecated and should not be used anymore. We
6510 document here those which are really old to help understanding old code
6511 and to allow migration to their modern counterparts.
6513 *Warning:* These interfaces will be removed in a future version of
6516 -- Function: void gpgme_key_release (gpgme_key_t KEY)
6517 The function ‘gpgme_key_release’ is equivalent to
6520 -- Function: void gpgme_trust_item_release (gpgme_trust_item_t ITEM)
6521 The function ‘gpgme_trust_item_release’ is an alias for
6522 ‘gpgme_trust_item_unref’.
6524 -- Function: gpgme_error_t gpgme_op_import_ext (gpgme_ctx_t CTX,
6525 gpgme_data_t KEYDATA, int *NR)
6526 The function ‘gpgme_op_import_ext’ is equivalent to:
6528 gpgme_error_t err = gpgme_op_import (ctx, keydata);
6531 gpgme_import_result_t result = gpgme_op_import_result (ctx);
6532 *nr = result->considered;
6535 -- Data type: gpgme_error_t (*gpgme_edit_cb_t) (void *HANDLE,
6536 gpgme_status_code_t STATUS, const char *ARGS, int FD)
6537 The ‘gpgme_edit_cb_t’ type is the type of functions which GPGME
6538 calls if it a key edit operation is on-going. The status code
6539 STATUS and the argument line ARGS are passed through by GPGME from
6540 the crypto engine. The file descriptor FD is -1 for normal status
6541 messages. If STATUS indicates a command rather than a status
6542 message, the response to the command should be written to FD. The
6543 HANDLE is provided by the user at start of operation.
6545 The function should return ‘GPG_ERR_FALSE’ if it did not handle the
6546 status code, ‘0’ for success, or any other error value.
6548 -- Function: gpgme_error_t gpgme_op_edit (gpgme_ctx_t CTX,
6549 gpgme_key_t KEY, gpgme_edit_cb_t FNC, void *HANDLE,
6551 Note: This function is deprecated, please use ‘gpgme_op_interact’
6554 The function ‘gpgme_op_edit’ processes the key KEY interactively,
6555 using the edit callback function FNC with the handle HANDLE. The
6556 callback is invoked for every status and command request from the
6557 crypto engine. The output of the crypto engine is written to the
6560 Note that the protocol between the callback function and the crypto
6561 engine is specific to the crypto engine and no further support in
6562 implementing this protocol correctly is provided by GPGME.
6564 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the edit
6565 operation completes successfully, ‘GPG_ERR_INV_VALUE’ if CTX or KEY
6566 is not a valid pointer, and any error returned by the crypto engine
6567 or the edit callback handler.
6569 -- Function: gpgme_error_t gpgme_op_edit_start (gpgme_ctx_t CTX,
6570 gpgme_key_t KEY, gpgme_edit_cb_t FNC, void *HANDLE,
6572 Note: This function is deprecated, please use
6573 ‘gpgme_op_interact_start’ instead.
6575 The function ‘gpgme_op_edit_start’ initiates a ‘gpgme_op_edit’
6576 operation. It can be completed by calling ‘gpgme_wait’ on the
6577 context. *Note Waiting For Completion::.
6579 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
6580 operation was started successfully, and ‘GPG_ERR_INV_VALUE’ if CTX
6581 or KEY is not a valid pointer.
6583 -- Function: gpgme_error_t gpgme_op_card_edit (gpgme_ctx_t CTX,
6584 gpgme_key_t KEY, gpgme_edit_cb_t FNC, void *HANDLE,
6586 Note: This function is deprecated, please use ‘gpgme_op_interact’
6587 with the flag ‘GPGME_INTERACT_CARD’ instead.
6589 The function ‘gpgme_op_card_edit’ is analogous to ‘gpgme_op_edit’,
6590 but should be used to process the smart card corresponding to the
6593 -- Function: gpgme_error_t gpgme_op_card_edit_start (gpgme_ctx_t CTX,
6594 gpgme_key_t KEY, gpgme_edit_cb_t FNC, void *HANDLE,
6596 Note: This function is deprecated, please use
6597 ‘gpgme_op_interact_start’ with the flag ‘GPGME_INTERACT_CARD’
6600 The function ‘gpgme_op_card_edit_start’ initiates a
6601 ‘gpgme_op_card_edit’ operation. It can be completed by calling
6602 ‘gpgme_wait’ on the context. *Note Waiting For Completion::.
6604 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
6605 operation was started successfully, and ‘GPG_ERR_INV_VALUE’ if CTX
6606 or KEY is not a valid pointer.
6608 -- Function: gpgme_error_t gpgme_data_new_with_read_cb
6609 (gpgme_data_t *DH, int (*READFUNC) (void *HOOK, char *BUFFER,
6610 size_t COUNT, size_t *NREAD), void *HOOK_VALUE)
6611 The function ‘gpgme_data_new_with_read_cb’ creates a new
6612 ‘gpgme_data_t’ object and uses the callback function READFUNC to
6613 retrieve the data on demand. As the callback function can supply
6614 the data in any way it wants, this is the most flexible data type
6615 GPGME provides. However, it can not be used to write data.
6617 The callback function receives HOOK_VALUE as its first argument
6618 whenever it is invoked. It should return up to COUNT bytes in
6619 BUFFER, and return the number of bytes actually read in NREAD. It
6620 may return ‘0’ in NREAD if no data is currently available. To
6621 indicate ‘EOF’ the function should return with an error code of
6622 ‘-1’ and set NREAD to ‘0’. The callback function may support to
6623 reset its internal read pointer if it is invoked with BUFFER and
6624 NREAD being ‘NULL’ and COUNT being ‘0’.
6626 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data
6627 object was successfully created, ‘GPG_ERR_INV_VALUE’ if DH or
6628 READFUNC is not a valid pointer, and ‘GPG_ERR_ENOMEM’ if not enough
6629 memory is available.
6631 -- Function: gpgme_error_t gpgme_data_rewind (gpgme_data_t DH)
6632 The function ‘gpgme_data_rewind’ is equivalent to:
6634 return (gpgme_data_seek (dh, 0, SEEK_SET) == -1)
6635 ? gpgme_error_from_errno (errno) : 0;
6637 -- Data type: gpgme_attr_t
6638 The ‘gpgme_attr_t’ type is used to specify a key or trust item
6639 attribute. The following attributes are defined:
6642 This is the key ID of a sub key. It is representable as a
6645 For trust items, the trust item refers to the key with this
6649 This is the fingerprint of a sub key. It is representable as
6653 This is the crypto algorithm for which the sub key can be
6654 used. It is representable as a string and as a number. The
6655 numbers correspond to the ‘enum gcry_pk_algos’ values in the
6659 This is the key length of a sub key. It is representable as a
6662 ‘GPGME_ATTR_CREATED’
6663 This is the timestamp at creation time of a sub key. It is
6664 representable as a number.
6667 This is the expiration time of a sub key. It is representable
6671 XXX FIXME (also for trust items)
6674 This is a user ID. There can be more than one user IDs in a
6675 GPGME_KEY_T object. The first one (with index 0) is the
6676 primary user ID. The user ID is representable as a number.
6678 For trust items, this is the user ID associated with this
6682 This is the name belonging to a user ID. It is representable
6686 This is the email address belonging to a user ID. It is
6687 representable as a string.
6689 ‘GPGME_ATTR_COMMENT’
6690 This is the comment belonging to a user ID. It is
6691 representable as a string.
6693 ‘GPGME_ATTR_VALIDITY’
6694 This is the validity belonging to a user ID. It is
6695 representable as a string and as a number. See below for a
6696 list of available validities.
6698 For trust items, this is the validity that is associated with
6701 ‘GPGME_ATTR_UID_REVOKED’
6702 This specifies if a user ID is revoked. It is representable
6703 as a number, and is ‘1’ if the user ID is revoked, and ‘0’
6706 ‘GPGME_ATTR_UID_INVALID’
6707 This specifies if a user ID is invalid. It is representable
6708 as a number, and is ‘1’ if the user ID is invalid, and ‘0’
6712 This is the trust level of a trust item.
6715 This returns information about the type of key. For the
6716 string function this will eother be "PGP" or "X.509". The
6717 integer function returns 0 for PGP and 1 for X.509. It is
6718 also used for the type of a trust item.
6720 ‘GPGME_ATTR_IS_SECRET’
6721 This specifies if the key is a secret key. It is
6722 representable as a number, and is ‘1’ if the key is revoked,
6725 ‘GPGME_ATTR_KEY_REVOKED’
6726 This specifies if a sub key is revoked. It is representable
6727 as a number, and is ‘1’ if the key is revoked, and ‘0’
6730 ‘GPGME_ATTR_KEY_INVALID’
6731 This specifies if a sub key is invalid. It is representable
6732 as a number, and is ‘1’ if the key is invalid, and ‘0’
6735 ‘GPGME_ATTR_KEY_EXPIRED’
6736 This specifies if a sub key is expired. It is representable
6737 as a number, and is ‘1’ if the key is expired, and ‘0’
6740 ‘GPGME_ATTR_KEY_DISABLED’
6741 This specifies if a sub key is disabled. It is representable
6742 as a number, and is ‘1’ if the key is disabled, and ‘0’
6745 ‘GPGME_ATTR_KEY_CAPS’
6746 This is a description of the capabilities of a sub key. It is
6747 representable as a string. The string contains the letter “e”
6748 if the key can be used for encryption, “s” if the key can be
6749 used for signatures, and “c” if the key can be used for
6752 ‘GPGME_ATTR_CAN_ENCRYPT’
6753 This specifies if a sub key can be used for encryption. It is
6754 representable as a number, and is ‘1’ if the sub key can be
6755 used for encryption, and ‘0’ otherwise.
6757 ‘GPGME_ATTR_CAN_SIGN’
6758 This specifies if a sub key can be used to create data
6759 signatures. It is representable as a number, and is ‘1’ if
6760 the sub key can be used for signatures, and ‘0’ otherwise.
6762 ‘GPGME_ATTR_CAN_CERTIFY’
6763 This specifies if a sub key can be used to create key
6764 certificates. It is representable as a number, and is ‘1’ if
6765 the sub key can be used for certifications, and ‘0’ otherwise.
6768 The X.509 issuer serial attribute of the key. It is
6769 representable as a string.
6772 The X.509 issuer name attribute of the key. It is
6773 representable as a string.
6775 ‘GPGME_ATTR_CHAINID’
6776 The X.509 chain ID can be used to build the certification
6777 chain. It is representable as a string.
6779 -- Function: const char * gpgme_key_get_string_attr (gpgme_key_t KEY,
6780 gpgme_attr_t WHAT, const void *RESERVED, int IDX)
6781 The function ‘gpgme_key_get_string_attr’ returns the value of the
6782 string-representable attribute WHAT of key KEY. If the attribute
6783 is an attribute of a sub key or an user ID, IDX specifies the sub
6784 key or user ID of which the attribute value is returned. The
6785 argument RESERVED is reserved for later use and should be ‘NULL’.
6787 The string returned is only valid as long as the key is valid.
6789 The function returns ‘0’ if an attribute can’t be returned as a
6790 string, KEY is not a valid pointer, IDX out of range, or RESERVED
6793 -- Function: unsigned long gpgme_key_get_ulong_attr (gpgme_key_t KEY,
6794 gpgme_attr_t WHAT, const void *RESERVED, int IDX)
6795 The function ‘gpgme_key_get_ulong_attr’ returns the value of the
6796 number-representable attribute WHAT of key KEY. If the attribute
6797 is an attribute of a sub key or an user ID, IDX specifies the sub
6798 key or user ID of which the attribute value is returned. The
6799 argument RESERVED is reserved for later use and should be ‘NULL’.
6801 The function returns ‘0’ if the attribute can’t be returned as a
6802 number, KEY is not a valid pointer, IDX out of range, or RESERVED
6805 The signatures on a key are only available if the key was retrieved
6806 via a listing operation with the ‘GPGME_KEYLIST_MODE_SIGS’ mode enabled,
6807 because it is expensive to retrieve all signatures of a key.
6809 So, before using the below interfaces to retrieve the signatures on a
6810 key, you have to make sure that the key was listed with signatures
6811 enabled. One convenient, but blocking, way to do this is to use the
6812 function ‘gpgme_get_key’.
6814 -- Data type: gpgme_attr_t
6815 The ‘gpgme_attr_t’ type is used to specify a key signature
6816 attribute. The following attributes are defined:
6819 This is the key ID of the key which was used for the
6820 signature. It is representable as a string.
6823 This is the crypto algorithm used to create the signature. It
6824 is representable as a string and as a number. The numbers
6825 correspond to the ‘enum gcry_pk_algos’ values in the gcrypt
6828 ‘GPGME_ATTR_CREATED’
6829 This is the timestamp at creation time of the signature. It
6830 is representable as a number.
6833 This is the expiration time of the signature. It is
6834 representable as a number.
6837 This is the user ID associated with the signing key. The user
6838 ID is representable as a number.
6841 This is the name belonging to a user ID. It is representable
6845 This is the email address belonging to a user ID. It is
6846 representable as a string.
6848 ‘GPGME_ATTR_COMMENT’
6849 This is the comment belonging to a user ID. It is
6850 representable as a string.
6852 ‘GPGME_ATTR_KEY_REVOKED’
6853 This specifies if a key signature is a revocation signature.
6854 It is representable as a number, and is ‘1’ if the key is
6855 revoked, and ‘0’ otherwise.
6857 ‘GPGME_ATTR_SIG_CLASS’
6858 This specifies the signature class of a key signature. It is
6859 representable as a number. The meaning is specific to the
6862 ‘GPGME_ATTR_SIG_CLASS’
6863 This specifies the signature class of a key signature. It is
6864 representable as a number. The meaning is specific to the
6867 ‘GPGME_ATTR_SIG_STATUS’
6868 This is the same value as returned by ‘gpgme_get_sig_status’.
6870 -- Function: const char * gpgme_key_sig_get_string_attr
6871 (gpgme_key_t KEY, int UID_IDX, gpgme_attr_t WHAT,
6872 const void *RESERVED, int IDX)
6873 The function ‘gpgme_key_sig_get_string_attr’ returns the value of
6874 the string-representable attribute WHAT of the signature IDX on the
6875 user ID UID_IDX in the key KEY. The argument RESERVED is reserved
6876 for later use and should be ‘NULL’.
6878 The string returned is only valid as long as the key is valid.
6880 The function returns ‘0’ if an attribute can’t be returned as a
6881 string, KEY is not a valid pointer, UID_IDX or IDX out of range, or
6882 RESERVED not ‘NULL’.
6884 -- Function: unsigned long gpgme_key_sig_get_ulong_attr
6885 (gpgme_key_t KEY, int UID_IDX, gpgme_attr_t WHAT,
6886 const void *RESERVED, int IDX)
6887 The function ‘gpgme_key_sig_get_ulong_attr’ returns the value of
6888 the number-representable attribute WHAT of the signature IDX on the
6889 user ID UID_IDX in the key KEY. The argument RESERVED is reserved
6890 for later use and should be ‘NULL’.
6892 The function returns ‘0’ if an attribute can’t be returned as a
6893 string, KEY is not a valid pointer, UID_IDX or IDX out of range, or
6894 RESERVED not ‘NULL’.
6896 Trust items have attributes which can be queried using the interfaces
6897 below. The attribute identifiers are shared with those for key
6898 attributes. *Note Information About Keys::.
6900 -- Function: const char * gpgme_trust_item_get_string_attr
6901 (gpgme_trust_item_t ITEM, gpgme_attr_t WHAT,
6902 const void *RESERVED, int IDX)
6903 The function ‘gpgme_trust_item_get_string_attr’ returns the value
6904 of the string-representable attribute WHAT of trust item ITEM. The
6905 arguments IDX and RESERVED are reserved for later use and should be
6906 ‘0’ and ‘NULL’ respectively.
6908 The string returned is only valid as long as the key is valid.
6910 The function returns ‘0’ if an attribute can’t be returned as a
6911 string, KEY is not a valid pointer, IDX out of range, or RESERVED
6914 -- Function: int gpgme_trust_item_get_int_attr
6915 (gpgme_trust_item_t ITEM, gpgme_attr_t WHAT,
6916 const void *RESERVED, int IDX)
6917 The function ‘gpgme_trust_item_get_int_attr’ returns the value of
6918 the number-representable attribute WHAT of trust item ITEM. If the
6919 attribute occurs more than once in the trust item, the index is
6920 specified by IDX. However, currently no such attribute exists, so
6921 IDX should be ‘0’. The argument RESERVED is reserved for later use
6922 and should be ‘NULL’.
6924 The function returns ‘0’ if the attribute can’t be returned as a
6925 number, KEY is not a valid pointer, IDX out of range, or RESERVED
6928 -- Data type: enum gpgme_sig_stat_t
6929 The ‘gpgme_sig_stat_t’ type holds the result of a signature check,
6930 or the combined result of all signatures. The following results
6933 ‘GPGME_SIG_STAT_NONE’
6934 This status should not occur in normal operation.
6936 ‘GPGME_SIG_STAT_GOOD’
6937 This status indicates that the signature is valid. For the
6938 combined result this status means that all signatures are
6941 ‘GPGME_SIG_STAT_GOOD_EXP’
6942 This status indicates that the signature is valid but expired.
6943 For the combined result this status means that all signatures
6944 are valid and expired.
6946 ‘GPGME_SIG_STAT_GOOD_EXPKEY’
6947 This status indicates that the signature is valid but the key
6948 used to verify the signature has expired. For the combined
6949 result this status means that all signatures are valid and all
6952 ‘GPGME_SIG_STAT_BAD’
6953 This status indicates that the signature is invalid. For the
6954 combined result this status means that all signatures are
6957 ‘GPGME_SIG_STAT_NOKEY’
6958 This status indicates that the signature could not be verified
6959 due to a missing key. For the combined result this status
6960 means that all signatures could not be checked due to missing
6963 ‘GPGME_SIG_STAT_NOSIG’
6964 This status indicates that the signature data provided was not
6967 ‘GPGME_SIG_STAT_ERROR’
6968 This status indicates that there was some other error which
6969 prevented the signature verification.
6971 ‘GPGME_SIG_STAT_DIFF’
6972 For the combined result this status means that at least two
6973 signatures have a different status. You can get each key’s
6974 status with ‘gpgme_get_sig_status’.
6976 -- Function: const char * gpgme_get_sig_status (gpgme_ctx_t CTX,
6977 int IDX, gpgme_sig_stat_t *R_STAT, time_t *R_CREATED)
6978 The function ‘gpgme_get_sig_status’ is equivalent to:
6980 gpgme_verify_result_t result;
6981 gpgme_signature_t sig;
6983 result = gpgme_op_verify_result (ctx);
6984 sig = result->signatures;
6996 switch (gpg_err_code (sig->status))
6998 case GPG_ERR_NO_ERROR:
6999 *r_stat = GPGME_SIG_STAT_GOOD;
7002 case GPG_ERR_BAD_SIGNATURE:
7003 *r_stat = GPGME_SIG_STAT_BAD;
7006 case GPG_ERR_NO_PUBKEY:
7007 *r_stat = GPGME_SIG_STAT_NOKEY;
7010 case GPG_ERR_NO_DATA:
7011 *r_stat = GPGME_SIG_STAT_NOSIG;
7014 case GPG_ERR_SIG_EXPIRED:
7015 *r_stat = GPGME_SIG_STAT_GOOD_EXP;
7018 case GPG_ERR_KEY_EXPIRED:
7019 *r_stat = GPGME_SIG_STAT_GOOD_EXPKEY;
7023 *r_stat = GPGME_SIG_STAT_ERROR;
7028 *r_created = sig->timestamp;
7031 -- Function: const char * gpgme_get_sig_string_attr (gpgme_ctx_t CTX,
7032 int IDX, gpgme_attr_t WHAT, int WHATIDX)
7033 The function ‘gpgme_get_sig_string_attr’ is equivalent to:
7035 gpgme_verify_result_t result;
7036 gpgme_signature_t sig;
7038 result = gpgme_op_verify_result (ctx);
7039 sig = result->signatures;
7051 case GPGME_ATTR_FPR:
7054 case GPGME_ATTR_ERRTOK:
7056 return sig->wrong_key_usage ? "Wrong_Key_Usage" : "";
7065 -- Function: const char * gpgme_get_sig_ulong_attr (gpgme_ctx_t CTX,
7066 int IDX, gpgme_attr_t WAHT, int WHATIDX)
7067 The function ‘gpgme_get_sig_ulong_attr’ is equivalent to:
7069 gpgme_verify_result_t result;
7070 gpgme_signature_t sig;
7072 result = gpgme_op_verify_result (ctx);
7073 sig = result->signatures;
7085 case GPGME_ATTR_CREATED:
7086 return sig->timestamp;
7088 case GPGME_ATTR_EXPIRE:
7089 return sig->exp_timestamp;
7091 case GPGME_ATTR_VALIDITY:
7092 return (unsigned long) sig->validity;
7094 case GPGME_ATTR_SIG_STATUS:
7095 switch (sig->status)
7097 case GPG_ERR_NO_ERROR:
7098 return GPGME_SIG_STAT_GOOD;
7100 case GPG_ERR_BAD_SIGNATURE:
7101 return GPGME_SIG_STAT_BAD;
7103 case GPG_ERR_NO_PUBKEY:
7104 return GPGME_SIG_STAT_NOKEY;
7106 case GPG_ERR_NO_DATA:
7107 return GPGME_SIG_STAT_NOSIG;
7109 case GPG_ERR_SIG_EXPIRED:
7110 return GPGME_SIG_STAT_GOOD_EXP;
7112 case GPG_ERR_KEY_EXPIRED:
7113 return GPGME_SIG_STAT_GOOD_EXPKEY;
7116 return GPGME_SIG_STAT_ERROR;
7119 case GPGME_ATTR_SIG_SUMMARY:
7120 return sig->summary;
7127 -- Function: const char * gpgme_get_sig_key (gpgme_ctx_t CTX, int IDX,
7129 The function ‘gpgme_get_sig_key’ is equivalent to:
7131 gpgme_verify_result_t result;
7132 gpgme_signature_t sig;
7134 result = gpgme_op_verify_result (ctx);
7135 sig = result->signatures;
7143 return gpg_error (GPG_ERR_EOF);
7145 return gpgme_get_key (ctx, sig->fpr, r_key, 0);
projects / platform / upstream / gpgme.git / blob