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: Feb 28, 2020 Time: 03:04:48PM 38 */ 39 40 #ifndef _CRYPT_HASH_FP_H_ 41 #define _CRYPT_HASH_FP_H_ 42 43 //*** CryptHashInit() 44 // This function is called by _TPM_Init do perform the initialization operations for 45 // the library. 46 BOOL 47 CryptHashInit( 48 void 49 ); 50 51 //*** CryptHashStartup() 52 // This function is called by TPM2_Startup(). It checks that the size of the 53 // HashDefArray is consistent with the HASH_COUNT. 54 BOOL 55 CryptHashStartup( 56 void 57 ); 58 59 //*** CryptGetHashDef() 60 // This function accesses the hash descriptor associated with a hash a 61 // algorithm. The function returns a pointer to a 'null' descriptor if hashAlg is 62 // TPM_ALG_NULL or not a defined algorithm. 63 PHASH_DEF 64 CryptGetHashDef( 65 TPM_ALG_ID hashAlg 66 ); 67 68 //*** CryptHashIsValidAlg() 69 // This function tests to see if an algorithm ID is a valid hash algorithm. If 70 // flag is true, then TPM_ALG_NULL is a valid hash. 71 // Return Type: BOOL 72 // TRUE(1) hashAlg is a valid, implemented hash on this TPM 73 // FALSE(0) hashAlg is not valid for this TPM 74 BOOL 75 CryptHashIsValidAlg( 76 TPM_ALG_ID hashAlg, // IN: the algorithm to check 77 BOOL flag // IN: TRUE if TPM_ALG_NULL is to be treated 78 // as a valid hash 79 ); 80 81 //*** CryptHashGetAlgByIndex() 82 // This function is used to iterate through the hashes. TPM_ALG_NULL 83 // is returned for all indexes that are not valid hashes. 84 // If the TPM implements 3 hashes, then an 'index' value of 0 will 85 // return the first implemented hash and an 'index' of 2 will return the 86 // last. All other index values will return TPM_ALG_NULL. 87 // 88 // Return Type: TPM_ALG_ID 89 // TPM_ALG_xxx a hash algorithm 90 // TPM_ALG_NULL this can be used as a stop value 91 LIB_EXPORT TPM_ALG_ID 92 CryptHashGetAlgByIndex( 93 UINT32 index // IN: the index 94 ); 95 96 //*** CryptHashGetDigestSize() 97 // Returns the size of the digest produced by the hash. If 'hashAlg' is not a hash 98 // algorithm, the TPM will FAIL. 99 // Return Type: UINT16 100 // 0 TPM_ALG_NULL 101 // > 0 the digest size 102 // 103 LIB_EXPORT UINT16 104 CryptHashGetDigestSize( 105 TPM_ALG_ID hashAlg // IN: hash algorithm to look up 106 ); 107 108 //*** CryptHashGetBlockSize() 109 // Returns the size of the block used by the hash. If 'hashAlg' is not a hash 110 // algorithm, the TPM will FAIL. 111 // Return Type: UINT16 112 // 0 TPM_ALG_NULL 113 // > 0 the digest size 114 // 115 LIB_EXPORT UINT16 116 CryptHashGetBlockSize( 117 TPM_ALG_ID hashAlg // IN: hash algorithm to look up 118 ); 119 120 //*** CryptHashGetOid() 121 // This function returns a pointer to DER=encoded OID for a hash algorithm. All OIDs 122 // are full OID values including the Tag (0x06) and length byte. 123 LIB_EXPORT const BYTE * 124 CryptHashGetOid( 125 TPM_ALG_ID hashAlg 126 ); 127 128 //*** CryptHashGetContextAlg() 129 // This function returns the hash algorithm associated with a hash context. 130 TPM_ALG_ID 131 CryptHashGetContextAlg( 132 PHASH_STATE state // IN: the context to check 133 ); 134 135 //*** CryptHashCopyState 136 // This function is used to clone a HASH_STATE. 137 LIB_EXPORT void 138 CryptHashCopyState( 139 HASH_STATE *out, // OUT: destination of the state 140 const HASH_STATE *in // IN: source of the state 141 ); 142 143 //*** CryptHashExportState() 144 // This function is used to export a hash or HMAC hash state. This function 145 // would be called when preparing to context save a sequence object. 146 void 147 CryptHashExportState( 148 PCHASH_STATE internalFmt, // IN: the hash state formatted for use by 149 // library 150 PEXPORT_HASH_STATE externalFmt // OUT: the exported hash state 151 ); 152 153 //*** CryptHashImportState() 154 // This function is used to import the hash state. This function 155 // would be called to import a hash state when the context of a sequence object 156 // was being loaded. 157 void 158 CryptHashImportState( 159 PHASH_STATE internalFmt, // OUT: the hash state formatted for use by 160 // the library 161 PCEXPORT_HASH_STATE externalFmt // IN: the exported hash state 162 ); 163 164 //*** CryptHashStart() 165 // Functions starts a hash stack 166 // Start a hash stack and returns the digest size. As a side effect, the 167 // value of 'stateSize' in hashState is updated to indicate the number of bytes 168 // of state that were saved. This function calls GetHashServer() and that function 169 // will put the TPM into failure mode if the hash algorithm is not supported. 170 // 171 // This function does not use the sequence parameter. If it is necessary to import 172 // or export context, this will start the sequence in a local state 173 // and export the state to the input buffer. Will need to add a flag to the state 174 // structure to indicate that it needs to be imported before it can be used. 175 // (BLEH). 176 // Return Type: UINT16 177 // 0 hash is TPM_ALG_NULL 178 // >0 digest size 179 LIB_EXPORT UINT16 180 CryptHashStart( 181 PHASH_STATE hashState, // OUT: the running hash state 182 TPM_ALG_ID hashAlg // IN: hash algorithm 183 ); 184 185 //*** CryptDigestUpdate() 186 // Add data to a hash or HMAC, SMAC stack. 187 // 188 void 189 CryptDigestUpdate( 190 PHASH_STATE hashState, // IN: the hash context information 191 UINT32 dataSize, // IN: the size of data to be added 192 const BYTE *data // IN: data to be hashed 193 ); 194 195 //*** CryptHashEnd() 196 // Complete a hash or HMAC computation. This function will place the smaller of 197 // 'digestSize' or the size of the digest in 'dOut'. The number of bytes in the 198 // placed in the buffer is returned. If there is a failure, the returned value 199 // is <= 0. 200 // Return Type: UINT16 201 // 0 no data returned 202 // > 0 the number of bytes in the digest or dOutSize, whichever is smaller 203 LIB_EXPORT UINT16 204 CryptHashEnd( 205 PHASH_STATE hashState, // IN: the state of hash stack 206 UINT32 dOutSize, // IN: size of digest buffer 207 BYTE *dOut // OUT: hash digest 208 ); 209 210 //*** CryptHashBlock() 211 // Start a hash, hash a single block, update 'digest' and return the size of 212 // the results. 213 // 214 // The 'digestSize' parameter can be smaller than the digest. If so, only the more 215 // significant bytes are returned. 216 // Return Type: UINT16 217 // >= 0 number of bytes placed in 'dOut' 218 LIB_EXPORT UINT16 219 CryptHashBlock( 220 TPM_ALG_ID hashAlg, // IN: The hash algorithm 221 UINT32 dataSize, // IN: size of buffer to hash 222 const BYTE *data, // IN: the buffer to hash 223 UINT32 dOutSize, // IN: size of the digest buffer 224 BYTE *dOut // OUT: digest buffer 225 ); 226 227 //*** CryptDigestUpdate2B() 228 // This function updates a digest (hash or HMAC) with a TPM2B. 229 // 230 // This function can be used for both HMAC and hash functions so the 231 // 'digestState' is void so that either state type can be passed. 232 LIB_EXPORT void 233 CryptDigestUpdate2B( 234 PHASH_STATE state, // IN: the digest state 235 const TPM2B *bIn // IN: 2B containing the data 236 ); 237 238 //*** CryptHashEnd2B() 239 // This function is the same as CryptCompleteHash() but the digest is 240 // placed in a TPM2B. This is the most common use and this is provided 241 // for specification clarity. 'digest.size' should be set to indicate the number of 242 // bytes to place in the buffer 243 // Return Type: UINT16 244 // >=0 the number of bytes placed in 'digest.buffer' 245 LIB_EXPORT UINT16 246 CryptHashEnd2B( 247 PHASH_STATE state, // IN: the hash state 248 P2B digest // IN: the size of the buffer Out: requested 249 // number of bytes 250 ); 251 252 //*** CryptDigestUpdateInt() 253 // This function is used to include an integer value to a hash stack. The function 254 // marshals the integer into its canonical form before calling CryptDigestUpdate(). 255 LIB_EXPORT void 256 CryptDigestUpdateInt( 257 void *state, // IN: the state of hash stack 258 UINT32 intSize, // IN: the size of 'intValue' in bytes 259 UINT64 intValue // IN: integer value to be hashed 260 ); 261 262 //*** CryptHmacStart() 263 // This function is used to start an HMAC using a temp 264 // hash context. The function does the initialization 265 // of the hash with the HMAC key XOR iPad and updates the 266 // HMAC key XOR oPad. 267 // 268 // The function returns the number of bytes in a digest produced by 'hashAlg'. 269 // Return Type: UINT16 270 // >= 0 number of bytes in digest produced by 'hashAlg' (may be zero) 271 // 272 LIB_EXPORT UINT16 273 CryptHmacStart( 274 PHMAC_STATE state, // IN/OUT: the state buffer 275 TPM_ALG_ID hashAlg, // IN: the algorithm to use 276 UINT16 keySize, // IN: the size of the HMAC key 277 const BYTE *key // IN: the HMAC key 278 ); 279 280 //*** CryptHmacEnd() 281 // This function is called to complete an HMAC. It will finish the current 282 // digest, and start a new digest. It will then add the oPadKey and the 283 // completed digest and return the results in dOut. It will not return more 284 // than dOutSize bytes. 285 // Return Type: UINT16 286 // >= 0 number of bytes in 'dOut' (may be zero) 287 LIB_EXPORT UINT16 288 CryptHmacEnd( 289 PHMAC_STATE state, // IN: the hash state buffer 290 UINT32 dOutSize, // IN: size of digest buffer 291 BYTE *dOut // OUT: hash digest 292 ); 293 294 //*** CryptHmacStart2B() 295 // This function starts an HMAC and returns the size of the digest 296 // that will be produced. 297 // 298 // This function is provided to support the most common use of starting an HMAC 299 // with a TPM2B key. 300 // 301 // The caller must provide a block of memory in which the hash sequence state 302 // is kept. The caller should not alter the contents of this buffer until the 303 // hash sequence is completed or abandoned. 304 // 305 // Return Type: UINT16 306 // > 0 the digest size of the algorithm 307 // = 0 the hashAlg was TPM_ALG_NULL 308 LIB_EXPORT UINT16 309 CryptHmacStart2B( 310 PHMAC_STATE hmacState, // OUT: the state of HMAC stack. It will be used 311 // in HMAC update and completion 312 TPMI_ALG_HASH hashAlg, // IN: hash algorithm 313 P2B key // IN: HMAC key 314 ); 315 316 //*** CryptHmacEnd2B() 317 // This function is the same as CryptHmacEnd() but the HMAC result 318 // is returned in a TPM2B which is the most common use. 319 // Return Type: UINT16 320 // >=0 the number of bytes placed in 'digest' 321 LIB_EXPORT UINT16 322 CryptHmacEnd2B( 323 PHMAC_STATE hmacState, // IN: the state of HMAC stack 324 P2B digest // OUT: HMAC 325 ); 326 327 //** Mask and Key Generation Functions 328 //*** CryptMGF_KDF() 329 // This function performs MGF1/KDF1 or KDF2 using the selected hash. KDF1 and KDF2 are 330 // T('n') = T('n'-1) || H('seed' || 'counter') with the difference being that, with 331 // KDF1, 'counter' starts at 0 but with KDF2, 'counter' starts at 1. The caller 332 // determines which version by setting the initial value of counter to either 0 or 1. 333 // Note: Any value that is not 0 is considered to be 1. 334 // 335 // This function returns the length of the mask produced which 336 // could be zero if the digest algorithm is not supported 337 // Return Type: UINT16 338 // 0 hash algorithm was TPM_ALG_NULL 339 // > 0 should be the same as 'mSize' 340 LIB_EXPORT UINT16 341 CryptMGF_KDF( 342 UINT32 mSize, // IN: length of the mask to be produced 343 BYTE *mask, // OUT: buffer to receive the mask 344 TPM_ALG_ID hashAlg, // IN: hash to use 345 UINT32 seedSize, // IN: size of the seed 346 BYTE *seed, // IN: seed size 347 UINT32 counter // IN: counter initial value 348 ); 349 350 //*** CryptKDFa() 351 // This function performs the key generation according to Part 1 of the 352 // TPM specification. 353 // 354 // This function returns the number of bytes generated which may be zero. 355 // 356 // The 'key' and 'keyStream' pointers are not allowed to be NULL. The other 357 // pointer values may be NULL. The value of 'sizeInBits' must be no larger 358 // than (2^18)-1 = 256K bits (32385 bytes). 359 // 360 // The 'once' parameter is set to allow incremental generation of a large 361 // value. If this flag is TRUE, 'sizeInBits' will be used in the HMAC computation 362 // but only one iteration of the KDF is performed. This would be used for 363 // XOR obfuscation so that the mask value can be generated in digest-sized 364 // chunks rather than having to be generated all at once in an arbitrarily 365 // large buffer and then XORed into the result. If 'once' is TRUE, then 366 // 'sizeInBits' must be a multiple of 8. 367 // 368 // Any error in the processing of this command is considered fatal. 369 // Return Type: UINT16 370 // 0 hash algorithm is not supported or is TPM_ALG_NULL 371 // > 0 the number of bytes in the 'keyStream' buffer 372 LIB_EXPORT UINT16 373 CryptKDFa( 374 TPM_ALG_ID hashAlg, // IN: hash algorithm used in HMAC 375 const TPM2B *key, // IN: HMAC key 376 const TPM2B *label, // IN: a label for the KDF 377 const TPM2B *contextU, // IN: context U 378 const TPM2B *contextV, // IN: context V 379 UINT32 sizeInBits, // IN: size of generated key in bits 380 BYTE *keyStream, // OUT: key buffer 381 UINT32 *counterInOut, // IN/OUT: caller may provide the iteration 382 // counter for incremental operations to 383 // avoid large intermediate buffers. 384 UINT16 blocks // IN: If non-zero, this is the maximum number 385 // of blocks to be returned, regardless 386 // of sizeInBits 387 ); 388 389 //*** CryptKDFe() 390 // This function implements KDFe() as defined in TPM specification part 1. 391 // 392 // This function returns the number of bytes generated which may be zero. 393 // 394 // The 'Z' and 'keyStream' pointers are not allowed to be NULL. The other 395 // pointer values may be NULL. The value of 'sizeInBits' must be no larger 396 // than (2^18)-1 = 256K bits (32385 bytes). 397 // Any error in the processing of this command is considered fatal. 398 // Return Type: UINT16 399 // 0 hash algorithm is not supported or is TPM_ALG_NULL 400 // > 0 the number of bytes in the 'keyStream' buffer 401 // 402 LIB_EXPORT UINT16 403 CryptKDFe( 404 TPM_ALG_ID hashAlg, // IN: hash algorithm used in HMAC 405 TPM2B *Z, // IN: Z 406 const TPM2B *label, // IN: a label value for the KDF 407 TPM2B *partyUInfo, // IN: PartyUInfo 408 TPM2B *partyVInfo, // IN: PartyVInfo 409 UINT32 sizeInBits, // IN: size of generated key in bits 410 BYTE *keyStream // OUT: key buffer 411 ); 412 413 #endif // _CRYPT_HASH_FP_H_ 414