From 9e7dc717b05296f4459c173d85b32f316167355e Mon Sep 17 00:00:00 2001
From: Gilles Peskine <Gilles.Peskine@arm.com>
Date: Wed, 28 Mar 2018 14:18:50 +0200
Subject: [PATCH] New function: generate key/random

---
 include/psa/crypto.h | 65 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index d9c8fed6e..3835ce46d 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -1440,6 +1440,71 @@ psa_status_t psa_asymmetric_decrypt(psa_key_slot_t key,
 
 /**@}*/
 
+/** \defgroup generation Key generation
+ * @{
+ */
+
+/**
+ * \brief Generate random bytes.
+ *
+ * \warning This function **can** fail! Callers MUST check the return status
+ *          and MUST NOT use the content of the output buffer if the return
+ *          status is not #PSA_SUCCESS.
+ *
+ * \note    To generate a key, use psa_generate_key() instead.
+ *
+ * \param output            Output buffer for the generated data.
+ * \param output_size       Number of bytes to generate and output.
+ *
+ * \retval PSA_SUCCESS
+ * \retval PSA_ERROR_NOT_SUPPORTED
+ * \retval PSA_ERROR_INSUFFICIENT_ENTROPY
+ * \retval PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval PSA_ERROR_HARDWARE_FAILURE
+ * \retval PSA_ERROR_TAMPERING_DETECTED
+ */
+psa_status_t psa_generate_random(uint8_t *output,
+                                 size_t output_size);
+
+/**
+ * \brief Generate a key or key pair.
+ *
+ * \param key         Slot where the key will be stored. This must be a
+ *                    valid slot for a key of the chosen type. It must
+ *                    be unoccupied.
+ * \param type        Key type (a \c PSA_KEY_TYPE_XXX value).
+ * \param bits        Key size in bits.
+ * \param parameters  Extra parameters for key generation. The interpretation
+ *                    of this parameter depends on \c type. All types support
+ *                    \c NULL to use default parameters specified below.
+ *
+ * For any symmetric key type (type such that
+ * `PSA_KEY_TYPE_IS_ASYMMETRIC(type)` is false), \c parameters must be
+ * \c NULL. For asymmetric key types defined by this specification,
+ * the parameter type and the default parameters are defined by the
+ * table below. For vendor-defined key types, the vendor documentation
+ * shall define the parameter type and the default parameters.
+ *
+ * Type | Parameter type | Default parameters
+ * ---- | -------------- | ------------------
+ * `PSA_KEY_TYPE_RSA_KEYPAIR` | `unsigned int` | 65537
+ *
+ * \retval PSA_SUCCESS
+ * \retval PSA_ERROR_NOT_SUPPORTED
+ * \retval PSA_ERROR_INVALID_ARGUMENT
+ * \retval PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval PSA_ERROR_INSUFFICIENT_ENTROPY
+ * \retval PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval PSA_ERROR_HARDWARE_FAILURE
+ * \retval PSA_ERROR_TAMPERING_DETECTED
+ */
+psa_status_t psa_generate_key(psa_key_slot_t key,
+                              psa_key_type_t type,
+                              size_t bits,
+                              const void *parameters);
+
+/**@}*/
+
 #ifdef __cplusplus
 }
 #endif