Fix spawn prototype for w32 glib and qt versions.
[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->path && !info->version)
878           fprintf (stderr, "Engine %s not installed properly",
879                    info->path);
880         else if (info->path && info->version && info->req_version)
881           fprintf (stderr, "Engine %s version %s installed, "
882                    "but at least version %s required", info->path,
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_VALIDATE
2212 The @code{GPGME_KEYLIST_MODE_VALIDATE} symbol specifies that the
2213 backend should do key or certificate validation and not just get the
2214 validity information from an internal cache.  This might be an
2215 expensive operation and is in general not useful.  Currently only
2216 implemented for the S/MIME backend and ignored for other backends.
2217
2218 @end table
2219
2220 At least one of @code{GPGME_KEYLIST_MODE_LOCAL} and
2221 @code{GPGME_KEYLIST_MODE_EXTERN} must be specified.  For future binary
2222 compatibility, you should get the current mode with
2223 @code{gpgme_get_keylist_mode} and modify it by setting or clearing the
2224 appropriate bits, and then using that calculated value in the
2225 @code{gpgme_set_keylisting_mode} operation.  This will leave all other
2226 bits in the mode value intact (in particular those that are not used
2227 in the current version of the library).
2228
2229 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
2230 mode could be set correctly, and @code{GPG_ERR_INV_VALUE} if @var{ctx}
2231 is not a valid pointer or @var{mode} is not a valid mode.
2232 @end deftypefun
2233
2234
2235 @deftypefun gpgme_keylist_mode_t gpgme_get_keylist_mode (@w{gpgme_ctx_t @var{ctx}})
2236 The function @code{gpgme_get_keylist_mode} returns the current key
2237 listing mode of the context @var{ctx}.  This value can then be
2238 modified and used in a subsequent @code{gpgme_set_keylist_mode}
2239 operation to only affect the desired bits (and leave all others
2240 intact).
2241
2242 The function returns 0 if @var{ctx} is not a valid pointer, and the
2243 current mode otherwise.  Note that 0 is not a valid mode value.
2244 @end deftypefun
2245
2246
2247 @node Passphrase Callback
2248 @subsection Passphrase Callback
2249 @cindex callback, passphrase
2250 @cindex passphrase callback
2251
2252 @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}})}
2253 @tindex gpgme_passphrase_cb_t
2254 The @code{gpgme_passphrase_cb_t} type is the type of functions usable as
2255 passphrase callback function.
2256
2257 The argument @var{uid_hint} might contain a string that gives an
2258 indication for which user ID the passphrase is required.  If this is
2259 not available, or not applicable (in the case of symmetric encryption,
2260 for example), @var{uid_hint} will be @code{NULL}.
2261
2262 The argument @var{passphrase_info}, if not @code{NULL}, will give
2263 further information about the context in which the passphrase is
2264 required.  This information is engine and operation specific.
2265
2266 If this is the repeated attempt to get the passphrase, because
2267 previous attempts failed, then @var{prev_was_bad} is 1, otherwise it
2268 will be 0.
2269
2270 The user must write the passphrase, followed by a newline character,
2271 to the file descriptor @var{fd}.  If the user returns 0 indicating
2272 success, the user must at least write a newline character before
2273 returning from the callback.
2274
2275 If an error occurs, return the corresponding @code{gpgme_error_t}
2276 value.  You can use the error code @code{GPG_ERR_CANCELED} to abort
2277 the operation.  Otherwise, return @code{0}.
2278 @end deftp
2279
2280 @deftypefun void gpgme_set_passphrase_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_passphrase_cb_t @var{passfunc}}, @w{void *@var{hook_value}})
2281 The function @code{gpgme_set_passphrase_cb} sets the function that is
2282 used when a passphrase needs to be provided by the user to
2283 @var{passfunc}.  The function @var{passfunc} needs to implemented by
2284 the user, and whenever it is called, it is called with its first
2285 argument being @var{hook_value}.  By default, no passphrase callback
2286 function is set.
2287
2288 Not all crypto engines require this callback to retrieve the
2289 passphrase.  It is better if the engine retrieves the passphrase from
2290 a trusted agent (a daemon process), rather than having each user to
2291 implement their own passphrase query.  Some engines do not even
2292 support an external passphrase callback at all, in this case the error
2293 code @code{GPG_ERR_NOT_SUPPORTED} is returned.
2294
2295 The user can disable the use of a passphrase callback function by
2296 calling @code{gpgme_set_passphrase_cb} with @var{passfunc} being
2297 @code{NULL}.
2298 @end deftypefun
2299
2300 @deftypefun void gpgme_get_passphrase_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_passphrase_cb_t *@var{passfunc}}, @w{void **@var{hook_value}})
2301 The function @code{gpgme_get_passphrase_cb} returns the function that
2302 is used when a passphrase needs to be provided by the user in
2303 @var{*passfunc}, and the first argument for this function in
2304 @var{*hook_value}.  If no passphrase callback is set, or @var{ctx} is
2305 not a valid pointer, @code{NULL} is returned in both variables.
2306
2307 @var{passfunc} or @var{hook_value} can be @code{NULL}.  In this case,
2308 the corresponding value will not be returned.
2309 @end deftypefun
2310
2311
2312 @node Progress Meter Callback
2313 @subsection Progress Meter Callback
2314 @cindex callback, progress meter
2315 @cindex progress meter callback
2316
2317 @deftp {Data type} {void (*gpgme_progress_cb_t)(void *@var{hook}, const char *@var{what}, int @var{type}, int @var{current}, int @var{total})}
2318 @tindex gpgme_progress_cb_t
2319 The @code{gpgme_progress_cb_t} type is the type of functions usable as
2320 progress callback function.
2321
2322 The arguments are specific to the crypto engine.  More information
2323 about the progress information returned from the GnuPG engine can be
2324 found in the GnuPG source code in the file @file{doc/DETAILS} in the
2325 section PROGRESS.
2326 @end deftp
2327
2328 @deftypefun void gpgme_set_progress_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_progress_cb_t @var{progfunc}}, @w{void *@var{hook_value}})
2329 The function @code{gpgme_set_progress_cb} sets the function that is
2330 used when progress information about a cryptographic operation is
2331 available.  The function @var{progfunc} needs to implemented by the
2332 user, and whenever it is called, it is called with its first argument
2333 being @var{hook_value}.  By default, no progress callback function
2334 is set.
2335
2336 Setting a callback function allows an interactive program to display
2337 progress information about a long operation to the user.
2338
2339 The user can disable the use of a progress callback function by
2340 calling @code{gpgme_set_progress_cb} with @var{progfunc} being
2341 @code{NULL}.
2342 @end deftypefun
2343
2344 @deftypefun void gpgme_get_progress_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_progress_cb_t *@var{progfunc}}, @w{void **@var{hook_value}})
2345 The function @code{gpgme_get_progress_cb} returns the function that is
2346 used to inform the user about the progress made in @var{*progfunc},
2347 and the first argument for this function in @var{*hook_value}.  If no
2348 progress callback is set, or @var{ctx} is not a valid pointer,
2349 @code{NULL} is returned in both variables.
2350
2351 @var{progfunc} or @var{hook_value} can be @code{NULL}.  In this case,
2352 the corresponding value will not be returned.
2353 @end deftypefun
2354
2355
2356 @node Locale
2357 @subsection Locale
2358 @cindex locale, default
2359 @cindex locale, of a context
2360
2361 A locale setting can be associated with a context.  This locale is
2362 passed to the crypto engine, and used for applications like the PIN
2363 entry, which is displayed to the user when entering a passphrase is
2364 required.
2365
2366 The default locale is used to initialize the locale setting of all
2367 contexts created afterwards.
2368
2369 @deftypefun gpgme_error_t gpgme_set_locale (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{category}}, @w{const char *@var{value}})
2370 The function @code{gpgme_set_locale} sets the locale of the context
2371 @var{ctx}, or the default locale if @var{ctx} is a null pointer.
2372
2373 The locale settings that should be changed are specified by
2374 @var{category}.  Supported categories are @code{LC_CTYPE},
2375 @code{LC_MESSAGES}, and @code{LC_ALL}, which is a wildcard you can use
2376 if you want to change all the categories at once.
2377
2378 The value to be used for the locale setting is @var{value}, which will
2379 be copied to @acronym{GPGME}'s internal data structures.  @var{value}
2380 can be a null pointer, which disables setting the locale, and will
2381 make PIN entry and other applications use their default setting, which
2382 is usually not what you want.
2383
2384 Note that the settings are only used if the application runs on a text
2385 terminal, and that the settings should fit the configuration of the
2386 output terminal.  Normally, it is sufficient to initialize the default
2387 value at startup.
2388
2389 The function returns an error if not enough memory is available.
2390 @end deftypefun
2391
2392
2393 @node Key Management
2394 @section Key Management
2395 @cindex key management
2396
2397 Some of the cryptographic operations require that recipients or
2398 signers are specified.  This is always done by specifying the
2399 respective keys that should be used for the operation.  The following
2400 section describes how such keys can be selected and manipulated.
2401
2402 @deftp {Data type} gpgme_sub_key_t
2403 The @code{gpgme_sub_key_t} type is a pointer to a subkey structure.
2404 Sub keys are one component of a @code{gpgme_key_t} object.  In fact,
2405 subkeys are those parts that contains the real information about the
2406 individual cryptographic keys that belong to the same key object.  One
2407 @code{gpgme_key_t} can contain several subkeys.  The first subkey in
2408 the linked list is also called the primary key.
2409
2410 The subkey structure has the following members:
2411
2412 @table @code
2413 @item gpgme_sub_key_t next
2414 This is a pointer to the next subkey structure in the linked list, or
2415 @code{NULL} if this is the last element.
2416
2417 @item unsigned int revoked : 1
2418 This is true if the subkey is revoked.
2419
2420 @item unsigned int expired : 1
2421 This is true if the subkey is expired.
2422
2423 @item unsigned int disabled : 1
2424 This is true if the subkey is disabled.
2425
2426 @item unsigned int invalid : 1
2427 This is true if the subkey is invalid.
2428
2429 @item unsigned int can_encrypt : 1
2430 This is true if the subkey can be used for encryption.
2431
2432 @item unsigned int can_sign : 1
2433 This is true if the subkey can be used to create data signatures.
2434
2435 @item unsigned int can_certify : 1
2436 This is true if the subkey can be used to create key certificates.
2437
2438 @item unsigned int can_authenticate : 1
2439 This is true if the subkey can be used for authentication.
2440
2441 @item unsigned int is_qualified : 1
2442 This is true if the subkey can be used for qualified signatures
2443 according to local government regulations.
2444
2445 @item unsigned int secret : 1
2446 This is true if the subkey is a secret key.  Note that it will be false
2447 if the key is actually a stub key; i.e. a secret key operation is
2448 currently not possible (offline-key).
2449
2450 @item gpgme_pubkey_algo_t pubkey_algo
2451 This is the public key algorithm supported by this subkey.
2452
2453 @item unsigned int length
2454 This is the length of the subkey (in bits).
2455
2456 @item char *keyid
2457 This is the key ID of the subkey in hexadecimal digits.
2458
2459 @item char *fpr
2460 This is the fingerprint of the subkey in hexadecimal digits, if
2461 available.
2462
2463 @item long int timestamp
2464 This is the creation timestamp of the subkey.  This is -1 if the
2465 timestamp is invalid, and 0 if it is not available.
2466
2467 @item long int expires
2468 This is the expiration timestamp of the subkey, or 0 if the subkey
2469 does not expire.
2470 @end table
2471 @end deftp
2472
2473 @deftp {Data type} gpgme_key_sig_t
2474 The @code{gpgme_key_sig_t} type is a pointer to a key signature structure.
2475 Key signatures are one component of a @code{gpgme_key_t} object, and
2476 validate user IDs on the key.
2477
2478 The signatures on a key are only available if the key was retrieved
2479 via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode
2480 enabled, because it can be expensive to retrieve all signatures of a
2481 key.
2482
2483 The signature notations on a key signature are only available if the
2484 key was retrieved via a listing operation with the
2485 @code{GPGME_KEYLIST_MODE_SIG_NOTATIONS} mode enabled, because it can
2486 be expensive to retrieve all signature notations.
2487
2488 The key signature structure has the following members:
2489
2490 @table @code
2491 @item gpgme_key_sig_t next
2492 This is a pointer to the next key signature structure in the linked
2493 list, or @code{NULL} if this is the last element.
2494
2495 @item unsigned int revoked : 1
2496 This is true if the key signature is a revocation signature.
2497
2498 @item unsigned int expired : 1
2499 This is true if the key signature is expired.
2500
2501 @item unsigned int invalid : 1
2502 This is true if the key signature is invalid.
2503
2504 @item unsigned int exportable : 1
2505 This is true if the key signature is exportable.
2506
2507 @item gpgme_pubkey_algo_t pubkey_algo
2508 This is the public key algorithm used to create the signature.
2509
2510 @item char *keyid
2511 This is the key ID of the key (in hexadecimal digits) used to create
2512 the signature.
2513
2514 @item long int timestamp
2515 This is the creation timestamp of the key signature.  This is -1 if
2516 the timestamp is invalid, and 0 if it is not available.
2517
2518 @item long int expires
2519 This is the expiration timestamp of the key signature, or 0 if the key
2520 signature does not expire.
2521
2522 @item gpgme_error_t status
2523 This is the status of the signature and has the same meaning as the
2524 member of the same name in a @code{gpgme_signature_t} object.
2525
2526 @item unsigned int sig_class
2527 This specifies the signature class of the key signature.  The meaning
2528 is specific to the crypto engine.
2529
2530 @item char *uid
2531 This is the main user ID of the key used to create the signature.
2532
2533 @item char *name
2534 This is the name component of @code{uid}, if available.
2535
2536 @item char *comment
2537 This is the comment component of @code{uid}, if available.
2538
2539 @item char *email
2540 This is the email component of @code{uid}, if available.
2541
2542 @item gpgme_sig_notation_t notations
2543 This is a linked list with the notation data and policy URLs.
2544 @end table
2545 @end deftp
2546
2547 @deftp {Data type} gpgme_user_id_t
2548 A user ID is a component of a @code{gpgme_key_t} object.  One key can
2549 have many user IDs.  The first one in the list is the main (or
2550 primary) user ID.
2551
2552 The user ID structure has the following members.
2553
2554 @table @code
2555 @item gpgme_user_id_t next
2556 This is a pointer to the next user ID structure in the linked list, or
2557 @code{NULL} if this is the last element.
2558
2559 @item unsigned int revoked : 1
2560 This is true if the user ID is revoked.
2561
2562 @item unsigned int invalid : 1
2563 This is true if the user ID is invalid.
2564
2565 @item gpgme_validity_t validity
2566 This specifies the validity of the user ID.
2567
2568 @item char *uid
2569 This is the user ID string.
2570
2571 @item char *name
2572 This is the name component of @code{uid}, if available.
2573
2574 @item char *comment
2575 This is the comment component of @code{uid}, if available.
2576
2577 @item char *email
2578 This is the email component of @code{uid}, if available.
2579
2580 @item gpgme_key_sig_t signatures
2581 This is a linked list with the signatures on this user ID.
2582 @end table
2583 @end deftp
2584
2585 @deftp {Data type} gpgme_key_t
2586 The @code{gpgme_key_t} type is a pointer to a key object.  It has the
2587 following members:
2588
2589 @table @code
2590 @item gpgme_keylist_mode_t keylist_mode
2591 The keylist mode that was active when the key was retrieved.
2592
2593 @item unsigned int revoked : 1
2594 This is true if the key is revoked.
2595
2596 @item unsigned int expired : 1
2597 This is true if the key is expired.
2598
2599 @item unsigned int disabled : 1
2600 This is true if the key is disabled.
2601
2602 @item unsigned int invalid : 1
2603 This is true if the key is invalid. This might have several reasons,
2604 for a example for the S/MIME backend, it will be set in during key
2605 listsing if the key could not be validated due to a missing
2606 certificates or unmatched policies.
2607
2608 @item unsigned int can_encrypt : 1
2609 This is true if the key (ie one of its subkeys) can be used for
2610 encryption.
2611
2612 @item unsigned int can_sign : 1
2613 This is true if the key (ie one of its subkeys) can be used to create
2614 data signatures.
2615
2616 @item unsigned int can_certify : 1
2617 This is true if the key (ie one of its subkeys) can be used to create
2618 key certificates.
2619
2620 @item unsigned int can_authenticate : 1
2621 This is true if the key (ie one of its subkeys) can be used for
2622 authentication.
2623
2624 @item unsigned int is_qualified : 1
2625 This is true if the key can be used for qualified signatures according
2626 to local government regulations.
2627
2628 @item unsigned int secret : 1
2629 This is true if the key is a secret key.  Note, that this will always be
2630 true even if the corresponding subkey flag may be false (offline/stub
2631 keys).
2632
2633 @item gpgme_protocol_t protocol
2634 This is the protocol supported by this key.
2635
2636 @item char *issuer_serial
2637 If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
2638 issuer serial.
2639
2640 @item char *issuer_name
2641 If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
2642 issuer name.
2643
2644 @item char *chain_id
2645 If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
2646 chain ID, which can be used to built the certificate chain.
2647  
2648 @item gpgme_validity_t owner_trust
2649 If @code{protocol} is @code{GPGME_PROTOCOL_OpenPGP}, then this is the
2650 owner trust.
2651
2652 @item gpgme_sub_key_t subkeys
2653 This is a linked list with the subkeys of the key.  The first subkey
2654 in the list is the primary key and usually available.
2655
2656 @item gpgme_user_id_t uids
2657 This is a linked list with the user IDs of the key.  The first user ID
2658 in the list is the main (or primary) user ID.
2659 @end table
2660 @end deftp
2661
2662 @menu
2663 * Listing Keys::                  Browsing the list of available keys.
2664 * Information About Keys::        Requesting detailed information about keys.
2665 * Key Signatures::                Listing the signatures on a key.
2666 * Manipulating Keys::             Operations on keys.
2667 * Generating Keys::               Creating new key pairs.
2668 * Exporting Keys::                Retrieving key data from the key ring.
2669 * Importing Keys::                Adding keys to the key ring.
2670 * Deleting Keys::                 Removing keys from the key ring.
2671 * Advanced Key Editing::          Advanced key edit operation.
2672 @end menu
2673
2674
2675 @node Listing Keys
2676 @subsection Listing Keys
2677 @cindex listing keys
2678 @cindex key listing
2679 @cindex key listing, start
2680 @cindex key ring, list
2681 @cindex key ring, search
2682
2683 @deftypefun gpgme_error_t gpgme_op_keylist_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}})
2684 The function @code{gpgme_op_keylist_start} initiates a key listing
2685 operation inside the context @var{ctx}.  It sets everything up so that
2686 subsequent invocations of @code{gpgme_op_keylist_next} return the keys
2687 in the list.
2688
2689 If @var{pattern} is @code{NULL}, all available keys are returned.
2690 Otherwise, @var{pattern} contains an engine specific expression that
2691 is used to limit the list to all keys matching the pattern.  Note that
2692 the total length of the pattern is restricted to an engine-specific
2693 maximum (a couple of hundred characters are usually accepted).  The
2694 pattern should be used to restrict the search to a certain common name
2695 or user, not to list many specific keys at once by listing their
2696 fingerprints or key IDs.
2697
2698 If @var{secret_only} is not @code{0}, the list is restricted to secret
2699 keys only.
2700
2701 The context will be busy until either all keys are received (and
2702 @code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}), or
2703 @code{gpgme_op_keylist_end} is called to finish the operation.
2704
2705 The function returns the error code @code{GPG_ERR_INV_VALUE} if
2706 @var{ctx} is not a valid pointer, and passes through any errors that
2707 are reported by the crypto engine support routines.
2708 @end deftypefun
2709
2710 @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}})
2711 The function @code{gpgme_op_keylist_ext_start} initiates an extended
2712 key listing operation inside the context @var{ctx}.  It sets
2713 everything up so that subsequent invocations of
2714 @code{gpgme_op_keylist_next} return the keys in the list.
2715
2716 If @var{pattern} or @var{*pattern} is @code{NULL}, all available keys
2717 are returned.  Otherwise, @var{pattern} is a @code{NULL} terminated
2718 array of strings that are used to limit the list to all keys matching
2719 at least one of the patterns verbatim.  Note that the total length of
2720 all patterns is restricted to an engine-specific maximum (the exact
2721 limit also depends on the number of patterns and amount of quoting
2722 required, but a couple of hundred characters are usually accepted).
2723 Patterns should be used to restrict the search to a certain common
2724 name or user, not to list many specific keys at once by listing their
2725 fingerprints or key IDs.
2726
2727 If @var{secret_only} is not @code{0}, the list is restricted to secret
2728 keys only.
2729
2730 The value of @var{reserved} must be @code{0}.
2731
2732 The context will be busy until either all keys are received (and
2733 @code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}), or
2734 @code{gpgme_op_keylist_end} is called to finish the operation.
2735
2736 The function returns the error code @code{GPG_ERR_INV_VALUE} if
2737 @var{ctx} is not a valid pointer, and passes through any errors that
2738 are reported by the crypto engine support routines.
2739 @end deftypefun
2740
2741 @deftypefun gpgme_error_t gpgme_op_keylist_next (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t *@var{r_key}})
2742 The function @code{gpgme_op_keylist_next} returns the next key in the
2743 list created by a previous @code{gpgme_op_keylist_start} operation in
2744 the context @var{ctx}.  The key will have one reference for the user.
2745 @xref{Manipulating Keys}.
2746
2747 This is the only way to get at @code{gpgme_key_t} objects in
2748 @acronym{GPGME}.
2749
2750 If the last key in the list has already been returned,
2751 @code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}.
2752
2753 The function returns the error code @code{GPG_ERR_INV_VALUE} if
2754 @var{ctx} or @var{r_key} is not a valid pointer, and
2755 @code{GPG_ERR_ENOMEM} if there is not enough memory for the operation.
2756 @end deftypefun
2757
2758 @deftypefun gpgme_error_t gpgme_op_keylist_end (@w{gpgme_ctx_t @var{ctx}})
2759 The function @code{gpgme_op_keylist_next} ends a pending key list
2760 operation in the context @var{ctx}.
2761
2762 After the operation completed successfully, the result of the key
2763 listing operation can be retrieved with
2764 @code{gpgme_op_keylist_result}.
2765
2766 The function returns the error code @code{GPG_ERR_INV_VALUE} if
2767 @var{ctx} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if at some
2768 time during the operation there was not enough memory available.
2769 @end deftypefun
2770
2771 The following example illustrates how all keys containing a certain
2772 string (@code{g10code}) can be listed with their key ID and the name
2773 and e-mail address of the main user ID:
2774
2775 @example
2776 gpgme_ctx_t ctx;
2777 gpgme_key_t key;
2778 gpgme_error_t err = gpgme_new (&ctx);
2779
2780 if (!err)
2781   @{
2782     err = gpgme_op_keylist_start (ctx, "g10code", 0);
2783     while (!err)
2784       @{
2785         err = gpgme_op_keylist_next (ctx, &key);
2786         if (err)
2787           break;
2788         printf ("%s:", key->subkeys->keyid);
2789         if (key->uids && key->uids->name)
2790           printf (" %s", key->uids->name);
2791         if (key->uids && key->uids->email)
2792           printf (" <%s>", key->uids->email);
2793         putchar ('\n');
2794         gpgme_key_release (key);
2795       @}
2796     gpgme_release (ctx);
2797   @}
2798 if (gpg_err_code (err) != GPG_ERR_EOF)
2799   @{
2800     fprintf (stderr, "can not list keys: %s\n", gpgme_strerror (err));
2801     exit (1);
2802   @}
2803 @end example
2804
2805 @deftp {Data type} {gpgme_keylist_result_t}
2806 This is a pointer to a structure used to store the result of a
2807 @code{gpgme_op_keylist_*} operation.  After successfully ending a key
2808 listing operation, you can retrieve the pointer to the result with
2809 @code{gpgme_op_keylist_result}.  The structure contains the following
2810 member:
2811
2812 @table @code
2813 @item unsigned int truncated : 1
2814 This is true if the crypto backend had to truncate the result, and
2815 less than the desired keys could be listed.
2816 @end table
2817 @end deftp
2818
2819 @deftypefun gpgme_keylist_result_t gpgme_op_keylist_result (@w{gpgme_ctx_t @var{ctx}})
2820 The function @code{gpgme_op_keylist_result} returns a
2821 @code{gpgme_keylist_result_t} pointer to a structure holding the
2822 result of a @code{gpgme_op_keylist_*} operation.  The pointer is only
2823 valid if the last operation on the context was a key listing
2824 operation, and if this operation finished successfully.  The returned
2825 pointer is only valid until the next operation is started on the
2826 context.
2827 @end deftypefun
2828
2829 In a simple program, for which a blocking operation is acceptable, the
2830 following function can be used to retrieve a single key.
2831
2832 @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}})
2833 The function @code{gpgme_get_key} gets the key with the fingerprint
2834 (or key ID) @var{fpr} from the crypto backend and return it in
2835 @var{r_key}.  If @var{secret} is true, get the secret key.  The
2836 currently active keylist mode is used to retrieve the key.  The key
2837 will have one reference for the user.
2838
2839 If the key is not found in the keyring, @code{gpgme_get_key} returns
2840 the error code @code{GPG_ERR_EOF} and *@var{r_key} will be set to
2841 @code{NULL}.
2842
2843 The function returns the error code @code{GPG_ERR_INV_VALUE} if
2844 @var{ctx} or @var{r_key} is not a valid pointer or @var{fpr} is not a
2845 fingerprint or key ID, @code{GPG_ERR_AMBIGUOUS_NAME} if the key ID was
2846 not a unique specifier for a key, and @code{GPG_ERR_ENOMEM} if at some
2847 time during the operation there was not enough memory available.
2848 @end deftypefun
2849
2850
2851 @node Information About Keys
2852 @subsection Information About Keys
2853 @cindex key, information about
2854 @cindex key, attributes
2855 @cindex attributes, of a key
2856
2857 Please see the beginning of this section for more information about
2858 @code{gpgme_key_t} objects.
2859
2860 @deftp {Data type} gpgme_validity_t
2861 The @code{gpgme_validity_t} type is used to specify the validity of a user ID
2862 in a key.  The following validities are defined:
2863
2864 @table @code
2865 @item GPGME_VALIDITY_UNKNOWN
2866 The user ID is of unknown validity.  The string representation of this
2867 validity is ``?''.
2868
2869 @item GPGME_VALIDITY_UNDEFINED
2870 The validity of the user ID is undefined.  The string representation of this
2871 validity is ``q''.
2872
2873 @item GPGME_VALIDITY_NEVER
2874 The user ID is never valid.  The string representation of this
2875 validity is ``n''.
2876
2877 @item GPGME_VALIDITY_MARGINAL
2878 The user ID is marginally valid.  The string representation of this
2879 validity is ``m''.
2880
2881 @item GPGME_VALIDITY_FULL
2882 The user ID is fully valid.  The string representation of this
2883 validity is ``f''.
2884
2885 @item GPGME_VALIDITY_ULTIMATE
2886 The user ID is ultimately valid.  The string representation of this
2887 validity is ``u''.
2888 @end table
2889 @end deftp
2890
2891
2892 The following interfaces are deprecated and only provided for backward
2893 compatibility.  Don't use them.  They will be removed in a future
2894 version of @acronym{GPGME}.
2895
2896 @deftp {Data type} gpgme_attr_t
2897 The @code{gpgme_attr_t} type is used to specify a key or trust item
2898 attribute.  The following attributes are defined:
2899
2900 @table @code
2901 @item GPGME_ATTR_KEYID
2902 This is the key ID of a sub key.  It is representable as a string.
2903
2904 For trust items, the trust item refers to the key with this ID.
2905
2906 @item GPGME_ATTR_FPR
2907 This is the fingerprint of a sub key.  It is representable as a
2908 string.
2909
2910 @item GPGME_ATTR_ALGO
2911 This is the crypto algorithm for which the sub key can be used.  It
2912 is representable as a string and as a number.  The numbers correspond
2913 to the @code{enum gcry_pk_algos} values in the gcrypt library.
2914
2915 @item GPGME_ATTR_LEN
2916 This is the key length of a sub key.  It is representable as a
2917 number.
2918
2919 @item GPGME_ATTR_CREATED
2920 This is the timestamp at creation time of a sub key.  It is
2921 representable as a number.
2922
2923 @item GPGME_ATTR_EXPIRE
2924 This is the expiration time of a sub key.  It is representable as a
2925 number.
2926
2927 @item GPGME_ATTR_OTRUST
2928 XXX FIXME  (also for trust items)
2929
2930 @item GPGME_ATTR_USERID
2931 This is a user ID.  There can be more than one user IDs in a
2932 @var{gpgme_key_t} object.  The first one (with index 0) is the primary
2933 user ID.  The user ID is representable as a number.
2934
2935 For trust items, this is the user ID associated with this trust item.
2936
2937 @item GPGME_ATTR_NAME
2938 This is the name belonging to a user ID.  It is representable as a string.
2939
2940 @item GPGME_ATTR_EMAIL
2941 This is the email address belonging to a user ID.  It is representable
2942 as a string.
2943
2944 @item GPGME_ATTR_COMMENT
2945 This is the comment belonging to a user ID.  It is representable as a
2946 string.
2947
2948 @item GPGME_ATTR_VALIDITY
2949 This is the validity belonging to a user ID.  It is representable as a
2950 string and as a number.  See below for a list of available validities.
2951
2952 For trust items, this is the validity that is associated with this
2953 trust item.
2954
2955 @item GPGME_ATTR_UID_REVOKED
2956 This specifies if a user ID is revoked.  It is representable as a
2957 number, and is @code{1} if the user ID is revoked, and @code{0}
2958 otherwise.
2959
2960 @item GPGME_ATTR_UID_INVALID
2961 This specifies if a user ID is invalid.  It is representable as a
2962 number, and is @code{1} if the user ID is invalid, and @code{0}
2963 otherwise.
2964
2965 @item GPGME_ATTR_LEVEL
2966 This is the trust level of a trust item.
2967
2968 @item GPGME_ATTR_TYPE
2969 This returns information about the type of key.  For the string function
2970 this will eother be "PGP" or "X.509".  The integer function returns 0
2971 for PGP and 1 for X.509.  It is also used for the type of a trust item.
2972
2973 @item GPGME_ATTR_IS_SECRET
2974 This specifies if the key is a secret key.  It is representable as a
2975 number, and is @code{1} if the key is revoked, and @code{0} otherwise.
2976
2977 @item GPGME_ATTR_KEY_REVOKED
2978 This specifies if a sub key is revoked.  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_INVALID
2982 This specifies if a sub key is invalid.  It is representable as a
2983 number, and is @code{1} if the key is invalid, and @code{0} otherwise.
2984
2985 @item GPGME_ATTR_KEY_EXPIRED
2986 This specifies if a sub key is expired.  It is representable as a
2987 number, and is @code{1} if the key is expired, and @code{0} otherwise.
2988
2989 @item GPGME_ATTR_KEY_DISABLED
2990 This specifies if a sub key is disabled.  It is representable as a
2991 number, and is @code{1} if the key is disabled, and @code{0} otherwise.
2992
2993 @item GPGME_ATTR_KEY_CAPS
2994 This is a description of the capabilities of a sub key.  It is
2995 representable as a string.  The string contains the letter ``e'' if
2996 the key can be used for encryption, ``s'' if the key can be used for
2997 signatures, and ``c'' if the key can be used for certifications.
2998
2999 @item GPGME_ATTR_CAN_ENCRYPT
3000 This specifies if a sub key can be used for encryption.  It is
3001 representable as a number, and is @code{1} if the sub key can be used
3002 for encryption, and @code{0} otherwise.
3003
3004 @item GPGME_ATTR_CAN_SIGN
3005 This specifies if a sub key can be used to create data signatures.  It
3006 is representable as a number, and is @code{1} if the sub key can be
3007 used for signatures, and @code{0} otherwise.
3008
3009 @item GPGME_ATTR_CAN_CERTIFY
3010 This specifies if a sub key can be used to create key certificates.
3011 It is representable as a number, and is @code{1} if the sub key can be
3012 used for certifications, and @code{0} otherwise.
3013
3014 @item GPGME_ATTR_SERIAL
3015 The X.509 issuer serial attribute of the key.  It is representable as
3016 a string.
3017
3018 @item GPGME_ATTR_ISSUE
3019 The X.509 issuer name attribute of the key.  It is representable as a
3020 string.
3021
3022 @item GPGME_ATTR_CHAINID
3023 The X.509 chain ID can be used to build the certification chain.  It
3024 is representable as a string.
3025 @end table
3026 @end deftp
3027
3028 @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}})
3029 The function @code{gpgme_key_get_string_attr} returns the value of the
3030 string-representable attribute @var{what} of key @var{key}.  If the
3031 attribute is an attribute of a sub key or an user ID, @var{idx}
3032 specifies the sub key or user ID of which the attribute value is
3033 returned.  The argument @var{reserved} is reserved for later use and
3034 should be @code{NULL}.
3035
3036 The string returned is only valid as long as the key is valid.
3037
3038 The function returns @code{0} if an attribute can't be returned as a
3039 string, @var{key} is not a valid pointer, @var{idx} out of range,
3040 or @var{reserved} not @code{NULL}.
3041 @end deftypefun
3042
3043 @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}})
3044 The function @code{gpgme_key_get_ulong_attr} returns the value of the
3045 number-representable attribute @var{what} of key @var{key}.  If the
3046 attribute is an attribute of a sub key or an user ID, @var{idx}
3047 specifies the sub key or user ID of which the attribute value is
3048 returned.  The argument @var{reserved} is reserved for later use and
3049 should be @code{NULL}.
3050
3051 The function returns @code{0} if the attribute can't be returned as a
3052 number, @var{key} is not a valid pointer, @var{idx} out of range, or
3053 @var{reserved} not @code{NULL}.
3054 @end deftypefun
3055
3056
3057 @node Key Signatures
3058 @subsection Key Signatures
3059 @cindex key, signatures
3060 @cindex signatures, on a key
3061
3062 The following interfaces are deprecated and only provided for backward
3063 compatibility.  Don't use them.  They will be removed in a future
3064 version of @acronym{GPGME}.
3065
3066 The signatures on a key are only available if the key was retrieved
3067 via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode
3068 enabled, because it is expensive to retrieve all signatures of a key.
3069
3070 So, before using the below interfaces to retrieve the signatures on a
3071 key, you have to make sure that the key was listed with signatures
3072 enabled.  One convenient, but blocking, way to do this is to use the
3073 function @code{gpgme_get_key}.
3074
3075 @deftp {Data type} gpgme_attr_t
3076 The @code{gpgme_attr_t} type is used to specify a key signature
3077 attribute.  The following attributes are defined:
3078
3079 @table @code
3080 @item GPGME_ATTR_KEYID
3081 This is the key ID of the key which was used for the signature.  It is
3082 representable as a string.
3083
3084 @item GPGME_ATTR_ALGO
3085 This is the crypto algorithm used to create the signature.  It is
3086 representable as a string and as a number.  The numbers correspond to
3087 the @code{enum gcry_pk_algos} values in the gcrypt library.
3088
3089 @item GPGME_ATTR_CREATED
3090 This is the timestamp at creation time of the signature.  It is
3091 representable as a number.
3092
3093 @item GPGME_ATTR_EXPIRE
3094 This is the expiration time of the signature.  It is representable as
3095 a number.
3096
3097 @item GPGME_ATTR_USERID
3098 This is the user ID associated with the signing key.  The user ID is
3099 representable as a number.
3100
3101 @item GPGME_ATTR_NAME
3102 This is the name belonging to a user ID.  It is representable as a string.
3103
3104 @item GPGME_ATTR_EMAIL
3105 This is the email address belonging to a user ID.  It is representable
3106 as a string.
3107
3108 @item GPGME_ATTR_COMMENT
3109 This is the comment belonging to a user ID.  It is representable as a
3110 string.
3111
3112 @item GPGME_ATTR_KEY_REVOKED
3113 This specifies if a key signature is a revocation signature.  It is
3114 representable as a number, and is @code{1} if the key is revoked, and
3115 @code{0} otherwise.
3116
3117 @c @item GPGME_ATTR_KEY_EXPIRED
3118 @c This specifies if a key signature is expired.  It is representable as
3119 @c a number, and is @code{1} if the key is revoked, and @code{0}
3120 @c otherwise.
3121 @c
3122 @item GPGME_ATTR_SIG_CLASS
3123 This specifies the signature class of a key signature.  It is
3124 representable as a number.  The meaning is specific to the crypto
3125 engine.
3126
3127 @item GPGME_ATTR_SIG_CLASS
3128 This specifies the signature class of a key signature.  It is
3129 representable as a number.  The meaning is specific to the crypto
3130 engine.
3131
3132 @item GPGME_ATTR_SIG_STATUS
3133 This is the same value as returned by @code{gpgme_get_sig_status}.
3134 @end table
3135 @end deftp
3136
3137 @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}})
3138 The function @code{gpgme_key_sig_get_string_attr} returns the value of
3139 the string-representable attribute @var{what} of the signature
3140 @var{idx} on the user ID @var{uid_idx} in the key @var{key}.  The
3141 argument @var{reserved} is reserved for later use and should be
3142 @code{NULL}.
3143
3144 The string returned is only valid as long as the key is valid.
3145
3146 The function returns @code{0} if an attribute can't be returned as a
3147 string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx}
3148 out of range, or @var{reserved} not @code{NULL}.
3149 @end deftypefun
3150
3151 @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}})
3152 The function @code{gpgme_key_sig_get_ulong_attr} returns the value of
3153 the number-representable attribute @var{what} of the signature
3154 @var{idx} on the user ID @var{uid_idx} in the key @var{key}.  The
3155 argument @var{reserved} is reserved for later use and should be
3156 @code{NULL}.
3157
3158 The function returns @code{0} if an attribute can't be returned as a
3159 string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx}
3160 out of range, or @var{reserved} not @code{NULL}.
3161 @end deftypefun
3162
3163
3164 @node Manipulating Keys
3165 @subsection Manipulating Keys
3166 @cindex key, manipulation
3167
3168 @deftypefun void gpgme_key_ref (@w{gpgme_key_t @var{key}})
3169 The function @code{gpgme_key_ref} acquires an additional reference for
3170 the key @var{key}.
3171 @end deftypefun
3172
3173 @deftypefun void gpgme_key_unref (@w{gpgme_key_t @var{key}})
3174 The function @code{gpgme_key_unref} releases a reference for the key
3175 @var{key}.  If this was the last reference, the key will be destroyed
3176 and all resources associated to it will be released.
3177 @end deftypefun
3178
3179
3180 The following interface is deprecated and only provided for backward
3181 compatibility.  Don't use it.  It will be removed in a future version
3182 of @acronym{GPGME}.
3183
3184 @deftypefun void gpgme_key_release (@w{gpgme_key_t @var{key}})
3185 The function @code{gpgme_key_release} is equivalent to
3186 @code{gpgme_key_unref}.
3187 @end deftypefun
3188
3189
3190 @node Generating Keys
3191 @subsection Generating Keys
3192 @cindex key, creation
3193 @cindex key ring, add
3194
3195 @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}})
3196 The function @code{gpgme_op_genkey} generates a new key pair in the
3197 context @var{ctx}.  The meaning of @var{public} and @var{secret}
3198 depends on the crypto backend.
3199
3200 GnuPG does not support @var{public} and @var{secret}, they should be
3201 @code{NULL}.  GnuPG will generate a key pair and add it to the
3202 standard key ring.  The fingerprint of the generated key is available
3203 with @code{gpgme_op_genkey_result}.
3204
3205 GpgSM requires @var{public} to be a writable data object.  GpgSM will
3206 generate a secret key (which will be stored by @command{gpg-agent},
3207 and return a certificate request in @var{public}, which then needs to
3208 be signed by the certification authority and imported before it can be
3209 used.  GpgSM does not make the fingerprint available.
3210
3211 The argument @var{parms} specifies parameters for the key in an XML
3212 string.  The details about the format of @var{parms} are specific to
3213 the crypto engine used by @var{ctx}.  Here is an example for GnuPG as
3214 the crypto engine:
3215
3216 @example
3217 <GnupgKeyParms format="internal">
3218 Key-Type: DSA
3219 Key-Length: 1024
3220 Subkey-Type: ELG-E
3221 Subkey-Length: 1024
3222 Name-Real: Joe Tester
3223 Name-Comment: with stupid passphrase
3224 Name-Email: joe@@foo.bar
3225 Expire-Date: 0
3226 Passphrase: abc
3227 </GnupgKeyParms>
3228 @end example
3229
3230 Here is an example for GpgSM as the crypto engine:
3231
3232 @example
3233 <GnupgKeyParms format="internal">
3234 Key-Type: RSA
3235 Key-Length: 1024
3236 Name-DN: C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester
3237 Name-Email: joe@@foo.bar
3238 </GnupgKeyParms>
3239 @end example
3240
3241 Strings should be given in UTF-8 encoding.  The only format supported
3242 for now is ``internal''.  The content of the @code{GnupgKeyParms}
3243 container is passed verbatim to the crypto backend.  Control
3244 statements are not allowed.
3245
3246 After the operation completed successfully, the result can be
3247 retrieved with @code{gpgme_op_genkey_result}.
3248
3249 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3250 operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
3251 @var{parms} is not a valid XML string, @code{GPG_ERR_NOT_SUPPORTED} if
3252 @var{public} or @var{secret} is not valid, and @code{GPG_ERR_GENERAL}
3253 if no key was created by the backend.
3254 @end deftypefun
3255
3256 @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}})
3257 The function @code{gpgme_op_genkey_start} initiates a
3258 @code{gpgme_op_genkey} operation.  It can be completed by calling
3259 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
3260
3261 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3262 operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
3263 @var{parms} is not a valid XML string, and
3264 @code{GPG_ERR_NOT_SUPPORTED} if @var{public} or @var{secret} is not
3265 @code{NULL}.
3266 @end deftypefun
3267
3268 @deftp {Data type} {gpgme_genkey_result_t}
3269 This is a pointer to a structure used to store the result of a
3270 @code{gpgme_op_genkey} operation.  After successfully generating a
3271 key, you can retrieve the pointer to the result with
3272 @code{gpgme_op_genkey_result}.  The structure contains the following
3273 members:
3274
3275 @table @code
3276 @item unsigned int primary : 1
3277 This is a flag that is set to 1 if a primary key was created and to 0
3278 if not.
3279
3280 @item unsigned int sub : 1
3281 This is a flag that is set to 1 if a subkey was created and to 0
3282 if not.
3283
3284 @item char *fpr
3285 This is the fingerprint of the key that was created.  If both a
3286 primary and a sub key were generated, the fingerprint of the primary
3287 key will be returned.  If the crypto engine does not provide the
3288 fingerprint, @code{fpr} will be a null pointer.
3289 @end table
3290 @end deftp
3291
3292 @deftypefun gpgme_genkey_result_t gpgme_op_genkey_result (@w{gpgme_ctx_t @var{ctx}})
3293 The function @code{gpgme_op_genkey_result} returns a
3294 @code{gpgme_genkey_result_t} pointer to a structure holding the result of
3295 a @code{gpgme_op_genkey} operation.  The pointer is only valid if the
3296 last operation on the context was a @code{gpgme_op_genkey} or
3297 @code{gpgme_op_genkey_start} operation, and if this operation finished
3298 successfully.  The returned pointer is only valid until the next
3299 operation is started on the context.
3300 @end deftypefun
3301
3302
3303 @node Exporting Keys
3304 @subsection Exporting Keys
3305 @cindex key, export
3306 @cindex key ring, export from
3307
3308 @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}})
3309 The function @code{gpgme_op_export} extracts public keys and returns
3310 them in the data buffer @var{keydata}.  The output format of the key
3311 data returned is determined by the @acronym{ASCII} armor attribute set
3312 for the context @var{ctx}, or, if that is not set, by the encoding
3313 specified for @var{keydata}.
3314
3315 If @var{pattern} is @code{NULL}, all available keys are returned.
3316 Otherwise, @var{pattern} contains an engine specific expression that
3317 is used to limit the list to all keys matching the pattern.
3318
3319 @var{reserved} is reserved for future use and must be @code{0}.
3320
3321 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3322 operation completed successfully, @code{GPG_ERR_INV_VALUE} if
3323 @var{keydata} is not a valid empty data buffer, and passes through any
3324 errors that are reported by the crypto engine support routines.
3325 @end deftypefun
3326
3327 @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}})
3328 The function @code{gpgme_op_export_start} initiates a
3329 @code{gpgme_op_export} operation.  It can be completed by calling
3330 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
3331
3332 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3333 operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
3334 if @var{keydata} is not a valid empty data buffer.
3335 @end deftypefun
3336
3337 @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}})
3338 The function @code{gpgme_op_export} extracts public keys and returns
3339 them in the data buffer @var{keydata}.  The output format of the key
3340 data returned is determined by the @acronym{ASCII} armor attribute set
3341 for the context @var{ctx}, or, if that is not set, by the encoding
3342 specified for @var{keydata}.
3343
3344 If @var{pattern} or @var{*pattern} is @code{NULL}, all available keys
3345 are returned.  Otherwise, @var{pattern} is a @code{NULL} terminated
3346 array of strings that are used to limit the list to all keys matching
3347 at least one of the patterns verbatim.
3348
3349 @var{reserved} is reserved for future use and must be @code{0}.
3350
3351 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3352 operation completed successfully, @code{GPG_ERR_INV_VALUE} if
3353 @var{keydata} is not a valid empty data buffer, and passes through any
3354 errors that are reported by the crypto engine support routines.
3355 @end deftypefun
3356
3357 @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}})
3358 The function @code{gpgme_op_export_ext_start} initiates a
3359 @code{gpgme_op_export_ext} operation.  It can be completed by calling
3360 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
3361
3362 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3363 operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
3364 if @var{keydata} is not a valid empty data buffer.
3365 @end deftypefun
3366
3367
3368 @node Importing Keys
3369 @subsection Importing Keys
3370 @cindex key, import
3371 @cindex key ring, import to
3372
3373 @deftypefun gpgme_error_t gpgme_op_import (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}})
3374 The function @code{gpgme_op_import} adds the keys in the data buffer
3375 @var{keydata} to the key ring of the crypto engine used by @var{ctx}.
3376 The format of @var{keydata} can be @acronym{ASCII} armored, for example,
3377 but the details are specific to the crypto engine.
3378
3379 After the operation completed successfully, the result can be
3380 retrieved with @code{gpgme_op_import_result}.
3381
3382 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3383 import was completed successfully, @code{GPG_ERR_INV_VALUE} if
3384 @var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer,
3385 and @code{GPG_ERR_NO_DATA} if @var{keydata} is an empty data buffer.
3386 @end deftypefun
3387
3388 @deftypefun gpgme_error_t gpgme_op_import_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}})
3389 The function @code{gpgme_op_import_start} initiates a
3390 @code{gpgme_op_import} operation.  It can be completed by calling
3391 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
3392
3393 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3394 import could be started successfully, @code{GPG_ERR_INV_VALUE} if
3395 @var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer,
3396 and @code{GPG_ERR_NO_DATA} if @var{keydata} is an empty data buffer.
3397 @end deftypefun
3398
3399 @deftp {Data type} {gpgme_import_status_t}
3400 This is a pointer to a structure used to store a part of the result of
3401 a @code{gpgme_op_import} operation.  For each considered key one
3402 status is added that contains information about the result of the
3403 import.  The structure contains the following members:
3404
3405 @table @code
3406 @item gpgme_import_status_t next
3407 This is a pointer to the next status structure in the linked list, or
3408 @code{NULL} if this is the last element.
3409
3410 @item char *fpr
3411 This is the fingerprint of the key that was considered.
3412
3413 @item gpgme_error_t result
3414 If the import was not successful, this is the error value that caused
3415 the import to fail.  Otherwise the error code is
3416 @code{GPG_ERR_NO_ERROR}.
3417
3418 @item unsigned int status
3419 This is a bit-wise OR of the following flags that give more
3420 information about what part of the key was imported.  If the key was
3421 already known, this might be 0.
3422
3423 @table @code
3424 @item GPGME_IMPORT_NEW
3425 The key was new.
3426
3427 @item GPGME_IMPORT_UID
3428 The key contained new user IDs.
3429
3430 @item GPGME_IMPORT_SIG
3431 The key contained new signatures.
3432
3433 @item GPGME_IMPORT_SUBKEY
3434 The key contained new sub keys.
3435
3436 @item GPGME_IMPORT_SECRET
3437 The key contained a secret key.
3438 @end table
3439 @end table
3440 @end deftp
3441
3442 @deftp {Data type} {gpgme_import_result_t}
3443 This is a pointer to a structure used to store the result of a
3444 @code{gpgme_op_import} operation.  After a successful import
3445 operation, you can retrieve the pointer to the result with
3446 @code{gpgme_op_import_result}.  The structure contains the following
3447 members:
3448
3449 @table @code
3450 @item int considered
3451 The total number of considered keys.
3452
3453 @item int no_user_id
3454 The number of keys without user ID.
3455
3456 @item int imported
3457 The total number of imported keys.
3458
3459 @item imported_rsa
3460 The number of imported RSA keys.
3461
3462 @item unchanged
3463 The number of unchanged keys.
3464
3465 @item new_user_ids
3466 The number of new user IDs.
3467
3468 @item new_sub_keys
3469 The number of new sub keys.
3470
3471 @item new_signatures
3472 The number of new signatures.
3473
3474 @item new_revocations
3475 The number of new revocations.
3476
3477 @item secret_read
3478 The total number of secret keys read.
3479
3480 @item secret_imported
3481 The number of imported secret keys.
3482
3483 @item secret_unchanged
3484 The number of unchanged secret keys.
3485
3486 @item not_imported
3487 The number of keys not imported.
3488
3489 @item gpgme_import_status_t imports
3490 A list of gpgme_import_status_t objects which contain more information
3491 about the keys for which an import was attempted.
3492 @end table
3493 @end deftp
3494
3495 @deftypefun gpgme_import_result_t gpgme_op_import_result (@w{gpgme_ctx_t @var{ctx}})
3496 The function @code{gpgme_op_import_result} returns a
3497 @code{gpgme_import_result_t} pointer to a structure holding the result
3498 of a @code{gpgme_op_import} operation.  The pointer is only valid if
3499 the last operation on the context was a @code{gpgme_op_import} or
3500 @code{gpgme_op_import_start} operation, and if this operation finished
3501 successfully.  The returned pointer is only valid until the next
3502 operation is started on the context.
3503 @end deftypefun
3504
3505 The following interface is deprecated and only provided for backward
3506 compatibility.  Don't use it.  It will be removed in a future version
3507 of @acronym{GPGME}.
3508
3509 @deftypefun gpgme_error_t gpgme_op_import_ext (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}}, @w{int *@var{nr}})
3510 The function @code{gpgme_op_import_ext} is equivalent to:
3511
3512 @example
3513   gpgme_error_t err = gpgme_op_import (ctx, keydata);
3514   if (!err)
3515     @{
3516       gpgme_import_result_t result = gpgme_op_import_result (ctx);
3517       *nr = result->considered;
3518     @}
3519 @end example
3520 @end deftypefun
3521
3522
3523 @node Deleting Keys
3524 @subsection Deleting Keys
3525 @cindex key, delete
3526 @cindex key ring, delete from
3527
3528 @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}})
3529 The function @code{gpgme_op_delete} deletes the key @var{key} from the
3530 key ring of the crypto engine used by @var{ctx}.  If
3531 @var{allow_secret} is @code{0}, only public keys are deleted,
3532 otherwise secret keys are deleted as well, if that is supported.
3533
3534 The function returns the error code @code{GPG_ERR_NO_ERROR} if the key
3535 was deleted successfully, @code{GPG_ERR_INV_VALUE} if @var{ctx} or
3536 @var{key} is not a valid pointer, @code{GPG_ERR_NO_PUBKEY} if
3537 @var{key} could not be found in the keyring,
3538 @code{GPG_ERR_AMBIGUOUS_NAME} if the key was not specified
3539 unambiguously, and @code{GPG_ERR_CONFLICT} if the secret key for
3540 @var{key} is available, but @var{allow_secret} is zero.
3541 @end deftypefun
3542
3543 @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}})
3544 The function @code{gpgme_op_delete_start} initiates a
3545 @code{gpgme_op_delete} operation.  It can be completed by calling
3546 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
3547
3548 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3549 operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
3550 @var{ctx} or @var{key} is not a valid pointer.
3551 @end deftypefun
3552
3553
3554 @node Advanced Key Editing
3555 @subsection Advanced Key Editing
3556 @cindex key, edit
3557
3558 @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}})}
3559 @tindex gpgme_edit_cb_t
3560 The @code{gpgme_edit_cb_t} type is the type of functions which
3561 @acronym{GPGME} calls if it a key edit operation is on-going.  The
3562 status code @var{status} and the argument line @var{args} are passed
3563 through by @acronym{GPGME} from the crypto engine.  The file
3564 descriptor @var{fd} is -1 for normal status messages.  If @var{status}
3565 indicates a command rather than a status message, the response to the
3566 command should be written to @var{fd}.  The @var{handle} is provided
3567 by the user at start of operation.
3568
3569 The function should return @code{GPG_ERR_NO_ERROR} or an error value.
3570 @end deftp
3571
3572 @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}})
3573 The function @code{gpgme_op_edit} processes the key @var{KEY}
3574 interactively, using the edit callback function @var{FNC} with the
3575 handle @var{HANDLE}.  The callback is invoked for every status and
3576 command request from the crypto engine.  The output of the crypto
3577 engine is written to the data object @var{out}.
3578
3579 Note that the protocol between the callback function and the crypto
3580 engine is specific to the crypto engine and no further support in
3581 implementing this protocol correctly is provided by @acronym{GPGME}.
3582
3583 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3584 edit operation completes successfully, @code{GPG_ERR_INV_VALUE} if
3585 @var{ctx} or @var{key} is not a valid pointer, and any error returned
3586 by the crypto engine or the edit callback handler.
3587 @end deftypefun
3588
3589 @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}})
3590 The function @code{gpgme_op_edit_start} initiates a
3591 @code{gpgme_op_edit} operation.  It can be completed by calling
3592 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
3593
3594 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3595 operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
3596 @var{ctx} or @var{key} is not a valid pointer.
3597 @end deftypefun
3598
3599
3600 @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}})
3601 The function @code{gpgme_op_card_edit} is analogous to
3602 @code{gpgme_op_edit}, but should be used to process the smart card corresponding to the key @var{key}.
3603 @end deftypefun
3604
3605 @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}})
3606 The function @code{gpgme_op_card_edit_start} initiates a
3607 @code{gpgme_op_card_edit} operation.  It can be completed by calling
3608 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
3609
3610 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3611 operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
3612 @var{ctx} or @var{key} is not a valid pointer.
3613 @end deftypefun
3614
3615
3616 @node Trust Item Management
3617 @section Trust Item Management
3618 @cindex trust item
3619
3620 @strong{Caution:} The trust items interface is experimental.
3621
3622 @deftp {Data type} gpgme_trust_item_t
3623 The @code{gpgme_trust_item_t} type is a pointer to a trust item object.
3624 It has the following members:
3625
3626 @table @code
3627 @item char *keyid
3628 This is a string describing the key to which this trust items belongs.
3629
3630 @item int type
3631 This is the type of the trust item.  A value of 1 refers to a key, a
3632 value of 2 refers to a user ID.
3633
3634 @item int level
3635 This is the trust level.
3636
3637 @item char *owner_trust
3638 The owner trust if @code{type} is 1.
3639
3640 @item char *validity
3641 The calculated validity.
3642
3643 @item char *name
3644 The user name if @code{type} is 2.
3645 @end table
3646 @end deftp
3647
3648 @menu
3649 * Listing Trust Items::           Browsing the list of available trust items.
3650 * Information About Trust Items:: Requesting information about trust items.
3651 * Manipulating Trust Items::      Operations on trust items.
3652 @end menu
3653
3654
3655 @node Listing Trust Items
3656 @subsection Listing Trust Items
3657 @cindex trust item list
3658
3659 @deftypefun gpgme_error_t gpgme_op_trustlist_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{max_level}})
3660 The function @code{gpgme_op_trustlist_start} initiates a trust item
3661 listing operation inside the context @var{ctx}.  It sets everything up
3662 so that subsequent invocations of @code{gpgme_op_trustlist_next} return
3663 the trust items in the list.
3664
3665 The string @var{pattern} contains an engine specific expression that
3666 is used to limit the list to all trust items matching the pattern.  It
3667 can not be the empty string.
3668
3669 The argument @var{max_level} is currently ignored.
3670
3671 The context will be busy until either all trust items are received
3672 (and @code{gpgme_op_trustlist_next} returns @code{GPG_ERR_EOF}), or
3673 @code{gpgme_op_trustlist_end} is called to finish the operation.
3674
3675 The function returns the error code @code{GPG_ERR_INV_VALUE} if
3676 @var{ctx} is not a valid pointer, and passes through any errors that
3677 are reported by the crypto engine support routines.
3678 @end deftypefun
3679
3680 @deftypefun gpgme_error_t gpgme_op_trustlist_next (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_trust_item_t *@var{r_item}})
3681 The function @code{gpgme_op_trustlist_next} returns the next trust
3682 item in the list created by a previous @code{gpgme_op_trustlist_start}
3683 operation in the context @var{ctx}.  The trust item can be destroyed
3684 with @code{gpgme_trust_item_release}.  @xref{Manipulating Trust Items}.
3685
3686 This is the only way to get at @code{gpgme_trust_item_t} objects in
3687 @acronym{GPGME}.
3688
3689 If the last trust item in the list has already been returned,
3690 @code{gpgme_op_trustlist_next} returns @code{GPG_ERR_EOF}.
3691
3692 The function returns the error code @code{GPG_ERR_INV_VALUE} if @var{ctx} or
3693 @var{r_item} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if
3694 there is not enough memory for the operation.
3695 @end deftypefun
3696
3697 @deftypefun gpgme_error_t gpgme_op_trustlist_end (@w{gpgme_ctx_t @var{ctx}})
3698 The function @code{gpgme_op_trustlist_next} ends a pending key list
3699 operation in the context @var{ctx}.
3700
3701 The function returns the error code @code{GPG_ERR_INV_VALUE} if