[][src]Struct sequoia_openpgp::parse::PacketParser

pub struct PacketParser<'a> {
    pub packet: Packet,
    // some fields omitted
}

A low-level OpenPGP message parser.

A PacketParser provides a low-level, iterator-like interface to parse OpenPGP messages.

For each iteration, the user is presented with a Packet corresponding to the last packet, a PacketParser for the next packet, and their positions within the message.

Using the PacketParser, the user is able to configure how the new packet will be parsed. For instance, it is possible to stream the packet's contents (a PacketParser implements the std::io::Read and the BufferedReader traits), buffer them within the Packet, or drop them. The user can also decide to recurse into the packet, if it is a container, instead of getting the following packet.

See the next() and recurse() methods for more details.

Examples

Parse an OpenPGP message using a PacketParser:

let mut ppr = PacketParser::from_bytes(message_data)?;
while let PacketParserResult::Some(mut pp) = ppr {
    // Process the packet.

    if let Packet::Literal(_) = pp.packet {
        // Stream the content of any literal packets to stdout.
        std::io::copy(&mut pp, &mut std::io::stdout());
    }

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

Fields

packet: Packet

The packet that is being parsed.

Methods

impl<'a> PacketParser<'a>[src]

pub fn decrypted(&self) -> bool[src]

Returns whether the packet's contents (packet.common.body) are decrypted.

pub fn last_path(&self) -> &[usize][src]

Returns the path of the last packet.

pub fn path(&self) -> &[usize][src]

Returns the path of the current packet.

pub fn recursion_depth(&self) -> isize[src]

The current packet's recursion depth.

A top-level packet has a recursion depth of 0. Packets in a top-level container have a recursion depth of 1, etc.

pub fn last_recursion_depth(&self) -> Option<isize>[src]

The last packet's recursion depth.

A top-level packet has a recursion depth of 0. Packets in a top-level container have a recursion depth of 1, etc.

Note: if no packet has been returned yet, this returns None.

pub fn possible_message(&self) -> Result<()>[src]

Returns whether the message appears to be an OpenPGP Message.

Only when the whole message has been processed is it possible to say whether the message is definitely an OpenPGP Message. Before that, it is only possible to say that the message is a valid prefix or definitely not an OpenPGP message.

pub fn possible_keyring(&self) -> Result<()>[src]

Returns whether the message appears to be an OpenPGP keyring.

Only when the whole message has been processed is it possible to say whether the message is definitely an OpenPGP keyring. Before that, it is only possible to say that the message is a valid prefix or definitely not an OpenPGP keyring.

pub fn possible_tpk(&self) -> Result<()>[src]

Returns whether the message appears to be an OpenPGP TPK.

Only when the whole message has been processed is it possible to say whether the message is definitely an OpenPGP TPK. Before that, it is only possible to say that the message is a valid prefix or definitely not an OpenPGP TPK.

pub fn next(self) -> Result<(Packet, PacketParserResult<'a>)>[src]

Finishes parsing the current packet and starts parsing the next one.

This function finishes parsing the current packet. By default, any unread content is dropped. (See PacketParsererBuilder for how to configure this.) It then creates a new packet parser for the next packet. If the current packet is a container, this function does not recurse into the container, but skips any packets it contains. To recurse into the container, use the recurse() method.

The return value is a tuple containing:

  • A Packet holding the fully processed old packet;

  • A PacketParser holding the new packet;

To determine the two packet's position within the parse tree, you can use last_path() and path(), respectively. To determine their depth, you can use last_recursion_depth() and recursion_depth(), respectively.

Note: A recursion depth of 0 means that the packet is a top-level packet, a recursion depth of 1 means that the packet is an immediate child of a top-level-packet, etc.

Since the packets are serialized in depth-first order and all interior nodes are visited, we know that if the recursion depth is the same, then the packets are siblings (they have a common parent) and not, e.g., cousins (they have a common grandparent). This is because, if we move up the tree, the only way to move back down is to first visit a new container (e.g., an aunt).

Using the two positions, we can compute the change in depth as new_depth - old_depth. Thus, if the change in depth is 0, the two packets are siblings. If the value is 1, the old packet is a container, and the new packet is its first child. And, if the value is -1, the new packet is contained in the old packet's grandparent. The idea is illustrated below:

            ancestor
            |       \
           ...      -n
            |
          grandparent
          |          \
        parent       -1
        |      \
     packet    0
        |
        1

Note: since this function does not automatically recurse into a container, the change in depth will always be non-positive. If the current container is empty, this function DOES pop that container off the container stack, and returns the following packet in the parent container.

pub fn recurse(self) -> Result<(Packet, PacketParserResult<'a>)>[src]

Finishes parsing the current packet and starts parsing the next one, recursing if possible.

This method is similar to the next() method (see that method for more details), but if the current packet is a container (and we haven't reached the maximum recursion depth, and the user hasn't started reading the packet's contents), we recurse into the container, and return a PacketParser for its first child. Otherwise, we return the next packet in the packet stream. If this function recurses, then the new packet's recursion depth will be last_recursion_depth() + 1; because we always visit interior nodes, we can't recurse more than one level at a time.

pub fn buffer_unread_content(&mut self) -> Result<&[u8]>[src]

Causes the PacketParser to buffer the packet's contents.

The packet's contents can be retrieved using packet.body(). In general, you should avoid buffering a packet's content and prefer streaming its content unless you are certain that the content is small.

let mut ppr = PacketParser::from_bytes(message_data)?;
while let PacketParserResult::Some(mut pp) = ppr {
    // Process the packet.

    if let Packet::Literal(_) = pp.packet {
        assert!(pp.buffer_unread_content()?
                    .starts_with(b"A Cypherpunk's Manifesto"));
        assert!(pp.packet.body().unwrap()
                    .starts_with(b"A Cypherpunk's Manifesto"));
        assert_eq!(pp.packet.body().unwrap().len(), 5158);
    }

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

pub fn finish<'b>(&'b mut self) -> Result<&'b Packet>[src]

Finishes parsing the current packet.

By default, this drops any unread content. Use, for instance, PacketParserBuild to customize the default behavior.

pub fn header(&self) -> &Header[src]

Returns a reference to the current packet's header.

pub fn map(&self) -> Option<&Map>[src]

Returns a reference to the map (if any is written).

pub fn take_map(&mut self) -> Option<Map>[src]

Takes the map (if any is written).

impl<'a> PacketParser<'a>[src]

pub fn decrypt(
    &mut self,
    algo: SymmetricAlgorithm,
    key: &SessionKey
) -> Result<()>
[src]

Tries to decrypt the current packet.

On success, this function pushes one or more readers onto the PacketParser's reader stack, and sets the packet's decrypted flag.

If this function is called on a packet that does not contain encrypted data, or some of the data was already read, then it returns Error::InvalidOperation.

Trait Implementations

impl<'a> Parse<'a, PacketParserResult<'a>> for PacketParser<'a>[src]

fn from_reader<R: Read + 'a>(reader: R) -> Result<PacketParserResult<'a>>[src]

Starts parsing an OpenPGP message stored in a std::io::Read object.

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

fn from_file<P: AsRef<Path>>(path: P) -> Result<PacketParserResult<'a>>[src]

Starts parsing an OpenPGP message stored in a file named path.

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

fn from_bytes(bytes: &'a [u8]) -> Result<PacketParserResult<'a>>[src]

Starts parsing an OpenPGP message stored in a buffer.

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

impl<'a> Display for PacketParser<'a>[src]

impl<'a> Debug for PacketParser<'a>[src]

impl<'a> Read for PacketParser<'a>[src]

This interface allows a caller to read the content of a PacketParser using the Read interface. This is essential to supporting streaming operation.

Note: it is safe to mix the use of the std::io::Read and BufferedReader interfaces.

fn read_vectored(&mut self, bufs: &mut [IoVecMut]) -> Result<usize, Error>[src]

🔬 This is a nightly-only experimental API. (iovec)

Like read, except that it reads into a slice of buffers. Read more

unsafe fn initializer(&self) -> Initializer[src]

🔬 This is a nightly-only experimental API. (read_initializer)

Determines if this Reader can work with buffers of uninitialized memory. Read more

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>
1.0.0
[src]

Read all bytes until EOF in this source, placing them into buf. Read more

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
1.0.0
[src]

Read all bytes until EOF in this source, appending them to buf. Read more

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
1.6.0
[src]

Read the exact number of bytes required to fill buf. Read more

fn by_ref(&mut self) -> &mut Self
1.0.0
[src]

Creates a "by reference" adaptor for this instance of Read. Read more

fn bytes(self) -> Bytes<Self>
1.0.0
[src]

Transforms this Read instance to an [Iterator] over its bytes. Read more

fn chain<R>(self, next: R) -> Chain<Self, R> where
    R: Read
1.0.0
[src]

Creates an adaptor which will chain this stream with another. Read more

fn take(self, limit: u64) -> Take<Self>
1.0.0
[src]

Creates an adaptor which will read at most limit bytes from it. Read more

Auto Trait Implementations

impl<'a> !Send for PacketParser<'a>

impl<'a> !Sync for PacketParser<'a>

Blanket Implementations

impl<T> From for T[src]

impl<T, U> Into for T where
    U: From<T>, 
[src]

impl<T> ToString for T where
    T: Display + ?Sized
[src]

impl<T, U> TryFrom for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T> Borrow for T where
    T: ?Sized
[src]

impl<T> BorrowMut for T where
    T: ?Sized
[src]

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T, U> TryInto for T where
    U: TryFrom<T>, 
[src]

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

The type returned in the event of a conversion error.

impl<R> ReadBytesExt for R where
    R: Read + ?Sized

fn read_u8(&mut self) -> Result<u8, Error>

Reads an unsigned 8 bit integer from the underlying reader. Read more

fn read_i8(&mut self) -> Result<i8, Error>

Reads a signed 8 bit integer from the underlying reader. Read more

fn read_u16<T>(&mut self) -> Result<u16, Error> where
    T: ByteOrder, 

Reads an unsigned 16 bit integer from the underlying reader. Read more

fn read_i16<T>(&mut self) -> Result<i16, Error> where
    T: ByteOrder, 

Reads a signed 16 bit integer from the underlying reader. Read more

fn read_u24<T>(&mut self) -> Result<u32, Error> where
    T: ByteOrder, 

Reads an unsigned 24 bit integer from the underlying reader. Read more

fn read_i24<T>(&mut self) -> Result<i32, Error> where
    T: ByteOrder, 

Reads a signed 24 bit integer from the underlying reader. Read more

fn read_u32<T>(&mut self) -> Result<u32, Error> where
    T: ByteOrder, 

Reads an unsigned 32 bit integer from the underlying reader. Read more

fn read_i32<T>(&mut self) -> Result<i32, Error> where
    T: ByteOrder, 

Reads a signed 32 bit integer from the underlying reader. Read more

fn read_u48<T>(&mut self) -> Result<u64, Error> where
    T: ByteOrder, 

Reads an unsigned 48 bit integer from the underlying reader. Read more

fn read_i48<T>(&mut self) -> Result<i64, Error> where
    T: ByteOrder, 

Reads a signed 48 bit integer from the underlying reader. Read more

fn read_u64<T>(&mut self) -> Result<u64, Error> where
    T: ByteOrder, 

Reads an unsigned 64 bit integer from the underlying reader. Read more

fn read_i64<T>(&mut self) -> Result<i64, Error> where
    T: ByteOrder, 

Reads a signed 64 bit integer from the underlying reader. Read more

fn read_u128<T>(&mut self) -> Result<u128, Error> where
    T: ByteOrder, 

Reads an unsigned 128 bit integer from the underlying reader. Read more

fn read_i128<T>(&mut self) -> Result<i128, Error> where
    T: ByteOrder, 

Reads a signed 128 bit integer from the underlying reader. Read more

fn read_uint<T>(&mut self, nbytes: usize) -> Result<u64, Error> where
    T: ByteOrder, 

Reads an unsigned n-bytes integer from the underlying reader. Read more

fn read_int<T>(&mut self, nbytes: usize) -> Result<i64, Error> where
    T: ByteOrder, 

Reads a signed n-bytes integer from the underlying reader. Read more

fn read_uint128<T>(&mut self, nbytes: usize) -> Result<u128, Error> where
    T: ByteOrder, 

Reads an unsigned n-bytes integer from the underlying reader.

fn read_int128<T>(&mut self, nbytes: usize) -> Result<i128, Error> where
    T: ByteOrder, 

Reads a signed n-bytes integer from the underlying reader.

fn read_f32<T>(&mut self) -> Result<f32, Error> where
    T: ByteOrder, 

Reads a IEEE754 single-precision (4 bytes) floating point number from the underlying reader. Read more

fn read_f64<T>(&mut self) -> Result<f64, Error> where
    T: ByteOrder, 

Reads a IEEE754 double-precision (8 bytes) floating point number from the underlying reader. Read more

fn read_u16_into<T>(&mut self, dst: &mut [u16]) -> Result<(), Error> where
    T: ByteOrder, 

Reads a sequence of unsigned 16 bit integers from the underlying reader. Read more

fn read_u32_into<T>(&mut self, dst: &mut [u32]) -> Result<(), Error> where
    T: ByteOrder, 

Reads a sequence of unsigned 32 bit integers from the underlying reader. Read more

fn read_u64_into<T>(&mut self, dst: &mut [u64]) -> Result<(), Error> where
    T: ByteOrder, 

Reads a sequence of unsigned 64 bit integers from the underlying reader. Read more

fn read_u128_into<T>(&mut self, dst: &mut [u128]) -> Result<(), Error> where
    T: ByteOrder, 

Reads a sequence of unsigned 128 bit integers from the underlying reader. Read more

fn read_i8_into(&mut self, dst: &mut [i8]) -> Result<(), Error>

Reads a sequence of signed 8 bit integers from the underlying reader. Read more

fn read_i16_into<T>(&mut self, dst: &mut [i16]) -> Result<(), Error> where
    T: ByteOrder, 

Reads a sequence of signed 16 bit integers from the underlying reader. Read more

fn read_i32_into<T>(&mut self, dst: &mut [i32]) -> Result<(), Error> where
    T: ByteOrder, 

Reads a sequence of signed 32 bit integers from the underlying reader. Read more

fn read_i64_into<T>(&mut self, dst: &mut [i64]) -> Result<(), Error> where
    T: ByteOrder, 

Reads a sequence of signed 64 bit integers from the underlying reader. Read more

fn read_i128_into<T>(&mut self, dst: &mut [i128]) -> Result<(), Error> where
    T: ByteOrder, 

Reads a sequence of signed 128 bit integers from the underlying reader. Read more

fn read_f32_into<T>(&mut self, dst: &mut [f32]) -> Result<(), Error> where
    T: ByteOrder, 

Reads a sequence of IEEE754 single-precision (4 bytes) floating point numbers from the underlying reader. Read more

fn read_f32_into_unchecked<T>(&mut self, dst: &mut [f32]) -> Result<(), Error> where
    T: ByteOrder, 

Deprecated since 1.2.0:

please use read_f32_into instead

DEPRECATED. Read more

fn read_f64_into<T>(&mut self, dst: &mut [f64]) -> Result<(), Error> where
    T: ByteOrder, 

Reads a sequence of IEEE754 double-precision (8 bytes) floating point numbers from the underlying reader. Read more

fn read_f64_into_unchecked<T>(&mut self, dst: &mut [f64]) -> Result<(), Error> where
    T: ByteOrder, 

Deprecated since 1.2.0:

please use read_f64_into instead

DEPRECATED. Read more