pub struct SubpacketArea { /* private fields */ }
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§

source§

impl SubpacketArea

source

pub const MAX_SIZE: usize = 65_535usize

The maximum size of a subpacket area.

source

pub fn new(packets: Vec<Subpacket>) -> Result<SubpacketArea>

Returns a new subpacket area containing the given packets.

source

pub fn iter(&self) -> impl Iterator<Item = &Subpacket> + Send + Sync

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());
source

pub fn subpacket(&self, tag: SubpacketTag) -> Option<&Subpacket>

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.");
}
source

pub fn subpacket_mut(&mut self, tag: SubpacketTag) -> Option<&mut Subpacket>

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.");
}
source

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());
source

pub fn add(&mut self, packet: Subpacket) -> Result<()>

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)?;
source

pub fn replace(&mut self, packet: Subpacket) -> Result<()>

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)?;
source

pub fn remove_all(&mut self, tag: SubpacketTag)

Removes all subpackets with the given tag.

source

pub fn clear(&mut self)

Removes all subpackets.

source

pub fn sort(&mut self)

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§

source§

impl Clone for SubpacketArea

source§

fn clone(&self) -> SubpacketArea

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl Debug for SubpacketArea

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

impl Default for SubpacketArea

source§

fn default() -> Self

Returns the “default value” for a type. Read more
source§

impl Hash for SubpacketArea

source§

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher. Read more
1.3.0 · source§

fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher. Read more
source§

impl<'a> IntoIterator for &'a SubpacketArea

§

type Item = &'a Subpacket

The type of the elements being iterated over.
§

type IntoIter = Iter<'a, Subpacket>

Which kind of iterator are we turning this into?
source§

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value. Read more
source§

impl Marshal for SubpacketArea

source§

fn serialize(&self, o: &mut dyn Write) -> Result<()>

Writes a serialized version of the object to o.
source§

fn export(&self, o: &mut dyn Write) -> Result<()>

Exports a serialized version of the object to o. Read more
source§

impl MarshalInto for SubpacketArea

source§

fn serialized_len(&self) -> usize

Computes the maximal length of the serialized representation. Read more
source§

fn serialize_into(&self, buf: &mut [u8]) -> Result<usize>

Serializes into the given buffer. Read more
source§

fn to_vec(&self) -> Result<Vec<u8>>

Serializes the packet to a vector.
source§

fn export_into(&self, buf: &mut [u8]) -> Result<usize>

Exports into the given buffer. Read more
source§

fn export_to_vec(&self) -> Result<Vec<u8>>

Exports to a vector. Read more
source§

impl Ord for SubpacketArea

source§

fn cmp(&self, other: &SubpacketArea) -> Ordering

This method returns an Ordering between self and other. Read more
1.21.0 · source§

fn max(self, other: Self) -> Self
where Self: Sized,

Compares and returns the maximum of two values. Read more
1.21.0 · source§

fn min(self, other: Self) -> Self
where Self: Sized,

Compares and returns the minimum of two values. Read more
1.50.0 · source§

fn clamp(self, min: Self, max: Self) -> Self
where Self: Sized + PartialOrd,

Restrict a value to a certain interval. Read more
source§

impl PartialEq for SubpacketArea

source§

fn eq(&self, other: &SubpacketArea) -> bool

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl PartialOrd for SubpacketArea

source§

fn partial_cmp(&self, other: &SubpacketArea) -> Option<Ordering>

This method returns an ordering between self and other values if one exists. Read more
1.0.0 · source§

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator. Read more
1.0.0 · source§

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more
1.0.0 · source§

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator. Read more
1.0.0 · source§

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more
source§

impl Eq for SubpacketArea

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

default unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> DynClone for T
where T: Clone,

source§

fn __clone_box(&self, _: Private) -> *mut ()

source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> Same for T

§

type Output = T

Should always be Self
source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

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

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> ErasedDestructor for T
where T: 'static,

source§

impl<T> MaybeSendSync for T