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