commonware_cryptography/ed25519/
scheme.rs

1use crate::{Array, BatchScheme, Signer, Specification, Verifier};
2use bytes::{Buf, BufMut};
3use commonware_codec::{Error as CodecError, FixedSize, Read, ReadExt, Write};
4use commonware_utils::{hex, union_unique};
5use ed25519_consensus::{self, VerificationKey};
6use rand::{CryptoRng, Rng, RngCore};
7use std::borrow::Cow;
8use std::fmt::{Debug, Display};
9use std::hash::{Hash, Hasher};
10use std::ops::Deref;
11use zeroize::{Zeroize, ZeroizeOnDrop};
12
13const CURVE_NAME: &str = "ed25519";
14const PRIVATE_KEY_LENGTH: usize = 32;
15const PUBLIC_KEY_LENGTH: usize = 32;
16const SIGNATURE_LENGTH: usize = 64;
17
18/// Ed25519 Signer.
19#[derive(Clone)]
20pub struct Ed25519 {
21    signer: ed25519_consensus::SigningKey,
22    verifier: ed25519_consensus::VerificationKey,
23}
24
25impl Specification for Ed25519 {
26    type PublicKey = PublicKey;
27    type Signature = Signature;
28}
29
30impl Verifier for Ed25519 {
31    fn verify(
32        namespace: Option<&[u8]>,
33        message: &[u8],
34        public_key: &Self::PublicKey,
35        signature: &Self::Signature,
36    ) -> bool {
37        match namespace {
38            Some(namespace) => {
39                let payload = union_unique(namespace, message);
40                public_key
41                    .key
42                    .verify(&signature.signature, &payload)
43                    .is_ok()
44            }
45            None => public_key.key.verify(&signature.signature, message).is_ok(),
46        }
47    }
48}
49
50impl Signer for Ed25519 {
51    type PrivateKey = PrivateKey;
52
53    fn new<R: CryptoRng + Rng>(r: &mut R) -> Self {
54        let signer = ed25519_consensus::SigningKey::new(r);
55        let verifier = signer.verification_key();
56        Self { signer, verifier }
57    }
58
59    fn from(private_key: PrivateKey) -> Option<Self> {
60        let signer = private_key.key.clone();
61        let verifier = signer.verification_key();
62        Some(Self { signer, verifier })
63    }
64
65    fn private_key(&self) -> PrivateKey {
66        PrivateKey::from(self.signer.clone())
67    }
68
69    fn public_key(&self) -> PublicKey {
70        PublicKey::from(self.verifier)
71    }
72
73    fn sign(&mut self, namespace: Option<&[u8]>, message: &[u8]) -> Signature {
74        let sig = match namespace {
75            Some(namespace) => self.signer.sign(&union_unique(namespace, message)),
76            None => self.signer.sign(message),
77        };
78        Signature::from(sig)
79    }
80}
81
82/// Ed25519 Batch Verifier.
83pub struct Ed25519Batch {
84    verifier: ed25519_consensus::batch::Verifier,
85}
86
87impl Specification for Ed25519Batch {
88    type PublicKey = PublicKey;
89    type Signature = Signature;
90}
91
92impl BatchScheme for Ed25519Batch {
93    fn new() -> Self {
94        Ed25519Batch {
95            verifier: ed25519_consensus::batch::Verifier::new(),
96        }
97    }
98
99    fn add(
100        &mut self,
101        namespace: Option<&[u8]>,
102        message: &[u8],
103        public_key: &Self::PublicKey,
104        signature: &Self::Signature,
105    ) -> bool {
106        let payload = match namespace {
107            Some(namespace) => Cow::Owned(union_unique(namespace, message)),
108            None => Cow::Borrowed(message),
109        };
110        let item = ed25519_consensus::batch::Item::from((
111            public_key.key.into(),
112            signature.signature,
113            &payload,
114        ));
115        self.verifier.queue(item);
116        true
117    }
118
119    fn verify<R: RngCore + CryptoRng>(self, rng: &mut R) -> bool {
120        self.verifier.verify(rng).is_ok()
121    }
122}
123
124/// Ed25519 Private Key.
125#[derive(Clone, Zeroize, ZeroizeOnDrop)]
126pub struct PrivateKey {
127    raw: [u8; PRIVATE_KEY_LENGTH],
128    key: ed25519_consensus::SigningKey,
129}
130
131impl Write for PrivateKey {
132    fn write(&self, buf: &mut impl BufMut) {
133        self.raw.write(buf);
134    }
135}
136
137impl Read for PrivateKey {
138    fn read_cfg(buf: &mut impl Buf, _: &()) -> Result<Self, CodecError> {
139        let raw = <[u8; Self::SIZE]>::read(buf)?;
140        let key = ed25519_consensus::SigningKey::from(raw);
141        Ok(Self { raw, key })
142    }
143}
144
145impl FixedSize for PrivateKey {
146    const SIZE: usize = PRIVATE_KEY_LENGTH;
147}
148
149impl Array for PrivateKey {}
150
151impl Eq for PrivateKey {}
152
153impl Hash for PrivateKey {
154    fn hash<H: Hasher>(&self, state: &mut H) {
155        self.raw.hash(state);
156    }
157}
158
159impl PartialEq for PrivateKey {
160    fn eq(&self, other: &Self) -> bool {
161        self.raw == other.raw
162    }
163}
164
165impl Ord for PrivateKey {
166    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
167        self.raw.cmp(&other.raw)
168    }
169}
170
171impl PartialOrd for PrivateKey {
172    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
173        Some(self.cmp(other))
174    }
175}
176
177impl AsRef<[u8]> for PrivateKey {
178    fn as_ref(&self) -> &[u8] {
179        &self.raw
180    }
181}
182
183impl Deref for PrivateKey {
184    type Target = [u8];
185    fn deref(&self) -> &[u8] {
186        &self.raw
187    }
188}
189
190impl From<ed25519_consensus::SigningKey> for PrivateKey {
191    fn from(key: ed25519_consensus::SigningKey) -> Self {
192        let raw = key.to_bytes();
193        Self { raw, key }
194    }
195}
196
197impl Debug for PrivateKey {
198    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
199        write!(f, "{}", hex(&self.raw))
200    }
201}
202
203impl Display for PrivateKey {
204    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
205        write!(f, "{}", hex(&self.raw))
206    }
207}
208
209/// Ed25519 Public Key.
210#[derive(Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
211pub struct PublicKey {
212    raw: [u8; PUBLIC_KEY_LENGTH],
213    key: ed25519_consensus::VerificationKey,
214}
215
216impl Write for PublicKey {
217    fn write(&self, buf: &mut impl BufMut) {
218        self.raw.write(buf);
219    }
220}
221
222impl Read for PublicKey {
223    fn read_cfg(buf: &mut impl Buf, _: &()) -> Result<Self, CodecError> {
224        let raw = <[u8; Self::SIZE]>::read(buf)?;
225        let key = VerificationKey::try_from(raw)
226            .map_err(|e| CodecError::Wrapped(CURVE_NAME, e.into()))?;
227        Ok(Self { raw, key })
228    }
229}
230
231impl FixedSize for PublicKey {
232    const SIZE: usize = PUBLIC_KEY_LENGTH;
233}
234
235impl Array for PublicKey {}
236
237impl AsRef<[u8]> for PublicKey {
238    fn as_ref(&self) -> &[u8] {
239        &self.raw
240    }
241}
242
243impl Deref for PublicKey {
244    type Target = [u8];
245    fn deref(&self) -> &[u8] {
246        &self.raw
247    }
248}
249
250impl From<VerificationKey> for PublicKey {
251    fn from(key: VerificationKey) -> Self {
252        let raw = key.to_bytes();
253        Self { raw, key }
254    }
255}
256
257impl Debug for PublicKey {
258    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
259        write!(f, "{}", hex(&self.raw))
260    }
261}
262
263impl Display for PublicKey {
264    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
265        write!(f, "{}", hex(&self.raw))
266    }
267}
268
269/// Ed25519 Signature.
270#[derive(Clone, Eq, PartialEq)]
271pub struct Signature {
272    raw: [u8; SIGNATURE_LENGTH],
273    signature: ed25519_consensus::Signature,
274}
275
276impl Write for Signature {
277    fn write(&self, buf: &mut impl BufMut) {
278        self.raw.write(buf);
279    }
280}
281
282impl Read for Signature {
283    fn read_cfg(buf: &mut impl Buf, _: &()) -> Result<Self, CodecError> {
284        let raw = <[u8; Self::SIZE]>::read(buf)?;
285        let signature = ed25519_consensus::Signature::from(raw);
286        Ok(Self { raw, signature })
287    }
288}
289
290impl FixedSize for Signature {
291    const SIZE: usize = SIGNATURE_LENGTH;
292}
293
294impl Array for Signature {}
295
296impl Hash for Signature {
297    fn hash<H: Hasher>(&self, state: &mut H) {
298        self.raw.hash(state);
299    }
300}
301
302impl Ord for Signature {
303    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
304        self.raw.cmp(&other.raw)
305    }
306}
307
308impl PartialOrd for Signature {
309    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
310        Some(self.cmp(other))
311    }
312}
313
314impl AsRef<[u8]> for Signature {
315    fn as_ref(&self) -> &[u8] {
316        &self.raw
317    }
318}
319
320impl Deref for Signature {
321    type Target = [u8];
322    fn deref(&self) -> &[u8] {
323        &self.raw
324    }
325}
326
327impl From<ed25519_consensus::Signature> for Signature {
328    fn from(value: ed25519_consensus::Signature) -> Self {
329        let raw = value.to_bytes();
330        Self {
331            raw,
332            signature: value,
333        }
334    }
335}
336
337impl Debug for Signature {
338    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
339        write!(f, "{}", hex(&self.raw))
340    }
341}
342
343impl Display for Signature {
344    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
345        write!(f, "{}", hex(&self.raw))
346    }
347}
348
349/// Test vectors sourced from https://datatracker.ietf.org/doc/html/rfc8032#section-7.1.
350#[cfg(test)]
351mod tests {
352    use super::*;
353    use commonware_codec::{DecodeExt, Encode};
354    use rand::rngs::OsRng;
355
356    fn test_sign_and_verify(
357        private_key: PrivateKey,
358        public_key: PublicKey,
359        message: &[u8],
360        signature: Signature,
361    ) {
362        let mut signer = <Ed25519 as Signer>::from(private_key).unwrap();
363        let computed_signature = signer.sign(None, message);
364        assert_eq!(computed_signature, signature);
365        assert!(Ed25519::verify(
366            None,
367            message,
368            &public_key,
369            &computed_signature
370        ));
371    }
372
373    fn parse_private_key(private_key: &str) -> PrivateKey {
374        PrivateKey::decode(
375            commonware_utils::from_hex_formatted(private_key)
376                .unwrap()
377                .as_ref(),
378        )
379        .unwrap()
380    }
381
382    fn parse_public_key(public_key: &str) -> PublicKey {
383        PublicKey::decode(
384            commonware_utils::from_hex_formatted(public_key)
385                .unwrap()
386                .as_ref(),
387        )
388        .unwrap()
389    }
390
391    fn parse_signature(signature: &str) -> Signature {
392        Signature::decode(
393            commonware_utils::from_hex_formatted(signature)
394                .unwrap()
395                .as_ref(),
396        )
397        .unwrap()
398    }
399
400    fn vector_1() -> (PrivateKey, PublicKey, Vec<u8>, Signature) {
401        (
402            // secret key
403            parse_private_key(
404                "
405                9d61b19deffd5a60ba844af492ec2cc4
406                4449c5697b326919703bac031cae7f60
407                ",
408            ),
409            // public key
410            parse_public_key(
411                "
412                d75a980182b10ab7d54bfed3c964073a
413                0ee172f3daa62325af021a68f707511a
414                ",
415            ),
416            // message
417            b"".to_vec(),
418            // signature
419            parse_signature(
420                "
421                e5564300c360ac729086e2cc806e828a
422                84877f1eb8e5d974d873e06522490155
423                5fb8821590a33bacc61e39701cf9b46b
424                d25bf5f0595bbe24655141438e7a100b
425                ",
426            ),
427        )
428    }
429
430    fn vector_2() -> (PrivateKey, PublicKey, Vec<u8>, Signature) {
431        (
432            // secret key
433            parse_private_key(
434                "
435                4ccd089b28ff96da9db6c346ec114e0f
436                5b8a319f35aba624da8cf6ed4fb8a6fb
437                ",
438            ),
439            // public key
440            parse_public_key(
441                "
442                3d4017c3e843895a92b70aa74d1b7ebc
443                9c982ccf2ec4968cc0cd55f12af4660c
444                ",
445            ),
446            // message
447            [0x72].to_vec(),
448            // signature
449            parse_signature(
450                "
451                92a009a9f0d4cab8720e820b5f642540
452                a2b27b5416503f8fb3762223ebdb69da
453                085ac1e43e15996e458f3613d0f11d8c
454                387b2eaeb4302aeeb00d291612bb0c00
455                ",
456            ),
457        )
458    }
459
460    #[test]
461    fn test_codec_private_key() {
462        let private_key = parse_private_key(
463            "
464            9d61b19deffd5a60ba844af492ec2cc4
465            4449c5697b326919703bac031cae7f60
466            ",
467        );
468        let encoded = private_key.encode();
469        assert_eq!(encoded.len(), PRIVATE_KEY_LENGTH);
470        let decoded = PrivateKey::decode(encoded).unwrap();
471        assert_eq!(private_key, decoded);
472    }
473
474    #[test]
475    fn test_codec_public_key() {
476        let public_key = parse_public_key(
477            "
478            d75a980182b10ab7d54bfed3c964073a
479            0ee172f3daa62325af021a68f707511a
480            ",
481        );
482        let encoded = public_key.encode();
483        assert_eq!(encoded.len(), PUBLIC_KEY_LENGTH);
484        let decoded = PublicKey::decode(encoded).unwrap();
485        assert_eq!(public_key, decoded);
486    }
487
488    #[test]
489    fn test_codec_signature() {
490        let signature = parse_signature(
491            "
492            e5564300c360ac729086e2cc806e828a
493            84877f1eb8e5d974d873e06522490155
494            5fb8821590a33bacc61e39701cf9b46b
495            d25bf5f0595bbe24655141438e7a100b
496            ",
497        );
498        let encoded = signature.encode();
499        assert_eq!(encoded.len(), SIGNATURE_LENGTH);
500        let decoded = Signature::decode(encoded).unwrap();
501        assert_eq!(signature, decoded);
502    }
503
504    #[test]
505    fn rfc8032_test_vector_1() {
506        let (private_key, public_key, message, signature) = vector_1();
507        test_sign_and_verify(private_key, public_key, &message, signature)
508    }
509
510    // sanity check the test infra rejects bad signatures
511    #[test]
512    #[should_panic]
513    fn bad_signature() {
514        let (private_key, public_key, message, _) = vector_1();
515        let mut signer = <Ed25519 as Signer>::new(&mut OsRng);
516        let bad_signature = signer.sign(None, message.as_ref());
517        test_sign_and_verify(private_key, public_key, &message, bad_signature);
518    }
519
520    // sanity check the test infra rejects non-matching messages
521    #[test]
522    #[should_panic]
523    fn different_message() {
524        let (private_key, public_key, _, signature) = vector_1();
525        let different_message = b"this is a different message".to_vec();
526        test_sign_and_verify(private_key, public_key, &different_message, signature);
527    }
528
529    #[test]
530    fn rfc8032_test_vector_2() {
531        let (private_key, public_key, message, signature) = vector_2();
532        test_sign_and_verify(private_key, public_key, &message, signature)
533    }
534
535    #[test]
536    fn rfc8032_test_vector_3() {
537        let private_key = parse_private_key(
538            "
539            c5aa8df43f9f837bedb7442f31dcb7b1
540            66d38535076f094b85ce3a2e0b4458f7
541            ",
542        );
543        let public_key = parse_public_key(
544            "
545            fc51cd8e6218a1a38da47ed00230f058
546            0816ed13ba3303ac5deb911548908025
547            ",
548        );
549        let message: [u8; 2] = [0xaf, 0x82];
550        let signature = parse_signature(
551            "
552            6291d657deec24024827e69c3abe01a3
553            0ce548a284743a445e3680d7db5ac3ac
554            18ff9b538d16f290ae67f760984dc659
555            4a7c15e9716ed28dc027beceea1ec40a
556            ",
557        );
558        test_sign_and_verify(private_key, public_key, &message, signature)
559    }
560
561    #[test]
562    fn rfc8032_test_vector_1024() {
563        let private_key = parse_private_key(
564            "
565            f5e5767cf153319517630f226876b86c
566            8160cc583bc013744c6bf255f5cc0ee5
567            ",
568        );
569        let public_key = parse_public_key(
570            "
571            278117fc144c72340f67d0f2316e8386
572            ceffbf2b2428c9c51fef7c597f1d426e
573            ",
574        );
575        let message = commonware_utils::from_hex_formatted(
576            "
577            08b8b2b733424243760fe426a4b54908
578            632110a66c2f6591eabd3345e3e4eb98
579            fa6e264bf09efe12ee50f8f54e9f77b1
580            e355f6c50544e23fb1433ddf73be84d8
581            79de7c0046dc4996d9e773f4bc9efe57
582            38829adb26c81b37c93a1b270b20329d
583            658675fc6ea534e0810a4432826bf58c
584            941efb65d57a338bbd2e26640f89ffbc
585            1a858efcb8550ee3a5e1998bd177e93a
586            7363c344fe6b199ee5d02e82d522c4fe
587            ba15452f80288a821a579116ec6dad2b
588            3b310da903401aa62100ab5d1a36553e
589            06203b33890cc9b832f79ef80560ccb9
590            a39ce767967ed628c6ad573cb116dbef
591            efd75499da96bd68a8a97b928a8bbc10
592            3b6621fcde2beca1231d206be6cd9ec7
593            aff6f6c94fcd7204ed3455c68c83f4a4
594            1da4af2b74ef5c53f1d8ac70bdcb7ed1
595            85ce81bd84359d44254d95629e9855a9
596            4a7c1958d1f8ada5d0532ed8a5aa3fb2
597            d17ba70eb6248e594e1a2297acbbb39d
598            502f1a8c6eb6f1ce22b3de1a1f40cc24
599            554119a831a9aad6079cad88425de6bd
600            e1a9187ebb6092cf67bf2b13fd65f270
601            88d78b7e883c8759d2c4f5c65adb7553
602            878ad575f9fad878e80a0c9ba63bcbcc
603            2732e69485bbc9c90bfbd62481d9089b
604            eccf80cfe2df16a2cf65bd92dd597b07
605            07e0917af48bbb75fed413d238f5555a
606            7a569d80c3414a8d0859dc65a46128ba
607            b27af87a71314f318c782b23ebfe808b
608            82b0ce26401d2e22f04d83d1255dc51a
609            ddd3b75a2b1ae0784504df543af8969b
610            e3ea7082ff7fc9888c144da2af58429e
611            c96031dbcad3dad9af0dcbaaaf268cb8
612            fcffead94f3c7ca495e056a9b47acdb7
613            51fb73e666c6c655ade8297297d07ad1
614            ba5e43f1bca32301651339e22904cc8c
615            42f58c30c04aafdb038dda0847dd988d
616            cda6f3bfd15c4b4c4525004aa06eeff8
617            ca61783aacec57fb3d1f92b0fe2fd1a8
618            5f6724517b65e614ad6808d6f6ee34df
619            f7310fdc82aebfd904b01e1dc54b2927
620            094b2db68d6f903b68401adebf5a7e08
621            d78ff4ef5d63653a65040cf9bfd4aca7
622            984a74d37145986780fc0b16ac451649
623            de6188a7dbdf191f64b5fc5e2ab47b57
624            f7f7276cd419c17a3ca8e1b939ae49e4
625            88acba6b965610b5480109c8b17b80e1
626            b7b750dfc7598d5d5011fd2dcc5600a3
627            2ef5b52a1ecc820e308aa342721aac09
628            43bf6686b64b2579376504ccc493d97e
629            6aed3fb0f9cd71a43dd497f01f17c0e2
630            cb3797aa2a2f256656168e6c496afc5f
631            b93246f6b1116398a346f1a641f3b041
632            e989f7914f90cc2c7fff357876e506b5
633            0d334ba77c225bc307ba537152f3f161
634            0e4eafe595f6d9d90d11faa933a15ef1
635            369546868a7f3a45a96768d40fd9d034
636            12c091c6315cf4fde7cb68606937380d
637            b2eaaa707b4c4185c32eddcdd306705e
638            4dc1ffc872eeee475a64dfac86aba41c
639            0618983f8741c5ef68d3a101e8a3b8ca
640            c60c905c15fc910840b94c00a0b9d0
641            ",
642        )
643        .unwrap();
644        let signature = parse_signature(
645            "
646            0aab4c900501b3e24d7cdf4663326a3a
647            87df5e4843b2cbdb67cbf6e460fec350
648            aa5371b1508f9f4528ecea23c436d94b
649            5e8fcd4f681e30a6ac00a9704a188a03
650            ",
651        );
652        test_sign_and_verify(private_key, public_key, &message, signature)
653    }
654
655    #[test]
656    fn rfc8032_test_vector_sha() {
657        let private_key = commonware_utils::from_hex_formatted(
658            "
659            833fe62409237b9d62ec77587520911e
660            9a759cec1d19755b7da901b96dca3d42
661            ",
662        )
663        .unwrap();
664        let public_key = commonware_utils::from_hex_formatted(
665            "
666            ec172b93ad5e563bf4932c70e1245034
667            c35467ef2efd4d64ebf819683467e2bf
668            ",
669        )
670        .unwrap();
671        let message = commonware_utils::from_hex_formatted(
672            "
673            ddaf35a193617abacc417349ae204131
674            12e6fa4e89a97ea20a9eeee64b55d39a
675            2192992a274fc1a836ba3c23a3feebbd
676            454d4423643ce80e2a9ac94fa54ca49f
677            ",
678        )
679        .unwrap();
680        let signature = commonware_utils::from_hex_formatted(
681            "
682            dc2a4459e7369633a52b1bf277839a00
683            201009a3efbf3ecb69bea2186c26b589
684            09351fc9ac90b3ecfdfbc7c66431e030
685            3dca179c138ac17ad9bef1177331a704
686            ",
687        )
688        .unwrap();
689        test_sign_and_verify(
690            PrivateKey::decode(private_key.as_ref()).unwrap(),
691            PublicKey::decode(public_key.as_ref()).unwrap(),
692            &message,
693            Signature::decode(signature.as_ref()).unwrap(),
694        )
695    }
696
697    #[test]
698    fn batch_verify_valid() {
699        let v1 = vector_1();
700        let v2 = vector_2();
701        let mut batch = Ed25519Batch::new();
702        assert!(batch.add(None, &v1.2, &v1.1, &v1.3));
703        assert!(batch.add(None, &v2.2, &v2.1, &v2.3));
704        assert!(batch.verify(&mut rand::thread_rng()));
705    }
706
707    #[test]
708    fn batch_verify_invalid() {
709        let v1 = vector_1();
710        let v2 = vector_2();
711        let mut bad_signature = v2.3.to_vec();
712        bad_signature[3] = 0xff;
713
714        let mut batch = Ed25519Batch::new();
715        assert!(batch.add(None, &v1.2, &v1.1, &v1.3));
716        assert!(batch.add(
717            None,
718            &v2.2,
719            &v2.1,
720            &Signature::decode(bad_signature.as_ref()).unwrap()
721        ));
722        assert!(!batch.verify(&mut rand::thread_rng()));
723    }
724}
commonware_cryptography/ed25519/scheme.rs

commonware_cryptography/ed25519/
scheme.rs
