feat: add WalletConnect v2 Sign API

This change adds WalletConnect v2 Sign API, as per:
https://specs.walletconnect.com/2.0/specs/clients/sign/

Please note that although the specification is fairly thorough, there
are some inconsistencies. This implementation is derived from specs,
analyzing ws traffic in browsers devtools, as well as the original
WalletConnect JavaScript client at:
https://github.com/WalletConnect/walletconnect-monorepo

Design decisions:

Modularity:
- RPC and crypto modules are not dependent on each other, so client
  implementations don't have to use their own crypto implementation.

Closes: #47

Author: silvestrst-crypto

Cargo.toml

@@ -9,18 +9,21 @@ license = "Apache-2.0"
 [workspace]
 members = [
     "relay_client",
-    "relay_rpc"
+    "relay_rpc",
+    "sign_api"
 ]
 
 [features]
 default = ["full"]
-full = ["client", "rpc"]
+full = ["client", "rpc", "sign_api"]
 client = ["dep:relay_client"]
 rpc = ["dep:relay_rpc"]
+sign_api = ["dep:sign_api"]
 
 [dependencies]
 relay_client = { path = "./relay_client", optional = true }
 relay_rpc = { path = "./relay_rpc", optional = true }
+sign_api = { path = "./sign_api", optional = true }
 
 [dev-dependencies]
 anyhow = "1"

sign_api/Cargo.toml

@@ -0,0 +1,26 @@
+[package]
+name = "sign_api"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+anyhow = "1"
+base58 = "0.2"
+base64 = "0.21"
+base64-url = "2.0"
+chacha20poly1305 = "0.10"
+chrono = "0.4"
+hex = "0.4"
+hex-literal = "0.4"
+hkdf = "0.12"
+lazy_static = "1.4"
+once_cell = "1.16"
+paste = "1.0"
+rand = "0.8"
+regex = "1.10"
+sha2 = "0.10"
+serde = { version = "1.0", features = ["derive", "rc"] }
+serde_json = "1.0"
+thiserror = "1.0"
+x25519-dalek = { version = "2.0", features = ["static_secrets"] }
+url = "2.4"

sign_api/src/crypto.rs

@@ -0,0 +1,2 @@
+pub mod payload;
+pub mod session;

sign_api/src/crypto/payload.rs

