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( - blake3_hasher *self, - const char *context); -``` - -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"`. - -```c -void blake3_hasher_init_derive_key_len( +void blake3_hasher_init_derive_key_raw( blake3_hasher *self, const void *context, size_t context_len); ``` -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. +Initialize a `blake3_hasher` in the key derivation mode. Key material +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( + blake3_hasher *self, + const char *context); +``` + +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);