Enum sequoia_openpgp::packet::Signature[][src]

#[non_exhaustive]
pub enum Signature {
    V4(Signature4),
}
Expand description

Holds a signature packet.

Signature packets are used to hold all kinds of signatures including certifications, and signatures over documents. See Section 5.2 of RFC 4880 for details.

When signing a document, a Signature packet is typically created indirectly by the streaming Signer. Similarly, a Signature packet is created as a side effect of parsing a signed message using the PacketParser.

Signature packets are also used for self signatures on Keys, self signatures on User IDs, self signatures on User Attributes, certifications of User IDs, and certifications of User Attributes. In these cases, you’ll typically want to use the SignatureBuilder to create the Signature packet. See the linked documentation for details, and examples.

Note: This enum cannot be exhaustively matched to allow future extensions.

A note on equality

Two Signature packets are considered equal if their serialized form is equal. Notably this includes the unhashed subpacket area and the order of subpackets and notations. This excludes the computed digest and signature level, which are not serialized.

A consequence of considering packets in the unhashed subpacket area is that an adversary can take a valid signature and create many distinct but valid signatures by changing the unhashed subpacket area. This has the potential of creating a denial of service vector, if Signatures are naively deduplicated. To protect against this, consider using Signature::normalized_eq.

Examples

Add a User ID to an existing certificate:

use std::time;
use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::packet::prelude::*;
use openpgp::policy::StandardPolicy;

let p = &StandardPolicy::new();

let t1 = time::SystemTime::now();
let t2 = t1 + time::Duration::from_secs(1);

let (cert, _) = CertBuilder::new()
    .set_creation_time(t1)
    .add_userid("Alice <alice@example.org>")
    .generate()?;

// Add a new User ID.
let mut signer = cert
    .primary_key().key().clone().parts_into_secret()?.into_keypair()?;

// Use the existing User ID's signature as a template.  This ensures that
// we use the same
let userid = UserID::from("Alice <alice@other.com>");
let template: signature::SignatureBuilder
    = cert.with_policy(p, t1)?.primary_userid().unwrap()
        .binding_signature().clone().into();
let sig = template.clone()
    .set_signature_creation_time(t2)?;
let sig = userid.bind(&mut signer, &cert, sig)?;

let cert = cert.insert_packets(vec![Packet::from(userid), sig.into()])?;

Variants (Non-exhaustive)

This enum is marked as non-exhaustive
Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Signature packet version 4.

Tuple Fields of V4

0: Signature4

Implementations

Hashing-related functionality.

Hashes this signature for use in a Third-Party Confirmation signature.

Returns the value of any Issuer and Issuer Fingerprint subpackets.

The Issuer subpacket and Issuer Fingerprint subpacket are used when processing a signature to identify which certificate created the signature. Since this information is self-authenticating (the act of validating the signature authenticates the subpacket), it is typically stored in the unhashed subpacket area.

This function returns all instances of the Issuer subpacket and the Issuer Fingerprint subpacket in both the hashed subpacket area and the unhashed subpacket area.

The issuers are sorted so that the Fingerprints come before KeyIDs. The Fingerprints and KeyIDs are not further sorted, but are returned in the order that they are encountered.

Compares Signatures ignoring the unhashed subpacket area.

This comparison function ignores the unhashed subpacket area when comparing two signatures. This prevents a malicious party from taking valid signatures, adding subpackets to the unhashed area, and deriving valid but distinct signatures, which could be used to perform a denial of service attack. For instance, an attacker could create a lot of signatures, which need to be validated. Ignoring the unhashed subpackets means that we can deduplicate signatures using this predicate.

Unlike Signature::normalize, this method ignores authenticated packets in the unhashed subpacket area.

Examples

use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::packet::prelude::*;
use openpgp::packet::signature::subpacket::{Subpacket, SubpacketValue};
use openpgp::policy::StandardPolicy;
use openpgp::types::SignatureType;
use openpgp::types::Features;

