Struct ValidComponentAmalgamation

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

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.userid().value()),
                  u.preferred_symmetric_algorithms());
    }
}

Implementations

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

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

Returns the valid amalgamation’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 binding_signature(&self) -> &'a Signature

Returns the valid amalgamation’s active binding signature.

The active binding signature is the most recent, non-revoked self-signature that is valid according to the policy and alive at time t (creation time <= t, t < expiry). If there are multiple such signatures then the signatures are ordered by their MPIs interpreted as byte strings.

Examples

use openpgp::policy::StandardPolicy;
let p = &StandardPolicy::new();

// Display information about each User ID's current active
// binding signature (the `time` parameter is `None`), if any.
for ua in cert.with_policy(p, None)?.userids() {
    eprintln!("{:?}", ua.binding_signature());
}

pub fn amalgamation(&self) -> &ComponentAmalgamation<'a, C>

Returns the valid amalgamation’s amalgamation.

Examples

use openpgp::policy::StandardPolicy;

let p = &StandardPolicy::new();

// Get a user ID amalgamation.
let ua = cert.userids().next().expect("added one");

// Validate it, yielding a valid component amalgamation.
let vua = ua.with_policy(p, None)?;

// And here we get the amalgamation back.
let ua2 = vua.amalgamation();
assert_eq!(&ua, ua2);

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

Returns this valid amalgamation’s bundle.

Examples

use openpgp::cert::prelude::*;
use openpgp::packet::prelude::*;
let p = &openpgp::policy::StandardPolicy::new();

cert.with_policy(p, None)?.userids()
    .map(|ua| ua.bundle())
    .collect::<Vec<&ComponentBundle<_>>>();

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

Returns this valid amalgamation’s component.

Examples

let p = &openpgp::policy::StandardPolicy::new();

// Display some information about any userid components.
for u in cert.with_policy(p, None)?.userids() {
    eprintln!(" - {:?}", u.component());
}

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

where C: Send + Sync,

pub fn self_signatures( &self, ) -> impl Iterator<Item = &'a Signature> + Send + Sync + 'a

Returns the valid amalgamation’s self-signatures.

The signatures are validated, and they are sorted by their creation time, most recent first. This method only returns signatures that are valid under the current policy.

Examples

use openpgp::policy::StandardPolicy;
let p = &StandardPolicy::new();

for (i, ka) in cert.with_policy(p, None)?.keys().enumerate() {
    eprintln!("Key #{} ({}) has {:?} self signatures",
              i, ka.key().fingerprint(),
              ka.self_signatures().count());
}

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

Returns the component’s third-party certifications.

The signatures are not validated. They are sorted by their creation time, most recent first. This method only returns signatures that are valid under the current policy.

Examples

use openpgp::policy::StandardPolicy;
let p = &StandardPolicy::new();

for ua in cert.with_policy(p, None)?.userids() {
    eprintln!("User ID {} has {:?} unverified, third-party certifications",
              String::from_utf8_lossy(ua.userid().value()),
              ua.certifications().count());
}

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

Returns the valid amalgamation’s revocations that were issued by the certificate holder.

The revocations are validated, and they are sorted by their creation time, most recent first. This method only returns signatures that are valid under the current policy.

Examples

use openpgp::policy::StandardPolicy;
let p = &StandardPolicy::new();

for u in cert.with_policy(p, None)?.userids() {
    eprintln!("User ID {} has {:?} revocation certificates.",
              String::from_utf8_lossy(u.userid().value()),
              u.self_revocations().count());
}

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

Returns the valid amalgamation’s revocations that were issued by other certificates.

The revocations are not validated. They are sorted by their creation time, most recent first. This method only returns signatures that are valid under the current policy.

Examples

use openpgp::policy::StandardPolicy;
let p = &StandardPolicy::new();

for u in cert.with_policy(p, None)?.userids() {
    eprintln!("User ID {} has {:?} unverified, third-party revocation certificates.",
              String::from_utf8_lossy(u.userid().value()),
              u.other_revocations().count());
}

pub fn approvals( &self, ) -> impl Iterator<Item = &'a Signature> + Send + Sync + 'a

Returns all of the valid amalgamation’s Certification Approval Key Signatures.

This feature is experimental.

The signatures are validated, and they are sorted by their creation time, most recent first.

A certificate owner can use Certification Approval Key Signatures to approve of third party certifications. Currently, only userid and user attribute certifications can be approved. See Approved Certifications subpacket for details.

Examples

use openpgp::policy::StandardPolicy;
let p = &StandardPolicy::new();

