Add a hash algorithm parameter to the PAKE input and output size macros

[athoelke]

This is required for some PAKE algorithms where the size of the inputs and outputs can depend on the hash algorithm used in the PAKE cipher suite.

Fixes #88

[athoelke]

Some feedback would be very welcome from @silabs-Kusumit, @silabs-hannes, @oberon-sk, and @yanesca; given your involvement in the PAKE API development.

[silabs-Kusumit]

LGTM

[yanesca]

LGTM

[athoelke]

It turns out that this is inadequate for all PAKEs.

For example, for SPAKE2+, the output size of the key confirmation steps depends on the MAC algorithm. If we only want to support the HMAC-based cipher-suites, then the Hash algorithm is sufficient information; but if we want to permit the use of CMAC, then these macros will need the MAC algorithm as a parameter.

However, SRP-6 uses the output of the Hash for key confirmation, and does not use a MAC at all. So SRP-6 would require the Hash algorithm...

Do we need to add another algorithm?

[yanesca]

Do we need to add another algorithm?

That would resolve the problem at hand, but wouldn't give much assurance that it will be able to support further PAKEs.

The safe choice would be to pass the whole ciphersuite, but of course we can't do that because we want the macro to be possible to evaluate at compile time.

What we could do is to add a wildcard parameter to the macro, the semantics of which would depend on the algorithm. It would be hash for SRP-6, MAC for SPAKE2+. It could even depend on the steps as well if needed.

[athoelke]

Reconsidering the whole thing...

Stepping back, and looking across a number of PAKE protocols, could we instead reuse some of the vacant bits within the primary [PAKE] algorithm identifier to do some of the cipher-suite parameterization. (Given that we are breaking the API at the moment).

Mostly this is using the last 8 bits to encode a Hash algorithm. For example:

• For J-PAKE, define the primary algorithm as PSA_ALG_JPAKE(hash_alg), parameterized by the hash algorithm used within the cipher suite.
• For SPAKE2+, define three algorithm identifiers:
  • PSA_ALG_SPAKE2P_HMAC(hash_alg) - SPAKE2+ using Hash=hash_alg, KDF=HKDF-hash-alg, MAC=HMAC-hash_alg
  • PSA_ALG_SPAKE2P_CMAC_AES(hash_alg) - SPAKE2+ using Hash=hash_alg, KDF=HKDF-hash-alg, MAC=CMAC-AES-128
  • PSA_ALG_SPAKE2P_MATTER - Matter v1 PAKE (based on SPAKE2+ draft02) using Hash=SHA-256, KDF=HKDF-SHA-256, MAC=HMAC-SHA-256
    This encodes the selected Hash and MAC algorithms within the algorithm identifier (except for Matter which only has a single cipher-suite).
• Other protocols, such as SRP-6, also are parameterized by a Hash algorithm.

Will we fail with a more complex protocol in future that needs more flexible parameterization? (Or a future standard SPAKE2+ cipher suite that uses a different hash algorithm in the KDF than in the MAC or Hash operations?)

[athoelke]

• PSA_ALG_SPAKE2P_CMAC_AES(hash_alg) - SPAKE2+ using Hash=hash_alg, KDF=HKDF-hash-alg, MAC=CMAC-AES-128

This is arguably clearer in application use than just adding a PSA MAC algorithm attribute to the cipher suite object. The SPAKE2+ RFC cipher-suite table explicitly specifies CMAC-AES-128 as the MAC algorithm (when CMAC is used) - whereas the PSA_ALG_CMAC algorithm is implicitly parameterized by the key type when used. In SPAKE2+, the MAC keys are internally derived, so the implementation has to know what type and size of key to derive. I think it helps to make that explicit in the algorithm identifier value.

[yanesca]

I think it helps to make that explicit in the algorithm identifier value.

There are several fields in the ciphersuite that parametrise a PAKE. Making the hash explicit is a bit arbitrary and will not make it well defined. (Making the hash explicit for signature works, because the group is encoded in the key type or the key itself. There is no need for additional parameters.)

I can see that making the hash explicit is an option and might have some benefits, but I feel that it makes the interface more complicated and less future proof.

