openpgp-ffi: Change key iterator to return key amalgamations.

  - Introduce `KeyAmalgamation` and `ValidKeyAmalgamation` to the C
    FFI.

  - Change pgp_cert_key_iter_next and pgp_cert_valid_key_iter_next to
    return them instead of keys.

7 files changed, 179 insertions, 19 deletions

diff --git a/openpgp-ffi/examples/decrypt-with.c b/openpgp-ffi/examples/decrypt-with.c
index 489e70aa..b6fff7b1 100644
--- a/openpgp-ffi/examples/decrypt-with.c
+++ b/openpgp-ffi/examples/decrypt-with.c
@@ -170,14 +170,17 @@ decrypt_cb (void *cookie_opaque,
     pgp_keyid_t keyid = pgp_pkesk_recipient (pkesk);
 
     pgp_cert_key_iter_t key_iter = pgp_cert_key_iter (cookie->key);
+    pgp_key_amalgamation_t ka;
     pgp_key_t key;
-    while ((key = pgp_cert_key_iter_next (key_iter))) {
+    while ((ka = pgp_cert_key_iter_next (key_iter))) {
+      key = pgp_key_amalgamation_key (ka);
       pgp_keyid_t this_keyid = pgp_key_keyid (key);
       int match = pgp_keyid_equal (this_keyid, keyid);
       pgp_keyid_free (this_keyid);
       if (match)
         break;
       pgp_key_free (key);
+      pgp_key_amalgamation_free (ka);
     }
     pgp_cert_key_iter_free (key_iter);
     pgp_keyid_free (keyid);
@@ -193,6 +196,7 @@ decrypt_cb (void *cookie_opaque,
       error (1, 0, "pgp_pkesk_decrypt: %s", pgp_error_to_string (err));
     }
     pgp_key_free (key);
+    pgp_key_amalgamation_free (ka);
 
     pgp_session_key_t sk = pgp_session_key_from_bytes (session_key,
                                                        session_key_len);
diff --git a/openpgp-ffi/include/sequoia/openpgp.h b/openpgp-ffi/include/sequoia/openpgp.h
index e08a4901..c9ced255 100644
--- a/openpgp-ffi/include/sequoia/openpgp.h
+++ b/openpgp-ffi/include/sequoia/openpgp.h
@@ -628,10 +628,10 @@ pgp_cert_valid_key_iter_t pgp_cert_key_iter_policy
     (pgp_cert_key_iter_t iter, pgp_policy_t policy, time_t when);
 
 /*/
-/// Returns a reference to the next key.  Returns NULL if there are no
+/// Returns a key amalgamation for 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);
+pgp_key_amalgamation_t pgp_cert_key_iter_next (pgp_cert_key_iter_t iter);
 
 /*/
 /// Frees an pgp_cert_key_iter_t.
@@ -722,7 +722,7 @@ void pgp_cert_valid_key_iter_secret (pgp_cert_valid_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
+/// Returns a key amalgamation to the next key.  Returns NULL if there are no
 /// more elements.
 ///
 /// If signature is not NULL, stores the current self-signature (if
@@ -733,9 +733,10 @@ void pgp_cert_valid_key_iter_unencrypted_secret (pgp_cert_valid_key_iter_t iter)
 /// If rev is not NULL, this stores the key's revocation status in
 /// *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);
+pgp_valid_key_amalgamation_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_valid_key_iter_t.
@@ -1053,6 +1054,64 @@ pgp_status_t pgp_cert_builder_generate(pgp_error_t *errp,
                                       pgp_signature_t *revocation);
 
 
+/* KeyAmalgamation */
+
+/*/
+/// Returns a reference to the Key Amalgamation's `Key`.
+/*/
+pgp_key_t pgp_key_amalgamation_key (pgp_key_amalgamation_t ka);
+
+/*/
+/// Frees the Key Amalgamation.
+/*/
+void pgp_key_amalgamation_free (pgp_key_amalgamation_t ka);
+
+/*/
+/// Clones the Key Amalgamation.
+/*/
+pgp_key_amalgamation_t pgp_key_amalgamation_clone (pgp_key_amalgamation_t ka);
+
+/*/
+/// Returns a human readable description of this object suitable for
+/// debugging.
+/*/
+char *pgp_key_amalgamation_debug (const pgp_key_amalgamation_t ka);
+
+
+/* ValidKeyAmalgamation */
+
+/*/
+/// Returns a reference to the Valid Key Amalgamation's `Key`.
+/*/
+pgp_key_t pgp_valid_key_amalgamation_key (pgp_valid_key_amalgamation_t ka);
+
+/*/
+/// Returns the Valid Key Amalgamation's revocation status.
+/*/
+pgp_revocation_status_t pgp_valid_key_amalgamation_revocation_status (pgp_valid_key_amalgamation_t ka);
+
+/*/
+/// Returns a reference to the Valid Key Amalgamation's binding signature.
+/*/
+pgp_signature_t pgp_valid_key_amalgamation_binding_signature (pgp_valid_key_amalgamation_t ka);
+
+/*/
+/// Frees the Valid Key Amalgamation.
+/*/
+void pgp_valid_key_amalgamation_free (pgp_valid_key_amalgamation_t ka);
+
+/*/
+/// Clones the Valid Key Amalgamation.
+/*/
+pgp_valid_key_amalgamation_t pgp_valid_key_amalgamation_clone (pgp_valid_key_amalgamation_t ka);
+
+/*/
+/// Returns a human readable description of this object suitable for
+/// debugging.
+/*/
+char *pgp_valid_key_amalgamation_debug (const pgp_valid_key_amalgamation_t ka);
+
+
 /* TSK */
 
 /*/
diff --git a/openpgp-ffi/include/sequoia/openpgp/types.h b/openpgp-ffi/include/sequoia/openpgp/types.h
index c0851fb7..ec883df6 100644
--- a/openpgp-ffi/include/sequoia/openpgp/types.h
+++ b/openpgp-ffi/include/sequoia/openpgp/types.h
@@ -395,6 +395,16 @@ typedef struct pgp_cert_valid_key_iter *pgp_cert_valid_key_iter_t;
 typedef struct pgp_cert *pgp_cert_t;
 
 /*/
+/// A key amalgamation.
+/*/
+typedef struct pgp_key_amalgamation *pgp_key_amalgamation_t;
+
+/*/
+/// A valid key amalgamation.
+/*/
+typedef struct pgp_valid_key_amalgamation *pgp_valid_key_amalgamation_t;
+
+/*/
 /// A parser for Certs
 ///
 /// A `CertParser` parses a keyring, which is simply zero or more
diff --git a/openpgp-ffi/src/cert.rs b/openpgp-ffi/src/cert.rs
index 4dd2953f..5f04ac8c 100644
--- a/openpgp-ffi/src/cert.rs
+++ b/openpgp-ffi/src/cert.rs
@@ -29,6 +29,7 @@ use super::packet_pile::PacketPile;
 use super::tsk::TSK;
 use super::revocation_status::RevocationStatus;
 use super::policy::Policy;
+use super::key_amalgamation::{KeyAmalgamation, ValidKeyAmalgamation};
 
 use crate::Maybe;
 use crate::RefRaw;
@@ -541,14 +542,13 @@ pub extern "C" fn pgp_cert_key_iter_policy<'a>(
 #[::sequoia_ffi_macros::extern_fn] #[no_mangle]
 pub extern "C" fn pgp_cert_key_iter_next<'a>(
     iter_wrapper: *mut KeyIterWrapper<'a>)
-    -> Maybe<Key>
+    -> Maybe<KeyAmalgamation<'a>>
 {
     let iter_wrapper = ffi_param_ref_mut!(iter_wrapper);
     iter_wrapper.next_called = true;
 
     if let Some(ka) = iter_wrapper.iter.as_mut().unwrap().next() {
-        Some(ka.key().mark_parts_unspecified_ref().mark_role_unspecified_ref())
-            .move_into_raw()
+        Some(ka.mark_parts_unspecified()).move_into_raw()
     } else {
         None
     }
@@ -763,7 +763,7 @@ pub extern "C" fn pgp_cert_valid_key_iter_next<'a>(
     iter_wrapper: *mut ValidKeyIterWrapper<'a>,
     sigo: Option<&mut *mut Signature>,
     rso: Option<&mut *mut RevocationStatus<'a>>)
-    -> Maybe<Key>
+    -> Maybe<ValidKeyAmalgamation<'a>>
 {
     let iter_wrapper = ffi_param_ref_mut!(iter_wrapper);
     iter_wrapper.next_called = true;
@@ -771,7 +771,6 @@ pub extern "C" fn pgp_cert_valid_key_iter_next<'a>(
     if let Some(ka) = iter_wrapper.iter.as_mut().unwrap().next() {
         let sig = ka.binding_signature();
         let rs = ka.revoked();
-        let key = ka.key();
 
         if let Some(ptr) = sigo {
             *ptr = sig.move_into_raw();
@@ -781,10 +780,7 @@ pub extern "C" fn pgp_cert_valid_key_iter_next<'a>(
             *ptr = rs.move_into_raw();
         }
 
-        let key
-            = key.mark_parts_unspecified_ref().mark_role_unspecified_ref();
-
-        Some(key).move_into_raw()
+        Some(ka.mark_parts_unspecified()).move_into_raw()
     } else {
         None
     }
diff --git a/openpgp-ffi/src/common.rs b/openpgp-ffi/src/common.rs
index f212c2a1..cc2deb5e 100644
--- a/openpgp-ffi/src/common.rs
+++ b/openpgp-ffi/src/common.rs
@@ -343,3 +343,4 @@ pub mod cert;
 pub mod tsk;
 pub mod revocation_status;
 pub mod policy;
+pub mod key_amalgamation;
diff --git a/openpgp-ffi/src/key_amalgamation.rs b/openpgp-ffi/src/key_amalgamation.rs
new file mode 100644
index 00000000..68144e30
--- /dev/null
+++ b/openpgp-ffi/src/key_amalgamation.rs
@@ -0,0 +1,86 @@
+//! `KeyAmalgamation`s.
+//!
+//!
+//! Wraps [`sequoia-openpgp::cert::key_amalgamation::KeyAmalgamation`].
+//!
+//! [`sequoia-openpgp::cert::key_amalgamation::KeyAmalgamation`]: ../../../sequoia_openpgp/cert/key_amalgamation/struct.KeyAmalgamation.html
+
+extern crate sequoia_openpgp as openpgp;
+use self::openpgp::packet::key;
+use self::openpgp::cert::amalgamation::ValidAmalgamation;
+
+use super::packet::key::Key;
+use super::packet::signature::Signature;
+use super::revocation_status::RevocationStatus;
+
+use crate::MoveIntoRaw;
+use crate::RefRaw;
+
+/// A local alias to appease the proc macro transformation.
+type ErasedKeyAmalgamation<'a> =
+    openpgp::cert::key_amalgamation::ErasedKeyAmalgamation<'a, key::UnspecifiedParts>;
+
+/// A `KeyAmalgamation` holds a `Key` and associated data.
+///
+/// Wraps [`sequoia-openpgp::cert::key_amalgamation::KeyAmalgamation`].
+///
+/// [`sequoia-openpgp::cert::key_amalgamation::KeyAmalgamation`]: ../../../sequoia_openpgp/cert/key_amalgamation/struct.KeyAmalgamation.html
+#[crate::ffi_wrapper_type(prefix = "pgp_",
+                     derive = "Clone, Debug")]
+pub struct KeyAmalgamation<'a>(ErasedKeyAmalgamation<'a>);
+
+/// A local alias to appease the proc macro transformation.
+type ValidErasedKeyAmalgamation<'a> =
+    openpgp::cert::key_amalgamation::ValidErasedKeyAmalgamation<'a, key::UnspecifiedParts>;
+
+/// Returns a reference to the `Key`.
+#[::sequoia_ffi_macros::extern_fn] #[no_mangle]
+pub extern "C" fn pgp_key_amalgamation_key<'a>(ka: *const KeyAmalgamation<'a>)
+    -> *const Key
+{
+    let ka = ka.ref_raw();
+
+    ka.key().mark_parts_unspecified_ref().mark_role_unspecified_ref()
+        .move_into_raw()
+}
+
+/// A `ValidKeyAmalgamation` holds a `Key` and associated data
+/// including a policy and a reference time.
+///
+/// Wraps [`sequoia-openpgp::cert::key_amalgamation::ValidKeyAmalgamation`].
+///
+/// [`sequoia-openpgp::cert::key_amalgamation::ValidKeyAmalgamation`]: ../../../sequoia_openpgp/cert/key_amalgamation/struct.ValidKeyAmalgamation.html
+#[crate::ffi_wrapper_type(prefix = "pgp_",
+                     derive = "Clone, Debug")]
+pub struct ValidKeyAmalgamation<'a>(ValidErasedKeyAmalgamation<'a>);
+
+/// Returns a reference to the `Key`.
+#[::sequoia_ffi_macros::extern_fn] #[no_mangle]
+pub extern "C" fn pgp_valid_key_amalgamation_key<'a>(ka: *const ValidKeyAmalgamation<'a>)
+    -> *const Key
+{
+    let ka = ka.ref_raw();
+
+    ka.key().mark_parts_unspecified_ref().mark_role_unspecified_ref()
+        .move_into_raw()
+}
+
+/// Returns the Key Amalgamation's revocation status.
+#[::sequoia_ffi_macros::extern_fn] #[no_mangle]
+pub extern "C" fn pgp_valid_key_amalgamation_revocation_status<'a>(ka: *const ValidKeyAmalgamation<'a>)
+    -> *mut RevocationStatus<'a>
+{
+    ka.ref_raw()
+        .revoked()
+        .move_into_raw()
+}
+
+/// Returns the Key Amalgamation's binding signature.
+#[::sequoia_ffi_macros::extern_fn] #[no_mangle]
+pub extern "C" fn pgp_valid_key_amalgamation_binding_signature<'a>(ka: *const ValidKeyAmalgamation<'a>)
+    -> *const Signature
+{
+    ka.ref_raw()
+        .binding_signature()
+        .move_into_raw()
+}
diff --git a/openpgp-ffi/src/parse/stream.rs b/openpgp-ffi/src/parse/stream.rs
index b36bb640..66e277ff 100644
--- a/openpgp-ffi/src/parse/stream.rs
+++ b/openpgp-ffi/src/parse/stream.rs
@@ -944,18 +944,21 @@ impl DecryptionHelper for DHelper {
 ///     pgp_keyid_t keyid = pgp_pkesk_recipient (pkesk);
 ///
 ///     pgp_cert_key_iter_t key_iter = pgp_cert_key_iter (cookie->key);
-///     pgp_key_t key;
-///     while ((key = pgp_cert_key_iter_next (key_iter))) {
+///     pgp_key_amalgamation_t ka;
+///     pgp_key_t key = NULL;
+///     while ((ka = pgp_cert_key_iter_next (key_iter))) {
+///       key = pgp_key_amalgamation_key (ka);
 ///       pgp_keyid_t this_keyid = pgp_key_keyid (key);
 ///       int match = pgp_keyid_equal (this_keyid, keyid);
 ///       pgp_keyid_free (this_keyid);
 ///       if (match)
 ///         break;
 ///       pgp_key_free (key);
+///       pgp_key_amalgamation_free (ka);
 ///     }
 ///     pgp_cert_key_iter_free (key_iter);
 ///     pgp_keyid_free (keyid);
-///     if (! key)
+///     if (! ka)
 ///       continue;
 ///
 ///     uint8_t algo;
@@ -967,6 +970,7 @@ impl DecryptionHelper for DHelper {
 ///       error (1, 0, "pgp_pkesk_decrypt: %s", pgp_error_to_string (err));
 ///     }
 ///     pgp_key_free (key);
+///     pgp_key_amalgamation_free (ka);
 ///
 ///     pgp_session_key_t sk = pgp_session_key_from_bytes (session_key,
 ///                                                        session_key_len);