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: Aug 30, 2019 Time: 02:11:54PM 38 */ 39 40 #ifndef _CRYPT_UTIL_FP_H_ 41 #define _CRYPT_UTIL_FP_H_ 42 43 //*** CryptIsSchemeAnonymous() 44 // This function is used to test a scheme to see if it is an anonymous scheme 45 // The only anonymous scheme is ECDAA. ECDAA can be used to do things 46 // like U-Prove. 47 BOOL 48 CryptIsSchemeAnonymous( 49 TPM_ALG_ID scheme // IN: the scheme algorithm to test 50 ); 51 52 //*** ParmDecryptSym() 53 // This function performs parameter decryption using symmetric block cipher. 54 void 55 ParmDecryptSym( 56 TPM_ALG_ID symAlg, // IN: the symmetric algorithm 57 TPM_ALG_ID hash, // IN: hash algorithm for KDFa 58 UINT16 keySizeInBits, // IN: the key size in bits 59 TPM2B *key, // IN: KDF HMAC key 60 TPM2B *nonceCaller, // IN: nonce caller 61 TPM2B *nonceTpm, // IN: nonce TPM 62 UINT32 dataSize, // IN: size of parameter buffer 63 BYTE *data // OUT: buffer to be decrypted 64 ); 65 66 //*** ParmEncryptSym() 67 // This function performs parameter encryption using symmetric block cipher. 68 void 69 ParmEncryptSym( 70 TPM_ALG_ID symAlg, // IN: symmetric algorithm 71 TPM_ALG_ID hash, // IN: hash algorithm for KDFa 72 UINT16 keySizeInBits, // IN: symmetric key size in bits 73 TPM2B *key, // IN: KDF HMAC key 74 TPM2B *nonceCaller, // IN: nonce caller 75 TPM2B *nonceTpm, // IN: nonce TPM 76 UINT32 dataSize, // IN: size of parameter buffer 77 BYTE *data // OUT: buffer to be encrypted 78 ); 79 80 //*** CryptXORObfuscation() 81 // This function implements XOR obfuscation. It should not be called if the 82 // hash algorithm is not implemented. The only return value from this function 83 // is TPM_RC_SUCCESS. 84 void 85 CryptXORObfuscation( 86 TPM_ALG_ID hash, // IN: hash algorithm for KDF 87 TPM2B *key, // IN: KDF key 88 TPM2B *contextU, // IN: contextU 89 TPM2B *contextV, // IN: contextV 90 UINT32 dataSize, // IN: size of data buffer 91 BYTE *data // IN/OUT: data to be XORed in place 92 ); 93 94 //*** CryptInit() 95 // This function is called when the TPM receives a _TPM_Init indication. 96 // 97 // NOTE: The hash algorithms do not have to be tested, they just need to be 98 // available. They have to be tested before the TPM can accept HMAC authorization 99 // or return any result that relies on a hash algorithm. 100 // Return Type: BOOL 101 // TRUE(1) initializations succeeded 102 // FALSE(0) initialization failed and caller should place the TPM into 103 // Failure Mode 104 BOOL 105 CryptInit( 106 void 107 ); 108 109 //*** CryptStartup() 110 // This function is called by TPM2_Startup() to initialize the functions in 111 // this cryptographic library and in the provided CryptoLibrary. This function 112 // and CryptUtilInit() are both provided so that the implementation may move the 113 // initialization around to get the best interaction. 114 // Return Type: BOOL 115 // TRUE(1) startup succeeded 116 // FALSE(0) startup failed and caller should place the TPM into 117 // Failure Mode 118 BOOL 119 CryptStartup( 120 STARTUP_TYPE type // IN: the startup type 121 ); 122 123 //**************************************************************************** 124 //** Algorithm-Independent Functions 125 //**************************************************************************** 126 //*** Introduction 127 // These functions are used generically when a function of a general type 128 // (e.g., symmetric encryption) is required. The functions will modify the 129 // parameters as required to interface to the indicated algorithms. 130 // 131 //*** CryptIsAsymAlgorithm() 132 // This function indicates if an algorithm is an asymmetric algorithm. 133 // Return Type: BOOL 134 // TRUE(1) if it is an asymmetric algorithm 135 // FALSE(0) if it is not an asymmetric algorithm 136 BOOL 137 CryptIsAsymAlgorithm( 138 TPM_ALG_ID algID // IN: algorithm ID 139 ); 140 141 //*** CryptSecretEncrypt() 142 // This function creates a secret value and its associated secret structure using 143 // an asymmetric algorithm. 144 // 145 // This function is used by TPM2_Rewrap() TPM2_MakeCredential(), 146 // and TPM2_Duplicate(). 147 // Return Type: TPM_RC 148 // TPM_RC_ATTRIBUTES 'keyHandle' does not reference a valid decryption key 149 // TPM_RC_KEY invalid ECC key (public point is not on the curve) 150 // TPM_RC_SCHEME RSA key with an unsupported padding scheme 151 // TPM_RC_VALUE numeric value of the data to be decrypted is greater 152 // than the RSA key modulus 153 TPM_RC 154 CryptSecretEncrypt( 155 OBJECT *encryptKey, // IN: encryption key object 156 const TPM2B *label, // IN: a null-terminated string as L 157 TPM2B_DATA *data, // OUT: secret value 158 TPM2B_ENCRYPTED_SECRET *secret // OUT: secret structure 159 ); 160 161 //*** CryptSecretDecrypt() 162 // Decrypt a secret value by asymmetric (or symmetric) algorithm 163 // This function is used for ActivateCredential and Import for asymmetric 164 // decryption, and StartAuthSession for both asymmetric and symmetric 165 // decryption process 166 // 167 // Return Type: TPM_RC 168 // TPM_RC_ATTRIBUTES RSA key is not a decryption key 169 // TPM_RC_BINDING Invalid RSA key (public and private parts are not 170 // cryptographically bound. 171 // TPM_RC_ECC_POINT ECC point in the secret is not on the curve 172 // TPM_RC_INSUFFICIENT failed to retrieve ECC point from the secret 173 // TPM_RC_NO_RESULT multiplication resulted in ECC point at infinity 174 // TPM_RC_SIZE data to decrypt is not of the same size as RSA key 175 // TPM_RC_VALUE For RSA key, numeric value of the encrypted data is 176 // greater than the modulus, or the recovered data is 177 // larger than the output buffer. 178 // For keyedHash or symmetric key, the secret is 179 // larger than the size of the digest produced by 180 // the name algorithm. 181 // TPM_RC_FAILURE internal error 182 TPM_RC 183 CryptSecretDecrypt( 184 OBJECT *decryptKey, // IN: decrypt key 185 TPM2B_NONCE *nonceCaller, // IN: nonceCaller. It is needed for 186 // symmetric decryption. For 187 // asymmetric decryption, this 188 // parameter is NULL 189 const TPM2B *label, // IN: a value for L 190 TPM2B_ENCRYPTED_SECRET *secret, // IN: input secret 191 TPM2B_DATA *data // OUT: decrypted secret value 192 ); 193 194 //*** CryptParameterEncryption() 195 // This function does in-place encryption of a response parameter. 196 void 197 CryptParameterEncryption( 198 TPM_HANDLE handle, // IN: encrypt session handle 199 TPM2B *nonceCaller, // IN: nonce caller 200 UINT16 leadingSizeInByte, // IN: the size of the leading size field in 201 // bytes 202 TPM2B_AUTH *extraKey, // IN: additional key material other than 203 // sessionAuth 204 BYTE *buffer // IN/OUT: parameter buffer to be encrypted 205 ); 206 207 //*** CryptParameterDecryption() 208 // This function does in-place decryption of a command parameter. 209 // Return Type: TPM_RC 210 // TPM_RC_SIZE The number of bytes in the input buffer is less than 211 // the number of bytes to be decrypted. 212 TPM_RC 213 CryptParameterDecryption( 214 TPM_HANDLE handle, // IN: encrypted session handle 215 TPM2B *nonceCaller, // IN: nonce caller 216 UINT32 bufferSize, // IN: size of parameter buffer 217 UINT16 leadingSizeInByte, // IN: the size of the leading size field in 218 // byte 219 TPM2B_AUTH *extraKey, // IN: the authValue 220 BYTE *buffer // IN/OUT: parameter buffer to be decrypted 221 ); 222 223 //*** CryptComputeSymmetricUnique() 224 // This function computes the unique field in public area for symmetric objects. 225 void 226 CryptComputeSymmetricUnique( 227 TPMT_PUBLIC *publicArea, // IN: the object's public area 228 TPMT_SENSITIVE *sensitive, // IN: the associated sensitive area 229 TPM2B_DIGEST *unique // OUT: unique buffer 230 ); 231 232 //*** CryptCreateObject() 233 // This function creates an object. 234 // For an asymmetric key, it will create a key pair and, for a parent key, a seed 235 // value for child protections. 236 // 237 // For an symmetric object, (TPM_ALG_SYMCIPHER or TPM_ALG_KEYEDHASH), it will 238 // create a secret key if the caller did not provide one. It will create a random 239 // secret seed value that is hashed with the secret value to create the public 240 // unique value. 241 // 242 // 'publicArea', 'sensitive', and 'sensitiveCreate' are the only required parameters 243 // and are the only ones that are used by TPM2_Create(). The other parameters 244 // are optional and are used when the generated Object needs to be deterministic. 245 // This is the case for both Primary Objects and Derived Objects. 246 // 247 // When a seed value is provided, a RAND_STATE will be populated and used for 248 // all operations in the object generation that require a random number. In the 249 // simplest case, TPM2_CreatePrimary() will use 'seed', 'label' and 'context' with 250 // context being the hash of the template. If the Primary Object is in 251 // the Endorsement hierarchy, it will also populate 'proof' with ehProof. 252 // 253 // For derived keys, 'seed' will be the secret value from the parent, 'label' and 254 // 'context' will be set according to the parameters of TPM2_CreateLoaded() and 255 // 'hashAlg' will be set which causes the RAND_STATE to be a KDF generator. 256 // 257 // Return Type: TPM_RC 258 // TPM_RC_KEY a provided key is not an allowed value 259 // TPM_RC_KEY_SIZE key size in the public area does not match the size 260 // in the sensitive creation area for a symmetric key 261 // TPM_RC_NO_RESULT unable to get random values (only in derivation) 262 // TPM_RC_RANGE for an RSA key, the exponent is not supported 263 // TPM_RC_SIZE sensitive data size is larger than allowed for the 264 // scheme for a keyed hash object 265 // TPM_RC_VALUE exponent is not prime or could not find a prime using 266 // the provided parameters for an RSA key; 267 // unsupported name algorithm for an ECC key 268 TPM_RC 269 CryptCreateObject( 270 OBJECT *object, // IN: new object structure pointer 271 TPMS_SENSITIVE_CREATE *sensitiveCreate, // IN: sensitive creation 272 RAND_STATE *rand // IN: the random number generator 273 // to use 274 ); 275 276 //*** CryptGetSignHashAlg() 277 // Get the hash algorithm of signature from a TPMT_SIGNATURE structure. 278 // It assumes the signature is not NULL 279 // This is a function for easy access 280 TPMI_ALG_HASH 281 CryptGetSignHashAlg( 282 TPMT_SIGNATURE *auth // IN: signature 283 ); 284 285 //*** CryptIsSplitSign() 286 // This function us used to determine if the signing operation is a split 287 // signing operation that required a TPM2_Commit(). 288 // 289 BOOL 290 CryptIsSplitSign( 291 TPM_ALG_ID scheme // IN: the algorithm selector 292 ); 293 294 //*** CryptIsAsymSignScheme() 295 // This function indicates if a scheme algorithm is a sign algorithm. 296 BOOL 297 CryptIsAsymSignScheme( 298 TPMI_ALG_PUBLIC publicType, // IN: Type of the object 299 TPMI_ALG_ASYM_SCHEME scheme // IN: the scheme 300 ); 301 302 //*** CryptIsAsymDecryptScheme() 303 // This function indicate if a scheme algorithm is a decrypt algorithm. 304 BOOL 305 CryptIsAsymDecryptScheme( 306 TPMI_ALG_PUBLIC publicType, // IN: Type of the object 307 TPMI_ALG_ASYM_SCHEME scheme // IN: the scheme 308 ); 309 310 //*** CryptSelectSignScheme() 311 // This function is used by the attestation and signing commands. It implements 312 // the rules for selecting the signature scheme to use in signing. This function 313 // requires that the signing key either be TPM_RH_NULL or be loaded. 314 // 315 // If a default scheme is defined in object, the default scheme should be chosen, 316 // otherwise, the input scheme should be chosen. 317 // In the case that both object and input scheme has a non-NULL scheme 318 // algorithm, if the schemes are compatible, the input scheme will be chosen. 319 // 320 // This function should not be called if 'signObject->publicArea.type' == 321 // ALG_SYMCIPHER. 322 // 323 // Return Type: BOOL 324 // TRUE(1) scheme selected 325 // FALSE(0) both 'scheme' and key's default scheme are empty; or 326 // 'scheme' is empty while key's default scheme requires 327 // explicit input scheme (split signing); or 328 // non-empty default key scheme differs from 'scheme' 329 BOOL 330 CryptSelectSignScheme( 331 OBJECT *signObject, // IN: signing key 332 TPMT_SIG_SCHEME *scheme // IN/OUT: signing scheme 333 ); 334 335 //*** CryptSign() 336 // Sign a digest with asymmetric key or HMAC. 337 // This function is called by attestation commands and the generic TPM2_Sign 338 // command. 339 // This function checks the key scheme and digest size. It does not 340 // check if the sign operation is allowed for restricted key. It should be 341 // checked before the function is called. 342 // The function will assert if the key is not a signing key. 343 // 344 // Return Type: TPM_RC 345 // TPM_RC_SCHEME 'signScheme' is not compatible with the signing key type 346 // TPM_RC_VALUE 'digest' value is greater than the modulus of 347 // 'signHandle' or size of 'hashData' does not match hash 348 // algorithm in'signScheme' (for an RSA key); 349 // invalid commit status or failed to generate "r" value 350 // (for an ECC key) 351 TPM_RC 352 CryptSign( 353 OBJECT *signKey, // IN: signing key 354 TPMT_SIG_SCHEME *signScheme, // IN: sign scheme. 355 TPM2B_DIGEST *digest, // IN: The digest being signed 356 TPMT_SIGNATURE *signature // OUT: signature 357 ); 358 359 //*** CryptValidateSignature() 360 // This function is used to verify a signature. It is called by 361 // TPM2_VerifySignature() and TPM2_PolicySigned. 362 // 363 // Since this operation only requires use of a public key, no consistency 364 // checks are necessary for the key to signature type because a caller can load 365 // any public key that they like with any scheme that they like. This routine 366 // simply makes sure that the signature is correct, whatever the type. 367 // 368 // Return Type: TPM_RC 369 // TPM_RC_SIGNATURE the signature is not genuine 370 // TPM_RC_SCHEME the scheme is not supported 371 // TPM_RC_HANDLE an HMAC key was selected but the 372 // private part of the key is not loaded 373 TPM_RC 374 CryptValidateSignature( 375 TPMI_DH_OBJECT keyHandle, // IN: The handle of sign key 376 TPM2B_DIGEST *digest, // IN: The digest being validated 377 TPMT_SIGNATURE *signature // IN: signature 378 ); 379 380 //*** CryptGetTestResult 381 // This function returns the results of a self-test function. 382 // Note: the behavior in this function is NOT the correct behavior for a real 383 // TPM implementation. An artificial behavior is placed here due to the 384 // limitation of a software simulation environment. For the correct behavior, 385 // consult the part 3 specification for TPM2_GetTestResult(). 386 TPM_RC 387 CryptGetTestResult( 388 TPM2B_MAX_BUFFER *outData // OUT: test result data 389 ); 390 391 //*** CryptValidateKeys() 392 // This function is used to verify that the key material of and object is valid. 393 // For a 'publicOnly' object, the key is verified for size and, if it is an ECC 394 // key, it is verified to be on the specified curve. For a key with a sensitive 395 // area, the binding between the public and private parts of the key are verified. 396 // If the nameAlg of the key is TPM_ALG_NULL, then the size of the sensitive area 397 // is verified but the public portion is not verified, unless the key is an RSA key. 398 // For an RSA key, the reason for loading the sensitive area is to use it. The 399 // only way to use a private RSA key is to compute the private exponent. To compute 400 // the private exponent, the public modulus is used. 401 // Return Type: TPM_RC 402 // TPM_RC_BINDING the public and private parts are not cryptographically 403 // bound 404 // TPM_RC_HASH cannot have a publicOnly key with nameAlg of TPM_ALG_NULL 405 // TPM_RC_KEY the public unique is not valid 406 // TPM_RC_KEY_SIZE the private area key is not valid 407 // TPM_RC_TYPE the types of the sensitive and private parts do not match 408 TPM_RC 409 CryptValidateKeys( 410 TPMT_PUBLIC *publicArea, 411 TPMT_SENSITIVE *sensitive, 412 TPM_RC blamePublic, 413 TPM_RC blameSensitive 414 ); 415 416 //*** CryptSelectMac() 417 // This function is used to set the MAC scheme based on the key parameters and 418 // the input scheme. 419 // Return Type: TPM_RC 420 // TPM_RC_SCHEME the scheme is not a valid mac scheme 421 // TPM_RC_TYPE the input key is not a type that supports a mac 422 // TPM_RC_VALUE the input scheme and the key scheme are not compatible 423 TPM_RC 424 CryptSelectMac( 425 TPMT_PUBLIC *publicArea, 426 TPMI_ALG_MAC_SCHEME *inMac 427 ); 428 429 //*** CryptMacIsValidForKey() 430 // Check to see if the key type is compatible with the mac type 431 BOOL 432 CryptMacIsValidForKey( 433 TPM_ALG_ID keyType, 434 TPM_ALG_ID macAlg, 435 BOOL flag 436 ); 437 438 //*** CryptSmacIsValidAlg() 439 // This function is used to test if an algorithm is a supported SMAC algorithm. It 440 // needs to be updated as new algorithms are added. 441 BOOL 442 CryptSmacIsValidAlg( 443 TPM_ALG_ID alg, 444 BOOL FLAG // IN: Indicates if TPM_ALG_NULL is valid 445 ); 446 447 //*** CryptSymModeIsValid() 448 // Function checks to see if an algorithm ID is a valid, symmetric block cipher 449 // mode for the TPM. If 'flag' is SET, them TPM_ALG_NULL is a valid mode. 450 // not include the modes used for SMAC 451 BOOL 452 CryptSymModeIsValid( 453 TPM_ALG_ID mode, 454 BOOL flag 455 ); 456 457 #endif // _CRYPT_UTIL_FP_H_ 458