Key wrapping API proposal

[gilles-peskine-arm]

This is a first draft of the key wrapping API for PSA Cryptography 1.x.

This pull request only provides function prototypes and associated macro definitions. Tests and implementations will come later.

I implemented the proposal discussed in private. I'm not attached to function/macro names if you have better suggestions. The API comprises:

• Functions to back up and restore a key, wrapped with another key, using a vendor-chosen algorithm.
• A reserved identifier value for a wrapping key. There is currently no way to create a wrapping key that can wrap keys with metadata.
• Functions to wrap key material with another key, using standard algorithms.

[athoelke]

Do we also need a usage flag for WRAP and UNWRAP, as well as the defined flags for a key being exporting in wrapped form? Keys used as wrapping keys in psa_wrap_key_*() or psa_unwrap_key_*() would then require the applicable usage flag.

[gilles-peskine-arm]

@MarcusJGStreets @athoelke I pushed an update with a rewritten history that should resolve all your comments and cover what we discussed orally today, other than the naming. The original version is in https://github.com/gilles-peskine-arm/mbed-crypto/tree/psa-wrap-api-1

• I fixed copypasta by amending the corresponding commits.
• I removed the commit that introduced psa_get_wrapped_key_attributes, and instead made a new commit introducing psa_unwrap_key_to_alternate_lifetime and removing the attributes parameter to psa_unwrap_key_with_policy.
• I added usage flags for wrapping keys.

I'll subsequently make another update to fix the terminology issues (which includes finding a decent name for psa_unwrap_key_to_alternate_lifetime; I couldn't resolve myself to psa_unwrap_key_with_policy_to_alternate_lifetime). I'm more and more warming up to backup/restore for wrap-with-policy. It isn't the only use case for this function (there's also sharing, when another entity has the unwrapping key), but it's a common one. I think anyone would understand backup/restore, even if it isn't what crypto architects would use, unlike “binding”, which even crypto architects don't fully agree on.

[athoelke]

Hi @gilles-peskine-arm - thanks for the update.

• I'm quite happy with the idea of backup/restore terminology. Would you drop the _material from the other wrapping functions as a result?

• Some ideas for the tricky-to-name API:

  • psa_restore_key_as_volatile()
  • psa_restore_key_elsewhere() :-)
  • `psa_restore_key_ex()

The usage flag naming gets interesting now that we have "can be wrapped" and "can use to wrap" policy flags. It is clear there are two categories of flags:

1. Management policies - things the implementation/application can do to a key object: EXPORT, COPY, CACHE, WRAP, BACKUP
2. Usage policies - things the implementation/application can do with the key material: ENCRYPT, DECRYPT, SIGN, VERIFY, DERIVE, WRAP.

I wonder now if we should have named these categories of flag separately to make it easier to distinguish can-wrap-with from can-be-wrapped.