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