Struct sequoia_openpgp::parse::PacketParserBuilder

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

A builder for configuring a PacketParser.

Since the default settings are usually appropriate, this mechanism will only be needed in exceptional circumstances. Instead use, for instance, PacketParser::from_file or PacketParser::from_reader to start parsing an OpenPGP message.

Examples

use sequoia_openpgp as openpgp;
use openpgp::parse::{Parse, PacketParserResult, PacketParserBuilder};

// Parse a message.
let message_data: &[u8] = // ...
let mut ppr = PacketParserBuilder::from_bytes(message_data)?
    // Customize the `PacketParserBuilder` here.
    .build()?;
while let PacketParserResult::Some(mut pp) = ppr {
    // ...

    // Start parsing the next packet, recursing.
    ppr = pp.recurse()?.1;
}

Implementations

impl<'a> PacketParserBuilder<'a>

pub fn max_recursion_depth(self, value: u8) -> Self

Sets the maximum recursion depth.

Setting this to 0 means that the PacketParser will never recurse; it will only parse the top-level packets.

This is a u8, because recursing more than 255 times makes no sense. The default is DEFAULT_MAX_RECURSION_DEPTH. (GnuPG defaults to a maximum recursion depth of 32.)

Examples

use sequoia_openpgp as openpgp;
use openpgp::Packet;
use openpgp::parse::{Parse, PacketParserResult, PacketParserBuilder};

// Parse a compressed message.
let message_data: &[u8] = // ...
let mut ppr = PacketParserBuilder::from_bytes(message_data)?
    .max_recursion_depth(0)
    .build()?;
while let PacketParserResult::Some(mut pp) = ppr {
    assert_eq!(pp.recursion_depth(), 0);

    // Start parsing the next packet, recursing.
    ppr = pp.recurse()?.1;
}

pub fn max_packet_size(self, value: u32) -> Self

Sets the maximum size in bytes of non-container packets.

Packets that exceed this limit will be returned as Packet::Unknown, with the error set to Error::PacketTooLarge.

This limit applies to any packet type that is not a container packet, i.e. any packet that is not a literal data packet, a compressed data packet, a symmetrically encrypted data packet, or an AEAD encrypted data packet.

The default is DEFAULT_MAX_PACKET_SIZE.

Examples

use sequoia_openpgp as openpgp;
use openpgp::{Error, Packet};
use openpgp::packet::Tag;
use openpgp::parse::{Parse, PacketParserResult, PacketParserBuilder};
use openpgp::serialize::MarshalInto;

// Parse a signed message.
let message_data: &[u8] = // ...
let mut ppr = PacketParserBuilder::from_bytes(message_data)?
    .max_packet_size(256)    // Only parse 256 bytes of headers.
    .buffer_unread_content() // Used below.
    .build()?;
while let PacketParserResult::Some(mut pp) = ppr {
    match &pp.packet {
        Packet::OnePassSig(p) =>
            // The OnePassSig packet was small enough.
            assert!(p.serialized_len() < 256),
        Packet::Literal(p) =>
            // Likewise the `Literal` packet, excluding the body.
            assert!(p.serialized_len() - p.body().len() < 256),
        Packet::Unknown(p) =>
            // The signature packet was too big.
            assert_eq!(
                &Error::PacketTooLarge(Tag::Signature, 307, 256),
                p.error().downcast_ref().unwrap()),
        _ => unreachable!(),
    }

    // Start parsing the next packet, recursing.
    ppr = pp.recurse()?.1;
}

pub fn buffer_unread_content(self) -> Self

Causes PacketParser::build() to buffer any unread content.

The unread content can be accessed using Literal::body, Unknown::body, or Container::body.

Examples

use sequoia_openpgp as openpgp;
use openpgp::Packet;
use openpgp::parse::{Parse, PacketParserResult, PacketParserBuilder};

// Parse a simple message.
let message_data = b"\xcb\x12t\x00\x00\x00\x00\x00Hello world.";
let mut ppr = PacketParserBuilder::from_bytes(message_data)?
    .buffer_unread_content()
    .build()?;
while let PacketParserResult::Some(mut pp) = ppr {
    // Start parsing the next packet, recursing.
    let (packet, tmp) = pp.recurse()?;
    ppr = tmp;

    match packet {
        Packet::Literal(l) => assert_eq!(l.body(), b"Hello world."),
        _ => unreachable!(),
    }
}

pub fn drop_unread_content(self) -> Self

Causes PacketParser::finish() to drop any unread content.

This is the default.

Examples

use sequoia_openpgp as openpgp;
use openpgp::Packet;
use openpgp::parse::{Parse, PacketParserResult, PacketParserBuilder};

