Certificates and related data structures.
An OpenPGP certificate, often called a
PGP key or just a
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.
- Generating a certificate: See the
- Parsing a certificate: See the
- Parsing a keyring: See the
- Serializing a certificate: See the
Cert, and the
Cert::as_tskmethod to also include any secret key material.
- Using a certificate: See the
- Revoking a certificate: See the
- Merging packets: See the
- Merging certificates: See the
- Creating third-party certifications: See the
- Using User IDs and User Attributes: See the
- Using keys: See the
- Updating a binding signature: See the
- Checking third-party signatures: See the
- Checking third-party revocations: See 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
In Sequoia, we refer to
User Attributes, and
Components. To accommodate unsupported components (e.g.,
deprecated v3 keys) and unknown components (e.g., the
Xyzzy Property), we also define an
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
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.
To workaround this lack of context, we introduce another data
structure called a
ComponentAmalgamation references a
ComponentBundle and its
Cert. Unfortunately, we can't include a reference to
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.
Components, their associated signatures, and some useful methods.
A certificate component and its associated signatures.
Brings most relevant types and traits into scope for working with certificates.
A collection of components and their associated signatures.
Simplifies the generation of OpenPGP certificates.
An iterator over a sequence of certificates, i.e., an OpenPGP keyring.
A builder for revocation certificates for OpenPGP certificates.
An iterator that moves out of a
A builder for revocation certificates for subkeys.
A builder for revocation certificates for User Attributes.
A builder for revocation certificates for User ID.
Groups symmetric and asymmetric algorithms.
Returns the certificate holder's preferences.