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