HKDF 1: PSA: implement HKDF_Expand and HKDF_Extract algorithms

[gilles-peskine-arm]

Implement HKDF-Expand and HKDF-Extract as separate algorithms in the PSA API. We already have HKDF as a single algorithm, but this is not sufficient for TLS 1.3.

These algorithms will be added in the next version of the PSA Crypto API specification. Draft specification (private link).

We may want to first do the pending refactoring of the PSA key derivation code, needed to support drivers: #5477 and follow-ups.

[mpg]

We may want to first do the pending refactoring of the PSA key derivation code, needed to support drivers: #5477 and follow-ups.

Just to be sure: is it also OK to leave that refactoring for later?

[gilles-peskine-arm]

I would prefer to do the refactoring before, but either way works. What wouldn't work is to do the two in parallel.

[mprse]

I read about HKDF/HKDF-Extract/HKDF-Expand here.
We already have HKDF algorithm implemented and it consts of HKDF-Extract and HKDF-Expand.
Looking into the code I understand that the result of HKDF-Extract is hkdf->prk filled currently in psa_hkdf_input() (when salt and secret are provided):

mbedtls/library/psa_crypto.c

Lines 5195 to 5198 in 9bbb7ba

	status = psa_mac_sign_finish( &hkdf->hmac,
	hkdf->prk,
	sizeof( hkdf->prk ),
	&data_length );

The result of HKDF-Expand is the output of psa_key_derivation_hkdf_read() that makes usage of hkdf->prk.

Form my perspective we need to:

• add definitions for HKDF-Extract/HKDF-Expand algorithms (PSA_ALG_HKDF_EXTRACT_BASE, PSA_ALG_HKDF_EXTRACT, PSA_ALG_IS_HKDF_EXTRACT, PSA_ALG_HKDF_EXTRACT_GET_HASH, etc.)
• define steps for HKDF-Extract/HKDF-Expand. For HKDF-Extract we need salt and secret. For HKDF-Expand we need secret (prk) and label.

For HKDF we have now:

#define HKDF_STATE_INIT 0 /* no input yet */
#define HKDF_STATE_STARTED 1 /* got salt */
#define HKDF_STATE_KEYED 2 /* got key */
#define HKDF_STATE_OUTPUT 3 /* output started */

For info we have now special flag hkdf->info_set.

So it looks like we could have same states for HKDF-Extract

#define HKDF_EXTRACT_STATE_INIT 0 /* no input yet */
#define HKDF_EXTRACT_STATE_STARTED 1 /* got salt */
#define HKDF_EXTRACT_STATE_KEYED 2 /* got key */
#define HKDF_EXTRACT_STATE_OUTPUT 3 /* output started */

And the following states for expand:

#define HKDF_EXPAND_STATE_INIT 0 /* no input yet */
#define HKDF_EXPAND_STATE_KEYED 1 /* got key */
#define HKDF_EXPAND_STATE_OUTPUT 2 /* output started */

I'm not sure why we don't have state for info, probably because it can be provided at any time (before staring output generation).

• add implementation for psa_hkdf_extract_input() and psa_hkdf_expand_input().
• add implementation for psa_key_derivation_hkdf_extract_read() and psa_key_derivation_hkdf_expand_read().
• add tests

@gilles-peskine-arm @mpg Please confirm it this is what needs to be done here before I start working on implementation.

[mprse]

Alternatively it looks like it would be better maybe to adapt psa_hkdf_input() and psa_key_derivation_hkdf_read() to handle extract/expand separately.

[gilles-peskine-arm]

Looking into the code I understand that the result of HKDF-Extract is hkdf->prk

That's correct.

define steps for HKDF-Extract/HKDF-Expand. For HKDF-Extract we need salt and secret. For HKDF-Expand we need secret (prk) and label.

I don't understand what you mean by “define steps”. All the code to process those input steps is already there as part of HKDF code. Now HKDF-Extract needs to directly use the PRK as output, and HKDF-Expand needs to use the PRK as input.

So it looks like we could have same states for HKDF-Extract

Yes.

And the following states for expand:

#define HKDF_EXPAND_STATE_INIT 0 /* no input yet */
#define HKDF_EXPAND_STATE_KEYED 1 /* got key */
#define HKDF_EXPAND_STATE_OUTPUT 2 /* output started */

Yes. The last state actually starts as soon as info is received.

I'm not sure why we don't have state for info, probably because it can be provided at any time

Yes. Since info can be provided at any time, the states of HKDF are INIT_NOINFO, INIT_INFO, STARTED_NOINFO, STARTED_INFO, KEYED_NOINFO, KEYED_INFO and OUTPUT_INFO. Only OUTPUT_NOINFO is impossible (info is mandatory). To avoid having so many states, there's one variable that tracks salt+secret (which need to be passed in order), and one that tracks info.

Regarding

• add implementation for psa_hkdf_extract_input() and psa_hkdf_expand_input().
• add implementation for psa_key_derivation_hkdf_extract_read() and psa_key_derivation_hkdf_expand_read().

vs

adapt psa_hkdf_input() and psa_key_derivation_hkdf_read() to handle extract/expand separately.

that detail is up to you. Avoid duplicating code and keep the code readable.