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