core/identity: Document using external fixed keys for network identity (#2165)

Co-authored-by: István Zólyomi <[email protected]>
Co-authored-by: Ruben De Smet <[email protected]>
Co-authored-by: Max Inden <[email protected]>

Author: 4 people

core/src/identity.rs

@@ -19,6 +19,18 @@
 // DEALINGS IN THE SOFTWARE.
 
 //! A node's network identity keys.
+//!
+//! Such identity keys can be randomly generated on every startup,
+//! but using already existing, fixed keys is usually required.
+//! Though libp2p uses other crates (e.g. `ed25519_dalek`) internally,
+//! such details are not exposed as part of libp2p's public interface
+//! to keep them easily upgradable or replaceable (e.g. to `ed25519_zebra`).
+//! Consequently, keys of external ed25519 or secp256k1 crates cannot be
+//! directly converted into libp2p network identities.
+//! Instead, loading fixed keys must use the standard, thus more portable
+//! binary representation of the specific key type
+//! (e.g. [ed25519 binary format](https://datatracker.ietf.org/doc/html/rfc8032#section-5.1.5)).
+//! All key types have functions to enable conversion to/from their binary representations.
 
 pub mod ed25519;
 #[cfg(not(target_arch = "wasm32"))]

core/src/identity/ed25519.rs

@@ -31,7 +31,7 @@ use core::fmt;
 pub struct Keypair(ed25519::Keypair);
 
 impl Keypair {
-    /// Generate a new Ed25519 keypair.
+    /// Generate a new random Ed25519 keypair.
     pub fn generate() -> Keypair {
         Keypair::from(SecretKey::generate())
     }
@@ -43,8 +43,10 @@ impl Keypair {
         self.0.to_bytes()
     }
 
-    /// Decode a keypair from the format produced by `encode`,
-    /// zeroing the input on success.
+    /// Decode a keypair from the [binary format](https://datatracker.ietf.org/doc/html/rfc8032#section-5.1.5)
+    /// produced by [`Keypair::encode`], zeroing the input on success.
+    ///
+    /// Note that this binary format is the same as `ed25519_dalek`'s and `ed25519_zebra`'s.
     pub fn decode(kp: &mut [u8]) -> Result<Keypair, DecodingError> {
         ed25519::Keypair::from_bytes(kp)
             .map(|k| { kp.zeroize(); Keypair(k) })

core/src/identity/secp256k1.rs

@@ -83,14 +83,16 @@ impl fmt::Debug for SecretKey {
 }
 
 impl SecretKey {
-    /// Generate a new Secp256k1 secret key.
+    /// Generate a new random Secp256k1 secret key.
     pub fn generate() -> SecretKey {
         SecretKey(libsecp256k1::SecretKey::random(&mut rand::thread_rng()))
     }
 
     /// Create a secret key from a byte slice, zeroing the slice on success.
     /// If the bytes do not constitute a valid Secp256k1 secret key, an
     /// error is returned.
+    ///
+    /// Note that the expected binary format is the same as `libsecp256k1`'s.
     pub fn from_bytes(mut sk: impl AsMut<[u8]>) -> Result<SecretKey, DecodingError> {
         let sk_bytes = sk.as_mut();
         let secret = libsecp256k1::SecretKey::parse_slice(&*sk_bytes)