[][src]Struct sequoia_openpgp::cert::amalgamation::key::ValidKeyAmalgamationIter

pub struct ValidKeyAmalgamationIter<'a, P, R> where
    P: KeyParts,
    R: KeyRole
{ /* fields omitted */ }

An iterator over valid Keys.

A ValidComponentAmalgamationIter is a KeyAmalgamationIter that includes a Policy and a reference time, which it firstly uses to only return valid Keys. (For a definition of valid keys, see the documentation for ValidateAmalgamation.)

A ValidComponentAmalgamationIter also provides additional filters based on information available in the Keys' binding signatures. For instance, ValidKeyAmalgamationIter::revoked filters the returned Keys by whether or not they are revoked. And, ValidKeyAmalgamationIter::alive changes the iterator to only return Keys that are live.

ValidKeyAmalgamationIter follows the builder pattern. But, there is no need to explicitly finalize it: it already implements the Iterator trait.

A ValidKeyAmalgamationIter is returned by KeyAmalgamationIter::with_policy and ValidCert::keys.

Examples

Find a key that we can use to sign a document:

use openpgp::policy::StandardPolicy;
use openpgp::types::RevocationStatus;

let p = &StandardPolicy::new();

// The certificate *and* keys need to be valid.
let cert = cert.with_policy(p, None)?;

if let RevocationStatus::Revoked(_) = cert.revocation_status() {
    // Certificate is revoked.
} else if let Err(_err) = cert.alive() {
    // The certificate is not alive.
} else {
    // Iterate over all valid keys.
    //
    // Note: using the combinator interface (instead of checking
    // the individual keys) makes it harder to report exactly why no
    // key was usable.
    for ka in cert.keys()
        // Not revoked.
        .revoked(false)
        // Alive.
        .alive()
        // Be signing capable.
        .for_signing()
        // And have unencrypted secret material.
        .unencrypted_secret()
    {
        // We can use it.
    }
}

Implementations

impl<'a, P, R> ValidKeyAmalgamationIter<'a, P, R> where
    P: KeyParts,
    R: KeyRole
[src]

pub fn key_flags<F>(self, flags: F) -> Self where
    F: Borrow<KeyFlags>, 
[src]

Returns keys that have the at least one of the flags specified in flags.

If you call this function (or one of for_certification, for_signing, etc.) multiple times, the union of the values is used.

Note: Section 12.1 of RFC 4880 says that the primary key is certification capable independent of the Key Flags subpacket:

In a V4 key, the primary key MUST be a key capable of certification.

This function only reflects what is stored in the Key Flags packet; it does not implicitly set this flag. In practice, there are keys whose primary key's Key Flags do not have the certification capable flag set. Some versions of netpgp, for instance, create keys like this. Sequoia's higher-level functionality correctly handles these keys by always considering the primary key to be certification capable. Users of this interface should too.

The key flags are looked up as described in ValidKeyAmalgamation::key_flags.

Examples

use openpgp::policy::StandardPolicy;
use openpgp::types::KeyFlags;

let p = &StandardPolicy::new();

for ka in cert.keys()
    .with_policy(p, None)
    .key_flags(KeyFlags::empty()
        .set_transport_encryption(true)
        .set_storage_encryption(true))
{
    // Valid encryption-capable keys.
}

pub fn for_certification(self) -> Self[src]

Returns certification-capable keys.

If you call this function (or one of key_flags, for_signing, etc.) multiple times, the union of the values is used.

Note: Section 12.1 of RFC 4880 says that the primary key is certification capable independent of the Key Flags subpacket:

In a V4 key, the primary key MUST be a key capable of certification.

This function only reflects what is stored in the Key Flags packet; it does not implicitly set this flag. In practice, there are keys whose primary key's Key Flags do not have the certification capable flag set. Some versions of netpgp, for instance, create keys like this. Sequoia's higher-level functionality correctly handles these keys by always considering the primary key to be certification capable. Users of this interface should too.

The key flags are looked up as described in ValidKeyAmalgamation::key_flags.

Examples

use openpgp::policy::StandardPolicy;

let p = &StandardPolicy::new();

for ka in cert.keys()
    .with_policy(p, None)
    .for_certification()
{
    // Valid certification-capable keys.
}

pub fn for_signing(self) -> Self[src]

Returns signing-capable keys.

If you call this function (or one of key_flags, for_certification, etc.) multiple times, the union of the values is used.

Refer to ValidKeyAmalgamation::for_signing for additional details and caveats.

Examples

use openpgp::policy::StandardPolicy;

let p = &StandardPolicy::new();

for ka in cert.keys()
    .with_policy(p, None)
    .for_signing()
{
    // Valid signing-capable keys.
}

