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
sourceimpl 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<'_>ⓘNotable traits for Iter<'a>impl<'a> Iterator for Iter<'a> type Item = &'a Packet;
pub fn descendants(&self) -> Iter<'_>ⓘNotable traits for Iter<'a>impl<'a> Iterator for Iter<'a> type Item = &'a Packet;
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
sourceimpl Clone for PacketPile
impl Clone for PacketPile
sourcefn clone(&self) -> PacketPile
fn clone(&self) -> PacketPile
Returns a copy of the value. Read more
1.0.0 · sourcefn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
Performs copy-assignment from source
. Read more
sourceimpl Debug for PacketPile
impl Debug for PacketPile
sourceimpl Default for PacketPile
impl Default for PacketPile
sourcefn default() -> PacketPile
fn default() -> PacketPile
Returns the “default value” for a type. Read more
sourceimpl From<Cert> for PacketPile
impl From<Cert> for PacketPile
sourcefn 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
.
sourceimpl From<Message> for PacketPile
impl From<Message> for PacketPile
sourceimpl From<Packet> for PacketPile
impl From<Packet> for PacketPile
sourceimpl From<PacketPile> for Vec<Packet>
impl From<PacketPile> for Vec<Packet>
sourcefn from(pp: PacketPile) -> Self
fn from(pp: PacketPile) -> Self
Converts to this type from the input type.
sourceimpl FromIterator<Packet> for PacketPile
impl FromIterator<Packet> for PacketPile
sourcefn from_iter<I: IntoIterator<Item = Packet>>(iter: I) -> Self
fn from_iter<I: IntoIterator<Item = Packet>>(iter: I) -> Self
Creates a value from an iterator. Read more
sourceimpl FromStr for PacketPile
impl FromStr for PacketPile
sourceimpl Marshal for PacketPile
impl Marshal for PacketPile
sourceimpl MarshalInto for PacketPile
impl MarshalInto for PacketPile
sourcefn serialized_len(&self) -> usize
fn serialized_len(&self) -> usize
Computes the maximal length of the serialized representation. Read more
sourcefn serialize_into(&self, buf: &mut [u8]) -> Result<usize>
fn serialize_into(&self, buf: &mut [u8]) -> Result<usize>
Serializes into the given buffer. Read more
sourceimpl<'a> Parse<'a, PacketPile> for PacketPile
impl<'a> Parse<'a, PacketPile> for PacketPile
sourcefn 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.
sourcefn 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.
sourcefn 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.
sourceimpl PartialEq<PacketPile> for PacketPile
impl PartialEq<PacketPile> for PacketPile
sourcefn eq(&self, other: &PacketPile) -> bool
fn eq(&self, other: &PacketPile) -> bool
This method tests for self
and other
values to be equal, and is used
by ==
. Read more
sourcefn ne(&self, other: &PacketPile) -> bool
fn ne(&self, other: &PacketPile) -> bool
This method tests for !=
.
sourceimpl Serialize for PacketPile
impl Serialize for PacketPile
sourceimpl SerializeInto for PacketPile
impl SerializeInto for PacketPile
sourcefn serialized_len(&self) -> usize
fn serialized_len(&self) -> usize
Computes the maximal length of the serialized representation. Read more
sourcefn serialize_into(&self, buf: &mut [u8]) -> Result<usize>
fn serialize_into(&self, buf: &mut [u8]) -> Result<usize>
Serializes into the given buffer. Read more
sourceimpl<'a> TryFrom<PacketParserResult<'a>> for PacketPile
impl<'a> TryFrom<PacketParserResult<'a>> for PacketPile
sourcefn 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.
sourceimpl TryFrom<PacketPile> for Cert
impl TryFrom<PacketPile> for Cert
sourcefn 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());
sourceimpl TryFrom<PacketPile> for Message
impl TryFrom<PacketPile> for Message
sourcefn 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.
impl StructuralPartialEq for PacketPile
Auto Trait Implementations
impl RefUnwindSafe for PacketPile
impl Send for PacketPile
impl Sync for PacketPile
impl Unpin for PacketPile
impl UnwindSafe for PacketPile
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