sp_core/
ed25519.rs

1// This file is part of Substrate.
2
3// Copyright (C) Parity Technologies (UK) Ltd.
4// SPDX-License-Identifier: Apache-2.0
5
6// Licensed under the Apache License, Version 2.0 (the "License");
7// you may not use this file except in compliance with the License.
8// You may obtain a copy of the License at
9//
10// 	http://www.apache.org/licenses/LICENSE-2.0
11//
12// Unless required by applicable law or agreed to in writing, software
13// distributed under the License is distributed on an "AS IS" BASIS,
14// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15// See the License for the specific language governing permissions and
16// limitations under the License.
17
18//! Simple Ed25519 API.
19
20use crate::crypto::{
21	ByteArray, CryptoType, CryptoTypeId, DeriveError, DeriveJunction, Pair as TraitPair,
22	PublicBytes, SecretStringError, SignatureBytes,
23};
24
25use ed25519_zebra::{SigningKey, VerificationKey};
26
27use alloc::vec::Vec;
28
29/// An identifier used to match public keys against ed25519 keys
30pub const CRYPTO_ID: CryptoTypeId = CryptoTypeId(*b"ed25");
31
32/// The byte length of public key
33pub const PUBLIC_KEY_SERIALIZED_SIZE: usize = 32;
34
35/// The byte length of signature
36pub const SIGNATURE_SERIALIZED_SIZE: usize = 64;
37
38/// A secret seed. It's not called a "secret key" because ring doesn't expose the secret keys
39/// of the key pair (yeah, dumb); as such we're forced to remember the seed manually if we
40/// will need it later (such as for HDKD).
41type Seed = [u8; 32];
42
43#[doc(hidden)]
44pub struct Ed25519Tag;
45
46/// A public key.
47pub type Public = PublicBytes<PUBLIC_KEY_SERIALIZED_SIZE, Ed25519Tag>;
48
49/// A signature.
50pub type Signature = SignatureBytes<SIGNATURE_SERIALIZED_SIZE, Ed25519Tag>;
51
52/// A key pair.
53#[derive(Copy, Clone)]
54pub struct Pair {
55	public: VerificationKey,
56	secret: SigningKey,
57}
58
59/// Derive a single hard junction.
60fn derive_hard_junction(secret_seed: &Seed, cc: &[u8; 32]) -> Seed {
61	use codec::Encode;
62	("Ed25519HDKD", secret_seed, cc).using_encoded(sp_crypto_hashing::blake2_256)
63}
64
65impl TraitPair for Pair {
66	type Public = Public;
67	type Seed = Seed;
68	type Signature = Signature;
69
70	/// Make a new key pair from secret seed material. The slice must be 32 bytes long or it
71	/// will return `None`.
72	///
73	/// You should never need to use this; generate(), generate_with_phrase
74	fn from_seed_slice(seed_slice: &[u8]) -> Result<Pair, SecretStringError> {
75		let secret =
76			SigningKey::try_from(seed_slice).map_err(|_| SecretStringError::InvalidSeedLength)?;
77		let public = VerificationKey::from(&secret);
78		Ok(Pair { secret, public })
79	}
80
81	/// Derive a child key from a series of given junctions.
82	fn derive<Iter: Iterator<Item = DeriveJunction>>(
83		&self,
84		path: Iter,
85		_seed: Option<Seed>,
86	) -> Result<(Pair, Option<Seed>), DeriveError> {
87		let mut acc = self.secret.into();
88		for j in path {
89			match j {
90				DeriveJunction::Soft(_cc) => return Err(DeriveError::SoftKeyInPath),
91				DeriveJunction::Hard(cc) => acc = derive_hard_junction(&acc, &cc),
92			}
93		}
94		Ok((Self::from_seed(&acc), Some(acc)))
95	}
96
97	/// Get the public key.
98	fn public(&self) -> Public {
99		Public::from_raw(self.public.into())
100	}
101
102	/// Sign a message.
103	#[cfg(feature = "full_crypto")]
104	fn sign(&self, message: &[u8]) -> Signature {
105		Signature::from_raw(self.secret.sign(message).into())
106	}
107
108	/// Verify a signature on a message.
109	///
110	/// Returns true if the signature is good.
111	fn verify<M: AsRef<[u8]>>(sig: &Signature, message: M, public: &Public) -> bool {
112		let Ok(public) = VerificationKey::try_from(public.as_slice()) else { return false };
113		let Ok(signature) = ed25519_zebra::Signature::try_from(sig.as_slice()) else {
114			return false
115		};
116		public.verify(&signature, message.as_ref()).is_ok()
117	}
118
119	/// Return a vec filled with raw data.
120	fn to_raw_vec(&self) -> Vec<u8> {
121		self.seed().to_vec()
122	}
123}
124
125impl Pair {
126	/// Get the seed for this key.
127	pub fn seed(&self) -> Seed {
128		self.secret.into()
129	}
130
131	/// Exactly as `from_string` except that if no matches are found then, the the first 32
132	/// characters are taken (padded with spaces as necessary) and used as the MiniSecretKey.
133	#[cfg(feature = "std")]
134	pub fn from_legacy_string(s: &str, password_override: Option<&str>) -> Pair {
135		Self::from_string(s, password_override).unwrap_or_else(|_| {
136			let mut padded_seed: Seed = [b' '; 32];
137			let len = s.len().min(32);
138			padded_seed[..len].copy_from_slice(&s.as_bytes()[..len]);
139			Self::from_seed(&padded_seed)
140		})
141	}
142}
143
144impl CryptoType for Public {
145	type Pair = Pair;
146}
147
148impl CryptoType for Signature {
149	type Pair = Pair;
150}
151
152impl CryptoType for Pair {
153	type Pair = Pair;
154}
155
156#[cfg(test)]
157mod tests {
158	use super::*;
159	#[cfg(feature = "serde")]
160	use crate::crypto::Ss58Codec;
161	use crate::crypto::DEV_PHRASE;
162	use serde_json;
163
164	#[test]
165	fn default_phrase_should_be_used() {
166		assert_eq!(
167			Pair::from_string("//Alice///password", None).unwrap().public(),
168			Pair::from_string(&format!("{}//Alice", DEV_PHRASE), Some("password"))
169				.unwrap()
170				.public(),
171		);
172	}
173
174	#[test]
175	fn seed_and_derive_should_work() {
176		let seed = array_bytes::hex2array_unchecked(
177			"9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60",
178		);
179		let pair = Pair::from_seed(&seed);
180		assert_eq!(pair.seed(), seed);
181		let path = vec![DeriveJunction::Hard([0u8; 32])];
182		let derived = pair.derive(path.into_iter(), None).ok().unwrap().0;
183		assert_eq!(
184			derived.seed(),
185			array_bytes::hex2array_unchecked::<_, 32>(
186				"ede3354e133f9c8e337ddd6ee5415ed4b4ffe5fc7d21e933f4930a3730e5b21c"
187			)
188		);
189	}
190
191	#[test]
192	fn generate_with_phrase_should_be_recoverable_with_from_string() {
193		let (pair, phrase, seed) = Pair::generate_with_phrase(None);
194		let repair_seed = Pair::from_seed_slice(seed.as_ref()).expect("seed slice is valid");
195		assert_eq!(pair.public(), repair_seed.public());
196		assert_eq!(pair.to_raw_vec(), repair_seed.to_raw_vec());
197		let (repair_phrase, reseed) =
198			Pair::from_phrase(phrase.as_ref(), None).expect("seed slice is valid");
199		assert_eq!(seed, reseed);
200		assert_eq!(pair.public(), repair_phrase.public());
201		assert_eq!(pair.to_raw_vec(), repair_seed.to_raw_vec());
202		let repair_string = Pair::from_string(phrase.as_str(), None).expect("seed slice is valid");
203		assert_eq!(pair.public(), repair_string.public());
204		assert_eq!(pair.to_raw_vec(), repair_seed.to_raw_vec());
205	}
206
207	#[test]
208	fn test_vector_should_work() {
209		let pair = Pair::from_seed(&array_bytes::hex2array_unchecked(
210			"9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60",
211		));
212		let public = pair.public();
213		assert_eq!(
214			public,
215			Public::from_raw(array_bytes::hex2array_unchecked(
216				"d75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a"
217			))
218		);
219		let message = b"";
220		let signature = array_bytes::hex2array_unchecked("e5564300c360ac729086e2cc806e828a84877f1eb8e5d974d873e065224901555fb8821590a33bacc61e39701cf9b46bd25bf5f0595bbe24655141438e7a100b");
221		let signature = Signature::from_raw(signature);
222		assert!(pair.sign(&message[..]) == signature);
223		assert!(Pair::verify(&signature, &message[..], &public));
224	}
225
226	#[test]
227	fn test_vector_by_string_should_work() {
228		let pair = Pair::from_string(
229			"0x9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60",
230			None,
231		)
232		.unwrap();
233		let public = pair.public();
234		assert_eq!(
235			public,
236			Public::from_raw(array_bytes::hex2array_unchecked(
237				"d75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a"
238			))
239		);
240		let message = b"";
241		let signature = array_bytes::hex2array_unchecked("e5564300c360ac729086e2cc806e828a84877f1eb8e5d974d873e065224901555fb8821590a33bacc61e39701cf9b46bd25bf5f0595bbe24655141438e7a100b");
242		let signature = Signature::from_raw(signature);
243		assert!(pair.sign(&message[..]) == signature);
244		assert!(Pair::verify(&signature, &message[..], &public));
245	}
246
247	#[test]
248	fn generated_pair_should_work() {
249		let (pair, _) = Pair::generate();
250		let public = pair.public();
251		let message = b"Something important";
252		let signature = pair.sign(&message[..]);
253		assert!(Pair::verify(&signature, &message[..], &public));
254		assert!(!Pair::verify(&signature, b"Something else", &public));
255	}
256
257	#[test]
258	fn seeded_pair_should_work() {
259		let pair = Pair::from_seed(b"12345678901234567890123456789012");
260		let public = pair.public();
261		assert_eq!(
262			public,
263			Public::from_raw(array_bytes::hex2array_unchecked(
264				"2f8c6129d816cf51c374bc7f08c3e63ed156cf78aefb4a6550d97b87997977ee"
265			))
266		);
267		let message = array_bytes::hex2bytes_unchecked("2f8c6129d816cf51c374bc7f08c3e63ed156cf78aefb4a6550d97b87997977ee00000000000000000200d75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a4500000000000000");
268		let signature = pair.sign(&message[..]);
269		println!("Correct signature: {:?}", signature);
270		assert!(Pair::verify(&signature, &message[..], &public));
271		assert!(!Pair::verify(&signature, "Other message", &public));
272	}
273
274	#[test]
275	fn generate_with_phrase_recovery_possible() {
276		let (pair1, phrase, _) = Pair::generate_with_phrase(None);
277		let (pair2, _) = Pair::from_phrase(&phrase, None).unwrap();
278
279		assert_eq!(pair1.public(), pair2.public());
280	}
281
282	#[test]
283	fn generate_with_password_phrase_recovery_possible() {
284		let (pair1, phrase, _) = Pair::generate_with_phrase(Some("password"));
285		let (pair2, _) = Pair::from_phrase(&phrase, Some("password")).unwrap();
286
287		assert_eq!(pair1.public(), pair2.public());
288	}
289
290	#[test]
291	fn password_does_something() {
292		let (pair1, phrase, _) = Pair::generate_with_phrase(Some("password"));
293		let (pair2, _) = Pair::from_phrase(&phrase, None).unwrap();
294
295		assert_ne!(pair1.public(), pair2.public());
296		assert_ne!(pair1.to_raw_vec(), pair2.to_raw_vec());
297	}
298
299	#[test]
300	fn ss58check_roundtrip_works() {
301		let pair = Pair::from_seed(b"12345678901234567890123456789012");
302		let public = pair.public();
303		let s = public.to_ss58check();
304		println!("Correct: {}", s);
305		let cmp = Public::from_ss58check(&s).unwrap();
306		assert_eq!(cmp, public);
307	}
308
309	#[test]
310	fn signature_serialization_works() {
311		let pair = Pair::from_seed(b"12345678901234567890123456789012");
312		let message = b"Something important";
313		let signature = pair.sign(&message[..]);
314		let serialized_signature = serde_json::to_string(&signature).unwrap();
315		// Signature is 64 bytes, so 128 chars + 2 quote chars
316		assert_eq!(serialized_signature.len(), 130);
317		let signature = serde_json::from_str(&serialized_signature).unwrap();
318		assert!(Pair::verify(&signature, &message[..], &pair.public()));
319	}
320
321	#[test]
322	fn signature_serialization_doesnt_panic() {
323		fn deserialize_signature(text: &str) -> Result<Signature, serde_json::error::Error> {
324			serde_json::from_str(text)
325		}
326		assert!(deserialize_signature("Not valid json.").is_err());
327		assert!(deserialize_signature("\"Not an actual signature.\"").is_err());
328		// Poorly-sized
329		assert!(deserialize_signature("\"abc123\"").is_err());
330	}
331}
sp_core/ed25519.rs

sp_core/
ed25519.rs
