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