vti_common/slip10/

mod.rs

//! SLIP-0010 hierarchical deterministic key derivation for Ed25519.
//!
//! This is the derivation scheme the whole workspace's key hierarchy rests on:
//! every VTA key lives at some `m/26'/2'/<ctx>'/<key>'` under the master seed,
//! and the VTA re-derives them from that seed on every restart. Output here is
//! therefore a compatibility surface with every DID we have ever published —
//! see the byte-exactness note under "Provenance" below.
//!
//! # Why this exists in-tree
//!
//! This replaces the `ed25519-dalek-bip32` crate (plus its `derivation-path`
//! dependency), which pinned `ed25519-dalek 2.x` and so straddled the
//! workspace's move to `ed25519-dalek 3` / `curve25519-dalek 5`: the derived
//! `SigningKey` was a *different type* from the `SigningKey` every consumer
//! used, and only passed between them because both expose raw `[u8; 32]`. That
//! type-punning is now gone — this module derives directly into the workspace's
//! own `ed25519-dalek`, and uses `hmac 0.13` / `sha2 0.11` rather than the
//! `hmac 0.12` / `sha2 0.10` the old crate held.
//!
//! # Scheme
//!
//! SLIP-0010 for the `ed25519` curve, which is BIP-32 adapted to Ed25519:
//!
//! - Master key: `HMAC-SHA512(key = "ed25519 seed", data = seed)`, split into
//!   a 32-byte key and a 32-byte chain code.
//! - Child key: `HMAC-SHA512(key = chain_code, data = 0x00 || key || index_be)`,
//!   split the same way.
//! - **Hardened derivation only.** Ed25519 has no public-key child derivation,
//!   so a non-hardened index is a hard error, not a silent hardening. That is a
//!   security property worth stating: it means a leaked extended *public* key
//!   can never be walked to sibling or child keys.
//!
//! Note that this is *not* the scheme in the similarly-named `ed25519-bip32`
//! crate, which implements BIP32-Ed25519 (Khovratovich–Law, as used by
//! Cardano). That scheme derives different key material from the same seed and
//! path, and its extended keys have no 32-byte seed to hand to `did:key`.
//! Swapping to it would re-key every VTA. Do not "upgrade" to it.
//!
//! # Provenance
//!
//! Correctness is pinned to the published SLIP-0010 Ed25519 test vectors
//! (<https://github.com/satoshilabs/slips/blob/master/slip-0010.md>), reproduced
//! verbatim in this module's tests. The spec is frozen, so those vectors are a
//! permanent oracle — this code should never need to change to stay correct.
//!
//! Byte-exactness against the crate this replaces is pinned separately, and by
//! something stronger than a parity test: `vta-keys/src/derivation.rs` already
//! asserts hard-coded multibase key strings (e.g.
//! `z6MkestKNR7EyyB8yojbPcRoG8rF6iX4uXYkyVbDBsM9Fj5i` at `m/44'/0'/0'`) that
//! were generated by `ed25519-dalek-bip32` before this module existed. Those
//! are the workspace's own derived values rather than a synthetic comparison,
//! so if this module ever diverges, real VTA keys fail to re-derive and those
//! tests go red. Do not weaken or regenerate them.

mod path;

pub use path::{
    ChildIndex, ChildIndexError, ChildIndexParseError, DerivationPath, DerivationPathParseError,
};

use ed25519_dalek::{SigningKey, VerifyingKey};
use hmac::{Hmac, KeyInit, Mac};
use sha2::Sha512;
use std::fmt;
use zeroize::Zeroizing;

type HmacSha512 = Hmac<Sha512>;

/// SLIP-0010's fixed HMAC key for the Ed25519 curve. Changing this changes
/// every key the workspace has ever derived.
const ED25519_CURVE: &[u8] = b"ed25519 seed";

