Module sequoia_openpgp::packet::key

Key-related functionality.

Data Types

The main data type is the Key enum. This enum abstracts away the differences between the key formats (the deprecated version 3, the current version 4, and the proposed version 5 formats). Nevertheless, some functionality remains format specific. For instance, the Key enum doesn’t provide a mechanism to generate keys. This functionality depends on the format.

This version of Sequoia only supports version 4 keys (Key4). However, future versions may include limited support for version 3 keys to allow working with archived messages, and we intend to add support for version 5 keys once the new version of the specification has been finalized.

OpenPGP specifies four different types of keys: public keys, secret keys, public subkeys, and secret subkeys. These are all represented by the Key enum and the Key4 struct using marker types. We use marker types rather than an enum, to better exploit the type checking. For instance, type-specific methods like Key4::secret are only exposed for those types that actually support them. See the documentation for Key for an explanation of how the markers work.

The SecretKeyMaterial data type allows working with secret key material directly. This enum has two variants: Unencrypted, and Encrypted. It is not normally necessary to use this data structure directly. The primary functionality that is of interest to most users is decrypting secret key material. This is usually more conveniently done using Key::decrypt_secret.

Key Creation

Use Key4::generate_rsa or Key4::generate_ecc to create a new key.

Existing key material can be turned into an OpenPGP key using Key4::import_public_cv25519, Key4::import_public_ed25519, Key4::import_public_rsa, Key4::import_secret_cv25519, Key4::import_secret_ed25519, and Key4::import_secret_rsa.

Whether you create a new key or import existing key material, you still need to create a binding signature, and, for signing keys, a back signature for the key to be usable.

In-Memory Protection of Secret Key Material

Whether the secret key material is protected on disk or not, Sequoia encrypts unencrypted secret key material (Unencrypted) while it is memory. This helps protect against heartbleed-style attacks where a buffer over-read allows an attacker to read from the process’s address space. This protection is less important for Rust programs, which are memory safe. However, it is essential when Sequoia is used via its FFI.

See crypto::mem::Encrypted for details.

Structs

• Encrypted
  Secret key material encrypted with a password.
• Key4
  Holds a public key, public subkey, private key or private subkey packet.
• PrimaryRole
  A marker that indicates the Key should be treated like a primary key.
• PublicParts
  A marker that indicates that a Key should be treated like a public key.
• SecretParts
  A marker that indicates that a Key should be treated like a secret key.
• SubordinateRole
  A marker that indicates the Key should treated like a subkey.
• Unencrypted
  Unencrypted secret key material.
• UnspecifiedParts
  A marker that indicates that a Key’s parts are unspecified.
• UnspecifiedRole
  A marker that indicates the Key’s role is unspecified.

Enums

• SecretKeyMaterial
  Holds secret key material.

Traits

• KeyParts
  A marker trait that captures whether a Key definitely contains secret key material.
• KeyRole
  A marker trait that captures a Key’s role.