[][src]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());
    }
}

Implementations

impl<'a> ValidComponentAmalgamation<'a, UserID>[src]

pub fn attested_certifications(
    &self
) -> impl Iterator<Item = &Signature> + Send + Sync
[src]

Returns the userid's attested third-party certifications.

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. This can be used to address certificate flooding concerns.

This method only returns signatures that are valid under the current policy and are attested by the certificate holder.

pub fn attestation_key_signatures(
    &'a self
) -> impl Iterator<Item = &'a Signature> + Send + Sync
[src]

Returns set of active attestation key signatures.

This feature is experimental.

Returns the set of signatures with the newest valid signature creation time. Older signatures are not returned. The sum of all digests in these signatures are the set of attested third-party certifications.

This interface is useful for pruning old attestation key signatures when filtering a certificate.

Note: This is a low-level interface. Consider using ValidUserIDAmalgamation::attested_certifications to iterate over all attested certifications.

pub fn attest_certifications<C, S>(
    &self,
    primary_signer: &mut dyn Signer,
    certifications: C
) -> Result<Vec<Signature>> where
    C: IntoIterator<Item = S>,
    S: Borrow<Signature>, 
[src]

Attests to third-party certifications.

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. This can be used to address certificate flooding concerns.

Examples

let (alice, _) = CertBuilder::new()
    .add_userid("alice@example.org")
    .generate()?;
let mut alice_signer =
    alice.primary_key().key().clone().parts_into_secret()?
    .into_keypair()?;

let (bob, _) = CertBuilder::new()
    .add_userid("bob@example.org")
    .generate()?;
let mut bob_signer =
    bob.primary_key().key().clone().parts_into_secret()?
    .into_keypair()?;
let bob_pristine = bob.clone();

// Have Alice certify the binding between "bob@example.org" and
// Bob's key.
let alice_certifies_bob
    = bob.userids().next().unwrap().userid().bind(
        &mut alice_signer, &bob,
        SignatureBuilder::new(SignatureType::GenericCertification))?;
let bob = bob.insert_packets(vec![alice_certifies_bob.clone()])?;

// Have Bob attest that certification.
let bobs_uid = bob.userids().next().unwrap();
let attestations =
    bobs_uid.attest_certifications(
        policy,
        &mut bob_signer,
        bobs_uid.certifications())?;
let bob = bob.insert_packets(attestations)?;

assert_eq!(bob.bad_signatures().count(), 0);
assert_eq!(bob.userids().next().unwrap().certifications().next(),
           Some(&alice_certifies_bob));

impl<'a> ValidComponentAmalgamation<'a, UserAttribute>[src]

pub fn attested_certifications(
    &self
) -> impl Iterator<Item = &Signature> + Send + Sync
[src]

Returns the user attributes's attested third-party certifications.

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. This can be used to address certificate flooding concerns.

This method only returns signatures that are valid under the current policy and are attested by the certificate holder.

pub fn attestation_key_signatures(
    &'a self
) -> impl Iterator<Item = &'a Signature> + Send + Sync
[src]

Returns set of active attestation key signatures.

This feature is experimental.

Returns the set of signatures with the newest valid signature creation time. Older signatures are not returned. The sum of all digests in these signatures are the set of attested third-party certifications.

This interface is useful for pruning old attestation key signatures when filtering a certificate.

Note: This is a low-level interface. Consider using ValidUserAttributeAmalgamation::attested_certifications to iterate over all attested certifications.

pub fn attest_certifications<C, S>(
    &self,
    primary_signer: &mut dyn Signer,
    certifications: C
) -> Result<Vec<Signature>> where
    C: IntoIterator<Item = S>,
    S: Borrow<Signature>, 
[src]

Attests to third-party certifications.

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. This can be used to address certificate flooding concerns.

Examples

See ValidUserIDAmalgamation::attest_certifications#examples.

impl<'a, C> ValidComponentAmalgamation<'a, C> where
    C: Ord + Send + Sync
[src]

pub fn self_signatures(&self) -> impl Iterator<Item = &Signature> + Send + Sync[src]

The component's self-signatures.

This method only returns signatures that are valid under the current policy.

pub fn certifications(&self) -> impl Iterator<Item = &Signature> + Send + Sync[src]

The component's third-party certifications.

This method only returns signatures that are valid under the current policy.

pub fn self_revocations(&self) -> impl Iterator<Item = &Signature> + Send + Sync[src]

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

This method only returns signatures that are valid under the current policy.

pub fn other_revocations(
    &self
) -> impl Iterator<Item = &Signature> + Send + Sync
[src]

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

This method only returns signatures that are valid under the current policy.

