Module sequoia_openpgp::serialize

Packet serialization infrastructure.

OpenPGP defines a binary representation suitable for storing and communicating OpenPGP data structures (see Section 3 ff. of RFC 4880). Serialization is the process of creating the binary representation.

There are two interfaces to serialize OpenPGP data. Which one is applicable depends on whether or not the packet structure is already assembled in memory, with all information already in place (e.g. because it was previously parsed).

If it is, you can use the Serialize or SerializeInto trait. Otherwise, please use our streaming serialization interface.

Streaming serialization

The streaming serialization interface is the preferred way to create OpenPGP messages (see Section 11.3 of RFC 4880). It is ergonomic, yet flexible enough to accommodate most use cases. It requires little buffering, minimizing the memory footprint of the operation.

This example demonstrates how to create the simplest possible OpenPGP message (see Section 11.3 of RFC 4880) containing just a literal data packet (see Section 5.9 of RFC 4880):

use std::io::Write;
use sequoia_openpgp as openpgp;
use openpgp::serialize::stream::{Message, LiteralWriter};

let mut o = vec![];
{
    let message = Message::new(&mut o);
    let mut w = LiteralWriter::new(message).build()?;
    w.write_all(b"Hello world.")?;
    w.finalize()?;
}
assert_eq!(b"\xcb\x12b\x00\x00\x00\x00\x00Hello world.", o.as_slice());

For a more complete example, see the streaming examples.

Serializing objects

The traits Serialize and SerializeInto provide a mechanism to serialize OpenPGP data structures. Serialize writes to io::Writers, while SerializeInto writes into pre-allocated buffers, computes the size of the serialized representation, and provides a convenient method to create byte vectors with the serialized form.

To prevent accidentally serializing data structures that are not commonly exchanged between OpenPGP implementations, Serialize and SerializeInto is only implemented for types like Packet, Cert, and Message, but not for packet bodies like Signature.

This example demonstrates how to serialize a literal data packet (see Section 5.9 of RFC 4880):

use sequoia_openpgp as openpgp;
use openpgp::packet::{Literal, Packet};
use openpgp::serialize::{Serialize, SerializeInto};

let mut l = Literal::default();
l.set_body(b"Hello world.".to_vec());

// Add packet framing.
let p = Packet::from(l);

// Using Serialize.
let mut b = vec![];
p.serialize(&mut b)?;
assert_eq!(b"\xcb\x12b\x00\x00\x00\x00\x00Hello world.", b.as_slice());

// Using SerializeInto.
let b = p.to_vec()?;
assert_eq!(b"\xcb\x12b\x00\x00\x00\x00\x00Hello world.", b.as_slice());

Marshalling objects

The traits Marshal and MarshalInto provide a mechanism to serialize all OpenPGP data structures in this crate, even those not commonly interchanged between OpenPGP implementations. For example, it allows the serialization of unframed packet bodies:

use sequoia_openpgp as openpgp;
use openpgp::packet::Literal;
use openpgp::serialize::{Marshal, MarshalInto};

let mut l = Literal::default();
l.set_body(b"Hello world.".to_vec());

// Using Marshal.
let mut b = vec![];
l.serialize(&mut b)?;
assert_eq!(b"b\x00\x00\x00\x00\x00Hello world.", b.as_slice());

// Using MarshalInto.
let b = l.to_vec()?;
assert_eq!(b"b\x00\x00\x00\x00\x00Hello world.", b.as_slice());

Modules

• stream
  Streaming packet serialization.

Structs

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

Traits

• Marshal
  Serializes OpenPGP data structures.
• MarshalInto
  Serializes OpenPGP data structures into pre-allocated buffers.
• Serialize
  Serializes OpenPGP data structures.
• SerializeInto
  Serializes OpenPGP data structures into pre-allocated buffers.