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