iota_keys/
key_derive.rs

1// Copyright (c) Mysten Labs, Inc.
2// Modifications Copyright (c) 2024 IOTA Stiftung
3// SPDX-License-Identifier: Apache-2.0
4
5use anyhow::anyhow;
6use bip32::{ChildNumber, DerivationPath, XPrv};
7use bip39::{Language, Mnemonic, MnemonicType, Seed};
8use fastcrypto::{
9    ed25519::{Ed25519KeyPair, Ed25519PrivateKey},
10    secp256k1::{Secp256k1KeyPair, Secp256k1PrivateKey},
11    secp256r1::{Secp256r1KeyPair, Secp256r1PrivateKey},
12    traits::{KeyPair, ToFromBytes},
13};
14use iota_types::{
15    base_types::IotaAddress,
16    crypto::{IotaKeyPair, SignatureScheme},
17    error::IotaError,
18};
19use slip10_ed25519::derive_ed25519_private_key;
20
21pub const DERIVATION_PATH_COIN_TYPE: u32 = 4218;
22pub const DERVIATION_PATH_PURPOSE_ED25519: u32 = 44;
23pub const DERVIATION_PATH_PURPOSE_SECP256K1: u32 = 54;
24pub const DERVIATION_PATH_PURPOSE_SECP256R1: u32 = 74;
25
26/// Ed25519 follows SLIP-0010 using hardened path: m/44'/4218'/0'/0'/{index}'
27/// Secp256k1 follows BIP-32/44 using path where the first 3 levels are
28/// hardened: m/54'/4218'/0'/0/{index} Secp256r1 follows BIP-32/44 using path
29/// where the first 3 levels are hardened: m/74'/4218'/0'/0/{index}.
30/// Note that the purpose node is used to distinguish signature schemes.
31pub fn derive_key_pair_from_path(
32    seed: &[u8],
33    derivation_path: Option<DerivationPath>,
34    key_scheme: &SignatureScheme,
35) -> Result<(IotaAddress, IotaKeyPair), IotaError> {
36    let path = validate_path(key_scheme, derivation_path)?;
37    match key_scheme {
38        SignatureScheme::ED25519 => {
39            let indexes = path.into_iter().map(|i| i.into()).collect::<Vec<_>>();
40            let derived = derive_ed25519_private_key(seed, &indexes);
41            let sk = Ed25519PrivateKey::from_bytes(&derived)
42                .map_err(|e| IotaError::SignatureKeyGen(e.to_string()))?;
43            let kp: Ed25519KeyPair = sk.into();
44            Ok((kp.public().into(), IotaKeyPair::Ed25519(kp)))
45        }
46        SignatureScheme::Secp256k1 => {
47            let child_xprv = XPrv::derive_from_path(seed, &path)
48                .map_err(|e| IotaError::SignatureKeyGen(e.to_string()))?;
49            let kp = Secp256k1KeyPair::from(
50                Secp256k1PrivateKey::from_bytes(child_xprv.private_key().to_bytes().as_slice())
51                    .map_err(|e| IotaError::SignatureKeyGen(e.to_string()))?,
52            );
53            Ok((kp.public().into(), IotaKeyPair::Secp256k1(kp)))
54        }
55        SignatureScheme::Secp256r1 => {
56            let child_xprv = XPrv::derive_from_path(seed, &path)
57                .map_err(|e| IotaError::SignatureKeyGen(e.to_string()))?;
58            let kp = Secp256r1KeyPair::from(
59                Secp256r1PrivateKey::from_bytes(child_xprv.private_key().to_bytes().as_slice())
60                    .map_err(|e| IotaError::SignatureKeyGen(e.to_string()))?,
61            );
62            Ok((kp.public().into(), IotaKeyPair::Secp256r1(kp)))
63        }
64        SignatureScheme::BLS12381
65        | SignatureScheme::MultiSig
66        | SignatureScheme::ZkLoginAuthenticator
67        | SignatureScheme::PasskeyAuthenticator => Err(IotaError::UnsupportedFeature {
68            error: format!("key derivation not supported {:?}", key_scheme),
69        }),
70    }
71}
72
73pub fn validate_path(
74    key_scheme: &SignatureScheme,
75    path: Option<DerivationPath>,
76) -> Result<DerivationPath, IotaError> {
77    match key_scheme {
78        SignatureScheme::ED25519 => {
79            match path {
80                Some(p) => {
81                    // The derivation path must be hardened at all levels with purpose = 44,
82                    // coin_type = 4218
83                    if let &[purpose, coin_type, account, change, address] = p.as_ref() {
84                        if Some(purpose)
85                            == ChildNumber::new(DERVIATION_PATH_PURPOSE_ED25519, true).ok()
86                            && (Some(coin_type)
87                                == ChildNumber::new(DERIVATION_PATH_COIN_TYPE, true).ok())
88                            && account.is_hardened()
89                            && change.is_hardened()
90                            && address.is_hardened()
91                        {
92                            Ok(p)
93                        } else {
94                            Err(IotaError::SignatureKeyGen("Invalid path".to_string()))
95                        }
96                    } else {
97                        Err(IotaError::SignatureKeyGen("Invalid path".to_string()))
98                    }
99                }
100                None => Ok(format!(
101                    "m/{DERVIATION_PATH_PURPOSE_ED25519}'/{DERIVATION_PATH_COIN_TYPE}'/0'/0'/0'"
102                )
103                .parse()
104                .map_err(|_| IotaError::SignatureKeyGen("Cannot parse path".to_string()))?),
105            }
106        }
107        SignatureScheme::Secp256k1 => {
108            match path {
109                Some(p) => {
110                    // The derivation path must be hardened at first 3 levels with purpose = 54,
111                    // coin_type = 4218
112                    if let &[purpose, coin_type, account, change, address] = p.as_ref() {
113                        if Some(purpose)
114                            == ChildNumber::new(DERVIATION_PATH_PURPOSE_SECP256K1, true).ok()
115                            && Some(coin_type)
116                                == ChildNumber::new(DERIVATION_PATH_COIN_TYPE, true).ok()
117                            && account.is_hardened()
118                            && !change.is_hardened()
119                            && !address.is_hardened()
120                        {
121                            Ok(p)
122                        } else {
123                            Err(IotaError::SignatureKeyGen("Invalid path".to_string()))
124                        }
125                    } else {
126                        Err(IotaError::SignatureKeyGen("Invalid path".to_string()))
127                    }
128                }
129                None => Ok(format!(
130                    "m/{DERVIATION_PATH_PURPOSE_SECP256K1}'/{DERIVATION_PATH_COIN_TYPE}'/0'/0/0"
131                )
132                .parse()
133                .map_err(|_| IotaError::SignatureKeyGen("Cannot parse path".to_string()))?),
134            }
135        }
136        SignatureScheme::Secp256r1 => {
137            match path {
138                Some(p) => {
139                    // The derivation path must be hardened at first 3 levels with purpose = 74,
140                    // coin_type = 4218
141                    if let &[purpose, coin_type, account, change, address] = p.as_ref() {
142                        if Some(purpose)
143                            == ChildNumber::new(DERVIATION_PATH_PURPOSE_SECP256R1, true).ok()
144                            && Some(coin_type)
145                                == ChildNumber::new(DERIVATION_PATH_COIN_TYPE, true).ok()
146                            && account.is_hardened()
147                            && !change.is_hardened()
148                            && !address.is_hardened()
149                        {
150                            Ok(p)
151                        } else {
152                            Err(IotaError::SignatureKeyGen("Invalid path".to_string()))
153                        }
154                    } else {
155                        Err(IotaError::SignatureKeyGen("Invalid path".to_string()))
156                    }
157                }
158                None => Ok(format!(
159                    "m/{DERVIATION_PATH_PURPOSE_SECP256R1}'/{DERIVATION_PATH_COIN_TYPE}'/0'/0/0"
160                )
161                .parse()
162                .map_err(|_| IotaError::SignatureKeyGen("Cannot parse path".to_string()))?),
163            }
164        }
165        SignatureScheme::BLS12381
166        | SignatureScheme::MultiSig
167        | SignatureScheme::ZkLoginAuthenticator
168        | SignatureScheme::PasskeyAuthenticator => Err(IotaError::UnsupportedFeature {
169            error: format!("key derivation not supported {:?}", key_scheme),
170        }),
171    }
172}
173
174pub fn generate_new_key(
175    key_scheme: SignatureScheme,
176    derivation_path: Option<DerivationPath>,
177    word_length: Option<String>,
178) -> Result<(IotaAddress, IotaKeyPair, SignatureScheme, String), anyhow::Error> {
179    let mnemonic = Mnemonic::new(parse_word_length(word_length)?, Language::English);
180    let seed = Seed::new(&mnemonic, "");
181    match derive_key_pair_from_path(seed.as_bytes(), derivation_path, &key_scheme) {
182        Ok((address, kp)) => Ok((address, kp, key_scheme, mnemonic.phrase().to_string())),
183        Err(e) => Err(anyhow!("Failed to generate keypair: {:?}", e)),
184    }
185}
186
187fn parse_word_length(s: Option<String>) -> Result<MnemonicType, anyhow::Error> {
188    match s {
189        None => Ok(MnemonicType::Words12),
190        Some(s) => match s.as_str() {
191            "word12" => Ok(MnemonicType::Words12),
192            "word15" => Ok(MnemonicType::Words15),
193            "word18" => Ok(MnemonicType::Words18),
194            "word21" => Ok(MnemonicType::Words21),
195            "word24" => Ok(MnemonicType::Words24),
196            _ => anyhow::bail!("Invalid word length"),
197        },
198    }
199}