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