/// Minimum master-seed length, in bytes.
///
/// SLIP-0010 specifies a seed of 128–512 bits. We enforce only the floor: a
/// shorter seed is unambiguously a security defect and should fail loudly,
/// whereas rejecting a *longer* one would break an existing store for no
/// security benefit (HMAC accepts a key of any length). In practice the
/// workspace feeds this either 32 random bytes or a 64-byte BIP-39 seed.
pub const MIN_SEED_LEN: usize = 16;

/// Failure during SLIP-0010 derivation.
#[derive(Debug, thiserror::Error)]
pub enum Slip10Error {
    /// A non-hardened index was used. Ed25519 supports hardened derivation
    /// only; this is refused rather than silently hardened.
    #[error("expected hardened child index: {0}")]
    ExpectedHardenedIndex(ChildIndex),
    /// The master seed was shorter than [`MIN_SEED_LEN`].
    #[error("master seed is {got} bytes, need at least {min}")]
    SeedTooShort {
        /// Length actually supplied.
        got: usize,
        /// Required minimum ([`MIN_SEED_LEN`]).
        min: usize,
    },
}

/// An Ed25519 signing key plus the chain code needed to derive its children.
///
/// `signing_key` holds the 32-byte *seed* form of the Ed25519 key (what
/// `SigningKey::as_bytes` returns), which is what `did:key` encoding and
/// `Secret::generate_ed25519` consume — the reason SLIP-0010 fits this
/// workspace and BIP32-Ed25519 does not.
pub struct ExtendedSigningKey {
    /// Derivation depth: 0 for the master key.
    pub depth: u8,
    /// The index this key was derived under. `Normal(0)` for the master key,
    /// which matches SLIP-0010 and the crate this replaces.
    pub child_index: ChildIndex,
    /// The Ed25519 signing key at this path.
    pub signing_key: SigningKey,
    /// The chain code, mixed into every child derivation.
    pub chain_code: [u8; 32],
}

impl ExtendedSigningKey {
    /// Derive the master key from a seed.
    ///
    /// Errors if the seed is shorter than [`MIN_SEED_LEN`].
    pub fn from_seed(seed: &[u8]) -> Result<Self, Slip10Error> {
        if seed.len() < MIN_SEED_LEN {
            return Err(Slip10Error::SeedTooShort {
                got: seed.len(),
                min: MIN_SEED_LEN,
            });
        }

        let mut mac = <HmacSha512 as KeyInit>::new_from_slice(ED25519_CURVE)
            .expect("HMAC accepts a key of any length");
        mac.update(seed);

        Ok(Self::split(&mac_output(mac), 0, ChildIndex::Normal(0)))
    }

    /// Derive along a whole path. An empty path returns a clone of `self`.
    pub fn derive<P: AsRef<[ChildIndex]>>(&self, path: &P) -> Result<Self, Slip10Error> {
        let mut next = self.clone();
        for index in path.as_ref() {
            next = next.derive_child(*index)?;
        }
        Ok(next)
    }

    /// Derive a single child.
    ///
    /// Refuses non-hardened indexes — Ed25519 has no normal derivation.
    pub fn derive_child(&self, index: ChildIndex) -> Result<Self, Slip10Error> {
        if index.is_normal() {
            return Err(Slip10Error::ExpectedHardenedIndex(index));
        }

        let mut mac = <HmacSha512 as KeyInit>::new_from_slice(&self.chain_code)
            .expect("HMAC accepts a key of any length");
        // SLIP-0010 hardened child data: 0x00 || key || ser32(index).
        mac.update(&[0u8]);
        mac.update(self.signing_key.as_bytes());
        mac.update(&index.to_bits().to_be_bytes());

        Ok(Self::split(
            &mac_output(mac),
            self.depth.wrapping_add(1),
            index,
        ))
    }

    /// The public key for this signing key.
    #[inline]
    pub fn verifying_key(&self) -> VerifyingKey {
        self.signing_key.verifying_key()
    }

