5484 lines
202 KiB
Plaintext
5484 lines
202 KiB
Plaintext
()\input texinfo @c -*- Texinfo -*-
|
|
@setfilename gpgme.info
|
|
@settitle The `GnuPG Made Easy' Reference Manual
|
|
|
|
@dircategory GNU Libraries
|
|
@direntry
|
|
* @acronym{GPGME}: (gpgme). Adding support for cryptography to your program.
|
|
@end direntry
|
|
|
|
@include version.texi
|
|
|
|
@c Unify some of the indices.
|
|
@syncodeindex tp fn
|
|
@syncodeindex pg fn
|
|
|
|
@ifinfo
|
|
This file documents the @acronym{GPGME} library.
|
|
|
|
This is Edition @value{EDITION}, last updated @value{UPDATED}, of
|
|
@cite{The `GnuPG Made Easy' Reference Manual}, for Version
|
|
@value{VERSION}.
|
|
|
|
@c NOTE: Don't forget to update the year for the TeX version, too.
|
|
Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007 g10 Code GmbH.
|
|
|
|
The GPGME reference manual is free software; you can redistribute it
|
|
and/or modify it under the terms of the GNU Lesser General Public
|
|
License as published by the Free Software Foundation; either version
|
|
2.1 of the License, or (at your option) any later version.
|
|
|
|
The GPGME reference manual is distributed in the hope that it will be
|
|
useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
Lesser General Public License for more details.
|
|
|
|
You should have received a copy of the GNU Lesser General Public
|
|
License along with this program; if not, write to the Free Software
|
|
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
|
|
|
|
@end ifinfo
|
|
|
|
@iftex
|
|
@shorttitlepage The `GnuPG Made Easy' Reference Manual
|
|
@end iftex
|
|
@titlepage
|
|
@center @titlefont{The `GnuPG Made Easy'}
|
|
@sp 1
|
|
@center @titlefont{Reference Manual}
|
|
@sp 6
|
|
@center Edition @value{EDITION}
|
|
@sp 1
|
|
@center last updated @value{UPDATED}
|
|
@sp 1
|
|
@center for version @value{VERSION}
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007 g10 Code GmbH.
|
|
|
|
|
|
The GPGME reference manual is free software; you can redistribute it
|
|
and/or modify it under the terms of the GNU Lesser General Public
|
|
License as published by the Free Software Foundation; either version
|
|
2.1 of the License, or (at your option) any later version.
|
|
|
|
The GPGME reference manual is distributed in the hope that it will be
|
|
useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
Lesser General Public License for more details.
|
|
|
|
You should have received a copy of the GNU Lesser General Public
|
|
License along with this program; if not, write to the Free Software
|
|
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
|
|
@end titlepage
|
|
@page
|
|
|
|
@ifnottex
|
|
@node Top
|
|
@top Main Menu
|
|
This is Edition @value{EDITION}, last updated @value{UPDATED}, of
|
|
@cite{The `GnuPG Made Easy' Reference Manual}, for Version
|
|
@value{VERSION} of the @acronym{GPGME} library.
|
|
@end ifnottex
|
|
|
|
@menu
|
|
* Introduction:: How to use this manual.
|
|
* Preparation:: What you should do before using the library.
|
|
* Protocols and Engines:: Supported crypto protocols.
|
|
* Algorithms:: Supported algorithms.
|
|
* Error Handling:: Error numbers and their meanings.
|
|
* Exchanging Data:: Passing data to and from @acronym{GPGME}.
|
|
* Contexts:: Handling @acronym{GPGME} contexts.
|
|
|
|
Appendices
|
|
|
|
* Library Copying:: The GNU Lesser General Public License says
|
|
how you can copy and share `GnuPG Made Easy'.
|
|
|
|
Indices
|
|
|
|
* Concept Index:: Index of concepts and programs.
|
|
* Function and Data Index:: Index of functions, variables and data types.
|
|
|
|
|
|
@detailmenu
|
|
--- The Detailed Node Listing ---
|
|
|
|
Introduction
|
|
|
|
* Getting Started:: Purpose of the manual, and how to use it.
|
|
* Features:: Reasons to install and use @acronym{GPGME}.
|
|
* Overview:: Basic architecture of the @acronym{GPGME} library.
|
|
|
|
Preparation
|
|
|
|
* Header:: What header file you need to include.
|
|
* Building the Source:: Compiler options to be used.
|
|
* Largefile Support (LFS):: How to use @acronym{GPGME} with LFS.
|
|
* Using Automake:: Compiler options to be used the easy way.
|
|
* Using Libtool:: Avoiding compiler options entirely.
|
|
* Library Version Check:: Getting and verifying the library version.
|
|
* Signal Handling:: How @acronym{GPGME} affects signal handling.
|
|
* Multi Threading:: How @acronym{GPGME} can be used in an MT environment.
|
|
|
|
Protocols and Engines
|
|
|
|
* Engine Version Check:: Verifying the engine version.
|
|
* Engine Information:: Obtaining more information about the engines.
|
|
* Engine Configuration:: Changing the engine configuration.
|
|
* OpenPGP:: Support for the OpenPGP protocol.
|
|
* Cryptographic Message Syntax:: Support for the CMS.
|
|
|
|
Algorithms
|
|
|
|
* Public Key Algorithms:: A list of all public key algorithms.
|
|
* Hash Algorithms:: A list of all hash algorithms.
|
|
|
|
Error Handling
|
|
|
|
* Error Values:: The error value and what it means.
|
|
* Error Codes:: A list of important error codes.
|
|
* Error Sources:: A list of important error sources.
|
|
* Error Strings:: How to get a descriptive string from a value.
|
|
|
|
Exchanging Data
|
|
|
|
* Creating Data Buffers:: Creating new data buffers.
|
|
* Destroying Data Buffers:: Releasing data buffers.
|
|
* Manipulating Data Buffers:: Operations on data buffers.
|
|
|
|
Creating Data Buffers
|
|
|
|
* Memory Based Data Buffers:: Creating memory based data buffers.
|
|
* File Based Data Buffers:: Creating file based data buffers.
|
|
* Callback Based Data Buffers:: Creating callback based data buffers.
|
|
|
|
Manipulating Data Buffers
|
|
|
|
* Data Buffer I/O Operations:: I/O operations on data buffers.
|
|
* Data Buffer Meta-Data:: Meta-data manipulation of data buffers.
|
|
|
|
Contexts
|
|
|
|
* Creating Contexts:: Creating new @acronym{GPGME} contexts.
|
|
* Destroying Contexts:: Releasing @acronym{GPGME} contexts.
|
|
* Context Attributes:: Setting properties of a context.
|
|
* Key Management:: Managing keys with @acronym{GPGME}.
|
|
* Trust Item Management:: Managing trust items with @acronym{GPGME}.
|
|
* Crypto Operations:: Using a context for cryptography.
|
|
* Run Control:: Controlling how operations are run.
|
|
|
|
Context Attributes
|
|
|
|
* Protocol Selection:: Selecting the protocol used by a context.
|
|
* Crypto Engine:: Configuring the crypto engine.
|
|
* ASCII Armor:: Requesting @acronym{ASCII} armored output.
|
|
* Text Mode:: Choosing canonical text mode.
|
|
* Included Certificates:: Including a number of certificates.
|
|
* Key Listing Mode:: Selecting key listing mode.
|
|
* Passphrase Callback:: Getting the passphrase from the user.
|
|
* Progress Meter Callback:: Being informed about the progress.
|
|
* Locale:: Setting the locale of a context.
|
|
|
|
Key Management
|
|
|
|
* Listing Keys:: Browsing the list of available keys.
|
|
* Information About Keys:: Requesting detailed information about keys.
|
|
* Key Signatures:: Listing the signatures on a key.
|
|
* Manipulating Keys:: Operations on keys.
|
|
* Generating Keys:: Creating new key pairs.
|
|
* Exporting Keys:: Retrieving key data from the key ring.
|
|
* Importing Keys:: Adding keys to the key ring.
|
|
* Deleting Keys:: Removing keys from the key ring.
|
|
* Advanced Key Editing:: Advanced key edit operation.
|
|
|
|
Trust Item Management
|
|
|
|
* Listing Trust Items:: Browsing the list of available trust items.
|
|
* Information About Trust Items:: Requesting information about trust items.
|
|
* Manipulating Trust Items:: Operations on trust items.
|
|
|
|
Crypto Operations
|
|
|
|
* Decrypt:: Decrypting a ciphertext.
|
|
* Verify:: Verifying a signature.
|
|
* Decrypt and Verify:: Decrypting a signed ciphertext.
|
|
* Sign:: Creating a signature.
|
|
* Encrypt:: Encrypting a plaintext.
|
|
|
|
Sign
|
|
|
|
* Selecting Signers:: How to choose the keys to sign with.
|
|
* Creating a Signature:: How to create a signature.
|
|
* Signature Notation Data:: How to add notation data to a signature.
|
|
|
|
Encrypt
|
|
|
|
* Encrypting a Plaintext:: How to encrypt a plaintext.
|
|
|
|
Run Control
|
|
|
|
* Waiting For Completion:: Waiting until an operation is completed.
|
|
* Using External Event Loops:: Advanced control over what happens when.
|
|
* Cancellation:: How to end pending operations prematurely.
|
|
|
|
Using External Event Loops
|
|
|
|
* I/O Callback Interface:: How I/O callbacks are registered.
|
|
* Registering I/O Callbacks:: How to use I/O callbacks for a context.
|
|
* I/O Callback Example:: An example how to use I/O callbacks.
|
|
* I/O Callback Example GTK+:: How to integrate @acronym{GPGME} in GTK+.
|
|
* I/O Callback Example GDK:: How to integrate @acronym{GPGME} in GDK.
|
|
* I/O Callback Example Qt:: How to integrate @acronym{GPGME} in Qt.
|
|
|
|
@end detailmenu
|
|
@end menu
|
|
|
|
@node Introduction
|
|
@chapter Introduction
|
|
|
|
`GnuPG Made Easy' (@acronym{GPGME}) is a C language library that
|
|
allows to add support for cryptography to a program. It is designed
|
|
to make access to public key crypto engines like GnuPG or GpgSM easier
|
|
for applications. @acronym{GPGME} provides a high-level crypto API
|
|
for encryption, decryption, signing, signature verification and key
|
|
management.
|
|
|
|
@acronym{GPGME} uses GnuPG and GpgSM as its backends to support
|
|
OpenPGP and the Cryptographic Message Syntax (CMS).
|
|
|
|
@menu
|
|
* Getting Started:: Purpose of the manual, and how to use it.
|
|
* Features:: Reasons to install and use @acronym{GPGME}.
|
|
* Overview:: Basic architecture of the @acronym{GPGME} library.
|
|
@end menu
|
|
|
|
|
|
@node Getting Started
|
|
@section Getting Started
|
|
|
|
This manual documents the @acronym{GPGME} library programming
|
|
interface. All functions and data types provided by the library are
|
|
explained.
|
|
|
|
The reader is assumed to possess basic knowledge about cryptography in
|
|
general, and public key cryptography in particular. The underlying
|
|
cryptographic engines that are used by the library are not explained,
|
|
but where necessary, special features or requirements by an engine are
|
|
mentioned as far as they are relevant to @acronym{GPGME} or its users.
|
|
|
|
This manual can be used in several ways. If read from the beginning
|
|
to the end, it gives a good introduction into the library and how it
|
|
can be used in an application. Forward references are included where
|
|
necessary. Later on, the manual can be used as a reference manual to
|
|
get just the information needed about any particular interface of the
|
|
library. Experienced programmers might want to start looking at the
|
|
examples at the end of the manual, and then only read up those parts
|
|
of the interface which are unclear.
|
|
|
|
|
|
@node Features
|
|
@section Features
|
|
|
|
@acronym{GPGME} has a couple of advantages over other libraries doing
|
|
a similar job, and over implementing support for GnuPG or other crypto
|
|
engines into your application directly.
|
|
|
|
@table @asis
|
|
@item it's free software
|
|
Anybody can use, modify, and redistribute it under the terms of the GNU
|
|
Lesser General Public License (@pxref{Library Copying}).
|
|
|
|
@item it's flexible
|
|
@acronym{GPGME} provides transparent support for several cryptographic
|
|
protocols by different engines. Currently, @acronym{GPGME} supports
|
|
the OpenPGP protocol using GnuPG as the backend, and the Cryptographic
|
|
Message Syntax using GpgSM as the backend.
|
|
|
|
@item it's easy
|
|
@acronym{GPGME} hides the differences between the protocols and
|
|
engines from the programmer behind an easy-to-use interface. This way
|
|
the programmer can focus on the other parts of the program, and still
|
|
integrate strong cryptography in his application. Once support for
|
|
@acronym{GPGME} has been added to a program, it is easy to add support
|
|
for other crypto protocols once @acronym{GPGME} backends provide them.
|
|
@end table
|
|
|
|
|
|
@node Overview
|
|
@section Overview
|
|
|
|
@acronym{GPGME} provides a data abstraction that is used to pass data
|
|
to the crypto engine, and receive returned data from it. Data can be
|
|
read from memory or from files, but it can also be provided by a
|
|
callback function.
|
|
|
|
The actual cryptographic operations are always set within a context.
|
|
A context provides configuration parameters that define the behaviour
|
|
of all operations performed within it. Only one operation per context
|
|
is allowed at any time, but when one operation is finished, you can
|
|
run the next operation in the same context. There can be more than
|
|
one context, and all can run different operations at the same time.
|
|
|
|
Furthermore, @acronym{GPGME} has rich key management facilities
|
|
including listing keys, querying their attributes, generating,
|
|
importing, exporting and deleting keys, and acquiring information
|
|
about the trust path.
|
|
|
|
With some precautions, @acronym{GPGME} can be used in a multi-threaded
|
|
environment, although it is not completely thread safe and thus needs
|
|
the support of the application.
|
|
|
|
|
|
@node Preparation
|
|
@chapter Preparation
|
|
|
|
To use @acronym{GPGME}, you have to perform some changes to your
|
|
sources and the build system. The necessary changes are small and
|
|
explained in the following sections. At the end of this chapter, it
|
|
is described how the library is initialized, and how the requirements
|
|
of the library are verified.
|
|
|
|
@menu
|
|
* Header:: What header file you need to include.
|
|
* Building the Source:: Compiler options to be used.
|
|
* Largefile Support (LFS):: How to use @acronym{GPGME} with LFS.
|
|
* Using Automake:: Compiler options to be used the easy way.
|
|
* Using Libtool:: Avoiding compiler options entirely.
|
|
* Library Version Check:: Getting and verifying the library version.
|
|
* Signal Handling:: How @acronym{GPGME} affects signal handling.
|
|
* Multi Threading:: How @acronym{GPGME} can be used in an MT environment.
|
|
@end menu
|
|
|
|
|
|
@node Header
|
|
@section Header
|
|
@cindex header file
|
|
@cindex include file
|
|
|
|
All interfaces (data types and functions) of the library are defined
|
|
in the header file `gpgme.h'. You must include this in all programs
|
|
using the library, either directly or through some other header file,
|
|
like this:
|
|
|
|
@example
|
|
#include <gpgme.h>
|
|
@end example
|
|
|
|
The name space of @acronym{GPGME} is @code{gpgme_*} for function names
|
|
and data types and @code{GPGME_*} for other symbols. Symbols internal
|
|
to @acronym{GPGME} take the form @code{_gpgme_*} and @code{_GPGME_*}.
|
|
|
|
Because @acronym{GPGME} makes use of the GPG Error library, using
|
|
@acronym{GPGME} will also use the @code{GPG_ERR_*} name space
|
|
directly, and the @code{gpg_err*} and @code{gpg_str*} name space
|
|
indirectly.
|
|
|
|
|
|
@node Building the Source
|
|
@section Building the Source
|
|
@cindex compiler options
|
|
@cindex compiler flags
|
|
|
|
If you want to compile a source file including the `gpgme.h' header
|
|
file, you must make sure that the compiler can find it in the
|
|
directory hierarchy. This is accomplished by adding the path to the
|
|
directory in which the header file is located to the compilers include
|
|
file search path (via the @option{-I} option).
|
|
|
|
However, the path to the include file is determined at the time the
|
|
source is configured. To solve this problem, gpgme ships with a small
|
|
helper program @command{gpgme-config} that knows about the path to the
|
|
include file and other configuration options. The options that need
|
|
to be added to the compiler invocation at compile time are output by
|
|
the @option{--cflags} option to @command{gpgme-config}. The following
|
|
example shows how it can be used at the command line:
|
|
|
|
@example
|
|
gcc -c foo.c `gpgme-config --cflags`
|
|
@end example
|
|
|
|
Adding the output of @samp{gpgme-config --cflags} to the compiler
|
|
command line will ensure that the compiler can find the
|
|
@acronym{GPGME} header file.
|
|
|
|
A similar problem occurs when linking the program with the library.
|
|
Again, the compiler has to find the library files. For this to work,
|
|
the path to the library files has to be added to the library search
|
|
path (via the @option{-L} option). For this, the option
|
|
@option{--libs} to @command{gpgme-config} can be used. For
|
|
convenience, this option also outputs all other options that are
|
|
required to link the program with @acronym{GPGME} (in particular, the
|
|
@samp{-lgpgme} option). The example shows how to link @file{foo.o}
|
|
with the @acronym{GPGME} library to a program @command{foo}.
|
|
|
|
@example
|
|
gcc -o foo foo.o `gpgme-config --libs`
|
|
@end example
|
|
|
|
Of course you can also combine both examples to a single command by
|
|
specifying both options to @command{gpgme-config}:
|
|
|
|
@example
|
|
gcc -o foo foo.c `gpgme-config --cflags --libs`
|
|
@end example
|
|
|
|
If you want to link to one of the thread-safe versions of
|
|
@acronym{GPGME}, you must specify the @option{--thread} option before
|
|
any other option to select the thread package you want to link with.
|
|
Supported thread packages are @option{--thread=pth} and
|
|
@option{--thread=pthread}.
|
|
|
|
|
|
@node Largefile Support (LFS)
|
|
@section Largefile Support (LFS)
|
|
@cindex largefile support
|
|
@cindex LFS
|
|
|
|
@acronym{GPGME} is compiled with largefile support by default, if it
|
|
is available on the system. This means that GPGME supports files
|
|
larger than two gigabyte in size, if the underlying operating system
|
|
can. On some systems, largefile support is already the default. On
|
|
such systems, nothing special is required. However, some systems
|
|
provide only support for files up to two gigabyte in size by default.
|
|
Support for larger file sizes has to be specifically enabled.
|
|
|
|
To make a difficult situation even more complex, such systems provide
|
|
two different types of largefile support. You can either get all
|
|
relevant functions replaced with alternatives that are largefile
|
|
capable, or you can get new functions and data types for largefile
|
|
support added. Those new functions have the same name as their
|
|
smallfile counterparts, but with a suffix of 64.
|
|
|
|
An example: The data type @code{off_t} is 32 bit wide on GNU/Linux PC
|
|
systems. To address offsets in large files, you can either enable
|
|
largefile support add-on. Then a new data type @code{off64_t} is
|
|
provided, which is 64 bit wide. Or you can replace the existing
|
|
@code{off_t} data type with its 64 bit wide counterpart. All
|
|
occurences of @code{off_t} are then automagically replaced.
|
|
|
|
As if matters were not complex enough, there are also two different
|
|
types of file descriptors in such systems. This is important because
|
|
if file descriptors are exchanged between programs that use a
|
|
different maximum file size, certain errors must be produced on some
|
|
file descriptors to prevent subtle overflow bugs from occuring.
|
|
|
|
As you can see, supporting two different maximum file sizes at the
|
|
same time is not at all an easy task. However, the maximum file size
|
|
does matter for @acronym{GPGME}, because some data types it uses in
|
|
its interfaces are affected by that. For example, the @code{off_t}
|
|
data type is used in the @code{gpgme_data_seek} function, to match its
|
|
@acronym{POSIX} counterpart. This affects the call-frame of the
|
|
function, and thus the ABI of the library. Furthermore, file
|
|
descriptors can be exchanged between GPGME and the application.
|
|
|
|
For you as the user of the library, this means that your program must
|
|
be compiled in the same file size mode as the library. Luckily, there
|
|
is absolutely no valid reason for new programs to not enable largefile
|
|
support by default and just use that. The compatibility modes (small
|
|
file sizes or dual mode) can be considered an historic artefact, only
|
|
useful to allow for a transitional period.
|
|
|
|
@acronym{GPGME} is compiled using largefile support by default. This
|
|
means that your application must do the same, at least as far as it is
|
|
relevant for using the @file{gpgme.h} header file. All types in this
|
|
header files refer to their largefile counterparts, if they are
|
|
different from any default types on the system.
|
|
|
|
You can enable largefile support, if it is different from the default
|
|
on the system the application is compiled on, by using the Autoconf
|
|
macro @code{AC_SYS_LARGEFILE}. If you do this, then you don't need to
|
|
worry about anything else: It will just work. In this case you might
|
|
also want to use @code{AC_FUNC_FSEEKO} to take advantage of some new
|
|
interfaces, and @code{AC_TYPE_OFF_T} (just in case).
|
|
|
|
If you do not use Autoconf, you can define the preprocessor symbol
|
|
@code{_FILE_OFFSET_BITS} to 64 @emph{before} including any header
|
|
files, for example by specifying the option
|
|
@code{-D_FILE_OFFSET_BITS=64} on the compiler command line. You will
|
|
also want to define the preprocessor symbol @code{LARGEFILE_SOURCE} to
|
|
1 in this case, to take advantage of some new interfaces.
|
|
|
|
If you do not want to do either of the above, you probably know enough
|
|
about the issue to invent your own solution. Just keep in mind that
|
|
the @acronym{GPGME} header file expects that largefile support is
|
|
enabled, if it is available. In particular, we do not support dual
|
|
mode (@code{_LARGEFILE64_SOURCE}).
|
|
|
|
|
|
@node Using Automake
|
|
@section Using Automake
|
|
@cindex automake
|
|
@cindex autoconf
|
|
|
|
It is much easier if you use GNU Automake instead of writing your own
|
|
Makefiles. If you do that you do not have to worry about finding and
|
|
invoking the @command{gpgme-config} script at all. @acronym{GPGME}
|
|
provides an extension to Automake that does all the work for you.
|
|
|
|
@c A simple macro for optional variables.
|
|
@macro ovar{varname}
|
|
@r{[}@var{\varname\}@r{]}
|
|
@end macro
|
|
@defmac AM_PATH_GPGME (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
|
|
@defmacx AM_PATH_GPGME_PTH (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
|
|
@defmacx AM_PATH_GPGME_PTHREAD (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
|
|
Check whether @acronym{GPGME} (at least version @var{minimum-version},
|
|
if given) exists on the host system. If it is found, execute
|
|
@var{action-if-found}, otherwise do @var{action-if-not-found}, if
|
|
given.
|
|
|
|
Additionally, the function defines @code{GPGME_CFLAGS} to the flags
|
|
needed for compilation of the program to find the @file{gpgme.h}
|
|
header file, and @code{GPGME_LIBS} to the linker flags needed to link
|
|
the program to the @acronym{GPGME} library.
|
|
|
|
@code{AM_PATH_GPGME_PTH} checks for the version of @acronym{GPGME}
|
|
that can be used with GNU Pth, and defines @code{GPGME_PTH_CFLAGS} and
|
|
@code{GPGME_PTH_LIBS}.
|
|
|
|
@code{AM_PATH_GPGME_PTHREAD} checks for the version of @acronym{GPGME}
|
|
that can be used with the native pthread implementation, and defines
|
|
@code{GPGME_PTHREAD_CFLAGS} and @code{GPGME_PTHREAD_LIBS}.
|
|
@end defmac
|
|
|
|
You can use the defined Autoconf variables like this in your
|
|
@file{Makefile.am}:
|
|
|
|
@example
|
|
AM_CPPFLAGS = $(GPGME_CFLAGS)
|
|
LDADD = $(GPGME_LIBS)
|
|
@end example
|
|
|
|
|
|
@node Using Libtool
|
|
@section Using Libtool
|
|
@cindex libtool
|
|
|
|
The easiest way is to just use GNU Libtool. If you use libtool, and
|
|
link to @code{libgpgme.la}, @code{libgpgme-pth.la} or
|
|
@code{libgpgme-pthread.la} respectively, everything will be done
|
|
automatically by Libtool.
|
|
|
|
|
|
@node Library Version Check
|
|
@section Library Version Check
|
|
@cindex version check, of the library
|
|
|
|
@deftypefun {const char *} gpgme_check_version (@w{const char *@var{required_version}})
|
|
The function @code{gpgme_check_version} has three purposes. It can be
|
|
used to retrieve the version number of the library. In addition it
|
|
can verify that the version number is higher than a certain required
|
|
version number. In either case, the function initializes some
|
|
sub-systems, and for this reason alone it must be invoked early in
|
|
your program, before you make use of the other functions in
|
|
@acronym{GPGME}.
|
|
|
|
As a side effect for W32 based systems, the socket layer will get
|
|
initialized.
|
|
|
|
|
|
If @var{required_version} is @code{NULL}, the function returns a
|
|
pointer to a statically allocated string containing the version number
|
|
of the library.
|
|
|
|
If @var{required_version} is not @code{NULL}, it should point to a
|
|
string containing a version number, and the function checks that the
|
|
version of the library is at least as high as the version number
|
|
provided. In this case, the function returns a pointer to a
|
|
statically allocated string containing the version number of the
|
|
library. If @var{REQUIRED_VERSION} is not a valid version number, or
|
|
if the version requirement is not met, the function returns
|
|
@code{NULL}.
|
|
|
|
If you use a version of a library that is backwards compatible with
|
|
older releases, but contains additional interfaces which your program
|
|
uses, this function provides a run-time check if the necessary
|
|
features are provided by the installed version of the library.
|
|
@end deftypefun
|
|
|
|
|
|
After initializing @acronym{GPGME}, you should set the locale
|
|
information to the locale required for your output terminal. This
|
|
locale information is needed for example for the curses and Gtk
|
|
pinentry. Here is an example of a complete initialization:
|
|
|
|
@example
|
|
#include <locale.h>
|
|
#include <gpgme.h>
|
|
|
|
void
|
|
init_program (void)
|
|
@{
|
|
/* Initialize the locale environment. */
|
|
setlocale (LC_ALL, "");
|
|
gpgme_check_version (NULL);
|
|
gpgme_set_locale (NULL, LC_CTYPE, setlocale (LC_CTYPE, NULL));
|
|
#ifdef LC_MESSAGES
|
|
gpgme_set_locale (NULL, LC_MESSAGES, setlocale (LC_MESSAGES, NULL));
|
|
#endif
|
|
@}
|
|
@end example
|
|
|
|
Note that you are highly recommended to initialize the locale settings
|
|
like this. @acronym{GPGME} can not do this for you because it would
|
|
not be thread safe. The conditional on LC_MESSAGES is only necessary
|
|
for portability to W32 systems.
|
|
|
|
|
|
@node Signal Handling
|
|
@section Signal Handling
|
|
@cindex signals
|
|
@cindex signal handling
|
|
|
|
The @acronym{GPGME} library communicates with child processes (the
|
|
crypto engines). If a child process dies unexpectedly, for example
|
|
due to a bug, or system problem, a @code{SIGPIPE} signal will be
|
|
delivered to the application. The default action is to abort the
|
|
program. To protect against this, @code{gpgme_check_version} sets the
|
|
@code{SIGPIPE} signal action to @code{SIG_IGN}, which means that the
|
|
signal will be ignored.
|
|
|
|
@acronym{GPGME} will only do that if the signal action for
|
|
@code{SIGPIPE} is @code{SIG_DEF} at the time
|
|
@code{gpgme_check_version} is called. If it is something different,
|
|
@code{GPGME} will take no action.
|
|
|
|
This means that if your application does not install any signal
|
|
handler for @code{SIGPIPE}, you don't need to take any precautions.
|
|
If you do install a signal handler for @code{SIGPIPE}, you must be
|
|
prepared to handle any @code{SIGPIPE} events that occur due to
|
|
@acronym{GPGME} writing to a defunct pipe. Furthermore, if your
|
|
application is multi-threaded, and you install a signal action for
|
|
@code{SIGPIPE}, you must make sure you do this either before
|
|
@code{gpgme_check_version} is called or afterwards.
|
|
|
|
|
|
@node Multi Threading
|
|
@section Multi Threading
|
|
@cindex thread-safeness
|
|
@cindex multi-threading
|
|
|
|
The @acronym{GPGME} library is not entirely thread-safe, but it can
|
|
still be used in a multi-threaded environment if some care is taken.
|
|
If the following requirements are met, there should be no race
|
|
conditions to worry about:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@acronym{GPGME} supports the thread libraries pthread and GNU Pth.
|
|
The support for this has to be enabled at compile time.
|
|
@acronym{GPGME} will automatically detect the location in which the
|
|
thread libraries are installed and activate the support for them at
|
|
build time.
|
|
|
|
Support for other thread libraries is very easy to add. Please
|
|
contact us if you have the need.
|
|
|
|
@item
|
|
If you want to use @acronym{GPGME} with threads, you must link to the
|
|
right version of the library. The name of the right library is
|
|
@code{libgpgme-} followed by the name of the thread package you use.
|
|
For example, if you use GNU Pth, the right name is
|
|
@code{libgpgme-pth}. Use the Automake macros or
|
|
@command{gpgme-config} program for simplicity.
|
|
|
|
|
|
@item
|
|
The function @code{gpgme_check_version} must be called before any
|
|
other function in the library, because it initializes the thread
|
|
support subsystem in @acronym{GPGME}. To achieve this in
|
|
multi-threaded programs, you must synchronize the memory with respect
|
|
to other threads that also want to use @acronym{GPGME}. For this, it
|
|
is sufficient to call @code{gpgme_check_version} before creating the
|
|
other threads using @acronym{GPGME}@footnote{At least this is true for
|
|
POSIX threads, as @code{pthread_create} is a function that
|
|
synchronizes memory with respects to other threads. There are many
|
|
functions which have this property, a complete list can be found in
|
|
POSIX, IEEE Std 1003.1-2003, Base Definitions, Issue 6, in the
|
|
definition of the term ``Memory Synchronization''. For other thread
|
|
packages other, more relaxed or more strict rules may apply.}.
|
|
|
|
@item
|
|
Any @code{gpgme_data_t} and @code{gpgme_ctx_t} object must only be
|
|
accessed by one thread at a time. If multiple threads want to deal
|
|
with the same object, the caller has to make sure that operations on
|
|
that object are fully synchronized.
|
|
|
|
@item
|
|
Only one thread at any time is allowed to call @code{gpgme_wait}. If
|
|
multiple threads call this function, the caller must make sure that
|
|
all invocations are fully synchronized. It is safe to start
|
|
asynchronous operations while a thread is running in gpgme_wait.
|
|
|
|
@item
|
|
The function @code{gpgme_strerror} is not thread safe. You have to
|
|
use @code{gpgme_strerror_r} instead.
|
|
@end itemize
|
|
|
|
|
|
@node Protocols and Engines
|
|
@chapter Protocols and Engines
|
|
@cindex protocol
|
|
@cindex engine
|
|
@cindex crypto engine
|
|
@cindex backend
|
|
@cindex crypto backend
|
|
|
|
@acronym{GPGME} supports several cryptographic protocols, however, it
|
|
does not implement them. Rather it uses backends (also called
|
|
engines) which implement the protocol. @acronym{GPGME} uses
|
|
inter-process communication to pass data back and forth between the
|
|
application and the backend, but the details of the communication
|
|
protocol and invocation of the backend is completely hidden by the
|
|
interface. All complexity is handled by @acronym{GPGME}. Where an
|
|
exchange of information between the application and the backend is
|
|
necessary, @acronym{GPGME} provides the necessary callback function
|
|
hooks and further interfaces.
|
|
|
|
@deftp {Data type} {enum gpgme_protocol_t}
|
|
@tindex gpgme_protocol_t
|
|
The @code{gpgme_protocol_t} type specifies the set of possible protocol
|
|
values that are supported by @acronym{GPGME}. The following protocols
|
|
are supported:
|
|
|
|
@table @code
|
|
@item GPGME_PROTOCOL_OpenPGP
|
|
This specifies the OpenPGP protocol.
|
|
|
|
@item GPGME_PROTOCOL_CMS
|
|
This specifies the Cryptographic Message Syntax.
|
|
@end table
|
|
@end deftp
|
|
|
|
|
|
@deftypefun {const char *} gpgme_get_protocol_name (@w{gpgme_protocol_t @var{protocol}})
|
|
The function @code{gpgme_get_protocol_name} returns a statically
|
|
allocated string describing the protocol @var{protocol}, or
|
|
@code{NULL} if the protocol number is not valid.
|
|
@end deftypefun
|
|
|
|
@menu
|
|
* Engine Version Check:: Verifying the engine version.
|
|
* Engine Information:: Obtaining more information about the engines.
|
|
* Engine Configuration:: Changing the engine configuration.
|
|
* OpenPGP:: Support for the OpenPGP protocol.
|
|
* Cryptographic Message Syntax:: Support for the CMS.
|
|
@end menu
|
|
|
|
|
|
@node Engine Version Check
|
|
@section Engine Version Check
|
|
@cindex version check, of the engines
|
|
|
|
@deftypefun gpgme_error_t gpgme_engine_check_version (@w{gpgme_protocol_t @var{protocol}})
|
|
The function @code{gpgme_engine_check_version} verifies that the
|
|
engine implementing the protocol @var{PROTOCOL} is installed in the
|
|
expected path and meets the version requirement of @acronym{GPGME}.
|
|
|
|
This function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
engine is available and @code{GPG_ERR_INV_ENGINE} if it is not.
|
|
@end deftypefun
|
|
|
|
|
|
@node Engine Information
|
|
@section Engine Information
|
|
@cindex engine, information about
|
|
|
|
@deftp {Data type} {gpgme_engine_info_t}
|
|
@tindex gpgme_protocol_t
|
|
The @code{gpgme_engine_info_t} type specifies a pointer to a structure
|
|
describing a crypto engine. The structure contains the following
|
|
elements:
|
|
|
|
@table @code
|
|
@item gpgme_engine_info_t next
|
|
This is a pointer to the next engine info structure in the linked
|
|
list, or @code{NULL} if this is the last element.
|
|
|
|
@item gpgme_protocol_t protocol
|
|
This is the protocol for which the crypto engine is used. You can
|
|
convert this to a string with @code{gpgme_get_protocol_name} for
|
|
printing.
|
|
|
|
@item const char *file_name
|
|
This is a string holding the file name of the executable of the crypto
|
|
engine. Currently, it is never @code{NULL}, but using @code{NULL} is
|
|
reserved for future use, so always check before you use it.
|
|
|
|
@item const char *home_dir
|
|
This is a string holding the directory name of the crypto engine's
|
|
configuration directory. If it is @code{NULL}, then the default
|
|
directory is used.
|
|
|
|
@item const char *version
|
|
This is a string containing the version number of the crypto engine.
|
|
It might be @code{NULL} if the version number can not be determined,
|
|
for example because the executable doesn't exist or is invalid.
|
|
|
|
@item const char *req_version
|
|
This is a string containing the minimum required version number of the
|
|
crypto engine for @acronym{GPGME} to work correctly. This is the
|
|
version number that @code{gpgme_engine_check_version} verifies
|
|
against. Currently, it is never @code{NULL}, but using @code{NULL} is
|
|
reserved for future use, so always check before you use it.
|
|
@end table
|
|
@end deftp
|
|
|
|
@deftypefun gpgme_error_t gpgme_get_engine_info (@w{gpgme_engine_info_t *@var{info}})
|
|
The function @code{gpgme_get_engine_info} returns a linked list of
|
|
engine info structures in @var{info}. Each info structure describes
|
|
the defaults of one configured backend.
|
|
|
|
The memory for the info structures is allocated the first time this
|
|
function is invoked, and must not be freed by the caller.
|
|
|
|
This function returns the error code @code{GPG_ERR_NO_ERROR} if
|
|
successful, and a system error if the memory could not be allocated.
|
|
@end deftypefun
|
|
|
|
Here is an example how you can provide more diagnostics if you receive
|
|
an error message which indicates that the crypto engine is invalid.
|
|
|
|
@example
|
|
gpgme_ctx_t ctx;
|
|
gpgme_error_t err;
|
|
|
|
[...]
|
|
|
|
if (gpgme_err_code (err) == GPG_ERR_INV_ENGINE)
|
|
@{
|
|
gpgme_engine_info_t info;
|
|
err = gpgme_get_engine_info (&info);
|
|
if (!err)
|
|
@{
|
|
while (info && info->protocol != gpgme_get_protocol (ctx))
|
|
info = info->next;
|
|
if (!info)
|
|
fprintf (stderr, "GPGME compiled without support for protocol %s",
|
|
gpgme_get_protocol_name (info->protocol));
|
|
else if (info->path && !info->version)
|
|
fprintf (stderr, "Engine %s not installed properly",
|
|
info->path);
|
|
else if (info->path && info->version && info->req_version)
|
|
fprintf (stderr, "Engine %s version %s installed, "
|
|
"but at least version %s required", info->path,
|
|
info->version, info->req_version);
|
|
else
|
|
fprintf (stderr, "Unknown problem with engine for protocol %s",
|
|
gpgme_get_protocol_name (info->protocol));
|
|
@}
|
|
@}
|
|
@end example
|
|
|
|
|
|
@node Engine Configuration
|
|
@section Engine Configuration
|
|
@cindex engine, configuration of
|
|
@cindex configuration of crypto backend
|
|
|
|
You can change the configuration of a backend engine, and thus change
|
|
the executable program and configuration directory to be used. You
|
|
can make these changes the default or set them for some contexts
|
|
individually.
|
|
|
|
@deftypefun gpgme_error_t gpgme_set_engine_info (@w{gpgme_protocol_t @var{proto}}, @w{const char *@var{file_name}}, @w{const char *@var{home_dir}})
|
|
The function @code{gpgme_set_engine_info} changes the default
|
|
configuration of the crypto engine implementing the protocol
|
|
@var{proto}.
|
|
|
|
@var{file_name} is the file name of the executable program
|
|
implementing this protocol, and @var{home_dir} is the directory name
|
|
of the configuration directory for this crypto engine. If
|
|
@var{home_dir} is @code{NULL}, the engine's default will be used.
|
|
|
|
The new defaults are not applied to already created GPGME contexts.
|
|
|
|
This function returns the error code @code{GPG_ERR_NO_ERROR} if
|
|
successful, or an eror code on failure.
|
|
@end deftypefun
|
|
|
|
The functions @code{gpgme_ctx_get_engine_info} and
|
|
@code{gpgme_ctx_set_engine_info} can be used to change the engine
|
|
configuration per context. @xref{Crypto Engine}.
|
|
|
|
|
|
@node OpenPGP
|
|
@section OpenPGP
|
|
@cindex OpenPGP
|
|
@cindex GnuPG
|
|
@cindex protocol, GnuPG
|
|
@cindex engine, GnuPG
|
|
|
|
OpenPGP is implemented by GnuPG, the @acronym{GNU} Privacy Guard.
|
|
This is the first protocol that was supported by @acronym{GPGME}.
|
|
|
|
The OpenPGP protocol is specified by @code{GPGME_PROTOCOL_OpenPGP}.
|
|
|
|
|
|
@node Cryptographic Message Syntax
|
|
@section Cryptographic Message Syntax
|
|
@cindex CMS
|
|
@cindex cryptographic message syntax
|
|
@cindex GpgSM
|
|
@cindex protocol, CMS
|
|
@cindex engine, GpgSM
|
|
@cindex S/MIME
|
|
@cindex protocol, S/MIME
|
|
|
|
@acronym{CMS} is implemented by GpgSM, the S/MIME implementation for
|
|
GnuPG.
|
|
|
|
The @acronym{CMS} protocol is specified by @code{GPGME_PROTOCOL_CMS}.
|
|
|
|
|
|
@node Algorithms
|
|
@chapter Algorithms
|
|
@cindex algorithms
|
|
|
|
The crypto backends support a variety of algorithms used in public key
|
|
cryptography. The following sections list the identifiers used to
|
|
denote such an algorithm.
|
|
|
|
@menu
|
|
* Public Key Algorithms:: A list of all public key algorithms.
|
|
* Hash Algorithms:: A list of all hash algorithms.
|
|
@end menu
|
|
|
|
|
|
@node Public Key Algorithms
|
|
@section Public Key Algorithms
|
|
@cindex algorithms, public key
|
|
@cindex public key algorithms
|
|
|
|
Public key algorithms are used for encryption, decryption, signing and
|
|
verification of signatures.
|
|
|
|
@deftp {Data type} {enum gpgme_pubkey_algo_t}
|
|
@tindex gpgme_pubkey_algo_t
|
|
The @code{gpgme_pubkey_algo_t} type specifies the set of all public key
|
|
algorithms that are supported by @acronym{GPGME}. Possible values
|
|
are:
|
|
|
|
@table @code
|
|
@item GPGME_PK_RSA
|
|
This value indicates the RSA (Rivest, Shamir, Adleman) algorithm.
|
|
|
|
@item GPGME_PK_RSA_E
|
|
Deprecated. This value indicates the RSA (Rivest, Shamir, Adleman)
|
|
algorithm for encryption and decryption only.
|
|
|
|
@item GPGME_PK_RSA_S
|
|
Deprecated. This value indicates the RSA (Rivest, Shamir, Adleman)
|
|
algorithm for signing and verification only.
|
|
|
|
@item GPGME_PK_DSA
|
|
This value indicates DSA, the Digital Signature Algorithm.
|
|
|
|
@item GPGME_PK_ELG
|
|
This value indicates ElGamal.
|
|
|
|
@item GPGME_PK_ELG_E
|
|
This value also indicates ElGamal and is used specifically in GnuPG.
|
|
@end table
|
|
@end deftp
|
|
|
|
@deftypefun {const char *} gpgme_pubkey_algo_name (@w{gpgme_pubkey_algo_t @var{algo}})
|
|
The function @code{gpgme_pubkey_algo_name} returns a pointer to a
|
|
statically allocated string containing a description of the public key
|
|
algorithm @var{algo}. This string can be used to output the name of
|
|
the public key algorithm to the user.
|
|
|
|
If @var{algo} is not a valid public key algorithm, @code{NULL} is
|
|
returned.
|
|
@end deftypefun
|
|
|
|
|
|
@node Hash Algorithms
|
|
@section Hash Algorithms
|
|
@cindex algorithms, hash
|
|
@cindex algorithms, message digest
|
|
@cindex hash algorithms
|
|
@cindex message digest algorithms
|
|
|
|
Hash (message digest) algorithms are used to compress a long message
|
|
to make it suitable for public key cryptography.
|
|
|
|
@deftp {Data type} {enum gpgme_hash_algo_t}
|
|
@tindex gpgme_hash_algo_t
|
|
The @code{gpgme_hash_algo_t} type specifies the set of all hash algorithms
|
|
that are supported by @acronym{GPGME}. Possible values are:
|
|
|
|
@table @code
|
|
@item GPGME_MD_MD5
|
|
@item GPGME_MD_SHA1
|
|
@item GPGME_MD_RMD160
|
|
@item GPGME_MD_MD2
|
|
@item GPGME_MD_TIGER
|
|
@item GPGME_MD_HAVAL
|
|
@item GPGME_MD_SHA256
|
|
@item GPGME_MD_SHA384
|
|
@item GPGME_MD_SHA512
|
|
@item GPGME_MD_MD4
|
|
@item GPGME_MD_CRC32
|
|
@item GPGME_MD_CRC32_RFC1510
|
|
@item GPGME_MD_CRC24_RFC2440
|
|
@end table
|
|
@end deftp
|
|
|
|
@deftypefun {const char *} gpgme_hash_algo_name (@w{gpgme_hash_algo_t @var{algo}})
|
|
The function @code{gpgme_hash_algo_name} returns a pointer to a
|
|
statically allocated string containing a description of the hash
|
|
algorithm @var{algo}. This string can be used to output the name of
|
|
the hash algorithm to the user.
|
|
|
|
If @var{algo} is not a valid hash algorithm, @code{NULL} is returned.
|
|
@end deftypefun
|
|
|
|
|
|
@node Error Handling
|
|
@chapter Error Handling
|
|
@cindex error handling
|
|
|
|
Many functions in @acronym{GPGME} can return an error if they fail.
|
|
For this reason, the application should always catch the error
|
|
condition and take appropriate measures, for example by releasing the
|
|
resources and passing the error up to the caller, or by displaying a
|
|
descriptive message to the user and cancelling the operation.
|
|
|
|
Some error values do not indicate a system error or an error in the
|
|
operation, but the result of an operation that failed properly. For
|
|
example, if you try to decrypt a tempered message, the decryption will
|
|
fail. Another error value actually means that the end of a data
|
|
buffer or list has been reached. The following descriptions explain
|
|
for many error codes what they mean usually. Some error values have
|
|
specific meanings if returned by a certain functions. Such cases are
|
|
described in the documentation of those functions.
|
|
|
|
@acronym{GPGME} uses the @code{libgpg-error} library. This allows to
|
|
share the error codes with other components of the GnuPG system, and
|
|
thus pass error values transparently from the crypto engine, or some
|
|
helper application of the crypto engine, to the user. This way no
|
|
information is lost. As a consequence, @acronym{GPGME} does not use
|
|
its own identifiers for error codes, but uses those provided by
|
|
@code{libgpg-error}. They usually start with @code{GPG_ERR_}.
|
|
|
|
However, @acronym{GPGME} does provide aliases for the functions
|
|
defined in libgpg-error, which might be preferred for name space
|
|
consistency.
|
|
|
|
@menu
|
|
* Error Values:: The error value and what it means.
|
|
* Error Sources:: A list of important error sources.
|
|
* Error Codes:: A list of important error codes.
|
|
* Error Strings:: How to get a descriptive string from a value.
|
|
@end menu
|
|
|
|
|
|
@node Error Values
|
|
@section Error Values
|
|
@cindex error values
|
|
@cindex error codes
|
|
@cindex error sources
|
|
|
|
@deftp {Data type} {gpgme_err_code_t}
|
|
The @code{gpgme_err_code_t} type is an alias for the @code{libgpg-error}
|
|
type @code{gpg_err_code_t}. The error code indicates the type of an
|
|
error, or the reason why an operation failed.
|
|
|
|
A list of important error codes can be found in the next section.
|
|
@end deftp
|
|
|
|
@deftp {Data type} {gpgme_err_source_t}
|
|
The @code{gpgme_err_source_t} type is an alias for the
|
|
@code{libgpg-error} type @code{gpg_err_source_t}. The error source
|
|
has not a precisely defined meaning. Sometimes it is the place where
|
|
the error happened, sometimes it is the place where an error was
|
|
encoded into an error value. Usually the error source will give an
|
|
indication to where to look for the problem. This is not always true,
|
|
but it is attempted to achieve this goal.
|
|
|
|
A list of important error sources can be found in the next section.
|
|
@end deftp
|
|
|
|
@deftp {Data type} {gpgme_error_t}
|
|
The @code{gpgme_error_t} type is an alias for the @code{libgpg-error}
|
|
type @code{gpg_error_t}. An error value like this has always two
|
|
components, an error code and an error source. Both together form the
|
|
error value.
|
|
|
|
Thus, the error value can not be directly compared against an error
|
|
code, but the accessor functions described below must be used.
|
|
However, it is guaranteed that only 0 is used to indicate success
|
|
(@code{GPG_ERR_NO_ERROR}), and that in this case all other parts of
|
|
the error value are set to 0, too.
|
|
|
|
Note that in @acronym{GPGME}, the error source is used purely for
|
|
diagnostical purposes. Only the error code should be checked to test
|
|
for a certain outcome of a function. The manual only documents the
|
|
error code part of an error value. The error source is left
|
|
unspecified and might be anything.
|
|
@end deftp
|
|
|
|
@deftypefun {static inline gpgme_err_code_t} gpgme_err_code (@w{gpgme_error_t @var{err}})
|
|
The static inline function @code{gpgme_err_code} returns the
|
|
@code{gpgme_err_code_t} component of the error value @var{err}. This
|
|
function must be used to extract the error code from an error value in
|
|
order to compare it with the @code{GPG_ERR_*} error code macros.
|
|
@end deftypefun
|
|
|
|
@deftypefun {static inline gpgme_err_source_t} gpgme_err_source (@w{gpgme_error_t @var{err}})
|
|
The static inline function @code{gpgme_err_source} returns the
|
|
@code{gpgme_err_source_t} component of the error value @var{err}. This
|
|
function must be used to extract the error source from an error value in
|
|
order to compare it with the @code{GPG_ERR_SOURCE_*} error source macros.
|
|
@end deftypefun
|
|
|
|
@deftypefun {static inline gpgme_error_t} gpgme_err_make (@w{gpgme_err_source_t @var{source}}, @w{gpgme_err_code_t @var{code}})
|
|
The static inline function @code{gpgme_err_make} returns the error
|
|
value consisting of the error source @var{source} and the error code
|
|
@var{code}.
|
|
|
|
This function can be used in callback functions to construct an error
|
|
value to return it to the library.
|
|
@end deftypefun
|
|
|
|
@deftypefun {static inline gpgme_error_t} gpgme_error (@w{gpgme_err_code_t @var{code}})
|
|
The static inline function @code{gpgme_error} returns the error value
|
|
consisting of the default error source and the error code @var{code}.
|
|
|
|
For @acronym{GPGME} applications, the default error source is
|
|
@code{GPG_ERR_SOURCE_USER_1}. You can define
|
|
@code{GPGME_ERR_SOURCE_DEFAULT} before including @file{gpgme.h} to
|
|
change this default.
|
|
|
|
This function can be used in callback functions to construct an error
|
|
value to return it to the library.
|
|
@end deftypefun
|
|
|
|
The @code{libgpg-error} library provides error codes for all system
|
|
error numbers it knows about. If @var{err} is an unknown error
|
|
number, the error code @code{GPG_ERR_UNKNOWN_ERRNO} is used. The
|
|
following functions can be used to construct error values from system
|
|
errnor numbers.
|
|
|
|
@deftypefun {gpgme_error_t} gpgme_err_make_from_errno (@w{gpgme_err_source_t @var{source}}, @w{int @var{err}})
|
|
The function @code{gpgme_err_make_from_errno} is like
|
|
@code{gpgme_err_make}, but it takes a system error like @code{errno}
|
|
instead of a @code{gpgme_err_code_t} error code.
|
|
@end deftypefun
|
|
|
|
@deftypefun {gpgme_error_t} gpgme_error_from_errno (@w{int @var{err}})
|
|
The function @code{gpgme_error_from_errno} is like @code{gpgme_error},
|
|
but it takes a system error like @code{errno} instead of a
|
|
@code{gpgme_err_code_t} error code.
|
|
@end deftypefun
|
|
|
|
Sometimes you might want to map system error numbers to error codes
|
|
directly, or map an error code representing a system error back to the
|
|
system error number. The following functions can be used to do that.
|
|
|
|
@deftypefun {gpgme_err_code_t} gpgme_err_code_from_errno (@w{int @var{err}})
|
|
The function @code{gpgme_err_code_from_errno} returns the error code
|
|
for the system error @var{err}. If @var{err} is not a known system
|
|
error, the function returns @code{GPG_ERR_UNKNOWN_ERRNO}.
|
|
@end deftypefun
|
|
|
|
@deftypefun {int} gpgme_err_code_to_errno (@w{gpgme_err_code_t @var{err}})
|
|
The function @code{gpgme_err_code_to_errno} returns the system error
|
|
for the error code @var{err}. If @var{err} is not an error code
|
|
representing a system error, or if this system error is not defined on
|
|
this system, the function returns @code{0}.
|
|
@end deftypefun
|
|
|
|
|
|
@node Error Sources
|
|
@section Error Sources
|
|
@cindex error codes, list of
|
|
|
|
The library @code{libgpg-error} defines an error source for every
|
|
component of the GnuPG system. The error source part of an error
|
|
value is not well defined. As such it is mainly useful to improve the
|
|
diagnostic error message for the user.
|
|
|
|
If the error code part of an error value is @code{0}, the whole error
|
|
value will be @code{0}. In this case the error source part is of
|
|
course @code{GPG_ERR_SOURCE_UNKNOWN}.
|
|
|
|
The list of error sources that might occur in applications using
|
|
@acronym{GPGME} is:
|
|
|
|
@table @code
|
|
@item GPG_ERR_SOURCE_UNKNOWN
|
|
The error source is not known. The value of this error source is
|
|
@code{0}.
|
|
|
|
@item GPG_ERR_SOURCE_GPGME
|
|
The error source is @acronym{GPGME} itself. This is the default for
|
|
errors that occur in the @acronym{GPGME} library.
|
|
|
|
@item GPG_ERR_SOURCE_GPG
|
|
The error source is GnuPG, which is the crypto engine used for the
|
|
OpenPGP protocol.
|
|
|
|
@item GPG_ERR_SOURCE_GPGSM
|
|
The error source is GPGSM, which is the crypto engine used for the
|
|
CMS protocol.
|
|
|
|
@item GPG_ERR_SOURCE_GCRYPT
|
|
The error source is @code{libgcrypt}, which is used by crypto engines
|
|
to perform cryptographic operations.
|
|
|
|
@item GPG_ERR_SOURCE_GPGAGENT
|
|
The error source is @command{gpg-agent}, which is used by crypto
|
|
engines to perform operations with the secret key.
|
|
|
|
@item GPG_ERR_SOURCE_PINENTRY
|
|
The error source is @command{pinentry}, which is used by
|
|
@command{gpg-agent} to query the passphrase to unlock a secret key.
|
|
|
|
@item GPG_ERR_SOURCE_SCD
|
|
The error source is the SmartCard Daemon, which is used by
|
|
@command{gpg-agent} to delegate operations with the secret key to a
|
|
SmartCard.
|
|
|
|
@item GPG_ERR_SOURCE_KEYBOX
|
|
The error source is @code{libkbx}, a library used by the crypto
|
|
engines to manage local keyrings.
|
|
|
|
@item GPG_ERR_SOURCE_USER_1
|
|
@item GPG_ERR_SOURCE_USER_2
|
|
@item GPG_ERR_SOURCE_USER_3
|
|
@item GPG_ERR_SOURCE_USER_4
|
|
These error sources are not used by any GnuPG component and can be
|
|
used by other software. For example, applications using
|
|
@acronym{GPGME} can use them to mark error values coming from callback
|
|
handlers. Thus @code{GPG_ERR_SOURCE_USER_1} is the default for errors
|
|
created with @code{gpgme_error} and @code{gpgme_error_from_errno},
|
|
unless you define @code{GPGME_ERR_SOURCE_DEFAULT} before including
|
|
@file{gpgme.h}.
|
|
@end table
|
|
|
|
|
|
@node Error Codes
|
|
@section Error Codes
|
|
@cindex error codes, list of
|
|
|
|
The library @code{libgpg-error} defines many error values. Most of
|
|
them are not used by @code{GPGME} directly, but might be returned by
|
|
@acronym{GPGME} because it received them from the crypto engine. The
|
|
below list only includes such error codes that have a specific meaning
|
|
in @code{GPGME}, or which are so common that you should know about
|
|
them.
|
|
|
|
@table @code
|
|
@item GPG_ERR_EOF
|
|
This value indicates the end of a list, buffer or file.
|
|
|
|
@item GPG_ERR_NO_ERROR
|
|
This value indicates success. The value of this error code is
|
|
@code{0}. Also, it is guaranteed that an error value made from the
|
|
error code @code{0} will be @code{0} itself (as a whole). This means
|
|
that the error source information is lost for this error code,
|
|
however, as this error code indicates that no error occured, this is
|
|
generally not a problem.
|
|
|
|
@item GPG_ERR_GENERAL
|
|
This value means that something went wrong, but either there is not
|
|
enough information about the problem to return a more useful error
|
|
value, or there is no separate error value for this type of problem.
|
|
|
|
@item GPG_ERR_ENOMEM
|
|
This value means that an out-of-memory condition occurred.
|
|
|
|
@item GPG_ERR_E...
|
|
System errors are mapped to GPG_ERR_FOO where FOO is the symbol for
|
|
the system error.
|
|
|
|
@item GPG_ERR_INV_VALUE
|
|
This value means that some user provided data was out of range. This
|
|
can also refer to objects. For example, if an empty
|
|
@code{gpgme_data_t} object was expected, but one containing data was
|
|
provided, this error value is returned.
|
|
|
|
@item GPG_ERR_UNUSABLE_PUBKEY
|
|
This value means that some recipients for a message were invalid.
|
|
|
|
@item GPG_ERR_UNUSABLE_SECKEY
|
|
This value means that some signers were invalid.
|
|
|
|
@item GPG_ERR_NO_DATA
|
|
This value means that a @code{gpgme_data_t} object which was expected
|
|
to have content was found empty.
|
|
|
|
@item GPG_ERR_CONFLICT
|
|
This value means that a conflict of some sort occurred.
|
|
|
|
@item GPG_ERR_NOT_IMPLEMENTED
|
|
This value indicates that the specific function (or operation) is not
|
|
implemented. This error should never happen. It can only occur if
|
|
you use certain values or configuration options which do not work,
|
|
but for which we think that they should work at some later time.
|
|
|
|
@item GPG_ERR_DECRYPT_FAILED
|
|
This value indicates that a decryption operation was unsuccessful.
|
|
|
|
@item GPG_ERR_BAD_PASSPHRASE
|
|
This value means that the user did not provide a correct passphrase
|
|
when requested.
|
|
|
|
@item GPG_ERR_CANCELED
|
|
This value means that the operation was canceled.
|
|
|
|
@item GPG_ERR_INV_ENGINE
|
|
This value means that the engine that implements the desired protocol
|
|
is currently not available. This can either be because the sources
|
|
were configured to exclude support for this engine, or because the
|
|
engine is not installed properly.
|
|
|
|
@item GPG_ERR_AMBIGUOUS_NAME
|
|
This value indicates that a user ID or other specifier did not specify
|
|
a unique key.
|
|
|
|
@item GPG_ERR_WRONG_KEY_USAGE
|
|
This value indicates that a key is not used appropriately.
|
|
|
|
@item GPG_ERR_CERT_REVOKED
|
|
This value indicates that a key signature was revoced.
|
|
|
|
@item GPG_ERR_CERT_EXPIRED
|
|
This value indicates that a key signature expired.
|
|
|
|
@item GPG_ERR_NO_CRL_KNOWN
|
|
This value indicates that no certificate revocation list is known for
|
|
the certificate.
|
|
|
|
@item GPG_ERR_NO_POLICY_MATCH
|
|
This value indicates that a policy issue occured.
|
|
|
|
@item GPG_ERR_NO_SECKEY
|
|
This value indicates that no secret key for the user ID is available.
|
|
|
|
@item GPG_ERR_MISSING_CERT
|
|
This value indicates that a key could not be imported because the
|
|
issuer certificate is missing.
|
|
|
|
@item GPG_ERR_BAD_CERT_CHAIN
|
|
This value indicates that a key could not be imported because its
|
|
certificate chain is not good, for example it could be too long.
|
|
|
|
@item GPG_ERR_UNSUPPORTED_ALGORITHM
|
|
This value means a verification failed because the cryptographic
|
|
algorithm is not supported by the crypto backend.
|
|
|
|
@item GPG_ERR_BAD_SIGNATURE
|
|
This value means a verification failed because the signature is bad.
|
|
|
|
@item GPG_ERR_NO_PUBKEY
|
|
This value means a verification failed because the public key is not
|
|
available.
|
|
|
|
@item GPG_ERR_USER_1
|
|
@item GPG_ERR_USER_2
|
|
@item ...
|
|
@item GPG_ERR_USER_16
|
|
These error codes are not used by any GnuPG component and can be
|
|
freely used by other software. Applications using @acronym{GPGME}
|
|
might use them to mark specific errors returned by callback handlers
|
|
if no suitable error codes (including the system errors) for
|
|
these errors exist already.
|
|
@end table
|
|
|
|
|
|
@node Error Strings
|
|
@section Error Strings
|
|
@cindex error values, printing of
|
|
@cindex error codes, printing of
|
|
@cindex error sources, printing of
|
|
@cindex error strings
|
|
|
|
@deftypefun {const char *} gpgme_strerror (@w{gpgme_error_t @var{err}})
|
|
The function @code{gpgme_strerror} returns a pointer to a statically
|
|
allocated string containing a description of the error code contained
|
|
in the error value @var{err}. This string can be used to output a
|
|
diagnostic message to the user.
|
|
|
|
This function is not thread safe. Use @code{gpgme_strerror_r} in
|
|
multi-threaded programs.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun {int} gpgme_strerror_r (@w{gpgme_error_t @var{err}}, @w{char *@var{buf}}, @w{size_t @var{buflen}})
|
|
The function @code{gpgme_strerror_r} returns the error string for
|
|
@var{err} in the user-supplied buffer @var{buf} of size @var{buflen}.
|
|
This function is, in contrast to @code{gpgme_strerror}, thread-safe if
|
|
a thread-safe @code{strerror_r} function is provided by the system.
|
|
If the function succeeds, 0 is returned and @var{buf} contains the
|
|
string describing the error. If the buffer was not large enough,
|
|
ERANGE is returned and @var{buf} contains as much of the beginning of
|
|
the error string as fits into the buffer.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun {const char *} gpgme_strsource (@w{gpgme_error_t @var{err}})
|
|
The function @code{gpgme_strerror} returns a pointer to a statically
|
|
allocated string containing a description of the error source
|
|
contained in the error value @var{err}. This string can be used to
|
|
output a diagnostic message to the user.
|
|
@end deftypefun
|
|
|
|
The following example illustrates the use of @code{gpgme_strerror}:
|
|
|
|
@example
|
|
gpgme_ctx_t ctx;
|
|
gpgme_error_t err = gpgme_new (&ctx);
|
|
if (err)
|
|
@{
|
|
fprintf (stderr, "%s: creating GpgME context failed: %s: %s\n",
|
|
argv[0], gpgme_strsource (err), gpgme_strerror (err));
|
|
exit (1);
|
|
@}
|
|
@end example
|
|
|
|
|
|
@node Exchanging Data
|
|
@chapter Exchanging Data
|
|
@cindex data, exchanging
|
|
|
|
A lot of data has to be exchanged between the user and the crypto
|
|
engine, like plaintext messages, ciphertext, signatures and
|
|
information about the keys. The technical details about exchanging
|
|
the data information are completely abstracted by @acronym{GPGME}.
|
|
The user provides and receives the data via @code{gpgme_data_t} objects,
|
|
regardless of the communication protocol between @acronym{GPGME} and
|
|
the crypto engine in use.
|
|
|
|
@deftp {Data type} {gpgme_data_t}
|
|
The @code{gpgme_data_t} type is a handle for a container for generic
|
|
data, which is used by @acronym{GPGME} to exchange data with the user.
|
|
@end deftp
|
|
|
|
@menu
|
|
* Creating Data Buffers:: Creating new data buffers.
|
|
* Destroying Data Buffers:: Releasing data buffers.
|
|
* Manipulating Data Buffers:: Operations on data buffers.
|
|
@end menu
|
|
|
|
|
|
@node Creating Data Buffers
|
|
@section Creating Data Buffers
|
|
@cindex data buffer, creation
|
|
|
|
Data objects can be based on memory, files, or callback functions
|
|
provided by the user. Not all operations are supported by all
|
|
objects.
|
|
|
|
|
|
@menu
|
|
* Memory Based Data Buffers:: Creating memory based data buffers.
|
|
* File Based Data Buffers:: Creating file based data buffers.
|
|
* Callback Based Data Buffers:: Creating callback based data buffers.
|
|
@end menu
|
|
|
|
|
|
@node Memory Based Data Buffers
|
|
@subsection Memory Based Data Buffers
|
|
|
|
Memory based data objects store all data in allocated memory. This is
|
|
convenient, but only practical for an amount of data that is a
|
|
fraction of the available physical memory. The data has to be copied
|
|
from its source and to its destination, which can often be avoided by
|
|
using one of the other data object
|
|
|
|
@deftypefun gpgme_error_t gpgme_data_new (@w{gpgme_data_t *@var{dh}})
|
|
The function @code{gpgme_data_new} creates a new @code{gpgme_data_t}
|
|
object and returns a handle for it in @var{dh}. The data object is
|
|
memory based and initially empty.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
data object was successfully created, @code{GPG_ERR_INV_VALUE} if
|
|
@var{dh} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if not
|
|
enough memory is available.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_error_t gpgme_data_new_from_mem (@w{gpgme_data_t *@var{dh}}, @w{const char *@var{buffer}}, @w{size_t @var{size}}, @w{int @var{copy}})
|
|
The function @code{gpgme_data_new_from_mem} creates a new
|
|
@code{gpgme_data_t} object and fills it with @var{size} bytes starting
|
|
from @var{buffer}.
|
|
|
|
If @var{copy} is not zero, a private copy of the data is made. If
|
|
@var{copy} is zero, the data is taken from the specified buffer as
|
|
needed, and the user has to ensure that the buffer remains valid for
|
|
the whole life span of the data object.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
data object was successfully created, @code{GPG_ERR_INV_VALUE} if
|
|
@var{dh} or @var{buffer} is not a valid pointer, and
|
|
@code{GPG_ERR_ENOMEM} if not enough memory is available.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_error_t gpgme_data_new_from_file (@w{gpgme_data_t *@var{dh}}, @w{const char *@var{filename}}, @w{int @var{copy}})
|
|
The function @code{gpgme_data_new_from_file} creates a new
|
|
@code{gpgme_data_t} object and fills it with the content of the file
|
|
@var{filename}.
|
|
|
|
If @var{copy} is not zero, the whole file is read in at initialization
|
|
time and the file is not used anymore after that. This is the only
|
|
mode supported currently. Later, a value of zero for @var{copy} might
|
|
cause all reads to be delayed until the data is needed, but this is
|
|
not yet implemented.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
data object was successfully created, @code{GPG_ERR_INV_VALUE} if
|
|
@var{dh} or @var{filename} is not a valid pointer,
|
|
@code{GPG_ERR_NOT_IMPLEMENTED} if @var{code} is zero, and
|
|
@code{GPG_ERR_ENOMEM} if not enough memory is available.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_error_t gpgme_data_new_from_filepart (@w{gpgme_data_t *@var{dh}}, @w{const char *@var{filename}}, @w{FILE *@var{fp}}, @w{off_t @var{offset}}, @w{size_t @var{length}})
|
|
The function @code{gpgme_data_new_from_filepart} creates a new
|
|
@code{gpgme_data_t} object and fills it with a part of the file specified
|
|
by @var{filename} or @var{fp}.
|
|
|
|
Exactly one of @var{filename} and @var{fp} must be non-zero, the other
|
|
must be zero. The argument that is not zero specifies the file from
|
|
which @var{length} bytes are read into the data object, starting from
|
|
@var{offset}.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
data object was successfully created, @code{GPG_ERR_INV_VALUE} if
|
|
@var{dh} and exactly one of @var{filename} and @var{fp} is not a valid
|
|
pointer, and @code{GPG_ERR_ENOMEM} if not enough memory is available.
|
|
@end deftypefun
|
|
|
|
|
|
@node File Based Data Buffers
|
|
@subsection File Based Data Buffers
|
|
|
|
File based data objects operate directly on file descriptors or
|
|
streams. Only a small amount of data is stored in core at any time,
|
|
so the size of the data objects is not limited by @acronym{GPGME}.
|
|
|
|
@deftypefun gpgme_error_t gpgme_data_new_from_fd (@w{gpgme_data_t *@var{dh}}, @w{int @var{fd}})
|
|
The function @code{gpgme_data_new_from_fd} creates a new
|
|
@code{gpgme_data_t} object and uses the file descriptor @var{fd} to read
|
|
from (if used as an input data object) and write to (if used as an
|
|
output data object).
|
|
|
|
When using the data object as an input buffer, the function might read
|
|
a bit more from the file descriptor than is actually needed by the
|
|
crypto engine in the desired operation because of internal buffering.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
data object was successfully created, and @code{GPG_ERR_ENOMEM} if not
|
|
enough memory is available.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_error_t gpgme_data_new_from_stream (@w{gpgme_data_t *@var{dh}}, @w{FILE *@var{stream}})
|
|
The function @code{gpgme_data_new_from_stream} creates a new
|
|
@code{gpgme_data_t} object and uses the I/O stream @var{stream} to read
|
|
from (if used as an input data object) and write to (if used as an
|
|
output data object).
|
|
|
|
When using the data object as an input buffer, the function might read
|
|
a bit more from the stream than is actually needed by the crypto
|
|
engine in the desired operation because of internal buffering.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
data object was successfully created, and @code{GPG_ERR_ENOMEM} if not
|
|
enough memory is available.
|
|
@end deftypefun
|
|
|
|
|
|
@node Callback Based Data Buffers
|
|
@subsection Callback Based Data Buffers
|
|
|
|
If neither memory nor file based data objects are a good fit for your
|
|
application, you can implement the functions a data object provides
|
|
yourself and create a data object from these callback functions.
|
|
|
|
@deftp {Data type} {ssize_t (*gpgme_data_read_cb_t) (@w{void *@var{handle}}, @w{void @var{*buffer}}, @w{size_t @var{size}})}
|
|
@tindex gpgme_data_read_cb_t
|
|
The @code{gpgme_data_read_cb_t} type is the type of functions which
|
|
@acronym{GPGME} calls if it wants to read data from a user-implemented
|
|
data object. The function should read up to @var{size} bytes from the
|
|
current read position into the space starting at @var{buffer}. The
|
|
@var{handle} is provided by the user at data object creation time.
|
|
|
|
The function should return the number of bytes read, 0 on EOF, and -1
|
|
on error. If an error occurs, @var{errno} should be set to describe
|
|
the type of the error.
|
|
@end deftp
|
|
|
|
@deftp {Data type} {ssize_t (*gpgme_data_write_cb_t) (@w{void *@var{handle}}, @w{const void @var{*buffer}}, @w{size_t @var{size}})}
|
|
@tindex gpgme_data_write_cb_t
|
|
The @code{gpgme_data_write_cb_t} type is the type of functions which
|
|
@acronym{GPGME} calls if it wants to write data to a user-implemented
|
|
data object. The function should write up to @var{size} bytes to the
|
|
current write position from the space starting at @var{buffer}. The
|
|
@var{handle} is provided by the user at data object creation time.
|
|
|
|
The function should return the number of bytes written, and -1 on
|
|
error. If an error occurs, @var{errno} should be set to describe the
|
|
type of the error.
|
|
@end deftp
|
|
|
|
@deftp {Data type} {off_t (*gpgme_data_seek_cb_t) (@w{void *@var{handle}}, @w{off_t @var{offset}}, @w{int @var{whence}})}
|
|
@tindex gpgme_data_seek_cb_t
|
|
The @code{gpgme_data_seek_cb_t} type is the type of functions which
|
|
@acronym{GPGME} calls if it wants to change the current read/write
|
|
position in a user-implemented data object, just like the @code{lseek}
|
|
function.
|
|
|
|
The function should return the new read/write position, and -1 on
|
|
error. If an error occurs, @var{errno} should be set to describe the
|
|
type of the error.
|
|
@end deftp
|
|
|
|
@deftp {Data type} {void (*gpgme_data_release_cb_t) (@w{void *@var{handle}})}
|
|
@tindex gpgme_data_release_cb_t
|
|
The @code{gpgme_data_release_cb_t} type is the type of functions which
|
|
@acronym{GPGME} calls if it wants to destroy a user-implemented data
|
|
object. The @var{handle} is provided by the user at data object
|
|
creation time.
|
|
@end deftp
|
|
|
|
@deftp {Data type} {struct gpgme_data_cbs}
|
|
This structure is used to store the data callback interface functions
|
|
described above. It has the following members:
|
|
|
|
@table @code
|
|
@item gpgme_data_read_cb_t read
|
|
This is the function called by @acronym{GPGME} to read data from the
|
|
data object. It is only required for input data object.
|
|
|
|
@item gpgme_data_write_cb_t write
|
|
This is the function called by @acronym{GPGME} to write data to the
|
|
data object. It is only required for output data object.
|
|
|
|
@item gpgme_data_seek_cb_t seek
|
|
This is the function called by @acronym{GPGME} to change the current
|
|
read/write pointer in the data object (if available). It is optional.
|
|
|
|
@item gpgme_data_release_cb_t release
|
|
This is the function called by @acronym{GPGME} to release a data
|
|
object. It is optional.
|
|
@end table
|
|
@end deftp
|
|
|
|
@deftypefun gpgme_error_t gpgme_data_new_from_cbs (@w{gpgme_data_t *@var{dh}}, @w{gpgme_data_cbs_t @var{cbs}}, @w{void *@var{handle}})
|
|
The function @code{gpgme_data_new_from_cbs} creates a new
|
|
@code{gpgme_data_t} object and uses the user-provided callback functions
|
|
to operate on the data object.
|
|
|
|
The handle @var{handle} is passed as first argument to the callback
|
|
functions. This can be used to identify this data object.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
data object was successfully created, and @code{GPG_ERR_ENOMEM} if not
|
|
enough memory is available.
|
|
@end deftypefun
|
|
|
|
The following interface is deprecated and only provided for backward
|
|
compatibility. Don't use it. It will be removed in a future version
|
|
of @acronym{GPGME}.
|
|
|
|
@deftypefun gpgme_error_t gpgme_data_new_with_read_cb (@w{gpgme_data_t *@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}})
|
|
The function @code{gpgme_data_new_with_read_cb} creates a new
|
|
@code{gpgme_data_t} object and uses the callback function @var{readfunc}
|
|
to retrieve the data on demand. As the callback function can supply
|
|
the data in any way it wants, this is the most flexible data type
|
|
@acronym{GPGME} provides. However, it can not be used to write data.
|
|
|
|
The callback function receives @var{hook_value} as its first argument
|
|
whenever it is invoked. It should return up to @var{count} bytes in
|
|
@var{buffer}, and return the number of bytes actually read in
|
|
@var{nread}. It may return @code{0} in @var{nread} if no data is
|
|
currently available. To indicate @code{EOF} the function should
|
|
return with an error code of @code{-1} and set @var{nread} to
|
|
@code{0}. The callback function may support to reset its internal
|
|
read pointer if it is invoked with @var{buffer} and @var{nread} being
|
|
@code{NULL} and @var{count} being @code{0}.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
data object was successfully created, @code{GPG_ERR_INV_VALUE} if
|
|
@var{dh} or @var{readfunc} is not a valid pointer, and
|
|
@code{GPG_ERR_ENOMEM} if not enough memory is available.
|
|
@end deftypefun
|
|
|
|
|
|
@node Destroying Data Buffers
|
|
@section Destroying Data Buffers
|
|
@cindex data buffer, destruction
|
|
|
|
@deftypefun void gpgme_data_release (@w{gpgme_data_t @var{dh}})
|
|
The function @code{gpgme_data_release} destroys the data object with
|
|
the handle @var{dh}. It releases all associated resources that were
|
|
not provided by the user in the first place.
|
|
@end deftypefun
|
|
|
|
@deftypefun {char *} gpgme_data_release_and_get_mem (@w{gpgme_data_t @var{dh}}, @w{size_t *@var{length}})
|
|
The function @code{gpgme_data_release_and_get_mem} is like
|
|
@code{gpgme_data_release}, except that it returns the data buffer and
|
|
its length that was provided by the object.
|
|
|
|
The user has to release the buffer with @code{gpgme_free}. In case
|
|
the user provided the data buffer in non-copy mode, a copy will be
|
|
made for this purpose.
|
|
|
|
In case an error returns, or there is no suitable data buffer that can
|
|
be returned to the user, the function will return @code{NULL}. In any
|
|
case, the data object @var{dh} is destroyed.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void gpgme_free (@w{void *@var{buffer}})
|
|
The function @code{gpgme_free} releases the memory returned by
|
|
@code{gpgme_data_release_and_get_mem}. It should be used instead of
|
|
the system libraries @code{free} function in case different allocators
|
|
are used in a single program.
|
|
@end deftypefun
|
|
|
|
|
|
@node Manipulating Data Buffers
|
|
@section Manipulating Data Buffers
|
|
@cindex data buffer, manipulation
|
|
|
|
Data buffers contain data and meta-data. The following operations can
|
|
be used to manipulate both.
|
|
|
|
|
|
@menu
|
|
* Data Buffer I/O Operations:: I/O operations on data buffers.
|
|
* Data Buffer Meta-Data:: Meta-data manipulation of data buffers.
|
|
@end menu
|
|
|
|
|
|
@node Data Buffer I/O Operations
|
|
@subsection Data Buffer I/O Operations
|
|
@cindex data buffer, I/O operations
|
|
@cindex data buffer, read
|
|
@cindex data buffer, write
|
|
@cindex data buffer, seek
|
|
|
|
@deftypefun ssize_t gpgme_data_read (@w{gpgme_data_t @var{dh}}, @w{void *@var{buffer}}, @w{size_t @var{length}})
|
|
The function @code{gpgme_data_read} reads up to @var{length} bytes
|
|
from the data object with the handle @var{dh} into the space starting
|
|
at @var{buffer}.
|
|
|
|
If no error occurs, the actual amount read is returned. If the end of
|
|
the data object is reached, the function returns 0.
|
|
|
|
In all other cases, the function returns -1 and sets @var{errno}.
|
|
@end deftypefun
|
|
|
|
@deftypefun ssize_t gpgme_data_write (@w{gpgme_data_t @var{dh}}, @w{const void *@var{buffer}}, @w{size_t @var{size}})
|
|
The function @code{gpgme_data_write} writes up to @var{size} bytes
|
|
starting from @var{buffer} into the data object with the handle
|
|
@var{dh} at the current write position.
|
|
|
|
The function returns the number of bytes actually written, or -1 if an
|
|
error occurs. If an error occurs, @var{errno} is set.
|
|
@end deftypefun
|
|
|
|
@deftypefun off_t gpgme_data_seek (@w{gpgme_data_t @var{dh}}, @w{off_t @var{offset}}, @w{int @var{whence}})
|
|
The function @code{gpgme_data_seek} changes the current read/write
|
|
position.
|
|
|
|
The @var{whence} argument specifies how the @var{offset} should be
|
|
interpreted. It must be one of the following symbolic constants:
|
|
|
|
@table @code
|
|
@item SEEK_SET
|
|
Specifies that @var{offset} is a count of characters from the
|
|
beginning of the data object.
|
|
|
|
@item SEEK_CUR
|
|
Specifies that @var{offset} is a count of characters from the current
|
|
file position. This count may be positive or negative.
|
|
|
|
@item SEEK_END
|
|
Specifies that @var{offset} is a count of characters from the end of
|
|
the data object. A negative count specifies a position within the
|
|
current extent of the data object; a positive count specifies a
|
|
position past the current end. If you set the position past the
|
|
current end, and actually write data, you will extend the data object
|
|
with zeros up to that position.
|
|
@end table
|
|
|
|
If successful, the function returns the resulting file position,
|
|
measured in bytes from the beginning of the data object. You can use
|
|
this feature together with @code{SEEK_CUR} to read the current
|
|
read/write position.
|
|
|
|
If the function fails, -1 is returned and @var{errno} is set.
|
|
@end deftypefun
|
|
|
|
The following function is deprecated and should not be used. It will
|
|
be removed in a future version of @acronym{GPGME}.
|
|
|
|
@deftypefun gpgme_error_t gpgme_data_rewind (@w{gpgme_data_t @var{dh}})
|
|
The function @code{gpgme_data_rewind} is equivalent to:
|
|
|
|
@example
|
|
return (gpgme_data_seek (dh, 0, SEEK_SET) == -1)
|
|
? gpgme_error_from_errno (errno) : 0;
|
|
@end example
|
|
@end deftypefun
|
|
|
|
|
|
|
|
|
|
@node Data Buffer Meta-Data
|
|
@subsection Data Buffer Meta-Data
|
|
@cindex data buffer, meta-data
|
|
@cindex data buffer, file name
|
|
@cindex data buffer, encoding
|
|
|
|
@deftypefun {char *} gpgme_data_get_file_name (@w{gpgme_data_t @var{dh}})
|
|
The function @code{gpgme_data_get_file_name} returns a pointer to a
|
|
string containing the file name associated with the data object. The
|
|
file name will be stored in the output when encrypting or signing the
|
|
data and will be returned to the user when decrypting or verifying the
|
|
output data.
|
|
|
|
If no error occurs, the string containing the file name is returned.
|
|
Otherwise, @code{NULL} will be returned.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun gpgme_error_t gpgme_data_set_file_name (@w{gpgme_data_t @var{dh}}, @w{const char *@var{file_name}})
|
|
The function @code{gpgme_data_set_file_name} sets the file name
|
|
associated with the data object. The file name will be stored in the
|
|
output when encrypting or signing the data and will be returned to the
|
|
user when decrypting or verifying the output data.
|
|
|
|
The function returns the error code @code{GPG_ERR_INV_VALUE} if
|
|
@var{dh} is not a valid pointer and @code{GPG_ERR_ENOMEM} if not
|
|
enough memory is available.
|
|
@end deftypefun
|
|
|
|
|
|
@deftp {Data type} {enum gpgme_data_encoding_t}
|
|
@tindex gpgme_data_encoding_t
|
|
The @code{gpgme_data_encoding_t} type specifies the encoding of a
|
|
@code{gpgme_data_t} object. This encoding is useful to give the backend
|
|
a hint on the type of data. The following data types are available:
|
|
|
|
@table @code
|
|
@item GPGME_DATA_ENCODING_NONE
|
|
This specifies that the encoding is not known. This is the default
|
|
for a new data object. The backend will try its best to detect the
|
|
encoding automatically.
|
|
|
|
@item GPGME_DATA_ENCODING_BINARY
|
|
This specifies that the data is encoding in binary form; i.e. there is
|
|
no special encoding.
|
|
|
|
@item GPGME_DATA_ENCODING_BASE64
|
|
This specifies that the data is encoded using the Base-64 encoding
|
|
scheme as used by @acronym{MIME} and other protocols.
|
|
|
|
@item GPGME_DATA_ENCODING_ARMOR
|
|
This specifies that the data is encoded in an armored form as used by
|
|
OpenPGP and PEM.
|
|
@end table
|
|
@end deftp
|
|
|
|
@deftypefun gpgme_data_encoding_t gpgme_data_get_encoding (@w{gpgme_data_t @var{dh}})
|
|
The function @code{gpgme_data_get_encoding} returns the encoding of
|
|
the data object with the handle @var{dh}. If @var{dh} is not a valid
|
|
pointer (e.g. @code{NULL}) @code{GPGME_DATA_ENCODING_NONE} is
|
|
returned.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_error_t gpgme_data_set_encoding (@w{gpgme_data_t @var{dh}, gpgme_data_encoding_t @var{enc}})
|
|
The function @code{gpgme_data_set_encoding} changes the encoding of
|
|
the data object with the handle @var{dh} to @var{enc}.
|
|
@end deftypefun
|
|
|
|
|
|
@c
|
|
@c Chapter Contexts
|
|
@c
|
|
@node Contexts
|
|
@chapter Contexts
|
|
@cindex context
|
|
|
|
All cryptographic operations in @acronym{GPGME} are performed within a
|
|
context, which contains the internal state of the operation as well as
|
|
configuration parameters. By using several contexts you can run
|
|
several cryptographic operations in parallel, with different
|
|
configuration.
|
|
|
|
@deftp {Data type} {gpgme_ctx_t}
|
|
The @code{gpgme_ctx_t} type is a handle for a @acronym{GPGME} context,
|
|
which is used to hold the configuration, status and result of
|
|
cryptographic operations.
|
|
@end deftp
|
|
|
|
@menu
|
|
* Creating Contexts:: Creating new @acronym{GPGME} contexts.
|
|
* Destroying Contexts:: Releasing @acronym{GPGME} contexts.
|
|
* Context Attributes:: Setting properties of a context.
|
|
* Key Management:: Managing keys with @acronym{GPGME}.
|
|
* Trust Item Management:: Managing trust items with @acronym{GPGME}.
|
|
* Crypto Operations:: Using a context for cryptography.
|
|
* Run Control:: Controlling how operations are run.
|
|
@end menu
|
|
|
|
|
|
@node Creating Contexts
|
|
@section Creating Contexts
|
|
@cindex context, creation
|
|
|
|
@deftypefun gpgme_error_t gpgme_new (@w{gpgme_ctx_t *@var{ctx}})
|
|
The function @code{gpgme_new} creates a new @code{gpgme_ctx_t} object
|
|
and returns a handle for it in @var{ctx}.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
context was successfully created, @code{GPG_ERR_INV_VALUE} if
|
|
@var{ctx} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if not
|
|
enough memory is available.
|
|
@end deftypefun
|
|
|
|
|
|
@node Destroying Contexts
|
|
@section Destroying Contexts
|
|
@cindex context, destruction
|
|
|
|
@deftypefun void gpgme_release (@w{gpgme_ctx_t @var{ctx}})
|
|
The function @code{gpgme_release} destroys the context with the handle
|
|
@var{ctx} and releases all associated resources.
|
|
@end deftypefun
|
|
|
|
|
|
@node Context Attributes
|
|
@section Context Attributes
|
|
@cindex context, attributes
|
|
|
|
@menu
|
|
* Protocol Selection:: Selecting the protocol used by a context.
|
|
* Crypto Engine:: Configuring the crypto engine.
|
|
* ASCII Armor:: Requesting @acronym{ASCII} armored output.
|
|
* Text Mode:: Choosing canonical text mode.
|
|
* Included Certificates:: Including a number of certificates.
|
|
* Key Listing Mode:: Selecting key listing mode.
|
|
* Passphrase Callback:: Getting the passphrase from the user.
|
|
* Progress Meter Callback:: Being informed about the progress.
|
|
* Locale:: Setting the locale of a context.
|
|
@end menu
|
|
|
|
|
|
@node Protocol Selection
|
|
@subsection Protocol Selection
|
|
@cindex context, selecting protocol
|
|
@cindex protocol, selecting
|
|
|
|
@deftypefun gpgme_error_t gpgme_set_protocol (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_protocol_t @var{proto}})
|
|
The function @code{gpgme_set_protocol} sets the protocol used within
|
|
the context @var{ctx} to @var{proto}. All crypto operations will be
|
|
performed by the crypto engine configured for that protocol.
|
|
@xref{Protocols and Engines}.
|
|
|
|
Setting the protocol with @code{gpgme_set_protocol} does not check if
|
|
the crypto engine for that protocol is available and installed
|
|
correctly. @xref{Engine Version Check}.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
protocol could be set successfully, and @code{GPG_ERR_INV_VALUE} if
|
|
@var{protocol} is not a valid protocol.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_protocol_t gpgme_get_protocol (@w{gpgme_ctx_t @var{ctx}})
|
|
The function @code{gpgme_get_protocol} retrieves the protocol currently
|
|
use with the context @var{ctx}.
|
|
@end deftypefun
|
|
|
|
|
|
@node Crypto Engine
|
|
@subsection Crypto Engine
|
|
@cindex context, configuring engine
|
|
@cindex engine, configuration per context
|
|
|
|
The following functions can be used to set and retrieve the
|
|
configuration of the crypto engines of a specific context. The
|
|
default can also be retrieved without any particular context.
|
|
@xref{Engine Information}. The default can also be changed globally.
|
|
@xref{Engine Configuration}.
|
|
|
|
@deftypefun gpgme_engine_info_t gpgme_ctx_get_engine_info (@w{gpgme_ctx_t @var{ctx}})
|
|
The function @code{gpgme_ctx_get_engine_info} returns a linked list of
|
|
engine info structures. Each info structure describes the
|
|
configuration of one configured backend, as used by the context
|
|
@var{ctx}.
|
|
|
|
The result is valid until the next invocation of
|
|
@code{gpgme_ctx_set_engine_info} for this particular context.
|
|
|
|
This function can not fail.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_error_t gpgme_ctx_set_engine_info (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_protocol_t @var{proto}}, @w{const char *@var{file_name}}, @w{const char *@var{home_dir}})
|
|
The function @code{gpgme_ctx_set_engine_info} changes the
|
|
configuration of the crypto engine implementing the protocol
|
|
@var{proto} for the context @var{ctx}.
|
|
|
|
@var{file_name} is the file name of the executable program
|
|
implementing this protocol, and @var{home_dir} is the directory name
|
|
of the configuration directory for this crypto engine. If
|
|
@var{home_dir} is @code{NULL}, the engine's default will be used.
|
|
|
|
Currently this function must be used before starting the first crypto
|
|
operation. It is unspecified if and when the changes will take effect
|
|
if the function is called after starting the first operation on the
|
|
context @var{ctx}.
|
|
|
|
This function returns the error code @code{GPG_ERR_NO_ERROR} if
|
|
successful, or an eror code on failure.
|
|
@end deftypefun
|
|
|
|
|
|
@c FIXME: Unfortunately, using @acronym here breaks texi2dvi.
|
|
@node ASCII Armor
|
|
@subsection @acronym{ASCII} Armor
|
|
@cindex context, armor mode
|
|
@cindex @acronym{ASCII} armor
|
|
@cindex armor mode
|
|
|
|
@deftypefun void gpgme_set_armor (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{yes}})
|
|
The function @code{gpgme_set_armor} specifies if the output should be
|
|
@acronym{ASCII} armored. By default, output is not @acronym{ASCII}
|
|
armored.
|
|
|
|
@acronym{ASCII} armored output is disabled if @var{yes} is zero, and
|
|
enabled otherwise.
|
|
@end deftypefun
|
|
|
|
@deftypefun int gpgme_get_armor (@w{gpgme_ctx_t @var{ctx}})
|
|
The function @code{gpgme_get_armor} returns 1 if the output is
|
|
@acronym{ASCII} armored, and @code{0} if it is not, or if @var{ctx} is
|
|
not a valid pointer.
|
|
@end deftypefun
|
|
|
|
|
|
@node Text Mode
|
|
@subsection Text Mode
|
|
@cindex context, text mode
|
|
@cindex text mode
|
|
@cindex canonical text mode
|
|
|
|
@deftypefun void gpgme_set_textmode (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{yes}})
|
|
The function @code{gpgme_set_textmode} specifies if canonical text mode
|
|
should be used. By default, text mode is not used.
|
|
|
|
Text mode is for example used for the RFC2015 signatures; note that
|
|
the updated RFC 3156 mandates that the mail user agent does some
|
|
preparations so that text mode is not needed anymore.
|
|
|
|
This option is only relevant to the OpenPGP crypto engine, and ignored
|
|
by all other engines.
|
|
|
|
Canonical text mode is disabled if @var{yes} is zero, and enabled
|
|
otherwise.
|
|
@end deftypefun
|
|
|
|
@deftypefun int gpgme_get_textmode (@w{gpgme_ctx_t @var{ctx}})
|
|
The function @code{gpgme_get_textmode} returns 1 if canonical text
|
|
mode is enabled, and @code{0} if it is not, or if @var{ctx} is not a
|
|
valid pointer.
|
|
@end deftypefun
|
|
|
|
|
|
@node Included Certificates
|
|
@subsection Included Certificates
|
|
@cindex certificates, included
|
|
|
|
@deftypefun void gpgme_set_include_certs (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{nr_of_certs}})
|
|
The function @code{gpgme_set_include_certs} specifies how many
|
|
certificates should be included in an S/MIME signed message. By
|
|
default, only the sender's certificate is included. The possible
|
|
values of @var{nr_of_certs} are:
|
|
|
|
@table @code
|
|
@item GPGME_INCLUDE_CERTS_DEFAULT
|
|
Fall back to the default of the crypto backend. This is the default
|
|
for GPGME.
|
|
@item -2
|
|
Include all certificates except the root certificate.
|
|
@item -1
|
|
Include all certificates.
|
|
@item 0
|
|
Include no certificates.
|
|
@item 1
|
|
Include the sender's certificate only.
|
|
@item n
|
|
Include the first n certificates of the certificates path, starting
|
|
from the sender's certificate. The number @code{n} must be positive.
|
|
@end table
|
|
|
|
Values of @var{nr_of_certs} smaller than -2 are undefined.
|
|
|
|
This option is only relevant to the CMS crypto engine, and ignored by
|
|
all other engines.
|
|
@end deftypefun
|
|
|
|
@deftypefun int gpgme_get_include_certs (@w{gpgme_ctx_t @var{ctx}})
|
|
The function @code{gpgme_get_include_certs} returns the number of
|
|
certificates to include into an S/MIME signed message.
|
|
@end deftypefun
|
|
|
|
|
|
@node Key Listing Mode
|
|
@subsection Key Listing Mode
|
|
@cindex key listing mode
|
|
@cindex key listing, mode of
|
|
|
|
@deftypefun gpgme_error_t gpgme_set_keylist_mode (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_keylist_mode_t @var{mode}})
|
|
The function @code{gpgme_set_keylist_mode} changes the default
|
|
behaviour of the key listing functions. The value in @var{mode} is a
|
|
bitwise-or combination of one or multiple of the following bit values:
|
|
|
|
@table @code
|
|
@item GPGME_KEYLIST_MODE_LOCAL
|
|
The @code{GPGME_KEYLIST_MODE_LOCAL} symbol specifies that the local
|
|
keyring should be searched for keys in the keylisting operation. This
|
|
is the default.
|
|
|
|
@item GPGME_KEYLIST_MODE_EXTERN
|
|
The @code{GPGME_KEYLIST_MODE_EXTERN} symbol specifies that an external
|
|
source should be searched for keys in the keylisting
|
|
operation. The type of external source is dependant on the crypto
|
|
engine used. For example, it can be a remote keyserver or LDAP
|
|
certificate server.
|
|
|
|
@item GPGME_KEYLIST_MODE_SIGS
|
|
The @code{GPGME_KEYLIST_MODE_SIGS} symbol specifies that the key
|
|
signatures should be included in the listed keys.
|
|
|
|
@item GPGME_KEYLIST_MODE_SIG_NOTATIONS
|
|
The @code{GPGME_KEYLIST_MODE_SIG_NOTATIONS} symbol specifies that the
|
|
signature notations on key signatures should be included in the listed
|
|
keys. This only works if @code{GPGME_KEYLIST_MODE_SIGS} is also
|
|
enabled.
|
|
|
|
@item GPGME_KEYLIST_MODE_VALIDATE
|
|
The @code{GPGME_KEYLIST_MODE_VALIDATE} symbol specifies that the
|
|
backend should do key or certificate validation and not just get the
|
|
validity information from an internal cache. This might be an
|
|
expensive operation and is in general not useful. Currently only
|
|
implemented for the S/MIME backend and ignored for other backends.
|
|
|
|
@end table
|
|
|
|
At least one of @code{GPGME_KEYLIST_MODE_LOCAL} and
|
|
@code{GPGME_KEYLIST_MODE_EXTERN} must be specified. For future binary
|
|
compatibility, you should get the current mode with
|
|
@code{gpgme_get_keylist_mode} and modify it by setting or clearing the
|
|
appropriate bits, and then using that calulcated value in the
|
|
@code{gpgme_set_keylisting_mode} operation. This will leave all other
|
|
bits in the mode value intact (in particular those that are not used
|
|
in the current version of the library).
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
mode could be set correctly, and @code{GPG_ERR_INV_VALUE} if @var{ctx}
|
|
is not a valid pointer or @var{mode} is not a valid mode.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun gpgme_keylist_mode_t gpgme_get_keylist_mode (@w{gpgme_ctx_t @var{ctx}})
|
|
The function @code{gpgme_get_keylist_mode} returns the current key
|
|
listing mode of the context @var{ctx}. This value can then be
|
|
modified and used in a subsequent @code{gpgme_set_keylist_mode}
|
|
operation to only affect the desired bits (and leave all others
|
|
intact).
|
|
|
|
The function returns 0 if @var{ctx} is not a valid pointer, and the
|
|
current mode otherwise. Note that 0 is not a valid mode value.
|
|
@end deftypefun
|
|
|
|
|
|
@node Passphrase Callback
|
|
@subsection Passphrase Callback
|
|
@cindex callback, passphrase
|
|
@cindex passphrase callback
|
|
|
|
@deftp {Data type} {gpgme_error_t (*gpgme_passphrase_cb_t)(void *@var{hook}, const char *@var{uid_hint}, const char *@var{passphrase_info}, @w{int @var{prev_was_bad}}, @w{int @var{fd}})}
|
|
@tindex gpgme_passphrase_cb_t
|
|
The @code{gpgme_passphrase_cb_t} type is the type of functions usable as
|
|
passphrase callback function.
|
|
|
|
The argument @var{uid_hint} might contain a string that gives an
|
|
indication for which user ID the passphrase is required. If this is
|
|
not available, or not applicable (in the case of symmetric encryption,
|
|
for example), @var{uid_hint} will be @code{NULL}.
|
|
|
|
The argument @var{passphrase_info}, if not @code{NULL}, will give
|
|
further information about the context in which the passphrase is
|
|
required. This information is engine and operation specific.
|
|
|
|
If this is the repeated attempt to get the passphrase, because
|
|
previous attempts failed, then @var{prev_was_bad} is 1, otherwise it
|
|
will be 0.
|
|
|
|
The user must write the passphrase, followed by a newline character,
|
|
to the file descriptor @var{fd}. If the user returns 0 indicating
|
|
success, the user must at least write a newline character before
|
|
returning from the callback.
|
|
|
|
If an error occurs, return the corresponding @code{gpgme_error_t}
|
|
value. You can use the error code @code{GPG_ERR_CANCELED} to abort
|
|
the operation. Otherwise, return @code{0}.
|
|
@end deftp
|
|
|
|
@deftypefun void gpgme_set_passphrase_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_passphrase_cb_t @var{passfunc}}, @w{void *@var{hook_value}})
|
|
The function @code{gpgme_set_passphrase_cb} sets the function that is
|
|
used when a passphrase needs to be provided by the user to
|
|
@var{passfunc}. The function @var{passfunc} needs to implemented by
|
|
the user, and whenever it is called, it is called with its first
|
|
argument being @var{hook_value}. By default, no passphrase callback
|
|
function is set.
|
|
|
|
Not all crypto engines require this callback to retrieve the
|
|
passphrase. It is better if the engine retrieves the passphrase from
|
|
a trusted agent (a daemon process), rather than having each user to
|
|
implement their own passphrase query. Some engines do not even
|
|
support an external passphrase callback at all, in this case the error
|
|
code @code{GPG_ERR_NOT_SUPPORTED} is returned.
|
|
|
|
The user can disable the use of a passphrase callback function by
|
|
calling @code{gpgme_set_passphrase_cb} with @var{passfunc} being
|
|
@code{NULL}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void gpgme_get_passphrase_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_passphrase_cb_t *@var{passfunc}}, @w{void **@var{hook_value}})
|
|
The function @code{gpgme_get_passphrase_cb} returns the function that
|
|
is used when a passphrase needs to be provided by the user in
|
|
@var{*passfunc}, and the first argument for this function in
|
|
@var{*hook_value}. If no passphrase callback is set, or @var{ctx} is
|
|
not a valid pointer, @code{NULL} is returned in both variables.
|
|
|
|
@var{passfunc} or @var{hook_value} can be @code{NULL}. In this case,
|
|
the corresponding value will not be returned.
|
|
@end deftypefun
|
|
|
|
|
|
@node Progress Meter Callback
|
|
@subsection Progress Meter Callback
|
|
@cindex callback, progress meter
|
|
@cindex progress meter callback
|
|
|
|
@deftp {Data type} {void (*gpgme_progress_cb_t)(void *@var{hook}, const char *@var{what}, int @var{type}, int @var{current}, int @var{total})}
|
|
@tindex gpgme_progress_cb_t
|
|
The @code{gpgme_progress_cb_t} type is the type of functions usable as
|
|
progress callback function.
|
|
|
|
The arguments are specific to the crypto engine. More information
|
|
about the progress information returned from the GnuPG engine can be
|
|
found in the GnuPG source code in the file @file{doc/DETAILS} in the
|
|
section PROGRESS.
|
|
@end deftp
|
|
|
|
@deftypefun void gpgme_set_progress_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_progress_cb_t @var{progfunc}}, @w{void *@var{hook_value}})
|
|
The function @code{gpgme_set_progress_cb} sets the function that is
|
|
used when progress information about a cryptographic operation is
|
|
available. The function @var{progfunc} needs to implemented by the
|
|
user, and whenever it is called, it is called with its first argument
|
|
being @var{hook_value}. By default, no progress callback function
|
|
is set.
|
|
|
|
Setting a callback function allows an interactive program to display
|
|
progress information about a long operation to the user.
|
|
|
|
The user can disable the use of a progress callback function by
|
|
calling @code{gpgme_set_progress_cb} with @var{progfunc} being
|
|
@code{NULL}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void gpgme_get_progress_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_progress_cb_t *@var{progfunc}}, @w{void **@var{hook_value}})
|
|
The function @code{gpgme_get_progress_cb} returns the function that is
|
|
used to inform the user about the progress made in @var{*progfunc},
|
|
and the first argument for this function in @var{*hook_value}. If no
|
|
progress callback is set, or @var{ctx} is not a valid pointer,
|
|
@code{NULL} is returned in both variables.
|
|
|
|
@var{progfunc} or @var{hook_value} can be @code{NULL}. In this case,
|
|
the corresponding value will not be returned.
|
|
@end deftypefun
|
|
|
|
|
|
@node Locale
|
|
@subsection Locale
|
|
@cindex locale, default
|
|
@cindex locale, of a context
|
|
|
|
A locale setting can be associated with a context. This locale is
|
|
passed to the crypto engine, and used for applications like the PIN
|
|
entry, which is displayed to the user when entering a passphrase is
|
|
required.
|
|
|
|
The default locale is used to initialize the locale setting of all
|
|
contexts created afterwards.
|
|
|
|
@deftypefun gpgme_error_t gpgme_set_locale (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{category}}, @w{const char *@var{value}})
|
|
The function @code{gpgme_set_locale} sets the locale of the context
|
|
@var{ctx}, or the default locale if @var{ctx} is a null pointer.
|
|
|
|
The locale settings that should be changed are specified by
|
|
@var{category}. Supported categories are @code{LC_CTYPE},
|
|
@code{LC_MESSAGES}, and @code{LC_ALL}, which is a wildcard you can use
|
|
if you want to change all the categories at once.
|
|
|
|
The value to be used for the locale setting is @var{value}, which will
|
|
be copied to @acronym{GPGME}'s internal data structures. @var{value}
|
|
can be a null pointer, which disables setting the locale, and will
|
|
make PIN entry and other applications use their default setting, which
|
|
is usually not what you want.
|
|
|
|
Note that the settings are only used if the application runs on a text
|
|
terminal, and that the settings should fit the configuration of the
|
|
output terminal. Normally, it is sufficient to initialize the default
|
|
value at startup.
|
|
|
|
The function returns an error if not enough memory is available.
|
|
@end deftypefun
|
|
|
|
|
|
@node Key Management
|
|
@section Key Management
|
|
@cindex key management
|
|
|
|
Some of the cryptographic operations require that recipients or
|
|
signers are specified. This is always done by specifying the
|
|
respective keys that should be used for the operation. The following
|
|
section describes how such keys can be selected and manipulated.
|
|
|
|
@deftp {Data type} gpgme_sub_key_t
|
|
The @code{gpgme_sub_key_t} type is a pointer to a subkey structure.
|
|
Sub keys are one component of a @code{gpgme_key_t} object. In fact,
|
|
subkeys are those parts that contains the real information about the
|
|
individual cryptographic keys that belong to the same key object. One
|
|
@code{gpgme_key_t} can contain several subkeys. The first subkey in
|
|
the linked list is also called the primary key.
|
|
|
|
The subkey structure has the following members:
|
|
|
|
@table @code
|
|
@item gpgme_sub_key_t next
|
|
This is a pointer to the next subkey structure in the linked list, or
|
|
@code{NULL} if this is the last element.
|
|
|
|
@item unsigned int revoked : 1
|
|
This is true if the subkey is revoked.
|
|
|
|
@item unsigned int expired : 1
|
|
This is true if the subkey is expired.
|
|
|
|
@item unsigned int disabled : 1
|
|
This is true if the subkey is disabled.
|
|
|
|
@item unsigned int invalid : 1
|
|
This is true if the subkey is invalid.
|
|
|
|
@item unsigned int can_encrypt : 1
|
|
This is true if the subkey can be used for encryption.
|
|
|
|
@item unsigned int can_sign : 1
|
|
This is true if the subkey can be used to create data signatures.
|
|
|
|
@item unsigned int can_certify : 1
|
|
This is true if the subkey can be used to create key certificates.
|
|
|
|
@item unsigned int can_authenticate : 1
|
|
This is true if the subkey can be used for authentication.
|
|
|
|
@item unsigned int is_qualified : 1
|
|
This is true if the subkey can be used for qualified signatures
|
|
according to local government regulations.
|
|
|
|
@item unsigned int secret : 1
|
|
This is true if the subkey is a secret key. Note that it will be false
|
|
if the key is actually a stub key; i.e. a secret key operation is
|
|
currently not possible (offline-key).
|
|
|
|
@item gpgme_pubkey_algo_t pubkey_algo
|
|
This is the public key algorithm supported by this subkey.
|
|
|
|
@item unsigned int length
|
|
This is the length of the subkey (in bits).
|
|
|
|
@item char *keyid
|
|
This is the key ID of the subkey in hexadecimal digits.
|
|
|
|
@item char *fpr
|
|
This is the fingerprint of the subkey in hexadecimal digits, if
|
|
available.
|
|
|
|
@item long int timestamp
|
|
This is the creation timestamp of the subkey. This is -1 if the
|
|
timestamp is invalid, and 0 if it is not available.
|
|
|
|
@item long int expires
|
|
This is the expiration timestamp of the subkey, or 0 if the subkey
|
|
does not expire.
|
|
@end table
|
|
@end deftp
|
|
|
|
@deftp {Data type} gpgme_key_sig_t
|
|
The @code{gpgme_key_sig_t} type is a pointer to a key signature structure.
|
|
Key signatures are one component of a @code{gpgme_key_t} object, and
|
|
validate user IDs on the key.
|
|
|
|
The signatures on a key are only available if the key was retrieved
|
|
via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode
|
|
enabled, because it can be expensive to retrieve all signatures of a
|
|
key.
|
|
|
|
The signature notations on a key signature are only available if the
|
|
key was retrieved via a listing operation with the
|
|
@code{GPGME_KEYLIST_MODE_SIG_NOTATIONS} mode enabled, because it can
|
|
be expensive to retrieve all signature notations.
|
|
|
|
The key signature structure has the following members:
|
|
|
|
@table @code
|
|
@item gpgme_key_sig_t next
|
|
This is a pointer to the next key signature structure in the linked
|
|
list, or @code{NULL} if this is the last element.
|
|
|
|
@item unsigned int revoked : 1
|
|
This is true if the key signature is a revocation signature.
|
|
|
|
@item unsigned int expired : 1
|
|
This is true if the key signature is expired.
|
|
|
|
@item unsigned int invalid : 1
|
|
This is true if the key signature is invalid.
|
|
|
|
@item unsigned int exportable : 1
|
|
This is true if the key signature is exportable.
|
|
|
|
@item gpgme_pubkey_algo_t pubkey_algo
|
|
This is the public key algorithm used to create the signature.
|
|
|
|
@item char *keyid
|
|
This is the key ID of the key (in hexadecimal digits) used to create
|
|
the signature.
|
|
|
|
@item long int timestamp
|
|
This is the creation timestamp of the key signature. This is -1 if
|
|
the timestamp is invalid, and 0 if it is not available.
|
|
|
|
@item long int expires
|
|
This is the expiration timestamp of the key signature, or 0 if the key
|
|
signature does not expire.
|
|
|
|
@item gpgme_error_t status
|
|
This is the status of the signature and has the same meaning as the
|
|
member of the same name in a @code{gpgme_signature_t} object.
|
|
|
|
@item unsigned int sig_class
|
|
This specifies the signature class of the key signature. The meaning
|
|
is specific to the crypto engine.
|
|
|
|
@item char *uid
|
|
This is the main user ID of the key used to create the signature.
|
|
|
|
@item char *name
|
|
This is the name component of @code{uid}, if available.
|
|
|
|
@item char *comment
|
|
This is the comment component of @code{uid}, if available.
|
|
|
|
@item char *email
|
|
This is the email component of @code{uid}, if available.
|
|
|
|
@item gpgme_sig_notation_t notations
|
|
This is a linked list with the notation data and policy URLs.
|
|
@end table
|
|
@end deftp
|
|
|
|
@deftp {Data type} gpgme_user_id_t
|
|
A user ID is a component of a @code{gpgme_key_t} object. One key can
|
|
have many user IDs. The first one in the list is the main (or
|
|
primary) user ID.
|
|
|
|
The user ID structure has the following members.
|
|
|
|
@table @code
|
|
@item gpgme_user_id_t next
|
|
This is a pointer to the next user ID structure in the linked list, or
|
|
@code{NULL} if this is the last element.
|
|
|
|
@item unsigned int revoked : 1
|
|
This is true if the user ID is revoked.
|
|
|
|
@item unsigned int invalid : 1
|
|
This is true if the user ID is invalid.
|
|
|
|
@item gpgme_validity_t validity
|
|
This specifies the validity of the user ID.
|
|
|
|
@item char *uid
|
|
This is the user ID string.
|
|
|
|
@item char *name
|
|
This is the name component of @code{uid}, if available.
|
|
|
|
@item char *comment
|
|
This is the comment component of @code{uid}, if available.
|
|
|
|
@item char *email
|
|
This is the email component of @code{uid}, if available.
|
|
|
|
@item gpgme_key_sig_t signatures
|
|
This is a linked list with the signatures on this user ID.
|
|
@end table
|
|
@end deftp
|
|
|
|
@deftp {Data type} gpgme_key_t
|
|
The @code{gpgme_key_t} type is a pointer to a key object. It has the
|
|
following members:
|
|
|
|
@table @code
|
|
@item gpgme_keylist_mode_t keylist_mode
|
|
The keylist mode that was active when the key was retrieved.
|
|
|
|
@item unsigned int revoked : 1
|
|
This is true if the key is revoked.
|
|
|
|
@item unsigned int expired : 1
|
|
This is true if the key is expired.
|
|
|
|
@item unsigned int disabled : 1
|
|
This is true if the key is disabled.
|
|
|
|
@item unsigned int invalid : 1
|
|
This is true if the key is invalid. This might have several reasons,
|
|
for a example for the S/MIME backend, it will be set in during key
|
|
listsing if the key could not be validated due to a missing
|
|
certificates or unmatched policies.
|
|
|
|
@item unsigned int can_encrypt : 1
|
|
This is true if the key (ie one of its subkeys) can be used for
|
|
encryption.
|
|
|
|
@item unsigned int can_sign : 1
|
|
This is true if the key (ie one of its subkeys) can be used to create
|
|
data signatures.
|
|
|
|
@item unsigned int can_certify : 1
|
|
This is true if the key (ie one of its subkeys) can be used to create
|
|
key certificates.
|
|
|
|
@item unsigned int can_authenticate : 1
|
|
This is true if the key (ie one of its subkeys) can be used for
|
|
authentication.
|
|
|
|
@item unsigned int is_qualified : 1
|
|
This is true if the key can be used for qualified signatures according
|
|
to local government regulations.
|
|
|
|
@item unsigned int secret : 1
|
|
This is true if the key is a secret key. Note, that this will always be
|
|
true even if the corresponding subkey flag may be false (offline/stub
|
|
keys).
|
|
|
|
@item gpgme_protocol_t protocol
|
|
This is the protocol supported by this key.
|
|
|
|
@item char *issuer_serial
|
|
If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
|
|
issuer serial.
|
|
|
|
@item char *issuer_name
|
|
If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
|
|
issuer name.
|
|
|
|
@item char *chain_id
|
|
If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
|
|
chain ID, which can be used to built the certificate chain.
|
|
|
|
@item gpgme_validity_t owner_trust
|
|
If @code{protocol} is @code{GPGME_PROTOCOL_OpenPGP}, then this is the
|
|
owner trust.
|
|
|
|
@item gpgme_sub_key_t subkeys
|
|
This is a linked list with the subkeys of the key. The first subkey
|
|
in the list is the primary key and usually available.
|
|
|
|
@item gpgme_user_id_t uids
|
|
This is a linked list with the user IDs of the key. The first user ID
|
|
in the list is the main (or primary) user ID.
|
|
@end table
|
|
@end deftp
|
|
|
|
@menu
|
|
* Listing Keys:: Browsing the list of available keys.
|
|
* Information About Keys:: Requesting detailed information about keys.
|
|
* Key Signatures:: Listing the signatures on a key.
|
|
* Manipulating Keys:: Operations on keys.
|
|
* Generating Keys:: Creating new key pairs.
|
|
* Exporting Keys:: Retrieving key data from the key ring.
|
|
* Importing Keys:: Adding keys to the key ring.
|
|
* Deleting Keys:: Removing keys from the key ring.
|
|
* Advanced Key Editing:: Advanced key edit operation.
|
|
@end menu
|
|
|
|
|
|
@node Listing Keys
|
|
@subsection Listing Keys
|
|
@cindex listing keys
|
|
@cindex key listing
|
|
@cindex key listing, start
|
|
@cindex key ring, list
|
|
@cindex key ring, search
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_keylist_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}})
|
|
The function @code{gpgme_op_keylist_start} initiates a key listing
|
|
operation inside the context @var{ctx}. It sets everything up so that
|
|
subsequent invocations of @code{gpgme_op_keylist_next} return the keys
|
|
in the list.
|
|
|
|
If @var{pattern} is @code{NULL}, all available keys are returned.
|
|
Otherwise, @var{pattern} contains an engine specific expression that
|
|
is used to limit the list to all keys matching the pattern. Note that
|
|
the total length of the pattern is restricted to an engine-specific
|
|
maximum (a couple of hundred characters are usually accepted). The
|
|
pattern should be used to restrict the search to a certain common name
|
|
or user, not to list many specific keys at once by listing their
|
|
fingerprints or key IDs.
|
|
|
|
If @var{secret_only} is not @code{0}, the list is restricted to secret
|
|
keys only.
|
|
|
|
The context will be busy until either all keys are received (and
|
|
@code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}), or
|
|
@code{gpgme_op_keylist_end} is called to finish the operation.
|
|
|
|
The function returns the error code @code{GPG_ERR_INV_VALUE} if
|
|
@var{ctx} is not a valid pointer, and passes through any errors that
|
|
are reported by the crypto engine support routines.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_keylist_ext_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}[]}, @w{int @var{secret_only}}, @w{int @var{reserved}})
|
|
The function @code{gpgme_op_keylist_ext_start} initiates an extended
|
|
key listing operation inside the context @var{ctx}. It sets
|
|
everything up so that subsequent invocations of
|
|
@code{gpgme_op_keylist_next} return the keys in the list.
|
|
|
|
If @var{pattern} or @var{*pattern} is @code{NULL}, all available keys
|
|
are returned. Otherwise, @var{pattern} is a @code{NULL} terminated
|
|
array of strings that are used to limit the list to all keys matching
|
|
at least one of the patterns verbatim. Note that the total length of
|
|
all patterns is restricted to an engine-specific maximum (the exact
|
|
limit also depends on the number of patterns and amount of quoting
|
|
required, but a couple of hundred characters are usually accepted).
|
|
Patterns should be used to restrict the search to a certain common
|
|
name or user, not to list many specific keys at once by listing their
|
|
fingerprints or key IDs.
|
|
|
|
If @var{secret_only} is not @code{0}, the list is restricted to secret
|
|
keys only.
|
|
|
|
The value of @var{reserved} must be @code{0}.
|
|
|
|
The context will be busy until either all keys are received (and
|
|
@code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}), or
|
|
@code{gpgme_op_keylist_end} is called to finish the operation.
|
|
|
|
The function returns the error code @code{GPG_ERR_INV_VALUE} if
|
|
@var{ctx} is not a valid pointer, and passes through any errors that
|
|
are reported by the crypto engine support routines.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_keylist_next (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t *@var{r_key}})
|
|
The function @code{gpgme_op_keylist_next} returns the next key in the
|
|
list created by a previous @code{gpgme_op_keylist_start} operation in
|
|
the context @var{ctx}. The key will have one reference for the user.
|
|
@xref{Manipulating Keys}.
|
|
|
|
This is the only way to get at @code{gpgme_key_t} objects in
|
|
@acronym{GPGME}.
|
|
|
|
If the last key in the list has already been returned,
|
|
@code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}.
|
|
|
|
The function returns the error code @code{GPG_ERR_INV_VALUE} if
|
|
@var{ctx} or @var{r_key} is not a valid pointer, and
|
|
@code{GPG_ERR_ENOMEM} if there is not enough memory for the operation.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_keylist_end (@w{gpgme_ctx_t @var{ctx}})
|
|
The function @code{gpgme_op_keylist_next} ends a pending key list
|
|
operation in the context @var{ctx}.
|
|
|
|
After the operation completed successfully, the result of the key
|
|
listing operation can be retrieved with
|
|
@code{gpgme_op_keylist_result}.
|
|
|
|
The function returns the error code @code{GPG_ERR_INV_VALUE} if
|
|
@var{ctx} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if at some
|
|
time during the operation there was not enough memory available.
|
|
@end deftypefun
|
|
|
|
The following example illustrates how all keys containing a certain
|
|
string (@code{g10code}) can be listed with their key ID and the name
|
|
and e-mail address of the main user ID:
|
|
|
|
@example
|
|
gpgme_ctx_t ctx;
|
|
gpgme_error_t err = gpgme_new (&ctx);
|
|
|
|
if (!err)
|
|
@{
|
|
err = gpgme_op_keylist_start (ctx, "g10code", 0);
|
|
while (!err)
|
|
@{
|
|
err = gpgme_op_keylist_next (ctx, &key);
|
|
if (err)
|
|
break;
|
|
printf ("%s: %s <%s>\n", key->keyid, key->name, key->email);
|
|
gpgme_key_release (key);
|
|
@}
|
|
gpgme_release (ctx);
|
|
@}
|
|
if (gpg_err_code (err) != GPG_ERR_EOF)
|
|
@{
|
|
fprintf (stderr, "%s: can not list keys: %s\n",
|
|
argv[0], gpgme_strerror (err));
|
|
exit (1);
|
|
@}
|
|
@end example
|
|
|
|
@deftp {Data type} {gpgme_keylist_result_t}
|
|
This is a pointer to a structure used to store the result of a
|
|
@code{gpgme_op_keylist_*} operation. After successfully ending a key
|
|
listing operation, you can retrieve the pointer to the result with
|
|
@code{gpgme_op_keylist_result}. The structure contains the following
|
|
member:
|
|
|
|
@table @code
|
|
@item unsigned int truncated : 1
|
|
This is true if the crypto backend had to truncate the result, and
|
|
less than the desired keys could be listed.
|
|
@end table
|
|
@end deftp
|
|
|
|
@deftypefun gpgme_keylist_result_t gpgme_op_keylist_result (@w{gpgme_ctx_t @var{ctx}})
|
|
The function @code{gpgme_op_keylist_result} returns a
|
|
@code{gpgme_keylist_result_t} pointer to a structure holding the
|
|
result of a @code{gpgme_op_keylist_*} operation. The pointer is only
|
|
valid if the last operation on the context was a key listing
|
|
operation, and if this operation finished successfully. The returned
|
|
pointer is only valid until the next operation is started on the
|
|
context.
|
|
@end deftypefun
|
|
|
|
In a simple program, for which a blocking operation is acceptable, the
|
|
following function can be used to retrieve a single key.
|
|
|
|
@deftypefun gpgme_error_t gpgme_get_key (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{fpr}}, @w{gpgme_key_t *@var{r_key}}, @w{int @var{secret}})
|
|
The function @code{gpgme_get_key} gets the key with the fingerprint
|
|
(or key ID) @var{fpr} from the crypto backend and return it in
|
|
@var{r_key}. If @var{secret} is true, get the secret key. The
|
|
currently active keylist mode is used to retrieve the key. The key
|
|
will have one reference for the user.
|
|
|
|
If the key is not found in the keyring, @code{gpgme_get_key} returns
|
|
the error code @code{GPG_ERR_NO_ERROR} and *@var{r_key} will be set to
|
|
@code{NULL}.
|
|
|
|
The function returns the error code @code{GPG_ERR_INV_VALUE} if
|
|
@var{ctx} or @var{r_key} is not a valid pointer or @var{fpr} is not a
|
|
fingerprint or key ID, @code{GPG_ERR_AMBIGUOUS_NAME} if the key ID was
|
|
not a unique specifier for a key, and @code{GPG_ERR_ENOMEM} if at some
|
|
time during the operation there was not enough memory available.
|
|
@end deftypefun
|
|
|
|
|
|
@node Information About Keys
|
|
@subsection Information About Keys
|
|
@cindex key, information about
|
|
@cindex key, attributes
|
|
@cindex attributes, of a key
|
|
|
|
Please see the beginning of this section for more information about
|
|
@code{gpgme_key_t} objects.
|
|
|
|
@deftp {Data type} gpgme_validity_t
|
|
The @code{gpgme_validity_t} type is used to specify the validity of a user ID
|
|
in a key. The following validities are defined:
|
|
|
|
@table @code
|
|
@item GPGME_VALIDITY_UNKNOWN
|
|
The user ID is of unknown validity. The string representation of this
|
|
validity is ``?''.
|
|
|
|
@item GPGME_VALIDITY_UNDEFINED
|
|
The validity of the user ID is undefined. The string representation of this
|
|
validity is ``q''.
|
|
|
|
@item GPGME_VALIDITY_NEVER
|
|
The user ID is never valid. The string representation of this
|
|
validity is ``n''.
|
|
|
|
@item GPGME_VALIDITY_MARGINAL
|
|
The user ID is marginally valid. The string representation of this
|
|
validity is ``m''.
|
|
|
|
@item GPGME_VALIDITY_FULL
|
|
The user ID is fully valid. The string representation of this
|
|
validity is ``f''.
|
|
|
|
@item GPGME_VALIDITY_ULTIMATE
|
|
The user ID is ultimately valid. The string representation of this
|
|
validity is ``u''.
|
|
@end table
|
|
@end deftp
|
|
|
|
|
|
The following interfaces are deprecated and only provided for backward
|
|
compatibility. Don't use them. They will be removed in a future
|
|
version of @acronym{GPGME}.
|
|
|
|
@deftp {Data type} gpgme_attr_t
|
|
The @code{gpgme_attr_t} type is used to specify a key or trust item
|
|
attribute. The following attributes are defined:
|
|
|
|
@table @code
|
|
@item GPGME_ATTR_KEYID
|
|
This is the key ID of a sub key. It is representable as a string.
|
|
|
|
For trust items, the trust item refers to the key with this ID.
|
|
|
|
@item GPGME_ATTR_FPR
|
|
This is the fingerprint of a sub key. It is representable as a
|
|
string.
|
|
|
|
@item GPGME_ATTR_ALGO
|
|
This is the crypto algorithm for which the sub key can be used. It
|
|
is representable as a string and as a number. The numbers correspond
|
|
to the @code{enum gcry_pk_algos} values in the gcrypt library.
|
|
|
|
@item GPGME_ATTR_LEN
|
|
This is the key length of a sub key. It is representable as a
|
|
number.
|
|
|
|
@item GPGME_ATTR_CREATED
|
|
This is the timestamp at creation time of a sub key. It is
|
|
representable as a number.
|
|
|
|
@item GPGME_ATTR_EXPIRE
|
|
This is the expiration time of a sub key. It is representable as a
|
|
number.
|
|
|
|
@item GPGME_ATTR_OTRUST
|
|
XXX FIXME (also for trust items)
|
|
|
|
@item GPGME_ATTR_USERID
|
|
This is a user ID. There can be more than one user IDs in a
|
|
@var{gpgme_key_t} object. The first one (with index 0) is the primary
|
|
user ID. The user ID is representable as a number.
|
|
|
|
For trust items, this is the user ID associated with this trust item.
|
|
|
|
@item GPGME_ATTR_NAME
|
|
This is the name belonging to a user ID. It is representable as a string.
|
|
|
|
@item GPGME_ATTR_EMAIL
|
|
This is the email address belonging to a user ID. It is representable
|
|
as a string.
|
|
|
|
@item GPGME_ATTR_COMMENT
|
|
This is the comment belonging to a user ID. It is representable as a
|
|
string.
|
|
|
|
@item GPGME_ATTR_VALIDITY
|
|
This is the validity belonging to a user ID. It is representable as a
|
|
string and as a number. See below for a list of available validities.
|
|
|
|
For trust items, this is the validity that is associated with this
|
|
trust item.
|
|
|
|
@item GPGME_ATTR_UID_REVOKED
|
|
This specifies if a user ID is revoked. It is representable as a
|
|
number, and is @code{1} if the user ID is revoked, and @code{0}
|
|
otherwise.
|
|
|
|
@item GPGME_ATTR_UID_INVALID
|
|
This specifies if a user ID is invalid. It is representable as a
|
|
number, and is @code{1} if the user ID is invalid, and @code{0}
|
|
otherwise.
|
|
|
|
@item GPGME_ATTR_LEVEL
|
|
This is the trust level of a trust item.
|
|
|
|
@item GPGME_ATTR_TYPE
|
|
This returns information about the type of key. For the string function
|
|
this will eother be "PGP" or "X.509". The integer function returns 0
|
|
for PGP and 1 for X.509. It is also used for the type of a trust item.
|
|
|
|
@item GPGME_ATTR_IS_SECRET
|
|
This specifies if the key is a secret key. It is representable as a
|
|
number, and is @code{1} if the key is revoked, and @code{0} otherwise.
|
|
|
|
@item GPGME_ATTR_KEY_REVOKED
|
|
This specifies if a sub key is revoked. It is representable as a
|
|
number, and is @code{1} if the key is revoked, and @code{0} otherwise.
|
|
|
|
@item GPGME_ATTR_KEY_INVALID
|
|
This specifies if a sub key is invalid. It is representable as a
|
|
number, and is @code{1} if the key is invalid, and @code{0} otherwise.
|
|
|
|
@item GPGME_ATTR_KEY_EXPIRED
|
|
This specifies if a sub key is expired. It is representable as a
|
|
number, and is @code{1} if the key is expired, and @code{0} otherwise.
|
|
|
|
@item GPGME_ATTR_KEY_DISABLED
|
|
This specifies if a sub key is disabled. It is representable as a
|
|
number, and is @code{1} if the key is disabled, and @code{0} otherwise.
|
|
|
|
@item GPGME_ATTR_KEY_CAPS
|
|
This is a description of the capabilities of a sub key. It is
|
|
representable as a string. The string contains the letter ``e'' if
|
|
the key can be used for encryption, ``s'' if the key can be used for
|
|
signatures, and ``c'' if the key can be used for certifications.
|
|
|
|
@item GPGME_ATTR_CAN_ENCRYPT
|
|
This specifies if a sub key can be used for encryption. It is
|
|
representable as a number, and is @code{1} if the sub key can be used
|
|
for encryption, and @code{0} otherwise.
|
|
|
|
@item GPGME_ATTR_CAN_SIGN
|
|
This specifies if a sub key can be used to create data signatures. It
|
|
is representable as a number, and is @code{1} if the sub key can be
|
|
used for signatures, and @code{0} otherwise.
|
|
|
|
@item GPGME_ATTR_CAN_CERTIFY
|
|
This specifies if a sub key can be used to create key certificates.
|
|
It is representable as a number, and is @code{1} if the sub key can be
|
|
used for certifications, and @code{0} otherwise.
|
|
|
|
@item GPGME_ATTR_SERIAL
|
|
The X.509 issuer serial attribute of the key. It is representable as
|
|
a string.
|
|
|
|
@item GPGME_ATTR_ISSUE
|
|
The X.509 issuer name attribute of the key. It is representable as a
|
|
string.
|
|
|
|
@item GPGME_ATTR_CHAINID
|
|
The X.509 chain ID can be used to build the certification chain. It
|
|
is representable as a string.
|
|
@end table
|
|
@end deftp
|
|
|
|
@deftypefun {const char *} gpgme_key_get_string_attr (@w{gpgme_key_t @var{key}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
|
|
The function @code{gpgme_key_get_string_attr} returns the value of the
|
|
string-representable attribute @var{what} of key @var{key}. If the
|
|
attribute is an attribute of a sub key or an user ID, @var{idx}
|
|
specifies the sub key or user ID of which the attribute value is
|
|
returned. The argument @var{reserved} is reserved for later use and
|
|
should be @code{NULL}.
|
|
|
|
The string returned is only valid as long as the key is valid.
|
|
|
|
The function returns @code{0} if an attribute can't be returned as a
|
|
string, @var{key} is not a valid pointer, @var{idx} out of range,
|
|
or @var{reserved} not @code{NULL}.
|
|
@end deftypefun
|
|
|
|
@deftypefun {unsigned long} gpgme_key_get_ulong_attr (@w{gpgme_key_t @var{key}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
|
|
The function @code{gpgme_key_get_ulong_attr} returns the value of the
|
|
number-representable attribute @var{what} of key @var{key}. If the
|
|
attribute is an attribute of a sub key or an user ID, @var{idx}
|
|
specifies the sub key or user ID of which the attribute value is
|
|
returned. The argument @var{reserved} is reserved for later use and
|
|
should be @code{NULL}.
|
|
|
|
The function returns @code{0} if the attribute can't be returned as a
|
|
number, @var{key} is not a valid pointer, @var{idx} out of range, or
|
|
@var{reserved} not @code{NULL}.
|
|
@end deftypefun
|
|
|
|
|
|
@node Key Signatures
|
|
@subsection Key Signatures
|
|
@cindex key, signatures
|
|
@cindex signatures, on a key
|
|
|
|
The following interfaces are deprecated and only provided for backward
|
|
compatibility. Don't use them. They will be removed in a future
|
|
version of @acronym{GPGME}.
|
|
|
|
The signatures on a key are only available if the key was retrieved
|
|
via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode
|
|
enabled, because it is expensive to retrieve all signatures of a key.
|
|
|
|
So, before using the below interfaces to retrieve the signatures on a
|
|
key, you have to make sure that the key was listed with signatures
|
|
enabled. One convenient, but blocking, way to do this is to use the
|
|
function @code{gpgme_get_key}.
|
|
|
|
@deftp {Data type} gpgme_attr_t
|
|
The @code{gpgme_attr_t} type is used to specify a key signature
|
|
attribute. The following attributes are defined:
|
|
|
|
@table @code
|
|
@item GPGME_ATTR_KEYID
|
|
This is the key ID of the key which was used for the signature. It is
|
|
representable as a string.
|
|
|
|
@item GPGME_ATTR_ALGO
|
|
This is the crypto algorithm used to create the signature. It is
|
|
representable as a string and as a number. The numbers correspond to
|
|
the @code{enum gcry_pk_algos} values in the gcrypt library.
|
|
|
|
@item GPGME_ATTR_CREATED
|
|
This is the timestamp at creation time of the signature. It is
|
|
representable as a number.
|
|
|
|
@item GPGME_ATTR_EXPIRE
|
|
This is the expiration time of the signature. It is representable as
|
|
a number.
|
|
|
|
@item GPGME_ATTR_USERID
|
|
This is the user ID associated with the signing key. The user ID is
|
|
representable as a number.
|
|
|
|
@item GPGME_ATTR_NAME
|
|
This is the name belonging to a user ID. It is representable as a string.
|
|
|
|
@item GPGME_ATTR_EMAIL
|
|
This is the email address belonging to a user ID. It is representable
|
|
as a string.
|
|
|
|
@item GPGME_ATTR_COMMENT
|
|
This is the comment belonging to a user ID. It is representable as a
|
|
string.
|
|
|
|
@item GPGME_ATTR_KEY_REVOKED
|
|
This specifies if a key signature is a revocation signature. It is
|
|
representable as a number, and is @code{1} if the key is revoked, and
|
|
@code{0} otherwise.
|
|
|
|
@c @item GPGME_ATTR_KEY_EXPIRED
|
|
@c This specifies if a key signature is expired. It is representable as
|
|
@c a number, and is @code{1} if the key is revoked, and @code{0}
|
|
@c otherwise.
|
|
@c
|
|
@item GPGME_ATTR_SIG_CLASS
|
|
This specifies the signature class of a key signature. It is
|
|
representable as a number. The meaning is specific to the crypto
|
|
engine.
|
|
|
|
@item GPGME_ATTR_SIG_CLASS
|
|
This specifies the signature class of a key signature. It is
|
|
representable as a number. The meaning is specific to the crypto
|
|
engine.
|
|
|
|
@item GPGME_ATTR_SIG_STATUS
|
|
This is the same value as returned by @code{gpgme_get_sig_status}.
|
|
@end table
|
|
@end deftp
|
|
|
|
@deftypefun {const char *} gpgme_key_sig_get_string_attr (@w{gpgme_key_t @var{key}}, @w{int @var{uid_idx}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
|
|
The function @code{gpgme_key_sig_get_string_attr} returns the value of
|
|
the string-representable attribute @var{what} of the signature
|
|
@var{idx} on the user ID @var{uid_idx} in the key @var{key}. The
|
|
argument @var{reserved} is reserved for later use and should be
|
|
@code{NULL}.
|
|
|
|
The string returned is only valid as long as the key is valid.
|
|
|
|
The function returns @code{0} if an attribute can't be returned as a
|
|
string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx}
|
|
out of range, or @var{reserved} not @code{NULL}.
|
|
@end deftypefun
|
|
|
|
@deftypefun {unsigned long} gpgme_key_sig_get_ulong_attr (@w{gpgme_key_t @var{key}}, @w{int @var{uid_idx}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
|
|
The function @code{gpgme_key_sig_get_ulong_attr} returns the value of
|
|
the number-representable attribute @var{what} of the signature
|
|
@var{idx} on the user ID @var{uid_idx} in the key @var{key}. The
|
|
argument @var{reserved} is reserved for later use and should be
|
|
@code{NULL}.
|
|
|
|
The function returns @code{0} if an attribute can't be returned as a
|
|
string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx}
|
|
out of range, or @var{reserved} not @code{NULL}.
|
|
@end deftypefun
|
|
|
|
|
|
@node Manipulating Keys
|
|
@subsection Manipulating Keys
|
|
@cindex key, manipulation
|
|
|
|
@deftypefun void gpgme_key_ref (@w{gpgme_key_t @var{key}})
|
|
The function @code{gpgme_key_ref} acquires an additional reference for
|
|
the key @var{key}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void gpgme_key_unref (@w{gpgme_key_t @var{key}})
|
|
The function @code{gpgme_key_unref} releases a reference for the key
|
|
@var{key}. If this was the last reference, the key will be destroyed
|
|
and all resources associated to it will be released.
|
|
@end deftypefun
|
|
|
|
|
|
The following interface is deprecated and only provided for backward
|
|
compatibility. Don't use it. It will be removed in a future version
|
|
of @acronym{GPGME}.
|
|
|
|
@deftypefun void gpgme_key_release (@w{gpgme_key_t @var{key}})
|
|
The function @code{gpgme_key_release} is equivalent to
|
|
@code{gpgme_key_unref}.
|
|
@end deftypefun
|
|
|
|
|
|
@node Generating Keys
|
|
@subsection Generating Keys
|
|
@cindex key, creation
|
|
@cindex key ring, add
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_genkey (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{parms}}, @w{gpgme_data_t @var{public}}, @w{gpgme_data_t @var{secret}})
|
|
The function @code{gpgme_op_genkey} generates a new key pair in the
|
|
context @var{ctx}. The meaning of @var{public} and @var{secret}
|
|
depends on the crypto backend.
|
|
|
|
GnuPG does not support @var{public} and @var{secret}, they should be
|
|
@code{NULL}. GnuPG will generate a key pair and add it to the
|
|
standard key ring. The fingerprint of the generated key is available
|
|
with @code{gpgme_op_genkey_result}.
|
|
|
|
GpgSM requires @var{public} to be a writable data object. GpgSM will
|
|
generate a secret key (which will be stored by @command{gpg-agent},
|
|
and return a certificate request in @var{public}, which then needs to
|
|
be signed by the certification authority and imported before it can be
|
|
used. GpgSM does not make the fingerprint available.
|
|
|
|
The argument @var{parms} specifies parameters for the key in an XML
|
|
string. The details about the format of @var{parms} are specific to
|
|
the crypto engine used by @var{ctx}. Here is an example for GnuPG as
|
|
the crypto engine:
|
|
|
|
@example
|
|
<GnupgKeyParms format="internal">
|
|
Key-Type: DSA
|
|
Key-Length: 1024
|
|
Subkey-Type: ELG-E
|
|
Subkey-Length: 1024
|
|
Name-Real: Joe Tester
|
|
Name-Comment: with stupid passphrase
|
|
Name-Email: joe@@foo.bar
|
|
Expire-Date: 0
|
|
Passphrase: abc
|
|
</GnupgKeyParms>
|
|
@end example
|
|
|
|
Here is an example for GpgSM as the crypto engine:
|
|
|
|
@example
|
|
<GnupgKeyParms format="internal">
|
|
Key-Type: RSA
|
|
Key-Length: 1024
|
|
Name-DN: C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester
|
|
Name-Email: joe@@foo.bar
|
|
</GnupgKeyParms>
|
|
@end example
|
|
|
|
Strings should be given in UTF-8 encoding. The only format supported
|
|
for now is ``internal''. The content of the @code{GnupgKeyParms}
|
|
container is passed verbatim to the crypto backend. Control
|
|
statements are not allowed.
|
|
|
|
After the operation completed successfully, the result can be
|
|
retrieved with @code{gpgme_op_genkey_result}.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
|
|
@var{parms} is not a valid XML string, @code{GPG_ERR_NOT_SUPPORTED} if
|
|
@var{public} or @var{secret} is not valid, and @code{GPG_ERR_GENERAL}
|
|
if no key was created by the backend.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_genkey_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{parms}}, @w{gpgme_data_t @var{public}}, @w{gpgme_data_t @var{secret}})
|
|
The function @code{gpgme_op_genkey_start} initiates a
|
|
@code{gpgme_op_genkey} operation. It can be completed by calling
|
|
@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
|
|
@var{parms} is not a valid XML string, and
|
|
@code{GPG_ERR_NOT_SUPPORTED} if @var{public} or @var{secret} is not
|
|
@code{NULL}.
|
|
@end deftypefun
|
|
|
|
@deftp {Data type} {gpgme_genkey_result_t}
|
|
This is a pointer to a structure used to store the result of a
|
|
@code{gpgme_op_genkey} operation. After successfully generating a
|
|
key, you can retrieve the pointer to the result with
|
|
@code{gpgme_op_genkey_result}. The structure contains the following
|
|
members:
|
|
|
|
@table @code
|
|
@item unsigned int primary : 1
|
|
This is a flag that is set to 1 if a primary key was created and to 0
|
|
if not.
|
|
|
|
@item unsigned int sub : 1
|
|
This is a flag that is set to 1 if a subkey was created and to 0
|
|
if not.
|
|
|
|
@item char *fpr
|
|
This is the fingerprint of the key that was created. If both a
|
|
primary and a sub key were generated, the fingerprint of the primary
|
|
key will be returned. If the crypto engine does not provide the
|
|
fingerprint, @code{fpr} will be a null pointer.
|
|
@end table
|
|
@end deftp
|
|
|
|
@deftypefun gpgme_genkey_result_t gpgme_op_genkey_result (@w{gpgme_ctx_t @var{ctx}})
|
|
The function @code{gpgme_op_genkey_result} returns a
|
|
@code{gpgme_genkey_result_t} pointer to a structure holding the result of
|
|
a @code{gpgme_op_genkey} operation. The pointer is only valid if the
|
|
last operation on the context was a @code{gpgme_op_genkey} or
|
|
@code{gpgme_op_genkey_start} operation, and if this operation finished
|
|
successfully. The returned pointer is only valid until the next
|
|
operation is started on the context.
|
|
@end deftypefun
|
|
|
|
|
|
@node Exporting Keys
|
|
@subsection Exporting Keys
|
|
@cindex key, export
|
|
@cindex key ring, export from
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_export (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{unsigned int @var{reserved}}, @w{gpgme_data_t @var{keydata}})
|
|
The function @code{gpgme_op_export} extracts public keys and returns
|
|
them in the data buffer @var{keydata}. The output format of the key
|
|
data returned is determined by the @acronym{ASCII} armor attribute set
|
|
for the context @var{ctx}.
|
|
|
|
If @var{pattern} is @code{NULL}, all available keys are returned.
|
|
Otherwise, @var{pattern} contains an engine specific expression that
|
|
is used to limit the list to all keys matching the pattern.
|
|
|
|
@var{reserved} is reserved for future use and must be @code{0}.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
operation completed successfully, @code{GPG_ERR_INV_VALUE} if
|
|
@var{keydata} is not a valid empty data buffer, and passes through any
|
|
errors that are reported by the crypto engine support routines.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_export_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{unsigned int @var{reserved}}, @w{gpgme_data_t @var{keydata}})
|
|
The function @code{gpgme_op_export_start} initiates a
|
|
@code{gpgme_op_export} operation. It can be completed by calling
|
|
@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
|
|
if @var{keydata} is not a valid empty data buffer.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_export_ext (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}[]}, @w{unsigned int @var{reserved}}, @w{gpgme_data_t @var{keydata}})
|
|
The function @code{gpgme_op_export} extracts public keys and returns
|
|
them in the data buffer @var{keydata}. The output format of the key
|
|
data returned is determined by the @acronym{ASCII} armor attribute set
|
|
for the context @var{ctx}.
|
|
|
|
If @var{pattern} or @var{*pattern} is @code{NULL}, all available keys
|
|
are returned. Otherwise, @var{pattern} is a @code{NULL} terminated
|
|
array of strings that are used to limit the list to all keys matching
|
|
at least one of the patterns verbatim.
|
|
|
|
@var{reserved} is reserved for future use and must be @code{0}.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
operation completed successfully, @code{GPG_ERR_INV_VALUE} if
|
|
@var{keydata} is not a valid empty data buffer, and passes through any
|
|
errors that are reported by the crypto engine support routines.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_export_ext_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}[]}, @w{unsigned int @var{reserved}}, @w{gpgme_data_t @var{keydata}})
|
|
The function @code{gpgme_op_export_ext_start} initiates a
|
|
@code{gpgme_op_export_ext} operation. It can be completed by calling
|
|
@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
|
|
if @var{keydata} is not a valid empty data buffer.
|
|
@end deftypefun
|
|
|
|
|
|
@node Importing Keys
|
|
@subsection Importing Keys
|
|
@cindex key, import
|
|
@cindex key ring, import to
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_import (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}})
|
|
The function @code{gpgme_op_import} adds the keys in the data buffer
|
|
@var{keydata} to the key ring of the crypto engine used by @var{ctx}.
|
|
The format of @var{keydata} can be @acronym{ASCII} armored, for example,
|
|
but the details are specific to the crypto engine.
|
|
|
|
After the operation completed successfully, the result can be
|
|
retrieved with @code{gpgme_op_import_result}.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
import was completed successfully, @code{GPG_ERR_INV_VALUE} if
|
|
@var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer,
|
|
and @code{GPG_ERR_NO_DATA} if @var{keydata} is an empty data buffer.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_import_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}})
|
|
The function @code{gpgme_op_import_start} initiates a
|
|
@code{gpgme_op_import} operation. It can be completed by calling
|
|
@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
import could be started successfully, @code{GPG_ERR_INV_VALUE} if
|
|
@var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer,
|
|
and @code{GPG_ERR_NO_DATA} if @var{keydata} is an empty data buffer.
|
|
@end deftypefun
|
|
|
|
@deftp {Data type} {gpgme_import_status_t}
|
|
This is a pointer to a structure used to store a part of the result of
|
|
a @code{gpgme_op_import} operation. For each considered key one
|
|
status is added that contains information about the result of the
|
|
import. The structure contains the following members:
|
|
|
|
@table @code
|
|
@item gpgme_import_status_t next
|
|
This is a pointer to the next status structure in the linked list, or
|
|
@code{NULL} if this is the last element.
|
|
|
|
@item char *fpr
|
|
This is the fingerprint of the key that was considered.
|
|
|
|
@item gpgme_error_t result
|
|
If the import was not successful, this is the error value that caused
|
|
the import to fail. Otherwise the error code is
|
|
@code{GPG_ERR_NO_ERROR}.
|
|
|
|
@item unsigned int status
|
|
This is a bit-wise OR of the following flags that give more
|
|
information about what part of the key was imported. If the key was
|
|
already known, this might be 0.
|
|
|
|
@table @code
|
|
@item GPGME_IMPORT_NEW
|
|
The key was new.
|
|
|
|
@item GPGME_IMPORT_UID
|
|
The key contained new user IDs.
|
|
|
|
@item GPGME_IMPORT_SIG
|
|
The key contained new signatures.
|
|
|
|
@item GPGME_IMPORT_SUBKEY
|
|
The key contained new sub keys.
|
|
|
|
@item GPGME_IMPORT_SECRET
|
|
The key contained a secret key.
|
|
@end table
|
|
@end table
|
|
@end deftp
|
|
|
|
@deftp {Data type} {gpgme_import_result_t}
|
|
This is a pointer to a structure used to store the result of a
|
|
@code{gpgme_op_import} operation. After a successful import
|
|
operation, you can retrieve the pointer to the result with
|
|
@code{gpgme_op_import_result}. The structure contains the following
|
|
members:
|
|
|
|
@table @code
|
|
@item int considered
|
|
The total number of considered keys.
|
|
|
|
@item int no_user_id
|
|
The number of keys without user ID.
|
|
|
|
@item int imported
|
|
The total number of imported keys.
|
|
|
|
@item imported_rsa
|
|
The number of imported RSA keys.
|
|
|
|
@item unchanged
|
|
The number of unchanged keys.
|
|
|
|
@item new_user_ids
|
|
The number of new user IDs.
|
|
|
|
@item new_sub_keys
|
|
The number of new sub keys.
|
|
|
|
@item new_signatures
|
|
The number of new signatures.
|
|
|
|
@item new_revocations
|
|
The number of new revocations.
|
|
|
|
@item secret_read
|
|
The total number of secret keys read.
|
|
|
|
@item secret_imported
|
|
The number of imported secret keys.
|
|
|
|
@item secret_unchanged
|
|
The number of unchanged secret keys.
|
|
|
|
@item not_imported
|
|
The number of keys not imported.
|
|
|
|
@item gpgme_import_status_t imports
|
|
A list of gpgme_import_status_t objects which contain more information
|
|
about the keys for which an import was attempted.
|
|
@end table
|
|
@end deftp
|
|
|
|
@deftypefun gpgme_import_result_t gpgme_op_import_result (@w{gpgme_ctx_t @var{ctx}})
|
|
The function @code{gpgme_op_import_result} returns a
|
|
@code{gpgme_import_result_t} pointer to a structure holding the result
|
|
of a @code{gpgme_op_import} operation. The pointer is only valid if
|
|
the last operation on the context was a @code{gpgme_op_import} or
|
|
@code{gpgme_op_import_start} operation, and if this operation finished
|
|
successfully. The returned pointer is only valid until the next
|
|
operation is started on the context.
|
|
@end deftypefun
|
|
|
|
The following interface is deprecated and only provided for backward
|
|
compatibility. Don't use it. It will be removed in a future version
|
|
of @acronym{GPGME}.
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_import_ext (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}}, @w{int *@var{nr}})
|
|
The function @code{gpgme_op_import_ext} is equivalent to:
|
|
|
|
@example
|
|
gpgme_error_t err = gpgme_op_import (ctx, keydata);
|
|
if (!err)
|
|
@{
|
|
gpgme_import_result_t result = gpgme_op_import_result (ctx);
|
|
*nr = result->considered;
|
|
@}
|
|
@end example
|
|
@end deftypefun
|
|
|
|
|
|
@node Deleting Keys
|
|
@subsection Deleting Keys
|
|
@cindex key, delete
|
|
@cindex key ring, delete from
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_delete (@w{gpgme_ctx_t @var{ctx}}, @w{const gpgme_key_t @var{key}}, @w{int @var{allow_secret}})
|
|
The function @code{gpgme_op_delete} deletes the key @var{key} from the
|
|
key ring of the crypto engine used by @var{ctx}. If
|
|
@var{allow_secret} is @code{0}, only public keys are deleted,
|
|
otherwise secret keys are deleted as well, if that is supported.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the key
|
|
was deleted successfully, @code{GPG_ERR_INV_VALUE} if @var{ctx} or
|
|
@var{key} is not a valid pointer, @code{GPG_ERR_NO_PUBKEY} if
|
|
@var{key} could not be found in the keyring,
|
|
@code{GPG_ERR_AMBIGUOUS_NAME} if the key was not specified
|
|
unambiguously, and @code{GPG_ERR_CONFLICT} if the secret key for
|
|
@var{key} is available, but @var{allow_secret} is zero.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_delete_start (@w{gpgme_ctx_t @var{ctx}}, @w{const gpgme_key_t @var{key}}, @w{int @var{allow_secret}})
|
|
The function @code{gpgme_op_delete_start} initiates a
|
|
@code{gpgme_op_delete} operation. It can be completed by calling
|
|
@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
|
|
@var{ctx} or @var{key} is not a valid pointer.
|
|
@end deftypefun
|
|
|
|
|
|
@node Advanced Key Editing
|
|
@subsection Advanced Key Editing
|
|
@cindex key, edit
|
|
|
|
@deftp {Data type} {gpgme_error_t (*gpgme_edit_cb_t) (@w{void *@var{handle}}, @w{gpgme_status_code_t @var{status}}, @w{const char *@var{args}}, @w{int @var{fd}})}
|
|
@tindex gpgme_edit_cb_t
|
|
The @code{gpgme_edit_cb_t} type is the type of functions which
|
|
@acronym{GPGME} calls if it a key edit operation is on-going. The
|
|
status code @var{status} and the argument line @var{args} are passed
|
|
through by @acronym{GPGME} from the crypto engine. The file
|
|
descriptor @var{fd} is -1 for normal status messages. If @var{status}
|
|
indicates a command rather than a status message, the response to the
|
|
command should be written to @var{fd}. The @var{handle} is provided
|
|
by the user at start of operation.
|
|
|
|
The function should return @code{GPG_ERR_NO_ERROR} or an error value.
|
|
@end deftp
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
|
|
The function @code{gpgme_op_edit} processes the key @var{KEY}
|
|
interactively, using the edit callback function @var{FNC} with the
|
|
handle @var{HANDLE}. The callback is invoked for every status and
|
|
command request from the crypto engine. The output of the crypto
|
|
engine is written to the data object @var{out}.
|
|
|
|
Note that the protocol between the callback function and the crypto
|
|
engine is specific to the crypto engine and no further support in
|
|
implementing this protocol correctly is provided by @acronym{GPGME}.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
edit operation completes successfully, @code{GPG_ERR_INV_VALUE} if
|
|
@var{ctx} or @var{key} is not a valid pointer, and any error returned
|
|
by the crypto engine or the edit callback handler.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
|
|
The function @code{gpgme_op_edit_start} initiates a
|
|
@code{gpgme_op_edit} operation. It can be completed by calling
|
|
@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
|
|
@var{ctx} or @var{key} is not a valid pointer.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_card_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
|
|
The function @code{gpgme_op_card_edit} is analogous to
|
|
@code{gpgme_op_edit}, but should be used to process the smart card corresponding to the key @var{key}.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_card_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
|
|
The function @code{gpgme_op_card_edit_start} initiates a
|
|
@code{gpgme_op_card_edit} operation. It can be completed by calling
|
|
@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
|
|
@var{ctx} or @var{key} is not a valid pointer.
|
|
@end deftypefun
|
|
|
|
|
|
@node Trust Item Management
|
|
@section Trust Item Management
|
|
@cindex trust item
|
|
|
|
@strong{Caution:} The trust items interface is experimental.
|
|
|
|
@deftp {Data type} gpgme_trust_item_t
|
|
The @code{gpgme_trust_item_t} type is a pointer to a trust item object.
|
|
It has the following members:
|
|
|
|
@table @code
|
|
@item char *keyid
|
|
This is a string describing the key to which this trust items belongs.
|
|
|
|
@item int type
|
|
This is the type of the trust item. A value of 1 refers to a key, a
|
|
value of 2 refers to a user ID.
|
|
|
|
@item int level
|
|
This is the trust level.
|
|
|
|
@item char *owner_trust
|
|
The owner trust if @code{type} is 1.
|
|
|
|
@item char *validity
|
|
The calculated validity.
|
|
|
|
@item char *name
|
|
The user name if @code{type} is 2.
|
|
@end table
|
|
@end deftp
|
|
|
|
@menu
|
|
* Listing Trust Items:: Browsing the list of available trust items.
|
|
* Information About Trust Items:: Requesting information about trust items.
|
|
* Manipulating Trust Items:: Operations on trust items.
|
|
@end menu
|
|
|
|
|
|
@node Listing Trust Items
|
|
@subsection Listing Trust Items
|
|
@cindex trust item list
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_trustlist_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{max_level}})
|
|
The function @code{gpgme_op_trustlist_start} initiates a trust item
|
|
listing operation inside the context @var{ctx}. It sets everything up
|
|
so that subsequent invocations of @code{gpgme_op_trustlist_next} return
|
|
the trust items in the list.
|
|
|
|
The string @var{pattern} contains an engine specific expression that
|
|
is used to limit the list to all trust items matching the pattern. It
|
|
can not be the empty string.
|
|
|
|
The argument @var{max_level} is currently ignored.
|
|
|
|
The context will be busy until either all trust items are received
|
|
(and @code{gpgme_op_trustlist_next} returns @code{GPG_ERR_EOF}), or
|
|
@code{gpgme_op_trustlist_end} is called to finish the operation.
|
|
|
|
The function returns the error code @code{GPG_ERR_INV_VALUE} if
|
|
@var{ctx} is not a valid pointer, and passes through any errors that
|
|
are reported by the crypto engine support routines.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_trustlist_next (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_trust_item_t *@var{r_item}})
|
|
The function @code{gpgme_op_trustlist_next} returns the next trust
|
|
item in the list created by a previous @code{gpgme_op_trustlist_start}
|
|
operation in the context @var{ctx}. The trust item can be destroyed
|
|
with @code{gpgme_trust_item_release}. @xref{Manipulating Trust Items}.
|
|
|
|
This is the only way to get at @code{gpgme_trust_item_t} objects in
|
|
@acronym{GPGME}.
|
|
|
|
If the last trust item in the list has already been returned,
|
|
@code{gpgme_op_trustlist_next} returns @code{GPG_ERR_EOF}.
|
|
|
|
The function returns the error code @code{GPG_ERR_INV_VALUE} if @var{ctx} or
|
|
@var{r_item} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if
|
|
there is not enough memory for the operation.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_trustlist_end (@w{gpgme_ctx_t @var{ctx}})
|
|
The function @code{gpgme_op_trustlist_next} ends a pending key list
|
|
operation in the context @var{ctx}.
|
|
|
|
The function returns the error code @code{GPG_ERR_INV_VALUE} if
|
|
@var{ctx} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if at some
|
|
time during the operation there was not enough memory available.
|
|
@end deftypefun
|
|
|
|
|
|
@node Information About Trust Items
|
|
@subsection Information About Trust Items
|
|
@cindex trust item, information about
|
|
@cindex trust item, attributes
|
|
@cindex attributes, of a trust item
|
|
|
|
The following interfaces are deprecated and only provided for backward
|
|
compatibility. Don't use them. They will be removed in a future
|
|
version of @acronym{GPGME}.
|
|
|
|
Trust items have attributes which can be queried using the interfaces
|
|
below. The attribute identifiers are shared with those for key
|
|
attributes. @xref{Information About Keys}.
|
|
|
|
@deftypefun {const char *} gpgme_trust_item_get_string_attr (@w{gpgme_trust_item_t @var{item}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
|
|
The function @code{gpgme_trust_item_get_string_attr} returns the value
|
|
of the string-representable attribute @var{what} of trust item
|
|
@var{item}. The arguments @var{idx} and @var{reserved} are reserved
|
|
for later use and should be @code{0} and @code{NULL} respectively.
|
|
|
|
The string returned is only valid as long as the key is valid.
|
|
|
|
The function returns @code{0} if an attribute can't be returned as a
|
|
string, @var{key} is not a valid pointer, @var{idx} out of range,
|
|
or @var{reserved} not @code{NULL}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int gpgme_trust_item_get_int_attr (@w{gpgme_trust_item_t @var{item}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
|
|
The function @code{gpgme_trust_item_get_int_attr} returns the value of
|
|
the number-representable attribute @var{what} of trust item
|
|
@var{item}. If the attribute occurs more than once in the trust item,
|
|
the index is specified by @var{idx}. However, currently no such
|
|
attribute exists, so @var{idx} should be @code{0}. The argument
|
|
@var{reserved} is reserved for later use and should be @code{NULL}.
|
|
|
|
The function returns @code{0} if the attribute can't be returned as a
|
|
number, @var{key} is not a valid pointer, @var{idx} out of range,
|
|
or @var{reserved} not @code{NULL}.
|
|
@end deftypefun
|
|
|
|
|
|
@node Manipulating Trust Items
|
|
@subsection Manipulating Trust Items
|
|
@cindex trust item, manipulation
|
|
|
|
@deftypefun void gpgme_trust_item_ref (@w{gpgme_trust_item_t @var{item}})
|
|
The function @code{gpgme_trust_item_ref} acquires an additional
|
|
reference for the trust item @var{item}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void gpgme_trust_item_unref (@w{gpgme_trust_item_t @var{item}})
|
|
The function @code{gpgme_trust_item_unref} releases a reference for
|
|
the trust item @var{item}. If this was the last reference, the trust
|
|
item will be destroyed and all resources associated to it will be
|
|
released.
|
|
@end deftypefun
|
|
|
|
|
|
The following interface is deprecated and only provided for backward
|
|
compatibility. Don't use it. It will be removed in a future version
|
|
of @acronym{GPGME}.
|
|
|
|
@deftypefun void gpgme_trust_item_release (@w{gpgme_trust_item_t @var{item}})
|
|
The function @code{gpgme_trust_item_release} is an alias for
|
|
@code{gpgme_trust_item_unref}.
|
|
@end deftypefun
|
|
|
|
|
|
@node Crypto Operations
|
|
@section Crypto Operations
|
|
@cindex cryptographic operation
|
|
|
|
Sometimes, the result of a crypto operation returns a list of invalid
|
|
keys encountered in processing the request. The following structure
|
|
is used to hold information about such a key.
|
|
|
|
@deftp {Data type} {gpgme_invalid_key_t}
|
|
This is a pointer to a structure used to store a part of the result of
|
|
a crypto operation which takes user IDs as one input parameter. The
|
|
structure contains the following members:
|
|
|
|
@table @code
|
|
@item gpgme_invalid_key_t next
|
|
This is a pointer to the next invalid key structure in the linked
|
|
list, or @code{NULL} if this is the last element.
|
|
|
|
@item char *fpr
|
|
The fingerprint or key ID of the invalid key encountered.
|
|
|
|
@item gpgme_error_t reason
|
|
An error code describing the reason why the key was found invalid.
|
|
@end table
|
|
@end deftp
|
|
|
|
|
|
@menu
|
|
* Decrypt:: Decrypting a ciphertext.
|
|
* Verify:: Verifying a signature.
|
|
* Decrypt and Verify:: Decrypting a signed ciphertext.
|
|
* Sign:: Creating a signature.
|
|
* Encrypt:: Encrypting a plaintext.
|
|
@end menu
|
|
|
|
|
|
@node Decrypt
|
|
@subsection Decrypt
|
|
@cindex decryption
|
|
@cindex cryptographic operation, decryption
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_decrypt (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
|
|
The function @code{gpgme_op_decrypt} decrypts the ciphertext in the
|
|
data object @var{cipher} and stores it into the data object
|
|
@var{plain}.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
ciphertext could be decrypted successfully, @code{GPG_ERR_INV_VALUE}
|
|
if @var{ctx}, @var{cipher} or @var{plain} is not a valid pointer,
|
|
@code{GPG_ERR_NO_DATA} if @var{cipher} does not contain any data to
|
|
decrypt, @code{GPG_ERR_DECRYPT_FAILED} if @var{cipher} is not a valid
|
|
cipher text, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the
|
|
secret key could not be retrieved, and passes through any errors that
|
|
are reported by the crypto engine support routines.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_decrypt_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
|
|
The function @code{gpgme_op_decrypt_start} initiates a
|
|
@code{gpgme_op_decrypt} operation. It can be completed by calling
|
|
@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
|
|
if @var{cipher} or @var{plain} is not a valid pointer.
|
|
@end deftypefun
|
|
|
|
@deftp {Data type} {gpgme_recipient_t}
|
|
This is a pointer to a structure used to store information about the
|
|
recipient of an encrypted text which is decrypted in a
|
|
@code{gpgme_op_decrypt} operation. This information (except for the
|
|
status field) is even available before the operation finished
|
|
successfully, for example in a passphrase callback. The structure
|
|
contains the following members:
|
|
|
|
@table @code
|
|
@item gpgme_recipient_t next
|
|
This is a pointer to the next recipient structure in the linked list,
|
|
or @code{NULL} if this is the last element.
|
|
|
|
@item gpgme_pubkey_algo_t
|
|
The public key algorithm used in the encryption.
|
|
|
|
@item unsigned int wrong_key_usage : 1
|
|
This is true if the key was not used according to its policy.
|
|
|
|
@item char *keyid
|
|
This is the key ID of the key (in hexadecimal digits) used as
|
|
recipient.
|
|
|
|
@item gpgme_error_t status
|
|
This is an error number with the error code GPG_ERR_NO_SECKEY if the
|
|
secret key for this recipient is not available, and 0 otherwise.
|
|
@end table
|
|
@end deftp
|
|
|
|
@deftp {Data type} {gpgme_decrypt_result_t}
|
|
This is a pointer to a structure used to store the result of a
|
|
@code{gpgme_op_decrypt} operation. After successfully decrypting
|
|
data, you can retrieve the pointer to the result with
|
|
@code{gpgme_op_decrypt_result}. The structure contains the following
|
|
members:
|
|
|
|
@table @code
|
|
@item char *unsupported_algorithm
|
|
If an unsupported algorithm was encountered, this string describes the
|
|
algorithm that is not supported.
|
|
|
|
@item unsigned int wrong_key_usage : 1
|
|
This is true if the key was not used according to its policy.
|
|
|
|
@item gpgme_recipient_t recipient
|
|
This is a linked list of recipients to which this message was encrypted.
|
|
|
|
@item char *file_name
|
|
This is the filename of the original plaintext message file if it is
|
|
known, otherwise this is a null pointer.
|
|
@end table
|
|
@end deftp
|
|
|
|
@deftypefun gpgme_decrypt_result_t gpgme_op_decrypt_result (@w{gpgme_ctx_t @var{ctx}})
|
|
The function @code{gpgme_op_decrypt_result} returns a
|
|
@code{gpgme_decrypt_result_t} pointer to a structure holding the
|
|
result of a @code{gpgme_op_decrypt} operation. The pointer is only
|
|
valid if the last operation on the context was a
|
|
@code{gpgme_op_decrypt} or @code{gpgme_op_decrypt_start} operation.
|
|
If the operation failed this might be a @code{NULL} pointer. The
|
|
returned pointer is only valid until the next operation is started on
|
|
the context.
|
|
@end deftypefun
|
|
|
|
|
|
@node Verify
|
|
@subsection Verify
|
|
@cindex verification
|
|
@cindex signature, verification
|
|
@cindex cryptographic operation, verification
|
|
@cindex cryptographic operation, signature check
|
|
@cindex signature notation data
|
|
@cindex notation data
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{sig}}, @w{gpgme_data_t @var{signed_text}}, @w{gpgme_data_t @var{plain}})
|
|
The function @code{gpgme_op_verify} verifies that the signature in the
|
|
data object @var{sig} is a valid signature. If @var{sig} is a
|
|
detached signature, then the signed text should be provided in
|
|
@var{signed_text} and @var{plain} should be a null pointer.
|
|
Otherwise, if @var{sig} is a normal (or cleartext) signature,
|
|
@var{signed_text} should be a null pointer and @var{plain} should be a
|
|
writable data object that will contain the plaintext after successful
|
|
verification.
|
|
|
|
The results of the individual signature verifications can be retrieved
|
|
with @code{gpgme_op_verify_result}.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
operation could be completed successfully, @code{GPG_ERR_INV_VALUE} if
|
|
@var{ctx}, @var{sig} or @var{plain} is not a valid pointer,
|
|
@code{GPG_ERR_NO_DATA} if @var{sig} does not contain any data to
|
|
verify, and passes through any errors that are reported by the crypto
|
|
engine support routines.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_verify_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{sig}}, @w{gpgme_data_t @var{signed_text}}, @w{gpgme_data_t @var{plain}})
|
|
The function @code{gpgme_op_verify_start} initiates a
|
|
@code{gpgme_op_verify} operation. It can be completed by calling
|
|
@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
|
|
@var{ctx}, @var{sig} or @var{plain} is not a valid pointer, and
|
|
@code{GPG_ERR_NO_DATA} if @var{sig} or @var{plain} does not contain
|
|
any data to verify.
|
|
@end deftypefun
|
|
|
|
@deftp {Data type} {gpgme_sig_notation_t}
|
|
This is a pointer to a structure used to store a part of the result of
|
|
a @code{gpgme_op_verify} operation. The structure contains the
|
|
following members:
|
|
|
|
@table @code
|
|
@item gpgme_sig_notation_t next
|
|
This is a pointer to the next new signature notation structure in the
|
|
linked list, or @code{NULL} if this is the last element.
|
|
|
|
@item char *name
|
|
The name of the notation field. If this is @code{NULL}, then the
|
|
member @code{value} will contain a policy URL.
|
|
|
|
@item int name_len
|
|
The length of the @code{name} field. For strings the length is
|
|
counted without the trailing binary zero.
|
|
|
|
@item char *value
|
|
The value of the notation field. If @code{name} is @code{NULL}, then
|
|
this is a policy URL.
|
|
|
|
@item int value_len
|
|
The length of the @code{value} field. For strings the length is
|
|
counted without the trailing binary zero.
|
|
|
|
@item gpgme_sig_notation_flags_t flags
|
|
The accumulated flags field. This field contains the flags associated
|
|
with the notation data in an accumulated form which can be used as an
|
|
argument to the function @code{gpgme_sig_notation_add}. The value
|
|
@code{flags} is a bitwise-or combination of one or multiple of the
|
|
following bit values:
|
|
|
|
@table @code
|
|
@item GPGME_SIG_NOTATION_HUMAN_READABLE
|
|
The @code{GPGME_SIG_NOTATION_HUMAN_READABLE} symbol specifies that the
|
|
notation data is in human readable form
|
|
|
|
@item GPGME_SIG_NOTATION_CRITICAL
|
|
The @code{GPGME_SIG_NOTATION_CRITICAL} symbol specifies that the
|
|
notation data is critical.
|
|
|
|
@end table
|
|
|
|
@item unsigned int human_readable : 1
|
|
This is true if the @code{GPGME_SIG_NOTATION_HUMAN_READABLE} flag is
|
|
set and false otherwise. This flag is only valid for notation data,
|
|
not for policy URLs.
|
|
|
|
@item unsigned int critical : 1
|
|
This is true if the @code{GPGME_SIG_NOTATION_CRITICAL} flag is set and
|
|
false otherwise. This flag is valid for notation data and policy URLs.
|
|
|
|
@end table
|
|
@end deftp
|
|
|
|
@deftp {Data type} {gpgme_signature_t}
|
|
This is a pointer to a structure used to store a part of the result of
|
|
a @code{gpgme_op_verify} operation. The structure contains the
|
|
following members:
|
|
|
|
@table @code
|
|
@item gpgme_signature_t next
|
|
This is a pointer to the next new signature structure in the linked
|
|
list, or @code{NULL} if this is the last element.
|
|
|
|
@item gpgme_sigsum_t summary
|
|
This is a bit vector giving a summary of the signature status. It
|
|
provides an easy interface to a defined semantic of the signature
|
|
status. Checking just one bit is sufficient to see whether a
|
|
signature is valid without any restrictions.
|
|
|
|
The defined bits are:
|
|
@table @code
|
|
@item GPGME_SIGSUM_VALID
|
|
The signature is fully valid.
|
|
|
|
@item GPGME_SIGSUM_GREEN
|
|
The signature is good but one might want to display some extra
|
|
information. Check the other bits.
|
|
|
|
@item GPGME_SIGSUM_RED
|
|
The signature is bad. It might be useful to check other bits and
|
|
display more information, i.e. a revoked certificate might not render a
|
|
signature invalid when the message was received prior to the cause for
|
|
the revocation.
|
|
|
|
@item GPGME_SIGSUM_KEY_REVOKED
|
|
The key or at least one certificate has been revoked.
|
|
|
|
@item GPGME_SIGSUM_KEY_EXPIRED
|
|
The key or one of the certificates has expired. It is probably a good
|
|
idea to display the date of the expiration.
|
|
|
|
@item GPGME_SIGSUM_SIG_EXPIRED
|
|
The signature has expired.
|
|
|
|
@item GPGME_SIGSUM_KEY_MISSING
|
|
Can't verify due to a missing key or certificate.
|
|
|
|
@item GPGME_SIGSUM_CRL_MISSING
|
|
The CRL (or an equivalent mechanism) is not available.
|
|
|
|
@item GPGME_SIGSUM_CRL_TOO_OLD
|
|
Available CRL is too old.
|
|
|
|
@item GPGME_SIGSUM_BAD_POLICY
|
|
A policy requirement was not met.
|
|
|
|
@item GPGME_SIGSUM_SYS_ERROR
|
|
A system error occured.
|
|
@end table
|
|
|
|
@item char *fpr
|
|
This is the fingerprint or key ID of the signature.
|
|
|
|
@item gpgme_error_t status
|
|
This is the status of the signature. In particular, the following
|
|
status codes are of interest:
|
|
|
|
@table @code
|
|
@item GPG_ERR_NO_ERROR
|
|
This status indicates that the signature is valid. For the combined
|
|
result this status means that all signatures are valid.
|
|
|
|
@item GPG_ERR_SIG_EXPIRED
|
|
This status indicates that the signature is valid but expired. For
|
|
the combined result this status means that all signatures are valid
|
|
and expired.
|
|
|
|
@item GPG_ERR_KEY_EXPIRED
|
|
This status indicates that the signature is valid but the key used to
|
|
verify the signature has expired. For the combined result this status
|
|
means that all signatures are valid and all keys are expired.
|
|
|
|
@item GPG_ERR_CERT_REVOKED
|
|
This status indicates that the signature is valid but the key used
|
|
to verify the signature has been revoked. For the combined result
|
|
this status means that all signatures are valid and all keys are
|
|
revoked.
|
|
|
|
@item GPG_ERR_BAD_SIGNATURE
|
|
This status indicates that the signature is invalid. For the combined
|
|
result this status means that all signatures are invalid.
|
|
|
|
@item GPG_ERR_NO_PUBKEY
|
|
This status indicates that the signature could not be verified due to
|
|
a missing key. For the combined result this status means that all
|
|
signatures could not be checked due to missing keys.
|
|
|
|
@item GPG_ERR_GENERAL
|
|
This status indicates that there was some other error which prevented
|
|
the signature verification.
|
|
@end table
|
|
|
|
@item gpgme_sig_notation_t notations
|
|
This is a linked list with the notation data and policy URLs.
|
|
|
|
@item unsigned long timestamp
|
|
The creation timestamp of this signature.
|
|
|
|
@item unsigned long exp_timestamp
|
|
The expiration timestamp of this signature, or 0 if the signature does
|
|
not expire.
|
|
|
|
@item unsigned int wrong_key_usage : 1
|
|
This is true if the key was not used according to its policy.
|
|
|
|
@item unsigned int pka_trust : 2
|
|
This is set to the trust information gained by means of the PKA system.
|
|
Values are:
|
|
@table @code
|
|
@item 0
|
|
No PKA information available or verification not possible.
|
|
@item 1
|
|
PKA verification failed.
|
|
@item 2
|
|
PKA verification succeeded.
|
|
@item 3
|
|
Reserved for future use.
|
|
@end table
|
|
Depending on the configuration of the engine, this metric may also be
|
|
reflected by the validity of the signature.
|
|
|
|
@item unsigned int chain_model : 1
|
|
This is true if the validity of the signature has been checked using the
|
|
chain model. In the chain model the time the signature has been created
|
|
must be within the validity period of the certificate and the time the
|
|
certificate itself has been created must be within the validity period
|
|
of the issuing certificate. In contrast the default validation model
|
|
checks the validity of signature as well at the entire certificate chain
|
|
at the current time.
|
|
|
|
|
|
@item gpgme_validity_t validity
|
|
The validity of the signature.
|
|
|
|
@item gpgme_error_t validity_reason
|
|
If a signature is not valid, this provides a reason why.
|
|
|
|
@item gpgme_pubkey_algo_t
|
|
The public key algorithm used to create this signature.
|
|
|
|
@item gpgme_hash_algo_t
|
|
The hash algorithm used to create this signature.
|
|
@end table
|
|
@end deftp
|
|
|
|
@deftp {Data type} {gpgme_verify_result_t}
|
|
This is a pointer to a structure used to store the result of a
|
|
@code{gpgme_op_verify} operation. After verifying a signature, you
|
|
can retrieve the pointer to the result with
|
|
@code{gpgme_op_verify_result}. If the operation failed this might be
|
|
a @code{NULL} pointer. The structure contains the following member:
|
|
|
|
@table @code
|
|
@item gpgme_signature_t signatures
|
|
A linked list with information about all signatures for which a
|
|
verification was attempted.
|
|
|
|
@item char *file_name
|
|
This is the filename of the original plaintext message file if it is
|
|
known, otherwise this is a null pointer.
|
|
@end table
|
|
@end deftp
|
|
|
|
@deftypefun gpgme_verify_result_t gpgme_op_verify_result (@w{gpgme_ctx_t @var{ctx}})
|
|
The function @code{gpgme_op_verify_result} returns a
|
|
@code{gpgme_verify_result_t} pointer to a structure holding the result
|
|
of a @code{gpgme_op_verify} operation. The pointer is only valid if
|
|
the last operation on the context was a @code{gpgme_op_verify},
|
|
@code{gpgme_op_verify_start}, @code{gpgme_op_decrypt_verify} or
|
|
@code{gpgme_op_decrypt_verify_start} operation, and if this operation
|
|
finished successfully (for @code{gpgme_op_decrypt_verify} and
|
|
@code{gpgme_op_decrypt_verify_start}, the error code
|
|
@code{GPG_ERR_NO_DATA} counts as successful in this context). The
|
|
returned pointer is only valid until the next operation is started on
|
|
the context.
|
|
@end deftypefun
|
|
|
|
|
|
The following interfaces are deprecated and only provided for backward
|
|
compatibility. Don't use them. They will be removed in a future
|
|
version of @acronym{GPGME}.
|
|
|
|
@deftp {Data type} {enum gpgme_sig_stat_t}
|
|
@tindex gpgme_sig_stat_t
|
|
The @code{gpgme_sig_stat_t} type holds the result of a signature check, or
|
|
the combined result of all signatures. The following results are
|
|
possible:
|
|
|
|
@table @code
|
|
@item GPGME_SIG_STAT_NONE
|
|
This status should not occur in normal operation.
|
|
|
|
@item GPGME_SIG_STAT_GOOD
|
|
This status indicates that the signature is valid. For the combined
|
|
result this status means that all signatures are valid.
|
|
|
|
@item GPGME_SIG_STAT_GOOD_EXP
|
|
This status indicates that the signature is valid but expired. For
|
|
the combined result this status means that all signatures are valid
|
|
and expired.
|
|
|
|
@item GPGME_SIG_STAT_GOOD_EXPKEY
|
|
This status indicates that the signature is valid but the key used to
|
|
verify the signature has expired. For the combined result this status
|
|
means that all signatures are valid and all keys are expired.
|
|
|
|
@item GPGME_SIG_STAT_BAD
|
|
This status indicates that the signature is invalid. For the combined
|
|
result this status means that all signatures are invalid.
|
|
|
|
@item GPGME_SIG_STAT_NOKEY
|
|
This status indicates that the signature could not be verified due to
|
|
a missing key. For the combined result this status means that all
|
|
signatures could not be checked due to missing keys.
|
|
|
|
@item GPGME_SIG_STAT_NOSIG
|
|
This status indicates that the signature data provided was not a real
|
|
signature.
|
|
|
|
@item GPGME_SIG_STAT_ERROR
|
|
This status indicates that there was some other error which prevented
|
|
the signature verification.
|
|
|
|
@item GPGME_SIG_STAT_DIFF
|
|
For the combined result this status means that at least two signatures
|
|
have a different status. You can get each key's status with
|
|
@code{gpgme_get_sig_status}.
|
|
@end table
|
|
@end deftp
|
|
|
|
@deftypefun {const char *} gpgme_get_sig_status (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_sig_stat_t *@var{r_stat}}, @w{time_t *@var{r_created}})
|
|
The function @code{gpgme_get_sig_status} is equivalent to:
|
|
|
|
@example
|
|
gpgme_verify_result_t result;
|
|
gpgme_signature_t sig;
|
|
|
|
result = gpgme_op_verify_result (ctx);
|
|
sig = result->signatures;
|
|
|
|
while (sig && idx)
|
|
@{
|
|
sig = sig->next;
|
|
idx--;
|
|
@}
|
|
if (!sig || idx)
|
|
return NULL;
|
|
|
|
if (r_stat)
|
|
@{
|
|
switch (gpg_err_code (sig->status))
|
|
@{
|
|
case GPG_ERR_NO_ERROR:
|
|
*r_stat = GPGME_SIG_STAT_GOOD;
|
|
break;
|
|
|
|
case GPG_ERR_BAD_SIGNATURE:
|
|
*r_stat = GPGME_SIG_STAT_BAD;
|
|
break;
|
|
|
|
case GPG_ERR_NO_PUBKEY:
|
|
*r_stat = GPGME_SIG_STAT_NOKEY;
|
|
break;
|
|
|
|
case GPG_ERR_NO_DATA:
|
|
*r_stat = GPGME_SIG_STAT_NOSIG;
|
|
break;
|
|
|
|
case GPG_ERR_SIG_EXPIRED:
|
|
*r_stat = GPGME_SIG_STAT_GOOD_EXP;
|
|
break;
|
|
|
|
case GPG_ERR_KEY_EXPIRED:
|
|
*r_stat = GPGME_SIG_STAT_GOOD_EXPKEY;
|
|
break;
|
|
|
|
default:
|
|
*r_stat = GPGME_SIG_STAT_ERROR;
|
|
break;
|
|
@}
|
|
@}
|
|
if (r_created)
|
|
*r_created = sig->timestamp;
|
|
return sig->fpr;
|
|
@end example
|
|
@end deftypefun
|
|
|
|
@deftypefun {const char *} gpgme_get_sig_string_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{what}}, @w{int @var{whatidx}})
|
|
The function @code{gpgme_get_sig_string_attr} is equivalent to:
|
|
|
|
@example
|
|
gpgme_verify_result_t result;
|
|
gpgme_signature_t sig;
|
|
|
|
result = gpgme_op_verify_result (ctx);
|
|
sig = result->signatures;
|
|
|
|
while (sig && idx)
|
|
@{
|
|
sig = sig->next;
|
|
idx--;
|
|
@}
|
|
if (!sig || idx)
|
|
return NULL;
|
|
|
|
switch (what)
|
|
@{
|
|
case GPGME_ATTR_FPR:
|
|
return sig->fpr;
|
|
|
|
case GPGME_ATTR_ERRTOK:
|
|
if (whatidx == 1)
|
|
return sig->wrong_key_usage ? "Wrong_Key_Usage" : "";
|
|
else
|
|
return "";
|
|
default:
|
|
break;
|
|
@}
|
|
|
|
return NULL;
|
|
@end example
|
|
@end deftypefun
|
|
|
|
@deftypefun {const char *} gpgme_get_sig_ulong_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{waht}}, @w{int @var{whatidx}})
|
|
The function @code{gpgme_get_sig_ulong_attr} is equivalent to:
|
|
|
|
@example
|
|
gpgme_verify_result_t result;
|
|
gpgme_signature_t sig;
|
|
|
|
result = gpgme_op_verify_result (ctx);
|
|
sig = result->signatures;
|
|
|
|
while (sig && idx)
|
|
@{
|
|
sig = sig->next;
|
|
idx--;
|
|
@}
|
|
if (!sig || idx)
|
|
return 0;
|
|
|
|
switch (what)
|
|
@{
|
|
case GPGME_ATTR_CREATED:
|
|
return sig->timestamp;
|
|
|
|
case GPGME_ATTR_EXPIRE:
|
|
return sig->exp_timestamp;
|
|
|
|
case GPGME_ATTR_VALIDITY:
|
|
return (unsigned long) sig->validity;
|
|
|
|
case GPGME_ATTR_SIG_STATUS:
|
|
switch (sig->status)
|
|
@{
|
|
case GPG_ERR_NO_ERROR:
|
|
return GPGME_SIG_STAT_GOOD;
|
|
|
|
case GPG_ERR_BAD_SIGNATURE:
|
|
return GPGME_SIG_STAT_BAD;
|
|
|
|
case GPG_ERR_NO_PUBKEY:
|
|
return GPGME_SIG_STAT_NOKEY;
|
|
|
|
case GPG_ERR_NO_DATA:
|
|
return GPGME_SIG_STAT_NOSIG;
|
|
|
|
case GPG_ERR_SIG_EXPIRED:
|
|
return GPGME_SIG_STAT_GOOD_EXP;
|
|
|
|
case GPG_ERR_KEY_EXPIRED:
|
|
return GPGME_SIG_STAT_GOOD_EXPKEY;
|
|
|
|
default:
|
|
return GPGME_SIG_STAT_ERROR;
|
|
@}
|
|
|
|
case GPGME_ATTR_SIG_SUMMARY:
|
|
return sig->summary;
|
|
|
|
default:
|
|
break;
|
|
@}
|
|
return 0;
|
|
@end example
|
|
@end deftypefun
|
|
|
|
@deftypefun {const char *} gpgme_get_sig_key (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_key_t *@var{r_key}})
|
|
The function @code{gpgme_get_sig_key} is equivalent to:
|
|
|
|
@example
|
|
gpgme_verify_result_t result;
|
|
gpgme_signature_t sig;
|
|
|
|
result = gpgme_op_verify_result (ctx);
|
|
sig = result->signatures;
|
|
|
|
while (sig && idx)
|
|
@{
|
|
sig = sig->next;
|
|
idx--;
|
|
@}
|
|
if (!sig || idx)
|
|
return gpg_error (GPG_ERR_EOF);
|
|
|
|
return gpgme_get_key (ctx, sig->fpr, r_key, 0);
|
|
@end example
|
|
@end deftypefun
|
|
|
|
|
|
@node Decrypt and Verify
|
|
@subsection Decrypt and Verify
|
|
@cindex decryption and verification
|
|
@cindex verification and decryption
|
|
@cindex signature check
|
|
@cindex cryptographic operation, decryption and verification
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
|
|
The function @code{gpgme_op_decrypt_verify} decrypts the ciphertext in
|
|
the data object @var{cipher} and stores it into the data object
|
|
@var{plain}. If @var{cipher} contains signatures, they will be
|
|
verified.
|
|
|
|
After the operation completed, @code{gpgme_op_decrypt_result} and
|
|
@code{gpgme_op_verify_result} can be used to retrieve more information
|
|
about the signatures.
|
|
|
|
If the error code @code{GPG_ERR_NO_DATA} is returned, @var{cipher}
|
|
does not contain any data to decrypt. However, it might still be
|
|
signed. The information about detected signatures is available with
|
|
@code{gpgme_op_verify_result} in this case.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
ciphertext could be decrypted successfully, @code{GPG_ERR_INV_VALUE}
|
|
if @var{ctx}, @var{cipher} or @var{plain} is not a valid pointer,
|
|
@code{GPG_ERR_NO_DATA} if @var{cipher} does not contain any data to
|
|
decrypt, @code{GPG_ERR_DECRYPT_FAILED} if @var{cipher} is not a valid
|
|
cipher text, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the
|
|
secret key could not be retrieved, and passes through any errors that
|
|
are reported by the crypto engine support routines.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
|
|
The function @code{gpgme_op_decrypt_verify_start} initiates a
|
|
@code{gpgme_op_decrypt_verify} operation. It can be completed by
|
|
calling @code{gpgme_wait} on the context. @xref{Waiting For
|
|
Completion}.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
|
|
@var{ctx}, @var{cipher}, @var{plain} or @var{r_stat} is not a valid
|
|
pointer, and @code{GPG_ERR_NO_DATA} if @var{cipher} does not contain
|
|
any data to decrypt.
|
|
@end deftypefun
|
|
|
|
|
|
@node Sign
|
|
@subsection Sign
|
|
@cindex signature, creation
|
|
@cindex sign
|
|
@cindex cryptographic operation, signing
|
|
|
|
A signature can contain signatures by one or more keys. The set of
|
|
keys used to create a signatures is contained in a context, and is
|
|
applied to all following signing operations in this context (until the
|
|
set is changed).
|
|
|
|
@menu
|
|
* Selecting Signers:: How to choose the keys to sign with.
|
|
* Creating a Signature:: How to create a signature.
|
|
* Signature Notation Data:: How to add notation data to a signature.
|
|
@end menu
|
|
|
|
|
|
@node Selecting Signers
|
|
@subsubsection Selecting Signers
|
|
@cindex signature, selecting signers
|
|
@cindex signers, selecting
|
|
|
|
@deftypefun void gpgme_signers_clear (@w{gpgme_ctx_t @var{ctx}})
|
|
The function @code{gpgme_signers_clear} releases a reference for each
|
|
key on the signers list and removes the list of signers from the
|
|
context @var{ctx}.
|
|
|
|
Every context starts with an empty list.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_error_t gpgme_signers_add (@w{gpgme_ctx_t @var{ctx}}, @w{const gpgme_key_t @var{key}})
|
|
The function @code{gpgme_signers_add} adds the key @var{key} to the
|
|
list of signers in the context @var{ctx}.
|
|
|
|
Calling this function acquires an additional reference for the key.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_key_t gpgme_signers_enum (@w{const gpgme_ctx_t @var{ctx}}, @w{int @var{seq}})
|
|
The function @code{gpgme_signers_enum} returns the @var{seq}th key in
|
|
the list of signers in the context @var{ctx}. An additional reference
|
|
is acquired for the user.
|
|
|
|
If @var{seq} is out of range, @code{NULL} is returned.
|
|
@end deftypefun
|
|
|
|
|
|
@node Creating a Signature
|
|
@subsubsection Creating a Signature
|
|
|
|
@deftp {Data type} {enum gpgme_sig_mode_t}
|
|
@tindex gpgme_sig_mode_t
|
|
The @code{gpgme_sig_mode_t} type is used to specify the desired type of a
|
|
signature. The following modes are available:
|
|
|
|
@table @code
|
|
@item GPGME_SIG_MODE_NORMAL
|
|
A normal signature is made, the output includes the plaintext and the
|
|
signature.
|
|
|
|
@item GPGME_SIG_MODE_DETACH
|
|
A detached signature is made.
|
|
|
|
@item GPGME_SIG_MODE_CLEAR
|
|
A clear text signature is made. The @acronym{ASCII} armor and text
|
|
mode settings of the context are ignored.
|
|
@end table
|
|
@end deftp
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_sign (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{sig}}, @w{gpgme_sig_mode_t @var{mode}})
|
|
The function @code{gpgme_op_sign} creates a signature for the text in
|
|
the data object @var{plain} and returns it in the data object
|
|
@var{sig}. The type of the signature created is determined by the
|
|
@acronym{ASCII} armor and text mode attributes set for the context
|
|
@var{ctx} and the requested signature mode @var{mode}.
|
|
|
|
After the operation completed successfully, the result can be
|
|
retrieved with @code{gpgme_op_sign_result}.
|
|
|
|
If an S/MIME signed message is created using the CMS crypto engine,
|
|
the number of certificates to include in the message can be specified
|
|
with @code{gpgme_set_include_certs}. @xref{Included Certificates}.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
signature could be created successfully, @code{GPG_ERR_INV_VALUE} if
|
|
@var{ctx}, @var{plain} or @var{sig} is not a valid pointer,
|
|
@code{GPG_ERR_NO_DATA} if the signature could not be created,
|
|
@code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the secret key
|
|
could not be retrieved, @code{GPG_ERR_UNUSABLE_SECKEY} if there are
|
|
invalid signers, and passes through any errors that are reported by the
|
|
crypto engine support routines.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_sign_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{sig}}, @w{gpgme_sig_mode_t @var{mode}})
|
|
The function @code{gpgme_op_sign_start} initiates a
|
|
@code{gpgme_op_sign} operation. It can be completed by calling
|
|
@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the operation could be
|
|
started successfully, and @code{GPG_ERR_INV_VALUE} if @var{ctx},
|
|
@var{plain} or @var{sig} is not a valid pointer.
|
|
@end deftypefun
|
|
|
|
@deftp {Data type} {gpgme_new_signature_t}
|
|
This is a pointer to a structure used to store a part of the result of
|
|
a @code{gpgme_op_sign} operation. The structure contains the
|
|
following members:
|
|
|
|
@table @code
|
|
@item gpgme_new_signature_t next
|
|
This is a pointer to the next new signature structure in the linked
|
|
list, or @code{NULL} if this is the last element.
|
|
|
|
@item gpgme_sig_mode_t type
|
|
The type of this signature.
|
|
|
|
@item gpgme_pubkey_algo_t
|
|
The public key algorithm used to create this signature.
|
|
|
|
@item gpgme_hash_algo_t
|
|
The hash algorithm used to create this signature.
|
|
|
|
@item unsigned int sig_class
|
|
The signature class of this signature.
|
|
|
|
@item long int timestamp
|
|
The creation timestamp of this signature.
|
|
|
|
@item char *fpr
|
|
The fingerprint of the key which was used to create this signature.
|
|
@end table
|
|
@end deftp
|
|
|
|
@deftp {Data type} {gpgme_sign_result_t}
|
|
This is a pointer to a structure used to store the result of a
|
|
@code{gpgme_op_sign} operation. After successfully generating a
|
|
signature, you can retrieve the pointer to the result with
|
|
@code{gpgme_op_sign_result}. The structure contains the following
|
|
members:
|
|
|
|
@table @code
|
|
@item gpgme_invalid_key_t invalid_signers
|
|
A linked list with information about all invalid keys for which a
|
|
signature could not be created.
|
|
|
|
@item gpgme_new_signature_t signatures
|
|
A linked list with information about all signatures created.
|
|
@end table
|
|
@end deftp
|
|
|
|
@deftypefun gpgme_sign_result_t gpgme_op_sign_result (@w{gpgme_ctx_t @var{ctx}})
|
|
The function @code{gpgme_op_sign_result} returns a
|
|
@code{gpgme_sign_result_t} pointer to a structure holding the result
|
|
of a @code{gpgme_op_sign} operation. The pointer is only valid if the
|
|
last operation on the context was a @code{gpgme_op_sign},
|
|
@code{gpgme_op_sign_start}, @code{gpgme_op_encrypt_sign} or
|
|
@code{gpgme_op_encrypt_sign_start} operation. If that operation
|
|
failed, the function might return a @code{NULL} pointer, The returned
|
|
pointer is only valid until the next operation is started on the
|
|
context.
|
|
@end deftypefun
|
|
|
|
|
|
@node Signature Notation Data
|
|
@subsubsection Signature Notation Data
|
|
@cindex notation data
|
|
@cindex signature notation data
|
|
@cindex policy URL
|
|
|
|
Using the following functions, you can attach arbitrary notation data
|
|
to a signature. This information is then available to the user when
|
|
the signature is verified.
|
|
|
|
@deftypefun void gpgme_sig_notation_clear (@w{gpgme_ctx_t @var{ctx}})
|
|
The function @code{gpgme_sig_notation_clear} removes the notation data
|
|
from the context @var{ctx}. Subsequent signing operations from this
|
|
context will not include any notation data.
|
|
|
|
Every context starts with an empty notation data list.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_error_t gpgme_sig_notation_add (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{name}}, @w{const char *@var{value}}, @w{gpgme_sig_notation_flags_t @var{flags}})
|
|
The function @code{gpgme_sig_notation_add} adds the notation data with
|
|
the name @var{name} and the value @var{value} to the context
|
|
@var{ctx}.
|
|
|
|
Subsequent signing operations will include this notation data, as well
|
|
as any other notation data that was added since the creation of the
|
|
context or the last @code{gpgme_sig_notation_clear} operation.
|
|
|
|
The arguments @var{name} and @var{value} must be @code{NUL}-terminated
|
|
strings in human-readable form. The flag
|
|
@code{GPGME_SIG_NOTATION_HUMAN_READABLE} is implied
|
|
(non-human-readable notation data is currently not supported). The
|
|
strings must be in UTF-8 encoding.
|
|
|
|
If @var{name} is @code{NULL}, then @var{value} should be a policy URL.
|
|
|
|
The function @code{gpgme_sig_notation_add} returns the error code
|
|
@code{GPG_ERR_NO_ERROR} if the notation data could be added
|
|
successfully, @code{GPG_ERR_INV_VALUE} if @var{ctx} is not a valid
|
|
pointer, or if @var{name}, @var{value} and @var{flags} are an invalid
|
|
combination. The function also passes through any errors that are
|
|
reported by the crypto engine support routines.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_sig_notation_t gpgme_sig_notation_get (@w{const gpgme_ctx_t @var{ctx}})
|
|
The function @code{gpgme_sig_notation_get} returns the linked list of
|
|
notation data structures that are contained in the context @var{ctx}.
|
|
|
|
If @var{ctx} is not a valid pointer, or there is no notation data
|
|
added for this context, @code{NULL} is returned.
|
|
@end deftypefun
|
|
|
|
|
|
@node Encrypt
|
|
@subsection Encrypt
|
|
@cindex encryption
|
|
@cindex cryptographic operation, encryption
|
|
|
|
One plaintext can be encrypted for several recipients at the same
|
|
time. The list of recipients is created independently of any context,
|
|
and then passed to the encryption operation.
|
|
|
|
@menu
|
|
* Encrypting a Plaintext:: How to encrypt a plaintext.
|
|
@end menu
|
|
|
|
|
|
@node Encrypting a Plaintext
|
|
@subsubsection Encrypting a Plaintext
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_encrypt (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}[]}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
|
|
The function @code{gpgme_op_encrypt} encrypts the plaintext in the data
|
|
object @var{plain} for the recipients @var{recp} and stores the
|
|
ciphertext in the data object @var{cipher}. The type of the
|
|
ciphertext created is determined by the @acronym{ASCII} armor and text
|
|
mode attributes set for the context @var{ctx}.
|
|
|
|
@var{key} must be a @code{NULL}-terminated array of keys. The user
|
|
must keep references for all keys during the whole duration of the
|
|
call (but see @code{gpgme_op_encrypt_start} for the requirements with
|
|
the asynchronous variant).
|
|
|
|
The value in @var{flags} is a bitwise-or combination of one or
|
|
multiple of the following bit values:
|
|
|
|
@table @code
|
|
@item GPGME_ENCRYPT_ALWAYS_TRUST
|
|
The @code{GPGME_ENCRYPT_ALWAYS_TRUST} symbol specifies that all the
|
|
recipients in @var{recp} should be trusted, even if the keys do not
|
|
have a high enough validity in the keyring. This flag should be used
|
|
with care; in general it is not a good idea to use any untrusted keys.
|
|
@end table
|
|
|
|
If @code{GPG_ERR_UNUSABLE_PUBKEY} is returned, some recipients in
|
|
@var{recp} are invalid, but not all. In this case the plaintext might
|
|
be encrypted for all valid recipients and returned in @var{cipher} (if
|
|
this happens depends on the crypto engine). More information about
|
|
the invalid recipients is available with
|
|
@code{gpgme_op_encrypt_result}.
|
|
|
|
If @var{recp} is @code{NULL}, symmetric rather than public key
|
|
encryption is performed. Symmetrically encrypted cipher text can be
|
|
deciphered with @code{gpgme_op_decrypt}. Note that in this case the
|
|
crypto backend needs to retrieve a passphrase from the user.
|
|
Symmetric encryption is currently only supported for the OpenPGP
|
|
crypto backend.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
ciphertext could be created successfully, @code{GPG_ERR_INV_VALUE} if
|
|
@var{ctx}, @var{recp}, @var{plain} or @var{cipher} is not a valid
|
|
pointer, @code{GPG_ERR_UNUSABLE_PUBKEY} if @var{recp} contains some
|
|
invalid recipients, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase
|
|
for the symmetric key could not be retrieved, and passes through any
|
|
errors that are reported by the crypto engine support routines.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_encrypt_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}[]}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
|
|
The function @code{gpgme_op_encrypt_start} initiates a
|
|
@code{gpgme_op_encrypt} operation. It can be completed by calling
|
|
@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
|
|
|
|
References to the keys only need to be held for the duration of this
|
|
call. The user can release its references to the keys after this
|
|
function returns, even if the operation is not yet finished.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
|
|
@var{ctx}, @var{rset}, @var{plain} or @var{cipher} is not a valid
|
|
pointer, and @code{GPG_ERR_UNUSABLE_PUBKEY} if @var{rset} does not
|
|
contain any valid recipients.
|
|
@end deftypefun
|
|
|
|
@deftp {Data type} {gpgme_encrypt_result_t}
|
|
This is a pointer to a structure used to store the result of a
|
|
@code{gpgme_op_encrypt} operation. After successfully encrypting
|
|
data, you can retrieve the pointer to the result with
|
|
@code{gpgme_op_encrypt_result}. The structure contains the following
|
|
members:
|
|
|
|
@table @code
|
|
@item gpgme_invalid_key_t invalid_recipients
|
|
A linked list with information about all invalid keys for which
|
|
the data could not be encrypted.
|
|
@end table
|
|
@end deftp
|
|
|
|
@deftypefun gpgme_encrypt_result_t gpgme_op_encrypt_result (@w{gpgme_ctx_t @var{ctx}})
|
|
The function @code{gpgme_op_encrypt_result} returns a
|
|
@code{gpgme_encrypt_result_t} pointer to a structure holding the
|
|
result of a @code{gpgme_op_encrypt} operation. The pointer is only
|
|
valid if the last operation on the context was a
|
|
@code{gpgme_op_encrypt}, @code{gpgme_op_encrypt_start},
|
|
@code{gpgme_op_sign} or @code{gpgme_op_sign_start} operation. If this
|
|
operation failed, this might be a @code{NULL} pointer. The returned
|
|
pointer is only valid until the next operation is started on the
|
|
context.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_encrypt_sign (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}[]}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
|
|
The function @code{gpgme_op_encrypt_sign} does a combined encrypt and
|
|
sign operation. It is used like @code{gpgme_op_encrypt}, but the
|
|
ciphertext also contains signatures for the signers listed in
|
|
@var{ctx}.
|
|
|
|
The combined encrypt and sign operation is currently only available
|
|
for the OpenPGP crypto engine.
|
|
@end deftypefun
|
|
|
|
@deftypefun gpgme_error_t gpgme_op_encrypt_sign_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
|
|
The function @code{gpgme_op_encrypt_sign_start} initiates a
|
|
@code{gpgme_op_encrypt_sign} operation. It can be completed by
|
|
calling @code{gpgme_wait} on the context. @xref{Waiting For
|
|
Completion}.
|
|
|
|
The function returns the error code @code{GPG_ERR_NO_ERROR} if the
|
|
operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
|
|
if @var{ctx}, @var{rset}, @var{plain} or @var{cipher} is not a valid
|
|
pointer.
|
|
@end deftypefun
|
|
|
|
|
|
@node Run Control
|
|
@section Run Control
|
|
@cindex run control
|
|
@cindex cryptographic operation, running
|
|
|
|
@acronym{GPGME} supports running operations synchronously and
|
|
asynchronously. You can use asynchronous operation to set up a
|
|
context up to initiating the desired operation, but delay performing
|
|
it to a later point.
|
|
|
|
Furthermore, you can use an external event loop to control exactly
|
|
when @acronym{GPGME} runs. This ensures that @acronym{GPGME} only
|
|
runs when necessary and also prevents it from blocking for a long
|
|
time.
|
|
|
|
@menu
|
|
* Waiting For Completion:: Waiting until an operation is completed.
|
|
* Using External Event Loops:: Advanced control over what happens when.
|
|
* Cancellation:: How to end pending operations prematurely.
|
|
@end menu
|
|
|
|
|
|
@node Waiting For Completion
|
|
@subsection Waiting For Completion
|
|
@cindex cryptographic operation, wait for
|
|
@cindex wait for completion
|
|
|
|
@deftypefun gpgme_ctx_t gpgme_wait (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_error_t *@var{status}}, @w{int @var{hang}})
|
|
The function @code{gpgme_wait} continues the pending operation within
|
|
the context @var{ctx}. In particular, it ensures the data exchange
|
|
between @acronym{GPGME} and the crypto backend and watches over the
|
|
run time status of the backend process.
|
|
|
|
If @var{hang} is true, the function does not return until the
|
|
operation is completed or cancelled. Otherwise the function will not
|
|
block for a long time.
|
|
|
|
The error status of the finished operation is returned in @var{status}
|
|
if @code{gpgme_wait} does not return @code{NULL}.
|
|
|
|
The @var{ctx} argument can be @code{NULL}. In that case,
|
|
@code{gpgme_wait} waits for any context to complete its operation.
|
|
|
|
@code{gpgme_wait} can be used only in conjunction with any context
|
|
that has a pending operation initiated with one of the
|
|
@code{gpgme_op_*_start} functions except @code{gpgme_op_keylist_start}
|
|
and @code{gpgme_op_trustlist_start} (for which you should use the
|
|
corresponding @code{gpgme_op_*_next} functions). If @var{ctx} is
|
|
@code{NULL}, all of such contexts are waited upon and possibly
|
|
returned. Synchronous operations running in parallel, as well as key
|
|
and trust item list operations, do not affect @code{gpgme_wait}.
|
|
|
|
In a multi-threaded environment, only one thread should ever call
|
|
@code{gpgme_wait} at any time, irregardless if @var{ctx} is specified
|
|
or not. This means that all calls to this function should be fully
|
|
synchronized by locking primitives. It is safe to start asynchronous
|
|
operations while a thread is running in @code{gpgme_wait}.
|
|
|
|
The function returns the @var{ctx} of the context which has finished
|
|
the operation. If @var{hang} is false, and the timeout expires,
|
|
@code{NULL} is returned and @code{*status} will be set to 0. If an
|
|
error occurs, @code{NULL} is returned and the error is returned in
|
|
@code{*status}.
|
|
@end deftypefun
|
|
|
|
|
|
@node Using External Event Loops
|
|
@subsection Using External Event Loops
|
|
@cindex event loop, external
|
|
|
|
@acronym{GPGME} hides the complexity of the communication between the
|
|
library and the crypto engine. The price of this convenience is that
|
|
the calling thread can block arbitrary long waiting for the data
|
|
returned by the crypto engine. In single-threaded programs, in
|
|
particular if they are interactive, this is an unwanted side-effect.
|
|
OTOH, if @code{gpgme_wait} is used without the @var{hang} option being
|
|
enabled, it might be called unnecessarily often, wasting CPU time that
|
|
could be used otherwise.
|
|
|
|
The I/O callback interface described in this section lets the user
|
|
take control over what happens when. @acronym{GPGME} will provide the
|
|
user with the file descriptors that should be monitored, and the
|
|
callback functions that should be invoked when a file descriptor is
|
|
ready for reading or writing. It is then the user's responsibility to
|
|
decide when to check the file descriptors and when to invoke the
|
|
callback functions. Usually this is done in an event loop, that also
|
|
checks for events in other parts of the program. If the callback
|
|
functions are only called when the file descriptors are ready,
|
|
@acronym{GPGME} will never block. This gives the user more control
|
|
over the program flow, and allows to perform other tasks when
|
|
@acronym{GPGME} would block otherwise.
|
|
|
|
By using this advanced mechanism, @acronym{GPGME} can be integrated
|
|
smoothly into GUI toolkits like GTK+ even for single-threaded
|
|
programs.
|
|
|
|
@menu
|
|
* I/O Callback Interface:: How I/O callbacks are registered.
|
|
* Registering I/O Callbacks:: How to use I/O callbacks for a context.
|
|
* I/O Callback Example:: An example how to use I/O callbacks.
|
|
* I/O Callback Example GTK+:: How to use @acronym{GPGME} with GTK+.
|
|
* I/O Callback Example GDK:: How to use @acronym{GPGME} with GDK.
|
|
* I/O Callback Example Qt:: How to use @acronym{GPGME} with Qt.
|
|
@end menu
|
|
|
|
|
|
@node I/O Callback Interface
|
|
@subsubsection I/O Callback Interface
|
|
|
|
@deftp {Data type} {gpgme_error_t (*gpgme_io_cb_t) (@w{void *@var{data}}, @w{int @var{fd}})}
|
|
@tindex gpgme_io_cb_t
|
|
The @code{gpgme_io_cb_t} type is the type of functions which
|
|
@acronym{GPGME} wants to register as I/O callback handlers using the
|
|
@code{gpgme_register_io_cb_t} functions provided by the user.
|
|
|
|
@var{data} and @var{fd} are provided by @acronym{GPGME} when the I/O
|
|
callback handler is registered, and should be passed through to the
|
|
handler when it is invoked by the user because it noticed activity on
|
|
the file descriptor @var{fd}.
|
|
|
|
The callback handler always returns @code{0}, but you should consider
|
|
the return value to be reserved for later use.
|
|
@end deftp
|
|
|
|
@deftp {Data type} {gpgme_error_t (*gpgme_register_io_cb_t) (@w{void *@var{data}}, @w{int @var{fd}}, @w{int @var{dir}}, @w{gpgme_io_cb_t @var{fnc}}, @w{void *@var{fnc_data}}, @w{void **@var{tag}})}
|
|
@tindex gpgme_register_io_cb_t
|
|
The @code{gpgme_register_io_cb_t} type is the type of functions which can
|
|
be called by @acronym{GPGME} to register an I/O callback function
|
|
@var{fnc} for the file descriptor @var{fd} with the user.
|
|
@var{fnc_data} should be passed as the first argument to @var{fnc}
|
|
when the handler is invoked (the second argument should be @var{fd}).
|
|
If @var{dir} is 0, @var{fnc} should be called by the user when
|
|
@var{fd} is ready for writing. If @var{dir} is 1, @var{fnc} should be
|
|
called when @var{fd} is ready for reading.
|
|
|
|
@var{data} was provided by the user when registering the
|
|
@code{gpgme_register_io_cb_t} function with @acronym{GPGME} and will always
|
|
be passed as the first argument when registering a callback function.
|
|
For example, the user can use this to determine the event loop to
|
|
which the file descriptor should be added.
|
|
|
|
@acronym{GPGME} will call this function when a crypto operation is
|
|
initiated in a context for which the user has registered I/O callback
|
|
handler functions with @code{gpgme_set_io_cbs}. It can also call this
|
|
function when it is in an I/O callback handler for a file descriptor
|
|
associated to this context.
|
|
|
|
The user should return a unique handle in @var{tag} identifying this
|
|
I/O callback registration, which will be passed to the
|
|
@code{gpgme_register_io_cb_t} function without interpretation when the file
|
|
descriptor should not be monitored anymore.
|
|
@end deftp
|
|
|
|
@deftp {Data type} {void (*gpgme_remove_io_cb_t) (@w{void *@var{tag}})}
|
|
The @code{gpgme_remove_io_cb_t} type is the type of functions which can be
|
|
called by @acronym{GPGME} to remove an I/O callback handler that was
|
|
registered before. @var{tag} is the handle that was returned by the
|
|
@code{gpgme_register_io_cb_t} for this I/O callback.
|
|
|
|
@acronym{GPGME} can call this function when a crypto operation is in
|
|
an I/O callback. It will also call this function when the context is
|
|
destroyed while an operation is pending.
|
|
@end deftp
|
|
|
|
@deftp {Data type} {enum gpgme_event_io_t}
|
|
@tindex gpgme_event_io_t
|
|
The @code{gpgme_event_io_t} type specifies the type of an event that is
|
|
reported to the user by @acronym{GPGME} as a consequence of an I/O
|
|
operation. The following events are defined:
|
|
|
|
@table @code
|
|
@item GPGME_EVENT_START
|
|
The operation is fully initialized now, and you can start to run the
|
|
registered I/O callback handlers now. Note that registered I/O
|
|
callback handlers must not be run before this event is signalled.
|
|
@var{type_data} is @code{NULL} and reserved for later use.
|
|
|
|
@item GPGME_EVENT_DONE
|
|
The operation is finished, the last I/O callback for this operation
|
|
was removed. The accompanying @var{type_data} points to a
|
|
@code{gpgme_error_t} variable that contains the status of the operation
|
|
that finished. This event is signalled after the last I/O callback
|
|
has been removed.
|
|
|
|
@item GPGME_EVENT_NEXT_KEY
|
|
In a @code{gpgme_op_keylist_start} operation, the next key was
|
|
received from the crypto engine. The accompanying @var{type_data} is
|
|
a @code{gpgme_key_t} variable that contains the key with one reference
|
|
for the user.
|
|
|
|
@item GPGME_EVENT_NEXT_TRUSTITEM
|
|
In a @code{gpgme_op_trustlist_start} operation, the next trust item
|
|
was received from the crypto engine. The accompanying @var{type_data}
|
|
is a @code{gpgme_trust_item_t} variable that contains the trust item with
|
|
one reference for the user.
|
|
@end table
|
|
@end deftp
|
|
|
|
@deftp {Data type} {void (*gpgme_event_io_cb_t) (@w{void *@var{data}}, @w{gpgme_event_io_t @var{type}}, @w{void *@var{type_data}})}
|
|
The @code{gpgme_event_io_cb_t} type is the type of functions which can be
|
|
called by @acronym{GPGME} to signal an event for an operation running
|
|
in a context which has I/O callback functions registered by the user.
|
|
|
|
@var{data} was provided by the user when registering the
|
|
@code{gpgme_event_io_cb_t} function with @acronym{GPGME} and will always be
|
|
passed as the first argument when registering a callback function.
|
|
For example, the user can use this to determine the context in which
|
|
this event has occured.
|
|
|
|
@var{type} will specify the type of event that has occured.
|
|
@var{type_data} specifies the event further, as described in the above
|
|
list of possible @code{gpgme_event_io_t} types.
|
|
|
|
@acronym{GPGME} can call this function in an I/O callback handler.
|
|
@end deftp
|
|
|
|
|
|
@node Registering I/O Callbacks
|
|
@subsubsection Registering I/O Callbacks
|
|
|
|
@deftp {Data type} {struct gpgme_io_cb_ts}
|
|
@tindex gpgme_event_io_t
|
|
This structure is used to store the I/O callback interface functions
|
|
described in the previous section. It has the following members:
|
|
|
|
@table @code
|
|
@item gpgme_register_io_cb_t add
|
|
This is the function called by @acronym{GPGME} to register an I/O
|
|
callback handler. It must be specified.
|
|
|
|
@item void *add_data
|
|
This is passed as the first argument to the @code{add} function when
|
|
it is called by @acronym{GPGME}. For example, it can be used to
|
|
determine the event loop to which the file descriptor should be added.
|
|
|
|
@item gpgme_remove_io_cb_t remove
|
|
This is the function called by @acronym{GPGME} to remove an I/O
|
|
callback handler. It must be specified.
|
|
|
|
@item gpgme_event_io_cb_t event
|
|
This is the function called by @acronym{GPGME} to signal an event for
|
|
an operation. It must be specified, because at least the start event
|
|
must be processed.
|
|
|
|
@item void *event_data
|
|
This is passed as the first argument to the @code{event} function when
|
|
it is called by @acronym{GPGME}. For example, it can be used to
|
|
determine the context in which the event has occured.
|
|
@end table
|
|
@end deftp
|
|
|
|
@deftypefun void gpgme_set_io_cbs (@w{gpgme_ctx_t @var{ctx}}, @w{struct gpgme_io_cb_ts *@var{io_cbs}})
|
|
The function @code{gpgme_set_io_cbs} enables the I/O callback
|
|
interface for the context @var{ctx}. The I/O callback functions are
|
|
specified by @var{io_cbs}.
|
|
|
|
If @var{io_cbs}->@code{add} is @code{NULL}, the I/O callback interface
|
|
is disabled for the context, and normal operation is restored.
|
|
@end deftypefun
|
|
|
|
@deftypefun void gpgme_get_io_cbs (@w{gpgme_ctx_t @var{ctx}}, @w{struct gpgme_io_cb_ts *@var{io_cbs}})
|
|
The function @code{gpgme_get_io_cbs} returns the I/O callback
|
|
functions set with @code{gpgme_set_io_cbs} in @var{io_cbs}.
|
|
@end deftypefun
|
|
|
|
|
|
@node I/O Callback Example
|
|
@subsubsection I/O Callback Example
|
|
|
|
To actually use an external event loop, you have to implement the I/O
|
|
callback functions that are used by @acronym{GPGME} to register and
|
|
unregister file descriptors. Furthermore, you have to actually
|
|
monitor these file descriptors for activity and call the appropriate
|
|
I/O callbacks.
|
|
|
|
The following example illustrates how to do that. The example uses
|
|
locking to show in which way the callbacks and the event loop can
|
|
run concurrently. For the event loop, we use a fixed array. For a
|
|
real-world implementation, you should use a dynamically sized
|
|
structure because the number of file descriptors needed for a crypto
|
|
operation in @acronym{GPGME} is not predictable.
|
|
|
|
@example
|
|
#include <pthread.h>
|
|
#include <sys/types.h>
|
|
#include <gpgme.h>
|
|
|
|
/* The following structure holds the result of a crypto operation. */
|
|
struct op_result
|
|
@{
|
|
int done;
|
|
gpgme_error_t err;
|
|
@};
|
|
|
|
/* The following structure holds the data associated with one I/O
|
|
callback. */
|
|
struct one_fd
|
|
@{
|
|
int fd;
|
|
int dir;
|
|
gpgme_io_cb_t fnc;
|
|
void *fnc_data;
|
|
@};
|
|
|
|
struct event_loop
|
|
@{
|
|
pthread_mutex_t lock;
|
|
#define MAX_FDS 32
|
|
/* Unused slots are marked with FD being -1. */
|
|
struct one_fd fds[MAX_FDS];
|
|
@};
|
|
@end example
|
|
|
|
The following functions implement the I/O callback interface.
|
|
|
|
@example
|
|
gpgme_error_t
|
|
add_io_cb (void *data, int fd, int dir, gpgme_io_cb_t fnc, void *fnc_data,
|
|
void **r_tag)
|
|
@{
|
|
struct event_loop *loop = data;
|
|
struct one_fd *fds = loop->fds;
|
|
int i;
|
|
|
|
pthread_mutex_lock (&loop->lock);
|
|
for (i = 0; i < MAX_FDS; i++)
|
|
@{
|
|
if (fds[i].fd == -1)
|
|
@{
|
|
fds[i].fd = fd;
|
|
fds[i].dir = dir;
|
|
fds[i].fnc = fnc;
|
|
fds[i].fnc_data = fnc_data;
|
|
break;
|
|
@}
|
|
@}
|
|
pthread_mutex_unlock (&loop->lock);
|
|
if (i == MAX_FDS)
|
|
return gpg_error (GPG_ERR_GENERAL);
|
|
*r_tag = &fds[i];
|
|
return 0;
|
|
@}
|
|
|
|
void
|
|
remove_io_cb (void *tag)
|
|
@{
|
|
struct one_fd *fd = tag;
|
|
|
|
pthread_mutex_lock (&loop->lock);
|
|
fd->fd = -1;
|
|
pthread_mutex_unlock (&loop->lock);
|
|
@}
|
|
|
|
void
|
|
event_io_cb (void *data, gpgme_event_io_t type, void *type_data)
|
|
@{
|
|
struct op_result *result = data;
|
|
|
|
/* We don't support list operations here. */
|
|
if (type == GPGME_EVENT_DONE)
|
|
@{
|
|
result->done = 1;
|
|
result->err = *type_data;
|
|
@}
|
|
@}
|
|
@end example
|
|
|
|
The final missing piece is the event loop, which will be presented
|
|
next. We only support waiting for the success of a single operation.
|
|
|
|
@example
|
|
int
|
|
do_select (struct event_loop *loop)
|
|
@{
|
|
fd_set rfds;
|
|
fd_set wfds;
|
|
int i, n;
|
|
int any = 0;
|
|
|
|
pthread_mutex_lock (&loop->lock);
|
|
FD_ZERO (&rfds);
|
|
FD_ZERO (&wfds);
|
|
for (i = 0; i < FDLIST_MAX; i++)
|
|
if (fdlist[i].fd != -1)
|
|
FD_SET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds);
|
|
pthread_mutex_unlock (&loop->unlock);
|
|
|
|
do
|
|
@{
|
|
n = select (FD_SETSIZE, &rfds, &wfds, NULL, 0);
|
|
@}
|
|
while (n < 0 && errno == EINTR);
|
|
|
|
if (n < 0)
|
|
return n; /* Error or timeout. */
|
|
|
|
pthread_mutex_lock (&loop->lock);
|
|
for (i = 0; i < FDLIST_MAX && n; i++)
|
|
@{
|
|
if (fdlist[i].fd != -1)
|
|
@{
|
|
if (FD_ISSET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds))
|
|
@{
|
|
assert (n);
|
|
n--;
|
|
any = 1;
|
|
/* The I/O callback handler can register/remove callbacks,
|
|
so we have to unlock the file descriptor list. */
|
|
pthread_mutex_unlock (&loop->lock);
|
|
(*fdlist[i].fnc) (fdlist[i].fnc_data, fdlist[i].fd);
|
|
pthread_mutex_lock (&loop->lock);
|
|
@}
|
|
@}
|
|
@}
|
|
pthread_mutex_unlock (&loop->lock);
|
|
return any;
|
|
@}
|
|
|
|
void
|
|
wait_for_op (struct event_loop *loop, struct op_result *result)
|
|
@{
|
|
int ret;
|
|
|
|
do
|
|
@{
|
|
ret = do_select (loop);
|
|
@}
|
|
while (ret >= 0 && !result->done);
|
|
return ret;
|
|
@}
|
|
@end example
|
|
|
|
The main function shows how to put it all together.
|
|
|
|
@example
|
|
int
|
|
main (int argc, char *argv[])
|
|
@{
|
|
struct event_loop loop;
|
|
struct op_result result;
|
|
gpgme_ctx_t ctx;
|
|
gpgme_error_t err;
|
|
gpgme_data_t sig, text;
|
|
gpgme_sig_stat_t status;
|
|
int i;
|
|
struct gpgme_io_cb_ts io_cbs =
|
|
@{
|
|
add_io_cb,
|
|
&loop,
|
|
remove_io_cb,
|
|
event_io_cb,
|
|
&result
|
|
@};
|
|
|
|
/* Initialize the loop structure. */
|
|
loop.lock = PTHREAD_MUTEX_INITIALIZER;
|
|
for (i = 0; i < MAX_FDS; i++)
|
|
loop->fds[i].fd = -1;
|
|
|
|
/* Initialize the result structure. */
|
|
result.done = 0;
|
|
|
|
err = gpgme_data_new_from_file (&sig, "signature", 1);
|
|
if (!err)
|
|
err = gpgme_data_new_from_file (&text, "text", 1);
|
|
if (!err)
|
|
err = gpgme_new (&ctx);
|
|
if (!err)
|
|
@{
|
|
gpgme_set_io_cbs (ctx, &io_cbs);
|
|
err = gpgme_op_verify_start (ctx, sig, text, &status);
|
|
@}
|
|
if (err)
|
|
@{
|
|
fprintf (stderr, "gpgme error: %s: %s\n",
|
|
gpgme_strsource (err), gpgme_strerror (err));
|
|
exit (1);
|
|
@}
|
|
|
|
wait_for_op (&loop, &result);
|
|
if (!result.done)
|
|
@{
|
|
fprintf (stderr, "select error\n");
|
|
exit (1);
|
|
@}
|
|
if (!result.err)
|
|
@{
|
|
fprintf (stderr, "verification failed: %s: %s\n",
|
|
gpgme_strsource (result.err), gpgme_strerror (result.err));
|
|
exit (1);
|
|
@}
|
|
/* Evaluate STATUS. */
|
|
@dots{}
|
|
return 0;
|
|
@}
|
|
@end example
|
|
|
|
|
|
@node I/O Callback Example GTK+
|
|
@subsubsection I/O Callback Example GTK+
|
|
@cindex GTK+, using @acronym{GPGME} with
|
|
|
|
The I/O callback interface can be used to integrate @acronym{GPGME}
|
|
with the GTK+ event loop. The following code snippets shows how this
|
|
can be done using the appropriate register and remove I/O callback
|
|
functions. In this example, the private data of the register I/O
|
|
callback function is unused. The event notifications is missing
|
|
because it does not require any GTK+ specific setup.
|
|
|
|
@example
|
|
#include <gtk/gtk.h>
|
|
|
|
struct my_gpgme_io_cb
|
|
@{
|
|
gpgme_io_cb_t fnc;
|
|
void *fnc_data;
|
|
guint input_handler_id
|
|
@};
|
|
|
|
void
|
|
my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition)
|
|
@{
|
|
struct my_gpgme_io_cb *iocb = data;
|
|
(*(iocb->fnc)) (iocb->data, source);
|
|
@}
|
|
|
|
void
|
|
my_gpgme_remove_io_cb (void *data)
|
|
@{
|
|
struct my_gpgme_io_cb *iocb = data;
|
|
gtk_input_remove (data->input_handler_id);
|
|
@}
|
|
|
|
void
|
|
my_gpgme_register_io_callback (void *data, int fd, int dir, gpgme_io_cb_t fnc,
|
|
void *fnc_data, void **tag)
|
|
@{
|
|
struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb));
|
|
iocb->fnc = fnc;
|
|
iocb->data = fnc_data;
|
|
iocb->input_handler_id = gtk_input_add_full (fd, dir
|
|
? GDK_INPUT_READ
|
|
: GDK_INPUT_WRITE,
|
|
my_gpgme_io_callback,
|
|
0, iocb, NULL);
|
|
*tag = iocb;
|
|
return 0;
|
|
@}
|
|
@end example
|
|
|
|
|
|
@node I/O Callback Example GDK
|
|
@subsubsection I/O Callback Example GDK
|
|
@cindex GDK, using @acronym{GPGME} with
|
|
|
|
The I/O callback interface can also be used to integrate
|
|
@acronym{GPGME} with the GDK event loop. The following code snippets
|
|
shows how this can be done using the appropriate register and remove
|
|
I/O callback functions. In this example, the private data of the
|
|
register I/O callback function is unused. The event notifications is
|
|
missing because it does not require any GDK specific setup.
|
|
|
|
It is very similar to the GTK+ example in the previous section.
|
|
|
|
@example
|
|
#include <gdk/gdk.h>
|
|
|
|
struct my_gpgme_io_cb
|
|
@{
|
|
gpgme_io_cb_t fnc;
|
|
void *fnc_data;
|
|
gint tag;
|
|
@};
|
|
|
|
void
|
|
my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition)
|
|
@{
|
|
struct my_gpgme_io_cb *iocb = data;
|
|
(*(iocb->fnc)) (iocb->data, source);
|
|
@}
|
|
|
|
void
|
|
my_gpgme_remove_io_cb (void *data)
|
|
@{
|
|
struct my_gpgme_io_cb *iocb = data;
|
|
gdk_input_remove (data->tag);
|
|
@}
|
|
|
|
void
|
|
my_gpgme_register_io_callback (void *data, int fd, int dir, gpgme_io_cb_t fnc,
|
|
void *fnc_data, void **tag)
|
|
@{
|
|
struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb));
|
|
iocb->fnc = fnc;
|
|
iocb->data = fnc_data;
|
|
iocb->tag = gtk_input_add_full (fd, dir ? GDK_INPUT_READ : GDK_INPUT_WRITE,
|
|
my_gpgme_io_callback, iocb, NULL);
|
|
*tag = iocb;
|
|
return 0;
|
|
@}
|
|
@end example
|
|
|
|
|
|
@node I/O Callback Example Qt
|
|
@subsubsection I/O Callback Example Qt
|
|
@cindex Qt, using @acronym{GPGME} with
|
|
|
|
The I/O callback interface can also be used to integrate
|
|
@acronym{GPGME} with the Qt event loop. The following code snippets
|
|
show how this can be done using the appropriate register and remove
|
|
I/O callback functions. In this example, the private data of the
|
|
register I/O callback function is unused. The event notifications is
|
|
missing because it does not require any Qt specific setup.
|
|
|
|
@example
|
|
#include <qsocketnotifier.h>
|
|
#include <qapplication.h>
|
|
|
|
struct IOCB @{
|
|
IOCB( GpgmeIOCb f, void * d, QSocketNotifier * n )
|
|
: func( f ), data( d ), notifier( n ) @{@}
|
|
GpgmeIOCb func;
|
|
void * data;
|
|
QSocketNotifier * notifier;
|
|
@}
|
|
|
|
class MyApp : public QApplication @{
|
|
|
|
// ...
|
|
|
|
static void registerGpgmeIOCallback( void * data, int fd, int dir,
|
|
GpgmeIOCb func, void * func_data,
|
|
void ** tag ) @{
|
|
QSocketNotifier * n =
|
|
new QSocketNotifier( fd, dir ? QSocketNotifier::Read
|
|
: QSocketNotifier::Write );
|
|
connect( n, SIGNAL(activated(int)),
|
|
qApp, SLOT(slotGpgmeIOCallback(int)) );
|
|
qApp->mIOCBs.push_back( IOCB( func, func_data, n ) );
|
|
*tag = (void*)n;
|
|
@}
|
|
|
|
static void removeGpgmeIOCallback( void * tag ) @{
|
|
if ( !tag ) return;
|
|
QSocketNotifier * n = static_cast<QSocketNotifier*>( tag );
|
|
for ( QValueList<IOCB>::iterator it = qApp->mIOCBs.begin() ;
|
|
it != qApp->mIOCBs.end() ; ++it )
|
|
if ( it->notifier == n ) @{
|
|
delete it->notifier;
|
|
qApp->mIOCBs.erase( it );
|
|
return;
|
|
@}
|
|
@}
|
|
|
|
public slots:
|
|
void slotGpgmeIOCallback( int fd ) @{
|
|
for ( QValueList<IOCB>::const_iterator it = mIOCBs.begin() ;
|
|
it != mIOCBs.end() ; ++it )
|
|
if ( it->notifier && it->notifier->socket() == fd )
|
|
(*(it->func)) ( it->func_data, fd );
|
|
@}
|
|
|
|
// ...
|
|
|
|
private:
|
|
QValueList<IOCB> mIOCBs;
|
|
// ...
|
|
@};
|
|
@end example
|
|
|
|
|
|
@node Cancellation
|
|
@subsection Cancellation
|
|
@cindex cryptographic operation, aborting
|
|
@cindex cryptographic operation, cancelling
|
|
@cindex aborting operations
|
|
@cindex cancelling operations
|
|
|
|
Sometimes you do not want to wait for an operation to finish. If you
|
|
use external I/O callbacks, you can cancel a pending operation.
|
|
However, you must ensure that no other thread is currently using the
|
|
context in which the operation you want to cancel runs. This includes
|
|
callback handlers. So your external event loop must either be halted
|
|
or otherwise it must be guaranteed that no installed I/O callbacks are
|
|
run for this context.
|
|
|
|
@deftypefun gpgme_ctx_t gpgme_cancel (@w{gpgme_ctx_t @var{ctx}})
|
|
The function @code{gpgme_cancel} attempts to cancel a pending
|
|
operation in the context @var{ctx}. This only works if you use the
|
|
global event loop or your own event loop.
|
|
|
|
If you use the global event loop, you must not call @code{gpgme_wait}
|
|
or @code{gpgme_wait} during cancellation. After successful
|
|
cancellation, you can call @code{gpgme_wait} (optionally waiting on
|
|
@var{ctx}), and the context @var{ctx} will appear as if it had
|
|
finished with the error code @code{GPG_ERR_CANCEL}.
|
|
|
|
If you use your an external event loop, you must ensure that no I/O
|
|
callbacks are invoked for this context (for example by halting the
|
|
event loop). On successful cancellation, all registered I/O callbacks
|
|
for this context will be unregistered, and a @code{GPGME_EVENT_DONE}
|
|
event with the error code @code{GPG_ERR_CANCEL} will be signaled.
|
|
|
|
The function returns an error code if the cancellation failed (in this
|
|
case the state of @var{ctx} is not modified).
|
|
@end deftypefun
|
|
|
|
|
|
@include lesser.texi
|
|
|
|
|
|
@node Concept Index
|
|
@unnumbered Concept Index
|
|
|
|
@printindex cp
|
|
|
|
|
|
@node Function and Data Index
|
|
@unnumbered Function and Data Index
|
|
|
|
@printindex fn
|
|
|
|
|
|
@summarycontents
|
|
@contents
|
|
@bye
|