Enum sequoia_openpgp::packet::Key

source ·

#[non_exhaustive]
pub enum Key<P: KeyParts, R: KeyRole> {
    V4(Key4<P, R>),
}

Expand description

Holds a public key, public subkey, private key or private subkey packet.

The different Key packets are described in Section 5.5 of RFC 4880.

Note: This enum cannot be exhaustively matched to allow future extensions.

§Key Variants

There are four different types of keys in OpenPGP: public keys, secret keys, public subkeys, and secret subkeys. Although the semantics of each type of key are slightly different, the underlying representation is identical (even a public key and a secret key are the same: the public key variant just contains 0 bits of secret key material).

In Sequoia, we use a single type, Key, for all four variants. To improve type safety, we use marker traits rather than an enum to distinguish them. Specifically, we Key is generic over two type variables, P and R.

P and R take marker traits, which describe how any secret key material should be treated, and the key’s role (primary or subordinate). The markers also determine the Key’s behavior and the exposed functionality. P can be key::PublicParts, key::SecretParts, or key::UnspecifiedParts. And, R can be key::PrimaryRole, key::SubordinateRole, or key::UnspecifiedRole.

If P is key::PublicParts, any secret key material that is present is ignored. For instance, when serializing a key with this marker, any secret key material will be skipped. This is illutrated in the following example. If P is key::SecretParts, then the key definitely contains secret key material (although it is not guaranteed that the secret key material is valid), and methods that require secret key material are available.

Unlike P, R does not say anything about the Key’s content. But, a key’s role does influence’s the key’s semantics. For instance, some of a primary key’s meta-data is located on the primary User ID whereas a subordinate key’s meta-data is located on its binding signature.

The unspecified variants key::UnspecifiedParts and key::UnspecifiedRole exist to simplify type erasure, which is needed to mix different types of keys in a single collection. For instance, Cert::keys returns an iterator over the keys in a certificate. Since the keys have different roles (a primary key and zero or more subkeys), but the Iterator has to be over a single, fixed type, the returned keys use the key::UnspecifiedRole marker.

§Examples

Serializing a public key with secret key material drops the secret key material:

use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::packet::prelude::*;
use sequoia_openpgp::parse::Parse;
use openpgp::serialize::Serialize;

// Generate a new certificate.  It has secret key material.
let (cert, _) = CertBuilder::new()
    .generate()?;

let pk = cert.primary_key().key();
assert!(pk.has_secret());

// Serializing a `Key<key::PublicParts, _>` drops the secret key
// material.
let mut bytes = Vec::new();
Packet::from(pk.clone()).serialize(&mut bytes);
let p : Packet = Packet::from_bytes(&bytes)?;

if let Packet::PublicKey(key) = p {
    assert!(! key.has_secret());
} else {
    unreachable!();
}

§Conversions

Sometimes it is necessary to change a marker. For instance, to help prevent a user from inadvertently leaking secret key material, the Cert data structure never returns keys with the key::SecretParts marker. This means, to use any secret key material, e.g., when creating a Signer, the user needs to explicitly opt-in by changing the marker using Key::parts_into_secret or Key::parts_as_secret.

For P, the conversion functions are: Key::parts_into_public, Key::parts_as_public, Key::parts_into_secret, Key::parts_as_secret, Key::parts_into_unspecified, and Key::parts_as_unspecified. With the exception of converting P to key::SecretParts, these functions are infallible. Converting P to key::SecretParts may fail if the key doesn’t have any secret key material. (Note: although the secret key material is required, it not checked for validity.)

For R, the conversion functions are Key::role_into_primary, Key::role_as_primary, Key::role_into_subordinate, Key::role_as_subordinate, Key::role_into_unspecified, and Key::role_as_unspecified.

It is also possible to use From.

§Examples

Changing a marker:

use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::packet::prelude::*;

// Generate a new certificate.  It has secret key material.
let (cert, _) = CertBuilder::new()
    .generate()?;

