core: New API gpgme_op_set_uid_flag.
[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--2016 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} whis pinentry
2601 queries redirected to gpgme.
2602
2603 Note: This mode requires @code{allow-loopback-pinentry} to be enabled
2604 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 @end deftp
2767
2768 @deftypefun void gpgme_set_passphrase_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_passphrase_cb_t @var{passfunc}}, @w{void *@var{hook_value}})
2769 The function @code{gpgme_set_passphrase_cb} sets the function that is
2770 used when a passphrase needs to be provided by the user to
2771 @var{passfunc}.  The function @var{passfunc} needs to implemented by
2772 the user, and whenever it is called, it is called with its first
2773 argument being @var{hook_value}.  By default, no passphrase callback
2774 function is set.
2775
2776 Not all crypto engines require this callback to retrieve the
2777 passphrase.  It is better if the engine retrieves the passphrase from
2778 a trusted agent (a daemon process), rather than having each user to
2779 implement their own passphrase query.  Some engines do not even
2780 support an external passphrase callback at all, in this case the error
2781 code @code{GPG_ERR_NOT_SUPPORTED} is returned.
2782
2783 For GnuPG >= 2.1 the pinentry mode has to be set to
2784 @code{GPGME_PINENTRY_MODE_LOOPBACK} to enable the passphrase callback.
2785 See @code{gpgme_set_pinentry_mode}.
2786
2787 The user can disable the use of a passphrase callback function by
2788 calling @code{gpgme_set_passphrase_cb} with @var{passfunc} being
2789 @code{NULL}.
2790 @end deftypefun
2791
2792 @deftypefun void gpgme_get_passphrase_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_passphrase_cb_t *@var{passfunc}}, @w{void **@var{hook_value}})
2793 The function @code{gpgme_get_passphrase_cb} returns the function that
2794 is used when a passphrase needs to be provided by the user in
2795 @var{*passfunc}, and the first argument for this function in
2796 @var{*hook_value}.  If no passphrase callback is set, or @var{ctx} is
2797 not a valid pointer, @code{NULL} is returned in both variables.
2798
2799 @var{passfunc} or @var{hook_value} can be @code{NULL}.  In this case,
2800 the corresponding value will not be returned.
2801 @end deftypefun
2802
2803
2804 @node Progress Meter Callback
2805 @subsection Progress Meter Callback
2806 @cindex callback, progress meter
2807 @cindex progress meter callback
2808
2809 @deftp {Data type} {void (*gpgme_progress_cb_t)(void *@var{hook}, const char *@var{what}, int @var{type}, int @var{current}, int @var{total})}
2810 @tindex gpgme_progress_cb_t
2811 The @code{gpgme_progress_cb_t} type is the type of functions usable as
2812 progress callback function.
2813
2814 The arguments are specific to the crypto engine.  More information
2815 about the progress information returned from the GnuPG engine can be
2816 found in the GnuPG source code in the file @file{doc/DETAILS} in the
2817 section PROGRESS.
2818 @end deftp
2819
2820 @deftypefun void gpgme_set_progress_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_progress_cb_t @var{progfunc}}, @w{void *@var{hook_value}})
2821 The function @code{gpgme_set_progress_cb} sets the function that is
2822 used when progress information about a cryptographic operation is
2823 available.  The function @var{progfunc} needs to implemented by the
2824 user, and whenever it is called, it is called with its first argument
2825 being @var{hook_value}.  By default, no progress callback function
2826 is set.
2827
2828 Setting a callback function allows an interactive program to display
2829 progress information about a long operation to the user.
2830
2831 The user can disable the use of a progress callback function by
2832 calling @code{gpgme_set_progress_cb} with @var{progfunc} being
2833 @code{NULL}.
2834 @end deftypefun
2835
2836 @deftypefun void gpgme_get_progress_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_progress_cb_t *@var{progfunc}}, @w{void **@var{hook_value}})
2837 The function @code{gpgme_get_progress_cb} returns the function that is
2838 used to inform the user about the progress made in @var{*progfunc},
2839 and the first argument for this function in @var{*hook_value}.  If no
2840 progress callback is set, or @var{ctx} is not a valid pointer,
2841 @code{NULL} is returned in both variables.
2842
2843 @var{progfunc} or @var{hook_value} can be @code{NULL}.  In this case,
2844 the corresponding value will not be returned.
2845 @end deftypefun
2846
2847
2848 @node Status Message Callback
2849 @subsection Status Message Callback
2850 @cindex callback, status message
2851 @cindex status message callback
2852
2853 @deftp {Data type} {gpgme_error_t (*gpgme_status_cb_t)(void *@var{hook}, const char *@var{keyword}, const char *@var{args})}
2854 @tindex gpgme_status_cb_t
2855 The @code{gpgme_status_cb_t} type is the type of function usable as
2856 a status message callback function.
2857
2858 The argument @var{keyword} is the name of the status message while the
2859 @var{args} argument contains any arguments for the status message.
2860
2861 If an error occurs, return the corresponding @code{gpgme_error_t}
2862 value. Otherwise, return @code{0}.
2863 @end deftp
2864
2865 @deftypefun void gpgme_set_status_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_status_cb_t @var{statusfunc}}, @w{void *@var{hook_value}})
2866 The function @code{gpgme_set_status_cb} sets the function that is used when a
2867 status message is received from gpg to @var{statusfunc}. The function
2868 @var{statusfunc} needs to be implemented by the user, and whenever it is
2869 called, it is called with its first argument being @var{hook_value}.  By
2870 default, no status message callback function is set.
2871
2872 The user can disable the use of a status message callback function by calling
2873 @code{gpgme_set_status_cb} with @var{statusfunc} being @code{NULL}.
2874 @end deftypefun
2875
2876 @deftypefun void gpgme_get_status_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_status_cb_t *@var{statusfunc}}, @w{void **@var{hook_value}})
2877 The function @code{gpgme_get_status_cb} returns the function that is used to
2878 process status messages from gpg in @var{*statusfunc}, and the first argument
2879 for this function in @var{*hook_value}.  If no status message callback is set,
2880 or @var{ctx} is not a valid pointer, @code{NULL} is returned in both
2881 variables.
2882 @end deftypefun
2883
2884 @deftypefun {gpgme_error_t} gpgme_set_ctx_flag  @
2885             (@w{gpgme_ctx_t @var{ctx}}, @
2886             @w{const char *@var{name}}, @
2887             @w{const char *@var{value}})
2888
2889 Some minor properties of the context can be controlled with flags set
2890 by this function.  The properties are identified by the following
2891 values for @var{name}:
2892
2893 @table @code
2894 @item "redraw"
2895 This flag is normally not changed by the caller because GPGME sets and
2896 clears it automatically: The flag is cleared before an operation and
2897 set if an operation noticed that the engine has launched a Pinentry.
2898 A Curses based application may use this information to redraw the
2899 screen; for example:
2900
2901 @example
2902     err = gpgme_op_keylist_start (ctx, "foo@@example.org", 0);
2903     while (!err)
2904       @{
2905         err = gpgme_op_keylist_next (ctx, &key);
2906         if (err)
2907           break;
2908         show_key (key);
2909         gpgme_key_release (key);
2910       @}
2911     if ((s = gpgme_get_ctx_flag (ctx, "redraw")) && *s)
2912       redraw_screen ();
2913     gpgme_release (ctx);
2914 @end example
2915
2916
2917 @item "full-status"
2918 Using a @var{value} of "1" the status callback set by
2919 gpgme_set_status_cb returns all status lines with the exception of
2920 PROGRESS lines.  With the default of "0" the status callback is only
2921 called in certain situations.
2922
2923 @item "raw-description"
2924 Setting the @var{value} to "1" returns human readable strings in a raw
2925 format.  For example the non breaking space characters ("~") will not
2926 be removed from the @code{description} field of the
2927 @code{gpgme_tofu_info_t} object.
2928
2929 @item "export-session-key"
2930 Using a @var{value} of "1" specifies that the context should try to
2931 export the symmetric session key when decrypting data.  By default, or
2932 when using an empty string or "0" for @var{value}, session keys are
2933 not exported.
2934
2935 @item "override-session-key"
2936 The string given in @var{value} is passed to the GnuPG engine to override
2937 the session key for decryption.  The format of that session key is
2938 specific to GnuPG and can be retrieved during a decrypt operation when
2939 the context flag "export-session-key" is enabled.  Please be aware that
2940 using this feature with GnuPG < 2.1.16 will leak the session key on
2941 many platforms via ps(1).
2942
2943 @end table
2944
2945 This function returns @code{0} on success.
2946 @end deftypefun
2947
2948
2949 @deftypefun {const char *} gpgme_get_ctx_flag  @
2950             (@w{gpgme_ctx_t @var{ctx}}, @
2951             @w{const char *@var{name}})
2952
2953 The value of flags settable by @code{gpgme_set_ctx_flag} can be
2954 retrieved by this function.  If @var{name} is unknown the function
2955 returns @code{NULL}.  For boolean flags an empty string is returned
2956 for False and the string "1" is returned for True; either atoi(3) or a
2957 test for an empty string can be used to get the boolean value.
2958
2959 @end deftypefun
2960
2961
2962 @node Locale
2963 @subsection Locale
2964 @cindex locale, default
2965 @cindex locale, of a context
2966
2967 A locale setting can be associated with a context.  This locale is
2968 passed to the crypto engine, and used for applications like the PIN
2969 entry, which is displayed to the user when entering a passphrase is
2970 required.
2971
2972 The default locale is used to initialize the locale setting of all
2973 contexts created afterwards.
2974
2975 @deftypefun gpgme_error_t gpgme_set_locale (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{category}}, @w{const char *@var{value}})
2976 The function @code{gpgme_set_locale} sets the locale of the context
2977 @var{ctx}, or the default locale if @var{ctx} is a null pointer.
2978
2979 The locale settings that should be changed are specified by
2980 @var{category}.  Supported categories are @code{LC_CTYPE},
2981 @code{LC_MESSAGES}, and @code{LC_ALL}, which is a wildcard you can use
2982 if you want to change all the categories at once.
2983
2984 The value to be used for the locale setting is @var{value}, which will
2985 be copied to @acronym{GPGME}'s internal data structures.  @var{value}
2986 can be a null pointer, which disables setting the locale, and will
2987 make PIN entry and other applications use their default setting, which
2988 is usually not what you want.
2989
2990 Note that the settings are only used if the application runs on a text
2991 terminal, and that the settings should fit the configuration of the
2992 output terminal.  Normally, it is sufficient to initialize the default
2993 value at startup.
2994
2995 The function returns an error if not enough memory is available.
2996 @end deftypefun
2997
2998
2999 @node Key Management
3000 @section Key Management
3001 @cindex key management
3002
3003 Some of the cryptographic operations require that recipients or
3004 signers are specified.  This is always done by specifying the
3005 respective keys that should be used for the operation.  The following
3006 section describes how such keys can be selected and manipulated.
3007
3008
3009 @menu
3010 * Key objects::                   Description of the key structures.
3011 * Listing Keys::                  Browsing the list of available keys.
3012 * Information About Keys::        Requesting detailed information about keys.
3013 * Manipulating Keys::             Operations on keys.
3014 * Generating Keys::               Creating new key pairs.
3015 * Signing Keys::                  Adding key signatures to public keys.
3016 * Exporting Keys::                Retrieving key data from the key ring.
3017 * Importing Keys::                Adding keys to the key ring.
3018 * Deleting Keys::                 Removing keys from the key ring.
3019 * Changing Passphrases::          Change the passphrase of a key.
3020 * Changing TOFU Data::            Changing data pertaining to TOFU.
3021 * Advanced Key Editing::          Advanced key edit operation.
3022 @end menu
3023
3024 @node Key objects
3025 @subsection Key objects
3026
3027 The keys are represented in GPGME by structures which may only be read
3028 by the application but never be allocated or changed.  They are valid
3029 as long as the key object itself is valid.
3030
3031 @deftp {Data type} gpgme_key_t
3032
3033 The @code{gpgme_key_t} type is a pointer to a key object.  It has the
3034 following members:
3035
3036 @table @code
3037 @item gpgme_keylist_mode_t keylist_mode
3038 The keylist mode that was active when the key was retrieved.
3039
3040 @item unsigned int revoked : 1
3041 This is true if the key is revoked.
3042
3043 @item unsigned int expired : 1
3044 This is true if the key is expired.
3045
3046 @item unsigned int disabled : 1
3047 This is true if the key is disabled.
3048
3049 @item unsigned int invalid : 1
3050 This is true if the key is invalid. This might have several reasons,
3051 for a example for the S/MIME backend, it will be set during key
3052 listings if the key could not be validated due to missing
3053 certificates or unmatched policies.
3054
3055 @item unsigned int can_encrypt : 1
3056 This is true if the key (ie one of its subkeys) can be used for
3057 encryption.
3058
3059 @item unsigned int can_sign : 1
3060 This is true if the key (ie one of its subkeys) can be used to create
3061 data signatures.
3062
3063 @item unsigned int can_certify : 1
3064 This is true if the key (ie one of its subkeys) can be used to create
3065 key certificates.
3066
3067 @item unsigned int can_authenticate : 1
3068 This is true if the key (ie one of its subkeys) can be used for
3069 authentication.
3070
3071 @item unsigned int is_qualified : 1
3072 This is true if the key can be used for qualified signatures according
3073 to local government regulations.
3074
3075 @item unsigned int secret : 1
3076 This is true if the key is a secret key.  Note, that this will always
3077 be true even if the corresponding subkey flag may be false
3078 (offline/stub keys).  This is only set if a listing of secret keys has
3079 been requested or if @code{GPGME_KEYLIST_MODE_WITH_SECRET} is active.
3080
3081 @item gpgme_protocol_t protocol
3082 This is the protocol supported by this key.
3083
3084 @item char *issuer_serial
3085 If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
3086 issuer serial.
3087
3088 @item char *issuer_name
3089 If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
3090 issuer name.
3091
3092 @item char *chain_id
3093 If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
3094 chain ID, which can be used to built the certificate chain.
3095
3096 @item gpgme_validity_t owner_trust
3097 If @code{protocol} is @code{GPGME_PROTOCOL_OpenPGP}, then this is the
3098 owner trust.
3099
3100 @item gpgme_subkey_t subkeys
3101 This is a linked list with the subkeys of the key.  The first subkey
3102 in the list is the primary key and usually available.
3103
3104 @item gpgme_user_id_t uids
3105 This is a linked list with the user IDs of the key.  The first user ID
3106 in the list is the main (or primary) user ID.
3107
3108 @item char *fpr
3109 This field gives the fingerprint of the primary key.  Note that
3110 this is a copy of the fingerprint of the first subkey.  For an
3111 incomplete key (for example from a verification result) a subkey may
3112 be missing but this field may be set nevertheless.
3113
3114 @end table
3115 @end deftp
3116
3117
3118 @deftp {Data type} gpgme_subkey_t
3119
3120 The @code{gpgme_subkey_t} type is a pointer to a subkey structure.
3121 Subkeys are one component of a @code{gpgme_key_t} object.  In fact,
3122 subkeys are those parts that contains the real information about the
3123 individual cryptographic keys that belong to the same key object.  One
3124 @code{gpgme_key_t} can contain several subkeys.  The first subkey in
3125 the linked list is also called the primary key.
3126
3127 The subkey structure has the following members:
3128
3129 @table @code
3130 @item gpgme_subkey_t next
3131 This is a pointer to the next subkey structure in the linked list, or
3132 @code{NULL} if this is the last element.
3133
3134 @item unsigned int revoked : 1
3135 This is true if the subkey is revoked.
3136
3137 @item unsigned int expired : 1
3138 This is true if the subkey is expired.
3139
3140 @item unsigned int disabled : 1
3141 This is true if the subkey is disabled.
3142
3143 @item unsigned int invalid : 1
3144 This is true if the subkey is invalid.
3145
3146 @item unsigned int can_encrypt : 1
3147 This is true if the subkey can be used for encryption.
3148
3149 @item unsigned int can_sign : 1
3150 This is true if the subkey can be used to create data signatures.
3151
3152 @item unsigned int can_certify : 1
3153 This is true if the subkey can be used to create key certificates.
3154
3155 @item unsigned int can_authenticate : 1
3156 This is true if the subkey can be used for authentication.
3157
3158 @item unsigned int is_qualified : 1
3159 This is true if the subkey can be used for qualified signatures
3160 according to local government regulations.
3161
3162 @item unsigned int is_de_vs : 1
3163 This is true if the subkey complies with the rules for classified
3164 information in Germany at the restricted level (VS-NfD).  This are
3165 currently RSA keys of at least 2048 bits or ECDH/ECDSA keys using a
3166 Brainpool curve.
3167
3168 @item unsigned int secret : 1
3169 This is true if the subkey is a secret key.  Note that it will be
3170 false if the key is actually a stub key; i.e. a secret key operation
3171 is currently not possible (offline-key).  This is only set if a
3172 listing of secret keys has been requested or if
3173 @code{GPGME_KEYLIST_MODE_WITH_SECRET} is active.
3174
3175 @item gpgme_pubkey_algo_t pubkey_algo
3176 This is the public key algorithm supported by this subkey.
3177
3178 @item unsigned int length
3179 This is the length of the subkey (in bits).
3180
3181 @item char *keyid
3182 This is the key ID of the subkey in hexadecimal digits.
3183
3184 @item char *fpr
3185 This is the fingerprint of the subkey in hexadecimal digits, if
3186 available.
3187
3188 @item char *keygrip
3189 The keygrip of the subkey in hex digit form or @code{NULL} if not
3190 availabale.
3191
3192 @item long int timestamp
3193 This is the creation timestamp of the subkey.  This is -1 if the
3194 timestamp is invalid, and 0 if it is not available.
3195
3196 @item long int expires
3197 This is the expiration timestamp of the subkey, or 0 if the subkey
3198 does not expire.
3199
3200 @item unsigned int is_cardkey : 1
3201 True if the secret key is stored on a smart card.
3202
3203 @item char *card_number
3204 The serial number of a smart card holding this key or @code{NULL}.
3205
3206 @item char *curve
3207 For ECC algorithms the name of the curve.
3208
3209 @end table
3210 @end deftp
3211
3212 @deftp {Data type} gpgme_user_id_t
3213
3214 A user ID is a component of a @code{gpgme_key_t} object.  One key can
3215 have many user IDs.  The first one in the list is the main (or
3216 primary) user ID.
3217
3218 The user ID structure has the following members.
3219
3220 @table @code
3221 @item gpgme_user_id_t next
3222 This is a pointer to the next user ID structure in the linked list, or
3223 @code{NULL} if this is the last element.
3224
3225 @item unsigned int revoked : 1
3226 This is true if the user ID is revoked.
3227
3228 @item unsigned int invalid : 1
3229 This is true if the user ID is invalid.
3230
3231 @item gpgme_validity_t validity
3232 This specifies the validity of the user ID.
3233
3234 @item char *uid
3235 This is the user ID string.
3236
3237 @item char *name
3238 This is the name component of @code{uid}, if available.
3239
3240 @item char *comment
3241 This is the comment component of @code{uid}, if available.
3242
3243 @item char *email
3244 This is the email component of @code{uid}, if available.
3245
3246 @item char *address;
3247 The mail address (addr-spec from RFC-5322) of the user ID string.
3248 This is general the same as the @code{email} part of this structure
3249 but might be slightly different.  If no mail address is available
3250 @code{NULL} is stored.
3251
3252 @item gpgme_tofu_info_t tofu
3253 If not @code{NULL} information from the TOFU database pertaining to
3254 this user id.
3255
3256 @item gpgme_key_sig_t signatures
3257 This is a linked list with the signatures on this user ID.
3258 @end table
3259 @end deftp
3260
3261
3262 @deftp {Data type} gpgme_key_sig_t
3263
3264 The @code{gpgme_key_sig_t} type is a pointer to a key signature structure.
3265 Key signatures are one component of a @code{gpgme_key_t} object, and
3266 validate user IDs on the key in the OpenPGP protocol.
3267
3268 The signatures on a key are only available if the key was retrieved
3269 via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode
3270 enabled, because it can be expensive to retrieve all signatures of a
3271 key.
3272
3273 The signature notations on a key signature are only available if the
3274 key was retrieved via a listing operation with the
3275 @code{GPGME_KEYLIST_MODE_SIG_NOTATIONS} mode enabled, because it can
3276 be expensive to retrieve all signature notations.
3277
3278 The key signature structure has the following members:
3279
3280 @table @code
3281 @item gpgme_key_sig_t next
3282 This is a pointer to the next key signature structure in the linked
3283 list, or @code{NULL} if this is the last element.
3284
3285 @item unsigned int revoked : 1
3286 This is true if the key signature is a revocation signature.
3287
3288 @item unsigned int expired : 1
3289 This is true if the key signature is expired.
3290
3291 @item unsigned int invalid : 1
3292 This is true if the key signature is invalid.
3293
3294 @item unsigned int exportable : 1
3295 This is true if the key signature is exportable.
3296
3297 @item gpgme_pubkey_algo_t pubkey_algo
3298 This is the public key algorithm used to create the signature.
3299
3300 @item char *keyid
3301 This is the key ID of the key (in hexadecimal digits) used to create
3302 the signature.
3303
3304 @item long int timestamp
3305 This is the creation timestamp of the key signature.  This is -1 if
3306 the timestamp is invalid, and 0 if it is not available.
3307
3308 @item long int expires
3309 This is the expiration timestamp of the key signature, or 0 if the key
3310 signature does not expire.
3311
3312 @item gpgme_error_t status
3313 This is the status of the signature and has the same meaning as the
3314 member of the same name in a @code{gpgme_signature_t} object.
3315
3316 @item unsigned int sig_class
3317 This specifies the signature class of the key signature.  The meaning
3318 is specific to the crypto engine.
3319
3320 @item char *uid
3321 This is the main user ID of the key used to create the signature.
3322
3323 @item char *name
3324 This is the name component of @code{uid}, if available.
3325
3326 @item char *comment
3327 This is the comment component of @code{uid}, if available.
3328
3329 @item char *email
3330 This is the email component of @code{uid}, if available.
3331
3332 @item gpgme_sig_notation_t notations
3333 This is a linked list with the notation data and policy URLs.
3334 @end table
3335 @end deftp
3336
3337
3338
3339 @node Listing Keys
3340 @subsection Listing Keys
3341 @cindex listing keys
3342 @cindex key listing
3343 @cindex key listing, start
3344 @cindex key ring, list
3345 @cindex key ring, search
3346
3347 @deftypefun gpgme_error_t gpgme_op_keylist_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}})
3348
3349 The function @code{gpgme_op_keylist_start} initiates a key listing
3350 operation inside the context @var{ctx}.  It sets everything up so that
3351 subsequent invocations of @code{gpgme_op_keylist_next} return the keys
3352 in the list.
3353
3354 If @var{pattern} is @code{NULL}, all available keys are returned.
3355 Otherwise, @var{pattern} contains an engine specific expression that
3356 is used to limit the list to all keys matching the pattern.  Note that
3357 the total length of the pattern is restricted to an engine-specific
3358 maximum (a couple of hundred characters are usually accepted).  The
3359 pattern should be used to restrict the search to a certain common name
3360 or user, not to list many specific keys at once by listing their
3361 fingerprints or key IDs.
3362
3363 If @var{secret_only} is not @code{0}, the list is restricted to secret
3364 keys only.
3365
3366 The context will be busy until either all keys are received (and
3367 @code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}), or
3368 @code{gpgme_op_keylist_end} is called to finish the operation.
3369
3370 The function returns the error code @code{GPG_ERR_INV_VALUE} if
3371 @var{ctx} is not a valid pointer, and passes through any errors that
3372 are reported by the crypto engine support routines.
3373 @end deftypefun
3374
3375 @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}})
3376
3377 The function @code{gpgme_op_keylist_ext_start} initiates an extended
3378 key listing operation inside the context @var{ctx}.  It sets
3379 everything up so that subsequent invocations of
3380 @code{gpgme_op_keylist_next} return the keys in the list.
3381
3382 If @var{pattern} or @var{*pattern} is @code{NULL}, all available keys
3383 are returned.  Otherwise, @var{pattern} is a @code{NULL} terminated
3384 array of strings that are used to limit the list to all keys matching
3385 at least one of the patterns verbatim.  Note that the total length of
3386 all patterns is restricted to an engine-specific maximum (the exact
3387 limit also depends on the number of patterns and amount of quoting
3388 required, but a couple of hundred characters are usually accepted).
3389 Patterns should be used to restrict the search to a certain common
3390 name or user, not to list many specific keys at once by listing their
3391 fingerprints or key IDs.
3392
3393 If @var{secret_only} is not @code{0}, the list is restricted to secret
3394 keys only.
3395
3396 The value of @var{reserved} must be @code{0}.
3397
3398 The context will be busy until either all keys are received (and
3399 @code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}), or
3400 @code{gpgme_op_keylist_end} is called to finish the operation.
3401
3402 The function returns the error code @code{GPG_ERR_INV_VALUE} if
3403 @var{ctx} is not a valid pointer, and passes through any errors that
3404 are reported by the crypto engine support routines.
3405 @end deftypefun
3406
3407 @deftypefun gpgme_error_t gpgme_op_keylist_from_data @
3408             (@w{gpgme_ctx_t @var{ctx}}, @
3409              @w{gpgme_data_t @var{data}}, @
3410              @w{int @var{reserved}})
3411
3412 The function @code{gpgme_op_keylist_from_data_start} initiates a key
3413 listing operation inside the context @var{ctx}.  In contrast to the
3414 other key listing operation the keys are read from the supplied
3415 @var{data} and not from the local key database.  The keys are also not
3416 imported into the local ley database. The function sets everything up
3417 so that subsequent invocations of @code{gpgme_op_keylist_next} return
3418 the keys from @var{data}.
3419
3420 The value of @var{reserved} must be @code{0}.
3421
3422 This function requires at least GnuPG version 2.1.14 and currently
3423 works only with OpenPGP keys.
3424
3425 The context will be busy until either all keys are received (and
3426 @code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}), or
3427 @code{gpgme_op_keylist_end} is called to finish the operation.
3428 While the context is busy @var{data} may not be released.
3429
3430 The function returns the error code @code{GPG_ERR_INV_VALUE} if
3431 @var{ctx} is not a valid pointer, and passes through any errors that
3432 are reported by the crypto engine support routines.
3433 @end deftypefun
3434
3435 @deftypefun gpgme_error_t gpgme_op_keylist_next (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t *@var{r_key}})
3436
3437 The function @code{gpgme_op_keylist_next} returns the next key in the
3438 list created by a previous @code{gpgme_op_keylist_start} operation in
3439 the context @var{ctx}.  The key will have one reference for the user.
3440 @xref{Manipulating Keys}.
3441
3442 This is the only way to get at @code{gpgme_key_t} objects in
3443 @acronym{GPGME}.
3444
3445 If the last key in the list has already been returned,
3446 @code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}.
3447
3448 The function returns the error code @code{GPG_ERR_INV_VALUE} if
3449 @var{ctx} or @var{r_key} is not a valid pointer, and
3450 @code{GPG_ERR_ENOMEM} if there is not enough memory for the operation.
3451 @end deftypefun
3452
3453 @deftypefun gpgme_error_t gpgme_op_keylist_end (@w{gpgme_ctx_t @var{ctx}})
3454
3455 The function @code{gpgme_op_keylist_end} ends a pending key list
3456 operation in the context @var{ctx}.
3457
3458 After the operation completed successfully, the result of the key
3459 listing operation can be retrieved with
3460 @code{gpgme_op_keylist_result}.
3461
3462 The function returns the error code @code{GPG_ERR_INV_VALUE} if
3463 @var{ctx} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if at some
3464 time during the operation there was not enough memory available.
3465 @end deftypefun
3466
3467 The following example illustrates how all keys containing a certain
3468 string (@code{g10code}) can be listed with their key ID and the name
3469 and email address of the main user ID:
3470
3471 @example
3472 gpgme_ctx_t ctx;
3473 gpgme_key_t key;
3474 gpgme_error_t err = gpgme_new (&ctx);
3475
3476 if (!err)
3477   @{
3478     err = gpgme_op_keylist_start (ctx, "g10code", 0);
3479     while (!err)
3480       @{
3481         err = gpgme_op_keylist_next (ctx, &key);
3482         if (err)
3483           break;
3484         printf ("%s:", key->subkeys->keyid);
3485         if (key->uids && key->uids->name)
3486           printf (" %s", key->uids->name);
3487         if (key->uids && key->uids->email)
3488           printf (" <%s>", key->uids->email);
3489         putchar ('\n');
3490         gpgme_key_release (key);
3491       @}
3492     gpgme_release (ctx);
3493   @}
3494 if (gpg_err_code (err) != GPG_ERR_EOF)
3495   @{
3496     fprintf (stderr, "can not list keys: %s\n", gpgme_strerror (err));
3497     exit (1);
3498   @}
3499 @end example
3500
3501 @deftp {Data type} {gpgme_keylist_result_t}
3502 This is a pointer to a structure used to store the result of a
3503 @code{gpgme_op_keylist_*} operation.  After successfully ending a key
3504 listing operation, you can retrieve the pointer to the result with
3505 @code{gpgme_op_keylist_result}.  The structure contains the following
3506 member:
3507
3508 @table @code
3509 @item unsigned int truncated : 1
3510 This is true if the crypto backend had to truncate the result, and
3511 less than the desired keys could be listed.
3512 @end table
3513 @end deftp
3514
3515 @deftypefun gpgme_keylist_result_t gpgme_op_keylist_result (@w{gpgme_ctx_t @var{ctx}})
3516 The function @code{gpgme_op_keylist_result} returns a
3517 @code{gpgme_keylist_result_t} pointer to a structure holding the
3518 result of a @code{gpgme_op_keylist_*} operation.  The pointer is only
3519 valid if the last operation on the context was a key listing
3520 operation, and if this operation finished successfully.  The returned
3521 pointer is only valid until the next operation is started on the
3522 context.
3523 @end deftypefun
3524
3525 In a simple program, for which a blocking operation is acceptable, the
3526 following function can be used to retrieve a single key.
3527
3528 @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}})
3529 The function @code{gpgme_get_key} gets the key with the fingerprint
3530 (or key ID) @var{fpr} from the crypto backend and return it in
3531 @var{r_key}.  If @var{secret} is true, get the secret key.  The
3532 currently active keylist mode is used to retrieve the key.  The key
3533 will have one reference for the user.
3534
3535 If the key is not found in the keyring, @code{gpgme_get_key} returns
3536 the error code @code{GPG_ERR_EOF} and *@var{r_key} will be set to
3537 @code{NULL}.
3538
3539 The function returns the error code @code{GPG_ERR_INV_VALUE} if
3540 @var{ctx} or @var{r_key} is not a valid pointer or @var{fpr} is not a
3541 fingerprint or key ID, @code{GPG_ERR_AMBIGUOUS_NAME} if the key ID was
3542 not a unique specifier for a key, and @code{GPG_ERR_ENOMEM} if at some
3543 time during the operation there was not enough memory available.
3544 @end deftypefun
3545
3546
3547 @node Information About Keys
3548 @subsection Information About Keys
3549 @cindex key, information about
3550 @cindex key, attributes
3551 @cindex attributes, of a key
3552
3553 Please see the beginning of this section for more information about
3554 @code{gpgme_key_t} objects.
3555
3556 @deftp {Data type} gpgme_validity_t
3557 The @code{gpgme_validity_t} type is used to specify the validity of a user ID
3558 in a key.  The following validities are defined:
3559
3560 @table @code
3561 @item GPGME_VALIDITY_UNKNOWN
3562 The user ID is of unknown validity.  The string representation of this
3563 validity is ``?''.
3564
3565 @item GPGME_VALIDITY_UNDEFINED
3566 The validity of the user ID is undefined.  The string representation of this
3567 validity is ``q''.
3568
3569 @item GPGME_VALIDITY_NEVER
3570 The user ID is never valid.  The string representation of this
3571 validity is ``n''.
3572
3573 @item GPGME_VALIDITY_MARGINAL
3574 The user ID is marginally valid.  The string representation of this
3575 validity is ``m''.
3576
3577 @item GPGME_VALIDITY_FULL
3578 The user ID is fully valid.  The string representation of this
3579 validity is ``f''.
3580
3581 @item GPGME_VALIDITY_ULTIMATE
3582 The user ID is ultimately valid.  The string representation of this
3583 validity is ``u''.
3584 @end table
3585 @end deftp
3586
3587
3588
3589
3590 @node Manipulating Keys
3591 @subsection Manipulating Keys
3592 @cindex key, manipulation
3593
3594 @deftypefun void gpgme_key_ref (@w{gpgme_key_t @var{key}})
3595 The function @code{gpgme_key_ref} acquires an additional reference for
3596 the key @var{key}.
3597 @end deftypefun
3598
3599 @deftypefun void gpgme_key_unref (@w{gpgme_key_t @var{key}})
3600 The function @code{gpgme_key_unref} releases a reference for the key
3601 @var{key}.  If this was the last reference, the key will be destroyed
3602 and all resources associated to it will be released.
3603 @end deftypefun
3604
3605
3606 @node Generating Keys
3607 @subsection Generating Keys
3608 @cindex key, creation
3609 @cindex key ring, add
3610
3611 GPGME provides a set of functions to create public key pairs.  Most of
3612 these functions require the use of GnuPG 2.1 and later; for older
3613 GnuPG versions the @code{gpgme_op_genkey} function can be used.
3614 Existing code which wants to update to the new functions or new code
3615 which shall supports older GnuPG versions may try the new functions
3616 first and provide a fallback to the old function if the error code
3617 @code{GPG_ERR_NOT_SUPPORTED} is received.
3618
3619 @c
3620 @c  gpgme_op_createkey
3621 @c
3622 @deftypefun gpgme_error_t gpgme_op_createkey @
3623       (@w{gpgme_ctx_t @var{ctx}}, @
3624        @w{const char *@var{userid}}, @
3625        @w{const char *@var{algo}}, @
3626        @w{unsigned long @var{reserved}}, @
3627        @w{unsigned long @var{expires}}, @
3628        @w{gpgme_key_t @var{extrakey}}, @
3629        @w{unsigned int @var{flags}});
3630
3631 The function @code{gpgme_op_createkey} generates a new key for the
3632 procotol active in the context @var{ctx}.  As of now this function
3633 does only work for OpenPGP and requires at least version 2.1.13 of
3634 GnuPG.
3635
3636 @var{userid} is commonly the mail address associated with the key.
3637 GPGME does not require a specificy syntax but if more than a mail
3638 address is given, RFC-822 style format is suggested.  The value is
3639 expected to be in UTF-8 encoding (i.e. no IDN encoding for mail
3640 addresses).  This is a required parameter.
3641
3642 @var{algo} specifies the algorithm for the new key (actually a keypair
3643 of public and private key).  For a list of supported algorithms, see
3644 the GnuPG manual.  If @var{algo} is @code{NULL} or the string
3645 "default", the key is generated using the default algorithm of the
3646 engine.  If the string "future-default" is used the engine may use an
3647 algorithm which is planned to be the default in a future release of
3648 the engine; however existing implementation of the protocol may not be
3649 able to already handle such future algorithms.  For the OpenPGP
3650 protocol, the specification of a default algorithm, without requesting
3651 a non-default usage via @var{flags}, triggers the creation of a
3652 primary key plus a secondary key (subkey).
3653
3654 @var{reserved} must be set to zero.
3655
3656 @var{expires} specifies the expiration time in seconds.  If you supply
3657 0, a reasonable expiration time is chosen.  Use the flag
3658 @code{GPGME_CREATE_NOEXPIRE} to create keys that do not expire.  Note
3659 that this parameter takes an unsigned long value and not a
3660 @code{time_t} to avoid problems on systems which use a signed 32 bit
3661 @code{time_t}.  Note further that the OpenPGP protocol uses 32 bit
3662 values for timestamps and thus can only encode dates up to the year
3663 2106.
3664
3665 @var{extrakey} is currently not used and must be set to @code{NULL}.
3666 A future version of GPGME may use this parameter to create X.509 keys.
3667
3668 @var{flags} can be set to the bit-wise OR of the following flags:
3669
3670 @table @code
3671 @item GPGME_CREATE_SIGN
3672 @itemx GPGME_CREATE_ENCR
3673 @itemx GPGME_CREATE_CERT
3674 @itemx GPGME_CREATE_AUTH
3675 Do not create the key with the default capabilities (key usage) of the
3676 requested algorithm but use those explicitly given by these flags:
3677 ``signing'', ``encryption'', ``certification'', or ``authentication''.
3678 The allowed combinations depend on the algorithm.
3679
3680 If any of these flags are set and a default algorithm has been
3681 selected only one key is created in the case of the OpenPGP
3682 protocol.
3683
3684 @item GPGME_CREATE_NOPASSWD
3685 Request generation of the key without password protection.
3686
3687 @item GPGME_CREATE_SELFSIGNED
3688 For an X.509 key do not create a CSR but a self-signed certificate.
3689 This has not yet been implemented.
3690
3691 @item GPGME_CREATE_NOSTORE
3692 Do not store the created key in the local key database.
3693 This has not yet been implemented.
3694
3695 @item GPGME_CREATE_WANTPUB
3696 @itemx GPGME_CREATE_WANTSEC