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