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 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.