Struct sequoia_openpgp::packet::signature::SignatureBuilder

pub struct SignatureBuilder { /* 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,

When finalizing the SignatureBuilder, an Issuer subpacket and an IssuerFingerprint subpacket referencing the signing key are added to the unhashed subpacket area if neither an Issuer subpacket nor an IssuerFingerprint subpacket is present in either of the subpacket areas. Note: when converting a Signature to a SignatureBuilder, any Issuer subpackets or IssuerFingerprint subpackets are removed. Caution: using the wrong issuer, or not including an issuer at all will make the signature unverifiable by most OpenPGP implementations.

According to Section 5.2.3.4 of RFC 4880, Signatures must include a Signature Creation Time subpacket. When finalizing a SignatureBuilder, we automatically insert a creation time subpacket with the current time into the hashed subpacket area. To override this behavior, use set_signature_creation_time. Note: when converting an existing Signature into a SignatureBuilder, any existing Signature Creation Time subpackets are removed.

Implementations

impl SignatureBuilder

pub fn modify_unhashed_area<F>(self, f: F) -> Result<Self> where
    F: FnOnce(SubpacketArea) -> Result<SubpacketArea>, 

Modifies the unhashed subpacket area.

This method provides a builder-style interface for modifying the unhashed subpacket area.

Normally, to modify a subpacket area in a non-standard way (that is, when there are no subpacket-specific function like SignatureBuilder::set_signature_validity_period that implement the required functionality), you need to do something like the following:

let mut builder = SignatureBuilder::new(SignatureType::Binary)
    // Build up the signature.
    ;
builder.unhashed_area_mut().add(Subpacket::new(
        SubpacketValue::Unknown {
            tag: SubpacketTag::Private(61),
            body: [ 0x6D, 0x6F, 0x6F ].to_vec(),
        },
        true)?)?;
let sig = builder.sign_message(&mut signer, msg)?;

This is necessary, because modifying the subpacket area doesn't follow the builder pattern like the surrounding code. Using this function, you can instead do:

let sig = SignatureBuilder::new(SignatureType::Binary)
    // Call some setters.
    .modify_unhashed_area(|mut a| {
        a.add(Subpacket::new(
            SubpacketValue::Unknown {
                tag: SubpacketTag::Private(61),
                body: [ 0x6D, 0x6F, 0x6F ].to_vec(),
            },
            true)?);
        Ok(a)
    })?
   .sign_message(&mut signer, msg)?;

If you are only interested in modifying an existing signature's unhashed area, it may be better to simply modify the signature in place using Signature4::modify_unhashed_area rather than to create a new signature, because modifying the unhashed area doesn't invalidate any existing signature.

Examples

Create a signature with a custom, non-critical subpacket in the unhashed area:

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

let (cert, _) =
    CertBuilder::general_purpose(None, Some("alice@example.org"))
    .generate()?;
let mut signer = cert.primary_key().key().clone().parts_into_secret()?.into_keypair()?;

let msg = b"Hello, World";

let sig = SignatureBuilder::new(SignatureType::Binary)
    // Call some setters.
    .modify_unhashed_area(|mut a| {
        a.add(Subpacket::new(
            SubpacketValue::Unknown {
                tag: SubpacketTag::Private(61),
                body: [ 0x6D, 0x6F, 0x6F ].to_vec(),
            },
            true)?);
        Ok(a)
    })?
   .sign_message(&mut signer, msg)?;

pub fn modify_hashed_area<F>(self, f: F) -> Result<Self> where
    F: FnOnce(SubpacketArea) -> Result<SubpacketArea>, 

Modifies the hashed subpacket area.

This method provides a builder-style interface for modifying the hashed subpacket area.

Normally, to modify a subpacket area in a non-standard way (that is, when there are no subpacket-specific function like SignatureBuilder::set_signature_validity_period that implement the required functionality), you need to do something like the following:

let mut builder = SignatureBuilder::new(SignatureType::Binary)
    // Build up the signature.
    ;
builder.hashed_area_mut().add(Subpacket::new(
        SubpacketValue::Unknown {
            tag: SubpacketTag::Private(61),
            body: [ 0x6D, 0x6F, 0x6F ].to_vec(),
        },
        true)?)?;
let sig = builder.sign_message(&mut signer, msg)?;

This is necessary, because modifying the subpacket area doesn't follow the builder pattern like the surrounding code. Using this function, you can instead do:

let sig = SignatureBuilder::new(SignatureType::Binary)
    // Call some setters.
    .modify_hashed_area(|mut a| {
        a.add(Subpacket::new(
            SubpacketValue::Unknown {
                tag: SubpacketTag::Private(61),
                body: [ 0x6D, 0x6F, 0x6F ].to_vec(),
            },
            true)?);
        Ok(a)
    })?
   .sign_message(&mut signer, msg)?;

Examples

Add a critical, custom subpacket to a certificate's direct key signature:

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

let p = &StandardPolicy::new();

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

// Derive a signer (the primary key is always certification capable).
let pk = cert.primary_key().key();
let mut signer = pk.clone().parts_into_secret()?.into_keypair()?;

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

let sig = vc.direct_key_signature().expect("direct key signature");
let sig = SignatureBuilder::from(sig.clone())
    .modify_hashed_area(|mut a| {
        a.add(Subpacket::new(
            SubpacketValue::Unknown {
                tag: SubpacketTag::Private(61),
                body: [ 0x6D, 0x6F, 0x6F ].to_vec(),
            },
            true)?)?;
        Ok(a)
    })?
    .sign_direct_key(&mut signer, pk)?;

// Merge in the new signature.
let cert = cert.merge_packets(sig)?;

Update a certificate's feature set by updating the Features subpacket on any direct key signature, and any User ID binding signatures:

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::Features;

let p = &StandardPolicy::new();

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

// Derive a signer (the primary key is always certification capable).
let pk = cert.primary_key().key();
let mut signer = pk.clone().parts_into_secret()?.into_keypair()?;

let mut sigs = Vec::new();

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

if let Ok(sig) = vc.direct_key_signature() {
    sigs.push(SignatureBuilder::from(sig.clone())
        .modify_hashed_area(|mut a| {
            a.replace(Subpacket::new(
                SubpacketValue::Features(Features::sequoia().set(10)),
                false)?)?;
            Ok(a)
        })?
        // Update the direct key signature.
        .sign_direct_key(&mut signer, pk)?);
}

for ua in vc.userids() {
    sigs.push(SignatureBuilder::from(ua.binding_signature().clone())
        .modify_hashed_area(|mut a| {
            a.replace(Subpacket::new(
                SubpacketValue::Features(Features::sequoia().set(10)),
                false)?)?;
            Ok(a)
        })?
        // Update the direct key signature.
        .sign_userid_binding(&mut signer, pk, ua.userid())?);
}

// Merge in the new signatures.
let cert = cert.merge_packets(sigs.into_iter().map(Packet::from))?;

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 preserve_signature_creation_time(self) -> Result<Self>

Causes the builder to use an existing signature creation time subpacket.

Unless SignatureBuilder::set_signature_creation_time has been called, SignatureBuilder sets the SignatureCreationTime subpacket when the signature is generated. Calling this function causes the signature generation code to use the existing Signature Creation Time subpacket.

This function returns an error if there is no Signature Creation Time subpacket in the hashed area.

pub fn suppress_signature_creation_time(self) -> Result<Self>

Causes the builder to not output a signature creation time subpacket.

Section 5.2.3.4 of RFC 4880 says that the Signature Creation Time subpacket must be present in the hashed area. This function clears any Signature Creation Time subpackets from both the hashed area and the unhashed are, and causes the various SignatureBuilder finalizers to not emit a Signature Creation Time subpacket. This function should only be used for testing purposes.

pub fn set_signature_validity_period<D>(self, expires_in: D) -> Result<Self> where
    D: Into<Duration>, 

Sets the value of the Signature Expiration Time subpacket.

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_validity_period(
    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_key_expiration_time<P, R>(
    self,
    key: &Key<P, R>,
    expiration: Option<SystemTime>
) -> Result<Self> where
    P: KeyParts,
    R: KeyRole, 

Sets the value of the Key Expiration Time subpacket.

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, rk: Vec<RevocationKey>) -> 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.

Caution: By default, the issuer is set correctly when creating the signature. Only use this function to override it.

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

Adds an Issuer subpacket.

Adds an Issuer subpacket to the unhashed subpacket area. Unlike set_issuer, this function does not first remove any Issuer subpackets from the unhashed subpacket area.

Caution: By default, the issuer is set correctly when creating the signature. Only use this function to override it.

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 subpackets with the given name are replaced.

The name falls into two namespaces: The user namespace and the IETF namespace. Names in the user namespace have the form name@example.org and are managed by the owner of the domain. Names in the IETF namespace may not contain an @ and are managed by IANA. See Section 5.2.3.16 of RFC 4880 for details.

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 subpackets with the given name are kept.

The name falls into two namespaces: The user namespace and the IETF namespace. Names in the user namespace have the form name@example.org and are managed by the owner of the domain. Names in the IETF namespace may not contain an @ and are managed by IANA. See Section 5.2.3.16 of RFC 4880 for details.

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.

Caution: By default, the issuer fingerprint is set correctly when creating the signature. Only use this function to override it.

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

Adds an Issuer Fingerprint subpacket.

Adds an Issuer Fingerprint subpacket to the unhashed subpacket area. Unlike set_issuer_fingerprint, this function does not first remove any existing Issuer Fingerprint subpackets from the unhashed subpacket area.

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.

pub fn add_intended_recipient<T>(self, recipient: T) -> Result<Self> where
    T: AsRef<Fingerprint>, 

Adds an Intended Recipient subpacket.

Adds any Intended Recipient subpacket to the hashed subpacket area. Unlike set_intended_recipients, this function does not first removes any Intended Recipient subpackets from the hashed subpacket area.

impl SignatureBuilder

pub fn new(typ: SignatureType) -> Self

Returns a new SignatureBuilder object.

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

Sets the signature type.

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. If not set before, Issuer and Issuer Fingerprint subpackets are added pointing to 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. If not set before, Issuer and Issuer Fingerprint subpackets are added pointing to signer.

pub fn sign_direct_key<P>(
    self,
    signer: &mut dyn Signer,
    pk: &Key<P, PrimaryRole>
) -> Result<Signature> where
    P: KeyParts, 

Signs signer using itself.

The Signature's public-key algorithm field is set to the algorithm used by signer. If not set before, Issuer and Issuer Fingerprint subpackets are added pointing to 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. If not set before, Issuer and Issuer Fingerprint subpackets are added pointing to 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. If not set before, Issuer and Issuer Fingerprint subpackets are added pointing to 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. If not set before, Issuer and Issuer Fingerprint subpackets are added pointing to 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. If not set before, Issuer and Issuer Fingerprint subpackets are added pointing to signer.

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

Signs hash using signer.

This sets the hash algorithm to whatever 'hash's algorithm is.

The Signature's public-key algorithm field is set to the algorithm used by signer. If not set before, Issuer and Issuer Fingerprint subpackets are added pointing to 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. If not set before, Issuer and Issuer Fingerprint subpackets are added pointing to signer.

Methods from Deref<Target = SignatureFields>

pub fn version(&self) -> u8

Gets the version.

pub fn typ(&self) -> SignatureType

Gets the signature type.

pub fn hash_algo(&self) -> HashAlgorithm

Gets the hash algorithm.

Trait Implementations

impl Clone for SignatureBuilder

fn clone(&self) -> SignatureBuilder

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Deref for SignatureBuilder

type Target = SignatureFields

The resulting type after dereferencing.

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

Dereferences the value.

impl DerefMut for SignatureBuilder

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

Mutably dereferences the value.

impl Eq for SignatureBuilder

impl From<Signature> for SignatureBuilder

fn from(sig: Signature) -> Self

Performs the conversion.

impl From<Signature4> for SignatureBuilder

fn from(sig: Signature4) -> Self

Performs the conversion.

impl Hash for SignatureBuilder

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<SignatureBuilder> for SignatureBuilder

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

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

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

This method tests for !=.

impl StructuralEq for SignatureBuilder

impl StructuralPartialEq for SignatureBuilder