let p = &StandardPolicy::new();

let (cert, _) = CertBuilder::new().generate()?;

let orig = cert.with_policy(p, None)?.direct_key_signature()?;

// Add an inconspicuous subpacket to the unhashed area.
let sb = Subpacket::new(SubpacketValue::Features(Features::empty()), false)?;
let mut modified = orig.clone();
modified.unhashed_area_mut().add(sb);

// We modified the signature, but the signature is still valid.
modified.verify_direct_key(cert.primary_key().key(), cert.primary_key().key());

// PartialEq considers the packets to not be equal...
assert!(orig != &modified);
// ... but normalized_eq does.
assert!(orig.normalized_eq(&modified));

Compares Signatures ignoring the unhashed subpacket area.

This is useful to deduplicate signatures by first sorting them using this function, and then deduplicating using the Signature::normalized_eq predicate.

This comparison function ignores the unhashed subpacket area when comparing two signatures. This prevents a malicious party from taking valid signatures, adding subpackets to the unhashed area, and deriving valid but distinct signatures, which could be used to perform a denial of service attack. For instance, an attacker could create a lot of signatures, which need to be validated. Ignoring the unhashed subpackets means that we can deduplicate signatures using this predicate.

Unlike Signature::normalize, this method ignores authenticated packets in the unhashed subpacket area.

Examples

use std::cmp::Ordering;
use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::packet::prelude::*;
use openpgp::packet::signature::subpacket::{Subpacket, SubpacketValue};
use openpgp::policy::StandardPolicy;
use openpgp::types::SignatureType;
use openpgp::types::Features;

let p = &StandardPolicy::new();

let (cert, _) = CertBuilder::new().generate()?;

let orig = cert.with_policy(p, None)?.direct_key_signature()?;

// Add an inconspicuous subpacket to the unhashed area.
let sb = Subpacket::new(SubpacketValue::Features(Features::empty()), false)?;
let mut modified = orig.clone();
modified.unhashed_area_mut().add(sb);

// We modified the signature, but the signature is still valid.
modified.verify_direct_key(cert.primary_key().key(), cert.primary_key().key());

// PartialEq considers the packets to not be equal...
assert!(orig != &modified);
// ... but normalized_partial_cmp does.
assert!(orig.normalized_cmp(&modified) == Ordering::Equal);

Hashes everything but the unhashed subpacket area into state.

This is an alternate implementation of Hash, which does not hash the unhashed subpacket area.

Unlike Signature::normalize, this method ignores authenticated packets in the unhashed subpacket area.

Normalizes the signature.

This function normalizes the unhashed signature subpackets.

First, it removes all but the following self-authenticating subpackets:

  • SubpacketValue::Issuer
  • SubpacketValue::IssuerFingerprint
  • SubpacketValue::EmbeddedSignature

Note: the retained subpackets are not checked for validity.

Then, it adds any missing issuer information to the unhashed subpacket area that has been computed when verifying the signature.

Adds missing issuer information.

Calling this function adds any missing issuer information to the unhashed subpacket area.

When a signature is verified, the identity of the signing key is computed and stored in the Signature struct. This information can be used to complement the issuer information stored in the signature. Note that we don’t do this automatically when verifying signatures, because that would change the serialized representation of the signature as a side-effect of verifying the signature.

Merges two signatures.

Two signatures that are equal according to Signature::normalized_eq may differ in the contents of the unhashed subpacket areas. This function merges two signatures trying hard to incorporate all the information into one signature while avoiding denial of service attacks by merging in bad information.

