[][src]Struct sequoia_openpgp::packet::signature::subpacket::SubpacketAreas

pub struct SubpacketAreas { /* fields omitted */ }

Subpacket storage.

Subpackets are stored either in a so-called hashed area or a so-called unhashed area. Packets stored in the hashed area are protected by the signature's hash whereas packets stored in the unhashed area are not. Generally, two types of information are stored in the unhashed area: self-authenticating data (the Issuer subpacket, the Issuer Fingerprint subpacket, and the Embedded Signature subpacket), and hints, like the features subpacket.

When accessing subpackets directly via SubpacketAreas, the subpackets are only looked up in the hashed area unless the packets are self-authenticating in which case subpackets from the hash area are preferred. To return packets from a specific area, use the hashed_area and unhashed_area methods to get the specific methods and then use their accessors.

Implementations

impl SubpacketAreas[src]

pub fn new(hashed_area: SubpacketArea, unhashed_area: SubpacketArea) -> Self[src]

Returns a new SubpacketAreas object.

pub fn hashed_area(&self) -> &SubpacketArea[src]

Gets a reference to the hashed area.

pub fn hashed_area_mut(&mut self) -> &mut SubpacketArea[src]

Gets a mutable reference to the hashed area.

pub fn unhashed_area(&self) -> &SubpacketArea[src]

Gets a reference to the unhashed area.

pub fn unhashed_area_mut(&mut self) -> &mut SubpacketArea[src]

Gets a mutable reference to the unhashed area.

pub fn sort(&mut self)[src]

Sorts the subpacket areas.

See SubpacketArea::sort().

pub fn signature_expiration_time(&self) -> Option<SystemTime>[src]

Returns the time when the signature expires.

If the signature expiration time subpacket is not present, this returns None.

Note: if the signature contains multiple instances of the signature expiration time subpacket, only the last one is considered.

pub fn signature_alive<T, U>(
    &self,
    time: T,
    clock_skew_tolerance: U
) -> Result<()> where
    T: Into<Option<SystemTime>>,
    U: Into<Option<Duration>>, 
[src]

Returns whether or not the signature is alive at the specified time.

A signature is considered to be alive if creation time - tolerance <= time and time < expiration time.

If time is None, uses the current time.

If time is None, and clock_skew_tolerance is None, then uses CLOCK_SKEW_TOLERANCE. If time is not None, but clock_skew_tolerance is None, uses no tolerance.

Some tolerance for clock skew is sometimes necessary, because although most computers synchronize their clock with a time server, up to a few seconds of clock skew are not unusual in practice. And, even worse, several minutes of clock skew appear to be not uncommon on virtual machines.

Not accounting for clock skew can result in signatures being unexpectedly considered invalid. Consider: computer A sends a message to computer B at 9:00, but computer B, whose clock says the current time is 8:59, rejects it, because the signature appears to have been made in the future. This is particularly problematic for low-latency protocols built on top of OpenPGP, e.g., state synchronization between two MUAs via a shared IMAP folder.

Being tolerant to potential clock skew is not always appropriate. For instance, when determining a User ID's current self signature at time t, we don't ever want to consider a self-signature made after t to be valid, even if it was made just a few moments after t. This goes doubly so for soft revocation certificates: the user might send a message that she is retiring, and then immediately create a soft revocation. The soft revocation should not invalidate the message.

Unfortunately, in many cases, whether we should account for clock skew or not depends on application-specific context. As a rule of thumb, if the time and the timestamp come from different sources, you probably want to account for clock skew.

Note that Section 5.2.3.4 of RFC 4880 states that "[[A Signature Creation Time subpacket]] MUST be present in the hashed area." Consequently, if such a packet does not exist, but a "Signature Expiration Time" subpacket exists, we conservatively treat the signature as expired, because there is no way to evaluate the expiration time.

pub fn key_expiration_time<P, R>(&self, key: &Key<P, R>) -> Option<SystemTime> where
    P: KeyParts,
    R: KeyRole
[src]

Returns the time when the key expires.

If the key expiration time subpacket is not present, this returns None.

