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