doc/
[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 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 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 * Error Handling::                Error numbers and their meanings.
77 * Exchanging Data::               Passing data to and from @acronym{GPGME}.
78 * Contexts::                      Handling @acronym{GPGME} contexts.
79
80 Appendices
81
82 * Copying::                       The GNU General Public License says how you
83                                   can copy and share `GnuPG Made Easy'.
84 * Free Documentation License::    This manual is under the GNU Free
85                                   Documentation License.
86
87 Indices
88
89 * Concept Index::                 Index of concepts and programs.
90 * Function and Data Index::       Index of functions, variables and data types.
91
92
93 @detailmenu
94  --- The Detailed Node Listing ---
95
96 Introduction
97
98 * Getting Started::               Purpose of the manual, and how to use it.
99 * Features::                      Reasons to install and use @acronym{GPGME}.
100 * Overview::                      Basic architecture of the @acronym{GPGME} library.
101
102 Preparation
103
104 * Header::                        What header file you need to include.
105 * Building the Source::           Compiler options to be used.
106 * Using Automake::                Compiler options to be used the easy way.
107 * Library Version Check::         Getting and verifying the library version.
108 * Multi Threading::               How GPGME can be used in an MT environment.
109
110 Protocols and Engines
111
112 * Engine Version Check::          Verifying the engine version.
113 * Engine Information::            Obtaining more information about the engines.
114 * OpenPGP::                       Support for the OpenPGP protocol.
115 * Cryptographic Message Syntax::  Support for the CMS.
116
117 Error Handling
118
119 * Error Values::                  A list of all error values used.
120 * Error Strings::                 How to get a descriptive string from a value.
121
122 Exchanging Data 
123
124 * Creating Data Buffers::         Creating new data buffers.
125 * Destroying Data Buffers::       Releasing data buffers.
126 * Manipulating Data Buffers::     Operations on data buffers.
127
128 Contexts
129
130 * Creating Contexts::             Creating new @acronym{GPGME} contexts.
131 * Destroying Contexts::           Releasing @acronym{GPGME} contexts.
132 * Context Attributes::            Setting properties of a context.
133 * Key Management::                Managing keys with @acronym{GPGME}.
134 * Trust Item Management::         Managing trust items with @acronym{GPGME}.
135 * Crypto Operations::             Using a context for cryptography.
136 * Run Control::                   Controlling how operations are run.
137
138 Context Attributes
139
140 * Protocol Selection::            Selecting the protocol used by a context.
141 * @acronym{ASCII} Armor::                   Requesting @acronym{ASCII} armored output.
142 * Text Mode::                     Choosing canonical text mode.
143 * Included Certificates::         Including a number of certificates.
144 * Key Listing Mode::              Selecting key listing mode.
145 * Passphrase Callback::           Getting the passphrase from the user.
146 * Progress Meter Callback::       Being informed about the progress.
147
148 Key Management
149
150 * Listing Keys::                  Browsing the list of available keys.
151 * Information About Keys::        Requesting detailed information about keys.
152 * Manipulating Keys::             Operations on keys.
153 * Generating Keys::               Creating new key pairs.
154 * Exporting Keys::                Retrieving key data from the key ring.
155 * Importing Keys::                Adding keys to the key ring.
156 * Deleting Keys::                 Removing keys from the key ring.
157
158 Trust Item Management
159
160 * Listing Trust Items::           Browsing the list of available trust items.
161 * Information About Trust Items:: Requesting detailed information about trust items.
162 * Manipulating Trust Items::      Operations on trust items.
163
164 Crypto Operations
165
166 * Decrypt::                       Decrypting a ciphertext.
167 * Verify::                        Verifying a signature.
168 * Decrypt and Verify::            Decrypting a signed ciphertext.
169 * Sign::                          Creating a signature.
170 * Encrypt::                       Encrypting a plaintext.
171 * Detailed Results::              How to obtain more info about the operation.
172
173 Sign
174
175 * Selecting Signers::             How to choose the keys to sign with.
176 * Creating a Signature::          How to create a signature.
177
178 Encrypt
179
180 * Selecting Recipients::          How to choose the recipients.
181 * Encrypting a Plaintext::        How to encrypt a plaintext.
182
183 Run Control
184
185 * Waiting For Completion::        Waiting until an operation is completed.
186 * Cancelling an Operation::       Interrupting a running operation.
187 * Hooking Up Into Idle Time::     Doing something when nothing has to be done.
188 * Using External Event Loops::    Advanced control over what happens when.
189
190 Using External Event Loops
191
192 * I/O Callback Interface::        How I/O callbacks are registered.
193 * Registering I/O Callbacks::     How to use I/O callbacks for a context.
194 * I/O Callback Example::          An example how to use I/O callbacks.
195 * I/O Callback Example GTK+::     How to integrate @acronym{GPGME} in GTK+.
196 * I/O Callback Example GDK::      How to integrate @acronym{GPGME} in GDK.
197
198 @end detailmenu
199 @end menu
200
201 @node Introduction
202 @chapter Introduction
203
204 `GnuPG Made Easy' (@acronym{GPGME}) is a C language library that
205 allows to add support for cryptography to a program.  It is designed
206 to make access to crypto engines like GnuPG or GpgSM easier for
207 applications.  @acronym{GPGME} provides a high-level crypto API for
208 encryption, decryption, signing, signature verification and key
209 management.
210
211 @acronym{GPGME} uses GnuPG and GpgSM as its backends to support
212 OpenPGP and the Cryptographic Message Syntax (CMS).
213
214 @menu
215 * Getting Started::               Purpose of the manual, and how to use it.
216 * Features::                      Reasons to install and use @acronym{GPGME}.
217 * Overview::                      Basic architecture of the @acronym{GPGME} library.
218 @end menu
219
220
221 @node Getting Started
222 @section Getting Started
223
224 This library documents the @acronym{GPGME} library programming
225 interface.  All functions and data types provided by the library are
226 explained.
227
228 The reader is assumed to possess basic knowledge about cryptography in
229 general, and public key cryptography in particular.  The underlying
230 cryptographic engines that are used by the library are not explained,
231 but where necessary, special features or requirements by an engine are
232 mentioned as far as they are relevant to @acronym{GPGME} or its users.
233
234 This manual can be used in several ways.  If read from the beginning
235 to the end, it gives a good introduction into the library and how it
236 can be used in an application.  Forward references are included where
237 necessary.  Later on, the manual can be used as a reference manual to
238 get just the information needed about any particular interface of the
239 library.  Experienced programmers might want to start looking at the
240 examples at the end of the manual, and then only read up those parts
241 of the interface which are unclear.
242
243
244 @node Features
245 @section Features
246
247 @acronym{GPGME} has a couple of advantages over other libraries doing
248 a similar job, and over implementing support for GnuPG or other crypto
249 engines into your application directly.
250
251 @table @asis
252 @item it's free software
253 Anybody can use, modify, and redistribute it under the terms of the GNU
254 General Public License (@pxref{Copying}).
255
256 @item it's flexible
257 @acronym{GPGME} provides transparent support for several cryptographic
258 protocols by different engines.  Currently, @acronym{GPGME} supports
259 the OpenPGP protocol using GnuPG as the backend, and the Cryptographic
260 Message Syntax using GpgSM as the backend.
261
262 @item it's easy
263 @acronym{GPGME} hides the differences between the protocols and
264 engines from the programmer behind an easy-to-use interface.  This way
265 the programmer can focus on the other parts of the program, and still
266 integrate strong cryptography in his application.  Once support for
267 @acronym{GPGME} has been added to a program, it is easy to add support
268 for other crypto protocols once @acronym{GPGME} backends provide them.
269 @end table
270
271
272 @node Overview
273 @section Overview
274
275 @acronym{GPGME} provides a data abstraction that is used to pass data
276 to the crypto engine, and receive returned data from it.  Data can be
277 read from memory or from files, but it can also be provided by a
278 callback function.
279
280 The actual cryptographic operations are always set within a context.
281 A context provides configuration parameters that define the behaviour
282 of all operations performed within it.  Only one operation per context
283 is allowed at any time, but when one operation is finished, you can
284 run the next operation in the same context.  There can be more than
285 one context, and all can run different operations at the same time.
286
287 Furthermore, @acronym{GPGME} has rich key management facilities
288 including listing keys, querying their attributes, generating,
289 importing, exporting and deleting keys, and acquiring information
290 about the trust path.
291
292 With some precautions, @acronym{GPGME} can be used in a multi-threaded
293 environment, although it is not completely thread safe and thus needs
294 the support of the application.
295
296
297 @node Preparation
298 @chapter Preparation
299
300 To use @acronym{GPGME}, you have to perform some changes to your
301 sources and the build system.  The necessary changes are small and
302 explained in the following sections.  At the end of this chapter, it
303 is described how the library is initialized, and how the requirements
304 of the library are verified.
305
306 @menu
307 * Header::                        What header file you need to include.
308 * Building the Source::           Compiler options to be used.
309 * Using Automake::                Compiler options to be used the easy way.
310 * Library Version Check::         Getting and verifying the library version.
311 * Multi Threading::               How GPGME can be used in an MT environment.
312 @end menu
313
314
315 @node Header
316 @section Header
317 @cindex header file
318 @cindex include file
319
320 All interfaces (data types and functions) of the library are defined
321 in the header file `gpgme.h'.  You must include this in all programs
322 using the library, either directly or through some other header file,
323 like this:
324
325 @example
326 #include <gpgme.h>
327 @end example
328
329 The name space of @acronym{GPGME} is @code{gpgme_*} for function
330 names, @code{Gpgme*} for data types and @code{GPGME_*} for other
331 symbols.  Symbols internal to @acronym{GPGME} take the form
332 @code{_gpgme_*}.
333
334 Because @acronym{GPGME} links to the Assuan library, linking to
335 @acronym{GPGME} will also use the @code{assuan_*} and @code{_assuan_*}
336 name space indirectly.
337
338
339 @node Building the Source
340 @section Building the Source
341 @cindex compiler options
342 @cindex compiler flags
343
344 If you want to compile a source file including the `gpgme.h' header
345 file, you must make sure that the compiler can find it in the
346 directory hierarchy.  This is accomplished by adding the path to the
347 directory in which the header file is located to the compilers include
348 file search path (via the @option{-I} option).
349
350 However, the path to the include file is determined at the time the
351 source is configured.  To solve this problem, gpgme ships with a small
352 helper program @command{gpgme-config} that knows about the path to the
353 include file and other configuration options.  The options that need
354 to be added to the compiler invocation at compile time are output by
355 the @option{--cflags} option to @command{gpgme-config}.  The following
356 example shows how it can be used at the command line:
357
358 @example
359 gcc -c foo.c `gpgme-config --cflags`
360 @end example
361
362 Adding the output of @samp{gpgme-config --cflags} to the compilers
363 command line will ensure that the compiler can find the @acronym{GPGME} header
364 file.
365
366 A similar problem occurs when linking the program with the library.
367 Again, the compiler has to find the library files.  For this to work,
368 the path to the library files has to be added to the library search
369 path (via the @option{-L} option).  For this, the option
370 @option{--libs} to @command{gpgme-config} can be used.  For
371 convenience, this option also outputs all other options that are
372 required to link the program with @acronym{GPGME} (in particular, the
373 @samp{-lgpgme} option).  The example shows how to link @file{foo.o}
374 with the @acronym{GPGME} library to a program @command{foo}.
375
376 @example
377 gcc -o foo foo.o `gpgme-config --libs`
378 @end example
379
380 Of course you can also combine both examples to a single command by
381 specifying both options to @command{gpgme-config}:
382
383 @example
384 gcc -o foo foo.c `gpgme-config --cflags --libs`
385 @end example
386
387
388 @node Using Automake
389 @section Using Automake
390 @cindex automake
391 @cindex autoconf
392
393 It is much easier if you use GNU Automake instead writing your own
394 Makefiles.  If you do that you don't have to worry about finding and
395 invoking the @command{gpgme-config} script at all.  @acronym{GPGME}
396 provides an extension to Automake that does all the work for you.
397
398 @c A simple macro for optional variables.
399 @macro ovar{varname}
400 @r{[}@var{\varname\}@r{]}
401 @end macro
402 @defmac AM_PATH_GPGME (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
403 Check whether @acronym{GPGME} (at least version @var{minimum-version},
404 if given) exists on the host system.  If it is found, execute
405 @var{action-if-found}, otherwise do @var{action-if-not-found}, if
406 given.
407
408 Additionally, the function defines @code{GPGME_CFLAGS} to the flags
409 needed for compilation of the program to find the @file{gpgme.h}
410 header file, and @code{GPGME_LIBS} to the linker flags needed to link
411 the program to the @acronym{GPGME} library.
412 @end defmac
413
414 You can use the defined Autoconf variables like this in your
415 @file{Makefile.am}:
416
417 @example
418 AM_CPPFLAGS = $(GPGME_CFLAGS)
419 LDADD = $(GPGME_LIBS)
420 @end example
421
422
423 @node Library Version Check
424 @section Library Version Check
425 @cindex version check, of the library
426
427 @deftypefun {const char *} gpgme_check_version (@w{const char *@var{required_version}})
428 The function @code{gpgme_check_version} has three purposes.  It can be
429 used to retrieve the version number of the library.  In addition it
430 can verify that the version number is higher than a certain required
431 version number.  In either case, the function initializes some
432 sub-systems, and for this reason alone it must be invoked early in
433 your program, before you make use of the other functions in
434 @acronym{GPGME}.
435
436 If @var{required_version} is @code{NULL}, the function returns a
437 pointer to a statically allocated string containing the version number
438 of the library.
439
440 If @var{required_version} is not @code{NULL}, it should point to a
441 string containing a version number, and the function checks that the
442 version of the library is at least as high as the version number
443 provided.  In this case, the function returns a pointer to a
444 statically allocated string containing the version number of the
445 library.  If @var{REQUIRED_VERSION} is not a valid version number, or
446 if the version requirement is not met, the function returns
447 @code{NULL}.
448
449 If you use a version of a library that is backwards compatible with
450 older releases, but contains additional interfaces which your program
451 uses, this function provides a run-time check if the necessary
452 features are provided by the installed version of the library.
453 @end deftypefun
454
455
456 @node Multi Threading
457 @section Multi Threading
458 @cindex thread-safeness
459 @cindex multi-threading
460
461 The @acronym{GPGME} library is not entirely thread-safe, but it can
462 still be used in a multi-threaded environment if some care is taken.
463 If the following requirements are met, there should be no race
464 conditions to worry about:
465
466 @itemize @bullet
467 @item
468 @acronym{GPGME} supports the thread libraries pthread and GNU Pth.
469 The support for this has to be enabled at compile time.
470 @acronym{GPGME} will automatically detect the location in which the
471 thread libraries are installed and activate the support for them.
472
473 Support for other thread libraries is very easy to add.  Please
474 contact us if you have the need.
475
476 @item
477 If you link your program dynamically to @acronym{GPGME} and your
478 supported thread library, @acronym{GPGME} will automatically detect
479 the presence of this library and activate its use.  If you link to
480 both pthread and GNU Pth, @acronym{GPGME} will use the pthread
481 support.  This feature requires weak symbol support.
482
483 @item
484 If you link your program statically to @acronym{GPGME}, there is
485 currently no easy way to make sure that @acronym{GPGME} detects the
486 presence of the thread library.  This will be solved in a future
487 version.
488
489 @item
490 The function @code{gpgme_check_version} must be called before any
491 other function in the library, because it initializes the thread
492 support subsystem in @acronym{GPGME}.  To achieve this in all
493 generality, it is necessary to synchronize the call to this function
494 with all other calls to functions in the library, using the
495 synchronization mechanisms available in your thread library.
496 Otherwise, specific compiler or CPU memory cache optimizations could
497 lead to the situation where a thread is started and uses
498 @acronym{GPGME} before the effects of the initialization are visible
499 for this thread.  It doesn't even suffice to call
500 @code{gpgme_check_version} before creating this other
501 thread@footnote{In SMP systems the new thread could be started on
502 another CPU before the effects of the initialization are seen by that
503 CPU's memory cache.  Not doing proper synchronization here leads to
504 the same problems the double-checked locking idiom has.  You might
505 find that if you don't do proper synchronization, it still works in
506 most configurations.  Don't let this fool you.  Someday it might lead
507 to subtle bugs when someone tries it on a DEC Alpha or an SMP
508 machine.}.
509
510 For example, if you are using POSIX threads, each thread that wants to
511 call functions in @acronym{GPGME} could call the following function
512 before any function in the library:
513
514 @example
515 #include <pthread.h>
516
517 void
518 initialize_gpgme (void)
519 @{
520   static int gpgme_init;
521   static pthread_mutext_t gpgme_init_lock = PTHREAD_MUTEX_INITIALIZER;
522
523   pthread_mutex_lock (&gpgme_init_lock);
524   if (!gpgme_init)
525     @{
526       gpgme_check_version ();
527       gpgme_init = 1;
528     @}
529   pthread_mutex_unlock (&gpgme_init_lock);
530 @}
531 @end example
532
533 @item
534 Any @code{GpgmeData}, @code{GpgmeCtx} and @code{GpgmeRecipients}
535 object must only be accessed by one thread at a time.  If multiple
536 threads want to deal with the same object, the caller has to make sure
537 that operations on this object are fully synchronized.
538
539 @item
540 Only one thread at any time is allowed to call @code{gpgme_wait}.  If
541 multiple threads call this function, the caller must make sure that
542 all invocations are fully synchronized.
543 @end itemize
544
545
546 @node Protocols and Engines
547 @chapter Protocols and Engines
548 @cindex protocol
549 @cindex engine
550 @cindex crypto engine
551 @cindex backend
552 @cindex crypto backend
553
554 @acronym{GPGME} supports several cryptographic protocols, however, it
555 does not implement them.  Rather it uses backends (also called
556 engines) which implement the protocol.  @acronym{GPGME} uses
557 inter-process communication to pass data back and forth between the
558 application and the backend, but the details of the communication
559 protocol and invocation of the backends is completely hidden by the
560 interface.  All complexity is handled by @acronym{GPGME}.  Where an
561 exchange of information between the application and the backend is
562 necessary, @acronym{GPGME} provides the necessary callback function
563 hooks and further interfaces.
564
565 @deftp {Data type} {enum GpgmeProtocol}
566 @tindex GpgmeProtocol
567 The @code{GpgmeProtocol} type specifies the set of possible protocol
568 values that are supported by @acronym{GPGME}.  The following protocols
569 are supported:
570
571 @table @code
572 @item GPGME_PROTOCOL_OpenPGP
573 This specifies the OpenPGP protocol.
574 @item GPGME_PROTOCOL_CMS
575 This specifies the Cryptographic Message Syntax.
576 @end table
577 @end deftp
578
579 @menu
580 * Engine Version Check::          Verifying the engine version.
581 * Engine Information::            Obtaining more information about the engines.
582 * OpenPGP::                       Support for the OpenPGP protocol.
583 * Cryptographic Message Syntax::  Support for the CMS.
584 @end menu
585
586
587 @node Engine Version Check
588 @section Engine Version Check
589 @cindex version check, of the engines
590
591 @deftypefun GpgmeError gpgme_engine_check_version (@w{GpgmeProtocol @var{protocol}})
592 The function @code{gpgme_engine_check_version} verifies that the
593 engine implementing the protocol @var{PROTOCOL} is installed in the
594 expected path and meets the version requirement of @acronym{GPGME}.
595
596 This function returns @code{GPGME_No_Error} if the engine is available
597 and @code{GPGME_Invalid_Engine} if it is not.
598 @end deftypefun
599
600 @deftypefun GpgmeError gpgme_check_engine (void)
601 The function @code{gpgme_check_engine} is equivalent to
602
603 @example
604 gpgme_engine_check_version (GPGME_PROTOCOL_OpenPGP);
605 @end example
606
607 This function is deprecated and provided for backwards compatibility
608 only.  It is obsoleted by @code{gpgme_engine_check_version}.
609 @end deftypefun
610
611
612 @node Engine Information
613 @section Engine Information
614 @cindex engine, information about
615
616 @deftypefun {const char *} gpgme_get_engine_info (void)
617 The function @code{gpgme_get_engine_info} returns an @acronym{XML}
618 string containing information about the available protocols and the
619 engine which implement them.  The following information is returned
620 for each engine:
621
622 @table @samp
623 @item <protocol>
624 The name of the protocol.
625 @item <version>
626 The version of the engine.
627 @item <path>
628 The path to the engine binary.
629 @end table
630
631 A string is always returned.  If an error occurs, the string will
632 contain an @samp{<error>} tag with a description of the failure.
633 @end deftypefun
634
635 Here is the example output of what @code{gpgme_get_engine_info} might
636 return on your system:
637
638 @example
639 <EngineInfo>
640  <engine>
641   <protocol>OpenPGP</protocol>
642   <version>1.0.6</version>
643   <path>/usr/bin/gpg</path>
644  </engine>
645  <engine>
646   <protocol>CMS</protocol>
647   <version>0.0.0</version>
648   <path>/usr/bin/gpgsm</path>
649  </engine>
650 </EngineInfo>
651 @end example
652
653
654 @node OpenPGP
655 @section OpenPGP
656 @cindex OpenPGP
657 @cindex GnuPG
658 @cindex protocol, GnuPG
659 @cindex engine, GnuPG
660
661 OpenPGP is implemented by GnuPG, the @acronym{GNU} Privacy Guard.
662 This is the first protocol that was supported by @acronym{GPGME}.
663
664 The OpenPGP protocol is specified by @code{GPGME_PROTOCOL_OpenPGP}.
665
666
667 @node Cryptographic Message Syntax
668 @section Cryptographic Message Syntax
669 @cindex CMS
670 @cindex cryptographic message syntax
671 @cindex GpgSM
672 @cindex protocol, CMS
673 @cindex engine, GpgSM
674 @cindex S/MIME
675 @cindex protocol, S/MIME
676
677 @acronym{CMS} is implemented by GpgSM, the S/MIME implementation for
678 GnuPG.
679
680 The @acronym{CMS} protocol is specified by @code{GPGME_PROTOCOL_CMS}.
681
682
683 @node Error Handling
684 @chapter Error Handling
685 @cindex error handling
686
687 Many functions in @acronym{GPGME} can return an error if they fail.
688 For this reason, the application should always catch the error
689 condition and take appropriate measures, for example by releasing the
690 resources and passing the error up to the caller, or by displaying a
691 descriptive message to the user and cancelling the operation.
692
693 Some error values do not indicate a system error or an error in the
694 operation, but the result of an operation that failed properly.  For
695 example, if you try to decrypt a tempered message, the decryption will
696 fail.  Another error value actually means that the end of a data
697 buffer or list has been reached.  The following descriptions explain
698 what each error message means in general.  Some error values have
699 specific meanings if returned by a specific function.  Such cases are
700 described in the documentation of those functions.
701
702 @menu
703 * Error Values::                  A list of all error values used.
704 * Error Strings::                 How to get a descriptive string from a value.
705 @end menu
706
707
708 @node Error Values
709 @section Error Values
710 @cindex error values, list of
711
712 @deftp {Data type} {enum GpgmeError}
713 @tindex GpgmeError
714 The @code{GpgmeError} type specifies the set of all error values that
715 are used by @acronym{GPGME}.  Possible values are:
716
717 @table @code
718 @item GPGME_EOF
719 This value indicates the end of a list, buffer or file.
720
721 @item GPGME_No_Error
722 This value indicates success.  The value of this error is @code{0}.
723
724 @item GPGME_General_Error
725 This value means that something went wrong, but either there is not
726 enough information about the problem to return a more useful error
727 value, or there is no separate error value for this type of problem.
728
729 @item GPGME_Out_Of_Core
730 This value means that an out-of-memory condition occurred.
731
732 @item GPGME_Invalid_Value
733 This value means that some user provided data was out of range.  This
734 can also refer to objects.  For example, if an empty @code{GpgmeData}
735 object was expected, but one containing data was provided, this error
736 value is returned.
737
738 @item GPGME_Busy
739 This value is returned if you try to start a new operation in a
740 context that is already busy with some earlier operation which was not
741 cancelled or finished yet.
742
743 @item GPGME_No_Request
744 This value is in some sense the opposite of @code{GPGME_Busy}.  There
745 is no pending operation, but it is required for the function to
746 succeed.
747
748 @item GPGME_Exec_Error
749 This value means that an error occurred when trying to spawn a child
750 process.
751
752 @item GPGME_Too_Many_Procs
753 This value means that there are too many active backend processes.
754
755 @item GPGME_Pipe_Error
756 This value means that the creation of a pipe failed.
757
758 @item GPGME_No_Recipients 
759 This value means that no valid recipients for a message have been set.
760
761 @item GPGME_Invalid_Recipients 
762 This value means that some, but not all, recipients for a message have
763 been invalid.
764
765 @item GPGME_No_Data
766 This value means that a @code{GpgmeData} object which was expected to
767 have content was found empty.
768
769 @item GPGME_Conflict
770 This value means that a conflict of some sort occurred.
771
772 @item GPGME_Not_Implemented
773 This value indicates that the specific function (or operation) is not
774 implemented.  This error should never happen.  It can only occur if
775 you use certain values or configuration options which do not work,
776 but for which we think that they should work at some later time.
777
778 @item GPGME_Read_Error
779 This value means that an I/O read operation failed.
780
781 @item GPGME_Write_Error
782 This value means that an I/O write operation failed.
783
784 @item GPGME_Invalid_Type
785 This value means that a user provided object was of a wrong or
786 incompatible type.  Usually this refers to the type of a
787 @code{GpgmeData} object.
788
789 @item GPGME_Invalid_Mode
790 This value means that a @code{GpgmeData} object has an incorrect mode
791 of operation (for example, doesn't support output although it is
792 attempted to use it as an output buffer).
793
794 @item GPGME_File_Error
795 This value means that a file I/O operation failed.  The value of
796 @code{errno} contains the system error value.
797
798 @item GPGME_Decryption_Failed
799 This value indicates that a decryption operation was unsuccessful.
800
801 @item GPGME_No_Passphrase
802 This value means that the user did not provide a passphrase when
803 requested.
804
805 @item GPGME_Canceled
806 This value means that the operation was canceled.
807
808 @item GPGME_Invalid_Key
809 This value means that a key was invalid.
810
811 @item GPGME_Invalid_Engine
812 This value means that the engine that implements the desired protocol
813 is currently not available.  This can either be because the sources
814 were configured to exclude support for this engine, or because the
815 engine is not installed properly.
816 @end table
817 @end deftp
818
819
820 @node Error Strings
821 @section Error Strings
822 @cindex error values, printing of
823 @cindex error strings
824
825 @deftypefun {const char *} gpgme_strerror (@w{GpgmeError @var{err}})
826 The function @code{gpgme_strerror} returns a pointer to a statically
827 allocated string containing a description of the error with the error
828 value @var{err}.  This string can be used to output a diagnostic
829 message to the user.
830
831 The following example illustrates the use of @code{gpgme_strerror}:
832
833 @example
834 GpgmeCtx ctx;
835 GpgmeError err = gpgme_new (&ctx);
836 if (err)
837   @{
838     fprintf (stderr, "%s: creating GpgME context failed: %s\n",
839              argv[0], gpgme_strerror (err));
840     exit (1);
841   @}
842 @end example
843 @end deftypefun
844
845
846 @node Exchanging Data
847 @chapter Exchanging Data
848 @cindex data, exchanging
849
850 A lot of data has to be exchanged between the user and the crypto
851 engine, like plaintext messages, ciphertext, signatures and
852 information about the keys.  The technical details about exchanging
853 the data information are completely abstracted by @acronym{GPGME}.
854 The user provides and receives the data via @code{GpgmeData} objects,
855 regardless of the communication protocol between @acronym{GPGME} and
856 the crypto engine in use.
857
858 @deftp {Data type} {GpgmeData}
859 The @code{GpgmeData} type is a handle for a container for generic
860 data, which is used by @acronym{GPGME} to exchange data with the user.
861 @end deftp
862
863 @menu
864 * Creating Data Buffers::         Creating new data buffers.
865 * Destroying Data Buffers::       Releasing data buffers.
866 * Manipulating Data Buffers::     Operations on data buffers.
867 @end menu
868
869
870 @node Creating Data Buffers
871 @section Creating Data Buffers
872 @cindex data buffer, creation
873
874 @deftypefun GpgmeError gpgme_data_new (@w{GpgmeData *@var{dh}})
875 The function @code{gpgme_data_new} creates a new @code{GpgmeData}
876 object and returns a handle for it in @var{dh}.  The data object is
877 initially empty.
878
879 The function returns @code{GPGME_No_Error} if the data object was
880 successfully created, @code{GPGME_Invalid_Value} if @var{dh} is not a
881 valid pointer, and @code{GPGME_Out_Of_Core} if not enough memory is
882 available.
883 @end deftypefun
884
885 @deftypefun GpgmeError gpgme_data_new_from_mem (@w{GpgmeData *@var{dh}}, @w{const char *@var{buffer}}, @w{size_t @var{size}}, @w{int @var{copy}})
886 The function @code{gpgme_data_new_from_mem} creates a new
887 @code{GpgmeData} object and fills it with @var{size} bytes starting
888 from @var{buffer}.
889
890 If @var{copy} is not zero, a private copy of the data is made.  If
891 @var{copy} is zero, the data is taken from the specified buffer as
892 needed, and the user has to ensure that the buffer remains valid for
893 the whole life span of the data object.
894
895 The function returns @code{GPGME_No_Error} if the data object was
896 successfully created, @code{GPGME_Invalid_Value} if @var{dh} or
897 @var{buffer} is not a valid pointer, and @code{GPGME_Out_Of_Core} if
898 not enough memory is available.
899 @end deftypefun
900
901 @deftypefun GpgmeError gpgme_data_new_from_file (@w{GpgmeData *@var{dh}}, @w{const char *@var{filename}}, @w{int @var{copy}})
902 The function @code{gpgme_data_new_from_file} creates a new
903 @code{GpgmeData} object and fills it with the content of the file
904 @var{filename}.
905
906 If @var{copy} is not zero, the whole file is read in at initialization
907 time and the file is not used anymore after that.  This is the only
908 mode supported currently.  Later, a value of zero for @var{copy} might
909 cause all reads to be delayed until the data is needed, but this is
910 not yet implemented.
911
912 The function returns @code{GPGME_No_Error} if the data object was
913 successfully created, @code{GPGME_Invalid_Value} if @var{dh} or
914 @var{filename} is not a valid pointer, @code{GPGME_File_Error} if an
915 I/O operation fails, @code{GPGME_Not_Implemented} if @var{code} is
916 zero, and @code{GPGME_Out_Of_Core} if not enough memory is available.
917 @end deftypefun
918
919 @deftypefun GpgmeError gpgme_data_new_from_filepart (@w{GpgmeData *@var{dh}}, @w{const char *@var{filename}}, @w{FILE *@var{fp}}, @w{off_t @var{offset}}, @w{size_t @var{length}})
920 The function @code{gpgme_data_new_from_filepart} creates a new
921 @code{GpgmeData} object and fills it with a part of the file specified
922 by @var{filename} or @var{fp}.
923
924 Exactly one of @var{filename} and @var{fp} must be non-zero, the other
925 must be zero.  The argument that is not zero specifies the file from
926 which @var{length} bytes are read into the data object, starting from
927 @var{offset}.
928
929 The function returns @code{GPGME_No_Error} if the data object was
930 successfully created, @code{GPGME_Invalid_Value} if @var{dh} and
931 exactly one of @var{filename} and @var{fp} is not a valid pointer,
932 @code{GPGME_File_Error} if an I/O operation fails, and
933 @code{GPGME_Out_Of_Core} if not enough memory is available.
934 @end deftypefun
935
936 @deftypefun GpgmeError gpgme_data_new_with_read_cb (@w{GpgmeData *@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}})
937 The function @code{gpgme_data_new_with_read_cb} creates a new
938 @code{GpgmeData} object and uses the callback function @var{readfunc}
939 to retrieve the data on demand.  As the callback function can supply
940 the data in any way it wants, this is the most flexible data type
941 @acronym{GPGME} provides.  However, it can not be used to write data.
942
943 The callback function receives @var{hook_value} as its first argument
944 whenever it is invoked.  It should return up to @var{count} bytes in
945 @var{buffer}, and return the number of bytes actually read in
946 @var{nread}.  It may return @code{0} in @var{nread} if no data is
947 currently available.  To indicate @code{EOF} the function should
948 return with an error code of @code{-1} and set @var{nread} to
949 @code{0}.  The callback function may support to reset its internal
950 read pointer if it is invoked with @var{buffer} and @var{nread} being
951 @code{NULL} and @var{count} being @code{0}.
952
953 The function returns @code{GPGME_No_Error} if the data object was
954 successfully created, @code{GPGME_Invalid_Value} if @var{dh} or
955 @var{readfunc} is not a valid pointer, and @code{GPGME_Out_Of_Core} if
956 not enough memory is available.
957 @end deftypefun
958
959
960 @node Destroying Data Buffers
961 @section Destroying Data Buffers
962 @cindex data buffer, destruction
963
964 @deftypefun void gpgme_data_release (@w{GpgmeData @var{dh}})
965 The function @code{gpgme_data_release} destroys the data object with
966 the handle @var{dh}.  It releases all associated resources that were
967 not provided by the user in the first place.
968 @end deftypefun
969
970 @deftypefun {char *} gpgme_data_release_and_get_mem (@w{GpgmeData @var{dh}}, @w{size_t *@var{length}})
971 The function @code{gpgme_data_release_and_get_mem} is like
972 @code{gpgme_data_release}, except that it returns the data buffer and
973 its length that was provided by the object.
974
975 The user has to release the buffer with @code{free}.  In case the user
976 provided the data buffer in non-copy mode, a copy will be made for
977 this purpose.
978
979 In case an error returns, or there is no suitable data buffer that can
980 be returned to the user, the function will return @code{NULL}.
981 @end deftypefun
982
983
984 @node Manipulating Data Buffers
985 @section Manipulating Data Buffers
986 @cindex data buffere, manipulation
987
988 @deftypefun GpgmeError gpgme_data_read (@w{GpgmeData @var{dh}}, @w{void *@var{buffer}}, @w{size_t @var{length}}, @w{size_t *@var{nread}})
989 The function @code{gpgme_data_read} reads up to @var{length} bytes
990 from the data object with the handle @var{dh} into the space starting
991 at @var{buffer}.  The actual amount read is returned in @var{nread}.
992
993 If @var{buffer} is @code{NULL}, the function returns the amount of
994 bytes available in @var{nread} without changing the read pointer.
995 This is not supported by all types of data objects.  If this function
996 is not supported, @code{GPGME_Invalid_Type} is returned.
997
998 If the end of the data object is reached, the function returns
999 @code{GPGME_EOF} and sets @var{nread} to zero.
1000
1001 In all other cases, the function returns @code{GPGME_No_Error} if the
1002 operation was successfully performed and @code{GPGME_Invalid_Value} if
1003 @var{dh} is not a valid pointer.
1004 @end deftypefun
1005
1006 @deftypefun GpgmeError gpgme_data_rewind (@w{GpgmeData @var{dh}})
1007 The function @code{gpgme_data_rewind} resets the read pointer of the
1008 data object with the handle @var{dh}, so that a subsequent
1009 @code{gpgme_data_read} operation starts at the beginning of the data.
1010
1011 The function returns @code{GPGME_No_Error} if the operation was
1012 successfully performed, @code{GPGME_Not_Implemented} if the operation
1013 is not supported (for example, by a read callback function supplied by
1014 the user) and @code{GPGME_Invalid_Value} if @var{dh} is not a valid
1015 pointer.
1016 @end deftypefun
1017
1018 @deftypefun GpgmeError gpgme_data_write (@w{GpgmeData @var{dh}}, @w{const void *@var{buffer}}, @w{size_t @var{length}})
1019 The function @code{gpgme_data_write} writes @var{length} bytes
1020 starting from @var{buffer} into the data object with the handle
1021 @var{dh} at the current write position.
1022
1023 The function returns @code{GPGME_No_Error} if the operation was
1024 successfully performed, @code{GPGME_Invalid_Value} if @var{dh} or
1025 @var{buffer} is not a valid pointer, @code{GPGME_Invalid_Type} or
1026 @code{GPGME_Invalid_Mode} if the data object type does not support
1027 writing, and @code{GPGME_Out_Of_Core} if not enough memory is
1028 available.
1029 @end deftypefun
1030
1031 @c
1032 @c  GpgmeDataType
1033 @c
1034 @deftp {Data type} {enum GpgmeDataType}
1035 @tindex GpgmeDataType
1036 The @code{GpgmeDataType} type specifies the type of a @code{GpgmeData} object.
1037 The following data types are available:
1038
1039 @table @code
1040 @item GPGME_DATA_TYPE_NONE
1041 This specifies that the type is not yet determined.
1042
1043 @item GPGME_DATA_TYPE_MEM
1044 This specifies that the data is stored in memory.
1045
1046 @item GPGME_DATA_TYPE_FD
1047 This type is not implemented.
1048
1049 @item GPGME_DATA_TYPE_FILE
1050 This type is not implemented.
1051
1052 @item GPGME_DATA_TYPE_CB
1053 This type specifies that the data is provided by a callback function
1054 implemented by the user.
1055 @end table
1056 @end deftp
1057
1058 @deftypefun GpgmeDataType gpgme_data_get_type (@w{GpgmeData @var{dh}})
1059 The function @code{gpgme_data_get_type} returns the type of the data
1060 object with the handle @var{dh}.  If @var{dh} is not a valid pointer,
1061 @code{GPGME_DATA_TYPE_NONE} is returned.
1062 @end deftypefun
1063
1064 @c
1065 @c  GpgmeDataEncoding
1066 @c
1067 @deftp {Data type} {enum GpgmeDataEncoding}
1068 @tindex GpgmeDataEncoding
1069 The @code{GpgmeDataEncoding} type specifies the encoding of a
1070 @code{GpgmeData} object.  This encoding is useful to give the backend
1071 a hint on the type of data.  The following data types are available:
1072
1073 @table @code
1074 @item GPGME_DATA_ENCODING_NONE
1075 This specifies that the encoding is not known.  This is the default
1076 for a new data object.  The backend will try its best to detect the
1077 encoding automatically.
1078
1079 @item GPGME_DATA_ENCODING_BINARY
1080 This specifies that the data is encoding in binary form; i.e. there is
1081 no special encoding.
1082
1083 @item GPGME_DATA_ENCODING_BASE64
1084 This specifies that the data is encoded using the Base-64 encoding
1085 scheme as used by @acronym{MIME} and other protocols.
1086
1087 @item GPGME_DATA_ENCODING_ARMOR
1088 This specifies that the data is encoded in an armored form as used by
1089 OpenPGP and PEM.
1090 @end table
1091 @end deftp
1092
1093 @deftypefun GpgmeDataEncoding gpgme_data_get_encoding (@w{GpgmeData @var{dh}})
1094 The function @code{gpgme_data_get_encoding} returns the encoding of
1095 the data object with the handle @var{dh}.  If @var{dh} is not a valid
1096 pointer (e.g. @code{NULL}) @code{GPGME_DATA_ENCODING_NONE} is
1097 returned.
1098 @end deftypefun
1099
1100 @deftypefun GpgmeError gpgme_data_set_encoding (@w{GpgmeData @var{dh}, GpgmeDataEncoding @var{enc}})
1101 The function @code{gpgme_data_set_encoding} changes the encoding of
1102 the data object with the handle @var{dh} to @var{enc}.
1103 @end deftypefun
1104
1105
1106 @c
1107 @c    Chapter Contexts
1108 @c 
1109 @node Contexts
1110 @chapter Contexts
1111 @cindex context
1112
1113 All cryptographic operations in @acronym{GPGME} are performed within a
1114 context, which contains the internal state of the operation as well as
1115 configuration parameters.  By using several contexts you can run
1116 several cryptographic operations in parallel, with different
1117 configuration.
1118
1119 @deftp {Data type} {GpgmeCtx}
1120 The @code{GpgmeCtx} type is a handle for a @acronym{GPGME} context,
1121 which is used to hold the configuration, status and result of
1122 cryptographic operations.
1123 @end deftp
1124
1125 @menu
1126 * Creating Contexts::             Creating new @acronym{GPGME} contexts.
1127 * Destroying Contexts::           Releasing @acronym{GPGME} contexts.
1128 * Context Attributes::            Setting properties of a context.
1129 * Key Management::                Managing keys with @acronym{GPGME}.
1130 * Trust Item Management::         Managing trust items with @acronym{GPGME}.
1131 * Crypto Operations::             Using a context for cryptography.
1132 * Run Control::                   Controlling how operations are run.
1133 @end menu
1134
1135
1136 @node Creating Contexts
1137 @section Creating Contexts
1138 @cindex context, creation
1139
1140 @deftypefun GpgmeError gpgme_new (@w{GpgmeCtx *@var{ctx}})
1141 The function @code{gpgme_data_new} creates a new @code{GpgmeCtx}
1142 object and returns a handle for it in @var{ctx}.
1143
1144 The function returns @code{GPGME_No_Error} if the context was
1145 successfully created, @code{GPGME_Invalid_Value} if @var{ctx} is not a
1146 valid pointer, and @code{GPGME_Out_Of_Core} if not enough memory is
1147 available.
1148 @end deftypefun
1149
1150
1151 @node Destroying Contexts
1152 @section Destroying Contexts
1153 @cindex context, destruction
1154
1155 @deftypefun void gpgme_release (@w{GpgmeCtx @var{ctx}})
1156 The function @code{gpgme_release} destroys the context with the handle
1157 @var{ctx} and releases all associated resources.
1158 @end deftypefun
1159
1160
1161 @node Context Attributes
1162 @section Context Attributes
1163 @cindex context, attributes
1164
1165 @menu
1166 * Protocol Selection::            Selecting the protocol used by a context.
1167 * @acronym{ASCII} Armor::                   Requesting @acronym{ASCII} armored output.
1168 * Text Mode::                     Choosing canonical text mode.
1169 * Included Certificates::       Including a number of certificates.
1170 * Key Listing Mode::              Selecting key listing mode.
1171 * Passphrase Callback::           Getting the passphrase from the user.
1172 * Progress Meter Callback::       Being informed about the progress.
1173 @end menu
1174
1175
1176 @node Protocol Selection
1177 @subsection Protocol Selection
1178 @cindex context, selecting protocol
1179 @cindex protocol, selecting
1180
1181 @deftypefun GpgmeError gpgme_set_protocol (@w{GpgmeCtx @var{ctx}}, @w{GpgmeProtocol @var{proto}})
1182 The function @code{gpgme_set_protocol} sets the protocol used within
1183 the context @var{ctx} to @var{proto}.  All crypto operations will be
1184 performed by the crypto engine configured for that protocol.
1185 @xref{Protocols and Engines}.
1186
1187 Setting the protocol with @code{gpgme_set_protocol} does not check if
1188 the crypto engine for that protocol is available and installed
1189 correctly.  @xref{Engine Version Check}.
1190
1191 The function returns @code{GPGME_No_Error} if the protocol could be
1192 set successfully, and @code{GPGME_Invalid_Value} if @var{protocol} is
1193 not a valid protocol.
1194 @end deftypefun
1195
1196 @deftypefun GpgmeProtocol gpgme_get_protocol (@w{GpgmeCtx @var{ctx}})
1197 The function @code{gpgme_get_protocol} retrieves the protocol currently
1198 use with the context @var{ctx}.
1199 @end deftypefun
1200
1201 @node @acronym{ASCII} Armor
1202 @subsection @acronym{ASCII} Armor
1203 @cindex context, armor mode
1204 @cindex @acronym{ASCII} armor
1205 @cindex armor mode
1206
1207 @deftypefun void gpgme_set_armor (@w{GpgmeCtx @var{ctx}}, @w{int @var{yes}})
1208 The function @code{gpgme_set_armor} specifies if the output should be
1209 @acronym{ASCII} armored.  By default, output is not @acronym{ASCII}
1210 armored.
1211
1212 @acronym{ASCII} armored output is disabled if @var{yes} is zero, and
1213 enabled otherwise.
1214 @end deftypefun
1215
1216 @deftypefun int gpgme_get_armor (@w{GpgmeCtx @var{ctx}})
1217 The function @code{gpgme_get_armor} returns 1 if the output is
1218 @acronym{ASCII} armored, and @code{0} if it is not, or if @var{ctx} is
1219 not a valid pointer.
1220 @end deftypefun
1221
1222
1223 @node Text Mode
1224 @subsection Text Mode
1225 @cindex context, text mode
1226 @cindex text mode
1227 @cindex canonical text mode
1228
1229 @deftypefun void gpgme_set_textmode (@w{GpgmeCtx @var{ctx}}, @w{int @var{yes}})
1230 The function @code{gpgme_set_textmode} specifies if canonical text mode
1231 should be used.  By default, text mode is not used.
1232
1233 Text mode is for example used for the RFC2015 signatures; note that
1234 the updated RFC 3156 mandates that the mail user agent does some
1235 preparations so that text mode is not needed anymore.
1236
1237 This option is only relevant to the OpenPGP crypto engine, and ignored
1238 by all other engines.
1239
1240 Canonical text mode is disabled if @var{yes} is zero, and enabled
1241 otherwise.
1242 @end deftypefun
1243
1244 @deftypefun int gpgme_get_textmode (@w{GpgmeCtx @var{ctx}})
1245 The function @code{gpgme_get_textmode} returns 1 if canonical text
1246 mode is enabled, and @code{0} if it is not, or if @var{ctx} is not a
1247 valid pointer.
1248 @end deftypefun
1249
1250
1251 @node Included Certificates
1252 @subsection Included Certificates
1253 @cindex certificates, included
1254
1255 @deftypefun void gpgme_set_include_certs (@w{GpgmeCtx @var{ctx}}, @w{int @var{nr_of_certs}})
1256 The function @code{gpgme_set_include_certs} specifies how many
1257 certificates should be included in an S/MIME signed message.  By
1258 default, only the sender's certificate is included.  The possible
1259 values of @var{nr_of_certs} are:
1260
1261 @table @code
1262 @item -2
1263 Include all certificates except the root certificate.
1264 @item -1
1265 Include all certificates.
1266 @item 0
1267 Include no certificates.
1268 @item 1
1269 Include the sender's certificate only.
1270 @item n
1271 Include the first n certificates of the certificates path, starting
1272 from the sender's certificate.  The number @code{n} must be positive.
1273 @end table
1274
1275 Values of @var{nr_of_certs} smaller than -2 are undefined.
1276
1277 This option is only relevant to the CMS crypto engine, and ignored
1278 by all other engines.
1279 @end deftypefun
1280
1281 @deftypefun int gpgme_get_include_certs (@w{GpgmeCtx @var{ctx}})
1282 The function @code{gpgme_get_include_certs} returns the number of
1283 certificates to include into an S/MIME signed message.
1284 @end deftypefun
1285
1286
1287 @node Key Listing Mode
1288 @subsection Key Listing Mode
1289 @cindex key listing mode
1290 @cindex key listing, mode of
1291
1292 @deftypefun void gpgme_set_keylist_mode (@w{GpgmeCtx @var{ctx}}, @w{int @var{mode}})
1293 The function @code{gpgme_set_keylist_mode} changes the default
1294 behaviour of the key listing functions.  The value in @var{mode} is a
1295 bitwise-or combination of one or multiple of the following bit values:
1296
1297 @table @code
1298 @item GPGME_KEYLIST_MODE_LOCAL
1299 The @code{GPGME_KEYLIST_MODE_LOCAL} symbol specifies that the local
1300 keyring should be searched for keys in the keylisting operation.  This
1301 is the default.
1302
1303 @item GPGME_KEYLIST_MODE_EXTERN
1304 The @code{GPGME_KEYLIST_MODE_EXTERN} symbol specifies that an external
1305 source should be should be searched for keys in the keylisting
1306 operation.  The type of external source is dependant on the crypto
1307 engine used.  For example, it can be a remote keyserver or LDAP
1308 certificate server.
1309 @end table
1310
1311 At least one of @code{GPGME_KEYLIST_MODE_LOCAL} and
1312 @code{GPGME_KEYLIST_MODE_EXTERN} must be specified.  For future binary
1313 compatibility, you should get the current mode with
1314 @code{gpgme_get_keylist_mode} and modify it by setting or clearing the
1315 appropriate bits, and then using that calulcated value in the
1316 @code{gpgme_set_keylisting_mode} operation.  This will leave all other
1317 bits in the mode value intact (in particular those that are not used
1318 in the current version of the library).
1319
1320 The function returns @code{GPGME_No_Error} if the mode could be set
1321 correctly, and @code{GPGME_Invalid_Value} if @var{ctx} is not a valid
1322 pointer or @var{mode} is not a valid mode.
1323 @end deftypefun
1324
1325
1326 @deftypefun int gpgme_get_keylist_mode (@w{GpgmeCtx @var{ctx}})
1327 The function @code{gpgme_get_keylist_mode} returns the current key
1328 listing mode of the context @var{ctx}.  This value can then be
1329 modified and used in a subsequent @code{gpgme_set_keylist_mode}
1330 operation to only affect the desired bits (and leave all others
1331 intact).
1332
1333 The function returns 0 if @var{ctx} is not a valid pointer, and the
1334 current mode otherwise.  Note that 0 is not a valid mode value.
1335 @end deftypefun
1336
1337
1338 @node Passphrase Callback
1339 @subsection Passphrase Callback
1340 @cindex callback, passphrase
1341 @cindex passphrase callback
1342
1343 @deftp {Data type} {const char *(*GpgmePassphraseCb)(void *@var{hook}, const char *@var{desc}, void **@var{r_hd})}
1344 @tindex GpgmePassphraseCb
1345 The @code{GpgmePassphraseCb} type is the type of functions usable as
1346 passphrase callback function.
1347
1348 The string @var{desc} contains a text usable to be displayed to the
1349 user of the application.  The function should return a passphrase for
1350 the context when invoked with @var{desc} not being @code{NULL}.
1351
1352 The user may store information about the resources associated with the
1353 returned passphrase in @var{*r_hd}.  When the passphrase is no longer
1354 needed by @acronym{GPGME}, the passphrase callback function will be
1355 called with @var{desc} being @var{NULL}, and @var{r_hd} being the same
1356 as at the first invocation.
1357 @end deftp
1358
1359 @deftypefun void gpgme_set_passphrase_cb (@w{GpgmeCtx @var{ctx}}, @w{GpgmePassphraseCb @var{passfunc}}, @w{void *@var{hook_value}})
1360 The function @code{gpgme_set_passphrase_cb} sets the function that is
1361 used when a passphrase needs to be provided by the user to
1362 @var{passfunc}.  The function @var{passfunc} needs to implemented by
1363 the user, and whenever it is called, it is called with its first
1364 argument being @var{hook_value}.  By default, no passphrase callback
1365 function is set.
1366
1367 Not all crypto engines require this callback to retrieve the
1368 passphrase.  It is better if the engine retrieves the passphrase from
1369 a trusted agent (a daemon process), rather than having each user to
1370 implement their own passphrase query.
1371
1372 The user can disable the use of a passphrase callback function by
1373 calling @code{gpgme_set_passphrase_cb} with @var{passfunc} being
1374 @code{NULL}.
1375 @end deftypefun
1376
1377 @deftypefun void gpgme_get_passphrase_cb (@w{GpgmeCtx @var{ctx}}, @w{GpgmePassphraseCb *@var{passfunc}}, @w{void **@var{hook_value}})
1378 The function @code{gpgme_get_passphrase_cb} returns the function that
1379 is used when a passphrase needs to be provided by the user in
1380 @var{*passfunc}, and the first argument for this function in
1381 @var{*hook_value}.  If no passphrase callback is set, or @var{ctx} is
1382 not a valid pointer, @code{NULL} is returned in both variables.
1383
1384 @var{passfunc} or @var{hook_value} can be @code{NULL}.  In this case,
1385 the corresponding value will not be returned.
1386 @end deftypefun
1387
1388
1389 @node Progress Meter Callback
1390 @subsection Progress Meter Callback
1391 @cindex callback, progress meter
1392 @cindex progress meter callback
1393
1394 @deftp {Data type} {const char *(*GpgmeProgressCb)(void *@var{hook}, const char *@var{what}, int @var{type}, int @var{current}, int @var{total})}
1395 @tindex GpgmeProgressCb
1396 The @code{GpgmeProgressCb} type is the type of functions usable as
1397 progress callback function.
1398
1399 The arguments are specific to the crypto engine.  More information
1400 about the progress information returned from the GnuPG engine can be
1401 found in the GnuPG source code in the file @file{doc/DETAILS} in the
1402 section PROGRESS.
1403 @end deftp
1404
1405 @deftypefun void gpgme_set_progress_cb (@w{GpgmeCtx @var{ctx}}, @w{GpgmeProgressCb @var{progfunc}}, @w{void *@var{hook_value}})
1406 The function @code{gpgme_set_progress_cb} sets the function that is
1407 used when progress information about a cryptographic operation is
1408 available.  The function @var{progfunc} needs to implemented by the
1409 user, and whenever it is called, it is called with its first argument
1410 being @var{hook_value}.  By default, no progress callback function
1411 is set.
1412
1413 Setting a callback function allows an interactive program to display
1414 progress information about a long operation to the user.
1415
1416 The user can disable the use of a progress callback function by
1417 calling @code{gpgme_set_progress_cb} with @var{progfunc} being
1418 @code{NULL}.
1419 @end deftypefun
1420
1421 @deftypefun void gpgme_get_progress_cb (@w{GpgmeCtx @var{ctx}}, @w{GpgmeProgressCb *@var{progfunc}}, @w{void **@var{hook_value}})
1422 The function @code{gpgme_get_progress_cb} returns the function that is
1423 used to inform the user about the progress made in @var{*progfunc},
1424 and the first argument for this function in @var{*hook_value}.  If no
1425 progress callback is set, or @var{ctx} is not a valid pointer,
1426 @code{NULL} is returned in both variables.
1427
1428 @var{progfunc} or @var{hook_value} can be @code{NULL}.  In this case,
1429 the corresponding value will not be returned.
1430 @end deftypefun
1431
1432
1433 @node Key Management
1434 @section Key Management
1435 @cindex key management
1436
1437 Some of the cryptographic operations require that recipients or
1438 signers are specified.  This is always done by specifying the
1439 respective keys that should be used for the operation.  The following
1440 section describes how such keys can be selected and manipulated.
1441
1442 @deftp {Data type} GpgmeKey
1443 The @code{GpgmeKey} type is a handle for a public or secret key, and
1444 is used to select the key for operations involving it.
1445
1446 A key can contain several user IDs and sub keys.
1447 @end deftp
1448
1449 @menu
1450 * Listing Keys::                  Browsing the list of available keys.
1451 * Information About Keys::        Requesting detailed information about keys.
1452 * Manipulating Keys::             Operations on keys.
1453 * Generating Keys::               Creating new key pairs.
1454 * Exporting Keys::                Retrieving key data from the key ring.
1455 * Importing Keys::                Adding keys to the key ring.
1456 * Deleting Keys::                 Removing keys from the key ring.
1457 @end menu
1458
1459
1460 @node Listing Keys
1461 @subsection Listing Keys
1462 @cindex listing keys
1463 @cindex key listing
1464 @cindex key listing, start
1465 @cindex key ring, list
1466 @cindex key ring, search
1467
1468 @deftypefun GpgmeError gpgme_op_keylist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}})
1469 The function @code{gpgme_op_keylist_start} initiates a key listing
1470 operation inside the context @var{ctx}.  It sets everything up so that
1471 subsequent invocations of @code{gpgme_op_keylist_next} return the keys
1472 in the list.
1473
1474 If @var{pattern} is @code{NULL}, all available keys are returned.
1475 Otherwise, @var{pattern} contains an engine specific expression that
1476 is used to limit the list to all keys matching the pattern.
1477
1478 If @var{secret_only} is not @code{0}, the list is restricted to secret
1479 keys only.
1480
1481 The context will be busy until either all keys are received (and
1482 @code{gpgme_op_keylist_next} returns @code{GPGME_EOF}), or
1483 @code{gpgme_op_keylist_end} is called to finish the operation.
1484
1485 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
1486 valid pointer, and passes through any errors that are reported by the
1487 crypto engine support routines.
1488 @end deftypefun
1489
1490 @deftypefun GpgmeError gpgme_op_keylist_ext_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}[]}, @w{int @var{secret_only}}, @w{int @var{reserved}})
1491 The function @code{gpgme_op_keylist_ext_start} initiates an extended
1492 key listing operation inside the context @var{ctx}.  It sets
1493 everything up so that subsequent invocations of
1494 @code{gpgme_op_keylist_next} return the keys in the list.
1495
1496 If @var{pattern} or @var{*pattern} is @code{NULL}, all available keys
1497 are returned.  Otherwise, @var{pattern} is a @code{NULL} terminated
1498 array of strings that are used to limit the list to all keys matching
1499 at least one of the patterns verbatim.
1500
1501 If @var{secret_only} is not @code{0}, the list is restricted to secret
1502 keys only.
1503
1504 The value of @var{reserved} must be @code{0}.
1505
1506 The context will be busy until either all keys are received (and
1507 @code{gpgme_op_keylist_next} returns @code{GPGME_EOF}), or
1508 @code{gpgme_op_keylist_end} is called to finish the operation.
1509
1510 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
1511 valid pointer, and passes through any errors that are reported by the
1512 crypto engine support routines.
1513 @end deftypefun
1514
1515 @deftypefun GpgmeError gpgme_op_keylist_next (@w{GpgmeCtx @var{ctx}}, @w{GpgmeKey *@var{r_key}})
1516 The function @code{gpgme_op_keylist_next} returns the next key in the
1517 list created by a previous @code{gpgme_op_keylist_start} operation in
1518 the context @var{ctx}.  The key will have one reference for the user.
1519 @xref{Manipulating Keys}.
1520
1521 This is the only way to get at @code{GpgmeKey} objects in
1522 @acronym{GPGME}.
1523
1524 If the last key in the list has already been returned,
1525 @code{gpgme_op_keylist_next} returns @code{GPGME_EOF}.
1526
1527 The function returns @code{GPGME_Invalid_Value} if @var{ctx} or
1528 @var{r_key} is not a valid pointer, @code{GPGME_No_Request} if there
1529 is no pending operation, @code{GPGME_Out_Of_Core} if there is not
1530 enough memory for the operation.
1531 @end deftypefun
1532
1533 @deftypefun GpgmeError gpgme_op_keylist_end (@w{GpgmeCtx @var{ctx}})
1534 The function @code{gpgme_op_keylist_next} ends a pending key list
1535 operation in the context @var{ctx}.
1536
1537 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
1538 valid pointer, @code{GPGME_No_Request} if there is no pending
1539 operation, @code{GPGME_Out_Of_Core} if at some time during the
1540 operation there was not enough memory available.
1541 @end deftypefun
1542
1543 The following example illustrates how all keys containing a certain
1544 string (@code{g10code}) can be listed with their key ID and the name
1545 and e-mail address of the main user ID:
1546
1547 @example
1548 GpgmeCtx ctx;
1549 GpgmeError err = gpgme_new (&ctx);
1550
1551 if (!err)
1552   @{
1553     err = gpgme_op_keylist_start (ctx, "g10code", 0);
1554     while (!err && (err = gpgme_op_keylist_next (ctx, &key)) != GPGME_EOF)
1555       @{
1556         printf ("%s: %s <%s>\n",
1557                 gpgme_key_get_string_attr (key, GPGME_ATTR_KEYID, 0, 0),
1558                 gpgme_key_get_string_attr (key, GPGME_ATTR_NAME, 0, 0),
1559                 gpgme_key_get_string_attr (key, GPGME_ATTR_EMAIL, 0, 0));
1560         gpgme_key_release (key);
1561       @}
1562     gpgme_release (ctx);
1563   @}
1564 if (err)
1565   @{
1566     fprintf (stderr, "%s: can not list keys: %s\n",
1567              argv[0], gpgme_strerror (err));
1568     exit (1);
1569   @}
1570 @end example
1571
1572
1573 @node Information About Keys
1574 @subsection Information About Keys
1575 @cindex key, information about
1576 @cindex key, attributes
1577 @cindex attributes, of a key
1578
1579 @deftypefun {char *} gpgme_key_get_as_xml (@w{GpgmeKey @var{key}})
1580 The function @code{gpgme_key_get_as_xml} returns a string in
1581 @acronym{XML} format describing the key @var{key}.  The user has to
1582 release the string with @code{free}.
1583
1584 The function returns @code{NULL} if @var{key} is not a valid pointer,
1585 or there is not enough memory available.
1586 @end deftypefun
1587
1588 @deftp {Data type} GpgmeAttr
1589 The @code{GpgmeAttr} type is used to specify a key or trust item
1590 attribute.  The following attributes are defined:
1591
1592 @table @code
1593 @item GPGME_ATTR_KEYID
1594 This is the key ID of a sub key.  It is representable as a string.
1595
1596 For trust items, the trust item refers to the key with this ID.
1597
1598 @item GPGME_ATTR_FPR
1599 This is the fingerprint of a sub key.  It is representable as a
1600 string.
1601
1602 @item GPGME_ATTR_ALGO
1603 This is the crypto algorithm for which the sub key can be used.  It
1604 is representable as a string and as a number.  The numbers correspond
1605 to the @code{enum gcry_pk_algos} values in the gcrypt library.
1606
1607 @item GPGME_ATTR_LEN
1608 This is the key length of a sub key.  It is representable as a
1609 number.
1610
1611 @item GPGME_ATTR_CREATED
1612 This is the timestamp at creation time of a sub key.  It is
1613 representable as a number.
1614
1615 @item GPGME_ATTR_EXPIRE
1616 This is the expiration time of a sub key.  It is representable as a
1617 number.
1618
1619 @item GPGME_ATTR_OTRUST
1620 XXX FIXME  (also for trust items)
1621
1622 @item GPGME_ATTR_USERID
1623 This is a user ID.  There can be more than one user IDs in a
1624 @var{GpgmeKey} object.  The first one (with index 0) is the primary
1625 user ID.  The user ID is representable as a number.
1626
1627 For trust items, this is the user ID associated with this trust item.
1628
1629 @item GPGME_ATTR_NAME
1630 This is the name belonging to a user ID.  It is representable as a string.
1631
1632 @item GPGME_ATTR_EMAIL
1633 This is the email address belonging to a user ID.  It is representable
1634 as a string.
1635
1636 @item GPGME_ATTR_COMMENT
1637 This is the comment belonging to a user ID.  It is representable as a
1638 string.
1639
1640 @item GPGME_ATTR_VALIDITY
1641 This is the validity belonging to a user ID.  It is representable as a
1642 string and as a number.  See below for a list of available validities.
1643
1644 For trust items, this is the validity that is associated with this
1645 trust item.
1646
1647 @item GPGME_ATTR_UID_REVOKED
1648 This specifies if a user ID is revoked.  It is representable as a
1649 number, and is @code{1} if the user ID is revoked, and @code{0}
1650 otherwise.
1651
1652 @item GPGME_ATTR_UID_INVALID
1653 This specifies if a user ID is invalid.  It is representable as a
1654 number, and is @code{1} if the user ID is invalid, and @code{0}
1655 otherwise.
1656
1657 @item GPGME_ATTR_LEVEL
1658 This is the trust level of a trust item.
1659
1660 @item GPGME_ATTR_TYPE
1661 This returns information about the type of key.  For the string function
1662 this will eother be "PGP" or "X.509".  The integer function returns 0
1663 for PGP and 1 for X.509.  It is also used for the type of a trust item.
1664
1665 @item GPGME_ATTR_IS_SECRET
1666 This specifies if the key is a secret key.  It is representable as a
1667 string or a number.  If the key is a secret key, the representation is
1668 ``1'' or @code{1}, otherwise it is @code{NULL} or @code{0}.
1669
1670 @item GPGME_ATTR_KEY_REVOKED
1671 This specifies if a sub key is revoked.  It is representable as a
1672 number, and is @code{1} if the key is revoked, and @code{0} otherwise.
1673
1674 @item GPGME_ATTR_KEY_INVALID
1675 This specifies if a sub key is invalid.  It is representable as a
1676 number, and is @code{1} if the key is invalid, and @code{0} otherwise.
1677
1678 @item GPGME_ATTR_KEY_EXPIRED
1679 This specifies if a sub key is expired.  It is representable as a
1680 number, and is @code{1} if the key is expired, and @code{0} otherwise.
1681
1682 @item GPGME_ATTR_KEY_DISABLED
1683 This specifies if a sub key is disabled.  It is representable as a
1684 number, and is @code{1} if the key is disabled, and @code{0} otherwise.
1685
1686 @item GPGME_ATTR_KEY_CAPS
1687 This is a description of the capabilities of a sub key.  It is
1688 representable as a string.  The string contains the letter ``e'' if
1689 the key can be used for encryption, ``s'' if the key can be used for
1690 signatures, and ``c'' if the key can be used for certifications.
1691
1692 @item GPGME_ATTR_CAN_ENCRYPT
1693 This specifies if a sub key can be used for encryption.  It is
1694 representable as a number, and is @code{1} if the sub key can be used
1695 for encryption, and @code{0} otherwise.
1696
1697 @item GPGME_ATTR_CAN_SIGN
1698 This specifies if a sub key can be used for signatures.  It is
1699 representable as a number, and is @code{1} if the sub key can be used
1700 for signatures, and @code{0} otherwise.
1701
1702 @item GPGME_ATTR_CAN_CERTIFY
1703 This specifies if a sub key can be used for certifications.  It is
1704 representable as a number, and is @code{1} if the sub key can be used
1705 for certifications, and @code{0} otherwise.
1706
1707 @item GPGME_ATTR_SERIAL
1708 The X.509 issuer serial attribute of the key.  It is representable as
1709 a string.
1710
1711 @item GPGME_ATTR_ISSUE
1712 The X.509 issuer name attribute of the key.  It is representable as a
1713 string.
1714
1715 @item GPGME_ATTR_CHAINID
1716 The X.509 chain ID can be used to build the certification chain.  It
1717 is representable as a string.
1718 @end table
1719 @end deftp
1720
1721 @deftp {Data type} GpgmeValidity
1722 The @code{GpgmeValidity} type is used to specify the validity of a user ID
1723 in a key.  The following validities are defined:
1724
1725 @table @code
1726 @item GPGME_VALIDITY_UNKNOWN
1727 The user ID is of unknown validity.  The string representation of this
1728 validity is ``?''.
1729
1730 @item GPGME_VALIDITY_UNDEFINED
1731 The validity of the user ID is undefined.  The string representation of this
1732 validity is ``q''.
1733
1734 @item GPGME_VALIDITY_NEVER
1735 The user ID is never valid.  The string representation of this
1736 validity is ``n''.
1737
1738 @item GPGME_VALIDITY_MARGINAL
1739 The user ID is marginally valid.  The string representation of this
1740 validity is ``m''.
1741
1742 @item GPGME_VALIDITY_FULL
1743 The user ID is fully valid.  The string representation of this
1744 validity is ``f''.
1745
1746 @item GPGME_VALIDITY_ULTIMATE
1747 The user ID is ultimately valid.  The string representation of this
1748 validity is ``u''.
1749 @end table
1750 @end deftp
1751
1752 @deftypefun {const char *} gpgme_key_get_string_attr (@w{GpgmeKey @var{key}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
1753 The function @code{gpgme_key_get_string_attr} returns the value of the
1754 string-representable attribute @var{what} of key @var{key}.  If the
1755 attribute is an attribute of a sub key or an user ID, @var{idx}
1756 specifies the sub key or user ID of which the attribute value is
1757 returned.  The argument @var{reserved} is reserved for later use and
1758 should be @code{NULL}.
1759
1760 The string returned is only valid as long as the key is valid.
1761
1762 The function returns @code{0} if an attribute can't be returned as a
1763 string, @var{key} is not a valid pointer, @var{idx} out of range,
1764 or @var{reserved} not @code{NULL}.
1765 @end deftypefun
1766
1767 @deftypefun {unsigned long} gpgme_key_get_ulong_attr (@w{GpgmeKey @var{key}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
1768 The function @code{gpgme_key_get_ulong_attr} returns the value of the
1769 number-representable attribute @var{what} of key @var{key}.  If the
1770 attribute is an attribute of a sub key or an user ID, @var{idx}
1771 specifies the sub key or user ID of which the attribute value is
1772 returned.  The argument @var{reserved} is reserved for later use and
1773 should be @code{NULL}.
1774
1775 The function returns @code{0} if the attribute can't be returned as a
1776 number, @var{key} is not a valid pointer, @var{idx} out of range,
1777 or @var{reserved} not @code{NULL}.
1778 @end deftypefun
1779
1780
1781 @node Manipulating Keys
1782 @subsection Manipulating Keys
1783 @cindex key, manipulation
1784
1785 @deftypefun void gpgme_key_ref (@w{GpgmeKey @var{key}})
1786 The function @code{gpgme_key_ref} acquires an additional reference for
1787 the key @var{key}.
1788 @end deftypefun
1789
1790 @deftypefun void gpgme_key_unref (@w{GpgmeKey @var{key}})
1791 @deftypefunx void gpgme_key_release (@w{GpgmeKey @var{key}})
1792 The function @code{gpgme_key_ref} releases a reference for the key
1793 @var{key}.  If this was the last reference, the key will be destroyed
1794 and all resources associated to it will be released.
1795
1796 The function @code{gpgme_key_release} is an alias for
1797 @code{gpgme_key_unref}.
1798 @end deftypefun
1799
1800
1801 @node Generating Keys
1802 @subsection Generating Keys
1803 @cindex key, creation
1804 @cindex key ring, add
1805
1806 @deftypefun GpgmeError gpgme_op_genkey (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{pubkey}}, @w{GpgmeData @var{seckey}}, @w{char **@var{fpr}})
1807 The function @code{gpgme_op_genkey} generates a new key pair in the
1808 context @var{ctx} and puts it into the standard key ring if both
1809 @var{pubkey} and @var{seckey} are @code{NULL}.  In this case the
1810 function returns immediately after starting the operation, and does
1811 not wait for it to complete.  If @var{pubkey} is not @code{NULL} it
1812 should be the handle for an empty (newly created) data object, and
1813 upon successful completion the data object will contain the public
1814 key.  If @var{seckey} is not @code{NULL} it should be the handle for
1815 an empty (newly created) data object, and upon successful completion
1816 the data object will contain the secret key.
1817
1818 Note that not all crypto engines support this interface equally.
1819 GnuPG does not support @var{pubkey} and @var{subkey}, they should be
1820 both @code{NULL}, and the key pair will be added to the standard key
1821 ring.  GpgSM does only support @var{pubkey}, the secret key will be
1822 stored by @command{gpg-agent}.  GpgSM expects @var{pubkey} being not
1823 @code{NULL}.
1824
1825 The argument @var{parms} specifies parameters for the key in an XML
1826 string.  The details about the format of @var{parms} are specific to
1827 the crypto engine used by @var{ctx}.  Here is an example for GnuPG as
1828 the crypto engine:
1829
1830 @example
1831 <GnupgKeyParms format="internal">
1832 Key-Type: DSA
1833 Key-Length: 1024
1834 Subkey-Type: ELG-E
1835 Subkey-Length: 1024
1836 Name-Real: Joe Tester
1837 Name-Comment: with stupid passphrase
1838 Name-Email: joe@@foo.bar
1839 Expire-Date: 0
1840 Passphrase: abc
1841 </GnupgKeyParms>
1842 @end example
1843
1844 Here is an example for GpgSM as the crypto engine:
1845 @example
1846 <GnupgKeyParms format="internal">
1847 Key-Type: RSA
1848 Key-Length: 1024
1849 Name-DN: C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester
1850 Name-Email: joe@@foo.bar
1851 </GnupgKeyParms>
1852 @end example
1853
1854 Strings should be given in UTF-8 encoding.  The only format supported
1855 for now is ``internal''.  The content of the @code{GnupgKeyParms}
1856 container is passed verbatim to GnuPG.  Control statements are not
1857 allowed.
1858
1859 If @var{fpr} is not a null pointer, the function succeeds, and the
1860 crypto engine supports it, *@var{fpr} will contain a string with the
1861 fingerprint of the key, allocated with @code{malloc}.  If both a
1862 primary and a sub key was generated, the fingerprint of the primary
1863 key will be returned.  If the crypto engine does not provide the
1864 fingerprint, *@var{fpr} will be a null pointer.
1865
1866 The function returns @code{GPGME_No_Error} if the operation could be
1867 started successfully, @code{GPGME_Invalid_Value} if @var{parms} is not
1868 a valid XML string, @code{GPGME_Not_Supported} if @var{pubkey} or
1869 @var{seckey} is not valid, and @code{GPGME_General_Error} if no key
1870 was created by the backend.
1871 @end deftypefun
1872
1873 @deftypefun GpgmeError gpgme_op_genkey_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{pubkey}}, @w{GpgmeData @var{seckey}})
1874 The function @code{gpgme_op_genkey_start} initiates a
1875 @code{gpgme_op_genkey} operation.  It can be completed by calling
1876 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
1877
1878 The function returns @code{GPGME_No_Error} if the operation could be
1879 started successfully, @code{GPGME_Invalid_Value} if @var{parms} is not
1880 a valid XML string, and @code{GPGME_Not_Supported} if @var{pubkey} or
1881 @var{seckey} is not @code{NULL}.
1882 @end deftypefun
1883
1884
1885 @node Exporting Keys
1886 @subsection Exporting Keys
1887 @cindex key, export
1888 @cindex key ring, export from
1889
1890 @deftypefun GpgmeError gpgme_op_export (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{recipients}}, @w{GpgmeData @var{keydata}})
1891 The function @code{gpgme_op_export} extracts the public keys of the
1892 user IDs in @var{recipients} and returns them in the data buffer
1893 @var{keydata}.  The type of the public keys returned is determined by
1894 the @acronym{ASCII} armor attribute set for the context @var{ctx}.
1895
1896 The function returns @code{GPGME_No_Error} if the operation completed
1897 successfully, @code{GPGME_Invalid_Value} if @var{recipients} is
1898 @code{NULL} or @var{keydata} is not a valid empty data buffer, and
1899 passes through any errors that are reported by the crypto engine
1900 support routines.
1901 @end deftypefun
1902
1903 @deftypefun GpgmeError gpgme_op_export_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{recipients}}, @w{GpgmeData @var{keydata}})
1904 The function @code{gpgme_op_export_start} initiates a
1905 @code{gpgme_op_export} operation.  It can be completed by calling
1906 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
1907
1908 The function returns @code{GPGME_No_Error} if the operation could be
1909 started successfully, and @code{GPGME_Invalid_Value} if
1910 @var{recipients} is @code{NULL} or @var{keydata} is not a valid empty
1911 data buffer.
1912 @end deftypefun
1913
1914
1915 @node Importing Keys
1916 @subsection Importing Keys
1917 @cindex key, import
1918 @cindex key ring, import to
1919
1920 @deftypefun GpgmeError gpgme_op_import (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}})
1921 The function @code{gpgme_op_import} adds the keys in the data buffer
1922 @var{keydata} to the key ring of the crypto engine used by @var{ctx}.
1923 The format of @var{keydata} can be @var{ASCII} armored, for example,
1924 but the details are specific to the crypto engine.
1925
1926 More information about the import is available with
1927 @code{gpgme_get_op_info}.  @xref{Detailed Results}.
1928
1929 The function returns @code{GPGME_No_Error} if the import was completed
1930 successfully, @code{GPGME_Invalid_Value} if @var{keydata} if @var{ctx}
1931 or @var{keydata} is not a valid pointer, and @code{GPGME_No_Data} if
1932 @var{keydata} is an empty data buffer.
1933 @end deftypefun
1934
1935 @deftypefun GpgmeError gpgme_op_import_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}})
1936 The function @code{gpgme_op_import_start} initiates a
1937 @code{gpgme_op_import} operation.  It can be completed by calling
1938 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
1939
1940 The function returns @code{GPGME_No_Error} if the import could be
1941 started successfully, @code{GPGME_Invalid_Value} if @var{keydata} if
1942 @var{ctx} or @var{keydata} is not a valid pointer, and
1943 @code{GPGME_No_Data} if @var{keydata} is an empty data buffer.
1944 @end deftypefun
1945
1946 @deftypefun GpgmeError gpgme_op_import_ext (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}}, @w{int *@var{nr}})
1947 The function @code{gpgme_op_import_ext} is like
1948 @code{gpgme_op_import}, but also returns the number of processed keys
1949 in @var{nr}.  This is the same as the @code{count} information in the
1950 detailed results available with @code{gpgme_get_op_info}.
1951 @end deftypefun
1952
1953
1954 @node Deleting Keys
1955 @subsection Deleting Keys
1956 @cindex key, delete
1957 @cindex key ring, delete from
1958
1959 @deftypefun GpgmeError gpgme_op_delete (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}, @w{int @var{allow_secret}})
1960 The function @code{gpgme_op_delete} deletes the key @var{key} from the
1961 key ring of the crypto engine used by @var{ctx}.  If
1962 @var{allow_secret} is @code{0}, only public keys are deleted,
1963 otherwise secret keys are deleted as well, if that is supported.
1964
1965 The function returns @code{GPGME_No_Error} if the key was deleted
1966 successfully, @code{GPGME_Invalid_Value} if @var{ctx} or @var{key} is
1967 not a valid pointer, @code{GPGME_Invalid_Key} if @var{key} could not
1968 be found in the keyring, and @code{GPGME_Conflict} if the secret key
1969 for @var{key} is available, but @var{allow_secret} is zero.
1970 @end deftypefun
1971
1972 @deftypefun GpgmeError gpgme_op_delete_start (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}, @w{int @var{allow_secret}})
1973 The function @code{gpgme_op_delete_start} initiates a
1974 @code{gpgme_op_delete} operation.  It can be completed by calling
1975 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
1976
1977 The function returns @code{GPGME_No_Error} if the operation was
1978 started successfully, and @code{GPGME_Invalid_Value} if @var{ctx} or
1979 @var{key} is not a valid pointer.
1980 @end deftypefun
1981
1982
1983 @node Trust Item Management
1984 @section Trust Item Management
1985 @cindex trust item
1986
1987 @strong{Caution:} The trust items interface is experimental.
1988
1989 @deftp {Data type} GpgmeTrustItem
1990 The @code{GpgmeTrustItem} type is a handle for a trust item.
1991 @end deftp
1992
1993 @menu
1994 * Listing Trust Items::           Browsing the list of available trust items.
1995 * Information About Trust Items:: Requesting detailed information about trust items.
1996 * Manipulating Trust Items::      Operations on trust items.
1997 @end menu
1998
1999
2000 @node Listing Trust Items
2001 @subsection Listing Trust Items
2002 @cindex trust item list
2003
2004 @deftypefun GpgmeError gpgme_op_trustlist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{max_level}})
2005 The function @code{gpgme_op_trustlist_start} initiates a trust item
2006 listing operation inside the context @var{ctx}.  It sets everything up
2007 so that subsequent invocations of @code{gpgme_op_trustlist_next} return
2008 the trust items in the list.
2009
2010 The string @var{pattern} contains an engine specific expression that
2011 is used to limit the list to all trust items matching the pattern.  It
2012 can not be the empty string.
2013
2014 The argument @var{max_level} is currently ignored.
2015
2016 The context will be busy until either all trust items are received
2017 (and @code{gpgme_op_trustlist_next} returns @code{GPGME_EOF}), or
2018 @code{gpgme_op_trustlist_end} is called to finish the operation.
2019
2020 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
2021 valid pointer, and passes through any errors that are reported by the
2022 crypto engine support routines.
2023 @end deftypefun
2024
2025 @deftypefun GpgmeError gpgme_op_trustlist_next (@w{GpgmeCtx @var{ctx}}, @w{GpgmeTrustItem *@var{r_item}})
2026 The function @code{gpgme_op_trustlist_next} returns the next trust
2027 item in the list created by a previous @code{gpgme_op_trustlist_start}
2028 operation in the context @var{ctx}.  The trust item can be destroyed
2029 with @code{gpgme_trust_item_release}.  @xref{Manipulating Trust Items}.
2030
2031 This is the only way to get at @code{GpgmeTrustItem} objects in
2032 @acronym{GPGME}.
2033
2034 If the last trust item in the list has already been returned,
2035 @code{gpgme_op_trustlist_next} returns @code{GPGME_EOF}.
2036
2037 The function returns @code{GPGME_Invalid_Value} if @var{ctx} or
2038 @var{r_item} is not a valid pointer, @code{GPGME_No_Request} if there
2039 is no pending operation, @code{GPGME_Out_Of_Core} if there is not
2040 enough memory for the operation.
2041 @end deftypefun
2042
2043 @deftypefun GpgmeError gpgme_op_trustlist_end (@w{GpgmeCtx @var{ctx}})
2044 The function @code{gpgme_op_trustlist_next} ends a pending key list
2045 operation in the context @var{ctx}.
2046
2047 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
2048 valid pointer, @code{GPGME_No_Request} if there is no pending
2049 operation, @code{GPGME_Out_Of_Core} if at some time during the
2050 operation there was not enough memory available.
2051 @end deftypefun
2052
2053
2054 @node Information About Trust Items
2055 @subsection Information About Trust Items
2056 @cindex trust item, information about
2057 @cindex trust item, attributes
2058 @cindex attributes, of a trust item
2059
2060 Trust items have attributes which can be queried using the interfaces
2061 below.  The attribute identifiers are shared with those for key
2062 attributes.  @xref{Information About Keys}.
2063
2064 @deftypefun {const char *} gpgme_trust_item_get_string_attr (@w{GpgmeTrustItem @var{item}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
2065 The function @code{gpgme_trust_item_get_string_attr} returns the value
2066 of the string-representable attribute @var{what} of trust item
2067 @var{item}.  The arguments @var{idx} and @var{reserved} are reserved
2068 for later use and should be @code{0} and @code{NULL} respectively.
2069
2070 The string returned is only valid as long as the key is valid.
2071
2072 The function returns @code{0} if an attribute can't be returned as a
2073 string, @var{key} is not a valid pointer, @var{idx} out of range,
2074 or @var{reserved} not @code{NULL}.
2075 @end deftypefun
2076
2077 @deftypefun int gpgme_trust_item_get_int_attr (@w{GpgmeTrustItem @var{item}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
2078 The function @code{gpgme_trust_item_get_int_attr} returns the value of
2079 the number-representable attribute @var{what} of trust item
2080 @var{item}.  If the attribute occurs more than once in the trust item,
2081 the index is specified by @var{idx}.  However, currently no such
2082 attribute exists, so @var{idx} should be @code{0}.  The argument
2083 @var{reserved} is reserved for later use and should be @code{NULL}.
2084
2085 The function returns @code{0} if the attribute can't be returned as a
2086 number, @var{key} is not a valid pointer, @var{idx} out of range,
2087 or @var{reserved} not @code{NULL}.
2088 @end deftypefun
2089
2090
2091 @node Manipulating Trust Items
2092 @subsection Manipulating Trust Items
2093 @cindex trust item, manipulation
2094
2095 @deftypefun void gpgme_trust_item_release (@w{GpgmeTrustItem @var{item}})
2096 The function @code{gpgme_trust_item_release} destroys a
2097 @code{GpgmeTrustItem} object and releases all associated resources.
2098 @end deftypefun
2099
2100 @node Crypto Operations
2101 @section Crypto Operations
2102 @cindex cryptographic operation
2103
2104 @menu
2105 * Decrypt::                       Decrypting a ciphertext.
2106 * Verify::                        Verifying a signature.
2107 * Decrypt and Verify::            Decrypting a signed ciphertext.
2108 * Sign::                          Creating a signature.
2109 * Encrypt::                       Encrypting a plaintext.
2110 * Detailed Results::              How to obtain more info about the operation.
2111 @end menu
2112
2113
2114 @node Decrypt
2115 @subsection Decrypt
2116 @cindex decryption
2117 @cindex cryptographic operation, decryption
2118
2119 @deftypefun GpgmeError gpgme_op_decrypt (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
2120 The function @code{gpgme_op_decrypt} decrypts the ciphertext in the
2121 data object @var{cipher} and stores it into the data object
2122 @var{plain}.
2123
2124 The function returns @code{GPGME_No_Error} if the ciphertext could be
2125 decrypted successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2126 @var{cipher} or @var{plain} is not a valid pointer,
2127 @code{GPGME_No_Data} if @var{cipher} does not contain any data to
2128 decrypt, @code{GPGME_Decryption_Failed} if @var{cipher} is not a valid
2129 cipher text, @code{GPGME_No_Passphrase} if the passphrase for the
2130 secret key could not be retrieved, and passes through any errors that
2131 are reported by the crypto engine support routines.
2132 @end deftypefun
2133
2134 @deftypefun GpgmeError gpgme_op_decrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
2135 The function @code{gpgme_op_decrypt_start} initiates a
2136 @code{gpgme_op_decrypt} operation.  It can be completed by calling
2137 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
2138
2139 The function returns @code{GPGME_No_Error} if the operation could be
2140 started successfully, and @code{GPGME_Invalid_Value} if @var{cipher}
2141 or @var{plain} is not a valid pointer.
2142 @end deftypefun
2143
2144
2145 @node Verify
2146 @subsection Verify
2147 @cindex verification
2148 @cindex signature, verification
2149 @cindex cryptographic operation, verification
2150 @cindex cryptographic operation, signature check
2151 @cindex signature, status
2152
2153 @deftp {Data type} {enum GpgmeSigStat}
2154 @tindex GpgmeSigStat
2155 The @code{GpgmeSigStat} type holds the result of a signature check, or
2156 the combined result of all signatures.  The following results are
2157 possible:
2158
2159 @table @code
2160 @item GPGME_SIG_STAT_NONE
2161 This status should not occur in normal operation.
2162
2163 @item GPGME_SIG_STAT_GOOD
2164 This status indicates that the signature is valid.  For the combined
2165 result this status means that all signatures are valid.
2166
2167 @item GPGME_SIG_STAT_GOOD_EXP
2168 This status indicates that the signature is valid but expired.  For
2169 the combined result this status means that all signatures are valid
2170 and expired.
2171
2172 @item GPGME_SIG_STAT_GOOD_EXPKEY
2173 This status indicates that the signature is valid but the key used to
2174 verify the signature has expired.  For the combined result this status
2175 means that all signatures are valid and all keys are expired.
2176
2177 @item GPGME_SIG_STAT_BAD
2178 This status indicates that the signature is invalid.  For the combined
2179 result this status means that all signatures are invalid.
2180
2181 @item GPGME_SIG_STAT_NOKEY
2182 This status indicates that the signature could not be verified due to
2183 a missing key.  For the combined result this status means that all
2184 signatures could not be checked due to missing keys.
2185
2186 @item GPGME_SIG_STAT_NOSIG
2187 This status indicates that the signature data provided was not a real
2188 signature.
2189
2190 @item GPGME_SIG_STAT_ERROR
2191 This status indicates that there was some other error which prevented
2192 the signature verification.
2193
2194 @item GPGME_SIG_STAT_DIFF
2195 For the combined result this status means that at least two signatures
2196 have a different status.  You can get each key's status with
2197 @code{gpgme_get_sig_status}.
2198 @end table
2199 @end deftp
2200
2201 @deftypefun GpgmeError gpgme_op_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{sig}}, @w{GpgmeData @var{plain}}, @w{GpgmeSigStat *@var{r_stat}})
2202 The function @code{gpgme_op_verify} verifies that the signature in the
2203 data object @var{sig} is a valid signature.  If @var{plain} is
2204 initialized with plaintext data, it is assumed that @var{sig} is a
2205 detached signature, and its validity for the plaintext given in
2206 @var{plain} is verified.  If @var{plain} is an uninitialized data
2207 object, it is assumed that @var{sig} is a normal (or cleartext)
2208 signature, and the plaintext is available in @var{plain} after
2209 successful verification.
2210
2211 The combined status of all signatures is returned in @var{r_stat}.
2212 The results of the individual signature verifications can be retrieved
2213 with @code{gpgme_get_sig_status} and @code{gpgme_get_sig_key}.
2214
2215 The function returns @code{GPGME_No_Error} if the operation could be
2216 completed successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2217 @var{sig}, @var{plain} or @var{r_stat} is not a valid pointer,
2218 @code{GPGME_No_Data} if @var{sig} does not contain any data to verify,
2219 and passes through any errors that are reported by the crypto engine
2220 support routines.
2221 @end deftypefun
2222
2223 @deftypefun GpgmeError gpgme_op_verify_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{sig}}, @w{GpgmeData @var{plain}})
2224 The function @code{gpgme_op_verify_start} initiates a
2225 @code{gpgme_op_verify} operation.  It can be completed by calling
2226 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
2227
2228 The function returns @code{GPGME_No_Error} if the operation could be
2229 started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2230 @var{sig}, @var{plain} or @var{r_stat} is not a valid pointer, and
2231 @code{GPGME_No_Data} if @var{sig} or @var{plain} does not contain any
2232 data to verify.
2233 @end deftypefun
2234
2235 @deftypefun {const char *} gpgme_get_sig_status (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeSigStat *@var{r_stat}}, @w{time_t *@var{r_created}})
2236 The function @code{gpgme_get_sig_status} receives information about a
2237 signature after the @code{gpgme_op_verify} or
2238 @code{gpgme_op_verify_decrypt} operation.  A single detached signature
2239 can contain signatures by more than one key.  The @var{idx} specifies
2240 which signature's information should be retrieved, starting from
2241 @var{0}.
2242
2243 The status of the signature will be returned in @var{r_stat} if it is
2244 not @code{NULL}.  The creation time stamp of the signature will be
2245 returned in @var{r_created} if it is not @var{NULL}.
2246
2247 The function returns a statically allocated string that contains the
2248 fingerprint of the key which signed the plaintext, or @code{NULL} if
2249 @var{ctx} is not a valid pointer, the operation is still pending, or
2250 no verification could be performed.
2251 @end deftypefun
2252
2253 @deftypefun {const char *} gpgme_get_sig_string_attr (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeAttr @var{what}}, @w{int @var{whatidx}})
2254 This function is similar to @code{gpgme_get_sig_status} but may be used
2255 to retrieve more detailed information.  @var{ctx} should be the context
2256 used for the last signature verification, @var{idx} is used to enumerate
2257 over all signatures starting with @code{0} and @var{whatidx} should be
2258 @code{0} unless otherwise stated.
2259
2260 The following values may be used for @var{what}:
2261 @table @code
2262 @item GPGME_ATTR_FPR
2263 Return the fingerprint of the key used to create the signature.
2264
2265 @item GPGME_ATTR_ERRTOK
2266 Return a token with a more detailed error description.  A @var{whatidx}
2267 of @code{0} returns an error token associated with validity calculation,
2268 a value of @code{1} return an error token related to the certificate
2269 checking.
2270
2271 @end table
2272 @end deftypefun
2273
2274 @deftypefun {const char *} gpgme_get_sig_ulong_attr (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeAttr @var{waht}}, @w{int @var{whatidx}})
2275 This function is similar to @code{gpgme_get_sig_string_attr} but used
2276 for attributes which can be represented by an @code{unsigned long} data
2277 type.  @var{ctx} should be the context used for the last signature
2278 verification, @var{idx} is used to enumerate over all signatures
2279 starting with @code{0} and @var{whatidx} should be @code{0} unless
2280 otherwise stated.
2281
2282 The following values may be used for @var{what}:
2283 @table @code
2284 @item GPGME_ATTR_CREATED
2285 Return the creation time of the signature in seconds since Epoch.  This
2286 is the same value as returned by @code{gpgme_get_sig_status}.
2287
2288 @item GPGME_ATTR_EXPIRE
2289 Return the expiration time of the signature in seconds since Epoch. 
2290
2291 @item GPGME_ATTR_VALIDITY
2292 Returns the validity of the key used to create the signature.  This is a
2293 shortcut function which avoids an extra key lookup.  The value returned
2294 is one of @code{GPGME_VALIDITY_UNKNOWN}, @code{GPGME_VALIDITY_NEVER},
2295 @code{GPGME_VALIDITY_MARGINAL} or @code{GPGME_VALIDITY_FULL}.
2296
2297 @item GPGME_ATTR_SIG_STATUS
2298 This is the same value as returned by @code{gpgme_get_sig_status}.
2299
2300 @item GPGME_ATTR_SIG_SUMMARY
2301 This returns a bit vector giving a summary of the signature status.
2302 Itprovides an easy interface to a defined semantic of the signature
2303 status.  Checking just one bit is sufficient to see whether a signature
2304 is valid without any restrictions.
2305
2306 The defined bits are:
2307   @table @code
2308   @item GPGME_SIGSUM_VALID
2309   The signature is fully valid.
2310
2311   @item GPGME_SIGSUM_GREEN
2312   The signature is good but one might want to display some extra
2313   information.  Check the other bits.
2314
2315   @item GPGME_SIGSUM_RED
2316   The signature is bad. It might be useful to checkother bits and
2317   display moe information, i.e. a revoked certificate might not render a
2318   signature invalid when the message was received prior to the cause for
2319   the revocation.
2320
2321   @item GPGME_SIGSUM_KEY_REVOKED
2322   The key or at least one certificate has been revoked.
2323
2324   @item GPGME_SIGSUM_KEY_EXPIRED
2325   The key or one of the certificates has expired. It is probably a good
2326   idea to display the date of the expiration.
2327
2328   @item GPGME_SIGSUM_SIG_EXPIRED
2329   The signature has expired.
2330
2331   @item GPGME_SIGSUM_KEY_MISSING
2332   Can't verifydue to a missing key o certificate.
2333
2334   @item GPGME_SIGSUM_CRL_MISSING
2335   The CRL (or an equivalent mechanism) is not available. 
2336
2337   @item GPGME_SIGSUM_CRL_TOO_OLD
2338   Available CRL is too old.
2339
2340   @item GPGME_SIGSUM_BAD_POLICY
2341   A policy requirement was not met. 
2342
2343   @item GPGME_SIGSUM_SYS_ERROR
2344   A system error occured. 
2345
2346   @end table
2347
2348 @end table
2349 @end deftypefun
2350
2351
2352 @deftypefun {const char *} gpgme_get_sig_key (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeKey *@var{r_key}})
2353 The function @code{gpgme_get_sig_status} receives a @code{GpgmeKey}
2354 object for the key which was used to verify the signature after the
2355 @code{gpgme_op_verify} or @code{gpgme_op_verify_decrypt} operation.  A
2356 single detached signature can contain signatures by more than one key.
2357 The @var{idx} specifies which signature's information should be
2358 retrieved, starting from @var{0}.  The key will have on reference for
2359 the user.
2360
2361 The function is a convenient way to retrieve the keys belonging to the
2362 fingerprints returned by @code{gpgme_get_sig_status}.
2363
2364 The function returns @code{GPGME_No_Error} if the key could be
2365 returned, @code{GPGME_Invalid_Value} if @var{r_key} is not a valid
2366 pointer, @code{GPGME_Invalid_Key} if the fingerprint is not valid,
2367 @code{GPGME_EOF} if @var{idx} is too large, or some other error value
2368 if a problem occurred requesting the key.
2369 @end deftypefun
2370
2371 @deftypefun {char *} gpgme_get_notation (@w{GpgmeCtx @var{ctx}})
2372 The function @code{gpgme_get_notation} can be used to retrieve
2373 notation data from the last signature check in the context @var{ctx}.
2374
2375 If there is notation data available from the last signature check,
2376 this function may be used to return this notation data as a string.
2377 The string is an XML representation of that data embedded in a
2378 <notation> container.  The user has to release the string with
2379 @code{free}.
2380
2381 The function returns a string if the notation data is available or
2382 @code{NULL} if there is no such data available.
2383 @end deftypefun
2384
2385
2386 @node Decrypt and Verify
2387 @subsection Decrypt and Verify
2388 @cindex decryption and verification
2389 @cindex verification and decryption
2390 @cindex signature check
2391 @cindex cryptographic operation, decryption and verification
2392
2393 @deftypefun GpgmeError gpgme_op_decrypt_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}}, @w{GpgmeSigStat *@var{r_stat}})
2394 The function @code{gpgme_op_decrypt_verify} decrypts the ciphertext in
2395 the data object @var{cipher} and stores it into the data object
2396 @var{plain}.  If @var{cipher} contains signatures, they will be
2397 verified and their combined status will be returned in @var{r_stat}.
2398
2399 After the operation completed, @code{gpgme_op_get_sig_status} and
2400 @code{gpgme_op_get_sig_key} can be used to retrieve more information
2401 about the signatures.
2402
2403 The function returns @code{GPGME_No_Error} if the ciphertext could be
2404 decrypted successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2405 @var{cipher}, @var{plain} or @var{r_stat} is not a valid pointer,
2406 @code{GPGME_No_Data} if @var{cipher} does not contain any data to
2407 decrypt, @code{GPGME_Decryption_Failed} if @var{cipher} is not a valid
2408 cipher text, @code{GPGME_No_Passphrase} if the passphrase for the
2409 secret key could not be retrieved, and passes through any errors that
2410 are reported by the crypto engine support routines.
2411 @end deftypefun
2412
2413 @deftypefun GpgmeError gpgme_op_decrypt_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
2414 The function @code{gpgme_op_decrypt_verify_start} initiates a
2415 @code{gpgme_op_decrypt_verify} operation.  It can be completed by
2416 calling @code{gpgme_wait} on the context.  @xref{Waiting For
2417 Completion}.
2418
2419 The function returns @code{GPGME_No_Error} if the operation could be
2420 started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2421 @var{cipher}, @var{plain} or @var{r_stat} is not a valid pointer, and
2422 @code{GPGME_No_Data} if @var{cipher} does not contain any data to
2423 decrypt.
2424 @end deftypefun
2425
2426
2427 @node Sign
2428 @subsection Sign
2429 @cindex signature, creation
2430 @cindex sign
2431 @cindex cryptographic operation, signing
2432
2433 A signature can contain signatures by one or more keys.  The set of
2434 keys used to create a signatures is contained in a context, and is
2435 applied to all following signing operations in this context (until the
2436 set is changed).
2437
2438 @menu
2439 * Selecting Signers::             How to choose the keys to sign with.
2440 * Creating a Signature::          How to create a signature.
2441 @end menu
2442
2443
2444 @node Selecting Signers
2445 @subsubsection Selecting Signers
2446 @cindex signature, selecting signers
2447 @cindex signers, selecting
2448
2449 @deftypefun void gpgme_signers_clear (@w{GpgmeCtx @var{ctx}})
2450 The function @code{gpgme_signers_clear} releases a reference for each
2451 key on the signers list and removes the list of signers from the
2452 context @var{ctx}.
2453
2454 Every context starts with an empty list.
2455 @end deftypefun
2456
2457 @deftypefun GpgmeError gpgme_signers_add (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}})
2458 The function @code{gpgme_signers_add} adds the key @var{key} to the
2459 list of signers in the context @var{ctx}.
2460
2461 Calling this function acquires an additional reference for the key.
2462 @end deftypefun
2463
2464 @deftypefun GpgmeKey gpgme_signers_enum (@w{const GpgmeCtx @var{ctx}}, @w{int @var{seq}})
2465 The function @code{gpgme_signers_enum} returns the @var{seq}th key in
2466 the list of signers in the context @var{ctx}.  An additional reference
2467 is acquired for the user.
2468
2469 If @var{seq} is out of range, @code{NULL} is returned.
2470 @end deftypefun
2471
2472
2473 @node Creating a Signature
2474 @subsubsection Creating a Signature
2475
2476 @deftp {Data type} {enum GpgmeSigMode}
2477 @tindex GpgmeSigMode
2478 The @code{GpgmeSigMode} type is used to specify the desired type of a
2479 signature.  The following modes are available:
2480
2481 @table @code
2482 @item GPGME_SIG_MODE_NORMAL
2483 A normal signature is made, the output includes the plaintext and the
2484 signature.
2485
2486 @item GPGME_SIG_MODE_DETACH
2487 A detached signature is made.
2488
2489 @item GPGME_SIG_MODE_CLEAR
2490 A clear text signature is made.  The @acronym{ASCII} armor and text
2491 mode settings of the context are ignored.
2492 @end table
2493 @end deftp
2494
2495 @deftypefun GpgmeError gpgme_op_sign (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{sig}}, @w{GpgmeSigMode @var{mode}})
2496 The function @code{gpgme_op_sign} creates a signature for the text in
2497 the data object @var{plain} and returns it in the data object
2498 @var{sig}.  The type of the signature created is determined by the
2499 @acronym{ASCII} armor and text mode attributes set for the context
2500 @var{ctx} and the requested signature mode @var{mode}.
2501
2502 More information about the signatures is available with
2503 @code{gpgme_get_op_info}.  @xref{Detailed Results}.
2504
2505 If an S/MIME signed message is created using the CMS crypto engine,
2506 the number of certificates to include in the message can be specified
2507 with @code{gpgme_set_include_certs}.  @xref{Included Certificates}.
2508
2509 The function returns @code{GPGME_No_Error} if the signature could be
2510 created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2511 @var{plain} or @var{sig} is not a valid pointer, @code{GPGME_No_Data}
2512 if the signature could not be created, @code{GPGME_No_Passphrase} if
2513 the passphrase for the secret key could not be retrieved, and passes
2514 through any errors that are reported by the crypto engine support
2515 routines.
2516 @end deftypefun
2517
2518 @deftypefun GpgmeError gpgme_op_sign_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{sig}}, @w{GpgmeSigMode @var{mode}})
2519 The function @code{gpgme_op_sign_start} initiates a
2520 @code{gpgme_op_sign} operation.  It can be completed by calling
2521 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
2522
2523 The function returns @code{GPGME_No_Error} if the operation could be
2524 started successfully, and @code{GPGME_Invalid_Value} if @var{ctx},
2525 @var{plain} or @var{sig} is not a valid pointer.
2526 @end deftypefun
2527
2528
2529 @node Encrypt
2530 @subsection Encrypt
2531 @cindex encryption
2532 @cindex cryptographic operation, encryption
2533
2534 One plaintext can be encrypted for several recipients at the same
2535 time.  The list of recipients is created independently of any context,
2536 and then passed to the encryption operation.
2537
2538 @menu
2539 * Selecting Recipients::          How to choose the recipients.
2540 * Encrypting a Plaintext::        How to encrypt a plaintext.
2541 @end menu
2542
2543
2544 @node Selecting Recipients
2545 @subsubsection Selecting Recipients
2546 @cindex encryption, selecting recipients
2547 @cindex recipients
2548
2549 @deftp {Data type} GpgmeRecipients
2550 The @code{GpgmeRecipients} type is a handle for a set of recipients
2551 that can be used in an encryption process.
2552 @end deftp
2553
2554 @deftypefun GpgmeError gpgme_recipients_new (@w{GpgmeRecipients *@var{r_rset}})
2555 The function @code{gpgme_recipients_new} creates a new, empty set of
2556 recipients and returns a handle for it in @var{r_rset}.
2557
2558 The function returns @code{GPGME_No_Error} if the recipient set could
2559 be created successfully, and @code{GPGME_Out_Of_Core} if not enough
2560 memory was available.
2561 @end deftypefun
2562
2563 @deftypefun void gpgme_recipients_release (@w{GpgmeRecipients @var{rset}})
2564 The function @code{gpgme_recipients_release} destroys the set of
2565 recipients @var{rset} and releases all associated resources.
2566 @end deftypefun
2567
2568 @deftypefun GpgmeError gpgme_recipients_add_name (@w{GpgmeRecipients @var{rset}}, @w{const char *@var{name}})
2569 The function @code{gpgme_recipients_add_name} adds the recipient
2570 @var{name} to the set of recipients @var{rset}.  This is equivalent to
2571 @code{gpgme_recipients_add_name_with_validity} with a validity of
2572 @code{GPGME_VALIDITY_UNKNOWN}.
2573
2574 The function returns @code{GPGME_No_Error} if the recipient was added
2575 successfully, @code{GPGME_Invalid_Value} if @var{rset} or @var{name}
2576 is not a valid pointer, and @code{GPGME_Out_Of_Core} if not enough
2577 memory is available.
2578 @end deftypefun
2579
2580 @deftypefun GpgmeError gpgme_recipients_add_name_with_validity (@w{GpgmeRecipients @var{rset}}, @w{const char *@var{name}}, @w{GpgmeValidity @var{val}})
2581 The function @code{gpgme_recipients_add_name_with_validity} adds the
2582 recipient @var{name} with the validity @var{val} to the set of
2583 recipients @var{rset}.  If the validity is not known, the function
2584 @code{gpgme_recipients_add_name} can be used.
2585 @xref{Information About Keys}, for the possible values for @var{val}.
2586
2587 The function returns @code{GPGME_No_Error} if the recipient was added
2588 successfully, @code{GPGME_Invalid_Value} if @var{rset} or @var{name}
2589 is not a valid pointer, and @code{GPGME_Out_Of_Core} if not enough
2590 memory is available.
2591 @end deftypefun
2592
2593 @deftypefun {unsigned int} gpgme_recipients_count (@w{const @var{GpgmeRecipients rset}})
2594 The function @code{gpgme_recipients_count} returns the number of
2595 recipients in the set @var{rset}.
2596 @end deftypefun
2597
2598 @deftypefun GpgmeError gpgme_recipients_enum_open (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}})
2599 The function @code{gpgme_recipients_enum_open} creates a new iterator
2600 @var{iter} that can be used to walk through the set of recipients in
2601 @var{rset}, using @code{gpgme_recipients_enum_read}.
2602
2603 If the iterator is not needed anymore, it can be closed with
2604 @code{gpgme_recipients_enum_close}.
2605
2606 The function returns @code{GPGME_No_Error} if the enumerator was
2607 successfully created and @code{GPGME_Invalid_Value} if @var{rset} or
2608 @var{iter} is not a valid pointer.
2609 @end deftypefun
2610
2611 @deftypefun {const char *} gpgme_recipients_enum_read (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}})
2612 The function @code{gpgme_recipients_enum_read} returns a string
2613 containing the name of the next recipient in the set @var{rset} for
2614 the iterator @var{iter}.  The string is valid as long as @var{rset} is
2615 valid or the function is called the next time with the same recipient
2616 set and iterator, whatever is earlier.
2617 @end deftypefun
2618
2619 @deftypefun GpgmeError gpgme_recipients_enum_close (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}})
2620 The function @code{gpgme_recipients_enum_close} releases the iterator
2621 @var{iter} for the recipient set @var{rset}.
2622 @end deftypefun
2623
2624
2625 @node Encrypting a Plaintext
2626 @subsubsection Encrypting a Plaintext
2627
2628 @deftypefun GpgmeError gpgme_op_encrypt (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
2629 The function @code{gpgme_op_encrypt} encrypts the plaintext in the data
2630 object @var{plain} for the recipients @var{rset} and stores the
2631 ciphertext in the data object @var{cipher}.  The type of the
2632 ciphertext created is determined by the @acronym{ASCII} armor and text
2633 mode attributes set for the context @var{ctx}.
2634
2635 If @code{GPGME_Invalid_Recipients} is returned, some recipients in
2636 @var{rset} are invalid, but not all.  In this case the plaintext is
2637 encrypted for all valid recipients and returned in @var{cipher}.  More
2638 information about the invalid recipients is available with
2639 @code{gpgme_get_op_info}.  @xref{Detailed Results}.
2640
2641 If @var{recp} is @code{NULL}, symmetric rather than public key
2642 encryption is performed.  Symmetrically encrypted cipher text can be
2643 deciphered with @code{gpgme_op_decrypt}.  Note that in this case the
2644 crypto backend needs to retrieve a passphrase from the user.
2645 Symmetric encryption is currently only supported for the OpenPGP
2646 crypto backend.
2647
2648 The function returns @code{GPGME_No_Error} if the ciphertext could be
2649 created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2650 @var{rset}, @var{plain} or @var{cipher} is not a valid pointer,
2651 @code{GPGME_No_Recipients} if @var{rset} does not contain any valid
2652 recipients, @code{GPGME_Invalid_Recipients} if @var{rset} contains
2653 some invalid recipients, @code{GPGME_No_Passphrase} if the passphrase
2654 for the secret key could not be retrieved, and passes through any
2655 errors that are reported by the crypto engine support routines.
2656 @end deftypefun
2657
2658 @deftypefun GpgmeError gpgme_op_encrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
2659 The function @code{gpgme_op_encrypt_start} initiates a
2660 @code{gpgme_op_encrypt} operation.  It can be completed by calling
2661 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
2662
2663 The function returns @code{GPGME_No_Error} if the operation could be
2664 started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2665 @var{rset}, @var{plain} or @var{cipher} is not a valid pointer, and
2666 @code{GPGME_No_Recipients} if @var{rset} does not contain any valid
2667 recipients.
2668 @end deftypefun
2669
2670
2671 @deftypefun GpgmeError gpgme_op_encrypt_sign (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
2672 The function @code{gpgme_op_encrypt_sign} does a combined encrypt and
2673 sign operation.  It is used like @code{gpgme_op_encrypt}, but the
2674 ciphertext also contains signatures for the signers listed in
2675 @var{ctx}.
2676
2677 The combined encrypt and sign operation is currently only available
2678 for the OpenPGP crypto engine.
2679 @end deftypefun
2680
2681 @deftypefun GpgmeError gpgme_op_encrypt_sign_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
2682 The function @code{gpgme_op_encrypt_sign_start} initiates a
2683 @code{gpgme_op_encrypt_sign} operation.  It can be completed by
2684 calling @code{gpgme_wait} on the context.  @xref{Waiting For
2685 Completion}.
2686
2687 The function returns @code{GPGME_No_Error} if the operation could be
2688 started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2689 @var{rset}, @var{plain} or @var{cipher} is not a valid pointer, and
2690 @code{GPGME_No_Recipients} if @var{rset} does not contain any valid
2691 recipients.
2692 @end deftypefun
2693
2694
2695 @node Detailed Results
2696 @subsection Detailed Results
2697 @cindex cryptographic operation, detailed results
2698
2699 @deftypefun {char *} gpgme_get_op_info (@w{GpgmeCtx @var{ctx}}, @w{int @var{reserved}})
2700 The function @code{gpgme_get_op_info} retrieves more information about
2701 the last crypto operation.
2702
2703 The function returns a string in the XML format.  The user has to
2704 release the string with @code{free}.
2705
2706 Here is a sample of the information that might be returned:
2707 @example
2708 <GnupgOperationInfo>
2709   <signature>
2710     <detached/> <!-- or cleartext or standard -->
2711     <algo>17</algo>
2712     <hashalgo>2</hashalgo>
2713     <micalg>pgp-sha1</micalg>
2714     <sigclass>01</sigclass>
2715     <created>9222222</created>
2716     <fpr>121212121212121212</fpr>
2717   </signature>
2718 </GnupgOperationInfo>
2719 @end example
2720
2721 Currently, the only operations that return additional information are
2722 encrypt, sign and import.  @xref{Encrypt}, @xref{Sign},
2723 @xref{Importing Keys}.
2724
2725 The function returns a string or @code{NULL} if no such data is
2726 available.
2727 @end deftypefun
2728
2729
2730 @node Run Control
2731 @section Run Control
2732 @cindex run control
2733 @cindex cryptographic operation, running
2734
2735 @acronym{GPGME} supports running operations synchronously and
2736 asynchronously.  You can use asynchronous operation to set up a
2737 context up to initiating the desired operation, but delay performing
2738 it to a later point.
2739
2740 Furthermore, you can use an external event loop to control exactly
2741 when @acronym{GPGME} runs.  This ensures that @acronym{GPGME} only
2742 runs when necessary and also prevents it from blocking for a long
2743 time.
2744
2745 @menu
2746 * Waiting For Completion::        Waiting until an operation is completed.
2747 * Cancelling an Operation::       Interrupting a running operation.
2748 * Hooking Up Into Idle Time::     Doing something when nothing has to be done.
2749 * Using External Event Loops::    Advanced control over what happens when.
2750 @end menu
2751
2752
2753 @node Waiting For Completion
2754 @subsection Waiting For Completion
2755 @cindex cryptographic operation, wait for
2756 @cindex wait for completion
2757
2758 @deftypefun GpgmeCtx gpgme_wait (@w{GpgmeCtx @var{ctx}}, @w{GpgmeError *@var{status}}, @w{int @var{hang}})
2759 The function @code{gpgme_wait} continues the pending operation within
2760 the context @var{ctx}.  In particular, it ensures the data exchange
2761 between @acronym{GPGME} and the crypto backend and watches over the
2762 run time status of the backend process.
2763
2764 If @var{hang} is true, the function does not return until the
2765 operation is completed or cancelled.  Otherwise the function will not
2766 block for a long time.
2767
2768 The error status of the finished operation is returned in @var{status}
2769 if @code{gpgme_wait} does not return @code{NULL}.
2770
2771 The @var{ctx} argument can be @code{NULL}.  In that case,
2772 @code{gpgme_wait} waits for any context to complete its operation.
2773
2774 @code{gpgme_wait} can be used only in conjunction with any context
2775 that has a pending operation initiated with one of the
2776 @code{gpgme_op_*_start} functions except @code{gpgme_op_keylist_start}
2777 and @code{gpgme_op_trustlist_start} (for which you should use the
2778 corresponding @code{gpgme_op_*_next} functions).  If @var{ctx} is
2779 @code{NULL}, all of such contexts are waited upon and possibly
2780 returned.  Synchronous operations running in parallel, as well as key
2781 and trust item list operations, do not affect @code{gpgme_wait}.
2782
2783 In a multi-threaded environment, only one thread should ever call
2784 @code{gpgme_wait} at any time, irregardless if @var{ctx} is specified
2785 or not.  This means that all calls to this function should be fully
2786 synchronized by locking primitives.
2787
2788 The function returns the @var{ctx} of the context which has finished
2789 the operation.
2790 @end deftypefun
2791
2792
2793 @node Cancelling an Operation
2794 @subsection Cancelling an Operation
2795 @cindex cancellation
2796 @cindex cryptographic operation, cancel
2797
2798 @deftypefun void gpgme_cancel (@w{GpgmeCtx @var{ctx}})
2799 The function @code{gpgme_cancel} tries to cancel the pending
2800 operation.  A running synchronous operation in the context or the
2801 function @code{gpgme_wait} with this context as its @var{ctx} argument
2802 might notice the cancellation flag and return.  It is currently not
2803 guaranteed to work under all circumstances.  Its current primary
2804 purpose is to prevent asking for a passphrase again in the passphrase
2805 callback.
2806 @end deftypefun
2807
2808
2809 @node Hooking Up Into Idle Time
2810 @subsection Hooking Up Into Idle Time
2811 @cindex idle time
2812 @cindex idle function
2813
2814 @deftp {Data type} {void (*GpgmeIdleFunc) (void)}
2815 @tindex GpgmeIdleFunc
2816 The @code{GpgmeIdleFunc} type is the type of functions usable as
2817 an idle function that can be registered with @code{gpgme_register_idle}.
2818 @end deftp
2819
2820 @deftypefun GpgmeIdleFunc gpgme_register_idle (@w{GpgmeIdleFunc @var{idle}})
2821 The function @code{gpgme_register_idle} can be used to register
2822 @var{idle} as the idle function.
2823
2824 @var{idle} will be called whenever @acronym{GPGME} thinks that it is
2825 idle and time can better be spent elsewhere.  Setting @var{idle} to
2826 @code{NULL} disables use of the idle function (this is the default).
2827
2828 The function returns the old idle function, or @code{NULL} if none was
2829 registered yet.
2830 @end deftypefun
2831
2832
2833 @node Using External Event Loops
2834 @subsection Using External Event Loops
2835 @cindex event loop, external
2836
2837 @acronym{GPGME} hides the complexity of the communication between the
2838 library and the crypto engine.  The price of this convenience is that
2839 the calling thread can block arbitrary long waiting for the data
2840 returned by the crypto engine.  In single-threaded programs, in
2841 particular if they are interactive, this is an unwanted side-effect.
2842 OTOH, if @code{gpgme_wait} is used without the @var{hang} option being
2843 enabled, it might be called unnecessarily often, wasting CPU time that
2844 could be used otherwise.
2845
2846 The I/O callback interface described in this section lets the user
2847 take control over what happens when.  @acronym{GPGME} will provide the
2848 user with the file descriptors that should be monitored, and the
2849 callback functions that should be invoked when a file descriptor is
2850 ready for reading or writing.  It is then the user's responsibility to
2851 decide when to check the file descriptors and when to invoke the
2852 callback functions.  Usually this is done in an event loop, that also
2853 checks for events in other parts of the program.  If the callback
2854 functions are only called when the file descriptors are ready,
2855 @acronym{GPGME} will never block.  This gives the user mroe control
2856 over the program flow, and allows to perform other tasks when
2857 @acronym{GPGME} would block otherwise.
2858
2859 By using this advanced mechanism, @acronym{GPGME} can be integrated
2860 smoothly into GUI toolkits like GTK+ even for single-threaded
2861 programs.
2862
2863 @menu
2864 * I/O Callback Interface::        How I/O callbacks are registered.
2865 * Registering I/O Callbacks::     How to use I/O callbacks for a context.
2866 * I/O Callback Example::          An example how to use I/O callbacks.
2867 * I/O Callback Example GTK+::     How to use @acronym{GPGME} with GTK+.
2868 * I/O Callback Example GDK::      How to use @acronym{GPGME} with GDK.
2869 @end menu
2870
2871
2872 @node I/O Callback Interface
2873 @subsubsection I/O Callback Interface
2874
2875 @deftp {Data type} {void (*GpgmeIOCb) (@w{void *@var{data}}, @w{int @var{fd}})}
2876 @tindex GpgmeIOCb
2877 The @code{GpgmeIOCb} type is the type of functions which
2878 @acronym{GPGME} wants to register as I/O callback handlers using the
2879 @code{GpgmeRegisterIOCb} functions provided by the user.
2880
2881 @var{data} and @var{fd} are provided by @acronym{GPGME} when the I/O
2882 callback handler is registered, and should be passed through to the
2883 handler when it is invoked by the user because it noticed activity on
2884 the file descriptor @var{fd}.
2885 @end deftp
2886
2887 @deftp {Data type} {GpgmeError (*GpgmeRegisterIOCb) (@w{void *@var{data}}, @w{int @var{fd}}, @w{int @var{dir}}, @w{GpgmeIOCb @var{fnc}}, @w{void *@var{fnc_data}}, @w{void **@var{tag}})}
2888 @tindex GpgmeRegisterIOCb
2889 The @code{GpgmeRegisterIOCb} type is the type of functions which can
2890 be called by @acronym{GPGME} to register an I/O callback funtion
2891 @var{fnc} for the file descriptor @var{fd} with the user.
2892 @var{fnc_data} should be passed as the first argument to @var{fnc}
2893 when the handler is invoked (the second argument should be @var{fd}).
2894 If @var{dir} is 0, @var{fnc} should be called by the user when
2895 @var{fd} is ready for writing.  If @var{dir} is 1, @var{fnc} should be
2896 called when @var{fd} is ready for reading.
2897
2898 @var{data} was provided by the user when registering the
2899 @code{GpgmeRegisterIOCb} function with @acronym{GPGME} and will always
2900 be passed as the first argument when registering a callback function.
2901 For example, the user can use this to determine the event loop to
2902 which the file descriptor should be added.
2903
2904 @acronym{GPGME} will call this function when a crypto operation is
2905 initiated in a context for which the user has registered I/O callback
2906 handler functions with @code{gpgme_set_io_cbs}.  It can also call this
2907 function when it is in an I/O callback handler for a file descriptor
2908 associated to this context.
2909
2910 The user should return a unique handle in @var{tag} identifying this
2911 I/O callback registration, which will be passed to the
2912 @code{GpgmeRegisterIOCb} function without interpretation when the file
2913 descriptor should not be monitored anymore.
2914 @end deftp
2915
2916 @deftp {Data type} {void (*GpgmeRemoveIOCb) (@w{void *@var{tag}})}
2917 The @code{GpgmeRemoveIOCb} type is the type of functions which can be
2918 called by @acronym{GPGME} to remove an I/O callback handler that was
2919 registered before.  @var{tag} is the handle that was returned by the
2920 @code{GpgmeRegisterIOCb} for this I/O callback.
2921
2922 @acronym{GPGME} can call this function when a crypto operation is in
2923 an I/O callback.  It will also call this function when the context is
2924 destroyed while an operation is pending.
2925 @end deftp
2926
2927 @deftp {Data type} {enum GpgmeEventIO}
2928 @tindex GpgmeEventIO
2929 The @code{GpgmeEventIO} type specifies the type of an event that is
2930 reported to the user by @acronym{GPGME} as a consequence of an I/O
2931 operation.  The following events are defined:
2932
2933 @table @code
2934 @item GPGME_EVENT_DONE
2935 The operation is finished, the last I/O callback for this operation
2936 was removed.  The accompanying @var{type_data} points to a
2937 @code{GpgmeError} variable that contains the status of the operation
2938 that finished.  This event is signalled after the last I/O callback
2939 has been removed.
2940
2941 @item GPGME_EVENT_NEXT_KEY
2942 In a @code{gpgme_op_keylist_start} operation, the next key was
2943 received from the crypto engine.  The accompanying @var{type_data} is
2944 a @code{GpgmeKey} variable that contains the key with one reference
2945 for the user.
2946
2947 @item GPGME_EVENT_NEXT_TRUSTITEM
2948 In a @code{gpgme_op_trustlist_start} operation, the next trust item
2949 was received from the crypto engine.  The accompanying @var{type_data}
2950 is a @code{GpgmeTrustItem} variable that contains the trust item with
2951 one reference for the user.
2952 @end table
2953 @end deftp
2954
2955 @deftp {Data type} {void (*GpgmeEventIOCb) (@w{void *@var{data}}, @w{GpgmeEventIO @var{type}}, @w{void *@var{type_data}})}
2956 The @code{GpgmeEventIOCb} type is the type of functions which can be
2957 called by @acronym{GPGME} to signal an event for an operation running
2958 in a context which has I/O callback functions registered by the user.
2959
2960 @var{data} was provided by the user when registering the
2961 @code{GpgmeEventIOCb} function with @acronym{GPGME} and will always be
2962 passed as the first argument when registering a callback function.
2963 For example, the user can use this to determine the context in which
2964 this event has occured.
2965
2966 @var{type} will specify the type of event that has occured.
2967 @var{type_data} specifies the event further, as described in the above
2968 list of possible @code{GpgmeEventIO} types.
2969
2970 @acronym{GPGME} can call this function in an I/O callback handler.
2971 @end deftp
2972
2973
2974 @node Registering I/O Callbacks
2975 @subsubsection Registering I/O Callbacks
2976
2977 @deftp {Data type} {struct GpgmeIOCbs}
2978 @tindex GpgmeEventIO
2979 This structure is used to store the I/O callback interface functions
2980 described in the previous section.  It has the following members:
2981
2982 @table @code
2983 @item GpgmeRegisterIOCb add
2984 This is the function called by @acronym{GPGME} to register an I/O
2985 callback handler.  It must be specified.
2986
2987 @item void *add_data
2988 This is passed as the first argument to the @code{add} function when
2989 it is called by @acronym{GPGME}.  For example, it can be used to
2990 determine the event loop to which the file descriptor should be added.
2991
2992 @item GpgmeRemoveIOCb remove
2993 This is the function called by @acronym{GPGME} to remove an I/O
2994 callback handler.  It must be specified.
2995
2996 @item GpgmeEventIOCb event
2997 This is the function called by @acronym{GPGME} to signal an event for
2998 an operation.  It is optional, but if you don't specify it, you can
2999 not retrieve the return value of the operation.
3000
3001 @item void *event_data
3002 This is passed as the first argument to the @code{event} function when
3003 it is called by @acronym{GPGME}.  For example, it can be used to
3004 determine the context in which the event has occured.
3005 @end table
3006 @end deftp
3007
3008 @deftypefun void gpgme_set_io_cbs (@w{GpgmeCtx @var{ctx}}, @w{struct GpgmeIOCbs *@var{io_cbs}})
3009 The function @code{gpgme_set_io_cbs} enables the I/O callback
3010 interface for the context @var{ctx}.  The I/O callback functions are
3011 specified by @var{io_cbs}.
3012
3013 If @var{io_cbs}->@code{add} is @code{NULL}, the I/O callback interface
3014 is disabled for the context, and normal operation is restored.
3015 @end deftypefun
3016
3017 @deftypefun void gpgme_get_io_cbs (@w{GpgmeCtx @var{ctx}}, @w{struct GpgmeIOCbs *@var{io_cbs}})
3018 The function @code{gpgme_get_io_cbs} returns the I/O callback
3019 functions set with @code{gpgme_set_io_cbs} in @var{io_cbs}.
3020 @end deftypefun
3021
3022
3023 @node I/O Callback Example
3024 @subsubsection I/O Callback Example
3025
3026 To actually use an external event loop, you have to implement the I/O
3027 callback functions that are used by @acronym{GPGME} to register and
3028 unregister file descriptors.  Furthermore, you have to actually
3029 monitor these file descriptors for activity and call the appropriate
3030 I/O callbacks.
3031
3032 The following example illustrates how to do that.  The example uses
3033 locking to show in which way the the callbacks and the event loop can
3034 run concurrently.  For the event loop, we use a fixed array.  For a
3035 real-world implementation, you should use a dynamically sized
3036 structure because the number of file descriptors needed for a crypto
3037 operation in @acronym{GPGME} is not predictable.
3038
3039 @example
3040 #include <pthread.h>
3041 #include <sys/types.h>
3042 #include <gpgme.h>
3043
3044 /* The following structure holds the result of a crypto operation.  */
3045 struct op_result
3046 @{
3047   int done;
3048   GpgmeError err;
3049 @};
3050
3051 /* The following structure holds the data associated with one I/O
3052 callback.  */
3053 struct one_fd
3054 @{
3055   int fd;
3056   int dir;
3057   GpgmeIOCb fnc;
3058   void *fnc_data;
3059 @};
3060
3061 struct event_loop
3062 @{
3063   pthread_mutex_t lock;
3064 #define MAX_FDS 32
3065   /* Unused slots are marked with FD being -1.  */
3066   struct one_fd fds[MAX_FDS];
3067 @};
3068 @end example
3069
3070 The following functions implement the I/O callback interface.
3071
3072 @example
3073 GpgmeError
3074 add_io_cb (void *data, int fd, int dir, GpgmeIOCb fnc, void *fnc_data,
3075            void **r_tag)
3076 @{
3077   struct event_loop *loop = data;
3078   struct one_fd *fds = loop->fds;
3079   int i;
3080
3081   pthread_mutex_lock (&loop->lock);
3082   for (i = 0; i < MAX_FDS; i++)
3083     @{
3084       if (fds[i].fd == -1)
3085         @{
3086           fds[i].fd = fd;
3087           fds[i].dir = dir;
3088           fds[i].fnc = fnc;
3089           fds[i].fnc_data = fnc_data;
3090           break;
3091         @}
3092     @}
3093   pthread_mutex_unlock (&loop->lock);
3094   if (i == MAX_FDS)
3095     return GPGME_General_Error;
3096   *r_tag = &fds[i];
3097   return 0;
3098 @}
3099
3100 void
3101 remove_io_cb (void *tag)
3102 @{
3103   struct one_fd *fd = tag;
3104
3105   pthread_mutex_lock (&loop->lock);
3106   fd->fd = -1;
3107   pthread_mutex_unlock (&loop->lock);
3108 @}
3109
3110 void
3111 event_io_cb (void *data, GpgmeEventIO type, void *type_data)
3112 @{
3113   struct op_result *result = data;
3114   GpgmeError *err = data;
3115
3116   /* We don't support list operations here.  */
3117   if (type == GPGME_EVENT_DONE)
3118     @{
3119       result->done = 1;
3120       result->err = *data;
3121     @}
3122 @}
3123 @end example
3124
3125 The final missing piece is the event loop, which will be presented
3126 next.  We only support waiting for the success of a single operation.
3127
3128 @example
3129 int
3130 do_select (struct event_loop *loop)
3131 @{
3132   fd_set rfds;
3133   fd_set wfds;
3134   int i, n;
3135   int any = 0;
3136
3137   pthread_mutex_lock (&loop->lock);
3138   FD_ZERO (&rfds);
3139   FD_ZERO (&wfds);
3140   for (i = 0; i < FDLIST_MAX; i++)
3141     if (fdlist[i].fd != -1)
3142       FD_SET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds);
3143   pthread_mutex_unlock (&loop->unlock);
3144
3145   do
3146     @{
3147       n = select (FD_SETSIZE, &rfds, &wfds, NULL, 0);
3148     @}
3149   while (n < 0 && errno == EINTR);
3150
3151   if (n < 0)
3152     return n;   /* Error or timeout.  */
3153
3154   pthread_mutex_lock (&loop->lock);
3155   for (i = 0; i < FDLIST_MAX && n; i++)
3156     @{
3157       if (fdlist[i].fd != -1)
3158         @{
3159           if (FD_ISSET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds))
3160             @{
3161               assert (n);
3162               n--;
3163               any = 1;
3164               /* The I/O callback handler can register/remove callbacks,
3165                  so we have to unlock the file descriptor list.  */
3166               pthread_mutex_unlock (&loop->lock);
3167               (*fdlist[i].fnc) (fdlist[i].fnc_data, fdlist[i].fd);
3168               pthread_mutex_lock (&loop->lock);
3169             @}
3170         @}
3171     @}
3172   pthread_mutex_unlock (&loop->lock);
3173   return any;
3174 @}
3175
3176 void
3177 wait_for_op (struct event_loop *loop, struct op_result *result)
3178 @{
3179   int ret;
3180
3181   do
3182     @{
3183       ret = do_select (loop);
3184     @}
3185   while (ret >= 0 && !result->done);
3186   return ret;
3187 @}
3188 @end example
3189
3190 The main function shows how to put it all together.
3191
3192 @example
3193 int
3194 main (int argc, char *argv[])
3195 @{
3196   struct event_loop loop;
3197   struct op_result result;
3198   GpgmeCtx ctx;
3199   GpgmeError err;
3200   GpgmeData sig, text;
3201   GpgmeSigStat status;
3202   int i;
3203   struct GpgmeIOCbs io_cbs =
3204   @{
3205     add_io_cb,
3206     &loop,
3207     remove_io_cb,
3208     event_io_cb,
3209     &result
3210   @};
3211
3212   /* Initialize the loop structure.  */
3213   loop.lock = PTHREAD_MUTEX_INITIALIZER;
3214   for (i = 0; i < MAX_FDS; i++)
3215     loop->fds[i].fd = -1;
3216
3217   /* Initialize the result structure.  */
3218   result.done = 0;
3219
3220   err = gpgme_data_new_from_file (&sig, "signature", 1);
3221   if (!err)
3222     err = gpgme_data_new_from_file (&text, "text", 1);
3223   if (!err)
3224     err = gpgme_new (&ctx);
3225   if (!err)
3226     @{
3227        gpgme_set_io_cbs (ctx, &io_cbs);
3228        err = gpgme_op_verify_start (ctx, sig, text, &status);
3229     @}
3230   if (err)
3231     @{
3232       fprintf (stderr, "gpgme error: %s\n", gpgme_strerror (err));
3233       exit (1);
3234     @}
3235
3236   wait_for_op (&loop, &result);
3237   if (!result.done)
3238     @{
3239       fprintf (stderr, "select error\n");
3240       exit (1);
3241     @}
3242   if (!result.err)
3243     @{
3244       fprintf (stderr, "verification failed: %s\n", gpgme_strerror (result.err));
3245       exit (1);
3246     @}
3247   /* Evaluate STATUS.  */
3248   @dots{}
3249   return 0;
3250 @}
3251 @end example
3252
3253
3254 @node I/O Callback Example GTK+
3255 @subsubsection I/O Callback Example GTK+
3256 @cindex GTK+, using @acronym{GPGME} with
3257
3258 The I/O callback interface can be used to integrate @acronym{GPGME}
3259 with the GTK+ event loop.  The following code snippets shows how this
3260 can be done using the appropriate register and remove I/O callback
3261 functions.  In this example, the private data of the register I/O
3262 callback function is unused.  The event notifications is missing
3263 because it does not require any GTK+ specific setup.
3264
3265 @example
3266 #include <gtk/gtk.h>
3267
3268 struct my_gpgme_io_cb
3269 @{
3270   GpgmeIOCb fnc;
3271   void *fnc_data;
3272   guint input_handler_id
3273 @};
3274
3275 void
3276 my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition)
3277 @{
3278   struct my_gpgme_io_cb *iocb = data;
3279   (*(iocb->fnc)) (iocb->data, source);
3280 @}
3281
3282 void
3283 my_gpgme_remove_io_cb (void *data)
3284 @{
3285   struct my_gpgme_io_cb *iocb = data;
3286   gtk_input_remove (data->input_handler_id);
3287 @}
3288
3289 void
3290 my_gpgme_register_io_callback (void *data, int fd, int dir, GpgmeIOCb fnc,
3291                                void *fnc_data, void **tag)
3292 @{
3293   struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb));
3294   iocb->fnc = fnc;
3295   iocb->data = fnc_data;
3296   iocb->input_handler_id = gtk_input_add_full (fd, dir
3297                                                    ? GDK_INPUT_READ
3298                                                    : GDK_INPUT_WRITE,
3299                                                my_gpgme_io_callback,
3300                                                0, iocb, NULL);
3301   *tag = iocb;
3302   return 0;
3303 @}
3304 @end example
3305
3306
3307 @node I/O Callback Example GDK
3308 @subsubsection I/O Callback Example GDK
3309 @cindex GDK, using @acronym{GPGME} with
3310
3311 The I/O callback interface can also be used to integrate
3312 @acronym{GPGME} with the GDK event loop.  The following code snippets
3313 shows how this can be done using the appropriate register and remove
3314 I/O callback functions.  In this example, the private data of the
3315 register I/O callback function is unused.  The event notifications is
3316 missing because it does not require any GDK specific setup.
3317
3318 It is very similar to the GTK+ example in the previous section.
3319
3320 @example
3321 #include <gdk/gdk.h>
3322
3323 struct my_gpgme_io_cb
3324 @{
3325   GpgmeIOCb fnc;
3326   void *fnc_data;
3327   gint tag;
3328 @};
3329
3330 void
3331 my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition)
3332 @{
3333   struct my_gpgme_io_cb *iocb = data;
3334   (*(iocb->fnc)) (iocb->data, source);
3335 @}
3336
3337 void
3338 my_gpgme_remove_io_cb (void *data)
3339 @{
3340   struct my_gpgme_io_cb *iocb = data;
3341   gdk_input_remove (data->tag);
3342 @}
3343
3344 void
3345 my_gpgme_register_io_callback (void *data, int fd, int dir, GpgmeIOCb fnc,
3346                                void *fnc_data, void **tag)
3347 @{
3348   struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb));
3349   iocb->fnc = fnc;
3350   iocb->data = fnc_data;
3351   iocb->tag = gtk_input_add_full (fd, dir ? GDK_INPUT_READ : GDK_INPUT_WRITE,
3352                                   my_gpgme_io_callback, iocb, NULL);
3353   *tag = iocb;
3354   return 0;
3355 @}
3356 @end example
3357
3358
3359 @include gpl.texi
3360
3361
3362 @include fdl.texi
3363
3364
3365 @node Concept Index
3366 @unnumbered Concept Index
3367
3368 @printindex cp
3369
3370
3371 @node Function and Data Index
3372 @unnumbered Function and Data Index
3373
3374 @printindex fn
3375
3376
3377 @summarycontents
3378 @contents
3379 @bye