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