pub fn for_authentication(self) -> Self[src]

Returns authentication-capable keys.

If you call this function (or one of key_flags, for_certification, etc.) multiple times, the union of the values is used.

Refer to ValidKeyAmalgamation::for_authentication for additional details and caveats.

Examples

use openpgp::policy::StandardPolicy;

let p = &StandardPolicy::new();

for ka in cert.keys()
    .with_policy(p, None)
    .for_authentication()
{
    // Valid authentication-capable keys.
}

pub fn for_storage_encryption(self) -> Self[src]

Returns encryption-capable keys for data at rest.

If you call this function (or one of key_flags, for_certification, etc.) multiple times, the union of the values is used.

Refer to ValidKeyAmalgamation::for_storage_encryption for additional details and caveats.

Examples

use openpgp::policy::StandardPolicy;

let p = &StandardPolicy::new();

for ka in cert.keys()
    .with_policy(p, None)
    .for_storage_encryption()
{
    // Valid encryption-capable keys for data at rest.
}

pub fn for_transport_encryption(self) -> Self[src]

Returns encryption-capable keys for data in transit.

If you call this function (or one of key_flags, for_certification, etc.) multiple times, the union of the values is used.

Refer to ValidKeyAmalgamation::for_transport_encryption for additional details and caveats.

Examples

use openpgp::policy::StandardPolicy;

let p = &StandardPolicy::new();

for ka in cert.keys()
    .with_policy(p, None)
    .for_transport_encryption()
{
    // Valid encryption-capable keys for data in transit.
}

pub fn alive(self) -> Self[src]

Returns keys that are alive.

A ValidKeyAmalgamation is guaranteed to have a live binding signature. This is independent of whether the key is live, or the certificate is live, i.e., if you care about those things, you need to check them too.

For a definition of liveness, see the key_alive method.

Examples

use openpgp::policy::StandardPolicy;

let p = &StandardPolicy::new();

for ka in cert.keys()
    .with_policy(p, None)
    .alive()
{
    // ka is alive.
}

pub fn revoked<T>(self, revoked: T) -> Self where
    T: Into<Option<bool>>, 
[src]

Returns keys based on their revocation status.

A value of None disables this filter.

If you call this function multiple times on the same ValidKeyAmalgamationIter, only the last value is used.

This filter checks the key's revocation status; it does not check the certificate's revocation status.

This filter only checks whether the key has no valid-self revocations at the specified time. It does not check third-party revocations.

Examples

use openpgp::policy::StandardPolicy;

let p = &StandardPolicy::new();

for ka in cert.keys()
    .with_policy(p, None)
    .revoked(false)
{
    // ka has no self-revocations; recall: this filter doesn't check
    // third-party revocations.
}

This filter checks whether a key's revocation status is RevocationStatus::Revoked or not. ValidKeyAmalgamationIter::revoked(false) is equivalent to:

use openpgp::types::RevocationStatus;
use openpgp::policy::StandardPolicy;

let p = &StandardPolicy::new();

let non_revoked_keys = cert
    .keys()
    .with_policy(p, timestamp)
    .filter(|ka| {
        match ka.revocation_status() {
            RevocationStatus::Revoked(_) =>
                // It's definitely revoked, skip it.
                false,
            RevocationStatus::CouldBe(_) =>
                // There is a designated revoker that we
                // could check, but don't (or can't).  To
                // avoid a denial of service attack arising from
                // fake revocations, we assume that the key has
                // not been revoked and return it.
                true,
            RevocationStatus::NotAsFarAsWeKnow =>
                // We have no evidence to suggest that the key
                // is revoked.
                true,
        }
    })
    .map(|ka| ka.key())
    .collect::<Vec<_>>();

As the example shows, this filter is significantly less flexible than using KeyAmalgamation::revocation_status. However, this filter implements a typical policy, and does not preclude using something like Iter::filter to implement alternative policies.

pub fn secret(self) -> ValidKeyAmalgamationIter<'a, SecretParts, R>[src]

Changes the iterator to only return keys with secret key material.

Examples

use openpgp::policy::StandardPolicy;

let p = &StandardPolicy::new();

for ka in cert.keys().with_policy(p, None).secret() {
    // Use it.
}

pub fn unencrypted_secret(self) -> ValidKeyAmalgamationIter<'a, SecretParts, R>[src]

Changes the iterator to only return keys with unencrypted secret key material.

Examples

use openpgp::policy::StandardPolicy;

let p = &StandardPolicy::new();

for ka in cert.keys().with_policy(p, None).unencrypted_secret() {
    // Use it.
}

pub fn key_handle<H>(self, h: H) -> Self where
    H: Into<KeyHandle>, 
[src]

Changes the iterator to only return a key if it matches one of the specified KeyHandles.

