[][src]Struct sequoia_openpgp::tpk::TPK

pub struct TPK { /* fields omitted */ }

A transferable public key (TPK).

A TPK (see RFC 4880, section 11.1) can be used to verify signatures and encrypt data. It can be stored in a keystore and uploaded to keyservers.

TPKs are always canonicalized in the sense that only elements (user id, user attribute, subkey) with at least one valid self-signature are preserved. Also, invalid self-signatures are dropped. The self-signatures are sorted so that the newest self-signature comes first. Components are sorted, but in an undefined manner (i.e., when parsing the same TPK multiple times, the components will be in the same order, but we reserve the right to change the sort function between versions). Third-party certifications are not validated, as the keys are not available; they are simply passed through as is.

Secret keys

Any key in a TPK may have a secret key attached to it. To protect secret keys from being leaked, secret keys are not written out if a TPK is serialized. To also serialize the secret keys, you need to use TPK::as_tsk() to get an object that writes them out during serialization.

Example

use openpgp::TPK;

match TPK::from_packet_parser(ppr) {
    Ok(tpk) => {
        println!("Key: {}", tpk.primary());
        for binding in tpk.userids() {
            println!("User ID: {}", binding.userid());
        }
    }
    Err(err) => {
        eprintln!("Error parsing TPK: {}", err);
    }
}

Methods

impl TPK[src]

pub fn primary(&self) -> &PublicKey[src]

Returns a reference to the primary key binding.

Note: information about the primary key is often stored on the primary User ID's self signature. Since these signatures are associated with the UserID and not the primary key, that information is not contained in the key binding. Instead, you should use methods like TPK::primary_key_signature() to get information about the primary key.

pub fn primary_userid<T>(&self, t: T) -> Option<&UserIDBinding> where
    T: Into<Option<Tm>>, 
[src]

Returns the binding for the primary User ID at time t.

See TPK::primary_userid_full for a description of how the primary user id is determined.

pub fn primary_userid_full<T>(
    &self,
    t: T
) -> Option<(&UserIDBinding, &Signature, RevocationStatus)> where
    T: Into<Option<Tm>>, 
[src]

Returns the binding for the primary User ID at time t and some associated data.

In addition to the User ID binding, this also returns the binding signature and the User ID's RevocationStatus at time t.

The primary User ID is determined by taking the User IDs that are alive at time t, and sorting them as follows:

  • non-revoked first
  • primary first
  • signature creation first

If there is more than one, than one is selected in a deterministic, but undefined manner.

pub fn primary_key_signature_full<T>(
    &self,
    t: T
) -> Option<(&Signature, Option<(&UserIDBinding, RevocationStatus)>)> where
    T: Into<Option<Tm>>, 
[src]

Returns the primary key's current self-signature as of t.

If the current self-signature is from a User ID binding (and not a direct signature), this also returns the User ID binding and its revocation status as of t.

The primary key's current self-signature as of t is, in order of preference:

  • The binding signature of the primary User ID at time t, if the primary User ID is not revoked at time t.

  • The newest, live, direct self signature at time t.

  • The binding signature of the primary User ID at time t (this can only happen if there are only revoked User IDs at time t).

If there are no applicable signatures, None is returned.

pub fn primary_key_signature<T>(&self, t: T) -> Option<&Signature> where
    T: Into<Option<Tm>>, 
[src]

Returns the primary key's current self-signature.

This function is identical to TPK::primary_key_signature_full(), but it doesn't return the UserIDBinding.

pub fn direct_signatures(&self) -> &[Signature][src]

The direct signatures.

The signatures are validated, and they are reverse sorted by their creation time (newest first).

pub fn certifications(&self) -> &[Signature][src]

Third-party certifications.

The signatures are not validated. They are reverse sorted by their creation time (newest first).

pub fn self_revocations(&self) -> &[Signature][src]

Revocations issued by the key itself.

The revocations are validated, and they are reverse sorted by their creation time (newest first).

pub fn other_revocations(&self) -> &[Signature][src]

Revocations issued by other keys.

The revocations are not validated. They are reverse sorted by their creation time (newest first).

pub fn revoked<T>(&self, t: T) -> RevocationStatus where
    T: Into<Option<Tm>>, 
[src]

Returns the TPK's revocation status at time t.

A TPK is revoked at time t if:

  • There is a live revocation at time t that is newer than all live self signatures at time t, or

  • There is a hard revocation (even if it is not live at time t, and even if there is a newer self-signature).

