Trait sequoia_openpgp::serialize::Serialize

source · 
pub trait Serialize: Marshal {
    // Provided methods
    fn serialize(&self, o: &mut dyn Write) -> Result<()> { ... }
    fn export(&self, o: &mut dyn Write) -> Result<()> { ... }
}
Expand description

Serializes OpenPGP data structures.

This trait provides the same interface as the Marshal trait (in fact, it is just a wrapper around that trait), but only data structures that it makes sense to export implement it.

Having a separate trait for data structures that it makes sense to export avoids an easy-to-make and hard-to-debug bug: inadvertently exporting an OpenPGP data structure without any framing information.

This bug is easy to make, because Rust infers types, which means that it is often not clear from the immediate context exactly what is being serialized. This bug is hard to debug, because errors parsing data that has been incorrectly exported, are removed from the serialization code.

The following example shows how to correctly export a revocation certificate. It should make clear how easy it is to forget to convert a bare signature into an OpenPGP packet before serializing it:

use openpgp::cert::prelude::*;
use openpgp::Packet;
use openpgp::serialize::Serialize;

let (_cert, rev) =
    CertBuilder::general_purpose(None, Some("alice@example.org"))
    .generate()?;
let rev : Packet = rev.into();
rev.serialize(output)?;

Note: if you use both Serialize and Marshal, then, because they both have the same methods, and all data structures that implement Serialize also implement Marshal, you will have to use the Universal Function Call Syntax (UFCS) to call the methods on those objects, for example:

Serialize::serialize(&rev, output)?;

If you really needed Marshal, we strongly recommend importing it in as small a scope as possible to avoid this, and to avoid accidentally exporting data without the required framing.

Provided Methods§

source

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

Writes a serialized version of the object to o.

source

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

Exports a serialized version of the object to o.

This is similar to serialize(..), with these exceptions:

  • It is an error to export a Signature if it is marked as non-exportable.
  • When exporting a Cert, non-exportable signatures are not exported, and any component bound merely by non-exportable signatures is not exported.

Implementors§