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

• Generating a certificate: See the CertBuilder module.
• Parsing a certificate: See the Parser implementation for Cert.
• Parsing a keyring: See the CertParser module.
• Serializing a certificate: See the Serialize implementation for Cert, and the Cert::as_tsk method to also include any secret key material.
• Using a certificate: See the Cert and ValidCert data structures.
• Revoking a certificate: See the CertRevocationBuilder data structure.
• Decrypt or encrypt secret keys: See packet::Key::encrypt_secret’s example.
• Merging packets: See the Cert::insert_packets method.
• Merging certificates: See the Cert::merge_public method.
• Creating third-party certifications: See the UserID::certify and UserAttribute::certify methods.
• Using User IDs and User Attributes: See the ComponentAmalgamation module.
• Using keys: See the KeyAmalgamation module.
• Updating a binding signature: See the UserID::bind, UserAttribute::bind, and Key::bind methods.
• Checking third-party signatures: See the Signature::verify_direct_key, Signature::verify_userid_binding, and Signature::verify_user_attribute_binding methods.
• Checking third-party revocations: See the ValidCert::revocation_keys, ValidAmalgamation::revocation_keys, Signature::verify_primary_key_revocation, Signature::verify_userid_revocation, Signature::verify_user_attribute_revocation methods.

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.
• raw
  Functionality for dealing with mostly unparsed 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.
• KeyBuilder
  A Key builder.
• SubkeyBuilder
  A Subkey builder.
• 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.