mirror of
https://github.com/BLAKE3-team/BLAKE3
synced 2024-05-11 17:56:21 +02:00
C: rename blake3_hasher_init_derive_key_raw and documentation
This commit is contained in:
parent
31e4080aa2
commit
b205e0efa1
71
c/README.md
71
c/README.md
|
@ -103,30 +103,35 @@ Initialize a `blake3_hasher` in the keyed hashing mode. The key must be
|
||||||
exactly 32 bytes.
|
exactly 32 bytes.
|
||||||
|
|
||||||
```c
|
```c
|
||||||
void blake3_hasher_init_derive_key(
|
void blake3_hasher_init_derive_key_raw(
|
||||||
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(
|
|
||||||
blake3_hasher *self,
|
blake3_hasher *self,
|
||||||
const void *context,
|
const void *context,
|
||||||
size_t context_len);
|
size_t context_len);
|
||||||
```
|
```
|
||||||
|
|
||||||
Like `blake3_hasher_init_derive_key`, except the `context` and its
|
Initialize a `blake3_hasher` in the key derivation mode. Key material
|
||||||
length are given as separate parameters, and not together as a C string.
|
is to be given as input after initialization, using
|
||||||
This can be more convenient than the C string version when writing
|
`blake3_hasher_update`. The key derivation `context`
|
||||||
bindings to other languages.
|
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
|
```c
|
||||||
void blake3_hasher_finalize_seek(
|
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
|
efficiently stream a large output without allocating memory, call this
|
||||||
function in a loop, incrementing `seek` by the output length each time.
|
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
|
# Building
|
||||||
|
|
||||||
This implementation is just C and assembly files. It doesn't include a
|
This implementation is just C and assembly files. It doesn't include a
|
||||||
|
|
|
@ -367,7 +367,7 @@ void blake3_hasher_init_keyed(blake3_hasher *self,
|
||||||
hasher_init_base(self, key_words, KEYED_HASH);
|
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) {
|
size_t context_len) {
|
||||||
blake3_hasher context_hasher;
|
blake3_hasher context_hasher;
|
||||||
hasher_init_base(&context_hasher, IV, DERIVE_KEY_CONTEXT);
|
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) {
|
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
|
// As described in hasher_push_cv() below, we do "lazy merging", delaying
|
||||||
|
|
|
@ -42,7 +42,7 @@ void blake3_hasher_init(blake3_hasher *self);
|
||||||
void blake3_hasher_init_keyed(blake3_hasher *self,
|
void blake3_hasher_init_keyed(blake3_hasher *self,
|
||||||
const uint8_t key[BLAKE3_KEY_LEN]);
|
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(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);
|
size_t context_len);
|
||||||
void blake3_hasher_update(blake3_hasher *self, const void *input,
|
void blake3_hasher_update(blake3_hasher *self, const void *input,
|
||||||
size_t input_len);
|
size_t input_len);
|
||||||
|
|
Loading…
Reference in New Issue