Struct sequoia_openpgp::cert::amalgamation::ValidComponentAmalgamation

pub struct ValidComponentAmalgamation<'a, C> { /* fields omitted */ }

A ComponentAmalgamation plus a Policy and a reference time.

A ValidComponentAmalgamation combines a ComponentAmalgamation with a Policy and a reference time. This allows it to implement the ValidAmalgamation trait, which provides methods that require a Policy and a reference time. Although ComponentAmalgamation could implement these methods by requiring that the caller explicitly pass them in, embedding them in the ValidComponentAmalgamation helps ensure that multipart operations, even those that span multiple functions, use the same Policy and reference time.

A ValidComponentAmalgamation is typically obtained by transforming a ComponentAmalgamation using ValidateAmalgamation::with_policy. A ComponentAmalgamationIter can also be changed to yield ValidComponentAmalgamations.

A ValidComponentAmalgamation is guaranteed to come from a valid certificate, and have a valid and live binding signature at the specified reference time. Note: this only means that the binding signatures are live; it says nothing about whether the certificate is live. If you care about that, then you need to check it separately.

Examples

Print out information about all non-revoked User IDs.

use openpgp::cert::prelude::*;
use openpgp::packet::prelude::*;
use openpgp::policy::StandardPolicy;
use openpgp::types::RevocationStatus;

let p = &StandardPolicy::new();
for u in cert.userids() {
    // Create a `ValidComponentAmalgamation`.  This may fail if
    // there are no binding signatures that are accepted by the
    // policy and that are live right now.
    let u = u.with_policy(p, None)?;

    // Before using the User ID, we still need to check that it is
    // not revoked; `ComponentAmalgamation::with_policy` ensures
    // that there is a valid *binding signature*, not that the
    // `ComponentAmalgamation` is valid.
    //
    // Note: `ValidComponentAmalgamation::revocation_status` and
    // `Preferences::preferred_symmetric_algorithms` use the
    // embedded policy and timestamp.  Even though we used `None` for
    // the timestamp (i.e., now), they are guaranteed to use the same
    // timestamp, because `with_policy` eagerly transforms it into
    // the current time.
    //
    // Note: we only check whether the User ID is not revoked.  If
    // we were using a key, we'd also want to check that it is alive.
    // (Keys can expire, but User IDs cannot.)
    if let RevocationStatus::Revoked(_revs) = u.revocation_status() {
        // Revoked by the key owner.  (If we care about
        // designated revokers, then we need to check those
        // ourselves.)
    } else {
        // Print information about the User ID.
        eprintln!("{}: preferred symmetric algorithms: {:?}",
                  String::from_utf8_lossy(u.value()),
                  u.preferred_symmetric_algorithms());
    }
}

Methods from Deref<Target = ComponentAmalgamation<'a, C>>

pub fn parts_as_public(
    &'a self
) -> &'a ComponentAmalgamation<'a, Key<PublicParts, R>>

Changes the key's parts tag to PublicParts.

pub fn parts_as_secret(
    &'a self
) -> Result<&'a ComponentAmalgamation<'a, Key<SecretParts, R>>>

Changes the key's parts tag to SecretParts.

pub fn parts_as_unspecified(
    &'a self
) -> &ComponentAmalgamation<'a, Key<UnspecifiedParts, R>>

Changes the key's parts tag to UnspecifiedParts.

pub fn role_as_primary(
    &'a self
) -> &'a ComponentAmalgamation<'a, Key<P, PrimaryRole>>

Changes the key's role tag to PrimaryRole.

pub fn role_as_subordinate(
    &'a self
) -> &'a ComponentAmalgamation<'a, Key<P, SubordinateRole>>

Changes the key's role tag to SubordinateRole.

pub fn role_as_unspecified(
    &'a self
) -> &'a ComponentAmalgamation<'a, Key<P, UnspecifiedRole>>

Changes the key's role tag to UnspecifiedRole.

pub fn cert(&self) -> &'a Cert

Returns the component's associated certificate.

for u in cert.userids() {
    // It's not only an identical `Cert`, it's the same one.
    assert!(std::ptr::eq(u.cert(), &cert));
}

pub fn bundle(&self) -> &'a ComponentBundle<C>

Returns this amalgamation's bundle.

Note: although ComponentAmalgamation derefs to a &ComponentBundle, this method provides a more accurate lifetime, which is helpful when returning the reference from a function. See the module's documentation for more details.

Examples

use openpgp::cert::prelude::*;
use openpgp::packet::prelude::*;

cert.userids()
    .map(|ua| {
        // The following doesn't work:
        //
        //   let b: &ComponentBundle<_> = &ua; b
        //
        // Because ua's lifetime is this closure and autoderef
        // assigns `b` the same lifetime as `ua`.  `bundle()`,
        // however, returns a reference whose lifetime is that
        // of `cert`.
        ua.bundle()
    })
    .collect::<Vec<&ComponentBundle<_>>>();

pub fn component(&self) -> &'a C

Returns this amalgamation's component.

Note: although ComponentAmalgamation derefs to a &Component (via &ComponentBundle), this method provides a more accurate lifetime, which is helpful when returning the reference from a function. See the module's documentation for more details.

pub fn self_signatures(&self) -> &'a [Signature]

The component's self-signatures.

This method is a forwarder for ComponentBundle::self_signatures. Although ComponentAmalgamation derefs to a &ComponentBundle, this method provides a more accurate lifetime, which is helpful when returning the reference from a function. See the module's documentation for more details.

