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