Type Alias sequoia_openpgp::cert::amalgamation::UserIDAmalgamation

pub type UserIDAmalgamation<'a> = ComponentAmalgamation<'a, UserID>;

A User ID and its associated data.

A specialized version of ComponentAmalgamation.

Aliased Type

struct UserIDAmalgamation<'a> { /* private fields */ }

Implementations

impl<'a> UserIDAmalgamation<'a>

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 valid_certifications_by_key<T, PK>( &self, policy: &'a dyn Policy, reference_time: T, issuer: PK, ) -> impl Iterator<Item = &Signature> + Send + Sync

where T: Into<Option<SystemTime>>, PK: Into<&'a Key<PublicParts, UnspecifiedRole>>,

Returns the third-party certifications issued by the specified key, and valid at the specified time.

This function returns the certifications issued by the specified key. Specifically, it returns a certification if:

• it is well formed,
• it is live with respect to the reference time,
• it conforms to the policy, and
• the signature is cryptographically valid.

This method is implemented on a UserIDAmalgamation and not a ValidUserIDAmalgamation, because a third-party certification does not require the user ID to be self signed.

Examples

Alice has certified that a certificate belongs to Bob on two occasions. Whereas UserIDAmalgamation::valid_certifications_by_key returns both certifications, UserIDAmalgamation::active_certifications_by_key only returns the most recent certification.

use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::policy::StandardPolicy;

const P: &StandardPolicy = &StandardPolicy::new();

let alice: Cert = // ...
let bob: Cert = // ...

let ua = bob.userids().next().expect("have user id");

let valid_certifications = ua.valid_certifications_by_key(
    P, None, alice.primary_key().key());
// Alice certified Bob's certificate twice.
assert_eq!(valid_certifications.count(), 2);

let active_certifications = ua.active_certifications_by_key(
    P, None, alice.primary_key().key());
// But only the most recent one is active.
assert_eq!(active_certifications.count(), 1);

pub fn active_certifications_by_key<T, PK>( &self, policy: &'a dyn Policy, reference_time: T, issuer: PK, ) -> impl Iterator<Item = &Signature> + Send + Sync

where T: Into<Option<SystemTime>>, PK: Into<&'a Key<PublicParts, UnspecifiedRole>>,

Returns any active third-party certifications issued by the specified key.

This function is like UserIDAmalgamation::valid_certifications_by_key, but it only returns active certifications. Active certifications are the most recent valid certifications with respect to the reference time.

Although there is normally only a single active certification, there can be multiple certifications with the same timestamp. In this case, all of them are returned.

Unlike self-signatures, multiple third-party certifications issued by the same key at the same time can be sensible. For instance, Alice may fully trust a CA for user IDs in a particular domain, and partially trust it for everything else. This can only be expressed using multiple certifications.

This method is implemented on a UserIDAmalgamation and not a ValidUserIDAmalgamation, because a third-party certification does not require the user ID to be self signed.

Examples

See the examples for UserIDAmalgamation::valid_certifications_by_key.

pub fn valid_third_party_revocations_by_key<T, PK>( &self, policy: &'a dyn Policy, reference_time: T, issuer: PK, ) -> impl Iterator<Item = &Signature> + Send + Sync

where T: Into<Option<SystemTime>>, PK: Into<&'a Key<PublicParts, UnspecifiedRole>>,

Returns the third-party revocations issued by the specified key, and valid at the specified time.

This function returns the revocations issued by the specified key. Specifically, it returns a revocation if:

• it is well formed,
• it is live with respect to the reference time,
• it conforms to the policy, and
• the signature is cryptographically valid.

This method is implemented on a UserIDAmalgamation and not a ValidUserIDAmalgamation, because a third-party revocation does not require the user ID to be self signed.

Examples

Alice revokes a user ID on Bob’s certificate.

use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::policy::StandardPolicy;

const P: &StandardPolicy = &StandardPolicy::new();

let alice: Cert = // ...
let bob: Cert = // ...

let ua = bob.userids().next().expect("have user id");

let revs = ua.valid_third_party_revocations_by_key(
    P, None, alice.primary_key().key());
// Alice revoked the User ID.
assert_eq!(revs.count(), 1);

pub fn attest_certifications2<T, C, S>( &self, policy: &dyn Policy, time: T, primary_signer: &mut dyn Signer, certifications: C, ) -> Result<Vec<Signature>>

where T: Into<Option<SystemTime>>, C: IntoIterator<Item = S>, S: Borrow<Signature>,

Attests to third-party certifications.

This feature is experimental.

Allows the certificate owner to attest to third party certifications. See draft-dkg-openpgp-1pa3pc 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_certifications2(
        policy,
        None,
        &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 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>,

👎Deprecated: Use attest_certifications2 instead.

Attests to third-party certifications.

This feature is experimental.

This function is deprecated in favor of UserIDAmalgamation::attest_certifications2, which includes a reference time parameter.