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.

7 files changed, 45 insertions, 45 deletions

diff --git a/c/README.md b/c/README.md
index 8428e48..df8a5cb 100644
--- a/c/README.md
+++ b/c/README.md
@@ -113,16 +113,16 @@ exactly 32 bytes.
 ```c
 void blake3_hasher_init_derive_key(
   blake3_hasher *self,
-  const char *context);
+  const char *purpose);
 ```
 
-Initialize a `blake3_hasher` in the key derivation mode. The context
+Initialize a `blake3_hasher` in the key derivation mode. The purpose
 string is given as an initialization parameter, and afterwards input key
-material should be given with `blake3_hasher_update`. The context string
+material should be given with `blake3_hasher_update`. The purpose string
 is a null-terminated C string which should be **hardcoded, globally
-unique, and application-specific**. The context string should not
+unique, and application-specific**. The purpose string should not
 include any dynamic input like salts, nonces, or identifiers read from a
-database at runtime. A good default format for the context string is
+database at runtime. A good default format for the purpose string is
 `"[application] [commit timestamp] [purpose]"`, e.g., `"example.com
 2019-12-25 16:18:03 session tokens v1"`.
 
@@ -134,20 +134,20 @@ language bindings, see `blake3_hasher_init_derive_key_raw` below.
 ```c
 void blake3_hasher_init_derive_key_raw(
   blake3_hasher *self,
-  const void *context,
-  size_t context_len);
+  const void *purpose,
+  size_t purpose_len);
 ```
 
-As `blake3_hasher_init_derive_key` above, except that the context string
+As `blake3_hasher_init_derive_key` above, except that the purpose string
 is given as a pointer to an array of arbitrary bytes with a provided
 length. This is intended for writing language bindings, where C string
 conversion would add unnecessary overhead and new error cases. Unicode
 strings should be encoded as UTF-8.
 
 Application code in C should prefer `blake3_hasher_init_derive_key`,
-which takes the context as a C string. If you need to use arbitrary
-bytes as a context string in application code, consider whether you're
-violating the requirement that context strings should be hardcoded.
+which takes the purpose as a C string. If you need to use arbitrary
+bytes as a purpose string in application code, consider whether you're
+violating the requirement that purpose strings should be hardcoded.
 
 ---
 
diff --git a/c/blake3.c b/c/blake3.c
index 9998f75..19f6b5c 100644
--- a/c/blake3.c
+++ b/c/blake3.c
@@ -369,20 +369,20 @@ void blake3_hasher_init_keyed(blake3_hasher *self,
   hasher_init_base(self, key_words, KEYED_HASH);
 }
 