// Parse a simple message.
let message_data = b"\xcb\x12t\x00\x00\x00\x00\x00Hello world.";
let mut ppr = PacketParserBuilder::from_bytes(message_data)?
    .drop_unread_content()
    .build()?;
while let PacketParserResult::Some(mut pp) = ppr {
    // Start parsing the next packet, recursing.
    let (packet, tmp) = pp.recurse()?;
    ppr = tmp;

    match packet {
        Packet::Literal(l) => assert_eq!(l.body(), b""),
        _ => unreachable!(),
    }
}

pub fn map(self, enable: bool) -> Self

Controls mapping.

Note that enabling mapping buffers all the data.

Examples

use sequoia_openpgp as openpgp;
use openpgp::parse::{Parse, PacketParserBuilder};

let message_data = b"\xcb\x12t\x00\x00\x00\x00\x00Hello world.";
let pp = PacketParserBuilder::from_bytes(message_data)?
    .map(true) // Enable mapping.
    .build()?
    .expect("One packet, not EOF");
let map = pp.map().expect("Mapping is enabled");

assert_eq!(map.iter().nth(0).unwrap().name(), "CTB");
assert_eq!(map.iter().nth(0).unwrap().offset(), 0);
assert_eq!(map.iter().nth(0).unwrap().as_bytes(), &[0xcb]);

pub fn dearmor(self, mode: Dearmor) -> Self

Controls dearmoring.

By default, if the input does not appear to be plain binary OpenPGP data, we assume that it is ASCII-armored. This method can be used to tweak the behavior. See Dearmor for details.

Examples

use sequoia_openpgp as openpgp;
use openpgp::parse::{Parse, PacketParserBuilder, Dearmor};

let message_data = b"\xcb\x12t\x00\x00\x00\x00\x00Hello world.";
let pp = PacketParserBuilder::from_bytes(message_data)?
    .dearmor(Dearmor::Disabled) // Disable dearmoring.
    .build()?
    .expect("One packet, not EOF");

pub fn automatic_hashing(self, enable: bool) -> Self

Controls automatic hashing.

When encountering a OnePassSig packet, the packet parser will, by default, start hashing later packets using the hash algorithm specified in the packet. In some cases, this is not needed, and hashing will incur a non-trivial overhead.

If automatic hashing is disabled, then hashing may be explicitly enabled using PacketParser::start_hashing while parsing each OnePassSig packet.

Examples

let message_data = b"\xcb\x12t\x00\x00\x00\x00\x00Hello world.";
let pp = PacketParserBuilder::from_bytes(message_data)?
    .automatic_hashing(false) // Disable automatic hashing.
    .build()?
    .expect("One packet, not EOF");

pub fn build(self) -> Result<PacketParserResult<'a>> where
    Self: 'a, 

Builds the PacketParser.

Examples

use sequoia_openpgp as openpgp;
use openpgp::parse::{Parse, PacketParserResult, PacketParserBuilder};

// Parse a message.
let message_data: &[u8] = // ...
let mut ppr = PacketParserBuilder::from_bytes(message_data)?
    // Customize the `PacketParserBuilder` here.
    .build()?;
while let PacketParserResult::Some(mut pp) = ppr {
    // ...

    // Start parsing the next packet, recursing.
    ppr = pp.recurse()?.1;
}

impl<'a> PacketParserBuilder<'a>

pub fn into_packet_pile(self) -> Result<PacketPile>

Finishes configuring the PacketParser and returns a fully parsed message.

Note: calling this function does not change the default settings. Thus, by default, the content of packets will not be buffered.

Note: to avoid denial of service attacks, the PacketParser interface should be preferred unless the size of the message is known to fit in memory.

Examples

let message = PacketParserBuilder::from_bytes(message_data)?
    .buffer_unread_content()
    .into_packet_pile()?;

Trait Implementations

impl<'a> Parse<'a, PacketParserBuilder<'a>> for PacketParserBuilder<'a>

fn from_reader<R: Read + 'a + Send + Sync>(reader: R) -> Result<Self>

Creates a PacketParserBuilder for an OpenPGP message stored in a std::io::Read object.

fn from_file<P: AsRef<Path>>(path: P) -> Result<Self>

Creates a PacketParserBuilder for an OpenPGP message stored in the file named path.

fn from_bytes<D: AsRef<[u8]> + ?Sized>(
    data: &'a D
) -> Result<PacketParserBuilder<'a>>

Creates a PacketParserBuilder for an OpenPGP message stored in the specified buffer.

impl<'a> TryFrom<PacketParserBuilder<'a>> for PacketPileParser<'a>

fn try_from(ppb: PacketParserBuilder<'a>) -> Result<PacketPileParser<'a>>

Finishes configuring the PacketParser and returns a PacketPileParser.

type Error = Error

The type returned in the event of a conversion error.