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