pub fn signatures(&self) -> impl Iterator<Item = &Signature> + Send + Sync[src]

Returns all of the component's signatures.

This method only returns signatures that are valid under the current policy.

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

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

Changes the key's parts tag to PublicParts.

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

Changes the key's parts tag to SecretParts.

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

Changes the key's parts tag to UnspecifiedParts.

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

Changes the key's role tag to PrimaryRole.

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

Changes the key's role tag to SubordinateRole.

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

Changes the key's role tag to UnspecifiedRole.

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

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

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

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
) -> impl Iterator<Item = &'a Signature> + Send + Sync
[src]

The component's self-signatures.

pub fn certifications(
    &self
) -> impl Iterator<Item = &'a Signature> + Send + Sync
[src]

The component's third-party certifications.

pub fn self_revocations(
    &self
) -> impl Iterator<Item = &'a Signature> + Send + Sync
[src]

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

pub fn other_revocations(
    &self
) -> impl Iterator<Item = &'a Signature> + Send + Sync
[src]

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

pub fn signatures(&self) -> impl Iterator<Item = &'a Signature> + Send + Sync[src]

Returns all of the component's signatures.

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

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 attest_certifications<C, S>(
    &self,
    policy: &dyn Policy,
    primary_signer: &mut dyn Signer,
    certifications: C
) -> Result<Vec<Signature>> where
    C: IntoIterator<Item = S>,
    S: Borrow<Signature>, 
[src]

Attests to third-party certifications.

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. This can be used to address certificate flooding concerns.

A policy is needed, because the expiration is updated by updating the current binding signatures.

Examples

let (alice, _) = CertBuilder::new()
    .add_userid("alice@example.org")
    .generate()?;
let mut alice_signer =
    alice.primary_key().key().clone().parts_into_secret()?
    .into_keypair()?;

let (bob, _) = CertBuilder::new()
    .add_userid("bob@example.org")
    .generate()?;
let mut bob_signer =
    bob.primary_key().key().clone().parts_into_secret()?
    .into_keypair()?;
let bob_pristine = bob.clone();

// Have Alice certify the binding between "bob@example.org" and
// Bob's key.
let alice_certifies_bob
    = bob.userids().next().unwrap().userid().bind(
        &mut alice_signer, &bob,
        SignatureBuilder::new(SignatureType::GenericCertification))?;
let bob = bob.insert_packets(vec![alice_certifies_bob.clone()])?;

// Have Bob attest that certification.
let bobs_uid = bob.userids().next().unwrap();
let attestations =
    bobs_uid.attest_certifications(
        policy,
        &mut bob_signer,
        bobs_uid.certifications())?;
let bob = bob.insert_packets(attestations)?;

assert_eq!(bob.bad_signatures().count(), 0);
assert_eq!(bob.userids().next().unwrap().certifications().next(),
           Some(&alice_certifies_bob));

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

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.

pub fn attest_certifications<C, S>(
    &self,
    policy: &dyn Policy,
    primary_signer: &mut dyn Signer,
    certifications: C
) -> Result<Vec<Signature>> where
    C: IntoIterator<Item = S>,
    S: Borrow<Signature>, 
[src]

Attests to third-party certifications.

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. This can be used to address certificate flooding concerns.

A policy is needed, because the expiration is updated by updating the current binding signatures.

Examples

See UserIDAmalgamation::attest_certifications#examples.

Trait Implementations

impl<'a, C> Clone for ValidComponentAmalgamation<'a, C>[src]

impl<'a, C: Debug> Debug for ValidComponentAmalgamation<'a, C>[src]

impl<'a, C> Deref for ValidComponentAmalgamation<'a, C>[src]

type Target = ComponentAmalgamation<'a, C>

The resulting type after dereferencing.

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

impl<'a, C> Preferences<'a> for ValidComponentAmalgamation<'a, C>[src]

impl<'a, C> ValidAmalgamation<'a, C> for ValidComponentAmalgamation<'a, C>[src]

impl<'a, C> ValidateAmalgamation<'a, C> for ValidComponentAmalgamation<'a, C>[src]

type V = Self

The type returned by with_policy. Read more

Auto Trait Implementations

impl<'a, C> !RefUnwindSafe for ValidComponentAmalgamation<'a, C>

impl<'a, C> Send for ValidComponentAmalgamation<'a, C> where
    C: Sync

impl<'a, C> Sync for ValidComponentAmalgamation<'a, C> where
    C: Sync

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

impl<'a, C> !UnwindSafe for ValidComponentAmalgamation<'a, C>

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<T> Same<T> for T

type Output = T

Should always be Self

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.