add monero seed support (#252)

* add monero seed support

* fix some of the pr comments

* remove languages module and unnecessary error returns

* Clean classic seed impl

Fixes a few issues regarding Zeroize usage/API safety. Mainly a cleanup.

---------

Co-authored-by: Luke Parker <lukeparker5132@gmail.com>

Cargo.lock

@@ -5037,6 +5037,7 @@ name = "monero-serai"
 version = "0.1.2-alpha"
 dependencies = [
  "base58-monero",
+ "crc",
  "curve25519-dalek 3.2.0",
  "dalek-ff-group",
  "digest_auth",

coins/monero/Cargo.toml

@@ -15,6 +15,7 @@ rustdoc-args = ["--cfg", "docsrs"]
 hex-literal = "0.3"
 lazy_static = "1"
 thiserror = "1"
+crc = "3"
 
 rand_core = "0.6"
 rand_chacha = { version = "0.3", optional = true }

coins/monero/src/tests/mod.rs

@@ -1,3 +1,4 @@
 mod clsag;
 mod bulletproofs;
 mod address;
+mod seed;

coins/monero/src/tests/seed.rs

@@ -0,0 +1,177 @@
+use zeroize::Zeroizing;
+
+use rand_core::OsRng;
+
+use curve25519_dalek::scalar::Scalar;
+
+use crate::{
+  hash,
+  wallet::seed::{Seed, Language, classic::trim_by_lang},
+};
+
+#[test]
+fn test_classic_seed() {
+  struct Vector {
+    language: Language,
+    seed: String,
+    spend: String,
+    view: String,
+  }
+
+  let vectors = [
+    Vector {
+      language: Language::Chinese,
+      seed: "摇 曲 艺 武 滴 然 效 似 赏 式 祥 歌 买 疑 小 碧 堆 博 键 房 鲜 悲 付 喷 武".into(),
+      spend: "a5e4fff1706ef9212993a69f246f5c95ad6d84371692d63e9bb0ea112a58340d".into(),
+      view: "1176c43ce541477ea2f3ef0b49b25112b084e26b8a843e1304ac4677b74cdf02".into(),
+    },
+    Vector {
+      language: Language::English,
+      seed: "washing thirsty occur lectures tuesday fainted toxic adapt \
+               abnormal memoir nylon mostly building shrugged online ember northern \
+               ruby woes dauntless boil family illness inroads northern"
+        .into(),
+      spend: "c0af65c0dd837e666b9d0dfed62745f4df35aed7ea619b2798a709f0fe545403".into(),
+      view: "513ba91c538a5a9069e0094de90e927c0cd147fa10428ce3ac1afd49f63e3b01".into(),
+    },
+    Vector {
+      language: Language::Dutch,
+      seed: "setwinst riphagen vimmetje extase blief tuitelig fuiven meifeest \
+               ponywagen zesmaal ripdeal matverf codetaal leut ivoor rotten \
+               wisgerhof winzucht typograaf atrium rein zilt traktaat verzaagd setwinst"
+        .into(),
+      spend: "e2d2873085c447c2bc7664222ac8f7d240df3aeac137f5ff2022eaa629e5b10a".into(),
+      view: "eac30b69477e3f68093d131c7fd961564458401b07f8c87ff8f6030c1a0c7301".into(),
+    },
+    Vector {
+      language: Language::French,
+      seed: "poids vaseux tarte bazar poivre effet entier nuance \
+               sensuel ennui pacte osselet poudre battre alibi mouton \
+               stade paquet pliage gibier type question position projet pliage"
+        .into(),
+      spend: "2dd39ff1a4628a94b5c2ec3e42fb3dfe15c2b2f010154dc3b3de6791e805b904".into(),
+      view: "6725b32230400a1032f31d622b44c3a227f88258939b14a7c72e00939e7bdf0e".into(),
+    },
+    Vector {
+      language: Language::Spanish,
+      seed: "minero ocupar mirar evadir octubre cal logro miope \
+               opaco disco ancla litio clase cuello nasal clase \
+               fiar avance deseo mente grumo negro cordón croqueta clase"
+        .into(),
+      spend: "ae2c9bebdddac067d73ec0180147fc92bdf9ac7337f1bcafbbe57dd13558eb02".into(),
+      view: "18deafb34d55b7a43cae2c1c1c206a3c80c12cc9d1f84640b484b95b7fec3e05".into(),
+    },
+    Vector {
+      language: Language::German,
+      seed: "Kaliber Gabelung Tapir Liveband Favorit Specht Enklave Nabel \
+               Jupiter Foliant Chronik nisten löten Vase Aussage Rekord \
+               Yeti Gesetz Eleganz Alraune Künstler Almweide Jahr Kastanie Almweide"
+        .into(),
+      spend: "79801b7a1b9796856e2397d862a113862e1fdc289a205e79d8d70995b276db06".into(),
+      view: "99f0ec556643bd9c038a4ed86edcb9c6c16032c4622ed2e000299d527a792701".into(),
+    },
+    Vector {
+      language: Language::Italian,
+      seed: "cavo pancetta auto fulmine alleanza filmato diavolo prato \
+               forzare meritare litigare lezione segreto evasione votare buio \
+               licenza cliente dorso natale crescere vento tutelare vetta evasione"
+        .into(),
+      spend: "5e7fd774eb00fa5877e2a8b4dc9c7ffe111008a3891220b56a6e49ac816d650a".into(),
+      view: "698a1dce6018aef5516e82ca0cb3e3ec7778d17dfb41a137567bfa2e55e63a03".into(),
+    },
+    Vector {
+      language: Language::Portuguese,
+      seed: "agito eventualidade onus itrio holograma sodomizar objetos dobro \
+               iugoslavo bcrepuscular odalisca abjeto iuane darwinista eczema acetona \
+               cibernetico hoquei gleba driver buffer azoto megera nogueira agito"
+        .into(),
+      spend: "13b3115f37e35c6aa1db97428b897e584698670c1b27854568d678e729200c0f".into(),
+      view: "ad1b4fd35270f5f36c4da7166672b347e75c3f4d41346ec2a06d1d0193632801".into(),
+    },
+    Vector {
+      language: Language::Japanese,
+      seed: "ぜんぶ どうぐ おたがい せんきょ おうじ そんちょう じゅしん いろえんぴつ \
+               かほう つかれる えらぶ にちじょう くのう にちようび ぬまえび さんきゃく \
+               おおや ちぬき うすめる いがく せつでん さうな すいえい せつだん おおや"
+        .into(),
+      spend: "c56e895cdb13007eda8399222974cdbab493640663804b93cbef3d8c3df80b0b".into(),
+      view: "6c3634a313ec2ee979d565c33888fd7c3502d696ce0134a8bc1a2698c7f2c508".into(),
+    },
+    Vector {
+      language: Language::Russian,
+      seed: "шатер икра нация ехать получать инерция доза реальный \
+               рыжий таможня лопата душа веселый клетка атлас лекция \
+               обгонять паек наивный лыжный дурак стать ежик задача паек"
+        .into(),
+      spend: "7cb5492df5eb2db4c84af20766391cd3e3662ab1a241c70fc881f3d02c381f05".into(),
+      view: "fcd53e41ec0df995ab43927f7c44bc3359c93523d5009fb3f5ba87431d545a03".into(),
+    },
+    Vector {
+      language: Language::Esperanto,
+      seed: "ukazo klini peco etikedo fabriko imitado onklino urino \
+               pudro incidento kumuluso ikono smirgi hirundo uretro krii \
+               sparkado super speciala pupo alpinisto cvana vokegi zombio fabriko"
+        .into(),
+      spend: "82ebf0336d3b152701964ed41df6b6e9a035e57fc98b84039ed0bd4611c58904".into(),
+      view: "cd4d120e1ea34360af528f6a3e6156063312d9cefc9aa6b5218d366c0ed6a201".into(),
+    },
+    Vector {
+      language: Language::Lojban,
+      seed: "jetnu vensa julne xrotu xamsi julne cutci dakli \
+               mlatu xedja muvgau palpi xindo sfubu ciste cinri \
+               blabi darno dembi janli blabi fenki bukpu burcu blabi"
+        .into(),
+      spend: "e4f8c6819ab6cf792cebb858caabac9307fd646901d72123e0367ebc0a79c200".into(),
+      view: "c806ce62bafaa7b2d597f1a1e2dbe4a2f96bfd804bf6f8420fc7f4a6bd700c00".into(),
+    },
+    Vector {
+      language: Language::EnglishOld,
+      seed: "glorious especially puff son moment add youth nowhere \
+               throw glide grip wrong rhythm consume very swear \
+               bitter heavy eventually begin reason flirt type unable"
+        .into(),
+      spend: "647f4765b66b636ff07170ab6280a9a6804dfbaf19db2ad37d23be024a18730b".into(),
+      view: "045da65316a906a8c30046053119c18020b07a7a3a6ef5c01ab2a8755416bd02".into(),
+    },
+  ];
+
+  for vector in vectors {
+    let trim_seed = |seed: &str| {
+      seed
+        .split_whitespace()
+        .map(|word| trim_by_lang(word, vector.language))
+        .collect::<Vec<_>>()
+        .join(" ")
+    };
+
+    // Test against Monero
+    {
+      let seed = Seed::from_string(Zeroizing::new(vector.seed.clone())).unwrap();
+      assert_eq!(seed, Seed::from_string(Zeroizing::new(trim_seed(&vector.seed))).unwrap());
+
+      let spend: [u8; 32] = hex::decode(vector.spend).unwrap().try_into().unwrap();
+      // For classical seeds, Monero directly uses the entropy as a spend key
+      assert_eq!(
+        Scalar::from_canonical_bytes(*seed.entropy()),
+        Scalar::from_canonical_bytes(spend)
+      );
+
+      let view: [u8; 32] = hex::decode(vector.view).unwrap().try_into().unwrap();
+      // Monero then derives the view key as H(spend)
+      assert_eq!(
+        Scalar::from_bytes_mod_order(hash(&spend)),
+        Scalar::from_canonical_bytes(view).unwrap()
+      );
+
+      assert_eq!(Seed::from_entropy(vector.language, Zeroizing::new(spend)).unwrap(), seed);
+    }
+
+    // Test against ourself
+    {
+      let seed = Seed::new(&mut OsRng, vector.language);
+      assert_eq!(seed, Seed::from_string(Zeroizing::new(trim_seed(&seed.to_string()))).unwrap());
+      assert_eq!(seed, Seed::from_entropy(vector.language, seed.entropy()).unwrap());
+      assert_eq!(seed, Seed::from_string(seed.to_string()).unwrap());
+    }
+  }
+}

coins/monero/src/wallet/mod.rs

@@ -14,6 +14,9 @@ use crate::{hash, hash_to_scalar, serialize::write_varint, transaction::Input};
 pub mod extra;
 pub(crate) use extra::{PaymentId, ExtraField, Extra};
 
+/// Seed creation and parsing functionality.
+pub mod seed;
+
 /// Address encoding and decoding functionality.
 pub mod address;
 use address::{Network, AddressType, SubaddressIndex, AddressSpec, AddressMeta, MoneroAddress};

coins/monero/src/wallet/seed/classic.rs

@@ -0,0 +1,262 @@
+use core::ops::Deref;
+use std::collections::HashMap;
+
+use lazy_static::lazy_static;
+
+use zeroize::{Zeroize, Zeroizing};
+use rand_core::{RngCore, CryptoRng};
+
+use crc::{Crc, CRC_32_ISO_HDLC};
+
+use curve25519_dalek::scalar::Scalar;
+
+use crate::{
+  random_scalar,
+  wallet::seed::{SeedError, Language},
+};
+
+pub(crate) const CLASSIC_SEED_LENGTH: usize = 24;
+pub(crate) const CLASSIC_SEED_LENGTH_WITH_CHECKSUM: usize = 25;
+
+fn trim(word: &str, len: usize) -> Zeroizing<String> {
+  Zeroizing::new(word.chars().take(len).collect())
+}
+
+struct WordList {
+  word_list: Vec<String>,
+  word_map: HashMap<String, usize>,
+  trimmed_word_map: HashMap<String, usize>,
+  unique_prefix_length: usize,
+}
+
+impl WordList {
+  fn new(words: &'static str, prefix_length: usize) -> WordList {
+    let mut lang = WordList {
+      word_list: serde_json::from_str(words).unwrap(),
+      word_map: HashMap::new(),
+      trimmed_word_map: HashMap::new(),
+      unique_prefix_length: prefix_length,
+    };
+
+    for (i, word) in lang.word_list.iter().enumerate() {
+      lang.word_map.insert(word.clone(), i);
+      lang.trimmed_word_map.insert(trim(word, lang.unique_prefix_length).deref().clone(), i);
+    }
+
+    lang
+  }
+}
+
+lazy_static! {
+  static ref LANGUAGES: HashMap<Language, WordList> = HashMap::from([
+    (Language::Chinese, WordList::new(include_str!("./classic/zh.json"), 1)),
+    (Language::English, WordList::new(include_str!("./classic/en.json"), 3)),
+    (Language::Dutch, WordList::new(include_str!("./classic/nl.json"), 4)),
+    (Language::French, WordList::new(include_str!("./classic/fr.json"), 4)),
+    (Language::Spanish, WordList::new(include_str!("./classic/es.json"), 4)),
+    (Language::German, WordList::new(include_str!("./classic/de.json"), 4)),
+    (Language::Italian, WordList::new(include_str!("./classic/it.json"), 4)),
+    (Language::Portuguese, WordList::new(include_str!("./classic/pt.json"), 4)),
+    (Language::Japanese, WordList::new(include_str!("./classic/ja.json"), 3)),
+    (Language::Russian, WordList::new(include_str!("./classic/ru.json"), 4)),
+    (Language::Esperanto, WordList::new(include_str!("./classic/eo.json"), 4)),
+    (Language::Lojban, WordList::new(include_str!("./classic/jbo.json"), 4)),
+    (Language::EnglishOld, WordList::new(include_str!("./classic/ang.json"), 4)),
+  ]);
+}
+
+#[cfg(test)]
+pub(crate) fn trim_by_lang(word: &str, lang: Language) -> String {
+  if lang != Language::EnglishOld {
+    word.chars().take(LANGUAGES[&lang].unique_prefix_length).collect()
+  } else {
+    word.to_string()
+  }
+}
+
+fn checksum_index(words: &[Zeroizing<String>], lang: &WordList) -> usize {
+  let mut trimmed_words = Zeroizing::new(String::new());
+  for w in words {
+    *trimmed_words += &trim(w, lang.unique_prefix_length);
+  }
+
+  let crc = Crc::<u32>::new(&CRC_32_ISO_HDLC);
+  let mut digest = crc.digest();
+  digest.update(trimmed_words.as_bytes());
+
+  usize::try_from(digest.finalize()).unwrap() % words.len()
+}
+
+// Convert a private key to a seed
+fn key_to_seed(lang: Language, key: Zeroizing<Scalar>) -> ClassicSeed {
+  let bytes = Zeroizing::new(key.to_bytes());
+
+  // get the language words
+  let words = &LANGUAGES[&lang].word_list;
+  let list_len = u64::try_from(words.len()).unwrap();
+
+  // To store the found words & add the checksum word later.
+  let mut seed = Vec::with_capacity(25);
+
+  // convert to words
+  // 4 bytes -> 3 words. 8 digits base 16 -> 3 digits base 1626
+  let mut segment = [0; 4];
+  let mut indices = [0; 4];
+  for i in 0 .. 8 {
+    // convert first 4 byte to u32 & get the word indices
+    let start = i * 4;
+    // convert 4 byte to u32
+    segment.copy_from_slice(&bytes[start .. (start + 4)]);
+    // Actually convert to a u64 so we can add without overflowing
+    indices[0] = u64::from(u32::from_le_bytes(segment));
+    indices[1] = indices[0];
+    indices[0] /= list_len;
+    indices[2] = indices[0] + indices[1];
+    indices[0] /= list_len;
+    indices[3] = indices[0] + indices[2];
+
+    // append words to seed
+    for i in indices.iter().skip(1) {
+      let word = usize::try_from(i % list_len).unwrap();
+      seed.push(Zeroizing::new(words[word].clone()));
+    }
+  }
+  segment.zeroize();
+  indices.zeroize();
+
+  // create a checksum word for all languages except old english
+  if lang != Language::EnglishOld {
+    let checksum = seed[checksum_index(&seed, &LANGUAGES[&lang])].clone();
+    seed.push(checksum);
+  }
+
+  let mut res = Zeroizing::new(String::new());
+  for (i, word) in seed.iter().enumerate() {
+    if i != 0 {
+      *res += " ";
+    }
+    *res += word;
+  }
+  ClassicSeed(res)
+}
+
+// Convert a seed to bytes
+pub(crate) fn seed_to_bytes(words: &str) -> Result<(Language, Zeroizing<[u8; 32]>), SeedError> {
+  // get seed words
+  let words = words.split_whitespace().map(|w| Zeroizing::new(w.to_string())).collect::<Vec<_>>();
+  if (words.len() != CLASSIC_SEED_LENGTH) && (words.len() != CLASSIC_SEED_LENGTH_WITH_CHECKSUM) {
+    panic!("invalid seed passed to seed_to_bytes");
+  }
+
+  // find the language
+  let (matched_indices, lang_name, lang) = (|| {
+    let has_checksum = words.len() == CLASSIC_SEED_LENGTH_WITH_CHECKSUM;
+    let mut matched_indices = Zeroizing::new(vec![]);
+
+    // Iterate through all the languages
+    'language: for (lang_name, lang) in LANGUAGES.iter() {
+      matched_indices.zeroize();
+      matched_indices.clear();
+
+      let map_in_use = if has_checksum { &lang.trimmed_word_map } else { &lang.word_map };
+
+      // Iterate through all the words and see if they're all present
+      for word in &words {
+        let trimmed = trim(word, lang.unique_prefix_length);
+        let word = if has_checksum { &trimmed } else { word };
+
+        if let Some(index) = map_in_use.get(word.deref()) {
+          matched_indices.push(*index);
+        } else {
+          continue 'language;
+        }
+      }
+
+      if has_checksum {
+        if lang_name == &Language::EnglishOld {
+          Err(SeedError::EnglishOldWithChecksum)?;
+        }
+
+        // exclude the last word when calculating a checksum.
+        let last_word = words.last().unwrap().clone();
+        let checksum = words[checksum_index(&words[.. words.len() - 1], lang)].clone();
+
+        // check the trimmed checksum and trimmed last word line up
+        if trim(&checksum, lang.unique_prefix_length) != trim(&last_word, lang.unique_prefix_length)
+        {
+          Err(SeedError::InvalidChecksum)?;
+        }
+      }
+
+      return Ok((matched_indices, lang_name, lang));
+    }
+
+    Err(SeedError::UnknownLanguage)?
+  })()?;
+
+  // convert to bytes
+  let mut res = Zeroizing::new([0; 32]);
+  let mut indices = Zeroizing::new([0; 4]);
+  for i in 0 .. 8 {
+    // read 3 indices at a time
+    let i3 = i * 3;
+    indices[1] = matched_indices[i3];
+    indices[2] = matched_indices[i3 + 1];
+    indices[3] = matched_indices[i3 + 2];
+
+    let inner = |i| {
+      let mut base = (lang.word_list.len() - indices[i] + indices[i + 1]) % lang.word_list.len();
+      // Shift the index over
+      for _ in 0 .. i {
+        base *= lang.word_list.len();
+      }
+      base
+    };
+    // set the last index
+    indices[0] = indices[1] + inner(1) + inner(2);
+    if (indices[0] % lang.word_list.len()) != indices[1] {
+      Err(SeedError::InvalidSeed)?;
+    }
+
+    let pos = i * 4;
+    let mut bytes = u32::try_from(indices[0]).unwrap().to_le_bytes();
+    res[pos .. (pos + 4)].copy_from_slice(&bytes);
+    bytes.zeroize();
+  }
+
+  Ok((*lang_name, res))
+}
+
+#[derive(Clone, PartialEq, Eq, Zeroize)]
+pub struct ClassicSeed(Zeroizing<String>);
+impl ClassicSeed {
+  pub(crate) fn new<R: RngCore + CryptoRng>(rng: &mut R, lang: Language) -> ClassicSeed {
+    key_to_seed(lang, Zeroizing::new(random_scalar(rng)))
+  }
+
+  pub fn from_string(words: Zeroizing<String>) -> Result<ClassicSeed, SeedError> {
+    let (lang, entropy) = seed_to_bytes(&words)?;
+
+    // Make sure this is a valid scalar
+    let mut scalar = Scalar::from_canonical_bytes(*entropy);
+    if scalar.is_none() {
+      Err(SeedError::InvalidSeed)?;
+    }
+    scalar.zeroize();
+
+    // Call from_entropy so a trimmed seed becomes a full seed
+    Ok(Self::from_entropy(lang, entropy).unwrap())
+  }
+
+  pub fn from_entropy(lang: Language, entropy: Zeroizing<[u8; 32]>) -> Option<ClassicSeed> {
+    Scalar::from_canonical_bytes(*entropy).map(|scalar| key_to_seed(lang, Zeroizing::new(scalar)))
+  }
+
+  pub(crate) fn to_string(&self) -> Zeroizing<String> {
+    self.0.clone()
+  }
+
+  pub(crate) fn entropy(&self) -> Zeroizing<[u8; 32]> {
+    seed_to_bytes(&self.0).unwrap().1
+  }
+}

coins/monero/src/wallet/seed/mod.rs

@@ -0,0 +1,92 @@
+use core::fmt;
+
+use zeroize::{Zeroize, ZeroizeOnDrop, Zeroizing};
+use rand_core::{RngCore, CryptoRng};
+
+use thiserror::Error;
+
+pub(crate) mod classic;
+use classic::{CLASSIC_SEED_LENGTH, CLASSIC_SEED_LENGTH_WITH_CHECKSUM, ClassicSeed};
+
+/// Error when decoding a seed.
+#[derive(Clone, Copy, PartialEq, Eq, Debug, Error)]
+pub enum SeedError {
+  #[error("invalid number of words in seed")]
+  InvalidSeedLength,
+  #[error("unknown language")]
+  UnknownLanguage,
+  #[error("invalid checksum")]
+  InvalidChecksum,
+  #[error("english old seeds don't support checksums")]
+  EnglishOldWithChecksum,
+  #[error("invalid seed")]
+  InvalidSeed,
+}
+
+#[derive(Clone, Copy, PartialEq, Eq, Debug, Hash)]
+pub enum Language {
+  Chinese,
+  English,
+  Dutch,
+  French,
+  Spanish,
+  German,
+  Italian,
+  Portuguese,
+  Japanese,
+  Russian,
+  Esperanto,
+  Lojban,
+  EnglishOld,
+}
+
+/// A Monero seed.
+// TODO: Add polyseed to enum
+#[derive(Clone, PartialEq, Eq, Zeroize, ZeroizeOnDrop)]
+pub enum Seed {
+  Classic(ClassicSeed),
+}
+
+impl fmt::Debug for Seed {
+  fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+    match self {
+      Seed::Classic(_) => f.debug_struct("Seed::Classic").finish_non_exhaustive(),
+    }
+  }
+}
+
+impl Seed {
+  /// Create a new seed.
+  pub fn new<R: RngCore + CryptoRng>(rng: &mut R, lang: Language) -> Seed {
+    Seed::Classic(ClassicSeed::new(rng, lang))
+  }
+
+  /// Parse a seed from a String.
+  pub fn from_string(words: Zeroizing<String>) -> Result<Seed, SeedError> {
+    match words.split_whitespace().count() {
+      CLASSIC_SEED_LENGTH | CLASSIC_SEED_LENGTH_WITH_CHECKSUM => {
+        ClassicSeed::from_string(words).map(Seed::Classic)
+      }
+      _ => Err(SeedError::InvalidSeedLength)?,
+    }
+  }
+
+  /// Create a Seed from entropy.
+  pub fn from_entropy(lang: Language, entropy: Zeroizing<[u8; 32]>) -> Option<Seed> {
+    ClassicSeed::from_entropy(lang, entropy).map(Seed::Classic)
+  }
+
+  /// Convert a seed to a String.
+  pub fn to_string(&self) -> Zeroizing<String> {
+    match self {
+      Seed::Classic(seed) => seed.to_string(),
+    }
+  }
+
+  /// Return the entropy for this seed.
+  pub fn entropy(&self) -> Zeroizing<[u8; 32]> {
+    match self {
+      Seed::Classic(seed) => seed.entropy(),
+    }
+  }
+}