Move legacy definitions to crypto_extra.h
Types and functions that are not used in the attribute-based key
creation API are now implementation-specific extensions, kept around
until we finish transitioning to the new API.
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index e0ac89c..2046947 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -365,162 +365,10 @@
/**@}*/
-/** \defgroup policy Key policies
- * @{
- */
-
-/** The type of the key policy data structure.
- *
- * Before calling any function on a key policy, the application must initialize
- * it by any of the following means:
- * - Set the structure to all-bits-zero, for example:
- * \code
- * psa_key_policy_t policy;
- * memset(&policy, 0, sizeof(policy));
- * \endcode
- * - Initialize the structure to logical zero values, for example:
- * \code
- * psa_key_policy_t policy = {0};
- * \endcode
- * - Initialize the structure to the initializer #PSA_KEY_POLICY_INIT,
- * for example:
- * \code
- * psa_key_policy_t policy = PSA_KEY_POLICY_INIT;
- * \endcode
- * - Assign the result of the function psa_key_policy_init()
- * to the structure, for example:
- * \code
- * psa_key_policy_t policy;
- * policy = psa_key_policy_init();
- * \endcode
- *
- * This is an implementation-defined \c struct. Applications should not
- * make any assumptions about the content of this structure except
- * as directed by the documentation of a specific implementation. */
-typedef struct psa_key_policy_s psa_key_policy_t;
-
-/** \def PSA_KEY_POLICY_INIT
- *
- * This macro returns a suitable initializer for a key policy object of type
- * #psa_key_policy_t.
- */
-#ifdef __DOXYGEN_ONLY__
-/* This is an example definition for documentation purposes.
- * Implementations should define a suitable value in `crypto_struct.h`.
- */
-#define PSA_KEY_POLICY_INIT {0}
-#endif
-
-/** Return an initial value for a key policy that forbids all usage of the key.
- */
-static psa_key_policy_t psa_key_policy_init(void);
-
-/** \brief Set the standard fields of a policy structure.
- *
- * Note that this function does not make any consistency check of the
- * parameters. The values are only checked when applying the policy to
- * a key slot with psa_set_key_policy().
- *
- * \param[in,out] policy The key policy to modify. It must have been
- * initialized as per the documentation for
- * #psa_key_policy_t.
- * \param usage The permitted uses for the key.
- * \param alg The algorithm that the key may be used for.
- */
-void psa_key_policy_set_usage(psa_key_policy_t *policy,
- psa_key_usage_t usage,
- psa_algorithm_t alg);
-
-/** \brief Retrieve the usage field of a policy structure.
- *
- * \param[in] policy The policy object to query.
- *
- * \return The permitted uses for a key with this policy.
- */
-psa_key_usage_t psa_key_policy_get_usage(const psa_key_policy_t *policy);
-
-/** \brief Retrieve the algorithm field of a policy structure.
- *
- * \param[in] policy The policy object to query.
- *
- * \return The permitted algorithm for a key with this policy.
- */
-psa_algorithm_t psa_key_policy_get_algorithm(const psa_key_policy_t *policy);
-
-/** \brief Set the usage policy on a key slot.
- *
- * This function must be called on an empty key slot, before importing,
- * generating or creating a key in the slot. Changing the policy of an
- * existing key is not permitted.
- *
- * Implementations may set restrictions on supported key policies
- * depending on the key type and the key slot.
- *
- * \param handle Handle to the key whose policy is to be changed.
- * \param[in] policy The policy object to query.
- *
- * \retval #PSA_SUCCESS
- * Success.
- * If the key is persistent, it is implementation-defined whether
- * the policy has been saved to persistent storage. Implementations
- * may defer saving the policy until the key material is created.
- * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_ALREADY_EXISTS
- * \retval #PSA_ERROR_NOT_SUPPORTED
- * \retval #PSA_ERROR_INVALID_ARGUMENT
- * \retval #PSA_ERROR_COMMUNICATION_FAILURE
- * \retval #PSA_ERROR_HARDWARE_FAILURE
- * \retval #PSA_ERROR_TAMPERING_DETECTED
- * \retval #PSA_ERROR_BAD_STATE
- * The library has not been previously initialized by psa_crypto_init().
- * It is implementation-dependent whether a failure to initialize
- * results in this error code.
- */
-psa_status_t psa_set_key_policy(psa_key_handle_t handle,
- const psa_key_policy_t *policy);
-
-/** \brief Get the usage policy for a key slot.
- *
- * \param handle Handle to the key slot whose policy is being queried.
- * \param[out] policy On success, the key's policy.
- *
- * \retval #PSA_SUCCESS
- * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_COMMUNICATION_FAILURE
- * \retval #PSA_ERROR_HARDWARE_FAILURE
- * \retval #PSA_ERROR_TAMPERING_DETECTED
- * \retval #PSA_ERROR_BAD_STATE
- * The library has not been previously initialized by psa_crypto_init().
- * It is implementation-dependent whether a failure to initialize
- * results in this error code.
- */
-psa_status_t psa_get_key_policy(psa_key_handle_t handle,
- psa_key_policy_t *policy);
-
-/**@}*/
-
/** \defgroup key_management Key management
* @{
*/
-/** Allocate a key slot for a transient key, i.e. a key which is only stored
- * in volatile memory.
- *
- * The allocated key slot and its handle remain valid until the
- * application calls psa_close_key() or psa_destroy_key() or until the
- * application terminates.
- *
- * \param[out] handle On success, a handle to a volatile key slot.
- *
- * \retval #PSA_SUCCESS
- * Success. The application can now use the value of `*handle`
- * to access the newly allocated key slot.
- * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
- * There was not enough memory, or the maximum number of key slots
- * has been reached.
- */
-psa_status_t psa_allocate_key(psa_key_handle_t *handle);
-
/** Open a handle to an existing persistent key.
*
* Open a handle to a key which was previously created with psa_create_key().
@@ -685,33 +533,6 @@
psa_status_t psa_destroy_key(psa_key_handle_t handle);
/**
- * \brief Get basic metadata about a key.
- *
- * \param handle Handle to the key slot to query.
- * \param[out] type On success, the key type (a \c PSA_KEY_TYPE_XXX value).
- * This may be a null pointer, in which case the key type
- * is not written.
- * \param[out] bits On success, the key size in bits.
- * This may be a null pointer, in which case the key size
- * is not written.
- *
- * \retval #PSA_SUCCESS
- * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_DOES_NOT_EXIST
- * The handle is to a key slot which does not contain key material yet.
- * \retval #PSA_ERROR_COMMUNICATION_FAILURE
- * \retval #PSA_ERROR_HARDWARE_FAILURE
- * \retval #PSA_ERROR_TAMPERING_DETECTED
- * \retval #PSA_ERROR_BAD_STATE
- * The library has not been previously initialized by psa_crypto_init().
- * It is implementation-dependent whether a failure to initialize
- * results in this error code.
- */
-psa_status_t psa_get_key_information(psa_key_handle_t handle,
- psa_key_type_t *type,
- size_t *bits);
-
-/**
* \brief Set domain parameters for a key.
*
* Some key types require additional domain parameters to be set before import
diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index efd1b76..f2cf051 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -202,6 +202,115 @@
/* FIXME Deprecated. Remove this as soon as all the tests are updated. */
#define PSA_ALG_SELECT_RAW ((psa_algorithm_t)0x31000001)
+/** \defgroup policy Key policies
+ * @{
+ *
+ * The functions in this section are legacy interfaces where the properties
+ * of a key object are set after allocating a handle, in constrast with the
+ * preferred interface where key objects are created atomically from
+ * a structure that represents the properties.
+ */
+
+/** \def PSA_KEY_POLICY_INIT
+ *
+ * This macro returns a suitable initializer for a key policy object of type
+ * #psa_key_policy_t.
+ */
+#ifdef __DOXYGEN_ONLY__
+/* This is an example definition for documentation purposes.
+ * Implementations should define a suitable value in `crypto_struct.h`.
+ */
+#define PSA_KEY_POLICY_INIT {0}
+#endif
+
+/** Return an initial value for a key policy that forbids all usage of the key.
+ */
+static psa_key_policy_t psa_key_policy_init(void);
+
+/** \brief Set the standard fields of a policy structure.
+ *
+ * Note that this function does not make any consistency check of the
+ * parameters. The values are only checked when applying the policy to
+ * a key slot with psa_set_key_policy().
+ *
+ * \param[in,out] policy The key policy to modify. It must have been
+ * initialized as per the documentation for
+ * #psa_key_policy_t.
+ * \param usage The permitted uses for the key.
+ * \param alg The algorithm that the key may be used for.
+ */
+void psa_key_policy_set_usage(psa_key_policy_t *policy,
+ psa_key_usage_t usage,
+ psa_algorithm_t alg);
+
+/** \brief Retrieve the usage field of a policy structure.
+ *
+ * \param[in] policy The policy object to query.
+ *
+ * \return The permitted uses for a key with this policy.
+ */
+psa_key_usage_t psa_key_policy_get_usage(const psa_key_policy_t *policy);
+
+/** \brief Retrieve the algorithm field of a policy structure.
+ *
+ * \param[in] policy The policy object to query.
+ *
+ * \return The permitted algorithm for a key with this policy.
+ */
+psa_algorithm_t psa_key_policy_get_algorithm(const psa_key_policy_t *policy);
+
+/** \brief Set the usage policy on a key slot.
+ *
+ * This function must be called on an empty key slot, before importing,
+ * generating or creating a key in the slot. Changing the policy of an
+ * existing key is not permitted.
+ *
+ * Implementations may set restrictions on supported key policies
+ * depending on the key type and the key slot.
+ *
+ * \param handle Handle to the key whose policy is to be changed.
+ * \param[in] policy The policy object to query.
+ *
+ * \retval #PSA_SUCCESS
+ * Success.
+ * If the key is persistent, it is implementation-defined whether
+ * the policy has been saved to persistent storage. Implementations
+ * may defer saving the policy until the key material is created.
+ * \retval #PSA_ERROR_INVALID_HANDLE
+ * \retval #PSA_ERROR_ALREADY_EXISTS
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ * The library has not been previously initialized by psa_crypto_init().
+ * It is implementation-dependent whether a failure to initialize
+ * results in this error code.
+ */
+psa_status_t psa_set_key_policy(psa_key_handle_t handle,
+ const psa_key_policy_t *policy);
+
+/** \brief Get the usage policy for a key slot.
+ *
+ * \param handle Handle to the key slot whose policy is being queried.
+ * \param[out] policy On success, the key's policy.
+ *
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_INVALID_HANDLE
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ * The library has not been previously initialized by psa_crypto_init().
+ * It is implementation-dependent whether a failure to initialize
+ * results in this error code.
+ */
+psa_status_t psa_get_key_policy(psa_key_handle_t handle,
+ psa_key_policy_t *policy);
+
+/**@}*/
+
/** \defgroup to_handle Key creation to allocated handle
* @{
*
@@ -248,6 +357,51 @@
psa_key_id_t id,
psa_key_handle_t *handle);
+/** Allocate a key slot for a transient key, i.e. a key which is only stored
+ * in volatile memory.
+ *
+ * The allocated key slot and its handle remain valid until the
+ * application calls psa_close_key() or psa_destroy_key() or until the
+ * application terminates.
+ *
+ * \param[out] handle On success, a handle to a volatile key slot.
+ *
+ * \retval #PSA_SUCCESS
+ * Success. The application can now use the value of `*handle`
+ * to access the newly allocated key slot.
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * There was not enough memory, or the maximum number of key slots
+ * has been reached.
+ */
+psa_status_t psa_allocate_key(psa_key_handle_t *handle);
+
+/**
+ * \brief Get basic metadata about a key.
+ *
+ * \param handle Handle to the key slot to query.
+ * \param[out] type On success, the key type (a \c PSA_KEY_TYPE_XXX value).
+ * This may be a null pointer, in which case the key type
+ * is not written.
+ * \param[out] bits On success, the key size in bits.
+ * This may be a null pointer, in which case the key size
+ * is not written.
+ *
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_INVALID_HANDLE
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
+ * The handle is to a key slot which does not contain key material yet.
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ * The library has not been previously initialized by psa_crypto_init().
+ * It is implementation-dependent whether a failure to initialize
+ * results in this error code.
+ */
+psa_status_t psa_get_key_information(psa_key_handle_t handle,
+ psa_key_type_t *type,
+ size_t *bits);
+
/** \brief Retrieve the lifetime of an open key.
*
* \param handle Handle to query.
diff --git a/include/psa/crypto_struct.h b/include/psa/crypto_struct.h
index 51c9402..273f6b6 100644
--- a/include/psa/crypto_struct.h
+++ b/include/psa/crypto_struct.h
@@ -252,6 +252,7 @@
psa_key_usage_t usage;
psa_algorithm_t alg;
};
+typedef struct psa_key_policy_s psa_key_policy_t;
#define PSA_KEY_POLICY_INIT {0, 0}
static inline struct psa_key_policy_s psa_key_policy_init( void )