Struct sequoia_openpgp::packet::signature::Builder

pub struct Builder { /* fields omitted */ }

Builds a signature packet.

This is the mutable version of a Signature4 packet. To convert it to one, use sign_hash, sign_message, sign_direct_key, sign_subkey_binding, sign_primary_key_binding, sign_userid_binding, sign_user_attribute_binding, sign_standalone, or sign_timestamp,

Signatures must always include a creation time. We automatically insert a creation time subpacket with the current time into the hashed subpacket area. To override the creation time, use set_signature_creation_time.

Methods

impl Builder

pub fn set_signature_creation_time<T>(self, creation_time: T) -> Result<Self> where
    T: Into<SystemTime>, 

Sets the value of the Creation Time subpacket.

pub fn set_signature_expiration_time(
    self,
    expiration: Option<Duration>
) -> Result<Self>

Sets the value of the Signature Expiration Time subpacket.

If None is given, any expiration subpacket is removed.

pub fn set_exportable_certification(self, exportable: bool) -> Result<Self>

Sets 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).

pub fn set_trust_signature(self, level: u8, trust: u8) -> Result<Self>

Sets the value of the Trust Signature subpacket.

pub fn set_regular_expression<R>(self, re: R) -> Result<Self> where
    R: AsRef<[u8]>, 

Sets the value of the Regular Expression subpacket.

Note: The serialized form includes a trailing NUL byte. Sequoia adds this NUL when serializing the signature. Adding it yourself will result in two trailing NUL bytes.

pub fn set_revocable(self, revocable: bool) -> Result<Self>

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

pub fn set_key_expiration_time(
    self,
    expiration: Option<Duration>
) -> Result<Self>

Sets 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 None is given, any expiration subpacket is removed.

pub fn set_preferred_symmetric_algorithms(
    self,
    preferences: Vec<SymmetricAlgorithm>
) -> Result<Self>

Sets 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.

pub fn set_revocation_key(
    self,
    class: u8,
    pk_algo: PublicKeyAlgorithm,
    fp: Fingerprint
) -> Result<Self>

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

pub fn set_issuer(self, id: KeyID) -> Result<Self>

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

pub fn set_notation<N, V, F>(
    self,
    name: N,
    value: V,
    flags: F,
    critical: bool
) -> Result<Self> where
    N: AsRef<str>,
    V: AsRef<[u8]>,
    F: Into<Option<NotationDataFlags>>, 

Sets the value of the Notation Data subpacket with the given name.

Any existing Notation Data subpacket with the given name are replaced.

pub fn add_notation<N, V, F>(
    self,
    name: N,
    value: V,
    flags: F,
    critical: bool
) -> Result<Self> where
    N: AsRef<str>,
    V: AsRef<[u8]>,
    F: Into<Option<NotationDataFlags>>, 

Adds a Notation Data subpacket with the given name, value, and flags.

Any existing Notation Data subpacket with the given name are kept.

pub fn set_preferred_hash_algorithms(
    self,
    preferences: Vec<HashAlgorithm>
) -> Result<Self>

Sets 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.

pub fn set_preferred_compression_algorithms(
    self,
    preferences: Vec<CompressionAlgorithm>
) -> Result<Self>

Sets 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.

pub fn set_key_server_preferences(
    self,
    preferences: KeyServerPreferences
) -> Result<Self>

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

pub fn set_preferred_key_server<U>(self, uri: U) -> Result<Self> where
    U: AsRef<[u8]>, 

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

pub fn set_primary_userid(self, primary: bool) -> Result<Self>

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

pub fn set_policy_uri<U>(self, uri: U) -> Result<Self> where
    U: AsRef<[u8]>, 

Sets the value of the Policy URI subpacket.

pub fn set_key_flags(self, flags: &KeyFlags) -> Result<Self>

Sets 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).

pub fn set_signers_user_id<U>(self, uid: U) -> Result<Self> where
    U: AsRef<[u8]>, 

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

pub fn set_reason_for_revocation<R>(
    self,
    code: ReasonForRevocation,
    reason: R
) -> Result<Self> where
    R: AsRef<[u8]>, 

Sets the value of the Reason for Revocation subpacket.

pub fn set_features(self, features: &Features) -> Result<Self>

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

pub fn set_signature_target<D>(
    self,
    pk_algo: PublicKeyAlgorithm,
    hash_algo: HashAlgorithm,
    digest: D
) -> Result<Self> where
    D: AsRef<[u8]>, 

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

pub fn set_embedded_signature(self, signature: Signature) -> Result<Self>

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

pub fn set_issuer_fingerprint(self, fp: Fingerprint) -> Result<Self>

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

pub fn set_preferred_aead_algorithms(
    self,
    preferences: Vec<AEADAlgorithm>
) -> Result<Self>

Sets 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.

pub fn set_intended_recipients(
    self,
    recipients: Vec<Fingerprint>
) -> Result<Self>

Sets the intended recipients.

impl Builder

pub fn new(typ: SignatureType) -> Self

Returns a new Builder object.

pub fn version(&self) -> u8

Gets the version.