for (i, uid) in cert.with_policy(p, None)?.userids().enumerate() {
    eprintln!("UserID #{} ({:?}) has {:?} certification approval key signatures",
              i, uid.userid().email(),
              uid.approvals().count());
}

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

Returns all of the valid amalgamations’s signatures.

Only the self-signatures are validated. The signatures are sorted first by type, then by creation time. The self revocations come first, then the self signatures, then any certification approval key signatures, certifications, and third-party revocations coming last. This function may return additional types of signatures that could be associated to this component.

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

Examples

use openpgp::policy::StandardPolicy;
let p = &StandardPolicy::new();

for (i, ka) in cert.with_policy(p, None)?.keys().enumerate() {
    eprintln!("Key #{} ({}) has {:?} signatures",
              i, ka.key().fingerprint(),
              ka.signatures().count());
}

impl<'a> ValidComponentAmalgamation<'a, UserID>

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

Returns a reference to the User ID.

This is just a type-specific alias for ValidComponentAmalgamation::component.

Examples

// Display some information about the User IDs.
for ua in cert.userids() {
    eprintln!(" - {:?}", ua.userid());
}

pub fn approved_certifications( &self, ) -> impl Iterator<Item = &Signature> + Send + Sync

Returns the user ID’s approved third-party certifications.

This feature is experimental.

Allows the certificate owner to approve of third party certifications. See Approved Certification subpacket 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 approved by the certificate holder.

pub fn certification_approval_key_signatures( &'a self, ) -> impl Iterator<Item = &'a Signature> + Send + Sync

Returns set of active certification approval 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 approved third-party certifications.

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

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

pub fn approve_of_certifications<C, S>( &self, primary_signer: &mut dyn Signer, certifications: C, ) -> Result<Vec<Signature>>

where C: IntoIterator<Item = S>, S: Borrow<Signature>,

Approves of third-party certifications.

This feature is experimental.

Allows the certificate owner to approve of third party certifications. See Approved Certifications subpacket 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()])?.0;

// Have Bob approve of that certification.
let bobs_uid = bob.with_policy(policy, None)?.userids().next().unwrap();
let approvals =
    bobs_uid.approve_of_certifications(
        &mut bob_signer,
        bobs_uid.certifications())?;
let bob = bob.insert_packets(approvals)?.0;

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

impl<'a> ValidComponentAmalgamation<'a, UserAttribute>

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

Returns a reference to the User Attribute.

This is just a type-specific alias for ValidComponentAmalgamation::component.

Examples

// Display some information about the User IDs.
for ua in cert.user_attributes() {
    eprintln!(" - {:?}", ua.user_attribute());
}

pub fn approved_certifications( &self, ) -> impl Iterator<Item = &Signature> + Send + Sync

Returns the user attributes’ approved third-party certifications.

This feature is experimental.

Allows the certificate owner to approve of third party certifications. See Approved Certifications subpacket 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 approved by the certificate holder.

pub fn certification_approval_key_signatures( &'a self, ) -> impl Iterator<Item = &'a Signature> + Send + Sync

Returns set of active certification approval 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 approved third-party certifications.

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

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

pub fn approve_of_certifications<C, S>( &self, primary_signer: &mut dyn Signer, certifications: C, ) -> Result<Vec<Signature>>

where C: IntoIterator<Item = S>, S: Borrow<Signature>,

Approves of third-party certifications.

This feature is experimental.

Allows the certificate owner to approve of third party certifications. See Approved Certifications subpacket for details. This can be used to address certificate flooding concerns.

Examples

See ValidUserIDAmalgamation::approve_of_certifications#examples.

Trait Implementations

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

fn clone(&self) -> Self

Returns a duplicate of the value.

const 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: 'a> From<ValidComponentAmalgamation<'a, C>> for ComponentAmalgamation<'a, C>

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

Converts to this type from the input type.

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

where C: Send + Sync,

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_ciphersuites( &self, ) -> Option<&'a [(SymmetricAlgorithm, AEADAlgorithm)]>

Returns the supported AEAD ciphersuites 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 policy_uri(&self) -> Option<&'a [u8]>

Returns the URI of a document describing the policy the certificate was issued under.

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

Returns the certificate holder’s feature set.

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

where C: Send + Sync,

fn valid_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 revocation_keys(&self) -> Box<dyn Iterator<Item = &'a RevocationKey> + 'a>

Returns a list of any designated revokers for this component.

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> ValidBindingSignature<'a, C> for ValidComponentAmalgamation<'a, C>

where C: Send + Sync,

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

Maps the given function over binding and direct key signature.

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

type V = ValidComponentAmalgamation<'a, C>

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.