@@ -0,0 +1,227 @@
+use anyhow::Result;
+use base64::prelude::BASE64_STANDARD;
+use base64::Engine;
+use chacha20poly1305::aead::{Aead, KeyInit, OsRng, Payload};
+use chacha20poly1305::{AeadCore, ChaCha20Poly1305, Nonce};
+
+const TYPE_0: u8 = 0;
+const TYPE_1: u8 = 1;
+const TYPE_INDEX: usize = 0;
+const TYPE_LENGTH: usize = 1;
+const IV_LENGTH: usize = 12;
+const PUB_KEY_LENGTH: usize = 32;
+const SYM_KEY_LENGTH: usize = 32;
+
+pub type Iv = [u8; IV_LENGTH];
+pub type SymKey = [u8; SYM_KEY_LENGTH];
+pub type PubKey = [u8; PUB_KEY_LENGTH];
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum EnvelopeType<'a> {
+    Type0,
+    Type1 { sender_public_key: &'a PubKey },
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+struct EncodingParams<'a> {
+    sealed: &'a [u8],
+    iv: &'a Iv,
+    envelope_type: EnvelopeType<'a>,
+}
+
+impl<'a> EncodingParams<'a> {
+    fn parse_decoded(data: &'a [u8]) -> Result<Self> {
+        let envelope_type = data[0];
+        match envelope_type {
+            TYPE_0 => {
+                let iv_index: usize = TYPE_INDEX + TYPE_LENGTH;
+                let sealed_index: usize = iv_index + IV_LENGTH;
+                Ok(EncodingParams {
+                    iv: data[iv_index..=IV_LENGTH].try_into()?,
+                    sealed: &data[sealed_index..],
+                    envelope_type: EnvelopeType::Type0,
+                })
+            }
+            TYPE_1 => {
+                let key_index: usize = TYPE_INDEX + TYPE_LENGTH;
+                let iv_index: usize = key_index + PUB_KEY_LENGTH;
+                let sealed_index: usize = iv_index + IV_LENGTH;
+                Ok(EncodingParams {
+                    iv: data[iv_index..=IV_LENGTH].try_into()?,
+                    sealed: &data[sealed_index..],
+                    envelope_type: EnvelopeType::Type1 {
+                        sender_public_key: data[key_index..=PUB_KEY_LENGTH].try_into()?,
+                    },
+                })
+            }
+            _ => anyhow::bail!("Invalid envelope type: {}", envelope_type),
+        }
+    }
+}
+
+// TODO: RNG as an input
+pub fn encrypt_and_encode<T>(envelope_type: EnvelopeType, msg: T, key: &SymKey) -> Result<String>
+where
+    T: AsRef<[u8]>,
+{
+    let payload = Payload {
+        msg: msg.as_ref(),
+        aad: &[],
+    };
+    let nonce = ChaCha20Poly1305::generate_nonce(&mut OsRng);
+
+    let sealed = encrypt(&nonce, payload, key)?;
+    Ok(encode(
+        envelope_type,
+        sealed.as_slice(),
+        nonce.as_slice().try_into()?,
+    ))
+}
+
+pub fn decode_and_decrypt_type0<T>(msg: T, key: &SymKey) -> Result<String>
+where
+    T: AsRef<[u8]>,
+{
+    let data = BASE64_STANDARD.decode(msg)?;
+    let decoded = EncodingParams::parse_decoded(&data)?;
+    if let EnvelopeType::Type1 { .. } = decoded.envelope_type {
+        anyhow::bail!("Expected envelope type 0");
+    }
+
+    let payload = Payload {
+        msg: decoded.sealed,
+        aad: &[],
+    };
+    let decrypted = decrypt(decoded.iv.try_into()?, payload, key)?;
+
+    Ok(String::from_utf8(decrypted)?)
+}
+
+fn encrypt(nonce: &Nonce, payload: Payload<'_, '_>, key: &SymKey) -> Result<Vec<u8>> {
+    let cipher = ChaCha20Poly1305::new(key.try_into()?);
+    let sealed = cipher
+        .encrypt(nonce, payload)
+        .map_err(|e| anyhow::anyhow!("Encryption failed, err: {:?}", e))?;
+
+    Ok(sealed)
+}
+
+fn encode(envelope_type: EnvelopeType, sealed: &[u8], iv: &Iv) -> String {
+    match envelope_type {
+        EnvelopeType::Type0 => BASE64_STANDARD.encode([&[TYPE_0], iv.as_slice(), sealed].concat()),
+        EnvelopeType::Type1 { sender_public_key } => {
+            BASE64_STANDARD.encode([&[TYPE_1], sender_public_key.as_slice(), iv, sealed].concat())
+        }
+    }
+}
+
+fn decrypt(nonce: &Nonce, payload: Payload<'_, '_>, key: &SymKey) -> Result<Vec<u8>> {
+    let cipher = ChaCha20Poly1305::new(key.try_into()?);
+    let unsealed = cipher
+        .decrypt(nonce, payload)
+        .map_err(|e| anyhow::anyhow!("Decryption failed, err: {:?}", e))?;
+
+    Ok(unsealed)
+}
+
+#[cfg(test)]
+mod tests {
+    use hex_literal::hex;
+
+    use super::*;
+
+    // https://www.rfc-editor.org/rfc/rfc7539#section-2.8.2
+    // Below constans are taken from this section of the RFC.
+
+    const PLAINTEXT: &str = r#"Ladies and Gentlemen of the class of '99: If I could offer you only one tip for the future, sunscreen would be it."#;
+    const CIPHERTEXT: [u8; 114] = hex!(
+        "d3 1a 8d 34 64 8e 60 db 7b 86 af bc 53 ef 7e c2
+         a4 ad ed 51 29 6e 08 fe a9 e2 b5 a7 36 ee 62 d6
+         3d be a4 5e 8c a9 67 12 82 fa fb 69 da 92 72 8b
+         1a 71 de 0a 9e 06 0b 29 05 d6 a5 b6 7e cd 3b 36
+         92 dd bd 7f 2d 77 8b 8c 98 03 ae e3 28 09 1b 58
+         fa b3 24 e4 fa d6 75 94 55 85 80 8b 48 31 d7 bc
+         3f f4 de f0 8e 4b 7a 9d e5 76 d2 65 86 ce c6 4b
+         61 16"
+    );
+    const TAG: [u8; 16] = hex!("1a e1 0b 59 4f 09 e2 6a 7e 90 2e cb d0 60 06 91");
+    const SYMKEY: SymKey = hex!(
+        "80 81 82 83 84 85 86 87 88 89 8a 8b 8c 8d 8e 8f
+         90 91 92 93 94 95 96 97 98 99 9a 9b 9c 9d 9e 9f"
+    );
+    const AAD: [u8; 12] = hex!("50 51 52 53 c0 c1 c2 c3 c4 c5 c6 c7");
+    const IV: Iv = hex!("07 00 00 00 40 41 42 43 44 45 46 47");
+
+    /// Tests WCv2 encoding and decoding.
+    #[test]
+    fn test_decode_encoded() -> Result<()> {
+        let iv: &Iv = IV.as_slice().try_into()?;
+        let sealed = [CIPHERTEXT.as_slice(), TAG.as_slice()].concat();
+
+        let encoded = encode(EnvelopeType::Type0, &sealed, iv);
+        assert_eq!(
+            encoded,
+            "AAcAAABAQUJDREVGR9MajTRkjmDbe4avvFPvfsKkre1RKW4I/qnitac27mLWPb6kXoypZxKC+vtp2pJyixpx3gqeBgspBdaltn7NOzaS3b1/LXeLjJgDruMoCRtY+rMk5PrWdZRVhYCLSDHXvD/03vCOS3qd5XbSZYbOxkthFhrhC1lPCeJqfpAuy9BgBpE="
+        );
+
+        let data = BASE64_STANDARD.decode(&encoded)?;
+        let decoded = EncodingParams::parse_decoded(&data)?;
+        assert_eq!(decoded.envelope_type, EnvelopeType::Type0);
+        assert_eq!(decoded.sealed, sealed);
+        assert_eq!(decoded.iv, iv);
+
+        Ok(())
+    }
+
+    /// Tests ChaCha20-Poly1305 encryption against the RFC test vector.
+    ///
+    /// https://www.rfc-editor.org/rfc/rfc7539#section-2.8.2
+    /// Please note that this test vector has an
+    /// "Additional Authentication Data", in practice, we will likely
+    /// be using this algorithm without "AAD".
+    #[test]
+    fn test_encryption() -> Result<()> {
+        let payload = Payload {
+            msg: PLAINTEXT.as_bytes(),
+            aad: AAD.as_slice(),
+        };
+        let iv = IV.as_slice().try_into()?;
+
+        let sealed = encrypt(iv, payload, &SYMKEY)?;
+        assert_eq!(sealed, [CIPHERTEXT.as_slice(), TAG.as_slice()].concat());
+
+        Ok(())
+    }
+
+    /// Tests that encrypted message can be decrypted back.
+    #[test]
+    fn test_decrypt_encrypted() -> Result<()> {
+        let iv = IV.as_slice().try_into()?;
+
+        let seal_payload = Payload {
+            msg: PLAINTEXT.as_bytes(),
+            aad: AAD.as_slice(),
+        };
+        let sealed = encrypt(iv, seal_payload, &SYMKEY)?;
+
+        let unseal_payload = Payload {
+            msg: &sealed,
+            aad: AAD.as_slice(),
+        };
+        let unsealed = decrypt(iv, unseal_payload, &SYMKEY)?;
+
+        assert_eq!(PLAINTEXT.to_string(), String::from_utf8(unsealed)?);
+
+        Ok(())
+    }
+
+    /// Tests that plain text can be WCv2 serialized and deserialized back.
+    #[test]
+    fn test_encrypt_encode_decode_decrypt() -> Result<()> {
+        let encoded = encrypt_and_encode(EnvelopeType::Type0, PLAINTEXT, &SYMKEY)?;
+        let decoded = decode_and_decrypt_type0(&encoded, &SYMKEY)?;
+        assert_eq!(decoded, PLAINTEXT);
+
+        Ok(())
+    }
+}

