Merge #752: Create Party enum and deprecate ElligatorSwiftParty in favor of it

bf2c35c Deprecate `ElligatorSwiftParty` in favor of `Party` (Shing Him Ng)
3b7d393 Create `Party` enum (Shing Him Ng)

Pull request description:

  The initial naming of ElligatorSwiftParty wasn't very descriptive, so it will be deprecated in favor of a more descriptive `Party` enum. I updated `shared_secret` and `shared_secret_with_hasher` to accept the new `Party` enum as well - I'm not sure if there's a better way to do it, but changing it to an `impl Into<Party>` should preserve backwards compatibility

  Fixes #741

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

Tree-SHA512: c516b8797b53e8e4167666ee6c93be61f67f2e71d33ba7354d6432199bd1f80680eea030c0c00ee5c0ba23204439d8c63c0efb8fc753f13e4cec189f7eee9a36

Author: apoelstra

src/ellswift.rs

@@ -154,7 +154,7 @@ impl ElligatorSwift {
     /// ```
     /// # #[cfg(feature = "alloc")] {
     ///     use secp256k1::{
-    ///         ellswift::{ElligatorSwift, ElligatorSwiftParty},
+    ///         ellswift::{ElligatorSwift, Party},
     ///         PublicKey, SecretKey, XOnlyPublicKey, Secp256k1,
     ///     };
     ///     use core::str::FromStr;
@@ -167,8 +167,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);
     /// # }
@@ -177,18 +177,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,
             );
@@ -206,22 +207,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,
             );
@@ -291,18 +293,38 @@ impl ElligatorSwiftSharedSecret {
 /// This distinction is important because the different parties compute different
 /// hashes of the shared secret.
 #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
+#[deprecated(since = "0.30.0", 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,
         }
     }
 }
@@ -345,7 +367,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};
@@ -391,7 +413,7 @@ mod tests {
             ell,
             ell,
             SecretKey::from_slice(&priv32).unwrap(),
-            ElligatorSwiftParty::A,
+            Party::Initiator,
             |_, _, _| ElligatorSwiftSharedSecret([0xff; 32]),
         );
         assert_eq!(pk, ElligatorSwiftSharedSecret([0xff; 32]));
@@ -605,8 +627,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);