2002-01-30 Marcus Brinkmann <marcus@g10code.de>
[gpgme.git] / doc / gpgme.texi
1 \input texinfo                  @c -*- Texinfo -*-
2 @setfilename gpgme.info
3 @settitle The `GnuPG Made Easy' Reference Manual
4
5 @dircategory GNU Libraries
6 @direntry
7 * @acronym{GPGME}: (gpgme)           Adding support for cryptography to your program.
8 @end direntry
9
10 @include version.texi
11
12 @c Unify some of the indices.
13 @syncodeindex tp fn
14 @syncodeindex pg fn
15
16 @ifinfo
17 This file documents the @acronym{GPGME} library.
18
19 This is Edition @value{EDITION}, last updated @value{UPDATED}, of
20 @cite{The `GnuPG Made Easy' Reference Manual}, for Version
21 @value{VERSION}.
22
23 Copyright @copyright{} 2002 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.  Defined values for @var{mode}
1046 are:
1047
1048 @table @code
1049 @item 0
1050 Normal listing.
1051 @item 1
1052 Fast listing without information about the key validity.
1053 @end table
1054 @end deftypefun
1055
1056
1057 @node Passphrase Callback
1058 @subsection Passphrase Callback
1059 @cindex callback, passphrase
1060 @cindex passphrase callback
1061
1062 @deftp {Data type} {const char *(*GpgmePassphraseCb)(void *@var{hook}, const char *@var{desc}, void **@var{r_hd})}
1063 @tindex GpgmePassphraseCb
1064 The @code{GpgmePassphraseCb} type is the type of functions usable as
1065 passphrase callback function.
1066
1067 The string @var{desc} contains a test usable to be displayed to the
1068 user of the application.  The function should return a passphrase for
1069 the context when invoked with @var{desc} not being @code{NULL}.
1070
1071 The user may store information about the resources associated with the
1072 returned passphrase in @var{*r_hd}.  When the passphrase is no longer
1073 needed by @acronym{GPGME}, the passphrase callback function will be
1074 called with @var{desc} being @var{NULL}, and @var{r_hd} being the same
1075 as at the first invocation.
1076 @end deftp
1077
1078 @deftypefun void gpgme_set_passphrase_cb (@w{GpgmeCtx @var{ctx}}, @w{GpgmePassphraseCb @var{passfunc}}, @w{void *@var{hook_value}})
1079 The function @code{gpgme_set_passphrase_cb} sets the function that is
1080 used when a passphrase needs to be provided by the user to
1081 @var{passfunc}.  The function @var{passfunc} needs to implemented by
1082 the user, and whenever it is called, it is called with its first
1083 argument being @var{hook_value}.  By default, no passphrase callback
1084 function is set.
1085
1086 Not all crypto engines require this callback to retrieve the
1087 passphrase.  It is better if the engine retrieves the passphrase from
1088 a trusted agent (a daemon process), rather than having each user to
1089 implement their own passphrase query.
1090
1091 The user can disable the use of a passphrase callback function by
1092 calling @code{gpgme_set_passphrase_cb} with @var{passfunc} being
1093 @code{NULL}.
1094 @end deftypefun
1095
1096
1097 @node Progress Meter Callback
1098 @subsection Progress Meter Callback
1099 @cindex callback, progress meter
1100 @cindex progress meter callback
1101
1102 @deftp {Data type} {const char *(*GpgmeProgressCb)(void *@var{hook}, const char *@var{what}, int @var{type}, int @var{current}, int @var{total})}
1103 @tindex GpgmeProgressCb
1104 The @code{GpgmeProgressCb} type is the type of functions usable as
1105 progress callback function.
1106
1107 The arguments are specific to the crypto engine.  More information
1108 about the progress information returned from the GnuPG engine can be
1109 found in the GnuPG source code in the file @file{doc/DETAILS} in the
1110 section PROGRESS.
1111 @end deftp
1112
1113 @deftypefun void gpgme_set_progress_cb (@w{GpgmeCtx @var{ctx}}, @w{GpgmeProgressCb @var{progfunc}}, @w{void *@var{hook_value}})
1114 The function @code{gpgme_set_progress_cb} sets the function that is
1115 used when progress information about a cryptographic operation is
1116 available.  The function @var{progfunc} needs to implemented by the
1117 user, and whenever it is called, it is called with its first argument
1118 being @var{hook_value}.  By default, no progress callback function
1119 is set.
1120
1121 Setting a callback function allows an interactive program to display
1122 progress information about a long operation to the user.
1123
1124 The user can disable the use of a progress callback function by
1125 calling @code{gpgme_set_progress_cb} with @var{progfunc} being
1126 @code{NULL}.
1127 @end deftypefun
1128
1129
1130 @node Key Management
1131 @section Key Management
1132 @cindex key management
1133
1134 Some of the cryptographic operations require that recipients or
1135 signers are specified.  This is always done by specifying the
1136 respective keys that should be used for the operation.  The following
1137 section describes how such keys can be selected and manipulated.
1138
1139 @deftp {Data type} GpgmeKey
1140 The @code{GpgmeKey} type is a handle for a public or secret key, and
1141 is used to select the key for operations involving it.
1142
1143 A key can contain several user IDs and sub keys.
1144 @end deftp
1145
1146 @menu
1147 * Listing Keys::                  Browsing the list of available keys.
1148 * Information About Keys::        Requesting detailed information about keys.
1149 * Manipulating Keys::             Operations on keys.
1150 * Generating Keys::               Creating new key pairs.
1151 * Exporting Keys::                Retrieving key data from the key ring.
1152 * Importing Keys::                Adding keys to the key ring.
1153 * Deleting Keys::                 Removing keys from the key ring.
1154 @end menu
1155
1156
1157 @node Listing Keys
1158 @subsection Listing Keys
1159 @cindex listing keys
1160 @cindex key listing
1161 @cindex key listing, start
1162 @cindex key ring, list
1163 @cindex key ring, search
1164
1165 @deftypefun GpgmeError gpgme_op_keylist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}})
1166 The function @code{gpgme_op_keylist_start} initiates a key listing
1167 operation inside the context @var{ctx}.  It sets everything up so that
1168 subsequent invocations of @code{gpgme_op_keylist_next} return the keys
1169 in the list.
1170
1171 If @var{pattern} is @code{NULL}, all available keys are returned.
1172 Otherwise, @var{pattern} contains an engine specific expression that
1173 is used to limit the list to all keys matching the pattern.
1174
1175 If @var{secret_only} is not @code{0}, the list is restricted to secret
1176 keys only.
1177
1178 The context will be busy until either all keys are received (and
1179 @code{gpgme_op_keylist_next} returns @code{GPGME_EOF}), or
1180 @code{gpgme_op_keylist_end} is called to finish the operation.
1181
1182 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
1183 valid pointer, and passes through any errors that are reported by the
1184 crypto engine support routines.
1185 @end deftypefun
1186
1187 @deftypefun GpgmeError gpgme_op_keylist_next (@w{GpgmeCtx @var{ctx}}, @w{GpgmeKey *@var{r_key}})
1188 The function @code{gpgme_op_keylist_next} returns the next key in the
1189 list created by a previous @code{gpgme_op_keylist_start} operation in
1190 the context @var{ctx}.  The key will have one reference for the user.
1191 @xref{Manipulating Keys}.
1192
1193 This is the only way to get at @code{GpgmeKey} objects in
1194 @acronym{GPGME}.
1195
1196 If the last key in the list has already been returned,
1197 @code{gpgme_op_keylist_next} returns @code{GPGME_EOF}.
1198
1199 The function returns @code{GPGME_Invalid_Value} if @var{ctx} or
1200 @var{r_key} is not a valid pointer, @code{GPGME_No_Request} if there
1201 is no pending operation, @code{GPGME_Out_Of_Core} if there is not
1202 enough memory for the operation.
1203 @end deftypefun
1204
1205 @deftypefun GpgmeError gpgme_op_keylist_end (@w{GpgmeCtx @var{ctx}})
1206 The function @code{gpgme_op_keylist_next} ends a pending key list
1207 operation in the context @var{ctx}.
1208
1209 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
1210 valid pointer, @code{GPGME_No_Request} if there is no pending
1211 operation, @code{GPGME_Out_Of_Core} if at some time during the
1212 operation there was not enough memory available.
1213 @end deftypefun
1214
1215
1216 @node Information About Keys
1217 @subsection Information About Keys
1218 @cindex key, information about
1219 @cindex key, attributes
1220 @cindex attributes, of a key
1221
1222 @deftypefun {char *} gpgme_key_get_as_xml (@w{GpgmeKey @var{key}})
1223 The function @code{gpgme_key_get_as_xml} returns a string in
1224 @acronym{XML} format describing the key @var{key}.  The user has to
1225 release the string with @code{free}.
1226
1227 The function returns @code{NULL} if @var{key} is not a valid pointer,
1228 or there is not enough memory available.
1229 @end deftypefun
1230
1231 @deftp {Data type} GpgmeAttr
1232 The @code{GpgmeAttr} type is used to specify a key or trust item
1233 attribute.  The following attributes are defined:
1234
1235 @table @code
1236 @item GPGME_ATTR_KEYID
1237 This is the key ID of a sub key.  It is representable as a string.
1238
1239 For trust items, the trust item refers to the key with this ID.
1240
1241 @item GPGME_ATTR_FPR
1242 This is the fingerprint of a sub key.  It is representable as a
1243 string.
1244
1245 @item GPGME_ATTR_ALGO
1246 This is the crypto algorithm for which the sub key can be used.  It
1247 is representable as a string and as a number.  The numbers correspond
1248 to the @code{enum gcry_pk_algos} values in the gcrypt library.
1249
1250 @item GPGME_ATTR_LEN
1251 This is the key length of a sub key.  It is representable as a
1252 number.
1253
1254 @item GPGME_ATTR_CREATED
1255 This is the timestamp at creation time of a sub key.  It is
1256 representable as a number.
1257
1258 @item GPGME_ATTR_EXPIRE
1259 XXX FIXME
1260
1261 @item GPGME_ATTR_OTRUST
1262 XXX FIXME  (also for trust items)
1263
1264 @item GPGME_ATTR_USERID
1265 This is a user ID.  There can be more than one user IDs in a
1266 @var{GpgmeKey} object.  The first one (with index 0) is the primary
1267 user ID.  The user ID is representable as a number.
1268
1269 For trust items, this is the user ID associated with this trust item.
1270
1271 @item GPGME_ATTR_NAME
1272 This is the name belonging to a user ID.  It is representable as a string.
1273
1274 @item GPGME_ATTR_EMAIL
1275 This is the email address belonging to a user ID.  It is representable
1276 as a string.
1277
1278 @item GPGME_ATTR_COMMENT
1279 This is the comment belonging to a user ID.  It is representable as a
1280 string.
1281
1282 @item GPGME_ATTR_VALIDITY
1283 This is the validity belonging to a user ID.  It is representable as a
1284 string and as a number.  See below for a list of available validities.
1285
1286 For trust items, this is the validity that is associated with this
1287 trust item.
1288
1289 @item GPGME_ATTR_UID_REVOKED
1290 This specifies if a user ID is revoked.  It is representable as a
1291 number, and is @code{1} if the user ID is revoked, and @code{0}
1292 otherwise.
1293
1294 @item GPGME_ATTR_UID_INVALID
1295 This specifies if a user ID is invalid.  It is representable as a
1296 number, and is @code{1} if the user ID is invalid, and @code{0}
1297 otherwise.
1298
1299 @item GPGME_ATTR_LEVEL
1300 This is the trust level of a trust item.
1301
1302 @item GPGME_ATTR_TYPE
1303 This is the type of a trust item.
1304
1305 @item GPGME_ATTR_IS_SECRET
1306 This specifies if the key is a secret key.  It is representable as a
1307 string or a number.  If the key is a secret key, the representation is
1308 ``1'' or @code{1}, otherwise it is NULL or @code{0}.
1309
1310 @item GPGME_ATTR_KEY_REVOKED
1311 This specifies if a sub key is revoked.  It is representable as a
1312 number, and is @code{1} if the key is revoked, and @code{0} otherwise.
1313
1314 @item GPGME_ATTR_KEY_INVALID
1315 This specifies if a sub key is invalid.  It is representable as a
1316 number, and is @code{1} if the key is invalid, and @code{0} otherwise.
1317
1318 @item GPGME_ATTR_KEY_EXPIRED
1319 This specifies if a sub key is expired.  It is representable as a
1320 number, and is @code{1} if the key is expired, and @code{0} otherwise.
1321
1322 @item GPGME_ATTR_KEY_DISABLED
1323 This specifies if a sub key is disabled.  It is representable as a
1324 number, and is @code{1} if the key is disabled, and @code{0} otherwise.
1325
1326 @item GPGME_ATTR_KEY_CAPS
1327 This is a description of the capabilities of a sub key.  It is
1328 representable as a string.  The string contains the letter ``e'' if
1329 the key can be used for encryption, ``s'' if the key can be used for
1330 signatures, and ``c'' if the key can be used for certifications.
1331
1332 @item GPGME_ATTR_CAN_ENCRYPT
1333 This specifies if a sub key can be used for encryption.  It is
1334 representable as a number, and is @code{1} if the sub key can be used
1335 for encryption, and @code{0} otherwise.
1336
1337 @item GPGME_ATTR_CAN_SIGN
1338 This specifies if a sub key can be used for signatures.  It is
1339 representable as a number, and is @code{1} if the sub key can be used
1340 for signatures, and @code{0} otherwise.
1341
1342 @item GPGME_ATTR_CAN_CERTIFY
1343 This specifies if a sub key can be used for certifications.  It is
1344 representable as a number, and is @code{1} if the sub key can be used
1345 for certifications, and @code{0} otherwise.
1346 @end table
1347 @end deftp
1348
1349 @deftp {Data type} GpgmeValidity
1350 The @code{GpgmeValidity} type is used to specify the validity of a user ID
1351 in a key.  The following validities are defined:
1352
1353 @table @code
1354 @item GPGME_VALIDITY_UNKNOWN
1355 The user ID is of unknown validity.  The string representation of this
1356 validity is ``?''.
1357
1358 @item GPGME_VALIDITY_UNDEFINED
1359 The validity of the user ID is undefined.  The string representation of this
1360 validity is ``q''.
1361
1362 @item GPGME_VALIDITY_NEVER
1363 The user ID is never valid.  The string representation of this
1364 validity is ``n''.
1365
1366 @item GPGME_VALIDITY_MARGINAL
1367 The user ID is marginally valid.  The string representation of this
1368 validity is ``m''.
1369
1370 @item GPGME_VALIDITY_FULL
1371 The user ID is fully valid.  The string representation of this
1372 validity is ``f''.
1373
1374 @item GPGME_VALIDITY_ULTIMATE
1375 The user ID is ultimately valid.  The string representation of this
1376 validity is ``u''.
1377 @end table
1378 @end deftp
1379
1380 @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}})
1381 The function @code{gpgme_key_get_string_attr} returns the value of the
1382 string-representable attribute @var{what} of key @var{key}.  If the
1383 attribute occurs more than once in the key, the index is specified by
1384 @var{idx}.  This applies to attributes of sub keys and user IDs.  The
1385 argument @var{reserved} is reserved for later use and should be
1386 @code{NULL}.
1387
1388 The string returned is only valid as long as the key is valid.
1389
1390 The function returns @code{0} if an attribute can't be returned as a
1391 string, @var{key} is not a valid pointer, @var{idx} out of range,
1392 or @var{reserved} not @code{NULL}.
1393 @end deftypefun
1394
1395 @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}})
1396 The function @code{gpgme_key_get_ulong_attr} returns the value of the
1397 number-representable attribute @var{what} of key @var{key}.  If the
1398 attribute occurs more than once in the key, the index is specified by
1399 @var{idx}.  This applies to attributes of sub keys and user IDs.  The
1400 argument @var{reserved} is reserved for later use and should be
1401 @code{NULL}.
1402
1403 The function returns @code{0} if the attribute can't be returned as a
1404 number, @var{key} is not a valid pointer, @var{idx} out of range,
1405 or @var{reserved} not @code{NULL}.
1406 @end deftypefun
1407
1408
1409 @node Manipulating Keys
1410 @subsection Manipulating Keys
1411 @cindex key, manipulation
1412
1413 @deftypefun void gpgme_key_ref (@w{GpgmeKey @var{key}})
1414 The function @code{gpgme_key_ref} acquires an additional reference for
1415 the key @var{key}.
1416 @end deftypefun
1417
1418 @deftypefun void gpgme_key_unref (@w{GpgmeKey @var{key}})
1419 @deftypefunx void gpgme_key_release (@w{GpgmeKey @var{key}})
1420 The function @code{gpgme_key_ref} releases a reference for the key
1421 @var{key}.  If this was the last reference, the key will be destroyed
1422 and all resources associated to it will be released.
1423
1424 The function @code{gpgme_key_release} is an alias for
1425 @code{gpgme_key_unref}.
1426 @end deftypefun
1427
1428
1429 @node Generating Keys
1430 @subsection Generating Keys
1431 @cindex key, creation
1432 @cindex key ring, add
1433
1434 @deftypefun GpgmeError gpgme_op_genkey (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{pubkey}}, @w{GpgmeData @var{seckey}})
1435 The function @code{gpgme_op_genkey} generates a new key pair in the
1436 context @var{ctx} and puts it into the standard key ring if both
1437 @var{pubkey} and @var{seckey} are @code{NULL}.  In this case the
1438 function returns immediately after starting the operation, and does
1439 not wait for it to complete.  @var{pubkey} and @var{seckey} are
1440 reserved for later use and should be @code{NULL}.  (The function
1441 should return the public key in the data buffer @var{pubkey} and the
1442 secret key in the data buffer @var{seckey}, but this is not
1443 implemented yet).
1444
1445 The argument @var{parms} specifies parameters for the key in an XML
1446 string.  The details about the format of @var{parms} are specific to
1447 the crypto engine used by @var{ctx}.  Here is an example for GnuPG as
1448 the crypto engine:
1449
1450 @example
1451 <literal>
1452 <![CDATA[
1453 <GnupgKeyParms format="internal">
1454 Key-Type: DSA
1455 Key-Length: 1024
1456 Subkey-Type: ELG-E
1457 Subkey-Length: 1024
1458 Name-Real: Joe Tester
1459 Name-Comment: with stupid passphrase
1460 Name-Email: joe@@foo.bar
1461 Expire-Date: 0
1462 Passphrase: abc
1463 </GnupgKeyParms>
1464 ]]>
1465 </literal>
1466 @end example
1467
1468 Strings should be given in UTF-8 encoding.  The only format supported
1469 for now is ``internal''.  The content of the @code{GnupgKeyParms}
1470 container is passed verbatim to GnuPG.  Control statements are not
1471 allowed.
1472
1473 The function returns @code{GPGME_No_Error} if the operation could be
1474 started successfully, @code{GPGME_Invalid_Value} if @var{parms} is not
1475 a valid XML string, and @code{GPGME_Not_Supported} if @var{pubkey} or
1476 @var{seckey} is not @code{NULL}.
1477 @end deftypefun
1478
1479 @deftypefun GpgmeError gpgme_op_genkey_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{pubkey}}, @w{GpgmeData @var{seckey}})
1480 The function @code{gpgme_op_genkey_start} initiates a
1481 @code{gpgme_op_genkey} operation.  It can be completed by calling
1482 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
1483
1484 The function returns @code{GPGME_No_Error} if the operation could be
1485 started successfully, @code{GPGME_Invalid_Value} if @var{parms} is not
1486 a valid XML string, and @code{GPGME_Not_Supported} if @var{pubkey} or
1487 @var{seckey} is not @code{NULL}.
1488 @end deftypefun
1489
1490
1491 @node Exporting Keys
1492 @subsection Exporting Keys
1493 @cindex key, export
1494 @cindex key ring, export from
1495
1496 @deftypefun GpgmeError gpgme_op_export (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{recipients}}, @w{GpgmeData @var{keydata}})
1497 The function @code{gpgme_op_export} extracts the public keys of the
1498 user IDs in @var{recipients} and returns them in the data buffer
1499 @var{keydata}.  The type of the public keys returned is determined by
1500 the @acronym{ASCII} armor attribute set for the context @var{ctx}.
1501
1502 The function returns @code{GPGME_No_Error} if the operation completed
1503 successfully, @code{GPGME_Invalid_Value} if @var{recipients} is
1504 @code{NULL} or @var{keydata} is not a valid empty data buffer, and
1505 passes through any errors that are reported by the crypto engine
1506 support routines.
1507 @end deftypefun
1508
1509 @deftypefun GpgmeError gpgme_op_export_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{recipients}}, @w{GpgmeData @var{keydata}})
1510 The function @code{gpgme_op_export_start} initiates a
1511 @code{gpgme_op_export} operation.  It can be completed by calling
1512 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
1513
1514 The function returns @code{GPGME_No_Error} if the operation could be
1515 started successfully, and @code{GPGME_Invalid_Value} if
1516 @var{recipients} is @code{NULL} or @var{keydata} is not a valid empty
1517 data buffer.
1518 @end deftypefun
1519
1520
1521 @node Importing Keys
1522 @subsection Importing Keys
1523 @cindex key, import
1524 @cindex key ring, import to
1525
1526 @deftypefun GpgmeError gpgme_op_import (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}})
1527 The function @code{gpgme_op_import} adds the keys in the data buffer
1528 @var{keydata} to the key ring of the crypto engine used by @var{ctx}.
1529 The format of @var{keydata} can be @var{ASCII} armored, for example,
1530 but the details are specific to the crypto engine.
1531
1532 More information about the import is available with
1533 @code{gpgme_get_op_info}.  @xref{Detailed Results}.
1534
1535 The function returns @code{GPGME_No_Error} if the import was completed
1536 successfully, @code{GPGME_Invalid_Value} if @var{keydata} if @var{ctx}
1537 or @var{keydata} is not a valid pointer, and @code{GPGME_No_Data} if
1538 @var{keydata} is an empty data buffer.
1539 @end deftypefun
1540
1541 @deftypefun GpgmeError gpgme_op_import_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}})
1542 The function @code{gpgme_op_import_start} initiates a
1543 @code{gpgme_op_import} operation.  It can be completed by calling
1544 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
1545
1546 The function returns @code{GPGME_No_Error} if the import could be
1547 started successfully, @code{GPGME_Invalid_Value} if @var{keydata} if
1548 @var{ctx} or @var{keydata} is not a valid pointer, and
1549 @code{GPGME_No_Data} if @var{keydata} is an empty data buffer.
1550 @end deftypefun
1551
1552
1553 @node Deleting Keys
1554 @subsection Deleting Keys
1555 @cindex key, delete
1556 @cindex key ring, delete from
1557
1558 @deftypefun GpgmeError gpgme_op_delete (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}, @w{int @var{allow_secret}})
1559 The function @code{gpgme_op_delete} deletes the key @var{key} from the
1560 key ring of the crypto engine used by @var{ctx}.  If
1561 @var{allow_secret} is @code{0}, only public keys are deleted,
1562 otherwise secret keys are deleted as well.
1563
1564 The function returns @code{GPGME_No_Error} if the key was deleted
1565 successfully, @code{GPGME_Invalid_Value} if @var{ctx} or @var{key} is
1566 not a valid pointer, @code{GPGME_Invalid_Key} if @var{key} could not
1567 be found in the keyring, and @code{GPGME_Conflict} if the secret key
1568 for @var{key} is available, but @var{allow_secret} is zero.
1569 @end deftypefun
1570
1571 @deftypefun GpgmeError gpgme_op_delete_start (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}, @w{int @var{allow_secret}})
1572 The function @code{gpgme_op_delete_start} initiates a
1573 @code{gpgme_op_delete} operation.  It can be completed by calling
1574 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
1575
1576 The function returns @code{GPGME_No_Error} if the operation was
1577 started successfully, and @code{GPGME_Invalid_Value} if @var{ctx} or
1578 @var{key} is not a valid pointer.
1579 @end deftypefun
1580
1581
1582 @node Trust Item Management
1583 @section Trust Item Management
1584 @cindex trust item
1585
1586 @strong{Caution:} The trust items interface is experimental.
1587
1588 @deftp {Data type} GpgmeTrustItem
1589 The @code{GpgmeTrustItem} type is a handle for a trust item.
1590 @end deftp
1591
1592 @menu
1593 * Listing Trust Items::           Browsing the list of available trust items.
1594 * Information About Trust Items:: Requesting detailed information about trust items.
1595 * Manipulating Trust Items::      Operations on trust items.
1596 @end menu
1597
1598
1599 @node Listing Trust Items
1600 @subsection Listing Trust Items
1601 @cindex trust item list
1602
1603 @deftypefun GpgmeError gpgme_op_trustlist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{max_level}})
1604 The function @code{gpgme_op_trustlist_start} initiates a trust item
1605 listing operation inside the context @var{ctx}.  It sets everything up
1606 so that subsequent invocations of @code{gpgme_op_trustlist_next} return
1607 the trust items in the list.
1608
1609 The string @var{pattern} contains an engine specific expression that
1610 is used to limit the list to all trust items matching the pattern.  It
1611 can not be the empty string.
1612
1613 The argument @var{max_level} is currently ignored.
1614
1615 The context will be busy until either all trust items are received
1616 (and @code{gpgme_op_trustlist_next} returns @code{GPGME_EOF}), or
1617 @code{gpgme_op_trustlist_end} is called to finish the operation.
1618
1619 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
1620 valid pointer, and passes through any errors that are reported by the
1621 crypto engine support routines.
1622 @end deftypefun
1623
1624 @deftypefun GpgmeError gpgme_op_trustlist_next (@w{GpgmeCtx @var{ctx}}, @w{GpgmeTrustItem *@var{r_item}})
1625 The function @code{gpgme_op_trustlist_next} returns the next trust
1626 item in the list created by a previous @code{gpgme_op_trustlist_start}
1627 operation in the context @var{ctx}.  The trust item can be destroyed
1628 with @code{gpgme_trust_item_release}.  @xref{Manipulating Trust Items}.
1629
1630 This is the only way to get at @code{GpgmeTrustItem} objects in
1631 @acronym{GPGME}.
1632
1633 If the last trust item in the list has already been returned,
1634 @code{gpgme_op_trustlist_next} returns @code{GPGME_EOF}.
1635
1636 The function returns @code{GPGME_Invalid_Value} if @var{ctx} or
1637 @var{r_item} is not a valid pointer, @code{GPGME_No_Request} if there
1638 is no pending operation, @code{GPGME_Out_Of_Core} if there is not
1639 enough memory for the operation.
1640 @end deftypefun
1641
1642 @deftypefun GpgmeError gpgme_op_trustlist_end (@w{GpgmeCtx @var{ctx}})
1643 The function @code{gpgme_op_trustlist_next} ends a pending key list
1644 operation in the context @var{ctx}.
1645
1646 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
1647 valid pointer, @code{GPGME_No_Request} if there is no pending
1648 operation, @code{GPGME_Out_Of_Core} if at some time during the
1649 operation there was not enough memory available.
1650 @end deftypefun
1651
1652
1653 @node Information About Trust Items
1654 @subsection Information About Trust Items
1655 @cindex trust item, information about
1656 @cindex trust item, attributes
1657 @cindex attributes, of a trust item
1658
1659 Trust items have attributes which can be queried using the interfaces
1660 below.  The attribute identifiers are shared with those for key
1661 attributes.  @xref{Information About Keys}.
1662
1663 @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}})
1664 The function @code{gpgme_trust_item_get_string_attr} returns the value
1665 of the string-representable attribute @var{what} of trust item
1666 @var{item}.  If the attribute occurs more than once in the trust
1667 items, the index is specified by @var{idx}.  However, currently no
1668 such attributes exists, so @var{idx} should be @code{0}.  The argument
1669 @var{reserved} is reserved for later use and should be @code{NULL}.
1670
1671 The string returned is only valid as long as the key is valid.
1672
1673 The function returns @code{0} if an attribute can't be returned as a
1674 string, @var{key} is not a valid pointer, @var{idx} out of range,
1675 or @var{reserved} not @code{NULL}.
1676 @end deftypefun
1677
1678 @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}})
1679 The function @code{gpgme_trust_item_get_int_attr} returns the value of
1680 the number-representable attribute @var{what} of trust item
1681 @var{item}.  If the attribute occurs more than once in the trust item,
1682 the index is specified by @var{idx}.  However, currently no such
1683 attribute exists, so @var{idx} should be @code{0}.  The argument
1684 @var{reserved} is reserved for later use and should be @code{NULL}.
1685
1686 The function returns @code{0} if the attribute can't be returned as a
1687 number, @var{key} is not a valid pointer, @var{idx} out of range,
1688 or @var{reserved} not @code{NULL}.
1689 @end deftypefun
1690
1691
1692 @node Manipulating Trust Items
1693 @subsection Manipulating Trust Items
1694 @cindex trust item, manipulation
1695
1696 @deftypefun void gpgme_trust_item_release (@w{GpgmeTrustItem @var{item}})
1697 The function @code{gpgme_trust_item_release} destroys a
1698 @code{GpgmeTrustItem} object and releases all associated resources.
1699 @end deftypefun
1700
1701 @node Crypto Operations
1702 @section Crypto Operations
1703 @cindex cryptographic operation
1704
1705 @menu
1706 * Decrypt::                       Decrypting a ciphertext.
1707 * Verify::                        Verifying a signature.
1708 * Decrypt and Verify::            Decrypting a signed ciphertext.
1709 * Sign::                          Creating a signature.
1710 * Encrypt::                       Encrypting a plaintext.
1711 * Detailed Results::              How to obtain more info about the operation.
1712 @end menu
1713
1714
1715 @node Decrypt
1716 @subsection Decrypt
1717 @cindex decryption
1718 @cindex cryptographic operation, decryption
1719
1720 @deftypefun GpgmeError gpgme_op_decrypt (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
1721 The function @code{gpgme_op_decrypt} decrypts the ciphertext in the
1722 data object @var{cipher} and stores it into the data object
1723 @var{plain}.
1724
1725 The function returns @code{GPGME_No_Error} if the ciphertext could be
1726 decrypted successfully, @code{GPGME_Invalid_Value} if @var{ctx},
1727 @var{cipher} or @var{plain} is not a valid pointer,
1728 @code{GPGME_No_Data} if @var{cipher} does not contain any data to
1729 decrypt, @code{GPGME_Decryption_Failed} if @var{cipher} is not a valid
1730 cipher text, @code{GPGME_No_Passphrase} if the passphrase for the
1731 secret key could not be retrieved, and passes through any errors that
1732 are reported by the crypto engine support routines.
1733 @end deftypefun
1734
1735 @deftypefun GpgmeError gpgme_op_decrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
1736 The function @code{gpgme_op_decrypt_start} initiates a
1737 @code{gpgme_op_decrypt} operation.  It can be completed by calling
1738 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
1739
1740 The function returns @code{GPGME_No_Error} if the operation could be
1741 started successfully, and @code{GPGME_Invalid_Value} if @var{cipher}
1742 or @var{plain} is not a valid pointer.
1743 @end deftypefun
1744
1745
1746 @node Verify
1747 @subsection Verify
1748 @cindex verification
1749 @cindex signature, verification
1750 @cindex cryptographic operation, verification
1751 @cindex cryptographic operation, signature check
1752 @cindex signature, status
1753
1754 @deftp {Data type} {enum GpgmeSigStat}
1755 @tindex GpgmeSigStat
1756 The @code{GpgmeSigStat} type holds the result of a signature check, or
1757 the combined result of all signatures.  The following results are
1758 possible:
1759
1760 @table @code
1761 @item GPGME_SIG_STAT_NONE
1762 This status should not occur in normal operation.
1763
1764 @item GPGME_SIG_STAT_GOOD
1765 This status indicates that the signature is valid.  For the combined
1766 result this status means that all signatures are valid.
1767
1768 @item GPGME_SIG_STAT_BAD
1769 This status indicates that the signature is invalid.  For the combined
1770 result this status means that all signatures are invalid.
1771
1772 @item GPGME_SIG_STAT_NOKEY
1773 This status indicates that the signature could not be verified due to
1774 a missing key.  For the combined result this status means that all
1775 signatures could not be checked due to missing keys.
1776
1777 @item GPGME_SIG_STAT_NOSIG
1778 This status indicates that the signature data provided was not a real
1779 signature.
1780
1781 @item GPGME_SIG_STAT_ERROR
1782 This status indicates that there was some other error which prevented
1783 the signature verification.
1784
1785 @item GPGME_SIG_STAT_DIFF
1786 For the combined result this status means that at least two signatures
1787 have a different status.  You can get each key's status with
1788 @code{gpgme_get_sig_status}.
1789 @end table
1790 @end deftp
1791
1792 @deftypefun GpgmeError gpgme_op_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{sig}}, @w{GpgmeData @var{plain}}, @w{GpgmeSigStat *@var{r_stat}})
1793 The function @code{gpgme_op_verify} verifies that the detached
1794 signature in the data object @var{sig} is a valid signature for the
1795 plaintext in the data object @var{plain}.
1796
1797 The combined status of all signatures is returned in @var{r_stat}.
1798 The results of the individual signature verifications can be retrieved
1799 with @code{gpgme_get_sig_status} and @code{gpgme_get_sig_key}.
1800
1801 The function returns @code{GPGME_No_Error} if the operation could be
1802 completed successfully, @code{GPGME_Invalid_Value} if @var{ctx},
1803 @var{sig}, @var{plain} or @var{r_stat} is not a valid pointer,
1804 @code{GPGME_No_Data} if @var{sig} or @var{plain} does not contain any
1805 data to verify, and passes through any errors that are reported by the
1806 crypto engine support routines.
1807 @end deftypefun
1808
1809 @deftypefun GpgmeError gpgme_op_verify_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{sig}}, @w{GpgmeData @var{plain}})
1810 The function @code{gpgme_op_verify_start} initiates a
1811 @code{gpgme_op_verify} operation.  It can be completed by calling
1812 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
1813
1814 The function returns @code{GPGME_No_Error} if the operation could be
1815 started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
1816 @var{sig}, @var{plain} or @var{r_stat} is not a valid pointer, and
1817 @code{GPGME_No_Data} if @var{sig} or @var{plain} does not contain any
1818 data to verify.
1819 @end deftypefun
1820
1821 @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}})
1822 The function @code{gpgme_get_sig_status} receives information about a
1823 signature after the @code{gpgme_op_verify} or
1824 @code{gpgme_op_verify_decrypt} operation.  A single detached signature
1825 can contain signatures by more than one key.  The @var{idx} specifies
1826 which signature's information should be retrieved, starting from
1827 @var{0}.
1828
1829 The status of the signature will be returned in @var{r_stat} if it is
1830 not @code{NULL}.  The creation time stamp of the signature will be
1831 returned in @var{r_created} if it is not @var{NULL}.
1832
1833 The function returns a statically allocated string that contains the
1834 fingerprint of the key which signed the plaintext, or @code{NULL} if
1835 @var{ctx} is not a valid pointer, the operation is still pending, or
1836 no verification could be performed.
1837 @end deftypefun
1838
1839 @deftypefun {const char *} gpgme_get_sig_key (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeSigKey *@var{r_stat}})
1840 The function @code{gpgme_get_sig_status} receives a @code{GpgmeKey}
1841 object for the key which was used to verify the signature after the
1842 @code{gpgme_op_verify} or @code{gpgme_op_verify_decrypt} operation.  A
1843 single detached signature can contain signatures by more than one key.
1844 The @var{idx} specifies which signature's information should be
1845 retrieved, starting from @var{0}.  The key will have on reference for
1846 the user.
1847
1848 The function is a convenient way to retrieve the keys belonging to the
1849 fingerprints returned by @code{gpgme_get_sig_status}.
1850
1851 The function returns @code{GPGME_No_Error} if the key could be
1852 returned, @code{GPGME_Invalid_Value} if @var{r_key} is not a valid
1853 pointer, @code{GPGME_Invalid_Key} if the fingerprint is not valid,
1854 @code{GPGME_EOF} if @var{idx} is too large, or some other error value
1855 if a problem occurred requesting the key.
1856 @end deftypefun
1857
1858 @deftypefun {char *} gpgme_get_notation (@w{GpgmeCtx @var{ctx}})
1859 The function @code{gpgme_get_notation} can be used to retrieve
1860 notation data from the last signature check in the context @var{ctx}.
1861
1862 If there is notation data available from the last signature check,
1863 this function may be used to return this notation data as a string.
1864 The string is an XML representation of that data embedded in a
1865 <notation> container.  The user has to release the string with
1866 @code{free}.
1867
1868 The function returns a string if the notation data is available or
1869 @code{NULL} if there is no such data available.
1870 @end deftypefun
1871
1872
1873 @node Decrypt and Verify
1874 @subsection Decrypt and Verify
1875 @cindex decryption and verification
1876 @cindex verification and decryption
1877 @cindex signature check
1878 @cindex cryptographic operation, decryption and verification
1879
1880 @deftypefun GpgmeError gpgme_op_decrypt_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}}, @w{GpgmeSigStat *@var{r_stat}})
1881 The function @code{gpgme_op_decrypt_verify} decrypts the ciphertext in
1882 the data object @var{cipher} and stores it into the data object
1883 @var{plain}.  If @var{cipher} contains signatures, they will be
1884 verified and their combined status will be returned in @var{r_stat}.
1885
1886 After the operation completed, @code{gpgme_op_get_sig_status} and
1887 @code{gpgme_op_get_sig_key} can be used to retrieve more information
1888 about the signatures.
1889
1890 The function returns @code{GPGME_No_Error} if the ciphertext could be
1891 decrypted successfully, @code{GPGME_Invalid_Value} if @var{ctx},
1892 @var{cipher}, @var{plain} or @var{r_stat} is not a valid pointer,
1893 @code{GPGME_No_Data} if @var{cipher} does not contain any data to
1894 decrypt, @code{GPGME_Decryption_Failed} if @var{cipher} is not a valid
1895 cipher text, @code{GPGME_No_Passphrase} if the passphrase for the
1896 secret key could not be retrieved, and passes through any errors that
1897 are reported by the crypto engine support routines.
1898 @end deftypefun
1899
1900 @deftypefun GpgmeError gpgme_op_decrypt_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
1901 The function @code{gpgme_op_decrypt_verify_start} initiates a
1902 @code{gpgme_op_decrypt_verify} operation.  It can be completed by
1903 calling @code{gpgme_wait} on the context.  @xref{Waiting For
1904 Completion}.
1905
1906 The function returns @code{GPGME_No_Error} if the operation could be
1907 started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
1908 @var{cipher}, @var{plain} or @var{r_stat} is not a valid pointer, and
1909 @code{GPGME_No_Data} if @var{cipher} does not contain any data to
1910 decrypt.
1911 @end deftypefun
1912
1913
1914 @node Sign
1915 @subsection Sign
1916 @cindex signature, creation
1917 @cindex sign
1918 @cindex cryptographic operation, signing
1919
1920 A signature can contain signatures by one or more keys.  The set of
1921 keys used to create a signatures is contained in a context, and is
1922 applied to all following signing operations in this context (until the
1923 set is changed).
1924
1925 @menu
1926 * Selecting Signers::             How to choose the keys to sign with.
1927 * Creating a Signature::          How to create a signature.
1928 @end menu
1929
1930
1931 @node Selecting Signers
1932 @subsubsection Selecting Signers
1933 @cindex signature, selecting signers
1934 @cindex signers, selecting
1935
1936 @deftypefun void gpgme_signers_clear (@w{GpgmeCtx @var{ctx}})
1937 The function @code{gpgme_signers_clear} releases a reference for each
1938 key on the signers list and removes the list of signers from the
1939 context @var{ctx}.
1940
1941 Every context starts with an empty list.
1942 @end deftypefun
1943
1944 @deftypefun GpgmeError gpgme_signers_add (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}})
1945 The function @code{gpgme_signers_add} adds the key @var{key} to the
1946 list of signers in the context @var{ctx}.
1947
1948 One reference for the key is consumed.
1949 @end deftypefun
1950
1951 @deftypefun GpgmeKey gpgme_signers_enum (@w{const GpgmeCtx @var{ctx}}, @w{int @var{seq}})
1952 The function @code{gpgme_signers_enum} returns the @var{seq}th key in
1953 the list of signers in the context @var{ctx}.  An additional reference
1954 is acquired for the user.
1955
1956 If @var{seq} is out of range, @code{NULL} is returned.
1957 @end deftypefun
1958
1959
1960 @node Creating a Signature
1961 @subsubsection Creating a Signature
1962
1963 @deftp {Data type} {enum GpgmeSigMode}
1964 @tindex GpgmeSigMode
1965 The @code{GpgmeSigMode} type is used to specify the desired type of a
1966 signature.  The following modes are available:
1967
1968 @table @code
1969 @item GPGME_SIG_MODE_NORMAL
1970 A normal signature is made, the output includes the plaintext and the
1971 signature.
1972
1973 @item GPGME_SIG_MODE_DETACH
1974 A detached signature is made.
1975
1976 @item GPGME_SIG_MODE_CLEAR
1977 A clear text signature is made.  The @acronym{ASCII} armor and text
1978 mode settings of the context are ignored.
1979 @end table
1980 @end deftp
1981
1982 @deftypefun GpgmeError gpgme_op_sign (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{sig}}, @w{GpgmeSigMode @var{mode}})
1983 The function @code{gpgme_op_sign} creates a signature for the text in
1984 the data object @var{plain} and returns it in the data object
1985 @var{sig}.  The type of the signature created is determined by the
1986 @acronym{ASCII} armor and text mode attributes set for the context
1987 @var{ctx} and the requested signature mode @var{mode}.
1988
1989 More information about the signatures is available with
1990 @code{gpgme_get_op_info}.  @xref{Detailed Results}.
1991
1992 The function returns @code{GPGME_No_Error} if the signature could be
1993 created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
1994 @var{plain} or @var{sig} is not a valid pointer, @code{GPGME_No_Data}
1995 if the signature could not be created, @code{GPGME_No_Passphrase} if
1996 the passphrase for the secret key could not be retrieved, and passes
1997 through any errors that are reported by the crypto engine support
1998 routines.
1999 @end deftypefun
2000
2001 @deftypefun GpgmeError gpgme_op_sign (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{sig}}, @w{GpgmeSigMode @var{mode}})
2002 The function @code{gpgme_op_sign_start} initiates a
2003 @code{gpgme_op_sign} operation.  It can be completed by calling
2004 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
2005
2006 The function returns @code{GPGME_No_Error} if the operation could be
2007 started successfully, and @code{GPGME_Invalid_Value} if @var{ctx},
2008 @var{plain} or @var{sig} is not a valid pointer.
2009 @end deftypefun
2010
2011
2012 @node Encrypt
2013 @subsection Encrypt
2014 @cindex encryption
2015 @cindex cryptographic operation, encryption
2016
2017 One plaintext can be encrypted for several recipients at the same
2018 time.  The list of recipients is created independently of any context,
2019 and then passed to the encryption operation.
2020
2021 @menu
2022 * Selecting Recipients::          How to choose the recipients.
2023 * Encrypting a Plaintext::        How to encrypt a plaintext.
2024 @end menu
2025
2026
2027 @node Selecting Recipients
2028 @subsubsection Selecting Recipients
2029 @cindex encryption, selecting recipients
2030 @cindex recipients
2031
2032 @deftp {Data type} GpgmeRecipients
2033 The @code{GpgmeRecipients} type is a handle for a set of recipients
2034 that can be used in an encryption process.
2035 @end deftp
2036
2037 @deftypefun GpgmeError gpgme_recipients_new (@w{GpgmeRecipients *@var{r_rset}})
2038 The function @code{gpgme_recipients_new} creates a new, empty set of
2039 recipients and returns a handle for it in @var{r_rset}.
2040
2041 The function returns @code{GPGME_No_Error} if the recipient set could
2042 be created successfully, and @code{GPGME_Out_Of_Core} if not enough
2043 memory was available.
2044 @end deftypefun
2045
2046 @deftypefun void gpgme_recipients_release (@w{GpgmeRecipients @var{rset}})
2047 The function @code{gpgme_recipients_release} destroys the set of
2048 recipients @var{rset} and releases all associated resources.
2049 @end deftypefun
2050
2051 @deftypefun GpgmeError gpgme_recipients_add_name (@w{GpgmeRecipients @var{rset}}, @w{const char *@var{name}})
2052 The function @code{gpgme_recipients_add_name} adds the recipient
2053 @var{name} to the set of recipients @var{rset}.  This is equivalent to
2054 @code{gpgme_recipients_add_name_with_validity} with a validity of
2055 @code{GPGME_VALIDITY_UNKNOWN}.
2056
2057 The function returns @code{GPGME_No_Error} if the recipient was added
2058 successfully, @code{GPGME_Invalid_Value} if @var{rset} or @var{name}
2059 is not a valid pointer, and @code{GPGME_Out_Of_Core} if not enough
2060 memory is available.
2061 @end deftypefun
2062
2063 @deftypefun GpgmeError gpgme_recipients_add_name_with_validity (@w{GpgmeRecipients @var{rset}}, @w{const char *@var{name}}, @w{GpgmeValidity @var{val}})
2064 The function @code{gpgme_recipients_add_name_with_validity} adds the
2065 recipient @var{name} with the validity @var{val} to the set of
2066 recipients @var{rset}.  If the validity is not known, the function
2067 @code{gpgme_recipients_add_name} can be used.
2068 @xref{Information About Keys}, for the possible values for @var{val}.
2069
2070 The function returns @code{GPGME_No_Error} if the recipient was added
2071 successfully, @code{GPGME_Invalid_Value} if @var{rset} or @var{name}
2072 is not a valid pointer, and @code{GPGME_Out_Of_Core} if not enough
2073 memory is available.
2074 @end deftypefun
2075
2076 @deftypefun {unsigned int} gpgme_recipients_count (@w{const @var{GpgmeRecipients rset}})
2077 The function @code{gpgme_recipients_count} returns the number of
2078 recipients in the set @var{rset}.
2079 @end deftypefun
2080
2081 @deftypefun GpgmeError gpgme_recipients_enum_open (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}})
2082 The function @code{gpgme_recipients_enum_open} creates a new iterator
2083 @var{iter} that can be used to walk through the set of recipients in
2084 @var{rset}, using @code{gpgme_recipients_enum_read}.
2085
2086 If the iterator is not needed anymore, it can be closed with
2087 @code{gpgme_recipients_enum_close}.
2088
2089 The function returns @code{GPGME_No_Error} if the enumerator was
2090 successfully created and @code{GPGME_Invalid_Value} if @var{rset} or
2091 @var{iter} is not a valid pointer.
2092 @end deftypefun
2093
2094 @deftypefun {const char *} gpgme_recipients_enum_read (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}})
2095 The function @code{gpgme_recipients_enum_read} returns a string
2096 containing the name of the next recipient in the set @var{rset} for
2097 the iterator @var{iter}.  The string is valid as long as @var{rset} is
2098 valid or the function is called the next time with the same recipient
2099 set and iterator, whatever is earlier.
2100 @end deftypefun
2101
2102 @deftypefun GpgmeError gpgme_recipients_enum_close (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}})
2103 The function @code{gpgme_recipients_enum_close} releases the iterator
2104 @var{iter} for the recipient set @var{rset}.
2105 @end deftypefun
2106
2107
2108 @node Encrypting a Plaintext
2109 @subsubsection Encrypting a Plaintext
2110
2111 @deftypefun GpgmeError gpgme_op_encrypt (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
2112 The function @code{gpgme_op_crypt} encrypts the plaintext in the data
2113 object @var{plain} for the recipients @var{rset} and stores the
2114 ciphertext in the data object @var{cipher}.  The type of the
2115 ciphertext created is determined by the @acronym{ASCII} armor and text
2116 mode attributes set for the context @var{ctx}.
2117
2118 More information about the encrypted text is available with
2119 @code{gpgme_get_op_info}.  @xref{Detailed Results}.
2120
2121 The function returns @code{GPGME_No_Error} if the ciphertext could be
2122 created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2123 @var{rset}, @var{plain} or @var{cipher} is not a valid pointer,
2124 @code{GPGME_No_Recipient} if @var{rset} does not contain any
2125 valid recipients, @code{GPGME_No_Passphrase} if the passphrase for the
2126 secret key could not be retrieved, and passes through any errors that
2127 are reported by the crypto engine support routines.
2128 @end deftypefun
2129
2130 @deftypefun GpgmeError gpgme_op_encrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
2131 The function @code{gpgme_op_encrypt_start} initiates a
2132 @code{gpgme_op_encrypt} operation.  It can be completed by calling
2133 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
2134
2135 The function returns @code{GPGME_No_Error} if the operation could be
2136 started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2137 @var{rset}, @var{plain} or @var{cipher} is not a valid pointer, and
2138 @code{GPGME_No_Recipient} if @var{rset} does not contain any valid
2139 recipients.
2140 @end deftypefun
2141
2142
2143 @node Detailed Results
2144 @subsection Detailed Results
2145 @cindex cryptographic operation, detailed results
2146
2147 @deftypefun {char *} gpgme_get_op_info (@w{GpgmeCtx @var{ctx}}, @w{int @var{reserved}})
2148 The function @code{gpgme_get_op_info} retrieves more information about
2149 the last crypto operation.
2150
2151 The function returns a string in the XML format.  The user has to
2152 release the string with @code{free}.
2153
2154 Here is a sample of the information that might be returned:
2155 @example
2156 <literal>
2157 <![CDATA[
2158 <GnupgOperationInfo>
2159   <signature>
2160     <detached/> <!-- or cleartext or standard -->
2161     <algo>17</algo>
2162     <hashalgo>2</hashalgo>
2163     <micalg>pgp-sha1</micalg>
2164     <sigclass>01</sigclass>
2165     <created>9222222</created>
2166     <fpr>121212121212121212</fpr>
2167   </signature>
2168 </GnupgOperationInfo>
2169 ]]>
2170 </literal>
2171 @end example
2172
2173 Currently, the only operations that return additional information are
2174 encrypt and sign.  @xref{Encrypt}, @xref{Sign}.
2175
2176 The function returns a string or @code{NULL} if no such data is
2177 available.
2178 @end deftypefun
2179
2180
2181 @node Run Control
2182 @section Run Control
2183 @cindex run control
2184 @cindex cryptographic operation, running
2185
2186 Some basic support for running operations asynchronously is available
2187 in @acronym{GPGME}.  You can use it to set up a context completely up
2188 to initiating the desired operation, but delay performing it to a
2189 later point.
2190
2191 @menu
2192 * Waiting For Completion::        Waiting until an operation is completed.
2193 * Cancelling an Operation::       Interrupting a running operation.
2194 * Hooking Up Into Idle Time::     Doing something when nothing has to be done.
2195 @end menu
2196
2197
2198 @node Waiting For Completion
2199 @subsection Waiting For Completion
2200 @cindex cryptographic operation, wait for
2201 @cindex wait for completion
2202
2203 @deftypefun GpgmeCtx gpgme_wait (@w{GpgmeCtx @var{ctx}}, @w{int @var{hang}})
2204 The function @code{gpgme_wait} does continue the pending operation
2205 within the context @var{ctx}.  In particular, it ensures the data
2206 exchange between @acronym{GPGME} and the crypto backend and watches
2207 over the run time status of the backend process.
2208
2209 If @var{hang} is true, the function does not return until the
2210 operation is completed or cancelled.  Otherwise the function will not
2211 block for a long time.
2212
2213 The function returns @var{ctx}.
2214 @end deftypefun
2215
2216
2217 @node Cancelling an Operation
2218 @subsection Cancelling an Operation
2219 @cindex cancellation
2220 @cindex cryptographic operation, cancel
2221
2222 @deftypefun void gpgme_cancel (@w{GpgmeCtx @var{ctx}})
2223 The function @code{gpgme_cancel} tries to cancel the pending
2224 operation.  The function @code{gpgme_wait} might notice the
2225 cancellation flag and return.  It is currently not guaranteed to work
2226 under all circumstances.  It's current primary purpose is to prevent
2227 asking for a passphrase again in the passphrase callback.
2228 @end deftypefun
2229
2230
2231 @node Hooking Up Into Idle Time
2232 @subsection Hooking Up Into Idle Time
2233 @cindex idle time
2234 @cindex idle function
2235
2236 @deftp {Data type} {void (*GpgmeIdleFunc) (void)}
2237 @tindex GpgmeIdleFunc
2238 The @code{GpgmeIdleFunc} type is the type of functions usable as
2239 an idle function that can be registered with @code{gpgme_register_idle}.
2240 @end deftp
2241
2242 @deftypefun GpgmeIdleFunc gpgme_register_idle (@w{GpgmeIdleFunc @var{idle}})
2243 The function @code{gpgme_register_idle} can be used to register
2244 @var{idle} as the idle function.
2245
2246 @var{idle} will be called whenever @acronym{GPGME} thinks that it is
2247 idle and time can better be spent elsewhere.  Setting @var{idle} to
2248 @code{NULL} disables use of the idle function (this is the default).
2249
2250 The function returns the old idle function, or @code{NULL} if none was
2251 registered yet.
2252 @end deftypefun
2253
2254
2255 @include gpl.texi
2256
2257
2258 @include fdl.texi
2259
2260
2261 @node Concept Index
2262 @unnumbered Concept Index
2263
2264 @printindex cp
2265
2266
2267 @node Function and Data Index
2268 @unnumbered Function and Data Index
2269
2270 @printindex fn
2271
2272
2273 @summarycontents
2274 @contents
2275 @bye
2276
2277 @c  LocalWords:  GPGME gpgme