2002-08-30 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}})
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 The function returns @code{GPGME_No_Error} if the operation could be
1860 started successfully, @code{GPGME_Invalid_Value} if @var{parms} is not
1861 a valid XML string, @code{GPGME_Not_Supported} if @var{pubkey} or
1862 @var{seckey} is not valid, and @code{GPGME_General_Error} if no key
1863 was created by the backend.
1864 @end deftypefun
1865
1866 @deftypefun GpgmeError gpgme_op_genkey_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{pubkey}}, @w{GpgmeData @var{seckey}})
1867 The function @code{gpgme_op_genkey_start} initiates a
1868 @code{gpgme_op_genkey} operation.  It can be completed by calling
1869 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
1870
1871 The function returns @code{GPGME_No_Error} if the operation could be
1872 started successfully, @code{GPGME_Invalid_Value} if @var{parms} is not
1873 a valid XML string, and @code{GPGME_Not_Supported} if @var{pubkey} or
1874 @var{seckey} is not @code{NULL}.
1875 @end deftypefun
1876
1877
1878 @node Exporting Keys
1879 @subsection Exporting Keys
1880 @cindex key, export
1881 @cindex key ring, export from
1882
1883 @deftypefun GpgmeError gpgme_op_export (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{recipients}}, @w{GpgmeData @var{keydata}})
1884 The function @code{gpgme_op_export} extracts the public keys of the
1885 user IDs in @var{recipients} and returns them in the data buffer
1886 @var{keydata}.  The type of the public keys returned is determined by
1887 the @acronym{ASCII} armor attribute set for the context @var{ctx}.
1888
1889 The function returns @code{GPGME_No_Error} if the operation completed
1890 successfully, @code{GPGME_Invalid_Value} if @var{recipients} is
1891 @code{NULL} or @var{keydata} is not a valid empty data buffer, and
1892 passes through any errors that are reported by the crypto engine
1893 support routines.
1894 @end deftypefun
1895
1896 @deftypefun GpgmeError gpgme_op_export_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{recipients}}, @w{GpgmeData @var{keydata}})
1897 The function @code{gpgme_op_export_start} initiates a
1898 @code{gpgme_op_export} operation.  It can be completed by calling
1899 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
1900
1901 The function returns @code{GPGME_No_Error} if the operation could be
1902 started successfully, and @code{GPGME_Invalid_Value} if
1903 @var{recipients} is @code{NULL} or @var{keydata} is not a valid empty
1904 data buffer.
1905 @end deftypefun
1906
1907
1908 @node Importing Keys
1909 @subsection Importing Keys
1910 @cindex key, import
1911 @cindex key ring, import to
1912
1913 @deftypefun GpgmeError gpgme_op_import (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}})
1914 The function @code{gpgme_op_import} adds the keys in the data buffer
1915 @var{keydata} to the key ring of the crypto engine used by @var{ctx}.
1916 The format of @var{keydata} can be @var{ASCII} armored, for example,
1917 but the details are specific to the crypto engine.
1918
1919 More information about the import is available with
1920 @code{gpgme_get_op_info}.  @xref{Detailed Results}.
1921
1922 The function returns @code{GPGME_No_Error} if the import was completed
1923 successfully, @code{GPGME_Invalid_Value} if @var{keydata} if @var{ctx}
1924 or @var{keydata} is not a valid pointer, and @code{GPGME_No_Data} if
1925 @var{keydata} is an empty data buffer.
1926 @end deftypefun
1927
1928 @deftypefun GpgmeError gpgme_op_import_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}})
1929 The function @code{gpgme_op_import_start} initiates a
1930 @code{gpgme_op_import} operation.  It can be completed by calling
1931 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
1932
1933 The function returns @code{GPGME_No_Error} if the import could be
1934 started successfully, @code{GPGME_Invalid_Value} if @var{keydata} if
1935 @var{ctx} or @var{keydata} is not a valid pointer, and
1936 @code{GPGME_No_Data} if @var{keydata} is an empty data buffer.
1937 @end deftypefun
1938
1939 @deftypefun GpgmeError gpgme_op_import_ext (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}}, @w{int *@var{nr}})
1940 The function @code{gpgme_op_import_ext} is like
1941 @code{gpgme_op_import}, but also returns the number of processed keys
1942 in @var{nr}.  This is the same as the @code{count} information in the
1943 detailed results available with @code{gpgme_get_op_info}.
1944 @end deftypefun
1945
1946
1947 @node Deleting Keys
1948 @subsection Deleting Keys
1949 @cindex key, delete
1950 @cindex key ring, delete from
1951
1952 @deftypefun GpgmeError gpgme_op_delete (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}, @w{int @var{allow_secret}})
1953 The function @code{gpgme_op_delete} deletes the key @var{key} from the
1954 key ring of the crypto engine used by @var{ctx}.  If
1955 @var{allow_secret} is @code{0}, only public keys are deleted,
1956 otherwise secret keys are deleted as well, if that is supported.
1957
1958 The function returns @code{GPGME_No_Error} if the key was deleted
1959 successfully, @code{GPGME_Invalid_Value} if @var{ctx} or @var{key} is
1960 not a valid pointer, @code{GPGME_Invalid_Key} if @var{key} could not
1961 be found in the keyring, and @code{GPGME_Conflict} if the secret key
1962 for @var{key} is available, but @var{allow_secret} is zero.
1963 @end deftypefun
1964
1965 @deftypefun GpgmeError gpgme_op_delete_start (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}, @w{int @var{allow_secret}})
1966 The function @code{gpgme_op_delete_start} initiates a
1967 @code{gpgme_op_delete} operation.  It can be completed by calling
1968 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
1969
1970 The function returns @code{GPGME_No_Error} if the operation was
1971 started successfully, and @code{GPGME_Invalid_Value} if @var{ctx} or
1972 @var{key} is not a valid pointer.
1973 @end deftypefun
1974
1975
1976 @node Trust Item Management
1977 @section Trust Item Management
1978 @cindex trust item
1979
1980 @strong{Caution:} The trust items interface is experimental.
1981
1982 @deftp {Data type} GpgmeTrustItem
1983 The @code{GpgmeTrustItem} type is a handle for a trust item.
1984 @end deftp
1985
1986 @menu
1987 * Listing Trust Items::           Browsing the list of available trust items.
1988 * Information About Trust Items:: Requesting detailed information about trust items.
1989 * Manipulating Trust Items::      Operations on trust items.
1990 @end menu
1991
1992
1993 @node Listing Trust Items
1994 @subsection Listing Trust Items
1995 @cindex trust item list
1996
1997 @deftypefun GpgmeError gpgme_op_trustlist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{max_level}})
1998 The function @code{gpgme_op_trustlist_start} initiates a trust item
1999 listing operation inside the context @var{ctx}.  It sets everything up
2000 so that subsequent invocations of @code{gpgme_op_trustlist_next} return
2001 the trust items in the list.
2002
2003 The string @var{pattern} contains an engine specific expression that
2004 is used to limit the list to all trust items matching the pattern.  It
2005 can not be the empty string.
2006
2007 The argument @var{max_level} is currently ignored.
2008
2009 The context will be busy until either all trust items are received
2010 (and @code{gpgme_op_trustlist_next} returns @code{GPGME_EOF}), or
2011 @code{gpgme_op_trustlist_end} is called to finish the operation.
2012
2013 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
2014 valid pointer, and passes through any errors that are reported by the
2015 crypto engine support routines.
2016 @end deftypefun
2017
2018 @deftypefun GpgmeError gpgme_op_trustlist_next (@w{GpgmeCtx @var{ctx}}, @w{GpgmeTrustItem *@var{r_item}})
2019 The function @code{gpgme_op_trustlist_next} returns the next trust
2020 item in the list created by a previous @code{gpgme_op_trustlist_start}
2021 operation in the context @var{ctx}.  The trust item can be destroyed
2022 with @code{gpgme_trust_item_release}.  @xref{Manipulating Trust Items}.
2023
2024 This is the only way to get at @code{GpgmeTrustItem} objects in
2025 @acronym{GPGME}.
2026
2027 If the last trust item in the list has already been returned,
2028 @code{gpgme_op_trustlist_next} returns @code{GPGME_EOF}.
2029
2030 The function returns @code{GPGME_Invalid_Value} if @var{ctx} or
2031 @var{r_item} is not a valid pointer, @code{GPGME_No_Request} if there
2032 is no pending operation, @code{GPGME_Out_Of_Core} if there is not
2033 enough memory for the operation.
2034 @end deftypefun
2035
2036 @deftypefun GpgmeError gpgme_op_trustlist_end (@w{GpgmeCtx @var{ctx}})
2037 The function @code{gpgme_op_trustlist_next} ends a pending key list
2038 operation in the context @var{ctx}.
2039
2040 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
2041 valid pointer, @code{GPGME_No_Request} if there is no pending
2042 operation, @code{GPGME_Out_Of_Core} if at some time during the
2043 operation there was not enough memory available.
2044 @end deftypefun
2045
2046
2047 @node Information About Trust Items
2048 @subsection Information About Trust Items
2049 @cindex trust item, information about
2050 @cindex trust item, attributes
2051 @cindex attributes, of a trust item
2052
2053 Trust items have attributes which can be queried using the interfaces
2054 below.  The attribute identifiers are shared with those for key
2055 attributes.  @xref{Information About Keys}.
2056
2057 @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}})
2058 The function @code{gpgme_trust_item_get_string_attr} returns the value
2059 of the string-representable attribute @var{what} of trust item
2060 @var{item}.  The arguments @var{idx} and @var{reserved} are reserved
2061 for later use and should be @code{0} and @code{NULL} respectively.
2062
2063 The string returned is only valid as long as the key is valid.
2064
2065 The function returns @code{0} if an attribute can't be returned as a
2066 string, @var{key} is not a valid pointer, @var{idx} out of range,
2067 or @var{reserved} not @code{NULL}.
2068 @end deftypefun
2069
2070 @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}})
2071 The function @code{gpgme_trust_item_get_int_attr} returns the value of
2072 the number-representable attribute @var{what} of trust item
2073 @var{item}.  If the attribute occurs more than once in the trust item,
2074 the index is specified by @var{idx}.  However, currently no such
2075 attribute exists, so @var{idx} should be @code{0}.  The argument
2076 @var{reserved} is reserved for later use and should be @code{NULL}.
2077
2078 The function returns @code{0} if the attribute can't be returned as a
2079 number, @var{key} is not a valid pointer, @var{idx} out of range,
2080 or @var{reserved} not @code{NULL}.
2081 @end deftypefun
2082
2083
2084 @node Manipulating Trust Items
2085 @subsection Manipulating Trust Items
2086 @cindex trust item, manipulation
2087
2088 @deftypefun void gpgme_trust_item_release (@w{GpgmeTrustItem @var{item}})
2089 The function @code{gpgme_trust_item_release} destroys a
2090 @code{GpgmeTrustItem} object and releases all associated resources.
2091 @end deftypefun
2092
2093 @node Crypto Operations
2094 @section Crypto Operations
2095 @cindex cryptographic operation
2096
2097 @menu
2098 * Decrypt::                       Decrypting a ciphertext.
2099 * Verify::                        Verifying a signature.
2100 * Decrypt and Verify::            Decrypting a signed ciphertext.
2101 * Sign::                          Creating a signature.
2102 * Encrypt::                       Encrypting a plaintext.
2103 * Detailed Results::              How to obtain more info about the operation.
2104 @end menu
2105
2106
2107 @node Decrypt
2108 @subsection Decrypt
2109 @cindex decryption
2110 @cindex cryptographic operation, decryption
2111
2112 @deftypefun GpgmeError gpgme_op_decrypt (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
2113 The function @code{gpgme_op_decrypt} decrypts the ciphertext in the
2114 data object @var{cipher} and stores it into the data object
2115 @var{plain}.
2116
2117 The function returns @code{GPGME_No_Error} if the ciphertext could be
2118 decrypted successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2119 @var{cipher} or @var{plain} is not a valid pointer,
2120 @code{GPGME_No_Data} if @var{cipher} does not contain any data to
2121 decrypt, @code{GPGME_Decryption_Failed} if @var{cipher} is not a valid
2122 cipher text, @code{GPGME_No_Passphrase} if the passphrase for the
2123 secret key could not be retrieved, and passes through any errors that
2124 are reported by the crypto engine support routines.
2125 @end deftypefun
2126
2127 @deftypefun GpgmeError gpgme_op_decrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
2128 The function @code{gpgme_op_decrypt_start} initiates a
2129 @code{gpgme_op_decrypt} operation.  It can be completed by calling
2130 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
2131
2132 The function returns @code{GPGME_No_Error} if the operation could be
2133 started successfully, and @code{GPGME_Invalid_Value} if @var{cipher}
2134 or @var{plain} is not a valid pointer.
2135 @end deftypefun
2136
2137
2138 @node Verify
2139 @subsection Verify
2140 @cindex verification
2141 @cindex signature, verification
2142 @cindex cryptographic operation, verification
2143 @cindex cryptographic operation, signature check
2144 @cindex signature, status
2145
2146 @deftp {Data type} {enum GpgmeSigStat}
2147 @tindex GpgmeSigStat
2148 The @code{GpgmeSigStat} type holds the result of a signature check, or
2149 the combined result of all signatures.  The following results are
2150 possible:
2151
2152 @table @code
2153 @item GPGME_SIG_STAT_NONE
2154 This status should not occur in normal operation.
2155
2156 @item GPGME_SIG_STAT_GOOD
2157 This status indicates that the signature is valid.  For the combined
2158 result this status means that all signatures are valid.
2159
2160 @item GPGME_SIG_STAT_GOOD_EXP
2161 This status indicates that the signature is valid but expired.  For
2162 the combined result this status means that all signatures are valid
2163 and expired.
2164
2165 @item GPGME_SIG_STAT_GOOD_EXPKEY
2166 This status indicates that the signature is valid but the key used to
2167 verify the signature has expired.  For the combined result this status
2168 means that all signatures are valid and all keys are expired.
2169
2170 @item GPGME_SIG_STAT_BAD
2171 This status indicates that the signature is invalid.  For the combined
2172 result this status means that all signatures are invalid.
2173
2174 @item GPGME_SIG_STAT_NOKEY
2175 This status indicates that the signature could not be verified due to
2176 a missing key.  For the combined result this status means that all
2177 signatures could not be checked due to missing keys.
2178
2179 @item GPGME_SIG_STAT_NOSIG
2180 This status indicates that the signature data provided was not a real
2181 signature.
2182
2183 @item GPGME_SIG_STAT_ERROR
2184 This status indicates that there was some other error which prevented
2185 the signature verification.
2186
2187 @item GPGME_SIG_STAT_DIFF
2188 For the combined result this status means that at least two signatures
2189 have a different status.  You can get each key's status with
2190 @code{gpgme_get_sig_status}.
2191 @end table
2192 @end deftp
2193
2194 @deftypefun GpgmeError gpgme_op_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{sig}}, @w{GpgmeData @var{plain}}, @w{GpgmeSigStat *@var{r_stat}})
2195 The function @code{gpgme_op_verify} verifies that the signature in the
2196 data object @var{sig} is a valid signature.  If @var{plain} is
2197 initialized with plaintext data, it is assumed that @var{sig} is a
2198 detached signature, and its validity for the plaintext given in
2199 @var{plain} is verified.  If @var{plain} is an uninitialized data
2200 object, it is assumed that @var{sig} is a normal (or cleartext)
2201 signature, and the plaintext is available in @var{plain} after
2202 successful verification.
2203
2204 The combined status of all signatures is returned in @var{r_stat}.
2205 The results of the individual signature verifications can be retrieved
2206 with @code{gpgme_get_sig_status} and @code{gpgme_get_sig_key}.
2207
2208 The function returns @code{GPGME_No_Error} if the operation could be
2209 completed successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2210 @var{sig}, @var{plain} or @var{r_stat} is not a valid pointer,
2211 @code{GPGME_No_Data} if @var{sig} does not contain any data to verify,
2212 and passes through any errors that are reported by the crypto engine
2213 support routines.
2214 @end deftypefun
2215
2216 @deftypefun GpgmeError gpgme_op_verify_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{sig}}, @w{GpgmeData @var{plain}})
2217 The function @code{gpgme_op_verify_start} initiates a
2218 @code{gpgme_op_verify} operation.  It can be completed by calling
2219 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
2220
2221 The function returns @code{GPGME_No_Error} if the operation could be
2222 started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2223 @var{sig}, @var{plain} or @var{r_stat} is not a valid pointer, and
2224 @code{GPGME_No_Data} if @var{sig} or @var{plain} does not contain any
2225 data to verify.
2226 @end deftypefun
2227
2228 @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}})
2229 The function @code{gpgme_get_sig_status} receives information about a
2230 signature after the @code{gpgme_op_verify} or
2231 @code{gpgme_op_verify_decrypt} operation.  A single detached signature
2232 can contain signatures by more than one key.  The @var{idx} specifies
2233 which signature's information should be retrieved, starting from
2234 @var{0}.
2235
2236 The status of the signature will be returned in @var{r_stat} if it is
2237 not @code{NULL}.  The creation time stamp of the signature will be
2238 returned in @var{r_created} if it is not @var{NULL}.
2239
2240 The function returns a statically allocated string that contains the
2241 fingerprint of the key which signed the plaintext, or @code{NULL} if
2242 @var{ctx} is not a valid pointer, the operation is still pending, or
2243 no verification could be performed.
2244 @end deftypefun
2245
2246 @deftypefun {const char *} gpgme_get_sig_string_attr (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeAttr @var{what}}, @w{int @var{whatidx}})
2247 This function is similar to @code{gpgme_get_sig_status} but may be used
2248 to retrieve more detailed information.  @var{ctx} should be the context
2249 used for the last signature verification, @var{idx} is used to enumerate
2250 over all signatures starting with @code{0} and @var{whatidx} should be
2251 @code{0} unless otherwise stated.
2252
2253 The following values may be used for @var{what}:
2254 @table @code
2255 @item GPGME_ATTR_FPR
2256 Return the fingerprint of the key used to create the signature.
2257
2258 @item GPGME_ATTR_ERRTOK
2259 Return a token with a more detailed error description.  A @var{whatidx}
2260 of @code{0} returns an error token associated with validity calculation,
2261 a value of @code{1} return an error token related to the certificate
2262 checking.
2263
2264 @end table
2265 @end deftypefun
2266
2267 @deftypefun {const char *} gpgme_get_sig_ulong_attr (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeAttr @var{waht}}, @w{int @var{whatidx}})
2268 This function is similar to @code{gpgme_get_sig_string_attr} but used
2269 for attributes which can be represented by an @code{unsigned long} data
2270 type.  @var{ctx} should be the context used for the last signature
2271 verification, @var{idx} is used to enumerate over all signatures
2272 starting with @code{0} and @var{whatidx} should be @code{0} unless
2273 otherwise stated.
2274
2275 The following values may be used for @var{what}:
2276 @table @code
2277 @item GPGME_ATTR_CREATED
2278 Return the creation time of the signature in seconds since Epoch.  This
2279 is the same value as returned by @code{gpgme_get_sig_status}.
2280
2281 @item GPGME_ATTR_EXPIRE
2282 Return the expiration time of the signature in seconds since Epoch. 
2283
2284 @item GPGME_ATTR_VALIDITY
2285 Returns the validity of the key used to create the signature.  This is a
2286 shortcut function which avoids an extra key lookup.  The value returned
2287 is one of @code{GPGME_VALIDITY_UNKNOWN}, @code{GPGME_VALIDITY_NEVER},
2288 @code{GPGME_VALIDITY_MARGINAL} or @code{GPGME_VALIDITY_FULL}.
2289
2290 @item GPGME_ATTR_SIG_STATUS
2291 This is the same value as returned by @code{gpgme_get_sig_status}.
2292
2293 @item GPGME_ATTR_SIG_SUMMARY
2294 This returns a bit vector giving a summary of the signature status.
2295 Itprovides an easy interface to a defined semantic of the signature
2296 status.  Checking just one bit is sufficient to see whether a signature
2297 is valid without any restrictions.
2298
2299 The defined bits are:
2300   @table @code
2301   @item GPGME_SIGSUM_VALID
2302   The signature is fully valid.
2303
2304   @item GPGME_SIGSUM_GREEN
2305   The signature is good but one might want to display some extra
2306   information.  Check the other bits.
2307
2308   @item GPGME_SIGSUM_RED
2309   The signature is bad. It might be useful to checkother bits and
2310   display moe information, i.e. a revoked certificate might not render a
2311   signature invalid when the message was received prior to the cause for
2312   the revocation.
2313
2314   @item GPGME_SIGSUM_KEY_REVOKED
2315   The key or at least one certificate has been revoked.
2316
2317   @item GPGME_SIGSUM_KEY_EXPIRED
2318   The key or one of the certificates has expired. It is probably a good
2319   idea to display the date of the expiration.
2320
2321   @item GPGME_SIGSUM_SIG_EXPIRED
2322   The signature has expired.
2323
2324   @item GPGME_SIGSUM_KEY_MISSING
2325   Can't verifydue to a missing key o certificate.
2326
2327   @item GPGME_SIGSUM_CRL_MISSING
2328   The CRL (or an equivalent mechanism) is not available. 
2329
2330   @item GPGME_SIGSUM_CRL_TOO_OLD
2331   Available CRL is too old.
2332
2333   @item GPGME_SIGSUM_BAD_POLICY
2334   A policy requirement was not met. 
2335
2336   @item GPGME_SIGSUM_SYS_ERROR
2337   A system error occured. 
2338
2339   @end table
2340
2341 @end table
2342 @end deftypefun
2343
2344
2345 @deftypefun {const char *} gpgme_get_sig_key (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeSigKey *@var{r_stat}})
2346 The function @code{gpgme_get_sig_status} receives a @code{GpgmeKey}
2347 object for the key which was used to verify the signature after the
2348 @code{gpgme_op_verify} or @code{gpgme_op_verify_decrypt} operation.  A
2349 single detached signature can contain signatures by more than one key.
2350 The @var{idx} specifies which signature's information should be
2351 retrieved, starting from @var{0}.  The key will have on reference for
2352 the user.
2353
2354 The function is a convenient way to retrieve the keys belonging to the
2355 fingerprints returned by @code{gpgme_get_sig_status}.
2356
2357 The function returns @code{GPGME_No_Error} if the key could be
2358 returned, @code{GPGME_Invalid_Value} if @var{r_key} is not a valid
2359 pointer, @code{GPGME_Invalid_Key} if the fingerprint is not valid,
2360 @code{GPGME_EOF} if @var{idx} is too large, or some other error value
2361 if a problem occurred requesting the key.
2362 @end deftypefun
2363
2364 @deftypefun {char *} gpgme_get_notation (@w{GpgmeCtx @var{ctx}})
2365 The function @code{gpgme_get_notation} can be used to retrieve
2366 notation data from the last signature check in the context @var{ctx}.
2367
2368 If there is notation data available from the last signature check,
2369 this function may be used to return this notation data as a string.
2370 The string is an XML representation of that data embedded in a
2371 <notation> container.  The user has to release the string with
2372 @code{free}.
2373
2374 The function returns a string if the notation data is available or
2375 @code{NULL} if there is no such data available.
2376 @end deftypefun
2377
2378
2379 @node Decrypt and Verify
2380 @subsection Decrypt and Verify
2381 @cindex decryption and verification
2382 @cindex verification and decryption
2383 @cindex signature check
2384 @cindex cryptographic operation, decryption and verification
2385
2386 @deftypefun GpgmeError gpgme_op_decrypt_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}}, @w{GpgmeSigStat *@var{r_stat}})
2387 The function @code{gpgme_op_decrypt_verify} decrypts the ciphertext in
2388 the data object @var{cipher} and stores it into the data object
2389 @var{plain}.  If @var{cipher} contains signatures, they will be
2390 verified and their combined status will be returned in @var{r_stat}.
2391
2392 After the operation completed, @code{gpgme_op_get_sig_status} and
2393 @code{gpgme_op_get_sig_key} can be used to retrieve more information
2394 about the signatures.
2395
2396 The function returns @code{GPGME_No_Error} if the ciphertext could be
2397 decrypted successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2398 @var{cipher}, @var{plain} or @var{r_stat} is not a valid pointer,
2399 @code{GPGME_No_Data} if @var{cipher} does not contain any data to
2400 decrypt, @code{GPGME_Decryption_Failed} if @var{cipher} is not a valid
2401 cipher text, @code{GPGME_No_Passphrase} if the passphrase for the
2402 secret key could not be retrieved, and passes through any errors that
2403 are reported by the crypto engine support routines.
2404 @end deftypefun
2405
2406 @deftypefun GpgmeError gpgme_op_decrypt_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
2407 The function @code{gpgme_op_decrypt_verify_start} initiates a
2408 @code{gpgme_op_decrypt_verify} operation.  It can be completed by
2409 calling @code{gpgme_wait} on the context.  @xref{Waiting For
2410 Completion}.
2411
2412 The function returns @code{GPGME_No_Error} if the operation could be
2413 started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2414 @var{cipher}, @var{plain} or @var{r_stat} is not a valid pointer, and
2415 @code{GPGME_No_Data} if @var{cipher} does not contain any data to
2416 decrypt.
2417 @end deftypefun
2418
2419
2420 @node Sign
2421 @subsection Sign
2422 @cindex signature, creation
2423 @cindex sign
2424 @cindex cryptographic operation, signing
2425
2426 A signature can contain signatures by one or more keys.  The set of
2427 keys used to create a signatures is contained in a context, and is
2428 applied to all following signing operations in this context (until the
2429 set is changed).
2430
2431 @menu
2432 * Selecting Signers::             How to choose the keys to sign with.
2433 * Creating a Signature::          How to create a signature.
2434 @end menu
2435
2436
2437 @node Selecting Signers
2438 @subsubsection Selecting Signers
2439 @cindex signature, selecting signers
2440 @cindex signers, selecting
2441
2442 @deftypefun void gpgme_signers_clear (@w{GpgmeCtx @var{ctx}})
2443 The function @code{gpgme_signers_clear} releases a reference for each
2444 key on the signers list and removes the list of signers from the
2445 context @var{ctx}.
2446
2447 Every context starts with an empty list.
2448 @end deftypefun
2449
2450 @deftypefun GpgmeError gpgme_signers_add (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}})
2451 The function @code{gpgme_signers_add} adds the key @var{key} to the
2452 list of signers in the context @var{ctx}.
2453
2454 Calling this function acquires an additional reference for the key.
2455 @end deftypefun
2456
2457 @deftypefun GpgmeKey gpgme_signers_enum (@w{const GpgmeCtx @var{ctx}}, @w{int @var{seq}})
2458 The function @code{gpgme_signers_enum} returns the @var{seq}th key in
2459 the list of signers in the context @var{ctx}.  An additional reference
2460 is acquired for the user.
2461
2462 If @var{seq} is out of range, @code{NULL} is returned.
2463 @end deftypefun
2464
2465
2466 @node Creating a Signature
2467 @subsubsection Creating a Signature
2468
2469 @deftp {Data type} {enum GpgmeSigMode}
2470 @tindex GpgmeSigMode
2471 The @code{GpgmeSigMode} type is used to specify the desired type of a
2472 signature.  The following modes are available:
2473
2474 @table @code
2475 @item GPGME_SIG_MODE_NORMAL
2476 A normal signature is made, the output includes the plaintext and the
2477 signature.
2478
2479 @item GPGME_SIG_MODE_DETACH
2480 A detached signature is made.
2481
2482 @item GPGME_SIG_MODE_CLEAR
2483 A clear text signature is made.  The @acronym{ASCII} armor and text
2484 mode settings of the context are ignored.
2485 @end table
2486 @end deftp
2487
2488 @deftypefun GpgmeError gpgme_op_sign (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{sig}}, @w{GpgmeSigMode @var{mode}})
2489 The function @code{gpgme_op_sign} creates a signature for the text in
2490 the data object @var{plain} and returns it in the data object
2491 @var{sig}.  The type of the signature created is determined by the
2492 @acronym{ASCII} armor and text mode attributes set for the context
2493 @var{ctx} and the requested signature mode @var{mode}.
2494
2495 More information about the signatures is available with
2496 @code{gpgme_get_op_info}.  @xref{Detailed Results}.
2497
2498 If an S/MIME signed message is created using the CMS crypto engine,
2499 the number of certificates to include in the message can be specified
2500 with @code{gpgme_set_include_certs}.  @xref{Included Certificates}.
2501
2502 The function returns @code{GPGME_No_Error} if the signature could be
2503 created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2504 @var{plain} or @var{sig} is not a valid pointer, @code{GPGME_No_Data}
2505 if the signature could not be created, @code{GPGME_No_Passphrase} if
2506 the passphrase for the secret key could not be retrieved, and passes
2507 through any errors that are reported by the crypto engine support
2508 routines.
2509 @end deftypefun
2510
2511 @deftypefun GpgmeError gpgme_op_sign_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{sig}}, @w{GpgmeSigMode @var{mode}})
2512 The function @code{gpgme_op_sign_start} initiates a
2513 @code{gpgme_op_sign} operation.  It can be completed by calling
2514 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
2515
2516 The function returns @code{GPGME_No_Error} if the operation could be
2517 started successfully, and @code{GPGME_Invalid_Value} if @var{ctx},
2518 @var{plain} or @var{sig} is not a valid pointer.
2519 @end deftypefun
2520
2521
2522 @node Encrypt
2523 @subsection Encrypt
2524 @cindex encryption
2525 @cindex cryptographic operation, encryption
2526
2527 One plaintext can be encrypted for several recipients at the same
2528 time.  The list of recipients is created independently of any context,
2529 and then passed to the encryption operation.
2530
2531 @menu
2532 * Selecting Recipients::          How to choose the recipients.
2533 * Encrypting a Plaintext::        How to encrypt a plaintext.
2534 @end menu
2535
2536
2537 @node Selecting Recipients
2538 @subsubsection Selecting Recipients
2539 @cindex encryption, selecting recipients
2540 @cindex recipients
2541
2542 @deftp {Data type} GpgmeRecipients
2543 The @code{GpgmeRecipients} type is a handle for a set of recipients
2544 that can be used in an encryption process.
2545 @end deftp
2546
2547 @deftypefun GpgmeError gpgme_recipients_new (@w{GpgmeRecipients *@var{r_rset}})
2548 The function @code{gpgme_recipients_new} creates a new, empty set of
2549 recipients and returns a handle for it in @var{r_rset}.
2550
2551 The function returns @code{GPGME_No_Error} if the recipient set could
2552 be created successfully, and @code{GPGME_Out_Of_Core} if not enough
2553 memory was available.
2554 @end deftypefun
2555
2556 @deftypefun void gpgme_recipients_release (@w{GpgmeRecipients @var{rset}})
2557 The function @code{gpgme_recipients_release} destroys the set of
2558 recipients @var{rset} and releases all associated resources.
2559 @end deftypefun
2560
2561 @deftypefun GpgmeError gpgme_recipients_add_name (@w{GpgmeRecipients @var{rset}}, @w{const char *@var{name}})
2562 The function @code{gpgme_recipients_add_name} adds the recipient
2563 @var{name} to the set of recipients @var{rset}.  This is equivalent to
2564 @code{gpgme_recipients_add_name_with_validity} with a validity of
2565 @code{GPGME_VALIDITY_UNKNOWN}.
2566
2567 The function returns @code{GPGME_No_Error} if the recipient was added
2568 successfully, @code{GPGME_Invalid_Value} if @var{rset} or @var{name}
2569 is not a valid pointer, and @code{GPGME_Out_Of_Core} if not enough
2570 memory is available.
2571 @end deftypefun
2572
2573 @deftypefun GpgmeError gpgme_recipients_add_name_with_validity (@w{GpgmeRecipients @var{rset}}, @w{const char *@var{name}}, @w{GpgmeValidity @var{val}})
2574 The function @code{gpgme_recipients_add_name_with_validity} adds the
2575 recipient @var{name} with the validity @var{val} to the set of
2576 recipients @var{rset}.  If the validity is not known, the function
2577 @code{gpgme_recipients_add_name} can be used.
2578 @xref{Information About Keys}, for the possible values for @var{val}.
2579
2580 The function returns @code{GPGME_No_Error} if the recipient was added
2581 successfully, @code{GPGME_Invalid_Value} if @var{rset} or @var{name}
2582 is not a valid pointer, and @code{GPGME_Out_Of_Core} if not enough
2583 memory is available.
2584 @end deftypefun
2585
2586 @deftypefun {unsigned int} gpgme_recipients_count (@w{const @var{GpgmeRecipients rset}})
2587 The function @code{gpgme_recipients_count} returns the number of
2588 recipients in the set @var{rset}.
2589 @end deftypefun
2590
2591 @deftypefun GpgmeError gpgme_recipients_enum_open (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}})
2592 The function @code{gpgme_recipients_enum_open} creates a new iterator
2593 @var{iter} that can be used to walk through the set of recipients in
2594 @var{rset}, using @code{gpgme_recipients_enum_read}.
2595
2596 If the iterator is not needed anymore, it can be closed with
2597 @code{gpgme_recipients_enum_close}.
2598
2599 The function returns @code{GPGME_No_Error} if the enumerator was
2600 successfully created and @code{GPGME_Invalid_Value} if @var{rset} or
2601 @var{iter} is not a valid pointer.
2602 @end deftypefun
2603
2604 @deftypefun {const char *} gpgme_recipients_enum_read (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}})
2605 The function @code{gpgme_recipients_enum_read} returns a string
2606 containing the name of the next recipient in the set @var{rset} for
2607 the iterator @var{iter}.  The string is valid as long as @var{rset} is
2608 valid or the function is called the next time with the same recipient
2609 set and iterator, whatever is earlier.
2610 @end deftypefun
2611
2612 @deftypefun GpgmeError gpgme_recipients_enum_close (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}})
2613 The function @code{gpgme_recipients_enum_close} releases the iterator
2614 @var{iter} for the recipient set @var{rset}.
2615 @end deftypefun
2616
2617
2618 @node Encrypting a Plaintext
2619 @subsubsection Encrypting a Plaintext
2620
2621 @deftypefun GpgmeError gpgme_op_encrypt (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
2622 The function @code{gpgme_op_encrypt} encrypts the plaintext in the data
2623 object @var{plain} for the recipients @var{rset} and stores the
2624 ciphertext in the data object @var{cipher}.  The type of the
2625 ciphertext created is determined by the @acronym{ASCII} armor and text
2626 mode attributes set for the context @var{ctx}.
2627
2628 If @code{GPGME_Invalid_Recipients} is returned, some recipients in
2629 @var{rset} are invalid, but not all.  In this case the plaintext is
2630 encrypted for all valid recipients and returned in @var{cipher}.  More
2631 information about the invalid recipients is available with
2632 @code{gpgme_get_op_info}.  @xref{Detailed Results}.
2633
2634 If @var{recp} is @code{NULL}, symmetric rather than public key
2635 encryption is performed.  Symmetrically encrypted cipher text can be
2636 deciphered with @code{gpgme_op_decrypt}.  Note that in this case the
2637 crypto backend needs to retrieve a passphrase from the user.
2638 Symmetric encryption is currently only supported for the OpenPGP
2639 crypto backend.
2640
2641 The function returns @code{GPGME_No_Error} if the ciphertext could be
2642 created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2643 @var{rset}, @var{plain} or @var{cipher} is not a valid pointer,
2644 @code{GPGME_No_Recipients} if @var{rset} does not contain any valid
2645 recipients, @code{GPGME_Invalid_Recipients} if @var{rset} contains
2646 some invalid recipients, @code{GPGME_No_Passphrase} if the passphrase
2647 for the secret key could not be retrieved, and passes through any
2648 errors that are reported by the crypto engine support routines.
2649 @end deftypefun
2650
2651 @deftypefun GpgmeError gpgme_op_encrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
2652 The function @code{gpgme_op_encrypt_start} initiates a
2653 @code{gpgme_op_encrypt} operation.  It can be completed by calling
2654 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
2655
2656 The function returns @code{GPGME_No_Error} if the operation could be
2657 started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2658 @var{rset}, @var{plain} or @var{cipher} is not a valid pointer, and
2659 @code{GPGME_No_Recipients} if @var{rset} does not contain any valid
2660 recipients.
2661 @end deftypefun
2662
2663
2664 @deftypefun GpgmeError gpgme_op_encrypt_sign (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
2665 The function @code{gpgme_op_encrypt_sign} does a combined encrypt and
2666 sign operation.  It is used like @code{gpgme_op_encrypt}, but the
2667 ciphertext also contains signatures for the signers listed in
2668 @var{ctx}.
2669
2670 The combined encrypt and sign operation is currently only available
2671 for the OpenPGP crypto engine.
2672 @end deftypefun
2673
2674 @deftypefun GpgmeError gpgme_op_encrypt_sign_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
2675 The function @code{gpgme_op_encrypt_sign_start} initiates a
2676 @code{gpgme_op_encrypt_sign} operation.  It can be completed by
2677 calling @code{gpgme_wait} on the context.  @xref{Waiting For
2678 Completion}.
2679
2680 The function returns @code{GPGME_No_Error} if the operation could be
2681 started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2682 @var{rset}, @var{plain} or @var{cipher} is not a valid pointer, and
2683 @code{GPGME_No_Recipients} if @var{rset} does not contain any valid
2684 recipients.
2685 @end deftypefun
2686
2687
2688 @node Detailed Results
2689 @subsection Detailed Results
2690 @cindex cryptographic operation, detailed results
2691
2692 @deftypefun {char *} gpgme_get_op_info (@w{GpgmeCtx @var{ctx}}, @w{int @var{reserved}})
2693 The function @code{gpgme_get_op_info} retrieves more information about
2694 the last crypto operation.
2695
2696 The function returns a string in the XML format.  The user has to
2697 release the string with @code{free}.
2698
2699 Here is a sample of the information that might be returned:
2700 @example
2701 <GnupgOperationInfo>
2702   <signature>
2703     <detached/> <!-- or cleartext or standard -->
2704     <algo>17</algo>
2705     <hashalgo>2</hashalgo>
2706     <micalg>pgp-sha1</micalg>
2707     <sigclass>01</sigclass>
2708     <created>9222222</created>
2709     <fpr>121212121212121212</fpr>
2710   </signature>
2711 </GnupgOperationInfo>
2712 @end example
2713
2714 Currently, the only operations that return additional information are
2715 encrypt, sign and import.  @xref{Encrypt}, @xref{Sign},
2716 @xref{Importing Keys}.
2717
2718 The function returns a string or @code{NULL} if no such data is
2719 available.
2720 @end deftypefun
2721
2722
2723 @node Run Control
2724 @section Run Control
2725 @cindex run control
2726 @cindex cryptographic operation, running
2727
2728 @acronym{GPGME} supports running operations synchronously and
2729 asynchronously.  You can use asynchronous operation to set up a
2730 context up to initiating the desired operation, but delay performing
2731 it to a later point.
2732
2733 Furthermore, you can use an external event loop to control exactly
2734 when @acronym{GPGME} runs.  This ensures that @acronym{GPGME} only
2735 runs when necessary and also prevents it from blocking for a long
2736 time.
2737
2738 @menu
2739 * Waiting For Completion::        Waiting until an operation is completed.
2740 * Cancelling an Operation::       Interrupting a running operation.
2741 * Hooking Up Into Idle Time::     Doing something when nothing has to be done.
2742 * Using External Event Loops::    Advanced control over what happens when.
2743 @end menu
2744
2745
2746 @node Waiting For Completion
2747 @subsection Waiting For Completion
2748 @cindex cryptographic operation, wait for
2749 @cindex wait for completion
2750
2751 @deftypefun GpgmeCtx gpgme_wait (@w{GpgmeCtx @var{ctx}}, @w{GpgmeError *@var{status}}, @w{int @var{hang}})
2752 The function @code{gpgme_wait} continues the pending operation within
2753 the context @var{ctx}.  In particular, it ensures the data exchange
2754 between @acronym{GPGME} and the crypto backend and watches over the
2755 run time status of the backend process.
2756
2757 If @var{hang} is true, the function does not return until the
2758 operation is completed or cancelled.  Otherwise the function will not
2759 block for a long time.
2760
2761 The error status of the finished operation is returned in @var{status}
2762 if @code{gpgme_wait} does not return @code{NULL}.
2763
2764 The @var{ctx} argument can be @code{NULL}.  In that case,
2765 @code{gpgme_wait} waits for any context to complete its operation.
2766
2767 @code{gpgme_wait} can be used only in conjunction with any context
2768 that has a pending operation initiated with one of the
2769 @code{gpgme_op_*_start} functions except @code{gpgme_op_keylist_start}
2770 and @code{gpgme_op_trustlist_start} (for which you should use the
2771 corresponding @code{gpgme_op_*_next} functions).  If @var{ctx} is
2772 @code{NULL}, all of such contexts are waited upon and possibly
2773 returned.  Synchronous operations running in parallel, as well as key
2774 and trust item list operations, do not affect @code{gpgme_wait}.
2775
2776 In a multi-threaded environment, only one thread should ever call
2777 @code{gpgme_wait} at any time, irregardless if @var{ctx} is specified
2778 or not.  This means that all calls to this function should be fully
2779 synchronized by locking primitives.
2780
2781 The function returns the @var{ctx} of the context which has finished
2782 the operation.
2783 @end deftypefun
2784
2785
2786 @node Cancelling an Operation
2787 @subsection Cancelling an Operation
2788 @cindex cancellation
2789 @cindex cryptographic operation, cancel
2790
2791 @deftypefun void gpgme_cancel (@w{GpgmeCtx @var{ctx}})
2792 The function @code{gpgme_cancel} tries to cancel the pending
2793 operation.  A running synchronous operation in the context or the
2794 function @code{gpgme_wait} with this context as its @var{ctx} argument
2795 might notice the cancellation flag and return.  It is currently not
2796 guaranteed to work under all circumstances.  Its current primary
2797 purpose is to prevent asking for a passphrase again in the passphrase
2798 callback.
2799 @end deftypefun
2800
2801
2802 @node Hooking Up Into Idle Time
2803 @subsection Hooking Up Into Idle Time
2804 @cindex idle time
2805 @cindex idle function
2806
2807 @deftp {Data type} {void (*GpgmeIdleFunc) (void)}
2808 @tindex GpgmeIdleFunc
2809 The @code{GpgmeIdleFunc} type is the type of functions usable as
2810 an idle function that can be registered with @code{gpgme_register_idle}.
2811 @end deftp
2812
2813 @deftypefun GpgmeIdleFunc gpgme_register_idle (@w{GpgmeIdleFunc @var{idle}})
2814 The function @code{gpgme_register_idle} can be used to register
2815 @var{idle} as the idle function.
2816
2817 @var{idle} will be called whenever @acronym{GPGME} thinks that it is
2818 idle and time can better be spent elsewhere.  Setting @var{idle} to
2819 @code{NULL} disables use of the idle function (this is the default).
2820
2821 The function returns the old idle function, or @code{NULL} if none was
2822 registered yet.
2823 @end deftypefun
2824
2825
2826 @node Using External Event Loops
2827 @subsection Using External Event Loops
2828 @cindex event loop, external
2829
2830 @acronym{GPGME} hides the complexity of the communication between the
2831 library and the crypto engine.  The price of this convenience is that
2832 the calling thread can block arbitrary long waiting for the data
2833 returned by the crypto engine.  In single-threaded programs, in
2834 particular if they are interactive, this is an unwanted side-effect.
2835 OTOH, if @code{gpgme_wait} is used without the @var{hang} option being
2836 enabled, it might be called unnecessarily often, wasting CPU time that
2837 could be used otherwise.
2838
2839 The I/O callback interface described in this section lets the user
2840 take control over what happens when.  @acronym{GPGME} will provide the
2841 user with the file descriptors that should be monitored, and the
2842 callback functions that should be invoked when a file descriptor is
2843 ready for reading or writing.  It is then the user's responsibility to
2844 decide when to check the file descriptors and when to invoke the
2845 callback functions.  Usually this is done in an event loop, that also
2846 checks for events in other parts of the program.  If the callback
2847 functions are only called when the file descriptors are ready,
2848 @acronym{GPGME} will never block.  This gives the user mroe control
2849 over the program flow, and allows to perform other tasks when
2850 @acronym{GPGME} would block otherwise.
2851
2852 By using this advanced mechanism, @acronym{GPGME} can be integrated
2853 smoothly into GUI toolkits like GTK+ even for single-threaded
2854 programs.
2855
2856 @menu
2857 * I/O Callback Interface::        How I/O callbacks are registered.
2858 * Registering I/O Callbacks::     How to use I/O callbacks for a context.
2859 * I/O Callback Example::          An example how to use I/O callbacks.
2860 * I/O Callback Example GTK+::     How to use @acronym{GPGME} with GTK+.
2861 * I/O Callback Example GDK::      How to use @acronym{GPGME} with GDK.
2862 @end menu
2863
2864
2865 @node I/O Callback Interface
2866 @subsubsection I/O Callback Interface
2867
2868 @deftp {Data type} {void (*GpgmeIOCb) (@w{void *@var{data}}, @w{int @var{fd}})}
2869 @tindex GpgmeIOCb
2870 The @code{GpgmeIOCb} type is the type of functions which
2871 @acronym{GPGME} wants to register as I/O callback handlers using the
2872 @code{GpgmeRegisterIOCb} functions provided by the user.
2873
2874 @var{data} and @var{fd} are provided by @acronym{GPGME} when the I/O
2875 callback handler is registered, and should be passed through to the
2876 handler when it is invoked by the user because it noticed activity on
2877 the file descriptor @var{fd}.
2878 @end deftp
2879
2880 @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}})}
2881 @tindex GpgmeRegisterIOCb
2882 The @code{GpgmeRegisterIOCb} type is the type of functions which can
2883 be called by @acronym{GPGME} to register an I/O callback funtion
2884 @var{fnc} for the file descriptor @var{fd} with the user.
2885 @var{fnc_data} should be passed as the first argument to @var{fnc}
2886 when the handler is invoked (the second argument should be @var{fd}).
2887 If @var{dir} is 0, @var{fnc} should be called by the user when
2888 @var{fd} is ready for writing.  If @var{dir} is 1, @var{fnc} should be
2889 called when @var{fd} is ready for reading.
2890
2891 @var{data} was provided by the user when registering the
2892 @code{GpgmeRegisterIOCb} function with @acronym{GPGME} and will always
2893 be passed as the first argument when registering a callback function.
2894 For example, the user can use this to determine the event loop to
2895 which the file descriptor should be added.
2896
2897 @acronym{GPGME} will call this function when a crypto operation is
2898 initiated in a context for which the user has registered I/O callback
2899 handler functions with @code{gpgme_set_io_cbs}.  It can also call this
2900 function when it is in an I/O callback handler for a file descriptor
2901 associated to this context.
2902
2903 The user should return a unique handle in @var{tag} identifying this
2904 I/O callback registration, which will be passed to the
2905 @code{GpgmeRegisterIOCb} function without interpretation when the file
2906 descriptor should not be monitored anymore.
2907 @end deftp
2908
2909 @deftp {Data type} {void (*GpgmeRemoveIOCb) (@w{void *@var{tag}})}
2910 The @code{GpgmeRemoveIOCb} type is the type of functions which can be
2911 called by @acronym{GPGME} to remove an I/O callback handler that was
2912 registered before.  @var{tag} is the handle that was returned by the
2913 @code{GpgmeRegisterIOCb} for this I/O callback.
2914
2915 @acronym{GPGME} can call this function when a crypto operation is in
2916 an I/O callback.  It will also call this function when the context is
2917 destroyed while an operation is pending.
2918 @end deftp
2919
2920 @deftp {Data type} {enum GpgmeEventIO}
2921 @tindex GpgmeEventIO
2922 The @code{GpgmeEventIO} type specifies the type of an event that is
2923 reported to the user by @acronym{GPGME} as a consequence of an I/O
2924 operation.  The following events are defined:
2925
2926 @table @code
2927 @item GPGME_EVENT_DONE
2928 The operation is finished, the last I/O callback for this operation
2929 was removed.  The accompanying @var{type_data} points to a
2930 @code{GpgmeError} variable that contains the status of the operation
2931 that finished.  This event is signalled after the last I/O callback
2932 has been removed.
2933
2934 @item GPGME_EVENT_NEXT_KEY
2935 In a @code{gpgme_op_keylist_start} operation, the next key was
2936 received from the crypto engine.  The accompanying @var{type_data} is
2937 a @code{GpgmeKey} variable that contains the key with one reference
2938 for the user.
2939
2940 @item GPGME_EVENT_NEXT_TRUSTITEM
2941 In a @code{gpgme_op_trustlist_start} operation, the next trust item
2942 was received from the crypto engine.  The accompanying @var{type_data}
2943 is a @code{GpgmeTrustItem} variable that contains the trust item with
2944 one reference for the user.
2945 @end table
2946 @end deftp
2947
2948 @deftp {Data type} {void (*GpgmeEventIOCb) (@w{void *@var{data}}, @w{GpgmeEventIO @var{type}}, @w{void *@var{type_data}})}
2949 The @code{GpgmeEventIOCb} type is the type of functions which can be
2950 called by @acronym{GPGME} to signal an event for an operation running
2951 in a context which has I/O callback functions registered by the user.
2952
2953 @var{data} was provided by the user when registering the
2954 @code{GpgmeEventIOCb} function with @acronym{GPGME} and will always be
2955 passed as the first argument when registering a callback function.
2956 For example, the user can use this to determine the context in which
2957 this event has occured.
2958
2959 @var{type} will specify the type of event that has occured.
2960 @var{type_data} specifies the event further, as described in the above
2961 list of possible @code{GpgmeEventIO} types.
2962
2963 @acronym{GPGME} can call this function in an I/O callback handler.
2964 @end deftp
2965
2966
2967 @node Registering I/O Callbacks
2968 @subsubsection Registering I/O Callbacks
2969
2970 @deftp {Data type} {struct GpgmeIOCbs}
2971 @tindex GpgmeEventIO
2972 This structure is used to store the I/O callback interface functions
2973 described in the previous section.  It has the following members:
2974
2975 @table @code
2976 @item GpgmeRegisterIOCb add
2977 This is the function called by @acronym{GPGME} to register an I/O
2978 callback handler.  It must be specified.
2979
2980 @item void *add_data
2981 This is passed as the first argument to the @code{add} function when
2982 it is called by @acronym{GPGME}.  For example, it can be used to
2983 determine the event loop to which the file descriptor should be added.
2984
2985 @item GpgmeRemoveIOCb remove
2986 This is the function called by @acronym{GPGME} to remove an I/O
2987 callback handler.  It must be specified.
2988
2989 @item GpgmeEventIOCb event
2990 This is the function called by @acronym{GPGME} to signal an event for
2991 an operation.  It is optional, but if you don't specify it, you can
2992 not retrieve the return value of the operation.
2993
2994 @item void *event_data
2995 This is passed as the first argument to the @code{event} function when
2996 it is called by @acronym{GPGME}.  For example, it can be used to
2997 determine the context in which the event has occured.
2998 @end table
2999 @end deftp
3000
3001 @deftypefun void gpgme_set_io_cbs (@w{GpgmeCtx @var{ctx}}, @w{struct GpgmeIOCbs *@var{io_cbs}})
3002 The function @code{gpgme_set_io_cbs} enables the I/O callback
3003 interface for the context @var{ctx}.  The I/O callback functions are
3004 specified by @var{io_cbs}.
3005
3006 If @var{io_cbs}->@code{add} is @code{NULL}, the I/O callback interface
3007 is disabled for the context, and normal operation is restored.
3008 @end deftypefun
3009
3010 @deftypefun void gpgme_get_io_cbs (@w{GpgmeCtx @var{ctx}}, @w{struct GpgmeIOCbs *@var{io_cbs}})
3011 The function @code{gpgme_get_io_cbs} returns the I/O callback
3012 functions set with @code{gpgme_set_io_cbs} in @var{io_cbs}.
3013 @end deftypefun
3014
3015
3016 @node I/O Callback Example
3017 @subsubsection I/O Callback Example
3018
3019 To actually use an external event loop, you have to implement the I/O
3020 callback functions that are used by @acronym{GPGME} to register and
3021 unregister file descriptors.  Furthermore, you have to actually
3022 monitor these file descriptors for activity and call the appropriate
3023 I/O callbacks.
3024
3025 The following example illustrates how to do that.  The example uses
3026 locking to show in which way the the callbacks and the event loop can
3027 run concurrently.  For the event loop, we use a fixed array.  For a
3028 real-world implementation, you should use a dynamically sized
3029 structure because the number of file descriptors needed for a crypto
3030 operation in @acronym{GPGME} is not predictable.
3031
3032 @example
3033 #include <pthread.h>
3034 #include <sys/types.h>
3035 #include <gpgme.h>
3036
3037 /* The following structure holds the result of a crypto operation.  */
3038 struct op_result
3039 @{
3040   int done;
3041   GpgmeError err;
3042 @};
3043
3044 /* The following structure holds the data associated with one I/O
3045 callback.  */
3046 struct one_fd
3047 @{
3048   int fd;
3049   int dir;
3050   GpgmeIOCb fnc;
3051   void *fnc_data;
3052 @};
3053
3054 struct event_loop
3055 @{
3056   pthread_mutex_t lock;
3057 #define MAX_FDS 32
3058   /* Unused slots are marked with FD being -1.  */
3059   struct one_fd fds[MAX_FDS];
3060 @};
3061 @end example
3062
3063 The following functions implement the I/O callback interface.
3064
3065 @example
3066 GpgmeError
3067 add_io_cb (void *data, int fd, int dir, GpgmeIOCb fnc, void *fnc_data,
3068            void **r_tag)
3069 @{
3070   struct event_loop *loop = data;
3071   struct one_fd *fds = loop->fds;
3072   int i;
3073
3074   pthread_mutex_lock (&loop->lock);
3075   for (i = 0; i < MAX_FDS; i++)
3076     @{
3077       if (fds[i].fd == -1)
3078         @{
3079           fds[i].fd = fd;
3080           fds[i].dir = dir;
3081           fds[i].fnc = fnc;
3082           fds[i].fnc_data = fnc_data;
3083           break;
3084         @}
3085     @}
3086   pthread_mutex_unlock (&loop->lock);
3087   if (i == MAX_FDS)
3088     return GPGME_General_Error;
3089   *r_tag = &fds[i];
3090   return 0;
3091 @}
3092
3093 void
3094 remove_io_cb (void *tag)
3095 @{
3096   struct one_fd *fd = tag;
3097
3098   pthread_mutex_lock (&loop->lock);
3099   fd->fd = -1;
3100   pthread_mutex_unlock (&loop->lock);
3101 @}
3102
3103 void
3104 event_io_cb (void *data, GpgmeEventIO type, void *type_data)
3105 @{
3106   struct op_result *result = data;
3107   GpgmeError *err = data;
3108
3109   /* We don't support list operations here.  */
3110   if (type == GPGME_EVENT_DONE)
3111     @{
3112       result->done = 1;
3113       result->err = *data;
3114     @}
3115 @}
3116 @end example
3117
3118 The final missing piece is the event loop, which will be presented
3119 next.  We only support waiting for the success of a single operation.
3120
3121 @example
3122 int
3123 do_select (struct event_loop *loop)
3124 @{
3125   fd_set rfds;
3126   fd_set wfds;
3127   int i, n;
3128   int any = 0;
3129
3130   pthread_mutex_lock (&loop->lock);
3131   FD_ZERO (&rfds);
3132   FD_ZERO (&wfds);
3133   for (i = 0; i < FDLIST_MAX; i++)
3134     if (fdlist[i].fd != -1)
3135       FD_SET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds);
3136   pthread_mutex_unlock (&loop->unlock);
3137
3138   do
3139     @{
3140       n = select (FD_SETSIZE, &rfds, &wfds, NULL, 0);
3141     @}
3142   while (n < 0 && errno == EINTR);
3143
3144   if (n < 0)
3145     return n;   /* Error or timeout.  */
3146
3147   pthread_mutex_lock (&loop->lock);
3148   for (i = 0; i < FDLIST_MAX && n; i++)
3149     @{
3150       if (fdlist[i].fd != -1)
3151         @{
3152           if (FD_ISSET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds))
3153             @{
3154               assert (n);
3155               n--;
3156               any = 1;
3157               /* The I/O callback handler can register/remove callbacks,
3158                  so we have to unlock the file descriptor list.  */
3159               pthread_mutex_unlock (&loop->lock);
3160               (*fdlist[i].fnc) (fdlist[i].fnc_data, fdlist[i].fd);
3161               pthread_mutex_lock (&loop->lock);
3162             @}
3163         @}
3164     @}
3165   pthread_mutex_unlock (&loop->lock);
3166   return any;
3167 @}
3168
3169 void
3170 wait_for_op (struct event_loop *loop, struct op_result *result)
3171 @{
3172   int ret;
3173
3174   do
3175     @{
3176       ret = do_select (loop);
3177     @}
3178   while (ret >= 0 && !result->done);
3179   return ret;
3180 @}
3181 @end example
3182
3183 The main function shows how to put it all together.
3184
3185 @example
3186 int
3187 main (int argc, char *argv[])
3188 @{
3189   struct event_loop loop;
3190   struct op_result result;
3191   GpgmeCtx ctx;
3192   GpgmeError err;
3193   GpgmeData sig, text;
3194   GpgmeSigStat status;
3195   int i;
3196   struct GpgmeIOCbs io_cbs =
3197   @{
3198     add_io_cb,
3199     &loop,
3200     remove_io_cb,
3201     event_io_cb,
3202     &result
3203   @};
3204
3205   /* Initialize the loop structure.  */
3206   loop.lock = PTHREAD_MUTEX_INITIALIZER;
3207   for (i = 0; i < MAX_FDS; i++)
3208     loop->fds[i].fd = -1;
3209
3210   /* Initialize the result structure.  */
3211   result.done = 0;
3212
3213   err = gpgme_data_new_from_file (&sig, "signature", 1);
3214   if (!err)
3215     err = gpgme_data_new_from_file (&text, "text", 1);
3216   if (!err)
3217     err = gpgme_new (&ctx);
3218   if (!err)
3219     @{
3220        gpgme_set_io_cbs (ctx, &io_cbs);
3221        err = gpgme_op_verify_start (ctx, sig, text, &status);
3222     @}
3223   if (err)
3224     @{
3225       fprintf (stderr, "gpgme error: %s\n", gpgme_strerror (err));
3226       exit (1);
3227     @}
3228
3229   wait_for_op (&loop, &result);
3230   if (!result.done)
3231     @{
3232       fprintf (stderr, "select error\n");
3233       exit (1);
3234     @}
3235   if (!result.err)
3236     @{
3237       fprintf (stderr, "verification failed: %s\n", gpgme_strerror (result.err));
3238       exit (1);
3239     @}
3240   /* Evaluate STATUS.  */
3241   @dots{}
3242   return 0;
3243 @}
3244 @end example
3245
3246
3247 @node I/O Callback Example GTK+
3248 @subsubsection I/O Callback Example GTK+
3249 @cindex GTK+, using @acronym{GPGME} with
3250
3251 The I/O callback interface can be used to integrate @acronym{GPGME}
3252 with the GTK+ event loop.  The following code snippets shows how this
3253 can be done using the appropriate register and remove I/O callback
3254 functions.  In this example, the private data of the register I/O
3255 callback function is unused.  The event notifications is missing
3256 because it does not require any GTK+ specific setup.
3257
3258 @example
3259 #include <gtk/gtk.h>
3260
3261 struct my_gpgme_io_cb
3262 @{
3263   GpgmeIOCb fnc;
3264   void *fnc_data;
3265   guint input_handler_id
3266 @};
3267
3268 void
3269 my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition)
3270 @{
3271   struct my_gpgme_io_cb *iocb = data;
3272   (*(iocb->fnc)) (iocb->data, source);
3273 @}
3274
3275 void
3276 my_gpgme_remove_io_cb (void *data)
3277 @{
3278   struct my_gpgme_io_cb *iocb = data;
3279   gtk_input_remove (data->input_handler_id);
3280 @}
3281
3282 void
3283 my_gpgme_register_io_callback (void *data, int fd, int dir, GpgmeIOCb fnc,
3284                                void *fnc_data, void **tag)
3285 @{
3286   struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb));
3287   iocb->fnc = fnc;
3288   iocb->data = fnc_data;
3289   iocb->input_handler_id = gtk_input_add_full (fd, dir
3290                                                    ? GDK_INPUT_READ
3291                                                    : GDK_INPUT_WRITE,
3292                                                my_gpgme_io_callback,
3293                                                0, iocb, NULL);
3294   *tag = iocb;
3295   return 0;
3296 @}
3297 @end example
3298
3299
3300 @node I/O Callback Example GDK
3301 @subsubsection I/O Callback Example GDK
3302 @cindex GDK, using @acronym{GPGME} with
3303
3304 The I/O callback interface can also be used to integrate
3305 @acronym{GPGME} with the GDK event loop.  The following code snippets
3306 shows how this can be done using the appropriate register and remove
3307 I/O callback functions.  In this example, the private data of the
3308 register I/O callback function is unused.  The event notifications is
3309 missing because it does not require any GDK specific setup.
3310
3311 It is very similar to the GTK+ example in the previous section.
3312
3313 @example
3314 #include <gdk/gdk.h>
3315
3316 struct my_gpgme_io_cb
3317 @{
3318   GpgmeIOCb fnc;
3319   void *fnc_data;
3320   gint tag;
3321 @};
3322
3323 void
3324 my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition)
3325 @{
3326   struct my_gpgme_io_cb *iocb = data;
3327   (*(iocb->fnc)) (iocb->data, source);
3328 @}
3329
3330 void
3331 my_gpgme_remove_io_cb (void *data)
3332 @{
3333   struct my_gpgme_io_cb *iocb = data;
3334   gdk_input_remove (data->tag);
3335 @}
3336
3337 void
3338 my_gpgme_register_io_callback (void *data, int fd, int dir, GpgmeIOCb fnc,
3339                                void *fnc_data, void **tag)
3340 @{
3341   struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb));
3342   iocb->fnc = fnc;
3343   iocb->data = fnc_data;
3344   iocb->tag = gtk_input_add_full (fd, dir ? GDK_INPUT_READ : GDK_INPUT_WRITE,
3345                                   my_gpgme_io_callback, iocb, NULL);
3346   *tag = iocb;
3347   return 0;
3348 @}
3349 @end example
3350
3351
3352 @include gpl.texi
3353
3354
3355 @include fdl.texi
3356
3357
3358 @node Concept Index
3359 @unnumbered Concept Index
3360
3361 @printindex cp
3362
3363
3364 @node Function and Data Index
3365 @unnumbered Function and Data Index
3366
3367 @printindex fn
3368
3369
3370 @summarycontents
3371 @contents
3372 @bye