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