openpgp: Pass a timestamp to the KeyIter instead of each filter.

  - KeyIter::revoked and KeyIter::key_flags (and its variants) didn't
    take a time stamp so they could only be used for filtering keys
    based on their current state, not their state at some time in the
    past.  Adding a time stamp to each of the filters would have fixed
    the problem, but it would have made the interface ugly: callers
    always want the same time stamp for all filters.

  - Split KeyIter into two structures: a KeyIter and a ValidKeyIter.

  - Add KeyIter::policy.  It takes a time stamp, which is then used
    for filters like `alive` and `revoked`, and it returns a
    ValidKeyIter, which exposes filters that require a time stamp.

3 files changed, 71 insertions, 26 deletions

diff --git a/openpgp-ffi/include/sequoia/openpgp.h b/openpgp-ffi/include/sequoia/openpgp.h
index 4468ccb5..1a27fad9 100644
--- a/openpgp-ffi/include/sequoia/openpgp.h
+++ b/openpgp-ffi/include/sequoia/openpgp.h
@@ -607,6 +607,41 @@ void pgp_user_id_binding_iter_free (pgp_user_id_binding_iter_t iter);
 /* openpgp::cert::KeyIter.  */
 
 /*/
+/// Changes the iterator to only return keys that have secret keys.
+///
+/// Note: you may not call this function after starting to iterate.
+/*/
+void pgp_cert_key_iter_secret (pgp_cert_key_iter_t iter);
+
+/*/
+/// Changes the iterator to only return keys that have unencrypted
+/// secret keys.
+///
+/// Note: you may not call this function after starting to iterate.
+/*/
+void pgp_cert_key_iter_unencrypted_secret (pgp_cert_key_iter_t iter);
+
+/*/
+/// Changes the iterator to only return keys that have unencrypted
+/// secret keys.
+///
+/// Note: you may not call this function after starting to iterate.
+/*/
+pgp_cert_valid_key_iter_t pgp_cert_key_iter_policy
+    (pgp_cert_key_iter_t iter, time_t when);
+
+/*/
+/// Returns a reference to the next key.  Returns NULL if there are no
+/// more elements.
+/*/
+pgp_key_t pgp_cert_key_iter_next (pgp_cert_key_iter_t iter);
+
+/*/
+/// Frees an pgp_cert_key_iter_t.
+/*/
+void pgp_cert_key_iter_free (pgp_cert_key_iter_t iter);
+
+/*/
 /// Changes the iterator to only return keys that are certification
 /// capable.
 ///
@@ -617,7 +652,7 @@ void pgp_user_id_binding_iter_free (pgp_user_id_binding_iter_t iter);
 ///
 /// Note: you may not call this function after starting to iterate.
 /*/
-void pgp_cert_key_iter_for_certification (pgp_cert_key_iter_t iter);
+void pgp_cert_valid_key_iter_for_certification (pgp_cert_valid_key_iter_t iter);
 
 /*/
 /// Changes the iterator to only return keys that are certification
@@ -630,7 +665,7 @@ void pgp_cert_key_iter_for_certification (pgp_cert_key_iter_t iter);
 ///
 /// Note: you may not call this function after starting to iterate.
 /*/
-void pgp_cert_key_iter_for_signing (pgp_cert_key_iter_t iter);
+void pgp_cert_valid_key_iter_for_signing (pgp_cert_valid_key_iter_t iter);
 
 /*/
 /// Changes the iterator to only return keys that are capable of
@@ -643,7 +678,7 @@ void pgp_cert_key_iter_for_signing (pgp_cert_key_iter_t iter);
 ///
 /// Note: you may not call this function after starting to iterate.
 /*/
-void pgp_cert_key_iter_for_storage_encryption (pgp_cert_key_iter_t);
+void pgp_cert_valid_key_iter_for_storage_encryption (pgp_cert_valid_key_iter_t);
 
 /*/
 /// Changes the iterator to only return keys that are capable of
@@ -656,28 +691,16 @@ void pgp_cert_key_iter_for_storage_encryption (pgp_cert_key_iter_t);
 ///
 /// Note: you may not call this function after starting to iterate.
 /*/
-void pgp_cert_key_iter_for_transport_encryption (pgp_cert_key_iter_t);
+void pgp_cert_valid_key_iter_for_transport_encryption (pgp_cert_valid_key_iter_t);
 
 /*/
 /// Changes the iterator to only return keys that are alive.
 ///
-/// If you call this function (or `pgp_cert_key_iter_alive_at`), only
-/// the last value is used.
+/// If you call this function, only the last value is used.
 ///
 /// Note: you may not call this function after starting to iterate.
 /*/
-void pgp_cert_key_iter_alive (pgp_cert_key_iter_t iter);
-
-/*/
-/// Changes the iterator to only return keys that are alive at the
-/// specified time.
-///
-/// If you call this function (or `pgp_cert_key_iter_alive`), only the
-/// last value is used.
-///
-/// Note: you may not call this function after starting to iterate.
-/*/
-void pgp_cert_key_iter_alive_at (pgp_cert_key_iter_t iter, time_t when);
+void pgp_cert_valid_key_iter_alive (pgp_cert_valid_key_iter_t iter);
 
 /*/
 /// Changes the iterator to only return keys whose revocation status
@@ -685,14 +708,14 @@ void pgp_cert_key_iter_alive_at (pgp_cert_key_iter_t iter, time_t when);
 ///
 /// Note: you may not call this function after starting to iterate.
 /*/
