Autonomous random driver: declare the type and function

Define a sample type mbedtls_psa_external_random_context_t in
psa/crypto_platform.h and define the prototype of
mbedtls_psa_external_get_random() in a public header.

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

include/mbedtls/config.h

@@ -1342,9 +1342,10 @@
  * Make the PSA Crypto module use an external random generator provided
  * by a driver, instead of Mbed TLS's entropy and DRBG modules.
  *
- * If you enable this option, you must supply a type called
+ * If you enable this option, you must supply configure the type
- * \c mbedtls_psa_external_random_context_t and a function called
+ * ::mbedtls_psa_external_random_context_t in psa/crypto_platform.h
- * mbedtls_psa_external_get_random() with the following prototype:
+ * and define a function called mbedtls_psa_external_get_random()
+ * with the following prototype:
  * ```
  * psa_status_t mbedtls_psa_external_get_random(
  *     mbedtls_psa_external_random_context_t *context,

include/psa/crypto_extra.h

@@ -649,6 +649,36 @@ mbedtls_ecp_group_id mbedtls_ecc_group_of_psa( psa_ecc_family_t curve,
 
 /**@}*/
 
+/** \defgroup psa_external_rng External random generator
+ * @{
+ */
+
+#if defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG)
+/** External random generator function, implemented by the platform.
+ *
+ * When the compile-time option #MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG is enabled,
+ * this function replaces Mbed TLS's entropy and DRBG modules for all
+ * random generation triggered via PSA crypto interfaces.
+ *
+ * \param[in,out] context       Pointer to the random generator context.
+ *                              This is all-bits-zero on the first call
+ *                              and preserved between successive calls.
+ * \param[out] output           Output buffer. On success, this buffer
+ *                              contains random data with a uniform
+ *                              distribution.
+ * \param output_size           The size of the \p output buffer in bytes.
+ * \param[out] output_length    On success, set this value to \p output_size.
+ *
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ */
+psa_status_t mbedtls_psa_external_get_random(
+    mbedtls_psa_external_random_context_t *context,
+    uint8_t *output, size_t output_size, size_t *output_length );
+#endif /* MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG */
+
+/**@}*/
+
 #ifdef __cplusplus
 }
 #endif

include/psa/crypto_platform.h

@@ -81,4 +81,10 @@ static inline int mbedtls_key_owner_id_equal( mbedtls_key_owner_id_t id1,
 
 #endif /* MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER */
 
+#if defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG)
+typedef struct {
+    uint8_t opaque[32];
+} mbedtls_psa_external_random_context_t;
+#endif /* MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG */
+
 #endif /* PSA_CRYPTO_PLATFORM_H */