Note: TPKs and subkeys have different criteria from User IDs and User Attributes.

Note: this only returns whether this TPK is revoked; it does not imply anything about the TPK or other components.

pub fn revoke_in_place<R>(
    self,
    primary_signer: &mut dyn Signer<R>,
    code: ReasonForRevocation,
    reason: &[u8]
) -> Result<TPK> where
    R: KeyRole
[src]

Revokes the TPK in place.

Note: to just generate a revocation certificate, use the TPKRevocationBuilder.

If you want to revoke an individual component, use SubkeyRevocationBuilder, UserIDRevocationBuilder, or UserAttributeRevocationBuilder, as appropriate.

Example

use openpgp::RevocationStatus;
use openpgp::constants::{ReasonForRevocation, SignatureType};
use openpgp::tpk::{CipherSuite, TPKBuilder};
use openpgp::crypto::KeyPair;
use openpgp::parse::Parse;
let (mut tpk, _) = TPKBuilder::new()
    .set_cipher_suite(CipherSuite::Cv25519)
    .generate()?;
assert_eq!(RevocationStatus::NotAsFarAsWeKnow,
           tpk.revoked(None));

let mut keypair = tpk.primary().clone()
    .mark_parts_secret().into_keypair()?;
let tpk = tpk.revoke_in_place(&mut keypair,
                              ReasonForRevocation::KeyCompromised,
                              b"It was the maid :/")?;
if let RevocationStatus::Revoked(sigs) = tpk.revoked(None) {
    assert_eq!(sigs.len(), 1);
    assert_eq!(sigs[0].typ(), SignatureType::KeyRevocation);
    assert_eq!(sigs[0].reason_for_revocation(),
               Some((ReasonForRevocation::KeyCompromised,
                     "It was the maid :/".as_bytes())));
} else {
    unreachable!()
}

pub fn expired<T>(&self, t: T) -> bool where
    T: Into<Option<Tm>>, 
[src]

Returns whether or not the TPK is expired at t.

pub fn alive<T>(&self, t: T) -> bool where
    T: Into<Option<Tm>>, 
[src]

Returns whether or not the TPK is alive at t.

pub fn set_expiry<R>(
    self,
    primary_signer: &mut dyn Signer<R>,
    expiration: Option<Duration>
) -> Result<TPK> where
    R: KeyRole
[src]

Sets the key to expire in delta.

Note: the time is relative to the key's creation time, not the current time!

pub fn userids(&self) -> UserIDBindingIter[src]

Returns an iterator over the TPK's UserIDBindings.

pub fn user_attributes(&self) -> UserAttributeBindingIter[src]

Returns an iterator over the TPK's valid UserAttributeBindings.

A valid UserIDAttributeBinding has at least one good self-signature.

pub fn subkeys(&self) -> KeyBindingIter<PublicParts, SubordinateRole>[src]

Returns an iterator over the TPK's valid subkeys.

A valid KeyBinding has at least one good self-signature.

pub fn unknowns(&self) -> UnknownBindingIter[src]

Returns an iterator over the TPK's valid unknown components.

A valid UnknownBinding has at least one good self-signature.

pub fn bad_signatures(&self) -> &[Signature][src]

Returns a slice containing all bad signatures.

Bad signatures are signatures that we could not associate with one of the components.

Important traits for KeyIter<'a, P, R>
pub fn keys_valid(&self) -> KeyIter<PublicParts, UnspecifiedRole>[src]

Returns an iterator over the TPK's valid keys (live and not-revoked).

That is, this returns an iterator over the primary key and any subkeys, along with the corresponding signatures.

Note: since a primary key is different from a binding, the iterator is over Keys and not KeyBindings. Furthermore, the primary key has no binding signature. Here, the signature carrying the primary key's key flags is returned. There are corner cases where no such signature exists (e.g. partial TPKs), therefore this iterator may return None for the primary key's signature.

A valid Key has at least one good self-signature.

To return all keys, do keys_all().unfiltered(). See the documentation of keys for how to control what keys are returned.

Important traits for KeyIter<'a, P, R>
pub fn keys_all(&self) -> KeyIter<PublicParts, UnspecifiedRole>[src]

Returns an iterator over the TPK's keys.

Unlike TPK::keys_valid(), this iterator also returns expired and revoked keys.

