search

ARM-software / psa-api

Documentation source and development of the PSA Certified API
https://arm-software.github.io/psa-api/
Other
58 stars 28 forks source link

PSA_ERROR_INVALID_HANDLE: clarify that it's about existing objects #138

Closed gilles-peskine-arm closed 10 months ago

gilles-peskine-arm commented 10 months ago

The current wording makes it look like the error also applies when creating an object with a caller-chosen handle and the caller's choice is not acceptable. See https://lists.trustedfirmware.org/archives/list/mbed-tls@lists.trustedfirmware.org/thread/DOBLFTSJMN2BGW3E7J6HVX6CXZ4YBKK3/

MarcusJGStreets commented 10 months ago

If you make this change, what would be the difference between PSA_ERROR_INVALID_HANDLE and PSA_ERROR_DOES_NOT_EXIST?

What do you return if the value is out of range? PSA_KEY_ID_USER_MIN to PSAKEY_ID_USER_MAX or PSA_KEY_ID_VENDOR_MIN to PSA_KEY_ID_VENDOR_MAX?

gilles-peskine-arm commented 10 months ago

This is intended only to clarify the existing specification, not as a change of behavior.

Crypto API functions don't return PSA_ERROR_DOES_NOT_EXIST. Storage does, and I think storage doesn't use PSA_ERROR_INVALID_HANDLE.

What do you return if the value is out of range?

When attempting to use an existing key: INVALID_HANDLE, same as if the value is in range but the key does not exist. Note that a key can exist outside the ranges you specify, if it's a vendor-specific built-in/magic key.

When attempting to create a key: INVALID_ARGUMENT, same as other arguments with a value that isn't acceptable.

athoelke commented 10 months ago

If you make this change, what would be the difference between PSA_ERROR_INVALID_HANDLE and PSA_ERROR_DOES_NOT_EXIST?

The use of PSA_ERROR_INVALID_HANDLE stems from a legacy. The initial development of this API had distinct handles for using a key, and identifiers for naming a persistent key. Just prior to 1.0.0, we merged the concepts and used key ids for everything - but we didn't change the API of all key-using functions to return PSA_ERROR_DOES_NOT_EXIST instead of PSA_ERROR_INVALID_HANDLE for key ids that did not match any key.

If starting from scratch, I would use PSA_ERROR_DOES_NOT_EXIST, as for other identifiers, such as in the Storage and Firmware Update APIs. However, changing this aspect of the API would be a breaking change so we live with PSA_ERROR_INVALID_HANDLE.