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