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,238 @@
+use {
+    anyhow::Result,
+    base64::{prelude::BASE64_STANDARD, Engine},
+    chacha20poly1305::{
+        aead::{Aead, KeyInit, OsRng, Payload},
+        AeadCore, ChaCha20Poly1305, Nonce,
+    },
+};
+
+// https://specs.walletconnect.com/2.0/specs/clients/core/crypto/
+// crypto-envelopes
+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 },
+}
+
+/// Non-owning convenient representation of the decoded payload blob.
+#[derive(Clone, Debug, PartialEq, Eq)]
+struct EncodingParams<'a> {
+    /// Encrypted payload.
+    sealed: &'a [u8],
+    /// Initialization Vector.
+    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),
+        }
+    }
+}
+
+/// Encrypts and encodes the plain-text payload.
+///
+/// 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()?,
+    ))
+}
+
+/// Decodes and decrypts the Type0 envelope payload.
+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,73 @@
+//! https://specs.walletconnect.com/2.0/specs/clients/sign/session-proposal
+
+use {
+    anyhow::Result,
+    hkdf::Hkdf,
+    rand::{rngs::OsRng, CryptoRng, RngCore},
+    sha2::{Digest, Sha256},
+    std::fmt::{Debug, Formatter},
+    x25519_dalek::{EphemeralSecret, PublicKey},
+};
+
+#[derive(Clone)]
+pub struct SessionKey {
+    sym_key: [u8; 32],
+    public_key: PublicKey,
+}
+
+impl Debug for SessionKey {
+    /// Custom debug to hide the symmetrical key.
+    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 {
+    /// Creates new session key from `osrng`.
+    ///
+    /// Helper for  when `osrng` is good enough.
+    pub fn from_osrng(sender_public_key: &[u8; 32]) -> Result<Self> {
+        SessionKey::diffie_hellman(OsRng, sender_public_key)
+    }
+
+    /// Performs Diffie-Hellman symmetric key derivation.
+    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)
+    }
+
+    /// Gets symmetic key reference.
+    pub fn symmetric_key(&self) -> &[u8; 32] {
+        &self.sym_key
+    }
+
+    /// Gets "our" public key used in symmetric key derivation.
+    pub fn diffie_public_key(&self) -> &[u8; 32] {
+        self.public_key.as_bytes()
+    }
+
+    /// Generates new session topic.
+    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;