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