pub fn from_packet_parser(ppr: PacketParserResult) -> Result<Self>[src]

Returns the TPK found in the packet stream.

If there are more packets after the TPK, e.g. because the packet stream is a keyring, this function will return Error::MalformedTPK.

pub fn from_packet_pile(p: PacketPile) -> Result<Self>[src]

Returns the first TPK found in the PacketPile.

pub fn fingerprint(&self) -> Fingerprint[src]

Returns the TPK's fingerprint.

pub fn keyid(&self) -> KeyID[src]

Returns the TPK's keyid.

pub fn into_packets(self) -> impl Iterator<Item = Packet>[src]

Converts the TPK into an iterator over a sequence of packets.

This method discards invalid components and bad signatures.

pub fn into_packet_pile(self) -> PacketPile[src]

Converts the TPK into a PacketPile.

This method discards invalid components and bad signatures.

pub fn merge(self, other: TPK) -> Result<Self>[src]

Merges other into self.

If other is a different key, then an error is returned.

pub fn merge_packets(self, packets: Vec<Packet>) -> Result<Self>[src]

Adds packets to the TPK.

This recanonicalizes the TPK. If the packets are invalid, they are dropped.

pub fn is_tsk(&self) -> bool[src]

Returns whether at least one of the keys includes a secret part.

impl TPK[src]

pub fn as_tsk<'a>(&'a self) -> TSK<'a>[src]

Derive a TSK object from this key.

This object writes out secret keys during serialization.

impl TPK[src]

pub fn armor_headers(&self) -> Vec<String>[src]

Creates descriptive armor headers.

Returns armor headers that describe this TPK. The TPK's primary fingerprint and userids are included as comments, so that it is easier to identify the TPK when looking at the armored data.

pub fn armored<'a>(&'a self) -> impl Serialize + SerializeInto + 'a[src]

Wraps this TPK in an armor structure when serialized.

Derives an object from this TPK that adds an armor structure to the serialized TPK when it is serialized. Additionally, the TPK's userids are added as comments, so that it is easier to identify the TPK when looking at the armored data.

Example

use sequoia_openpgp as openpgp;
use openpgp::tpk;
use openpgp::serialize::SerializeInto;

let (tpk, _) =
    tpk::TPKBuilder::general_purpose(None, Some("Mr. Pink ☮☮☮"))
    .generate()?;
let armored = String::from_utf8(tpk.armored().to_vec()?)?;

assert!(armored.starts_with("-----BEGIN PGP PUBLIC KEY BLOCK-----"));
assert!(armored.contains("Mr. Pink ☮☮☮"));

Trait Implementations

impl Serialize for TPK[src]

impl SerializeInto for TPK[src]

fn to_vec(&self) -> Result<Vec<u8>>[src]

Serializes the packet to a vector.

fn export_to_vec(&self) -> Result<Vec<u8>>[src]

Exports to a vector. Read more

impl<'a> Parse<'a, TPK> for TPK[src]

fn from_reader<R: Read>(reader: R) -> Result<Self>[src]

Returns the first TPK encountered in the reader.

fn from_file<P: AsRef<Path>>(path: P) -> Result<Self>[src]

Returns the first TPK encountered in the file.

fn from_bytes<D: AsRef<[u8]> + ?Sized>(data: &'a D) -> Result<Self>[src]

Returns the first TPK found in buf.

buf must be an OpenPGP-encoded message.

impl PartialEq<TPK> for TPK[src]

impl Clone for TPK[src]

fn clone_from(&mut self, source: &Self)
1.0.0
[src]

Performs copy-assignment from source. Read more

impl Display for TPK[src]

impl Debug for TPK[src]

impl FromStr for TPK[src]

type Err = Error

The associated error which can be returned from parsing.

Auto Trait Implementations

impl Send for TPK

impl Sync for TPK

Blanket Implementations

impl<T> From for T[src]

impl<T, U> Into for T where
    U: From<T>, 
[src]

impl<T> ToOwned for T where
    T: Clone
[src]

type Owned = T

impl<T> ToString for T where
    T: Display + ?Sized
[src]

impl<T, U> TryFrom for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T> Borrow for T where
    T: ?Sized
[src]

impl<T> BorrowMut for T where
    T: ?Sized
[src]

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T, U> TryInto for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.

impl<V, T> VZip for T where
    V: MultiLane<T>,