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 /** 17 * @defgroup crypt_eal_rand 18 * @ingroup crypt 19 * @brief random number module 20 */ 21 22 #ifndef CRYPT_EAL_RAND_H 23 #define CRYPT_EAL_RAND_H 24 25 #include <stdbool.h> 26 #include <stdint.h> 27 #include "crypt_algid.h" 28 #include "crypt_types.h" 29 #include "crypt_eal_provider.h" 30 #include "bsl_params.h" 31 32 #ifdef __cplusplus 33 extern "C" { 34 #endif 35 36 /** 37 * @ingroup crypt_eal_rand 38 * @brief rand generate callback 39 * 40 * rand[out] randomdata 41 * randLen[in] len 42 * 43 * @return int32_t, defined by users. 44 */ 45 typedef int32_t (*CRYPT_EAL_RandFunc)(uint8_t *rand, uint32_t randLen); 46 47 /** 48 * @ingroup crypt_eal_rand 49 * @brief set rand func callback 50 * 51 * func[in] rand func 52 * 53 * @return void. 54 */ 55 void CRYPT_EAL_SetRandCallBack(CRYPT_EAL_RandFunc func); 56 57 /** 58 * @ingroup crypt_eal_rand 59 * @brief rand generate callback 60 * 61 * ctx[in] ctx 62 * rand[out] randomdata 63 * randLen[in] len 64 * 65 * @return int32_t, defined by users. 66 */ 67 typedef int32_t (*CRYPT_EAL_RandFuncEx)(void *ctx, uint8_t *rand, uint32_t randLen); 68 69 /** 70 * @ingroup crypt_eal_rand 71 * @brief set rand func callback 72 * 73 * func[in] rand func 74 * 75 * @return void. 76 */ 77 void CRYPT_EAL_SetRandCallBackEx(CRYPT_EAL_RandFuncEx func); 78 79 /** 80 * @ingroup crypt_eal_rand 81 * @brief Random number initialization interface. This interface does not support multiple threads. 82 * 83 * Initialize global random number to RAND, Entropy sources and addtional random numbers in the seed material 84 * which implemented by HiTLS. and this value is provided by the user. if user not provid the entropy source 85 * (seedMeth and seedCtx are both NULL), the default software entropy source is used. 86 * In addition, this interface does not support multiple threads. 87 * The global random number is initialized to the random generation algorithm described in Nist 800-90a. 88 * Application scenarios are as follows: 89 * 1. seedMeth == NULL && seedCtx == NULL ====> Use the default system entropy source in AES_CTR mode 90 * (that is, non-DF cannot use the default entropy source). 91 * 2. seedMeth == NULL && seedCtx != NULL ===> Error report. 92 * 3. seedMeth != NULL ====> This function can be used normally, seedCtx is not restricted, but make sure 93 * seedMeth can handle all kinds of situations. 94 * 95 * @attention: Support obtain or generate random numbers with multithreading, but not support initialization 96 * and deinitialization with multithreading. 97 * @param id [IN] RAND id 98 * @param seedMeth [IN] Seed method, which can be set NULL with seedCtx, The default entropy source is used 99 * or provided by the user. 100 * @param seedCtx [IN] Seed context information, which can be set NULL, But the seedMeth provided by the user can 101 * handle the situation where seedCtx is NULL. 102 * Generally, seedCtx needs to contain data such as entropy and nonce. 103 * @param pers [IN] Personal data, which can be NULL. 104 * @param persLen [IN] Length of the personal data, the length ranges from [0,0x7FFFFFF0]. 105 * @retval #CRYPT_SUCCESS, if successful. 106 * For other error codes, see the crypt_errno.h file. 107 */ 108 int32_t CRYPT_EAL_RandInit(CRYPT_RAND_AlgId id, CRYPT_RandSeedMethod *seedMeth, void *seedCtx, 109 const uint8_t *pers, uint32_t persLen); 110 111 /** 112 * @ingroup crypt_eal_rand 113 * @brief Random number initialization in the providers. 114 * 115 * @param libCtx [IN] Library context 116 * @param algId [IN] rand algorithm ID. 117 * @param attrName [IN] Specify expected attribute values 118 * @param pers [IN] Personal data, which can be NULL. 119 * @param persLen [IN] Personal data length. the range is [0,0x7FFFFFF0]. 120 * @param param [IN] Transparent transmission of underlying parameters 121 * 122 * @retval #CRYPT_SUCCESS, if successful. 123 * For other error codes, see the crypt_errno.h file. 124 */ 125 int32_t CRYPT_EAL_ProviderRandInitCtx(CRYPT_EAL_LibCtx *libCtx, int32_t algId, const char *attrName, 126 const uint8_t *pers, uint32_t persLen, BSL_Param *param); 127 128 /** 129 * @ingroup crypt_eal_rand 130 * @brief Deinitializing the global RAND interface, this interface does not support multiple threads. 131 * 132 * @retval void, no return value. 133 */ 134 void CRYPT_EAL_RandDeinit(void); 135 136 /** 137 * @ingroup crypt_eal_rand 138 * @brief Deinitializing the libCtx RAND interface, this interface does not support multiple threads. 139 * 140 * @param libCtx [IN] Library context 141 * 142 * @retval void, no return value. 143 */ 144 void CRYPT_EAL_RandDeinitEx(CRYPT_EAL_LibCtx *libCtx); 145 146 /** 147 * @ingroup crypt_eal_rand 148 * @brief Generate a random number. 149 * 150 * The addtional data marked as "addin" can be NULL, and additional data specified by the user. 151 * This interface does not support multiple threads. 152 * 153 * @param byte [OUT] Output random numbers, the memory is provided by the user. 154 * @param len [IN] Required random number length, the maximum length is (0, 65536]. 155 * @param addin [IN] Addtional data, which can set be NULL. 156 * @param addinLen [IN] Addtional data length, the maximum length is[0,0x7FFFFFF0]. 157 * @retval #CRYPT_SUCCESS, if successful. 158 * For other error codes, see the crypt_errno.h file. 159 */ 160 int32_t CRYPT_EAL_RandbytesWithAdin(uint8_t *byte, uint32_t len, uint8_t *addin, uint32_t addinLen); 161 162 /** 163 * @ingroup crypt_eal_rand 164 * @brief Generate a random number. 165 * 166 * The addtional data marked as "addin" can be NULL, and additional data specified by the user. 167 * This interface does not support multiple threads. 168 * 169 * @param libCtx [IN] Library context 170 * @param byte [OUT] Output random numbers, the memory is provided by the user. 171 * @param len [IN] Required random number length, the maximum length is (0, 65536]. 172 * @param addin [IN] Addtional data, which can set be NULL. 173 * @param addinLen [IN] Addtional data length, the maximum length is[0,0x7FFFFFF0]. 174 * @retval #CRYPT_SUCCESS, if successful. 175 * For other error codes, see the crypt_errno.h file. 176 */ 177 int32_t CRYPT_EAL_RandbytesWithAdinEx(CRYPT_EAL_LibCtx *libCtx, 178 uint8_t *byte, uint32_t len, uint8_t *addin, uint32_t addinLen); 179 180 /** 181 * @ingroup crypt_eal_rand 182 * 183 * Generate a random number, which is equivalent to CRYPT_EAL_RandbytesWithAdin(bytes, len, NULL, 0). 184 * This interface supports multi-thread access. 185 * 186 * @param byte [OUT] Used to store output random numbers, the memory is provided by the user. 187 * @param len [IN] Required random number length, the length range is(0, 65536]. 188 * @retval #CRYPT_SUCCESS, if successful. 189 * For other error codes, see the crypt_errno.h file. 190 */ 191 int32_t CRYPT_EAL_Randbytes(uint8_t *byte, uint32_t len); 192 193 /** 194 * @ingroup crypt_eal_rand 195 * 196 * Generate a random number 197 * This interface supports multi-thread access. 198 * 199 * @param libCtx [IN] Library context 200 * @param byte [OUT] Used to store output random numbers, the memory is provided by the user. 201 * @param len [IN] Required random number length, the length range is(0, 65536]. 202 * @retval #CRYPT_SUCCESS, if successful. 203 * For other error codes, see the crypt_errno.h file. 204 */ 205 int32_t CRYPT_EAL_RandbytesEx(CRYPT_EAL_LibCtx *libCtx, uint8_t *byte, uint32_t len); 206 207 /** 208 * @ingroup crypt_eal_rand 209 * @brief Regenerate the seed. 210 * 211 * @attention The addtional data can set be NULL, and this interface supports multi-thread access. 212 * @param addin [IN] Additional data, which can set be NULL. 213 * @param addinLen [IN] Addtional data length, the range is [0,0x7FFFFFF0]. 214 * @retval #CRYPT_SUCCESS, if successful. 215 * For other error codes, see crypt_errno.h. 216 * 217 * @note After forking, it is necessary to manually supplement the entropy source for the new program 218 */ 219 int32_t CRYPT_EAL_RandSeedWithAdin(uint8_t *addin, uint32_t addinLen); 220 221 /** 222 * @ingroup crypt_eal_rand 223 * 224 * Regenerate the seed, which is equivalent to CRYPT_EAL_RandSeedWithAdin(NULL, 0), and the interface 225 * supports multi-thread access. 226 * 227 * @retval #CRYPT_SUCCESS 228 * For other error codes, see crypt_errno.h. 229 * 230 * @note After forking, it is necessary to manually supplement the entropy source for the new program 231 */ 232 int32_t CRYPT_EAL_RandSeed(void); 233 234 /** 235 * @ingroup crypt_eal_rand 236 * 237 * Regenerate the seed, which is equivalent to CRYPT_EAL_RandSeedWithAdin(NULL, 0), and the interface 238 * supports multi-thread access. 239 * @param libCtx [IN] Library context 240 * @retval #CRYPT_SUCCESS 241 * For other error codes, see crypt_errno.h. 242 * 243 * @note After forking, it is necessary to manually supplement the entropy source for the new program 244 */ 245 int32_t CRYPT_EAL_RandSeedEx(CRYPT_EAL_LibCtx *libCtx); 246 247 typedef struct EAL_RndCtx CRYPT_EAL_RndCtx; 248 249 /** 250 * @ingroup CRYPT_EAL_DrbgNew 251 * @brief Random number initialization interface, and this interface does not support multiple threads. 252 * 253 * Initial DRBG with HiTLS, entropy source and addtional random number in the seed material 254 * are provided by users. This interface does not support multi-threading, the initial random number is 255 * the random number generation algorithm described in Nist 800-90a. 256 * Usage scenes are as follows: 257 * 1. seedMeth == NULL && seedCtx == NULL ====> Use the default system entropy source in AES_CTR mode 258 * (that is, non-DF cannot use the default entropy source). 259 * 2. seedMeth == NULL && seedCtx != NULL ===> error reported. 260 * 3. seedMeth != NULL ====> This function can be used normally, seedCtx function is not restricted, 261 * but make sure seedMeth can handle all kinds of situations. 262 * 263 * @attention Initialization and deinitialization 264 * @param id [IN] RAND id 265 * @param seedMeth [IN] Seed method, this parameter and seedCtx can be null at the same time. The default entropy 266 * source is used or provided by the user. 267 * @param seedCtx [IN] Seed context information, which can be NULL, but the seedMeth provided by the user needs 268 * to be able to handle the situation where seedCtx is null. 269 * seedCtx generally needs to contain the entropy source marked as "entropy", additional random number "nonce", and 270 * other data. 271 * @retval DRBG handle, if successful. 272 * NULL, if failed. 273 */ 274 CRYPT_EAL_RndCtx *CRYPT_EAL_DrbgNew(CRYPT_RAND_AlgId id, CRYPT_RandSeedMethod *seedMeth, void *seedCtx); 275 276 /** 277 * @ingroup crypt_eal_rand 278 * @brief Random number initialization in the providers. 279 * 280 * @param libCtx [IN] Library context 281 * @param algId [IN] rand algorithm ID. 282 * @param attrName [IN] Specify expected attribute values 283 * @param param [IN] Transparent transmission of underlying parameters 284 * 285 * @retval Success: cipher ctx. 286 * Fails: NULL. 287 */ 288 CRYPT_EAL_RndCtx *CRYPT_EAL_ProviderDrbgNewCtx(CRYPT_EAL_LibCtx *libCtx, int32_t algId, const char *attrName, 289 BSL_Param *param); 290 291 /** 292 * @ingroup CRYPT_EAL_DrbgDeinit 293 * @brief CRYPT_EAL_DrbgDeinit Deinitialization interface, this interface does not support multiple threads. 294 * 295 * @param ctx [IN] DRBG handle 296 * @retval Void, no value is returned. 297 */ 298 void CRYPT_EAL_DrbgDeinit(CRYPT_EAL_RndCtx *ctx); 299 300 /** 301 * @ingroup crypt_eal_rand 302 * @brief Generate a random number. 303 * 304 * @attention The addtional data can be NULL, user specifies the addtional data, 305 * and the interface supports multi-thread access. 306 * @param ctx [IN] DRBG handle 307 * @param byte [OUT] Outputs random numbers. the memory is provided by the user. 308 * @param len [IN] Required random number length. the range is (0, 65536]. 309 * @param addin [IN] Addtional data, which can be NULL. 310 * @param addinLen [IN] Addtional data length. the range is [0,0x7FFFFFF0]. 311 * @retval #CRYPT_SUCCESS, if successful. 312 * For other error codes, see the crypt_errno.h file. 313 */ 314 int32_t CRYPT_EAL_DrbgbytesWithAdin(CRYPT_EAL_RndCtx *ctx, uint8_t *byte, uint32_t len, uint8_t *addin, uint32_t addinLen); 315 316 /** 317 * @ingroup crypt_eal_rand 318 * 319 * Generate a random number, which is equivalent to CRYPT_EAL_RandbytesWithAdin(bytes, len, NULL, 0). 320 * This interface supports multi-thread access. 321 * 322 * @param ctx [IN] DRBG handle 323 * @param byte [OUT] Used to store output random numbers. the memory is provided by the user. 324 * @param len [IN] Required random number length. the range is (0, 65536]. 325 * @retval #CRYPT_SUCCESS, if successful. 326 * For other error codes, see the crypt_errno.h file. 327 */ 328 int32_t CRYPT_EAL_Drbgbytes(CRYPT_EAL_RndCtx *ctx, uint8_t *byte, uint32_t len); 329 330 /** 331 * @ingroup crypt_eal_rand 332 * @brief Regenerate the seed. The addtional data can be NULL. This interface supports multi-thread access. 333 * 334 * @param ctx [IN] DRBG handle 335 * @param addin [IN] Addtional data, which can be null. 336 * @param addinLen [IN] Addtional data length. The maximum length is [0,0x7FFFFFF0]. 337 * @retval #CRYPT_SUCCESS, if successful. 338 * For other error codes, see crypt_errno.h. 339 */ 340 int32_t CRYPT_EAL_DrbgSeedWithAdin(CRYPT_EAL_RndCtx *ctx, uint8_t *addin, uint32_t addinLen); 341 342 /** 343 * @ingroup crypt_eal_rand 344 * @brief Regenerate the seed, which is equivalent to CRYPT_EAL_RandSeedWithAdin(NULL, 0). 345 * 346 * @attention This interface supports multi-thread access. 347 * @param ctx [IN] DRBG handle. 348 * @retval #CRYPT_SUCCESS, if successful. 349 * For other error codes, see crypt_errno.h. 350 */ 351 int32_t CRYPT_EAL_DrbgSeed(CRYPT_EAL_RndCtx *ctx); 352 353 /** 354 * @ingroup crypt_eal_rand 355 * @brief Check whether the id is valid Rand algorithm ID. 356 * 357 * @param id [IN] Rand algorithm ID. 358 * 359 * @retval true, if valid. 360 * false, if invalid. 361 */ 362 bool CRYPT_EAL_RandIsValidAlgId(CRYPT_RAND_AlgId id); 363 364 /** 365 * @ingroup crypt_eal_rand 366 * @brief Instantiate the DRBG. 367 * 368 * This function instantiates the Deterministic Random Bit Generator (DRBG) with personalization string. 369 * It supports multi-thread access. 370 * 371 * @param ctx [IN] DRBG handle 372 * @param pers [IN] Personal data, which can be NULL. 373 * @param persLen [IN] Personal data length. the range is [0,0x7FFFFFF0]. 374 * @retval #CRYPT_SUCCESS, if successful. 375 * For other error codes, see crypt_errno.h. 376 */ 377 int32_t CRYPT_EAL_DrbgInstantiate(CRYPT_EAL_RndCtx *ctx, const uint8_t *pers, uint32_t persLen); 378 379 /** 380 * @ingroup crypt_eal_rand 381 * @brief get or set rand param 382 * 383 * @param ctx [IN] rand context 384 * @param cmd [IN] Option information 385 * @param val [IN/OUT] Data to be set/obtained 386 * @param valLen [IN] Length of the data marked as "val" 387 * 388 * @retval #CRYPT_SUCCESS. 389 * For other error codes, see crypt_errno.h. 390 */ 391 int32_t CRYPT_EAL_DrbgCtrl(CRYPT_EAL_RndCtx *ctx, int32_t cmd, void *val, uint32_t valLen); 392 393 #ifdef __cplusplus 394 } 395 #endif 396 397 #endif // CRYPT_EAL_RAND_H 398