Note: if the key contains multiple instances of the key expiration time subpacket, only the last one is considered.

pub fn key_alive<P, R, T>(&self, key: &Key<P, R>, t: T) -> Result<()> where
    P: KeyParts,
    R: KeyRole,
    T: Into<Option<SystemTime>>, 
[src]

Returns whether or not the given key is alive at t.

A key is considered to be alive if creation time <= t and t < expiration time.

This function does not check whether the key was revoked.

See Section 5.2.3.6 of RFC 4880.

pub fn issuer(&self) -> Option<&KeyID>[src]

Returns the value of the Issuer subpacket, which contains the KeyID of the key that allegedly created this signature.

If the subpacket is not present, this returns None.

Note: if the signature contains multiple instances of this subpacket, only the last one is considered.

pub fn embedded_signature(&self) -> Option<&Signature>[src]

Returns the value of the Embedded Signature subpacket, which contains a signature.

This is used, for instance, to store a subkey's primary key binding signature (0x19).

If the subpacket is not present, this returns None.

Note: if the signature contains multiple instances of this subpacket, only the last one is considered.

pub fn issuer_fingerprint(&self) -> Option<&Fingerprint>[src]

Returns the value of the Issuer Fingerprint subpacket, which contains the fingerprint of the key that allegedly created this signature.

This subpacket should be preferred to the Issuer subpacket, because Fingerprints are not subject to collisions.

If the subpacket is not present, this returns None.

Note: if the signature contains multiple instances of this subpacket, only the last one is considered.

Methods from Deref<Target = SubpacketArea>

pub fn iter<'a>(&'a self) -> impl Iterator<Item = &'a Subpacket>[src]

Iterates over the subpackets.

pub fn lookup(&self, tag: SubpacketTag) -> Option<&Subpacket>[src]

Returns the last subpacket, if any, with the specified tag.

This is the recommended strategy of dealing with multiple, possibly conflicting, subpackets. See Section 5.2.4.1 of RFC 4880.

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

Adds the given subpacket.

Errors

Returns Error::MalformedPacket if adding the packet makes the subpacket area exceed the size limit.

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

Adds the given subpacket, replacing all other subpackets with the same tag.

Errors

Returns Error::MalformedPacket if adding the packet makes the subpacket area exceed the size limit.

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

Removes all subpackets with the given tag.

Returns the old subpacket area, so that it can be restored if necessary.

pub fn clear(&mut self)[src]

Removes all subpackets.

pub fn sort(&mut self)[src]

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.

pub fn signature_creation_time(&self) -> Option<SystemTime>[src]

Returns the value of the Creation Time subpacket, which contains the time when the signature was created as a unix timestamp.

If the subpacket is not present, this returns None.

Note: if the signature contains multiple instances of this subpacket, only the last one is considered.

pub fn signature_validity_period(&self) -> Option<Duration>[src]

Returns the value of the Signature Expiration Time subpacket, which contains when the signature expires as the number of seconds after its creation.

If the subpacket is not present, this returns None. If this function returns None, or the returned period is 0, the signature does not expire.

Note: if the signature contains multiple instances of this subpacket, only the last one is considered.

pub fn exportable_certification(&self) -> Option<bool>[src]

Returns the value of the Exportable Certification subpacket, which contains whether the certification should be exported (i.e., whether the packet is not a local signature).

If the subpacket is not present, this returns None.

Note: if the signature contains multiple instances of this subpacket, only the last one is considered.

pub fn trust_signature(&self) -> Option<(u8, u8)>[src]

Returns the value of the Trust Signature subpacket.

The return value is a tuple consisting of the level or depth and the trust amount.

Recall from Section 5.2.3.13 of RFC 4880:

Level 0 has the same meaning as an ordinary
validity signature.  Level 1 means that the signed key is asserted to
be a valid trusted introducer, with the 2nd octet of the body
specifying the degree of trust.  Level 2 means that the signed key is
asserted to be trusted to issue level 1 trust signatures, i.e., that
it is a "meta introducer".

And, the trust amount is:

interpreted such that values less than 120 indicate partial
trust and values of 120 or greater indicate complete trust.
Implementations SHOULD emit values of 60 for partial trust and
120 for complete trust.

