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