C: rename blake3_hasher_init_derive_key_raw and documentation

3 files changed, 51 insertions, 18 deletions

diff --git a/c/README.md b/c/README.md
index 139ce2a..b341900 100644
--- a/c/README.md
+++ b/c/README.md
@@ -103,30 +103,35 @@ Initialize a `blake3_hasher` in the keyed hashing mode. The key must be
 exactly 32 bytes.
 
 ```c
-void blake3_hasher_init_derive_key(
+void blake3_hasher_init_derive_key_raw(
   blake3_hasher *self,
-  const char *context);
+  const void *context,
+  size_t context_len);
 ```
 
 Initialize a `blake3_hasher` in the key derivation mode. Key material
-should be given as input after initialization, using
-`blake3_hasher_update`. `context` is a standard null-terminated C string
-of any length.  The context string should be hardcoded, globally unique,
-and application-specific. A good default format for the context string
-is `"[application] [commit timestamp] [purpose]"`, e.g., `"example.com
-2019-12-25 16:18:03 session tokens v1"`.
+is to be given as input after initialization, using
+`blake3_hasher_update`. The key derivation `context` 
+should follow the __Key Derivation Context Guidelines__
+described below. `context_len` indicates the size of `context` in bytes.
 
 ```c
-void blake3_hasher_init_derive_key_len(
+void blake3_hasher_init_derive_key(
   blake3_hasher *self,
-  const void *context,
-  size_t context_len);
+  const char *context);
 ```
 
-Like `blake3_hasher_init_derive_key`, except the `context` and its 
-length are given as separate parameters, and not together as a C string.
-This can be more convenient than the C string version when writing 
-bindings to other languages.
+Similar to `blake3_hasher_init_derive_key_raw`, except it takes the key 
+derivation `context` as a null-terminated C string. 
+
+This function is offered as a convenience. It is recommended to use this 
+function when giving a literal, hardcoded C string as parameter.  
+
+Notice that contrary to `blake3_hasher_init_derive_key_raw`, this function
+cannot accept `context`s containing the byte `0x00` except as a the 
+terminating byte. For this reason, `blake3_hasher_init_derive_key_raw` is 
+preferred in more general contexts, such as when implementing bindings to 
+this C library.
 
 ```c
 void blake3_hasher_finalize_seek(
@@ -141,6 +146,34 @@ parameter for the starting byte position in the output stream. To
 efficiently stream a large output without allocating memory, call this
 function in a loop, incrementing `seek` by the output length each time.
 
+## Key Derivation Context Guidelines
+
+The key derivation context should uniquely describe the 
+application, place and purpose of the derivation.
+
+The context should be **statically known, 
+hardcoded, globally unique, and application-specific**.
+
+The context should not depend on any dynamic input such as salts, 
+nonces, or identifiers read from a database at runtime.
+
+A good format for the context string is:
+
+```
+[application] [commit timestamp] [purpose]
+```
+
+For example:
+
+```
+example.com 2019-12-25 16:18:03 session tokens v1
+```
+
+It's recommended that the context string consists of ASCII bytes 
+containing only alphanumeric characters, whitespace and punctuation. 
+However, any bytes are acceptable as long as they satisfy the 
+static constraints described above.
+
 # Building
 
 This implementation is just C and assembly files. It doesn't include a
diff --git a/c/blake3.c b/c/blake3.c
index c2823d1..71aed71 100644
--- a/c/blake3.c
+++ b/c/blake3.c
@@ -367,7 +367,7 @@ void blake3_hasher_init_keyed(blake3_hasher *self,
   hasher_init_base(self, key_words, KEYED_HASH);
 }
 
-void blake3_hasher_init_derive_key_len(blake3_hasher *self, const void *context, 
+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);
@@ -380,7 +380,7 @@ void blake3_hasher_init_derive_key_len(blake3_hasher *self, const void *context,
 }
 
 void blake3_hasher_init_derive_key(blake3_hasher *self, const char *context) {
-  blake3_hasher_init_derive_key_len(self, context, strlen(context));
+  blake3_hasher_init_derive_key_raw(self, context, strlen(context));
 }
 
 // As described in hasher_push_cv() below, we do "lazy merging", delaying
diff --git a/c/blake3.h b/c/blake3.h
index 292d002..51f1d2a 100644
--- a/c/blake3.h
+++ b/c/blake3.h
@@ -42,7 +42,7 @@ 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_len(blake3_hasher *self, const void *context, 
+void blake3_hasher_init_derive_key_raw(blake3_hasher *self, const void *context, 
                                        size_t context_len);
 void blake3_hasher_update(blake3_hasher *self, const void *input,
                           size_t input_len);