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