let pk: &Key<key::PublicParts, key::PrimaryRole>
    = cert.primary_key().key();
// `has_secret`s is one of the few methods that ignores the
// parts type.
assert!(pk.has_secret());

// Treat it like a secret key.  This only works if `pk` really
// has secret key material (which it does in this case, see above).
let sk = pk.parts_as_secret()?;
assert!(sk.has_secret());

// And back.
let pk = sk.parts_as_public();
// Yes, the secret key material is still there.
assert!(pk.has_secret());

The Cert data structure only returns public keys. To work with any secret key material, the Key first needs to be converted to a secret key. This is necessary, for instance, when creating a Signer:

use std::time;
use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::crypto::KeyPair;
use openpgp::policy::StandardPolicy;

let p = &StandardPolicy::new();

let the_past = time::SystemTime::now() - time::Duration::from_secs(1);
let (cert, _) = CertBuilder::new()
    .set_creation_time(the_past)
    .generate()?;

// Set the certificate to expire now.  To do this, we need
// to create a new self-signature, and sign it using a
// certification-capable key.  The primary key is always
// certification capable.
let mut keypair = cert.primary_key()
    .key().clone().parts_into_secret()?.into_keypair()?;
let sigs = cert.set_expiration_time(p, None, &mut keypair,
                                    Some(time::SystemTime::now()))?;

let cert = cert.insert_packets(sigs)?;
// It's expired now.
assert!(cert.with_policy(p, None)?.alive().is_err());

§Key Generation

Key is a wrapper around the different key formats. (Currently, Sequoia only supports version 4 keys, however, future versions may add limited support for version 3 keys to facilitate working with achieved messages, and RFC 4880bis includes a proposal for a new key format.) As such, it doesn’t provide a mechanism to generate keys or import existing key material. Instead, use the format-specific functions (e.g., Key4::generate_ecc) and then convert the result into a Key packet, as the following example demonstrates.

§Examples

use sequoia_openpgp as openpgp;
use openpgp::packet::prelude::*;
use openpgp::types::Curve;

let key: Key<key::SecretParts, key::PrimaryRole>
    = Key::from(Key4::generate_ecc(true, Curve::Ed25519)?);

§Password Protection

OpenPGP provides a mechanism to password protect keys. If a key is password protected, you need to decrypt the password using Key::decrypt_secret before using its secret key material (e.g., to decrypt a message, or to generate a signature).

§A note on equality

The implementation of Eq for Key compares the serialized form of Keys. Comparing or serializing values of Key<PublicParts, _> ignore secret key material, whereas the secret key material is considered and serialized for Key<SecretParts, _>, and for Key<UnspecifiedParts, _> if present. To explicitly exclude the secret key material from the comparison, use Key::public_cmp or Key::public_eq.

When merging in secret key material from untrusted sources, you need to be very careful: secret key material is not cryptographically protected by the key’s self signature. Thus, an attacker can provide a valid key with a valid self signature, but invalid secret key material. If naively merged, this could overwrite valid secret key material, and thereby render the key useless. Unfortunately, the only way to find out that the secret key material is bad is to actually try using it. But, because the secret key material is usually encrypted, this can’t always be done automatically.

Compare:

use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::packet::prelude::*;
use openpgp::packet::key::*;

// Generate a new certificate.  It has secret key material.
let (cert, _) = CertBuilder::new()
    .generate()?;

let sk: &Key<PublicParts, _> = cert.primary_key().key();
assert!(sk.has_secret());

// Strip the secret key material.
let cert = cert.clone().strip_secret_key_material();
let pk: &Key<PublicParts, _> = cert.primary_key().key();
assert!(! pk.has_secret());

// Eq on Key<PublicParts, _> compares only the public bits, so it
// considers pk and sk to be equal.
assert_eq!(pk, sk);

// Convert to Key<UnspecifiedParts, _>.
let sk: &Key<UnspecifiedParts, _> = sk.parts_as_unspecified();
let pk: &Key<UnspecifiedParts, _> = pk.parts_as_unspecified();

