openpgp-ffi: Use UserIDAmalgamations, not UserIDBundles.

  - Add the `UserID`, `UserIDAmalgamation` and
    `ValidUserIDAmalgamation` types, and some associated methods.

  - Replace the use of `UserIDBundle` with `UserIDAmalgamation` and
    `ValidUserIDAmalgamation`.

2 files changed, 136 insertions, 19 deletions

diff --git a/openpgp-ffi/include/sequoia/openpgp.h b/openpgp-ffi/include/sequoia/openpgp.h
index e9158f15..09b2f49e 100644
--- a/openpgp-ffi/include/sequoia/openpgp.h
+++ b/openpgp-ffi/include/sequoia/openpgp.h
@@ -570,7 +570,7 @@ pgp_packet_t pgp_literal_into_packet (pgp_literal_t literal);
 /*/
 void pgp_literal_free (pgp_literal_t literal);
 
-/* openpgp::cert::UserIDBundle.  */
+/* openpgp::amalgamation::UserIDAmalgamation.  */
 
 /*/
 /// Returns the user id.
@@ -581,26 +581,105 @@ void pgp_literal_free (pgp_literal_t literal);
 ///
 /// The caller must free the returned value.
 /*/
-char *pgp_user_id_bundle_user_id (pgp_user_id_bundle_t binding);
+char *pgp_user_id_amalgamation_user_id (pgp_user_id_amalgamation_t ua);
 
 /*/
-/// Returns a reference to the self-signature, if any.
+/// Frees the User ID Amalgamation.
 /*/
-pgp_signature_t pgp_user_id_bundle_selfsig(pgp_error_t *errp,
-                                           pgp_user_id_bundle_t binding,
-                                           pgp_policy_t policy);
+void pgp_user_id_amalgamation_free (pgp_user_id_amalgamation_t ua);
 
-/* openpgp::cert::UserIDBundleIter.  */
+/*/
+/// Clones the UserID Amalgamation.
+/*/
+pgp_user_id_amalgamation_t pgp_user_id_amalgamation_clone (pgp_user_id_amalgamation_t ua);
+
+/*/
+/// Returns a human readable description of this object suitable for
+/// debugging.
+/*/
+char *pgp_user_id_amalgamation_debug (const pgp_user_id_amalgamation_t ua);
+
+/*/
+/// Returns the user id.
+///
+/// This function may fail and return NULL if the user id contains an
+/// interior NUL byte.  We do this rather than complicate the API, as
+/// there is no valid use for such user ids; they must be malicious.
+///
+/// The caller must free the returned value.
+/*/
+pgp_user_id_t pgp_valid_user_id_amalgamation_user_id
+    (pgp_valid_user_id_amalgamation_t ua);
+
+/*/
+/// Returns the Valid UserID Amalgamation's revocation status.
+/*/
+pgp_revocation_status_t pgp_valid_user_id_amalgamation_revocation_status
+    (pgp_valid_user_id_amalgamation_t ua);
+
+/*/
+/// Returns a reference to the self-signature.
+/*/
+pgp_signature_t pgp_valid_user_id_amalgamation_binding_signature
+    (pgp_valid_user_id_amalgamation_t ua);
+
+/*/
+/// Changes the policy applied to the `ValidUserIDAmalgamation`.
+///
+/// This consumes the UserID amalgamation.
+/*/
+pgp_valid_user_id_amalgamation_t pgp_valid_user_id_amalgamation_with_policy
+    (pgp_error_t *errp,
+     pgp_valid_user_id_amalgamation_t ua,
+     pgp_policy_t policy,
+     time_t time);
+
+/*/
+/// Frees the User ID Amalgamation.
+/*/
+void pgp_valid_user_id_amalgamation_free (pgp_valid_user_id_amalgamation_t ua);
+
+/*/
+/// Clones the UserID Amalgamation.
+/*/
+pgp_valid_user_id_amalgamation_t pgp_valid_user_id_amalgamation_clone (pgp_valid_user_id_amalgamation_t ua);
+
+/*/
+/// Returns a human readable description of this object suitable for
+/// debugging.
+/*/
+char *pgp_valid_user_id_amalgamation_debug (const pgp_valid_user_id_amalgamation_t ua);
+
+/* openpgp::cert::UserIDIter.  */
+
+/*/
+/// Returns the next element in the iterator.
+/*/
+pgp_user_id_amalgamation_t pgp_cert_user_id_iter_next (pgp_cert_user_id_iter_t iter);
+
+/*/
+/// Sets a policy.
+///
+/// Only User IDs that are valid according to the policy at the
+/// specified time are returned.
+/*/
+pgp_cert_valid_user_id_iter_t pgp_cert_user_id_iter_policy
+    (pgp_cert_user_id_iter_t iter, pgp_policy_t policy, time_t when);
+
+/*/
+/// Frees a pgp_cert_user_id_iter_t.
+/*/
+void pgp_cert_user_id_iter_free (pgp_cert_user_id_iter_t iter);
 
 /*/
 /// Returns the next element in the iterator.
 /*/
