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