Note: if the signature contains multiple instances of this subpacket, only the last one is considered.

pub fn regular_expression(&self) -> Option<&[u8]>[src]

Returns the value of the Regular Expression subpacket.

Note: the serialized form includes a trailing NUL byte. This returns the value without the trailing NUL.

If the subpacket is not present, this returns None.

Note: if the signature contains multiple instances of this subpacket, only the last one is considered.

pub fn revocable(&self) -> Option<bool>[src]

Returns the value of the Revocable subpacket, which indicates whether the signature is revocable, i.e., whether revocation certificates for this signature should be ignored.

If the subpacket is not present, this returns None.

Note: if the signature contains multiple instances of this subpacket, only the last one is considered.

pub fn key_validity_period(&self) -> Option<Duration>[src]

Returns the value of the Key Expiration Time subpacket, which contains when the referenced key expires as the number of seconds after the key's creation.

If the subpacket is not present, this returns None. If this function returns None, or the returned period is 0, the key does not expire.

Note: if the signature contains multiple instances of this subpacket, only the last one is considered.

pub fn preferred_symmetric_algorithms(&self) -> Option<&[SymmetricAlgorithm]>[src]

Returns the value of the Preferred Symmetric Algorithms subpacket, which contains the list of symmetric algorithms that the key holder prefers, ordered according by the key holder's preference.

If the subpacket is not present, this returns None.

Note: if the signature contains multiple instances of this subpacket, only the last one is considered.

pub fn revocation_keys(&self) -> impl Iterator<Item = &RevocationKey>[src]

Returns the value of the Revocation Key subpacket, which contains a designated revoker.

If the subpacket is not present, this returns None.

Note: if the signature contains multiple instances of this subpacket, only the last one is considered.

pub fn issuer(&self) -> Option<&KeyID>[src]

Returns the value of the Issuer subpacket, which contains the KeyID of the key that allegedly created this signature.

If the subpacket is not present, this returns None.

Note: if the signature contains multiple instances of this subpacket, only the last one is considered.

pub fn notation_data(&self) -> Vec<&NotationData>[src]

Returns the value of all Notation Data packets.

If the subpacket is not present or malformed, this returns an empty vector.

Note: unlike other subpacket accessor functions, this function returns all the Notation Data subpackets, not just the last one.

pub fn notation<N>(&self, name: N) -> Vec<&[u8]> where
    N: AsRef<str>, 
[src]

Returns the value of all Notation Data subpackets with the given name.

pub fn preferred_hash_algorithms(&self) -> Option<&[HashAlgorithm]>[src]

Returns the value of the Preferred Hash Algorithms subpacket, which contains the list of hash algorithms that the key holders prefers, ordered according by the key holder's preference.

If the subpacket is not present, this returns None.

Note: if the signature contains multiple instances of this subpacket, only the last one is considered.

pub fn preferred_compression_algorithms(
    &self
) -> Option<&[CompressionAlgorithm]>
[src]

Returns the value of the Preferred Compression Algorithms subpacket, which contains the list of compression algorithms that the key holder prefers, ordered according by the key holder's preference.

If the subpacket is not present, this returns None.

Note: if the signature contains multiple instances of this subpacket, only the last one is considered.

pub fn key_server_preferences(&self) -> Option<KeyServerPreferences>[src]

Returns the value of the Key Server Preferences subpacket, which contains the key holder's key server preferences.

If the subpacket is not present, this returns None.

Note: if the signature contains multiple instances of this subpacket, only the last one is considered.

pub fn preferred_key_server(&self) -> Option<&[u8]>[src]

Returns the value of the Preferred Key Server subpacket, which contains the user's preferred key server for updates.

Note: this packet should be ignored, because it acts as key tracker.

If the subpacket is not present, this returns None.

Note: if the signature contains multiple instances of this subpacket, only the last one is considered.

pub fn primary_userid(&self) -> Option<bool>[src]

Returns the value of the Primary UserID subpacket, which indicates whether the referenced UserID should be considered the user's primary User ID.