// Eq on Key<UnspecifiedParts, _> compares both the public and the
// secret bits, so it considers pk and sk to be different.
assert_ne!(pk, sk);

// In any case, Key::public_eq only compares the public bits,
// so it considers them to be equal.
assert!(Key::public_eq(pk, sk));

Variants (Non-exhaustive)§

This enum is marked as non-exhaustive

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

§

V4(Key4<P, R>)

A version 4 Key packet.

Enum sequoia_openpgp::packet::KeyCopy item path

§Key Variants

§Examples

§Conversions

§Examples

§Key Generation

§Examples

§Password Protection

§A note on equality

Variants (Non-exhaustive)§

V4(Key4<P, R>)

Implementations§

impl<P, R> Key<P, R>where P: KeyParts, R: KeyRole,

pub fn parts_into_public(self) -> Key<PublicParts, R>

pub fn parts_as_public(&self) -> &Key<PublicParts, R>

pub fn parts_as_public_mut(&mut self) -> &mut Key<PublicParts, R>

pub fn parts_into_secret(self) -> Result<Key<SecretParts, R>>

pub fn parts_as_secret(&self) -> Result<&Key<SecretParts, R>>

pub fn parts_as_secret_mut(&mut self) -> Result<&mut Key<SecretParts, R>>

pub fn parts_into_unspecified(self) -> Key<UnspecifiedParts, R>

pub fn parts_as_unspecified(&self) -> &Key<UnspecifiedParts, R>

pub fn parts_as_unspecified_mut(&mut self) -> &mut Key<UnspecifiedParts, R>

impl<P, R> Key<P, R>where P: KeyParts, R: KeyRole,

pub fn role_into_primary(self) -> Key<P, PrimaryRole>

pub fn role_as_primary(&self) -> &Key<P, PrimaryRole>

pub fn role_as_primary_mut(&mut self) -> &mut Key<P, PrimaryRole>

pub fn role_into_subordinate(self) -> Key<P, SubordinateRole>

pub fn role_as_subordinate(&self) -> &Key<P, SubordinateRole>

pub fn role_as_subordinate_mut(&mut self) -> &mut Key<P, SubordinateRole>

pub fn role_into_unspecified(self) -> Key<P, UnspecifiedRole>

pub fn role_as_unspecified(&self) -> &Key<P, UnspecifiedRole>

pub fn role_as_unspecified_mut(&mut self) -> &mut Key<P, UnspecifiedRole>

impl<P, R> Key<P, R>where P: KeyParts, R: KeyRole,

pub fn encrypt(&self, data: &SessionKey) -> Result<Ciphertext>

pub fn verify( &self, sig: &Signature, hash_algo: HashAlgorithm, digest: &[u8] ) -> Result<()>

impl<P: KeyParts, R: KeyRole> Key<P, R>

pub fn version(&self) -> u8

pub fn public_cmp<PB, RB>(&self, b: &Key<PB, RB>) -> Orderingwhere PB: KeyParts, RB: KeyRole,

pub fn public_eq<PB, RB>(&self, b: &Key<PB, RB>) -> boolwhere PB: KeyParts, RB: KeyRole,

impl<R: KeyRole> Key<SecretParts, R>

pub fn into_keypair(self) -> Result<KeyPair>

§Errors

§Examples

pub fn decrypt_secret(self, password: &Password) -> Result<Self>

§Examples

pub fn encrypt_secret(self, password: &Password) -> Result<Self>

§Examples

impl<R: KeyRole> Key<PublicParts, R>

pub fn take_secret(self) -> (Key<PublicParts, R>, Option<SecretKeyMaterial>)

pub fn add_secret( self, secret: SecretKeyMaterial ) -> (Key<SecretParts, R>, Option<SecretKeyMaterial>)

impl<R: KeyRole> Key<UnspecifiedParts, R>

pub fn take_secret(self) -> (Key<PublicParts, R>, Option<SecretKeyMaterial>)

