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
V4(Signature4)Signature packet version 4.
Tuple Fields of V4
0: Signature4Implementations
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::IssuerSubpacketValue::IssuerFingerprintSubpacketValue::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
selfcommonly found in unhashed areas - Unauthenticated subpackets from
othercommonly found in unhashed areas - Remaining subpackets from
self - Remaining subpackets from
other
See
Subpacket::authenticatedfor how subpackets are authenticated. Subpackets commonly found in unhashed areas are issuer information and embedded signatures. - Authenticated subpackets from
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.
pub fn verify_direct_key<P, Q, R>(
&mut self,
signer: &Key<P, R>,
pk: &Key<Q, PrimaryRole>
) -> Result<()> where
P: KeyParts,
Q: KeyParts,
R: KeyRole,
pub fn verify_direct_key<P, Q, R>(
&mut self,
signer: &Key<P, R>,
pk: &Key<Q, PrimaryRole>
) -> Result<()> where
P: KeyParts,
Q: KeyParts,
R: KeyRole,
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.
pub fn verify_primary_key_revocation<P, Q, R>(
&mut self,
signer: &Key<P, R>,
pk: &Key<Q, PrimaryRole>
) -> Result<()> where
P: KeyParts,
Q: KeyParts,
R: KeyRole,
pub fn verify_primary_key_revocation<P, Q, R>(
&mut self,
signer: &Key<P, R>,
pk: &Key<Q, PrimaryRole>
) -> Result<()> where
P: KeyParts,
Q: KeyParts,
R: KeyRole,
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.
pub fn verify_subkey_binding<P, Q, R, S>(
&mut self,
signer: &Key<P, R>,
pk: &Key<Q, PrimaryRole>,
subkey: &Key<S, SubordinateRole>
) -> Result<()> where
P: KeyParts,
Q: KeyParts,
R: KeyRole,
S: KeyParts,
pub fn verify_subkey_binding<P, Q, R, S>(
&mut self,
signer: &Key<P, R>,
pk: &Key<Q, PrimaryRole>,
subkey: &Key<S, SubordinateRole>
) -> Result<()> where
P: KeyParts,
Q: KeyParts,
R: KeyRole,
S: KeyParts,
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.
pub fn verify_primary_key_binding<P, Q>(
&mut self,
pk: &Key<P, PrimaryRole>,
subkey: &Key<Q, SubordinateRole>
) -> Result<()> where
P: KeyParts,
Q: KeyParts,
pub fn verify_primary_key_binding<P, Q>(
&mut self,
pk: &Key<P, PrimaryRole>,
subkey: &Key<Q, SubordinateRole>
) -> Result<()> where
P: KeyParts,
Q: KeyParts,
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.
pub fn verify_subkey_revocation<P, Q, R, S>(
&mut self,
signer: &Key<P, R>,
pk: &Key<Q, PrimaryRole>,
subkey: &Key<S, SubordinateRole>
) -> Result<()> where
P: KeyParts,
Q: KeyParts,
R: KeyRole,
S: KeyParts,
pub fn verify_subkey_revocation<P, Q, R, S>(
&mut self,
signer: &Key<P, R>,
pk: &Key<Q, PrimaryRole>,
subkey: &Key<S, SubordinateRole>
) -> Result<()> where
P: KeyParts,
Q: KeyParts,
R: KeyRole,
S: KeyParts,
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.
pub fn verify_user_attribute_binding<P, Q, R>(
&mut self,
signer: &Key<P, R>,
pk: &Key<Q, PrimaryRole>,
ua: &UserAttribute
) -> Result<()> where
P: KeyParts,
Q: KeyParts,
R: KeyRole,
pub fn verify_user_attribute_binding<P, Q, R>(
&mut self,
signer: &Key<P, R>,
pk: &Key<Q, PrimaryRole>,
ua: &UserAttribute
) -> Result<()> where
P: KeyParts,
Q: KeyParts,
R: KeyRole,
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.
pub fn verify_user_attribute_revocation<P, Q, R>(
&mut self,
signer: &Key<P, R>,
pk: &Key<Q, PrimaryRole>,
ua: &UserAttribute
) -> Result<()> where
P: KeyParts,
Q: KeyParts,
R: KeyRole,
pub fn verify_user_attribute_revocation<P, Q, R>(
&mut self,
signer: &Key<P, R>,
pk: &Key<Q, PrimaryRole>,
ua: &UserAttribute
) -> Result<()> where
P: KeyParts,
Q: KeyParts,
R: KeyRole,
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.
pub fn verify_user_attribute_attestation<P, Q, R>(
&mut self,
signer: &Key<P, R>,
pk: &Key<Q, PrimaryRole>,
ua: &UserAttribute
) -> Result<()> where
P: KeyParts,
Q: KeyParts,
R: KeyRole,
pub fn verify_user_attribute_attestation<P, Q, R>(
&mut self,
signer: &Key<P, R>,
pk: &Key<Q, PrimaryRole>,
ua: &UserAttribute
) -> Result<()> where
P: KeyParts,
Q: KeyParts,
R: KeyRole,
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.
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 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
type Target = Signature4
type Target = Signature4
The resulting type after dereferencing.
Performs the conversion.
Implement IntoIterator so that
cert::insert_packets(sig) just works.
Reads from the given reader.
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 Signature
impl UnwindSafe for Signature
Blanket Implementations
Mutably borrows from an owned value. Read more