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