Merge pull request #230 from iqlusioninc/hkd32/bech32

hkd32: Add (optional) Bech32 encoding support

Author: tony-iqlusion

Cargo.lock

@@ -23,6 +23,7 @@ travis-ci = { repository = "iqlusioninc/crates", branch = "develop" }
 getrandom = { version = "0.1", optional = true }
 hmac = { version = "0.7", default-features = false }
 sha2 = { version = "0.8", default-features = false }
+subtle-encoding = { version = "0.3", optional = true }
 tiny-bip39 = { version = "0.6", default-features = false, optional = true }
 
 [dependencies.zeroize]
@@ -32,8 +33,9 @@ default-features = false
 features = ["zeroize_derive"]
 
 [features]
-default = ["alloc", "getrandom"]
+default = ["alloc", "bech32", "getrandom"]
 alloc = ["zeroize/alloc"]
+bech32 = ["alloc", "subtle-encoding/bech32-preview"]
 mnemonic = ["alloc", "tiny-bip39"]
 
 [package.metadata.docs.rs]

hkd32/Cargo.toml

@@ -9,12 +9,18 @@
 #[cfg(feature = "mnemonic")]
 use crate::mnemonic;
 use crate::{path::Path, Error, KEY_SIZE};
+#[cfg(feature = "bech32")]
+use alloc::string::String;
 use core::convert::TryFrom;
 #[cfg(feature = "getrandom")]
 use getrandom::getrandom;
 use hmac::{Hmac, Mac};
 use sha2::Sha512;
+#[cfg(feature = "bech32")]
+use subtle_encoding::bech32::Bech32;
 use zeroize::Zeroize;
+#[cfg(feature = "bech32")]
+use zeroize::Zeroizing;
 
 /// Cryptographic key material: 256-bit (32-byte) uniformly random bytestring
 /// generated either via a CSRNG or via hierarchical derivation.
@@ -34,6 +40,18 @@ impl KeyMaterial {
         Self::new(bytes)
     }
 
+    /// Decode key material from a Bech32 representation
+    #[cfg(feature = "bech32")]
+    pub fn from_bech32<S>(encoded: S) -> Result<(String, Self), Error>
+    where
+        S: AsRef<str>,
+    {
+        let (hrp, mut key_bytes) = Bech32::default().decode(encoded).map_err(|_| Error)?;
+        let key_result = Self::from_bytes(&key_bytes);
+        key_bytes.zeroize();
+        key_result.map(|key| (hrp, key))
+    }
+
     /// 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>
@@ -100,6 +118,16 @@ impl KeyMaterial {
             })
     }
 
+    /// Serialize this `KeyMaterial` as a self-zeroizing Bech32 string
+    #[cfg(feature = "bech32")]
+    pub fn to_bech32<S>(&self, hrp: S) -> Zeroizing<String>
+    where
+        S: AsRef<str>,
+    {
+        let b32 = Bech32::default().encode(hrp, self.as_bytes());
+        Zeroizing::new(b32)
+    }
+
     /// Serialize this `KeyMaterial` as a BIP39 mnemonic phrase
     #[cfg(feature = "mnemonic")]
     pub fn to_mnemonic(&self, language: mnemonic::Language) -> mnemonic::Phrase {

hkd32/src/key_material.rs

@@ -6,6 +6,29 @@
 //! This library implements a fully symmetric construction inspired by
 //! [BIP-0032: Hierarchical Deterministic Wallets][bip32].
 //!
+//! # Usage
+//!
+//! To derive a key using HKD32, you'll need the following:
+//!
+//! - `hkd32::KeyMaterial`: a 32-byte (256-bit) uniformly random value
+//! - `hkd32::Path` or `hkd32::PathBuf`: path to the child key
+//!
+//! Derivation paths can be raw bytestrings but also support
+//!
+//! # Example
+//!
+//! ```rust
+//! // Parent key
+//! let input_key_material = hkd32::KeyMaterial::random();
+//!
+//! // Path to the child key
+//! let derivation_path = "/foo/bar/baz".parse::<hkd32::PathBuf>().unwrap();
+//!
+//! // Derive subkey from the parent key. Call `as_bytes()` on this to obtain
+//! // a byte slice containing the derived key.
+//! let output_key_material = input_key_material.derive_subkey(derivation_path);
+//! ```
+//!
 //! [bip32]: https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki
 
 #![no_std]

hkd32/src/lib.rs

@@ -192,9 +192,15 @@ impl<'a> Component<'a> {
     /// Requires the `alloc` feature is enabled.
     #[cfg(feature = "alloc")]
     pub fn stringify(&self) -> Result<String, Error> {
-        str::from_utf8(self.as_bytes())
+        let s = str::from_utf8(self.as_bytes())
             .map(String::from)
-            .map_err(|_| Error)
+            .map_err(|_| Error)?;
+
+        if s.is_ascii() {
+            Ok(s)
+        } else {
+            Err(Error)
+        }
     }
 
     /// Serialize this component as a length-prefixed bytestring.

hkd32/src/path.rs

@@ -117,6 +117,10 @@ impl FromStr for PathBuf {
         }
 
         for component in components {
+            if !component.is_ascii() {
+                return Err(Error);
+            }
+
             result.push(Component::new(component.as_bytes())?);
         }