hkdf.h File Reference

(dbfdd20677)

HKDF operations for the OpenTitan cryptography library. More...

#include "datatypes.h"

Go to the source code of this file.

Functions
otcrypto_status_t	otcrypto_hkdf (const otcrypto_blinded_key_t ikm, otcrypto_const_byte_buf_t salt, otcrypto_const_byte_buf_t info, otcrypto_blinded_key_t *okm)
	Performs HKDF (IETF RFC 5869) in one shot, both expand and extract stages. More...
otcrypto_status_t	otcrypto_hkdf_extract (const otcrypto_blinded_key_t ikm, otcrypto_const_byte_buf_t salt, otcrypto_blinded_key_t *prk)
	Performs the "extract" step of HKDF (IETF RFC 5869). More...
otcrypto_status_t	otcrypto_hkdf_expand (const otcrypto_blinded_key_t prk, otcrypto_const_byte_buf_t info, otcrypto_blinded_key_t *okm)
	Performs the "expand" step of HKDF (IETF RFC 5869). More...

Detailed Description

HKDF operations for the OpenTitan cryptography library.

Implements the HMAC-based extract-and-expand key derivation function specified in IETF RFC 5869.

Definition in file hkdf.h.

Function Documentation

otcrypto_hkdf()

otcrypto_status_t otcrypto_hkdf	(	const otcrypto_blinded_key_t	ikm,
		otcrypto_const_byte_buf_t	salt,
		otcrypto_const_byte_buf_t	info,
		otcrypto_blinded_key_t *	okm
	)

Performs HKDF (IETF RFC 5869) in one shot, both expand and extract stages.

The hash mode for the underlying HMAC is determined by the mode of the input key material, e.g. the key mode kOtcryptoKeyModeHmacSha256 results in HMAC with SHA-256.

The caller should allocate and partially populate the okm blinded key struct, including populating the key configuration and allocating space for the keyblob. The configuration may not indicate a hardware-backed key and must indicate a symmetric mode. The allocated keyblob length for the output key should be twice the unmasked key length indicated in its key configuration, rounded up to the nearest 32-bit word. This unmasked key length must not be longer than 255*<length of digest for the chosen hash mode>, as per the RFC. The value in the checksum field of the blinded key struct will be populated by the key derivation function.

Parameters

	ikm	Blinded input key material.
	salt	Salt value (optional, may be empty).
	info	Context-specific string (optional, may be empty).
[out]	okm	Blinded output keying material.

Returns

Result of the key derivation operation.

Definition at line 47 of file hkdf.c.

otcrypto_hkdf_expand()

otcrypto_status_t otcrypto_hkdf_expand	(	const otcrypto_blinded_key_t	prk,
		otcrypto_const_byte_buf_t	info,
		otcrypto_blinded_key_t *	okm
	)

Performs the "expand" step of HKDF (IETF RFC 5869).

The hash mode for the underlying HMAC is determined by the mode of the pseudo-random key, e.g. the key mode kOtcryptoKeyModeHmacSha256 results in HMAC with SHA-256.

See otcrypto_hkdf for the requirements on okm.

Parameters

	prk	Pseudo-random key from HKDF-extract.
	info	Context-specific string (optional).
[out]	okm	Blinded output key material.

Returns

Result of the key derivation operation.

Definition at line 222 of file hkdf.c.

otcrypto_hkdf_extract()

otcrypto_status_t otcrypto_hkdf_extract	(	const otcrypto_blinded_key_t	ikm,
		otcrypto_const_byte_buf_t	salt,
		otcrypto_blinded_key_t *	prk
	)

Performs the "extract" step of HKDF (IETF RFC 5869).

The hash mode for the underlying HMAC is determined by the mode of the input key material, e.g. the key mode kOtcryptoKeyModeHmacSha256 results in HMAC with SHA-256.

The caller should allocate and partially populate the prk blinded key struct, including populating the key configuration and allocating space for the keyblob. The configuration may not indicate a hardware-backed key, and the mode should be the same HMAC mode as the input keying material. The allocated keyblob length should be twice the hash function digest length for the chosen hash mode (e.g. 512 bits for SHA-256).

Parameters

	ikm	Blinded input key material.
	salt	Salt value (optional, may be empty).
[out]	prk	Extracted pseudo-random key.

Returns

Result of the key derivation operation.

Definition at line 119 of file hkdf.c.