[][src]Struct sequoia_openpgp::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. User IDs are sorted so that the first UserID is the primary User ID. 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) -> &Key[src]

Returns a reference to the primary key.

pub fn primary_key_signature_full(
    &self
) -> Option<(Option<&UserIDBinding>, &Signature)>
[src]

Returns the primary key's current self-signature and, if it belong to a user id, a reference to the UserIDBinding.

Normally, the primary key's current self-signature is the primary user id's newest, non-revoked self-signature. However, if all user ids are revoked and there is a direct signature, that is returned. If there is no direct signature, then we return the newest self-signature on the most recently revoked user id (i.e., the binding signature that was last valid). If there are no user ids at all and no direct signatures, then we return None.

pub fn primary_key_signature(&self) -> Option<&Signature>[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 selfsigs(&self) -> &[Signature][src]

The self-signatures.

All self-signatures have been validated, and the newest self-signature is last.

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

Any third-party certifications.

The signatures have not been validated.

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

Revocations issued by the key itself.

The revocations have been validated, and the newest is last.

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

Revocations issued by other keys.

The revocations have not been validated.

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

Returns the TPK's revocation status at the specified time.

Note: this only returns whether the primary key is revoked. If you want to know whether a subkey, user id, etc., is revoked, then you need to query them separately.

pub fn revocation_status(&self) -> RevocationStatus[src]

Returns the TPK's current revocation status.

Note: this only returns whether the primary key is revoked. If you want to know whether a subkey, user id, etc., is revoked, then you need to query them separately.

pub fn revoke(
    &self,
    primary_signer: &mut dyn Signer,
    code: ReasonForRevocation,
    reason: &[u8]
) -> Result<Signature>
[src]

Returns a revocation certificate for the TPK.

Example

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

let mut keypair = tpk.primary().clone().into_keypair()?;
let sig = tpk.revoke(&mut keypair, ReasonForRevocation::KeyCompromised,
                     b"It was the maid :/")?;
assert_eq!(sig.sigtype(), SignatureType::KeyRevocation);

let tpk = tpk.merge_packets(vec![sig.clone().into()])?;
assert_eq!(RevocationStatus::Revoked(&[sig]),
           tpk.revocation_status());

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

Revokes the TPK.

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.revocation_status());

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

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

Returns whether or not the TPK has expired.

pub fn expired_at(&self, tm: Tm) -> bool[src]

Returns whether or not the key is expired at the given time.

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

Returns whether or not the TPK is alive.

pub fn alive_at(&self, tm: Tm) -> bool[src]

Returns whether or not the key is alive at the given time.

pub fn set_expiry(
    self,
    primary_signer: &mut dyn Signer,
    expiration: Option<Duration>
) -> Result<TPK>
[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 valid UserIDBindings.

The primary user id is returned first. A valid UserIDBinding has at least one good self-signature.

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) -> SubkeyBindingIter[src]

Returns an iterator over the TPK's valid subkeys.

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

pub fn keys_valid(&self) -> KeyIter[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 SubkeyBindings. 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.

pub fn keys_all(&self) -> KeyIter[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 first TPK found in the packet stream.

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) -> Vec<Packet>[src]

Converts the TPK into a sequence of packets.

This method discards an invalid components and bad signatures.

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

Converts the TPK into a PacketPile.

This method discards an 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 nothing is merged into self, but self is still canonicalized.

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.

Trait Implementations

impl Clone for TPK[src]

impl Debug for TPK[src]

impl Display for TPK[src]

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(buf: &[u8]) -> Result<Self>[src]

Returns the first TPK found in buf.

buf must be an OpenPGP-encoded message.

impl PartialEq<TPK> for TPK[src]

impl Serialize for TPK[src]

impl SerializeInto for TPK[src]

impl StructuralPartialEq for TPK[src]

Auto Trait Implementations

impl !RefUnwindSafe for TPK

impl Send for TPK

impl !Sync for TPK

impl Unpin for TPK

impl !UnwindSafe for TPK

Blanket Implementations

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

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

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

impl<T> From<T> for T[src]

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

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

type Owned = T

The resulting type after obtaining ownership.

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

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

type Error = Infallible

The type returned in the event of a conversion error.

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

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

The type returned in the event of a conversion error.