Add compatibility notes regarding values embedded in the key store
Certain numerical values are written to the key store. Changing those
numerical values would break the backward compatibility of stored keys. Add
a note to the affected types. Add comments near the definitions of affected
values.
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h
index cd9a034..af27253 100644
--- a/include/psa/crypto_values.h
+++ b/include/psa/crypto_values.h
@@ -12,6 +12,11 @@
* designations of cryptographic algorithms, and error codes returned by
* the library.
*
+ * Note that many of the constants defined in this file are embedded in
+ * the persistent key store, as part of key metadata (including usage
+ * policies). As a consequence, they must not be changed (unless the storage
+ * format version changes).
+ *
* This header file only defines preprocessor macros.
*/
/*
@@ -40,6 +45,11 @@
/* PSA error codes */
+/* Error codes are standardized across PSA domains (framework, crypto, storage,
+ * etc.). Do not change the values in this section. If you must add a new
+ * value, check with the Arm PSA framework group to pick one that other
+ * domains aren't already using. */
+
/** The action was completed successfully. */
#define PSA_SUCCESS ((psa_status_t)0)
@@ -316,6 +326,12 @@
* @{
*/
+/* Note that key type values, including ECC family and DH group values, are
+ * embedded in the persistent key store, as part of key metadata. As a
+ * consequence, they must not be changed (unless the storage format version
+ * changes).
+ */
+
/** An invalid key type value.
*
* Zero is not the encoding of any key type.
@@ -673,6 +689,11 @@
1u << PSA_GET_KEY_TYPE_BLOCK_SIZE_EXPONENT(type) : \
0u)
+/* Note that algorithm values are embedded in the persistent key store,
+ * as part of key metadata. As a consequence, they must not be changed
+ * (unless the storage format version changes).
+ */
+
/** Vendor-defined algorithm flag.
*
* Algorithms defined by this standard will never have the #PSA_ALG_VENDOR_FLAG
@@ -1928,6 +1949,11 @@
* @{
*/
+/* Note that location and persistence level values are embedded in the
+ * persistent key store, as part of key metadata. As a consequence, they
+ * must not be changed (unless the storage format version changes).
+ */
+
/** The default lifetime for volatile keys.
*
* A volatile key only exists as long as the identifier to it is not destroyed.
@@ -2043,6 +2069,11 @@
#define PSA_KEY_LOCATION_VENDOR_FLAG ((psa_key_location_t)0x800000)
+/* Note that key identifier values are embedded in the
+ * persistent key store, as part of key metadata. As a consequence, they
+ * must not be changed (unless the storage format version changes).
+ */
+
/** The null key identifier.
*/
#define PSA_KEY_ID_NULL ((psa_key_id_t)0)
@@ -2154,6 +2185,11 @@
* @{
*/
+/* Note that key usage flags are embedded in the
+ * persistent key store, as part of key metadata. As a consequence, they
+ * must not be changed (unless the storage format version changes).
+ */
+
/** Whether the key may be exported.
*
* A public key or the public part of a key pair may always be exported
@@ -2255,6 +2291,9 @@
* @{
*/
+/* Key input steps are not embedded in the persistent storage, so you can
+ * change them if needed: it's only an ABI change. */
+
/** A secret input for key derivation.
*
* This should be a key of type #PSA_KEY_TYPE_DERIVE