Encapsulation and ECIES (v2)

[athoelke]

Starting from #220 - this PR:

• Strips out ML-KEM (to be presented in a PQC extension document).
• Updates the text align with other key establishment APIs.
• Provide a more general overview for KEMs.
• Provide a detailed alignment for ECIES with the SEC1 procedures, as the ECIES in the Crypto API is just the key agreement aspect.
• Moved some of the description and commentary into admonitions to clarify the content.

Some open issues:

• The encapsulation data sizing macro names. On other APIs, we typically name these after the function and the output parameter - but that would result in PSA_ENCAPSULATE_ENCAPSULATION_SIZE() which seems somewhat repetitive. I have currently gone with PSA_ENCAPSULATION_SIZE(), as the variable name is pretty distinctive.
• Should we consistently call this 'Encapsulation', 'Key encapsulation', or 'Key encapsulation mechanism'? - currently the text is mostly a mix of the first two.
• The output key is variously referred to as 'output key', 'shared output key', 'shared secret', and 'shared secret key'. Is there a best/preferred term for this in this API?
• If a decapsulation algorithm has an explicit failure (returns an error if the decapsulation fails rather than the wrong key), what error code should we use? (INVALID_ARGUMENT, or INVALID_SIGNATURE, or something else?).

This PR provides the API foundations for ML-KEM (#95).

[athoelke]

Another thing I am noticing in the additions for 1.3 - there are a lot of new key-returning functions. The list of 'key creation' functions is repeated about 8 times in the spec, and these are getting quite chunky now with over 10 such functions.

It might be worth reviewing those passages and simplifying the wording, and references to ALL of these APIs.

[athoelke]

Updated:

• Decided to use "key-encapsulation algorithm" everywhere
• Use "shared secret" when describing the result value of the encapsulation/decapsulation process
• Use "shared output key" when describing the key object returned by psa_encapsulate() and psa_decapsulate()
• Permit PSA_ERROR_INVALID_SIGNATURE for encapsulation data authentication failure
• Describe failure possibility for probablistic algorithms (e.g. ML-KEM) as reason for non-identical output keys
• Warn implementations against reporting padding validity errors

[athoelke]

Decided that PSA_ENCAPSULATION_SIZE() and PSA_ENCAPSULATION_MAX_SIZE are suitable for the support macro names.

[gilles-peskine-arm]

Looks mostly good to me, but with a few reservations, mostly about terminology.

[gilles-peskine-arm]

I wonder if ENCAPSULATE/DECAPSULATE are truly different usages from ENCRYPT/DECRYPT. We already have a precedent that ENCRYPT/DECRYPT covers symmetric encryption, AEAD and asymmetric encryption.

[athoelke]

This seems reasonable.

Although ECIES uses an ECC key - the permitted algorithm policy would ensure that ENCRYPT usage indicates permission for psa_encapsulate(), and not psa_asymmetric_encrypt(). This is similar to the way ENCRYPT usage on an AES key is qualified by the permitted algorithm policy.

[athoelke]

The [currently] last commit (145c376) has an implementation of this idea - removing the new usage flags and adding encapsulation and encapsulation to ENCRYPT/DECRYPT.

[athoelke]

Addressed all of the issues raised - but one or two might benefit from validation and/or fine tuning. The removal of explicit encalsulation usage flags is a single commit that can be reverted if this does not turn out to be a better approach.

[gilles-peskine-arm]

LGTM except for one confusing paragraph.

[gilles-peskine-arm]

“B, who needs to establish …” — the formulation is ambiguous: is this a goal of key encapsulation, or a prerequisite? It would be clearer to first state that the goal of key encapsulation is to establish a shared secret between A and B, before starting the description of the protocol.

[athoelke]

Good point. I patterned the current text on material elsewhere, but the motivation context will also allow me to make that sentence simpler.

[athoelke]

I've rewritten that paragraph into more of a flow:

In a key-encapsulation algorithm, participants A and B establish a shared secret as follows:

1. Participant A generates a key-pair: a private decapsulation key, and a public encapsulation key.
2. The public encapsulation key is made available to participant B.
3. Participant B uses the encapsulation key to generate one copy of a shared secret, and some ciphertext.
4. The ciphertext is transferred to participant A.
5. Participant A uses the private decapsulation key to compute another copy of the shared secret.

[athoelke]

Rebased following merge of #221, and added improvement for the description of key encapsulation.

[gilles-peskine-arm]

LGTM