doc/
[gpgme.git] / doc / gpgme.texi
1 \input texinfo                  @c -*- Texinfo -*-
2 @setfilename gpgme.info
3 @settitle The `GnuPG Made Easy' Reference Manual
4
5 @dircategory GNU Libraries
6 @direntry
7 * @acronym{GPGME}: (gpgme)           Adding support for cryptography to your program.
8 @end direntry
9
10 @include version.texi
11
12 @c Unify some of the indices.
13 @syncodeindex tp fn
14 @syncodeindex pg fn
15
16 @ifinfo
17 This file documents the @acronym{GPGME} library.
18
19 This is Edition @value{EDITION}, last updated @value{UPDATED}, of
20 @cite{The `GnuPG Made Easy' Reference Manual}, for Version
21 @value{VERSION}.
22
23 Copyright @copyright{} 2002 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 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 * Error Handling::                Error numbers and their meanings.
77 * Exchanging Data::               Passing data to and from @acronym{GPGME}.
78 * Contexts::                      Handling @acronym{GPGME} contexts.
79
80 Appendices
81
82 * Copying::                       The GNU General Public License says how you
83                                   can copy and share `GnuPG Made Easy'.
84 * Free Documentation License::    This manual is under the GNU Free
85                                   Documentation License.
86
87 Indices
88
89 * Concept Index::                 Index of concepts and programs.
90 * Function and Data Index::       Index of functions, variables and data types.
91
92
93 @detailmenu
94  --- The Detailed Node Listing ---
95
96 Introduction
97
98 * Getting Started::               Purpose of the manual, and how to use it.
99 * Features::                      Reasons to install and use @acronym{GPGME}.
100 * Overview::                      Basic architecture of the @acronym{GPGME} library.
101
102 Preparation
103
104 * Header::                        What header file you need to include.
105 * Building the Source::           Compiler options to be used.
106 * Library Version Check::         Getting and verifying the library version.
107
108 Protocols and Engines
109
110 * Engine Version Check::          Verifying the engine version.
111 * Engine Information::            Obtaining more information about the engines.
112 * OpenPGP::                       Support for the OpenPGP protocol.
113 * Cryptographic Message Syntax::  Support for the CMS.
114
115 Error Handling
116
117 * Error Values::                  A list of all error values used.
118 * Error Strings::                 How to get a descriptive string from a value.
119
120 Exchanging Data 
121
122 * Creating Data Buffers::         Creating new data buffers.
123 * Destroying Data Buffers::       Releasing data buffers.
124 * Manipulating Data Buffers::     Operations on data buffers.
125
126 Contexts
127
128 * Creating Contexts::             Creating new @acronym{GPGME} contexts.
129 * Destroying Contexts::           Releasing @acronym{GPGME} contexts.
130 * Context Attributes::            Setting properties of a context.
131 * Key Management::                Managing keys with @acronym{GPGME}.
132 * Trust Item Management::         Managing trust items with @acronym{GPGME}.
133 * Crypto Operations::             Using a context for cryptography.
134 * Run Control::                   Controlling how operations are run.
135
136 Context Attributes
137
138 * Protocol Selection::            Selecting the protocol used by a context.
139 * @acronym{ASCII} Armor::                   Requesting @acronym{ASCII} armored output.
140 * Text Mode::                     Choosing canonical text mode.
141 * Key Listing Mode::              Selecting key listing mode.
142 * Passphrase Callback::           Getting the passphrase from the user.
143 * Progress Meter Callback::       Being informed about the progress.
144
145 Key Management
146
147 * Listing Keys::                  Browsing the list of available keys.
148 * Information About Keys::        Requesting detailed information about keys.
149 * Manipulating Keys::             Operations on keys.
150 * Generating Keys::               Creating new key pairs.
151 * Exporting Keys::                Retrieving key data from the key ring.
152 * Importing Keys::                Adding keys to the key ring.
153 * Deleting Keys::                 Removing keys from the key ring.
154
155 Trust Item Management
156
157 * Listing Trust Items::           Browsing the list of available trust items.
158 * Information About Trust Items:: Requesting detailed information about trust items.
159 * Manipulating Trust Items::      Operations on trust items.
160
161 Crypto Operations
162
163 * Decrypt::                       Decrypting a ciphertext.
164 * Verify::                        Verifying a signature.
165 * Decrypt and Verify::            Decrypting a signed ciphertext.
166 * Sign::                          Creating a signature.
167 * Encrypt::                       Encrypting a plaintext.
168 * Detailed Results::              How to obtain more info about the operation.
169
170 Sign
171
172 * Selecting Signers::             How to choose the keys to sign with.
173 * Creating a Signature::          How to create a signature.
174
175 Encrypt
176
177 * Selecting Recipients::          How to choose the recipients.
178 * Encrypting a Plaintext::        How to encrypt a plaintext.
179
180 Run Control
181
182 * Waiting For Completion::        Waiting until an operation is completed.
183 * Cancelling an Operation::       Interrupting a running operation.
184 * Hooking Up Into Idle Time::     Doing something when nothing has to be done.
185
186 @end detailmenu
187 @end menu
188
189 @node Introduction
190 @chapter Introduction
191
192 `GnuPG Made Easy' (@acronym{GPGME}) is a C language library that
193 allows to add support for cryptography to a program.  It is designed
194 to make access to crypto engines like GnuPG or GpgSM easier for
195 applications.  @acronym{GPGME} provides a high-level crypto API for
196 encryption, decryption, signing, signature verification and key
197 management.
198
199 @acronym{GPGME} uses GnuPG and GpgSM as its backends to support
200 OpenPGP and the Cryptographic Message Syntax (CMS).
201
202 @menu
203 * Getting Started::               Purpose of the manual, and how to use it.
204 * Features::                      Reasons to install and use @acronym{GPGME}.
205 * Overview::                      Basic architecture of the @acronym{GPGME} library.
206 @end menu
207
208
209 @node Getting Started
210 @section Getting Started
211
212 This library documents the @acronym{GPGME} library programming
213 interface.  All functions and data types provided by the library are
214 explained.
215
216 The reader is assumed to possess basic knowledge about cryptography in
217 general, and public key cryptography in particular.  The underlying
218 cryptographic engines that are used by the library are not explained,
219 but where necessary, special features or requirements by an engine are
220 mentioned as far as they are relevant to @acronym{GPGME} or its users.
221
222 This manual can be used in several ways.  If read from the beginning
223 to the end, it gives a good introduction into the library and how it
224 can be used in an application.  Forward references are included where
225 necessary.  Later on, the manual can be used as a reference manual to
226 get just the information needed about any particular interface of the
227 library.  Experienced programmers might want to start looking at the
228 examples at the end of the manual, and then only read up those parts
229 of the interface which are unclear.
230
231
232 @node Features
233 @section Features
234
235 @acronym{GPGME} has a couple of advantages over other libraries doing
236 a similar job, and over implementing support for GnuPG or other crypto
237 engines into your application directly.
238
239 @table @asis
240 @item it's free software
241 Anybody can use, modify, and redistribute it under the terms of the GNU
242 General Public License (@pxref{Copying}).
243
244 @item it's flexible
245 @acronym{GPGME} provides transparent support for several cryptographic
246 protocols by different engines.  Currently, @acronym{GPGME} supports
247 the OpenPGP protocol using GnuPG as the backend, and the Cryptographic
248 Message Syntax using GpgSM as the backend.
249
250 @item it's easy
251 @acronym{GPGME} hides the differences between the protocols and
252 engines from the programmer behind an easy-to-use interface.  This way
253 the programmer can focus on the other parts of the program, and still
254 integrate strong cryptography in his application.  Once support for
255 @acronym{GPGME} has been added to a program, it is easy to add support
256 for other crypto protocols once @acronym{GPGME} backends provide them.
257 @end table
258
259
260 @node Overview
261 @section Overview
262
263 @acronym{GPGME} provides a data abstraction that is used to pass data
264 to the crypto engine, and receive returned data from it.  Data can be
265 read from memory or from files, but it can also be provided by a
266 callback function.
267
268 The actual cryptographic operations are always set within a context.
269 A context provides configuration parameters that define the behaviour
270 of all operations performed within it.  Only one operation per context
271 is allowed at any time, but when one operation is finished, you can
272 run the next operation in the same context.  There can be more than
273 one context, and all can run different operations at the same time.
274
275 Furthermore, @acronym{GPGME} has rich key management facilities
276 including listing keys, querying their attributes, generating,
277 importing, exporting and deleting keys, and acquiring information
278 about the trust path.
279
280 @cindex thread-safeness
281 @cindex multi-threading
282 @strong{Caution:} The @acronym{GPGME} library is not thread-safe.  It
283 will be to some extent in the future, but currently great care has to
284 be taken if @acronym{GPGME} is used in a multi-threaded environment.
285
286
287 @node Preparation
288 @chapter Preparation
289
290 To use @acronym{GPGME}, you have to perform some changes to your
291 sources and the build system.  The necessary changes are small and
292 explained in the following sections.  At the end of this chapter, it
293 is described how the library is initialized, and how the requirements
294 of the library are verified.
295
296 @menu
297 * Header::                        What header file you need to include.
298 * Building the Source::           Compiler options to be used.
299 * Library Version Check::         Getting and verifying the library version.
300 @end menu
301
302
303 @node Header
304 @section Header
305 @cindex header file
306 @cindex include file
307
308 All interfaces (data types and functions) of the library are defined
309 in the header file `gpgme.h'.  You must include this in all programs
310 using the library, either directly or through some other header file,
311 like this:
312
313 @example
314 #include <gpgme.h>
315 @end example
316
317 The name space of @acronym{GPGME} is @code{gpgme_*} for function
318 names, @code{Gpgme*} for data types and @code{GPGME_*} for other
319 symbols.
320
321
322 @node Building the Source
323 @section Building the Source
324 @cindex compiler options
325 @cindex compiler flags
326
327 If you want to compile a source file including the `gpgme.h' header
328 file, you must make sure that the compiler can find it in the
329 directory hierarchy.  This is accomplished by adding the path to the
330 directory in which the header file is located to the compilers include
331 file search path (via the @option{-I} option).
332
333 However, the path to the include file is determined at the time the
334 source is configured.  To solve this problem, gpgme ships with a small
335 helper program @command{gpgme-config} that knows about the path to the
336 include file and other configuration options.  The options that need
337 to be added to the compiler invocation at compile time are output by
338 the @option{--cflags} option to @command{gpgme-config}.  The following
339 example shows how it can be used at the command line:
340
341 @example
342 gcc -c foo.c `gpgme-config --cflags`
343 @end example
344
345 Adding the output of @samp{gpgme-config --cflags} to the compilers
346 command line will ensure that the compiler can find the @acronym{GPGME} header
347 file.
348
349 A similar problem occurs when linking the program with the library.
350 Again, the compiler has to find the library files.  For this to work,
351 the path to the library files has to be added to the library search
352 path (via the @option{-L} option).  For this, the option
353 @option{--libs} to @command{gpgme-config} can be used.  For
354 convenience, this option also outputs all other options that are
355 required to link the program with @acronym{GPGME} (in particular, the
356 @samp{-lgpgme} option).  The example shows how to link @file{foo.o}
357 with the @acronym{GPGME} library to a program @command{foo}.
358
359 @example
360 gcc -o foo foo.o `gpgme-config --libs`
361 @end example
362
363 Of course you can also combine both examples to a single command by
364 specifying both options to @command{gpgme-config}:
365
366 @example
367 gcc -o foo foo.c `gpgme-config --cflags --libs`
368 @end example
369
370
371 @node Library Version Check
372 @section Library Version Check
373 @cindex version check, of the library
374
375 @deftypefun {const char *} gpgme_check_version (@w{const char *@var{required_version}})
376 The function @code{gpgme_check_version} has three purposes.  It can be
377 used to retrieve the version number of the library.  In addition it
378 can verify that the version number is higher than a certain required
379 version number.  In either case, the function initializes some
380 sub-systems, and for this reason alone it must be invoked early in
381 your program, before you make use of the other functions in
382 @acronym{GPGME}.
383
384 If @var{required_version} is @code{NULL}, the function returns a
385 pointer to a statically allocated string containing the version number
386 of the library.
387
388 If @var{required_version} is not @code{NULL}, it should point to a
389 string containing a version number, and the function checks that the
390 version of the library is at least as high as the version number
391 provided.  In this case, the function returns a pointer to a
392 statically allocated string containing the version number of the
393 library.  If @var{REQUIRED_VERSION} is not a valid version number, or
394 if the version requirement is not met, the function returns
395 @code{NULL}.
396
397 If you use a version of a library that is backwards compatible with
398 older releases, but contains additional interfaces which your program
399 uses, this function provides a run-time check if the necessary
400 features are provided by the installed version of the library.
401 @end deftypefun
402
403
404 @node Protocols and Engines
405 @chapter Protocols and Engines
406 @cindex protocol
407 @cindex engine
408 @cindex crypto engine
409 @cindex backend
410 @cindex crypto backend
411
412 @acronym{GPGME} supports several cryptographic protocols, however, it
413 does not implement them.  Rather it uses backends (also called
414 engines) which implement the protocol.  @acronym{GPGME} uses
415 inter-process communication to pass data back and forth between the
416 application and the backend, but the details of the communication
417 protocol and invocation of the backends is completely hidden by the
418 interface.  All complexity is handled by @acronym{GPGME}.  Where an
419 exchange of information between the application and the backend is
420 necessary, @acronym{GPGME} provides the necessary callback function
421 hooks and further interfaces.
422
423 @deftp {Data type} {enum GpgmeProtocol}
424 @tindex GpgmeProtocol
425 The @code{GpgmeProtocol} type specifies the set of possible protocol
426 values that are supported by @acronym{GPGME}.  The following protocols
427 are supported:
428
429 @table @code
430 @item GPGME_PROTOCOL_OpenPGP
431 This specifies the OpenPGP protocol.
432 @item GPGME_PROTOCOL_CMS
433 This specifies the Cryptographic Message Syntax.
434 @end table
435 @end deftp
436
437 @menu
438 * Engine Version Check::          Verifying the engine version.
439 * Engine Information::            Obtaining more information about the engines.
440 * OpenPGP::                       Support for the OpenPGP protocol.
441 * Cryptographic Message Syntax::  Support for the CMS.
442 @end menu
443
444
445 @node Engine Version Check
446 @section Engine Version Check
447 @cindex version check, of the engines
448
449 @deftypefun GpgmeError gpgme_engine_check_version (@w{GpgmeProtocol @var{protocol}})
450 The function @code{gpgme_engine_check_version} verifies that the
451 engine implementing the protocol @var{PROTOCOL} is installed in the
452 expected path and meets the version requirement of @acronym{GPGME}.
453
454 This function returns @code{GPGME_No_Error} if the engine is available
455 and @code{GPGME_Invalid_Engine} if it is not.
456 @end deftypefun
457
458 @deftypefun GpgmeError gpgme_check_engine (void)
459 The function @code{gpgme_check_engine} is equivalent to
460
461 @example
462 gpgme_engine_check_version (GPGME_PROTOCOL_OpenPGP);
463 @end example
464
465 This function is deprecated and provided for backwards compatibility
466 only.  It is obsoleted by @code{gpgme_engine_check_version}.
467 @end deftypefun
468
469
470 @node Engine Information
471 @section Engine Information
472 @cindex engine, information about
473
474 @deftypefun {const char *} gpgme_get_engine_info (void)
475 The function @code{gpgme_get_engine_info} returns an @acronym{XML}
476 string containing information about the available protocols and the
477 engine which implement them.  The following information is returned
478 for each engine:
479
480 @table @samp
481 @item <protocol>
482 The name of the protocol.
483 @item <version>
484 The version of the engine.
485 @item <path>
486 The path to the engine binary.
487 @end table
488
489 A string is always returned.  If an error occurs, the string will
490 contain an @samp{<error>} tag with a description of the failure.
491 @end deftypefun
492
493 Here is the example output of what @code{gpgme_get_engine_info} might
494 return on your system:
495
496 @example
497 <EngineInfo>
498  <engine>
499   <protocol>OpenPGP</protocol>
500   <version>1.0.6</version>
501   <path>/usr/bin/gpg</path>
502  </engine>
503  <engine>
504   <protocol>CMS</protocol>
505   <version>0.0.0</version>
506   <path>/usr/bin/gpgsm</path>
507  </engine>
508 </EngineInfo>
509 @end example
510
511
512 @node OpenPGP
513 @section OpenPGP
514 @cindex OpenPGP
515 @cindex GnuPG
516 @cindex protocol, GnuPG
517 @cindex engine, GnuPG
518
519 OpenPGP is implemented by GnuPG, the @acronym{GNU} Privacy Guard.
520 This is the first protocol that was supported by @acronym{GPGME}.
521
522 The OpenPGP protocol is specified by @code{GPGME_PROTOCOL_OpenPGP}.
523
524
525 @node Cryptographic Message Syntax
526 @section Cryptographic Message Syntax
527 @cindex CMS
528 @cindex cryptographic message syntax
529 @cindex GpgSM
530 @cindex protocol, CMS
531 @cindex engine, GpgSM
532 @cindex S/MIME
533 @cindex protocol, S/MIME
534
535 @acronym{CMS} is implemented by GpgSM, the S/MIME implementation for
536 GnuPG.
537
538 The @acronym{CMS} protocol is specified by @code{GPGME_PROTOCOL_CMS}.
539
540
541 @node Error Handling
542 @chapter Error Handling
543 @cindex error handling
544
545 Many functions in @acronym{GPGME} can return an error if they fail.
546 For this reason, the application should always catch the error
547 condition and take appropriate measures, for example by releasing the
548 resources and passing the error up to the caller, or by displaying a
549 descriptive message to the user and cancelling the operation.
550
551 Some error values do not indicate a system error or an error in the
552 operation, but the result of an operation that failed properly.  For
553 example, if you try to decrypt a tempered message, the decryption will
554 fail.  Another error value actually means that the end of a data
555 buffer or list has been reached.  The following descriptions explain
556 what each error message means in general.  Some error values have
557 specific meanings if returned by a specific function.  Such cases are
558 described in the documentation of those functions.
559
560 @menu
561 * Error Values::                  A list of all error values used.
562 * Error Strings::                 How to get a descriptive string from a value.
563 @end menu
564
565
566 @node Error Values
567 @section Error Values
568 @cindex error values, list of
569
570 @deftp {Data type} {enum GpgmeError}
571 @tindex GpgmeError
572 The @code{GpgmeError} type specifies the set of all error values that
573 are used by @acronym{GPGME}.  Possible values are:
574
575 @table @code
576 @item GPGME_EOF
577 This value indicates the end of a list, buffer or file.
578
579 @item GPGME_No_Error
580 This value indicates success.  The value of this error is @code{0}.
581
582 @item GPGME_General_Error
583 This value means that something went wrong, but either there is not
584 enough information about the problem to return a more useful error
585 value, or there is no separate error value for this type of problem.
586
587 @item GPGME_Out_Of_Core
588 This value means that an out-of-memory condition occurred.
589
590 @item GPGME_Invalid_Value
591 This value means that some user provided data was out of range.  This
592 can also refer to objects.  For example, if an empty @code{GpgmeData}
593 object was expected, but one containing data was provided, this error
594 value is returned.
595
596 @item GPGME_Busy
597 This value is returned if you try to start a new operation in a
598 context that is already busy with some earlier operation which was not
599 cancelled or finished yet.
600
601 @item GPGME_No_Request
602 This value is in some sense the opposite of @code{GPGME_Busy}.  There
603 is no pending operation, but it is required for the function to
604 succeed.
605
606 @item GPGME_Exec_Error
607 This value means that an error occurred when trying to spawn a child
608 process.
609
610 @item GPGME_Too_Many_Procs
611 This value means that there are too many active backend processes.
612
613 @item GPGME_Pipe_Error
614 This value means that the creation of a pipe failed.
615
616 @item GPGME_No_Recipients 
617 This value means that no recipients for a message have been set.
618
619 @item GPGME_No_Data
620 This value means that a @code{GpgmeData} object which was expected to
621 have content was found empty.
622
623 @item GPGME_Conflict
624 This value means that a conflict of some sort occurred.
625
626 @item GPGME_Not_Implemented
627 This value indicates that the specific function (or operation) is not
628 implemented.  This error should never happen.  It can only occur if
629 you use certain values or configuration options which do not work,
630 but for which we think that they should work at some later time.
631
632 @item GPGME_Read_Error
633 This value means that an I/O read operation failed.
634
635 @item GPGME_Write_Error
636 This value means that an I/O write operation failed.
637
638 @item GPGME_Invalid_Type
639 This value means that a user provided object was of a wrong or
640 incompatible type.  Usually this refers to the type of a
641 @code{GpgmeData} object.
642
643 @item GPGME_Invalid_Mode
644 This value means that a @code{GpgmeData} object has an incorrect mode
645 of operation (for example, doesn't support output although it is
646 attempted to use it as an output buffer).
647
648 @item GPGME_File_Error
649 This value means that a file I/O operation failed.  The value of
650 @code{errno} contains the system error value.
651
652 @item GPGME_Decryption_Failed
653 This value indicates that a decryption operation was unsuccessful.
654
655 @item GPGME_No_Passphrase
656 This value means that the user did not provide a passphrase when
657 requested.
658
659 @item GPGME_Canceled
660 This value means that the operation was canceled.
661
662 @item GPGME_Invalid_Key
663 This value means that a key was invalid.
664
665 @item GPGME_Invalid_Engine
666 This value means that the engine that implements the desired protocol
667 is currently not available.  This can either be because the sources
668 were configured to exclude support for this engine, or because the
669 engine is not installed properly.
670 @end table
671 @end deftp
672
673
674 @node Error Strings
675 @section Error Strings
676 @cindex error values, printing of
677 @cindex error strings
678
679 @deftypefun {const char *} gpgme_strerror (@w{GpgmeError @var{err}})
680 The function @code{gpgme_strerror} returns a pointer to a statically
681 allocated string containing a description of the error with the error
682 value @var{err}.  This string can be used to output a diagnostic
683 message to the user.
684 @end deftypefun
685
686
687 @node Exchanging Data
688 @chapter Exchanging Data
689 @cindex data, exchanging
690
691 A lot of data has to be exchanged between the user and the crypto
692 engine, like plaintext messages, ciphertext, signatures and
693 information about the keys.  The technical details about exchanging
694 the data information are completely abstracted by @acronym{GPGME}.
695 The user provides and receives the data via @code{GpgmeData} objects,
696 regardless of the communication protocol between @acronym{GPGME} and
697 the crypto engine in use.
698
699 @deftp {Data type} {GpgmeData}
700 The @code{GpgmeData} type is a handle for a container for generic
701 data, which is used by @acronym{GPGME} to exchange data with the user.
702 @end deftp
703
704 @menu
705 * Creating Data Buffers::         Creating new data buffers.
706 * Destroying Data Buffers::       Releasing data buffers.
707 * Manipulating Data Buffers::     Operations on data buffers.
708 @end menu
709
710
711 @node Creating Data Buffers
712 @section Creating Data Buffers
713 @cindex data buffer, creation
714
715 @deftypefun GpgmeError gpgme_data_new (@w{GpgmeData *@var{dh}})
716 The function @code{gpgme_data_new} creates a new @code{GpgmeData}
717 object and returns a handle for it in @var{dh}.  The data object is
718 initially empty.
719
720 The function returns @code{GPGME_No_Error} if the data object was
721 successfully created, @code{GPGME_Invalid_Value} if @var{dh} is not a
722 valid pointer, and @code{GPGME_Out_Of_Core} if not enough memory is
723 available.
724 @end deftypefun
725
726 @deftypefun GpgmeError gpgme_data_new_from_mem (@w{GpgmeData *@var{dh}}, @w{const char *@var{buffer}}, @w{size_t @var{size}}, @w{int @var{copy}})
727 The function @code{gpgme_data_new_from_mem} creates a new
728 @code{GpgmeData} object and fills it with @var{size} bytes starting
729 from @var{buffer}.
730
731 If @var{copy} is not zero, a private copy of the data is made.  If
732 @var{copy} is zero, the data is taken from the specified buffer as
733 needed, and the user has to ensure that the buffer remains valid for
734 the whole life span of the data object.
735
736 The function returns @code{GPGME_No_Error} if the data object was
737 successfully created, @code{GPGME_Invalid_Value} if @var{dh} or
738 @var{buffer} is not a valid pointer, and @code{GPGME_Out_Of_Core} if
739 not enough memory is available.
740 @end deftypefun
741
742 @deftypefun GpgmeError gpgme_data_new_from_file (@w{GpgmeData *@var{dh}}, @w{const char *@var{filename}}, @w{int @var{copy}})
743 The function @code{gpgme_data_new_from_file} creates a new
744 @code{GpgmeData} object and fills it with the content of the file
745 @var{filename}.
746
747 If @var{copy} is not zero, the whole file is read in at initialization
748 time and the file is not used anymore after that.  This is the only
749 mode supported currently.  Later, a value of zero for @var{copy} might
750 cause all reads to be delayed until the data is needed, but this is
751 not yet implemented.
752
753 The function returns @code{GPGME_No_Error} if the data object was
754 successfully created, @code{GPGME_Invalid_Value} if @var{dh} or
755 @var{filename} is not a valid pointer, @code{GPGME_File_Error} if an
756 I/O operation fails, @code{GPGME_Not_Implemented} if @var{code} is
757 zero, and @code{GPGME_Out_Of_Core} if not enough memory is available.
758 @end deftypefun
759
760 @deftypefun GpgmeError gpgme_data_new_from_filepart (@w{GpgmeData *@var{dh}}, @w{const char *@var{filename}}, @w{FILE *@var{fp}}, @w{off_t @var{offset}}, @w{size_t @var{length}})
761 The function @code{gpgme_data_new_from_filepart} creates a new
762 @code{GpgmeData} object and fills it with a part of the file specified
763 by @var{filename} or @var{fp}.
764
765 Exactly one of @var{filename} and @var{fp} must be non-zero, the other
766 must be zero.  The argument that is not zero specifies the file from
767 which @var{length} bytes are read into the data object, starting from
768 @var{offset}.
769
770 The function returns @code{GPGME_No_Error} if the data object was
771 successfully created, @code{GPGME_Invalid_Value} if @var{dh} and
772 exactly one of @var{filename} and @var{fp} is not a valid pointer,
773 @code{GPGME_File_Error} if an I/O operation fails, and
774 @code{GPGME_Out_Of_Core} if not enough memory is available.
775 @end deftypefun
776
777
778 @deftypefun GpgmeError gpgme_data_new_with_read_cb (@w{GpgmeData *@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}})
779 The function @code{gpgme_data_new_with_read_cb} creates a new
780 @code{GpgmeData} object and uses the callback function @var{readfunc}
781 to retrieve the data on demand.  As the callback function can supply
782 the data in any way it wants, this is the most flexible data type
783 @acronym{GPGME} provides.  However, it can not be used to write data.
784
785 The callback function receives @var{hook_value} as its first argument
786 whenever it is invoked.  It should return up to @var{count} bytes in
787 @var{buffer}, and return the number of bytes actually read in
788 @var{nread}.  It may return @code{0} in @var{nread} if no data is
789 currently available.  To indicate @code{EOF} the function should
790 return with an error code of @code{-1} and set @var{nread} to
791 @code{0}.  The callback function may support to reset its internal
792 read pointer if it is invoked with @var{buffer} and @var{nread} being
793 @code{NULL} and @var{count} being @code{0}.
794
795 The function returns @code{GPGME_No_Error} if the data object was
796 successfully created, @code{GPGME_Invalid_Value} if @var{dh} or
797 @var{readfunc} is not a valid pointer, and @code{GPGME_Out_Of_Core} if
798 not enough memory is available.
799 @end deftypefun
800
801
802 @node Destroying Data Buffers
803 @section Destroying Data Buffers
804 @cindex data buffer, destruction
805
806 @deftypefun void gpgme_data_release (@w{GpgmeData @var{dh}})
807 The function @code{gpgme_data_release} destroys the data object with
808 the handle @var{dh}.  It releases all associated resources that were
809 not provided by the user in the first place.
810 @end deftypefun
811
812 @deftypefun {char *} gpgme_data_release_and_get_mem (@w{GpgmeData @var{dh}}, @w{size_t *@var{length}})
813 The function @code{gpgme_data_release_and_get_mem} is like
814 @code{gpgme_data_release}, except that it returns the data buffer and
815 its length that was provided by the object.
816
817 The user has to release the buffer with @code{free}.  In case the user
818 provided the data buffer in non-copy mode, a copy will be made for
819 this purpose.
820
821 In case an error returns, or there is no suitable data buffer that can
822 be returned to the user, the function will return @code{NULL}.
823 @end deftypefun
824
825
826 @node Manipulating Data Buffers
827 @section Manipulating Data Buffers
828 @cindex data buffere, manipulation
829
830 @deftypefun GpgmeError gpgme_data_read (@w{GpgmeData @var{dh}}, @w{char *@var{buffer}}, @w{size_t @var{length}}, @w{size_t *@var{nread}})
831 The function @code{gpgme_data_read} reads up to @var{length} bytes
832 from the data object with the handle @var{dh} into the space starting
833 at @var{buffer}.  The actual amount read is returned in @var{nread}.
834
835 If @var{buffer} is @code{NULL}, the function returns the amount of
836 bytes available in @var{nread} without changing the read pointer.
837 This is not supported by all types of data objects.  If this function
838 is not supported, @code{GPGME_Invalid_Type} is returned.
839
840 If the end of the data object is reached, the function returns
841 @code{GPGME_EOF} and sets @var{nread} to zero.
842
843 In all other cases, the function returns @code{GPGME_No_Error} if the
844 operation was successfully performed and @code{GPGME_Invalid_Value} if
845 @var{dh} is not a valid pointer.
846 @end deftypefun
847
848 @deftypefun GpgmeError gpgme_data_rewind (@w{GpgmeData @var{dh}})
849 The function @code{gpgme_data_rewind} resets the read pointer of the
850 data object with the handle @var{dh}, so that a subsequent
851 @code{gpgme_data_read} operation starts at the beginning of the data.
852
853 The function returns @code{GPGME_No_Error} if the operation was
854 successfully performed, @code{GPGME_Not_Implemented} if the operation
855 is not supported (for example, by a read callback function supplied by
856 the user) and @code{GPGME_Invalid_Value} if @var{dh} is not a valid
857 pointer.
858 @end deftypefun
859
860 @deftypefun GpgmeError gpgme_data_write (@w{GpgmeData @var{dh}}, @w{const char *@var{buffer}}, @w{size_t @var{length}})
861 The function @code{gpgme_data_write} writes @var{length} bytes
862 starting from @var{buffer} into the data object with the handle
863 @var{dh} at the current write position.
864
865 The function returns @code{GPGME_No_Error} if the operation was
866 successfully performed, @code{GPGME_Invalid_Value} if @var{dh} or
867 @var{buffer} is not a valid pointer, @code{GPGME_Invalid_Type} or
868 @code{GPGME_Invalid_Mode} if the data object type does not support
869 writing, and @code{GPGME_Out_Of_Core} if not enough memory is
870 available.
871 @end deftypefun
872
873 @deftp {Data type} {enum GpgmeDataType}
874 @tindex GpgmeDataType
875 The @code{GpgmeDataType} type specifies the type of a @code{GpgmeData} object.
876 The following data types are available:
877
878 @table @code
879 @item GPGME_DATA_TYPE_NONE
880 This specifies that the type is not yet determined.
881
882 @item GPGME_DATA_TYPE_MEM
883 This specifies that the data is stored in memory.
884
885 @item GPGME_DATA_TYPE_FD
886 This type is not implemented.
887
888 @item GPGME_DATA_TYPE_FILE
889 This type is not implemented.
890
891 @item GPGME_DATA_TYPE_CB
892 This type specifies that the data is provided by a callback function
893 implemented by the user.
894 @end table
895 @end deftp
896
897 @deftypefun GpgmeDataType gpgme_data_get_type (@w{GpgmeData @var{dh}})
898 The function @code{gpgme_data_get_type} returns the type of the data
899 object with the handle @var{dh}.  If @var{dh} is not a valid pointer,
900 @code{GPGME_DATA_TYPE_NONE} is returned.
901 @end deftypefun
902
903
904 @node Contexts
905 @chapter Contexts
906 @cindex context
907
908 All cryptographic operations in @acronym{GPGME} are performed within a
909 context, which contains the internal state of the operation as well as
910 configuration parameters.  By using several contexts you can run
911 several cryptographic operations in parallel, with different
912 configuration.
913
914 @deftp {Data type} {GpgmeCtx}
915 The @code{GpgmeCtx} type is a handle for a @acronym{GPGME} context,
916 which is used to hold the configuration, status and result of
917 cryptographic operations.
918 @end deftp
919
920 @menu
921 * Creating Contexts::             Creating new @acronym{GPGME} contexts.
922 * Destroying Contexts::           Releasing @acronym{GPGME} contexts.
923 * Context Attributes::            Setting properties of a context.
924 * Key Management::                Managing keys with @acronym{GPGME}.
925 * Trust Item Management::         Managing trust items with @acronym{GPGME}.
926 * Crypto Operations::             Using a context for cryptography.
927 * Run Control::                   Controlling how operations are run.
928 @end menu
929
930
931 @node Creating Contexts
932 @section Creating Contexts
933 @cindex context, creation
934
935 @deftypefun GpgmeError gpgme_new (@w{GpgmeCtx *@var{ctx}})
936 The function @code{gpgme_data_new} creates a new @code{GpgmeCtx}
937 object and returns a handle for it in @var{ctx}.
938
939 The function returns @code{GPGME_No_Error} if the context was
940 successfully created, @code{GPGME_Invalid_Value} if @var{ctx} is not a
941 valid pointer, and @code{GPGME_Out_Of_Core} if not enough memory is
942 available.
943 @end deftypefun
944
945
946 @node Destroying Contexts
947 @section Destroying Contexts
948 @cindex context, destruction
949
950 @deftypefun void gpgme_release (@w{GpgmeCtx @var{ctx}})
951 The function @code{gpgme_release} destroys the context with the handle
952 @var{ctx} and releases all associated resources.
953 @end deftypefun
954
955
956 @node Context Attributes
957 @section Context Attributes
958 @cindex context, attributes
959
960 @menu
961 * Protocol Selection::            Selecting the protocol used by a context.
962 * @acronym{ASCII} Armor::                   Requesting @acronym{ASCII} armored output.
963 * Text Mode::                     Choosing canonical text mode.
964 * Key Listing Mode::              Selecting key listing mode.
965 * Passphrase Callback::           Getting the passphrase from the user.
966 * Progress Meter Callback::       Being informed about the progress.
967 @end menu
968
969
970 @node Protocol Selection
971 @subsection Protocol Selection
972 @cindex context, selecting protocol
973 @cindex protocol, selecting
974
975 @deftypefun GpgmeError gpgme_set_protocol (@w{GpgmeCtx @var{ctx}}, @w{GpgmeProtocol @var{proto}})
976 The function @code{gpgme_set_protocol} sets the protocol used within
977 the context @var{ctx} to @var{proto}.  All crypto operations will be
978 performed by the crypto engine configured for that protocol.
979 @xref{Protocols and Engines}.
980
981 Setting the protocol with @code{gpgme_set_protocol} does not check if
982 the crypto engine for that protocol is available and installed
983 correctly.  @xref{Engine Version Check}.
984
985 The function returns @code{GPGME_No_Error} if the protocol could be
986 set successfully, and @code{GPGME_Invalid_Value} if @var{protocol} is
987 not a valid protocol.
988 @end deftypefun
989
990
991 @node @acronym{ASCII} Armor
992 @subsection @acronym{ASCII} Armor
993 @cindex context, armor mode
994 @cindex @acronym{ASCII} armor
995 @cindex armor mode
996
997 @deftypefun void gpgme_set_armor (@w{GpgmeCtx @var{ctx}}, @w{int @var{yes}})
998 The function @code{gpgme_set_armor} specifies if the output should be
999 @acronym{ASCII} armored.  By default, output is not @acronym{ASCII}
1000 armored.
1001
1002 @acronym{ASCII} armored output is disabled if @var{yes} is zero, and
1003 enabled otherwise.
1004 @end deftypefun
1005
1006 @deftypefun int gpgme_get_armor (@w{GpgmeCtx @var{ctx}})
1007 The function @code{gpgme_get_armor} returns 1 if the output is
1008 @acronym{ASCII} armored, and @code{0} if it is not, or if @var{ctx} is
1009 not a valid pointer.
1010 @end deftypefun
1011
1012
1013 @node Text Mode
1014 @subsection Text Mode
1015 @cindex context, text mode
1016 @cindex text mode
1017 @cindex canonical text mode
1018
1019 @deftypefun void gpgme_set_textmode (@w{GpgmeCtx @var{ctx}}, @w{int @var{yes}})
1020 The function @code{gpgme_set_textmode} specifies if canonical text mode
1021 should be used.  By default, text mode is not used.
1022
1023 Text mode is for example used for the RFC2015 signatures; note that
1024 the updated RFC 3156 mandates that the mail user agent does some
1025 preparations so that text mode is not needed anymore.
1026
1027 Canonical text mode is disabled if @var{yes} is zero, and enabled
1028 otherwise.
1029 @end deftypefun
1030
1031 @deftypefun int gpgme_get_textmode (@w{GpgmeCtx @var{ctx}})
1032 The function @code{gpgme_get_textmode} returns 1 if canonical text
1033 mode is enabled, and @code{0} if it is not, or if @var{ctx} is not a
1034 valid pointer.
1035 @end deftypefun
1036
1037
1038 @node Key Listing Mode
1039 @subsection Key Listing Mode
1040 @cindex key listing mode
1041 @cindex key listing, mode of
1042
1043 @deftypefun void gpgme_set_keylist_mode (@w{GpgmeCtx @var{ctx}}, @w{int @var{mode}})
1044 The function @code{gpgme_set_keylist_mode} changes the default
1045 behaviour of the key listing functions.  The value in @var{mode} is a
1046 bitwise-or combination of one or multiple of the following bit values:
1047
1048 @table @code
1049 @item GPGME_KEYLIST_MODE_LOCAL
1050 The @code{GPGME_KEYLIST_MODE_LOCAL} symbol specifies that the local
1051 keyring should be searched for keys in the keylisting operation.  This
1052 is the default.
1053
1054 @item GPGME_KEYLIST_MODE_EXTERN
1055 The @code{GPGME_KEYLIST_MODE_EXTERN} symbol specifies that an external
1056 source should be should be searched for keys in the keylisting
1057 operation.  The type of external source is dependant on the crypto
1058 engine used.  For example, it can be a remote keyserver or LDAP
1059 certificate server.
1060 @end table
1061
1062 At least one of @code{GPGME_KEYLIST_MODE_LOCAL} and
1063 @code{GPGME_KEYLIST_MODE_EXTERN} must be specified.  For future binary
1064 compatibility, you should get the current mode with
1065 @code{gpgme_get_keylist_mode} and modify it by setting or clearing the
1066 appropriate bits, and then using that calulcated value in the
1067 @code{gpgme_set_keylisting_mode} operation.  This will leave all other
1068 bits in the mode value intact (in particular those that are not used
1069 in the current version of the library).
1070
1071 The function returns @code{GPGME_No_Error} if the mode could be set
1072 correctly, and @code{GPGME_Invalid_Value} if @var{ctx} is not a valid
1073 pointer or @var{mode} is not a valid mode.
1074 @end deftypefun
1075
1076
1077 @deftypefun int gpgme_get_keylist_mode (@w{GpgmeCtx @var{ctx}})
1078 The function @code{gpgme_get_keylist_mode} returns the current key
1079 listing mode of the context @var{ctx}.  This value can then be
1080 modified and used in a subsequent @code{gpgme_set_keylist_mode}
1081 operation to only affect the desired bits (and leave all others
1082 intact).
1083
1084 The function returns 0 if @var{ctx} is not a valid pointer, and the
1085 current mode otherwise.  Note that 0 is not a valid mode value.
1086 @end deftypefun
1087
1088
1089 @node Passphrase Callback
1090 @subsection Passphrase Callback
1091 @cindex callback, passphrase
1092 @cindex passphrase callback
1093
1094 @deftp {Data type} {const char *(*GpgmePassphraseCb)(void *@var{hook}, const char *@var{desc}, void **@var{r_hd})}
1095 @tindex GpgmePassphraseCb
1096 The @code{GpgmePassphraseCb} type is the type of functions usable as
1097 passphrase callback function.
1098
1099 The string @var{desc} contains a test usable to be displayed to the
1100 user of the application.  The function should return a passphrase for
1101 the context when invoked with @var{desc} not being @code{NULL}.
1102
1103 The user may store information about the resources associated with the
1104 returned passphrase in @var{*r_hd}.  When the passphrase is no longer
1105 needed by @acronym{GPGME}, the passphrase callback function will be
1106 called with @var{desc} being @var{NULL}, and @var{r_hd} being the same
1107 as at the first invocation.
1108 @end deftp
1109
1110 @deftypefun void gpgme_set_passphrase_cb (@w{GpgmeCtx @var{ctx}}, @w{GpgmePassphraseCb @var{passfunc}}, @w{void *@var{hook_value}})
1111 The function @code{gpgme_set_passphrase_cb} sets the function that is
1112 used when a passphrase needs to be provided by the user to
1113 @var{passfunc}.  The function @var{passfunc} needs to implemented by
1114 the user, and whenever it is called, it is called with its first
1115 argument being @var{hook_value}.  By default, no passphrase callback
1116 function is set.
1117
1118 Not all crypto engines require this callback to retrieve the
1119 passphrase.  It is better if the engine retrieves the passphrase from
1120 a trusted agent (a daemon process), rather than having each user to
1121 implement their own passphrase query.
1122
1123 The user can disable the use of a passphrase callback function by
1124 calling @code{gpgme_set_passphrase_cb} with @var{passfunc} being
1125 @code{NULL}.
1126 @end deftypefun
1127
1128
1129 @node Progress Meter Callback
1130 @subsection Progress Meter Callback
1131 @cindex callback, progress meter
1132 @cindex progress meter callback
1133
1134 @deftp {Data type} {const char *(*GpgmeProgressCb)(void *@var{hook}, const char *@var{what}, int @var{type}, int @var{current}, int @var{total})}
1135 @tindex GpgmeProgressCb
1136 The @code{GpgmeProgressCb} type is the type of functions usable as
1137 progress callback function.
1138
1139 The arguments are specific to the crypto engine.  More information
1140 about the progress information returned from the GnuPG engine can be
1141 found in the GnuPG source code in the file @file{doc/DETAILS} in the
1142 section PROGRESS.
1143 @end deftp
1144
1145 @deftypefun void gpgme_set_progress_cb (@w{GpgmeCtx @var{ctx}}, @w{GpgmeProgressCb @var{progfunc}}, @w{void *@var{hook_value}})
1146 The function @code{gpgme_set_progress_cb} sets the function that is
1147 used when progress information about a cryptographic operation is
1148 available.  The function @var{progfunc} needs to implemented by the
1149 user, and whenever it is called, it is called with its first argument
1150 being @var{hook_value}.  By default, no progress callback function
1151 is set.
1152
1153 Setting a callback function allows an interactive program to display
1154 progress information about a long operation to the user.
1155
1156 The user can disable the use of a progress callback function by
1157 calling @code{gpgme_set_progress_cb} with @var{progfunc} being
1158 @code{NULL}.
1159 @end deftypefun
1160
1161
1162 @node Key Management
1163 @section Key Management
1164 @cindex key management
1165
1166 Some of the cryptographic operations require that recipients or
1167 signers are specified.  This is always done by specifying the
1168 respective keys that should be used for the operation.  The following
1169 section describes how such keys can be selected and manipulated.
1170
1171 @deftp {Data type} GpgmeKey
1172 The @code{GpgmeKey} type is a handle for a public or secret key, and
1173 is used to select the key for operations involving it.
1174
1175 A key can contain several user IDs and sub keys.
1176 @end deftp
1177
1178 @menu
1179 * Listing Keys::                  Browsing the list of available keys.
1180 * Information About Keys::        Requesting detailed information about keys.
1181 * Manipulating Keys::             Operations on keys.
1182 * Generating Keys::               Creating new key pairs.
1183 * Exporting Keys::                Retrieving key data from the key ring.
1184 * Importing Keys::                Adding keys to the key ring.
1185 * Deleting Keys::                 Removing keys from the key ring.
1186 @end menu
1187
1188
1189 @node Listing Keys
1190 @subsection Listing Keys
1191 @cindex listing keys
1192 @cindex key listing
1193 @cindex key listing, start
1194 @cindex key ring, list
1195 @cindex key ring, search
1196
1197 @deftypefun GpgmeError gpgme_op_keylist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}})
1198 The function @code{gpgme_op_keylist_start} initiates a key listing
1199 operation inside the context @var{ctx}.  It sets everything up so that
1200 subsequent invocations of @code{gpgme_op_keylist_next} return the keys
1201 in the list.
1202
1203 If @var{pattern} is @code{NULL}, all available keys are returned.
1204 Otherwise, @var{pattern} contains an engine specific expression that
1205 is used to limit the list to all keys matching the pattern.
1206
1207 If @var{secret_only} is not @code{0}, the list is restricted to secret
1208 keys only.
1209
1210 The context will be busy until either all keys are received (and
1211 @code{gpgme_op_keylist_next} returns @code{GPGME_EOF}), or
1212 @code{gpgme_op_keylist_end} is called to finish the operation.
1213
1214 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
1215 valid pointer, and passes through any errors that are reported by the
1216 crypto engine support routines.
1217 @end deftypefun
1218
1219 @deftypefun GpgmeError gpgme_op_keylist_next (@w{GpgmeCtx @var{ctx}}, @w{GpgmeKey *@var{r_key}})
1220 The function @code{gpgme_op_keylist_next} returns the next key in the
1221 list created by a previous @code{gpgme_op_keylist_start} operation in
1222 the context @var{ctx}.  The key will have one reference for the user.
1223 @xref{Manipulating Keys}.
1224
1225 This is the only way to get at @code{GpgmeKey} objects in
1226 @acronym{GPGME}.
1227
1228 If the last key in the list has already been returned,
1229 @code{gpgme_op_keylist_next} returns @code{GPGME_EOF}.
1230
1231 The function returns @code{GPGME_Invalid_Value} if @var{ctx} or
1232 @var{r_key} is not a valid pointer, @code{GPGME_No_Request} if there
1233 is no pending operation, @code{GPGME_Out_Of_Core} if there is not
1234 enough memory for the operation.
1235 @end deftypefun
1236
1237 @deftypefun GpgmeError gpgme_op_keylist_end (@w{GpgmeCtx @var{ctx}})
1238 The function @code{gpgme_op_keylist_next} ends a pending key list
1239 operation in the context @var{ctx}.
1240
1241 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
1242 valid pointer, @code{GPGME_No_Request} if there is no pending
1243 operation, @code{GPGME_Out_Of_Core} if at some time during the
1244 operation there was not enough memory available.
1245 @end deftypefun
1246
1247
1248 @node Information About Keys
1249 @subsection Information About Keys
1250 @cindex key, information about
1251 @cindex key, attributes
1252 @cindex attributes, of a key
1253
1254 @deftypefun {char *} gpgme_key_get_as_xml (@w{GpgmeKey @var{key}})
1255 The function @code{gpgme_key_get_as_xml} returns a string in
1256 @acronym{XML} format describing the key @var{key}.  The user has to
1257 release the string with @code{free}.
1258
1259 The function returns @code{NULL} if @var{key} is not a valid pointer,
1260 or there is not enough memory available.
1261 @end deftypefun
1262
1263 @deftp {Data type} GpgmeAttr
1264 The @code{GpgmeAttr} type is used to specify a key or trust item
1265 attribute.  The following attributes are defined:
1266
1267 @table @code
1268 @item GPGME_ATTR_KEYID
1269 This is the key ID of a sub key.  It is representable as a string.
1270
1271 For trust items, the trust item refers to the key with this ID.
1272
1273 @item GPGME_ATTR_FPR
1274 This is the fingerprint of a sub key.  It is representable as a
1275 string.
1276
1277 @item GPGME_ATTR_ALGO
1278 This is the crypto algorithm for which the sub key can be used.  It
1279 is representable as a string and as a number.  The numbers correspond
1280 to the @code{enum gcry_pk_algos} values in the gcrypt library.
1281
1282 @item GPGME_ATTR_LEN
1283 This is the key length of a sub key.  It is representable as a
1284 number.
1285
1286 @item GPGME_ATTR_CREATED
1287 This is the timestamp at creation time of a sub key.  It is
1288 representable as a number.
1289
1290 @item GPGME_ATTR_EXPIRE
1291 XXX FIXME
1292
1293 @item GPGME_ATTR_OTRUST
1294 XXX FIXME  (also for trust items)
1295
1296 @item GPGME_ATTR_USERID
1297 This is a user ID.  There can be more than one user IDs in a
1298 @var{GpgmeKey} object.  The first one (with index 0) is the primary
1299 user ID.  The user ID is representable as a number.
1300
1301 For trust items, this is the user ID associated with this trust item.
1302
1303 @item GPGME_ATTR_NAME
1304 This is the name belonging to a user ID.  It is representable as a string.
1305
1306 @item GPGME_ATTR_EMAIL
1307 This is the email address belonging to a user ID.  It is representable
1308 as a string.
1309
1310 @item GPGME_ATTR_COMMENT
1311 This is the comment belonging to a user ID.  It is representable as a
1312 string.
1313
1314 @item GPGME_ATTR_VALIDITY
1315 This is the validity belonging to a user ID.  It is representable as a
1316 string and as a number.  See below for a list of available validities.
1317
1318 For trust items, this is the validity that is associated with this
1319 trust item.
1320
1321 @item GPGME_ATTR_UID_REVOKED
1322 This specifies if a user ID is revoked.  It is representable as a
1323 number, and is @code{1} if the user ID is revoked, and @code{0}
1324 otherwise.
1325
1326 @item GPGME_ATTR_UID_INVALID
1327 This specifies if a user ID is invalid.  It is representable as a
1328 number, and is @code{1} if the user ID is invalid, and @code{0}
1329 otherwise.
1330
1331 @item GPGME_ATTR_LEVEL
1332 This is the trust level of a trust item.
1333
1334 @item GPGME_ATTR_TYPE
1335 This is the type of a trust item.
1336
1337 @item GPGME_ATTR_IS_SECRET
1338 This specifies if the key is a secret key.  It is representable as a
1339 string or a number.  If the key is a secret key, the representation is
1340 ``1'' or @code{1}, otherwise it is @code{NULL} or @code{0}.
1341
1342 @item GPGME_ATTR_KEY_REVOKED
1343 This specifies if a sub key is revoked.  It is representable as a
1344 number, and is @code{1} if the key is revoked, and @code{0} otherwise.
1345
1346 @item GPGME_ATTR_KEY_INVALID
1347 This specifies if a sub key is invalid.  It is representable as a
1348 number, and is @code{1} if the key is invalid, and @code{0} otherwise.
1349
1350 @item GPGME_ATTR_KEY_EXPIRED
1351 This specifies if a sub key is expired.  It is representable as a
1352 number, and is @code{1} if the key is expired, and @code{0} otherwise.
1353
1354 @item GPGME_ATTR_KEY_DISABLED
1355 This specifies if a sub key is disabled.  It is representable as a
1356 number, and is @code{1} if the key is disabled, and @code{0} otherwise.
1357
1358 @item GPGME_ATTR_KEY_CAPS
1359 This is a description of the capabilities of a sub key.  It is
1360 representable as a string.  The string contains the letter ``e'' if
1361 the key can be used for encryption, ``s'' if the key can be used for
1362 signatures, and ``c'' if the key can be used for certifications.
1363
1364 @item GPGME_ATTR_CAN_ENCRYPT
1365 This specifies if a sub key can be used for encryption.  It is
1366 representable as a number, and is @code{1} if the sub key can be used
1367 for encryption, and @code{0} otherwise.
1368
1369 @item GPGME_ATTR_CAN_SIGN
1370 This specifies if a sub key can be used for signatures.  It is
1371 representable as a number, and is @code{1} if the sub key can be used
1372 for signatures, and @code{0} otherwise.
1373
1374 @item GPGME_ATTR_CAN_CERTIFY
1375 This specifies if a sub key can be used for certifications.  It is
1376 representable as a number, and is @code{1} if the sub key can be used
1377 for certifications, and @code{0} otherwise.
1378 @end table
1379 @end deftp
1380
1381 @deftp {Data type} GpgmeValidity
1382 The @code{GpgmeValidity} type is used to specify the validity of a user ID
1383 in a key.  The following validities are defined:
1384
1385 @table @code
1386 @item GPGME_VALIDITY_UNKNOWN
1387 The user ID is of unknown validity.  The string representation of this
1388 validity is ``?''.
1389
1390 @item GPGME_VALIDITY_UNDEFINED
1391 The validity of the user ID is undefined.  The string representation of this
1392 validity is ``q''.
1393
1394 @item GPGME_VALIDITY_NEVER
1395 The user ID is never valid.  The string representation of this
1396 validity is ``n''.
1397
1398 @item GPGME_VALIDITY_MARGINAL
1399 The user ID is marginally valid.  The string representation of this
1400 validity is ``m''.
1401
1402 @item GPGME_VALIDITY_FULL
1403 The user ID is fully valid.  The string representation of this
1404 validity is ``f''.
1405
1406 @item GPGME_VALIDITY_ULTIMATE
1407 The user ID is ultimately valid.  The string representation of this
1408 validity is ``u''.
1409 @end table
1410 @end deftp
1411
1412 @deftypefun {const char *} gpgme_key_get_string_attr (@w{GpgmeKey @var{key}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
1413 The function @code{gpgme_key_get_string_attr} returns the value of the
1414 string-representable attribute @var{what} of key @var{key}.  If the
1415 attribute occurs more than once in the key, the index is specified by
1416 @var{idx}.  This applies to attributes of sub keys and user IDs.  The
1417 argument @var{reserved} is reserved for later use and should be
1418 @code{NULL}.
1419
1420 The string returned is only valid as long as the key is valid.
1421
1422 The function returns @code{0} if an attribute can't be returned as a
1423 string, @var{key} is not a valid pointer, @var{idx} out of range,
1424 or @var{reserved} not @code{NULL}.
1425 @end deftypefun
1426
1427 @deftypefun {unsigned long} gpgme_key_get_ulong_attr (@w{GpgmeKey @var{key}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
1428 The function @code{gpgme_key_get_ulong_attr} returns the value of the
1429 number-representable attribute @var{what} of key @var{key}.  If the
1430 attribute occurs more than once in the key, the index is specified by
1431 @var{idx}.  This applies to attributes of sub keys and user IDs.  The
1432 argument @var{reserved} is reserved for later use and should be
1433 @code{NULL}.
1434
1435 The function returns @code{0} if the attribute can't be returned as a
1436 number, @var{key} is not a valid pointer, @var{idx} out of range,
1437 or @var{reserved} not @code{NULL}.
1438 @end deftypefun
1439
1440
1441 @node Manipulating Keys
1442 @subsection Manipulating Keys
1443 @cindex key, manipulation
1444
1445 @deftypefun void gpgme_key_ref (@w{GpgmeKey @var{key}})
1446 The function @code{gpgme_key_ref} acquires an additional reference for
1447 the key @var{key}.
1448 @end deftypefun
1449
1450 @deftypefun void gpgme_key_unref (@w{GpgmeKey @var{key}})
1451 @deftypefunx void gpgme_key_release (@w{GpgmeKey @var{key}})
1452 The function @code{gpgme_key_ref} releases a reference for the key
1453 @var{key}.  If this was the last reference, the key will be destroyed
1454 and all resources associated to it will be released.
1455
1456 The function @code{gpgme_key_release} is an alias for
1457 @code{gpgme_key_unref}.
1458 @end deftypefun
1459
1460
1461 @node Generating Keys
1462 @subsection Generating Keys
1463 @cindex key, creation
1464 @cindex key ring, add
1465
1466 @deftypefun GpgmeError gpgme_op_genkey (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{pubkey}}, @w{GpgmeData @var{seckey}})
1467 The function @code{gpgme_op_genkey} generates a new key pair in the
1468 context @var{ctx} and puts it into the standard key ring if both
1469 @var{pubkey} and @var{seckey} are @code{NULL}.  In this case the
1470 function returns immediately after starting the operation, and does
1471 not wait for it to complete.  @var{pubkey} and @var{seckey} are
1472 reserved for later use and should be @code{NULL}.  (The function
1473 should return the public key in the data buffer @var{pubkey} and the
1474 secret key in the data buffer @var{seckey}, but this is not
1475 implemented yet).
1476
1477 The argument @var{parms} specifies parameters for the key in an XML
1478 string.  The details about the format of @var{parms} are specific to
1479 the crypto engine used by @var{ctx}.  Here is an example for GnuPG as
1480 the crypto engine:
1481
1482 @example
1483 <literal>
1484 <![CDATA[
1485 <GnupgKeyParms format="internal">
1486 Key-Type: DSA
1487 Key-Length: 1024
1488 Subkey-Type: ELG-E
1489 Subkey-Length: 1024
1490 Name-Real: Joe Tester
1491 Name-Comment: with stupid passphrase
1492 Name-Email: joe@@foo.bar
1493 Expire-Date: 0
1494 Passphrase: abc
1495 </GnupgKeyParms>
1496 ]]>
1497 </literal>
1498 @end example
1499
1500 Strings should be given in UTF-8 encoding.  The only format supported
1501 for now is ``internal''.  The content of the @code{GnupgKeyParms}
1502 container is passed verbatim to GnuPG.  Control statements are not
1503 allowed.
1504
1505 The function returns @code{GPGME_No_Error} if the operation could be
1506 started successfully, @code{GPGME_Invalid_Value} if @var{parms} is not
1507 a valid XML string, @code{GPGME_Not_Supported} if @var{pubkey} or
1508 @var{seckey} is not @code{NULL}, and @code{GPGME_General_Error} if no
1509 key was created by the backend.
1510 @end deftypefun
1511
1512 @deftypefun GpgmeError gpgme_op_genkey_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{pubkey}}, @w{GpgmeData @var{seckey}})
1513 The function @code{gpgme_op_genkey_start} initiates a
1514 @code{gpgme_op_genkey} operation.  It can be completed by calling
1515 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
1516
1517 The function returns @code{GPGME_No_Error} if the operation could be
1518 started successfully, @code{GPGME_Invalid_Value} if @var{parms} is not
1519 a valid XML string, and @code{GPGME_Not_Supported} if @var{pubkey} or
1520 @var{seckey} is not @code{NULL}.
1521 @end deftypefun
1522
1523
1524 @node Exporting Keys
1525 @subsection Exporting Keys
1526 @cindex key, export
1527 @cindex key ring, export from
1528
1529 @deftypefun GpgmeError gpgme_op_export (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{recipients}}, @w{GpgmeData @var{keydata}})
1530 The function @code{gpgme_op_export} extracts the public keys of the
1531 user IDs in @var{recipients} and returns them in the data buffer
1532 @var{keydata}.  The type of the public keys returned is determined by
1533 the @acronym{ASCII} armor attribute set for the context @var{ctx}.
1534
1535 The function returns @code{GPGME_No_Error} if the operation completed
1536 successfully, @code{GPGME_Invalid_Value} if @var{recipients} is
1537 @code{NULL} or @var{keydata} is not a valid empty data buffer, and
1538 passes through any errors that are reported by the crypto engine
1539 support routines.
1540 @end deftypefun
1541
1542 @deftypefun GpgmeError gpgme_op_export_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{recipients}}, @w{GpgmeData @var{keydata}})
1543 The function @code{gpgme_op_export_start} initiates a
1544 @code{gpgme_op_export} operation.  It can be completed by calling
1545 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
1546
1547 The function returns @code{GPGME_No_Error} if the operation could be
1548 started successfully, and @code{GPGME_Invalid_Value} if
1549 @var{recipients} is @code{NULL} or @var{keydata} is not a valid empty
1550 data buffer.
1551 @end deftypefun
1552
1553
1554 @node Importing Keys
1555 @subsection Importing Keys
1556 @cindex key, import
1557 @cindex key ring, import to
1558
1559 @deftypefun GpgmeError gpgme_op_import (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}})
1560 The function @code{gpgme_op_import} adds the keys in the data buffer
1561 @var{keydata} to the key ring of the crypto engine used by @var{ctx}.
1562 The format of @var{keydata} can be @var{ASCII} armored, for example,
1563 but the details are specific to the crypto engine.
1564
1565 More information about the import is available with
1566 @code{gpgme_get_op_info}.  @xref{Detailed Results}.
1567
1568 The function returns @code{GPGME_No_Error} if the import was completed
1569 successfully, @code{GPGME_Invalid_Value} if @var{keydata} if @var{ctx}
1570 or @var{keydata} is not a valid pointer, and @code{GPGME_No_Data} if
1571 @var{keydata} is an empty data buffer.
1572 @end deftypefun
1573
1574 @deftypefun GpgmeError gpgme_op_import_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}})
1575 The function @code{gpgme_op_import_start} initiates a
1576 @code{gpgme_op_import} operation.  It can be completed by calling
1577 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
1578
1579 The function returns @code{GPGME_No_Error} if the import could be
1580 started successfully, @code{GPGME_Invalid_Value} if @var{keydata} if
1581 @var{ctx} or @var{keydata} is not a valid pointer, and
1582 @code{GPGME_No_Data} if @var{keydata} is an empty data buffer.
1583 @end deftypefun
1584
1585
1586 @node Deleting Keys
1587 @subsection Deleting Keys
1588 @cindex key, delete
1589 @cindex key ring, delete from
1590
1591 @deftypefun GpgmeError gpgme_op_delete (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}, @w{int @var{allow_secret}})
1592 The function @code{gpgme_op_delete} deletes the key @var{key} from the
1593 key ring of the crypto engine used by @var{ctx}.  If
1594 @var{allow_secret} is @code{0}, only public keys are deleted,
1595 otherwise secret keys are deleted as well.
1596
1597 The function returns @code{GPGME_No_Error} if the key was deleted
1598 successfully, @code{GPGME_Invalid_Value} if @var{ctx} or @var{key} is
1599 not a valid pointer, @code{GPGME_Invalid_Key} if @var{key} could not
1600 be found in the keyring, and @code{GPGME_Conflict} if the secret key
1601 for @var{key} is available, but @var{allow_secret} is zero.
1602 @end deftypefun
1603
1604 @deftypefun GpgmeError gpgme_op_delete_start (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}, @w{int @var{allow_secret}})
1605 The function @code{gpgme_op_delete_start} initiates a
1606 @code{gpgme_op_delete} operation.  It can be completed by calling
1607 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
1608
1609 The function returns @code{GPGME_No_Error} if the operation was
1610 started successfully, and @code{GPGME_Invalid_Value} if @var{ctx} or
1611 @var{key} is not a valid pointer.
1612 @end deftypefun
1613
1614
1615 @node Trust Item Management
1616 @section Trust Item Management
1617 @cindex trust item
1618
1619 @strong{Caution:} The trust items interface is experimental.
1620
1621 @deftp {Data type} GpgmeTrustItem
1622 The @code{GpgmeTrustItem} type is a handle for a trust item.
1623 @end deftp
1624
1625 @menu
1626 * Listing Trust Items::           Browsing the list of available trust items.
1627 * Information About Trust Items:: Requesting detailed information about trust items.
1628 * Manipulating Trust Items::      Operations on trust items.
1629 @end menu
1630
1631
1632 @node Listing Trust Items
1633 @subsection Listing Trust Items
1634 @cindex trust item list
1635
1636 @deftypefun GpgmeError gpgme_op_trustlist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{max_level}})
1637 The function @code{gpgme_op_trustlist_start} initiates a trust item
1638 listing operation inside the context @var{ctx}.  It sets everything up
1639 so that subsequent invocations of @code{gpgme_op_trustlist_next} return
1640 the trust items in the list.
1641
1642 The string @var{pattern} contains an engine specific expression that
1643 is used to limit the list to all trust items matching the pattern.  It
1644 can not be the empty string.
1645
1646 The argument @var{max_level} is currently ignored.
1647
1648 The context will be busy until either all trust items are received
1649 (and @code{gpgme_op_trustlist_next} returns @code{GPGME_EOF}), or
1650 @code{gpgme_op_trustlist_end} is called to finish the operation.
1651
1652 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
1653 valid pointer, and passes through any errors that are reported by the
1654 crypto engine support routines.
1655 @end deftypefun
1656
1657 @deftypefun GpgmeError gpgme_op_trustlist_next (@w{GpgmeCtx @var{ctx}}, @w{GpgmeTrustItem *@var{r_item}})
1658 The function @code{gpgme_op_trustlist_next} returns the next trust
1659 item in the list created by a previous @code{gpgme_op_trustlist_start}
1660 operation in the context @var{ctx}.  The trust item can be destroyed
1661 with @code{gpgme_trust_item_release}.  @xref{Manipulating Trust Items}.
1662
1663 This is the only way to get at @code{GpgmeTrustItem} objects in
1664 @acronym{GPGME}.
1665
1666 If the last trust item in the list has already been returned,
1667 @code{gpgme_op_trustlist_next} returns @code{GPGME_EOF}.
1668
1669 The function returns @code{GPGME_Invalid_Value} if @var{ctx} or
1670 @var{r_item} is not a valid pointer, @code{GPGME_No_Request} if there
1671 is no pending operation, @code{GPGME_Out_Of_Core} if there is not
1672 enough memory for the operation.
1673 @end deftypefun
1674
1675 @deftypefun GpgmeError gpgme_op_trustlist_end (@w{GpgmeCtx @var{ctx}})
1676 The function @code{gpgme_op_trustlist_next} ends a pending key list
1677 operation in the context @var{ctx}.
1678
1679 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
1680 valid pointer, @code{GPGME_No_Request} if there is no pending
1681 operation, @code{GPGME_Out_Of_Core} if at some time during the
1682 operation there was not enough memory available.
1683 @end deftypefun
1684
1685
1686 @node Information About Trust Items
1687 @subsection Information About Trust Items
1688 @cindex trust item, information about
1689 @cindex trust item, attributes
1690 @cindex attributes, of a trust item
1691
1692 Trust items have attributes which can be queried using the interfaces
1693 below.  The attribute identifiers are shared with those for key
1694 attributes.  @xref{Information About Keys}.
1695
1696 @deftypefun {const char *} gpgme_trust_item_get_string_attr (@w{GpgmeTrustItem @var{item}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
1697 The function @code{gpgme_trust_item_get_string_attr} returns the value
1698 of the string-representable attribute @var{what} of trust item
1699 @var{item}.  If the attribute occurs more than once in the trust
1700 items, the index is specified by @var{idx}.  However, currently no
1701 such attributes exists, so @var{idx} should be @code{0}.  The argument
1702 @var{reserved} is reserved for later use and should be @code{NULL}.
1703
1704 The string returned is only valid as long as the key is valid.
1705
1706 The function returns @code{0} if an attribute can't be returned as a
1707 string, @var{key} is not a valid pointer, @var{idx} out of range,
1708 or @var{reserved} not @code{NULL}.
1709 @end deftypefun
1710
1711 @deftypefun int gpgme_trust_item_get_int_attr (@w{GpgmeTrustItem @var{item}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
1712 The function @code{gpgme_trust_item_get_int_attr} returns the value of
1713 the number-representable attribute @var{what} of trust item
1714 @var{item}.  If the attribute occurs more than once in the trust item,
1715 the index is specified by @var{idx}.  However, currently no such
1716 attribute exists, so @var{idx} should be @code{0}.  The argument
1717 @var{reserved} is reserved for later use and should be @code{NULL}.
1718
1719 The function returns @code{0} if the attribute can't be returned as a
1720 number, @var{key} is not a valid pointer, @var{idx} out of range,
1721 or @var{reserved} not @code{NULL}.
1722 @end deftypefun
1723
1724
1725 @node Manipulating Trust Items
1726 @subsection Manipulating Trust Items
1727 @cindex trust item, manipulation
1728
1729 @deftypefun void gpgme_trust_item_release (@w{GpgmeTrustItem @var{item}})
1730 The function @code{gpgme_trust_item_release} destroys a
1731 @code{GpgmeTrustItem} object and releases all associated resources.
1732 @end deftypefun
1733
1734 @node Crypto Operations
1735 @section Crypto Operations
1736 @cindex cryptographic operation
1737
1738 @menu
1739 * Decrypt::                       Decrypting a ciphertext.
1740 * Verify::                        Verifying a signature.
1741 * Decrypt and Verify::            Decrypting a signed ciphertext.
1742 * Sign::                          Creating a signature.
1743 * Encrypt::                       Encrypting a plaintext.
1744 * Detailed Results::              How to obtain more info about the operation.
1745 @end menu
1746
1747
1748 @node Decrypt
1749 @subsection Decrypt
1750 @cindex decryption
1751 @cindex cryptographic operation, decryption
1752
1753 @deftypefun GpgmeError gpgme_op_decrypt (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
1754 The function @code{gpgme_op_decrypt} decrypts the ciphertext in the
1755 data object @var{cipher} and stores it into the data object
1756 @var{plain}.
1757
1758 The function returns @code{GPGME_No_Error} if the ciphertext could be
1759 decrypted successfully, @code{GPGME_Invalid_Value} if @var{ctx},
1760 @var{cipher} or @var{plain} is not a valid pointer,
1761 @code{GPGME_No_Data} if @var{cipher} does not contain any data to
1762 decrypt, @code{GPGME_Decryption_Failed} if @var{cipher} is not a valid
1763 cipher text, @code{GPGME_No_Passphrase} if the passphrase for the
1764 secret key could not be retrieved, and passes through any errors that
1765 are reported by the crypto engine support routines.
1766 @end deftypefun
1767
1768 @deftypefun GpgmeError gpgme_op_decrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
1769 The function @code{gpgme_op_decrypt_start} initiates a
1770 @code{gpgme_op_decrypt} operation.  It can be completed by calling
1771 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
1772
1773 The function returns @code{GPGME_No_Error} if the operation could be
1774 started successfully, and @code{GPGME_Invalid_Value} if @var{cipher}
1775 or @var{plain} is not a valid pointer.
1776 @end deftypefun
1777
1778
1779 @node Verify
1780 @subsection Verify
1781 @cindex verification
1782 @cindex signature, verification
1783 @cindex cryptographic operation, verification
1784 @cindex cryptographic operation, signature check
1785 @cindex signature, status
1786
1787 @deftp {Data type} {enum GpgmeSigStat}
1788 @tindex GpgmeSigStat
1789 The @code{GpgmeSigStat} type holds the result of a signature check, or
1790 the combined result of all signatures.  The following results are
1791 possible:
1792
1793 @table @code
1794 @item GPGME_SIG_STAT_NONE
1795 This status should not occur in normal operation.
1796
1797 @item GPGME_SIG_STAT_GOOD
1798 This status indicates that the signature is valid.  For the combined
1799 result this status means that all signatures are valid.
1800
1801 @item GPGME_SIG_STAT_BAD
1802 This status indicates that the signature is invalid.  For the combined
1803 result this status means that all signatures are invalid.
1804
1805 @item GPGME_SIG_STAT_NOKEY
1806 This status indicates that the signature could not be verified due to
1807 a missing key.  For the combined result this status means that all
1808 signatures could not be checked due to missing keys.
1809
1810 @item GPGME_SIG_STAT_NOSIG
1811 This status indicates that the signature data provided was not a real
1812 signature.
1813
1814 @item GPGME_SIG_STAT_ERROR
1815 This status indicates that there was some other error which prevented
1816 the signature verification.
1817
1818 @item GPGME_SIG_STAT_DIFF
1819 For the combined result this status means that at least two signatures
1820 have a different status.  You can get each key's status with
1821 @code{gpgme_get_sig_status}.
1822 @end table
1823 @end deftp
1824
1825 @deftypefun GpgmeError gpgme_op_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{sig}}, @w{GpgmeData @var{plain}}, @w{GpgmeSigStat *@var{r_stat}})
1826 The function @code{gpgme_op_verify} verifies that the detached
1827 signature in the data object @var{sig} is a valid signature for the
1828 plaintext in the data object @var{plain}.
1829
1830 The combined status of all signatures is returned in @var{r_stat}.
1831 The results of the individual signature verifications can be retrieved
1832 with @code{gpgme_get_sig_status} and @code{gpgme_get_sig_key}.
1833
1834 The function returns @code{GPGME_No_Error} if the operation could be
1835 completed successfully, @code{GPGME_Invalid_Value} if @var{ctx},
1836 @var{sig}, @var{plain} or @var{r_stat} is not a valid pointer,
1837 @code{GPGME_No_Data} if @var{sig} or @var{plain} does not contain any
1838 data to verify, and passes through any errors that are reported by the
1839 crypto engine support routines.
1840 @end deftypefun
1841
1842 @deftypefun GpgmeError gpgme_op_verify_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{sig}}, @w{GpgmeData @var{plain}})
1843 The function @code{gpgme_op_verify_start} initiates a
1844 @code{gpgme_op_verify} operation.  It can be completed by calling
1845 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
1846
1847 The function returns @code{GPGME_No_Error} if the operation could be
1848 started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
1849 @var{sig}, @var{plain} or @var{r_stat} is not a valid pointer, and
1850 @code{GPGME_No_Data} if @var{sig} or @var{plain} does not contain any
1851 data to verify.
1852 @end deftypefun
1853
1854 @deftypefun {const char *} gpgme_get_sig_status (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeSigStat *@var{r_stat}}, @w{time_t *@var{r_created}})
1855 The function @code{gpgme_get_sig_status} receives information about a
1856 signature after the @code{gpgme_op_verify} or
1857 @code{gpgme_op_verify_decrypt} operation.  A single detached signature
1858 can contain signatures by more than one key.  The @var{idx} specifies
1859 which signature's information should be retrieved, starting from
1860 @var{0}.
1861
1862 The status of the signature will be returned in @var{r_stat} if it is
1863 not @code{NULL}.  The creation time stamp of the signature will be
1864 returned in @var{r_created} if it is not @var{NULL}.
1865
1866 The function returns a statically allocated string that contains the
1867 fingerprint of the key which signed the plaintext, or @code{NULL} if
1868 @var{ctx} is not a valid pointer, the operation is still pending, or
1869 no verification could be performed.
1870 @end deftypefun
1871
1872 @deftypefun {const char *} gpgme_get_sig_key (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeSigKey *@var{r_stat}})
1873 The function @code{gpgme_get_sig_status} receives a @code{GpgmeKey}
1874 object for the key which was used to verify the signature after the
1875 @code{gpgme_op_verify} or @code{gpgme_op_verify_decrypt} operation.  A
1876 single detached signature can contain signatures by more than one key.
1877 The @var{idx} specifies which signature's information should be
1878 retrieved, starting from @var{0}.  The key will have on reference for
1879 the user.
1880
1881 The function is a convenient way to retrieve the keys belonging to the
1882 fingerprints returned by @code{gpgme_get_sig_status}.
1883
1884 The function returns @code{GPGME_No_Error} if the key could be
1885 returned, @code{GPGME_Invalid_Value} if @var{r_key} is not a valid
1886 pointer, @code{GPGME_Invalid_Key} if the fingerprint is not valid,
1887 @code{GPGME_EOF} if @var{idx} is too large, or some other error value
1888 if a problem occurred requesting the key.
1889 @end deftypefun
1890
1891 @deftypefun {char *} gpgme_get_notation (@w{GpgmeCtx @var{ctx}})
1892 The function @code{gpgme_get_notation} can be used to retrieve
1893 notation data from the last signature check in the context @var{ctx}.
1894
1895 If there is notation data available from the last signature check,
1896 this function may be used to return this notation data as a string.
1897 The string is an XML representation of that data embedded in a
1898 <notation> container.  The user has to release the string with
1899 @code{free}.
1900
1901 The function returns a string if the notation data is available or
1902 @code{NULL} if there is no such data available.
1903 @end deftypefun
1904
1905
1906 @node Decrypt and Verify
1907 @subsection Decrypt and Verify
1908 @cindex decryption and verification
1909 @cindex verification and decryption
1910 @cindex signature check
1911 @cindex cryptographic operation, decryption and verification
1912
1913 @deftypefun GpgmeError gpgme_op_decrypt_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}}, @w{GpgmeSigStat *@var{r_stat}})
1914 The function @code{gpgme_op_decrypt_verify} decrypts the ciphertext in
1915 the data object @var{cipher} and stores it into the data object
1916 @var{plain}.  If @var{cipher} contains signatures, they will be
1917 verified and their combined status will be returned in @var{r_stat}.
1918
1919 After the operation completed, @code{gpgme_op_get_sig_status} and
1920 @code{gpgme_op_get_sig_key} can be used to retrieve more information
1921 about the signatures.
1922
1923 The function returns @code{GPGME_No_Error} if the ciphertext could be
1924 decrypted successfully, @code{GPGME_Invalid_Value} if @var{ctx},
1925 @var{cipher}, @var{plain} or @var{r_stat} is not a valid pointer,
1926 @code{GPGME_No_Data} if @var{cipher} does not contain any data to
1927 decrypt, @code{GPGME_Decryption_Failed} if @var{cipher} is not a valid
1928 cipher text, @code{GPGME_No_Passphrase} if the passphrase for the
1929 secret key could not be retrieved, and passes through any errors that
1930 are reported by the crypto engine support routines.
1931 @end deftypefun
1932
1933 @deftypefun GpgmeError gpgme_op_decrypt_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
1934 The function @code{gpgme_op_decrypt_verify_start} initiates a
1935 @code{gpgme_op_decrypt_verify} operation.  It can be completed by
1936 calling @code{gpgme_wait} on the context.  @xref{Waiting For
1937 Completion}.
1938
1939 The function returns @code{GPGME_No_Error} if the operation could be
1940 started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
1941 @var{cipher}, @var{plain} or @var{r_stat} is not a valid pointer, and
1942 @code{GPGME_No_Data} if @var{cipher} does not contain any data to
1943 decrypt.
1944 @end deftypefun
1945
1946
1947 @node Sign
1948 @subsection Sign
1949 @cindex signature, creation
1950 @cindex sign
1951 @cindex cryptographic operation, signing
1952
1953 A signature can contain signatures by one or more keys.  The set of
1954 keys used to create a signatures is contained in a context, and is
1955 applied to all following signing operations in this context (until the
1956 set is changed).
1957
1958 @menu
1959 * Selecting Signers::             How to choose the keys to sign with.
1960 * Creating a Signature::          How to create a signature.
1961 @end menu
1962
1963
1964 @node Selecting Signers
1965 @subsubsection Selecting Signers
1966 @cindex signature, selecting signers
1967 @cindex signers, selecting
1968
1969 @deftypefun void gpgme_signers_clear (@w{GpgmeCtx @var{ctx}})
1970 The function @code{gpgme_signers_clear} releases a reference for each
1971 key on the signers list and removes the list of signers from the
1972 context @var{ctx}.
1973
1974 Every context starts with an empty list.
1975 @end deftypefun
1976
1977 @deftypefun GpgmeError gpgme_signers_add (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}})
1978 The function @code{gpgme_signers_add} adds the key @var{key} to the
1979 list of signers in the context @var{ctx}.
1980
1981 One reference for the key is consumed.
1982 @end deftypefun
1983
1984 @deftypefun GpgmeKey gpgme_signers_enum (@w{const GpgmeCtx @var{ctx}}, @w{int @var{seq}})
1985 The function @code{gpgme_signers_enum} returns the @var{seq}th key in
1986 the list of signers in the context @var{ctx}.  An additional reference
1987 is acquired for the user.
1988
1989 If @var{seq} is out of range, @code{NULL} is returned.
1990 @end deftypefun
1991
1992
1993 @node Creating a Signature
1994 @subsubsection Creating a Signature
1995
1996 @deftp {Data type} {enum GpgmeSigMode}
1997 @tindex GpgmeSigMode
1998 The @code{GpgmeSigMode} type is used to specify the desired type of a
1999 signature.  The following modes are available:
2000
2001 @table @code
2002 @item GPGME_SIG_MODE_NORMAL
2003 A normal signature is made, the output includes the plaintext and the
2004 signature.
2005
2006 @item GPGME_SIG_MODE_DETACH
2007 A detached signature is made.
2008
2009 @item GPGME_SIG_MODE_CLEAR
2010 A clear text signature is made.  The @acronym{ASCII} armor and text
2011 mode settings of the context are ignored.
2012 @end table
2013 @end deftp
2014
2015 @deftypefun GpgmeError gpgme_op_sign (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{sig}}, @w{GpgmeSigMode @var{mode}})
2016 The function @code{gpgme_op_sign} creates a signature for the text in
2017 the data object @var{plain} and returns it in the data object
2018 @var{sig}.  The type of the signature created is determined by the
2019 @acronym{ASCII} armor and text mode attributes set for the context
2020 @var{ctx} and the requested signature mode @var{mode}.
2021
2022 More information about the signatures is available with
2023 @code{gpgme_get_op_info}.  @xref{Detailed Results}.
2024
2025 The function returns @code{GPGME_No_Error} if the signature could be
2026 created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2027 @var{plain} or @var{sig} is not a valid pointer, @code{GPGME_No_Data}
2028 if the signature could not be created, @code{GPGME_No_Passphrase} if
2029 the passphrase for the secret key could not be retrieved, and passes
2030 through any errors that are reported by the crypto engine support
2031 routines.
2032 @end deftypefun
2033
2034 @deftypefun GpgmeError gpgme_op_sign (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{sig}}, @w{GpgmeSigMode @var{mode}})
2035 The function @code{gpgme_op_sign_start} initiates a
2036 @code{gpgme_op_sign} operation.  It can be completed by calling
2037 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
2038
2039 The function returns @code{GPGME_No_Error} if the operation could be
2040 started successfully, and @code{GPGME_Invalid_Value} if @var{ctx},
2041 @var{plain} or @var{sig} is not a valid pointer.
2042 @end deftypefun
2043
2044
2045 @node Encrypt
2046 @subsection Encrypt
2047 @cindex encryption
2048 @cindex cryptographic operation, encryption
2049
2050 One plaintext can be encrypted for several recipients at the same
2051 time.  The list of recipients is created independently of any context,
2052 and then passed to the encryption operation.
2053
2054 @menu
2055 * Selecting Recipients::          How to choose the recipients.
2056 * Encrypting a Plaintext::        How to encrypt a plaintext.
2057 @end menu
2058
2059
2060 @node Selecting Recipients
2061 @subsubsection Selecting Recipients
2062 @cindex encryption, selecting recipients
2063 @cindex recipients
2064
2065 @deftp {Data type} GpgmeRecipients
2066 The @code{GpgmeRecipients} type is a handle for a set of recipients
2067 that can be used in an encryption process.
2068 @end deftp
2069
2070 @deftypefun GpgmeError gpgme_recipients_new (@w{GpgmeRecipients *@var{r_rset}})
2071 The function @code{gpgme_recipients_new} creates a new, empty set of
2072 recipients and returns a handle for it in @var{r_rset}.
2073
2074 The function returns @code{GPGME_No_Error} if the recipient set could
2075 be created successfully, and @code{GPGME_Out_Of_Core} if not enough
2076 memory was available.
2077 @end deftypefun
2078
2079 @deftypefun void gpgme_recipients_release (@w{GpgmeRecipients @var{rset}})
2080 The function @code{gpgme_recipients_release} destroys the set of
2081 recipients @var{rset} and releases all associated resources.
2082 @end deftypefun
2083
2084 @deftypefun GpgmeError gpgme_recipients_add_name (@w{GpgmeRecipients @var{rset}}, @w{const char *@var{name}})
2085 The function @code{gpgme_recipients_add_name} adds the recipient
2086 @var{name} to the set of recipients @var{rset}.  This is equivalent to
2087 @code{gpgme_recipients_add_name_with_validity} with a validity of
2088 @code{GPGME_VALIDITY_UNKNOWN}.
2089
2090 The function returns @code{GPGME_No_Error} if the recipient was added
2091 successfully, @code{GPGME_Invalid_Value} if @var{rset} or @var{name}
2092 is not a valid pointer, and @code{GPGME_Out_Of_Core} if not enough
2093 memory is available.
2094 @end deftypefun
2095
2096 @deftypefun GpgmeError gpgme_recipients_add_name_with_validity (@w{GpgmeRecipients @var{rset}}, @w{const char *@var{name}}, @w{GpgmeValidity @var{val}})
2097 The function @code{gpgme_recipients_add_name_with_validity} adds the
2098 recipient @var{name} with the validity @var{val} to the set of
2099 recipients @var{rset}.  If the validity is not known, the function
2100 @code{gpgme_recipients_add_name} can be used.
2101 @xref{Information About Keys}, for the possible values for @var{val}.
2102
2103 The function returns @code{GPGME_No_Error} if the recipient was added
2104 successfully, @code{GPGME_Invalid_Value} if @var{rset} or @var{name}
2105 is not a valid pointer, and @code{GPGME_Out_Of_Core} if not enough
2106 memory is available.
2107 @end deftypefun
2108
2109 @deftypefun {unsigned int} gpgme_recipients_count (@w{const @var{GpgmeRecipients rset}})
2110 The function @code{gpgme_recipients_count} returns the number of
2111 recipients in the set @var{rset}.
2112 @end deftypefun
2113
2114 @deftypefun GpgmeError gpgme_recipients_enum_open (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}})
2115 The function @code{gpgme_recipients_enum_open} creates a new iterator
2116 @var{iter} that can be used to walk through the set of recipients in
2117 @var{rset}, using @code{gpgme_recipients_enum_read}.
2118
2119 If the iterator is not needed anymore, it can be closed with
2120 @code{gpgme_recipients_enum_close}.
2121
2122 The function returns @code{GPGME_No_Error} if the enumerator was
2123 successfully created and @code{GPGME_Invalid_Value} if @var{rset} or
2124 @var{iter} is not a valid pointer.
2125 @end deftypefun
2126
2127 @deftypefun {const char *} gpgme_recipients_enum_read (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}})
2128 The function @code{gpgme_recipients_enum_read} returns a string
2129 containing the name of the next recipient in the set @var{rset} for
2130 the iterator @var{iter}.  The string is valid as long as @var{rset} is
2131 valid or the function is called the next time with the same recipient
2132 set and iterator, whatever is earlier.
2133 @end deftypefun
2134
2135 @deftypefun GpgmeError gpgme_recipients_enum_close (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}})
2136 The function @code{gpgme_recipients_enum_close} releases the iterator
2137 @var{iter} for the recipient set @var{rset}.
2138 @end deftypefun
2139
2140
2141 @node Encrypting a Plaintext
2142 @subsubsection Encrypting a Plaintext
2143
2144 @deftypefun GpgmeError gpgme_op_encrypt (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
2145 The function @code{gpgme_op_crypt} encrypts the plaintext in the data
2146 object @var{plain} for the recipients @var{rset} and stores the
2147 ciphertext in the data object @var{cipher}.  The type of the
2148 ciphertext created is determined by the @acronym{ASCII} armor and text
2149 mode attributes set for the context @var{ctx}.
2150
2151 More information about the encrypted text is available with
2152 @code{gpgme_get_op_info}.  @xref{Detailed Results}.
2153
2154 The function returns @code{GPGME_No_Error} if the ciphertext could be
2155 created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2156 @var{rset}, @var{plain} or @var{cipher} is not a valid pointer,
2157 @code{GPGME_No_Recipient} if @var{rset} does not contain any
2158 valid recipients, @code{GPGME_No_Passphrase} if the passphrase for the
2159 secret key could not be retrieved, and passes through any errors that
2160 are reported by the crypto engine support routines.
2161 @end deftypefun
2162
2163 @deftypefun GpgmeError gpgme_op_encrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
2164 The function @code{gpgme_op_encrypt_start} initiates a
2165 @code{gpgme_op_encrypt} operation.  It can be completed by calling
2166 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
2167
2168 The function returns @code{GPGME_No_Error} if the operation could be
2169 started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2170 @var{rset}, @var{plain} or @var{cipher} is not a valid pointer, and
2171 @code{GPGME_No_Recipient} if @var{rset} does not contain any valid
2172 recipients.
2173 @end deftypefun
2174
2175
2176 @node Detailed Results
2177 @subsection Detailed Results
2178 @cindex cryptographic operation, detailed results
2179
2180 @deftypefun {char *} gpgme_get_op_info (@w{GpgmeCtx @var{ctx}}, @w{int @var{reserved}})
2181 The function @code{gpgme_get_op_info} retrieves more information about
2182 the last crypto operation.
2183
2184 The function returns a string in the XML format.  The user has to
2185 release the string with @code{free}.
2186
2187 Here is a sample of the information that might be returned:
2188 @example
2189 <literal>
2190 <![CDATA[
2191 <GnupgOperationInfo>
2192   <signature>
2193     <detached/> <!-- or cleartext or standard -->
2194     <algo>17</algo>
2195     <hashalgo>2</hashalgo>
2196     <micalg>pgp-sha1</micalg>
2197     <sigclass>01</sigclass>
2198     <created>9222222</created>
2199     <fpr>121212121212121212</fpr>
2200   </signature>
2201 </GnupgOperationInfo>
2202 ]]>
2203 </literal>
2204 @end example
2205
2206 Currently, the only operations that return additional information are
2207 encrypt and sign.  @xref{Encrypt}, @xref{Sign}.
2208
2209 The function returns a string or @code{NULL} if no such data is
2210 available.
2211 @end deftypefun
2212
2213
2214 @node Run Control
2215 @section Run Control
2216 @cindex run control
2217 @cindex cryptographic operation, running
2218
2219 Some basic support for running operations asynchronously is available
2220 in @acronym{GPGME}.  You can use it to set up a context completely up
2221 to initiating the desired operation, but delay performing it to a
2222 later point.
2223
2224 @menu
2225 * Waiting For Completion::        Waiting until an operation is completed.
2226 * Cancelling an Operation::       Interrupting a running operation.
2227 * Hooking Up Into Idle Time::     Doing something when nothing has to be done.
2228 @end menu
2229
2230
2231 @node Waiting For Completion
2232 @subsection Waiting For Completion
2233 @cindex cryptographic operation, wait for
2234 @cindex wait for completion
2235
2236 @deftypefun GpgmeCtx gpgme_wait (@w{GpgmeCtx @var{ctx}}, @w{GpgmeError *@var{status}}, @w{int @var{hang}})
2237 The function @code{gpgme_wait} does continue the pending operation
2238 within the context @var{ctx}.  In particular, it ensures the data
2239 exchange between @acronym{GPGME} and the crypto backend and watches
2240 over the run time status of the backend process.
2241
2242 If @var{hang} is true, the function does not return until the
2243 operation is completed or cancelled.  Otherwise the function will not
2244 block for a long time.
2245
2246 The error status of the finished operation is returned in
2247 @var{status}.
2248
2249 The @var{ctx} argument can be @code{NULL}.  In that case,
2250 @code{gpgme_wait} waits for any context to complete its operation.
2251
2252 The function returns the @var{ctx} of the context which has finished
2253 the operation.
2254 @end deftypefun
2255
2256
2257 @node Cancelling an Operation
2258 @subsection Cancelling an Operation
2259 @cindex cancellation
2260 @cindex cryptographic operation, cancel
2261
2262 @deftypefun void gpgme_cancel (@w{GpgmeCtx @var{ctx}})
2263 The function @code{gpgme_cancel} tries to cancel the pending
2264 operation.  The function @code{gpgme_wait} might notice the
2265 cancellation flag and return.  It is currently not guaranteed to work
2266 under all circumstances.  It's current primary purpose is to prevent
2267 asking for a passphrase again in the passphrase callback.
2268 @end deftypefun
2269
2270
2271 @node Hooking Up Into Idle Time
2272 @subsection Hooking Up Into Idle Time
2273 @cindex idle time
2274 @cindex idle function
2275
2276 @deftp {Data type} {void (*GpgmeIdleFunc) (void)}
2277 @tindex GpgmeIdleFunc
2278 The @code{GpgmeIdleFunc} type is the type of functions usable as
2279 an idle function that can be registered with @code{gpgme_register_idle}.
2280 @end deftp
2281
2282 @deftypefun GpgmeIdleFunc gpgme_register_idle (@w{GpgmeIdleFunc @var{idle}})
2283 The function @code{gpgme_register_idle} can be used to register
2284 @var{idle} as the idle function.
2285
2286 @var{idle} will be called whenever @acronym{GPGME} thinks that it is
2287 idle and time can better be spent elsewhere.  Setting @var{idle} to
2288 @code{NULL} disables use of the idle function (this is the default).
2289
2290 The function returns the old idle function, or @code{NULL} if none was
2291 registered yet.
2292 @end deftypefun
2293
2294
2295 @include gpl.texi
2296
2297
2298 @include fdl.texi
2299
2300
2301 @node Concept Index
2302 @unnumbered Concept Index
2303
2304 @printindex cp
2305
2306
2307 @node Function and Data Index
2308 @unnumbered Function and Data Index
2309
2310 @printindex fn
2311
2312
2313 @summarycontents
2314 @contents
2315 @bye
2316
2317 @c  LocalWords:  GPGME gpgme