Struct sequoia_openpgp::parse::PacketParserBuilder

source ·
pub struct PacketParserBuilder<'a> { /* private fields */ }
Expand description

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§

source§

impl<'a> PacketParserBuilder<'a>

source

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;
}
source

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;
}
source

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!(),
    }
}
source

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!(),
    }
}
source

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

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

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

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;
}
source§

impl<'a> PacketParserBuilder<'a>

source

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§

source§

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

source§

fn from_buffered_reader<R>(reader: R) -> Result<PacketParserBuilder<'a>>
where R: BufferedReader<Cookie> + 'a,

Starts parsing an OpenPGP object stored in a BufferedReader object.

This function returns a PacketParser for the first packet in the stream.

source§

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.

source§

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

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

source§

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.

source§

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

source§

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.

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> Same for T

§

type Output = T

Should always be Self
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> ErasedDestructor for T
where T: 'static,

source§

impl<T> MaybeSendSync for T