psa-api icon indicating copy to clipboard operation
psa-api copied to clipboard

Add support for key wrapping (v2)

Open athoelke opened this issue 1 year ago • 1 comments

This PR replaces #215, simplifying the API to only support key wrapping algorithms, and not wrapped-key formats. Wrapped-key formats will be considered later, along with import and export of formatted key data (see also #50, #149 and #207 for more discussion).

This added the psa_wrap_key() and psa_unwrap_key() functions, and support for AES-KW and AES-KWP algorithms.

Open issues:

  1. NIST 800-38F describes a generalised AES-KW and AES-KWP to support any 128-bit 'approved block cipher', which exactly matches RFC 3394 and RFC 5649 definitions for the AES block cipher. Is it valuable to define this as the more general algorithm identifier, compatible with any 128-bit block cipher key, or just keep the AES-specific name and AES-only compatibility?

  2. I have allocated a new algorithm category, as key-wrapping algorithms tend to be specialized authenticated encryption. However, AES-SIV can be used as a general AEAD algorithm, as well as a key-wrapping algorithm. Would that be problematic?

  3. I have recycled the 'S' bit in the algorithm identifier to flag whether the algorithm has alignment constraints on the input data (AES-KW does, AES-KWP does not) - similar to block-aligned sizes for some block-mode ciphers. Is this at all useful, or should we just make this bit 0 for key-wrap algorithms?

Partly fixes #50

athoelke avatar Oct 24 '24 19:10 athoelke

After another round of review and consideration, this approach is not convincing.

Although it avoids the challenge of designing the key policy handling that comes with an API for handling wrapped-key formats (see #215), it will result in multiple APIs for key wrapping which is not ideal.

This PR will remain as Draft for the time being - this API should be considered experimentatal/Beta. We will revisit the API for wrapping and unwrapping keys after v1.3.

athoelke avatar Dec 04 '24 10:12 athoelke

I think it is time to revive this PR and decide on the design of key wrapping APIs?

This simplified wrappign API for encrypting key material without structured output and key metadata, is vaulable for use cases such as encrypted firmware. For example, constrained bootloader runtimes benefit from the elimination of unused parameters and behavioral requirements that a unified, but more complex, wrapping/formatting API would entail.

This current proposed API is in use in some implementations of the specification.

athoelke avatar Sep 08 '25 14:09 athoelke

We think this proposal is good, it works for us.

bheeb avatar Sep 11 '25 13:09 bheeb

I have addressed Open issue 1 directly, and am happy with the encoding decisions

athoelke avatar Oct 03 '25 16:10 athoelke