make derive_key() return an array

2 files changed, 31 insertions, 30 deletions

diff --git a/src/lib.rs b/src/lib.rs
index 9869ebb..c620bbf 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -788,29 +788,31 @@ fn hash_all_at_once(input: &[u8], key: &CVWords, flags: u8) -> Output {
 
 /// The default hash function.
 ///
-/// For an incremental version that accepts multiple writes, see [`Hasher::update`].
+/// For an incremental version that accepts multiple writes, see
+/// [`Hasher::update`].
+///
+/// For output sizes other than 32 bytes, see [`Hasher::finalize_xof`] and
+/// [`OutputReader`].
 ///
 /// This function is always single-threaded. For multi-threading support, see
 /// [`Hasher::update_with_join`].
-///
-/// [`Hasher::update`]: struct.Hasher.html#method.update
-/// [`Hasher::update_with_join`]: struct.Hasher.html#method.update_with_join
 pub fn hash(input: &[u8]) -> Hash {
     hash_all_at_once(input, IV, 0).root_hash()
 }
 
 /// The keyed hash function.
 ///
-/// This is suitable for use as a message authentication code, for
-/// example to replace an HMAC instance.
-///  In that use case, the constant-time equality checking provided by
-/// [`Hash`](struct.Hash.html) is almost always a security requirement, and
-/// callers need to be careful not to compare MACs as raw bytes.
+/// This is suitable for use as a message authentication code, for example to
+/// replace an HMAC instance. In that use case, the constant-time equality
+/// checking provided by [`Hash`](struct.Hash.html) is almost always a security
+/// requirement, and callers need to be careful not to compare MACs as raw
+/// bytes.
+///
+/// For output sizes other than 32 bytes, see [`Hasher::new_keyed`],
+/// [`Hasher::finalize_xof`], and [`OutputReader`].
 ///
 /// This function is always single-threaded. For multi-threading support, see
 /// [`Hasher::update_with_join`].
-///
-/// [`Hasher::update_with_join`]: struct.Hasher.html#method.update_with_join
 pub fn keyed_hash(key: &[u8; KEY_LEN], input: &[u8]) -> Hash {
     let key_words = platform::words_from_le_bytes_32(key);
     hash_all_at_once(input, &key_words, KEYED_HASH).root_hash()
@@ -819,9 +821,9 @@ pub fn keyed_hash(key: &[u8; KEY_LEN], input: &[u8]) -> Hash {
 /// The key derivation function.
 ///
 /// Given cryptographic key material of any length and a context string of any
-/// length, this function outputs a derived subkey of any length. **The context
-/// string should be hardcoded, globally unique, and application-specific.** A
-/// good default format for such strings is `"[application] [commit timestamp]
+/// length, this function outputs a 32-byte derived subkey. **The context string
+/// should be hardcoded, globally unique, and application-specific.** A good
+/// default format for such strings is `"[application] [commit timestamp]
 /// [purpose]"`, e.g., `"example.com 2019-12-25 16:18:03 session tokens v1"`.
 ///
 /// Key derivation is important when you want to use the same key in multiple
@@ -842,18 +844,19 @@ pub fn keyed_hash(key: &[u8; KEY_LEN], input: &[u8]) -> Hash {
 /// [Argon2]. Password hashes are entirely different from generic hash
 /// functions, with opposite design requirements.
 ///
+/// For output sizes other than 32 bytes, see [`Hasher::new_derive_key`],
+/// [`Hasher::finalize_xof`], and [`OutputReader`].
+///
 /// This function is always single-threaded. For multi-threading support, see
 /// [`Hasher::update_with_join`].
 ///
-/// [`Hasher::new_derive_key`]: struct.Hasher.html#method.new_derive_key
-/// [`Hasher::finalize_xof`]: struct.Hasher.html#method.finalize_xof
 /// [Argon2]: https://en.wikipedia.org/wiki/Argon2
-/// [`Hasher::update_with_join`]: struct.Hasher.html#method.update_with_join
-pub fn derive_key(context: &str, key_material: &[u8], output: &mut [u8]) {
+pub fn derive_key(context: &str, key_material: &[u8]) -> [u8; OUT_LEN] {
     let context_key = hash_all_at_once(context.as_bytes(), IV, DERIVE_KEY_CONTEXT).root_hash();
     let context_key_words = platform::words_from_le_bytes_32(context_key.as_bytes());
-    let inner_output = hash_all_at_once(key_material, &context_key_words, DERIVE_KEY_MATERIAL);
-    OutputReader::new(inner_output).fill(output);
+    hash_all_at_once(key_material, &context_key_words, DERIVE_KEY_MATERIAL)
+        .root_hash()
+        .0
 }
 
 fn parent_node_output(
diff --git a/src/test.rs b/src/test.rs
index cd46091..7e9fd42 100644
--- a/src/test.rs
+++ b/src/test.rs
@@ -284,7 +284,7 @@ fn test_compare_reference_impl() {
 
             // all at once
             let test_out = crate::hash(input);
-            assert_eq!(test_out, *array_ref!(expected_out, 0, 32));
+            assert_eq!(test_out, expected_out[..32]);
             // incremental
             let mut hasher = crate::Hasher::new();
             hasher.update(input);
@@ -293,7 +293,7 @@ fn test_compare_reference_impl() {
             // xof
             let mut extended = [0; OUT];
             hasher.finalize_xof().fill(&mut extended);
-            assert_eq!(extended[..], expected_out[..]);
+            assert_eq!(extended, expected_out);
         }
 
         // keyed
@@ -305,7 +305,7 @@ fn test_compare_reference_impl() {
 
             // all at once
             let test_out = crate::keyed_hash(&TEST_KEY, input);
-            assert_eq!(test_out, *array_ref!(expected_out, 0, 32));
+            assert_eq!(test_out, expected_out[..32]);
             // incremental
             let mut hasher = crate::Hasher::new_keyed(&TEST_KEY);
             hasher.update(input);
@@ -314,7 +314,7 @@ fn test_compare_reference_impl() {
             // xof
             let mut extended = [0; OUT];
             hasher.finalize_xof().fill(&mut extended);
-            assert_eq!(extended[..], expected_out[..]);
+            assert_eq!(extended, expected_out);
         }
 
         // derive_key
@@ -326,9 +326,8 @@ fn test_compare_reference_impl() {
             reference_hasher.finalize(&mut expected_out);
 
             // all at once
-            let mut test_out = [0; OUT];
-            crate::derive_key(context, input, &mut test_out);
-            assert_eq!(test_out[..], expected_out[..]);
+            let test_out = crate::derive_key(context, input);
+            assert_eq!(test_out[..], expected_out[..32]);
             // incremental
             let mut hasher = crate::Hasher::new_derive_key(context);
             hasher.update(input);
@@ -337,7 +336,7 @@ fn test_compare_reference_impl() {
             // xof
             let mut extended = [0; OUT];
             hasher.finalize_xof().fill(&mut extended);
-            assert_eq!(extended[..], expected_out[..]);
+            assert_eq!(extended, expected_out);
         }
     }
 }
@@ -501,8 +500,7 @@ fn test_reset() {
     kdf.update(&[42; 3 * CHUNK_LEN + 7]);
     kdf.reset();
     kdf.update(&[42; CHUNK_LEN + 3]);
-    let mut expected = [0; crate::OUT_LEN];
-    crate::derive_key(context, &[42; CHUNK_LEN + 3], &mut expected);
+    let expected = crate::derive_key(context, &[42; CHUNK_LEN + 3]);
     assert_eq!(kdf.finalize(), expected);
 }