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