Functions
IQR_API iqr_retval	iqr_RFC5869HKDFDeriveKey (const iqr_Context ctx, iqr_HashAlgorithmType hash_algo, const uint8_t salt, size_t salt_size, const uint8_t ikm, size_t ikm_size, const uint8_t info, size_t info_size, uint8_t *key, size_t key_size)

IQR_API iqr_retval	iqr_ConcatenationKDFDeriveKey (const iqr_Context ctx, iqr_HashAlgorithmType hash_algo, const uint8_t shared_secret, size_t shared_secret_size, const uint8_t other_info, size_t other_info_size, uint8_t key, size_t key_size)

IQR_API iqr_retval	iqr_PBKDF2DeriveKey (const iqr_Context ctx, iqr_HashAlgorithmType hash_algo, const uint8_t password, size_t password_size, const uint8_t salt, size_t salt_size, uint32_t iteration_count, uint8_t key, size_t key_size)

Function Documentation

§ iqr_ConcatenationKDFDeriveKey()

IQR_API iqr_retval iqr_ConcatenationKDFDeriveKey	(	const iqr_Context *	ctx,
		iqr_HashAlgorithmType	hash_algo,
		const uint8_t *	shared_secret,
		size_t	shared_secret_size,
		const uint8_t *	other_info,
		size_t	other_info_size,
		uint8_t *	key,
		size_t	key_size
	)

Derive a key using the NIST SP 800-56A Alternative 1 Concatenation algorithm.

This function implements NIST SP 800-56A Approved Alternative 1 Concatenation KDF, as specified in section 5.8.1 of NIST SP 800-56A.

You must call iqr_HashRegisterCallbacks() to set the Hash implementation for hash_algo before using this KDF.

Parameters

[in]	ctx	A Context object.
[in]	hash_algo	The Hash algorithm to use.
[in]	shared_secret	This corresponds to Z, the shared secret, in the specification.
[in]	shared_secret_size	The size of shared_secret in bytes.
[in]	other_info	This corresponds to OtherInfo in the specification, which contains additional information used to derive the key. (Optional. Set it to `NULL` if not used.)
[in]	other_info_size	The size of other_info in bytes. (Set it to 0 if other_info is not used)
[out]	key	The requested key generated by this function based on shared_secret and other_info.
[in]	key_size	The size of the requested key in bytes. Cannot be 0.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

§ iqr_PBKDF2DeriveKey()

IQR_API iqr_retval iqr_PBKDF2DeriveKey	(	const iqr_Context *	ctx,
		iqr_HashAlgorithmType	hash_algo,
		const uint8_t *	password,
		size_t	password_size,
		const uint8_t *	salt,
		size_t	salt_size,
		uint32_t	iteration_count,
		uint8_t *	key,
		size_t	key_size
	)

Derive a key using the IETF's Password Based Key Derivation Function 2.

This function implements IETF's PBKDF2, specified by RFC 2898, section A.2.

You must call iqr_HashRegisterCallbacks() to set the Hash implementation for hash_algo before using this KDF.

Parameters

[in]	ctx	A Context object.
[in]	hash_algo	The hash algorithm to use.
[in]	password	Password string. (Optional. Set it to `NULL` if not used.)
[in]	password_size	The size of password in bytes. If password is `NULL`, this must be 0.
[in]	salt	Salt string. (Optional. Set it to `NULL` if not used.)
[in]	salt_size	The size of salt in bytes. If salt is `NULL`, this must be 0.
[in]	iteration_count	Iteration count. Cannot be 0.
[out]	key	The requested key generated by this function based on password and salt.
[in]	key_size	The size of the requested key in bytes. Must be less than 2³² times the hash digest size.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

§ iqr_RFC5869HKDFDeriveKey()

IQR_API iqr_retval iqr_RFC5869HKDFDeriveKey	(	const iqr_Context *	ctx,
		iqr_HashAlgorithmType	hash_algo,
		const uint8_t *	salt,
		size_t	salt_size,
		const uint8_t *	ikm,
		size_t	ikm_size,
		const uint8_t *	info,
		size_t	info_size,
		uint8_t *	key,
		size_t	key_size
	)

Derive a key using the RFC-5869 algorithm.

This KDF uses an HMAC internally, which will be created using the specified hashing algorithm.

The salt can be empty (pass NULL and a salt_size of 0), but this isn't recommended. The salt is used as the HMAC's key.

The initial keying material (ikm) is passed into the HMAC as the HMAC message. Some algorithms may have an existing cryptographically strong key to use for the ikm, such as the premaster secret in TLS RSA cipher suites.

The optional info buffer is for context and application specific information. This binds the derived key to your information, such as a protocol number, an algorithm identifier, user data, etc.

You must call iqr_HashRegisterCallbacks() to set the Hash implementation for the specified hash_algo before using this KDF.

The key_size cannot be more than 254 times the size of the hash's digest size or this will return IQR_EOUTOFRANGE.

See IETF HKDF RFC-5869 for more information.

Parameters

[in]	ctx	A Context object.
[in]	hash_algo	The Hash algorithm to use internally.
[in]	salt	A salt buffer, or `NULL`.
[in]	salt_size	The size, in bytes, of the salt buffer, or 0 if salt is `NULL`.
[in]	ikm	An initial keying material buffer. Cannot be `NULL`.
[in]	ikm_size	The size, in bytes, of the initial keying material. Cannot be 0.
[in]	info	An info buffer, or `NULL`.
[in]	info_size	The size, in bytes, of the info buffer, or 0 if info is `NULL`.
[out]	key	A buffer to store the derived key.
[in]	key_size	The size of the key buffer in bytes.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

Detailed Description

ISARA Toolkit's Key Derivation Functions.

There are currently three key derivation functions (KDFs) available in the Toolkit:

RFC-5869 HMAC-based Extract-and-Expand Key Derivation Function (HKDF)
NIST SP 800-56A Alternative 1 Concatenation
RFC-2898 Password Based Key Derivation Function 2 (PBKDF2)

License: The code and other content set out herein is not in the public domain, is considered a trade secret and is confidential to ISARA Corporation. Use, reproduction or distribution, in whole or in part, of such code or other content is strictly prohibited except by express written permission of ISARA Corporation. Please contact ISARA Corporation at info@.nosp@m.isar.nosp@m.a.com for more information.