The GPGME Framework

Introduction

`GnuPG Made Easy' (GPGME) is an Objective-C framework wrapping libgpgme, a C language library, that allows to add support for cryptography to a program. It is designed to make access to crypto engines like GnuPG or GpgSM easier for applications. GPGME provides a high-level crypto API for encryption, decryption, signing, signature verification and key management.

GPGME uses GnuPG and GpgSM as its backends to support OpenPGP and the Cryptographic Message Syntax (CMS).

Getting Started

This file introduces the GPGME framework programming interface. Read the different pages to get more information about classes, methods, functions and data types provided by the framework.

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 framework are not explained, but where necessary, special features or requirements by an engine are mentioned as far as they are relevant to GPGME or its users.

Features

GPGME has a couple of advantages over other libraries/frameworks doing a similar job, and over implementing support for GnuPG or other crypto engines into your application directly.

It's free software: Anybody can use, modify, and redistribute it under the terms of the GNU Lesser General Public License.
It's flexible: GPGME provides transparent support for several cryptographic protocols by different engines. Currently, GPGME supports the OpenPGP protocol using GnuPG as the backend, and the Cryptographic Message Syntax using GpgSM as the backend. NOTE: GpgSM has not yet been ported to MacOS X.
It's easy: 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 GPGME has been added to a program, it is easy to add support for other crypto protocols once GPGME backends provide them.

Overview

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 data source.

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, 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.

Caution: The GPGME framework is not thread-safe. It will be to some extent in the future, but currently great care has to be taken if GPGME is used in a multi-threaded environment. You should at least take care that no instance of GPGContext nor GPGData is accessed concurrently, and that only one thread at any time calls +[GPGContext waitOnAnyRequest:] or -[GPGContext wait:].

Error handling

Many methods in GPGME can raise an exception 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 tampered message, the decryption will fail.

Most methods indicate that they could raise an exception, but in most cases, this is... exceptional (e.g. out of memory condition). You don't need to enclose all GPGME method calls in exception handlers. Just do it for operations which could fail, due to invalid parameters/data given by the end user.