480945485e1f2efcaab5495793c73912a8fa71fc
[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 disabled : 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 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.
2481
2482 If the key is not found in the keyring, @code{gpgme_get_key} returns
2483 the error code @code{GPG_ERR_NO_ERROR} and *@var{r_key} will be set to
2484 @code{NULL}.
2485
2486 The function returns the error code @code{GPG_ERR_INV_VALUE} if
2487 @var{ctx} or @var{r_key} is not a valid pointer or @var{fpr} is not a
2488 fingerprint or key ID, @code{GPG_ERR_AMBIGUOUS_NAME} if the key ID was
2489 not a unique specifier for a key, and @code{GPG_ERR_ENOMEM} if at some
2490 time during the operation there was not enough memory available.
2491 @end deftypefun
2492
2493
2494 @node Information About Keys
2495 @subsection Information About Keys
2496 @cindex key, information about
2497 @cindex key, attributes
2498 @cindex attributes, of a key
2499
2500 Please see the beginning of this section for more information about
2501 @code{gpgme_key_t} objects.
2502
2503 @deftp {Data type} gpgme_validity_t
2504 The @code{gpgme_validity_t} type is used to specify the validity of a user ID
2505 in a key.  The following validities are defined:
2506
2507 @table @code
2508 @item GPGME_VALIDITY_UNKNOWN
2509 The user ID is of unknown validity.  The string representation of this
2510 validity is ``?''.
2511
2512 @item GPGME_VALIDITY_UNDEFINED
2513 The validity of the user ID is undefined.  The string representation of this
2514 validity is ``q''.
2515
2516 @item GPGME_VALIDITY_NEVER
2517 The user ID is never valid.  The string representation of this
2518 validity is ``n''.
2519
2520 @item GPGME_VALIDITY_MARGINAL
2521 The user ID is marginally valid.  The string representation of this
2522 validity is ``m''.
2523
2524 @item GPGME_VALIDITY_FULL
2525 The user ID is fully valid.  The string representation of this
2526 validity is ``f''.
2527
2528 @item GPGME_VALIDITY_ULTIMATE
2529 The user ID is ultimately valid.  The string representation of this
2530 validity is ``u''.
2531 @end table
2532 @end deftp
2533
2534
2535 The following interfaces are deprecated and only provided for backward
2536 compatibility.  Don't use them.  They will be removed in a future
2537 version of @acronym{GPGME}.
2538
2539 @deftp {Data type} gpgme_attr_t
2540 The @code{gpgme_attr_t} type is used to specify a key or trust item
2541 attribute.  The following attributes are defined:
2542
2543 @table @code
2544 @item GPGME_ATTR_KEYID
2545 This is the key ID of a sub key.  It is representable as a string.
2546
2547 For trust items, the trust item refers to the key with this ID.
2548
2549 @item GPGME_ATTR_FPR
2550 This is the fingerprint of a sub key.  It is representable as a
2551 string.
2552
2553 @item GPGME_ATTR_ALGO
2554 This is the crypto algorithm for which the sub key can be used.  It
2555 is representable as a string and as a number.  The numbers correspond
2556 to the @code{enum gcry_pk_algos} values in the gcrypt library.
2557
2558 @item GPGME_ATTR_LEN
2559 This is the key length of a sub key.  It is representable as a
2560 number.
2561
2562 @item GPGME_ATTR_CREATED
2563 This is the timestamp at creation time of a sub key.  It is
2564 representable as a number.
2565
2566 @item GPGME_ATTR_EXPIRE
2567 This is the expiration time of a sub key.  It is representable as a
2568 number.
2569
2570 @item GPGME_ATTR_OTRUST
2571 XXX FIXME  (also for trust items)
2572
2573 @item GPGME_ATTR_USERID
2574 This is a user ID.  There can be more than one user IDs in a
2575 @var{gpgme_key_t} object.  The first one (with index 0) is the primary
2576 user ID.  The user ID is representable as a number.
2577
2578 For trust items, this is the user ID associated with this trust item.
2579
2580 @item GPGME_ATTR_NAME
2581 This is the name belonging to a user ID.  It is representable as a string.
2582
2583 @item GPGME_ATTR_EMAIL
2584 This is the email address belonging to a user ID.  It is representable
2585 as a string.
2586
2587 @item GPGME_ATTR_COMMENT
2588 This is the comment belonging to a user ID.  It is representable as a
2589 string.
2590
2591 @item GPGME_ATTR_VALIDITY
2592 This is the validity belonging to a user ID.  It is representable as a
2593 string and as a number.  See below for a list of available validities.
2594
2595 For trust items, this is the validity that is associated with this
2596 trust item.
2597
2598 @item GPGME_ATTR_UID_REVOKED
2599 This specifies if a user ID is revoked.  It is representable as a
2600 number, and is @code{1} if the user ID is revoked, and @code{0}
2601 otherwise.
2602
2603 @item GPGME_ATTR_UID_INVALID
2604 This specifies if a user ID is invalid.  It is representable as a
2605 number, and is @code{1} if the user ID is invalid, and @code{0}
2606 otherwise.
2607
2608 @item GPGME_ATTR_LEVEL
2609 This is the trust level of a trust item.
2610
2611 @item GPGME_ATTR_TYPE
2612 This returns information about the type of key.  For the string function
2613 this will eother be "PGP" or "X.509".  The integer function returns 0
2614 for PGP and 1 for X.509.  It is also used for the type of a trust item.
2615
2616 @item GPGME_ATTR_IS_SECRET
2617 This specifies if the key is a secret key.  It is representable as a
2618 number, and is @code{1} if the key is revoked, and @code{0} otherwise.
2619
2620 @item GPGME_ATTR_KEY_REVOKED
2621 This specifies if a sub key is revoked.  It is representable as a
2622 number, and is @code{1} if the key is revoked, and @code{0} otherwise.
2623
2624 @item GPGME_ATTR_KEY_INVALID
2625 This specifies if a sub key is invalid.  It is representable as a
2626 number, and is @code{1} if the key is invalid, and @code{0} otherwise.
2627
2628 @item GPGME_ATTR_KEY_EXPIRED
2629 This specifies if a sub key is expired.  It is representable as a
2630 number, and is @code{1} if the key is expired, and @code{0} otherwise.
2631
2632 @item GPGME_ATTR_KEY_DISABLED
2633 This specifies if a sub key is disabled.  It is representable as a
2634 number, and is @code{1} if the key is disabled, and @code{0} otherwise.
2635
2636 @item GPGME_ATTR_KEY_CAPS
2637 This is a description of the capabilities of a sub key.  It is
2638 representable as a string.  The string contains the letter ``e'' if
2639 the key can be used for encryption, ``s'' if the key can be used for
2640 signatures, and ``c'' if the key can be used for certifications.
2641
2642 @item GPGME_ATTR_CAN_ENCRYPT
2643 This specifies if a sub key can be used for encryption.  It is
2644 representable as a number, and is @code{1} if the sub key can be used
2645 for encryption, and @code{0} otherwise.
2646
2647 @item GPGME_ATTR_CAN_SIGN
2648 This specifies if a sub key can be used to create data signatures.  It
2649 is representable as a number, and is @code{1} if the sub key can be
2650 used for signatures, and @code{0} otherwise.
2651
2652 @item GPGME_ATTR_CAN_CERTIFY
2653 This specifies if a sub key can be used to create key certificates.
2654 It is representable as a number, and is @code{1} if the sub key can be
2655 used for certifications, and @code{0} otherwise.
2656
2657 @item GPGME_ATTR_SERIAL
2658 The X.509 issuer serial attribute of the key.  It is representable as
2659 a string.
2660
2661 @item GPGME_ATTR_ISSUE
2662 The X.509 issuer name attribute of the key.  It is representable as a
2663 string.
2664
2665 @item GPGME_ATTR_CHAINID
2666 The X.509 chain ID can be used to build the certification chain.  It
2667 is representable as a string.
2668 @end table
2669 @end deftp
2670
2671 @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}})
2672 The function @code{gpgme_key_get_string_attr} returns the value of the
2673 string-representable attribute @var{what} of key @var{key}.  If the
2674 attribute is an attribute of a sub key or an user ID, @var{idx}
2675 specifies the sub key or user ID of which the attribute value is
2676 returned.  The argument @var{reserved} is reserved for later use and
2677 should be @code{NULL}.
2678
2679 The string returned is only valid as long as the key is valid.
2680
2681 The function returns @code{0} if an attribute can't be returned as a
2682 string, @var{key} is not a valid pointer, @var{idx} out of range,
2683 or @var{reserved} not @code{NULL}.
2684 @end deftypefun
2685
2686 @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}})
2687 The function @code{gpgme_key_get_ulong_attr} returns the value of the
2688 number-representable attribute @var{what} of key @var{key}.  If the
2689 attribute is an attribute of a sub key or an user ID, @var{idx}
2690 specifies the sub key or user ID of which the attribute value is
2691 returned.  The argument @var{reserved} is reserved for later use and
2692 should be @code{NULL}.
2693
2694 The function returns @code{0} if the attribute can't be returned as a
2695 number, @var{key} is not a valid pointer, @var{idx} out of range, or
2696 @var{reserved} not @code{NULL}.
2697 @end deftypefun
2698
2699
2700 @node Key Signatures
2701 @subsection Key Signatures
2702 @cindex key, signatures
2703 @cindex signatures, on a key
2704
2705 The following interfaces are deprecated and only provided for backward
2706 compatibility.  Don't use them.  They will be removed in a future
2707 version of @acronym{GPGME}.
2708
2709 The signatures on a key are only available if the key was retrieved
2710 via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode
2711 enabled, because it is expensive to retrieve all signatures of a key.
2712
2713 So, before using the below interfaces to retrieve the signatures on a
2714 key, you have to make sure that the key was listed with signatures
2715 enabled.  One convenient, but blocking, way to do this is to use the
2716 function @code{gpgme_get_key}.
2717
2718 @deftp {Data type} gpgme_attr_t
2719 The @code{gpgme_attr_t} type is used to specify a key signature
2720 attribute.  The following attributes are defined:
2721
2722 @table @code
2723 @item GPGME_ATTR_KEYID
2724 This is the key ID of the key which was used for the signature.  It is
2725 representable as a string.
2726
2727 @item GPGME_ATTR_ALGO
2728 This is the crypto algorithm used to create the signature.  It is
2729 representable as a string and as a number.  The numbers correspond to
2730 the @code{enum gcry_pk_algos} values in the gcrypt library.
2731
2732 @item GPGME_ATTR_CREATED
2733 This is the timestamp at creation time of the signature.  It is
2734 representable as a number.
2735
2736 @item GPGME_ATTR_EXPIRE
2737 This is the expiration time of the signature.  It is representable as
2738 a number.
2739
2740 @item GPGME_ATTR_USERID
2741 This is the user ID associated with the signing key.  The user ID is
2742 representable as a number.
2743
2744 @item GPGME_ATTR_NAME
2745 This is the name belonging to a user ID.  It is representable as a string.
2746
2747 @item GPGME_ATTR_EMAIL
2748 This is the email address belonging to a user ID.  It is representable
2749 as a string.
2750
2751 @item GPGME_ATTR_COMMENT
2752 This is the comment belonging to a user ID.  It is representable as a
2753 string.
2754
2755 @item GPGME_ATTR_KEY_REVOKED
2756 This specifies if a key signature is a revocation signature.  It is
2757 representable as a number, and is @code{1} if the key is revoked, and
2758 @code{0} otherwise.
2759
2760 @c @item GPGME_ATTR_KEY_EXPIRED
2761 @c This specifies if a key signature is expired.  It is representable as
2762 @c a number, and is @code{1} if the key is revoked, and @code{0}
2763 @c otherwise.
2764 @c
2765 @item GPGME_ATTR_SIG_CLASS
2766 This specifies the signature class of a key signature.  It is
2767 representable as a number.  The meaning is specific to the crypto
2768 engine.
2769
2770 @item GPGME_ATTR_SIG_CLASS
2771 This specifies the signature class of a key signature.  It is
2772 representable as a number.  The meaning is specific to the crypto
2773 engine.
2774
2775 @item GPGME_ATTR_SIG_STATUS
2776 This is the same value as returned by @code{gpgme_get_sig_status}.
2777 @end table
2778 @end deftp
2779
2780 @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}})
2781 The function @code{gpgme_key_sig_get_string_attr} returns the value of
2782 the string-representable attribute @var{what} of the signature
2783 @var{idx} on the user ID @var{uid_idx} in the key @var{key}.  The
2784 argument @var{reserved} is reserved for later use and should be
2785 @code{NULL}.
2786
2787 The string returned is only valid as long as the key is valid.
2788
2789 The function returns @code{0} if an attribute can't be returned as a
2790 string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx}
2791 out of range, or @var{reserved} not @code{NULL}.
2792 @end deftypefun
2793
2794 @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}})
2795 The function @code{gpgme_key_sig_get_ulong_attr} returns the value of
2796 the number-representable attribute @var{what} of the signature
2797 @var{idx} on the user ID @var{uid_idx} in the key @var{key}.  The
2798 argument @var{reserved} is reserved for later use and should be
2799 @code{NULL}.
2800
2801 The function returns @code{0} if an attribute can't be returned as a
2802 string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx}
2803 out of range, or @var{reserved} not @code{NULL}.
2804 @end deftypefun
2805
2806
2807 @node Manipulating Keys
2808 @subsection Manipulating Keys
2809 @cindex key, manipulation
2810
2811 @deftypefun void gpgme_key_ref (@w{gpgme_key_t @var{key}})
2812 The function @code{gpgme_key_ref} acquires an additional reference for
2813 the key @var{key}.
2814 @end deftypefun
2815
2816 @deftypefun void gpgme_key_unref (@w{gpgme_key_t @var{key}})
2817 The function @code{gpgme_key_unref} releases a reference for the key
2818 @var{key}.  If this was the last reference, the key will be destroyed
2819 and all resources associated to it will be released.
2820 @end deftypefun
2821
2822
2823 The following interface is deprecated and only provided for backward
2824 compatibility.  Don't use it.  It will be removed in a future version
2825 of @acronym{GPGME}.
2826
2827 @deftypefun void gpgme_key_release (@w{gpgme_key_t @var{key}})
2828 The function @code{gpgme_key_release} is equivalent to
2829 @code{gpgme_key_unref}.
2830 @end deftypefun
2831
2832
2833 @node Generating Keys
2834 @subsection Generating Keys
2835 @cindex key, creation
2836 @cindex key ring, add
2837
2838 @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}})
2839 The function @code{gpgme_op_genkey} generates a new key pair in the
2840 context @var{ctx}.  The meaning of @var{public} and @var{secret}
2841 depends on the crypto backend.
2842
2843 GnuPG does not support @var{public} and @var{secret}, they should be
2844 @code{NULL}.  GnuPG will generate a key pair and add it to the
2845 standard key ring.  The fingerprint of the generated key is available
2846 with @code{gpgme_op_genkey_result}.
2847
2848 GpgSM requires @var{public} to be a writable data object.  GpgSM will
2849 generate a secret key (which will be stored by @command{gpg-agent},
2850 and return a certificate request in @var{public}, which then needs to
2851 be signed by the certification authority and imported before it can be
2852 used.  GpgSM does not make the fingerprint available.
2853
2854 The argument @var{parms} specifies parameters for the key in an XML
2855 string.  The details about the format of @var{parms} are specific to
2856 the crypto engine used by @var{ctx}.  Here is an example for GnuPG as
2857 the crypto engine:
2858
2859 @example
2860 <GnupgKeyParms format="internal">
2861 Key-Type: DSA
2862 Key-Length: 1024
2863 Subkey-Type: ELG-E
2864 Subkey-Length: 1024
2865 Name-Real: Joe Tester
2866 Name-Comment: with stupid passphrase
2867 Name-Email: joe@@foo.bar
2868 Expire-Date: 0
2869 Passphrase: abc
2870 </GnupgKeyParms>
2871 @end example
2872
2873 Here is an example for GpgSM as the crypto engine:
2874
2875 @example
2876 <GnupgKeyParms format="internal">
2877 Key-Type: RSA
2878 Key-Length: 1024
2879 Name-DN: C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester
2880 Name-Email: joe@@foo.bar
2881 </GnupgKeyParms>
2882 @end example
2883
2884 Strings should be given in UTF-8 encoding.  The only format supported
2885 for now is ``internal''.  The content of the @code{GnupgKeyParms}
2886 container is passed verbatim to the crypto backend.  Control
2887 statements are not allowed.
2888
2889 After the operation completed successfully, the result can be
2890 retrieved with @code{gpgme_op_genkey_result}.
2891
2892 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
2893 operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
2894 @var{parms} is not a valid XML string, @code{GPG_ERR_NOT_SUPPORTED} if
2895 @var{public} or @var{secret} is not valid, and @code{GPG_ERR_GENERAL}
2896 if no key was created by the backend.
2897 @end deftypefun
2898
2899 @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}})
2900 The function @code{gpgme_op_genkey_start} initiates a
2901 @code{gpgme_op_genkey} operation.  It can be completed by calling
2902 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
2903
2904 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
2905 operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
2906 @var{parms} is not a valid XML string, and
2907 @code{GPG_ERR_NOT_SUPPORTED} if @var{public} or @var{secret} is not
2908 @code{NULL}.
2909 @end deftypefun
2910
2911 @deftp {Data type} {gpgme_genkey_result_t}
2912 This is a pointer to a structure used to store the result of a
2913 @code{gpgme_op_genkey} operation.  After successfully generating a
2914 key, you can retrieve the pointer to the result with
2915 @code{gpgme_op_genkey_result}.  The structure contains the following
2916 members:
2917
2918 @table @code
2919 @item unsigned int primary : 1
2920 This is a flag that is set to 1 if a primary key was created and to 0
2921 if not.
2922
2923 @item unsigned int sub : 1
2924 This is a flag that is set to 1 if a subkey was created and to 0
2925 if not.
2926
2927 @item char *fpr
2928 This is the fingerprint of the key that was created.  If both a
2929 primary and a sub key were generated, the fingerprint of the primary
2930 key will be returned.  If the crypto engine does not provide the
2931 fingerprint, @code{fpr} will be a null pointer.
2932 @end table
2933 @end deftp
2934
2935 @deftypefun gpgme_genkey_result_t gpgme_op_genkey_result (@w{gpgme_ctx_t @var{ctx}})
2936 The function @code{gpgme_op_genkey_result} returns a
2937 @code{gpgme_genkey_result_t} pointer to a structure holding the result of
2938 a @code{gpgme_op_genkey} operation.  The pointer is only valid if the
2939 last operation on the context was a @code{gpgme_op_genkey} or
2940 @code{gpgme_op_genkey_start} operation, and if this operation finished
2941 successfully.  The returned pointer is only valid until the next
2942 operation is started on the context.
2943 @end deftypefun
2944
2945
2946 @node Exporting Keys
2947 @subsection Exporting Keys
2948 @cindex key, export
2949 @cindex key ring, export from
2950
2951 @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}})
2952 The function @code{gpgme_op_export} extracts public keys and returns
2953 them in the data buffer @var{keydata}.  The output format of the key
2954 data returned is determined by the @acronym{ASCII} armor attribute set
2955 for the context @var{ctx}.
2956
2957 If @var{pattern} is @code{NULL}, all available keys are returned.
2958 Otherwise, @var{pattern} contains an engine specific expression that
2959 is used to limit the list to all keys matching the pattern.
2960
2961 @var{reserved} is reserved for future use and must be @code{0}.
2962
2963 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
2964 operation completed successfully, @code{GPG_ERR_INV_VALUE} if
2965 @var{keydata} is not a valid empty data buffer, and passes through any
2966 errors that are reported by the crypto engine support routines.
2967 @end deftypefun
2968
2969 @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}})
2970 The function @code{gpgme_op_export_start} initiates a
2971 @code{gpgme_op_export} operation.  It can be completed by calling
2972 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
2973
2974 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
2975 operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
2976 if @var{keydata} is not a valid empty data buffer.
2977 @end deftypefun
2978
2979 @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}})
2980 The function @code{gpgme_op_export} extracts public keys and returns
2981 them in the data buffer @var{keydata}.  The output format of the key
2982 data returned is determined by the @acronym{ASCII} armor attribute set
2983 for the context @var{ctx}.
2984
2985 If @var{pattern} or @var{*pattern} is @code{NULL}, all available keys
2986 are returned.  Otherwise, @var{pattern} is a @code{NULL} terminated
2987 array of strings that are used to limit the list to all keys matching
2988 at least one of the patterns verbatim.
2989
2990 @var{reserved} is reserved for future use and must be @code{0}.
2991
2992 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
2993 operation completed successfully, @code{GPG_ERR_INV_VALUE} if
2994 @var{keydata} is not a valid empty data buffer, and passes through any
2995 errors that are reported by the crypto engine support routines.
2996 @end deftypefun
2997
2998 @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}})
2999 The function @code{gpgme_op_export_ext_start} initiates a
3000 @code{gpgme_op_export_ext} operation.  It can be completed by calling
3001 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
3002
3003 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3004 operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
3005 if @var{keydata} is not a valid empty data buffer.
3006 @end deftypefun
3007
3008
3009 @node Importing Keys
3010 @subsection Importing Keys
3011 @cindex key, import
3012 @cindex key ring, import to
3013
3014 @deftypefun gpgme_error_t gpgme_op_import (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}})
3015 The function @code{gpgme_op_import} adds the keys in the data buffer
3016 @var{keydata} to the key ring of the crypto engine used by @var{ctx}.
3017 The format of @var{keydata} can be @acronym{ASCII} armored, for example,
3018 but the details are specific to the crypto engine.
3019
3020 After the operation completed successfully, the result can be
3021 retrieved with @code{gpgme_op_import_result}.
3022
3023 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3024 import was completed successfully, @code{GPG_ERR_INV_VALUE} if
3025 @var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer,
3026 and @code{GPG_ERR_NO_DATA} if @var{keydata} is an empty data buffer.
3027 @end deftypefun
3028
3029 @deftypefun gpgme_error_t gpgme_op_import_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}})
3030 The function @code{gpgme_op_import_start} initiates a
3031 @code{gpgme_op_import} operation.  It can be completed by calling
3032 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
3033
3034 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3035 import could be started successfully, @code{GPG_ERR_INV_VALUE} if
3036 @var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer,
3037 and @code{GPG_ERR_NO_DATA} if @var{keydata} is an empty data buffer.
3038 @end deftypefun
3039
3040 @deftp {Data type} {gpgme_import_status_t}
3041 This is a pointer to a structure used to store a part of the result of
3042 a @code{gpgme_op_import} operation.  For each considered key one
3043 status is added that contains information about the result of the
3044 import.  The structure contains the following members:
3045
3046 @table @code
3047 @item gpgme_import_status_t next
3048 This is a pointer to the next status structure in the linked list, or
3049 @code{NULL} if this is the last element.
3050
3051 @item char *fpr
3052 This is the fingerprint of the key that was considered.
3053
3054 @item gpgme_error_t result
3055 If the import was not successful, this is the error value that caused
3056 the import to fail.  Otherwise the error code is
3057 @code{GPG_ERR_NO_ERROR}.
3058
3059 @item unsigned int status
3060 This is a bit-wise OR of the following flags that give more
3061 information about what part of the key was imported.  If the key was
3062 already known, this might be 0.
3063
3064 @table @code
3065 @item GPGME_IMPORT_NEW
3066 The key was new.
3067
3068 @item GPGME_IMPORT_UID
3069 The key contained new user IDs.
3070
3071 @item GPGME_IMPORT_SIG
3072 The key contained new signatures.
3073
3074 @item GPGME_IMPORT_SUBKEY
3075 The key contained new sub keys.
3076
3077 @item GPGME_IMPORT_SECRET
3078 The key contained a secret key.
3079 @end table
3080 @end table
3081 @end deftp
3082
3083 @deftp {Data type} {gpgme_import_result_t}
3084 This is a pointer to a structure used to store the result of a
3085 @code{gpgme_op_import} operation.  After a successful import
3086 operation, you can retrieve the pointer to the result with
3087 @code{gpgme_op_import_result}.  The structure contains the following
3088 members:
3089
3090 @table @code
3091 @item int considered
3092 The total number of considered keys.
3093
3094 @item int no_user_id
3095 The number of keys without user ID.
3096
3097 @item int imported
3098 The total number of imported keys.
3099
3100 @item imported_rsa
3101 The number of imported RSA keys.
3102
3103 @item unchanged
3104 The number of unchanged keys.
3105
3106 @item new_user_ids
3107 The number of new user IDs.
3108
3109 @item new_sub_keys
3110 The number of new sub keys.
3111
3112 @item new_signatures
3113 The number of new signatures.
3114
3115 @item new_revocations
3116 The number of new revocations.
3117
3118 @item secret_read
3119 The total number of secret keys read.
3120
3121 @item secret_imported
3122 The number of imported secret keys.
3123
3124 @item secret_unchanged
3125 The number of unchanged secret keys.
3126
3127 @item not_imported
3128 The number of keys not imported.
3129
3130 @item gpgme_import_status_t imports
3131 A list of gpgme_import_status_t objects which contain more information
3132 about the keys for which an import was attempted.
3133 @end table
3134 @end deftp
3135
3136 @deftypefun gpgme_import_result_t gpgme_op_import_result (@w{gpgme_ctx_t @var{ctx}})
3137 The function @code{gpgme_op_import_result} returns a
3138 @code{gpgme_import_result_t} pointer to a structure holding the result
3139 of a @code{gpgme_op_import} operation.  The pointer is only valid if
3140 the last operation on the context was a @code{gpgme_op_import} or
3141 @code{gpgme_op_import_start} operation, and if this operation finished
3142 successfully.  The returned pointer is only valid until the next
3143 operation is started on the context.
3144 @end deftypefun
3145
3146 The following interface is deprecated and only provided for backward
3147 compatibility.  Don't use it.  It will be removed in a future version
3148 of @acronym{GPGME}.
3149
3150 @deftypefun gpgme_error_t gpgme_op_import_ext (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}}, @w{int *@var{nr}})
3151 The function @code{gpgme_op_import_ext} is equivalent to:
3152
3153 @example
3154   gpgme_error_t err = gpgme_op_import (ctx, keydata);
3155   if (!err)
3156     @{
3157       gpgme_import_result_t result = gpgme_op_import_result (ctx);
3158       *nr = result->considered;
3159     @}
3160 @end example
3161 @end deftypefun
3162
3163
3164 @node Deleting Keys
3165 @subsection Deleting Keys
3166 @cindex key, delete
3167 @cindex key ring, delete from
3168
3169 @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}})
3170 The function @code{gpgme_op_delete} deletes the key @var{key} from the
3171 key ring of the crypto engine used by @var{ctx}.  If
3172 @var{allow_secret} is @code{0}, only public keys are deleted,
3173 otherwise secret keys are deleted as well, if that is supported.
3174
3175 The function returns the error code @code{GPG_ERR_NO_ERROR} if the key
3176 was deleted successfully, @code{GPG_ERR_INV_VALUE} if @var{ctx} or
3177 @var{key} is not a valid pointer, @code{GPG_ERR_NO_PUBKEY} if
3178 @var{key} could not be found in the keyring,
3179 @code{GPG_ERR_AMBIGUOUS_NAME} if the key was not specified
3180 unambiguously, and @code{GPG_ERR_CONFLICT} if the secret key for
3181 @var{key} is available, but @var{allow_secret} is zero.
3182 @end deftypefun
3183
3184 @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}})
3185 The function @code{gpgme_op_delete_start} initiates a
3186 @code{gpgme_op_delete} operation.  It can be completed by calling
3187 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
3188
3189 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3190 operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
3191 @var{ctx} or @var{key} is not a valid pointer.
3192 @end deftypefun
3193
3194
3195 @node Trust Item Management
3196 @section Trust Item Management
3197 @cindex trust item
3198
3199 @strong{Caution:} The trust items interface is experimental.
3200
3201 @deftp {Data type} gpgme_trust_item_t
3202 The @code{gpgme_trust_item_t} type is a pointer to a trust item object.
3203 It has the following members:
3204
3205 @table @code
3206 @item char *keyid
3207 This is a string describing the key to which this trust items belongs.
3208
3209 @item int type
3210 This is the type of the trust item.  A value of 1 refers to a key, a
3211 value of 2 refers to a user ID.
3212
3213 @item int level
3214 This is the trust level.
3215
3216 @item char *owner_trust
3217 The owner trust if @code{type} is 1.
3218
3219 @item char *validity
3220 The calculated validity.
3221
3222 @item char *name
3223 The user name if @code{type} is 2.
3224 @end table
3225 @end deftp
3226
3227 @menu
3228 * Listing Trust Items::           Browsing the list of available trust items.
3229 * Information About Trust Items:: Requesting information about trust items.
3230 * Manipulating Trust Items::      Operations on trust items.
3231 @end menu
3232
3233
3234 @node Listing Trust Items
3235 @subsection Listing Trust Items
3236 @cindex trust item list
3237
3238 @deftypefun gpgme_error_t gpgme_op_trustlist_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{max_level}})
3239 The function @code{gpgme_op_trustlist_start} initiates a trust item
3240 listing operation inside the context @var{ctx}.  It sets everything up
3241 so that subsequent invocations of @code{gpgme_op_trustlist_next} return
3242 the trust items in the list.
3243
3244 The string @var{pattern} contains an engine specific expression that
3245 is used to limit the list to all trust items matching the pattern.  It
3246 can not be the empty string.
3247
3248 The argument @var{max_level} is currently ignored.
3249
3250 The context will be busy until either all trust items are received
3251 (and @code{gpgme_op_trustlist_next} returns @code{GPG_ERR_EOF}), or
3252 @code{gpgme_op_trustlist_end} is called to finish the operation.
3253
3254 The function returns the error code @code{GPG_ERR_INV_VALUE} if
3255 @var{ctx} is not a valid pointer, and passes through any errors that
3256 are reported by the crypto engine support routines.
3257 @end deftypefun
3258
3259 @deftypefun gpgme_error_t gpgme_op_trustlist_next (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_trust_item_t *@var{r_item}})
3260 The function @code{gpgme_op_trustlist_next} returns the next trust
3261 item in the list created by a previous @code{gpgme_op_trustlist_start}
3262 operation in the context @var{ctx}.  The trust item can be destroyed
3263 with @code{gpgme_trust_item_release}.  @xref{Manipulating Trust Items}.
3264
3265 This is the only way to get at @code{gpgme_trust_item_t} objects in
3266 @acronym{GPGME}.
3267
3268 If the last trust item in the list has already been returned,
3269 @code{gpgme_op_trustlist_next} returns @code{GPG_ERR_EOF}.
3270
3271 The function returns the error code @code{GPG_ERR_INV_VALUE} if @var{ctx} or
3272 @var{r_item} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if
3273 there is not enough memory for the operation.
3274 @end deftypefun
3275
3276 @deftypefun gpgme_error_t gpgme_op_trustlist_end (@w{gpgme_ctx_t @var{ctx}})
3277 The function @code{gpgme_op_trustlist_next} ends a pending key list
3278 operation in the context @var{ctx}.
3279
3280 The function returns the error code @code{GPG_ERR_INV_VALUE} if
3281 @var{ctx} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if at some
3282 time during the operation there was not enough memory available.
3283 @end deftypefun
3284
3285
3286 @node Information About Trust Items
3287 @subsection Information About Trust Items
3288 @cindex trust item, information about
3289 @cindex trust item, attributes
3290 @cindex attributes, of a trust item
3291
3292 The following interfaces are deprecated and only provided for backward
3293 compatibility.  Don't use them.  They will be removed in a future
3294 version of @acronym{GPGME}.
3295
3296 Trust items have attributes which can be queried using the interfaces
3297 below.  The attribute identifiers are shared with those for key
3298 attributes.  @xref{Information About Keys}.
3299
3300 @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}})
3301 The function @code{gpgme_trust_item_get_string_attr} returns the value
3302 of the string-representable attribute @var{what} of trust item
3303 @var{item}.  The arguments @var{idx} and @var{reserved} are reserved
3304 for later use and should be @code{0} and @code{NULL} respectively.
3305
3306 The string returned is only valid as long as the key is valid.
3307
3308 The function returns @code{0} if an attribute can't be returned as a
3309 string, @var{key} is not a valid pointer, @var{idx} out of range,
3310 or @var{reserved} not @code{NULL}.
3311 @end deftypefun
3312
3313 @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}})
3314 The function @code{gpgme_trust_item_get_int_attr} returns the value of
3315 the number-representable attribute @var{what} of trust item
3316 @var{item}.  If the attribute occurs more than once in the trust item,
3317 the index is specified by @var{idx}.  However, currently no such
3318 attribute exists, so @var{idx} should be @code{0}.  The argument
3319 @var{reserved} is reserved for later use and should be @code{NULL}.
3320
3321 The function returns @code{0} if the attribute can't be returned as a
3322 number, @var{key} is not a valid pointer, @var{idx} out of range,
3323 or @var{reserved} not @code{NULL}.
3324 @end deftypefun
3325
3326
3327 @node Manipulating Trust Items
3328 @subsection Manipulating Trust Items
3329 @cindex trust item, manipulation
3330
3331 @deftypefun void gpgme_trust_item_ref (@w{gpgme_trust_item_t @var{item}})
3332 The function @code{gpgme_trust_item_ref} acquires an additional
3333 reference for the trust item @var{item}.
3334 @end deftypefun
3335
3336 @deftypefun void gpgme_trust_item_unref (@w{gpgme_trust_item_t @var{item}})
3337 The function @code{gpgme_trust_item_unref} releases a reference for
3338 the trust item @var{item}.  If this was the last reference, the trust
3339 item will be destroyed and all resources associated to it will be
3340 released.
3341 @end deftypefun
3342
3343
3344 The following interface is deprecated and only provided for backward
3345 compatibility.  Don't use it.  It will be removed in a future version
3346 of @acronym{GPGME}.
3347
3348 @deftypefun void gpgme_trust_item_release (@w{gpgme_trust_item_t @var{item}})
3349 The function @code{gpgme_trust_item_release} is an alias for
3350 @code{gpgme_trust_item_unref}.
3351 @end deftypefun
3352
3353
3354 @node Crypto Operations
3355 @section Crypto Operations
3356 @cindex cryptographic operation
3357
3358 Sometimes, the result of a crypto operation returns a list of invalid
3359 keys encountered in processing the request.  The following structure
3360 is used to hold information about such a key.
3361
3362 @deftp {Data type} {gpgme_invalid_key_t}
3363 This is a pointer to a structure used to store a part of the result of
3364 a crypto operation which takes user IDs as one input parameter.  The
3365 structure contains the following members:
3366
3367 @table @code
3368 @item gpgme_invalid_key_t next
3369 This is a pointer to the next invalid key structure in the linked
3370 list, or @code{NULL} if this is the last element.
3371
3372 @item char *fpr
3373 The fingerprint or key ID of the invalid key encountered.
3374
3375 @item gpgme_error_t reason
3376 An error code describing the reason why the key was found invalid.
3377 @end table
3378 @end deftp
3379
3380
3381 @menu
3382 * Decrypt::                       Decrypting a ciphertext.
3383 * Verify::                        Verifying a signature.
3384 * Decrypt and Verify::            Decrypting a signed ciphertext.
3385 * Sign::                          Creating a signature.
3386 * Encrypt::                       Encrypting a plaintext.
3387 @end menu
3388
3389
3390 @node Decrypt
3391 @subsection Decrypt
3392 @cindex decryption
3393 @cindex cryptographic operation, decryption
3394
3395 @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}})
3396 The function @code{gpgme_op_decrypt} decrypts the ciphertext in the
3397 data object @var{cipher} and stores it into the data object
3398 @var{plain}.
3399
3400 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3401 ciphertext could be decrypted successfully, @code{GPG_ERR_INV_VALUE}
3402 if @var{ctx}, @var{cipher} or @var{plain} is not a valid pointer,
3403 @code{GPG_ERR_NO_DATA} if @var{cipher} does not contain any data to
3404 decrypt, @code{GPG_ERR_DECRYPT_FAILED} if @var{cipher} is not a valid
3405 cipher text, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the
3406 secret key could not be retrieved, and passes through any errors that
3407 are reported by the crypto engine support routines.
3408 @end deftypefun
3409
3410 @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}})
3411 The function @code{gpgme_op_decrypt_start} initiates a
3412 @code{gpgme_op_decrypt} operation.  It can be completed by calling
3413 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
3414
3415 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3416 operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
3417 if @var{cipher} or @var{plain} is not a valid pointer.
3418 @end deftypefun
3419
3420 @deftp {Data type} {gpgme_decrypt_result_t}
3421 This is a pointer to a structure used to store the result of a
3422 @code{gpgme_op_decrypt} operation.  After successfully encrypting
3423 data, you can retrieve the pointer to the result with
3424 @code{gpgme_op_decrypt_result}.  The structure contains the following
3425 members:
3426
3427 @table @code
3428 @item char *unsupported_algorithm
3429 If an unsupported algorithm was encountered, this string describes the
3430 algorithm that is not supported.
3431 @end table
3432 @end deftp
3433
3434 @deftypefun gpgme_decrypt_result_t gpgme_op_decrypt_result (@w{gpgme_ctx_t @var{ctx}})
3435 The function @code{gpgme_op_decrypt_result} returns a
3436 @code{gpgme_decrypt_result_t} pointer to a structure holding the
3437 result of a @code{gpgme_op_decrypt} operation.  The pointer is only
3438 valid if the last operation on the context was a
3439 @code{gpgme_op_decrypt} or @code{gpgme_op_decrypt_start} operation.
3440 If the operation failed this might be a @code{NULL} pointer.  The
3441 returned pointer is only valid until the next operation is started on
3442 the context.
3443 @end deftypefun
3444
3445
3446 @node Verify
3447 @subsection Verify
3448 @cindex verification
3449 @cindex signature, verification
3450 @cindex cryptographic operation, verification
3451 @cindex cryptographic operation, signature check
3452
3453 @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}})
3454 The function @code{gpgme_op_verify} verifies that the signature in the
3455 data object @var{sig} is a valid signature.  If @var{sig} is a
3456 detached signature, then the signed text should be provided in
3457 @var{signed_text} and @var{plain} should be a null pointer.
3458 Otherwise, if @var{sig} is a normal (or cleartext) signature,
3459 @var{signed_text} should be a null pointer and @var{plain} should be a
3460 writable data object that will contain the plaintext after successful
3461 verification.
3462
3463 The results of the individual signature verifications can be retrieved
3464 with @code{gpgme_op_verify_result}.
3465
3466 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3467 operation could be completed successfully, @code{GPG_ERR_INV_VALUE} if
3468 @var{ctx}, @var{sig} or @var{plain} is not a valid pointer,
3469 @code{GPG_ERR_NO_DATA} if @var{sig} does not contain any data to
3470 verify, and passes through any errors that are reported by the crypto
3471 engine support routines.
3472 @end deftypefun
3473
3474 @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}})
3475 The function @code{gpgme_op_verify_start} initiates a
3476 @code{gpgme_op_verify} operation.  It can be completed by calling
3477 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
3478
3479 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
3480 operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
3481 @var{ctx}, @var{sig} or @var{plain} is not a valid pointer, and
3482 @code{GPG_ERR_NO_DATA} if @var{sig} or @var{plain} does not contain
3483 any data to verify.
3484 @end deftypefun
3485
3486 @deftp {Data type} {gpgme_sig_notation_t}
3487 This is a pointer to a structure used to store a part of the result of
3488 a @code{gpgme_op_verify} operation.  The structure contains the
3489 following members:
3490
3491 @table @code
3492 @item gpgme_sig_notation_t next
3493 This is a pointer to the next new signature notation structure in the
3494 linked list, or @code{NULL} if this is the last element.
3495
3496 @item char *name
3497 The name of the notation field.  If this is @code{NULL}, then the
3498 member @code{value} will contain a policy URL.
3499
3500 @item char *value
3501 The value of the notation field.  If @code{name} is @code{NULL}, then
3502 this is a policy URL.
3503 @end table
3504 @end deftp
3505
3506 @deftp {Data type} {gpgme_signature_t}
3507 This is a pointer to a structure used to store a part of the result of
3508 a @code{gpgme_op_verify} operation.  The structure contains the
3509 following members:
3510
3511 @table @code
3512 @item gpgme_signature_t next
3513 This is a pointer to the next new signature structure in the linked
3514 list, or @code{NULL} if this is the last element.
3515
3516 @item gpgme_sigsum_t summary;
3517 This is a bit vector giving a summary of the signature status.  It
3518 provides an easy interface to a defined semantic of the signature
3519 status.  Checking just one bit is sufficient to see whether a
3520 signature is valid without any restrictions.
3521
3522 The defined bits are:
3523   @table @code
3524   @item GPGME_SIGSUM_VALID
3525   The signature is fully valid.
3526
3527   @item GPGME_SIGSUM_GREEN
3528   The signature is good but one might want to display some extra
3529   information.  Check the other bits.
3530
3531   @item GPGME_SIGSUM_RED
3532   The signature is bad. It might be useful to check other bits and
3533   display more information, i.e. a revoked certificate might not render a
3534   signature invalid when the message was received prior to the cause for
3535   the revocation.
3536
3537   @item GPGME_SIGSUM_KEY_REVOKED
3538   The key or at least one certificate has been revoked.
3539
3540   @item GPGME_SIGSUM_KEY_EXPIRED
3541   The key or one of the certificates has expired. It is probably a good
3542   idea to display the date of the expiration.
3543
3544   @item GPGME_SIGSUM_SIG_EXPIRED
3545   The signature has expired.
3546
3547   @item GPGME_SIGSUM_KEY_MISSING
3548   Can't verify due to a missing key or certificate.
3549
3550   @item GPGME_SIGSUM_CRL_MISSING
3551   The CRL (or an equivalent mechanism) is not available. 
3552
3553   @item GPGME_SIGSUM_CRL_TOO_OLD
3554   Available CRL is too old.
3555
3556   @item GPGME_SIGSUM_BAD_POLICY
3557   A policy requirement was not met. 
3558
3559   @item GPGME_SIGSUM_SYS_ERROR
3560   A system error occured. 
3561   @end table
3562
3563 @item char *fpr
3564 This is the fingerprint or key ID of the signature.
3565
3566 @item gpgme_error_t status
3567 This is the status of the signature.  In particular, the following
3568 status codes are of interest:
3569
3570   @table @code
3571   @item GPG_ERR_NO_ERROR
3572   This status indicates that the signature is valid.  For the combined
3573   result this status means that all signatures are valid.
3574
3575   @item GPG_ERR_SIG_EXPIRED
3576   This status indicates that the signature is valid but expired.  For
3577   the combined result this status means that all signatures are valid
3578   and expired.
3579
3580   @item GPG_ERR_KEY_EXPIRED
3581   This status indicates that the signature is valid but the key used to
3582   verify the signature has expired.  For the combined result this status
3583   means that all signatures are valid and all keys are expired.
3584
3585   @item GPG_ERR_BAD_SIGNATURE
3586   This status indicates that the signature is invalid.  For the combined
3587   result this status means that all signatures are invalid.
3588
3589   @item GPG_ERR_NO_PUBKEY
3590   This status indicates that the signature could not be verified due to
3591   a missing key.  For the combined result this status means that all
3592   signatures could not be checked due to missing keys.
3593
3594   @item GPG_ERR_GENERAL
3595   This status indicates that there was some other error which prevented
3596   the signature verification.
3597   @end table
3598
3599 @item gpgme_sig_notation_t notations
3600 This is a linked list with the notation data and policy URLs.
3601
3602 @item unsigned long timestamp
3603 The creation timestamp of this signature.
3604
3605 @item unsigned long exp_timestamp
3606 The expiration timestamp of this signature, or 0 if the signature does
3607 not expire.
3608
3609 @item int wrong_key_usage : 1;
3610 This is true if the key was not used according to its policy.
3611
3612 @item gpgme_validity_t validity
3613 The validity of the signature.
3614
3615 @item gpgme_error_t validity_reason
3616 If a signature is not valid, this provides a reason why.
3617
3618 @end table
3619 @end deftp
3620
3621 @deftp {Data type} {gpgme_verify_result_t}
3622 This is a pointer to a structure used to store the result of a
3623 @code{gpgme_op_verify} operation.  After verifying a signature, you
3624 can retrieve the pointer to the result with
3625 @code{gpgme_op_verify_result}.  If the operation failed this might be
3626 a @code{NULL} pointer.  The structure contains the following member:
3627
3628 @table @code
3629 @item gpgme_signature_t signatures
3630 A linked list with information about all signatures for which a
3631 verification was attempted.
3632 @end table
3633 @end deftp
3634
3635 @deftypefun gpgme_sign_result_t gpgme_op_verify_result (@w{gpgme_ctx_t @var{ctx}})
3636 The function @code{gpgme_op_verify_result} returns a
3637 @code{gpgme_verify_result_t} pointer to a structure holding the result of
3638 a @code{gpgme_op_verify} operation.  The pointer is only valid if the
3639 last operation on the context was a @code{gpgme_op_verify} or
3640 @code{gpgme_op_verify_start} operation, and if this operation finished
3641 successfully.  The returned pointer is only valid until the next
3642 operation is started on the context.
3643 @end deftypefun
3644
3645
3646 The following interfaces are deprecated and only provided for backward
3647 compatibility.  Don't use them.  They will be removed in a future
3648 version of @acronym{GPGME}.
3649
3650 @deftp {Data type} {enum gpgme_sig_stat_t}
3651 @tindex gpgme_sig_stat_t
3652 The @code{gpgme_sig_stat_t} type holds the result of a signature check, or
3653 the combined result of all signatures.  The following results are
3654 possible:
3655
3656 @table @code
3657 @item GPGME_SIG_STAT_NONE
3658 This status should not occur in normal operation.
3659
3660 @item GPGME_SIG_STAT_GOOD
3661 This status indicates that the signature is valid.  For the combined
3662 result this status means that all signatures are valid.
3663
3664 @item GPGME_SIG_STAT_GOOD_EXP
3665 This status indicates that the signature is valid but expired.  For
3666 the combined result this status means that all signatures are valid
3667 and expired.
3668
3669 @item GPGME_SIG_STAT_GOOD_EXPKEY
3670 This status indicates that the signature is valid but the key used to
3671 verify the signature has expired.  For the combined result this status
3672 means that all signatures are valid and all keys are expired.
3673
3674 @item GPGME_SIG_STAT_BAD
3675 This status indicates that the signature is invalid.  For the combined
3676 result this status means that all signatures are invalid.
3677
3678 @item GPGME_SIG_STAT_NOKEY
3679 This status indicates that the signature could not be verified due to
3680 a missing key.  For the combined result this status means that all
3681 signatures could not be checked due to missing keys.
3682
3683 @item GPGME_SIG_STAT_NOSIG
3684 This status indicates that the signature data provided was not a real
3685 signature.
3686
3687 @item GPGME_SIG_STAT_ERROR
3688 This status indicates that there was some other error which prevented
3689 the signature verification.
3690
3691 @item GPGME_SIG_STAT_DIFF
3692 For the combined result this status means that at least two signatures
3693 have a different status.  You can get each key's status with
3694 @code{gpgme_get_sig_status}.
3695 @end table
3696 @end deftp
3697
3698 @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}})
3699 The function @code{gpgme_get_sig_status} is equivalent to:
3700  
3701 @example
3702   gpgme_verify_result_t result;
3703   gpgme_signature_t sig;
3704
3705   result = gpgme_op_verify_result (ctx);
3706   sig = result->signatures;
3707
3708   while (sig && idx)
3709     @{
3710       sig = sig->next;
3711       idx--;
3712     @}
3713   if (!sig || idx)
3714     return NULL;
3715
3716   if (r_stat)
3717     @{
3718       switch (gpg_err_code (sig->status))
3719         @{
3720         case GPG_ERR_NO_ERROR:
3721           *r_stat = GPGME_SIG_STAT_GOOD;
3722           break;
3723           
3724         case GPG_ERR_BAD_SIGNATURE:
3725           *r_stat = GPGME_SIG_STAT_BAD;