pub fn add_secret( self, secret: SecretKeyMaterial ) -> (Key<SecretParts, R>, Option<SecretKeyMaterial>)

impl<R: KeyRole> Key<SecretParts, R>

pub fn take_secret(self) -> (Key<PublicParts, R>, SecretKeyMaterial)

pub fn add_secret( self, secret: SecretKeyMaterial ) -> (Key<SecretParts, R>, SecretKeyMaterial)

impl<P: KeyParts> Key<P, SubordinateRole>

pub fn bind( &self, signer: &mut dyn Signer, cert: &Cert, signature: SignatureBuilder ) -> Result<Signature>

§Examples

Methods from Deref<Target = Key4<P, R>>§

pub fn parts_as_public(&self) -> &Key4<PublicParts, R>

pub fn parts_as_public_mut(&mut self) -> &mut Key4<PublicParts, R>

pub fn parts_as_secret(&self) -> Result<&Key4<SecretParts, R>>

pub fn parts_as_secret_mut(&mut self) -> Result<&mut Key4<SecretParts, R>>

pub fn parts_as_unspecified(&self) -> &Key4<UnspecifiedParts, R>

pub fn parts_as_unspecified_mut(&mut self) -> &mut Key4<UnspecifiedParts, R>

pub fn role_as_primary(&self) -> &Key4<P, PrimaryRole>

pub fn role_as_primary_mut(&mut self) -> &mut Key4<P, PrimaryRole>

pub fn role_as_subordinate(&self) -> &Key4<P, SubordinateRole>

pub fn role_as_subordinate_mut(&mut self) -> &mut Key4<P, SubordinateRole>

pub fn role_as_unspecified(&self) -> &Key4<P, UnspecifiedRole>

pub fn role_as_unspecified_mut(&mut self) -> &mut Key4<P, UnspecifiedRole>

pub fn hash_algo_security(&self) -> HashAlgoSecurity

pub fn public_cmp<PB, RB>(&self, b: &Key4<PB, RB>) -> Orderingwhere PB: KeyParts, RB: KeyRole,

pub fn public_eq<PB, RB>(&self, b: &Key4<PB, RB>) -> boolwhere PB: KeyParts, RB: KeyRole,

pub fn public_hash<H>(&self, state: &mut H)where H: Hasher,

pub fn creation_time(&self) -> SystemTime

pub fn set_creation_time<T>(&mut self, timestamp: T) -> Result<SystemTime>where T: Into<SystemTime>,

pub fn pk_algo(&self) -> PublicKeyAlgorithm

pub fn set_pk_algo(&mut self, pk_algo: PublicKeyAlgorithm) -> PublicKeyAlgorithm

Enum sequoia_openpgp::packet::Key

impl<P, R> Key<P, R>
where P: KeyParts, R: KeyRole,

impl<P, R> Key<P, R>
where P: KeyParts, R: KeyRole,

impl<P, R> Key<P, R>
where P: KeyParts, R: KeyRole,

pub fn public_cmp<PB, RB>(&self, b: &Key<PB, RB>) -> Ordering
where PB: KeyParts, RB: KeyRole,

pub fn public_eq<PB, RB>(&self, b: &Key<PB, RB>) -> bool
where PB: KeyParts, RB: KeyRole,

pub fn public_cmp<PB, RB>(&self, b: &Key4<PB, RB>) -> Ordering
where PB: KeyParts, RB: KeyRole,

pub fn public_eq<PB, RB>(&self, b: &Key4<PB, RB>) -> bool
where PB: KeyParts, RB: KeyRole,

pub fn public_hash<H>(&self, state: &mut H)
where H: Hasher,

pub fn set_creation_time<T>(&mut self, timestamp: T) -> Result<SystemTime>
where T: Into<SystemTime>,

impl<P> From<&Key<P, PrimaryRole>> for &Key<P, SubordinateRole>
where P: KeyParts,

impl<P> From<&Key<P, PrimaryRole>> for &Key<P, UnspecifiedRole>
where P: KeyParts,