    /// Split a 64-byte HMAC output into `(key, chain_code)`.
    fn split(bytes: &[u8; 64], depth: u8, child_index: ChildIndex) -> Self {
        let mut key = Zeroizing::new([0u8; 32]);
        key.copy_from_slice(&bytes[..32]);

        let mut chain_code = [0u8; 32];
        chain_code.copy_from_slice(&bytes[32..]);

        Self {
            depth,
            child_index,
            signing_key: SigningKey::from_bytes(&key),
            chain_code,
        }
    }
}

impl Clone for ExtendedSigningKey {
    fn clone(&self) -> Self {
        Self {
            depth: self.depth,
            child_index: self.child_index,
            signing_key: SigningKey::from_bytes(self.signing_key.as_bytes()),
            chain_code: self.chain_code,
        }
    }
}

/// Redacted on purpose: the crate this replaces derived `Debug`, which prints
/// the private key bytes. Anything that logged an `ExtendedSigningKey` — or a
/// struct containing one — leaked a key into the log.
impl fmt::Debug for ExtendedSigningKey {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("ExtendedSigningKey")
            .field("depth", &self.depth)
            .field("child_index", &self.child_index)
            .field("signing_key", &"<redacted>")
            .field("chain_code", &"<redacted>")
            .finish()
    }
}

/// Take the 64-byte HMAC output into a zeroizing buffer.
///
/// The `finalize()` temporary is not itself zeroized (its type does not
/// implement `Zeroize`), but it dies at the end of this expression, and the
/// copy every caller actually holds is wiped on drop.
fn mac_output(mac: HmacSha512) -> Zeroizing<[u8; 64]> {
    let mut out = Zeroizing::new([0u8; 64]);
    out.copy_from_slice(&mac.finalize().into_bytes());
    out
}

#[cfg(test)]
mod tests {
    use super::*;

    fn hex32(s: &str) -> [u8; 32] {
        let v = hex::decode(s).expect("valid hex");
        v.try_into().expect("32 bytes")
    }

    fn root(seed_hex: &str) -> ExtendedSigningKey {
        ExtendedSigningKey::from_seed(&hex::decode(seed_hex).expect("valid hex")).expect("root key")
    }

    /// Assert one step of a published SLIP-0010 vector.
    fn assert_node(
        node: &ExtendedSigningKey,
        depth: u8,
        child_index: ChildIndex,
        chain_code: &str,
        secret: &str,
        public: &str,
    ) {
        assert_eq!(node.depth, depth, "depth");
        assert_eq!(node.child_index, child_index, "child index");
        assert_eq!(node.chain_code, hex32(chain_code), "chain code");
        assert_eq!(node.signing_key.to_bytes(), hex32(secret), "private key");
        assert_eq!(node.verifying_key().to_bytes(), hex32(public), "public key");
    }

    // ---------------------------------------------------------------------
    // Published SLIP-0010 test vectors for the ed25519 curve.
    // Source: https://github.com/satoshilabs/slips/blob/master/slip-0010.md
    // These are the permanent correctness oracle for this module.
    // ---------------------------------------------------------------------