The merge strategy is as follows:

  • If the signatures differ according to Signature::normalized_eq, the merge fails.

  • Do not consider any subpacket that does not belong into the unhashed subpacket area.

  • Consider all remaining subpackets, in the following order. If we run out of space, all remaining subpackets are ignored.

    • Authenticated subpackets from self
    • Authenticated subpackets from other
    • Unauthenticated subpackets from self commonly found in unhashed areas
    • Unauthenticated subpackets from other commonly found in unhashed areas
    • Remaining subpackets from self
    • Remaining subpackets from other

    See Subpacket::authenticated for how subpackets are authenticated. Subpackets commonly found in unhashed areas are issuer information and embedded signatures.

Verification-related functionality.

Verifies the signature against hash.

The hash should only be computed over the payload, this function hashes in the signature itself before verifying it.

Note: Due to limited context, this only verifies the cryptographic signature and checks that the key predates the signature. Further constraints on the signature, like creation and expiration time, or signature revocations must be checked by the caller.

Likewise, this function does not check whether key can made valid signatures; it is up to the caller to make sure the key is not revoked, not expired, has a valid self-signature, has a subkey binding signature (if appropriate), has the signing capability, etc.

Verifies the signature against digest.

Note: Due to limited context, this only verifies the cryptographic signature and checks that the key predates the signature. Further constraints on the signature, like creation and expiration time, or signature revocations must be checked by the caller.

Likewise, this function does not check whether key can made valid signatures; it is up to the caller to make sure the key is not revoked, not expired, has a valid self-signature, has a subkey binding signature (if appropriate), has the signing capability, etc.

Verifies the signature over text or binary documents using key.

Note: Due to limited context, this only verifies the cryptographic signature, checks the signature’s type, and checks that the key predates the signature. Further constraints on the signature, like creation and expiration time, or signature revocations must be checked by the caller.

Likewise, this function does not check whether key can make valid signatures; it is up to the caller to make sure the key is not revoked, not expired, has a valid self-signature, has a subkey binding signature (if appropriate), has the signing capability, etc.

Verifies the standalone signature using key.

Note: Due to limited context, this only verifies the cryptographic signature, checks the signature’s type, and checks that the key predates the signature. Further constraints on the signature, like creation and expiration time, or signature revocations must be checked by the caller.

Likewise, this function does not check whether key can make valid signatures; it is up to the caller to make sure the key is not revoked, not expired, has a valid self-signature, has a subkey binding signature (if appropriate), has the signing capability, etc.

Verifies the timestamp signature using key.

Note: Due to limited context, this only verifies the cryptographic signature, checks the signature’s type, and checks that the key predates the signature. Further constraints on the signature, like creation and expiration time, or signature revocations must be checked by the caller.

Likewise, this function does not check whether key can make valid signatures; it is up to the caller to make sure the key is not revoked, not expired, has a valid self-signature, has a subkey binding signature (if appropriate), has the signing capability, etc.

Verifies the direct key signature.

self is the direct key signature, signer is the key that allegedly made the signature, and pk is the primary key.

For a self-signature, signer and pk will be the same.

Note: Due to limited context, this only verifies the cryptographic signature, checks the signature’s type, and checks that the key predates the signature. Further constraints on the signature, like creation and expiration time, or signature revocations must be checked by the caller.

Likewise, this function does not check whether signer can made valid signatures; it is up to the caller to make sure the key is not revoked, not expired, has a valid self-signature, has a subkey binding signature (if appropriate), has the signing capability, etc.

Verifies the primary key revocation certificate.

self is the primary key revocation certificate, signer is the key that allegedly made the signature, and pk is the primary key,

For a self-signature, signer and pk will be the same.

Note: Due to limited context, this only verifies the cryptographic signature, checks the signature’s type, and checks that the key predates the signature. Further constraints on the signature, like creation and expiration time, or signature revocations must be checked by the caller.

Likewise, this function does not check whether signer can made valid signatures; it is up to the caller to make sure the key is not revoked, not expired, has a valid self-signature, has a subkey binding signature (if appropriate), has the signing capability, etc.

Verifies the subkey binding.

