/**
 * \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 The Mbed TLS Contributors
 *  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 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)(void *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)(void *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 {
    /** The driver-specific size of the entropy context */
    const size_t                context_size;
    /** 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 */