Refactor to use "flat" path representation

Previously `Path` was represented as a slice of byte slices
(i.e. `&[&[u8]]`) and `PathBuf` as a `Vec<Vec<u8>>`.

These sorts of representations of paths preclude ever being able to impl
safe, non-allocating wrapper types, because there is not a safe
reference conversion from nested `Vec`s to nested slices.

This commit switches to using a 1-byte length prefix on each of the
components. This has the advantages of making reference types easier to
work with and also ensures a canonical wire serialization.

It places a max limit of 256-bytes on each path component, but this
is a reasonable upper bound.

The downside is this temporarily relies on an unsafe pointer conversion
to make everything work, however there is some discussion of how to make
this particular kind of reference conversion safe by means of safe
casting from reference types to transparent wrappers around them:

<https://internals.rust-lang.org/t/pre-rfc-patterns-allowing-transparent-wrapper-types/10229>

Author: tony-iqlusion

hkd32/Cargo.toml

@@ -33,8 +33,8 @@ features = ["zeroize_derive"]
 
 [features]
 default = ["alloc", "getrandom"]
-alloc = []
-mnemonic = ["tiny-bip39"]
+alloc = ["zeroize/alloc"]
+mnemonic = ["alloc", "tiny-bip39"]
 
 [package.metadata.docs.rs]
 all-features = true

hkd32/src/key_material.rs

@@ -0,0 +1,122 @@
+//! Cryptographic key material.
+//!
+//! Unlike traditional KDFs and XOFs, HKD32 acts on fixed-sized
+//! 256-bit (32-byte) keys.
+//!
+//! The `KeyMaterial` type is used to represent both input and output key
+//! material, and is the primary type useful for deriving other keys.
+
+#[cfg(feature = "mnemonic")]
+use crate::mnemonic;
+use crate::{path::Path, Error, KEY_SIZE};
+use core::convert::TryFrom;
+#[cfg(feature = "getrandom")]
+use getrandom::getrandom;
+use hmac::{Hmac, Mac};
+use sha2::Sha512;
+use zeroize::Zeroize;
+
+/// Cryptographic key material: 256-bit (32-byte) uniformly random bytestring
+/// generated either via a CSRNG or via hierarchical derivation.
+///
+/// This type provides the main key derivation functionality and is used to
+/// represent both input and output key material.
+#[derive(Clone, Zeroize)]
+#[zeroize(drop)]
+pub struct KeyMaterial([u8; KEY_SIZE]);
+
+impl KeyMaterial {
+    /// Create random key material using the operating system CSRNG
+    #[cfg(feature = "getrandom")]
+    pub fn random() -> Self {
+        let mut bytes = [0u8; KEY_SIZE];
+        getrandom(&mut bytes).expect("getrandom failure!");
+        Self::new(bytes)
+    }
+
+    /// Create key material from a 24-word BIP39 mnemonic phrase
+    #[cfg(feature = "mnemonic")]
+    pub fn from_mnemonic<S>(phrase: S, language: mnemonic::Language) -> Result<Self, Error>
+    where
+        S: AsRef<str>,
+    {
+        Ok(mnemonic::Phrase::new(phrase, language)?.into())
+    }
+
+    /// Create new key material from a byte slice.
+    ///
+    /// Byte slice is expected to have been generated by a cryptographically
+    /// secure random number generator.
+    pub fn from_bytes(slice: &[u8]) -> Result<Self, Error> {
+        if slice.len() == KEY_SIZE {
+            let mut bytes = [0u8; KEY_SIZE];
+            bytes.copy_from_slice(slice);
+            Ok(Self::new(bytes))
+        } else {
+            Err(Error)
+        }
+    }
+
+    /// Import existing key material - must be uniformly random!
+    pub fn new(bytes: [u8; KEY_SIZE]) -> KeyMaterial {
+        KeyMaterial(bytes)
+    }
+
+    /// Borrow the key material as a byte slice
+    pub fn as_bytes(&self) -> &[u8] {
+        &self.0
+    }
+
+    /// Derive an output key from the given input key material
+    pub fn derive_subkey<P>(self, path: P) -> Self
+    where
+        P: AsRef<Path>,
+    {
+        let component_count = path.as_ref().components().count();
+
+        path.as_ref()
+            .components()
+            .enumerate()
+            .fold(self, |parent_key, (i, component)| {
+                let mut hmac = Hmac::<Sha512>::new_varkey(parent_key.as_bytes()).unwrap();
+                hmac.input(component.as_bytes());
+
+                let mut hmac_result = hmac.result().code();
+                let (secret_key, chain_code) = hmac_result.split_at_mut(KEY_SIZE);
+                let mut child_key = [0u8; KEY_SIZE];
+
+                if i < component_count - 1 {
+                    // Use chain code for all but the last element
+                    child_key.copy_from_slice(chain_code);
+                } else {
+                    // Use secret key for the last element
+                    child_key.copy_from_slice(secret_key);
+                }
+
+                secret_key.zeroize();
+                chain_code.zeroize();
+
+                KeyMaterial(child_key)
+            })
+    }
+
+    /// Serialize this `KeyMaterial` as a BIP39 mnemonic phrase
+    #[cfg(feature = "mnemonic")]
+    pub fn to_mnemonic(&self, language: mnemonic::Language) -> mnemonic::Phrase {
+        mnemonic::Phrase::from_key_material(self, language)
+    }
+}
+
+impl From<[u8; KEY_SIZE]> for KeyMaterial {
+    fn from(bytes: [u8; KEY_SIZE]) -> Self {
+        Self::new(bytes)
+    }
+}
+
+impl<'a> TryFrom<&'a [u8]> for KeyMaterial {
+    type Error = Error;
+
+    fn try_from(slice: &'a [u8]) -> Result<Self, Error> {
+        Self::from_bytes(slice)
+    }
+}