The key derivation function.
Given cryptographic key material of any length and a context string of any
length, this function outputs a derived subkey of any length. 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".
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 algorithms is generally forbidden, and deriving a separate subkey for each use case protects you from bad interactions. Derived keys also mitigate the damage from one part of your application accidentally leaking its key.
As a rare exception to that general rule, however, it is possible to use
derive_key itself with key material that you are already using with
another algorithm. You might need to do this if you’re adding features to
an existing application, which does not yet use key derivation internally.
However, you still must not share key material with algorithms that forbid
key reuse entirely, like a one-time pad.
Note that BLAKE3 is not a password hash, and
derive_key should never be
used with passwords. Instead, use a dedicated password hash like
Argon2. Password hashes are entirely different from generic hash
functions, with opposite design requirements.
This function is always single-threaded. For multi-threading support, see