Module crypto_kdf 

Key derivation function

Implements libsodium’s key derivation functions (crypto_kdf_*).

The Blake2b crypto_kdf_* functions derive bounded subkeys from a random main key and an 8-byte application context. The HKDF functions derive output keying material from existing input keying material, using an optional salt and a public context string.

Use crypto_kdf_derive_from_key when you have one random main key and need numbered subkeys. Use the HKDF functions when you already have keying material, such as a key-exchange result, and need to turn it into one or more purpose-specific keys.

For details, refer to libsodium docs.

Classic API example

use base64::Engine as _;
use base64::engine::general_purpose;
use dryoc::classic::crypto_kdf::*;

// Generate a random main key
let main_key = crypto_kdf_keygen();
// Provide exactly 8 bytes of public context data
let context = b"WTCHKEYS";

// Derive 20 subkeys
for i in 0..20 {
    let mut key = Key::default();
    crypto_kdf_derive_from_key(&mut key, i, context, &main_key).expect("kdf failed");
    println!("Subkey {}: {}", i, general_purpose::STANDARD.encode(&key));
}

HKDF-SHA-256 example

use dryoc::classic::crypto_kdf::*;

let mut prk = HkdfSha256Key::default();
crypto_kdf_hkdf_sha256_extract(&mut prk, Some(b"salt"), b"Some rise by sin");

let mut output = [0u8; 42];
crypto_kdf_hkdf_sha256_expand(&mut output, b"encryption key", &prk).expect("expand failed");

The HKDF extract step can also be fed incrementally. This is useful when the input keying material arrives in pieces:

use dryoc::classic::crypto_kdf::*;

let mut state = crypto_kdf_hkdf_sha256_extract_init(Some(b"salt"));
crypto_kdf_hkdf_sha256_extract_update(&mut state, b"Some rise ");
crypto_kdf_hkdf_sha256_extract_update(&mut state, b"by sin");

let mut prk = HkdfSha256Key::default();
crypto_kdf_hkdf_sha256_extract_final(state, &mut prk);

HKDF-SHA-512 example

use dryoc::classic::crypto_kdf::*;

let mut prk: HkdfSha512Key = [0u8; 64];
crypto_kdf_hkdf_sha512_extract(&mut prk, None, b"and some by virtue fall");

let mut output = [0u8; 64];
crypto_kdf_hkdf_sha512_expand(&mut output, b"authentication key", &prk).expect("expand failed");

Structs

HkdfSha256State

Internal state for incremental HKDF-SHA-256 extract.

HkdfSha512State

Internal state for incremental HKDF-SHA-512 extract.

Functions

crypto_kdf_derive_from_key

Derives subkey from main_key, using context and subkey_id such that subkey will always be the same for the given set of inputs, but main_key cannot be derived from subkey.

crypto_kdf_hkdf_sha256_expand

Expands an HKDF-SHA-256 pseudorandom key into output keying material.

crypto_kdf_hkdf_sha256_extract

Creates an HKDF-SHA-256 pseudorandom key from input keying material.

crypto_kdf_hkdf_sha256_extract_final

Finalizes incremental HKDF-SHA-256 extract and writes the pseudorandom key.

crypto_kdf_hkdf_sha256_extract_init

Initializes incremental HKDF-SHA-256 extract.

crypto_kdf_hkdf_sha256_extract_update

Updates incremental HKDF-SHA-256 extract with input keying material.

crypto_kdf_hkdf_sha256_keygen

Generates a random pseudorandom key for HKDF-SHA-256 expand.

crypto_kdf_hkdf_sha512_expand

Expands an HKDF-SHA-512 pseudorandom key into output keying material.

crypto_kdf_hkdf_sha512_extract

Creates an HKDF-SHA-512 pseudorandom key from input keying material.

crypto_kdf_hkdf_sha512_extract_final

Finalizes incremental HKDF-SHA-512 extract and writes the pseudorandom key.

crypto_kdf_hkdf_sha512_extract_init

Initializes incremental HKDF-SHA-512 extract.

crypto_kdf_hkdf_sha512_extract_update

Updates incremental HKDF-SHA-512 extract with input keying material.

crypto_kdf_hkdf_sha512_keygen

Generates a random pseudorandom key for HKDF-SHA-512 expand.

crypto_kdf_keygen

Generates a random key, suitable for use as a main key with crypto_kdf_derive_from_key.

Type Aliases

Context

Context for key derivation.

HkdfSha256Key

Pseudorandom key for HKDF-SHA-256.

HkdfSha512Key

Pseudorandom key for HKDF-SHA-512.

Key

Key type for the main key used for deriving subkeys.