[][src]Module sequoia_openpgp::cert

Certificates and related data structures.

An OpenPGP certificate, often called a PGP key or just a key, is a collection of keys, identity information, and certifications about those keys and identities.

The foundation of an OpenPGP certificate is the so-called primary key. A primary key has three essential functions. First, the primary key is used to derive a universally unique identifier (UUID) for the certificate, the certificate's so-called fingerprint. Second, the primary key is used to certify assertions that the certificate holder makes about their certificate. For instance, to associate a subkey or a User ID with a certificate, the certificate holder uses the primary key to create a self signature called a binding signature. This binding signature is distributed with the certificate. It allows anyone who has the certificate to verify that the certificate holder (identified by the primary key) really intended for the subkey to be associated with the certificate. Finally, the primary key can be used to make assertions about other certificates. For instance, Alice can make a so-called third-party certification that attests that she is convinced that Bob (as described by some User ID) controls a particular certificate. These third-party certifications are typically distributed alongside the signee's certificate, and are used by trust models like the Web of Trust to authenticate certificates.

Common Operations

Data Structures

Cert

The Cert data structure closely mirrors the transferable public key (TPK) data structure described in Section 11.1 of RFC 4880: it contains the certificate's Components and their associated signatures.

Components

In Sequoia, we refer to User IDs, User Attributes, and Keys as Components. To accommodate unsupported components (e.g., deprecated v3 keys) and unknown components (e.g., the yet-to-be-defined Xyzzy Property), we also define an Unknown component.

ComponentBundles

We call a Component and any associated signatures a ComponentBundle. There are four types of associated signatures: self signatures, third-party signatures, self revocations, and third-party revocations.

Although some information about a given Component is stored in the Component itself, most of the information is stored on the associated signatures. For instance, a key's creation time is stored in the key packet, but the key's capabilities (e.g., whether it can be used for encryption or signing), and its expiry are stored in the associated self signatures. Thus, to use a component, we usually need its corresponding self signature.

When a certificate is parsed, Sequoia ensures that all components (except the primary key) have at least one valid self signature. However, when using a component, it is still necessary to find the right self signature. And, unfortunately, finding the self signature for the primary Key is non-trivial: that's the primary User ID's self signature. Another complication is that if the self signature doesn't contain the required information, then the implementation should look for the information on a direct key signature. Thus, a ComponentBundle doesn't contain all of the information that is needed to use a component.

ComponentAmalgamations

To workaround this lack of context, we introduce another data structure called a ComponentAmalgamation. A ComponentAmalgamation references a ComponentBundle and its associated Cert. Unfortunately, we can't include a reference to the Cert in the ComponentBundle, because the Cert owns the ComponentBundle, and that would create a self-referential data structure, which is currently not supported in Rust.

Modules

amalgamation

Components, their associated signatures, and some useful methods.

bundle

A certificate component and its associated signatures.

prelude

Brings most relevant types and traits into scope for working with certificates.

Structs

Cert

A collection of components and their associated signatures.

CertBuilder

Simplifies the generation of OpenPGP certificates.

CertParser

An iterator over a sequence of certificates, i.e., an OpenPGP keyring.

CertRevocationBuilder

A builder for revocation certificates for OpenPGP certificates.

IntoIter

An iterator that moves out of a Cert.

SubkeyRevocationBuilder

A builder for revocation certificates for subkeys.

UserAttributeRevocationBuilder

A builder for revocation certificates for User Attributes.

UserIDRevocationBuilder

A builder for revocation certificates for User ID.

ValidCert

A Cert plus a Policy and a reference time.

Enums

CipherSuite

Groups symmetric and asymmetric algorithms.

Traits

Preferences

Returns the certificate holder's preferences.