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

pub enum Signature {
    V4(Signature4),
    // some variants omitted
}

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

Signature packet version 4.

Implementations

impl Signature[src]

Hashing-related functionality.

pub fn hash_standalone(sig: &SignatureFields) -> Result<Vec<u8>>[src]

Computes the message digest of standalone signatures.

pub fn hash_timestamp(sig: &SignatureFields) -> Result<Vec<u8>>[src]

Computes the message digest of timestamp signatures.

pub fn hash_direct_key<P>(
    sig: &SignatureFields,
    key: &Key<P, PrimaryRole>
) -> Result<Vec<u8>> where
    P: KeyParts
[src]

Returns the message digest of the direct key signature over the specified primary key.

pub fn hash_subkey_binding<P, Q>(
    sig: &SignatureFields,
    key: &Key<P, PrimaryRole>,
    subkey: &Key<Q, SubordinateRole>
) -> Result<Vec<u8>> where
    P: KeyParts,
    Q: KeyParts
[src]

Returns the message digest of the subkey binding over the specified primary key and subkey.

pub fn hash_primary_key_binding<P, Q>(
    sig: &SignatureFields,
    key: &Key<P, PrimaryRole>,
    subkey: &Key<Q, SubordinateRole>
) -> Result<Vec<u8>> where
    P: KeyParts,
    Q: KeyParts
[src]

Returns the message digest of the primary key binding over the specified primary key and subkey.

pub fn hash_userid_binding<P>(
    sig: &SignatureFields,
    key: &Key<P, PrimaryRole>,
    userid: &UserID
) -> Result<Vec<u8>> where
    P: KeyParts
[src]

Returns the message digest of the user ID binding over the specified primary key, user ID, and signature.

pub fn hash_user_attribute_binding<P>(
    sig: &SignatureFields,
    key: &Key<P, PrimaryRole>,
    ua: &UserAttribute
) -> Result<Vec<u8>> where
    P: KeyParts
[src]

Returns the message digest of the user attribute binding over the specified primary key, user attribute, and signature.

impl Signature[src]

pub fn get_issuers(&self) -> Vec<KeyHandle>[src]

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.

pub fn normalized_eq(&self, other: &Signature) -> bool[src]

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.

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

pub fn normalized_cmp(&self, other: &Signature) -> Ordering[src]

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.

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

pub fn normalize(&self) -> Self[src]

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.

pub fn add_missing_issuers(&mut self) -> Result<()>[src]

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.

pub fn merge(self, other: Signature) -> Result<Signature>[src]

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.

impl Signature[src]

Verification-related functionality.

pub fn verify_hash<P, R>(
    &mut self,
    key: &Key<P, R>,
    hash: Context
) -> Result<()> where
    P: KeyParts,
    R: KeyRole
[src]

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.

pub fn verify_digest<P, R, D>(
    &mut self,
    key: &Key<P, R>,
    digest: D
) -> Result<()> where
    P: KeyParts,
    R: KeyRole,
    D: AsRef<[u8]>, 
[src]

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.

pub fn verify<P, R>(&mut self, key: &Key<P, R>) -> Result<()> where
    P: KeyParts,
    R: KeyRole
[src]

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.

pub fn verify_standalone<P, R>(&mut self, key: &Key<P, R>) -> Result<()> where
    P: KeyParts,
    R: KeyRole
[src]

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.

pub fn verify_timestamp<P, R>(&mut self, key: &Key<P, R>) -> Result<()> where
    P: KeyParts,
    R: KeyRole
[src]

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
[src]

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
[src]

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
[src]

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
[src]

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
[src]

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.

pub fn verify_userid_binding<P, Q, R>(
    &mut self,
    signer: &Key<P, R>,
    pk: &Key<Q, PrimaryRole>,
    userid: &UserID
) -> Result<()> where
    P: KeyParts,
    Q: KeyParts,
    R: KeyRole
[src]

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.

pub fn verify_userid_revocation<P, Q, R>(
    &mut self,
    signer: &Key<P, R>,
    pk: &Key<Q, PrimaryRole>,
    userid: &UserID
) -> Result<()> where
    P: KeyParts,
    Q: KeyParts,
    R: KeyRole
[src]

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.

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
[src]

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
[src]

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_message<M, P, R>(
    &mut self,
    signer: &Key<P, R>,
    msg: M
) -> Result<()> where
    M: AsRef<[u8]>,
    P: KeyParts,
    R: KeyRole
[src]

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.

impl Signature[src]

pub fn version(&self) -> u8[src]

Gets the version.

Methods from Deref<Target = Signature4>

pub fn pk_algo(&self) -> PublicKeyAlgorithm[src]

Gets the public key algorithm.

pub fn digest_prefix(&self) -> &[u8; 2][src]

Gets the hash prefix.

pub fn mpis(&self) -> &Signature[src]

Gets the signature packet's MPIs.

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

Gets the computed hash value.

This is set by the PacketParser when parsing the message.

pub fn level(&self) -> usize[src]

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.

pub fn exportable(&self) -> Result<()>[src]

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

impl Clone for Signature[src]

impl Debug for Signature[src]

impl Deref for Signature[src]

type Target = Signature4

The resulting type after dereferencing.

impl DerefMut for Signature[src]

impl Eq for Signature[src]

impl From<Signature> for SignatureBuilder[src]

impl From<Signature> for Packet[src]

impl From<Signature4> for Signature[src]

impl Hash for Signature[src]

impl Hash for Signature[src]

impl IntoIterator for Signature[src]

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

type Item = Signature

The type of the elements being iterated over.

type IntoIter = Once<Signature>

Which kind of iterator are we turning this into?

impl Marshal for Signature[src]

impl MarshalInto for Signature[src]

impl Ord for Signature[src]

impl<'a> Parse<'a, Signature> for Signature[src]

impl PartialEq<Signature> for Signature[src]

impl PartialOrd<Signature> for Signature[src]

impl StructuralEq for Signature[src]

impl StructuralPartialEq for Signature[src]

impl<'a> TryFrom<&'a Signature> for OnePassSig3[src]

type Error = Error

The type returned in the event of a conversion error.

impl TryFrom<Signature> for Signature4[src]

type Error = Error

The type returned in the event of a conversion error.

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<I> IntoIterator for I where
    I: Iterator
[src]

type Item = <I as Iterator>::Item

The type of the elements being iterated over.

type IntoIter = I

Which kind of iterator are we turning this into?

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.