1 /* 2 * This file is part of the openHiTLS project. 3 * 4 * openHiTLS is licensed under the Mulan PSL v2. 5 * You can use this software according to the terms and conditions of the Mulan PSL v2. 6 * You may obtain a copy of Mulan PSL v2 at: 7 * 8 * http://license.coscl.org.cn/MulanPSL2 9 * 10 * THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, 11 * EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, 12 * MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE. 13 * See the Mulan PSL v2 for more details. 14 */ 15 16 #ifndef CRYPT_EAL_ENTROPY_H 17 #define CRYPT_EAL_ENTROPY_H 18 19 #include <stdbool.h> 20 #include <stdint.h> 21 #include "crypt_algid.h" 22 #include "crypt_types.h" 23 24 #ifdef __cplusplus 25 extern "C" { 26 #endif 27 28 typedef struct CryptEalEntropySource CRYPT_EAL_Es; 29 30 /** 31 * @ingroup crypt_eal_entropy 32 * @brief Generate entropy source handle. 33 * @attention If the function is called by an external user and the error stack is concerned, 34 * it is recommended that BSL_ERR_ClearError() be called before this function is called. 35 * 36 * @return Success: entropy source ctx. 37 * Fails: NULL. 38 */ 39 CRYPT_EAL_Es *CRYPT_EAL_EsNew(void); 40 41 /** 42 * @ingroup crypt_eal_entropy 43 * @brief Release the entropy source handle. 44 * @attention If the function is called by an external user and the error stack is concerned, it is recommended 45 * that BSL_ERR_ClearError() be called before this function is called. 46 * 47 * @param es [IN] the entropy source handle. The CTX is set null by the caller. 48 * @return None 49 */ 50 void CRYPT_EAL_EsFree(CRYPT_EAL_Es *es); 51 52 /** 53 * @ingroup crypt_eal_entropy 54 * @brief Initialize the handle. 55 * @attention If the function is called by an external user and the error stack is concerned, 56 * you are advised to call BSL_ERR_ClearError() before calling this function. 57 * 58 * @param es [IN] the entropy source handle. 59 * @return CRYPT_SUCCESS,success 60 * For other error codes, see crypt_errno.h. 61 */ 62 int32_t CRYPT_EAL_EsInit(CRYPT_EAL_Es *es); 63 64 /** 65 * @ingroup crypt_eal_entropy 66 * @brief Set the mode ctx parameters in the CTX. 67 * parameter data type Length(len):number of data bytes 68 * CRYPT_ENTROPY_SET_CF string Adjust the length of the function type name. For example, 69 if the function type name is sm3-df, the length is 6. 70 This interface can be invoked only once before the 71 CRYPT_EAL_EsInit interface is invoked. 72 * CRYPT_ENTROPY_SET_POOL_SIZE uint32_t Specifies the size of the entropy pool. The recommended value 73 ranges from 512 to 4096. The default value is 4096. 74 Can only be called before CRYPT_EAL_EsInit interface. 75 * CRYPT_ENTROPY_ADD_NS CRYPT_EAL_NsPara Add a noise source.Repeated noise sources cannot be added. 76 Whether a noise source is repeated is determined based on the 77 name. 78 The length is the size of the CRYPT_EAL_NsPara structure. 79 Can only be called before CRYPT_EAL_EsInit interface. 80 * CRYPT_ENTROPY_REMOVE_NS string Length of the entropy source name. 81 Can only be called before CRYPT_EAL_EsInit interface. 82 When an entropy source is created, two noise sources are carried 83 by default, that is, timeStamp and CPU-Jitter. If the noise 84 sources are not required, you can delete them by using this 85 interface. 86 * CRYPT_ENTROPY_ENABLE_TEST bool Sets whether to enable the health test, length is 1. 87 Can only be called before CRYPT_EAL_EsInit interface. 88 * CRYPT_ENTROPY_GET_STATE uint32_t Obtains the current entropy source status, length is 4. 89 Can only be called after CRYPT_EAL_EsInit interface. 90 * CRYPT_ENTROPY_GET_POOL_SIZE uint32_t Obtains the total entropy pool capacity, length is 4. 91 Can only be called after CRYPT_EAL_EsInit interface. 92 * CRYPT_ENTROPY_POOL_GET_CURRSIZE uint32_t Obtains the current entropy pool capacity, length is 4. 93 Can only be called after CRYPT_EAL_EsInit interface. 94 * CRYPT_ENTROPY_GET_CF_SIZE uint32_t Get the size of the conditioning function, length is 4. 95 Can only be called after CRYPT_EAL_EsInit interface. 96 * @attention If the function is called by an external user and the error stack is concerned, 97 * it is recommended that BSL_ERR_ClearError() be called before this function is called. 98 * @param es [IN] the entropy source handle 99 * @param type [IN] Parameter type 100 * @param data [IN/OUT] Input and output data 101 * @param len [IN] Data length 102 * @return Success response: CRYPT_SUCCESS 103 * error codes see the crypt_errno.h 104 */ 105 int32_t CRYPT_EAL_EsCtrl(CRYPT_EAL_Es *es, int32_t type, void *data, uint32_t len); 106 107 /** 108 * @ingroup crypt_eal_entropy 109 * @brief Get Entropy Output. 110 * 111 * @param es [IN] the entropy source handle. 112 * @param data [OUT] Output data 113 * @param len [IN] Data length 114 * @return CRYPT_SUCCESS, success 115 * Other error codes see crypt_errno.h 116 */ 117 uint32_t CRYPT_EAL_EsEntropyGet(CRYPT_EAL_Es *es, uint8_t *data, uint32_t len); 118 119 typedef struct EAL_SeedPool CRYPT_EAL_SeedPoolCtx; 120 121 /** 122 * @ingroup crypt_eal_entropy 123 * @brief Creating an seed pool. 124 * 125 * @param isCreateNullPool [IN] Whether the entropy pool provides a default entropy source. 126 * @return success: seed pool ctx. 127 * failed: NULL 128 */ 129 CRYPT_EAL_SeedPoolCtx *CRYPT_EAL_SeedPoolNew(bool isCreateNullPool); 130 131 /** 132 * @ingroup crypt_eal_entropy 133 * @brief Adding an entropy source. 134 * 135 * @param ctx [IN] seed pool ctx. 136 * @param para [IN] Entropy Source para. 137 * @return Success: CRYPT_SUCCESS. 138 * failed: Other error codes see crypt_errno.h 139 */ 140 int32_t CRYPT_EAL_SeedPoolAddEs(CRYPT_EAL_SeedPoolCtx *ctx, const CRYPT_EAL_EsPara *para); 141 142 /** 143 * @ingroup crypt_eal_entropy 144 * @brief get entropy data. 145 * 146 * @param ctx [IN] seed pool ctx. 147 * @param entropy [OUT] obtained entropy data. 148 * @param strength [IN] the amount of entropy required. 149 * @param lenRange [IN] entropy data range. 150 * @return null. 151 */ 152 int32_t CRYPT_EAL_SeedPoolGetEntropy(CRYPT_EAL_SeedPoolCtx *ctx, CRYPT_Data *entropy, uint32_t strength, 153 const CRYPT_Range *lenRange); 154 155 /** 156 * @ingroup crypt_eal_entropy 157 * @brief release entropy source. 158 * 159 * @param ctx [IN] seed pool ctx. 160 * @return null. 161 */ 162 void CRYPT_EAL_SeedPoolFree(CRYPT_EAL_SeedPoolCtx *ctx); 163 164 #ifdef __cplusplus 165 } 166 #endif 167 #endif 168