sign_api/src/crypto/session.rs

@@ -0,0 +1,61 @@
+use std::fmt::{Debug, Formatter};
+
+use anyhow::Result;
+use hkdf::Hkdf;
+use rand::{rngs::OsRng, CryptoRng, RngCore};
+use sha2::{Digest, Sha256};
+use x25519_dalek::{EphemeralSecret, PublicKey};
+
+pub struct SessionKey {
+    sym_key: [u8; 32],
+    public_key: PublicKey,
+}
+
+impl Debug for SessionKey {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("WalletConnectUrl")
+            .field("sym_key", &"********")
+            .field("public_key", &self.public_key)
+            .finish()
+    }
+}
+
+impl SessionKey {
+    pub fn from_osrng(sender_public_key: &[u8; 32]) -> Result<Self> {
+        SessionKey::diffie_hellman(OsRng, sender_public_key)
+    }
+
+    pub fn diffie_hellman<T>(csprng: T, sender_public_key: &[u8; 32]) -> Result<Self>
+    where
+        T: RngCore + CryptoRng,
+    {
+        let single_use_private_key = EphemeralSecret::random_from_rng(csprng);
+        let public_key = PublicKey::from(&single_use_private_key);
+
+        let ikm = single_use_private_key.diffie_hellman(&PublicKey::from(*sender_public_key));
+
+        let mut session_sym_key = Self {
+            sym_key: [0u8; 32],
+            public_key,
+        };
+        let hk = Hkdf::<Sha256>::new(None, ikm.as_bytes());
+        hk.expand(&[], &mut session_sym_key.sym_key)
+            .map_err(|e| anyhow::anyhow!("Failed to generate SymKey: {e}"))?;
+
+        Ok(session_sym_key)
+    }
+
+    pub fn symmetric_key(&self) -> &[u8; 32] {
+        &self.sym_key
+    }
+
+    pub fn diffie_public_key(&self) -> &[u8; 32] {
+        self.public_key.as_bytes()
+    }
+
+    pub fn generate_topic(&self) -> String {
+        let mut hasher = Sha256::new();
+        hasher.update(self.sym_key);
+        hex::encode(hasher.finalize())
+    }
+}

sign_api/src/lib.rs

@@ -0,0 +1,3 @@
+pub mod crypto;
+pub mod pairing_uri;
+pub mod rpc;