If the subpacket is not present, this returns None.

Note: if the signature contains multiple instances of this subpacket, only the last one is considered.

pub fn policy_uri(&self) -> Option<&[u8]>[src]

Returns the value of the Policy URI subpacket.

If the subpacket is not present, this returns None.

Note: if the signature contains multiple instances of this subpacket, only the last one is considered.

pub fn key_flags(&self) -> Option<KeyFlags>[src]

Returns the value of the Key Flags subpacket, which contains information about the referenced key, in particular, how it is used (certification, signing, encryption, authentication), and how it is stored (split, held by multiple people).

If the subpacket is not present, this returns None.

Note: if the signature contains multiple instances of this subpacket, only the last one is considered.

pub fn signers_user_id(&self) -> Option<&[u8]>[src]

Returns the value of the Signer's UserID subpacket, which contains the User ID that the key holder considers responsible for the signature.

If the subpacket is not present, this returns None.

Note: if the signature contains multiple instances of this subpacket, only the last one is considered.

pub fn reason_for_revocation(&self) -> Option<(ReasonForRevocation, &[u8])>[src]

Returns the value of the Reason for Revocation subpacket.

If the subpacket is not present, this returns None.

Note: if the signature contains multiple instances of this subpacket, only the last one is considered.

pub fn features(&self) -> Option<Features>[src]

Returns the value of the Features subpacket, which contains a list of features that the user's OpenPGP implementation supports.

If the subpacket is not present, this returns None.

Note: if the signature contains multiple instances of this subpacket, only the last one is considered.

pub fn signature_target(
    &self
) -> Option<(PublicKeyAlgorithm, HashAlgorithm, &[u8])>
[src]

Returns the value of the Signature Target subpacket, which contains the hash of the referenced signature packet.

This is used, for instance, by a signature revocation certification to designate the signature that is being revoked.

If the subpacket is not present, this returns None.

Note: if the signature contains multiple instances of this subpacket, only the last one is considered.

pub fn embedded_signature(&self) -> Option<&Signature>[src]

Returns the value of the Embedded Signature subpacket, which contains a signature.

This is used, for instance, to store a subkey's primary key binding signature (0x19).

If the subpacket is not present, this returns None.

Note: if the signature contains multiple instances of this subpacket, only the last one is considered.

pub fn issuer_fingerprint(&self) -> Option<&Fingerprint>[src]

Returns the value of the Issuer Fingerprint subpacket, which contains the fingerprint of the key that allegedly created this signature.

This subpacket should be preferred to the Issuer subpacket, because Fingerprints are not subject to collisions.

If the subpacket is not present, this returns None.

Note: if the signature contains multiple instances of this subpacket, only the last one is considered.

pub fn preferred_aead_algorithms(&self) -> Option<&[AEADAlgorithm]>[src]

Returns the value of the Preferred AEAD Algorithms subpacket, which contains the list of AEAD algorithms that the key holder prefers, ordered according by the key holder's preference.

If the subpacket is not present, this returns None.

Note: if the signature contains multiple instances of this subpacket, only the last one is considered.

pub fn intended_recipients(&self) -> Vec<Fingerprint>[src]

Returns the intended recipients.

Trait Implementations

impl Clone for SubpacketAreas[src]

impl Default for SubpacketAreas[src]

impl Deref for SubpacketAreas[src]

type Target = SubpacketArea

The resulting type after dereferencing.

impl DerefMut for SubpacketAreas[src]

impl Eq for SubpacketAreas[src]

impl Hash for SubpacketAreas[src]

impl PartialEq<SubpacketAreas> for SubpacketAreas[src]

impl StructuralEq for SubpacketAreas[src]

impl StructuralPartialEq for SubpacketAreas[src]

Auto Trait Implementations

Blanket Implementations

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

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

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

impl<T> DynClone for T where
    T: Clone
[src]

impl<T> From<T> for T[src]

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

impl<T> ToOwned for T where
    T: Clone
[src]

type Owned = T

The resulting type after obtaining ownership.

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

type Error = Infallible

The type returned in the event of a conversion error.

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

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

The type returned in the event of a conversion error.