1 /* Microsoft Reference Implementation for TPM 2.0 2 * 3 * The copyright in this software is being made available under the BSD License, 4 * included below. This software may be subject to other third party and 5 * contributor rights, including patent rights, and no such rights are granted 6 * under this license. 7 * 8 * Copyright (c) Microsoft Corporation 9 * 10 * All rights reserved. 11 * 12 * BSD License 13 * 14 * Redistribution and use in source and binary forms, with or without modification, 15 * are permitted provided that the following conditions are met: 16 * 17 * Redistributions of source code must retain the above copyright notice, this list 18 * of conditions and the following disclaimer. 19 * 20 * Redistributions in binary form must reproduce the above copyright notice, this 21 * list of conditions and the following disclaimer in the documentation and/or 22 * other materials provided with the distribution. 23 * 24 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ""AS IS"" 25 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 26 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 27 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR 28 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 29 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 30 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 31 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 32 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 33 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 34 */ 35 /*(Auto-generated) 36 * Created by TpmPrototypes; Version 3.0 July 18, 2017 37 * Date: Mar 4, 2020 Time: 02:36:44PM 38 */ 39 40 #ifndef _CRYPT_RAND_FP_H_ 41 #define _CRYPT_RAND_FP_H_ 42 43 //*** DRBG_GetEntropy() 44 // Even though this implementation never fails, it may get blocked 45 // indefinitely long in the call to get entropy from the platform 46 // (DRBG_GetEntropy32()). 47 // This function is only used during instantiation of the DRBG for 48 // manufacturing and on each start-up after an non-orderly shutdown. 49 // 50 // Return Type: BOOL 51 // TRUE(1) requested entropy returned 52 // FALSE(0) entropy Failure 53 BOOL 54 DRBG_GetEntropy( 55 UINT32 requiredEntropy, // IN: requested number of bytes of full 56 // entropy 57 BYTE *entropy // OUT: buffer to return collected entropy 58 ); 59 60 //*** IncrementIv() 61 // This function increments the IV value by 1. It is used by EncryptDRBG(). 62 void 63 IncrementIv( 64 DRBG_IV *iv 65 ); 66 67 //*** DRBG_Reseed() 68 // This function is used when reseeding of the DRBG is required. If 69 // entropy is provided, it is used in lieu of using hardware entropy. 70 // Note: the provided entropy must be the required size. 71 // 72 // Return Type: BOOL 73 // TRUE(1) reseed succeeded 74 // FALSE(0) reseed failed, probably due to the entropy generation 75 BOOL 76 DRBG_Reseed( 77 DRBG_STATE *drbgState, // IN: the state to update 78 DRBG_SEED *providedEntropy, // IN: entropy 79 DRBG_SEED *additionalData // IN: 80 ); 81 82 //*** DRBG_SelfTest() 83 // This is run when the DRBG is instantiated and at startup. 84 // 85 // Return Type: BOOL 86 // TRUE(1) test OK 87 // FALSE(0) test failed 88 BOOL 89 DRBG_SelfTest( 90 void 91 ); 92 93 //*** CryptRandomStir() 94 // This function is used to cause a reseed. A DRBG_SEED amount of entropy is 95 // collected from the hardware and then additional data is added. 96 // 97 // Return Type: TPM_RC 98 // TPM_RC_NO_RESULT failure of the entropy generator 99 LIB_EXPORT TPM_RC 100 CryptRandomStir( 101 UINT16 additionalDataSize, 102 BYTE *additionalData 103 ); 104 105 //*** CryptRandomGenerate() 106 // Generate a 'randomSize' number or random bytes. 107 LIB_EXPORT UINT16 108 CryptRandomGenerate( 109 UINT16 randomSize, 110 BYTE *buffer 111 ); 112 113 //*** DRBG_InstantiateSeededKdf() 114 // This function is used to instantiate a KDF-based RNG. This is used for derivations. 115 // This function always returns TRUE. 116 LIB_EXPORT BOOL 117 DRBG_InstantiateSeededKdf( 118 KDF_STATE *state, // OUT: buffer to hold the state 119 TPM_ALG_ID hashAlg, // IN: hash algorithm 120 TPM_ALG_ID kdf, // IN: the KDF to use 121 TPM2B *seed, // IN: the seed to use 122 const TPM2B *label, // IN: a label for the generation process. 123 TPM2B *context, // IN: the context value 124 UINT32 limit // IN: Maximum number of bits from the KDF 125 ); 126 127 //*** DRBG_AdditionalData() 128 // Function to reseed the DRBG with additional entropy. This is normally called 129 // before computing the protection value of a primary key in the Endorsement 130 // hierarchy. 131 LIB_EXPORT void 132 DRBG_AdditionalData( 133 DRBG_STATE *drbgState, // IN:OUT state to update 134 TPM2B *additionalData // IN: value to incorporate 135 ); 136 137 //*** DRBG_InstantiateSeeded() 138 // This function is used to instantiate a random number generator from seed values. 139 // The nominal use of this generator is to create sequences of pseudo-random 140 // numbers from a seed value. 141 // 142 // Return Type: TPM_RC 143 // TPM_RC_FAILURE DRBG self-test failure 144 LIB_EXPORT TPM_RC 145 DRBG_InstantiateSeeded( 146 DRBG_STATE *drbgState, // IN/OUT: buffer to hold the state 147 const TPM2B *seed, // IN: the seed to use 148 const TPM2B *purpose, // IN: a label for the generation process. 149 const TPM2B *name, // IN: name of the object 150 const TPM2B *additional // IN: additional data 151 ); 152 153 //*** CryptRandStartup() 154 // This function is called when TPM_Startup is executed. This function always returns 155 // TRUE. 156 LIB_EXPORT BOOL 157 CryptRandStartup( 158 void 159 ); 160 161 //**** CryptRandInit() 162 // This function is called when _TPM_Init is being processed. 163 // 164 // Return Type: BOOL 165 // TRUE(1) success 166 // FALSE(0) failure 167 LIB_EXPORT BOOL 168 CryptRandInit( 169 void 170 ); 171 172 //*** DRBG_Generate() 173 // This function generates a random sequence according SP800-90A. 174 // If 'random' is not NULL, then 'randomSize' bytes of random values are generated. 175 // If 'random' is NULL or 'randomSize' is zero, then the function returns 176 // zero without generating any bits or updating the reseed counter. 177 // This function returns the number of bytes produced which could be less than the 178 // number requested if the request is too large ("too large" is implementation 179 // dependent.) 180 LIB_EXPORT UINT16 181 DRBG_Generate( 182 RAND_STATE *state, 183 BYTE *random, // OUT: buffer to receive the random values 184 UINT16 randomSize // IN: the number of bytes to generate 185 ); 186 187 //*** DRBG_Instantiate() 188 // This is CTR_DRBG_Instantiate_algorithm() from [SP 800-90A 10.2.1.3.1]. 189 // This is called when a the TPM DRBG is to be instantiated. This is 190 // called to instantiate a DRBG used by the TPM for normal 191 // operations. 192 // 193 // Return Type: BOOL 194 // TRUE(1) instantiation succeeded 195 // FALSE(0) instantiation failed 196 LIB_EXPORT BOOL 197 DRBG_Instantiate( 198 DRBG_STATE *drbgState, // OUT: the instantiated value 199 UINT16 pSize, // IN: Size of personalization string 200 BYTE *personalization // IN: The personalization string 201 ); 202 203 //*** DRBG_Uninstantiate() 204 // This is Uninstantiate_function() from [SP 800-90A 9.4]. 205 // 206 // Return Type: TPM_RC 207 // TPM_RC_VALUE not a valid state 208 LIB_EXPORT TPM_RC 209 DRBG_Uninstantiate( 210 DRBG_STATE *drbgState // IN/OUT: working state to erase 211 ); 212 213 #endif // _CRYPT_RAND_FP_H_ 214