Struct sequoia_openpgp::PacketPile
source · pub struct PacketPile { /* private fields */ }
Expand description
An unstructured packet sequence.
To parse an OpenPGP packet stream into a PacketPile
, you can use
PacketParser
, PacketPileParser
, or
PacketPile::from_file
(or related routines).
You can also convert a Cert
into a PacketPile
using
PacketPile::from
. Unlike serializing a Cert
, this does not
drop any secret key material.
Normally, you’ll want to convert the PacketPile
to a Cert
or a
Message
.
Examples
This example shows how to modify packets in PacketPile using pathspec
s.
use std::convert::TryFrom;
use openpgp::{Packet, PacketPile};
use openpgp::packet::signature::Signature4;
use openpgp::packet::Signature;
use openpgp::cert::prelude::*;
use openpgp::parse::Parse;
use openpgp::serialize::Serialize;
use openpgp::policy::StandardPolicy;
use openpgp::crypto::mpi;
use openpgp::types::RevocationStatus;
let (cert, revocation) = CertBuilder::new().generate()?;
let mut buffer = Vec::new();
cert.serialize(&mut buffer)?;
let packet: Packet = revocation.into();
packet.serialize(&mut buffer)?;
let policy = &StandardPolicy::new();
// Certificate is considered revoked because it is accompanied with its
// revocation signature
let pp: PacketPile = PacketPile::from_bytes(&buffer)?;
let cert = Cert::try_from(pp)?;
if let RevocationStatus::Revoked(_) = cert.revocation_status(policy, None) {
// cert is considered revoked
}
// Breaking the revocation signature changes certificate's status
let mut pp: PacketPile = PacketPile::from_bytes(&buffer)?;
if let Some(Packet::Signature(ref mut sig)) = pp.path_ref_mut(&[2]) {
*sig = Signature4::new(
sig.typ(),
sig.pk_algo(),
sig.hash_algo(),
sig.hashed_area().clone(),
sig.unhashed_area().clone(),
*sig.digest_prefix(),
// MPI is replaced with a dummy one
mpi::Signature::RSA {
s: mpi::MPI::from(vec![1, 2, 3])
}).into();
}
let cert = Cert::try_from(pp)?;
if let RevocationStatus::NotAsFarAsWeKnow = cert.revocation_status(policy, None) {
// revocation signature is broken and the cert is not revoked
assert_eq!(cert.bad_signatures().count(), 1);
}
Implementations§
source§impl PacketPile
impl PacketPile
sourcepub fn pretty_print(&self)
pub fn pretty_print(&self)
Pretty prints the message to stderr.
This function is primarily intended for debugging purposes.
sourcepub fn path_ref(&self, pathspec: &[usize]) -> Option<&Packet>
pub fn path_ref(&self, pathspec: &[usize]) -> Option<&Packet>
Returns a reference to the packet at the location described by
pathspec
.
pathspec
is a slice of the form [0, 1, 2]
. Each element
is the index of packet in a container. Thus, the previous
path specification means: return the third child of the second
child of the first top-level packet. In other words, the
starred packet in the following tree:
PacketPile
/ | \
0 1 2 ...
/ \
/ \
0 1 ...
/ | \ ...
0 1 2
*
And, [10]
means return the 11th top-level packet.
Note: there is no packet at the root. Thus, the path []
returns None.
Examples
let pile = PacketPile::from(packets);
if let Some(packet) = pile.path_ref(&[0]) {
// There is a packet at this path.
}
if let None = pile.path_ref(&[0, 1, 2]) {
// But none here.
}
sourcepub fn path_ref_mut(&mut self, pathspec: &[usize]) -> Option<&mut Packet>
pub fn path_ref_mut(&mut self, pathspec: &[usize]) -> Option<&mut Packet>
Returns a mutable reference to the packet at the location
described by pathspec
.
See the description of the path_spec
for more details.
Examples
let mut pile = PacketPile::from(packets);
if let Some(ref packet) = pile.path_ref_mut(&[0]) {
// There is a packet at this path.
}
if let None = pile.path_ref_mut(&[0, 1, 2]) {
// But none here.
}
sourcepub fn replace(
&mut self,
pathspec: &[usize],
count: usize,
packets: Vec<Packet>
) -> Result<Vec<Packet>>
pub fn replace( &mut self, pathspec: &[usize], count: usize, packets: Vec<Packet> ) -> Result<Vec<Packet>>
Replaces the specified packets at the location described by
pathspec
with packets
.
If a packet is a container, the sub-tree rooted at the container is removed.
Note: the number of packets to remove need not match the number of packets to insert.
The removed packets are returned.
If the path was invalid, then Error::IndexOutOfRange
is
returned instead.
Examples
// A compressed data packet that contains a literal data packet.
let mut literal = Literal::new(DataFormat::Text);
literal.set_body(b"old".to_vec());
let mut compressed =
CompressedData::new(CompressionAlgorithm::Uncompressed);
compressed.children_mut().unwrap().push(literal.into());
let mut pile = PacketPile::from(Packet::from(compressed));
// Replace the literal data packet.
let mut literal = Literal::new(DataFormat::Text);
literal.set_body(b"new".to_vec());
pile.replace(
&[0, 0], 1,
[literal.into()].to_vec())?;
sourcepub fn descendants(&self) -> Iter<'_> ⓘ
pub fn descendants(&self) -> Iter<'_> ⓘ
Returns an iterator over all of the packet’s descendants, in depth-first order.
let mut lit = Literal::new(DataFormat::Text);
lit.set_body(b"test".to_vec());
let pile = PacketPile::from(vec![lit.into()]);
for packet in pile.descendants() {
assert_eq!(packet.tag(), Tag::Literal);
}
sourcepub fn children(
&self
) -> impl Iterator<Item = &Packet> + ExactSizeIterator + Send + Sync
pub fn children( &self ) -> impl Iterator<Item = &Packet> + ExactSizeIterator + Send + Sync
Returns an iterator over the top-level packets.
let mut lit = Literal::new(DataFormat::Text);
lit.set_body(b"test".to_vec());
let pile = PacketPile::from(vec![lit.into()]);
assert_eq!(pile.children().len(), 1);
sourcepub fn into_children(
self
) -> impl Iterator<Item = Packet> + ExactSizeIterator + Send + Sync
pub fn into_children( self ) -> impl Iterator<Item = Packet> + ExactSizeIterator + Send + Sync
Returns an IntoIter
over the top-level packets.
let mut lit = Literal::new(DataFormat::Text);
lit.set_body(b"test".to_vec());
let pile = PacketPile::from(vec![lit.into()]);
for packet in pile.into_children() {
assert_eq!(packet.tag(), Tag::Literal);
}
Trait Implementations§
source§impl Clone for PacketPile
impl Clone for PacketPile
source§fn clone(&self) -> PacketPile
fn clone(&self) -> PacketPile
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moresource§impl Debug for PacketPile
impl Debug for PacketPile
source§impl Default for PacketPile
impl Default for PacketPile
source§fn default() -> PacketPile
fn default() -> PacketPile
source§impl From<Cert> for PacketPile
impl From<Cert> for PacketPile
source§fn from(cert: Cert) -> PacketPile
fn from(cert: Cert) -> PacketPile
Converts the Cert
into a PacketPile
.
If any packets include secret key material, that secret key
material is not dropped, as it is when serializing a Cert
.
source§impl From<Message> for PacketPile
impl From<Message> for PacketPile
source§impl From<Packet> for PacketPile
impl From<Packet> for PacketPile
source§impl From<PacketPile> for Vec<Packet>
impl From<PacketPile> for Vec<Packet>
source§fn from(pp: PacketPile) -> Self
fn from(pp: PacketPile) -> Self
source§impl FromIterator<Packet> for PacketPile
impl FromIterator<Packet> for PacketPile
source§impl FromStr for PacketPile
impl FromStr for PacketPile
source§impl Marshal for PacketPile
impl Marshal for PacketPile
source§impl MarshalInto for PacketPile
impl MarshalInto for PacketPile
source§fn serialized_len(&self) -> usize
fn serialized_len(&self) -> usize
source§fn serialize_into(&self, buf: &mut [u8]) -> Result<usize>
fn serialize_into(&self, buf: &mut [u8]) -> Result<usize>
source§impl<'a> Parse<'a, PacketPile> for PacketPile
impl<'a> Parse<'a, PacketPile> for PacketPile
source§fn from_reader<R: 'a + Read + Send + Sync>(reader: R) -> Result<PacketPile>
fn from_reader<R: 'a + Read + Send + Sync>(reader: R) -> Result<PacketPile>
Deserializes the OpenPGP message stored in a std::io::Read
object.
Although this method is easier to use to parse a sequence of
OpenPGP packets than a PacketParser
or a
PacketPileParser
, this interface buffers the whole message
in memory. Thus, the caller must be certain that the
deserialized message is not too large.
Note: this interface does buffer the contents of packets.
source§fn from_file<P: AsRef<Path>>(path: P) -> Result<PacketPile>
fn from_file<P: AsRef<Path>>(path: P) -> Result<PacketPile>
Deserializes the OpenPGP message stored in the file named by
path
.
See from_reader
for more details and caveats.
source§fn from_bytes<D: AsRef<[u8]> + ?Sized>(data: &'a D) -> Result<PacketPile>
fn from_bytes<D: AsRef<[u8]> + ?Sized>(data: &'a D) -> Result<PacketPile>
Deserializes the OpenPGP message stored in the provided buffer.
See from_reader
for more details and caveats.
source§impl PartialEq<PacketPile> for PacketPile
impl PartialEq<PacketPile> for PacketPile
source§fn eq(&self, other: &PacketPile) -> bool
fn eq(&self, other: &PacketPile) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl Serialize for PacketPile
impl Serialize for PacketPile
source§impl SerializeInto for PacketPile
impl SerializeInto for PacketPile
source§fn serialized_len(&self) -> usize
fn serialized_len(&self) -> usize
source§fn serialize_into(&self, buf: &mut [u8]) -> Result<usize>
fn serialize_into(&self, buf: &mut [u8]) -> Result<usize>
source§impl<'a> TryFrom<PacketParserResult<'a>> for PacketPile
impl<'a> TryFrom<PacketParserResult<'a>> for PacketPile
source§fn try_from(ppr: PacketParserResult<'a>) -> Result<PacketPile>
fn try_from(ppr: PacketParserResult<'a>) -> Result<PacketPile>
Reads all of the packets from a PacketParser
, and turns them
into a message.
Note: this assumes that ppr
points to a top-level packet.
source§impl TryFrom<PacketPile> for Cert
impl TryFrom<PacketPile> for Cert
source§fn try_from(p: PacketPile) -> Result<Self>
fn try_from(p: PacketPile) -> Result<Self>
Returns the certificate found in the PacketPile
.
If the PacketPile
does not start with a certificate
(specifically, if it does not start with a primary key
packet), then this fails.
If the sequence contains multiple certificates (i.e., it is a
keyring), or the certificate is followed by an invalid packet
this function will fail. To parse keyrings, use
CertParser
instead of this function.
Examples
use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::packet::prelude::*;
use openpgp::PacketPile;
use std::convert::TryFrom;
let (cert, rev) =
CertBuilder::general_purpose(None, Some("alice@example.org"))
.generate()?;
// We should be able to turn a certificate into a PacketPile
// and back.
let pp : PacketPile = cert.into();
assert!(Cert::try_from(pp).is_ok());
// But a revocation certificate is not a certificate, so this
// will fail.
let pp : PacketPile = Packet::from(rev).into();
assert!(Cert::try_from(pp).is_err());
source§impl TryFrom<PacketPile> for Message
impl TryFrom<PacketPile> for Message
source§fn try_from(pile: PacketPile) -> Result<Self>
fn try_from(pile: PacketPile) -> Result<Self>
Converts the PacketPile
to a Message
.
Converting a PacketPile
to a Message
doesn’t change the
packets; it asserts that the packet sequence is an optionally
encrypted, optionally signed, optionally compressed literal
data packet. The exact grammar is defined in Section 11.3 of
RFC 4880.
Caveats: this function assumes that any still encrypted parts or still compressed parts are valid messages.