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.8.0-beta50, last updated 16 November 2016, of ‘The
23 ‘GnuPG Made Easy’ Reference Manual’, for Version 1.8.0-beta50.
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.8.0-beta50, last updated 16 November 2016, of ‘The
45 ‘GnuPG Made Easy’ Reference Manual’, for Version 1.8.0-beta50 of the
50 * Introduction:: How to use this manual.
51 * Preparation:: What you should do before using the library.
52 * Protocols and Engines:: Supported crypto protocols.
53 * Algorithms:: Supported algorithms.
54 * Error Handling:: Error numbers and their meanings.
55 * Exchanging Data:: Passing data to and from GPGME.
56 * Contexts:: Handling GPGME contexts.
60 * UI Server Protocol:: The GnuPG UI Server Protocol.
61 * Debugging:: How to solve problems.
62 * Deprecated Functions:: Documentation of deprecated functions.
64 * Library Copying:: The GNU Lesser General Public License says
65 how you can copy and share ‘GnuPG Made Easy’.
66 * Copying:: The GNU General Public License says how you
67 can copy and share this manual.
71 * Concept Index:: Index of concepts and programs.
72 * Function and Data Index:: Index of functions, variables and data types.
74 — The Detailed Node Listing —
78 * Getting Started:: Purpose of the manual, and how to use it.
79 * Features:: Reasons to install and use GPGME.
80 * Overview:: Basic architecture of the GPGME library.
84 * Header:: What header file you need to include.
85 * Building the Source:: Compiler options to be used.
86 * Largefile Support (LFS):: How to use GPGME with LFS.
87 * Using Automake:: Compiler options to be used the easy way.
88 * Using Libtool:: Avoiding compiler options entirely.
89 * Library Version Check:: Getting and verifying the library version.
90 * Signal Handling:: How GPGME affects signal handling.
91 * Multi-Threading:: How GPGME can be used in an MT environment.
95 * Engine Version Check:: Verifying the engine version.
96 * Engine Information:: Obtaining more information about the engines.
97 * Engine Configuration:: Changing the engine configuration.
98 * OpenPGP:: Support for the OpenPGP protocol.
99 * Cryptographic Message Syntax:: Support for the CMS.
103 * Public Key Algorithms:: A list of all public key algorithms.
104 * Hash Algorithms:: A list of all hash algorithms.
108 * Error Values:: The error value and what it means.
109 * Error Codes:: A list of important error codes.
110 * Error Sources:: A list of important error sources.
111 * Error Strings:: How to get a descriptive string from a value.
115 * Creating Data Buffers:: Creating new data buffers.
116 * Destroying Data Buffers:: Releasing data buffers.
117 * Manipulating Data Buffers:: Operations on data buffers.
119 Creating Data Buffers
121 * Memory Based Data Buffers:: Creating memory based data buffers.
122 * File Based Data Buffers:: Creating file based data buffers.
123 * Callback Based Data Buffers:: Creating callback based data buffers.
125 Manipulating Data Buffers
127 * Data Buffer I/O Operations:: I/O operations on data buffers.
128 * Data Buffer Meta-Data:: Meta-data manipulation of data buffers.
129 * Data Buffer Convenience:: Convenience function for data buffers.
133 * Creating Contexts:: Creating new GPGME contexts.
134 * Destroying Contexts:: Releasing GPGME contexts.
135 * Result Management:: Managing the result of crypto operations.
136 * Context Attributes:: Setting properties of a context.
137 * Key Management:: Managing keys with GPGME.
138 * Trust Item Management:: Managing trust items with GPGME.
139 * Crypto Operations:: Using a context for cryptography.
140 * Miscellaneous:: Miscellaneous operations.
141 * Run Control:: Controlling how operations are run.
145 * Protocol Selection:: Selecting the protocol used by a context.
146 * Crypto Engine:: Configuring the crypto engine.
147 * Setting the Sender:: How to tell the engine the sender.
148 * ASCII Armor:: Requesting ASCII armored output.
149 * Text Mode:: Choosing canonical text mode.
150 * Offline Mode:: Choosing offline mode.
151 * Included Certificates:: Including a number of certificates.
152 * Key Listing Mode:: Selecting key listing mode.
153 * Passphrase Callback:: Getting the passphrase from the user.
154 * Progress Meter Callback:: Being informed about the progress.
155 * Status Message Callback:: Status messages received from gpg.
156 * Locale:: Setting the locale of a context.
160 * Key objects:: Description of the key structures.
161 * Listing Keys:: Browsing the list of available keys.
162 * Information About Keys:: Requesting detailed information about keys.
163 * Manipulating Keys:: Operations on keys.
164 * Generating Keys:: Creating new key pairs.
165 * Signing Keys:: Adding key signatures to public keys.
166 * Exporting Keys:: Retrieving key data from the key ring.
167 * Importing Keys:: Adding keys to the key ring.
168 * Deleting Keys:: Removing keys from the key ring.
169 * Changing Passphrases:: Change the passphrase of a key.
170 * Changing TOFU Data:: Changing data pertaining to TOFU.
171 * Advanced Key Editing:: Advanced key edit operation.
173 Trust Item Management
175 * Listing Trust Items:: Browsing the list of available trust items.
176 * Manipulating Trust Items:: Operations on trust items.
180 * Decrypt:: Decrypting a ciphertext.
181 * Verify:: Verifying a signature.
182 * Decrypt and Verify:: Decrypting a signed ciphertext.
183 * Sign:: Creating a signature.
184 * Encrypt:: Encrypting a plaintext.
188 * Selecting Signers:: How to choose the keys to sign with.
189 * Creating a Signature:: How to create a signature.
190 * Signature Notation Data:: How to add notation data to a signature.
194 * Encrypting a Plaintext:: How to encrypt a plaintext.
198 * Running other Programs:: Running other Programs.
199 * Using the Assuan protocol:: Using the Assuan protocol.
200 * Checking for updates:: How to check for software updates.
204 * Waiting For Completion:: Waiting until an operation is completed.
205 * Using External Event Loops:: Advanced control over what happens when.
206 * Cancellation:: How to end pending operations prematurely.
208 Using External Event Loops
210 * I/O Callback Interface:: How I/O callbacks are registered.
211 * Registering I/O Callbacks:: How to use I/O callbacks for a context.
212 * I/O Callback Example:: An example how to use I/O callbacks.
213 * I/O Callback Example GTK+:: How to integrate GPGME in GTK+.
214 * I/O Callback Example GDK:: How to integrate GPGME in GDK.
215 * I/O Callback Example Qt:: How to integrate GPGME in Qt.
219 File: gpgme.info, Node: Introduction, Next: Preparation, Prev: Top, Up: Top
224 ‘GnuPG Made Easy’ (GPGME) is a C language library that allows to add
225 support for cryptography to a program. It is designed to make access to
226 public key crypto engines like GnuPG or GpgSM easier for applications.
227 GPGME provides a high-level crypto API for encryption, decryption,
228 signing, signature verification and key management.
230 GPGME uses GnuPG and GpgSM as its backends to support OpenPGP and the
231 Cryptographic Message Syntax (CMS).
235 * Getting Started:: Purpose of the manual, and how to use it.
236 * Features:: Reasons to install and use GPGME.
237 * Overview:: Basic architecture of the GPGME library.
240 File: gpgme.info, Node: Getting Started, Next: Features, Up: Introduction
245 This manual documents the GPGME library programming interface. All
246 functions and data types provided by the library are explained.
248 The reader is assumed to possess basic knowledge about cryptography
249 in general, and public key cryptography in particular. The underlying
250 cryptographic engines that are used by the library are not explained,
251 but where necessary, special features or requirements by an engine are
252 mentioned as far as they are relevant to GPGME or its users.
254 This manual can be used in several ways. If read from the beginning
255 to the end, it gives a good introduction into the library and how it can
256 be used in an application. Forward references are included where
257 necessary. Later on, the manual can be used as a reference manual to
258 get just the information needed about any particular interface of the
259 library. Experienced programmers might want to start looking at the
260 examples at the end of the manual, and then only read up those parts of
261 the interface which are unclear.
263 The documentation for the language bindings is currently not included
264 in this manual. Those languages bindings follow the general programming
265 model of GPGME but may provide some extra high level abstraction on top
266 of the GPGME style API. For now please see the README files in the
267 ‘lang/’ directory of the source distribution.
270 File: gpgme.info, Node: Features, Next: Overview, Prev: Getting Started, Up: Introduction
275 GPGME has a couple of advantages over other libraries doing a similar
276 job, and over implementing support for GnuPG or other crypto engines
277 into your application directly.
280 Anybody can use, modify, and redistribute it under the terms of the
281 GNU Lesser General Public License (*note Library Copying::).
284 GPGME provides transparent support for several cryptographic
285 protocols by different engines. Currently, GPGME supports the
286 OpenPGP protocol using GnuPG as the backend, and the Cryptographic
287 Message Syntax using GpgSM as the backend.
290 GPGME hides the differences between the protocols and engines from
291 the programmer behind an easy-to-use interface. This way the
292 programmer can focus on the other parts of the program, and still
293 integrate strong cryptography in his application. Once support for
294 GPGME has been added to a program, it is easy to add support for
295 other crypto protocols once GPGME backends provide them.
297 it’s language friendly
298 GPGME comes with languages bindings for several common programming
299 languages: Common Lisp, C++, Python 2, and Python 3.
302 File: gpgme.info, Node: Overview, Prev: Features, Up: Introduction
307 GPGME provides a data abstraction that is used to pass data to the
308 crypto engine, and receive returned data from it. Data can be read from
309 memory or from files, but it can also be provided by a callback
312 The actual cryptographic operations are always set within a context.
313 A context provides configuration parameters that define the behaviour of
314 all operations performed within it. Only one operation per context is
315 allowed at any time, but when one operation is finished, you can run the
316 next operation in the same context. There can be more than one context,
317 and all can run different operations at the same time.
319 Furthermore, GPGME has rich key management facilities including
320 listing keys, querying their attributes, generating, importing,
321 exporting and deleting keys, and acquiring information about the trust
324 With some precautions, GPGME can be used in a multi-threaded
325 environment, although it is not completely thread safe and thus needs
326 the support of the application.
329 File: gpgme.info, Node: Preparation, Next: Protocols and Engines, Prev: Introduction, Up: Top
334 To use GPGME, you have to perform some changes to your sources and the
335 build system. The necessary changes are small and explained in the
336 following sections. At the end of this chapter, it is described how the
337 library is initialized, and how the requirements of the library are
342 * Header:: What header file you need to include.
343 * Building the Source:: Compiler options to be used.
344 * Largefile Support (LFS):: How to use GPGME with LFS.
345 * Using Automake:: Compiler options to be used the easy way.
346 * Using Libtool:: Avoiding compiler options entirely.
347 * Library Version Check:: Getting and verifying the library version.
348 * Signal Handling:: How GPGME affects signal handling.
349 * Multi-Threading:: How GPGME can be used in an MT environment.
352 File: gpgme.info, Node: Header, Next: Building the Source, Up: Preparation
357 All interfaces (data types and functions) of the library are defined in
358 the header file ‘gpgme.h’. You must include this in all programs using
359 the library, either directly or through some other header file, like
364 The name space of GPGME is ‘gpgme_*’ for function names and data
365 types and ‘GPGME_*’ for other symbols. Symbols internal to GPGME take
366 the form ‘_gpgme_*’ and ‘_GPGME_*’.
368 Because GPGME makes use of the GPG Error library, using GPGME will
369 also use the ‘GPG_ERR_*’ name space directly, and the ‘gpg_err*’,
370 ‘gpg_str*’, and ‘gpgrt_*’ name space indirectly.
373 File: gpgme.info, Node: Building the Source, Next: Largefile Support (LFS), Prev: Header, Up: Preparation
375 2.2 Building the Source
376 =======================
378 If you want to compile a source file including the ‘gpgme.h’ header
379 file, you must make sure that the compiler can find it in the directory
380 hierarchy. This is accomplished by adding the path to the directory in
381 which the header file is located to the compilers include file search
382 path (via the ‘-I’ option).
384 However, the path to the include file is determined at the time the
385 source is configured. To solve this problem, gpgme ships with a small
386 helper program ‘gpgme-config’ that knows about the path to the include
387 file and other configuration options. The options that need to be added
388 to the compiler invocation at compile time are output by the ‘--cflags’
389 option to ‘gpgme-config’. The following example shows how it can be
390 used at the command line:
392 gcc -c foo.c `gpgme-config --cflags`
394 Adding the output of ‘gpgme-config --cflags’ to the compiler command
395 line will ensure that the compiler can find the GPGME header file.
397 A similar problem occurs when linking the program with the library.
398 Again, the compiler has to find the library files. For this to work,
399 the path to the library files has to be added to the library search path
400 (via the ‘-L’ option). For this, the option ‘--libs’ to ‘gpgme-config’
401 can be used. For convenience, this option also outputs all other
402 options that are required to link the program with GPGME (in particular,
403 the ‘-lgpgme’ option). The example shows how to link ‘foo.o’ with the
404 GPGME library to a program ‘foo’.
406 gcc -o foo foo.o `gpgme-config --libs`
408 Of course you can also combine both examples to a single command by
409 specifying both options to ‘gpgme-config’:
411 gcc -o foo foo.c `gpgme-config --cflags --libs`
413 If you need to detect the installed language bindings you can use
416 gpgme-config --print-lang
418 or test for the availability using
420 gpgme-config --have-lang=python && echo 'Bindings for Pythons available'
423 File: gpgme.info, Node: Largefile Support (LFS), Next: Using Automake, Prev: Building the Source, Up: Preparation
425 2.3 Largefile Support (LFS)
426 ===========================
428 GPGME is compiled with largefile support by default, if it is available
429 on the system. This means that GPGME supports files larger than two
430 gigabyte in size, if the underlying operating system can. On some
431 systems, largefile support is already the default. On such systems,
432 nothing special is required. However, some systems provide only support
433 for files up to two gigabyte in size by default. Support for larger
434 file sizes has to be specifically enabled.
436 To make a difficult situation even more complex, such systems provide
437 two different types of largefile support. You can either get all
438 relevant functions replaced with alternatives that are largefile
439 capable, or you can get new functions and data types for largefile
440 support added. Those new functions have the same name as their
441 smallfile counterparts, but with a suffix of 64.
443 An example: The data type ‘off_t’ is 32 bit wide on GNU/Linux PC
444 systems. To address offsets in large files, you can either enable
445 largefile support add-on. Then a new data type ‘off64_t’ is provided,
446 which is 64 bit wide. Or you can replace the existing ‘off_t’ data type
447 with its 64 bit wide counterpart. All occurences of ‘off_t’ are then
448 automagically replaced.
450 As if matters were not complex enough, there are also two different
451 types of file descriptors in such systems. This is important because if
452 file descriptors are exchanged between programs that use a different
453 maximum file size, certain errors must be produced on some file
454 descriptors to prevent subtle overflow bugs from occuring.
456 As you can see, supporting two different maximum file sizes at the
457 same time is not at all an easy task. However, the maximum file size
458 does matter for GPGME, because some data types it uses in its interfaces
459 are affected by that. For example, the ‘off_t’ data type is used in the
460 ‘gpgme_data_seek’ function, to match its POSIX counterpart. This
461 affects the call-frame of the function, and thus the ABI of the library.
462 Furthermore, file descriptors can be exchanged between GPGME and the
465 For you as the user of the library, this means that your program must
466 be compiled in the same file size mode as the library. Luckily, there
467 is absolutely no valid reason for new programs to not enable largefile
468 support by default and just use that. The compatibility modes (small
469 file sizes or dual mode) can be considered an historic artefact, only
470 useful to allow for a transitional period.
472 On POSIX platforms GPGME is compiled using largefile support by
473 default. This means that your application must do the same, at least as
474 far as it is relevant for using the ‘gpgme.h’ header file. All types in
475 this header files refer to their largefile counterparts, if they are
476 different from any default types on the system.
478 On 32 and 64 bit Windows platforms ‘off_t’ is declared as 32 bit
479 signed integer. There is no specific support for LFS in the C library.
480 The recommendation from Microsoft is to use the native interface
481 (‘CreateFile’ et al.) for large files. Released binary versions of
482 GPGME (libgpgme-11.dll) have always been build with a 32 bit ‘off_t’.
483 To avoid an ABI break we stick to this convention for 32 bit Windows by
484 using ‘long’ there. GPGME versions for 64 bit Windows have never been
485 released and thus we are able to use ‘int64_t’ instead of ‘off_t’ there.
486 For easier migration the typedef ‘gpgme_off_t’ has been defined. The
487 reason we cannot use ‘off_t’ directly is that some toolchains (e.g.
488 mingw64) introduce a POSIX compatible hack for ‘off_t’. Some widely
489 used toolkits make use of this hack and in turn GPGME would need to use
490 it also. However, this would introduce an ABI break and existing
491 software making use of libgpgme might suffer from a severe break. Thus
492 with version 1.4.2 we redefined all functions using ‘off_t’ to use
493 ‘gpgme_off_t’ which is defined as explained above. This way we keep the
494 ABI well defined and independent of any toolchain hacks. The bottom
495 line is that LFS support in GPGME is only available on 64 bit versions
498 On POSIX platforms you can enable largefile support, if it is
499 different from the default on the system the application is compiled on,
500 by using the Autoconf macro ‘AC_SYS_LARGEFILE’. If you do this, then
501 you don’t need to worry about anything else: It will just work. In this
502 case you might also want to use ‘AC_FUNC_FSEEKO’ to take advantage of
503 some new interfaces, and ‘AC_TYPE_OFF_T’ (just in case).
505 If you do not use Autoconf, you can define the preprocessor symbol
506 ‘_FILE_OFFSET_BITS’ to 64 _before_ including any header files, for
507 example by specifying the option ‘-D_FILE_OFFSET_BITS=64’ on the
508 compiler command line. You will also want to define the preprocessor
509 symbol ‘LARGEFILE_SOURCE’ to 1 in this case, to take advantage of some
512 If you do not want to do either of the above, you probably know
513 enough about the issue to invent your own solution. Just keep in mind
514 that the GPGME header file expects that largefile support is enabled, if
515 it is available. In particular, we do not support dual mode
516 (‘_LARGEFILE64_SOURCE’).
519 File: gpgme.info, Node: Using Automake, Next: Using Libtool, Prev: Largefile Support (LFS), Up: Preparation
524 It is much easier if you use GNU Automake instead of writing your own
525 Makefiles. If you do that you do not have to worry about finding and
526 invoking the ‘gpgme-config’ script at all. GPGME provides an extension
527 to Automake that does all the work for you.
529 -- Macro: AM_PATH_GPGME ([MINIMUM-VERSION], [ACTION-IF-FOUND],
530 [ACTION-IF-NOT-FOUND])
531 -- Macro: AM_PATH_GPGME_PTH ([MINIMUM-VERSION], [ACTION-IF-FOUND],
532 [ACTION-IF-NOT-FOUND])
533 -- Macro: AM_PATH_GPGME_PTHREAD ([MINIMUM-VERSION], [ACTION-IF-FOUND],
534 [ACTION-IF-NOT-FOUND])
535 Check whether GPGME (at least version MINIMUM-VERSION, if given)
536 exists on the host system. If it is found, execute
537 ACTION-IF-FOUND, otherwise do ACTION-IF-NOT-FOUND, if given.
539 Additionally, the function defines ‘GPGME_CFLAGS’ to the flags
540 needed for compilation of the program to find the ‘gpgme.h’ header
541 file, and ‘GPGME_LIBS’ to the linker flags needed to link the
542 program to the GPGME library. If the used helper script does not
543 match the target type you are building for a warning is printed and
544 the string ‘libgcrypt’ is appended to the variable
545 ‘gpg_config_script_warn’.
547 ‘AM_PATH_GPGME_PTH’ checks for the version of GPGME that can be
548 used with GNU Pth, and defines ‘GPGME_PTH_CFLAGS’ and
551 ‘AM_PATH_GPGME_PTHREAD’ checks for the version of GPGME that can be
552 used with the native pthread implementation, and defines
553 ‘GPGME_PTHREAD_CFLAGS’ and ‘GPGME_PTHREAD_LIBS’. Since version
554 1.8.0 this is no longer required to GPGME_PTHREAD as GPGME itself
557 This macro searches for ‘gpgme-config’ along the PATH. If you are
558 cross-compiling, it is useful to set the environment variable
559 ‘SYSROOT’ to the top directory of your target. The macro will then
560 first look for the helper program in the ‘bin’ directory below that
561 top directory. An absolute directory name must be used for
562 ‘SYSROOT’. Finally, if the configure command line option
563 ‘--with-gpgme-prefix’ is used, only its value is used for the top
564 directory below which the helper script is expected.
566 You can use the defined Autoconf variables like this in your
569 AM_CPPFLAGS = $(GPGME_CFLAGS)
570 LDADD = $(GPGME_LIBS)
573 File: gpgme.info, Node: Using Libtool, Next: Library Version Check, Prev: Using Automake, Up: Preparation
578 The easiest way is to just use GNU Libtool. If you use libtool, and
579 link to ‘libgpgme.la’, ‘libgpgme-pth.la’ or ‘libgpgme-pthread.la’
580 respectively, everything will be done automatically by Libtool.
583 File: gpgme.info, Node: Library Version Check, Next: Signal Handling, Prev: Using Libtool, Up: Preparation
585 2.6 Library Version Check
586 =========================
588 -- Function: const char * gpgme_check_version
589 (const char *REQUIRED_VERSION)
590 The function ‘gpgme_check_version’ has four purposes. It can be
591 used to retrieve the version number of the library. In addition it
592 can verify that the version number is higher than a certain
593 required version number. In either case, the function initializes
594 some sub-systems, and for this reason alone it must be invoked
595 early in your program, before you make use of the other functions
596 in GPGME. The last purpose is to run selftests.
598 As a side effect for W32 based systems, the socket layer will get
601 If REQUIRED_VERSION is ‘NULL’, the function returns a pointer to a
602 statically allocated string containing the version number of the
605 If REQUIRED_VERSION is not ‘NULL’, it should point to a string
606 containing a version number, and the function checks that the
607 version of the library is at least as high as the version number
608 provided. In this case, the function returns a pointer to a
609 statically allocated string containing the version number of the
610 library. If REQUIRED_VERSION is not a valid version number, or if
611 the version requirement is not met, the function returns ‘NULL’.
613 If you use a version of a library that is backwards compatible with
614 older releases, but contains additional interfaces which your
615 program uses, this function provides a run-time check if the
616 necessary features are provided by the installed version of the
619 If a selftest fails, the function may still succeed. Selftest
620 errors are returned later when invoking ‘gpgme_new’, so that a
621 detailed error code can be returned (historically,
622 ‘gpgme_check_version’ does not return a detailed error code).
624 -- Function: int gpgme_set_global_flag (const char *NAME,
627 On some systems it is not easy to set environment variables and
628 thus hard to use GPGME’s internal trace facility for debugging.
629 This function has been introduced as an alternative way to enable
630 debugging and for a couple of other rarely used tweaks. It is
631 important to assure that only one thread accesses GPGME functions
632 between a call to this function and after the return from the call
633 to ‘gpgme_check_version’.
635 All currently supported features require that this function is
636 called as early as possible — even before ‘gpgme_check_version’.
637 The features are identified by the following values for NAME:
640 To enable debugging use the string “debug” for NAME and VALUE
641 identical to the value used with the environment variable
645 Using this feature with any VALUE disables the detection of
646 the gpgconf program and thus forces GPGME to fallback into the
647 simple OpenPGP only mode. It may be used to force the use of
648 GnuPG-1 on systems which have both GPG versions installed.
649 Note that in general the use of ‘gpgme_set_engine_info’ is a
650 better way to select a specific engine version.
654 Set the name of the gpgconf respective gpg binary. The
655 defaults are ‘GNU/GnuPG/gpgconf’ and ‘GNU/GnuPG/gpg’. Under
656 Unix the leading directory part is ignored. Under Windows the
657 leading directory part is used as the default installation
658 directory; the ‘.exe’ suffix is added by GPGME. Use forward
659 slashed even under Windows.
662 Set the mimimum version of the required GnuPG engine. If that
663 version is not met, GPGME fails early instead of trying to use
664 the existant version. The given version must be a string with
665 major, minor, and micro number. Example: "2.1.0".
668 On Windows GPGME needs to know its installation directory to
669 find its spawn helper. This is in general no problem because
670 a DLL has this information. Some applications however link
671 statically to GPGME and thus GPGME can only figure out the
672 installation directory of this application which may be wrong
673 in certain cases. By supplying an installation directory as
674 value to this flag, GPGME will assume that that directory is
675 the installation directory. This flag has no effect on
676 non-Windows platforms.
678 This function returns ‘0’ on success. In contrast to other
679 functions the non-zero return value on failure does not convey any
680 error code. For setting “debug” the only possible error cause is
681 an out of memory condition; which would exhibit itself later
682 anyway. Thus the return value may be ignored.
684 After initializing GPGME, you should set the locale information to
685 the locale required for your output terminal. This locale information
686 is needed for example for the curses and Gtk pinentry. Here is an
687 example of a complete initialization:
695 /* Initialize the locale environment. */
696 setlocale (LC_ALL, "");
697 gpgme_check_version (NULL);
698 gpgme_set_locale (NULL, LC_CTYPE, setlocale (LC_CTYPE, NULL));
700 gpgme_set_locale (NULL, LC_MESSAGES, setlocale (LC_MESSAGES, NULL));
704 Note that you are highly recommended to initialize the locale
705 settings like this. GPGME can not do this for you because it would not
706 be thread safe. The conditional on LC_MESSAGES is only necessary for
707 portability to W32 systems.
710 File: gpgme.info, Node: Signal Handling, Next: Multi-Threading, Prev: Library Version Check, Up: Preparation
715 The GPGME library communicates with child processes (the crypto
716 engines). If a child process dies unexpectedly, for example due to a
717 bug, or system problem, a ‘SIGPIPE’ signal will be delivered to the
718 application. The default action is to abort the program. To protect
719 against this, ‘gpgme_check_version’ sets the ‘SIGPIPE’ signal action to
720 ‘SIG_IGN’, which means that the signal will be ignored.
722 GPGME will only do that if the signal action for ‘SIGPIPE’ is
723 ‘SIG_DEF’ at the time ‘gpgme_check_version’ is called. If it is
724 something different, ‘GPGME’ will take no action.
726 This means that if your application does not install any signal
727 handler for ‘SIGPIPE’, you don’t need to take any precautions. If you
728 do install a signal handler for ‘SIGPIPE’, you must be prepared to
729 handle any ‘SIGPIPE’ events that occur due to GPGME writing to a defunct
730 pipe. Furthermore, if your application is multi-threaded, and you
731 install a signal action for ‘SIGPIPE’, you must make sure you do this
732 either before ‘gpgme_check_version’ is called or afterwards.
735 File: gpgme.info, Node: Multi-Threading, Prev: Signal Handling, Up: Preparation
740 The GPGME library is mostly thread-safe, and can be used in a
741 multi-threaded environment but there are some requirements for
744 • The function ‘gpgme_check_version’ must be called before any other
745 function in the library, because it initializes the thread support
746 subsystem in GPGME. To achieve this in multi-threaded programs,
747 you must synchronize the memory with respect to other threads that
748 also want to use GPGME. For this, it is sufficient to call
749 ‘gpgme_check_version’ before creating the other threads using
752 • Any ‘gpgme_data_t’ and ‘gpgme_ctx_t’ object must only be accessed
753 by one thread at a time. If multiple threads want to deal with the
754 same object, the caller has to make sure that operations on that
755 object are fully synchronized.
757 • Only one thread at any time is allowed to call ‘gpgme_wait’. If
758 multiple threads call this function, the caller must make sure that
759 all invocations are fully synchronized. It is safe to start
760 asynchronous operations while a thread is running in gpgme_wait.
762 • The function ‘gpgme_strerror’ is not thread safe. You have to use
763 ‘gpgme_strerror_r’ instead.
765 ---------- Footnotes ----------
767 (1) At least this is true for POSIX threads, as ‘pthread_create’ is a
768 function that synchronizes memory with respects to other threads. There
769 are many functions which have this property, a complete list can be
770 found in POSIX, IEEE Std 1003.1-2003, Base Definitions, Issue 6, in the
771 definition of the term “Memory Synchronization”. For other thread
772 packages other, more relaxed or more strict rules may apply.
775 File: gpgme.info, Node: Protocols and Engines, Next: Algorithms, Prev: Preparation, Up: Top
777 3 Protocols and Engines
778 ***********************
780 GPGME supports several cryptographic protocols, however, it does not
781 implement them. Rather it uses backends (also called engines) which
782 implement the protocol. GPGME uses inter-process communication to pass
783 data back and forth between the application and the backend, but the
784 details of the communication protocol and invocation of the backend is
785 completely hidden by the interface. All complexity is handled by GPGME.
786 Where an exchange of information between the application and the backend
787 is necessary, GPGME provides the necessary callback function hooks and
790 -- Data type: enum gpgme_protocol_t
791 The ‘gpgme_protocol_t’ type specifies the set of possible protocol
792 values that are supported by GPGME. The following protocols are
795 ‘GPGME_PROTOCOL_OpenPGP’
796 This specifies the OpenPGP protocol.
799 This specifies the Cryptographic Message Syntax.
801 ‘GPGME_PROTOCOL_GPGCONF’
802 Under development. Please ask on <gnupg-devel@gnupg.org> for
805 ‘GPGME_PROTOCOL_ASSUAN’
806 This specifies the raw Assuan protocol.
809 Under development. Please ask on <gnupg-devel@gnupg.org> for
812 ‘GPGME_PROTOCOL_UISERVER’
813 Under development. Please ask on <gnupg-devel@gnupg.org> for
816 ‘GPGME_PROTOCOL_SPAWN’
817 Special protocol for use with ‘gpgme_op_spawn’.
819 ‘GPGME_PROTOCOL_UNKNOWN’
820 Reserved for future extension. You may use this to indicate
821 that the used protocol is not known to the application.
822 Currently, GPGME does not accept this value in any operation,
823 though, except for ‘gpgme_get_protocol_name’.
825 -- Function: const char * gpgme_get_protocol_name
826 (gpgme_protocol_t PROTOCOL)
827 The function ‘gpgme_get_protocol_name’ returns a statically
828 allocated string describing the protocol PROTOCOL, or ‘NULL’ if the
829 protocol number is not valid.
833 * Engine Version Check:: Verifying the engine version.
834 * Engine Information:: Obtaining more information about the engines.
835 * Engine Configuration:: Changing the engine configuration.
836 * OpenPGP:: Support for the OpenPGP protocol.
837 * Cryptographic Message Syntax:: Support for the CMS.
838 * Assuan:: Support for the raw Assuan protocol.
841 File: gpgme.info, Node: Engine Version Check, Next: Engine Information, Up: Protocols and Engines
843 3.1 Engine Version Check
844 ========================
846 -- Function: const char * gpgme_get_dirinfo (cons char *WHAT)
847 The function ‘gpgme_get_dirinfo’ returns a statically allocated
848 string with the value associated to WHAT. The returned values are
849 the defaults and won’t change even after ‘gpgme_set_engine_info’
850 has been used to configure a different engine. ‘NULL’ is returned
851 if no value is available. Commonly supported values for WHAT are:
854 Return the default home directory.
857 Return the name of the system configuration directory
860 Return the name of the directory with GnuPG program files.
863 Return the name of the directory with GnuPG related library
867 Return the name of the directory with GnuPG helper program
871 Return the name of the directory with GnuPG shared data.
874 Return the name of the directory with GnuPG locale data.
877 Return the name of the socket to connect to the gpg-agent.
880 Return the name of the socket to connect to the ssh-agent
881 component of gpg-agent.
884 Return the name of the socket to connect to the dirmngr.
887 Return the name of the socket to connect to the user interface
891 Return the file name of the engine configuration tool.
894 Return the file name of the OpenPGP engine.
897 Return the file name of the CMS engine.
900 Return the name of the file container encryption engine.
902 -- Function: gpgme_error_t gpgme_engine_check_version
903 (gpgme_protocol_t PROTOCOL)
904 The function ‘gpgme_engine_check_version’ verifies that the engine
905 implementing the protocol PROTOCOL is installed in the expected
906 path and meets the version requirement of GPGME.
908 This function returns the error code ‘GPG_ERR_NO_ERROR’ if the
909 engine is available and ‘GPG_ERR_INV_ENGINE’ if it is not.
912 File: gpgme.info, Node: Engine Information, Next: Engine Configuration, Prev: Engine Version Check, Up: Protocols and Engines
914 3.2 Engine Information
915 ======================
917 -- Data type: gpgme_engine_info_t
918 The ‘gpgme_engine_info_t’ type specifies a pointer to a structure
919 describing a crypto engine. The structure contains the following
922 ‘gpgme_engine_info_t next’
923 This is a pointer to the next engine info structure in the
924 linked list, or ‘NULL’ if this is the last element.
926 ‘gpgme_protocol_t protocol’
927 This is the protocol for which the crypto engine is used. You
928 can convert this to a string with ‘gpgme_get_protocol_name’
931 ‘const char *file_name’
932 This is a string holding the file name of the executable of
933 the crypto engine. Currently, it is never ‘NULL’, but using
934 ‘NULL’ is reserved for future use, so always check before you
937 ‘const char *home_dir’
938 This is a string holding the directory name of the crypto
939 engine’s configuration directory. If it is ‘NULL’, then the
940 default directory is used. See ‘gpgme_get_dirinfo’ on how to
941 get the default directory.
943 ‘const char *version’
944 This is a string containing the version number of the crypto
945 engine. It might be ‘NULL’ if the version number can not be
946 determined, for example because the executable doesn’t exist
949 ‘const char *req_version’
950 This is a string containing the minimum required version
951 number of the crypto engine for GPGME to work correctly. This
952 is the version number that ‘gpgme_engine_check_version’
953 verifies against. Currently, it is never ‘NULL’, but using
954 ‘NULL’ is reserved for future use, so always check before you
957 -- Function: gpgme_error_t gpgme_get_engine_info
958 (gpgme_engine_info_t *INFO)
959 The function ‘gpgme_get_engine_info’ returns a linked list of
960 engine info structures in INFO. Each info structure describes the
961 defaults of one configured backend.
963 The memory for the info structures is allocated the first time this
964 function is invoked, and must not be freed by the caller.
966 This function returns the error code ‘GPG_ERR_NO_ERROR’ if
967 successful, and a system error if the memory could not be
970 Here is an example how you can provide more diagnostics if you
971 receive an error message which indicates that the crypto engine is
979 if (gpgme_err_code (err) == GPG_ERR_INV_ENGINE)
981 gpgme_engine_info_t info;
982 err = gpgme_get_engine_info (&info);
985 while (info && info->protocol != gpgme_get_protocol (ctx))
988 fprintf (stderr, "GPGME compiled without support for protocol %s",
989 gpgme_get_protocol_name (info->protocol));
990 else if (info->file_name && !info->version)
991 fprintf (stderr, "Engine %s not installed properly",
993 else if (info->file_name && info->version && info->req_version)
994 fprintf (stderr, "Engine %s version %s installed, "
995 "but at least version %s required", info->file_name,
996 info->version, info->req_version);
998 fprintf (stderr, "Unknown problem with engine for protocol %s",
999 gpgme_get_protocol_name (info->protocol));
1004 File: gpgme.info, Node: Engine Configuration, Next: OpenPGP, Prev: Engine Information, Up: Protocols and Engines
1006 3.3 Engine Configuration
1007 ========================
1009 You can change the configuration of a backend engine, and thus change
1010 the executable program and configuration directory to be used. You can
1011 make these changes the default or set them for some contexts
1014 -- Function: gpgme_error_t gpgme_set_engine_info
1015 (gpgme_protocol_t PROTO, const char *FILE_NAME,
1016 const char *HOME_DIR)
1017 The function ‘gpgme_set_engine_info’ changes the default
1018 configuration of the crypto engine implementing the protocol PROTO.
1020 FILE_NAME is the file name of the executable program implementing
1021 this protocol, and HOME_DIR is the directory name of the
1022 configuration directory for this crypto engine. If HOME_DIR is
1023 ‘NULL’, the engine’s default will be used.
1025 The new defaults are not applied to already created GPGME contexts.
1027 This function returns the error code ‘GPG_ERR_NO_ERROR’ if
1028 successful, or an eror code on failure.
1030 The functions ‘gpgme_ctx_get_engine_info’ and
1031 ‘gpgme_ctx_set_engine_info’ can be used to change the engine
1032 configuration per context. *Note Crypto Engine::.
1035 File: gpgme.info, Node: OpenPGP, Next: Cryptographic Message Syntax, Prev: Engine Configuration, Up: Protocols and Engines
1040 OpenPGP is implemented by GnuPG, the GNU Privacy Guard. This is the
1041 first protocol that was supported by GPGME.
1043 The OpenPGP protocol is specified by ‘GPGME_PROTOCOL_OpenPGP’.
1046 File: gpgme.info, Node: Cryptographic Message Syntax, Next: Assuan, Prev: OpenPGP, Up: Protocols and Engines
1048 3.5 Cryptographic Message Syntax
1049 ================================
1051 CMS is implemented by GpgSM, the S/MIME implementation for GnuPG.
1053 The CMS protocol is specified by ‘GPGME_PROTOCOL_CMS’.
1056 File: gpgme.info, Node: Assuan, Prev: Cryptographic Message Syntax, Up: Protocols and Engines
1061 Assuan is the RPC library used by the various GnuPG components. The
1062 Assuan protocol allows one to talk to arbitrary Assuan servers using
1063 GPGME. *Note Using the Assuan protocol::.
1065 The ASSUAN protocol is specified by ‘GPGME_PROTOCOL_ASSUAN’.
1068 File: gpgme.info, Node: Algorithms, Next: Error Handling, Prev: Protocols and Engines, Up: Top
1073 The crypto backends support a variety of algorithms used in public key
1074 cryptography.(1) The following sections list the identifiers used to
1075 denote such an algorithm.
1079 * Public Key Algorithms:: A list of all public key algorithms.
1080 * Hash Algorithms:: A list of all hash algorithms.
1082 ---------- Footnotes ----------
1084 (1) Some engines also provide symmetric only encryption; see the
1085 description of the encryption function on how to use this.
1088 File: gpgme.info, Node: Public Key Algorithms, Next: Hash Algorithms, Up: Algorithms
1090 4.1 Public Key Algorithms
1091 =========================
1093 Public key algorithms are used for encryption, decryption, signing and
1094 verification of signatures.
1096 -- Data type: enum gpgme_pubkey_algo_t
1097 The ‘gpgme_pubkey_algo_t’ type specifies the set of all public key
1098 algorithms that are supported by GPGME. Possible values are:
1101 This value indicates the RSA (Rivest, Shamir, Adleman)
1105 Deprecated. This value indicates the RSA (Rivest, Shamir,
1106 Adleman) algorithm for encryption and decryption only.
1109 Deprecated. This value indicates the RSA (Rivest, Shamir,
1110 Adleman) algorithm for signing and verification only.
1113 This value indicates DSA, the Digital Signature Algorithm.
1116 This value indicates ElGamal.
1119 This value also indicates ElGamal and is used specifically in
1123 This value is a generic indicator for ellipic curve
1127 This value indicates ECDSA, the Elliptic Curve Digital
1128 Signature Algorithm as defined by FIPS 186-2 and RFC-6637.
1131 This value indicates ECDH, the Eliptic Curve Diffie-Hellmann
1132 encryption algorithm as defined by RFC-6637.
1135 This value indicates the EdDSA algorithm.
1137 -- Function: const char * gpgme_pubkey_algo_name
1138 (gpgme_pubkey_algo_t ALGO)
1139 The function ‘gpgme_pubkey_algo_name’ returns a pointer to a
1140 statically allocated string containing a description of the public
1141 key algorithm ALGO. This string can be used to output the name of
1142 the public key algorithm to the user.
1144 If ALGO is not a valid public key algorithm, ‘NULL’ is returned.
1146 -- Function: char * gpgme_pubkey_algo_string (gpgme_subkey_t KEY)
1147 The function ‘gpgme_pubkey_algo_string’ is a convenience function
1148 to build and return an algorithm string in the same way GnuPG does
1149 (e.g. “rsa2048” or “ed25519”). The caller must free the result
1150 using ‘gpgme_free’. On error (e.g. invalid argument or memory
1151 exhausted), the function returns NULL and sets ‘ERRNO’.
1154 File: gpgme.info, Node: Hash Algorithms, Prev: Public Key Algorithms, Up: Algorithms
1159 Hash (message digest) algorithms are used to compress a long message to
1160 make it suitable for public key cryptography.
1162 -- Data type: enum gpgme_hash_algo_t
1163 The ‘gpgme_hash_algo_t’ type specifies the set of all hash
1164 algorithms that are supported by GPGME. Possible values are:
1178 ‘GPGME_MD_CRC32_RFC1510’
1179 ‘GPGME_MD_CRC24_RFC2440’
1181 -- Function: const char * gpgme_hash_algo_name (gpgme_hash_algo_t ALGO)
1182 The function ‘gpgme_hash_algo_name’ returns a pointer to a
1183 statically allocated string containing a description of the hash
1184 algorithm ALGO. This string can be used to output the name of the
1185 hash algorithm to the user.
1187 If ALGO is not a valid hash algorithm, ‘NULL’ is returned.
1190 File: gpgme.info, Node: Error Handling, Next: Exchanging Data, Prev: Algorithms, Up: Top
1195 Many functions in GPGME can return an error if they fail. For this
1196 reason, the application should always catch the error condition and take
1197 appropriate measures, for example by releasing the resources and passing
1198 the error up to the caller, or by displaying a descriptive message to
1199 the user and cancelling the operation.
1201 Some error values do not indicate a system error or an error in the
1202 operation, but the result of an operation that failed properly. For
1203 example, if you try to decrypt a tempered message, the decryption will
1204 fail. Another error value actually means that the end of a data buffer
1205 or list has been reached. The following descriptions explain for many
1206 error codes what they mean usually. Some error values have specific
1207 meanings if returned by a certain functions. Such cases are described
1208 in the documentation of those functions.
1210 GPGME uses the ‘libgpg-error’ library. This allows to share the
1211 error codes with other components of the GnuPG system, and thus pass
1212 error values transparently from the crypto engine, or some helper
1213 application of the crypto engine, to the user. This way no information
1214 is lost. As a consequence, GPGME does not use its own identifiers for
1215 error codes, but uses those provided by ‘libgpg-error’. They usually
1216 start with ‘GPG_ERR_’.
1218 However, GPGME does provide aliases for the functions defined in
1219 libgpg-error, which might be preferred for name space consistency.
1223 * Error Values:: The error value and what it means.
1224 * Error Sources:: A list of important error sources.
1225 * Error Codes:: A list of important error codes.
1226 * Error Strings:: How to get a descriptive string from a value.
1229 File: gpgme.info, Node: Error Values, Next: Error Sources, Up: Error Handling
1234 -- Data type: gpgme_err_code_t
1235 The ‘gpgme_err_code_t’ type is an alias for the ‘libgpg-error’ type
1236 ‘gpg_err_code_t’. The error code indicates the type of an error,
1237 or the reason why an operation failed.
1239 A list of important error codes can be found in the next section.
1241 -- Data type: gpgme_err_source_t
1242 The ‘gpgme_err_source_t’ type is an alias for the ‘libgpg-error’
1243 type ‘gpg_err_source_t’. The error source has not a precisely
1244 defined meaning. Sometimes it is the place where the error
1245 happened, sometimes it is the place where an error was encoded into
1246 an error value. Usually the error source will give an indication
1247 to where to look for the problem. This is not always true, but it
1248 is attempted to achieve this goal.
1250 A list of important error sources can be found in the next section.
1252 -- Data type: gpgme_error_t
1253 The ‘gpgme_error_t’ type is an alias for the ‘libgpg-error’ type
1254 ‘gpg_error_t’. An error value like this has always two components,
1255 an error code and an error source. Both together form the error
1258 Thus, the error value can not be directly compared against an error
1259 code, but the accessor functions described below must be used.
1260 However, it is guaranteed that only 0 is used to indicate success
1261 (‘GPG_ERR_NO_ERROR’), and that in this case all other parts of the
1262 error value are set to 0, too.
1264 Note that in GPGME, the error source is used purely for
1265 diagnostical purposes. Only the error code should be checked to
1266 test for a certain outcome of a function. The manual only
1267 documents the error code part of an error value. The error source
1268 is left unspecified and might be anything.
1270 -- Function: static inline gpgme_err_code_t gpgme_err_code
1272 The static inline function ‘gpgme_err_code’ returns the
1273 ‘gpgme_err_code_t’ component of the error value ERR. This function
1274 must be used to extract the error code from an error value in order
1275 to compare it with the ‘GPG_ERR_*’ error code macros.
1277 -- Function: static inline gpgme_err_source_t gpgme_err_source
1279 The static inline function ‘gpgme_err_source’ returns the
1280 ‘gpgme_err_source_t’ component of the error value ERR. This
1281 function must be used to extract the error source from an error
1282 value in order to compare it with the ‘GPG_ERR_SOURCE_*’ error
1285 -- Function: static inline gpgme_error_t gpgme_err_make
1286 (gpgme_err_source_t SOURCE, gpgme_err_code_t CODE)
1287 The static inline function ‘gpgme_err_make’ returns the error value
1288 consisting of the error source SOURCE and the error code CODE.
1290 This function can be used in callback functions to construct an
1291 error value to return it to the library.
1293 -- Function: static inline gpgme_error_t gpgme_error
1294 (gpgme_err_code_t CODE)
1295 The static inline function ‘gpgme_error’ returns the error value
1296 consisting of the default error source and the error code CODE.
1298 For GPGME applications, the default error source is
1299 ‘GPG_ERR_SOURCE_USER_1’. You can define ‘GPGME_ERR_SOURCE_DEFAULT’
1300 before including ‘gpgme.h’ to change this default.
1302 This function can be used in callback functions to construct an
1303 error value to return it to the library.
1305 The ‘libgpg-error’ library provides error codes for all system error
1306 numbers it knows about. If ERR is an unknown error number, the error
1307 code ‘GPG_ERR_UNKNOWN_ERRNO’ is used. The following functions can be
1308 used to construct error values from system errnor numbers.
1310 -- Function: gpgme_error_t gpgme_err_make_from_errno
1311 (gpgme_err_source_t SOURCE, int ERR)
1312 The function ‘gpgme_err_make_from_errno’ is like ‘gpgme_err_make’,
1313 but it takes a system error like ‘errno’ instead of a
1314 ‘gpgme_err_code_t’ error code.
1316 -- Function: gpgme_error_t gpgme_error_from_errno (int ERR)
1317 The function ‘gpgme_error_from_errno’ is like ‘gpgme_error’, but it
1318 takes a system error like ‘errno’ instead of a ‘gpgme_err_code_t’
1321 Sometimes you might want to map system error numbers to error codes
1322 directly, or map an error code representing a system error back to the
1323 system error number. The following functions can be used to do that.
1325 -- Function: gpgme_err_code_t gpgme_err_code_from_errno (int ERR)
1326 The function ‘gpgme_err_code_from_errno’ returns the error code for
1327 the system error ERR. If ERR is not a known system error, the
1328 function returns ‘GPG_ERR_UNKNOWN_ERRNO’.
1330 -- Function: int gpgme_err_code_to_errno (gpgme_err_code_t ERR)
1331 The function ‘gpgme_err_code_to_errno’ returns the system error for
1332 the error code ERR. If ERR is not an error code representing a
1333 system error, or if this system error is not defined on this
1334 system, the function returns ‘0’.
1337 File: gpgme.info, Node: Error Sources, Next: Error Codes, Prev: Error Values, Up: Error Handling
1342 The library ‘libgpg-error’ defines an error source for every component
1343 of the GnuPG system. The error source part of an error value is not
1344 well defined. As such it is mainly useful to improve the diagnostic
1345 error message for the user.
1347 If the error code part of an error value is ‘0’, the whole error
1348 value will be ‘0’. In this case the error source part is of course
1349 ‘GPG_ERR_SOURCE_UNKNOWN’.
1351 The list of error sources that might occur in applications using
1354 ‘GPG_ERR_SOURCE_UNKNOWN’
1355 The error source is not known. The value of this error source is
1358 ‘GPG_ERR_SOURCE_GPGME’
1359 The error source is GPGME itself. This is the default for errors
1360 that occur in the GPGME library.
1362 ‘GPG_ERR_SOURCE_GPG’
1363 The error source is GnuPG, which is the crypto engine used for the
1366 ‘GPG_ERR_SOURCE_GPGSM’
1367 The error source is GPGSM, which is the crypto engine used for the
1370 ‘GPG_ERR_SOURCE_GCRYPT’
1371 The error source is ‘libgcrypt’, which is used by crypto engines to
1372 perform cryptographic operations.
1374 ‘GPG_ERR_SOURCE_GPGAGENT’
1375 The error source is ‘gpg-agent’, which is used by crypto engines to
1376 perform operations with the secret key.
1378 ‘GPG_ERR_SOURCE_PINENTRY’
1379 The error source is ‘pinentry’, which is used by ‘gpg-agent’ to
1380 query the passphrase to unlock a secret key.
1382 ‘GPG_ERR_SOURCE_SCD’
1383 The error source is the SmartCard Daemon, which is used by
1384 ‘gpg-agent’ to delegate operations with the secret key to a
1387 ‘GPG_ERR_SOURCE_KEYBOX’
1388 The error source is ‘libkbx’, a library used by the crypto engines
1389 to manage local keyrings.
1391 ‘GPG_ERR_SOURCE_USER_1’
1392 ‘GPG_ERR_SOURCE_USER_2’
1393 ‘GPG_ERR_SOURCE_USER_3’
1394 ‘GPG_ERR_SOURCE_USER_4’
1395 These error sources are not used by any GnuPG component and can be
1396 used by other software. For example, applications using GPGME can
1397 use them to mark error values coming from callback handlers. Thus
1398 ‘GPG_ERR_SOURCE_USER_1’ is the default for errors created with
1399 ‘gpgme_error’ and ‘gpgme_error_from_errno’, unless you define
1400 ‘GPGME_ERR_SOURCE_DEFAULT’ before including ‘gpgme.h’.
1403 File: gpgme.info, Node: Error Codes, Next: Error Strings, Prev: Error Sources, Up: Error Handling
1408 The library ‘libgpg-error’ defines many error values. Most of them are
1409 not used by ‘GPGME’ directly, but might be returned by GPGME because it
1410 received them from the crypto engine. The below list only includes such
1411 error codes that have a specific meaning in ‘GPGME’, or which are so
1412 common that you should know about them.
1415 This value indicates the end of a list, buffer or file.
1418 This value indicates success. The value of this error code is ‘0’.
1419 Also, it is guaranteed that an error value made from the error code
1420 ‘0’ will be ‘0’ itself (as a whole). This means that the error
1421 source information is lost for this error code, however, as this
1422 error code indicates that no error occured, this is generally not a
1426 This value means that something went wrong, but either there is not
1427 enough information about the problem to return a more useful error
1428 value, or there is no separate error value for this type of
1432 This value means that an out-of-memory condition occurred.
1435 System errors are mapped to GPG_ERR_FOO where FOO is the symbol for
1439 This value means that some user provided data was out of range.
1440 This can also refer to objects. For example, if an empty
1441 ‘gpgme_data_t’ object was expected, but one containing data was
1442 provided, this error value is returned.
1444 ‘GPG_ERR_UNUSABLE_PUBKEY’
1445 This value means that some recipients for a message were invalid.
1447 ‘GPG_ERR_UNUSABLE_SECKEY’
1448 This value means that some signers were invalid.
1451 This value means that a ‘gpgme_data_t’ object which was expected to
1452 have content was found empty.
1455 This value means that a conflict of some sort occurred.
1457 ‘GPG_ERR_NOT_IMPLEMENTED’
1458 This value indicates that the specific function (or operation) is
1459 not implemented. This error should never happen. It can only
1460 occur if you use certain values or configuration options which do
1461 not work, but for which we think that they should work at some
1464 ‘GPG_ERR_DECRYPT_FAILED’
1465 This value indicates that a decryption operation was unsuccessful.
1467 ‘GPG_ERR_BAD_PASSPHRASE’
1468 This value means that the user did not provide a correct passphrase
1472 This value means that the operation was canceled.
1474 ‘GPG_ERR_INV_ENGINE’
1475 This value means that the engine that implements the desired
1476 protocol is currently not available. This can either be because
1477 the sources were configured to exclude support for this engine, or
1478 because the engine is not installed properly.
1480 ‘GPG_ERR_AMBIGUOUS_NAME’
1481 This value indicates that a user ID or other specifier did not
1482 specify a unique key.
1484 ‘GPG_ERR_WRONG_KEY_USAGE’
1485 This value indicates that a key is not used appropriately.
1487 ‘GPG_ERR_CERT_REVOKED’
1488 This value indicates that a key signature was revoced.
1490 ‘GPG_ERR_CERT_EXPIRED’
1491 This value indicates that a key signature expired.
1493 ‘GPG_ERR_NO_CRL_KNOWN’
1494 This value indicates that no certificate revocation list is known
1495 for the certificate.
1497 ‘GPG_ERR_NO_POLICY_MATCH’
1498 This value indicates that a policy issue occured.
1501 This value indicates that no secret key for the user ID is
1504 ‘GPG_ERR_MISSING_CERT’
1505 This value indicates that a key could not be imported because the
1506 issuer certificate is missing.
1508 ‘GPG_ERR_BAD_CERT_CHAIN’
1509 This value indicates that a key could not be imported because its
1510 certificate chain is not good, for example it could be too long.
1512 ‘GPG_ERR_UNSUPPORTED_ALGORITHM’
1513 This value means a verification failed because the cryptographic
1514 algorithm is not supported by the crypto backend.
1516 ‘GPG_ERR_BAD_SIGNATURE’
1517 This value means a verification failed because the signature is
1521 This value means a verification failed because the public key is
1528 These error codes are not used by any GnuPG component and can be
1529 freely used by other software. Applications using GPGME might use
1530 them to mark specific errors returned by callback handlers if no
1531 suitable error codes (including the system errors) for these errors
1535 File: gpgme.info, Node: Error Strings, Prev: Error Codes, Up: Error Handling
1540 -- Function: const char * gpgme_strerror (gpgme_error_t ERR)
1541 The function ‘gpgme_strerror’ returns a pointer to a statically
1542 allocated string containing a description of the error code
1543 contained in the error value ERR. This string can be used to
1544 output a diagnostic message to the user.
1546 This function is not thread safe. Use ‘gpgme_strerror_r’ in
1547 multi-threaded programs.
1549 -- Function: int gpgme_strerror_r (gpgme_error_t ERR, char *BUF,
1551 The function ‘gpgme_strerror_r’ returns the error string for ERR in
1552 the user-supplied buffer BUF of size BUFLEN. This function is, in
1553 contrast to ‘gpgme_strerror’, thread-safe if a thread-safe
1554 ‘strerror_r’ function is provided by the system. If the function
1555 succeeds, 0 is returned and BUF contains the string describing the
1556 error. If the buffer was not large enough, ERANGE is returned and
1557 BUF contains as much of the beginning of the error string as fits
1560 -- Function: const char * gpgme_strsource (gpgme_error_t ERR)
1561 The function ‘gpgme_strerror’ returns a pointer to a statically
1562 allocated string containing a description of the error source
1563 contained in the error value ERR. This string can be used to
1564 output a diagnostic message to the user.
1566 The following example illustrates the use of ‘gpgme_strerror’:
1569 gpgme_error_t err = gpgme_new (&ctx);
1572 fprintf (stderr, "%s: creating GpgME context failed: %s: %s\n",
1573 argv[0], gpgme_strsource (err), gpgme_strerror (err));
1578 File: gpgme.info, Node: Exchanging Data, Next: Contexts, Prev: Error Handling, Up: Top
1583 A lot of data has to be exchanged between the user and the crypto
1584 engine, like plaintext messages, ciphertext, signatures and information
1585 about the keys. The technical details about exchanging the data
1586 information are completely abstracted by GPGME. The user provides and
1587 receives the data via ‘gpgme_data_t’ objects, regardless of the
1588 communication protocol between GPGME and the crypto engine in use.
1590 -- Data type: gpgme_data_t
1591 The ‘gpgme_data_t’ type is a handle for a container for generic
1592 data, which is used by GPGME to exchange data with the user.
1594 ‘gpgme_data_t’ objects do not provide notifications on events. It is
1595 assumed that read and write operations are blocking until data is
1596 available. If this is undesirable, the application must ensure that all
1597 GPGME data operations always have data available, for example by using
1598 memory buffers or files rather than pipes or sockets. This might be
1599 relevant, for example, if the external event loop mechanism is used.
1601 -- Data type: gpgme_off_t
1602 On POSIX platforms the ‘gpgme_off_t’ type is an alias for ‘off_t’;
1603 it may be used interchangeable. On Windows platforms ‘gpgme_off_t’
1604 is defined as a long (i.e. 32 bit) for 32 bit Windows and as a 64
1605 bit signed integer for 64 bit Windows.
1607 -- Data type: gpgme_ssize_t
1608 The ‘gpgme_ssize_t’ type is an alias for ‘ssize_t’. It has only
1609 been introduced to overcome portability problems pertaining to the
1610 declaration of ‘ssize_t’ by different toolchains.
1614 * Creating Data Buffers:: Creating new data buffers.
1615 * Destroying Data Buffers:: Releasing data buffers.
1616 * Manipulating Data Buffers:: Operations on data buffers.
1619 File: gpgme.info, Node: Creating Data Buffers, Next: Destroying Data Buffers, Up: Exchanging Data
1621 6.1 Creating Data Buffers
1622 =========================
1624 Data objects can be based on memory, files, or callback functions
1625 provided by the user. Not all operations are supported by all objects.
1629 * Memory Based Data Buffers:: Creating memory based data buffers.
1630 * File Based Data Buffers:: Creating file based data buffers.
1631 * Callback Based Data Buffers:: Creating callback based data buffers.
1634 File: gpgme.info, Node: Memory Based Data Buffers, Next: File Based Data Buffers, Up: Creating Data Buffers
1636 6.1.1 Memory Based Data Buffers
1637 -------------------------------
1639 Memory based data objects store all data in allocated memory. This is
1640 convenient, but only practical for an amount of data that is a fraction
1641 of the available physical memory. The data has to be copied from its
1642 source and to its destination, which can often be avoided by using one
1643 of the other data object
1645 -- Function: gpgme_error_t gpgme_data_new (gpgme_data_t *DH)
1646 The function ‘gpgme_data_new’ creates a new ‘gpgme_data_t’ object
1647 and returns a handle for it in DH. The data object is memory based
1648 and initially empty.
1650 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data
1651 object was successfully created, ‘GPG_ERR_INV_VALUE’ if DH is not a
1652 valid pointer, and ‘GPG_ERR_ENOMEM’ if not enough memory is
1655 -- Function: gpgme_error_t gpgme_data_new_from_mem (gpgme_data_t *DH,
1656 const char *BUFFER, size_t SIZE, int COPY)
1657 The function ‘gpgme_data_new_from_mem’ creates a new ‘gpgme_data_t’
1658 object and fills it with SIZE bytes starting from BUFFER.
1660 If COPY is not zero, a private copy of the data is made. If COPY
1661 is zero, the data is taken from the specified buffer as needed, and
1662 the user has to ensure that the buffer remains valid for the whole
1663 life span of the data object.
1665 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data
1666 object was successfully created, ‘GPG_ERR_INV_VALUE’ if DH or
1667 BUFFER is not a valid pointer, and ‘GPG_ERR_ENOMEM’ if not enough
1668 memory is available.
1670 -- Function: gpgme_error_t gpgme_data_new_from_file (gpgme_data_t *DH,
1671 const char *FILENAME, int COPY)
1672 The function ‘gpgme_data_new_from_file’ creates a new
1673 ‘gpgme_data_t’ object and fills it with the content of the file
1676 If COPY is not zero, the whole file is read in at initialization
1677 time and the file is not used anymore after that. This is the only
1678 mode supported currently. Later, a value of zero for COPY might
1679 cause all reads to be delayed until the data is needed, but this is
1680 not yet implemented.
1682 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data
1683 object was successfully created, ‘GPG_ERR_INV_VALUE’ if DH or
1684 FILENAME is not a valid pointer, ‘GPG_ERR_NOT_IMPLEMENTED’ if CODE
1685 is zero, and ‘GPG_ERR_ENOMEM’ if not enough memory is available.
1687 -- Function: gpgme_error_t gpgme_data_new_from_filepart
1688 (gpgme_data_t *DH, const char *FILENAME, FILE *FP,
1689 off_t OFFSET, size_t LENGTH)
1690 The function ‘gpgme_data_new_from_filepart’ creates a new
1691 ‘gpgme_data_t’ object and fills it with a part of the file
1692 specified by FILENAME or FP.
1694 Exactly one of FILENAME and FP must be non-zero, the other must be
1695 zero. The argument that is not zero specifies the file from which
1696 LENGTH bytes are read into the data object, starting from OFFSET.
1698 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data
1699 object was successfully created, ‘GPG_ERR_INV_VALUE’ if DH and
1700 exactly one of FILENAME and FP is not a valid pointer, and
1701 ‘GPG_ERR_ENOMEM’ if not enough memory is available.
1704 File: gpgme.info, Node: File Based Data Buffers, Next: Callback Based Data Buffers, Prev: Memory Based Data Buffers, Up: Creating Data Buffers
1706 6.1.2 File Based Data Buffers
1707 -----------------------------
1709 File based data objects operate directly on file descriptors or streams.
1710 Only a small amount of data is stored in core at any time, so the size
1711 of the data objects is not limited by GPGME.
1713 -- Function: gpgme_error_t gpgme_data_new_from_fd (gpgme_data_t *DH,
1715 The function ‘gpgme_data_new_from_fd’ creates a new ‘gpgme_data_t’
1716 object and uses the file descriptor FD to read from (if used as an
1717 input data object) and write to (if used as an output data object).
1719 When using the data object as an input buffer, the function might
1720 read a bit more from the file descriptor than is actually needed by
1721 the crypto engine in the desired operation because of internal
1724 Note that GPGME assumes that the file descriptor is set to blocking
1725 mode. Errors during I/O operations, except for EINTR, are usually
1726 fatal for crypto operations.
1728 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data
1729 object was successfully created, and ‘GPG_ERR_ENOMEM’ if not enough
1730 memory is available.
1732 -- Function: gpgme_error_t gpgme_data_new_from_stream
1733 (gpgme_data_t *DH, FILE *STREAM)
1734 The function ‘gpgme_data_new_from_stream’ creates a new
1735 ‘gpgme_data_t’ object and uses the I/O stream STREAM to read from
1736 (if used as an input data object) and write to (if used as an
1737 output data object).
1739 When using the data object as an input buffer, the function might
1740 read a bit more from the stream than is actually needed by the
1741 crypto engine in the desired operation because of internal
1744 Note that GPGME assumes that the stream is in blocking mode.
1745 Errors during I/O operations, except for EINTR, are usually fatal
1746 for crypto operations.
1748 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data
1749 object was successfully created, and ‘GPG_ERR_ENOMEM’ if not enough
1750 memory is available.
1753 File: gpgme.info, Node: Callback Based Data Buffers, Prev: File Based Data Buffers, Up: Creating Data Buffers
1755 6.1.3 Callback Based Data Buffers
1756 ---------------------------------
1758 If neither memory nor file based data objects are a good fit for your
1759 application, you can implement the functions a data object provides
1760 yourself and create a data object from these callback functions.
1762 -- Data type: ssize_t (*gpgme_data_read_cb_t) (void *HANDLE,
1763 void *BUFFER, size_t SIZE)
1764 The ‘gpgme_data_read_cb_t’ type is the type of functions which
1765 GPGME calls if it wants to read data from a user-implemented data
1766 object. The function should read up to SIZE bytes from the current
1767 read position into the space starting at BUFFER. The HANDLE is
1768 provided by the user at data object creation time.
1770 Note that GPGME assumes that the read blocks until data is
1771 available. Errors during I/O operations, except for EINTR, are
1772 usually fatal for crypto operations.
1774 The function should return the number of bytes read, 0 on EOF, and
1775 -1 on error. If an error occurs, ERRNO should be set to describe
1776 the type of the error.
1778 -- Data type: ssize_t (*gpgme_data_write_cb_t) (void *HANDLE,
1779 const void *BUFFER, size_t SIZE)
1780 The ‘gpgme_data_write_cb_t’ type is the type of functions which
1781 GPGME calls if it wants to write data to a user-implemented data
1782 object. The function should write up to SIZE bytes to the current
1783 write position from the space starting at BUFFER. The HANDLE is
1784 provided by the user at data object creation time.
1786 Note that GPGME assumes that the write blocks until data is
1787 available. Errors during I/O operations, except for EINTR, are
1788 usually fatal for crypto operations.
1790 The function should return the number of bytes written, and -1 on
1791 error. If an error occurs, ERRNO should be set to describe the
1794 -- Data type: off_t (*gpgme_data_seek_cb_t) (void *HANDLE,
1795 off_t OFFSET, int WHENCE)
1796 The ‘gpgme_data_seek_cb_t’ type is the type of functions which
1797 GPGME calls if it wants to change the current read/write position
1798 in a user-implemented data object, just like the ‘lseek’ function.
1800 The function should return the new read/write position, and -1 on
1801 error. If an error occurs, ERRNO should be set to describe the
1804 -- Data type: void (*gpgme_data_release_cb_t) (void *HANDLE)
1805 The ‘gpgme_data_release_cb_t’ type is the type of functions which
1806 GPGME calls if it wants to destroy a user-implemented data object.
1807 The HANDLE is provided by the user at data object creation time.
1809 -- Data type: struct gpgme_data_cbs
1810 This structure is used to store the data callback interface
1811 functions described above. It has the following members:
1813 ‘gpgme_data_read_cb_t read’
1814 This is the function called by GPGME to read data from the
1815 data object. It is only required for input data object.
1817 ‘gpgme_data_write_cb_t write’
1818 This is the function called by GPGME to write data to the data
1819 object. It is only required for output data object.
1821 ‘gpgme_data_seek_cb_t seek’
1822 This is the function called by GPGME to change the current
1823 read/write pointer in the data object (if available). It is
1826 ‘gpgme_data_release_cb_t release’
1827 This is the function called by GPGME to release a data object.
1830 -- Function: gpgme_error_t gpgme_data_new_from_cbs (gpgme_data_t *DH,
1831 gpgme_data_cbs_t CBS, void *HANDLE)
1832 The function ‘gpgme_data_new_from_cbs’ creates a new ‘gpgme_data_t’
1833 object and uses the user-provided callback functions to operate on
1836 The handle HANDLE is passed as first argument to the callback
1837 functions. This can be used to identify this data object.
1839 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data
1840 object was successfully created, and ‘GPG_ERR_ENOMEM’ if not enough
1841 memory is available.
1844 File: gpgme.info, Node: Destroying Data Buffers, Next: Manipulating Data Buffers, Prev: Creating Data Buffers, Up: Exchanging Data
1846 6.2 Destroying Data Buffers
1847 ===========================
1849 -- Function: void gpgme_data_release (gpgme_data_t DH)
1850 The function ‘gpgme_data_release’ destroys the data object with the
1851 handle DH. It releases all associated resources that were not
1852 provided by the user in the first place.
1854 -- Function: char * gpgme_data_release_and_get_mem (gpgme_data_t DH,
1856 The function ‘gpgme_data_release_and_get_mem’ is like
1857 ‘gpgme_data_release’, except that it returns the data buffer and
1858 its length that was provided by the object.
1860 The user has to release the buffer with ‘gpgme_free’. In case the
1861 user provided the data buffer in non-copy mode, a copy will be made
1864 In case an error returns, or there is no suitable data buffer that
1865 can be returned to the user, the function will return ‘NULL’. In
1866 any case, the data object DH is destroyed.
1868 -- Function: void gpgme_free (void *BUFFER)
1869 The function ‘gpgme_free’ releases the memory returned by
1870 ‘gpgme_data_release_and_get_mem’ and ‘gpgme_pubkey_algo_string’.
1871 It should be used instead of the system libraries ‘free’ function
1872 in case different allocators are used by a program. This is often
1873 the case if gpgme is used under Windows as a DLL.
1876 File: gpgme.info, Node: Manipulating Data Buffers, Prev: Destroying Data Buffers, Up: Exchanging Data
1878 6.3 Manipulating Data Buffers
1879 =============================
1881 Data buffers contain data and meta-data. The following operations can
1882 be used to manipulate both.
1886 * Data Buffer I/O Operations:: I/O operations on data buffers.
1887 * Data Buffer Meta-Data:: Meta-data manipulation of data buffers.
1888 * Data Buffer Convenience:: Convenience function for data buffers.
1891 File: gpgme.info, Node: Data Buffer I/O Operations, Next: Data Buffer Meta-Data, Up: Manipulating Data Buffers
1893 6.3.1 Data Buffer I/O Operations
1894 --------------------------------
1896 -- Function: ssize_t gpgme_data_read (gpgme_data_t DH, void *BUFFER,
1898 The function ‘gpgme_data_read’ reads up to LENGTH bytes from the
1899 data object with the handle DH into the space starting at BUFFER.
1901 If no error occurs, the actual amount read is returned. If the end
1902 of the data object is reached, the function returns 0.
1904 In all other cases, the function returns -1 and sets ERRNO.
1906 -- Function: ssize_t gpgme_data_write (gpgme_data_t DH,
1907 const void *BUFFER, size_t SIZE)
1908 The function ‘gpgme_data_write’ writes up to SIZE bytes starting
1909 from BUFFER into the data object with the handle DH at the current
1912 The function returns the number of bytes actually written, or -1 if
1913 an error occurs. If an error occurs, ERRNO is set.
1915 -- Function: off_t gpgme_data_seek (gpgme_data_t DH, off_t OFFSET,
1917 The function ‘gpgme_data_seek’ changes the current read/write
1920 The WHENCE argument specifies how the OFFSET should be interpreted.
1921 It must be one of the following symbolic constants:
1924 Specifies that OFFSET is a count of characters from the
1925 beginning of the data object.
1928 Specifies that OFFSET is a count of characters from the
1929 current file position. This count may be positive or
1933 Specifies that OFFSET is a count of characters from the end of
1934 the data object. A negative count specifies a position within
1935 the current extent of the data object; a positive count
1936 specifies a position past the current end. If you set the
1937 position past the current end, and actually write data, you
1938 will extend the data object with zeros up to that position.
1940 If successful, the function returns the resulting file position,
1941 measured in bytes from the beginning of the data object. You can
1942 use this feature together with ‘SEEK_CUR’ to read the current
1943 read/write position.
1945 If the function fails, -1 is returned and ERRNO is set.
1948 File: gpgme.info, Node: Data Buffer Meta-Data, Next: Data Buffer Convenience, Prev: Data Buffer I/O Operations, Up: Manipulating Data Buffers
1950 6.3.2 Data Buffer Meta-Data
1951 ---------------------------
1953 -- Function: char * gpgme_data_get_file_name (gpgme_data_t DH)
1954 The function ‘gpgme_data_get_file_name’ returns a pointer to a
1955 string containing the file name associated with the data object.
1956 The file name will be stored in the output when encrypting or
1957 signing the data and will be returned to the user when decrypting
1958 or verifying the output data.
1960 If no error occurs, the string containing the file name is
1961 returned. Otherwise, ‘NULL’ will be returned.
1963 -- Function: gpgme_error_t gpgme_data_set_file_name (gpgme_data_t DH,
1964 const char *FILE_NAME)
1965 The function ‘gpgme_data_set_file_name’ sets the file name
1966 associated with the data object. The file name will be stored in
1967 the output when encrypting or signing the data and will be returned
1968 to the user when decrypting or verifying the output data.
1970 The function returns the error code ‘GPG_ERR_INV_VALUE’ if DH is
1971 not a valid pointer and ‘GPG_ERR_ENOMEM’ if not enough memory is
1974 -- Data type: enum gpgme_data_encoding_t
1975 The ‘gpgme_data_encoding_t’ type specifies the encoding of a
1976 ‘gpgme_data_t’ object. For input data objects, the encoding is
1977 useful to give the backend a hint on the type of data. For output
1978 data objects, the encoding can specify the output data format on
1979 certain operations. Please note that not all backends support all
1980 encodings on all operations. The following data types are
1983 ‘GPGME_DATA_ENCODING_NONE’
1984 This specifies that the encoding is not known. This is the
1985 default for a new data object. The backend will try its best
1986 to detect the encoding automatically.
1988 ‘GPGME_DATA_ENCODING_BINARY’
1989 This specifies that the data is encoding in binary form; i.e.
1990 there is no special encoding.
1992 ‘GPGME_DATA_ENCODING_BASE64’
1993 This specifies that the data is encoded using the Base-64
1994 encoding scheme as used by MIME and other protocols.
1996 ‘GPGME_DATA_ENCODING_ARMOR’
1997 This specifies that the data is encoded in an armored form as
1998 used by OpenPGP and PEM.
2000 ‘GPGME_DATA_ENCODING_MIME’
2001 This specifies that the data is encoded as a MIME part.
2003 ‘GPGME_DATA_ENCODING_URL’
2004 The data is a list of linefeed delimited URLs. This is only
2005 useful with ‘gpgme_op_import’.
2007 ‘GPGME_DATA_ENCODING_URL0’
2008 The data is a list of binary zero delimited URLs. This is
2009 only useful with ‘gpgme_op_import’.
2011 ‘GPGME_DATA_ENCODING_URLESC’
2012 The data is a list of linefeed delimited URLs with all control
2013 and space characters percent escaped. This mode is is not yet
2016 -- Function: gpgme_data_encoding_t gpgme_data_get_encoding
2018 The function ‘gpgme_data_get_encoding’ returns the encoding of the
2019 data object with the handle DH. If DH is not a valid pointer (e.g.
2020 ‘NULL’) ‘GPGME_DATA_ENCODING_NONE’ is returned.
2022 -- Function: gpgme_error_t gpgme_data_set_encoding
2023 (gpgme_data_t DH, gpgme_data_encoding_t ENC)
2024 The function ‘gpgme_data_set_encoding’ changes the encoding of the
2025 data object with the handle DH to ENC.
2027 -- Function: gpgme_error_t gpgme_data_set_flag (gpgme_data_t DH,
2028 const char *NAME, const char *VALUE)
2030 Some minor properties of the data object can be controlled with
2031 flags set by this function. The properties are identified by the
2032 following values for NAME:
2035 The value is a decimal number with the length gpgme shall
2036 assume for this data object. This is useful if the data is
2037 provided by callbacks or via file descriptors but the
2038 applications knows the total size of the data. If this is set
2039 the OpenPGP engine may use this to decide on buffer allocation
2040 strategies and to provide a total value for its progress
2043 This function returns ‘0’ on success.
2046 File: gpgme.info, Node: Data Buffer Convenience, Prev: Data Buffer Meta-Data, Up: Manipulating Data Buffers
2048 6.3.3 Data Buffer Convenience Functions
2049 ---------------------------------------
2051 -- Data type: enum gpgme_data_type_t
2052 The ‘gpgme_data_type_t’ type is used to return the detected type of
2053 the content of a data buffer.
2055 ‘GPGME_DATA_TYPE_INVALID’
2056 This is returned by ‘gpgme_data_identify’ if it was not possible to
2057 identify the data. Reasons for this might be a non-seekable stream
2058 or a memory problem. The value is 0.
2059 ‘GPGME_DATA_TYPE_UNKNOWN’
2060 The type of the data is not known.
2061 ‘GPGME_DATA_TYPE_PGP_SIGNED’
2062 The data is an OpenPGP signed message. This may be a binary
2063 signature, a detached one or a cleartext signature.
2064 ‘GPGME_DATA_TYPE_PGP_OTHER’
2065 This is a generic OpenPGP message. In most cases this will be
2067 ‘GPGME_DATA_TYPE_PGP_KEY’
2068 This is an OpenPGP key (private or public).
2069 ‘GPGME_DATA_TYPE_CMS_SIGNED’
2070 This is a CMS signed message.
2071 ‘GPGME_DATA_TYPE_CMS_ENCRYPTED’
2072 This is a CMS encrypted (enveloped data) message.
2073 ‘GPGME_DATA_TYPE_CMS_OTHER’
2074 This is used for other CMS message types.
2075 ‘GPGME_DATA_TYPE_X509_CERT’
2076 The data is a X.509 certificate
2077 ‘GPGME_DATA_TYPE_PKCS12’
2078 The data is a PKCS#12 message. This is commonly used to exchange
2079 private keys for X.509.
2081 -- Function: gpgme_data_type_t gpgme_data_identify (gpgme_data_t DH)
2082 The function ‘gpgme_data_identify’ returns the type of the data
2083 with the handle DH. If it is not possible to perform the
2084 identification, the function returns zero
2085 (‘GPGME_DATA_TYPE_INVALID’). Note that depending on how the data
2086 object has been created the identification may not be possible or
2087 the data object may change its internal state (file pointer moved).
2088 For file or memory based data object, the state should not change.
2091 File: gpgme.info, Node: Contexts, Next: UI Server Protocol, Prev: Exchanging Data, Up: Top
2096 All cryptographic operations in GPGME are performed within a context,
2097 which contains the internal state of the operation as well as
2098 configuration parameters. By using several contexts you can run several
2099 cryptographic operations in parallel, with different configuration.
2101 -- Data type: gpgme_ctx_t
2102 The ‘gpgme_ctx_t’ type is a handle for a GPGME context, which is
2103 used to hold the configuration, status and result of cryptographic
2108 * Creating Contexts:: Creating new GPGME contexts.
2109 * Destroying Contexts:: Releasing GPGME contexts.
2110 * Result Management:: Managing the result of crypto operations.
2111 * Context Attributes:: Setting properties of a context.
2112 * Key Management:: Managing keys with GPGME.
2113 * Trust Item Management:: Managing trust items with GPGME.
2114 * Crypto Operations:: Using a context for cryptography.
2115 * Miscellaneous:: Miscellaneous operations
2116 * Run Control:: Controlling how operations are run.
2119 File: gpgme.info, Node: Creating Contexts, Next: Destroying Contexts, Up: Contexts
2121 7.1 Creating Contexts
2122 =====================
2124 -- Function: gpgme_error_t gpgme_new (gpgme_ctx_t *CTX)
2125 The function ‘gpgme_new’ creates a new ‘gpgme_ctx_t’ object and
2126 returns a handle for it in CTX.
2128 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
2129 context was successfully created, ‘GPG_ERR_INV_VALUE’ if CTX is not
2130 a valid pointer, and ‘GPG_ERR_ENOMEM’ if not enough memory is
2131 available. Also, it returns ‘GPG_ERR_NOT_OPERATIONAL’ if
2132 ‘gpgme_check_version’ was not called to initialize GPGME, and
2133 ‘GPG_ERR_SELFTEST_FAILED’ if a selftest failed. Currently, the
2134 only selftest is for Windows MingW32 targets to see if
2135 ‘-mms-bitfields’ was used (as required).
2138 File: gpgme.info, Node: Destroying Contexts, Next: Result Management, Prev: Creating Contexts, Up: Contexts
2140 7.2 Destroying Contexts
2141 =======================
2143 -- Function: void gpgme_release (gpgme_ctx_t CTX)
2144 The function ‘gpgme_release’ destroys the context with the handle
2145 CTX and releases all associated resources.
2148 File: gpgme.info, Node: Result Management, Next: Context Attributes, Prev: Destroying Contexts, Up: Contexts
2150 7.3 Result Management
2151 =====================
2153 The detailed result of an operation is returned in operation-specific
2154 structures such as ‘gpgme_decrypt_result_t’. The corresponding
2155 retrieval functions such as ‘gpgme_op_decrypt_result’ provide static
2156 access to the results after an operation completes. Those structures
2157 shall be considered read-only and an application must not allocate such
2158 a structure on its own. The following interfaces make it possible to
2159 detach a result structure from its associated context and give it a
2160 lifetime beyond that of the current operation or context.
2162 -- Function: void gpgme_result_ref (void *RESULT)
2163 The function ‘gpgme_result_ref’ acquires an additional reference
2164 for the result RESULT, which may be of any type ‘gpgme_*_result_t’.
2165 As long as the user holds a reference, the result structure is
2166 guaranteed to be valid and unmodified.
2168 -- Function: void gpgme_result_unref (void *RESULT)
2169 The function ‘gpgme_result_unref’ releases a reference for the
2170 result RESULT. If this was the last reference, the result
2171 structure will be destroyed and all resources associated to it will
2174 Note that a context may hold its own references to result structures,
2175 typically until the context is destroyed or the next operation is
2176 started. In fact, these references are accessed through the
2177 ‘gpgme_op_*_result’ functions.
2180 File: gpgme.info, Node: Context Attributes, Next: Key Management, Prev: Result Management, Up: Contexts
2182 7.4 Context Attributes
2183 ======================
2187 * Protocol Selection:: Selecting the protocol used by a context.
2188 * Crypto Engine:: Configuring the crypto engine.
2189 * Setting the Sender:: How to tell the engine the sender.
2190 * ASCII Armor:: Requesting ASCII armored output.
2191 * Text Mode:: Choosing canonical text mode.
2192 * Offline Mode:: Choosing offline mode.
2193 * Pinentry Mode:: Choosing the pinentry mode.
2194 * Included Certificates:: Including a number of certificates.
2195 * Key Listing Mode:: Selecting key listing mode.
2196 * Passphrase Callback:: Getting the passphrase from the user.
2197 * Progress Meter Callback:: Being informed about the progress.
2198 * Status Message Callback:: Status messages received from gpg.
2199 * Locale:: Setting the locale of a context.
2202 File: gpgme.info, Node: Protocol Selection, Next: Crypto Engine, Up: Context Attributes
2204 7.4.1 Protocol Selection
2205 ------------------------
2207 -- Function: gpgme_error_t gpgme_set_protocol (gpgme_ctx_t CTX,
2208 gpgme_protocol_t PROTO)
2209 The function ‘gpgme_set_protocol’ sets the protocol used within the
2210 context CTX to PROTO. All crypto operations will be performed by
2211 the crypto engine configured for that protocol. *Note Protocols
2214 Setting the protocol with ‘gpgme_set_protocol’ does not check if
2215 the crypto engine for that protocol is available and installed
2216 correctly. *Note Engine Version Check::.
2218 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
2219 protocol could be set successfully, and ‘GPG_ERR_INV_VALUE’ if
2220 PROTOCOL is not a valid protocol.
2222 -- Function: gpgme_protocol_t gpgme_get_protocol (gpgme_ctx_t CTX)
2223 The function ‘gpgme_get_protocol’ retrieves the protocol currently
2224 use with the context CTX.
2227 File: gpgme.info, Node: Crypto Engine, Next: Setting the Sender, Prev: Protocol Selection, Up: Context Attributes
2232 The following functions can be used to set and retrieve the
2233 configuration of the crypto engines of a specific context. The default
2234 can also be retrieved without any particular context. *Note Engine
2235 Information::. The default can also be changed globally. *Note Engine
2238 -- Function: gpgme_engine_info_t gpgme_ctx_get_engine_info
2240 The function ‘gpgme_ctx_get_engine_info’ returns a linked list of
2241 engine info structures. Each info structure describes the
2242 configuration of one configured backend, as used by the context
2245 The result is valid until the next invocation of
2246 ‘gpgme_ctx_set_engine_info’ for this particular context.
2248 This function can not fail.
2250 -- Function: gpgme_error_t gpgme_ctx_set_engine_info (gpgme_ctx_t CTX,
2251 gpgme_protocol_t PROTO, const char *FILE_NAME,
2252 const char *HOME_DIR)
2253 The function ‘gpgme_ctx_set_engine_info’ changes the configuration
2254 of the crypto engine implementing the protocol PROTO for the
2257 FILE_NAME is the file name of the executable program implementing
2258 this protocol, and HOME_DIR is the directory name of the
2259 configuration directory for this crypto engine. If HOME_DIR is
2260 ‘NULL’, the engine’s default will be used.
2262 Currently this function must be used before starting the first
2263 crypto operation. It is unspecified if and when the changes will
2264 take effect if the function is called after starting the first
2265 operation on the context CTX.
2267 This function returns the error code ‘GPG_ERR_NO_ERROR’ if
2268 successful, or an eror code on failure.
2271 File: gpgme.info, Node: Setting the Sender, Next: ASCII Armor, Prev: Crypto Engine, Up: Context Attributes
2273 7.4.3 How to tell the engine the sender.
2274 ----------------------------------------
2276 Some engines can make use of the sender’s address, for example to figure
2277 out the best user id in certain trust models. For verification and
2278 signing of mails, it is thus suggested to let the engine know the sender
2279 ("From:") address. GPGME provides two functions to accomplish that.
2280 Note that the esoteric use of multiple "From:" addresses is not
2283 -- Function: gpgme_error_t gpgme_set_sender (gpgme_ctx_t CTX,
2286 The function ‘gpgme_set_sender’ specifies the sender address for
2287 use in sign and verify operations. ADDRESS is expected to be the
2288 “addr-spec” part of an address but my also be a complete mailbox
2289 address, in which case this function extracts the “addr-spec” from
2290 it. Using ‘NULL’ for ADDRESS clears the sender address.
2292 The function returns 0 on success or an error code on failure. The
2293 most likely failure is that no valid “addr-spec” was found in
2296 -- Function: const char * gpgme_get_sender (gpgme_ctx_t CTX)
2298 The function ‘gpgme_get_sender’ returns the current sender address
2299 from the context, or NULL if none was set. The returned value is
2300 valid as long as the CTX is valid and ‘gpgme_set_sender’ has not
2304 File: gpgme.info, Node: ASCII Armor, Next: Text Mode, Prev: Setting the Sender, Up: Context Attributes
2309 -- Function: void gpgme_set_armor (gpgme_ctx_t CTX, int YES)
2310 The function ‘gpgme_set_armor’ specifies if the output should be
2311 ASCII armored. By default, output is not ASCII armored.
2313 ASCII armored output is disabled if YES is zero, and enabled
2316 -- Function: int gpgme_get_armor (gpgme_ctx_t CTX)
2317 The function ‘gpgme_get_armor’ returns 1 if the output is ASCII
2318 armored, and ‘0’ if it is not, or if CTX is not a valid pointer.
2321 File: gpgme.info, Node: Text Mode, Next: Offline Mode, Prev: ASCII Armor, Up: Context Attributes
2326 -- Function: void gpgme_set_textmode (gpgme_ctx_t CTX, int YES)
2327 The function ‘gpgme_set_textmode’ specifies if canonical text mode
2328 should be used. By default, text mode is not used.
2330 Text mode is for example used for the RFC2015 signatures; note that
2331 the updated RFC 3156 mandates that the mail user agent does some
2332 preparations so that text mode is not needed anymore.
2334 This option is only relevant to the OpenPGP crypto engine, and
2335 ignored by all other engines.
2337 Canonical text mode is disabled if YES is zero, and enabled
2340 -- Function: int gpgme_get_textmode (gpgme_ctx_t CTX)
2341 The function ‘gpgme_get_textmode’ returns 1 if canonical text mode
2342 is enabled, and ‘0’ if it is not, or if CTX is not a valid pointer.
2345 File: gpgme.info, Node: Offline Mode, Next: Pinentry Mode, Prev: Text Mode, Up: Context Attributes
2350 -- Function: void gpgme_set_offline (gpgme_ctx_t CTX, int YES)
2351 The function ‘gpgme_set_offline’ specifies if offline mode should
2352 be used. By default, offline mode is not used.
2354 The offline mode specifies if dirmngr should be used to do
2355 additional validation that might require connections to external
2356 services. (e.g. CRL / OCSP checks).
2358 Offline mode only affects the keylist mode
2359 ‘GPGME_KEYLIST_MODE_VALIDATE’ and is only relevant to the CMS
2360 crypto engine. Offline mode is ignored otherwise.
2362 This option may be extended in the future to completely disable the
2363 use of dirmngr for any engine.
2365 Offline mode is disabled if YES is zero, and enabled otherwise.
2367 -- Function: int gpgme_get_offline (gpgme_ctx_t CTX)
2368 The function ‘gpgme_get_offline’ returns 1 if offline mode is
2369 enabled, and ‘0’ if it is not, or if CTX is not a valid pointer.
2372 File: gpgme.info, Node: Pinentry Mode, Next: Included Certificates, Prev: Offline Mode, Up: Context Attributes
2377 -- Function: gpgme_error_t gpgme_set_pinentry_mode (gpgme_ctx_t CTX,
2378 gpgme_pinentry_mode_t MODE) The function ‘gpgme_set_pinentry_mode’
2379 specifies the pinentry mode to be used.
2381 For GnuPG >= 2.1 this option is required to be set to
2382 ‘GPGME_PINENTRY_MODE_LOOPBACK’ to enable the passphrase callback
2383 mechanism in GPGME through ‘gpgme_set_passphrase_cb’.
2385 -- Function: gpgme_pinentry_mode_t gpgme_get_pinentry_mode
2387 The function ‘gpgme_get_pinenty_mode’ returns the mode set for the
2390 -- Data type: enum gpgme_pinentry_mode_t
2391 The ‘gpgme_minentry_mode_t’ type specifies the set of possible
2392 pinentry modes that are supported by GPGME if GnuPG >= 2.1 is used.
2393 The following modes are supported:
2395 ‘GPGME_PINENTRY_MODE_DEFAULT’
2396 Use the default of the agent, which is ask.
2398 ‘GPGME_PINENTRY_MODE_ASK’
2399 Force the use of the Pinentry.
2401 ‘GPGME_PINENTRY_MODE_CANCEL’
2402 Emulate use of Pinentry’s cancel button.
2404 ‘GPGME_PINENTRY_MODE_ERROR’
2405 Return a Pinentry error ‘No Pinentry’.
2407 ‘GPGME_PINENTRY_MODE_LOOPBACK’
2408 Redirect Pinentry queries to the caller. This enables the use
2409 of ‘gpgme_set_passphrase_cb’ whis pinentry queries redirected
2412 Note: This mode requires ‘allow-loopback-pinentry’ to be
2413 enabled in the ‘gpg-agent.conf’ or an agent started with that
2417 File: gpgme.info, Node: Included Certificates, Next: Key Listing Mode, Prev: Pinentry Mode, Up: Context Attributes
2419 7.4.8 Included Certificates
2420 ---------------------------
2422 -- Function: void gpgme_set_include_certs (gpgme_ctx_t CTX,
2424 The function ‘gpgme_set_include_certs’ specifies how many
2425 certificates should be included in an S/MIME signed message. By
2426 default, only the sender’s certificate is included. The possible
2427 values of NR_OF_CERTS are:
2429 ‘GPGME_INCLUDE_CERTS_DEFAULT’
2430 Fall back to the default of the crypto backend. This is the
2433 Include all certificates except the root certificate.
2435 Include all certificates.
2437 Include no certificates.
2439 Include the sender’s certificate only.
2441 Include the first n certificates of the certificates path,
2442 starting from the sender’s certificate. The number ‘n’ must
2445 Values of NR_OF_CERTS smaller than -2 are undefined.
2447 This option is only relevant to the CMS crypto engine, and ignored
2448 by all other engines.
2450 -- Function: int gpgme_get_include_certs (gpgme_ctx_t CTX)
2451 The function ‘gpgme_get_include_certs’ returns the number of
2452 certificates to include into an S/MIME signed message.
2455 File: gpgme.info, Node: Key Listing Mode, Next: Passphrase Callback, Prev: Included Certificates, Up: Context Attributes
2457 7.4.9 Key Listing Mode
2458 ----------------------
2460 -- Function: gpgme_error_t gpgme_set_keylist_mode (gpgme_ctx_t CTX,
2461 gpgme_keylist_mode_t MODE)
2462 The function ‘gpgme_set_keylist_mode’ changes the default behaviour
2463 of the key listing functions. The value in MODE is a bitwise-or
2464 combination of one or multiple of the following bit values:
2466 ‘GPGME_KEYLIST_MODE_LOCAL’
2467 The ‘GPGME_KEYLIST_MODE_LOCAL’ symbol specifies that the local
2468 keyring should be searched for keys in the keylisting
2469 operation. This is the default.
2471 ‘GPGME_KEYLIST_MODE_EXTERN’
2472 The ‘GPGME_KEYLIST_MODE_EXTERN’ symbol specifies that an
2473 external source should be searched for keys in the keylisting
2474 operation. The type of external source is dependant on the
2475 crypto engine used and whether it is combined with
2476 ‘GPGME_KEYLIST_MODE_LOCAL’. For example, it can be a remote
2477 keyserver or LDAP certificate server.
2479 ‘GPGME_KEYLIST_MODE_SIGS’
2480 The ‘GPGME_KEYLIST_MODE_SIGS’ symbol specifies that the key
2481 signatures should be included in the listed keys.
2483 ‘GPGME_KEYLIST_MODE_SIG_NOTATIONS’
2484 The ‘GPGME_KEYLIST_MODE_SIG_NOTATIONS’ symbol specifies that
2485 the signature notations on key signatures should be included
2486 in the listed keys. This only works if
2487 ‘GPGME_KEYLIST_MODE_SIGS’ is also enabled.
2489 ‘GPGME_KEYLIST_MODE_WITH_TOFU’
2490 The ‘GPGME_KEYLIST_MODE_WITH_TOFU’ symbol specifies that
2491 information pertaining to the TOFU trust model should be
2492 included in the listed keys.
2494 ‘GPGME_KEYLIST_MODE_WITH_SECRET’
2495 The ‘GPGME_KEYLIST_MODE_WITH_SECRET’ returns information about
2496 the presence of a corresponding secret key in a public key
2497 listing. A public key listing with this mode is slower than a
2498 standard listing but can be used instead of a second run to
2499 list the secret keys. This is only supported for GnuPG
2502 ‘GPGME_KEYLIST_MODE_EPHEMERAL’
2503 The ‘GPGME_KEYLIST_MODE_EPHEMERAL’ symbol specifies that keys
2504 flagged as ephemeral are included in the listing.
2506 ‘GPGME_KEYLIST_MODE_VALIDATE’
2507 The ‘GPGME_KEYLIST_MODE_VALIDATE’ symbol specifies that the
2508 backend should do key or certificate validation and not just
2509 get the validity information from an internal cache. This
2510 might be an expensive operation and is in general not useful.
2511 Currently only implemented for the S/MIME backend and ignored
2514 At least one of ‘GPGME_KEYLIST_MODE_LOCAL’ and
2515 ‘GPGME_KEYLIST_MODE_EXTERN’ must be specified. For future binary
2516 compatibility, you should get the current mode with
2517 ‘gpgme_get_keylist_mode’ and modify it by setting or clearing the
2518 appropriate bits, and then using that calculated value in the
2519 ‘gpgme_set_keylisting_mode’ operation. This will leave all other
2520 bits in the mode value intact (in particular those that are not
2521 used in the current version of the library).
2523 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the mode
2524 could be set correctly, and ‘GPG_ERR_INV_VALUE’ if CTX is not a
2525 valid pointer or MODE is not a valid mode.
2527 -- Function: gpgme_keylist_mode_t gpgme_get_keylist_mode
2529 The function ‘gpgme_get_keylist_mode’ returns the current key
2530 listing mode of the context CTX. This value can then be modified
2531 and used in a subsequent ‘gpgme_set_keylist_mode’ operation to only
2532 affect the desired bits (and leave all others intact).
2534 The function returns 0 if CTX is not a valid pointer, and the
2535 current mode otherwise. Note that 0 is not a valid mode value.
2538 File: gpgme.info, Node: Passphrase Callback, Next: Progress Meter Callback, Prev: Key Listing Mode, Up: Context Attributes
2540 7.4.10 Passphrase Callback
2541 --------------------------
2543 -- Data type: gpgme_error_t (*gpgme_passphrase_cb_t)(void *HOOK, const
2544 char *UID_HINT, const char *PASSPHRASE_INFO, int PREV_WAS_BAD,
2546 The ‘gpgme_passphrase_cb_t’ type is the type of functions usable as
2547 passphrase callback function.
2549 The argument UID_HINT might contain a string that gives an
2550 indication for which user ID the passphrase is required. If this
2551 is not available, or not applicable (in the case of symmetric
2552 encryption, for example), UID_HINT will be ‘NULL’.
2554 The argument PASSPHRASE_INFO, if not ‘NULL’, will give further
2555 information about the context in which the passphrase is required.
2556 This information is engine and operation specific.
2558 If this is the repeated attempt to get the passphrase, because
2559 previous attempts failed, then PREV_WAS_BAD is 1, otherwise it will
2562 The user must write the passphrase, followed by a newline
2563 character, to the file descriptor FD. The function
2564 ‘gpgme_io_writen’ should be used for the write operation. Note
2565 that if the user returns 0 to indicate success, the user must at
2566 least write a newline character before returning from the callback.
2568 If an error occurs, return the corresponding ‘gpgme_error_t’ value.
2569 You can use the error code ‘GPG_ERR_CANCELED’ to abort the
2570 operation. Otherwise, return ‘0’.
2572 -- Function: void gpgme_set_passphrase_cb (gpgme_ctx_t CTX,
2573 gpgme_passphrase_cb_t PASSFUNC, void *HOOK_VALUE)
2574 The function ‘gpgme_set_passphrase_cb’ sets the function that is
2575 used when a passphrase needs to be provided by the user to
2576 PASSFUNC. The function PASSFUNC needs to implemented by the user,
2577 and whenever it is called, it is called with its first argument
2578 being HOOK_VALUE. By default, no passphrase callback function is
2581 Not all crypto engines require this callback to retrieve the
2582 passphrase. It is better if the engine retrieves the passphrase
2583 from a trusted agent (a daemon process), rather than having each
2584 user to implement their own passphrase query. Some engines do not
2585 even support an external passphrase callback at all, in this case
2586 the error code ‘GPG_ERR_NOT_SUPPORTED’ is returned.
2588 For GnuPG >= 2.1 the pinentry mode has to be set to
2589 ‘GPGME_PINENTRY_MODE_LOOPBACK’ to enable the passphrase callback.
2590 See ‘gpgme_set_pinentry_mode’.
2592 The user can disable the use of a passphrase callback function by
2593 calling ‘gpgme_set_passphrase_cb’ with PASSFUNC being ‘NULL’.
2595 -- Function: void gpgme_get_passphrase_cb (gpgme_ctx_t CTX,
2596 gpgme_passphrase_cb_t *PASSFUNC, void **HOOK_VALUE)
2597 The function ‘gpgme_get_passphrase_cb’ returns the function that is
2598 used when a passphrase needs to be provided by the user in
2599 *PASSFUNC, and the first argument for this function in *HOOK_VALUE.
2600 If no passphrase callback is set, or CTX is not a valid pointer,
2601 ‘NULL’ is returned in both variables.
2603 PASSFUNC or HOOK_VALUE can be ‘NULL’. In this case, the
2604 corresponding value will not be returned.
2607 File: gpgme.info, Node: Progress Meter Callback, Next: Status Message Callback, Prev: Passphrase Callback, Up: Context Attributes
2609 7.4.11 Progress Meter Callback
2610 ------------------------------
2612 -- Data type: void (*gpgme_progress_cb_t)(void *HOOK, const char *WHAT,
2613 int TYPE, int CURRENT, int TOTAL)
2614 The ‘gpgme_progress_cb_t’ type is the type of functions usable as
2615 progress callback function.
2617 The arguments are specific to the crypto engine. More information
2618 about the progress information returned from the GnuPG engine can
2619 be found in the GnuPG source code in the file ‘doc/DETAILS’ in the
2622 -- Function: void gpgme_set_progress_cb (gpgme_ctx_t CTX,
2623 gpgme_progress_cb_t PROGFUNC, void *HOOK_VALUE)
2624 The function ‘gpgme_set_progress_cb’ sets the function that is used
2625 when progress information about a cryptographic operation is
2626 available. The function PROGFUNC needs to implemented by the user,
2627 and whenever it is called, it is called with its first argument
2628 being HOOK_VALUE. By default, no progress callback function is
2631 Setting a callback function allows an interactive program to
2632 display progress information about a long operation to the user.
2634 The user can disable the use of a progress callback function by
2635 calling ‘gpgme_set_progress_cb’ with PROGFUNC being ‘NULL’.
2637 -- Function: void gpgme_get_progress_cb (gpgme_ctx_t CTX,
2638 gpgme_progress_cb_t *PROGFUNC, void **HOOK_VALUE)
2639 The function ‘gpgme_get_progress_cb’ returns the function that is
2640 used to inform the user about the progress made in *PROGFUNC, and
2641 the first argument for this function in *HOOK_VALUE. If no
2642 progress callback is set, or CTX is not a valid pointer, ‘NULL’ is
2643 returned in both variables.
2645 PROGFUNC or HOOK_VALUE can be ‘NULL’. In this case, the
2646 corresponding value will not be returned.
2649 File: gpgme.info, Node: Status Message Callback, Next: Locale, Prev: Progress Meter Callback, Up: Context Attributes
2651 7.4.12 Status Message Callback
2652 ------------------------------
2654 -- Data type: gpgme_error_t (*gpgme_status_cb_t)(void *HOOK, const char
2655 *KEYWORD, const char *ARGS)
2656 The ‘gpgme_status_cb_t’ type is the type of function usable as a
2657 status message callback function.
2659 The argument KEYWORD is the name of the status message while the
2660 ARGS argument contains any arguments for the status message.
2662 If an error occurs, return the corresponding ‘gpgme_error_t’ value.
2663 Otherwise, return ‘0’.
2665 -- Function: void gpgme_set_status_cb (gpgme_ctx_t CTX,
2666 gpgme_status_cb_t STATUSFUNC, void *HOOK_VALUE)
2667 The function ‘gpgme_set_status_cb’ sets the function that is used
2668 when a status message is received from gpg to STATUSFUNC. The
2669 function STATUSFUNC needs to be implemented by the user, and
2670 whenever it is called, it is called with its first argument being
2671 HOOK_VALUE. By default, no status message callback function is
2674 The user can disable the use of a status message callback function
2675 by calling ‘gpgme_set_status_cb’ with STATUSFUNC being ‘NULL’.
2677 -- Function: void gpgme_get_status_cb (gpgme_ctx_t CTX,
2678 gpgme_status_cb_t *STATUSFUNC, void **HOOK_VALUE)
2679 The function ‘gpgme_get_status_cb’ returns the function that is
2680 used to process status messages from gpg in *STATUSFUNC, and the
2681 first argument for this function in *HOOK_VALUE. If no status
2682 message callback is set, or CTX is not a valid pointer, ‘NULL’ is
2683 returned in both variables.
2685 -- Function: gpgme_error_t gpgme_set_ctx_flag (gpgme_ctx_t CTX,
2686 const char *NAME, const char *VALUE)
2688 Some minor properties of the context can be controlled with flags
2689 set by this function. The properties are identified by the
2690 following values for NAME:
2693 Using a VALUE of "1" the status callback set by
2694 gpgme_set_status_cb returns all status lines with the
2695 exception of PROGRESS lines. With the default of "0" the
2696 status callback is only called in certain situations.
2699 Setting the VALUE to "1" returns human readable strings in a
2700 raw format. For example the non breaking space characters
2701 ("~") will not be removed from the ‘description’ field of the
2702 ‘gpgme_tofu_info_t’ object.
2704 ‘"export-session-key"’
2705 Using a VALUE of "1" specifies that the context should try to
2706 export the symmetric session key when decrypting data. By
2707 default, or when using an empty string or "0" for VALUE,
2708 session keys are not exported.
2710 ‘"override-session-key"’
2711 The string given in VALUE is passed to the GnuPG engine to
2712 override the session key for decryption. The format of that
2713 session key is specific to GnuPG and can be retrieved during a
2714 decrypt operation when the context flag "export-session-key"
2715 is enabled. Please be aware that using this feature with
2716 GnuPG < 2.1.16 will leak the session key on many platforms via
2719 This function returns ‘0’ on success.
2721 -- Function: const char * gpgme_get_ctx_flag (gpgme_ctx_t CTX,
2724 The value of flags settable by ‘gpgme_set_ctx_flag’ can be
2725 retrieved by this function. If NAME is unknown the function
2726 returns ‘NULL’. For boolean flags an empty string is returned for
2727 False and the string "1" is returned for True; either atoi(3) or a
2728 test for an empty string can be used to get the boolean value.
2731 File: gpgme.info, Node: Locale, Prev: Status Message Callback, Up: Context Attributes
2736 A locale setting can be associated with a context. This locale is
2737 passed to the crypto engine, and used for applications like the PIN
2738 entry, which is displayed to the user when entering a passphrase is
2741 The default locale is used to initialize the locale setting of all
2742 contexts created afterwards.
2744 -- Function: gpgme_error_t gpgme_set_locale (gpgme_ctx_t CTX,
2745 int CATEGORY, const char *VALUE)
2746 The function ‘gpgme_set_locale’ sets the locale of the context CTX,
2747 or the default locale if CTX is a null pointer.
2749 The locale settings that should be changed are specified by
2750 CATEGORY. Supported categories are ‘LC_CTYPE’, ‘LC_MESSAGES’, and
2751 ‘LC_ALL’, which is a wildcard you can use if you want to change all
2752 the categories at once.
2754 The value to be used for the locale setting is VALUE, which will be
2755 copied to GPGME’s internal data structures. VALUE can be a null
2756 pointer, which disables setting the locale, and will make PIN entry
2757 and other applications use their default setting, which is usually
2760 Note that the settings are only used if the application runs on a
2761 text terminal, and that the settings should fit the configuration
2762 of the output terminal. Normally, it is sufficient to initialize
2763 the default value at startup.
2765 The function returns an error if not enough memory is available.
2768 File: gpgme.info, Node: Key Management, Next: Trust Item Management, Prev: Context Attributes, Up: Contexts
2773 Some of the cryptographic operations require that recipients or signers
2774 are specified. This is always done by specifying the respective keys
2775 that should be used for the operation. The following section describes
2776 how such keys can be selected and manipulated.
2780 * Key objects:: Description of the key structures.
2781 * Listing Keys:: Browsing the list of available keys.
2782 * Information About Keys:: Requesting detailed information about keys.
2783 * Manipulating Keys:: Operations on keys.
2784 * Generating Keys:: Creating new key pairs.
2785 * Signing Keys:: Adding key signatures to public keys.
2786 * Exporting Keys:: Retrieving key data from the key ring.
2787 * Importing Keys:: Adding keys to the key ring.
2788 * Deleting Keys:: Removing keys from the key ring.
2789 * Changing Passphrases:: Change the passphrase of a key.
2790 * Changing TOFU Data:: Changing data pertaining to TOFU.
2791 * Advanced Key Editing:: Advanced key edit operation.
2794 File: gpgme.info, Node: Key objects, Next: Listing Keys, Up: Key Management
2799 The keys are represented in GPGME by structures which may only be read
2800 by the application but never be allocated or changed. They are valid as
2801 long as the key object itself is valid.
2803 -- Data type: gpgme_key_t
2805 The ‘gpgme_key_t’ type is a pointer to a key object. It has the
2808 ‘gpgme_keylist_mode_t keylist_mode’
2809 The keylist mode that was active when the key was retrieved.
2811 ‘unsigned int revoked : 1’
2812 This is true if the key is revoked.
2814 ‘unsigned int expired : 1’
2815 This is true if the key is expired.
2817 ‘unsigned int disabled : 1’
2818 This is true if the key is disabled.
2820 ‘unsigned int invalid : 1’
2821 This is true if the key is invalid. This might have several
2822 reasons, for a example for the S/MIME backend, it will be set
2823 during key listings if the key could not be validated due to
2824 missing certificates or unmatched policies.
2826 ‘unsigned int can_encrypt : 1’
2827 This is true if the key (ie one of its subkeys) can be used
2830 ‘unsigned int can_sign : 1’
2831 This is true if the key (ie one of its subkeys) can be used to
2832 create data signatures.
2834 ‘unsigned int can_certify : 1’
2835 This is true if the key (ie one of its subkeys) can be used to
2836 create key certificates.
2838 ‘unsigned int can_authenticate : 1’
2839 This is true if the key (ie one of its subkeys) can be used
2842 ‘unsigned int is_qualified : 1’
2843 This is true if the key can be used for qualified signatures
2844 according to local government regulations.
2846 ‘unsigned int secret : 1’
2847 This is true if the key is a secret key. Note, that this will
2848 always be true even if the corresponding subkey flag may be
2849 false (offline/stub keys). This is only set if a listing of
2850 secret keys has been requested or if
2851 ‘GPGME_KEYLIST_MODE_WITH_SECRET’ is active.
2853 ‘gpgme_protocol_t protocol’
2854 This is the protocol supported by this key.
2856 ‘char *issuer_serial’
2857 If ‘protocol’ is ‘GPGME_PROTOCOL_CMS’, then this is the issuer
2861 If ‘protocol’ is ‘GPGME_PROTOCOL_CMS’, then this is the issuer
2865 If ‘protocol’ is ‘GPGME_PROTOCOL_CMS’, then this is the chain
2866 ID, which can be used to built the certificate chain.
2868 ‘gpgme_validity_t owner_trust’
2869 If ‘protocol’ is ‘GPGME_PROTOCOL_OpenPGP’, then this is the
2872 ‘gpgme_subkey_t subkeys’
2873 This is a linked list with the subkeys of the key. The first
2874 subkey in the list is the primary key and usually available.
2876 ‘gpgme_user_id_t uids’
2877 This is a linked list with the user IDs of the key. The first
2878 user ID in the list is the main (or primary) user ID.
2881 This field gives the fingerprint of the primary key. Note
2882 that this is a copy of the fingerprint of the first subkey.
2883 For an incomplete key (for example from a verification result)
2884 a subkey may be missing but this field may be set
2887 -- Data type: gpgme_subkey_t
2889 The ‘gpgme_subkey_t’ type is a pointer to a subkey structure.
2890 Subkeys are one component of a ‘gpgme_key_t’ object. In fact,
2891 subkeys are those parts that contains the real information about
2892 the individual cryptographic keys that belong to the same key
2893 object. One ‘gpgme_key_t’ can contain several subkeys. The first
2894 subkey in the linked list is also called the primary key.
2896 The subkey structure has the following members:
2898 ‘gpgme_subkey_t next’
2899 This is a pointer to the next subkey structure in the linked
2900 list, or ‘NULL’ if this is the last element.
2902 ‘unsigned int revoked : 1’
2903 This is true if the subkey is revoked.
2905 ‘unsigned int expired : 1’
2906 This is true if the subkey is expired.
2908 ‘unsigned int disabled : 1’
2909 This is true if the subkey is disabled.
2911 ‘unsigned int invalid : 1’
2912 This is true if the subkey is invalid.
2914 ‘unsigned int can_encrypt : 1’
2915 This is true if the subkey can be used for encryption.
2917 ‘unsigned int can_sign : 1’
2918 This is true if the subkey can be used to create data
2921 ‘unsigned int can_certify : 1’
2922 This is true if the subkey can be used to create key
2925 ‘unsigned int can_authenticate : 1’
2926 This is true if the subkey can be used for authentication.
2928 ‘unsigned int is_qualified : 1’
2929 This is true if the subkey can be used for qualified
2930 signatures according to local government regulations.
2932 ‘unsigned int secret : 1’
2933 This is true if the subkey is a secret key. Note that it will
2934 be false if the key is actually a stub key; i.e. a secret key
2935 operation is currently not possible (offline-key). This is
2936 only set if a listing of secret keys has been requested or if
2937 ‘GPGME_KEYLIST_MODE_WITH_SECRET’ is active.
2939 ‘gpgme_pubkey_algo_t pubkey_algo’
2940 This is the public key algorithm supported by this subkey.
2942 ‘unsigned int length’
2943 This is the length of the subkey (in bits).
2946 This is the key ID of the subkey in hexadecimal digits.
2949 This is the fingerprint of the subkey in hexadecimal digits,
2953 The keygrip of the subkey in hex digit form or ‘NULL’ if not
2956 ‘long int timestamp’
2957 This is the creation timestamp of the subkey. This is -1 if
2958 the timestamp is invalid, and 0 if it is not available.
2961 This is the expiration timestamp of the subkey, or 0 if the
2962 subkey does not expire.
2964 ‘unsigned int is_cardkey : 1’
2965 True if the secret key is stored on a smart card.
2968 The serial number of a smart card holding this key or ‘NULL’.
2971 For ECC algorithms the name of the curve.
2973 -- Data type: gpgme_user_id_t
2975 A user ID is a component of a ‘gpgme_key_t’ object. One key can
2976 have many user IDs. The first one in the list is the main (or
2979 The user ID structure has the following members.
2981 ‘gpgme_user_id_t next’
2982 This is a pointer to the next user ID structure in the linked
2983 list, or ‘NULL’ if this is the last element.
2985 ‘unsigned int revoked : 1’
2986 This is true if the user ID is revoked.
2988 ‘unsigned int invalid : 1’
2989 This is true if the user ID is invalid.
2991 ‘gpgme_validity_t validity’
2992 This specifies the validity of the user ID.
2995 This is the user ID string.
2998 This is the name component of ‘uid’, if available.
3001 This is the comment component of ‘uid’, if available.
3004 This is the email component of ‘uid’, if available.
3007 The mail address (addr-spec from RFC-5322) of the user ID
3008 string. This is general the same as the ‘email’ part of this
3009 structure but might be slightly different. If no mail address
3010 is available ‘NULL’ is stored.
3012 ‘gpgme_tofu_info_t tofu’
3013 If not ‘NULL’ information from the TOFU database pertaining to
3016 ‘gpgme_key_sig_t signatures’
3017 This is a linked list with the signatures on this user ID.
3019 -- Data type: gpgme_key_sig_t
3021 The ‘gpgme_key_sig_t’ type is a pointer to a key signature
3022 structure. Key signatures are one component of a ‘gpgme_key_t’
3023 object, and validate user IDs on the key in the OpenPGP protocol.
3025 The signatures on a key are only available if the key was retrieved
3026 via a listing operation with the ‘GPGME_KEYLIST_MODE_SIGS’ mode
3027 enabled, because it can be expensive to retrieve all signatures of
3030 The signature notations on a key signature are only available if
3031 the key was retrieved via a listing operation with the
3032 ‘GPGME_KEYLIST_MODE_SIG_NOTATIONS’ mode enabled, because it can be
3033 expensive to retrieve all signature notations.
3035 The key signature structure has the following members:
3037 ‘gpgme_key_sig_t next’
3038 This is a pointer to the next key signature structure in the
3039 linked list, or ‘NULL’ if this is the last element.
3041 ‘unsigned int revoked : 1’
3042 This is true if the key signature is a revocation signature.
3044 ‘unsigned int expired : 1’
3045 This is true if the key signature is expired.
3047 ‘unsigned int invalid : 1’
3048 This is true if the key signature is invalid.
3050 ‘unsigned int exportable : 1’
3051 This is true if the key signature is exportable.
3053 ‘gpgme_pubkey_algo_t pubkey_algo’
3054 This is the public key algorithm used to create the signature.
3057 This is the key ID of the key (in hexadecimal digits) used to
3058 create the signature.
3060 ‘long int timestamp’
3061 This is the creation timestamp of the key signature. This is
3062 -1 if the timestamp is invalid, and 0 if it is not available.
3065 This is the expiration timestamp of the key signature, or 0 if
3066 the key signature does not expire.
3068 ‘gpgme_error_t status’
3069 This is the status of the signature and has the same meaning
3070 as the member of the same name in a ‘gpgme_signature_t’
3073 ‘unsigned int sig_class’
3074 This specifies the signature class of the key signature. The
3075 meaning is specific to the crypto engine.
3078 This is the main user ID of the key used to create the
3082 This is the name component of ‘uid’, if available.
3085 This is the comment component of ‘uid’, if available.
3088 This is the email component of ‘uid’, if available.
3090 ‘gpgme_sig_notation_t notations’
3091 This is a linked list with the notation data and policy URLs.
3094 File: gpgme.info, Node: Listing Keys, Next: Information About Keys, Prev: Key objects, Up: Key Management
3099 -- Function: gpgme_error_t gpgme_op_keylist_start (gpgme_ctx_t CTX,
3100 const char *PATTERN, int SECRET_ONLY)
3101 The function ‘gpgme_op_keylist_start’ initiates a key listing
3102 operation inside the context CTX. It sets everything up so that
3103 subsequent invocations of ‘gpgme_op_keylist_next’ return the keys
3106 If PATTERN is ‘NULL’, all available keys are returned. Otherwise,
3107 PATTERN contains an engine specific expression that is used to
3108 limit the list to all keys matching the pattern. Note that the
3109 total length of the pattern is restricted to an engine-specific
3110 maximum (a couple of hundred characters are usually accepted). The
3111 pattern should be used to restrict the search to a certain common
3112 name or user, not to list many specific keys at once by listing
3113 their fingerprints or key IDs.
3115 If SECRET_ONLY is not ‘0’, the list is restricted to secret keys
3118 The context will be busy until either all keys are received (and
3119 ‘gpgme_op_keylist_next’ returns ‘GPG_ERR_EOF’), or
3120 ‘gpgme_op_keylist_end’ is called to finish the operation.
3122 The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX is
3123 not a valid pointer, and passes through any errors that are
3124 reported by the crypto engine support routines.
3126 -- Function: gpgme_error_t gpgme_op_keylist_ext_start (gpgme_ctx_t CTX,
3127 const char *PATTERN[], int SECRET_ONLY, int RESERVED)
3128 The function ‘gpgme_op_keylist_ext_start’ initiates an extended key
3129 listing operation inside the context CTX. It sets everything up so
3130 that subsequent invocations of ‘gpgme_op_keylist_next’ return the
3133 If PATTERN or *PATTERN is ‘NULL’, all available keys are returned.
3134 Otherwise, PATTERN is a ‘NULL’ terminated array of strings that are
3135 used to limit the list to all keys matching at least one of the
3136 patterns verbatim. Note that the total length of all patterns is
3137 restricted to an engine-specific maximum (the exact limit also
3138 depends on the number of patterns and amount of quoting required,
3139 but a couple of hundred characters are usually accepted). Patterns
3140 should be used to restrict the search to a certain common name or
3141 user, not to list many specific keys at once by listing their
3142 fingerprints or key IDs.
3144 If SECRET_ONLY is not ‘0’, the list is restricted to secret keys
3147 The value of RESERVED must be ‘0’.
3149 The context will be busy until either all keys are received (and
3150 ‘gpgme_op_keylist_next’ returns ‘GPG_ERR_EOF’), or
3151 ‘gpgme_op_keylist_end’ is called to finish the operation.
3153 The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX is
3154 not a valid pointer, and passes through any errors that are
3155 reported by the crypto engine support routines.
3157 -- Function: gpgme_error_t gpgme_op_keylist_next (gpgme_ctx_t CTX,
3159 The function ‘gpgme_op_keylist_next’ returns the next key in the
3160 list created by a previous ‘gpgme_op_keylist_start’ operation in
3161 the context CTX. The key will have one reference for the user.
3162 *Note Manipulating Keys::.
3164 This is the only way to get at ‘gpgme_key_t’ objects in GPGME.
3166 If the last key in the list has already been returned,
3167 ‘gpgme_op_keylist_next’ returns ‘GPG_ERR_EOF’.
3169 The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX or
3170 R_KEY is not a valid pointer, and ‘GPG_ERR_ENOMEM’ if there is not
3171 enough memory for the operation.
3173 -- Function: gpgme_error_t gpgme_op_keylist_end (gpgme_ctx_t CTX)
3174 The function ‘gpgme_op_keylist_end’ ends a pending key list
3175 operation in the context CTX.
3177 After the operation completed successfully, the result of the key
3178 listing operation can be retrieved with ‘gpgme_op_keylist_result’.
3180 The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX is
3181 not a valid pointer, and ‘GPG_ERR_ENOMEM’ if at some time during
3182 the operation there was not enough memory available.
3184 The following example illustrates how all keys containing a certain
3185 string (‘g10code’) can be listed with their key ID and the name and
3186 e-mail address of the main user ID:
3190 gpgme_error_t err = gpgme_new (&ctx);
3194 err = gpgme_op_keylist_start (ctx, "g10code", 0);
3197 err = gpgme_op_keylist_next (ctx, &key);
3200 printf ("%s:", key->subkeys->keyid);
3201 if (key->uids && key->uids->name)
3202 printf (" %s", key->uids->name);
3203 if (key->uids && key->uids->email)
3204 printf (" <%s>", key->uids->email);
3206 gpgme_key_release (key);
3208 gpgme_release (ctx);
3210 if (gpg_err_code (err) != GPG_ERR_EOF)
3212 fprintf (stderr, "can not list keys: %s\n", gpgme_strerror (err));
3216 -- Data type: gpgme_keylist_result_t
3217 This is a pointer to a structure used to store the result of a
3218 ‘gpgme_op_keylist_*’ operation. After successfully ending a key
3219 listing operation, you can retrieve the pointer to the result with
3220 ‘gpgme_op_keylist_result’. The structure contains the following
3223 ‘unsigned int truncated : 1’
3224 This is true if the crypto backend had to truncate the result,
3225 and less than the desired keys could be listed.
3227 -- Function: gpgme_keylist_result_t gpgme_op_keylist_result
3229 The function ‘gpgme_op_keylist_result’ returns a
3230 ‘gpgme_keylist_result_t’ pointer to a structure holding the result
3231 of a ‘gpgme_op_keylist_*’ operation. The pointer is only valid if
3232 the last operation on the context was a key listing operation, and
3233 if this operation finished successfully. The returned pointer is
3234 only valid until the next operation is started on the context.
3236 In a simple program, for which a blocking operation is acceptable,
3237 the following function can be used to retrieve a single key.
3239 -- Function: gpgme_error_t gpgme_get_key (gpgme_ctx_t CTX,
3240 const char *FPR, gpgme_key_t *R_KEY, int SECRET)
3241 The function ‘gpgme_get_key’ gets the key with the fingerprint (or
3242 key ID) FPR from the crypto backend and return it in R_KEY. If
3243 SECRET is true, get the secret key. The currently active keylist
3244 mode is used to retrieve the key. The key will have one reference
3247 If the key is not found in the keyring, ‘gpgme_get_key’ returns the
3248 error code ‘GPG_ERR_EOF’ and *R_KEY will be set to ‘NULL’.
3250 The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX or
3251 R_KEY is not a valid pointer or FPR is not a fingerprint or key ID,
3252 ‘GPG_ERR_AMBIGUOUS_NAME’ if the key ID was not a unique specifier
3253 for a key, and ‘GPG_ERR_ENOMEM’ if at some time during the
3254 operation there was not enough memory available.
3257 File: gpgme.info, Node: Information About Keys, Next: Manipulating Keys, Prev: Listing Keys, Up: Key Management
3259 7.5.3 Information About Keys
3260 ----------------------------
3262 Please see the beginning of this section for more information about
3263 ‘gpgme_key_t’ objects.
3265 -- Data type: gpgme_validity_t
3266 The ‘gpgme_validity_t’ type is used to specify the validity of a
3267 user ID in a key. The following validities are defined:
3269 ‘GPGME_VALIDITY_UNKNOWN’
3270 The user ID is of unknown validity. The string representation
3271 of this validity is “?”.
3273 ‘GPGME_VALIDITY_UNDEFINED’
3274 The validity of the user ID is undefined. The string
3275 representation of this validity is “q”.
3277 ‘GPGME_VALIDITY_NEVER’
3278 The user ID is never valid. The string representation of this
3281 ‘GPGME_VALIDITY_MARGINAL’
3282 The user ID is marginally valid. The string representation of
3283 this validity is “m”.
3285 ‘GPGME_VALIDITY_FULL’
3286 The user ID is fully valid. The string representation of this
3289 ‘GPGME_VALIDITY_ULTIMATE’
3290 The user ID is ultimately valid. The string representation of
3291 this validity is “u”.
3294 File: gpgme.info, Node: Manipulating Keys, Next: Generating Keys, Prev: Information About Keys, Up: Key Management
3296 7.5.4 Manipulating Keys
3297 -----------------------
3299 -- Function: void gpgme_key_ref (gpgme_key_t KEY)
3300 The function ‘gpgme_key_ref’ acquires an additional reference for
3303 -- Function: void gpgme_key_unref (gpgme_key_t KEY)
3304 The function ‘gpgme_key_unref’ releases a reference for the key
3305 KEY. If this was the last reference, the key will be destroyed and
3306 all resources associated to it will be released.
3309 File: gpgme.info, Node: Generating Keys, Next: Signing Keys, Prev: Manipulating Keys, Up: Key Management
3311 7.5.5 Generating Keys
3312 ---------------------
3314 GPGME provides a set of functions to create public key pairs. Most of
3315 these functions require the use of GnuPG 2.1 and later; for older GnuPG
3316 versions the ‘gpgme_op_genkey’ function can be used. Existing code
3317 which wants to update to the new functions or new code which shall
3318 supports older GnuPG versions may try the new functions first and
3319 provide a fallback to the old function if the error code
3320 ‘GPG_ERR_NOT_SUPPORTED’ is received.
3322 -- Function: gpgme_error_t gpgme_op_createkey (gpgme_ctx_t CTX,
3323 const char *USERID, const char *ALGO, unsigned long RESERVED,
3324 unsigned long EXPIRES, gpgme_key_t EXTRAKEY,
3325 unsigned int FLAGS);
3327 The function ‘gpgme_op_createkey’ generates a new key for the
3328 procotol active in the context CTX. As of now this function does
3329 only work for OpenPGP and requires at least version 2.1.13 of
3332 USERID is commonly the mail address associated with the key. GPGME
3333 does not require a specificy syntax but if more than a mail address
3334 is given, RFC-822 style format is suggested. The value is expected
3335 to be in UTF-8 encoding (i.e. no IDN encoding for mail addresses).
3336 This is a required parameter.
3338 ALGO specifies the algorithm for the new key (actually a keypair of
3339 public and private key). For a list of supported algorithms, see
3340 the GnuPG manual. If ALGO is ‘NULL’ or the string "default", the
3341 key is generated using the default algorithm of the engine. If the
3342 string "future-default" is used the engine may use an algorithm
3343 which is planned to be the default in a future release of the
3344 engine; however existing implementation of the protocol may not be
3345 able to already handle such future algorithms. For the OpenPGP
3346 protocol, the specification of a default algorithm, without
3347 requesting a non-default usage via FLAGS, triggers the creation of
3348 a primary key plus a secondary key (subkey).
3350 RESERVED must be set to zero.
3352 EXPIRES can be set to the number of seconds since Epoch of the
3353 desired expiration date in UTC for the new key. Using 0 does not
3354 set an expiration date. Note that this parameter takes an unsigned
3355 long value and not a ‘time_t’ to avoid problems on systems which
3356 use a signed 32 bit ‘time_t’. Note further that the OpenPGP
3357 protocol uses 32 bit values for timestamps and thus can only encode
3358 dates up to the year 2106.
3360 EXTRAKEY is currently not used and must be set to ‘NULL’. A future
3361 version of GPGME may use this parameter to create X.509 keys.
3363 FLAGS can be set to the bit-wise OR of the following flags:
3369 Do not create the key with the default capabilities (key
3370 usage) of the requested algorithm but use those explicitly
3371 given by these flags: “signing”, “encryption”,
3372 “certification”, or “authentication”. The allowed
3373 combinations depend on the algorithm.
3375 If any of these flags are set and a default algorithm has been
3376 selected only one key is created in the case of the OpenPGP
3379 ‘GPGME_CREATE_NOPASSWD’
3380 Request generation of the key without password protection.
3382 ‘GPGME_CREATE_SELFSIGNED’
3383 For an X.509 key do not create a CSR but a self-signed
3384 certificate. This has not yet been implemented.
3386 ‘GPGME_CREATE_NOSTORE’
3387 Do not store the created key in the local key database. This
3388 has not yet been implemented.
3390 ‘GPGME_CREATE_WANTPUB’
3391 ‘GPGME_CREATE_WANTSEC’
3392 Return the public or secret key as part of the result
3393 structure. This has not yet been implemented.
3395 ‘GPGME_CREATE_FORCE’
3396 The engine does not allow the creation of a key with a user ID
3397 already existing in the local key database. This flag can be
3398 used to override this check.
3400 After the operation completed successfully, information about the
3401 created key can be retrieved with ‘gpgme_op_genkey_result’.
3403 The function returns zero on success, ‘GPG_ERR_NOT_SUPPORTED’ if
3404 the engine does not support the command, or a bunch of other error
3407 -- Function: gpgme_error_t gpgme_op_createkey_start (gpgme_ctx_t CTX,
3408 const char *USERID, const char *ALGO, unsigned long RESERVED,
3409 unsigned long EXPIRES, gpgme_key_t EXTRAKEY,
3410 unsigned int FLAGS);
3412 The function ‘gpgme_op_createkey_start’ initiates a
3413 ‘gpgme_op_createkey’ operation; see there for details. It must be
3414 completed by calling ‘gpgme_wait’ on the context. *Note Waiting
3417 -- Function: gpgme_error_t gpgme_op_createsubkey (gpgme_ctx_t CTX,
3418 gpgme_key_t KEY, const char *ALGO, unsigned long RESERVED,
3419 unsigned long EXPIRES, unsigned int FLAGS);
3421 The function ‘gpgme_op_createsubkey’ creates and adds a new subkey
3422 to the primary OpenPGP key given by KEY. The only allowed protocol
3423 in CTX is ‘GPGME_PROTOCOL_OPENPGP’. Subkeys (aka secondary keys)
3424 are a concept in the OpenPGP protocol to bind several keys to a
3425 primary key. As of now this function requires at least version
3428 KEY specifies the key to operate on.
3430 ALGO specifies the algorithm for the new subkey. For a list of
3431 supported algorithms, see the GnuPG manual. If ALGO is ‘NULL’ or
3432 the string "default", the subkey is generated using the default
3433 algorithm for an encryption subkey of the engine. If the string
3434 "future-default" is used the engine may use an encryption algorithm
3435 which is planned to be the default in a future release of the
3436 engine; however existing implementation of the protocol may not be
3437 able to already handle such future algorithms.
3439 RESERVED must be set to zero.
3441 EXPIRES can be set to the number of seconds since Epoch of the
3442 desired expiration date in UTC for the new subkey. Using 0 does
3443 not set an expiration date. Note that this parameter takes an
3444 unsigned long value and not a ‘time_t’ to avoid problems on systems
3445 which use a signed 32 bit ‘time_t’. Note further that the OpenPGP
3446 protocol uses 32 bit values for timestamps and thus can only encode
3447 dates up to the year 2106.
3449 FLAGS takes the same values as described above for
3450 ‘gpgme_op_createkey’.
3452 After the operation completed successfully, information about the
3453 created key can be retrieved with ‘gpgme_op_genkey_result’.
3455 The function returns zero on success, ‘GPG_ERR_NOT_SUPPORTED’ if
3456 the engine does not support the command, or a bunch of other error
3459 -- Function: gpgme_error_t gpgme_op_createsubkey_start
3460 (gpgme_ctx_t CTX, gpgme_key_t KEY, const char *ALGO,
3461 unsigned long RESERVED, unsigned long EXPIRES,
3462 unsigned int FLAGS);
3464 The function ‘gpgme_op_createsubkey_start’ initiates a
3465 ‘gpgme_op_createsubkey’ operation; see there for details. It must
3466 be completed by calling ‘gpgme_wait’ on the context. *Note Waiting
3469 -- Function: gpgme_error_t gpgme_op_adduid (gpgme_ctx_t CTX,
3470 gpgme_key_t KEY, const char *USERID, unsigned int FLAGS);
3472 The function ‘gpgme_op_adduid’ adds a new user ID to the OpenPGP
3473 key given by KEY. Adding additional user IDs after key creation is
3474 a feature of the OpenPGP protocol and thus the protocol for the
3475 context CTX must be set to OpenPGP. As of now this function
3476 requires at least version 2.1.13 of GnuPG.
3478 KEY specifies the key to operate on.
3480 USERID is the user ID to add to the key. A user ID is commonly the
3481 mail address to be associated with the key. GPGME does not require
3482 a specificy syntax but if more than a mail address is given,
3483 RFC-822 style format is suggested. The value is expected to be in
3484 UTF-8 encoding (i.e. no IDN encoding for mail addresses). This is
3485 a required parameter.
3487 FLAGS are currently not used and must be set to zero.
3489 The function returns zero on success, ‘GPG_ERR_NOT_SUPPORTED’ if
3490 the engine does not support the command, or a bunch of other error
3493 -- Function: gpgme_error_t gpgme_op_adduid_start (gpgme_ctx_t CTX,
3494 gpgme_key_t KEY, const char *USERID, unsigned int FLAGS);
3496 The function ‘gpgme_op_adduid_start’ initiates a ‘gpgme_op_adduid’
3497 operation; see there for details. It must be completed by calling
3498 ‘gpgme_wait’ on the context. *Note Waiting For Completion::.
3500 -- Function: gpgme_error_t gpgme_op_revuid (gpgme_ctx_t CTX,
3501 gpgme_key_t KEY, const char *USERID, unsigned int FLAGS);
3503 The function ‘gpgme_op_revuid’ revokes a user ID from the OpenPGP
3504 key given by KEY. Revoking user IDs after key creation is a
3505 feature of the OpenPGP protocol and thus the protocol for the
3506 context CTX must be set to OpenPGP. As of now this function
3507 requires at least version 2.1.13 of GnuPG.
3509 KEY specifies the key to operate on.
3511 USERID is the user ID to be revoked from the key. The user ID must
3512 be given verbatim because the engine does an exact and case
3513 sensitive match. Thus the ‘uid’ field from the user ID object
3514 (‘gpgme_user_id_t’) is to be used. This is a required parameter.
3516 FLAGS are currently not used and must be set to zero.
3518 Note that the engine won’t allow to revoke the last valid user ID.
3519 To change a user ID is better to first add the new user ID, then
3520 revoke the old one, and finally publish the key.
3522 The function returns zero on success, ‘GPG_ERR_NOT_SUPPORTED’ if
3523 the engine does not support the command, or a bunch of other error
3526 -- Function: gpgme_error_t gpgme_op_revuid_start (gpgme_ctx_t CTX,
3527 gpgme_key_t KEY, const char *USERID, unsigned int FLAGS);
3529 The function ‘gpgme_op_revuid_start’ initiates a ‘gpgme_op_revuid’
3530 operation; see there for details. It must be completed by calling
3531 ‘gpgme_wait’ on the context. *Note Waiting For Completion::.
3533 -- Function: gpgme_error_t gpgme_op_genkey (gpgme_ctx_t CTX,
3534 const char *PARMS, gpgme_data_t PUBLIC, gpgme_data_t SECRET)
3536 The function ‘gpgme_op_genkey’ generates a new key pair in the
3537 context CTX. The meaning of PUBLIC and SECRET depends on the
3540 GPG does not support PUBLIC and SECRET, they should be ‘NULL’.
3541 GnuPG will generate a key pair and add it to the standard key ring.
3542 The fingerprint of the generated key is available with
3543 ‘gpgme_op_genkey_result’.
3545 GpgSM requires PUBLIC to be a writable data object. GpgSM will
3546 generate a secret key (which will be stored by ‘gpg-agent’, and
3547 return a certificate request in PUBLIC, which then needs to be
3548 signed by the certification authority and imported before it can be
3549 used. GpgSM does not make the fingerprint available.
3551 The argument PARMS specifies parameters for the key in an XML
3552 string. The details about the format of PARMS are specific to the
3553 crypto engine used by CTX. Here is an example for GnuPG as the
3554 crypto engine (all parameters of OpenPGP key generation are
3555 documented in the GPG manual):
3557 <GnupgKeyParms format="internal">
3559 Subkey-Type: default
3560 Name-Real: Joe Tester
3561 Name-Comment: with stupid passphrase
3562 Name-Email: joe@foo.bar
3567 Here is an example for GpgSM as the crypto engine (all parameters
3568 of OpenPGP key generation are documented in the GPGSM manual):
3570 <GnupgKeyParms format="internal">
3573 Name-DN: C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester
3574 Name-Email: joe@foo.bar
3577 Strings should be given in UTF-8 encoding. The only format
3578 supported for now is “internal”. The content of the
3579 ‘GnupgKeyParms’ container is passed verbatim to the crypto backend.
3580 Control statements are not allowed.
3582 After the operation completed successfully, the result can be
3583 retrieved with ‘gpgme_op_genkey_result’.
3585 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
3586 operation could be started successfully, ‘GPG_ERR_INV_VALUE’ if
3587 PARMS is not a valid XML string, ‘GPG_ERR_NOT_SUPPORTED’ if PUBLIC
3588 or SECRET is not valid, and ‘GPG_ERR_GENERAL’ if no key was created
3591 -- Function: gpgme_error_t gpgme_op_genkey_start (gpgme_ctx_t CTX,
3592 const char *PARMS, gpgme_data_t PUBLIC, gpgme_data_t SECRET)
3594 The function ‘gpgme_op_genkey_start’ initiates a ‘gpgme_op_genkey’
3595 operation. It can be completed by calling ‘gpgme_wait’ on the
3596 context. *Note Waiting For Completion::.
3598 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
3599 operation could be started successfully, ‘GPG_ERR_INV_VALUE’ if
3600 PARMS is not a valid XML string, and ‘GPG_ERR_NOT_SUPPORTED’ if
3601 PUBLIC or SECRET is not ‘NULL’.
3603 -- Data type: gpgme_genkey_result_t
3605 This is a pointer to a structure used to store the result of a
3606 ‘gpgme_op_genkey’ operation. After successfully generating a key,
3607 you can retrieve the pointer to the result with
3608 ‘gpgme_op_genkey_result’. The structure contains the following
3611 ‘unsigned int primary : 1’
3612 This flag is set to 1 if a primary key was created and to 0 if
3615 ‘unsigned int sub : 1’
3616 This flag is set to 1 if a subkey was created and to 0 if not.
3618 ‘unsigned int uid : 1’
3619 This flag is set to 1 if a user ID was created and to 0 if
3623 This is the fingerprint of the key that was created. If both
3624 a primary and a subkey were generated, the fingerprint of the
3625 primary key will be returned. If the crypto engine does not
3626 provide the fingerprint, ‘fpr’ will be a null pointer.
3628 ‘gpgme_data_t pubkey’
3629 This will eventually be used to return the public key. It is
3632 ‘gpgme_data_t seckey’
3633 This will eventually be used to return the secret key. It is
3636 -- Function: gpgme_genkey_result_t gpgme_op_genkey_result
3639 The function ‘gpgme_op_genkey_result’ returns a
3640 ‘gpgme_genkey_result_t’ pointer to a structure holding the result
3641 of a ‘gpgme_op_genkey’ operation. The pointer is only valid if the
3642 last operation on the context was a ‘gpgme_op_genkey’ or
3643 ‘gpgme_op_genkey_start’ operation, and if this operation finished
3644 successfully. The returned pointer is only valid until the next
3645 operation is started on the context.
3648 File: gpgme.info, Node: Signing Keys, Next: Exporting Keys, Prev: Generating Keys, Up: Key Management
3653 Key signatures are a unique concept of the OpenPGP protocol. They can
3654 be used to certify the validity of a key and are used to create the
3655 Web-of-Trust (WoT). Instead of using the ‘gpgme_op_interact’ function
3656 along with a finite state machine, GPGME provides a convenient function
3657 to create key signatures when using modern GnuPG versions.
3659 -- Function: gpgme_error_t gpgme_op_keysign (gpgme_ctx_t CTX,
3660 gpgme_key_t KEY, const char *USERID, unsigned long EXPIRES,
3661 unsigned int FLAGS);
3663 The function ‘gpgme_op_keysign’ adds a new key signature to the
3664 public key KEY. This function requires at least version 2.1.12 of
3667 CTX is the usual context which describes the protocol to use (which
3668 must be OpenPGP) and has also the list of signer keys to be used
3669 for the signature. The common case is to use the default key for
3670 signing other keys. If another key or more than one key shall be
3671 used for a key signature, ‘gpgme_signers_add’ can be used. *Note
3672 Selecting Signers::.
3674 KEY specifies the key to operate on.
3676 USERID selects the user ID or user IDs to be signed. If USERID is
3677 set to ‘NULL’ all valid user IDs are signed. The user ID must be
3678 given verbatim because the engine does an exact and case sensitive
3679 match. Thus the ‘uid’ field from the user ID object
3680 (‘gpgme_user_id_t’) is to be used. To select more than one user ID
3681 put them all into one string separated by linefeeds characters
3682 (‘\n’) and set the flag ‘GPGME_KEYSIGN_LFSEP’.
3684 EXPIRES can be set to the number of seconds since Epoch of the
3685 desired expiration date in UTC for the new signature. The common
3686 case is to use 0 to not set an expiration date. However, if the
3687 configuration of the engine defines a default expiration for key
3688 signatures, that is still used unless the flag
3689 ‘GPGME_KEYSIGN_NOEXPIRE’ is used. Note that this parameter takes
3690 an unsigned long value and not a ‘time_t’ to avoid problems on
3691 systems which use a signed 32 bit ‘time_t’. Note further that the
3692 OpenPGP protocol uses 32 bit values for timestamps and thus can
3693 only encode dates up to the year 2106.
3695 FLAGS can be set to the bit-wise OR of the following flags:
3697 ‘GPGME_KEYSIGN_LOCAL’
3698 Instead of creating an exportable key signature, create a key
3699 signature which is is marked as non-exportable.
3701 ‘GPGME_KEYSIGN_LFSEP’
3702 Although linefeeds are uncommon in user IDs this flag is
3703 required to explicitly declare that USERID may contain several
3704 linefeed separated user IDs.
3706 ‘GPGME_KEYSIGN_NOEXPIRE’
3707 Force the creation of a key signature without an expiration
3708 date. This overrides EXPIRE and any local configuration of
3711 The function returns zero on success, ‘GPG_ERR_NOT_SUPPORTED’ if
3712 the engine does not support the command, or a bunch of other error
3715 -- Function: gpgme_error_t gpgme_op_keysign_start (gpgme_ctx_t CTX,
3716 gpgme_key_t KEY, const char *USERID, unsigned long EXPIRES,
3717 unsigned int FLAGS);
3719 The function ‘gpgme_op_keysign_start’ initiates a
3720 ‘gpgme_op_keysign’ operation; see there for details. It must be
3721 completed by calling ‘gpgme_wait’ on the context. *Note Waiting
3725 File: gpgme.info, Node: Exporting Keys, Next: Importing Keys, Prev: Signing Keys, Up: Key Management
3727 7.5.7 Exporting Keys
3728 --------------------
3730 Exporting keys means the same as running ‘gpg’ with the command
3731 ‘--export’. However, a mode flag can be used to change the way the
3732 export works. The available mode flags are described below, they may be
3735 ‘GPGME_EXPORT_MODE_EXTERN’
3736 If this bit is set, the output is send directly to the default
3737 keyserver. This is currently only allowed for OpenPGP keys. It is
3738 good practise to not send more than a few dozens key to a keyserver
3739 at one time. Using this flag requires that the KEYDATA argument of
3740 the export function is set to ‘NULL’.
3742 ‘GPGME_EXPORT_MODE_MINIMAL’
3743 If this bit is set, the smallest possible key is exported. For
3744 OpenPGP keys it removes all signatures except for the latest
3745 self-signatures. For X.509 keys it has no effect.
3747 ‘GPGME_EXPORT_MODE_SECRET’
3748 Instead of exporting the public key, the secret key is exported.
3749 This may not be combined with ‘GPGME_EXPORT_MODE_EXTERN’. For
3750 X.509 the export format is PKCS#8.
3752 ‘GPGME_EXPORT_MODE_RAW’
3753 If this flag is used with ‘GPGME_EXPORT_MODE_SECRET’ for an X.509
3754 key the export format will be changed to PKCS#1. This flag may not
3755 be used with OpenPGP.
3757 ‘GPGME_EXPORT_MODE_PKCS12’
3758 If this flag is used with ‘GPGME_EXPORT_MODE_SECRET’ for an X.509
3759 key the export format will be changed to PKCS#12 which also
3760 includes the certificate. This flag may not be used with OpenPGP.
3762 -- Function: gpgme_error_t gpgme_op_export (gpgme_ctx_t CTX,
3763 const char *PATTERN, gpgme_export_mode_t MODE,
3764 gpgme_data_t KEYDATA)
3765 The function ‘gpgme_op_export’ extracts public keys and returns
3766 them in the data buffer KEYDATA. The output format of the key data
3767 returned is determined by the ASCII armor attribute set for the
3768 context CTX, or, if that is not set, by the encoding specified for
3771 If PATTERN is ‘NULL’, all available keys are returned. Otherwise,
3772 PATTERN contains an engine specific expression that is used to
3773 limit the list to all keys matching the pattern.
3775 MODE is usually 0; other values are described above.
3777 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
3778 operation completed successfully, ‘GPG_ERR_INV_VALUE’ if KEYDATA is
3779 not a valid empty data buffer, and passes through any errors that
3780 are reported by the crypto engine support routines.
3782 -- Function: gpgme_error_t gpgme_op_export_start (gpgme_ctx_t CTX,
3783 const char *PATTERN, gpgme_export_mode_t MODE,
3784 gpgme_data_t KEYDATA)
3785 The function ‘gpgme_op_export_start’ initiates a ‘gpgme_op_export’
3786 operation. It can be completed by calling ‘gpgme_wait’ on the
3787 context. *Note Waiting For Completion::.
3789 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
3790 operation could be started successfully, and ‘GPG_ERR_INV_VALUE’ if
3791 KEYDATA is not a valid empty data buffer.
3793 -- Function: gpgme_error_t gpgme_op_export_ext (gpgme_ctx_t CTX,
3794 const char *PATTERN[], gpgme_export_mode_t MODE,
3795 gpgme_data_t KEYDATA)
3796 The function ‘gpgme_op_export’ extracts public keys and returns
3797 them in the data buffer KEYDATA. The output format of the key data
3798 returned is determined by the ASCII armor attribute set for the
3799 context CTX, or, if that is not set, by the encoding specified for
3802 If PATTERN or *PATTERN is ‘NULL’, all available keys are returned.
3803 Otherwise, PATTERN is a ‘NULL’ terminated array of strings that are
3804 used to limit the list to all keys matching at least one of the
3807 MODE is usually 0; other values are described above.
3809 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
3810 operation completed successfully, ‘GPG_ERR_INV_VALUE’ if KEYDATA is
3811 not a valid empty data buffer, and passes through any errors that
3812 are reported by the crypto engine support routines.
3814 -- Function: gpgme_error_t gpgme_op_export_ext_start (gpgme_ctx_t CTX,
3815 const char *PATTERN[], gpgme_export_mode_t MODE,
3816 gpgme_data_t KEYDATA)
3817 The function ‘gpgme_op_export_ext_start’ initiates a
3818 ‘gpgme_op_export_ext’ operation. It can be completed by calling
3819 ‘gpgme_wait’ on the context. *Note Waiting For Completion::.
3821 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
3822 operation could be started successfully, and ‘GPG_ERR_INV_VALUE’ if
3823 KEYDATA is not a valid empty data buffer.
3825 -- Function: gpgme_error_t gpgme_op_export_keys (gpgme_ctx_t CTX,
3826 gpgme_key_t keys[], gpgme_export_mode_t MODE,
3827 gpgme_data_t KEYDATA)
3828 The function ‘gpgme_op_export_keys’ extracts public keys and
3829 returns them in the data buffer KEYDATA. The output format of the
3830 key data returned is determined by the ASCII armor attribute set
3831 for the context CTX, or, if that is not set, by the encoding
3832 specified for KEYDATA.
3834 The keys to export are taken form the ‘NULL’ terminated array KEYS.
3835 Only keys of the currently selected protocol of CTX which do have a
3836 fingerprint set are considered for export. Other keys specified by
3837 the KEYS are ignored. In particular OpenPGP keys retrieved via an
3838 external key listing are not included.
3840 MODE is usually 0; other values are described above.
3842 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
3843 operation completed successfully, ‘GPG_ERR_INV_VALUE’ if KEYDATA is
3844 not a valid empty data buffer, ‘GPG_ERR_NO_DATA’ if no useful keys
3845 are in KEYS and passes through any errors that are reported by the
3846 crypto engine support routines.
3848 -- Function: gpgme_error_t gpgme_op_export_keys_start (gpgme_ctx_t CTX,
3849 gpgme_key_t KEYS[], gpgme_export_mode_t MODE,
3850 gpgme_data_t KEYDATA)
3851 The function ‘gpgme_op_export_keys_start’ initiates a
3852 ‘gpgme_op_export_ext’ operation. It can be completed by calling
3853 ‘gpgme_wait’ on the context. *Note Waiting For Completion::.
3855 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
3856 operation could be started successfully, and ‘GPG_ERR_INV_VALUE’ if
3857 KEYDATA is not a valid empty data buffer, ‘GPG_ERR_NO_DATA’ if no
3858 useful keys are in KEYS and passes through any errors that are
3859 reported by the crypto engine support routines.
3862 File: gpgme.info, Node: Importing Keys, Next: Deleting Keys, Prev: Exporting Keys, Up: Key Management
3864 7.5.8 Importing Keys
3865 --------------------
3867 Importing keys means the same as running ‘gpg’ with the command
3870 -- Function: gpgme_error_t gpgme_op_import (gpgme_ctx_t CTX,
3871 gpgme_data_t KEYDATA)
3872 The function ‘gpgme_op_import’ adds the keys in the data buffer
3873 KEYDATA to the key ring of the crypto engine used by CTX. The
3874 format of KEYDATA can be ASCII armored, for example, but the
3875 details are specific to the crypto engine.
3877 After the operation completed successfully, the result can be
3878 retrieved with ‘gpgme_op_import_result’.
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, and ‘GPG_ERR_NO_DATA’ if
3883 KEYDATA is an empty data buffer.
3885 -- Function: gpgme_error_t gpgme_op_import_start (gpgme_ctx_t CTX,
3886 gpgme_data_t KEYDATA)
3887 The function ‘gpgme_op_import_start’ initiates a ‘gpgme_op_import’
3888 operation. It can be completed by calling ‘gpgme_wait’ on the
3889 context. *Note Waiting For Completion::.
3891 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
3892 import could be started successfully, ‘GPG_ERR_INV_VALUE’ if
3893 KEYDATA if CTX or KEYDATA is not a valid pointer, and
3894 ‘GPG_ERR_NO_DATA’ if KEYDATA is an empty data buffer.
3896 -- Function: gpgme_error_t gpgme_op_import_keys (gpgme_ctx_t CTX,
3898 The function ‘gpgme_op_import_keys’ adds the keys described by the
3899 ‘NULL’ terminated array KEYS to the key ring of the crypto engine
3900 used by CTX. This function is the general interface to move a key
3901 from one crypto engine to another as long as they are compatible.
3902 In particular it is used to actually import and make keys permanent
3903 which have been retrieved from an external source (i.e. using
3904 ‘GPGME_KEYLIST_MODE_EXTERN’). (1)
3906 Only keys of the currently selected protocol of CTX are considered
3907 for import. Other keys specified by the KEYS are ignored. As of
3908 now all considered keys must have been retrieved using the same
3909 method, that is the used key listing mode must be identical.
3911 After the operation completed successfully, the result can be
3912 retrieved with ‘gpgme_op_import_result’.
3914 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
3915 import was completed successfully, ‘GPG_ERR_INV_VALUE’ if KEYDATA
3916 if CTX or KEYDATA is not a valid pointer, ‘GPG_ERR_CONFLICT’ if the
3917 key listing mode does not match, and ‘GPG_ERR_NO_DATA’ if no keys
3918 are considered for export.
3920 -- Function: gpgme_error_t gpgme_op_import_keys_start (gpgme_ctx_t CTX,
3922 The function ‘gpgme_op_import_keys_start’ initiates a
3923 ‘gpgme_op_import_keys’ operation. It can be completed by calling
3924 ‘gpgme_wait’ on the context. *Note Waiting For Completion::.
3926 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
3927 import was completed successfully, ‘GPG_ERR_INV_VALUE’ if KEYDATA
3928 if CTX or KEYDATA is not a valid pointer, ‘GPG_ERR_CONFLICT’ if the
3929 key listing mode does not match, and ‘GPG_ERR_NO_DATA’ if no keys
3930 are considered for export.
3932 -- Data type: gpgme_import_status_t
3933 This is a pointer to a structure used to store a part of the result
3934 of a ‘gpgme_op_import’ operation. For each considered key one
3935 status is added that contains information about the result of the
3936 import. The structure contains the following members:
3938 ‘gpgme_import_status_t next’
3939 This is a pointer to the next status structure in the linked
3940 list, or ‘NULL’ if this is the last element.
3943 This is the fingerprint of the key that was considered.
3945 ‘gpgme_error_t result’
3946 If the import was not successful, this is the error value that
3947 caused the import to fail. Otherwise the error code is
3950 ‘unsigned int status’
3951 This is a bit-wise OR of the following flags that give more
3952 information about what part of the key was imported. If the
3953 key was already known, this might be 0.
3959 The key contained new user IDs.
3962 The key contained new signatures.
3964 ‘GPGME_IMPORT_SUBKEY’
3965 The key contained new sub keys.
3967 ‘GPGME_IMPORT_SECRET’
3968 The key contained a secret key.
3970 -- Data type: gpgme_import_result_t
3971 This is a pointer to a structure used to store the result of a
3972 ‘gpgme_op_import’ operation. After a successful import operation,
3973 you can retrieve the pointer to the result with
3974 ‘gpgme_op_import_result’. The structure contains the following
3978 The total number of considered keys.
3981 The number of keys without user ID.
3984 The total number of imported keys.
3987 The number of imported RSA keys.
3990 The number of unchanged keys.
3993 The number of new user IDs.
3996 The number of new sub keys.
3998 ‘int new_signatures’
3999 The number of new signatures.
4001 ‘int new_revocations’
4002 The number of new revocations.
4005 The total number of secret keys read.
4007 ‘int secret_imported’
4008 The number of imported secret keys.
4010 ‘int secret_unchanged’
4011 The number of unchanged secret keys.
4014 The number of keys not imported.
4016 ‘gpgme_import_status_t imports’
4017 A list of gpgme_import_status_t objects which contain more
4018 information about the keys for which an import was attempted.
4020 -- Function: gpgme_import_result_t gpgme_op_import_result
4022 The function ‘gpgme_op_import_result’ returns a
4023 ‘gpgme_import_result_t’ pointer to a structure holding the result
4024 of a ‘gpgme_op_import’ operation. The pointer is only valid if the
4025 last operation on the context was a ‘gpgme_op_import’ or
4026 ‘gpgme_op_import_start’ operation, and if this operation finished
4027 successfully. The returned pointer is only valid until the next
4028 operation is started on the context.
4030 ---------- Footnotes ----------
4032 (1) Thus it is a replacement for the usual workaround of exporting
4033 and then importing a key to make an X.509 key permanent.
4036 File: gpgme.info, Node: Deleting Keys, Next: Changing Passphrases, Prev: Importing Keys, Up: Key Management
4041 -- Function: gpgme_error_t gpgme_op_delete (gpgme_ctx_t CTX,
4042 const gpgme_key_t KEY, int ALLOW_SECRET)
4043 The function ‘gpgme_op_delete’ deletes the key KEY from the key
4044 ring of the crypto engine used by CTX. If ALLOW_SECRET is ‘0’,
4045 only public keys are deleted, otherwise secret keys are deleted as
4046 well, if that is supported.
4048 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the key
4049 was deleted successfully, ‘GPG_ERR_INV_VALUE’ if CTX or KEY is not
4050 a valid pointer, ‘GPG_ERR_NO_PUBKEY’ if KEY could not be found in
4051 the keyring, ‘GPG_ERR_AMBIGUOUS_NAME’ if the key was not specified
4052 unambiguously, and ‘GPG_ERR_CONFLICT’ if the secret key for KEY is
4053 available, but ALLOW_SECRET is zero.
4055 -- Function: gpgme_error_t gpgme_op_delete_start (gpgme_ctx_t CTX,
4056 const gpgme_key_t KEY, int ALLOW_SECRET)
4057 The function ‘gpgme_op_delete_start’ initiates a ‘gpgme_op_delete’
4058 operation. It can be completed by calling ‘gpgme_wait’ on the
4059 context. *Note Waiting For Completion::.
4061 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
4062 operation was started successfully, and ‘GPG_ERR_INV_VALUE’ if CTX
4063 or KEY is not a valid pointer.
4066 File: gpgme.info, Node: Changing Passphrases, Next: Changing TOFU Data, Prev: Deleting Keys, Up: Key Management
4068 7.5.10 Changing Passphrases
4069 ---------------------------
4071 -- Function: gpgme_error_t gpgme_op_passwd (gpgme_ctx_t CTX,
4072 const gpgme_key_t KEY, unsigned int FLAGS)
4074 The function ‘gpgme_op_passwd’ changes the passphrase of the
4075 private key associated with KEY. The only allowed value for FLAGS
4076 is ‘0’. The backend engine will usually popup a window to ask for
4077 the old and the new passphrase. Thus this function is not useful
4078 in a server application (where passphrases are not required
4081 Note that old ‘gpg’ engines (before version 2.0.15) do not support
4082 this command and will silently ignore it.
4084 -- Function: gpgme_error_t gpgme_op_passwd_start (gpgme_ctx_t CTX,
4085 const gpgme_key_t KEY, unsigned int FLAGS)
4087 The function ‘gpgme_op_passwd_start’ initiates a ‘gpgme_op_passwd’
4088 operation. It can be completed by calling ‘gpgme_wait’ on the
4089 context. *Note Waiting For Completion::.
4091 The function returns ‘0’ if the operation was started successfully,
4092 and an error code if one of the arguments is not valid or the
4093 oepration could not be started.
4096 File: gpgme.info, Node: Changing TOFU Data, Next: Advanced Key Editing, Prev: Changing Passphrases, Up: Key Management
4098 7.5.11 Changing TOFU Data
4099 -------------------------
4101 The OpenPGP engine features a Trust-On-First-Use (TOFU) key validation
4102 model. For resolving clonflics it is necessary to declare the policy
4103 for a key. See the GnuPG manual for details on the TOFU implementation.
4105 -- Data type: enum gpgme_tofu_policy_t
4106 The ‘gpgme_tofu_policy_t’ type specifies the set of possible policy
4107 values that are supported by GPGME:
4109 ‘GPGME_TOFU_POLICY_AUTO’
4110 Set the policy to “auto”.
4111 ‘GPGME_TOFU_POLICY_GOOD’
4112 Set the policy to “goog”.
4113 ‘GPGME_TOFU_POLICY_BAD’
4114 Set the policy to “bad”.
4115 ‘GPGME_TOFU_POLICY_ASK’
4116 Set the policy to “ask”.
4117 ‘GPGME_TOFU_POLICY_UNKNOWN’
4118 Set the policy to “unknown”.
4120 To change the policy for a key the following functions can be used:
4122 -- Function: gpgme_error_t gpgme_op_tofu_policy (gpgme_ctx_t CTX,
4123 const gpgme_key_t KEY, gpgme_tofu_policy_t POLICY)
4125 The function ‘gpgme_op_tofu_policy’ changes the TOFU policy of KEY.
4126 The valid values for POLICY are listed above. As of now this
4127 function does only work for OpenPGP and requires at least version
4130 The function returns zero on success, ‘GPG_ERR_NOT_SUPPORTED’ if
4131 the engine does not support the command, or a bunch of other error
4134 -- Function: gpgme_error_t gpgme_op_tofu_policy_start (gpgme_ctx_t CTX,
4135 const gpgme_key_t KEY, gpgme_tofu_policy_t POLICY)
4137 The function ‘gpgme_op_tofu_policy_start’ initiates a
4138 ‘gpgme_op_tofu_policy’ operation. It can be completed by calling
4139 ‘gpgme_wait’ on the context. *Note Waiting For Completion::.
4141 The function returns ‘0’ if the operation was started successfully,
4142 and an error code if one of the arguments is not valid or the
4143 oepration could not be started.
4146 File: gpgme.info, Node: Advanced Key Editing, Prev: Changing TOFU Data, Up: Key Management
4148 7.5.12 Advanced Key Editing
4149 ---------------------------
4151 -- Data type: gpgme_error_t (*gpgme_interact_cb_t) (void *HANDLE,
4152 const char *STATUS, const char *ARGS, int FD)
4153 The ‘gpgme_interact_cb_t’ type is the type of functions which GPGME
4154 calls if it a key interact operation is on-going. The status
4155 keyword STATUS and the argument line ARGS are passed through by
4156 GPGME from the crypto engine. An empty string represents EOF. The
4157 file descriptor FD is -1 for normal status messages. If STATUS
4158 indicates a command rather than a status message, the response to
4159 the command should be written to FD. The HANDLE is provided by the
4160 user at start of operation.
4162 The function should return ‘GPG_ERR_FALSE’ if it did not handle the
4163 status code, ‘0’ for success, or any other error value.
4165 -- Function: gpgme_error_t gpgme_op_interact (gpgme_ctx_t CTX,
4166 gpgme_key_t KEY, unsigned int FLAGS, gpgme_interact_cb_t FNC,
4167 void *HANDLE, gpgme_data_t OUT)
4168 The function ‘gpgme_op_interact’ processes the key KEY
4169 interactively, using the interact callback function FNC with the
4170 handle HANDLE. The callback is invoked for every status and
4171 command request from the crypto engine. The output of the crypto
4172 engine is written to the data object OUT.
4174 Note that the protocol between the callback function and the crypto
4175 engine is specific to the crypto engine and no further support in
4176 implementing this protocol correctly is provided by GPGME.
4178 FLAGS modifies the behaviour of the function; the only defined bit
4181 ‘GPGME_INTERACT_CARD’
4182 This is used for smartcard based keys and uses gpg’s
4183 ‘--card-edit’ command.
4185 The function returns ‘0’ if the edit operation completes
4186 successfully, ‘GPG_ERR_INV_VALUE’ if CTX or KEY is not a valid
4187 pointer, and any error returned by the crypto engine or the edit
4190 -- Function: gpgme_error_t gpgme_op_interact_start (gpgme_ctx_t CTX,
4191 gpgme_key_t KEY, unsigned int FLAGS, gpgme_interact_cb_t FNC,
4192 void *HANDLE, gpgme_data_t OUT)
4193 The function ‘gpgme_op_interact_start’ initiates a
4194 ‘gpgme_op_interact’ operation. It can be completed by calling
4195 ‘gpgme_wait’ on the context. *Note Waiting For Completion::.
4197 The function returns ‘0’ if the operation was started successfully,
4198 and ‘GPG_ERR_INV_VALUE’ if CTX or KEY is not a valid pointer.
4201 File: gpgme.info, Node: Trust Item Management, Next: Crypto Operations, Prev: Key Management, Up: Contexts
4203 7.6 Trust Item Management
4204 =========================
4206 *Caution:* The trust items interface is experimental.
4208 -- Data type: gpgme_trust_item_t
4209 The ‘gpgme_trust_item_t’ type is a pointer to a trust item object.
4210 It has the following members:
4213 This is a string describing the key to which this trust items
4217 This is the type of the trust item. A value of 1 refers to a
4218 key, a value of 2 refers to a user ID.
4221 This is the trust level.
4224 The owner trust if ‘type’ is 1.
4227 The calculated validity.
4230 The user name if ‘type’ is 2.
4234 * Listing Trust Items:: Browsing the list of available trust items.
4235 * Manipulating Trust Items:: Operations on trust items.
4238 File: gpgme.info, Node: Listing Trust Items, Next: Manipulating Trust Items, Up: Trust Item Management
4240 7.6.1 Listing Trust Items
4241 -------------------------
4243 -- Function: gpgme_error_t gpgme_op_trustlist_start (gpgme_ctx_t CTX,
4244 const char *PATTERN, int MAX_LEVEL)
4245 The function ‘gpgme_op_trustlist_start’ initiates a trust item
4246 listing operation inside the context CTX. It sets everything up so
4247 that subsequent invocations of ‘gpgme_op_trustlist_next’ return the
4248 trust items in the list.
4250 The string PATTERN contains an engine specific expression that is
4251 used to limit the list to all trust items matching the pattern. It
4252 can not be the empty string.
4254 The argument MAX_LEVEL is currently ignored.
4256 The context will be busy until either all trust items are received
4257 (and ‘gpgme_op_trustlist_next’ returns ‘GPG_ERR_EOF’), or
4258 ‘gpgme_op_trustlist_end’ is called to finish the operation.
4260 The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX is
4261 not a valid pointer, and passes through any errors that are
4262 reported by the crypto engine support routines.
4264 -- Function: gpgme_error_t gpgme_op_trustlist_next (gpgme_ctx_t CTX,
4265 gpgme_trust_item_t *R_ITEM)
4266 The function ‘gpgme_op_trustlist_next’ returns the next trust item
4267 in the list created by a previous ‘gpgme_op_trustlist_start’
4268 operation in the context CTX. The trust item can be destroyed with
4269 ‘gpgme_trust_item_release’. *Note Manipulating Trust Items::.
4271 This is the only way to get at ‘gpgme_trust_item_t’ objects in
4274 If the last trust item in the list has already been returned,
4275 ‘gpgme_op_trustlist_next’ returns ‘GPG_ERR_EOF’.
4277 The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX or
4278 R_ITEM is not a valid pointer, and ‘GPG_ERR_ENOMEM’ if there is not
4279 enough memory for the operation.
4281 -- Function: gpgme_error_t gpgme_op_trustlist_end (gpgme_ctx_t CTX)
4282 The function ‘gpgme_op_trustlist_end’ ends a pending trust list
4283 operation in the context CTX.
4285 The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX is
4286 not a valid pointer, and ‘GPG_ERR_ENOMEM’ if at some time during
4287 the operation there was not enough memory available.
4290 File: gpgme.info, Node: Manipulating Trust Items, Prev: Listing Trust Items, Up: Trust Item Management
4292 7.6.2 Manipulating Trust Items
4293 ------------------------------
4295 -- Function: void gpgme_trust_item_ref (gpgme_trust_item_t ITEM)
4296 The function ‘gpgme_trust_item_ref’ acquires an additional
4297 reference for the trust item ITEM.
4299 -- Function: void gpgme_trust_item_unref (gpgme_trust_item_t ITEM)
4300 The function ‘gpgme_trust_item_unref’ releases a reference for the
4301 trust item ITEM. If this was the last reference, the trust item
4302 will be destroyed and all resources associated to it will be
4306 File: gpgme.info, Node: Crypto Operations, Next: Miscellaneous, Prev: Trust Item Management, Up: Contexts
4308 7.7 Crypto Operations
4309 =====================
4311 Sometimes, the result of a crypto operation returns a list of invalid
4312 keys encountered in processing the request. The following structure is
4313 used to hold information about such a key.
4315 -- Data type: gpgme_invalid_key_t
4316 This is a pointer to a structure used to store a part of the result
4317 of a crypto operation which takes user IDs as one input parameter.
4318 The structure contains the following members:
4320 ‘gpgme_invalid_key_t next’
4321 This is a pointer to the next invalid key structure in the
4322 linked list, or ‘NULL’ if this is the last element.
4325 The fingerprint or key ID of the invalid key encountered.
4327 ‘gpgme_error_t reason’
4328 An error code describing the reason why the key was found
4333 * Decrypt:: Decrypting a ciphertext.
4334 * Verify:: Verifying a signature.
4335 * Decrypt and Verify:: Decrypting a signed ciphertext.
4336 * Sign:: Creating a signature.
4337 * Encrypt:: Encrypting a plaintext.
4340 File: gpgme.info, Node: Decrypt, Next: Verify, Up: Crypto Operations
4345 -- Function: gpgme_error_t gpgme_op_decrypt (gpgme_ctx_t CTX,
4346 gpgme_data_t CIPHER, gpgme_data_t PLAIN)
4347 The function ‘gpgme_op_decrypt’ decrypts the ciphertext in the data
4348 object CIPHER and stores it into the data object PLAIN.
4350 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
4351 ciphertext could be decrypted successfully, ‘GPG_ERR_INV_VALUE’ if
4352 CTX, CIPHER or PLAIN is not a valid pointer, ‘GPG_ERR_NO_DATA’ if
4353 CIPHER does not contain any data to decrypt,
4354 ‘GPG_ERR_DECRYPT_FAILED’ if CIPHER is not a valid cipher text,
4355 ‘GPG_ERR_BAD_PASSPHRASE’ if the passphrase for the secret key could
4356 not be retrieved, and passes through any errors that are reported
4357 by the crypto engine support routines.
4359 -- Function: gpgme_error_t gpgme_op_decrypt_start (gpgme_ctx_t CTX,
4360 gpgme_data_t CIPHER, gpgme_data_t PLAIN)
4361 The function ‘gpgme_op_decrypt_start’ initiates a
4362 ‘gpgme_op_decrypt’ operation. It can be completed by calling
4363 ‘gpgme_wait’ on the context. *Note Waiting For Completion::.
4365 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
4366 operation could be started successfully, and ‘GPG_ERR_INV_VALUE’ if
4367 CIPHER or PLAIN is not a valid pointer.
4369 -- Data type: gpgme_recipient_t
4370 This is a pointer to a structure used to store information about
4371 the recipient of an encrypted text which is decrypted in a
4372 ‘gpgme_op_decrypt’ operation. This information (except for the
4373 status field) is even available before the operation finished
4374 successfully, for example in a passphrase callback. The structure
4375 contains the following members:
4377 ‘gpgme_recipient_t next’
4378 This is a pointer to the next recipient structure in the
4379 linked list, or ‘NULL’ if this is the last element.
4381 ‘gpgme_pubkey_algo_t’
4382 The public key algorithm used in the encryption.
4385 This is the key ID of the key (in hexadecimal digits) used as
4388 ‘gpgme_error_t status’
4389 This is an error number with the error code GPG_ERR_NO_SECKEY
4390 if the secret key for this recipient is not available, and 0
4393 -- Data type: gpgme_decrypt_result_t
4394 This is a pointer to a structure used to store the result of a
4395 ‘gpgme_op_decrypt’ operation. After successfully decrypting data,
4396 you can retrieve the pointer to the result with
4397 ‘gpgme_op_decrypt_result’. As with all result structures, it this
4398 structure shall be considered read-only and an application must not
4399 allocated such a strucure on its own. The structure contains the
4402 ‘char *unsupported_algorithm’
4403 If an unsupported algorithm was encountered, this string
4404 describes the algorithm that is not supported.
4406 ‘unsigned int wrong_key_usage : 1’
4407 This is true if the key was not used according to its policy.
4409 ‘gpgme_recipient_t recipients’
4410 This is a linked list of recipients to which this message was
4414 This is the filename of the original plaintext message file if
4415 it is known, otherwise this is a null pointer.
4418 A textual representation (nul-terminated string) of the
4419 session key used in symmetric encryption of the message, if
4420 the context has been set to export session keys (see
4421 ‘gpgme_set_ctx_flag, "export-session-key"’), and a session key
4422 was available for the most recent decryption operation.
4423 Otherwise, this is a null pointer.
4425 You must not try to access this member of the struct unless
4426 ‘gpgme_set_ctx_flag (ctx, "export-session-key")’ returns
4427 success or ‘gpgme_get_ctx_flag (ctx, "export-session-key")’
4428 returns true (non-empty string).
4430 -- Function: gpgme_decrypt_result_t gpgme_op_decrypt_result
4432 The function ‘gpgme_op_decrypt_result’ returns a
4433 ‘gpgme_decrypt_result_t’ pointer to a structure holding the result
4434 of a ‘gpgme_op_decrypt’ operation. The pointer is only valid if
4435 the last operation on the context was a ‘gpgme_op_decrypt’ or
4436 ‘gpgme_op_decrypt_start’ operation. If the operation failed this
4437 might be a ‘NULL’ pointer. The returned pointer is only valid
4438 until the next operation is started on the context.
4441 File: gpgme.info, Node: Verify, Next: Decrypt and Verify, Prev: Decrypt, Up: Crypto Operations
4446 -- Function: gpgme_error_t gpgme_op_verify (gpgme_ctx_t CTX,
4447 gpgme_data_t SIG, gpgme_data_t SIGNED_TEXT,
4449 The function ‘gpgme_op_verify’ verifies that the signature in the
4450 data object SIG is a valid signature. If SIG is a detached
4451 signature, then the signed text should be provided in SIGNED_TEXT
4452 and PLAIN should be a null pointer. Otherwise, if SIG is a normal
4453 (or cleartext) signature, SIGNED_TEXT should be a null pointer and
4454 PLAIN should be a writable data object that will contain the
4455 plaintext after successful verification.
4457 The results of the individual signature verifications can be
4458 retrieved with ‘gpgme_op_verify_result’.
4460 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
4461 operation could be completed successfully, ‘GPG_ERR_INV_VALUE’ if
4462 CTX, SIG or PLAIN is not a valid pointer, ‘GPG_ERR_NO_DATA’ if SIG
4463 does not contain any data to verify, and passes through any errors
4464 that are reported by the crypto engine support routines.
4466 -- Function: gpgme_error_t gpgme_op_verify_start (gpgme_ctx_t CTX,
4467 gpgme_data_t SIG, gpgme_data_t SIGNED_TEXT,
4469 The function ‘gpgme_op_verify_start’ initiates a ‘gpgme_op_verify’
4470 operation. It can be completed by calling ‘gpgme_wait’ on the
4471 context. *Note Waiting For Completion::.
4473 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
4474 operation could be started successfully, ‘GPG_ERR_INV_VALUE’ if
4475 CTX, SIG or PLAIN is not a valid pointer, and ‘GPG_ERR_NO_DATA’ if
4476 SIG or PLAIN does not contain any data to verify.
4478 -- Data type: gpgme_sig_notation_t
4479 This is a pointer to a structure used to store a part of the result
4480 of a ‘gpgme_op_verify’ operation. The structure contains the
4483 ‘gpgme_sig_notation_t next’
4484 This is a pointer to the next new signature notation structure
4485 in the linked list, or ‘NULL’ if this is the last element.
4488 The name of the notation field. If this is ‘NULL’, then the
4489 member ‘value’ will contain a policy URL.
4492 The length of the ‘name’ field. For strings the length is
4493 counted without the trailing binary zero.
4496 The value of the notation field. If ‘name’ is ‘NULL’, then
4497 this is a policy URL.
4500 The length of the ‘value’ field. For strings the length is
4501 counted without the trailing binary zero.
4503 ‘gpgme_sig_notation_flags_t flags’
4504 The accumulated flags field. This field contains the flags
4505 associated with the notation data in an accumulated form which
4506 can be used as an argument to the function
4507 ‘gpgme_sig_notation_add’. The value ‘flags’ is a bitwise-or
4508 combination of one or multiple of the following bit values:
4510 ‘GPGME_SIG_NOTATION_HUMAN_READABLE’
4511 The ‘GPGME_SIG_NOTATION_HUMAN_READABLE’ symbol specifies
4512 that the notation data is in human readable form
4514 ‘GPGME_SIG_NOTATION_CRITICAL’
4515 The ‘GPGME_SIG_NOTATION_CRITICAL’ symbol specifies that
4516 the notation data is critical.
4518 ‘unsigned int human_readable : 1’
4519 This is true if the ‘GPGME_SIG_NOTATION_HUMAN_READABLE’ flag
4520 is set and false otherwise. This flag is only valid for
4521 notation data, not for policy URLs.
4523 ‘unsigned int critical : 1’
4524 This is true if the ‘GPGME_SIG_NOTATION_CRITICAL’ flag is set
4525 and false otherwise. This flag is valid for notation data and
4528 -- Data type: gpgme_signature_t
4529 This is a pointer to a structure used to store a part of the result
4530 of a ‘gpgme_op_verify’ operation. The structure contains the
4533 ‘gpgme_signature_t next’
4534 This is a pointer to the next new signature structure in the
4535 linked list, or ‘NULL’ if this is the last element.
4537 ‘gpgme_sigsum_t summary’
4538 This is a bit vector giving a summary of the signature status.
4539 It provides an easy interface to a defined semantic of the
4540 signature status. Checking just one bit is sufficient to see
4541 whether a signature is valid without any restrictions.
4543 The defined bits are:
4544 ‘GPGME_SIGSUM_VALID’
4545 The signature is fully valid.
4547 ‘GPGME_SIGSUM_GREEN’
4548 The signature is good but one might want to display some
4549 extra information. Check the other bits.
4552 The signature is bad. It might be useful to check other
4553 bits and display more information, i.e. a revoked
4554 certificate might not render a signature invalid when the
4555 message was received prior to the cause for the
4558 ‘GPGME_SIGSUM_KEY_REVOKED’
4559 The key or at least one certificate has been revoked.
4561 ‘GPGME_SIGSUM_KEY_EXPIRED’
4562 The key or one of the certificates has expired. It is
4563 probably a good idea to display the date of the
4566 ‘GPGME_SIGSUM_SIG_EXPIRED’
4567 The signature has expired.
4569 ‘GPGME_SIGSUM_KEY_MISSING’
4570 Can’t verify due to a missing key or certificate.
4572 ‘GPGME_SIGSUM_CRL_MISSING’
4573 The CRL (or an equivalent mechanism) is not available.
4575 ‘GPGME_SIGSUM_CRL_TOO_OLD’
4576 Available CRL is too old.
4578 ‘GPGME_SIGSUM_BAD_POLICY’
4579 A policy requirement was not met.
4581 ‘GPGME_SIGSUM_SYS_ERROR’
4582 A system error occured.
4585 This is the fingerprint or key ID of the signature.
4587 ‘gpgme_error_t status’
4588 This is the status of the signature. In particular, the
4589 following status codes are of interest:
4592 This status indicates that the signature is valid. For
4593 the combined result this status means that all signatures
4596 ‘GPG_ERR_SIG_EXPIRED’
4597 This status indicates that the signature is valid but
4598 expired. For the combined result this status means that
4599 all signatures are valid and expired.
4601 ‘GPG_ERR_KEY_EXPIRED’
4602 This status indicates that the signature is valid but the
4603 key used to verify the signature has expired. For the
4604 combined result this status means that all signatures are
4605 valid and all keys are expired.
4607 ‘GPG_ERR_CERT_REVOKED’
4608 This status indicates that the signature is valid but the
4609 key used to verify the signature has been revoked. For
4610 the combined result this status means that all signatures
4611 are valid and all keys are revoked.
4613 ‘GPG_ERR_BAD_SIGNATURE’
4614 This status indicates that the signature is invalid. For
4615 the combined result this status means that all signatures
4619 This status indicates that the signature could not be
4620 verified due to a missing key. For the combined result
4621 this status means that all signatures could not be
4622 checked due to missing keys.
4625 This status indicates that there was some other error
4626 which prevented the signature verification.
4628 ‘gpgme_sig_notation_t notations’
4629 This is a linked list with the notation data and policy URLs.
4631 ‘unsigned long timestamp’
4632 The creation timestamp of this signature.
4634 ‘unsigned long exp_timestamp’
4635 The expiration timestamp of this signature, or 0 if the
4636 signature does not expire.
4638 ‘unsigned int wrong_key_usage : 1’
4639 This is true if the key was not used according to its policy.
4641 ‘unsigned int pka_trust : 2’
4642 This is set to the trust information gained by means of the
4643 PKA system. Values are:
4645 No PKA information available or verification not
4648 PKA verification failed.
4650 PKA verification succeeded.
4652 Reserved for future use.
4653 Depending on the configuration of the engine, this metric may
4654 also be reflected by the validity of the signature.
4656 ‘unsigned int chain_model : 1’
4657 This is true if the validity of the signature has been checked
4658 using the chain model. In the chain model the time the
4659 signature has been created must be within the validity period
4660 of the certificate and the time the certificate itself has
4661 been created must be within the validity period of the issuing
4662 certificate. In contrast the default validation model checks
4663 the validity of signature as well at the entire certificate
4664 chain at the current time.
4666 ‘gpgme_validity_t validity’
4667 The validity of the signature.
4669 ‘gpgme_error_t validity_reason’
4670 If a signature is not valid, this provides a reason why.
4672 ‘gpgme_pubkey_algo_t’
4673 The public key algorithm used to create this signature.
4676 The hash algorithm used to create this signature.
4679 The mailbox from the PKA information or ‘NULL’.
4682 An object describing the key used to create the signature.
4683 This key object may be incomplete in that it only conveys
4684 information availabale directly with a signature. It may also
4685 be ‘NULL’ if such information is not readily available.
4687 -- Data type: gpgme_verify_result_t
4688 This is a pointer to a structure used to store the result of a
4689 ‘gpgme_op_verify’ operation. After verifying a signature, you can
4690 retrieve the pointer to the result with ‘gpgme_op_verify_result’.
4691 If the operation failed this might be a ‘NULL’ pointer. The
4692 structure contains the following member:
4694 ‘gpgme_signature_t signatures’
4695 A linked list with information about all signatures for which
4696 a verification was attempted.
4699 This is the filename of the original plaintext message file if
4700 it is known, otherwise this is a null pointer.
4702 -- Function: gpgme_verify_result_t gpgme_op_verify_result
4704 The function ‘gpgme_op_verify_result’ returns a
4705 ‘gpgme_verify_result_t’ pointer to a structure holding the result
4706 of a ‘gpgme_op_verify’ operation. The pointer is only valid if the
4707 last operation on the context was a ‘gpgme_op_verify’,
4708 ‘gpgme_op_verify_start’, ‘gpgme_op_decrypt_verify’ or
4709 ‘gpgme_op_decrypt_verify_start’ operation, and if this operation
4710 finished successfully (for ‘gpgme_op_decrypt_verify’ and
4711 ‘gpgme_op_decrypt_verify_start’, the error code ‘GPG_ERR_NO_DATA’
4712 counts as successful in this context). The returned pointer is
4713 only valid until the next operation is started on the context.
4716 File: gpgme.info, Node: Decrypt and Verify, Next: Sign, Prev: Verify, Up: Crypto Operations
4718 7.7.3 Decrypt and Verify
4719 ------------------------
4721 -- Function: gpgme_error_t gpgme_op_decrypt_verify (gpgme_ctx_t CTX,
4722 gpgme_data_t CIPHER, gpgme_data_t PLAIN)
4723 The function ‘gpgme_op_decrypt_verify’ decrypts the ciphertext in
4724 the data object CIPHER and stores it into the data object PLAIN.
4725 If CIPHER contains signatures, they will be verified.
4727 After the operation completed, ‘gpgme_op_decrypt_result’ and
4728 ‘gpgme_op_verify_result’ can be used to retrieve more information
4729 about the signatures.
4731 If the error code ‘GPG_ERR_NO_DATA’ is returned, CIPHER does not
4732 contain any data to decrypt. However, it might still be signed.
4733 The information about detected signatures is available with
4734 ‘gpgme_op_verify_result’ in this case.
4736 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
4737 ciphertext could be decrypted successfully, ‘GPG_ERR_INV_VALUE’ if
4738 CTX, CIPHER or PLAIN is not a valid pointer, ‘GPG_ERR_NO_DATA’ if
4739 CIPHER does not contain any data to decrypt,
4740 ‘GPG_ERR_DECRYPT_FAILED’ if CIPHER is not a valid cipher text,
4741 ‘GPG_ERR_BAD_PASSPHRASE’ if the passphrase for the secret key could
4742 not be retrieved, and passes through any errors that are reported
4743 by the crypto engine support routines.
4745 -- Function: gpgme_error_t gpgme_op_decrypt_verify_start
4746 (gpgme_ctx_t CTX, gpgme_data_t CIPHER, gpgme_data_t PLAIN)
4747 The function ‘gpgme_op_decrypt_verify_start’ initiates a
4748 ‘gpgme_op_decrypt_verify’ operation. It can be completed by
4749 calling ‘gpgme_wait’ on the context. *Note Waiting For
4752 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
4753 operation could be started successfully, ‘GPG_ERR_INV_VALUE’ if
4754 CTX, CIPHER, PLAIN or R_STAT is not a valid pointer, and
4755 ‘GPG_ERR_NO_DATA’ if CIPHER does not contain any data to decrypt.
4757 When processing mails it is sometimes useful to extract the actual
4758 mail address (the “addr-spec”) from a string. GPGME provides this
4759 helper function which uses the same semantics as the internal functions
4762 -- Function: char * gpgme_addrspec_from_uid (const char *UID)
4764 Return the mail address (called “addr-spec” in RFC-5322) from the
4765 string UID which is assumed to be a user id (called “address” in
4766 RFC-5322). All plain ASCII characters (i.e. those with bit 7
4767 cleared) in the result are converted to lowercase. Caller must
4768 free the result using ‘gpgme_free’. Returns ‘NULL’ if no valid
4769 address was found (in which case ‘ERRNO’ is set to ‘EINVAL’) or for
4773 File: gpgme.info, Node: Sign, Next: Encrypt, Prev: Decrypt and Verify, Up: Crypto Operations
4778 A signature can contain signatures by one or more keys. The set of keys
4779 used to create a signatures is contained in a context, and is applied to
4780 all following signing operations in this context (until the set is
4785 * Selecting Signers:: How to choose the keys to sign with.
4786 * Creating a Signature:: How to create a signature.
4787 * Signature Notation Data:: How to add notation data to a signature.
4790 File: gpgme.info, Node: Selecting Signers, Next: Creating a Signature, Up: Sign
4792 7.7.4.1 Selecting Signers
4793 .........................
4795 The key or the keys used to create a signature are stored in the
4796 context. The following functions can be used to manipulate this list.
4797 If no signer has been set into the context a default key is used for
4800 -- Function: void gpgme_signers_clear (gpgme_ctx_t CTX)
4801 The function ‘gpgme_signers_clear’ releases a reference for each
4802 key on the signers list and removes the list of signers from the
4805 Every context starts with an empty list.
4807 -- Function: gpgme_error_t gpgme_signers_add (gpgme_ctx_t CTX,
4808 const gpgme_key_t KEY)
4809 The function ‘gpgme_signers_add’ adds the key KEY to the list of
4810 signers in the context CTX.
4812 Calling this function acquires an additional reference for the key.
4814 -- Function: unsigned int gpgme_signers_count (const gpgme_ctx_t CTX)
4815 The function ‘gpgme_signers_count’ returns the number of signer
4816 keys in the context CTX.
4818 -- Function: gpgme_key_t gpgme_signers_enum (const gpgme_ctx_t CTX,
4820 The function ‘gpgme_signers_enum’ returns the SEQth key in the list
4821 of signers in the context CTX. An additional reference is acquired
4824 If SEQ is out of range, ‘NULL’ is returned.
4827 File: gpgme.info, Node: Creating a Signature, Next: Signature Notation Data, Prev: Selecting Signers, Up: Sign
4829 7.7.4.2 Creating a Signature
4830 ............................
4832 -- Data type: enum gpgme_sig_mode_t
4833 The ‘gpgme_sig_mode_t’ type is used to specify the desired type of
4834 a signature. The following modes are available:
4836 ‘GPGME_SIG_MODE_NORMAL’
4837 A normal signature is made, the output includes the plaintext
4840 ‘GPGME_SIG_MODE_DETACH’
4841 A detached signature is made.
4843 ‘GPGME_SIG_MODE_CLEAR’
4844 A clear text signature is made. The ASCII armor and text mode
4845 settings of the context are ignored.
4847 -- Function: gpgme_error_t gpgme_op_sign (gpgme_ctx_t CTX,
4848 gpgme_data_t PLAIN, gpgme_data_t SIG, gpgme_sig_mode_t MODE)
4849 The function ‘gpgme_op_sign’ creates a signature for the text in
4850 the data object PLAIN and returns it in the data object SIG. The
4851 type of the signature created is determined by the ASCII armor (or,
4852 if that is not set, by the encoding specified for SIG), the text
4853 mode attributes set for the context CTX and the requested signature
4856 After the operation completed successfully, the result can be
4857 retrieved with ‘gpgme_op_sign_result’.
4859 If an S/MIME signed message is created using the CMS crypto engine,
4860 the number of certificates to include in the message can be
4861 specified with ‘gpgme_set_include_certs’. *Note Included
4864 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
4865 signature could be created successfully, ‘GPG_ERR_INV_VALUE’ if
4866 CTX, PLAIN or SIG is not a valid pointer, ‘GPG_ERR_NO_DATA’ if the
4867 signature could not be created, ‘GPG_ERR_BAD_PASSPHRASE’ if the
4868 passphrase for the secret key could not be retrieved,
4869 ‘GPG_ERR_UNUSABLE_SECKEY’ if there are invalid signers, and passes
4870 through any errors that are reported by the crypto engine support
4873 -- Function: gpgme_error_t gpgme_op_sign_start (gpgme_ctx_t CTX,
4874 gpgme_data_t PLAIN, gpgme_data_t SIG, gpgme_sig_mode_t MODE)
4875 The function ‘gpgme_op_sign_start’ initiates a ‘gpgme_op_sign’
4876 operation. It can be completed by calling ‘gpgme_wait’ on the
4877 context. *Note Waiting For Completion::.
4879 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
4880 operation could be started successfully, and ‘GPG_ERR_INV_VALUE’ if
4881 CTX, PLAIN or SIG is not a valid pointer.
4883 -- Data type: gpgme_new_signature_t
4884 This is a pointer to a structure used to store a part of the result
4885 of a ‘gpgme_op_sign’ operation. The structure contains the
4888 ‘gpgme_new_signature_t next’
4889 This is a pointer to the next new signature structure in the
4890 linked list, or ‘NULL’ if this is the last element.
4892 ‘gpgme_sig_mode_t type’
4893 The type of this signature.
4895 ‘gpgme_pubkey_algo_t pubkey_algo’
4896 The public key algorithm used to create this signature.
4898 ‘gpgme_hash_algo_t hash_algo’
4899 The hash algorithm used to create this signature.
4901 ‘unsigned int sig_class’
4902 The signature class of this signature.
4904 ‘long int timestamp’
4905 The creation timestamp of this signature.
4908 The fingerprint of the key which was used to create this
4911 -- Data type: gpgme_sign_result_t
4912 This is a pointer to a structure used to store the result of a
4913 ‘gpgme_op_sign’ operation. After successfully generating a
4914 signature, you can retrieve the pointer to the result with
4915 ‘gpgme_op_sign_result’. The structure contains the following
4918 ‘gpgme_invalid_key_t invalid_signers’
4919 A linked list with information about all invalid keys for
4920 which a signature could not be created.
4922 ‘gpgme_new_signature_t signatures’
4923 A linked list with information about all signatures created.
4925 -- Function: gpgme_sign_result_t gpgme_op_sign_result (gpgme_ctx_t CTX)
4926 The function ‘gpgme_op_sign_result’ returns a ‘gpgme_sign_result_t’
4927 pointer to a structure holding the result of a ‘gpgme_op_sign’
4928 operation. The pointer is only valid if the last operation on the
4929 context was a ‘gpgme_op_sign’, ‘gpgme_op_sign_start’,
4930 ‘gpgme_op_encrypt_sign’ or ‘gpgme_op_encrypt_sign_start’ operation.
4931 If that operation failed, the function might return a ‘NULL’
4932 pointer. The returned pointer is only valid until the next
4933 operation is started on the context.
4936 File: gpgme.info, Node: Signature Notation Data, Prev: Creating a Signature, Up: Sign
4938 7.7.4.3 Signature Notation Data
4939 ...............................
4941 Using the following functions, you can attach arbitrary notation data to
4942 a signature. This information is then available to the user when the
4943 signature is verified.
4945 -- Function: void gpgme_sig_notation_clear (gpgme_ctx_t CTX)
4946 The function ‘gpgme_sig_notation_clear’ removes the notation data
4947 from the context CTX. Subsequent signing operations from this
4948 context will not include any notation data.
4950 Every context starts with an empty notation data list.
4952 -- Function: gpgme_error_t gpgme_sig_notation_add (gpgme_ctx_t CTX,
4953 const char *NAME, const char *VALUE,
4954 gpgme_sig_notation_flags_t FLAGS)
4955 The function ‘gpgme_sig_notation_add’ adds the notation data with
4956 the name NAME and the value VALUE to the context CTX.
4958 Subsequent signing operations will include this notation data, as
4959 well as any other notation data that was added since the creation
4960 of the context or the last ‘gpgme_sig_notation_clear’ operation.
4962 The arguments NAME and VALUE must be ‘NUL’-terminated strings in
4963 human-readable form. The flag ‘GPGME_SIG_NOTATION_HUMAN_READABLE’
4964 is implied (non-human-readable notation data is currently not
4965 supported). The strings must be in UTF-8 encoding.
4967 If NAME is ‘NULL’, then VALUE should be a policy URL.
4969 The function ‘gpgme_sig_notation_add’ returns the error code
4970 ‘GPG_ERR_NO_ERROR’ if the notation data could be added
4971 successfully, ‘GPG_ERR_INV_VALUE’ if CTX is not a valid pointer, or
4972 if NAME, VALUE and FLAGS are an invalid combination. The function
4973 also passes through any errors that are reported by the crypto
4974 engine support routines.
4976 -- Function: gpgme_sig_notation_t gpgme_sig_notation_get
4977 (const gpgme_ctx_t CTX)
4978 The function ‘gpgme_sig_notation_get’ returns the linked list of
4979 notation data structures that are contained in the context CTX.
4981 If CTX is not a valid pointer, or there is no notation data added
4982 for this context, ‘NULL’ is returned.
4985 File: gpgme.info, Node: Encrypt, Prev: Sign, Up: Crypto Operations
4990 One plaintext can be encrypted for several recipients at the same time.
4991 The list of recipients is created independently of any context, and then
4992 passed to the encryption operation.
4996 * Encrypting a Plaintext:: How to encrypt a plaintext.
4999 File: gpgme.info, Node: Encrypting a Plaintext, Up: Encrypt
5001 7.7.5.1 Encrypting a Plaintext
5002 ..............................
5004 -- Function: gpgme_error_t gpgme_op_encrypt (gpgme_ctx_t CTX,
5005 gpgme_key_t RECP[], gpgme_encrypt_flags_t FLAGS,
5006 gpgme_data_t PLAIN, gpgme_data_t CIPHER)
5007 The function ‘gpgme_op_encrypt’ encrypts the plaintext in the data
5008 object PLAIN for the recipients RECP and stores the ciphertext in
5009 the data object CIPHER. The type of the ciphertext created is
5010 determined by the ASCII armor (or, if that is not set, by the
5011 encoding specified for CIPHER) and the text mode attributes set for
5014 RECP must be a ‘NULL’-terminated array of keys. The user must keep
5015 references for all keys during the whole duration of the call (but
5016 see ‘gpgme_op_encrypt_start’ for the requirements with the
5017 asynchronous variant).
5019 The value in FLAGS is a bitwise-or combination of one or multiple
5020 of the following bit values:
5022 ‘GPGME_ENCRYPT_ALWAYS_TRUST’
5023 The ‘GPGME_ENCRYPT_ALWAYS_TRUST’ symbol specifies that all the
5024 recipients in RECP should be trusted, even if the keys do not
5025 have a high enough validity in the keyring. This flag should
5026 be used with care; in general it is not a good idea to use any
5029 ‘GPGME_ENCRYPT_NO_ENCRYPT_TO’
5030 The ‘GPGME_ENCRYPT_NO_ENCRYPT_TO’ symbol specifies that no
5031 default or hidden default recipients as configured in the
5032 crypto backend should be included. This can be useful for
5033 managing different user profiles.
5035 ‘GPGME_ENCRYPT_NO_COMPRESS’
5036 The ‘GPGME_ENCRYPT_NO_COMPRESS’ symbol specifies that the
5037 plaintext shall not be compressed before it is encrypted.
5038 This is in some cases useful if the length of the encrypted
5039 message may reveal information about the plaintext.
5041 ‘GPGME_ENCRYPT_PREPARE’
5042 ‘GPGME_ENCRYPT_EXPECT_SIGN’
5043 The ‘GPGME_ENCRYPT_PREPARE’ symbol is used with the UI Server
5044 protocol to prepare an encryption (i.e. sending the
5045 ‘PREP_ENCRYPT’ command). With the ‘GPGME_ENCRYPT_EXPECT_SIGN’
5046 symbol the UI Server is advised to also expect a sign command.
5048 ‘GPGME_ENCRYPT_SYMMETRIC’
5049 The ‘GPGME_ENCRYPT_SYMMETRIC’ symbol specifies that the output
5050 should be additionally encrypted symmetically even if
5051 recipients are provided. This feature is only supported for
5052 for the OpenPGP crypto engine.
5054 If ‘GPG_ERR_UNUSABLE_PUBKEY’ is returned, some recipients in RECP
5055 are invalid, but not all. In this case the plaintext might be
5056 encrypted for all valid recipients and returned in CIPHER (if this
5057 happens depends on the crypto engine). More information about the
5058 invalid recipients is available with ‘gpgme_op_encrypt_result’.
5060 If RECP is ‘NULL’, symmetric rather than public key encryption is
5061 performed. Symmetrically encrypted cipher text can be deciphered
5062 with ‘gpgme_op_decrypt’. Note that in this case the crypto backend
5063 needs to retrieve a passphrase from the user. Symmetric encryption
5064 is currently only supported for the OpenPGP crypto backend.
5066 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
5067 ciphertext could be created successfully, ‘GPG_ERR_INV_VALUE’ if
5068 CTX, RECP, PLAIN or CIPHER is not a valid pointer,
5069 ‘GPG_ERR_UNUSABLE_PUBKEY’ if RECP contains some invalid recipients,
5070 ‘GPG_ERR_BAD_PASSPHRASE’ if the passphrase for the symmetric key
5071 could not be retrieved, and passes through any errors that are
5072 reported by the crypto engine support routines.
5074 -- Function: gpgme_error_t gpgme_op_encrypt_start (gpgme_ctx_t CTX,
5075 gpgme_key_t RECP[], gpgme_encrypt_flags_t FLAGS,
5076 gpgme_data_t PLAIN, gpgme_data_t CIPHER)
5077 The function ‘gpgme_op_encrypt_start’ initiates a
5078 ‘gpgme_op_encrypt’ operation. It can be completed by calling
5079 ‘gpgme_wait’ on the context. *Note Waiting For Completion::.
5081 References to the keys only need to be held for the duration of
5082 this call. The user can release its references to the keys after
5083 this function returns, even if the operation is not yet finished.
5085 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
5086 operation could be started successfully, ‘GPG_ERR_INV_VALUE’ if
5087 CTX, RSET, PLAIN or CIPHER is not a valid pointer, and
5088 ‘GPG_ERR_UNUSABLE_PUBKEY’ if RSET does not contain any valid
5091 -- Data type: gpgme_encrypt_result_t
5092 This is a pointer to a structure used to store the result of a
5093 ‘gpgme_op_encrypt’ operation. After successfully encrypting data,
5094 you can retrieve the pointer to the result with
5095 ‘gpgme_op_encrypt_result’. The structure contains the following
5098 ‘gpgme_invalid_key_t invalid_recipients’
5099 A linked list with information about all invalid keys for
5100 which the data could not be encrypted.
5102 -- Function: gpgme_encrypt_result_t gpgme_op_encrypt_result
5104 The function ‘gpgme_op_encrypt_result’ returns a
5105 ‘gpgme_encrypt_result_t’ pointer to a structure holding the result
5106 of a ‘gpgme_op_encrypt’ operation. The pointer is only valid if
5107 the last operation on the context was a ‘gpgme_op_encrypt’,
5108 ‘gpgme_op_encrypt_start’, ‘gpgme_op_sign’ or ‘gpgme_op_sign_start’
5109 operation. If this operation failed, this might be a ‘NULL’
5110 pointer. The returned pointer is only valid until the next
5111 operation is started on the context.
5113 -- Function: gpgme_error_t gpgme_op_encrypt_sign (gpgme_ctx_t CTX,
5114 gpgme_key_t RECP[], gpgme_encrypt_flags_t FLAGS,
5115 gpgme_data_t PLAIN, gpgme_data_t CIPHER)
5116 The function ‘gpgme_op_encrypt_sign’ does a combined encrypt and
5117 sign operation. It is used like ‘gpgme_op_encrypt’, but the
5118 ciphertext also contains signatures for the signers listed in CTX.
5120 The combined encrypt and sign operation is currently only available
5121 for the OpenPGP crypto engine.
5123 -- Function: gpgme_error_t gpgme_op_encrypt_sign_start
5124 (gpgme_ctx_t CTX, gpgme_key_t RECP,
5125 gpgme_encrypt_flags_t FLAGS, gpgme_data_t PLAIN,
5126 gpgme_data_t CIPHER)
5127 The function ‘gpgme_op_encrypt_sign_start’ initiates a
5128 ‘gpgme_op_encrypt_sign’ operation. It can be completed by calling
5129 ‘gpgme_wait’ on the context. *Note Waiting For Completion::.
5131 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
5132 operation could be started successfully, and ‘GPG_ERR_INV_VALUE’ if
5133 CTX, RSET, PLAIN or CIPHER is not a valid pointer.
5136 File: gpgme.info, Node: Miscellaneous, Next: Run Control, Prev: Crypto Operations, Up: Contexts
5138 7.8 Miscellaneous operations
5139 ============================
5141 Here are some support functions which are sometimes useful.
5145 * Running other Programs:: Running other Programs
5146 * Using the Assuan protocol:: Using the Assuan protocol
5147 * Checking for updates:: How to check for software updates
5150 File: gpgme.info, Node: Running other Programs, Next: Using the Assuan protocol, Up: Miscellaneous
5152 7.8.1 Running other Programs
5153 ----------------------------
5155 GPGME features an internal subsystem to run the actual backend engines.
5156 Along with data abstraction object this subsystem can be used to run
5157 arbitrary simple programs which even need not be related to
5158 cryptographic features. It may for example be used to run tools which
5159 are part of the GnuPG system but are not directly accessible with the
5162 -- Function: gpgme_error_t gpgme_op_spawn (gpgme_ctx_t CTX,
5163 const char *FILE, const char *ARGV[], gpgme_data_t DATAIN,
5164 gpgme_data_t DATAOUT, gpgme_data_t DATAERR,
5167 The function ‘gpgme_op_spawn’ runs the program FILE with the
5168 arguments taken from the NULL terminated array ARGV. If no
5169 arguments are required ARGV may be given as ‘NULL’. In the latter
5170 case or if ‘argv[0]’ is the empty string, GPGME uses the basename
5171 of FILE for ‘argv[0]’. The file descriptors ‘stdin’, ‘stdout’, and
5172 ‘stderr’ are connected to the data objects DATAIN, DATAOUT, and
5173 DATAERR. If NULL is passed for one of these data objects the
5174 corresponding file descriptor is connected to ‘/dev/null’.
5176 The value in FLAGS is a bitwise-or combination of one or multiple
5177 of the following bit values:
5179 ‘GPGME_SPAWN_DETACHED’
5180 Under Windows this flag inhibits the allocation of a new
5181 console for the program. This is useful for a GUI application
5182 which needs to call a command line helper tool.
5183 ‘GPGME_SPAWN_ALLOW_SET_FG’
5184 Under Windows this flag allows the called program to put
5185 itself into the foreground.
5187 -- Function: gpgme_error_t gpgme_op_spawn_start (gpgme_ctx_t CTX,
5188 const char *FILE, const char *ARGV[], gpgme_data_t DATAIN,
5189 gpgme_data_t DATAOUT, gpgme_data_t DATAERR,
5192 This is the asynchronous variant of ‘gpgme_op_spawn’.
5195 File: gpgme.info, Node: Using the Assuan protocol, Next: Checking for updates, Prev: Running other Programs, Up: Miscellaneous
5197 7.8.2 Using the Assuan protocol
5198 -------------------------------
5200 The Assuan protocol can be used to talk to arbitrary Assuan servers. By
5201 default it is connected to the GnuPG agent, but it may be connected to
5202 arbitrary servers by using ‘gpgme_ctx_set_engine_info’, passing the
5203 location of the servers socket as FILE_NAME argument, and an empty
5204 string as HOME_DIR argument.
5206 The Assuan protocol functions use three kinds of callbacks to
5209 -- Data type: gpgme_error_t (*gpgme_assuan_data_cb_t) (void *OPAQUE,
5210 const void *DATA, size_t DATALEN)
5212 This callback receives any data sent by the server. OPAQUE is the
5213 pointer passed to ‘gpgme_op_assuan_transact_start’, DATA of length
5214 DATALEN refers to the data sent.
5216 -- Data type: gpgme_error_t (*gpgme_assuan_inquire_cb_t) (void *OPAQUE,
5217 const char *NAME, const char *ARGS, gpgme_data_t *R_DATA)
5219 This callback is used to provide additional data to the Assuan
5220 server. OPAQUE is the pointer passed to
5221 ‘gpgme_op_assuan_transact_start’, NAME and ARGS specify what kind
5222 of data the server requested, and R_DATA is used to return the
5225 Note: Returning data is currently not implemented in GPGME.
5227 -- Data type: gpgme_error_t (*gpgme_assuan_status_cb_t) (void *OPAQUE,
5228 const char *STATUS, const char *ARGS)
5230 This callback receives any status lines sent by the server. OPAQUE
5231 is the pointer passed to ‘gpgme_op_assuan_transact_start’, STATUS
5232 and ARGS denote the status update sent.
5234 -- Function: gpgme_error_t gpgme_op_assuan_transact_start
5235 (gpgme_ctx_t CTX, const char *COMMAND,
5236 gpgme_assuan_data_cb_t DATA_CB, void * DATA_CB_VALUE,
5237 gpgme_assuan_inquire_cb_t INQUIRE_CB, void * INQUIRE_CB_VALUE,
5238 gpgme_assuan_status_cb_t STATUS_CB, void * STATUS_CB_VALUE)
5240 Send the Assuan COMMAND and return results via the callbacks. Any
5241 callback may be ‘NULL’. The result of the operation may be
5242 retrieved using ‘gpgme_wait_ext’.
5244 Asynchronous variant.
5246 -- Function: gpgme_error_t gpgme_op_assuan_transact_ext
5247 (gpgme_ctx_t CTX, const char *COMMAND,
5248 gpgme_assuan_data_cb_t DATA_CB, void * DATA_CB_VALUE,
5249 gpgme_assuan_inquire_cb_t INQUIRE_CB, void * INQUIRE_CB_VALUE,
5250 gpgme_assuan_status_cb_t STATUS_CB, void * STATUS_CB_VALUE,
5251 gpgme_error_t *OP_ERR)
5253 Send the Assuan COMMAND and return results via the callbacks. The
5254 result of the operation is returned in OP_ERR.
5256 Synchronous variant.
5259 File: gpgme.info, Node: Checking for updates, Prev: Using the Assuan protocol, Up: Miscellaneous
5261 7.8.3 How to check for software updates
5262 ---------------------------------------
5264 The GnuPG Project operates a server to query the current versions of
5265 software packages related to GnuPG. GPGME can be used to access this
5266 online database and check whether a new version of a software package is
5269 -- Data type: gpgme_query_swdb_result_t
5270 This is a pointer to a structure used to store the result of a
5271 ‘gpgme_op_query_swdb’ operation. After success full call to that
5272 function, you can retrieve the pointer to the result with
5273 ‘gpgme_op_query_swdb_result’. The structure contains the following
5277 This is the name of the package.
5280 The currently installed version or an empty string. This
5281 value is either a copy of the argument given to
5282 ‘gpgme_op_query_swdb’ or the version of the installed software
5283 as figured out by GPGME or GnuPG.
5286 This gives the date the file with the list of version numbers
5287 has originally be created by the GnuPG project.
5290 This gives the date the file was downloaded.
5293 If this flag is set either an error has occurred or some of
5294 the information in this structure are not properly set. For
5295 example if the version number of the installed software could
5296 not be figured out, the ‘update’ flag may not reflect a
5297 required update status.
5300 If this flag is set an update of the software is available.
5303 If this flag is set an available update is important.
5306 If this flag is set, no valid information could be retrieved.
5309 If this flag is set the given ‘name’ is not known.
5312 If this flag is set the available information is not fresh
5316 If this flag is set some other error has occured.
5319 The version string of the latest released version.
5322 The release date of the latest released version.
5324 -- Function: gpgme_error_t gpgme_op_query_swdb (gpgme_ctx_t CTX,
5325 const char *NAME, const char *IVERSION, gpgme_data_t RESERVED)
5327 Query the software version database for software package NAME and
5328 check against the installed version given by IVERSION. If IVERSION
5329 is given as ‘NULL’ a check is only done if GPGME can figure out the
5330 version by itself (for example when using "gpgme" or "gnupg"). If
5331 ‘NULL’ is used for NAME the current gpgme version is checked.
5332 RESERVED must be set to 0.
5334 -- Function: gpgme_query_swdb_result_t gpgme_op_query_swdb_result
5337 The function ‘gpgme_op_query_swdb_result’ returns a
5338 ‘gpgme_query_swdb_result_t’ pointer to a structure holding the
5339 result of a ‘gpgme_op_query_swdb’ operation. The pointer is only
5340 valid if the last operation on the context was a sucessful call to
5341 ‘gpgme_op_query_swdb’. If that call failed, the result might be a
5342 ‘NULL’ pointer. The returned pointer is only valid until the next
5343 operation is started on the context CTX.
5345 Here is an example on how to check whether GnuPG is current:
5354 gpgme_query_swdb_result_t result;
5356 gpgme_check_version (NULL);
5357 err = gpgme_new (&ctx);
5359 fprintf (stderr, "error creating context: %s\n", gpg_strerror (err));
5362 gpgme_set_protocol (ctx, GPGME_PROTOCOL_GPGCONF);
5364 err = gpgme_op_query_swdb (ctx, "gnupg", NULL, 0);
5366 fprintf (stderr, "error querying swdb: %s\n", gpg_strerror (err));
5369 result = gpgme_op_query_swdb_result (ctx);
5371 fprintf (stderr, "error querying swdb\n");
5372 if (!result->warning && !result->update)
5373 printf ("GnuPG version %s is current\n",
5375 else if (!result->warning && result->update)
5376 printf ("GnuPG version %s can be updated to %s\n",
5377 result->iversion, result->version);
5379 fprintf (stderr, "error finding the update status\n");
5381 gpgme_release (ctx);
5387 File: gpgme.info, Node: Run Control, Prev: Miscellaneous, Up: Contexts
5392 GPGME supports running operations synchronously and asynchronously. You
5393 can use asynchronous operation to set up a context up to initiating the
5394 desired operation, but delay performing it to a later point.
5396 Furthermore, you can use an external event loop to control exactly
5397 when GPGME runs. This ensures that GPGME only runs when necessary and
5398 also prevents it from blocking for a long time.
5402 * Waiting For Completion:: Waiting until an operation is completed.
5403 * Using External Event Loops:: Advanced control over what happens when.
5404 * Cancellation:: How to end pending operations prematurely.
5407 File: gpgme.info, Node: Waiting For Completion, Next: Using External Event Loops, Up: Run Control
5409 7.9.1 Waiting For Completion
5410 ----------------------------
5412 -- Function: gpgme_ctx_t gpgme_wait (gpgme_ctx_t CTX,
5413 gpgme_error_t *STATUS, int HANG)
5414 The function ‘gpgme_wait’ continues the pending operation within
5415 the context CTX. In particular, it ensures the data exchange
5416 between GPGME and the crypto backend and watches over the run time
5417 status of the backend process.
5419 If HANG is true, the function does not return until the operation
5420 is completed or cancelled. Otherwise the function will not block
5423 The error status of the finished operation is returned in STATUS if
5424 ‘gpgme_wait’ does not return ‘NULL’.
5426 The CTX argument can be ‘NULL’. In that case, ‘gpgme_wait’ waits
5427 for any context to complete its operation.
5429 ‘gpgme_wait’ can be used only in conjunction with any context that
5430 has a pending operation initiated with one of the
5431 ‘gpgme_op_*_start’ functions except ‘gpgme_op_keylist_start’ and
5432 ‘gpgme_op_trustlist_start’ (for which you should use the
5433 corresponding ‘gpgme_op_*_next’ functions). If CTX is ‘NULL’, all
5434 of such contexts are waited upon and possibly returned.
5435 Synchronous operations running in parallel, as well as key and
5436 trust item list operations, do not affect ‘gpgme_wait’.
5438 In a multi-threaded environment, only one thread should ever call
5439 ‘gpgme_wait’ at any time, irregardless if CTX is specified or not.
5440 This means that all calls to this function should be fully
5441 synchronized by locking primitives. It is safe to start
5442 asynchronous operations while a thread is running in ‘gpgme_wait’.
5444 The function returns the CTX of the context which has finished the
5445 operation. If HANG is false, and the timeout expires, ‘NULL’ is
5446 returned and ‘*status’ will be set to 0. If an error occurs,
5447 ‘NULL’ is returned and the error is returned in ‘*status’.
5450 File: gpgme.info, Node: Using External Event Loops, Next: Cancellation, Prev: Waiting For Completion, Up: Run Control
5452 7.9.2 Using External Event Loops
5453 --------------------------------
5455 GPGME hides the complexity of the communication between the library and
5456 the crypto engine. The price of this convenience is that the calling
5457 thread can block arbitrary long waiting for the data returned by the
5458 crypto engine. In single-threaded programs, in particular if they are
5459 interactive, this is an unwanted side-effect. OTOH, if ‘gpgme_wait’ is
5460 used without the HANG option being enabled, it might be called
5461 unnecessarily often, wasting CPU time that could be used otherwise.
5463 The I/O callback interface described in this section lets the user
5464 take control over what happens when. GPGME will provide the user with
5465 the file descriptors that should be monitored, and the callback
5466 functions that should be invoked when a file descriptor is ready for
5467 reading or writing. It is then the user’s responsibility to decide when
5468 to check the file descriptors and when to invoke the callback functions.
5469 Usually this is done in an event loop, that also checks for events in
5470 other parts of the program. If the callback functions are only called
5471 when the file descriptors are ready, GPGME will never block. This gives
5472 the user more control over the program flow, and allows to perform other
5473 tasks when GPGME would block otherwise.
5475 By using this advanced mechanism, GPGME can be integrated smoothly
5476 into GUI toolkits like GTK+ even for single-threaded programs.
5480 * I/O Callback Interface:: How I/O callbacks are registered.
5481 * Registering I/O Callbacks:: How to use I/O callbacks for a context.
5482 * I/O Callback Example:: An example how to use I/O callbacks.
5483 * I/O Callback Example GTK+:: How to use GPGME with GTK+.
5484 * I/O Callback Example GDK:: How to use GPGME with GDK.
5485 * I/O Callback Example Qt:: How to use GPGME with Qt.
5488 File: gpgme.info, Node: I/O Callback Interface, Next: Registering I/O Callbacks, Up: Using External Event Loops
5490 7.9.2.1 I/O Callback Interface
5491 ..............................
5493 -- Data type: gpgme_error_t (*gpgme_io_cb_t) (void *DATA, int FD)
5494 The ‘gpgme_io_cb_t’ type is the type of functions which GPGME wants
5495 to register as I/O callback handlers using the
5496 ‘gpgme_register_io_cb_t’ functions provided by the user.
5498 DATA and FD are provided by GPGME when the I/O callback handler is
5499 registered, and should be passed through to the handler when it is
5500 invoked by the user because it noticed activity on the file
5503 The callback handler always returns ‘0’, but you should consider
5504 the return value to be reserved for later use.
5506 -- Data type: gpgme_error_t (*gpgme_register_io_cb_t) (void *DATA,
5507 int FD, int DIR, gpgme_io_cb_t FNC, void *FNC_DATA,
5509 The ‘gpgme_register_io_cb_t’ type is the type of functions which
5510 can be called by GPGME to register an I/O callback function FNC for
5511 the file descriptor FD with the user. FNC_DATA should be passed as
5512 the first argument to FNC when the handler is invoked (the second
5513 argument should be FD). If DIR is 0, FNC should be called by the
5514 user when FD is ready for writing. If DIR is 1, FNC should be
5515 called when FD is ready for reading.
5517 DATA was provided by the user when registering the
5518 ‘gpgme_register_io_cb_t’ function with GPGME and will always be
5519 passed as the first argument when registering a callback function.
5520 For example, the user can use this to determine the event loop to
5521 which the file descriptor should be added.
5523 GPGME will call this function when a crypto operation is initiated
5524 in a context for which the user has registered I/O callback handler
5525 functions with ‘gpgme_set_io_cbs’. It can also call this function
5526 when it is in an I/O callback handler for a file descriptor
5527 associated to this context.
5529 The user should return a unique handle in TAG identifying this I/O
5530 callback registration, which will be passed to the
5531 ‘gpgme_register_io_cb_t’ function without interpretation when the
5532 file descriptor should not be monitored anymore.
5534 -- Data type: void (*gpgme_remove_io_cb_t) (void *TAG)
5535 The ‘gpgme_remove_io_cb_t’ type is the type of functions which can
5536 be called by GPGME to remove an I/O callback handler that was
5537 registered before. TAG is the handle that was returned by the
5538 ‘gpgme_register_io_cb_t’ for this I/O callback.
5540 GPGME can call this function when a crypto operation is in an I/O
5541 callback. It will also call this function when the context is
5542 destroyed while an operation is pending.
5544 -- Data type: enum gpgme_event_io_t
5545 The ‘gpgme_event_io_t’ type specifies the type of an event that is
5546 reported to the user by GPGME as a consequence of an I/O operation.
5547 The following events are defined:
5550 The operation is fully initialized now, and you can start to
5551 run the registered I/O callback handlers now. Note that
5552 registered I/O callback handlers must not be run before this
5553 event is signalled. TYPE_DATA is ‘NULL’ and reserved for
5557 The operation is finished, the last I/O callback for this
5558 operation was removed. The accompanying TYPE_DATA points to a
5559 ‘struct gpgme_io_event_done_data’ variable that contains the
5560 status of the operation that finished. This event is
5561 signalled after the last I/O callback has been removed.
5563 ‘GPGME_EVENT_NEXT_KEY’
5564 In a ‘gpgme_op_keylist_start’ operation, the next key was
5565 received from the crypto engine. The accompanying TYPE_DATA
5566 is a ‘gpgme_key_t’ variable that contains the key with one
5567 reference for the user.
5569 ‘GPGME_EVENT_NEXT_TRUSTITEM’
5570 In a ‘gpgme_op_trustlist_start’ operation, the next trust item
5571 was received from the crypto engine. The accompanying
5572 TYPE_DATA is a ‘gpgme_trust_item_t’ variable that contains the
5573 trust item with one reference for the user.
5575 -- Data type: void (*gpgme_event_io_cb_t) (void *DATA,
5576 gpgme_event_io_t TYPE, void *TYPE_DATA)
5577 The ‘gpgme_event_io_cb_t’ type is the type of functions which can
5578 be called by GPGME to signal an event for an operation running in a
5579 context which has I/O callback functions registered by the user.
5581 DATA was provided by the user when registering the
5582 ‘gpgme_event_io_cb_t’ function with GPGME and will always be passed
5583 as the first argument when registering a callback function. For
5584 example, the user can use this to determine the context in which
5585 this event has occured.
5587 TYPE will specify the type of event that has occured. TYPE_DATA
5588 specifies the event further, as described in the above list of
5589 possible ‘gpgme_event_io_t’ types.
5591 GPGME can call this function in an I/O callback handler.
5594 File: gpgme.info, Node: Registering I/O Callbacks, Next: I/O Callback Example, Prev: I/O Callback Interface, Up: Using External Event Loops
5596 7.9.2.2 Registering I/O Callbacks
5597 .................................
5599 -- Data type: struct gpgme_io_cbs
5600 This structure is used to store the I/O callback interface
5601 functions described in the previous section. It has the following
5604 ‘gpgme_register_io_cb_t add’
5605 This is the function called by GPGME to register an I/O
5606 callback handler. It must be specified.
5609 This is passed as the first argument to the ‘add’ function
5610 when it is called by GPGME. For example, it can be used to
5611 determine the event loop to which the file descriptor should
5614 ‘gpgme_remove_io_cb_t remove’
5615 This is the function called by GPGME to remove an I/O callback
5616 handler. It must be specified.
5618 ‘gpgme_event_io_cb_t event’
5619 This is the function called by GPGME to signal an event for an
5620 operation. It must be specified, because at least the start
5621 event must be processed.
5624 This is passed as the first argument to the ‘event’ function
5625 when it is called by GPGME. For example, it can be used to
5626 determine the context in which the event has occured.
5628 -- Function: void gpgme_set_io_cbs (gpgme_ctx_t CTX,
5629 struct gpgme_io_cbs *IO_CBS)
5630 The function ‘gpgme_set_io_cbs’ enables the I/O callback interface
5631 for the context CTX. The I/O callback functions are specified by
5634 If IO_CBS->‘add’ is ‘NULL’, the I/O callback interface is disabled
5635 for the context, and normal operation is restored.
5637 -- Function: void gpgme_get_io_cbs (gpgme_ctx_t CTX,
5638 struct gpgme_io_cbs *IO_CBS)
5639 The function ‘gpgme_get_io_cbs’ returns the I/O callback functions
5640 set with ‘gpgme_set_io_cbs’ in IO_CBS.
5643 File: gpgme.info, Node: I/O Callback Example, Next: I/O Callback Example GTK+, Prev: Registering I/O Callbacks, Up: Using External Event Loops
5645 7.9.2.3 I/O Callback Example
5646 ............................
5648 To actually use an external event loop, you have to implement the I/O
5649 callback functions that are used by GPGME to register and unregister
5650 file descriptors. Furthermore, you have to actually monitor these file
5651 descriptors for activity and call the appropriate I/O callbacks.
5653 The following example illustrates how to do that. The example uses
5654 locking to show in which way the callbacks and the event loop can run
5655 concurrently. For the event loop, we use a fixed array. For a
5656 real-world implementation, you should use a dynamically sized structure
5657 because the number of file descriptors needed for a crypto operation in
5658 GPGME is not predictable.
5663 #include <pthread.h>
5664 #include <sys/types.h>
5667 /* The following structure holds the result of a crypto operation. */
5674 /* The following structure holds the data associated with one I/O
5687 pthread_mutex_t lock;
5689 /* Unused slots are marked with FD being -1. */
5690 struct one_fd fds[MAX_FDS];
5693 The following functions implement the I/O callback interface.
5696 add_io_cb (void *data, int fd, int dir, gpgme_io_cb_t fnc, void *fnc_data,
5699 struct event_loop *loop = data;
5700 struct one_fd *fds = loop->fds;
5703 pthread_mutex_lock (&loop->lock);
5704 for (i = 0; i < MAX_FDS; i++)
5706 if (fds[i].fd == -1)
5711 fds[i].fnc_data = fnc_data;
5716 pthread_mutex_unlock (&loop->lock);
5718 return gpg_error (GPG_ERR_GENERAL);
5724 remove_io_cb (void *tag)
5726 struct one_fd *fd = tag;
5727 struct event_loop *loop = fd->loop;
5729 pthread_mutex_lock (&loop->lock);
5731 pthread_mutex_unlock (&loop->lock);
5735 event_io_cb (void *data, gpgme_event_io_t type, void *type_data)
5737 struct op_result *result = data;
5739 /* We don't support list operations here. */
5740 if (type == GPGME_EVENT_DONE)
5743 result->err = *type_data;
5747 The final missing piece is the event loop, which will be presented
5748 next. We only support waiting for the success of a single operation.
5751 do_select (struct event_loop *loop)
5758 struct one_fd *fdlist = loop->fds;
5760 pthread_mutex_lock (&loop->lock);
5763 for (i = 0; i < MAX_FDS; i++)
5764 if (fdlist[i].fd != -1)
5765 FD_SET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds);
5766 pthread_mutex_unlock (&loop->lock);
5773 n = select (FD_SETSIZE, &rfds, &wfds, NULL, &tv);
5775 while (n < 0 && errno == EINTR);
5778 return n; /* Error or timeout. */
5780 pthread_mutex_lock (&loop->lock);
5781 for (i = 0; i < MAX_FDS && n; i++)
5783 if (fdlist[i].fd != -1)
5785 if (FD_ISSET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds))
5790 /* The I/O callback handler can register/remove callbacks,
5791 so we have to unlock the file descriptor list. */
5792 pthread_mutex_unlock (&loop->lock);
5793 (*fdlist[i].fnc) (fdlist[i].fnc_data, fdlist[i].fd);
5794 pthread_mutex_lock (&loop->lock);
5798 pthread_mutex_unlock (&loop->lock);
5803 wait_for_op (struct event_loop *loop, struct op_result *result)
5809 ret = do_select (loop);
5811 while (ret >= 0 && !result->done);
5814 The main function shows how to put it all together.
5817 main (int argc, char *argv[])
5819 struct event_loop loop;
5820 struct op_result result;
5823 gpgme_data_t sig, text;
5825 pthread_mutexattr_t attr;
5826 struct gpgme_io_cbs io_cbs =
5837 /* Initialize the loop structure. */
5839 /* The mutex must be recursive, since remove_io_cb (which acquires a
5840 lock) can be called while holding a lock acquired in do_select. */
5841 pthread_mutexattr_init (&attr);
5842 pthread_mutexattr_settype (&attr, PTHREAD_MUTEX_RECURSIVE);
5843 pthread_mutex_init (&loop.lock, &attr);
5844 pthread_mutexattr_destroy (&attr);
5846 for (i = 0; i < MAX_FDS; i++)
5847 loop.fds[i].fd = -1;
5849 /* Initialize the result structure. */
5852 err = gpgme_data_new_from_file (&sig, "signature", 1);
5854 err = gpgme_data_new_from_file (&text, "text", 1);
5856 err = gpgme_new (&ctx);
5859 gpgme_set_io_cbs (ctx, &io_cbs);
5860 err = gpgme_op_verify_start (ctx, sig, text, NULL);
5864 fprintf (stderr, "gpgme error: %s: %s\n",
5865 gpgme_strsource (err), gpgme_strerror (err));
5869 wait_for_op (&loop, &result);
5872 fprintf (stderr, "select error\n");
5877 fprintf (stderr, "verification failed: %s: %s\n",
5878 gpgme_strsource (result.err), gpgme_strerror (result.err));
5881 /* Evaluate verify result. */
5887 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
5889 7.9.2.4 I/O Callback Example GTK+
5890 .................................
5892 The I/O callback interface can be used to integrate GPGME with the GTK+
5893 event loop. The following code snippets shows how this can be done
5894 using the appropriate register and remove I/O callback functions. In
5895 this example, the private data of the register I/O callback function is
5896 unused. The event notifications is missing because it does not require
5897 any GTK+ specific setup.
5899 #include <gtk/gtk.h>
5901 struct my_gpgme_io_cb
5905 guint input_handler_id
5909 my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition)
5911 struct my_gpgme_io_cb *iocb = data;
5912 (*(iocb->fnc)) (iocb->data, source);
5916 my_gpgme_remove_io_cb (void *data)
5918 struct my_gpgme_io_cb *iocb = data;
5919 gtk_input_remove (data->input_handler_id);
5923 my_gpgme_register_io_callback (void *data, int fd, int dir, gpgme_io_cb_t fnc,
5924 void *fnc_data, void **tag)
5926 struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb));
5928 iocb->data = fnc_data;
5929 iocb->input_handler_id = gtk_input_add_full (fd, dir
5932 my_gpgme_io_callback,
5939 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
5941 7.9.2.5 I/O Callback Example GDK
5942 ................................
5944 The I/O callback interface can also be used to integrate GPGME with the
5945 GDK event loop. The following code snippets shows how this can be done
5946 using the appropriate register and remove I/O callback functions. In
5947 this example, the private data of the register I/O callback function is
5948 unused. The event notifications is missing because it does not require
5949 any GDK specific setup.
5951 It is very similar to the GTK+ example in the previous section.
5953 #include <gdk/gdk.h>
5955 struct my_gpgme_io_cb
5963 my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition)
5965 struct my_gpgme_io_cb *iocb = data;
5966 (*(iocb->fnc)) (iocb->data, source);
5970 my_gpgme_remove_io_cb (void *data)
5972 struct my_gpgme_io_cb *iocb = data;
5973 gdk_input_remove (data->tag);
5977 my_gpgme_register_io_callback (void *data, int fd, int dir, gpgme_io_cb_t fnc,
5978 void *fnc_data, void **tag)
5980 struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb));
5982 iocb->data = fnc_data;
5983 iocb->tag = gtk_input_add_full (fd, dir ? GDK_INPUT_READ : GDK_INPUT_WRITE,
5984 my_gpgme_io_callback, iocb, NULL);
5990 File: gpgme.info, Node: I/O Callback Example Qt, Prev: I/O Callback Example GDK, Up: Using External Event Loops
5992 7.9.2.6 I/O Callback Example Qt
5993 ...............................
5995 The I/O callback interface can also be used to integrate GPGME with the
5996 Qt event loop. The following code snippets show how this can be done
5997 using the appropriate register and remove I/O callback functions. In
5998 this example, the private data of the register I/O callback function is
5999 unused. The event notifications is missing because it does not require
6000 any Qt specific setup.
6002 #include <qsocketnotifier.h>
6003 #include <qapplication.h>
6006 IOCB( GpgmeIOCb f, void * d, QSocketNotifier * n )
6007 : func( f ), data( d ), notifier( n ) {}
6010 QSocketNotifier * notifier;
6013 class MyApp : public QApplication {
6017 static void registerGpgmeIOCallback( void * data, int fd, int dir,
6018 GpgmeIOCb func, void * func_data,
6020 QSocketNotifier * n =
6021 new QSocketNotifier( fd, dir ? QSocketNotifier::Read
6022 : QSocketNotifier::Write );
6023 connect( n, SIGNAL(activated(int)),
6024 qApp, SLOT(slotGpgmeIOCallback(int)) );
6025 qApp->mIOCBs.push_back( IOCB( func, func_data, n ) );
6029 static void removeGpgmeIOCallback( void * tag ) {
6031 QSocketNotifier * n = static_cast<QSocketNotifier*>( tag );
6032 for ( QValueList<IOCB>::iterator it = qApp->mIOCBs.begin() ;
6033 it != qApp->mIOCBs.end() ; ++it )
6034 if ( it->notifier == n ) {
6035 delete it->notifier;
6036 qApp->mIOCBs.erase( it );
6042 void slotGpgmeIOCallback( int fd ) {
6043 for ( QValueList<IOCB>::const_iterator it = mIOCBs.begin() ;
6044 it != mIOCBs.end() ; ++it )
6045 if ( it->notifier && it->notifier->socket() == fd )
6046 (*(it->func)) ( it->func_data, fd );
6052 QValueList<IOCB> mIOCBs;
6057 File: gpgme.info, Node: Cancellation, Prev: Using External Event Loops, Up: Run Control
6062 Sometimes you do not want to wait for an operation to finish. GPGME
6063 provides two different functions to achieve that. The function
6064 ‘gpgme_cancel’ takes effect immediately. When it returns, the operation
6065 is effectively canceled. However, it has some limitations and can not
6066 be used with synchronous operations. In contrast, the function
6067 ‘gpgme_cancel_async’ can be used with any context and from any thread,
6068 but it is not guaranteed to take effect immediately. Instead,
6069 cancellation occurs at the next possible time (typically the next time
6070 I/O occurs in the target context).
6072 -- Function: gpgme_ctx_t gpgme_cancel (gpgme_ctx_t CTX)
6073 The function ‘gpgme_cancel’ attempts to cancel a pending operation
6074 in the context CTX. This only works if you use the global event
6075 loop or your own event loop.
6077 If you use the global event loop, you must not call ‘gpgme_wait’
6078 during cancellation. After successful cancellation, you can call
6079 ‘gpgme_wait’ (optionally waiting on CTX), and the context CTX will
6080 appear as if it had finished with the error code ‘GPG_ERR_CANCEL’.
6082 If you use an external event loop, you must ensure that no I/O
6083 callbacks are invoked for this context (for example by halting the
6084 event loop). On successful cancellation, all registered I/O
6085 callbacks for this context will be unregistered, and a
6086 ‘GPGME_EVENT_DONE’ event with the error code ‘GPG_ERR_CANCEL’ will
6089 The function returns an error code if the cancellation failed (in
6090 this case the state of CTX is not modified).
6092 -- Function: gpgme_ctx_t gpgme_cancel_async (gpgme_ctx_t CTX)
6093 The function ‘gpgme_cancel_async’ attempts to cancel a pending
6094 operation in the context CTX. This can be called by any thread at
6095 any time after starting an operation on the context, but will not
6096 take effect immediately. The actual cancellation happens at the
6097 next time GPGME processes I/O in that context.
6099 The function returns an error code if the cancellation failed (in
6100 this case the state of CTX is not modified).
6103 File: gpgme.info, Node: UI Server Protocol, Next: Debugging, Prev: Contexts, Up: Top
6105 Appendix A The GnuPG UI Server Protocol
6106 ***************************************
6108 This section specifies the protocol used between clients and a User
6109 Interface Server (UI server). This protocol helps to build a system
6110 where all cryptographic operations are done by a server and the server
6111 is responsible for all dialogs. Although GPGME has no direct support
6112 for this protocol it is believed that servers will utilize the GPGME
6113 library; thus having the specification included in this manual is an
6114 appropriate choice. This protocol should be referenced as ‘The GnuPG UI
6117 A server needs to implement these commands:(1)
6121 * UI Server Encrypt:: Encrypt a message.
6122 * UI Server Sign:: Sign a message.
6123 * UI Server Decrypt:: Decrypt a message.
6124 * UI Server Verify:: Verify a message.
6125 * UI Server Set Input Files:: Specifying the input files to operate on.
6126 * UI Server Sign/Encrypt Files:: Encrypting and signing files.
6127 * UI Server Verify/Decrypt Files:: Decrypting and verifying files.
6128 * UI Server Import/Export Keys:: Managing certificates.
6129 * UI Server Checksum Files:: Create and verify checksums for files.
6130 * Miscellaneous UI Server Commands:: Commands not related to a specific operation.
6132 ---------- Footnotes ----------
6134 (1) In all examples we assume that the connection has already been
6135 established; see the Assuan manual for details.
6138 File: gpgme.info, Node: UI Server Encrypt, Next: UI Server Sign, Up: UI Server Protocol
6140 A.1 UI Server: Encrypt a Message
6141 ================================
6143 Before encryption can be done the recipients must be set using the
6146 -- Command: RECIPIENT STRING
6148 Set the recipient for the encryption. STRING is an RFC-2822
6149 recipient name ("mailbox" as per section 3.4). This command may or
6150 may not check the recipient for validity right away; if it does not
6151 all recipients are expected to be checked at the time of the
6152 ‘ENCRYPT’ command. All ‘RECIPIENT’ commands are cumulative until a
6153 successful ‘ENCRYPT’ command or until a ‘RESET’ command. Linefeeds
6154 are obviously not allowed in STRING and should be folded into
6155 spaces (which are equivalent).
6157 To tell the server the source and destination of the data, the next two
6158 commands are to be used:
6160 -- Command: INPUT FD=N
6161 Set the file descriptor for the message to be encrypted to N. The
6162 message send to the server is binary encoded.
6164 GpgOL is a Windows only program, thus N is not a libc file
6165 descriptor but a regular system handle. Given that the Assuan
6166 connection works over a socket, it is not possible to use regular
6167 inheritance to make the file descriptor available to the server.
6168 Thus ‘DuplicateHandle’ needs to be used to duplicate a handle to
6169 the server process. This is the reason that the server needs to
6170 implement the ‘GETINFO pid’ command. Sending this command a second
6171 time replaces the file descriptor set by the last one.
6173 -- Command: OUTPUT FD=N [--binary]
6174 Set the file descriptor to be used for the output (i.e. the
6175 encrypted message) to N. If the option ‘--binary’ is given the
6176 output shall be in binary format; if not given, the output for
6177 OpenPGP needs to be ASCII armored and for CMS Base-64 encoded. For
6178 details on the file descriptor, see the ‘INPUT’ command.
6180 The setting of the recipients, the data source and destination may
6181 happen in any order, even intermixed. If this has been done the actual
6182 encryption operation is called using:
6184 -- Command: ENCRYPT --protocol=NAME
6186 This command reads the plaintext from the file descriptor set by
6187 the ‘INPUT’ command, encrypts it and writes the ciphertext to the
6188 file descriptor set by the ‘OUTPUT’ command. The server may (and
6189 should) overlap reading and writing. The recipients used for the
6190 encryption are all the recipients set so far. If any recipient is
6191 not usable the server should take appropriate measures to notify
6192 the user about the problem and may cancel the operation by
6193 returning an error code. The used file descriptors are void after
6194 this command; the recipient list is only cleared if the server
6197 Because GpgOL uses a streaming mode of operation the server is not
6198 allowed to auto select the protocol and must obey to the mandatory
6202 Use the OpenPGP protocol (RFC-2440).
6204 Use the CMS (PKCS#7) protocol (RFC-3852).
6206 To support automagically selection of the protocol depending on the
6207 selected keys, the server MAY implement the command:
6209 -- Command: PREP_ENCRYPT [--protocol=NAME] [--expect-sign]
6211 This commands considers all recipients set so far and decides
6212 whether it is able to take input and start the actual encryption.
6213 This is kind of a dry-run ‘ENCRYPT’ without requiring or using the
6214 input and output file descriptors. The server shall cache the
6215 result of any user selection to avoid asking this again when the
6216 actual ‘ENCRYPT’ command is send. The ‘--protocol’ option is
6217 optional; if it is not given, the server should allow the user to
6218 select the protocol to be used based on the recipients given or by
6221 If ‘--expect-sign’ is given the server should expect that the
6222 message will also be signed and use this hint to present a unified
6223 recipient and signer selection dialog if possible and desired. A
6224 selected signer should then be cached for the expected SIGN command
6225 (which is expected in the same session but possible on another
6228 If this command is given again before a successful ‘ENCRYPT’
6229 command, the second one takes effect.
6231 Before sending the OK response the server shall tell the client the
6232 protocol to be used (either the one given by the argument or the
6233 one selected by the user) by means of a status line:
6235 -- Status line: PROTOCOL NAME
6236 Advise the client to use the protocol NAME for the ‘ENCRYPT’
6237 command. The valid protocol names are listed under the description
6238 of the ‘ENCRYPT’ command. The server shall emit exactly one
6239 PROTOCOL status line.
6241 Here is an example of a complete encryption sequence; client lines are
6242 indicated by a C:, server responses by C::
6246 C: RECIPIENT foo@example.net
6248 C: RECIPIENT bar@example.com
6251 S: S PROTOCOL OpenPGP
6261 File: gpgme.info, Node: UI Server Sign, Next: UI Server Decrypt, Prev: UI Server Encrypt, Up: UI Server Protocol
6263 A.2 UI Server: Sign a Message
6264 =============================
6266 The server needs to implement opaque signing as well as detached
6267 signing. Due to the nature of OpenPGP messages it is always required to
6268 send the entire message to the server; sending just the hash is not
6269 possible. The following two commands are required to set the input and
6270 output file descriptors:
6272 -- Command: INPUT FD=N
6273 Set the file descriptor for the message to be signed to N. The
6274 message send to the server is binary encoded. For details on the
6275 file descriptor, see the description of ‘INPUT’ in the ‘ENCRYPT’
6278 -- Command: OUTPUT FD=N [--binary]
6279 Set the file descriptor to be used for the output. The output is
6280 either the complete signed message or in case of a detached
6281 signature just that detached signature. If the option ‘--binary’
6282 is given the output shall be in binary format; if not given, the
6283 output for OpenPGP needs to be ASCII armored and for CMS Base-64
6284 encoded. For details on the file descriptor, see the ‘INPUT’
6287 To allow the server the selection of a non-default signing key the
6288 client may optionally use the ‘SENDER’ command, see *note command
6291 The signing operation is then initiated by:
6293 -- Command: SIGN --protocol=NAME [--detached]
6294 Sign the data set with the ‘INPUT’ command and write it to the sink
6295 set by OUTPUT. NAME is the signing protocol used for the message.
6296 For a description of the allowed protocols see the ‘ENCRYPT’
6297 command. With option ‘--detached’ given, a detached signature is
6298 created; this is actually the usual way the command is used.
6300 The client expects the server to send at least this status information
6301 before the final OK response:
6303 -- Status line: MICALG STRING
6304 The STRING represents the hash algorithm used to create the
6305 signature. It is used with RFC-1847 style signature messages and
6306 defined by PGP/MIME (RFC-3156) and S/MIME (RFC-3851). The GPGME
6307 library has a supporting function ‘gpgme_hash_algo_name’ to return
6308 the algorithm name as a string. This string needs to be lowercased
6309 and for OpenPGP prefixed with "‘pgp-’".
6312 File: gpgme.info, Node: UI Server Decrypt, Next: UI Server Verify, Prev: UI Server Sign, Up: UI Server Protocol
6314 A.3 UI Server: Decrypt a Message
6315 ================================
6317 Decryption may include the verification of OpenPGP messages. This is
6318 due to the often used combined signing/encryption modus of OpenPGP. The
6319 client may pass an option to the server to inhibit the signature
6320 verification. The following two commands are required to set the input
6321 and output file descriptors:
6323 -- Command: INPUT FD=N
6324 Set the file descriptor for the message to be decrypted to N. The
6325 message send to the server is either binary encoded or — in the
6326 case of OpenPGP — ASCII armored. For details on the file
6327 descriptor, see the description of ‘INPUT’ in the ‘ENCRYPT’
6330 -- Command: OUTPUT FD=N
6331 Set the file descriptor to be used for the output. The output is
6332 binary encoded. For details on the file descriptor, see the
6333 description of ‘INPUT’ in the ‘ENCRYPT’ section.
6335 The decryption is started with the command:
6337 -- Command: DECRYPT --protocol=NAME [--no-verify]
6338 [--export-session-key]
6339 NAME is the encryption protocol used for the message. For a
6340 description of the allowed protocols see the ‘ENCRYPT’ command.
6341 This argument is mandatory. If the option ‘--no-verify’ is given,
6342 the server should not try to verify a signature, in case the input
6343 data is an OpenPGP combined message. If the option
6344 ‘--export-session-key’ is given and the underlying engine knows how
6345 to export the session key, it will appear on a status line
6348 File: gpgme.info, Node: UI Server Verify, Next: UI Server Set Input Files, Prev: UI Server Decrypt, Up: UI Server Protocol
6350 A.4 UI Server: Verify a Message
6351 ===============================
6353 The server needs to support the verification of opaque signatures as
6354 well as detached signatures. The kind of input sources controls what
6355 kind message is to be verified.
6357 -- Command: MESSAGE FD=N
6358 This command is used with detached signatures to set the file
6359 descriptor for the signed data to N. The data is binary encoded
6360 (used verbatim). For details on the file descriptor, see the
6361 description of ‘INPUT’ in the ‘ENCRYPT’ section.
6363 -- Command: INPUT FD=N
6364 Set the file descriptor for the opaque message or the signature
6365 part of a detached signature to N. The message send to the server
6366 is either binary encoded or – in the case of OpenPGP – ASCII
6367 armored. For details on the file descriptor, see the description
6368 of ‘INPUT’ in the ‘ENCRYPT’ section.
6370 -- Command: OUTPUT FD=N
6371 Set the file descriptor to be used for the output. The output is
6372 binary encoded and only used for opaque signatures. For details on
6373 the file descriptor, see the description of ‘INPUT’ in the
6376 The verification is then started using:
6378 -- Command: VERIFY --protocol=NAME [--silent]
6379 NAME is the signing protocol used for the message. For a
6380 description of the allowed protocols see the ‘ENCRYPT’ command.
6381 This argument is mandatory. Depending on the combination of
6382 ‘MESSAGE’ ‘INPUT’ and ‘OUTPUT’ commands, the server needs to select
6383 the appropriate verification mode:
6386 This indicates a detached signature. Output data is not
6389 This indicates an opaque signature. As no output command has
6390 been given, the server is only required to check the
6393 This indicates an opaque signature. The server shall write
6394 the signed data to the file descriptor set by the output
6395 command. This data shall even be written if the signatures
6398 With ‘--silent’ the server shall not display any dialog; this is for
6399 example used by the client to get the content of opaque signed messages.
6400 The client expects the server to send at least this status information
6401 before the final OK response:
6403 -- Status line: SIGSTATUS FLAG DISPLAYSTRING
6404 Returns the status for the signature and a short string explaining
6405 the status. Valid values for FLAG are:
6408 The message has a signature but it could not not be verified
6409 due to a missing key.
6411 The signature is fully valid.
6413 The signature is valid but additional information was shown
6414 regarding the validity of the key.
6416 The signature is not valid.
6418 DISPLAYSTRING is a percent-and-plus-encoded string with a short
6419 human readable description of the status. For example
6421 S SIGSTATUS green Good+signature+from+Keith+Moon+<keith@example.net>
6423 Note that this string needs to fit into an Assuan line and should
6424 be short enough to be displayed as short one-liner on the clients
6425 window. As usual the encoding of this string is UTF-8 and it
6426 should be send in its translated form.
6428 The server shall send one status line for every signature found on
6432 File: gpgme.info, Node: UI Server Set Input Files, Next: UI Server Sign/Encrypt Files, Prev: UI Server Verify, Up: UI Server Protocol
6434 A.5 UI Server: Specifying the input files to operate on.
6435 ========================================================
6437 All file related UI server commands operate on a number of input files
6438 or directories, specified by one or more ‘FILE’ commands:
6440 -- Command: FILE [--clear] NAME
6441 Add the file or directory NAME to the list of pathnames to be
6442 processed by the server. The parameter NAME must be an absolute
6443 path name (including the drive letter) and is percent espaced (in
6444 particular, the characters %, = and white space characters are
6445 always escaped). If the option ‘--clear’ is given, the list of
6446 files is cleared before adding NAME.
6448 Historical note: The original spec did not define ‘--clear’ but the
6449 keyword ‘--continued’ after the file name to indicate that more
6450 files are to be expected. However, this has never been used and
6451 thus removed from the specs.
6454 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
6456 A.6 UI Server: Encrypting and signing files.
6457 ============================================
6459 First, the input files need to be specified by one or more ‘FILE’
6460 commands. Afterwards, the actual operation is requested:
6462 -- Command: ENCRYPT_FILES --nohup
6463 -- Command: SIGN_FILES --nohup
6464 -- Command: ENCRYPT_SIGN_FILES --nohup
6465 Request that the files specified by ‘FILE’ are encrypted and/or
6466 signed. The command selects the default action. The UI server may
6467 allow the user to change this default afterwards interactively, and
6468 even abort the operation or complete it only on some of the
6469 selected files and directories.
6471 What it means to encrypt or sign a file or directory is specific to
6472 the preferences of the user, the functionality the UI server
6473 provides, and the selected protocol. Typically, for each input
6474 file a new file is created under the original filename plus a
6475 protocol specific extension (like ‘.gpg’ or ‘.sig’), which contain
6476 the encrypted/signed file or a detached signature. For
6477 directories, the server may offer multiple options to the user (for
6478 example ignore or process recursively).
6480 The ‘ENCRYPT_SIGN_FILES’ command requests a combined sign and
6481 encrypt operation. It may not be available for all protocols (for
6482 example, it is available for OpenPGP but not for CMS).
6484 The option ‘--nohup’ is mandatory. It is currently unspecified
6485 what should happen if ‘--nohup’ is not present. Because ‘--nohup’
6486 is present, the server always returns ‘OK’ promptly, and completes
6487 the operation asynchronously.
6490 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
6492 A.7 UI Server: Decrypting and verifying files.
6493 ==============================================
6495 First, the input files need to be specified by one or more ‘FILE’
6496 commands. Afterwards, the actual operation is requested:
6498 -- Command: DECRYPT_FILES --nohup
6499 -- Command: VERIFY_FILES --nohup
6500 -- Command: DECRYPT_VERIFY_FILES --nohup
6501 Request that the files specified by ‘FILE’ are decrypted and/or
6502 verified. The command selects the default action. The UI server
6503 may allow the user to change this default afterwards interactively,
6504 and even abort the operation or complete it only on some of the
6505 selected files and directories.
6507 What it means to decrypt or verify a file or directory is specific
6508 to the preferences of the user, the functionality the UI server
6509 provides, and the selected protocol. Typically, for decryption, a
6510 new file is created for each input file under the original filename
6511 minus a protocol specific extension (like ‘.gpg’) which contains
6512 the original plaintext. For verification a status is displayed for
6513 each signed input file, indicating if it is signed, and if yes, if
6514 the signature is valid. For files that are signed and encrypted,
6515 the ‘VERIFY’ command transiently decrypts the file to verify the
6516 enclosed signature. For directories, the server may offer multiple
6517 options to the user (for example ignore or process recursively).
6519 The option ‘--nohup’ is mandatory. It is currently unspecified
6520 what should happen if ‘--nohup’ is not present. Because ‘--nohup’
6521 is present, the server always returns ‘OK’ promptly, and completes
6522 the operation asynchronously.
6525 File: gpgme.info, Node: UI Server Import/Export Keys, Next: UI Server Checksum Files, Prev: UI Server Verify/Decrypt Files, Up: UI Server Protocol
6527 A.8 UI Server: Managing certificates.
6528 =====================================
6530 First, the input files need to be specified by one or more ‘FILE’
6531 commands. Afterwards, the actual operation is requested:
6533 -- Command: IMPORT_FILES --nohup
6534 Request that the certificates contained in the files specified by
6535 ‘FILE’ are imported into the local certificate databases.
6537 For directories, the server may offer multiple options to the user
6538 (for example ignore or process recursively).
6540 The option ‘--nohup’ is mandatory. It is currently unspecified
6541 what should happen if ‘--nohup’ is not present. Because ‘--nohup’
6542 is present, the server always returns ‘OK’ promptly, and completes
6543 the operation asynchronously.
6545 FIXME: It may be nice to support an ‘EXPORT’ command as well, which
6546 is enabled by the context menu of the background of a directory.
6549 File: gpgme.info, Node: UI Server Checksum Files, Next: Miscellaneous UI Server Commands, Prev: UI Server Import/Export Keys, Up: UI Server Protocol
6551 A.9 UI Server: Create and verify checksums for files.
6552 =====================================================
6554 First, the input files need to be specified by one or more ‘FILE’
6555 commands. Afterwards, the actual operation is requested:
6557 -- Command: CHECKSUM_CREATE_FILES --nohup
6558 Request that checksums are created for the files specifed by
6559 ‘FILE’. The choice of checksum algorithm and the destination
6560 storage and format for the created checksums depend on the
6561 preferences of the user and the functionality provided by the UI
6562 server. For directories, the server may offer multiple options to
6563 the user (for example ignore or process recursively).
6565 The option ‘--nohup’ is mandatory. It is currently unspecified
6566 what should happen if ‘--nohup’ is not present. Because ‘--nohup’
6567 is present, the server always returns ‘OK’ promptly, and completes
6568 the operation asynchronously.
6570 -- Command: CHECKSUM_VERIFY_FILES --nohup
6571 Request that checksums are created for the files specifed by ‘FILE’
6572 and verified against previously created and stored checksums. The
6573 choice of checksum algorithm and the source storage and format for
6574 previously created checksums depend on the preferences of the user
6575 and the functionality provided by the UI server. For directories,
6576 the server may offer multiple options to the user (for example
6577 ignore or process recursively).
6579 If the source storage of previously created checksums is available
6580 to the user through the Windows shell, this command may also accept
6581 such checksum files as ‘FILE’ arguments. In this case, the UI
6582 server should instead verify the checksum of the referenced files
6583 as if they were given as INPUT files.
6585 The option ‘--nohup’ is mandatory. It is currently unspecified
6586 what should happen if ‘--nohup’ is not present. Because ‘--nohup’
6587 is present, the server always returns ‘OK’ promptly, and completes
6588 the operation asynchronously.
6591 File: gpgme.info, Node: Miscellaneous UI Server Commands, Prev: UI Server Checksum Files, Up: UI Server Protocol
6593 A.10 Miscellaneous UI Server Commands
6594 =====================================
6596 The server needs to implement the following commands which are not
6597 related to a specific command:
6599 -- Command: GETINFO WHAT
6600 This is a multi purpose command, commonly used to return a variety
6601 of information. The required subcommands as described by the WHAT
6605 Return the process id of the server in decimal notation using
6606 an Assuan data line.
6608 To allow the server to pop up the windows in the correct relation to the
6609 client, the client is advised to tell the server by sending the option:
6611 -- Command option: window-id NUMBER
6612 The NUMBER represents the native window ID of the clients current
6613 window. On Windows systems this is a windows handle (‘HWND’) and
6614 on X11 systems it is the ‘X Window ID’. The number needs to be
6615 given as a hexadecimal value so that it is easier to convey pointer
6616 values (e.g. ‘HWND’).
6618 A client may want to fire up the certificate manager of the server. To
6619 do this it uses the Assuan command:
6621 -- Command: START_KEYMANAGER
6622 The server shall pop up the main window of the key manager (aka
6623 certificate manager). The client expects that the key manager is
6624 brought into the foregound and that this command immediatley
6625 returns (does not wait until the key manager has been fully brought
6628 A client may want to fire up the configuration dialog of the server. To
6629 do this it uses the Assuan command:
6631 -- Command: START_CONFDIALOG
6632 The server shall pop up its configuration dialog. The client
6633 expects that this dialog is brought into the foregound and that
6634 this command immediatley returns (i.e. it does not wait until the
6635 dialog has been fully brought up).
6637 When doing an operation on a mail, it is useful to let the server know
6638 the address of the sender:
6640 -- Command: SENDER [--info] [--protocol=NAME] EMAIL
6641 EMAIL is the plain ASCII encoded address ("addr-spec" as per
6642 RFC-2822) enclosed in angle brackets. The address set with this
6643 command is valid until a successful completion of the operation or
6644 until a ‘RESET’ command. A second command overrides the effect of
6645 the first one; if EMAIL is not given and ‘--info’ is not used, the
6646 server shall use the default signing key.
6648 If option ‘--info’ is not given, the server shall also suggest a
6649 protocol to use for signing. The client may use this suggested
6650 protocol on its own discretion. The same status line as with
6651 PREP_ENCRYPT is used for this.
6653 The option ‘--protocol’ may be used to give the server a hint on
6654 which signing protocol should be preferred.
6656 To allow the UI-server to visually identify a running operation or to
6657 associate operations the server MAY support the command:
6659 -- Command: SESSION NUMBER [STRING]
6660 The NUMBER is an arbitrary value, a server may use to associate
6661 simultaneous running sessions. It is a 32 bit unsigned integer
6662 with ‘0’ as a special value indicating that no session association
6665 If STRING is given, the server may use this as the title of a
6666 window or, in the case of an email operation, to extract the
6667 sender’s address. The string may contain spaces; thus no
6668 plus-escaping is used.
6670 This command may be used at any time and overrides the effect of
6671 the last command. A ‘RESET’ undoes the effect of this command.
6674 File: gpgme.info, Node: Debugging, Next: Deprecated Functions, Prev: UI Server Protocol, Up: Top
6676 Appendix B How to solve problems
6677 ********************************
6679 Everyone knows that software often does not do what it should do and
6680 thus there is a need to track down problems. This is in particular true
6681 for applications using a complex library like GPGME and of course also
6682 for the library itself. Here we give a few hints on how to solve such
6685 First of all you should make sure that the keys you want to use are
6686 installed in the GnuPG engine and are usable. Thus the first test is to
6687 run the desired operation using ‘gpg’ or ‘gpgsm’ on the command line.
6688 If you can’t figure out why things don’t work, you may use GPGME’s built
6689 in trace feature. This feature is either enabled using the environment
6690 variable ‘GPGME_DEBUG’ or, if this is not possible, by calling the
6691 function ‘gpgme_set_global_flag’. The value is the trace level and an
6692 optional file name. If no file name is given the trace output is
6693 printed to ‘stderr’.
6696 GPGME_DEBUG=9:/home/user/mygpgme.log
6697 (Note that under Windows you use a semicolon in place of the colon to
6698 separate the fields.)
6700 A trace level of 9 is pretty verbose and thus you may want to start
6701 off with a lower level. The exact definition of the trace levels and
6702 the output format may change with any release; you need to check the
6703 source code for details. In any case the trace log should be helpful to
6704 understand what is going going on. Warning: The trace log may reveal
6705 sensitive details like passphrases or other data you use in your
6706 application. If you are asked to send a log file, make sure that you
6707 run your tests only with play data.
6710 File: gpgme.info, Node: Deprecated Functions, Next: Library Copying, Prev: Debugging, Up: Top
6712 Appendix C Deprecated Functions
6713 *******************************
6715 For backward compatibility GPGME has a number of functions, data types
6716 and constants which are deprecated and should not be used anymore. We
6717 document here those which are really old to help understanding old code
6718 and to allow migration to their modern counterparts.
6720 *Warning:* These interfaces will be removed in a future version of
6723 -- Function: void gpgme_key_release (gpgme_key_t KEY)
6724 The function ‘gpgme_key_release’ is equivalent to
6727 -- Function: void gpgme_trust_item_release (gpgme_trust_item_t ITEM)
6728 The function ‘gpgme_trust_item_release’ is an alias for
6729 ‘gpgme_trust_item_unref’.
6731 -- Function: gpgme_error_t gpgme_op_import_ext (gpgme_ctx_t CTX,
6732 gpgme_data_t KEYDATA, int *NR)
6733 The function ‘gpgme_op_import_ext’ is equivalent to:
6735 gpgme_error_t err = gpgme_op_import (ctx, keydata);
6738 gpgme_import_result_t result = gpgme_op_import_result (ctx);
6739 *nr = result->considered;
6742 -- Data type: gpgme_error_t (*gpgme_edit_cb_t) (void *HANDLE,
6743 gpgme_status_code_t STATUS, const char *ARGS, int FD)
6744 The ‘gpgme_edit_cb_t’ type is the type of functions which GPGME
6745 calls if it a key edit operation is on-going. The status code
6746 STATUS and the argument line ARGS are passed through by GPGME from
6747 the crypto engine. The file descriptor FD is -1 for normal status
6748 messages. If STATUS indicates a command rather than a status
6749 message, the response to the command should be written to FD. The
6750 HANDLE is provided by the user at start of operation.
6752 The function should return ‘GPG_ERR_FALSE’ if it did not handle the
6753 status code, ‘0’ for success, or any other error value.
6755 -- Function: gpgme_error_t gpgme_op_edit (gpgme_ctx_t CTX,
6756 gpgme_key_t KEY, gpgme_edit_cb_t FNC, void *HANDLE,
6758 Note: This function is deprecated, please use ‘gpgme_op_interact’
6761 The function ‘gpgme_op_edit’ processes the key KEY interactively,
6762 using the edit callback function FNC with the handle HANDLE. The
6763 callback is invoked for every status and command request from the
6764 crypto engine. The output of the crypto engine is written to the
6767 Note that the protocol between the callback function and the crypto
6768 engine is specific to the crypto engine and no further support in
6769 implementing this protocol correctly is provided by GPGME.
6771 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the edit
6772 operation completes successfully, ‘GPG_ERR_INV_VALUE’ if CTX or KEY
6773 is not a valid pointer, and any error returned by the crypto engine
6774 or the edit callback handler.
6776 -- Function: gpgme_error_t gpgme_op_edit_start (gpgme_ctx_t CTX,
6777 gpgme_key_t KEY, gpgme_edit_cb_t FNC, void *HANDLE,
6779 Note: This function is deprecated, please use
6780 ‘gpgme_op_interact_start’ instead.
6782 The function ‘gpgme_op_edit_start’ initiates a ‘gpgme_op_edit’
6783 operation. It can be completed by calling ‘gpgme_wait’ on the
6784 context. *Note Waiting For Completion::.
6786 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
6787 operation was started successfully, and ‘GPG_ERR_INV_VALUE’ if CTX
6788 or KEY is not a valid pointer.
6790 -- Function: gpgme_error_t gpgme_op_card_edit (gpgme_ctx_t CTX,
6791 gpgme_key_t KEY, gpgme_edit_cb_t FNC, void *HANDLE,
6793 Note: This function is deprecated, please use ‘gpgme_op_interact’
6794 with the flag ‘GPGME_INTERACT_CARD’ instead.
6796 The function ‘gpgme_op_card_edit’ is analogous to ‘gpgme_op_edit’,
6797 but should be used to process the smart card corresponding to the
6800 -- Function: gpgme_error_t gpgme_op_card_edit_start (gpgme_ctx_t CTX,
6801 gpgme_key_t KEY, gpgme_edit_cb_t FNC, void *HANDLE,
6803 Note: This function is deprecated, please use
6804 ‘gpgme_op_interact_start’ with the flag ‘GPGME_INTERACT_CARD’
6807 The function ‘gpgme_op_card_edit_start’ initiates a
6808 ‘gpgme_op_card_edit’ operation. It can be completed by calling
6809 ‘gpgme_wait’ on the context. *Note Waiting For Completion::.
6811 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
6812 operation was started successfully, and ‘GPG_ERR_INV_VALUE’ if CTX
6813 or KEY is not a valid pointer.
6815 -- Function: gpgme_error_t gpgme_data_new_with_read_cb
6816 (gpgme_data_t *DH, int (*READFUNC) (void *HOOK, char *BUFFER,
6817 size_t COUNT, size_t *NREAD), void *HOOK_VALUE)
6818 The function ‘gpgme_data_new_with_read_cb’ creates a new
6819 ‘gpgme_data_t’ object and uses the callback function READFUNC to
6820 retrieve the data on demand. As the callback function can supply
6821 the data in any way it wants, this is the most flexible data type
6822 GPGME provides. However, it can not be used to write data.
6824 The callback function receives HOOK_VALUE as its first argument
6825 whenever it is invoked. It should return up to COUNT bytes in
6826 BUFFER, and return the number of bytes actually read in NREAD. It
6827 may return ‘0’ in NREAD if no data is currently available. To
6828 indicate ‘EOF’ the function should return with an error code of
6829 ‘-1’ and set NREAD to ‘0’. The callback function may support to
6830 reset its internal read pointer if it is invoked with BUFFER and
6831 NREAD being ‘NULL’ and COUNT being ‘0’.
6833 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data
6834 object was successfully created, ‘GPG_ERR_INV_VALUE’ if DH or
6835 READFUNC is not a valid pointer, and ‘GPG_ERR_ENOMEM’ if not enough
6836 memory is available.
6838 -- Function: gpgme_error_t gpgme_data_rewind (gpgme_data_t DH)
6839 The function ‘gpgme_data_rewind’ is equivalent to:
6841 return (gpgme_data_seek (dh, 0, SEEK_SET) == -1)
6842 ? gpgme_error_from_errno (errno) : 0;
6844 -- Data type: gpgme_attr_t
6845 The ‘gpgme_attr_t’ type is used to specify a key or trust item
6846 attribute. The following attributes are defined:
6849 This is the key ID of a sub key. It is representable as a
6852 For trust items, the trust item refers to the key with this
6856 This is the fingerprint of a sub key. It is representable as
6860 This is the crypto algorithm for which the sub key can be
6861 used. It is representable as a string and as a number. The
6862 numbers correspond to the ‘enum gcry_pk_algos’ values in the
6866 This is the key length of a sub key. It is representable as a
6869 ‘GPGME_ATTR_CREATED’
6870 This is the timestamp at creation time of a sub key. It is
6871 representable as a number.
6874 This is the expiration time of a sub key. It is representable
6878 XXX FIXME (also for trust items)
6881 This is a user ID. There can be more than one user IDs in a
6882 GPGME_KEY_T object. The first one (with index 0) is the
6883 primary user ID. The user ID is representable as a number.
6885 For trust items, this is the user ID associated with this
6889 This is the name belonging to a user ID. It is representable
6893 This is the email address belonging to a user ID. It is
6894 representable as a string.
6896 ‘GPGME_ATTR_COMMENT’
6897 This is the comment belonging to a user ID. It is
6898 representable as a string.
6900 ‘GPGME_ATTR_VALIDITY’
6901 This is the validity belonging to a user ID. It is
6902 representable as a string and as a number. See below for a
6903 list of available validities.
6905 For trust items, this is the validity that is associated with
6908 ‘GPGME_ATTR_UID_REVOKED’
6909 This specifies if a user ID is revoked. It is representable
6910 as a number, and is ‘1’ if the user ID is revoked, and ‘0’
6913 ‘GPGME_ATTR_UID_INVALID’
6914 This specifies if a user ID is invalid. It is representable
6915 as a number, and is ‘1’ if the user ID is invalid, and ‘0’
6919 This is the trust level of a trust item.
6922 This returns information about the type of key. For the
6923 string function this will eother be "PGP" or "X.509". The
6924 integer function returns 0 for PGP and 1 for X.509. It is
6925 also used for the type of a trust item.
6927 ‘GPGME_ATTR_IS_SECRET’
6928 This specifies if the key is a secret key. It is
6929 representable as a number, and is ‘1’ if the key is revoked,
6932 ‘GPGME_ATTR_KEY_REVOKED’
6933 This specifies if a sub key is revoked. It is representable
6934 as a number, and is ‘1’ if the key is revoked, and ‘0’
6937 ‘GPGME_ATTR_KEY_INVALID’
6938 This specifies if a sub key is invalid. It is representable
6939 as a number, and is ‘1’ if the key is invalid, and ‘0’
6942 ‘GPGME_ATTR_KEY_EXPIRED’
6943 This specifies if a sub key is expired. It is representable
6944 as a number, and is ‘1’ if the key is expired, and ‘0’
6947 ‘GPGME_ATTR_KEY_DISABLED’
6948 This specifies if a sub key is disabled. It is representable
6949 as a number, and is ‘1’ if the key is disabled, and ‘0’
6952 ‘GPGME_ATTR_KEY_CAPS’
6953 This is a description of the capabilities of a sub key. It is
6954 representable as a string. The string contains the letter “e”
6955 if the key can be used for encryption, “s” if the key can be
6956 used for signatures, and “c” if the key can be used for
6959 ‘GPGME_ATTR_CAN_ENCRYPT’
6960 This specifies if a sub key can be used for encryption. It is
6961 representable as a number, and is ‘1’ if the sub key can be
6962 used for encryption, and ‘0’ otherwise.
6964 ‘GPGME_ATTR_CAN_SIGN’
6965 This specifies if a sub key can be used to create data
6966 signatures. It is representable as a number, and is ‘1’ if
6967 the sub key can be used for signatures, and ‘0’ otherwise.
6969 ‘GPGME_ATTR_CAN_CERTIFY’
6970 This specifies if a sub key can be used to create key
6971 certificates. It is representable as a number, and is ‘1’ if
6972 the sub key can be used for certifications, and ‘0’ otherwise.
6975 The X.509 issuer serial attribute of the key. It is
6976 representable as a string.
6979 The X.509 issuer name attribute of the key. It is
6980 representable as a string.
6982 ‘GPGME_ATTR_CHAINID’
6983 The X.509 chain ID can be used to build the certification
6984 chain. It is representable as a string.
6986 -- Function: const char * gpgme_key_get_string_attr (gpgme_key_t KEY,
6987 gpgme_attr_t WHAT, const void *RESERVED, int IDX)
6988 The function ‘gpgme_key_get_string_attr’ returns the value of the
6989 string-representable attribute WHAT of key KEY. If the attribute
6990 is an attribute of a sub key or an user ID, IDX specifies the sub
6991 key or user ID of which the attribute value is returned. The
6992 argument RESERVED is reserved for later use and should be ‘NULL’.
6994 The string returned is only valid as long as the key is valid.
6996 The function returns ‘0’ if an attribute can’t be returned as a
6997 string, KEY is not a valid pointer, IDX out of range, or RESERVED
7000 -- Function: unsigned long gpgme_key_get_ulong_attr (gpgme_key_t KEY,
7001 gpgme_attr_t WHAT, const void *RESERVED, int IDX)
7002 The function ‘gpgme_key_get_ulong_attr’ returns the value of the
7003 number-representable attribute WHAT of key KEY. If the attribute
7004 is an attribute of a sub key or an user ID, IDX specifies the sub
7005 key or user ID of which the attribute value is returned. The
7006 argument RESERVED is reserved for later use and should be ‘NULL’.
7008 The function returns ‘0’ if the attribute can’t be returned as a
7009 number, KEY is not a valid pointer, IDX out of range, or RESERVED
7012 The signatures on a key are only available if the key was retrieved
7013 via a listing operation with the ‘GPGME_KEYLIST_MODE_SIGS’ mode enabled,
7014 because it is expensive to retrieve all signatures of a key.
7016 So, before using the below interfaces to retrieve the signatures on a
7017 key, you have to make sure that the key was listed with signatures
7018 enabled. One convenient, but blocking, way to do this is to use the
7019 function ‘gpgme_get_key’.
7021 -- Data type: gpgme_attr_t
7022 The ‘gpgme_attr_t’ type is used to specify a key signature
7023 attribute. The following attributes are defined:
7026 This is the key ID of the key which was used for the
7027 signature. It is representable as a string.
7030 This is the crypto algorithm used to create the signature. It
7031 is representable as a string and as a number. The numbers
7032 correspond to the ‘enum gcry_pk_algos’ values in the gcrypt
7035 ‘GPGME_ATTR_CREATED’
7036 This is the timestamp at creation time of the signature. It
7037 is representable as a number.
7040 This is the expiration time of the signature. It is
7041 representable as a number.
7044 This is the user ID associated with the signing key. The user
7045 ID is representable as a number.
7048 This is the name belonging to a user ID. It is representable
7052 This is the email address belonging to a user ID. It is
7053 representable as a string.
7055 ‘GPGME_ATTR_COMMENT’
7056 This is the comment belonging to a user ID. It is
7057 representable as a string.
7059 ‘GPGME_ATTR_KEY_REVOKED’
7060 This specifies if a key signature is a revocation signature.
7061 It is representable as a number, and is ‘1’ if the key is
7062 revoked, and ‘0’ otherwise.
7064 ‘GPGME_ATTR_SIG_CLASS’
7065 This specifies the signature class of a key signature. It is
7066 representable as a number. The meaning is specific to the
7069 ‘GPGME_ATTR_SIG_CLASS’
7070 This specifies the signature class of a key signature. It is
7071 representable as a number. The meaning is specific to the
7074 ‘GPGME_ATTR_SIG_STATUS’
7075 This is the same value as returned by ‘gpgme_get_sig_status’.
7077 -- Function: const char * gpgme_key_sig_get_string_attr
7078 (gpgme_key_t KEY, int UID_IDX, gpgme_attr_t WHAT,
7079 const void *RESERVED, int IDX)
7080 The function ‘gpgme_key_sig_get_string_attr’ returns the value of
7081 the string-representable attribute WHAT of the signature IDX on the
7082 user ID UID_IDX in the key KEY. The argument RESERVED is reserved
7083 for later use and should be ‘NULL’.
7085 The string returned is only valid as long as the key is valid.
7087 The function returns ‘0’ if an attribute can’t be returned as a
7088 string, KEY is not a valid pointer, UID_IDX or IDX out of range, or
7089 RESERVED not ‘NULL’.
7091 -- Function: unsigned long gpgme_key_sig_get_ulong_attr
7092 (gpgme_key_t KEY, int UID_IDX, gpgme_attr_t WHAT,
7093 const void *RESERVED, int IDX)
7094 The function ‘gpgme_key_sig_get_ulong_attr’ returns the value of
7095 the number-representable attribute WHAT of the signature IDX on the
7096 user ID UID_IDX in the key KEY. The argument RESERVED is reserved
7097 for later use and should be ‘NULL’.
7099 The function returns ‘0’ if an attribute can’t be returned as a
7100 string, KEY is not a valid pointer, UID_IDX or IDX out of range, or
7101 RESERVED not ‘NULL’.
7103 Trust items have attributes which can be queried using the interfaces
7104 below. The attribute identifiers are shared with those for key
7105 attributes. *Note Information About Keys::.
7107 -- Function: const char * gpgme_trust_item_get_string_attr
7108 (gpgme_trust_item_t ITEM, gpgme_attr_t WHAT,
7109 const void *RESERVED, int IDX)
7110 The function ‘gpgme_trust_item_get_string_attr’ returns the value
7111 of the string-representable attribute WHAT of trust item ITEM. The
7112 arguments IDX and RESERVED are reserved for later use and should be
7113 ‘0’ and ‘NULL’ respectively.
7115 The string returned is only valid as long as the key is valid.
7117 The function returns ‘0’ if an attribute can’t be returned as a
7118 string, KEY is not a valid pointer, IDX out of range, or RESERVED
7121 -- Function: int gpgme_trust_item_get_int_attr
7122 (gpgme_trust_item_t ITEM, gpgme_attr_t WHAT,
7123 const void *RESERVED, int IDX)
7124 The function ‘gpgme_trust_item_get_int_attr’ returns the value of
7125 the number-representable attribute WHAT of trust item ITEM. If the
7126 attribute occurs more than once in the trust item, the index is
7127 specified by IDX. However, currently no such attribute exists, so
7128 IDX should be ‘0’. The argument RESERVED is reserved for later use
7129 and should be ‘NULL’.
7131 The function returns ‘0’ if the attribute can’t be returned as a
7132 number, KEY is not a valid pointer, IDX out of range, or RESERVED
7135 -- Data type: enum gpgme_sig_stat_t
7136 The ‘gpgme_sig_stat_t’ type holds the result of a signature check,
7137 or the combined result of all signatures. The following results
7140 ‘GPGME_SIG_STAT_NONE’
7141 This status should not occur in normal operation.
7143 ‘GPGME_SIG_STAT_GOOD’
7144 This status indicates that the signature is valid. For the
7145 combined result this status means that all signatures are
7148 ‘GPGME_SIG_STAT_GOOD_EXP’
7149 This status indicates that the signature is valid but expired.
7150 For the combined result this status means that all signatures
7151 are valid and expired.
7153 ‘GPGME_SIG_STAT_GOOD_EXPKEY’
7154 This status indicates that the signature is valid but the key
7155 used to verify the signature has expired. For the combined
7156 result this status means that all signatures are valid and all
7159 ‘GPGME_SIG_STAT_BAD’
7160 This status indicates that the signature is invalid. For the
7161 combined result this status means that all signatures are
7164 ‘GPGME_SIG_STAT_NOKEY’
7165 This status indicates that the signature could not be verified
7166 due to a missing key. For the combined result this status
7167 means that all signatures could not be checked due to missing
7170 ‘GPGME_SIG_STAT_NOSIG’
7171 This status indicates that the signature data provided was not
7174 ‘GPGME_SIG_STAT_ERROR’
7175 This status indicates that there was some other error which
7176 prevented the signature verification.
7178 ‘GPGME_SIG_STAT_DIFF’
7179 For the combined result this status means that at least two
7180 signatures have a different status. You can get each key’s
7181 status with ‘gpgme_get_sig_status’.
7183 -- Function: const char * gpgme_get_sig_status (gpgme_ctx_t CTX,
7184 int IDX, gpgme_sig_stat_t *R_STAT, time_t *R_CREATED)
7185 The function ‘gpgme_get_sig_status’ is equivalent to:
7187 gpgme_verify_result_t result;
7188 gpgme_signature_t sig;
7190 result = gpgme_op_verify_result (ctx);
7191 sig = result->signatures;
7203 switch (gpg_err_code (sig->status))
7205 case GPG_ERR_NO_ERROR:
7206 *r_stat = GPGME_SIG_STAT_GOOD;
7209 case GPG_ERR_BAD_SIGNATURE:
7210 *r_stat = GPGME_SIG_STAT_BAD;
7213 case GPG_ERR_NO_PUBKEY:
7214 *r_stat = GPGME_SIG_STAT_NOKEY;
7217 case GPG_ERR_NO_DATA:
7218 *r_stat = GPGME_SIG_STAT_NOSIG;
7221 case GPG_ERR_SIG_EXPIRED:
7222 *r_stat = GPGME_SIG_STAT_GOOD_EXP;
7225 case GPG_ERR_KEY_EXPIRED:
7226 *r_stat = GPGME_SIG_STAT_GOOD_EXPKEY;
7230 *r_stat = GPGME_SIG_STAT_ERROR;
7235 *r_created = sig->timestamp;
7238 -- Function: const char * gpgme_get_sig_string_attr (gpgme_ctx_t CTX,
7239 int IDX, gpgme_attr_t WHAT, int WHATIDX)
7240 The function ‘gpgme_get_sig_string_attr’ is equivalent to:
7242 gpgme_verify_result_t result;
7243 gpgme_signature_t sig;
7245 result = gpgme_op_verify_result (ctx);
7246 sig = result->signatures;
7258 case GPGME_ATTR_FPR:
7261 case GPGME_ATTR_ERRTOK:
7263 return sig->wrong_key_usage ? "Wrong_Key_Usage" : "";
7272 -- Function: const char * gpgme_get_sig_ulong_attr (gpgme_ctx_t CTX,
7273 int IDX, gpgme_attr_t WAHT, int WHATIDX)
7274 The function ‘gpgme_get_sig_ulong_attr’ is equivalent to:
7276 gpgme_verify_result_t result;
7277 gpgme_signature_t sig;
7279 result = gpgme_op_verify_result (ctx);
7280 sig = result->signatures;
7292 case GPGME_ATTR_CREATED:
7293 return sig->timestamp;
7295 case GPGME_ATTR_EXPIRE:
7296 return sig->exp_timestamp;
7298 case GPGME_ATTR_VALIDITY:
7299 return (unsigned long) sig->validity;
7301 case GPGME_ATTR_SIG_STATUS:
7302 switch (sig->status)
7304 case GPG_ERR_NO_ERROR:
7305 return GPGME_SIG_STAT_GOOD;
7307 case GPG_ERR_BAD_SIGNATURE:
7308 return GPGME_SIG_STAT_BAD;
7310 case GPG_ERR_NO_PUBKEY:
7311 return GPGME_SIG_STAT_NOKEY;
7313 case GPG_ERR_NO_DATA:
7314 return GPGME_SIG_STAT_NOSIG;
7316 case GPG_ERR_SIG_EXPIRED:
7317 return GPGME_SIG_STAT_GOOD_EXP;
7319 case GPG_ERR_KEY_EXPIRED:
7320 return GPGME_SIG_STAT_GOOD_EXPKEY;
7323 return GPGME_SIG_STAT_ERROR;
7326 case GPGME_ATTR_SIG_SUMMARY:
7327 return sig->summary;
7334 -- Function: const char * gpgme_get_sig_key (gpgme_ctx_t CTX, int IDX,
7336 The function ‘gpgme_get_sig_key’ is equivalent to:
7338 gpgme_verify_result_t result;
7339 gpgme_signature_t sig;
7341 result = gpgme_op_verify_result (ctx);
7342 sig = result->signatures;
7350 return gpg_error (GPG_ERR_EOF);
7352 return gpgme_get_key (ctx, sig->fpr, r_key, 0);