1 \input texinfo @c -*- Texinfo -*-
2 @setfilename gpgme.info
3 @settitle The `GnuPG Made Easy' Reference Manual
6 @c char *gpgme_get_op_info (GpgmeCtx c, int reserved);
7 @c void gpgme_cancel (GpgmeCtx c);
8 @c GpgmeCtx gpgme_wait (GpgmeCtx c, int hang);
9 @c char *gpgme_get_notation (GpgmeCtx c);
10 @c void gpgme_register_idle (void (*fnc)(void));
12 @dircategory GNU Libraries
14 * @acronym{GPGME}: (gpgme) Adding support for cryptography to your program.
19 @c Unify some of the indices.
24 This file documents the @acronym{GPGME} library.
26 This is Edition @value{EDITION}, last updated @value{UPDATED}, of
27 @cite{The `GnuPG Made Easy' Reference Manual}, for Version
30 Copyright @copyright{} 2002 g10 Code GmbH.
32 Permission is granted to copy, distribute and/or modify this document
33 under the terms of the GNU Free Documentation License, Version 1.1 or
34 any later version published by the Free Software Foundation; with the
35 Invariant Sections being ``Free Software Needs Free Documentation'' and
36 ``GNU Lesser General Public License'', the Front-Cover texts being (a)
37 (see below), and with the Back-Cover Texts being (b) (see below). A
38 copy of the license is included in the section entitled ``GNU Free
39 Documentation License''.
44 @shorttitlepage The `GnuPG Made Easy' Reference Manual
47 @center @titlefont{The `GnuPG Made Easy'}
49 @center @titlefont{Reference Manual}
51 @center Edition @value{EDITION}
53 @center last updated @value{UPDATED}
55 @center for version @value{VERSION}
57 @vskip 0pt plus 1filll
58 Copyright @copyright{} 2002 g10 Code GmbH.
60 Permission is granted to copy, distribute and/or modify this document
61 under the terms of the GNU Free Documentation License, Version 1.1 or
62 any later version published by the Free Software Foundation; with the
63 Invariant Sections being ``Free Software Needs Free Documentation'' and
64 ``GNU Lesser General Public License'', the Front-Cover texts being (a)
65 (see below), and with the Back-Cover Texts being (b) (see below). A
66 copy of the license is included in the section entitled ``GNU Free
67 Documentation License''.
74 This is Edition @value{EDITION}, last updated @value{UPDATED}, of
75 @cite{The `GnuPG Made Easy' Reference Manual}, for Version
76 @value{VERSION} of the @acronym{GPGME} library.
80 * Introduction:: How to use this manual.
81 * Preperation:: What you should do before using the library.
82 * Protocols and Engines:: Supported crypto protocols.
83 * Error Handling:: Error numbers and their meanings.
84 * Exchanging Data:: Passing data to and from @acronym{GPGME}.
85 * Contexts:: Handling @acronym{GPGME} contexts.
89 * Copying:: The GNU General Public License says how you
90 can copy and share `GnuPG Made Easy'.
91 * Free Documentation License:: This manual is under the GNU Free
92 Documentation License.
96 * Concept Index:: Index of concepts and programs.
97 * Function and Data Index:: Index of functions, variables and data types.
101 --- The Detailed Node Listing ---
105 * Getting Started:: Purpose of the manual, and how to use it.
106 * Features:: Reasons to install and use @acronym{GPGME}.
107 * Overview:: Basic architecture of the @acronym{GPGME} library.
111 * Header:: What header file you need to include.
112 * Building the source:: Compiler options to be used.
113 * Library version check:: Getting and verifying the library version.
115 Protocols and Engines
117 * Engine version check:: Verifying the engine version.
118 * Engine information:: Obtaining more information about the engines.
119 * OpenPGP:: Support for the OpenPGP protocol.
120 * Cryptographic Message Syntax:: Support for the CMS.
124 * Error values:: A list of all error values used.
125 * Error strings:: How to get a descriptive string from a value.
129 * Creating data buffers:: Creating new data buffers.
130 * Destroying data buffers:: Releasing data buffers.
131 * Manipulating data buffers:: Operations on data buffers.
135 * Creating contexts:: Creating new @acronym{GPGME} contexts.
136 * Destroying contexts:: Releasing @acronym{GPGME} contexts.
137 * Context attributes:: Setting properties of a context.
138 * Key Management:: Managing keys with @acronym{GPGME}.
139 * Trust Item Management:: Managing trust items with @acronym{GPGME}.
140 * Crypto Operations:: Using a context for cryptography.
144 * Protocol selection:: Selecting the protocol used by a context.
145 * @acronym{ASCII} armor:: Requesting @acronym{ASCII} armored output.
146 * Text mode:: Choosing canonical text mode.
147 * Key listing mode:: Selecting key listing mode.
148 * Passphrase callback:: Getting the passphrase from the user.
149 * Progress meter callback:: Being informed about the progress.
153 * Listing keys:: Browsing the list of available keys.
154 * Information about keys:: Requesting detailed information about keys.
155 * Manipulating keys:: Operations on keys.
156 * Generating keys:: Creating new key pairs.
157 * Exporting keys:: Retrieving key data from the key ring.
158 * Importing keys:: Adding keys to the keyring.
159 * Deleting keys:: Removing keys from the keyring.
161 Trust Item Management
163 * Listing trust items:: Browsing the list of available trust items.
164 * Information about trust items:: Requesting detailed information about trust items.
165 * Manipulating trust items:: Operations on trust items.
169 * Decrypt:: Decrypting a ciphertext.
170 * Verify:: Verifying a signature.
171 * Decrypt and verify:: Decrypting a signed ciphertext.
172 * Sign:: Creating a signature.
173 * Encrypt:: Encrypting a plaintext.
177 * Selecting signers:: How to choose the keys to sign with.
178 * Creating a signature:: How to create a signature.
182 * Selecting recipients:: How to choose the recipients.
183 * Encrypting a plaintext:: How to encrypt a plaintext.
190 @chapter Introduction
192 `GnuPG Made Easy' (@acronym{GPGME}) is a C language library that
193 allows to add support for cryptography to a program. It is designed
194 to make access to crypto engines like GnuPG or GpgSM easier for
195 applications. @acronym{GPGME} provides a high-level crypto API for
196 encryption, decryption, signing, signature verification and key
199 @acronym{GPGME} uses GnuPG and GpgSM as its backends to support
200 OpenPGP and the Cryptograhic Message Syntax (CMS).
203 * Getting Started:: Purpose of the manual, and how to use it.
204 * Features:: Reasons to install and use @acronym{GPGME}.
205 * Overview:: Basic architecture of the @acronym{GPGME} library.
209 @node Getting Started
210 @section Getting Started
212 This library documents the @acronym{GPGME} library programming
213 interface. All functions and data types provided by the library are
216 The reader is assumed to posess basic knowledge about cryptography in
217 general, and public key cryptography in particular. The underlying
218 cryptographic engines that are used by the library are not explained,
219 but where necessary, special features or requirements by an engine are
220 mentioned as far as they are relevant to @acronym{GPGME} or its users.
222 This manual can be used in several ways. If read from the beginning
223 to the end, it gives a good introduction into the library and how it
224 can be used in an application. Forward references are included where
225 necessary. Later on, the manual can be used as a reference manual to
226 get just the information needed about any particular interface of the
227 library. Experienced programmers might want to start looking at the
228 examples at the end of the manual, and then only read up those parts
229 of the interface which are unclear.
235 @acronym{GPGME} has a couple of advantages over other libraries doing
236 a similar job, and over implementing support for GnuPG or other crypto
237 engines into your application directly.
240 @item it's free software
241 Anybody can use, modify, and redistribute it under the terms of the GNU
242 General Public License (@pxref{Copying}).
245 @acronym{GPGME} provides transparent support for several cryptographic
246 protocols by different engines. Currently, @acronym{GPGME} supports
247 the OpenPGP protocol using GnuPG as the backend, and the Cryptographic
248 Message Syntax using GpgSM as the backend.
251 @acronym{GPGME} hides the differences between the protocols and
252 engines from the programmer behind an easy-to-use interface. This way
253 the programmer can focus on the other parts of the program, and still
254 integrate strong cryptography in his application. Once support for
255 @acronym{GPGME} has been added to a program, it is easy to add support
256 for other crypto protocols once @acronym{GPGME} backends provide them.
263 @acronym{GPGME} provides a data abstraction that is used to pass data
264 to the crypto engine, and receive returned data from it. Data can be
265 read from memory or from files, but it can also be provided by a
268 The actual cryptographic operations are always set within a context.
269 A context provides configuration parameters that define the behaviour
270 of all operations performed within it. Only one operation per context
271 is allowed at any time, but when one operation is finished, you can
272 run the next operation in the same context. There can be more than
273 one context, and all can run different operations at the same time.
275 Furthermore, @acronym{GPGME} has rich key management facilities
276 including listing keys, querying their attributes, generating,
277 importing, exporting and deleting keys, and acquiring information
278 about the trust path.
280 @strong{Caution:} The @acronym{GPGME} library is not thread-safe. It
281 will be to some extent in the future, but currently great care has to
282 be taken if @acronym{GPGME} is used in a multi-threaded environment.
288 To use @acronym{GPGME}, you have to perform some changes to your
289 sources and the build system. The necessary changes are small and
290 explained in the following sections. At the end of this chapter, it
291 is described how the library is initialized, and how the requirements
292 of the library are verified.
295 * Header:: What header file you need to include.
296 * Building the source:: Compiler options to be used.
297 * Library version check:: Getting and verifying the library version.
304 All interfaces (data types and functions) of the library are defined
305 in the header file `gpgme.h'. You must include this in all programs
306 using the library, either directly or through some other header file,
313 The name space of @acronym{GPGME} is @code{gpgme_*} for function
314 names, @code{Gpgme*} for data types and @code{GPGME_*} for other
318 @node Building the source
319 @section Building the source
321 If you want to compile a source file including the `gpgme.h' header
322 file, you must make sure that the compiler can find it in the
323 directory hierarchy. This is accomplished by adding the path to the
324 directory in which the header file is located to the compilers include
325 file search path (via the @option{-I} option).
327 However, the path to the include file is determined at the time the
328 source is configured. To solve this problem, gpgme ships with a small
329 helper program @command{gpgme-config} that knows about the path to the
330 include file and other configuration options. The options that need
331 to be added to the compiler invocation at compile time are output by
332 the @option{--cflags} option to @command{gpgme-config}. The following
333 example shows how it can be used at the command line:
336 gcc -c foo.c `gpgme-config --cflags`
339 Adding the output of @samp{gpgme-config --cflags} to the compilers
340 command line will ensure that the compiler can find the @acronym{GPGME} header
343 A similar problem occurs when linking the program with the library.
344 Again, the compiler has to find the library files. For this to work,
345 the path to the library files has to be added to the library search
346 path (via the @option{-L} option). For this, the option
347 @option{--libs} to @command{gpgme-config} can be used. For
348 convenience, this option also outputs all other options that are
349 required to link the program with @acronym{GPGME} (in particular, the
350 @samp{-lgpgme} option). The example shows how to link @file{foo.o}
351 with the @acronym{GPGME} library to a program @command{foo}.
354 gcc -o foo foo.o `gpgme-config --libs`
357 Of course you can also combine both examples to a single command by
358 specifying both options to @command{gpgme-config}:
361 gcc -o foo foo.c `gpgme-config --cflags --libs`
365 @node Library version check
366 @section Library version check
368 @deftypefun {const char *} gpgme_check_version (@w{const char *@var{required_version}})
369 The function @code{gpgme_check_version} has three purposes. It can be
370 used to retrieve the version number of the library. In addition it
371 can verify that the version number is higher than a certain required
372 version number. In either case, the function initializes some
373 sub-systems, and for this reason alone it must be invoked early in
374 your program, before you make use of the other functions in
377 If @var{required_version} is @code{NULL}, the function returns a
378 pointer to a statically allocated string containing the version number
381 If @var{required_version} is not @code{NULL}, it should point to a
382 string containing a version number, and the function checks that the
383 version of the library is at least as high as the version number
384 provided. In this case, the function returns a pointer to a
385 statically allocated string containing the version number of the
386 library. If @var{REQUIRED_VERSION} is not a valid version number, or
387 if the version requirement is not met, the function returns
390 If you use a version of a library that is backwards compatible with
391 older releases, but contains additional interfaces which your program
392 uses, this function provides a run-time check if the necessary
393 features are provided by the installed version of the library.
397 @node Protocols and Engines
398 @chapter Protocols and Engines
400 @acronym{GPGME} supports several cryptographic protocols, however, it
401 does not implement them. Rather it uses backends (also called
402 engines) which implement the protocol. @acronym{GPGME} uses
403 inter-process communication to pass data back and forth between the
404 application and the backend, but the details of the communication
405 protocol and invocation of the backends is completely hidden by the
406 interface. All complexity is handled by @acronym{GPGME}. Where an
407 exchange of information between the application and the backend is
408 necessary, @acronym{GPGME} provides the necessary callback function
409 hooks and further interfaces.
411 @deftp {Data type} {enum GpgmeProtocol}
412 The @code{GpgmeProtocol} type specifies the set of possible protocol
413 values that are supported by @acronym{GPGME}. The following protocols
417 @item GPGME_PROTOCOL_OpenPGP
418 This specifies the OpenPGP protocol.
419 @item GPGME_PROTOCOL_CMS
420 This specifies the Cryptographic Message Syntax.
425 * Engine version check:: Verifying the engine version.
426 * Engine information:: Obtaining more information about the engines.
427 * OpenPGP:: Support for the OpenPGP protocol.
428 * Cryptographic Message Syntax:: Support for the CMS.
432 @node Engine version check
433 @section Engine version check
435 @deftypefun GpgmeError gpgme_engine_check_version (@w{GpgmeProtocol @var{protocol}})
436 The function @code{gpgme_engine_check_version} verifies that the
437 engine implementing the protocol @var{PROTOCOL} is installed in the
438 expected path and meets the version requirement of @acronym{GPGME}.
440 This function returns @code{GPGME_No_Error} if the engine is available
441 and @code{GPGME_Invalid_Engine} if it is not.
444 @deftypefun GpgmeError gpgme_check_engine (void)
445 The function @code{gpgme_check_engine} is equivalent to
448 gpgme_engine_check_version (GPGME_PROTOCOL_OpenPGP);
451 This function is deprecated and provided for backwards compatibility
452 only. It is obsoleted by @code{gpgme_engine_check_version}.
456 @node Engine information
457 @section Engine information
459 @deftypefun {const char *} gpgme_get_engine_info (void)
460 The function @code{gpgme_get_engine_info} returns an @acronym{XML}
461 string containing information about the available protocols and the
462 engine which implement them. The following information is returned
467 The name of the protocol.
469 The version of the engine.
471 The path to the engine binary.
474 A string is always returned. If an error occurs, the string will
475 contain an @samp{<error>} tag with a description of the failure.
478 Here is the example output of what @code{gpgme_get_engine_info} might
479 return on your system:
484 <protocol>OpenPGP</protocol>
485 <version>1.0.6</version>
486 <path>/usr/bin/gpg</path>
489 <protocol>CMS</protocol>
490 <version>0.0.0</version>
491 <path>/usr/bin/gpgsm</path>
500 OpenPGP is implemented by GnuPG, the @acronym{GNU} Privacy Guard.
501 This is the first protocol that was supported by @acronym{GPGME}.
503 The OpenPGP protocol is specified by @code{GPGME_PROTOCOL_OpenPGP}.
506 @node Cryptographic Message Syntax
507 @section Cryptographic Message Syntax
509 @acronym{CMS} is implemented by GpgSM, the S/MIME implementation for
512 The @acronym{CMS} protocol is specified by @code{GPGME_PROTOCOL_CMS}.
516 @chapter Error Handling
518 Many functions in @acronym{GPGME} can return an error if they fail.
519 For this reason, the application should always catch the error
520 condition and take appropriate measures, for example by releasing the
521 resources and passing the error up to the caller, or by displaying a
522 descriptive message to the user and cancelling the operation.
524 Some error values do not indicate a system error or an error in the
525 operation, but the result of an operation that failed properly. For
526 example, if you try to decrypt a tempered message, the decryption will
527 fail. Another error value actually means that the end of a data
528 buffer or list has been reached. The following descriptions explain
529 what each error message means in general. Some error values have
530 specific meanings if returned by a specific function. Such cases are
531 described in the documentation of those functions.
534 * Error values:: A list of all error values used.
535 * Error strings:: How to get a descriptive string from a value.
540 @section Error values
542 @deftp {Data type} {enum GpgmeError}
543 The @code{GpgmeError} type specifies the set of all error values that
544 are used by @acronym{GPGME}. Possible values are:
548 This value indicates the end of a list, buffer or file.
551 This value indicates success. The value of this error is @code{0}.
553 @item GPGME_General_Error
554 This value means that something went wrong, but either there is not
555 enough information about the problem to return a more useful error
556 value, or there is no seperate error value for this type of problem.
558 @item GPGME_Out_Of_Core
559 This value means that an out-of-memory condition occured.
561 @item GPGME_Invalid_Value
562 This value means that some user provided data was out of range. This
563 can also refer to objects. For example, if an empty @code{GpgmeData}
564 object was expected, but one containing data was provided, this error
568 This value is returned if you try to start a new operation in a
569 context that is already busy with some earlier operation which was not
570 canceled or finished yet.
572 @item GPGME_No_Request
573 This value is in some sense the opposite of @code{GPGME_Busy}. There
574 is no pending operation, but it is required for the function to
577 @item GPGME_Exec_Error
578 This value means that an error occured when trying to spawn a child
581 @item GPGME_Too_Many_Procs
582 This value means that there are too many active backend processes.
584 @item GPGME_Pipe_Error
585 This value means that the creation of a pipe failed.
587 @item GPGME_No_Recipients
588 This value means that no recipients for a message have been set.
591 This value means that a @code{GpgmeData} object which was expected to
592 have content was found empty.
595 This value means that a conflict of some sort occured.
597 @item GPGME_Not_Implemented
598 This value indicates that the specific function (or operation) is not
599 implemented. This error should never happen. It can only occur if
600 you use certain values or configuration options which do not work,
601 but for which we think that they should work at some later time.
603 @item GPGME_Read_Error
604 This value means that an I/O read operation failed.
606 @item GPGME_Write_Error
607 This value means that an I/O write operation failed.
609 @item GPGME_Invalid_Type
610 This value means that a user provided object was of a wrong or
611 incompatible type. Usually this refers to the type of a
612 @code{GpgmeData} object.
614 @item GPGME_Invalid_Mode
615 This value means that a @code{GpgmeData} object has an incorrect mode
616 of operation (for example, doesn't support output although it is
617 attempted to use it as an output buffer).
619 @item GPGME_File_Error
620 This value means that a file I/O operation failed. The value of
621 @code{errno} contains the system error value.
623 @item GPGME_Decryption_Failed
624 This value indicates that a decryption operation was unsuccessful.
626 @item GPGME_No_Passphrase
627 This value means that the user did not provide a passphrase when
631 This value means that the operation was canceled.
633 @item GPGME_Invalid_Key
634 This value means that a key was invalid.
636 @item GPGME_Invalid_Engine
637 This value means that the engine that implements the desired protocol
638 is currently not available. This can either be because the sources
639 were configured to exclude support for this engine, or because the
640 engine is not installed properly.
646 @section Error strings
648 @deftypefun {const char *} gpgme_strerror (@w{GpgmeError @var{err}})
649 The function @code{gpgme_strerror} returns a pointer to a statically
650 allocated string containing a description of the error with the error
651 value @var{err}. This string can be used to output a diagnostic
656 @node Exchanging Data
657 @chapter Exchanging Data
659 A lot of data has to be exchanged between the user and the crypto
660 engine, like plaintext messages, ciphertext, signatures and
661 information about the keys. The technical details about exchanging
662 the data information are completely abstracted by @acronym{GPGME}.
663 The user provides and receives the data via @code{GpgmeData} objects,
664 regardless of the communication protocol between @acronym{GPGME} and
665 the crypto engine in use.
667 @deftp {Data type} {GpgmeData}
668 The @code{GpgmeData} type is a handle for a container for generic
669 data, which is used by @acronym{GPGME} to exchange data with the user.
673 * Creating data buffers:: Creating new data buffers.
674 * Destroying data buffers:: Releasing data buffers.
675 * Manipulating data buffers:: Operations on data buffers.
679 @node Creating data buffers
680 @section Creating data buffers
682 @deftypefun GpgmeError gpgme_data_new (@w{GpgmeData *@var{dh}})
683 The function @code{gpgme_data_new} creates a new @code{GpgmeData}
684 object and returns a handle for it in @var{dh}. The data object is
687 The function returns @code{GPGME_No_Error} if the data object was
688 successfully created, @code{GPGME_Invalid_Value} if @var{dh} is not a
689 valid pointer, and @code{GPGME_Out_Of_Core} if not enough memory is
693 @deftypefun GpgmeError gpgme_data_new_from_mem (@w{GpgmeData *@var{dh}}, @w{const char *@var{buffer}}, @w{size_t @var{size}}, @w{int @var{copy}})
694 The function @code{gpgme_data_new_from_mem} creates a new
695 @code{GpgmeData} object and fills it with @var{size} bytes starting
698 If @var{copy} is not zero, a private copy of the data is made. If
699 @var{copy} is zero, the data is taken from the specified buffer as
700 needed, and the user has to ensure that the buffer remains valid for
701 the whole life span of the data object.
703 The function returns @code{GPGME_No_Error} if the data object was
704 successfully created, @code{GPGME_Invalid_Value} if @var{dh} or
705 @var{buffer} is not a valid pointer, and @code{GPGME_Out_Of_Core} if
706 not enough memory is available.
709 @deftypefun GpgmeError gpgme_data_new_from_file (@w{GpgmeData *@var{dh}}, @w{const char *@var{filename}}, @w{int @var{copy}})
710 The function @code{gpgme_data_new_from_file} creates a new
711 @code{GpgmeData} object and fills it with the content of the file
714 If @var{copy} is not zero, the whole file is read in at initialization
715 time and the file is not used anymore after that. This is the only
716 mode supported currently. Later, a value of zero for @var{copy} might
717 cause all reads to be delayed until the data is needed, but this is
720 The function returns @code{GPGME_No_Error} if the data object was
721 successfully created, @code{GPGME_Invalid_Value} if @var{dh} or
722 @var{filename} is not a valid pointer, @code{GPGME_File_Error} if an
723 I/O operation fails, @code{GPGME_Not_Implemented} if @var{code} is
724 zero, and @code{GPGME_Out_Of_Core} if not enough memory is available.
727 @deftypefun GpgmeError gpgme_data_new_from_filepart (@w{GpgmeData *@var{dh}}, @w{const char *@var{filename}}, @w{FILE *@var{fp}}, @w{off_t @var{offset}}, @w{size_t @var{length}})
728 The function @code{gpgme_data_new_from_filepart} creates a new
729 @code{GpgmeData} object and fills it with a part of the file specified
730 by @var{filename} or @var{fp}.
732 Exactly one of @var{filename} and @var{fp} must be non-zero, the other
733 must be zero. The argument that is not zero specifies the file from
734 which @var{length} bytes are read into the data object, starting from
737 The function returns @code{GPGME_No_Error} if the data object was
738 successfully created, @code{GPGME_Invalid_Value} if @var{dh} and
739 exactly one of @var{filename} and @var{fp} is not a valid pointer,
740 @code{GPGME_File_Error} if an I/O operation fails, and
741 @code{GPGME_Out_Of_Core} if not enough memory is available.
745 @deftypefun GpgmeError gpgme_data_new_with_read_cb (@w{GpgmeData *@var{dh}}, @w{int (*@var{readfunc})} (@w{void *@var{hook}}, @w{char *@var{buffer}}, @w{size_t @var{count}}, @w{size_t *@var{nread}}), @w{void *@var{hook_value}})
746 The function @code{gpgme_data_new_with_read_cb} creates a new
747 @code{GpgmeData} object and uses the callback function @var{readfunc}
748 to retrieve the data on demand. As the callback function can supply
749 the data in any way it wants, this is the most flexible data type
750 @acronym{GPGME} provides. However, it can not be used to write data.
752 The callback function receives @var{hook_value} as its first argument
753 whenever it is invoked. It should return up to @var{count} bytes in
754 @var{buffer}, and return the number of bytes actually read in
755 @var{nread}. It may return @code{0} in @var{nread} if no data is
756 currently available. To indicate @code{EOF} the function should
757 return with an error code of @code{-1} and set @var{nread} to
758 @code{0}. The callback function may support to reset its internal
759 read pointer if it is invoked with @var{buffer} and @var{nread} being
760 @code{NULL} and @var{count} being @code{0}.
762 The function returns @code{GPGME_No_Error} if the data object was
763 successfully created, @code{GPGME_Invalid_Value} if @var{dh} or
764 @var{readfunc} is not a valid pointer, and @code{GPGME_Out_Of_Core} if
765 not enough memory is available.
769 @node Destroying data buffers
770 @section Destroying data buffers
772 @deftypefun void gpgme_data_release (@w{GpgmeData @var{dh}})
773 The function @code{gpgme_data_release} destroys the data object with
774 the handle @var{dh}. It releases all associated resources that were
775 not provided by the user in the first place.
778 @deftypefun {char *} gpgme_data_release_and_get_mem (@w{GpgmeData @var{dh}}, @w{size_t *@var{length}})
779 The function @code{gpgme_data_release_and_get_mem} is like
780 @code{gpgme_data_release}, except that it returns the data buffer and
781 its length that was provided by the object.
783 The user has to release the buffer with @code{free}. In case the user
784 provided the data buffer in non-copy mode, a copy will be made for
787 In case an error returns, or there is no suitable data buffer that can
788 be returned to the user, the function will return @code{NULL}.
792 @node Manipulating data buffers
793 @section Manipulating data buffers
795 @deftypefun GpgmeError gpgme_data_read (@w{GpgmeData @var{dh}}, @w{char *@var{buffer}}, @w{size_t @var{length}}, @w{size_t *@var{nread}})
796 The function @code{gpgme_data_read} reads up to @var{length} bytes
797 from the data object with the handle @var{dh} into the space starting
798 at @var{buffer}. The actual amount read is returned in @var{nread}.
800 If @var{buffer} is @code{NULL}, the function returns the amount of
801 bytes available in @var{nread} without changing the read pointer.
802 This is not supported by all types of data objects. If this function
803 is not supported, @code{GPGME_Invalid_Type} is returned.
805 If the end of the data object is reached, the function returns
806 @code{GPGME_EOF} and sets @var{nread} to zero.
808 In all other cases, the function returns @code{GPGME_No_Error} if the
809 operation was successfully performed and @code{GPGME_Invalid_Value} if
810 @var{dh} is not a valid pointer.
813 @deftypefun GpgmeError gpgme_data_rewind (@w{GpgmeData @var{dh}})
814 The function @code{gpgme_data_rewind} resets the read pointer of the
815 data object with the handle @var{dh}, so that a subsequent
816 @code{gpgme_data_read} operation starts at the beginning of the data.
818 The function returns @code{GPGME_No_Error} if the operation was
819 successfully performed, @code{GPGME_Not_Implemented} if the operation
820 is not supported (for example, by a read callback function supplied by
821 the user) and @code{GPGME_Invalid_Value} if @var{dh} is not a valid
825 @deftypefun GpgmeError gpgme_data_write (@w{GpgmeData @var{dh}}, @w{const char *@var{buffer}}, @w{size_t @var{length}})
826 The function @code{gpgme_data_write} writes @var{length} bytes
827 starting from @var{buffer} into the data object with the handle
828 @var{dh} at the current write position.
830 The function returns @code{GPGME_No_Error} if the operation was
831 successfully performed, @code{GPGME_Invalid_Value} if @var{dh} or
832 @var{buffer} is not a valid pointer, @code{GPGME_Invalid_Type} or
833 @code{GPGME_Invalid_Mode} if the data object type does not support
834 writing, and @code{GPGME_Out_Of_Core} if not enough memory is
838 @deftp {Data type} {enum GpgmeDataType}
839 The @code{GpgmeDataType} type specifies the type of a @code{GpgmeData} object.
840 The following data types are available:
843 @item GPGME_DATA_TYPE_NONE
844 This specifies that the type is not yet determined.
846 @item GPGME_DATA_TYPE_MEM
847 This specifies that the data is stored in memory.
849 @item GPGME_DATA_TYPE_FD
850 This type is not implemented.
852 @item GPGME_DATA_TYPE_FILE
853 This type is not implemented.
855 @item GPGME_DATA_TYPE_CB
856 This type specifies that the data is provided by a callback function
857 implemented by the user.
861 @deftypefun GpgmeDataType gpgme_data_get_type (@w{GpgmeData @var{dh}})
862 The function @code{gpgme_data_get_type} returns the type of the data
863 object with the handle @var{dh}. If @var{dh} is not a valid pointer,
864 @code{GPGME_DATA_TYPE_NONE} is returned.
871 All cryptograhic operations in @acronym{GPGME} are performed within a
872 context, which contains the internal state of the operation as well as
873 configuration parameters. By using several contexts you can run
874 several cryptographic operations in parallel, with different
877 @deftp {Data type} {GpgmeCtx}
878 The @code{GpgmeCtx} type is a handle for a @acronym{GPGME} context,
879 which is used to hold the configuration, status and result of
880 cryptographic operations.
884 * Creating contexts:: Creating new @acronym{GPGME} contexts.
885 * Destroying contexts:: Releasing @acronym{GPGME} contexts.
886 * Context attributes:: Setting properties of a context.
887 * Key Management:: Managing keys with @acronym{GPGME}.
888 * Trust Item Management:: Managing trust items with @acronym{GPGME}.
889 * Crypto Operations:: Using a context for cryptography.
893 @node Creating contexts
894 @section Creating contexts
896 @deftypefun GpgmeError gpgme_new (@w{GpgmeCtx *@var{ctx}})
897 The function @code{gpgme_data_new} creates a new @code{GpgmeCtx}
898 object and returns a handle for it in @var{ctx}.
900 The function returns @code{GPGME_No_Error} if the context was
901 successfully created, @code{GPGME_Invalid_Value} if @var{ctx} is not a
902 valid pointer, and @code{GPGME_Out_Of_Core} if not enough memory is
908 @node Destroying contexts
909 @section Destroying contexts
911 @deftypefun void gpgme_release (@w{GpgmeCtx @var{ctx}})
912 The function @code{gpgme_release} destroys the context with the handle
913 @var{ctx} and releases all associated resources.
917 @node Context attributes
918 @section Context attributes
921 * Protocol selection:: Selecting the protocol used by a context.
922 * @acronym{ASCII} armor:: Requesting @acronym{ASCII} armored output.
923 * Text mode:: Choosing canonical text mode.
924 * Key listing mode:: Selecting key listing mode.
925 * Passphrase callback:: Getting the passphrase from the user.
926 * Progress meter callback:: Being informed about the progress.
930 @node Protocol selection
931 @subsection Protocol selection
933 @deftypefun GpgmeError gpgme_set_protocol (@w{GpgmeCtx @var{ctx}}, @w{GpgmeProtocol @var{proto}})
934 The function @code{gpgme_set_protocol} sets the protocol used within
935 the context @var{ctx} to @var{proto}. All crypto operations will be
936 performed by the crypto engine configured for that protocol.
937 @xref{Protocols and Engines}.
939 Setting the protocol with @code{gpgme_set_protocol} does not check if
940 the crypto engine for that protocol is available and installed
941 correctly. @xref{Engine version check}.
943 The function returns @code{GPGME_No_Error} if the protocol could be
944 set successfully, and @code{GPGME_Invalid_Value} if @var{protocol} is
945 not a valid protocol.
949 @node @acronym{ASCII} armor
950 @subsection @acronym{ASCII} armor
952 @deftypefun void gpgme_set_armor (@w{GpgmeCtx @var{ctx}}, @w{int @var{yes}})
953 The function @code{gpgme_set_armor} specifies if the output should be
954 @acronym{ASCII} armored. By default, output is not @acronym{ASCII}
957 @acronym{ASCII} armored output is disabled if @var{yes} is zero, and
961 @deftypefun int gpgme_get_armor (@w{GpgmeCtx @var{ctx}})
962 The function @code{gpgme_get_armor} returns 1 if the output is
963 @acronym{ASCII} armored, and @code{0} if it is not, or if @var{ctx} is
969 @subsection Text mode
971 @deftypefun void gpgme_set_textmode (@w{GpgmeCtx @var{ctx}}, @w{int @var{yes}})
972 The function @code{gpgme_set_textmode} specifies if canonical text mode
973 should be used. By default, text mode is not used.
975 Text mode is for example used for the RFC2015 signatures; note that
976 the updated RFC 3156 mandates that the mail user agent does some
977 preparations so that text mode is not needed anymore.
979 Canonical text mode is disabled if @var{yes} is zero, and enabled
983 @deftypefun int gpgme_get_textmode (@w{GpgmeCtx @var{ctx}})
984 The function @code{gpgme_get_textmode} returns 1 if canonical text
985 mode is enabled, and @code{0} if it is not, or if @var{ctx} is not a
990 @node Key listing mode
991 @subsection Key listing mode
993 @deftypefun void gpgme_set_keylist_mode (@w{GpgmeCtx @var{ctx}}, @w{int @var{mode}})
994 The function @code{gpgme_set_keylist_mode} changes the default
995 behaviour of the key listing functions. Defined values for @var{mode}
1002 Fast listing without information about the key validity.
1007 @node Passphrase callback
1008 @subsection Passphrase callback
1010 @deftp {Data type} {const char *(*GpgmePassphraseCb)(void *@var{hook}, const char *@var{desc}, void *@var{r_hd})}
1011 The @code{GpgmePasshraseCb} type is the type of functions usable as
1012 passphrase callback function.
1014 The string @var{desc} contains a test usable to be displayed to the
1015 user of the application. The function should return a passphrase for
1016 the context when invoked with @var{desc} not being @code{NULL}.
1018 The user may store information about the resources associated with the
1019 returned passphrase in @var{*r_hd}. When the passphrase is no longer
1020 needed by @acronym{GPGME}, the passphrase callback function will be
1021 called with @var{desc} being @var{NULL}, and @var{r_hd} being the same
1022 as at the first invocation.
1025 @deftypefun void gpgme_set_passphrase_cb (@w{GpgmeCtx @var{ctx}}, @w{GpgmePassphraseCb @var{passfunc}}, @w{void *@var{hook_value}})
1026 The function @code{gpgme_set_passphrase_cb} sets the function that is
1027 used when a passphrase needs to be provided by the user to
1028 @var{passfunc}. The function @var{passfunc} needs to implemented by
1029 the user, and whenever it is called, it is called with its first
1030 argument being @var{hook_value}. By default, no passphrase callback
1033 Not all crypto engines require this callback to retrieve the
1034 passphrase. It is better if the engine retrieves the passphrase from
1035 a trusted agent (a daemon process), rather than having each user to
1036 implement their own passphrase query.
1038 The user can disable the use of a passphrase callback function by
1039 calling @code{gpgme_set_passphrase_cb} with @var{passfunc} being
1044 @node Progress meter callback
1045 @subsection Progress meter callback
1047 @deftp {Data type} {const char *(*GpgmeProgressCb)(void *@var{hook}, const char *@var{what}, int @var{type}, int @var{current}, int @var{total})}
1048 The @code{GpgmeProgressCb} type is the type of functions usable as
1049 progress callback function.
1051 The arguments are specific to the crypto engine. More information
1052 about the progress information returned from the GnuPG engine can be
1053 found in the GnuPG source code in the file @file{doc/DETAILS} in the
1057 @deftypefun void gpgme_set_progress_cb (@w{GpgmeCtx @var{ctx}}, @w{GpgmeProgressCb @var{progfunc}}, @w{void *@var{hook_value}})
1058 The function @code{gpgme_set_progress_cb} sets the function that is
1059 used when progress information about a cryptographic operation is
1060 available. The function @var{progfunc} needs to implemented by the
1061 user, and whenever it is called, it is called with its first argument
1062 being @var{hook_value}. By default, no progress callback function
1065 Setting a callback function allows an interactive program to display
1066 progress information about a long operation to the user.
1068 The user can disable the use of a progress callback function by
1069 calling @code{gpgme_set_progress_cb} with @var{progfunc} being
1074 @node Key Management
1075 @section Key Management
1077 Some of the cryptographic operations require that recipients or
1078 signers are specified. This is always done by specifying the
1079 respective keys that should be used for the operation. The following
1080 section describes how such keys can be selected and manipulated.
1082 @deftp {Data type} GpgmeKey
1083 The @code{GpgmeKey} type is a handle for a public or secret key, and
1084 is used to select the key for operations involving it.
1086 A key can contain several user IDs and sub keys.
1090 * Listing keys:: Browsing the list of available keys.
1091 * Information about keys:: Requesting detailed information about keys.
1092 * Manipulating keys:: Operations on keys.
1093 * Generating keys:: Creating new key pairs.
1094 * Exporting keys:: Retrieving key data from the key ring.
1095 * Importing keys:: Adding keys to the keyring.
1096 * Deleting keys:: Removing keys from the keyring.
1101 @subsection Listing keys
1103 @deftypefun GpgmeError gpgme_op_keylist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}})
1104 The function @code{gpgme_op_keylist_start} initiates a key listing
1105 operation inside the context @var{ctx}. It sets everything up so that
1106 subsequent invocations of @code{gpgme_op_keylist_next} return the keys
1109 If @var{pattern} is @code{NULL}, all available keys are returned.
1110 Otherwise, @var{pattern} contains an engine specific expression that
1111 is used to limit the list to all keys matching the pattern.
1113 If @var{secret_only} is not @code{0}, the list is restricted to secret
1116 The context will be busy until either all keys are received (and
1117 @code{gpgme_op_keylist_next} returns @code{GPGME_EOF}), or
1118 @code{gpgme_op_keylist_end} is called to finish the operation.
1120 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
1121 valid pointer, and passes through any errors that are reported by the
1122 crypto engine support routines.
1125 @deftypefun GpgmeError gpgme_op_keylist_next (@w{GpgmeCtx @var{ctx}}, @w{GpgmeKey *@var{r_key}})
1126 The function @code{gpgme_op_keylist_next} returns the next key in the
1127 list created by a previous @code{gpgme_op_keylist_start} operation in
1128 the context @var{ctx}. The key will have one reference for the user.
1129 @xref{Manipulating keys}.
1131 This is the only way to get at @code{GpgmeKey} objects in
1134 If the last key in the list has already been returned,
1135 @code{gpgme_op_keylist_next} returns @code{GPGME_EOF}.
1137 The function returns @code{GPGME_Invalid_Value} if @var{ctx} or
1138 @var{r_key} is not a valid pointer, @code{GPGME_No_Request} if there
1139 is no pending operation, @code{GPGME_Out_Of_Core} if there is not
1140 enough memory for the operation.
1143 @deftypefun GpgmeError gpgme_op_keylist_end (@w{GpgmeCtx @var{ctx}})
1144 The function @code{gpgme_op_keylist_next} ends a pending key list
1145 operation in the context @var{ctx}.
1147 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
1148 valid pointer, @code{GPGME_No_Request} if there is no pending
1149 operation, @code{GPGME_Out_Of_Core} if at some time during the
1150 operation there was not enough memory available.
1154 @node Information about keys
1155 @subsection Information about keys
1157 @deftypefun {char *} gpgme_key_get_as_xml (@w{GpgmeKey @var{key}})
1158 The function @code{gpgme_key_get_as_xml} returns a string in
1159 @acronym{XML} format describing the key @var{key}. The user has to
1160 release the string with @code{free}.
1162 The function returns @code{NULL} if @var{key} is not a valid pointer,
1163 or there is not enough memory available.
1166 @deftp {Data type} GpgmeAttr
1167 The @code{GpgmeAttr} type is used to specify a key or trust item
1168 attribute. The following attributes are defined:
1171 @item GPGME_ATTR_KEYID
1172 This is the key ID of a sub key. It is representable as a string.
1174 For trust items, the trust item refers to the key with this ID.
1176 @item GPGME_ATTR_FPR
1177 This is the fingerprint of a sub key. It is representable as a
1180 @item GPGME_ATTR_ALGO
1181 This is the crypto algorithm for which the sub key can be used. It
1182 is representable as a string and as a number. The numbers correspond
1183 to the @code{enum gcry_pk_algos} values in the gcrypt library.
1185 @item GPGME_ATTR_LEN
1186 This is the key length of a sub key. It is representable as a
1189 @item GPGME_ATTR_CREATED
1190 This is the timestamp at creation time of a sub key. It is
1191 representable as a number.
1193 @item GPGME_ATTR_EXPIRE
1196 @item GPGME_ATTR_OTRUST
1197 XXX FIXME (also for trust items)
1199 @item GPGME_ATTR_USERID
1200 This is a user ID. There can be more than one user IDs in a
1201 @var{GpgmeKey} object. The first one (with index 0) is the primary
1202 user ID. The user ID is representable as a number.
1204 For trust items, this is the user ID associated with this trust item.
1206 @item GPGME_ATTR_NAME
1207 This is the name belonging to a user ID. It is representable as a string.
1209 @item GPGME_ATTR_EMAIL
1210 This is the email address belonging to a user ID. It is representable
1213 @item GPGME_ATTR_COMMENT
1214 This is the comment belonging to a user ID. It is representable as a
1217 @item GPGME_ATTR_VALIDITY
1218 This is the validity belonging to a user ID. It is representable as a
1219 string and as a number. See below for a list of available validities.
1221 For trust items, this is the validity that is associated with this
1224 @item GPGME_ATTR_UID_REVOKED
1225 This specifies if a user ID is revoked. It is representable as a
1226 number, and is @code{1} if the user ID is revoked, and @code{0}
1229 @item GPGME_ATTR_UID_INVALID
1230 This specifies if a user ID is invalid. It is representable as a
1231 number, and is @code{1} if the user ID is invalid, and @code{0}
1234 @item GPGME_ATTR_LEVEL
1235 This is the trust level of a trust item.
1237 @item GPGME_ATTR_TYPE
1238 This is the type of a trust item.
1240 @item GPGME_ATTR_IS_SECRET
1241 This specifies if the key is a secret key. It is representable as a
1242 string or a number. If the key is a secret key, the representation is
1243 ``1'' or @code{1}, otherwise it is NULL or @code{0}.
1245 @item GPGME_ATTR_KEY_REVOKED
1246 This specifies if a sub key is revoked. It is representable as a
1247 number, and is @code{1} if the key is revoked, and @code{0} otherwise.
1249 @item GPGME_ATTR_KEY_INVALID
1250 This specifies if a sub key is invalid. It is representable as a
1251 number, and is @code{1} if the key is invalid, and @code{0} otherwise.
1253 @item GPGME_ATTR_KEY_EXPIRED
1254 This specifies if a sub key is expired. It is representable as a
1255 number, and is @code{1} if the key is expired, and @code{0} otherwise.
1257 @item GPGME_ATTR_KEY_DISABLED
1258 This specifies if a sub key is disabled. It is representable as a
1259 number, and is @code{1} if the key is disabled, and @code{0} otherwise.
1261 @item GPGME_ATTR_KEY_CAPS
1262 This is a description of the capabilities of a sub key. It is
1263 representable as a string. The string contains the letter ``e'' if
1264 the key can be used for encryption, ``s'' if the key can be used for
1265 signatures, and ``c'' if the key can be used for certifications.
1267 @item GPGME_ATTR_CAN_ENCRYPT
1268 This specifies if a sub key can be used for encryption. It is
1269 representable as a number, and is @code{1} if the sub key can be used
1270 for encryption, and @code{0} otherwise.
1272 @item GPGME_ATTR_CAN_SIGN
1273 This specifies if a sub key can be used for signatures. It is
1274 representable as a number, and is @code{1} if the sub key can be used
1275 for signatures, and @code{0} otherwise.
1277 @item GPGME_ATTR_CAN_CERTIFY
1278 This specifies if a sub key can be used for certifications. It is
1279 representable as a number, and is @code{1} if the sub key can be used
1280 for certifications, and @code{0} otherwise.
1284 @deftp {Data type} GpgmeValidity
1285 The @code{GpgmeValidity} type is used to specify the validity of a user ID
1286 in a key. The following validities are defined:
1289 @item GPGME_VALIDITY_UNKNOWN
1290 The user ID is of unknown validity. The string representation of this
1293 @item GPGME_VALIDITY_UNDEFINED
1294 The validity of the user ID is undefined. The string representation of this
1297 @item GPGME_VALIDITY_NEVER
1298 The user ID is never valid. The string representation of this
1301 @item GPGME_VALIDITY_MARGINAL
1302 The user ID is marginally valid. The string representation of this
1305 @item GPGME_VALIDITY_FULL
1306 The user ID is fully valid. The string representation of this
1309 @item GPGME_VALIDITY_ULTIMATE
1310 The user ID is ultimately valid. The string representation of this
1315 @deftypefun {const char *} gpgme_key_get_string_attr (@w{GpgmeKey @var{key}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
1316 The function @code{gpgme_key_get_string_attr} returns the value of the
1317 string-representable attribute @var{what} of key @var{key}. If the
1318 attribute occurs more than once in the key, the index is specified by
1319 @var{idx}. This applies to attributes of sub keys and user IDs. The
1320 argument @var{reserved} is reserved for later use and should be
1323 The string returned is only valid as long as the key is valid.
1325 The function returns @code{0} if an attribute can't be returned as a
1326 string, @var{key} is not a valid pointer, @var{idx} out of range,
1327 or @var{reserved} not @code{NULL}.
1330 @deftypefun {unsigned long} gpgme_key_get_ulong_attr (@w{GpgmeKey @var{key}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
1331 The function @code{gpgme_key_get_ulong_attr} returns the value of the
1332 number-representable attribute @var{what} of key @var{key}. If the
1333 attribute occurs more than once in the key, the index is specified by
1334 @var{idx}. This applies to attributes of sub keys and user IDs. The
1335 argument @var{reserved} is reserved for later use and should be
1338 The function returns @code{0} if the attribute can't be returned as a
1339 number, @var{key} is not a valid pointer, @var{idx} out of range,
1340 or @var{reserved} not @code{NULL}.
1344 @node Manipulating keys
1345 @subsection Manipulating keys
1347 @deftypefun void gpgme_key_ref (@w{GpgmeKey @var{key}})
1348 The function @code{gpgme_key_ref} acquires an additional reference for
1352 @deftypefun void gpgme_key_unref (@w{GpgmeKey @var{key}})
1353 @deftypefunx void gpgme_key_release (@w{GpgmeKey @var{key}})
1354 The function @code{gpgme_key_ref} releases a reference for the key
1355 @var{key}. If this was the last reference, the key will be destroyed
1356 and all resources associated to it will be released.
1358 The function @code{gpgme_key_release} is an alias for
1359 @code{gpgme_key_unref}.
1363 @node Generating keys
1364 @subsection Generating keys
1366 @deftypefun GpgmeError gpgme_op_genkey (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{pubkey}}, @w{GpgmeData @var{seckey}})
1367 The function @code{gpgme_op_genkey} generates a new key pair in the
1368 context @var{ctx} and puts it into the standard keyring if both
1369 @var{pubkey} and @var{seckey} are @code{NULL}. In this case the
1370 function returns immediately after starting the operation, and does
1371 not wait for it to complete. @var{pubkey} and @var{seckey} are
1372 reserved for later use and should be @code{NULL}. (The function
1373 should return the public key in the data buffer @var{pubkey} and the
1374 secret key in the data buffer @var{seckey}, but this is not
1377 The argument @var{parms} specifies parameters for the key in an XML
1378 string. The details about the format of @var{parms} are specific to
1379 teh crypto engine used by @var{ctx}. Here is an example for GnuPG as
1385 <GnupgKeyParms format="internal">
1390 Name-Real: Joe Tester
1391 Name-Comment: with stupid passphrase
1392 Name-Email: joe@@foo.bar
1400 Strings should be given in UTF-8 encoding. The only format supported
1401 for now is ``internal''. The content of the @code{GnupgKeyParms}
1402 container is passed verbatim to GnuPG. Control statements are not
1405 The function returns @code{GPGME_No_Error} if the operation could be
1406 started, @code{GPGME_Invalid_Value} if @var{parms} is not a valid XML
1407 string, and @code{GPGME_Not_Supported} if @var{pubkey} or @var{seckey}
1412 @node Exporting keys
1413 @subsection Exporting keys
1415 @deftypefun GpgmeError gpgme_op_export (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{recipients}}, @w{GpgmeData @var{keydata}})
1416 The function @code{gpgme_op_export} extracts the public keys of the
1417 user IDs in @var{recipients} and returns them in the data buffer
1418 @var{keydata}. The type of the public keys returned is determined by
1419 the @acronym{ASCII} armor attribute set for the context @var{ctx}.
1421 The function returns @code{GPGME_No_Error} if the operation completed
1422 successfully, @code{GPGME_Invalid_Value} if @var{recipients} is
1423 @code{NULL} or @var{keydata} is not a valid empty data buffer, and
1424 passes through any errors that are reported by the crypto engine
1429 @node Importing keys
1430 @subsection Importing keys
1432 @deftypefun GpgmeError gpgme_op_import (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}})
1433 The function @code{gpgme_op_import} adds the keys in the data buffer
1434 @var{keydata} to the key ring of the crypto engine used by @var{ctx}.
1435 The format of @var{keydata} can be @var{ASCII} armored, for example,
1436 but the details are specific to the crypto engine.
1438 The function returns @code{GPGME_No_Error} if the import was completed
1439 successfully, @code{GPGME_Invalid_Value} if @var{keydata} if @var{ctx}
1440 or @var{keydata} is not a valid pointer, and @code{GPGME_No_Data} if
1441 @var{keydata} is an empty data buffer.
1446 @subsection Deleting keys
1448 @deftypefun GpgmeError gpgme_op_delete (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}, @w{int @var{allow_secret}})
1449 The function @code{gpgme_op_delete} deletes the key @var{key} from the
1450 key ring of the crypto engine used by @var{ctx}. If
1451 @var{allow_secret} is @code{0}, only public keys are deleted,
1452 otherwise secret keys are deleted as well.
1454 The function returns @code{GPGME_No_Error} if the key was deleted
1455 successfully, and @code{GPGME_Invalid_Value} if @var{ctx} or @var{key}
1456 is not a valid pointer.
1460 @node Trust Item Management
1461 @section Trust Item Management
1463 @strong{Caution:} The trust items interface is experimental.
1465 @deftp {Data type} GpgmeTrustItem
1466 The @code{GpgmeTrustItem} type is a handle for a trust item.
1470 * Listing trust items:: Browsing the list of available trust items.
1471 * Information about trust items:: Requesting detailed information about trust items.
1472 * Manipulating trust items:: Operations on trust items.
1476 @node Listing trust items
1477 @subsection Listing trust items
1479 @deftypefun GpgmeError gpgme_op_trustlist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{max_level}})
1480 The function @code{gpgme_op_trustlist_start} initiates a trust item
1481 listing operation inside the context @var{ctx}. It sets everything up
1482 so that subsequent invocations of @code{gpgme_op_trustlist_next} return
1483 the trsut items in the list.
1485 The string @var{pattern} contains an engine specific expression that
1486 is used to limit the list to all trust items matching the pattern. It
1487 can not be the empty string.
1489 The argument @var{max_level} is currently ignored.
1491 The context will be busy until either all trust items are received
1492 (and @code{gpgme_op_trustlist_next} returns @code{GPGME_EOF}), or
1493 @code{gpgme_op_trustlist_end} is called to finish the operation.
1495 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
1496 valid pointer, and passes through any errors that are reported by the
1497 crypto engine support routines.
1500 @deftypefun GpgmeError gpgme_op_trustlist_next (@w{GpgmeCtx @var{ctx}}, @w{GpgmeTrustItem *@var{r_item}})
1501 The function @code{gpgme_op_trustlist_next} returns the next trust
1502 item in the list created by a previous @code{gpgme_op_trustlist_start}
1503 operation in the context @var{ctx}. The trust item can be destroyed
1504 with @code{gpgme_trust_item_release}. @xref{Manipulating trust items}.
1506 This is the only way to get at @code{GpgmeTrustItem} objects in
1509 If the last trust item in the list has already been returned,
1510 @code{gpgme_op_trustlist_next} returns @code{GPGME_EOF}.
1512 The function returns @code{GPGME_Invalid_Value} if @var{ctx} or
1513 @var{r_item} is not a valid pointer, @code{GPGME_No_Request} if there
1514 is no pending operation, @code{GPGME_Out_Of_Core} if there is not
1515 enough memory for the operation.
1518 @deftypefun GpgmeError gpgme_op_trustlist_end (@w{GpgmeCtx @var{ctx}})
1519 The function @code{gpgme_op_trustlist_next} ends a pending key list
1520 operation in the context @var{ctx}.
1522 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
1523 valid pointer, @code{GPGME_No_Request} if there is no pending
1524 operation, @code{GPGME_Out_Of_Core} if at some time during the
1525 operation there was not enough memory available.
1529 @node Information about trust items
1530 @subsection Information about trust items
1532 Trust items have attributes which can be queried using the interfaces
1533 below. The attribute identifiers are shared with those for key
1534 attributes. @xref{Information about keys}.
1536 @deftypefun {const char *} gpgme_trust_item_get_string_attr (@w{GpgmeTrustItem @var{item}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
1537 The function @code{gpgme_trust_item_get_string_attr} returns the value
1538 of the string-representable attribute @var{what} of trust item
1539 @var{item}. If the attribute occurs more than once in the trust
1540 items, the index is specified by @var{idx}. However, currently no
1541 such attributes exists, so @var{idx} should be @code{0}. The argument
1542 @var{reserved} is reserved for later use and should be @code{NULL}.
1544 The string returned is only valid as long as the key is valid.
1546 The function returns @code{0} if an attribute can't be returned as a
1547 string, @var{key} is not a valid pointer, @var{idx} out of range,
1548 or @var{reserved} not @code{NULL}.
1551 @deftypefun int gpgme_trust_item_get_int_attr (@w{GpgmeTrustItem @var{item}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
1552 The function @code{gpgme_trust_item_get_int_attr} returns the value of
1553 the number-representable attribute @var{what} of trust item
1554 @var{item}. If the attribute occurs more than once in the trust item,
1555 the index is specified by @var{idx}. However, currently no such
1556 attribute exists, so @var{idx} should be @code{0}. The argument
1557 @var{reserved} is reserved for later use and should be @code{NULL}.
1559 The function returns @code{0} if the attribute can't be returned as a
1560 number, @var{key} is not a valid pointer, @var{idx} out of range,
1561 or @var{reserved} not @code{NULL}.
1565 @node Manipulating trust items
1566 @subsection Manipulating trust items
1568 @deftypefun void gpgme_trust_item_release (@w{GpgmeTrustItem @var{item}})
1569 The function @code{gpgme_trust_item_release} destroys a
1570 @code{GpgmeTrustItem} object and releases all associated resources.
1573 @node Crypto Operations
1574 @section Crypto Operations
1577 * Decrypt:: Decrypting a ciphertext.
1578 * Verify:: Verifying a signature.
1579 * Decrypt and verify:: Decrypting a signed ciphertext.
1580 * Sign:: Creating a signature.
1581 * Encrypt:: Encrypting a plaintext.
1588 @deftypefun GpgmeError gpgme_op_decrypt (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
1589 The function @code{gpgme_op_decrypt} decrypts the ciphertext in the
1590 data object @var{cipher} and stores it into the data object
1593 The function returns @code{GPGME_No_Error} if the ciphertext could be
1594 decrypted successfully, @code{GPGME_Invalid_Value} if @var{ctx},
1595 @var{cipher} or @var{plain} is not a valid pointer,
1596 @code{GPGME_No_Data} if @var{cipher} does not contain any data to
1597 decrypt, @code{GPGME_Decryption_Failed} if @var{cipher} is not a valid
1598 cipher text, @code{GPGME_No_Passphrase} if the passphrase for the
1599 secret key could not be retrieved, and passes through any errors that
1600 are reported by the crypto engine support routines.
1603 @c @deftypefun GpgmeError gpgme_op_decrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
1604 @c The function @code{gpgme_op_decrypt_start} initiates a
1605 @c @code{gpgme_op_decrypt} operation. It can be completed by calling
1606 @c @code{gpgme_wait} on the context.
1608 @c The function returns @code{GPGME_No_Error} if the operation could be
1609 @c started, @code{GPGME_Invalid_Value} if @var{cipher} or @var{plain} is
1610 @c not a valid pointer, and passes through any errors that are reported
1611 @c by the crypto engine support routines.
1618 @deftp {Data type} {enum GpgmeSigStat}
1619 The @code{GpgmeSigStat} type holds the result of a signature check, or
1620 the combined result of all signatures. The following results are
1624 @item GPGME_SIG_STAT_NONE
1625 This status should not occur in normal operation.
1627 @item GPGME_SIG_STAT_GOOD
1628 This status indicates that the signature is valid. For the combined
1629 result this status means that all signatures are valid.
1631 @item GPGME_SIG_STAT_BAD
1632 This status indicates that the signature is invalid. For the combined
1633 result this status means that all signatures are invalid.
1635 @item GPGME_SIG_STAT_NOKEY
1636 This status indicates that the signature could not be verified due to
1637 a missing key. For the combined result this status means that all
1638 signatures could not be checked due to missing keys.
1640 @item GPGME_SIG_STAT_NOSIG
1641 This status indicates that the signature data provided was not a real
1644 @item GPGME_SIG_STAT_ERROR
1645 This status indicates that there was some other error which prevented
1646 the signature verification.
1648 @item GPGME_SIG_STAT_DIFF
1649 For the combined result this status means that at least two signatures
1650 have a different status. You can get each key's status with
1651 @code{gpgme_get_sig_status}.
1655 @deftypefun GpgmeError gpgme_op_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{sig}}, @w{GpgmeData @var{plain}}, @w{GpgmeSigStat *@var{r_stat}})
1656 The function @code{gpgme_op_verify} verifies that the detached
1657 signature in the data object @var{sig} is a valid signature for the
1658 plaintext in the data object @var{plain}.
1660 The combined status of all signatures is returned in @var{r_stat}.
1661 The results of the individual signature verifications can be retrieved
1662 with @code{gpgme_get_sig_status} and @code{gpgme_get_sig_key}.
1664 The function returns @code{GPGME_No_Error} if the operation could be
1665 completed successfully, @code{GPGME_Invalid_Value} if @var{ctx},
1666 @var{sig}, @var{plain} or @var{r_stat} is not a valid pointer,
1667 @code{GPGME_No_Data} if @var{sig} or @var{plain} does not contain any
1668 data to verify, and passes through any errors that are reported by the
1669 crypto engine support routines.
1672 @c GpgmeError gpgme_op_verify_start (GpgmeCtx ctx, GpgmeData sig, GpgmeData plain);
1674 @deftypefun {const char *} gpgme_get_sig_status (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeSigStat *@var{r_stat}}, @w{time_t *@var{r_created}})
1675 The function @code{gpgme_get_sig_status} receives information about a
1676 signature after the @code{gpgme_op_verify} or
1677 @code{gpgme_op_verify_decrypt} operation. A single detached signature
1678 can contain signatures by more than one key. The @var{idx} specifies
1679 which signature's information should be retrieved, starting from
1682 The status of the signature will be returned in @var{r_stat} if it is
1683 not @code{NULL}. The creation time stamp of the signature will be
1684 returned in @var{r_created} if it is not @var{NULL}.
1686 The function returns a statically allocated string that contains the
1687 fingerprint of the key which signed the plaintext, or @code{NULL} if
1688 @var{ctx} is not a valid pointer, the operation is still pending, or
1689 no verification could be performed.
1692 @deftypefun {const char *} gpgme_get_sig_key (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeSigKey *@var{r_stat}})
1693 The function @code{gpgme_get_sig_status} receives a @code{GpgmeKey}
1694 object for the key which was used to verify the signature after the
1695 @code{gpgme_op_verify} or @code{gpgme_op_verify_decrypt} operation. A
1696 single detached signature can contain signatures by more than one key.
1697 The @var{idx} specifies which signature's information should be
1698 retrieved, starting from @var{0}. The key will have on reference for
1701 The function is a convenient way to retrieve the keys belonging to the
1702 fingerprints returned by @code{gpgme_get_sig_status}.
1704 The function returns @code{GPGME_No_Error} if the key could be
1705 returned, @code{GPGME_Invalid_Value} if @var{r_key} is not a valid
1706 pointer, @code{GPGME_Invalid_Key} if the fingerprint is not valid,
1707 @code{GPGME_EOF} if @var{idx} is too large, or some other error value
1708 if a problem occured requesting the key.
1712 @node Decrypt and verify
1713 @subsection Decrypt and verify
1715 @deftypefun GpgmeError gpgme_op_decrypt_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}}, @w{GpgmeSigStat *@var{r_stat}})
1716 The function @code{gpgme_op_decrypt_verify} decrypts the ciphertext in
1717 the data object @var{cipher} and stores it into the data object
1718 @var{plain}. If @var{cipher} contains signatures, they will be
1719 verified and their combined status will be returned in @var{r_stat}.
1721 After the operation completed, @code{gpgme_op_get_sig_status} and
1722 @code{gpgme_op_get_sig_key} can be used to retrieve more information
1723 about the signatures.
1725 The function returns @code{GPGME_No_Error} if the ciphertext could be
1726 decrypted successfully, @code{GPGME_Invalid_Value} if @var{ctx},
1727 @var{cipher}, @var{plain} or @var{r_stat} is not a valid pointer,
1728 @code{GPGME_No_Data} if @var{cipher} does not contain any data to
1729 decrypt, @code{GPGME_Decryption_Failed} if @var{cipher} is not a valid
1730 cipher text, @code{GPGME_No_Passphrase} if the passphrase for the
1731 secret key could not be retrieved, and passes through any errors that
1732 are reported by the crypto engine support routines.
1735 @c GpgmeError gpgme_op_decrypt_verify (GpgmeCtx c, GpgmeData in, GpgmeData out, GpgmeSigStat *r_status);
1741 A signature can contain signatures by one or more keys. The set of
1742 keys used to create a signatures is contained in a context, and is
1743 applied to all following signing operations in this context (until the
1747 * Selecting signers:: How to choose the keys to sign with.
1748 * Creating a signature:: How to create a signature.
1752 @node Selecting signers
1753 @subsubsection Selecting signers
1755 @deftypefun void gpgme_signers_clear (@w{GpgmeCtx @var{ctx}})
1756 The function @code{gpgme_signers_clear} releases a reference for each
1757 key on the signers list and removes the list of signers from the
1760 Every context starts with an empty list.
1764 @deftypefun GpgmeError gpgme_signers_add (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}})
1765 The function @code{gpgme_signers_add} adds the key @var{key} to the
1766 list of signers in the context @var{ctx}.
1768 One reference for the key is consumed.
1771 @deftypefun GpgmeKey gpgme_signers_enum (@w{const GpgmeCtx @var{ctx}}, @w{int @var{seq}})
1772 The function @code{gpgme_signers_enum} returns the @var{seq}th key in
1773 the list of signers in the context @var{ctx}. An additional reference
1774 is acquired for the user.
1776 If @var{seq} is out of range, @code{NULL} is returned.
1780 @node Creating a signature
1781 @subsubsection Creating a signature
1783 @deftp {Data type} {enum GpgmeSigMode}
1784 The @code{GpgmeSigMode} type is used to specify the desired type of a
1785 signature. The following modes are available:
1788 @item GPGME_SIG_MODE_NORMAL
1789 A normal signature is made, the output includes the plaintext and the
1792 @item GPGME_SIG_MODE_DETACH
1793 A detached signature is made.
1795 @item GPGME_SIG_MODE_CLEAR
1796 A clear text signature is made. The @acronym{ASCII} armor and text
1797 mode settings of the context are ignored.
1801 @deftypefun GpgmeError gpgme_op_sign (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{sig}}, @w{GpgmeSigMode @var{mode}})
1802 The function @code{gpgme_op_sign} creates a signature for the text in
1803 the data object @var{plain} and returns it in the data object
1804 @var{sig}. The type of the signature created is determined by the
1805 @acronym{ASCII} armor and text mode attributes set for the context
1806 @var{ctx} and the requested signature mode @var{mode}.
1808 The function returns @code{GPGME_No_Error} if the signature could be
1809 created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
1810 @var{plain} or @var{sig} is not a valid pointer, @code{GPGME_No_Data}
1811 if the signature could not be created, @code{GPGME_No_Passphrase} if
1812 the passphrase for the secret key could not be retrieved, and passes
1813 through any errors that are reported by the crypto engine support
1821 One plaintext can be encrypted for several recipients at the same
1822 time. The list of recipients is created independently of any context,
1823 and then passed to the encryption operation.
1826 * Selecting recipients:: How to choose the recipients.
1827 * Encrypting a plaintext:: How to encrypt a plaintext.
1831 @node Selecting recipients
1832 @subsubsection Selecting recipients
1834 @deftp {Data type} GpgmeRecipients
1835 The @code{GpgmeRecipients} type is a handle for a set of recipients
1836 that can be used in an encryption process.
1839 @deftypefun GpgmeError gpgme_recipients_new (@w{GpgmeRecipients *@var{r_rset}})
1840 The function @code{gpgme_recipients_new} creates a new, empty set of
1841 recipients and returns a handle for it in @var{r_rset}.
1843 The function returns @code{GPGME_No_Error} if the recipient set could
1844 be created successfully, and @code{GPGME_Out_Of_Core} if not enough
1845 memory was available.
1848 @deftypefun void gpgme_recipients_release (@w{GpgmeRecipients @var{rset}})
1849 The function @code{gpgme_recipients_release} destroys the set of
1850 recipients @var{rset} and releases all associated resources.
1853 @deftypefun GpgmeError gpgme_recipients_add_name (@w{GpgmeRecipients @var{rset}}, @w{const char *@var{name}})
1854 The function @code{gpgme_recipients_add_name} adds the recipient
1855 @var{name} to the set of recipients @var{rset}. This is equivalent to
1856 @code{gpgme_recipients_add_name_with_validity} with a validity of
1857 @code{GPGME_VALIDITY_UNKNOWN}.
1859 The function returns @code{GPGME_No_Error} if the recipient was added
1860 successfully, @code{GPGME_Invalid_Value} if @var{rset} or @var{name}
1861 is not a valid pointer, and @code{GPGME_Out_Of_Core} if not enough
1862 memory is available.
1865 @deftypefun GpgmeError gpgme_recipients_add_name_with_validity (@w{GpgmeRecipients @var{rset}}, @w{const char *@var{name}}, @w{GpgmeValidity @var{val}})
1866 The function @code{gpgme_recipients_add_name_with_validity} adds the
1867 recipient @var{name} with the validity @var{val} to the set of
1868 recipients @var{rset}. If the validity is not known, the function
1869 @code{gpgme_recipients_add_name} can be used.
1870 @xref{Information about keys}, for the possible values for @var{val}.
1872 The function returns @code{GPGME_No_Error} if the recipient was added
1873 successfully, @code{GPGME_Invalid_Value} if @var{rset} or @var{name}
1874 is not a valid pointer, and @code{GPGME_Out_Of_Core} if not enough
1875 memory is available.
1878 @deftypefun {unsigned int} gpgme_recipients_count (@w{const @var{GpgmeRecipients rset}})
1879 The function @code{gpgme_recipients_count} returns the number of
1880 recipients in the set @var{rset}.
1883 @deftypefun GpgmeError gpgme_recipients_enum_open (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}})
1884 The function @code{gpgme_recipients_enum_open} creates a new iterator
1885 @var{iter} that can be used to walk through the set of recipients in
1886 @var{rset}, using @code{gpgme_recipients_enum_read}.
1888 If the iterator is not needed anymore, it can be closed with
1889 @code{gpgme_recipients_enum_close}.
1891 The function returns @code{GPGME_No_Error} if the enumerator was
1892 successfully created and @code{GPGME_Invalid_Value} if @var{rset} or
1893 @var{iter} is not a valid pointer.
1896 @deftypefun {const char *} gpgme_recipients_enum_read (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}})
1897 The function @code{gpgme_recipients_enum_read} returns a string
1898 containing the name of the next recipient in the set @var{rset} for
1899 the iterator @var{iter}. The string is valid as long as @var{rset} is
1900 valid or the function is called the next time with the same recipient
1901 set and iterator, whatever is earlier.
1904 @deftypefun GpgmeError gpgme_recipients_enum_close (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}})
1905 The function @code{gpgme_recipients_enum_close} releases the iterator
1906 @var{iter} for the recipient set @var{rset}.
1910 @node Encrypting a plaintext
1911 @subsubsection Encrypting a plaintext
1913 @deftypefun GpgmeError gpgme_op_encrypt (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
1914 The function @code{gpgme_op_crypt} encrypts the plaintext in the data
1915 object @var{plain} for the recipients @var{rset} and stores the
1916 ciphertext in the data object @var{cipher}. The type of the
1917 ciphertext created is determined by the @acronym{ASCII} armor and text
1918 mode attributes set for the context @var{ctx}.
1920 The function returns @code{GPGME_No_Error} if the ciphertext could be
1921 created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
1922 @var{rset}, @var{plain} or @var{cipher} is not a valid pointer,
1923 @code{GPGME_No_Recipient} if @var{rset} does not contain any
1924 valid recipients, @code{GPGME_No_Passphrase} if the passphrase for the
1925 secret key could not be retrieved, and passes through any errors that
1926 are reported by the crypto engine support routines.
1937 @unnumbered Concept Index
1942 @node Function and Data Index
1943 @unnumbered Function and Data Index