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