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 7, 2020 Time: 07:06:44PM 38 */ 39 40 #ifndef _OBJECT_SPT_FP_H_ 41 #define _OBJECT_SPT_FP_H_ 42 43 //*** AdjustAuthSize() 44 // This function will validate that the input authValue is no larger than the 45 // digestSize for the nameAlg. It will then pad with zeros to the size of the 46 // digest. 47 BOOL 48 AdjustAuthSize( 49 TPM2B_AUTH *auth, // IN/OUT: value to adjust 50 TPMI_ALG_HASH nameAlg // IN: 51 ); 52 53 //*** AreAttributesForParent() 54 // This function is called by create, load, and import functions. 55 // 56 // Note: The 'isParent' attribute is SET when an object is loaded and it has 57 // attributes that are suitable for a parent object. 58 // Return Type: BOOL 59 // TRUE(1) properties are those of a parent 60 // FALSE(0) properties are not those of a parent 61 BOOL 62 ObjectIsParent( 63 OBJECT *parentObject // IN: parent handle 64 ); 65 66 //*** CreateChecks() 67 // Attribute checks that are unique to creation. 68 // Return Type: TPM_RC 69 // TPM_RC_ATTRIBUTES sensitiveDataOrigin is not consistent with the 70 // object type 71 // other returns from PublicAttributesValidation() 72 TPM_RC 73 CreateChecks( 74 OBJECT *parentObject, 75 TPMT_PUBLIC *publicArea, 76 UINT16 sensitiveDataSize 77 ); 78 79 //*** SchemeChecks 80 // This function is called by TPM2_LoadExternal() and PublicAttributesValidation(). 81 // This function validates the schemes in the public area of an object. 82 // Return Type: TPM_RC 83 // TPM_RC_HASH non-duplicable storage key and its parent have different 84 // name algorithm 85 // TPM_RC_KDF incorrect KDF specified for decrypting keyed hash object 86 // TPM_RC_KEY invalid key size values in an asymmetric key public area 87 // TPM_RCS_SCHEME inconsistent attributes 'decrypt', 'sign', 'restricted' 88 // and key's scheme ID; or hash algorithm is inconsistent 89 // with the scheme ID for keyed hash object 90 // TPM_RC_SYMMETRIC a storage key with no symmetric algorithm specified; or 91 // non-storage key with symmetric algorithm different from 92 // ALG_NULL 93 TPM_RC 94 SchemeChecks( 95 OBJECT *parentObject, // IN: parent (null if primary seed) 96 TPMT_PUBLIC *publicArea // IN: public area of the object 97 ); 98 99 //*** PublicAttributesValidation() 100 // This function validates the values in the public area of an object. 101 // This function is used in the processing of TPM2_Create, TPM2_CreatePrimary, 102 // TPM2_CreateLoaded(), TPM2_Load(), TPM2_Import(), and TPM2_LoadExternal(). 103 // For TPM2_Import() this is only used if the new parent has fixedTPM SET. For 104 // TPM2_LoadExternal(), this is not used for a public-only key 105 // Return Type: TPM_RC 106 // TPM_RC_ATTRIBUTES 'fixedTPM', 'fixedParent', or 'encryptedDuplication' 107 // attributes are inconsistent between themselves or with 108 // those of the parent object; 109 // inconsistent 'restricted', 'decrypt' and 'sign' 110 // attributes; 111 // attempt to inject sensitive data for an asymmetric key; 112 // attempt to create a symmetric cipher key that is not 113 // a decryption key 114 // TPM_RC_HASH nameAlg is TPM_ALG_NULL 115 // TPM_RC_SIZE 'authPolicy' size does not match digest size of the name 116 // algorithm in 'publicArea' 117 // other returns from SchemeChecks() 118 TPM_RC 119 PublicAttributesValidation( 120 OBJECT *parentObject, // IN: input parent object 121 TPMT_PUBLIC *publicArea // IN: public area of the object 122 ); 123 124 //*** FillInCreationData() 125 // Fill in creation data for an object. 126 // Return Type: void 127 void 128 FillInCreationData( 129 TPMI_DH_OBJECT parentHandle, // IN: handle of parent 130 TPMI_ALG_HASH nameHashAlg, // IN: name hash algorithm 131 TPML_PCR_SELECTION *creationPCR, // IN: PCR selection 132 TPM2B_DATA *outsideData, // IN: outside data 133 TPM2B_CREATION_DATA *outCreation, // OUT: creation data for output 134 TPM2B_DIGEST *creationDigest // OUT: creation digest 135 ); 136 137 //*** GetSeedForKDF() 138 // Get a seed for KDF. The KDF for encryption and HMAC key use the same seed. 139 const TPM2B * 140 GetSeedForKDF( 141 OBJECT *protector // IN: the protector handle 142 ); 143 144 //*** ProduceOuterWrap() 145 // This function produce outer wrap for a buffer containing the sensitive data. 146 // It requires the sensitive data being marshaled to the outerBuffer, with the 147 // leading bytes reserved for integrity hash. If iv is used, iv space should 148 // be reserved at the beginning of the buffer. It assumes the sensitive data 149 // starts at address (outerBuffer + integrity size @). 150 // This function: 151 // a) adds IV before sensitive area if required; 152 // b) encrypts sensitive data with IV or a NULL IV as required; 153 // c) adds HMAC integrity at the beginning of the buffer; and 154 // d) returns the total size of blob with outer wrap. 155 UINT16 156 ProduceOuterWrap( 157 OBJECT *protector, // IN: The handle of the object that provides 158 // protection. For object, it is parent 159 // handle. For credential, it is the handle 160 // of encrypt object. 161 TPM2B *name, // IN: the name of the object 162 TPM_ALG_ID hashAlg, // IN: hash algorithm for outer wrap 163 TPM2B *seed, // IN: an external seed may be provided for 164 // duplication blob. For non duplication 165 // blob, this parameter should be NULL 166 BOOL useIV, // IN: indicate if an IV is used 167 UINT16 dataSize, // IN: the size of sensitive data, excluding the 168 // leading integrity buffer size or the 169 // optional iv size 170 BYTE *outerBuffer // IN/OUT: outer buffer with sensitive data in 171 // it 172 ); 173 174 //*** UnwrapOuter() 175 // This function remove the outer wrap of a blob containing sensitive data 176 // This function: 177 // a) checks integrity of outer blob; and 178 // b) decrypts the outer blob. 179 // 180 // Return Type: TPM_RC 181 // TPM_RCS_INSUFFICIENT error during sensitive data unmarshaling 182 // TPM_RCS_INTEGRITY sensitive data integrity is broken 183 // TPM_RCS_SIZE error during sensitive data unmarshaling 184 // TPM_RCS_VALUE IV size for CFB does not match the encryption 185 // algorithm block size 186 TPM_RC 187 UnwrapOuter( 188 OBJECT *protector, // IN: The object that provides 189 // protection. For object, it is parent 190 // handle. For credential, it is the 191 // encrypt object. 192 TPM2B *name, // IN: the name of the object 193 TPM_ALG_ID hashAlg, // IN: hash algorithm for outer wrap 194 TPM2B *seed, // IN: an external seed may be provided for 195 // duplication blob. For non duplication 196 // blob, this parameter should be NULL. 197 BOOL useIV, // IN: indicates if an IV is used 198 UINT16 dataSize, // IN: size of sensitive data in outerBuffer, 199 // including the leading integrity buffer 200 // size, and an optional iv area 201 BYTE *outerBuffer // IN/OUT: sensitive data 202 ); 203 204 //*** SensitiveToPrivate() 205 // This function prepare the private blob for off the chip storage 206 // This function: 207 // a) marshals TPM2B_SENSITIVE structure into the buffer of TPM2B_PRIVATE 208 // b) applies encryption to the sensitive area; and 209 // c) applies outer integrity computation. 210 void 211 SensitiveToPrivate( 212 TPMT_SENSITIVE *sensitive, // IN: sensitive structure 213 TPM2B_NAME *name, // IN: the name of the object 214 OBJECT *parent, // IN: The parent object 215 TPM_ALG_ID nameAlg, // IN: hash algorithm in public area. This 216 // parameter is used when parentHandle is 217 // NULL, in which case the object is 218 // temporary. 219 TPM2B_PRIVATE *outPrivate // OUT: output private structure 220 ); 221 222 //*** PrivateToSensitive() 223 // Unwrap a input private area. Check the integrity, decrypt and retrieve data 224 // to a sensitive structure. 225 // This function: 226 // a) checks the integrity HMAC of the input private area; 227 // b) decrypts the private buffer; and 228 // c) unmarshals TPMT_SENSITIVE structure into the buffer of TPMT_SENSITIVE. 229 // Return Type: TPM_RC 230 // TPM_RCS_INTEGRITY if the private area integrity is bad 231 // TPM_RC_SENSITIVE unmarshal errors while unmarshaling TPMS_ENCRYPT 232 // from input private 233 // TPM_RCS_SIZE error during sensitive data unmarshaling 234 // TPM_RCS_VALUE outer wrapper does not have an iV of the correct 235 // size 236 TPM_RC 237 PrivateToSensitive( 238 TPM2B *inPrivate, // IN: input private structure 239 TPM2B *name, // IN: the name of the object 240 OBJECT *parent, // IN: parent object 241 TPM_ALG_ID nameAlg, // IN: hash algorithm in public area. It is 242 // passed separately because we only pass 243 // name, rather than the whole public area 244 // of the object. This parameter is used in 245 // the following two cases: 1. primary 246 // objects. 2. duplication blob with inner 247 // wrap. In other cases, this parameter 248 // will be ignored 249 TPMT_SENSITIVE *sensitive // OUT: sensitive structure 250 ); 251 252 //*** SensitiveToDuplicate() 253 // This function prepare the duplication blob from the sensitive area. 254 // This function: 255 // a) marshals TPMT_SENSITIVE structure into the buffer of TPM2B_PRIVATE; 256 // b) applies inner wrap to the sensitive area if required; and 257 // c) applies outer wrap if required. 258 void 259 SensitiveToDuplicate( 260 TPMT_SENSITIVE *sensitive, // IN: sensitive structure 261 TPM2B *name, // IN: the name of the object 262 OBJECT *parent, // IN: The new parent object 263 TPM_ALG_ID nameAlg, // IN: hash algorithm in public area. It 264 // is passed separately because we 265 // only pass name, rather than the 266 // whole public area of the object. 267 TPM2B *seed, // IN: the external seed. If external 268 // seed is provided with size of 0, 269 // no outer wrap should be applied 270 // to duplication blob. 271 TPMT_SYM_DEF_OBJECT *symDef, // IN: Symmetric key definition. If the 272 // symmetric key algorithm is NULL, 273 // no inner wrap should be applied. 274 TPM2B_DATA *innerSymKey, // IN/OUT: a symmetric key may be 275 // provided to encrypt the inner 276 // wrap of a duplication blob. May 277 // be generated here if needed. 278 TPM2B_PRIVATE *outPrivate // OUT: output private structure 279 ); 280 281 //*** DuplicateToSensitive() 282 // Unwrap a duplication blob. Check the integrity, decrypt and retrieve data 283 // to a sensitive structure. 284 // This function: 285 // a) checks the integrity HMAC of the input private area; 286 // b) decrypts the private buffer; and 287 // c) unmarshals TPMT_SENSITIVE structure into the buffer of TPMT_SENSITIVE. 288 // 289 // Return Type: TPM_RC 290 // TPM_RC_INSUFFICIENT unmarshaling sensitive data from 'inPrivate' failed 291 // TPM_RC_INTEGRITY 'inPrivate' data integrity is broken 292 // TPM_RC_SIZE unmarshaling sensitive data from 'inPrivate' failed 293 TPM_RC 294 DuplicateToSensitive( 295 TPM2B *inPrivate, // IN: input private structure 296 TPM2B *name, // IN: the name of the object 297 OBJECT *parent, // IN: the parent 298 TPM_ALG_ID nameAlg, // IN: hash algorithm in public area. 299 TPM2B *seed, // IN: an external seed may be provided. 300 // If external seed is provided with 301 // size of 0, no outer wrap is 302 // applied 303 TPMT_SYM_DEF_OBJECT *symDef, // IN: Symmetric key definition. If the 304 // symmetric key algorithm is NULL, 305 // no inner wrap is applied 306 TPM2B *innerSymKey, // IN: a symmetric key may be provided 307 // to decrypt the inner wrap of a 308 // duplication blob. 309 TPMT_SENSITIVE *sensitive // OUT: sensitive structure 310 ); 311 312 //*** SecretToCredential() 313 // This function prepare the credential blob from a secret (a TPM2B_DIGEST) 314 // This function: 315 // a) marshals TPM2B_DIGEST structure into the buffer of TPM2B_ID_OBJECT; 316 // b) encrypts the private buffer, excluding the leading integrity HMAC area; 317 // c) computes integrity HMAC and append to the beginning of the buffer; and 318 // d) sets the total size of TPM2B_ID_OBJECT buffer. 319 void 320 SecretToCredential( 321 TPM2B_DIGEST *secret, // IN: secret information 322 TPM2B *name, // IN: the name of the object 323 TPM2B *seed, // IN: an external seed. 324 OBJECT *protector, // IN: the protector 325 TPM2B_ID_OBJECT *outIDObject // OUT: output credential 326 ); 327 328 //*** CredentialToSecret() 329 // Unwrap a credential. Check the integrity, decrypt and retrieve data 330 // to a TPM2B_DIGEST structure. 331 // This function: 332 // a) checks the integrity HMAC of the input credential area; 333 // b) decrypts the credential buffer; and 334 // c) unmarshals TPM2B_DIGEST structure into the buffer of TPM2B_DIGEST. 335 // 336 // Return Type: TPM_RC 337 // TPM_RC_INSUFFICIENT error during credential unmarshaling 338 // TPM_RC_INTEGRITY credential integrity is broken 339 // TPM_RC_SIZE error during credential unmarshaling 340 // TPM_RC_VALUE IV size does not match the encryption algorithm 341 // block size 342 TPM_RC 343 CredentialToSecret( 344 TPM2B *inIDObject, // IN: input credential blob 345 TPM2B *name, // IN: the name of the object 346 TPM2B *seed, // IN: an external seed. 347 OBJECT *protector, // IN: the protector 348 TPM2B_DIGEST *secret // OUT: secret information 349 ); 350 351 //*** MemoryRemoveTrailingZeros() 352 // This function is used to adjust the length of an authorization value. 353 // It adjusts the size of the TPM2B so that it does not include octets 354 // at the end of the buffer that contain zero. 355 // 356 // This function returns the number of non-zero octets in the buffer. 357 UINT16 358 MemoryRemoveTrailingZeros( 359 TPM2B_AUTH *auth // IN/OUT: value to adjust 360 ); 361 362 //*** SetLabelAndContext() 363 // This function sets the label and context for a derived key. It is possible 364 // that 'label' or 'context' can end up being an Empty Buffer. 365 TPM_RC 366 SetLabelAndContext( 367 TPMS_DERIVE *labelContext, // IN/OUT: the recovered label and 368 // context 369 TPM2B_SENSITIVE_DATA *sensitive // IN: the sensitive data 370 ); 371 372 //*** UnmarshalToPublic() 373 // Support function to unmarshal the template. This is used because the 374 // Input may be a TPMT_TEMPLATE and that structure does not have the same 375 // size as a TPMT_PUBLIC because of the difference between the 'unique' and 376 // 'seed' fields. 377 // 378 // If 'derive' is not NULL, then the 'seed' field is assumed to contain 379 // a 'label' and 'context' that are unmarshaled into 'derive'. 380 TPM_RC 381 UnmarshalToPublic( 382 TPMT_PUBLIC *tOut, // OUT: output 383 TPM2B_TEMPLATE *tIn, // IN: 384 BOOL derivation, // IN: indicates if this is for a derivation 385 TPMS_DERIVE *labelContext// OUT: label and context if derivation 386 ); 387 388 //*** ObjectSetExternal() 389 // Set the external attributes for an object. 390 void 391 ObjectSetExternal( 392 OBJECT *object 393 ); 394 395 #endif // _OBJECT_SPT_FP_H_ 396