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_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>,

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));