1 /**************************************************************************/ 2 /* */ 3 /* Copyright (c) Microsoft Corporation. All rights reserved. */ 4 /* */ 5 /* This software is licensed under the Microsoft Software License */ 6 /* Terms for Microsoft Azure RTOS. Full text of the license can be */ 7 /* found in the LICENSE file at https://aka.ms/AzureRTOS_EULA */ 8 /* and in the root directory of this software. */ 9 /* */ 10 /**************************************************************************/ 11 12 13 /**************************************************************************/ 14 /**************************************************************************/ 15 /** */ 16 /** NetX Crypto Component */ 17 /** */ 18 /** Deterministic Random Bit Generator (DRBG) */ 19 /** */ 20 /**************************************************************************/ 21 /**************************************************************************/ 22 23 24 /**************************************************************************/ 25 /* */ 26 /* APPLICATION INTERFACE DEFINITION RELEASE */ 27 /* */ 28 /* nx_crypto_drbg.h PORTABLE C */ 29 /* 6.1 */ 30 /* AUTHOR */ 31 /* */ 32 /* Timothy Stapko, Microsoft Corporation */ 33 /* */ 34 /* DESCRIPTION */ 35 /* */ 36 /* This file defines the basic Application Interface (API) to the */ 37 /* NetX Crypto DRBG module. */ 38 /* */ 39 /* RELEASE HISTORY */ 40 /* */ 41 /* DATE NAME DESCRIPTION */ 42 /* */ 43 /* 05-19-2020 Timothy Stapko Initial Version 6.0 */ 44 /* 09-30-2020 Timothy Stapko Modified comment(s), */ 45 /* resulting in version 6.1 */ 46 /* */ 47 /**************************************************************************/ 48 49 #ifndef NX_CRYPTO_DRBG_H 50 #define NX_CRYPTO_DRBG_H 51 52 /* Determine if a C++ compiler is being used. If so, ensure that standard 53 C is used to process the API information. */ 54 #ifdef __cplusplus 55 56 /* Yes, C++ compiler is present. Use standard C. */ 57 extern "C" { 58 59 #endif 60 61 #include "nx_crypto.h" 62 63 /* Constants. */ 64 #define NX_CRYPTO_DRBG_BLOCK_LENGTH_AES (16) 65 #define NX_CRYPTO_DRBG_MAX_BLOCK_LENGTH (16) 66 #define NX_CRYPTO_DRBG_MAX_KEY_LENGTH (32) 67 #define NX_CRYPTO_DRBG_MAX_SEEDLEN (48) 68 69 #ifndef NX_CRYPTO_DRBG_BLOCK_LENGTH 70 #define NX_CRYPTO_DRBG_BLOCK_LENGTH (NX_CRYPTO_DRBG_BLOCK_LENGTH_AES) 71 #endif 72 73 #define NX_CRYPTO_DRBG_DF_INPUT_OFFSET (NX_CRYPTO_DRBG_BLOCK_LENGTH + 8) 74 75 #ifndef NX_CRYPTO_DRBG_SEED_BUFFER_LEN 76 #define NX_CRYPTO_DRBG_SEED_BUFFER_LEN (256) 77 #endif 78 79 #ifndef NX_CRYPTO_DRBG_MAX_ENTROPY_LEN 80 #define NX_CRYPTO_DRBG_MAX_ENTROPY_LEN (125) 81 #endif 82 83 #ifndef NX_CRYPTO_DRBG_MAX_SEED_LIFE 84 #define NX_CRYPTO_DRBG_MAX_SEED_LIFE (100000) 85 #endif 86 87 #ifndef NX_CRYPTO_DRBG_MUTEX_GET 88 #define NX_CRYPTO_DRBG_MUTEX_GET 89 #endif 90 91 #ifndef NX_CRYPTO_DRBG_MUTEX_PUT 92 #define NX_CRYPTO_DRBG_MUTEX_PUT 93 #endif 94 95 #ifndef NX_CRYPTO_DRBG_USE_DF 96 #define NX_CRYPTO_DRBG_USE_DF (1) 97 #endif 98 99 #ifndef NX_CRYPTO_DRBG_PREDICTION_RESISTANCE 100 #define NX_CRYPTO_DRBG_PREDICTION_RESISTANCE (1) 101 #endif 102 103 #ifndef NX_CRYPTO_DRBG_CTR_CRYPTO_METHOD 104 extern NX_CRYPTO_METHOD crypto_method_aes_cbc_128; 105 #define NX_CRYPTO_DRBG_CTR_CRYPTO_METHOD &crypto_method_aes_cbc_128 106 #endif 107 108 #ifndef NX_CRYPTO_DRBG_CTR_CRYPTO_METADATA 109 #define NX_CRYPTO_DRBG_CTR_CRYPTO_METADATA _nx_crypto_ctr_metadata 110 #define NX_CRYPTO_DRBG_CTR_METADATA_SIZE (sizeof(NX_CRYPTO_AES)) 111 #endif 112 113 #ifndef NX_CRYPTO_DRBG_ENTROPY_INPUT_FUNC 114 #define NX_CRYPTO_DRBG_ENTROPY_INPUT_FUNC _nx_crypto_drbg_rnd_entropy_input 115 #endif 116 117 118 119 /* DRBG control structure. */ 120 typedef struct NX_CRYPTO_DRBG_STRUCT 121 { 122 /* Crypto method and metadata used in the DRBG. */ 123 NX_CRYPTO_METHOD *nx_crypto_drbg_crypto_method; 124 VOID *nx_crypto_drbg_crypto_metadata; 125 126 UINT (*nx_crypto_drbg_get_entropy)(UCHAR *entropy, UINT *entropy_len, UINT entropy_max_len); 127 128 UINT nx_crypto_drbg_use_df; 129 UINT nx_crypto_drbg_prediction_resistance; 130 UINT nx_crypto_drbg_security_strength; 131 132 UINT nx_crypto_drbg_instantiated; 133 134 /* DRBG working state. */ 135 UCHAR nx_crypto_drbg_key[NX_CRYPTO_DRBG_MAX_KEY_LENGTH]; 136 UCHAR nx_crypto_drbg_v[NX_CRYPTO_DRBG_MAX_BLOCK_LENGTH]; 137 138 /* A counter that indicates the number of requests for pseudorandom bits since instantiation or reseeding. */ 139 UINT nx_crypto_drgb_reseed_counter; 140 141 UINT nx_crypto_drbg_seedlen; 142 143 UCHAR nx_crypto_drbg_buffer[NX_CRYPTO_DRBG_SEED_BUFFER_LEN]; 144 } NX_CRYPTO_DRBG; 145 146 /* DRBG control structure. */ 147 typedef struct NX_CRYPTO_DRBG_OPTIONS_STRUCT 148 { 149 /* Crypto method and metadata used in the DRBG. */ 150 NX_CRYPTO_METHOD *crypto_method; 151 VOID *crypto_metadata; 152 153 UINT (*entropy_input)(UCHAR *entropy, UINT *entropy_len, UINT entropy_max_len); 154 155 UINT use_df; 156 UINT prediction_resistance; 157 UINT security_strength; 158 } NX_CRYPTO_DRBG_OPTIONS; 159 160 161 /* Function prototypes */ 162 163 164 UINT _nx_crypto_drbg_instantiate(NX_CRYPTO_DRBG *drbg_ptr, 165 UCHAR *nonce, 166 UINT nonce_len, 167 UCHAR *personalization_string, 168 UINT personalization_string_len); 169 170 UINT _nx_crypto_drbg_reseed(NX_CRYPTO_DRBG *drbg_ptr, 171 UCHAR *additional_input, 172 UINT additional_input_len); 173 174 UINT _nx_crypto_drbg_generate(NX_CRYPTO_DRBG *drbg_ptr, 175 UCHAR *output, UINT output_length_in_byte, 176 UCHAR *additional_input, 177 UINT additional_input_len); 178 179 UINT _nx_crypto_method_drbg_init(struct NX_CRYPTO_METHOD_STRUCT *method, 180 UCHAR *key, NX_CRYPTO_KEY_SIZE key_size_in_bits, 181 VOID **handle, 182 VOID *crypto_metadata, 183 ULONG crypto_metadata_size); 184 185 UINT _nx_crypto_method_drbg_cleanup(VOID *crypto_metadata); 186 187 UINT _nx_crypto_method_drbg_operation(UINT op, 188 VOID *handle, 189 struct NX_CRYPTO_METHOD_STRUCT *method, 190 UCHAR *key, NX_CRYPTO_KEY_SIZE key_size_in_bits, 191 UCHAR *input, ULONG input_length_in_byte, 192 UCHAR *iv_ptr, 193 UCHAR *output, ULONG output_length_in_byte, 194 VOID *crypto_metadata, ULONG crypto_metadata_size, 195 VOID *packet_ptr, 196 VOID (*nx_crypto_hw_process_callback)(VOID *, UINT)); 197 198 UINT _nx_crypto_drbg(UINT bits, UCHAR *result); 199 200 #ifdef __cplusplus 201 } 202 #endif 203 204 #endif /* NX_CRYPTO_DRBG_H */ 205 206
