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