doc/
[gpgme.git] / doc / gpgme.texi
1 \input texinfo                  @c -*- Texinfo -*-
2 @setfilename gpgme.info
3 @settitle The `GnuPG Made Easy' Reference Manual
4
5 @dircategory GNU Libraries
6 @direntry
7 * @acronym{GPGME}: (gpgme).          Adding support for cryptography to your program.
8 @end direntry
9
10 @include version.texi
11
12 @c Unify some of the indices.
13 @syncodeindex tp fn
14 @syncodeindex pg fn
15
16 @ifinfo
17 This file documents the @acronym{GPGME} library.
18
19 This is Edition @value{EDITION}, last updated @value{UPDATED}, of
20 @cite{The `GnuPG Made Easy' Reference Manual}, for Version
21 @value{VERSION}.
22
23 @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 GPGME_INCLUDE_CERTS_DEFAULT
2032 Fall back to the default of the crypto backend.  This is the default
2033 for GPGME.
2034 @item -2
2035 Include all certificates except the root certificate.
2036 @item -1
2037 Include all certificates.
2038 @item 0
2039 Include no certificates.
2040 @item 1
2041 Include the sender's certificate only.
2042 @item n
2043 Include the first n certificates of the certificates path, starting
2044 from the sender's certificate.  The number @code{n} must be positive.
2045 @end table
2046
2047 Values of @var{nr_of_certs} smaller than -2 are undefined.
2048
2049 This option is only relevant to the CMS crypto engine, and ignored by
2050 all other engines.
2051 @end deftypefun
2052
2053 @deftypefun int gpgme_get_include_certs (@w{gpgme_ctx_t @var{ctx}})
2054 The function @code{gpgme_get_include_certs} returns the number of
2055 certificates to include into an S/MIME signed message.
2056 @end deftypefun
2057
2058
2059 @node Key Listing Mode
2060 @subsection Key Listing Mode
2061 @cindex key listing mode
2062 @cindex key listing, mode of
2063
2064 @deftypefun gpgme_error_t gpgme_set_keylist_mode (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_keylist_mode_t @var{mode}})
2065 The function @code{gpgme_set_keylist_mode} changes the default
2066 behaviour of the key listing functions.  The value in @var{mode} is a
2067 bitwise-or combination of one or multiple of the following bit values:
2068
2069 @table @code
2070 @item GPGME_KEYLIST_MODE_LOCAL
2071 The @code{GPGME_KEYLIST_MODE_LOCAL} symbol specifies that the local
2072 keyring should be searched for keys in the keylisting operation.  This
2073 is the default.
2074
2075 @item GPGME_KEYLIST_MODE_EXTERN
2076 The @code{GPGME_KEYLIST_MODE_EXTERN} symbol specifies that an external
2077 source should be searched for keys in the keylisting
2078 operation.  The type of external source is dependant on the crypto
2079 engine used.  For example, it can be a remote keyserver or LDAP
2080 certificate server.
2081
2082 @item GPGME_KEYLIST_MODE_SIGS
2083 The @code{GPGME_KEYLIST_MODE_SIGS} symbol specifies that the key
2084 signatures should be included in the listed keys.
2085
2086 @item GPGME_KEYLIST_MODE_VALIDATE
2087 The @code{GPGME_KEYLIST_MODE_VALIDATE} symbol specifies that the
2088 backend should do key or certificate validation and not just get the
2089 validity information from an internal cache.  This might be an
2090 expensive operation and is in general not usefule.  Currently only
2091 implemented for the S/MIME backend and ignored for other backends.
2092
2093 @end table
2094
2095 At least one of @code{GPGME_KEYLIST_MODE_LOCAL} and
2096 @code{GPGME_KEYLIST_MODE_EXTERN} must be specified.  For future binary
2097 compatibility, you should get the current mode with
2098 @code{gpgme_get_keylist_mode} and modify it by setting or clearing the
2099 appropriate bits, and then using that calulcated value in the
2100 @code{gpgme_set_keylisting_mode} operation.  This will leave all other
2101 bits in the mode value intact (in particular those that are not used
2102 in the current version of the library).
2103
2104 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
2105 mode could be set correctly, and @code{GPG_ERR_INV_VALUE} if @var{ctx}
2106 is not a valid pointer or @var{mode} is not a valid mode.
2107 @end deftypefun
2108
2109
2110 @deftypefun gpgme_keylist_mode_t gpgme_get_keylist_mode (@w{gpgme_ctx_t @var{ctx}})
2111 The function @code{gpgme_get_keylist_mode} returns the current key
2112 listing mode of the context @var{ctx}.  This value can then be
2113 modified and used in a subsequent @code{gpgme_set_keylist_mode}
2114 operation to only affect the desired bits (and leave all others
2115 intact).
2116
2117 The function returns 0 if @var{ctx} is not a valid pointer, and the
2118 current mode otherwise.  Note that 0 is not a valid mode value.
2119 @end deftypefun
2120
2121
2122 @node Passphrase Callback
2123 @subsection Passphrase Callback
2124 @cindex callback, passphrase
2125 @cindex passphrase callback
2126
2127 @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}})}
2128 @tindex gpgme_passphrase_cb_t
2129 The @code{gpgme_passphrase_cb_t} type is the type of functions usable as
2130 passphrase callback function.
2131
2132 The argument @var{uid_hint} might contain a string that gives an
2133 indication for which user ID the passphrase is required.  If this is
2134 not available, or not applicable (in the case of symmetric encryption,
2135 for example), @var{uid_hint} will be @code{NULL}.
2136
2137 The argument @var{passphrase_info}, if not @code{NULL}, will give
2138 further information about the context in which the passphrase is
2139 required.  This information is engine and operation specific.
2140
2141 If this is the repeated attempt to get the passphrase, because
2142 previous attempts failed, then @var{prev_was_bad} is 1, otherwise it
2143 will be 0.
2144
2145 The user must write the passphrase, followed by a newline character,
2146 to the file descriptor @var{fd}.  If the user does not return 0
2147 indicating success, the user must at least write a newline character
2148 before returning from the callback.
2149
2150 If an error occurs, return the corresponding @code{gpgme_error_t}
2151 value.  You can use the error code @code{GPG_ERR_CANCELED} to abort
2152 the operation.  Otherwise, return @code{0}.
2153 @end deftp
2154
2155 @deftypefun void gpgme_set_passphrase_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_passphrase_cb_t @var{passfunc}}, @w{void *@var{hook_value}})
2156 The function @code{gpgme_set_passphrase_cb} sets the function that is
2157 used when a passphrase needs to be provided by the user to
2158 @var{passfunc}.  The function @var{passfunc} needs to implemented by
2159 the user, and whenever it is called, it is called with its first
2160 argument being @var{hook_value}.  By default, no passphrase callback
2161 function is set.
2162
2163 Not all crypto engines require this callback to retrieve the
2164 passphrase.  It is better if the engine retrieves the passphrase from
2165 a trusted agent (a daemon process), rather than having each user to
2166 implement their own passphrase query.  Some engines do not even
2167 support an external passphrase callback at all, in this case the error
2168 code @code{GPG_ERR_NOT_SUPPORTED} is returned.
2169
2170 The user can disable the use of a passphrase callback function by
2171 calling @code{gpgme_set_passphrase_cb} with @var{passfunc} being
2172 @code{NULL}.
2173 @end deftypefun
2174
2175 @deftypefun void gpgme_get_passphrase_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_passphrase_cb_t *@var{passfunc}}, @w{void **@var{hook_value}})
2176 The function @code{gpgme_get_passphrase_cb} returns the function that
2177 is used when a passphrase needs to be provided by the user in
2178 @var{*passfunc}, and the first argument for this function in
2179 @var{*hook_value}.  If no passphrase callback is set, or @var{ctx} is
2180 not a valid pointer, @code{NULL} is returned in both variables.
2181
2182 @var{passfunc} or @var{hook_value} can be @code{NULL}.  In this case,
2183 the corresponding value will not be returned.
2184 @end deftypefun
2185
2186
2187 @node Progress Meter Callback
2188 @subsection Progress Meter Callback
2189 @cindex callback, progress meter
2190 @cindex progress meter callback
2191
2192 @deftp {Data type} {void (*gpgme_progress_cb_t)(void *@var{hook}, const char *@var{what}, int @var{type}, int @var{current}, int @var{total})}
2193 @tindex gpgme_progress_cb_t
2194 The @code{gpgme_progress_cb_t} type is the type of functions usable as
2195 progress callback function.
2196
2197 The arguments are specific to the crypto engine.  More information
2198 about the progress information returned from the GnuPG engine can be
2199 found in the GnuPG source code in the file @file{doc/DETAILS} in the
2200 section PROGRESS.
2201 @end deftp
2202
2203 @deftypefun void gpgme_set_progress_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_progress_cb_t @var{progfunc}}, @w{void *@var{hook_value}})
2204 The function @code{gpgme_set_progress_cb} sets the function that is
2205 used when progress information about a cryptographic operation is
2206 available.  The function @var{progfunc} needs to implemented by the
2207 user, and whenever it is called, it is called with its first argument
2208 being @var{hook_value}.  By default, no progress callback function
2209 is set.
2210
2211 Setting a callback function allows an interactive program to display
2212 progress information about a long operation to the user.
2213
2214 The user can disable the use of a progress callback function by
2215 calling @code{gpgme_set_progress_cb} with @var{progfunc} being
2216 @code{NULL}.
2217 @end deftypefun
2218
2219 @deftypefun void gpgme_get_progress_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_progress_cb_t *@var{progfunc}}, @w{void **@var{hook_value}})
2220 The function @code{gpgme_get_progress_cb} returns the function that is
2221 used to inform the user about the progress made in @var{*progfunc},
2222 and the first argument for this function in @var{*hook_value}.  If no
2223 progress callback is set, or @var{ctx} is not a valid pointer,
2224 @code{NULL} is returned in both variables.
2225
2226 @var{progfunc} or @var{hook_value} can be @code{NULL}.  In this case,
2227 the corresponding value will not be returned.
2228 @end deftypefun
2229
2230
2231 @node Locale
2232 @subsection Locale
2233 @cindex locale, default
2234 @cindex locale, of a context
2235
2236 A locale setting can be associated with a context.  This locale is
2237 passed to the crypto engine, and used for applications like the PIN
2238 entry, which is displayed to the user when entering a passphrase is
2239 required.
2240
2241 The default locale is used to initialize the locale setting of all
2242 contexts created afterwards.
2243
2244 @deftypefun gpgme_error_t gpgme_set_locale (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{category}}, @w{const char *@var{value}})
2245 The function @code{gpgme_set_locale} sets the locale of the context
2246 @var{ctx}, or the default locale if @var{ctx} is a null pointer.
2247
2248 The locale settings that should be changed are specified by
2249 @var{category}.  Supported categories are @code{LC_CTYPE},
2250 @code{LC_MESSAGES}, and @code{LC_ALL}, which is a wildcard you can use
2251 if you want to change all the categories at once.
2252
2253 The value to be used for the locale setting is @var{value}, which will
2254 be copied to @acronym{GPGME}'s internal data structures.  @var{value}
2255 can be a null pointer, which disables setting the locale, and will
2256 make PIN entry and other applications use their default setting, which
2257 is usually not what you want.
2258
2259 Note that the settings are only used if the application runs on a text
2260 terminal, and that the settings should fit the configuration of the
2261 output terminal.  Normally, it is sufficient to initialize the default
2262 value at startup.
2263
2264 The function returns an error if not enough memory is available.
2265 @end deftypefun
2266
2267
2268 @node Key Management
2269 @section Key Management
2270 @cindex key management
2271
2272 Some of the cryptographic operations require that recipients or
2273 signers are specified.  This is always done by specifying the
2274 respective keys that should be used for the operation.  The following
2275 section describes how such keys can be selected and manipulated.
2276
2277 @deftp {Data type} gpgme_sub_key_t
2278 The @code{gpgme_sub_key_t} type is a pointer to a subkey structure.
2279 Sub keys are one component of a @code{gpgme_key_t} object.  In fact,
2280 subkeys are those parts that contains the real information about the
2281 individual cryptographic keys that belong to the same key object.  One
2282 @code{gpgme_key_t} can contain several subkeys.  The first subkey in
2283 the linked list is also called the primary key.
2284
2285 The subkey structure has the following members:
2286
2287 @table @code
2288 @item gpgme_sub_key_t next
2289 This is a pointer to the next subkey structure in the linked list, or
2290 @code{NULL} if this is the last element.
2291
2292 @item unsigned int revoked : 1
2293 This is true if the subkey is revoked.
2294
2295 @item unsigned int expired : 1
2296 This is true if the subkey is expired.
2297
2298 @item unsigned int disabled : 1
2299 This is true if the subkey is disabled.
2300
2301 @item unsigned int invalid : 1
2302 This is true if the subkey is invalid.
2303
2304 @item unsigned int can_encrypt : 1
2305 This is true if the subkey can be used for encryption.
2306
2307 @item unsigned int can_sign : 1
2308 This is true if the subkey can be used to create data signatures.
2309
2310 @item unsigned int can_certify : 1
2311 This is true if the subkey can be used to create key certificates.
2312
2313 @item unsigned int can_authenticate : 1
2314 This is true if the subkey can be used for authentication.
2315
2316 @item unsigned int is_qualified : 1
2317 This is true if the subkey can be used for qualified signatures
2318 according to local government regulations.
2319
2320 @item unsigned int secret : 1
2321 This is true if the subkey is a secret key.
2322
2323 @item gpgme_pubkey_algo_t pubkey_algo
2324 This is the public key algorithm supported by this subkey.
2325
2326 @item unsigned int length
2327 This is the length of the subkey (in bits).
2328
2329 @item char *keyid
2330 This is the key ID of the subkey in hexadecimal digits.
2331
2332 @item char *fpr
2333 This is the fingerprint of the subkey in hexadecimal digits, if
2334 available.  This is usually only available for the primary key.
2335
2336 @item long int timestamp
2337 This is the creation timestamp of the subkey.  This is -1 if the
2338 timestamp is invalid, and 0 if it is not available.
2339
2340 @item long int expires
2341 This is the expiration timestamp of the subkey, or 0 if the subkey
2342 does not expire.
2343 @end table
2344 @end deftp
2345
2346 @deftp {Data type} gpgme_key_sig_t
2347 The @code{gpgme_key_sig_t} type is a pointer to a key signature structure.
2348 Key signatures are one component of a @code{gpgme_key_t} object, and
2349 validate user IDs on the key.
2350
2351 The signatures on a key are only available if the key was retrieved
2352 via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode
2353 enabled, because it is expensive to retrieve all signatures of a key.
2354
2355 The key signature structure has the following members:
2356
2357 @table @code
2358 @item gpgme_key_sig_t next
2359 This is a pointer to the next key signature structure in the linked
2360 list, or @code{NULL} if this is the last element.
2361
2362 @item unsigned int revoked : 1
2363 This is true if the key signature is a revocation signature.
2364
2365 @item unsigned int expired : 1
2366 This is true if the key signature is expired.
2367
2368 @item unsigned int invalid : 1
2369 This is true if the key signature is invalid.
2370
2371 @item unsigned int exportable : 1
2372 This is true if the key signature is exportable.
2373
2374 @item gpgme_pubkey_algo_t pubkey_algo
2375 This is the public key algorithm used to create the signature.
2376
2377 @item char *keyid
2378 This is the key ID of the key (in hexadecimal digits) used to create
2379 the signature.
2380
2381 @item long int timestamp
2382 This is the creation timestamp of the key signature.  This is -1 if
2383 the timestamp is invalid, and 0 if it is not available.
2384
2385 @item long int expires
2386 This is the expiration timestamp of the key signature, or 0 if the key
2387 signature does not expire.
2388
2389 @item gpgme_error_t status
2390 This is the status of the signature and has the same meaning as the
2391 member of the same name in a @code{gpgme_signature_t} object.
2392
2393 @item unsigned int sig_class
2394 This specifies the signature class of the key signature.  The meaning
2395 is specific to the crypto engine.
2396
2397 @item char *uid
2398 This is the main user ID of the key used to create the signature.
2399
2400 @item char *name
2401 This is the name component of @code{uid}, if available.
2402
2403 @item char *comment
2404 This is the comment component of @code{uid}, if available.
2405
2406 @item char *email
2407 This is the email component of @code{uid}, if available.
2408 @end table
2409 @end deftp
2410
2411 @deftp {Data type} gpgme_user_id_t
2412 A user ID is a component of a @code{gpgme_key_t} object.  One key can
2413 have many user IDs.  The first one in the list is the main (or
2414 primary) user ID.
2415
2416 The user ID structure has the following members.
2417
2418 @table @code
2419 @item gpgme_user_id_t next
2420 This is a pointer to the next user ID structure in the linked list, or
2421 @code{NULL} if this is the last element.
2422
2423 @item unsigned int revoked : 1
2424 This is true if the user ID is revoked.
2425
2426 @item unsigned int invalid : 1
2427 This is true if the user ID is invalid.
2428
2429 @item gpgme_validity_t validity
2430 This specifies the validity of the user ID.
2431
2432 @item char *uid
2433 This is the user ID string.
2434
2435 @item char *name
2436 This is the name component of @code{uid}, if available.
2437
2438 @item char *comment
2439 This is the comment component of @code{uid}, if available.
2440
2441 @item char *email
2442 This is the email component of @code{uid}, if available.
2443
2444 @item gpgme_key_sig_t signatures
2445 This is a linked list with the signatures on this user ID.
2446 @end table
2447 @end deftp
2448
2449 @deftp {Data type} gpgme_key_t
2450 The @code{gpgme_key_t} type is a pointer to a key object.  It has the
2451 following members:
2452
2453 @table @code
2454 @item gpgme_keylist_mode_t keylist_mode
2455 The keylist mode that was active when the key was retrieved.
2456
2457 @item unsigned int revoked : 1
2458 This is true if the key is revoked.
2459
2460 @item unsigned int expired : 1
2461 This is true if the key is expired.
2462
2463 @item unsigned int disabled : 1
2464 This is true if the key is disabled.
2465
2466 @item unsigned int invalid : 1
2467 This is true if the key is invalid. This might have several reasons,
2468 for a example for the S/MIME backend, it will be set in during key
2469 listsing if the key could not be validated due to a missing
2470 certificates or unmatched policies.
2471
2472 @item unsigned int can_encrypt : 1
2473 This is true if the key (ie one of its subkeys) can be used for
2474 encryption.
2475
2476 @item unsigned int can_sign : 1
2477 This is true if the key (ie one of its subkeys) can be used to create
2478 data signatures.
2479
2480 @item unsigned int can_certify : 1
2481 This is true if the key (ie one of its subkeys) can be used to create
2482 key certificates.
2483
2484 @item unsigned int can_authenticate : 1
2485 This is true if the key (ie one of its subkeys) can be used for
2486 authentication.
2487
2488 @item unsigned int is_qualified : 1
2489 This is true if the key can be used for qualified signatures according
2490 to local government regulations.
2491
2492 @item unsigned int secret : 1
2493 This is true if the key is a secret key.
2494
2495 @item gpgme_protocol_t protocol
2496 This is the protocol supported by this key.
2497
2498 @item char *issuer_serial
2499 If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
2500 issuer serial.
2501
2502 @item char *issuer_name
2503 If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
2504 issuer name.
2505
2506 @item char *chain_id
2507 If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
2508 chain ID, which can be used to built the certificate chain.
2509  
2510 @item gpgme_validity_t owner_trust
2511 If @code{protocol} is @code{GPGME_PROTOCOL_OpenPGP}, then this is the
2512 owner trust.
2513
2514 @item gpgme_sub_key_t subkeys
2515 This is a linked list with the subkeys of the key.  The first subkey
2516 in the list is the primary key and usually available.
2517
2518 @item gpgme_user_id_t uids
2519 This is a linked list with the user IDs of the key.  The first user ID
2520 in the list is the main (or primary) user ID.
2521 @end table
2522 @end deftp
2523
2524 @menu
2525 * Listing Keys::                  Browsing the list of available keys.
2526 * Information About Keys::        Requesting detailed information about keys.
2527 * Key Signatures::                Listing the signatures on a key.
2528 * Manipulating Keys::             Operations on keys.
2529 * Generating Keys::               Creating new key pairs.
2530 * Exporting Keys::                Retrieving key data from the key ring.
2531 * Importing Keys::                Adding keys to the key ring.
2532 * Deleting Keys::                 Removing keys from the key ring.
2533 @end menu
2534
2535
2536 @node Listing Keys
2537 @subsection Listing Keys
2538 @cindex listing keys
2539 @cindex key listing
2540 @cindex key listing, start
2541 @cindex key ring, list
2542 @cindex key ring, search
2543
2544 @deftypefun gpgme_error_t gpgme_op_keylist_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}})
2545 The function @code{gpgme_op_keylist_start} initiates a key listing
2546 operation inside the context @var{ctx}.  It sets everything up so that
2547 subsequent invocations of @code{gpgme_op_keylist_next} return the keys
2548 in the list.
2549
2550 If @var{pattern} is @code{NULL}, all available keys are returned.
2551 Otherwise, @var{pattern} contains an engine specific expression that
2552 is used to limit the list to all keys matching the pattern.  Note that
2553 the total length of the pattern is restricted to an engine-specific
2554 maximum (a couple of hundred characters are usually accepted).  The
2555 pattern should be used to restrict the search to a certain common name
2556 or user, not to list many specific keys at once by listing their
2557 fingerprints or key IDs.
2558
2559 If @var{secret_only} is not @code{0}, the list is restricted to secret
2560 keys only.
2561
2562 The context will be busy until either all keys are received (and
2563 @code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}), or
2564 @code{gpgme_op_keylist_end} is called to finish the operation.
2565
2566 The function returns the error code @code{GPG_ERR_INV_VALUE} if
2567 @var{ctx} is not a valid pointer, and passes through any errors that
2568 are reported by the crypto engine support routines.
2569 @end deftypefun
2570
2571 @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}})
2572 The function @code{gpgme_op_keylist_ext_start} initiates an extended
2573 key listing operation inside the context @var{ctx}.  It sets
2574 everything up so that subsequent invocations of
2575 @code{gpgme_op_keylist_next} return the keys in the list.
2576
2577 If @var{pattern} or @var{*pattern} is @code{NULL}, all available keys
2578 are returned.  Otherwise, @var{pattern} is a @code{NULL} terminated
2579 array of strings that are used to limit the list to all keys matching
2580 at least one of the patterns verbatim.  Note that the total length of
2581 all patterns is restricted to an engine-specific maximum (the exact
2582 limit also depends on the number of patterns and amount of quoting
2583 required, but a couple of hundred characters are usually accepted).
2584 Patterns should be used to restrict the search to a certain common
2585 name or user, not to list many specific keys at once by listing their
2586 fingerprints or key IDs.
2587
2588 If @var{secret_only} is not @code{0}, the list is restricted to secret
2589 keys only.
2590
2591 The value of @var{reserved} must be @code{0}.
2592
2593 The context will be busy until either all keys are received (and
2594 @code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}), or
2595 @code{gpgme_op_keylist_end} is called to finish the operation.
2596
2597 The function returns the error code @code{GPG_ERR_INV_VALUE} if
2598 @var{ctx} is not a valid pointer, and passes through any errors that
2599 are reported by the crypto engine support routines.
2600 @end deftypefun
2601
2602 @deftypefun gpgme_error_t gpgme_op_keylist_next (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t *@var{r_key}})
2603 The function @code{gpgme_op_keylist_next} returns the next key in the
2604 list created by a previous @code{gpgme_op_keylist_start} operation in
2605 the context @var{ctx}.  The key will have one reference for the user.
2606 @xref{Manipulating Keys}.
2607
2608 This is the only way to get at @code{gpgme_key_t} objects in
2609 @acronym{GPGME}.
2610
2611 If the last key in the list has already been returned,
2612 @code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}.
2613
2614 The function returns the error code @code{GPG_ERR_INV_VALUE} if
2615 @var{ctx} or @var{r_key} is not a valid pointer, and
2616 @code{GPG_ERR_ENOMEM} if there is not enough memory for the operation.
2617 @end deftypefun
2618
2619 @deftypefun gpgme_error_t gpgme_op_keylist_end (@w{gpgme_ctx_t @var{ctx}})
2620 The function @code{gpgme_op_keylist_next} ends a pending key list
2621 operation in the context @var{ctx}.
2622
2623 After the operation completed successfully, the result of the key
2624 listing operation can be retrieved with
2625 @code{gpgme_op_keylist_result}.
2626
2627 The function returns the error code @code{GPG_ERR_INV_VALUE} if
2628 @var{ctx} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if at some
2629 time during the operation there was not enough memory available.
2630 @end deftypefun
2631
2632 The following example illustrates how all keys containing a certain
2633 string (@code{g10code}) can be listed with their key ID and the name
2634 and e-mail address of the main user ID:
2635
2636 @example
2637 gpgme_ctx_t ctx;
2638 gpgme_error_t err = gpgme_new (&ctx);
2639
2640 if (!err)
2641   @{
2642     err = gpgme_op_keylist_start (ctx, "g10code", 0);
2643     while (!err)
2644       @{
2645         err = gpgme_op_keylist_next (ctx, &key);
2646         if (err)
2647           break;
2648         printf ("%s: %s <%s>\n", key->keyid, key->name, key->email);
2649         gpgme_key_release (key);
2650       @}
2651     gpgme_release (ctx);
2652   @}
2653 if (gpg_err_code (err) != GPG_ERR_EOF)
2654   @{
2655     fprintf (stderr, "%s: can not list keys: %s\n",
2656              argv[0], gpgme_strerror (err));
2657     exit (1);
2658   @}
2659 @end example
2660
2661 @deftp {Data type} {gpgme_keylist_result_t}
2662 This is a pointer to a structure used to store the result of a
2663 @code{gpgme_op_keylist_*} operation.  After successfully ending a key
2664 listing operation, you can retrieve the pointer to the result with
2665 @code{gpgme_op_keylist_result}.  The structure contains the following
2666 member:
2667
2668 @table @code
2669 @item unsigned int truncated : 1
2670 This is true if the crypto backend had to truncate the result, and
2671 less than the desired keys could be listed.
2672 @end table
2673 @end deftp
2674
2675 @deftypefun gpgme_keylist_result_t gpgme_op_keylist_result (@w{gpgme_ctx_t @var{ctx}})
2676 The function @code{gpgme_op_keylist_result} returns a
2677 @code{gpgme_keylist_result_t} pointer to a structure holding the
2678 result of a @code{gpgme_op_keylist_*} operation.  The pointer is only
2679 valid if the last operation on the context was a key listing
2680 operation, and if this operation finished successfully.  The returned
2681 pointer is only valid until the next operation is started on the
2682 context.
2683 @end deftypefun
2684
2685 In a simple program, for which a blocking operation is acceptable, the
2686 following function can be used to retrieve a single key.
2687
2688 @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}})
2689 The function @code{gpgme_get_key} gets the key with the fingerprint
2690 (or key ID) @var{fpr} from the crypto backend and return it in
2691 @var{r_key}.  If @var{secret} is true, get the secret key.  The
2692 currently active keylist mode is used to retrieve the key.  The key
2693 will have one reference for the user.
2694
2695 If the key is not found in the keyring, @code{gpgme_get_key} returns
2696 the error code @code{GPG_ERR_NO_ERROR} and *@var{r_key} will be set to
2697 @code{NULL}.
2698
2699 The function returns the error code @code{GPG_ERR_INV_VALUE} if
2700 @var{ctx} or @var{r_key} is not a valid pointer or @var{fpr} is not a
2701 fingerprint or key ID, @code{GPG_ERR_AMBIGUOUS_NAME} if the key ID was
2702 not a unique specifier for a key, and @code{GPG_ERR_ENOMEM} if at some
2703 time during the operation there was not enough memory available.
2704 @end deftypefun
2705
2706
2707 @node Information About Keys
2708 @subsection Information About Keys
2709 @cindex key, information about
2710 @cindex key, attributes
2711 @cindex attributes, of a key
2712
2713 Please see the beginning of this section for more information about
2714 @code{gpgme_key_t} objects.
2715
2716 @deftp {Data type} gpgme_validity_t
2717 The @code{gpgme_validity_t} type is used to specify the validity of a user ID
2718 in a key.  The following validities are defined:
2719
2720 @table @code
2721 @item GPGME_VALIDITY_UNKNOWN
2722 The user ID is of unknown validity.  The string representation of this
2723 validity is ``?''.
2724
2725 @item GPGME_VALIDITY_UNDEFINED
2726 The validity of the user ID is undefined.  The string representation of this
2727 validity is ``q''.
2728
2729 @item GPGME_VALIDITY_NEVER
2730 The user ID is never valid.  The string representation of this
2731 validity is ``n''.
2732
2733 @item GPGME_VALIDITY_MARGINAL
2734 The user ID is marginally valid.  The string representation of this
2735 validity is ``m''.
2736
2737 @item GPGME_VALIDITY_FULL
2738 The user ID is fully valid.  The string representation of this
2739 validity is ``f''.
2740
2741 @item GPGME_VALIDITY_ULTIMATE
2742 The user ID is ultimately valid.  The string representation of this
2743 validity is ``u''.
2744 @end table
2745 @end deftp
2746
2747
2748 The following interfaces are deprecated and only provided for backward
2749 compatibility.  Don't use them.  They will be removed in a future
2750 version of @acronym{GPGME}.
2751
2752 @deftp {Data type} gpgme_attr_t
2753 The @code{gpgme_attr_t} type is used to specify a key or trust item
2754 attribute.  The following attributes are defined:
2755
2756 @table @code
2757 @item GPGME_ATTR_KEYID
2758 This is the key ID of a sub key.  It is representable as a string.
2759
2760 For trust items, the trust item refers to the key with this ID.
2761
2762 @item GPGME_ATTR_FPR
2763 This is the fingerprint of a sub key.  It is representable as a
2764 string.
2765
2766 @item GPGME_ATTR_ALGO
2767 This is the crypto algorithm for which the sub key can be used.  It
2768 is representable as a string and as a number.  The numbers correspond
2769 to the @code{enum gcry_pk_algos} values in the gcrypt library.
2770
2771 @item GPGME_ATTR_LEN
2772 This is the key length of a sub key.  It is representable as a
2773 number.
2774
2775 @item GPGME_ATTR_CREATED
2776 This is the timestamp at creation time of a sub key.  It is
2777 representable as a number.
2778
2779 @item GPGME_ATTR_EXPIRE
2780 This is the expiration time of a sub key.  It is representable as a
2781 number.
2782
2783 @item GPGME_ATTR_OTRUST
2784 XXX FIXME  (also for trust items)
2785
2786 @item GPGME_ATTR_USERID
2787 This is a user ID.  There can be more than one user IDs in a
2788 @var{gpgme_key_t} object.  The first one (with index 0) is the primary
2789 user ID.  The user ID is representable as a number.
2790
2791 For trust items, this is the user ID associated with this trust item.
2792
2793 @item GPGME_ATTR_NAME
2794 This is the name belonging to a user ID.  It is representable as a string.
2795
2796 @item GPGME_ATTR_EMAIL
2797 This is the email address belonging to a user ID.  It is representable
2798 as a string.
2799
2800 @item GPGME_ATTR_COMMENT
2801 This is the comment belonging to a user ID.  It is representable as a
2802 string.
2803
2804 @item GPGME_ATTR_VALIDITY
2805 This is the validity belonging to a user ID.  It is representable as a
2806 string and as a number.  See below for a list of available validities.
2807
2808 For trust items, this is the validity that is associated with this
2809 trust item.
2810
2811 @item GPGME_ATTR_UID_REVOKED
2812 This specifies if a user ID is revoked.  It is representable as a
2813 number, and is @code{1} if the user ID is revoked, and @code{0}
2814 otherwise.
2815
2816 @item GPGME_ATTR_UID_INVALID
2817 This specifies if a user ID is invalid.  It is representable as a
2818 number, and is @code{1} if the user ID is invalid, and @code{0}
2819 otherwise.
2820
2821 @item GPGME_ATTR_LEVEL
2822 This is the trust level of a trust item.
2823
2824 @item GPGME_ATTR_TYPE
2825 This returns information about the type of key.  For the string function
2826 this will eother be "PGP" or "X.509".  The integer function returns 0
2827 for PGP and 1 for X.509.  It is also used for the type of a trust item.
2828
2829 @item GPGME_ATTR_IS_SECRET
2830 This specifies if the key is a secret key.  It is representable as a
2831 number, and is @code{1} if the key is revoked, and @code{0} otherwise.
2832
2833 @item GPGME_ATTR_KEY_REVOKED
2834 This specifies if a sub key is revoked.  It is representable as a
2835 number, and is @code{1} if the key is revoked, and @code{0} otherwise.
2836
2837 @item GPGME_ATTR_KEY_INVALID
2838 This specifies if a sub key is invalid.  It is representable as a
2839 number, and is @code{1} if the key is invalid, and @code{0} otherwise.
2840
2841 @item GPGME_ATTR_KEY_EXPIRED
2842 This specifies if a sub key is expired.  It is representable as a
2843 number, and is @code{1} if the key is expired, and @code{0} otherwise.
2844
2845 @item GPGME_ATTR_KEY_DISABLED
2846 This specifies if a sub key is disabled.  It is representable as a
2847 number, and is @code{1} if the key is disabled, and @code{0} otherwise.
2848
2849 @item GPGME_ATTR_KEY_CAPS
2850 This is a description of the capabilities of a sub key.  It is
2851 representable as a string.  The string contains the letter ``e'' if
2852 the key can be used for encryption, ``s'' if the key can be used for
2853 signatures, and ``c'' if the key can be used for certifications.
2854
2855 @item GPGME_ATTR_CAN_ENCRYPT
2856 This specifies if a sub key can be used for encryption.  It is
2857 representable as a number, and is @code{1} if the sub key can be used
2858 for encryption, and @code{0} otherwise.
2859
2860 @item GPGME_ATTR_CAN_SIGN
2861 This specifies if a sub key can be used to create data signatures.  It
2862 is representable as a number, and is @code{1} if the sub key can be
2863 used for signatures, and @code{0} otherwise.
2864
2865 @item GPGME_ATTR_CAN_CERTIFY
2866 This specifies if a sub key can be used to create key certificates.
2867 It is representable as a number, and is @code{1} if the sub key can be
2868 used for certifications, and @code{0} otherwise.
2869
2870 @item GPGME_ATTR_SERIAL
2871 The X.509 issuer serial attribute of the key.  It is representable as
2872 a string.
2873
2874 @item GPGME_ATTR_ISSUE
2875 The X.509 issuer name attribute of the key.  It is representable as a
2876 string.
2877
2878 @item GPGME_ATTR_CHAINID
2879 The X.509 chain ID can be used to build the certification chain.  It
2880 is representable as a string.
2881 @end table
2882 @end deftp
2883
2884 @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}})
2885 The function @code{gpgme_key_get_string_attr} returns the value of the
2886 string-representable attribute @var{what} of key @var{key}.  If the
2887 attribute is an attribute of a sub key or an user ID, @var{idx}
2888 specifies the sub key or user ID of which the attribute value is
2889 returned.  The argument @var{reserved} is reserved for later use and
2890 should be @code{NULL}.
2891
2892 The string returned is only valid as long as the key is valid.
2893
2894 The function returns @code{0} if an attribute can't be returned as a
2895 string, @var{key} is not a valid pointer, @var{idx} out of range,
2896 or @var{reserved} not @code{NULL}.
2897 @end deftypefun
2898
2899 @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}})
2900 The function @code{gpgme_key_get_ulong_attr} returns the value of the
2901 number-representable attribute @var{what} of key @var{key}.  If the
2902 attribute is an attribute of a sub key or an user ID, @var{idx}
2903 specifies the sub key or user ID of which the attribute value is
2904 returned.  The argument @var{reserved} is reserved for later use and
2905 should be @code{NULL}.
2906
2907 The function returns @code{0} if the attribute can't be returned as a
2908 number, @var{key} is not a valid pointer, @var{idx} out of range, or
2909 @var{reserved} not @code{NULL}.
2910 @end deftypefun
2911
2912
2913 @node Key Signatures
2914 @subsection Key Signatures
2915 @cindex key, signatures
2916 @cindex signatures, on a key
2917
2918 The following interfaces are deprecated and only provided for backward
2919 compatibility.  Don't use them.  They will be removed in a future
2920 version of @acronym{GPGME}.
2921
2922 The signatures on a key are only available if the key was retrieved
2923 via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode
2924 enabled, because it is expensive to retrieve all signatures of a key.
2925
2926 So, before using the below interfaces to retrieve the signatures on a
2927 key, you have to make sure that the key was listed with signatures
2928 enabled.  One convenient, but blocking, way to do this is to use the
2929 function @code{gpgme_get_key}.
2930
2931 @deftp {Data type} gpgme_attr_t
2932 The @code{gpgme_attr_t} type is used to specify a key signature
2933 attribute.  The following attributes are defined:
2934
2935 @table @code
2936 @item GPGME_ATTR_KEYID
2937 This is the key ID of the key which was used for the signature.  It is
2938 representable as a string.
2939
2940 @item GPGME_ATTR_ALGO
2941 This is the crypto algorithm used to create the signature.  It is
2942 representable as a string and as a number.  The numbers correspond to
2943 the @code{enum gcry_pk_algos} values in the gcrypt library.
2944
2945 @item GPGME_ATTR_CREATED
2946 This is the timestamp at creation time of the signature.  It is
2947 representable as a number.
2948
2949 @item GPGME_ATTR_EXPIRE
2950 This is the expiration time of the signature.  It is representable as
2951 a number.
2952
2953 @item GPGME_ATTR_USERID
2954 This is the user ID associated with the signing key.  The user ID is
2955 representable as a number.
2956
2957 @item GPGME_ATTR_NAME
2958 This is the name belonging to a user ID.  It is representable as a string.
2959
2960 @item GPGME_ATTR_EMAIL
2961 This is the email address belonging to a user ID.  It is representable
2962 as a string.
2963
2964 @item GPGME_ATTR_COMMENT
2965 This is the comment belonging to a user ID.  It is representable as a
2966 string.
2967
2968 @item GPGME_ATTR_KEY_REVOKED
2969 This specifies if a key signature is a revocation signature.  It is
2970 representable as a number, and is @code{1} if the key is revoked, and
2971 @code{0} otherwise.
2972
2973 @c @item GPGME_ATTR_KEY_EXPIRED
2974 @c This specifies if a key signature is expired.  It is representable as
2975 @c a number, and is @code{1} if the key is revoked, and @code{0}
2976 @c otherwise.
2977 @c
2978 @item GPGME_ATTR_SIG_CLASS
2979 This specifies the signature class of a key signature.  It is
2980 representable as a number.  The meaning is specific to the crypto
2981 engine.
2982
2983 @item GPGME_ATTR_SIG_CLASS
2984 This specifies the signature class of a key signature.  It is
2985 representable as a number.  The meaning is specific to the crypto
2986 engine.
2987
2988 @item GPGME_ATTR_SIG_STATUS
2989 This is the same value as returned by @code{gpgme_get_sig_status}.
2990 @end table
2991 @end deftp
2992
2993 @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}})
2994 The function @code{gpgme_key_sig_get_string_attr} returns the value of
2995 the string-representable attribute @var{what} of the signature
2996 @var{idx} on the user ID @var{uid_idx} in the key @var{key}.  The
2997 argument @var{reserved} is reserved for later use and should be
2998 @code{NULL}.
2999
3000 The string returned is only valid as long as the key is valid.
3001
3002 The function returns @code{0} if an attribute can't be returned as a
3003 string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx}
3004 out of range, or @var{reserved} not @code{NULL}.
3005 @end deftypefun
3006
3007 @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}})
3008 The function @code{gpgme_key_sig_get_ulong_attr} returns the value of
3009 the number-representable attribute @var{what} of the signature
3010 @var{idx} on the user ID @var{uid_idx} in the key @var{key}.  The
3011 argument @var{reserved} is reserved for later use and should be
3012 @code{NULL}.
3013
3014 The function returns @code{0} if an attribute can't be returned as a
3015 string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx}
3016 out of range, or @var{reserved} not @code{NULL}.
3017 @end deftypefun
3018
3019
3020 @node Manipulating Keys
3021 @subsection Manipulating Keys
3022 @cindex key, manipulation
3023
3024 @deftypefun void gpgme_key_ref (@w{gpgme_key_t @var{key}})
3025 The function @code{gpgme_key_ref} acquires an additional reference for
3026 the key @var{key}.
3027 @end deftypefun
3028
3029 @deftypefun void gpgme_key_unref (@w{gpgme_key_t @var{key}})
3030 The function @code{gpgme_key_unref} releases a reference for the key
3031 @var{key}.  If this was the last reference, the key will be destroyed
3032 and all resources associated to it will be released.
3033 @end deftypefun
3034
3035
3036 The following interface is deprecated and only provided for backward
3037 compatibility.  Don't use it.  It will be removed in a future version
3038 of @acronym{GPGME}.
3039
3040 @deftypefun void gpgme_key_release (@w{gpgme_key_t @var{key}})
3041 The function @code{gpgme_key_release} is equivalent to
3042 @code{gpgme_key_unref}.
3043 @end deftypefun
3044
3045
3046 @node Generating Keys
3047 @subsection Generating Keys
3048 @cindex key, creation
3049 @cindex key ring, add
3050
3051 @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}})
3052 The function @code{gpgme_op_genkey} generates a new key pair in the
3053 context @var{ctx}.  The meaning of @var{public} and @var{secret}
3054 depends on the crypto backend.
3055
3056 GnuPG does not support @var{public} and @var{secret}, they should be
3057 @code{NULL}.  GnuPG will generate a key pair and add it to the
3058 standard key ring.  The fingerprint of the generated key is available
3059 with @code{gpgme_op_genkey_result}.
3060
3061 GpgSM requires @var{public} to be a writable data object.  GpgSM will
3062 generate a secret key (which will be stored by @command{gpg-agent},
3063 and return a certificate request in @var{public}, which then needs to
3064 be signed by the certification authority and imported before it can be
3065 used.  GpgSM does not make the fingerprint available.
3066
3067 The argument @var{parms} specifies parameters for the key in an XML
3068 string.  The details about the format of @var{parms} are specific to
3069 the crypto engine used by @var{ctx}.  Here is an example for GnuPG as
3070 the crypto engine:
3071
3072 @example
3073 <GnupgKeyParms format="internal">
3074 Key-Type: DSA
3075 Key-Length: 1024
3076 Subkey-Type: ELG-E
3077 Subkey-Length: 1024
3078 Name-Real: Joe Tester
3079 Name-Comment: with stupid passphrase
3080 Name-Email: joe@@foo.bar
3081 Expire-Date: 0
3082 Passphrase: abc
3083 </GnupgKeyParms>
3084 @end example
3085
3086 Here is an example for GpgSM as the crypto engine:
3087
3088 @example
3089 <GnupgKeyParms format="internal">
3090 Key-Type: RSA
3091 Key-Length: 1024
3092 Name-DN: C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester
3093 Name-Email: joe@@foo.bar
3094 </GnupgKeyParms>
3095 @end example
3096
3097 Strings should be given in UTF-8 encoding.  The only format supported
3098 for now is ``internal''.  The content of the @code{GnupgKeyParms}
3099 container is passed verbatim to the crypto backend.  Control
3100 statements are not allowed.
3101
3102 After the operation completed successfully, the result can be
3103 retrieved with @code{gpgme_op_genkey_result}.
3104
3105 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3106 operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
3107 @var{parms} is not a valid XML string, @code{GPG_ERR_NOT_SUPPORTED} if
3108 @var{public} or @var{secret} is not valid, and @code{GPG_ERR_GENERAL}
3109 if no key was created by the backend.
3110 @end deftypefun
3111
3112 @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}})
3113 The function @code{gpgme_op_genkey_start} initiates a
3114 @code{gpgme_op_genkey} operation.  It can be completed by calling
3115 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
3116
3117 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3118 operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
3119 @var{parms} is not a valid XML string, and
3120 @code{GPG_ERR_NOT_SUPPORTED} if @var{public} or @var{secret} is not
3121 @code{NULL}.
3122 @end deftypefun
3123
3124 @deftp {Data type} {gpgme_genkey_result_t}
3125 This is a pointer to a structure used to store the result of a
3126 @code{gpgme_op_genkey} operation.  After successfully generating a
3127 key, you can retrieve the pointer to the result with
3128 @code{gpgme_op_genkey_result}.  The structure contains the following
3129 members:
3130
3131 @table @code
3132 @item unsigned int primary : 1
3133 This is a flag that is set to 1 if a primary key was created and to 0
3134 if not.
3135
3136 @item unsigned int sub : 1
3137 This is a flag that is set to 1 if a subkey was created and to 0
3138 if not.
3139
3140 @item char *fpr
3141 This is the fingerprint of the key that was created.  If both a
3142 primary and a sub key were generated, the fingerprint of the primary
3143 key will be returned.  If the crypto engine does not provide the
3144 fingerprint, @code{fpr} will be a null pointer.
3145 @end table
3146 @end deftp
3147
3148 @deftypefun gpgme_genkey_result_t gpgme_op_genkey_result (@w{gpgme_ctx_t @var{ctx}})
3149 The function @code{gpgme_op_genkey_result} returns a
3150 @code{gpgme_genkey_result_t} pointer to a structure holding the result of
3151 a @code{gpgme_op_genkey} operation.  The pointer is only valid if the
3152 last operation on the context was a @code{gpgme_op_genkey} or
3153 @code{gpgme_op_genkey_start} operation, and if this operation finished
3154 successfully.  The returned pointer is only valid until the next
3155 operation is started on the context.
3156 @end deftypefun
3157
3158
3159 @node Exporting Keys
3160 @subsection Exporting Keys
3161 @cindex key, export
3162 @cindex key ring, export from
3163
3164 @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}})
3165 The function @code{gpgme_op_export} extracts public keys and returns
3166 them in the data buffer @var{keydata}.  The output format of the key
3167 data returned is determined by the @acronym{ASCII} armor attribute set
3168 for the context @var{ctx}.
3169
3170 If @var{pattern} is @code{NULL}, all available keys are returned.
3171 Otherwise, @var{pattern} contains an engine specific expression that
3172 is used to limit the list to all keys matching the pattern.
3173
3174 @var{reserved} is reserved for future use and must be @code{0}.
3175
3176 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3177 operation completed successfully, @code{GPG_ERR_INV_VALUE} if
3178 @var{keydata} is not a valid empty data buffer, and passes through any
3179 errors that are reported by the crypto engine support routines.
3180 @end deftypefun
3181
3182 @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}})
3183 The function @code{gpgme_op_export_start} initiates a
3184 @code{gpgme_op_export} operation.  It can be completed by calling
3185 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
3186
3187 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3188 operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
3189 if @var{keydata} is not a valid empty data buffer.
3190 @end deftypefun
3191
3192 @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}})
3193 The function @code{gpgme_op_export} extracts public keys and returns
3194 them in the data buffer @var{keydata}.  The output format of the key
3195 data returned is determined by the @acronym{ASCII} armor attribute set
3196 for the context @var{ctx}.
3197
3198 If @var{pattern} or @var{*pattern} is @code{NULL}, all available keys
3199 are returned.  Otherwise, @var{pattern} is a @code{NULL} terminated
3200 array of strings that are used to limit the list to all keys matching
3201 at least one of the patterns verbatim.
3202
3203 @var{reserved} is reserved for future use and must be @code{0}.
3204
3205 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3206 operation completed successfully, @code{GPG_ERR_INV_VALUE} if
3207 @var{keydata} is not a valid empty data buffer, and passes through any
3208 errors that are reported by the crypto engine support routines.
3209 @end deftypefun
3210
3211 @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}})
3212 The function @code{gpgme_op_export_ext_start} initiates a
3213 @code{gpgme_op_export_ext} operation.  It can be completed by calling
3214 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
3215
3216 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3217 operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
3218 if @var{keydata} is not a valid empty data buffer.
3219 @end deftypefun
3220
3221
3222 @node Importing Keys
3223 @subsection Importing Keys
3224 @cindex key, import
3225 @cindex key ring, import to
3226
3227 @deftypefun gpgme_error_t gpgme_op_import (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}})
3228 The function @code{gpgme_op_import} adds the keys in the data buffer
3229 @var{keydata} to the key ring of the crypto engine used by @var{ctx}.
3230 The format of @var{keydata} can be @acronym{ASCII} armored, for example,
3231 but the details are specific to the crypto engine.
3232
3233 After the operation completed successfully, the result can be
3234 retrieved with @code{gpgme_op_import_result}.
3235
3236 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3237 import was completed 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 @deftypefun gpgme_error_t gpgme_op_import_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}})
3243 The function @code{gpgme_op_import_start} initiates a
3244 @code{gpgme_op_import} operation.  It can be completed by calling
3245 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
3246
3247 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3248 import could be started successfully, @code{GPG_ERR_INV_VALUE} if
3249 @var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer,
3250 and @code{GPG_ERR_NO_DATA} if @var{keydata} is an empty data buffer.
3251 @end deftypefun
3252
3253 @deftp {Data type} {gpgme_import_status_t}
3254 This is a pointer to a structure used to store a part of the result of
3255 a @code{gpgme_op_import} operation.  For each considered key one
3256 status is added that contains information about the result of the
3257 import.  The structure contains the following members:
3258
3259 @table @code
3260 @item gpgme_import_status_t next
3261 This is a pointer to the next status structure in the linked list, or
3262 @code{NULL} if this is the last element.
3263
3264 @item char *fpr
3265 This is the fingerprint of the key that was considered.
3266
3267 @item gpgme_error_t result
3268 If the import was not successful, this is the error value that caused
3269 the import to fail.  Otherwise the error code is
3270 @code{GPG_ERR_NO_ERROR}.
3271
3272 @item unsigned int status
3273 This is a bit-wise OR of the following flags that give more
3274 information about what part of the key was imported.  If the key was
3275 already known, this might be 0.
3276
3277 @table @code
3278 @item GPGME_IMPORT_NEW
3279 The key was new.
3280
3281 @item GPGME_IMPORT_UID
3282 The key contained new user IDs.
3283
3284 @item GPGME_IMPORT_SIG
3285 The key contained new signatures.
3286
3287 @item GPGME_IMPORT_SUBKEY
3288 The key contained new sub keys.
3289
3290 @item GPGME_IMPORT_SECRET
3291 The key contained a secret key.
3292 @end table
3293 @end table
3294 @end deftp
3295
3296 @deftp {Data type} {gpgme_import_result_t}
3297 This is a pointer to a structure used to store the result of a
3298 @code{gpgme_op_import} operation.  After a successful import
3299 operation, you can retrieve the pointer to the result with
3300 @code{gpgme_op_import_result}.  The structure contains the following
3301 members:
3302
3303 @table @code
3304 @item int considered
3305 The total number of considered keys.
3306
3307 @item int no_user_id
3308 The number of keys without user ID.
3309
3310 @item int imported
3311 The total number of imported keys.
3312
3313 @item imported_rsa
3314 The number of imported RSA keys.
3315
3316 @item unchanged
3317 The number of unchanged keys.
3318
3319 @item new_user_ids
3320 The number of new user IDs.
3321
3322 @item new_sub_keys
3323 The number of new sub keys.
3324
3325 @item new_signatures
3326 The number of new signatures.
3327
3328 @item new_revocations
3329 The number of new revocations.
3330
3331 @item secret_read
3332 The total number of secret keys read.
3333
3334 @item secret_imported
3335 The number of imported secret keys.
3336
3337 @item secret_unchanged
3338 The number of unchanged secret keys.
3339
3340 @item not_imported
3341 The number of keys not imported.
3342
3343 @item gpgme_import_status_t imports
3344 A list of gpgme_import_status_t objects which contain more information
3345 about the keys for which an import was attempted.
3346 @end table
3347 @end deftp
3348
3349 @deftypefun gpgme_import_result_t gpgme_op_import_result (@w{gpgme_ctx_t @var{ctx}})
3350 The function @code{gpgme_op_import_result} returns a
3351 @code{gpgme_import_result_t} pointer to a structure holding the result
3352 of a @code{gpgme_op_import} operation.  The pointer is only valid if
3353 the last operation on the context was a @code{gpgme_op_import} or
3354 @code{gpgme_op_import_start} operation, and if this operation finished
3355 successfully.  The returned pointer is only valid until the next
3356 operation is started on the context.
3357 @end deftypefun
3358
3359 The following interface is deprecated and only provided for backward
3360 compatibility.  Don't use it.  It will be removed in a future version
3361 of @acronym{GPGME}.
3362
3363 @deftypefun gpgme_error_t gpgme_op_import_ext (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}}, @w{int *@var{nr}})
3364 The function @code{gpgme_op_import_ext} is equivalent to:
3365
3366 @example
3367   gpgme_error_t err = gpgme_op_import (ctx, keydata);
3368   if (!err)
3369     @{
3370       gpgme_import_result_t result = gpgme_op_import_result (ctx);
3371       *nr = result->considered;
3372     @}
3373 @end example
3374 @end deftypefun
3375
3376
3377 @node Deleting Keys
3378 @subsection Deleting Keys
3379 @cindex key, delete
3380 @cindex key ring, delete from
3381
3382 @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}})
3383 The function @code{gpgme_op_delete} deletes the key @var{key} from the
3384 key ring of the crypto engine used by @var{ctx}.  If
3385 @var{allow_secret} is @code{0}, only public keys are deleted,
3386 otherwise secret keys are deleted as well, if that is supported.
3387
3388 The function returns the error code @code{GPG_ERR_NO_ERROR} if the key
3389 was deleted successfully, @code{GPG_ERR_INV_VALUE} if @var{ctx} or
3390 @var{key} is not a valid pointer, @code{GPG_ERR_NO_PUBKEY} if
3391 @var{key} could not be found in the keyring,
3392 @code{GPG_ERR_AMBIGUOUS_NAME} if the key was not specified
3393 unambiguously, and @code{GPG_ERR_CONFLICT} if the secret key for
3394 @var{key} is available, but @var{allow_secret} is zero.
3395 @end deftypefun
3396
3397 @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}})
3398 The function @code{gpgme_op_delete_start} initiates a
3399 @code{gpgme_op_delete} operation.  It can be completed by calling
3400 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
3401
3402 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3403 operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
3404 @var{ctx} or @var{key} is not a valid pointer.
3405 @end deftypefun
3406
3407
3408 @node Trust Item Management
3409 @section Trust Item Management
3410 @cindex trust item
3411
3412 @strong{Caution:} The trust items interface is experimental.
3413
3414 @deftp {Data type} gpgme_trust_item_t
3415 The @code{gpgme_trust_item_t} type is a pointer to a trust item object.
3416 It has the following members:
3417
3418 @table @code
3419 @item char *keyid
3420 This is a string describing the key to which this trust items belongs.
3421
3422 @item int type
3423 This is the type of the trust item.  A value of 1 refers to a key, a
3424 value of 2 refers to a user ID.
3425
3426 @item int level
3427 This is the trust level.
3428
3429 @item char *owner_trust
3430 The owner trust if @code{type} is 1.
3431
3432 @item char *validity
3433 The calculated validity.
3434
3435 @item char *name
3436 The user name if @code{type} is 2.
3437 @end table
3438 @end deftp
3439
3440 @menu
3441 * Listing Trust Items::           Browsing the list of available trust items.
3442 * Information About Trust Items:: Requesting information about trust items.
3443 * Manipulating Trust Items::      Operations on trust items.
3444 @end menu
3445
3446
3447 @node Listing Trust Items
3448 @subsection Listing Trust Items
3449 @cindex trust item list
3450
3451 @deftypefun gpgme_error_t gpgme_op_trustlist_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{max_level}})
3452 The function @code{gpgme_op_trustlist_start} initiates a trust item
3453 listing operation inside the context @var{ctx}.  It sets everything up
3454 so that subsequent invocations of @code{gpgme_op_trustlist_next} return
3455 the trust items in the list.
3456
3457 The string @var{pattern} contains an engine specific expression that
3458 is used to limit the list to all trust items matching the pattern.  It
3459 can not be the empty string.
3460
3461 The argument @var{max_level} is currently ignored.
3462
3463 The context will be busy until either all trust items are received
3464 (and @code{gpgme_op_trustlist_next} returns @code{GPG_ERR_EOF}), or
3465 @code{gpgme_op_trustlist_end} is called to finish the operation.
3466
3467 The function returns the error code @code{GPG_ERR_INV_VALUE} if
3468 @var{ctx} is not a valid pointer, and passes through any errors that
3469 are reported by the crypto engine support routines.
3470 @end deftypefun
3471
3472 @deftypefun gpgme_error_t gpgme_op_trustlist_next (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_trust_item_t *@var{r_item}})
3473 The function @code{gpgme_op_trustlist_next} returns the next trust
3474 item in the list created by a previous @code{gpgme_op_trustlist_start}
3475 operation in the context @var{ctx}.  The trust item can be destroyed
3476 with @code{gpgme_trust_item_release}.  @xref{Manipulating Trust Items}.
3477
3478 This is the only way to get at @code{gpgme_trust_item_t} objects in
3479 @acronym{GPGME}.
3480
3481 If the last trust item in the list has already been returned,
3482 @code{gpgme_op_trustlist_next} returns @code{GPG_ERR_EOF}.
3483
3484 The function returns the error code @code{GPG_ERR_INV_VALUE} if @var{ctx} or
3485 @var{r_item} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if
3486 there is not enough memory for the operation.
3487 @end deftypefun
3488
3489 @deftypefun gpgme_error_t gpgme_op_trustlist_end (@w{gpgme_ctx_t @var{ctx}})
3490 The function @code{gpgme_op_trustlist_next} ends a pending key list
3491 operation in the context @var{ctx}.
3492
3493 The function returns the error code @code{GPG_ERR_INV_VALUE} if
3494 @var{ctx} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if at some
3495 time during the operation there was not enough memory available.
3496 @end deftypefun
3497
3498
3499 @node Information About Trust Items
3500 @subsection Information About Trust Items
3501 @cindex trust item, information about
3502 @cindex trust item, attributes
3503 @cindex attributes, of a trust item
3504
3505 The following interfaces are deprecated and only provided for backward
3506 compatibility.  Don't use them.  They will be removed in a future
3507 version of @acronym{GPGME}.
3508
3509 Trust items have attributes which can be queried using the interfaces
3510 below.  The attribute identifiers are shared with those for key
3511 attributes.  @xref{Information About Keys}.
3512
3513 @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}})
3514 The function @code{gpgme_trust_item_get_string_attr} returns the value
3515 of the string-representable attribute @var{what} of trust item
3516 @var{item}.  The arguments @var{idx} and @var{reserved} are reserved
3517 for later use and should be @code{0} and @code{NULL} respectively.
3518
3519 The string returned is only valid as long as the key is valid.
3520
3521 The function returns @code{0} if an attribute can't be returned as a
3522 string, @var{key} is not a valid pointer, @var{idx} out of range,
3523 or @var{reserved} not @code{NULL}.
3524 @end deftypefun
3525
3526 @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}})
3527 The function @code{gpgme_trust_item_get_int_attr} returns the value of
3528 the number-representable attribute @var{what} of trust item
3529 @var{item}.  If the attribute occurs more than once in the trust item,
3530 the index is specified by @var{idx}.  However, currently no such
3531 attribute exists, so @var{idx} should be @code{0}.  The argument
3532 @var{reserved} is reserved for later use and should be @code{NULL}.
3533
3534 The function returns @code{0} if the attribute can't be returned as a
3535 number, @var{key} is not a valid pointer, @var{idx} out of range,
3536 or @var{reserved} not @code{NULL}.
3537 @end deftypefun
3538
3539
3540 @node Manipulating Trust Items
3541 @subsection Manipulating Trust Items
3542 @cindex trust item, manipulation
3543
3544 @deftypefun void gpgme_trust_item_ref (@w{gpgme_trust_item_t @var{item}})
3545 The function @code{gpgme_trust_item_ref} acquires an additional
3546 reference for the trust item @var{item}.
3547 @end deftypefun
3548
3549 @deftypefun void gpgme_trust_item_unref (@w{gpgme_trust_item_t @var{item}})
3550 The function @code{gpgme_trust_item_unref} releases a reference for
3551 the trust item @var{item}.  If this was the last reference, the trust
3552 item will be destroyed and all resources associated to it will be
3553 released.
3554 @end deftypefun
3555
3556
3557 The following interface is deprecated and only provided for backward
3558 compatibility.  Don't use it.  It will be removed in a future version
3559 of @acronym{GPGME}.
3560
3561 @deftypefun void gpgme_trust_item_release (@w{gpgme_trust_item_t @var{item}})
3562 The function @code{gpgme_trust_item_release} is an alias for
3563 @code{gpgme_trust_item_unref}.
3564 @end deftypefun
3565
3566
3567 @node Crypto Operations
3568 @section Crypto Operations
3569 @cindex cryptographic operation
3570
3571 Sometimes, the result of a crypto operation returns a list of invalid
3572 keys encountered in processing the request.  The following structure
3573 is used to hold information about such a key.
3574
3575 @deftp {Data type} {gpgme_invalid_key_t}
3576 This is a pointer to a structure used to store a part of the result of
3577 a crypto operation which takes user IDs as one input parameter.  The
3578 structure contains the following members:
3579
3580 @table @code
3581 @item gpgme_invalid_key_t next
3582 This is a pointer to the next invalid key structure in the linked
3583 list, or @code{NULL} if this is the last element.
3584
3585 @item char *fpr
3586 The fingerprint or key ID of the invalid key encountered.
3587
3588 @item gpgme_error_t reason
3589 An error code describing the reason why the key was found invalid.
3590 @end table
3591 @end deftp
3592
3593
3594 @menu
3595 * Decrypt::                       Decrypting a ciphertext.
3596 * Verify::                        Verifying a signature.
3597 * Decrypt and Verify::            Decrypting a signed ciphertext.
3598 * Sign::                          Creating a signature.
3599 * Encrypt::                       Encrypting a plaintext.
3600 @end menu
3601
3602
3603 @node Decrypt
3604 @subsection Decrypt
3605 @cindex decryption
3606 @cindex cryptographic operation, decryption
3607
3608 @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}})
3609 The function @code{gpgme_op_decrypt} decrypts the ciphertext in the
3610 data object @var{cipher} and stores it into the data object
3611 @var{plain}.
3612
3613 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3614 ciphertext could be decrypted successfully, @code{GPG_ERR_INV_VALUE}
3615 if @var{ctx}, @var{cipher} or @var{plain} is not a valid pointer,
3616 @code{GPG_ERR_NO_DATA} if @var{cipher} does not contain any data to
3617 decrypt, @code{GPG_ERR_DECRYPT_FAILED} if @var{cipher} is not a valid
3618 cipher text, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the
3619 secret key could not be retrieved, and passes through any errors that
3620 are reported by the crypto engine support routines.
3621 @end deftypefun
3622
3623 @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}})
3624 The function @code{gpgme_op_decrypt_start} initiates a
3625 @code{gpgme_op_decrypt} operation.  It can be completed by calling
3626 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
3627
3628 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3629 operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
3630 if @var{cipher} or @var{plain} is not a valid pointer.
3631 @end deftypefun
3632
3633 @deftp {Data type} {gpgme_recipient_t}
3634 This is a pointer to a structure used to store information about the
3635 recipient of an encrypted text which is decrypted in a
3636 @code{gpgme_op_decrypt} operation.  This information (except for the
3637 status field) is even available before the operation finished
3638 successfully, for example in a passphrase callback.  The structure
3639 contains the following members:
3640
3641 @table @code
3642 @item gpgme_recipient_t next
3643 This is a pointer to the next recipient structure in the linked list,
3644 or @code{NULL} if this is the last element.
3645
3646 @item gpgme_pubkey_algo_t
3647 The public key algorithm used in the encryption.
3648
3649 @item unsigned int wrong_key_usage : 1
3650 This is true if the key was not used according to its policy.
3651
3652 @item char *keyid
3653 This is the key ID of the key (in hexadecimal digits) used as
3654 recipient.
3655
3656 @item gpgme_error_t status
3657 This is an error number with the error code GPG_ERR_NO_SECKEY if the
3658 secret key for this recipient is not available, and 0 otherwise.
3659 @end table
3660 @end deftp
3661
3662 @deftp {Data type} {gpgme_decrypt_result_t}
3663 This is a pointer to a structure used to store the result of a
3664 @code{gpgme_op_decrypt} operation.  After successfully decrypting
3665 data, you can retrieve the pointer to the result with
3666 @code{gpgme_op_decrypt_result}.  The structure contains the following
3667 members:
3668
3669 @table @code
3670 @item char *unsupported_algorithm
3671 If an unsupported algorithm was encountered, this string describes the
3672 algorithm that is not supported.
3673
3674 @item unsigned int wrong_key_usage : 1
3675 This is true if the key was not used according to its policy.
3676
3677 @item gpgme_recipient_t recipient
3678 This is a linked list of recipients to which this message was encrypted.
3679
3680 @item char *file_name
3681 This is the filename of the original plaintext message file if it is
3682 known, otherwise this is a null pointer.
3683 @end table
3684 @end deftp
3685
3686 @deftypefun gpgme_decrypt_result_t gpgme_op_decrypt_result (@w{gpgme_ctx_t @var{ctx}})
3687 The function @code{gpgme_op_decrypt_result} returns a
3688 @code{gpgme_decrypt_result_t} pointer to a structure holding the
3689 result of a @code{gpgme_op_decrypt} operation.  The pointer is only
3690 valid if the last operation on the context was a
3691 @code{gpgme_op_decrypt} or @code{gpgme_op_decrypt_start} operation.
3692 If the operation failed this might be a @code{NULL} pointer.  The
3693 returned pointer is only valid until the next operation is started on
3694 the context.
3695 @end deftypefun
3696
3697
3698 @node Verify
3699 @subsection Verify
3700 @cindex verification
3701 @cindex signature, verification
3702 @cindex cryptographic operation, verification
3703 @cindex cryptographic operation, signature check
3704
3705 @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}})
3706 The function @code{gpgme_op_verify} verifies that the signature in the
3707 data object @var{sig} is a valid signature.  If @var{sig} is a
3708 detached signature, then the signed text should be provided in
3709 @var{signed_text} and @var{plain} should be a null pointer.
3710 Otherwise, if @var{sig} is a normal (or cleartext) signature,
3711 @var{signed_text} should be a null pointer and @var{plain} should be a
3712 writable data object that will contain the plaintext after successful
3713 verification.
3714
3715 The results of the individual signature verifications can be retrieved
3716 with @code{gpgme_op_verify_result}.
3717
3718 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3719 operation could be completed successfully, @code{GPG_ERR_INV_VALUE} if
3720 @var{ctx}, @var{sig} or @var{plain} is not a valid pointer,
3721 @code{GPG_ERR_NO_DATA} if @var{sig} does not contain any data to
3722 verify, and passes through any errors that are reported by the crypto
3723 engine support routines.
3724 @end deftypefun
3725
3726 @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}})
3727 The function @code{gpgme_op_verify_start} initiates a
3728 @code{gpgme_op_verify} operation.  It can be completed by calling
3729 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
3730
3731 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3732 operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
3733 @var{ctx}, @var{sig} or @var{plain} is not a valid pointer, and
3734 @code{GPG_ERR_NO_DATA} if @var{sig} or @var{plain} does not contain
3735 any data to verify.
3736 @end deftypefun
3737
3738 @deftp {Data type} {gpgme_sig_notation_t}
3739 This is a pointer to a structure used to store a part of the result of
3740 a @code{gpgme_op_verify} operation.  The structure contains the
3741 following members:
3742
3743 @table @code
3744 @item gpgme_sig_notation_t next
3745 This is a pointer to the next new signature notation structure in the
3746 linked list, or @code{NULL} if this is the last element.
3747
3748 @item char *name
3749 The name of the notation field.  If this is @code{NULL}, then the
3750 member @code{value} will contain a policy URL.
3751
3752 @item char *value
3753 The value of the notation field.  If @code{name} is @code{NULL}, then
3754 this is a policy URL.
3755 @end table
3756 @end deftp
3757
3758 @deftp {Data type} {gpgme_signature_t}
3759 This is a pointer to a structure used to store a part of the result of
3760 a @code{gpgme_op_verify} operation.  The structure contains the
3761 following members:
3762
3763 @table @code
3764 @item gpgme_signature_t next
3765 This is a pointer to the next new signature structure in the linked
3766 list, or @code{NULL} if this is the last element.
3767
3768 @item gpgme_sigsum_t summary
3769 This is a bit vector giving a summary of the signature status.  It
3770 provides an easy interface to a defined semantic of the signature
3771 status.  Checking just one bit is sufficient to see whether a
3772 signature is valid without any restrictions.
3773
3774 The defined bits are:
3775   @table @code
3776   @item GPGME_SIGSUM_VALID
3777   The signature is fully valid.
3778
3779   @item GPGME_SIGSUM_GREEN
3780   The signature is good but one might want to display some extra
3781   information.  Check the other bits.
3782
3783   @item GPGME_SIGSUM_RED
3784   The signature is bad. It might be useful to check other bits and
3785   display more information, i.e. a revoked certificate might not render a
3786   signature invalid when the message was received prior to the cause for
3787   the revocation.
3788
3789   @item GPGME_SIGSUM_KEY_REVOKED
3790   The key or at least one certificate has been revoked.
3791
3792   @item GPGME_SIGSUM_KEY_EXPIRED
3793   The key or one of the certificates has expired. It is probably a good
3794   idea to display the date of the expiration.
3795
3796   @item GPGME_SIGSUM_SIG_EXPIRED
3797   The signature has expired.
3798
3799   @item GPGME_SIGSUM_KEY_MISSING
3800   Can't verify due to a missing key or certificate.
3801
3802   @item GPGME_SIGSUM_CRL_MISSING
3803   The CRL (or an equivalent mechanism) is not available. 
3804
3805   @item GPGME_SIGSUM_CRL_TOO_OLD
3806   Available CRL is too old.
3807
3808   @item GPGME_SIGSUM_BAD_POLICY
3809   A policy requirement was not met. 
3810
3811   @item GPGME_SIGSUM_SYS_ERROR
3812   A system error occured. 
3813   @end table
3814
3815 @item char *fpr
3816 This is the fingerprint or key ID of the signature.
3817
3818 @item gpgme_error_t status
3819 This is the status of the signature.  In particular, the following
3820 status codes are of interest:
3821
3822   @table @code
3823   @item GPG_ERR_NO_ERROR
3824   This status indicates that the signature is valid.  For the combined
3825   result this status means that all signatures are valid.
3826
3827   @item GPG_ERR_SIG_EXPIRED
3828   This status indicates that the signature is valid but expired.  For
3829   the combined result this status means that all signatures are valid
3830   and expired.
3831
3832   @item GPG_ERR_KEY_EXPIRED
3833   This status indicates that the signature is valid but the key used to
3834   verify the signature has expired.  For the combined result this status
3835   means that all signatures are valid and all keys are expired.
3836
3837   @item GPG_ERR_CERT_REVOKED
3838   This status indicates that the signature is valid but the key used
3839   to verify the signature has been revoked.  For the combined result
3840   this status means that all signatures are valid and all keys are
3841   revoked.
3842
3843   @item GPG_ERR_BAD_SIGNATURE
3844   This status indicates that the signature is invalid.  For the combined
3845   result this status means that all signatures are invalid.
3846
3847   @item GPG_ERR_NO_PUBKEY
3848   This status indicates that the signature could not be verified due to
3849   a missing key.  For the combined result this status means that all
3850   signatures could not be checked due to missing keys.
3851
3852   @item GPG_ERR_GENERAL
3853   This status indicates that there was some other error which prevented
3854   the signature verification.
3855   @end table
3856
3857 @item gpgme_sig_notation_t notations
3858 This is a linked list with the notation data and policy URLs.
3859
3860 @item unsigned long timestamp
3861 The creation timestamp of this signature.
3862
3863 @item unsigned long exp_timestamp
3864 The expiration timestamp of this signature, or 0 if the signature does
3865 not expire.
3866
3867 @item unsigned int wrong_key_usage : 1
3868 This is true if the key was not used according to its policy.
3869
3870 @item gpgme_validity_t validity
3871 The validity of the signature.
3872
3873 @item gpgme_error_t validity_reason
3874 If a signature is not valid, this provides a reason why.
3875
3876 @item gpgme_pubkey_algo_t
3877 The public key algorithm used to create this signature.
3878
3879 @item gpgme_hash_algo_t
3880 The hash algorithm used to create this signature.
3881 @end table
3882 @end deftp
3883
3884 @deftp {Data type} {gpgme_verify_result_t}
3885 This is a pointer to a structure used to store the result of a
3886 @code{gpgme_op_verify} operation.  After verifying a signature, you
3887 can retrieve the pointer to the result with
3888 @code{gpgme_op_verify_result}.  If the operation failed this might be
3889 a @code{NULL} pointer.  The structure contains the following member:
3890
3891 @table @code
3892 @item gpgme_signature_t signatures
3893 A linked list with information about all signatures for which a
3894 verification was attempted.
3895
3896 @item char *file_name
3897 This is the filename of the original plaintext message file if it is
3898 known, otherwise this is a null pointer.
3899 @end table
3900 @end deftp
3901
3902 @deftypefun gpgme_verify_result_t gpgme_op_verify_result (@w{gpgme_ctx_t @var{ctx}})
3903 The function @code{gpgme_op_verify_result} returns a
3904 @code{gpgme_verify_result_t} pointer to a structure holding the result
3905 of a @code{gpgme_op_verify} operation.  The pointer is only valid if
3906 the last operation on the context was a @code{gpgme_op_verify},
3907 @code{gpgme_op_verify_start}, @code{gpgme_op_decrypt_verify} or
3908 @code{gpgme_op_decrypt_verify_start} operation, and if this operation
3909 finished successfully (for @code{gpgme_op_decrypt_verify} and
3910 @code{gpgme_op_decrypt_verify_start}, the error code
3911 @code{GPG_ERR_NO_DATA} counts as successful in this context).  The
3912 returned pointer is only valid until the next operation is started on
3913 the context.
3914 @end deftypefun
3915
3916
3917 The following interfaces are deprecated and only provided for backward
3918 compatibility.  Don't use them.  They will be removed in a future
3919 version of @acronym{GPGME}.
3920
3921 @deftp {Data type} {enum gpgme_sig_stat_t}
3922 @tindex gpgme_sig_stat_t
3923 The @code{gpgme_sig_stat_t} type holds the result of a signature check, or
3924 the combined result of all signatures.  The following results are
3925 possible:
3926
3927 @table @code
3928 @item GPGME_SIG_STAT_NONE
3929 This status should not occur in normal operation.
3930
3931 @item GPGME_SIG_STAT_GOOD
3932 This status indicates that the signature is valid.  For the combined
3933 result this status means that all signatures are valid.
3934
3935 @item GPGME_SIG_STAT_GOOD_EXP
3936 This status indicates that the signature is valid but expired.  For
3937 the combined result this status means that all signatures are valid
3938 and expired.
3939
3940 @item GPGME_SIG_STAT_GOOD_EXPKEY
3941 This status indicates that the signature is valid but the key used to
3942 verify the signature has expired.  For the combined result this status
3943 means that all signatures are valid and all keys are expired.
3944
3945 @item GPGME_SIG_STAT_BAD
3946 This status indicates that the signature is invalid.  For the combined
3947 result this status means that all signatures are invalid.
3948
3949 @item GPGME_SIG_STAT_NOKEY
3950 This status indicates that the signature could not be verified due to
3951 a missing key.  For the combined result this status means that all
3952 signatures could not be checked due to missing keys.
3953
3954 @item GPGME_SIG_STAT_NOSIG
3955 This status indicates that the signature data provided was not a real
3956 signature.
3957
3958 @item GPGME_SIG_STAT_ERROR
3959 This status indicates that there was some other error which prevented
3960 the signature verification.
3961
3962 @item GPGME_SIG_STAT_DIFF
3963 For the combined result this status means that at least two signatures
3964 have a different status.  You can get each key's status with
3965 @code{gpgme_get_sig_status}.
3966 @end table
3967 @end deftp
3968
3969 @deftypefun {const char *} gpgme_get_sig_status (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_sig_stat_t *@var{r_stat}}, @w{time_t *@var{r_created}})
3970 The function @code{gpgme_get_sig_status} is equivalent to:
3971  
3972 @example
3973   gpgme_verify_result_t result;
3974   gpgme_signature_t sig;
3975
3976   result = gpgme_op_verify_result (ctx);
3977   sig = result->signatures;
3978
3979   while (sig && idx)
3980     @{
3981       sig = sig->next;
3982       idx--;
3983     @}
3984   if (!sig || idx)
3985     return NULL;
3986
3987   if (r_stat)
3988     @{
3989       switch (gpg_err_code (sig->status))
3990         @{
3991         case GPG_ERR_NO_ERROR:
3992           *r_stat = GPGME_SIG_STAT_GOOD;
3993           break;
3994           
3995         case GPG_ERR_BAD_SIGNATURE:
3996           *r_stat = GPGME_SIG_STAT_BAD;
3997           break;
3998           
3999         case GPG_ERR_NO_PUBKEY:
4000           *r_stat = GPGME_SIG_STAT_NOKEY;
4001           break;
4002           
4003         case GPG_ERR_NO_DATA:
4004           *r_stat = GPGME_SIG_STAT_NOSIG;
4005           break;
4006           
4007         case GPG_ERR_SIG_EXPIRED:
4008           *r_stat = GPGME_SIG_STAT_GOOD_EXP;
4009           break;
4010           
4011         case GPG_ERR_KEY_EXPIRED:
4012           *r_stat = GPGME_SIG_STAT_GOOD_EXPKEY;
4013           break;
4014           
4015         default:
4016           *r_stat = GPGME_SIG_STAT_ERROR;
4017           break;
4018         @}
4019     @}
4020   if (r_created)
4021     *r_created = sig->timestamp;
4022   return sig->fpr;
4023 @end example
4024 @end deftypefun
4025
4026 @deftypefun {const char *} gpgme_get_sig_string_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{what}}, @w{int @var{whatidx}})
4027 The function @code{gpgme_get_sig_string_attr} is equivalent to:
4028  
4029 @example
4030   gpgme_verify_result_t result;
4031   gpgme_signature_t sig;
4032
4033   result = gpgme_op_verify_result (ctx);
4034   sig = result->signatures;
4035
4036   while (sig && idx)
4037     @{
4038       sig = sig->next;
4039       idx--;
4040     @}
4041   if (!sig || idx)
4042     return NULL;
4043
4044   switch (what)
4045     @{
4046     case GPGME_ATTR_FPR:
4047       return sig->fpr;
4048
4049     case GPGME_ATTR_ERRTOK:
4050       if (whatidx == 1)
4051         return sig->wrong_key_usage ? "Wrong_Key_Usage" : "";
4052       else
4053         return "";
4054     default:
4055       break;
4056     @}
4057
4058   return NULL;
4059 @end example
4060 @end deftypefun
4061
4062 @deftypefun {const char *} gpgme_get_sig_ulong_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{waht}}, @w{int @var{whatidx}})
4063 The function @code{gpgme_get_sig_ulong_attr} is equivalent to:
4064  
4065 @example
4066   gpgme_verify_result_t result;
4067   gpgme_signature_t sig;
4068
4069   result = gpgme_op_verify_result (ctx);
4070   sig = result->signatures;
4071
4072   while (sig && idx)
4073     @{
4074       sig = sig->next;
4075       idx--;
4076     @}
4077   if (!sig || idx)
4078     return 0;
4079
4080   switch (what)
4081     @{
4082     case GPGME_ATTR_CREATED:
4083       return sig->timestamp;
4084
4085     case GPGME_ATTR_EXPIRE:
4086       return sig->exp_timestamp;
4087
4088     case GPGME_ATTR_VALIDITY:
4089       return (unsigned long) sig->validity;
4090
4091     case GPGME_ATTR_SIG_STATUS:
4092       switch (sig->status)
4093         @{
4094         case GPG_ERR_NO_ERROR:
4095           return GPGME_SIG_STAT_GOOD;
4096           
4097         case GPG_ERR_BAD_SIGNATURE:
4098           return GPGME_SIG_STAT_BAD;
4099           
4100         case GPG_ERR_NO_PUBKEY:
4101           return GPGME_SIG_STAT_NOKEY;
4102           
4103         case GPG_ERR_NO_DATA:
4104           return GPGME_SIG_STAT_NOSIG;
4105           
4106         case GPG_ERR_SIG_EXPIRED:
4107           return GPGME_SIG_STAT_GOOD_EXP;
4108           
4109         case GPG_ERR_KEY_EXPIRED:
4110           return GPGME_SIG_STAT_GOOD_EXPKEY;
4111           
4112         default:
4113           return GPGME_SIG_STAT_ERROR;
4114         @}
4115
4116     case GPGME_ATTR_SIG_SUMMARY:
4117       return sig->summary;
4118
4119     default:
4120       break;
4121     @}
4122   return 0;
4123 @end example
4124 @end deftypefun
4125
4126 @deftypefun {const char *} gpgme_get_sig_key (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_key_t *@var{r_key}})
4127 The function @code{gpgme_get_sig_key} is equivalent to:
4128
4129 @example
4130   gpgme_verify_result_t result;
4131   gpgme_signature_t sig;
4132
4133   result = gpgme_op_verify_result (ctx);
4134   sig = result->signatures;
4135
4136   while (sig && idx)
4137     @{
4138       sig = sig->next;
4139       idx--;
4140     @}
4141   if (!sig || idx)
4142     return gpg_error (GPG_ERR_EOF);
4143
4144   return gpgme_get_key (ctx, sig->fpr, r_key, 0);
4145 @end example
4146 @end deftypefun
4147
4148
4149 @node Decrypt and Verify
4150 @subsection Decrypt and Verify
4151 @cindex decryption and verification
4152 @cindex verification and decryption
4153 @cindex signature check
4154 @cindex cryptographic operation, decryption and verification
4155
4156 @deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
4157 The function @code{gpgme_op_decrypt_verify} decrypts the ciphertext in
4158 the data object @var{cipher} and stores it into the data object
4159 @var{plain}.  If @var{cipher} contains signatures, they will be
4160 verified.
4161
4162 After the operation completed, @code{gpgme_op_decrypt_result} and
4163 @code{gpgme_op_verify_result} can be used to retrieve more information
4164 about the signatures.
4165
4166 If the error code @code{GPG_ERR_NO_DATA} is returned, @var{cipher}
4167 does not contain any data to decrypt.  However, it might still be
4168 signed.  The information about detected signatures is available with
4169 @code{gpgme_op_verify_result} in this case.
4170
4171 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
4172 ciphertext could be decrypted successfully, @code{GPG_ERR_INV_VALUE}
4173 if @var{ctx}, @var{cipher} or @var{plain} is not a valid pointer,
4174 @code{GPG_ERR_NO_DATA} if @var{cipher} does not contain any data to
4175 decrypt, @code{GPG_ERR_DECRYPT_FAILED} if @var{cipher} is not a valid
4176 cipher text, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the
4177 secret key could not be retrieved, and passes through any errors that
4178 are reported by the crypto engine support routines.
4179 @end deftypefun
4180
4181 @deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
4182 The function @code{gpgme_op_decrypt_verify_start} initiates a
4183 @code{gpgme_op_decrypt_verify} operation.  It can be completed by
4184 calling @code{gpgme_wait} on the context.  @xref{Waiting For
4185 Completion}.
4186
4187 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
4188 operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
4189 @var{ctx}, @var{cipher}, @var{plain} or @var{r_stat} is not a valid
4190 pointer, and @code{GPG_ERR_NO_DATA} if @var{cipher} does not contain
4191 any data to decrypt.
4192 @end deftypefun
4193
4194
4195 @node Sign
4196 @subsection Sign
4197 @cindex signature, creation
4198 @cindex sign
4199 @cindex cryptographic operation, signing
4200
4201 A signature can contain signatures by one or more keys.  The set of
4202 keys used to create a signatures is contained in a context, and is
4203 applied to all following signing operations in this context (until the
4204 set is changed).
4205
4206 @menu
4207 * Selecting Signers::             How to choose the keys to sign with.
4208 * Creating a Signature::          How to create a signature.
4209 @end menu
4210
4211
4212 @node Selecting Signers
4213 @subsubsection Selecting Signers
4214 @cindex signature, selecting signers
4215 @cindex signers, selecting
4216
4217 @deftypefun void gpgme_signers_clear (@w{gpgme_ctx_t @var{ctx}})
4218 The function @code{gpgme_signers_clear} releases a reference for each
4219 key on the signers list and removes the list of signers from the
4220 context @var{ctx}.
4221
4222 Every context starts with an empty list.
4223 @end deftypefun
4224
4225 @deftypefun gpgme_error_t gpgme_signers_add (@w{gpgme_ctx_t @var{ctx}}, @w{const gpgme_key_t @var{key}})
4226 The function @code{gpgme_signers_add} adds the key @var{key} to the
4227 list of signers in the context @var{ctx}.
4228
4229 Calling this function acquires an additional reference for the key.
4230 @end deftypefun
4231
4232 @deftypefun gpgme_key_t gpgme_signers_enum (@w{const gpgme_ctx_t @var{ctx}}, @w{int @var{seq}})
4233 The function @code{gpgme_signers_enum} returns the @var{seq}th key in
4234 the list of signers in the context @var{ctx}.  An additional reference
4235 is acquired for the user.
4236
4237 If @var{seq} is out of range, @code{NULL} is returned.
4238 @end deftypefun
4239
4240
4241 @node Creating a Signature
4242 @subsubsection Creating a Signature
4243
4244 @deftp {Data type} {enum gpgme_sig_mode_t}
4245 @tindex gpgme_sig_mode_t
4246 The @code{gpgme_sig_mode_t} type is used to specify the desired type of a
4247 signature.  The following modes are available:
4248
4249 @table @code
4250 @item GPGME_SIG_MODE_NORMAL
4251 A normal signature is made, the output includes the plaintext and the
4252 signature.
4253
4254 @item GPGME_SIG_MODE_DETACH
4255 A detached signature is made.
4256
4257 @item GPGME_SIG_MODE_CLEAR
4258 A clear text signature is made.  The @acronym{ASCII} armor and text
4259 mode settings of the context are ignored.
4260 @end table
4261 @end deftp
4262
4263 @deftypefun gpgme_error_t gpgme_op_sign (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{sig}}, @w{gpgme_sig_mode_t @var{mode}})
4264 The function @code{gpgme_op_sign} creates a signature for the text in
4265 the data object @var{plain} and returns it in the data object
4266 @var{sig}.  The type of the signature created is determined by the
4267 @acronym{ASCII} armor and text mode attributes set for the context
4268 @var{ctx} and the requested signature mode @var{mode}.
4269
4270 After the operation completed successfully, the result can be
4271 retrieved with @code{gpgme_op_sign_result}.
4272
4273 If an S/MIME signed message is created using the CMS crypto engine,
4274 the number of certificates to include in the message can be specified
4275 with @code{gpgme_set_include_certs}.  @xref{Included Certificates}.
4276
4277 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
4278 signature could be created successfully, @code{GPG_ERR_INV_VALUE} if
4279 @var{ctx}, @var{plain} or @var{sig} is not a valid pointer,
4280 @code{GPG_ERR_NO_DATA} if the signature could not be created,
4281 @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the secret key
4282 could not be retrieved, @code{GPG_ERR_UNUSABLE_SECKEY} if there are
4283 invalid signers, and passes through any errors that are reported by the
4284 crypto engine support routines.
4285 @end deftypefun
4286
4287 @deftypefun gpgme_error_t gpgme_op_sign_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{sig}}, @w{gpgme_sig_mode_t @var{mode}})
4288 The function @code{gpgme_op_sign_start} initiates a
4289 @code{gpgme_op_sign} operation.  It can be completed by calling
4290 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
4291
4292 The function returns the error code @code{GPG_ERR_NO_ERROR} if the operation could be
4293 started successfully, and @code{GPG_ERR_INV_VALUE} if @var{ctx},
4294 @var{plain} or @var{sig} is not a valid pointer.
4295 @end deftypefun
4296
4297 @deftp {Data type} {gpgme_new_signature_t}
4298 This is a pointer to a structure used to store a part of the result of
4299 a @code{gpgme_op_sign} operation.  The structure contains the
4300 following members:
4301
4302 @table @code
4303 @item gpgme_new_signature_t next
4304 This is a pointer to the next new signature structure in the linked
4305 list, or @code{NULL} if this is the last element.
4306
4307 @item gpgme_sig_mode_t type
4308 The type of this signature.
4309
4310 @item gpgme_pubkey_algo_t
4311 The public key algorithm used to create this signature.
4312
4313 @item gpgme_hash_algo_t
4314 The hash algorithm used to create this signature.
4315
4316 @item unsigned int sig_class
4317 The signature class of this signature.
4318
4319 @item long int timestamp
4320 The creation timestamp of this signature.
4321
4322 @item char *fpr
4323 The fingerprint of the key which was used to create this signature.
4324 @end table
4325 @end deftp
4326
4327 @deftp {Data type} {gpgme_sign_result_t}
4328 This is a pointer to a structure used to store the result of a
4329 @code{gpgme_op_sign} operation.  After successfully generating a
4330 signature, you can retrieve the pointer to the result with
4331 @code{gpgme_op_sign_result}.  The structure contains the following
4332 members:
4333
4334 @table @code
4335 @item gpgme_invalid_key_t invalid_signers
4336 A linked list with information about all invalid keys for which a
4337 signature could not be created.
4338
4339 @item gpgme_new_signature_t signatures
4340 A linked list with information about all signatures created.
4341 @end table
4342 @end deftp
4343
4344 @deftypefun gpgme_sign_result_t gpgme_op_sign_result (@w{gpgme_ctx_t @var{ctx}})
4345 The function @code{gpgme_op_sign_result} returns a
4346 @code{gpgme_sign_result_t} pointer to a structure holding the result
4347 of a @code{gpgme_op_sign} operation.  The pointer is only valid if the
4348 last operation on the context was a @code{gpgme_op_sign},
4349 @code{gpgme_op_sign_start}, @code{gpgme_op_encrypt_sign} or
4350 @code{gpgme_op_encrypt_sign_start} operation.  If that operation
4351 failed, the function might return a @code{NULL} pointer, The returned
4352 pointer is only valid until the next operation is started on the
4353 context.
4354 @end deftypefun
4355
4356
4357 @node Encrypt
4358 @subsection Encrypt
4359 @cindex encryption
4360 @cindex cryptographic operation, encryption
4361
4362 One plaintext can be encrypted for several recipients at the same
4363 time.  The list of recipients is created independently of any context,
4364 and then passed to the encryption operation.
4365
4366 @menu
4367 * Encrypting a Plaintext::        How to encrypt a plaintext.
4368 @end menu
4369
4370
4371 @node Encrypting a Plaintext
4372 @subsubsection Encrypting a Plaintext
4373
4374 @deftypefun gpgme_error_t gpgme_op_encrypt (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}[]}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
4375 The function @code{gpgme_op_encrypt} encrypts the plaintext in the data
4376 object @var{plain} for the recipients @var{recp} and stores the
4377 ciphertext in the data object @var{cipher}.  The type of the
4378 ciphertext created is determined by the @acronym{ASCII} armor and text
4379 mode attributes set for the context @var{ctx}.
4380
4381 @var{key} must be a @code{NULL}-terminated array of keys.  The user
4382 must keep references for all keys during the whole duration of the
4383 call (but see @code{gpgme_op_encrypt_start} for the requirements with
4384 the asynchronous variant).
4385
4386 The value in @var{flags} is a bitwise-or combination of one or
4387 multiple of the following bit values:
4388
4389 @table @code
4390 @item GPGME_ENCRYPT_ALWAYS_TRUST