Declare key binding functions

gilles-peskine-arm · gilles-peskine-arm · commit 3cb715b9c4dd · 2020-02-12T18:45:31.000+01:00
Declare functions to wrap and unwrap a key together with its metadata,
in an unspecified vendor-specific format but with an explicitly
specified key.

Declare a corresponding usage flag.
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
@@ -854,6 +854,135 @@ psa_status_t psa_export_public_key(psa_key_handle_t handle,
                                    size_t data_size,
                                    size_t *data_length);
 
+/**
+ * \brief Export a key and its metadata in wrapped form.
+ *
+ * A wrapped form of the key object preserves the confidentiality and
+ * authenticity of the key material and the authenticity of the key
+ * policy. In practical terms, the key material is encrypted, and
+ * the key data and metadata are authenticated together.
+ *
+ * The format of the wrapped data is implementation-dependent. It may depend
+ * both on the choice of wrapping key and on the type of key to wrap.
+ *
+ * The policy on the key must have the usage flag
+ * #PSA_KEY_USAGE_EXPORT_WRAPPED set.
+ *
+ * \param wrapping_key      Handle to the key to wrap with.
+ * \param handle            Handle to the key to export in wrapped form.
+ * \param[out] data         Buffer where the wrapped key data is to be written.
+ * \param data_size         Size of the \p data buffer in bytes.
+ * \param[out] data_length  On success, the number of bytes
+ *                          that make up the wrapped key data.
+ *
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_INVALID_HANDLE
+ *         One or both of \p handle and \p wrapping_key is not a valid
+ *         handle to a key.
+ * \retval #PSA_ERROR_NOT_PERMITTED
+ *         The key \p handle does not have the #PSA_KEY_USAGE_BACKUP flag.
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ *         \p wrapping_key does not support wrapping keys with metadata.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ *         \p wrapping_key does not support wrapping the key designated
+ *         by \p handle.
+ * \retval #PSA_ERROR_BUFFER_TOO_SMALL
+ *         The size of the \p data buffer is too small. You can determine a
+ *         sufficient buffer size by calling
+ *         #PSA_WRAP_KEY_WITH_POLICY_OUTPUT_SIZE(\c type, \c bits)
+ *         where \c type is the key type of \p handle
+ *         and \c bits is the key size of \p handle in bits.
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \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_wrap_key_with_policy(psa_key_handle_t wrapping_key,
+                                      psa_key_handle_t handle,
+                                      uint8_t *data,
+                                      size_t data_size,
+                                      size_t *data_length);
+
+/**
+ * \brief Import a wrapped key with its metadata.
+ *
+ * This function supports any output from psa_wrap_key_with_policy().
+ * For symmetric wrapping, you must unwrap with the same key that was
+ * used to wrap. For asymmetric wrapping where the wrapping operation uses
+ * a public key and the unwrapping operation uses the corresponding private
+ * key, you must unwrap with the corresponding unwrapping key.
+ *
+ * \param wrapping_key      Handle to the key to unwrap with.
+ * \param[in] attributes    The attributes for the new key.
+ *                          They are used as follows:
+ *                          - The key type and size may be 0. If either is
+ *                            nonzero, it must match the corresponding
+ *                            attribute of the wrapped key data.
+ *                          - The key location (the lifetime and, for
+ *                            persistent keys, the key identifier) is
+ *                            used directly.
+ *                            If the wrapped key does not have the usage
+ *                            flag #PSA_KEY_USAGE_COPY, then the location
+ *                            must match the location embedded in \p data.
+ *                            If the wrapped key has the usage
+ *                            flag #PSA_KEY_USAGE_COPY, then the location
+ *                            embedded in \p data is ignored.
+ *                          - The policy constraints (usage flags and
+ *                            algorithm policy) are combined from
+ *                            the wrapped key data and \p attributes so that
+ *                            both sets of restrictions apply. The
+ *                            policy restrictions are calculated in the
+ *                            same way as in psa_copy_key().
+ * \param[in] data          Buffer containing the wrapped key material.
+ *                          The expected format of this buffer depends
+ *                          on the wrapping key.
+ * \param data_length       Size of the \p data buffer in bytes.
+ * \param[out] handle       On success, a handle to the newly created key.
+ *                          \c 0 on failure.
+ *
+ * \retval #PSA_SUCCESS
+ *         Success.
+ *         If the unwrapped key is persistent, the key material and the
+ *         key's metadata have been saved to persistent storage.
+ * \retval #PSA_ERROR_ALREADY_EXISTS
+ *         This is an attempt to create a persistent key, and there is
+ *         already a persistent key with the given identifier.
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ *         The key attributes, as a whole, are invalid.
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ *         The key data is not correctly formatted.
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ *         The size in \p attributes is nonzero and does not match the size
+ *         of the key data.
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ *         \p wrapping_key does not support unwrapping keys with metadata.
+ * \retval #PSA_ERROR_INVALID_SIGNATURE
+ *         \p data is not a valid wrapped key for \p wrapping_key.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ *         Some of the metadata in either \p attributes or \p data is
+ *         not supported.
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_CORRUPTION_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_unwrap_key_with_policy(psa_key_handle_t wrapping_key,
+                                        const psa_key_attributes_t *attributes,
+                                        const uint8_t *data,
+                                        size_t data_length,
+                                        psa_key_handle_t *handle);
+
 
 
 /**@}*/
diff --git a/include/psa/crypto_sizes.h b/include/psa/crypto_sizes.h
@@ -659,4 +659,29 @@
      PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY(key_type) ? PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_bits) : \
      0)
 
+/** Sufficient output buffer size for psa_wrap_key_with_policy().
+ *
+ * This macro returns a compile-time constant if its arguments are
+ * compile-time constants.
+ *
+ * \warning This function may call its arguments multiple times or
+ *          zero times, so you should not pass arguments that contain
+ *          side effects.
+ *
+ * \param key_type  A supported key type.
+ * \param key_bits  The size of the key in bits.
+ *
+ * \return If the parameters are valid and supported, return
+ *         a buffer size in bytes that guarantees that
+ *         psa_wrap_key_with_policy() will not fail with
+ *         #PSA_ERROR_BUFFER_TOO_SMALL.
+ *         If the parameters are a valid combination that is not supported
+ *         by the implementation, this macro shall return either a
+ *         sensible size or 0.
+ *         If the parameters are not valid, the
+ *         return value is unspecified.
+ */
+#define PSA_WRAP_KEY_WITH_POLICY_OUTPUT_SIZE(key_type, key_bits)        \
+    0u /*not implemented yet*/
+
 #endif /* PSA_CRYPTO_SIZES_H */
diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h
@@ -1606,6 +1606,19 @@
  */
 #define PSA_KEY_USAGE_COPY                      ((psa_key_usage_t)0x00000002)
 
+/** Whether the key object may be saved outside the device in wrapped form.
+ * This is also known as key binding.
+ *
+ * This flag allows the use of psa_wrap_key_with_policy() on the given key,
+ * with any suitable wrapping key.
+ *
+ * A wrapped form of the key object preserves the confidentiality and
+ * authenticity of the key material and the authenticity of the key
+ * policy. In practical terms, the key material is encrypted, and
+ * the key data and metadata are authenticated together.
+ */
+#define PSA_KEY_USAGE_BACKUP                    ((psa_key_usage_t)0x00000020)
+
 /** Whether the key may be used to encrypt a message.
  *
  * This flag allows the key to be used for a symmetric encryption operation,
