1 /* 2 * Copyright (c) 2023, The TrustedFirmware-M Contributors. All rights reserved. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 * 6 */ 7 8 #ifndef __CC3XX_DRBG_H__ 9 #define __CC3XX_DRBG_H__ 10 11 /** 12 * @file Contains a generic interface towards a DRBG mechanism that 13 * can be chosen at runtime during the instantiation phase of 14 * the DRBG, i.e. when calling cc3xx_drbg_init() 15 */ 16 17 #include <stdint.h> 18 #include <stddef.h> 19 #include "cc3xx_error.h" 20 #include "cc3xx_config.h" 21 22 #include "cc3xx_drbg_ctr.h" 23 #include "cc3xx_drbg_hash.h" 24 #include "cc3xx_drbg_hmac.h" 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 /** 31 * @brief This enum defines which DRBG mechanism to use. Allowed 32 * values are CC3XX_DRBG_CTR, CC3XX_DRBG_HASH, CC3XX_DRBG_HMAC 33 */ 34 typedef enum { 35 CC3XX_DRBG_CTR = 0, 36 CC3XX_DRBG_HMAC, 37 CC3XX_DRBG_HASH, 38 CC3XX_DRBG_MAX = CC3XX_DRBG_HASH + 1, 39 } cc3xx_drbg_id_t; 40 41 /** 42 * @brief Generic context for a DRBG generator 43 * 44 */ 45 struct cc3xx_drbg_state_t { 46 cc3xx_drbg_id_t id; 47 union { 48 struct cc3xx_drbg_ctr_state_t ctr; 49 struct cc3xx_drbg_hmac_state_t hmac; 50 struct cc3xx_drbg_hash_state_t hash; 51 }; 52 }; 53 54 /** 55 * @brief Instantiate the DRBG 56 * 57 * @param[in] id The ID of the DRBG to instantiate, of type \ref cc3xx_drbg_id_t 58 * @param[out] state A pointer to a state structure 59 * @param[in] entropy Buffer containing the entropy for the instantiation 60 * @param[in] entropy_len Size in bytes of the entropy buffer \param entropy 61 * @param[in] nonce Buffer containing the nonce 62 * @param[in] nonce_len Size in bytes of the nonce buffer \param nonce 63 * @param[in] personalization Buffer containing the personalization string 64 * @param[in] personalization_len Size in bytes of the personalization buffer \param personalization 65 * @return cc3xx_err_t 66 */ 67 cc3xx_err_t cc3xx_lowlevel_drbg_init( 68 cc3xx_drbg_id_t id, 69 struct cc3xx_drbg_state_t *state, 70 const uint8_t *entropy, size_t entropy_len, 71 const uint8_t *nonce, size_t nonce_len, 72 const uint8_t *personalization, size_t personalization_len); 73 74 /** 75 * @brief Generates random bits from the DRBG instance 76 * 77 * @param[in,out] state Pointer to an instantiated DRBG generator 78 * @param[in] len_bits Size in bits to be generated. Must be byte aligned for simplicity 79 * @param[out] returned_bits Pointer holding the returned random bit string 80 * @param[in] additional_input Pointer to the additional input to be used 81 * @param[in] additional_input_len Size in bytes of the additional input to be used 82 * @return cc3xx_err_t 83 */ 84 cc3xx_err_t cc3xx_lowlevel_drbg_generate( 85 struct cc3xx_drbg_state_t *state, 86 size_t len_bits, uint8_t *returned_bits, 87 const uint8_t *additional_input, size_t additional_input_len); 88 89 /** 90 * @brief Reseeds the DRBG 91 * 92 * @param[in,out] state A pointer to a state structure 93 * @param[in] entropy Entropy to be used for reseeding 94 * @param[in] entropy_len Size in bytes of the entropy pointed by \param entropy 95 * @param[in] additional_input Optional pointer containing additional input for reseeding 96 * @param[in] additional_input_len Size in bytes of the buffer pointed by \param additional_input 97 * @return cc3xx_err_t 98 */ 99 cc3xx_err_t cc3xx_lowlevel_drbg_reseed( 100 struct cc3xx_drbg_state_t *state, 101 const uint8_t *entropy, size_t entropy_len, 102 const uint8_t *additional_input, size_t additional_input_len); 103 104 /** 105 * @brief Un-initializes the state structure associated to the underlying DRBG 106 * 107 * @param[out] state Pointer to the structure 108 * @return cc3xx_err_t 109 */ 110 cc3xx_err_t cc3xx_lowlevel_drbg_uninit(struct cc3xx_drbg_state_t *state); 111 112 #ifdef __cplusplus 113 } 114 #endif 115 116 #endif /* __CC3XX_DRBG_H__ */ 117
