Struct sequoia_openpgp::parse::PacketParserBuilder[][src]

pub struct PacketParserBuilder<'a> { /* fields omitted */ }
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

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

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

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

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

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

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

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

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

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

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

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

Finishes configuring the PacketParser and returns a PacketPileParser.

The type returned in the event of a conversion error.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Performs the conversion.

Performs the conversion.

Should always be Self

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.