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.