libsodium_crypto_kdf_hkdf_sha256 (libsodium v3.0.1)
View SourceHKDF (RFC 5869) with
HMAC-SHA-256. extract/2 condenses input keying material, such as a
Diffie-Hellman shared secret, and an optional salt into a keybytes/0
byte pseudorandom key (PRK); expand/3 then derives up to bytes_max/0
bytes from the PRK for each context. A uniformly random key, such as one
from keygen/0, can be used as the PRK directly.
The extraction can also be streamed: extract_init/1,
extract_update/2, and extract_final/1 thread an opaque state/0,
and each call returns a new state and leaves its argument unchanged.
HKDF is mainly useful for interoperability with existing protocols. To
derive subkeys from a uniformly random key, libsodium_crypto_kdf is
simpler; to derive keys from passwords, use libsodium_crypto_pwhash.
PRK = libsodium_crypto_kdf_hkdf_sha256:extract(<<"salt">>, <<"input keying material">>),
32 = byte_size(PRK),
Key1 = libsodium_crypto_kdf_hkdf_sha256:expand(32, <<"encryption key">>, PRK),
Key2 = libsodium_crypto_kdf_hkdf_sha256:expand(32, <<"authentication key">>, PRK),
true = Key1 =/= Key2,
State0 = libsodium_crypto_kdf_hkdf_sha256:extract_init(<<"salt">>),
State1 = libsodium_crypto_kdf_hkdf_sha256:extract_update(State0, <<"input keying ">>),
State2 = libsodium_crypto_kdf_hkdf_sha256:extract_update(State1, <<"material">>),
PRK = libsodium_crypto_kdf_hkdf_sha256:extract_final(State2).Summary
Types
A crypto_kdf_hkdf_sha256_KEYBYTES (32-byte) binary.
An opaque native crypto_kdf_hkdf_sha256_state.
Functions
Return crypto_kdf_hkdf_sha256_bytes_max(), in bytes.
Return crypto_kdf_hkdf_sha256_bytes_min(), in bytes.
Derive OutLen bytes from the keybytes/0 byte pseudorandom key PRK
for the context Ctx (default empty).
Derive OutLen bytes from the keybytes/0 byte pseudorandom key PRK
for the context Ctx (default empty).
Extract a keybytes/0 byte pseudorandom key from the input keying
material IKM and the optional Salt (default empty).
Extract a keybytes/0 byte pseudorandom key from the input keying
material IKM and the optional Salt (default empty).
Finish the streaming extraction in State, returning a keybytes/0 byte pseudorandom key.
Start a streaming extraction with the optional Salt (default empty) and return its state.
Start a streaming extraction with the optional Salt (default empty) and return its state.
Absorb the input keying material IKM into State and return the updated state.
Return crypto_kdf_hkdf_sha256_keybytes(), in bytes.
Generate a random keybytes/0 byte pseudorandom key.
Return crypto_kdf_hkdf_sha256_statebytes(), in bytes.
Types
-type prk() :: <<_:256>>.
A crypto_kdf_hkdf_sha256_KEYBYTES (32-byte) binary.
-type state() :: libsodium_nif:crypto_kdf_hkdf_sha256_state().
An opaque native crypto_kdf_hkdf_sha256_state.
Operations never modify a state: each returns a new one, so earlier states remain valid and can be reused or shared between processes. States cannot be serialized; they exist only within the running VM.
Functions
-spec bytes_max() -> Result when Result :: 8160.
Return crypto_kdf_hkdf_sha256_bytes_max(), in bytes.
-spec bytes_min() -> Result when Result :: 0.
Return crypto_kdf_hkdf_sha256_bytes_min(), in bytes.
-spec expand(OutLen, PRK) -> Result when OutLen :: non_neg_integer(), PRK :: prk(), Result :: binary() | -1.
Derive OutLen bytes from the keybytes/0 byte pseudorandom key PRK
for the context Ctx (default empty).
Returns -1 when OutLen is greater than bytes_max/0.
-spec expand(OutLen, Ctx, PRK) -> Result when OutLen :: non_neg_integer(), Ctx :: binary(), PRK :: prk(), Result :: binary() | -1.
Derive OutLen bytes from the keybytes/0 byte pseudorandom key PRK
for the context Ctx (default empty).
Returns -1 when OutLen is greater than bytes_max/0.
Extract a keybytes/0 byte pseudorandom key from the input keying
material IKM and the optional Salt (default empty).
Extract a keybytes/0 byte pseudorandom key from the input keying
material IKM and the optional Salt (default empty).
Finish the streaming extraction in State, returning a keybytes/0 byte pseudorandom key.
-spec extract_init() -> Result when Result :: state() | -1.
Start a streaming extraction with the optional Salt (default empty) and return its state.
Start a streaming extraction with the optional Salt (default empty) and return its state.
-spec extract_update(State, Ikm) -> Result when State :: state(), Ikm :: binary(), Result :: state() | -1.
Absorb the input keying material IKM into State and return the updated state.
-spec keybytes() -> Result when Result :: 32.
Return crypto_kdf_hkdf_sha256_keybytes(), in bytes.
-spec keygen() -> Result when Result :: prk().
Generate a random keybytes/0 byte pseudorandom key.
-spec statebytes() -> Result when Result :: 208.
Return crypto_kdf_hkdf_sha256_statebytes(), in bytes.