-void pgp_cert_key_iter_revoked (pgp_cert_key_iter_t iter, bool revoked);
+void pgp_cert_valid_key_iter_revoked (pgp_cert_valid_key_iter_t iter, bool revoked);
 
 /*/
 /// Changes the iterator to only return keys that have secret keys.
 ///
 /// Note: you may not call this function after starting to iterate.
 /*/
-void pgp_cert_key_iter_secret (pgp_cert_key_iter_t iter);
+void pgp_cert_valid_key_iter_secret (pgp_cert_valid_key_iter_t iter);
 
 /*/
 /// Changes the iterator to only return keys that have unencrypted
@@ -700,7 +723,7 @@ void pgp_cert_key_iter_secret (pgp_cert_key_iter_t iter);
 ///
 /// Note: you may not call this function after starting to iterate.
 /*/
-void pgp_cert_key_iter_unencrypted_secret (pgp_cert_key_iter_t iter);
+void pgp_cert_valid_key_iter_unencrypted_secret (pgp_cert_valid_key_iter_t iter);
 
 /*/
 /// Returns a reference to the next key.  Returns NULL if there are no
@@ -714,14 +737,14 @@ void pgp_cert_key_iter_unencrypted_secret (pgp_cert_key_iter_t iter);
 /// If rev is not NULL, this stores the key's revocation status in
 /// *rev.
 /*/
-pgp_key_t pgp_cert_key_iter_next (pgp_cert_key_iter_t iter,
-                                 pgp_signature_t *signature,
-                                 pgp_revocation_status_t *rev);
+pgp_key_t pgp_cert_valid_key_iter_next (pgp_cert_valid_key_iter_t iter,
+                                        pgp_signature_t *signature,
+                                        pgp_revocation_status_t *rev);
 
 /*/
-/// Frees an pgp_cert_key_iter_t.
+/// Frees an pgp_cert_valid_key_iter_t.
 /*/
-void pgp_cert_key_iter_free (pgp_cert_key_iter_t iter);
+void pgp_cert_valid_key_iter_free (pgp_cert_valid_key_iter_t iter);
 
 /* openpgp::cert.  */
 
@@ -917,6 +940,15 @@ pgp_user_id_binding_iter_t pgp_cert_user_id_binding_iter (pgp_cert_t cert);
 pgp_cert_key_iter_t pgp_cert_key_iter (pgp_cert_t cert);
 
 /*/
+/// Returns an iterator over all valid `Key`s in a Cert.
+///
+/// That is, this returns an iterator over the primary key and any
+/// subkeys that are valid (i.e., have a self-signature at time
+/// `when`).
+/*/
+pgp_cert_valid_key_iter_t pgp_cert_valid_key_iter (pgp_cert_t cert, time_t when);
+
+/*/
 /// Returns the Cert's primary user id (if any).
 /*/
 char *pgp_cert_primary_user_id(pgp_cert_t cert);
diff --git a/openpgp-ffi/include/sequoia/openpgp/serialize.h b/openpgp-ffi/include/sequoia/openpgp/serialize.h
index 09d62c95..5f9239b5 100644
--- a/openpgp-ffi/include/sequoia/openpgp/serialize.h
+++ b/openpgp-ffi/include/sequoia/openpgp/serialize.h
@@ -37,4 +37,12 @@ void pgp_recipient_set_keyid (pgp_recipient_t, pgp_keyid_t);
 /*/
 pgp_recipient_t *pgp_recipients_from_key_iter (pgp_cert_key_iter_t, size_t *);
 
+/*/
+/// Collects recipients from a `pgp_cert_valid_key_iter_t`.
+///
+/// Consumes the iterator.  The returned buffer must be freed using
+/// libc's allocator.
+/*/
+pgp_recipient_t *pgp_recipients_from_valid_key_iter (pgp_cert_valid_key_iter_t, size_t *);
+
 #endif
diff --git a/openpgp-ffi/include/sequoia/openpgp/types.h b/openpgp-ffi/include/sequoia/openpgp/types.h
index c0b3bbd7..e85916f3 100644
--- a/openpgp-ffi/include/sequoia/openpgp/types.h
+++ b/openpgp-ffi/include/sequoia/openpgp/types.h
@@ -379,6 +379,11 @@ typedef struct pgp_user_id_binding_iter *pgp_user_id_binding_iter_t;
 typedef struct pgp_cert_key_iter *pgp_cert_key_iter_t;
 
 /*/
+/// An iterator over valid keys in a Cert.
+/*/
+typedef struct pgp_cert_valid_key_iter *pgp_cert_valid_key_iter_t;
+
+/*/
 /// An OpenPGP Certificate.
 ///
 /// A Certificate (see [RFC 4880, section 11.1]) can be used to verify