iroh_base/
key.rs

1//! Cryptographic key handling for `iroh`.
2
3use std::{
4    borrow::Borrow,
5    cmp::{Ord, PartialOrd},
6    fmt::{self, Debug, Display},
7    hash::Hash,
8    ops::Deref,
9    str::FromStr,
10};
11
12use curve25519_dalek::edwards::CompressedEdwardsY;
13use data_encoding::Encoding;
14use data_encoding_macro::new_encoding;
15use ed25519_dalek::{SigningKey, VerifyingKey};
16use n0_error::{e, ensure, stack_error};
17use serde::{Deserialize, Serialize, de, ser};
18
19/// z-base-32 encoding as used by [pkarr](https://pkarr.org) for endpoint id domain names.
20const Z_BASE_32: Encoding = new_encoding! {
21    symbols: "ybndrfg8ejkmcpqxot1uwisza345h769",
22};
23
24/// A public key.
25///
26/// The key itself is stored as the `CompressedEdwards` y coordinate of the public key
27/// It is verified to decompress into a valid key when created.
28#[derive(Clone, Copy, PartialEq, Eq)]
29#[repr(transparent)]
30pub struct PublicKey(CompressedEdwardsY);
31
32impl Borrow<[u8; 32]> for PublicKey {
33    fn borrow(&self) -> &[u8; 32] {
34        self.as_bytes()
35    }
36}
37
38impl Deref for PublicKey {
39    type Target = [u8; 32];
40
41    fn deref(&self) -> &Self::Target {
42        self.as_bytes()
43    }
44}
45
46impl PartialOrd for PublicKey {
47    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
48        Some(self.cmp(other))
49    }
50}
51
52impl Ord for PublicKey {
53    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
54        self.0.as_bytes().cmp(other.0.as_bytes())
55    }
56}
57
58/// The identifier for an endpoint in the (iroh) network.
59///
60/// Each endpoint in iroh has a unique identifier created as a cryptographic key.  This can be
61/// used to globally identify an endpoint.  Since it is also a cryptographic key it is also the
62/// mechanism by which all traffic is always encrypted for a specific endpoint only.
63///
64/// This is equivalent to [`PublicKey`].  By convention we will (or should) use `PublicKey`
65/// as type name when performing cryptographic operations, but use `EndpointId` when referencing
66/// an endpoint.  E.g.:
67///
68/// - `encrypt(key: PublicKey)`
69/// - `send_to(endpoint: EndpointId)`
70pub type EndpointId = PublicKey;
71
72impl Hash for PublicKey {
73    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
74        self.0.hash(state);
75    }
76}
77
78impl Serialize for PublicKey {
79    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
80    where
81        S: serde::Serializer,
82    {
83        if serializer.is_human_readable() {
84            serializer.serialize_str(&self.to_string())
85        } else {
86            self.0.as_bytes().serialize(serializer)
87        }
88    }
89}
90
91impl<'de> Deserialize<'de> for PublicKey {
92    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
93    where
94        D: serde::Deserializer<'de>,
95    {
96        if deserializer.is_human_readable() {
97            let s = String::deserialize(deserializer)?;
98            Self::from_str(&s).map_err(serde::de::Error::custom)
99        } else {
100            let data: [u8; 32] = serde::Deserialize::deserialize(deserializer)?;
101            Self::try_from(data.as_ref()).map_err(serde::de::Error::custom)
102        }
103    }
104}
105
106impl PublicKey {
107    /// The length of an ed25519 `PublicKey`, in bytes.
108    pub const LENGTH: usize = ed25519_dalek::PUBLIC_KEY_LENGTH;
109
110    /// Get this public key as a byte array.
111    pub fn as_bytes(&self) -> &[u8; 32] {
112        self.0.as_bytes()
113    }
114
115    /// Construct a `PublicKey` from a slice of bytes.
116    ///
117    /// # Warning
118    ///
119    /// This will return a [`SignatureError`] if the bytes passed into this method do not represent
120    /// a valid `ed25519_dalek` curve point. Will never fail for bytes return from [`Self::as_bytes`].
121    /// See [`VerifyingKey::from_bytes`] for details.
122    pub fn from_bytes(bytes: &[u8; 32]) -> Result<Self, KeyParsingError> {
123        let key =
124            VerifyingKey::from_bytes(bytes).map_err(|_| e!(KeyParsingError::InvalidKeyData))?;
125        let y = CompressedEdwardsY(key.to_bytes());
126        Ok(Self(y))
127    }
128
129    /// Verify a signature on a message with this secret key's public key.
130    ///
131    /// # Return
132    ///
133    /// Returns `Ok(())` if the signature is valid, and `Err` otherwise.
134    pub fn verify(&self, message: &[u8], signature: &Signature) -> Result<(), SignatureError> {
135        self.as_verifying_key()
136            .verify_strict(message, &signature.0)
137            .map_err(|_| SignatureError::new())
138    }
139
140    /// Convert to a hex string limited to the first 5 bytes for a friendly string
141    /// representation of the key.
142    pub fn fmt_short(&self) -> impl Display + Copy + 'static {
143        PublicKeyShort(
144            self.0.as_bytes()[0..5]
145                .try_into()
146                .expect("slice with incorrect length"),
147        )
148    }
149
150    /// Needed for internal conversions, not part of the stable API.
151    #[doc(hidden)]
152    pub fn as_verifying_key(&self) -> VerifyingKey {
153        VerifyingKey::from_bytes(self.0.as_bytes()).expect("already verified")
154    }
155
156    /// Needed for internal conversions, not part of the stable API.
157    #[doc(hidden)]
158    pub fn from_verifying_key(key: VerifyingKey) -> Self {
159        Self(CompressedEdwardsY(key.to_bytes()))
160    }
161
162    /// Encodes this key in [z-base-32](https://philzimmermann.com/docs/human-oriented-base-32-encoding.txt),
163    /// the encoding used by [pkarr](https://pkarr.org) domain names.
164    pub fn to_z32(&self) -> String {
165        Z_BASE_32.encode(self.as_bytes())
166    }
167
168    /// Parses a key from its [z-base-32](https://philzimmermann.com/docs/human-oriented-base-32-encoding.txt) encoding.
169    pub fn from_z32(s: &str) -> Result<Self, KeyParsingError> {
170        let bytes = Z_BASE_32
171            .decode(s.as_bytes())
172            .map_err(|_| e!(KeyParsingError::FailedToDecodeBase32))?;
173        Self::try_from(bytes.as_slice())
174    }
175}
176
177#[derive(Copy, Clone)]
178struct PublicKeyShort([u8; 5]);
179
180impl Display for PublicKeyShort {
181    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
182        data_encoding::HEXLOWER.encode_write(&self.0, f)
183    }
184}
185
186impl TryFrom<&[u8]> for PublicKey {
187    type Error = KeyParsingError;
188
189    #[inline]
190    fn try_from(bytes: &[u8]) -> Result<Self, Self::Error> {
191        let vk = VerifyingKey::try_from(bytes).map_err(|_| e!(KeyParsingError::InvalidKeyData))?;
192        Ok(Self(CompressedEdwardsY(vk.to_bytes())))
193    }
194}
195
196impl TryFrom<&[u8; 32]> for PublicKey {
197    type Error = KeyParsingError;
198
199    #[inline]
200    fn try_from(bytes: &[u8; 32]) -> Result<Self, Self::Error> {
201        Self::from_bytes(bytes)
202    }
203}
204
205impl AsRef<[u8]> for PublicKey {
206    fn as_ref(&self) -> &[u8] {
207        self.as_bytes()
208    }
209}
210
211impl Debug for PublicKey {
212    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
213        write!(
214            f,
215            "PublicKey({})",
216            data_encoding::HEXLOWER.encode(self.as_bytes())
217        )
218    }
219}
220
221impl Display for PublicKey {
222    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
223        write!(f, "{}", data_encoding::HEXLOWER.encode(self.as_bytes()))
224    }
225}
226
227/// Error when deserialising a [`PublicKey`] or a [`SecretKey`].
228#[stack_error(derive, add_meta, from_sources, std_sources)]
229#[allow(missing_docs)]
230#[non_exhaustive]
231pub enum KeyParsingError {
232    /// The input string could not be decoded as hex.
233    #[error("failed to decode hex string")]
234    FailedToDecodeHex,
235    /// The input string could not be decoded as base32.
236    #[error("failed to decode base32 string")]
237    FailedToDecodeBase32,
238    /// The input has invalid length.
239    #[error("invalid length")]
240    InvalidLength,
241    /// The decoded data is not a valid Ed25591 public key.
242    #[error("data is not a valid public key")]
243    InvalidKeyData,
244}
245
246/// Deserialises the [`PublicKey`] from it's base32 encoding.
247///
248/// [`Display`] is capable of serialising this format.
249impl FromStr for PublicKey {
250    type Err = KeyParsingError;
251
252    fn from_str(s: &str) -> Result<Self, Self::Err> {
253        let bytes = decode_base32_hex(s)?;
254
255        Self::from_bytes(&bytes)
256    }
257}
258
259/// A secret key.
260#[derive(Clone, zeroize::ZeroizeOnDrop)]
261pub struct SecretKey(SigningKey);
262
263impl Debug for SecretKey {
264    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
265        write!(f, "SecretKey(..)")
266    }
267}
268
269impl FromStr for SecretKey {
270    type Err = KeyParsingError;
271
272    fn from_str(s: &str) -> Result<Self, Self::Err> {
273        let bytes = decode_base32_hex(s)?;
274        Ok(SecretKey::from(bytes))
275    }
276}
277
278impl Serialize for SecretKey {
279    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
280    where
281        S: serde::Serializer,
282    {
283        self.0.serialize(serializer)
284    }
285}
286
287impl<'de> Deserialize<'de> for SecretKey {
288    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
289    where
290        D: serde::Deserializer<'de>,
291    {
292        let secret = SigningKey::deserialize(deserializer)?;
293        Ok(Self(secret))
294    }
295}
296
297impl SecretKey {
298    /// The public key of this [`SecretKey`].
299    pub fn public(&self) -> PublicKey {
300        let key = self.0.verifying_key().to_bytes();
301        PublicKey(CompressedEdwardsY(key))
302    }
303
304    /// Generate a new [`SecretKey`] with a randomness generator.
305    ///
306    /// This uses the default random number generator from the `rand` crate.
307    /// If you want to customize how the randomness is generated, use
308    /// [`Self::from_bytes`] instead and generate the 32 bytes yourself:
309    ///
310    /// ```rust
311    /// # use iroh_base::SecretKey;
312    /// # use rand::RngExt;
313    /// // Create a random number generator.
314    /// let mut rng = rand::rng();
315    /// // Use it to generate the 32 bytes that make up a secret key.
316    /// let secret_key = SecretKey::from_bytes(&rng.random());
317    /// ```
318    pub fn generate() -> Self {
319        Self::from_bytes(&rand::random())
320    }
321
322    /// Sign the given message and return a digital signature
323    pub fn sign(&self, msg: &[u8]) -> Signature {
324        use ed25519_dalek::Signer;
325
326        let sig = self.0.sign(msg);
327        Signature(sig)
328    }
329
330    /// Convert this to the bytes representing the secret part.
331    /// The public part can always be recovered.
332    pub fn to_bytes(&self) -> [u8; 32] {
333        self.0.to_bytes()
334    }
335
336    /// Create a secret key from its byte representation.
337    pub fn from_bytes(bytes: &[u8; 32]) -> Self {
338        let secret = SigningKey::from_bytes(bytes);
339        Self(secret)
340    }
341
342    /// Needed for internal conversions, not part of the stable API.
343    #[doc(hidden)]
344    pub fn as_signing_key(&self) -> &SigningKey {
345        &self.0
346    }
347}
348
349impl From<[u8; 32]> for SecretKey {
350    fn from(value: [u8; 32]) -> Self {
351        Self::from_bytes(&value)
352    }
353}
354
355impl TryFrom<&[u8]> for SecretKey {
356    type Error = KeyParsingError;
357
358    #[inline]
359    fn try_from(bytes: &[u8]) -> Result<Self, Self::Error> {
360        let bytes: [u8; 32] = bytes
361            .try_into()
362            .map_err(|_| e!(KeyParsingError::InvalidLength))?;
363        let secret = SigningKey::from_bytes(&bytes);
364        Ok(Self(secret))
365    }
366}
367
368/// Ed25519 signature.
369#[derive(Copy, Clone, Eq, PartialEq)]
370pub struct Signature(ed25519_dalek::Signature);
371
372impl Serialize for Signature {
373    fn serialize<S: ser::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
374        use ser::SerializeTuple;
375
376        let mut seq = serializer.serialize_tuple(Signature::LENGTH)?;
377
378        for byte in self.to_bytes() {
379            seq.serialize_element(&byte)?;
380        }
381
382        seq.end()
383    }
384}
385
386// serde lacks support for deserializing arrays larger than 32-bytes
387// see: <https://github.com/serde-rs/serde/issues/631>
388impl<'de> Deserialize<'de> for Signature {
389    fn deserialize<D: de::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
390        struct ByteArrayVisitor;
391
392        impl<'de> de::Visitor<'de> for ByteArrayVisitor {
393            type Value = [u8; Signature::LENGTH];
394
395            fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
396                formatter.write_str("bytestring of length 64")
397            }
398
399            fn visit_seq<A>(self, mut seq: A) -> Result<[u8; Signature::LENGTH], A::Error>
400            where
401                A: de::SeqAccess<'de>,
402            {
403                use de::Error;
404                let mut arr = [0u8; Signature::LENGTH];
405
406                for (i, byte) in arr.iter_mut().enumerate() {
407                    *byte = seq
408                        .next_element()?
409                        .ok_or_else(|| Error::invalid_length(i, &self))?;
410                }
411
412                Ok(arr)
413            }
414        }
415
416        deserializer
417            .deserialize_tuple(Signature::LENGTH, ByteArrayVisitor)
418            .map(|b| Signature::from_bytes(&b))
419    }
420}
421
422impl Debug for Signature {
423    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
424        write!(f, "{:?}", self.0)
425    }
426}
427
428impl Display for Signature {
429    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
430        write!(f, "{}", self.0)
431    }
432}
433
434#[stack_error(derive, add_meta)]
435#[error("Could not parse ed25519 signature")]
436pub struct SignatureParsingError;
437
438impl TryFrom<&[u8]> for Signature {
439    type Error = SignatureParsingError;
440
441    fn try_from(bytes: &[u8]) -> Result<Self, Self::Error> {
442        let signature =
443            ed25519_dalek::Signature::from_slice(bytes).map_err(|_| e!(SignatureParsingError))?;
444        Ok(Self(signature))
445    }
446}
447
448impl Signature {
449    /// The length of an ed25519 `Signature`, in bytes.
450    pub const LENGTH: usize = ed25519_dalek::Signature::BYTE_SIZE;
451
452    /// Return the inner byte array.
453    pub fn to_bytes(&self) -> [u8; Self::LENGTH] {
454        self.0.to_bytes()
455    }
456
457    /// Parse an Ed25519 signature from a byte slice.
458    pub fn from_bytes(bytes: &[u8; Self::LENGTH]) -> Self {
459        Self(ed25519_dalek::Signature::from_bytes(bytes))
460    }
461}
462
463/// Verification of a signature failed.
464#[stack_error(derive, add_meta)]
465#[error("Invalid signature")]
466pub struct SignatureError {}
467
468fn decode_base32_hex(s: &str) -> Result<[u8; 32], KeyParsingError> {
469    let mut bytes = [0u8; 32];
470
471    let len = if s.len() == PublicKey::LENGTH * 2 {
472        // hex
473        data_encoding::HEXLOWER
474            .decode_mut(s.as_bytes(), &mut bytes)
475            .map_err(|_| e!(KeyParsingError::FailedToDecodeHex))?
476    } else {
477        let input = s.to_ascii_uppercase();
478        let input = input.as_bytes();
479        ensure!(
480            data_encoding::BASE32_NOPAD.decode_len(input.len()) == Ok(bytes.len()),
481            KeyParsingError::InvalidLength
482        );
483        data_encoding::BASE32_NOPAD
484            .decode_mut(input, &mut bytes)
485            .map_err(|_| e!(KeyParsingError::FailedToDecodeBase32))?
486    };
487    ensure!(len == PublicKey::LENGTH, KeyParsingError::InvalidLength);
488    Ok(bytes)
489}
490
491#[cfg(test)]
492mod tests {
493    use data_encoding::HEXLOWER;
494    use rand::{RngExt, SeedableRng};
495
496    use super::*;
497
498    #[test]
499    fn test_public_key_postcard() {
500        let public_key =
501            PublicKey::from_str("ae58ff8833241ac82d6ff7611046ed67b5072d142c588d0063e942d9a75502b6")
502                .unwrap();
503        let bytes = postcard::to_stdvec(&public_key).unwrap();
504        let expected = HEXLOWER
505            .decode(b"ae58ff8833241ac82d6ff7611046ed67b5072d142c588d0063e942d9a75502b6")
506            .unwrap();
507        assert_eq!(bytes, expected);
508    }
509
510    #[test]
511    fn public_key_postcard() {
512        let key = PublicKey::from_bytes(&[0; 32]).unwrap();
513        let bytes = postcard::to_stdvec(&key).unwrap();
514        let key2: PublicKey = postcard::from_bytes(&bytes).unwrap();
515        assert_eq!(key, key2);
516    }
517
518    #[test]
519    fn public_key_json() {
520        let key = PublicKey::from_bytes(&[0; 32]).unwrap();
521        let bytes = serde_json::to_string(&key).unwrap();
522        let key2: PublicKey = serde_json::from_str(&bytes).unwrap();
523        assert_eq!(key, key2);
524    }
525
526    #[test]
527    fn test_from_str() {
528        let mut rng = rand_chacha::ChaCha8Rng::seed_from_u64(0u64);
529        let key = SecretKey::from_bytes(&rng.random());
530        assert_eq!(
531            SecretKey::from_str(&HEXLOWER.encode(&key.to_bytes()))
532                .unwrap()
533                .to_bytes(),
534            key.to_bytes()
535        );
536
537        assert_eq!(
538            PublicKey::from_str(&key.public().to_string()).unwrap(),
539            key.public()
540        );
541    }
542
543    #[test]
544    fn test_regression_parse_endpoint_id_panic() {
545        let not_a_endpoint_id = "foobarbaz";
546        assert!(PublicKey::from_str(not_a_endpoint_id).is_err());
547    }
548
549    #[test]
550    fn signature_postcard() {
551        let key = SecretKey::generate();
552        let signature = key.sign(b"hello world");
553        let bytes = postcard::to_stdvec(&signature).unwrap();
554        let signature2: Signature = postcard::from_bytes(&bytes).unwrap();
555        assert_eq!(signature, signature2);
556    }
557}
iroh_base/key.rs

iroh_base/
key.rs
