2003-09-03 Marcus Brinkmann <marcus@g10code.de>
[gpgme.git] / doc / gpgme.texi
1 \input texinfo                  @c -*- Texinfo -*-
2 @setfilename gpgme.info
3 @settitle The `GnuPG Made Easy' Reference Manual
4
5 @dircategory GNU Libraries
6 @direntry
7 * @acronym{GPGME}: (gpgme).          Adding support for cryptography to your program.
8 @end direntry
9
10 @include version.texi
11
12 @c Unify some of the indices.
13 @syncodeindex tp fn
14 @syncodeindex pg fn
15
16 @ifinfo
17 This file documents the @acronym{GPGME} library.
18
19 This is Edition @value{EDITION}, last updated @value{UPDATED}, of
20 @cite{The `GnuPG Made Easy' Reference Manual}, for Version
21 @value{VERSION}.
22
23 Copyright @copyright{} 2002, 2003 g10 Code GmbH.
24
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''.
33
34 @end ifinfo
35
36 @iftex
37 @shorttitlepage The `GnuPG Made Easy' Reference Manual
38 @end iftex
39 @titlepage
40 @center @titlefont{The `GnuPG Made Easy'}
41 @sp 1
42 @center @titlefont{Reference Manual}
43 @sp 6
44 @center Edition @value{EDITION}
45 @sp 1
46 @center last updated @value{UPDATED}
47 @sp 1
48 @center for version @value{VERSION}
49 @page
50 @vskip 0pt plus 1filll
51 Copyright @copyright{} 2002, 2003 g10 Code GmbH.
52
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''.
61 @end titlepage
62 @page
63
64 @ifnottex
65 @node Top
66 @top Main Menu
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.
70 @end ifnottex
71
72 @menu
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.
80
81 Appendices
82
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.
87
88 Indices
89
90 * Concept Index::                 Index of concepts and programs.
91 * Function and Data Index::       Index of functions, variables and data types.
92
93
94 @detailmenu
95  --- The Detailed Node Listing ---
96
97 Introduction
98
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.
102
103 Preparation
104
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 * Using Libtool::                 Avoiding compiler options entirely.
109 * Library Version Check::         Getting and verifying the library version.
110 * Multi Threading::               How @acronym{GPGME} can be used in an MT environment.
111
112 Protocols and Engines
113
114 * Engine Version Check::          Verifying the engine version.
115 * Engine Information::            Obtaining more information about the engines.
116 * OpenPGP::                       Support for the OpenPGP protocol.
117 * Cryptographic Message Syntax::  Support for the CMS.
118
119 Algorithms
120
121 * Public Key Algorithms::         A list of all public key algorithms.
122 * Hash Algorithms::               A list of all hash algorithms.
123
124 Error Handling
125
126 * Error Values::                  The error value and what it means.
127 * Error Codes::                   A list of important error codes.
128 * Error Sources::                 A list of important error sources.
129 * Error Strings::                 How to get a descriptive string from a value.
130
131 Exchanging Data 
132
133 * Creating Data Buffers::         Creating new data buffers.
134 * Destroying Data Buffers::       Releasing data buffers.
135 * Manipulating Data Buffers::     Operations on data buffers.
136
137 Creating Data Buffers
138
139 * Memory Based Data Buffers::     Creating memory based data buffers.
140 * File Based Data Buffers::       Creating file based data buffers.
141 * Callback Based Data Buffers::   Creating callback based data buffers.
142
143 Contexts
144
145 * Creating Contexts::             Creating new @acronym{GPGME} contexts.
146 * Destroying Contexts::           Releasing @acronym{GPGME} contexts.
147 * Context Attributes::            Setting properties of a context.
148 * Key Management::                Managing keys with @acronym{GPGME}.
149 * Trust Item Management::         Managing trust items with @acronym{GPGME}.
150 * Crypto Operations::             Using a context for cryptography.
151 * Run Control::                   Controlling how operations are run.
152
153 Context Attributes
154
155 * Protocol Selection::            Selecting the protocol used by a context.
156 * ASCII Armor::                   Requesting @acronym{ASCII} armored output.
157 * Text Mode::                     Choosing canonical text mode.
158 * Included Certificates::         Including a number of certificates.
159 * Key Listing Mode::              Selecting key listing mode.
160 * Passphrase Callback::           Getting the passphrase from the user.
161 * Progress Meter Callback::       Being informed about the progress.
162
163 Key Management
164
165 * Listing Keys::                  Browsing the list of available keys.
166 * Information About Keys::        Requesting detailed information about keys.
167 * Key Signatures::                Listing the signatures on a key.
168 * Manipulating Keys::             Operations on keys.
169 * Generating Keys::               Creating new key pairs.
170 * Exporting Keys::                Retrieving key data from the key ring.
171 * Importing Keys::                Adding keys to the key ring.
172 * Deleting Keys::                 Removing keys from the key ring.
173
174 Trust Item Management
175
176 * Listing Trust Items::           Browsing the list of available trust items.
177 * Information About Trust Items:: Requesting information about trust items.
178 * Manipulating Trust Items::      Operations on trust items.
179
180 Crypto Operations
181
182 * Decrypt::                       Decrypting a ciphertext.
183 * Verify::                        Verifying a signature.
184 * Decrypt and Verify::            Decrypting a signed ciphertext.
185 * Sign::                          Creating a signature.
186 * Encrypt::                       Encrypting a plaintext.
187
188 Sign
189
190 * Selecting Signers::             How to choose the keys to sign with.
191 * Creating a Signature::          How to create a signature.
192
193 Encrypt
194
195 * Encrypting a Plaintext::        How to encrypt a plaintext.
196
197 Run Control
198
199 * Waiting For Completion::        Waiting until an operation is completed.
200 * Using External Event Loops::    Advanced control over what happens when.
201
202 Using External Event Loops
203
204 * I/O Callback Interface::        How I/O callbacks are registered.
205 * Registering I/O Callbacks::     How to use I/O callbacks for a context.
206 * I/O Callback Example::          An example how to use I/O callbacks.
207 * I/O Callback Example GTK+::     How to integrate @acronym{GPGME} in GTK+.
208 * I/O Callback Example GDK::      How to integrate @acronym{GPGME} in GDK.
209
210 @end detailmenu
211 @end menu
212
213 @node Introduction
214 @chapter Introduction
215
216 `GnuPG Made Easy' (@acronym{GPGME}) is a C language library that
217 allows to add support for cryptography to a program.  It is designed
218 to make access to public key crypto engines like GnuPG or GpgSM easier
219 for applications.  @acronym{GPGME} provides a high-level crypto API
220 for encryption, decryption, signing, signature verification and key
221 management.
222
223 @acronym{GPGME} uses GnuPG and GpgSM as its backends to support
224 OpenPGP and the Cryptographic Message Syntax (CMS).
225
226 @menu
227 * Getting Started::               Purpose of the manual, and how to use it.
228 * Features::                      Reasons to install and use @acronym{GPGME}.
229 * Overview::                      Basic architecture of the @acronym{GPGME} library.
230 @end menu
231
232
233 @node Getting Started
234 @section Getting Started
235
236 This manual documents the @acronym{GPGME} library programming
237 interface.  All functions and data types provided by the library are
238 explained.
239
240 The reader is assumed to possess basic knowledge about cryptography in
241 general, and public key cryptography in particular.  The underlying
242 cryptographic engines that are used by the library are not explained,
243 but where necessary, special features or requirements by an engine are
244 mentioned as far as they are relevant to @acronym{GPGME} or its users.
245
246 This manual can be used in several ways.  If read from the beginning
247 to the end, it gives a good introduction into the library and how it
248 can be used in an application.  Forward references are included where
249 necessary.  Later on, the manual can be used as a reference manual to
250 get just the information needed about any particular interface of the
251 library.  Experienced programmers might want to start looking at the
252 examples at the end of the manual, and then only read up those parts
253 of the interface which are unclear.
254
255
256 @node Features
257 @section Features
258
259 @acronym{GPGME} has a couple of advantages over other libraries doing
260 a similar job, and over implementing support for GnuPG or other crypto
261 engines into your application directly.
262
263 @table @asis
264 @item it's free software
265 Anybody can use, modify, and redistribute it under the terms of the GNU
266 General Public License (@pxref{Copying}).
267
268 @item it's flexible
269 @acronym{GPGME} provides transparent support for several cryptographic
270 protocols by different engines.  Currently, @acronym{GPGME} supports
271 the OpenPGP protocol using GnuPG as the backend, and the Cryptographic
272 Message Syntax using GpgSM as the backend.
273
274 @item it's easy
275 @acronym{GPGME} hides the differences between the protocols and
276 engines from the programmer behind an easy-to-use interface.  This way
277 the programmer can focus on the other parts of the program, and still
278 integrate strong cryptography in his application.  Once support for
279 @acronym{GPGME} has been added to a program, it is easy to add support
280 for other crypto protocols once @acronym{GPGME} backends provide them.
281 @end table
282
283
284 @node Overview
285 @section Overview
286
287 @acronym{GPGME} provides a data abstraction that is used to pass data
288 to the crypto engine, and receive returned data from it.  Data can be
289 read from memory or from files, but it can also be provided by a
290 callback function.
291
292 The actual cryptographic operations are always set within a context.
293 A context provides configuration parameters that define the behaviour
294 of all operations performed within it.  Only one operation per context
295 is allowed at any time, but when one operation is finished, you can
296 run the next operation in the same context.  There can be more than
297 one context, and all can run different operations at the same time.
298
299 Furthermore, @acronym{GPGME} has rich key management facilities
300 including listing keys, querying their attributes, generating,
301 importing, exporting and deleting keys, and acquiring information
302 about the trust path.
303
304 With some precautions, @acronym{GPGME} can be used in a multi-threaded
305 environment, although it is not completely thread safe and thus needs
306 the support of the application.
307
308
309 @node Preparation
310 @chapter Preparation
311
312 To use @acronym{GPGME}, you have to perform some changes to your
313 sources and the build system.  The necessary changes are small and
314 explained in the following sections.  At the end of this chapter, it
315 is described how the library is initialized, and how the requirements
316 of the library are verified.
317
318 @menu
319 * Header::                        What header file you need to include.
320 * Building the Source::           Compiler options to be used.
321 * Using Automake::                Compiler options to be used the easy way.
322 * Using Libtool::                 Avoiding compiler options entirely.
323 * Library Version Check::         Getting and verifying the library version.
324 * Multi Threading::               How @acronym{GPGME} can be used in an MT environment.
325 @end menu
326
327
328 @node Header
329 @section Header
330 @cindex header file
331 @cindex include file
332
333 All interfaces (data types and functions) of the library are defined
334 in the header file `gpgme.h'.  You must include this in all programs
335 using the library, either directly or through some other header file,
336 like this:
337
338 @example
339 #include <gpgme.h>
340 @end example
341
342 The name space of @acronym{GPGME} is @code{gpgme_*} for function names
343 and data types and @code{GPGME_*} for other symbols.  Symbols internal
344 to @acronym{GPGME} take the form @code{_gpgme_*} and @code{_GPGME_*}.
345
346 Because @acronym{GPGME} makes use of the GPG Error library, using
347 @acronym{GPGME} will also use the @code{GPG_ERR_*} name space
348 directly, and the @code{gpg_err*} and @code{gpg_str*} name space
349 indirectly.
350
351
352 @node Building the Source
353 @section Building the Source
354 @cindex compiler options
355 @cindex compiler flags
356
357 If you want to compile a source file including the `gpgme.h' header
358 file, you must make sure that the compiler can find it in the
359 directory hierarchy.  This is accomplished by adding the path to the
360 directory in which the header file is located to the compilers include
361 file search path (via the @option{-I} option).
362
363 However, the path to the include file is determined at the time the
364 source is configured.  To solve this problem, gpgme ships with a small
365 helper program @command{gpgme-config} that knows about the path to the
366 include file and other configuration options.  The options that need
367 to be added to the compiler invocation at compile time are output by
368 the @option{--cflags} option to @command{gpgme-config}.  The following
369 example shows how it can be used at the command line:
370
371 @example
372 gcc -c foo.c `gpgme-config --cflags`
373 @end example
374
375 Adding the output of @samp{gpgme-config --cflags} to the compiler
376 command line will ensure that the compiler can find the
377 @acronym{GPGME} header file.
378
379 A similar problem occurs when linking the program with the library.
380 Again, the compiler has to find the library files.  For this to work,
381 the path to the library files has to be added to the library search
382 path (via the @option{-L} option).  For this, the option
383 @option{--libs} to @command{gpgme-config} can be used.  For
384 convenience, this option also outputs all other options that are
385 required to link the program with @acronym{GPGME} (in particular, the
386 @samp{-lgpgme} option).  The example shows how to link @file{foo.o}
387 with the @acronym{GPGME} library to a program @command{foo}.
388
389 @example
390 gcc -o foo foo.o `gpgme-config --libs`
391 @end example
392
393 Of course you can also combine both examples to a single command by
394 specifying both options to @command{gpgme-config}:
395
396 @example
397 gcc -o foo foo.c `gpgme-config --cflags --libs`
398 @end example
399
400 If you want to link to one of the thread-safe versions of
401 @acronym{GPGME}, you must specify the @option{--thread} option before
402 any other option to select the thread package you want to link with.
403 Supported thread packages are @option{--thread=pth} and
404 @option{--thread=pthread}.
405
406
407 @node Using Automake
408 @section Using Automake
409 @cindex automake
410 @cindex autoconf
411
412 It is much easier if you use GNU Automake instead of writing your own
413 Makefiles.  If you do that you do not have to worry about finding and
414 invoking the @command{gpgme-config} script at all.  @acronym{GPGME}
415 provides an extension to Automake that does all the work for you.
416
417 @c A simple macro for optional variables.
418 @macro ovar{varname}
419 @r{[}@var{\varname\}@r{]}
420 @end macro
421 @defmac AM_PATH_GPGME (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
422 @defmacx AM_PATH_GPGME_PTH (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
423 @defmacx AM_PATH_GPGME_PTHREAD (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
424 Check whether @acronym{GPGME} (at least version @var{minimum-version},
425 if given) exists on the host system.  If it is found, execute
426 @var{action-if-found}, otherwise do @var{action-if-not-found}, if
427 given.
428
429 Additionally, the function defines @code{GPGME_CFLAGS} to the flags
430 needed for compilation of the program to find the @file{gpgme.h}
431 header file, and @code{GPGME_LIBS} to the linker flags needed to link
432 the program to the @acronym{GPGME} library.
433
434 @code{AM_PATH_GPGME_PTH} checks for the version of @acronym{GPGME}
435 that can be used with GNU Pth, and defines @code{GPGME_PTH_CFLAGS} and
436 @code{GPGME_PTH_LIBS}.
437
438 @code{AM_PATH_GPGME_PTHREAD} checks for the version of @acronym{GPGME}
439 that can be used with the native pthread implementation, and defines
440 @code{GPGME_PTHREAD_CFLAGS} and @code{GPGME_PTHREAD_LIBS}.
441 @end defmac
442
443 You can use the defined Autoconf variables like this in your
444 @file{Makefile.am}:
445
446 @example
447 AM_CPPFLAGS = $(GPGME_CFLAGS)
448 LDADD = $(GPGME_LIBS)
449 @end example
450
451
452 @node Using Libtool
453 @section Using Libtool
454 @cindex libtool
455
456 The easiest way is to just use GNU Libtool.  If you use libtool, and
457 link to @code{libgpgme.la}, @code{libgpgme-pth.la} or
458 @code{libgpgme-pthread.la} respectively, everything will be done
459 automatically by Libtool.
460
461
462 @node Library Version Check
463 @section Library Version Check
464 @cindex version check, of the library
465
466 @deftypefun {const char *} gpgme_check_version (@w{const char *@var{required_version}})
467 The function @code{gpgme_check_version} has three purposes.  It can be
468 used to retrieve the version number of the library.  In addition it
469 can verify that the version number is higher than a certain required
470 version number.  In either case, the function initializes some
471 sub-systems, and for this reason alone it must be invoked early in
472 your program, before you make use of the other functions in
473 @acronym{GPGME}.
474
475 If @var{required_version} is @code{NULL}, the function returns a
476 pointer to a statically allocated string containing the version number
477 of the library.
478
479 If @var{required_version} is not @code{NULL}, it should point to a
480 string containing a version number, and the function checks that the
481 version of the library is at least as high as the version number
482 provided.  In this case, the function returns a pointer to a
483 statically allocated string containing the version number of the
484 library.  If @var{REQUIRED_VERSION} is not a valid version number, or
485 if the version requirement is not met, the function returns
486 @code{NULL}.
487
488 If you use a version of a library that is backwards compatible with
489 older releases, but contains additional interfaces which your program
490 uses, this function provides a run-time check if the necessary
491 features are provided by the installed version of the library.
492 @end deftypefun
493
494
495 @node Multi Threading
496 @section Multi Threading
497 @cindex thread-safeness
498 @cindex multi-threading
499
500 The @acronym{GPGME} library is not entirely thread-safe, but it can
501 still be used in a multi-threaded environment if some care is taken.
502 If the following requirements are met, there should be no race
503 conditions to worry about:
504
505 @itemize @bullet
506 @item
507 @acronym{GPGME} supports the thread libraries pthread and GNU Pth.
508 The support for this has to be enabled at compile time.
509 @acronym{GPGME} will automatically detect the location in which the
510 thread libraries are installed and activate the support for them at
511 build time.
512
513 Support for other thread libraries is very easy to add.  Please
514 contact us if you have the need.
515
516 @item
517 If you link your program dynamically to @acronym{GPGME} and your
518 supported thread library, @acronym{GPGME} will automatically detect
519 the presence of this library and activate its use.  You must link to
520 the thread library before linking to @acronym{GPGME}.  If you link to
521 both pthread and GNU Pth, @acronym{GPGME} will use the pthread
522 support.  This feature requires weak symbol support.
523
524 @item
525 If you link your program statically to @acronym{GPGME}, or your system
526 does not support weak symbols, there is currently no easy way to make
527 sure that @acronym{GPGME} detects the presence of the thread library.
528 This will be solved in a future version.
529
530 @item
531 The function @code{gpgme_check_version} must be called before any
532 other function in the library, because it initializes the thread
533 support subsystem in @acronym{GPGME}.  To achieve this in all
534 generality, it is necessary to synchronize the call to this function
535 with all other calls to functions in the library, using the
536 synchronization mechanisms available in your thread library.
537 Otherwise, specific compiler or CPU memory cache optimizations could
538 lead to the situation where a thread is started and uses
539 @acronym{GPGME} before the effects of the initialization are visible
540 for this thread.  It doesn't even suffice to call
541 @code{gpgme_check_version} before creating this other
542 thread@footnote{In SMP systems the new thread could be started on
543 another CPU before the effects of the initialization are seen by that
544 CPU's memory cache.  Not doing proper synchronization here leads to
545 the same problems the double-checked locking idiom has.  You might
546 find that if you don't do proper synchronization, it still works in
547 most configurations.  Don't let this fool you.  Someday it might lead
548 to subtle bugs when someone tries it on a DEC Alpha or an SMP
549 machine.}.
550
551 For example, if you are using POSIX threads, each thread that wants to
552 call functions in @acronym{GPGME} could call the following function
553 before any function in the library:
554
555 @example
556 #include <pthread.h>
557
558 void
559 initialize_gpgme (void)
560 @{
561   static int gpgme_init;
562   static pthread_mutext_t gpgme_init_lock = PTHREAD_MUTEX_INITIALIZER;
563
564   pthread_mutex_lock (&gpgme_init_lock);
565   if (!gpgme_init)
566     @{
567       gpgme_check_version ();
568       gpgme_init = 1;
569     @}
570   pthread_mutex_unlock (&gpgme_init_lock);
571 @}
572 @end example
573
574 @item
575 Any @code{gpgme_data_t} and @code{gpgme_ctx_t} object must only be
576 accessed by one thread at a time.  If multiple threads want to deal
577 with the same object, the caller has to make sure that operations on
578 that object are fully synchronized.
579
580 @item
581 Only one thread at any time is allowed to call @code{gpgme_wait}.  If
582 multiple threads call this function, the caller must make sure that
583 all invocations are fully synchronized.  It is safe to start
584 asynchronous operations while a thread is running in gpgme_wait.
585 @end itemize
586
587
588 @node Protocols and Engines
589 @chapter Protocols and Engines
590 @cindex protocol
591 @cindex engine
592 @cindex crypto engine
593 @cindex backend
594 @cindex crypto backend
595
596 @acronym{GPGME} supports several cryptographic protocols, however, it
597 does not implement them.  Rather it uses backends (also called
598 engines) which implement the protocol.  @acronym{GPGME} uses
599 inter-process communication to pass data back and forth between the
600 application and the backend, but the details of the communication
601 protocol and invocation of the backend is completely hidden by the
602 interface.  All complexity is handled by @acronym{GPGME}.  Where an
603 exchange of information between the application and the backend is
604 necessary, @acronym{GPGME} provides the necessary callback function
605 hooks and further interfaces.
606
607 @deftp {Data type} {enum gpgme_protocol_t}
608 @tindex gpgme_protocol_t
609 The @code{gpgme_protocol_t} type specifies the set of possible protocol
610 values that are supported by @acronym{GPGME}.  The following protocols
611 are supported:
612
613 @table @code
614 @item GPGME_PROTOCOL_OpenPGP
615 This specifies the OpenPGP protocol.
616
617 @item GPGME_PROTOCOL_CMS
618 This specifies the Cryptographic Message Syntax.
619 @end table
620 @end deftp
621
622
623 @deftypefun const char *gpgme_get_protocol_name (@w{gpgme_protocol_t @var{protocol}})
624 The function @code{gpgme_get_protocol_name} returns a statically
625 allocated string describing the protocol @var{protocol}, or
626 @code{NULL} if the protocol number is not valid.
627 @end deftypefun
628
629 @menu
630 * Engine Version Check::          Verifying the engine version.
631 * Engine Information::            Obtaining more information about the engines.
632 * OpenPGP::                       Support for the OpenPGP protocol.
633 * Cryptographic Message Syntax::  Support for the CMS.
634 @end menu
635
636
637 @node Engine Version Check
638 @section Engine Version Check
639 @cindex version check, of the engines
640
641 @deftypefun gpgme_error_t gpgme_engine_check_version (@w{gpgme_protocol_t @var{protocol}})
642 The function @code{gpgme_engine_check_version} verifies that the
643 engine implementing the protocol @var{PROTOCOL} is installed in the
644 expected path and meets the version requirement of @acronym{GPGME}.
645
646 This function returns the error code @code{GPG_ERR_NO_ERROR} if the
647 engine is available and @code{GPG_ERR_INV_ENGINE} if it is not.
648 @end deftypefun
649
650
651 @node Engine Information
652 @section Engine Information
653 @cindex engine, information about
654
655 @deftp {Data type} {gpgme_engine_info_t}
656 @tindex gpgme_protocol_t
657 The @code{gpgme_engine_info_t} type specifies a pointer to a structure
658 describing a crypto engine.  The structure contains the following
659 elements:
660
661 @table @code
662 @item gpgme_engine_info_t next
663 This is a pointer to the next engine info structure in the linked
664 list, or @code{NULL} if this is the last element.
665
666 @item gpgme_protocol_t protocol
667 This is the protocol for which the crypto engine is used.  You can
668 convert this to a string with @code{gpgme_get_protocol_name} for
669 printing.
670
671 @item const char *file_name
672 This is a string holding the file name of the executable of the crypto
673 engine.  Currently, it is never @code{NULL}, but using @code{NULL} is
674 reserved for future use, so always check before you use it.
675
676 @item const char *version
677 This is a string containing the version number of the crypto engine.
678 It might be @code{NULL} if the version number can not be determined,
679 for example because the executable doesn't exist or is invalid.
680
681 @item const char *req_version
682 This is a string containing the minimum required version number of the
683 crypto engine for @acronym{GPGME} to work correctly.  This is the
684 version number that @code{gpgme_engine_check_version} verifies
685 against.  Currently, it is never @code{NULL}, but using @code{NULL} is
686 reserved for future use, so always check before you use it.
687 @end table
688 @end deftp
689
690 @deftypefun gpgme_error_t gpgme_get_engine_info (gpgme_engine_info_t *info)
691 The function @code{gpgme_get_engine_info} returns a linked list of
692 engine info structures in @var{info}.  Each info structure describes
693 one configured backend.
694
695 The memory for the info structures is allocated the first time this
696 function is invoked, and must not be freed by the caller.
697
698 This function returns the error code @code{GPG_ERR_NO_ERROR} if
699 successful, and a system error if the memory could not be allocated.
700 @end deftypefun
701
702 Here is an example how you can provide more diagnostics if you receive
703 an error message which indicates that the crypto engine is invalid.
704
705 @example
706 gpgme_ctx_t ctx;
707 gpgme_error_t err;
708
709 [...]
710
711 if (gpgme_err_code (err) == GPG_ERR_INV_ENGINE)
712   @{
713     gpgme_engine_info_t info;
714     err = gpgme_get_engine_info (&info);
715     if (!err)
716       @{
717         while (info && info->protocol != gpgme_get_protocol (ctx))
718           info = info->next;
719         if (!info)
720           fprintf (stderr, "GPGME compiled without support for protocol %s",
721                    gpgme_get_protocol_name (info->protocol));
722         else if (info->path && !info->version)
723           fprintf (stderr, "Engine %s not installed properly",
724                    info->path);
725         else if (info->path && info->version && info->req_version)
726           fprintf (stderr, "Engine %s version %s installed, "
727                    "but at least version %s required", info->path,
728                    info->version, info->req_version);
729         else
730           fprintf (stderr, "Unknown problem with engine for protocol %s",
731                    gpgme_get_protocol_name (info->protocol));
732       @}
733   @}
734 @end example
735
736
737 @node OpenPGP
738 @section OpenPGP
739 @cindex OpenPGP
740 @cindex GnuPG
741 @cindex protocol, GnuPG
742 @cindex engine, GnuPG
743
744 OpenPGP is implemented by GnuPG, the @acronym{GNU} Privacy Guard.
745 This is the first protocol that was supported by @acronym{GPGME}.
746
747 The OpenPGP protocol is specified by @code{GPGME_PROTOCOL_OpenPGP}.
748
749
750 @node Cryptographic Message Syntax
751 @section Cryptographic Message Syntax
752 @cindex CMS
753 @cindex cryptographic message syntax
754 @cindex GpgSM
755 @cindex protocol, CMS
756 @cindex engine, GpgSM
757 @cindex S/MIME
758 @cindex protocol, S/MIME
759
760 @acronym{CMS} is implemented by GpgSM, the S/MIME implementation for
761 GnuPG.
762
763 The @acronym{CMS} protocol is specified by @code{GPGME_PROTOCOL_CMS}.
764
765
766 @node Algorithms
767 @chapter Algorithms
768 @cindex algorithms
769
770 The crypto backends support a variety of algorithms used in public key
771 cryptography.  The following sections list the identifiers used to
772 denote such an algorithm.
773
774 @menu
775 * Public Key Algorithms::         A list of all public key algorithms.
776 * Hash Algorithms::               A list of all hash algorithms.
777 @end menu
778
779
780 @node Public Key Algorithms
781 @section Public Key Algorithms
782 @cindex algorithms, public key
783 @cindex public key algorithms
784
785 Public key algorithms are used for encryption, decryption, signing and
786 verification of signatures.
787
788 @deftp {Data type} {enum gpgme_pubkey_algo_t}
789 @tindex gpgme_pubkey_algo_t
790 The @code{gpgme_pubkey_algo_t} type specifies the set of all public key
791 algorithms that are supported by @acronym{GPGME}.  Possible values
792 are:
793
794 @table @code
795 @item GPGME_PK_RSA
796 This value indicates the RSA (Rivest, Shamir, Adleman) algorithm.
797
798 @item GPGME_PK_RSA_E
799 Deprecated.  This value indicates the RSA (Rivest, Shamir, Adleman)
800 algorithm for encryption and decryption only.
801
802 @item GPGME_PK_RSA_S
803 Deprecated.  This value indicates the RSA (Rivest, Shamir, Adleman)
804 algorithm for signing and verification only.
805
806 @item GPGME_PK_DSA
807 This value indicates DSA, the Digital Signature Algorithm.
808
809 @item GPGME_PK_ELG
810 This value indicates ElGamal.
811
812 @item GPGME_PK_ELG_E
813 This value also indicates ElGamal and is used specifically in GnuPG.
814 @end table
815 @end deftp
816
817 @deftypefun {const char *} gpgme_pubkey_algo_name (@w{gpgme_pubkey_algo_t @var{algo}})
818 The function @code{gpgme_pubkey_algo_name} returns a pointer to a
819 statically allocated string containing a description of the public key
820 algorithm @var{algo}.  This string can be used to output the name of
821 the public key algorithm to the user.
822
823 If @var{algo} is not a valid public key algorithm, @code{NULL} is
824 returned.
825 @end deftypefun
826
827
828 @node Hash Algorithms
829 @section Hash Algorithms
830 @cindex algorithms, hash
831 @cindex algorithms, message digest
832 @cindex hash algorithms
833 @cindex message digest algorithms
834
835 Hash (message digest) algorithms are used to compress a long message
836 to make it suitable for public key cryptography.
837
838 @deftp {Data type} {enum gpgme_hash_algo_t}
839 @tindex gpgme_hash_algo_t
840 The @code{gpgme_hash_algo_t} type specifies the set of all hash algorithms
841 that are supported by @acronym{GPGME}.  Possible values are:
842
843 @table @code
844 @item GPGME_MD_MD5
845 @item GPGME_MD_SHA1
846 @item GPGME_MD_RMD160
847 @item GPGME_MD_MD2
848 @item GPGME_MD_TIGER
849 @item GPGME_MD_HAVAL
850 @item GPGME_MD_SHA256
851 @item GPGME_MD_SHA384
852 @item GPGME_MD_SHA512
853 @item GPGME_MD_MD4
854 @item GPGME_MD_CRC32
855 @item GPGME_MD_CRC32_RFC1510
856 @item GPGME_MD_CRC24_RFC2440
857 @end table
858 @end deftp
859
860 @deftypefun {const char *} gpgme_hash_algo_name (@w{gpgme_hash_algo_t @var{algo}})
861 The function @code{gpgme_hash_algo_name} returns a pointer to a
862 statically allocated string containing a description of the hash
863 algorithm @var{algo}.  This string can be used to output the name of
864 the hash algorithm to the user.
865
866 If @var{algo} is not a valid hash algorithm, @code{NULL} is returned.
867 @end deftypefun
868
869
870 @node Error Handling
871 @chapter Error Handling
872 @cindex error handling
873
874 Many functions in @acronym{GPGME} can return an error if they fail.
875 For this reason, the application should always catch the error
876 condition and take appropriate measures, for example by releasing the
877 resources and passing the error up to the caller, or by displaying a
878 descriptive message to the user and cancelling the operation.
879
880 Some error values do not indicate a system error or an error in the
881 operation, but the result of an operation that failed properly.  For
882 example, if you try to decrypt a tempered message, the decryption will
883 fail.  Another error value actually means that the end of a data
884 buffer or list has been reached.  The following descriptions explain
885 for many error codes what they mean usually.  Some error values have
886 specific meanings if returned by a certain functions.  Such cases are
887 described in the documentation of those functions.
888
889 @acronym{GPGME} uses the @code{libgpg-error} library.  This allows to
890 share the error codes with other components of the GnuPG system, and
891 thus pass error values transparently from the crypto engine, or some
892 helper application of the crypto engine, to the user.  This way no
893 information is lost.  As a consequence, @acronym{GPGME} does not use
894 its own identifiers for error codes, but uses those provided by
895 @code{libgpg-error}.  They usually start with @code{GPG_ERR_}.
896
897 However, @acronym{GPGME} does provide aliases for the functions
898 defined in libgpg-error, which might be preferred for name space
899 consistency.
900
901 @menu
902 * Error Values::                  The error value and what it means.
903 * Error Sources::                 A list of important error sources.
904 * Error Codes::                   A list of important error codes.
905 * Error Strings::                 How to get a descriptive string from a value.
906 @end menu
907
908
909 @node Error Values
910 @section Error Values
911 @cindex error values
912 @cindex error codes
913 @cindex error sources
914
915 @deftp {Data type} {gpgme_err_code_t}
916 The @code{gpgme_err_code_t} type is an alias for the @code{libgpg-error}
917 type @code{gpg_err_code_t}.  The error code indicates the type of an
918 error, or the reason why an operation failed.
919
920 A list of important error codes can be found in the next section.
921 @end deftp
922
923 @deftp {Data type} {gpgme_err_source_t}
924 The @code{gpgme_err_source_t} type is an alias for the
925 @code{libgpg-error} type @code{gpg_err_source_t}.  The error source
926 has not a precisely defined meaning.  Sometimes it is the place where
927 the error happened, sometimes it is the place where an error was
928 encoded into an error value.  Usually the error source will give an
929 indication to where to look for the problem.  This is not always true,
930 but it is attempted to achieve this goal.
931
932 A list of important error sources can be found in the next section.
933 @end deftp
934
935 @deftp {Data type} {gpgme_error_t}
936 The @code{gpgme_error_t} type is an alias for the @code{libgpg-error}
937 type @code{gpg_error_t}.  An error value like this has always two
938 components, an error code and an error source.  Both together form the
939 error value.
940
941 Thus, the error value can not be directly compared against an error
942 code, but the accessor functions described below must be used.
943 However, it is guaranteed that only 0 is used to indicate success
944 (@code{GPG_ERR_NO_ERROR}), and that in this case all other parts of
945 the error value are set to 0, too.
946
947 Note that in @acronym{GPGME}, the error source is used purely for
948 diagnostical purposes.  Only the error code should be checked to test
949 for a certain outcome of a function.  The manual only documents the
950 error code part of an error value.  The error source is left
951 unspecified and might be anything.
952 @end deftp
953
954 @deftypefun {static __inline__ gpgme_err_code_t} gpgme_err_code (@w{gpgme_error_t @var{err}})
955 The static inline function @code{gpgme_err_code} returns the
956 @code{gpgme_err_code_t} component of the error value @var{err}.  This
957 function must be used to extract the error code from an error value in
958 order to compare it with the @code{GPG_ERR_*} error code macros.
959 @end deftypefun
960
961 @deftypefun {static __inline__ gpgme_err_source_t} gpgme_err_source (@w{gpgme_error_t @var{err}})
962 The static inline function @code{gpgme_err_source} returns the
963 @code{gpgme_err_source_t} component of the error value @var{err}.  This
964 function must be used to extract the error source from an error value in
965 order to compare it with the @code{GPG_ERR_SOURCE_*} error source macros.
966 @end deftypefun
967
968 @deftypefun {static __inline__ gpgme_error_t} gpgme_err_make (@w{gpgme_err_source_t @var{source}}, @w{gpgme_err_code_t @var{code}})
969 The static inline function @code{gpgme_err_make} returns the error
970 value consisting of the error source @var{source} and the error code
971 @var{code}.
972
973 This function can be used in callback functions to construct an error
974 value to return it to the library.
975 @end deftypefun
976
977 @deftypefun {static __inline__ gpgme_error_t} gpgme_error (@w{gpgme_err_code_t @var{code}})
978 The static inline function @code{gpgme_error} returns the error value
979 consisting of the default error source and the error code @var{code}.
980
981 For @acronym{GPGME} applications, the default error source is
982 @code{GPG_ERR_SOURCE_USER_1}.  You can define
983 @code{GPGME_ERR_SOURCE_DEFAULT} before including @file{gpgme.h} to
984 change this default.
985
986 This function can be used in callback functions to construct an error
987 value to return it to the library.
988 @end deftypefun
989
990 The @code{libgpg-error} library provides error codes for all system
991 error numbers it knows about.  If @var{err} is an unknown error
992 number, the error code @code{GPG_ERR_UNKNOWN_ERRNO} is used.  The
993 following functions can be used to construct error values from system
994 errnor numbers.
995
996 @deftypefun {gpgme_error_t} gpgme_err_make_from_errno (@w{gpgme_err_source_t @var{source}}, @w{int @var{err}})
997 The function @code{gpgme_err_make_from_errno} is like
998 @code{gpgme_err_make}, but it takes a system error like @code{errno}
999 instead of a @code{gpgme_err_code_t} error code.
1000 @end deftypefun
1001
1002 @deftypefun {gpgme_error_t} gpgme_error_from_errno (@w{int @var{err}})
1003 The function @code{gpgme_error_from_errno} is like @code{gpgme_error},
1004 but it takes a system error like @code{errno} instead of a
1005 @code{gpgme_err_code_t} error code.
1006 @end deftypefun
1007
1008 Sometimes you might want to map system error numbers to error codes
1009 directly, or map an error code representing a system error back to the
1010 system error number.  The following functions can be used to do that.
1011
1012 @deftypefun {gpgme_err_code_t} gpgme_err_code_from_errno (@w{int @var{err}})
1013 The function @code{gpgme_err_code_from_errno} returns the error code
1014 for the system error @var{err}.  If @var{err} is not a known system
1015 error, the function returns @code{GPG_ERR_UNKNOWN_ERRNO}.
1016 @end deftypefun
1017
1018 @deftypefun {int} gpgme_err_code_to_errno (@w{gpgme_err_code_t @var{err}})
1019 The function @code{gpgme_err_code_to_errno} returns the system error
1020 for the error code @var{err}.  If @var{err} is not an error code
1021 representing a system error, or if this system error is not defined on
1022 this system, the function returns @code{0}.
1023 @end deftypefun
1024
1025
1026 @node Error Sources
1027 @section Error Sources
1028 @cindex error codes, list of
1029
1030 The library @code{libgpg-error} defines an error source for every
1031 component of the GnuPG system.  The error source part of an error
1032 value is not well defined.  As such it is mainly useful to improve the
1033 diagnostic error message for the user.
1034
1035 If the error code part of an error value is @code{0}, the whole error
1036 value will be @code{0}.  In this case the error source part is of
1037 course @code{GPG_ERR_SOURCE_UNKNOWN}.
1038
1039 The list of error sources that might occur in applications using
1040 @acronym{GPGME} is:
1041
1042 @table @code
1043 @item GPG_ERR_SOURCE_UNKNOWN
1044 The error source is not known.  The value of this error source is
1045 @code{0}.
1046
1047 @item GPG_ERR_SOURCE_GPGME
1048 The error source is @acronym{GPGME} itself.  This is the default for
1049 errors that occur in the @acronym{GPGME} library.
1050
1051 @item GPG_ERR_SOURCE_GPG
1052 The error source is GnuPG, which is the crypto engine used for the
1053 OpenPGP protocol.
1054
1055 @item GPG_ERR_SOURCE_GPGSM
1056 The error source is GPGSM, which is the crypto engine used for the
1057 CMS protocol.
1058
1059 @item GPG_ERR_SOURCE_GCRYPT
1060 The error source is @code{libgcrypt}, which is used by crypto engines
1061 to perform cryptographic operations.
1062
1063 @item GPG_ERR_SOURCE_GPGAGENT
1064 The error source is @command{gpg-agent}, which is used by crypto
1065 engines to perform operations with the secret key.
1066
1067 @item GPG_ERR_SOURCE_PINENTRY
1068 The error source is @command{pinentry}, which is used by
1069 @command{gpg-agent} to query the passphrase to unlock a secret key.
1070
1071 @item GPG_ERR_SOURCE_SCD
1072 The error source is the SmartCard Daemon, which is used by
1073 @command{gpg-agent} to delegate operations with the secret key to a
1074 SmartCard.
1075
1076 @item GPG_ERR_SOURCE_KEYBOX
1077 The error source is @code{libkbx}, a library used by the crypto
1078 engines to manage local keyrings.
1079
1080 @item GPG_ERR_SOURCE_USER_1
1081 @item GPG_ERR_SOURCE_USER_2
1082 @item GPG_ERR_SOURCE_USER_3
1083 @item GPG_ERR_SOURCE_USER_4
1084 These error sources are not used by any GnuPG component and can be
1085 used by other software.  For example, applications using
1086 @acronym{GPGME} can use them to mark error values coming from callback
1087 handlers.  Thus @code{GPG_ERR_SOURCE_USER_1} is the default for errors
1088 created with @code{gpgme_error} and @code{gpgme_error_from_errno},
1089 unless you define @code{GPGME_ERR_SOURCE_DEFAULT} before including
1090 @file{gpgme.h}.
1091 @end table
1092
1093
1094 @node Error Codes
1095 @section Error Codes
1096 @cindex error codes, list of
1097
1098 The library @code{libgpg-error} defines many error values.  Most of
1099 them are not used by @code{GPGME} directly, but might be returned by
1100 @acronym{GPGME} because it received them from the crypto engine.  The
1101 below list only includes such error codes that have a specific meaning
1102 in @code{GPGME}, or which are so common that you should know about
1103 them.
1104
1105 @table @code
1106 @item GPG_ERR_EOF
1107 This value indicates the end of a list, buffer or file.
1108
1109 @item GPG_ERR_NO_ERROR
1110 This value indicates success.  The value of this error code is
1111 @code{0}.  Also, it is guaranteed that an error value made from the
1112 error code @code{0} will be @code{0} itself (as a whole).  This means
1113 that the error source information is lost for this error code,
1114 however, as this error code indicates that no error occured, this is
1115 generally not a problem.
1116
1117 @item GPG_ERR_GENERAL
1118 This value means that something went wrong, but either there is not
1119 enough information about the problem to return a more useful error
1120 value, or there is no separate error value for this type of problem.
1121
1122 @item GPG_ERR_ENOMEM
1123 This value means that an out-of-memory condition occurred.
1124
1125 @item GPG_ERR_E...
1126 System errors are mapped to GPG_ERR_FOO where FOO is the symbol for
1127 the system error.
1128
1129 @item GPG_ERR_INV_VALUE
1130 This value means that some user provided data was out of range.  This
1131 can also refer to objects.  For example, if an empty
1132 @code{gpgme_data_t} object was expected, but one containing data was
1133 provided, this error value is returned.
1134
1135 @item GPG_ERR_UNUSABLE_PUBKEY
1136 This value means that some recipients for a message were invalid.
1137
1138 @item GPG_ERR_UNUSABLE_SECKEY
1139 This value means that some signers were invalid.
1140
1141 @item GPG_ERR_NO_DATA
1142 This value means that a @code{gpgme_data_t} object which was expected
1143 to have content was found empty.
1144
1145 @item GPG_ERR_CONFLICT
1146 This value means that a conflict of some sort occurred.
1147
1148 @item GPG_ERR_NOT_IMPLEMENTED
1149 This value indicates that the specific function (or operation) is not
1150 implemented.  This error should never happen.  It can only occur if
1151 you use certain values or configuration options which do not work,
1152 but for which we think that they should work at some later time.
1153
1154 @item GPG_ERR_DECRYPT_FAILED
1155 This value indicates that a decryption operation was unsuccessful.
1156
1157 @item GPG_ERR_BAD_PASSPHRASE
1158 This value means that the user did not provide a correct passphrase
1159 when requested.
1160
1161 @item GPG_ERR_CANCELED
1162 This value means that the operation was canceled.
1163
1164 @item GPG_ERR_INV_ENGINE
1165 This value means that the engine that implements the desired protocol
1166 is currently not available.  This can either be because the sources
1167 were configured to exclude support for this engine, or because the
1168 engine is not installed properly.
1169
1170 @item GPG_ERR_AMBIGUOUS_NAME
1171 This value indicates that a user ID or other specifier did not specify
1172 a unique key.
1173
1174 @item GPG_ERR_WRONG_KEY_USAGE
1175 This value indicates that a key is not used appropriately.
1176
1177 @item GPG_ERR_CERT_REVOKED
1178 This value indicates that a key signature was revoced.
1179
1180 @item GPG_ERR_CERT_EXPIRED
1181 This value indicates that a key signature expired.
1182
1183 @item GPG_ERR_NO_CRL_KNOWN
1184 This value indicates that no certificate revocation list is known for
1185 the certificate.
1186
1187 @item GPG_ERR_NO_POLICY_MATCH
1188 This value indicates that a policy issue occured.
1189
1190 @item GPG_ERR_NO_SECKEY
1191 This value indicates that no secret key for the user ID is available.
1192
1193 @item GPG_ERR_MISSING_CERT
1194 This value indicates that a key could not be imported because the
1195 issuer certificate is missing.
1196
1197 @item GPG_ERR_BAD_CERT_CHAIN
1198 This value indicates that a key could not be imported because its
1199 certificate chain is not good, for example it could be too long.
1200
1201 @item GPG_ERR_UNSUPPORTED_ALGORITHM
1202 This value means a verification failed because the cryptographic
1203 algorithm is not supported by the crypto backend.
1204
1205 @item GPG_ERR_BAD_SIGNATURE
1206 This value means a verification failed because the signature is bad.
1207
1208 @item GPG_ERR_NO_PUBKEY
1209 This value means a verification failed because the public key is not
1210 available.
1211
1212 @item GPG_ERR_USER_1
1213 @item GPG_ERR_USER_2
1214 @item ...
1215 @item GPG_ERR_USER_16
1216 These error codes are not used by any GnuPG component and can be
1217 freely used by other software.  Applications using @acronym{GPGME}
1218 might use them to mark specific errors returned by callback handlers
1219 if no suitable error codes (including the system errors) for
1220 these errors exist already.
1221 @end table
1222
1223
1224 @node Error Strings
1225 @section Error Strings
1226 @cindex error values, printing of
1227 @cindex error codes, printing of
1228 @cindex error sources, printing of
1229 @cindex error strings
1230
1231 @deftypefun {const char *} gpgme_strerror (@w{gpgme_error_t @var{err}})
1232 The function @code{gpgme_strerror} returns a pointer to a statically
1233 allocated string containing a description of the error code contained
1234 in the error value @var{err}.  This string can be used to output a
1235 diagnostic message to the user.
1236 @end deftypefun
1237
1238
1239 @deftypefun {const char *} gpgme_strsource (@w{gpgme_error_t @var{err}})
1240 The function @code{gpgme_strerror} returns a pointer to a statically
1241 allocated string containing a description of the error source
1242 contained in the error value @var{err}.  This string can be used to
1243 output a diagnostic message to the user.
1244 @end deftypefun
1245
1246 The following example illustrates the use of @code{gpgme_strerror}:
1247
1248 @example
1249 gpgme_ctx_t ctx;
1250 gpgme_error_t err = gpgme_new (&ctx);
1251 if (err)
1252   @{
1253     fprintf (stderr, "%s: creating GpgME context failed: %s: %s\n",
1254              argv[0], gpgme_strsource (err), gpgme_strerror (err));
1255     exit (1);
1256   @}
1257 @end example
1258
1259
1260 @node Exchanging Data
1261 @chapter Exchanging Data
1262 @cindex data, exchanging
1263
1264 A lot of data has to be exchanged between the user and the crypto
1265 engine, like plaintext messages, ciphertext, signatures and
1266 information about the keys.  The technical details about exchanging
1267 the data information are completely abstracted by @acronym{GPGME}.
1268 The user provides and receives the data via @code{gpgme_data_t} objects,
1269 regardless of the communication protocol between @acronym{GPGME} and
1270 the crypto engine in use.
1271
1272 @deftp {Data type} {gpgme_data_t}
1273 The @code{gpgme_data_t} type is a handle for a container for generic
1274 data, which is used by @acronym{GPGME} to exchange data with the user.
1275 @end deftp
1276
1277 @menu
1278 * Creating Data Buffers::         Creating new data buffers.
1279 * Destroying Data Buffers::       Releasing data buffers.
1280 * Manipulating Data Buffers::     Operations on data buffers.
1281 @end menu
1282
1283
1284 @node Creating Data Buffers
1285 @section Creating Data Buffers
1286 @cindex data buffer, creation
1287
1288 Data objects can be based on memory, files, or callback functions
1289 provided by the user.  Not all operations are supported by all
1290 objects.
1291
1292
1293 @menu
1294 * Memory Based Data Buffers::     Creating memory based data buffers.
1295 * File Based Data Buffers::       Creating file based data buffers.
1296 * Callback Based Data Buffers::   Creating callback based data buffers.
1297 @end menu
1298
1299
1300 @node Memory Based Data Buffers
1301 @subsection Memory Based Data Buffers
1302
1303 Memory based data objects store all data in allocated memory.  This is
1304 convenient, but only practical for an amount of data that is a
1305 fraction of the available physical memory.  The data has to be copied
1306 from its source and to its destination, which can often be avoided by
1307 using one of the other data object 
1308
1309 @deftypefun gpgme_error_t gpgme_data_new (@w{gpgme_data_t *@var{dh}})
1310 The function @code{gpgme_data_new} creates a new @code{gpgme_data_t}
1311 object and returns a handle for it in @var{dh}.  The data object is
1312 memory based and initially empty.
1313
1314 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1315 data object was successfully created, @code{GPG_ERR_INV_VALUE} if
1316 @var{dh} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if not
1317 enough memory is available.
1318 @end deftypefun
1319
1320 @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}})
1321 The function @code{gpgme_data_new_from_mem} creates a new
1322 @code{gpgme_data_t} object and fills it with @var{size} bytes starting
1323 from @var{buffer}.
1324
1325 If @var{copy} is not zero, a private copy of the data is made.  If
1326 @var{copy} is zero, the data is taken from the specified buffer as
1327 needed, and the user has to ensure that the buffer remains valid for
1328 the whole life span of the data object.
1329
1330 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1331 data object was successfully created, @code{GPG_ERR_INV_VALUE} if
1332 @var{dh} or @var{buffer} is not a valid pointer, and
1333 @code{GPG_ERR_ENOMEM} if not enough memory is available.
1334 @end deftypefun
1335
1336 @deftypefun gpgme_error_t gpgme_data_new_from_file (@w{gpgme_data_t *@var{dh}}, @w{const char *@var{filename}}, @w{int @var{copy}})
1337 The function @code{gpgme_data_new_from_file} creates a new
1338 @code{gpgme_data_t} object and fills it with the content of the file
1339 @var{filename}.
1340
1341 If @var{copy} is not zero, the whole file is read in at initialization
1342 time and the file is not used anymore after that.  This is the only
1343 mode supported currently.  Later, a value of zero for @var{copy} might
1344 cause all reads to be delayed until the data is needed, but this is
1345 not yet implemented.
1346
1347 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1348 data object was successfully created, @code{GPG_ERR_INV_VALUE} if
1349 @var{dh} or @var{filename} is not a valid pointer,
1350 @code{GPG_ERR_NOT_IMPLEMENTED} if @var{code} is zero, and
1351 @code{GPG_ERR_ENOMEM} if not enough memory is available.
1352 @end deftypefun
1353
1354 @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}})
1355 The function @code{gpgme_data_new_from_filepart} creates a new
1356 @code{gpgme_data_t} object and fills it with a part of the file specified
1357 by @var{filename} or @var{fp}.
1358
1359 Exactly one of @var{filename} and @var{fp} must be non-zero, the other
1360 must be zero.  The argument that is not zero specifies the file from
1361 which @var{length} bytes are read into the data object, starting from
1362 @var{offset}.
1363
1364 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1365 data object was successfully created, @code{GPG_ERR_INV_VALUE} if
1366 @var{dh} and exactly one of @var{filename} and @var{fp} is not a valid
1367 pointer, and @code{GPG_ERR_ENOMEM} if not enough memory is available.
1368 @end deftypefun
1369
1370
1371 @node File Based Data Buffers
1372 @subsection File Based Data Buffers
1373
1374 File based data objects operate directly on file descriptors or
1375 streams.  Only a small amount of data is stored in core at any time,
1376 so the size of the data objects is not limited by @acronym{GPGME}.
1377
1378 @deftypefun gpgme_error_t gpgme_data_new_from_fd (@w{gpgme_data_t *@var{dh}}, @w{int @var{fd}})
1379 The function @code{gpgme_data_new_from_fd} creates a new
1380 @code{gpgme_data_t} object and uses the file descriptor @var{fd} to read
1381 from (if used as an input data object) and write to (if used as an
1382 output data object).
1383
1384 When using the data object as an input buffer, the function might read
1385 a bit more from the file descriptor than is actually needed by the
1386 crypto engine in the desired operation because of internal buffering.
1387
1388 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1389 data object was successfully created, and @code{GPG_ERR_ENOMEM} if not
1390 enough memory is available.
1391 @end deftypefun
1392
1393 @deftypefun gpgme_error_t gpgme_data_new_from_stream (@w{gpgme_data_t *@var{dh}}, @w{FILE *@var{stream}})
1394 The function @code{gpgme_data_new_from_stream} creates a new
1395 @code{gpgme_data_t} object and uses the I/O stream @var{stream} to read
1396 from (if used as an input data object) and write to (if used as an
1397 output data object).
1398
1399 When using the data object as an input buffer, the function might read
1400 a bit more from the stream than is actually needed by the crypto
1401 engine in the desired operation because of internal buffering.
1402
1403 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1404 data object was successfully created, and @code{GPG_ERR_ENOMEM} if not
1405 enough memory is available.
1406 @end deftypefun
1407
1408
1409 @node Callback Based Data Buffers
1410 @subsection Callback Based Data Buffers
1411
1412 If neither memory nor file based data objects are a good fit for your
1413 application, you can implement the functions a data object provides
1414 yourself and create a data object from these callback functions.
1415
1416 @deftp {Data type} {ssize_t (*gpgme_data_read_cb_t) (@w{void *@var{handle}}, @w{void @var{*buffer}}, @w{size_t @var{size}})}
1417 @tindex gpgme_data_read_cb_t
1418 The @code{gpgme_data_read_cb_t} type is the type of functions which
1419 @acronym{GPGME} calls if it wants to read data from a user-implemented
1420 data object.  The function should read up to @var{size} bytes from the
1421 current read position into the space starting at @var{buffer}.  The
1422 @var{handle} is provided by the user at data object creation time.
1423
1424 The function should return the number of bytes read, 0 on EOF, and -1
1425 on error.  If an error occurs, @var{errno} should be set to describe
1426 the type of the error.
1427 @end deftp
1428
1429 @deftp {Data type} {ssize_t (*gpgme_data_write_cb_t) (@w{void *@var{handle}}, @w{const void @var{*buffer}}, @w{size_t @var{size}})}
1430 @tindex gpgme_data_write_cb_t
1431 The @code{gpgme_data_write_cb_t} type is the type of functions which
1432 @acronym{GPGME} calls if it wants to write data to a user-implemented
1433 data object.  The function should write up to @var{size} bytes to the
1434 current write position from the space starting at @var{buffer}.  The
1435 @var{handle} is provided by the user at data object creation time.
1436
1437 The function should return the number of bytes written, and -1 on
1438 error.  If an error occurs, @var{errno} should be set to describe the
1439 type of the error.
1440 @end deftp
1441
1442 @deftp {Data type} {off_t (*gpgme_data_seek_cb_t) (@w{void *@var{handle}}, @w{off_t @var{offset}}, @w{int @var{whence}})}
1443 @tindex gpgme_data_seek_cb_t
1444 The @code{gpgme_data_seek_cb_t} type is the type of functions which
1445 @acronym{GPGME} calls if it wants to change the current read/write
1446 position in a user-implemented data object, just like the @code{lseek}
1447 function.
1448
1449 The function should return the new read/write position, and -1 on
1450 error.  If an error occurs, @var{errno} should be set to describe the
1451 type of the error.
1452 @end deftp
1453
1454 @deftp {Data type} {void (*gpgme_data_release_cb_t) (@w{void *@var{handle}})}
1455 @tindex gpgme_data_release_cb_t
1456 The @code{gpgme_data_release_cb_t} type is the type of functions which
1457 @acronym{GPGME} calls if it wants to destroy a user-implemented data
1458 object.  The @var{handle} is provided by the user at data object
1459 creation time.
1460 @end deftp
1461
1462 @deftp {Data type} {struct gpgme_data_cbs}
1463 This structure is used to store the data callback interface functions
1464 described above.  It has the following members:
1465
1466 @table @code
1467 @item gpgme_data_read_cb_t read
1468 This is the function called by @acronym{GPGME} to read data from the
1469 data object.  It is only required for input data object.
1470
1471 @item gpgme_data_write_cb_t write
1472 This is the function called by @acronym{GPGME} to write data to the
1473 data object.  It is only required for output data object.
1474
1475 @item gpgme_data_seek_cb_t seek
1476 This is the function called by @acronym{GPGME} to change the current
1477 read/write pointer in the data object (if available).  It is optional.
1478
1479 @item gpgme_data_release_cb_t release
1480 This is the function called by @acronym{GPGME} to release a data
1481 object.  It is optional.
1482 @end table
1483 @end deftp
1484
1485 @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}})
1486 The function @code{gpgme_data_new_from_cbs} creates a new
1487 @code{gpgme_data_t} object and uses the user-provided callback functions
1488 to operate on the data object.
1489
1490 The handle @var{handle} is passed as first argument to the callback
1491 functions.  This can be used to identify this data object.
1492
1493 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1494 data object was successfully created, and @code{GPG_ERR_ENOMEM} if not
1495 enough memory is available.
1496 @end deftypefun
1497
1498 The following interface is deprecated and only provided for backward
1499 compatibility.  Don't use it.  It will be removed in a future version
1500 of @acronym{GPGME}.
1501
1502 @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}})
1503 The function @code{gpgme_data_new_with_read_cb} creates a new
1504 @code{gpgme_data_t} object and uses the callback function @var{readfunc}
1505 to retrieve the data on demand.  As the callback function can supply
1506 the data in any way it wants, this is the most flexible data type
1507 @acronym{GPGME} provides.  However, it can not be used to write data.
1508
1509 The callback function receives @var{hook_value} as its first argument
1510 whenever it is invoked.  It should return up to @var{count} bytes in
1511 @var{buffer}, and return the number of bytes actually read in
1512 @var{nread}.  It may return @code{0} in @var{nread} if no data is
1513 currently available.  To indicate @code{EOF} the function should
1514 return with an error code of @code{-1} and set @var{nread} to
1515 @code{0}.  The callback function may support to reset its internal
1516 read pointer if it is invoked with @var{buffer} and @var{nread} being
1517 @code{NULL} and @var{count} being @code{0}.
1518
1519 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1520 data object was successfully created, @code{GPG_ERR_INV_VALUE} if
1521 @var{dh} or @var{readfunc} is not a valid pointer, and
1522 @code{GPG_ERR_ENOMEM} if not enough memory is available.
1523 @end deftypefun
1524
1525
1526 @node Destroying Data Buffers
1527 @section Destroying Data Buffers
1528 @cindex data buffer, destruction
1529
1530 @deftypefun void gpgme_data_release (@w{gpgme_data_t @var{dh}})
1531 The function @code{gpgme_data_release} destroys the data object with
1532 the handle @var{dh}.  It releases all associated resources that were
1533 not provided by the user in the first place.
1534 @end deftypefun
1535
1536 @deftypefun {char *} gpgme_data_release_and_get_mem (@w{gpgme_data_t @var{dh}}, @w{size_t *@var{length}})
1537 The function @code{gpgme_data_release_and_get_mem} is like
1538 @code{gpgme_data_release}, except that it returns the data buffer and
1539 its length that was provided by the object.
1540
1541 The user has to release the buffer with @code{free}.  In case the user
1542 provided the data buffer in non-copy mode, a copy will be made for
1543 this purpose.
1544
1545 In case an error returns, or there is no suitable data buffer that can
1546 be returned to the user, the function will return @code{NULL}.
1547 @end deftypefun
1548
1549
1550 @node Manipulating Data Buffers
1551 @section Manipulating Data Buffers
1552 @cindex data buffere, manipulation
1553
1554 @deftypefun ssize_t gpgme_data_read (@w{gpgme_data_t @var{dh}}, @w{void *@var{buffer}}, @w{size_t @var{length}})
1555 The function @code{gpgme_data_read} reads up to @var{length} bytes
1556 from the data object with the handle @var{dh} into the space starting
1557 at @var{buffer}.
1558
1559 If no error occurs, the actual amount read is returned.  If the end of
1560 the data object is reached, the function returns 0.
1561
1562 In all other cases, the function returns -1 and sets @var{errno}.
1563 @end deftypefun
1564
1565 @deftypefun ssize_t gpgme_data_write (@w{gpgme_data_t @var{dh}}, @w{const void *@var{buffer}}, @w{size_t @var{size}})
1566 The function @code{gpgme_data_write} writes up to @var{size} bytes
1567 starting from @var{buffer} into the data object with the handle
1568 @var{dh} at the current write position.
1569
1570 The function returns the number of bytes actually written, or -1 if an
1571 error occurs.  If an error occurs, @var{errno} is set.
1572 @end deftypefun
1573
1574 @deftypefun off_t gpgme_data_seek (@w{gpgme_data_t @var{dh}}, @w{off_t *@var{offset}}, @w{int @var{whence}})
1575 The function @code{gpgme_data_seek} changes the current read/write
1576 position.
1577
1578 The @var{whence} argument specifies how the @var{offset} should be
1579 interpreted.  It must be one of the following symbolic constants:
1580
1581 @table @code
1582 @item SEEK_SET
1583 Specifies that @var{whence} is a count of characters from the
1584 beginning of the data object.
1585
1586 @item SEEK_CUR
1587 Specifies that @var{whence} is a count of characters from the current
1588 file position.  This count may be positive or negative.
1589
1590 @item SEEK_END
1591 Specifies that @var{whence} is a count of characters from the end of
1592 the data object.  A negative count specifies a position within the
1593 current extent of the data object; a positive count specifies a
1594 position past the current end.  If you set the position past the
1595 current end, and actually write data, you will extend the data object
1596 with zeros up to that position.
1597 @end table
1598
1599 If successful, the function returns the resulting file position,
1600 measured in bytes from the beginning of the data object.  You can use
1601 this feature together with @code{SEEK_CUR} to read the current
1602 read/write position.
1603
1604 If the function fails, -1 is returned and @var{errno} is set.
1605 @end deftypefun
1606
1607 The following function is deprecated and should not be used.  It will
1608 be removed in a future version of @acronym{GPGME}.
1609
1610 @deftypefun gpgme_error_t gpgme_data_rewind (@w{gpgme_data_t @var{dh}})
1611 The function @code{gpgme_data_rewind} is equivalent to:
1612
1613 @example
1614   return (gpgme_data_seek (dh, 0, SEEK_SET) == -1)
1615     ? gpgme_error_from_errno (errno) : 0;
1616 @end example
1617 @end deftypefun
1618
1619 @c
1620 @c  gpgme_data_encoding_t
1621 @c
1622 @deftp {Data type} {enum gpgme_data_encoding_t}
1623 @tindex gpgme_data_encoding_t
1624 The @code{gpgme_data_encoding_t} type specifies the encoding of a
1625 @code{gpgme_data_t} object.  This encoding is useful to give the backend
1626 a hint on the type of data.  The following data types are available:
1627
1628 @table @code
1629 @item GPGME_DATA_ENCODING_NONE
1630 This specifies that the encoding is not known.  This is the default
1631 for a new data object.  The backend will try its best to detect the
1632 encoding automatically.
1633
1634 @item GPGME_DATA_ENCODING_BINARY
1635 This specifies that the data is encoding in binary form; i.e. there is
1636 no special encoding.
1637
1638 @item GPGME_DATA_ENCODING_BASE64
1639 This specifies that the data is encoded using the Base-64 encoding
1640 scheme as used by @acronym{MIME} and other protocols.
1641
1642 @item GPGME_DATA_ENCODING_ARMOR
1643 This specifies that the data is encoded in an armored form as used by
1644 OpenPGP and PEM.
1645 @end table
1646 @end deftp
1647
1648 @deftypefun gpgme_data_encoding_t gpgme_data_get_encoding (@w{gpgme_data_t @var{dh}})
1649 The function @code{gpgme_data_get_encoding} returns the encoding of
1650 the data object with the handle @var{dh}.  If @var{dh} is not a valid
1651 pointer (e.g. @code{NULL}) @code{GPGME_DATA_ENCODING_NONE} is
1652 returned.
1653 @end deftypefun
1654
1655 @deftypefun gpgme_error_t gpgme_data_set_encoding (@w{gpgme_data_t @var{dh}, gpgme_data_encoding_t @var{enc}})
1656 The function @code{gpgme_data_set_encoding} changes the encoding of
1657 the data object with the handle @var{dh} to @var{enc}.
1658 @end deftypefun
1659
1660
1661 @c
1662 @c    Chapter Contexts
1663 @c 
1664 @node Contexts
1665 @chapter Contexts
1666 @cindex context
1667
1668 All cryptographic operations in @acronym{GPGME} are performed within a
1669 context, which contains the internal state of the operation as well as
1670 configuration parameters.  By using several contexts you can run
1671 several cryptographic operations in parallel, with different
1672 configuration.
1673
1674 @deftp {Data type} {gpgme_ctx_t}
1675 The @code{gpgme_ctx_t} type is a handle for a @acronym{GPGME} context,
1676 which is used to hold the configuration, status and result of
1677 cryptographic operations.
1678 @end deftp
1679
1680 @menu
1681 * Creating Contexts::             Creating new @acronym{GPGME} contexts.
1682 * Destroying Contexts::           Releasing @acronym{GPGME} contexts.
1683 * Context Attributes::            Setting properties of a context.
1684 * Key Management::                Managing keys with @acronym{GPGME}.
1685 * Trust Item Management::         Managing trust items with @acronym{GPGME}.
1686 * Crypto Operations::             Using a context for cryptography.
1687 * Run Control::                   Controlling how operations are run.
1688 @end menu
1689
1690
1691 @node Creating Contexts
1692 @section Creating Contexts
1693 @cindex context, creation
1694
1695 @deftypefun gpgme_error_t gpgme_new (@w{gpgme_ctx_t *@var{ctx}})
1696 The function @code{gpgme_data_new} creates a new @code{gpgme_ctx_t}
1697 object and returns a handle for it in @var{ctx}.
1698
1699 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1700 context was successfully created, @code{GPG_ERR_INV_VALUE} if
1701 @var{ctx} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if not
1702 enough memory is available.
1703 @end deftypefun
1704
1705
1706 @node Destroying Contexts
1707 @section Destroying Contexts
1708 @cindex context, destruction
1709
1710 @deftypefun void gpgme_release (@w{gpgme_ctx_t @var{ctx}})
1711 The function @code{gpgme_release} destroys the context with the handle
1712 @var{ctx} and releases all associated resources.
1713 @end deftypefun
1714
1715
1716 @node Context Attributes
1717 @section Context Attributes
1718 @cindex context, attributes
1719
1720 @menu
1721 * Protocol Selection::            Selecting the protocol used by a context.
1722 * ASCII Armor::                   Requesting @acronym{ASCII} armored output.
1723 * Text Mode::                     Choosing canonical text mode.
1724 * Included Certificates::       Including a number of certificates.
1725 * Key Listing Mode::              Selecting key listing mode.
1726 * Passphrase Callback::           Getting the passphrase from the user.
1727 * Progress Meter Callback::       Being informed about the progress.
1728 @end menu
1729
1730
1731 @node Protocol Selection
1732 @subsection Protocol Selection
1733 @cindex context, selecting protocol
1734 @cindex protocol, selecting
1735
1736 @deftypefun gpgme_error_t gpgme_set_protocol (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_protocol_t @var{proto}})
1737 The function @code{gpgme_set_protocol} sets the protocol used within
1738 the context @var{ctx} to @var{proto}.  All crypto operations will be
1739 performed by the crypto engine configured for that protocol.
1740 @xref{Protocols and Engines}.
1741
1742 Setting the protocol with @code{gpgme_set_protocol} does not check if
1743 the crypto engine for that protocol is available and installed
1744 correctly.  @xref{Engine Version Check}.
1745
1746 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1747 protocol could be set successfully, and @code{GPG_ERR_INV_VALUE} if
1748 @var{protocol} is not a valid protocol.
1749 @end deftypefun
1750
1751 @deftypefun gpgme_protocol_t gpgme_get_protocol (@w{gpgme_ctx_t @var{ctx}})
1752 The function @code{gpgme_get_protocol} retrieves the protocol currently
1753 use with the context @var{ctx}.
1754 @end deftypefun
1755
1756 @c FIXME: Unfortunately, using @acronym here breaks texi2dvi.
1757 @node ASCII Armor
1758 @subsection @acronym{ASCII} Armor
1759 @cindex context, armor mode
1760 @cindex @acronym{ASCII} armor
1761 @cindex armor mode
1762
1763 @deftypefun void gpgme_set_armor (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{yes}})
1764 The function @code{gpgme_set_armor} specifies if the output should be
1765 @acronym{ASCII} armored.  By default, output is not @acronym{ASCII}
1766 armored.
1767
1768 @acronym{ASCII} armored output is disabled if @var{yes} is zero, and
1769 enabled otherwise.
1770 @end deftypefun
1771
1772 @deftypefun int gpgme_get_armor (@w{gpgme_ctx_t @var{ctx}})
1773 The function @code{gpgme_get_armor} returns 1 if the output is
1774 @acronym{ASCII} armored, and @code{0} if it is not, or if @var{ctx} is
1775 not a valid pointer.
1776 @end deftypefun
1777
1778
1779 @node Text Mode
1780 @subsection Text Mode
1781 @cindex context, text mode
1782 @cindex text mode
1783 @cindex canonical text mode
1784
1785 @deftypefun void gpgme_set_textmode (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{yes}})
1786 The function @code{gpgme_set_textmode} specifies if canonical text mode
1787 should be used.  By default, text mode is not used.
1788
1789 Text mode is for example used for the RFC2015 signatures; note that
1790 the updated RFC 3156 mandates that the mail user agent does some
1791 preparations so that text mode is not needed anymore.
1792
1793 This option is only relevant to the OpenPGP crypto engine, and ignored
1794 by all other engines.
1795
1796 Canonical text mode is disabled if @var{yes} is zero, and enabled
1797 otherwise.
1798 @end deftypefun
1799
1800 @deftypefun int gpgme_get_textmode (@w{gpgme_ctx_t @var{ctx}})
1801 The function @code{gpgme_get_textmode} returns 1 if canonical text
1802 mode is enabled, and @code{0} if it is not, or if @var{ctx} is not a
1803 valid pointer.
1804 @end deftypefun
1805
1806
1807 @node Included Certificates
1808 @subsection Included Certificates
1809 @cindex certificates, included
1810
1811 @deftypefun void gpgme_set_include_certs (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{nr_of_certs}})
1812 The function @code{gpgme_set_include_certs} specifies how many
1813 certificates should be included in an S/MIME signed message.  By
1814 default, only the sender's certificate is included.  The possible
1815 values of @var{nr_of_certs} are:
1816
1817 @table @code
1818 @item -2
1819 Include all certificates except the root certificate.
1820 @item -1
1821 Include all certificates.
1822 @item 0
1823 Include no certificates.
1824 @item 1
1825 Include the sender's certificate only.
1826 @item n
1827 Include the first n certificates of the certificates path, starting
1828 from the sender's certificate.  The number @code{n} must be positive.
1829 @end table
1830
1831 Values of @var{nr_of_certs} smaller than -2 are undefined.
1832
1833 This option is only relevant to the CMS crypto engine, and ignored by
1834 all other engines.
1835 @end deftypefun
1836
1837 @deftypefun int gpgme_get_include_certs (@w{gpgme_ctx_t @var{ctx}})
1838 The function @code{gpgme_get_include_certs} returns the number of
1839 certificates to include into an S/MIME signed message.
1840 @end deftypefun
1841
1842
1843 @node Key Listing Mode
1844 @subsection Key Listing Mode
1845 @cindex key listing mode
1846 @cindex key listing, mode of
1847
1848 @deftypefun void gpgme_set_keylist_mode (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_keylist_mode_t @var{mode}})
1849 The function @code{gpgme_set_keylist_mode} changes the default
1850 behaviour of the key listing functions.  The value in @var{mode} is a
1851 bitwise-or combination of one or multiple of the following bit values:
1852
1853 @table @code
1854 @item GPGME_KEYLIST_MODE_LOCAL
1855 The @code{GPGME_KEYLIST_MODE_LOCAL} symbol specifies that the local
1856 keyring should be searched for keys in the keylisting operation.  This
1857 is the default.
1858
1859 @item GPGME_KEYLIST_MODE_EXTERN
1860 The @code{GPGME_KEYLIST_MODE_EXTERN} symbol specifies that an external
1861 source should be searched for keys in the keylisting
1862 operation.  The type of external source is dependant on the crypto
1863 engine used.  For example, it can be a remote keyserver or LDAP
1864 certificate server.
1865
1866 @item GPGME_KEYLIST_MODE_SIGS
1867 The @code{GPGME_KEYLIST_MODE_SIGS} symbol specifies that the key
1868 signatures should be included in the listed keys.
1869 @end table
1870
1871 At least one of @code{GPGME_KEYLIST_MODE_LOCAL} and
1872 @code{GPGME_KEYLIST_MODE_EXTERN} must be specified.  For future binary
1873 compatibility, you should get the current mode with
1874 @code{gpgme_get_keylist_mode} and modify it by setting or clearing the
1875 appropriate bits, and then using that calulcated value in the
1876 @code{gpgme_set_keylisting_mode} operation.  This will leave all other
1877 bits in the mode value intact (in particular those that are not used
1878 in the current version of the library).
1879
1880 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
1881 mode could be set correctly, and @code{GPG_ERR_INV_VALUE} if @var{ctx}
1882 is not a valid pointer or @var{mode} is not a valid mode.
1883 @end deftypefun
1884
1885
1886 @deftypefun gpgme_keylist_mode_t gpgme_get_keylist_mode (@w{gpgme_ctx_t @var{ctx}})
1887 The function @code{gpgme_get_keylist_mode} returns the current key
1888 listing mode of the context @var{ctx}.  This value can then be
1889 modified and used in a subsequent @code{gpgme_set_keylist_mode}
1890 operation to only affect the desired bits (and leave all others
1891 intact).
1892
1893 The function returns 0 if @var{ctx} is not a valid pointer, and the
1894 current mode otherwise.  Note that 0 is not a valid mode value.
1895 @end deftypefun
1896
1897
1898 @node Passphrase Callback
1899 @subsection Passphrase Callback
1900 @cindex callback, passphrase
1901 @cindex passphrase callback
1902
1903 @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}})}
1904 @tindex gpgme_passphrase_cb_t
1905 The @code{gpgme_passphrase_cb_t} type is the type of functions usable as
1906 passphrase callback function.
1907
1908 The argument @var{uid_hint} might contain a string that gives an
1909 indication for which user ID the passphrase is required.  If this is
1910 not available, or not applicable (in the case of symmetric encryption,
1911 for example), @var{uid_hint} will be @code{NULL}.
1912
1913 The argument @var{passphrase_info}, if not @code{NULL}, will give
1914 further information about the context in which the passphrase is
1915 required.  This information is engine and operation specific.
1916
1917 If this is the repeated attempt to get the passphrase, because
1918 previous attempts failed, then @var{prev_was_bad} is 1, otherwise it
1919 will be 0.
1920
1921 The user must write the passphrase, followed by a newline character,
1922 to the file descriptor @var{fd}.  If the user does not return 0
1923 indicating success, the user must at least write a newline character
1924 before returning from the callback.
1925
1926 If an error occurs, return the corresponding @code{gpgme_error_t}
1927 value.  You can use the error code @code{GPG_ERR_CANCELED} to abort
1928 the operation.  Otherwise, return @code{0}.
1929 @end deftp
1930
1931 @deftypefun void gpgme_set_passphrase_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_passphrase_cb_t @var{passfunc}}, @w{void *@var{hook_value}})
1932 The function @code{gpgme_set_passphrase_cb} sets the function that is
1933 used when a passphrase needs to be provided by the user to
1934 @var{passfunc}.  The function @var{passfunc} needs to implemented by
1935 the user, and whenever it is called, it is called with its first
1936 argument being @var{hook_value}.  By default, no passphrase callback
1937 function is set.
1938
1939 Not all crypto engines require this callback to retrieve the
1940 passphrase.  It is better if the engine retrieves the passphrase from
1941 a trusted agent (a daemon process), rather than having each user to
1942 implement their own passphrase query.
1943
1944 The user can disable the use of a passphrase callback function by
1945 calling @code{gpgme_set_passphrase_cb} with @var{passfunc} being
1946 @code{NULL}.
1947 @end deftypefun
1948
1949 @deftypefun void gpgme_get_passphrase_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_passphrase_cb_t *@var{passfunc}}, @w{void **@var{hook_value}})
1950 The function @code{gpgme_get_passphrase_cb} returns the function that
1951 is used when a passphrase needs to be provided by the user in
1952 @var{*passfunc}, and the first argument for this function in
1953 @var{*hook_value}.  If no passphrase callback is set, or @var{ctx} is
1954 not a valid pointer, @code{NULL} is returned in both variables.
1955
1956 @var{passfunc} or @var{hook_value} can be @code{NULL}.  In this case,
1957 the corresponding value will not be returned.
1958 @end deftypefun
1959
1960
1961 @node Progress Meter Callback
1962 @subsection Progress Meter Callback
1963 @cindex callback, progress meter
1964 @cindex progress meter callback
1965
1966 @deftp {Data type} {void (*gpgme_progress_cb_t)(void *@var{hook}, const char *@var{what}, int @var{type}, int @var{current}, int @var{total})}
1967 @tindex gpgme_progress_cb_t
1968 The @code{gpgme_progress_cb_t} type is the type of functions usable as
1969 progress callback function.
1970
1971 The arguments are specific to the crypto engine.  More information
1972 about the progress information returned from the GnuPG engine can be
1973 found in the GnuPG source code in the file @file{doc/DETAILS} in the
1974 section PROGRESS.
1975 @end deftp
1976
1977 @deftypefun void gpgme_set_progress_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_progress_cb_t @var{progfunc}}, @w{void *@var{hook_value}})
1978 The function @code{gpgme_set_progress_cb} sets the function that is
1979 used when progress information about a cryptographic operation is
1980 available.  The function @var{progfunc} needs to implemented by the
1981 user, and whenever it is called, it is called with its first argument
1982 being @var{hook_value}.  By default, no progress callback function
1983 is set.
1984
1985 Setting a callback function allows an interactive program to display
1986 progress information about a long operation to the user.
1987
1988 The user can disable the use of a progress callback function by
1989 calling @code{gpgme_set_progress_cb} with @var{progfunc} being
1990 @code{NULL}.
1991 @end deftypefun
1992
1993 @deftypefun void gpgme_get_progress_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_progress_cb_t *@var{progfunc}}, @w{void **@var{hook_value}})
1994 The function @code{gpgme_get_progress_cb} returns the function that is
1995 used to inform the user about the progress made in @var{*progfunc},
1996 and the first argument for this function in @var{*hook_value}.  If no
1997 progress callback is set, or @var{ctx} is not a valid pointer,
1998 @code{NULL} is returned in both variables.
1999
2000 @var{progfunc} or @var{hook_value} can be @code{NULL}.  In this case,
2001 the corresponding value will not be returned.
2002 @end deftypefun
2003
2004
2005 @node Key Management
2006 @section Key Management
2007 @cindex key management
2008
2009 Some of the cryptographic operations require that recipients or
2010 signers are specified.  This is always done by specifying the
2011 respective keys that should be used for the operation.  The following
2012 section describes how such keys can be selected and manipulated.
2013
2014 @deftp {Data type} gpgme_sub_key_t
2015 The @code{gpgme_sub_key_t} type is a pointer to a subkey structure.
2016 Sub keys are one component of a @code{gpgme_key_t} object.  In fact,
2017 subkeys are those parts that contains the real information about the
2018 individual cryptographic keys that belong to the same key object.  One
2019 @code{gpgme_key_t} can contain several subkeys.  The first subkey in
2020 the linked list is also called the primary key.
2021
2022 The subkey structure has the following members:
2023
2024 @table @code
2025 @item gpgme_sub_key_t next
2026 This is a pointer to the next subkey structure in the linked list, or
2027 @code{NULL} if this is the last element.
2028
2029 @item unsigned int revoked : 1
2030 This is true if the subkey is revoked.
2031
2032 @item unsigned int expired : 1
2033 This is true if the subkey is expired.
2034
2035 @item unsigned int disabled : 1
2036 This is true if the subkey is disabled.
2037
2038 @item unsigned int invalid : 1
2039 This is true if the subkey is invalid.
2040
2041 @item unsigned int can_encrypt : 1
2042 This is true if the subkey can be used for encryption.
2043
2044 @item unsigned int can_sign : 1
2045 This is true if the subkey can be used to create data signatures.
2046
2047 @item unsigned int can_certify : 1
2048 This is true if the subkey can be used to create key certificates.
2049
2050 @item unsigned int can_authenticate : 1
2051 This is true if the subkey can be used for authentication.
2052
2053 @item unsigned int secret : 1
2054 This is true if the subkey is a secret key.
2055
2056 @item gpgme_pubkey_algo_t pubkey_algo
2057 This is the public key algorithm supported by this subkey.
2058
2059 @item unsigned int length
2060 This is the length of the subkey (in bits).
2061
2062 @item char *keyid
2063 This is the key ID of the subkey in hexadecimal digits.
2064
2065 @item char *fpr
2066 This is the fingerprint of the subkey in hexadecimal digits, if
2067 available.  This is usually only available for the primary key.
2068
2069 @item long int timestamp
2070 This is the creation timestamp of the subkey.  This is -1 if the
2071 timestamp is invalid, and 0 if it is not available.
2072
2073 @item long int expires
2074 This is the expiration timestamp of the subkey, or 0 if the subkey
2075 does not expire.
2076 @end table
2077 @end deftp
2078
2079 @deftp {Data type} gpgme_key_sig_t
2080 The @code{gpgme_key_sig_t} type is a pointer to a key signature structure.
2081 Key signatures are one component of a @code{gpgme_key_t} object, and
2082 validate user IDs on the key.
2083
2084 The signatures on a key are only available if the key was retrieved
2085 via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode
2086 enabled, because it is expensive to retrieve all signatures of a key.
2087
2088 The key signature structure has the following members:
2089
2090 @table @code
2091 @item gpgme_key_sig_t next
2092 This is a pointer to the next key signature structure in the linked
2093 list, or @code{NULL} if this is the last element.
2094
2095 @item unsigned int revoked : 1
2096 This is true if the key signature is a revocation signature.
2097
2098 @item unsigned int expired : 1
2099 This is true if the key signature is expired.
2100
2101 @item unsigned int invalid : 1
2102 This is true if the key signature is invalid.
2103
2104 @item unsigned int disabled : 1
2105 This is true if the key signature is exportable.
2106
2107 @item gpgme_pubkey_algo_t pubkey_algo
2108 This is the public key algorithm used to create the signature.
2109
2110 @item char *keyid
2111 This is the key ID of the key (in hexadecimal digits) used to create
2112 the signature.
2113
2114 @item long int timestamp
2115 This is the creation timestamp of the key signature.  This is -1 if
2116 the timestamp is invalid, and 0 if it is not available.
2117
2118 @item long int expires
2119 This is the expiration timestamp of the key signature, or 0 if the key
2120 signature does not expire.
2121
2122 @item gpgme_error_t status
2123 This is the status of the signature and has the same meaning as the
2124 member of the same name in a @code{gpgme_signature_t} object.
2125
2126 @item unsigned int class
2127 This specifies the signature class of the key signature.  The meaning
2128 is specific to the crypto engine.
2129
2130 @item char *uid
2131 This is the main user ID of the key used to create the signature.
2132
2133 @item char *name
2134 This is the name component of @code{uid}, if available.
2135
2136 @item char *comment
2137 This is the comment component of @code{uid}, if available.
2138
2139 @item char *email
2140 This is the email component of @code{uid}, if available.
2141 @end table
2142 @end deftp
2143
2144 @deftp {Data type} gpgme_user_id_t
2145 A user ID is a component of a @code{gpgme_key_t} object.  One key can
2146 have many user IDs.  The first one in the list is the main (or
2147 primary) user ID.
2148
2149 The user ID structure has the following members.
2150
2151 @table @code
2152 @item gpgme_user_id_t next
2153 This is a pointer to the next user ID structure in the linked list, or
2154 @code{NULL} if this is the last element.
2155
2156 @item unsigned int revoked : 1
2157 This is true if the user ID is revoked.
2158
2159 @item unsigned int invalid : 1
2160 This is true if the user ID is invalid.
2161
2162 @item gpgme_validity_t validity
2163 This specifies the validity of the user ID.
2164
2165 @item char *uid
2166 This is the user ID string.
2167
2168 @item char *name
2169 This is the name component of @code{uid}, if available.
2170
2171 @item char *comment
2172 This is the comment component of @code{uid}, if available.
2173
2174 @item char *email
2175 This is the email component of @code{uid}, if available.
2176
2177 @item gpgme_key_sig_t signatures
2178 This is a linked list with the signatures on this user ID.
2179 @end table
2180 @end deftp
2181
2182 @deftp {Data type} gpgme_key_t
2183 The @code{gpgme_key_t} type is a pointer to a key object.  It has the
2184 following members:
2185
2186 @table @code
2187 @item unsigned int revoked : 1
2188 This is true if the key is revoked.
2189
2190 @item unsigned int expired : 1
2191 This is true if the key is expired.
2192
2193 @item unsigned int disabled : 1
2194 This is true if the key is disabled.
2195
2196 @item unsigned int invalid : 1
2197 This is true if the key is invalid.
2198
2199 @item unsigned int can_encrypt : 1
2200 This is true if the key (ie one of its subkeys) can be used for
2201 encryption.
2202
2203 @item unsigned int can_sign : 1
2204 This is true if the key (ie one of its subkeys) can be used to create
2205 data signatures.
2206
2207 @item unsigned int can_certify : 1
2208 This is true if the key (ie one of its subkeys) can be used to create
2209 key certificates.
2210
2211 @item unsigned int can_authenticate : 1
2212 This is true if the key (ie one of its subkeys) can be used for
2213 authentication.
2214
2215 @item unsigned int secret : 1
2216 This is true if the key is a secret key.
2217
2218 @item gpgme_protocol_t protocol
2219 This is the protocol supported by this key.
2220
2221 @item char *issuer_serial
2222 If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
2223 issuer serial.
2224
2225 @item char *issuer_name
2226 If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
2227 issuer name.
2228
2229 @item char *chain_id
2230 If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
2231 chain ID, which can be used to built the certificate chain.
2232  
2233 @item gpgme_validity_t owner_trust
2234 If @code{protocol} is @code{GPGME_PROTOCOL_OpenPGP}, then this is the
2235 owner trust.
2236
2237 @item gpgme_sub_key_t subkeys
2238 This is a linked list with the subkeys of the key.  The first subkey
2239 in the list is the primary key and usually available.
2240
2241 @item gpgme_user_id_t uids
2242 This is a linked list with the user IDs of the key.  The first user ID
2243 in the list is the main (or primary) user ID.
2244 @end table
2245 @end deftp
2246
2247 @menu
2248 * Listing Keys::                  Browsing the list of available keys.
2249 * Information About Keys::        Requesting detailed information about keys.
2250 * Key Signatures::                Listing the signatures on a key.
2251 * Manipulating Keys::             Operations on keys.
2252 * Generating Keys::               Creating new key pairs.
2253 * Exporting Keys::                Retrieving key data from the key ring.
2254 * Importing Keys::                Adding keys to the key ring.
2255 * Deleting Keys::                 Removing keys from the key ring.
2256 @end menu
2257
2258
2259 @node Listing Keys
2260 @subsection Listing Keys
2261 @cindex listing keys
2262 @cindex key listing
2263 @cindex key listing, start
2264 @cindex key ring, list
2265 @cindex key ring, search
2266
2267 @deftypefun gpgme_error_t gpgme_op_keylist_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}})
2268 The function @code{gpgme_op_keylist_start} initiates a key listing
2269 operation inside the context @var{ctx}.  It sets everything up so that
2270 subsequent invocations of @code{gpgme_op_keylist_next} return the keys
2271 in the list.
2272
2273 If @var{pattern} is @code{NULL}, all available keys are returned.
2274 Otherwise, @var{pattern} contains an engine specific expression that
2275 is used to limit the list to all keys matching the pattern.
2276
2277 If @var{secret_only} is not @code{0}, the list is restricted to secret
2278 keys only.
2279
2280 The context will be busy until either all keys are received (and
2281 @code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}), or
2282 @code{gpgme_op_keylist_end} is called to finish the operation.
2283
2284 The function returns the error code @code{GPG_ERR_INV_VALUE} if
2285 @var{ctx} is not a valid pointer, and passes through any errors that
2286 are reported by the crypto engine support routines.
2287 @end deftypefun
2288
2289 @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}})
2290 The function @code{gpgme_op_keylist_ext_start} initiates an extended
2291 key listing operation inside the context @var{ctx}.  It sets
2292 everything up so that subsequent invocations of
2293 @code{gpgme_op_keylist_next} return the keys in the list.
2294
2295 If @var{pattern} or @var{*pattern} is @code{NULL}, all available keys
2296 are returned.  Otherwise, @var{pattern} is a @code{NULL} terminated
2297 array of strings that are used to limit the list to all keys matching
2298 at least one of the patterns verbatim.
2299
2300 If @var{secret_only} is not @code{0}, the list is restricted to secret
2301 keys only.
2302
2303 The value of @var{reserved} must be @code{0}.
2304
2305 The context will be busy until either all keys are received (and
2306 @code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}), or
2307 @code{gpgme_op_keylist_end} is called to finish the operation.
2308
2309 The function returns the error code @code{GPG_ERR_INV_VALUE} if
2310 @var{ctx} is not a valid pointer, and passes through any errors that
2311 are reported by the crypto engine support routines.
2312 @end deftypefun
2313
2314 @deftypefun gpgme_error_t gpgme_op_keylist_next (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t *@var{r_key}})
2315 The function @code{gpgme_op_keylist_next} returns the next key in the
2316 list created by a previous @code{gpgme_op_keylist_start} operation in
2317 the context @var{ctx}.  The key will have one reference for the user.
2318 @xref{Manipulating Keys}.
2319
2320 This is the only way to get at @code{gpgme_key_t} objects in
2321 @acronym{GPGME}.
2322
2323 If the last key in the list has already been returned,
2324 @code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}.
2325
2326 The function returns the error code @code{GPG_ERR_INV_VALUE} if
2327 @var{ctx} or @var{r_key} is not a valid pointer, and
2328 @code{GPG_ERR_ENOMEM} if there is not enough memory for the operation.
2329 @end deftypefun
2330
2331 @deftypefun gpgme_error_t gpgme_op_keylist_end (@w{gpgme_ctx_t @var{ctx}})
2332 The function @code{gpgme_op_keylist_next} ends a pending key list
2333 operation in the context @var{ctx}.
2334
2335 After the operation completed successfully, the result of the key
2336 listing operation can be retrieved with
2337 @code{gpgme_op_keylist_result}.
2338
2339 The function returns the error code @code{GPG_ERR_INV_VALUE} if
2340 @var{ctx} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if at some
2341 time during the operation there was not enough memory available.
2342 @end deftypefun
2343
2344 The following example illustrates how all keys containing a certain
2345 string (@code{g10code}) can be listed with their key ID and the name
2346 and e-mail address of the main user ID:
2347
2348 @example
2349 gpgme_ctx_t ctx;
2350 gpgme_error_t err = gpgme_new (&ctx);
2351
2352 if (!err)
2353   @{
2354     err = gpgme_op_keylist_start (ctx, "g10code", 0);
2355     while (!err)
2356       @{
2357         err = gpgme_op_keylist_next (ctx, &key);
2358         if (err)
2359           break;
2360         printf ("%s: %s <%s>\n", key->keyid, key->name, key->email);
2361         gpgme_key_release (key);
2362       @}
2363     gpgme_release (ctx);
2364   @}
2365 if (gpg_err_code (err) != GPG_ERR_EOF)
2366   @{
2367     fprintf (stderr, "%s: can not list keys: %s\n",
2368              argv[0], gpgme_strerror (err));
2369     exit (1);
2370   @}
2371 @end example
2372
2373 @deftp {Data type} {gpgme_keylist_result_t}
2374 This is a pointer to a structure used to store the result of a
2375 @code{gpgme_op_keylist_*} operation.  After successfully ending a key
2376 listing operation, you can retrieve the pointer to the result with
2377 @code{gpgme_op_keylist_result}.  The structure contains the following
2378 member:
2379
2380 @table @code
2381 @item unsigned int truncated : 1
2382 This is true if the crypto backend had to truncate the result, and
2383 less than the desired keys could be listed.
2384 @end table
2385 @end deftp
2386
2387 @deftypefun gpgme_keylist_result_t gpgme_op_keylist_result (@w{gpgme_ctx_t @var{ctx}})
2388 The function @code{gpgme_op_keylist_result} returns a
2389 @code{gpgme_keylist_result_t} pointer to a structure holding the
2390 result of a @code{gpgme_op_keylist_*} operation.  The pointer is only
2391 valid if the last operation on the context was a key listing
2392 operation, and if this operation finished successfully.  The returned
2393 pointer is only valid until the next operation is started on the
2394 context.
2395 @end deftypefun
2396
2397 In a simple program, for which a blocking operation is acceptable, the
2398 following function can be used to retrieve a single key.
2399
2400 @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}})
2401 The function @code{gpgme_get_key} gets the key with the fingerprint
2402 (or key ID) @var{fpr} from the crypto backend and return it in
2403 @var{r_key}.  If @var{secret} is true, get the secret key.  The
2404 currently active keylist mode is used to retrieve the key.
2405
2406 If the key is not found in the keyring, @code{gpgme_get_key} returns
2407 the error code @code{GPG_ERR_NO_ERROR} and *@var{r_key} will be set to
2408 @code{NULL}.
2409
2410 The function returns the error code @code{GPG_ERR_INV_VALUE} if
2411 @var{ctx} or @var{r_key} is not a valid pointer or @var{fpr} is not a
2412 fingerprint or key ID, @code{GPG_ERR_AMBIGUOUS_NAME} if the key ID was
2413 not a unique specifier for a key, and @code{GPG_ERR_ENOMEM} if at some
2414 time during the operation there was not enough memory available.
2415 @end deftypefun
2416
2417
2418 @node Information About Keys
2419 @subsection Information About Keys
2420 @cindex key, information about
2421 @cindex key, attributes
2422 @cindex attributes, of a key
2423
2424 Please see the beginning of this section for more information about
2425 @code{gpgme_key_t} objects.
2426
2427 @deftp {Data type} gpgme_validity_t
2428 The @code{gpgme_validity_t} type is used to specify the validity of a user ID
2429 in a key.  The following validities are defined:
2430
2431 @table @code
2432 @item GPGME_VALIDITY_UNKNOWN
2433 The user ID is of unknown validity.  The string representation of this
2434 validity is ``?''.
2435
2436 @item GPGME_VALIDITY_UNDEFINED
2437 The validity of the user ID is undefined.  The string representation of this
2438 validity is ``q''.
2439
2440 @item GPGME_VALIDITY_NEVER
2441 The user ID is never valid.  The string representation of this
2442 validity is ``n''.
2443
2444 @item GPGME_VALIDITY_MARGINAL
2445 The user ID is marginally valid.  The string representation of this
2446 validity is ``m''.
2447
2448 @item GPGME_VALIDITY_FULL
2449 The user ID is fully valid.  The string representation of this
2450 validity is ``f''.
2451
2452 @item GPGME_VALIDITY_ULTIMATE
2453 The user ID is ultimately valid.  The string representation of this
2454 validity is ``u''.
2455 @end table
2456 @end deftp
2457
2458
2459 The following interfaces are deprecated and only provided for backward
2460 compatibility.  Don't use them.  They will be removed in a future
2461 version of @acronym{GPGME}.
2462
2463 @deftp {Data type} gpgme_attr_t
2464 The @code{gpgme_attr_t} type is used to specify a key or trust item
2465 attribute.  The following attributes are defined:
2466
2467 @table @code
2468 @item GPGME_ATTR_KEYID
2469 This is the key ID of a sub key.  It is representable as a string.
2470
2471 For trust items, the trust item refers to the key with this ID.
2472
2473 @item GPGME_ATTR_FPR
2474 This is the fingerprint of a sub key.  It is representable as a
2475 string.
2476
2477 @item GPGME_ATTR_ALGO
2478 This is the crypto algorithm for which the sub key can be used.  It
2479 is representable as a string and as a number.  The numbers correspond
2480 to the @code{enum gcry_pk_algos} values in the gcrypt library.
2481
2482 @item GPGME_ATTR_LEN
2483 This is the key length of a sub key.  It is representable as a
2484 number.
2485
2486 @item GPGME_ATTR_CREATED
2487 This is the timestamp at creation time of a sub key.  It is
2488 representable as a number.
2489
2490 @item GPGME_ATTR_EXPIRE
2491 This is the expiration time of a sub key.  It is representable as a
2492 number.
2493
2494 @item GPGME_ATTR_OTRUST
2495 XXX FIXME  (also for trust items)
2496
2497 @item GPGME_ATTR_USERID
2498 This is a user ID.  There can be more than one user IDs in a
2499 @var{gpgme_key_t} object.  The first one (with index 0) is the primary
2500 user ID.  The user ID is representable as a number.
2501
2502 For trust items, this is the user ID associated with this trust item.
2503
2504 @item GPGME_ATTR_NAME
2505 This is the name belonging to a user ID.  It is representable as a string.
2506
2507 @item GPGME_ATTR_EMAIL
2508 This is the email address belonging to a user ID.  It is representable
2509 as a string.
2510
2511 @item GPGME_ATTR_COMMENT
2512 This is the comment belonging to a user ID.  It is representable as a
2513 string.
2514
2515 @item GPGME_ATTR_VALIDITY
2516 This is the validity belonging to a user ID.  It is representable as a
2517 string and as a number.  See below for a list of available validities.
2518
2519 For trust items, this is the validity that is associated with this
2520 trust item.
2521
2522 @item GPGME_ATTR_UID_REVOKED
2523 This specifies if a user ID is revoked.  It is representable as a
2524 number, and is @code{1} if the user ID is revoked, and @code{0}
2525 otherwise.
2526
2527 @item GPGME_ATTR_UID_INVALID
2528 This specifies if a user ID is invalid.  It is representable as a
2529 number, and is @code{1} if the user ID is invalid, and @code{0}
2530 otherwise.
2531
2532 @item GPGME_ATTR_LEVEL
2533 This is the trust level of a trust item.
2534
2535 @item GPGME_ATTR_TYPE
2536 This returns information about the type of key.  For the string function
2537 this will eother be "PGP" or "X.509".  The integer function returns 0
2538 for PGP and 1 for X.509.  It is also used for the type of a trust item.
2539
2540 @item GPGME_ATTR_IS_SECRET
2541 This specifies if the key is a secret key.  It is representable as a
2542 number, and is @code{1} if the key is revoked, and @code{0} otherwise.
2543
2544 @item GPGME_ATTR_KEY_REVOKED
2545 This specifies if a sub key is revoked.  It is representable as a
2546 number, and is @code{1} if the key is revoked, and @code{0} otherwise.
2547
2548 @item GPGME_ATTR_KEY_INVALID
2549 This specifies if a sub key is invalid.  It is representable as a
2550 number, and is @code{1} if the key is invalid, and @code{0} otherwise.
2551
2552 @item GPGME_ATTR_KEY_EXPIRED
2553 This specifies if a sub key is expired.  It is representable as a
2554 number, and is @code{1} if the key is expired, and @code{0} otherwise.
2555
2556 @item GPGME_ATTR_KEY_DISABLED
2557 This specifies if a sub key is disabled.  It is representable as a
2558 number, and is @code{1} if the key is disabled, and @code{0} otherwise.
2559
2560 @item GPGME_ATTR_KEY_CAPS
2561 This is a description of the capabilities of a sub key.  It is
2562 representable as a string.  The string contains the letter ``e'' if
2563 the key can be used for encryption, ``s'' if the key can be used for
2564 signatures, and ``c'' if the key can be used for certifications.
2565
2566 @item GPGME_ATTR_CAN_ENCRYPT
2567 This specifies if a sub key can be used for encryption.  It is
2568 representable as a number, and is @code{1} if the sub key can be used
2569 for encryption, and @code{0} otherwise.
2570
2571 @item GPGME_ATTR_CAN_SIGN
2572 This specifies if a sub key can be used to create data signatures.  It
2573 is representable as a number, and is @code{1} if the sub key can be
2574 used for signatures, and @code{0} otherwise.
2575
2576 @item GPGME_ATTR_CAN_CERTIFY
2577 This specifies if a sub key can be used to create key certificates.
2578 It is representable as a number, and is @code{1} if the sub key can be
2579 used for certifications, and @code{0} otherwise.
2580
2581 @item GPGME_ATTR_SERIAL
2582 The X.509 issuer serial attribute of the key.  It is representable as
2583 a string.
2584
2585 @item GPGME_ATTR_ISSUE
2586 The X.509 issuer name attribute of the key.  It is representable as a
2587 string.
2588
2589 @item GPGME_ATTR_CHAINID
2590 The X.509 chain ID can be used to build the certification chain.  It
2591 is representable as a string.
2592 @end table
2593 @end deftp
2594
2595 @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}})
2596 The function @code{gpgme_key_get_string_attr} returns the value of the
2597 string-representable attribute @var{what} of key @var{key}.  If the
2598 attribute is an attribute of a sub key or an user ID, @var{idx}
2599 specifies the sub key or user ID of which the attribute value is
2600 returned.  The argument @var{reserved} is reserved for later use and
2601 should be @code{NULL}.
2602
2603 The string returned is only valid as long as the key is valid.
2604
2605 The function returns @code{0} if an attribute can't be returned as a
2606 string, @var{key} is not a valid pointer, @var{idx} out of range,
2607 or @var{reserved} not @code{NULL}.
2608 @end deftypefun
2609
2610 @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}})
2611 The function @code{gpgme_key_get_ulong_attr} returns the value of the
2612 number-representable attribute @var{what} of key @var{key}.  If the
2613 attribute is an attribute of a sub key or an user ID, @var{idx}
2614 specifies the sub key or user ID of which the attribute value is
2615 returned.  The argument @var{reserved} is reserved for later use and
2616 should be @code{NULL}.
2617
2618 The function returns @code{0} if the attribute can't be returned as a
2619 number, @var{key} is not a valid pointer, @var{idx} out of range, or
2620 @var{reserved} not @code{NULL}.
2621 @end deftypefun
2622
2623
2624 @node Key Signatures
2625 @subsection Key Signatures
2626 @cindex key, signatures
2627 @cindex signatures, on a key
2628
2629 The following interfaces are deprecated and only provided for backward
2630 compatibility.  Don't use them.  They will be removed in a future
2631 version of @acronym{GPGME}.
2632
2633 The signatures on a key are only available if the key was retrieved
2634 via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode
2635 enabled, because it is expensive to retrieve all signatures of a key.
2636
2637 So, before using the below interfaces to retrieve the signatures on a
2638 key, you have to make sure that the key was listed with signatures
2639 enabled.  One convenient, but blocking, way to do this is to use the
2640 function @code{gpgme_get_key}.
2641
2642 @deftp {Data type} gpgme_attr_t
2643 The @code{gpgme_attr_t} type is used to specify a key signature
2644 attribute.  The following attributes are defined:
2645
2646 @table @code
2647 @item GPGME_ATTR_KEYID
2648 This is the key ID of the key which was used for the signature.  It is
2649 representable as a string.
2650
2651 @item GPGME_ATTR_ALGO
2652 This is the crypto algorithm used to create the signature.  It is
2653 representable as a string and as a number.  The numbers correspond to
2654 the @code{enum gcry_pk_algos} values in the gcrypt library.
2655
2656 @item GPGME_ATTR_CREATED
2657 This is the timestamp at creation time of the signature.  It is
2658 representable as a number.
2659
2660 @item GPGME_ATTR_EXPIRE
2661 This is the expiration time of the signature.  It is representable as
2662 a number.
2663
2664 @item GPGME_ATTR_USERID
2665 This is the user ID associated with the signing key.  The user ID is
2666 representable as a number.
2667
2668 @item GPGME_ATTR_NAME
2669 This is the name belonging to a user ID.  It is representable as a string.
2670
2671 @item GPGME_ATTR_EMAIL
2672 This is the email address belonging to a user ID.  It is representable
2673 as a string.
2674
2675 @item GPGME_ATTR_COMMENT
2676 This is the comment belonging to a user ID.  It is representable as a
2677 string.
2678
2679 @item GPGME_ATTR_KEY_REVOKED
2680 This specifies if a key signature is a revocation signature.  It is
2681 representable as a number, and is @code{1} if the key is revoked, and
2682 @code{0} otherwise.
2683
2684 @c @item GPGME_ATTR_KEY_EXPIRED
2685 @c This specifies if a key signature is expired.  It is representable as
2686 @c a number, and is @code{1} if the key is revoked, and @code{0}
2687 @c otherwise.
2688 @c
2689 @item GPGME_ATTR_SIG_CLASS
2690 This specifies the signature class of a key signature.  It is
2691 representable as a number.  The meaning is specific to the crypto
2692 engine.
2693
2694 @item GPGME_ATTR_SIG_CLASS
2695 This specifies the signature class of a key signature.  It is
2696 representable as a number.  The meaning is specific to the crypto
2697 engine.
2698
2699 @item GPGME_ATTR_SIG_STATUS
2700 This is the same value as returned by @code{gpgme_get_sig_status}.
2701 @end table
2702 @end deftp
2703
2704 @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}})
2705 The function @code{gpgme_key_sig_get_string_attr} returns the value of
2706 the string-representable attribute @var{what} of the signature
2707 @var{idx} on the user ID @var{uid_idx} in the key @var{key}.  The
2708 argument @var{reserved} is reserved for later use and should be
2709 @code{NULL}.
2710
2711 The string returned is only valid as long as the key is valid.
2712
2713 The function returns @code{0} if an attribute can't be returned as a
2714 string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx}
2715 out of range, or @var{reserved} not @code{NULL}.
2716 @end deftypefun
2717
2718 @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}})
2719 The function @code{gpgme_key_sig_get_ulong_attr} returns the value of
2720 the number-representable attribute @var{what} of the signature
2721 @var{idx} on the user ID @var{uid_idx} in the key @var{key}.  The
2722 argument @var{reserved} is reserved for later use and should be
2723 @code{NULL}.
2724
2725 The function returns @code{0} if an attribute can't be returned as a
2726 string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx}
2727 out of range, or @var{reserved} not @code{NULL}.
2728 @end deftypefun
2729
2730
2731 @node Manipulating Keys
2732 @subsection Manipulating Keys
2733 @cindex key, manipulation
2734
2735 @deftypefun void gpgme_key_ref (@w{gpgme_key_t @var{key}})
2736 The function @code{gpgme_key_ref} acquires an additional reference for
2737 the key @var{key}.
2738 @end deftypefun
2739
2740 @deftypefun void gpgme_key_unref (@w{gpgme_key_t @var{key}})
2741 The function @code{gpgme_key_unref} releases a reference for the key
2742 @var{key}.  If this was the last reference, the key will be destroyed
2743 and all resources associated to it will be released.
2744 @end deftypefun
2745
2746
2747 The following interface is deprecated and only provided for backward
2748 compatibility.  Don't use it.  It will be removed in a future version
2749 of @acronym{GPGME}.
2750
2751 @deftypefun void gpgme_key_release (@w{gpgme_key_t @var{key}})
2752 The function @code{gpgme_key_release} is equivalent to
2753 @code{gpgme_key_unref}.
2754 @end deftypefun
2755
2756
2757 @node Generating Keys
2758 @subsection Generating Keys
2759 @cindex key, creation
2760 @cindex key ring, add
2761
2762 @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}})
2763 The function @code{gpgme_op_genkey} generates a new key pair in the
2764 context @var{ctx}.  The meaning of @var{public} and @var{secret}
2765 depends on the crypto backend.
2766
2767 GnuPG does not support @var{public} and @var{secret}, they should be
2768 @code{NULL}.  GnuPG will generate a key pair and add it to the
2769 standard key ring.  The fingerprint of the generated key is available
2770 with @code{gpgme_op_genkey_result}.
2771
2772 GpgSM requires @var{public} to be a writable data object.  GpgSM will
2773 generate a secret key (which will be stored by @command{gpg-agent},
2774 and return a certificate request in @var{public}, which then needs to
2775 be signed by the certification authority and imported before it can be
2776 used.  GpgSM does not make the fingerprint available.
2777
2778 The argument @var{parms} specifies parameters for the key in an XML
2779 string.  The details about the format of @var{parms} are specific to
2780 the crypto engine used by @var{ctx}.  Here is an example for GnuPG as
2781 the crypto engine:
2782
2783 @example
2784 <GnupgKeyParms format="internal">
2785 Key-Type: DSA
2786 Key-Length: 1024
2787 Subkey-Type: ELG-E
2788 Subkey-Length: 1024
2789 Name-Real: Joe Tester
2790 Name-Comment: with stupid passphrase
2791 Name-Email: joe@@foo.bar
2792 Expire-Date: 0
2793 Passphrase: abc
2794 </GnupgKeyParms>
2795 @end example
2796
2797 Here is an example for GpgSM as the crypto engine:
2798
2799 @example
2800 <GnupgKeyParms format="internal">
2801 Key-Type: RSA
2802 Key-Length: 1024
2803 Name-DN: C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester
2804 Name-Email: joe@@foo.bar
2805 </GnupgKeyParms>
2806 @end example
2807
2808 Strings should be given in UTF-8 encoding.  The only format supported
2809 for now is ``internal''.  The content of the @code{GnupgKeyParms}
2810 container is passed verbatim to the crypto backend.  Control
2811 statements are not allowed.
2812
2813 After the operation completed successfully, the result can be
2814 retrieved with @code{gpgme_op_genkey_result}.
2815
2816 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
2817 operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
2818 @var{parms} is not a valid XML string, @code{GPG_ERR_NOT_SUPPORTED} if
2819 @var{public} or @var{secret} is not valid, and @code{GPG_ERR_GENERAL}
2820 if no key was created by the backend.
2821 @end deftypefun
2822
2823 @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}})
2824 The function @code{gpgme_op_genkey_start} initiates a
2825 @code{gpgme_op_genkey} operation.  It can be completed by calling
2826 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
2827
2828 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
2829 operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
2830 @var{parms} is not a valid XML string, and
2831 @code{GPG_ERR_NOT_SUPPORTED} if @var{public} or @var{secret} is not
2832 @code{NULL}.
2833 @end deftypefun
2834
2835 @deftp {Data type} {gpgme_genkey_result_t}
2836 This is a pointer to a structure used to store the result of a
2837 @code{gpgme_op_genkey} operation.  After successfully generating a
2838 key, you can retrieve the pointer to the result with
2839 @code{gpgme_op_genkey_result}.  The structure contains the following
2840 members:
2841
2842 @table @code
2843 @item unsigned int primary : 1
2844 This is a flag that is set to 1 if a primary key was created and to 0
2845 if not.
2846
2847 @item unsigned int sub : 1
2848 This is a flag that is set to 1 if a subkey was created and to 0
2849 if not.
2850
2851 @item char *fpr
2852 This is the fingerprint of the key that was created.  If both a
2853 primary and a sub key were generated, the fingerprint of the primary
2854 key will be returned.  If the crypto engine does not provide the
2855 fingerprint, @code{fpr} will be a null pointer.
2856 @end table
2857 @end deftp
2858
2859 @deftypefun gpgme_genkey_result_t gpgme_op_genkey_result (@w{gpgme_ctx_t @var{ctx}})
2860 The function @code{gpgme_op_genkey_result} returns a
2861 @code{gpgme_genkey_result_t} pointer to a structure holding the result of
2862 a @code{gpgme_op_genkey} operation.  The pointer is only valid if the
2863 last operation on the context was a @code{gpgme_op_genkey} or
2864 @code{gpgme_op_genkey_start} operation, and if this operation finished
2865 successfully.  The returned pointer is only valid until the next
2866 operation is started on the context.
2867 @end deftypefun
2868
2869
2870 @node Exporting Keys
2871 @subsection Exporting Keys
2872 @cindex key, export
2873 @cindex key ring, export from
2874
2875 @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}})
2876 The function @code{gpgme_op_export} extracts public keys and returns
2877 them in the data buffer @var{keydata}.  The output format of the key
2878 data returned is determined by the @acronym{ASCII} armor attribute set
2879 for the context @var{ctx}.
2880
2881 If @var{pattern} is @code{NULL}, all available keys are returned.
2882 Otherwise, @var{pattern} contains an engine specific expression that
2883 is used to limit the list to all keys matching the pattern.
2884
2885 @var{reserved} is reserved for future use and must be @code{0}.
2886
2887 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
2888 operation completed successfully, @code{GPG_ERR_INV_VALUE} if
2889 @var{keydata} is not a valid empty data buffer, and passes through any
2890 errors that are reported by the crypto engine support routines.
2891 @end deftypefun
2892
2893 @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}})
2894 The function @code{gpgme_op_export_start} initiates a
2895 @code{gpgme_op_export} operation.  It can be completed by calling
2896 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
2897
2898 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
2899 operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
2900 if @var{keydata} is not a valid empty data buffer.
2901 @end deftypefun
2902
2903 @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}})
2904 The function @code{gpgme_op_export} extracts public keys and returns
2905 them in the data buffer @var{keydata}.  The output format of the key
2906 data returned is determined by the @acronym{ASCII} armor attribute set
2907 for the context @var{ctx}.
2908
2909 If @var{pattern} or @var{*pattern} is @code{NULL}, all available keys
2910 are returned.  Otherwise, @var{pattern} is a @code{NULL} terminated
2911 array of strings that are used to limit the list to all keys matching
2912 at least one of the patterns verbatim.
2913
2914 @var{reserved} is reserved for future use and must be @code{0}.
2915
2916 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
2917 operation completed successfully, @code{GPG_ERR_INV_VALUE} if
2918 @var{keydata} is not a valid empty data buffer, and passes through any
2919 errors that are reported by the crypto engine support routines.
2920 @end deftypefun
2921
2922 @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}})
2923 The function @code{gpgme_op_export_ext_start} initiates a
2924 @code{gpgme_op_export_ext} operation.  It can be completed by calling
2925 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
2926
2927 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
2928 operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
2929 if @var{keydata} is not a valid empty data buffer.
2930 @end deftypefun
2931
2932
2933 @node Importing Keys
2934 @subsection Importing Keys
2935 @cindex key, import
2936 @cindex key ring, import to
2937
2938 @deftypefun gpgme_error_t gpgme_op_import (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}})
2939 The function @code{gpgme_op_import} adds the keys in the data buffer
2940 @var{keydata} to the key ring of the crypto engine used by @var{ctx}.
2941 The format of @var{keydata} can be @acronym{ASCII} armored, for example,
2942 but the details are specific to the crypto engine.
2943
2944 After the operation completed successfully, the result can be
2945 retrieved with @code{gpgme_op_import_result}.
2946
2947 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
2948 import was completed successfully, @code{GPG_ERR_INV_VALUE} if
2949 @var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer,
2950 and @code{GPG_ERR_NO_DATA} if @var{keydata} is an empty data buffer.
2951 @end deftypefun
2952
2953 @deftypefun gpgme_error_t gpgme_op_import_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}})
2954 The function @code{gpgme_op_import_start} initiates a
2955 @code{gpgme_op_import} operation.  It can be completed by calling
2956 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
2957
2958 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
2959 import could be started successfully, @code{GPG_ERR_INV_VALUE} if
2960 @var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer,
2961 and @code{GPG_ERR_NO_DATA} if @var{keydata} is an empty data buffer.
2962 @end deftypefun
2963
2964 @deftp {Data type} {gpgme_import_status_t}
2965 This is a pointer to a structure used to store a part of the result of
2966 a @code{gpgme_op_import} operation.  For each considered key one
2967 status is added that contains information about the result of the
2968 import.  The structure contains the following members:
2969
2970 @table @code
2971 @item gpgme_import_status_t next
2972 This is a pointer to the next status structure in the linked list, or
2973 @code{NULL} if this is the last element.
2974
2975 @item char *fpr
2976 This is the fingerprint of the key that was considered.
2977
2978 @item gpgme_error_t result
2979 If the import was not successful, this is the error value that caused
2980 the import to fail.  Otherwise the error code is
2981 @code{GPG_ERR_NO_ERROR}.
2982
2983 @item unsigned int status
2984 This is a bit-wise OR of the following flags that give more
2985 information about what part of the key was imported.  If the key was
2986 already known, this might be 0.
2987
2988 @table @code
2989 @item GPGME_IMPORT_NEW
2990 The key was new.
2991
2992 @item GPGME_IMPORT_UID
2993 The key contained new user IDs.
2994
2995 @item GPGME_IMPORT_SIG
2996 The key contained new signatures.
2997
2998 @item GPGME_IMPORT_SUBKEY
2999 The key contained new sub keys.
3000
3001 @item GPGME_IMPORT_SECRET
3002 The key contained a secret key.
3003 @end table
3004 @end table
3005 @end deftp
3006
3007 @deftp {Data type} {gpgme_import_result_t}
3008 This is a pointer to a structure used to store the result of a
3009 @code{gpgme_op_import} operation.  After a successful import
3010 operation, you can retrieve the pointer to the result with
3011 @code{gpgme_op_import_result}.  The structure contains the following
3012 members:
3013
3014 @table @code
3015 @item int considered
3016 The total number of considered keys.
3017
3018 @item int no_user_id
3019 The number of keys without user ID.
3020
3021 @item int imported
3022 The total number of imported keys.
3023
3024 @item imported_rsa
3025 The number of imported RSA keys.
3026
3027 @item unchanged
3028 The number of unchanged keys.
3029
3030 @item new_user_ids
3031 The number of new user IDs.
3032
3033 @item new_sub_keys
3034 The number of new sub keys.
3035
3036 @item new_signatures
3037 The number of new signatures.
3038
3039 @item new_revocations
3040 The number of new revocations.
3041
3042 @item secret_read
3043 The total number of secret keys read.
3044
3045 @item secret_imported
3046 The number of imported secret keys.
3047
3048 @item secret_unchanged
3049 The number of unchanged secret keys.
3050
3051 @item not_imported
3052 The number of keys not imported.
3053
3054 @item gpgme_import_status_t imports
3055 A list of gpgme_import_status_t objects which contain more information
3056 about the keys for which an import was attempted.
3057 @end table
3058 @end deftp
3059
3060 @deftypefun gpgme_import_result_t gpgme_op_import_result (@w{gpgme_ctx_t @var{ctx}})
3061 The function @code{gpgme_op_import_result} returns a
3062 @code{gpgme_import_result_t} pointer to a structure holding the result
3063 of a @code{gpgme_op_import} operation.  The pointer is only valid if
3064 the last operation on the context was a @code{gpgme_op_import} or
3065 @code{gpgme_op_import_start} operation, and if this operation finished
3066 successfully.  The returned pointer is only valid until the next
3067 operation is started on the context.
3068 @end deftypefun
3069
3070 The following interface is deprecated and only provided for backward
3071 compatibility.  Don't use it.  It will be removed in a future version
3072 of @acronym{GPGME}.
3073
3074 @deftypefun gpgme_error_t gpgme_op_import_ext (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}}, @w{int *@var{nr}})
3075 The function @code{gpgme_op_import_ext} is equivalent to:
3076
3077 @example
3078   gpgme_error_t err = gpgme_op_import (ctx, keydata);
3079   if (!err)
3080     @{
3081       gpgme_import_result_t result = gpgme_op_import_result (ctx);
3082       *nr = result->considered;
3083     @}
3084 @end example
3085 @end deftypefun
3086
3087
3088 @node Deleting Keys
3089 @subsection Deleting Keys
3090 @cindex key, delete
3091 @cindex key ring, delete from
3092
3093 @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}})
3094 The function @code{gpgme_op_delete} deletes the key @var{key} from the
3095 key ring of the crypto engine used by @var{ctx}.  If
3096 @var{allow_secret} is @code{0}, only public keys are deleted,
3097 otherwise secret keys are deleted as well, if that is supported.
3098
3099 The function returns the error code @code{GPG_ERR_NO_ERROR} if the key
3100 was deleted successfully, @code{GPG_ERR_INV_VALUE} if @var{ctx} or
3101 @var{key} is not a valid pointer, @code{GPG_ERR_NO_PUBKEY} if
3102 @var{key} could not be found in the keyring,
3103 @code{GPG_ERR_AMBIGUOUS_NAME} if the key was not specified
3104 unambiguously, and @code{GPG_ERR_CONFLICT} if the secret key for
3105 @var{key} is available, but @var{allow_secret} is zero.
3106 @end deftypefun
3107
3108 @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}})
3109 The function @code{gpgme_op_delete_start} initiates a
3110 @code{gpgme_op_delete} operation.  It can be completed by calling
3111 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
3112
3113 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3114 operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
3115 @var{ctx} or @var{key} is not a valid pointer.
3116 @end deftypefun
3117
3118
3119 @node Trust Item Management
3120 @section Trust Item Management
3121 @cindex trust item
3122
3123 @strong{Caution:} The trust items interface is experimental.
3124
3125 @deftp {Data type} gpgme_trust_item_t
3126 The @code{gpgme_trust_item_t} type is a pointer to a trust item object.
3127 It has the following members:
3128
3129 @table @code
3130 @item char *keyid
3131 This is a string describing the key to which this trust items belongs.
3132
3133 @item int type
3134 This is the type of the trust item.  A value of 1 refers to a key, a
3135 value of 2 refers to a user ID.
3136
3137 @item int level
3138 This is the trust level.
3139
3140 @item char *owner_trust
3141 The owner trust if @code{type} is 1.
3142
3143 @item char *validity
3144 The calculated validity.
3145
3146 @item char *name
3147 The user name if @code{type} is 2.
3148 @end table
3149 @end deftp
3150
3151 @menu
3152 * Listing Trust Items::           Browsing the list of available trust items.
3153 * Information About Trust Items:: Requesting information about trust items.
3154 * Manipulating Trust Items::      Operations on trust items.
3155 @end menu
3156
3157
3158 @node Listing Trust Items
3159 @subsection Listing Trust Items
3160 @cindex trust item list
3161
3162 @deftypefun gpgme_error_t gpgme_op_trustlist_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{max_level}})
3163 The function @code{gpgme_op_trustlist_start} initiates a trust item
3164 listing operation inside the context @var{ctx}.  It sets everything up
3165 so that subsequent invocations of @code{gpgme_op_trustlist_next} return
3166 the trust items in the list.
3167
3168 The string @var{pattern} contains an engine specific expression that
3169 is used to limit the list to all trust items matching the pattern.  It
3170 can not be the empty string.
3171
3172 The argument @var{max_level} is currently ignored.
3173
3174 The context will be busy until either all trust items are received
3175 (and @code{gpgme_op_trustlist_next} returns @code{GPG_ERR_EOF}), or
3176 @code{gpgme_op_trustlist_end} is called to finish the operation.
3177
3178 The function returns the error code @code{GPG_ERR_INV_VALUE} if
3179 @var{ctx} is not a valid pointer, and passes through any errors that
3180 are reported by the crypto engine support routines.
3181 @end deftypefun
3182
3183 @deftypefun gpgme_error_t gpgme_op_trustlist_next (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_trust_item_t *@var{r_item}})
3184 The function @code{gpgme_op_trustlist_next} returns the next trust
3185 item in the list created by a previous @code{gpgme_op_trustlist_start}
3186 operation in the context @var{ctx}.  The trust item can be destroyed
3187 with @code{gpgme_trust_item_release}.  @xref{Manipulating Trust Items}.
3188
3189 This is the only way to get at @code{gpgme_trust_item_t} objects in
3190 @acronym{GPGME}.
3191
3192 If the last trust item in the list has already been returned,
3193 @code{gpgme_op_trustlist_next} returns @code{GPG_ERR_EOF}.
3194
3195 The function returns the error code @code{GPG_ERR_INV_VALUE} if @var{ctx} or
3196 @var{r_item} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if
3197 there is not enough memory for the operation.
3198 @end deftypefun
3199
3200 @deftypefun gpgme_error_t gpgme_op_trustlist_end (@w{gpgme_ctx_t @var{ctx}})
3201 The function @code{gpgme_op_trustlist_next} ends a pending key list
3202 operation in the context @var{ctx}.
3203
3204 The function returns the error code @code{GPG_ERR_INV_VALUE} if
3205 @var{ctx} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if at some
3206 time during the operation there was not enough memory available.
3207 @end deftypefun
3208
3209
3210 @node Information About Trust Items
3211 @subsection Information About Trust Items
3212 @cindex trust item, information about
3213 @cindex trust item, attributes
3214 @cindex attributes, of a trust item
3215
3216 The following interfaces are deprecated and only provided for backward
3217 compatibility.  Don't use them.  They will be removed in a future
3218 version of @acronym{GPGME}.
3219
3220 Trust items have attributes which can be queried using the interfaces
3221 below.  The attribute identifiers are shared with those for key
3222 attributes.  @xref{Information About Keys}.
3223
3224 @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}})
3225 The function @code{gpgme_trust_item_get_string_attr} returns the value
3226 of the string-representable attribute @var{what} of trust item
3227 @var{item}.  The arguments @var{idx} and @var{reserved} are reserved
3228 for later use and should be @code{0} and @code{NULL} respectively.
3229
3230 The string returned is only valid as long as the key is valid.
3231
3232 The function returns @code{0} if an attribute can't be returned as a
3233 string, @var{key} is not a valid pointer, @var{idx} out of range,
3234 or @var{reserved} not @code{NULL}.
3235 @end deftypefun
3236
3237 @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}})
3238 The function @code{gpgme_trust_item_get_int_attr} returns the value of
3239 the number-representable attribute @var{what} of trust item
3240 @var{item}.  If the attribute occurs more than once in the trust item,
3241 the index is specified by @var{idx}.  However, currently no such
3242 attribute exists, so @var{idx} should be @code{0}.  The argument
3243 @var{reserved} is reserved for later use and should be @code{NULL}.
3244
3245 The function returns @code{0} if the attribute can't be returned as a
3246 number, @var{key} is not a valid pointer, @var{idx} out of range,
3247 or @var{reserved} not @code{NULL}.
3248 @end deftypefun
3249
3250
3251 @node Manipulating Trust Items
3252 @subsection Manipulating Trust Items
3253 @cindex trust item, manipulation
3254
3255 @deftypefun void gpgme_trust_item_ref (@w{gpgme_trust_item_t @var{item}})
3256 The function @code{gpgme_trust_item_ref} acquires an additional
3257 reference for the trust item @var{item}.
3258 @end deftypefun
3259
3260 @deftypefun void gpgme_trust_item_unref (@w{gpgme_trust_item_t @var{item}})
3261 The function @code{gpgme_trust_item_unref} releases a reference for
3262 the trust item @var{item}.  If this was the last reference, the trust
3263 item will be destroyed and all resources associated to it will be
3264 released.
3265 @end deftypefun
3266
3267
3268 The following interface is deprecated and only provided for backward
3269 compatibility.  Don't use it.  It will be removed in a future version
3270 of @acronym{GPGME}.
3271
3272 @deftypefun void gpgme_trust_item_release (@w{gpgme_trust_item_t @var{item}})
3273 The function @code{gpgme_trust_item_release} is an alias for
3274 @code{gpgme_trust_item_unref}.
3275 @end deftypefun
3276
3277
3278 @node Crypto Operations
3279 @section Crypto Operations
3280 @cindex cryptographic operation
3281
3282 Sometimes, the result of a crypto operation returns a list of invalid
3283 keys encountered in processing the request.  The following structure
3284 is used to hold information about such a key.
3285
3286 @deftp {Data type} {gpgme_invalid_key_t}
3287 This is a pointer to a structure used to store a part of the result of
3288 a crypto operation which takes user IDs as one input parameter.  The
3289 structure contains the following members:
3290
3291 @table @code
3292 @item gpgme_invalid_key_t next
3293 This is a pointer to the next invalid key structure in the linked
3294 list, or @code{NULL} if this is the last element.
3295
3296 @item char *fpr
3297 The fingerprint or key ID of the invalid key encountered.
3298
3299 @item gpgme_error_t reason
3300 An error code describing the reason why the key was found invalid.
3301 @end table
3302 @end deftp
3303
3304
3305 @menu
3306 * Decrypt::                       Decrypting a ciphertext.
3307 * Verify::                        Verifying a signature.
3308 * Decrypt and Verify::            Decrypting a signed ciphertext.
3309 * Sign::                          Creating a signature.
3310 * Encrypt::                       Encrypting a plaintext.
3311 @end menu
3312
3313
3314 @node Decrypt
3315 @subsection Decrypt
3316 @cindex decryption
3317 @cindex cryptographic operation, decryption
3318
3319 @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}})
3320 The function @code{gpgme_op_decrypt} decrypts the ciphertext in the
3321 data object @var{cipher} and stores it into the data object
3322 @var{plain}.
3323
3324 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3325 ciphertext could be decrypted successfully, @code{GPG_ERR_INV_VALUE}
3326 if @var{ctx}, @var{cipher} or @var{plain} is not a valid pointer,
3327 @code{GPG_ERR_NO_DATA} if @var{cipher} does not contain any data to
3328 decrypt, @code{GPG_ERR_DECRYPT_FAILED} if @var{cipher} is not a valid
3329 cipher text, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the
3330 secret key could not be retrieved, and passes through any errors that
3331 are reported by the crypto engine support routines.
3332 @end deftypefun
3333
3334 @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}})
3335 The function @code{gpgme_op_decrypt_start} initiates a
3336 @code{gpgme_op_decrypt} operation.  It can be completed by calling
3337 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
3338
3339 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3340 operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
3341 if @var{cipher} or @var{plain} is not a valid pointer.
3342 @end deftypefun
3343
3344 @deftp {Data type} {gpgme_decrypt_result_t}
3345 This is a pointer to a structure used to store the result of a
3346 @code{gpgme_op_decrypt} operation.  After successfully encrypting
3347 data, you can retrieve the pointer to the result with
3348 @code{gpgme_op_decrypt_result}.  The structure contains the following
3349 members:
3350
3351 @table @code
3352 @item char *unsupported_algorithm
3353 If an unsupported algorithm was encountered, this string describes the
3354 algorithm that is not supported.
3355 @end table
3356 @end deftp
3357
3358 @deftypefun gpgme_decrypt_result_t gpgme_op_decrypt_result (@w{gpgme_ctx_t @var{ctx}})
3359 The function @code{gpgme_op_decrypt_result} returns a
3360 @code{gpgme_decrypt_result_t} pointer to a structure holding the
3361 result of a @code{gpgme_op_decrypt} operation.  The pointer is only
3362 valid if the last operation on the context was a
3363 @code{gpgme_op_decrypt} or @code{gpgme_op_decrypt_start} operation.
3364 If the operation failed this might be a @code{NULL} pointer.  The
3365 returned pointer is only valid until the next operation is started on
3366 the context.
3367 @end deftypefun
3368
3369
3370 @node Verify
3371 @subsection Verify
3372 @cindex verification
3373 @cindex signature, verification
3374 @cindex cryptographic operation, verification
3375 @cindex cryptographic operation, signature check
3376
3377 @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}})
3378 The function @code{gpgme_op_verify} verifies that the signature in the
3379 data object @var{sig} is a valid signature.  If @var{sig} is a
3380 detached signature, then the signed text should be provided in
3381 @var{signed_text} and @var{plain} should be a null pointer.
3382 Otherwise, if @var{sig} is a normal (or cleartext) signature,
3383 @var{signed_text} should be a null pointer and @var{plain} should be a
3384 writable data object that will contain the plaintext after successful
3385 verification.
3386
3387 The results of the individual signature verifications can be retrieved
3388 with @code{gpgme_op_verify_result}.
3389
3390 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3391 operation could be completed successfully, @code{GPG_ERR_INV_VALUE} if
3392 @var{ctx}, @var{sig} or @var{plain} is not a valid pointer,
3393 @code{GPG_ERR_NO_DATA} if @var{sig} does not contain any data to
3394 verify, and passes through any errors that are reported by the crypto
3395 engine support routines.
3396 @end deftypefun
3397
3398 @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}})
3399 The function @code{gpgme_op_verify_start} initiates a
3400 @code{gpgme_op_verify} operation.  It can be completed by calling
3401 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
3402
3403 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3404 operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
3405 @var{ctx}, @var{sig} or @var{plain} is not a valid pointer, and
3406 @code{GPG_ERR_NO_DATA} if @var{sig} or @var{plain} does not contain
3407 any data to verify.
3408 @end deftypefun
3409
3410 @deftp {Data type} {gpgme_sig_notation_t}
3411 This is a pointer to a structure used to store a part of the result of
3412 a @code{gpgme_op_verify} operation.  The structure contains the
3413 following members:
3414
3415 @table @code
3416 @item gpgme_sig_notation_t next
3417 This is a pointer to the next new signature notation structure in the
3418 linked list, or @code{NULL} if this is the last element.
3419
3420 @item char *name
3421 The name of the notation field.  If this is @code{NULL}, then the
3422 member @code{value} will contain a policy URL.
3423
3424 @item char *value
3425 The value of the notation field.  If @code{name} is @code{NULL}, then
3426 this is a policy URL.
3427 @end table
3428 @end deftp
3429
3430 @deftp {Data type} {gpgme_signature_t}
3431 This is a pointer to a structure used to store a part of the result of
3432 a @code{gpgme_op_verify} operation.  The structure contains the
3433 following members:
3434
3435 @table @code
3436 @item gpgme_signature_t next
3437 This is a pointer to the next new signature structure in the linked
3438 list, or @code{NULL} if this is the last element.
3439
3440 @item gpgme_sigsum_t summary;
3441 This is a bit vector giving a summary of the signature status.  It
3442 provides an easy interface to a defined semantic of the signature
3443 status.  Checking just one bit is sufficient to see whether a
3444 signature is valid without any restrictions.
3445
3446 The defined bits are:
3447   @table @code
3448   @item GPGME_SIGSUM_VALID
3449   The signature is fully valid.
3450
3451   @item GPGME_SIGSUM_GREEN
3452   The signature is good but one might want to display some extra
3453   information.  Check the other bits.
3454
3455   @item GPGME_SIGSUM_RED
3456   The signature is bad. It might be useful to check other bits and
3457   display more information, i.e. a revoked certificate might not render a
3458   signature invalid when the message was received prior to the cause for
3459   the revocation.
3460
3461   @item GPGME_SIGSUM_KEY_REVOKED
3462   The key or at least one certificate has been revoked.
3463
3464   @item GPGME_SIGSUM_KEY_EXPIRED
3465   The key or one of the certificates has expired. It is probably a good
3466   idea to display the date of the expiration.
3467
3468   @item GPGME_SIGSUM_SIG_EXPIRED
3469   The signature has expired.
3470
3471   @item GPGME_SIGSUM_KEY_MISSING
3472   Can't verify due to a missing key or certificate.
3473
3474   @item GPGME_SIGSUM_CRL_MISSING
3475   The CRL (or an equivalent mechanism) is not available. 
3476
3477   @item GPGME_SIGSUM_CRL_TOO_OLD
3478   Available CRL is too old.
3479
3480   @item GPGME_SIGSUM_BAD_POLICY
3481   A policy requirement was not met. 
3482
3483   @item GPGME_SIGSUM_SYS_ERROR
3484   A system error occured. 
3485   @end table
3486
3487 @item char *fpr
3488 This is the fingerprint or key ID of the signature.
3489
3490 @item gpgme_error_t status
3491 This is the status of the signature.  In particular, the following
3492 status codes are of interest:
3493
3494   @table @code
3495   @item GPG_ERR_NO_ERROR
3496   This status indicates that the signature is valid.  For the combined
3497   result this status means that all signatures are valid.
3498
3499   @item GPG_ERR_SIG_EXPIRED
3500   This status indicates that the signature is valid but expired.  For
3501   the combined result this status means that all signatures are valid
3502   and expired.
3503
3504   @item GPG_ERR_KEY_EXPIRED
3505   This status indicates that the signature is valid but the key used to
3506   verify the signature has expired.  For the combined result this status
3507   means that all signatures are valid and all keys are expired.
3508
3509   @item GPG_ERR_BAD_SIGNATURE
3510   This status indicates that the signature is invalid.  For the combined
3511   result this status means that all signatures are invalid.
3512
3513   @item GPG_ERR_NO_PUBKEY
3514   This status indicates that the signature could not be verified due to
3515   a missing key.  For the combined result this status means that all
3516   signatures could not be checked due to missing keys.
3517
3518   @item GPG_ERR_GENERAL
3519   This status indicates that there was some other error which prevented
3520   the signature verification.
3521   @end table
3522
3523 @item gpgme_sig_notation_t notations
3524 This is a linked list with the notation data and policy URLs.
3525
3526 @item unsigned long timestamp
3527 The creation timestamp of this signature.
3528
3529 @item unsigned long exp_timestamp
3530 The expiration timestamp of this signature, or 0 if the signature does
3531 not expire.
3532
3533 @item int wrong_key_usage : 1;
3534 This is true if the key was not used according to its policy.
3535
3536 @item gpgme_validity_t validity
3537 The validity of the signature.
3538
3539 @item gpgme_error_t validity_reason
3540 If a signature is not valid, this provides a reason why.
3541
3542 @end table
3543 @end deftp
3544
3545 @deftp {Data type} {gpgme_verify_result_t}
3546 This is a pointer to a structure used to store the result of a
3547 @code{gpgme_op_verify} operation.  After verifying a signature, you
3548 can retrieve the pointer to the result with
3549 @code{gpgme_op_verify_result}.  If the operation failed this might be
3550 a @code{NULL} pointer.  The structure contains the following member:
3551
3552 @table @code
3553 @item gpgme_signature_t signatures
3554 A linked list with information about all signatures for which a
3555 verification was attempted.
3556 @end table
3557 @end deftp
3558
3559 @deftypefun gpgme_sign_result_t gpgme_op_verify_result (@w{gpgme_ctx_t @var{ctx}})
3560 The function @code{gpgme_op_verify_result} returns a
3561 @code{gpgme_verify_result_t} pointer to a structure holding the result of
3562 a @code{gpgme_op_verify} operation.  The pointer is only valid if the
3563 last operation on the context was a @code{gpgme_op_verify} or
3564 @code{gpgme_op_verify_start} operation, and if this operation finished
3565 successfully.  The returned pointer is only valid until the next
3566 operation is started on the context.
3567 @end deftypefun
3568
3569
3570 The following interfaces are deprecated and only provided for backward
3571 compatibility.  Don't use them.  They will be removed in a future
3572 version of @acronym{GPGME}.
3573
3574 @deftp {Data type} {enum gpgme_sig_stat_t}
3575 @tindex gpgme_sig_stat_t
3576 The @code{gpgme_sig_stat_t} type holds the result of a signature check, or
3577 the combined result of all signatures.  The following results are
3578 possible:
3579
3580 @table @code
3581 @item GPGME_SIG_STAT_NONE
3582 This status should not occur in normal operation.
3583
3584 @item GPGME_SIG_STAT_GOOD
3585 This status indicates that the signature is valid.  For the combined
3586 result this status means that all signatures are valid.
3587
3588 @item GPGME_SIG_STAT_GOOD_EXP
3589 This status indicates that the signature is valid but expired.  For
3590 the combined result this status means that all signatures are valid
3591 and expired.
3592
3593 @item GPGME_SIG_STAT_GOOD_EXPKEY
3594 This status indicates that the signature is valid but the key used to
3595 verify the signature has expired.  For the combined result this status
3596 means that all signatures are valid and all keys are expired.
3597
3598 @item GPGME_SIG_STAT_BAD
3599 This status indicates that the signature is invalid.  For the combined
3600 result this status means that all signatures are invalid.
3601
3602 @item GPGME_SIG_STAT_NOKEY
3603 This status indicates that the signature could not be verified due to
3604 a missing key.  For the combined result this status means that all
3605 signatures could not be checked due to missing keys.
3606
3607 @item GPGME_SIG_STAT_NOSIG
3608 This status indicates that the signature data provided was not a real
3609 signature.
3610
3611 @item GPGME_SIG_STAT_ERROR
3612 This status indicates that there was some other error which prevented
3613 the signature verification.
3614
3615 @item GPGME_SIG_STAT_DIFF
3616 For the combined result this status means that at least two signatures
3617 have a different status.  You can get each key's status with
3618 @code{gpgme_get_sig_status}.
3619 @end table
3620 @end deftp
3621
3622 @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}})
3623 The function @code{gpgme_get_sig_status} is equivalent to:
3624  
3625 @example
3626   gpgme_verify_result_t result;
3627   gpgme_signature_t sig;
3628
3629   result = gpgme_op_verify_result (ctx);
3630   sig = result->signatures;
3631
3632   while (sig && idx)
3633     @{
3634       sig = sig->next;
3635       idx--;
3636     @}
3637   if (!sig || idx)
3638     return NULL;
3639
3640   if (r_stat)
3641     @{
3642       switch (gpg_err_code (sig->status))
3643         @{
3644         case GPG_ERR_NO_ERROR:
3645           *r_stat = GPGME_SIG_STAT_GOOD;
3646           break;
3647           
3648         case GPG_ERR_BAD_SIGNATURE:
3649           *r_stat = GPGME_SIG_STAT_BAD;
3650           break;
3651           
3652         case GPG_ERR_NO_PUBKEY:
3653           *r_stat = GPGME_SIG_STAT_NOKEY;
3654           break;
3655           
3656         case GPG_ERR_NO_DATA:
3657           *r_stat = GPGME_SIG_STAT_NOSIG;
3658           break;
3659           
3660         case GPG_ERR_SIG_EXPIRED:
3661           *r_stat = GPGME_SIG_STAT_GOOD_EXP;
3662           break;
3663           
3664         case GPG_ERR_KEY_EXPIRED:
3665           *r_stat = GPGME_SIG_STAT_GOOD_EXPKEY;
3666           break;
3667           
3668         default:
3669           *r_stat = GPGME_SIG_STAT_ERROR;
3670           break;
3671         @}
3672     @}
3673   if (r_created)
3674     *r_created = sig->timestamp;
3675   return sig->fpr;
3676 @end example
3677 @end deftypefun
3678
3679 @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}})
3680 The function @code{gpgme_get_sig_string_attr} is equivalent to:
3681  
3682 @example
3683   gpgme_verify_result_t result;
3684   gpgme_signature_t sig;
3685
3686   result = gpgme_op_verify_result (ctx);
3687   sig = result->signatures;
3688
3689   while (sig && idx)
3690     @{
3691       sig = sig->next;
3692       idx--;
3693     @}
3694   if (!sig || idx)
3695     return NULL;
3696
3697   switch (what)
3698     @{
3699     case GPGME_ATTR_FPR:
3700       return sig->fpr;
3701
3702     case GPGME_ATTR_ERRTOK:
3703       if (whatidx == 1)
3704         return sig->wrong_key_usage ? "Wrong_Key_Usage" : "";
3705       else
3706         return "";
3707     default:
3708       break;
3709     @}
3710
3711   return NULL;
3712 @end example
3713 @end deftypefun
3714
3715 @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}})
3716 The function @code{gpgme_get_sig_ulong_attr} is equivalent to:
3717  
3718 @example
3719   gpgme_verify_result_t result;
3720   gpgme_signature_t sig;
3721
3722   result = gpgme_op_verify_result (ctx);
3723   sig = result->signatures;
3724
3725   while (sig && idx)
3726     @{
3727       sig = sig->next;
3728       idx--;
3729     @}
3730   if (!sig || idx)
3731     return 0;
3732
3733   switch (what)
3734     @{
3735     case GPGME_ATTR_CREATED:
3736       return sig->timestamp;
3737
3738     case GPGME_ATTR_EXPIRE:
3739       return sig->exp_timestamp;
3740
3741     case GPGME_ATTR_VALIDITY:
3742       return (unsigned long) sig->validity;
3743
3744     case GPGME_ATTR_SIG_STATUS:
3745       switch (sig->status)
3746         @{
3747         case GPG_ERR_NO_ERROR:
3748           return GPGME_SIG_STAT_GOOD;
3749           
3750         case GPG_ERR_BAD_SIGNATURE:
3751           return GPGME_SIG_STAT_BAD;
3752           
3753         case GPG_ERR_NO_PUBKEY:
3754           return GPGME_SIG_STAT_NOKEY;
3755           
3756         case GPG_ERR_NO_DATA:
3757           return GPGME_SIG_STAT_NOSIG;
3758           
3759         case GPG_ERR_SIG_EXPIRED:
3760           return GPGME_SIG_STAT_GOOD_EXP;
3761           
3762         case GPG_ERR_KEY_EXPIRED:
3763           return GPGME_SIG_STAT_GOOD_EXPKEY;
3764           
3765         default:
3766           return GPGME_SIG_STAT_ERROR;
3767         @}
3768
3769     case GPGME_ATTR_SIG_SUMMARY:
3770       return sig->summary;
3771
3772     default:
3773       break;
3774     @}
3775   return 0;
3776 @end example
3777 @end deftypefun
3778
3779 @deftypefun {const char *} gpgme_get_sig_key (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_key_t *@var{r_key}})
3780 The function @code{gpgme_get_sig_key} is equivalent to:
3781
3782 @example
3783   gpgme_verify_result_t result;
3784   gpgme_signature_t sig;
3785
3786   result = gpgme_op_verify_result (ctx);
3787   sig = result->signatures;
3788
3789   while (sig && idx)
3790     @{
3791       sig = sig->next;
3792       idx--;
3793     @}
3794   if (!sig || idx)
3795     return gpg_error (GPG_ERR_EOF);
3796
3797   return gpgme_get_key (ctx, sig->fpr, r_key, 0, 0);
3798 @end example
3799 @end deftypefun
3800
3801
3802 @node Decrypt and Verify
3803 @subsection Decrypt and Verify
3804 @cindex decryption and verification
3805 @cindex verification and decryption
3806 @cindex signature check
3807 @cindex cryptographic operation, decryption and verification
3808
3809 @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}})
3810 The function @code{gpgme_op_decrypt_verify} decrypts the ciphertext in
3811 the data object @var{cipher} and stores it into the data object
3812 @var{plain}.  If @var{cipher} contains signatures, they will be
3813 verified.
3814
3815 After the operation completed, @code{gpgme_op_decrypt_result} and
3816 @code{gpgme_op_verify_result} can be used to retrieve more information
3817 about the signatures.
3818
3819 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3820 ciphertext could be decrypted successfully, @code{GPG_ERR_INV_VALUE}
3821 if @var{ctx}, @var{cipher} or @var{plain} is not a valid pointer,
3822 @code{GPG_ERR_NO_DATA} if @var{cipher} does not contain any data to
3823 decrypt, @code{GPG_ERR_DECRYPT_FAILED} if @var{cipher} is not a valid
3824 cipher text, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the
3825 secret key could not be retrieved, and passes through any errors that
3826 are reported by the crypto engine support routines.
3827 @end deftypefun
3828
3829 @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}})
3830 The function @code{gpgme_op_decrypt_verify_start} initiates a
3831 @code{gpgme_op_decrypt_verify} operation.  It can be completed by
3832 calling @code{gpgme_wait} on the context.  @xref{Waiting For
3833 Completion}.
3834
3835 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3836 operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
3837 @var{ctx}, @var{cipher}, @var{plain} or @var{r_stat} is not a valid
3838 pointer, and @code{GPG_ERR_NO_DATA} if @var{cipher} does not contain
3839 any data to decrypt.
3840 @end deftypefun
3841
3842
3843 @node Sign
3844 @subsection Sign
3845 @cindex signature, creation
3846 @cindex sign
3847 @cindex cryptographic operation, signing
3848
3849 A signature can contain signatures by one or more keys.  The set of
3850 keys used to create a signatures is contained in a context, and is
3851 applied to all following signing operations in this context (until the
3852 set is changed).
3853
3854 @menu
3855 * Selecting Signers::             How to choose the keys to sign with.
3856 * Creating a Signature::          How to create a signature.
3857 @end menu
3858
3859
3860 @node Selecting Signers
3861 @subsubsection Selecting Signers
3862 @cindex signature, selecting signers
3863 @cindex signers, selecting
3864
3865 @deftypefun void gpgme_signers_clear (@w{gpgme_ctx_t @var{ctx}})
3866 The function @code{gpgme_signers_clear} releases a reference for each
3867 key on the signers list and removes the list of signers from the
3868 context @var{ctx}.
3869
3870 Every context starts with an empty list.
3871 @end deftypefun
3872
3873 @deftypefun gpgme_error_t gpgme_signers_add (@w{gpgme_ctx_t @var{ctx}}, @w{const gpgme_key_t @var{key}})
3874 The function @code{gpgme_signers_add} adds the key @var{key} to the
3875 list of signers in the context @var{ctx}.
3876
3877 Calling this function acquires an additional reference for the key.
3878 @end deftypefun
3879
3880 @deftypefun gpgme_key_t gpgme_signers_enum (@w{const gpgme_ctx_t @var{ctx}}, @w{int @var{seq}})
3881 The function @code{gpgme_signers_enum} returns the @var{seq}th key in
3882 the list of signers in the context @var{ctx}.  An additional reference
3883 is acquired for the user.
3884
3885 If @var{seq} is out of range, @code{NULL} is returned.
3886 @end deftypefun
3887
3888
3889 @node Creating a Signature
3890 @subsubsection Creating a Signature
3891
3892 @deftp {Data type} {enum gpgme_sig_mode_t}
3893 @tindex gpgme_sig_mode_t
3894 The @code{gpgme_sig_mode_t} type is used to specify the desired type of a
3895 signature.  The following modes are available:
3896
3897 @table @code
3898 @item GPGME_SIG_MODE_NORMAL
3899 A normal signature is made, the output includes the plaintext and the
3900 signature.
3901
3902 @item GPGME_SIG_MODE_DETACH
3903 A detached signature is made.
3904
3905 @item GPGME_SIG_MODE_CLEAR
3906 A clear text signature is made.  The @acronym{ASCII} armor and text
3907 mode settings of the context are ignored.
3908 @end table
3909 @end deftp
3910
3911 @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}})
3912 The function @code{gpgme_op_sign} creates a signature for the text in
3913 the data object @var{plain} and returns it in the data object
3914 @var{sig}.  The type of the signature created is determined by the
3915 @acronym{ASCII} armor and text mode attributes set for the context
3916 @var{ctx} and the requested signature mode @var{mode}.
3917
3918 After the operation completed successfully, the result can be
3919 retrieved with @code{gpgme_op_sign_result}.
3920
3921 If an S/MIME signed message is created using the CMS crypto engine,
3922 the number of certificates to include in the message can be specified
3923 with @code{gpgme_set_include_certs}.  @xref{Included Certificates}.
3924
3925 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3926 signature could be created successfully, @code{GPG_ERR_INV_VALUE} if
3927 @var{ctx}, @var{plain} or @var{sig} is not a valid pointer,
3928 @code{GPG_ERR_NO_DATA} if the signature could not be created,
3929 @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the secret key
3930 could not be retrieved, @code{GPG_ERR_UNUSABLE_SECKEY} if there are
3931 invalid signers, and passes through any errors that are reported by the
3932 crypto engine support routines.
3933 @end deftypefun
3934
3935 @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}})
3936 The function @code{gpgme_op_sign_start} initiates a
3937 @code{gpgme_op_sign} operation.  It can be completed by calling
3938 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
3939
3940 The function returns the error code @code{GPG_ERR_NO_ERROR} if the operation could be
3941 started successfully, and @code{GPG_ERR_INV_VALUE} if @var{ctx},
3942 @var{plain} or @var{sig} is not a valid pointer.
3943 @end deftypefun
3944
3945 @deftp {Data type} {gpgme_new_signature_t}
3946 This is a pointer to a structure used to store a part of the result of
3947 a @code{gpgme_op_sign} operation.  The structure contains the
3948 following members:
3949
3950 @table @code
3951 @item gpgme_new_signature_t next
3952 This is a pointer to the next new signature structure in the linked
3953 list, or @code{NULL} if this is the last element.
3954
3955 @item gpgme_sig_mode_t type
3956 The type of this signature.
3957
3958 @item gpgme_pubkey_algo_t
3959 The public key algorithm used to create this signature.
3960
3961 @item gpgme_hash_algo_t
3962 The hash algorithm used to create this signature.
3963
3964 @item unsigned int class
3965 The signature class of this signature.
3966
3967 @item long int timestamp
3968 The creation timestamp of this signature.
3969
3970 @item char *fpr
3971 The fingerprint of the key which was used to create this signature.
3972 @end table
3973 @end deftp
3974
3975 @deftp {Data type} {gpgme_sign_result_t}
3976 This is a pointer to a structure used to store the result of a
3977 @code{gpgme_op_sign} operation.  After successfully generating a
3978 signature, you can retrieve the pointer to the result with
3979 @code{gpgme_op_sign_result}.  The structure contains the following
3980 members:
3981
3982 @table @code
3983 @item gpgme_invalid_key_t invalid_signers
3984 A linked list with information about all invalid keys for which a
3985 signature could not be created.
3986
3987 @item gpgme_new_signature_t signatures
3988 A linked list with information about all signatures created.
3989 @end table
3990 @end deftp
3991
3992 @deftypefun gpgme_sign_result_t gpgme_op_sign_result (@w{gpgme_ctx_t @var{ctx}})
3993 The function @code{gpgme_op_sign_result} returns a
3994 @code{gpgme_sign_result_t} pointer to a structure holding the result
3995 of a @code{gpgme_op_sign} operation.  The pointer is only valid if the
3996 last operation on the context was a @code{gpgme_op_sign},
3997 @code{gpgme_op_sign_start}, @code{gpgme_op_encrypt_sign} or
3998 @code{gpgme_op_encrypt_sign_start} operation.  If that operation
3999 failed, the function might return a @code{NULL} pointer, The returned
4000 pointer is only valid until the next operation is started on the
4001 context.
4002 @end deftypefun
4003
4004
4005 @node Encrypt
4006 @subsection Encrypt
4007 @cindex encryption
4008 @cindex cryptographic operation, encryption
4009
4010 One plaintext can be encrypted for several recipients at the same
4011 time.  The list of recipients is created independently of any context,
4012 and then passed to the encryption operation.
4013
4014 @menu
4015 * Encrypting a Plaintext::        How to encrypt a plaintext.
4016 @end menu
4017
4018
4019 @node Encrypting a Plaintext
4020 @subsubsection Encrypting a Plaintext
4021
4022 @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}})
4023 The function @code{gpgme_op_encrypt} encrypts the plaintext in the data
4024 object @var{plain} for the recipients @var{recp} and stores the
4025 ciphertext in the data object @var{cipher}.  The type of the
4026 ciphertext created is determined by the @acronym{ASCII} armor and text
4027 mode attributes set for the context @var{ctx}.
4028
4029 @var{key} must be a @code{NULL}-terminated array of keys.  The user
4030 must keep references for all keys during the whole duration of the
4031 call (but see @code{gpgme_op_encrypt_start} for the requirements with
4032 the asynchronous variant).
4033
4034 The value in @var{flags} is a bitwise-or combination of one or
4035 multiple of the following bit values:
4036
4037 @table @code
4038 @item GPGME_ENCRYPT_ALWAYS_TRUST
4039 The @code{GPGME_ENCRYPT_ALWAYS_TRUST} symbol specifies that all the
4040 recipients in @var{recp} should be trusted, even if the keys do not
4041 have a high enough validity in the keyring.  This flag should be used
4042 with care; in general it is not a good idea to use any untrusted keys.
4043 @end table
4044
4045 If @code{GPG_ERR_UNUSABLE_PUBKEY} is returned, some recipients in
4046 @var{recp} are invalid, but not all.  In this case the plaintext might
4047 be encrypted for all valid recipients and returned in @var{cipher} (if
4048 this happens depends on the crypto engine).  More information about
4049 the invalid recipients is available with
4050 @code{gpgme_op_encrypt_result}.
4051
4052 If @var{recp} is @code{NULL}, symmetric rather than public key
4053 encryption is performed.  Symmetrically encrypted cipher text can be
4054 deciphered with @code{gpgme_op_decrypt}.  Note that in this case the
4055 crypto backend needs to retrieve a passphrase from the user.
4056 Symmetric encryption is currently only supported for the OpenPGP
4057 crypto backend.
4058
4059 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
4060 ciphertext could be created successfully, @code{GPG_ERR_INV_VALUE} if
4061 @var{ctx}, @var{recp}, @var{plain} or @var{cipher} is not a valid
4062 pointer, @code{GPG_ERR_UNUSABLE_PUBKEY} if @var{recp} contains some
4063 invalid recipients, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase
4064 for the symmetric key could not be retrieved, and passes through any
4065 errors that are reported by the crypto engine support routines.
4066 @end deftypefun
4067
4068 @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}})
4069 The function @code{gpgme_op_encrypt_start} initiates a
4070 @code{gpgme_op_encrypt} operation.  It can be completed by calling
4071 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
4072
4073 References to the keys only need to be held for the duration of this
4074 call.  The user can release its references to the keys after this
4075 function returns, even if the operation is not yet finished.
4076
4077 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
4078 operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
4079 @var{ctx}, @var{rset}, @var{plain} or @var{cipher} is not a valid
4080 pointer, and @code{GPG_ERR_UNUSABLE_PUBKEY} if @var{rset} does not
4081 contain any valid recipients.
4082 @end deftypefun
4083
4084 @deftp {Data type} {gpgme_encrypt_result_t}
4085 This is a pointer to a structure used to store the result of a
4086 @code{gpgme_op_encrypt} operation.  After successfully encrypting
4087 data, you can retrieve the pointer to the result with
4088 @code{gpgme_op_encrypt_result}.  The structure contains the following
4089 members:
4090
4091 @table @code
4092 @item gpgme_invalid_key_t invalid_recipients
4093 A linked list with information about all invalid keys for which
4094 the data could not be encrypted.
4095 @end table
4096 @end deftp
4097
4098 @deftypefun gpgme_encrypt_result_t gpgme_op_encrypt_result (@w{gpgme_ctx_t @var{ctx}})
4099 The function @code{gpgme_op_encrypt_result} returns a
4100 @code{gpgme_encrypt_result_t} pointer to a structure holding the
4101 result of a @code{gpgme_op_encrypt} operation.  The pointer is only
4102 valid if the last operation on the context was a
4103 @code{gpgme_op_encrypt}, @code{gpgme_op_encrypt_start},
4104 @code{gpgme_op_sign} or @code{gpgme_op_sign_start} operation.  If this
4105 operation failed, this might be a @code{NULL} pointer.  The returned
4106 pointer is only valid until the next operation is started on the
4107 context.
4108 @end deftypefun
4109
4110
4111 @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}})
4112 The function @code{gpgme_op_encrypt_sign} does a combined encrypt and
4113 sign operation.  It is used like @code{gpgme_op_encrypt}, but the
4114 ciphertext also contains signatures for the signers listed in
4115 @var{ctx}.
4116
4117 The combined encrypt and sign operation is currently only available
4118 for the OpenPGP crypto engine.
4119 @end deftypefun
4120
4121 @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}})
4122 The function @code{gpgme_op_encrypt_sign_start} initiates a
4123 @code{gpgme_op_encrypt_sign} operation.  It can be completed by
4124 calling @code{gpgme_wait} on the context.  @xref{Waiting For
4125 Completion}.
4126
4127 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
4128 operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
4129 if @var{ctx}, @var{rset}, @var{plain} or @var{cipher} is not a valid
4130 pointer.
4131 @end deftypefun
4132
4133
4134 @node Run Control
4135 @section Run Control
4136 @cindex run control
4137 @cindex cryptographic operation, running
4138
4139 @acronym{GPGME} supports running operations synchronously and
4140 asynchronously.  You can use asynchronous operation to set up a
4141 context up to initiating the desired operation, but delay performing
4142 it to a later point.
4143
4144 Furthermore, you can use an external event loop to control exactly
4145 when @acronym{GPGME} runs.  This ensures that @acronym{GPGME} only
4146 runs when necessary and also prevents it from blocking for a long
4147 time.
4148
4149 @menu
4150 * Waiting For Completion::        Waiting until an operation is completed.
4151 * Using External Event Loops::    Advanced control over what happens when.
4152 @end menu
4153
4154
4155 @node Waiting For Completion
4156 @subsection Waiting For Completion
4157 @cindex cryptographic operation, wait for
4158 @cindex wait for completion
4159
4160 @deftypefun gpgme_ctx_t gpgme_wait (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_error_t *@var{status}}, @w{int @var{hang}})
4161 The function @code{gpgme_wait} continues the pending operation within
4162 the context @var{ctx}.  In particular, it ensures the data exchange
4163 between @acronym{GPGME} and the crypto backend and watches over the
4164 run time status of the backend process.
4165
4166 If @var{hang} is true, the function does not return until the
4167 operation is completed or cancelled.  Otherwise the function will not
4168 block for a long time.
4169
4170 The error status of the finished operation is returned in @var{status}
4171 if @code{gpgme_wait} does not return @code{NULL}.
4172
4173 The @var{ctx} argument can be @code{NULL}.  In that case,
4174 @code{gpgme_wait} waits for any context to complete its operation.
4175
4176 @code{gpgme_wait} can be used only in conjunction with any context
4177 that has a pending operation initiated with one of the
4178 @code{gpgme_op_*_start} functions except @code{gpgme_op_keylist_start}
4179 and @code{gpgme_op_trustlist_start} (for which you should use the
4180 corresponding @code{gpgme_op_*_next} functions).  If @var{ctx} is
4181 @code{NULL}, all of such contexts are waited upon and possibly
4182 returned.  Synchronous operations running in parallel, as well as key
4183 and trust item list operations, do not affect @code{gpgme_wait}.
4184
4185 In a multi-threaded environment, only one thread should ever call
4186 @code{gpgme_wait} at any time, irregardless if @var{ctx} is specified
4187 or not.  This means that all calls to this function should be fully
4188 synchronized by locking primitives.  It is safe to start asynchronous
4189 operations while a thread is running in @code{gpgme_wait}.
4190
4191 The function returns the @var{ctx} of the context which has finished
4192 the operation.  If @var{hang} is false, and the timeout expires,
4193 @code{NULL} is returned and @code{*status} will be set to 0.  If an
4194 error occurs, @code{NULL} is returned and the error is returned in
4195 @code{*status}.
4196 @end deftypefun
4197
4198
4199 @node Using External Event Loops
4200 @subsection Using External Event Loops
4201 @cindex event loop, external
4202
4203 @acronym{GPGME} hides the complexity of the communication between the
4204 library and the crypto engine.  The price of this convenience is that
4205 the calling thread can block arbitrary long waiting for the data
4206 returned by the crypto engine.  In single-threaded programs, in
4207 particular if they are interactive, this is an unwanted side-effect.
4208 OTOH, if @code{gpgme_wait} is used without the @var{hang} option being
4209 enabled, it might be called unnecessarily often, wasting CPU time that
4210 could be used otherwise.
4211
4212 The I/O callback interface described in this section lets the user
4213 take control over what happens when.  @acronym{GPGME} will provide the
4214 user with the file descriptors that should be monitored, and the
4215 callback functions that should be invoked when a file descriptor is
4216 ready for reading or writing.  It is then the user's responsibility to
4217 decide when to check the file descriptors and when to invoke the
4218 callback functions.  Usually this is done in an event loop, that also
4219 checks for events in other parts of the program.  If the callback
4220 functions are only called when the file descriptors are ready,
4221 @acronym{GPGME} will never block.  This gives the user mroe control
4222 over the program flow, and allows to perform other tasks when
4223 @acronym{GPGME} would block otherwise.
4224
4225 By using this advanced mechanism, @acronym{GPGME} can be integrated
4226 smoothly into GUI toolkits like GTK+ even for single-threaded
4227 programs.
4228
4229 @menu
4230 * I/O Callback Interface::        How I/O callbacks are registered.
4231 * Registering I/O Callbacks::     How to use I/O callbacks for a context.
4232 * I/O Callback Example::          An example how to use I/O callbacks.
4233 * I/O Callback Example GTK+::     How to use @acronym{GPGME} with GTK+.
4234 * I/O Callback Example GDK::      How to use @acronym{GPGME} with GDK.
4235 @end menu
4236
4237
4238 @node I/O Callback Interface
4239 @subsubsection I/O Callback Interface
4240
4241 @deftp {Data type} {gpgme_error_t (*gpgme_io_cb_t) (@w{void *@var{data}}, @w{int @var{fd}})}
4242 @tindex gpgme_io_cb_t
4243 The @code{gpgme_io_cb_t} type is the type of functions which
4244 @acronym{GPGME} wants to register as I/O callback handlers using the
4245 @code{gpgme_register_io_cb_t} functions provided by the user.
4246
4247 @var{data} and @var{fd} are provided by @acronym{GPGME} when the I/O
4248 callback handler is registered, and should be passed through to the
4249 handler when it is invoked by the user because it noticed activity on
4250 the file descriptor @var{fd}.
4251
4252 The callback handler always returns @code{0}, but you should consider
4253 the return value to be reserved for later use.
4254 @end deftp
4255
4256 @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}})}
4257 @tindex gpgme_register_io_cb_t
4258 The @code{gpgme_register_io_cb_t} type is the type of functions which can
4259 be called by @acronym{GPGME} to register an I/O callback funtion
4260 @var{fnc} for the file descriptor @var{fd} with the user.
4261 @var{fnc_data} should be passed as the first argument to @var{fnc}
4262 when the handler is invoked (the second argument should be @var{fd}).
4263 If @var{dir} is 0, @var{fnc} should be called by the user when
4264 @var{fd} is ready for writing.  If @var{dir} is 1, @var{fnc} should be
4265 called when @var{fd} is ready for reading.
4266
4267 @var{data} was provided by the user when registering the
4268 @code{gpgme_register_io_cb_t} function with @acronym{GPGME} and will always
4269 be passed as the first argument when registering a callback function.
4270 For example, the user can use this to determine the event loop to
4271 which the file descriptor should be added.
4272
4273 @acronym{GPGME} will call this function when a crypto operation is
4274 initiated in a context for which the user has registered I/O callback
4275 handler functions with @code{gpgme_set_io_cbs}.  It can also call this
4276 function when it is in an I/O callback handler for a file descriptor
4277 associated to this context.
4278
4279 The user should return a unique handle in @var{tag} identifying this
4280 I/O callback registration, which will be passed to the
4281 @code{gpgme_register_io_cb_t} function without interpretation when the file
4282 descriptor should not be monitored anymore.
4283 @end deftp
4284
4285 @deftp {Data type} {void (*gpgme_remove_io_cb_t) (@w{void *@var{tag}})}
4286 The @code{gpgme_remove_io_cb_t} type is the type of functions which can be
4287 called by @acronym{GPGME} to remove an I/O callback handler that was
4288 registered before.  @var{tag} is the handle that was returned by the
4289 @code{gpgme_register_io_cb_t} for this I/O callback.
4290
4291 @acronym{GPGME} can call this function when a crypto operation is in
4292 an I/O callback.  It will also call this function when the context is
4293 destroyed while an operation is pending.
4294 @end deftp
4295
4296 @deftp {Data type} {enum gpgme_event_io_t}
4297 @tindex gpgme_event_io_t
4298 The @code{gpgme_event_io_t} type specifies the type of an event that is
4299 reported to the user by @acronym{GPGME} as a consequence of an I/O
4300 operation.  The following events are defined:
4301
4302 @table @code
4303 @item GPGME_EVENT_START
4304 The operation is fully initialized now, and you can start to run the
4305 registered I/O callback handlers now.  Note that registered I/O
4306 callback handlers must not be run before this event is signalled.
4307 @var{type_data} is @code{NULL} and reserved for later use.
4308
4309 @item GPGME_EVENT_DONE
4310 The operation is finished, the last I/O callback for this operation
4311 was removed.  The accompanying @var{type_data} points to a
4312 @code{gpgme_error_t} variable that contains the status of the operation
4313 that finished.  This event is signalled after the last I/O callback
4314 has been removed.
4315
4316 @item GPGME_EVENT_NEXT_KEY
4317 In a @code{gpgme_op_keylist_start} operation, the next key was
4318 received from the crypto engine.  The accompanying @var{type_data} is
4319 a @code{gpgme_key_t} variable that contains the key with one reference
4320 for the user.
4321
4322 @item GPGME_EVENT_NEXT_TRUSTITEM
4323 In a @code{gpgme_op_trustlist_start} operation, the next trust item
4324 was received from the crypto engine.  The accompanying @var{type_data}
4325 is a @code{gpgme_trust_item_t} variable that contains the trust item with
4326 one reference for the user.
4327 @end table
4328 @end deftp
4329
4330 @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}})}
4331 The @code{gpgme_event_io_cb_t} type is the type of functions which can be
4332 called by @acronym{GPGME} to signal an event for an operation running
4333 in a context which has I/O callback functions registered by the user.
4334
4335 @var{data} was provided by the user when registering the
4336 @code{gpgme_event_io_cb_t} function with @acronym{GPGME} and will always be
4337 passed as the first argument when registering a callback function.
4338 For example, the user can use this to determine the context in which
4339 this event has occured.
4340
4341 @var{type} will specify the type of event that has occured.
4342 @var{type_data} specifies the event further, as described in the above
4343 list of possible @code{gpgme_event_io_t} types.
4344
4345 @acronym{GPGME} can call this function in an I/O callback handler.
4346 @end deftp
4347
4348
4349 @node Registering I/O Callbacks
4350 @subsubsection Registering I/O Callbacks
4351
4352 @deftp {Data type} {struct gpgme_io_cb_ts}
4353 @tindex gpgme_event_io_t
4354 This structure is used to store the I/O callback interface functions
4355 described in the previous section.  It has the following members:
4356
4357 @table @code
4358 @item gpgme_register_io_cb_t add
4359 This is the function called by @acronym{GPGME} to register an I/O
4360 callback handler.  It must be specified.
4361
4362 @item void *add_data
4363 This is passed as the first argument to the @code{add} function when
4364 it is called by @acronym{GPGME}.  For example, it can be used to
4365 determine the event loop to which the file descriptor should be added.
4366
4367 @item gpgme_remove_io_cb_t remove
4368 This is the function called by @acronym{GPGME} to remove an I/O
4369 callback handler.  It must be specified.
4370
4371 @item gpgme_event_io_cb_t event
4372 This is the function called by @acronym{GPGME} to signal an event for
4373 an operation.  It is optional, but if you don't specify it, you can
4374 not retrieve the return value of the operation.
4375
4376 @item void *event_data
4377 This is passed as the first argument to the @code{event} function when
4378 it is called by @acronym{GPGME}.  For example, it can be used to
4379 determine the context in which the event has occured.
4380 @end table
4381 @end deftp
4382
4383 @deftypefun void gpgme_set_io_cbs (@w{gpgme_ctx_t @var{ctx}}, @w{struct gpgme_io_cb_ts *@var{io_cbs}})
4384 The function @code{gpgme_set_io_cbs} enables the I/O callback
4385 interface for the context @var{ctx}.  The I/O callback functions are
4386 specified by @var{io_cbs}.
4387
4388 If @var{io_cbs}->@code{add} is @code{NULL}, the I/O callback interface
4389 is disabled for the context, and normal operation is restored.
4390 @end deftypefun
4391
4392 @deftypefun void gpgme_get_io_cbs (@w{gpgme_ctx_t @var{ctx}}, @w{struct gpgme_io_cb_ts *@var{io_cbs}})
4393 The function @code{gpgme_get_io_cbs} returns the I/O callback