1 \input texinfo @c -*- Texinfo -*-
2 @setfilename gpgme.info
3 @settitle The `GnuPG Made Easy' Reference Manual
5 @dircategory GNU Libraries
7 * @acronym{GPGME}: (gpgme). Adding support for cryptography to your program.
12 @c Unify some of the indices.
17 This file documents the @acronym{GPGME} library.
19 This is Edition @value{EDITION}, last updated @value{UPDATED}, of
20 @cite{The `GnuPG Made Easy' Reference Manual}, for Version
23 Copyright @copyright{} 2002, 2003 g10 Code GmbH.
25 Permission is granted to copy, distribute and/or modify this document
26 under the terms of the GNU Free Documentation License, Version 1.1 or
27 any later version published by the Free Software Foundation; with the
28 Invariant Sections being ``Free Software Needs Free Documentation'' and
29 ``GNU Lesser General Public License'', the Front-Cover texts being (a)
30 (see below), and with the Back-Cover Texts being (b) (see below). A
31 copy of the license is included in the section entitled ``GNU Free
32 Documentation License''.
37 @shorttitlepage The `GnuPG Made Easy' Reference Manual
40 @center @titlefont{The `GnuPG Made Easy'}
42 @center @titlefont{Reference Manual}
44 @center Edition @value{EDITION}
46 @center last updated @value{UPDATED}
48 @center for version @value{VERSION}
50 @vskip 0pt plus 1filll
51 Copyright @copyright{} 2002, 2003 g10 Code GmbH.
53 Permission is granted to copy, distribute and/or modify this document
54 under the terms of the GNU Free Documentation License, Version 1.1 or
55 any later version published by the Free Software Foundation; with the
56 Invariant Sections being ``Free Software Needs Free Documentation'' and
57 ``GNU Lesser General Public License'', the Front-Cover texts being (a)
58 (see below), and with the Back-Cover Texts being (b) (see below). A
59 copy of the license is included in the section entitled ``GNU Free
60 Documentation License''.
67 This is Edition @value{EDITION}, last updated @value{UPDATED}, of
68 @cite{The `GnuPG Made Easy' Reference Manual}, for Version
69 @value{VERSION} of the @acronym{GPGME} library.
73 * Introduction:: How to use this manual.
74 * Preparation:: What you should do before using the library.
75 * Protocols and Engines:: Supported crypto protocols.
76 * Algorithms:: Supported algorithms.
77 * Error Handling:: Error numbers and their meanings.
78 * Exchanging Data:: Passing data to and from @acronym{GPGME}.
79 * Contexts:: Handling @acronym{GPGME} contexts.
83 * Copying:: The GNU General Public License says how you
84 can copy and share `GnuPG Made Easy'.
85 * Free Documentation License:: This manual is under the GNU Free
86 Documentation License.
90 * Concept Index:: Index of concepts and programs.
91 * Function and Data Index:: Index of functions, variables and data types.
95 --- The Detailed Node Listing ---
99 * Getting Started:: Purpose of the manual, and how to use it.
100 * Features:: Reasons to install and use @acronym{GPGME}.
101 * Overview:: Basic architecture of the @acronym{GPGME} library.
105 * Header:: What header file you need to include.
106 * Building the Source:: Compiler options to be used.
107 * Using Automake:: Compiler options to be used the easy way.
108 * Library Version Check:: Getting and verifying the library version.
109 * Multi Threading:: How @acronym{GPGME} can be used in an MT environment.
111 Protocols and Engines
113 * Engine Version Check:: Verifying the engine version.
114 * Engine Information:: Obtaining more information about the engines.
115 * OpenPGP:: Support for the OpenPGP protocol.
116 * Cryptographic Message Syntax:: Support for the CMS.
120 * Public Key Algorithms:: A list of all public key algorithms.
121 * Hash Algorithms:: A list of all hash algorithms.
125 * Error Values:: The error value and what it means.
126 * Error Codes:: A list of important error codes.
127 * Error Sources:: A list of important error sources.
128 * Error Strings:: How to get a descriptive string from a value.
132 * Creating Data Buffers:: Creating new data buffers.
133 * Destroying Data Buffers:: Releasing data buffers.
134 * Manipulating Data Buffers:: Operations on data buffers.
136 Creating Data Buffers
138 * Memory Based Data Buffers:: Creating memory based data buffers.
139 * File Based Data Buffers:: Creating file based data buffers.
140 * Callback Based Data Buffers:: Creating callback based data buffers.
144 * Creating Contexts:: Creating new @acronym{GPGME} contexts.
145 * Destroying Contexts:: Releasing @acronym{GPGME} contexts.
146 * Context Attributes:: Setting properties of a context.
147 * Key Management:: Managing keys with @acronym{GPGME}.
148 * Trust Item Management:: Managing trust items with @acronym{GPGME}.
149 * Crypto Operations:: Using a context for cryptography.
150 * Run Control:: Controlling how operations are run.
154 * Protocol Selection:: Selecting the protocol used by a context.
155 * ASCII Armor:: Requesting @acronym{ASCII} armored output.
156 * Text Mode:: Choosing canonical text mode.
157 * Included Certificates:: Including a number of certificates.
158 * Key Listing Mode:: Selecting key listing mode.
159 * Passphrase Callback:: Getting the passphrase from the user.
160 * Progress Meter Callback:: Being informed about the progress.
164 * Listing Keys:: Browsing the list of available keys.
165 * Information About Keys:: Requesting detailed information about keys.
166 * Key Signatures:: Listing the signatures on a key.
167 * Manipulating Keys:: Operations on keys.
168 * Generating Keys:: Creating new key pairs.
169 * Exporting Keys:: Retrieving key data from the key ring.
170 * Importing Keys:: Adding keys to the key ring.
171 * Deleting Keys:: Removing keys from the key ring.
173 Trust Item Management
175 * Listing Trust Items:: Browsing the list of available trust items.
176 * Information About Trust Items:: Requesting information about trust items.
177 * Manipulating Trust Items:: Operations on trust items.
181 * Decrypt:: Decrypting a ciphertext.
182 * Verify:: Verifying a signature.
183 * Decrypt and Verify:: Decrypting a signed ciphertext.
184 * Sign:: Creating a signature.
185 * Encrypt:: Encrypting a plaintext.
189 * Selecting Signers:: How to choose the keys to sign with.
190 * Creating a Signature:: How to create a signature.
194 * Encrypting a Plaintext:: How to encrypt a plaintext.
198 * Waiting For Completion:: Waiting until an operation is completed.
199 * Using External Event Loops:: Advanced control over what happens when.
201 Using External Event Loops
203 * I/O Callback Interface:: How I/O callbacks are registered.
204 * Registering I/O Callbacks:: How to use I/O callbacks for a context.
205 * I/O Callback Example:: An example how to use I/O callbacks.
206 * I/O Callback Example GTK+:: How to integrate @acronym{GPGME} in GTK+.
207 * I/O Callback Example GDK:: How to integrate @acronym{GPGME} in GDK.
213 @chapter Introduction
215 `GnuPG Made Easy' (@acronym{GPGME}) is a C language library that
216 allows to add support for cryptography to a program. It is designed
217 to make access to public key crypto engines like GnuPG or GpgSM easier
218 for applications. @acronym{GPGME} provides a high-level crypto API
219 for encryption, decryption, signing, signature verification and key
222 @acronym{GPGME} uses GnuPG and GpgSM as its backends to support
223 OpenPGP and the Cryptographic Message Syntax (CMS).
226 * Getting Started:: Purpose of the manual, and how to use it.
227 * Features:: Reasons to install and use @acronym{GPGME}.
228 * Overview:: Basic architecture of the @acronym{GPGME} library.
232 @node Getting Started
233 @section Getting Started
235 This manual documents the @acronym{GPGME} library programming
236 interface. All functions and data types provided by the library are
239 The reader is assumed to possess basic knowledge about cryptography in
240 general, and public key cryptography in particular. The underlying
241 cryptographic engines that are used by the library are not explained,
242 but where necessary, special features or requirements by an engine are
243 mentioned as far as they are relevant to @acronym{GPGME} or its users.
245 This manual can be used in several ways. If read from the beginning
246 to the end, it gives a good introduction into the library and how it
247 can be used in an application. Forward references are included where
248 necessary. Later on, the manual can be used as a reference manual to
249 get just the information needed about any particular interface of the
250 library. Experienced programmers might want to start looking at the
251 examples at the end of the manual, and then only read up those parts
252 of the interface which are unclear.
258 @acronym{GPGME} has a couple of advantages over other libraries doing
259 a similar job, and over implementing support for GnuPG or other crypto
260 engines into your application directly.
263 @item it's free software
264 Anybody can use, modify, and redistribute it under the terms of the GNU
265 General Public License (@pxref{Copying}).
268 @acronym{GPGME} provides transparent support for several cryptographic
269 protocols by different engines. Currently, @acronym{GPGME} supports
270 the OpenPGP protocol using GnuPG as the backend, and the Cryptographic
271 Message Syntax using GpgSM as the backend.
274 @acronym{GPGME} hides the differences between the protocols and
275 engines from the programmer behind an easy-to-use interface. This way
276 the programmer can focus on the other parts of the program, and still
277 integrate strong cryptography in his application. Once support for
278 @acronym{GPGME} has been added to a program, it is easy to add support
279 for other crypto protocols once @acronym{GPGME} backends provide them.
286 @acronym{GPGME} provides a data abstraction that is used to pass data
287 to the crypto engine, and receive returned data from it. Data can be
288 read from memory or from files, but it can also be provided by a
291 The actual cryptographic operations are always set within a context.
292 A context provides configuration parameters that define the behaviour
293 of all operations performed within it. Only one operation per context
294 is allowed at any time, but when one operation is finished, you can
295 run the next operation in the same context. There can be more than
296 one context, and all can run different operations at the same time.
298 Furthermore, @acronym{GPGME} has rich key management facilities
299 including listing keys, querying their attributes, generating,
300 importing, exporting and deleting keys, and acquiring information
301 about the trust path.
303 With some precautions, @acronym{GPGME} can be used in a multi-threaded
304 environment, although it is not completely thread safe and thus needs
305 the support of the application.
311 To use @acronym{GPGME}, you have to perform some changes to your
312 sources and the build system. The necessary changes are small and
313 explained in the following sections. At the end of this chapter, it
314 is described how the library is initialized, and how the requirements
315 of the library are verified.
318 * Header:: What header file you need to include.
319 * Building the Source:: Compiler options to be used.
320 * Using Automake:: Compiler options to be used the easy way.
321 * Library Version Check:: Getting and verifying the library version.
322 * Multi Threading:: How @acronym{GPGME} can be used in an MT environment.
331 All interfaces (data types and functions) of the library are defined
332 in the header file `gpgme.h'. You must include this in all programs
333 using the library, either directly or through some other header file,
340 The name space of @acronym{GPGME} is @code{gpgme_*} for function names
341 and data types and @code{GPGME_*} for other symbols. Symbols internal
342 to @acronym{GPGME} take the form @code{_gpgme_*} and @code{_GPGME_*}.
344 Because @acronym{GPGME} links to the Assuan library, linking to
345 @acronym{GPGME} will also use the @code{assuan_*} and @code{_assuan_*}
346 name space indirectly.
348 Because @acronym{GPGME} makes use of the GPG Error library, using
349 @acronym{GPGME} will also use the @code{GPG_ERR_*} name space
350 directly, and the @code{gpg_err*} and @code{gpg_str*} name space
354 @node Building the Source
355 @section Building the Source
356 @cindex compiler options
357 @cindex compiler flags
359 If you want to compile a source file including the `gpgme.h' header
360 file, you must make sure that the compiler can find it in the
361 directory hierarchy. This is accomplished by adding the path to the
362 directory in which the header file is located to the compilers include
363 file search path (via the @option{-I} option).
365 However, the path to the include file is determined at the time the
366 source is configured. To solve this problem, gpgme ships with a small
367 helper program @command{gpgme-config} that knows about the path to the
368 include file and other configuration options. The options that need
369 to be added to the compiler invocation at compile time are output by
370 the @option{--cflags} option to @command{gpgme-config}. The following
371 example shows how it can be used at the command line:
374 gcc -c foo.c `gpgme-config --cflags`
377 Adding the output of @samp{gpgme-config --cflags} to the compiler
378 command line will ensure that the compiler can find the
379 @acronym{GPGME} header file.
381 A similar problem occurs when linking the program with the library.
382 Again, the compiler has to find the library files. For this to work,
383 the path to the library files has to be added to the library search
384 path (via the @option{-L} option). For this, the option
385 @option{--libs} to @command{gpgme-config} can be used. For
386 convenience, this option also outputs all other options that are
387 required to link the program with @acronym{GPGME} (in particular, the
388 @samp{-lgpgme} option). The example shows how to link @file{foo.o}
389 with the @acronym{GPGME} library to a program @command{foo}.
392 gcc -o foo foo.o `gpgme-config --libs`
395 Of course you can also combine both examples to a single command by
396 specifying both options to @command{gpgme-config}:
399 gcc -o foo foo.c `gpgme-config --cflags --libs`
404 @section Using Automake
408 It is much easier if you use GNU Automake instead of writing your own
409 Makefiles. If you do that you do not have to worry about finding and
410 invoking the @command{gpgme-config} script at all. @acronym{GPGME}
411 provides an extension to Automake that does all the work for you.
413 @c A simple macro for optional variables.
415 @r{[}@var{\varname\}@r{]}
417 @defmac AM_PATH_GPGME (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
418 Check whether @acronym{GPGME} (at least version @var{minimum-version},
419 if given) exists on the host system. If it is found, execute
420 @var{action-if-found}, otherwise do @var{action-if-not-found}, if
423 Additionally, the function defines @code{GPGME_CFLAGS} to the flags
424 needed for compilation of the program to find the @file{gpgme.h}
425 header file, and @code{GPGME_LIBS} to the linker flags needed to link
426 the program to the @acronym{GPGME} library.
429 You can use the defined Autoconf variables like this in your
433 AM_CPPFLAGS = $(GPGME_CFLAGS)
434 LDADD = $(GPGME_LIBS)
438 @node Library Version Check
439 @section Library Version Check
440 @cindex version check, of the library
442 @deftypefun {const char *} gpgme_check_version (@w{const char *@var{required_version}})
443 The function @code{gpgme_check_version} has three purposes. It can be
444 used to retrieve the version number of the library. In addition it
445 can verify that the version number is higher than a certain required
446 version number. In either case, the function initializes some
447 sub-systems, and for this reason alone it must be invoked early in
448 your program, before you make use of the other functions in
451 If @var{required_version} is @code{NULL}, the function returns a
452 pointer to a statically allocated string containing the version number
455 If @var{required_version} is not @code{NULL}, it should point to a
456 string containing a version number, and the function checks that the
457 version of the library is at least as high as the version number
458 provided. In this case, the function returns a pointer to a
459 statically allocated string containing the version number of the
460 library. If @var{REQUIRED_VERSION} is not a valid version number, or
461 if the version requirement is not met, the function returns
464 If you use a version of a library that is backwards compatible with
465 older releases, but contains additional interfaces which your program
466 uses, this function provides a run-time check if the necessary
467 features are provided by the installed version of the library.
471 @node Multi Threading
472 @section Multi Threading
473 @cindex thread-safeness
474 @cindex multi-threading
476 The @acronym{GPGME} library is not entirely thread-safe, but it can
477 still be used in a multi-threaded environment if some care is taken.
478 If the following requirements are met, there should be no race
479 conditions to worry about:
483 @acronym{GPGME} supports the thread libraries pthread and GNU Pth.
484 The support for this has to be enabled at compile time.
485 @acronym{GPGME} will automatically detect the location in which the
486 thread libraries are installed and activate the support for them at
489 Support for other thread libraries is very easy to add. Please
490 contact us if you have the need.
493 If you link your program dynamically to @acronym{GPGME} and your
494 supported thread library, @acronym{GPGME} will automatically detect
495 the presence of this library and activate its use. You must link to
496 the thread library before linking to @acronym{GPGME}. If you link to
497 both pthread and GNU Pth, @acronym{GPGME} will use the pthread
498 support. This feature requires weak symbol support.
501 If you link your program statically to @acronym{GPGME}, or your system
502 does not support weak symbols, there is currently no easy way to make
503 sure that @acronym{GPGME} detects the presence of the thread library.
504 This will be solved in a future version.
507 The function @code{gpgme_check_version} must be called before any
508 other function in the library, because it initializes the thread
509 support subsystem in @acronym{GPGME}. To achieve this in all
510 generality, it is necessary to synchronize the call to this function
511 with all other calls to functions in the library, using the
512 synchronization mechanisms available in your thread library.
513 Otherwise, specific compiler or CPU memory cache optimizations could
514 lead to the situation where a thread is started and uses
515 @acronym{GPGME} before the effects of the initialization are visible
516 for this thread. It doesn't even suffice to call
517 @code{gpgme_check_version} before creating this other
518 thread@footnote{In SMP systems the new thread could be started on
519 another CPU before the effects of the initialization are seen by that
520 CPU's memory cache. Not doing proper synchronization here leads to
521 the same problems the double-checked locking idiom has. You might
522 find that if you don't do proper synchronization, it still works in
523 most configurations. Don't let this fool you. Someday it might lead
524 to subtle bugs when someone tries it on a DEC Alpha or an SMP
527 For example, if you are using POSIX threads, each thread that wants to
528 call functions in @acronym{GPGME} could call the following function
529 before any function in the library:
535 initialize_gpgme (void)
537 static int gpgme_init;
538 static pthread_mutext_t gpgme_init_lock = PTHREAD_MUTEX_INITIALIZER;
540 pthread_mutex_lock (&gpgme_init_lock);
543 gpgme_check_version ();
546 pthread_mutex_unlock (&gpgme_init_lock);
551 Any @code{gpgme_data_t} and @code{gpgme_ctx_t} object must only be
552 accessed by one thread at a time. If multiple threads want to deal
553 with the same object, the caller has to make sure that operations on
554 that object are fully synchronized.
557 Only one thread at any time is allowed to call @code{gpgme_wait}. If
558 multiple threads call this function, the caller must make sure that
559 all invocations are fully synchronized. It is safe to start
560 asynchronous operations while a thread is running in gpgme_wait.
564 @node Protocols and Engines
565 @chapter Protocols and Engines
568 @cindex crypto engine
570 @cindex crypto backend
572 @acronym{GPGME} supports several cryptographic protocols, however, it
573 does not implement them. Rather it uses backends (also called
574 engines) which implement the protocol. @acronym{GPGME} uses
575 inter-process communication to pass data back and forth between the
576 application and the backend, but the details of the communication
577 protocol and invocation of the backend is completely hidden by the
578 interface. All complexity is handled by @acronym{GPGME}. Where an
579 exchange of information between the application and the backend is
580 necessary, @acronym{GPGME} provides the necessary callback function
581 hooks and further interfaces.
583 @deftp {Data type} {enum gpgme_protocol_t}
584 @tindex gpgme_protocol_t
585 The @code{gpgme_protocol_t} type specifies the set of possible protocol
586 values that are supported by @acronym{GPGME}. The following protocols
590 @item GPGME_PROTOCOL_OpenPGP
591 This specifies the OpenPGP protocol.
593 @item GPGME_PROTOCOL_CMS
594 This specifies the Cryptographic Message Syntax.
599 @deftypefun const char *gpgme_get_protocol_name (@w{gpgme_protocol_t @var{protocol}})
600 The function @code{gpgme_get_protocol_name} returns a statically
601 allocated string describing the protocol @var{protocol}, or
602 @code{NULL} if the protocol number is not valid.
606 * Engine Version Check:: Verifying the engine version.
607 * Engine Information:: Obtaining more information about the engines.
608 * OpenPGP:: Support for the OpenPGP protocol.
609 * Cryptographic Message Syntax:: Support for the CMS.
613 @node Engine Version Check
614 @section Engine Version Check
615 @cindex version check, of the engines
617 @deftypefun gpgme_error_t gpgme_engine_check_version (@w{gpgme_protocol_t @var{protocol}})
618 The function @code{gpgme_engine_check_version} verifies that the
619 engine implementing the protocol @var{PROTOCOL} is installed in the
620 expected path and meets the version requirement of @acronym{GPGME}.
622 This function returns the error code @code{GPG_ERR_NO_ERROR} if the
623 engine is available and @code{GPG_ERR_INV_ENGINE} if it is not.
627 @node Engine Information
628 @section Engine Information
629 @cindex engine, information about
631 @deftp {Data type} {gpgme_engine_info_t}
632 @tindex gpgme_protocol_t
633 The @code{gpgme_engine_info_t} type specifies a pointer to a structure
634 describing a crypto engine. The structure contains the following
638 @item gpgme_engine_info_t next
639 This is a pointer to the next engine info structure in the linked
640 list, or @code{NULL} if this is the last element.
642 @item gpgme_protocol_t protocol
643 This is the protocol for which the crypto engine is used. You can
644 convert this to a string with @code{gpgme_get_protocol_name} for
647 @item const char *file_name
648 This is a string holding the file name of the executable of the crypto
649 engine. Currently, it is never @code{NULL}, but using @code{NULL} is
650 reserved for future use, so always check before you use it.
652 @item const char *version
653 This is a string containing the version number of the crypto engine.
654 It might be @code{NULL} if the version number can not be determined,
655 for example because the executable doesn't exist or is invalid.
657 @item const char *req_version
658 This is a string containing the minimum required version number of the
659 crypto engine for @acronym{GPGME} to work correctly. This is the
660 version number that @code{gpgme_engine_check_version} verifies
661 against. Currently, it is never @code{NULL}, but using @code{NULL} is
662 reserved for future use, so always check before you use it.
666 @deftypefun gpgme_error_t gpgme_get_engine_info (gpgme_engine_info_t *info)
667 The function @code{gpgme_get_engine_info} returns a linked list of
668 engine info structures in @var{info}. Each info structure describes
669 one configured backend.
671 The memory for the info structures is allocated the first time this
672 function is invoked, and must not be freed by the caller.
674 This function returns the error code @code{GPG_ERR_NO_ERROR} if
675 successful, and a system error if the memory could not be allocated.
678 Here is an example how you can provide more diagnostics if you receive
679 an error message which indicates that the crypto engine is invalid.
687 if (gpgme_err_code (err) == GPG_ERR_INV_ENGINE)
689 gpgme_engine_info_t info;
690 err = gpgme_get_engine_info (&info);
693 while (info && info->protocol != gpgme_get_protocol (ctx))
696 fprintf (stderr, "GPGME compiled without support for protocol %s",
697 gpgme_get_protocol_name (info->protocol));
698 else if (info->path && !info->version)
699 fprintf (stderr, "Engine %s not installed properly",
701 else if (info->path && info->version && info->req_version)
702 fprintf (stderr, "Engine %s version %s installed, "
703 "but at least version %s required", info->path,
704 info->version, info->req_version);
706 fprintf (stderr, "Unknown problem with engine for protocol %s",
707 gpgme_get_protocol_name (info->protocol));
717 @cindex protocol, GnuPG
718 @cindex engine, GnuPG
720 OpenPGP is implemented by GnuPG, the @acronym{GNU} Privacy Guard.
721 This is the first protocol that was supported by @acronym{GPGME}.
723 The OpenPGP protocol is specified by @code{GPGME_PROTOCOL_OpenPGP}.
726 @node Cryptographic Message Syntax
727 @section Cryptographic Message Syntax
729 @cindex cryptographic message syntax
731 @cindex protocol, CMS
732 @cindex engine, GpgSM
734 @cindex protocol, S/MIME
736 @acronym{CMS} is implemented by GpgSM, the S/MIME implementation for
739 The @acronym{CMS} protocol is specified by @code{GPGME_PROTOCOL_CMS}.
746 The crypto backends support a variety of algorithms used in public key
747 cryptography. The following sections list the identifiers used to
748 denote such an algorithm.
751 * Public Key Algorithms:: A list of all public key algorithms.
752 * Hash Algorithms:: A list of all hash algorithms.
756 @node Public Key Algorithms
757 @section Public Key Algorithms
758 @cindex algorithms, public key
759 @cindex public key algorithms
761 Public key algorithms are used for encryption, decryption, signing and
762 verification of signatures.
764 @deftp {Data type} {enum gpgme_pubkey_algo_t}
765 @tindex gpgme_pubkey_algo_t
766 The @code{gpgme_pubkey_algo_t} type specifies the set of all public key
767 algorithms that are supported by @acronym{GPGME}. Possible values
772 This value indicates the RSA (Rivest, Shamir, Adleman) algorithm.
775 Deprecated. This value indicates the RSA (Rivest, Shamir, Adleman)
776 algorithm for encryption and decryption only.
779 Deprecated. This value indicates the RSA (Rivest, Shamir, Adleman)
780 algorithm for signing and verification only.
783 This value indicates DSA, the Digital Signature Algorithm.
786 This value indicates ElGamal.
789 This value also indicates ElGamal and is used specifically in GnuPG.
793 @deftypefun {const char *} gpgme_pubkey_algo_name (@w{gpgme_pubkey_algo_t @var{algo}})
794 The function @code{gpgme_pubkey_algo_name} returns a pointer to a
795 statically allocated string containing a description of the public key
796 algorithm @var{algo}. This string can be used to output the name of
797 the public key algorithm to the user.
799 If @var{algo} is not a valid public key algorithm, @code{NULL} is
804 @node Hash Algorithms
805 @section Hash Algorithms
806 @cindex algorithms, hash
807 @cindex algorithms, message digest
808 @cindex hash algorithms
809 @cindex message digest algorithms
811 Hash (message digest) algorithms are used to compress a long message
812 to make it suitable for public key cryptography.
814 @deftp {Data type} {enum gpgme_hash_algo_t}
815 @tindex gpgme_hash_algo_t
816 The @code{gpgme_hash_algo_t} type specifies the set of all hash algorithms
817 that are supported by @acronym{GPGME}. Possible values are:
822 @item GPGME_MD_RMD160
826 @item GPGME_MD_SHA256
827 @item GPGME_MD_SHA384
828 @item GPGME_MD_SHA512
831 @item GPGME_MD_CRC32_RFC1510
832 @item GPGME_MD_CRC24_RFC2440
836 @deftypefun {const char *} gpgme_hash_algo_name (@w{gpgme_hash_algo_t @var{algo}})
837 The function @code{gpgme_hash_algo_name} returns a pointer to a
838 statically allocated string containing a description of the hash
839 algorithm @var{algo}. This string can be used to output the name of
840 the hash algorithm to the user.
842 If @var{algo} is not a valid hash algorithm, @code{NULL} is returned.
847 @chapter Error Handling
848 @cindex error handling
850 Many functions in @acronym{GPGME} can return an error if they fail.
851 For this reason, the application should always catch the error
852 condition and take appropriate measures, for example by releasing the
853 resources and passing the error up to the caller, or by displaying a
854 descriptive message to the user and cancelling the operation.
856 Some error values do not indicate a system error or an error in the
857 operation, but the result of an operation that failed properly. For
858 example, if you try to decrypt a tempered message, the decryption will
859 fail. Another error value actually means that the end of a data
860 buffer or list has been reached. The following descriptions explain
861 for many error codes what they mean usually. Some error values have
862 specific meanings if returned by a certain functions. Such cases are
863 described in the documentation of those functions.
865 @acronym{GPGME} uses the @code{libgpg-error} library. This allows to
866 share the error codes with other components of the GnuPG system, and
867 thus pass error values transparently from the crypto engine, or some
868 helper application of the crypto engine, to the user. This way no
869 information is lost. As a consequence, @acronym{GPGME} does not use
870 its own identifiers for error codes, but uses those provided by
871 @code{libgpg-error}. They usually start with @code{GPG_ERR_}.
873 However, @acronym{GPGME} does provide aliases for the functions
874 defined in libgpg-error, which might be preferred for name space
878 * Error Values:: The error value and what it means.
879 * Error Sources:: A list of important error sources.
880 * Error Codes:: A list of important error codes.
881 * Error Strings:: How to get a descriptive string from a value.
886 @section Error Values
889 @cindex error sources
891 @deftp {Data type} {gpgme_err_code_t}
892 The @code{gpgme_err_code_t} type is an alias for the @code{libgpg-error}
893 type @code{gpg_err_code_t}. The error code indicates the type of an
894 error, or the reason why an operation failed.
896 A list of important error codes can be found in the next section.
899 @deftp {Data type} {gpgme_err_source_t}
900 The @code{gpgme_err_source_t} type is an alias for the
901 @code{libgpg-error} type @code{gpg_err_source_t}. The error source
902 has not a precisely defined meaning. Sometimes it is the place where
903 the error happened, sometimes it is the place where an error was
904 encoded into an error value. Usually the error source will give an
905 indication to where to look for the problem. This is not always true,
906 but it is attempted to achieve this goal.
908 A list of important error sources can be found in the next section.
911 @deftp {Data type} {gpgme_error_t}
912 The @code{gpgme_error_t} type is an alias for the @code{libgpg-error}
913 type @code{gpg_error_t}. An error value like this has always two
914 components, an error code and an error source. Both together form the
917 Thus, the error value can not be directly compared against an error
918 code, but the accessor functions described below must be used.
919 However, it is guaranteed that only 0 is used to indicate success
920 (@code{GPG_ERR_NO_ERROR}), and that in this case all other parts of
921 the error value are set to 0, too.
923 Note that in @acronym{GPGME}, the error source is used purely for
924 diagnostical purposes. Only the error code should be checked to test
925 for a certain outcome of a function. The manual only documents the
926 error code part of an error value. The error source is left
927 unspecified and might be anything.
930 @deftypefun {static __inline__ gpgme_err_code_t} gpgme_err_code (@w{gpgme_error_t @var{err}})
931 The static inline function @code{gpgme_err_code} returns the
932 @code{gpgme_err_code_t} component of the error value @var{err}. This
933 function must be used to extract the error code from an error value in
934 order to compare it with the @code{GPG_ERR_*} error code macros.
937 @deftypefun {static __inline__ gpgme_err_source_t} gpgme_err_source (@w{gpgme_error_t @var{err}})
938 The static inline function @code{gpgme_err_source} returns the
939 @code{gpgme_err_source_t} component of the error value @var{err}. This
940 function must be used to extract the error source from an error value in
941 order to compare it with the @code{GPG_ERR_SOURCE_*} error source macros.
944 @deftypefun {static __inline__ gpgme_error_t} gpgme_err_make (@w{gpgme_err_source_t @var{source}}, @w{gpgme_err_code_t @var{code}})
945 The static inline function @code{gpgme_err_make} returns the error
946 value consisting of the error source @var{source} and the error code
949 This function can be used in callback functions to construct an error
950 value to return it to the library.
953 @deftypefun {static __inline__ gpgme_error_t} gpgme_error (@w{gpgme_err_code_t @var{code}})
954 The static inline function @code{gpgme_error} returns the error value
955 consisting of the default error source and the error code @var{code}.
957 For @acronym{GPGME} applications, the default error source is
958 @code{GPG_ERR_SOURCE_USER_1}. You can define
959 @code{GPGME_ERR_SOURCE_DEFAULT} before including @file{gpgme.h} to
962 This function can be used in callback functions to construct an error
963 value to return it to the library.
966 The @code{libgpg-error} library provides error codes for all system
967 error numbers it knows about. If @var{err} is an unknown error
968 number, the error code @code{GPG_ERR_UNKNOWN_ERRNO} is used. The
969 following functions can be used to construct error values from system
972 @deftypefun {gpgme_error_t} gpgme_err_make_from_errno (@w{gpgme_err_source_t @var{source}}, @w{int @var{err}})
973 The function @code{gpgme_err_make_from_errno} is like
974 @code{gpgme_err_make}, but it takes a system error like @code{errno}
975 instead of a @code{gpgme_err_code_t} error code.
978 @deftypefun {gpgme_error_t} gpgme_error_from_errno (@w{int @var{err}})
979 The function @code{gpgme_error_from_errno} is like @code{gpgme_error},
980 but it takes a system error like @code{errno} instead of a
981 @code{gpgme_err_code_t} error code.
984 Sometimes you might want to map system error numbers to error codes
985 directly, or map an error code representing a system error back to the
986 system error number. The following functions can be used to do that.
988 @deftypefun {gpgme_err_code_t} gpgme_err_code_from_errno (@w{int @var{err}})
989 The function @code{gpgme_err_code_from_errno} returns the error code
990 for the system error @var{err}. If @var{err} is not a known system
991 error, the function returns @code{GPG_ERR_UNKNOWN_ERRNO}.
994 @deftypefun {int} gpgme_err_code_to_errno (@w{gpgme_err_code_t @var{err}})
995 The function @code{gpgme_err_code_to_errno} returns the system error
996 for the error code @var{err}. If @var{err} is not an error code
997 representing a system error, or if this system error is not defined on
998 this system, the function returns @code{0}.
1003 @section Error Sources
1004 @cindex error codes, list of
1006 The library @code{libgpg-error} defines an error source for every
1007 component of the GnuPG system. The error source part of an error
1008 value is not well defined. As such it is mainly useful to improve the
1009 diagnostic error message for the user.
1011 If the error code part of an error value is @code{0}, the whole error
1012 value will be @code{0}. In this case the error source part is of
1013 course @code{GPG_ERR_SOURCE_UNKNOWN}.
1015 The list of error sources that might occur in applications using
1019 @item GPG_ERR_SOURCE_UNKNOWN
1020 The error source is not known. The value of this error source is
1023 @item GPG_ERR_SOURCE_GPGME
1024 The error source is @acronym{GPGME} itself. This is the default for
1025 errors that occur in the @acronym{GPGME} library.
1027 @item GPG_ERR_SOURCE_GPG
1028 The error source is GnuPG, which is the crypto engine used for the
1031 @item GPG_ERR_SOURCE_GPGSM
1032 The error source is GPGSM, which is the crypto engine used for the
1035 @item GPG_ERR_SOURCE_GCRYPT
1036 The error source is @code{libgcrypt}, which is used by crypto engines
1037 to perform cryptographic operations.
1039 @item GPG_ERR_SOURCE_GPGAGENT
1040 The error source is @command{gpg-agent}, which is used by crypto
1041 engines to perform operations with the secret key.
1043 @item GPG_ERR_SOURCE_PINENTRY
1044 The error source is @command{pinentry}, which is used by
1045 @command{gpg-agent} to query the passphrase to unlock a secret key.
1047 @item GPG_ERR_SOURCE_SCD
1048 The error source is the SmartCard Daemon, which is used by
1049 @command{gpg-agent} to delegate operations with the secret key to a
1052 @item GPG_ERR_SOURCE_KEYBOX
1053 The error source is @code{libkbx}, a library used by the crypto
1054 engines to manage local keyrings.
1056 @item GPG_ERR_SOURCE_USER_1
1057 @item GPG_ERR_SOURCE_USER_2
1058 @item GPG_ERR_SOURCE_USER_3
1059 @item GPG_ERR_SOURCE_USER_4
1060 These error sources are not used by any GnuPG component and can be
1061 used by other software. For example, applications using
1062 @acronym{GPGME} can use them to mark error values coming from callback
1063 handlers. Thus @code{GPG_ERR_SOURCE_USER_1} is the default for errors
1064 created with @code{gpgme_error} and @code{gpgme_error_from_errno},
1065 unless you define @code{GPGME_ERR_SOURCE_DEFAULT} before including
1071 @section Error Codes
1072 @cindex error codes, list of
1074 The library @code{libgpg-error} defines many error values. Most of
1075 them are not used by @code{GPGME} directly, but might be returned by
1076 @acronym{GPGME} because it received them from the crypto engine. The
1077 below list only includes such error codes that have a specific meaning
1078 in @code{GPGME}, or which are so common that you should know about
1083 This value indicates the end of a list, buffer or file.
1085 @item GPG_ERR_NO_ERROR
1086 This value indicates success. The value of this error code is
1087 @code{0}. Also, it is guaranteed that an error value made from the
1088 error code @code{0} will be @code{0} itself (as a whole). This means
1089 that the error source information is lost for this error code,
1090 however, as this error code indicates that no error occured, this is
1091 generally not a problem.
1093 @item GPG_ERR_GENERAL
1094 This value means that something went wrong, but either there is not
1095 enough information about the problem to return a more useful error
1096 value, or there is no separate error value for this type of problem.
1098 @item GPG_ERR_ENOMEM
1099 This value means that an out-of-memory condition occurred.
1102 System errors are mapped to GPG_ERR_FOO where FOO is the symbol for
1105 @item GPG_ERR_INV_VALUE
1106 This value means that some user provided data was out of range. This
1107 can also refer to objects. For example, if an empty
1108 @code{gpgme_data_t} object was expected, but one containing data was
1109 provided, this error value is returned.
1111 @item GPG_ERR_UNUSABLE_PUBKEY
1112 This value means that some recipients for a message were invalid.
1114 @item GPG_ERR_UNUSABLE_SECKEY
1115 This value means that some signers were invalid.
1117 @item GPG_ERR_NO_DATA
1118 This value means that a @code{gpgme_data_t} object which was expected
1119 to have content was found empty.
1121 @item GPG_ERR_CONFLICT
1122 This value means that a conflict of some sort occurred.
1124 @item GPG_ERR_NOT_IMPLEMENTED
1125 This value indicates that the specific function (or operation) is not
1126 implemented. This error should never happen. It can only occur if
1127 you use certain values or configuration options which do not work,
1128 but for which we think that they should work at some later time.
1130 @item GPG_ERR_DECRYPT_FAILED
1131 This value indicates that a decryption operation was unsuccessful.
1133 @item GPG_ERR_BAD_PASSPHRASE
1134 This value means that the user did not provide a correct passphrase
1137 @item GPG_ERR_CANCELED
1138 This value means that the operation was canceled.
1140 @item GPG_ERR_INV_ENGINE
1141 This value means that the engine that implements the desired protocol
1142 is currently not available. This can either be because the sources
1143 were configured to exclude support for this engine, or because the
1144 engine is not installed properly.
1146 @item GPG_ERR_AMBIGUOUS_NAME
1147 This value indicates that a user ID did not specify a unique key.
1149 @item GPG_ERR_WRONG_KEY_USAGE
1150 This value indicates that a key is not used appropriately.
1152 @item GPG_ERR_CERT_REVOKED
1153 This value indicates that a key signature was revoced.
1155 @item GPG_ERR_CERT_EXPIRED
1156 This value indicates that a key signature expired.
1158 @item GPG_ERR_NO_CRL_KNOWN
1159 This value indicates that no certificate revocation list is known for
1162 @item GPG_ERR_NO_POLICY_MATCH
1163 This value indicates that a policy issue occured.
1165 @item GPG_ERR_NO_SECKEY
1166 This value indicates that no secret key for the user ID is available.
1168 @item GPG_ERR_MISSING_CERT
1169 This value indicates that a key could not be imported because the
1170 issuer certificate is missing.
1172 @item GPG_ERR_BAD_CERT_CHAIN
1173 This value indicates that a key could not be imported because its
1174 certificate chain is not good, for example it could be too long.
1176 @item GPG_ERR_UNSUPPORTED_ALGORITHM
1177 This value means a verification failed because the cryptographic
1178 algorithm is not supported by the crypto backend.
1180 @item GPG_ERR_BAD_SIGNATURE
1181 This value means a verification failed because the signature is bad.
1183 @item GPG_ERR_NO_PUBKEY
1184 This value means a verification failed because the public key is not
1187 @item GPG_ERR_USER_1
1188 @item GPG_ERR_USER_2
1190 @item GPG_ERR_USER_16
1191 These error codes are not used by any GnuPG component and can be
1192 freely used by other software. Applications using @acronym{GPGME}
1193 might use them to mark specific errors returned by callback handlers
1194 if no suitable error codes (including the system errors) for
1195 these errors exist already.
1200 @section Error Strings
1201 @cindex error values, printing of
1202 @cindex error codes, printing of
1203 @cindex error sources, printing of
1204 @cindex error strings
1206 @deftypefun {const char *} gpgme_strerror (@w{gpgme_error_t @var{err}})
1207 The function @code{gpgme_strerror} returns a pointer to a statically
1208 allocated string containing a description of the error code contained
1209 in the error value @var{err}. This string can be used to output a
1210 diagnostic message to the user.
1214 @deftypefun {const char *} gpgme_strsource (@w{gpgme_error_t @var{err}})
1215 The function @code{gpgme_strerror} returns a pointer to a statically
1216 allocated string containing a description of the error source
1217 contained in the error value @var{err}. This string can be used to
1218 output a diagnostic message to the user.
1221 The following example illustrates the use of @code{gpgme_strerror}:
1225 gpgme_error_t err = gpgme_new (&ctx);
1228 fprintf (stderr, "%s: creating GpgME context failed: %s: %s\n",
1229 argv[0], gpgme_strsource (err), gpgme_strerror (err));
1235 @node Exchanging Data
1236 @chapter Exchanging Data
1237 @cindex data, exchanging
1239 A lot of data has to be exchanged between the user and the crypto
1240 engine, like plaintext messages, ciphertext, signatures and
1241 information about the keys. The technical details about exchanging
1242 the data information are completely abstracted by @acronym{GPGME}.
1243 The user provides and receives the data via @code{gpgme_data_t} objects,
1244 regardless of the communication protocol between @acronym{GPGME} and
1245 the crypto engine in use.
1247 @deftp {Data type} {gpgme_data_t}
1248 The @code{gpgme_data_t} type is a handle for a container for generic
1249 data, which is used by @acronym{GPGME} to exchange data with the user.
1253 * Creating Data Buffers:: Creating new data buffers.
1254 * Destroying Data Buffers:: Releasing data buffers.
1255 * Manipulating Data Buffers:: Operations on data buffers.
1259 @node Creating Data Buffers
1260 @section Creating Data Buffers
1261 @cindex data buffer, creation
1263 Data objects can be based on memory, files, or callback functions
1264 provided by the user. Not all operations are supported by all
1269 * Memory Based Data Buffers:: Creating memory based data buffers.
1270 * File Based Data Buffers:: Creating file based data buffers.
1271 * Callback Based Data Buffers:: Creating callback based data buffers.
1275 @node Memory Based Data Buffers
1276 @subsection Memory Based Data Buffers
1278 Memory based data objects store all data in allocated memory. This is
1279 convenient, but only practical for an amount of data that is a
1280 fraction of the available physical memory. The data has to be copied
1281 from its source and to its destination, which can often be avoided by
1282 using one of the other data object
1284 @deftypefun gpgme_error_t gpgme_data_new (@w{gpgme_data_t *@var{dh}})
1285 The function @code{gpgme_data_new} creates a new @code{gpgme_data_t}
1286 object and returns a handle for it in @var{dh}. The data object is
1287 memory based and initially empty.
1289 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1290 data object was successfully created, @code{GPG_ERR_INV_VALUE} if
1291 @var{dh} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if not
1292 enough memory is available.
1295 @deftypefun gpgme_error_t gpgme_data_new_from_mem (@w{gpgme_data_t *@var{dh}}, @w{const char *@var{buffer}}, @w{size_t @var{size}}, @w{int @var{copy}})
1296 The function @code{gpgme_data_new_from_mem} creates a new
1297 @code{gpgme_data_t} object and fills it with @var{size} bytes starting
1300 If @var{copy} is not zero, a private copy of the data is made. If
1301 @var{copy} is zero, the data is taken from the specified buffer as
1302 needed, and the user has to ensure that the buffer remains valid for
1303 the whole life span of the data object.
1305 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1306 data object was successfully created, @code{GPG_ERR_INV_VALUE} if
1307 @var{dh} or @var{buffer} is not a valid pointer, and
1308 @code{GPG_ERR_ENOMEM} if not enough memory is available.
1311 @deftypefun gpgme_error_t gpgme_data_new_from_file (@w{gpgme_data_t *@var{dh}}, @w{const char *@var{filename}}, @w{int @var{copy}})
1312 The function @code{gpgme_data_new_from_file} creates a new
1313 @code{gpgme_data_t} object and fills it with the content of the file
1316 If @var{copy} is not zero, the whole file is read in at initialization
1317 time and the file is not used anymore after that. This is the only
1318 mode supported currently. Later, a value of zero for @var{copy} might
1319 cause all reads to be delayed until the data is needed, but this is
1320 not yet implemented.
1322 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1323 data object was successfully created, @code{GPG_ERR_INV_VALUE} if
1324 @var{dh} or @var{filename} is not a valid pointer,
1325 @code{GPG_ERR_NOT_IMPLEMENTED} if @var{code} is zero, and
1326 @code{GPG_ERR_ENOMEM} if not enough memory is available.
1329 @deftypefun gpgme_error_t gpgme_data_new_from_filepart (@w{gpgme_data_t *@var{dh}}, @w{const char *@var{filename}}, @w{FILE *@var{fp}}, @w{off_t @var{offset}}, @w{size_t @var{length}})
1330 The function @code{gpgme_data_new_from_filepart} creates a new
1331 @code{gpgme_data_t} object and fills it with a part of the file specified
1332 by @var{filename} or @var{fp}.
1334 Exactly one of @var{filename} and @var{fp} must be non-zero, the other
1335 must be zero. The argument that is not zero specifies the file from
1336 which @var{length} bytes are read into the data object, starting from
1339 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1340 data object was successfully created, @code{GPG_ERR_INV_VALUE} if
1341 @var{dh} and exactly one of @var{filename} and @var{fp} is not a valid
1342 pointer, and @code{GPG_ERR_ENOMEM} if not enough memory is available.
1346 @node File Based Data Buffers
1347 @subsection File Based Data Buffers
1349 File based data objects operate directly on file descriptors or
1350 streams. Only a small amount of data is stored in core at any time,
1351 so the size of the data objects is not limited by @acronym{GPGME}.
1353 @deftypefun gpgme_error_t gpgme_data_new_from_fd (@w{gpgme_data_t *@var{dh}}, @w{int @var{fd}})
1354 The function @code{gpgme_data_new_from_fd} creates a new
1355 @code{gpgme_data_t} object and uses the file descriptor @var{fd} to read
1356 from (if used as an input data object) and write to (if used as an
1357 output data object).
1359 When using the data object as an input buffer, the function might read
1360 a bit more from the file descriptor than is actually needed by the
1361 crypto engine in the desired operation because of internal buffering.
1363 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1364 data object was successfully created, and @code{GPG_ERR_ENOMEM} if not
1365 enough memory is available.
1368 @deftypefun gpgme_error_t gpgme_data_new_from_stream (@w{gpgme_data_t *@var{dh}}, @w{FILE *@var{stream}})
1369 The function @code{gpgme_data_new_from_stream} creates a new
1370 @code{gpgme_data_t} object and uses the I/O stream @var{stream} to read
1371 from (if used as an input data object) and write to (if used as an
1372 output data object).
1374 When using the data object as an input buffer, the function might read
1375 a bit more from the stream than is actually needed by the crypto
1376 engine in the desired operation because of internal buffering.
1378 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1379 data object was successfully created, and @code{GPG_ERR_ENOMEM} if not
1380 enough memory is available.
1384 @node Callback Based Data Buffers
1385 @subsection Callback Based Data Buffers
1387 If neither memory nor file based data objects are a good fit for your
1388 application, you can implement the functions a data object provides
1389 yourself and create a data object from these callback functions.
1391 @deftp {Data type} {ssize_t (*gpgme_data_read_cb_t) (@w{void *@var{handle}}, @w{void @var{*buffer}}, @w{size_t @var{size}})}
1392 @tindex gpgme_data_read_cb_t
1393 The @code{gpgme_data_read_cb_t} type is the type of functions which
1394 @acronym{GPGME} calls if it wants to read data from a user-implemented
1395 data object. The function should read up to @var{size} bytes from the
1396 current read position into the space starting at @var{buffer}. The
1397 @var{handle} is provided by the user at data object creation time.
1399 The function should return the number of bytes read, 0 on EOF, and -1
1400 on error. If an error occurs, @var{errno} should be set to describe
1401 the type of the error.
1404 @deftp {Data type} {ssize_t (*gpgme_data_write_cb_t) (@w{void *@var{handle}}, @w{const void @var{*buffer}}, @w{size_t @var{size}})}
1405 @tindex gpgme_data_write_cb_t
1406 The @code{gpgme_data_write_cb_t} type is the type of functions which
1407 @acronym{GPGME} calls if it wants to write data to a user-implemented
1408 data object. The function should write up to @var{size} bytes to the
1409 current write position from the space starting at @var{buffer}. The
1410 @var{handle} is provided by the user at data object creation time.
1412 The function should return the number of bytes written, and -1 on
1413 error. If an error occurs, @var{errno} should be set to describe the
1417 @deftp {Data type} {off_t (*gpgme_data_seek_cb_t) (@w{void *@var{handle}}, @w{off_t @var{offset}}, @w{int @var{whence}})}
1418 @tindex gpgme_data_seek_cb_t
1419 The @code{gpgme_data_seek_cb_t} type is the type of functions which
1420 @acronym{GPGME} calls if it wants to change the current read/write
1421 position in a user-implemented data object, just like the @code{lseek}
1424 The function should return the new read/write position, and -1 on
1425 error. If an error occurs, @var{errno} should be set to describe the
1429 @deftp {Data type} {void (*gpgme_data_release_cb_t) (@w{void *@var{handle}})}
1430 @tindex gpgme_data_release_cb_t
1431 The @code{gpgme_data_release_cb_t} type is the type of functions which
1432 @acronym{GPGME} calls if it wants to destroy a user-implemented data
1433 object. The @var{handle} is provided by the user at data object
1437 @deftp {Data type} {struct gpgme_data_cbs}
1438 This structure is used to store the data callback interface functions
1439 described above. It has the following members:
1442 @item gpgme_data_read_cb_t read
1443 This is the function called by @acronym{GPGME} to read data from the
1444 data object. It is only required for input data object.
1446 @item gpgme_data_write_cb_t write
1447 This is the function called by @acronym{GPGME} to write data to the
1448 data object. It is only required for output data object.
1450 @item gpgme_data_seek_cb_t seek
1451 This is the function called by @acronym{GPGME} to change the current
1452 read/write pointer in the data object (if available). It is optional.
1454 @item gpgme_data_release_cb_t release
1455 This is the function called by @acronym{GPGME} to release a data
1456 object. It is optional.
1460 @deftypefun gpgme_error_t gpgme_data_new_from_cbs (@w{gpgme_data_t *@var{dh}}, @w{gpgme_data_cbs_t @var{cbs}}, @w{void *@var{handle}})
1461 The function @code{gpgme_data_new_from_cbs} creates a new
1462 @code{gpgme_data_t} object and uses the user-provided callback functions
1463 to operate on the data object.
1465 The handle @var{handle} is passed as first argument to the callback
1466 functions. This can be used to identify this data object.
1468 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1469 data object was successfully created, and @code{GPG_ERR_ENOMEM} if not
1470 enough memory is available.
1473 The following interface is deprecated and only provided for backward
1474 compatibility. Don't use it. It will be removed in a future version
1477 @deftypefun gpgme_error_t gpgme_data_new_with_read_cb (@w{gpgme_data_t *@var{dh}}, @w{int (*@var{readfunc})} (@w{void *@var{hook}}, @w{char *@var{buffer}}, @w{size_t @var{count}}, @w{size_t *@var{nread}}), @w{void *@var{hook_value}})
1478 The function @code{gpgme_data_new_with_read_cb} creates a new
1479 @code{gpgme_data_t} object and uses the callback function @var{readfunc}
1480 to retrieve the data on demand. As the callback function can supply
1481 the data in any way it wants, this is the most flexible data type
1482 @acronym{GPGME} provides. However, it can not be used to write data.
1484 The callback function receives @var{hook_value} as its first argument
1485 whenever it is invoked. It should return up to @var{count} bytes in
1486 @var{buffer}, and return the number of bytes actually read in
1487 @var{nread}. It may return @code{0} in @var{nread} if no data is
1488 currently available. To indicate @code{EOF} the function should
1489 return with an error code of @code{-1} and set @var{nread} to
1490 @code{0}. The callback function may support to reset its internal
1491 read pointer if it is invoked with @var{buffer} and @var{nread} being
1492 @code{NULL} and @var{count} being @code{0}.
1494 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1495 data object was successfully created, @code{GPG_ERR_INV_VALUE} if
1496 @var{dh} or @var{readfunc} is not a valid pointer, and
1497 @code{GPG_ERR_ENOMEM} if not enough memory is available.
1501 @node Destroying Data Buffers
1502 @section Destroying Data Buffers
1503 @cindex data buffer, destruction
1505 @deftypefun void gpgme_data_release (@w{gpgme_data_t @var{dh}})
1506 The function @code{gpgme_data_release} destroys the data object with
1507 the handle @var{dh}. It releases all associated resources that were
1508 not provided by the user in the first place.
1511 @deftypefun {char *} gpgme_data_release_and_get_mem (@w{gpgme_data_t @var{dh}}, @w{size_t *@var{length}})
1512 The function @code{gpgme_data_release_and_get_mem} is like
1513 @code{gpgme_data_release}, except that it returns the data buffer and
1514 its length that was provided by the object.
1516 The user has to release the buffer with @code{free}. In case the user
1517 provided the data buffer in non-copy mode, a copy will be made for
1520 In case an error returns, or there is no suitable data buffer that can
1521 be returned to the user, the function will return @code{NULL}.
1525 @node Manipulating Data Buffers
1526 @section Manipulating Data Buffers
1527 @cindex data buffere, manipulation
1529 @deftypefun ssize_t gpgme_data_read (@w{gpgme_data_t @var{dh}}, @w{void *@var{buffer}}, @w{size_t @var{length}})
1530 The function @code{gpgme_data_read} reads up to @var{length} bytes
1531 from the data object with the handle @var{dh} into the space starting
1534 If no error occurs, the actual amount read is returned. If the end of
1535 the data object is reached, the function returns 0.
1537 In all other cases, the function returns -1 and sets @var{errno}.
1540 @deftypefun ssize_t gpgme_data_write (@w{gpgme_data_t @var{dh}}, @w{const void *@var{buffer}}, @w{size_t @var{size}})
1541 The function @code{gpgme_data_write} writes up to @var{size} bytes
1542 starting from @var{buffer} into the data object with the handle
1543 @var{dh} at the current write position.
1545 The function returns the number of bytes actually written, or -1 if an
1546 error occurs. If an error occurs, @var{errno} is set.
1549 @deftypefun off_t gpgme_data_seek (@w{gpgme_data_t @var{dh}}, @w{off_t *@var{offset}}, @w{int @var{whence}})
1550 The function @code{gpgme_data_seek} changes the current read/write
1553 The @var{whence} argument specifies how the @var{offset} should be
1554 interpreted. It must be one of the following symbolic constants:
1558 Specifies that @var{whence} is a count of characters from the
1559 beginning of the data object.
1562 Specifies that @var{whence} is a count of characters from the current
1563 file position. This count may be positive or negative.
1566 Specifies that @var{whence} is a count of characters from the end of
1567 the data object. A negative count specifies a position within the
1568 current extent of the data object; a positive count specifies a
1569 position past the current end. If you set the position past the
1570 current end, and actually write data, you will extend the data object
1571 with zeros up to that position.
1574 If successful, the function returns the resulting file position,
1575 measured in bytes from the beginning of the data object. You can use
1576 this feature together with @code{SEEK_CUR} to read the current
1577 read/write position.
1579 If the function fails, -1 is returned and @var{errno} is set.
1582 The following function is deprecated and should not be used. It will
1583 be removed in a future version of @acronym{GPGME}.
1585 @deftypefun gpgme_error_t gpgme_data_rewind (@w{gpgme_data_t @var{dh}})
1586 The function @code{gpgme_data_rewind} is equivalent to:
1589 return (gpgme_data_seek (dh, 0, SEEK_SET) == -1)
1590 ? gpgme_error_from_errno (errno) : 0;
1595 @c gpgme_data_encoding_t
1597 @deftp {Data type} {enum gpgme_data_encoding_t}
1598 @tindex gpgme_data_encoding_t
1599 The @code{gpgme_data_encoding_t} type specifies the encoding of a
1600 @code{gpgme_data_t} object. This encoding is useful to give the backend
1601 a hint on the type of data. The following data types are available:
1604 @item GPGME_DATA_ENCODING_NONE
1605 This specifies that the encoding is not known. This is the default
1606 for a new data object. The backend will try its best to detect the
1607 encoding automatically.
1609 @item GPGME_DATA_ENCODING_BINARY
1610 This specifies that the data is encoding in binary form; i.e. there is
1611 no special encoding.
1613 @item GPGME_DATA_ENCODING_BASE64
1614 This specifies that the data is encoded using the Base-64 encoding
1615 scheme as used by @acronym{MIME} and other protocols.
1617 @item GPGME_DATA_ENCODING_ARMOR
1618 This specifies that the data is encoded in an armored form as used by
1623 @deftypefun gpgme_data_encoding_t gpgme_data_get_encoding (@w{gpgme_data_t @var{dh}})
1624 The function @code{gpgme_data_get_encoding} returns the encoding of
1625 the data object with the handle @var{dh}. If @var{dh} is not a valid
1626 pointer (e.g. @code{NULL}) @code{GPGME_DATA_ENCODING_NONE} is
1630 @deftypefun gpgme_error_t gpgme_data_set_encoding (@w{gpgme_data_t @var{dh}, gpgme_data_encoding_t @var{enc}})
1631 The function @code{gpgme_data_set_encoding} changes the encoding of
1632 the data object with the handle @var{dh} to @var{enc}.
1643 All cryptographic operations in @acronym{GPGME} are performed within a
1644 context, which contains the internal state of the operation as well as
1645 configuration parameters. By using several contexts you can run
1646 several cryptographic operations in parallel, with different
1649 @deftp {Data type} {gpgme_ctx_t}
1650 The @code{gpgme_ctx_t} type is a handle for a @acronym{GPGME} context,
1651 which is used to hold the configuration, status and result of
1652 cryptographic operations.
1656 * Creating Contexts:: Creating new @acronym{GPGME} contexts.
1657 * Destroying Contexts:: Releasing @acronym{GPGME} contexts.
1658 * Context Attributes:: Setting properties of a context.
1659 * Key Management:: Managing keys with @acronym{GPGME}.
1660 * Trust Item Management:: Managing trust items with @acronym{GPGME}.
1661 * Crypto Operations:: Using a context for cryptography.
1662 * Run Control:: Controlling how operations are run.
1666 @node Creating Contexts
1667 @section Creating Contexts
1668 @cindex context, creation
1670 @deftypefun gpgme_error_t gpgme_new (@w{gpgme_ctx_t *@var{ctx}})
1671 The function @code{gpgme_data_new} creates a new @code{gpgme_ctx_t}
1672 object and returns a handle for it in @var{ctx}.
1674 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1675 context was successfully created, @code{GPG_ERR_INV_VALUE} if
1676 @var{ctx} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if not
1677 enough memory is available.
1681 @node Destroying Contexts
1682 @section Destroying Contexts
1683 @cindex context, destruction
1685 @deftypefun void gpgme_release (@w{gpgme_ctx_t @var{ctx}})
1686 The function @code{gpgme_release} destroys the context with the handle
1687 @var{ctx} and releases all associated resources.
1691 @node Context Attributes
1692 @section Context Attributes
1693 @cindex context, attributes
1696 * Protocol Selection:: Selecting the protocol used by a context.
1697 * ASCII Armor:: Requesting @acronym{ASCII} armored output.
1698 * Text Mode:: Choosing canonical text mode.
1699 * Included Certificates:: Including a number of certificates.
1700 * Key Listing Mode:: Selecting key listing mode.
1701 * Passphrase Callback:: Getting the passphrase from the user.
1702 * Progress Meter Callback:: Being informed about the progress.
1706 @node Protocol Selection
1707 @subsection Protocol Selection
1708 @cindex context, selecting protocol
1709 @cindex protocol, selecting
1711 @deftypefun gpgme_error_t gpgme_set_protocol (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_protocol_t @var{proto}})
1712 The function @code{gpgme_set_protocol} sets the protocol used within
1713 the context @var{ctx} to @var{proto}. All crypto operations will be
1714 performed by the crypto engine configured for that protocol.
1715 @xref{Protocols and Engines}.
1717 Setting the protocol with @code{gpgme_set_protocol} does not check if
1718 the crypto engine for that protocol is available and installed
1719 correctly. @xref{Engine Version Check}.
1721 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1722 protocol could be set successfully, and @code{GPG_ERR_INV_VALUE} if
1723 @var{protocol} is not a valid protocol.
1726 @deftypefun gpgme_protocol_t gpgme_get_protocol (@w{gpgme_ctx_t @var{ctx}})
1727 The function @code{gpgme_get_protocol} retrieves the protocol currently
1728 use with the context @var{ctx}.
1731 @c FIXME: Unfortunately, using @acronym here breaks texi2dvi.
1733 @subsection @acronym{ASCII} Armor
1734 @cindex context, armor mode
1735 @cindex @acronym{ASCII} armor
1738 @deftypefun void gpgme_set_armor (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{yes}})
1739 The function @code{gpgme_set_armor} specifies if the output should be
1740 @acronym{ASCII} armored. By default, output is not @acronym{ASCII}
1743 @acronym{ASCII} armored output is disabled if @var{yes} is zero, and
1747 @deftypefun int gpgme_get_armor (@w{gpgme_ctx_t @var{ctx}})
1748 The function @code{gpgme_get_armor} returns 1 if the output is
1749 @acronym{ASCII} armored, and @code{0} if it is not, or if @var{ctx} is
1750 not a valid pointer.
1755 @subsection Text Mode
1756 @cindex context, text mode
1758 @cindex canonical text mode
1760 @deftypefun void gpgme_set_textmode (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{yes}})
1761 The function @code{gpgme_set_textmode} specifies if canonical text mode
1762 should be used. By default, text mode is not used.
1764 Text mode is for example used for the RFC2015 signatures; note that
1765 the updated RFC 3156 mandates that the mail user agent does some
1766 preparations so that text mode is not needed anymore.
1768 This option is only relevant to the OpenPGP crypto engine, and ignored
1769 by all other engines.
1771 Canonical text mode is disabled if @var{yes} is zero, and enabled
1775 @deftypefun int gpgme_get_textmode (@w{gpgme_ctx_t @var{ctx}})
1776 The function @code{gpgme_get_textmode} returns 1 if canonical text
1777 mode is enabled, and @code{0} if it is not, or if @var{ctx} is not a
1782 @node Included Certificates
1783 @subsection Included Certificates
1784 @cindex certificates, included
1786 @deftypefun void gpgme_set_include_certs (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{nr_of_certs}})
1787 The function @code{gpgme_set_include_certs} specifies how many
1788 certificates should be included in an S/MIME signed message. By
1789 default, only the sender's certificate is included. The possible
1790 values of @var{nr_of_certs} are:
1794 Include all certificates except the root certificate.
1796 Include all certificates.
1798 Include no certificates.
1800 Include the sender's certificate only.
1802 Include the first n certificates of the certificates path, starting
1803 from the sender's certificate. The number @code{n} must be positive.
1806 Values of @var{nr_of_certs} smaller than -2 are undefined.
1808 This option is only relevant to the CMS crypto engine, and ignored by
1812 @deftypefun int gpgme_get_include_certs (@w{gpgme_ctx_t @var{ctx}})
1813 The function @code{gpgme_get_include_certs} returns the number of
1814 certificates to include into an S/MIME signed message.
1818 @node Key Listing Mode
1819 @subsection Key Listing Mode
1820 @cindex key listing mode
1821 @cindex key listing, mode of
1823 @deftypefun void gpgme_set_keylist_mode (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_keylist_mode_t @var{mode}})
1824 The function @code{gpgme_set_keylist_mode} changes the default
1825 behaviour of the key listing functions. The value in @var{mode} is a
1826 bitwise-or combination of one or multiple of the following bit values:
1829 @item GPGME_KEYLIST_MODE_LOCAL
1830 The @code{GPGME_KEYLIST_MODE_LOCAL} symbol specifies that the local
1831 keyring should be searched for keys in the keylisting operation. This
1834 @item GPGME_KEYLIST_MODE_EXTERN
1835 The @code{GPGME_KEYLIST_MODE_EXTERN} symbol specifies that an external
1836 source should be searched for keys in the keylisting
1837 operation. The type of external source is dependant on the crypto
1838 engine used. For example, it can be a remote keyserver or LDAP
1841 @item GPGME_KEYLIST_MODE_SIGS
1842 The @code{GPGME_KEYLIST_MODE_SIGS} symbol specifies that the key
1843 signatures should be included in the listed keys.
1846 At least one of @code{GPGME_KEYLIST_MODE_LOCAL} and
1847 @code{GPGME_KEYLIST_MODE_EXTERN} must be specified. For future binary
1848 compatibility, you should get the current mode with
1849 @code{gpgme_get_keylist_mode} and modify it by setting or clearing the
1850 appropriate bits, and then using that calulcated value in the
1851 @code{gpgme_set_keylisting_mode} operation. This will leave all other
1852 bits in the mode value intact (in particular those that are not used
1853 in the current version of the library).
1855 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1856 mode could be set correctly, and @code{GPG_ERR_INV_VALUE} if @var{ctx}
1857 is not a valid pointer or @var{mode} is not a valid mode.
1861 @deftypefun gpgme_keylist_mode_t gpgme_get_keylist_mode (@w{gpgme_ctx_t @var{ctx}})
1862 The function @code{gpgme_get_keylist_mode} returns the current key
1863 listing mode of the context @var{ctx}. This value can then be
1864 modified and used in a subsequent @code{gpgme_set_keylist_mode}
1865 operation to only affect the desired bits (and leave all others
1868 The function returns 0 if @var{ctx} is not a valid pointer, and the
1869 current mode otherwise. Note that 0 is not a valid mode value.
1873 @node Passphrase Callback
1874 @subsection Passphrase Callback
1875 @cindex callback, passphrase
1876 @cindex passphrase callback
1878 @deftp {Data type} {gpgme_error_t (*gpgme_passphrase_cb_t)(void *@var{hook}, const char *@var{uid_hint}, const char *@var{passphrase_info}, @w{int @var{prev_was_bad}}, @w{int @var{fd}})}
1879 @tindex gpgme_passphrase_cb_t
1880 The @code{gpgme_passphrase_cb_t} type is the type of functions usable as
1881 passphrase callback function.
1883 The argument @var{uid_hint} might contain a string that gives an
1884 indication for which user ID the passphrase is required. If this is
1885 not available, or not applicable (in the case of symmetric encryption,
1886 for example), @var{uid_hint} will be @code{NULL}.
1888 The argument @var{passphrase_info}, if not @code{NULL}, will give
1889 further information about the context in which the passphrase is
1890 required. This information is engine and operation specific.
1892 If this is the repeated attempt to get the passphrase, because
1893 previous attempts failed, then @var{prev_was_bad} is 1, otherwise it
1896 The user must write the passphrase, followed by a newline character,
1897 to the file descriptor @var{fd}. If the user does not return 0
1898 indicating success, the user must at least write a newline character
1899 before returning from the callback.
1901 If an error occurs, return the corresponding @code{gpgme_error_t}
1902 value. You can use the error code @code{GPG_ERR_CANCELED} to abort
1903 the operation. Otherwise, return @code{0}.
1906 @deftypefun void gpgme_set_passphrase_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_passphrase_cb_t @var{passfunc}}, @w{void *@var{hook_value}})
1907 The function @code{gpgme_set_passphrase_cb} sets the function that is
1908 used when a passphrase needs to be provided by the user to
1909 @var{passfunc}. The function @var{passfunc} needs to implemented by
1910 the user, and whenever it is called, it is called with its first
1911 argument being @var{hook_value}. By default, no passphrase callback
1914 Not all crypto engines require this callback to retrieve the
1915 passphrase. It is better if the engine retrieves the passphrase from
1916 a trusted agent (a daemon process), rather than having each user to
1917 implement their own passphrase query.
1919 The user can disable the use of a passphrase callback function by
1920 calling @code{gpgme_set_passphrase_cb} with @var{passfunc} being
1924 @deftypefun void gpgme_get_passphrase_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_passphrase_cb_t *@var{passfunc}}, @w{void **@var{hook_value}})
1925 The function @code{gpgme_get_passphrase_cb} returns the function that
1926 is used when a passphrase needs to be provided by the user in
1927 @var{*passfunc}, and the first argument for this function in
1928 @var{*hook_value}. If no passphrase callback is set, or @var{ctx} is
1929 not a valid pointer, @code{NULL} is returned in both variables.
1931 @var{passfunc} or @var{hook_value} can be @code{NULL}. In this case,
1932 the corresponding value will not be returned.
1936 @node Progress Meter Callback
1937 @subsection Progress Meter Callback
1938 @cindex callback, progress meter
1939 @cindex progress meter callback
1941 @deftp {Data type} {void (*gpgme_progress_cb_t)(void *@var{hook}, const char *@var{what}, int @var{type}, int @var{current}, int @var{total})}
1942 @tindex gpgme_progress_cb_t
1943 The @code{gpgme_progress_cb_t} type is the type of functions usable as
1944 progress callback function.
1946 The arguments are specific to the crypto engine. More information
1947 about the progress information returned from the GnuPG engine can be
1948 found in the GnuPG source code in the file @file{doc/DETAILS} in the
1952 @deftypefun void gpgme_set_progress_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_progress_cb_t @var{progfunc}}, @w{void *@var{hook_value}})
1953 The function @code{gpgme_set_progress_cb} sets the function that is
1954 used when progress information about a cryptographic operation is
1955 available. The function @var{progfunc} needs to implemented by the
1956 user, and whenever it is called, it is called with its first argument
1957 being @var{hook_value}. By default, no progress callback function
1960 Setting a callback function allows an interactive program to display
1961 progress information about a long operation to the user.
1963 The user can disable the use of a progress callback function by
1964 calling @code{gpgme_set_progress_cb} with @var{progfunc} being
1968 @deftypefun void gpgme_get_progress_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_progress_cb_t *@var{progfunc}}, @w{void **@var{hook_value}})
1969 The function @code{gpgme_get_progress_cb} returns the function that is
1970 used to inform the user about the progress made in @var{*progfunc},
1971 and the first argument for this function in @var{*hook_value}. If no
1972 progress callback is set, or @var{ctx} is not a valid pointer,
1973 @code{NULL} is returned in both variables.
1975 @var{progfunc} or @var{hook_value} can be @code{NULL}. In this case,
1976 the corresponding value will not be returned.
1980 @node Key Management
1981 @section Key Management
1982 @cindex key management
1984 Some of the cryptographic operations require that recipients or
1985 signers are specified. This is always done by specifying the
1986 respective keys that should be used for the operation. The following
1987 section describes how such keys can be selected and manipulated.
1989 @deftp {Data type} gpgme_sub_key_t
1990 The @code{gpgme_sub_key_t} type is a pointer to a subkey structure.
1991 Sub keys are one component of a @code{gpgme_key_t} object. In fact,
1992 subkeys are those parts that contains the real information about the
1993 individual cryptographic keys that belong to the same key object. One
1994 @code{gpgme_key_t} can contain several subkeys. The first subkey in
1995 the linked list is also called the primary key.
1997 The subkey structure has the following members:
2000 @item gpgme_sub_key_t next
2001 This is a pointer to the next subkey structure in the linked list, or
2002 @code{NULL} if this is the last element.
2004 @item unsigned int revoked : 1
2005 This is true if the subkey is revoked.
2007 @item unsigned int expired : 1
2008 This is true if the subkey is expired.
2010 @item unsigned int disabled : 1
2011 This is true if the subkey is disabled.
2013 @item unsigned int invalid : 1
2014 This is true if the subkey is invalid.
2016 @item unsigned int can_encrypt : 1
2017 This is true if the subkey can be used for encryption.
2019 @item unsigned int can_sign : 1
2020 This is true if the subkey can be used to create data signatures.
2022 @item unsigned int can_certify : 1
2023 This is true if the subkey can be used to create key certificates.
2025 @item unsigned int secret : 1
2026 This is true if the subkey is a secret key.
2028 @item gpgme_pubkey_algo_t pubkey_algo
2029 This is the public key algorithm supported by this subkey.
2031 @item unsigned int length
2032 This is the length of the subkey (in bits).
2035 This is the key ID of the subkey in hexadecimal digits.
2038 This is the fingerprint of the subkey in hexadecimal digits, if
2039 available. This is usually only available for the primary key.
2041 @item long int timestamp
2042 This is the creation timestamp of the subkey. This is -1 if the
2043 timestamp is invalid, and 0 if it is not available.
2045 @item long int expires
2046 This is the expiration timestamp of the subkey, or 0 if the subkey
2051 @deftp {Data type} gpgme_key_sig_t
2052 The @code{gpgme_key_sig_t} type is a pointer to a key signature structure.
2053 Key signatures are one component of a @code{gpgme_key_t} object, and
2054 validate user IDs on the key.
2056 The signatures on a key are only available if the key was retrieved
2057 via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode
2058 enabled, because it is expensive to retrieve all signatures of a key.
2060 The key signature structure has the following members:
2063 @item gpgme_key_sig_t next
2064 This is a pointer to the next key signature structure in the linked
2065 list, or @code{NULL} if this is the last element.
2067 @item unsigned int revoked : 1
2068 This is true if the key signature is a revocation signature.
2070 @item unsigned int expired : 1
2071 This is true if the key signature is expired.
2073 @item unsigned int invalid : 1
2074 This is true if the key signature is invalid.
2076 @item unsigned int disabled : 1
2077 This is true if the key signature is exportable.
2079 @item gpgme_pubkey_algo_t pubkey_algo
2080 This is the public key algorithm used to create the signature.
2083 This is the key ID of the key (in hexadecimal digits) used to create
2086 @item long int timestamp
2087 This is the creation timestamp of the key signature. This is -1 if
2088 the timestamp is invalid, and 0 if it is not available.
2090 @item long int expires
2091 This is the expiration timestamp of the key signature, or 0 if the key
2092 signature does not expire.
2094 @item gpgme_error_t status
2095 This is the status of the signature and has the same meaning as the
2096 member of the same name in a @code{gpgme_signature_t} object.
2098 @item unsigned int class
2099 This specifies the signature class of the key signature. The meaning
2100 is specific to the crypto engine.
2103 This is the main user ID of the key used to create the signature.
2106 This is the name component of @code{uid}, if available.
2109 This is the comment component of @code{uid}, if available.
2112 This is the email component of @code{uid}, if available.
2116 @deftp {Data type} gpgme_user_id_t
2117 A user ID is a component of a @code{gpgme_key_t} object. One key can
2118 have many user IDs. The first one in the list is the main (or
2121 The user ID structure has the following members.
2124 @item gpgme_user_id_t next
2125 This is a pointer to the next user ID structure in the linked list, or
2126 @code{NULL} if this is the last element.
2128 @item unsigned int revoked : 1
2129 This is true if the user ID is revoked.
2131 @item unsigned int invalid : 1
2132 This is true if the user ID is invalid.
2134 @item gpgme_validity_t validity
2135 This specifies the validity of the user ID.
2138 This is the user ID string.
2141 This is the name component of @code{uid}, if available.
2144 This is the comment component of @code{uid}, if available.
2147 This is the email component of @code{uid}, if available.
2149 @item gpgme_key_sig_t signatures
2150 This is a linked list with the signatures on this user ID.
2154 @deftp {Data type} gpgme_key_t
2155 The @code{gpgme_key_t} type is a pointer to a key object. It has the
2159 @item unsigned int revoked : 1
2160 This is true if the key is revoked.
2162 @item unsigned int expired : 1
2163 This is true if the key is expired.
2165 @item unsigned int disabled : 1
2166 This is true if the key is disabled.
2168 @item unsigned int invalid : 1
2169 This is true if the key is invalid.
2171 @item unsigned int can_encrypt : 1
2172 This is true if the key (ie one of its subkeys) can be used for
2175 @item unsigned int can_sign : 1
2176 This is true if the key (ie one of its subkeys) can be used to create
2179 @item unsigned int can_certify : 1
2180 This is true if the key (ie one of its subkeys) can be used to create
2183 @item unsigned int secret : 1
2184 This is true if the key is a secret key.
2186 @item gpgme_protocol_t protocol
2187 This is the protocol supported by this key.
2189 @item char *issuer_serial
2190 If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
2193 @item char *issuer_name
2194 If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
2197 @item char *chain_id
2198 If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
2199 chain ID, which can be used to built the certificate chain.
2201 @item gpgme_validity_t owner_trust
2202 If @code{protocol} is @code{GPGME_PROTOCOL_OpenPGP}, then this is the
2205 @item gpgme_sub_key_t subkeys
2206 This is a linked list with the subkeys of the key. The first subkey
2207 in the list is the primary key and usually available.
2209 @item gpgme_user_id_t uids
2210 This is a linked list with the user IDs of the key. The first user ID
2211 in the list is the main (or primary) user ID.
2216 * Listing Keys:: Browsing the list of available keys.
2217 * Information About Keys:: Requesting detailed information about keys.
2218 * Key Signatures:: Listing the signatures on a key.
2219 * Manipulating Keys:: Operations on keys.
2220 * Generating Keys:: Creating new key pairs.
2221 * Exporting Keys:: Retrieving key data from the key ring.
2222 * Importing Keys:: Adding keys to the key ring.
2223 * Deleting Keys:: Removing keys from the key ring.
2228 @subsection Listing Keys
2229 @cindex listing keys
2231 @cindex key listing, start
2232 @cindex key ring, list
2233 @cindex key ring, search
2235 @deftypefun gpgme_error_t gpgme_op_keylist_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}})
2236 The function @code{gpgme_op_keylist_start} initiates a key listing
2237 operation inside the context @var{ctx}. It sets everything up so that
2238 subsequent invocations of @code{gpgme_op_keylist_next} return the keys
2241 If @var{pattern} is @code{NULL}, all available keys are returned.
2242 Otherwise, @var{pattern} contains an engine specific expression that
2243 is used to limit the list to all keys matching the pattern.
2245 If @var{secret_only} is not @code{0}, the list is restricted to secret
2248 The context will be busy until either all keys are received (and
2249 @code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}), or
2250 @code{gpgme_op_keylist_end} is called to finish the operation.
2252 The function returns the error code @code{GPG_ERR_INV_VALUE} if
2253 @var{ctx} is not a valid pointer, and passes through any errors that
2254 are reported by the crypto engine support routines.
2257 @deftypefun gpgme_error_t gpgme_op_keylist_ext_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}[]}, @w{int @var{secret_only}}, @w{int @var{reserved}})
2258 The function @code{gpgme_op_keylist_ext_start} initiates an extended
2259 key listing operation inside the context @var{ctx}. It sets
2260 everything up so that subsequent invocations of
2261 @code{gpgme_op_keylist_next} return the keys in the list.
2263 If @var{pattern} or @var{*pattern} is @code{NULL}, all available keys
2264 are returned. Otherwise, @var{pattern} is a @code{NULL} terminated
2265 array of strings that are used to limit the list to all keys matching
2266 at least one of the patterns verbatim.
2268 If @var{secret_only} is not @code{0}, the list is restricted to secret
2271 The value of @var{reserved} must be @code{0}.
2273 The context will be busy until either all keys are received (and
2274 @code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}), or
2275 @code{gpgme_op_keylist_end} is called to finish the operation.
2277 The function returns the error code @code{GPG_ERR_INV_VALUE} if
2278 @var{ctx} is not a valid pointer, and passes through any errors that
2279 are reported by the crypto engine support routines.
2282 @deftypefun gpgme_error_t gpgme_op_keylist_next (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t *@var{r_key}})
2283 The function @code{gpgme_op_keylist_next} returns the next key in the
2284 list created by a previous @code{gpgme_op_keylist_start} operation in
2285 the context @var{ctx}. The key will have one reference for the user.
2286 @xref{Manipulating Keys}.
2288 This is the only way to get at @code{gpgme_key_t} objects in
2291 If the last key in the list has already been returned,
2292 @code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}.
2294 The function returns the error code @code{GPG_ERR_INV_VALUE} if
2295 @var{ctx} or @var{r_key} is not a valid pointer, and
2296 @code{GPG_ERR_ENOMEM} if there is not enough memory for the operation.
2299 @deftypefun gpgme_error_t gpgme_op_keylist_end (@w{gpgme_ctx_t @var{ctx}})
2300 The function @code{gpgme_op_keylist_next} ends a pending key list
2301 operation in the context @var{ctx}.
2303 After the operation completed successfully, the result of the key
2304 listing operation can be retrieved with
2305 @code{gpgme_op_keylist_result}.
2307 The function returns the error code @code{GPG_ERR_INV_VALUE} if
2308 @var{ctx} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if at some
2309 time during the operation there was not enough memory available.
2312 The following example illustrates how all keys containing a certain
2313 string (@code{g10code}) can be listed with their key ID and the name
2314 and e-mail address of the main user ID:
2318 gpgme_error_t err = gpgme_new (&ctx);
2322 err = gpgme_op_keylist_start (ctx, "g10code", 0);
2325 err = gpgme_op_keylist_next (ctx, &key);
2328 printf ("%s: %s <%s>\n", key->keyid, key->name, key->email);
2329 gpgme_key_release (key);
2331 gpgme_release (ctx);
2333 if (gpg_err_code (err) != GPG_ERR_EOF)
2335 fprintf (stderr, "%s: can not list keys: %s\n",
2336 argv[0], gpgme_strerror (err));
2341 @deftp {Data type} {gpgme_keylist_result_t}
2342 This is a pointer to a structure used to store the result of a
2343 @code{gpgme_op_keylist_*} operation. After successfully ending a key
2344 listing operation, you can retrieve the pointer to the result with
2345 @code{gpgme_op_keylist_result}. The structure contains the following
2349 @item unsigned int truncated : 1
2350 This is true if the crypto backend had to truncate the result, and
2351 less than the desired keys could be listed.
2355 @deftypefun gpgme_keylist_result_t gpgme_op_keylist_result (@w{gpgme_ctx_t @var{ctx}})
2356 The function @code{gpgme_op_keylist_result} returns a
2357 @code{gpgme_keylist_result_t} pointer to a structure holding the
2358 result of a @code{gpgme_op_keylist_*} operation. The pointer is only
2359 valid if the last operation on the context was a key listing
2360 operation, and if this operation finished successfully. The returned
2361 pointer is only valid until the next operation is started on the
2365 In a simple program, for which a blocking operation is acceptable, the
2366 following function can be used to retrieve a single key.
2368 @deftypefun gpgme_error_t gpgme_get_key (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{fpr}}, @w{gpgme_key_t *@var{r_key}}, @w{int @var{secret}})
2369 The function @code{gpgme_get_key} gets the key with the fingerprint
2370 (or key ID) @var{fpr} from the crypto backend and return it in
2371 @var{r_key}. If @var{secret} is true, get the secret key. The
2372 currently active keylist mode is used to retrieve the key.
2374 If the key is not found in the keyring, @code{gpgme_get_key} returns
2375 the error code @code{GPG_ERR_NO_ERROR} and *@var{r_key} will be set to
2378 The function returns the error code @code{GPG_ERR_INV_VALUE} if
2379 @var{ctx} or @var{r_key} is not a valid pointer or @var{fpr} is not a
2380 fingerprint or key ID, and @code{GPG_ERR_ENOMEM} if at some time
2381 during the operation there was not enough memory available.
2385 @node Information About Keys
2386 @subsection Information About Keys
2387 @cindex key, information about
2388 @cindex key, attributes
2389 @cindex attributes, of a key
2391 Please see the beginning of this section for more information about
2392 @code{gpgme_key_t} objects.
2394 @deftp {Data type} gpgme_validity_t
2395 The @code{gpgme_validity_t} type is used to specify the validity of a user ID
2396 in a key. The following validities are defined:
2399 @item GPGME_VALIDITY_UNKNOWN
2400 The user ID is of unknown validity. The string representation of this
2403 @item GPGME_VALIDITY_UNDEFINED
2404 The validity of the user ID is undefined. The string representation of this
2407 @item GPGME_VALIDITY_NEVER
2408 The user ID is never valid. The string representation of this
2411 @item GPGME_VALIDITY_MARGINAL
2412 The user ID is marginally valid. The string representation of this
2415 @item GPGME_VALIDITY_FULL
2416 The user ID is fully valid. The string representation of this
2419 @item GPGME_VALIDITY_ULTIMATE
2420 The user ID is ultimately valid. The string representation of this
2426 The following interfaces are deprecated and only provided for backward
2427 compatibility. Don't use them. They will be removed in a future
2428 version of @acronym{GPGME}.
2430 @deftp {Data type} gpgme_attr_t
2431 The @code{gpgme_attr_t} type is used to specify a key or trust item
2432 attribute. The following attributes are defined:
2435 @item GPGME_ATTR_KEYID
2436 This is the key ID of a sub key. It is representable as a string.
2438 For trust items, the trust item refers to the key with this ID.
2440 @item GPGME_ATTR_FPR
2441 This is the fingerprint of a sub key. It is representable as a
2444 @item GPGME_ATTR_ALGO
2445 This is the crypto algorithm for which the sub key can be used. It
2446 is representable as a string and as a number. The numbers correspond
2447 to the @code{enum gcry_pk_algos} values in the gcrypt library.
2449 @item GPGME_ATTR_LEN
2450 This is the key length of a sub key. It is representable as a
2453 @item GPGME_ATTR_CREATED
2454 This is the timestamp at creation time of a sub key. It is
2455 representable as a number.
2457 @item GPGME_ATTR_EXPIRE
2458 This is the expiration time of a sub key. It is representable as a
2461 @item GPGME_ATTR_OTRUST
2462 XXX FIXME (also for trust items)
2464 @item GPGME_ATTR_USERID
2465 This is a user ID. There can be more than one user IDs in a
2466 @var{gpgme_key_t} object. The first one (with index 0) is the primary
2467 user ID. The user ID is representable as a number.
2469 For trust items, this is the user ID associated with this trust item.
2471 @item GPGME_ATTR_NAME
2472 This is the name belonging to a user ID. It is representable as a string.
2474 @item GPGME_ATTR_EMAIL
2475 This is the email address belonging to a user ID. It is representable
2478 @item GPGME_ATTR_COMMENT
2479 This is the comment belonging to a user ID. It is representable as a
2482 @item GPGME_ATTR_VALIDITY
2483 This is the validity belonging to a user ID. It is representable as a
2484 string and as a number. See below for a list of available validities.
2486 For trust items, this is the validity that is associated with this
2489 @item GPGME_ATTR_UID_REVOKED
2490 This specifies if a user ID is revoked. It is representable as a
2491 number, and is @code{1} if the user ID is revoked, and @code{0}
2494 @item GPGME_ATTR_UID_INVALID
2495 This specifies if a user ID is invalid. It is representable as a
2496 number, and is @code{1} if the user ID is invalid, and @code{0}
2499 @item GPGME_ATTR_LEVEL
2500 This is the trust level of a trust item.
2502 @item GPGME_ATTR_TYPE
2503 This returns information about the type of key. For the string function
2504 this will eother be "PGP" or "X.509". The integer function returns 0
2505 for PGP and 1 for X.509. It is also used for the type of a trust item.
2507 @item GPGME_ATTR_IS_SECRET
2508 This specifies if the key is a secret key. It is representable as a
2509 number, and is @code{1} if the key is revoked, and @code{0} otherwise.
2511 @item GPGME_ATTR_KEY_REVOKED
2512 This specifies if a sub key is revoked. It is representable as a
2513 number, and is @code{1} if the key is revoked, and @code{0} otherwise.
2515 @item GPGME_ATTR_KEY_INVALID
2516 This specifies if a sub key is invalid. It is representable as a
2517 number, and is @code{1} if the key is invalid, and @code{0} otherwise.
2519 @item GPGME_ATTR_KEY_EXPIRED
2520 This specifies if a sub key is expired. It is representable as a
2521 number, and is @code{1} if the key is expired, and @code{0} otherwise.
2523 @item GPGME_ATTR_KEY_DISABLED
2524 This specifies if a sub key is disabled. It is representable as a
2525 number, and is @code{1} if the key is disabled, and @code{0} otherwise.
2527 @item GPGME_ATTR_KEY_CAPS
2528 This is a description of the capabilities of a sub key. It is
2529 representable as a string. The string contains the letter ``e'' if
2530 the key can be used for encryption, ``s'' if the key can be used for
2531 signatures, and ``c'' if the key can be used for certifications.
2533 @item GPGME_ATTR_CAN_ENCRYPT
2534 This specifies if a sub key can be used for encryption. It is
2535 representable as a number, and is @code{1} if the sub key can be used
2536 for encryption, and @code{0} otherwise.
2538 @item GPGME_ATTR_CAN_SIGN
2539 This specifies if a sub key can be used to create data signatures. It
2540 is representable as a number, and is @code{1} if the sub key can be
2541 used for signatures, and @code{0} otherwise.
2543 @item GPGME_ATTR_CAN_CERTIFY
2544 This specifies if a sub key can be used to create key certificates.
2545 It is representable as a number, and is @code{1} if the sub key can be
2546 used for certifications, and @code{0} otherwise.
2548 @item GPGME_ATTR_SERIAL
2549 The X.509 issuer serial attribute of the key. It is representable as
2552 @item GPGME_ATTR_ISSUE
2553 The X.509 issuer name attribute of the key. It is representable as a
2556 @item GPGME_ATTR_CHAINID
2557 The X.509 chain ID can be used to build the certification chain. It
2558 is representable as a string.
2562 @deftypefun {const char *} gpgme_key_get_string_attr (@w{gpgme_key_t @var{key}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
2563 The function @code{gpgme_key_get_string_attr} returns the value of the
2564 string-representable attribute @var{what} of key @var{key}. If the
2565 attribute is an attribute of a sub key or an user ID, @var{idx}
2566 specifies the sub key or user ID of which the attribute value is
2567 returned. The argument @var{reserved} is reserved for later use and
2568 should be @code{NULL}.
2570 The string returned is only valid as long as the key is valid.
2572 The function returns @code{0} if an attribute can't be returned as a
2573 string, @var{key} is not a valid pointer, @var{idx} out of range,
2574 or @var{reserved} not @code{NULL}.
2577 @deftypefun {unsigned long} gpgme_key_get_ulong_attr (@w{gpgme_key_t @var{key}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
2578 The function @code{gpgme_key_get_ulong_attr} returns the value of the
2579 number-representable attribute @var{what} of key @var{key}. If the
2580 attribute is an attribute of a sub key or an user ID, @var{idx}
2581 specifies the sub key or user ID of which the attribute value is
2582 returned. The argument @var{reserved} is reserved for later use and
2583 should be @code{NULL}.
2585 The function returns @code{0} if the attribute can't be returned as a
2586 number, @var{key} is not a valid pointer, @var{idx} out of range, or
2587 @var{reserved} not @code{NULL}.
2591 @node Key Signatures
2592 @subsection Key Signatures
2593 @cindex key, signatures
2594 @cindex signatures, on a key
2596 The following interfaces are deprecated and only provided for backward
2597 compatibility. Don't use them. They will be removed in a future
2598 version of @acronym{GPGME}.
2600 The signatures on a key are only available if the key was retrieved
2601 via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode
2602 enabled, because it is expensive to retrieve all signatures of a key.
2604 So, before using the below interfaces to retrieve the signatures on a
2605 key, you have to make sure that the key was listed with signatures
2606 enabled. One convenient, but blocking, way to do this is to use the
2607 function @code{gpgme_get_key}.
2609 @deftp {Data type} gpgme_attr_t
2610 The @code{gpgme_attr_t} type is used to specify a key signature
2611 attribute. The following attributes are defined:
2614 @item GPGME_ATTR_KEYID
2615 This is the key ID of the key which was used for the signature. It is
2616 representable as a string.
2618 @item GPGME_ATTR_ALGO
2619 This is the crypto algorithm used to create the signature. It is
2620 representable as a string and as a number. The numbers correspond to
2621 the @code{enum gcry_pk_algos} values in the gcrypt library.
2623 @item GPGME_ATTR_CREATED
2624 This is the timestamp at creation time of the signature. It is
2625 representable as a number.
2627 @item GPGME_ATTR_EXPIRE
2628 This is the expiration time of the signature. It is representable as
2631 @item GPGME_ATTR_USERID
2632 This is the user ID associated with the signing key. The user ID is
2633 representable as a number.
2635 @item GPGME_ATTR_NAME
2636 This is the name belonging to a user ID. It is representable as a string.
2638 @item GPGME_ATTR_EMAIL
2639 This is the email address belonging to a user ID. It is representable
2642 @item GPGME_ATTR_COMMENT
2643 This is the comment belonging to a user ID. It is representable as a
2646 @item GPGME_ATTR_KEY_REVOKED
2647 This specifies if a key signature is a revocation signature. It is
2648 representable as a number, and is @code{1} if the key is revoked, and
2651 @c @item GPGME_ATTR_KEY_EXPIRED
2652 @c This specifies if a key signature is expired. It is representable as
2653 @c a number, and is @code{1} if the key is revoked, and @code{0}
2656 @item GPGME_ATTR_SIG_CLASS
2657 This specifies the signature class of a key signature. It is
2658 representable as a number. The meaning is specific to the crypto
2661 @item GPGME_ATTR_SIG_CLASS
2662 This specifies the signature class of a key signature. It is
2663 representable as a number. The meaning is specific to the crypto
2666 @item GPGME_ATTR_SIG_STATUS
2667 This is the same value as returned by @code{gpgme_get_sig_status}.
2671 @deftypefun {const char *} gpgme_key_sig_get_string_attr (@w{gpgme_key_t @var{key}}, @w{int @var{uid_idx}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
2672 The function @code{gpgme_key_sig_get_string_attr} returns the value of
2673 the string-representable attribute @var{what} of the signature
2674 @var{idx} on the user ID @var{uid_idx} in the key @var{key}. The
2675 argument @var{reserved} is reserved for later use and should be
2678 The string returned is only valid as long as the key is valid.
2680 The function returns @code{0} if an attribute can't be returned as a
2681 string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx}
2682 out of range, or @var{reserved} not @code{NULL}.
2685 @deftypefun {unsigned long} gpgme_key_sig_get_ulong_attr (@w{gpgme_key_t @var{key}}, @w{int @var{uid_idx}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
2686 The function @code{gpgme_key_sig_get_ulong_attr} returns the value of
2687 the number-representable attribute @var{what} of the signature
2688 @var{idx} on the user ID @var{uid_idx} in the key @var{key}. The
2689 argument @var{reserved} is reserved for later use and should be
2692 The function returns @code{0} if an attribute can't be returned as a
2693 string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx}
2694 out of range, or @var{reserved} not @code{NULL}.
2698 @node Manipulating Keys
2699 @subsection Manipulating Keys
2700 @cindex key, manipulation
2702 @deftypefun void gpgme_key_ref (@w{gpgme_key_t @var{key}})
2703 The function @code{gpgme_key_ref} acquires an additional reference for
2707 @deftypefun void gpgme_key_unref (@w{gpgme_key_t @var{key}})
2708 The function @code{gpgme_key_unref} releases a reference for the key
2709 @var{key}. If this was the last reference, the key will be destroyed
2710 and all resources associated to it will be released.
2714 The following interface is deprecated and only provided for backward
2715 compatibility. Don't use it. It will be removed in a future version
2718 @deftypefun void gpgme_key_release (@w{gpgme_key_t @var{key}})
2719 The function @code{gpgme_key_release} is equivalent to
2720 @code{gpgme_key_unref}.
2724 @node Generating Keys
2725 @subsection Generating Keys
2726 @cindex key, creation
2727 @cindex key ring, add
2729 @deftypefun gpgme_error_t gpgme_op_genkey (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{parms}}, @w{gpgme_data_t @var{public}}, @w{gpgme_data_t @var{secret}})
2730 The function @code{gpgme_op_genkey} generates a new key pair in the
2731 context @var{ctx}. The meaning of @var{public} and @var{secret}
2732 depends on the crypto backend.
2734 GnuPG does not support @var{public} and @var{secret}, they should be
2735 @code{NULL}. GnuPG will generate a key pair and add it to the
2736 standard key ring. The fingerprint of the generated key is available
2737 with @code{gpgme_op_genkey_result}.
2739 GpgSM requires @var{public} to be a writable data object. GpgSM will
2740 generate a secret key (which will be stored by @command{gpg-agent},
2741 and return a certificate request in @var{public}, which then needs to
2742 be signed by the certification authority and imported before it can be
2743 used. GpgSM does not make the fingerprint available.
2745 The argument @var{parms} specifies parameters for the key in an XML
2746 string. The details about the format of @var{parms} are specific to
2747 the crypto engine used by @var{ctx}. Here is an example for GnuPG as
2751 <GnupgKeyParms format="internal">
2756 Name-Real: Joe Tester
2757 Name-Comment: with stupid passphrase
2758 Name-Email: joe@@foo.bar
2764 Here is an example for GpgSM as the crypto engine:
2767 <GnupgKeyParms format="internal">
2770 Name-DN: C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester
2771 Name-Email: joe@@foo.bar
2775 Strings should be given in UTF-8 encoding. The only format supported
2776 for now is ``internal''. The content of the @code{GnupgKeyParms}
2777 container is passed verbatim to the crypto backend. Control
2778 statements are not allowed.
2780 After the operation completed successfully, the result can be
2781 retrieved with @code{gpgme_op_genkey_result}.
2783 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
2784 operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
2785 @var{parms} is not a valid XML string, @code{GPG_ERR_NOT_SUPPORTED} if
2786 @var{public} or @var{secret} is not valid, and @code{GPG_ERR_GENERAL}
2787 if no key was created by the backend.
2790 @deftypefun gpgme_error_t gpgme_op_genkey_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{parms}}, @w{gpgme_data_t @var{public}}, @w{gpgme_data_t @var{secret}})
2791 The function @code{gpgme_op_genkey_start} initiates a
2792 @code{gpgme_op_genkey} operation. It can be completed by calling
2793 @code{gpgme_wait} on the context. @xref{Waiting For Completion}.
2795 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
2796 operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
2797 @var{parms} is not a valid XML string, and
2798 @code{GPG_ERR_NOT_SUPPORTED} if @var{public} or @var{secret} is not
2802 @deftp {Data type} {gpgme_genkey_result_t}
2803 This is a pointer to a structure used to store the result of a
2804 @code{gpgme_op_genkey} operation. After successfully generating a
2805 key, you can retrieve the pointer to the result with
2806 @code{gpgme_op_genkey_result}. The structure contains the following
2810 @item unsigned int primary : 1
2811 This is a flag that is set to 1 if a primary key was created and to 0
2814 @item unsigned int sub : 1
2815 This is a flag that is set to 1 if a subkey was created and to 0
2819 This is the fingerprint of the key that was created. If both a
2820 primary and a sub key were generated, the fingerprint of the primary
2821 key will be returned. If the crypto engine does not provide the
2822 fingerprint, @code{fpr} will be a null pointer.
2826 @deftypefun gpgme_genkey_result_t gpgme_op_genkey_result (@w{gpgme_ctx_t @var{ctx}})
2827 The function @code{gpgme_op_genkey_result} returns a
2828 @code{gpgme_genkey_result_t} pointer to a structure holding the result of
2829 a @code{gpgme_op_genkey} operation. The pointer is only valid if the
2830 last operation on the context was a @code{gpgme_op_genkey} or
2831 @code{gpgme_op_genkey_start} operation, and if this operation finished
2832 successfully. The returned pointer is only valid until the next
2833 operation is started on the context.
2837 @node Exporting Keys
2838 @subsection Exporting Keys
2840 @cindex key ring, export from
2842 @deftypefun gpgme_error_t gpgme_op_export (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{unsigned int @var{reserved}}, @w{gpgme_data_t @var{keydata}})
2843 The function @code{gpgme_op_export} extracts public keys and returns
2844 them in the data buffer @var{keydata}. The output format of the key
2845 data returned is determined by the @acronym{ASCII} armor attribute set
2846 for the context @var{ctx}.
2848 If @var{pattern} is @code{NULL}, all available keys are returned.
2849 Otherwise, @var{pattern} contains an engine specific expression that
2850 is used to limit the list to all keys matching the pattern.
2852 @var{reserved} is reserved for future use and must be @code{0}.
2854 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
2855 operation completed successfully, @code{GPG_ERR_INV_VALUE} if
2856 @var{keydata} is not a valid empty data buffer, and passes through any
2857 errors that are reported by the crypto engine support routines.
2860 @deftypefun gpgme_error_t gpgme_op_export_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{unsigned int @var{reserved}}, @w{gpgme_data_t @var{keydata}})
2861 The function @code{gpgme_op_export_start} initiates a
2862 @code{gpgme_op_export} operation. It can be completed by calling
2863 @code{gpgme_wait} on the context. @xref{Waiting For Completion}.
2865 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
2866 operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
2867 if @var{keydata} is not a valid empty data buffer.
2870 @deftypefun gpgme_error_t gpgme_op_export_ext (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}[]}, @w{unsigned int @var{reserved}}, @w{gpgme_data_t @var{keydata}})
2871 The function @code{gpgme_op_export} extracts public keys and returns
2872 them in the data buffer @var{keydata}. The output format of the key
2873 data returned is determined by the @acronym{ASCII} armor attribute set
2874 for the context @var{ctx}.
2876 If @var{pattern} or @var{*pattern} is @code{NULL}, all available keys
2877 are returned. Otherwise, @var{pattern} is a @code{NULL} terminated
2878 array of strings that are used to limit the list to all keys matching
2879 at least one of the patterns verbatim.
2881 @var{reserved} is reserved for future use and must be @code{0}.
2883 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
2884 operation completed successfully, @code{GPG_ERR_INV_VALUE} if
2885 @var{keydata} is not a valid empty data buffer, and passes through any
2886 errors that are reported by the crypto engine support routines.
2889 @deftypefun gpgme_error_t gpgme_op_export_ext_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}[]}, @w{unsigned int @var{reserved}}, @w{gpgme_data_t @var{keydata}})
2890 The function @code{gpgme_op_export_ext_start} initiates a
2891 @code{gpgme_op_export_ext} operation. It can be completed by calling
2892 @code{gpgme_wait} on the context. @xref{Waiting For Completion}.
2894 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
2895 operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
2896 if @var{keydata} is not a valid empty data buffer.
2900 @node Importing Keys
2901 @subsection Importing Keys
2903 @cindex key ring, import to
2905 @deftypefun gpgme_error_t gpgme_op_import (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}})
2906 The function @code{gpgme_op_import} adds the keys in the data buffer
2907 @var{keydata} to the key ring of the crypto engine used by @var{ctx}.
2908 The format of @var{keydata} can be @acronym{ASCII} armored, for example,
2909 but the details are specific to the crypto engine.
2911 After the operation completed successfully, the result can be
2912 retrieved with @code{gpgme_op_import_result}.
2914 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
2915 import was completed successfully, @code{GPG_ERR_INV_VALUE} if
2916 @var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer,
2917 and @code{GPG_ERR_NO_DATA} if @var{keydata} is an empty data buffer.
2920 @deftypefun gpgme_error_t gpgme_op_import_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}})
2921 The function @code{gpgme_op_import_start} initiates a
2922 @code{gpgme_op_import} operation. It can be completed by calling
2923 @code{gpgme_wait} on the context. @xref{Waiting For Completion}.
2925 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
2926 import could be started successfully, @code{GPG_ERR_INV_VALUE} if
2927 @var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer,
2928 and @code{GPG_ERR_NO_DATA} if @var{keydata} is an empty data buffer.
2931 @deftp {Data type} {gpgme_import_status_t}
2932 This is a pointer to a structure used to store a part of the result of
2933 a @code{gpgme_op_import} operation. For each considered key one
2934 status is added that contains information about the result of the
2935 import. The structure contains the following members:
2938 @item gpgme_import_status_t next
2939 This is a pointer to the next status structure in the linked list, or
2940 @code{NULL} if this is the last element.
2943 This is the fingerprint of the key that was considered.
2945 @item gpgme_error_t result
2946 If the import was not successful, this is the error value that caused
2947 the import to fail. Otherwise the error code is
2948 @code{GPG_ERR_NO_ERROR}.
2950 @item unsigned int status
2951 This is a bit-wise OR of the following flags that give more
2952 information about what part of the key was imported. If the key was
2953 already known, this might be 0.
2956 @item GPGME_IMPORT_NEW
2959 @item GPGME_IMPORT_UID
2960 The key contained new user IDs.
2962 @item GPGME_IMPORT_SIG
2963 The key contained new signatures.
2965 @item GPGME_IMPORT_SUBKEY
2966 The key contained new sub keys.
2968 @item GPGME_IMPORT_SECRET
2969 The key contained a secret key.
2974 @deftp {Data type} {gpgme_import_result_t}
2975 This is a pointer to a structure used to store the result of a
2976 @code{gpgme_op_import} operation. After a successful import
2977 operation, you can retrieve the pointer to the result with
2978 @code{gpgme_op_import_result}. The structure contains the following
2982 @item int considered
2983 The total number of considered keys.
2985 @item int no_user_id
2986 The number of keys without user ID.
2989 The total number of imported keys.
2992 The number of imported RSA keys.
2995 The number of unchanged keys.
2998 The number of new user IDs.
3001 The number of new sub keys.
3003 @item new_signatures
3004 The number of new signatures.
3006 @item new_revocations
3007 The number of new revocations.
3010 The total number of secret keys read.
3012 @item secret_imported
3013 The number of imported secret keys.
3015 @item secret_unchanged
3016 The number of unchanged secret keys.
3019 The number of keys not imported.
3021 @item gpgme_import_status_t imports
3022 A list of gpgme_import_status_t objects which contain more information
3023 about the keys for which an import was attempted.
3027 @deftypefun gpgme_import_result_t gpgme_op_import_result (@w{gpgme_ctx_t @var{ctx}})
3028 The function @code{gpgme_op_import_result} returns a
3029 @code{gpgme_import_result_t} pointer to a structure holding the result
3030 of a @code{gpgme_op_import} operation. The pointer is only valid if
3031 the last operation on the context was a @code{gpgme_op_import} or
3032 @code{gpgme_op_import_start} operation, and if this operation finished
3033 successfully. The returned pointer is only valid until the next
3034 operation is started on the context.
3037 The following interface is deprecated and only provided for backward
3038 compatibility. Don't use it. It will be removed in a future version
3041 @deftypefun gpgme_error_t gpgme_op_import_ext (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}}, @w{int *@var{nr}})
3042 The function @code{gpgme_op_import_ext} is equivalent to:
3045 gpgme_error_t err = gpgme_op_import (ctx, keydata);
3048 gpgme_import_result_t result = gpgme_op_import_result (ctx);
3049 *nr = result->considered;
3056 @subsection Deleting Keys
3058 @cindex key ring, delete from
3060 @deftypefun gpgme_error_t gpgme_op_delete (@w{gpgme_ctx_t @var{ctx}}, @w{const gpgme_key_t @var{key}}, @w{int @var{allow_secret}})
3061 The function @code{gpgme_op_delete} deletes the key @var{key} from the
3062 key ring of the crypto engine used by @var{ctx}. If
3063 @var{allow_secret} is @code{0}, only public keys are deleted,
3064 otherwise secret keys are deleted as well, if that is supported.
3066 The function returns the error code @code{GPG_ERR_NO_ERROR} if the key
3067 was deleted successfully, @code{GPG_ERR_INV_VALUE} if @var{ctx} or
3068 @var{key} is not a valid pointer, @code{GPG_ERR_NO_PUBKEY} if
3069 @var{key} could not be found in the keyring,
3070 @code{GPG_ERR_AMBIGUOUS_NAME} if the key was not specified
3071 unambiguously, and @code{GPG_ERR_CONFLICT} if the secret key for
3072 @var{key} is available, but @var{allow_secret} is zero.
3075 @deftypefun gpgme_error_t gpgme_op_delete_start (@w{gpgme_ctx_t @var{ctx}}, @w{const gpgme_key_t @var{key}}, @w{int @var{allow_secret}})
3076 The function @code{gpgme_op_delete_start} initiates a
3077 @code{gpgme_op_delete} operation. It can be completed by calling
3078 @code{gpgme_wait} on the context. @xref{Waiting For Completion}.
3080 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3081 operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
3082 @var{ctx} or @var{key} is not a valid pointer.
3086 @node Trust Item Management
3087 @section Trust Item Management
3090 @strong{Caution:} The trust items interface is experimental.
3092 @deftp {Data type} gpgme_trust_item_t
3093 The @code{gpgme_trust_item_t} type is a pointer to a trust item object.
3094 It has the following members:
3098 This is a string describing the key to which this trust items belongs.
3101 This is the type of the trust item. A value of 1 refers to a key, a
3102 value of 2 refers to a user ID.
3105 This is the trust level.
3107 @item char *owner_trust
3108 The owner trust if @code{type} is 1.
3110 @item char *validity
3111 The calculated validity.
3114 The user name if @code{type} is 2.
3119 * Listing Trust Items:: Browsing the list of available trust items.
3120 * Information About Trust Items:: Requesting information about trust items.
3121 * Manipulating Trust Items:: Operations on trust items.
3125 @node Listing Trust Items
3126 @subsection Listing Trust Items
3127 @cindex trust item list
3129 @deftypefun gpgme_error_t gpgme_op_trustlist_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{max_level}})
3130 The function @code{gpgme_op_trustlist_start} initiates a trust item
3131 listing operation inside the context @var{ctx}. It sets everything up
3132 so that subsequent invocations of @code{gpgme_op_trustlist_next} return
3133 the trust items in the list.
3135 The string @var{pattern} contains an engine specific expression that
3136 is used to limit the list to all trust items matching the pattern. It
3137 can not be the empty string.
3139 The argument @var{max_level} is currently ignored.
3141 The context will be busy until either all trust items are received
3142 (and @code{gpgme_op_trustlist_next} returns @code{GPG_ERR_EOF}), or
3143 @code{gpgme_op_trustlist_end} is called to finish the operation.
3145 The function returns the error code @code{GPG_ERR_INV_VALUE} if
3146 @var{ctx} is not a valid pointer, and passes through any errors that
3147 are reported by the crypto engine support routines.
3150 @deftypefun gpgme_error_t gpgme_op_trustlist_next (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_trust_item_t *@var{r_item}})
3151 The function @code{gpgme_op_trustlist_next} returns the next trust
3152 item in the list created by a previous @code{gpgme_op_trustlist_start}
3153 operation in the context @var{ctx}. The trust item can be destroyed
3154 with @code{gpgme_trust_item_release}. @xref{Manipulating Trust Items}.
3156 This is the only way to get at @code{gpgme_trust_item_t} objects in
3159 If the last trust item in the list has already been returned,
3160 @code{gpgme_op_trustlist_next} returns @code{GPG_ERR_EOF}.
3162 The function returns the error code @code{GPG_ERR_INV_VALUE} if @var{ctx} or
3163 @var{r_item} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if
3164 there is not enough memory for the operation.
3167 @deftypefun gpgme_error_t gpgme_op_trustlist_end (@w{gpgme_ctx_t @var{ctx}})
3168 The function @code{gpgme_op_trustlist_next} ends a pending key list
3169 operation in the context @var{ctx}.
3171 The function returns the error code @code{GPG_ERR_INV_VALUE} if
3172 @var{ctx} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if at some
3173 time during the operation there was not enough memory available.
3177 @node Information About Trust Items
3178 @subsection Information About Trust Items
3179 @cindex trust item, information about
3180 @cindex trust item, attributes
3181 @cindex attributes, of a trust item
3183 The following interfaces are deprecated and only provided for backward
3184 compatibility. Don't use them. They will be removed in a future
3185 version of @acronym{GPGME}.
3187 Trust items have attributes which can be queried using the interfaces
3188 below. The attribute identifiers are shared with those for key
3189 attributes. @xref{Information About Keys}.
3191 @deftypefun {const char *} gpgme_trust_item_get_string_attr (@w{gpgme_trust_item_t @var{item}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
3192 The function @code{gpgme_trust_item_get_string_attr} returns the value
3193 of the string-representable attribute @var{what} of trust item
3194 @var{item}. The arguments @var{idx} and @var{reserved} are reserved
3195 for later use and should be @code{0} and @code{NULL} respectively.
3197 The string returned is only valid as long as the key is valid.
3199 The function returns @code{0} if an attribute can't be returned as a
3200 string, @var{key} is not a valid pointer, @var{idx} out of range,
3201 or @var{reserved} not @code{NULL}.
3204 @deftypefun int gpgme_trust_item_get_int_attr (@w{gpgme_trust_item_t @var{item}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
3205 The function @code{gpgme_trust_item_get_int_attr} returns the value of
3206 the number-representable attribute @var{what} of trust item
3207 @var{item}. If the attribute occurs more than once in the trust item,
3208 the index is specified by @var{idx}. However, currently no such
3209 attribute exists, so @var{idx} should be @code{0}. The argument
3210 @var{reserved} is reserved for later use and should be @code{NULL}.
3212 The function returns @code{0} if the attribute can't be returned as a
3213 number, @var{key} is not a valid pointer, @var{idx} out of range,
3214 or @var{reserved} not @code{NULL}.
3218 @node Manipulating Trust Items
3219 @subsection Manipulating Trust Items
3220 @cindex trust item, manipulation
3222 @deftypefun void gpgme_trust_item_ref (@w{gpgme_trust_item_t @var{item}})
3223 The function @code{gpgme_trust_item_ref} acquires an additional
3224 reference for the trust item @var{item}.
3227 @deftypefun void gpgme_trust_item_unref (@w{gpgme_trust_item_t @var{item}})
3228 The function @code{gpgme_trust_item_unref} releases a reference for
3229 the trust item @var{item}. If this was the last reference, the trust
3230 item will be destroyed and all resources associated to it will be
3235 The following interface is deprecated and only provided for backward
3236 compatibility. Don't use it. It will be removed in a future version
3239 @deftypefun void gpgme_trust_item_release (@w{gpgme_trust_item_t @var{item}})
3240 The function @code{gpgme_trust_item_release} is an alias for
3241 @code{gpgme_trust_item_unref}.
3245 @node Crypto Operations
3246 @section Crypto Operations
3247 @cindex cryptographic operation
3249 Sometimes, the result of a crypto operation returns a list of invalid
3250 keys encountered in processing the request. The following structure
3251 is used to hold information about such a key.
3253 @deftp {Data type} {gpgme_invalid_key_t}
3254 This is a pointer to a structure used to store a part of the result of
3255 a crypto operation which takes user IDs as one input parameter. The
3256 structure contains the following members:
3259 @item gpgme_invalid_key_t next
3260 This is a pointer to the next invalid key structure in the linked
3261 list, or @code{NULL} if this is the last element.
3264 The fingerprint or key ID of the invalid key encountered.
3266 @item gpgme_error_t reason
3267 An error code describing the reason why the key was found invalid.
3273 * Decrypt:: Decrypting a ciphertext.
3274 * Verify:: Verifying a signature.
3275 * Decrypt and Verify:: Decrypting a signed ciphertext.
3276 * Sign:: Creating a signature.
3277 * Encrypt:: Encrypting a plaintext.
3284 @cindex cryptographic operation, decryption
3286 @deftypefun gpgme_error_t gpgme_op_decrypt (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
3287 The function @code{gpgme_op_decrypt} decrypts the ciphertext in the
3288 data object @var{cipher} and stores it into the data object
3291 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3292 ciphertext could be decrypted successfully, @code{GPG_ERR_INV_VALUE}
3293 if @var{ctx}, @var{cipher} or @var{plain} is not a valid pointer,
3294 @code{GPG_ERR_NO_DATA} if @var{cipher} does not contain any data to
3295 decrypt, @code{GPG_ERR_DECRYPT_FAILED} if @var{cipher} is not a valid
3296 cipher text, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the
3297 secret key could not be retrieved, and passes through any errors that
3298 are reported by the crypto engine support routines.
3301 @deftypefun gpgme_error_t gpgme_op_decrypt_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
3302 The function @code{gpgme_op_decrypt_start} initiates a
3303 @code{gpgme_op_decrypt} operation. It can be completed by calling
3304 @code{gpgme_wait} on the context. @xref{Waiting For Completion}.
3306 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3307 operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
3308 if @var{cipher} or @var{plain} is not a valid pointer.
3311 @deftp {Data type} {gpgme_decrypt_result_t}
3312 This is a pointer to a structure used to store the result of a
3313 @code{gpgme_op_decrypt} operation. After successfully encrypting
3314 data, you can retrieve the pointer to the result with
3315 @code{gpgme_op_decrypt_result}. The structure contains the following
3319 @item char *unsupported_algorithm
3320 If an unsupported algorithm was encountered, this string describes the
3321 algorithm that is not supported.
3325 @deftypefun gpgme_decrypt_result_t gpgme_op_decrypt_result (@w{gpgme_ctx_t @var{ctx}})
3326 The function @code{gpgme_op_decrypt_result} returns a
3327 @code{gpgme_decrypt_result_t} pointer to a structure holding the
3328 result of a @code{gpgme_op_decrypt} operation. The pointer is only
3329 valid if the last operation on the context was a
3330 @code{gpgme_op_decrypt} or @code{gpgme_op_decrypt_start} operation.
3331 If the operation failed this might be a @code{NULL} pointer. The
3332 returned pointer is only valid until the next operation is started on
3339 @cindex verification
3340 @cindex signature, verification
3341 @cindex cryptographic operation, verification
3342 @cindex cryptographic operation, signature check
3344 @deftypefun gpgme_error_t gpgme_op_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{sig}}, @w{gpgme_data_t @var{signed_text}}, @w{gpgme_data_t @var{plain}})
3345 The function @code{gpgme_op_verify} verifies that the signature in the
3346 data object @var{sig} is a valid signature. If @var{sig} is a
3347 detached signature, then the signed text should be provided in
3348 @var{signed_text} and @var{plain} should be a null pointer.
3349 Otherwise, if @var{sig} is a normal (or cleartext) signature,
3350 @var{signed_text} should be a null pointer and @var{plain} should be a
3351 writable data object that will contain the plaintext after successful
3354 The results of the individual signature verifications can be retrieved
3355 with @code{gpgme_op_verify_result}.
3357 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3358 operation could be completed successfully, @code{GPG_ERR_INV_VALUE} if
3359 @var{ctx}, @var{sig} or @var{plain} is not a valid pointer,
3360 @code{GPG_ERR_NO_DATA} if @var{sig} does not contain any data to
3361 verify, and passes through any errors that are reported by the crypto
3362 engine support routines.
3365 @deftypefun gpgme_error_t gpgme_op_verify_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{sig}}, @w{gpgme_data_t @var{signed_text}}, @w{gpgme_data_t @var{plain}})
3366 The function @code{gpgme_op_verify_start} initiates a
3367 @code{gpgme_op_verify} operation. It can be completed by calling
3368 @code{gpgme_wait} on the context. @xref{Waiting For Completion}.
3370 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3371 operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
3372 @var{ctx}, @var{sig} or @var{plain} is not a valid pointer, and
3373 @code{GPG_ERR_NO_DATA} if @var{sig} or @var{plain} does not contain
3377 @deftp {Data type} {gpgme_sig_notation_t}
3378 This is a pointer to a structure used to store a part of the result of
3379 a @code{gpgme_op_verify} operation. The structure contains the
3383 @item gpgme_sig_notation_t next
3384 This is a pointer to the next new signature notation structure in the
3385 linked list, or @code{NULL} if this is the last element.
3388 The name of the notation field. If this is @code{NULL}, then the
3389 member @code{value} will contain a policy URL.
3392 The value of the notation field. If @code{name} is @code{NULL}, then
3393 this is a policy URL.
3397 @deftp {Data type} {gpgme_signature_t}
3398 This is a pointer to a structure used to store a part of the result of
3399 a @code{gpgme_op_verify} operation. The structure contains the
3403 @item gpgme_signature_t next
3404 This is a pointer to the next new signature structure in the linked
3405 list, or @code{NULL} if this is the last element.
3407 @item gpgme_sigsum_t summary;
3408 This is a bit vector giving a summary of the signature status. It
3409 provides an easy interface to a defined semantic of the signature
3410 status. Checking just one bit is sufficient to see whether a
3411 signature is valid without any restrictions.
3413 The defined bits are:
3415 @item GPGME_SIGSUM_VALID
3416 The signature is fully valid.
3418 @item GPGME_SIGSUM_GREEN
3419 The signature is good but one might want to display some extra
3420 information. Check the other bits.
3422 @item GPGME_SIGSUM_RED
3423 The signature is bad. It might be useful to check other bits and
3424 display more information, i.e. a revoked certificate might not render a
3425 signature invalid when the message was received prior to the cause for
3428 @item GPGME_SIGSUM_KEY_REVOKED
3429 The key or at least one certificate has been revoked.
3431 @item GPGME_SIGSUM_KEY_EXPIRED
3432 The key or one of the certificates has expired. It is probably a good
3433 idea to display the date of the expiration.
3435 @item GPGME_SIGSUM_SIG_EXPIRED
3436 The signature has expired.
3438 @item GPGME_SIGSUM_KEY_MISSING
3439 Can't verify due to a missing key or certificate.
3441 @item GPGME_SIGSUM_CRL_MISSING
3442 The CRL (or an equivalent mechanism) is not available.
3444 @item GPGME_SIGSUM_CRL_TOO_OLD
3445 Available CRL is too old.
3447 @item GPGME_SIGSUM_BAD_POLICY
3448 A policy requirement was not met.
3450 @item GPGME_SIGSUM_SYS_ERROR
3451 A system error occured.
3455 This is the fingerprint or key ID of the signature.
3457 @item gpgme_error_t status
3458 This is the status of the signature. In particular, the following
3459 status codes are of interest:
3462 @item GPG_ERR_NO_ERROR
3463 This status indicates that the signature is valid. For the combined
3464 result this status means that all signatures are valid.
3466 @item GPG_ERR_SIG_EXPIRED
3467 This status indicates that the signature is valid but expired. For
3468 the combined result this status means that all signatures are valid
3471 @item GPG_ERR_KEY_EXPIRED
3472 This status indicates that the signature is valid but the key used to
3473 verify the signature has expired. For the combined result this status
3474 means that all signatures are valid and all keys are expired.
3476 @item GPG_ERR_BAD_SIGNATURE
3477 This status indicates that the signature is invalid. For the combined
3478 result this status means that all signatures are invalid.
3480 @item GPG_ERR_NO_PUBKEY
3481 This status indicates that the signature could not be verified due to
3482 a missing key. For the combined result this status means that all
3483 signatures could not be checked due to missing keys.
3485 @item GPG_ERR_GENERAL
3486 This status indicates that there was some other error which prevented
3487 the signature verification.
3490 @item gpgme_sig_notation_t notations
3491 This is a linked list with the notation data and policy URLs.
3493 @item unsigned long timestamp
3494 The creation timestamp of this signature.
3496 @item unsigned long exp_timestamp
3497 The expiration timestamp of this signature, or 0 if the signature does
3500 @item int wrong_key_usage : 1;
3501 This is true if the key was not used according to its policy.
3503 @item gpgme_validity_t validity
3504 The validity of the signature.
3506 @item gpgme_error_t validity_reason
3507 If a signature is not valid, this provides a reason why.
3512 @deftp {Data type} {gpgme_verify_result_t}
3513 This is a pointer to a structure used to store the result of a
3514 @code{gpgme_op_verify} operation. After verifying a signature, you
3515 can retrieve the pointer to the result with
3516 @code{gpgme_op_verify_result}. If the operation failed this might be
3517 a @code{NULL} pointer. The structure contains the following member:
3520 @item gpgme_signature_t signatures
3521 A linked list with information about all signatures for which a
3522 verification was attempted.
3526 @deftypefun gpgme_sign_result_t gpgme_op_verify_result (@w{gpgme_ctx_t @var{ctx}})
3527 The function @code{gpgme_op_verify_result} returns a
3528 @code{gpgme_verify_result_t} pointer to a structure holding the result of
3529 a @code{gpgme_op_verify} operation. The pointer is only valid if the
3530 last operation on the context was a @code{gpgme_op_verify} or
3531 @code{gpgme_op_verify_start} operation, and if this operation finished
3532 successfully. The returned pointer is only valid until the next
3533 operation is started on the context.
3537 The following interfaces are deprecated and only provided for backward
3538 compatibility. Don't use them. They will be removed in a future
3539 version of @acronym{GPGME}.
3541 @deftp {Data type} {enum gpgme_sig_stat_t}
3542 @tindex gpgme_sig_stat_t
3543 The @code{gpgme_sig_stat_t} type holds the result of a signature check, or
3544 the combined result of all signatures. The following results are
3548 @item GPGME_SIG_STAT_NONE
3549 This status should not occur in normal operation.
3551 @item GPGME_SIG_STAT_GOOD
3552 This status indicates that the signature is valid. For the combined
3553 result this status means that all signatures are valid.
3555 @item GPGME_SIG_STAT_GOOD_EXP
3556 This status indicates that the signature is valid but expired. For
3557 the combined result this status means that all signatures are valid
3560 @item GPGME_SIG_STAT_GOOD_EXPKEY
3561 This status indicates that the signature is valid but the key used to
3562 verify the signature has expired. For the combined result this status
3563 means that all signatures are valid and all keys are expired.
3565 @item GPGME_SIG_STAT_BAD
3566 This status indicates that the signature is invalid. For the combined
3567 result this status means that all signatures are invalid.
3569 @item GPGME_SIG_STAT_NOKEY
3570 This status indicates that the signature could not be verified due to
3571 a missing key. For the combined result this status means that all
3572 signatures could not be checked due to missing keys.
3574 @item GPGME_SIG_STAT_NOSIG
3575 This status indicates that the signature data provided was not a real
3578 @item GPGME_SIG_STAT_ERROR
3579 This status indicates that there was some other error which prevented
3580 the signature verification.
3582 @item GPGME_SIG_STAT_DIFF
3583 For the combined result this status means that at least two signatures
3584 have a different status. You can get each key's status with
3585 @code{gpgme_get_sig_status}.
3589 @deftypefun {const char *} gpgme_get_sig_status (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_sig_stat_t *@var{r_stat}}, @w{time_t *@var{r_created}})
3590 The function @code{gpgme_get_sig_status} is equivalent to:
3593 gpgme_verify_result_t result;
3594 gpgme_signature_t sig;
3596 result = gpgme_op_verify_result (ctx);
3597 sig = result->signatures;
3609 switch (sig->status)
3611 case GPG_ERR_NO_ERROR:
3612 *r_stat = GPGME_SIG_STAT_GOOD;
3615 case GPG_ERR_BAD_SIGNATURE:
3616 *r_stat = GPGME_SIG_STAT_BAD;
3619 case GPG_ERR_NO_PUBKEY:
3620 *r_stat = GPGME_SIG_STAT_NOKEY;
3623 case GPG_ERR_NO_DATA:
3624 *r_stat = GPGME_SIG_STAT_NOSIG;
3627 case GPG_ERR_SIG_EXPIRED:
3628 *r_stat = GPGME_SIG_STAT_GOOD_EXP;
3631 case GPG_ERR_KEY_EXPIRED:
3632 *r_stat = GPGME_SIG_STAT_GOOD_EXPKEY;
3636 *r_stat = GPGME_SIG_STAT_ERROR;
3641 *r_created = sig->timestamp;
3646 @deftypefun {const char *} gpgme_get_sig_string_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{what}}, @w{int @var{whatidx}})
3647 The function @code{gpgme_get_sig_string_attr} is equivalent to:
3650 gpgme_verify_result_t result;
3651 gpgme_signature_t sig;
3653 result = gpgme_op_verify_result (ctx);
3654 sig = result->signatures;
3666 case GPGME_ATTR_FPR:
3669 case GPGME_ATTR_ERRTOK:
3671 return sig->wrong_key_usage ? "Wrong_Key_Usage" : "";
3682 @deftypefun {const char *} gpgme_get_sig_ulong_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{waht}}, @w{int @var{whatidx}})
3683 The function @code{gpgme_get_sig_ulong_attr} is equivalent to:
3686 gpgme_verify_result_t result;
3687 gpgme_signature_t sig;
3689 result = gpgme_op_verify_result (ctx);
3690 sig = result->signatures;
3702 case GPGME_ATTR_CREATED:
3703 return sig->timestamp;
3705 case GPGME_ATTR_EXPIRE:
3706 return sig->exp_timestamp;
3708 case GPGME_ATTR_VALIDITY:
3709 return (unsigned long) sig->validity;
3711 case GPGME_ATTR_SIG_STATUS:
3712 switch (sig->status)
3714 case GPG_ERR_NO_ERROR:
3715 return GPGME_SIG_STAT_GOOD;
3717 case GPG_ERR_BAD_SIGNATURE:
3718 return GPGME_SIG_STAT_BAD;
3720 case GPG_ERR_NO_PUBKEY:
3721 return GPGME_SIG_STAT_NOKEY;
3723 case GPG_ERR_NO_DATA:
3724 return GPGME_SIG_STAT_NOSIG;
3726 case GPG_ERR_SIG_EXPIRED:
3727 return GPGME_SIG_STAT_GOOD_EXP;
3729 case GPG_ERR_KEY_EXPIRED:
3730 return GPGME_SIG_STAT_GOOD_EXPKEY;
3733 return GPGME_SIG_STAT_ERROR;
3736 case GPGME_ATTR_SIG_SUMMARY:
3737 return sig->summary;
3746 @deftypefun {const char *} gpgme_get_sig_key (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_key_t *@var{r_key}})
3747 The function @code{gpgme_get_sig_key} is equivalent to:
3750 gpgme_verify_result_t result;
3751 gpgme_signature_t sig;
3753 result = gpgme_op_verify_result (ctx);
3754 sig = result->signatures;
3762 return gpg_error (GPG_ERR_EOF);
3764 return gpgme_get_key (ctx, sig->fpr, r_key, 0, 0);
3769 @node Decrypt and Verify
3770 @subsection Decrypt and Verify
3771 @cindex decryption and verification
3772 @cindex verification and decryption
3773 @cindex signature check
3774 @cindex cryptographic operation, decryption and verification
3776 @deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
3777 The function @code{gpgme_op_decrypt_verify} decrypts the ciphertext in
3778 the data object @var{cipher} and stores it into the data object
3779 @var{plain}. If @var{cipher} contains signatures, they will be
3782 After the operation completed, @code{gpgme_op_decrypt_result} and
3783 @code{gpgme_op_verify_result} can be used to retrieve more information
3784 about the signatures.
3786 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3787 ciphertext could be decrypted successfully, @code{GPG_ERR_INV_VALUE}
3788 if @var{ctx}, @var{cipher} or @var{plain} is not a valid pointer,
3789 @code{GPG_ERR_NO_DATA} if @var{cipher} does not contain any data to
3790 decrypt, @code{GPG_ERR_DECRYPT_FAILED} if @var{cipher} is not a valid
3791 cipher text, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the
3792 secret key could not be retrieved, and passes through any errors that
3793 are reported by the crypto engine support routines.
3796 @deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
3797 The function @code{gpgme_op_decrypt_verify_start} initiates a
3798 @code{gpgme_op_decrypt_verify} operation. It can be completed by
3799 calling @code{gpgme_wait} on the context. @xref{Waiting For
3802 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3803 operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
3804 @var{ctx}, @var{cipher}, @var{plain} or @var{r_stat} is not a valid
3805 pointer, and @code{GPG_ERR_NO_DATA} if @var{cipher} does not contain
3806 any data to decrypt.
3812 @cindex signature, creation
3814 @cindex cryptographic operation, signing
3816 A signature can contain signatures by one or more keys. The set of
3817 keys used to create a signatures is contained in a context, and is
3818 applied to all following signing operations in this context (until the
3822 * Selecting Signers:: How to choose the keys to sign with.
3823 * Creating a Signature:: How to create a signature.
3827 @node Selecting Signers
3828 @subsubsection Selecting Signers
3829 @cindex signature, selecting signers
3830 @cindex signers, selecting
3832 @deftypefun void gpgme_signers_clear (@w{gpgme_ctx_t @var{ctx}})
3833 The function @code{gpgme_signers_clear} releases a reference for each
3834 key on the signers list and removes the list of signers from the
3837 Every context starts with an empty list.
3840 @deftypefun gpgme_error_t gpgme_signers_add (@w{gpgme_ctx_t @var{ctx}}, @w{const gpgme_key_t @var{key}})
3841 The function @code{gpgme_signers_add} adds the key @var{key} to the
3842 list of signers in the context @var{ctx}.
3844 Calling this function acquires an additional reference for the key.
3847 @deftypefun gpgme_key_t gpgme_signers_enum (@w{const gpgme_ctx_t @var{ctx}}, @w{int @var{seq}})
3848 The function @code{gpgme_signers_enum} returns the @var{seq}th key in
3849 the list of signers in the context @var{ctx}. An additional reference
3850 is acquired for the user.
3852 If @var{seq} is out of range, @code{NULL} is returned.
3856 @node Creating a Signature
3857 @subsubsection Creating a Signature
3859 @deftp {Data type} {enum gpgme_sig_mode_t}
3860 @tindex gpgme_sig_mode_t
3861 The @code{gpgme_sig_mode_t} type is used to specify the desired type of a
3862 signature. The following modes are available:
3865 @item GPGME_SIG_MODE_NORMAL
3866 A normal signature is made, the output includes the plaintext and the
3869 @item GPGME_SIG_MODE_DETACH
3870 A detached signature is made.
3872 @item GPGME_SIG_MODE_CLEAR
3873 A clear text signature is made. The @acronym{ASCII} armor and text
3874 mode settings of the context are ignored.
3878 @deftypefun gpgme_error_t gpgme_op_sign (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{sig}}, @w{gpgme_sig_mode_t @var{mode}})
3879 The function @code{gpgme_op_sign} creates a signature for the text in
3880 the data object @var{plain} and returns it in the data object
3881 @var{sig}. The type of the signature created is determined by the
3882 @acronym{ASCII} armor and text mode attributes set for the context
3883 @var{ctx} and the requested signature mode @var{mode}.
3885 After the operation completed successfully, the result can be
3886 retrieved with @code{gpgme_op_sign_result}.
3888 If an S/MIME signed message is created using the CMS crypto engine,
3889 the number of certificates to include in the message can be specified
3890 with @code{gpgme_set_include_certs}. @xref{Included Certificates}.
3892 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3893 signature could be created successfully, @code{GPG_ERR_INV_VALUE} if
3894 @var{ctx}, @var{plain} or @var{sig} is not a valid pointer,
3895 @code{GPG_ERR_NO_DATA} if the signature could not be created,
3896 @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the secret key
3897 could not be retrieved, and passes through any errors that are
3898 reported by the crypto engine support routines.
3901 @deftypefun gpgme_error_t gpgme_op_sign_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{sig}}, @w{gpgme_sig_mode_t @var{mode}})
3902 The function @code{gpgme_op_sign_start} initiates a
3903 @code{gpgme_op_sign} operation. It can be completed by calling
3904 @code{gpgme_wait} on the context. @xref{Waiting For Completion}.
3906 The function returns the error code @code{GPG_ERR_NO_ERROR} if the operation could be
3907 started successfully, and @code{GPG_ERR_INV_VALUE} if @var{ctx},
3908 @var{plain} or @var{sig} is not a valid pointer.
3911 @deftp {Data type} {gpgme_new_signature_t}
3912 This is a pointer to a structure used to store a part of the result of
3913 a @code{gpgme_op_sign} operation. The structure contains the
3917 @item gpgme_new_signature_t next
3918 This is a pointer to the next new signature structure in the linked
3919 list, or @code{NULL} if this is the last element.
3921 @item gpgme_sig_mode_t type
3922 The type of this signature.
3924 @item gpgme_pubkey_algo_t
3925 The public key algorithm used to create this signature.
3927 @item gpgme_hash_algo_t
3928 The hash algorithm used to create this signature.
3930 @item unsigned long class
3931 The signature class of this signature.
3933 @item long int timestamp
3934 The creation timestamp of this signature.
3937 The fingerprint of the key which was used to create this signature.
3941 @deftp {Data type} {gpgme_sign_result_t}
3942 This is a pointer to a structure used to store the result of a
3943 @code{gpgme_op_sign} operation. After successfully generating a
3944 signature, you can retrieve the pointer to the result with
3945 @code{gpgme_op_sign_result}. The structure contains the following
3949 @item gpgme_invalid_key_t invalid_signers
3950 A linked list with information about all invalid keys for which a
3951 signature could not be created.
3953 @item gpgme_new_signature_t signatures
3954 A linked list with information about all signatures created.
3958 @deftypefun gpgme_sign_result_t gpgme_op_sign_result (@w{gpgme_ctx_t @var{ctx}})
3959 The function @code{gpgme_op_sign_result} returns a
3960 @code{gpgme_sign_result_t} pointer to a structure holding the result of a
3961 @code{gpgme_op_sign} operation. The pointer is only valid if the last
3962 operation on the context was a @code{gpgme_op_sign} or
3963 @code{gpgme_op_sign_start} operation, and if this operation finished
3964 successfully. The returned pointer is only valid until the next
3965 operation is started on the context.
3972 @cindex cryptographic operation, encryption
3974 One plaintext can be encrypted for several recipients at the same
3975 time. The list of recipients is created independently of any context,
3976 and then passed to the encryption operation.
3979 * Encrypting a Plaintext:: How to encrypt a plaintext.
3983 @node Encrypting a Plaintext
3984 @subsubsection Encrypting a Plaintext
3986 @deftypefun gpgme_error_t gpgme_op_encrypt (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}[]}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
3987 The function @code{gpgme_op_encrypt} encrypts the plaintext in the data
3988 object @var{plain} for the recipients @var{recp} and stores the
3989 ciphertext in the data object @var{cipher}. The type of the
3990 ciphertext created is determined by the @acronym{ASCII} armor and text
3991 mode attributes set for the context @var{ctx}.
3993 @var{key} must be a @code{NULL}-terminated array of keys. The user
3994 must keep references for all keys during the whole duration of the
3995 call (but see @code{gpgme_op_encrypt_start} for the requirements with
3996 the asynchronous variant).
3998 The value in @var{flags} is a bitwise-or combination of one or
3999 multiple of the following bit values:
4002 @item GPGME_ENCRYPT_ALWAYS_TRUST
4003 The @code{GPGME_ENCRYPT_ALWAYS_TRUST} symbol specifies that all the
4004 recipients in @var{recp} should be trusted, even if the keys do not
4005 have a high enough validity in the keyring. This flag should be used
4006 with care; in general it is not a good idea to use any untrusted keys.
4009 If @code{GPG_ERR_UNUSABLE_PUBKEY} is returned, some recipients in
4010 @var{recp} are invalid, but not all. In this case the plaintext might
4011 be encrypted for all valid recipients and returned in @var{cipher} (if
4012 this happens depends on the crypto engine). More information about
4013 the invalid recipients is available with
4014 @code{gpgme_op_encrypt_result}.
4016 If @var{recp} is @code{NULL}, symmetric rather than public key
4017 encryption is performed. Symmetrically encrypted cipher text can be
4018 deciphered with @code{gpgme_op_decrypt}. Note that in this case the
4019 crypto backend needs to retrieve a passphrase from the user.
4020 Symmetric encryption is currently only supported for the OpenPGP
4023 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
4024 ciphertext could be created successfully, @code{GPG_ERR_INV_VALUE} if
4025 @var{ctx}, @var{recp}, @var{plain} or @var{cipher} is not a valid
4026 pointer, @code{GPG_ERR_UNUSABLE_PUBKEY} if @var{recp} contains some
4027 invalid recipients, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase
4028 for the secret key could not be retrieved, and passes through any
4029 errors that are reported by the crypto engine support routines.
4032 @deftypefun gpgme_error_t gpgme_op_encrypt_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}[]}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
4033 The function @code{gpgme_op_encrypt_start} initiates a
4034 @code{gpgme_op_encrypt} operation. It can be completed by calling
4035 @code{gpgme_wait} on the context. @xref{Waiting For Completion}.
4037 References to the keys only need to be held for the duration of this
4038 call. The user can release its references to the keys after this
4039 function returns, even if the operation is not yet finished.
4041 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
4042 operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
4043 @var{ctx}, @var{rset}, @var{plain} or @var{cipher} is not a valid
4044 pointer, and @code{GPG_ERR_UNUSABLE_PUBKEY} if @var{rset} does not
4045 contain any valid recipients.
4048 @deftp {Data type} {gpgme_encrypt_result_t}
4049 This is a pointer to a structure used to store the result of a
4050 @code{gpgme_op_encrypt} operation. After successfully encrypting
4051 data, you can retrieve the pointer to the result with
4052 @code{gpgme_op_encrypt_result}. The structure contains the following
4056 @item gpgme_invalid_key_t invalid_recipients
4057 A linked list with information about all invalid keys for which
4058 the data could not be encrypted.
4062 @deftypefun gpgme_encrypt_result_t gpgme_op_encrypt_result (@w{gpgme_ctx_t @var{ctx}})
4063 The function @code{gpgme_op_encrypt_result} returns a
4064 @code{gpgme_encrypt_result_t} pointer to a structure holding the result of
4065 a @code{gpgme_op_encrypt} operation. The pointer is only valid if the
4066 last operation on the context was a @code{gpgme_op_encrypt} or
4067 @code{gpgme_op_encrypt_start} operation, and if this operation
4068 finished successfully. The returned pointer is only valid until the
4069 next operation is started on the context.
4073 @deftypefun gpgme_error_t gpgme_op_encrypt_sign (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}[]}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
4074 The function @code{gpgme_op_encrypt_sign} does a combined encrypt and
4075 sign operation. It is used like @code{gpgme_op_encrypt}, but the
4076 ciphertext also contains signatures for the signers listed in
4079 The combined encrypt and sign operation is currently only available
4080 for the OpenPGP crypto engine.
4083 @deftypefun gpgme_error_t gpgme_op_encrypt_sign_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
4084 The function @code{gpgme_op_encrypt_sign_start} initiates a
4085 @code{gpgme_op_encrypt_sign} operation. It can be completed by
4086 calling @code{gpgme_wait} on the context. @xref{Waiting For
4089 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
4090 operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
4091 if @var{ctx}, @var{rset}, @var{plain} or @var{cipher} is not a valid
4097 @section Run Control
4099 @cindex cryptographic operation, running
4101 @acronym{GPGME} supports running operations synchronously and
4102 asynchronously. You can use asynchronous operation to set up a
4103 context up to initiating the desired operation, but delay performing
4104 it to a later point.
4106 Furthermore, you can use an external event loop to control exactly
4107 when @acronym{GPGME} runs. This ensures that @acronym{GPGME} only
4108 runs when necessary and also prevents it from blocking for a long
4112 * Waiting For Completion:: Waiting until an operation is completed.
4113 * Using External Event Loops:: Advanced control over what happens when.
4117 @node Waiting For Completion
4118 @subsection Waiting For Completion
4119 @cindex cryptographic operation, wait for
4120 @cindex wait for completion
4122 @deftypefun gpgme_ctx_t gpgme_wait (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_error_t *@var{status}}, @w{int @var{hang}})
4123 The function @code{gpgme_wait} continues the pending operation within
4124 the context @var{ctx}. In particular, it ensures the data exchange
4125 between @acronym{GPGME} and the crypto backend and watches over the
4126 run time status of the backend process.
4128 If @var{hang} is true, the function does not return until the
4129 operation is completed or cancelled. Otherwise the function will not
4130 block for a long time.
4132 The error status of the finished operation is returned in @var{status}
4133 if @code{gpgme_wait} does not return @code{NULL}.
4135 The @var{ctx} argument can be @code{NULL}. In that case,
4136 @code{gpgme_wait} waits for any context to complete its operation.
4138 @code{gpgme_wait} can be used only in conjunction with any context
4139 that has a pending operation initiated with one of the
4140 @code{gpgme_op_*_start} functions except @code{gpgme_op_keylist_start}
4141 and @code{gpgme_op_trustlist_start} (for which you should use the
4142 corresponding @code{gpgme_op_*_next} functions). If @var{ctx} is
4143 @code{NULL}, all of such contexts are waited upon and possibly
4144 returned. Synchronous operations running in parallel, as well as key
4145 and trust item list operations, do not affect @code{gpgme_wait}.
4147 In a multi-threaded environment, only one thread should ever call
4148 @code{gpgme_wait} at any time, irregardless if @var{ctx} is specified
4149 or not. This means that all calls to this function should be fully
4150 synchronized by locking primitives. It is safe to start asynchronous
4151 operations while a thread is running in @code{gpgme_wait}.
4153 The function returns the @var{ctx} of the context which has finished
4154 the operation. If @var{hang} is false, and the timeout expires,
4155 @code{NULL} is returned and @code{*status} will be set to 0. If an
4156 error occurs, @code{NULL} is returned and the error is returned in
4161 @node Using External Event Loops
4162 @subsection Using External Event Loops
4163 @cindex event loop, external
4165 @acronym{GPGME} hides the complexity of the communication between the
4166 library and the crypto engine. The price of this convenience is that
4167 the calling thread can block arbitrary long waiting for the data
4168 returned by the crypto engine. In single-threaded programs, in
4169 particular if they are interactive, this is an unwanted side-effect.
4170 OTOH, if @code{gpgme_wait} is used without the @var{hang} option being
4171 enabled, it might be called unnecessarily often, wasting CPU time that
4172 could be used otherwise.
4174 The I/O callback interface described in this section lets the user
4175 take control over what happens when. @acronym{GPGME} will provide the
4176 user with the file descriptors that should be monitored, and the
4177 callback functions that should be invoked when a file descriptor is
4178 ready for reading or writing. It is then the user's responsibility to
4179 decide when to check the file descriptors and when to invoke the
4180 callback functions. Usually this is done in an event loop, that also
4181 checks for events in other parts of the program. If the callback
4182 functions are only called when the file descriptors are ready,
4183 @acronym{GPGME} will never block. This gives the user mroe control
4184 over the program flow, and allows to perform other tasks when
4185 @acronym{GPGME} would block otherwise.
4187 By using this advanced mechanism, @acronym{GPGME} can be integrated
4188 smoothly into GUI toolkits like GTK+ even for single-threaded
4192 * I/O Callback Interface:: How I/O callbacks are registered.
4193 * Registering I/O Callbacks:: How to use I/O callbacks for a context.
4194 * I/O Callback Example:: An example how to use I/O callbacks.
4195 * I/O Callback Example GTK+:: How to use @acronym{GPGME} with GTK+.
4196 * I/O Callback Example GDK:: How to use @acronym{GPGME} with GDK.
4200 @node I/O Callback Interface
4201 @subsubsection I/O Callback Interface
4203 @deftp {Data type} {gpgme_error_t (*gpgme_io_cb_t) (@w{void *@var{data}}, @w{int @var{fd}})}
4204 @tindex gpgme_io_cb_t
4205 The @code{gpgme_io_cb_t} type is the type of functions which
4206 @acronym{GPGME} wants to register as I/O callback handlers using the
4207 @code{gpgme_register_io_cb_t} functions provided by the user.
4209 @var{data} and @var{fd} are provided by @acronym{GPGME} when the I/O
4210 callback handler is registered, and should be passed through to the
4211 handler when it is invoked by the user because it noticed activity on
4212 the file descriptor @var{fd}.
4214 The callback handler always returns @code{0}, but you should consider
4215 the return value to be reserved for later use.
4218 @deftp {Data type} {gpgme_error_t (*gpgme_register_io_cb_t) (@w{void *@var{data}}, @w{int @var{fd}}, @w{int @var{dir}}, @w{gpgme_io_cb_t @var{fnc}}, @w{void *@var{fnc_data}}, @w{void **@var{tag}})}
4219 @tindex gpgme_register_io_cb_t
4220 The @code{gpgme_register_io_cb_t} type is the type of functions which can
4221 be called by @acronym{GPGME} to register an I/O callback funtion
4222 @var{fnc} for the file descriptor @var{fd} with the user.
4223 @var{fnc_data} should be passed as the first argument to @var{fnc}
4224 when the handler is invoked (the second argument should be @var{fd}).
4225 If @var{dir} is 0, @var{fnc} should be called by the user when
4226 @var{fd} is ready for writing. If @var{dir} is 1, @var{fnc} should be
4227 called when @var{fd} is ready for reading.
4229 @var{data} was provided by the user when registering the
4230 @code{gpgme_register_io_cb_t} function with @acronym{GPGME} and will always
4231 be passed as the first argument when registering a callback function.
4232 For example, the user can use this to determine the event loop to
4233 which the file descriptor should be added.
4235 @acronym{GPGME} will call this function when a crypto operation is
4236 initiated in a context for which the user has registered I/O callback
4237 handler functions with @code{gpgme_set_io_cbs}. It can also call this
4238 function when it is in an I/O callback handler for a file descriptor
4239 associated to this context.
4241 The user should return a unique handle in @var{tag} identifying this
4242 I/O callback registration, which will be passed to the
4243 @code{gpgme_register_io_cb_t} function without interpretation when the file
4244 descriptor should not be monitored anymore.
4247 @deftp {Data type} {void (*gpgme_remove_io_cb_t) (@w{void *@var{tag}})}
4248 The @code{gpgme_remove_io_cb_t} type is the type of functions which can be
4249 called by @acronym{GPGME} to remove an I/O callback handler that was
4250 registered before. @var{tag} is the handle that was returned by the
4251 @code{gpgme_register_io_cb_t} for this I/O callback.
4253 @acronym{GPGME} can call this function when a crypto operation is in
4254 an I/O callback. It will also call this function when the context is
4255 destroyed while an operation is pending.
4258 @deftp {Data type} {enum gpgme_event_io_t}
4259 @tindex gpgme_event_io_t
4260 The @code{gpgme_event_io_t} type specifies the type of an event that is
4261 reported to the user by @acronym{GPGME} as a consequence of an I/O
4262 operation. The following events are defined:
4265 @item GPGME_EVENT_START
4266 The operation is fully initialized now, and you can start to run the
4267 registered I/O callback handlers now. Note that registered I/O
4268 callback handlers must not be run before this event is signalled.
4269 @var{type_data} is @code{NULL} and reserved for later use.
4271 @item GPGME_EVENT_DONE
4272 The operation is finished, the last I/O callback for this operation
4273 was removed. The accompanying @var{type_data} points to a
4274 @code{gpgme_error_t} variable that contains the status of the operation
4275 that finished. This event is signalled after the last I/O callback
4278 @item GPGME_EVENT_NEXT_KEY
4279 In a @code{gpgme_op_keylist_start} operation, the next key was
4280 received from the crypto engine. The accompanying @var{type_data} is
4281 a @code{gpgme_key_t} variable that contains the key with one reference
4284 @item GPGME_EVENT_NEXT_TRUSTITEM
4285 In a @code{gpgme_op_trustlist_start} operation, the next trust item
4286 was received from the crypto engine. The accompanying @var{type_data}
4287 is a @code{gpgme_trust_item_t} variable that contains the trust item with
4288 one reference for the user.
4292 @deftp {Data type} {void (*gpgme_event_io_cb_t) (@w{void *@var{data}}, @w{gpgme_event_io_t @var{type}}, @w{void *@var{type_data}})}
4293 The @code{gpgme_event_io_cb_t} type is the type of functions which can be
4294 called by @acronym{GPGME} to signal an event for an operation running
4295 in a context which has I/O callback functions registered by the user.
4297 @var{data} was provided by the user when registering the
4298 @code{gpgme_event_io_cb_t} function with @acronym{GPGME} and will always be
4299 passed as the first argument when registering a callback function.
4300 For example, the user can use this to determine the context in which
4301 this event has occured.
4303 @var{type} will specify the type of event that has occured.
4304 @var{type_data} specifies the event further, as described in the above
4305 list of possible @code{gpgme_event_io_t} types.
4307 @acronym{GPGME} can call this function in an I/O callback handler.
4311 @node Registering I/O Callbacks
4312 @subsubsection Registering I/O Callbacks
4314 @deftp {Data type} {struct gpgme_io_cb_ts}
4315 @tindex gpgme_event_io_t
4316 This structure is used to store the I/O callback interface functions
4317 described in the previous section. It has the following members:
4320 @item gpgme_register_io_cb_t add
4321 This is the function called by @acronym{GPGME} to register an I/O
4322 callback handler. It must be specified.
4324 @item void *add_data
4325 This is passed as the first argument to the @code{add} function when
4326 it is called by @acronym{GPGME}. For example, it can be used to
4327 determine the event loop to which the file descriptor should be added.
4329 @item gpgme_remove_io_cb_t remove
4330 This is the function called by @acronym{GPGME} to remove an I/O
4331 callback handler. It must be specified.
4333 @item gpgme_event_io_cb_t event
4334 This is the function called by @acronym{GPGME} to signal an event for
4335 an operation. It is optional, but if you don't specify it, you can
4336 not retrieve the return value of the operation.
4338 @item void *event_data
4339 This is passed as the first argument to the @code{event} function when
4340 it is called by @acronym{GPGME}. For example, it can be used to
4341 determine the context in which the event has occured.
4345 @deftypefun void gpgme_set_io_cbs (@w{gpgme_ctx_t @var{ctx}}, @w{struct gpgme_io_cb_ts *@var{io_cbs}})
4346 The function @code{gpgme_set_io_cbs} enables the I/O callback
4347 interface for the context @var{ctx}. The I/O callback functions are
4348 specified by @var{io_cbs}.
4350 If @var{io_cbs}->@code{add} is @code{NULL}, the I/O callback interface
4351 is disabled for the context, and normal operation is restored.
4354 @deftypefun void gpgme_get_io_cbs (@w{gpgme_ctx_t @var{ctx}}, @w{struct gpgme_io_cb_ts *@var{io_cbs}})
4355 The function @code{gpgme_get_io_cbs} returns the I/O callback
4356 functions set with @code{gpgme_set_io_cbs} in @var{io_cbs}.
4360 @node I/O Callback Example
4361 @subsubsection I/O Callback Example
4363 To actually use an external event loop, you have to implement the I/O
4364 callback functions that are used by @acronym{GPGME} to register and
4365 unregister file descriptors. Furthermore, you have to actually
4366 monitor these file descriptors for activity and call the appropriate
4369 The following example illustrates how to do that. The example uses
4370 locking to show in which way the the callbacks and the event loop can
4371 run concurrently. For the event loop, we use a fixed array. For a
4372 real-world implementation, you should use a dynamically sized
4373 structure because the number of file descriptors needed for a crypto
4374 operation in @acronym{GPGME} is not predictable.
4377 #include <pthread.h>
4378 #include <sys/types.h>
4381 /* The following structure holds the result of a crypto operation. */
4388 /* The following structure holds the data associated with one I/O
4400 pthread_mutex_t lock;
4402 /* Unused slots are marked with FD being -1. */
4403 struct one_fd fds[MAX_FDS];
4407 The following functions implement the I/O callback interface.
4411 add_io_cb (void *data, int fd, int dir, gpgme_io_cb_t fnc, void *fnc_data,
4414 struct event_loop *loop = data;
4415 struct one_fd *fds = loop->fds;
4418 pthread_mutex_lock (&loop->lock);
4419 for (i = 0; i < MAX_FDS; i++)
4421 if (fds[i].fd == -1)
4426 fds[i].fnc_data = fnc_data;
4430 pthread_mutex_unlock (&loop->lock);
4432 return gpg_error (GPG_ERR_GENERAL);
4438 remove_io_cb (void *tag)
4440 struct one_fd *fd = tag;
4442 pthread_mutex_lock (&loop->lock);
4444 pthread_mutex_unlock (&loop->lock);
4448 event_io_cb (void *data, gpgme_event_io_t type, void *type_data)
4450 struct op_result *result = data;
4452 /* We don't support list operations here. */
4453 if (type == GPGME_EVENT_DONE)
4456 result->err = *type_data;
4461 The final missing piece is the event loop, which will be presented
4462 next. We only support waiting for the success of a single operation.
4466 do_select (struct event_loop *loop)
4473 pthread_mutex_lock (&loop->lock);
4476 for (i = 0; i < FDLIST_MAX; i++)
4477 if (fdlist[i].fd != -1)
4478 FD_SET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds);
4479 pthread_mutex_unlock (&loop->unlock);
4483 n = select (FD_SETSIZE, &rfds, &wfds, NULL, 0);
4485 while (n < 0 && errno == EINTR);
4488 return n; /* Error or timeout. */
4490 pthread_mutex_lock (&loop->lock);
4491 for (i = 0; i < FDLIST_MAX && n; i++)
4493 if (fdlist[i].fd != -1)
4495 if (FD_ISSET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds))
4500 /* The I/O callback handler can register/remove callbacks,
4501 so we have to unlock the file descriptor list. */
4502 pthread_mutex_unlock (&loop->lock);
4503 (*fdlist[i].fnc) (fdlist[i].fnc_data, fdlist[i].fd);
4504 pthread_mutex_lock (&loop->lock);
4508 pthread_mutex_unlock (&loop->lock);
4513 wait_for_op (struct event_loop *loop, struct op_result *result)
4519 ret = do_select (loop);
4521 while (ret >= 0 && !result->done);
4526 The main function shows how to put it all together.
4530 main (int argc, char *argv[])
4532 struct event_loop loop;
4533 struct op_result result;
4536 gpgme_data_t sig, text;
4537 gpgme_sig_stat_t status;
4539 struct gpgme_io_cb_ts io_cbs =
4548 /* Initialize the loop structure. */
4549 loop.lock = PTHREAD_MUTEX_INITIALIZER;
4550 for (i = 0; i < MAX_FDS; i++)
4551 loop->fds[i].fd = -1;
4553 /* Initialize the result structure. */
4556 err = gpgme_data_new_from_file (&sig, "signature", 1);
4558 err = gpgme_data_new_from_file (&text, "text", 1);
4560 err = gpgme_new (&ctx);
4563 gpgme_set_io_cbs (ctx, &io_cbs);
4564 err = gpgme_op_verify_start (ctx, sig, text, &status);
4568 fprintf (stderr, "gpgme error: %s: %s\n",
4569 gpgme_strsource (err), gpgme_strerror (err));
4573 wait_for_op (&loop, &result);
4576 fprintf (stderr, "select error\n");
4581 fprintf (stderr, "verification failed: %s: %s\n",
4582 gpgme_strsource (result.err), gpgme_strerror (result.err));
4585 /* Evaluate STATUS. */
4592 @node I/O Callback Example GTK+
4593 @subsubsection I/O Callback Example GTK+
4594 @cindex GTK+, using @acronym{GPGME} with
4596 The I/O callback interface can be used to integrate @acronym{GPGME}
4597 with the GTK+ event loop. The following code snippets shows how this
4598 can be done using the appropriate register and remove I/O callback
4599 functions. In this example, the private data of the register I/O
4600 callback function is unused. The event notifications is missing
4601 because it does not require any GTK+ specific setup.
4604 #include <gtk/gtk.h>
4606 struct my_gpgme_io_cb
4610 guint input_handler_id
4614 my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition)
4616 struct my_gpgme_io_cb *iocb = data;
4617 (*(iocb->fnc)) (iocb->data, source);
4621 my_gpgme_remove_io_cb (void *data)
4623 struct my_gpgme_io_cb *iocb = data;
4624 gtk_input_remove (data->input_handler_id);
4628 my_gpgme_register_io_callback (void *data, int fd, int dir, gpgme_io_cb_t fnc,
4629 void *fnc_data, void **tag)
4631 struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb));
4633 iocb->data = fnc_data;
4634 iocb->input_handler_id = gtk_input_add_full (fd, dir
4637 my_gpgme_io_callback,
4645 @node I/O Callback Example GDK
4646 @subsubsection I/O Callback Example GDK
4647 @cindex GDK, using @acronym{GPGME} with
4649 The I/O callback interface can also be used to integrate
4650 @acronym{GPGME} with the GDK event loop. The following code snippets
4651 shows how this can be done using the appropriate register and remove
4652 I/O callback functions. In this example, the private data of the
4653 register I/O callback function is unused. The event notifications is
4654 missing because it does not require any GDK specific setup.
4656 It is very similar to the GTK+ example in the previous section.
4659 #include <gdk/gdk.h>
4661 struct my_gpgme_io_cb
4669 my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition)
4671 struct my_gpgme_io_cb *iocb = data;
4672 (*(iocb->fnc)) (iocb->data, source);
4676 my_gpgme_remove_io_cb (void *data)
4678 struct my_gpgme_io_cb *iocb = data;
4679 gdk_input_remove (data->tag);
4683 my_gpgme_register_io_callback (void *data, int fd, int dir, gpgme_io_cb_t fnc,
4684 void *fnc_data, void **tag)
4686 struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb));
4688 iocb->data = fnc_data;
4689 iocb->tag = gtk_input_add_full (fd, dir ? GDK_INPUT_READ : GDK_INPUT_WRITE,
4690 my_gpgme_io_callback, iocb, NULL);
4704 @unnumbered Concept Index
4709 @node Function and Data Index
4710 @unnumbered Function and Data Index