rename the "context string" to the "purpose string"purpose_string

Apart from being pretty ambiguous in general, the term "context string"
has the specific problem that it isn't clear whether it should be
describing the input or the output. In fact, it's quite important that
it describes the output, because the whole point is to domain-separate
different outputs that derive from the *same* input. To make that
clearer, rename the "context string" to the "purpose string" in
documentation.

2 files changed, 22 insertions, 22 deletions

diff --git a/src/lib.rs b/src/lib.rs
index c620bbf..5e6d6c6 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -820,11 +820,11 @@ 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 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"`.
+/// Given a purpose string of any length and key material of any length, this
+/// function outputs a 32-byte derived subkey. **The purpose 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
 /// algorithms or use cases. Using the same key with different cryptographic
@@ -851,10 +851,10 @@ pub fn keyed_hash(key: &[u8; KEY_LEN], input: &[u8]) -> Hash {
 /// [`Hasher::update_with_join`].
 ///
 /// [Argon2]: https://en.wikipedia.org/wiki/Argon2
-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());
-    hash_all_at_once(key_material, &context_key_words, DERIVE_KEY_MATERIAL)
+pub fn derive_key(purpose: &str, key_material: &[u8]) -> [u8; OUT_LEN] {
+    let purpose_key = hash_all_at_once(purpose.as_bytes(), IV, DERIVE_KEY_CONTEXT).root_hash();
+    let purpose_key_words = platform::words_from_le_bytes_32(purpose_key.as_bytes());
+    hash_all_at_once(key_material, &purpose_key_words, DERIVE_KEY_MATERIAL)
         .root_hash()
         .0
 }
@@ -950,20 +950,20 @@ impl Hasher {
     }
 
     /// Construct a new `Hasher` for the key derivation function. See
-    /// [`derive_key`]. The context string should be hardcoded, globally
+    /// [`derive_key`]. The purpose string should be hardcoded, globally
     /// unique, and application-specific.
     ///
     /// [`derive_key`]: fn.derive_key.html
-    pub fn new_derive_key(context: &str) -> Self {
-        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());
-        Self::new_internal(&context_key_words, DERIVE_KEY_MATERIAL)
+    pub fn new_derive_key(purpose: &str) -> Self {
+        let purpose_key = hash_all_at_once(purpose.as_bytes(), IV, DERIVE_KEY_CONTEXT).root_hash();
+        let purpose_key_words = platform::words_from_le_bytes_32(purpose_key.as_bytes());
+        Self::new_internal(&purpose_key_words, DERIVE_KEY_MATERIAL)
     }
 
     /// Reset the `Hasher` to its initial state.
     ///
     /// This is functionally the same as overwriting the `Hasher` with a new
-    /// one, using the same key or context string if any. However, depending on
+    /// one, using the same key or purpose string if any. However, depending on
     /// how much inlining the optimizer does, moving a `Hasher` might copy its
     /// entire CV stack, most of which is useless uninitialized bytes. This
     /// methods avoids that copy.
diff --git a/src/test.rs b/src/test.rs
index 7e9fd42..5a4a1ac 100644
--- a/src/test.rs
+++ b/src/test.rs
@@ -319,17 +319,17 @@ fn test_compare_reference_impl() {
 
         // derive_key
         {
-            let context = "BLAKE3 2019-12-27 16:13:59 example context (not the test vector one)";
-            let mut reference_hasher = reference_impl::Hasher::new_derive_key(context);
+            let purpose = "BLAKE3 2019-12-27 16:13:59 example context (not the test vector one)";
+            let mut reference_hasher = reference_impl::Hasher::new_derive_key(purpose);
             reference_hasher.update(input);
             let mut expected_out = [0; OUT];
             reference_hasher.finalize(&mut expected_out);
 
             // all at once
-            let test_out = crate::derive_key(context, input);
+            let test_out = crate::derive_key(purpose, input);
             assert_eq!(test_out[..], expected_out[..32]);
             // incremental
-            let mut hasher = crate::Hasher::new_derive_key(context);
+            let mut hasher = crate::Hasher::new_derive_key(purpose);
             hasher.update(input);
             assert_eq!(hasher.finalize(), *array_ref!(expected_out, 0, 32));
             assert_eq!(hasher.finalize(), *array_ref!(test_out, 0, 32));
@@ -495,12 +495,12 @@ fn test_reset() {
         crate::keyed_hash(key, &[42; CHUNK_LEN + 3]),
     );
 
-    let context = "BLAKE3 2020-02-12 10:20:58 reset test";
-    let mut kdf = crate::Hasher::new_derive_key(context);
+    let purpose = "BLAKE3 2020-02-12 10:20:58 reset test";
+    let mut kdf = crate::Hasher::new_derive_key(purpose);
     kdf.update(&[42; 3 * CHUNK_LEN + 7]);
     kdf.reset();
     kdf.update(&[42; CHUNK_LEN + 3]);
-    let expected = crate::derive_key(context, &[42; CHUNK_LEN + 3]);
+    let expected = crate::derive_key(purpose, &[42; CHUNK_LEN + 3]);
     assert_eq!(kdf.finalize(), expected);
 }