self is the subkey key binding signature, signer is the key that allegedly made the signature, pk is the primary key, and subkey is the subkey.

For a self-signature, signer and pk will be the same.

If the signature indicates that this is a Signing capable subkey, then the back signature is also verified. If it is missing or can’t be verified, then this function returns false.

Note: Due to limited context, this only verifies the cryptographic signature, checks the signature’s type, and checks that the key predates the signature. Further constraints on the signature, like creation and expiration time, or signature revocations must be checked by the caller.

Likewise, this function does not check whether signer can made valid signatures; it is up to the caller to make sure the key is not revoked, not expired, has a valid self-signature, has a subkey binding signature (if appropriate), has the signing capability, etc.

Verifies the primary key binding.

self is the primary key binding signature, pk is the primary key, and subkey is the subkey.

Note: Due to limited context, this only verifies the cryptographic signature, checks the signature’s type, and checks that the key predates the signature. Further constraints on the signature, like creation and expiration time, or signature revocations must be checked by the caller.

Likewise, this function does not check whether subkey can made valid signatures; it is up to the caller to make sure the key is not revoked, not expired, has a valid self-signature, has a subkey binding signature (if appropriate), has the signing capability, etc.

Verifies the subkey revocation.

self is the subkey key revocation certificate, signer is the key that allegedly made the signature, pk is the primary key, and subkey is the subkey.

For a self-revocation, signer and pk will be the same.

Note: Due to limited context, this only verifies the cryptographic signature, checks the signature’s type, and checks that the key predates the signature. Further constraints on the signature, like creation and expiration time, or signature revocations must be checked by the caller.

Likewise, this function does not check whether signer can made valid signatures; it is up to the caller to make sure the key is not revoked, not expired, has a valid self-signature, has a subkey binding signature (if appropriate), has the signing capability, etc.

Verifies the user id binding.

self is the user id binding signature, signer is the key that allegedly made the signature, pk is the primary key, and userid is the user id.

For a self-signature, signer and pk will be the same.

Note: Due to limited context, this only verifies the cryptographic signature, checks the signature’s type, and checks that the key predates the signature. Further constraints on the signature, like creation and expiration time, or signature revocations must be checked by the caller.

Likewise, this function does not check whether signer can made valid signatures; it is up to the caller to make sure the key is not revoked, not expired, has a valid self-signature, has a subkey binding signature (if appropriate), has the signing capability, etc.

Verifies the user id revocation certificate.

self is the revocation certificate, signer is the key that allegedly made the signature, pk is the primary key, and userid is the user id.

For a self-signature, signer and pk will be the same.

Note: Due to limited context, this only verifies the cryptographic signature, checks the signature’s type, and checks that the key predates the signature. Further constraints on the signature, like creation and expiration time, or signature revocations must be checked by the caller.

Likewise, this function does not check whether signer can made valid signatures; it is up to the caller to make sure the key is not revoked, not expired, has a valid self-signature, has a subkey binding signature (if appropriate), has the signing capability, etc.

Verifies an attested key signature on a user id.

This feature is experimental.

Allows the certificate owner to attest to third party certifications. See Section 5.2.3.30 of RFC 4880bis for details.

self is the attested key signature, signer is the key that allegedly made the signature, pk is the primary key, and userid is the user id.

Note: Due to limited context, this only verifies the cryptographic signature, checks the signature’s type, and checks that the key predates the signature. Further constraints on the signature, like creation and expiration time, or signature revocations must be checked by the caller.

Likewise, this function does not check whether signer can made valid signatures; it is up to the caller to make sure the key is not revoked, not expired, has a valid self-signature, has a subkey binding signature (if appropriate), has the signing capability, etc.

Verifies the user attribute binding.

self is the user attribute binding signature, signer is the key that allegedly made the signature, pk is the primary key, and ua is the user attribute.

For a self-signature, signer and pk will be the same.