    #[test]
    fn slip10_test_vector_1_ed25519() {
        let node = root("000102030405060708090a0b0c0d0e0f");
        assert_node(
            &node,
            0,
            ChildIndex::Normal(0),
            "90046a93de5380a72b5e45010748567d5ea02bbf6522f979e05c0d8d8ca9fffb",
            "2b4be7f19ee27bbf30c667b642d5f4aa69fd169872f8fc3059c08ebae2eb19e7",
            "a4b2856bfec510abab89753fac1ac0e1112364e7d250545963f135f2a33188ed",
        );

        let node = node.derive_child(ChildIndex::Hardened(0)).unwrap();
        assert_node(
            &node,
            1,
            ChildIndex::Hardened(0),
            "8b59aa11380b624e81507a27fedda59fea6d0b779a778918a2fd3590e16e9c69",
            "68e0fe46dfb67e368c75379acec591dad19df3cde26e63b93a8e704f1dade7a3",
            "8c8a13df77a28f3445213a0f432fde644acaa215fc72dcdf300d5efaa85d350c",
        );

        let node = node.derive_child(ChildIndex::Hardened(1)).unwrap();
        assert_node(
            &node,
            2,
            ChildIndex::Hardened(1),
            "a320425f77d1b5c2505a6b1b27382b37368ee640e3557c315416801243552f14",
            "b1d0bad404bf35da785a64ca1ac54b2617211d2777696fbffaf208f746ae84f2",
            "1932a5270f335bed617d5b935c80aedb1a35bd9fc1e31acafd5372c30f5c1187",
        );

        let node = node.derive_child(ChildIndex::Hardened(2)).unwrap();
        assert_node(
            &node,
            3,
            ChildIndex::Hardened(2),
            "2e69929e00b5ab250f49c3fb1c12f252de4fed2c1db88387094a0f8c4c9ccd6c",
            "92a5b23c0b8a99e37d07df3fb9966917f5d06e02ddbd909c7e184371463e9fc9",
            "ae98736566d30ed0e9d2f4486a64bc95740d89c7db33f52121f8ea8f76ff0fc1",
        );

        let node = node.derive_child(ChildIndex::Hardened(2)).unwrap();
        assert_node(
            &node,
            4,
            ChildIndex::Hardened(2),
            "8f6d87f93d750e0efccda017d662a1b31a266e4a6f5993b15f5c1f07f74dd5cc",
            "30d1dc7e5fc04c31219ab25a27ae00b50f6fd66622f6e9c913253d6511d1e662",
            "8abae2d66361c879b900d204ad2cc4984fa2aa344dd7ddc46007329ac76c429c",
        );

        let node = node.derive_child(ChildIndex::Hardened(1000000000)).unwrap();
        assert_node(
            &node,
            5,
            ChildIndex::Hardened(1000000000),
            "68789923a0cac2cd5a29172a475fe9e0fb14cd6adb5ad98a3fa70333e7afa230",
            "8f94d394a8e8fd6b1bc2f3f49f5c47e385281d5c17e65324b0f62483e37e8793",
            "3c24da049451555d51a7014a37337aa4e12d41e485abccfa46b47dfb2af54b7a",
        );
    }

