[][src]Struct sequoia_openpgp::cert::amalgamation::KeyAmalgamationIter

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

An iterator over all Keys (both the primary key and the subkeys) in a certificate.

Returned by Cert::keys().

KeyAmalgamationIter follows the builder pattern. There is no need to explicitly finalize it, however: it already implements the Iterator trait.

By default, KeyAmalgamationIter returns all keys. KeyAmalgamationIter provides some filters to control what it returns. For instance, KeyAmalgamationIter::secret causes the iterator to only returns keys that include secret key material. Of course, since KeyAmalgamationIter implements Iterator, it is possible to use Iterator::filter to implement custom filters.

Implementations

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

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

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

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

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

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

Only returns a key if it matches the specified handle.

Note: 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 handles.

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

Only returns a key if it matches any of the specified handles.

Note: 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 handles.

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

Changes the iterator to skip the primary key.

pub fn with_policy<T>(
    self,
    policy: &'a dyn Policy,
    time: T
) -> ValidKeyAmalgamationIter<'a, P, R> where
    T: Into<Option<SystemTime>>, 
[src]

Changes the iterator to only return keys that are valid at time time.

If time is None, then the current time is used.

See ValidKeyAmalgamationIter for the definition of a valid key.

This also makes a number of filters like alive and revoked available and causes the iterator to return a KeyAmalgamation instead of a bare Key.

As a general rule of thumb, when encrypting or signing a message, you only want to use keys that are alive, not revoked, and have the appropriate capabilities keys right now. For example:

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

let p = &StandardPolicy::new();

if let RevocationStatus::Revoked(_) = cert.revoked(p, None) {
    // The certificate is revoked, don't use any keys from it.
} else if let Err(_) = cert.alive(p, None) {
    // The certificate is not alive, don't use any keys from it.
} else {
    for key in cert.keys().with_policy(p, None).alive().revoked(false).for_signing() {
        // We can sign the message with this key.
    }
}

When verifying a message, you only want to use keys that were alive, not revoked, and signing capable when the message was signed. These are the only keys that the signer could have used; anything else suggests an attack, e.g., a forged time stamp.

For version 4 Signature packets, the Signature Creation Time subpacket indicates when the signature was allegedly created. For the purpose of finding the key to verify the signature, this time stamp should be trusted.

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

let p = &StandardPolicy::new();

if let RevocationStatus::Revoked(_) = cert.revoked(p, None) {
    // The certificate is revoked, don't use any keys from it.
} else if let Err(_) = cert.alive(p, None) {
    // The certificate is not alive, don't use any keys from it.
} else {
    for key in cert.keys().with_policy(p, timestamp).alive().revoked(false).for_signing() {
        // Verify the message with this keys.
    }
}

Similarly, when decrypting a message, you should only consider keys that were alive, not revoked, and encryption-capable when the message was encrypted. Unfortunately, we don't know when a message was encrypted. This, of course, precludes checking the key's liveness, its revocation status, and its key capabilities at the time of encryption.

Decrypting a message encrypt to an expired or revoked key is not a security problem. In fact, due to the slow propagation of revocation certificates, it is better to not ignore revoked keys in this case. However, checking whether a key is encryption capable is important. This discussion explains why using a signing key to decrypt a message can be dangerous.

A possible workaround is to check whether the key is encryption capable now. Since a key's key flags don't typically change, this will correctly filter out keys that are not encryption capable. But, it will also skip keys whose self signature is now expired. Happily, no one appears to use signature expirations on self signatures. Since using the current time will almost never result in skipping the correct decryption key, but does protect the user from a dangerous attack, we recommend this approach when looking up a decryption key.

use sequoia_openpgp::policy::StandardPolicy;

let p = &StandardPolicy::new();

let decryption_keys = cert.keys().with_policy(p, None)
    .for_storage_encryption().for_transport_encryption()
    .collect::<Vec<_>>();

Trait Implementations

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

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

type Item = PrimaryKeyAmalgamation<'a, PublicParts>

The type of the elements being iterated over.

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

type Item = PrimaryKeyAmalgamation<'a, SecretParts>

The type of the elements being iterated over.

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

type Item = PrimaryKeyAmalgamation<'a, UnspecifiedParts>

The type of the elements being iterated over.

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

type Item = SubordinateKeyAmalgamation<'a, PublicParts>

The type of the elements being iterated over.

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

type Item = SubordinateKeyAmalgamation<'a, SecretParts>

The type of the elements being iterated over.

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

type Item = SubordinateKeyAmalgamation<'a, UnspecifiedParts>

The type of the elements being iterated over.

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

type Item = ErasedKeyAmalgamation<'a, PublicParts>

The type of the elements being iterated over.

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

type Item = ErasedKeyAmalgamation<'a, SecretParts>

The type of the elements being iterated over.

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

type Item = ErasedKeyAmalgamation<'a, UnspecifiedParts>

The type of the elements being iterated over.

Auto Trait Implementations

impl<'a, P, R> RefUnwindSafe for KeyAmalgamationIter<'a, P, R> where
    P: RefUnwindSafe,
    R: RefUnwindSafe

impl<'a, P, R> Send for KeyAmalgamationIter<'a, P, R> where
    P: Send,
    R: Send

impl<'a, P, R> Sync for KeyAmalgamationIter<'a, P, R> where
    P: Sync,
    R: Sync

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

impl<'a, P, R> UnwindSafe for KeyAmalgamationIter<'a, P, R> where
    P: UnwindSafe,
    R: UnwindSafe

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<I> IteratorRandom for I where
    I: Iterator
[src]

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]

impl<V, T> VZip<V> for T where
    V: MultiLane<T>,