Struct sequoia_openpgp::serialize::TSK

source ·

pub struct TSK<'a> { /* private fields */ }

Expand description

A reference to a Cert that allows serialization of secret keys.

To avoid accidental leakage, secret keys are not serialized when a serializing a Cert. To serialize Certs with secret keys, use Cert::as_tsk() to create a TSK, which is a shim on top of the Cert, and serialize this.

§Examples

let (cert, _) = CertBuilder::new().generate()?;
assert!(cert.is_tsk());

let mut buf = Vec::new();
cert.as_tsk().serialize(&mut buf)?;

let cert_ = Cert::from_bytes(&buf)?;
assert!(cert_.is_tsk());
assert_eq!(cert, cert_);

Implementations§

source §

impl<'a> TSK<'a>

source

pub fn into_packets(self) -> impl Iterator<Item = Packet> + 'a

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

This function emits secret key packets, modulo the keys that are filtered (see TSK::set_filter). If requested, missing secret key material is replaced by stubs (see TSK::emit_secret_key_stubs.

§Examples

assert!(cert.is_tsk());
let a = cert.as_tsk().to_vec()?;
let mut b = Vec::new();
cert.into_tsk().into_packets()
    .for_each(|p| p.serialize(&mut b).unwrap());
assert_eq!(a, b);

source §

impl<'a> TSK<'a>

source

pub fn set_filter(self, predicate: P) -> Self
where P: 'a + Fn(&Key<SecretParts, UnspecifiedRole>) -> bool,

Filters which secret keys to export using the given predicate.

Note that the given filter replaces any existing filter.

§Examples

This example demonstrates how to create a TSK with a detached primary secret key.

use sequoia_openpgp::policy::StandardPolicy;

let p = &StandardPolicy::new();

let (cert, _) = CertBuilder::new().add_signing_subkey().generate()?;
assert_eq!(cert.keys().with_policy(p, None).alive().revoked(false).secret().count(), 2);

// Only write out the subkey's secret.
let mut buf = Vec::new();
cert.as_tsk()
    .set_filter(|k| k.fingerprint() != cert.fingerprint())
    .serialize(&mut buf)?;

let cert_ = Cert::from_bytes(&buf)?;
assert!(! cert_.primary_key().has_secret());
assert_eq!(cert_.keys().with_policy(p, None).alive().revoked(false).secret().count(), 1);

source

pub fn emit_secret_key_stubs(self, emit_stubs: bool) -> Self

Changes TSK to emit secret key stubs.

If TSK::set_filter is used to selectively export secret keys, or if the cert contains both keys without secret key material and with secret key material, then are two ways to serialize this cert. Neither is sanctioned by the OpenPGP standard.

The default way is to simply emit public key packets when no secret key material is available. While straight forward, this may be in violation of Section 11.2 of RFC 4880.

The alternative is to emit a secret key packet with a placeholder secret key value. GnuPG uses this variant with a private S2K format. If interoperability with GnuPG is a concern, use this variant.

See this test for support in other implementations.

§Examples

This example demonstrates how to create a TSK with a detached primary secret key, serializing it using secret key stubs.

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

let p = &openpgp::policy::StandardPolicy::new();

let (cert, _) = CertBuilder::new().add_signing_subkey().generate()?;
assert_eq!(cert.keys().with_policy(p, None)
           .alive().revoked(false).unencrypted_secret().count(), 2);

// Only write out the subkey's secret, the primary key is "detached".
let mut buf = Vec::new();
cert.as_tsk()
    .set_filter(|k| k.fingerprint() != cert.fingerprint())
    .emit_secret_key_stubs(true)
    .serialize(&mut buf)?;

let cert_ = Cert::from_bytes(&buf)?;
// The primary key has an "encrypted" stub.
assert!(cert_.primary_key().has_secret());
assert_eq!(cert_.keys().with_policy(p, None)
           .alive().revoked(false).unencrypted_secret().count(), 1);

source §

impl<'a> TSK<'a>

source

pub fn armored(self) -> impl Serialize + SerializeInto + 'a

Wraps this TSK in an armor structure when serialized.

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

§Examples

use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::serialize::SerializeInto;

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

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