    #[test]
    fn slip10_test_vector_2_ed25519() {
        let node = root(
            "fffcf9f6f3f0edeae7e4e1dedbd8d5d2cfccc9c6c3c0bdbab7b4b1aeaba8a5a29f9c99969390\
             8d8a8784817e7b7875726f6c696663605d5a5754514e4b484542",
        );
        assert_node(
            &node,
            0,
            ChildIndex::Normal(0),
            "ef70a74db9c3a5af931b5fe73ed8e1a53464133654fd55e7a66f8570b8e33c3b",
            "171cb88b1b3c1db25add599712e36245d75bc65a1a5c9e18d76f9f2b1eab4012",
            "8fe9693f8fa62a4305a140b9764c5ee01e455963744fe18204b4fb948249308a",
        );

        let node = node.derive_child(ChildIndex::Hardened(0)).unwrap();
        assert_node(
            &node,
            1,
            ChildIndex::Hardened(0),
            "0b78a3226f915c082bf118f83618a618ab6dec793752624cbeb622acb562862d",
            "1559eb2bbec5790b0c65d8693e4d0875b1747f4970ae8b650486ed7470845635",
            "86fab68dcb57aa196c77c5f264f215a112c22a912c10d123b0d03c3c28ef1037",
        );

        let node = node.derive_child(ChildIndex::Hardened(2147483647)).unwrap();
        assert_node(
            &node,
            2,
            ChildIndex::Hardened(2147483647),
            "138f0b2551bcafeca6ff2aa88ba8ed0ed8de070841f0c4ef0165df8181eaad7f",
            "ea4f5bfe8694d8bb74b7b59404632fd5968b774ed545e810de9c32a4fb4192f4",
            "5ba3b9ac6e90e83effcd25ac4e58a1365a9e35a3d3ae5eb07b9e4d90bcf7506d",
        );

        let node = node.derive_child(ChildIndex::Hardened(1)).unwrap();
        assert_node(
            &node,
            3,
            ChildIndex::Hardened(1),
            "73bd9fff1cfbde33a1b846c27085f711c0fe2d66fd32e139d3ebc28e5a4a6b90",
            "3757c7577170179c7868353ada796c839135b3d30554bbb74a4b1e4a5a58505c",
            "2e66aa57069c86cc18249aecf5cb5a9cebbfd6fadeab056254763874a9352b45",
        );

        let node = node.derive_child(ChildIndex::Hardened(2147483646)).unwrap();
        assert_node(
            &node,
            4,
            ChildIndex::Hardened(2147483646),
            "0902fe8a29f9140480a00ef244bd183e8a13288e4412d8389d140aac1794825a",
            "5837736c89570de861ebc173b1086da4f505d4adb387c6a1b1342d5e4ac9ec72",
            "e33c0f7d81d843c572275f287498e8d408654fdf0d1e065b84e2e6f157aab09b",
        );

        let node = node.derive_child(ChildIndex::Hardened(2)).unwrap();
        assert_node(
            &node,
            5,
            ChildIndex::Hardened(2),
            "5d70af781f3a37b829f0d060924d5e960bdc02e85423494afc0b1a41bbe196d4",
            "551d333177df541ad876a60ea71f00447931c0a9da16f227c11ea080d7391b8d",
            "47150c75db263559a70d5778bf36abbab30fb061ad69f69ece61a72b0cfa4fc0",
        );
    }

    /// Walking a whole `DerivationPath` must equal stepping child-by-child.
    #[test]
    fn derive_by_path_matches_stepwise_derivation() {
        let node = root("000102030405060708090a0b0c0d0e0f");

        let path: DerivationPath = "m/0'/1'/2'/2'/1000000000'".parse().unwrap();
        let by_path = node.derive(&path).unwrap();

        let mut stepwise = node.clone();
        for index in [0, 1, 2, 2, 1000000000] {
            stepwise = stepwise.derive_child(ChildIndex::Hardened(index)).unwrap();
        }

        assert_eq!(
            by_path.signing_key.to_bytes(),
            stepwise.signing_key.to_bytes()
        );
        assert_eq!(by_path.chain_code, stepwise.chain_code);
        assert_eq!(by_path.depth, 5);
    }

    #[test]
    fn the_empty_path_is_the_master_key() {
        let node = root("000102030405060708090a0b0c0d0e0f");
        let path: DerivationPath = "m".parse().unwrap();
        let derived = node.derive(&path).unwrap();

        assert_eq!(derived.signing_key.to_bytes(), node.signing_key.to_bytes());
        assert_eq!(derived.chain_code, node.chain_code);
        assert_eq!(derived.depth, 0);
    }

    // ---------------------------------------------------------------------
    // Hardened-only enforcement. Ed25519 cannot do public child derivation,
    // so a normal index must be an error and never a silent hardening.
    // ---------------------------------------------------------------------

    #[test]
    fn a_normal_child_index_is_refused() {
        let node = root("000102030405060708090a0b0c0d0e0f");

        assert!(matches!(
            node.derive_child(ChildIndex::Normal(0)),
            Err(Slip10Error::ExpectedHardenedIndex(ChildIndex::Normal(0)))
        ));
        assert!(matches!(
            node.derive_child(ChildIndex::Normal(100000)),
            Err(Slip10Error::ExpectedHardenedIndex(ChildIndex::Normal(
                100000
            )))
        ));
    }

