Struct sequoia_openpgp::serialize::TSK

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

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

impl<'a> TSK<'a>

pub fn set_filter<P>(self, predicate: P) -> Self where
    P: 'a + Fn(&'a 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);

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);

impl<'a> TSK<'a>

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 ☮☮☮"));

Trait Implementations

impl<'a> Marshal for TSK<'a>

fn serialize(&self, o: &mut dyn Write) -> Result<()>

Writes a serialized version of the object to o.

fn export(&self, o: &mut dyn Write) -> Result<()>

Exports a serialized version of the object to o.

impl<'a> MarshalInto for TSK<'a>

fn serialized_len(&self) -> usize

Computes the maximal length of the serialized representation.

fn serialize_into(&self, buf: &mut [u8]) -> Result<usize>

Serializes into the given buffer.

fn export_into(&self, buf: &mut [u8]) -> Result<usize>

Exports into the given buffer.

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

Serializes the packet to a vector.

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

Exports to a vector.

impl<'a> Serialize for TSK<'a>

fn serialize(&self, o: &mut dyn Write) -> Result<()>

Writes a serialized version of the object to o.

fn export(&self, o: &mut dyn Write) -> Result<()>

Exports a serialized version of the object to o.

impl<'a> SerializeInto for TSK<'a>

fn serialized_len(&self) -> usize

Computes the maximal length of the serialized representation.

fn serialize_into(&self, buf: &mut [u8]) -> Result<usize>

Serializes into the given buffer.

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

Serializes the packet to a vector.

fn export_into(&self, buf: &mut [u8]) -> Result<usize>

Exports into the given buffer.

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

Exports to a vector.