Merge #753: Backport #752 to 0.29.x

f12bde6 Deprecate `ElligatorSwiftParty` in favor of `Party` (Shing Him Ng)
33fda15 Create `Party` enum (Shing Him Ng)

Pull request description:

  Also, we should consider backporting this to the version used by rust-bitcoin 0.32.

  _Originally posted by apoelstra in #752 (comment)

  Backport #752 to the [version used by rust-bitcoin 0.32](https://github.com/rust-bitcoin/rust-bitcoin/blob/7af9e33f2b9033cf2701725eba280e14ebda0cf5/bitcoin/Cargo.toml#L35)

ACKs for top commit:
  apoelstra:
    ACK f12bde6; successfully ran local tests

Tree-SHA512: e8184c0df1f19a6512b1168bb1cf49e906de6d7f51ef1f9a4e3977422c36e603c3325fedb1485efa49ea8cb0361b54a293cdfefef10f3370541c8086b2b28bff

src/ellswift.rs

@@ -153,7 +153,7 @@ impl ElligatorSwift {
     /// ```
     /// # #[cfg(feature = "alloc")] {
     ///     use secp256k1::{
-    ///         ellswift::{ElligatorSwift, ElligatorSwiftParty},
+    ///         ellswift::{ElligatorSwift, Party},
     ///         PublicKey, SecretKey, XOnlyPublicKey, Secp256k1,
     ///     };
     ///     use core::str::FromStr;
@@ -166,8 +166,8 @@ impl ElligatorSwift {
     ///     let alice_es = ElligatorSwift::from_seckey(&secp, alice_sk, None);
     ///     let bob_es = ElligatorSwift::from_seckey(&secp, bob_sk, None);
     ///
-    ///     let alice_shared_secret = ElligatorSwift::shared_secret(alice_es, bob_es, alice_sk, ElligatorSwiftParty::A, None);
-    ///     let bob_shared_secret = ElligatorSwift::shared_secret(alice_es, bob_es, bob_sk, ElligatorSwiftParty::B, None);
+    ///     let alice_shared_secret = ElligatorSwift::shared_secret(alice_es, bob_es, alice_sk, Party::Initiator, None);
+    ///     let bob_shared_secret = ElligatorSwift::shared_secret(alice_es, bob_es, bob_sk, Party::Responder, None);
     ///
     ///     assert_eq!(alice_shared_secret, bob_shared_secret);
     /// # }
@@ -176,18 +176,19 @@ impl ElligatorSwift {
         ellswift_a: ElligatorSwift,
         ellswift_b: ElligatorSwift,
         secret_key: SecretKey,
-        party: ElligatorSwiftParty,
+        party: impl Into<Party>,
         data: Option<&[u8]>,
     ) -> ElligatorSwiftSharedSecret {
         let mut shared_secret = [0u8; 32];
+        let p: Party = party.into();
         unsafe {
             let ret = ffi::secp256k1_ellswift_xdh(
                 ffi::secp256k1_context_no_precomp,
                 shared_secret.as_mut_c_ptr(),
                 ellswift_a.as_c_ptr(),
                 ellswift_b.as_c_ptr(),
                 secret_key.as_c_ptr(),
-                party.to_ffi_int(),
+                p.to_ffi_int(),
                 ffi::secp256k1_ellswift_xdh_hash_function_bip324,
                 data.as_c_ptr() as *mut c_void,
             );
@@ -205,22 +206,23 @@ impl ElligatorSwift {
         ellswift_a: ElligatorSwift,
         ellswift_b: ElligatorSwift,
         secret_key: SecretKey,
-        party: ElligatorSwiftParty,
+        party: impl Into<Party>,
         mut hash_function: F,
     ) -> ElligatorSwiftSharedSecret
     where
         F: FnMut([u8; 32], [u8; 64], [u8; 64]) -> ElligatorSwiftSharedSecret,
     {
         let mut shared_secret = [0u8; 32];
         let hashfp = hash_callback::<F>;
+        let p: Party = party.into();
         unsafe {
             let ret = ffi::secp256k1_ellswift_xdh(
                 ffi::secp256k1_context_no_precomp,
                 shared_secret.as_mut_c_ptr(),
                 ellswift_a.0.as_c_ptr(),
                 ellswift_b.0.as_c_ptr(),
                 secret_key.as_c_ptr(),
-                party.to_ffi_int(),
+                p.to_ffi_int(),
                 Some(hashfp),
                 &mut hash_function as *mut F as *mut c_void,
             );
@@ -285,18 +287,38 @@ impl ElligatorSwiftSharedSecret {
 /// we are. In this context, "we" means the party that is using this library, and possesses the
 /// secret key passed to `ElligatorSwift::shared_secret`.
 #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
+#[deprecated(since = "0.29.2", note = "Use `Party` instead.")]
 pub enum ElligatorSwiftParty {
     /// We are the initiator of the ECDH
     A,
     /// We are the responder of the ECDH
     B,
 }
 
-impl ElligatorSwiftParty {
+/// Represents the two parties in ECDH
+#[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub enum Party {
+    /// The party that starts the key exchange or communication process
+    Initiator,
+    /// The party that responds to the initiator's communications
+    Responder,
+}
+
+#[allow(deprecated)]
+impl From<ElligatorSwiftParty> for Party {
+    fn from(value: ElligatorSwiftParty) -> Self {
+        match value {
+            ElligatorSwiftParty::A => Party::Initiator,
+            ElligatorSwiftParty::B => Party::Responder,
+        }
+    }
+}
+
+impl Party {
     fn to_ffi_int(self) -> c_int {
         match self {
-            ElligatorSwiftParty::A => 0,
-            ElligatorSwiftParty::B => 1,
+            Party::Initiator => 0,
+            Party::Responder => 1,
         }
     }
 }
@@ -339,7 +361,7 @@ mod tests {
 
     use crate::ellswift::ElligatorSwift;
     #[cfg(all(not(secp256k1_fuzz), feature = "alloc"))]
-    use crate::ellswift::{ElligatorSwiftParty, ElligatorSwiftSharedSecret};
+    use crate::ellswift::{ElligatorSwiftSharedSecret, Party};
     #[cfg(all(not(secp256k1_fuzz), feature = "alloc"))]
     use crate::SecretKey;
     use crate::{from_hex, PublicKey, XOnlyPublicKey};
@@ -385,7 +407,7 @@ mod tests {
             ell,
             ell,
             SecretKey::from_slice(&priv32).unwrap(),
-            ElligatorSwiftParty::A,
+            Party::Initiator,
             |_, _, _| ElligatorSwiftSharedSecret([0xff; 32]),
         );
         assert_eq!(pk, ElligatorSwiftSharedSecret([0xff; 32]));
@@ -599,8 +621,7 @@ mod tests {
                 )
             };
             let sec_key = SecretKey::from_slice(&my_secret).unwrap();
-            let initiator =
-                if initiator == 0 { ElligatorSwiftParty::B } else { ElligatorSwiftParty::A };
+            let initiator = if initiator == 0 { Party::Responder } else { Party::Initiator };
 
             let shared = ElligatorSwift::shared_secret(el_a, el_b, sec_key, initiator, None);