Struct sequoia_openpgp::packet::signature::subpacket::SubpacketArea [−][src]
pub struct SubpacketArea { /* fields omitted */ }
Expand description
Subpacket area.
A version 4 Signature contains two areas that can stored
signature subpackets: a so-called hashed subpacket area, and a
so-called unhashed subpacket area. The hashed subpacket area is
protected by the signature; the unhashed area is not. This makes
the unhashed subpacket area only appropriate for
self-authenticating data, like the Issuer
subpacket. The
SubpacketAreas
data structure understands these nuances and
routes lookups appropriately. As such, it is usually better to
work with subpackets using that interface.
Examples
fn sig_stats(sig: &Signature) {
eprintln!("Hashed subpacket area has {} subpackets",
sig.hashed_area().iter().count());
eprintln!("Unhashed subpacket area has {} subpackets",
sig.unhashed_area().iter().count());
}
Implementations
Returns a new subpacket area containing the given packets
.
Iterates over the subpackets.
Examples
Print the number of different types of subpackets in a Signature’s hashed subpacket area:
let mut tags: Vec<_> = sig.hashed_area().iter().map(|sb| {
sb.tag()
}).collect();
tags.sort();
tags.dedup();
eprintln!("The hashed area contains {} types of subpackets",
tags.len());
Returns a reference to the last instance of the specified subpacket, if any.
A given subpacket may occur multiple times. For some, like
the Notation Data
subpacket, this is reasonable. For
others, like the Signature Creation Time
subpacket, this
results in an ambiguity. Section 5.2.4.1 of RFC 4880 says:
a signature may contain multiple copies of a preference or multiple expiration times. In most cases, an implementation SHOULD use the last subpacket in the signature, but MAY use any conflict resolution scheme that makes more sense.
This function implements the recommended strategy of returning the last subpacket.
Examples
All signatures must have a Signature Creation Time
subpacket
in the hashed subpacket area:
use sequoia_openpgp as openpgp;
use openpgp::packet::signature::subpacket::SubpacketTag;
if sig.hashed_area().subpacket(SubpacketTag::SignatureCreationTime).is_none() {
eprintln!("Invalid signature.");
}
Returns a mutable reference to the last instance of the specified subpacket, if any.
A given subpacket may occur multiple times. For some, like
the Notation Data
subpacket, this is reasonable. For
others, like the Signature Creation Time
subpacket, this
results in an ambiguity. Section 5.2.4.1 of RFC 4880 says:
a signature may contain multiple copies of a preference or multiple expiration times. In most cases, an implementation SHOULD use the last subpacket in the signature, but MAY use any conflict resolution scheme that makes more sense.
This function implements the recommended strategy of returning the last subpacket.
Examples
All signatures must have a Signature Creation Time
subpacket
in the hashed subpacket area:
use sequoia_openpgp as openpgp;
use openpgp::packet::signature::subpacket::SubpacketTag;
if sig.hashed_area().subpacket(SubpacketTag::SignatureCreationTime).is_none() {
eprintln!("Invalid signature.");
}
pub fn subpackets(
&self,
target: SubpacketTag
) -> impl Iterator<Item = &Subpacket> + Send + Sync
pub fn subpackets(
&self,
target: SubpacketTag
) -> impl Iterator<Item = &Subpacket> + Send + Sync
Returns all instances of the specified subpacket.
For most subpackets, only a single instance of the subpacket
makes sense. SubpacketArea::subpacket
resolves this
ambiguity by returning the last instance of the request
subpacket type. But, for some subpackets, like the Notation Data
subpacket, multiple instances of the subpacket are
reasonable.
Examples
Count the number of Notation Data
subpackets in the hashed
subpacket area:
use sequoia_openpgp as openpgp;
use openpgp::packet::signature::subpacket::SubpacketTag;
eprintln!("Signature has {} notations.",
sig.hashed_area().subpackets(SubpacketTag::NotationData).count());
Adds the given subpacket.
Adds the given subpacket to the subpacket area. If the
subpacket area already contains subpackets with the same tag,
they are left in place. If you want to replace them, you
should instead use the SubpacketArea::replace
method.
Errors
Returns Error::MalformedPacket
if adding the packet makes
the subpacket area exceed the size limit.
Examples
Adds an additional Issuer
subpacket to the unhashed
subpacket area. (This is useful if the key material is
associated with multiple certificates, e.g., a v4 and a v5
certificate.) Because the subpacket is added to the unhashed
area, the signature remains valid.
use sequoia_openpgp as openpgp;
use openpgp::KeyID;
use openpgp::packet::signature::subpacket::{
Subpacket,
SubpacketTag,
SubpacketValue,
};
let mut sig: Signature = sig;
sig.unhashed_area_mut().add(
Subpacket::new(
SubpacketValue::Issuer(KeyID::from_hex("AAAA BBBB CCCC DDDD")?),
false)?);
sig.verify_message(signer.public(), msg)?;
Adds the given subpacket, replacing all other subpackets with the same tag.
Adds the given subpacket to the subpacket area. If the
subpacket area already contains subpackets with the same tag,
they are first removed. If you want to preserve them, you
should instead use the SubpacketArea::add
method.
Errors
Returns Error::MalformedPacket
if adding the packet makes
the subpacket area exceed the size limit.
Examples
Assuming we have a signature with an additional Issuer
subpacket in the unhashed area (see the example for
SubpacketArea::add
, this replaces the Issuer
subpacket
in the unhashed area. Because the unhashed area is not
protected by the signature, the signature remains valid:
use sequoia_openpgp as openpgp;
use openpgp::KeyID;
use openpgp::packet::signature::subpacket::{
Subpacket,
SubpacketTag,
SubpacketValue,
};
// First, add a subpacket to the unhashed area.
let mut sig: Signature = sig;
sig.unhashed_area_mut().add(
Subpacket::new(
SubpacketValue::Issuer(KeyID::from_hex("DDDD CCCC BBBB AAAA")?),
false)?);
// Now, replace it.
sig.unhashed_area_mut().replace(
Subpacket::new(
SubpacketValue::Issuer(KeyID::from_hex("AAAA BBBB CCCC DDDD")?),
false)?);
sig.verify_message(signer.public(), msg)?;
Removes all subpackets with the given tag.
Sorts the subpackets by subpacket tag.
This normalizes the subpacket area, and accelerates lookups in implementations that sort the in-core representation and use binary search for lookups.
The subpackets are sorted by the numeric value of their tag.
The sort is stable. So, if there are multiple Notation Data
subpackets, for instance, they will remain in the same order.
The SignatureBuilder
sorts the subpacket areas just before
creating the signature.
Trait Implementations
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
Auto Trait Implementations
impl RefUnwindSafe for SubpacketArea
impl Send for SubpacketArea
impl Sync for SubpacketArea
impl Unpin for SubpacketArea
impl UnwindSafe for SubpacketArea
Blanket Implementations
Mutably borrows from an owned value. Read more