[athoelke]

I can see that making the hash explicit is an option and might have some benefits, but I feel that it makes the interface more complicated and less future proof.

I think I need to provide a more complete explanation of my thought process here - I have probably spent too long inside the SPAKE2+ specifications and assume others are as familiar with the content....

At the moment:

• J-PAKE is parameterized by a Group (EC or FF), and a Hash
• SPAKE2+ is parameterized by a Group (EC or FF), a Hash, a KDF, and a MAC

RFC9383 tables a set of defined agreed cipher-suites that significantly reduces the option-space for parameters for SPAKE2+. Although the protocol can work with other parameters, it is unlikely to see usage outside of the specified set, though a future update might add additional cipher suite combinations.

In #120, a MAC is added to the cipher suite so that the implementation of SPAKE2+ knows whether a HMAC or CMAC key confirmation is needed. But note that in the Crypto API, the value of this field for a CMAC-AES-128 based cipher suite would be PSA_ALG_CMAC. Although this is just about sufficient for the current set of defined SPAKE2+ cipher suites, it would be incomplete if a CMAC-AES-256 MAC was needed for SPAKE2+ as the PSA algorithm identifier for CMAC does not encode the block-cipher or key size. Even if we accept the limitation of using a PSA MAC algorithm identifier, there is an invisible (in the application code) assumption that setting the cipher-suite MAC to PSA_ALG_CMAC for SPAKE2+ is requesting the use of CMAC-AES-128. I would prefer that the -AES-128 aspect of that parameterization was explicit, because it has a material effect on the operation results.

So we could start adding even more custom parameterization to the PAKE cipher suite - we don't have anything in the API for this currently - or, we could consider an alternative approach. We have precedent in the API already for encoding algorithm parameters into the full algorithm identifier:

• Hashes in many places: HMAC, KDFs, signature
• MAC selection: PSA_ALG_PBKDF2_HMAC(hash) and PSA_ALG_PBKDF2_CMAC_AES_PRF_128

My suggestion is that we revisit the encoding of the full PAKE cipher-suite, and consider using the primary algorithm identifier in the cipher-suite to encode the PAKE protocol, the Hash parameter, and (for SPAKE2+) the MAC parameter. As in the current API, the cipher suite also includes the PAKE primitive to encode the computational Group.

[yanesca]

It is a nice proposal and it solves the size macro problem.

It also has an impact on defining key policies. The keys used are typically output of password based key derivation for most, but some of them it can be plain password (OPAQUE depending on how we implement it, I couldn't see an easy way to separate out the memory hard function), or like we are planning for SPAKE2+ a key pair. We will need to encode in the key type everything else we need when using these and in the future we might find that we need to introduce more key types than we would want to.

That said, the proposal makes this situation better as well, and I can't see any potential issue at this point.

[athoelke]

It also has an impact on defining key policies.

Good point. I think we could reuse the PSA_ALG_ANY_HASH behavior for signature algorithm polices with PAKE algorithm policies. On the other hand, at the point at which a J-PAKE password hash, or a SPAKE2+ key pair is derived (e.g. via PBKDF2), I would expect that the application knows the cipher suite, and therefore the Hash algorithm that will be used in the PAKE protocol itself.

Similarly, although a SPAKE2+ verification or prover key could technically be used with a CMAC or HMAC cipher suite - is there a use case where the MAC element of the cipher suite would either (a) be unknown at the time of 'registration' (key derivation), or (b) change during the lifetime of a previously registered key?

Could we keep the permitted algorithm policy simple for now (exact match), and reconsider wildcards when a use case is identified?

[athoelke]

My suggestion is that we revisit the encoding of the full PAKE cipher-suite, and consider using the primary algorithm identifier in the cipher-suite to encode the PAKE protocol, the Hash parameter, and (for SPAKE2+) the MAC parameter. As in the current API, the cipher suite also includes the PAKE primitive to encode the computational Group.

I will explore this idea as a separate/alternate PR to tease out all the emergent implications... [editted] See #124

[athoelke]

Obsolete. Fixed by #124 instead