silk/hkdf

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc.

HKDF key extraction and expansion with SHA-256 and SHA-384.

When to use

Use HkdfSha256 or HkdfSha384 to derive keys from secret input material under RFC 5869. Use silk.hmac when the protocol needs a message authentication tag.

Details

extract returns a fixed-size pseudorandom key. expand borrows that key and context bytes, then fills caller-owned output. These operations allocate no memory.

Gotchas

HKDF is not a password-hashing function. These actors provide no protocol labels or secret-erasure guarantee. Expansion rejects output beyond 255 digest blocks with OutputTooLongError before any output write.

Import as HkdfSha256 with import silk.hkdf { HkdfSha256 }.

Public declarations: 3.

OutputTooLongError

pub struct OutputTooLongError

An HKDF output request that exceeds the selected hash's 255-block limit.

Field requested

pub requested: usize

The requested output length in bytes.

Field maximum

pub maximum: usize

The maximum output length in bytes for the selected hash.

HkdfSha256

pub struct HkdfSha256

HKDF-SHA-256 extraction and expansion with a 32-byte pseudorandom key.

Associated function HkdfSha256.extract

pub fn extract<'life0, 'life1>(salt: &'life0 [u8], ikm: &'life1 [u8]) -> Array<u8, 32>

Returns a 32-byte pseudorandom key from borrowed salt and input key material.

Details

An empty salt is equivalent to 32 zero bytes. Empty input key material is valid. Use the result with HkdfSha256.expand and protocol-specific context bytes.

Gotchas

If the salt exceeds the 64-bit bit-length domain, the program traps. If the input plus the 64-byte HMAC pad exceeds that domain, the program traps.

Associated function HkdfSha256.expand

pub fn expand<'life0, 'life1, 'life2>(prk: &'life0 Array<u8, 32>, info: &'life1 [u8], output: &'life2 mut [u8]) -> silk/result.Result<(), silk/hkdf.OutputTooLongError>

Writes the requested HKDF-SHA-256 output prefix, or returns an error without changing output.

Details

prk must be a pseudorandom key from extraction or an equivalently strong key source. Empty info and zero output length are valid. Lengths through 8160 bytes succeed. Larger lengths return OutputTooLongError with the requested length and maximum 8160.

Gotchas

If the HMAC input exceeds the 64-bit bit-length domain, the program traps. That input includes the 64-byte pad, previous digest, info, and one counter byte.

HkdfSha384

pub struct HkdfSha384

HKDF-SHA-384 extraction and expansion with a 48-byte pseudorandom key.

Associated function HkdfSha384.extract

pub fn extract<'life0, 'life1>(salt: &'life0 [u8], ikm: &'life1 [u8]) -> Array<u8, 48>

Returns a 48-byte pseudorandom key from borrowed salt and input key material.

Details

An empty salt is equivalent to 48 zero bytes. Empty input key material is valid. Use the result with HkdfSha384.expand and protocol-specific context bytes.

Gotchas

If the salt exceeds the 128-bit bit-length domain, the program traps. If the input plus the 128-byte HMAC pad exceeds that domain, the program traps.

Associated function HkdfSha384.expand

pub fn expand<'life0, 'life1, 'life2>(prk: &'life0 Array<u8, 48>, info: &'life1 [u8], output: &'life2 mut [u8]) -> silk/result.Result<(), silk/hkdf.OutputTooLongError>

Writes the requested HKDF-SHA-384 output prefix, or returns an error without changing output.

Details

prk must be a pseudorandom key from extraction or an equivalently strong key source. Empty info and zero output length are valid. Lengths through 12240 bytes succeed. Larger lengths return OutputTooLongError with the requested length and maximum 12240.

Gotchas

If the HMAC input exceeds the 128-bit bit-length domain, the program traps. That input includes the 128-byte pad, previous digest, info, and one counter byte.