2002-01-22 Marcus Brinkmann <marcus@g10code.de>
[gpgme.git] / doc / gpgme.texi
1 \input texinfo                  @c -*- Texinfo -*-
2 @setfilename gpgme.info
3 @settitle The `GnuPG Made Easy' Reference Manual
4
5 @c TODO:
6 @c char *gpgme_get_op_info (GpgmeCtx c, int reserved);
7 @c void       gpgme_cancel (GpgmeCtx c);
8 @c GpgmeCtx   gpgme_wait (GpgmeCtx c, int hang);
9 @c char *gpgme_get_notation (GpgmeCtx c);
10 @c void        gpgme_register_idle (void (*fnc)(void));
11
12 @dircategory GNU Libraries
13 @direntry
14 * @acronym{GPGME}: (gpgme)           Adding support for cryptography to your program.
15 @end direntry
16
17 @include version.texi
18
19 @c Unify some of the indices.
20 @syncodeindex tp fn
21 @syncodeindex pg fn
22
23 @ifinfo
24 This file documents the @acronym{GPGME} library.
25
26 This is Edition @value{EDITION}, last updated @value{UPDATED}, of
27 @cite{The `GnuPG Made Easy' Reference Manual}, for Version
28 @value{VERSION}.
29
30 Copyright @copyright{} 2002 g10 Code GmbH.
31
32 Permission is granted to copy, distribute and/or modify this document
33 under the terms of the GNU Free Documentation License, Version 1.1 or
34 any later version published by the Free Software Foundation; with the
35 Invariant Sections being ``Free Software Needs Free Documentation'' and
36 ``GNU Lesser General Public License'', the Front-Cover texts being (a)
37 (see below), and with the Back-Cover Texts being (b) (see below).  A
38 copy of the license is included in the section entitled ``GNU Free
39 Documentation License''.
40
41 @end ifinfo
42
43 @iftex
44 @shorttitlepage The `GnuPG Made Easy' Reference Manual
45 @end iftex
46 @titlepage
47 @center @titlefont{The `GnuPG Made Easy'}
48 @sp 1
49 @center @titlefont{Reference Manual}
50 @sp 6
51 @center Edition @value{EDITION}
52 @sp 1
53 @center last updated @value{UPDATED}
54 @sp 1
55 @center for version @value{VERSION}
56 @page
57 @vskip 0pt plus 1filll
58 Copyright @copyright{} 2001 g10 Code GmbH.
59
60 Permission is granted to copy, distribute and/or modify this document
61 under the terms of the GNU Free Documentation License, Version 1.1 or
62 any later version published by the Free Software Foundation; with the
63 Invariant Sections being ``Free Software Needs Free Documentation'' and
64 ``GNU Lesser General Public License'', the Front-Cover texts being (a)
65 (see below), and with the Back-Cover Texts being (b) (see below).  A
66 copy of the license is included in the section entitled ``GNU Free
67 Documentation License''.
68 @end titlepage
69 @page
70
71 @ifnottex
72 @node Top
73 @top Main Menu
74 This is Edition @value{EDITION}, last updated @value{UPDATED}, of
75 @cite{The `GnuPG Made Easy' Reference Manual}, for Version
76 @value{VERSION} of the @acronym{GPGME} library.
77 @end ifnottex
78
79 @menu
80 * Introduction::                  How to use this manual.
81 * Preperation::                   What you should do before using the library.
82 * Protocols and Engines::         Supported crypto protocols.
83 * Error Handling::                Error numbers and their meanings.
84 * Exchanging Data::               Passing data to and from @acronym{GPGME}.
85 * Contexts::                      Handling @acronym{GPGME} contexts.
86
87 Appendices
88
89 * Copying::                       The GNU General Public License says how you
90                                   can copy and share `GnuPG Made Easy'.
91 * Free Documentation License::    This manual is under the GNU Free
92                                   Documentation License.
93
94 Indices
95
96 * Concept Index::                 Index of concepts and programs.
97 * Function and Data Index::       Index of functions, variables and data types.
98
99
100 @detailmenu
101  --- The Detailed Node Listing ---
102
103 Introduction
104
105 * Getting Started::               Purpose of the manual, and how to use it.
106 * Features::                      Reasons to install and use @acronym{GPGME}.
107 * Overview::                      Basic architecture of the @acronym{GPGME} library.
108
109 Preperation
110
111 * Header::                        What header file you need to include.
112 * Building the source::           Compiler options to be used.
113 * Library version check::         Getting and verifying the library version.
114
115 Protocols and Engines
116
117 * Engine version check::          Verifying the engine version.
118 * Engine information::            Obtaining more information about the engines.
119 * OpenPGP::                       Support for the OpenPGP protocol.
120 * Cryptographic Message Syntax::  Support for the CMS.
121
122 Error Handling
123
124 * Error values::                  A list of all error values used.
125 * Error strings::                 How to get a descriptive string from a value.
126
127 Exchanging Data 
128
129 * Creating data buffers::         Creating new data buffers.
130 * Destroying data buffers::       Releasing data buffers.
131 * Manipulating data buffers::     Operations on data buffers.
132
133 Contexts
134
135 * Creating contexts::             Creating new @acronym{GPGME} contexts.
136 * Destroying contexts::           Releasing @acronym{GPGME} contexts.
137 * Context attributes::            Setting properties of a context.
138 * Key Management::                Managing keys with @acronym{GPGME}.
139 * Trust Item Management::         Managing trust items with @acronym{GPGME}.
140 * Crypto Operations::             Using a context for cryptography.
141
142 Context attributes
143
144 * Protocol selection::            Selecting the protocol used by a context.
145 * @acronym{ASCII} armor::                   Requesting @acronym{ASCII} armored output.
146 * Text mode::                     Choosing canonical text mode.
147 * Key listing mode::              Selecting key listing mode.
148 * Passphrase callback::           Getting the passphrase from the user.
149 * Progress meter callback::       Being informed about the progress.
150
151 Key Management
152
153 * Listing keys::                  Browsing the list of available keys.
154 * Information about keys::        Requesting detailed information about keys.
155 * Manipulating keys::             Operations on keys.
156 * Generating keys::               Creating new key pairs.
157 * Exporting keys::                Retrieving key data from the key ring.
158 * Importing keys::                Adding keys to the keyring.
159 * Deleting keys::                 Removing keys from the keyring.
160
161 Trust Item Management
162
163 * Listing trust items::           Browsing the list of available trust items.
164 * Information about trust items:: Requesting detailed information about trust items.
165 * Manipulating trust items::      Operations on trust items.
166
167 Crypto Operations
168
169 * Decrypt::                       Decrypting a ciphertext.
170 * Verify::                        Verifying a signature.
171 * Decrypt and verify::            Decrypting a signed ciphertext.
172 * Sign::                          Creating a signature.
173 * Encrypt::                       Encrypting a plaintext.
174
175 Sign
176
177 * Selecting signers::             How to choose the keys to sign with.
178 * Creating a signature::          How to create a signature.
179
180 Encrypt
181
182 * Selecting recipients::          How to choose the recipients.
183 * Encrypting a plaintext::        How to encrypt a plaintext.
184
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 Cryptograhic 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 posess 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 @strong{Caution:} The @acronym{GPGME} library is not thread-safe.  It
281 will be to some extent in the future, but currently great care has to
282 be taken if @acronym{GPGME} is used in a multi-threaded environment.
283
284
285 @node Preperation
286 @chapter Preperation
287
288 To use @acronym{GPGME}, you have to perform some changes to your
289 sources and the build system.  The necessary changes are small and
290 explained in the following sections.  At the end of this chapter, it
291 is described how the library is initialized, and how the requirements
292 of the library are verified.
293
294 @menu
295 * Header::                        What header file you need to include.
296 * Building the source::           Compiler options to be used.
297 * Library version check::         Getting and verifying the library version.
298 @end menu
299
300
301 @node Header
302 @section Header
303
304 All interfaces (data types and functions) of the library are defined
305 in the header file `gpgme.h'.  You must include this in all programs
306 using the library, either directly or through some other header file,
307 like this:
308
309 @example
310 #include <gpgme.h>
311 @end example
312
313 The name space of @acronym{GPGME} is @code{gpgme_*} for function
314 names, @code{Gpgme*} for data types and @code{GPGME_*} for other
315 symbols.
316
317
318 @node Building the source
319 @section Building the source
320
321 If you want to compile a source file including the `gpgme.h' header
322 file, you must make sure that the compiler can find it in the
323 directory hierarchy.  This is accomplished by adding the path to the
324 directory in which the header file is located to the compilers include
325 file search path (via the @option{-I} option).
326
327 However, the path to the include file is determined at the time the
328 source is configured.  To solve this problem, gpgme ships with a small
329 helper program @command{gpgme-config} that knows about the path to the
330 include file and other configuration options.  The options that need
331 to be added to the compiler invocation at compile time are output by
332 the @option{--cflags} option to @command{gpgme-config}.  The following
333 example shows how it can be used at the command line:
334
335 @example
336 gcc -c foo.c `gpgme-config --cflags`
337 @end example
338
339 Adding the output of @samp{gpgme-config --cflags} to the compilers
340 command line will ensure that the compiler can find the @acronym{GPGME} header
341 file.
342
343 A similar problem occurs when linking the program with the library.
344 Again, the compiler has to find the library files.  For this to work,
345 the path to the library files has to be added to the library search
346 path (via the @option{-L} option).  For this, the option
347 @option{--libs} to @command{gpgme-config} can be used.  For
348 convenience, this option also outputs all other options that are
349 required to link the program with @acronym{GPGME} (in particular, the
350 @samp{-lgpgme} option).  The example shows how to link @file{foo.o}
351 with the @acronym{GPGME} library to a program @command{foo}.
352
353 @example
354 gcc -o foo foo.o `gpgme-config --libs`
355 @end example
356
357 Of course you can also combine both examples to a single command by
358 specifying both options to @command{gpgme-config}:
359
360 @example
361 gcc -o foo foo.c `gpgme-config --cflags --libs`
362 @end example
363
364
365 @node Library version check
366 @section Library version check
367
368 @deftypefun {const char *} gpgme_check_version (@w{const char *@var{required_version}})
369 The function @code{gpgme_check_version} has three purposes.  It can be
370 used to retrieve the version number of the library.  In addition it
371 can verify that the version number is higher than a certain required
372 version number.  In either case, the function initializes some
373 sub-systems, and for this reason alone it must be invoked early in
374 your program, before you make use of the other functions in
375 @acronym{GPGME}.
376
377 If @var{required_version} is @code{NULL}, the function returns a
378 pointer to a statically allocated string containing the version number
379 of the library.
380
381 If @var{required_version} is not @code{NULL}, it should point to a
382 string containing a version number, and the function checks that the
383 version of the library is at least as high as the version number
384 provided.  In this case, the function returns a pointer to a
385 statically allocated string containing the version number of the
386 library.  If @var{REQUIRED_VERSION} is not a valid version number, or
387 if the version requirement is not met, the function returns
388 @code{NULL}.
389
390 If you use a version of a library that is backwards compatible with
391 older releases, but contains additional interfaces which your program
392 uses, this function provides a run-time check if the necessary
393 features are provided by the installed version of the library.
394 @end deftypefun
395
396
397 @node Protocols and Engines
398 @chapter Protocols and Engines
399
400 @acronym{GPGME} supports several cryptographic protocols, however, it
401 does not implement them.  Rather it uses backends (also called
402 engines) which implement the protocol.  @acronym{GPGME} uses
403 inter-process communication to pass data back and forth between the
404 application and the backend, but the details of the communication
405 protocol and invocation of the backends is completely hidden by the
406 interface.  All complexity is handled by @acronym{GPGME}.  Where an
407 exchange of information between the application and the backend is
408 necessary, @acronym{GPGME} provides the necessary callback function
409 hooks and further interfaces.
410
411 @deftp {Data type} {enum GpgmeProtocol}
412 The @code{GpgmeProtocol} type specifies the set of possible protocol
413 values that are supported by @acronym{GPGME}.  The following protocols
414 are supported:
415
416 @table @code
417 @item GPGME_PROTOCOL_OpenPGP
418 This specifies the OpenPGP protocol.
419 @item GPGME_PROTOCOL_CMS
420 This specifies the Cryptographic Message Syntax.
421 @end table
422 @end deftp
423
424 @menu
425 * Engine version check::          Verifying the engine version.
426 * Engine information::            Obtaining more information about the engines.
427 * OpenPGP::                       Support for the OpenPGP protocol.
428 * Cryptographic Message Syntax::  Support for the CMS.
429 @end menu
430
431
432 @node Engine version check
433 @section Engine version check
434
435 @deftypefun GpgmeError gpgme_engine_check_version (@w{GpgmeProtocol @var{protocol}})
436 The function @code{gpgme_engine_check_version} verifies that the
437 engine implementing the protocol @var{PROTOCOL} is installed in the
438 expected path and meets the version requirement of @acronym{GPGME}.
439
440 This function returns @code{GPGME_No_Error} if the engine is available
441 and @code{GPGME_Invalid_Engine} if it is not.
442 @end deftypefun
443
444 @deftypefun GpgmeError gpgme_check_engine (void)
445 The function @code{gpgme_check_engine} is equivalent to
446
447 @example
448 gpgme_engine_check_version (GPGME_PROTOCOL_OpenPGP);
449 @end example
450
451 This function is deprecated and provided for backwards compatibility
452 only.  It is obsoleted by @code{gpgme_engine_check_version}.
453 @end deftypefun
454
455
456 @node Engine information
457 @section Engine information
458
459 @deftypefun {const char *} gpgme_get_engine_info (void)
460 The function @code{gpgme_get_engine_info} returns an @acronym{XML}
461 string containing information about the available protocols and the
462 engine which implement them.  The following information is returned
463 for each engine:
464
465 @table @samp
466 @item <protocol>
467 The name of the protocol.
468 @item <version>
469 The version of the engine.
470 @item <path>
471 The path to the engine binary.
472 @end table
473
474 A string is always returned.  If an error occurs, the string will
475 contain an @samp{<error>} tag with a description of the failure.
476 @end deftypefun
477
478 Here is the example output of what @code{gpgme_get_engine_info} might
479 return on your system:
480
481 @example
482 <EngineInfo>
483  <engine>
484   <protocol>OpenPGP</protocol>
485   <version>1.0.6</version>
486   <path>/usr/bin/gpg</path>
487  </engine>
488  <engine>
489   <protocol>CMS</protocol>
490   <version>0.0.0</version>
491   <path>/usr/bin/gpgsm</path>
492  </engine>
493 </EngineInfo>
494 @end example
495
496
497 @node OpenPGP
498 @section OpenPGP
499
500 OpenPGP is implemented by GnuPG, the @acronym{GNU} Privacy Guard.
501 This is the first protocol that was supported by @acronym{GPGME}.
502
503 The OpenPGP protocol is specified by @code{GPGME_PROTOCOL_OpenPGP}.
504
505
506 @node Cryptographic Message Syntax
507 @section Cryptographic Message Syntax
508
509 @acronym{CMS} is implemented by GpgSM, the S/MIME implementation for
510 GnuPG.
511
512 The @acronym{CMS} protocol is specified by @code{GPGME_PROTOCOL_CMS}.
513
514
515 @node Error Handling
516 @chapter Error Handling
517
518 Many functions in @acronym{GPGME} can return an error if they fail.
519 For this reason, the application should always catch the error
520 condition and take appropriate measures, for example by releasing the
521 resources and passing the error up to the caller, or by displaying a
522 descriptive message to the user and cancelling the operation.
523
524 Some error values do not indicate a system error or an error in the
525 operation, but the result of an operation that failed properly.  For
526 example, if you try to decrypt a tempered message, the decryption will
527 fail.  Another error value actually means that the end of a data
528 buffer or list has been reached.  The following descriptions explain
529 what each error message means in general.  Some error values have
530 specific meanings if returned by a specific function.  Such cases are
531 described in the documentation of those functions.
532
533 @menu
534 * Error values::                  A list of all error values used.
535 * Error strings::                 How to get a descriptive string from a value.
536 @end menu
537
538
539 @node Error values
540 @section Error values
541
542 @deftp {Data type} {enum GpgmeError}
543 The @code{GpgmeError} type specifies the set of all error values that
544 are used by @acronym{GPGME}.  Possible values are:
545
546 @table @code
547 @item GPGME_EOF
548 This value indicates the end of a list, buffer or file.
549
550 @item GPGME_No_Error
551 This value indicates success.  The value of this error is @code{0}.
552
553 @item GPGME_General_Error
554 This value means that something went wrong, but either there is not
555 enough information about the problem to return a more useful error
556 value, or there is no seperate error value for this type of problem.
557
558 @item GPGME_Out_Of_Core
559 This value means that an out-of-memory condition occured.
560
561 @item GPGME_Invalid_Value
562 This value means that some user provided data was out of range.  This
563 can also refer to objects.  For example, if an empty @code{GpgmeData}
564 object was expected, but one containing data was provided, this error
565 value is returned.
566
567 @item GPGME_Busy
568 This value is returned if you try to start a new operation in a
569 context that is already busy with some earlier operation which was not
570 canceled or finished yet.
571
572 @item GPGME_No_Request
573 This value is in some sense the opposite of @code{GPGME_Busy}.  There
574 is no pending operation, but it is required for the function to
575 succeed.
576
577 @item GPGME_Exec_Error
578 This value means that an error occured when trying to spawn a child
579 process.
580
581 @item GPGME_Too_Many_Procs
582 This value means that there are too many active backend processes.
583
584 @item GPGME_Pipe_Error
585 This value means that the creation of a pipe failed.
586
587 @item GPGME_No_Recipients 
588 This value means that no recipients for a message have been set.
589
590 @item GPGME_No_Data
591 This value means that a @code{GpgmeData} object which was expected to
592 have content was found empty.
593
594 @item GPGME_Conflict
595 This value means that a conflict of some sort occured.
596
597 @item GPGME_Not_Implemented
598 This value indicates that the specific function (or operation) is not
599 implemented.  This error should never happen.  It can only occur if
600 you use certain values or configuration options which do not work,
601 but for which we think that they should work at some later time.
602
603 @item GPGME_Read_Error
604 This value means that an I/O read operation failed.
605
606 @item GPGME_Write_Error
607 This value means that an I/O write operation failed.
608
609 @item GPGME_Invalid_Type
610 This value means that a user provided object was of a wrong or
611 incompatible type.  Usually this refers to the type of a
612 @code{GpgmeData} object.
613
614 @item GPGME_Invalid_Mode
615 This value means that a @code{GpgmeData} object has an incorrect mode
616 of operation (for example, doesn't support output although it is
617 attempted to use it as an output buffer).
618
619 @item GPGME_File_Error
620 This value means that a file I/O operation failed.  The value of
621 @code{errno} contains the system error value.
622
623 @item GPGME_Decryption_Failed
624 This value indicates that a decryption operation was unsuccessful.
625
626 @item GPGME_No_Passphrase
627 This value means that the user did not provide a passphrase when
628 requested.
629
630 @item GPGME_Canceled
631 This value means that the operation was canceled.
632
633 @item GPGME_Invalid_Key
634 This value means that a key was invalid.
635
636 @item GPGME_Invalid_Engine
637 This value means that the engine that implements the desired protocol
638 is currently not available.  This can either be because the sources
639 were configured to exclude support for this engine, or because the
640 engine is not installed properly.
641 @end table
642 @end deftp
643
644
645 @node Error strings
646 @section Error strings
647
648 @deftypefun {const char *} gpgme_strerror (@w{GpgmeError @var{err}})
649 The function @code{gpgme_strerror} returns a pointer to a statically
650 allocated string containing a description of the error with the error
651 value @var{err}.  This string can be used to output a diagnostic
652 message to the user.
653 @end deftypefun
654
655
656 @node Exchanging Data
657 @chapter Exchanging Data
658
659 A lot of data has to be exchanged between the user and the crypto
660 engine, like plaintext messages, ciphertext, signatures and
661 information about the keys.  The technical details about exchanging
662 the data information are completely abstracted by @acronym{GPGME}.
663 The user provides and receives the data via @code{GpgmeData} objects,
664 regardless of the communication protocol between @acronym{GPGME} and
665 the crypto engine in use.
666
667 @deftp {Data type} {GpgmeData}
668 The @code{GpgmeData} type is a handle for a container for generic
669 data, which is used by @acronym{GPGME} to exchange data with the user.
670 @end deftp
671
672 @menu
673 * Creating data buffers::         Creating new data buffers.
674 * Destroying data buffers::       Releasing data buffers.
675 * Manipulating data buffers::     Operations on data buffers.
676 @end menu
677
678
679 @node Creating data buffers
680 @section Creating data buffers
681
682 @deftypefun GpgmeError gpgme_data_new (@w{GpgmeData *@var{dh}})
683 The function @code{gpgme_data_new} creates a new @code{GpgmeData}
684 object and returns a handle for it in @var{dh}.  The data object is
685 initially empty.
686
687 The function returns @code{GPGME_No_Error} if the data object was
688 successfully created, @code{GPGME_Invalid_Value} if @var{dh} is not a
689 valid pointer, and @code{GPGME_Out_Of_Core} if not enough memory is
690 available.
691 @end deftypefun
692
693 @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}})
694 The function @code{gpgme_data_new_from_mem} creates a new
695 @code{GpgmeData} object and fills it with @var{size} bytes starting
696 from @var{buffer}.
697
698 If @var{copy} is not zero, a private copy of the data is made.  If
699 @var{copy} is zero, the data is taken from the specified buffer as
700 needed, and the user has to ensure that the buffer remains valid for
701 the whole life span of the data object.
702
703 The function returns @code{GPGME_No_Error} if the data object was
704 successfully created, @code{GPGME_Invalid_Value} if @var{dh} or
705 @var{buffer} is not a valid pointer, and @code{GPGME_Out_Of_Core} if
706 not enough memory is available.
707 @end deftypefun
708
709 @deftypefun GpgmeError gpgme_data_new_from_file (@w{GpgmeData *@var{dh}}, @w{const char *@var{filename}}, @w{int @var{copy}})
710 The function @code{gpgme_data_new_from_file} creates a new
711 @code{GpgmeData} object and fills it with the content of the file
712 @var{filename}.
713
714 If @var{copy} is not zero, the whole file is read in at initialization
715 time and the file is not used anymore after that.  This is the only
716 mode supported currently.  Later, a value of zero for @var{copy} might
717 cause all reads to be delayed until the data is needed, but this is
718 not yet implemented.
719
720 The function returns @code{GPGME_No_Error} if the data object was
721 successfully created, @code{GPGME_Invalid_Value} if @var{dh} or
722 @var{filename} is not a valid pointer, @code{GPGME_File_Error} if an
723 I/O operation fails, @code{GPGME_Not_Implemented} if @var{code} is
724 zero, and @code{GPGME_Out_Of_Core} if not enough memory is available.
725 @end deftypefun
726
727 @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{off_t @var{length}})
728 The function @code{gpgme_data_new_from_filepart} creates a new
729 @code{GpgmeData} object and fills it with a part of the file specified
730 by @var{filename} or @var{fp}.
731
732 Exactly one of @var{filename} and @var{fp} must be non-zero, the other
733 must be zero.  The argument that is not zero specifies the file from
734 which @var{length} bytes are read into the data object, starting from
735 @var{offset}.
736
737 The function returns @code{GPGME_No_Error} if the data object was
738 successfully created, @code{GPGME_Invalid_Value} if @var{dh} and
739 exactly one of @var{filename} and @var{fp} is not a valid pointer,
740 @code{GPGME_File_Error} if an I/O operation fails, and
741 @code{GPGME_Out_Of_Core} if not enough memory is available.
742 @end deftypefun
743
744
745 @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}})
746 The function @code{gpgme_data_new_with_read_cb} creates a new
747 @code{GpgmeData} object and uses the callback function @var{readfunc}
748 to retrieve the data on demand.  As the callback function can supply
749 the data in any way it wants, this is the most flexible data type
750 @acronym{GPGME} provides.  However, it can not be used to write data.
751
752 The callback function receives @var{hook_value} as its first argument
753 whenever it is invoked.  It should return up to @var{count} bytes in
754 @var{buffer}, and return the number of bytes actually read in
755 @var{nread}.  It may return @code{0} in @var{nread} if no data is
756 currently available.  To indicate @code{EOF} the function should
757 return with an error code of @code{-1} and set @var{nread} to
758 @code{0}.  The callback function may support to reset its internal
759 read pointer if it is invoked with @var{buffer} and @var{nread} being
760 @code{NULL} and @var{count} being @code{0}.
761
762 The function returns @code{GPGME_No_Error} if the data object was
763 successfully created, @code{GPGME_Invalid_Value} if @var{dh} or
764 @var{readfunc} is not a valid pointer, and @code{GPGME_Out_Of_Core} if
765 not enough memory is available.
766 @end deftypefun
767
768
769 @node Destroying data buffers
770 @section Destroying data buffers
771
772 @deftypefun void gpgme_data_release (@w{GpgmeData @var{dh}})
773 The function @code{gpgme_data_release} destroys the data object with
774 the handle @var{dh}.  It releases all associated resources that were
775 not provided by the user in the first place.
776 @end deftypefun
777
778 @deftypefun {char *} gpgme_data_release_and_get_mem (@w{GpgmeData @var{dh}}, @w{size_t *@var{length}})
779 The function @code{gpgme_data_release_and_get_mem} is like
780 @code{gpgme_data_release}, except that it returns the data buffer and
781 its length that was provided by the object.
782
783 The user has to release the buffer with @code{free}.  In case the user
784 provided the data buffer in non-copy mode, a copy will be made for
785 this purpose.
786
787 In case an error returns, or there is no suitable data buffer that can
788 be returned to the user, the function will return @code{NULL}.
789 @end deftypefun
790
791
792 @node Manipulating data buffers
793 @section Manipulating data buffers
794
795 @deftypefun GpgmeError gpgme_data_read (@w{GpgmeData @var{dh}}, @w{char *@var{buffer}}, @w{size_t @var{length}}, @w{size_t *@var{nread}})
796 The function @code{gpgme_data_read} reads up to @var{length} bytes
797 from the data object with the handle @var{dh} into the space starting
798 at @var{buffer}.  The actual amount read is returned in @var{nread}.
799
800 If @var{buffer} is @code{NULL}, the function returns the amount of
801 bytes available in @var{nread} without changing the read pointer.
802 This is not supported by all types of data objects.  If this function
803 is not supported, @code{GPGME_Invalid_Type} is returned.
804
805 If the end of the data object is reached, the function returns
806 @code{GPGME_EOF} and sets @var{nread} to zero.
807
808 In all other cases, the function returns @code{GPGME_No_Error} if the
809 operation was successfully performed and @code{GPGME_Invalid_Value} if
810 @var{dh} is not a valid pointer.
811 @end deftypefun
812
813 @deftypefun GpgmeError gpgme_data_rewind (@w{GpgmeData @var{dh}})
814 The function @code{gpgme_data_rewind} resets the read pointer of the
815 data object with the handle @var{dh}, so that a subsequent
816 @code{gpgme_data_read} operation starts at the beginning of the data.
817
818 The function returns @code{GPGME_No_Error} if the operation was
819 successfully performed, @code{GPGME_Not_Implemented} if the operation
820 is not supported (for example, by a read callback function supplied by
821 the user) and @code{GPGME_Invalid_Value} if @var{dh} is not a valid
822 pointer.
823 @end deftypefun
824
825 @deftypefun GpgmeError gpgme_data_write (@w{GpgmeData @var{dh}}, @w{const char *@var{buffer}}, @w{size_t @var{length}})
826 The function @code{gpgme_data_write} writes @var{length} bytes
827 starting from @var{buffer} into the data object with the handle
828 @var{dh} at the current write position.
829
830 The function returns @code{GPGME_No_Error} if the operation was
831 successfully performed, @code{GPGME_Invalid_Value} if @var{dh} or
832 @var{buffer} is not a valid pointer, @code{GPGME_Invalid_Type} or
833 @code{GPGME_Invalid_Mode} if the data object type does not support
834 writing, and @code{GPGME_Out_Of_Core} if not enough memory is
835 available.
836 @end deftypefun
837
838 @deftp {Data type} {enum GpgmeDataType}
839 The @code{GpgmeDataType} type specifies the type of a @code{GpgmeData} object.
840 The following data types are available:
841
842 @table @code
843 @item GPGME_DATA_TYPE_NONE
844 This specifies that the type is not yet determined.
845
846 @item GPGME_DATA_TYPE_MEM
847 This specifies that the data is stored in memory.
848
849 @item GPGME_DATA_TYPE_FD
850 This type is not implemented.
851
852 @item GPGME_DATA_TYPE_FILE
853 This type is not implemented.
854
855 @item GPGME_DATA_TYPE_CB
856 This type specifies that the data is provided by a callback function
857 implemented by the user.
858 @end table
859 @end deftp
860
861 @deftypefun GpgmeDataType gpgme_data_get_type (@w{GpgmeData @var{dh}})
862 The function @code{gpgme_data_get_type} returns the type of the data
863 object with the handle @var{dh}.  If @var{dh} is not a valid pointer,
864 @code{GPGME_DATA_TYPE_NONE} is returned.
865 @end deftypefun
866
867
868 @node Contexts
869 @chapter Contexts
870
871 All cryptograhic operations in @acronym{GPGME} are performed within a
872 context, which contains the internal state of the operation as well as
873 configuration parameters.  By using several contexts you can run
874 several cryptographic operations in parallel, with different
875 configuration.
876
877 @deftp {Data type} {GpgmeCtx}
878 The @code{GpgmeCtx} type is a handle for a @acronym{GPGME} context,
879 which is used to hold the configuration, status and result of
880 cryptographic operations.
881 @end deftp
882
883 @menu
884 * Creating contexts::             Creating new @acronym{GPGME} contexts.
885 * Destroying contexts::           Releasing @acronym{GPGME} contexts.
886 * Context attributes::            Setting properties of a context.
887 * Key Management::                Managing keys with @acronym{GPGME}.
888 * Trust Item Management::         Managing trust items with @acronym{GPGME}.
889 * Crypto Operations::             Using a context for cryptography.
890 @end menu
891
892
893 @node Creating contexts
894 @section Creating contexts
895
896 @deftypefun GpgmeError gpgme_new (@w{GpgmeCtx *@var{ctx}})
897 The function @code{gpgme_data_new} creates a new @code{GpgmeCtx}
898 object and returns a handle for it in @var{ctx}.
899
900 The function returns @code{GPGME_No_Error} if the context was
901 successfully created, @code{GPGME_Invalid_Value} if @var{ctx} is not a
902 valid pointer, and @code{GPGME_Out_Of_Core} if not enough memory is
903 available.
904 @end deftypefun
905
906
907
908 @node Destroying contexts
909 @section Destroying contexts
910
911 @deftypefun void gpgme_release (@w{GpgmeCtx @var{ctx}})
912 The function @code{gpgme_release} destroys the context with the handle
913 @var{ctx} and releases all associated resources.
914 @end deftypefun
915
916
917 @node Context attributes
918 @section Context attributes
919
920 @menu
921 * Protocol selection::            Selecting the protocol used by a context.
922 * @acronym{ASCII} armor::                   Requesting @acronym{ASCII} armored output.
923 * Text mode::                     Choosing canonical text mode.
924 * Key listing mode::              Selecting key listing mode.
925 * Passphrase callback::           Getting the passphrase from the user.
926 * Progress meter callback::       Being informed about the progress.
927 @end menu
928
929
930 @node Protocol selection
931 @subsection Protocol selection
932
933 @deftypefun GpgmeError gpgme_set_protocol (@w{GpgmeCtx @var{ctx}}, @w{GpgmeProtocol @var{proto}})
934 The function @code{gpgme_set_protocol} sets the protocol used within
935 the context @var{ctx} to @var{proto}.  All crypto operations will be
936 performed by the crypto engine configured for that protocol.
937 @xref{Protocols and Engines}.
938
939 Setting the protocol with @code{gpgme_set_protocol} does not check if
940 the crypto engine for that protocol is available and installed
941 correctly.  @xref{Engine version check}.
942
943 The function returns @code{GPGME_No_Error} if the protocol could be
944 set successfully, and @code{GPGME_Invalid_Value} if @var{protocol} is
945 not a valid protocol.
946 @end deftypefun
947
948
949 @node @acronym{ASCII} armor
950 @subsection @acronym{ASCII} armor
951
952 @deftypefun void gpgme_set_armor (@w{GpgmeCtx @var{ctx}}, @w{int @var{yes}})
953 The function @code{gpgme_set_armor} specifies if the output should be
954 @acronym{ASCII} armored.  By default, output is not @acronym{ASCII}
955 armored.
956
957 @acronym{ASCII} armored output is disabled if @var{yes} is zero, and
958 enabled otherwise.
959 @end deftypefun
960
961 @deftypefun int gpgme_get_armor (@w{GpgmeCtx @var{ctx}})
962 The function @code{gpgme_get_armor} returns 1 if the output is
963 @acronym{ASCII} armored, and @code{0} if it is not, or if @var{ctx} is
964 not a valid pointer.
965 @end deftypefun
966
967
968 @node Text mode
969 @subsection Text mode
970
971 @deftypefun void gpgme_set_textmode (@w{GpgmeCtx @var{ctx}}, @w{int @var{yes}})
972 The function @code{gpgme_set_textmode} specifies if canonical text mode
973 should be used.  By default, text mode is not used.
974
975 Text mode is for example used for the RFC2015 signatures; note that
976 the updated RFC 3156 mandates that the mail user agent does some
977 preparations so that text mode is not needed anymore.
978
979 Canonical text mode is disabled if @var{yes} is zero, and enabled
980 otherwise.
981 @end deftypefun
982
983 @deftypefun int gpgme_get_textmode (@w{GpgmeCtx @var{ctx}})
984 The function @code{gpgme_get_textmode} returns 1 if canonical text
985 mode is enabled, and @code{0} if it is not, or if @var{ctx} is not a
986 valid pointer.
987 @end deftypefun
988
989
990 @node Key listing mode
991 @subsection Key listing mode
992
993 @deftypefun void gpgme_set_keylist_mode (@w{GpgmeCtx @var{ctx}}, @w{int @var{mode}})
994 The function @code{gpgme_set_keylist_mode} changes the default
995 behaviour of the key listing functions.  Defined values for @var{mode}
996 are:
997
998 @table @code
999 @item 0
1000 Normal listing.
1001 @item 1
1002 Fast listing without information about the key validity.
1003 @end table
1004 @end deftypefun
1005
1006
1007 @node Passphrase callback
1008 @subsection Passphrase callback
1009
1010 @deftp {Data type} {const char *(*GpgmePassphraseCb)(void *@var{hook}, const char *@var{desc}, void *@var{r_hd})}
1011 The @code{GpgmePasshraseCb} type is the type of functions usable as
1012 passphrase callback function.
1013
1014 The string @var{desc} contains a test usable to be displayed to the
1015 user of the application.  The function should return a passphrase for
1016 the context when invoked with @var{desc} not being @code{NULL}.
1017
1018 The user may store information about the resources associated with the
1019 returned passphrase in @var{*r_hd}.  When the passphrase is no longer
1020 needed by @acronym{GPGME}, the passphrase callback function will be
1021 called with @var{desc} being @var{NULL}, and @var{r_hd} being the same
1022 as at the first invocation.
1023 @end deftp
1024
1025 @deftypefun void gpgme_set_passphrase_cb (@w{GpgmeCtx @var{ctx}}, @w{GpgmePassphraseCb @var{passfunc}}, @w{void *@var{hook_value}})
1026 The function @code{gpgme_set_passphrase_cb} sets the function that is
1027 used when a passphrase needs to be provided by the user to
1028 @var{passfunc}.  The function @var{passfunc} needs to implemented by
1029 the user, and whenever it is called, it is called with its first
1030 argument being @var{hook_value}.  By default, no passphrase callback
1031 function is set.
1032
1033 Not all crypto engines require this callback to retrieve the
1034 passphrase.  It is better if the engine retrieves the passphrase from
1035 a trusted agent (a daemon process), rather than having each user to
1036 implement their own passphrase query.
1037
1038 The user can disable the use of a passphrase callback function by
1039 calling @code{gpgme_set_passphrase_cb} with @var{passfunc} being
1040 @code{NULL}.
1041 @end deftypefun
1042
1043
1044 @node Progress meter callback
1045 @subsection Progress meter callback
1046
1047 @deftp {Data type} {const char *(*GpgmeProgressCb)(void *@var{hook}, const char *@var{what}, int @var{type}, int @var{current}, int @var{total})}
1048 The @code{GpgmeProgressCb} type is the type of functions usable as
1049 progress callback function.
1050
1051 The arguments are specific to the crypto engine.  More information
1052 about the progress information returned from the GnuPG engine can be
1053 found in the GnuPG source code in the file @file{doc/DETAILS} in the
1054 section PROGRESS.
1055 @end deftp
1056
1057 @deftypefun void gpgme_set_progress_cb (@w{GpgmeCtx @var{ctx}}, @w{GpgmeProgressCb @var{progfunc}}, @w{void *@var{hook_value}})
1058 The function @code{gpgme_set_progress_cb} sets the function that is
1059 used when progress information about a cryptographic operation is
1060 available.  The function @var{progfunc} needs to implemented by the
1061 user, and whenever it is called, it is called with its first argument
1062 being @var{hook_value}.  By default, no progress callback function
1063 is set.
1064
1065 Setting a callback function allows an interactive program to display
1066 progress information about a long operation to the user.
1067
1068 The user can disable the use of a progress callback function by
1069 calling @code{gpgme_set_progress_cb} with @var{progfunc} being
1070 @code{NULL}.
1071 @end deftypefun
1072
1073
1074 @node Key Management
1075 @section Key Management
1076
1077 Some of the cryptographic operations require that recipients or
1078 signers are specified.  This is always done by specifying the
1079 respective keys that should be used for the operation.  The following
1080 section describes how such keys can be selected and manipulated.
1081
1082 @deftp {Data type} GpgmeKey
1083 The @code{GpgmeKey} type is a handle for a public or secret key, and
1084 is used to select the key for operations involving it.
1085
1086 A key can contain several user IDs and sub keys.
1087 @end deftp
1088
1089 @menu
1090 * Listing keys::                  Browsing the list of available keys.
1091 * Information about keys::        Requesting detailed information about keys.
1092 * Manipulating keys::             Operations on keys.
1093 * Generating keys::               Creating new key pairs.
1094 * Exporting keys::                Retrieving key data from the key ring.
1095 * Importing keys::                Adding keys to the keyring.
1096 * Deleting keys::                 Removing keys from the keyring.
1097 @end menu
1098
1099
1100 @node Listing keys
1101 @subsection Listing keys
1102
1103 @deftypefun GpgmeError gpgme_op_keylist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}})
1104 The function @code{gpgme_op_keylist_start} initiates a key listing
1105 operation inside the context @var{ctx}.  It sets everything up so that
1106 subsequent invocations of @code{gpgme_op_keylist_next} return the keys
1107 in the list.
1108
1109 If @var{pattern} is @code{NULL}, all available keys are returned.
1110 Otherwise, @var{pattern} contains an engine specific expression that
1111 is used to limit the list to all keys matching the pattern.
1112
1113 If @var{secret_only} is not @code{0}, the list is restricted to secret
1114 keys only.
1115
1116 The context will be busy until either all keys are received (and
1117 @code{gpgme_op_keylist_next} returns @code{GPGME_EOF}), or
1118 @code{gpgme_op_keylist_end} is called to finish the operation.
1119
1120 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
1121 valid pointer, and passes through any errors that are reported by the
1122 crypto engine support routines.
1123 @end deftypefun
1124
1125 @deftypefun GpgmeError gpgme_op_keylist_next (@w{GpgmeCtx @var{ctx}}, @w{GpgmeKey *@var{r_key}})
1126 The function @code{gpgme_op_keylist_next} returns the next key in the
1127 list created by a previous @code{gpgme_op_keylist_start} operation in
1128 the context @var{ctx}.  The key will have one reference for the user.
1129 @xref{Manipulating keys}.
1130
1131 This is the only way to get at @code{GpgmeKey} objects in
1132 @acronym{GPGME}.
1133
1134 If the last key in the list has already been returned,
1135 @code{gpgme_op_keylist_next} returns @code{GPGME_EOF}.
1136
1137 The function returns @code{GPGME_Invalid_Value} if @var{ctx} or
1138 @var{r_key} is not a valid pointer, @code{GPGME_No_Request} if there
1139 is no pending operation, @code{GPGME_Out_Of_Core} if there is not
1140 enough memory for the operation.
1141 @end deftypefun
1142
1143 @deftypefun GpgmeError gpgme_op_keylist_end (@w{GpgmeCtx @var{ctx}})
1144 The function @code{gpgme_op_keylist_next} ends a pending key list
1145 operation in the context @var{ctx}.
1146
1147 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
1148 valid pointer, @code{GPGME_No_Request} if there is no pending
1149 operation, @code{GPGME_Out_Of_Core} if at some time during the
1150 operation there was not enough memory available.
1151 @end deftypefun
1152
1153
1154 @node Information about keys
1155 @subsection Information about keys
1156
1157 @deftypefun {char *} gpgme_key_get_as_xml (@w{GpgmeKey @var{key}})
1158 The function @code{gpgme_key_get_as_xml} returns a string in
1159 @acronym{XML} format describing the key @var{key}.  The user has to
1160 release the string with @code{free}.
1161
1162 The function returns @code{NULL} if @var{key} is not a valid pointer,
1163 or there is not enough memory available.
1164 @end deftypefun
1165
1166 @deftp {Data type} GpgmeAttr
1167 The @code{GpgmeAttr} type is used to specify a key or trust item
1168 attribute.  The following attributes are defined:
1169
1170 @table @code
1171 @item GPGME_ATTR_KEYID
1172 This is the key ID of a sub key.  It is representable as a string.
1173
1174 For trust items, the trust item refers to the key with this ID.
1175
1176 @item GPGME_ATTR_FPR
1177 This is the fingerprint of a sub key.  It is representable as a
1178 string.
1179
1180 @item GPGME_ATTR_ALGO
1181 This is the crypto algorithm for which the sub key can be used.  It
1182 is representable as a string and as a number.  The numbers correspond
1183 to the @code{enum gcry_pk_algos} values in the gcrypt library.
1184
1185 @item GPGME_ATTR_LEN
1186 This is the key length of a sub key.  It is representable as a
1187 number.
1188
1189 @item GPGME_ATTR_CREATED
1190 This is the timestamp at creation time of a sub key.  It is
1191 representable as a number.
1192
1193 @item GPGME_ATTR_EXPIRE
1194 XXX FIXME
1195
1196 @item GPGME_ATTR_OTRUST
1197 XXX FIXME  (also for trust items)
1198
1199 @item GPGME_ATTR_USERID
1200 This is a user ID.  There can be more than one user IDs in a
1201 @var{GpgmeKey} object.  The first one (with index 0) is the primary
1202 user ID.  The user ID is representable as a number.
1203
1204 For trust items, this is the user ID associated with this trust item.
1205
1206 @item GPGME_ATTR_NAME
1207 This is the name belonging to a user ID.  It is representable as a string.
1208
1209 @item GPGME_ATTR_EMAIL
1210 This is the email address belonging to a user ID.  It is representable
1211 as a string.
1212
1213 @item GPGME_ATTR_COMMENT
1214 This is the comment belonging to a user ID.  It is representable as a
1215 string.
1216
1217 @item GPGME_ATTR_VALIDITY
1218 This is the validity belonging to a user ID.  It is representable as a
1219 string and as a number.  See below for a list of available validities.
1220
1221 For trust items, this is the validity that is associated with this
1222 trust item.
1223
1224 @item GPGME_ATTR_UID_REVOKED
1225 This specifies if a user ID is revoked.  It is representable as a
1226 number, and is @code{1} if the user ID is revoked, and @code{0}
1227 otherwise.
1228
1229 @item GPGME_ATTR_UID_INVALID
1230 This specifies if a user ID is invalid.  It is representable as a
1231 number, and is @code{1} if the user ID is invalid, and @code{0}
1232 otherwise.
1233
1234 @item GPGME_ATTR_LEVEL
1235 This is the trust level of a trust item.
1236
1237 @item GPGME_ATTR_TYPE
1238 This is the type of a trust item.
1239
1240 @item GPGME_ATTR_IS_SECRET
1241 This specifies if the key is a secret key.  It is representable as a
1242 string or a number.  If the key is a secret key, the representation is
1243 ``1'' or @code{1}, otherwise it is NULL or @code{0}.
1244
1245 @item GPGME_ATTR_KEY_REVOKED
1246 This specifies if a sub key is revoked.  It is representable as a
1247 number, and is @code{1} if the key is revoked, and @code{0} otherwise.
1248
1249 @item GPGME_ATTR_KEY_INVALID
1250 This specifies if a sub key is invalid.  It is representable as a
1251 number, and is @code{1} if the key is invalid, and @code{0} otherwise.
1252
1253 @item GPGME_ATTR_KEY_EXPIRED
1254 This specifies if a sub key is expired.  It is representable as a
1255 number, and is @code{1} if the key is expired, and @code{0} otherwise.
1256
1257 @item GPGME_ATTR_KEY_DISABLED
1258 This specifies if a sub key is disabled.  It is representable as a
1259 number, and is @code{1} if the key is disabled, and @code{0} otherwise.
1260
1261 @item GPGME_ATTR_KEY_CAPS
1262 This is a description of the capabilities of a sub key.  It is
1263 representable as a string.  The string contains the letter ``e'' if
1264 the key can be used for encryption, ``s'' if the key can be used for
1265 signatures, and ``c'' if the key can be used for certifications.
1266
1267 @item GPGME_ATTR_CAN_ENCRYPT
1268 This specifies if a sub key can be used for encryption.  It is
1269 representable as a number, and is @code{1} if the sub key can be used
1270 for encryption, and @code{0} otherwise.
1271
1272 @item GPGME_ATTR_CAN_SIGN
1273 This specifies if a sub key can be used for signatures.  It is
1274 representable as a number, and is @code{1} if the sub key can be used
1275 for signatures, and @code{0} otherwise.
1276
1277 @item GPGME_ATTR_CAN_CERTIFY
1278 This specifies if a sub key can be used for certifications.  It is
1279 representable as a number, and is @code{1} if the sub key can be used
1280 for certifications, and @code{0} otherwise.
1281 @end table
1282 @end deftp
1283
1284 @deftp {Data type} GpgmeValidity
1285 The @code{GpgmeValidity} type is used to specify the validity of a user ID
1286 in a key.  The following validities are defined:
1287
1288 @table @code
1289 @item GPGME_VALIDITY_UNKNOWN
1290 The user ID is of unknown validity.  The string representation of this
1291 validity is ``?''.
1292
1293 @item GPGME_VALIDITY_UNDEFINED
1294 The validity of the user ID is undefined.  The string representation of this
1295 validity is ``q''.
1296
1297 @item GPGME_VALIDITY_NEVER
1298 The user ID is never valid.  The string representation of this
1299 validity is ``n''.
1300
1301 @item GPGME_VALIDITY_MARGINAL
1302 The user ID is marginally valid.  The string representation of this
1303 validity is ``m''.
1304
1305 @item GPGME_VALIDITY_FULL
1306 The user ID is fully valid.  The string representation of this
1307 validity is ``f''.
1308
1309 @item GPGME_VALIDITY_ULTIMATE
1310 The user ID is ultimately valid.  The string representation of this
1311 validity is ``u''.
1312 @end table
1313 @end deftp
1314
1315 @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}})
1316 The function @code{gpgme_key_get_string_attr} returns the value of the
1317 string-representable attribute @var{what} of key @var{key}.  If the
1318 attribute occurs more than once in the key, the index is specified by
1319 @var{idx}.  This applies to attributes of sub keys and user IDs.  The
1320 argument @var{reserved} is reserved for later use and should be
1321 @code{NULL}.
1322
1323 The string returned is only valid as long as the key is valid.
1324
1325 The function returns @code{0} if an attribute can't be returned as a
1326 string, @var{key} is not a valid pointer, @var{idx} out of range,
1327 or @var{reserved} not @code{NULL}.
1328 @end deftypefun
1329
1330 @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}})
1331 The function @code{gpgme_key_get_ulong_attr} returns the value of the
1332 number-representable attribute @var{what} of key @var{key}.  If the
1333 attribute occurs more than once in the key, the index is specified by
1334 @var{idx}.  This applies to attributes of sub keys and user IDs.  The
1335 argument @var{reserved} is reserved for later use and should be
1336 @code{NULL}.
1337
1338 The function returns @code{0} if the attribute can't be returned as a
1339 number, @var{key} is not a valid pointer, @var{idx} out of range,
1340 or @var{reserved} not @code{NULL}.
1341 @end deftypefun
1342
1343
1344 @node Manipulating keys
1345 @subsection Manipulating keys
1346
1347 @deftypefun void gpgme_key_ref (@w{GpgmeKey @var{key}})
1348 The function @code{gpgme_key_ref} acquires an additional reference for
1349 the key @var{key}.
1350 @end deftypefun
1351
1352 @deftypefun void gpgme_key_unref (@w{GpgmeKey @var{key}})
1353 @deftypefunx void gpgme_key_release (@w{GpgmeKey @var{key}})
1354 The function @code{gpgme_key_ref} releases a reference for the key
1355 @var{key}.  If this was the last reference, the key will be destroyed
1356 and all resources associated to it will be released.
1357
1358 The function @code{gpgme_key_release} is an alias for
1359 @code{gpgme_key_unref}.
1360 @end deftypefun
1361
1362
1363 @node Generating keys
1364 @subsection Generating keys
1365
1366 @deftypefun GpgmeError gpgme_op_genkey (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{pubkey}}, @w{GpgmeData @var{seckey}})
1367 The function @code{gpgme_op_genkey} generates a new key pair in the
1368 context @var{ctx} and puts it into the standard keyring if both
1369 @var{pubkey} and @var{seckey} are @code{NULL}.  In this case the
1370 function returns immediately after starting the operation, and does
1371 not wait for it to complete.  @var{pubkey} and @var{seckey} are
1372 reserved for later use and should be @code{NULL}.  (The function
1373 should return the public key in the data buffer @var{pubkey} and the
1374 secret key in the data buffer @var{seckey}, but this is not
1375 implemented yet).
1376
1377 The argument @var{parms} specifies parameters for the key in an XML
1378 string.  The details about the format of @var{parms} are specific to
1379 teh crypto engine used by @var{ctx}.  Here is an example for GnuPG as
1380 the crypto engine:
1381
1382 @example
1383 <literal>
1384 <![CDATA[
1385 <GnupgKeyParms format="internal">
1386 Key-Type: DSA
1387 Key-Length: 1024
1388 Subkey-Type: ELG-E
1389 Subkey-Length: 1024
1390 Name-Real: Joe Tester
1391 Name-Comment: with stupid passphrase
1392 Name-Email: joe@@foo.bar
1393 Expire-Date: 0
1394 Passphrase: abc
1395 </GnupgKeyParms>
1396 ]]>
1397 </literal>
1398 @end example
1399
1400 Strings should be given in UTF-8 encoding.  The only format supported
1401 for now is ``internal''.  The content of the @code{GnupgKeyParms}
1402 container is passed verbatim to GnuPG.  Control statements are not
1403 allowed.
1404
1405 The function returns @code{GPGME_No_Error} if the operation could be
1406 started, @code{GPGME_Invalid_Value} if @var{parms} is not a valid XML
1407 string, and @code{GPGME_Not_Supported} if @var{pubkey} or @var{seckey}
1408 is not @code{NULL}.
1409 @end deftypefun
1410
1411
1412 @node Exporting keys
1413 @subsection Exporting keys
1414
1415 @deftypefun GpgmeError gpgme_op_export (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{recipients}}, @w{GpgmeData @var{keydata}})
1416 The function @code{gpgme_op_export} extracts the public keys of the
1417 user IDs in @var{recipients} and returns them in the data buffer
1418 @var{keydata}.  The type of the public keys returned is determined by
1419 the @acronym{ASCII} armor attribute set for the context @var{ctx}.
1420
1421 The function returns @code{GPGME_No_Error} if the operation completed
1422 successfully, @code{GPGME_Invalid_Value} if @var{recipients} is
1423 @code{NULL} or @var{keydata} is not a valid empty data buffer, and
1424 passes through any errors that are reported by the crypto engine
1425 support routines.
1426 @end deftypefun
1427
1428
1429 @node Importing keys
1430 @subsection Importing keys
1431
1432 @deftypefun GpgmeError gpgme_op_import (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}})
1433 The function @code{gpgme_op_import} adds the keys in the data buffer
1434 @var{keydata} to the key ring of the crypto engine used by @var{ctx}.
1435 The format of @var{keydata} can be @var{ASCII} armored, for example,
1436 but the details are specific to the crypto engine.
1437
1438 The function returns @code{GPGME_No_Error} if the import was completed
1439 successfully, @code{GPGME_Invalid_Value} if @var{keydata} if @var{ctx}
1440 or @var{keydata} is not a valid pointer, and @code{GPGME_No_Data} if
1441 @var{keydata} is an empty data buffer.
1442 @end deftypefun
1443
1444
1445 @node Deleting keys
1446 @subsection Deleting keys
1447
1448 @deftypefun GpgmeError gpgme_op_delete (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}, @w{int @var{allow_secret}})
1449 The function @code{gpgme_op_delete} deletes the key @var{key} from the
1450 key ring of the crypto engine used by @var{ctx}.  If
1451 @var{allow_secret} is @code{0}, only public keys are deleted,
1452 otherwise secret keys are deleted as well.
1453
1454 The function returns @code{GPGME_No_Error} if the key was deleted
1455 successfully, and @code{GPGME_Invalid_Value} if @var{ctx} or @var{key}
1456 is not a valid pointer.
1457 @end deftypefun
1458
1459
1460 @node Trust Item Management
1461 @section Trust Item Management
1462
1463 @strong{Caution:} The trust items interface is experimental.
1464
1465 @deftp {Data type} GpgmeTrustItem
1466 The @code{GpgmeTrustItem} type is a handle for a trust item.
1467 @end deftp
1468
1469 @menu
1470 * Listing trust items::           Browsing the list of available trust items.
1471 * Information about trust items:: Requesting detailed information about trust items.
1472 * Manipulating trust items::      Operations on trust items.
1473 @end menu
1474
1475
1476 @node Listing trust items
1477 @subsection Listing trust items
1478
1479 @deftypefun GpgmeError gpgme_op_trustlist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{max_level}})
1480 The function @code{gpgme_op_trustlist_start} initiates a trust item
1481 listing operation inside the context @var{ctx}.  It sets everything up
1482 so that subsequent invocations of @code{gpgme_op_trustlist_next} return
1483 the trsut items in the list.
1484
1485 The string @var{pattern} contains an engine specific expression that
1486 is used to limit the list to all trust items matching the pattern.  It
1487 can not be the empty string.
1488
1489 The argument @var{max_level} is currently ignored.
1490
1491 The context will be busy until either all trust items are received
1492 (and @code{gpgme_op_trustlist_next} returns @code{GPGME_EOF}), or
1493 @code{gpgme_op_trustlist_end} is called to finish the operation.
1494
1495 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
1496 valid pointer, and passes through any errors that are reported by the
1497 crypto engine support routines.
1498 @end deftypefun
1499
1500 @deftypefun GpgmeError gpgme_op_trustlist_next (@w{GpgmeCtx @var{ctx}}, @w{GpgmeTrustItem *@var{r_item}})
1501 The function @code{gpgme_op_trustlist_next} returns the next trust
1502 item in the list created by a previous @code{gpgme_op_trustlist_start}
1503 operation in the context @var{ctx}.  The trust item can be destroyed
1504 with @code{gpgme_trust_item_release}.  @xref{Manipulating trust items}.
1505
1506 This is the only way to get at @code{GpgmeTrustItem} objects in
1507 @acronym{GPGME}.
1508
1509 If the last trust item in the list has already been returned,
1510 @code{gpgme_op_trustlist_next} returns @code{GPGME_EOF}.
1511
1512 The function returns @code{GPGME_Invalid_Value} if @var{ctx} or
1513 @var{r_item} is not a valid pointer, @code{GPGME_No_Request} if there
1514 is no pending operation, @code{GPGME_Out_Of_Core} if there is not
1515 enough memory for the operation.
1516 @end deftypefun
1517
1518 @deftypefun GpgmeError gpgme_op_trustlist_end (@w{GpgmeCtx @var{ctx}})
1519 The function @code{gpgme_op_trustlist_next} ends a pending key list
1520 operation in the context @var{ctx}.
1521
1522 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
1523 valid pointer, @code{GPGME_No_Request} if there is no pending
1524 operation, @code{GPGME_Out_Of_Core} if at some time during the
1525 operation there was not enough memory available.
1526 @end deftypefun
1527
1528
1529 @node Information about trust items
1530 @subsection Information about trust items
1531
1532 Trust items have attributes which can be queried using the interfaces
1533 below.  The attribute identifiers are shared with those for key
1534 attributes.  @xref{Information about keys}.
1535
1536 @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}})
1537 The function @code{gpgme_trust_item_get_string_attr} returns the value
1538 of the string-representable attribute @var{what} of trust item
1539 @var{item}.  If the attribute occurs more than once in the trust
1540 items, the index is specified by @var{idx}.  However, currently no
1541 such attributes exists, so @var{idx} should be @code{0}.  The argument
1542 @var{reserved} is reserved for later use and should be @code{NULL}.
1543
1544 The string returned is only valid as long as the key is valid.
1545
1546 The function returns @code{0} if an attribute can't be returned as a
1547 string, @var{key} is not a valid pointer, @var{idx} out of range,
1548 or @var{reserved} not @code{NULL}.
1549 @end deftypefun
1550
1551 @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}})
1552 The function @code{gpgme_trust_item_get_int_attr} returns the value of
1553 the number-representable attribute @var{what} of trust item
1554 @var{item}.  If the attribute occurs more than once in the trust item,
1555 the index is specified by @var{idx}.  However, currently no such
1556 attribute exists, so @var{idx} should be @code{0}.  The argument
1557 @var{reserved} is reserved for later use and should be @code{NULL}.
1558
1559 The function returns @code{0} if the attribute can't be returned as a
1560 number, @var{key} is not a valid pointer, @var{idx} out of range,
1561 or @var{reserved} not @code{NULL}.
1562 @end deftypefun
1563
1564
1565 @node Manipulating trust items
1566 @subsection Manipulating trust items
1567
1568 @deftypefun void gpgme_trust_item_release (@w{GpgmeTrustItem @var{item}})
1569 The function @code{gpgme_trust_item_release} destroys a
1570 @code{GpgmeTrustItem} object and releases all associated resources.
1571 @end deftypefun
1572
1573 @node Crypto Operations
1574 @section Crypto Operations
1575
1576 @menu
1577 * Decrypt::                       Decrypting a ciphertext.
1578 * Verify::                        Verifying a signature.
1579 * Decrypt and verify::            Decrypting a signed ciphertext.
1580 * Sign::                          Creating a signature.
1581 * Encrypt::                       Encrypting a plaintext.
1582 @end menu
1583
1584
1585 @node Decrypt
1586 @subsection Decrypt
1587
1588 @deftypefun GpgmeError gpgme_op_decrypt (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
1589 The function @code{gpgme_op_decrypt} decrypts the ciphertext in the
1590 data object @var{cipher} and stores it into the data object
1591 @var{plain}.
1592
1593 The function returns @code{GPGME_No_Error} if the ciphertext could be
1594 decrypted successfully, @code{GPGME_Invalid_Value} if @var{ctx},
1595 @var{cipher} or @var{plain} is not a valid pointer,
1596 @code{GPGME_No_Data} if @var{cipher} does not contain any data to
1597 decrypt, @code{GPGME_Decryption_Failed} if @var{cipher} is not a valid
1598 cipher text, @code{GPGME_No_Passphrase} if the passphrase for the
1599 secret key could not be retrieved, and passes through any errors that
1600 are reported by the crypto engine support routines.
1601 @end deftypefun
1602
1603 @c @deftypefun GpgmeError gpgme_op_decrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
1604 @c The function @code{gpgme_op_decrypt_start} initiates a
1605 @c @code{gpgme_op_decrypt} operation.  It can be completed by calling
1606 @c @code{gpgme_wait} on the context.
1607
1608 @c The function returns @code{GPGME_No_Error} if the operation could be
1609 @c started, @code{GPGME_Invalid_Value} if @var{cipher} or @var{plain} is
1610 @c not a valid pointer, and passes through any errors that are reported
1611 @c by the crypto engine support routines.
1612 @c @end deftypefun
1613
1614
1615 @node Verify
1616 @subsection Verify
1617
1618 @deftp {Data type} {enum GpgmeSigStat}
1619 The @code{GpgmeSigStat} type holds the result of a signature check, or
1620 the combined result of all signatures.  The following results are
1621 possible:
1622
1623 @table @code
1624 @item GPGME_SIG_STAT_NONE
1625 This status should not occur in normal operation.
1626
1627 @item GPGME_SIG_STAT_GOOD
1628 This status indicates that the signature is valid.  For the combined
1629 result this status means that all signatures are valid.
1630
1631 @item GPGME_SIG_STAT_BAD
1632 This status indicates that the signature is invalid.  For the combined
1633 result this status means that all signatures are invalid.
1634
1635 @item GPGME_SIG_STAT_NOKEY
1636 This status indicates that the signature could not be verified due to
1637 a missing key.  For the combined result this status means that all
1638 signatures could not be checked due to missing keys.
1639
1640 @item GPGME_SIG_STAT_NOSIG
1641 This status indicates that the signature data provided was not a real
1642 signature.
1643
1644 @item GPGME_SIG_STAT_ERROR
1645 This status indicates that there was some other error which prevented
1646 the signature verification.
1647
1648 @item GPGME_SIG_STAT_DIFF
1649 For the combined result this status means that at least two signatures
1650 have a different status.  You can get each key's status with
1651 @code{gpgme_get_sig_status}.
1652 @end table
1653 @end deftp
1654
1655 @deftypefun GpgmeError gpgme_op_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{sig}}, @w{GpgmeData @var{plain}}, @w{GpgmeSigStat *@var{r_stat}})
1656 The function @code{gpgme_op_verify} verifies that the detached
1657 signature in the data object @var{sig} is a valid signature for the
1658 plaintext in the data object @var{plain}.
1659
1660 The combined status of all signatures is returned in @var{r_stat}.
1661 The results of the individual signature verifications can be retrieved
1662 with @code{gpgme_get_sig_status} and @code{gpgme_get_sig_key}.
1663
1664 The function returns @code{GPGME_No_Error} if the operation could be
1665 completed successfully, @code{GPGME_Invalid_Value} if @var{ctx},
1666 @var{sig}, @var{plain} or @var{r_stat} is not a valid pointer,
1667 @code{GPGME_No_Data} if @var{sig} or @var{plain} does not contain any
1668 data to verify, and passes through any errors that are reported by the
1669 crypto engine support routines.
1670 @end deftypefun
1671
1672 @c GpgmeError gpgme_op_verify_start (GpgmeCtx ctx, GpgmeData sig, GpgmeData plain);
1673
1674 @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}})
1675 The function @code{gpgme_get_sig_status} receives information about a
1676 signature after the @code{gpgme_op_verify} or
1677 @code{gpgme_op_verify_decrypt} operation.  A single detached signature
1678 can contain signatures by more than one key.  The @var{idx} specifies
1679 which signature's information should be retrieved, starting from
1680 @var{0}.
1681
1682 The status of the signature will be returned in @var{r_stat} if it is
1683 not @code{NULL}.  The creation time stamp of the signature will be
1684 returned in @var{r_created} if it is not @var{NULL}.
1685
1686 The function returns a statically allocated string that contains the
1687 fingerprint of the key which signed the plaintext, or @code{NULL} if
1688 @var{ctx} is not a valid pointer, the operation is still pending, or
1689 no verification could be performed.
1690 @end deftypefun
1691
1692 @deftypefun {const char *} gpgme_get_sig_key (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeSigKey *@var{r_stat}})
1693 The function @code{gpgme_get_sig_status} receives a @code{GpgmeKey}
1694 object for the key which was used to verify the signature after the
1695 @code{gpgme_op_verify} or @code{gpgme_op_verify_decrypt} operation.  A
1696 single detached signature can contain signatures by more than one key.
1697 The @var{idx} specifies which signature's information should be
1698 retrieved, starting from @var{0}.  The key will have on reference for
1699 the user.
1700
1701 The function is a convenient way to retrieve the keys belonging to the
1702 fingerprints returned by @code{gpgme_get_sig_status}.
1703
1704 The function returns @code{GPGME_No_Error} if the key could be
1705 returned, @code{GPGME_Invalid_Value} if @var{r_key} is not a valid
1706 pointer, @code{GPGME_Invalid_Key} if the fingerprint is not valid,
1707 @code{GPGME_EOF} if @var{idx} is too large, or some other error value
1708 if a problem occured requesting the key.
1709 @end deftypefun
1710
1711
1712 @node Decrypt and verify
1713 @subsection Decrypt and verify
1714
1715 @deftypefun GpgmeError gpgme_op_decrypt_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}}, @w{GpgmeSigStat *@var{r_stat}})
1716 The function @code{gpgme_op_decrypt_verify} decrypts the ciphertext in
1717 the data object @var{cipher} and stores it into the data object
1718 @var{plain}.  If @var{cipher} contains signatures, they will be
1719 verified and their combined status will be returned in @var{r_stat}.
1720
1721 After the operation completed, @code{gpgme_op_get_sig_status} and
1722 @code{gpgme_op_get_sig_key} can be used to retrieve more information
1723 about the signatures.
1724
1725 The function returns @code{GPGME_No_Error} if the ciphertext could be
1726 decrypted successfully, @code{GPGME_Invalid_Value} if @var{ctx},
1727 @var{cipher}, @var{plain} or @var{r_stat} is not a valid pointer,
1728 @code{GPGME_No_Data} if @var{cipher} does not contain any data to
1729 decrypt, @code{GPGME_Decryption_Failed} if @var{cipher} is not a valid
1730 cipher text, @code{GPGME_No_Passphrase} if the passphrase for the
1731 secret key could not be retrieved, and passes through any errors that
1732 are reported by the crypto engine support routines.
1733 @end deftypefun
1734
1735 @c GpgmeError gpgme_op_decrypt_verify (GpgmeCtx c, GpgmeData in, GpgmeData out, GpgmeSigStat *r_status);
1736
1737
1738 @node Sign
1739 @subsection Sign
1740
1741 A signature can contain signatures by one or more keys.  The set of
1742 keys used to create a signatures is contained in a context, and is
1743 applied to all following signing operations in this context (until the
1744 set is changed).
1745
1746 @menu
1747 * Selecting signers::             How to choose the keys to sign with.
1748 * Creating a signature::          How to create a signature.
1749 @end menu
1750
1751
1752 @node Selecting signers
1753 @subsubsection Selecting signers
1754
1755 @deftypefun void gpgme_signers_clear (@w{GpgmeCtx @var{ctx}})
1756 The function @code{gpgme_signers_clear} releases a reference for each
1757 key on the signers list and removes the list of signers from the
1758 context @var{ctx}.
1759
1760 Every context starts with an empty list.
1761 @end deftypefun
1762
1763
1764 @deftypefun GpgmeError gpgme_signers_add (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}})
1765 The function @code{gpgme_signers_add} adds the key @var{key} to the
1766 list of signers in the context @var{ctx}.
1767
1768 One reference for the key is consumed.
1769 @end deftypefun
1770
1771 @deftypefun GpgmeKey gpgme_signers_enum (@w{const GpgmeCtx @var{ctx}}, @w{int @var{seq}})
1772 The function @code{gpgme_signers_enum} returns the @var{seq}th key in
1773 the list of signers in the context @var{ctx}.  An additional reference
1774 is acquired for the user.
1775
1776 If @var{seq} is out of range, @code{NULL} is returned.
1777 @end deftypefun
1778
1779
1780 @node Creating a signature
1781 @subsubsection Creating a signature
1782
1783 @deftp {Data type} {enum GpgmeSigMode}
1784 The @code{GpgmeSigMode} type is used to specify the desired type of a
1785 signature.  The following modes are available:
1786
1787 @table @code
1788 @item GPGME_SIG_MODE_NORMAL
1789 A normal signature is made, the output includes the plaintext and the
1790 signature.
1791
1792 @item GPGME_SIG_MODE_DETACH
1793 A detached signature is made.
1794
1795 @item GPGME_SIG_MODE_CLEAR
1796 A clear text signature is made.  The @acronym{ASCII} armor and text
1797 mode settings of the context are ignored.
1798 @end table
1799 @end deftp
1800
1801 @deftypefun GpgmeError gpgme_op_sign (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{sig}}, @w{GpgmeSigMode @var{mode}})
1802 The function @code{gpgme_op_sign} creates a signature for the text in
1803 the data object @var{plain} and returns it in the data object
1804 @var{sig}.  The type of the signature created is determined by the
1805 @acronym{ASCII} armor and text mode attributes set for the context
1806 @var{ctx} and the requested signature mode @var{mode}.
1807
1808 The function returns @code{GPGME_No_Error} if the signature could be
1809 created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
1810 @var{plain} or @var{sig} is not a valid pointer, @code{GPGME_No_Data}
1811 if the signature could not be created, @code{GPGME_No_Passphrase} if
1812 the passphrase for the secret key could not be retrieved, and passes
1813 through any errors that are reported by the crypto engine support
1814 routines.
1815 @end deftypefun
1816
1817
1818 @node Encrypt
1819 @subsection Encrypt
1820
1821 One plaintext can be encrypted for several recipients at the same
1822 time.  The list of recipients is created independently of any context,
1823 and then passed to the encryption operation.
1824
1825 @menu
1826 * Selecting recipients::          How to choose the recipients.
1827 * Encrypting a plaintext::        How to encrypt a plaintext.
1828 @end menu
1829
1830
1831 @node Selecting recipients
1832 @subsubsection Selecting recipients
1833
1834 @deftp {Data type} GpgmeRecipients
1835 The @code{GpgmeRecipients} type is a handle for a set of recipients
1836 that can be used in an encryption process.
1837 @end deftp
1838
1839 @deftypefun GpgmeError gpgme_recipients_new (@w{GpgmeRecipients *@var{r_rset}})
1840 The function @code{gpgme_recipients_new} creates a new, empty set of
1841 recipients and returns a handle for it in @var{r_rset}.
1842
1843 The function returns @code{GPGME_No_Error} if the recipient set could
1844 be created successfully, and @code{GPGME_Out_Of_Core} if not enough
1845 memory was available.
1846 @end deftypefun
1847
1848 @deftypefun void gpgme_recipients_release (@w{GpgmeRecipients @var{rset}})
1849 The function @code{gpgme_recipients_release} destroys the set of
1850 recipients @var{rset} and releases all associated resources.
1851 @end deftypefun
1852
1853 @deftypefun GpgmeError gpgme_recipients_add_name (@w{GpgmeRecipients @var{rset}}, @w{const char *@var{name}})
1854 The function @code{gpgme_recipients_add_name} adds the recipient
1855 @var{name} to the set of recipients @var{rset}.  This is equivalent to
1856 @code{gpgme_recipients_add_name_with_validity} with a validity of
1857 @code{GPGME_VALIDITY_UNKNOWN}.
1858
1859 The function returns @code{GPGME_No_Error} if the recipient was added
1860 successfully, @code{GPGME_Invalid_Value} if @var{rset} or @var{name}
1861 is not a valid pointer, and @code{GPGME_Out_Of_Core} if not enough
1862 memory is available.
1863 @end deftypefun
1864
1865 @deftypefun GpgmeError gpgme_recipients_add_name_with_validity (@w{GpgmeRecipients @var{rset}}, @w{const char *@var{name}}, @w{GpgmeValidity @var{val}})
1866 The function @code{gpgme_recipients_add_name_with_validity} adds the
1867 recipient @var{name} with the validity @var{val} to the set of
1868 recipients @var{rset}.  If the validity is not known, the function
1869 @code{gpgme_recipients_add_name} can be used.
1870 @xref{Information about keys}, for the possible values for @var{val}.
1871
1872 The function returns @code{GPGME_No_Error} if the recipient was added
1873 successfully, @code{GPGME_Invalid_Value} if @var{rset} or @var{name}
1874 is not a valid pointer, and @code{GPGME_Out_Of_Core} if not enough
1875 memory is available.
1876 @end deftypefun
1877
1878 @deftypefun {unsigned int} gpgme_recipients_count (@w{const @var{GpgmeRecipients rset}})
1879 The function @code{gpgme_recipients_count} returns the number of
1880 recipients in the set @var{rset}.
1881 @end deftypefun
1882
1883 @deftypefun GpgmeError gpgme_recipients_enum_open (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}})
1884 The function @code{gpgme_recipients_enum_open} creates a new iterator
1885 @var{iter} that can be used to walk through the set of recipients in
1886 @var{rset}, using @code{gpgme_recipients_enum_read}.
1887
1888 If the iterator is not needed anymore, it can be closed with
1889 @code{gpgme_recipients_enum_close}.
1890
1891 The function returns @code{GPGME_No_Error} if the enumerator was
1892 successfully created and @code{GPGME_Invalid_Value} if @var{rset} or
1893 @var{iter} is not a valid pointer.
1894 @end deftypefun
1895
1896 @deftypefun {const char *} gpgme_recipients_enum_read (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}})
1897 The function @code{gpgme_recipients_enum_read} returns a string
1898 containing the name of the next recipient in the set @var{rset} for
1899 the iterator @var{iter}.  The string is valid as long as @var{rset} is
1900 valid or the function is called the next time with the same recipient
1901 set and iterator, whatever is earlier.
1902 @end deftypefun
1903
1904 @deftypefun GpgmeError gpgme_recipients_enum_close (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}})
1905 The function @code{gpgme_recipients_enum_close} releases the iterator
1906 @var{iter} for the recipient set @var{rset}.
1907 @end deftypefun
1908
1909
1910 @node Encrypting a plaintext
1911 @subsubsection Encrypting a plaintext
1912
1913 @deftypefun GpgmeError gpgme_op_encrypt (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
1914 The function @code{gpgme_op_crypt} encrypts the plaintext in the data
1915 object @var{plain} for the recipients @var{rset} and stores the
1916 ciphertext in the data object @var{cipher}.  The type of the
1917 ciphertext created is determined by the @acronym{ASCII} armor and text
1918 mode attributes set for the context @var{ctx}.
1919
1920 The function returns @code{GPGME_No_Error} if the ciphertext could be
1921 created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
1922 @var{rset}, @var{plain} or @var{cipher} is not a valid pointer,
1923 @code{GPGME_No_Recipient} if @var{rset} does not contain any
1924 valid recipients, @code{GPGME_No_Passphrase} if the passphrase for the
1925 secret key could not be retrieved, and passes through any errors that
1926 are reported by the crypto engine support routines.
1927 @end deftypefun
1928
1929
1930 @include gpl.texi
1931
1932
1933 @include fdl.texi
1934
1935
1936 @node Concept Index
1937 @unnumbered Concept Index
1938
1939 @printindex cp
1940
1941
1942 @node Function and Data Index
1943 @unnumbered Function and Data Index
1944
1945 @printindex fn
1946
1947
1948 @summarycontents
1949 @contents
1950 @bye