This function is cumulative. If you call this function (or key_handles) multiple times, then the iterator returns a key if it matches any of the specified KeyHandles.

This function uses KeyHandle::aliases to compare key handles.

Examples

use openpgp::policy::StandardPolicy;

let p = &StandardPolicy::new();

for ka in cert.keys().with_policy(p, None).key_handle(key_handle) {
    // Use it.
}

pub fn key_handles<'b>(self, h: impl Iterator<Item = &'b KeyHandle>) -> Self where
    'a: 'b, 
[src]

Changes the iterator to only return a key if it matches one of the specified KeyHandles.

This function is cumulative. If you call this function (or key_handle) multiple times, then the iterator returns a key if it matches any of the specified KeyHandles.

This function uses KeyHandle::aliases to compare key handles.

Examples

use openpgp::policy::StandardPolicy;

let p = &StandardPolicy::new();

for ka in cert.keys().with_policy(p, None).key_handles(key_handles.iter()) {
    // Use it.
}

pub fn subkeys(self) -> ValidKeyAmalgamationIter<'a, P, SubordinateRole>[src]

Changes the iterator to skip the primary key.

This also changes the iterator's return type. Instead of returning a ValidErasedKeyAmalgamation, it returns a ValidSubordinateKeyAmalgamation.

Examples

use openpgp::policy::StandardPolicy;

let p = &StandardPolicy::new();

for ka in cert.keys().with_policy(p, None).subkeys() {
    assert!(! ka.primary());
}

Trait Implementations

impl<'a, P, R> Debug for ValidKeyAmalgamationIter<'a, P, R> where
    P: KeyParts,
    R: KeyRole
[src]

impl<'a> Iterator for ValidKeyAmalgamationIter<'a, PublicParts, PrimaryRole>[src]

type Item = ValidPrimaryKeyAmalgamation<'a, PublicParts>

The type of the elements being iterated over.

impl<'a> Iterator for ValidKeyAmalgamationIter<'a, SecretParts, PrimaryRole>[src]

type Item = ValidPrimaryKeyAmalgamation<'a, SecretParts>

The type of the elements being iterated over.

impl<'a> Iterator for ValidKeyAmalgamationIter<'a, UnspecifiedParts, PrimaryRole>[src]

type Item = ValidPrimaryKeyAmalgamation<'a, UnspecifiedParts>

The type of the elements being iterated over.

impl<'a> Iterator for ValidKeyAmalgamationIter<'a, PublicParts, SubordinateRole>[src]

type Item = ValidSubordinateKeyAmalgamation<'a, PublicParts>

The type of the elements being iterated over.

impl<'a> Iterator for ValidKeyAmalgamationIter<'a, SecretParts, SubordinateRole>[src]

type Item = ValidSubordinateKeyAmalgamation<'a, SecretParts>

The type of the elements being iterated over.

impl<'a> Iterator for ValidKeyAmalgamationIter<'a, UnspecifiedParts, SubordinateRole>[src]

type Item = ValidSubordinateKeyAmalgamation<'a, UnspecifiedParts>

The type of the elements being iterated over.

impl<'a> Iterator for ValidKeyAmalgamationIter<'a, PublicParts, UnspecifiedRole>[src]

type Item = ValidErasedKeyAmalgamation<'a, PublicParts>

The type of the elements being iterated over.

impl<'a> Iterator for ValidKeyAmalgamationIter<'a, SecretParts, UnspecifiedRole>[src]

type Item = ValidErasedKeyAmalgamation<'a, SecretParts>

The type of the elements being iterated over.

impl<'a> Iterator for ValidKeyAmalgamationIter<'a, UnspecifiedParts, UnspecifiedRole>[src]

type Item = ValidErasedKeyAmalgamation<'a, UnspecifiedParts>

The type of the elements being iterated over.

Auto Trait Implementations

impl<'a, P, R> !RefUnwindSafe for ValidKeyAmalgamationIter<'a, P, R>

impl<'a, P, R> !Send for ValidKeyAmalgamationIter<'a, P, R>

impl<'a, P, R> !Sync for ValidKeyAmalgamationIter<'a, P, R>

impl<'a, P, R> Unpin for ValidKeyAmalgamationIter<'a, P, R> where
    P: Unpin,
    R: Unpin

impl<'a, P, R> !UnwindSafe for ValidKeyAmalgamationIter<'a, P, R>

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> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<I> IntoIterator for I where
    I: Iterator
[src]

type Item = <I as Iterator>::Item

The type of the elements being iterated over.

type IntoIter = I

Which kind of iterator are we turning this into?

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.

impl<I> UnicodeNormalization<I> for I where
    I: Iterator<Item = char>, 
[src]