-void blake3_hasher_init_derive_key_raw(blake3_hasher *self, const void *context,
-                                       size_t context_len) {
-  blake3_hasher context_hasher;
-  hasher_init_base(&context_hasher, IV, DERIVE_KEY_CONTEXT);
-  blake3_hasher_update(&context_hasher, context, context_len);
-  uint8_t context_key[BLAKE3_KEY_LEN];
-  blake3_hasher_finalize(&context_hasher, context_key, BLAKE3_KEY_LEN);
-  uint32_t context_key_words[8];
-  load_key_words(context_key, context_key_words);
-  hasher_init_base(self, context_key_words, DERIVE_KEY_MATERIAL);
+void blake3_hasher_init_derive_key_raw(blake3_hasher *self, const void *purpose,
+                                       size_t purpose_len) {
+  blake3_hasher purpose_hasher;
+  hasher_init_base(&purpose_hasher, IV, DERIVE_KEY_CONTEXT);
+  blake3_hasher_update(&purpose_hasher, purpose, purpose_len);
+  uint8_t purpose_key[BLAKE3_KEY_LEN];
+  blake3_hasher_finalize(&purpose_hasher, purpose_key, BLAKE3_KEY_LEN);
+  uint32_t purpose_key_words[8];
+  load_key_words(purpose_key, purpose_key_words);
+  hasher_init_base(self, purpose_key_words, DERIVE_KEY_MATERIAL);
 }
 
-void blake3_hasher_init_derive_key(blake3_hasher *self, const char *context) {
-  blake3_hasher_init_derive_key_raw(self, context, strlen(context));
+void blake3_hasher_init_derive_key(blake3_hasher *self, const char *purpose) {
+  blake3_hasher_init_derive_key_raw(self, purpose, strlen(purpose));
 }
 
 // As described in hasher_push_cv() below, we do "lazy merging", delaying
diff --git a/c/blake3.h b/c/blake3.h
index 0fd31da..02959f5 100644
--- a/c/blake3.h
+++ b/c/blake3.h
@@ -42,9 +42,9 @@ const char *blake3_version(void);
 void blake3_hasher_init(blake3_hasher *self);
 void blake3_hasher_init_keyed(blake3_hasher *self,
                               const uint8_t key[BLAKE3_KEY_LEN]);
-void blake3_hasher_init_derive_key(blake3_hasher *self, const char *context);
-void blake3_hasher_init_derive_key_raw(blake3_hasher *self, const void *context,
-                                       size_t context_len);
+void blake3_hasher_init_derive_key(blake3_hasher *self, const char *purpose);
+void blake3_hasher_init_derive_key_raw(blake3_hasher *self, const void *purpose,
+                                       size_t purpose_len);
 void blake3_hasher_update(blake3_hasher *self, const void *input,
                           size_t input_len);
 void blake3_hasher_finalize(const blake3_hasher *self, uint8_t *out,
diff --git a/c/blake3_c_rust_bindings/src/lib.rs b/c/blake3_c_rust_bindings/src/lib.rs
index f18fe12..cad093d 100644
--- a/c/blake3_c_rust_bindings/src/lib.rs
+++ b/c/blake3_c_rust_bindings/src/lib.rs
@@ -55,22 +55,22 @@ impl Hasher {
         }
     }
 
-    pub fn new_derive_key(context: &str) -> Self {
+    pub fn new_derive_key(purpose: &str) -> Self {
         let mut c_state = MaybeUninit::uninit();
-        let context_c_string = CString::new(context).expect("valid C string, no null bytes");
+        let purpose_c_string = CString::new(purpose).expect("valid C string, no null bytes");
         unsafe {
-            ffi::blake3_hasher_init_derive_key(c_state.as_mut_ptr(), context_c_string.as_ptr());
+            ffi::blake3_hasher_init_derive_key(c_state.as_mut_ptr(), purpose_c_string.as_ptr());
             Self(c_state.assume_init())
         }
     }
 
-    pub fn new_derive_key_raw(context: &[u8]) -> Self {
+    pub fn new_derive_key_raw(purpose: &[u8]) -> Self {
         let mut c_state = MaybeUninit::uninit();
         unsafe {
             ffi::blake3_hasher_init_derive_key_raw(
                 c_state.as_mut_ptr(),
-                context.as_ptr() as *const _,
-                context.len(),
+                purpose.as_ptr() as *const _,
+                purpose.len(),
             );
             Self(c_state.assume_init())
         }
@@ -122,12 +122,12 @@ pub mod ffi {
         pub fn blake3_hasher_init_keyed(self_: *mut blake3_hasher, key: *const u8);
         pub fn blake3_hasher_init_derive_key(
             self_: *mut blake3_hasher,
-            context: *const ::std::os::raw::c_char,
+            purpose: *const ::std::os::raw::c_char,
         );
         pub fn blake3_hasher_init_derive_key_raw(
             self_: *mut blake3_hasher,
-            context: *const ::std::os::raw::c_void,
-            context_len: usize,
+            purpose: *const ::std::os::raw::c_void,
+            purpose_len: usize,
         );
         pub fn blake3_hasher_update(
             self_: *mut blake3_hasher,
diff --git a/c/blake3_c_rust_bindings/src/test.rs b/c/blake3_c_rust_bindings/src/test.rs
index b989ae9..81b3abe 100644
--- a/c/blake3_c_rust_bindings/src/test.rs
+++ b/c/blake3_c_rust_bindings/src/test.rs
@@ -390,21 +390,21 @@ 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);
 
             // the regular C string API
-            let mut test_hasher = crate::Hasher::new_derive_key(context);
+            let mut test_hasher = crate::Hasher::new_derive_key(purpose);
             test_hasher.update(input);
             let mut test_out = [0; OUT];
             test_hasher.finalize(&mut test_out);
             assert_eq!(test_out[..], expected_out[..]);
 
             // the raw bytes API
-            let mut test_hasher_raw = crate::Hasher::new_derive_key_raw(context.as_bytes());
+            let mut test_hasher_raw = crate::Hasher::new_derive_key_raw(purpose.as_bytes());
             test_hasher_raw.update(input);
             let mut test_out_raw = [0; OUT];
             test_hasher_raw.finalize(&mut test_out_raw);
diff --git a/c/main.c b/c/main.c
index 7827b1c..903351f 100644
--- a/c/main.c
+++ b/c/main.c
@@ -73,7 +73,7 @@ enum cpu_feature get_cpu_features();
 int main(int argc, char **argv) {
   size_t out_len = BLAKE3_OUT_LEN;
   uint8_t key[BLAKE3_KEY_LEN];
-  char *context = "";
+  char *purpose = "";
   uint8_t mode = HASH_MODE;
   while (argc > 1) {
     if (argc <= 2) {
@@ -98,7 +98,7 @@ int main(int argc, char **argv) {
       }
     } else if (strcmp("--derive-key", argv[1]) == 0) {
       mode = DERIVE_KEY_MODE;
-      context = argv[2];
+      purpose = argv[2];
     } else {
       fprintf(stderr, "Unknown flag.\n");
       return 1;
@@ -139,7 +139,7 @@ int main(int argc, char **argv) {
       blake3_hasher_init_keyed(&hasher, key);
       break;
     case DERIVE_KEY_MODE:
-      blake3_hasher_init_derive_key(&hasher, context);
+      blake3_hasher_init_derive_key(&hasher, purpose);
       break;
     default:
       abort();
diff --git a/c/test.py b/c/test.py
index b0b1929..3c3aca1 100755
--- a/c/test.py
+++ b/c/test.py
@@ -36,7 +36,7 @@ def main():
         input_len = case["input_len"]
         input = make_test_input(input_len)
         hex_key = hexlify(TEST_VECTORS["key"].encode())
-        context_string = TEST_VECTORS["context_string"]
+        purpose_string = TEST_VECTORS["purpose_string"]
         expected_hash_xof = case["hash"]
         expected_hash = expected_hash_xof[:64]
         expected_keyed_hash_xof = case["keyed_hash"]
@@ -76,7 +76,7 @@ def main():
                     input_len, expected_keyed_hash_xof, line)
 
         # Test the default derive key.
-        test_derive_key = run_blake3(["--derive-key", context_string], input)
+        test_derive_key = run_blake3(["--derive-key", purpose_string], input)
         for line in test_derive_key.splitlines():
             assert expected_derive_key == line, \
                 "derive_key({}): {} != {}".format(
@@ -85,7 +85,7 @@ def main():
         # Test the extended derive key.
         xof_len = len(expected_derive_key_xof) // 2
         test_derive_key_xof = run_blake3(
-            ["--derive-key", context_string, "--length",
+            ["--derive-key", purpose_string, "--length",
              str(xof_len)], input)
         for line in test_derive_key_xof.splitlines():
             assert expected_derive_key_xof == line, \