bip39/
seed.rs

1use crate::crypto::pbkdf2;
2use crate::mnemonic::Mnemonic;
3use std::fmt;
4use unicode_normalization::UnicodeNormalization;
5use zeroize::{Zeroize, Zeroizing};
6
7/// The secret value used to derive HD wallet addresses from a [`Mnemonic`][Mnemonic] phrase.
8///
9/// Because it is not possible to create a [`Mnemonic`][Mnemonic] instance that is invalid, it is
10/// therefore impossible to have a [`Seed`][Seed] instance that is invalid. This guarantees that only
11/// a valid, intact mnemonic phrase can be used to derive HD wallet addresses.
12///
13/// To get the raw byte value use [`Seed::as_bytes()`][Seed::as_bytes()]. These can be used to derive
14/// HD wallet addresses using another crate (deriving HD wallet addresses is outside the scope of this
15/// crate and the BIP39 standard).
16///
17/// [`Seed`][Seed] implements [`Zeroize`][Zeroize], so it's bytes will be zeroed when it's dropped.
18///
19/// [Mnemonic]: ./mnemonic/struct.Mnemonic.html
20/// [Seed]: ./seed/struct.Seed.html
21/// [Seed::as_bytes()]: ./seed/struct.Seed.html#method.as_bytes
22
23#[derive(Clone, Zeroize)]
24#[zeroize(drop)]
25pub struct Seed {
26    bytes: Vec<u8>,
27}
28
29impl Seed {
30    /// Generates the seed from the [`Mnemonic`][Mnemonic] and the password.
31    ///
32    /// [Mnemonic]: ./mnemonic/struct.Mnemonic.html
33    pub fn new(mnemonic: &Mnemonic, password: &str) -> Self {
34        let salt = Zeroizing::new(format!("mnemonic{}", password));
35        let normalized_salt = Zeroizing::new(salt.nfkd().to_string());
36        let bytes = pbkdf2(mnemonic.phrase().as_bytes(), &normalized_salt);
37
38        Self { bytes }
39    }
40
41    /// Get the seed value as a byte slice
42    pub fn as_bytes(&self) -> &[u8] {
43        &self.bytes
44    }
45}
46
47impl AsRef<[u8]> for Seed {
48    fn as_ref(&self) -> &[u8] {
49        self.as_bytes()
50    }
51}
52
53impl fmt::Debug for Seed {
54    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
55        write!(f, "{:#X}", self)
56    }
57}
58
59impl fmt::LowerHex for Seed {
60    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
61        if f.alternate() {
62            f.write_str("0x")?;
63        }
64
65        for byte in &self.bytes {
66            write!(f, "{:02x}", byte)?;
67        }
68
69        Ok(())
70    }
71}
72
73impl fmt::UpperHex for Seed {
74    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
75        if f.alternate() {
76            f.write_str("0x")?;
77        }
78
79        for byte in &self.bytes {
80            write!(f, "{:02X}", byte)?;
81        }
82
83        Ok(())
84    }
85}
86
87#[cfg(test)]
88mod test {
89    use super::*;
90    use crate::language::Language;
91    #[cfg(target_arch = "wasm32")]
92    use wasm_bindgen_test::*;
93
94    #[cfg_attr(all(target_arch = "wasm32"), wasm_bindgen_test)]
95    #[cfg_attr(not(target_arch = "wasm32"), test)]
96    fn seed_hex_format() {
97        let entropy = &[
98            0x33, 0xE4, 0x6B, 0xB1, 0x3A, 0x74, 0x6E, 0xA4, 0x1C, 0xDD, 0xE4, 0x5C, 0x90, 0x84,
99            0x6A, 0x79,
100        ];
101
102        let mnemonic = Mnemonic::from_entropy(entropy, Language::English).unwrap();
103        let seed = Seed::new(&mnemonic, "password");
104
105        assert_eq!(format!("{:x}", seed), "0bde96f14c35a66235478e0c16c152fcaf6301e4d9a81d3febc50879fe7e5438e6a8dd3e39bdf3ab7b12d6b44218710e17d7a2844ee9633fab0e03d9a6c8569b");
106        assert_eq!(format!("{:X}", seed), "0BDE96F14C35A66235478E0C16C152FCAF6301E4D9A81D3FEBC50879FE7E5438E6A8DD3E39BDF3AB7B12D6B44218710E17D7A2844EE9633FAB0E03D9A6C8569B");
107        assert_eq!(format!("{:#x}", seed), "0x0bde96f14c35a66235478e0c16c152fcaf6301e4d9a81d3febc50879fe7e5438e6a8dd3e39bdf3ab7b12d6b44218710e17d7a2844ee9633fab0e03d9a6c8569b");
108        assert_eq!(format!("{:#X}", seed), "0x0BDE96F14C35A66235478E0C16C152FCAF6301E4D9A81D3FEBC50879FE7E5438E6A8DD3E39BDF3AB7B12D6B44218710E17D7A2844EE9633FAB0E03D9A6C8569B");
109    }
110
111    fn test_unicode_normalization(
112        lang: Language,
113        phrase: &str,
114        password: &str,
115        expected_seed_hex: &str,
116    ) {
117        let mnemonic = Mnemonic::from_phrase(phrase, lang).unwrap();
118        let seed = Seed::new(&mnemonic, password);
119        assert_eq!(format!("{:x}", seed), expected_seed_hex);
120    }
121
122    #[cfg_attr(all(target_arch = "wasm32"), wasm_bindgen_test)]
123    #[cfg_attr(not(target_arch = "wasm32"), test)]
124    /// Test vector is derived from https://github.com/infincia/bip39-rs/issues/26#issuecomment-586476647
125    #[cfg(feature = "spanish")]
126    fn issue_26() {
127        test_unicode_normalization(
128            Language::Spanish,
129            "camello pomelo toque oponer urgente lástima merengue cutis tirón pudor pomo barco",
130            "el español se habla en muchos países",
131            "67a2cf87b9d110dd5210275fd4d7a107a0a0dd9446e02f3822f177365786ae440b8873693c88f732834af90785753d989a367f7094230901b204c567718ce6be",
132        );
133    }
134
135    #[cfg_attr(all(target_arch = "wasm32"), wasm_bindgen_test)]
136    #[cfg_attr(not(target_arch = "wasm32"), test)]
137    /// https://github.com/MetacoSA/NBitcoin/blob/master/NBitcoin.Tests/data/bip39_vectors.en.json
138    fn password_is_unicode_normalized() {
139        test_unicode_normalization(
140            Language::English,
141            "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
142            "nullius　à　nym.zone ¹teſts² English",
143            "61f3aa13adcf5f4b8661fc062501d67eca3a53fc0ed129076ad7a22983b6b5ed0e84e47b24cff23b7fca57e127f62f28c1584ed487872d4bfbc773257bdbc434",
144        );
145    }
146
147    #[cfg_attr(all(target_arch = "wasm32"), wasm_bindgen_test)]
148    #[cfg_attr(not(target_arch = "wasm32"), test)]
149    /// https://github.com/bip32JP/bip32JP.github.io/commit/360c05a6439e5c461bbe5e84c7567ec38eb4ac5f
150    #[cfg(feature = "japanese")]
151    fn japanese_normalization_1() {
152        test_unicode_normalization(
153            Language::Japanese,
154            "あいこくしん　あいこくしん　あいこくしん　あいこくしん　あいこくしん　あいこくしん　あいこくしん　あいこくしん　あいこくしん　あいこくしん　あいこくしん　あおぞら",
155            "㍍ガバヴァぱばぐゞちぢ十人十色",
156            "a262d6fb6122ecf45be09c50492b31f92e9beb7d9a845987a02cefda57a15f9c467a17872029a9e92299b5cbdf306e3a0ee620245cbd508959b6cb7ca637bd55",
157        );
158    }
159
160    #[cfg_attr(all(target_arch = "wasm32"), wasm_bindgen_test)]
161    #[cfg_attr(not(target_arch = "wasm32"), test)]
162    #[cfg(feature = "japanese")]
163    fn japanese_normalization_2() {
164        test_unicode_normalization(
165            Language::Japanese,
166            "うちゅう　ふそく　ひしょ　がちょう　うけもつ　めいそう　みかん　そざい　いばる　うけとる　さんま　さこつ　おうさま　ぱんつ　しひょう　めした　たはつ　いちぶ　つうじょう　てさぎょう　きつね　みすえる　いりぐち　かめれおん",
167            "㍍ガバヴァぱばぐゞちぢ十人十色",
168            "346b7321d8c04f6f37b49fdf062a2fddc8e1bf8f1d33171b65074531ec546d1d3469974beccb1a09263440fc92e1042580a557fdce314e27ee4eabb25fa5e5fe",
169        );
170    }
171
172    #[cfg_attr(all(target_arch = "wasm32"), wasm_bindgen_test)]
173    #[cfg_attr(not(target_arch = "wasm32"), test)]
174    #[cfg(feature = "french")]
175    fn french_normalization() {
176        test_unicode_normalization(
177            Language::French,
178            "paternel xénon curatif séparer docile capable exigence boulon styliste plexus surface embryon crayon gorge exister",
179            "nullius　à　nym.zone ¹teſts² Français",
180            "cff9ffd2b23549e73601db4129a334c81b28a40f0ee819b5d6a54c409999f0dfb6b89df17cae6408c96786165c205403d283baadc03ffdd391a490923b7d9493",
181        );
182    }
183}
bip39/seed.rs

bip39/
seed.rs
