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
sourceimpl<'a> PacketParserBuilder<'a>
impl<'a> PacketParserBuilder<'a>
sourcepub fn max_recursion_depth(self, value: u8) -> Self
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;
}
sourcepub fn max_packet_size(self, value: u32) -> Self
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;
}
sourcepub fn buffer_unread_content(self) -> Self
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!(),
}
}
sourcepub fn drop_unread_content(self) -> Self
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!(),
}
}
sourcepub fn map(self, enable: bool) -> Self
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]);
sourcepub fn dearmor(self, mode: Dearmor) -> Self
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");
sourcepub fn build(self) -> Result<PacketParserResult<'a>> where
Self: 'a,
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;
}
sourceimpl<'a> PacketParserBuilder<'a>
impl<'a> PacketParserBuilder<'a>
sourcepub fn into_packet_pile(self) -> Result<PacketPile>
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
sourceimpl<'a> Parse<'a, PacketParserBuilder<'a>> for PacketParserBuilder<'a>
impl<'a> Parse<'a, PacketParserBuilder<'a>> for PacketParserBuilder<'a>
sourcefn from_reader<R: Read + 'a + Send + Sync>(reader: R) -> Result<Self>
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.
sourcefn from_file<P: AsRef<Path>>(path: P) -> Result<Self>
fn from_file<P: AsRef<Path>>(path: P) -> Result<Self>
Creates a PacketParserBuilder
for an OpenPGP message stored
in the file named path
.
sourcefn from_bytes<D: AsRef<[u8]> + ?Sized>(
data: &'a D
) -> Result<PacketParserBuilder<'a>>
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.
sourceimpl<'a> TryFrom<PacketParserBuilder<'a>> for PacketPileParser<'a>
impl<'a> TryFrom<PacketParserBuilder<'a>> for PacketPileParser<'a>
sourcefn try_from(ppb: PacketParserBuilder<'a>) -> Result<PacketPileParser<'a>>
fn try_from(ppb: PacketParserBuilder<'a>) -> Result<PacketPileParser<'a>>
Finishes configuring the PacketParser
and returns a
PacketPileParser
.
Auto Trait Implementations
impl<'a> !RefUnwindSafe for PacketParserBuilder<'a>
impl<'a> Send for PacketParserBuilder<'a>
impl<'a> Sync for PacketParserBuilder<'a>
impl<'a> Unpin for PacketParserBuilder<'a>
impl<'a> !UnwindSafe for PacketParserBuilder<'a>
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more