Note: Due to limited context, this only verifies the cryptographic signature, checks the signature’s type, and checks that the key predates the signature. Further constraints on the signature, like creation and expiration time, or signature revocations must be checked by the caller.

Likewise, this function does not check whether signer can made valid signatures; it is up to the caller to make sure the key is not revoked, not expired, has a valid self-signature, has a subkey binding signature (if appropriate), has the signing capability, etc.

Verifies the user attribute revocation certificate.

self is the user attribute binding signature, signer is the key that allegedly made the signature, pk is the primary key, and ua is the user attribute.

For a self-signature, signer and pk will be the same.

Note: Due to limited context, this only verifies the cryptographic signature, checks the signature’s type, and checks that the key predates the signature. Further constraints on the signature, like creation and expiration time, or signature revocations must be checked by the caller.

Likewise, this function does not check whether signer can made valid signatures; it is up to the caller to make sure the key is not revoked, not expired, has a valid self-signature, has a subkey binding signature (if appropriate), has the signing capability, etc.

Verifies an attested key signature on a user attribute.

This feature is experimental.

Allows the certificate owner to attest to third party certifications. See Section 5.2.3.30 of RFC 4880bis for details.

self is the attested key signature, signer is the key that allegedly made the signature, pk is the primary key, and ua is the user attribute.

Note: Due to limited context, this only verifies the cryptographic signature, checks the signature’s type, and checks that the key predates the signature. Further constraints on the signature, like creation and expiration time, or signature revocations must be checked by the caller.

Likewise, this function does not check whether signer can made valid signatures; it is up to the caller to make sure the key is not revoked, not expired, has a valid self-signature, has a subkey binding signature (if appropriate), has the signing capability, etc.

Verifies a signature of a message.

self is the message signature, signer is the key that allegedly made the signature and msg is the message.

This function is for short messages, if you want to verify larger files use Verifier.

Note: Due to limited context, this only verifies the cryptographic signature, checks the signature’s type, and checks that the key predates the signature. Further constraints on the signature, like creation and expiration time, or signature revocations must be checked by the caller.

Likewise, this function does not check whether signer can made valid signatures; it is up to the caller to make sure the key is not revoked, not expired, has a valid self-signature, has a subkey binding signature (if appropriate), has the signing capability, etc.

Gets the version.

Methods from Deref<Target = Signature4>

Hashes this signature for use in a Third-Party Confirmation signature.

Gets the public key algorithm.

Gets the hash prefix.

Gets the signature packet’s MPIs.

Gets the computed hash value.

This is set by the PacketParser when parsing the message.

Gets the signature level.

A level of 0 indicates that the signature is directly over the data, a level of 1 means that the signature is a notarization over all level 0 signatures and the data, and so on.

Returns whether or not this signature should be exported.

This checks whether the Exportable Certification subpacket is absent or present and 1, and that the signature does not include any sensitive Revocation Key (designated revokers) subpackets.

Trait Implementations

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

The resulting type after dereferencing.

Dereferences the value.

Mutably dereferences the value.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Updates the given hash with this object.

Feeds this value into the given Hasher. Read more

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

Implement IntoIterator so that cert::insert_packets(sig) just works.

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

Creates an iterator from a value. Read more

Writes a serialized version of the object to o.

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

Computes the maximal length of the serialized representation. Read more

Serializes into the given buffer. Read more

Exports into the given buffer. Read more

Exports to a vector. Read more

Serializes the packet to a vector.

This method returns an Ordering between self and other. Read more

Compares and returns the maximum of two values. Read more

Compares and returns the minimum of two values. Read more

Restrict a value to a certain interval. Read more

Reads from the given reader.

Reads from the given file. Read more

Reads from the given slice. Read more

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

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

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

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Performs the conversion.

Performs the conversion.

Should always be Self

The resulting type after obtaining ownership.

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

🔬 This is a nightly-only experimental API. (toowned_clone_into)

recently added

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

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.