Merge pull request Mbed-TLS#240 from ARMmbed/psa-header_split

Split type definitions out of crypto.h and split crypto_driver.h

include/psa/crypto_driver_common.h

@@ -0,0 +1,54 @@
+/**
+ * \file psa/crypto_driver_common.h
+ * \brief Definitions for all PSA crypto drivers
+ *
+ * This file contains common definitions shared by all PSA crypto drivers.
+ * Do not include it directly: instead, include the header file(s) for
+ * the type(s) of driver that you are implementing. For example, if
+ * you are writing a driver for a chip that provides both a hardware
+ * random generator and an accelerator for some cryptographic algorithms,
+ * include `psa/crypto_entropy_driver.h` and `psa/crypto_accel_driver.h`.
+ *
+ * This file is part of the PSA Crypto Driver Model, containing functions for
+ * driver developers to implement to enable hardware to be called in a
+ * standardized way by a PSA Cryptographic API implementation. The functions
+ * comprising the driver model, which driver authors implement, are not
+ * intended to be called by application developers.
+ */
+
+/*
+ *  Copyright (C) 2018, ARM Limited, All Rights Reserved
+ *  SPDX-License-Identifier: Apache-2.0
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *  not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+#ifndef PSA_CRYPTO_DRIVER_COMMON_H
+#define PSA_CRYPTO_DRIVER_COMMON_H
+
+#include <stddef.h>
+#include <stdint.h>
+
+/* Include type definitions (psa_status_t, psa_algorithm_t,
+ * psa_key_type_t, etc.) and macros to build and analyze values
+ * of these types. */
+#include "crypto_types.h"
+#include "crypto_values.h"
+
+/** For encrypt-decrypt functions, whether the operation is an encryption
+ * or a decryption. */
+typedef enum {
+    PSA_CRYPTO_DRIVER_DECRYPT,
+    PSA_CRYPTO_DRIVER_ENCRYPT
+} psa_encrypt_or_decrypt_t;
+
+#endif /* PSA_CRYPTO_DRIVER_COMMON_H */

include/psa/crypto_entropy_driver.h

@@ -0,0 +1,111 @@
+/**
+ * \file psa/crypto_entropy_driver.h
+ * \brief PSA entropy source driver module
+ *
+ * This header declares types and function signatures for entropy sources.
+ *
+ * This file is part of the PSA Crypto Driver Model, containing functions for
+ * driver developers to implement to enable hardware to be called in a
+ * standardized way by a PSA Cryptographic API implementation. The functions
+ * comprising the driver model, which driver authors implement, are not
+ * intended to be called by application developers.
+ */
+
+/*
+ *  Copyright (C) 2018, ARM Limited, All Rights Reserved
+ *  SPDX-License-Identifier: Apache-2.0
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *  not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+#ifndef PSA_CRYPTO_ENTROPY_DRIVER_H
+#define PSA_CRYPTO_ENTROPY_DRIVER_H
+
+#include "crypto_driver_common.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** \defgroup driver_rng Entropy Generation
+ */
+/**@{*/
+
+/** \brief A hardware-specific structure for a entropy providing hardware
+ */
+typedef struct psa_drv_entropy_context_s psa_drv_entropy_context_t;
+
+/** \brief Initialize an entropy driver
+ *
+ *
+ * \param[in,out] p_context             A hardware-specific structure
+ *                                      containing any context information for
+ *                                      the implementation
+ *
+ * \retval PSA_SUCCESS
+ */
+typedef psa_status_t (*psa_drv_entropy_init_t)(psa_drv_entropy_context_t *p_context);
+
+/** \brief Get a specified number of bits from the entropy source
+ *
+ * It retrives `buffer_size` bytes of data from the entropy source. The entropy
+ * source will always fill the provided buffer to its full size, however, most
+ * entropy sources have biases, and the actual amount of entropy contained in
+ * the buffer will be less than the number of bytes.
+ * The driver will return the actual number of bytes of entropy placed in the
+ * buffer in `p_received_entropy_bytes`.
+ * A PSA Crypto API implementation will likely feed the output of this function
+ * into a Digital Random Bit Generator (DRBG), and typically has a minimum
+ * amount of entropy that it needs.
+ * To accomplish this, the PSA Crypto implementation should be designed to call
+ * this function multiple times until it has received the required amount of
+ * entropy from the entropy source.
+ *
+ * \param[in,out] p_context                 A hardware-specific structure
+ *                                          containing any context information
+ *                                          for the implementation
+ * \param[out] p_buffer                     A caller-allocated buffer for the
+ *                                          retrieved entropy to be placed in
+ * \param[in] buffer_size                   The allocated size of `p_buffer`
+ * \param[out] p_received_entropy_bits      The amount of entropy (in bits)
+ *                                          actually provided in `p_buffer`
+ *
+ * \retval PSA_SUCCESS
+ */
+typedef psa_status_t (*psa_drv_entropy_get_bits_t)(psa_drv_entropy_context_t *p_context,
+                                                   uint8_t *p_buffer,
+                                                   uint32_t buffer_size,
+                                                   uint32_t *p_received_entropy_bits);
+
+/**
+ * \brief A struct containing all of the function pointers needed to interface
+ * to an entropy source
+ *
+ * PSA Crypto API implementations should populate instances of the table as
+ * appropriate upon startup.
+ *
+ * If one of the functions is not implemented, it should be set to NULL.
+ */
+typedef struct {
+    /** Function that performs initialization for the entropy source */
+    psa_drv_entropy_init_t *p_init;
+    /** Function that performs the get_bits operation for the entropy source
+    */
+    psa_drv_entropy_get_bits_t *p_get_bits;
+} psa_drv_entropy_t;
+/**@}*/
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* PSA_CRYPTO_ENTROPY_DRIVER_H */