From 31ee7c0ae34af040d9d87adeeb06b0a08e353654 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Philipp=20Kr=C3=BCger?= <philipp.krueger1@gmail.com>
Date: Mon, 17 Jul 2023 16:37:32 +0200
Subject: [PATCH] Use `derive_key` algorithm from blake3 for domain separation

---
 src/ratchet.rs | 36 ++++++++++++++++++------------------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/src/ratchet.rs b/src/ratchet.rs
index b05a3c6..3219a4a 100644
--- a/src/ratchet.rs
+++ b/src/ratchet.rs
@@ -102,15 +102,18 @@ impl Ratchet {
     /// use blake3::traits::digest::Digest;
     ///
     /// let ratchet = Ratchet::from_rng(&mut rand::thread_rng());
-    /// let key: [u8; 32] = ratchet.derive_key("awesome.ly temporal key derivation").finalize().into();
+    /// let key: [u8; 32] = ratchet.derive_key("awesome.ly 2023 encryption key derivation").finalize().into();
     /// ```
-    pub fn derive_key(&self, domain_separation_info: impl AsRef<[u8]>) -> blake3::Hasher {
-        let mut hasher = blake3::Hasher::new();
-        self.derive_key_with(domain_separation_info, &mut hasher);
+    pub fn derive_key(&self, domain_separation_info: &str) -> blake3::Hasher {
+        let mut hasher = blake3::Hasher::new_derive_key(domain_separation_info);
+        self.derive_key_with(&mut hasher);
         hasher
     }
 
-    /// Derives a new key from the ratchet using given hashing algorithm.
+    /// Hashes the ratchet into given hashing algorithm.
+    ///
+    /// If used for key derivation, consider adding a domain separation string
+    /// to the hash, as seen in the example.
     ///
     /// # Examples
     ///
@@ -119,20 +122,15 @@ impl Ratchet {
     /// use blake3::traits::digest::Digest;
     ///
     /// let ratchet = Ratchet::from_rng(&mut rand::thread_rng());
-    /// let dsi = "awesome.ly temporal key derivation";
-    /// let mut hasher = blake3::Hasher::new();
-    /// ratchet.derive_key_with(dsi, &mut hasher);
+    /// let dsi = "awesome.ly 2023 encryption key derivation";
+    /// let mut hasher = blake3::Hasher::new_derive_key(dsi);
+    /// ratchet.derive_key_with(&mut hasher);
     /// let key: [u8; 32] = hasher.finalize().into();
     /// let key2: [u8; 32] = ratchet.derive_key(dsi).finalize().into();
     /// assert_eq!(key2, key);
     /// ```
-    pub fn derive_key_with(
-        &self,
-        domain_separation_info: impl AsRef<[u8]>,
-        hasher: &mut impl Digest,
-    ) {
+    pub fn derive_key_with(&self, hasher: &mut impl Digest) {
         // Minimally fewer allocations than using `self.key_derivation_data()`.
-        hasher.update(domain_separation_info);
         hasher.update(self.large);
         hasher.update(self.medium);
         hasher.update(self.small);
@@ -142,23 +140,25 @@ impl Ratchet {
     ///
     /// Can be useful for hashing using algorithms other than Blake3 for the final key derivation.
     ///
+    /// Please consider separating the domain the key is used for by using a keyed hashing function,
+    /// see the example.
+    ///
     /// # Examples
     ///
     /// ```
     /// use skip_ratchet::Ratchet;
     /// use blake3::traits::digest::Digest;
     ///
-    /// let dsi = "awesome.ly key derivation 2023";
+    /// let dsi = "awesome.ly 2023 encryption key derivation";
     /// let ratchet = Ratchet::from_rng(&mut rand::thread_rng());
     ///
     /// let key: [u8; 32] = ratchet.derive_key(dsi).finalize().into();
-    /// let key2: [u8; 32] = blake3::Hasher::new().chain_update(ratchet.key_derivation_data(dsi)).finalize().into();
+    /// let key2: [u8; 32] = blake3::Hasher::new_derive_key(dsi).chain_update(ratchet.key_derivation_data()).finalize().into();
     ///
     /// assert_eq!(key, key2);
     /// ```
-    pub fn key_derivation_data(&self, domain_separation_info: impl AsRef<[u8]>) -> Vec<u8> {
+    pub fn key_derivation_data(&self) -> Vec<u8> {
         let mut vec = Vec::new();
-        vec.extend(domain_separation_info.as_ref());
         vec.extend(self.large.as_ref());
         vec.extend(self.medium.as_ref());
         vec.extend(self.small.as_ref());