Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
crypto_entropy_driver.h
Go to the documentation of this file.
1 /**
2  * \file psa/crypto_entropy_driver.h
3  * \brief PSA entropy source driver module
4  *
5  * This header declares types and function signatures for entropy sources.
6  *
7  * This file is part of the PSA Crypto Driver Model, containing functions for
8  * driver developers to implement to enable hardware to be called in a
9  * standardized way by a PSA Cryptographic API implementation. The functions
10  * comprising the driver model, which driver authors implement, are not
11  * intended to be called by application developers.
12  */
13 
14 /*
15  * Copyright The Mbed TLS Contributors
16  * SPDX-License-Identifier: Apache-2.0
17  *
18  * Licensed under the Apache License, Version 2.0 (the "License"); you may
19  * not use this file except in compliance with the License.
20  * You may obtain a copy of the License at
21  *
22  * http://www.apache.org/licenses/LICENSE-2.0
23  *
24  * Unless required by applicable law or agreed to in writing, software
25  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
26  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
27  * See the License for the specific language governing permissions and
28  * limitations under the License.
29  */
30 #ifndef PSA_CRYPTO_ENTROPY_DRIVER_H
31 #define PSA_CRYPTO_ENTROPY_DRIVER_H
32 
33 #include "crypto_driver_common.h"
34 
35 #ifdef __cplusplus
36 extern "C" {
37 #endif
38 
39 /** \defgroup driver_rng Entropy Generation
40  */
41 /**@{*/
42 
43 /** \brief Initialize an entropy driver
44  *
45  *
46  * \param[in,out] p_context A hardware-specific structure
47  * containing any context information for
48  * the implementation
49  *
50  * \retval #PSA_SUCCESS
51  */
52 typedef psa_status_t (*psa_drv_entropy_init_t)(void *p_context);
53 
54 /** \brief Get a specified number of bits from the entropy source
55  *
56  * It retrives `buffer_size` bytes of data from the entropy source. The entropy
57  * source will always fill the provided buffer to its full size, however, most
58  * entropy sources have biases, and the actual amount of entropy contained in
59  * the buffer will be less than the number of bytes.
60  * The driver will return the actual number of bytes of entropy placed in the
61  * buffer in `p_received_entropy_bytes`.
62  * A PSA Crypto API implementation will likely feed the output of this function
63  * into a Digital Random Bit Generator (DRBG), and typically has a minimum
64  * amount of entropy that it needs.
65  * To accomplish this, the PSA Crypto implementation should be designed to call
66  * this function multiple times until it has received the required amount of
67  * entropy from the entropy source.
68  *
69  * \param[in,out] p_context A hardware-specific structure
70  * containing any context information
71  * for the implementation
72  * \param[out] p_buffer A caller-allocated buffer for the
73  * retrieved entropy to be placed in
74  * \param[in] buffer_size The allocated size of `p_buffer`
75  * \param[out] p_received_entropy_bits The amount of entropy (in bits)
76  * actually provided in `p_buffer`
77  *
78  * \retval #PSA_SUCCESS
79  */
80 typedef psa_status_t (*psa_drv_entropy_get_bits_t)(void *p_context,
81  uint8_t *p_buffer,
82  uint32_t buffer_size,
83  uint32_t *p_received_entropy_bits);
84 
85 /**
86  * \brief A struct containing all of the function pointers needed to interface
87  * to an entropy source
88  *
89  * PSA Crypto API implementations should populate instances of the table as
90  * appropriate upon startup.
91  *
92  * If one of the functions is not implemented, it should be set to NULL.
93  */
94 typedef struct {
95  /** The driver-specific size of the entropy context */
96  const size_t context_size;
97  /** Function that performs initialization for the entropy source */
98  psa_drv_entropy_init_t p_init;
99  /** Function that performs the get_bits operation for the entropy source */
100  psa_drv_entropy_get_bits_t p_get_bits;
101 } psa_drv_entropy_t;
102 /**@}*/
103 
104 #ifdef __cplusplus
105 }
106 #endif
107 
108 #endif /* PSA_CRYPTO_ENTROPY_DRIVER_H */
psa_drv_entropy_init_t
psa_status_t(* psa_drv_entropy_init_t)(void *p_context)
Initialize an entropy driver.
Definition: crypto_entropy_driver.h:52
psa_drv_entropy_t::p_init
psa_drv_entropy_init_t p_init
Function that performs initialization for the entropy source.
Definition: crypto_entropy_driver.h:98
psa_drv_entropy_t::p_get_bits
psa_drv_entropy_get_bits_t p_get_bits
Function that performs the get_bits operation for the entropy source.
Definition: crypto_entropy_driver.h:100
psa_drv_entropy_t
A struct containing all of the function pointers needed to interface to an entropy source...
Definition: crypto_entropy_driver.h:94
psa_drv_entropy_get_bits_t
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)
Get a specified number of bits from the entropy source.
Definition: crypto_entropy_driver.h:80
crypto_driver_common.h
Definitions for all PSA crypto drivers.
psa_drv_entropy_t::context_size
const size_t context_size
The driver-specific size of the entropy context.
Definition: crypto_entropy_driver.h:96
psa_status_t
int32_t psa_status_t
Function return status.
Definition: TARGET_MBED_PSA_SRV/inc/psa/crypto_types.h:55
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.