crypto_entropy_driver.h

00001 /**
00002  * \file psa/crypto_entropy_driver.h
00003  * \brief PSA entropy source driver module
00004  *
00005  * This header declares types and function signatures for entropy sources.
00006  *
00007  * This file is part of the PSA Crypto Driver Model, containing functions for
00008  * driver developers to implement to enable hardware to be called in a
00009  * standardized way by a PSA Cryptographic API implementation. The functions
00010  * comprising the driver model, which driver authors implement, are not
00011  * intended to be called by application developers.
00012  */
00013 
00014 /*
00015  *  Copyright (C) 2018, ARM Limited, All Rights Reserved
00016  *  SPDX-License-Identifier: Apache-2.0
00017  *
00018  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00019  *  not use this file except in compliance with the License.
00020  *  You may obtain a copy of the License at
00021  *
00022  *  http://www.apache.org/licenses/LICENSE-2.0
00023  *
00024  *  Unless required by applicable law or agreed to in writing, software
00025  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00026  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00027  *  See the License for the specific language governing permissions and
00028  *  limitations under the License.
00029  */
00030 #ifndef PSA_CRYPTO_ENTROPY_DRIVER_H
00031 #define PSA_CRYPTO_ENTROPY_DRIVER_H
00032 
00033 #include "crypto_driver_common.h"
00034 
00035 #ifdef __cplusplus
00036 extern "C" {
00037 #endif
00038 
00039 /** \defgroup driver_rng Entropy Generation
00040  */
00041 /**@{*/
00042 
00043 /** \brief Initialize an entropy driver
00044  *
00045  *
00046  * \param[in,out] p_context             A hardware-specific structure
00047  *                                      containing any context information for
00048  *                                      the implementation
00049  *
00050  * \retval PSA_SUCCESS
00051  */
00052 typedef psa_status_t (*psa_drv_entropy_init_t)(void *p_context);
00053 
00054 /** \brief Get a specified number of bits from the entropy source
00055  *
00056  * It retrives `buffer_size` bytes of data from the entropy source. The entropy
00057  * source will always fill the provided buffer to its full size, however, most
00058  * entropy sources have biases, and the actual amount of entropy contained in
00059  * the buffer will be less than the number of bytes.
00060  * The driver will return the actual number of bytes of entropy placed in the
00061  * buffer in `p_received_entropy_bytes`.
00062  * A PSA Crypto API implementation will likely feed the output of this function
00063  * into a Digital Random Bit Generator (DRBG), and typically has a minimum
00064  * amount of entropy that it needs.
00065  * To accomplish this, the PSA Crypto implementation should be designed to call
00066  * this function multiple times until it has received the required amount of
00067  * entropy from the entropy source.
00068  *
00069  * \param[in,out] p_context                 A hardware-specific structure
00070  *                                          containing any context information
00071  *                                          for the implementation
00072  * \param[out] p_buffer                     A caller-allocated buffer for the
00073  *                                          retrieved entropy to be placed in
00074  * \param[in] buffer_size                   The allocated size of `p_buffer`
00075  * \param[out] p_received_entropy_bits      The amount of entropy (in bits)
00076  *                                          actually provided in `p_buffer`
00077  *
00078  * \retval PSA_SUCCESS
00079  */
00080 typedef psa_status_t (*psa_drv_entropy_get_bits_t)(void *p_context,
00081                                                    uint8_t *p_buffer,
00082                                                    uint32_t buffer_size,
00083                                                    uint32_t *p_received_entropy_bits);
00084 
00085 /**
00086  * \brief A struct containing all of the function pointers needed to interface
00087  * to an entropy source
00088  *
00089  * PSA Crypto API implementations should populate instances of the table as
00090  * appropriate upon startup.
00091  *
00092  * If one of the functions is not implemented, it should be set to NULL.
00093  */
00094 typedef struct {
00095     /** The driver-specific size of the entropy context */
00096     const size_t                context_size;
00097     /** Function that performs initialization for the entropy source */
00098     psa_drv_entropy_init_t      p_init;
00099     /** Function that performs the get_bits operation for the entropy source */
00100     psa_drv_entropy_get_bits_t  p_get_bits;
00101 } psa_drv_entropy_t;
00102 /**@}*/
00103 
00104 #ifdef __cplusplus
00105 }
00106 #endif
00107 
00108 #endif /* PSA_CRYPTO_ENTROPY_DRIVER_H */