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