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