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