-pgp_user_id_bundle_t pgp_user_id_bundle_iter_next (pgp_user_id_bundle_iter_t iter);
+pgp_valid_user_id_amalgamation_t pgp_cert_valid_user_id_iter_next (pgp_cert_valid_user_id_iter_t iter);
 
 /*/
-/// Frees an pgp_user_id_bundle_iter_t.
+/// Frees a pgp_cert_valid_user_id_iter_t.
 /*/
-void pgp_user_id_bundle_iter_free (pgp_user_id_bundle_iter_t iter);
+void pgp_cert_valid_user_id_iter_free (pgp_cert_valid_user_id_iter_t iter);
 
 /* openpgp::cert::KeyIter.  */
 
@@ -620,10 +699,10 @@ void pgp_cert_key_iter_secret (pgp_cert_key_iter_t iter);
 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.
+/// Sets a policy.
 ///
-/// Note: you may not call this function after starting to iterate.
+/// Only keys that are valid according to the policy at the specified
+/// time are returned.
 /*/
 pgp_cert_valid_key_iter_t pgp_cert_key_iter_policy
     (pgp_cert_key_iter_t iter, pgp_policy_t policy, time_t when);
@@ -925,9 +1004,16 @@ pgp_cert_t pgp_cert_set_expiration_time(pgp_error_t *errp,
 int pgp_cert_is_tsk(pgp_cert_t cert);
 
 /*/
-/// Returns an iterator over the `UserIDBundle`s.
+/// Returns an iterator over the `UserID`s.
 /*/
-pgp_user_id_bundle_iter_t pgp_cert_user_id_bundle_iter (pgp_cert_t cert);
+pgp_cert_user_id_iter_t pgp_cert_user_id_iter (pgp_cert_t cert);
+
+/*/
+/// Returns an iterator over the valid `UserID`s.
+/*/
+pgp_cert_valid_user_id_iter_t pgp_cert_valid_user_id_iter (pgp_cert_t cert,
+                                                           pgp_policy_t policy,
+                                                           time_t when);
 
 /*/
 /// Returns an iterator over all `Key`s in a Cert.
@@ -1361,6 +1447,27 @@ const uint8_t *pgp_user_attribute_value (pgp_packet_t ua,
 					size_t *value_len);
 
 /*/
+/// Frees a pgp_user_id_t.
+/*/
+void pgp_user_id_free (pgp_user_id_t userid);
+
+/*/
+/// Clones the UserID.
+/*/
+pgp_user_id_t pgp_user_id_clone (pgp_user_id_t userid);
+
+/*/
+/// Returns a human readable description of this object suitable for
+/// debugging.
+/*/
+char *pgp_user_id_debug (const pgp_user_id_t userid);
+
+/*/
+/// Compares passwords.
+/*/
+bool pgp_user_id_equal (const pgp_user_id_t a, const pgp_user_id_t b);
+
+/*/
 /// Returns the session key.
 ///
 /// `key` of size `key_len` must be a buffer large enough to hold the
diff --git a/openpgp-ffi/include/sequoia/openpgp/types.h b/openpgp-ffi/include/sequoia/openpgp/types.h
index 14c4ef08..74b4f1d6 100644
--- a/openpgp-ffi/include/sequoia/openpgp/types.h
+++ b/openpgp-ffi/include/sequoia/openpgp/types.h
@@ -364,14 +364,24 @@ typedef struct pgp_packet_parser_eof *pgp_packet_parser_eof_t;
 typedef struct pgp_packet_pile *pgp_packet_pile_t;
 
 /*/
-/// A `UserIDBinding`.
+/// An iterator over User IDs in a Cert.
 /*/
-typedef struct pgp_user_id_bundle *pgp_user_id_bundle_t;
+typedef struct pgp_cert_user_id_iter *pgp_cert_user_id_iter_t;
 
 /*/
-/// An iterator over `UserIDBinding`s.
+/// An iterator over valid User IDs in a Cert.
 /*/
-typedef struct pgp_user_id_bundle_iter *pgp_user_id_bundle_iter_t;
+typedef struct pgp_cert_valid_user_id_iter *pgp_cert_valid_user_id_iter_t;
+
+/*/
+/// A `UserIDAmalgmation`.
+/*/
+typedef struct pgp_user_id_amalgamation *pgp_user_id_amalgamation_t;
+
+/*/
+/// A `UserIDAmalgmation`.
+/*/
+typedef struct pgp_valid_user_id_amalgamation *pgp_valid_user_id_amalgamation_t;
 
 /*/
 /// An iterator over keys in a Cert.