    #[test]
    fn a_normal_index_mid_path_is_refused() {
        let node = root("000102030405060708090a0b0c0d0e0f");
        let soft_path: DerivationPath = "m/0'/1'/2'/3/4'".parse().unwrap();

        assert!(matches!(
            node.derive(&soft_path),
            Err(Slip10Error::ExpectedHardenedIndex(ChildIndex::Normal(3)))
        ));
    }

    // ---------------------------------------------------------------------
    // Seed handling.
    // ---------------------------------------------------------------------

    #[test]
    fn a_short_seed_is_refused() {
        let err = ExtendedSigningKey::from_seed(&[0u8; 15]).unwrap_err();
        assert!(matches!(
            err,
            Slip10Error::SeedTooShort { got: 15, min: 16 }
        ));
        // The floor itself is accepted.
        assert!(ExtendedSigningKey::from_seed(&[0u8; 16]).is_ok());
    }

    #[test]
    fn the_seed_lengths_this_workspace_actually_uses_are_accepted() {
        // 32 random bytes (`load_or_generate_seed`) and a 64-byte BIP-39 seed.
        assert!(ExtendedSigningKey::from_seed(&[7u8; 32]).is_ok());
        assert!(ExtendedSigningKey::from_seed(&[7u8; 64]).is_ok());
    }

    #[test]
    fn different_seeds_give_different_master_keys() {
        let a = ExtendedSigningKey::from_seed(&[1u8; 32]).unwrap();
        let b = ExtendedSigningKey::from_seed(&[2u8; 32]).unwrap();
        assert_ne!(a.signing_key.to_bytes(), b.signing_key.to_bytes());
        assert_ne!(a.chain_code, b.chain_code);
    }

    #[test]
    fn derivation_is_deterministic_across_calls() {
        let path: DerivationPath = "m/26'/2'/0'/1'".parse().unwrap();
        let first = ExtendedSigningKey::from_seed(&[9u8; 32])
            .unwrap()
            .derive(&path)
            .unwrap();
        let second = ExtendedSigningKey::from_seed(&[9u8; 32])
            .unwrap()
            .derive(&path)
            .unwrap();

        assert_eq!(first.signing_key.to_bytes(), second.signing_key.to_bytes());
        assert_eq!(first.chain_code, second.chain_code);
    }

    #[test]
    fn sibling_paths_give_independent_keys() {
        let root = ExtendedSigningKey::from_seed(&[3u8; 32]).unwrap();
        let a = root
            .derive(&"m/26'/2'/0'/0'".parse::<DerivationPath>().unwrap())
            .unwrap();
        let b = root
            .derive(&"m/26'/2'/0'/1'".parse::<DerivationPath>().unwrap())
            .unwrap();

        assert_ne!(a.signing_key.to_bytes(), b.signing_key.to_bytes());
        assert_ne!(a.chain_code, b.chain_code);
    }

    // ---------------------------------------------------------------------
    // Hygiene.
    // ---------------------------------------------------------------------

    #[test]
    fn clone_preserves_the_whole_node() {
        let node = root("000102030405060708090a0b0c0d0e0f")
            .derive_child(ChildIndex::Hardened(26))
            .unwrap();
        let cloned = node.clone();

        assert_eq!(cloned.depth, node.depth);
        assert_eq!(cloned.child_index, node.child_index);
        assert_eq!(cloned.chain_code, node.chain_code);
        assert_eq!(cloned.signing_key.to_bytes(), node.signing_key.to_bytes());
    }

    /// A key must never reach a log through `Debug`.
    #[test]
    fn debug_does_not_leak_key_material() {
        let node = root("000102030405060708090a0b0c0d0e0f");
        let rendered = format!("{node:?}");

        assert!(rendered.contains("<redacted>"));
        assert!(
            !rendered.contains("2b4be7f1"),
            "private key leaked into Debug output: {rendered}"
        );
        // The chain code is a derivation secret too.
        assert!(
            !rendered.contains("90046a93"),
            "chain code leaked into Debug output: {rendered}"
        );
    }
}