pub fn typ(&self) -> SignatureType

Gets the signature type.

pub fn set_type(self, t: SignatureType) -> Self

Sets the signature type.

pub fn pk_algo(&self) -> PublicKeyAlgorithm

Gets the public key algorithm.

pub fn hash_algo(&self) -> HashAlgorithm

Gets the hash algorithm.

pub fn set_hash_algo(self, h: HashAlgorithm) -> Self

Sets the hash algorithm.

pub fn sign_standalone(self, signer: &mut dyn Signer) -> Result<Signature>

Creates a standalone signature.

The Signature's public-key algorithm field is set to the algorithm used by signer.

pub fn sign_timestamp(self, signer: &mut dyn Signer) -> Result<Signature>

Creates a timestamp signature.

The Signature's public-key algorithm field is set to the algorithm used by signer.

pub fn sign_direct_key(self, signer: &mut dyn Signer) -> Result<Signature>

Signs signer using itself.

The Signature's public-key algorithm field is set to the algorithm used by signer.

pub fn sign_userid_binding<P>(
    self,
    signer: &mut dyn Signer,
    key: &Key<P, PrimaryRole>,
    userid: &UserID
) -> Result<Signature> where
    P: KeyParts, 

Signs binding between userid and key using signer.

The Signature's public-key algorithm field is set to the algorithm used by signer.

pub fn sign_subkey_binding<P, Q>(
    self,
    signer: &mut dyn Signer,
    primary: &Key<P, PrimaryRole>,
    subkey: &Key<Q, SubordinateRole>
) -> Result<Signature> where
    P: KeyParts,
    Q: KeyParts, 

Signs subkey binding from primary to subkey using signer.

The Signature's public-key algorithm field is set to the algorithm used by signer.

pub fn sign_primary_key_binding<P, Q>(
    self,
    subkey_signer: &mut dyn Signer,
    primary: &Key<P, PrimaryRole>,
    subkey: &Key<Q, SubordinateRole>
) -> Result<Signature> where
    P: KeyParts,
    Q: KeyParts, 

Signs primary key binding from primary to subkey using subkey_signer.

The Signature's public-key algorithm field is set to the algorithm used by subkey_signer.

pub fn sign_user_attribute_binding<P>(
    self,
    signer: &mut dyn Signer,
    key: &Key<P, PrimaryRole>,
    ua: &UserAttribute
) -> Result<Signature> where
    P: KeyParts, 

Signs binding between ua and key using signer.

The Signature's public-key algorithm field is set to the algorithm used by signer.

pub fn sign_hash(
    self,
    signer: &mut dyn Signer,
    hash: Context
) -> Result<Signature>

Signs hash using signer.

The Signature's public-key algorithm field is set to the algorithm used by signer.

pub fn sign_message<M>(
    self,
    signer: &mut dyn Signer,
    msg: M
) -> Result<Signature> where
    M: AsRef<[u8]>, 

Signs message using signer.

The Signature's public-key algorithm field is set to the algorithm used by signer.

Methods from Deref<Target = SubpacketAreas>

pub fn hashed_area(&self) -> &SubpacketArea

Gets a reference to the hashed area.

pub fn hashed_area_mut(&mut self) -> &mut SubpacketArea

Gets a mutable reference to the hashed area.

pub fn unhashed_area(&self) -> &SubpacketArea

Gets a reference to the unhashed area.

pub fn unhashed_area_mut(&mut self) -> &mut SubpacketArea

Gets a mutable reference to the unhashed area.

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

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_alive<P, R, T>(&self, key: &Key<P, R>, t: T) -> Result<()> where
    P: KeyParts,
    R: KeyRole,
    T: Into<Option<SystemTime>>, 

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>

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

Note: for historical reasons this packet is usually stored in the unhashed area of the signature and, consequently, it is not protected by the signature. Thus, it is trivial to modify it in transit. For this reason, the Issuer Fingerprint subpacket should be preferred, when it is present.

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>

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>

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, and the Issuer subpacket is, for historic reasons, traditionally stored in the unhashed area, i.e., it is not cryptographically secured.

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.

Trait Implementations

impl Clone for Builder

fn clone(&self) -> Builder

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Deref for Builder

type Target = SubpacketAreas

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for Builder

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl Eq for Builder

impl<'a> From<&'a Signature> for &'a Builder

fn from(sig: &'a Signature) -> Self

Performs the conversion.

impl<'a> From<&'a Signature4> for &'a Builder

fn from(sig: &'a Signature4) -> Self

Performs the conversion.

impl From<Signature> for Builder

fn from(sig: Signature) -> Self

Performs the conversion.

impl From<Signature4> for Builder

fn from(sig: Signature4) -> Self

Performs the conversion.

impl Hash for Builder

fn hash(&self, hash: &mut Context)

Adds the Signature to the provided hash context.

impl Hash for Builder

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

Feeds this value into the given [Hasher].

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

Feeds a slice of this type into the given [Hasher].

impl PartialEq<Builder> for Builder

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

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

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

This method tests for !=.

impl StructuralEq for Builder

impl StructuralPartialEq for Builder