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