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