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