pub fn certifications(&self) -> &'a [Signature]

The component's third-party certifications.

This method is a forwarder for ComponentBundle::certifications. Although ComponentAmalgamation derefs to a &ComponentBundle, this method provides a more accurate lifetime, which is helpful when returning the reference from a function. See the module's documentation for more details.

pub fn self_revocations(&self) -> &'a [Signature]

The component's revocations that were issued by the certificate holder.

This method is a forwarder for ComponentBundle::self_revocations. Although ComponentAmalgamation derefs to a &ComponentBundle, this method provides a more accurate lifetime, which is helpful when returning the reference from a function. See the module's documentation for more details.

pub fn other_revocations(&self) -> &'a [Signature]

The component's revocations that were issued by other certificates.

This method is a forwarder for ComponentBundle::other_revocations. Although ComponentAmalgamation derefs to a &ComponentBundle, this method provides a more accurate lifetime, which is helpful when returning the reference from a function. See the module's documentation for more details.

pub fn revocation_keys(
    &self,
    policy: &dyn Policy
) -> Box<dyn Iterator<Item = &'a RevocationKey> + 'a>

Returns a list of any designated revokers for this component.

This function returns the designated revokers listed on both this component's binding signature and the certificate's direct key signature.

Note: the returned list is deduplicated.

Examples

use openpgp::cert::prelude::*;
use openpgp::policy::StandardPolicy;
use openpgp::types::RevocationKey;

let p = &StandardPolicy::new();

let (alice, _) =
    CertBuilder::general_purpose(None, Some("alice@example.org"))
    .generate()?;
// Make Alice a designated revoker for Bob.
let (bob, _) =
    CertBuilder::general_purpose(None, Some("bob@example.org"))
    .set_revocation_keys(vec![(&alice).into()])
    .generate()?;

// Make sure Alice is listed as a designated revoker for Bob
// on a component.
assert_eq!(bob.with_policy(p, None)?.primary_userid()?.revocation_keys(p)
               .collect::<Vec<&RevocationKey>>(),
           vec![&(&alice).into()]);

pub fn userid(&self) -> &'a UserID

Returns a reference to the User ID.

Note: although ComponentAmalgamation<UserID> derefs to a &UserID (via &ComponentBundle), this method provides a more accurate lifetime, which is helpful when returning the reference from a function. See the module's documentation for more details.

pub fn user_attribute(&self) -> &'a UserAttribute

Returns a reference to the User Attribute.

Note: although ComponentAmalgamation<UserAttribute> derefs to a &UserAttribute (via &ComponentBundle), this method provides a more accurate lifetime, which is helpful when returning the reference from a function. See the module's documentation for more details.

Trait Implementations

impl<'a, C> Clone for ValidComponentAmalgamation<'a, C>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a, C: Debug> Debug for ValidComponentAmalgamation<'a, C>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<'a, C> Deref for ValidComponentAmalgamation<'a, C>

type Target = ComponentAmalgamation<'a, C>

The resulting type after dereferencing.

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

Dereferences the value.

impl<'a, C: 'a> From<ValidComponentAmalgamation<'a, C>> for ComponentAmalgamation<'a, C>

fn from(vca: ValidComponentAmalgamation<'a, C>) -> Self

Performs the conversion.

impl<'a, C> Preferences<'a> for ValidComponentAmalgamation<'a, C>

fn preferred_symmetric_algorithms(&self) -> Option<&'a [SymmetricAlgorithm]>

Returns the supported symmetric algorithms ordered by preference.

fn preferred_hash_algorithms(&self) -> Option<&'a [HashAlgorithm]>

Returns the supported hash algorithms ordered by preference.

fn preferred_compression_algorithms(&self) -> Option<&'a [CompressionAlgorithm]>

Returns the supported compression algorithms ordered by preference.

fn preferred_aead_algorithms(&self) -> Option<&'a [AEADAlgorithm]>

Returns the supported AEAD algorithms ordered by preference.

fn key_server_preferences(&self) -> Option<KeyServerPreferences>

Returns the certificate holder's keyserver preferences.

fn preferred_key_server(&self) -> Option<&'a [u8]>

Returns the certificate holder's preferred keyserver for updates.

fn features(&self) -> Option<Features>

Returns the certificate holder's feature set.

impl<'a, C> ValidAmalgamation<'a, C> for ValidComponentAmalgamation<'a, C>

fn cert(&self) -> &ValidCert<'a>

Returns the valid amalgamation's associated certificate.

fn time(&self) -> SystemTime

Returns the amalgamation's reference time.

fn policy(&self) -> &'a dyn Policy

Returns the amalgamation's policy.

fn binding_signature(&self) -> &'a Signature

Returns the component's binding signature as of the reference time.

fn revocation_status(&self) -> RevocationStatus<'a>

Returns the component's revocation status as of the amalgamation's reference time.

fn map<F: Fn(&'a Signature) -> Option<T>, T>(&self, f: F) -> Option<T>

Maps the given function over binding and direct key signature.

fn direct_key_signature(&self) -> Result<&'a Signature>

Returns the certificate's direct key signature as of the reference time, if any.

impl<'a, C> ValidateAmalgamation<'a, C> for ValidComponentAmalgamation<'a, C>

type V = Self

The type returned by with_policy.

fn with_policy<T>(self, policy: &'a dyn Policy, time: T) -> Result<Self::V> where
    T: Into<Option<SystemTime>>,
    Self: Sized, 

Uses the specified Policy and reference time with the amalgamation.