1Trusted Platform Module Library 2Part 3: Commands 3Family “2.0” 4Level 00 Revision 00.99 5October 31, 2013 6 7Contact: admin@trustedcomputinggroup.org 8 9Published 10Copyright © TCG 2006-2013 11 12TCG 13 14 Part 3: Commands 15 16Trusted Platform Module Library 17 18Licenses and Notices 191. Copyright Licenses: 20 21 22Trusted Computing Group (TCG) grants to the user of the source code in this specification (the 23“Source Code”) a worldwide, irrevocable, nonexclusive, royalty free, copyright license to 24reproduce, create derivative works, distribute, display and perform the Source Code and 25derivative works thereof, and to grant others the rights granted herein. 26 27 28 29The TCG grants to the user of the other parts of the specification (other than the Source Code) 30the rights to reproduce, distribute, display, and perform the specification solely for the purpose of 31developing products based on such documents. 32 332. Source Code Distribution Conditions: 34 35 36Redistributions of Source Code must retain the above copyright licenses, this list of conditions 37and the following disclaimers. 38 39 40 41Redistributions in binary form must reproduce the above copyright licenses, this list of conditions 42and the following disclaimers in the documentation and/or other materials provided with the 43distribution. 44 453. Disclaimers: 46 47 48THE COPYRIGHT LICENSES SET FORTH ABOVE DO NOT REPRESENT ANY FORM OF 49LICENSE OR WAIVER, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, WITH 50RESPECT TO PATENT RIGHTS HELD BY TCG MEMBERS (OR OTHER THIRD PARTIES) 51THAT MAY BE NECESSARY TO IMPLEMENT THIS SPECIFICATION OR OTHERWISE. 52Contact TCG Administration (admin@trustedcomputinggroup.org) for information on specification 53licensing rights available through TCG membership agreements. 54 55 56 57THIS SPECIFICATION IS PROVIDED "AS IS" WITH NO EXPRESS OR IMPLIED WARRANTIES 58WHATSOEVER, INCLUDING ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A 59PARTICULAR PURPOSE, ACCURACY, COMPLETENESS, OR NONINFRINGEMENT OF 60INTELLECTUAL PROPERTY RIGHTS, OR ANY WARRANTY OTHERWISE ARISING OUT OF 61ANY PROPOSAL, SPECIFICATION OR SAMPLE. 62 63 64 65Without limitation, TCG and its members and licensors disclaim all liability, including liability for 66infringement of any proprietary rights, relating to use of information in this specification and to the 67implementation of this specification, and TCG disclaims all liability for cost of procurement of 68substitute goods or services, lost profits, loss of use, loss of data or any incidental, consequential, 69direct, indirect, or special damages, whether under contract, tort, warranty or otherwise, arising in 70any way out of use or reliance upon this specification or any information herein. 71 72Any marks and brands contained herein are the property of their respective owner 73 74Page ii 75October 31, 2013 76 77Published 78Copyright © TCG 2006-2013 79 80Family “2.0” 81Level 00 Revision 00.99 82 83 Trusted Platform Module Library 84 85Part 3: Commands 86 87CONTENTS 881 892 903 914 92 93Scope .................................................................................................................................................... 1 94Terms and Definitions ........................................................................................................................... 1 95Symbols and abbreviated terms ............................................................................................................ 1 96Notation ................................................................................................................................................. 1 974.1 984.2 994.3 1004.4 101 1025 1036 1047 105 106Introduction ..................................................................................................................................... 1 107Table Decorations ........................................................................................................................... 1 108Handle and Parameter Demarcation .............................................................................................. 3 109AuthorizationSize and ParameterSize ............................................................................................ 3 110 111Normative References ........................................................................................................................... 4 112Symbols and Abbreviated Terms .......................................................................................................... 4 113Command Processing ........................................................................................................................... 4 1147.1 1157.2 1167.3 1177.4 1187.5 1197.6 1207.7 1217.8 1227.9 123 1248 125 126Introduction ..................................................................................................................................... 4 127Command Header Validation .......................................................................................................... 4 128Mode Checks .................................................................................................................................. 4 129Handle Area Validation ................................................................................................................... 5 130Session Area Validation .................................................................................................................. 6 131Authorization Checks ...................................................................................................................... 7 132Parameter Decryption ..................................................................................................................... 8 133Parameter Unmarshaling ................................................................................................................ 9 134Command Post Processing .......................................................................................................... 10 135 136Response Values ................................................................................................................................ 12 1378.1 1388.2 139 1409 14110 142 143Implementation Dependent ................................................................................................................. 15 144Detailed Actions Assumptions ............................................................................................................. 16 145 14610.1 14710.2 14810.3 14911 150 151Introduction ................................................................................................................................... 28 152TPM2_SelfTest ............................................................................................................................. 29 153TPM2_IncrementalSelfTest .......................................................................................................... 32 154TPM2_GetTestResult ................................................................................................................... 35 155 156Session Commands ............................................................................................................................ 38 157 15813.1 15913.2 16014 161 162Introduction ................................................................................................................................... 17 163_TPM_Init...................................................................................................................................... 17 164TPM2_Startup ............................................................................................................................... 19 165TPM2_Shutdown .......................................................................................................................... 24 166 167Testing ................................................................................................................................................. 28 168 16912.1 17012.2 17112.3 17212.4 17313 174 175Introduction ................................................................................................................................... 16 176Pre-processing .............................................................................................................................. 16 177Post Processing ............................................................................................................................ 16 178 179Start-up ................................................................................................................................................ 17 180 18111.1 18211.2 18311.3 18411.4 18512 186 187Tag ................................................................................................................................................ 12 188Response Codes .......................................................................................................................... 12 189 190TPM2_StartAuthSession .............................................................................................................. 38 191TPM2_PolicyRestart ..................................................................................................................... 43 192 193Object Commands............................................................................................................................... 46 194 195Family “2.0” 196Level 00 Revision 00.99 197 198Published 199Copyright © TCG 2006-2013 200 201Page iii 202October 31, 2013 203 204 Part 3: Commands 20514.1 20614.2 20714.3 20814.4 20914.5 21014.6 21114.7 21214.8 21315 214 215Introduction ................................................................................................................................. 132 216TPM2_HMAC_Start .................................................................................................................... 132 217TPM2_HashSequenceStart ........................................................................................................ 136 218TPM2_SequenceUpdate ............................................................................................................ 139 219TPM2_SequenceComplete......................................................................................................... 143 220TPM2_EventSequenceComplete ............................................................................................... 147 221 222Attestation Commands ...................................................................................................................... 151 223 22420.1 22520.2 22620.3 22720.4 22820.5 22920.6 23020.7 23121 232 233TPM2_GetRandom ..................................................................................................................... 126 234TPM2_StirRandom ..................................................................................................................... 129 235 236Hash/HMAC/Event Sequences ......................................................................................................... 132 237 23819.1 23919.2 24019.3 24119.4 24219.5 24319.6 24420 245 246Introduction ................................................................................................................................. 113 247TPM2_EncryptDecrypt ................................................................................................................ 115 248TPM2_Hash ................................................................................................................................ 119 249TPM2_HMAC .............................................................................................................................. 122 250 251Random Number Generator .............................................................................................................. 126 252 25318.1 25418.2 25519 256 257Introduction ................................................................................................................................... 92 258TPM2_RSA_Encrypt ..................................................................................................................... 92 259TPM2_RSA_Decrypt .................................................................................................................... 97 260TPM2_ECDH_KeyGen ............................................................................................................... 101 261TPM2_ECDH_ZGen ................................................................................................................... 104 262TPM2_ECC_Parameters ............................................................................................................ 107 263TPM2_ZGen_2Phase ................................................................................................................. 108 264 265Symmetric Primitives ......................................................................................................................... 113 266 26717.1 26817.2 26917.3 27017.4 27118 272 273TPM2_Duplicate ........................................................................................................................... 77 274TPM2_Rewrap .............................................................................................................................. 81 275TPM2_Import ................................................................................................................................ 86 276 277Asymmetric Primitives ......................................................................................................................... 92 278 27916.1 28016.2 28116.3 28216.4 28316.5 28416.6 28516.7 28617 287 288TPM2_Create................................................................................................................................ 46 289TPM2_Load .................................................................................................................................. 51 290TPM2_LoadExternal ..................................................................................................................... 55 291TPM2_ReadPublic ........................................................................................................................ 60 292TPM2_ActivateCredential ............................................................................................................. 63 293TPM2_MakeCredential ................................................................................................................. 67 294TPM2_Unseal ............................................................................................................................... 70 295TPM2_ObjectChangeAuth ............................................................................................................ 73 296 297Duplication Commands ....................................................................................................................... 77 298 29915.1 30015.2 30115.3 30216 303 304Trusted Platform Module Library 305 306Introduction ................................................................................................................................. 151 307TPM2_Certify .............................................................................................................................. 153 308TPM2_CertifyCreation ................................................................................................................ 157 309TPM2_Quote............................................................................................................................... 161 310TPM2_GetSessionAuditDigest ................................................................................................... 165 311TPM2_GetCommandAuditDigest ............................................................................................... 169 312TPM2_GetTime........................................................................................................................... 173 313 314Ephemeral EC Keys .......................................................................................................................... 177 315 316Page iv 317October 31, 2013 318 319Published 320Copyright © TCG 2006-2013 321 322Family “2.0” 323Level 00 Revision 00.99 324 325 Trusted Platform Module Library 32621.1 32721.2 32821.3 32922 330 331Introduction ................................................................................................................................. 200 332TPM2_PCR_Extend ................................................................................................................... 201 333TPM2_PCR_Event ..................................................................................................................... 204 334TPM2_PCR_Read ...................................................................................................................... 207 335TPM2_PCR_Allocate .................................................................................................................. 210 336TPM2_PCR_SetAuthPolicy ........................................................................................................ 213 337TPM2_PCR_SetAuthValue ......................................................................................................... 216 338TPM2_PCR_Reset ..................................................................................................................... 219 339_TPM_Hash_Start ...................................................................................................................... 222 340_TPM_Hash_Data ...................................................................................................................... 224 341_TPM_Hash_End ....................................................................................................................... 226 342 343Enhanced Authorization (EA) Commands ........................................................................................ 229 344 34525.1 34625.2 34725.3 34825.4 34925.5 35025.6 35125.7 35225.8 35325.9 35425.10 35525.11 35625.12 35725.13 35825.14 35925.15 36025.16 36125.17 36225.18 36325.19 36425.20 36526 366 367Introduction ................................................................................................................................. 195 368TPM2_SetCommandCodeAuditStatus ....................................................................................... 196 369 370Integrity Collection (PCR) .................................................................................................................. 200 371 37224.1 37324.2 37424.3 37524.4 37624.5 37724.6 37824.7 37924.8 38024.9 38124.10 38224.11 38325 384 385TPM2_VerifySignature ................................................................................................................ 187 386TPM2_Sign ................................................................................................................................. 191 387 388Command Audit ................................................................................................................................. 195 389 39023.1 39123.2 39224 393 394Introduction ................................................................................................................................. 177 395TPM2_Commit ............................................................................................................................ 178 396TPM2_EC_Ephemeral ................................................................................................................ 184 397 398Signing and Signature Verification .................................................................................................... 187 399 40022.1 40122.2 40223 403 404Part 3: Commands 405 406Introduction ................................................................................................................................. 229 407Signed Authorization Actions ...................................................................................................... 230 408TPM2_PolicySigned ................................................................................................................... 234 409TPM2_PolicySecret .................................................................................................................... 240 410TPM2_PolicyTicket ..................................................................................................................... 244 411TPM2_PolicyOR ......................................................................................................................... 248 412TPM2_PolicyPCR ....................................................................................................................... 252 413TPM2_PolicyLocality .................................................................................................................. 256 414TPM2_PolicyNV .......................................................................................................................... 260 415TPM2_PolicyCounterTimer......................................................................................................... 265 416TPM2_PolicyCommandCode ..................................................................................................... 270 417TPM2_PolicyPhysicalPresence .................................................................................................. 273 418TPM2_PolicyCpHash .................................................................................................................. 276 419TPM2_PolicyNameHash ............................................................................................................. 280 420TPM2_PolicyDuplicationSelect ................................................................................................... 283 421TPM2_PolicyAuthorize ............................................................................................................... 287 422TPM2_PolicyAuthValue .............................................................................................................. 291 423TPM2_PolicyPassword ............................................................................................................... 294 424TPM2_PolicyGetDigest ............................................................................................................... 297 425TPM2_PolicyNvWritten ............................................................................................................... 300 426 427Hierarchy Commands........................................................................................................................ 304 428 42926.1 43026.2 43126.3 432 433TPM2_CreatePrimary ................................................................................................................. 304 434TPM2_HierarchyControl ............................................................................................................. 308 435TPM2_SetPrimaryPolicy ............................................................................................................. 312 436 437Family “2.0” 438Level 00 Revision 00.99 439 440Published 441Copyright © TCG 2006-2013 442 443Page v 444October 31, 2013 445 446 Part 3: Commands 44726.4 44826.5 44926.6 45026.7 45126.8 45227 453 454TPM2_ReadClock ....................................................................................................................... 372 455TPM2_ClockSet .......................................................................................................................... 375 456TPM2_ClockRateAdjust .............................................................................................................. 378 457 458Capability Commands ....................................................................................................................... 381 459 46032.1 46132.2 46232.3 46333 464 465Introduction ................................................................................................................................. 354 466TPM2_ContextSave .................................................................................................................... 354 467TPM2_ContextLoad .................................................................................................................... 359 468TPM2_FlushContext ................................................................................................................... 364 469TPM2_EvictControl ..................................................................................................................... 367 470 471Clocks and Timers............................................................................................................................. 372 472 47331.1 47431.2 47531.3 47632 477 478Introduction ................................................................................................................................. 343 479TPM2_FieldUpgradeStart ........................................................................................................... 345 480TPM2_FieldUpgradeData ........................................................................................................... 348 481TPM2_FirmwareRead ................................................................................................................. 351 482 483Context Management ........................................................................................................................ 354 484 48530.1 48630.2 48730.3 48830.4 48930.5 49031 491 492Introduction ................................................................................................................................. 337 493TPM2_PP_Commands ............................................................................................................... 337 494TPM2_SetAlgorithmSet .............................................................................................................. 340 495 496Field Upgrade .................................................................................................................................... 343 497 49829.1 49929.2 50029.3 50129.4 50230 503 504Introduction ................................................................................................................................. 331 505TPM2_DictionaryAttackLockReset ............................................................................................. 331 506TPM2_DictionaryAttackParameters............................................................................................ 334 507 508Miscellaneous Management Functions ............................................................................................. 337 509 51028.1 51128.2 51228.3 51329 514 515TPM2_ChangePPS .................................................................................................................... 315 516TPM2_ChangeEPS .................................................................................................................... 318 517TPM2_Clear ................................................................................................................................ 321 518TPM2_ClearControl .................................................................................................................... 325 519TPM2_HierarchyChangeAuth ..................................................................................................... 328 520 521Dictionary Attack Functions ............................................................................................................... 331 522 52327.1 52427.2 52527.3 52628 527 528Trusted Platform Module Library 529 530Introduction ................................................................................................................................. 381 531TPM2_GetCapability ................................................................................................................... 381 532TPM2_TestParms ....................................................................................................................... 389 533 534Non-volatile Storage .......................................................................................................................... 392 535 53633.1 53733.2 53833.3 53933.4 54033.5 54133.6 54233.7 54333.8 54433.9 54533.10 54633.11 547 548Introduction ................................................................................................................................. 392 549NV Counters ............................................................................................................................... 393 550TPM2_NV_DefineSpace ............................................................................................................. 394 551TPM2_NV_UndefineSpace ......................................................................................................... 400 552TPM2_NV_UndefineSpaceSpecial ............................................................................................. 403 553TPM2_NV_ReadPublic ............................................................................................................... 406 554TPM2_NV_Write ......................................................................................................................... 409 555TPM2_NV_Increment ................................................................................................................. 413 556TPM2_NV_Extend ...................................................................................................................... 417 557TPM2_NV_SetBits ...................................................................................................................... 421 558TPM2_NV_WriteLock ................................................................................................................. 425 559 560Page vi 561October 31, 2013 562 563Published 564Copyright © TCG 2006-2013 565 566Family “2.0” 567Level 00 Revision 00.99 568 569 Trusted Platform Module Library 57033.12 57133.13 57233.14 57333.15 57433.16 575 576Part 3: Commands 577 578TPM2_NV_GlobalWriteLock ....................................................................................................... 429 579TPM2_NV_Read ......................................................................................................................... 432 580TPM2_NV_ReadLock ................................................................................................................. 435 581TPM2_NV_ChangeAuth ............................................................................................................. 438 582TPM2_NV_Certify ....................................................................................................................... 441 583 584Family “2.0” 585Level 00 Revision 00.99 586 587Published 588Copyright © TCG 2006-2013 589 590Page vii 591October 31, 2013 592 593 Part 3: Commands 594 595Trusted Platform Module Library 596 597Tables 598Table 1 — Command Modifiers and Decoration ........................................................................................... 2 599Table 2 — Separators ................................................................................................................................... 3 600Table 3 — Unmarshaling Errors ................................................................................................................. 10 601Table 4 — Command-Independent Response Codes ................................................................................ 13 602Table 5 — TPM2_Startup Command .......................................................................................................... 21 603Table 6 — TPM2_Startup Response .......................................................................................................... 21 604Table 7 — TPM2_Shutdown Command ..................................................................................................... 25 605Table 8 — TPM2_Shutdown Response ...................................................................................................... 25 606Table 9 — TPM2_SelfTest Command ........................................................................................................ 30 607Table 10 — TPM2_SelfTest Response ...................................................................................................... 30 608Table 11 — TPM2_IncrementalSelfTest Command ................................................................................... 33 609Table 12 — TPM2_IncrementalSelfTest Response ................................................................................... 33 610Table 13 — TPM2_GetTestResult Command ............................................................................................ 36 611Table 14 — TPM2_GetTestResult Response............................................................................................. 36 612Table 15 — TPM2_StartAuthSession Command ....................................................................................... 40 613Table 16 — TPM2_StartAuthSession Response ........................................................................................ 40 614Table 17 — TPM2_PolicyRestart Command .............................................................................................. 44 615Table 18 — TPM2_PolicyRestart Response .............................................................................................. 44 616Table 19 — TPM2_Create Command ........................................................................................................ 48 617Table 20 — TPM2_Create Response ......................................................................................................... 48 618Table 21 — TPM2_Load Command ........................................................................................................... 52 619Table 22 — TPM2_Load Response ............................................................................................................ 52 620Table 23 — TPM2_LoadExternal Command .............................................................................................. 57 621Table 24 — TPM2_LoadExternal Response .............................................................................................. 57 622Table 25 — TPM2_ReadPublic Command ................................................................................................. 61 623Table 26 — TPM2_ReadPublic Response ................................................................................................. 61 624Table 27 — TPM2_ActivateCredential Command ...................................................................................... 64 625Table 28 — TPM2_ActivateCredential Response ...................................................................................... 64 626Table 29 — TPM2_MakeCredential Command .......................................................................................... 68 627Table 30 — TPM2_MakeCredential Response .......................................................................................... 68 628Table 31 — TPM2_Unseal Command ........................................................................................................ 71 629Table 32 — TPM2_Unseal Response ........................................................................................................ 71 630Table 33 — TPM2_ObjectChangeAuth Command ..................................................................................... 74 631Table 34 — TPM2_ObjectChangeAuth Response ..................................................................................... 74 632Table 35 — TPM2_Duplicate Command .................................................................................................... 78 633Table 36 — TPM2_Duplicate Response ..................................................................................................... 78 634Table 37 — TPM2_Rewrap Command ....................................................................................................... 82 635Table 38 — TPM2_Rewrap Response ....................................................................................................... 82 636Page viii 637October 31, 2013 638 639Published 640Copyright © TCG 2006-2013 641 642Family “2.0” 643Level 00 Revision 00.99 644 645 Trusted Platform Module Library 646 647Part 3: Commands 648 649Table 39 — TPM2_Import Command ......................................................................................................... 88 650Table 40 — TPM2_Import Response ......................................................................................................... 88 651Table 41 — Padding Scheme Selection ..................................................................................................... 92 652Table 42 — Message Size Limits Based on Padding ................................................................................. 93 653Table 43 — TPM2_RSA_Encrypt Command.............................................................................................. 94 654Table 44 — TPM2_RSA_Encrypt Response .............................................................................................. 94 655Table 45 — TPM2_RSA_Decrypt Command ............................................................................................. 98 656Table 46 — TPM2_RSA_Decrypt Response .............................................................................................. 98 657Table 47 — TPM2_ECDH_KeyGen Command ........................................................................................ 102 658Table 48 — TPM2_ECDH_KeyGen Response ........................................................................................ 102 659Table 49 — TPM2_ECDH_ZGen Command ............................................................................................ 105 660Table 50 — TPM2_ECDH_ZGen Response ............................................................................................ 105 661Table 51 — TPM2_ECC_Parameters Command ..................................................................................... 107 662Table 52 — TPM2_ECC_Parameters Response ..................................................................................... 107 663Table 53 — TPM2_ZGen_2Phase Command .......................................................................................... 110 664Table 54 — TPM2_ZGen_2Phase Response .......................................................................................... 110 665Table 55 — Symmetric Chaining Process ................................................................................................ 114 666Table 56 — TPM2_EncryptDecrypt Command......................................................................................... 116 667Table 57 — TPM2_EncryptDecrypt Response ......................................................................................... 116 668Table 58 — TPM2_Hash Command ......................................................................................................... 120 669Table 59 — TPM2_Hash Response ......................................................................................................... 120 670Table 60 — TPM2_HMAC Command ....................................................................................................... 123 671Table 61 — TPM2_HMAC Response ....................................................................................................... 123 672Table 62 — TPM2_GetRandom Command .............................................................................................. 127 673Table 63 — TPM2_GetRandom Response .............................................................................................. 127 674Table 64 — TPM2_StirRandom Command .............................................................................................. 130 675Table 65 — TPM2_StirRandom Response ............................................................................................... 130 676Table 66 — Hash Selection Matrix ........................................................................................................... 132 677Table 67 — TPM2_HMAC_Start Command ............................................................................................. 133 678Table 68 — TPM2_HMAC_Start Response ............................................................................................. 133 679Table 69 — TPM2_HashSequenceStart Command ................................................................................. 137 680Table 70 — TPM2_HashSequenceStart Response ................................................................................. 137 681Table 71 — TPM2_SequenceUpdate Command ..................................................................................... 140 682Table 72 — TPM2_SequenceUpdate Response ...................................................................................... 140 683Table 73 — TPM2_SequenceComplete Command ................................................................................. 144 684Table 74 — TPM2_SequenceComplete Response .................................................................................. 144 685Table 75 — TPM2_EventSequenceComplete Command ........................................................................ 148 686Table 76 — TPM2_EventSequenceComplete Response ......................................................................... 148 687Table 77 — TPM2_Certify Command ....................................................................................................... 154 688Family “2.0” 689Level 00 Revision 00.99 690 691Published 692Copyright © TCG 2006-2013 693 694Page ix 695October 31, 2013 696 697 Part 3: Commands 698 699Trusted Platform Module Library 700 701Table 78 — TPM2_Certify Response ....................................................................................................... 154 702Table 79 — TPM2_CertifyCreation Command ......................................................................................... 158 703Table 80 — TPM2_CertifyCreation Response .......................................................................................... 158 704Table 81 — TPM2_Quote Command ....................................................................................................... 162 705Table 82 — TPM2_Quote Response ........................................................................................................ 162 706Table 83 — TPM2_GetSessionAuditDigest Command ............................................................................ 166 707Table 84 — TPM2_GetSessionAuditDigest Response ............................................................................ 166 708Table 85 — TPM2_GetCommandAuditDigest Command ........................................................................ 170 709Table 86 — TPM2_GetCommandAuditDigest Response ......................................................................... 170 710Table 87 — TPM2_GetTime Command ................................................................................................... 174 711Table 88 — TPM2_GetTime Response .................................................................................................... 174 712Table 89 — TPM2_Commit Command ..................................................................................................... 180 713Table 90 — TPM2_Commit Response ..................................................................................................... 180 714Table 91 — TPM2_EC_Ephemeral Command ......................................................................................... 185 715Table 92 — TPM2_EC_Ephemeral Response ......................................................................................... 185 716Table 93 — TPM2_VerifySignature Command......................................................................................... 188 717Table 94 — TPM2_VerifySignature Response ......................................................................................... 188 718Table 95 — TPM2_Sign Command .......................................................................................................... 192 719Table 96 — TPM2_Sign Response .......................................................................................................... 192 720Table 97 — TPM2_SetCommandCodeAuditStatus Command ................................................................ 197 721Table 98 — TPM2_SetCommandCodeAuditStatus Response ................................................................ 197 722Table 99 — TPM2_PCR_Extend Command ............................................................................................ 202 723Table 100 — TPM2_PCR_Extend Response ........................................................................................... 202 724Table 101 — TPM2_PCR_Event Command ............................................................................................ 205 725Table 102 — TPM2_PCR_Event Response ............................................................................................. 205 726Table 103 — TPM2_PCR_Read Command ............................................................................................. 208 727Table 104 — TPM2_PCR_Read Response ............................................................................................. 208 728Table 105 — TPM2_PCR_Allocate Command ......................................................................................... 211 729Table 106 — TPM2_PCR_Allocate Response ......................................................................................... 211 730Table 107 — TPM2_PCR_SetAuthPolicy Command ............................................................................... 214 731Table 108 — TPM2_PCR_SetAuthPolicy Response ............................................................................... 214 732Table 109 — TPM2_PCR_SetAuthValue Command ............................................................................... 217 733Table 110 — TPM2_PCR_SetAuthValue Response ................................................................................ 217 734Table 111 — TPM2_PCR_Reset Command ............................................................................................ 220 735Table 112 — TPM2_PCR_Reset Response ............................................................................................. 220 736Table 113 — TPM2_PolicySigned Command .......................................................................................... 236 737Table 114 — TPM2_PolicySigned Response ........................................................................................... 236 738Table 115 — TPM2_PolicySecret Command ........................................................................................... 241 739Table 116 — TPM2_PolicySecret Response ............................................................................................ 241 740Page x 741October 31, 2013 742 743Published 744Copyright © TCG 2006-2013 745 746Family “2.0” 747Level 00 Revision 00.99 748 749 Trusted Platform Module Library 750 751Part 3: Commands 752 753Table 117 — TPM2_PolicyTicket Command ............................................................................................ 245 754Table 118 — TPM2_PolicyTicket Response ............................................................................................ 245 755Table 119 — TPM2_PolicyOR Command ................................................................................................ 249 756Table 120 — TPM2_PolicyOR Response ................................................................................................. 249 757Table 121 — TPM2_PolicyPCR Command .............................................................................................. 253 758Table 122 — TPM2_PolicyPCR Response .............................................................................................. 253 759Table 123 — TPM2_PolicyLocality Command ......................................................................................... 257 760Table 124 — TPM2_PolicyLocality Response .......................................................................................... 257 761Table 125 — TPM2_PolicyNV Command ................................................................................................. 261 762Table 126 — TPM2_PolicyNV Response ................................................................................................. 261 763Table 127 — TPM2_PolicyCounterTimer Command ............................................................................... 266 764Table 128 — TPM2_PolicyCounterTimer Response ................................................................................ 266 765Table 129 — TPM2_PolicyCommandCode Command ............................................................................ 271 766Table 130 — TPM2_PolicyCommandCode Response ............................................................................. 271 767Table 131 — TPM2_PolicyPhysicalPresence Command ......................................................................... 274 768Table 132 — TPM2_PolicyPhysicalPresence Response ......................................................................... 274 769Table 133 — TPM2_PolicyCpHash Command......................................................................................... 277 770Table 134 — TPM2_PolicyCpHash Response ......................................................................................... 277 771Table 135 — TPM2_PolicyNameHash Command.................................................................................... 281 772Table 136 — TPM2_PolicyNameHash Response .................................................................................... 281 773Table 137 — TPM2_PolicyDuplicationSelect Command .......................................................................... 284 774Table 138 — TPM2_PolicyDuplicationSelect Response .......................................................................... 284 775Table 139 — TPM2_PolicyAuthorize Command ...................................................................................... 288 776Table 140 — TPM2_PolicyAuthorize Response ....................................................................................... 288 777Table 141 — TPM2_PolicyAuthValue Command ..................................................................................... 292 778Table 142 — TPM2_PolicyAuthValue Response ..................................................................................... 292 779Table 143 — TPM2_PolicyPassword Command ...................................................................................... 295 780Table 144 — TPM2_PolicyPassword Response ...................................................................................... 295 781Table 145 — TPM2_PolicyGetDigest Command...................................................................................... 298 782Table 146 — TPM2_PolicyGetDigest Response ...................................................................................... 298 783Table 133 — TPM2_PolicyNvWritten Command ...................................................................................... 301 784Table 134 — TPM2_PolicyNvWritten Response ...................................................................................... 301 785Table 147 — TPM2_CreatePrimary Command ........................................................................................ 305 786Table 148 — TPM2_CreatePrimary Response ........................................................................................ 305 787Table 149 — TPM2_HierarchyControl Command .................................................................................... 309 788Table 150 — TPM2_HierarchyControl Response .................................................................................... 309 789Table 151 — TPM2_SetPrimaryPolicy Command .................................................................................... 313 790Table 152 — TPM2_SetPrimaryPolicy Response .................................................................................... 313 791Table 153 — TPM2_ChangePPS Command ........................................................................................... 316 792Family “2.0” 793Level 00 Revision 00.99 794 795Published 796Copyright © TCG 2006-2013 797 798Page xi 799October 31, 2013 800 801 Part 3: Commands 802 803Trusted Platform Module Library 804 805Table 154 — TPM2_ChangePPS Response ............................................................................................ 316 806Table 155 — TPM2_ChangeEPS Command ........................................................................................... 319 807Table 156 — TPM2_ChangeEPS Response ............................................................................................ 319 808Table 157 — TPM2_Clear Command ....................................................................................................... 322 809Table 158 — TPM2_Clear Response ....................................................................................................... 322 810Table 159 — TPM2_ClearControl Command ........................................................................................... 326 811Table 160 — TPM2_ClearControl Response ........................................................................................... 326 812Table 161 — TPM2_HierarchyChangeAuth Command ............................................................................ 329 813Table 162 — TPM2_HierarchyChangeAuth Response ............................................................................ 329 814Table 163 — TPM2_DictionaryAttackLockReset Command .................................................................... 332 815Table 164 — TPM2_DictionaryAttackLockReset Response .................................................................... 332 816Table 165 — TPM2_DictionaryAttackParameters Command .................................................................. 335 817Table 166 — TPM2_DictionaryAttackParameters Response ................................................................... 335 818Table 167 — TPM2_PP_Commands Command ...................................................................................... 338 819Table 168 — TPM2_PP_Commands Response ...................................................................................... 338 820Table 169 — TPM2_SetAlgorithmSet Command ..................................................................................... 341 821Table 170 — TPM2_SetAlgorithmSet Response...................................................................................... 341 822Table 171 — TPM2_FieldUpgradeStart Command .................................................................................. 346 823Table 172 — TPM2_FieldUpgradeStart Response .................................................................................. 346 824Table 173 — TPM2_FieldUpgradeData Command .................................................................................. 349 825Table 174 — TPM2_FieldUpgradeData Response .................................................................................. 349 826Table 175 — TPM2_FirmwareRead Command........................................................................................ 352 827Table 176 — TPM2_FirmwareRead Response ........................................................................................ 352 828Table 177 — TPM2_ContextSave Command........................................................................................... 355 829Table 178 — TPM2_ContextSave Response ........................................................................................... 355 830Table 179 — TPM2_ContextLoad Command ........................................................................................... 360 831Table 180 — TPM2_ContextLoad Response ........................................................................................... 360 832Table 181 — TPM2_FlushContext Command .......................................................................................... 365 833Table 182 — TPM2_FlushContext Response .......................................................................................... 365 834Table 183 — TPM2_EvictControl Command ............................................................................................ 369 835Table 184 — TPM2_EvictControl Response ............................................................................................ 369 836Table 185 — TPM2_ReadClock Command.............................................................................................. 373 837Table 186 — TPM2_ReadClock Response .............................................................................................. 373 838Table 187 — TPM2_ClockSet Command ................................................................................................. 376 839Table 188 — TPM2_ClockSet Response ................................................................................................. 376 840Table 189 — TPM2_ClockRateAdjust Command..................................................................................... 379 841Table 190 — TPM2_ClockRateAdjust Response ..................................................................................... 379 842Table 191 — TPM2_GetCapability Command.......................................................................................... 385 843Table 192 — TPM2_GetCapability Response .......................................................................................... 385 844Page xii 845October 31, 2013 846 847Published 848Copyright © TCG 2006-2013 849 850Family “2.0” 851Level 00 Revision 00.99 852 853 Trusted Platform Module Library 854 855Part 3: Commands 856 857Table 193 — TPM2_TestParms Command .............................................................................................. 390 858Table 194 — TPM2_TestParms Response .............................................................................................. 390 859Table 195 — TPM2_NV_DefineSpace Command ................................................................................... 396 860Table 196 — TPM2_NV_DefineSpace Response .................................................................................... 396 861Table 197 — TPM2_NV_UndefineSpace Command ............................................................................... 401 862Table 198 — TPM2_NV_UndefineSpace Response ................................................................................ 401 863Table 199 — TPM2_NV_UndefineSpaceSpecial Command .................................................................... 404 864Table 200 — TPM2_NV_UndefineSpaceSpecial Response .................................................................... 404 865Table 201 — TPM2_NV_ReadPublic Command ...................................................................................... 407 866Table 202 — TPM2_NV_ReadPublic Response ...................................................................................... 407 867Table 203 — TPM2_NV_Write Command ................................................................................................ 410 868Table 204 — TPM2_NV_Write Response ................................................................................................ 410 869Table 205 — TPM2_NV_Increment Command ........................................................................................ 414 870Table 206 — TPM2_NV_Increment Response......................................................................................... 414 871Table 207 — TPM2_NV_Extend Command ............................................................................................. 418 872Table 208 — TPM2_NV_Extend Response ............................................................................................. 418 873Table 209 — TPM2_NV_SetBits Command ............................................................................................. 422 874Table 210 — TPM2_NV_SetBits Response ............................................................................................. 422 875Table 211 — TPM2_NV_WriteLock Command ........................................................................................ 426 876Table 212 — TPM2_NV_WriteLock Response......................................................................................... 426 877Table 213 — TPM2_NV_GlobalWriteLock Command .............................................................................. 430 878Table 214 — TPM2_NV_GlobalWriteLock Response .............................................................................. 430 879Table 215 — TPM2_NV_Read Command................................................................................................ 433 880Table 216 — TPM2_NV_Read Response ................................................................................................ 433 881Table 217 — TPM2_NV_ReadLock Command ........................................................................................ 436 882Table 218 — TPM2_NV_ReadLock Response ........................................................................................ 436 883Table 219 — TPM2_NV_ChangeAuth Command .................................................................................... 439 884Table 220 — TPM2_NV_ChangeAuth Response .................................................................................... 439 885Table 221 — TPM2_NV_Certify Command .............................................................................................. 442 886Table 222 — TPM2_NV_Certify Response .............................................................................................. 442 887 888Family “2.0” 889Level 00 Revision 00.99 890 891Published 892Copyright © TCG 2006-2013 893 894Page xiii 895October 31, 2013 896 897 Trusted Platform Module Library 898 899Part 3: Commands 900 901Trusted Platform Module Library 902Part 3: Commands 9031 904 905Scope 906 907This part 3 of the Trusted Module Library specification contains the definitions of the TPM commands. 908These commands make use of the constants, flags, structure, and union definitions defined in part 2: 909Structures. 910The detailed description of the operation of the commands is written in the C language with extensive 911comments. The behavior of the C code in this part 3 is normative but does not fully describe the behavior 912of a TPM. The combination of this part 3 and part 4: Supporting Routines is sufficient to fully describe the 913required behavior of a TPM. 914The code in parts 3 and 4 is written to define the behavior of a compliant TPM. In some cases (e.g., 915firmware update), it is not possible to provide a compliant implementation. In those cases, any 916implementation provided by the vendor that meets the general description of the function provided in part 9173 would be compliant. 918The code in parts 3 and 4 is not written to meet any particular level of conformance nor does this 919specification require that a TPM meet any particular level of conformance. 9202 921 922Terms and Definitions 923 924For the purposes of this document, the terms and definitions given in part 1 of this specification apply. 9253 926 927Symbols and abbreviated terms 928 929For the purposes of this document, the symbols and abbreviated terms given in part 1 apply. 9304 931 932Notation 933 9344.1 Introduction 935In addition to the notation in this clause, the “Notations” clause in Part 1 of this specification is applicable 936to this Part 3. 937Command and response tables used various decorations to indicate the fields of the command and the 938allowed types. These decorations are described in this clause. 9394.2 940 941Table Decorations 942 943The symbols and terms in the Notation column of Table 1 are used in the tables for the command 944schematics. These values indicate various qualifiers for the parameters or descriptions with which they 945are associated. 946 947Family “2.0” 948Level 00 Revision 00.99 949 950Published 951Copyright © TCG 2006-2013 952 953Page 1 954October 31, 2013 955 956 Part 3: Commands 957 958Trusted Platform Module Library 959Table 1 — Command Modifiers and Decoration 960 961Notation 962 963Meaning 964 965+ 966 967A Type decoration – When appended to a value in the Type column of a command, this symbol 968indicates that the parameter is allowed to use the “null” value of the data type (see "Conditional 969Types" in Part 2). The null value is usually TPM_RH_NULL for a handle or TPM_ALG_NULL for 970an algorithm selector. 971 972@ 973 974A Name decoration – When this symbol precedes a handle parameter in the “Name” column, it 975indicates that an authorization session is required for use of the entity associated with the handle. 976If a handle does not have this symbol, then an authorization session is not allowed. 977 978+PP 979 980A Description modifier – This modifier may follow TPM_RH_PLATFORM in the “Description” 981column to indicate that Physical Presence is required when platformAuth/platformPolicy is 982provided. 983 984+{PP} 985 986A Description modifier – This modifier may follow TPM_RH_PLATFORM to indicate that Physical 987Presence may be required when platformAuth/platformPolicy is provided. The commands with this 988notation may be in the setList or clearList of TPM2_PP_Commands(). 989 990{NV} 991 992A Description modifier – This modifier may follow the commandCode in the “Description” column 993to indicate that the command may result in an update of NV memory and be subject to rate 994throttling by the TPM. If the command code does not have this notation, then a write to NV 995memory does not occur as part of the command actions. 996NOTE Any command that uses authorization may cause a write to NV if there is an authorization 997failure. A TPM may use the occasion of command execution to update the NV 998copy of clock. 999 1000{F} 1001 1002A Description modifier – This modifier indicates that the “flushed” attribute will be SET in the 1003TPMA_CC for the command. The modifier may follow the commandCode in the “Description” 1004column to indicate that any transient handle context used by the command will be flushed from the 1005TPM when the command completes. This may be combined with the {NV} modifier but not with the 1006{E} modifier. 1007EXAMPLE 1 1008 1009{E} 1010 1011{NV F} 1012 1013EXAMPLE 2 1014 1015TPM2_SequenceComplete() will flush the context associated with the sequenceHandle. 1016 1017A Description modifier – This modifier indicates that the “extensive” attribute will be SET in the 1018TPMA_CC for the command. This modifier may follow the commandCode in the “Description” 1019column to indicate that the command may flush many objects and re-enumeration of the loaded 1020context likely will be required. This may be combined with the {NV} modifier but not with the {F} 1021modifier. 1022EXAMPLE 1 1023 1024Auth Index: 1025 1026{NV E} 1027 1028EXAMPLE 2 1029 1030TPM2_Clear() will flush all contexts associated with the Storage hierarchy and the 1031Endorsement hierarchy. 1032 1033A Description modifier – When a handle has a “@” decoration, the “Description” column will 1034contain an “Auth Index:” entry for the handle. This entry indicates the number of the authorization 1035session. The authorization sessions associated with handles will occur in the session area in the 1036order of the handles with the “@” modifier. Sessions used only for encryption/decryption or only for 1037audit will follow the handles used for authorization. 1038 1039Page 2 1040October 31, 2013 1041 1042Published 1043Copyright © TCG 2006-2013 1044 1045Family “2.0” 1046Level 00 Revision 00.99 1047 1048 Trusted Platform Module Library 1049 1050Part 3: Commands 1051 1052Notation 1053 1054Meaning 1055 1056Auth Role: 1057 1058A Description modifier – This will be in the “Description” column of a handle with the “@” 1059decoration. It may have a value of USER, ADMIN or DUP. If the handle has the Auth Role of 1060USER and the handle is an Object, the type of authorization is determined by the setting of 1061userWithAuth in the Object's attributes. If the Auth Role is ADMIN and the handle is an Object, the 1062type of authorization is determined by the setting of adminWithPolicy in the Object's attributes. If 1063the DUP role is selected, authorization may only be with a policy session (DUP role only applies to 1064Objects). When either ADMIN or DUP role is selected, a policy command that selects the 1065command being authorized is required to be part of the policy. 1066EXAMPLE 1067 1068TPM2_Certify requires the ADMIN role for the first handle (objectHandle). The policy authorization 1069for objectHandle is required to contain TPM2_PolicyCommandCode(commandCode == 1070TPM_CC_Certify). This sets the state of the policy so that it can be used for ADMIN role 1071authorization in TPM2_Certify(). 1072 1073If the handle references an NV Index, then the allowed authorizations are determined by the 1074settings of the attributes of the NV Index as described in Part 2, "TPMA_NV (NV Index Attributes)." 1075 10764.3 1077 1078Handle and Parameter Demarcation 1079 1080The demarcations between the header, handle, and parameter parts are indicated by: 1081Table 2 — Separators 1082Separator 1083 1084Meaning 1085the values immediately following are in the handle area 1086the values immediately following are in the parameter area 1087 10884.4 1089 1090AuthorizationSize and ParameterSize 1091 1092Authorization sessions are not shown in the command or response schematics. When the tag of a 1093command or response is TPM_ST_SESSIONS, then a 32-bit value will be present in the 1094command/response buffer to indicate the size of the authorization field or the parameter field. This value 1095shall immediately follow the handle area (which may contain no handles). For a command, this value 1096(authorizationSize) indicates the size of the Authorization Area and shall have a value of 9 or more. For a 1097response, this value (parameterSize) indicates the size of the parameter area and may have a value of 1098zero. 1099If the authorizationSize field is present in the command, parameterSize will be present in the response, 1100but only if the responseCode is TPM_RC_SUCCESS. 1101When the command tag is TPM_ST_NO_SESSIONS, no authorizations are present and no 1102authorizationSize field is required and shall not be present. 1103 1104Family “2.0” 1105Level 00 Revision 00.99 1106 1107Published 1108Copyright © TCG 2006-2013 1109 1110Page 3 1111October 31, 2013 1112 1113 Part 3: Commands 1114 11155 1116 1117Trusted Platform Module Library 1118 1119Normative References 1120 1121The “Normative References” clause in Part 1 of this specification is applicable to this Part 3. 11226 1123 1124Symbols and Abbreviated Terms 1125 1126The “Symbols and Abbreviated Terms” clause in Part 1 of this specification is applicable to this Part 3. 1127 11287 11297.1 1130 1131Command Processing 1132Introduction 1133 1134This clause defines the command validations that are required of any implementation and the response 1135code returned if the indicated check fails. Unless stated otherwise, the order of the checks is not 1136normative and different TPM may give different responses when a command has multiple errors. 1137In the description below, some statements that describe a check may be followed by a response code in 1138parentheses. This is the normative response code should the indicated check fail. A normative response 1139code may also be included in the statement. 11407.2 1141 1142Command Header Validation 1143 1144Before a TPM may begin the actions associated with a command, a set of command format and 1145consistency checks shall be performed. These checks are listed below and should be performed in the 1146indicated order. 1147a) The TPM shall successfully unmarshal a TPMI_ST_COMMAND_TAG and verify that it is either 1148TPM_ST_SESSIONS or TPM_ST_NO_SESSIONS (TPM_RC_BAD_TAG). 1149b) The TPM shall successfully unmarshal a UINT32 as the commandSize. If the TPM has an interface 1150buffer that is loaded by some hardware process, the number of octets in the input buffer for the 1151command reported by the hardware process shall exactly match the value in commandSize 1152(TPM_RC_COMMAND_SIZE). 1153NOTE 1154 1155A TPM may have direct access to system memory and unmarshal directly from that memory. 1156 1157c) The TPM shall successfully unmarshal a TPM_CC and verify that the command is implemented 1158(TPM_RC_COMMAND_CODE). 11597.3 1160 1161Mode Checks 1162 1163The following mode checks shall be performed in the order listed: 1164 1165Page 4 1166October 31, 2013 1167 1168Published 1169Copyright © TCG 2006-2013 1170 1171Family “2.0” 1172Level 00 Revision 00.99 1173 1174 Trusted Platform Module Library 1175 1176Part 3: Commands 1177 1178a) If the TPM is in Failure mode, then the commandCode is TPM_CC_GetTestResult or 1179TPM_CC_GetCapability (TPM_RC_FAILURE) and the command tag is TPM_ST_NO_SESSIONS 1180(TPM_RC_FAILURE). 1181NOTE 1 1182 1183In Failure mode, the TPM has no cryptographic capability and proc essing of sessions is not 1184supported. 1185 1186b) The TPM is in Field Upgrade mode (FUM), the commandCode is TPM_CC_FieldUpgradeData 1187(TPM_RC_UPGRADE). 1188c) If the TPM has not been initialized (TPM2_Startup()), then the commandCode is TPM_CC_Startup 1189(TPM_RC_INITIALIZE). 1190NOTE 2 1191 1192The TPM may enter Failure mode during _TPM_Init processing, before TPM2_Startup(). Since 1193the platform firmware cannot know that the TPM is in Failure mode without accessing it, and 1194since the first command is required to be TPM2_Startup(), the expected sequence will be that 1195platform firmware (the CRTM) will issue TPM2_Startup() and receive TPM_RC_FAILURE 1196indicating that the TPM is in Failure mode. 1197There may be failures where a TPM cannot record that it received TPM2_Startup(). In those 1198cases, a TPM in failure mode may process TPM2_GetTestResult(), TPM2_GetCapability(), or 1199the field upgrade commands. As a side effect, that TPM may process TPM2_GetTestResult(), 1200TPM2_GetCapability() or the field upgrade commands before TPM2_Startup(). 1201This is a corner case exception to the rule that TPM2_Startup() must be the first command. 1202 1203The mode checks may be performed before or after the command header validation. 12047.4 Handle Area Validation 1205After successfully unmarshaling and validating the command header, the TPM shall perform the following 1206checks on the handles and sessions. These checks may be performed in any order. 1207a) The TPM shall successfully unmarshal the number of handles required by the command and validate 1208that the value of the handle is consistent with the command syntax. If not, the TPM shall return 1209TPM_RC_VALUE. 1210NOTE 1 1211 1212The TPM may unmarshal a handle and validate that it references an entity on the TPM before 1213unmarshaling a subsequent handle. 1214 1215NOTE 2 1216 1217If the submitted command contains fewer handles than required by the syntax of the command, 1218the TPM may continue to read into the next area and attempt to interpret the data as a handle. 1219 1220b) For all handles in the handle area of the command, the TPM will validate that the referenced entity is 1221present in the TPM. 12221) If the handle references a transient object, the handle shall reference a loaded object 1223(TPM_RC_REFERENCE_H0 + N where N is the number of the handle in the command). 1224NOTE 3 1225 1226If the hierarchy for a transient object is disabled, then the transient objects will be flushe d so this 1227check will fail. 1228 12292) If the handle references a persistent object, then 1230i) 1231 1232the handle shall reference a persistent object that is currently in TPM non-volatile memory 1233(TPM_RC_HANDLE); 1234 1235ii) 1236 1237the hierarchy associated with the object is not disabled (TPM_RC_HIERARCHY); and 1238 1239iii) if the TPM implementation moves a persistent object to RAM for command processing then 1240sufficient RAM space is available (TPM_RC_OBJECT_MEMORY). 1241 1242Family “2.0” 1243Level 00 Revision 00.99 1244 1245Published 1246Copyright © TCG 2006-2013 1247 1248Page 5 1249October 31, 2013 1250 1251 Part 3: Commands 1252 1253Trusted Platform Module Library 1254 12553) If the handle references an NV Index, then 1256i) 1257 1258an Index exists that corresponds to the handle (TPM_RC_HANDLE); and 1259 1260ii) 1261 1262the hierarchy associated with the existing NV Index is not disabled (TPM_RC_HANDLE). 1263 1264iii) the hierarchy associated 1265(TPM_RC_HIERARCHY) 1266 1267with 1268 1269an 1270 1271NV 1272 1273index 1274 1275being 1276 1277defined 1278 1279is 1280 1281not 1282 1283disabled 1284 12854) If the handle references a session, then the session context shall be present in TPM memory 1286(TPM_RC_REFERENCE_S0 + N). 12875) If the handle references a primary seed for a hierarchy (TPM_RH_ENDORSEMENT, 1288TPM_RH_OWNER, or TPM_RH_PLATFORM) then the enable for the hierarchy is SET 1289(TPM_RC_HIERARCHY). 12906) If the handle references a PCR, then the value is within the range of PCR supported by the TPM 1291(TPM_RC_VALUE) 1292NOTE 4 1293 12947.5 1295 1296In the reference implementation, this TPM_RC_VALUE is returned by the unmarshaling code for 1297a TPMI_DH_PCR. 1298 1299Session Area Validation 1300 1301a) If the tag is TPM_ST_SESSIONS and the command is a context management command 1302(TPM2_ContextSave(), TPM2_ContextLoad(), or TPM2_FlushContext()) the TPM will return 1303TPM_RC_AUTH_CONTEXT. 1304b) If the tag is TPM_ST_SESSIONS, the TPM will attempt to unmarshal an authorizationSize and return 1305TPM_RC_AUTHSIZE if the value is not within an acceptable range. 13061) The minimum value is (sizeof(TPM_HANDLE) + sizeof(UINT16) + sizeof(TPMA_SESSION) + 1307sizeof(UINT16)). 13082) The maximum value of authorizationSize is equal to commandSize – (sizeof(TPM_ST) + 1309sizeof(UINT32) + sizeof(TPM_CC) + (N * sizeof(TPM_HANDLE)) + sizeof(UINT32)) where N is 1310the number of handles associated with the commandCode and may be zero. 1311NOTE 1 1312 1313(sizeof(TPM_ST) + sizeof(UINT32) + sizeof(TPM_CC)) is the size of a command header. The 1314last UINT32 contains the authorizationSize octets, which are not counted as being in the 1315authorization session area. 1316 1317c) The TPM will unmarshal the authorization sessions and perform the following validations: 13181) If the session handle is not a handle for an HMAC session, a handle for a policy session, or, 1319TPM_RS_PW then the TPM shall return TPM_RC_HANDLE. 13202) If the session is not loaded, the TPM will return the warning TPM_RC_REFERENCE_S0 + N 1321where N is the number of the session. The first session is session zero, N = 0. 1322NOTE 2 1323 1324If the HMAC and policy session contexts use the same memory, the type of the context must 1325match the type of the handle. 1326 13273) If the maximum allowed number of sessions have been unmarshaled and fewer octets than 1328indicated in authorizationSize were unmarshaled (that is, authorizationSize is too large), the TPM 1329shall return TPM_RC_AUTHSIZE. 1330 1331Page 6 1332October 31, 2013 1333 1334Published 1335Copyright © TCG 2006-2013 1336 1337Family “2.0” 1338Level 00 Revision 00.99 1339 1340 Trusted Platform Module Library 1341 1342Part 3: Commands 1343 13444) The consistency of the authorization session attributes is checked. 1345i) 1346 1347An authorization session is present for each of the handles with the “@” decoration 1348(TPM_RC_AUTH_MISSING). 1349 1350ii) 1351 1352Only one session is allowed for: 1353(a) session auditing (TPM_RC_ATTRIBUTES) – this session may be used for encrypt or 1354decrypt but may not be a session that is also used for authorization; 1355(b) decrypting a command parameter (TPM_RC_ATTRIBUTES) – this may be any of the 1356authorization sessions, or the audit session, or a session may be added for the single 1357purpose of decrypting a command parameter, as long as the total number of sessions 1358does not exceed three; and 1359(c) encrypting a response parameter (TPM_RC_ATTRIBUTES) – this may be any of the 1360authorization sessions, or the audit session if present, ora session may be added for the 1361single purpose of encrypting a response parameter, as long as the total number of 1362sessions does not exceed three. 1363NOTE 3 1364 13657.6 1366 1367A session used for decrypting a command parameter may also be used for 1368encrypting a response parameter. 1369 1370Authorization Checks 1371 1372After unmarshaling and validating the handles and the consistency of the authorization sessions, the 1373authorizations shall be checked. Authorization checks only apply to handles if the handle in the command 1374schematic has the “@” decoration. 1375a) The public and sensitive portions 1376(TPM_RC_AUTH_UNAVAILABLE). 1377 1378of 1379 1380the 1381 1382object 1383 1384shall 1385 1386be 1387 1388present 1389 1390on 1391 1392the 1393 1394TPM 1395 1396b) If the associated handle is TPM_RH_PLATFORM, and the command requires confirmation with 1397physical presence, then physical presence is asserted (TPM_RC_PP). 1398c) If the object or NV Index is subject to DA protection, and the authorization is with an HMAC or 1399password, then the TPM is not in lockout (TPM_RC_LOCKOUT). 1400NOTE 1 1401 1402An object is subject to DA protection if its noDA attribute is CLEAR. An NV Index is subject to 1403DA protection if its TPMA_NV_NO_DA attribute is CLEAR. 1404 1405NOTE 2 1406 1407An HMAC or password is required in a policy 1408TPM2_PolicyAuthValue() or TPM2_PolicyPassword(). 1409 1410session 1411 1412when 1413 1414the 1415 1416policy 1417 1418contains 1419 1420d) If the command requires a handle to have DUP role authorization, then the associated authorization 1421session is a policy session (TPM_RC_POLICY_FAIL). 1422e) If the command requires a handle to have ADMIN role authorization: 14231) If the entity being authorized is an object and its adminWithPolicy attribute is SET, then the 1424authorization session is a policy session (TPM_RC_POLICY_FAIL). 1425NOTE 3 1426 1427If adminWithPolicy is CLEAR, then any type of authorization session is allowed . 1428 14292) If the entity being authorized is an NV Index, then the associated authorization session is a policy 1430session. 1431NOTE 4 1432 1433The only commands that are currently defined that required use of ADMIN role authorization are 1434commands that operate on objects and NV Indices. 1435 1436Family “2.0” 1437Level 00 Revision 00.99 1438 1439Published 1440Copyright © TCG 2006-2013 1441 1442Page 7 1443October 31, 2013 1444 1445 Part 3: Commands 1446f) 1447 1448Trusted Platform Module Library 1449 1450If the command requires a handle to have USER role authorization: 14511) If the entity being authorized is an object and its userWithAuth attribute is CLEAR, then the 1452associated authorization session is a policy session (TPM_RC_POLICY_FAIL). 14532) If the entity being authorized is an NV Index; 1454i) 1455 1456if the authorization session is a policy session; 1457(a) the TPMA_NV_POLICYWRITE attribute of the NV Index is SET if the command modifies 1458the NV Index data (TPM_RC_AUTH_UNAVAILABLE); 1459(b) the TPMA_NV_POLICYREAD attribute of the NV Index is SET if the command reads the 1460NV Index data (TPM_RC_AUTH_UNAVAILABLE); 1461 1462ii) 1463 1464if the authorization is an HMAC session or a password; 1465(a) the TPMA_NV_AUTHWRITE attribute of the NV Index is SET if the command modifies 1466the NV Index data (TPM_RC_AUTH_UNAVAILABLE); 1467(b) the TPMA_NV_AUTHREAD attribute of the NV Index is SET if the command reads the 1468NV Index data (TPM_RC_AUTH_UNAVAILABLE). 1469 1470g) If the authorization is provided by a policy session, then: 14711) if policySession→timeOut 1472(TPM_RC_EXPIRED); 1473 1474has 1475 1476been 1477 1478set, 1479 1480the 1481 1482session 1483 1484shall 1485 1486not 1487 1488have 1489 1490expired 1491 14922) if policySession→cpHash has been set, it shall match the cpHash of the command 1493(TPM_RC_POLICY_FAIL); 14943) if policySession→commandCode has been set, then commandCode of the command shall match 1495(TPM_RC_POLICY_CC); 14964) policySession→policyDigest 1497(TPM_RC_POLICY_FAIL); 1498 1499shall 1500 1501match 1502 1503the 1504 1505authPolicy 1506 1507associated 1508 1509with 1510 1511the 1512 1513handle 1514 15155) if policySession→pcrUpdateCounter has been set, then it shall match the value of 1516pcrUpdateCounter (TPM_RC_PCR_CHANGED); 15176) if policySession->commandLocality has been set, it shall match the locality of the command 1518(TPM_RC_LOCALITY), and 15197) if the authorization uses an HMAC, then the HMAC is properly constructed using the authValue 1520associated with the handle and/or the session secret (TPM_RC_AUTH_FAIL or 1521TPM_RC_BAD_AUTH). 1522NOTE 5 1523 1524For a bound session, if the handle references the object us ed to initiate the session, then the 1525authValue will not be required but proof of knowledge of the session secret is necessary. 1526 1527NOTE 6 1528 1529A policy session may require proof of knowledge of the authValue of the object being authorized. 1530 1531If the TPM returns an error other than TPM_RC_AUTH_FAIL then the TPM shall not alter any TPM state. 1532If the TPM return TPM_RC_AUTH_FAIL, then the TPM shall not alter any TPM state other than 1533lockoutCount. 1534NOTE 7 1535 15367.7 1537 1538The TPM may decrease failedTries regardless of any other processing performed by the TPM. That 1539is, the TPM may exit Lockout mode, regardless of the return code. 1540 1541Parameter Decryption 1542 1543If an authorization session has the TPMA_SESSION.decrypt attribute SET, and the command does not 1544allow a command parameter to be encrypted, then the TPM will return TPM_RC_ATTRIBUTES. 1545 1546Page 8 1547October 31, 2013 1548 1549Published 1550Copyright © TCG 2006-2013 1551 1552Family “2.0” 1553Level 00 Revision 00.99 1554 1555 Trusted Platform Module Library 1556 1557Part 3: Commands 1558 1559Otherwise, the TPM will decrypt the parameter using the values associated with the session before 1560parsing parameters. 15617.8 15627.8.1 1563 1564Parameter Unmarshaling 1565Introduction 1566 1567The detailed actions for each command assume that the input parameters of the command have been 1568unmarshaled into a command-specific structure with the structure defined by the command schematic. 1569Additionally, a response-specific output structure is assumed which will receive the values produced by 1570the detailed actions. 1571NOTE 1572 1573An implementation is not required to process parameters in this manner or to separate the 1574parameter parsing from the command actions. This method was chosen for the specification so that 1575the normative behavior described by the detailed actions would be clear and unencumbered. 1576 1577Unmarshaling is the process of processing the parameters in the input buffer and preparing the 1578parameters for use by the command-specific action code. No data movement need take place but it is 1579required that the TPM validate that the parameters meet the requirements of the expected data type as 1580defined in Part 2 of this specification. 15817.8.2 1582 1583Unmarshaling Errors 1584 1585When an error is encountered while unmarshaling a command parameter, an error response code is 1586returned and no command processing occurs. A table defining a data type may have response codes 1587embedded in the table to indicate the error returned when the input value does not match the parameters 1588of the table. 1589NOTE 1590 1591In the reference implementation, a parameter number is added to the response code so that the 1592offending parameter can be isolated. This is optional. 1593 1594In many cases, the table contains no specific response code value and the return code will be determined 1595as defined in Table 3. 1596 1597Family “2.0” 1598Level 00 Revision 00.99 1599 1600Published 1601Copyright © TCG 2006-2013 1602 1603Page 9 1604October 31, 2013 1605 1606 Part 3: Commands 1607 1608Trusted Platform Module Library 1609Table 3 — Unmarshaling Errors 1610 1611Response Code 1612 1613Meaning 1614 1615TPM_RC_ASYMMETRIC 1616 1617a parameter that should be an asymmetric algorithm selection does not have a 1618value that is supported by the TPM 1619 1620TPM_RC_BAD_TAG 1621 1622a parameter that should be a command tag selection has a value that is not 1623supported by the TPM 1624 1625TPM_RC_COMMAND_CODE 1626 1627a parameter that should be a command code does not have a value that is 1628supported by the TPM 1629 1630TPM_RC_HASH 1631 1632a parameter that should be a hash algorithm selection does not have a value that 1633is supported by the TPM 1634 1635TPM_RC_INSUFFICIENT 1636 1637the input buffer did not contain enough octets to allow unmarshaling of the 1638expected data type; 1639 1640TPM_RC_KDF 1641 1642a parameter that should be a key derivation scheme (KDF) selection does not 1643have a value that is supported by the TPM 1644 1645TPM_RC_KEY_SIZE 1646 1647a parameter that is a key size has a value that is not supported by the TPM 1648 1649TPM_RC_MODE 1650 1651a parameter that should be a symmetric encryption mode selection does not have 1652a value that is supported by the TPM 1653 1654TPM_RC_RESERVED 1655 1656a non-zero value was found in a reserved field of an attribute structure (TPMA_) 1657 1658TPM_RC_SCHEME 1659 1660a parameter that should be signing or encryption scheme selection does not have 1661a value that is supported by the TPM 1662 1663TPM_RC_SIZE 1664 1665the value of a size parameter is larger or smaller than allowed 1666 1667TPM_RC_SYMMETRIC 1668 1669a parameter that should be a symmetric algorithm selection does not have a 1670value that is supported by the TPM 1671 1672TPM_RC_TAG 1673 1674a parameter that should be a structure tag has a value that is not supported by 1675the TPM 1676 1677TPM_RC_TYPE 1678 1679The type parameter of a TPMT_PUBLIC or TPMT_SENSITIVE has a value that is 1680not supported by the TPM 1681 1682TPM_RC_VALUE 1683 1684a parameter does not have one of its allowed values 1685 1686In some commands, a parameter may not be used because of various options of that command. 1687However, the unmarshaling code is required to validate that all parameters have values that are allowed 1688by the Part 2 definition of the parameter type even if that parameter is not used in the command actions. 16897.9 1690 1691Command Post Processing 1692 1693When the code that implements the detailed actions of the command completes, it returns a response 1694code. If that code is not TPM_RC_SUCCESS, the post processing code will not update any session or 1695audit data and will return a 10-octet response packet. 1696If the command completes successfully, the tag of the command determines if any authorization sessions 1697will be in the response. If so, the TPM will encrypt the first parameter of the response if indicated by the 1698authorization attributes. The TPM will then generate a new nonce value for each session and, if 1699appropriate, generate an HMAC. 1700 1701Page 10 1702October 31, 2013 1703 1704Published 1705Copyright © TCG 2006-2013 1706 1707Family “2.0” 1708Level 00 Revision 00.99 1709 1710 Trusted Platform Module Library 1711 1712Part 3: Commands 1713 1714NOTE 1 1715 1716The authorization attributes were validated during the session area validation to ensure that only 1717one session was used for parameter encryption of the response and that the command allowed 1718encryption in the response. 1719 1720NOTE 2 1721 1722No session nonce value is used for a password authorization but the session data is present. 1723 1724Additionally, if the command is being audited by Command Audit, the audit digest is updated with the 1725cpHash of the command and rpHash of the response. 1726 1727Family “2.0” 1728Level 00 Revision 00.99 1729 1730Published 1731Copyright © TCG 2006-2013 1732 1733Page 11 1734October 31, 2013 1735 1736 Part 3: Commands 1737 17388 17398.1 1740 1741Trusted Platform Module Library 1742 1743Response Values 1744Tag 1745 1746When a command completes successfully, the tag parameter in the response shall have the same value 1747as the tag parameter in the command (TPM_ST_SESSIONS or TPM_RC_NO_SESSIONS). When a 1748command fails (the responseCode is not TPM_RC_SUCCESS), then the tag parameter in the response 1749shall be TPM_ST_NO_SESSIONS. 1750A special case exists when the command tag parameter is not an allowed value (TPM_ST_SESSIONS or 1751TPM_ST_NO_SESSIONS). For this case, it is assumed that the system software is attempting to send a 1752command formatted for a TPM 1.2 but the TPM is not capable of executing TPM 1.2 commands. So that 1753the TPM 1.2 compatible software will have a recognizable response, the TPM sets tag to 1754TPM_ST_RSP_COMMAND, responseSize to 00 00 00 0A16 and responseCode to TPM_RC_BAD_TAG. 1755This is the same response as the TPM 1.2 fatal error for TPM_BADTAG. 17568.2 1757 1758Response Codes 1759 1760The normal response for any command is TPM_RC_SUCCESS. Any other value indicates that the 1761command did not complete and the state of the TPM is unchanged. An exception to this general rule is 1762that the logic associated with dictionary attack protection is allowed to be modified when an authorization 1763failure occurs. 1764Commands have response codes that are specific to that command, and those response codes are 1765enumerated in the detailed actions of each command. The codes associated with the unmarshaling of 1766parameters are documented Table 3. Another set of response code value are not command specific and 1767indicate a problem that is not specific to the command. That is, if the indicated problem is remedied, the 1768same command could be resubmitted and may complete normally. 1769The response codes that are not command specific are listed and described in Table 4. 1770The reference code for the command actions may have code that generates specific response codes 1771associated with a specific check but the listing of responses may not have that response code listed. 1772 1773Page 12 1774October 31, 2013 1775 1776Published 1777Copyright © TCG 2006-2013 1778 1779Family “2.0” 1780Level 00 Revision 00.99 1781 1782 Trusted Platform Module Library 1783 1784Part 3: Commands 1785 1786Table 4 — Command-Independent Response Codes 1787Response Code 1788 1789Meaning 1790 1791TPM_RC_CANCELLED 1792 1793This response code may be returned by a TPM that supports command cancel. 1794When the TPM receives an indication that the current command should be 1795cancelled, the TPM may complete the command or return this code. If this code 1796is returned, then the TPM state is not changed and the same command may be 1797retried. 1798 1799TPM_RC_CONTEXT_GAP 1800 1801This response code can be returned for commands that manage session 1802contexts. It indicates that the gap between the lowest numbered active session 1803and the highest numbered session is at the limits of the session tracking logic. 1804The remedy is to load the session context with the lowest number so that its 1805tracking number can be updated. 1806 1807TPM_RC_LOCKOUT 1808 1809This response indicates that authorizations for objects subject to DA protection 1810are not allowed at this time because the TPM is in DA lockout mode. The remedy 1811is to wait or to exeucte TPM2_DictionaryAttackLockoutReset(). 1812 1813TPM_RC_MEMORY 1814 1815A TPM may use a common pool of memory for objects, sessions, and other 1816purposes. When the TPM does not have enough memory available to perform 1817the actions of the command, it may return TPM_RC_MEMORY. This indicates 1818that the TPM resource manager may flush either sessions or objects in order to 1819make memory available for the command execution. A TPM may choose to 1820return TPM_RC_OBJECT_MEMORY or TPM_RC_SESSION_MEMORY if it 1821needs contexts of a particular type to be flushed. 1822 1823TPM_RC_NV_RATE 1824 1825This response code indicates that the TPM is rate-limiting writes to the NV 1826memory in order to prevent wearout. This response is possible for any command 1827that explicity writes to NV or commands that incidentally use NV such as a 1828command that uses authorization session that may need to update the dictionary 1829attack logic. 1830 1831TPM_RC_NV_UNAVAILABLE 1832 1833This response code is similar to TPM_RC_NV_RATE but indicates that access to 1834NV memory is currently not available and the command is not allowed to proceed 1835until it is. This would occur in a system where the NV memory used by the TPM 1836is not exclusive to the TPM and is a shared system resource. 1837 1838TPM_RC_OBJECT_HANDLES 1839 1840This response code indicates that the TPM has exhausted its handle space and 1841no new objects can be loaded unless the TPM is rebooted. This does not occur in 1842the reference implementation because of the way that object handles are 1843allocated. However, other implementations are allowed to assign each object a 1844unique handle each time the object is loaded. A TPM using this implementation 184524 1846would be able to load 2 objects before the object space is exhausted. 1847 1848TPM_RC_OBJECT_MEMORY 1849 1850This response code can be returned by any command that causes the TPM to 1851need an object 'slot'. The most common case where this might be returned is 1852when an object is loaded (TPM2_Load, TPM2_CreatePrimary(), or 1853TPM2_ContextLoad()). However, the TPM implementation is allowed to use 1854object slots for other reasons. In the reference implementation, the TPM copies a 1855referenced persistent object into RAM for the duration of the commannd. If all the 1856slots are previously occupied, the TPM may return this value. A TPM is allowed 1857to use object slots for other purposes and return this value. The remedy when 1858this response is returned is for the TPM resource manager to flush a transient 1859object. 1860 1861TPM_RC_REFERENCE_Hx 1862 1863This response code indicates that a handle in the handle area of the command is 1864not associated with a loaded object. The value of 'x' is in the range 0 to 6 with a 1865st 1866th 1867value of 0 indicating the 1 handle and 6 representing the 7 . The TPM resource 1868manager needs to find the correct object and load it. It may then adjust the 1869handle and retry the command. 1870NOTE 1871 1872Family “2.0” 1873Level 00 Revision 00.99 1874 1875Usually, this error indicates that the TPM resource manager has a corrupted 1876database. 1877 1878Published 1879Copyright © TCG 2006-2013 1880 1881Page 13 1882October 31, 2013 1883 1884 Part 3: Commands 1885 1886Trusted Platform Module Library 1887 1888Response Code 1889 1890Meaning 1891 1892TPM_RC_REFERENCE_Sx 1893 1894This response code indicates that a handle in the session area of the command 1895is not associated with a loaded session. The value of 'x' is in the range 0 to 6 with 1896st 1897th 1898a value of 0 indicating the 1 session handle and 6 representing the 7 . The 1899TPM resource manager needs to find the correct session and load it. It may then 1900retry the command. 1901NOTE Usually, this error indicates that the TPM resource manager has a 1902corrupted database. 1903 1904TPM_RC_RETRY 1905 1906the TPM was not able to start the command 1907 1908This response code indicates that the TPM does not have a handle to assign to a 1909new session. This respose is only returned by TPM2_StartAuthSession(). It is 1910TPM_RC_SESSION_HANDLES 1911listed here because the command is not in error and the TPM resource manager 1912can remedy the situation by flushing a session (TPM2_FlushContext(). 1913 1914TPM_RC_SESSION_MEMORY 1915 1916This response code can be returned by any command that causes the TPM to 1917need a session 'slot'. The most common case where this might be returned is 1918when a session is loaded (TPM2_StartAuthSession() or TPM2_ContextLoad()). 1919However, the TPM implementation is allowed to use object slots for other 1920purposes. The remedy when this response is returned is for the TPM resource 1921manager to flush a transient object. 1922 1923TPM_RC_SUCCESS 1924 1925Normal completion for any command. If the responseCode is 1926TPM_RC_SESSIONS, then the rest of the response has the format indicated in 1927the response schematic. Otherwise, the response is a 10 octet value indicating 1928an error. 1929 1930TPM_RC_TESTING 1931 1932This response code indicates that the TPM is performing tests and cannot 1933respond to the request at this time. The command may be retried. 1934 1935TPM_RC_YIELDED 1936 1937the TPM has suspended operation on the command; forward progress was made 1938and the command may be retried. 1939See Part 1, “Multi-tasking.” 1940NOTE 1941 1942Page 14 1943October 31, 2013 1944 1945This cannot occur on the reference implementation. 1946 1947Published 1948Copyright © TCG 2006-2013 1949 1950Family “2.0” 1951Level 00 Revision 00.99 1952 1953 Trusted Platform Module Library 1954 19559 1956 1957Part 3: Commands 1958 1959Implementation Dependent 1960 1961The actions code for each command makes assumptions about the behavior of various sub-systems. 1962There are many possible implementations of the subsystems that would achieve equivalent results. The 1963actions code is not written to anticipate all possible implementations of the sub-systems. Therefore, it is 1964the responsibility of the implementer to ensure that the necessary changes are made to the actions code 1965when the sub-system behavior changes. 1966 1967Family “2.0” 1968Level 00 Revision 00.99 1969 1970Published 1971Copyright © TCG 2006-2013 1972 1973Page 15 1974October 31, 2013 1975 1976 Part 3: Commands 1977 1978Trusted Platform Module Library 1979 1980Detailed Actions Assumptions 1981 198210 198310.1 1984 1985Introduction 1986 1987The C code in the Detailed Actions for each command is written with a set of assumptions about the 1988processing performed before the action code is called and the processing that will be done after the 1989action code completes. 199010.2 1991 1992Pre-processing 1993 1994Before calling the command actions code, the following actions have occurred. 1995 1996 1997Verification that the handles in the handle area reference entities that are resident on the TPM. 1998NOTE 1999 2000If a handle is in the parameter portion of the command, the associated entity does not have to 2001be loaded, but the handle is required to be the correct type. 2002 2003 2004 2005If use of a handle requires authorization, the Password, HMAC, or Policy session associated with the 2006handle has been verified. 2007 2008 2009 2010If a command parameter was encrypted using parameter encryption, it was decrypted before being 2011unmarshaled. 2012 2013 2014 2015If the command uses handles or parameters, the calling stack contains a pointer to a data structure 2016(in) that holds the unmarshaled values for the handles and commands. If the response has handles 2017or parameters, the calling stack contains a pointer to a data structure ( out) to hold the handles and 2018parameters generated by the command. 2019 2020 2021 2022All parameters of the in structure have been validated and meet the requirements of the parameter 2023type as defined in Part 2. 2024 2025 2026 2027Space set aside for the out structure is sufficient to hold the largest out structure that could be 2028produced by the command 2029 203010.3 2031 2032Post Processing 2033 2034When the function implementing the command actions completes, 2035 2036 2037response parameters that require parameter encryption will be encrypted after the command actions 2038complete; 2039 2040 2041 2042audit and session contexts will be updated if the command response is TPM_RC_SUCCESS; and 2043 2044 2045 2046the command header and command response parameters will be marshaled to the response buffer. 2047 2048Page 16 2049October 31, 2013 2050 2051Published 2052Copyright © TCG 2006-2013 2053 2054Family “2.0” 2055Level 00 Revision 00.99 2056 2057 Trusted Platform Module Library 2058 205911 2060 2061Part 3: Commands 2062 2063Start-up 2064 206511.1 2066 2067Introduction 2068 2069This clause contains the commands used to manage the startup and restart state of a TPM. 207011.2 2071 2072_TPM_Init 2073 207411.2.1 General Description 2075_TPM_Init initializes a TPM. 2076Initialization actions include testing code required to execute the next expected command. If the TPM is in 2077FUM, the next expected command is TPM2_FieldUpgradeData(); otherwise, the next expected command 2078is TPM2_Startup(). 2079NOTE 1 2080 2081If the TPM performs self-tests after receiving _TPM_Init() and the TPM enters Failure mode before 2082receiving TPM2_Startup() or TPM2_FieldUpgradeData(), then the TPM may be able to accept 2083TPM2_GetTestResult() or TPM2_GetCapability(). 2084 2085The means of signaling _TPM_Init shall be defined in the platform-specific specifications that define the 2086physical interface to the TPM. The platform shall send this indication whenever the platform starts its boot 2087process and only when the platform starts its boot process. 2088There shall be no software method of generating this indication that does not also reset the platform and 2089begin execution of the CRTM. 2090NOTE 2 2091 2092In the reference implementation, this signal causes an internal flag ( s_initialized) to be CLEAR. 2093While this flag is CLEAR, the TPM will only accept the next expected command described above. 2094 2095Family “2.0” 2096Level 00 Revision 00.99 2097 2098Published 2099Copyright © TCG 2006-2013 2100 2101Page 17 2102October 31, 2013 2103 2104 Part 3: Commands 2105 2106Trusted Platform Module Library 2107 210811.2.2 Detailed Actions 21091 2110 2111#include "InternalRoutines.h" 2112 2113This function is used to process a _TPM_Init() indication. 21142 21153 21164 21175 21186 21197 21208 21219 212210 212311 212412 212513 212614 212715 212816 212917 213018 213119 213220 213321 213422 213523 213624 2137 2138void _TPM_Init(void) 2139{ 2140// Initialize crypto engine 2141CryptInitUnits(); 2142// Initialize NV environment 2143NvPowerOn(); 2144// Start clock 2145TimePowerOn(); 2146// Set initialization state 2147TPMInit(); 2148// Set g_DRTMHandle as unassigned 2149g_DRTMHandle = TPM_RH_UNASSIGNED; 2150// No H-CRTM, yet. 2151g_DrtmPreStartup = FALSE; 2152return; 2153} 2154 2155Page 18 2156October 31, 2013 2157 2158Published 2159Copyright © TCG 2006-2013 2160 2161Family “2.0” 2162Level 00 Revision 00.99 2163 2164 Trusted Platform Module Library 2165 216611.3 2167 2168Part 3: Commands 2169 2170TPM2_Startup 2171 217211.3.1 General Description 2173TPM2_Startup() is always preceded by _TPM_Init, which is the physical indication that TPM initialization 2174is necessary because of a system-wide reset. TPM2_Startup() is only valid after _TPM_Init Additional 2175TPM2_Startup() commands are not allowed after it has completed successfully. If a TPM requires 2176TPM2_Startup() and another command is received, or if the TPM receives TPM2_Startup() when it is not 2177required, the TPM shall return TPM_RC_INITIALIZE. 2178NOTE 1 2179 2180See 11.2.1 for other command options for a TPM supporting field upgrade mode. 2181 2182NOTE 2 2183 2184_TPM_Hash_Start, _TPM_Hash_Data, and _TPM_Hash_End are not commands and a platform specific specification may allow these indications between _TPM_Init and TPM2_Startup(). 2185 2186If in Failure mode the TPM shall accept TPM2_GetTestResult() and TPM2_GetCapability() even if 2187TPM2_Startup() is not completed successfully or processed at all. 2188A Shutdown/Startup sequence determines the way in which the TPM will operate in response to 2189TPM2_Startup(). The three sequences are: 21901) TPM Reset – This is a Startup(CLEAR) preceded by either Shutdown(CLEAR) or no 2191TPM2_Shutdown(). On TPM Reset, all variables go back to their default initialization state. 2192NOTE 3 2193 2194Only those values that are specified as having a default initialization state are changed by TPM 2195Reset. Persistent values that have no default initialization state are not changed by this 2196command. Values such as seeds have no default initialization state and only change due to 2197specific commands. 2198 21992) TPM Restart – This is a Startup(CLEAR) preceded by Shutdown(STATE). This preserves much of the 2200previous state of the TPM except that PCR and the controls associated with the Platform hierarchy 2201are all returned to their default initialization state; 22023) TPM Resume – This is a Startup(STATE) preceded by Shutdown(STATE). This preserves the 2203previous state of the TPM including the static Root of Trust for Measurement (S-RTM) PCR and the 2204platform controls other than the phEnable and phEnableNV. 2205If a TPM receives Startup(STATE) and that was not preceded by Shutdown(STATE), the TPM shall return 2206TPM_RC_VALUE. 2207If, during TPM Restart or TPM Resume, the TPM fails to restore the state saved at the last 2208Shutdown(STATE), the TPM shall enter Failure Mode and return TPM_RC_FAILURE. 2209On any TPM2_Startup(), 2210 2211 2212phEnable and phEnableNV shall be SET; 2213 2214 2215 2216all transient contexts (objects, sessions, and sequences) shall be flushed from TPM memory; 2217 2218 2219 2220TPMS_TIME_INFO.time shall be reset to zero; and 2221 2222 2223 2224use of lockoutAuth shall be enabled if lockoutRecovery is zero. 2225 2226Additional actions are performed based on the Shutdown/Startup sequence. 2227On TPM Reset 2228 2229Family “2.0” 2230Level 00 Revision 00.99 2231 2232Published 2233Copyright © TCG 2006-2013 2234 2235Page 19 2236October 31, 2013 2237 2238 Part 3: Commands 2239 2240Trusted Platform Module Library 2241 2242 2243 2244platformAuth and platformPolicy shall be set to the Empty Buffer, 2245 2246 2247 2248tracking data for saved session contexts shall be set to its initial value, 2249 2250 2251 2252the object context sequence number is reset to zero, 2253 2254 2255 2256a new context encryption key shall be generated, 2257 2258 2259 2260TPMS_CLOCK_INFO.restartCount shall be reset to zero, 2261 2262 2263 2264TPMS_CLOCK_INFO.resetCount shall be incremented, 2265 2266 2267 2268the PCR Update Counter shall be clear to zero, 2269 2270 2271 2272shEnable and ehEnable shall be SET, and 2273 2274 2275 2276PCR in all banks are reset to their default initial conditions as determined by the relevant platformspecific specification. 2277NOTE 4 2278 2279PCR may be initialized any time between _TPM_Init and the end of TPM2_Startup(). PCR that 2280are preserved by TPM Resume will need to be restored during TPM2_Startup(). 2281 2282NOTE 5 2283 2284See "Initializing PCR" in Part 1 of this specification for a description of the default initial 2285conditions for a PCR. 2286 2287On TPM Restart 2288 2289 2290TPMS_CLOCK_INFO.restartCount shall be incremented, 2291 2292 2293 2294shEnable and ehEnable shall be SET, 2295 2296 2297 2298platformAuth and platformPolicy shall be set to the Empty Buffer, and 2299 2300 2301 2302PCR in all banks are reset to their default initial conditions. 2303 2304 2305 2306If a CRTM Event sequence is active, extend the PCR designated by the platform-specific 2307specification. 2308 2309On TPM Resume 2310 2311 2312the H-CRTM startup method is the same for this TPM2_Startup() as for the previous TPM2_Startup(); 2313(TPM_RC_LOCALITY) 2314 2315 2316 2317TPMS_CLOCK_INFO.restartCount shall be incremented; and 2318 2319 2320 2321PCR that are specified in a platform-specific specification to be preserved on TPM Resume are 2322restored to their saved state and other PCR are set to their initial value as determined by a platformspecific specification. 2323 2324Other TPM state may change as required to meet the needs of the implementation. 2325If the startupType is TPM_SU_STATE and the TPM requires TPM_SU_CLEAR, then the TPM shall return 2326TPM_RC_VALUE. 2327NOTE 6 2328 2329The TPM will require 2330Shutdown(CLEAR). 2331 2332NOTE 7 2333 2334If startupType is neither TPM_SU_STATE nor TPM_SU_CLEAR, then the unmarshaling code returns 2335TPM_RC_VALUE. 2336 2337Page 20 2338October 31, 2013 2339 2340TPM_SU_CLEAR 2341 2342when 2343 2344no 2345 2346Published 2347Copyright © TCG 2006-2013 2348 2349shutdown 2350 2351was 2352 2353performed 2354 2355or 2356 2357after 2358 2359Family “2.0” 2360Level 00 Revision 00.99 2361 2362 Trusted Platform Module Library 2363 2364Part 3: Commands 2365 236611.3.2 Command and Response 2367Table 5 — TPM2_Startup Command 2368Type 2369 2370Name 2371 2372Description 2373 2374TPMI_ST_COMMAND_TAG 2375 2376tag 2377 2378TPM_ST_NO_SESSIONS 2379 2380UINT32 2381 2382commandSize 2383 2384TPM_CC 2385 2386commandCode 2387 2388TPM_CC_Startup {NV} 2389 2390TPM_SU 2391 2392startupType 2393 2394TPM_SU_CLEAR or TPM_SU_STATE 2395 2396Table 6 — TPM2_Startup Response 2397Type 2398 2399Name 2400 2401Description 2402 2403TPM_ST 2404 2405tag 2406 2407see clause 8 2408 2409UINT32 2410 2411responseSize 2412 2413TPM_RC 2414 2415responseCode 2416 2417Family “2.0” 2418Level 00 Revision 00.99 2419 2420Published 2421Copyright © TCG 2006-2013 2422 2423Page 21 2424October 31, 2013 2425 2426 Part 3: Commands 2427 2428Trusted Platform Module Library 2429 243011.3.3 Detailed Actions 24311 24322 2433 2434#include "InternalRoutines.h" 2435#include "Startup_fp.h" 2436Error Returns 2437TPM_RC_VALUE 2438 24393 24404 24415 24426 24437 24448 24459 244610 244711 244812 244913 245014 245115 245216 245317 245418 245519 245620 245721 245822 245923 246024 246125 246226 246327 246428 246529 246630 246731 246832 246933 247034 247135 247236 247337 247438 247539 247640 247741 247842 247943 248044 248145 248246 248347 248448 248549 248650 248751 248852 248953 249054 2491 2492Meaning 2493start up type is not compatible with previous shutdown sequence 2494 2495TPM_RC 2496TPM2_Startup( 2497Startup_In 2498 2499*in 2500 2501// IN: input parameter list 2502 2503) 2504{ 2505STARTUP_TYPE 2506TPM_RC 2507BOOL 2508 2509startup; 2510result; 2511prevDrtmPreStartup; 2512 2513// The command needs NV update. Check if NV is available. 2514// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 2515// this point 2516result = NvIsAvailable(); 2517if(result != TPM_RC_SUCCESS) 2518return result; 2519// Input Validation 2520// Read orderly shutdown states from previous power cycle 2521NvReadReserved(NV_ORDERLY, &g_prevOrderlyState); 2522// HACK to extract the DRTM startup type associated with the previous shutdown 2523prevDrtmPreStartup = (g_prevOrderlyState == (TPM_SU_STATE + 0x8000)); 2524if(prevDrtmPreStartup) 2525g_prevOrderlyState = TPM_SU_STATE; 2526// if the previous power cycle was shut down with no StateSave command, or 2527// with StateSave command for CLEAR, this cycle can not startup up with 2528// STATE 2529if( 2530( 2531g_prevOrderlyState == SHUTDOWN_NONE 2532|| g_prevOrderlyState == TPM_SU_CLEAR 2533) 2534&& in->startupType == TPM_SU_STATE 2535) 2536return TPM_RC_VALUE + RC_Startup_startupType; 2537// Internal Date Update 2538// Translate the TPM2_ShutDown and TPM2_Startup sequence into the startup 2539// types. 2540if(in->startupType == TPM_SU_CLEAR && g_prevOrderlyState == TPM_SU_STATE) 2541{ 2542startup = SU_RESTART; 2543// Read state reset data 2544NvReadReserved(NV_STATE_RESET, &gr); 2545} 2546else if(in->startupType == TPM_SU_STATE && g_prevOrderlyState == TPM_SU_STATE) 2547{ 2548// For a resume, the H-CRTM startup method must be the same 2549if(g_DrtmPreStartup != prevDrtmPreStartup) 2550return TPM_RC_LOCALITY; 2551 2552Page 22 2553October 31, 2013 2554 2555Published 2556Copyright © TCG 2006-2013 2557 2558Family “2.0” 2559Level 00 Revision 00.99 2560 2561 Trusted Platform Module Library 256255 256356 256457 256558 256659 256760 256861 256962 257063 257164 257265 257366 257467 257568 257669 257770 257871 257972 258073 258174 258275 258376 258477 258578 258679 258780 258881 258982 259083 259184 259285 259386 259487 259588 259689 259790 259891 259992 260093 260194 260295 260396 260497 260598 260699 2607100 2608101 2609102 2610103 2611104 2612105 2613106 2614107 2615108 2616109 2617110 2618111 2619112 2620113 2621114 2622115 2623116 2624 2625Part 3: Commands 2626 2627// Read state clear and state reset data 2628NvReadReserved(NV_STATE_CLEAR, &gc); 2629NvReadReserved(NV_STATE_RESET, &gr); 2630startup = SU_RESUME; 2631} 2632else 2633{ 2634startup = SU_RESET; 2635} 2636// Read persistent data from NV 2637NvReadPersistent(); 2638// Crypto Startup 2639CryptUtilStartup(startup); 2640// Start up subsystems 2641// Start counters and timers 2642TimeStartup(startup); 2643// Start dictionary attack subsystem 2644DAStartup(startup); 2645// Enable hierarchies 2646HierarchyStartup(startup); 2647// Restore/Initialize PCR 2648PCRStartup(startup); 2649// Restore/Initialize command audit information 2650CommandAuditStartup(startup); 2651// Object context variables 2652if(startup == SU_RESET) 2653{ 2654// Reset object context ID to 0 2655gr.objectContextID = 0; 2656// Reset clearCount to 0 2657gr.clearCount= 0; 2658} 2659// Initialize object table 2660ObjectStartup(); 2661// Initialize session table 2662SessionStartup(startup); 2663// Initialize index/evict data. 2664// in NV index 2665NvEntityStartup(startup); 2666 2667This function clear read/write locks 2668 2669// Initialize the orderly shut down flag for this cycle to SHUTDOWN_NONE. 2670gp.orderlyState = SHUTDOWN_NONE; 2671NvWriteReserved(NV_ORDERLY, &gp.orderlyState); 2672// Update TPM internal states if command succeeded. 2673// Record a TPM2_Startup command has been received. 2674TPMRegisterStartup(); 2675return TPM_RC_SUCCESS; 2676} 2677 2678Family “2.0” 2679Level 00 Revision 00.99 2680 2681Published 2682Copyright © TCG 2006-2013 2683 2684Page 23 2685October 31, 2013 2686 2687 Part 3: Commands 2688 268911.4 2690 2691Trusted Platform Module Library 2692 2693TPM2_Shutdown 2694 269511.4.1 General Description 2696This command is used to prepare the TPM for a power cycle. The shutdownType parameter indicates 2697how the subsequent TPM2_Startup() will be processed. 2698For a shutdownType of any type, the volatile portion of Clock is saved to NV memory and the orderly 2699shutdown indication is SET. NV with the TPMA_NV_ORDERY attribute will be updated. 2700For a shutdownType of TPM_SU_STATE, the following additional items are saved: 2701 2702 2703tracking information for saved session contexts; 2704 2705 2706 2707the session context counter; 2708 2709 2710 2711PCR that are designated as being preserved by TPM2_Shutdown(TPM_SU_STATE); 2712 2713 2714 2715the PCR Update Counter; 2716 2717 2718 2719flags associated with supporting the TPMA_NV_WRITESTCLEAR and TPMA_NV_READSTCLEAR 2720attributes; and 2721 2722 2723 2724the command audit digest and count. 2725 2726The following items shall not be saved and will not be in TPM memory after the next TPM2_Startup: 2727 2728 2729TPM-memory-resident session contexts; 2730 2731 2732 2733TPM-memory-resident transient objects; or 2734 2735 2736 2737TPM-memory-resident hash contexts created by TPM2_HashSequenceStart(). 2738 2739Some values may be either derived from other values or saved to NV memory. 2740This command saves TPM state but does not change the state other than the internal indication that the 2741context has been saved. The TPM shall continue to accept commands. If a subsequent command 2742changes TPM state saved by this command, then the effect of this command is nullified. The TPM MAY 2743nullify this command for any subsequent command rather than check whether the command changed 2744state saved by this command. If this command is nullified. and if no TPM2_Shutdown() occurs before the 2745next TPM2_Startup(), then the next TPM2_Startup() shall be TPM2_Startup(CLEAR). 2746 2747Page 24 2748October 31, 2013 2749 2750Published 2751Copyright © TCG 2006-2013 2752 2753Family “2.0” 2754Level 00 Revision 00.99 2755 2756 Trusted Platform Module Library 2757 2758Part 3: Commands 2759 276011.4.2 Command and Response 2761Table 7 — TPM2_Shutdown Command 2762Type 2763 2764Name 2765 2766Description 2767 2768TPMI_ST_COMMAND_TAG 2769 2770tag 2771 2772UINT32 2773 2774commandSize 2775 2776TPM_CC 2777 2778commandCode 2779 2780TPM_CC_Shutdown {NV} 2781 2782TPM_SU 2783 2784shutdownType 2785 2786TPM_SU_CLEAR or TPM_SU_STATE 2787 2788Table 8 — TPM2_Shutdown Response 2789Type 2790 2791Name 2792 2793Description 2794 2795TPM_ST 2796 2797tag 2798 2799see clause 8 2800 2801UINT32 2802 2803responseSize 2804 2805TPM_RC 2806 2807responseCode 2808 2809Family “2.0” 2810Level 00 Revision 00.99 2811 2812Published 2813Copyright © TCG 2006-2013 2814 2815Page 25 2816October 31, 2013 2817 2818 Part 3: Commands 2819 2820Trusted Platform Module Library 2821 282211.4.3 Detailed Actions 28231 28242 2825 2826#include "InternalRoutines.h" 2827#include "Shutdown_fp.h" 2828Error Returns 2829TPM_RC_TYPE 2830 28313 28324 28335 28346 28357 28368 28379 283810 283911 284012 284113 284214 284315 284416 284517 284618 284719 284820 284921 285022 285123 285224 285325 285426 285527 285628 285729 285830 285931 286032 286133 286234 286335 286436 286537 286638 286739 286840 286941 287042 287143 287244 287345 287446 287547 287648 287749 287850 287951 288052 288153 2882 2883Meaning 2884if PCR bank has been re-configured, a CLEAR StateSave() is 2885required 2886 2887TPM_RC 2888TPM2_Shutdown( 2889Shutdown_In 2890 2891*in 2892 2893// IN: input parameter list 2894 2895) 2896{ 2897TPM_RC 2898 2899result; 2900 2901// The command needs NV update. Check if NV is available. 2902// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 2903// this point 2904result = NvIsAvailable(); 2905if(result != TPM_RC_SUCCESS) return result; 2906// Input Validation 2907// If PCR bank has been reconfigured, a CLEAR state save is required 2908if(g_pcrReConfig && in->shutdownType == TPM_SU_STATE) 2909return TPM_RC_TYPE + RC_Shutdown_shutdownType; 2910// Internal Data Update 2911// PCR private date state save 2912PCRStateSave(in->shutdownType); 2913// Get DRBG state 2914CryptDrbgGetPutState(GET_STATE); 2915// Save all orderly data 2916NvWriteReserved(NV_ORDERLY_DATA, &go); 2917// Save RAM backed NV index data 2918NvStateSave(); 2919if(in->shutdownType == TPM_SU_STATE) 2920{ 2921// Save STATE_RESET and STATE_CLEAR data 2922NvWriteReserved(NV_STATE_CLEAR, &gc); 2923NvWriteReserved(NV_STATE_RESET, &gr); 2924} 2925else if(in->shutdownType == TPM_SU_CLEAR) 2926{ 2927// Save STATE_RESET data 2928NvWriteReserved(NV_STATE_RESET, &gr); 2929} 2930// Write orderly shut down state 2931if(in->shutdownType == TPM_SU_CLEAR) 2932gp.orderlyState = TPM_SU_CLEAR; 2933else if(in->shutdownType == TPM_SU_STATE) 2934gp.orderlyState = TPM_SU_STATE; 2935else 2936 2937Page 26 2938October 31, 2013 2939 2940Published 2941Copyright © TCG 2006-2013 2942 2943Family “2.0” 2944Level 00 Revision 00.99 2945 2946 Trusted Platform Module Library 294754 294855 294956 295057 295158 295259 2953 2954Part 3: Commands 2955 2956pAssert(FALSE); 2957NvWriteReserved(NV_ORDERLY, &gp.orderlyState); 2958return TPM_RC_SUCCESS; 2959} 2960 2961Family “2.0” 2962Level 00 Revision 00.99 2963 2964Published 2965Copyright © TCG 2006-2013 2966 2967Page 27 2968October 31, 2013 2969 2970 Part 3: Commands 2971 297212 297312.1 2974 2975Trusted Platform Module Library 2976 2977Testing 2978Introduction 2979 2980Compliance to standards for hardware security modules may require that the TPM test its functions 2981before the results that depend on those functions may be returned. The TPM may perform operations 2982using testable functions before those functions have been tested as long as the TPM returns no value 2983that depends on the correctness of the testable function. 2984EXAMPLE 2985 2986TPM2_PCR_Event() may be executed before the hash algorithms have been tested. However, until 2987the hash algorithms have been tested, the contents of a PCR may not be used in any command if 2988that command may result in a value being returned to the TPM user. This means tha t 2989TPM2_PCR_Read() or TPM2_PolicyPCR() could not complete until the hashes have been checked 2990but other TPM2_PCR_Event() commands may be executed even though the operation uses previous 2991PCR values. 2992 2993If a command is received that requires return of a value that depends on untested functions, the TPM 2994shall test the required functions before completing the command. 2995Once the TPM has received TPM2_SelfTest() and before completion of all tests, the TPM is required to 2996return TPM_RC_TESTING for any command that uses a function that requires a test. 2997If a self-test fails at any time, the TPM will enter Failure mode. While in Failure mode, the TPM will return 2998TPM_RC_FAILURE for any command other than TPM2_GetTestResult() and TPM2_GetCapability(). The 2999TPM will remain in Failure mode until the next _TPM_Init. 3000 3001Page 28 3002October 31, 2013 3003 3004Published 3005Copyright © TCG 2006-2013 3006 3007Family “2.0” 3008Level 00 Revision 00.99 3009 3010 Trusted Platform Module Library 3011 301212.2 3013 3014Part 3: Commands 3015 3016TPM2_SelfTest 3017 301812.2.1 General Description 3019This command causes the TPM to perform a test of its capabilities. If the fullTest is YES, the TPM will test 3020all functions. If fullTest = NO, the TPM will only test those functions that have not previously been tested. 3021If any tests are required, the TPM shall either 3022a) return TPM_RC_TESTING and begin self-test of the required functions, or 3023NOTE 1 3024 3025If fullTest is NO, and all functions have been tested, the TPM shall return TPM_RC_SUCCESS. 3026 3027b) perform the tests and return the test result when complete. 3028If the TPM uses option a), the TPM shall return TPM_RC_TESTING for any command that requires use 3029of a testable function, even if the functions required for completion of the command have already been 3030tested. 3031NOTE 2 3032 3033This command may cause the TPM to continue processing after it has returned the response. So 3034that software can be notified of the completion of the testing, the interface may include controls that 3035would allow the TPM to generate an interrupt when the “background” processing is complete. This 3036would be in addition to the interrupt may be available for signaling normal command completion. It is 3037not necessary that there be two interrupts, but the interface should provide a way to indicate the 3038nature of the interrupt (normal command or deferred command). 3039 3040Family “2.0” 3041Level 00 Revision 00.99 3042 3043Published 3044Copyright © TCG 2006-2013 3045 3046Page 29 3047October 31, 2013 3048 3049 Part 3: Commands 3050 3051Trusted Platform Module Library 3052 305312.2.2 Command and Response 3054Table 9 — TPM2_SelfTest Command 3055Type 3056 3057Name 3058 3059Description 3060 3061TPMI_ST_COMMAND_TAG 3062 3063tag 3064 3065UINT32 3066 3067commandSize 3068 3069TPM_CC 3070 3071commandCode 3072 3073TPM_CC_SelfTest {NV} 3074 3075TPMI_YES_NO 3076 3077fullTest 3078 3079YES if full test to be performed 3080NO if only test of untested functions required 3081 3082Table 10 — TPM2_SelfTest Response 3083Type 3084 3085Name 3086 3087Description 3088 3089TPM_ST 3090 3091tag 3092 3093see clause 8 3094 3095UINT32 3096 3097responseSize 3098 3099TPM_RC 3100 3101responseCode 3102 3103Page 30 3104October 31, 2013 3105 3106Published 3107Copyright © TCG 2006-2013 3108 3109Family “2.0” 3110Level 00 Revision 00.99 3111 3112 Trusted Platform Module Library 3113 3114Part 3: Commands 3115 311612.2.3 Detailed Actions 31171 31182 3119 3120#include "InternalRoutines.h" 3121#include "SelfTest_fp.h" 3122Error Returns 3123TPM_RC_TESTING 3124 31253 31264 31275 31286 31297 31308 31319 313210 313311 313412 3135 3136Meaning 3137self test in process 3138 3139TPM_RC 3140TPM2_SelfTest( 3141SelfTest_In 3142) 3143{ 3144// Command Output 3145 3146*in 3147 3148// IN: input parameter list 3149 3150// Call self test function in crypt module 3151return CryptSelfTest(in->fullTest); 3152} 3153 3154Family “2.0” 3155Level 00 Revision 00.99 3156 3157Published 3158Copyright © TCG 2006-2013 3159 3160Page 31 3161October 31, 2013 3162 3163 Part 3: Commands 3164 316512.3 3166 3167Trusted Platform Module Library 3168 3169TPM2_IncrementalSelfTest 3170 317112.3.1 General Description 3172This command causes the TPM to perform a test of the selected algorithms. 3173NOTE 1 3174 3175The toTest list indicates the algorithms that software would like the TPM to test in anticipation of 3176future use. This allows tests to be done so that a future commands will not be delayed due to 3177testing. 3178 3179If toTest contains an algorithm that has already been tested, it will not be tested again. 3180NOTE 2 3181 3182The only way to force retesting of an algorithm is with TPM2_SelfTest( fullTest = YES). 3183 3184The TPM will return in toDoList a list of algorithms that are yet to be tested. This list is not the list of 3185algorithms that are scheduled to be tested but the algorithms/functions that have not been tested. Only 3186the algorithms on the toTest list are scheduled to be tested by this command. 3187Making toTest an empty list allows the determination of the algorithms that remain untested without 3188triggering any testing. 3189If toTest is not an empty list, the TPM shall return TPM_RC_SUCCESS for this command and then return 3190TPM_RC_TESTING for any subsequent command (including TPM2_IncrementalSelfTest()) until the 3191requested testing is complete. 3192NOTE 3 3193 3194If toDoList is empty, then no additional tests are required and TPM_RC_TESTING will not be 3195returned in subsequent commands and no additional delay will occur in a command due to testing. 3196 3197NOTE 4 3198 3199If none of the algorithms listed in toTest is in the toDoList, then no tests will be performed. 3200 3201If all the parameters in this command are valid, the TPM returns TPM_RC_SUCCESS and the toDoList 3202(which may be empty). 3203NOTE 5 3204 3205An implementation may perform all requested tests before returning TPM_RC_SUCCESS, or it may 3206return TPM_RC_SUCCESS for this command and then return TPM_RC_TESTING for all 3207subsequence commands (including TPM2_IncrementatSelfTest()) until the requested tests are 3208complete. 3209 3210Page 32 3211October 31, 2013 3212 3213Published 3214Copyright © TCG 2006-2013 3215 3216Family “2.0” 3217Level 00 Revision 00.99 3218 3219 Trusted Platform Module Library 3220 3221Part 3: Commands 3222 322312.3.2 Command and Response 3224Table 11 — TPM2_IncrementalSelfTest Command 3225Type 3226 3227Name 3228 3229Description 3230 3231TPMI_ST_COMMAND_TAG 3232 3233tag 3234 3235UINT32 3236 3237commandSize 3238 3239TPM_CC 3240 3241commandCode 3242 3243TPM_CC_IncrementalSelfTest {NV} 3244 3245TPML_ALG 3246 3247toTest 3248 3249list of algorithms that should be tested 3250 3251Table 12 — TPM2_IncrementalSelfTest Response 3252Type 3253 3254Name 3255 3256Description 3257 3258TPM_ST 3259 3260tag 3261 3262see clause 8 3263 3264UINT32 3265 3266responseSize 3267 3268TPM_RC 3269 3270responseCode 3271 3272TPML_ALG 3273 3274toDoList 3275 3276Family “2.0” 3277Level 00 Revision 00.99 3278 3279list of algorithms that need testing 3280 3281Published 3282Copyright © TCG 2006-2013 3283 3284Page 33 3285October 31, 2013 3286 3287 Part 3: Commands 3288 3289Trusted Platform Module Library 3290 329112.3.3 Detailed Actions 32921 32932 32943 32954 32965 32976 32987 32998 33009 330110 330211 330312 330413 3305 3306#include "InternalRoutines.h" 3307#include "IncrementalSelfTest_fp.h" 3308 3309TPM_RC 3310TPM2_IncrementalSelfTest( 3311IncrementalSelfTest_In 3312IncrementalSelfTest_Out 3313 3314*in, 3315*out 3316 3317// IN: input parameter list 3318// OUT: output parameter list 3319 3320) 3321{ 3322// Command Output 3323// Call incremental self test function in crypt module 3324return CryptIncrementalSelfTest(&in->toTest, &out->toDoList); 3325} 3326 3327Page 34 3328October 31, 2013 3329 3330Published 3331Copyright © TCG 2006-2013 3332 3333Family “2.0” 3334Level 00 Revision 00.99 3335 3336 Trusted Platform Module Library 3337 333812.4 3339 3340Part 3: Commands 3341 3342TPM2_GetTestResult 3343 334412.4.1 General Description 3345This command returns manufacturer-specific information regarding the results of a self-test and an 3346indication of the test status. 3347If TPM2_SelfTest() has not been executed and a testable function has not been tested, testResult will be 3348TPM_RC_NEEDS_TEST. If TPM2_SelfTest() has been received and the tests are not complete, 3349testResult will be TPM_RC_TESTING. If testing of all functions is complete without functional failures, 3350testResult will be TPM_RC_SUCCESS. If any test failed, testResult will be TPM_RC_FAILURE. If the 3351TPM is in Failure mode because of an invalid startupType in TPM2_Startup(), testResult will be 3352TPM_RC_INITIALIZE. 3353This command will operate when the TPM is in Failure mode so that software can determine the test 3354status of the TPM and so that diagnostic information can be obtained for use in failure analysis. If the 3355TPM is in Failure mode, then tag is required to be TPM_ST_NO_SESSIONS or the TPM shall return 3356TPM_RC_FAILURE. 3357 3358Family “2.0” 3359Level 00 Revision 00.99 3360 3361Published 3362Copyright © TCG 2006-2013 3363 3364Page 35 3365October 31, 2013 3366 3367 Part 3: Commands 3368 3369Trusted Platform Module Library 3370 337112.4.2 Command and Response 3372Table 13 — TPM2_GetTestResult Command 3373Type 3374 3375Name 3376 3377Description 3378 3379TPMI_ST_COMMAND_TAG 3380 3381tag 3382 3383UINT32 3384 3385commandSize 3386 3387TPM_CC 3388 3389commandCode 3390 3391TPM_CC_GetTestResult 3392 3393Table 14 — TPM2_GetTestResult Response 3394Type 3395 3396Name 3397 3398Description 3399 3400TPMI_ST_COMMAND_TAG 3401 3402tag 3403 3404see clause 8 3405 3406UINT32 3407 3408responseSize 3409 3410TPM_RC 3411 3412responseCode 3413 3414TPM2B_MAX_BUFFER 3415 3416outData 3417 3418TPM_RC 3419 3420testResult 3421 3422Page 36 3423October 31, 2013 3424 3425test result data 3426contains manufacturer-specific information 3427 3428Published 3429Copyright © TCG 2006-2013 3430 3431Family “2.0” 3432Level 00 Revision 00.99 3433 3434 Trusted Platform Module Library 3435 3436Part 3: Commands 3437 343812.4.3 Detailed Actions 34391 34402 34413 34424 34435 34446 34457 34468 34479 344810 344911 345012 345113 345214 3453 3454#include "InternalRoutines.h" 3455#include "GetTestResult_fp.h" 3456 3457TPM_RC 3458TPM2_GetTestResult( 3459GetTestResult_Out 3460) 3461{ 3462// Command Output 3463 3464*out 3465 3466// OUT: output parameter list 3467 3468// Call incremental self test function in crypt module 3469out->testResult = CryptGetTestResult(&out->outData); 3470return TPM_RC_SUCCESS; 3471} 3472 3473Family “2.0” 3474Level 00 Revision 00.99 3475 3476Published 3477Copyright © TCG 2006-2013 3478 3479Page 37 3480October 31, 2013 3481 3482 Part 3: Commands 3483 3484Trusted Platform Module Library 3485 3486Session Commands 3487 348813 348913.1 3490 3491TPM2_StartAuthSession 3492 349313.1.1 General Description 3494This command is used to start an authorization session using alternative methods of establishing the 3495session key (sessionKey). The session key is then used to derive values used for authorization and for 3496encrypting parameters. 3497This command allows injection of a secret into the TPM using either asymmetric or symmetric encryption. 3498The type of tpmKey determines how the value in encryptedSalt is encrypted. The decrypted secret value 3499is used to compute the sessionKey. 3500NOTE 1 3501 3502If tpmKey Is TPM_RH_NULL, then encryptedSalt is required to be an Empty Buffer. 3503 3504The label value of “SECRET” (see “Terms and Definitions” in Part 1 of this specification) is used in the 3505recovery of the secret value. 3506The TPM generates the sessionKey from the recovered secret value. 3507No authorization is required for tpmKey or bind. 3508NOTE 2 3509 3510The justification for using tpmKey without providing authorization is that the result o f using the key is 3511not available to the caller, except indirectly through the sessionKey. This does not represent a point 3512of attack on the value of the key. If the caller attempts to use the session without knowing the 3513sessionKey value, it is an authorization failure that will trigger the dictionary attack logic. 3514 3515The entity referenced with the bind parameter contributes an authorization value to the sessionKey 3516generation process. 3517If both tpmKey and bind are TPM_ALG_NULL, then sessionKey is set to the Empty Buffer. If tpmKey is 3518not TPM_ALG_NULL, then encryptedSalt is used in the computation of sessionKey. If bind is not 3519TPM_ALG_NULL, the authValue of bind is used in the sessionKey computation. 3520If symmetric specifies a block cipher, then TPM_ALG_CFB is the only allowed value for the mode field in 3521the symmetric parameter (TPM_RC_MODE). 3522This command starts an authorization session and returns the session handle along with an initial 3523nonceTPM in the response. 3524If the TPM does not have 3525TPM_RC_SESSION_HANDLES. 3526 3527a 3528 3529free 3530 3531slot 3532 3533for 3534 3535an 3536 3537authorization 3538 3539session, 3540 3541it 3542 3543shall 3544 3545return 3546 3547If the TPM implements a “gap” scheme for assigning contextID values, then the TPM shall return 3548TPM_RC_CONTEXT_GAP if creating the session would prevent recycling of old saved contexts (See 3549“Context Management” in Part 1). 3550If tpmKey is not TPM_ALG_NULL then encryptedSalt shall be a TPM2B_ENCRYPTED_SECRET of the 3551proper type for tpmKey. The TPM shall return TPM_RC_VALUE if: 3552a) tpmKey references an RSA key and 35531) encryptedSalt does not contain a value that is the size of the public modulus of tpmKey, 35542) encryptedSalt has a value that is greater than the public modulus of tpmKey, 35553) encryptedSalt is not a properly encode OAEP value, or 35564) the decrypted salt value is larger than the size of the digest produced by the nameAlg of tpmKey; 3557or 3558 3559Page 38 3560October 31, 2013 3561 3562Published 3563Copyright © TCG 2006-2013 3564 3565Family “2.0” 3566Level 00 Revision 00.99 3567 3568 Trusted Platform Module Library 3569 3570Part 3: Commands 3571 3572b) tpmKey references an ECC key and encryptedSalt 35731) does not contain a TPMS_ECC_POINT or 35742) is not a point on the curve of tpmKey; 3575NOTE 3 3576 3577When ECC is used, the point multiply process produces a value (Z) that is used in a KDF to 3578produce the final secret value. The size of the secret value is an input parameter to the KDF 3579and the result will be set to be the size of the digest produced by the nameAlg of tpmKey. 3580 3581c) tpmKey references a symmetric block cipher or a keyedHash object and encryptedSalt contains a 3582value that is larger than the size of the digest produced by the nameAlg of tpmKey. 3583For all session types, this command will cause initialization of the sessionKey and may establish binding 3584between the session and an object (the bind object). If sessionType is TPM_SE_POLICY or 3585TPM_SE_TRIAL, the additional session initialization is: 3586 3587 3588set policySession→policyDigest to a Zero Digest (the digest size for policySession→policyDigest is 3589the size of the digest produced by authHash); 3590 3591 3592 3593authorization may be given at any locality; 3594 3595 3596 3597authorization may apply to any command code; 3598 3599 3600 3601authorization may apply to any command parameters or handles; 3602 3603 3604 3605the authorization has no time limit; 3606 3607 3608 3609an authValue is not needed when the authorization is used; 3610 3611 3612 3613the session is not bound; 3614 3615 3616 3617the session is not an audit session; and 3618 3619 3620 3621the time at which the policy session was created is recorded. 3622 3623Additionally, if sessionType is TPM_SE_TRIAL, the session will not be usable for authorization but can be 3624used to compute the authPolicy for an object. 3625NOTE 4 3626 3627Although this command changes the session allocation information in the TPM, it does not invalidate 3628a saved context. That is, TPM2_Shutdown() is not required after this comm and in order to reestablish the orderly state of the TPM. This is because the created context will occupy an available 3629slot in the TPM and sessions in the TPM do not survive any TPM2_Startup(). However, if a created 3630session is context saved, the orderly state does change. 3631 3632The TPM shall return TPM_RC_SIZE if nonceCaller is less than 16 octets or is greater than the size of 3633the digest produced by authHash. 3634 3635Family “2.0” 3636Level 00 Revision 00.99 3637 3638Published 3639Copyright © TCG 2006-2013 3640 3641Page 39 3642October 31, 2013 3643 3644 Part 3: Commands 3645 3646Trusted Platform Module Library 3647 364813.1.2 Command and Response 3649Table 15 — TPM2_StartAuthSession Command 3650Type 3651 3652Name 3653 3654TPMI_ST_COMMAND_TAG 3655 3656tag 3657 3658UINT32 3659 3660commandSize 3661 3662TPM_CC 3663 3664commandCode 3665 3666TPM_CC_StartAuthSession 3667 3668TPMI_DH_OBJECT+ 3669 3670tpmKey 3671 3672handle of a loaded decrypt key used to encrypt salt 3673may be TPM_RH_NULL 3674Auth Index: None 3675 3676TPMI_DH_ENTITY+ 3677 3678bind 3679 3680entity providing the authValue 3681may be TPM_RH_NULL 3682Auth Index: None 3683 3684TPM2B_NONCE 3685 3686nonceCaller 3687 3688Description 3689 3690initial nonceCaller, sets nonce size for the session 3691shall be at least 16 octets 3692 3693TPM2B_ENCRYPTED_SECRET 3694 3695encryptedSalt 3696 3697value encrypted according to the type of tpmKey 3698If tpmKey is TPM_RH_NULL, this shall be the Empty 3699Buffer. 3700 3701TPM_SE 3702 3703sessionType 3704 3705indicates the type of the session; simple HMAC or policy 3706(including a trial policy) 3707 3708TPMT_SYM_DEF+ 3709 3710symmetric 3711 3712the algorithm and key size for parameter encryption 3713may select TPM_ALG_NULL 3714 3715TPMI_ALG_HASH 3716 3717authHash 3718 3719hash algorithm to use for the session 3720Shall be a hash algorithm supported by the TPM and 3721not TPM_ALG_NULL 3722 3723Table 16 — TPM2_StartAuthSession Response 3724Type 3725 3726Name 3727 3728Description 3729 3730TPM_ST 3731 3732tag 3733 3734see clause 8 3735 3736UINT32 3737 3738responseSize 3739 3740TPM_RC 3741 3742responseCode 3743 3744TPMI_SH_AUTH_SESSION 3745 3746sessionHandle 3747 3748handle for the newly created session 3749 3750TPM2B_NONCE 3751 3752nonceTPM 3753 3754the initial nonce from the TPM, used in the computation 3755of the sessionKey 3756 3757Page 40 3758October 31, 2013 3759 3760Published 3761Copyright © TCG 2006-2013 3762 3763Family “2.0” 3764Level 00 Revision 00.99 3765 3766 Trusted Platform Module Library 3767 3768Part 3: Commands 3769 377013.1.3 Detailed Actions 37711 37722 3773 3774#include "InternalRoutines.h" 3775#include "StartAuthSession_fp.h" 3776Error Returns 3777TPM_RC_ATTRIBUTES 3778 3779tpmKey does not reference a decrypt key 3780 3781TPM_RC_CONTEXT_GAP 3782 3783the difference between the most recently created active context and 3784the oldest active context is at the limits of the TPM 3785 3786TPM_RC_HANDLE 3787 3788input decrypt key handle only has public portion loaded 3789 3790TPM_RC_MODE 3791 3792symmetric specifies a block cipher but the mode is not 3793TPM_ALG_CFB. 3794 3795TPM_RC_SESSION_HANDLES 3796 3797no session handle is available 3798 3799TPM_RC_SESSION_MEMORY 3800 3801no more slots for loading a session 3802 3803TPM_RC_SIZE 3804 3805nonce less than 16 octets or greater than the size of the digest 3806produced by authHash 3807 3808TPM_RC_VALUE 3809 38103 38114 38125 38136 38147 38158 38169 381710 381811 381912 382013 382114 382215 382316 382417 382518 382619 382720 382821 382922 383023 383124 383225 383326 383427 383528 383629 383730 383831 383932 384033 384134 384235 384336 3844 3845Meaning 3846 3847secret size does not match decrypt key type; or the recovered secret 3848is larget than the digest size of the nameAlg of tpmKey; or, for an 3849RSA decrypt key, if encryptedSecret is greater than the public 3850exponent of tpmKey. 3851 3852TPM_RC 3853TPM2_StartAuthSession( 3854StartAuthSession_In 3855StartAuthSession_Out 3856 3857*in, 3858*out 3859 3860// IN: input parameter buffer 3861// OUT: output parameter buffer 3862 3863TPM_RC 3864OBJECT 3865SESSION 3866TPM2B_DATA 3867 3868result = TPM_RC_SUCCESS; 3869*tpmKey; 3870// TPM key for decrypt salt 3871*session; 3872// session internal data 3873salt; 3874 3875) 3876{ 3877 3878// Input Validation 3879// Check input nonce size. IT should be at least 16 bytes but not larger 3880// than the digest size of session hash. 3881if( 3882in->nonceCaller.t.size < 16 3883|| in->nonceCaller.t.size > CryptGetHashDigestSize(in->authHash)) 3884return TPM_RC_SIZE + RC_StartAuthSession_nonceCaller; 3885// If an decrypt key is passed in, check its validation 3886if(in->tpmKey != TPM_RH_NULL) 3887{ 3888// secret size cannot be 0 3889if(in->encryptedSalt.t.size == 0) 3890return TPM_RC_VALUE + RC_StartAuthSession_encryptedSalt; 3891// Get pointer to loaded decrypt key 3892tpmKey = ObjectGet(in->tpmKey); 3893// Decrypting salt requires accessing the private portion of a key. 3894// Therefore, tmpKey can not be a key with only public portion loaded 3895if(tpmKey->attributes.publicOnly) 3896return TPM_RC_HANDLE + RC_StartAuthSession_tpmKey; 3897 3898Family “2.0” 3899Level 00 Revision 00.99 3900 3901Published 3902Copyright © TCG 2006-2013 3903 3904Page 41 3905October 31, 2013 3906 3907 Part 3: Commands 390837 390938 391039 391140 391241 391342 391443 391544 391645 391746 391847 391948 392049 392150 392251 392352 392453 392554 392655 392756 392857 392958 393059 393160 393261 393362 393463 393564 393665 393766 393867 393968 394069 394170 394271 394372 394473 394574 394675 394776 394877 394978 395079 395180 395281 395382 395483 395584 395685 395786 395887 395988 396089 396190 3962 3963Trusted Platform Module Library 3964 3965// HMAC session input handle check. 3966// tpmKey should be a decryption key 3967if(tpmKey->publicArea.objectAttributes.decrypt != SET) 3968return TPM_RC_ATTRIBUTES + RC_StartAuthSession_tpmKey; 3969// Secret Decryption. A TPM_RC_VALUE, TPM_RC_KEY or Unmarshal errors 3970// may be returned at this point 3971result = CryptSecretDecrypt(in->tpmKey, &in->nonceCaller, "SECRET", 3972&in->encryptedSalt, &salt); 3973if(result != TPM_RC_SUCCESS) 3974return TPM_RC_VALUE + RC_StartAuthSession_encryptedSalt; 3975} 3976else 3977{ 3978// secret size must be 0 3979if(in->encryptedSalt.t.size != 0) 3980return TPM_RC_VALUE + RC_StartAuthSession_encryptedSalt; 3981salt.t.size = 0; 3982} 3983// If 'symmetric' is a symmetric block cipher (not TPM_ALG_NULL or TPM_ALG_XOR) 3984// then the mode must be CFB. 3985if( 3986in->symmetric.algorithm != TPM_ALG_NULL 3987&& in->symmetric.algorithm != TPM_ALG_XOR 3988&& in->symmetric.mode.sym != TPM_ALG_CFB) 3989return TPM_RC_MODE + RC_StartAuthSession_symmetric; 3990// Internal Data Update 3991// Create internal session structure. TPM_RC_CONTEXT_GAP, TPM_RC_NO_HANDLES 3992// or TPM_RC_SESSION_MEMORY errors may be returned returned at this point. 3993// 3994// The detailed actions for creating the session context are not shown here 3995// as the details are implementation dependent 3996// SessionCreate sets the output handle 3997result = SessionCreate(in->sessionType, in->authHash, 3998&in->nonceCaller, &in->symmetric, 3999in->bind, &salt, &out->sessionHandle); 4000if(result != TPM_RC_SUCCESS) 4001return result; 4002// Command Output 4003// Get session pointer 4004session = SessionGet(out->sessionHandle); 4005// Copy nonceTPM 4006out->nonceTPM = session->nonceTPM; 4007return TPM_RC_SUCCESS; 4008} 4009 4010Page 42 4011October 31, 2013 4012 4013Published 4014Copyright © TCG 2006-2013 4015 4016Family “2.0” 4017Level 00 Revision 00.99 4018 4019 Trusted Platform Module Library 4020 402113.2 4022 4023Part 3: Commands 4024 4025TPM2_PolicyRestart 4026 402713.2.1 General Description 4028This command allows a policy authorization session to be returned to its initial state. This command is 4029used after the TPM returns TPM_RC_PCR_CHANGED. That response code indicates that a policy will 4030fail because the PCR have changed after TPM2_PolicyPCR() was executed. Restarting the session 4031allows the authorizations to be replayed because the session restarts with the same nonceTPM. If the 4032PCR are valid for the policy, the policy may then succeed. 4033This command does not reset the policy ID or the policy start time. 4034 4035Family “2.0” 4036Level 00 Revision 00.99 4037 4038Published 4039Copyright © TCG 2006-2013 4040 4041Page 43 4042October 31, 2013 4043 4044 Part 3: Commands 4045 4046Trusted Platform Module Library 4047 404813.2.2 Command and Response 4049Table 17 — TPM2_PolicyRestart Command 4050Type 4051 4052Name 4053 4054Description 4055 4056TPMI_ST_COMMAND_TAG 4057 4058tag 4059 4060UINT32 4061 4062commandSize 4063 4064TPM_CC 4065 4066commandCode 4067 4068TPM_CC_PolicyRestart 4069 4070TPMI_SH_POLICY 4071 4072sessionHandle 4073 4074the handle for the policy session 4075 4076Table 18 — TPM2_PolicyRestart Response 4077Type 4078 4079Name 4080 4081Description 4082 4083TPM_ST 4084 4085tag 4086 4087see clause 8 4088 4089UINT32 4090 4091responseSize 4092 4093TPM_RC 4094 4095responseCode 4096 4097Page 44 4098October 31, 2013 4099 4100Published 4101Copyright © TCG 2006-2013 4102 4103Family “2.0” 4104Level 00 Revision 00.99 4105 4106 Trusted Platform Module Library 4107 4108Part 3: Commands 4109 411013.2.3 Detailed Actions 41111 41122 41133 41144 41155 41166 41177 41188 41199 412010 412111 412212 412313 412414 412515 412616 412717 412818 412919 413020 413121 413222 4133 4134#include "InternalRoutines.h" 4135#include "PolicyRestart_fp.h" 4136 4137TPM_RC 4138TPM2_PolicyRestart( 4139PolicyRestart_In 4140 4141*in 4142 4143// IN: input parameter list 4144 4145SESSION 4146BOOL 4147 4148*session; 4149wasTrialSession; 4150 4151) 4152{ 4153 4154// Internal Data Update 4155session = SessionGet(in->sessionHandle); 4156wasTrialSession = session->attributes.isTrialPolicy == SET; 4157// Initialize policy session 4158SessionResetPolicyData(session); 4159session->attributes.isTrialPolicy = wasTrialSession; 4160return TPM_RC_SUCCESS; 4161} 4162 4163Family “2.0” 4164Level 00 Revision 00.99 4165 4166Published 4167Copyright © TCG 2006-2013 4168 4169Page 45 4170October 31, 2013 4171 4172 Part 3: Commands 4173 4174Trusted Platform Module Library 4175 4176Object Commands 4177 417814 417914.1 4180 4181TPM2_Create 4182 418314.1.1 General Description 4184This command is used to create an object that can be loaded into a TPM using TPM2_Load(). If the 4185command completes successfully, the TPM will create the new object and return the object’s creation 4186data (creationData), its public area (outPublic), and its encrypted sensitive area (outPrivate). Preservation 4187of the returned data is the responsibility of the caller. The object will need to be loaded (TPM2_Load()) 4188before it may be used. 4189TPM2B_PUBLIC template (inPublic) contains all of the fields necessary to define the properties of the 4190new object. The setting for these fields is defined in “Public Area Template” in Part 1 and 4191“TPMA_OBJECT” in Part 2. 4192The parentHandle parameter shall reference a loaded decryption key that has both the public and 4193sensitive area loaded. 4194When defining the object, the caller provides a template structure for the object in a TPM2B_PUBLIC 4195structure (inPublic), an initial value for the object’s authValue (inSensitive.authValue), and, if the object is 4196a symmetric object, an optional initial data value (inSensitive.data). The TPM shall validate the 4197consistency of inPublic.attributes according to the Creation rules in “TPMA_OBJECT” in Part 2. 4198The sensitive parameter may be encrypted using parameter encryption. 4199The methods in this clause are used by both TPM2_Create() and TPM2_CreatePrimary(). When a value 4200is indicated as being TPM-generated, the value is filled in by bits from the RNG if the command is 4201TPM2_Create() and with values from KDFa() if the command is TPM2_CreatePrimary(). The parameters 4202of each creation value are specified in Part 1. 4203The sensitiveDataOrigin attribute of inPublic shall be SET if inSensitive.data is an Empty Buffer and 4204CLEAR if inSensitive.data is not an Empty Buffer or the TPM shall return TPM_RC_ATTRIBUTES. 4205The TPM will create new data for the sensitive area and compute a TPMT_PUBLIC.unique from the 4206sensitive area based on the object type: 4207a) For a symmetric key: 42081) If inSensitive.data is the Empty Buffer, a TPM-generated key value is placed in the new object’s 4209TPMT_SENSITIVE.sensitive.sym. The size of the key will be determined by 4210inPublic.publicArea.parameters. 42112) If inSensitive.data is not the Empty Buffer, the TPM will validate that the size of inSensitive.data is 4212no larger than the key size indicated in the inPublic template (TPM_RC_SIZE) and copy the 4213inSensitive.data to TPMT_SENSITIVE.sensitive.sym of the new object. 42143) A TPM-generated obfuscation value is placed in TPMT_SENSITIVE.sensitive.seedValue. The 4215size of the obfuscation value is the size of the digest produced by the nameAlg in inPublic. This 4216value prevents the public unique value from leaking information about the sensitive area. 42174) The TPMT_PUBLIC.unique.sym.buffer value for the new object is then generated, as shown in 4218equation (1) below, by hashing the key and obfuscation values in the TPMT_SENSITIVE with the 4219nameAlg of the object. 4220 4221unique ≔ HnameAlg(sensitive.seedValue.buffer || sensitive.any.buffer) 4222 4223(1) 4224 4225b) If the Object is an asymmetric key: 42261) If sensitive.data is not the Empty Buffer, then the TPM shall return TPM_RC_VALUE. 4227 4228Page 46 4229October 31, 2013 4230 4231Published 4232Copyright © TCG 2006-2013 4233 4234Family “2.0” 4235Level 00 Revision 00.99 4236 4237 Trusted Platform Module Library 4238 4239Part 3: Commands 4240 42412) A TPM-generated private key value is created with the size determined by the parameters of 4242inPublic.publicArea.parameters. 42433) If the key is a Storage Key, a TPM-generated TPMT_SENSITIVE.symKey value is created; 4244otherwise, TPMT_SENSITIVE.symKey.size is set to zero. 42454) The public unique value is computed from the private key according to the methods of the key 4246type. 42475) If the key is an ECC key and the scheme required by the curveID is not the same as scheme in 4248the public area of the template, then the TPM shall return TPM_RC_SCHEME. 42496) If the key is an ECC key and the KDF required by the curveID is not the same as kdf in the pubic 4250area of the template, then the TPM shall return TPM_RC_KDF. 4251NOTE 1 4252 4253There is currently no command in which the caller may specify the KDF to be used with an 4254ECC decryption key. Since there is no use for this capability, the reference implementation 4255requires that the kdf in the template be set to TPM_ALG_NULL or TPM_RC_KDF is 4256returned. 4257 4258c) If the Object is a keyedHash object: 42591) If inSensitive.data is an Empty Buffer, and neither sign nor decrypt is SET in inPublic.attributes, 4260the TPM shall return TPM_RC_ATTRIBUTES. This would be a data object with no data. 42612) If inSensitive.data is not an Empty Buffer, the TPM will copy the inSensitive.data to 4262TPMT_SENSITIVE.sensitive of the new object. 4263NOTE 2 4264 4265The size of inSensitive.data is limited to be no larger 4266TPMT_SENSITIVE.sensitive.bits.data by MAX_SYM_DATA. 4267 4268than 4269 4270the 4271 4272largest 4273 4274value 4275 4276of 4277 42783) If inSensitive.data is an Empty Buffer, a TPM-generated key value that is the size of the digest 4279produced by the nameAlg in inPublic is placed in TPMT_SENSITIVE.sensitive.any.buffer. 42804) A TPM-generated obfuscation value that is the size of the digest produced by the nameAlg of 4281inPublic is placed in TPMT_SENSITIVE.symKey.buffer. 42825) The TPMT_PUBLIC.unique.sym.buffer value for the new object is then generated, as shown in 4283equation (1) above, by hashing the key and obfuscation values in the TPMT_SENSITIVE with the 4284nameAlg of the object. 4285For TPM2_Load(), the TPM will apply normal symmetric protections to the created TPMT_SENSITIVE to 4286create outPublic. 4287NOTE 3 4288 4289The encryption key is derived from the symmetric seed in the sensitive area of the parent. 4290 4291In addition to outPublic and outPrivate, the TPM will build a TPMS_CREATION_DATA structure for the 4292object. TPMS_CREATION_DATA.outsideInfo is set to outsideInfo. This structure is returned in 4293creationData. Additionally, the digest of this structure is returned in creationHash, and, finally, a 4294TPMT_TK_CREATION is created so that the association between the creation data and the object may 4295be validated by TPM2_CertifyCreation(). 4296If the object being created is a Storage Key and inPublic.objectAttributes.fixedParent is SET, then the 4297algorithms of inPublic are required to match those of the parent. The algorithms that must match are 4298inPublic.type, inPublic.nameAlg, and inPublic.parameters. If inPublic.type does not match, the TPM shall 4299return TPM_RC_TYPE. If inPublic.nameAlg does not match, the TPM shall return TPM_RC_HASH. If 4300inPublic.parameters does not match, the TPM shall return TPM_RC_ASSYMETRIC. The TPM shall not 4301differentiate between mismatches of the components of inPublic.parameters. 4302EXAMPLE 4303 4304If the inPublic.parameters.ecc.symmetric.algorithm does not match the parent, the TPM shall return 4305TPM_RC_ ASYMMETRIC rather than TPM_RC_SYMMETRIC. 4306 4307Family “2.0” 4308Level 00 Revision 00.99 4309 4310Published 4311Copyright © TCG 2006-2013 4312 4313Page 47 4314October 31, 2013 4315 4316 Part 3: Commands 4317 4318Trusted Platform Module Library 4319 432014.1.2 Command and Response 4321Table 19 — TPM2_Create Command 4322Type 4323 4324Name 4325 4326Description 4327 4328TPMI_ST_COMMAND_TAG 4329 4330tag 4331 4332UINT32 4333 4334commandSize 4335 4336TPM_CC 4337 4338commandCode 4339 4340TPM_CC_Create 4341 4342TPMI_DH_OBJECT 4343 4344@parentHandle 4345 4346handle of parent for new object 4347Auth Index: 1 4348Auth Role: USER 4349 4350TPM2B_SENSITIVE_CREATE 4351 4352inSensitive 4353 4354the sensitive data 4355 4356TPM2B_PUBLIC 4357 4358inPublic 4359 4360the public template 4361 4362TPM2B_DATA 4363 4364outsideInfo 4365 4366data that will be included in the creation data for this 4367object to provide permanent, verifiable linkage between 4368this object and some object owner data 4369 4370TPML_PCR_SELECTION 4371 4372creationPCR 4373 4374PCR that will be used in creation data 4375 4376Table 20 — TPM2_Create Response 4377Type 4378 4379Name 4380 4381Description 4382 4383TPM_ST 4384 4385tag 4386 4387see clause 8 4388 4389UINT32 4390 4391responseSize 4392 4393TPM_RC 4394 4395responseCode 4396 4397TPM2B_PRIVATE 4398 4399outPrivate 4400 4401the private portion of the object 4402 4403TPM2B_PUBLIC 4404 4405outPublic 4406 4407the public portion of the created object 4408 4409TPM2B_CREATION_DATA 4410 4411creationData 4412 4413contains a TPMS_CREATION_DATA 4414 4415TPM2B_DIGEST 4416 4417creationHash 4418 4419digest of creationData using nameAlg of outPublic 4420 4421TPMT_TK_CREATION 4422 4423creationTicket 4424 4425ticket used by TPM2_CertifyCreation() to validate that 4426the creation data was produced by the TPM 4427 4428Page 48 4429October 31, 2013 4430 4431Published 4432Copyright © TCG 2006-2013 4433 4434Family “2.0” 4435Level 00 Revision 00.99 4436 4437 Trusted Platform Module Library 4438 4439Part 3: Commands 4440 444114.1.3 Detailed Actions 44421 44432 44443 4445 4446#include "InternalRoutines.h" 4447#include "Object_spt_fp.h" 4448#include "Create_fp.h" 4449Error Returns 4450TPM_RC_ASYMMETRIC 4451 4452non-duplicable storage key and its parent have different public 4453params 4454 4455TPM_RC_ATTRIBUTES 4456 4457sensitiveDataOrigin is CLEAR when 'sensitive. data' is an Empty 4458Buffer, or is SET when 'sensitive. data' is not empty; fixedTPM, 4459fixedParent, or encryptedDuplication attributes are inconsistent 4460between themselves or with those of the parent object; inconsistent 4461restricted, decrypt and sign attributes; attempt to inject sensitive data 4462for an asymmetric key; attempt to create a symmetric cipher key that 4463is not a decryption key 4464 4465TPM_RC_HASH 4466 4467non-duplicable storage key and its parent have different name 4468algorithm 4469 4470TPM_RC_KDF 4471 4472incorrect KDF specified for decrypting keyed hash object 4473 4474TPM_RC_KEY 4475 4476invalid key size values in an asymmetric key public area 4477 4478TPM_RC_KEY_SIZE 4479 4480key size in public area for symmetric key differs from the size in the 4481sensitive creation area; may also be returned if the TPM does not 4482allow the key size to be used for a Storage Key 4483 4484TPM_RC_RANGE 4485 4486FOr() an RSA key, the exponent value is not supported. 4487 4488TPM_RC_SCHEME 4489 4490inconsistent attributes decrypt, sign, restricted and key's scheme ID; 4491or hash algorithm is inconsistent with the scheme ID for keyed hash 4492object 4493 4494TPM_RC_SIZE 4495 4496size of public auth policy or sensitive auth value does not match 4497digest size of the name algorithm sensitive data size for the keyed 4498hash object is larger than is allowed for the scheme 4499 4500TPM_RC_SYMMETRIC 4501 4502a storage key with no symmetric algorithm specified; or non-storage 4503key with symmetric algorithm different from TPM_ALG_NULL 4504 4505TPM_RC_TYPE 4506 4507unknown object type; non-duplicable storage key and its parent have 4508different types; parentHandle does not reference a restricted 4509decryption key in the storage hierarchy with both public and sensitive 4510portion loaded 4511 4512TPM_RC_VALUE 4513 4514exponent is not prime or could not find a prime using the provided 4515parameters for an RSA key; unsupported name algorithm for an ECC 4516key 4517 4518TPM_RC_OBJECT_MEMORY 4519 45204 45215 45226 45237 45248 45259 452610 452711 452812 452913 4530 4531Meaning 4532 4533there is no free slot for the object. This implementation does not 4534return this error. 4535 4536TPM_RC 4537TPM2_Create( 4538Create_In 4539Create_Out 4540 4541*in, 4542*out 4543 4544// IN: input parameter list 4545// OUT: output parameter list 4546 4547) 4548{ 4549TPM_RC 4550TPMT_SENSITIVE 4551TPM2B_NAME 4552 4553Family “2.0” 4554Level 00 Revision 00.99 4555 4556result = TPM_RC_SUCCESS; 4557sensitive; 4558name; 4559 4560Published 4561Copyright © TCG 2006-2013 4562 4563Page 49 4564October 31, 2013 4565 4566 Part 3: Commands 456714 456815 456916 457017 457118 457219 457320 457421 457522 457623 457724 457825 457926 458027 458128 458229 458330 458431 458532 458633 458734 458835 458936 459037 459138 459239 459340 459441 459542 459643 459744 459845 459946 460047 460148 460249 460350 460451 460552 460653 460754 460855 460956 461057 461158 461259 461360 461461 461562 461663 461764 461865 461966 462067 462168 462269 462370 462471 462572 462673 4627 4628Trusted Platform Module Library 4629 4630// Input Validation 4631OBJECT 4632 4633*parentObject; 4634 4635parentObject = ObjectGet(in->parentHandle); 4636// Does parent have the proper attributes? 4637if(!AreAttributesForParent(parentObject)) 4638return TPM_RC_TYPE + RC_Create_parentHandle; 4639// The sensitiveDataOrigin attribute must be consistent with the setting of 4640// the size of the data object in inSensitive. 4641if( 4642(in->inPublic.t.publicArea.objectAttributes.sensitiveDataOrigin == SET) 4643!= (in->inSensitive.t.sensitive.data.t.size == 0)) 4644// Mismatch between the object attributes and the parameter. 4645return TPM_RC_ATTRIBUTES + RC_Create_inSensitive; 4646// Check attributes in input public area. TPM_RC_ASYMMETRIC, TPM_RC_ATTRIBUTES, 4647// TPM_RC_HASH, TPM_RC_KDF, TPM_RC_SCHEME, TPM_RC_SIZE, TPM_RC_SYMMETRIC, 4648// or TPM_RC_TYPE error may be returned at this point. 4649result = PublicAttributesValidation(FALSE, in->parentHandle, 4650&in->inPublic.t.publicArea); 4651if(result != TPM_RC_SUCCESS) 4652return RcSafeAddToResult(result, RC_Create_inPublic); 4653// Validate the sensitive area values 4654if( MemoryRemoveTrailingZeros(&in->inSensitive.t.sensitive.userAuth) 4655> CryptGetHashDigestSize(in->inPublic.t.publicArea.nameAlg)) 4656return TPM_RC_SIZE + RC_Create_inSensitive; 4657// Command Output 4658// Create object crypto data 4659result = CryptCreateObject(in->parentHandle, &in->inPublic.t.publicArea, 4660&in->inSensitive.t.sensitive, &sensitive); 4661if(result != TPM_RC_SUCCESS) 4662return result; 4663// Fill in creation data 4664FillInCreationData(in->parentHandle, in->inPublic.t.publicArea.nameAlg, 4665&in->creationPCR, &in->outsideInfo, 4666&out->creationData, &out->creationHash); 4667// Copy public area from input to output 4668out->outPublic.t.publicArea = in->inPublic.t.publicArea; 4669// Compute name from public area 4670ObjectComputeName(&(out->outPublic.t.publicArea), &name); 4671// Compute creation ticket 4672TicketComputeCreation(EntityGetHierarchy(in->parentHandle), &name, 4673&out->creationHash, &out->creationTicket); 4674// Prepare output private data from sensitive 4675SensitiveToPrivate(&sensitive, &name, in->parentHandle, 4676out->outPublic.t.publicArea.nameAlg, 4677&out->outPrivate); 4678return TPM_RC_SUCCESS; 4679} 4680 4681Page 50 4682October 31, 2013 4683 4684Published 4685Copyright © TCG 2006-2013 4686 4687Family “2.0” 4688Level 00 Revision 00.99 4689 4690 Trusted Platform Module Library 4691 469214.2 4693 4694Part 3: Commands 4695 4696TPM2_Load 4697 469814.2.1 General Description 4699This command is used to load objects into the TPM. This command is used when both a TPM2B_PUBLIC 4700and TPM2B_PRIVATE are to be loaded. If only a TPM2B_PUBLIC is to be loaded, the 4701TPM2_LoadExternal command is used. 4702NOTE 1 4703 4704Loading an object is not the same as restoring a saved object context. 4705 4706The object’s TPMA_OBJECT attributes will be checked according to the rules defined in 4707“TPMA_OBJECT” in Part 2 of this specification. 4708Objects loaded using this command will have a Name. The Name is the concatenation of nameAlg and 4709the digest of the public area using the nameAlg. 4710NOTE 2 4711 4712nameAlg is a parameter in the public area of the inPublic structure. 4713 4714If inPrivate.size is zero, the load will fail. 4715After inPrivate.buffer is decrypted using the symmetric key of the parent, the integrity value shall be 4716checked before the sensitive area is used, or unmarshaled. 4717NOTE 3 4718 4719Checking the integrity before the data is used prevents attacks o n the sensitive area by fuzzing the 4720data and looking at the differences in the response codes. 4721 4722The command returns a handle for the loaded object and the Name that the TPM computed for 4723inPublic.public (that is, the digest of the TPMT_PUBLIC structure in inPublic). 4724NOTE 4 4725 4726The TPM-computed Name is provided as a convenience to the caller for those cases where the 4727caller does not implement the hash algorithms specified in the nameAlg of the object. 4728 4729NOTE 5 4730 4731The returned handle is associated with the object until the object is flushed (TPM2_FlushContext) or 4732until the next TPM2_Startup. 4733 4734For all objects, the size of the key in the sensitive area shall be consistent with the key size indicated in 4735the public area or the TPM shall return TPM_RC_KEY_SIZE. 4736Before use, a loaded object shall be checked to validate that the public and sensitive portions are 4737properly linked, cryptographically. Use of an object includes use in any policy command. If the parts of the 4738object are not properly linked, the TPM shall return TPM_RC_BINDING. 4739EXAMPLE 1 4740 4741For a symmetric object, the unique value in the public area shall be the digest of the sensitive key 4742and the obfuscation value. 4743 4744EXAMPLE 2 4745 4746For a two-prime RSA key, the remainder when dividing the public modulus by the private key shall 4747be zero and it shall be possible to form a private exponent from the two prime factors of the public 4748modulus. 4749 4750EXAMPLE 3 4751 4752For an ECC key, the public point shall be f(x) where x is the private key. 4753 4754Family “2.0” 4755Level 00 Revision 00.99 4756 4757Published 4758Copyright © TCG 2006-2013 4759 4760Page 51 4761October 31, 2013 4762 4763 Part 3: Commands 4764 4765Trusted Platform Module Library 4766 476714.2.2 Command and Response 4768Table 21 — TPM2_Load Command 4769Type 4770 4771Name 4772 4773Description 4774 4775TPMI_ST_COMMAND_TAG 4776 4777tag 4778 4779UINT32 4780 4781commandSize 4782 4783TPM_CC 4784 4785commandCode 4786 4787TPM_CC_Load 4788 4789TPMI_DH_OBJECT 4790 4791@parentHandle 4792 4793TPM handle of parent key; shall not be a reserved 4794handle 4795Auth Index: 1 4796Auth Role: USER 4797 4798TPM2B_PRIVATE 4799 4800inPrivate 4801 4802the private portion of the object 4803 4804TPM2B_PUBLIC 4805 4806inPublic 4807 4808the public portion of the object 4809 4810Table 22 — TPM2_Load Response 4811Type 4812 4813Name 4814 4815Description 4816 4817TPM_ST 4818 4819tag 4820 4821see clause 8 4822 4823UINT32 4824 4825responseSize 4826 4827TPM_RC 4828 4829responseCode 4830 4831TPM_HANDLE 4832 4833objectHandle 4834 4835handle for the loaded object 4836 4837TPM2B_NAME 4838 4839name 4840 4841Name of the loaded object 4842 4843Page 52 4844October 31, 2013 4845 4846Published 4847Copyright © TCG 2006-2013 4848 4849Family “2.0” 4850Level 00 Revision 00.99 4851 4852 Trusted Platform Module Library 4853 4854Part 3: Commands 4855 485614.2.3 Detailed Actions 48571 48582 48593 4860 4861#include "InternalRoutines.h" 4862#include "Load_fp.h" 4863#include "Object_spt_fp.h" 4864Error Returns 4865TPM_RC_ASYMMETRIC 4866 4867storage key with different asymmetric type than parent 4868 4869TPM_RC_ATTRIBUTES 4870 4871inPulblic attributes are not allowed with selected parent 4872 4873TPM_RC_BINDING 4874 4875inPrivate and inPublic are not cryptographically bound 4876 4877TPM_RC_HASH 4878 4879incorrect hash selection for signing key 4880 4881TPM_RC_INTEGRITY 4882 4883HMAC on inPrivate was not valid 4884 4885TPM_RC_KDF 4886 4887KDF selection not allowed 4888 4889TPM_RC_KEY 4890 4891the size of the object's unique field is not consistent with the indicated 4892size in the object's parameters 4893 4894TPM_RC_OBJECT_MEMORY 4895 4896no available object slot 4897 4898TPM_RC_SCHEME 4899 4900the signing scheme is not valid for the key 4901 4902TPM_RC_SENSITIVE 4903 4904the inPrivate did not unmarshal correctly 4905 4906TPM_RC_SIZE 4907 4908inPrivate missing, or authPolicy size for inPublic or is not valid 4909 4910TPM_RC_SYMMETRIC 4911 4912symmetric algorithm not provided when required 4913 4914TPM_RC_TYPE 4915 4916parentHandle is not a storage key, or the object to load is a storage 4917key but its parameters do not match the parameters of the parent. 4918 4919TPM_RC_VALUE 49204 49215 49226 49237 49248 49259 492610 492711 492812 492913 493014 493115 493216 493317 493418 493519 493620 493721 493822 493923 494024 494125 494226 494327 494428 494529 494630 4947 4948Meaning 4949 4950decryption failure 4951 4952TPM_RC 4953TPM2_Load( 4954Load_In *in, 4955Load_Out *out 4956 4957// IN: input parameter list 4958// OUT: output parameter list 4959 4960) 4961{ 4962TPM_RC 4963TPMT_SENSITIVE 4964TPMI_RH_HIERARCHY 4965OBJECT 4966BOOL 4967 4968result = TPM_RC_SUCCESS; 4969sensitive; 4970hierarchy; 4971*parentObject = NULL; 4972skipChecks = FALSE; 4973 4974// Input Validation 4975if(in->inPrivate.t.size == 0) 4976return TPM_RC_SIZE + RC_Load_inPrivate; 4977parentObject = ObjectGet(in->parentHandle); 4978// Is the object that is being used as the parent actually a parent. 4979if(!AreAttributesForParent(parentObject)) 4980return TPM_RC_TYPE + RC_Load_parentHandle; 4981// If the parent is fixedTPM, then the attributes of the object 4982// are either "correct by construction" or were validated 4983// when the object was imported. If they pass the integrity 4984// check, then the values are valid 4985if(parentObject->publicArea.objectAttributes.fixedTPM) 4986skipChecks = TRUE; 4987 4988Family “2.0” 4989Level 00 Revision 00.99 4990 4991Published 4992Copyright © TCG 2006-2013 4993 4994Page 53 4995October 31, 2013 4996 4997 Part 3: Commands 499831 499932 500033 500134 500235 500336 500437 500538 500639 500740 500841 500942 501043 501144 501245 501346 501447 501548 501649 501750 501851 501952 502053 502154 502255 502356 502457 502558 502659 502760 502861 502962 503063 503164 503265 503366 503467 503568 503669 503770 503871 503972 504073 504174 504275 504376 5044 5045Trusted Platform Module Library 5046 5047else 5048{ 5049// If parent doesn't have fixedTPM SET, then this can't have 5050// fixedTPM SET. 5051if(in->inPublic.t.publicArea.objectAttributes.fixedTPM == SET) 5052return TPM_RC_ATTRIBUTES + RC_Load_inPublic; 5053// Perform self check on input public area. A TPM_RC_SIZE, TPM_RC_SCHEME, 5054// TPM_RC_VALUE, TPM_RC_SYMMETRIC, TPM_RC_TYPE, TPM_RC_HASH, 5055// TPM_RC_ASYMMETRIC, TPM_RC_ATTRIBUTES or TPM_RC_KDF error may be returned 5056// at this point 5057result = PublicAttributesValidation(TRUE, in->parentHandle, 5058&in->inPublic.t.publicArea); 5059if(result != TPM_RC_SUCCESS) 5060return RcSafeAddToResult(result, RC_Load_inPublic); 5061} 5062// Compute the name of object 5063ObjectComputeName(&in->inPublic.t.publicArea, &out->name); 5064// Retrieve sensitive data. PrivateToSensitive() may return TPM_RC_INTEGRITY or 5065// TPM_RC_SENSITIVE 5066// errors may be returned at this point 5067result = PrivateToSensitive(&in->inPrivate, &out->name, in->parentHandle, 5068in->inPublic.t.publicArea.nameAlg, 5069&sensitive); 5070if(result != TPM_RC_SUCCESS) 5071return RcSafeAddToResult(result, RC_Load_inPrivate); 5072// Internal Data Update 5073// Get hierarchy of parent 5074hierarchy = ObjectGetHierarchy(in->parentHandle); 5075// Create internal object. A lot of different errors may be returned by this 5076// loading operation as it will do several validations, including the public 5077// binding check 5078result = ObjectLoad(hierarchy, &in->inPublic.t.publicArea, &sensitive, 5079&out->name, in->parentHandle, skipChecks, 5080&out->objectHandle); 5081if(result != TPM_RC_SUCCESS) 5082return result; 5083return TPM_RC_SUCCESS; 5084} 5085 5086Page 54 5087October 31, 2013 5088 5089Published 5090Copyright © TCG 2006-2013 5091 5092Family “2.0” 5093Level 00 Revision 00.99 5094 5095 Trusted Platform Module Library 5096 509714.3 5098 5099Part 3: Commands 5100 5101TPM2_LoadExternal 5102 510314.3.1 General Description 5104This command is used to load an object that is not a Protected Object into the TPM. The command allows 5105loading of a public area or both a public and sensitive area. 5106NOTE 1 5107 5108Typical use for loading a public area is to allow the TPM to validate an asymmetric signature. 5109Typical use for loading both a public and sensitive area is to allow the TPM to be used as a crypto 5110accelerator. 5111 5112Load of a public external object area allows the object be associated with a hierarchy so that the correct 5113algorithms may be used when creating tickets. The hierarchy parameter provides this association. If the 5114public and sensitive portions of the object are loaded, hierarchy is required to be TPM_RH_NULL. 5115NOTE 2 5116 5117If both the public and private portions of an object are loaded, the object is not allowed to appear to 5118be part of a hierarchy. 5119 5120The object’s TPMA_OBJECT attributes will be checked according to the rules defined in 5121“TPMA_OBJECT” in Part 2. In particular, fixedTPM, fixedParent, and restricted shall be CLEAR if 5122inPrivate is not the Empty Buffer. 5123NOTE 3 5124 5125The duplication status of a public key needs to be able to be the same as the full key which may be 5126resident on a different TPM. If both the public and private parts of the key are loaded, then it is not 5127possible for the key to be either fixedTPM or fixedParent, since, its private area would not be 5128available in the clear to load. 5129 5130Objects loaded using this command will have a Name. The Name is the nameAlg of the object 5131concatenated with the digest of the public area using the nameAlg. The Qualified Name for the object will 5132be the same as its Name. The TPM will validate that the authPolicy is either the size of the digest 5133produced by nameAlg or the Empty Buffer. 5134NOTE 4 5135 5136If nameAlg is TPM_ALG_NULL, then the Name is the Empty Buffer. When the authorization value for 5137an object with no Name is computed, no Name value is included in the HMAC. To ensure that these 5138unnamed entities are not substituted, they should have an authValue that is statistically unique. 5139 5140NOTE 5 5141 5142The digest size for TPM_ALG_NULL is zero. 5143 5144If the nameAlg is TPM_ALG_NULL, the TPM shall not verify the cryptographic binding between the public 5145and sensitive areas, but the TPM will validate that the size of the key in the sensitive area is consistent 5146with the size indicated in the public area. If it is not, the TPM shall return TPM_RC_KEY_SIZE. 5147NOTE 6 5148 5149For an ECC object, the TPM will verify that the public key is on the curve of the key before the public 5150area is used. 5151 5152If nameAlg is not TPM_ALG_NULL, then the same consistency checks between inPublic and inPrivate 5153are made as for TPM2_Load(). 5154NOTE 7 5155 5156Consistency checks are necessary because an object with a Name needs to have the public and 5157sensitive portions cryptographically bound so that an attacker cannot mix pubic and sensitive areas. 5158 5159The command returns a handle for the loaded object and the Name that the TPM computed for 5160inPublic.public (that is, the TPMT_PUBLIC structure in inPublic). 5161NOTE 8 5162 5163The TPM-computed Name is provided as a convenience to the caller for those cases where the 5164caller does not implement the hash algorithm specified in the nameAlg of the object. 5165 5166Family “2.0” 5167Level 00 Revision 00.99 5168 5169Published 5170Copyright © TCG 2006-2013 5171 5172Page 55 5173October 31, 2013 5174 5175 Part 3: Commands 5176 5177Trusted Platform Module Library 5178 5179The hierarchy parameter associates the external object with a hierarchy. External objects are flushed 5180when their associated hierarchy is disabled. If hierarchy is TPM_RH_NULL, the object is part of no 5181hierarchy, and there is no implicit flush. 5182If hierarchy is TPM_RH_NULL or nameAlg is TPM_ALG_NULL, a ticket produced using the object shall 5183be a NULL Ticket. 5184EXAMPLE 5185 5186If a key is loaded with hierarchy set to TPM_RH_NULL, then TPM2_VerifySignature() will produce a 5187NULL Ticket of the required type. 5188 5189External objects are Temporary Objects. The saved external object contexts shall be invalidated at the 5190next TPM Reset. 5191 5192Page 56 5193October 31, 2013 5194 5195Published 5196Copyright © TCG 2006-2013 5197 5198Family “2.0” 5199Level 00 Revision 00.99 5200 5201 Trusted Platform Module Library 5202 5203Part 3: Commands 5204 520514.3.2 Command and Response 5206Table 23 — TPM2_LoadExternal Command 5207Type 5208 5209Name 5210 5211Description 5212 5213TPMI_ST_COMMAND_TAG 5214 5215tag 5216 5217UINT32 5218 5219commandSize 5220 5221TPM_CC 5222 5223commandCode 5224 5225TPM_CC_LoadExternal 5226 5227TPM2B_SENSITIVE 5228 5229inPrivate 5230 5231the sensitive portion of the object (optional) 5232 5233TPM2B_PUBLIC+ 5234 5235inPublic 5236 5237the public portion of the object 5238 5239TPMI_RH_HIERARCHY+ 5240 5241hierarchy 5242 5243hierarchy with which the object area is associated 5244 5245Table 24 — TPM2_LoadExternal Response 5246Type 5247 5248Name 5249 5250Description 5251 5252TPM_ST 5253 5254tag 5255 5256see clause 8 5257 5258UINT32 5259 5260responseSize 5261 5262TPM_RC 5263 5264responseCode 5265 5266TPM_HANDLE 5267 5268objectHandle 5269 5270handle for the loaded object 5271 5272TPM2B_NAME 5273 5274name 5275 5276name of the loaded object 5277 5278Family “2.0” 5279Level 00 Revision 00.99 5280 5281Published 5282Copyright © TCG 2006-2013 5283 5284Page 57 5285October 31, 2013 5286 5287 Part 3: Commands 5288 5289Trusted Platform Module Library 5290 529114.3.3 Detailed Actions 52921 52932 52943 5295 5296#include "InternalRoutines.h" 5297#include "LoadExternal_fp.h" 5298#include "Object_spt_fp.h" 5299Error Returns 5300TPM_RC_ATTRIBUTES 5301 5302'fixedParent" and fixedTPM must be CLEAR on on an external key if 5303both public and sensitive portions are loaded 5304 5305TPM_RC_BINDING 5306 5307the inPublic and inPrivate structures are not cryptographically bound. 5308 5309TPM_RC_HASH 5310 5311incorrect hash selection for signing key 5312 5313TPM_RC_HIERARCHY 5314 5315hierarchy is turned off, or only NULL hierarchy is allowed when 5316loading public and private parts of an object 5317 5318TPM_RC_KDF 5319 5320incorrect KDF selection for decrypting keyedHash object 5321 5322TPM_RC_KEY 5323 5324the size of the object's unique field is not consistent with the indicated 5325size in the object's parameters 5326 5327TPM_RC_OBJECT_MEMORY 5328 5329if there is no free slot for an object 5330 5331TPM_RC_SCHEME 5332 5333the signing scheme is not valid for the key 5334 5335TPM_RC_SIZE 5336 5337authPolicy is not zero and is not the size of a digest produced by the 5338object's nameAlg TPM_RH_NULL hierarchy 5339 5340TPM_RC_SYMMETRIC 5341 5342symmetric algorithm not provided when required 5343 5344TPM_RC_TYPE 53454 53465 53476 53487 53498 53509 535110 535211 535312 535413 535514 535615 535716 535817 535918 536019 536120 536221 536322 536423 536524 536625 536726 536827 536928 537029 537130 537231 537332 537433 5375 5376Meaning 5377 5378inPublic and inPrivate are not the same type 5379 5380TPM_RC 5381TPM2_LoadExternal( 5382LoadExternal_In 5383LoadExternal_Out 5384 5385*in, 5386*out 5387 5388// IN: input parameter list 5389// OUT: output parameter list 5390 5391TPM_RC 5392TPMT_SENSITIVE 5393BOOL 5394 5395result; 5396*sensitive; 5397skipChecks; 5398 5399) 5400{ 5401 5402// Input Validation 5403// If the target hierarchy is turned off, the object can not be loaded. 5404if(!HierarchyIsEnabled(in->hierarchy)) 5405return TPM_RC_HIERARCHY + RC_LoadExternal_hierarchy; 5406// the size of authPolicy is either 0 or the digest size of nameAlg 5407if(in->inPublic.t.publicArea.authPolicy.t.size != 0 5408&& in->inPublic.t.publicArea.authPolicy.t.size != 5409CryptGetHashDigestSize(in->inPublic.t.publicArea.nameAlg)) 5410return TPM_RC_SIZE + RC_LoadExternal_inPublic; 5411// For loading an object with both public and sensitive 5412if(in->inPrivate.t.size != 0) 5413{ 5414// An external object can only be loaded at TPM_RH_NULL hierarchy 5415if(in->hierarchy != TPM_RH_NULL) 5416return TPM_RC_HIERARCHY + RC_LoadExternal_hierarchy; 5417// An external object with a sensitive area must have fixedTPM == CLEAR 5418// fixedParent == CLEAR, and must have restrict CLEAR so that it does not 5419 5420Page 58 5421October 31, 2013 5422 5423Published 5424Copyright © TCG 2006-2013 5425 5426Family “2.0” 5427Level 00 Revision 00.99 5428 5429 Trusted Platform Module Library 543034 543135 543236 543337 543438 543539 543640 543741 543842 543943 544044 544145 544246 544347 544448 544549 544650 544751 544852 544953 545054 545155 545256 545357 545458 545559 545660 545761 545862 545963 546064 546165 5462 5463Part 3: Commands 5464 5465// appear to be a key that was created by this TPM. 5466if( 5467in->inPublic.t.publicArea.objectAttributes.fixedTPM != CLEAR 5468|| in->inPublic.t.publicArea.objectAttributes.fixedParent != CLEAR 5469|| in->inPublic.t.publicArea.objectAttributes.restricted != CLEAR 5470) 5471return TPM_RC_ATTRIBUTES + RC_LoadExternal_inPublic; 5472} 5473// Validate the scheme parameters 5474result = SchemeChecks(TRUE, TPM_RH_NULL, &in->inPublic.t.publicArea); 5475if(result != TPM_RC_SUCCESS) 5476return RcSafeAddToResult(result, RC_LoadExternal_inPublic); 5477// Internal Data Update 5478// Need the name to compute the qualified name 5479ObjectComputeName(&in->inPublic.t.publicArea, &out->name); 5480skipChecks = (in->inPublic.t.publicArea.nameAlg == TPM_ALG_NULL); 5481// If a sensitive area was provided, load it 5482if(in->inPrivate.t.size != 0) 5483sensitive = &in->inPrivate.t.sensitiveArea; 5484else 5485sensitive = NULL; 5486// Create external object. A TPM_RC_BINDING, TPM_RC_KEY, TPM_RC_OBJECT_MEMORY 5487// or TPM_RC_TYPE error may be returned by ObjectLoad() 5488result = ObjectLoad(in->hierarchy, &in->inPublic.t.publicArea, 5489sensitive, &out->name, TPM_RH_NULL, skipChecks, 5490&out->objectHandle); 5491return result; 5492} 5493 5494Family “2.0” 5495Level 00 Revision 00.99 5496 5497Published 5498Copyright © TCG 2006-2013 5499 5500Page 59 5501October 31, 2013 5502 5503 Part 3: Commands 5504 550514.4 5506 5507Trusted Platform Module Library 5508 5509TPM2_ReadPublic 5510 551114.4.1 General Description 5512This command allows access to the public area of a loaded object. 5513Use of the objectHandle does not require authorization. 5514NOTE 5515 5516Since the caller is not likely to know the public area of the object associated with objectHandle, it 5517would not be possible to include the Name associated with objectHandle in the cpHash computation. 5518 5519If objectHandle references a sequence object, the TPM shall return TPM_RC_SEQUENCE. 5520 5521Page 60 5522October 31, 2013 5523 5524Published 5525Copyright © TCG 2006-2013 5526 5527Family “2.0” 5528Level 00 Revision 00.99 5529 5530 Trusted Platform Module Library 5531 5532Part 3: Commands 5533 553414.4.2 Command and Response 5535Table 25 — TPM2_ReadPublic Command 5536Type 5537 5538Name 5539 5540Description 5541 5542TPMI_ST_COMMAND_TAG 5543 5544tag 5545 5546UINT32 5547 5548commandSize 5549 5550TPM_CC 5551 5552commandCode 5553 5554TPM_CC_ReadPublic 5555 5556TPMI_DH_OBJECT 5557 5558objectHandle 5559 5560TPM handle of an object 5561Auth Index: None 5562 5563Table 26 — TPM2_ReadPublic Response 5564Type 5565 5566Name 5567 5568Description 5569 5570TPM_ST 5571 5572tag 5573 5574see clause 8 5575 5576UINT32 5577 5578responseSize 5579 5580TPM_RC 5581 5582responseCode 5583 5584TPM2B_PUBLIC 5585 5586outPublic 5587 5588structure containing the public area of an object 5589 5590TPM2B_NAME 5591 5592name 5593 5594name of the object 5595 5596TPM2B_NAME 5597 5598qualifiedName 5599 5600the Qualified Name of the object 5601 5602Family “2.0” 5603Level 00 Revision 00.99 5604 5605Published 5606Copyright © TCG 2006-2013 5607 5608Page 61 5609October 31, 2013 5610 5611 Part 3: Commands 5612 5613Trusted Platform Module Library 5614 561514.4.3 Detailed Actions 56161 56172 5618 5619#include "InternalRoutines.h" 5620#include "ReadPublic_fp.h" 5621Error Returns 5622TPM_RC_SEQUENCE 5623 56243 56254 56265 56276 56287 56298 56309 563110 563211 563312 563413 563514 563615 563716 563817 563918 564019 564120 564221 564322 564423 564524 564625 564726 564827 564928 565029 565130 565231 565332 565433 565534 565635 565736 5658 5659Meaning 5660can not read the public area of a sequence object 5661 5662TPM_RC 5663TPM2_ReadPublic( 5664ReadPublic_In 5665ReadPublic_Out 5666 5667*in, 5668*out 5669 5670// IN: input parameter list 5671// OUT: output parameter list 5672 5673OBJECT 5674 5675*object; 5676 5677) 5678{ 5679// Input Validation 5680// Get loaded object pointer 5681object = ObjectGet(in->objectHandle); 5682// Can not read public area of a sequence object 5683if(ObjectIsSequence(object)) 5684return TPM_RC_SEQUENCE; 5685// Command Output 5686// Compute size of public area in canonical form 5687out->outPublic.t.size = TPMT_PUBLIC_Marshal(&object->publicArea, NULL, NULL); 5688// Copy public area to output 5689out->outPublic.t.publicArea = object->publicArea; 5690// Copy name to output 5691out->name.t.size = ObjectGetName(in->objectHandle, &out->name.t.name); 5692// Copy qualified name to output 5693ObjectGetQualifiedName(in->objectHandle, &out->qualifiedName); 5694return TPM_RC_SUCCESS; 5695} 5696 5697Page 62 5698October 31, 2013 5699 5700Published 5701Copyright © TCG 2006-2013 5702 5703Family “2.0” 5704Level 00 Revision 00.99 5705 5706 Trusted Platform Module Library 5707 570814.5 5709 5710Part 3: Commands 5711 5712TPM2_ActivateCredential 5713 571414.5.1 General Description 5715This command enables the association of a credential with an object in a way that ensures that the TPM 5716has validated the parameters of the credentialed object. 5717If both the public and private portions of activateHandle and keyHandle are not loaded, then the TPM 5718shall return TPM_RC_AUTH_UNAVAILABLE. 5719If keyHandle is not a Storage Key, then the TPM shall return TPM_RC_TYPE. 5720Authorization for activateHandle requires the ADMIN role. 5721The key associated with keyHandle is used to recover a seed from secret, which is the encrypted seed. 5722The Name of the object associated with activateHandle and the recovered seed are used in a KDF to 5723recover the symmetric key. The recovered seed (but not the Name) is used is used in a KDF to recover 5724the HMAC key. 5725The HMAC is used to validate that the credentialBlob is associated with activateHandle and that the data 5726in credentialBlob has not been modified. The linkage to the object associated with activateHandle is 5727achieved by including the Name in the HMAC calculation. 5728If the integrity checks succeed, credentialBlob is decrypted and returned as certInfo. 5729 5730Family “2.0” 5731Level 00 Revision 00.99 5732 5733Published 5734Copyright © TCG 2006-2013 5735 5736Page 63 5737October 31, 2013 5738 5739 Part 3: Commands 5740 5741Trusted Platform Module Library 5742 574314.5.2 Command and Response 5744Table 27 — TPM2_ActivateCredential Command 5745Type 5746 5747Name 5748 5749TPMI_ST_COMMAND_TAG 5750 5751tag 5752 5753UINT32 5754 5755commandSize 5756 5757TPM_CC 5758 5759commandCode 5760 5761Description 5762 5763TPM_CC_ActivateCredential 5764 5765TPMI_DH_OBJECT 5766 5767@activateHandle 5768 5769handle of the object associated with certificate in 5770credentialBlob 5771Auth Index: 1 5772Auth Role: ADMIN 5773 5774TPMI_DH_OBJECT 5775 5776@keyHandle 5777 5778loaded key used to decrypt the TPMS_SENSITIVE in 5779credentialBlob 5780Auth Index: 2 5781Auth Role: USER 5782 5783TPM2B_ID_OBJECT 5784 5785credentialBlob 5786 5787the credential 5788 5789TPM2B_ENCRYPTED_SECRET 5790 5791secret 5792 5793keyHandle algorithm-dependent encrypted seed that 5794protects credentialBlob 5795 5796Table 28 — TPM2_ActivateCredential Response 5797Type 5798 5799Name 5800 5801Description 5802 5803TPM_ST 5804 5805tag 5806 5807see clause 8 5808 5809UINT32 5810 5811responseSize 5812 5813TPM_RC 5814 5815responseCode 5816 5817TPM2B_DIGEST 5818 5819certInfo 5820 5821Page 64 5822October 31, 2013 5823 5824the decrypted certificate information 5825the data should be no larger than the size of the digest 5826of the nameAlg associated with keyHandle 5827 5828Published 5829Copyright © TCG 2006-2013 5830 5831Family “2.0” 5832Level 00 Revision 00.99 5833 5834 Trusted Platform Module Library 5835 5836Part 3: Commands 5837 583814.5.3 Detailed Actions 58391 58402 58413 5842 5843#include "InternalRoutines.h" 5844#include "ActivateCredential_fp.h" 5845#include "Object_spt_fp.h" 5846Error Returns 5847TPM_RC_ATTRIBUTES 5848 5849keyHandle does not reference a decryption key 5850 5851TPM_RC_ECC_POINT 5852 5853secret is invalid (when keyHandle is an ECC key) 5854 5855TPM_RC_INSUFFICIENT 5856 5857secret is invalid (when keyHandle is an ECC key) 5858 5859TPM_RC_INTEGRITY 5860 5861credentialBlob fails integrity test 5862 5863TPM_RC_NO_RESULT 5864 5865secret is invalid (when keyHandle is an ECC key) 5866 5867TPM_RC_SIZE 5868 5869secret size is invalid or the credentialBlob does not unmarshal 5870correctly 5871 5872TPM_RC_TYPE 5873 5874keyHandle does not reference an asymmetric key. 5875 5876TPM_RC_VALUE 58774 58785 58796 58807 58818 58829 588310 588411 588512 588613 588714 588815 588916 589017 589118 589219 589320 589421 589522 589623 589724 589825 589926 590027 590128 590229 590330 590431 590532 590633 590734 590835 590936 591037 591138 591239 591340 591441 5915 5916Meaning 5917 5918secret is invalid (when keyHandle is an RSA key) 5919 5920TPM_RC 5921TPM2_ActivateCredential( 5922ActivateCredential_In 5923ActivateCredential_Out 5924 5925*in, 5926*out 5927 5928// IN: input parameter list 5929// OUT: output parameter list 5930 5931TPM_RC 5932OBJECT 5933OBJECT 5934// credential 5935TPM2B_DATA 5936 5937result = TPM_RC_SUCCESS; 5938*object; 5939// decrypt key 5940*activateObject;// key associated with 5941 5942) 5943{ 5944 5945data; 5946 5947// credential data 5948 5949// Input Validation 5950// Get decrypt key pointer 5951object = ObjectGet(in->keyHandle); 5952// Get certificated object pointer 5953activateObject = ObjectGet(in->activateHandle); 5954// input decrypt key must be an asymmetric, restricted decryption key 5955if( 5956!CryptIsAsymAlgorithm(object->publicArea.type) 5957|| object->publicArea.objectAttributes.decrypt == CLEAR 5958|| object->publicArea.objectAttributes.restricted == CLEAR) 5959return TPM_RC_TYPE + RC_ActivateCredential_keyHandle; 5960// Command output 5961// Decrypt input credential data via asymmetric decryption. A 5962// TPM_RC_VALUE, TPM_RC_KEY or unmarshal errors may be returned at this 5963// point 5964result = CryptSecretDecrypt(in->keyHandle, NULL, 5965"IDENTITY", &in->secret, &data); 5966if(result != TPM_RC_SUCCESS) 5967{ 5968if(result == TPM_RC_KEY) 5969return TPM_RC_FAILURE; 5970 5971Family “2.0” 5972Level 00 Revision 00.99 5973 5974Published 5975Copyright © TCG 2006-2013 5976 5977Page 65 5978October 31, 2013 5979 5980 Part 3: Commands 598142 598243 598344 598445 598546 598647 598748 598849 598950 599051 599152 599253 599354 599455 599556 5996 5997Trusted Platform Module Library 5998 5999return RcSafeAddToResult(result, RC_ActivateCredential_secret); 6000} 6001// Retrieve secret data. A TPM_RC_INTEGRITY error or unmarshal 6002// errors may be returned at this point 6003result = CredentialToSecret(&in->credentialBlob, 6004&activateObject->name, 6005(TPM2B_SEED *) &data, 6006in->keyHandle, 6007&out->certInfo); 6008if(result != TPM_RC_SUCCESS) 6009return RcSafeAddToResult(result,RC_ActivateCredential_credentialBlob); 6010return TPM_RC_SUCCESS; 6011} 6012 6013Page 66 6014October 31, 2013 6015 6016Published 6017Copyright © TCG 2006-2013 6018 6019Family “2.0” 6020Level 00 Revision 00.99 6021 6022 Trusted Platform Module Library 6023 602414.6 6025 6026Part 3: Commands 6027 6028TPM2_MakeCredential 6029 603014.6.1 General Description 6031This command allows the TPM to perform the actions required of a Certificate Authority (CA) in creating a 6032TPM2B_ID_OBJECT containing an activation credential. 6033The TPM will produce a TPM_ID_OBJECT according to the methods in “Credential Protection” in Part 1. 6034The loaded public area referenced by handle is required to be the public area of a Storage key, 6035otherwise, the credential cannot be properly sealed. 6036This command does not use any TPM secrets nor does it require authorization. It is a convenience 6037function, using the TPM to perform cryptographic calculations that could be done externally. 6038 6039Family “2.0” 6040Level 00 Revision 00.99 6041 6042Published 6043Copyright © TCG 2006-2013 6044 6045Page 67 6046October 31, 2013 6047 6048 Part 3: Commands 6049 6050Trusted Platform Module Library 6051 605214.6.2 Command and Response 6053Table 29 — TPM2_MakeCredential Command 6054Type 6055 6056Name 6057 6058Description 6059 6060TPMI_ST_COMMAND_TAG 6061 6062tag 6063 6064UINT32 6065 6066commandSize 6067 6068TPM_CC 6069 6070commandCode 6071 6072TPM_CC_MakeCredential 6073 6074TPMI_DH_OBJECT 6075 6076handle 6077 6078loaded public area, used to encrypt the sensitive area 6079containing the credential key 6080Auth Index: None 6081 6082TPM2B_DIGEST 6083 6084credential 6085 6086the credential information 6087 6088TPM2B_NAME 6089 6090objectName 6091 6092Name of the object to which the credential applies 6093 6094Table 30 — TPM2_MakeCredential Response 6095Type 6096 6097Name 6098 6099Description 6100 6101TPM_ST 6102 6103tag 6104 6105see clause 8 6106 6107UINT32 6108 6109responseSize 6110 6111TPM_RC 6112 6113responseCode 6114 6115TPM2B_ID_OBJECT 6116 6117credentialBlob 6118 6119TPM2B_ENCRYPTED_SECRET 6120 6121secret 6122 6123Page 68 6124October 31, 2013 6125 6126the credential 6127handle algorithm-dependent data that wraps the key 6128that encrypts credentialBlob 6129 6130Published 6131Copyright © TCG 2006-2013 6132 6133Family “2.0” 6134Level 00 Revision 00.99 6135 6136 Trusted Platform Module Library 6137 6138Part 3: Commands 6139 614014.6.3 Detailed Actions 61411 61422 61433 6144 6145#include "InternalRoutines.h" 6146#include "MakeCredential_fp.h" 6147#include "Object_spt_fp.h" 6148Error Returns 6149TPM_RC_KEY 6150 6151handle referenced an ECC key that has a unique field that is not a 6152point on the curve of the key 6153 6154TPM_RC_SIZE 6155 6156credential is larger than the digest size of Name algorithm of handle 6157 6158TPM_RC_TYPE 61594 61605 61616 61627 61638 61649 616510 616611 616712 616813 616914 617015 617116 617217 617318 617419 617520 617621 617722 617823 617924 618025 618126 618227 618328 618429 618530 618631 618732 618833 618934 619035 619136 619237 619338 619439 619540 619641 619742 619843 619944 620045 620146 620247 6203 6204Meaning 6205 6206handle does not reference an asymmetric decryption key 6207 6208TPM_RC 6209TPM2_MakeCredential( 6210MakeCredential_In 6211MakeCredential_Out 6212 6213*in, 6214*out 6215 6216// IN: input parameter list 6217// OUT: output parameter list 6218 6219TPM_RC 6220 6221result = TPM_RC_SUCCESS; 6222 6223OBJECT 6224TPM2B_DATA 6225 6226*object; 6227data; 6228 6229) 6230{ 6231 6232// Input Validation 6233// Get object pointer 6234object = ObjectGet(in->handle); 6235// input key must be an asymmetric, restricted decryption key 6236// NOTE: Needs to be restricted to have a symmetric value. 6237if( 6238!CryptIsAsymAlgorithm(object->publicArea.type) 6239|| object->publicArea.objectAttributes.decrypt == CLEAR 6240|| object->publicArea.objectAttributes.restricted == CLEAR 6241) 6242return TPM_RC_TYPE + RC_MakeCredential_handle; 6243// The credential information may not be larger than the digest size used for 6244// the Name of the key associated with handle. 6245if(in->credential.t.size > CryptGetHashDigestSize(object->publicArea.nameAlg)) 6246return TPM_RC_SIZE + RC_MakeCredential_credential; 6247// Command Output 6248// Make encrypt key and its associated secret structure. 6249// Even though CrypeSecretEncrypt() may return 6250out->secret.t.size = sizeof(out->secret.t.secret); 6251result = CryptSecretEncrypt(in->handle, "IDENTITY", &data, &out->secret); 6252if(result != TPM_RC_SUCCESS) 6253return result; 6254// Prepare output credential data from secret 6255SecretToCredential(&in->credential, &in->objectName, (TPM2B_SEED *) &data, 6256in->handle, &out->credentialBlob); 6257return TPM_RC_SUCCESS; 6258} 6259 6260Family “2.0” 6261Level 00 Revision 00.99 6262 6263Published 6264Copyright © TCG 2006-2013 6265 6266Page 69 6267October 31, 2013 6268 6269 Part 3: Commands 6270 627114.7 6272 6273Trusted Platform Module Library 6274 6275TPM2_Unseal 6276 627714.7.1 General Description 6278This command returns the data in a loaded Sealed Data Object. 6279NOTE 6280 6281A random, TPM-generated, Sealed Data Object may be created by the TPM with TPM2_Create() or 6282TPM2_CreatePrimary() using the template for a Sealed Data Object. A Sealed Data Object is more 6283likely to be created externally and imported (TPM2_Import()) so that the data is not created by the 6284TPM. 6285 6286The returned value may be encrypted using authorization session encryption. 6287If either restricted, decrypt, or sign is SET in the attributes of itemHandle, then the TPM shall return 6288TPM_RC_ATTRIBUTES. If the type of itemHandle is not TPM_ALG_KEYEDHASH, then the TPM shall 6289return TPM_RC_TYPE. 6290 6291Page 70 6292October 31, 2013 6293 6294Published 6295Copyright © TCG 2006-2013 6296 6297Family “2.0” 6298Level 00 Revision 00.99 6299 6300 Trusted Platform Module Library 6301 6302Part 3: Commands 6303 630414.7.2 Command and Response 6305Table 31 — TPM2_Unseal Command 6306Type 6307 6308Name 6309 6310TPMI_ST_COMMAND_TAG 6311 6312Tag 6313 6314UINT32 6315 6316commandSize 6317 6318TPM_CC 6319 6320commandCode 6321 6322TPM_CC_Unseal 6323 6324TPMI_DH_OBJECT 6325 6326@itemHandle 6327 6328handle of a loaded data object 6329Auth Index: 1 6330Auth Role: USER 6331 6332Description 6333 6334Table 32 — TPM2_Unseal Response 6335Type 6336 6337Name 6338 6339Description 6340 6341TPM_ST 6342 6343tag 6344 6345see clause 8 6346 6347UINT32 6348 6349responseSize 6350 6351TPM_RC 6352 6353responseCode 6354 6355TPM2B_SENSITIVE_DATA 6356 6357outData 6358 6359Family “2.0” 6360Level 00 Revision 00.99 6361 6362unsealed data 6363Size of outData is limited to be no more than 128 octets. 6364 6365Published 6366Copyright © TCG 2006-2013 6367 6368Page 71 6369October 31, 2013 6370 6371 Part 3: Commands 6372 6373Trusted Platform Module Library 6374 637514.7.3 Detailed Actions 63761 63772 6378 6379#include "InternalRoutines.h" 6380#include "Unseal_fp.h" 6381Error Returns 6382TPM_RC_ATTRIBUTES 6383 6384itemHandle has wrong attributes 6385 6386TPM_RC_TYPE 63873 63884 63895 63906 63917 63928 63939 639410 639511 639612 639713 639814 639915 640016 640117 640218 640319 640420 640521 640622 640723 640824 640925 641026 641127 641228 6413 6414Meaning 6415 6416itemHandle is not a KEYEDHASH data object 6417 6418TPM_RC 6419TPM2_Unseal(Unseal_In *in, Unseal_Out *out) 6420{ 6421OBJECT 6422 6423*object; 6424 6425// Input Validation 6426// Get pointer to loaded object 6427object = ObjectGet(in->itemHandle); 6428// Input handle must be a data object 6429if(object->publicArea.type != TPM_ALG_KEYEDHASH) 6430return TPM_RC_TYPE + RC_Unseal_itemHandle; 6431if( 6432object->publicArea.objectAttributes.decrypt == SET 6433|| object->publicArea.objectAttributes.sign == SET 6434|| object->publicArea.objectAttributes.restricted == SET) 6435return TPM_RC_ATTRIBUTES + RC_Unseal_itemHandle; 6436// Command Output 6437// Copy data 6438MemoryCopy2B(&out->outData.b, &object->sensitive.sensitive.bits.b, 6439sizeof(out->outData.t.buffer)); 6440return TPM_RC_SUCCESS; 6441} 6442 6443Page 72 6444October 31, 2013 6445 6446Published 6447Copyright © TCG 2006-2013 6448 6449Family “2.0” 6450Level 00 Revision 00.99 6451 6452 Trusted Platform Module Library 6453 645414.8 6455 6456Part 3: Commands 6457 6458TPM2_ObjectChangeAuth 6459 646014.8.1 General Description 6461This command is used to change the authorization secret for a TPM-resident object. 6462If successful, a new private area for the TPM-resident object associated with objectHandle is returned, 6463which includes the new authorization value. 6464This command does not change the authorization of the TPM-resident object on which it operates. 6465Therefore, the old authValue (of the TPM-resident object) is used when generating the response HMAC 6466key if required.. 6467NOTE 1 6468 6469The returned outPrivate will need to be loaded before the new authorization will apply. 6470 6471NOTE 2 6472 6473The TPM-resident object may be persistent and changing the authorization value of the persistent 6474object could prevent other users from accessing the object. This is why this command does not 6475change the TPM-resident object. 6476 6477EXAMPLE 6478 6479If a persistent key is being used as a Storage Root Key and the authorization of the key is a well known value so that the key can be used generally, then changing the authorization value in the 6480persistent key would deny access to other users. 6481 6482This command may not be used to change the authorization value for an NV Index or a Primary Object. 6483NOTE 3 6484 6485If an NV Index is to have a new authorization, it is done with TPM2_NV_ChangeAuth(). 6486 6487NOTE 4 6488 6489If a Primary Object is to have a new authorization, it needs to be recreated (TPM2_CreatePrimary()). 6490 6491Family “2.0” 6492Level 00 Revision 00.99 6493 6494Published 6495Copyright © TCG 2006-2013 6496 6497Page 73 6498October 31, 2013 6499 6500 Part 3: Commands 6501 6502Trusted Platform Module Library 6503 650414.8.2 Command and Response 6505Table 33 — TPM2_ObjectChangeAuth Command 6506Type 6507 6508Name 6509 6510Description 6511 6512TPMI_ST_COMMAND_TAG 6513 6514tag 6515 6516UINT32 6517 6518commandSize 6519 6520TPM_CC 6521 6522commandCode 6523 6524TPM_CC_ObjectChangeAuth 6525 6526TPMI_DH_OBJECT 6527 6528@objectHandle 6529 6530handle of the object 6531Auth Index: 1 6532Auth Role: ADMIN 6533 6534TPMI_DH_OBJECT 6535 6536parentHandle 6537 6538handle of the parent 6539Auth Index: None 6540 6541TPM2B_AUTH 6542 6543newAuth 6544 6545new authorization value 6546 6547Table 34 — TPM2_ObjectChangeAuth Response 6548Type 6549 6550Name 6551 6552Description 6553 6554TPM_ST 6555 6556tag 6557 6558see clause 8 6559 6560UINT32 6561 6562responseSize 6563 6564TPM_RC 6565 6566responseCode 6567 6568TPM2B_PRIVATE 6569 6570outPrivate 6571 6572Page 74 6573October 31, 2013 6574 6575private area containing the new authorization value 6576 6577Published 6578Copyright © TCG 2006-2013 6579 6580Family “2.0” 6581Level 00 Revision 00.99 6582 6583 Trusted Platform Module Library 6584 6585Part 3: Commands 6586 658714.8.3 Detailed Actions 65881 65892 65903 6591 6592#include "InternalRoutines.h" 6593#include "ObjectChangeAuth_fp.h" 6594#include "Object_spt_fp.h" 6595Error Returns 6596TPM_RC_SIZE 6597 6598newAuth is larger than the size of the digest of the Name algorithm of 6599objectHandle 6600 6601TPM_RC_TYPE 6602 66034 66045 66056 66067 66078 66089 660910 661011 661112 661213 661314 661415 661516 661617 661718 661819 661920 662021 662122 662223 662324 662425 662526 662627 662728 662829 662930 663031 663132 663233 663334 663435 663536 663637 663738 663839 663940 664041 664142 664243 664344 664445 664546 664647 664748 664849 664950 665051 6651 6652Meaning 6653 6654the key referenced by parentHandle is not the parent of the object 6655referenced by objectHandle; or objectHandle is a sequence object. 6656 6657TPM_RC 6658TPM2_ObjectChangeAuth( 6659ObjectChangeAuth_In 6660ObjectChangeAuth_Out 6661 6662*in, 6663*out 6664 6665// IN: input parameter list 6666// OUT: output parameter list 6667 6668) 6669{ 6670TPMT_SENSITIVE 6671OBJECT 6672TPM2B_NAME 6673TPM2B_NAME 6674 6675sensitive; 6676*object; 6677objectQN, QNCompare; 6678parentQN; 6679 6680// Input Validation 6681// Get object pointer 6682object = ObjectGet(in->objectHandle); 6683// Can not change auth on sequence object 6684if(ObjectIsSequence(object)) 6685return TPM_RC_TYPE + RC_ObjectChangeAuth_objectHandle; 6686// Make sure that the auth value is consistent with the nameAlg 6687if( MemoryRemoveTrailingZeros(&in->newAuth) 6688> CryptGetHashDigestSize(object->publicArea.nameAlg)) 6689return TPM_RC_SIZE + RC_ObjectChangeAuth_newAuth; 6690// Check parent for object 6691// parent handle must be the parent of object handle. In this 6692// implementation we verify this by checking the QN of object. Other 6693// implementation may choose different method to verify this attribute. 6694ObjectGetQualifiedName(in->parentHandle, &parentQN); 6695ObjectComputeQualifiedName(&parentQN, object->publicArea.nameAlg, 6696&object->name, &QNCompare); 6697ObjectGetQualifiedName(in->objectHandle, &objectQN); 6698if(!Memory2BEqual(&objectQN.b, &QNCompare.b)) 6699return TPM_RC_TYPE + RC_ObjectChangeAuth_parentHandle; 6700// Command Output 6701// Copy internal sensitive area 6702sensitive = object->sensitive; 6703// Copy authValue 6704sensitive.authValue = in->newAuth; 6705// Prepare output private data from sensitive 6706SensitiveToPrivate(&sensitive, &object->name, in->parentHandle, 6707 6708Family “2.0” 6709Level 00 Revision 00.99 6710 6711Published 6712Copyright © TCG 2006-2013 6713 6714Page 75 6715October 31, 2013 6716 6717 Part 3: Commands 671852 671953 672054 672155 672256 6723 6724Trusted Platform Module Library 6725object->publicArea.nameAlg, 6726&out->outPrivate); 6727 6728return TPM_RC_SUCCESS; 6729} 6730 6731Page 76 6732October 31, 2013 6733 6734Published 6735Copyright © TCG 2006-2013 6736 6737Family “2.0” 6738Level 00 Revision 00.99 6739 6740 Trusted Platform Module Library 6741 674215 6743 6744Part 3: Commands 6745 6746Duplication Commands 6747 674815.1 6749 6750TPM2_Duplicate 6751 675215.1.1 General Description 6753This command duplicates a loaded object so that it may be used in a different hierarchy. The new parent 6754key for the duplicate may be on the same or different TPM or TPM_RH_NULL. Only the public area of 6755newParentHandle is required to be loaded. 6756NOTE 1 6757 6758Since the new parent may only be extant on a different TPM, it is likely that the new parent’s 6759sensitive area could not be loaded in the TPM from which objectHandle is being duplicated. 6760 6761If encryptedDuplication is SET in the object being duplicated, then the TPM shall return 6762TPM_RC_SYMMETRIC if symmetricAlg is TPM_RH_NULL or TPM_RC_HIERARCHY if 6763newParentHandle is TPM_RH_NULL. 6764The authorization for this command shall be with a policy session. 6765If fixedParent of objectHandle→attributes is SET, the TPM shall return TPM_RC_ATTRIBUTES. If 6766objectHandle→nameAlg is TPM_ALG_NULL, the TPM shall return TPM_RC_TYPE. 6767The policySession→commandCode parameter in the policy session is required to be TPM_CC_Duplicate 6768to indicate that authorization for duplication has been provided. This indicates that the policy that is being 6769used is a policy that is for duplication, and not a policy that would approve another use. That is, authority 6770to use an object does not grant authority to duplicate the object. 6771The policy is likely to include cpHash in order to restrict where duplication can occur. 6772If 6773TPM2_PolicyCpHash() has been executed as part of the policy, the policySession→cpHash is compared 6774to the cpHash of the command. 6775If TPM2_PolicyDuplicationSelect() has 6776policySession→nameHash is compared to 6777 6778been 6779 6780executed 6781 6782as 6783 6784part 6785 6786of 6787 6788the 6789 6790policy, 6791 6792HpolicyAlg(objectHandle→Name || newParentHandle→Name) 6793 6794the 6795(2) 6796 6797If the compared hashes are not the same, then the TPM shall return TPM_RC_POLICY_FAIL. 6798NOTE 2 6799 6800It is allowed that policySesion→nameHash and policySession→cpHash share the same memory 6801space. 6802 6803NOTE 3 6804 6805A duplication policy is not required to have either TPM2_PolicyDuplicationSelect() or 6806TPM2_PolicyCpHash() as part of the policy. If neither is present, then the duplication policy may be 6807satisfied with a policy that only contains TPM2_PolicyCommaneCode( code = TPM_CC_Duplicate). 6808 6809The TPM shall follow the process of encryption defined in the “Duplication” subclause of “Protected 6810Storage Hierarchy” in Part 1 of this specification. 6811 6812Family “2.0” 6813Level 00 Revision 00.99 6814 6815Published 6816Copyright © TCG 2006-2013 6817 6818Page 77 6819October 31, 2013 6820 6821 Part 3: Commands 6822 6823Trusted Platform Module Library 6824 682515.1.2 Command and Response 6826Table 35 — TPM2_Duplicate Command 6827Type 6828 6829Name 6830 6831Description 6832 6833TPMI_ST_COMMAND_TAG 6834 6835tag 6836 6837UINT32 6838 6839commandSize 6840 6841TPM_CC 6842 6843commandCode 6844 6845TPM_CC_Duplicate 6846 6847TPMI_DH_OBJECT 6848 6849@objectHandle 6850 6851loaded object to duplicate 6852Auth Index: 1 6853Auth Role: DUP 6854 6855TPMI_DH_OBJECT+ 6856 6857newParentHandle 6858 6859shall reference the public area of an asymmetric key 6860Auth Index: None 6861 6862TPM2B_DATA 6863 6864encryptionKeyIn 6865 6866optional symmetric encryption key 6867The size for this key is set to zero when the TPM is to 6868generate the key. This parameter may be encrypted. 6869 6870TPMT_SYM_DEF_OBJECT+ 6871 6872symmetricAlg 6873 6874definition for the symmetric algorithm to be used for the 6875inner wrapper 6876may be TPM_ALG_NULL if no inner wrapper is applied 6877 6878Table 36 — TPM2_Duplicate Response 6879Type 6880 6881Name 6882 6883Description 6884 6885TPM_ST 6886 6887tag 6888 6889see clause 8 6890 6891UINT32 6892 6893responseSize 6894 6895TPM_RC 6896 6897responseCode 6898 6899TPM2B_DATA 6900 6901encryptionKeyOut 6902 6903If the caller provided an encryption key or if 6904symmetricAlg was TPM_ALG_NULL, then this will be 6905the Empty Buffer; otherwise, it shall contain the TPMgenerated, symmetric encryption key for the inner 6906wrapper. 6907 6908TPM2B_PRIVATE 6909 6910duplicate 6911 6912private area that may be encrypted by encryptionKeyIn; 6913and may be doubly encrypted 6914 6915TPM2B_ENCRYPTED_SECRET 6916 6917outSymSeed 6918 6919Page 78 6920October 31, 2013 6921 6922seed protected by the asymmetric algorithms of new 6923parent (NP) 6924 6925Published 6926Copyright © TCG 2006-2013 6927 6928Family “2.0” 6929Level 00 Revision 00.99 6930 6931 Trusted Platform Module Library 6932 6933Part 3: Commands 6934 693515.1.3 Detailed Actions 69361 69372 69383 6939 6940#include "InternalRoutines.h" 6941#include "Duplicate_fp.h" 6942#include "Object_spt_fp.h" 6943Error Returns 6944TPM_RC_ATTRIBUTES 6945 6946key to duplicate has fixedParent SET 6947 6948TPM_RC_HIERARCHY 6949 6950encryptedDuplication is SET and newParentHandle specifies Null 6951Hierarchy 6952 6953TPM_RC_KEY 6954 6955newParentHandle references invalid ECC key (public point not on the 6956curve) 6957 6958TPM_RC_SIZE 6959 6960input encryption key size does not match the size specified in 6961symmetric algorithm 6962 6963TPM_RC_SYMMETRIC 6964 6965encryptedDuplication is SET but no symmetric algorithm is provided 6966 6967TPM_RC_TYPE 6968 69694 69705 69716 69727 69738 69749 697510 697611 697712 697813 697914 698015 698116 698217 698318 698419 698520 698621 698722 698823 698924 699025 699126 699227 699328 699429 699530 699631 699732 699833 699934 700035 700136 700237 700338 700439 700540 700641 700742 7008 7009Meaning 7010 7011newParentHandle is neither a storage key nor TPM_RH_NULL; or 7012the object has a NULL nameAlg 7013 7014TPM_RC 7015TPM2_Duplicate( 7016Duplicate_In 7017Duplicate_Out 7018 7019*in, 7020*out 7021 7022// IN: input parameter list 7023// OUT: output parameter list 7024 7025) 7026{ 7027TPM_RC 7028TPMT_SENSITIVE 7029 7030result = TPM_RC_SUCCESS; 7031sensitive; 7032 7033UINT16 7034 7035innerKeySize = 0; // encrypt key size for inner wrap 7036 7037OBJECT 7038TPM2B_DATA 7039 7040*object; 7041data; 7042 7043// Input Validation 7044// Get duplicate object pointer 7045object = ObjectGet(in->objectHandle); 7046// duplicate key must have fixParent bit CLEAR. 7047if(object->publicArea.objectAttributes.fixedParent == SET) 7048return TPM_RC_ATTRIBUTES + RC_Duplicate_objectHandle; 7049// Do not duplicate object with NULL nameAlg 7050if(object->publicArea.nameAlg == TPM_ALG_NULL) 7051return TPM_RC_TYPE + RC_Duplicate_objectHandle; 7052// new parent key must be a storage object or TPM_RH_NULL 7053if(in->newParentHandle != TPM_RH_NULL 7054&& !ObjectIsStorage(in->newParentHandle)) 7055return TPM_RC_TYPE + RC_Duplicate_newParentHandle; 7056// If the duplicates object has encryptedDuplication SET, then there must be 7057// an inner wrapper and the new parent may not be TPM_RH_NULL 7058if(object->publicArea.objectAttributes.encryptedDuplication == SET) 7059{ 7060if(in->symmetricAlg.algorithm == TPM_ALG_NULL) 7061return TPM_RC_SYMMETRIC + RC_Duplicate_symmetricAlg; 7062if(in->newParentHandle == TPM_RH_NULL) 7063 7064Family “2.0” 7065Level 00 Revision 00.99 7066 7067Published 7068Copyright © TCG 2006-2013 7069 7070Page 79 7071October 31, 2013 7072 7073 Part 3: Commands 707443 707544 707645 707746 707847 707948 708049 708150 708251 708352 708453 708554 708655 708756 708857 708958 709059 709160 709261 709362 709463 709564 709665 709766 709867 709968 710069 710170 710271 710372 710473 710574 710675 710776 710877 710978 711079 711180 711281 711382 711483 711584 711685 711786 711887 711988 712089 712190 712291 712392 712493 712594 712695 712796 7128 7129Trusted Platform Module Library 7130 7131return TPM_RC_HIERARCHY + RC_Duplicate_newParentHandle; 7132} 7133if(in->symmetricAlg.algorithm == TPM_ALG_NULL) 7134{ 7135// if algorithm is TPM_ALG_NULL, input key size must be 0 7136if(in->encryptionKeyIn.t.size != 0) 7137return TPM_RC_SIZE + RC_Duplicate_encryptionKeyIn; 7138} 7139else 7140{ 7141// Get inner wrap key size 7142innerKeySize = in->symmetricAlg.keyBits.sym; 7143// If provided the input symmetric key must match the size of the algorithm 7144if(in->encryptionKeyIn.t.size != 0 7145&& in->encryptionKeyIn.t.size != (innerKeySize + 7) / 8) 7146return TPM_RC_SIZE + RC_Duplicate_encryptionKeyIn; 7147} 7148// Command Output 7149if(in->newParentHandle != TPM_RH_NULL) 7150{ 7151// Make encrypt key and its associated secret structure. A TPM_RC_KEY 7152// error may be returned at this point 7153out->outSymSeed.t.size = sizeof(out->outSymSeed.t.secret); 7154result = CryptSecretEncrypt(in->newParentHandle, 7155"DUPLICATE", &data, &out->outSymSeed); 7156pAssert(result != TPM_RC_VALUE); 7157if(result != TPM_RC_SUCCESS) 7158return result; 7159} 7160else 7161{ 7162// Do not apply outer wrapper 7163data.t.size = 0; 7164out->outSymSeed.t.size = 0; 7165} 7166// Copy sensitive area 7167sensitive = object->sensitive; 7168// Prepare output private data from sensitive 7169SensitiveToDuplicate(&sensitive, &object->name, in->newParentHandle, 7170object->publicArea.nameAlg, (TPM2B_SEED *) &data, 7171&in->symmetricAlg, &in->encryptionKeyIn, 7172&out->duplicate); 7173out->encryptionKeyOut = in->encryptionKeyIn; 7174return TPM_RC_SUCCESS; 7175} 7176 7177Page 80 7178October 31, 2013 7179 7180Published 7181Copyright © TCG 2006-2013 7182 7183Family “2.0” 7184Level 00 Revision 00.99 7185 7186 Trusted Platform Module Library 7187 718815.2 7189 7190Part 3: Commands 7191 7192TPM2_Rewrap 7193 719415.2.1 General Description 7195This command allows the TPM to serve in the role as a Duplication Authority. If proper authorization for 7196use of the oldParent is provided, then an HMAC key and a symmetric key are recovered from inSymSeed 7197and used to integrity check and decrypt inDuplicate. A new protection seed value is generated according 7198to the methods appropriate for newParent and the blob is re-encrypted and a new integrity value is 7199computed. The re-encrypted blob is returned in outDuplicate and the symmetric key returned in 7200outSymKey. 7201In the rewrap process, L is “DUPLICATE” (see “Terms and Definitions” in Part 1). 7202If inSymSeed has a zero length, then oldParent is required to be TPM_RH_NULL and no decryption of 7203inDuplicate takes place. 7204If newParent is TPM_RH_NULL, then no encryption is performed on outDuplicate. outSymSeed will have 7205a zero length. See Part 2 encryptedDuplication. 7206 7207Family “2.0” 7208Level 00 Revision 00.99 7209 7210Published 7211Copyright © TCG 2006-2013 7212 7213Page 81 7214October 31, 2013 7215 7216 Part 3: Commands 7217 7218Trusted Platform Module Library 7219 722015.2.2 Command and Response 7221Table 37 — TPM2_Rewrap Command 7222Type 7223 7224Name 7225 7226TPMI_ST_COMMAND_TAG 7227 7228tag 7229 7230UINT32 7231 7232commandSize 7233 7234TPM_CC 7235 7236commandCode 7237 7238TPM_CC_Rewrap 7239 7240TPMI_DH_OBJECT+ 7241 7242@oldParent 7243 7244parent of object 7245Auth Index: 1 7246Auth Role: User 7247 7248TPMI_DH_OBJECT+ 7249 7250newParent 7251 7252new parent of the object 7253Auth Index: None 7254 7255TPM2B_PRIVATE 7256 7257inDuplicate 7258 7259an object encrypted using symmetric key derived from 7260inSymSeed 7261 7262TPM2B_NAME 7263 7264name 7265 7266the Name of the object being rewrapped 7267 7268TPM2B_ENCRYPTED_SECRET 7269 7270inSymSeed 7271 7272Description 7273 7274seed for symmetric key 7275needs oldParent private key to recover the seed and 7276generate the symmetric key 7277 7278Table 38 — TPM2_Rewrap Response 7279Type 7280 7281Name 7282 7283Description 7284 7285TPM_ST 7286 7287tag 7288 7289see clause 8 7290 7291UINT32 7292 7293responseSize 7294 7295TPM_RC 7296 7297responseCode 7298 7299TPM2B_PRIVATE 7300 7301outDuplicate 7302 7303TPM2B_ENCRYPTED_SECRET 7304 7305outSymSeed 7306 7307Page 82 7308October 31, 2013 7309 7310an object encrypted using symmetric key derived from 7311outSymSeed 7312seed for a symmetric key protected by newParent 7313asymmetric key 7314 7315Published 7316Copyright © TCG 2006-2013 7317 7318Family “2.0” 7319Level 00 Revision 00.99 7320 7321 Trusted Platform Module Library 7322 7323Part 3: Commands 7324 732515.2.3 Detailed Actions 73261 73272 73283 7329 7330#include "InternalRoutines.h" 7331#include "Rewrap_fp.h" 7332#include "Object_spt_fp.h" 7333Error Returns 7334TPM_RC_ATTRIBUTES 7335 7336newParent is not a decryption key 7337 7338TPM_RC_HANDLE 7339 7340oldParent does not consistent with inSymSeed 7341 7342TPM_RC_INTEGRITY 7343 7344the integrity check of inDuplicate failed 7345 7346TPM_RC_KEY 7347 7348for an ECC key, the public key is not on the curve of the curve ID 7349 7350TPM_RC_KEY_SIZE 7351 7352the decrypted input symmetric key size does not matches the 7353symmetric algorithm key size of oldParent 7354 7355TPM_RC_TYPE 7356 7357oldParent is not a storage key, or 'newParent is not a storage key 7358 7359TPM_RC_VALUE 7360 7361for an 'oldParent; RSA key, the data to be decrypted is greater than 7362the public exponent 7363 7364Unmarshal errors 7365 73664 73675 73686 73697 73708 73719 737210 737311 737412 737513 737614 737715 737816 737917 738018 738119 738220 738321 738422 738523 738624 738725 738826 738927 739028 739129 739230 739331 739432 739533 739634 739735 739836 739937 740038 740139 7402 7403Meaning 7404 7405errors during unmarshaling the input encrypted buffer to a ECC public 7406key, or unmarshal the private buffer to sensitive 7407 7408TPM_RC 7409TPM2_Rewrap( 7410Rewrap_In 7411Rewrap_Out 7412 7413*in, 7414*out 7415 7416// IN: input parameter list 7417// OUT: output parameter list 7418 7419TPM_RC 7420OBJECT 7421TPM2B_DATA 7422UINT16 7423TPM2B_PRIVATE 7424 7425result = TPM_RC_SUCCESS; 7426*oldParent; 7427data; 7428// symmetric key 7429hashSize = 0; 7430privateBlob; 7431// A temporary private blob 7432// to transit between old 7433// and new wrappers 7434 7435) 7436{ 7437 7438// Input Validation 7439if((in->inSymSeed.t.size == 0 && in->oldParent != TPM_RH_NULL) 7440|| (in->inSymSeed.t.size != 0 && in->oldParent == TPM_RH_NULL)) 7441return TPM_RC_HANDLE + RC_Rewrap_oldParent; 7442if(in->oldParent != TPM_RH_NULL) 7443{ 7444// Get old parent pointer 7445oldParent = ObjectGet(in->oldParent); 7446// old parent key must be a storage object 7447if(!ObjectIsStorage(in->oldParent)) 7448return TPM_RC_TYPE + RC_Rewrap_oldParent; 7449// Decrypt input secret data via asymmetric decryption. A 7450// TPM_RC_VALUE, TPM_RC_KEY or unmarshal errors may be returned at this 7451// point 7452result = CryptSecretDecrypt(in->oldParent, NULL, 7453"DUPLICATE", &in->inSymSeed, &data); 7454if(result != TPM_RC_SUCCESS) 7455return TPM_RC_VALUE + RC_Rewrap_inSymSeed; 7456 7457Family “2.0” 7458Level 00 Revision 00.99 7459 7460Published 7461Copyright © TCG 2006-2013 7462 7463Page 83 7464October 31, 2013 7465 7466 Part 3: Commands 746740 746841 746942 747043 747144 747245 747346 747447 747548 747649 747750 747851 747952 748053 748154 748255 748356 748457 748558 748659 748760 748861 748962 749063 749164 749265 749366 749467 749568 749669 749770 749871 749972 750073 750174 750275 750376 750477 750578 750679 750780 750881 750982 751083 751184 751285 751386 751487 751588 751689 751790 751891 751992 752093 752194 752295 752396 752497 752598 752699 7527100 7528101 7529102 7530103 7531 7532Trusted Platform Module Library 7533 7534// Unwrap Outer 7535result = UnwrapOuter(in->oldParent, &in->name, 7536oldParent->publicArea.nameAlg, (TPM2B_SEED *) &data, 7537FALSE, 7538in->inDuplicate.t.size, in->inDuplicate.t.buffer); 7539if(result != TPM_RC_SUCCESS) 7540return RcSafeAddToResult(result, RC_Rewrap_inDuplicate); 7541// Copy unwrapped data to temporary variable, remove the integrity field 7542hashSize = sizeof(UINT16) + 7543CryptGetHashDigestSize(oldParent->publicArea.nameAlg); 7544privateBlob.t.size = in->inDuplicate.t.size - hashSize; 7545MemoryCopy(privateBlob.t.buffer, in->inDuplicate.t.buffer + hashSize, 7546privateBlob.t.size, sizeof(privateBlob.t.buffer)); 7547} 7548else 7549{ 7550// No outer wrap from input blob. 7551privateBlob = in->inDuplicate; 7552} 7553 7554Direct copy. 7555 7556if(in->newParent != TPM_RH_NULL) 7557{ 7558OBJECT 7559*newParent; 7560newParent = ObjectGet(in->newParent); 7561// New parent must be a storage object 7562if(!ObjectIsStorage(in->newParent)) 7563return TPM_RC_TYPE + RC_Rewrap_newParent; 7564// Make new encrypt key and its associated secret structure. A 7565// TPM_RC_VALUE error may be returned at this point if RSA algorithm is 7566// enabled in TPM 7567out->outSymSeed.t.size = sizeof(out->outSymSeed.t.secret); 7568result = CryptSecretEncrypt(in->newParent, 7569"DUPLICATE", &data, &out->outSymSeed); 7570if(result != TPM_RC_SUCCESS) return result; 7571// Command output 7572// Copy temporary variable to output, reserve the space for integrity 7573hashSize = sizeof(UINT16) + 7574CryptGetHashDigestSize(newParent->publicArea.nameAlg); 7575out->outDuplicate.t.size = privateBlob.t.size; 7576MemoryCopy(out->outDuplicate.t.buffer + hashSize, privateBlob.t.buffer, 7577privateBlob.t.size, sizeof(out->outDuplicate.t.buffer)); 7578// Produce outer wrapper for output 7579out->outDuplicate.t.size = ProduceOuterWrap(in->newParent, &in->name, 7580newParent->publicArea.nameAlg, 7581(TPM2B_SEED *) &data, 7582FALSE, 7583out->outDuplicate.t.size, 7584out->outDuplicate.t.buffer); 7585} 7586else // New parent is a null key so there is no seed 7587{ 7588out->outSymSeed.t.size = 0; 7589// Copy privateBlob directly 7590out->outDuplicate = privateBlob; 7591} 7592 7593Page 84 7594October 31, 2013 7595 7596Published 7597Copyright © TCG 2006-2013 7598 7599Family “2.0” 7600Level 00 Revision 00.99 7601 7602 Trusted Platform Module Library 7603104 7604105 7605 7606Part 3: Commands 7607 7608return TPM_RC_SUCCESS; 7609} 7610 7611Family “2.0” 7612Level 00 Revision 00.99 7613 7614Published 7615Copyright © TCG 2006-2013 7616 7617Page 85 7618October 31, 2013 7619 7620 Part 3: Commands 7621 762215.3 7623 7624Trusted Platform Module Library 7625 7626TPM2_Import 7627 762815.3.1 General Description 7629This command allows an object to be encrypted using the symmetric encryption values of a Storage Key. 7630After encryption, the object may be loaded and used in the new hierarchy. The imported object (duplicate) 7631may be singly encrypted, multiply encrypted, or unencrypted. 7632If fixedTPM or fixedParent is SET in objectPublic, the TPM shall return TPM_RC_ATTRIBUTES. 7633If encryptedDuplication is SET in the object referenced by parentHandle, then encryptedDuplication shall 7634be set in objectPublic (TPM_RC_ATTRIBUTES). However, see Note 2. 7635Recovery of the sensitive data of the object occurs in the TPM in a three-step process in the following 7636order: 7637 7638 7639If present, the outer layer of symmetric encryption is removed. If inSymSeed has a non-zero size, the 7640asymmetric parameters and private key of parentHandle are used to recover the seed used in the 7641creation of the HMAC key and encryption keys used to protect the duplication blob. When recovering 7642the seed, L is “DUPLICATE”. 7643NOTE 1 7644 7645If the encryptedDuplication attribute of the object 7646TPM_RC_ATTRIBUTES if inSymSeed is an empty buffer. 7647 7648is 7649 7650SET, 7651 7652the 7653 7654TPM 7655 7656shall 7657 7658return 7659 7660 7661 7662If present, the inner layer of symmetric encryption is removed. If encryptionKey and symmetricAlg are 7663provided, they are used to decrypt duplication. 7664 7665 7666 7667If present, the integrity value of the blob is checked. The presence of the integrity value is indicated 7668by a non-zero value for duplicate.data.integrity.size. The integrity of the private area is validated using 7669the Name of objectPublic in the integrity HMAC computation. If either the outer layer or inner layer of 7670encryption is performed, then the integrity value shall be present. 7671 7672If the inner or outer wrapper is present, then a valid integrity value shall be present or the TPM shall 7673return TPM_RC_INTEGRITY. 7674NOTE 2 7675 7676It is not necessary to validate that the sensitive area data is cryptographically bound to the public 7677area other than that the Name of the public area is included in the HMAC. However, if the binding is 7678not validated by this command, the binding must be checked each time the object is loaded. For an 7679object that is imported under a parent with fixedTPM SET, binding need only be checked at import. If 7680the parent has fixedTPM CLEAR, then the binding needs to be checked each time the object is 7681loaded, or before the TPM performs an operation for which the binding affects the outcome of the 7682operation (for example, TPM2_PolicySigned() or TPM2_Certify()). 7683Similarly, if the new parent's fixedTPM is set, the encryptedDuplication state need only be checked 7684at import. 7685If the new parent is not fixedTPM, then that object will be loadable on any TPM (including SW 7686versions) on which the new parent exists. This means that, each time an object is loaded under a 7687parent that is not fixedTPM, it is necessary to validate all of the properties of that object. If the 7688parent is fixedTPM, then the new private blob is integrity protected by the TPM that “owns” the 7689parent. So, it is sufficient to validate the object’s properties (attribute and public -private binding) on 7690import and not again. 7691 7692Before duplicate.buffer is decrypted using the symmetric key of the parent, the integrity value shall be 7693checked before the sensitive area is used, or unmarshaled. 7694After integrity checks and decryption, the TPM will create a new symmetrically encrypted private area 7695using the encryption key of the parent. 7696NOTE 3 7697 7698Checking the integrity before the data is used prevents attacks on the sensitive area by fuzzing the 7699data and looking at the differences in the response codes. 7700 7701Page 86 7702October 31, 2013 7703 7704Published 7705Copyright © TCG 2006-2013 7706 7707Family “2.0” 7708Level 00 Revision 00.99 7709 7710 Trusted Platform Module Library 7711NOTE 4 7712 7713Part 3: Commands 7714 7715The symmetric re-encryption is the normal integrity generation and symmetric encryption applied to 7716a child object. 7717 7718Family “2.0” 7719Level 00 Revision 00.99 7720 7721Published 7722Copyright © TCG 2006-2013 7723 7724Page 87 7725October 31, 2013 7726 7727 Part 3: Commands 7728 7729Trusted Platform Module Library 7730 773115.3.2 Command and Response 7732Table 39 — TPM2_Import Command 7733Type 7734 7735Name 7736 7737TPMI_ST_COMMAND_TAG 7738 7739tag 7740 7741UINT32 7742 7743commandSize 7744 7745TPM_CC 7746 7747commandCode 7748 7749TPM_CC_Import 7750 7751TPMI_DH_OBJECT 7752 7753@parentHandle 7754 7755the handle of the new parent for the object 7756Auth Index: 1 7757Auth Role: USER 7758 7759TPM2B_DATA 7760 7761encryptionKey 7762 7763the optional symmetric encryption key used as the inner 7764wrapper for duplicate 7765If symmetricAlg is TPM_ALG_NULL, then this 7766parameter shall be the Empty Buffer. 7767 7768TPM2B_PUBLIC 7769 7770objectPublic 7771 7772Description 7773 7774the public area of the object to be imported 7775This is provided so that the integrity value for duplicate 7776and the object attributes can be checked. 7777NOTE 7778 7779TPM2B_PRIVATE 7780 7781duplicate 7782 7783Even if the integrity value of the object is not 7784checked on input, the object Name is required to 7785create the integrity value for the imported object. 7786 7787the symmetrically encrypted duplicate object that may 7788contain an inner symmetric wrapper 7789 7790TPM2B_ENCRYPTED_SECRET 7791inSymSeed 7792 7793symmetric key used to encrypt duplicate 7794inSymSeed is encrypted/encoded using the algorithms 7795of newParent. 7796 7797TPMT_SYM_DEF_OBJECT+ 7798 7799symmetricAlg 7800 7801definition for the symmetric algorithm to use for the inner 7802wrapper 7803If this algorithm is TPM_ALG_NULL, no inner wrapper is 7804present and encryptionKey shall be the Empty Buffer. 7805 7806Table 40 — TPM2_Import Response 7807Type 7808 7809Name 7810 7811Description 7812 7813TPM_ST 7814 7815tag 7816 7817see clause 8 7818 7819UINT32 7820 7821responseSize 7822 7823TPM_RC 7824 7825responseCode 7826 7827TPM2B_PRIVATE 7828 7829outPrivate 7830 7831Page 88 7832October 31, 2013 7833 7834the sensitive area encrypted with the symmetric key of 7835parentHandle 7836 7837Published 7838Copyright © TCG 2006-2013 7839 7840Family “2.0” 7841Level 00 Revision 00.99 7842 7843 Trusted Platform Module Library 7844 7845Part 3: Commands 7846 784715.3.3 Detailed Actions 78481 78492 78503 7851 7852#include "InternalRoutines.h" 7853#include "Import_fp.h" 7854#include "Object_spt_fp.h" 7855Error Returns 7856 7857Meaning 7858 7859TPM_RC_ASYMMETRIC 7860 7861non-duplicable storage key represented by objectPublic and its 7862parent referenced by parentHandle have different public params 7863 7864TPM_RC_ATTRIBUTES 7865 7866attributes FixedTPM and fixedParent of objectPublic are not both 7867CLEAR; or inSymSeed is nonempty and parentHandle does not 7868reference a decryption key; or objectPublic and parentHandle have 7869incompatible or inconsistent attributes 7870 7871TPM_RC_BINDING 7872 7873duplicate and objectPublic are not cryptographically bound 7874 7875TPM_RC_ECC_POINT 7876 7877inSymSeed is nonempty and ECC point in inSymSeed is not on the 7878curve 7879 7880TPM_RC_HASH 7881 7882non-duplicable storage key represented by objectPublic and its 7883parent referenced by parentHandle have different name algorithm 7884 7885TPM_RC_INSUFFICIENT 7886 7887inSymSeed is nonempty and failed to retrieve ECC point from the 7888secret; or unmarshaling sensitive value from duplicate failed the 7889result of inSymSeed decryption 7890 7891TPM_RC_INTEGRITY 7892 7893duplicate integrity is broken 7894 7895TPM_RC_KDF 7896 7897objectPublic representing decrypting keyed hash object specifies 7898invalid KDF 7899 7900TPM_RC_KEY 7901 7902inconsistent parameters of objectPublic; or inSymSeed is nonempty 7903and parentHandle does not reference a key of supported type; or 7904invalid key size in objectPublic representing an asymmetric key 7905 7906TPM_RC_NO_RESULT 7907 7908inSymSeed is nonempty and multiplication resulted in ECC point at 7909infinity 7910 7911TPM_RC_OBJECT_MEMORY 7912 7913no available object slot 7914 7915TPM_RC_SCHEME 7916 7917inconsistent attributes decrypt, sign, restricted and key's scheme ID 7918in objectPublic; or hash algorithm is inconsistent with the scheme ID 7919for keyed hash object 7920 7921TPM_RC_SIZE 7922 7923authPolicy size does not match digest size of the name algorithm in 7924objectPublic; or symmetricAlg and encryptionKey have different 7925sizes; or inSymSeed is nonempty and it is not of the same size as 7926RSA key referenced by parentHandle; or unmarshaling sensitive 7927value from duplicate failed 7928 7929TPM_RC_SYMMETRIC 7930 7931objectPublic is either a storage key with no symmetric algorithm or a 7932non-storage key with symmetric algorithm different from 7933TPM_ALG_NULL 7934 7935TPM_RC_TYPE 7936 7937unsupported type of objectPublic; or non-duplicable storage key 7938represented by objectPublic and its parent referenced by 7939parentHandle are of different types; or parentHandle is not a storage 7940key; or only the public portion of parentHandle is loaded; or 7941objectPublic and duplicate are of different types 7942 7943TPM_RC_VALUE 7944 7945nonempty inSymSeed and its numeric value is greater than the 7946modulus of the key referenced by parentHandle or inSymSeed is 7947larger than the size of the digest produced by the name algorithm of 7948the symmetric key referenced by parentHandle 7949 7950Family “2.0” 7951Level 00 Revision 00.99 7952 7953Published 7954Copyright © TCG 2006-2013 7955 7956Page 89 7957October 31, 2013 7958 7959 Part 3: Commands 79604 79615 79626 79637 79648 79659 796610 796711 796812 796913 797014 797115 797216 797317 797418 797519 797620 797721 797822 797923 798024 798125 798226 798327 798428 798529 798630 798731 798832 798933 799034 799135 799236 799337 799438 799539 799640 799741 799842 799943 800044 800145 800246 800347 800448 800549 800650 800751 800852 800953 801054 801155 801256 801357 801458 801559 801660 801761 801862 801963 802064 802165 802266 802367 8024 8025Trusted Platform Module Library 8026 8027TPM_RC 8028TPM2_Import( 8029Import_In 8030Import_Out 8031 8032*in, 8033*out 8034 8035// IN: input parameter list 8036// OUT: output parameter list 8037 8038) 8039{ 8040TPM_RC 8041OBJECT 8042TPM2B_DATA 8043TPMT_SENSITIVE 8044TPM2B_NAME 8045 8046result = TPM_RC_SUCCESS; 8047*parentObject; 8048data; 8049// symmetric key 8050sensitive; 8051name; 8052 8053UINT16 8054 8055innerKeySize = 0; 8056 8057// encrypt key size for inner 8058// wrapper 8059 8060// Input Validation 8061// FixedTPM and fixedParent must be CLEAR 8062if( 8063in->objectPublic.t.publicArea.objectAttributes.fixedTPM == SET 8064|| in->objectPublic.t.publicArea.objectAttributes.fixedParent == SET) 8065return TPM_RC_ATTRIBUTES + RC_Import_objectPublic; 8066// Get parent pointer 8067parentObject = ObjectGet(in->parentHandle); 8068if(!AreAttributesForParent(parentObject)) 8069return TPM_RC_TYPE + RC_Import_parentHandle; 8070if(in->symmetricAlg.algorithm != TPM_ALG_NULL) 8071{ 8072// Get inner wrap key size 8073innerKeySize = in->symmetricAlg.keyBits.sym; 8074// Input symmetric key must match the size of algorithm. 8075if(in->encryptionKey.t.size != (innerKeySize + 7) / 8) 8076return TPM_RC_SIZE + RC_Import_encryptionKey; 8077} 8078else 8079{ 8080// If input symmetric algorithm is NULL, input symmetric key size must 8081// be 0 as well 8082if(in->encryptionKey.t.size != 0) 8083return TPM_RC_SIZE + RC_Import_encryptionKey; 8084} 8085// See if there is an outer wrapper 8086if(in->inSymSeed.t.size != 0) 8087{ 8088// Decrypt input secret data via asymmetric decryption. TPM_RC_ATTRIBUTES, 8089// TPM_RC_ECC_POINT, TPM_RC_INSUFFICIENT, TPM_RC_KEY, TPM_RC_NO_RESULT, 8090// TPM_RC_SIZE, TPM_RC_VALUE may be returned at this point 8091result = CryptSecretDecrypt(in->parentHandle, NULL, "DUPLICATE", 8092&in->inSymSeed, &data); 8093pAssert(result != TPM_RC_BINDING); 8094if(result != TPM_RC_SUCCESS) 8095return TPM_RC_VALUE + RC_Import_inSymSeed; 8096} 8097else 8098{ 8099data.t.size = 0; 8100} 8101// Compute name of object 8102ObjectComputeName(&(in->objectPublic.t.publicArea), &name); 8103 8104Page 90 8105October 31, 2013 8106 8107Published 8108Copyright © TCG 2006-2013 8109 8110Family “2.0” 8111Level 00 Revision 00.99 8112 8113 Trusted Platform Module Library 811468 811569 811670 811771 811872 811973 812074 812175 812276 812377 812478 812579 812680 812781 812882 812983 813084 813185 813286 813387 813488 813589 813690 813791 813892 813993 814094 814195 814296 814397 814498 814599 8146100 8147101 8148102 8149103 8150104 8151105 8152106 8153107 8154108 8155109 8156110 8157111 8158112 8159113 8160114 8161 8162Part 3: Commands 8163 8164// Retrieve sensitive from private. 8165// TPM_RC_INSUFFICIENT, TPM_RC_INTEGRITY, TPM_RC_SIZE may be returned here. 8166result = DuplicateToSensitive(&in->duplicate, &name, in->parentHandle, 8167in->objectPublic.t.publicArea.nameAlg, 8168(TPM2B_SEED *) &data, &in->symmetricAlg, 8169&in->encryptionKey, &sensitive); 8170if(result != TPM_RC_SUCCESS) 8171return RcSafeAddToResult(result, RC_Import_duplicate); 8172// If the parent of this object has fixedTPM SET, then fully validate this 8173// object so that validation can be skipped when it is loaded 8174if(parentObject->publicArea.objectAttributes.fixedTPM == SET) 8175{ 8176TPM_HANDLE 8177objectHandle; 8178// Perform self check on input public area. A TPM_RC_SIZE, TPM_RC_SCHEME, 8179// TPM_RC_VALUE, TPM_RC_SYMMETRIC, TPM_RC_TYPE, TPM_RC_HASH, 8180// TPM_RC_ASYMMETRIC, TPM_RC_ATTRIBUTES or TPM_RC_KDF error may be returned 8181// at this point 8182result = PublicAttributesValidation(TRUE, in->parentHandle, 8183&in->objectPublic.t.publicArea); 8184if(result != TPM_RC_SUCCESS) 8185return RcSafeAddToResult(result, RC_Import_objectPublic); 8186// Create internal object. A TPM_RC_KEY_SIZE, TPM_RC_KEY or 8187// TPM_RC_OBJECT_MEMORY error may be returned at this point 8188result = ObjectLoad(TPM_RH_NULL, &in->objectPublic.t.publicArea, 8189&sensitive, NULL, in->parentHandle, FALSE, 8190&objectHandle); 8191if(result != TPM_RC_SUCCESS) 8192return result; 8193// Don't need the object, just needed the checks to be performed so 8194// flush the object 8195ObjectFlush(objectHandle); 8196} 8197// Command output 8198// Prepare output private data from sensitive 8199SensitiveToPrivate(&sensitive, &name, in->parentHandle, 8200in->objectPublic.t.publicArea.nameAlg, 8201&out->outPrivate); 8202return TPM_RC_SUCCESS; 8203} 8204 8205Family “2.0” 8206Level 00 Revision 00.99 8207 8208Published 8209Copyright © TCG 2006-2013 8210 8211Page 91 8212October 31, 2013 8213 8214 Part 3: Commands 8215 821616 8217 8218Trusted Platform Module Library 8219 8220Asymmetric Primitives 8221 822216.1 8223 8224Introduction 8225 8226The commands in this clause provide low-level primitives for access to the asymmetric algorithms 8227implemented in the TPM. Many of these commands are only allowed if the asymmetric key is an 8228unrestricted key. 822916.2 8230 8231TPM2_RSA_Encrypt 8232 823316.2.1 General Description 8234This command performs RSA encryption using the indicated padding scheme according to PKCS#1v2.1 8235(PKCS#1). If the scheme of keyHandle is TPM_ALG_NULL, then the caller may use inScheme to specify 8236the padding scheme. If scheme of keyHandle is not TPM_ALG_NULL, then inScheme shall either be 8237TPM_ALG_NULL or be the same as scheme (TPM_RC_SCHEME). 8238The key referenced by keyHandle is required to be an RSA key (TPM_RC_KEY) with the decrypt attribute 8239SET (TPM_RC_ATTRIBUTES). 8240NOTE 8241 8242Requiring that the decrypt attribute be set allows the TPM to ensure that the scheme selection is 8243done with the presumption that the scheme of the key is a decryption scheme selection. It is 8244understood that this command will operate on a key with only the publi c part loaded so the caller 8245may modify any key in any desired way. So, this constraint only serves to simplify the TPM logic. 8246 8247The three types of allowed padding are: 82481) TPM_ALG_OAEP – Data is OAEP padded as described in 7.1 of PKCS#1 v2.1. The only 8249supported mask generation is MGF1. 82502) TPM_ALG_RSAES – Data is padded as described in 7.2 of PKCS#1 v2.1. 82513) TPM_ALG_NULL – Data is not padded by the TPM and the TPM will treat message as an 8252unsigned integer and perform a modular exponentiation of message using the public 8253exponent of the key referenced by keyHandle. This scheme is only used if both the scheme 8254in the key referenced by keyHandle is TPM_ALG_NULL, and the inScheme parameter of the 8255command is TPM_ALG_NULL. The input value cannot be larger than the public modulus of 8256the key referenced by keyHandle. 8257Table 41 — Padding Scheme Selection 8258keyHandle→scheme 8259 8260OAEP 8261RSAES 8262 8263TPM_ALG_RSAES 8264 8265RSAES 8266error (TPM_RC_SCHEME) 8267 8268TPM_ALG_NULL 8269 8270OAEP 8271 8272TPM_ALG_RSAES 8273 8274error (TPM_RC_SCHEME) 8275 8276TPM_AGL_OAEP 8277 8278October 31, 2013 8279 8280RSAES 8281 8282TPM_ALG_OAEP 8283 8284Page 92 8285 8286TPM_ALG_RSAES 8287 8288TPM_ALG_NULL 8289 8290TPM_ALG_OAEP 8291 8292none 8293 8294TPM_ALG_OAEP 8295 8296TPM_ALG_RSAES 8297 8298padding scheme used 8299 8300TPM_ALG_NULL 8301TPM_ALG_NULL 8302 8303inScheme 8304 8305OAEP 8306 8307Published 8308Copyright © TCG 2006-2013 8309 8310Family “2.0” 8311Level 00 Revision 00.99 8312 8313 Trusted Platform Module Library 8314 8315Part 3: Commands 8316 8317After padding, the data is RSAEP encrypted according to 5.1.1 of PKCS#1v2.1. 8318NOTE 1 8319 8320It is required that decrypt be SET so that the commands that load a key can validate that the 8321scheme is consistent rather than have that deferred until the key is used. 8322 8323NOTE 2 8324 8325If it is desired to use a key that had restricted SET, the caller may CLEAR restricted and load the 8326public part of the key and use that unrestricted version of the key for encryption. 8327 8328If inScheme is used, and the scheme requires a hash algorithm it may not be TPM_ALG_NULL. 8329NOTE 3 8330 8331Because only the public portion of the key needs to be loaded for this command, the caller can 8332manipulate the attributes of the key in any way desired. As a result , the TPM shall not check the 8333consistency of the attributes. The only property checking is that the key is an RSA key and that the 8334padding scheme is supported. 8335 8336The message parameter is limited in size by the padding scheme according to the following table: 8337Table 42 — Message Size Limits Based on Padding 8338Scheme 8339 8340Maximum Message Length 8341(mLen) in Octets 8342 8343TPM_ALG_OAEP 8344 8345mLen k – 2hLen – 2 8346 8347TPM_ALG_RSAES 8348 8349mLen k – 11 8350 8351TPM_ALG_NULL 8352 8353mLen k 8354 8355Comments 8356 8357The numeric value of the message must be 8358less than the numeric value of the public 8359modulus (n). 8360 8361NOTES 83621) 83632) 8364 8365k ≔ the number of byes in the public modulus 8366hLen ≔ the number of octets in the digest produced by the hash algorithm used in the process 8367 8368The label parameter is optional. If provided (label.size != 0) then the TPM shall return TPM_RC_VALUE if 8369the last octet in label is not zero. If a zero octet occurs before label.buffer[label.size-1], the TPM shall 8370truncate the label at that point. The terminating octet of zero is included in the label used in the padding 8371scheme. 8372NOTE 4 8373 8374If the scheme does not use a label, the TPM will still verify that label is properly formatted if label is 8375present. 8376 8377The function returns padded and encrypted value outData. 8378The message parameter in the command may be encrypted using parameter encryption. 8379NOTE 5 8380 8381Only the public area of keyHandle is required to be loaded. A public key may be loaded with any 8382desired scheme. If the scheme is to be changed, a different public area must be loaded. 8383 8384Family “2.0” 8385Level 00 Revision 00.99 8386 8387Published 8388Copyright © TCG 2006-2013 8389 8390Page 93 8391October 31, 2013 8392 8393 Part 3: Commands 8394 8395Trusted Platform Module Library 8396 839716.2.2 Command and Response 8398Table 43 — TPM2_RSA_Encrypt Command 8399Type 8400 8401Name 8402 8403Description 8404 8405TPMI_ST_COMMAND_TAG 8406 8407tag 8408 8409UINT32 8410 8411commandSize 8412 8413TPM_CC 8414 8415commandCode 8416 8417TPM_CC_RSA_Encrypt 8418 8419TPMI_DH_OBJECT 8420 8421keyHandle 8422 8423reference to public portion of RSA key to use for 8424encryption 8425Auth Index: None 8426message to be encrypted 8427 8428TPM2B_PUBLIC_KEY_RSA 8429 8430message 8431 8432TPMT_RSA_DECRYPT+ 8433 8434inScheme 8435 8436TPM2B_DATA 8437 8438label 8439 8440NOTE 1 8441 8442The data type was chosen because it limits the 8443overall size of the input to no greater than the size 8444of the largest RSA public key. This may be larger 8445than allowed for keyHandle. 8446 8447the padding scheme to use if scheme associated with 8448keyHandle is TPM_ALG_NULL 8449optional label L to be associated with the message 8450Size of the buffer is zero if no label is present 8451NOTE 2 8452 8453See description of label above. 8454 8455Table 44 — TPM2_RSA_Encrypt Response 8456Type 8457 8458Name 8459 8460Description 8461 8462TPM_ST 8463 8464tag 8465 8466see clause 8 8467 8468UINT32 8469 8470responseSize 8471 8472TPM_RC 8473 8474responseCode 8475 8476TPM2B_PUBLIC_KEY_RSA 8477 8478outData 8479 8480Page 94 8481October 31, 2013 8482 8483encrypted output 8484 8485Published 8486Copyright © TCG 2006-2013 8487 8488Family “2.0” 8489Level 00 Revision 00.99 8490 8491 Trusted Platform Module Library 8492 8493Part 3: Commands 8494 849516.2.3 Detailed Actions 84961 84972 84983 8499 8500#include "InternalRoutines.h" 8501#include "RSA_Encrypt_fp.h" 8502#ifdef TPM_ALG_RSA 8503Error Returns 8504TPM_RC_ATTRIBUTES 8505 8506decrypt attribute is not SET in key referenced by keyHandle 8507 8508TPM_RC_KEY 8509 8510keyHandle does not reference an RSA key 8511 8512TPM_RC_SCHEME 8513 8514incorrect input scheme, or the chosen scheme is not a valid RSA 8515decrypt scheme 8516 8517TPM_RC_VALUE 8518 85194 85205 85216 85227 85238 85249 852510 852611 852712 852813 852914 853015 853116 853217 853318 853419 853520 853621 853722 853823 853924 854025 854126 854227 854328 854429 854530 854631 854732 854833 854934 855035 855136 855237 855338 855439 855540 855641 855742 855843 855944 856045 856146 8562 8563Meaning 8564 8565the numeric value of message is greater than the public modulus of 8566the key referenced by keyHandle, or label is not a null-terminated 8567string 8568 8569TPM_RC 8570TPM2_RSA_Encrypt( 8571RSA_Encrypt_In 8572RSA_Encrypt_Out 8573 8574*in, 8575*out 8576 8577// IN: input parameter list 8578// OUT: output parameter list 8579 8580TPM_RC 8581OBJECT 8582TPMT_RSA_DECRYPT 8583char 8584 8585result; 8586*rsaKey; 8587*scheme; 8588*label = NULL; 8589 8590) 8591{ 8592 8593// Input Validation 8594rsaKey = ObjectGet(in->keyHandle); 8595// selected key must be an RSA key 8596if(rsaKey->publicArea.type != TPM_ALG_RSA) 8597return TPM_RC_KEY + RC_RSA_Encrypt_keyHandle; 8598// selected key must have the decryption attribute 8599if(rsaKey->publicArea.objectAttributes.decrypt != SET) 8600return TPM_RC_ATTRIBUTES + RC_RSA_Encrypt_keyHandle; 8601// Is there a label? 8602if(in->label.t.size > 0) 8603{ 8604// label is present, so make sure that is it NULL-terminated 8605if(in->label.t.buffer[in->label.t.size - 1] != 0) 8606return TPM_RC_VALUE + RC_RSA_Encrypt_label; 8607label = (char *)in->label.t.buffer; 8608} 8609// Command Output 8610// Select a scheme for encryption 8611scheme = CryptSelectRSAScheme(in->keyHandle, &in->inScheme); 8612if(scheme == NULL) 8613return TPM_RC_SCHEME + RC_RSA_Encrypt_inScheme; 8614// Encryption. TPM_RC_VALUE, or TPM_RC_SCHEME errors my be returned buy 8615// CryptEncyptRSA. Note: It can also return TPM_RC_ATTRIBUTES if the key does 8616// not have the decrypt attribute but that was checked above. 8617out->outData.t.size = sizeof(out->outData.t.buffer); 8618 8619Family “2.0” 8620Level 00 Revision 00.99 8621 8622Published 8623Copyright © TCG 2006-2013 8624 8625Page 95 8626October 31, 2013 8627 8628 Part 3: Commands 862947 863048 863149 863250 863351 863452 8635 8636Trusted Platform Module Library 8637 8638result = CryptEncryptRSA(&out->outData.t.size, out->outData.t.buffer, rsaKey, 8639scheme, in->message.t.size, in->message.t.buffer, 8640label); 8641return result; 8642} 8643#endif 8644 8645Page 96 8646October 31, 2013 8647 8648Published 8649Copyright © TCG 2006-2013 8650 8651Family “2.0” 8652Level 00 Revision 00.99 8653 8654 Trusted Platform Module Library 8655 865616.3 8657 8658Part 3: Commands 8659 8660TPM2_RSA_Decrypt 8661 866216.3.1 General Description 8663This command performs RSA decryption using the indicated padding scheme according to PKCS#1v2.1 8664(PKCS#1). 8665The scheme selection for this command is the same as for TPM2_RSA_Encrypt() and is shown in Table 866641. 8667The key referenced by keyHandle shall be an RSA key (TPM_RC_KEY) with restricted CLEAR and 8668decrypt SET (TPM_RC_ATTRIBUTES). 8669This command uses the private key of keyHandle for this operation and authorization is required. 8670The TPM will perform a modular exponentiation of ciphertext using the private exponent associated with 8671keyHandle (this is described in PKCS#1v2.1, clause 5.1.2). It will then validate the padding according to 8672the selected scheme. If the padding checks fail, TPM_RC_VALUE is returned. Otherwise, the data is 8673returned with the padding removed. If no padding is used, the returned value is an unsigned integer value 8674that is the result of the modular exponentiation of cipherText using the private exponent of keyHandle. 8675The returned value may include leading octets zeros so that it is the same size as the public modulus. For 8676the other padding schemes, the returned value will be smaller than the public modulus but will contain all 8677the data remaining after padding is removed and this may include leading zeros if the original encrypted 8678value contained leading zeros.. 8679If a label is used in the padding process of the scheme, the label parameter is required to be present in 8680the decryption process and label is required to be the same in both cases. The TPM shall verify that the 8681label is consistent and if not it shall return TPM_RC_VALUE. 8682If label is present (label.size != 0), it 8683shall be a NULL-terminated string or the TPM will return TPM_RC_VALUE. 8684NOTE 1 8685 8686The size of label includes the terminating null. 8687 8688The message parameter in the response may be encrypted using parameter encryption. 8689If the decryption scheme does not require a hash function, the hash parameter of inScheme may be set 8690to any valid hash function or TPM_ALG_NULL. 8691If the description scheme does not require a label, the value in label is not used but the size of the label 8692field is checked for consistency with the indicated data type (TPM2B_DATA). That is, the field may not be 8693larger than allowed for a TPM2B_DATA. 8694 8695Family “2.0” 8696Level 00 Revision 00.99 8697 8698Published 8699Copyright © TCG 2006-2013 8700 8701Page 97 8702October 31, 2013 8703 8704 Part 3: Commands 8705 8706Trusted Platform Module Library 8707 870816.3.2 Command and Response 8709Table 45 — TPM2_RSA_Decrypt Command 8710Type 8711 8712Name 8713 8714Description 8715 8716TPMI_ST_COMMAND_TAG 8717 8718tag 8719 8720UINT32 8721 8722commandSize 8723 8724TPM_CC 8725 8726commandCode 8727 8728TPM_CC_RSA_Decrypt 8729 8730TPMI_DH_OBJECT 8731 8732@keyHandle 8733 8734RSA key to use for decryption 8735Auth Index: 1 8736Auth Role: USER 8737 8738TPM2B_PUBLIC_KEY_RSA 8739 8740cipherText 8741 8742NOTE 8743 8744TPMT_RSA_DECRYPT+ 8745 8746inScheme 8747 8748the padding scheme to use if scheme associated with 8749keyHandle is TPM_ALG_NULL 8750 8751TPM2B_DATA 8752 8753label 8754 8755label whose association with the message is to be 8756verified 8757 8758cipher text to be decrypted 8759An encrypted RSA data block is the size of the 8760public modulus. 8761 8762Table 46 — TPM2_RSA_Decrypt Response 8763Type 8764 8765Name 8766 8767Description 8768 8769TPM_ST 8770 8771tag 8772 8773see clause 8 8774 8775UINT32 8776 8777responseSize 8778 8779TPM_RC 8780 8781responseCode 8782 8783TPM2B_PUBLIC_KEY_RSA 8784 8785message 8786 8787Page 98 8788October 31, 2013 8789 8790decrypted output 8791 8792Published 8793Copyright © TCG 2006-2013 8794 8795Family “2.0” 8796Level 00 Revision 00.99 8797 8798 Trusted Platform Module Library 8799 8800Part 3: Commands 8801 880216.3.3 Detailed Actions 88031 88042 88053 8806 8807#include "InternalRoutines.h" 8808#include "RSA_Decrypt_fp.h" 8809#ifdef TPM_ALG_RSA 8810Error Returns 8811TPM_RC_KEY 8812 8813keyHandle does not reference an unrestricted decrypt key 8814 8815TPM_RC_SCHEME 8816 8817incorrect input scheme, or the chosen scheme is not a valid RSA 8818decrypt scheme 8819 8820TPM_RC_SIZE 8821 8822cipherText is not the size of the modulus of key referenced by 8823keyHandle 8824 8825TPM_RC_VALUE 8826 88274 88285 88296 88307 88318 88329 883310 883411 883512 883613 883714 883815 883916 884017 884118 884219 884320 884421 884522 884623 884724 884825 884926 885027 885128 885229 885330 885431 885532 885633 885734 885835 885936 886037 886138 886239 886340 886441 886542 886643 886744 886845 886946 8870 8871Meaning 8872 8873label is not a null terminated string or the value of cipherText is 8874greater that the modulus of keyHandle 8875 8876TPM_RC 8877TPM2_RSA_Decrypt( 8878RSA_Decrypt_In 8879RSA_Decrypt_Out 8880 8881*in, 8882*out 8883 8884// IN: input parameter list 8885// OUT: output parameter list 8886 8887TPM_RC 8888OBJECT 8889TPMT_RSA_DECRYPT 8890char 8891 8892result; 8893*rsaKey; 8894*scheme; 8895*label = NULL; 8896 8897) 8898{ 8899 8900// Input Validation 8901rsaKey = ObjectGet(in->keyHandle); 8902// The selected key must be an RSA key 8903if(rsaKey->publicArea.type != TPM_ALG_RSA) 8904return TPM_RC_KEY + RC_RSA_Decrypt_keyHandle; 8905// The selected key must be an unrestricted decryption key 8906if( 8907rsaKey->publicArea.objectAttributes.restricted == SET 8908|| rsaKey->publicArea.objectAttributes.decrypt == CLEAR) 8909return TPM_RC_ATTRIBUTES + RC_RSA_Decrypt_keyHandle; 8910// 8911// 8912// 8913// 8914 8915NOTE: Proper operation of this command requires that the sensitive area 8916of the key is loaded. This is assured because authorization is required 8917to use the sensitive area of the key. In order to check the authorization, 8918the sensitive area has to be loaded, even if authorization is with policy. 8919 8920// If label is present, make sure that it is a NULL-terminated string 8921if(in->label.t.size > 0) 8922{ 8923// Present, so make sure that it is NULL-terminated 8924if(in->label.t.buffer[in->label.t.size - 1] != 0) 8925return TPM_RC_VALUE + RC_RSA_Decrypt_label; 8926label = (char *)in->label.t.buffer; 8927} 8928// Command Output 8929// Select a scheme for decrypt. 8930scheme = CryptSelectRSAScheme(in->keyHandle, &in->inScheme); 8931if(scheme == NULL) 8932 8933Family “2.0” 8934Level 00 Revision 00.99 8935 8936Published 8937Copyright © TCG 2006-2013 8938 8939Page 99 8940October 31, 2013 8941 8942 Part 3: Commands 894347 894448 894549 894650 894751 894852 894953 895054 895155 895256 895357 895458 895559 895660 895761 8958 8959Trusted Platform Module Library 8960 8961return TPM_RC_SCHEME + RC_RSA_Decrypt_inScheme; 8962// Decryption. TPM_RC_VALUE, TPM_RC_SIZE, and TPM_RC_KEY error may be 8963// returned by CryptDecryptRSA. 8964// NOTE: CryptDecryptRSA can also return TPM_RC_ATTRIBUTES or TPM_RC_BINDING 8965// when the key is not a decryption key but that was checked above. 8966out->message.t.size = sizeof(out->message.t.buffer); 8967result = CryptDecryptRSA(&out->message.t.size, out->message.t.buffer, rsaKey, 8968scheme, in->cipherText.t.size, 8969in->cipherText.t.buffer, 8970label); 8971return result; 8972} 8973#endif 8974 8975Page 100 8976October 31, 2013 8977 8978Published 8979Copyright © TCG 2006-2013 8980 8981Family “2.0” 8982Level 00 Revision 00.99 8983 8984 Trusted Platform Module Library 8985 898616.4 8987 8988Part 3: Commands 8989 8990TPM2_ECDH_KeyGen 8991 899216.4.1 General Description 8993This command uses the TPM to generate an ephemeral key pair (de, Qe where Qe ≔ [de]G). It uses the private 8994ephemeral key and a loaded public key (QS) to compute the shared secret value (P ≔ [hde]QS). 8995 8996keyHandle shall refer to a loaded ECC key. The sensitive portion of this key need not be loaded. 8997The curve parameters of the loaded ECC key are used to generate the ephemeral key. 8998NOTE 1 8999 9000This function is the equivalent of encrypting data to another object’s public key. The seed value is 9001used in a KDF to generate a symmetric key and that key is used to encrypt the data. Once the data 9002is encrypted and the symmetric key discarded, only the ob ject with the private portion of the 9003keyHandle will be able to decrypt it. 9004 9005The zPoint in the response may be encrypted using parameter encryption. 9006 9007Family “2.0” 9008Level 00 Revision 00.99 9009 9010Published 9011Copyright © TCG 2006-2013 9012 9013Page 101 9014October 31, 2013 9015 9016 Part 3: Commands 9017 9018Trusted Platform Module Library 9019 902016.4.2 Command and Response 9021Table 47 — TPM2_ECDH_KeyGen Command 9022Type 9023 9024Name 9025 9026Description 9027 9028TPMI_ST_COMMAND_TAG 9029 9030tag 9031 9032UINT32 9033 9034commandSize 9035 9036TPM_CC 9037 9038commandCode 9039 9040TPM_CC_ECDH_KeyGen 9041 9042TPMI_DH_OBJECT 9043 9044keyHandle 9045 9046Handle of a loaded ECC key public area. 9047Auth Index: None 9048 9049Table 48 — TPM2_ECDH_KeyGen Response 9050Type 9051 9052Name 9053 9054Description 9055 9056TPM_ST 9057 9058tag 9059 9060see clause 8 9061 9062UINT32 9063 9064responseSize 9065 9066TPM_RC 9067 9068responseCode 9069 9070TPM2B_ECC_POINT 9071 9072zPoint 9073 9074results of P ≔ h[de]Qs 9075 9076TPM2B_ECC_POINT 9077 9078pubPoint 9079 9080generated ephemeral public point (Qe) 9081 9082Page 102 9083October 31, 2013 9084 9085Published 9086Copyright © TCG 2006-2013 9087 9088Family “2.0” 9089Level 00 Revision 00.99 9090 9091 Trusted Platform Module Library 9092 9093Part 3: Commands 9094 909516.4.3 Detailed Actions 90961 90972 90983 9099 9100#include "InternalRoutines.h" 9101#include "ECDH_KeyGen_fp.h" 9102#ifdef TPM_ALG_ECC 9103Error Returns 9104TPM_RC_KEY 9105 91064 91075 91086 91097 91108 91119 911210 911311 911412 911513 911614 911715 911816 911917 912018 912119 912220 912321 912422 912523 912624 912725 912826 912927 913028 913129 913230 913331 913432 913533 913634 913735 913836 913937 914038 914139 914240 914341 914442 914543 914644 914745 914846 914947 915048 915149 915250 915351 915452 915553 9156 9157Meaning 9158keyHandle does not reference a non-restricted decryption ECC key 9159 9160TPM_RC 9161TPM2_ECDH_KeyGen( 9162ECDH_KeyGen_In 9163ECDH_KeyGen_Out 9164 9165*in, 9166*out 9167 9168// IN: input parameter list 9169// OUT: output parameter list 9170 9171) 9172{ 9173OBJECT 9174TPM2B_ECC_PARAMETER 9175TPM_RC 9176 9177*eccKey; 9178sensitive; 9179result; 9180 9181// Input Validation 9182eccKey = ObjectGet(in->keyHandle); 9183// Input key must be a non-restricted, decrypt ECC key 9184if( 9185eccKey->publicArea.type != TPM_ALG_ECC 9186|| eccKey->publicArea.objectAttributes.restricted == SET 9187|| eccKey->publicArea.objectAttributes.decrypt != SET 9188) 9189return TPM_RC_KEY + RC_ECDH_KeyGen_keyHandle; 9190// Command Output 9191do 9192{ 9193// Create ephemeral ECC key 9194CryptNewEccKey(eccKey->publicArea.parameters.eccDetail.curveID, 9195&out->pubPoint.t.point, &sensitive); 9196out->pubPoint.t.size = TPMS_ECC_POINT_Marshal(&out->pubPoint.t.point, 9197NULL, NULL); 9198// Compute Z 9199result = CryptEccPointMultiply(&out->zPoint.t.point, 9200eccKey->publicArea.parameters.eccDetail.curveID, 9201&sensitive, &eccKey->publicArea.unique.ecc); 9202// The point in the key is not on the curve. Indicate that the key is bad. 9203if(result == TPM_RC_ECC_POINT) 9204return TPM_RC_KEY + RC_ECDH_KeyGen_keyHandle; 9205// The other possible error is TPM_RC_NO_RESULT indicating that the 9206// multiplication resulted in the point at infinity, so get a new 9207// random key and start over (hardly ever happens). 9208} 9209while(result != TPM_RC_SUCCESS); 9210// Marshal the values to generate the point. 9211out->zPoint.t.size = TPMS_ECC_POINT_Marshal(&out->zPoint.t.point, NULL, NULL); 9212return TPM_RC_SUCCESS; 9213} 9214#endif 9215 9216Family “2.0” 9217Level 00 Revision 00.99 9218 9219Published 9220Copyright © TCG 2006-2013 9221 9222Page 103 9223October 31, 2013 9224 9225 Part 3: Commands 9226 922716.5 9228 9229Trusted Platform Module Library 9230 9231TPM2_ECDH_ZGen 9232 923316.5.1 General Description 9234This command uses the TPM to recover the Z value from a public point (QB) and a private key (ds). It will 9235perform the multiplication of the provided inPoint (QB) with the private key (ds) and return the coordinates 9236of the resultant point (Z = (xZ , yZ) ≔ [hds]QB; where h is the cofactor of the curve). 9237keyHandle shall refer to a loaded, ECC key (TPM_RC_KEY) with the restricted attribute CLEAR and the 9238decrypt attribute SET (TPM_RC_ATTRIBUTES). 9239The scheme of the key referenced by keyHandle is required to be either TPM_ALG_ECDH or 9240TPM_ALG_NULL (TPM_RC_SCHEME). 9241inPoint is required to be on the curve of the key referenced by keyHandle (TPM_RC_ECC_POINT). 9242The parameters of the key referenced by keyHandle are used to perform the point multiplication. 9243 9244Page 104 9245October 31, 2013 9246 9247Published 9248Copyright © TCG 2006-2013 9249 9250Family “2.0” 9251Level 00 Revision 00.99 9252 9253 Trusted Platform Module Library 9254 9255Part 3: Commands 9256 925716.5.2 Command and Response 9258Table 49 — TPM2_ECDH_ZGen Command 9259Type 9260 9261Name 9262 9263Description 9264 9265TPMI_ST_COMMAND_TAG 9266 9267tag 9268 9269UINT32 9270 9271commandSize 9272 9273TPM_CC 9274 9275commandCode 9276 9277TPM_CC_ECDH_ZGen 9278 9279TPMI_DH_OBJECT 9280 9281@keyHandle 9282 9283handle of a loaded ECC key 9284Auth Index: 1 9285Auth Role: USER 9286 9287TPM2B_ECC_POINT 9288 9289inPoint 9290 9291a public key 9292 9293Table 50 — TPM2_ECDH_ZGen Response 9294Type 9295 9296Name 9297 9298Description 9299 9300TPM_ST 9301 9302tag 9303 9304see clause 8 9305 9306UINT32 9307 9308responseSize 9309 9310TPM_RC 9311 9312responseCode 9313 9314TPM2B_ECC_POINT 9315 9316outPoint 9317 9318Family “2.0” 9319Level 00 Revision 00.99 9320 9321X and Y coordinates of the product of the multiplication 9322 9323Z = (xZ , yZ) ≔ [hdS]QB 9324 9325Published 9326Copyright © TCG 2006-2013 9327 9328Page 105 9329October 31, 2013 9330 9331 Part 3: Commands 9332 9333Trusted Platform Module Library 9334 933516.5.3 Detailed Actions 93361 93372 93383 9339 9340#include "InternalRoutines.h" 9341#include "ECDH_ZGen_fp.h" 9342#ifdef TPM_ALG_ECC 9343Error Returns 9344TPM_RC_KEY 9345 9346keyHandle does not reference a non-restricted decryption ECC key 9347 9348TPM_RC_ECC_POINT 9349 9350invalid argument 9351 9352TPM_RC_NO_RESULT 93534 93545 93556 93567 93578 93589 935910 936011 936112 936213 936314 936415 936516 936617 936718 936819 936920 937021 937122 937223 937324 937425 937526 937627 937728 937829 937930 938031 938132 938233 938334 938435 938536 938637 938738 938839 9389 9390Meaning 9391 9392multiplying inPoint resulted in a point at infinity 9393 9394TPM_RC 9395TPM2_ECDH_ZGen( 9396ECDH_ZGen_In 9397ECDH_ZGen_Out 9398 9399*in, 9400*out 9401 9402// IN: input parameter list 9403// OUT: output parameter list 9404 9405) 9406{ 9407TPM_RC 9408OBJECT 9409 9410result; 9411*eccKey; 9412 9413// Input Validation 9414eccKey = ObjectGet(in->keyHandle); 9415// Input key must be a non-restricted, decrypt ECC key 9416if( 9417eccKey->publicArea.type != TPM_ALG_ECC 9418|| eccKey->publicArea.objectAttributes.restricted == SET 9419|| eccKey->publicArea.objectAttributes.decrypt != SET 9420) 9421return TPM_RC_KEY + RC_ECDH_ZGen_keyHandle; 9422// Command Output 9423// Compute Z. TPM_RC_ECC_POINT or TPM_RC_NO_RESULT may be returned here. 9424result = CryptEccPointMultiply(&out->outPoint.t.point, 9425eccKey->publicArea.parameters.eccDetail.curveID, 9426&eccKey->sensitive.sensitive.ecc, 9427&in->inPoint.t.point); 9428if(result != TPM_RC_SUCCESS) 9429return RcSafeAddToResult(result, RC_ECDH_ZGen_inPoint); 9430out->outPoint.t.size = TPMS_ECC_POINT_Marshal(&out->outPoint.t.point, 9431NULL, NULL); 9432return TPM_RC_SUCCESS; 9433} 9434#endif 9435 9436Page 106 9437October 31, 2013 9438 9439Published 9440Copyright © TCG 2006-2013 9441 9442Family “2.0” 9443Level 00 Revision 00.99 9444 9445 Trusted Platform Module Library 9446 944716.6 9448 9449Part 3: Commands 9450 9451TPM2_ECC_Parameters 9452 945316.6.1 General Description 9454This command returns the parameters of an ECC curve identified by its TCG-assigned curveID. 945516.6.2 Command and Response 9456Table 51 — TPM2_ECC_Parameters Command 9457Type 9458 9459Name 9460 9461Description 9462 9463TPMI_ST_COMMAND_TAG 9464 9465tag 9466 9467UINT32 9468 9469commandSize 9470 9471TPM_CC 9472 9473commandCode 9474 9475TPM_CC_ECC_Parameters 9476 9477TPMI_ECC_CURVE 9478 9479curveID 9480 9481parameter set selector 9482 9483Table 52 — TPM2_ECC_Parameters Response 9484Type 9485 9486Name 9487 9488Description 9489 9490TPM_ST 9491 9492tag 9493 9494see clause 8 9495 9496UINT32 9497 9498responseSize 9499 9500TPM_RC 9501 9502responseCode 9503 9504TPMS_ALGORITHM_DETAIL_ECC 9505 9506parameters 9507 9508Family “2.0” 9509Level 00 Revision 00.99 9510 9511ECC parameters for the selected curve 9512 9513Published 9514Copyright © TCG 2006-2013 9515 9516Page 107 9517October 31, 2013 9518 9519 Part 3: Commands 9520 9521Trusted Platform Module Library 9522 952316.6.3 Detailed Actions 95241 95252 95263 9527 9528#include "InternalRoutines.h" 9529#include "ECC_Parameters_fp.h" 9530#ifdef TPM_ALG_ECC 9531Error Returns 9532TPM_RC_VALUE 9533 95344 95355 95366 95377 95388 95399 954010 954111 954212 954313 954414 954515 954616 954717 954818 9549 9550Meaning 9551Unsupported ECC curve ID 9552 9553TPM_RC 9554TPM2_ECC_Parameters( 9555ECC_Parameters_In 9556ECC_Parameters_Out 9557 9558*in, 9559*out 9560 9561// IN: input parameter list 9562// OUT: output parameter list 9563 9564) 9565{ 9566// Command Output 9567// Get ECC curve parameters 9568if(CryptEccGetParameters(in->curveID, &out->parameters)) 9569return TPM_RC_SUCCESS; 9570else 9571return TPM_RC_VALUE + RC_ECC_Parameters_curveID; 9572} 9573#endif 9574 957516.7 957616.7.1 9577 9578TPM2_ZGen_2Phase 9579General Description 9580 9581This command supports two-phase key exchange protocols. The command is used in combination with 9582TPM2_EC_Ephemeral(). TPM2_EC_Ephemeral() generates an ephemeral key and returns the public 9583point of that ephemeral key along with a numeric value that allows the TPM to regenerate the associated 9584private key. 9585The input parameters for this command are a static public key (inQsU), an ephemeral key (inQeU) from 9586party B, and the commitCounter returned by TPM2_EC_Ephemeral(). The TPM uses the counter value to 9587regenerate the ephemeral private key (de,V) and the associated public key (Qe,V). keyA provides the static 9588ephemeral elements ds,V and Qs,V. This provides the two pairs of ephemeral and static keys that are 9589required for the schemes supported by this command. 9590The TPM will compute Z or Zs and Ze according to the selected scheme. If the scheme is not a two-phase 9591key exchange scheme or if the scheme is not supported, the TPM will return TPM_RC_SCHEME. 9592It is an error if inQsB or inQeB are not on the curve of keyA (TPM_RC_ECC_POINT). 9593The two-phase key schemes that were assigned an algorithm ID as of the time of the publication of this 9594specification are TPM_ALG_ECDH, TPM_ALG_ECMQV, and TPM_ALG_SM2. 9595If this command is supported, then support for TPM_ALG_ECDH is required. Support for 9596TPM_ALG_ECMQV or TPM_ALG_SM2 is optional. 9597NOTE 1 9598 9599If SM2 is supported and this command is supported, then the implementation is required to support 9600the key exchange protocol of SM2, part 3. 9601 9602For TPM_ALG_ECDH outZ1 will be Zs and outZ2 will Ze as defined in 6.1.1.2 of SP800-56A. 9603 9604Page 108 9605October 31, 2013 9606 9607Published 9608Copyright © TCG 2006-2013 9609 9610Family “2.0” 9611Level 00 Revision 00.99 9612 9613 Trusted Platform Module Library 9614NOTE 2 9615 9616Part 3: Commands 9617 9618A non-restricted decryption key using ECDH may be used in either TPM2_ECDH_ZGen() or 9619TPM2_ZGen_2Phase as the computation done with the private part of keyA is the same in both 9620cases. 9621 9622For TPM_ALG_ECMQV or TPM_ALG_SM2 outZ1 will be Z and outZ2 will be an Empty Point. 9623NOTE 3 9624 9625An Empty Point has two Empty Buffers as coordinates meaning the minimum size value for outZ2 9626will be four. 9627 9628If the input scheme is TPM_ALG_ECDH, then outZ1 will be Zs and outZ2 will be Ze. For schemes like 9629MQV (including SM2), outZ1 will contain the computed value and outZ2 will be an Empty Point. 9630NOTE 9631 9632The Z values returned by the TPM are a full point and not ju st an x-coordinate. 9633 9634If a computation of either Z produces the point at infinity, then the corresponding Z value will be an Empty 9635Point. 9636 9637Family “2.0” 9638Level 00 Revision 00.99 9639 9640Published 9641Copyright © TCG 2006-2013 9642 9643Page 109 9644October 31, 2013 9645 9646 Part 3: Commands 9647 964816.7.2 9649 9650Trusted Platform Module Library 9651 9652Command and Response 9653Table 53 — TPM2_ZGen_2Phase Command 9654 9655Type 9656 9657Name 9658 9659TPMI_ST_COMMAND_TAG 9660 9661tag 9662 9663UINT32 9664 9665commandSize 9666 9667TPM_CC 9668 9669commandCode 9670 9671Description 9672 9673TPM_CC_ZGen_2Phase 9674handle of an unrestricted decryption key ECC 9675The private key referenced by this handle is used as dS,A 9676 9677TPMI_DH_OBJECT 9678 9679@keyA 9680 9681TPM2B_ECC_POINT 9682 9683inQsB 9684 9685other party’s static public key (Qs,B = (Xs,B, Ys,B)) 9686 9687TPM2B_ECC_POINT 9688 9689inQeB 9690 9691other party's ephemeral public key (Qe,B = (Xe,B, Ye,B)) 9692 9693TPMI_ECC_KEY_EXCHANGE 9694 9695inScheme 9696 9697the key exchange scheme 9698 9699UINT16 9700 9701counter 9702 9703value returned by TPM2_EC_Ephemeral() 9704 9705Auth Index: 1 9706Auth Role: USER 9707 9708Table 54 — TPM2_ZGen_2Phase Response 9709Type 9710 9711Name 9712 9713TPM_ST 9714 9715tag 9716 9717UINT32 9718 9719responseSize 9720 9721TPM_RC 9722 9723responseCode 9724 9725TPM2B_ECC_POINT 9726 9727outZ1 9728 9729X and Y coordinates of the computed value (scheme 9730dependent) 9731 9732TPM2B_ECC_POINT 9733 9734outZ2 9735 9736X and Y coordinates of the second computed value 9737(scheme dependent) 9738 9739Page 110 9740October 31, 2013 9741 9742Description 9743 9744Published 9745Copyright © TCG 2006-2013 9746 9747Family “2.0” 9748Level 00 Revision 00.99 9749 9750 Trusted Platform Module Library 9751 975216.7.3 97531 97542 97553 9756 9757Part 3: Commands 9758 9759Detailed Actions 9760 9761#include "InternalRoutines.h" 9762#include "ZGen_2Phase_fp.h" 9763#if defined TPM_ALG_ECC && (CC_ZGen_2Phase == YES) 9764 9765This command uses the TPM to recover one or two Z values in a two phase key exchange protocol 9766Error Returns 9767TPM_RC_ATTRIBUTES 9768 9769key referenced by keyA is restricted or not a decrypt key 9770 9771TPM_RC_ECC_POINT 9772 9773inQsB or inQeB is not on the curve of the key reference by keyA 9774 9775TPM_RC_KEY 9776 9777key referenced by keyA is not an ECC key 9778 9779TPM_RC_SCHEME 9780 97814 97825 97836 97847 97858 97869 978710 978811 978912 979013 979114 979215 979316 979417 979518 979619 979720 979821 979922 980023 980124 980225 980326 980427 980528 980629 980730 980831 980932 981033 981134 981235 981336 981437 981538 981639 981740 981841 981942 982043 982144 982245 982346 982447 9825 9826Meaning 9827 9828the scheme of the key referenced by keyA is not TPM_ALG_NULL, 9829TPM_ALG_ECDH, TPM_ALG_ECMQV or TPM_ALG_SM2 9830 9831TPM_RC 9832TPM2_ZGen_2Phase( 9833ZGen_2Phase_In 9834ZGen_2Phase_Out 9835 9836*in, 9837*out 9838 9839// IN: input parameter list 9840// OUT: output parameter list 9841 9842) 9843{ 9844TPM_RC 9845OBJECT 9846TPM2B_ECC_PARAMETER 9847TPM_ALG_ID 9848 9849result; 9850*eccKey; 9851r; 9852scheme; 9853 9854// Input Validation 9855eccKey = ObjectGet(in->keyA); 9856// keyA must be an ECC key 9857if(eccKey->publicArea.type != TPM_ALG_ECC) 9858return TPM_RC_KEY + RC_ZGen_2Phase_keyA; 9859// keyA must not be restricted and must be a decrypt key 9860if( 9861eccKey->publicArea.objectAttributes.restricted == SET 9862|| eccKey->publicArea.objectAttributes.decrypt != SET 9863) 9864return TPM_RC_ATTRIBUTES + RC_ZGen_2Phase_keyA; 9865// if the scheme of keyA is TPM_ALG_NULL, then use the input scheme; otherwise 9866// the input scheme must be the same as the scheme of keyA 9867scheme = eccKey->publicArea.parameters.asymDetail.scheme.scheme; 9868if(scheme != TPM_ALG_NULL) 9869{ 9870if(scheme != in->inScheme) 9871return TPM_RC_SCHEME + RC_ZGen_2Phase_inScheme; 9872} 9873else 9874scheme = in->inScheme; 9875if(scheme == TPM_ALG_NULL) 9876return TPM_RC_SCHEME + RC_ZGen_2Phase_inScheme; 9877// Input points must be on the curve of keyA 9878if(!CryptEccIsPointOnCurve(eccKey->publicArea.parameters.eccDetail.curveID, 9879&in->inQsB.t.point)) 9880return TPM_RC_ECC_POINT + RC_ZGen_2Phase_inQsB; 9881if(!CryptEccIsPointOnCurve(eccKey->publicArea.parameters.eccDetail.curveID, 9882 9883Family “2.0” 9884Level 00 Revision 00.99 9885 9886Published 9887Copyright © TCG 2006-2013 9888 9889Page 111 9890October 31, 2013 9891 9892 Part 3: Commands 989348 989449 989550 989651 989752 989853 989954 990055 990156 990257 990358 990459 990560 990661 990762 990863 990964 991065 991166 991267 991368 991469 991570 991671 991772 991873 9919 9920Trusted Platform Module Library 9921 9922&in->inQeB.t.point)) 9923return TPM_RC_ECC_POINT + RC_ZGen_2Phase_inQeB; 9924if(!CryptGenerateR(&r, &in->counter, 9925eccKey->publicArea.parameters.eccDetail.curveID, 9926NULL)) 9927return TPM_RC_VALUE + RC_ZGen_2Phase_counter; 9928// Command Output 9929result = CryptEcc2PhaseKeyExchange(&out->outZ1.t.point, 9930&out->outZ2.t.point, 9931eccKey->publicArea.parameters.eccDetail.curveID, 9932scheme, 9933&eccKey->sensitive.sensitive.ecc, 9934&r, 9935&in->inQsB.t.point, 9936&in->inQeB.t.point); 9937if(result != TPM_RC_SUCCESS) 9938return result; 9939CryptEndCommit(in->counter); 9940return TPM_RC_SUCCESS; 9941} 9942#endif 9943 9944Page 112 9945October 31, 2013 9946 9947Published 9948Copyright © TCG 2006-2013 9949 9950Family “2.0” 9951Level 00 Revision 00.99 9952 9953 Trusted Platform Module Library 9954 995517 995617.1 9957 9958Part 3: Commands 9959 9960Symmetric Primitives 9961Introduction 9962 9963The commands in this clause provide low-level primitives for access to the symmetric algorithms 9964implemented in the TPM that operate on blocks of data. These include symmetric encryption and 9965decryption as well as hash and HMAC. All of the commands in this group are stateless. That is, they have 9966no persistent state that is retained in the TPM when the command is complete. 9967For hashing, HMAC, and Events that require large blocks of data with retained state, the sequence 9968commands are provided (see clause 1). 9969Some of the symmetric encryption/decryption modes use an IV. When an IV is used, it may be an 9970initiation value or a chained value from a previous stage. The chaining for each mode is: 9971 9972Family “2.0” 9973Level 00 Revision 00.99 9974 9975Published 9976Copyright © TCG 2006-2013 9977 9978Page 113 9979October 31, 2013 9980 9981 Part 3: Commands 9982 9983Trusted Platform Module Library 9984Table 55 — Symmetric Chaining Process 9985 9986Mode 9987 9988Chaining process 9989 9990TPM_ALG_CTR 9991 9992The TPM will increment the entire IV provided by the caller. The last encrypted value will be 9993returned to the caller as ivOut. This can be the input value to the next encrypted buffer. 9994ivIn is required to be the size of a block encrypted by the selected algorithm and key 9995combination. If the size of ivIn is not correct, the TPM shall return TPM_RC_SIZE. 9996EXAMPLE 1 AES requires that ivIn be 128 bits (16 octets). 9997 9998ivOut will be the size of a cipher block and not the size of the last encrypted block. 9999NOTE 10000 10001ivOut will be the value of the counter after the last block is encrypted. 10002 10003EXAMPLE 2 If ivIn were 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0016 and four data blocks 10004were encrypted, ivOut will have a value of 1000500 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0416. 10006 10007All the bits of the IV are incremented as if it were an unsigned integer. 10008TPM_ALG_OFB 10009 10010In Output Feedback (OFB), the output of the pseudo-random function (the block encryption 10011algorithm) is XORed with a plaintext block to produce a ciphertext block. ivOut will be the 10012value that was XORed with the last plaintext block. That value can be used as the ivIn for a 10013next buffer. 10014ivIn is required to be the size of a block encrypted by the selected algorithm and key 10015combination. If the size of ivIn is not correct, the TPM shall return TPM_RC_SIZE. 10016ivOut will be the size of a cipher block and not the size of the last encrypted block. 10017 10018TPM_ALG_CBC 10019 10020For Cipher Block Chaining (CBC), a block of ciphertext is XORed with the next plaintext 10021block and that block is encrypted. The encrypted block is then input to the encryption of the 10022next block. The last ciphertext block then is used as an IV for the next buffer. 10023Even though the last ciphertext block is evident in the encrypted data, it is also returned in 10024ivOut. 10025ivIn is required to be the size of a block encrypted by the selected algorithm and key 10026combination. If the size of ivIn is not correct, the TPM shall return TPM_RC_SIZE. 10027inData is required to be an even multiple of the block encrypted by the selected algorithm 10028and key combination. If the size of inData is not correct, the TPM shall return 10029TPM_RC_SIZE. 10030 10031TPM_ALG_CFB 10032 10033Similar to CBC in that the last ciphertext block is an input to the encryption of the next block. 10034ivOut will be the value that was XORed with the last plaintext block. That value can be used 10035as the ivIn for a next buffer. 10036ivIn is required to be the size of a block encrypted by the selected algorithm and key 10037combination. If the size of ivIn is not correct, the TPM shall return TPM_RC_SIZE. 10038ivOut will be the size of a cipher block and not the size of the last encrypted block. 10039 10040TPM_ALG_ECB 10041 10042Electronic Codebook (ECB) has no chaining. Each block of plaintext is encrypted using the 10043key. ECB does not support chaining and ivIn shall be the Empty Buffer. ivOut will be the 10044Empty Buffer. 10045inData is required to be an even multiple of the block encrypted by the selected algorithm 10046and key combination. If the size of inData is not correct, the TPM shall return 10047TPM_RC_SIZE. 10048 10049Page 114 10050October 31, 2013 10051 10052Published 10053Copyright © TCG 2006-2013 10054 10055Family “2.0” 10056Level 00 Revision 00.99 10057 10058 Trusted Platform Module Library 10059 1006017.2 10061 10062Part 3: Commands 10063 10064TPM2_EncryptDecrypt 10065 1006617.2.1 General Description 10067This command performs symmetric encryption or decryption. 10068keyHandle shall reference a symmetric cipher object (TPM_RC_KEY). 10069For a restricted key, mode shall be either the same as the mode of the key, or TPM_ALG_NULL 10070(TPM_RC_VALUE). For an unrestricted key, mode may be the same or different from the mode of the key 10071but both shall not be TPM_ALG_NULL (TPM_RC_VALUE). 10072If the TPM allows this command to be canceled before completion, then the TPM may produce 10073incremental results and return TPM_RC_SUCCESS rather than TPM_RC_CANCEL. In such case, 10074outData may be less than inData. 10075 10076Family “2.0” 10077Level 00 Revision 00.99 10078 10079Published 10080Copyright © TCG 2006-2013 10081 10082Page 115 10083October 31, 2013 10084 10085 Part 3: Commands 10086 10087Trusted Platform Module Library 10088 1008917.2.2 Command and Response 10090Table 56 — TPM2_EncryptDecrypt Command 10091Type 10092 10093Name 10094 10095Description 10096 10097TPMI_ST_COMMAND_TAG 10098 10099tag 10100 10101UINT32 10102 10103commandSize 10104 10105TPM_CC 10106 10107commandCode 10108 10109TPM_CC_EncryptDecrypt 10110 10111TPMI_DH_OBJECT 10112 10113@keyHandle 10114 10115the symmetric key used for the operation 10116Auth Index: 1 10117Auth Role: USER 10118 10119TPMI_YES_NO 10120 10121decrypt 10122 10123if YES, then the operation is decryption; if NO, the 10124operation is encryption 10125 10126TPMI_ALG_SYM_MODE+ 10127 10128mode 10129 10130symmetric mode 10131For a restricted key, this field shall match the default 10132mode of the key or be TPM_ALG_NULL. 10133 10134TPM2B_IV 10135 10136ivIn 10137 10138an initial value as required by the algorithm 10139 10140TPM2B_MAX_BUFFER 10141 10142inData 10143 10144the data to be encrypted/decrypted 10145 10146Table 57 — TPM2_EncryptDecrypt Response 10147Type 10148 10149Name 10150 10151Description 10152 10153TPM_ST 10154 10155tag 10156 10157see clause 8 10158 10159UINT32 10160 10161responseSize 10162 10163TPM_RC 10164 10165responseCode 10166 10167TPM2B_MAX_BUFFER 10168 10169outData 10170 10171encrypted output 10172 10173TPM2B_IV 10174 10175ivOut 10176 10177chaining value to use for IV in next round 10178 10179Page 116 10180October 31, 2013 10181 10182Published 10183Copyright © TCG 2006-2013 10184 10185Family “2.0” 10186Level 00 Revision 00.99 10187 10188 Trusted Platform Module Library 10189 10190Part 3: Commands 10191 1019217.2.3 Detailed Actions 101931 101942 10195 10196#include "InternalRoutines.h" 10197#include "EncryptDecrypt_fp.h" 10198Error Returns 10199TPM_RC_KEY 10200 10201is not a symmetric decryption key with both public and private 10202portions loaded 10203 10204TPM_RC_SIZE 10205 10206IvIn size is incompatible with the block cipher mode; or inData size is 10207not an even multiple of the block size for CBC or ECB mode 10208 10209TPM_RC_VALUE 10210 102113 102124 102135 102146 102157 102168 102179 1021810 1021911 1022012 1022113 1022214 1022315 1022416 1022517 1022618 1022719 1022820 1022921 1023022 1023123 1023224 1023325 1023426 1023527 1023628 1023729 1023830 1023931 1024032 1024133 1024234 1024335 1024436 1024537 1024638 1024739 1024840 1024941 1025042 1025143 1025244 1025345 1025446 1025547 1025648 10257 10258Meaning 10259 10260keyHandle is restricted and the argument mode does not match the 10261key's mode 10262 10263TPM_RC 10264TPM2_EncryptDecrypt( 10265EncryptDecrypt_In 10266EncryptDecrypt_Out 10267 10268*in, 10269*out 10270 10271// IN: input parameter list 10272// OUT: output parameter list 10273 10274) 10275{ 10276OBJECT 10277UINT16 10278UINT16 10279BYTE 10280TPM_ALG_ID 10281 10282*symKey; 10283keySize; 10284blockSize; 10285*key; 10286alg; 10287 10288// Input Validation 10289symKey = ObjectGet(in->keyHandle); 10290// The input key should be a symmetric decrypt key. 10291if( 10292symKey->publicArea.type != TPM_ALG_SYMCIPHER 10293|| symKey->attributes.publicOnly == SET) 10294return TPM_RC_KEY + RC_EncryptDecrypt_keyHandle; 10295// If the input mode is TPM_ALG_NULL, use the key's mode 10296if( in->mode == TPM_ALG_NULL) 10297in->mode = symKey->publicArea.parameters.symDetail.sym.mode.sym; 10298// If the key is restricted, the input sym mode should match the key's sym 10299// mode 10300if( 10301symKey->publicArea.objectAttributes.restricted == SET 10302&& symKey->publicArea.parameters.symDetail.sym.mode.sym != in->mode) 10303return TPM_RC_VALUE + RC_EncryptDecrypt_mode; 10304// If the mode is null, then we have a problem. 10305// Note: Construction of a TPMT_SYM_DEF does not allow the 'mode' to be 10306// TPM_ALG_NULL so setting in->mode to the mode of the key should have 10307// produced a valid mode. However, this is suspenders. 10308if(in->mode == TPM_ALG_NULL) 10309return TPM_RC_VALUE + RC_EncryptDecrypt_mode; 10310// The input iv for ECB mode should be null. All the other modes should 10311// have an iv size same as encryption block size 10312keySize = symKey->publicArea.parameters.symDetail.sym.keyBits.sym; 10313alg = symKey->publicArea.parameters.symDetail.sym.algorithm; 10314blockSize = CryptGetSymmetricBlockSize(alg, keySize); 10315if( 10316(in->mode == TPM_ALG_ECB && in->ivIn.t.size != 0) 10317|| (in->mode != TPM_ALG_ECB && in->ivIn.t.size != blockSize)) 10318return TPM_RC_SIZE + RC_EncryptDecrypt_ivIn; 10319 10320Family “2.0” 10321Level 00 Revision 00.99 10322 10323Published 10324Copyright © TCG 2006-2013 10325 10326Page 117 10327October 31, 2013 10328 10329 Part 3: Commands 1033049 1033150 1033251 1033352 1033453 1033554 1033655 1033756 1033857 1033958 1034059 1034160 1034261 1034362 1034463 1034564 1034665 1034766 1034867 1034968 1035069 1035170 1035271 1035372 1035473 1035574 1035675 1035776 1035877 1035978 1036079 1036180 1036281 1036382 1036483 1036584 1036685 1036786 1036887 1036988 1037089 1037190 1037291 10373 10374Trusted Platform Module Library 10375 10376// The input data size of CBC mode or ECB mode must be an even multiple of 10377// the symmetric algorithm's block size 10378if( 10379(in->mode == TPM_ALG_CBC || in->mode == TPM_ALG_ECB) 10380&& (in->inData.t.size % blockSize) != 0) 10381return TPM_RC_SIZE + RC_EncryptDecrypt_inData; 10382// Copy IV 10383// Note: This is copied here so that the calls to the encrypt/decrypt functions 10384// will modify the output buffer, not the input buffer 10385out->ivOut = in->ivIn; 10386// Command Output 10387key = symKey->sensitive.sensitive.sym.t.buffer; 10388// For symmetric encryption, the cipher data size is the same as plain data 10389// size. 10390out->outData.t.size = in->inData.t.size; 10391if(in->decrypt == YES) 10392{ 10393// Decrypt data to output 10394CryptSymmetricDecrypt(out->outData.t.buffer, 10395alg, 10396keySize, in->mode, key, 10397&(out->ivOut), 10398in->inData.t.size, 10399in->inData.t.buffer); 10400} 10401else 10402{ 10403// Encrypt data to output 10404CryptSymmetricEncrypt(out->outData.t.buffer, 10405alg, 10406keySize, 10407in->mode, key, 10408&(out->ivOut), 10409in->inData.t.size, 10410in->inData.t.buffer); 10411} 10412return TPM_RC_SUCCESS; 10413} 10414 10415Page 118 10416October 31, 2013 10417 10418Published 10419Copyright © TCG 2006-2013 10420 10421Family “2.0” 10422Level 00 Revision 00.99 10423 10424 Trusted Platform Module Library 10425 1042617.3 10427 10428Part 3: Commands 10429 10430TPM2_Hash 10431 1043217.3.1 General Description 10433This command performs a hash operation on a data buffer and returns the results. 10434NOTE 10435 10436If the data buffer to be hashed is larger than will fit into the TPM’s input buffer, then the sequence 10437hash commands will need to be used. 10438 10439If the results of the hash will be used in a signing operation that uses a restricted signing key, then the 10440ticket returned by this command can indicate that the hash is safe to sign. 10441If the digest is not safe to sign, then the TPM will return a TPMT_TK_HASHCHECK with the hierarchy set 10442to TPM_RH_NULL and digest set to the Empty Buffer. 10443If hierarchy is TPM_RH_NULL, then digest in the ticket will be the Empty Buffer. 10444 10445Family “2.0” 10446Level 00 Revision 00.99 10447 10448Published 10449Copyright © TCG 2006-2013 10450 10451Page 119 10452October 31, 2013 10453 10454 Part 3: Commands 10455 10456Trusted Platform Module Library 10457 1045817.3.2 Command and Response 10459Table 58 — TPM2_Hash Command 10460Type 10461 10462Name 10463 10464Description 10465 10466TPMI_ST_COMMAND_TAG 10467 10468tag 10469 10470Shall have at least one session 10471 10472UINT32 10473 10474commandSize 10475 10476TPM_CC 10477 10478commandCode 10479 10480TPM_CC_Hash 10481 10482TPM2B_MAX_BUFFER 10483 10484data 10485 10486data to be hashed 10487 10488TPMI_ALG_HASH 10489 10490hashAlg 10491 10492algorithm for the hash being computed – shall not be 10493TPM_ALG_NULL 10494 10495TPMI_RH_HIERARCHY+ 10496 10497hierarchy 10498 10499hierarchy to use for the ticket (TPM_RH_NULL allowed) 10500 10501Table 59 — TPM2_Hash Response 10502Type 10503 10504Name 10505 10506Description 10507 10508TPM_ST 10509 10510tag 10511 10512see clause 8 10513 10514UINT32 10515 10516responseSize 10517 10518TPM_RC 10519 10520responseCode 10521 10522TPM2B_DIGEST 10523 10524outHash 10525 10526results 10527 10528TPMT_TK_HASHCHECK 10529 10530validation 10531 10532ticket indicating that the sequence of octets used to 10533compute outDigest did not start with 10534TPM_GENERATED_VALUE 10535will be a NULL ticket if the digest may not be signed 10536with a restricted key 10537 10538Page 120 10539October 31, 2013 10540 10541Published 10542Copyright © TCG 2006-2013 10543 10544Family “2.0” 10545Level 00 Revision 00.99 10546 10547 Trusted Platform Module Library 10548 10549Part 3: Commands 10550 1055117.3.3 Detailed Actions 105521 105532 105543 105554 105565 105576 105587 105598 105609 1056110 1056211 1056312 1056413 1056514 1056615 1056716 1056817 1056918 1057019 1057120 1057221 1057322 1057423 1057524 1057625 1057726 1057827 1057928 1058029 1058130 1058231 1058332 1058433 1058534 1058635 1058736 1058837 1058938 1059039 1059140 1059241 1059342 1059443 1059544 1059645 10597 10598#include "InternalRoutines.h" 10599#include "Hash_fp.h" 10600 10601TPM_RC 10602TPM2_Hash( 10603Hash_In 10604Hash_Out 10605 10606*in, 10607*out 10608 10609// IN: input parameter list 10610// OUT: output parameter list 10611 10612) 10613{ 10614HASH_STATE 10615 10616hashState; 10617 10618// Command Output 10619// Output hash 10620// Start hash stack 10621out->outHash.t.size = CryptStartHash(in->hashAlg, &hashState); 10622// Adding hash data 10623CryptUpdateDigest2B(&hashState, &in->data.b); 10624// Complete hash 10625CryptCompleteHash2B(&hashState, &out->outHash.b); 10626// Output ticket 10627out->validation.tag = TPM_ST_HASHCHECK; 10628out->validation.hierarchy = in->hierarchy; 10629if(in->hierarchy == TPM_RH_NULL) 10630{ 10631// Ticket is not required 10632out->validation.hierarchy = TPM_RH_NULL; 10633out->validation.digest.t.size = 0; 10634} 10635else if( in->data.t.size >= sizeof(TPM_GENERATED) 10636&& !TicketIsSafe(&in->data.b)) 10637{ 10638// Ticket is not safe 10639out->validation.hierarchy = TPM_RH_NULL; 10640out->validation.digest.t.size = 0; 10641} 10642else 10643{ 10644// Compute ticket 10645TicketComputeHashCheck(in->hierarchy, &out->outHash, &out->validation); 10646} 10647return TPM_RC_SUCCESS; 10648} 10649 10650Family “2.0” 10651Level 00 Revision 00.99 10652 10653Published 10654Copyright © TCG 2006-2013 10655 10656Page 121 10657October 31, 2013 10658 10659 Part 3: Commands 10660 1066117.4 10662 10663Trusted Platform Module Library 10664 10665TPM2_HMAC 10666 1066717.4.1 General Description 10668This command performs an HMAC on the supplied data using the indicated hash algorithm. 10669The caller shall provide proper authorization for use of handle. 10670If the sign attribute is not SET in the key referenced by handle then the TPM shall return 10671TPM_RC_ATTRIBUTES. If the key type is not TPM_ALG_KEYEDHASH then the TPM shall return 10672TPM_RC_TYPE. 10673If handle references a restricted key, then the hash algorithm specified in the key's scheme is used as the 10674hash algorithm for the HMAC and the TPM shall return TPM_RC_VALUE if hashAlg is not 10675TPM_ALG_NULL or the same algorithm as selected in the key's scheme. 10676NOTE 1 10677A restricted key may only have one of sign or decrypt SET and the default scheme may not 10678be TPM_ALG_NULL. These restrictions are enforced by TPM2_Create() and TPM2_CreatePrimary(), 10679If the key referenced by handle is not restricted, then the TPM will use hashAlg for the HMAC. However, if 10680hashAlg is TPM_ALG_NULL the TPM will use the default scheme of the key. 10681If both hashAlg and the key default are TPM_ALG_NULL, the TPM shall return TPM_RC_VALUE. 10682NOTE 10683 10684A key may only have both sign and decrypt SET if the key is unrestricted. When bo th sign and 10685decrypt are set, there is no default scheme for the key and the hash algorithm must be specified . 10686 10687Page 122 10688October 31, 2013 10689 10690Published 10691Copyright © TCG 2006-2013 10692 10693Family “2.0” 10694Level 00 Revision 00.99 10695 10696 Trusted Platform Module Library 10697 10698Part 3: Commands 10699 1070017.4.2 Command and Response 10701Table 60 — TPM2_HMAC Command 10702Type 10703 10704Name 10705 10706Description 10707 10708TPMI_ST_COMMAND_TAG 10709 10710tag 10711 10712UINT32 10713 10714commandSize 10715 10716TPM_CC 10717 10718commandCode 10719 10720TPM_CC_HMAC 10721 10722TPMI_DH_OBJECT 10723 10724@handle 10725 10726handle for the symmetric signing key providing the 10727HMAC key 10728Auth Index: 1 10729Auth Role: USER 10730 10731TPM2B_MAX_BUFFER 10732 10733buffer 10734 10735HMAC data 10736 10737TPMI_ALG_HASH+ 10738 10739hashAlg 10740 10741algorithm to use for HMAC 10742 10743Table 61 — TPM2_HMAC Response 10744Type 10745 10746Name 10747 10748Description 10749 10750TPM_ST 10751 10752tag 10753 10754see clause 8 10755 10756UINT32 10757 10758responseSize 10759 10760TPM_RC 10761 10762responseCode 10763 10764TPM2B_DIGEST 10765 10766outHMAC 10767 10768Family “2.0” 10769Level 00 Revision 00.99 10770 10771the returned HMAC in a sized buffer 10772 10773Published 10774Copyright © TCG 2006-2013 10775 10776Page 123 10777October 31, 2013 10778 10779 Part 3: Commands 10780 10781Trusted Platform Module Library 10782 1078317.4.3 Detailed Actions 107841 107852 10786 10787#include "InternalRoutines.h" 10788#include "HMAC_fp.h" 10789Error Returns 10790TPM_RC_ATTRIBUTES 10791 10792key referenced by handle is not a signing key 10793 10794TPM_RC_TYPE 10795 10796key referenced by handle is not an HMAC key 10797 10798TPM_RC_VALUE 10799 108003 108014 108025 108036 108047 108058 108069 1080710 1080811 1080912 1081013 1081114 1081215 1081316 1081417 1081518 1081619 1081720 1081821 1081922 1082023 1082124 1082225 1082326 1082427 1082528 1082629 1082730 1082831 1082932 1083033 1083134 1083235 1083336 1083437 1083538 1083639 1083740 1083841 1083942 1084043 1084144 1084245 1084346 1084447 1084548 1084649 10847 10848Meaning 10849 10850hashAlg specified when the key is restricted is neither 10851TPM_ALG_NULL not equal to that of the key scheme; or both 10852hashAlg and the key scheme's algorithm are TPM_ALG_NULL 10853 10854TPM_RC 10855TPM2_HMAC( 10856HMAC_In 10857HMAC_Out 10858 10859*in, 10860*out 10861 10862// IN: input parameter list 10863// OUT: output parameter list 10864 10865HMAC_STATE 10866OBJECT 10867TPMI_ALG_HASH 10868TPMT_PUBLIC 10869 10870hmacState; 10871*hmacObject; 10872hashAlg; 10873*publicArea; 10874 10875) 10876{ 10877 10878// Input Validation 10879// Get HMAC key object and public area pointers 10880hmacObject = ObjectGet(in->handle); 10881publicArea = &hmacObject->publicArea; 10882// Make sure that the key is an HMAC signing key 10883if(publicArea->type != TPM_ALG_KEYEDHASH) 10884return TPM_RC_TYPE + RC_HMAC_handle; 10885if(publicArea->objectAttributes.sign != SET) 10886return TPM_RC_ATTRIBUTES + RC_HMAC_handle; 10887// Assume that the key default scheme is used 10888hashAlg = publicArea->parameters.keyedHashDetail.scheme.details.hmac.hashAlg; 10889// if the key is restricted, then need to use the scheme of the key and the 10890// input algorithm must be TPM_ALG_NULL or the same as the key scheme 10891if(publicArea->objectAttributes.restricted == SET) 10892{ 10893if(in->hashAlg != TPM_ALG_NULL && in->hashAlg != hashAlg) 10894hashAlg = TPM_ALG_NULL; 10895} 10896else 10897{ 10898// for a non-restricted key, use hashAlg if it is provided; 10899if(in->hashAlg != TPM_ALG_NULL) 10900hashAlg = in->hashAlg; 10901} 10902// if the hashAlg is TPM_ALG_NULL, then the input hashAlg is not compatible 10903// with the key scheme or type 10904if(hashAlg == TPM_ALG_NULL) 10905return TPM_RC_VALUE + RC_HMAC_hashAlg; 10906// Command Output 10907 10908Page 124 10909October 31, 2013 10910 10911Published 10912Copyright © TCG 2006-2013 10913 10914Family “2.0” 10915Level 00 Revision 00.99 10916 10917 Trusted Platform Module Library 1091850 1091951 1092052 1092153 1092254 1092355 1092456 1092557 1092658 1092759 1092860 1092961 10930 10931Part 3: Commands 10932 10933// Start HMAC stack 10934out->outHMAC.t.size = CryptStartHMAC2B(hashAlg, 10935&hmacObject->sensitive.sensitive.bits.b, 10936&hmacState); 10937// Adding HMAC data 10938CryptUpdateDigest2B(&hmacState, &in->buffer.b); 10939// Complete HMAC 10940CryptCompleteHMAC2B(&hmacState, &out->outHMAC.b); 10941return TPM_RC_SUCCESS; 10942} 10943 10944Family “2.0” 10945Level 00 Revision 00.99 10946 10947Published 10948Copyright © TCG 2006-2013 10949 10950Page 125 10951October 31, 2013 10952 10953 Part 3: Commands 10954 1095518 10956 10957Trusted Platform Module Library 10958 10959Random Number Generator 10960 1096118.1 10962 10963TPM2_GetRandom 10964 1096518.1.1 General Description 10966This command returns the next bytesRequested octets from the random number generator (RNG). 10967NOTE 1 10968 10969It is recommended that a TPM implement the RNG in a manner that would allow it to return RNG 10970octets such that the frequency of bytesRequested being more than the number of octets available is 10971an infrequent occurrence. 10972 10973If bytesRequested is more than will fit into a TPM2B_DIGEST on the TPM, no error is returned but the 10974TPM will only return as much data as will fit into a TPM2B_DIGEST buffer for the TPM. 10975NOTE 2 10976 10977TPM2B_DIGEST is large enough to hold the largest digest that may be produced by the TPM. 10978Because that digest size changes according to the implemented hashes, the maximum amount of 10979data returned by this command is TPM implementation-dependent. 10980 10981Page 126 10982October 31, 2013 10983 10984Published 10985Copyright © TCG 2006-2013 10986 10987Family “2.0” 10988Level 00 Revision 00.99 10989 10990 Trusted Platform Module Library 10991 10992Part 3: Commands 10993 1099418.1.2 Command and Response 10995Table 62 — TPM2_GetRandom Command 10996Type 10997 10998Name 10999 11000Description 11001 11002TPMI_ST_COMMAND_TAG 11003 11004tag 11005 11006UINT32 11007 11008commandSize 11009 11010TPM_CC 11011 11012commandCode 11013 11014TPM_CC_GetRandom 11015 11016UINT16 11017 11018bytesRequested 11019 11020number of octets to return 11021 11022Table 63 — TPM2_GetRandom Response 11023Type 11024 11025Name 11026 11027Description 11028 11029TPM_ST 11030 11031tag 11032 11033see clause 8 11034 11035UINT32 11036 11037responseSize 11038 11039TPM_RC 11040 11041responseCode 11042 11043TPM2B_DIGEST 11044 11045randomBytes 11046 11047Family “2.0” 11048Level 00 Revision 00.99 11049 11050the random octets 11051 11052Published 11053Copyright © TCG 2006-2013 11054 11055Page 127 11056October 31, 2013 11057 11058 Part 3: Commands 11059 11060Trusted Platform Module Library 11061 1106218.1.3 Detailed Actions 110631 110642 110653 110664 110675 110686 110697 110708 110719 1107210 1107311 1107412 1107513 1107614 1107715 1107816 1107917 1108018 1108119 1108220 1108321 11084 11085#include "InternalRoutines.h" 11086#include "GetRandom_fp.h" 11087 11088TPM_RC 11089TPM2_GetRandom( 11090GetRandom_In 11091GetRandom_Out 11092 11093*in, 11094*out 11095 11096// IN: input parameter list 11097// OUT: output parameter list 11098 11099) 11100{ 11101// Command Output 11102// if the requested bytes exceed the output buffer size, generates the 11103// maximum bytes that the output buffer allows 11104if(in->bytesRequested > sizeof(TPMU_HA)) 11105out->randomBytes.t.size = sizeof(TPMU_HA); 11106else 11107out->randomBytes.t.size = in->bytesRequested; 11108CryptGenerateRandom(out->randomBytes.t.size, out->randomBytes.t.buffer); 11109return TPM_RC_SUCCESS; 11110} 11111 11112Page 128 11113October 31, 2013 11114 11115Published 11116Copyright © TCG 2006-2013 11117 11118Family “2.0” 11119Level 00 Revision 00.99 11120 11121 Trusted Platform Module Library 11122 1112318.2 11124 11125Part 3: Commands 11126 11127TPM2_StirRandom 11128 1112918.2.1 General Description 11130This command is used to add "additional information" to the RNG state. 11131NOTE 11132 11133The "additional information" is as defined in SP800 -90A. 11134 11135The inData parameter may not be larger than 128 octets. 11136 11137Family “2.0” 11138Level 00 Revision 00.99 11139 11140Published 11141Copyright © TCG 2006-2013 11142 11143Page 129 11144October 31, 2013 11145 11146 Part 3: Commands 11147 11148Trusted Platform Module Library 11149 1115018.2.2 Command and Response 11151Table 64 — TPM2_StirRandom Command 11152Type 11153 11154Name 11155 11156Description 11157 11158TPMI_ST_COMMAND_TAG 11159 11160tag 11161 11162UINT32 11163 11164commandSize 11165 11166TPM_CC 11167 11168commandCode 11169 11170TPM_CC_StirRandom {NV} 11171 11172TPM2B_SENSITIVE_DATA 11173 11174inData 11175 11176additional information 11177 11178Table 65 — TPM2_StirRandom Response 11179Type 11180 11181Name 11182 11183Description 11184 11185TPM_ST 11186 11187tag 11188 11189see clause 8 11190 11191UINT32 11192 11193responseSize 11194 11195TPM_RC 11196 11197responseCode 11198 11199Page 130 11200October 31, 2013 11201 11202Published 11203Copyright © TCG 2006-2013 11204 11205Family “2.0” 11206Level 00 Revision 00.99 11207 11208 Trusted Platform Module Library 11209 11210Part 3: Commands 11211 1121218.2.3 Detailed Actions 112131 112142 112153 112164 112175 112186 112197 112208 112219 1122210 1122311 1122412 11225 11226#include "InternalRoutines.h" 11227#include "StirRandom_fp.h" 11228 11229TPM_RC 11230TPM2_StirRandom( 11231StirRandom_In 11232*in 11233// IN: input parameter list 11234) 11235{ 11236// Internal Data Update 11237CryptStirRandom(in->inData.t.size, in->inData.t.buffer); 11238return TPM_RC_SUCCESS; 11239} 11240 11241Family “2.0” 11242Level 00 Revision 00.99 11243 11244Published 11245Copyright © TCG 2006-2013 11246 11247Page 131 11248October 31, 2013 11249 11250 Part 3: Commands 11251 1125219 11253 11254Trusted Platform Module Library 11255 11256Hash/HMAC/Event Sequences 11257 1125819.1 11259 11260Introduction 11261 11262All of the commands in this group are to support sequences for which an intermediate state must be 11263maintained. For a description of sequences, see “Hash, HMAC, and Event Sequences” in Part 1. 1126419.2 11265 11266TPM2_HMAC_Start 11267 1126819.2.1 General Description 11269This command starts an HMAC sequence. The TPM will create and initialize an HMAC sequence 11270structure, assign a handle to the sequence, and set the authValue of the sequence object to the value in 11271auth. 11272NOTE 1 11273 11274The structure of a sequence object is vendor -dependent. 11275 11276The caller shall provide proper authorization for use of handle. 11277If the sign attribute is not SET in the key referenced by handle then the TPM shall return 11278TPM_RC_ATTRIBUTES. If the key type is not TPM_ALG_KEYEDHASH then the TPM shall return 11279TPM_RC_TYPE. 11280If handle references a restricted key, then the hash algorithm specified in the key's scheme is used as the 11281hash algorithm for the HMAC and the TPM shall return TPM_RC_VALUE if hashAlg is not 11282TPM_ALG_NULL or the same algorithm in the key's scheme. 11283If the key referenced by handle is not restricted, then the TPM will use hashAlg for the HMAC; unless 11284hashAlg is TPM_ALG_NULL in which case it will use the default scheme of the key. 11285Table 66 — Hash Selection Matrix 11286handle→restricted 11287(key's restricted 11288attribute) 11289 11290handle→scheme 11291(hash algorithm 11292from key's scheme) 11293 11294CLEAR (unrestricted) 11295 11296TPM_ALG_NULL 11297 11298CLEAR 11299 11300don’t care 11301 11302CLEAR 11303 11304valid hash 11305 11306hash used 11307 11308TPM_ALG_NULL 11309 11310error 11311 11312valid hash 11313 11314(1) 11315 11316hashAlg 11317 11318hashAlg 11319 11320(2) 11321 11322(TPM_RC_SCHEME) 11323 11324TPM_ALG_NULL 11325 11326handle→scheme 11327 11328same as handle→scheme 11329 11330handle→scheme 11331 11332(3) 11333 11334SET 11335 11336handle→scheme 11337 11338(3) 11339 11340SET (restricted) 11341 11342TPM_ALG_NULL 11343 11344(3) 11345 11346not same as 11347handle→scheme 11348 11349error 11350 11351valid hash 11352valid hash 11353 11354SET 11355 11356valid hash 11357 11358(4) 11359 11360(TPM_RC_SCHEME) 11361 11362NOTES: 113631) 11364 11365The scheme for the handle may only be TPM_ALG_NULL if both sign and decrypt are SET. 11366 113672) 11368 11369A hash algorithm is required for the HMAC. 11370 113713) 11372 11373A restricted key is required to have a scheme with a valid hash algorithm. A restricted key may not have both sign and 11374decrypt SET. 11375 113764) 11377 11378The scheme for a restricted key cannot be overridden. 11379 11380Page 132 11381October 31, 2013 11382 11383Published 11384Copyright © TCG 2006-2013 11385 11386Family “2.0” 11387Level 00 Revision 00.99 11388 11389 Trusted Platform Module Library 11390 11391Part 3: Commands 11392 1139319.2.2 Command and Response 11394Table 67 — TPM2_HMAC_Start Command 11395Type 11396 11397Name 11398 11399Description 11400 11401TPMI_ST_COMMAND_TAG 11402 11403tag 11404 11405UINT32 11406 11407commandSize 11408 11409TPM_CC 11410 11411commandCode 11412 11413TPM_CC_HMAC_Start 11414 11415TPMI_DH_OBJECT 11416 11417@handle 11418 11419handle of an HMAC key 11420Auth Index: 1 11421Auth Role: USER 11422 11423TPM2B_AUTH 11424 11425auth 11426 11427authorization value for subsequent use of the sequence 11428 11429TPMI_ALG_HASH+ 11430 11431hashAlg 11432 11433the hash algorithm to use for the HMAC 11434 11435Table 68 — TPM2_HMAC_Start Response 11436Type 11437 11438Name 11439 11440Description 11441 11442TPM_ST 11443 11444tag 11445 11446see clause 8 11447 11448UINT32 11449 11450responseSize 11451 11452TPM_RC 11453 11454responseCode 11455 11456TPMI_DH_OBJECT 11457 11458sequenceHandle 11459 11460Family “2.0” 11461Level 00 Revision 00.99 11462 11463a handle to reference the sequence 11464 11465Published 11466Copyright © TCG 2006-2013 11467 11468Page 133 11469October 31, 2013 11470 11471 Part 3: Commands 11472 11473Trusted Platform Module Library 11474 1147519.2.3 Detailed Actions 114761 114772 11478 11479#include "InternalRoutines.h" 11480#include "HMAC_Start_fp.h" 11481Error Returns 11482TPM_RC_ATTRIBUTES 11483 11484key referenced by handle is not a signing key 11485 11486TPM_RC_OBJECT_MEMORY 11487 11488no space to create an internal object 11489 11490TPM_RC_TYPE 11491 11492key referenced by handle is not an HMAC key 11493 11494TPM_RC_VALUE 11495 114963 114974 114985 114996 115007 115018 115029 1150310 1150411 1150512 1150613 1150714 1150815 1150916 1151017 1151118 1151219 1151320 1151421 1151522 1151623 1151724 1151825 1151926 1152027 1152128 1152229 1152330 1152431 1152532 1152633 1152734 1152835 1152936 1153037 1153138 1153239 1153340 1153441 1153542 1153643 1153744 1153845 1153946 1154047 11541 11542Meaning 11543 11544hashAlg specified when the key is restricted is neither 11545TPM_ALG_NULL not equal to that of the key scheme; or both 11546hashAlg and the key scheme's algorithm are TPM_ALG_NULL 11547 11548TPM_RC 11549TPM2_HMAC_Start( 11550HMAC_Start_In 11551HMAC_Start_Out 11552 11553*in, 11554*out 11555 11556// IN: input parameter list 11557// OUT: output parameter list 11558 11559) 11560{ 11561OBJECT 11562TPMT_PUBLIC 11563TPM_ALG_ID 11564 11565*hmacObject; 11566*publicArea; 11567hashAlg; 11568 11569// Input Validation 11570// Get HMAC key object and public area pointers 11571hmacObject = ObjectGet(in->handle); 11572publicArea = &hmacObject->publicArea; 11573// Make sure that the key is an HMAC signing key 11574if(publicArea->type != TPM_ALG_KEYEDHASH) 11575return TPM_RC_TYPE + RC_HMAC_Start_handle; 11576if(publicArea->objectAttributes.sign != SET) 11577return TPM_RC_ATTRIBUTES + RC_HMAC_Start_handle; 11578// Assume that the key default scheme is used 11579hashAlg = publicArea->parameters.keyedHashDetail.scheme.details.hmac.hashAlg; 11580// if the key is restricted, then need to use the scheme of the key and the 11581// input algorithm must be TPM_ALG_NULL or the same as the key scheme 11582if(publicArea->objectAttributes.restricted == SET) 11583{ 11584if(in->hashAlg != TPM_ALG_NULL && in->hashAlg != hashAlg) 11585hashAlg = TPM_ALG_NULL; 11586} 11587else 11588{ 11589// for a non-restricted key, use hashAlg if it is provided; 11590if(in->hashAlg != TPM_ALG_NULL) 11591hashAlg = in->hashAlg; 11592} 11593// if the algorithm selection ended up with TPM_ALG_NULL, then either the 11594// schemes are not compatible or no hash was provided and both conditions 11595// are errors. 11596if(hashAlg == TPM_ALG_NULL) 11597return TPM_RC_VALUE + RC_HMAC_Start_hashAlg; 11598// Internal Data Update 11599 11600Page 134 11601October 31, 2013 11602 11603Published 11604Copyright © TCG 2006-2013 11605 11606Family “2.0” 11607Level 00 Revision 00.99 11608 11609 Trusted Platform Module Library 1161048 1161149 1161250 1161351 1161452 1161553 1161654 1161755 11618 11619Part 3: Commands 11620 11621// Create a HMAC sequence object. A TPM_RC_OBJECT_MEMORY error may be 11622// returned at this point 11623return ObjectCreateHMACSequence(hashAlg, 11624in->handle, 11625&in->auth, 11626&out->sequenceHandle); 11627} 11628 11629Family “2.0” 11630Level 00 Revision 00.99 11631 11632Published 11633Copyright © TCG 2006-2013 11634 11635Page 135 11636October 31, 2013 11637 11638 Part 3: Commands 11639 1164019.3 11641 11642Trusted Platform Module Library 11643 11644TPM2_HashSequenceStart 11645 1164619.3.1 General Description 11647This command starts a hash or an Event sequence. If hashAlg is an implemented hash, then a hash 11648sequence is started. If hashAlg is TPM_ALG_NULL, then an Event sequence is started. If hashAlg is 11649neither an implemented algorithm nor TPM_ALG_NULL, then the TPM shall return TPM_RC_HASH. 11650Depending on hashAlg, the TPM will create and initialize a hash sequence structure or an Event 11651sequence structure. Additionally, it will assign a handle to the sequence and set the authValue of the 11652sequence to the value in auth. A sequence structure for an Event (hashAlg = TPM_ALG_NULL) contains 11653a hash context for each of the PCR banks implemented on the TPM. 11654 11655Page 136 11656October 31, 2013 11657 11658Published 11659Copyright © TCG 2006-2013 11660 11661Family “2.0” 11662Level 00 Revision 00.99 11663 11664 Trusted Platform Module Library 11665 11666Part 3: Commands 11667 1166819.3.2 Command and Response 11669Table 69 — TPM2_HashSequenceStart Command 11670Type 11671 11672Name 11673 11674Description 11675 11676TPMI_ST_COMMAND_TAG 11677 11678tag 11679 11680UINT32 11681 11682commandSize 11683 11684TPM_CC 11685 11686commandCode 11687 11688TPM_CC_HashSequenceStart 11689 11690TPM2B_AUTH 11691 11692auth 11693 11694authorization value for subsequent use of the sequence 11695 11696TPMI_ALG_HASH+ 11697 11698hashAlg 11699 11700the hash algorithm to use for the hash sequence 11701An Event sequence starts if this is TPM_ALG_NULL. 11702 11703Table 70 — TPM2_HashSequenceStart Response 11704Type 11705 11706Name 11707 11708Description 11709 11710TPM_ST 11711 11712tag 11713 11714see clause 8 11715 11716UINT32 11717 11718responseSize 11719 11720TPM_RC 11721 11722responseCode 11723 11724TPMI_DH_OBJECT 11725 11726sequenceHandle 11727 11728Family “2.0” 11729Level 00 Revision 00.99 11730 11731a handle to reference the sequence 11732 11733Published 11734Copyright © TCG 2006-2013 11735 11736Page 137 11737October 31, 2013 11738 11739 Part 3: Commands 11740 11741Trusted Platform Module Library 11742 1174319.3.3 Detailed Actions 117441 117452 11746 11747#include "InternalRoutines.h" 11748#include "HashSequenceStart_fp.h" 11749Error Returns 11750TPM_RC_OBJECT_MEMORY 11751 117523 117534 117545 117556 117567 117578 117589 1175910 1176011 1176112 1176213 1176314 1176415 1176516 1176617 1176718 1176819 11769 11770Meaning 11771no space to create an internal object 11772 11773TPM_RC 11774TPM2_HashSequenceStart( 11775HashSequenceStart_In 11776HashSequenceStart_Out 11777 11778*in, 11779*out 11780 11781// IN: input parameter list 11782// OUT: output parameter list 11783 11784) 11785{ 11786// Internal Data Update 11787if(in->hashAlg == TPM_ALG_NULL) 11788// Start a event sequence. A TPM_RC_OBJECT_MEMORY error may be 11789// returned at this point 11790return ObjectCreateEventSequence(&in->auth, &out->sequenceHandle); 11791// Start a hash sequence. A TPM_RC_OBJECT_MEMORY error may be 11792// returned at this point 11793return ObjectCreateHashSequence(in->hashAlg, &in->auth, &out->sequenceHandle); 11794} 11795 11796Page 138 11797October 31, 2013 11798 11799Published 11800Copyright © TCG 2006-2013 11801 11802Family “2.0” 11803Level 00 Revision 00.99 11804 11805 Trusted Platform Module Library 11806 1180719.4 11808 11809Part 3: Commands 11810 11811TPM2_SequenceUpdate 11812 1181319.4.1 General Description 11814This command is used to add data to a hash or HMAC sequence. The amount of data in buffer may be 11815any size up to the limits of the TPM. 11816NOTE 11817 11818In all TPM, a buffer size of 1,024 octets is allowed. 11819 11820Proper authorization for the sequence object associated with sequenceHandle is required. If an 11821authorization or audit of this command requires computation of a cpHash and an rpHash, the Name 11822associated with sequenceHandle will be the Empty Buffer. 11823If the command does not return TPM_RC_SUCCESS, the state of the sequence is unmodified. 11824If the sequence is intended to produce a digest that will be signed by a restricted signing key, then the 11825first block of data shall contain sizeof(TPM_GENERATED) octets and the first octets shall not be 11826TPM_GENERATED_VALUE. 11827NOTE 11828 11829This requirement allows the TPM to validate that the first block is safe to sign without having to 11830accumulate octets over multiple calls. 11831 11832Family “2.0” 11833Level 00 Revision 00.99 11834 11835Published 11836Copyright © TCG 2006-2013 11837 11838Page 139 11839October 31, 2013 11840 11841 Part 3: Commands 11842 11843Trusted Platform Module Library 11844 1184519.4.2 Command and Response 11846Table 71 — TPM2_SequenceUpdate Command 11847Type 11848 11849Name 11850 11851Description 11852 11853TPMI_ST_COMMAND_TAG 11854 11855tag 11856 11857UINT32 11858 11859commandSize 11860 11861TPM_CC 11862 11863commandCode 11864 11865TPM_CC_SequenceUpdate 11866 11867TPMI_DH_OBJECT 11868 11869@sequenceHandle 11870 11871handle for the sequence object 11872Auth Index: 1 11873Auth Role: USER 11874 11875TPM2B_MAX_BUFFER 11876 11877buffer 11878 11879data to be added to hash 11880 11881Table 72 — TPM2_SequenceUpdate Response 11882Type 11883 11884Name 11885 11886Description 11887 11888TPM_ST 11889 11890tag 11891 11892see clause 8 11893 11894UINT32 11895 11896responseSize 11897 11898TPM_RC 11899 11900responseCode 11901 11902Page 140 11903October 31, 2013 11904 11905Published 11906Copyright © TCG 2006-2013 11907 11908Family “2.0” 11909Level 00 Revision 00.99 11910 11911 Trusted Platform Module Library 11912 11913Part 3: Commands 11914 1191519.4.3 Detailed Actions 119161 119172 11918 11919#include "InternalRoutines.h" 11920#include "SequenceUpdate_fp.h" 11921Error Returns 11922TPM_RC_MODE 11923 119243 119254 119265 119276 119287 119298 119309 1193110 1193211 1193312 1193413 1193514 1193615 1193716 1193817 1193918 1194019 1194120 1194221 1194322 1194423 1194524 1194625 1194726 1194827 1194928 1195029 1195130 1195231 1195332 1195433 1195534 1195635 1195736 1195837 1195938 1196039 1196140 1196241 1196342 1196443 1196544 1196645 1196746 1196847 1196948 1197049 1197150 1197251 1197352 1197453 11975 11976Meaning 11977sequenceHandle does not reference a hash or HMAC sequence 11978object 11979 11980TPM_RC 11981TPM2_SequenceUpdate( 11982SequenceUpdate_In 11983 11984*in 11985 11986// IN: input parameter list 11987 11988) 11989{ 11990OBJECT 11991 11992*object; 11993 11994// Input Validation 11995// Get sequence object pointer 11996object = ObjectGet(in->sequenceHandle); 11997// Check that referenced object is a sequence object. 11998if(!ObjectIsSequence(object)) 11999return TPM_RC_MODE + RC_SequenceUpdate_sequenceHandle; 12000// Internal Data Update 12001if(object->attributes.eventSeq == SET) 12002{ 12003// Update event sequence object 12004UINT32 12005i; 12006HASH_OBJECT 12007*hashObject = (HASH_OBJECT *)object; 12008for(i = 0; i < HASH_COUNT; i++) 12009{ 12010// Update sequence object 12011CryptUpdateDigest2B(&hashObject->state.hashState[i], &in->buffer.b); 12012} 12013} 12014else 12015{ 12016HASH_OBJECT 12017*hashObject = (HASH_OBJECT *)object; 12018// Update hash/HMAC sequence object 12019if(hashObject->attributes.hashSeq == SET) 12020{ 12021// Is this the first block of the sequence 12022if(hashObject->attributes.firstBlock == CLEAR) 12023{ 12024// If so, indicate that first block was received 12025hashObject->attributes.firstBlock = SET; 12026// Check the first block to see if the first block can contain 12027// the TPM_GENERATED_VALUE. If it does, it is not safe for 12028// a ticket. 12029if(TicketIsSafe(&in->buffer.b)) 12030hashObject->attributes.ticketSafe = SET; 12031} 12032// Update sequence object hash/HMAC stack 12033CryptUpdateDigest2B(&hashObject->state.hashState[0], &in->buffer.b); 12034 12035Family “2.0” 12036Level 00 Revision 00.99 12037 12038Published 12039Copyright © TCG 2006-2013 12040 12041Page 141 12042October 31, 2013 12043 12044 Part 3: Commands 1204554 1204655 1204756 1204857 1204958 1205059 1205160 1205261 1205362 1205463 1205564 1205665 12057 12058Trusted Platform Module Library 12059 12060} 12061else if(object->attributes.hmacSeq == SET) 12062{ 12063HASH_OBJECT 12064*hashObject = (HASH_OBJECT *)object; 12065// Update sequence object hash/HMAC stack 12066CryptUpdateDigest2B(&hashObject->state.hmacState, &in->buffer.b); 12067} 12068} 12069return TPM_RC_SUCCESS; 12070} 12071 12072Page 142 12073October 31, 2013 12074 12075Published 12076Copyright © TCG 2006-2013 12077 12078Family “2.0” 12079Level 00 Revision 00.99 12080 12081 Trusted Platform Module Library 12082 1208319.5 12084 12085Part 3: Commands 12086 12087TPM2_SequenceComplete 12088 1208919.5.1 General Description 12090This command adds the last part of data, if any, to a hash/HMAC sequence and returns the result. 12091NOTE 1 12092 12093This command is not used to complete an Event sequence. TPM2_EventSequenceComplete() is 12094used for that purpose. 12095 12096For a hash sequence, if the results of the hash will be used in a signing operation that uses a restricted 12097signing key, then the ticket returned by this command can indicate that the hash is safe to sign. 12098If the digest is not safe to sign, then validation will be a TPMT_TK_HASHCHECK with the hierarchy set to 12099TPM_RH_NULL and digest set to the Empty Buffer. 12100NOTE 2 12101 12102Regardless of the contents of the first octets of the hashed message, if the first buffer sent to the 12103TPM had fewer than sizeof(TPM_GENERATED) octets, then the TPM will operate as if digest is not 12104safe to sign. 12105 12106If sequenceHandle references an Event sequence, then the TPM shall return TPM_RC_MODE. 12107Proper authorization for the sequence object associated with sequenceHandle is required. If an 12108authorization or audit of this command requires computation of a cpHash and an rpHash, the Name 12109associated with sequenceHandle will be the Empty Buffer. 12110If this command completes successfully, the sequenceHandle object will be flushed. 12111 12112Family “2.0” 12113Level 00 Revision 00.99 12114 12115Published 12116Copyright © TCG 2006-2013 12117 12118Page 143 12119October 31, 2013 12120 12121 Part 3: Commands 12122 12123Trusted Platform Module Library 12124 1212519.5.2 Command and Response 12126Table 73 — TPM2_SequenceComplete Command 12127Type 12128 12129Name 12130 12131Description 12132 12133TPMI_ST_COMMAND_TAG 12134 12135tag 12136 12137UINT32 12138 12139commandSize 12140 12141TPM_CC 12142 12143commandCode 12144 12145TPM_CC_SequenceComplete {F} 12146 12147TPMI_DH_OBJECT 12148 12149@sequenceHandle 12150 12151authorization for the sequence 12152Auth Index: 1 12153Auth Role: USER 12154 12155TPM2B_MAX_BUFFER 12156 12157buffer 12158 12159data to be added to the hash/HMAC 12160 12161TPMI_RH_HIERARCHY+ 12162 12163hierarchy 12164 12165hierarchy of the ticket for a hash 12166 12167Table 74 — TPM2_SequenceComplete Response 12168Type 12169 12170Name 12171 12172Description 12173 12174TPM_ST 12175 12176tag 12177 12178see clause 8 12179 12180UINT32 12181 12182responseSize 12183 12184TPM_RC 12185 12186responseCode 12187 12188TPM2B_DIGEST 12189 12190result 12191 12192the returned HMAC or digest in a sized buffer 12193 12194TPMT_TK_HASHCHECK 12195 12196validation 12197 12198ticket indicating that the sequence of octets used to 12199compute outDigest did not start with 12200TPM_GENERATED_VALUE 12201This is a NULL Ticket when the session is HMAC. 12202 12203Page 144 12204October 31, 2013 12205 12206Published 12207Copyright © TCG 2006-2013 12208 12209Family “2.0” 12210Level 00 Revision 00.99 12211 12212 Trusted Platform Module Library 12213 12214Part 3: Commands 12215 1221619.5.3 Detailed Actions 122171 122182 122193 12220 12221#include "InternalRoutines.h" 12222#include "SequenceComplete_fp.h" 12223#include <Platform.h> 12224Error Returns 12225TPM_RC_TYPE 12226 122274 122285 122296 122307 122318 122329 1223310 1223411 1223512 1223613 1223714 1223815 1223916 1224017 1224118 1224219 1224320 1224421 1224522 1224623 1224724 1224825 1224926 1225027 1225128 1225229 1225330 1225431 1225532 1225633 1225734 1225835 1225936 1226037 1226138 1226239 1226340 1226441 1226542 1226643 1226744 1226845 1226946 1227047 1227148 1227249 1227350 1227451 1227552 1227653 12277 12278Meaning 12279sequenceHandle does not reference a hash or HMAC sequence 12280object 12281 12282TPM_RC 12283TPM2_SequenceComplete( 12284SequenceComplete_In 12285SequenceComplete_Out 12286 12287*in, 12288*out 12289 12290OBJECT 12291 12292// IN: input parameter list 12293// OUT: output parameter list 12294 12295*object; 12296 12297) 12298{ 12299// Input validation 12300// Get hash object pointer 12301object = ObjectGet(in->sequenceHandle); 12302// input handle must be a hash or HMAC sequence object. 12303if( 12304object->attributes.hashSeq == CLEAR 12305&& object->attributes.hmacSeq == CLEAR) 12306return TPM_RC_MODE + RC_SequenceComplete_sequenceHandle; 12307// Command Output 12308if(object->attributes.hashSeq == SET) 12309// sequence object for hash 12310{ 12311// Update last piece of data 12312HASH_OBJECT 12313*hashObject = (HASH_OBJECT *)object; 12314CryptUpdateDigest2B(&hashObject->state.hashState[0], &in->buffer.b); 12315// Complete hash 12316out->result.t.size 12317= CryptGetHashDigestSize( 12318CryptGetContextAlg(&hashObject->state.hashState[0])); 12319CryptCompleteHash2B(&hashObject->state.hashState[0], &out->result.b); 12320// Check if the first block of the sequence has been received 12321if(hashObject->attributes.firstBlock == CLEAR) 12322{ 12323// If not, then this is the first block so see if it is 'safe' 12324// to sign. 12325if(TicketIsSafe(&in->buffer.b)) 12326hashObject->attributes.ticketSafe = SET; 12327} 12328// Output ticket 12329out->validation.tag = TPM_ST_HASHCHECK; 12330out->validation.hierarchy = in->hierarchy; 12331if(in->hierarchy == TPM_RH_NULL) 12332{ 12333// Ticket is not required 12334out->validation.digest.t.size = 0; 12335 12336Family “2.0” 12337Level 00 Revision 00.99 12338 12339Published 12340Copyright © TCG 2006-2013 12341 12342Page 145 12343October 31, 2013 12344 12345 Part 3: Commands 1234654 1234755 1234856 1234957 1235058 1235159 1235260 1235361 1235462 1235563 1235664 1235765 1235866 1235967 1236068 1236169 1236270 1236371 1236472 1236573 1236674 1236775 1236876 1236977 1237078 1237179 1237280 1237381 1237482 1237583 1237684 1237785 1237886 1237987 1238088 1238189 1238290 1238391 1238492 12385 12386Trusted Platform Module Library 12387 12388} 12389else if(object->attributes.ticketSafe == CLEAR) 12390{ 12391// Ticket is not safe to generate 12392out->validation.hierarchy = TPM_RH_NULL; 12393out->validation.digest.t.size = 0; 12394} 12395else 12396{ 12397// Compute ticket 12398TicketComputeHashCheck(out->validation.hierarchy, 12399&out->result, &out->validation); 12400} 12401} 12402else 12403{ 12404HASH_OBJECT 12405 12406*hashObject = (HASH_OBJECT *)object; 12407 12408// 12409Update last piece of data 12410CryptUpdateDigest2B(&hashObject->state.hmacState, &in->buffer.b); 12411// Complete hash/HMAC 12412out->result.t.size = 12413CryptGetHashDigestSize( 12414CryptGetContextAlg(&hashObject->state.hmacState.hashState)); 12415CryptCompleteHMAC2B(&(hashObject->state.hmacState), &out->result.b); 12416// No ticket is generated for HMAC sequence 12417out->validation.tag = TPM_ST_HASHCHECK; 12418out->validation.hierarchy = TPM_RH_NULL; 12419out->validation.digest.t.size = 0; 12420} 12421// Internal Data Update 12422// mark sequence object as evict so it will be flushed on the way out 12423object->attributes.evict = SET; 12424return TPM_RC_SUCCESS; 12425} 12426 12427Page 146 12428October 31, 2013 12429 12430Published 12431Copyright © TCG 2006-2013 12432 12433Family “2.0” 12434Level 00 Revision 00.99 12435 12436 Trusted Platform Module Library 12437 1243819.6 12439 12440Part 3: Commands 12441 12442TPM2_EventSequenceComplete 12443 1244419.6.1 General Description 12445This command adds the last part of data, if any, to an Event sequence and returns the result in a digest 12446list. If pcrHandle references a PCR and not TPM_RH_NULL, then the returned digest list is processed in 12447the same manner as the digest list input parameter to TPM2_PCR_Extend() with the pcrHandle in each 12448bank extended with the associated digest value. 12449If sequenceHandle references a hash or HMAC sequence, the TPM shall return TPM_RC_MODE. 12450Proper authorization for the sequence object associated with sequenceHandle is required. If an 12451authorization or audit of this command requires computation of a cpHash and an rpHash, the Name 12452associated with sequenceHandle will be the Empty Buffer. 12453If this command completes successfully, the sequenceHandle object will be flushed. 12454 12455Family “2.0” 12456Level 00 Revision 00.99 12457 12458Published 12459Copyright © TCG 2006-2013 12460 12461Page 147 12462October 31, 2013 12463 12464 Part 3: Commands 12465 12466Trusted Platform Module Library 12467 1246819.6.2 Command and Response 12469Table 75 — TPM2_EventSequenceComplete Command 12470Type 12471 12472Name 12473 12474TPMI_ST_COMMAND_TAG 12475 12476tag 12477 12478UINT32 12479 12480commandSize 12481 12482TPM_CC 12483 12484commandCode 12485 12486TPM_CC_EventSequenceComplete {NV F} 12487 12488TPMI_DH_PCR+ 12489 12490@pcrHandle 12491 12492PCR to be extended with the Event data 12493Auth Index: 1 12494Auth Role: USER 12495 12496TPMI_DH_OBJECT 12497 12498@sequenceHandle 12499 12500authorization for the sequence 12501Auth Index: 2 12502Auth Role: USER 12503 12504TPM2B_MAX_BUFFER 12505 12506buffer 12507 12508data to be added to the Event 12509 12510Description 12511 12512Table 76 — TPM2_EventSequenceComplete Response 12513Type 12514 12515Name 12516 12517Description 12518 12519TPM_ST 12520 12521tag 12522 12523see clause 8 12524 12525UINT32 12526 12527responseSize 12528 12529TPM_RC 12530 12531responseCode 12532 12533TPML_DIGEST_VALUES 12534 12535results 12536 12537Page 148 12538October 31, 2013 12539 12540list of digests computed for the PCR 12541 12542Published 12543Copyright © TCG 2006-2013 12544 12545Family “2.0” 12546Level 00 Revision 00.99 12547 12548 Trusted Platform Module Library 12549 12550Part 3: Commands 12551 1255219.6.3 Detailed Actions 125531 125542 12555 12556#include "InternalRoutines.h" 12557#include "EventSequenceComplete_fp.h" 12558Error Returns 12559TPM_RC_LOCALITY 12560 12561PCR extension is not allowed at the current locality 12562 12563TPM_RC_MODE 125643 125654 125665 125676 125687 125698 125709 1257110 1257211 1257312 1257413 1257514 1257615 1257716 1257817 1257918 1258019 1258120 1258221 1258322 1258423 1258524 1258625 1258726 1258827 1258928 1259029 1259130 1259231 1259332 1259433 1259534 1259635 1259736 1259837 1259938 1260039 1260140 1260241 1260342 1260443 1260544 1260645 1260746 1260847 1260948 1261049 1261150 1261251 1261352 1261453 12615 12616Meaning 12617 12618input handle is not a valid event sequence object 12619 12620TPM_RC 12621TPM2_EventSequenceComplete( 12622EventSequenceComplete_In 12623EventSequenceComplete_Out 12624 12625*in, 12626*out 12627 12628// IN: input parameter list 12629// OUT: output parameter list 12630 12631) 12632{ 12633TPM_RC 12634HASH_OBJECT 12635UINT32 12636TPM_ALG_ID 12637 12638result; 12639*hashObject; 12640i; 12641hashAlg; 12642 12643// Input validation 12644// get the event sequence object pointer 12645hashObject = (HASH_OBJECT *)ObjectGet(in->sequenceHandle); 12646// input handle must reference an event sequence object 12647if(hashObject->attributes.eventSeq != SET) 12648return TPM_RC_MODE + RC_EventSequenceComplete_sequenceHandle; 12649// see if a PCR extend is requested in call 12650if(in->pcrHandle != TPM_RH_NULL) 12651{ 12652// see if extend of the PCR is allowed at the locality of the command, 12653if(!PCRIsExtendAllowed(in->pcrHandle)) 12654return TPM_RC_LOCALITY; 12655// if an extend is going to take place, then check to see if there has 12656// been an orderly shutdown. If so, and the selected PCR is one of the 12657// state saved PCR, then the orderly state has to change. The orderly state 12658// does not change for PCR that are not preserved. 12659// NOTE: This doesn't just check for Shutdown(STATE) because the orderly 12660// state will have to change if this is a state-saved PCR regardless 12661// of the current state. This is because a subsequent Shutdown(STATE) will 12662// check to see if there was an orderly shutdown and not do anything if 12663// there was. So, this must indicate that a future Shutdown(STATE) has 12664// something to do. 12665if(gp.orderlyState != SHUTDOWN_NONE && PCRIsStateSaved(in->pcrHandle)) 12666{ 12667result = NvIsAvailable(); 12668if(result != TPM_RC_SUCCESS) return result; 12669g_clearOrderly = TRUE; 12670} 12671} 12672// Command Output 12673out->results.count = 0; 12674for(i = 0; i < HASH_COUNT; i++) 12675{ 12676hashAlg = CryptGetHashAlgByIndex(i); 12677 12678Family “2.0” 12679Level 00 Revision 00.99 12680 12681Published 12682Copyright © TCG 2006-2013 12683 12684Page 149 12685October 31, 2013 12686 12687 Part 3: Commands 1268854 1268955 1269056 1269157 1269258 1269359 1269460 1269561 1269662 1269763 1269864 1269965 1270066 1270167 1270268 1270369 1270470 1270571 1270672 1270773 1270874 1270975 1271076 12711 12712Trusted Platform Module Library 12713 12714// Update last piece of data 12715CryptUpdateDigest2B(&hashObject->state.hashState[i], &in->buffer.b); 12716// Complete hash 12717out->results.digests[out->results.count].hashAlg = hashAlg; 12718CryptCompleteHash(&hashObject->state.hashState[i], 12719CryptGetHashDigestSize(hashAlg), 12720(BYTE *) &out->results.digests[out->results.count].digest); 12721// Extend PCR 12722if(in->pcrHandle != TPM_RH_NULL) 12723PCRExtend(in->pcrHandle, hashAlg, 12724CryptGetHashDigestSize(hashAlg), 12725(BYTE *) &out->results.digests[out->results.count].digest); 12726out->results.count++; 12727} 12728// Internal Data Update 12729// mark sequence object as evict so it will be flushed on the way out 12730hashObject->attributes.evict = SET; 12731return TPM_RC_SUCCESS; 12732} 12733 12734Page 150 12735October 31, 2013 12736 12737Published 12738Copyright © TCG 2006-2013 12739 12740Family “2.0” 12741Level 00 Revision 00.99 12742 12743 Trusted Platform Module Library 12744 12745Part 3: Commands 12746 12747Attestation Commands 12748 1274920 1275020.1 12751 12752Introduction 12753 12754The attestation commands cause the TPM to sign an internally generated data structure. The contents of 12755the data structure vary according to the command. 12756For all signing commands, provisions are made for the caller to provide a scheme to be used for the 12757signing operation. This scheme will be applied only if the scheme of the key is TPM_ALG_NULL. If the 12758scheme for signHandle is not TPM_ALG_NULL, then inScheme.scheme shall be TPM_ALG_NULL or the 12759same as scheme in the public area of the key. If the scheme for signHandle is TPM_ALG_NULL, then 12760inScheme will be used for the signing operation and may not be TPM_ALG_NULL. The TPM shall return 12761TPM_RC_SCHEME to indicate that the scheme is not appropriate. 12762For a signing key that is not restricted, the caller may specify the scheme to be used as long as the 12763scheme is compatible with the family of the key (for example, TPM_ALG_RSAPSS cannot be selected for 12764an ECC key). If the caller sets scheme to TPM_ALG_NULL, then the default scheme of the key is used. 12765If the handle for the signing key (signHandle) is TPM_RH_NULL, then all of the actions of the command 12766are performed and the attestation block is “signed” with the NULL Signature. 12767NOTE 1 12768 12769This mechanism is provided so that additional commands are not required to access the data that 12770might be in an attestation structure. 12771 12772NOTE 2 12773 12774When signHandle is TPM_RH_NULL, scheme is still required to be a valid signing scheme (may be 12775TPM_ALG_NULL), but the scheme will have no effect on the format of the signature. It will always 12776be the NULL Signature. 12777 12778TPM2_NV_Certify() is an attestation command that is documented in 1. The remaining attestation 12779commands are collected in the remainder of this clause. 12780Each of the attestation structures contains a TPMS_CLOCK_INFO structure and a firmware version 12781number. These values may be considered privacy-sensitive, because they would aid in the correlation of 12782attestations by different keys. To provide improved privacy, the resetCount, restartCount, and 12783firmwareVersion numbers are obfuscated when the signing key is not in the Endorsement or Platform 12784hierarchies. 12785The obfuscation value is computed by: 12786 12787obfuscation ≔ KDFa(signHandle→nameAlg, shProof, “OBFUSCATE”, signHandle→QN, 0, 128) (3) 12788Of the returned 128 bits, 64 bits are added to the versionNumber field of the attestation structure; 32 bits 12789are added to the clockInfo.resetCount and 32 bits are added to the clockInfo.restartCount. The order in 12790which the bits are added is implementation-dependent. 12791NOTE 3 12792 12793The obfuscation value for each signing key will be unique to that key in a specific location. That is, 12794each version of a duplicated signing key will have a different obfuscation value. 12795 12796When the signing key is TPM_RH_NULL, the data structure is produced but not signed; and the values in 12797the signed data structure are obfuscated. When computing the obfuscation value for TPM_RH_NULL, the 12798hash used for context integrity is used. 12799NOTE 4 12800 12801The QN for TPM_RH_NULL is TPM_RH_NULL. 12802 12803If the signing scheme of signHandle is an anonymous scheme, then the attestation blocks will not contain 12804the Qualified Name of the signHandle. 12805Each of the attestation structures allows the caller to provide some qualifying data (qualifyingData). For 12806most signing schemes, this value will be placed in the TPMS_ATTEST.extraData parameter that is then 12807 12808Family “2.0” 12809Level 00 Revision 00.99 12810 12811Published 12812Copyright © TCG 2006-2013 12813 12814Page 151 12815October 31, 2013 12816 12817 Part 3: Commands 12818 12819Trusted Platform Module Library 12820 12821hashed and signed. However, for some schemes such as ECDAA, the qualifyingData is used in a 12822different manner (for details, see “ECDAA” in Part 1). 12823 12824Page 152 12825October 31, 2013 12826 12827Published 12828Copyright © TCG 2006-2013 12829 12830Family “2.0” 12831Level 00 Revision 00.99 12832 12833 Trusted Platform Module Library 12834 1283520.2 12836 12837Part 3: Commands 12838 12839TPM2_Certify 12840 1284120.2.1 General Description 12842The purpose of this command is to prove that an object with a specific Name is loaded in the TPM. By 12843certifying that the object is loaded, the TPM warrants that a public area with a given Name is selfconsistent and associated with a valid sensitive area. If a relying party has a public area that has the 12844same Name as a Name certified with this command, then the values in that public area are correct. 12845NOTE 1 12846 12847See 20.1 for description of how the signing scheme is selected. 12848 12849Authorization for objectHandle requires ADMIN role authorization. If performed with a policy session, the 12850session shall have a policySession→commandCode set to TPM_CC_Certify. This indicates that the 12851policy that is being used is a policy that is for certification, and not a policy that would approve another 12852use. That is, authority to use an object does not grant authority to certify the object. 12853The object may be any object that is loaded with TPM2_Load() or TPM2_CreatePrimary(). An object that 12854only has its public area loaded cannot be certified. 12855NOTE 2 12856 12857The restriction occurs because the Name is used to identify the object being certified. If the TPM 12858has not validated that the public area is associated with a matched sensitive area, then the public 12859area may not represent a valid object a nd cannot be certified. 12860 12861The certification includes the Name and Qualified Name of the certified object as well as the Name and 12862the Qualified Name of the certifying object. 12863 12864Family “2.0” 12865Level 00 Revision 00.99 12866 12867Published 12868Copyright © TCG 2006-2013 12869 12870Page 153 12871October 31, 2013 12872 12873 Part 3: Commands 12874 12875Trusted Platform Module Library 12876 1287720.2.2 Command and Response 12878Table 77 — TPM2_Certify Command 12879Type 12880 12881Name 12882 12883TPMI_ST_COMMAND_TAG 12884 12885tag 12886 12887UINT32 12888 12889commandSize 12890 12891TPM_CC 12892 12893commandCode 12894 12895TPM_CC_Certify 12896 12897TPMI_DH_OBJECT 12898 12899@objectHandle 12900 12901handle of the object to be certified 12902Auth Index: 1 12903Auth Role: ADMIN 12904 12905TPMI_DH_OBJECT+ 12906 12907@signHandle 12908 12909handle of the key used to sign the attestation structure 12910Auth Index: 2 12911Auth Role: USER 12912 12913TPM2B_DATA 12914 12915qualifyingData 12916 12917user provided qualifying data 12918 12919TPMT_SIG_SCHEME+ 12920 12921inScheme 12922 12923signing scheme to use if the scheme for signHandle is 12924TPM_ALG_NULL 12925 12926Description 12927 12928Table 78 — TPM2_Certify Response 12929Type 12930 12931Name 12932 12933Description 12934 12935TPM_ST 12936 12937tag 12938 12939see clause 8 12940 12941UINT32 12942 12943responseSize 12944 12945TPM_RC 12946 12947responseCode 12948 12949. 12950 12951TPM2B_ATTEST 12952 12953certifyInfo 12954 12955the structure that was signed 12956 12957TPMT_SIGNATURE 12958 12959signature 12960 12961the asymmetric signature over certifyInfo using the key 12962referenced by signHandle 12963 12964Page 154 12965October 31, 2013 12966 12967Published 12968Copyright © TCG 2006-2013 12969 12970Family “2.0” 12971Level 00 Revision 00.99 12972 12973 Trusted Platform Module Library 12974 12975Part 3: Commands 12976 1297720.2.3 Detailed Actions 129781 129792 129803 12981 12982#include "InternalRoutines.h" 12983#include "Attest_spt_fp.h" 12984#include "Certify_fp.h" 12985Error Returns 12986TPM_RC_KEY 12987 12988key referenced by signHandle is not a signing key 12989 12990TPM_RC_SCHEME 12991 12992inScheme is not compatible with signHandle 12993 12994TPM_RC_VALUE 12995 129964 129975 129986 129997 130008 130019 1300210 1300311 1300412 1300513 1300614 1300715 1300816 1300917 1301018 1301119 1301220 1301321 1301422 1301523 1301624 1301725 1301826 1301927 1302028 1302129 1302230 1302331 1302432 1302533 1302634 1302735 1302836 1302937 1303038 1303139 1303240 1303341 1303442 1303543 1303644 1303745 1303846 1303947 1304048 13041 13042Meaning 13043 13044digest generated for inScheme is greater or has larger size than the 13045modulus of signHandle, or the buffer for the result in signature is too 13046small (for an RSA key); invalid commit status (for an ECC key with a 13047split scheme). 13048 13049TPM_RC 13050TPM2_Certify( 13051Certify_In 13052Certify_Out 13053 13054*in, 13055*out 13056 13057// IN: input parameter list 13058// OUT: output parameter list 13059 13060) 13061{ 13062TPM_RC 13063TPMS_ATTEST 13064 13065result; 13066certifyInfo; 13067 13068// Command Output 13069// Filling in attest information 13070// Common fields 13071result = FillInAttestInfo(in->signHandle, 13072&in->inScheme, 13073&in->qualifyingData, 13074&certifyInfo); 13075if(result != TPM_RC_SUCCESS) 13076{ 13077if(result == TPM_RC_KEY) 13078return TPM_RC_KEY + RC_Certify_signHandle; 13079else 13080return RcSafeAddToResult(result, RC_Certify_inScheme); 13081} 13082// Certify specific fields 13083// Attestation type 13084certifyInfo.type = TPM_ST_ATTEST_CERTIFY; 13085// Certified object name 13086certifyInfo.attested.certify.name.t.size = 13087ObjectGetName(in->objectHandle, 13088&certifyInfo.attested.certify.name.t.name); 13089// Certified object qualified name 13090ObjectGetQualifiedName(in->objectHandle, 13091&certifyInfo.attested.certify.qualifiedName); 13092// Sign attestation structure. A NULL signature will be returned if 13093// signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, 13094// TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned 13095// by SignAttestInfo() 13096result = SignAttestInfo(in->signHandle, 13097&in->inScheme, 13098&certifyInfo, 13099&in->qualifyingData, 13100&out->certifyInfo, 13101 13102Family “2.0” 13103Level 00 Revision 00.99 13104 13105Published 13106Copyright © TCG 2006-2013 13107 13108Page 155 13109October 31, 2013 13110 13111 Part 3: Commands 1311249 1311350 1311451 1311552 1311653 1311754 1311855 1311956 1312057 1312158 1312259 1312360 1312461 1312562 1312663 1312764 13128 13129Trusted Platform Module Library 13130&out->signature); 13131 13132// TPM_RC_ATTRIBUTES cannot be returned here as FillInAttestInfo would already 13133// have returned TPM_RC_KEY 13134pAssert(result != TPM_RC_ATTRIBUTES); 13135if(result != TPM_RC_SUCCESS) 13136return result; 13137// orderly state should be cleared because of the reporting of clock info 13138// if signing happens 13139if(in->signHandle != TPM_RH_NULL) 13140g_clearOrderly = TRUE; 13141return TPM_RC_SUCCESS; 13142} 13143 13144Page 156 13145October 31, 2013 13146 13147Published 13148Copyright © TCG 2006-2013 13149 13150Family “2.0” 13151Level 00 Revision 00.99 13152 13153 Trusted Platform Module Library 13154 1315520.3 13156 13157Part 3: Commands 13158 13159TPM2_CertifyCreation 13160 1316120.3.1 General Description 13162This command is used to prove the association between an object and its creation data. The TPM will 13163validate that the ticket was produced by the TPM and that the ticket validates the association between a 13164loaded public area and the provided hash of the creation data (creationHash). 13165NOTE 1 13166 13167See 20.1 for description of how the signing scheme is selected. 13168 13169The TPM will create a test ticket using the Name associated with objectHandle and creationHash as: 13170 13171HMAC(proof, (TPM_ST_CREATION || objectHandle→Name || creationHash)) 13172 13173(4) 13174 13175This ticket is then compared to creation ticket. If the tickets are not the same, the TPM shall return 13176TPM_RC_TICKET. 13177If the ticket is valid, then the TPM will create a TPMS_ATTEST structure and place creationHash of the 13178command in the creationHash field of the structure. The Name associated with objectHandle will be 13179included in the attestation data that is then signed using the key associated with signHandle. 13180NOTE 2 13181 13182If signHandle is TPM_RH_NULL, the TPMS_ATTEST structure is returned and signature is a NULL 13183Signature. 13184 13185ObjectHandle may be any object that is loaded with TPM2_Load() or TPM2_CreatePrimary(). 13186 13187Family “2.0” 13188Level 00 Revision 00.99 13189 13190Published 13191Copyright © TCG 2006-2013 13192 13193Page 157 13194October 31, 2013 13195 13196 Part 3: Commands 13197 13198Trusted Platform Module Library 13199 1320020.3.2 Command and Response 13201Table 79 — TPM2_CertifyCreation Command 13202Type 13203 13204Name 13205 13206Description 13207 13208TPMI_ST_COMMAND_TAG 13209 13210tag 13211 13212UINT32 13213 13214commandSize 13215 13216TPM_CC 13217 13218commandCode 13219 13220TPM_CC_CertifyCreation 13221 13222TPMI_DH_OBJECT+ 13223 13224@signHandle 13225 13226handle of the key that will sign the attestation block 13227Auth Index: 1 13228Auth Role: USER 13229 13230TPMI_DH_OBJECT 13231 13232objectHandle 13233 13234the object associated with the creation data 13235Auth Index: None 13236 13237TPM2B_DATA 13238 13239qualifyingData 13240 13241user-provided qualifying data 13242 13243TPM2B_DIGEST 13244 13245creationHash 13246 13247hash of the creation data produced by TPM2_Create() 13248or TPM2_CreatePrimary() 13249 13250TPMT_SIG_SCHEME+ 13251 13252inScheme 13253 13254signing scheme to use if the scheme for signHandle is 13255TPM_ALG_NULL 13256 13257TPMT_TK_CREATION 13258 13259creationTicket 13260 13261ticket produced by TPM2_Create() or 13262TPM2_CreatePrimary() 13263 13264Table 80 — TPM2_CertifyCreation Response 13265Type 13266 13267Name 13268 13269Description 13270 13271TPM_ST 13272 13273tag 13274 13275see clause 8 13276 13277UINT32 13278 13279responseSize 13280 13281TPM_RC 13282 13283responseCode 13284 13285TPM2B_ATTEST 13286 13287certifyInfo 13288 13289the structure that was signed 13290 13291TPMT_SIGNATURE 13292 13293signature 13294 13295the signature over certifyInfo 13296 13297Page 158 13298October 31, 2013 13299 13300Published 13301Copyright © TCG 2006-2013 13302 13303Family “2.0” 13304Level 00 Revision 00.99 13305 13306 Trusted Platform Module Library 13307 13308Part 3: Commands 13309 1331020.3.3 Detailed Actions 133111 133122 133133 13314 13315#include "InternalRoutines.h" 13316#include "Attest_spt_fp.h" 13317#include "CertifyCreation_fp.h" 13318Error Returns 13319TPM_RC_KEY 13320 13321key referenced by signHandle is not a signing key 13322 13323TPM_RC_SCHEME 13324 13325inScheme is not compatible with signHandle 13326 13327TPM_RC_TICKET 13328 13329creationTicket does not match objectHandle 13330 13331TPM_RC_VALUE 13332 133334 133345 133356 133367 133378 133389 1333910 1334011 1334112 1334213 1334314 1334415 1334516 1334617 1334718 1334819 1334920 1335021 1335122 1335223 1335324 1335425 1335526 1335627 1335728 1335829 1335930 1336031 1336132 1336233 1336334 1336435 1336536 1336637 1336738 1336839 1336940 1337041 1337142 1337243 1337344 1337445 1337546 13376 13377Meaning 13378 13379digest generated for inScheme is greater or has larger size than the 13380modulus of signHandle, or the buffer for the result in signature is too 13381small (for an RSA key); invalid commit status (for an ECC key with a 13382split scheme). 13383 13384TPM_RC 13385TPM2_CertifyCreation( 13386CertifyCreation_In 13387CertifyCreation_Out 13388 13389*in, 13390*out 13391 13392// IN: input parameter list 13393// OUT: output parameter list 13394 13395) 13396{ 13397TPM_RC 13398TPM2B_NAME 13399TPMT_TK_CREATION 13400TPMS_ATTEST 13401 13402result; 13403name; 13404ticket; 13405certifyInfo; 13406 13407// Input Validation 13408// CertifyCreation specific input validation 13409// Get certified object name 13410name.t.size = ObjectGetName(in->objectHandle, &name.t.name); 13411// Re-compute ticket 13412TicketComputeCreation(in->creationTicket.hierarchy, &name, 13413&in->creationHash, &ticket); 13414// Compare ticket 13415if(!Memory2BEqual(&ticket.digest.b, &in->creationTicket.digest.b)) 13416return TPM_RC_TICKET + RC_CertifyCreation_creationTicket; 13417// Command Output 13418// Common fields 13419result = FillInAttestInfo(in->signHandle, &in->inScheme, &in->qualifyingData, 13420&certifyInfo); 13421if(result != TPM_RC_SUCCESS) 13422{ 13423if(result == TPM_RC_KEY) 13424return TPM_RC_KEY + RC_CertifyCreation_signHandle; 13425else 13426return RcSafeAddToResult(result, RC_CertifyCreation_inScheme); 13427} 13428// CertifyCreation specific fields 13429// Attestation type 13430certifyInfo.type = TPM_ST_ATTEST_CREATION; 13431certifyInfo.attested.creation.objectName = name; 13432// Copy the creationHash 13433certifyInfo.attested.creation.creationHash = in->creationHash; 13434 13435Family “2.0” 13436Level 00 Revision 00.99 13437 13438Published 13439Copyright © TCG 2006-2013 13440 13441Page 159 13442October 31, 2013 13443 13444 Part 3: Commands 1344547 1344648 1344749 1344850 1344951 1345052 1345153 1345254 1345355 1345456 1345557 1345658 1345759 1345860 1345961 1346062 1346163 1346264 1346365 1346466 1346567 1346668 1346769 1346870 1346971 13470 13471Trusted Platform Module Library 13472 13473// Sign attestation structure. A NULL signature will be returned if 13474// signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, 13475// TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at 13476// this point 13477result = SignAttestInfo(in->signHandle, 13478&in->inScheme, 13479&certifyInfo, 13480&in->qualifyingData, 13481&out->certifyInfo, 13482&out->signature); 13483// TPM_RC_ATTRIBUTES cannot be returned here as FillInAttestInfo would already 13484// have returned TPM_RC_KEY 13485pAssert(result != TPM_RC_ATTRIBUTES); 13486if(result != TPM_RC_SUCCESS) 13487return result; 13488// orderly state should be cleared because of the reporting of clock info 13489// if signing happens 13490if(in->signHandle != TPM_RH_NULL) 13491g_clearOrderly = TRUE; 13492return TPM_RC_SUCCESS; 13493} 13494 13495Page 160 13496October 31, 2013 13497 13498Published 13499Copyright © TCG 2006-2013 13500 13501Family “2.0” 13502Level 00 Revision 00.99 13503 13504 Trusted Platform Module Library 13505 1350620.4 13507 13508Part 3: Commands 13509 13510TPM2_Quote 13511 1351220.4.1 General Description 13513This command is used to quote PCR values. 13514NOTE 13515 13516See 20.1 for description of how the signing scheme is selected. 13517 13518The TPM will hash the list of PCR selected by PCRselect using the hash algorithm associated with 13519signHandle (this is the hash algorithm of the signing scheme, not the nameAlg of signHandle). 13520The digest is computed as the hash of the concatenation of all of the digest values of the selected PCR. 13521The concatenation of PCR is described in Part 1, Selecting Multiple PCR. 13522 13523Family “2.0” 13524Level 00 Revision 00.99 13525 13526Published 13527Copyright © TCG 2006-2013 13528 13529Page 161 13530October 31, 2013 13531 13532 Part 3: Commands 13533 13534Trusted Platform Module Library 13535 1353620.4.2 Command and Response 13537Table 81 — TPM2_Quote Command 13538Type 13539 13540Name 13541 13542Description 13543 13544TPMI_ST_COMMAND_TAG 13545 13546tag 13547 13548UINT32 13549 13550commandSize 13551 13552TPM_CC 13553 13554commandCode 13555 13556TPM_CC_Quote 13557 13558TPMI_DH_OBJECT 13559 13560@signHandle 13561 13562handle of key that will perform signature 13563Auth Index: 1 13564Auth Role: USER 13565 13566TPM2B_DATA 13567 13568qualifyingData 13569 13570data supplied by the caller 13571 13572TPMT_SIG_SCHEME+ 13573 13574inScheme 13575 13576signing scheme to use if the scheme for signHandle is 13577TPM_ALG_NULL 13578 13579TPML_PCR_SELECTION 13580 13581PCRselect 13582 13583PCR set to quote 13584 13585Table 82 — TPM2_Quote Response 13586Type 13587 13588Name 13589 13590Description 13591 13592TPM_ST 13593 13594tag 13595 13596see clause 8 13597 13598UINT32 13599 13600responseSize 13601 13602TPM_RC 13603 13604responseCode 13605 13606TPM2B_ATTEST 13607 13608quoted 13609 13610the quoted information 13611 13612TPMT_SIGNATURE 13613 13614signature 13615 13616the signature over quoted 13617 13618Page 162 13619October 31, 2013 13620 13621Published 13622Copyright © TCG 2006-2013 13623 13624Family “2.0” 13625Level 00 Revision 00.99 13626 13627 Trusted Platform Module Library 13628 13629Part 3: Commands 13630 1363120.4.3 Detailed Actions 136321 136332 136343 13635 13636#include "InternalRoutines.h" 13637#include "Attest_spt_fp.h" 13638#include "Quote_fp.h" 13639Error Returns 13640TPM_RC_KEY 13641 13642signHandle does not reference a signing key; 13643 13644TPM_RC_SCHEME 13645 136464 136475 136486 136497 136508 136519 1365210 1365311 1365412 1365513 1365614 1365715 1365816 1365917 1366018 1366119 1366220 1366321 1366422 1366523 1366624 1366725 1366826 1366927 1367028 1367129 1367230 1367331 1367432 1367533 1367634 1367735 1367836 1367937 1368038 1368139 1368240 1368341 1368442 1368543 1368644 1368745 1368846 1368947 1369048 1369149 1369250 1369351 13694 13695Meaning 13696 13697the scheme is not compatible with sign key type, or input scheme is 13698not compatible with default scheme, or the chosen scheme is not a 13699valid sign scheme 13700 13701TPM_RC 13702TPM2_Quote( 13703Quote_In 13704Quote_Out 13705 13706*in, 13707*out 13708 13709// IN: input parameter list 13710// OUT: output parameter list 13711 13712) 13713{ 13714TPM_RC 13715TPMI_ALG_HASH 13716TPMS_ATTEST 13717 13718result; 13719hashAlg; 13720quoted; 13721 13722// Command Output 13723// Filling in attest information 13724// Common fields 13725// FillInAttestInfo will return TPM_RC_SCHEME or TPM_RC_KEY 13726result = FillInAttestInfo(in->signHandle, 13727&in->inScheme, 13728&in->qualifyingData, 13729"ed); 13730if(result != TPM_RC_SUCCESS) 13731{ 13732if(result == TPM_RC_KEY) 13733return TPM_RC_KEY + RC_Quote_signHandle; 13734else 13735return RcSafeAddToResult(result, RC_Quote_inScheme); 13736} 13737// Quote specific fields 13738// Attestation type 13739quoted.type = TPM_ST_ATTEST_QUOTE; 13740// Get hash algorithm in sign scheme. This hash algorithm is used to 13741// compute PCR digest. If there is no algorithm, then the PCR cannot 13742// be digested and this command returns TPM_RC_SCHEME 13743hashAlg = in->inScheme.details.any.hashAlg; 13744if(hashAlg == TPM_ALG_NULL) 13745return TPM_RC_SCHEME + RC_Quote_inScheme; 13746// Compute PCR digest 13747PCRComputeCurrentDigest(hashAlg, 13748&in->PCRselect, 13749"ed.attested.quote.pcrDigest); 13750// Copy PCR select. "PCRselect" is modified in PCRComputeCurrentDigest 13751// function 13752quoted.attested.quote.pcrSelect = in->PCRselect; 13753 13754Family “2.0” 13755Level 00 Revision 00.99 13756 13757Published 13758Copyright © TCG 2006-2013 13759 13760Page 163 13761October 31, 2013 13762 13763 Part 3: Commands 1376452 1376553 1376654 1376755 1376856 1376957 1377058 1377159 1377260 1377361 1377462 1377563 1377664 1377765 1377866 1377967 1378068 1378169 1378270 1378371 1378472 1378573 1378674 13787 13788Trusted Platform Module Library 13789 13790// Sign attestation structure. A NULL signature will be returned if 13791// signHandle is TPM_RH_NULL. TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES 13792// error may be returned by SignAttestInfo. 13793// NOTE: TPM_RC_ATTRIBUTES means that the key is not a signing key but that 13794// was checked above and TPM_RC_KEY was returned. TPM_RC_VALUE means that the 13795// value to sign is too large but that means that the digest is too big and 13796// that can't happen. 13797result = SignAttestInfo(in->signHandle, 13798&in->inScheme, 13799"ed, 13800&in->qualifyingData, 13801&out->quoted, 13802&out->signature); 13803if(result != TPM_RC_SUCCESS) 13804return result; 13805// orderly state should be cleared because of the reporting of clock info 13806// if signing happens 13807if(in->signHandle != TPM_RH_NULL) 13808g_clearOrderly = TRUE; 13809return TPM_RC_SUCCESS; 13810} 13811 13812Page 164 13813October 31, 2013 13814 13815Published 13816Copyright © TCG 2006-2013 13817 13818Family “2.0” 13819Level 00 Revision 00.99 13820 13821 Trusted Platform Module Library 13822 1382320.5 13824 13825Part 3: Commands 13826 13827TPM2_GetSessionAuditDigest 13828 1382920.5.1 General Description 13830This command returns a digital signature of the audit session digest. 13831NOTE 1 13832 13833See 20.1 for description of how the signing scheme is selected. 13834 13835If sessionHandle is not an audit session, the TPM shall return TPM_RC_TYPE. 13836NOTE 2 13837 13838A session does not become an audit session until the successful completion of the command in 13839which the session is first used as an audit session. 13840 13841This command requires authorization from the privacy administrator of the TPM (expressed with 13842endorsementAuth) as well as authorization to use the key associated with signHandle. 13843If this command is audited, then the audit digest that is signed will not include the digest of this command 13844because the audit digest is only updated when the command completes successfully. 13845This command does not cause the audit session to be closed and does not reset the digest value. 13846NOTE 3 13847 13848The audit session digest will be reset if the sessionHandle is used as the audit session for the 13849command and the auditReset attribute of the session is set; and this command will be the first 13850command in the audit digest. 13851 13852NOTE 4 13853 13854A reason for using 'sessionHahdle' in this command is so that the continueSession attribute may be 13855CLEAR. This will flush the session at the end of the command. 13856 13857Family “2.0” 13858Level 00 Revision 00.99 13859 13860Published 13861Copyright © TCG 2006-2013 13862 13863Page 165 13864October 31, 2013 13865 13866 Part 3: Commands 13867 13868Trusted Platform Module Library 13869 1387020.5.2 Command and Response 13871Table 83 — TPM2_GetSessionAuditDigest Command 13872Type 13873 13874Name 13875 13876TPMI_ST_COMMAND_TAG 13877 13878tag 13879 13880UINT32 13881 13882commandSize 13883 13884TPM_CC 13885 13886commandCode 13887 13888TPM_CC_GetSessionAuditDigest 13889 13890TPMI_RH_ENDORSEMENT 13891 13892@privacyAdminHandle 13893 13894handle of the privacy administrator 13895(TPM_RH_ENDORSEMENT) 13896Auth Index: 1 13897Auth Role: USER 13898 13899TPMI_DH_OBJECT+ 13900 13901@signHandle 13902 13903handle of the signing key 13904Auth Index: 2 13905Auth Role: USER 13906 13907TPMI_SH_HMAC 13908 13909sessionHandle 13910 13911handle of the audit session 13912Auth Index: None 13913 13914TPM2B_DATA 13915 13916qualifyingData 13917 13918user-provided qualifying data – may be zero-length 13919 13920TPMT_SIG_SCHEME+ 13921 13922inScheme 13923 13924signing scheme to use if the scheme for signHandle is 13925TPM_ALG_NULL 13926 13927Description 13928 13929Table 84 — TPM2_GetSessionAuditDigest Response 13930Type 13931 13932Name 13933 13934Description 13935 13936TPM_ST 13937 13938tag 13939 13940see clause 8 13941 13942UINT32 13943 13944responseSize 13945 13946TPM_RC 13947 13948responseCode 13949 13950TPM2B_ATTEST 13951 13952auditInfo 13953 13954the audit information that was signed 13955 13956TPMT_SIGNATURE 13957 13958signature 13959 13960the signature over auditInfo 13961 13962Page 166 13963October 31, 2013 13964 13965Published 13966Copyright © TCG 2006-2013 13967 13968Family “2.0” 13969Level 00 Revision 00.99 13970 13971 Trusted Platform Module Library 13972 13973Part 3: Commands 13974 1397520.5.3 Detailed Actions 139761 139772 139783 13979 13980#include "InternalRoutines.h" 13981#include "Attest_spt_fp.h" 13982#include "GetSessionAuditDigest_fp.h" 13983Error Returns 13984TPM_RC_KEY 13985 13986key referenced by signHandle is not a signing key 13987 13988TPM_RC_SCHEME 13989 13990inScheme is incompatible with signHandle type; or both scheme and 13991key's default scheme are empty; or scheme is empty while key's 13992default scheme requires explicit input scheme (split signing); or nonempty default key scheme differs from scheme 13993 13994TPM_RC_TYPE 13995 13996sessionHandle does not reference an audit session 13997 13998TPM_RC_VALUE 13999 140004 140015 140026 140037 140048 140059 1400610 1400711 1400812 1400913 1401014 1401115 1401216 1401317 1401418 1401519 1401620 1401721 1401822 1401923 1402024 1402125 1402226 1402327 1402428 1402529 1402630 1402731 1402832 1402933 1403034 1403135 1403236 1403337 1403438 1403539 1403640 1403741 1403842 1403943 1404044 14041 14042Meaning 14043 14044digest generated for the given scheme is greater than the modulus of 14045signHandle (for an RSA key); invalid commit status or failed to 14046generate r value (for an ECC key) 14047 14048TPM_RC 14049TPM2_GetSessionAuditDigest( 14050GetSessionAuditDigest_In 14051GetSessionAuditDigest_Out 14052 14053*in, 14054*out 14055 14056// IN: input parameter list 14057// OUT: output parameter list 14058 14059) 14060{ 14061TPM_RC 14062SESSION 14063TPMS_ATTEST 14064 14065result; 14066*session; 14067auditInfo; 14068 14069// Input Validation 14070// SessionAuditDigest specific input validation 14071// Get session pointer 14072session = SessionGet(in->sessionHandle); 14073// session must be an audit session 14074if(session->attributes.isAudit == CLEAR) 14075return TPM_RC_TYPE + RC_GetSessionAuditDigest_sessionHandle; 14076// Command Output 14077// Filling in attest information 14078// Common fields 14079result = FillInAttestInfo(in->signHandle, 14080&in->inScheme, 14081&in->qualifyingData, 14082&auditInfo); 14083if(result != TPM_RC_SUCCESS) 14084{ 14085if(result == TPM_RC_KEY) 14086return TPM_RC_KEY + RC_GetSessionAuditDigest_signHandle; 14087else 14088return RcSafeAddToResult(result, RC_GetSessionAuditDigest_inScheme); 14089} 14090// SessionAuditDigest specific fields 14091// Attestation type 14092auditInfo.type = TPM_ST_ATTEST_SESSION_AUDIT; 14093// Copy digest 14094 14095Family “2.0” 14096Level 00 Revision 00.99 14097 14098Published 14099Copyright © TCG 2006-2013 14100 14101Page 167 14102October 31, 2013 14103 14104 Part 3: Commands 1410545 1410646 1410747 1410848 1410949 1411050 1411151 1411252 1411353 1411454 1411555 1411656 1411757 1411858 1411959 1412060 1412161 1412262 1412363 1412464 1412565 1412666 1412767 1412868 1412969 1413070 1413171 1413272 14133 14134Trusted Platform Module Library 14135 14136auditInfo.attested.sessionAudit.sessionDigest = session->u2.auditDigest; 14137// Exclusive audit session 14138if(g_exclusiveAuditSession == in->sessionHandle) 14139auditInfo.attested.sessionAudit.exclusiveSession = TRUE; 14140else 14141auditInfo.attested.sessionAudit.exclusiveSession = FALSE; 14142// Sign attestation structure. A NULL signature will be returned if 14143// signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, 14144// TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at 14145// this point 14146result = SignAttestInfo(in->signHandle, 14147&in->inScheme, 14148&auditInfo, 14149&in->qualifyingData, 14150&out->auditInfo, 14151&out->signature); 14152if(result != TPM_RC_SUCCESS) 14153return result; 14154// orderly state should be cleared because of the reporting of clock info 14155// if signing happens 14156if(in->signHandle != TPM_RH_NULL) 14157g_clearOrderly = TRUE; 14158return TPM_RC_SUCCESS; 14159} 14160 14161Page 168 14162October 31, 2013 14163 14164Published 14165Copyright © TCG 2006-2013 14166 14167Family “2.0” 14168Level 00 Revision 00.99 14169 14170 Trusted Platform Module Library 14171 1417220.6 14173 14174Part 3: Commands 14175 14176TPM2_GetCommandAuditDigest 14177 1417820.6.1 General Description 14179This command returns the current value of the command audit digest, a digest of the commands being 14180audited, and the audit hash algorithm. These values are placed in an attestation structure and signed with 14181the key referenced by signHandle. 14182NOTE 1 14183 14184See 20.1 for description of how the signing scheme is selected. 14185 14186When this command completes successfully, and signHandle is not TPM_RH_NULL, the audit digest is 14187cleared. 14188NOTE 2 14189 14190The way that the TPM tracks that the digest is clear is vendor -dependent. The reference 14191implementation resets the size of the digest to zero. 14192 14193If this command is being audited, then the signed digest produced by the command will not include the 14194command. At the end of this command, the audit digest will be extended with cpHash and the rpHash of 14195the command which would change the command audit digest signed by the next invocation of this 14196command. 14197This command requires authorization from the privacy administrator of the TPM (expressed with 14198endorsementAuth) as well as authorization to use the key associated with signHandle. 14199 14200Family “2.0” 14201Level 00 Revision 00.99 14202 14203Published 14204Copyright © TCG 2006-2013 14205 14206Page 169 14207October 31, 2013 14208 14209 Part 3: Commands 14210 14211Trusted Platform Module Library 14212 1421320.6.2 Command and Response 14214Table 85 — TPM2_GetCommandAuditDigest Command 14215Type 14216 14217Name 14218 14219Description 14220 14221TPMI_ST_COMMAND_TAG 14222 14223tag 14224 14225UINT32 14226 14227commandSize 14228 14229TPM_CC 14230 14231commandCode 14232 14233TPM_CC_GetCommandAuditDigest {NV} 14234 14235TPMI_RH_ENDORSEMENT 14236 14237@privacyHandle 14238 14239handle of the privacy administrator 14240(TPM_RH_ENDORSEMENT) 14241Auth Index: 1 14242Auth Role: USER 14243 14244TPMI_DH_OBJECT+ 14245 14246@signHandle 14247 14248the handle of the signing key 14249Auth Index: 2 14250Auth Role: USER 14251 14252TPM2B_DATA 14253 14254qualifyingData 14255 14256other data to associate with this audit digest 14257 14258TPMT_SIG_SCHEME+ 14259 14260inScheme 14261 14262signing scheme to use if the scheme for signHandle is 14263TPM_ALG_NULL 14264 14265Table 86 — TPM2_GetCommandAuditDigest Response 14266Type 14267 14268Name 14269 14270Description 14271 14272TPM_ST 14273 14274tag 14275 14276see clause 8 14277 14278UINT32 14279 14280responseSize 14281 14282TPM_RC 14283 14284responseCode 14285 14286TPM2B_ATTEST 14287 14288auditInfo 14289 14290the auditInfo that was signed 14291 14292TPMT_SIGNATURE 14293 14294signature 14295 14296the signature over auditInfo 14297 14298Page 170 14299October 31, 2013 14300 14301Published 14302Copyright © TCG 2006-2013 14303 14304Family “2.0” 14305Level 00 Revision 00.99 14306 14307 Trusted Platform Module Library 14308 14309Part 3: Commands 14310 1431120.6.3 Detailed Actions 143121 143132 143143 14315 14316#include "InternalRoutines.h" 14317#include "Attest_spt_fp.h" 14318#include "GetCommandAuditDigest_fp.h" 14319Error Returns 14320TPM_RC_KEY 14321 14322key referenced by signHandle is not a signing key 14323 14324TPM_RC_SCHEME 14325 14326inScheme is incompatible with signHandle type; or both scheme and 14327key's default scheme are empty; or scheme is empty while key's 14328default scheme requires explicit input scheme (split signing); or nonempty default key scheme differs from scheme 14329 14330TPM_RC_VALUE 14331 143324 143335 143346 143357 143368 143379 1433810 1433911 1434012 1434113 1434214 1434315 1434416 1434517 1434618 1434719 1434820 1434921 1435022 1435123 1435224 1435325 1435426 1435527 1435628 1435729 1435830 1435931 1436032 1436133 1436234 1436335 1436436 1436537 1436638 1436739 1436840 1436941 1437042 1437143 1437244 1437345 1437446 14375 14376Meaning 14377 14378digest generated for the given scheme is greater than the modulus of 14379signHandle (for an RSA key); invalid commit status or failed to 14380generate r value (for an ECC key) 14381 14382TPM_RC 14383TPM2_GetCommandAuditDigest( 14384GetCommandAuditDigest_In 14385GetCommandAuditDigest_Out 14386 14387*in, 14388*out 14389 14390// IN: input parameter list 14391// OUT: output parameter list 14392 14393) 14394{ 14395TPM_RC 14396TPMS_ATTEST 14397 14398result; 14399auditInfo; 14400 14401// Command Output 14402// Filling in attest information 14403// Common fields 14404result = FillInAttestInfo(in->signHandle, 14405&in->inScheme, 14406&in->qualifyingData, 14407&auditInfo); 14408if(result != TPM_RC_SUCCESS) 14409{ 14410if(result == TPM_RC_KEY) 14411return TPM_RC_KEY + RC_GetCommandAuditDigest_signHandle; 14412else 14413return RcSafeAddToResult(result, RC_GetCommandAuditDigest_inScheme); 14414} 14415// CommandAuditDigest specific fields 14416// Attestation type 14417auditInfo.type = TPM_ST_ATTEST_COMMAND_AUDIT; 14418// Copy audit hash algorithm 14419auditInfo.attested.commandAudit.digestAlg = gp.auditHashAlg; 14420// Copy counter value 14421auditInfo.attested.commandAudit.auditCounter = gp.auditCounter; 14422// Copy command audit log 14423auditInfo.attested.commandAudit.auditDigest = gr.commandAuditDigest; 14424CommandAuditGetDigest(&auditInfo.attested.commandAudit.commandDigest); 14425// 14426// 14427// 14428// 14429 14430Sign attestation structure. A NULL signature will be returned if 14431signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, 14432TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at 14433this point 14434 14435Family “2.0” 14436Level 00 Revision 00.99 14437 14438Published 14439Copyright © TCG 2006-2013 14440 14441Page 171 14442October 31, 2013 14443 14444 Part 3: Commands 1444547 1444648 1444749 1444850 1444951 1445052 1445153 1445254 1445355 1445456 1445557 1445658 1445759 1445860 1445961 1446062 1446163 1446264 1446365 1446466 1446567 1446668 1446769 1446870 14469 14470Trusted Platform Module Library 14471 14472result = SignAttestInfo(in->signHandle, 14473&in->inScheme, 14474&auditInfo, 14475&in->qualifyingData, 14476&out->auditInfo, 14477&out->signature); 14478if(result != TPM_RC_SUCCESS) 14479return result; 14480// Internal Data Update 14481if(in->signHandle != TPM_RH_NULL) 14482{ 14483// Reset log 14484gr.commandAuditDigest.t.size = 0; 14485// orderly state should be cleared because of the update in 14486// commandAuditDigest, as well as the reporting of clock info 14487g_clearOrderly = TRUE; 14488} 14489return TPM_RC_SUCCESS; 14490} 14491 14492Page 172 14493October 31, 2013 14494 14495Published 14496Copyright © TCG 2006-2013 14497 14498Family “2.0” 14499Level 00 Revision 00.99 14500 14501 Trusted Platform Module Library 14502 1450320.7 14504 14505Part 3: Commands 14506 14507TPM2_GetTime 14508 1450920.7.1 General Description 14510This command returns the current values of Time and Clock. 14511NOTE 1 14512 14513See 20.1 for description of how the signing scheme is selected. 14514 14515The values of Clock, resetCount and restartCount appear in two places in timeInfo: once in 14516TPMS_ATTEST.clockInfo and again in TPMS_ATTEST.attested.time.clockInfo. The firmware version 14517number 14518also 14519appears 14520in 14521two 14522places 14523(TPMS_ATTEST.firmwareVersion 14524and 14525TPMS_ATTEST.attested.time.firmwareVersion). If signHandle is in the endorsement or platform 14526hierarchies, both copies of the data will be the same. However, if signHandle is in the storage hierarchy or 14527is TPM_RH_NULL, the values in TPMS_ATTEST.clockInfo and TPMS_ATTEST.firmwareVersion are 14528obfuscated but the values in TPM_ATTEST.attested.time are not. 14529NOTE 2 14530 14531The purpose of this duplication is to allow an entity who is trusted by the privacy Administrator to 14532correlate the obfuscated values with the clear -text values. 14533 14534Family “2.0” 14535Level 00 Revision 00.99 14536 14537Published 14538Copyright © TCG 2006-2013 14539 14540Page 173 14541October 31, 2013 14542 14543 Part 3: Commands 14544 14545Trusted Platform Module Library 14546 1454720.7.2 Command and Response 14548Table 87 — TPM2_GetTime Command 14549Type 14550 14551Name 14552 14553TPMI_ST_COMMAND_TAG 14554 14555tag 14556 14557UINT32 14558 14559commandSize 14560 14561TPM_CC 14562 14563commandCode 14564 14565TPM_CC_GetTime 14566 14567TPMI_RH_ENDORSEMENT 14568 14569@privacyAdminHandle 14570 14571handle of the privacy administrator 14572(TPM_RH_ENDORSEMENT) 14573Auth Index: 1 14574Auth Role: USER 14575 14576TPMI_DH_OBJECT+ 14577 14578@signHandle 14579 14580the keyHandle identifier of a loaded key that can 14581perform digital signatures 14582Auth Index: 2 14583Auth Role: USER 14584 14585TPM2B_DATA 14586 14587qualifyingData 14588 14589data to tick stamp 14590 14591TPMT_SIG_SCHEME+ 14592 14593inScheme 14594 14595signing scheme to use if the scheme for signHandle is 14596TPM_ALG_NULL 14597 14598Description 14599 14600Table 88 — TPM2_GetTime Response 14601Type 14602 14603Name 14604 14605Description 14606 14607TPM_ST 14608 14609tag 14610 14611see clause 8 14612 14613UINT32 14614 14615responseSize 14616 14617TPM_RC 14618 14619responseCode 14620 14621. 14622 14623TPM2B_ATTEST 14624 14625timeInfo 14626 14627standard TPM-generated attestation block 14628 14629TPMT_SIGNATURE 14630 14631signature 14632 14633the signature over timeInfo 14634 14635Page 174 14636October 31, 2013 14637 14638Published 14639Copyright © TCG 2006-2013 14640 14641Family “2.0” 14642Level 00 Revision 00.99 14643 14644 Trusted Platform Module Library 14645 14646Part 3: Commands 14647 1464820.7.3 Detailed Actions 146491 146502 146513 14652 14653#include "InternalRoutines.h" 14654#include "Attest_spt_fp.h" 14655#include "GetTime_fp.h" 14656Error Returns 14657TPM_RC_KEY 14658 14659key referenced by signHandle is not a signing key 14660 14661TPM_RC_SCHEME 14662 14663inScheme is incompatible with signHandle type; or both scheme and 14664key's default scheme are empty; or scheme is empty while key's 14665default scheme requires explicit input scheme (split signing); or nonempty default key scheme differs from scheme 14666 14667TPM_RC_VALUE 14668 146694 146705 146716 146727 146738 146749 1467510 1467611 1467712 1467813 1467914 1468015 1468116 1468217 1468318 1468419 1468520 1468621 1468722 1468823 1468924 1469025 1469126 1469227 1469328 1469429 1469530 1469631 1469732 1469833 1469934 1470035 1470136 1470237 1470338 1470439 1470540 1470641 1470742 1470843 1470944 1471045 1471146 14712 14713Meaning 14714 14715digest generated for the given scheme is greater than the modulus of 14716signHandle (for an RSA key); invalid commit status or failed to 14717generate r value (for an ECC key) 14718 14719TPM_RC 14720TPM2_GetTime( 14721GetTime_In 14722GetTime_Out 14723 14724*in, 14725*out 14726 14727// IN: input parameter list 14728// OUT: output parameter list 14729 14730) 14731{ 14732TPM_RC 14733TPMS_ATTEST 14734 14735result; 14736timeInfo; 14737 14738// Command Output 14739// Filling in attest information 14740// Common fields 14741result = FillInAttestInfo(in->signHandle, 14742&in->inScheme, 14743&in->qualifyingData, 14744&timeInfo); 14745if(result != TPM_RC_SUCCESS) 14746{ 14747if(result == TPM_RC_KEY) 14748return TPM_RC_KEY + RC_GetTime_signHandle; 14749else 14750return RcSafeAddToResult(result, RC_GetTime_inScheme); 14751} 14752// GetClock specific fields 14753// Attestation type 14754timeInfo.type = TPM_ST_ATTEST_TIME; 14755// current clock in plain text 14756timeInfo.attested.time.time.time = g_time; 14757TimeFillInfo(&timeInfo.attested.time.time.clockInfo); 14758// Firmware version in plain text 14759timeInfo.attested.time.firmwareVersion 14760= ((UINT64) gp.firmwareV1) << 32; 14761timeInfo.attested.time.firmwareVersion += gp.firmwareV2; 14762// Sign attestation structure. A NULL signature will be returned if 14763// signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, 14764// TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at 14765// this point 14766result = SignAttestInfo(in->signHandle, 14767 14768Family “2.0” 14769Level 00 Revision 00.99 14770 14771Published 14772Copyright © TCG 2006-2013 14773 14774Page 175 14775October 31, 2013 14776 14777 Part 3: Commands 1477847 1477948 1478049 1478150 1478251 1478352 1478453 1478554 1478655 1478756 1478857 1478958 1479059 1479160 1479261 14793 14794Trusted Platform Module Library 14795 14796&in->inScheme, 14797&timeInfo, 14798&in->qualifyingData, 14799&out->timeInfo, 14800&out->signature); 14801if(result != TPM_RC_SUCCESS) 14802return result; 14803// orderly state should be cleared because of the reporting of clock info 14804// if signing happens 14805if(in->signHandle != TPM_RH_NULL) 14806g_clearOrderly = TRUE; 14807return TPM_RC_SUCCESS; 14808} 14809 14810Page 176 14811October 31, 2013 14812 14813Published 14814Copyright © TCG 2006-2013 14815 14816Family “2.0” 14817Level 00 Revision 00.99 14818 14819 Trusted Platform Module Library 14820 1482121 14822 14823Part 3: Commands 14824 14825Ephemeral EC Keys 14826 1482721.1 14828 14829Introduction 14830 14831The TPM generates keys that have different lifetimes. TPM keys in a hierarchy can be persistent for as 14832long as the seed of the hierarchy is unchanged and these keys may be used multiple times. Other TPMgenerated keys are only useful for a single operation. Some of these single-use keys are used in the 14833command in which they are created. Examples of this use are TPM2_Duplicate() where an ephemeral 14834key is created for a single pass key exchange with another TPM. However, there are other cases, such 14835as anonymous attestation, where the protocol requires two passes where the public part of the ephemeral 14836key is used outside of the TPM before the final command "consumes" the ephemeral key. 14837For these uses, TPM2_Commit() or TPM2_EC_Ephemeral() may be used to have the TPM create an 14838ephemeral EC key and return the public part of the key for external use. Then in a subsequent command, 14839the caller provides a reference to the ephemeral key so that the TPM can retrieve or recreate the 14840associated private key. 14841When an ephemeral EC key is created, it is assigned a number and that number is returned to the caller 14842as the identifier for the key. This number is not a handle. A handle is assigned to a key that may be 14843context saved but these ephemeral EC keys may not be saved and do not have a full key context. When 14844a subsequent command uses the ephemeral key, the caller provides the number of the ephemeral key. 14845The TPM uses that number to either look up or recompute the associated private key. After the key is 14846used, the TPM records the fact that the key has been used so that it cannot be used again. 14847As mentioned, the TPM can keep each assigned private ephemeral key in memory until it is used. 14848However, this could consume a large amount of memory. To limit the memory size, the TPM is allowed to 14849restrict the number of pending private keys – keys that have been allocated but not used. 14850NOTE 14851 14852The minimum number of ephemeral keys is determined by a platform specific specification 14853 14854To further reduce the memory requirements for the ephemeral private keys, the TPM is allowed to use 14855pseudo-random values for the ephemeral keys. Instead of keeping the full value of the key in memory, the 14856TPM can use a counter as input to a KDF. Incrementing the counter will cause the TPM to generate a 14857new pseudo-random value. 14858Using the counter to generate pseudo-random private ephemeral keys greatly simplifies tracking of key 14859usage. When a counter value is used to create a key, a bit in an array may be set to indicate that the key 14860use is pending. When the ephemeral key is consumed, the bit is cleared. This prevents the key from 14861being used more than once. 14862Since the TPM is allowed to restrict the number of pending ephemeral keys, the array size can be limited. 14863For example, a 128 bit array would allow 128 keys to be "pending". 14864The management of the array is described in greater detail in the Split Operations clause in Annex C of 14865part 1. 14866 14867Family “2.0” 14868Level 00 Revision 00.99 14869 14870Published 14871Copyright © TCG 2006-2013 14872 14873Page 177 14874October 31, 2013 14875 14876 Part 3: Commands 14877 1487821.2 14879 14880Trusted Platform Module Library 14881 14882TPM2_Commit 14883 1488421.2.1 General Description 14885TPM2_Commit() performs the first part of an ECC anonymous signing operation. The TPM will perform 14886the point multiplications on the provided points and return intermediate signing values. The signHandle 14887parameter shall refer to an ECC key with the sign attribute (TPM_RC_ATTRIBUTES) using an 14888anonymous signing scheme (TPM_RC_SCHEME). 14889For this command, p1, s2 and y2 are optional parameters. If s2 is an Empty Buffer, then the TPM shall 14890return TPM_RC_SIZE if y2 is not an Empty Buffer. If p1, s2, and y2 are all Empty Buffers, the TPM shall 14891return TPM_RC_NO_RESULT. 14892In the algorithm below, the following additional values are used in addition to the command parameters: 14893 14894HnameAlg 14895 14896hash function using the nameAlg of the key associated with 14897signHandle 14898 14899p 14900 14901field modulus of the curve associated with signHandle 14902 14903n 14904 14905order of the curve associated with signHandle 14906 14907ds 14908 14909private key associated with signHandle 14910 14911c 14912 14913counter that increments each time a TPM2_Commit() is 14914successfully completed 14915 14916A[i] 14917 14918array of bits used to indicate when a value of c has been used in 14919a signing operation; values of i are 0 to 2n-1 14920 14921k 14922 14923nonce that is set to a random value on each TPM Reset; nonce 14924size is twice the security strength of any ECDAA key supported 14925by the TPM. 14926 14927The algorithm is: 14928a) set K, L, and E to be Empty Buffers. 14929b) if s2 is not an Empty Buffer, compute x2 ≔ HnameAlg (s2) mod p, else skip to step (e) 14930c) if (x2, y2) is not a point on the curve of signHandle, return TPM_RC_ECC_POINT 14931d) set K ≔ [ds] (x2, y2) 14932e) generate or derive r (see the "Commit Random Value" clause in Part 1) 14933f) 14934 14935set r ≔ r mod n 14936 14937NOTE 1 14938 14939nLen is the number of bits in n 14940 14941g) if p1 is an Empty Buffer, skip to step i) 14942h) if (p1) is not a point on the curve of signHandle, return TPM_RC_ECC_POINT 14943i) 14944 14945set E ≔ [r] (p1) 14946 14947j) 14948 14949if K is not an Empty Buffer, set L ≔ [r] (x2, y2) 14950 14951k) if K, L, or E is the point at infinity, return TPM_RC_NO_RESULT 14952l) 14953 14954set counter ≔ commitCount 14955 14956m) set commitCount ≔ commitCount + 1 14957 14958Page 178 14959October 31, 2013 14960 14961Published 14962Copyright © TCG 2006-2013 14963 14964Family “2.0” 14965Level 00 Revision 00.99 14966 14967 Trusted Platform Module Library 14968NOTE 2 14969 14970Part 3: Commands 14971 14972Depending on the method of generating r, it may be necessary to update the tracking array here. 14973 14974n) output K, L, E and counter 14975NOTE 3 14976 14977Depending on the input parameters K and L may be Empty Buffers or E may be an Empty Buffer 14978 14979Family “2.0” 14980Level 00 Revision 00.99 14981 14982Published 14983Copyright © TCG 2006-2013 14984 14985Page 179 14986October 31, 2013 14987 14988 Part 3: Commands 14989 14990Trusted Platform Module Library 14991 1499221.2.2 Command and Response 14993Table 89 — TPM2_Commit Command 14994Type 14995 14996Name 14997 14998TPMI_ST_COMMAND_TAG 14999 15000tag 15001 15002UINT32 15003 15004paramSize 15005 15006TPM_CC 15007 15008commandCode 15009 15010Description 15011 15012TPM_CC_Commit 15013handle of the key that will be used in the signing 15014operation 15015 15016TPMI_DH_OBJECT 15017 15018@signHandle 15019 15020Auth Index: 1 15021Auth Role: USER 15022 15023TPM2B_ECC_POINT 15024 15025P1 15026 15027a point (M) on the curve used by signHandle 15028 15029TPM2B_SENSITIVE_DATA 15030 15031s2 15032 15033octet array used to derive x-coordinate of a base point 15034 15035TPM2B_ECC_PARAMETER 15036 15037y2 15038 15039y coordinate of the point associated with s2 15040 15041Table 90 — TPM2_Commit Response 15042Type 15043 15044Name 15045 15046Description 15047 15048TPM_ST 15049 15050tag 15051 15052see 8 15053 15054UINT32 15055 15056paramSize 15057 15058TPM_RC 15059 15060responseCode 15061 15062TPM2B_ECC_POINT 15063 15064K 15065 15066ECC point K ≔ [ds](x2, y2) 15067 15068TPM2B_ECC_POINT 15069 15070L 15071 15072ECC point L ≔ [r](x2, y2) 15073 15074TPM2B_ECC_POINT 15075 15076E 15077 15078ECC point E ≔ [r]P1 15079 15080UINT16 15081 15082counter 15083 15084least-significant 16 bits of commitCount 15085 15086Page 180 15087October 31, 2013 15088 15089Published 15090Copyright © TCG 2006-2013 15091 15092Family “2.0” 15093Level 00 Revision 00.99 15094 15095 Trusted Platform Module Library 15096 15097Part 3: Commands 15098 1509921.2.3 Detailed Actions 151001 151012 151023 15103 15104#include "InternalRoutines.h" 15105#include "Commit_fp.h" 15106#ifdef TPM_ALG_ECC 15107Error Returns 15108TPM_RC_ATTRIBUTES 15109 15110keyHandle references a restricted key that is not a signing key 15111 15112TPM_RC_ECC_POINT 15113 15114either P1 or the point derived from s2 is not on the curve of 15115keyHandle 15116 15117TPM_RC_HASH 15118 15119invalid name algorithm in keyHandle 15120 15121TPM_RC_KEY 15122 15123keyHandle does not reference an ECC key 15124 15125TPM_RC_SCHEME 15126 15127keyHandle references a restricted signing key that does not use and 15128anonymous scheme 15129 15130TPM_RC_NO_RESULT 15131 15132K, L or E was a point at infinity; or failed to generate r value 15133 15134TPM_RC_SIZE 151354 151365 151376 151387 151398 151409 1514110 1514211 1514312 1514413 1514514 1514615 1514716 1514817 1514918 1515019 1515120 1515221 1515322 1515423 1515524 1515625 1515726 1515827 1515928 1516029 1516130 1516231 1516332 1516433 1516534 1516635 1516736 1516837 1516938 1517039 1517140 1517241 1517342 1517443 15175 15176Meaning 15177 15178s2 is empty but y2 is not or s2 provided but y2 is not 15179 15180TPM_RC 15181TPM2_Commit( 15182Commit_In 15183Commit_Out 15184 15185*in, 15186*out 15187 15188// IN: input parameter list 15189// OUT: output parameter list 15190 15191) 15192{ 15193OBJECT 15194TPMS_ECC_POINT 15195TPMS_ECC_POINT 15196TPMS_ECC_POINT 15197TPM2B_ECC_PARAMETER 15198TPM2B 15199TPM_RC 15200UINT16 15201 15202*eccKey; 15203P2; 15204*pP2 = NULL; 15205*pP1 = NULL; 15206r; 15207*p; 15208result; 15209hashResults; 15210 15211// Input Validation 15212eccKey = ObjectGet(in->signHandle); 15213// Input key must be an ECC key 15214if(eccKey->publicArea.type != TPM_ALG_ECC) 15215return TPM_RC_KEY + RC_Commit_signHandle; 15216// if the key is restricted, it must be a signing key using an anonymous scheme 15217if(eccKey->publicArea.objectAttributes.restricted == SET) 15218{ 15219if(eccKey->publicArea.objectAttributes.sign != SET) 15220return TPM_RC_ATTRIBUTES + RC_Commit_signHandle; 15221if(!CryptIsSchemeAnonymous( 15222eccKey->publicArea.parameters.eccDetail.scheme.scheme)) 15223return TPM_RC_SCHEME + RC_Commit_signHandle; 15224} 15225else 15226{ 15227// if not restricted, s2, and y2 must be an Empty Buffer 15228if(in->s2.t.size) 15229return TPM_RC_SIZE + RC_Commit_s2; 15230} 15231// Make sure that both parts of P2 are present if either is present 15232if((in->s2.t.size == 0) != (in->y2.t.size == 0)) 15233 15234Family “2.0” 15235Level 00 Revision 00.99 15236 15237Published 15238Copyright © TCG 2006-2013 15239 15240Page 181 15241October 31, 2013 15242 15243 Part 3: Commands 1524444 1524545 1524646 1524747 1524848 1524949 1525050 1525151 1525252 1525353 1525454 1525555 1525656 1525757 1525858 1525959 1526060 1526161 1526262 1526363 1526464 1526565 1526666 1526767 1526868 1526969 1527070 1527171 1527272 1527373 1527474 1527575 1527676 1527777 1527878 1527979 1528080 1528181 1528282 1528383 1528484 1528585 1528686 1528787 1528888 1528989 1529090 1529191 1529292 1529393 1529494 1529595 1529696 1529797 1529898 1529999 15300100 15301101 15302102 15303103 15304104 15305105 15306106 15307107 15308 15309Trusted Platform Module Library 15310 15311return TPM_RC_SIZE + RC_Commit_y2; 15312// Get prime modulus for the curve. This is needed later but getting this now 15313// allows confirmation that the curve exists 15314p = (TPM2B *)CryptEccGetParameter('p', 15315eccKey->publicArea.parameters.eccDetail.curveID); 15316// if no p, then the curve ID is bad 15317// NOTE: This should never occur if the input unmarshaling code is working 15318// correctly 15319if(p == NULL) 15320return TPM_RC_KEY + RC_Commit_signHandle; 15321// Get the random value that will be used in the point multiplications 15322// Note: this does not commit the count. 15323if(!CryptGenerateR(&r, 15324NULL, 15325eccKey->publicArea.parameters.eccDetail.curveID, 15326&eccKey->name)) 15327return TPM_RC_NO_RESULT; 15328// Set up P2 if s2 and Y2 are provided 15329if(in->s2.t.size != 0) 15330{ 15331pP2 = &P2; 15332// copy y2 for P2 15333MemoryCopy2B(&P2.y.b, &in->y2.b, sizeof(P2.y.t.buffer)); 15334// Compute x2 HnameAlg(s2) mod p 15335// 15336do the hash operation on s2 with the size of curve 'p' 15337hashResults = CryptHashBlock(eccKey->publicArea.nameAlg, 15338in->s2.t.size, 15339in->s2.t.buffer, 15340p->size, 15341P2.x.t.buffer); 15342// If there were error returns in the hash routine, indicate a problem 15343// with the hash in 15344if(hashResults == 0) 15345return TPM_RC_HASH + RC_Commit_signHandle; 15346// set the size of the X value to the size of the hash 15347P2.x.t.size = hashResults; 15348// set p2.x = hash(s2) mod p 15349if(CryptDivide(&P2.x.b, p, NULL, &P2.x.b) != TPM_RC_SUCCESS) 15350return TPM_RC_NO_RESULT; 15351if(!CryptEccIsPointOnCurve(eccKey->publicArea.parameters.eccDetail.curveID, 15352pP2)) 15353return TPM_RC_ECC_POINT + RC_Commit_s2; 15354if(eccKey->attributes.publicOnly == SET) 15355return TPM_RC_KEY + RC_Commit_signHandle; 15356} 15357else 15358// If there is a P1, make sure that it is on the curve 15359// NOTE: an "empty" point has two UINT16 values which are the size values 15360// for each of the coordinates. 15361if(in->P1.t.size > 4) 15362{ 15363 15364Page 182 15365October 31, 2013 15366 15367Published 15368Copyright © TCG 2006-2013 15369 15370Family “2.0” 15371Level 00 Revision 00.99 15372 15373 Trusted Platform Module Library 15374108 15375109 15376110 15377111 15378112 15379113 15380114 15381115 15382116 15383117 15384118 15385119 15386120 15387121 15388122 15389123 15390124 15391125 15392126 15393127 15394128 15395129 15396130 15397131 15398132 15399133 15400134 15401135 15402136 15403137 15404138 15405139 15406 15407Part 3: Commands 15408 15409pP1 = &in->P1.t.point; 15410if(!CryptEccIsPointOnCurve(eccKey->publicArea.parameters.eccDetail.curveID, 15411pP1)) 15412return TPM_RC_ECC_POINT + RC_Commit_P1; 15413} 15414// Pass the parameters to CryptCommit. 15415// The work is not done inline because it does several point multiplies 15416// with the same curve. There is significant optimization by not 15417// having to reload the curve parameters multiple times. 15418result = CryptCommitCompute(&out->K.t.point, 15419&out->L.t.point, 15420&out->E.t.point, 15421eccKey->publicArea.parameters.eccDetail.curveID, 15422pP1, 15423pP2, 15424&eccKey->sensitive.sensitive.ecc, 15425&r); 15426if(result != TPM_RC_SUCCESS) 15427return result; 15428out->K.t.size = TPMS_ECC_POINT_Marshal(&out->K.t.point, NULL, NULL); 15429out->L.t.size = TPMS_ECC_POINT_Marshal(&out->L.t.point, NULL, NULL); 15430out->E.t.size = TPMS_ECC_POINT_Marshal(&out->E.t.point, NULL, NULL); 15431// The commit computation was successful so complete the commit by setting 15432// the bit 15433out->counter = CryptCommit(); 15434return TPM_RC_SUCCESS; 15435} 15436#endif 15437 15438Family “2.0” 15439Level 00 Revision 00.99 15440 15441Published 15442Copyright © TCG 2006-2013 15443 15444Page 183 15445October 31, 2013 15446 15447 Part 3: Commands 15448 1544921.3 15450 15451Trusted Platform Module Library 15452 15453TPM2_EC_Ephemeral 15454 1545521.3.1 General Description 15456TPM2_EC_Ephemeral() creates an ephemeral key for use in a two-phase key exchange protocol. 15457The TPM will use the commit mechanism to assign an ephemeral key r and compute a public point Q ≔ 15458[r]G where G is the generator point associated with curveID. 15459 15460Page 184 15461October 31, 2013 15462 15463Published 15464Copyright © TCG 2006-2013 15465 15466Family “2.0” 15467Level 00 Revision 00.99 15468 15469 Trusted Platform Module Library 15470 15471Part 3: Commands 15472 1547321.3.2 Command and Response 15474Table 91 — TPM2_EC_Ephemeral Command 15475Type 15476 15477Name 15478 15479Description 15480 15481TPMI_ST_COMMAND_TAG 15482 15483tag 15484 15485UINT32 15486 15487paramSize 15488 15489TPM_CC 15490 15491commandCode 15492 15493TPM_CC_EC_Ephemeral 15494 15495TPMI_ECC_CURVE 15496 15497curveID 15498 15499The curve for the computed ephemeral point 15500 15501Table 92 — TPM2_EC_Ephemeral Response 15502Type 15503 15504Name 15505 15506Description 15507 15508TPM_ST 15509 15510tag 15511 15512see 8 15513 15514UINT32 15515 15516paramSize 15517 15518TPM_RC 15519 15520responseCode 15521 15522TPM2B_ECC_POINT 15523 15524Q 15525 15526ephemeral public key Q ≔ [r]G 15527 15528UINT16 15529 15530counter 15531 15532least-significant 16 bits of commitCount 15533 15534Family “2.0” 15535Level 00 Revision 00.99 15536 15537Published 15538Copyright © TCG 2006-2013 15539 15540Page 185 15541October 31, 2013 15542 15543 Part 3: Commands 15544 15545Trusted Platform Module Library 15546 1554721.3.3 Detailed Actions 155481 155492 155503 15551 15552#include "InternalRoutines.h" 15553#include "EC_Ephemeral_fp.h" 15554#ifdef TPM_ALG_ECC 15555Error Returns 15556none 15557 155584 155595 155606 155617 155628 155639 1556410 1556511 1556612 1556713 1556814 1556915 1557016 1557117 1557218 1557319 1557420 1557521 1557622 1557723 1557824 1557925 1558026 1558127 15582 15583Meaning 15584... 15585 15586TPM_RC 15587TPM2_EC_Ephemeral( 15588EC_Ephemeral_In 15589EC_Ephemeral_Out 15590 15591*in, 15592*out 15593 15594// IN: input parameter list 15595// OUT: output parameter list 15596 15597) 15598{ 15599TPM2B_ECC_PARAMETER 15600 15601r; 15602 15603// Get the random value that will be used in the point multiplications 15604// Note: this does not commit the count. 15605if(!CryptGenerateR(&r, 15606NULL, 15607in->curveID, 15608NULL)) 15609return TPM_RC_NO_RESULT; 15610CryptEccPointMultiply(&out->Q.t.point, in->curveID, &r, NULL); 15611// commit the count value 15612out->counter = CryptCommit(); 15613return TPM_RC_SUCCESS; 15614} 15615#endif 15616 15617Page 186 15618October 31, 2013 15619 15620Published 15621Copyright © TCG 2006-2013 15622 15623Family “2.0” 15624Level 00 Revision 00.99 15625 15626 Trusted Platform Module Library 15627 1562822 15629 15630Part 3: Commands 15631 15632Signing and Signature Verification 15633 1563422.1 15635 15636TPM2_VerifySignature 15637 1563822.1.1 General Description 15639This command uses loaded keys to validate a signature on a message with the message digest passed 15640to the TPM. 15641If the signature check succeeds, then the TPM will produce a TPMT_TK_VERIFIED. Otherwise, the TPM 15642shall return TPM_RC_SIGNATURE. 15643NOTE 1 15644 15645A valid ticket may be used in subsequent commands to provide proof to the TPM that the TPM has 15646validated the signature over the message using the key referenced by keyHandle. 15647 15648If keyHandle references an asymmetric key, only the public portion of the key needs to be loaded. If 15649keyHandle references a symmetric key, both the public and private portions need to be loaded. 15650NOTE 2 15651 15652The sensitive area of the symmetric object is required to allow verification of the symmetric 15653signature (the HMAC). 15654 15655Family “2.0” 15656Level 00 Revision 00.99 15657 15658Published 15659Copyright © TCG 2006-2013 15660 15661Page 187 15662October 31, 2013 15663 15664 Part 3: Commands 15665 15666Trusted Platform Module Library 15667 1566822.1.2 Command and Response 15669Table 93 — TPM2_VerifySignature Command 15670Type 15671 15672Name 15673 15674Description 15675 15676TPMI_ST_COMMAND_TAG 15677 15678tag 15679 15680UINT32 15681 15682commandSize 15683 15684TPM_CC 15685 15686commandCode 15687 15688TPM_CC_VerifySignature 15689 15690TPMI_DH_OBJECT 15691 15692keyHandle 15693 15694handle of public key that will be used in the validation 15695Auth Index: None 15696 15697TPM2B_DIGEST 15698 15699digest 15700 15701digest of the signed message 15702 15703TPMT_SIGNATURE 15704 15705signature 15706 15707signature to be tested 15708 15709Table 94 — TPM2_VerifySignature Response 15710Type 15711 15712Name 15713 15714Description 15715 15716TPM_ST 15717 15718tag 15719 15720see clause 8 15721 15722UINT32 15723 15724responseSize 15725 15726TPM_RC 15727 15728responseCode 15729 15730TPMT_TK_VERIFIED 15731 15732validation 15733 15734Page 188 15735October 31, 2013 15736 15737Published 15738Copyright © TCG 2006-2013 15739 15740Family “2.0” 15741Level 00 Revision 00.99 15742 15743 Trusted Platform Module Library 15744 15745Part 3: Commands 15746 1574722.1.3 Detailed Actions 157481 157492 15750 15751#include "InternalRoutines.h" 15752#include "VerifySignature_fp.h" 15753Error Returns 15754TPM_RC_ATTRIBUTES 15755 15756keyHandle does not reference a signing key 15757 15758TPM_RC_SIGNATURE 15759 15760signature is not genuine 15761 15762TPM_RC_SCHEME 15763 15764CryptVerifySignature() 15765 15766TPM_RC_HANDLE 157673 157684 157695 157706 157717 157728 157739 1577410 1577511 1577612 1577713 1577814 1577915 1578016 1578117 1578218 1578319 1578420 1578521 1578622 1578723 1578824 1578925 1579026 1579127 1579228 1579329 1579430 1579531 1579632 1579733 1579834 1579935 1580036 1580137 1580238 1580339 1580440 1580541 1580642 1580743 1580844 1580945 1581046 1581147 1581248 1581349 15814 15815Meaning 15816 15817the input handle is not a sign key with private portion loaded 15818 15819TPM_RC 15820TPM2_VerifySignature( 15821VerifySignature_In 15822VerifySignature_Out 15823 15824*in, 15825*out 15826 15827// IN: input parameter list 15828// OUT: output parameter list 15829 15830TPM_RC 15831TPM2B_NAME 15832OBJECT 15833TPMI_RH_HIERARCHY 15834 15835result; 15836name; 15837*signObject; 15838hierarchy; 15839 15840) 15841{ 15842 15843// Input Validation 15844// Get sign object pointer 15845signObject = ObjectGet(in->keyHandle); 15846// The object to validate the signature must be a signing key. 15847if(signObject->publicArea.objectAttributes.sign != SET) 15848return TPM_RC_ATTRIBUTES + RC_VerifySignature_keyHandle; 15849// If it doesn't have a sensitive area loaded 15850// then it can't be a keyed hash signing key 15851if( 15852signObject->attributes.publicOnly == SET 15853&& signObject->publicArea.type == TPM_ALG_KEYEDHASH 15854) 15855return TPM_RC_HANDLE + RC_VerifySignature_keyHandle; 15856// Validate Signature. A TPM_RC_BINDING, TPM_RC_SCHEME or TPM_RC_SIGNATURE 15857// error may be returned by CryptCVerifySignatrue() 15858result = CryptVerifySignature(in->keyHandle, &in->digest, &in->signature); 15859if(result != TPM_RC_SUCCESS) 15860return RcSafeAddToResult(result, RC_VerifySignature_signature); 15861// Command Output 15862hierarchy = ObjectGetHierarchy(in->keyHandle); 15863if( 15864hierarchy == TPM_RH_NULL 15865|| signObject->publicArea.nameAlg == TPM_ALG_NULL) 15866{ 15867// produce empty ticket if hierarchy is TPM_RH_NULL or nameAlg is 15868// TPM_ALG_NULL 15869out->validation.tag = TPM_ST_VERIFIED; 15870out->validation.hierarchy = TPM_RH_NULL; 15871out->validation.digest.t.size = 0; 15872} 15873else 15874{ 15875 15876Family “2.0” 15877Level 00 Revision 00.99 15878 15879Published 15880Copyright © TCG 2006-2013 15881 15882Page 189 15883October 31, 2013 15884 15885 Part 3: Commands 1588650 1588751 1588852 1588953 1589054 1589155 1589256 1589357 15894 15895Trusted Platform Module Library 15896 15897// Get object name that verifies the signature 15898name.t.size = ObjectGetName(in->keyHandle, &name.t.name); 15899// Compute ticket 15900TicketComputeVerified(hierarchy, &in->digest, &name, &out->validation); 15901} 15902return TPM_RC_SUCCESS; 15903} 15904 15905Page 190 15906October 31, 2013 15907 15908Published 15909Copyright © TCG 2006-2013 15910 15911Family “2.0” 15912Level 00 Revision 00.99 15913 15914 Trusted Platform Module Library 15915 1591622.2 15917 15918Part 3: Commands 15919 15920TPM2_Sign 15921 1592222.2.1 General Description 15923This command causes the TPM to sign an externally provided hash with the specified asymmetric signing 15924key. 15925NOTE 1 15926 15927Symmetric “signing” is done with an HMAC. 15928 15929If keyHandle references a restricted signing key, then validation shall be provided indicating that the TPM 15930performed the hash of the data and validation shall indicate that hashed data did not start with 15931TPM_GENERATED_VALUE. 15932NOTE 2 15933 15934If the hashed data did start with TPM_GENERATED_VALUE, then the validation will be a NULL 15935ticket. 15936 15937If the scheme of keyHandle is not TPM_ALG_NULL, then inScheme shall either be the same scheme as 15938keyHandle or TPM_ALG_NULL. 15939If the scheme of keyHandle is TPM_ALG_NULL, the TPM will sign using inScheme; otherwise, it will sign 15940using the scheme of keyHandle. 15941NOTE 3 15942 15943When the signing scheme requires a hash algorithm, the hash is defined in the qualifying data of the 15944scheme. 15945 15946If inScheme is not a valid signing scheme for the type of keyHandle (or TPM_ALG_NULL), then the TPM 15947shall return TPM_RC_SCHEME. 15948If the scheme of keyHandle is an anonymous scheme, then inScheme shall have the same scheme 15949algorithm as keyHandle and inScheme will contain a counter value that will be used in the signing 15950process. 15951As long as it is no larger than allowed, the digest parameter is not required to have any specific size but 15952the signature operation may fail if digest is too large for the selected scheme. 15953If the validation parameter is not the Empty Buffer, then it will be checked even if the key referenced by 15954keyHandle is not a restricted signing key. 15955 15956Family “2.0” 15957Level 00 Revision 00.99 15958 15959Published 15960Copyright © TCG 2006-2013 15961 15962Page 191 15963October 31, 2013 15964 15965 Part 3: Commands 15966 15967Trusted Platform Module Library 15968 1596922.2.2 Command and Response 15970Table 95 — TPM2_Sign Command 15971Type 15972 15973Name 15974 15975TPMI_ST_COMMAND_TAG 15976 15977tag 15978 15979UINT32 15980 15981commandSize 15982 15983TPM_CC 15984 15985commandCode 15986 15987TPM_CC_Sign 15988 15989TPMI_DH_OBJECT 15990 15991@keyHandle 15992 15993Handle of key that will perform signing 15994Auth Index: 1 15995Auth Role: USER 15996 15997TPM2B_DIGEST 15998 15999digest 16000 16001digest to be signed 16002 16003TPMT_SIG_SCHEME+ 16004 16005inScheme 16006 16007signing scheme to use if the scheme for keyHandle is 16008TPM_ALG_NULL 16009 16010TPMT_TK_HASHCHECK 16011 16012validation 16013 16014proof that digest was created by the TPM 16015If keyHandle is not a restricted signing key, then this 16016may be a NULL Ticket with tag = 16017TPM_ST_CHECKHASH. 16018 16019Description 16020 16021Table 96 — TPM2_Sign Response 16022Type 16023 16024Name 16025 16026Description 16027 16028TPM_ST 16029 16030tag 16031 16032see clause 8 16033 16034UINT32 16035 16036responseSize 16037 16038TPM_RC 16039 16040responseCode 16041 16042TPMT_SIGNATURE 16043 16044signature 16045 16046Page 192 16047October 31, 2013 16048 16049the signature 16050 16051Published 16052Copyright © TCG 2006-2013 16053 16054Family “2.0” 16055Level 00 Revision 00.99 16056 16057 Trusted Platform Module Library 16058 16059Part 3: Commands 16060 1606122.2.3 Detailed Actions 160621 160632 160643 16065 16066#include "InternalRoutines.h" 16067#include "Sign_fp.h" 16068#include "Attest_spt_fp.h" 16069Error Returns 16070TPM_RC_ATTRIBUTES 16071 16072key referenced by keHandle is not a signing key 16073 16074TPM_RC_BINDING 16075 16076The public and private portions of the key are not properly bound. 16077 16078TPM_RC_SCHEME 16079 16080inScheme is not compatible with keyHandle; both inScheme and 16081key's default scheme are empty; or inScheme is empty while key's 16082default scheme requires explicit input scheme (split signing); or nonempty default key scheme differs from inScheme 16083 16084TPM_RC_TICKET 16085 16086validation is not a valid ticket 16087 16088TPM_RC_VALUE 160894 160905 160916 160927 160938 160949 1609510 1609611 1609712 1609813 1609914 1610015 1610116 1610217 1610318 1610419 1610520 1610621 1610722 1610823 1610924 1611025 1611126 1611227 1611328 1611429 1611530 1611631 1611732 1611833 1611934 1612035 1612136 1612237 1612338 1612439 1612540 1612641 1612742 1612843 1612944 16130 16131Meaning 16132 16133the value to sign is larger than allowed for the type of keyHandle 16134 16135TPM_RC 16136TPM2_Sign( 16137Sign_In 16138Sign_Out 16139 16140*in, 16141*out 16142 16143// IN: input parameter list 16144// OUT: output parameter list 16145 16146TPM_RC 16147TPMT_TK_HASHCHECK 16148OBJECT 16149 16150result; 16151ticket; 16152*signKey; 16153 16154) 16155{ 16156 16157// Input Validation 16158// Get sign key pointer 16159signKey = ObjectGet(in->keyHandle); 16160// If validation is provided, or the key is restricted, check the ticket 16161if( 16162in->validation.digest.t.size != 0 16163|| signKey->publicArea.objectAttributes.restricted == SET) 16164{ 16165// Compute and compare ticket 16166TicketComputeHashCheck(in->validation.hierarchy, &in->digest, &ticket); 16167if(!Memory2BEqual(&in->validation.digest.b, &ticket.digest.b)) 16168return TPM_RC_TICKET + RC_Sign_validation; 16169} 16170// Command Output 16171// pick a scheme for sign. If the input sign scheme is not compatible with 16172// the default scheme, return an error. 16173result = CryptSelectSignScheme(in->keyHandle, &in->inScheme); 16174if(result != TPM_RC_SUCCESS) 16175{ 16176if(result == TPM_RC_KEY) 16177return TPM_RC_KEY + RC_Sign_keyHandle; 16178else 16179return RcSafeAddToResult(result, RC_Sign_inScheme); 16180} 16181// Sign the hash. A TPM_RC_VALUE, TPM_RC_SCHEME, or TPM_RC_ATTRIBUTES 16182// error may be returned at this point 16183result = CryptSign(in->keyHandle, &in->inScheme, &in->digest, &out->signature); 16184 16185Family “2.0” 16186Level 00 Revision 00.99 16187 16188Published 16189Copyright © TCG 2006-2013 16190 16191Page 193 16192October 31, 2013 16193 16194 Part 3: Commands 1619545 1619646 1619747 16198 16199Trusted Platform Module Library 16200 16201return result; 16202} 16203 16204Page 194 16205October 31, 2013 16206 16207Published 16208Copyright © TCG 2006-2013 16209 16210Family “2.0” 16211Level 00 Revision 00.99 16212 16213 Trusted Platform Module Library 16214 1621523 16216 16217Part 3: Commands 16218 16219Command Audit 16220 1622123.1 16222 16223Introduction 16224 16225If a command has been selected for command audit, the command audit status will be updated when that 16226command completes successfully. The digest is updated as: 16227 16228commandAuditDigestnew ≔ HauditAlg(commandAuditDigestold || cpHash || rpHash) 16229 16230(5) 16231 16232where 16233 16234HauditAlg 16235 16236hash function using the algorithm of the audit sequence 16237 16238commandAuditDigest 16239 16240accumulated digest 16241 16242cpHash 16243 16244the command parameter hash 16245 16246rpHash 16247 16248the response parameter hash 16249 16250TPM2_Shutdown() cannot be audited but TPM2_Startup() can be audited. If the cpHash of the 16251TPM2_Startup() is TPM_SU_STATE, that would indicate that a TPM2_Shutdown() had been successfully 16252executed. 16253TPM2_SetCommandCodeAuditStatus() is always audited. 16254If the TPM is in Failure mode, command audit is not functional. 16255 16256Family “2.0” 16257Level 00 Revision 00.99 16258 16259Published 16260Copyright © TCG 2006-2013 16261 16262Page 195 16263October 31, 2013 16264 16265 Part 3: Commands 16266 1626723.2 16268 16269Trusted Platform Module Library 16270 16271TPM2_SetCommandCodeAuditStatus 16272 1627323.2.1 General Description 16274This command may be used by the Privacy Administrator or platform to change the audit status of a 16275command or to set the hash algorithm used for the audit digest, but not both at the same time. 16276If the auditAlg parameter is a supported hash algorithm and not the same as the current algorithm, then 16277the TPM will check both setList and clearList are empty (zero length). If so, then the algorithm is changed, 16278and the audit digest is cleared. If auditAlg is TPM_ALG_NULL or the same as the current algorithm, then 16279the algorithm and audit digest are unchanged and the setList and clearList will be processed. 16280NOTE 1 16281 16282Because the audit digest is cleared, the audit counter will increment the next time that an audited 16283command is executed. 16284 16285Use of TPM2_SetCommandCodeAuditStatus() to change the list of audited commands is an audited 16286event. If TPM_CC_SetCommandCodeAuditStatus is in clearList, it is ignored. 16287NOTE 2 16288 16289Use of this command to change the audit hash algorithm is not audited and the digest is reset when 16290the command completes. The change in the audit hash algorithm is the evidence that this command 16291was used to change the algorithm. 16292 16293The commands in setList indicate the commands that to be added to the list of audited commands and 16294the commands in clearList indicate the commands that will no longer be audited. It is not an error if a 16295command in setList is already audited or is not implemented. It is not an error if a command in clearList is 16296not currently being audited or is not implemented. 16297If a command code is in both setList and clearList, then it will not be audited (that is, setList shall be 16298processed first). 16299 16300Page 196 16301October 31, 2013 16302 16303Published 16304Copyright © TCG 2006-2013 16305 16306Family “2.0” 16307Level 00 Revision 00.99 16308 16309 Trusted Platform Module Library 16310 16311Part 3: Commands 16312 1631323.2.2 Command and Response 16314Table 97 — TPM2_SetCommandCodeAuditStatus Command 16315Type 16316 16317Name 16318 16319Description 16320 16321TPMI_ST_COMMAND_TAG 16322 16323tag 16324 16325UINT32 16326 16327commandSize 16328 16329TPM_CC 16330 16331commandCode 16332 16333TPM_CC_SetCommandCodeAuditStatus {NV} 16334 16335TPMI_RH_PROVISION 16336 16337@auth 16338 16339TPM_RH_ENDORSEMENT or 16340TPM_RH_PLATFORM+{PP} 16341Auth Index: 1 16342Auth Role: USER 16343 16344TPMI_ALG_HASH+ 16345 16346auditAlg 16347 16348hash algorithm for the audit digest; if 16349TPM_ALG_NULL, then the hash is not changed 16350 16351TPML_CC 16352 16353setList 16354 16355list of commands that will be added to those that will 16356be audited 16357 16358TPML_CC 16359 16360clearList 16361 16362list of commands that will no longer be audited 16363 16364Table 98 — TPM2_SetCommandCodeAuditStatus Response 16365Type 16366 16367Name 16368 16369Description 16370 16371TPM_ST 16372 16373tag 16374 16375see clause 8 16376 16377UINT32 16378 16379responseSize 16380 16381TPM_RC 16382 16383responseCode 16384 16385Family “2.0” 16386Level 00 Revision 00.99 16387 16388Published 16389Copyright © TCG 2006-2013 16390 16391Page 197 16392October 31, 2013 16393 16394 Part 3: Commands 16395 16396Trusted Platform Module Library 16397 1639823.2.3 Detailed Actions 163991 164002 164013 164024 164035 164046 164057 164068 164079 1640810 1640911 1641012 1641113 1641214 1641315 1641416 1641517 1641618 1641719 1641820 1641921 1642022 1642123 1642224 1642325 1642426 1642527 1642628 1642729 1642830 1642931 1643032 1643133 1643234 1643335 1643436 1643537 1643638 1643739 1643840 1643941 1644042 1644143 1644244 1644345 1644446 1644547 1644648 1644749 1644850 1644951 1645052 1645153 1645254 1645355 1645456 1645557 1645658 1645759 1645860 16459 16460#include "InternalRoutines.h" 16461#include "SetCommandCodeAuditStatus_fp.h" 16462 16463TPM_RC 16464TPM2_SetCommandCodeAuditStatus( 16465SetCommandCodeAuditStatus_In 16466 16467*in 16468 16469// IN: input parameter list 16470 16471) 16472{ 16473TPM_RC 16474UINT32 16475BOOL 16476 16477result; 16478i; 16479changed = FALSE; 16480 16481// The command needs NV update. Check if NV is available. 16482// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 16483// this point 16484result = NvIsAvailable(); 16485if(result != TPM_RC_SUCCESS) 16486return result; 16487// Internal Data Update 16488// Update hash algorithm 16489if( 16490in->auditAlg != TPM_ALG_NULL 16491&& in->auditAlg != gp.auditHashAlg) 16492{ 16493// Can't change the algorithm and command list at the same time 16494if(in->setList.count != 0 || in->clearList.count != 0) 16495return TPM_RC_VALUE + RC_SetCommandCodeAuditStatus_auditAlg; 16496// Change the hash algorithm for audit 16497gp.auditHashAlg = in->auditAlg; 16498// Set the digest size to a unique value that indicates that the digest 16499// algorithm has been changed. The size will be cleared to zero in the 16500// command audit processing on exit. 16501gr.commandAuditDigest.t.size = 1; 16502// Save the change of command audit data (this sets g_updateNV so that NV 16503// will be updagted on exit.) 16504NvWriteReserved(NV_AUDIT_HASH_ALG, &gp.auditHashAlg); 16505} else { 16506// Process set list 16507for(i = 0; i < in->setList.count; i++) 16508// If change is made in CommandAuditSet, set changed flag 16509if(CommandAuditSet(in->setList.commandCodes[i])) 16510changed = TRUE; 16511// Process clear list 16512for(i = 0; i < in->clearList.count; i++) 16513// If change is made in CommandAuditClear, set changed flag 16514if(CommandAuditClear(in->clearList.commandCodes[i])) 16515changed = TRUE; 16516// if change was made to command list, update NV 16517if(changed) 16518// this sets g_updateNV so that NV will be updagted on exit. 16519NvWriteReserved(NV_AUDIT_COMMANDS, &gp.auditComands); 16520 16521Page 198 16522October 31, 2013 16523 16524Published 16525Copyright © TCG 2006-2013 16526 16527Family “2.0” 16528Level 00 Revision 00.99 16529 16530 Trusted Platform Module Library 1653161 1653262 1653363 1653464 16535 16536Part 3: Commands 16537 16538} 16539return TPM_RC_SUCCESS; 16540} 16541 16542Family “2.0” 16543Level 00 Revision 00.99 16544 16545Published 16546Copyright © TCG 2006-2013 16547 16548Page 199 16549October 31, 2013 16550 16551 Part 3: Commands 16552 1655324 16554 16555Trusted Platform Module Library 16556 16557Integrity Collection (PCR) 16558 1655924.1 16560 16561Introduction 16562 16563In TPM 1.2, an Event was hashed using SHA-1 and then the 20-octet digest was extended to a PCR 16564using TPM_Extend(). This specification allows the use of multiple PCR at a given Index, each using a 16565different hash algorithm. Rather than require that the external software generate multiple hashes of the 16566Event with each being extended to a different PCR, the Event data may be sent to the TPM for hashing. 16567This ensures that the resulting digests will properly reflect the algorithms chosen for the PCR even if the 16568calling software is unable to implement the hash algorithm. 16569NOTE 1 16570 16571There is continued support for software hashing of events with TPM2_PCR_Extend(). 16572 16573To support recording of an Event that is larger than the TPM input buffer, the caller may use the 16574command sequence described in clause 1. 16575Change to a PCR requires authorization. The authorization may be with either an authorization value or 16576an authorization policy. The platform-specific specifications determine which PCR may be controlled by 16577policy. All other PCR are controlled by authorization. 16578If a PCR may be associated with a policy, then the algorithm ID of that policy determines whether the 16579policy is to be applied. If the algorithm ID is not TPM_ALG_NULL, then the policy digest associated with 16580the PCR must match the policySession→policyDigest in a policy session. If the algorithm ID is 16581TPM_ALG_NULL, then no policy is present and the authorization requires an EmptyAuth. 16582If a platform-specific specification indicates that PCR are grouped, then all the PCR in the group use the 16583same authorization policy or authorization value. 16584PcrUpdateCounter counter will be incremented on the successful completion of any command that 16585modifies (Extends or resets) a PCR unless the platform-specific specification explicitly excludes the PCR 16586from being counted. 16587NOTE 2 16588 16589If a command causes PCR in multiple banks to change, the PCR Update Counter may be 16590incremented either once or once for each bank. 16591 16592A platform-specific specification may designate a set of PCR that are under control of the TCB. These 16593PCR may not be modified without the proper authorization. Updates of these PCR shall not cause the 16594PCR Update Counter to increment. 16595EXAMPLE 16596 16597Updates of the TCB PCR will not cause the PCR update counter to increment b ecause these PCR 16598are changed at the whim of the TCB and are not intended to represent the trust state of the platform. 16599 16600Page 200 16601October 31, 2013 16602 16603Published 16604Copyright © TCG 2006-2013 16605 16606Family “2.0” 16607Level 00 Revision 00.99 16608 16609 Trusted Platform Module Library 16610 1661124.2 16612 16613Part 3: Commands 16614 16615TPM2_PCR_Extend 16616 1661724.2.1 General Description 16618This command is used to cause an update to the indicated PCR. The digests parameter contains one or 16619more tagged digest value identified by an algorithm ID. For each digest, the PCR associated with 16620pcrHandle is Extended into the bank identified by the tag (hashAlg). 16621EXAMPLE 16622 16623A SHA1 digest would be Extended into the SHA1 bank and a SHA256 digest would be Extended into 16624a SHA256 bank. 16625 16626For each list entry, the TPM will check to see if pcrNum is implemented for that algorithm. If so, the TPM 16627shall perform the following operation: 16628 16629PCR.digestnew [pcrNum][alg] ≔ Halg(PCR.digestold [pcrNum][alg] || data[alg].buffer)) 16630 16631(6) 16632 16633where 16634 16635Halg() 16636 16637hash function using the hash algorithm associated with the PCR 16638instance 16639 16640PCR.digest 16641 16642the digest value in a PCR 16643 16644pcrNum 16645 16646the PCR numeric 16647TPM_RH_PCR0) 16648 16649alg 16650 16651the PCR algorithm selector for the digest 16652 16653data[alg].buffer 16654 16655the bank-specific data to be extended 16656 16657selector 16658 16659(equal 16660 16661to 16662 16663pcrHandle 16664 16665– 16666 16667If no digest value is specified for a bank, then the PCR in that bank are not modified. 16668NOTE 1 16669 16670This allows consistent operation of the digests list for all of the Event recording commands. 16671 16672If a digest is present and the PCR in that bank is not implemented, the digest value is not used. 16673NOTE 2 16674 16675If the caller includes digests for algorithms that are not implemented, then the TPM will fail the call 16676because the unmarshalling of digests will fail. Each of the entries in the list is a TPMT_HA which is a 16677hash algorithm followed by a digest. If the algorithm is not implemented, unmarshalling of the 16678hashAlg will fail and the TPM will return TPM_RC_HASH. 16679 16680If the TPM unmarshals the hashAlg of a list entry and the unmarshaled value is not a hash algorithm 16681implemented on the TPM, the TPM shall return TPM_RC_HASH. 16682The pcrHandle parameter is allowed to reference TPM_RH_NULL. If so, the input parameters are 16683processed but no action is taken by the TPM. 16684NOTE 3 16685 16686This command allows a list of digests so that PCR in all banks may be updated in a single 16687command. While the semantics of this command allow multiple extends to a single PCR bank, this is 16688not the preferred use and the limit on the number of entries in the list make this use somewhat 16689impractical. 16690 16691Family “2.0” 16692Level 00 Revision 00.99 16693 16694Published 16695Copyright © TCG 2006-2013 16696 16697Page 201 16698October 31, 2013 16699 16700 Part 3: Commands 16701 16702Trusted Platform Module Library 16703 1670424.2.2 Command and Response 16705Table 99 — TPM2_PCR_Extend Command 16706Type 16707 16708Name 16709 16710Description 16711 16712TPMI_ST_COMMAND_TAG 16713 16714tag 16715 16716UINT32 16717 16718commandSize 16719 16720TPM_CC 16721 16722commandCode 16723 16724TPM_CC_PCR_Extend {NV} 16725 16726TPMI_DH_PCR+ 16727 16728@pcrHandle 16729 16730handle of the PCR 16731Auth Handle: 1 16732Auth Role: USER 16733 16734TPML_DIGEST_VALUES 16735 16736digests 16737 16738list of tagged digest values to be extended 16739 16740Table 100 — TPM2_PCR_Extend Response 16741Type 16742 16743Name 16744 16745Description 16746 16747TPM_ST 16748 16749tag 16750 16751see clause 8 16752 16753UINT32 16754 16755responseSize 16756 16757TPM_RC 16758 16759responseCode 16760 16761Page 202 16762October 31, 2013 16763 16764. 16765 16766Published 16767Copyright © TCG 2006-2013 16768 16769Family “2.0” 16770Level 00 Revision 00.99 16771 16772 Trusted Platform Module Library 16773 16774Part 3: Commands 16775 1677624.2.3 Detailed Actions 167771 167782 16779 16780#include "InternalRoutines.h" 16781#include "PCR_Extend_fp.h" 16782Error Returns 16783TPM_RC_LOCALITY 16784 167853 167864 167875 167886 167897 167908 167919 1679210 1679311 1679412 1679513 1679614 1679715 1679816 1679917 1680018 1680119 1680220 1680321 1680422 1680523 1680624 1680725 1680826 1680927 1681028 1681129 1681230 1681331 1681432 1681533 1681634 1681735 1681836 1681937 1682038 1682139 1682240 1682341 1682442 1682543 1682644 1682745 1682846 1682947 1683048 1683149 16832 16833Meaning 16834current command locality is not allowed to extend the PCR 16835referenced by pcrHandle 16836 16837TPM_RC 16838TPM2_PCR_Extend( 16839PCR_Extend_In 16840 16841*in 16842 16843// IN: input parameter list 16844 16845) 16846{ 16847TPM_RC 16848UINT32 16849 16850result; 16851i; 16852 16853// Input Validation 16854// 16855// 16856// 16857// 16858// 16859// 16860// 16861 16862NOTE: This function assumes that the unmarshaling function for 'digests' will 16863have validated that all of the indicated hash algorithms are valid. If the 16864hash algorithms are correct, the unmarshaling code will unmarshal a digest 16865of the size indicated by the hash algorithm. If the overall size is not 16866consistent, the unmarshaling code will run out of input data or have input 16867data left over. In either case, it will cause an unmarshaling error and this 16868function will not be called. 16869 16870// For NULL handle, do nothing and return success 16871if(in->pcrHandle == TPM_RH_NULL) 16872return TPM_RC_SUCCESS; 16873// Check if the extend operation is allowed by the current command locality 16874if(!PCRIsExtendAllowed(in->pcrHandle)) 16875return TPM_RC_LOCALITY; 16876// If PCR is state saved and we need to update orderlyState, check NV 16877// availability 16878if(PCRIsStateSaved(in->pcrHandle) && gp.orderlyState != SHUTDOWN_NONE) 16879{ 16880result = NvIsAvailable(); 16881if(result != TPM_RC_SUCCESS) return result; 16882g_clearOrderly = TRUE; 16883} 16884// Internal Data Update 16885// Iterate input digest list to extend 16886for(i = 0; i < in->digests.count; i++) 16887{ 16888PCRExtend(in->pcrHandle, in->digests.digests[i].hashAlg, 16889CryptGetHashDigestSize(in->digests.digests[i].hashAlg), 16890(BYTE *) &in->digests.digests[i].digest); 16891} 16892return TPM_RC_SUCCESS; 16893} 16894 16895Family “2.0” 16896Level 00 Revision 00.99 16897 16898Published 16899Copyright © TCG 2006-2013 16900 16901Page 203 16902October 31, 2013 16903 16904 Part 3: Commands 16905 1690624.3 16907 16908Trusted Platform Module Library 16909 16910TPM2_PCR_Event 16911 1691224.3.1 General Description 16913This command is used to cause an update to the indicated PCR. 16914The data in eventData is hashed using the hash algorithm associated with each bank in which the 16915indicated PCR has been allocated. After the data is hashed, the digests list is returned. If the pcrHandle 16916references an implemented PCR and not TPM_ALG_NULL, digests list is processed as in 16917TPM2_PCR_Extend(). 16918A TPM shall support an Event.size of zero through 1,024 inclusive (Event.size is an octet count). An 16919Event.size of zero indicates that there is no data but the indicated operations will still occur, 16920EXAMPLE 1 16921 16922If the command implements PCR[2] in a SHA1 bank and a SHA256 bank, then an extend to PCR[2] 16923will cause eventData to be hashed twice, once with SHA1 and once with SHA256. The SHA1 hash of 16924eventData will be Extended to PCR[2] in the SHA1 bank and the SHA256 hash of eventData will be 16925Extended to PCR[2] of the SHA256 bank. 16926 16927On successful command completion, digests will contain the list of tagged digests of eventData that was 16928computed in preparation for extending the data into the PCR. At the option of the TPM, the list may 16929contain a digest for each bank, or it may only contain a digest for each bank in which pcrHandle is extant. 16930EXAMPLE 2 16931 16932Assume a TPM that implements a SHA1 bank and a SHA256 bank and that PCR[22] is only 16933implemented in the SHA1 bank. If pcrHandle references PCR[22], then digests may contain either a 16934SHA1 and a SHA256 digest or just a SHA1 digest. 16935 16936Page 204 16937October 31, 2013 16938 16939Published 16940Copyright © TCG 2006-2013 16941 16942Family “2.0” 16943Level 00 Revision 00.99 16944 16945 Trusted Platform Module Library 16946 16947Part 3: Commands 16948 1694924.3.2 Command and Response 16950Table 101 — TPM2_PCR_Event Command 16951Type 16952 16953Name 16954 16955Description 16956 16957TPMI_ST_COMMAND_TAG 16958 16959tag 16960 16961UINT32 16962 16963commandSize 16964 16965TPM_CC 16966 16967commandCode 16968 16969TPM_CC_PCR_Event {NV} 16970 16971TPMI_DH_PCR+ 16972 16973@pcrHandle 16974 16975Handle of the PCR 16976Auth Handle: 1 16977Auth Role: USER 16978 16979TPM2B_EVENT 16980 16981eventData 16982 16983Event data in sized buffer 16984 16985Table 102 — TPM2_PCR_Event Response 16986Type 16987 16988Name 16989 16990Description 16991 16992TPM_ST 16993 16994tag 16995 16996see clause 8 16997 16998UINT32 16999 17000responseSize 17001 17002TPM_RC 17003 17004responseCode 17005 17006TPML_DIGEST_VALUES 17007 17008digests 17009 17010Family “2.0” 17011Level 00 Revision 00.99 17012 17013. 17014 17015Published 17016Copyright © TCG 2006-2013 17017 17018Page 205 17019October 31, 2013 17020 17021 Part 3: Commands 17022 17023Trusted Platform Module Library 17024 1702524.3.3 Detailed Actions 170261 170272 17028 17029#include "InternalRoutines.h" 17030#include "PCR_Event_fp.h" 17031Error Returns 17032TPM_RC_LOCALITY 17033 170343 170354 170365 170376 170387 170398 170409 1704110 1704211 1704312 1704413 1704514 1704615 1704716 1704817 1704918 1705019 1705120 1705221 1705322 1705423 1705524 1705625 1705726 1705827 1705928 1706029 1706130 1706231 1706332 1706433 1706534 1706635 1706736 1706837 1706938 1707039 1707140 1707241 1707342 1707443 1707544 1707645 1707746 1707847 1707948 1708049 1708150 1708251 1708352 17084 17085Meaning 17086current command locality is not allowed to extend the PCR 17087referenced by pcrHandle 17088 17089TPM_RC 17090TPM2_PCR_Event( 17091PCR_Event_In 17092PCR_Event_Out 17093 17094*in, 17095*out 17096 17097// IN: input parameter list 17098// OUT: output parameter list 17099 17100) 17101{ 17102TPM_RC 17103HASH_STATE 17104UINT32 17105UINT16 17106 17107result; 17108hashState; 17109i; 17110size; 17111 17112// Input Validation 17113// If a PCR extend is required 17114if(in->pcrHandle != TPM_RH_NULL) 17115{ 17116// If the PCR is not allow to extend, return error 17117if(!PCRIsExtendAllowed(in->pcrHandle)) 17118return TPM_RC_LOCALITY; 17119// If PCR is state saved and we need to update orderlyState, check NV 17120// availability 17121if(PCRIsStateSaved(in->pcrHandle) && gp.orderlyState != SHUTDOWN_NONE) 17122{ 17123result = NvIsAvailable(); 17124if(result != TPM_RC_SUCCESS) return result; 17125g_clearOrderly = TRUE; 17126} 17127} 17128// Internal Data Update 17129out->digests.count = HASH_COUNT; 17130// Iterate supported PCR bank algorithms to extend 17131for(i = 0; i < HASH_COUNT; i++) 17132{ 17133TPM_ALG_ID hash = CryptGetHashAlgByIndex(i); 17134out->digests.digests[i].hashAlg = hash; 17135size = CryptStartHash(hash, &hashState); 17136CryptUpdateDigest2B(&hashState, &in->eventData.b); 17137CryptCompleteHash(&hashState, size, 17138(BYTE *) &out->digests.digests[i].digest); 17139if(in->pcrHandle != TPM_RH_NULL) 17140PCRExtend(in->pcrHandle, hash, size, 17141(BYTE *) &out->digests.digests[i].digest); 17142} 17143return TPM_RC_SUCCESS; 17144} 17145 17146Page 206 17147October 31, 2013 17148 17149Published 17150Copyright © TCG 2006-2013 17151 17152Family “2.0” 17153Level 00 Revision 00.99 17154 17155 Trusted Platform Module Library 17156 1715724.4 17158 17159Part 3: Commands 17160 17161TPM2_PCR_Read 17162 1716324.4.1 General Description 17164This command returns the values of all PCR specified in pcrSelect. 17165The TPM will process the list of TPMS_PCR_SELECTION in pcrSelectionIn in order. Within each 17166TPMS_PCR_SELECTION, the TPM will process the bits in the pcrSelect array in ascending PCR order 17167(see Part 2 for definition of the PCR order). If a bit is SET, and the indicated PCR is present, then the 17168TPM will add the digest of the PCR to the list of values to be returned in pcrValue. 17169The TPM will continue processing bits until all have been processed or until pcrValues would be too large 17170to fit into the output buffer if additional values were added. 17171The returned pcrSelectionOut will have a bit SET in its pcrSelect structures for each value present in 17172pcrValues. 17173The current value of the PCR Update Counter is returned in pcrUpdateCounter. 17174The returned list may be empty if none of the selected PCR are implemented. 17175NOTE 17176 17177If no PCR are returned from a bank, the selector for the bank will be present in pcrSelectionOut. 17178 17179No authorization is required to read a PCR and any implemented PCR may be read from any locality. 17180 17181Family “2.0” 17182Level 00 Revision 00.99 17183 17184Published 17185Copyright © TCG 2006-2013 17186 17187Page 207 17188October 31, 2013 17189 17190 Part 3: Commands 17191 17192Trusted Platform Module Library 17193 1719424.4.2 Command and Response 17195Table 103 — TPM2_PCR_Read Command 17196Type 17197 17198Name 17199 17200Description 17201 17202TPMI_ST_COMMAND_TAG 17203 17204tag 17205 17206UINT32 17207 17208commandSize 17209 17210TPM_CC 17211 17212commandCode 17213 17214TPM_CC_PCR_Read 17215 17216TPML_PCR_SELECTION 17217 17218pcrSelectionIn 17219 17220The selection of PCR to read 17221 17222Table 104 — TPM2_PCR_Read Response 17223Type 17224 17225Name 17226 17227Description 17228 17229TPM_ST 17230 17231tag 17232 17233see clause 8 17234 17235UINT32 17236 17237responseSize 17238 17239TPM_RC 17240 17241responseCode 17242 17243UINT32 17244 17245pcrUpdateCounter 17246 17247the current value of the PCR update counter 17248 17249TPML_PCR_SELECTION 17250 17251pcrSelectionOut 17252 17253the PCR in the returned list 17254 17255TPML_DIGEST 17256 17257pcrValues 17258 17259the contents of the PCR indicated in pcrSelect as 17260tagged digests 17261 17262Page 208 17263October 31, 2013 17264 17265Published 17266Copyright © TCG 2006-2013 17267 17268Family “2.0” 17269Level 00 Revision 00.99 17270 17271 Trusted Platform Module Library 17272 17273Part 3: Commands 17274 1727524.4.3 Detailed Actions 172761 172772 172783 172794 172805 172816 172827 172838 172849 1728510 1728611 1728712 1728813 1728914 1729015 1729116 1729217 1729318 17294 17295#include "InternalRoutines.h" 17296#include "PCR_Read_fp.h" 17297 17298TPM_RC 17299TPM2_PCR_Read( 17300PCR_Read_In 17301PCR_Read_Out 17302 17303*in, 17304*out 17305 17306// IN: input parameter list 17307// OUT: output parameter list 17308 17309) 17310{ 17311// Command Output 17312// Call PCR read function. input pcrSelectionIn parameter could be changed 17313// to reflect the actual PCR being returned 17314PCRRead(&in->pcrSelectionIn, &out->pcrValues, &out->pcrUpdateCounter); 17315out->pcrSelectionOut = in->pcrSelectionIn; 17316return TPM_RC_SUCCESS; 17317} 17318 17319Family “2.0” 17320Level 00 Revision 00.99 17321 17322Published 17323Copyright © TCG 2006-2013 17324 17325Page 209 17326October 31, 2013 17327 17328 Part 3: Commands 17329 1733024.5 17331 17332Trusted Platform Module Library 17333 17334TPM2_PCR_Allocate 17335 1733624.5.1 General Description 17337This command is used to set the desired PCR allocation of PCR and algorithms. This command requires 17338platformAuth. 17339The TPM will evaluate the request and, if sufficient memory is available for the requested allocation, the 17340TPM will store the allocation request for use during the next TPM2_Startup(TPM_SU_CLEAR) operation. 17341The PCR allocation in place when this command is executed will be retained until the next 17342TPM2_Startup(TPM_SU_CLEAR). 17343If no allocation is specified for a bank, then no PCR will be allocated to that bank. If a bank is listed more 17344than once, then the last selection in the pcrAllocation list is the one that the TPM will attempt to allocate. 17345This command shall not allocate more PCR in any bank than there are PCR attribute definitions. The 17346PCR attribute definitions indicate how a PCR is to be managed – if it is resettable, the locality for update, 17347etc. In the response to this command, the TPM returns the maximum number of PCR allowed for any 17348bank. 17349If the command is properly authorized, it will return SUCCESS even though the request fails. This is to 17350allow the TPM to return information about the size needed for the requested allocation and the size 17351available. If the sizeNeeded parameter in the return is less than or equal to the sizeAvailable parameter, 17352then the allocationSuccess parameter will be YES. 17353After this command, TPM2_Shutdown() is only allowed to have a startupType equal to TPM_SU_CLEAR. 17354NOTE 17355 17356Even if this command does not cause the PCR allocation to change, the TPM cannot have its state 17357saved. This is done in order to simplify the implementation. There is no need to optimize this 17358command as it is not expected to be used more than once in the lifetime of the TPM (it can be used 17359any number of times but there is no justification for optimization) . 17360 17361Page 210 17362October 31, 2013 17363 17364Published 17365Copyright © TCG 2006-2013 17366 17367Family “2.0” 17368Level 00 Revision 00.99 17369 17370 Trusted Platform Module Library 17371 17372Part 3: Commands 17373 1737424.5.2 Command and Response 17375Table 105 — TPM2_PCR_Allocate Command 17376Type 17377 17378Name 17379 17380Description 17381 17382TPMI_ST_COMMAND_TAG 17383 17384tag 17385 17386UINT32 17387 17388commandSize 17389 17390TPM_CC 17391 17392commandCode 17393 17394TPM_CC_PCR_Allocate {NV} 17395 17396TPMI_RH_PLATFORM 17397 17398@authHandle 17399 17400TPM_RH_PLATFORM+{PP} 17401Auth Index: 1 17402Auth Role: USER 17403 17404TPML_PCR_SELECTION 17405 17406pcrAllocation 17407 17408the requested allocation 17409 17410Table 106 — TPM2_PCR_Allocate Response 17411Type 17412 17413Name 17414 17415Description 17416 17417TPM_ST 17418 17419tag 17420 17421see clause 8 17422 17423UINT32 17424 17425responseSize 17426 17427TPM_RC 17428 17429responseCode 17430 17431TPMI_YES_NO 17432 17433allocationSuccess 17434 17435YES if the allocation succeeded 17436 17437UINT32 17438 17439maxPCR 17440 17441maximum number of PCR that may be in a bank 17442 17443UINT32 17444 17445sizeNeeded 17446 17447number of octets required to satisfy the request 17448 17449UINT32 17450 17451sizeAvailable 17452 17453Number of octets available. Computed before the 17454allocation. 17455 17456Family “2.0” 17457Level 00 Revision 00.99 17458 17459Published 17460Copyright © TCG 2006-2013 17461 17462Page 211 17463October 31, 2013 17464 17465 Part 3: Commands 17466 17467Trusted Platform Module Library 17468 1746924.5.3 Detailed Actions 174701 174712 174723 174734 174745 174756 174767 174778 174789 1747910 1748011 1748112 1748213 1748314 1748415 1748516 1748617 1748718 1748819 1748920 1749021 1749122 1749223 1749324 1749425 1749526 1749627 1749728 1749829 1749930 1750031 1750132 1750233 1750334 17504 17505#include "InternalRoutines.h" 17506#include "PCR_Allocate_fp.h" 17507 17508TPM_RC 17509TPM2_PCR_Allocate( 17510PCR_Allocate_In 17511PCR_Allocate_Out 17512 17513*in, 17514*out 17515 17516// IN: input parameter list 17517// OUT: output parameter list 17518 17519) 17520{ 17521TPM_RC 17522 17523result; 17524 17525// The command needs NV update. Check if NV is available. 17526// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 17527// this point. 17528// Note: These codes are not listed in the return values above because it is 17529// an implementation choice to check in this routine rather than in a common 17530// function that is called before these actions are called. These return values 17531// are described in the Response Code section of Part 3. 17532result = NvIsAvailable(); 17533if(result != TPM_RC_SUCCESS) 17534return result; 17535// Command Output 17536// Call PCR Allocation function. 17537out->allocationSuccess = PCRAllocate(&in->pcrAllocation, &out->maxPCR, 17538&out->sizeNeeded, &out->sizeAvailable); 17539// if re-configuration succeeds, set the flag to indicate PCR configuration is 17540// going to be changed in next boot 17541if(out->allocationSuccess == YES) 17542g_pcrReConfig = TRUE; 17543return TPM_RC_SUCCESS; 17544} 17545 17546Page 212 17547October 31, 2013 17548 17549Published 17550Copyright © TCG 2006-2013 17551 17552Family “2.0” 17553Level 00 Revision 00.99 17554 17555 Trusted Platform Module Library 17556 1755724.6 17558 17559Part 3: Commands 17560 17561TPM2_PCR_SetAuthPolicy 17562 1756324.6.1 General Description 17564This command is used to associate a policy with a PCR or group of PCR. The policy determines the 17565conditions under which a PCR may be extended or reset. 17566A policy may only be associated with a PCR that has been defined by a platform-specific specification as 17567allowing a policy. If the TPM implementation does not allow a policy for pcrNum, the TPM shall return 17568TPM_RC_VALUE. 17569A platform-specific specification may group PCR so that they share a common policy. In such case, a 17570pcrNum that selects any of the PCR in the group will change the policy for all PCR in the group. 17571The policy setting is persistent and may only be changed by TPM2_PCR_SetAuthPolicy() or by 17572TPM2_ChangePPS(). 17573Before this command is first executed on a TPM or after TPM2_ChangePPS(), the access control on the 17574PCR will be set to the default value defined in the platform-specific specification. 17575NOTE 1 17576 17577It is expected that the typical default will be with the policy hash set to TPM_ALG_NULL and an 17578Empty Buffer for the authPolicy value. This will allow an EmptyAuth to be used as the authorization 17579value. 17580 17581If the size of the data buffer in authPolicy is not the size of a digest produced by hashAlg, the TPM shall 17582return TPM_RC_SIZE. 17583NOTE 2 17584 17585If hashAlg is TPM_ALG_NULL, then the size is required to be zero. 17586 17587This command requires platformAuth/platformPolicy. 17588NOTE 3 17589 17590If the PCR is in multiple policy sets, the policy will be changed in only one set. The set that is 17591changed will be implementation dependent. 17592 17593Family “2.0” 17594Level 00 Revision 00.99 17595 17596Published 17597Copyright © TCG 2006-2013 17598 17599Page 213 17600October 31, 2013 17601 17602 Part 3: Commands 17603 17604Trusted Platform Module Library 17605 1760624.6.2 Command and Response 17607Table 107 — TPM2_PCR_SetAuthPolicy Command 17608Type 17609 17610Name 17611 17612Description 17613 17614TPMI_ST_COMMAND_TAG 17615 17616tag 17617 17618UINT32 17619 17620commandSize 17621 17622TPM_CC 17623 17624commandCode 17625 17626TPM_CC_PCR_SetAuthPolicy {NV} 17627 17628TPMI_RH_PLATFORM 17629 17630@authHandle 17631 17632TPM_RH_PLATFORM+{PP} 17633Auth Index: 1 17634Auth Role: USER 17635 17636TPM2B_DIGEST 17637 17638authPolicy 17639 17640the desired authPolicy 17641 17642TPMI_ALG_HASH+ 17643 17644policyDigest 17645 17646the digest of the policy 17647 17648TPMI_DH_PCR 17649 17650pcrNum 17651 17652the PCR for which the policy is to be set 17653 17654Table 108 — TPM2_PCR_SetAuthPolicy Response 17655Type 17656 17657Name 17658 17659Description 17660 17661TPM_ST 17662 17663tag 17664 17665see clause 8 17666 17667UINT32 17668 17669responseSize 17670 17671TPM_RC 17672 17673responseCode 17674 17675Page 214 17676October 31, 2013 17677 17678Published 17679Copyright © TCG 2006-2013 17680 17681Family “2.0” 17682Level 00 Revision 00.99 17683 17684 Trusted Platform Module Library 17685 17686Part 3: Commands 17687 1768824.6.3 Detailed Actions 176891 176902 17691 17692#include "InternalRoutines.h" 17693#include "PCR_SetAuthPolicy_fp.h" 17694Error Returns 17695TPM_RC_SIZE 17696 17697size of authPolicy is not the size of a digest produced by policyDigest 17698 17699TPM_RC_VALUE 177003 177014 177025 177036 177047 177058 177069 1770710 1770811 1770912 1771013 1771114 1771215 1771316 1771417 1771518 1771619 1771720 1771821 1771922 1772023 1772124 1772225 1772326 1772427 1772528 1772629 1772730 1772831 1772932 1773033 1773134 1773235 1773336 1773437 1773538 17736 17737Meaning 17738 17739PCR referenced by pcrNum is not a member of a PCR policy group 17740 17741TPM_RC 17742TPM2_PCR_SetAuthPolicy( 17743PCR_SetAuthPolicy_In 17744 17745*in 17746 17747// IN: input parameter list 17748 17749) 17750{ 17751UINT32 17752 17753groupIndex; 17754 17755TPM_RC 17756 17757result; 17758 17759// The command needs NV update. Check if NV is available. 17760// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 17761// this point 17762result = NvIsAvailable(); 17763if(result != TPM_RC_SUCCESS) return result; 17764// Input Validation: 17765// Check the authPolicy consistent with hash algorithm 17766if(in->authPolicy.t.size != CryptGetHashDigestSize(in->policyDigest)) 17767return TPM_RC_SIZE + RC_PCR_SetAuthPolicy_authPolicy; 17768// If PCR does not belong to a policy group, return TPM_RC_VALUE 17769if(!PCRBelongsPolicyGroup(in->pcrNum, &groupIndex)) 17770return TPM_RC_VALUE + RC_PCR_SetAuthPolicy_pcrNum; 17771// Internal Data Update 17772// Set PCR policy 17773gp.pcrPolicies.hashAlg[groupIndex] = in->policyDigest; 17774gp.pcrPolicies.policy[groupIndex] = in->authPolicy; 17775// Save new policy to NV 17776NvWriteReserved(NV_PCR_POLICIES, &gp.pcrPolicies); 17777return TPM_RC_SUCCESS; 17778} 17779 17780Family “2.0” 17781Level 00 Revision 00.99 17782 17783Published 17784Copyright © TCG 2006-2013 17785 17786Page 215 17787October 31, 2013 17788 17789 Part 3: Commands 17790 1779124.7 17792 17793Trusted Platform Module Library 17794 17795TPM2_PCR_SetAuthValue 17796 1779724.7.1 General Description 17798This command changes the authValue of a PCR or group of PCR. 17799An authValue may only be associated with a PCR that has been defined by a platform-specific 17800specification as allowing an authorization value. If the TPM implementation does not allow an 17801authorization for pcrNum, the TPM shall return TPM_RC_VALUE. A platform-specific specification may 17802group PCR so that they share a common authorization value. In such case, a pcrNum that selects any of 17803the PCR in the group will change the authValue value for all PCR in the group. 17804The authorization setting is set to EmptyAuth on each STARTUP(CLEAR) or by TPM2_Clear(). The 17805authorization setting is preserved by SHUTDOWN(STATE). 17806 17807Page 216 17808October 31, 2013 17809 17810Published 17811Copyright © TCG 2006-2013 17812 17813Family “2.0” 17814Level 00 Revision 00.99 17815 17816 Trusted Platform Module Library 17817 17818Part 3: Commands 17819 1782024.7.2 Command and Response 17821Table 109 — TPM2_PCR_SetAuthValue Command 17822Type 17823 17824Name 17825 17826Description 17827 17828TPMI_ST_COMMAND_TAG 17829 17830tag 17831 17832UINT32 17833 17834commandSize 17835 17836TPM_CC 17837 17838commandCode 17839 17840TPM_CC_PCR_SetAuthValue 17841 17842TPMI_DH_PCR 17843 17844@pcrHandle 17845 17846handle for a PCR that may have an authorization value 17847set 17848Auth Index: 1 17849Auth Role: USER 17850 17851TPM2B_DIGEST 17852 17853auth 17854 17855the desired authorization value 17856 17857Table 110 — TPM2_PCR_SetAuthValue Response 17858Type 17859 17860Name 17861 17862Description 17863 17864TPM_ST 17865 17866tag 17867 17868see clause 8 17869 17870UINT32 17871 17872responseSize 17873 17874TPM_RC 17875 17876responseCode 17877 17878Family “2.0” 17879Level 00 Revision 00.99 17880 17881Published 17882Copyright © TCG 2006-2013 17883 17884Page 217 17885October 31, 2013 17886 17887 Part 3: Commands 17888 17889Trusted Platform Module Library 17890 1789124.7.3 Detailed Actions 178921 178932 17894 17895#include "InternalRoutines.h" 17896#include "PCR_SetAuthValue_fp.h" 17897Error Returns 17898TPM_RC_VALUE 17899 179003 179014 179025 179036 179047 179058 179069 1790710 1790811 1790912 1791013 1791114 1791215 1791316 1791417 1791518 1791619 1791720 1791821 1791922 1792023 1792124 1792225 1792326 1792427 1792528 1792629 1792730 1792831 1792932 1793033 1793134 17932 17933Meaning 17934PCR referenced by pcrHandle is not a member of a PCR 17935authorization group 17936 17937TPM_RC 17938TPM2_PCR_SetAuthValue( 17939PCR_SetAuthValue_In 17940 17941*in 17942 17943// IN: input parameter list 17944 17945) 17946{ 17947UINT32 17948TPM_RC 17949 17950groupIndex; 17951result; 17952 17953// Input Validation: 17954// If PCR does not belong to an auth group, return TPM_RC_VALUE 17955if(!PCRBelongsAuthGroup(in->pcrHandle, &groupIndex)) 17956return TPM_RC_VALUE; 17957// The command may cause the orderlyState to be cleared due to the update of 17958// state clear data. If this is the case, Check if NV is available. 17959// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 17960// this point 17961if(gp.orderlyState != SHUTDOWN_NONE) 17962{ 17963result = NvIsAvailable(); 17964if(result != TPM_RC_SUCCESS) return result; 17965g_clearOrderly = TRUE; 17966} 17967// Internal Data Update 17968// Set PCR authValue 17969gc.pcrAuthValues.auth[groupIndex] = in->auth; 17970return TPM_RC_SUCCESS; 17971} 17972 17973Page 218 17974October 31, 2013 17975 17976Published 17977Copyright © TCG 2006-2013 17978 17979Family “2.0” 17980Level 00 Revision 00.99 17981 17982 Trusted Platform Module Library 17983 1798424.8 17985 17986Part 3: Commands 17987 17988TPM2_PCR_Reset 17989 1799024.8.1 General Description 17991If the attribute of a PCR allows the PCR to be reset and proper authorization is provided, then this 17992command may be used to set the PCR to zero. The attributes of the PCR may restrict the locality that can 17993perform the reset operation. 17994NOTE 1 17995 17996The definition of TPMI_DH_PCR in Part 2 indicates that if pcrHandle is out of the allowed range for 17997PCR, then the appropriate return value is TPM_RC_VALUE. 17998 17999If pcrHandle references a PCR that cannot be reset, the TPM shall return TPM_RC_LOCALITY. 18000NOTE 2 18001 18002TPM_RC_LOCALITY is returned because the reset attributes are defined on a per -locality basis. 18003 18004Family “2.0” 18005Level 00 Revision 00.99 18006 18007Published 18008Copyright © TCG 2006-2013 18009 18010Page 219 18011October 31, 2013 18012 18013 Part 3: Commands 18014 18015Trusted Platform Module Library 18016 1801724.8.2 Command and Response 18018Table 111 — TPM2_PCR_Reset Command 18019Type 18020 18021Name 18022 18023Description 18024 18025TPMI_ST_COMMAND_TAG 18026 18027tag 18028 18029UINT32 18030 18031commandSize 18032 18033TPM_CC 18034 18035commandCode 18036 18037TPM_CC_PCR_Reset {NV} 18038 18039TPMI_DH_PCR 18040 18041@pcrHandle 18042 18043the PCR to reset 18044Auth Index: 1 18045Auth Role: USER 18046 18047Table 112 — TPM2_PCR_Reset Response 18048Type 18049 18050Name 18051 18052Description 18053 18054TPM_ST 18055 18056tag 18057 18058see clause 8 18059 18060UINT32 18061 18062responseSize 18063 18064TPM_RC 18065 18066responseCode 18067 18068Page 220 18069October 31, 2013 18070 18071Published 18072Copyright © TCG 2006-2013 18073 18074Family “2.0” 18075Level 00 Revision 00.99 18076 18077 Trusted Platform Module Library 18078 18079Part 3: Commands 18080 1808124.8.3 Detailed Actions 180821 180832 18084 18085#include "InternalRoutines.h" 18086#include "PCR_Reset_fp.h" 18087Error Returns 18088TPM_RC_LOCALITY 18089 180903 180914 180925 180936 180947 180958 180969 1809710 1809811 1809912 1810013 1810114 1810215 1810316 1810417 1810518 1810619 1810720 1810821 1810922 1811023 1811124 1811225 1811326 1811427 1811528 1811629 1811730 1811831 1811932 1812033 1812134 1812235 1812336 18124 18125Meaning 18126current command locality is not allowed to reset the PCR referenced 18127by pcrHandle 18128 18129TPM_RC 18130TPM2_PCR_Reset( 18131PCR_Reset_In 18132 18133*in 18134 18135// IN: input parameter list 18136 18137) 18138{ 18139TPM_RC 18140 18141result; 18142 18143// Input Validation 18144// Check if the reset operation is allowed by the current command locality 18145if(!PCRIsResetAllowed(in->pcrHandle)) 18146return TPM_RC_LOCALITY; 18147// If PCR is state saved and we need to update orderlyState, check NV 18148// availability 18149if(PCRIsStateSaved(in->pcrHandle) && gp.orderlyState != SHUTDOWN_NONE) 18150{ 18151result = NvIsAvailable(); 18152if(result != TPM_RC_SUCCESS) 18153return result; 18154g_clearOrderly = TRUE; 18155} 18156// Internal Data Update 18157// Reset seleccted PCR in all banks to 0 18158PCRSetValue(in->pcrHandle, 0); 18159// Indicate that the PCR changed so that pcrCounter will be incremented if 18160// necessary. 18161PCRChanged(in->pcrHandle); 18162return TPM_RC_SUCCESS; 18163} 18164 18165Family “2.0” 18166Level 00 Revision 00.99 18167 18168Published 18169Copyright © TCG 2006-2013 18170 18171Page 221 18172October 31, 2013 18173 18174 Part 3: Commands 18175 1817624.9 18177 18178Trusted Platform Module Library 18179 18180_TPM_Hash_Start 18181 1818224.9.1 Description 18183This indication from the TPM interface indicates the start of a dynamic Core Root of Trust for 18184Measurement (D-CRTM) measurement sequence. On receipt of this indication, the TPM will initialize an 18185Event sequence context. 18186If no object memory is available for creation of the sequence context, the TPM will flush the context of an 18187object so that creation of the Event sequence context will always succeed. 18188A platform-specific specification may allow this indication before TPM2_Startup(). 18189NOTE 18190 18191If this indication occurs after TPM2_Startup(), it is the responsibility of software to ensure that an 18192object context slot is available or to deal with the consequences of having the TPM select an 18193arbitrary object to be flushed. If this indication occurs before TPM2_Startup() then all context slots 18194are available. 18195 18196Page 222 18197October 31, 2013 18198 18199Published 18200Copyright © TCG 2006-2013 18201 18202Family “2.0” 18203Level 00 Revision 00.99 18204 18205 Trusted Platform Module Library 18206 18207Part 3: Commands 18208 1820924.9.2 Detailed Actions 182101 18211 18212#include "InternalRoutines.h" 18213 18214This function is called to process a _TPM_Hash_Start() indication. 182152 182163 182174 182185 182196 182207 182218 182229 1822310 1822411 1822512 1822613 1822714 1822815 1822916 1823017 1823118 1823219 1823320 1823421 1823522 1823623 1823724 1823825 1823926 1824027 1824128 1824229 1824330 1824431 1824532 1824633 1824734 1824835 1824936 1825037 1825138 1825239 1825340 1825441 1825542 1825643 1825744 1825845 1825946 1826047 1826148 1826249 1826350 18264 18265void 18266_TPM_Hash_Start(void) 18267{ 18268TPM_RC 18269TPMI_DH_OBJECT 18270 18271result; 18272handle; 18273 18274// If a DRTM sequence object exists, terminate it. 18275if(g_DRTMHandle != TPM_RH_UNASSIGNED) 18276ObjectTerminateEvent(); 18277// Create an event sequence object and store the handle in global 18278// g_DRTMHandle. A TPM_RC_OBJECT_MEMORY error may be returned at this point 18279// The null value for the 'auth' parameter will cause the sequence structure to 18280// be allocated without being set as present. This keeps the sequence from 18281// being left behind if the sequence is terminated early. 18282result = ObjectCreateEventSequence(NULL, &g_DRTMHandle); 18283// If a free slot was not available, then free up a slot. 18284if(result != TPM_RC_SUCCESS) 18285{ 18286// An implementation does not need to have a fixed relationship between 18287// slot numbers and handle numbers. To handle the general case, scan for 18288// a handle that is assigned an free it for the DRTM sequence. 18289// In the reference implementation, the relationship between handles and 18290// slots is fixed. So, if the call to ObjectCreateEvenSequence() 18291// failed indicating that all slots are occupied, then the first handle we 18292// are going to check (TRANSIENT_FIRST) will be occupied. It will be freed 18293// so that it can be assigned for use as the DRTM sequence object. 18294for(handle = TRANSIENT_FIRST; handle < TRANSIENT_LAST; handle++) 18295{ 18296// try to flush the first object 18297if(ObjectIsPresent(handle)) 18298break; 18299} 18300// If the first call to find a slot fails but none of the slots is occupied 18301// then there's a big problem 18302pAssert(handle < TRANSIENT_LAST); 18303// Free the slot 18304ObjectFlush(handle); 18305// Try to create an event sequence object again. This time, we must 18306// succeed. 18307result = ObjectCreateEventSequence(NULL, &g_DRTMHandle); 18308pAssert(result == TPM_RC_SUCCESS); 18309} 18310return; 18311} 18312 18313Family “2.0” 18314Level 00 Revision 00.99 18315 18316Published 18317Copyright © TCG 2006-2013 18318 18319Page 223 18320October 31, 2013 18321 18322 Part 3: Commands 18323 18324Trusted Platform Module Library 18325 1832624.10 _TPM_Hash_Data 1832724.10.1 18328 18329Description 18330 18331This indication from the TPM interface indicates arrival of one or more octets of data that are to be 18332included in the Core Root of Trust for Measurement (CRTM) sequence context created by the 18333_TPM_Hash_Start indication. The context holds data for each hash algorithm for each PCR bank 18334implemented on the TPM. 18335If no DRTM Event Sequence context exists, this indication is discarded and no other action is performed. 18336 18337Page 224 18338October 31, 2013 18339 18340Published 18341Copyright © TCG 2006-2013 18342 18343Family “2.0” 18344Level 00 Revision 00.99 18345 18346 Trusted Platform Module Library 18347 1834824.10.2 183491 183502 18351 18352Part 3: Commands 18353 18354Detailed Actions 18355 18356#include "InternalRoutines.h" 18357#include "Platform.h" 18358 18359This function is called to process a _TPM_Hash_Data() indication. 183603 183614 183625 183636 183647 183658 183669 1836710 1836811 1836912 1837013 1837114 1837215 1837316 1837417 1837518 1837619 1837720 1837821 1837922 1838023 1838124 1838225 1838326 1838427 1838528 1838629 1838730 1838831 18389 18390void 18391_TPM_Hash_Data( 18392UINT32 18393BYTE 18394 18395dataSize, 18396*data 18397 18398UINT32 18399HASH_OBJECT 18400 18401// IN: size of data to be extend 18402// IN: data buffer 18403 18404i; 18405*hashObject; 18406 18407) 18408{ 18409 18410// If there is no DRTM sequence object, then _TPM_Hash_Start 18411// was not called so this function returns without doing 18412// anything. 18413if(g_DRTMHandle == TPM_RH_UNASSIGNED) 18414return; 18415hashObject = (HASH_OBJECT *)ObjectGet(g_DRTMHandle); 18416pAssert(hashObject->attributes.eventSeq); 18417// For each of the implemented hash algorithms, update the digest with the 18418// data provided. NOTE: the implementation could be done such that the TPM 18419// only computes the hash for the banks that contain the DRTM PCR. 18420for(i = 0; i < HASH_COUNT; i++) 18421{ 18422// Update sequence object 18423CryptUpdateDigest(&hashObject->state.hashState[i], dataSize, data); 18424} 18425return; 18426} 18427 18428Family “2.0” 18429Level 00 Revision 00.99 18430 18431Published 18432Copyright © TCG 2006-2013 18433 18434Page 225 18435October 31, 2013 18436 18437 Part 3: Commands 18438 18439Trusted Platform Module Library 18440 1844124.11 _TPM_Hash_End 1844224.11.1 18443 18444Description 18445 18446This indication from the TPM interface indicates the end of the CRTM measurement. This indication is 18447discarded and no other action performed if the TPM does not contain a CRTM Event sequence context. 18448NOTE 18449 18450A CRTM Event Sequence context is created by _TPM_Hash_Start(). 18451 18452If the CRTM Event sequence occurs after TPM2_Startup(), the TPM will set all of the PCR designated in 18453the platform-specific specifications as resettable by this event to the value indicated in the platform 18454specific specification, and increment restartCount. The TPM will then Extend the Event Sequence 18455digest/digests into the designated, DRTM PCR. 18456PCR[DRTM][hashAlg] ≔ HhashAlg (initial_value || HhashAlg (hash_data)) 18457 18458(7) 18459 18460where 18461DRTM 18462 18463index for CRTM PCR designated by a platform-specific 18464specification 18465 18466hashAlg 18467 18468hash algorithm associated with a bank of PCR 18469 18470initial_value 18471 18472initialization value specified in the platform-specific specification 18473(should be 0…0) 18474 18475hash_data 18476 18477all the octets of data received in _TPM_Hash_Data indications 18478 18479A _TPM_Hash_End indication that occurs after TPM2_Startup() will increment pcrUpdateCounter unless 18480a platform-specific specification excludes modifications of PCR[DRTM] from causing an increment. 18481A platform-specific specification may allow an H-CRTM Event Sequence before TPM2_Startup(). If so, 18482_TPM_Hash_End will complete the digest, initialize PCR[0] with a digest-size value of 4, and then extend 18483the H-CRTM Event Sequence data into PCR[0]. 18484PCR[0][hashAlg] ≔ HhashAlg (0…04 || HhashAlg (hash_data)) 18485NOTE 18486 18487(8) 18488 18489The entire sequence of _TPM_Hash_Start, _TPM_Hash_Data, and _TPM_Hash_End are required to 18490complete before TPM2_Startup() or the sequence will have no effect on the TPM. 18491 18492Page 226 18493October 31, 2013 18494 18495Published 18496Copyright © TCG 2006-2013 18497 18498Family “2.0” 18499Level 00 Revision 00.99 18500 18501 Trusted Platform Module Library 18502 1850324.11.2 185041 18505 18506Part 3: Commands 18507 18508Detailed Actions 18509 18510#include "InternalRoutines.h" 18511 18512This function is called to process a _TPM_Hash_End() indication. 185132 185143 185154 185165 185176 185187 185198 185209 1852110 1852211 1852312 1852413 1852514 1852615 1852716 1852817 1852918 1853019 1853120 1853221 1853322 1853423 1853524 1853625 1853726 1853827 1853928 1854029 1854130 1854231 1854332 1854433 1854534 1854635 1854736 1854837 1854938 1855039 1855140 1855241 1855342 1855443 1855544 1855645 1855746 1855847 1855948 1856049 1856150 1856251 1856352 1856453 1856554 1856655 1856756 1856857 18569 18570void 18571_TPM_Hash_End(void) 18572{ 18573UINT32 18574TPM2B_DIGEST 18575HASH_OBJECT 18576TPMI_DH_PCR 18577 18578i; 18579digest; 18580*hashObject; 18581pcrHandle; 18582 18583// If the DRTM handle is not being used, then either _TPM_Hash_Start has not 18584// been called, _TPM_Hash_End was previously called, or some other command 18585// was executed and the sequence was aborted. 18586if(g_DRTMHandle == TPM_RH_UNASSIGNED) 18587return; 18588// Get DRTM sequence object 18589hashObject = (HASH_OBJECT *)ObjectGet(g_DRTMHandle); 18590// Is this _TPM_Hash_End after Startup or before 18591if(TPMIsStarted()) 18592{ 18593// After 18594// Reset the DRTM PCR 18595PCRResetDynamics(); 18596// Extend the DRTM_PCR. 18597pcrHandle = PCR_FIRST + DRTM_PCR; 18598// DRTM sequence increments restartCount 18599gr.restartCount++; 18600} 18601else 18602{ 18603pcrHandle = PCR_FIRST + HCRTM_PCR; 18604} 18605// Complete hash and extend PCR, or if this is an HCRTM, complete 18606// the hash and write the PCR 18607for(i = 0; i < HASH_COUNT; i++) 18608{ 18609TPMI_ALG_HASH 18610hash = CryptGetHashAlgByIndex(i); 18611// Complete hash 18612digest.t.size = CryptGetHashDigestSize(hash); 18613CryptCompleteHash2B(&hashObject->state.hashState[i], &digest.b); 18614// If this is DRTM, extend to zeroed PCR 18615// If this is H-DRTM, copy to HCRM PCR 18616if(TPMIsStarted()) 18617// Extend PCR 18618PCRExtend(pcrHandle, hash, digest.t.size, digest.t.buffer); 18619else 18620PcrWrite(pcrHandle, hash, &digest); 18621 18622Family “2.0” 18623Level 00 Revision 00.99 18624 18625Published 18626Copyright © TCG 2006-2013 18627 18628Page 227 18629October 31, 2013 18630 18631 Part 3: Commands 1863258 1863359 1863460 1863561 1863662 1863763 1863864 1863965 1864066 1864167 1864268 18643 18644Trusted Platform Module Library 18645 18646} 18647// Flush sequence object. 18648ObjectFlush(g_DRTMHandle); 18649g_DRTMHandle = TPM_RH_UNASSIGNED; 18650g_DrtmPreStartup = TRUE; 18651return; 18652} 18653 18654Page 228 18655October 31, 2013 18656 18657Published 18658Copyright © TCG 2006-2013 18659 18660Family “2.0” 18661Level 00 Revision 00.99 18662 18663 Trusted Platform Module Library 18664 1866525 18666 18667Part 3: Commands 18668 18669Enhanced Authorization (EA) Commands 18670 1867125.1 18672 18673Introduction 18674 18675The commands in this clause 1 are used for policy evaluation. When successful, each command will 18676update the policySession→policyDigest in a policy session context in order to establish that the 18677authorizations required to use an object have been provided. Many of the commands will also modify 18678other parts of a policy context so that the caller may constrain the scope of the authorization that is 18679provided. 18680NOTE 1 18681 18682Many of the terms used in this clause are described in detail i n Part 1 and are not redefined in this 18683clause. 18684 18685The policySession parameter of the command is the handle of the policy session context to be modified 18686by the command. 18687If the policySession parameter indicates a trial policy session, then the policySession→policyDigest will 18688be updated and the indicated validations are not performed. 18689NOTE 2 18690 18691A policy session is a trial policy by TPM2_StartAuthSession( sessionType = TPM_SE_TRIAL). 18692 18693NOTE 3 18694 18695Unless there is an unmarshaling error in the parameters of the command, these commands will 18696return TPM_RC_SUCCESS when policySession references a trial session. 18697 18698NOTE 4 18699 18700Policy context other than the policySession→policyDigest may be updated for a trial policy but it is 18701not required. 18702 18703Family “2.0” 18704Level 00 Revision 00.99 18705 18706Published 18707Copyright © TCG 2006-2013 18708 18709Page 229 18710October 31, 2013 18711 18712 Part 3: Commands 18713 1871425.2 18715 18716Trusted Platform Module Library 18717 18718Signed Authorization Actions 18719 1872025.2.1 Introduction 18721The TPM2_PolicySigned, TPM_PolicySecret, and TPM2_PolicyTicket commands use many of the same 18722functions. This clause consolidates those functions to simplify the document and to ensure uniformity of 18723the operations. 1872425.2.2 Policy Parameter Checks 18725These parameter checks will be performed when indicated in the description of each of the commands: 18726a) nonceTPM – If this parameter is not the Empty Buffer, and 18727policySession→nonceTPM, then the TPM shall return TPM_RC_VALUE. 18728 18729it 18730 18731does 18732 18733not 18734 18735match 18736 18737b) expiration – If this parameter is not zero, then its absolute value is compared to the time in seconds 18738since the policySession→nonceTPM was generated. If more time has passed than indicted in 18739expiration, the TPM shall return TPM_RC_EXPIRED. If nonceTPM is the Empty buffer, and expiration 18740is non-zero, then the TPM shall return TPM_RC_EXPIRED. 18741c) timeout – This parameter is compared to the current TPM time. If policySession→timeout is in the 18742past, then the TPM shall return TPM_RC_EXPIRED. 18743NOTE 1 18744 18745The expiration parameter is present in the TPM2_PolicySigned and TPM2_PolicySecret 18746command and timeout is the analogous parameter in the TPM2_PolicyTicket command. 18747 18748d) cpHashA – If this parameter is not an Empty Buffer 18749NOTE 2 18750 18751CpHashA is the hash of the command to be executed using this policy session in the 18752authorization. The algorithm used to compute this hash is required to be the algorithm of the 18753policy session. 18754 187551) the TPM shall return TPM_RC_CPHASH if policySession→cpHash does not have its default 18756value or the contents of policySession→cpHash are not the same as cpHashA; or 18757NOTE 3 18758 18759CpHash is the expected cpHash value held in the policy session context. 18760 187612) the TPM shall return TPM_RC_SIZE 18762policySession→policyDigest. 18763NOTE 4 18764 18765Page 230 18766October 31, 2013 18767 18768if 18769 18770cpHashA 18771 18772is 18773 18774not 18775 18776the 18777 18778same 18779 18780size 18781 18782as 18783 18784PolicySession→policyDigest is the size of the digest produced by the hash algorithm used to 18785compute policyDigest. 18786 18787Published 18788Copyright © TCG 2006-2013 18789 18790Family “2.0” 18791Level 00 Revision 00.99 18792 18793 Trusted Platform Module Library 18794 18795Part 3: Commands 18796 1879725.2.3 PolicyDigest Update Function (PolicyUpdate()) 18798This is the update process for policySession→policyDigest used by TPM2_PolicySigned(), 18799TPM2_PolicySecret(), TPM2_PolicyTicket(), and TPM2_PolicyAuthorize(). The function prototype for the 18800update function is: 18801 18802PolicyUpdate(commandCode, arg2, arg3) 18803 18804(9) 18805 18806where 18807 18808arg2 18809 18810a TPM2B_NAME 18811 18812arg3 18813 18814a TPM2B 18815 18816These parameters are used to update policySession→policyDigest by 18817 18818policyDigestnew ≔ HpolicyAlg(policyDigestold || commandCode || arg2.name) 18819 18820(10) 18821 18822policyDigestnew+1 ≔ HpolicyAlg(policyDigestnew || arg3.buffer) 18823 18824(11) 18825 18826followed by 18827 18828where 18829 18830HpolicyAlg() 18831 18832the hash algorithm chosen when the policy session was started 18833 18834NOTE 1 18835 18836If arg3 is a TPM2B_NAME, then arg3.buffer will actually be an arg3.name. 18837 18838NOTE 2 18839 18840The arg2.size and arg3.size fields are not included in the hashes. 18841 18842NOTE 3 18843 18844PolicyUpdate() uses two hashes because arg2 and arg3 are variable-sized and the concatenation of 18845arg2 and arg3 in a single hash could produce the same digest even though arg2 and arg3 are 18846different. Processing of the arguments separately in different Extend operation insures that the 18847digest produced by PolicyUpdate() will be different if arg2 and arg3 are different. 18848 18849Family “2.0” 18850Level 00 Revision 00.99 18851 18852Published 18853Copyright © TCG 2006-2013 18854 18855Page 231 18856October 31, 2013 18857 18858 Part 3: Commands 18859 18860Trusted Platform Module Library 18861 1886225.2.4 Policy Context Updates 18863When a policy command modifies some part of the policy session context other than the 18864policySession→policyDigest, the following rules apply. 18865 18866 18867cpHash – this parameter may only be changed if it contains its initialization value (an Empty String). 18868If cpHash is not the Empty String when a policy command attempts to update it, the TPM will return 18869an error (TPM_RC_CPHASH) if the current and update values are not the same. 18870 18871 18872 18873timeOut – this parameter may only be changed to a smaller value. If a command attempts to update 18874this value with a larger value (longer into the future), the TPM will discard the update value. This is 18875not an error condition. 18876 18877 18878 18879commandCode – once set by a policy command, this value may not be change except by 18880TPM2_PolicyRestart(). If a policy command tries to change this to a different value, an error is 18881returned (TPM_RC_POLICY_CC). 18882 18883 18884 18885pcrUpdateCounter – this parameter is updated by TPM2_PolicyPCR(). This value may only be set 18886once during a policy. Each time TPM2_PolicyPCR() executes, it checks to see if 18887policySession→pcrUpdateCounter has its default state indicating that this is the first 18888TPM2_PolicyPCR(). If it has its default value, then policySession→pcrUpdateCounter is set to the 18889current value of pcrUpdateCounter. If policySession→pcrUpdateCounter does not have its default 18890value and its value is not the same as pcrUpdateCounter, the TPM shall return 18891TPM_RC_PCR_CHANGED. 18892NOTE 18893 18894If this parameter and pcrUpdateCounter are not the same, it indicates that PCR have changed 18895since checked by the previous TPM2_PolicyPCR(). Since they have changed, the previous PCR 18896validation is no longer valid. 18897 18898 18899 18900commandLocality – this parameter is the logical AND of all enabled localities. All localities are 18901enabled for a policy when the policy session is created. TPM2_PolicyLocalities() selectively disables 18902localities. Once use of a policy for a locality has been disabled, it cannot be enabled except by 18903TPM2_PolicyRestart(). 18904 18905 18906 18907isPPRequired – once SET, this parameter may only be CLEARed by TPM2_PolicyRestart(). 18908 18909 18910 18911isAuthValueNeeded – once SET, this parameter may only be CLEARed by TPM2_PolicyPassword() 18912or TPM2_PolicyRestart(). 18913 18914 18915 18916isPasswordNeeded – once SET, this parameter may only be CLEARed by TPM2_PolicyAuthValue() 18917or TPM2_PolicyRestart(), 18918 18919NOTE 18920 18921Both TPM2_PolicyAuthValue() and TPM2_PolicyPassword() change policySession→policyDigest in 18922the same way. The different commands simply indicate to the TPM the format used for the authValue 18923(HMAC or clear text). Both commands could be in the same policy. The final instance of these 18924commands determines the format. 18925 18926Page 232 18927October 31, 2013 18928 18929Published 18930Copyright © TCG 2006-2013 18931 18932Family “2.0” 18933Level 00 Revision 00.99 18934 18935 Trusted Platform Module Library 18936 18937Part 3: Commands 18938 1893925.2.5 Policy Ticket Creation 18940If for TPM2_PolicySigned() or TPM2_PolicySecret() the caller specified a negative value for expiration, 18941and the policy update succeeds, then the TPM will return a ticket that includes a value indicating when 18942the authorization expires. The required computation for the digest in the authorization ticket is: 18943 18944HMAC(proof, HpolicyAlg(ticketType || timeout || cpHashA || policyRef || authObject→Name)) (12) 18945where 18946 18947proof 18948 18949secret associated with the storage primary seed (SPS) of the 18950TPM 18951 18952HpolicyAlg 18953 18954hash function using the hash algorithm associated with the policy 18955session 18956 18957ticketType 18958 18959either TPM_ST_AUTH_SECRET or TPM_ST_AUTH_SIGNED, 18960used to indicate type of the ticket 18961 18962NOTE 1 18963 18964If 18965the 18966ticket 18967is 18968produced 18969by 18970TPM2_PolicySecret() 18971then 18972ticketType 18973is 18974TPM_ST_AUTH_SECRET and if produced by TPM2_PolicySigned() then ticketType is 18975TPM_ST_AUTH_SIGNED. 18976 18977timeout 18978 18979NOTE 2 18980 18981implementation-specific representation of the expiration time of 18982the ticket; required to be the implementation equivalent of 18983policySession→startTime plus the absolute value of expiration 18984Timeout is not the same as expiration. The expiration value in the aHash is a relative time, 18985using the creation time of the authorization session (TPM2_StartAuthSession()) as its 18986reference. The timeout parameter is an absolute time, using TPM Clock as the reference. 18987 18988cpHashA 18989 18990the command parameter digest for the command being 18991authorized; computed using the hash algorithm of the policy 18992session 18993 18994policyRef 18995 18996the commands that use this function have a policyRef parameter 18997and the value of that parameter is used here 18998 18999authObject→Name 19000 19001Name associated with the authObject parameter 19002 19003Family “2.0” 19004Level 00 Revision 00.99 19005 19006Published 19007Copyright © TCG 2006-2013 19008 19009Page 233 19010October 31, 2013 19011 19012 Part 3: Commands 1901325.3 19014 19015Trusted Platform Module Library 19016 19017TPM2_PolicySigned 19018 1901925.3.1 General Description 19020This command includes a signed authorization in a policy. The command ties the policy to a signing key 19021by including the Name of the signing key in the policyDigest 19022If policySession is a trial session, the TPM will not check the signature and will update 19023policySession→policyDigest as described in 25.2.3 as if a properly signed authorization was received; but 19024no ticket will be produced. 19025If policySession is not a trial session, the TPM will validate auth and only perform the update if it is a valid 19026signature over the fields of the command. 19027The authorizing object will sign a digest of the authorization qualifiers: nonceTPM, expiration, cpHashA, 19028and policyRef. The digest is computed as: 19029 19030aHash ≔ HauthAlg(nonceTPM || expiration || cpHashA || policyRef) 19031 19032(13) 19033 19034where 19035 19036HauthAlg() 19037NOTE 1 19038 19039the hash associated with the auth parameter of this command 19040Each signature and key combination indicates the scheme and each scheme has an 19041associated hash. 19042 19043nonceTPM 19044 19045the nonceTPM parameter from the TPM2_StartAuthSession() 19046response. If the authorization is not limited to this session, the 19047size of this value is zero. 19048 19049expiration 19050 19051time limit on authorization set by authorizing object. This 32-bit 19052value is set to zero if the expiration time is not being set. 19053 19054cpHashA 19055 19056digest of the command parameters for the command being 19057approved using the hash algorithm of the policy session. Set to 19058an EmptyAuth if the authorization is not limited to a specific 19059command. 19060 19061NOTE 2 19062 19063This is not the cpHash of this TPM2_PolicySigned() command. 19064 19065policyRef 19066EXAMPLE 19067 19068an opaque value determined by the authorizing entity. Set to the 19069Empty Buffer if no value is present. 19070 19071The computation for an aHash if there are no restrictions is: 19072 19073aHash ≔ HauthAlg(00 00 00 0016) 19074which is the hash of an expiration time of zero. 19075 19076The aHash is signed by the private key associated with key. The signature and signing parameters are 19077combined to create the auth parameter. 19078The TPM will perform the parameter checks listed in 25.2.2 19079If the parameter checks succeed, the TPM will construct a test digest (tHash) over the provided 19080parameters using the same formulation a shown in equation (13) above. 19081If tHash does not match the digest of the signed aHash, then the authorization fails and the TPM shall 19082return TPM_RC_POLICY_FAIL and make no change to policySession→policyDigest. 19083 19084Page 234 19085October 31, 2013 19086 19087Published 19088Copyright © TCG 2006-2013 19089 19090Family “2.0” 19091Level 00 Revision 00.99 19092 19093 Trusted Platform Module Library 19094 19095Part 3: Commands 19096 19097When all validations have succeeded, policySession→policyDigest is updated by PolicyUpdate() (see 1909825.2.3). 19099 19100PolicyUpdate(TPM_CC_PolicySigned, authObject→Name, policyRef) 19101 19102(14) 19103 19104If the cpHashA parameter is not an Empty Buffer, it is copied to policySession→cpHash. 19105The TPM will optionally produce a ticket as described in 25.2.5. 19106Authorization to use authObject is not required. 19107 19108Family “2.0” 19109Level 00 Revision 00.99 19110 19111Published 19112Copyright © TCG 2006-2013 19113 19114Page 235 19115October 31, 2013 19116 19117 Part 3: Commands 19118 19119Trusted Platform Module Library 19120 1912125.3.2 Command and Response 19122Table 113 — TPM2_PolicySigned Command 19123Type 19124 19125Name 19126 19127TPMI_ST_COMMAND_TAG 19128 19129tag 19130 19131UINT32 19132 19133commandSize 19134 19135TPM_CC 19136 19137commandCode 19138 19139TPM_CC_PolicySigned 19140 19141TPMI_DH_OBJECT 19142 19143authObject 19144 19145handle for a public key that will validate the signature 19146Auth Index: None 19147 19148TPMI_SH_POLICY 19149 19150policySession 19151 19152handle for the policy session being extended 19153Auth Index: None 19154 19155TPM2B_NONCE 19156 19157nonceTPM 19158 19159the policy nonce for the session 19160If the nonce is not included in the authorization 19161qualification, this field is the Empty Buffer. 19162 19163TPM2B_DIGEST 19164 19165cpHashA 19166 19167digest of the command parameters to which this 19168authorization is limited 19169This is not the cpHash for this command but the cpHash 19170for the command to which this policy session will be 19171applied. If it is not limited, the parameter will be the 19172Empty Buffer. 19173 19174TPM2B_NONCE 19175 19176policyRef 19177 19178a reference to a policy relating to the authorization – 19179may be the Empty Buffer 19180Size is limited to be no larger than the nonce size 19181supported on the TPM. 19182 19183INT32 19184 19185expiration 19186 19187time when authorization will expire, measured in 19188seconds from the time that nonceTPM was generated 19189If expiration is zero, a NULL Ticket is returned. 19190 19191TPMT_SIGNATURE 19192 19193auth 19194 19195signed authorization (not optional) 19196 19197Description 19198 19199Table 114 — TPM2_PolicySigned Response 19200Type 19201 19202Name 19203 19204Description 19205 19206TPM_ST 19207 19208tag 19209 19210see clause 8 19211 19212UINT32 19213 19214responseSize 19215 19216TPM_RC 19217 19218responseCode 19219 19220TPM2B_TIMEOUT 19221 19222timeout 19223 19224TPMT_TK_AUTH 19225 19226policyTicket 19227 19228Page 236 19229October 31, 2013 19230 19231implementation-specific time value, used to indicate to 19232the TPM when the ticket expires 19233NOTE 19234 19235If policyTicket is a NULL Ticket, then this shall be 19236the Empty Buffer. 19237 19238produced if the command succeeds and expiration in 19239the command was non-zero; this ticket will use the 19240TPMT_ST_AUTH_SIGNED structure tag 19241 19242Published 19243Copyright © TCG 2006-2013 19244 19245Family “2.0” 19246Level 00 Revision 00.99 19247 19248 Trusted Platform Module Library 19249 19250Part 3: Commands 19251 1925225.3.3 Detailed Actions 192531 192542 192553 19256 19257#include "InternalRoutines.h" 19258#include "Policy_spt_fp.h" 19259#include "PolicySigned_fp.h" 19260Error Returns 19261TPM_RC_CPHASH 19262 19263cpHash was previously set to a different value 19264 19265TPM_RC_EXPIRED 19266 19267expiration indicates a time in the past or expiration is non-zero but no 19268nonceTPM is present 19269 19270TPM_RC_HANDLE 19271 19272authObject need to have sensitive portion loaded 19273 19274TPM_RC_KEY 19275 19276authObject is not a signing scheme 19277 19278TPM_RC_NONCE 19279 19280nonceTPM is not the nonce associated with the policySession 19281 19282TPM_RC_SCHEME 19283 19284the signing scheme of auth is not supported by the TPM 19285 19286TPM_RC_SIGNATURE 19287 19288the signature is not genuine 19289 19290TPM_RC_SIZE 19291 19292input cpHash has wrong size 19293 19294TPM_RC_VALUE 19295 192964 192975 192986 192997 193008 193019 1930210 1930311 1930412 1930513 1930614 1930715 1930816 1930917 1931018 1931119 1931220 1931321 1931422 1931523 1931624 1931725 1931826 1931927 1932028 1932129 1932230 1932331 1932432 1932533 1932634 1932735 1932836 1932937 1933038 1933139 19332 19333Meaning 19334 19335input policyID or expiration does not match the internal data in policy 19336session 19337 19338TPM_RC 19339TPM2_PolicySigned( 19340PolicySigned_In 19341PolicySigned_Out 19342 19343*in, 19344*out 19345 19346// IN: input parameter list 19347// OUT: output parameter list 19348 19349TPM_RC 19350SESSION 19351OBJECT 19352TPM2B_NAME 19353TPM2B_DIGEST 19354HASH_STATE 19355UINT32 19356 19357result = TPM_RC_SUCCESS; 19358*session; 19359*authObject; 19360entityName; 19361authHash; 19362hashState; 19363expiration = (in->expiration < 0) 19364? -(in->expiration) : in->expiration; 19365authTimeout = 0; 19366 19367) 19368{ 19369 19370UINT64 19371// Input Validation 19372 19373// Set up local pointers 19374session = SessionGet(in->policySession); 19375authObject = ObjectGet(in->authObject); 19376 19377// the session structure 19378// pointer for the object 19379// 19380providing authorization 19381// 19382signature 19383 19384// Only do input validation if this is not a trial policy session 19385if(session->attributes.isTrialPolicy == CLEAR) 19386{ 19387if(expiration != 0) 19388authTimeout = expiration * 1000 + session->startTime; 19389result = PolicyParameterChecks(session, authTimeout, 19390&in->cpHashA, &in->nonceTPM, 19391RC_PolicySigned_nonceTPM, 19392RC_PolicySigned_cpHashA, 19393RC_PolicySigned_expiration); 19394if(result != TPM_RC_SUCCESS) 19395 19396Family “2.0” 19397Level 00 Revision 00.99 19398 19399Published 19400Copyright © TCG 2006-2013 19401 19402Page 237 19403October 31, 2013 19404 19405 Part 3: Commands 1940640 1940741 1940842 1940943 1941044 1941145 1941246 1941347 1941448 1941549 1941650 1941751 1941852 1941953 1942054 1942155 1942256 1942357 1942458 1942559 1942660 1942761 1942862 1942963 1943064 1943165 1943266 1943367 1943468 1943569 1943670 1943771 1943872 1943973 1944074 1944175 1944276 1944377 1944478 1944579 1944680 1944781 1944882 1944983 1945084 1945185 1945286 1945387 1945488 1945589 1945690 1945791 1945892 1945993 1946094 1946195 1946296 1946397 1946498 1946599 19466100 19467101 19468102 19469103 19470 19471Trusted Platform Module Library 19472 19473return result; 19474// Re-compute the digest being signed 19475/*(See part 3 specification) 19476// The digest is computed as: 19477// 19478aHash := hash ( nonceTPM | expiration | cpHashA | policyRef) 19479// where: 19480// 19481hash() 19482the hash associated with the signed auth 19483// 19484nonceTPM 19485the nonceTPM value from the TPM2_StartAuthSession . 19486// 19487response If the authorization is not limited to this 19488// 19489session, the size of this value is zero. 19490// 19491expiration time limit on authorization set by authorizing object. 19492// 19493This 32-bit value is set to zero if the expiration 19494// 19495time is not being set. 19496// 19497cpHashA 19498hash of the command parameters for the command being 19499// 19500approved using the hash algorithm of the PSAP session. 19501// 19502Set to NULLauth if the authorization is not limited 19503// 19504to a specific command. 19505// 19506policyRef 19507hash of an opaque value determined by the authorizing 19508// 19509object. Set to the NULLdigest if no hash is present. 19510*/ 19511// Start hash 19512authHash.t.size = CryptStartHash(CryptGetSignHashAlg(&in->auth), 19513&hashState); 19514// add nonceTPM 19515CryptUpdateDigest2B(&hashState, &in->nonceTPM.b); 19516// add expiration 19517CryptUpdateDigestInt(&hashState, sizeof(UINT32), (BYTE*) &in->expiration); 19518// add cpHashA 19519CryptUpdateDigest2B(&hashState, &in->cpHashA.b); 19520// add policyRef 19521CryptUpdateDigest2B(&hashState, &in->policyRef.b); 19522// Complete digest 19523CryptCompleteHash2B(&hashState, &authHash.b); 19524// Validate Signature. A TPM_RC_SCHEME, TPM_RC_TYPE or TPM_RC_SIGNATURE 19525// error may be returned at this point 19526result = CryptVerifySignature(in->authObject, &authHash, &in->auth); 19527if(result != TPM_RC_SUCCESS) 19528return RcSafeAddToResult(result, RC_PolicySigned_auth); 19529} 19530// Internal Data Update 19531// Need the Name of the signing entity 19532entityName.t.size = EntityGetName(in->authObject, &entityName.t.name); 19533// Update policy with input policyRef and name of auth key 19534// These values are updated even if the session is a trial session 19535PolicyContextUpdate(TPM_CC_PolicySigned, &entityName, &in->policyRef, 19536&in->cpHashA, authTimeout, session); 19537// Command Output 19538// Create ticket and timeout buffer if in->expiration < 0 and this is not 19539// a trial session. 19540// NOTE: PolicyParameterChecks() makes sure that nonceTPM is present 19541// when expiration is non-zero. 19542if( 19543in->expiration < 0 19544&& session->attributes.isTrialPolicy == CLEAR 19545) 19546 19547Page 238 19548October 31, 2013 19549 19550Published 19551Copyright © TCG 2006-2013 19552 19553Family “2.0” 19554Level 00 Revision 00.99 19555 19556 Trusted Platform Module Library 19557104 19558105 19559106 19560107 19561108 19562109 19563110 19564111 19565112 19566113 19567114 19568115 19569116 19570117 19571118 19572119 19573120 19574121 19575122 19576123 19577124 19578125 19579126 19580127 19581128 19582129 19583130 19584131 19585132 19586 19587Part 3: Commands 19588 19589{ 19590// Generate timeout buffer. The format of output timeout buffer is 19591// TPM-specific. 19592// Note: can't do a direct copy because the output buffer is a byte 19593// array and it may not be aligned to accept a 64-bit value. The method 19594// used has the side-effect of making the returned value a big-endian, 19595// 64-bit value that is byte aligned. 19596out->timeout.t.size = sizeof(UINT64); 19597UINT64_TO_BYTE_ARRAY(authTimeout, out->timeout.t.buffer); 19598// Compute policy ticket 19599TicketComputeAuth(TPM_ST_AUTH_SIGNED, EntityGetHierarchy(in->authObject), 19600authTimeout, &in->cpHashA, &in->policyRef, &entityName, 19601&out->policyTicket); 19602} 19603else 19604{ 19605// Generate a null ticket. 19606// timeout buffer is null 19607out->timeout.t.size = 0; 19608// auth ticket is null 19609out->policyTicket.tag = TPM_ST_AUTH_SIGNED; 19610out->policyTicket.hierarchy = TPM_RH_NULL; 19611out->policyTicket.digest.t.size = 0; 19612} 19613return TPM_RC_SUCCESS; 19614} 19615 19616Family “2.0” 19617Level 00 Revision 00.99 19618 19619Published 19620Copyright © TCG 2006-2013 19621 19622Page 239 19623October 31, 2013 19624 19625 Part 3: Commands 19626 1962725.4 19628 19629Trusted Platform Module Library 19630 19631TPM2_PolicySecret 19632 1963325.4.1 General Description 19634This command includes a secret-based authorization to a policy. The caller proves knowledge of the 19635secret value using an authorization session using the authValue associated with authHandle. A 19636password session, an HMAC session, or a policy session containing TPM2_PolicyAuthValue() or 19637TPM2_PolicyPassword() will satisfy this requirement. 19638“If a policy session is used and use of the authValue of authHandle is not required, the TPM will return 19639TPM_RC_MODE.” 19640The secret is the authValue of authObject, which may be any TPM entity with a handle and an associated 19641authValue. This includes the reserved handles (for example, Platform, Storage, and Endorsement), NV 19642Indexes, and loaded objects. 19643NOTE 1 19644 19645The authorization value for a hierarchy cannot be used in th is command if the hierarchy is disabled. 19646 19647If the authorization check fails, then the normal dictionary attack logic is invoked. 19648If the authorization provided by the authorization session is valid, the command parameters are checked 19649as described in 25.2.2. 19650When all validations have succeeded, policySession→policyDigest is updated by PolicyUpdate() (see 1965125.2.3). 19652 19653PolicyUpdate(TPM_CC_PolicySecret, authObject→Name, policyRef) 19654 19655(15) 19656 19657If the cpHashA command parameter is not an Empty Buffer, it is copied to cpHash in the session context. 19658The TPM will optionally produce a ticket as described in 25.2.5. 19659If the session is a trial session, policySession→policyDigest is updated as if the authorization is valid but 19660no check is performed. 19661NOTE 2 19662 19663If an HMAC is used to convey the authorization, a separate session is needed for the authorization. 19664Because the HMAC in that authorization will include a nonce that prevents replay of the 19665authorization, the value of the nonceTPM parameter in this command is limited. It is retained mostly 19666to provide processing consistency with TPM2_PolicySigned(). 19667 19668Page 240 19669October 31, 2013 19670 19671Published 19672Copyright © TCG 2006-2013 19673 19674Family “2.0” 19675Level 00 Revision 00.99 19676 19677 Trusted Platform Module Library 19678 19679Part 3: Commands 19680 1968125.4.2 Command and Response 19682Table 115 — TPM2_PolicySecret Command 19683Type 19684 19685Name 19686 19687Description 19688 19689TPMI_ST_COMMAND_TAG 19690 19691tag 19692 19693see clause 8 19694 19695UINT32 19696 19697commandSize 19698 19699TPM_CC 19700 19701commandCode 19702 19703TPM_CC_PolicySecret 19704 19705TPMI_DH_ENTITY 19706 19707@authHandle 19708 19709handle for an entity providing the authorization 19710Auth Index: 1 19711Auth Role: USER 19712 19713TPMI_SH_POLICY 19714 19715policySession 19716 19717handle for the policy session being extended 19718Auth Index: None 19719 19720TPM2B_NONCE 19721 19722nonceTPM 19723 19724the policy nonce for the session 19725If the nonce is not included in the authorization 19726qualification, this field is the Empty Buffer. 19727 19728TPM2B_DIGEST 19729 19730cpHashA 19731 19732digest of the command parameters to which this 19733authorization is limited 19734This not the cpHash for this command but the cpHash 19735for the command to which this policy session will be 19736applied. If it is not limited, the parameter will be the 19737Empty Buffer. 19738 19739TPM2B_NONCE 19740 19741policyRef 19742 19743a reference to a policy relating to the authorization – 19744may be the Empty Buffer 19745Size is limited to be no larger than the nonce size 19746supported on the TPM. 19747 19748INT32 19749 19750expiration 19751 19752time when authorization will expire, measured in 19753seconds from the time that nonceTPM was generated 19754If expiration is zero, a NULL Ticket is returned. 19755 19756Table 116 — TPM2_PolicySecret Response 19757Type 19758 19759Name 19760 19761Description 19762 19763TPM_ST 19764 19765tag 19766 19767see clause 8 19768 19769UINT32 19770 19771responseSize 19772 19773TPM_RC 19774 19775responseCode 19776 19777TPM2B_TIMEOUT 19778 19779timeout 19780 19781implementation-specific time value used to indicate to 19782the TPM when the ticket expires; this ticket will use the 19783TPMT_ST_AUTH_SECRET structure tag 19784 19785TPMT_TK_AUTH 19786 19787policyTicket 19788 19789produced if the command succeeds and expiration in 19790the command was non-zero 19791 19792Family “2.0” 19793Level 00 Revision 00.99 19794 19795Published 19796Copyright © TCG 2006-2013 19797 19798Page 241 19799October 31, 2013 19800 19801 Part 3: Commands 19802 19803Trusted Platform Module Library 19804 1980525.4.3 Detailed Actions 198061 198072 198083 19809 19810#include "InternalRoutines.h" 19811#include "PolicySecret_fp.h" 19812#include "Policy_spt_fp.h" 19813Error Returns 19814TPM_RC_CPHASH 19815 19816cpHash for policy was previously set to a value that is not the same 19817as cpHashA 19818 19819TPM_RC_EXPIRED 19820 19821expiration indicates a time in the past 19822 19823TPM_RC_NONCE 19824 19825nonceTPM does not match the nonce associated with policySession 19826 19827TPM_RC_SIZE 19828 19829cpHashA is not the size of a digest for the hash associated with 19830policySession 19831 19832TPM_RC_VALUE 19833 198344 198355 198366 198377 198388 198399 1984010 1984111 1984212 1984313 1984414 1984515 1984616 1984717 1984818 1984919 1985020 1985121 1985222 1985323 1985424 1985525 1985626 1985727 1985828 1985929 1986030 1986131 1986232 1986333 1986434 1986535 1986636 1986737 1986838 1986939 1987040 1987141 1987242 1987343 1987444 19875 19876Meaning 19877 19878input policyID or expiration does not match the internal data in policy 19879session 19880 19881TPM_RC 19882TPM2_PolicySecret( 19883PolicySecret_In 19884PolicySecret_Out 19885 19886*in, 19887*out 19888 19889// IN: input parameter list 19890// OUT: output parameter list 19891 19892TPM_RC 19893SESSION 19894TPM2B_NAME 19895UINT32 19896 19897result; 19898*session; 19899entityName; 19900expiration = (in->expiration < 0) 19901? -(in->expiration) : in->expiration; 19902authTimeout = 0; 19903 19904) 19905{ 19906 19907UINT64 19908// Input Validation 19909 19910// Get pointer to the session structure 19911session = SessionGet(in->policySession); 19912//Only do input validation if this is not a trial policy session 19913if(session->attributes.isTrialPolicy == CLEAR) 19914{ 19915if(expiration != 0) 19916authTimeout = expiration * 1000 + session->startTime; 19917result = PolicyParameterChecks(session, authTimeout, 19918&in->cpHashA, &in->nonceTPM, 19919RC_PolicySecret_nonceTPM, 19920RC_PolicySecret_cpHashA, 19921RC_PolicySecret_expiration); 19922if(result != TPM_RC_SUCCESS) 19923return result; 19924} 19925// Internal Data Update 19926// Need the name of the authorizing entity 19927entityName.t.size = EntityGetName(in->authHandle, &entityName.t.name); 19928// Update policy context with input policyRef and name of auth key 19929// This value is computed even for trial sessions. Possibly update the cpHash 19930PolicyContextUpdate(TPM_CC_PolicySecret, &entityName, &in->policyRef, 19931 19932Page 242 19933October 31, 2013 19934 19935Published 19936Copyright © TCG 2006-2013 19937 19938Family “2.0” 19939Level 00 Revision 00.99 19940 19941 Trusted Platform Module Library 1994245 1994346 1994447 1994548 1994649 1994750 1994851 1994952 1995053 1995154 1995255 1995356 1995457 1995558 1995659 1995760 1995861 1995962 1996063 1996164 1996265 1996366 1996467 1996568 1996669 1996770 1996871 1996972 1997073 1997174 1997275 1997376 1997477 1997578 1997679 1997780 1997881 1997982 1998083 19981 19982Part 3: Commands 19983 19984&in->cpHashA, authTimeout, session); 19985// Command Output 19986// Create ticket and timeout buffer if in->expiration < 0 and this is not 19987// a trial session. 19988// NOTE: PolicyParameterChecks() makes sure that nonceTPM is present 19989// when expiration is non-zero. 19990if( 19991in->expiration < 0 19992&& session->attributes.isTrialPolicy == CLEAR 19993) 19994{ 19995// Generate timeout buffer. The format of output timeout buffer is 19996// TPM-specific. 19997// Note: can't do a direct copy because the output buffer is a byte 19998// array and it may not be aligned to accept a 64-bit value. The method 19999// used has the side-effect of making the returned value a big-endian, 20000// 64-bit value that is byte aligned. 20001out->timeout.t.size = sizeof(UINT64); 20002UINT64_TO_BYTE_ARRAY(authTimeout, out->timeout.t.buffer); 20003// Compute policy ticket 20004TicketComputeAuth(TPM_ST_AUTH_SECRET, EntityGetHierarchy(in->authHandle), 20005authTimeout, &in->cpHashA, &in->policyRef, 20006&entityName, &out->policyTicket); 20007} 20008else 20009{ 20010// timeout buffer is null 20011out->timeout.t.size = 0; 20012// auth ticket is null 20013out->policyTicket.tag = TPM_ST_AUTH_SECRET; 20014out->policyTicket.hierarchy = TPM_RH_NULL; 20015out->policyTicket.digest.t.size = 0; 20016} 20017return TPM_RC_SUCCESS; 20018} 20019 20020Family “2.0” 20021Level 00 Revision 00.99 20022 20023Published 20024Copyright © TCG 2006-2013 20025 20026Page 243 20027October 31, 2013 20028 20029 Part 3: Commands 20030 2003125.5 20032 20033Trusted Platform Module Library 20034 20035TPM2_PolicyTicket 20036 2003725.5.1 General Description 20038This command is similar to TPM2_PolicySigned() except that it takes a ticket instead of a signed 20039authorization. The ticket represents a validated authorization that had an expiration time associated with 20040it. 20041The parameters of this command are checked as described in 25.2.2. 20042If the checks succeed, the TPM uses the timeout, cpHashA, policyRef, and keyName to construct a ticket 20043to compare with the value in ticket. If these tickets match, then the TPM will create a TPM2B_NAME 20044(objectName) using authName and update the context of policySession by PolicyUpdate() (see 25.2.3). 20045 20046PolicyUpdate(commandCode, authName, policyRef) 20047 20048(16) 20049 20050If the structure tag of ticket is TPM_ST_AUTH_SECRET, then commandCode will be 20051TPM_CC_PolicySecret. If the structure tag of ticket is TPM_ST_AUTH_SIGNED, then commandCode will 20052be TPM_CC_PolicySIgned. 20053If the cpHashA command parameter is not an Empty Buffer, it may be copied to cpHash in the session 20054context.as described in 25.2.1. 20055 20056Page 244 20057October 31, 2013 20058 20059Published 20060Copyright © TCG 2006-2013 20061 20062Family “2.0” 20063Level 00 Revision 00.99 20064 20065 Trusted Platform Module Library 20066 20067Part 3: Commands 20068 2006925.5.2 Command and Response 20070Table 117 — TPM2_PolicyTicket Command 20071Type 20072 20073Name 20074 20075Description 20076 20077TPMI_ST_COMMAND_TAG 20078 20079tag 20080 20081see clause 8 20082 20083UINT32 20084 20085commandSize 20086 20087TPM_CC 20088 20089commandCode 20090 20091TPM_CC_PolicyTicket 20092 20093TPMI_SH_POLICY 20094 20095policySession 20096 20097handle for the policy session being extended 20098Auth Index: None 20099 20100TPM2B_TIMEOUT 20101 20102timeout 20103 20104time when authorization will expire 20105The contents are TPM specific. This shall be the value 20106returned when ticket was produced. 20107 20108TPM2B_DIGEST 20109 20110cpHashA 20111 20112digest of the command parameters to which this 20113authorization is limited 20114If it is not limited, the parameter will be the Empty 20115Buffer. 20116 20117TPM2B_NONCE 20118 20119policyRef 20120 20121reference to a qualifier for the policy – may be the 20122Empty Buffer 20123 20124TPM2B_NAME 20125 20126authName 20127 20128name of the object that provided the authorization 20129 20130TPMT_TK_AUTH 20131 20132ticket 20133 20134an authorization ticket returned by the TPM in response 20135to a TPM2_PolicySigned() or TPM2_PolicySecret() 20136 20137Table 118 — TPM2_PolicyTicket Response 20138Type 20139 20140Name 20141 20142Description 20143 20144TPM_ST 20145 20146tag 20147 20148see clause 8 20149 20150UINT32 20151 20152responseSize 20153 20154TPM_RC 20155 20156responseCode 20157 20158Family “2.0” 20159Level 00 Revision 00.99 20160 20161Published 20162Copyright © TCG 2006-2013 20163 20164Page 245 20165October 31, 2013 20166 20167 Part 3: Commands 20168 20169Trusted Platform Module Library 20170 2017125.5.3 Detailed Actions 201721 201732 201743 20175 20176#include "InternalRoutines.h" 20177#include "PolicyTicket_fp.h" 20178#include "Policy_spt_fp.h" 20179Error Returns 20180TPM_RC_CPHASH 20181 20182policy's cpHash was previously set to a different value 20183 20184TPM_RC_EXPIRED 20185 20186timeout value in the ticket is in the past and the ticket has expired 20187 20188TPM_RC_SIZE 20189 20190timeout or cpHash has invalid size for the 20191 20192TPM_RC_TICKET 201934 201945 201956 201967 201978 201989 2019910 2020011 2020112 2020213 2020314 2020415 2020516 2020617 2020718 2020819 2020920 2021021 2021122 2021223 2021324 2021425 2021526 2021627 2021728 2021829 2021930 2022031 2022132 2022233 2022334 2022435 2022536 2022637 2022738 2022839 2022940 2023041 2023142 2023243 2023344 2023445 2023546 2023647 2023748 2023849 20239 20240Meaning 20241 20242ticket is not valid 20243 20244TPM_RC 20245TPM2_PolicyTicket( 20246PolicyTicket_In 20247 20248*in 20249 20250// IN: input parameter list 20251 20252TPM_RC 20253SESSION 20254UINT64 20255TPMT_TK_AUTH 20256TPM_CC 20257 20258result; 20259*session; 20260timeout; 20261ticketToCompare; 20262commandCode = TPM_CC_PolicySecret; 20263 20264) 20265{ 20266 20267// Input Validation 20268// Get pointer to the session structure 20269session = SessionGet(in->policySession); 20270// NOTE: A trial policy session is not allowed to use this command. 20271// A ticket is used in place of a previously given authorization. Since 20272// a trial policy doesn't actually authenticate, the validated 20273// ticket is not necessary and, in place of using a ticket, one 20274// should use the intended authorization for which the ticket 20275// would be a subsitute. 20276if(session->attributes.isTrialPolicy) 20277return TPM_RCS_ATTRIBUTES + RC_PolicyTicket_policySession; 20278// Restore timeout data. The format of timeout buffer is TPM-specific. 20279// In this implementation, we simply copy the value of timeout to the 20280// buffer. 20281if(in->timeout.t.size != sizeof(UINT64)) 20282return TPM_RC_SIZE + RC_PolicyTicket_timeout; 20283timeout = BYTE_ARRAY_TO_UINT64(in->timeout.t.buffer); 20284// Do the normal checks on the cpHashA and timeout values 20285result = PolicyParameterChecks(session, timeout, 20286&in->cpHashA, NULL, 202870, 20288// no bad nonce return 20289RC_PolicyTicket_cpHashA, 20290RC_PolicyTicket_timeout); 20291if(result != TPM_RC_SUCCESS) 20292return result; 20293// Validate Ticket 20294// Re-generate policy ticket by input parameters 20295TicketComputeAuth(in->ticket.tag, in->ticket.hierarchy, timeout, &in->cpHashA, 20296&in->policyRef, &in->authName, &ticketToCompare); 20297 20298Page 246 20299October 31, 2013 20300 20301Published 20302Copyright © TCG 2006-2013 20303 20304Family “2.0” 20305Level 00 Revision 00.99 20306 20307 Trusted Platform Module Library 2030850 2030951 2031052 2031153 2031254 2031355 2031456 2031557 2031658 2031759 2031860 2031961 2032062 2032163 2032264 2032365 2032466 2032567 2032668 2032769 2032870 2032971 2033072 2033173 20332 20333Part 3: Commands 20334 20335// Compare generated digest with input ticket digest 20336if(!Memory2BEqual(&in->ticket.digest.b, &ticketToCompare.digest.b)) 20337return TPM_RC_TICKET + RC_PolicyTicket_ticket; 20338// Internal Data Update 20339// Is this ticket to take the place of a TPM2_PolicySigned() or 20340// a TPM2_PolicySecret()? 20341if(in->ticket.tag == TPM_ST_AUTH_SIGNED) 20342commandCode = TPM_CC_PolicySigned; 20343else if(in->ticket.tag == TPM_ST_AUTH_SECRET) 20344commandCode = TPM_CC_PolicySecret; 20345else 20346// There could only be two possible tag values. Any other value should 20347// be caught by the ticket validation process. 20348pAssert(FALSE); 20349// Update policy context 20350PolicyContextUpdate(commandCode, &in->authName, &in->policyRef, 20351&in->cpHashA, timeout, session); 20352return TPM_RC_SUCCESS; 20353} 20354 20355Family “2.0” 20356Level 00 Revision 00.99 20357 20358Published 20359Copyright © TCG 2006-2013 20360 20361Page 247 20362October 31, 2013 20363 20364 Part 3: Commands 20365 2036625.6 20367 20368Trusted Platform Module Library 20369 20370TPM2_PolicyOR 20371 2037225.6.1 General Description 20373This command allows options in authorizations without requiring that the TPM evaluate all of the options. 20374If a policy may be satisfied by different sets of conditions, the TPM need only evaluate one set that 20375satisfies the policy. This command will indicate that one of the required sets of conditions has been 20376satisfied. 20377PolicySession→policyDigest is compared against the list of provided values. If the current 20378policySession→policyDigest does not match any value in the list, the TPM shall return TPM_RC_VALUE. 20379Otherwise, it will replace policySession→policyDigest with the digest of the concatenation of all of the 20380digests and return TPM_RC_SUCCESS. 20381If policySession is a trial session, the TPM will assume that policySession→policyDigest matches one of 20382the list entries and compute the new value of policyDigest. 20383The algorithm for computing the new value for policyDigest of policySession is: 20384a) Concatenate all the digest values in pHashList: 20385 20386digests ≔ pHashList.digests[1].buffer || … || pHashList.digests[n].buffer 20387NOTE 1 20388 20389(17) 20390 20391The TPM makes no check to see if the size of an entry matches the size of the digest of the 20392policy. 20393 20394b) Reset policyDigest to a Zero Digest. 20395c) Extend the command code and the hashes computed in step a) above: 20396 20397policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyOR || digests) 20398NOTE 2 20399 20400(18) 20401 20402The computation in b) and c) above is equivalent to: 20403 20404policyDigestnew ≔ HpolicyAlg(0…0 || TPM_CC_PolicyOR || digests) 20405 20406A TPM shall support a list with at least eight tagged digest values. 20407NOTE 3 20408 20409If policies are to be portable between TPMs, then they should not use more than eight values. 20410 20411Page 248 20412October 31, 2013 20413 20414Published 20415Copyright © TCG 2006-2013 20416 20417Family “2.0” 20418Level 00 Revision 00.99 20419 20420 Trusted Platform Module Library 20421 20422Part 3: Commands 20423 2042425.6.2 Command and Response 20425Table 119 — TPM2_PolicyOR Command 20426Type 20427 20428Name 20429 20430Description 20431 20432TPMI_ST_COMMAND_TAG 20433 20434tag 20435 20436UINT32 20437 20438commandSize 20439 20440TPM_CC 20441 20442commandCode 20443 20444TPM_CC_PolicyOR. 20445 20446TPMI_SH_POLICY 20447 20448policySession 20449 20450handle for the policy session being extended 20451Auth Index: None 20452 20453TPML_DIGEST 20454 20455pHashList 20456 20457the list of hashes to check for a match 20458 20459Table 120 — TPM2_PolicyOR Response 20460Type 20461 20462Name 20463 20464Description 20465 20466TPM_ST 20467 20468tag 20469 20470see clause 8 20471 20472UINT32 20473 20474responseSize 20475 20476TPM_RC 20477 20478responseCode 20479 20480Family “2.0” 20481Level 00 Revision 00.99 20482 20483Published 20484Copyright © TCG 2006-2013 20485 20486Page 249 20487October 31, 2013 20488 20489 Part 3: Commands 20490 20491Trusted Platform Module Library 20492 2049325.6.3 Detailed Actions 204941 204952 204963 20497 20498#include "InternalRoutines.h" 20499#include "PolicyOR_fp.h" 20500#include "Policy_spt_fp.h" 20501Error Returns 20502TPM_RC_VALUE 20503 205044 205055 205066 205077 205088 205099 2051010 2051111 2051212 2051313 2051414 2051515 2051616 2051717 2051818 2051919 2052020 2052121 2052222 2052323 2052424 2052525 2052626 2052727 2052828 2052929 2053030 2053131 2053232 2053333 2053434 2053535 2053636 2053737 2053838 2053939 2054040 2054141 2054242 2054343 2054444 2054545 2054646 2054747 2054848 2054949 2055050 2055151 2055252 2055353 20554 20555Meaning 20556no digest in pHashList matched the current value of policyDigest for 20557policySession 20558 20559TPM_RC 20560TPM2_PolicyOR( 20561PolicyOR_In *in 20562 20563// IN: input parameter list 20564 20565) 20566{ 20567SESSION 20568UINT32 20569 20570*session; 20571i; 20572 20573// Input Validation and Update 20574// Get pointer to the session structure 20575session = SessionGet(in->policySession); 20576// Compare and Update Internal Session policy if match 20577for(i = 0; i < in->pHashList.count; i++) 20578{ 20579if( 20580session->attributes.isTrialPolicy == SET 20581|| (Memory2BEqual(&session->u2.policyDigest.b, 20582&in->pHashList.digests[i].b)) 20583) 20584{ 20585// Found a match 20586HASH_STATE 20587hashState; 20588TPM_CC 20589commandCode = TPM_CC_PolicyOR; 20590// Start hash 20591session->u2.policyDigest.t.size = CryptStartHash(session->authHashAlg, 20592&hashState); 20593// Set policyDigest to 0 string and add it to hash 20594MemorySet(session->u2.policyDigest.t.buffer, 0, 20595session->u2.policyDigest.t.size); 20596CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 20597// add command code 20598CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 20599// Add each of the hashes in the list 20600for(i = 0; i < in->pHashList.count; i++) 20601{ 20602// Extend policyDigest 20603CryptUpdateDigest2B(&hashState, &in->pHashList.digests[i].b); 20604} 20605// Complete digest 20606CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 20607return TPM_RC_SUCCESS; 20608} 20609} 20610// None of the values in the list matched the current policyDigest 20611return TPM_RC_VALUE + RC_PolicyOR_pHashList; 20612 20613Page 250 20614October 31, 2013 20615 20616Published 20617Copyright © TCG 2006-2013 20618 20619Family “2.0” 20620Level 00 Revision 00.99 20621 20622 Trusted Platform Module Library 2062354 20624 20625Part 3: Commands 20626 20627} 20628 20629Family “2.0” 20630Level 00 Revision 00.99 20631 20632Published 20633Copyright © TCG 2006-2013 20634 20635Page 251 20636October 31, 2013 20637 20638 Part 3: Commands 20639 2064025.7 20641 20642Trusted Platform Module Library 20643 20644TPM2_PolicyPCR 20645 2064625.7.1 General Description 20647This command is used to cause conditional gating of a policy based on PCR. This allows one group of 20648authorizations to occur when PCR are in one state and a different set of authorizations when the PCR are 20649in a different state. If this command is used for a trial policySession, policySession→policyDigest will be 20650updated using the values from the command rather than the values from digest of the TPM PCR. 20651The TPM will modify the pcrs parameter so that bits that correspond to unimplemented PCR are CLEAR. 20652If policySession is not a trial policy session, the TPM will use the modified value of pcrs to select PCR 20653values to hash according to Part 1, Selecting Multiple PCR. The hash algorithm of the policy session is 20654used to compute a digest (digestTPM) of the selected PCR. If pcrDigest does not have a length of zero, 20655then it is compared to digestTPM; and if the values do not match, the TPM shall return TPM_RC_VALUE 20656and make no change to policySession→policyDigest. If the values match, or if the length of pcrDigest is 20657zero, then policySession→policyDigest is extended by: 20658 20659policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyPCR || pcrs || digestTPM) 20660 20661(19) 20662 20663where 20664 20665pcrs 20666 20667the pcrs parameter with bits corresponding to unimplemented 20668PCR set to 0 20669 20670digestTPM 20671 20672the digest of the selected PCR using the hash algorithm of the 20673policy session 20674 20675NOTE 1 20676 20677If the caller provides the expected PCR value, the intention is that the policy evaluation stop at that 20678point if the PCR do not match. If the caller does not provide the expected PCR value, then the 20679validity of the settings will not be determined until an attempt is made to use the policy for 20680authorization. If the policy is constructed such that the PCR check comes before user authorization 20681checks, this early termination would allow software to avoid unnecessary prompts for user input to 20682satisfy a policy that would fail later due to incorr ect PCR values. 20683 20684After this command completes successfully, the TPM shall return TPM_RC_PCR_CHANGED if the policy 20685session is used for authorization and the PCR are not known to be correct. 20686The TPM uses a “generation” number (pcrUpdateCounter) that is incremented each time PCR are 20687updated (unless the PCR being changed is specified not to cause a change to this counter). The value of 20688this counter is stored in the policy session context (policySession→pcrUpdateCounter) when this 20689command is executed. When the policy is used for authorization, the current value of the counter is 20690compared to the value in the policy session context and the authorization will fail if the values are not the 20691same. 20692When this command is executed, policySession→pcrUpdateCounter is checked to see if it has been 20693previously set (in the reference implementation, it has a value of zero if not previously set). If it has been 20694set, it will be compared with the current value of pcrUpdateCounter to determine if any PCR changes 20695have occurred. If the values are different, the TPM shall return TPM_RC_PCR_CHANGED. If 20696policySession→pcrUpdateCounter has not been set, then it is set to the current value of 20697pcrUpdateCounter. 20698If policySession is a trial policy session, the TPM will not check any PCR and will compute: 20699 20700policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyPCR || pcrs || pcrDigest) 20701 20702(20) 20703 20704In this computation, pcrs is the input parameter without modification. 20705NOTE 2 20706 20707The pcrs parameter is expected to match the configuration of the TPM for which the policy is being 20708computed which may not be the same as the TPM on which the trial policy is being computed. 20709 20710Page 252 20711October 31, 2013 20712 20713Published 20714Copyright © TCG 2006-2013 20715 20716Family “2.0” 20717Level 00 Revision 00.99 20718 20719 Trusted Platform Module Library 20720 20721Part 3: Commands 20722 2072325.7.2 Command and Response 20724Table 121 — TPM2_PolicyPCR Command 20725Type 20726 20727Name 20728 20729Description 20730 20731TPMI_ST_COMMAND_TAG 20732 20733tag 20734 20735UINT32 20736 20737commandSize 20738 20739TPM_CC 20740 20741commandCode 20742 20743TPM_CC_PolicyPCR 20744 20745TPMI_SH_POLICY 20746 20747policySession 20748 20749handle for the policy session being extended 20750Auth Index: None 20751 20752TPM2B_DIGEST 20753 20754pcrDigest 20755 20756expected digest value of the selected PCR using the 20757hash algorithm of the session; may be zero length 20758 20759TPML_PCR_SELECTION 20760 20761pcrs 20762 20763the PCR to include in the check digest 20764 20765Table 122 — TPM2_PolicyPCR Response 20766Type 20767 20768Name 20769 20770Description 20771 20772TPM_ST 20773 20774tag 20775 20776see clause 8 20777 20778UINT32 20779 20780responseSize 20781 20782TPM_RC 20783 20784responseCode 20785 20786Family “2.0” 20787Level 00 Revision 00.99 20788 20789Published 20790Copyright © TCG 2006-2013 20791 20792Page 253 20793October 31, 2013 20794 20795 Part 3: Commands 20796 20797Trusted Platform Module Library 20798 2079925.7.3 Detailed Actions 208001 208012 20802 20803#include "InternalRoutines.h" 20804#include "PolicyPCR_fp.h" 20805Error Returns 20806TPM_RC_VALUE 20807 20808if provided, pcrDigest does not match the current PCR settings 20809 20810TPM_RC_PCR_CHANGED 208113 208124 208135 208146 208157 208168 208179 2081810 2081911 2082012 2082113 2082214 2082315 2082416 2082517 2082618 2082719 2082820 2082921 2083022 2083123 2083224 2083325 2083426 2083527 2083628 2083729 2083830 2083931 2084032 2084133 2084234 2084335 2084436 2084537 2084638 2084739 2084840 2084941 2085042 2085143 2085244 2085345 2085446 2085547 2085648 2085749 2085850 2085951 2086052 2086153 20862 20863Meaning 20864 20865a previous TPM2_PolicyPCR() set pcrCounter and it has changed 20866 20867TPM_RC 20868TPM2_PolicyPCR( 20869PolicyPCR_In 20870 20871*in 20872 20873// IN: input parameter list 20874 20875SESSION 20876TPM2B_DIGEST 20877BYTE 20878UINT32 20879BYTE 20880TPM_CC 20881HASH_STATE 20882 20883*session; 20884pcrDigest; 20885pcrs[sizeof(TPML_PCR_SELECTION)]; 20886pcrSize; 20887*buffer; 20888commandCode = TPM_CC_PolicyPCR; 20889hashState; 20890 20891) 20892{ 20893 20894// Input Validation 20895// Get pointer to the session structure 20896session = SessionGet(in->policySession); 20897// Do validation for non trial session 20898if(session->attributes.isTrialPolicy == CLEAR) 20899{ 20900// Make sure that this is not going to invalidate a previous PCR check 20901if(session->pcrCounter != 0 && session->pcrCounter != gr.pcrCounter) 20902return TPM_RC_PCR_CHANGED; 20903// Compute current PCR digest 20904PCRComputeCurrentDigest(session->authHashAlg, &in->pcrs, &pcrDigest); 20905// If the caller specified the PCR digest and it does not 20906// match the current PCR settings, return an error.. 20907if(in->pcrDigest.t.size != 0) 20908{ 20909if(!Memory2BEqual(&in->pcrDigest.b, &pcrDigest.b)) 20910return TPM_RC_VALUE + RC_PolicyPCR_pcrDigest; 20911} 20912} 20913else 20914{ 20915// For trial session, just use the input PCR digest 20916pcrDigest = in->pcrDigest; 20917} 20918// Internal Data Update 20919// Update policy hash 20920// policyDigestnew = hash( 20921policyDigestold || TPM_CC_PolicyPCR 20922// 20923|| pcrs || pcrDigest) 20924// Start hash 20925CryptStartHash(session->authHashAlg, &hashState); 20926// add old digest 20927CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 20928 20929Page 254 20930October 31, 2013 20931 20932Published 20933Copyright © TCG 2006-2013 20934 20935Family “2.0” 20936Level 00 Revision 00.99 20937 20938 Trusted Platform Module Library 2093954 2094055 2094156 2094257 2094358 2094459 2094560 2094661 2094762 2094863 2094964 2095065 2095166 2095267 2095368 2095469 2095570 2095671 2095772 2095873 2095974 2096075 2096176 20962 20963Part 3: Commands 20964 20965// add commandCode 20966CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 20967// add PCRS 20968buffer = pcrs; 20969pcrSize = TPML_PCR_SELECTION_Marshal(&in->pcrs, &buffer, NULL); 20970CryptUpdateDigest(&hashState, pcrSize, pcrs); 20971// add PCR digest 20972CryptUpdateDigest2B(&hashState, &pcrDigest.b); 20973// complete the hash and get the results 20974CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 20975// update pcrCounter in session context for non trial session 20976if(session->attributes.isTrialPolicy == CLEAR) 20977{ 20978session->pcrCounter = gr.pcrCounter; 20979} 20980return TPM_RC_SUCCESS; 20981} 20982 20983Family “2.0” 20984Level 00 Revision 00.99 20985 20986Published 20987Copyright © TCG 2006-2013 20988 20989Page 255 20990October 31, 2013 20991 20992 Part 3: Commands 20993 2099425.8 20995 20996Trusted Platform Module Library 20997 20998TPM2_PolicyLocality 20999 2100025.8.1 General Description 21001This command indicates that the authorization will be limited to a specific locality. 21002policySession→commandLocality is a parameter kept in the session context. It is initialized when the 21003policy session is started to allow the policy to apply to any locality. 21004If locality has a value greater than 31, then an extended locality is indicated. For an extended locality, the 21005TPM will validate that policySession→commandLocality is has not previously been set or that the current 21006value of policySession→commandLocality is the same as locality (TPM_RC_RANGE). 21007When locality is not an extended locality, the TPM will validate that the policySession→commandLocality 21008is not set or is not set to an extended locality value (TPM_RC_RANGE). If not the TPM will disable any 21009locality not SET in the locality parameter. If the result of disabling localities results in no locality being 21010enabled, the TPM will return TPM_RC_RANGE. 21011If no error occurred in the validation of locality, policySession→policyDigest is extended with 21012 21013policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyLocality || locality) 21014 21015(21) 21016 21017Then policySession→commandLocality is updated to indicate which localities are still allowed after 21018execution of TPM2_PolicyLocality(). 21019When the policy session is used to authorize a command, the authorization will fail if the locality used for 21020the command is not one of the enabled localities in policySession→commandLocality. 21021 21022Page 256 21023October 31, 2013 21024 21025Published 21026Copyright © TCG 2006-2013 21027 21028Family “2.0” 21029Level 00 Revision 00.99 21030 21031 Trusted Platform Module Library 21032 21033Part 3: Commands 21034 2103525.8.2 Command and Response 21036Table 123 — TPM2_PolicyLocality Command 21037Type 21038 21039Name 21040 21041Description 21042 21043TPMI_ST_COMMAND_TAG 21044 21045tag 21046 21047UINT32 21048 21049commandSize 21050 21051TPM_CC 21052 21053commandCode 21054 21055TPM_CC_PolicyLocality 21056 21057TPMI_SH_POLICY 21058 21059policySession 21060 21061handle for the policy session being extended 21062Auth Index: None 21063 21064TPMA_LOCALITY 21065 21066locality 21067 21068the allowed localities for the policy 21069 21070Table 124 — TPM2_PolicyLocality Response 21071Type 21072 21073Name 21074 21075Description 21076 21077TPM_ST 21078 21079tag 21080 21081see clause 8 21082 21083UINT32 21084 21085responseSize 21086 21087TPM_RC 21088 21089responseCode 21090 21091Family “2.0” 21092Level 00 Revision 00.99 21093 21094Published 21095Copyright © TCG 2006-2013 21096 21097Page 257 21098October 31, 2013 21099 21100 Part 3: Commands 21101 21102Trusted Platform Module Library 21103 2110425.8.3 Detailed Actions 211051 211062 21107 21108#include "InternalRoutines.h" 21109#include "PolicyLocality_fp.h" 21110 21111Limit a policy to a specific locality 21112Error Returns 21113TPM_RC_RANGE 21114 211153 211164 211175 211186 211197 211208 211219 2112210 2112311 2112412 2112513 2112614 2112715 2112816 2112917 2113018 2113119 2113220 2113321 2113422 2113523 2113624 2113725 2113826 2113927 2114028 2114129 2114230 2114331 2114432 2114533 2114634 2114735 2114836 2114937 2115038 2115139 2115240 2115341 2115442 2115543 2115644 2115745 2115846 2115947 2116048 2116149 2116250 2116351 2116452 21165 21166Meaning 21167all the locality values selected by locality have been disabled by 21168previous TPM2_PolicyLocality() calls. 21169 21170TPM_RC 21171TPM2_PolicyLocality( 21172PolicyLocality_In 21173 21174*in 21175 21176// IN: input parameter list 21177 21178) 21179{ 21180SESSION 21181BYTE 21182BYTE 21183UINT32 21184BYTE 21185TPM_CC 21186HASH_STATE 21187 21188*session; 21189marshalBuffer[sizeof(TPMA_LOCALITY)]; 21190prevSetting[sizeof(TPMA_LOCALITY)]; 21191marshalSize; 21192*buffer; 21193commandCode = TPM_CC_PolicyLocality; 21194hashState; 21195 21196// Input Validation 21197// Get pointer to the session structure 21198session = SessionGet(in->policySession); 21199// Get new locality setting in canonical form 21200buffer = marshalBuffer; 21201marshalSize = TPMA_LOCALITY_Marshal(&in->locality, &buffer, NULL); 21202// Its an error if the locality parameter is zero 21203if(marshalBuffer[0] == 0) 21204return TPM_RC_RANGE + RC_PolicyLocality_locality; 21205// Get existing locality setting in canonical form 21206buffer = prevSetting; 21207TPMA_LOCALITY_Marshal(&session->commandLocality, &buffer, NULL); 21208// If the locality has been previously set, then it needs to be the same 21209// tye as the input locality (i.e. both extended or both normal 21210if(prevSetting[0] != 0 && ((prevSetting[0] <= 0) != (marshalBuffer[0] <= 0))) 21211return TPM_RC_RANGE + RC_PolicyLocality_locality; 21212// See if the input is a regular or extended locality 21213if(marshalBuffer[0] < 32) 21214{ 21215// For regular locality 21216// The previous setting must not be an extended locality 21217if(prevSetting[0] > 31) 21218return TPM_RC_RANGE + RC_PolicyLocality_locality; 21219// if there was no previous setting, start with all normal localities 21220// enabled 21221if(prevSetting[0] == 0) 21222prevSetting[0] = 0x1F; 21223// AND the new setting with the previous setting and store it in prevSetting 21224 21225Page 258 21226October 31, 2013 21227 21228Published 21229Copyright © TCG 2006-2013 21230 21231Family “2.0” 21232Level 00 Revision 00.99 21233 21234 Trusted Platform Module Library 2123553 2123654 2123755 2123856 2123957 2124058 2124159 2124260 2124361 2124462 2124563 2124664 2124765 2124866 2124967 2125068 2125169 2125270 2125371 2125472 2125573 2125674 2125775 2125876 2125977 2126078 2126179 2126280 2126381 2126482 2126583 2126684 2126785 2126886 2126987 2127088 2127189 2127290 2127391 2127492 2127593 2127694 2127795 2127896 2127997 21280 21281Part 3: Commands 21282 21283prevSetting[0] &= marshalBuffer[0]; 21284// The result setting can not be 0 21285if(prevSetting[0] == 0) 21286return TPM_RC_RANGE + RC_PolicyLocality_locality; 21287} 21288else 21289{ 21290// for extended locality 21291// if the locality has already been set, then it must match the 21292if(prevSetting[0] != 0 && prevSetting[0] != marshalBuffer[0]) 21293return TPM_RC_RANGE + RC_PolicyLocality_locality; 21294// Setting is OK 21295prevSetting[0] = marshalBuffer[0]; 21296} 21297// Internal Data Update 21298// Update policy hash 21299// policyDigestnew = hash(policyDigestold || TPM_CC_PolicyLocality || locality) 21300// Start hash 21301CryptStartHash(session->authHashAlg, &hashState); 21302// add old digest 21303CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 21304// add commandCode 21305CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 21306// add input locality 21307CryptUpdateDigest(&hashState, marshalSize, marshalBuffer); 21308// complete the digest 21309CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 21310// update session locality by unmarshal function. The function must succeed 21311// because both input and existing locality setting have been validated. 21312buffer = prevSetting; 21313TPMA_LOCALITY_Unmarshal(&session->commandLocality, &buffer, 21314(INT32 *) &marshalSize); 21315return TPM_RC_SUCCESS; 21316} 21317 21318Family “2.0” 21319Level 00 Revision 00.99 21320 21321Published 21322Copyright © TCG 2006-2013 21323 21324Page 259 21325October 31, 2013 21326 21327 Part 3: Commands 21328 2132925.9 21330 21331Trusted Platform Module Library 21332 21333TPM2_PolicyNV 21334 2133525.9.1 General Description 21336This command is used to cause conditional gating of a policy based on the contents of an NV Index. 21337If policySession is a trial policy session, the TPM will update policySession→policyDigest as shown in 21338equations (22) and (23) below and return TPM_RC_SUCCESS. It will not perform any validation. The 21339remainder of this general description would apply only if policySession is not a trial policy session. 21340An authorization session providing authorization to read the NV Index shall be provided. 21341NOTE 1 21342 21343If read access is controlled by policy, the policy should include a branch that authorizes a 21344TPM2_PolicyNV(). 21345 21346If TPMA_NV_WRITTEN is not SET in the NV Index, the TPM shall return TPM_RC_NV_UNINITIALIZED. 21347The TPM will validate that the size of operandB plus offset is not greater than the size of the NV Index. If 21348it is, the TPM shall return TPM_RC_SIZE. 21349The TPM will perform the indicated arithmetic check on the indicated portion of the selected NV Index. If 21350the check fails, the TPM shall return TPM_RC_POLICY and not change policySession→policyDigest. If 21351the check succeeds, the TPM will hash the arguments: 21352 21353args ≔ HpolicyAlg(operand.buffer || offset || operation) 21354 21355(22) 21356 21357where 21358 21359HpolicyAlg() 21360 21361hash function using the algorithm of the policy session 21362 21363operandB 21364 21365the value used for the comparison 21366 21367offset 21368 21369offset from the start of the NV Index data to start the comparison 21370 21371operation 21372 21373the operation parameter indicating the comparison being 21374performed 21375 21376The value of args and the Name of the NV Index are extended to policySession→policyDigest by 21377 21378policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyNV || args || nvIndex→Name) 21379 21380(23) 21381 21382where 21383 21384HpolicyAlg() 21385 21386hash function using the algorithm of the policy session 21387 21388args 21389 21390value computed in equation (22) 21391 21392nvIndex→Name 21393 21394the Name of the NV Index 21395 21396The signed arithmetic operations are performed using twos-compliment. 21397Magnitude comparisons assume that the octet at offset zero in the referenced NV location and in 21398operandB contain the most significant octet of the data. 21399NOTE 2 21400 21401When an Index is written, it has a different authorization name than an Index that has not been 21402written. It is possible to use this change in the NV Index to create a write-once Index. 21403 21404Page 260 21405October 31, 2013 21406 21407Published 21408Copyright © TCG 2006-2013 21409 21410Family “2.0” 21411Level 00 Revision 00.99 21412 21413 Trusted Platform Module Library 21414 21415Part 3: Commands 21416 2141725.9.2 Command and Response 21418Table 125 — TPM2_PolicyNV Command 21419Type 21420 21421Name 21422 21423Description 21424 21425TPMI_ST_COMMAND_TAG 21426 21427tag 21428 21429UINT32 21430 21431commandSize 21432 21433TPM_CC 21434 21435commandCode 21436 21437TPM_CC_PolicyNV 21438 21439TPMI_RH_NV_AUTH 21440 21441@authHandle 21442 21443handle indicating the source of the authorization value 21444Auth Index: 1 21445Auth Role: USER 21446 21447TPMI_RH_NV_INDEX 21448 21449nvIndex 21450 21451the NV Index of the area to read 21452Auth Index: None 21453 21454TPMI_SH_POLICY 21455 21456policySession 21457 21458handle for the policy session being extended 21459Auth Index: None 21460 21461TPM2B_OPERAND 21462 21463operandB 21464 21465the second operand 21466 21467UINT16 21468 21469offset 21470 21471the offset in the NV Index for the start of operand A 21472 21473TPM_EO 21474 21475operation 21476 21477the comparison to make 21478 21479Table 126 — TPM2_PolicyNV Response 21480Type 21481 21482Name 21483 21484Description 21485 21486TPM_ST 21487 21488tag 21489 21490see clause 8 21491 21492UINT32 21493 21494responseSize 21495 21496TPM_RC 21497 21498responseCode 21499 21500Family “2.0” 21501Level 00 Revision 00.99 21502 21503Published 21504Copyright © TCG 2006-2013 21505 21506Page 261 21507October 31, 2013 21508 21509 Part 3: Commands 21510 21511Trusted Platform Module Library 21512 2151325.9.3 Detailed Actions 215141 215152 215163 215174 21518 21519#include 21520#include 21521#include 21522#include 21523 21524"InternalRoutines.h" 21525"PolicyNV_fp.h" 21526"Policy_spt_fp.h" 21527"NV_spt_fp.h" 21528 21529// Include NV support routine for read access check 21530 21531Error Returns 21532TPM_RC_AUTH_TYPE 21533 21534NV index authorization type is not correct 21535 21536TPM_RC_NV_LOCKED 21537 21538NV index read locked 21539 21540TPM_RC_NV_UNINITIALIZED 21541 21542the NV index has not been initialized 21543 21544TPM_RC_POLICY 21545 21546the comparison to the NV contents failed 21547 21548TPM_RC_SIZE 21549 215505 215516 215527 215538 215549 2155510 2155611 2155712 2155813 2155914 2156015 2156116 2156217 2156318 2156419 2156520 2156621 2156722 2156823 2156924 2157025 2157126 2157227 2157328 2157429 2157530 2157631 2157732 2157833 2157934 2158035 2158136 2158237 2158338 2158439 2158540 2158641 2158742 2158843 2158944 2159045 2159146 21592 21593Meaning 21594 21595the size of nvIndex data starting at offset is less than the size of 21596operandB 21597 21598TPM_RC 21599TPM2_PolicyNV( 21600PolicyNV_In 21601 21602*in 21603 21604// IN: input parameter list 21605 21606TPM_RC 21607SESSION 21608NV_INDEX 21609BYTE 21610TPM2B_NAME 21611TPM_CC 21612HASH_STATE 21613TPM2B_DIGEST 21614 21615result; 21616*session; 21617nvIndex; 21618nvBuffer[sizeof(in->operandB.t.buffer)]; 21619nvName; 21620commandCode = TPM_CC_PolicyNV; 21621hashState; 21622argHash; 21623 21624) 21625{ 21626 21627// Input Validation 21628// Get NV index information 21629NvGetIndexInfo(in->nvIndex, &nvIndex); 21630// Get pointer to the session structure 21631session = SessionGet(in->policySession); 21632//If this is a trial policy, skip all validations and the operation 21633if(session->attributes.isTrialPolicy == CLEAR) 21634{ 21635// NV Read access check. NV index should be allowed for read. A 21636// TPM_RC_AUTH_TYPE or TPM_RC_NV_LOCKED error may be return at this 21637// point 21638result = NvReadAccessChecks(in->authHandle, in->nvIndex); 21639if(result != TPM_RC_SUCCESS) return result; 21640// Valid NV data size should not be smaller than input operandB size 21641if((nvIndex.publicArea.dataSize - in->offset) < in->operandB.t.size) 21642return TPM_RC_SIZE + RC_PolicyNV_operandB; 21643// Arithmetic Comparison 21644// Get NV data. The size of NV data equals the input operand B size 21645NvGetIndexData(in->nvIndex, &nvIndex, in->offset, 21646in->operandB.t.size, nvBuffer); 21647switch(in->operation) 21648 21649Page 262 21650October 31, 2013 21651 21652Published 21653Copyright © TCG 2006-2013 21654 21655Family “2.0” 21656Level 00 Revision 00.99 21657 21658 Trusted Platform Module Library 2165947 2166048 2166149 2166250 2166351 2166452 2166553 2166654 2166755 2166856 2166957 2167058 2167159 2167260 2167361 2167462 2167563 2167664 2167765 2167866 2167967 2168068 2168169 2168270 2168371 2168472 2168573 2168674 2168775 2168876 2168977 2169078 2169179 2169280 2169381 2169482 2169583 2169684 2169785 2169886 2169987 2170088 2170189 2170290 2170391 2170492 2170593 2170694 2170795 2170896 2170997 2171098 2171199 21712100 21713101 21714102 21715103 21716104 21717105 21718106 21719107 21720108 21721109 21722110 21723 21724Part 3: Commands 21725 21726{ 21727case TPM_EO_EQ: 21728// compare A = B 21729if(CryptCompare(in->operandB.t.size, nvBuffer, 21730in->operandB.t.size, in->operandB.t.buffer) 21731return TPM_RC_POLICY; 21732break; 21733case TPM_EO_NEQ: 21734// compare A != B 21735if(CryptCompare(in->operandB.t.size, nvBuffer, 21736in->operandB.t.size, in->operandB.t.buffer) 21737return TPM_RC_POLICY; 21738break; 21739case TPM_EO_SIGNED_GT: 21740// compare A > B signed 21741if(CryptCompareSigned(in->operandB.t.size, nvBuffer, 21742in->operandB.t.size, in->operandB.t.buffer) 21743return TPM_RC_POLICY; 21744break; 21745case TPM_EO_UNSIGNED_GT: 21746// compare A > B unsigned 21747if(CryptCompare(in->operandB.t.size, nvBuffer, 21748in->operandB.t.size, in->operandB.t.buffer) 21749return TPM_RC_POLICY; 21750break; 21751case TPM_EO_SIGNED_LT: 21752// compare A < B signed 21753if(CryptCompareSigned(in->operandB.t.size, nvBuffer, 21754in->operandB.t.size, in->operandB.t.buffer) 21755return TPM_RC_POLICY; 21756break; 21757case TPM_EO_UNSIGNED_LT: 21758// compare A < B unsigned 21759if(CryptCompare(in->operandB.t.size, nvBuffer, 21760in->operandB.t.size, in->operandB.t.buffer) 21761return TPM_RC_POLICY; 21762break; 21763case TPM_EO_SIGNED_GE: 21764// compare A >= B signed 21765if(CryptCompareSigned(in->operandB.t.size, nvBuffer, 21766in->operandB.t.size, in->operandB.t.buffer) 21767return TPM_RC_POLICY; 21768break; 21769case TPM_EO_UNSIGNED_GE: 21770// compare A >= B unsigned 21771if(CryptCompare(in->operandB.t.size, nvBuffer, 21772in->operandB.t.size, in->operandB.t.buffer) 21773return TPM_RC_POLICY; 21774break; 21775case TPM_EO_SIGNED_LE: 21776// compare A <= B signed 21777if(CryptCompareSigned(in->operandB.t.size, nvBuffer, 21778in->operandB.t.size, in->operandB.t.buffer) 21779return TPM_RC_POLICY; 21780break; 21781case TPM_EO_UNSIGNED_LE: 21782// compare A <= B unsigned 21783if(CryptCompare(in->operandB.t.size, nvBuffer, 21784in->operandB.t.size, in->operandB.t.buffer) 21785return TPM_RC_POLICY; 21786break; 21787case TPM_EO_BITSET: 21788// All bits SET in B are SET in A. ((A&B)=B) 21789{ 21790 21791Family “2.0” 21792Level 00 Revision 00.99 21793 21794Published 21795Copyright © TCG 2006-2013 21796 21797!= 0) 21798 21799== 0) 21800 21801<= 0) 21802 21803<= 0) 21804 21805>= 0) 21806 21807>= 0) 21808 21809< 0) 21810 21811< 0) 21812 21813> 0) 21814 21815> 0) 21816 21817Page 263 21818October 31, 2013 21819 21820 Part 3: Commands 21821111 21822112 21823113 21824114 21825115 21826116 21827117 21828118 21829119 21830120 21831121 21832122 21833123 21834124 21835125 21836126 21837127 21838128 21839129 21840130 21841131 21842132 21843133 21844134 21845135 21846136 21847137 21848138 21849139 21850140 21851141 21852142 21853143 21854144 21855145 21856146 21857147 21858148 21859149 21860150 21861151 21862152 21863153 21864154 21865155 21866156 21867157 21868158 21869159 21870160 21871161 21872162 21873163 21874164 21875165 21876166 21877167 21878168 21879169 21880170 21881171 21882 21883Trusted Platform Module Library 21884 21885UINT32 i; 21886for (i = 0; i < in->operandB.t.size; i++) 21887if((nvBuffer[i] & in->operandB.t.buffer[i]) 21888!= in->operandB.t.buffer[i]) 21889return TPM_RC_POLICY; 21890} 21891break; 21892case TPM_EO_BITCLEAR: 21893// All bits SET in B are CLEAR in A. ((A&B)=0) 21894{ 21895UINT32 i; 21896for (i = 0; i < in->operandB.t.size; i++) 21897if((nvBuffer[i] & in->operandB.t.buffer[i]) != 0) 21898return TPM_RC_POLICY; 21899} 21900break; 21901default: 21902pAssert(FALSE); 21903break; 21904} 21905} 21906// Internal Data Update 21907// Start argument hash 21908argHash.t.size = CryptStartHash(session->authHashAlg, &hashState); 21909// add operandB 21910CryptUpdateDigest2B(&hashState, &in->operandB.b); 21911// add offset 21912CryptUpdateDigestInt(&hashState, sizeof(UINT16), &in->offset); 21913// add operation 21914CryptUpdateDigestInt(&hashState, sizeof(TPM_EO), &in->operation); 21915// complete argument digest 21916CryptCompleteHash2B(&hashState, &argHash.b); 21917// Update policyDigest 21918// Start digest 21919CryptStartHash(session->authHashAlg, &hashState); 21920// add old digest 21921CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 21922// add commandCode 21923CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 21924// add argument digest 21925CryptUpdateDigest2B(&hashState, &argHash.b); 21926// Adding nvName 21927nvName.t.size = EntityGetName(in->nvIndex, &nvName.t.name); 21928CryptUpdateDigest2B(&hashState, &nvName.b); 21929// complete the digest 21930CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 21931return TPM_RC_SUCCESS; 21932} 21933 21934Page 264 21935October 31, 2013 21936 21937Published 21938Copyright © TCG 2006-2013 21939 21940Family “2.0” 21941Level 00 Revision 00.99 21942 21943 Trusted Platform Module Library 21944 21945Part 3: Commands 21946 2194725.10 TPM2_PolicyCounterTimer 2194825.10.1 21949 21950General Description 21951 21952This command is used to cause conditional gating of a policy based on the contents of the 21953TPMS_TIME_INFO structure. 21954If policySession is a trial policy session, the TPM will update policySession→policyDigest as shown in 21955equations (24) and (25) below and return TPM_RC_SUCCESS. It will not perform any validation. The 21956remainder of this general description would apply only if policySession is not a trial policy session. 21957The TPM will perform the indicated arithmetic check on the indicated portion of the TPMS_TIME_INFO 21958structure. If the check fails, the TPM shall return TPM_RC_POLICY and not change 21959policySession→policyDigest. If the check succeeds, the TPM will hash the arguments: 21960 21961args ≔ HpolicyAlg(operandB.buffer || offset || operation) 21962 21963(24) 21964 21965where 21966 21967HpolicyAlg() 21968 21969hash function using the algorithm of the policy session 21970 21971operandB.buffer 21972 21973the value used for the comparison 21974 21975offset 21976 21977offset from the start of the TPMS_TIME_INFO structure at which 21978the comparison starts 21979 21980operation 21981 21982the operation parameter indicating the comparison being 21983performed 21984 21985The value of args is extended to policySession→policyDigest by 21986 21987policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyCounterTimer || args) 21988 21989(25) 21990 21991where 21992 21993HpolicyAlg() 21994 21995hash function using the algorithm of the policy session 21996 21997args 21998 21999value computed in equation (24) 22000 22001The signed arithmetic operations are performed using twos-compliment. 22002Magnitude comparisons assume that the octet at offset zero in the referenced location and in operandB 22003contain the most significant octet of the data. 22004 22005Family “2.0” 22006Level 00 Revision 00.99 22007 22008Published 22009Copyright © TCG 2006-2013 22010 22011Page 265 22012October 31, 2013 22013 22014 Part 3: Commands 22015 2201625.10.2 22017 22018Trusted Platform Module Library 22019 22020Command and Response 22021Table 127 — TPM2_PolicyCounterTimer Command 22022 22023Type 22024 22025Name 22026 22027Description 22028 22029TPMI_ST_COMMAND_TAG 22030 22031tag 22032 22033UINT32 22034 22035commandSize 22036 22037TPM_CC 22038 22039commandCode 22040 22041TPM_CC_PolicyCounterTimer 22042 22043TPMI_SH_POLICY 22044 22045policySession 22046 22047handle for the policy session being extended 22048Auth Index: None 22049 22050TPM2B_OPERAND 22051 22052operandB 22053 22054the second operand 22055 22056UINT16 22057 22058offset 22059 22060the offset in TPMS_TIME_INFO structure for the start of 22061operand A 22062 22063TPM_EO 22064 22065operation 22066 22067the comparison to make 22068 22069Table 128 — TPM2_PolicyCounterTimer Response 22070Type 22071 22072Name 22073 22074Description 22075 22076TPM_ST 22077 22078tag 22079 22080see clause 8 22081 22082UINT32 22083 22084responseSize 22085 22086TPM_RC 22087 22088responseCode 22089 22090Page 266 22091October 31, 2013 22092 22093Published 22094Copyright © TCG 2006-2013 22095 22096Family “2.0” 22097Level 00 Revision 00.99 22098 22099 Trusted Platform Module Library 22100 2210125.10.3 221021 221032 221043 22105 22106Part 3: Commands 22107 22108Detailed Actions 22109 22110#include "InternalRoutines.h" 22111#include "PolicyCounterTimer_fp.h" 22112#include "Policy_spt_fp.h" 22113Error Returns 22114TPM_RC_POLICY 22115 22116the comparison of the selected portion of the TPMS_TIME_INFO with 22117operandB failed 22118 22119TPM_RC_RANGE 221204 221215 221226 221237 221248 221259 2212610 2212711 2212812 2212913 2213014 2213115 2213216 2213317 2213418 2213519 2213620 2213721 2213822 2213923 2214024 2214125 2214226 2214327 2214428 2214529 2214630 2214731 2214832 2214933 2215034 2215135 2215236 2215337 2215438 2215539 2215640 2215741 2215842 2215943 2216044 2216145 2216246 2216347 2216448 2216549 2216650 2216751 2216852 22169 22170Meaning 22171 22172offset + size exceed size of TPMS_TIME_INFO structure 22173 22174TPM_RC 22175TPM2_PolicyCounterTimer( 22176PolicyCounterTimer_In 22177 22178*in 22179 22180// IN: input parameter list 22181 22182) 22183{ 22184TPM_RC 22185SESSION 22186TIME_INFO 22187TPM_CC 22188HASH_STATE 22189TPM2B_DIGEST 22190 22191result; 22192*session; 22193infoData; 22194// data buffer of TPMS_TIME_INFO 22195commandCode = TPM_CC_PolicyCounterTimer; 22196hashState; 22197argHash; 22198 22199// Input Validation 22200// If the command is going to use any part of the counter or timer, need 22201// to verify that time is advancing. 22202// The time and clock vales are the first two 64-bit values in the clock 22203if(in->offset < <K>sizeof(UINT64) + sizeof(UINT64)) 22204{ 22205// Using Clock or Time so see if clock is running. Clock doesn't run while 22206// NV is unavailable. 22207// TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned here. 22208result = NvIsAvailable(); 22209if(result != TPM_RC_SUCCESS) 22210return result; 22211} 22212// Get pointer to the session structure 22213session = SessionGet(in->policySession); 22214//If this is a trial policy, skip all validations and the operation 22215if(session->attributes.isTrialPolicy == CLEAR) 22216{ 22217// Get time data info. The size of time info data equals the input 22218// operand B size. A TPM_RC_RANGE error may be returned at this point 22219result = TimeGetRange(in->offset, in->operandB.t.size, &infoData); 22220if(result != TPM_RC_SUCCESS) return result; 22221// Arithmetic Comparison 22222switch(in->operation) 22223{ 22224case TPM_EO_EQ: 22225// compare A = B 22226if(CryptCompare(in->operandB.t.size, infoData, 22227in->operandB.t.size, in->operandB.t.buffer) != 0) 22228return TPM_RC_POLICY; 22229break; 22230case TPM_EO_NEQ: 22231// compare A != B 22232if(CryptCompare(in->operandB.t.size, infoData, 22233 22234Family “2.0” 22235Level 00 Revision 00.99 22236 22237Published 22238Copyright © TCG 2006-2013 22239 22240Page 267 22241October 31, 2013 22242 22243 Part 3: Commands 2224453 2224554 2224655 2224756 2224857 2224958 2225059 2225160 2225261 2225362 2225463 2225564 2225665 2225766 2225867 2225968 2226069 2226170 2226271 2226372 2226473 2226574 2226675 2226776 2226877 2226978 2227079 2227180 2227281 2227382 2227483 2227584 2227685 2227786 2227887 2227988 2228089 2228190 2228291 2228392 2228493 2228594 2228695 2228796 2228897 2228998 2229099 22291100 22292101 22293102 22294103 22295104 22296105 22297106 22298107 22299108 22300109 22301110 22302111 22303112 22304113 22305114 22306115 22307116 22308 22309Trusted Platform Module Library 22310 22311in->operandB.t.size, in->operandB.t.buffer) 22312return TPM_RC_POLICY; 22313break; 22314case TPM_EO_SIGNED_GT: 22315// compare A > B signed 22316if(CryptCompareSigned(in->operandB.t.size, infoData, 22317in->operandB.t.size, in->operandB.t.buffer) 22318return TPM_RC_POLICY; 22319break; 22320case TPM_EO_UNSIGNED_GT: 22321// compare A > B unsigned 22322if(CryptCompare(in->operandB.t.size, infoData, 22323in->operandB.t.size, in->operandB.t.buffer) 22324return TPM_RC_POLICY; 22325break; 22326case TPM_EO_SIGNED_LT: 22327// compare A < B signed 22328if(CryptCompareSigned(in->operandB.t.size, infoData, 22329in->operandB.t.size, in->operandB.t.buffer) 22330return TPM_RC_POLICY; 22331break; 22332case TPM_EO_UNSIGNED_LT: 22333// compare A < B unsigned 22334if(CryptCompare(in->operandB.t.size, infoData, 22335in->operandB.t.size, in->operandB.t.buffer) 22336return TPM_RC_POLICY; 22337break; 22338case TPM_EO_SIGNED_GE: 22339// compare A >= B signed 22340if(CryptCompareSigned(in->operandB.t.size, infoData, 22341in->operandB.t.size, in->operandB.t.buffer) 22342return TPM_RC_POLICY; 22343break; 22344case TPM_EO_UNSIGNED_GE: 22345// compare A >= B unsigned 22346if(CryptCompare(in->operandB.t.size, infoData, 22347in->operandB.t.size, in->operandB.t.buffer) 22348return TPM_RC_POLICY; 22349break; 22350case TPM_EO_SIGNED_LE: 22351// compare A <= B signed 22352if(CryptCompareSigned(in->operandB.t.size, infoData, 22353in->operandB.t.size, in->operandB.t.buffer) 22354return TPM_RC_POLICY; 22355break; 22356case TPM_EO_UNSIGNED_LE: 22357// compare A <= B unsigned 22358if(CryptCompare(in->operandB.t.size, infoData, 22359in->operandB.t.size, in->operandB.t.buffer) 22360return TPM_RC_POLICY; 22361break; 22362case TPM_EO_BITSET: 22363// All bits SET in B are SET in A. ((A&B)=B) 22364{ 22365UINT32 i; 22366for (i = 0; i < in->operandB.t.size; i++) 22367if( 22368(infoData[i] & in->operandB.t.buffer[i]) 22369!= in->operandB.t.buffer[i]) 22370return TPM_RC_POLICY; 22371} 22372break; 22373case TPM_EO_BITCLEAR: 22374// All bits SET in B are CLEAR in A. ((A&B)=0) 22375{ 22376 22377Page 268 22378October 31, 2013 22379 22380Published 22381Copyright © TCG 2006-2013 22382 22383== 0) 22384 22385<= 0) 22386 22387<= 0) 22388 22389>= 0) 22390 22391>= 0) 22392 22393< 0) 22394 22395< 0) 22396 22397> 0) 22398 22399> 0) 22400 22401Family “2.0” 22402Level 00 Revision 00.99 22403 22404 Trusted Platform Module Library 22405117 22406118 22407119 22408120 22409121 22410122 22411123 22412124 22413125 22414126 22415127 22416128 22417129 22418130 22419131 22420132 22421133 22422134 22423135 22424136 22425137 22426138 22427139 22428140 22429141 22430142 22431143 22432144 22433145 22434146 22435147 22436148 22437149 22438150 22439151 22440152 22441153 22442154 22443155 22444156 22445157 22446158 22447159 22448 22449Part 3: Commands 22450 22451UINT32 i; 22452for (i = 0; i < in->operandB.t.size; i++) 22453if((infoData[i] & in->operandB.t.buffer[i]) != 0) 22454return TPM_RC_POLICY; 22455} 22456break; 22457default: 22458pAssert(FALSE); 22459break; 22460} 22461} 22462// Internal Data Update 22463// Start argument list hash 22464argHash.t.size = CryptStartHash(session->authHashAlg, &hashState); 22465// add operandB 22466CryptUpdateDigest2B(&hashState, &in->operandB.b); 22467// add offset 22468CryptUpdateDigestInt(&hashState, sizeof(UINT16), &in->offset); 22469// add operation 22470CryptUpdateDigestInt(&hashState, sizeof(TPM_EO), &in->operation); 22471// complete argument hash 22472CryptCompleteHash2B(&hashState, &argHash.b); 22473// update policyDigest 22474// start hash 22475CryptStartHash(session->authHashAlg, &hashState); 22476// add old digest 22477CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 22478// add commandCode 22479CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 22480// add argument digest 22481CryptUpdateDigest2B(&hashState, &argHash.b); 22482// complete the digest 22483CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 22484return TPM_RC_SUCCESS; 22485} 22486 22487Family “2.0” 22488Level 00 Revision 00.99 22489 22490Published 22491Copyright © TCG 2006-2013 22492 22493Page 269 22494October 31, 2013 22495 22496 Part 3: Commands 22497 22498Trusted Platform Module Library 22499 2250025.11 TPM2_PolicyCommandCode 2250125.11.1 22502 22503General Description 22504 22505This command indicates that the authorization will be limited to a specific command code. 22506If policySession→commandCode has its default value, then it will be set to code. If 22507policySession→commandCode does not have its default value, then the TPM will return 22508TPM_RC_VALUE if the two values are not the same. 22509If code is not implemented, the TPM will return TPM_RC_POLICY_CC. 22510If the TPM does not return an error, it will update policySession→policyDigest by 22511 22512policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyCommandCode || code) 22513 22514(26) 22515 22516NOTE 1 22517 22518If a previous TPM2_PolicyCommandCode() had been executed, then it is probable that the policy 22519expression is improperly formed but the TPM does not return an error. 22520 22521NOTE 2 22522 22523A TPM2_PolicyOR() would be used to allow an authorization to be used for multiple commands. 22524 22525When the policy session is used to authorize a command, the TPM will fail the command if the 22526commandCode of that command does not match policySession→commandCode. 22527This command, or TPM2_PolicyDuplicationSelect(), is required to enable the policy to be used for ADMIN 22528role authorization. 22529EXAMPLE 22530 22531Before TPM2_Certify() can 22532TPM_CC_Certify is required. 22533 22534Page 270 22535October 31, 2013 22536 22537be 22538 22539executed, 22540 22541TPM2_PolicyCommandCode() 22542 22543Published 22544Copyright © TCG 2006-2013 22545 22546with 22547 22548code 22549 22550set 22551 22552to 22553 22554Family “2.0” 22555Level 00 Revision 00.99 22556 22557 Trusted Platform Module Library 22558 2255925.11.2 22560 22561Part 3: Commands 22562 22563Command and Response 22564Table 129 — TPM2_PolicyCommandCode Command 22565 22566Type 22567 22568Name 22569 22570Description 22571 22572TPMI_ST_COMMAND_TAG 22573 22574tag 22575 22576UINT32 22577 22578commandSize 22579 22580TPM_CC 22581 22582commandCode 22583 22584TPM_CC_PolicyCommandCode 22585 22586TPMI_SH_POLICY 22587 22588policySession 22589 22590handle for the policy session being extended 22591Auth Index: None 22592 22593TPM_CC 22594 22595code 22596 22597the allowed commandCode 22598 22599Table 130 — TPM2_PolicyCommandCode Response 22600Type 22601 22602Name 22603 22604Description 22605 22606TPM_ST 22607 22608tag 22609 22610see clause 8 22611 22612UINT32 22613 22614responseSize 22615 22616TPM_RC 22617 22618responseCode 22619 22620Family “2.0” 22621Level 00 Revision 00.99 22622 22623Published 22624Copyright © TCG 2006-2013 22625 22626Page 271 22627October 31, 2013 22628 22629 Part 3: Commands 22630 2263125.11.3 226321 226332 22634 22635Trusted Platform Module Library 22636 22637Detailed Actions 22638 22639#include "InternalRoutines.h" 22640#include "PolicyCommandCode_fp.h" 22641Error Returns 22642TPM_RC_VALUE 22643 226443 226454 226465 226476 226487 226498 226509 2265110 2265211 2265312 2265413 2265514 2265615 2265716 2265817 2265918 2266019 2266120 2266221 2266322 2266423 2266524 2266625 2266726 2266827 2266928 2267029 2267130 2267231 2267332 2267433 2267534 2267635 2267736 2267837 2267938 2268039 2268140 2268241 2268342 2268443 2268544 22686 22687Meaning 22688commandCode of policySession previously set to a different value 22689 22690TPM_RC 22691TPM2_PolicyCommandCode( 22692PolicyCommandCode_In *in 22693 22694// IN: input parameter list 22695 22696) 22697{ 22698SESSION 22699TPM_CC 22700HASH_STATE 22701 22702*session; 22703commandCode = TPM_CC_PolicyCommandCode; 22704hashState; 22705 22706// Input validation 22707// Get pointer to the session structure 22708session = SessionGet(in->policySession); 22709if(session->commandCode != 0 && session->commandCode != in->code) 22710return TPM_RC_VALUE + RC_PolicyCommandCode_code; 22711if(!CommandIsImplemented(in->code)) 22712return TPM_RC_POLICY_CC + RC_PolicyCommandCode_code; 22713// Internal Data Update 22714// Update policy hash 22715// policyDigestnew = hash(policyDigestold || TPM_CC_PolicyCommandCode || code) 22716// Start hash 22717CryptStartHash(session->authHashAlg, &hashState); 22718// add old digest 22719CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 22720// add commandCode 22721CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 22722// add input commandCode 22723CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &in->code); 22724// complete the hash and get the results 22725CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 22726// update commandCode value in session context 22727session->commandCode = in->code; 22728return TPM_RC_SUCCESS; 22729} 22730 22731Page 272 22732October 31, 2013 22733 22734Published 22735Copyright © TCG 2006-2013 22736 22737Family “2.0” 22738Level 00 Revision 00.99 22739 22740 Trusted Platform Module Library 22741 22742Part 3: Commands 22743 2274425.12 TPM2_PolicyPhysicalPresence 2274525.12.1 22746 22747General Description 22748 22749This command indicates that physical presence will need to be asserted at the time the authorization is 22750performed. 22751If this command is successful, policySession→isPPRequired will be SET to indicate that this check is 22752required when the policy is used for authorization. Additionally, policySession→policyDigest is extended 22753with 22754 22755policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyPhysicalPresence) 22756 22757Family “2.0” 22758Level 00 Revision 00.99 22759 22760Published 22761Copyright © TCG 2006-2013 22762 22763(27) 22764 22765Page 273 22766October 31, 2013 22767 22768 Part 3: Commands 22769 2277025.12.2 22771 22772Trusted Platform Module Library 22773 22774Command and Response 22775Table 131 — TPM2_PolicyPhysicalPresence Command 22776 22777Type 22778 22779Name 22780 22781Description 22782 22783TPMI_ST_COMMAND_TAG 22784 22785tag 22786 22787UINT32 22788 22789commandSize 22790 22791TPM_CC 22792 22793commandCode 22794 22795TPM_CC_PolicyPhysicalPresence 22796 22797TPMI_SH_POLICY 22798 22799policySession 22800 22801handle for the policy session being extended 22802Auth Index: None 22803 22804Table 132 — TPM2_PolicyPhysicalPresence Response 22805Type 22806 22807Name 22808 22809Description 22810 22811TPM_ST 22812 22813tag 22814 22815see clause 8 22816 22817UINT32 22818 22819responseSize 22820 22821TPM_RC 22822 22823responseCode 22824 22825Page 274 22826October 31, 2013 22827 22828Published 22829Copyright © TCG 2006-2013 22830 22831Family “2.0” 22832Level 00 Revision 00.99 22833 22834 Trusted Platform Module Library 22835 2283625.12.3 228371 228382 228393 228404 228415 228426 228437 228448 228459 2284610 2284711 2284812 2284913 2285014 2285115 2285216 2285317 2285418 2285519 2285620 2285721 2285822 2285923 2286024 2286125 2286226 2286327 2286428 2286529 2286630 2286731 2286832 2286933 2287034 2287135 22872 22873Part 3: Commands 22874 22875Detailed Actions 22876 22877#include "InternalRoutines.h" 22878#include "PolicyPhysicalPresence_fp.h" 22879 22880TPM_RC 22881TPM2_PolicyPhysicalPresence( 22882PolicyPhysicalPresence_In *in 22883 22884// IN: input parameter list 22885 22886) 22887{ 22888SESSION 22889TPM_CC 22890HASH_STATE 22891 22892*session; 22893commandCode = TPM_CC_PolicyPhysicalPresence; 22894hashState; 22895 22896// Internal Data Update 22897// Get pointer to the session structure 22898session = SessionGet(in->policySession); 22899// Update policy hash 22900// policyDigestnew = hash(policyDigestold || TPM_CC_PolicyPhysicalPresence) 22901// Start hash 22902CryptStartHash(session->authHashAlg, &hashState); 22903// add old digest 22904CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 22905// add commandCode 22906CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 22907// complete the digest 22908CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 22909// update session attribute 22910session->attributes.isPPRequired = SET; 22911return TPM_RC_SUCCESS; 22912} 22913 22914Family “2.0” 22915Level 00 Revision 00.99 22916 22917Published 22918Copyright © TCG 2006-2013 22919 22920Page 275 22921October 31, 2013 22922 22923 Part 3: Commands 22924 22925Trusted Platform Module Library 22926 2292725.13 TPM2_PolicyCpHash 2292825.13.1 22929 22930General Description 22931 22932This command is used to allow a policy to be bound to a specific command and command parameters. 22933TPM2_PolicySigned(), TPM2_PolicySecret(), and TPM2_PolicyTIcket() are designed to allow an 22934authorizing entity to execute an arbitrary command as the cpHashA parameter of those commands is not 22935included in policySession→policyDigest. TPM2_PolicyCommandCode() allows the policy to be bound to a 22936specific Command Code so that only certain entities may authorize specific command codes. This 22937command allows the policy to be restricted such that an entity may only authorize a command with a 22938specific set of parameters. 22939If policySession→cpHash is already set and not the same as cpHashA, then the TPM shall return 22940TPM_RC_VALUE. If cpHashA does not have the size of the policySession→policyDigest, the TPM shall 22941return TPM_RC_SIZE. 22942If the cpHashA checks succeed, policySession→cpHash 22943policySession→policyDigest is updated with 22944 22945is 22946 22947set 22948 22949to 22950 22951cpHashA 22952 22953policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyCpHash || cpHashA) 22954 22955Page 276 22956October 31, 2013 22957 22958Published 22959Copyright © TCG 2006-2013 22960 22961and 22962(28) 22963 22964Family “2.0” 22965Level 00 Revision 00.99 22966 22967 Trusted Platform Module Library 22968 2296925.13.2 22970 22971Part 3: Commands 22972 22973Command and Response 22974Table 133 — TPM2_PolicyCpHash Command 22975 22976Type 22977 22978Name 22979 22980Description 22981 22982TPMI_ST_COMMAND_TAG 22983 22984tag 22985 22986UINT32 22987 22988commandSize 22989 22990TPM_CC 22991 22992commandCode 22993 22994TPM_CC_PolicyCpHash 22995 22996TPMI_SH_POLICY 22997 22998policySession 22999 23000handle for the policy session being extended 23001Auth Index: None 23002 23003TPM2B_DIGEST 23004 23005cpHashA 23006 23007the cpHash added to the policy 23008 23009Table 134 — TPM2_PolicyCpHash Response 23010Type 23011 23012Name 23013 23014Description 23015 23016TPM_ST 23017 23018tag 23019 23020see clause 8 23021 23022UINT32 23023 23024responseSize 23025 23026TPM_RC 23027 23028responseCode 23029 23030Family “2.0” 23031Level 00 Revision 00.99 23032 23033Published 23034Copyright © TCG 2006-2013 23035 23036Page 277 23037October 31, 2013 23038 23039 Part 3: Commands 23040 2304125.13.3 230421 230432 23044 23045Trusted Platform Module Library 23046 23047Detailed Actions 23048 23049#include "InternalRoutines.h" 23050#include "PolicyCpHash_fp.h" 23051Error Returns 23052TPM_RC_CPHASH 23053 23054cpHash of policySession has previously been set to a different value 23055 23056TPM_RC_SIZE 23057 230583 230594 230605 230616 230627 230638 230649 2306510 2306611 2306712 2306813 2306914 2307015 2307116 2307217 2307318 2307419 2307520 2307621 2307722 2307823 2307924 2308025 2308126 2308227 2308328 2308429 2308530 2308631 2308732 2308833 2308934 2309035 2309136 2309237 2309338 2309439 2309540 2309641 2309742 2309843 2309944 2310045 2310146 2310247 2310348 2310449 2310550 2310651 2310752 23108 23109Meaning 23110 23111cpHashA is not the size of a digest produced by the hash algorithm 23112associated with policySession 23113 23114TPM_RC 23115TPM2_PolicyCpHash( 23116PolicyCpHash_In *in 23117 23118// IN: input parameter list 23119 23120) 23121{ 23122SESSION 23123TPM_CC 23124HASH_STATE 23125 23126*session; 23127commandCode = TPM_CC_PolicyCpHash; 23128hashState; 23129 23130// Input Validation 23131// Get pointer to the session structure 23132session = SessionGet(in->policySession); 23133// A new cpHash is given in input parameter, but cpHash in session context 23134// is not empty, or is not the same as the new cpHash 23135if( 23136in->cpHashA.t.size != 0 23137&& session->u1.cpHash.t.size != 0 23138&& !Memory2BEqual(&in->cpHashA.b, &session->u1.cpHash.b) 23139) 23140return TPM_RC_CPHASH; 23141// A valid cpHash must have the same size as session hash digest 23142if(in->cpHashA.t.size != CryptGetHashDigestSize(session->authHashAlg)) 23143return TPM_RC_SIZE + RC_PolicyCpHash_cpHashA; 23144// Internal Data Update 23145// Update policy hash 23146// policyDigestnew = hash(policyDigestold || TPM_CC_PolicyCpHash || cpHashA) 23147// Start hash 23148CryptStartHash(session->authHashAlg, &hashState); 23149// add old digest 23150CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 23151// add commandCode 23152CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 23153// add cpHashA 23154CryptUpdateDigest2B(&hashState, &in->cpHashA.b); 23155// complete the digest and get the results 23156CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 23157// update cpHash in session context 23158session->u1.cpHash = in->cpHashA; 23159session->attributes.iscpHashDefined = SET; 23160return TPM_RC_SUCCESS; 23161 23162Page 278 23163October 31, 2013 23164 23165Published 23166Copyright © TCG 2006-2013 23167 23168Family “2.0” 23169Level 00 Revision 00.99 23170 23171 Trusted Platform Module Library 2317253 23173 23174Part 3: Commands 23175 23176} 23177 23178Family “2.0” 23179Level 00 Revision 00.99 23180 23181Published 23182Copyright © TCG 2006-2013 23183 23184Page 279 23185October 31, 2013 23186 23187 Part 3: Commands 23188 23189Trusted Platform Module Library 23190 2319125.14 TPM2_PolicyNameHash 2319225.14.1 23193 23194General Description 23195 23196This command allows a policy to be bound to a specific set of TPM entities without being bound to the 23197parameters of the command. This is most useful for commands such as TPM2_Duplicate() and for 23198TPM2_PCR_Event() when the referenced PCR requires a policy. 23199The nameHash parameter should contain the digest of the Names associated with the handles to be used 23200in the authorized command. 23201EXAMPLE 23202 23203For the TPM2_Duplicate() command, two handles are provided. One is the handle of the object 23204being duplicated and the other is the handle of the new parent. For that command, nameHash would 23205contain: 23206 23207nameHash ≔ H policyAlg (objectHandle→Name || newParentHandle→Name) 23208 23209If policySession→cpHash is already set, the TPM shall return TPM_RC_VALUE. If the size of nameHash 23210is not the size of policySession→policyDigest, the TPM shall return TPM_RC_SIZE. Otherwise, 23211policySession→cpHash is set to nameHash. 23212If this command completes successfully, the cpHash of the authorized command will not be used for 23213validation. Only the digest of the Names associated with the handles in the command will be used. 23214NOTE 1 23215 23216This allows the space normally 23217policySession→nameHash instead. 23218 23219used 23220 23221to 23222 23223hold 23224 23225policySession→cpHash 23226 23227to 23228 23229be 23230 23231used 23232 23233for 23234 23235The policySession→policyDigest will be updated with 23236 23237policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyNameHash || nameHash) 23238NOTE 2 23239 23240(29) 23241 23242This command will often be used with TPM2_PolicyAuthorize() where the owner of the object being 23243duplicated provides approval for their object to be migrated to a specific new parent. 23244 23245Page 280 23246October 31, 2013 23247 23248Published 23249Copyright © TCG 2006-2013 23250 23251Family “2.0” 23252Level 00 Revision 00.99 23253 23254 Trusted Platform Module Library 23255 2325625.14.2 23257 23258Part 3: Commands 23259 23260Command and Response 23261Table 135 — TPM2_PolicyNameHash Command 23262 23263Type 23264 23265Name 23266 23267Description 23268 23269TPMI_ST_COMMAND_TAG 23270 23271tag 23272 23273UINT32 23274 23275commandSize 23276 23277TPM_CC 23278 23279commandCode 23280 23281TPM_CC_PolicyNameHash 23282 23283TPMI_SH_POLICY 23284 23285policySession 23286 23287handle for the policy session being extended 23288Auth Index: None 23289 23290TPM2B_DIGEST 23291 23292nameHash 23293 23294the digest to be added to the policy 23295 23296Table 136 — TPM2_PolicyNameHash Response 23297Type 23298 23299Name 23300 23301Description 23302 23303TPM_ST 23304 23305tag 23306 23307see clause 8 23308 23309UINT32 23310 23311responseSize 23312 23313TPM_RC 23314 23315responseCode 23316 23317Family “2.0” 23318Level 00 Revision 00.99 23319 23320Published 23321Copyright © TCG 2006-2013 23322 23323Page 281 23324October 31, 2013 23325 23326 Part 3: Commands 23327 2332825.14.3 233291 233302 23331 23332Trusted Platform Module Library 23333 23334Detailed Actions 23335 23336#include "InternalRoutines.h" 23337#include "PolicyNameHash_fp.h" 23338Error Returns 23339TPM_RC_CPHASH 23340 23341nameHash has been previously set to a different value 23342 23343TPM_RC_SIZE 23344 233453 233464 233475 233486 233497 233508 233519 2335210 2335311 2335412 2335513 2335614 2335715 2335816 2335917 2336018 2336119 2336220 2336321 2336422 2336523 2336624 2336725 2336826 2336927 2337028 2337129 2337230 2337331 2337432 2337533 2337634 2337735 2337836 2337937 2338038 2338139 2338240 2338341 2338442 2338543 2338644 2338745 2338846 2338947 2339048 2339149 2339250 2339351 2339452 23395 23396Meaning 23397 23398nameHash is not the size of the digest produced by the hash 23399algorithm associated with policySession 23400 23401TPM_RC 23402TPM2_PolicyNameHash( 23403PolicyNameHash_In 23404 23405*in 23406 23407// IN: input parameter list 23408 23409SESSION 23410TPM_CC 23411HASH_STATE 23412 23413*session; 23414commandCode = TPM_CC_PolicyNameHash; 23415hashState; 23416 23417) 23418{ 23419 23420// Input Validation 23421// Get pointer to the session structure 23422session = SessionGet(in->policySession); 23423// A new nameHash is given in input parameter, but cpHash in session context 23424// is not empty 23425if(in->nameHash.t.size != 0 && session->u1.cpHash.t.size != 0) 23426return TPM_RC_CPHASH; 23427// A valid nameHash must have the same size as session hash digest 23428if(in->nameHash.t.size != CryptGetHashDigestSize(session->authHashAlg)) 23429return TPM_RC_SIZE + RC_PolicyNameHash_nameHash; 23430// Internal Data Update 23431// Update policy hash 23432// policyDigestnew = hash(policyDigestold || TPM_CC_PolicyNameHash || nameHash) 23433// Start hash 23434CryptStartHash(session->authHashAlg, &hashState); 23435// add old digest 23436CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 23437// add commandCode 23438CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 23439// add nameHash 23440CryptUpdateDigest2B(&hashState, &in->nameHash.b); 23441// complete the digest 23442CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 23443// clear iscpHashDefined bit to indicate now this field contains a nameHash 23444session->attributes.iscpHashDefined = CLEAR; 23445// update nameHash in session context 23446session->u1.cpHash = in->nameHash; 23447return TPM_RC_SUCCESS; 23448} 23449 23450Page 282 23451October 31, 2013 23452 23453Published 23454Copyright © TCG 2006-2013 23455 23456Family “2.0” 23457Level 00 Revision 00.99 23458 23459 Trusted Platform Module Library 23460 23461Part 3: Commands 23462 2346325.15 TPM2_PolicyDuplicationSelect 2346425.15.1 23465 23466General Description 23467 23468This command allows qualification of duplication to allow duplication to a selected new parent. 23469If this command not used in conjunction with TPM2_PolicyAuthorize(), then only the new parent is 23470selected. 23471EXAMPLE 23472 23473When an object is created when the list of allowed duplication targets is known, the policy would be 23474created with includeObject CLEAR. 23475 23476NOTE 1 23477 23478Only the new parent may be selected because, without TPM2_PolicyAuthorize() , the Name of the 23479Object to be duplicated would need to be known at the time that Object's policy is created. However, 23480since the Name of the Object includes its policy, the Name is not known. 23481 23482If used in conjunction with TPM2_PolicyAuthorize(), then the authorizer of the new policy has the option 23483of selecting just the new parent or of selecting both the new parent and the duplication Object.. 23484NOTE 2 23485 23486If the authorizing entity for an TPM2_PolicyAuthorize() only specifies the new parent, then that 23487authorization may be applied to the duplication of any number of other Objects. If the authorizing 23488entity specifies both a new parent and the duplicated Object, then the authorization only applies to 23489that pairing of Object and new parent. 23490 23491If either policySession→cpHash or policySession→nameHash has been previously set, the TPM shall 23492return TPM_RC_CPHASH. Otherwise, policySession→nameHash will be set to: 23493 23494nameHash ≔ HpolicyAlg(objectName || newParentName) 23495 23496(30) 23497 23498It is allowed that policySesion→nameHash and policySession→cpHash share the same memory 23499space. 23500 23501NOTE 3 23502 23503The policySession→policyDigest will be updated according to the setting of includeObject. If equal to 23504YES, policySession→policyDigest is updated by: 23505 23506policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyDuplicationSelect || 23507objectName || newParentName || includeObject) 23508 23509(31) 23510 23511If includeObject is NO, policySession→policyDigest is updated by: 23512 23513policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyDuplicationSelect || 23514newParentName || includeObject) 23515NOTE 4 23516 23517(32) 23518 23519PolicySession→CpHash receives the digest of both Names so that the check performed in 23520TPM2_Duplicate() may be the same regardless of which Names are included in 23521policySession→policyDigest. This means that, when TPM2_PolicyDuplicationSelect() is executed, it 23522is only valid for a specific pair of duplication object and new parent. 23523 23524If the command succeeds, commandCode in the policy session context is set to TPM_CC_Duplicate. 23525NOTE 5 23526 23527The normal use of this command is before a TPM2_PolicyAuthorize(). An authorized entity would 23528approve a policyDigest that allowed duplication to a specific new parent. The authorizing entity may 23529want to limit the authorization so that the approval allows only a specific object to be duplicated to 23530the new parent. In that case, the authorizing entity would approve the policyDigest of equation (31). 23531 23532Family “2.0” 23533Level 00 Revision 00.99 23534 23535Published 23536Copyright © TCG 2006-2013 23537 23538Page 283 23539October 31, 2013 23540 23541 Part 3: Commands 23542 2354325.15.2 23544 23545Trusted Platform Module Library 23546 23547Command and Response 23548Table 137 — TPM2_PolicyDuplicationSelect Command 23549 23550Type 23551 23552Name 23553 23554Description 23555 23556TPMI_ST_COMMAND_TAG 23557 23558tag 23559 23560UINT32 23561 23562commandSize 23563 23564TPM_CC 23565 23566commandCode 23567 23568TPM_CC_PolicyDuplicationSelect 23569 23570TPMI_SH_POLICY 23571 23572policySession 23573 23574handle for the policy session being extended 23575Auth Index: None 23576 23577TPM2B_NAME 23578 23579objectName 23580 23581the Name of the object to be duplicated 23582 23583TPM2B_NAME 23584 23585newParentName 23586 23587the Name of the new parent 23588 23589TPMI_YES_NO 23590 23591includeObject 23592 23593if YES, the objectName will be included in the value in 23594policySession→policyDigest 23595 23596Table 138 — TPM2_PolicyDuplicationSelect Response 23597Type 23598 23599Name 23600 23601Description 23602 23603TPM_ST 23604 23605tag 23606 23607see clause 8 23608 23609UINT32 23610 23611responseSize 23612 23613TPM_RC 23614 23615responseCode 23616 23617Page 284 23618October 31, 2013 23619 23620Published 23621Copyright © TCG 2006-2013 23622 23623Family “2.0” 23624Level 00 Revision 00.99 23625 23626 Trusted Platform Module Library 23627 2362825.15.3 236291 236302 23631 23632Part 3: Commands 23633 23634Detailed Actions 23635 23636#include "InternalRoutines.h" 23637#include "PolicyDuplicationSelect_fp.h" 23638Error Returns 23639TPM_RC_COMMAND_CODE 23640 23641commandCode of 'policySession; is not empty 23642 23643TPM_RC_CPHASH 236443 236454 236465 236476 236487 236498 236509 2365110 2365211 2365312 2365413 2365514 2365615 2365716 2365817 2365918 2366019 2366120 2366221 2366322 2366423 2366524 2366625 2366726 2366827 2366928 2367029 2367130 2367231 2367332 2367433 2367534 2367635 2367736 2367837 2367938 2368039 2368140 2368241 2368342 2368443 2368544 2368645 2368746 2368847 2368948 2369049 2369150 2369251 2369352 2369453 23695 23696Meaning 23697 23698cpHash of policySession is not empty 23699 23700TPM_RC 23701TPM2_PolicyDuplicationSelect( 23702PolicyDuplicationSelect_In *in 23703 23704// IN: input parameter list 23705 23706) 23707{ 23708SESSION 23709HASH_STATE 23710TPM_CC 23711 23712*session; 23713hashState; 23714commandCode = TPM_CC_PolicyDuplicationSelect; 23715 23716// Input Validation 23717// Get pointer to the session structure 23718session = SessionGet(in->policySession); 23719// cpHash in session context must be empty 23720if(session->u1.cpHash.t.size != 0) 23721return TPM_RC_CPHASH; 23722// commandCode in session context must be empty 23723if(session->commandCode != 0) 23724return TPM_RC_COMMAND_CODE; 23725// Internal Data Update 23726// Update name hash 23727session->u1.cpHash.t.size = CryptStartHash(session->authHashAlg, &hashState); 23728// add objectName 23729CryptUpdateDigest2B(&hashState, &in->objectName.b); 23730// add new parent name 23731CryptUpdateDigest2B(&hashState, &in->newParentName.b); 23732// complete hash 23733CryptCompleteHash2B(&hashState, &session->u1.cpHash.b); 23734// update policy hash 23735// Old policyDigest size should be the same as the new policyDigest size since 23736// they are using the same hash algorithm 23737session->u2.policyDigest.t.size 23738= CryptStartHash(session->authHashAlg, &hashState); 23739// add old policy 23740CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 23741// add command code 23742CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 23743// add objectName 23744if(in->includeObject == YES) 23745CryptUpdateDigest2B(&hashState, &in->objectName.b); 23746 23747Family “2.0” 23748Level 00 Revision 00.99 23749 23750Published 23751Copyright © TCG 2006-2013 23752 23753Page 285 23754October 31, 2013 23755 23756 Part 3: Commands 2375754 2375855 2375956 2376057 2376158 2376259 2376360 2376461 2376562 2376663 2376764 2376865 2376966 2377067 2377168 2377269 2377370 2377471 23775 23776Trusted Platform Module Library 23777 23778// add new parent name 23779CryptUpdateDigest2B(&hashState, &in->newParentName.b); 23780// add includeObject 23781CryptUpdateDigestInt(&hashState, sizeof(TPMI_YES_NO), &in->includeObject); 23782// complete digest 23783CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 23784// clear iscpHashDefined bit to indicate now this field contains a nameHash 23785session->attributes.iscpHashDefined = CLEAR; 23786// set commandCode in session context 23787session->commandCode = TPM_CC_Duplicate; 23788return TPM_RC_SUCCESS; 23789} 23790 23791Page 286 23792October 31, 2013 23793 23794Published 23795Copyright © TCG 2006-2013 23796 23797Family “2.0” 23798Level 00 Revision 00.99 23799 23800 Trusted Platform Module Library 23801 23802Part 3: Commands 23803 2380425.16 TPM2_PolicyAuthorize 2380525.16.1 23806 23807General Description 23808 23809This command allows policies to change. If a policy were static, then it would be difficult to add users to a 23810policy. This command lets a policy authority sign a new policy so that it may be used in an existing policy. 23811The authorizing entity signs a structure that contains 23812 23813aHash ≔ HaHashAlg(approvedPolicy || policyRef) 23814 23815(33) 23816 23817The aHashAlg is required to be the nameAlg of the key used to sign the aHash. The aHash value is then 23818signed (symmetric or asymmetric) by keySign. That signature is then checked by the TPM in 23819TPM2_VerifySignature() which produces a ticket by 23820 23821HMAC(proof, (TPM_ST_VERIFIED || aHash || keySign→Name)) 23822NOTE 23823 23824(34) 23825 23826The reason for the validation is because of the expectation that the policy will be used multiple times 23827and it is more efficient to check a ticket than to load an object each time to chec k a signature. 23828 23829The ticket is then used in TPM2_PolicyAuthorize() to validate the parameters. 23830The keySign parameter is required to be a valid object name using nameAlg other than TPM_ALG_NULL. 23831If the first two octets of keySign are not a valid hash algorithm, the TPM shall return TPM_RC_HASH. If 23832the remainder of the Name is not the size of the indicated digest, the TPM shall return TPM_RC_SIZE. 23833The TPM validates that the approvedPolicy matches the current value of policySession→policyDigest and 23834if not, shall return TPM_RC_VALUE. 23835The TPM then validates that the parameters to TPM2_PolicyAuthorize() match the values used to 23836generate the ticket. If so, the TPM will reset policySession→policyDigest to a Zero Digest. Then it will 23837create a TPM2B_NAME (keyName) using keySign and update policySession→policyDigest with 23838PolicyUpdate() (see 25.2.3). 23839 23840PolicyUpdate(TPM_CC_PolicyAuthorize, keyName, policyRef) 23841 23842(35) 23843 23844If the ticket is not valid, the TPM shall return TPM_RC_POLICY. 23845If policySession is a trial session, policySession→policyDigest is extended as if the ticket is valid without 23846actual verification. 23847NOTE 23848 23849The unmarshaling process requires that a proper TPMT_TK_VERIFIED be provided for checkTicket 23850but it may be a NULL Ticket. 23851 23852Family “2.0” 23853Level 00 Revision 00.99 23854 23855Published 23856Copyright © TCG 2006-2013 23857 23858Page 287 23859October 31, 2013 23860 23861 Part 3: Commands 23862 2386325.16.2 23864 23865Trusted Platform Module Library 23866 23867Command and Response 23868Table 139 — TPM2_PolicyAuthorize Command 23869 23870Type 23871 23872Name 23873 23874Description 23875 23876TPMI_ST_COMMAND_TAG 23877 23878tag 23879 23880UINT32 23881 23882commandSize 23883 23884TPM_CC 23885 23886commandCode 23887 23888TPM_CC_PolicyAuthorize 23889 23890TPMI_SH_POLICY 23891 23892policySession 23893 23894handle for the policy session being extended 23895Auth Index: None 23896 23897TPM2B_DIGEST 23898 23899approvedPolicy 23900 23901digest of the policy being approved 23902 23903TPM2B_NONCE 23904 23905policyRef 23906 23907a policy qualifier 23908 23909TPM2B_NAME 23910 23911keySign 23912 23913Name of a key that can sign a policy addition 23914 23915TPMT_TK_VERIFIED 23916 23917checkTicket 23918 23919ticket validating that approvedPolicy and policyRef were 23920signed by keySign 23921 23922Table 140 — TPM2_PolicyAuthorize Response 23923Type 23924 23925Name 23926 23927Description 23928 23929TPM_ST 23930 23931tag 23932 23933see clause 8 23934 23935UINT32 23936 23937responseSize 23938 23939TPM_RC 23940 23941responseCode 23942 23943Page 288 23944October 31, 2013 23945 23946Published 23947Copyright © TCG 2006-2013 23948 23949Family “2.0” 23950Level 00 Revision 00.99 23951 23952 Trusted Platform Module Library 23953 2395425.16.3 239551 239562 239573 23958 23959Part 3: Commands 23960 23961Detailed Actions 23962 23963#include "InternalRoutines.h" 23964#include "PolicyAuthorize_fp.h" 23965#include "Policy_spt_fp.h" 23966Error Returns 23967TPM_RC_HASH 23968 23969hash algorithm in keyName is not supported 23970 23971TPM_RC_SIZE 23972 23973keyName is not the correct size for its hash algorithm 23974 23975TPM_RC_VALUE 23976 239774 239785 239796 239807 239818 239829 2398310 2398411 2398512 2398613 2398714 2398815 2398916 2399017 2399118 2399219 2399320 2399421 2399522 2399623 2399724 2399825 2399926 2400027 2400128 2400229 2400330 2400431 2400532 2400633 2400734 2400835 2400936 2401037 2401138 2401239 2401340 2401441 2401542 2401643 2401744 2401845 2401946 2402047 2402148 2402249 2402350 24024 24025Meaning 24026 24027the current policyDigest of policySession does not match 24028approvedPolicy; or checkTicket doesn't match the provided values 24029 24030TPM_RC 24031TPM2_PolicyAuthorize( 24032PolicyAuthorize_In 24033 24034*in 24035 24036// IN: input parameter list 24037 24038SESSION 24039TPM2B_DIGEST 24040HASH_STATE 24041TPMT_TK_VERIFIED 24042TPM_ALG_ID 24043UINT16 24044 24045*session; 24046authHash; 24047hashState; 24048ticket; 24049hashAlg; 24050digestSize; 24051 24052) 24053{ 24054 24055// Input Validation 24056// Get pointer to the session structure 24057session = SessionGet(in->policySession); 24058// Extract from the Name of the key, the algorithm used to compute it's Name 24059hashAlg = BYTE_ARRAY_TO_UINT16(in->keySign.t.name); 24060// 'keySign' parameter needs to use a supported hash algorithm, otherwise 24061// can't tell how large the digest should be 24062digestSize = CryptGetHashDigestSize(hashAlg); 24063if(digestSize == 0) 24064return TPM_RC_HASH + RC_PolicyAuthorize_keySign; 24065if(digestSize != (in->keySign.t.size - 2)) 24066return TPM_RC_SIZE + RC_PolicyAuthorize_keySign; 24067//If this is a trial policy, skip all validations 24068if(session->attributes.isTrialPolicy == CLEAR) 24069{ 24070// Check that "approvedPolicy" matches the current value of the 24071// policyDigest in policy session 24072if(!Memory2BEqual(&session->u2.policyDigest.b, 24073&in->approvedPolicy.b)) 24074return TPM_RC_VALUE + RC_PolicyAuthorize_approvedPolicy; 24075// Validate ticket TPMT_TK_VERIFIED 24076// Compute aHash. The authorizing object sign a digest 24077// aHash := hash(approvedPolicy || policyRef). 24078// Start hash 24079authHash.t.size = CryptStartHash(hashAlg, &hashState); 24080// add approvedPolicy 24081CryptUpdateDigest2B(&hashState, &in->approvedPolicy.b); 24082 24083Family “2.0” 24084Level 00 Revision 00.99 24085 24086Published 24087Copyright © TCG 2006-2013 24088 24089Page 289 24090October 31, 2013 24091 24092 Part 3: Commands 2409351 2409452 2409553 2409654 2409755 2409856 2409957 2410058 2410159 2410260 2410361 2410462 2410563 2410664 2410765 2410866 2410967 2411068 2411169 2411270 2411371 2411472 2411573 2411674 2411775 2411876 2411977 2412078 24121 24122Trusted Platform Module Library 24123 24124// add policyRef 24125CryptUpdateDigest2B(&hashState, &in->policyRef.b); 24126// complete hash 24127CryptCompleteHash2B(&hashState, &authHash.b); 24128// re-compute TPMT_TK_VERIFIED 24129TicketComputeVerified(in->checkTicket.hierarchy, &authHash, 24130&in->keySign, &ticket); 24131// Compare ticket digest. If not match, return error 24132if(!Memory2BEqual(&in->checkTicket.digest.b, &ticket.digest.b)) 24133return TPM_RC_VALUE+ RC_PolicyAuthorize_checkTicket; 24134} 24135// Internal Data Update 24136// Set policyDigest to zero digest 24137MemorySet(session->u2.policyDigest.t.buffer, 0, 24138session->u2.policyDigest.t.size); 24139// Update policyDigest 24140PolicyContextUpdate(TPM_CC_PolicyAuthorize, &in->keySign, &in->policyRef, 24141NULL, 0, session); 24142return TPM_RC_SUCCESS; 24143} 24144 24145Page 290 24146October 31, 2013 24147 24148Published 24149Copyright © TCG 2006-2013 24150 24151Family “2.0” 24152Level 00 Revision 00.99 24153 24154 Trusted Platform Module Library 24155 24156Part 3: Commands 24157 2415825.17 TPM2_PolicyAuthValue 2415925.17.1 24160 24161General Description 24162 24163This command allows a policy to be bound to the authorization value of the authorized object. 24164When this command completes successfully, policySession→isAuthValueNeeded is SET to indicate that 24165the authValue will be included in hmacKey when the authorization HMAC is computed for this session. 24166Additionally, policySession→isPasswordNeeded will be CLEAR. 24167NOTE 24168 24169If a policy does not use this command, then the hmacKey for the authorized command would only 24170use sessionKey. If sessionKey is not present, then the hmacKey is an Empty Buffer and no HMAC 24171would be computed. 24172 24173If successful, policySession→policyDigest will be updated with 24174 24175policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyAuthValue) 24176 24177Family “2.0” 24178Level 00 Revision 00.99 24179 24180Published 24181Copyright © TCG 2006-2013 24182 24183(36) 24184 24185Page 291 24186October 31, 2013 24187 24188 Part 3: Commands 24189 2419025.17.2 24191 24192Trusted Platform Module Library 24193 24194Command and Response 24195Table 141 — TPM2_PolicyAuthValue Command 24196 24197Type 24198 24199Name 24200 24201Description 24202 24203TPMI_ST_COMMAND_TAG 24204 24205tag 24206 24207UINT32 24208 24209commandSize 24210 24211TPM_CC 24212 24213commandCode 24214 24215TPM_CC_PolicyAuthValue 24216 24217TPMI_SH_POLICY 24218 24219policySession 24220 24221handle for the policy session being extended 24222Auth Index: None 24223 24224Table 142 — TPM2_PolicyAuthValue Response 24225Type 24226 24227Name 24228 24229Description 24230 24231TPM_ST 24232 24233tag 24234 24235see clause 8 24236 24237UINT32 24238 24239responseSize 24240 24241TPM_RC 24242 24243responseCode 24244 24245Page 292 24246October 31, 2013 24247 24248Published 24249Copyright © TCG 2006-2013 24250 24251Family “2.0” 24252Level 00 Revision 00.99 24253 24254 Trusted Platform Module Library 24255 2425625.17.3 242571 242582 242593 242604 242615 242626 242637 242648 242659 2426610 2426711 2426812 2426913 2427014 2427115 2427216 2427317 2427418 2427519 2427620 2427721 2427822 2427923 2428024 2428125 2428226 2428327 2428428 2428529 2428630 2428731 2428832 2428933 2429034 2429135 2429236 2429337 24294 24295Part 3: Commands 24296 24297Detailed Actions 24298 24299#include "InternalRoutines.h" 24300#include "PolicyAuthValue_fp.h" 24301#include "Policy_spt_fp.h" 24302 24303TPM_RC 24304TPM2_PolicyAuthValue( 24305PolicyAuthValue_In 24306 24307*in 24308 24309// IN: input parameter list 24310 24311SESSION 24312TPM_CC 24313HASH_STATE 24314 24315*session; 24316commandCode = TPM_CC_PolicyAuthValue; 24317hashState; 24318 24319) 24320{ 24321 24322// Internal Data Update 24323// Get pointer to the session structure 24324session = SessionGet(in->policySession); 24325// Update policy hash 24326// policyDigestnew = hash(policyDigestold || TPM_CC_PolicyAuthValue) 24327// 24328Start hash 24329CryptStartHash(session->authHashAlg, &hashState); 24330// add old digest 24331CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 24332// add commandCode 24333CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 24334// complete the hash and get the results 24335CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 24336// update isAuthValueNeeded bit in the session context 24337session->attributes.isAuthValueNeeded = SET; 24338session->attributes.isPasswordNeeded = CLEAR; 24339return TPM_RC_SUCCESS; 24340} 24341 24342Family “2.0” 24343Level 00 Revision 00.99 24344 24345Published 24346Copyright © TCG 2006-2013 24347 24348Page 293 24349October 31, 2013 24350 24351 Part 3: Commands 24352 24353Trusted Platform Module Library 24354 2435525.18 TPM2_PolicyPassword 2435625.18.1 24357 24358General Description 24359 24360This command allows a policy to be bound to the authorization value of the authorized object. 24361When this command completes successfully, policySession→isPasswordNeeded is SET to indicate that 24362authValue of the authorized object will be checked when the session is used for authorization. The caller 24363will provide the authValue in clear text in the hmac parameter of the authorization. The comparison of 24364hmac to authValue is performed as if the authorization is a password. 24365NOTE 1 24366 24367The parameter field in the policy session where the authorization value is provided is called hmac. If 24368TPM2_PolicyPassword() is part of the sequence, then the field will contain a password and not an 24369HMAC. 24370 24371If successful, policySession→policyDigest will be updated with 24372 24373policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyAuthValue) 24374NOTE 2 24375 24376(37) 24377 24378This is the same extend value as used with TPM2_PolicyAuthValue so that the evaluation may be 24379done using either an HMAC or a password with no change to the authPolicy of the object. The 24380reason that two commands are present is to indicate to the TPM if the hmac field in the authorization 24381will contain an HMAC or a password value. 24382 24383When this command is successful, policySession→isAuthValueNeeded will be CLEAR. 24384 24385Page 294 24386October 31, 2013 24387 24388Published 24389Copyright © TCG 2006-2013 24390 24391Family “2.0” 24392Level 00 Revision 00.99 24393 24394 Trusted Platform Module Library 24395 2439625.18.2 24397 24398Part 3: Commands 24399 24400Command and Response 24401Table 143 — TPM2_PolicyPassword Command 24402 24403Type 24404 24405Name 24406 24407Description 24408 24409TPMI_ST_COMMAND_TAG 24410 24411tag 24412 24413UINT32 24414 24415commandSize 24416 24417TPM_CC 24418 24419commandCode 24420 24421TPM_CC_PolicyPassword 24422 24423TPMI_SH_POLICY 24424 24425policySession 24426 24427handle for the policy session being extended 24428Auth Index: None 24429 24430Table 144 — TPM2_PolicyPassword Response 24431Type 24432 24433Name 24434 24435Description 24436 24437TPM_ST 24438 24439tag 24440 24441see clause 8 24442 24443UINT32 24444 24445responseSize 24446 24447TPM_RC 24448 24449responseCode 24450 24451Family “2.0” 24452Level 00 Revision 00.99 24453 24454Published 24455Copyright © TCG 2006-2013 24456 24457Page 295 24458October 31, 2013 24459 24460 Part 3: Commands 24461 2446225.18.3 244631 244642 244653 244664 244675 244686 244697 244708 244719 2447210 2447311 2447412 2447513 2447614 2447715 2447816 2447917 2448018 2448119 2448220 2448321 2448422 2448523 2448624 2448725 2448826 2448927 2449028 2449129 2449230 2449331 2449432 2449533 2449634 2449735 2449836 2449937 24500 24501Trusted Platform Module Library 24502 24503Detailed Actions 24504 24505#include "InternalRoutines.h" 24506#include "PolicyPassword_fp.h" 24507#include "Policy_spt_fp.h" 24508 24509TPM_RC 24510TPM2_PolicyPassword( 24511PolicyPassword_In 24512 24513*in 24514 24515// IN: input parameter list 24516 24517SESSION 24518TPM_CC 24519HASH_STATE 24520 24521*session; 24522commandCode = TPM_CC_PolicyAuthValue; 24523hashState; 24524 24525) 24526{ 24527 24528// Internal Data Update 24529// Get pointer to the session structure 24530session = SessionGet(in->policySession); 24531// Update policy hash 24532// policyDigestnew = hash(policyDigestold || TPM_CC_PolicyAuthValue) 24533// Start hash 24534CryptStartHash(session->authHashAlg, &hashState); 24535// add old digest 24536CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 24537// add commandCode 24538CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 24539// complete the digest 24540CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 24541// Update isPasswordNeeded bit 24542session->attributes.isPasswordNeeded = SET; 24543session->attributes.isAuthValueNeeded = CLEAR; 24544return TPM_RC_SUCCESS; 24545} 24546 24547Page 296 24548October 31, 2013 24549 24550Published 24551Copyright © TCG 2006-2013 24552 24553Family “2.0” 24554Level 00 Revision 00.99 24555 24556 Trusted Platform Module Library 24557 24558Part 3: Commands 24559 2456025.19 TPM2_PolicyGetDigest 2456125.19.1 24562 24563General Description 24564 24565This command returns the current policyDigest of the session. This command allows the TPM to be used 24566to perform the actions required to pre-compute the authPolicy for an object. 24567 24568Family “2.0” 24569Level 00 Revision 00.99 24570 24571Published 24572Copyright © TCG 2006-2013 24573 24574Page 297 24575October 31, 2013 24576 24577 Part 3: Commands 24578 2457925.19.2 24580 24581Trusted Platform Module Library 24582 24583Command and Response 24584Table 145 — TPM2_PolicyGetDigest Command 24585 24586Type 24587 24588Name 24589 24590Description 24591 24592TPMI_ST_COMMAND_TAG 24593 24594tag 24595 24596UINT32 24597 24598commandSize 24599 24600TPM_CC 24601 24602commandCode 24603 24604TPM_CC_PolicyGetDigest 24605 24606TPMI_SH_POLICY 24607 24608policySession 24609 24610handle for the policy session 24611Auth Index: None 24612 24613Table 146 — TPM2_PolicyGetDigest Response 24614Type 24615 24616Name 24617 24618Description 24619 24620TPM_ST 24621 24622tag 24623 24624see clause 8 24625 24626UINT32 24627 24628responseSize 24629 24630TPM_RC 24631 24632responseCode 24633 24634TPM2B_DIGEST 24635 24636policyDigest 24637 24638Page 298 24639October 31, 2013 24640 24641the current value of the policySession→policyDigest 24642 24643Published 24644Copyright © TCG 2006-2013 24645 24646Family “2.0” 24647Level 00 Revision 00.99 24648 24649 Trusted Platform Module Library 24650 2465125.19.3 246521 246532 246543 246554 246565 246576 246587 246598 246609 2466110 2466211 2466312 2466413 2466514 2466615 2466716 2466817 2466918 2467019 24671 24672Part 3: Commands 24673 24674Detailed Actions 24675 24676#include "InternalRoutines.h" 24677#include "PolicyGetDigest_fp.h" 24678 24679TPM_RC 24680TPM2_PolicyGetDigest( 24681PolicyGetDigest_In 24682PolicyGetDigest_Out 24683 24684*in, 24685*out 24686 24687// IN: input parameter list 24688// OUT: output parameter list 24689 24690) 24691{ 24692SESSION 24693 24694*session; 24695 24696// Command Output 24697// Get pointer to the session structure 24698session = SessionGet(in->policySession); 24699out->policyDigest = session->u2.policyDigest; 24700return TPM_RC_SUCCESS; 24701} 24702 24703Family “2.0” 24704Level 00 Revision 00.99 24705 24706Published 24707Copyright © TCG 2006-2013 24708 24709Page 299 24710October 31, 2013 24711 24712 Part 3: Commands 24713 24714Trusted Platform Module Library 24715 2471625.20 TPM2_PolicyNvWritten 2471725.20.1 24718 24719General Description 24720 24721This command allows a policy to be bound to the TPMA_NV_WRITTEN attributes. This is a deferred 24722assertion. Values are stored in the policy session context and checked when the policy is used for 24723authorization. 24724If policySession→checkNVWritten is CLEAR, it is SET and policySession→nvWrittenState is set to 24725writtenSet. 24726If policySession→checkNVWritten is SET, the TPM will return TPM_RC_VALUE if 24727policySession→nvWrittenState and writtenSet are not the same. 24728If the TPM does not return and error, it will update policySession→policyDigest by 24729 24730policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyNvWritten || writtenSet) 24731 24732(38) 24733 24734When the policy session is used to authorize a command, the TPM will fail the command if 24735policySession→checkNVWritten is SET and nvIndex→attributes→TPMA_NV_WRITTEN does not match 24736policySession→nvWrittenState. 24737NOTE 24738 24739A typical use case is a simple policy for the first write during manufacturing provisioning that would 24740require TPMA_NV_WRITTEN CLEAR and a more complex policy for later use that would require 24741TPMA_NV_WRITTEN SET. 24742 24743Page 300 24744October 31, 2013 24745 24746Published 24747Copyright © TCG 2006-2013 24748 24749Family “2.0” 24750Level 00 Revision 00.99 24751 24752 Trusted Platform Module Library 24753 2475425.20.2 24755 24756Part 3: Commands 24757 24758Command and Response 24759Table 147 — TPM2_PolicyNvWritten Command 24760 24761Type 24762 24763Name 24764 24765Description 24766 24767TPMI_ST_COMMAND_TAG 24768 24769Tag 24770 24771UINT32 24772 24773commandSize 24774 24775TPM_CC 24776 24777commandCode 24778 24779TPM_CC_PolicyNVWritten 24780 24781TPMI_SH_POLICY 24782 24783policySession 24784 24785handle for the policy session being extended 24786Auth Index: None 24787 24788TPMI_YES_NO 24789 24790writtenSet 24791 24792YES if NV Index is required to have been written 24793NO if NV Index is required not to have been written 24794 24795Table 148 — TPM2_PolicyNvWritten Response 24796Type 24797 24798Name 24799 24800Description 24801 24802TPM_ST 24803 24804Tag 24805 24806see clause 8 24807 24808UINT32 24809 24810responseSize 24811 24812TPM_RC 24813 24814responseCode 24815 24816Family “2.0” 24817Level 00 Revision 00.99 24818 24819Published 24820Copyright © TCG 2006-2013 24821 24822Page 301 24823October 31, 2013 24824 24825 Part 3: Commands 24826 2482725.20.3 248281 248292 24830 24831Trusted Platform Module Library 24832 24833Detailed Actions 24834 24835#include "InternalRoutines.h" 24836#include "PolicyNvWritten_fp.h" 24837 24838Make an NV Index policy dependent on the state of the TPMA_NV_WRITTEN attribute of the index. 24839Error Returns 24840TPM_RC_VALUE 248413 248424 248435 248446 248457 248468 248479 2484810 2484911 2485012 2485113 2485214 2485315 2485416 2485517 2485618 2485719 2485820 2485921 2486022 2486123 2486224 2486325 2486426 2486527 2486628 2486729 2486830 2486931 2487032 2487133 2487234 2487335 2487436 2487537 2487638 2487739 2487840 2487941 2488042 2488143 2488244 2488345 2488446 2488547 2488648 2488749 2488850 2488951 2489052 24891 24892Meaning 24893a conflicting request for the attribute has already been processed 24894 24895TPM_RC 24896TPM2_PolicyNvWritten( 24897PolicyNvWritten_In 24898 24899*in 24900 24901// IN: input parameter list 24902 24903) 24904{ 24905SESSION 24906TPM_CC 24907HASH_STATE 24908 24909*session; 24910commandCode = TPM_CC_PolicyNvWritten; 24911hashState; 24912 24913// Input Validation 24914// Get pointer to the session structure 24915session = SessionGet(in->policySession); 24916// If already set is this a duplicate (the same setting)? If it 24917// is a conflicting setting, it is an error 24918if(session->attributes.checkNvWritten == SET) 24919{ 24920if(( 24921(session->attributes.nvWrittenState == SET) 24922!= (in->writtenSet == YES))) 24923return TPM_RC_VALUE + RC_PolicyNvWritten_writtenSet; 24924} 24925// Internal Data Update 24926// Set session attributes so that the NV Index needs to be checked 24927session->attributes.checkNvWritten = SET; 24928session->attributes.nvWrittenState = (in->writtenSet == YES); 24929// Update policy hash 24930// policyDigestnew = hash(policyDigestold || TPM_CC_PolicyNvWritten 24931// 24932|| writtenSet) 24933// Start hash 24934CryptStartHash(session->authHashAlg, &hashState); 24935// add old digest 24936CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 24937// add commandCode 24938CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 24939// add the byte of writtenState 24940CryptUpdateDigestInt(&hashState, sizeof(TPMI_YES_NO), &in->writtenSet); 24941// complete the digest 24942CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 24943return TPM_RC_SUCCESS; 24944} 24945 24946Page 302 24947October 31, 2013 24948 24949Published 24950Copyright © TCG 2006-2013 24951 24952Family “2.0” 24953Level 00 Revision 00.99 24954 24955 Trusted Platform Module Library 24956 24957Family “2.0” 24958Level 00 Revision 00.99 24959 24960Part 3: Commands 24961 24962Published 24963Copyright © TCG 2006-2013 24964 24965Page 303 24966October 31, 2013 24967 24968 Part 3: Commands 24969 2497026 24971 24972Trusted Platform Module Library 24973 24974Hierarchy Commands 24975 2497626.1 24977 24978TPM2_CreatePrimary 24979 2498026.1.1 General Description 24981This command is used to create a Primary Object under one of the Primary Seeds or a Temporary Object 24982under TPM_RH_NULL. The command uses a TPM2B_PUBLIC as a template for the object to be created. 24983The command will create and load a Primary Object. The sensitive area is not returned. 24984NOTE: 24985 24986Since the sensitive data is not returned, the key cannot be reloaded. 24987persistent or it can be recreated. 24988 24989It can either be made 24990 24991Any type of object and attributes combination that is allowed by TPM2_Create() may be created by this 24992command. The constraints on templates and parameters are the same as TPM2_Create() except that a 24993Primary Storage Key and a Temporary Storage Key are not constrained to use the algorithms of their 24994parents. 24995For setting of the attributes of the created object, fixedParent, fixedTPM, userWithAuth, adminWithPolicy, 24996encrypt, and restricted are implied to be SET in the parent (a Permanent Handle). The remaining 24997attributes are implied to be CLEAR. 24998The TPM will derive the object from the Primary Seed indicated in primaryHandle using an approved 24999KDF. All of the bits of the template are used in the creation of the Primary Key. Methods for creating a 25000Primary Object from a Primary Seed are described in Part 1 of this specification and implemented in Part 250014. 25002If this command is called multiple times with the same inPublic parameter, inSensitive.data, and Primary 25003Seed, the TPM shall produce the same Primary Object. 25004NOTE 25005 25006If the Primary Seed is changed, the Primary Objects generated with the new seed shall be 25007statistically unique even if the parameters of the call are the same. 25008 25009This command requires authorization. Authorization for a Primary Object attached to the Platform Primary 25010Seed (PPS) shall be provided by platformAuth or platformPolicy. Authorization for a Primary Object 25011attached to the Storage Primary Seed (SPS) shall be provided by ownerAuth or ownerPolicy. 25012Authorization for a Primary Key attached to the Endorsement Primary Seed (EPS) shall be provided by 25013endorsementAuth or endorsementPolicy. 25014 25015Page 304 25016October 31, 2013 25017 25018Published 25019Copyright © TCG 2006-2013 25020 25021Family “2.0” 25022Level 00 Revision 00.99 25023 25024 Trusted Platform Module Library 25025 25026Part 3: Commands 25027 2502826.1.2 Command and Response 25029Table 149 — TPM2_CreatePrimary Command 25030Type 25031 25032Name 25033 25034Description 25035 25036TPMI_ST_COMMAND_TAG 25037 25038tag 25039 25040UINT32 25041 25042commandSize 25043 25044TPM_CC 25045 25046commandCode 25047 25048TPM_CC_CreatePrimary 25049 25050TPMI_RH_HIERARCHY+ 25051 25052@primaryHandle 25053 25054TPM_RH_ENDORSEMENT, TPM_RH_OWNER, 25055TPM_RH_PLATFORM+{PP}, or TPM_RH_NULL 25056Auth Index: 1 25057Auth Role: USER 25058 25059TPM2B_SENSITIVE_CREATE 25060 25061inSensitive 25062 25063the sensitive data, see Part 1 Sensitive Values 25064 25065TPM2B_PUBLIC 25066 25067inPublic 25068 25069the public template 25070 25071TPM2B_DATA 25072 25073outsideInfo 25074 25075data that will be included in the creation data for this 25076object to provide permanent, verifiable linkage between 25077this object and some object owner data 25078 25079TPML_PCR_SELECTION 25080 25081creationPCR 25082 25083PCR that will be used in creation data 25084 25085Table 150 — TPM2_CreatePrimary Response 25086Type 25087 25088Name 25089 25090Description 25091 25092TPM_ST 25093 25094tag 25095 25096see clause 8 25097 25098UINT32 25099 25100responseSize 25101 25102TPM_RC 25103 25104responseCode 25105 25106TPM_HANDLE 25107 25108objectHandle 25109 25110Handle for created Primary Object 25111 25112TPM2B_PUBLIC 25113 25114outPublic 25115 25116the public portion of the created object 25117 25118TPM2B_CREATION_DATA 25119 25120creationData 25121 25122contains a TPMT_CREATION_DATA 25123 25124TPM2B_DIGEST 25125 25126creationHash 25127 25128digest of creationData using nameAlg of outPublic 25129 25130TPMT_TK_CREATION 25131 25132creationTicket 25133 25134ticket used by TPM2_CertifyCreation() to validate that 25135the creation data was produced by the TPM 25136 25137TPM2B_NAME 25138 25139name 25140 25141the name of the created object 25142 25143Family “2.0” 25144Level 00 Revision 00.99 25145 25146Published 25147Copyright © TCG 2006-2013 25148 25149Page 305 25150October 31, 2013 25151 25152 Part 3: Commands 25153 25154Trusted Platform Module Library 25155 2515626.1.3 Detailed Actions 251571 251582 251593 251604 25161 25162#include 25163#include 25164#include 25165#include 25166 25167"InternalRoutines.h" 25168"CreatePrimary_fp.h" 25169"Object_spt_fp.h" 25170<Platform.h> 25171 25172Error Returns 25173TPM_RC_ATTRIBUTES 25174 25175sensitiveDataOrigin is CLEAR when 'sensitive. data' is an Empty 25176Buffer, or is SET when 'sensitive. data' is not empty; fixedTPM, 25177fixedParent, or encryptedDuplication attributes are inconsistent 25178between themselves or with those of the parent object; inconsistent 25179restricted, decrypt and sign attributes; attempt to inject sensitive data 25180for an asymmetric key; attempt to create a symmetric cipher key that 25181is not a decryption key 25182 25183TPM_RC_KDF 25184 25185incorrect KDF specified for decrypting keyed hash object 25186 25187TPM_RC_OBJECT_MEMORY 25188 25189there is no free slot for the object 25190 25191TPM_RC_SCHEME 25192 25193inconsistent attributes decrypt, sign, restricted and key's scheme ID; 25194or hash algorithm is inconsistent with the scheme ID for keyed hash 25195object 25196 25197TPM_RC_SIZE 25198 25199size of public auth policy or sensitive auth value does not match 25200digest size of the name algorithm sensitive data size for the keyed 25201hash object is larger than is allowed for the scheme 25202 25203TPM_RC_SYMMETRIC 25204 25205a storage key with no symmetric algorithm specified; or non-storage 25206key with symmetric algorithm different from TPM_ALG_NULL 25207 25208TPM_RC_TYPE 252095 252106 252117 252128 252139 2521410 2521511 2521612 2521713 2521814 2521915 2522016 2522117 2522218 2522319 2522420 2522521 2522622 2522723 2522824 2522925 2523026 2523127 2523228 2523329 2523430 2523531 2523632 2523733 25238 25239Meaning 25240 25241unknown object type; 25242 25243TPM_RC 25244TPM2_CreatePrimary( 25245CreatePrimary_In 25246CreatePrimary_Out 25247) 25248{ 25249// Local variables 25250TPM_RC 25251TPMT_SENSITIVE 25252 25253*in, 25254*out 25255 25256// IN: input parameter list 25257// OUT: output parameter list 25258 25259result = TPM_RC_SUCCESS; 25260sensitive; 25261 25262// Input Validation 25263// The sensitiveDataOrigin attribute must be consistent with the setting of 25264// the size of the data object in inSensitive. 25265if( 25266(in->inPublic.t.publicArea.objectAttributes.sensitiveDataOrigin == SET) 25267!= (in->inSensitive.t.sensitive.data.t.size == 0 )) 25268// Mismatch between the object attributes and the parameter. 25269return TPM_RC_ATTRIBUTES + RC_CreatePrimary_inSensitive; 25270// Check attributes in input public area. TPM_RC_ATTRIBUTES, TPM_RC_KDF, 25271// TPM_RC_SCHEME, TPM_RC_SIZE, TPM_RC_SYMMETRIC, or TPM_RC_TYPE error may 25272// be returned at this point. 25273result = PublicAttributesValidation(FALSE, in->primaryHandle, 25274&in->inPublic.t.publicArea); 25275if(result != TPM_RC_SUCCESS) 25276return RcSafeAddToResult(result, RC_CreatePrimary_inPublic); 25277// Validate the sensitive area values 25278if( MemoryRemoveTrailingZeros(&in->inSensitive.t.sensitive.userAuth) 25279> CryptGetHashDigestSize(in->inPublic.t.publicArea.nameAlg)) 25280 25281Page 306 25282October 31, 2013 25283 25284Published 25285Copyright © TCG 2006-2013 25286 25287Family “2.0” 25288Level 00 Revision 00.99 25289 25290 Trusted Platform Module Library 2529134 2529235 2529336 2529437 2529538 2529639 2529740 2529841 2529942 2530043 2530144 2530245 2530346 2530447 2530548 2530649 2530750 2530851 2530952 2531053 2531154 2531255 2531356 2531457 2531558 2531659 2531760 2531861 2531962 2532063 2532164 2532265 2532366 2532467 2532568 2532669 25327 25328Part 3: Commands 25329 25330return TPM_RC_SIZE + RC_CreatePrimary_inSensitive; 25331// Command output 25332// Generate Primary Object 25333// The primary key generation process uses the Name of the input public 25334// template to compute the key. The keys are generated from the template 25335// before anything in the template is allowed to be changed. 25336// A TPM_RC_KDF, TPM_RC_SIZE error may be returned at this point 25337result = CryptCreateObject(in->primaryHandle, &in->inPublic.t.publicArea, 25338&in->inSensitive.t.sensitive,&sensitive); 25339if(result != TPM_RC_SUCCESS) 25340return result; 25341// Fill in creation data 25342FillInCreationData(in->primaryHandle, in->inPublic.t.publicArea.nameAlg, 25343&in->creationPCR, &in->outsideInfo, &out->creationData, 25344&out->creationHash); 25345// Copy public area 25346out->outPublic = in->inPublic; 25347// Fill in private area for output 25348ObjectComputeName(&(out->outPublic.t.publicArea), &out->name); 25349// Compute creation ticket 25350TicketComputeCreation(EntityGetHierarchy(in->primaryHandle), &out->name, 25351&out->creationHash, &out->creationTicket); 25352// Create a internal object. A TPM_RC_OBJECT_MEMORY error may be returned 25353// at this point. 25354result = ObjectLoad(in->primaryHandle, &in->inPublic.t.publicArea, &sensitive, 25355&out->name, in->primaryHandle, TRUE, &out->objectHandle); 25356return result; 25357} 25358 25359Family “2.0” 25360Level 00 Revision 00.99 25361 25362Published 25363Copyright © TCG 2006-2013 25364 25365Page 307 25366October 31, 2013 25367 25368 Part 3: Commands 25369 2537026.2 25371 25372Trusted Platform Module Library 25373 25374TPM2_HierarchyControl 25375 2537626.2.1 General Description 25377This command enables and disables use of a hierarchy and its associated NV storage. The command 25378allows phEnable, phEnableNV, shEnable, and ehEnable to be changed when the proper authorization is 25379provided. 25380This command may be used to CLEAR phEnable and phEnableNV if platformAuth/platformPolicy is 25381provided. phEnable may not be SET using this command. 25382This command may be used to CLEAR shEnable if either platformAuth/platformPolicy 25383ownerAuth/ownerPolicy is provided. shEnable may be SET if platformAuth/platformPolicy is provided. 25384 25385or 25386 25387This command may be used to CLEAR ehEnable if either platformAuth/platformPolicy or 25388endorsementAuth/endorsementPolicy is provided. ehEnable may be SET if platformAuth/platformPolicy is 25389provided. 25390When this command is used to CLEAR phEnable, shEnable, or ehEnable, the TPM will disable use of 25391any persistent entity associated with the disabled hierarchy and will flush any transient objects associated 25392with the disabled hierarchy. 25393When this command is used to CLEAR shEnable, the TPM will disable access to any NV index that has 25394TPMA_NV_PLATFORMCREATE CLEAR (indicating that the NV Index was defined using ownerAuth). As 25395long as shEnable is CLEAR, the TPM will return an error in response to any command that attempts to 25396operate upon an NV index that has TPMA_NV_PLATFORMCREATE CLEAR. 25397When this command is used to CLEAR phEnableNV, the TPM will disable access to any NV index that 25398has TPMA_NV_PLATFORMCREATE SET (indicating that the NV Index was defined using platformAuth). 25399As long as phEnableNV is CLEAR, the TPM will return an error in response to any command that 25400attempts to operate upon an NV index that has TPMA_NV_PLATFORMCREATE SET. 25401 25402Page 308 25403October 31, 2013 25404 25405Published 25406Copyright © TCG 2006-2013 25407 25408Family “2.0” 25409Level 00 Revision 00.99 25410 25411 Trusted Platform Module Library 25412 25413Part 3: Commands 25414 2541526.2.2 Command and Response 25416Table 151 — TPM2_HierarchyControl Command 25417Type 25418 25419Name 25420 25421Description 25422 25423TPMI_ST_COMMAND_TAG 25424 25425tag 25426 25427UINT32 25428 25429commandSize 25430 25431TPM_CC 25432 25433commandCode 25434 25435TPM_CC_HierarchyControl {NV E} 25436 25437TPMI_RH_HIERARCHY 25438 25439@authHandle 25440 25441TPM_RH_ENDORSEMENT, TPM_RH_OWNER or 25442TPM_RH_PLATFORM+{PP} 25443Auth Index: 1 25444Auth Role: USER 25445 25446TPMI_RH_ENABLES 25447 25448enable 25449 25450the enable being modified 25451TPM_RH_ENDORSEMENT, TPM_RH_OWNER, 25452TPM_RH_PLATFORM, or TPM_RH_PLATFORM_NV 25453 25454TPMI_YES_NO 25455 25456state 25457 25458YES if the enable should be SET, NO if the enable 25459should be CLEAR 25460 25461Table 152 — TPM2_HierarchyControl Response 25462Type 25463 25464Name 25465 25466Description 25467 25468TPM_ST 25469 25470tag 25471 25472see clause 8 25473 25474UINT32 25475 25476responseSize 25477 25478TPM_RC 25479 25480responseCode 25481 25482Family “2.0” 25483Level 00 Revision 00.99 25484 25485Published 25486Copyright © TCG 2006-2013 25487 25488Page 309 25489October 31, 2013 25490 25491 Part 3: Commands 25492 25493Trusted Platform Module Library 25494 2549526.2.3 Detailed Actions 254961 254972 25498 25499#include "InternalRoutines.h" 25500#include "HierarchyControl_fp.h" 25501Error Returns 25502TPM_RC_AUTH_TYPE 25503 255043 255054 255065 255076 255087 255098 255109 2551110 2551211 2551312 2551413 2551514 2551615 2551716 2551817 2551918 2552019 2552120 2552221 2552322 2552423 2552524 2552625 2552726 2552827 2552928 2553029 2553130 2553231 2553332 2553433 2553534 2553635 2553736 2553837 2553938 2554039 2554140 2554241 2554342 2554443 2554544 2554645 2554746 2554847 2554948 2555049 2555150 2555251 2555352 2555453 2555554 25556 25557Meaning 25558authHandle is not applicable to hierarchy in its current state 25559 25560TPM_RC 25561TPM2_HierarchyControl( 25562HierarchyControl_In 25563 25564*in 25565 25566// IN: input parameter list 25567 25568) 25569{ 25570TPM_RC 25571BOOL 25572BOOL 25573 25574result; 25575select = (in->state == YES); 25576*selected = NULL; 25577 25578// Input Validation 25579switch(in->enable) 25580{ 25581// Platform hierarchy has to be disabled by platform auth 25582// If the platform hierarchy has already been disabled, only a reboot 25583// can enable it again 25584case TPM_RH_PLATFORM: 25585case TPM_RH_PLATFORM_NV: 25586if(in->authHandle != TPM_RH_PLATFORM) 25587return TPM_RC_AUTH_TYPE; 25588break; 25589// ShEnable may be disabled if PlatformAuth/PlatformPolicy or 25590// OwnerAuth/OwnerPolicy is provided. If ShEnable is disabled, then it 25591// may only be enabled if PlatformAuth/PlatformPolicy is provided. 25592case TPM_RH_OWNER: 25593if( 25594in->authHandle != TPM_RH_PLATFORM 25595&& in->authHandle != TPM_RH_OWNER) 25596return TPM_RC_AUTH_TYPE; 25597if( 25598gc.shEnable == FALSE && in->state == YES 25599&& in->authHandle != TPM_RH_PLATFORM) 25600return TPM_RC_AUTH_TYPE; 25601break; 25602// EhEnable may be disabled if either PlatformAuth/PlatformPolicy or 25603// EndosementAuth/EndorsementPolicy is provided. If EhEnable is disabled, 25604// then it may only be enabled if PlatformAuth/PlatformPolicy is 25605// provided. 25606case TPM_RH_ENDORSEMENT: 25607if( 25608in->authHandle != TPM_RH_PLATFORM 25609&& in->authHandle != TPM_RH_ENDORSEMENT) 25610return TPM_RC_AUTH_TYPE; 25611if( 25612gc.ehEnable == FALSE && in->state == YES 25613&& in->authHandle != TPM_RH_PLATFORM) 25614return TPM_RC_AUTH_TYPE; 25615break; 25616default: 25617pAssert(FALSE); 25618break; 25619} 25620// Internal Data Update 25621 25622Page 310 25623October 31, 2013 25624 25625Published 25626Copyright © TCG 2006-2013 25627 25628Family “2.0” 25629Level 00 Revision 00.99 25630 25631 Trusted Platform Module Library 2563255 2563356 2563457 2563558 2563659 2563760 2563861 2563962 2564063 2564164 2564265 2564366 2564467 2564568 2564669 2564770 2564871 2564972 2565073 2565174 2565275 2565376 2565477 2565578 2565679 2565780 2565881 2565982 2566083 2566184 2566285 2566386 2566487 2566588 2566689 2566790 2566891 2566992 2567093 2567194 2567295 2567396 2567497 2567598 2567699 25677100 25678101 25679102 25680103 25681104 25682105 25683106 25684107 25685 25686Part 3: Commands 25687 25688// Enable or disable the selected hierarchy 25689// Note: the authorization processing for this command may keep these 25690// command actions from being executed. For example, if phEnable is 25691// CLEAR, then platformAuth cannot be used for authorization. This 25692// means that would not be possible to use platformAuth to change the 25693// state of phEnable from CLEAR to SET. 25694// If it is decided that platformPolicy can still be used when phEnable 25695// is CLEAR, then this code could SET phEnable when proper platform 25696// policy is provided. 25697switch(in->enable) 25698{ 25699case TPM_RH_OWNER: 25700selected = &gc.shEnable; 25701break; 25702case TPM_RH_ENDORSEMENT: 25703selected = &gc.ehEnable; 25704break; 25705case TPM_RH_PLATFORM: 25706selected = &g_phEnable; 25707break; 25708case TPM_RH_PLATFORM_NV: 25709selected = &gc.phEnableNV; 25710break; 25711default: 25712pAssert(FALSE); 25713break; 25714} 25715if(selected != NULL && *selected != select) 25716{ 25717// Before changing the internal state, make sure that NV is available. 25718// Only need to update NV if changing the orderly state 25719if(gp.orderlyState != SHUTDOWN_NONE) 25720{ 25721// The command needs NV update. Check if NV is available. 25722// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 25723// this point 25724result = NvIsAvailable(); 25725if(result != TPM_RC_SUCCESS) 25726return result; 25727} 25728// state is changing and NV is available so modify 25729*selected = select; 25730// If a hierarchy was just disabled, flush it 25731if(select == CLEAR && in->enable != TPM_RH_PLATFORM_NV) 25732// Flush hierarchy 25733ObjectFlushHierarchy(in->enable); 25734// orderly state should be cleared because of the update to state clear data 25735// This gets processed in ExecuteCommand() on the way out. 25736g_clearOrderly = TRUE; 25737} 25738return TPM_RC_SUCCESS; 25739} 25740 25741Family “2.0” 25742Level 00 Revision 00.99 25743 25744Published 25745Copyright © TCG 2006-2013 25746 25747Page 311 25748October 31, 2013 25749 25750 Part 3: Commands 25751 2575226.3 25753 25754Trusted Platform Module Library 25755 25756TPM2_SetPrimaryPolicy 25757 2575826.3.1 General Description 25759This command allows setting of the authorization policy for the platform hierarchy (platformPolicy), the 25760storage hierarchy (ownerPolicy), and the endorsement hierarchy (endorsementPolicy). 25761The command requires an authorization session. The session shall use the current authValue or satisfy 25762the current authPolicy for the referenced hierarchy. 25763The policy that is changed is the policy associated with authHandle. 25764If the enable associated with authHandle is not SET, then the associated authorization values (authValue 25765or authPolicy) may not be used. 25766 25767Page 312 25768October 31, 2013 25769 25770Published 25771Copyright © TCG 2006-2013 25772 25773Family “2.0” 25774Level 00 Revision 00.99 25775 25776 Trusted Platform Module Library 25777 25778Part 3: Commands 25779 2578026.3.2 Command and Response 25781Table 153 — TPM2_SetPrimaryPolicy Command 25782Type 25783 25784Name 25785 25786Description 25787 25788TPMI_ST_COMMAND_TAG 25789 25790tag 25791 25792UINT32 25793 25794commandSize 25795 25796TPM_CC 25797 25798commandCode 25799 25800TPM_CC_SetPrimaryPolicy {NV} 25801 25802TPMI_RH_HIERARCHY 25803 25804@authHandle 25805 25806TPM_RH_ENDORSEMENT, TPM_RH_OWNER or 25807TPM_RH_PLATFORM+{PP} 25808Auth Index: 1 25809Auth Role: USER 25810 25811TPM2B_DIGEST 25812 25813authPolicy 25814 25815an authorization policy digest; may be the Empty Buffer 25816If hashAlg is TPM_ALG_NULL, then this shall be an 25817Empty Buffer. 25818 25819TPMI_ALG_HASH+ 25820 25821hashAlg 25822 25823the hash algorithm to use for the policy 25824If the authPolicy is an Empty Buffer, then this field shall 25825be TPM_ALG_NULL. 25826 25827Table 154 — TPM2_SetPrimaryPolicy Response 25828Type 25829 25830Name 25831 25832Description 25833 25834TPM_ST 25835 25836tag 25837 25838see clause 8 25839 25840UINT32 25841 25842responseSize 25843 25844TPM_RC 25845 25846responseCode 25847 25848Family “2.0” 25849Level 00 Revision 00.99 25850 25851Published 25852Copyright © TCG 2006-2013 25853 25854Page 313 25855October 31, 2013 25856 25857 Part 3: Commands 25858 25859Trusted Platform Module Library 25860 2586126.3.3 Detailed Actions 258621 258632 25864 25865#include "InternalRoutines.h" 25866#include "SetPrimaryPolicy_fp.h" 25867Error Returns 25868TPM_RC_SIZE 25869 258703 258714 258725 258736 258747 258758 258769 2587710 2587811 2587912 2588013 2588114 2588215 2588316 2588417 2588518 2588619 2588720 2588821 2588922 2589023 2589124 2589225 2589326 2589427 2589528 2589629 2589730 2589831 2589932 2590033 2590134 2590235 2590336 2590437 2590538 2590639 2590740 2590841 2590942 2591043 2591144 2591245 2591346 2591447 2591548 2591649 2591750 2591851 2591952 2592053 2592154 25922 25923Meaning 25924size of input authPolicy is not consistent with input hash algorithm 25925 25926TPM_RC 25927TPM2_SetPrimaryPolicy( 25928SetPrimaryPolicy_In 25929 25930*in 25931 25932// IN: input parameter list 25933 25934) 25935{ 25936TPM_RC 25937 25938result; 25939 25940// Input Validation 25941// Check the authPolicy consistent with hash algorithm 25942if( 25943in->authPolicy.t.size != 0 25944&& in->authPolicy.t.size != CryptGetHashDigestSize(in->hashAlg)) 25945return TPM_RC_SIZE + RC_SetPrimaryPolicy_authPolicy; 25946// The command need NV update for OWNER and ENDORSEMENT hierarchy, and 25947// might need orderlyState update for PLATFROM hierarchy. 25948// Check if NV is available. A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE 25949// error may be returned at this point 25950result = NvIsAvailable(); 25951if(result != TPM_RC_SUCCESS) 25952return result; 25953// Internal Data Update 25954// Set hierarchy policy 25955switch(in->authHandle) 25956{ 25957case TPM_RH_OWNER: 25958gp.ownerAlg = in->hashAlg; 25959gp.ownerPolicy = in->authPolicy; 25960NvWriteReserved(NV_OWNER_ALG, &gp.ownerAlg); 25961NvWriteReserved(NV_OWNER_POLICY, &gp.ownerPolicy); 25962break; 25963case TPM_RH_ENDORSEMENT: 25964gp.endorsementAlg = in->hashAlg; 25965gp.endorsementPolicy = in->authPolicy; 25966NvWriteReserved(NV_ENDORSEMENT_ALG, &gp.endorsementAlg); 25967NvWriteReserved(NV_ENDORSEMENT_POLICY, &gp.endorsementPolicy); 25968break; 25969case TPM_RH_PLATFORM: 25970gc.platformAlg = in->hashAlg; 25971gc.platformPolicy = in->authPolicy; 25972// need to update orderly state 25973g_clearOrderly = TRUE; 25974break; 25975default: 25976pAssert(FALSE); 25977break; 25978} 25979return TPM_RC_SUCCESS; 25980} 25981 25982Page 314 25983October 31, 2013 25984 25985Published 25986Copyright © TCG 2006-2013 25987 25988Family “2.0” 25989Level 00 Revision 00.99 25990 25991 Trusted Platform Module Library 25992 2599326.4 25994 25995Part 3: Commands 25996 25997TPM2_ChangePPS 25998 2599926.4.1 General Description 26000This replaces the current PPS with a value from the RNG and sets platformPolicy to the default 26001initialization value (the Empty Buffer). 26002NOTE 1 26003 26004A policy that is the Empty Buffer can match no policy. 26005 26006NOTE 2 26007 26008platformAuth is not changed. 26009 26010All loaded transient and persistent objects in the Platform hierarchy are flushed. 26011Saved contexts in the Platform hierarchy that were created under the old PPS will no longer be able to be 26012loaded. 26013The policy hash algorithm for PCR is reset to TPM_ALG_NULL. 26014This command does not clear any NV Index values. 26015NOTE 3 26016 26017Index values belonging to the Platform are preserved because the indexes may have configuration 26018information that will be the same after the PPS changes. The Platform may remove the indexes that 26019are no longer needed using TPM2_NV_UndefineSpace(). 26020 26021This command requires platformAuth. 26022 26023Family “2.0” 26024Level 00 Revision 00.99 26025 26026Published 26027Copyright © TCG 2006-2013 26028 26029Page 315 26030October 31, 2013 26031 26032 Part 3: Commands 26033 26034Trusted Platform Module Library 26035 2603626.4.2 Command and Response 26037Table 155 — TPM2_ChangePPS Command 26038Type 26039 26040Name 26041 26042TPMI_ST_COMMAND_TAG 26043 26044tag 26045 26046UINT32 26047 26048commandSize 26049 26050TPM_CC 26051 26052commandCode 26053 26054TPM_CC_ChangePPS {NV E} 26055 26056TPMI_RH_PLATFORM 26057 26058@authHandle 26059 26060TPM_RH_PLATFORM+{PP} 26061Auth Index: 1 26062Auth Role: USER 26063 26064Description 26065 26066Table 156 — TPM2_ChangePPS Response 26067Type 26068 26069Name 26070 26071Description 26072 26073TPM_ST 26074 26075tag 26076 26077see clause 8 26078 26079UINT32 26080 26081responseSize 26082 26083TPM_RC 26084 26085responseCode 26086 26087Page 316 26088October 31, 2013 26089 26090Published 26091Copyright © TCG 2006-2013 26092 26093Family “2.0” 26094Level 00 Revision 00.99 26095 26096 Trusted Platform Module Library 26097 26098Part 3: Commands 26099 2610026.4.3 Detailed Actions 261011 261022 261033 261044 261055 261066 261077 261088 261099 2611010 2611111 2611212 2611313 2611414 2611515 2611616 2611717 2611818 2611919 2612020 2612121 2612222 2612323 2612424 2612525 2612626 2612727 2612828 2612929 2613030 2613131 2613232 2613333 2613434 2613535 2613636 2613737 2613838 2613939 2614040 2614141 2614242 2614343 2614444 2614545 2614646 2614747 2614848 2614949 2615050 2615151 2615252 2615353 2615454 26155 26156#include "InternalRoutines.h" 26157#include "ChangePPS_fp.h" 26158 26159TPM_RC 26160TPM2_ChangePPS( 26161ChangePPS_In 26162 26163*in 26164 26165// IN: input parameter list 26166 26167) 26168{ 26169UINT32 26170TPM_RC 26171 26172i; 26173result; 26174 26175// Check if NV is available. A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE 26176// error may be returned at this point 26177result = NvIsAvailable(); 26178if(result != TPM_RC_SUCCESS) return result; 26179// Input parameter is not reference in command action 26180in = NULL; 26181// Internal Data Update 26182// Reset platform hierarchy seed from RNG 26183CryptGenerateRandom(PRIMARY_SEED_SIZE, gp.PPSeed.t.buffer); 26184// Create a new phProof value from RNG to prevent the saved platform 26185// hierarchy contexts being loaded 26186CryptGenerateRandom(PROOF_SIZE, gp.phProof.t.buffer); 26187// Set platform authPolicy to null 26188gc.platformAlg = TPM_ALG_NULL; 26189gc.platformPolicy.t.size = 0; 26190// Flush loaded object in platform hierarchy 26191ObjectFlushHierarchy(TPM_RH_PLATFORM); 26192// Flush platform evict object and index in NV 26193NvFlushHierarchy(TPM_RH_PLATFORM); 26194// Save hierarchy changes to NV 26195NvWriteReserved(NV_PP_SEED, &gp.PPSeed); 26196NvWriteReserved(NV_PH_PROOF, &gp.phProof); 26197// Re-initialize PCR policies 26198for(i = 0; i < NUM_POLICY_PCR_GROUP; i++) 26199{ 26200gp.pcrPolicies.hashAlg[i] = TPM_ALG_NULL; 26201gp.pcrPolicies.policy[i].t.size = 0; 26202} 26203NvWriteReserved(NV_PCR_POLICIES, &gp.pcrPolicies); 26204// orderly state should be cleared because of the update to state clear data 26205g_clearOrderly = TRUE; 26206return TPM_RC_SUCCESS; 26207} 26208 26209Family “2.0” 26210Level 00 Revision 00.99 26211 26212Published 26213Copyright © TCG 2006-2013 26214 26215Page 317 26216October 31, 2013 26217 26218 Part 3: Commands 26219 2622026.5 26221 26222Trusted Platform Module Library 26223 26224TPM2_ChangeEPS 26225 2622626.5.1 General Description 26227This replaces the current EPS with a value from the RNG and sets the Endorsement hierarchy controls to 26228their default initialization values: ehEnable is SET, endorsementAuth and endorsementPolicy both equal 26229to the Empty Buffer. It will flush any loaded objects in the EPS hierarchy and not allow objects in the 26230hierarchy associated with the previous EPS to be loaded. 26231NOTE 26232 26233In the reference implementation, ehProof is a non-volatile value from the RNG. It is allowed that the 26234ehProof be generated by a KDF using both the EPS and SPS as inputs. If generated with a KDF, the 26235ehProof can be generated on an as-needed basis or made a non-volatile value. 26236 26237This command requires platformAuth. 26238 26239Page 318 26240October 31, 2013 26241 26242Published 26243Copyright © TCG 2006-2013 26244 26245Family “2.0” 26246Level 00 Revision 00.99 26247 26248 Trusted Platform Module Library 26249 26250Part 3: Commands 26251 2625226.5.2 Command and Response 26253Table 157 — TPM2_ChangeEPS Command 26254Type 26255 26256Name 26257 26258TPMI_ST_COMMAND_TAG 26259 26260tag 26261 26262UINT32 26263 26264commandSize 26265 26266TPM_CC 26267 26268commandCode 26269 26270TPM_CC_ChangeEPS {NV E} 26271 26272TPMI_RH_PLATFORM 26273 26274@authHandle 26275 26276TPM_RH_PLATFORM+{PP} 26277Auth Handle: 1 26278Auth Role: USER 26279 26280Description 26281 26282Table 158 — TPM2_ChangeEPS Response 26283Type 26284 26285Name 26286 26287Description 26288 26289TPM_ST 26290 26291tag 26292 26293see clause 8 26294 26295UINT32 26296 26297responseSize 26298 26299TPM_RC 26300 26301responseCode 26302 26303Family “2.0” 26304Level 00 Revision 00.99 26305 26306Published 26307Copyright © TCG 2006-2013 26308 26309Page 319 26310October 31, 2013 26311 26312 Part 3: Commands 26313 26314Trusted Platform Module Library 26315 2631626.5.3 Detailed Actions 263171 263182 263193 263204 263215 263226 263237 263248 263259 2632610 2632711 2632812 2632913 2633014 2633115 2633216 2633317 2633418 2633519 2633620 2633721 2633822 2633923 2634024 2634125 2634226 2634327 2634428 2634529 2634630 2634731 2634832 2634933 2635034 2635135 2635236 2635337 2635438 2635539 2635640 2635741 2635842 2635943 2636044 2636145 2636246 2636347 2636448 2636549 2636650 2636751 2636852 2636953 2637054 2637155 2637256 26373 26374#include "InternalRoutines.h" 26375#include "ChangeEPS_fp.h" 26376 26377TPM_RC 26378TPM2_ChangeEPS( 26379ChangeEPS_In 26380 26381*in 26382 26383// IN: input parameter list 26384 26385) 26386{ 26387TPM_RC 26388 26389result; 26390 26391// The command needs NV update. Check if NV is available. 26392// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 26393// this point 26394result = NvIsAvailable(); 26395if(result != TPM_RC_SUCCESS) return result; 26396// Input parameter is not reference in command action 26397in = NULL; 26398// Internal Data Update 26399// Reset endorsement hierarchy seed from RNG 26400CryptGenerateRandom(PRIMARY_SEED_SIZE, gp.EPSeed.t.buffer); 26401// Create new ehProof value from RNG 26402CryptGenerateRandom(PROOF_SIZE, gp.ehProof.t.buffer); 26403// Enable endorsement hierarchy 26404gc.ehEnable = TRUE; 26405// set authValue buffer to zeros 26406MemorySet(gp.endorsementAuth.t.buffer, 0, gp.endorsementAuth.t.size); 26407// Set endorsement authValue to null 26408gp.endorsementAuth.t.size = 0; 26409// Set endorsement authPolicy to null 26410gp.endorsementAlg = TPM_ALG_NULL; 26411gp.endorsementPolicy.t.size = 0; 26412// Flush loaded object in endorsement hierarchy 26413ObjectFlushHierarchy(TPM_RH_ENDORSEMENT); 26414// Flush evict object of endorsement hierarchy stored in NV 26415NvFlushHierarchy(TPM_RH_ENDORSEMENT); 26416// Save hierarchy changes to NV 26417NvWriteReserved(NV_EP_SEED, &gp.EPSeed); 26418NvWriteReserved(NV_EH_PROOF, &gp.ehProof); 26419NvWriteReserved(NV_ENDORSEMENT_AUTH, &gp.endorsementAuth); 26420NvWriteReserved(NV_ENDORSEMENT_ALG, &gp.endorsementAlg); 26421NvWriteReserved(NV_ENDORSEMENT_POLICY, &gp.endorsementPolicy); 26422// orderly state should be cleared because of the update to state clear data 26423g_clearOrderly = TRUE; 26424return TPM_RC_SUCCESS; 26425} 26426 26427Page 320 26428October 31, 2013 26429 26430Published 26431Copyright © TCG 2006-2013 26432 26433Family “2.0” 26434Level 00 Revision 00.99 26435 26436 Trusted Platform Module Library 26437 2643826.6 26439 26440Part 3: Commands 26441 26442TPM2_Clear 26443 2644426.6.1 General Description 26445This command removes all TPM context associated with a specific Owner. 26446The clear operation will: 26447 26448 26449flush loaded objects (persistent and volatile) in the Storage and Endorsement hierarchies; 26450 26451 26452 26453delete any NV Index with TPMA_NV_PLATFORMCREATE == CLEAR; 26454 26455 26456 26457change the SPS to a new value from the TPM’s random number generator (RNG), 26458 26459 26460 26461change shProof and ehProof, 26462NOTE 26463 26464The proof values may be set from the RNG or derived from the associated new Primary Seed. If 26465derived from the Primary Seeds, the derivation of ehProof shall use both the SPS and EPS. The 26466computation shall use the SPS as an HMAC key and the derived value may then be a parameter 26467in a second HMAC in which the EPS is the HMAC key. The reference design uses values from 26468the RNG. 26469 26470 26471 26472SET shEnable and ehEnable; 26473 26474 26475 26476set ownerAuth, endorsementAuth, and lockoutAuth to the Empty Buffer; 26477 26478 26479 26480set ownerPolicy and endorsementPolicy to the Empty Buffer; 26481 26482 26483 26484set Clock to zero; 26485 26486 26487 26488set resetCount to zero; 26489 26490 26491 26492set restartCount to zero; and 26493 26494 26495 26496set Safe to YES. 26497 26498This command requires platformAuth or lockoutAuth. If TPM2_ClearControl() has disabled this command, 26499the TPM shall return TPM_RC_DISABLED. 26500If this command is authorized using lockoutAuth, the HMAC in the response shall use the new 26501lockoutAuth value (that is, the Empty Buffer) when computing response HMAC. 26502 26503Family “2.0” 26504Level 00 Revision 00.99 26505 26506Published 26507Copyright © TCG 2006-2013 26508 26509Page 321 26510October 31, 2013 26511 26512 Part 3: Commands 26513 26514Trusted Platform Module Library 26515 2651626.6.2 Command and Response 26517Table 159 — TPM2_Clear Command 26518Type 26519 26520Name 26521 26522TPMI_ST_COMMAND_TAG 26523 26524tag 26525 26526UINT32 26527 26528commandSize 26529 26530TPM_CC 26531 26532commandCode 26533 26534TPM_CC_Clear {NV E} 26535 26536TPMI_RH_CLEAR 26537 26538@authHandle 26539 26540TPM_RH_LOCKOUT or TPM_RH_PLATFORM+{PP} 26541Auth Handle: 1 26542Auth Role: USER 26543 26544Description 26545 26546Table 160 — TPM2_Clear Response 26547Type 26548 26549Name 26550 26551Description 26552 26553TPM_ST 26554 26555tag 26556 26557see clause 8 26558 26559UINT32 26560 26561responseSize 26562 26563TPM_RC 26564 26565responseCode 26566 26567Page 322 26568October 31, 2013 26569 26570Published 26571Copyright © TCG 2006-2013 26572 26573Family “2.0” 26574Level 00 Revision 00.99 26575 26576 Trusted Platform Module Library 26577 26578Part 3: Commands 26579 2658026.6.3 Detailed Actions 265811 265822 26583 26584#include "InternalRoutines.h" 26585#include "Clear_fp.h" 26586Error Returns 26587TPM_RC_DISABLED 26588 265893 265904 265915 265926 265937 265948 265959 2659610 2659711 2659812 2659913 2660014 2660115 2660216 2660317 2660418 2660519 2660620 2660721 2660822 2660923 2661024 2661125 2661226 2661327 2661428 2661529 2661630 2661731 2661832 2661933 2662034 2662135 2662236 2662337 2662438 2662539 2662640 2662741 2662842 2662943 2663044 2663145 2663246 2663347 2663448 2663549 2663650 2663751 2663852 2663953 2664054 26641 26642Meaning 26643Clear command has been disabled 26644 26645TPM_RC 26646TPM2_Clear( 26647Clear_In 26648 26649*in 26650 26651// IN: input parameter list 26652 26653) 26654{ 26655TPM_RC 26656 26657result; 26658 26659// Input parameter is not reference in command action 26660in = NULL; 26661// The command needs NV update. Check if NV is available. 26662// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 26663// this point 26664result = NvIsAvailable(); 26665if(result != TPM_RC_SUCCESS) return result; 26666// Input Validation 26667// If Clear command is disabled, return an error 26668if(gp.disableClear) 26669return TPM_RC_DISABLED; 26670// Internal Data Update 26671// Reset storage hierarchy seed from RNG 26672CryptGenerateRandom(PRIMARY_SEED_SIZE, gp.SPSeed.t.buffer); 26673// Create new shProof and ehProof value from RNG 26674CryptGenerateRandom(PROOF_SIZE, gp.shProof.t.buffer); 26675CryptGenerateRandom(PROOF_SIZE, gp.ehProof.t.buffer); 26676// Enable storage and endorsement hierarchy 26677gc.shEnable = gc.ehEnable = TRUE; 26678// set the authValue buffers to zero 26679MemorySet(gp.ownerAuth.t.buffer, 0, gp.ownerAuth.t.size); 26680MemorySet(gp.endorsementAuth.t.buffer, 0, gp.endorsementAuth.t.size); 26681MemorySet(gp.lockoutAuth.t.buffer, 0, gp.lockoutAuth.t.size); 26682// Set storage, endorsement and lockout authValue to null 26683gp.ownerAuth.t.size = gp.endorsementAuth.t.size = gp.lockoutAuth.t.size = 0; 26684// Set storage and endorsement authPolicy to null 26685gp.ownerAlg = gp.endorsementAlg = TPM_ALG_NULL; 26686gp.ownerPolicy.t.size = gp.endorsementPolicy.t.size = 0; 26687// Flush loaded object in storage and endorsement hierarchy 26688ObjectFlushHierarchy(TPM_RH_OWNER); 26689ObjectFlushHierarchy(TPM_RH_ENDORSEMENT); 26690// Flush owner and endorsement object and owner index in NV 26691NvFlushHierarchy(TPM_RH_OWNER); 26692NvFlushHierarchy(TPM_RH_ENDORSEMENT); 26693 26694Family “2.0” 26695Level 00 Revision 00.99 26696 26697Published 26698Copyright © TCG 2006-2013 26699 26700Page 323 26701October 31, 2013 26702 26703 Part 3: Commands 2670455 2670556 2670657 2670758 2670859 2670960 2671061 2671162 2671263 2671364 2671465 2671566 2671667 2671768 2671869 2671970 2672071 2672172 2672273 2672374 2672475 2672576 2672677 2672778 2672879 2672980 2673081 2673182 2673283 2673384 2673485 2673586 2673687 2673788 26738 26739Trusted Platform Module Library 26740 26741// Save hierarchy changes to NV 26742NvWriteReserved(NV_SP_SEED, &gp.SPSeed); 26743NvWriteReserved(NV_SH_PROOF, &gp.shProof); 26744NvWriteReserved(NV_EH_PROOF, &gp.ehProof); 26745NvWriteReserved(NV_OWNER_AUTH, &gp.ownerAuth); 26746NvWriteReserved(NV_ENDORSEMENT_AUTH, &gp.endorsementAuth); 26747NvWriteReserved(NV_LOCKOUT_AUTH, &gp.lockoutAuth); 26748NvWriteReserved(NV_OWNER_ALG, &gp.ownerAlg); 26749NvWriteReserved(NV_ENDORSEMENT_ALG, &gp.endorsementAlg); 26750NvWriteReserved(NV_OWNER_POLICY, &gp.ownerPolicy); 26751NvWriteReserved(NV_ENDORSEMENT_POLICY, &gp.endorsementPolicy); 26752// Initialize dictionary attack parameters 26753DAPreInstall_Init(); 26754// Reset clock 26755go.clock = 0; 26756go.clockSafe = YES; 26757// Update the DRBG state whenever writing orderly state to NV 26758CryptDrbgGetPutState(GET_STATE); 26759NvWriteReserved(NV_ORDERLY_DATA, &go); 26760// Reset counters 26761gp.resetCount = gr.restartCount = gr.clearCount = 0; 26762gp.auditCounter = 0; 26763NvWriteReserved(NV_RESET_COUNT, &gp.resetCount); 26764NvWriteReserved(NV_AUDIT_COUNTER, &gp.auditCounter); 26765// orderly state should be cleared because of the update to state clear data 26766g_clearOrderly = TRUE; 26767return TPM_RC_SUCCESS; 26768} 26769 26770Page 324 26771October 31, 2013 26772 26773Published 26774Copyright © TCG 2006-2013 26775 26776Family “2.0” 26777Level 00 Revision 00.99 26778 26779 Trusted Platform Module Library 26780 2678126.7 26782 26783Part 3: Commands 26784 26785TPM2_ClearControl 26786 2678726.7.1 General Description 26788TPM2_ClearControl() disables and enables the execution of TPM2_Clear(). 26789The TPM will SET the TPM’s TPMA_PERMANENT.disableClear attribute if disable is YES and will 26790CLEAR the attribute if disable is NO. When the attribute is SET, TPM2_Clear() may not be executed. 26791NOTE 26792 26793This is to simplify the logic of TPM2_Clear(). TPM2_ClearControl() can be called using platformAuth 26794to CLEAR the disableClear attribute and then execute TPM2_Clear(). 26795 26796LockoutAuth may be used to SET disableClear but not to CLEAR it. 26797PlatformAuth may be used to SET or CLEAR disableClear. 26798 26799Family “2.0” 26800Level 00 Revision 00.99 26801 26802Published 26803Copyright © TCG 2006-2013 26804 26805Page 325 26806October 31, 2013 26807 26808 Part 3: Commands 26809 26810Trusted Platform Module Library 26811 2681226.7.2 Command and Response 26813Table 161 — TPM2_ClearControl Command 26814Type 26815 26816Name 26817 26818Description 26819 26820TPMI_ST_COMMAND_TAG 26821 26822tag 26823 26824UINT32 26825 26826commandSize 26827 26828TPM_CC 26829 26830commandCode 26831 26832TPM_CC_ClearControl {NV} 26833 26834TPMI_RH_CLEAR 26835 26836@auth 26837 26838TPM_RH_LOCKOUT or TPM_RH_PLATFORM+{PP} 26839Auth Handle: 1 26840Auth Role: USER 26841 26842TPMI_YES_NO 26843 26844disable 26845 26846YES if the disableOwnerClear flag is to be SET, NO if 26847the flag is to be CLEAR. 26848 26849Table 162 — TPM2_ClearControl Response 26850Type 26851 26852Name 26853 26854Description 26855 26856TPM_ST 26857 26858tag 26859 26860see clause 8 26861 26862UINT32 26863 26864responseSize 26865 26866TPM_RC 26867 26868responseCode 26869 26870Page 326 26871October 31, 2013 26872 26873Published 26874Copyright © TCG 2006-2013 26875 26876Family “2.0” 26877Level 00 Revision 00.99 26878 26879 Trusted Platform Module Library 26880 26881Part 3: Commands 26882 2688326.7.3 Detailed Actions 268841 268852 26886 26887#include "InternalRoutines.h" 26888#include "ClearControl_fp.h" 26889Error Returns 26890TPM_RC_AUTH_FAIL 26891 268923 268934 268945 268956 268967 268978 268989 2689910 2690011 2690112 2690213 2690314 2690415 2690516 2690617 2690718 2690819 2690920 2691021 2691122 2691223 2691324 2691425 2691526 2691627 2691728 2691829 2691930 2692031 2692132 2692233 26923 26924Meaning 26925authorization is not properly given 26926 26927TPM_RC 26928TPM2_ClearControl( 26929ClearControl_In 26930 26931*in 26932 26933// IN: input parameter list 26934 26935) 26936{ 26937TPM_RC 26938 26939result; 26940 26941// The command needs NV update. Check if NV is available. 26942// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 26943// this point 26944result = NvIsAvailable(); 26945if(result != TPM_RC_SUCCESS) return result; 26946// Input Validation 26947// LockoutAuth may be used to set disableLockoutClear to TRUE but not to FALSE 26948if(in->auth == TPM_RH_LOCKOUT && in->disable == NO) 26949return TPM_RC_AUTH_FAIL; 26950// Internal Data Update 26951if(in->disable == YES) 26952gp.disableClear = TRUE; 26953else 26954gp.disableClear = FALSE; 26955// Record the change to NV 26956NvWriteReserved(NV_DISABLE_CLEAR, &gp.disableClear); 26957return TPM_RC_SUCCESS; 26958} 26959 26960Family “2.0” 26961Level 00 Revision 00.99 26962 26963Published 26964Copyright © TCG 2006-2013 26965 26966Page 327 26967October 31, 2013 26968 26969 Part 3: Commands 26970 2697126.8 26972 26973Trusted Platform Module Library 26974 26975TPM2_HierarchyChangeAuth 26976 2697726.8.1 General Description 26978This command allows the authorization secret for a hierarchy or lockout to be changed using the current 26979authorization value as the command authorization. 26980If authHandle is TPM_RH_PLATFORM, then platformAuth is changed. If authHandle is 26981TPM_RH_OWNER, then ownerAuth is changed. If authHandle is TPM_RH_ENDORSEMENT, then 26982endorsementAuth is changed. If authHandle is TPM_RH_LOCKOUT, then lockoutAuth is changed. 26983If authHandle is TPM_RH_PLATFORM, then Physical Presence may need to be asserted for this 26984command to succeed (see 28.2, “TPM2_PP_Commands”). 26985The authorization value may be no larger than the digest produced by the hash algorithm used for context 26986integrity. 26987EXAMPLE 26988 26989If SHA384 is used in the computation of the integrity values for saved contexts, then the largest 26990authorization value is 48 octets. 26991 26992Page 328 26993October 31, 2013 26994 26995Published 26996Copyright © TCG 2006-2013 26997 26998Family “2.0” 26999Level 00 Revision 00.99 27000 27001 Trusted Platform Module Library 27002 27003Part 3: Commands 27004 2700526.8.2 Command and Response 27006Table 163 — TPM2_HierarchyChangeAuth Command 27007Type 27008 27009Name 27010 27011Description 27012 27013TPMI_ST_COMMAND_TAG 27014 27015tag 27016 27017UINT32 27018 27019commandSize 27020 27021TPM_CC 27022 27023commandCode 27024 27025TPM_CC_HierarchyChangeAuth {NV} 27026 27027TPMI_RH_HIERARCHY_AUTH 27028 27029@authHandle 27030 27031TPM_RH_LOCKOUT, TPM_RH_ENDORSEMENT, 27032TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 27033Auth Index: 1 27034Auth Role: USER 27035 27036TPM2B_AUTH 27037 27038newAuth 27039 27040new authorization value 27041 27042Table 164 — TPM2_HierarchyChangeAuth Response 27043Type 27044 27045Name 27046 27047Description 27048 27049TPM_ST 27050 27051tag 27052 27053see clause 8 27054 27055UINT32 27056 27057responseSize 27058 27059TPM_RC 27060 27061responseCode 27062 27063Family “2.0” 27064Level 00 Revision 00.99 27065 27066Published 27067Copyright © TCG 2006-2013 27068 27069Page 329 27070October 31, 2013 27071 27072 Part 3: Commands 27073 27074Trusted Platform Module Library 27075 2707626.8.3 Detailed Actions 270771 270782 270793 27080 27081#include "InternalRoutines.h" 27082#include "HierarchyChangeAuth_fp.h" 27083#include "Object_spt_fp.h" 27084Error Returns 27085TPM_RC_SIZE 27086 270874 270885 270896 270907 270918 270929 2709310 2709411 2709512 2709613 2709714 2709815 2709916 2710017 2710118 2710219 2710320 2710421 2710522 2710623 2710724 2710825 2710926 2711027 2711128 2711229 2711330 2711431 2711532 2711633 2711734 2711835 2711936 2712037 2712138 2712239 2712340 2712441 2712542 2712643 2712744 2712845 2712946 2713047 2713148 2713249 2713350 2713451 27135 27136Meaning 27137newAuth size is greater than that of integrity hash digest 27138 27139TPM_RC 27140TPM2_HierarchyChangeAuth( 27141HierarchyChangeAuth_In 27142 27143*in 27144 27145// IN: input parameter list 27146 27147) 27148{ 27149TPM_RC 27150 27151result; 27152 27153// The command needs NV update. Check if NV is available. 27154// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 27155// this point 27156result = NvIsAvailable(); 27157if(result != TPM_RC_SUCCESS) return result; 27158// Make sure the the auth value is a reasonable size (not larger than 27159// the size of the digest produced by the integrity hash. The integrity 27160// hash is assumed to produce the longest digest of any hash implemented 27161// on the TPM. 27162if( MemoryRemoveTrailingZeros(&in->newAuth) 27163> CryptGetHashDigestSize(CONTEXT_INTEGRITY_HASH_ALG)) 27164return TPM_RC_SIZE + RC_HierarchyChangeAuth_newAuth; 27165// Set hierarchy authValue 27166switch(in->authHandle) 27167{ 27168case TPM_RH_OWNER: 27169gp.ownerAuth = in->newAuth; 27170NvWriteReserved(NV_OWNER_AUTH, &gp.ownerAuth); 27171break; 27172case TPM_RH_ENDORSEMENT: 27173gp.endorsementAuth = in->newAuth; 27174NvWriteReserved(NV_ENDORSEMENT_AUTH, &gp.endorsementAuth); 27175break; 27176case TPM_RH_PLATFORM: 27177gc.platformAuth = in->newAuth; 27178// orderly state should be cleared 27179g_clearOrderly = TRUE; 27180break; 27181case TPM_RH_LOCKOUT: 27182gp.lockoutAuth = in->newAuth; 27183NvWriteReserved(NV_LOCKOUT_AUTH, &gp.lockoutAuth); 27184break; 27185default: 27186pAssert(FALSE); 27187break; 27188} 27189return TPM_RC_SUCCESS; 27190} 27191 27192Page 330 27193October 31, 2013 27194 27195Published 27196Copyright © TCG 2006-2013 27197 27198Family “2.0” 27199Level 00 Revision 00.99 27200 27201 Trusted Platform Module Library 27202 2720327 27204 27205Part 3: Commands 27206 27207Dictionary Attack Functions 27208 2720927.1 27210 27211Introduction 27212 27213A TPM is required to have support for logic that will help prevent a dictionary attack on an authorization 27214value. The protection is provided by a counter that increments when a password authorization or an 27215HMAC authorization fails. When the counter reaches a predefined value, the TPM will not accept, for 27216some time interval, further requests that require authorization and the TPM is in Lockout mode. While the 27217TPM is in Lockout mode, the TPM will return TPM_RC_LOCKED if the command requires use of an 27218object’s or Index’s authValue unless the authorization applies to an entry in the Platform hierarchy. 27219NOTE 27220 27221Authorizations for objects and NV Index values in the Platform hierarchy are never locked out. 27222However, a command that requires multiple authorizations will not be accepted when the TPM is in 27223Lockout mode unless all of the authorizations reference objects and indexes in the Platform 27224hierarchy. 27225 27226If the TPM is continuously powered for the duration of newRecoveryTime and no authorization failures 27227occur, the authorization failure counter will be decremented by one. This property is called “self-healing.” 27228Self-healing shall not cause the count of failed attempts to decrement below zero. 27229The count of failed attempts, the lockout interval, and self-healing interval are settable using 27230TPM2_DictionaryAttackParameters(). The lockout parameters and the current value of the lockout 27231counter can be read with TPM2_GetCapability(). 27232Dictionary attack protection does not apply to an entity associated with a permanent handle (handle type 27233== TPM_HT_PERMANENT). 2723427.2 27235 27236TPM2_DictionaryAttackLockReset 27237 2723827.2.1 General Description 27239This command cancels the effect of a TPM lockout due to a number of successive authorization failures. 27240If this command is properly authorized, the lockout counter is set to zero. 27241Only one authorization failure is allowed for this command during a lockoutRecovery interval (set using 27242TPM2_DictionaryAttackParameters(). 27243 27244Family “2.0” 27245Level 00 Revision 00.99 27246 27247Published 27248Copyright © TCG 2006-2013 27249 27250Page 331 27251October 31, 2013 27252 27253 Part 3: Commands 27254 27255Trusted Platform Module Library 27256 2725727.2.2 Command and Response 27258Table 165 — TPM2_DictionaryAttackLockReset Command 27259Type 27260 27261Name 27262 27263TPMI_ST_COMMAND_TAG 27264 27265tag 27266 27267UINT32 27268 27269commandSize 27270 27271TPM_CC 27272 27273commandCode 27274 27275TPM_CC_DictionaryAttackLockReset {NV} 27276 27277TPMI_RH_LOCKOUT 27278 27279@lockHandle 27280 27281TPM_RH_LOCKOUT 27282Auth Index: 1 27283Auth Role: USER 27284 27285Description 27286 27287Table 166 — TPM2_DictionaryAttackLockReset Response 27288Type 27289 27290Name 27291 27292Description 27293 27294TPM_ST 27295 27296tag 27297 27298see clause 8 27299 27300UINT32 27301 27302responseSize 27303 27304TPM_RC 27305 27306responseCode 27307 27308Page 332 27309October 31, 2013 27310 27311Published 27312Copyright © TCG 2006-2013 27313 27314Family “2.0” 27315Level 00 Revision 00.99 27316 27317 Trusted Platform Module Library 27318 27319Part 3: Commands 27320 2732127.2.3 Detailed Actions 273221 273232 273243 273254 273265 273276 273287 273298 273309 2733110 2733211 2733312 2733413 2733514 2733615 2733716 2733817 2733918 2734019 2734120 2734221 2734322 2734423 2734524 2734625 2734726 2734827 2734928 27350 27351#include "InternalRoutines.h" 27352#include "DictionaryAttackLockReset_fp.h" 27353 27354TPM_RC 27355TPM2_DictionaryAttackLockReset( 27356DictionaryAttackLockReset_In 27357 27358*in 27359 27360// IN: input parameter list 27361 27362) 27363{ 27364TPM_RC 27365 27366result; 27367 27368// Input parameter is not reference in command action 27369in = NULL; 27370// The command needs NV update. Check if NV is available. 27371// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 27372// this point 27373result = NvIsAvailable(); 27374if(result != TPM_RC_SUCCESS) return result; 27375// Internal Data Update 27376// Set failed tries to 0 27377gp.failedTries = 0; 27378// Record the changes to NV 27379NvWriteReserved(NV_FAILED_TRIES, &gp.failedTries); 27380return TPM_RC_SUCCESS; 27381} 27382 27383Family “2.0” 27384Level 00 Revision 00.99 27385 27386Published 27387Copyright © TCG 2006-2013 27388 27389Page 333 27390October 31, 2013 27391 27392 Part 3: Commands 27393 2739427.3 27395 27396Trusted Platform Module Library 27397 27398TPM2_DictionaryAttackParameters 27399 2740027.3.1 General Description 27401This command changes the lockout parameters. 27402The command requires lockoutAuth. 27403The timeout parameters (newRecoveryTime and lockoutRecovery) indicate values that are measured with 27404respect to the Time and not Clock. 27405NOTE 27406 27407Use of Time means that the TPM shall be continuously powered for the duration of a timeout. 27408 27409If newRecoveryTime is zero, then DA protection is disabled. Authorizations are checked but authorization 27410failures will not cause the TPM to enter lockout. 27411If newMaxTries is zero, the TPM will be in lockout and use of DA protected entities will be disabled. 27412If lockoutRecovery is zero, then the recovery interval is a boot cycle (_TPM_Init followed by 27413Startup(CLEAR). 27414This command will set the authorization failure count (failedTries) to zero. 27415Only one authorization failure is allowed for this command during a lockoutRecovery interval. 27416 27417Page 334 27418October 31, 2013 27419 27420Published 27421Copyright © TCG 2006-2013 27422 27423Family “2.0” 27424Level 00 Revision 00.99 27425 27426 Trusted Platform Module Library 27427 27428Part 3: Commands 27429 2743027.3.2 Command and Response 27431Table 167 — TPM2_DictionaryAttackParameters Command 27432Type 27433 27434Name 27435 27436Description 27437 27438TPMI_ST_COMMAND_TAG 27439 27440tag 27441 27442UINT32 27443 27444commandSize 27445 27446TPM_CC 27447 27448commandCode 27449 27450TPM_CC_DictionaryAttackParameters {NV} 27451 27452TPMI_RH_LOCKOUT 27453 27454@lockHandle 27455 27456TPM_RH_LOCKOUT 27457Auth Index: 1 27458Auth Role: USER 27459 27460UINT32 27461 27462newMaxTries 27463 27464count of authorization failures before the lockout is 27465imposed 27466 27467UINT32 27468 27469newRecoveryTime 27470 27471time in seconds before the authorization failure count 27472is automatically decremented 27473A value of zero indicates that DA protection is 27474disabled. 27475 27476UINT32 27477 27478lockoutRecovery 27479 27480time in seconds after a lockoutAuth failure before use 27481of lockoutAuth is allowed 27482A value of zero indicates that a reboot is required. 27483 27484Table 168 — TPM2_DictionaryAttackParameters Response 27485Type 27486 27487Name 27488 27489Description 27490 27491TPM_ST 27492 27493tag 27494 27495see clause 8 27496 27497UINT32 27498 27499responseSize 27500 27501TPM_RC 27502 27503responseCode 27504 27505Family “2.0” 27506Level 00 Revision 00.99 27507 27508Published 27509Copyright © TCG 2006-2013 27510 27511Page 335 27512October 31, 2013 27513 27514 Part 3: Commands 27515 27516Trusted Platform Module Library 27517 2751827.3.3 Detailed Actions 275191 275202 275213 275224 275235 275246 275257 275268 275279 2752810 2752911 2753012 2753113 2753214 2753315 2753416 2753517 2753618 2753719 2753820 2753921 2754022 2754123 2754224 2754325 2754426 2754527 2754628 2754729 2754830 2754931 2755032 2755133 27552 27553#include "InternalRoutines.h" 27554#include "DictionaryAttackParameters_fp.h" 27555 27556TPM_RC 27557TPM2_DictionaryAttackParameters( 27558DictionaryAttackParameters_In 27559 27560*in 27561 27562// IN: input parameter list 27563 27564) 27565{ 27566TPM_RC 27567 27568result; 27569 27570// The command needs NV update. Check if NV is available. 27571// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 27572// this point 27573result = NvIsAvailable(); 27574if(result != TPM_RC_SUCCESS) return result; 27575// Internal Data Update 27576// Set dictionary attack parameters 27577gp.maxTries = in->newMaxTries; 27578gp.recoveryTime = in->newRecoveryTime; 27579gp.lockoutRecovery = in->lockoutRecovery; 27580// Set failed tries to 0 27581gp.failedTries = 0; 27582// Record the changes to NV 27583NvWriteReserved(NV_FAILED_TRIES, &gp.failedTries); 27584NvWriteReserved(NV_MAX_TRIES, &gp.maxTries); 27585NvWriteReserved(NV_RECOVERY_TIME, &gp.recoveryTime); 27586NvWriteReserved(NV_LOCKOUT_RECOVERY, &gp.lockoutRecovery); 27587return TPM_RC_SUCCESS; 27588} 27589 27590Page 336 27591October 31, 2013 27592 27593Published 27594Copyright © TCG 2006-2013 27595 27596Family “2.0” 27597Level 00 Revision 00.99 27598 27599 Trusted Platform Module Library 27600 2760128 27602 27603Part 3: Commands 27604 27605Miscellaneous Management Functions 27606 2760728.1 27608 27609Introduction 27610 27611This clause contains commands that do not logically group with any other commands. 2761228.2 27613 27614TPM2_PP_Commands 27615 2761628.2.1 General Description 27617This command is used to determine which commands require assertion of Physical Presence (PP) in 27618addition to platformAuth/platformPolicy. 27619This command requires that auth is TPM_RH_PLATFORM and that Physical Presence be asserted. 27620After this command executes successfully, the commands listed in setList will be added to the list of 27621commands that require that Physical Presence be asserted when the handle associated with the 27622authorization is TPM_RH_PLATFORM. The commands in clearList will no longer require assertion of 27623Physical Presence in order to authorize a command. 27624If a command is not in either list, its state is not changed. If a command is in both lists, then it will no 27625longer require Physical Presence (for example, setList is processed first). 27626Only commands with 27627handle types of 27628TPMI_RH_PLATFORM, TPMI_RH_PROVISION, 27629TPMI_RH_CLEAR, or TPMI_RH_HIERARCHY can be gated with Physical Presence. If any other 27630command is in either list, it is discarded. 27631When a command requires that Physical Presence be provided, then Physical Presence shall be 27632asserted for either an HMAC or a Policy authorization. 27633NOTE 27634 27635Physical Presence may be made a requirement of any policy. 27636 27637TPM2_PP_Commands() always requires assertion of Physical Presence. 27638 27639Family “2.0” 27640Level 00 Revision 00.99 27641 27642Published 27643Copyright © TCG 2006-2013 27644 27645Page 337 27646October 31, 2013 27647 27648 Part 3: Commands 27649 27650Trusted Platform Module Library 27651 2765228.2.2 Command and Response 27653Table 169 — TPM2_PP_Commands Command 27654Type 27655 27656Name 27657 27658Description 27659 27660TPMI_ST_COMMAND_TAG 27661 27662tag 27663 27664UINT32 27665 27666commandSize 27667 27668TPM_CC 27669 27670commandCode 27671 27672TPM_CC_PP_Commands {NV} 27673 27674TPMI_RH_PLATFORM 27675 27676@auth 27677 27678TPM_RH_PLATFORM+PP 27679Auth Index: 1 27680Auth Role: USER + Physical Presence 27681 27682TPML_CC 27683 27684setList 27685 27686list of commands to be added to those that will require 27687that Physical Presence be asserted 27688 27689TPML_CC 27690 27691clearList 27692 27693list of commands that will no longer require that 27694Physical Presence be asserted 27695 27696Table 170 — TPM2_PP_Commands Response 27697Type 27698 27699Name 27700 27701Description 27702 27703TPM_ST 27704 27705tag 27706 27707see clause 8 27708 27709UINT32 27710 27711responseSize 27712 27713TPM_RC 27714 27715responseCode 27716 27717Page 338 27718October 31, 2013 27719 27720Published 27721Copyright © TCG 2006-2013 27722 27723Family “2.0” 27724Level 00 Revision 00.99 27725 27726 Trusted Platform Module Library 27727 27728Part 3: Commands 27729 2773028.2.3 Detailed Actions 277311 277322 277333 277344 277355 277366 277377 277388 277399 2774010 2774111 2774212 2774313 2774414 2774515 2774616 2774717 2774818 2774919 2775020 2775121 2775222 2775323 2775424 2775525 2775626 2775727 2775828 2775929 2776030 2776131 2776232 2776333 2776434 2776535 2776636 2776737 2776838 2776939 2777040 2777141 27772 27773#include "InternalRoutines.h" 27774#include "PP_Commands_fp.h" 27775 27776TPM_RC 27777TPM2_PP_Commands( 27778PP_Commands_In 27779 27780*in 27781 27782// IN: input parameter list 27783 27784) 27785{ 27786UINT32 27787TPM_RC 27788 27789i; 27790result; 27791 27792// The command needs NV update. Check if NV is available. 27793// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 27794// this point 27795result = NvIsAvailable(); 27796if(result != TPM_RC_SUCCESS) return result; 27797// Internal Data Update 27798// Process set list 27799for(i = 0; i < in->setList.count; i++) 27800// If command is implemented, set it as PP required. If the input 27801// command is not a PP command, it will be ignored at 27802// PhysicalPresenceCommandSet(). 27803if(CommandIsImplemented(in->setList.commandCodes[i])) 27804PhysicalPresenceCommandSet(in->setList.commandCodes[i]); 27805// Process clear list 27806for(i = 0; i < in->clearList.count; i++) 27807// If command is implemented, clear it as PP required. If the input 27808// command is not a PP command, it will be ignored at 27809// PhysicalPresenceCommandClear(). If the input command is 27810// TPM2_PP_Commands, it will be ignored as well 27811if(CommandIsImplemented(in->clearList.commandCodes[i])) 27812PhysicalPresenceCommandClear(in->clearList.commandCodes[i]); 27813// Save the change of PP list 27814NvWriteReserved(NV_PP_LIST, &gp.ppList); 27815return TPM_RC_SUCCESS; 27816} 27817 27818Family “2.0” 27819Level 00 Revision 00.99 27820 27821Published 27822Copyright © TCG 2006-2013 27823 27824Page 339 27825October 31, 2013 27826 27827 Part 3: Commands 27828 2782928.3 27830 27831Trusted Platform Module Library 27832 27833TPM2_SetAlgorithmSet 27834 2783528.3.1 General Description 27836This command allows the platform to change the set of algorithms that are used by the TPM. The 27837algorithmSet setting is a vendor-dependent value. 27838If the changing of the algorithm set results in a change of the algorithms of PCR banks, then the TPM will 27839need to be reset (_TPM_Init and TPM2_Startup(TPM_SU_CLEAR)) before the new PCR settings take 27840effect. After this command executes successfully, if startupType in the next TPM2_Startup() is not 27841TPM_SU_CLEAR, the TPM shall return TPM_RC_VALUE and enter Failure mode. 27842This command does not change the algorithms available to the platform. 27843NOTE 27844 27845The reference implementation does not have support for this command. In particular, it does not 27846support use of this command to selectively disable algorithms. Proper support wo uld require 27847modification of the unmarshaling code so that each time an algorithm is unmarshaled, it would be 27848verified as being enabled. 27849 27850Page 340 27851October 31, 2013 27852 27853Published 27854Copyright © TCG 2006-2013 27855 27856Family “2.0” 27857Level 00 Revision 00.99 27858 27859 Trusted Platform Module Library 27860 27861Part 3: Commands 27862 2786328.3.2 Command and Response 27864Table 171 — TPM2_SetAlgorithmSet Command 27865Type 27866 27867Name 27868 27869Description 27870 27871TPMI_ST_COMMAND_TAG 27872 27873tag 27874 27875UINT32 27876 27877commandSize 27878 27879TPM_CC 27880 27881commandCode 27882 27883TPM_CC_SetAlgorithmSet {NV} 27884 27885TPMI_RH_PLATFORM 27886 27887@authHandle 27888 27889TPM_RH_PLATFORM 27890Auth Index: 1 27891Auth Role: USER 27892 27893UINT32 27894 27895algorithmSet 27896 27897a TPM vendor-dependent value indicating the 27898algorithm set selection 27899 27900Table 172 — TPM2_SetAlgorithmSet Response 27901Type 27902 27903Name 27904 27905Description 27906 27907TPM_ST 27908 27909tag 27910 27911see clause 8 27912 27913UINT32 27914 27915responseSize 27916 27917TPM_RC 27918 27919responseCode 27920 27921Family “2.0” 27922Level 00 Revision 00.99 27923 27924Published 27925Copyright © TCG 2006-2013 27926 27927Page 341 27928October 31, 2013 27929 27930 Part 3: Commands 27931 27932Trusted Platform Module Library 27933 2793428.3.3 Detailed Actions 279351 279362 279373 279384 279395 279406 279417 279428 279439 2794410 2794511 2794612 2794713 2794814 2794915 2795016 2795117 2795218 2795319 2795420 2795521 2795622 2795723 27958 27959#include "InternalRoutines.h" 27960#include "SetAlgorithmSet_fp.h" 27961 27962TPM_RC 27963TPM2_SetAlgorithmSet( 27964SetAlgorithmSet_In 27965 27966*in 27967 27968// IN: input parameter list 27969 27970) 27971{ 27972TPM_RC 27973 27974result; 27975 27976// The command needs NV update. Check if NV is available. 27977// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 27978// this point 27979result = NvIsAvailable(); 27980if(result != TPM_RC_SUCCESS) return result; 27981// Internal Data Update 27982gp.algorithmSet = in->algorithmSet; 27983// Write the algorithm set changes to NV 27984NvWriteReserved(NV_ALGORITHM_SET, &gp.algorithmSet); 27985return TPM_RC_SUCCESS; 27986} 27987 27988Page 342 27989October 31, 2013 27990 27991Published 27992Copyright © TCG 2006-2013 27993 27994Family “2.0” 27995Level 00 Revision 00.99 27996 27997 Trusted Platform Module Library 27998 27999Part 3: Commands 28000 28001Field Upgrade 28002 2800329 2800429.1 28005 28006Introduction 28007 28008This clause contains the commands for managing field upgrade of the firmware in the TPM. The field 28009upgrade scheme may be used for replacement or augmentation of the firmware installed in the TPM. 28010EXAMPLE 1 28011 28012If an algorithm is found to be flawed, a patch of that algorithm might be installed using the firmware 28013upgrade process. The patch might be a replacement of a portion of the code or a complete 28014replacement of the firmware. 28015 28016EXAMPLE 2 28017 28018If an additional set of ECC parameters is needed, the firmware process may be used to add the 28019parameters to the TPM data set. 28020 28021The 28022field 28023upgrade 28024process 28025uses 28026two 28027commands 28028(TPM2_FieldUpgradeStart() 28029and 28030TPM2_FieldUpgradeData()). TPM2_FieldUpgradeStart() validates that a signature on the provided digest 28031is from the TPM manufacturer and that proper authorization is provided using platformPolicy. 28032NOTE 1 28033 28034The platformPolicy for field upgraded is defined by the PM and may include requirements that the 28035upgrade be signed by the PM or the TPM owner and include any other constraints that are desired 28036by the PM. 28037 28038If the proper authorization is given, the TPM will retain the signed digest and enter the Field Upgrade 28039mode (FUM). While in FUM, the TPM will accept TPM2_FieldUpgradeData() commands. It may accept 28040other commands if it is able to complete them using the previously installed firmware. Otherwise, it will 28041return TPM_RC_UPGRADE. 28042Each block of the field upgrade shall contain the digest of the next block of the field upgrade data. That 28043digest shall be included in the digest of the previous block. The digest of the first block is signed by the 28044TPM manufacturer. That signature and first block digest are the parameters for 28045TPM2_FieldUpgradeStart(). The digest is saved in the TPM as the required digest for the next field 28046upgrade data block and as the identifier of the field upgrade sequence. 28047For each field upgrade data block that is sent to the TPM by TPM2_FieldUpgradeData(), the TPM shall 28048validate that the digest matches the required digest and if not, shall return TPM_RC_VALUE. The TPM 28049shall extract the digest of the next expected block and return that value to the caller, along with the digest 28050of the first data block of the update sequence. 28051The system may attempt to abandon the firmware upgrade by using a zero-length buffer in 28052TPM2_FieldUpdateData(). If the TPM is able to resume operation using the firmware present when the 28053upgrade started, then the TPM will indicate that it has abandon the update by setting the digest of the 28054next block to the Empty Buffer. If the TPM cannot abandon the update, it will return the expected next 28055digest. 28056The system may also attempt to abandon the update because of a power interruption. If the TPM is able 28057to resume normal operations, then it will respond normally to TPM2_Startup(). If the TPM is not able to 28058resume normal operations, then it will respond to any command but TPM2_FieldUpgradeData() with 28059TPM_RC_FIELDUPGRADE. 28060After a _TPM_Init, system software may not be able to resume the field upgrade that was in process 28061when the power interruption occurred. In such case, the TPM firmware may be reset to one of two other 28062values: 28063 28064 28065the original firmware that was installed at the factory (“initial firmware”); or 28066 28067 28068 28069the firmware that was in the TPM when the field upgrade process started (“previous firmware”). 28070 28071The TPM retains the digest of the first block for these firmware images and checks to see if the first block 28072after _TPM_Init matches either of those digests. If so, the firmware update process restarts and the 28073original firmware may be loaded. 28074Family “2.0” 28075Level 00 Revision 00.99 28076 28077Published 28078Copyright © TCG 2006-2013 28079 28080Page 343 28081October 31, 2013 28082 28083 Part 3: Commands 28084NOTE 2 28085 28086Trusted Platform Module Library 28087 28088The TPM is required to accept the previous firmware as either a vendor -provided update or as 28089recovered from the TPM using TPM2_FirmwareRead(). 28090 28091When the last block of the firmware upgrade is loaded into the TPM (indicated to the TPM by data in the 28092data block in a TPM vendor-specific manner), the TPM will complete the upgrade process. If the TPM is 28093able to resume normal operations without a reboot, it will set the hash algorithm of the next block to 28094TPM_ALG_NULL and return TPM_RC_SUCCESS. If a reboot is required, the TPM shall return 28095TPM_RC_REBOOT in response to the last TPM2_FieldUpgradeData() and all subsequent TPM 28096commands until a _TPM_Init is received. 28097NOTE 3 28098 28099Because no additional data is allowed when the res ponse code is not TPM_RC_SUCCESS, the TPM 28100returns TPM_RC_SUCCESS for all calls to TPM2_FieldUpgradeData() except the last. In this 28101manner, the TPM is able to indicate the digest of the next block. If a _TPM_Init occurs while the 28102TPM is in FUM, the next block may be the digest for the first block of the original firmware. If it is 28103not, then the TPM will not accept the original firmware until the next _TPM_Init when the TPM is in 28104FUM. 28105 28106During the field upgrade process, the TPM shall preserve: 28107 28108 28109Primary Seeds; 28110 28111 28112 28113Hierarchy authValue, authPolicy, and proof values; 28114 28115 28116 28117Lockout authValue and authorization failure count values; 28118 28119 28120 28121PCR authValue and authPolicy values; 28122 28123 28124 28125NV Index allocations and contents; 28126 28127 28128 28129Persistent object allocations and contents; and 28130 28131 28132 28133Clock. 28134 28135Page 344 28136October 31, 2013 28137 28138Published 28139Copyright © TCG 2006-2013 28140 28141Family “2.0” 28142Level 00 Revision 00.99 28143 28144 Trusted Platform Module Library 28145 2814629.2 28147 28148Part 3: Commands 28149 28150TPM2_FieldUpgradeStart 28151 2815229.2.1 General Description 28153This command uses platformPolicy and a TPM Vendor Authorization Key to authorize a Field Upgrade 28154Manifest. 28155If the signature checks 28156TPM2_FieldUpgradeData(). 28157 28158succeed, 28159 28160the 28161 28162authorization 28163 28164is 28165 28166valid 28167 28168and 28169 28170the 28171 28172TPM 28173 28174will 28175 28176accept 28177 28178This signature is checked against the loaded key referenced by keyHandle. This key will have a Name 28179that is the same as a value that is part of the TPM firmware data. If the signature is not valid, the TPM 28180shall return TPM_RC_SIGNATURE. 28181NOTE 28182 28183A loaded key is used rather than a hard-coded key to reduce the amount of memory needed for this 28184key data in case more than one vendor key is needed. 28185 28186Family “2.0” 28187Level 00 Revision 00.99 28188 28189Published 28190Copyright © TCG 2006-2013 28191 28192Page 345 28193October 31, 2013 28194 28195 Part 3: Commands 28196 28197Trusted Platform Module Library 28198 2819929.2.2 Command and Response 28200Table 173 — TPM2_FieldUpgradeStart Command 28201Type 28202 28203Name 28204 28205Description 28206 28207TPMI_ST_COMMAND_TAG 28208 28209tag 28210 28211UINT32 28212 28213commandSize 28214 28215TPM_CC 28216 28217commandCode 28218 28219TPM_CC_FieldUpgradeStart 28220 28221TPMI_RH_PLATFORM 28222 28223@authorization 28224 28225TPM_RH_PLATFORM+{PP} 28226Auth Index:1 28227Auth Role: ADMIN 28228 28229TPMI_DH_OBJECT 28230 28231keyHandle 28232 28233handle of a public area that contains the TPM Vendor 28234Authorization Key that will be used to validate 28235manifestSignature 28236Auth Index: None 28237 28238TPM2B_DIGEST 28239 28240fuDigest 28241 28242digest of the first block in the field upgrade sequence 28243 28244TPMT_SIGNATURE 28245 28246manifestSignature 28247 28248signature over fuDigest using the key associated with 28249keyHandle (not optional) 28250 28251Table 174 — TPM2_FieldUpgradeStart Response 28252Type 28253 28254Name 28255 28256Description 28257 28258TPM_ST 28259 28260tag 28261 28262see clause 8 28263 28264UINT32 28265 28266responseSize 28267 28268TPM_RC 28269 28270responseCode 28271 28272Page 346 28273October 31, 2013 28274 28275Published 28276Copyright © TCG 2006-2013 28277 28278Family “2.0” 28279Level 00 Revision 00.99 28280 28281 Trusted Platform Module Library 28282 28283Part 3: Commands 28284 2828529.2.3 Detailed Actions 282861 282872 282883 282894 282905 282916 282927 282938 282949 2829510 2829611 2829712 2829813 28299 28300#include "InternalRoutines.h" 28301#include "FieldUpgradeStart_fp.h" 28302#if CC_FieldUpgradeStart == YES 28303 28304TPM_RC 28305TPM2_FieldUpgradeStart( 28306FieldUpgradeStart_In 28307 28308*in 28309 28310// IN: input parameter list 28311 28312) 28313{ 28314// Not implemented 28315UNUSED_PARAMETER(in); 28316return TPM_RC_SUCCESS; 28317} 28318#endif 28319 28320Family “2.0” 28321Level 00 Revision 00.99 28322 28323Published 28324Copyright © TCG 2006-2013 28325 28326Page 347 28327October 31, 2013 28328 28329 Part 3: Commands 28330 2833129.3 28332 28333Trusted Platform Module Library 28334 28335TPM2_FieldUpgradeData 28336 2833729.3.1 General Description 28338This command will take the actual field upgrade image to be installed on the TPM. The exact format of 28339fuData is vendor-specific. This command is only possible following a successful 28340TPM2_FieldUpgradeStart(). 28341If 28342the 28343TPM 28344has 28345not 28346received 28347a 28348properly 28349authorized 28350TPM2_FieldUpgradeStart(), then the TPM shall return TPM_RC_FIELDUPGRADE. 28351The TPM will validate that the digest of fuData matches an expected value. If so, the TPM may buffer or 28352immediately apply the update. If the digest of fuData does not match an expected value, the TPM shall 28353return TPM_RC_VALUE. 28354 28355Page 348 28356October 31, 2013 28357 28358Published 28359Copyright © TCG 2006-2013 28360 28361Family “2.0” 28362Level 00 Revision 00.99 28363 28364 Trusted Platform Module Library 28365 28366Part 3: Commands 28367 2836829.3.2 Command and Response 28369Table 175 — TPM2_FieldUpgradeData Command 28370Type 28371 28372Name 28373 28374Description 28375 28376TPMI_ST_COMMAND_TAG 28377 28378tag 28379 28380UINT32 28381 28382commandSize 28383 28384TPM_CC 28385 28386commandCode 28387 28388TPM_CC_FieldUpgradeData {NV} 28389 28390TPM2B_MAX_BUFFER 28391 28392fuData 28393 28394field upgrade image data 28395 28396Table 176 — TPM2_FieldUpgradeData Response 28397Type 28398 28399Name 28400 28401Description 28402 28403TPM_ST 28404 28405tag 28406 28407see clause 8 28408 28409UINT32 28410 28411responseSize 28412 28413TPM_RC 28414 28415responseCode 28416 28417TPMT_HA+ 28418 28419nextDigest 28420 28421tagged digest of the next block 28422TPM_ALG_NULL if field update is complete 28423 28424TPMT_HA 28425 28426firstDigest 28427 28428tagged digest of the first block of the sequence 28429 28430Family “2.0” 28431Level 00 Revision 00.99 28432 28433Published 28434Copyright © TCG 2006-2013 28435 28436Page 349 28437October 31, 2013 28438 28439 Part 3: Commands 28440 28441Trusted Platform Module Library 28442 2844329.3.3 Detailed Actions 284441 284452 284463 284474 284485 284496 284507 284518 284529 2845310 2845411 2845512 2845613 2845714 2845815 28459 28460#include "InternalRoutines.h" 28461#include "FieldUpgradeData_fp.h" 28462#if CC_FieldUpgradeData == YES 28463 28464TPM_RC 28465TPM2_FieldUpgradeData( 28466FieldUpgradeData_In 28467FieldUpgradeData_Out 28468 28469*in, 28470*out 28471 28472// IN: input parameter list 28473// OUT: output parameter list 28474 28475) 28476{ 28477// Not implemented 28478UNUSED_PARAMETER(in); 28479UNUSED_PARAMETER(out); 28480return TPM_RC_SUCCESS; 28481} 28482#endif 28483 28484Page 350 28485October 31, 2013 28486 28487Published 28488Copyright © TCG 2006-2013 28489 28490Family “2.0” 28491Level 00 Revision 00.99 28492 28493 Trusted Platform Module Library 28494 2849529.4 28496 28497Part 3: Commands 28498 28499TPM2_FirmwareRead 28500 2850129.4.1 General Description 28502This command is used to read a copy of the current firmware installed in the TPM. 28503The presumption is that the data will be returned in reverse order so that the last block in the sequence 28504would be the first block given to the TPM in case of a failure recovery. If the TPM2_FirmwareRead 28505sequence completes successfully, then the data provided from the TPM will be sufficient to allow the TPM 28506to recover from an abandoned upgrade of this firmware. 28507To start the sequence of retrieving the data, the caller sets sequenceNumber to zero. When the TPM has 28508returned all the firmware data, the TPM will return the Empty Buffer as fuData. 28509The contents of fuData are opaque to the caller. 28510NOTE 1 28511 28512The caller should retain the ordering of the update blocks so that the blocks sent to the TPM have 28513the same size and inverse order as the blocks returned by a sequence of calls to this command. 28514 28515NOTE 2 28516 28517Support for this command is optional even if the TPM implements TPM2_FieldUpgradeStart() and 28518TPM2_FieldUpgradeData(). 28519 28520Family “2.0” 28521Level 00 Revision 00.99 28522 28523Published 28524Copyright © TCG 2006-2013 28525 28526Page 351 28527October 31, 2013 28528 28529 Part 3: Commands 28530 28531Trusted Platform Module Library 28532 2853329.4.2 Command and Response 28534Table 177 — TPM2_FirmwareRead Command 28535Type 28536 28537Name 28538 28539Description 28540 28541TPMI_ST_COMMAND_TAG 28542 28543tag 28544 28545UINT32 28546 28547commandSize 28548 28549TPM_CC 28550 28551commandCode 28552 28553TPM_CC_FirmwareRead 28554 28555UINT32 28556 28557sequenceNumber 28558 28559the number of previous calls to this command in this 28560sequence 28561set to 0 on the first call 28562 28563Table 178 — TPM2_FirmwareRead Response 28564Type 28565 28566Name 28567 28568Description 28569 28570TPM_ST 28571 28572tag 28573 28574see clause 8 28575 28576UINT32 28577 28578responseSize 28579 28580TPM_RC 28581 28582responseCode 28583 28584TPM2B_MAX_BUFFER 28585 28586fuData 28587 28588Page 352 28589October 31, 2013 28590 28591field upgrade image data 28592 28593Published 28594Copyright © TCG 2006-2013 28595 28596Family “2.0” 28597Level 00 Revision 00.99 28598 28599 Trusted Platform Module Library 28600 28601Part 3: Commands 28602 2860329.4.3 Detailed Actions 286041 286052 286063 286074 286085 286096 286107 286118 286129 2861310 2861411 2861512 2861613 28617 28618#include "InternalRoutines.h" 28619#include "FirmwareRead_fp.h" 28620 28621TPM_RC 28622TPM2_FirmwareRead( 28623FirmwareRead_In 28624FirmwareRead_Out 28625 28626*in, 28627*out 28628 28629// IN: input parameter list 28630// OUT: output parameter list 28631 28632) 28633{ 28634// Not implemented 28635UNUSED_PARAMETER(in); 28636UNUSED_PARAMETER(out); 28637return TPM_RC_SUCCESS; 28638} 28639 28640Family “2.0” 28641Level 00 Revision 00.99 28642 28643Published 28644Copyright © TCG 2006-2013 28645 28646Page 353 28647October 31, 2013 28648 28649 Part 3: Commands 28650 2865130 28652 28653Trusted Platform Module Library 28654 28655Context Management 28656 2865730.1 28658 28659Introduction 28660 28661Three of the commands in this clause (TPM2_ContextSave(), TPM2_ContextLoad(), and 28662TPM2_FlushContext()) implement the resource management described in the "Context Management" 28663clause in Part 1. 28664The fourth command in this clause (TPM2_EvictControl()) is used to control the persistence of a loadable 28665objects in TPM memory. Background for this command may be found in the "Owner and Platform Evict 28666Objects" clause in Part 1. 2866730.2 28668 28669TPM2_ContextSave 28670 2867130.2.1 General Description 28672This command saves a session context, object context, or sequence object context outside the TPM. 28673No authorization sessions of any type are allowed with this command and tag is required to be 28674TPM_ST_NO_SESSIONS. 28675NOTE 28676 28677This preclusion avoids complex issues of dealing with the same session in handle and in the session 28678area. While it might be possible to provide specificity, it would add unnecessary complexity to the 28679TPM and, because this capability would provide no application benefit, use of authorization ses sions 28680for audit or encryption is prohibited. 28681 28682The TPM shall encrypt and integrity protect the context as described in the "Context Protection" clause in 28683Part 1. 28684See the “Context Data” clause in Part 2 for a description of the context structure in the response. 28685 28686Page 354 28687October 31, 2013 28688 28689Published 28690Copyright © TCG 2006-2013 28691 28692Family “2.0” 28693Level 00 Revision 00.99 28694 28695 Trusted Platform Module Library 28696 28697Part 3: Commands 28698 2869930.2.2 Command and Response 28700Table 179 — TPM2_ContextSave Command 28701Type 28702 28703Name 28704 28705Description 28706 28707TPMI_ST_COMMAND_TAG 28708 28709tag 28710 28711TPM_ST_NO_SESSIONS 28712 28713UINT32 28714 28715commandSize 28716 28717TPM_CC 28718 28719commandCode 28720 28721TPM_CC_ContextSave 28722 28723TPMI_DH_CONTEXT 28724 28725saveHandle 28726 28727handle of the resource to save 28728Auth Index: None 28729 28730Table 180 — TPM2_ContextSave Response 28731Type 28732 28733Name 28734 28735Description 28736 28737TPM_ST 28738 28739tag 28740 28741see clause 8 28742 28743UINT32 28744 28745responseSize 28746 28747TPM_RC 28748 28749responseCode 28750 28751TPMS_CONTEXT 28752 28753context 28754 28755Family “2.0” 28756Level 00 Revision 00.99 28757 28758Published 28759Copyright © TCG 2006-2013 28760 28761Page 355 28762October 31, 2013 28763 28764 Part 3: Commands 28765 28766Trusted Platform Module Library 28767 2876830.2.3 Detailed Actions 287691 287702 287713 28772 28773#include "InternalRoutines.h" 28774#include "ContextSave_fp.h" 28775#include "Context_spt_fp.h" 28776Error Returns 28777TPM_RC_CONTEXT_GAP 28778 28779a contextID could not be assigned for a session context save 28780 28781TPM_RC_TOO_MANY_CONTEXTS 287824 287835 287846 287857 287868 287879 2878810 2878911 2879012 2879113 2879214 2879315 2879416 2879517 2879618 2879719 2879820 2879921 2880022 2880123 2880224 2880325 2880426 2880527 2880628 2880729 2880830 2880931 2881032 2881133 2881234 2881335 2881436 2881537 2881638 2881739 2881840 2881941 2882042 2882143 2882244 2882345 2882446 2882547 2882648 2882749 2882850 2882951 2883052 2883153 28832 28833Meaning 28834 28835no more contexts can be saved as the counter has maxed out 28836 28837TPM_RC 28838TPM2_ContextSave( 28839ContextSave_In 28840ContextSave_Out 28841 28842*in, 28843*out 28844 28845// IN: input parameter list 28846// OUT: output parameter list 28847 28848) 28849{ 28850TPM_RC 28851UINT16 28852// blob. 28853UINT64 28854TPM2B_SYM_KEY 28855TPM2B_IV 28856 28857result; 28858fingerprintSize; 28859 28860TPM2B_DIGEST 28861UINT16 28862BYTE 28863 28864integrity; 28865integritySize; 28866*buffer; 28867 28868contextID = 0; 28869symKey; 28870iv; 28871 28872// The size of fingerprint in context 28873// session context ID 28874 28875// This command may cause the orderlyState to be cleared due to 28876// the update of state reset data. If this is the case, check if NV is 28877// available first 28878if(gp.orderlyState != SHUTDOWN_NONE) 28879{ 28880// The command needs NV update. Check if NV is available. 28881// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 28882// this point 28883result = NvIsAvailable(); 28884if(result != TPM_RC_SUCCESS) return result; 28885} 28886// Internal Data Update 28887// Initialize output handle. At the end of command action, the output 28888// handle of an object will be replaced, while the output handle 28889// for a session will be the same as input 28890out->context.savedHandle = in->saveHandle; 28891// Get the size of fingerprint in context blob. The sequence value in 28892// TPMS_CONTEXT structure is used as the fingerprint 28893fingerprintSize = sizeof(out->context.sequence); 28894// Compute the integrity size at the beginning of context blob 28895integritySize = sizeof(integrity.t.size) 28896+ CryptGetHashDigestSize(CONTEXT_INTEGRITY_HASH_ALG); 28897// Perform object or session specific context save 28898switch(HandleGetType(in->saveHandle)) 28899{ 28900case TPM_HT_TRANSIENT: 28901{ 28902 28903Page 356 28904October 31, 2013 28905 28906Published 28907Copyright © TCG 2006-2013 28908 28909Family “2.0” 28910Level 00 Revision 00.99 28911 28912 Trusted Platform Module Library 2891354 2891455 2891556 2891657 2891758 2891859 2891960 2892061 2892162 2892263 2892364 2892465 2892566 2892667 2892768 2892869 2892970 2893071 2893172 2893273 2893374 2893475 2893576 2893677 2893778 2893879 2893980 2894081 2894182 2894283 2894384 2894485 2894586 2894687 2894788 2894889 2894990 2895091 2895192 2895293 2895394 2895495 2895596 2895697 2895798 2895899 28959100 28960101 28961102 28962103 28963104 28964105 28965106 28966107 28967108 28968109 28969110 28970111 28971112 28972113 28973114 28974115 28975116 28976117 28977 28978OBJECT 28979OBJECT 28980 28981Part 3: Commands 28982 28983*object = ObjectGet(in->saveHandle); 28984*outObject = 28985(OBJECT *)(out->context.contextBlob.t.buffer 28986+ integritySize + fingerprintSize); 28987 28988// Set size of the context data. The contents of context blob is vendor 28989// defined. In this implementation, the size is size of integrity 28990// plus fingerprint plus the whole internal OBJECT structure 28991out->context.contextBlob.t.size = integritySize + 28992fingerprintSize + sizeof(*object); 28993// Copy the whole internal OBJECT structure to context blob, leave 28994// the size for fingerprint 28995*outObject = *object; 28996// Increment object context ID 28997gr.objectContextID++; 28998// If object context ID overflows, TPM should be put in failure mode 28999if(gr.objectContextID == 0) 29000FAIL(FATAL_ERROR_INTERNAL); 29001// Fill in other return values for an object. 29002out->context.sequence = gr.objectContextID; 29003// For regular object, savedHandle is 0x80000000. For sequence object, 29004// savedHandle is 0x80000001. For object with stClear, savedHandle 29005// is 0x80000002 29006if(ObjectIsSequence(object)) 29007{ 29008out->context.savedHandle = 0x80000001; 29009SequenceDataImportExport(object, outObject, EXPORT_STATE); 29010} 29011else if(object->attributes.stClear == SET) 29012{ 29013out->context.savedHandle = 0x80000002; 29014} 29015else 29016{ 29017out->context.savedHandle = 0x80000000; 29018} 29019// Get object hierarchy 29020out->context.hierarchy = ObjectDataGetHierarchy(object); 29021break; 29022} 29023case TPM_HT_HMAC_SESSION: 29024case TPM_HT_POLICY_SESSION: 29025{ 29026SESSION 29027*session = SessionGet(in->saveHandle); 29028// Set size of the context data. The contents of context blob is vendor 29029// defined. In this implementation, the size of context blob is the 29030// size of a internal session structure plus the size of 29031// fingerprint plus the size of integrity 29032out->context.contextBlob.t.size = integritySize + 29033fingerprintSize + sizeof(*session); 29034// Copy the whole internal SESSION structure to context blob. 29035// Save space for fingerprint at the beginning of the buffer 29036// This is done before anything else so that the actual context 29037// can be reclaimed after this call 29038MemoryCopy(out->context.contextBlob.t.buffer 29039+ integritySize + fingerprintSize, 29040session, sizeof(*session), 29041 29042Family “2.0” 29043Level 00 Revision 00.99 29044 29045Published 29046Copyright © TCG 2006-2013 29047 29048Page 357 29049October 31, 2013 29050 29051 Part 3: Commands 29052118 29053119 29054120 29055121 29056122 29057123 29058124 29059125 29060126 29061127 29062128 29063129 29064130 29065131 29066132 29067133 29068134 29069135 29070136 29071137 29072138 29073139 29074140 29075141 29076142 29077143 29078144 29079145 29080146 29081147 29082148 29083149 29084150 29085151 29086152 29087153 29088154 29089155 29090156 29091157 29092158 29093159 29094160 29095161 29096162 29097163 29098164 29099165 29100166 29101167 29102168 29103169 29104170 29105171 29106172 29107173 29108174 29109 29110Trusted Platform Module Library 29111sizeof(out->context.contextBlob.t.buffer) 29112- integritySize - fingerprintSize); 29113 29114// Fill in the other return parameters for a session 29115// Get a context ID and set the session tracking values appropriately 29116// TPM_RC_CONTEXT_GAP is a possible error. 29117// SessionContextSave() will flush the in-memory context 29118// so no additional errors may occur after this call. 29119result = SessionContextSave(out->context.savedHandle, &contextID); 29120if(result != TPM_RC_SUCCESS) return result; 29121// sequence number is the current session contextID 29122out->context.sequence = contextID; 29123// use TPM_RH_NULL as hierarchy for session context 29124out->context.hierarchy = TPM_RH_NULL; 29125break; 29126} 29127default: 29128// SaveContext may only take an object handle or a session handle. 29129// All the other handle type should be filtered out at unmarshal 29130pAssert(FALSE); 29131break; 29132} 29133// Save fingerprint at the beginning of encrypted area of context blob. 29134// Reserve the integrity space 29135MemoryCopy(out->context.contextBlob.t.buffer + integritySize, 29136&out->context.sequence, sizeof(out->context.sequence), 29137sizeof(out->context.contextBlob.t.buffer) - integritySize); 29138// Compute context encryption key 29139ComputeContextProtectionKey(&out->context, &symKey, &iv); 29140// Encrypt context blob 29141CryptSymmetricEncrypt(out->context.contextBlob.t.buffer + integritySize, 29142CONTEXT_ENCRYPT_ALG, CONTEXT_ENCRYPT_KEY_BITS, 29143TPM_ALG_CFB, symKey.t.buffer, &iv, 29144out->context.contextBlob.t.size - integritySize, 29145out->context.contextBlob.t.buffer + integritySize); 29146// Compute integrity hash for the object 29147// In this implementation, the same routine is used for both sessions 29148// and objects. 29149ComputeContextIntegrity(&out->context, &integrity); 29150// add integrity at the beginning of context blob 29151buffer = out->context.contextBlob.t.buffer; 29152TPM2B_DIGEST_Marshal(&integrity, &buffer, NULL); 29153// orderly state should be cleared because of the update of state reset and 29154// state clear data 29155g_clearOrderly = TRUE; 29156return TPM_RC_SUCCESS; 29157} 29158 29159Page 358 29160October 31, 2013 29161 29162Published 29163Copyright © TCG 2006-2013 29164 29165Family “2.0” 29166Level 00 Revision 00.99 29167 29168 Trusted Platform Module Library 29169 2917030.3 29171 29172Part 3: Commands 29173 29174TPM2_ContextLoad 29175 2917630.3.1 General Description 29177This command is used to reload a context that has been saved by TPM2_ContextSave(). 29178No authorization sessions of any type are allowed with this command and tag is required to be 29179TPM_ST_NO_SESSIONS (see note in 30.2.1). 29180The TPM will return TPM_RC_HIERARCHY if the context is associated with a hierarchy that is disabled. 29181NOTE 29182 29183Contexts for authorization sessions and for sequence object s belong to the NULL hierarchy which is 29184never disabled. 29185 29186See the “Context Data” clause in Part 2 for a description of the values in the context parameter. 29187If the integrity HMAC of the saved context is not valid, the TPM shall return TPM_RC_INTEGRITY. 29188The TPM shall perform a check on the decrypted context as described in the "Context Confidentiality 29189Protections" clause of Part 1 and enter failure mode if the check fails. 29190 29191Family “2.0” 29192Level 00 Revision 00.99 29193 29194Published 29195Copyright © TCG 2006-2013 29196 29197Page 359 29198October 31, 2013 29199 29200 Part 3: Commands 29201 29202Trusted Platform Module Library 29203 2920430.3.2 Command and Response 29205Table 181 — TPM2_ContextLoad Command 29206Type 29207 29208Name 29209 29210Description 29211 29212TPMI_ST_COMMAND_TAG 29213 29214tag 29215 29216TPM_ST_NO_SESSIONS 29217 29218UINT32 29219 29220commandSize 29221 29222TPM_CC 29223 29224commandCode 29225 29226TPM_CC_ContextLoad 29227 29228TPMS_CONTEXT 29229 29230context 29231 29232the context blob 29233 29234Table 182 — TPM2_ContextLoad Response 29235Type 29236 29237Name 29238 29239Description 29240 29241TPM_ST 29242 29243tag 29244 29245see clause 8 29246 29247UINT32 29248 29249responseSize 29250 29251TPM_RC 29252 29253responseCode 29254 29255TPMI_DH_CONTEXT 29256 29257loadedHandle 29258 29259Page 360 29260October 31, 2013 29261 29262the handle assigned to the resource after it has been 29263successfully loaded 29264 29265Published 29266Copyright © TCG 2006-2013 29267 29268Family “2.0” 29269Level 00 Revision 00.99 29270 29271 Trusted Platform Module Library 29272 29273Part 3: Commands 29274 2927530.3.3 Detailed Actions 292761 292772 292783 29279 29280#include "InternalRoutines.h" 29281#include "ContextLoad_fp.h" 29282#include "Context_spt_fp.h" 29283Error Returns 29284TPM_RC_CONTEXT_GAP 29285 29286there is only one available slot and this is not the oldest saved 29287session context 29288 29289TPM_RC_HANDLE 29290 29291'context. savedHandle' does not reference a saved session 29292 29293TPM_RC_HIERARCHY 29294 29295'context.hierarchy' is disabled 29296 29297TPM_RC_INTEGRITY 29298 29299context integrity check fail 29300 29301TPM_RC_OBJECT_MEMORY 29302 29303no free slot for an object 29304 29305TPM_RC_SESSION_MEMORY 29306 29307no free session slots 29308 29309TPM_RC_SIZE 293104 293115 293126 293137 293148 293159 2931610 2931711 2931812 2931913 2932014 2932115 2932216 2932317 2932418 2932519 2932620 2932721 2932822 2932923 2933024 2933125 2933226 2933327 2933428 2933529 2933630 2933731 2933832 2933933 2934034 2934135 2934236 2934337 2934438 2934539 2934640 2934741 2934842 2934943 29350 29351Meaning 29352 29353incorrect context blob size 29354 29355TPM_RC 29356TPM2_ContextLoad( 29357ContextLoad_In 29358ContextLoad_Out 29359 29360*in, 29361*out 29362 29363// IN: input parameter list 29364// OUT: output parameter list 29365 29366) 29367{ 29368// Local Variables 29369TPM_RC 29370result = TPM_RC_SUCCESS; 29371TPM2B_DIGEST 29372TPM2B_DIGEST 29373UINT16 29374UINT64 29375BYTE 29376INT32 29377 29378ingerityToCompare; 29379integrity; 29380integritySize; 29381fingerprint; 29382*buffer; 29383size; 29384 29385TPM_HT 29386TPM2B_SYM_KEY 29387TPM2B_IV 29388 29389handleType; 29390symKey; 29391iv; 29392 29393// Input Validation 29394// Check context blob size 29395handleType = HandleGetType(in->context.savedHandle); 29396// Check integrity 29397// In this implementation, the same routine is used for both sessions 29398// and objects. 29399integritySize = sizeof(integrity.t.size) 29400+ CryptGetHashDigestSize(CONTEXT_INTEGRITY_HASH_ALG); 29401// Get integrity from context blob 29402buffer = in->context.contextBlob.t.buffer; 29403size = (INT32) in->context.contextBlob.t.size; 29404result = TPM2B_DIGEST_Unmarshal(&integrity, &buffer, &size); 29405if(result != TPM_RC_SUCCESS) 29406return result; 29407// Compute context integrity 29408ComputeContextIntegrity(&in->context, &ingerityToCompare); 29409 29410Family “2.0” 29411Level 00 Revision 00.99 29412 29413Published 29414Copyright © TCG 2006-2013 29415 29416Page 361 29417October 31, 2013 29418 29419 Part 3: Commands 2942044 2942145 2942246 2942347 2942448 2942549 2942650 2942751 2942852 2942953 2943054 2943155 2943256 2943357 2943458 2943559 2943660 2943761 2943862 2943963 2944064 2944165 2944266 2944367 2944468 2944569 2944670 2944771 2944872 2944973 2945074 2945175 2945276 2945377 2945478 2945579 2945680 2945781 2945882 2945983 2946084 2946185 2946286 2946387 2946488 2946589 2946690 2946791 2946892 2946993 2947094 2947195 2947296 2947397 2947498 2947599 29476100 29477101 29478102 29479103 29480104 29481105 29482106 29483107 29484 29485Trusted Platform Module Library 29486 29487// Compare integrity 29488if(!Memory2BEqual(&integrity.b, &ingerityToCompare.b)) 29489return TPM_RC_INTEGRITY + RC_ContextLoad_context; 29490// Compute context encryption key 29491ComputeContextProtectionKey(&in->context, &symKey, &iv); 29492// Decrypt context data in place 29493CryptSymmetricDecrypt(in->context.contextBlob.t.buffer + integritySize, 29494CONTEXT_ENCRYPT_ALG, CONTEXT_ENCRYPT_KEY_BITS, 29495TPM_ALG_CFB, symKey.t.buffer, &iv, 29496in->context.contextBlob.t.size - integritySize, 29497in->context.contextBlob.t.buffer + integritySize); 29498// Read the fingerprint value, skip the leading integrity size 29499MemoryCopy(&fingerprint, in->context.contextBlob.t.buffer + integritySize, 29500sizeof(fingerprint), sizeof(fingerprint)); 29501// Check fingerprint. If the check fails, TPM should be put to failure mode 29502if(fingerprint != in->context.sequence) 29503FAIL(FATAL_ERROR_INTERNAL); 29504// Perform object or session specific input check 29505switch(handleType) 29506{ 29507case TPM_HT_TRANSIENT: 29508{ 29509// Get a pointer to the object in the context blob 29510OBJECT 29511*outObject = (OBJECT *)(in->context.contextBlob.t.buffer 29512+ integritySize + sizeof(fingerprint)); 29513// Discard any changes to the handle that the TRM might have made 29514in->context.savedHandle = TRANSIENT_FIRST; 29515// If hierarchy is disabled, no object context can be loaded in this 29516// hierarchy 29517if(!HierarchyIsEnabled(in->context.hierarchy)) 29518return TPM_RC_HIERARCHY + RC_ContextLoad_context; 29519// Restore object. A TPM_RC_OBJECT_MEMORY error may be returned at 29520// this point 29521result = ObjectContextLoad(outObject, &out->loadedHandle); 29522if(result != TPM_RC_SUCCESS) 29523return result; 29524// If this is a sequence object, the crypto library may need to 29525// reformat the data into an internal format 29526if(ObjectIsSequence(outObject)) 29527SequenceDataImportExport(ObjectGet(out->loadedHandle), 29528outObject, IMPORT_STATE); 29529break; 29530} 29531case TPM_HT_POLICY_SESSION: 29532case TPM_HT_HMAC_SESSION: 29533{ 29534SESSION 29535 29536*session = (SESSION *)(in->context.contextBlob.t.buffer 29537+ integritySize + sizeof(fingerprint)); 29538 29539// This command may cause the orderlyState to be cleared due to 29540// the update of state reset data. If this is the case, check if NV is 29541// available first 29542 29543Page 362 29544October 31, 2013 29545 29546Published 29547Copyright © TCG 2006-2013 29548 29549Family “2.0” 29550Level 00 Revision 00.99 29551 29552 Trusted Platform Module Library 29553108 29554109 29555110 29556111 29557112 29558113 29559114 29560115 29561116 29562117 29563118 29564119 29565120 29566121 29567122 29568123 29569124 29570125 29571126 29572127 29573128 29574129 29575130 29576131 29577132 29578133 29579134 29580135 29581136 29582137 29583138 29584139 29585140 29586141 29587142 29588143 29589144 29590 29591Part 3: Commands 29592 29593if(gp.orderlyState != SHUTDOWN_NONE) 29594{ 29595// The command needs NV update. Check if NV is available. 29596// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned 29597// at this point 29598result = NvIsAvailable(); 29599if(result != TPM_RC_SUCCESS) 29600return result; 29601} 29602// Check if input handle points to a valid saved session 29603if(!SessionIsSaved(in->context.savedHandle)) 29604return TPM_RC_HANDLE + RC_ContextLoad_context; 29605// Restore session. A TPM_RC_SESSION_MEMORY, TPM_RC_CONTEXT_GAP error 29606// may be returned at this point 29607result = SessionContextLoad(session, &in->context.savedHandle); 29608if(result != TPM_RC_SUCCESS) 29609return result; 29610out->loadedHandle = in->context.savedHandle; 29611// orderly state should be cleared because of the update of state 29612// reset and state clear data 29613g_clearOrderly = TRUE; 29614break; 29615} 29616default: 29617// Context blob may only have an object handle or a session handle. 29618// All the other handle type should be filtered out at unmarshal 29619pAssert(FALSE); 29620break; 29621} 29622return TPM_RC_SUCCESS; 29623} 29624 29625Family “2.0” 29626Level 00 Revision 00.99 29627 29628Published 29629Copyright © TCG 2006-2013 29630 29631Page 363 29632October 31, 2013 29633 29634 Part 3: Commands 29635 2963630.4 29637 29638Trusted Platform Module Library 29639 29640TPM2_FlushContext 29641 2964230.4.1 General Description 29643This command causes all context associated with a loaded object or session to be removed from TPM 29644memory. 29645This command may not be used to remove a persistent object from the TPM. 29646A session does not have to be loaded in TPM memory to have its context flushed. The saved session 29647context associated with the indicated handle is invalidated. 29648No sessions of any type are allowed with 29649TPM_ST_NO_SESSIONS (see note in 30.2.1). 29650 29651this 29652 29653command 29654 29655and 29656 29657tag 29658 29659is 29660 29661required 29662 29663to 29664 29665be 29666 29667If the handle is for a transient object and the handle is not associated with a loaded object, then the TPM 29668shall return TPM_RC_HANDLE. 29669If the handle is for an authorization session and the handle does not reference a loaded or active session, 29670then the TPM shall return TPM_RC_HANDLE. 29671NOTE 29672 29673flushHandle is a parameter and not a handle. If it were in the handle area, the TPM would validate 29674that the context for the referenced entity is in the TPM. When a TPM2_FlushContext references a 29675saved session context, it is not necessary for the context to be in the TPM . 29676 29677Page 364 29678October 31, 2013 29679 29680Published 29681Copyright © TCG 2006-2013 29682 29683Family “2.0” 29684Level 00 Revision 00.99 29685 29686 Trusted Platform Module Library 29687 29688Part 3: Commands 29689 2969030.4.2 Command and Response 29691Table 183 — TPM2_FlushContext Command 29692Type 29693 29694Name 29695 29696Description 29697 29698TPMI_ST_COMMAND_TAG 29699 29700tag 29701 29702TPM_ST_NO_SESSIONS 29703 29704UINT32 29705 29706commandSize 29707 29708TPM_CC 29709 29710commandCode 29711 29712TPMI_DH_CONTEXT 29713 29714flushHandle 29715 29716TPM_CC_FlushContext 29717the handle of the item to flush 29718NOTE 29719 29720This is a use of a handle as a parameter. 29721 29722Table 184 — TPM2_FlushContext Response 29723Type 29724 29725Name 29726 29727Description 29728 29729TPM_ST 29730 29731tag 29732 29733see clause 8 29734 29735UINT32 29736 29737responseSize 29738 29739TPM_RC 29740 29741responseCode 29742 29743Family “2.0” 29744Level 00 Revision 00.99 29745 29746Published 29747Copyright © TCG 2006-2013 29748 29749Page 365 29750October 31, 2013 29751 29752 Part 3: Commands 29753 29754Trusted Platform Module Library 29755 2975630.4.3 Detailed Actions 297571 297582 29759 29760#include "InternalRoutines.h" 29761#include "FlushContext_fp.h" 29762Error Returns 29763TPM_RC_HANDLE 29764 297653 297664 297675 297686 297697 297708 297719 2977210 2977311 2977412 2977513 2977614 2977715 2977816 2977917 2978018 2978119 2978220 2978321 2978422 2978523 2978624 2978725 2978826 2978927 2979028 2979129 2979230 2979331 2979432 2979533 2979634 2979735 2979836 2979937 2980038 2980139 2980240 2980341 2980442 29805 29806Meaning 29807flushHandle does not reference a loaded object or session 29808 29809TPM_RC 29810TPM2_FlushContext( 29811FlushContext_In 29812) 29813{ 29814// Internal Data Update 29815 29816*in 29817 29818// IN: input parameter list 29819 29820// Call object or session specific routine to flush 29821switch(HandleGetType(in->flushHandle)) 29822{ 29823case TPM_HT_TRANSIENT: 29824if(!ObjectIsPresent(in->flushHandle)) 29825return TPM_RC_HANDLE; 29826// Flush object 29827ObjectFlush(in->flushHandle); 29828break; 29829case TPM_HT_HMAC_SESSION: 29830case TPM_HT_POLICY_SESSION: 29831if( 29832!SessionIsLoaded(in->flushHandle) 29833&& !SessionIsSaved(in->flushHandle) 29834) 29835return TPM_RC_HANDLE; 29836// If the session to be flushed is the exclusive audit session, then 29837// indicate that there is no exclusive audit session any longer. 29838if(in->flushHandle == g_exclusiveAuditSession) 29839g_exclusiveAuditSession = TPM_RH_UNASSIGNED; 29840// Flush session 29841SessionFlush(in->flushHandle); 29842break; 29843default: 29844// This command only take object or session handle. 29845// should be filtered out at handle unmarshal 29846pAssert(FALSE); 29847break; 29848} 29849 29850Other handles 29851 29852return TPM_RC_SUCCESS; 29853} 29854 29855Page 366 29856October 31, 2013 29857 29858Published 29859Copyright © TCG 2006-2013 29860 29861Family “2.0” 29862Level 00 Revision 00.99 29863 29864 Trusted Platform Module Library 29865 2986630.5 29867 29868Part 3: Commands 29869 29870TPM2_EvictControl 29871 2987230.5.1 General Description 29873This command allows a transient object to be made persistent or a persistent object to be evicted. 29874NOTE 1 29875 29876A transient object is one that may be removed from TPM memory using either TPM2_FlushContext 29877or TPM2_Startup(). A persistent object is not removed from TPM memory by TPM2_FlushContext() 29878or TPM2_Startup(). 29879 29880If objectHandle is a transient object, then the call is to make the object persistent and assign 29881persistentHandle to the persistent version of the object. If objectHandle is a persistent object, then the call 29882is to evict the persistent object. 29883Before execution of TPM2_EvictControl code below, the TPM verifies that objectHandle references an 29884object that is resident on the TPM and that persistentHandle is a valid handle for a persistent object. 29885NOTE 2 29886 29887This requirement simplifies the unmarshaling code so that it only need check that persistentHandle 29888is always a persistent object. 29889 29890If objectHandle references a transient object: 29891a) The TPM shall return TPM_RC_ATTRIBUTES if 298921) it is in the hierarchy of TPM_RH_NULL, 298932) only the public portion of the object is loaded, or 298943) the stClear is SET in the object or in an ancestor key. 29895b) The TPM shall return TPM_RC_HIERARCHY if the object is not in the proper hierarchy as 29896determined by auth. 298971) If auth is TPM_RH_PLATFORM, the proper hierarchy is the Platform hierarchy. 298982) If auth is TPM_RH_OWNER, the proper hierarchy is either the Storage or the Endorsement 29899hierarchy. 29900c) The TPM shall return TPM_RC_RANGE if persistentHandle is not in the proper range as determined 29901by auth. 299021) If auth is TPM_RH_OWNER, then persistentHandle shall be in the inclusive range of 2990381 00 00 0016 to 81 7F FF FF16. 299042) If auth is TPM_RH_PLATFORM, then persistentHandle shall be in the inclusive range of 2990581 80 00 0016 to 81 FF FF FF16. 29906d) The TPM shall return TPM_RC_NV_DEFINED if a persistent object exists with the same handle as 29907persistentHandle. 29908e) The TPM shall return TPM_RC_NV_SPACE if insufficient space is available to make the object 29909persistent. 29910f) 29911 29912The TPM shall return TPM_RC_NV_SPACE if execution of this command will prevent the TPM from 29913being able to hold two transient objects of any kind. 29914NOTE 3 29915 29916This requirement anticipates that a TPM may be implemented such that all TPM memory is non volatile and not subject to endurance issues. In such case, there is no movement of an object 29917between memory of different types and it is necessary that the TPM ensure that it is always 29918possible for the management software to move objects to/from TPM memory in order to ensure 29919that the objects required for command execution can be context restored. 29920 29921Family “2.0” 29922Level 00 Revision 00.99 29923 29924Published 29925Copyright © TCG 2006-2013 29926 29927Page 367 29928October 31, 2013 29929 29930 Part 3: Commands 29931 29932Trusted Platform Module Library 29933 29934g) If the TPM returns TPM_RC_SUCCESS, the object referenced by objectHandle will not be flushed 29935and both objectHandle and persistentHandle may be used to access the object. 29936If objectHandle references a persistent object: 29937h) The TPM shall return TPM_RC_RANGE if objectHandle is not in the proper range as determined by 29938auth. If auth is TPM_RC_OWNER, objectHandle shall be in the inclusive range of 81 00 00 0016 to 2993981 7F FF FF16. If auth is TPM_RC_PLATFORM, objectHandle may be any valid persistent object 29940handle. 29941i) 29942 29943If the TPM returns TPM_RC_SUCCESS, objectHandle will be removed from persistent memory and 29944no longer be accessible. 29945 29946NOTE 4 29947 29948The persistent object is not converted to a transient object, as this would prevent the immediate 29949revocation of an object by removing it from persistent memory. 29950 29951Page 368 29952October 31, 2013 29953 29954Published 29955Copyright © TCG 2006-2013 29956 29957Family “2.0” 29958Level 00 Revision 00.99 29959 29960 Trusted Platform Module Library 29961 29962Part 3: Commands 29963 2996430.5.2 Command and Response 29965Table 185 — TPM2_EvictControl Command 29966Type 29967 29968Name 29969 29970TPMI_ST_COMMAND_TAG 29971 29972tag 29973 29974UINT32 29975 29976commandSize 29977 29978TPM_CC 29979 29980commandCode 29981 29982TPM_CC_EvictControl {NV} 29983 29984TPMI_RH_PROVISION 29985 29986@auth 29987 29988TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 29989Auth Handle: 1 29990Auth Role: USER 29991 29992TPMI_DH_OBJECT 29993 29994objectHandle 29995 29996the handle of a loaded object 29997Auth Index: None 29998 29999TPMI_DH_PERSISTENT 30000 30001persistentHandle 30002 30003if objectHandle is a transient object handle, then this is 30004the persistent handle for the object 30005if objectHandle is a persistent object handle, then this 30006shall be the same value as persistentHandle 30007 30008Description 30009 30010Table 186 — TPM2_EvictControl Response 30011Type 30012 30013Name 30014 30015Description 30016 30017TPM_ST 30018 30019tag 30020 30021see clause 8 30022 30023UINT32 30024 30025responseSize 30026 30027TPM_RC 30028 30029responseCode 30030 30031Family “2.0” 30032Level 00 Revision 00.99 30033 30034Published 30035Copyright © TCG 2006-2013 30036 30037Page 369 30038October 31, 2013 30039 30040 Part 3: Commands 30041 30042Trusted Platform Module Library 30043 3004430.5.3 Detailed Actions 300451 300462 30047 30048#include "InternalRoutines.h" 30049#include "EvictControl_fp.h" 30050Error Returns 30051TPM_RC_ATTRIBUTES 30052 30053an object with temporary, stClear or publicOnly attribute SET cannot 30054be made persistent 30055 30056TPM_RC_HIERARCHY 30057 30058auth cannot authorize the operation in the hierarchy of evictObject 30059 30060TPM_RC_HANDLE 30061 30062evictHandle of the persistent object to be evicted is not the same as 30063the persistentHandle argument 30064 30065TPM_RC_NV_HANDLE 30066 30067persistentHandle is unavailable 30068 30069TPM_RC_NV_SPACE 30070 30071no space in NV to make evictHandle persistent 30072 30073TPM_RC_RANGE 30074 300753 300764 300775 300786 300797 300808 300819 3008210 3008311 3008412 3008513 3008614 3008715 3008816 3008917 3009018 3009119 3009220 3009321 3009422 3009523 3009624 3009725 3009826 3009927 3010028 3010129 3010230 3010331 3010432 3010533 3010634 3010735 3010836 3010937 3011038 3011139 3011240 3011341 3011442 3011543 30116 30117Meaning 30118 30119persistentHandle is not in the range corresponding to the hierarchy of 30120evictObject 30121 30122TPM_RC 30123TPM2_EvictControl( 30124EvictControl_In 30125 30126*in 30127 30128// IN: input parameter list 30129 30130) 30131{ 30132TPM_RC 30133OBJECT 30134 30135result; 30136*evictObject; 30137 30138// The command needs NV update. Check if NV is available. 30139// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 30140// this point 30141result = NvIsAvailable(); 30142if(result != TPM_RC_SUCCESS) return result; 30143// Input Validation 30144// Get internal object pointer 30145evictObject = ObjectGet(in->objectHandle); 30146// Temporary, stClear or public only objects can not be made persistent 30147if( 30148evictObject->attributes.temporary == SET 30149|| evictObject->attributes.stClear == SET 30150|| evictObject->attributes.publicOnly == SET 30151) 30152return TPM_RC_ATTRIBUTES + RC_EvictControl_objectHandle; 30153// If objectHandle refers to a persistent object, it should be the same as 30154// input persistentHandle 30155if( 30156evictObject->attributes.evict == SET 30157&& evictObject->evictHandle != in->persistentHandle 30158) 30159return TPM_RC_HANDLE + RC_EvictControl_objectHandle; 30160// Additional auth validation 30161if(in->auth == TPM_RH_PLATFORM) 30162{ 30163// To make persistent 30164if(evictObject->attributes.evict == CLEAR) 30165{ 30166// Platform auth can not set evict object in storage or endorsement 30167// hierarchy 30168 30169Page 370 30170October 31, 2013 30171 30172Published 30173Copyright © TCG 2006-2013 30174 30175Family “2.0” 30176Level 00 Revision 00.99 30177 30178 Trusted Platform Module Library 3017944 3018045 3018146 3018247 3018348 3018449 3018550 3018651 3018752 3018853 3018954 3019055 3019156 3019257 3019358 3019459 3019560 3019661 3019762 3019863 3019964 3020065 3020166 3020267 3020368 3020469 3020570 3020671 3020772 3020873 3020974 3021075 3021176 3021277 3021378 3021479 3021580 3021681 3021782 3021883 3021984 3022085 3022186 3022287 3022388 3022489 3022590 3022691 30227 30228Part 3: Commands 30229 30230if(evictObject->attributes.ppsHierarchy == CLEAR) 30231return TPM_RC_HIERARCHY + RC_EvictControl_objectHandle; 30232// Platform cannot use a handle outside of platform persistent range. 30233if(!NvIsPlatformPersistentHandle(in->persistentHandle)) 30234return TPM_RC_RANGE + RC_EvictControl_persistentHandle; 30235} 30236// Platform auth can delete any persistent object 30237} 30238else if(in->auth == TPM_RH_OWNER) 30239{ 30240// Owner auth can not set or clear evict object in platform hierarchy 30241if(evictObject->attributes.ppsHierarchy == SET) 30242return TPM_RC_HIERARCHY + RC_EvictControl_objectHandle; 30243// Owner cannot use a handle outside of owner persistent range. 30244if( 30245evictObject->attributes.evict == CLEAR 30246&& !NvIsOwnerPersistentHandle(in->persistentHandle) 30247) 30248return TPM_RC_RANGE + RC_EvictControl_persistentHandle; 30249} 30250else 30251{ 30252// Other auth is not allowed in this command and should be filtered out 30253// at unmarshal process 30254pAssert(FALSE); 30255} 30256// Internal Data Update 30257// Change evict state 30258if(evictObject->attributes.evict == CLEAR) 30259{ 30260// Make object persistent 30261// A TPM_RC_NV_HANDLE or TPM_RC_NV_SPACE error may be returned at this 30262// point 30263result = NvAddEvictObject(in->persistentHandle, evictObject); 30264if(result != TPM_RC_SUCCESS) return result; 30265} 30266else 30267{ 30268// Delete the persistent object in NV 30269NvDeleteEntity(evictObject->evictHandle); 30270} 30271return TPM_RC_SUCCESS; 30272} 30273 30274Family “2.0” 30275Level 00 Revision 00.99 30276 30277Published 30278Copyright © TCG 2006-2013 30279 30280Page 371 30281October 31, 2013 30282 30283 Part 3: Commands 30284 3028531 30286 30287Trusted Platform Module Library 30288 30289Clocks and Timers 30290 3029131.1 30292 30293TPM2_ReadClock 30294 3029531.1.1 General Description 30296This command reads the current TPMS_TIME_INFO structure that contains the current setting of Time, 30297Clock, resetCount, and restartCount. 30298No authorization sessions of any type are allowed with this command and tag is required to be 30299TPM_ST_NO_SESSIONS. 30300NOTE 30301 30302This command is intended to allow the TCB to have access to values that have the potential to be 30303privacy sensitive. The values may be read without authorization because the TCB will not disclose 30304these values. Since they are not signed and cannot be accessed in a command that uses an 30305authorization session, it is not possible for any entity, other than the TCB, to be assured that the 30306values are accurate. 30307 30308Page 372 30309October 31, 2013 30310 30311Published 30312Copyright © TCG 2006-2013 30313 30314Family “2.0” 30315Level 00 Revision 00.99 30316 30317 Trusted Platform Module Library 30318 30319Part 3: Commands 30320 3032131.1.2 Command and Response 30322Table 187 — TPM2_ReadClock Command 30323Type 30324 30325Name 30326 30327Description 30328 30329TPMI_ST_COMMAND_TAG 30330 30331tag 30332 30333TPM_ST_NO_SESSIONS 30334 30335UINT32 30336 30337commandSize 30338 30339TPM_CC 30340 30341commandCode 30342 30343TPM_CC_ReadClock 30344 30345Table 188 — TPM2_ReadClock Response 30346Type 30347 30348Name 30349 30350Description 30351 30352TPM_ST 30353 30354tag 30355 30356see clause 8 30357 30358UINT32 30359 30360responseSize 30361 30362TPM_RC 30363 30364returnCode 30365 30366TPMS_TIME_INFO 30367 30368currentTime 30369 30370Family “2.0” 30371Level 00 Revision 00.99 30372 30373Published 30374Copyright © TCG 2006-2013 30375 30376Page 373 30377October 31, 2013 30378 30379 Part 3: Commands 30380 30381Trusted Platform Module Library 30382 3038331.1.3 Detailed Actions 303841 303852 303863 303874 303885 303896 303907 303918 303929 3039310 3039411 3039512 3039613 3039714 30398 30399#include "InternalRoutines.h" 30400#include "ReadClock_fp.h" 30401 30402TPM_RC 30403TPM2_ReadClock( 30404ReadClock_Out *out 30405) 30406{ 30407// Command Output 30408 30409// OUT: output parameter list 30410 30411out->currentTime.time = g_time; 30412TimeFillInfo(&out->currentTime.clockInfo); 30413return TPM_RC_SUCCESS; 30414} 30415 30416Page 374 30417October 31, 2013 30418 30419Published 30420Copyright © TCG 2006-2013 30421 30422Family “2.0” 30423Level 00 Revision 00.99 30424 30425 Trusted Platform Module Library 30426 3042731.2 30428 30429Part 3: Commands 30430 30431TPM2_ClockSet 30432 3043331.2.1 General Description 30434This command is used to advance the value of the TPM’s Clock. The command will fail if newTime is less 30435than the current value of Clock or if the new time is greater than FF FF 00 00 00 00 00 0016. If both of 30436these checks succeed, Clock is set to newTime. If either of these checks fails, the TPM shall return 30437TPM_RC_VALUE and make no change to Clock. 30438NOTE 30439 30440This maximum setting would prevent Clock from rolling over to zero for approximately 8,000 years if 30441the Clock update rate was set so that TPM time was passing 33 percent faster than real time. This 30442would still be more than 6,000 years before Clock would roll over to zero. Because Clock will not roll 30443over in the lifetime of the TPM, there is no need for external software to deal with the possibility that 30444Clock may wrap around. 30445 30446If the value of Clock after the update makes the volatile and non-volatile versions of 30447TPMS_CLOCK_INFO.clock differ by more than the reported update interval, then the TPM shall update 30448the non-volatile version of TPMS_CLOCK_INFO.clock before returning. 30449This command requires platformAuth or ownerAuth. 30450 30451Family “2.0” 30452Level 00 Revision 00.99 30453 30454Published 30455Copyright © TCG 2006-2013 30456 30457Page 375 30458October 31, 2013 30459 30460 Part 3: Commands 30461 30462Trusted Platform Module Library 30463 3046431.2.2 Command and Response 30465Table 189 — TPM2_ClockSet Command 30466Type 30467 30468Name 30469 30470Description 30471 30472TPMI_ST_COMMAND_TAG 30473 30474tag 30475 30476UINT32 30477 30478commandSize 30479 30480TPM_CC 30481 30482commandCode 30483 30484TPM_CC_ClockSet {NV} 30485 30486TPMI_RH_PROVISION 30487 30488@auth 30489 30490TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 30491Auth Handle: 1 30492Auth Role: USER 30493 30494UINT64 30495 30496newTime 30497 30498new Clock setting in milliseconds 30499 30500Table 190 — TPM2_ClockSet Response 30501Type 30502 30503Name 30504 30505Description 30506 30507TPM_ST 30508 30509tag 30510 30511see clause 8 30512 30513UINT32 30514 30515responseSize 30516 30517TPM_RC 30518 30519returnCode 30520 30521Page 376 30522October 31, 2013 30523 30524Published 30525Copyright © TCG 2006-2013 30526 30527Family “2.0” 30528Level 00 Revision 00.99 30529 30530 Trusted Platform Module Library 30531 30532Part 3: Commands 30533 3053431.2.3 Detailed Actions 305351 305362 30537 30538#include "InternalRoutines.h" 30539#include "ClockSet_fp.h" 30540 30541Read the current TPMS_TIMER_INFO structure settings 30542Error Returns 30543TPM_RC_VALUE 305443 305454 305465 305476 305487 305498 305509 3055110 3055211 3055312 3055413 3055514 3055615 3055716 3055817 3055918 3056019 3056120 3056221 3056322 3056423 3056524 3056625 3056726 3056827 3056928 3057029 3057130 3057231 3057332 3057433 3057534 3057635 30577 30578Meaning 30579invalid new clock 30580 30581TPM_RC 30582TPM2_ClockSet( 30583ClockSet_In *in 30584) 30585{ 30586#define CLOCK_UPDATE_MASK 30587UINT64 30588clockNow; 30589 30590// IN: input parameter list 30591((1ULL << NV_CLOCK_UPDATE_INTERVAL)- 1) 30592 30593// Input Validation 30594// new time can not be bigger than 0xFFFF000000000000 or smaller than 30595// current clock 30596if(in->newTime > 0xFFFF000000000000ULL 30597|| in->newTime < go.clock) 30598return TPM_RC_VALUE + RC_ClockSet_newTime; 30599// Internal Data Update 30600// Internal Data Update 30601clockNow = go.clock; 30602// grab the old value 30603go.clock = in->newTime; 30604// set the new value 30605// Check to see if the update has caused a need for an nvClock update 30606if((in->newTime & CLOCK_UPDATE_MASK) > (clockNow & CLOCK_UPDATE_MASK)) 30607{ 30608CryptDrbgGetPutState(GET_STATE); 30609NvWriteReserved(NV_ORDERLY_DATA, &go); 30610// Now the time state is safe 30611go.clockSafe = YES; 30612} 30613return TPM_RC_SUCCESS; 30614} 30615 30616Family “2.0” 30617Level 00 Revision 00.99 30618 30619Published 30620Copyright © TCG 2006-2013 30621 30622Page 377 30623October 31, 2013 30624 30625 Part 3: Commands 30626 3062731.3 30628 30629Trusted Platform Module Library 30630 30631TPM2_ClockRateAdjust 30632 3063331.3.1 General Description 30634This command adjusts the rate of advance of Clock and Time to provide a better approximation to real 30635time. 30636The rateAdjust value is relative to the current rate and not the nominal rate of advance. 30637EXAMPLE 1 30638 30639If this command had been called three times with rateAdjust = TPM_CLOCK_COARSE_SLOWER 30640and once with rateAdjust = TPM_CLOCK_COARSE_FASTER, the net effect will be as if the 30641command had been called twice with rateAdjust = TPM_CLOCK_COARSE_SLOWER. 30642 30643The range of adjustment shall be sufficient to allow Clock and Time to advance at real time but no more. 30644If the requested adjustment would make the rate advance faster or slower than the nominal accuracy of 30645the input frequency, the TPM shall return TPM_RC_VALUE. 30646EXAMPLE 2 30647 30648If the frequency tolerance of the TPM's input clock is +/-10 percent, then the TPM will return 30649TPM_RC_VALUE if the adjustment would make Clock run more than 10 percent faster or slower than 30650nominal. That is, if the input oscillator were nominally 100 megahertz (MHz), then 1 millisecond (ms) 30651would normally take 100,000 counts. The update Clock should be adjustable so that 1 ms is between 3065290,000 and 110,000 counts. 30653 30654The interpretation of “fine” and “coarse” adjustments is implementation-specific. 30655The nominal rate of advance for Clock and Time shall be accurate to within 15 percent. That is, with no 30656adjustment applied, Clock and Time shall be advanced at a rate within 15 percent of actual time. 30657NOTE 30658 30659If the adjustments are incorrect, it will be possible to m ake the difference between advance of 30660Clock/Time and real time to be as much as 1.15 2 or ~1.33. 30661 30662Changes to the current Clock update rate adjustment need not be persisted across TPM power cycles. 30663 30664Page 378 30665October 31, 2013 30666 30667Published 30668Copyright © TCG 2006-2013 30669 30670Family “2.0” 30671Level 00 Revision 00.99 30672 30673 Trusted Platform Module Library 30674 30675Part 3: Commands 30676 3067731.3.2 Command and Response 30678Table 191 — TPM2_ClockRateAdjust Command 30679Type 30680 30681Name 30682 30683Description 30684 30685TPMI_ST_COMMAND_TAG 30686 30687tag 30688 30689UINT32 30690 30691commandSize 30692 30693TPM_CC 30694 30695commandCode 30696 30697TPM_CC_ClockRateAdjust 30698 30699TPMI_RH_PROVISION 30700 30701@auth 30702 30703TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 30704Auth Handle: 1 30705Auth Role: USER 30706 30707TPM_CLOCK_ADJUST 30708 30709rateAdjust 30710 30711Adjustment to current Clock update rate 30712 30713Table 192 — TPM2_ClockRateAdjust Response 30714Type 30715 30716Name 30717 30718Description 30719 30720TPM_ST 30721 30722tag 30723 30724see clause 8 30725 30726UINT32 30727 30728responseSize 30729 30730TPM_RC 30731 30732returnCode 30733 30734Family “2.0” 30735Level 00 Revision 00.99 30736 30737Published 30738Copyright © TCG 2006-2013 30739 30740Page 379 30741October 31, 2013 30742 30743 Part 3: Commands 30744 30745Trusted Platform Module Library 30746 3074731.3.3 Detailed Actions 307481 307492 307503 307514 307525 307536 307547 307558 307569 3075710 3075811 3075912 30760 30761#include "InternalRoutines.h" 30762#include "ClockRateAdjust_fp.h" 30763 30764TPM_RC 30765TPM2_ClockRateAdjust( 30766ClockRateAdjust_In 30767*in 30768) 30769{ 30770// Internal Data Update 30771TimeSetAdjustRate(in->rateAdjust); 30772 30773// IN: input parameter list 30774 30775return TPM_RC_SUCCESS; 30776} 30777 30778Page 380 30779October 31, 2013 30780 30781Published 30782Copyright © TCG 2006-2013 30783 30784Family “2.0” 30785Level 00 Revision 00.99 30786 30787 Trusted Platform Module Library 30788 3078932 30790 30791Part 3: Commands 30792 30793Capability Commands 30794 3079532.1 30796 30797Introduction 30798 30799The TPM has numerous values that indicate the state, capabilities, and properties of the TPM. These 30800values are needed for proper management of the TPM. The TPM2_GetCapability() command is used to 30801access these values. 30802TPM2_GetCapability() allows reporting of multiple values in a single call. The values are grouped 30803according to type. 30804NOTE 30805 3080632.2 30807 30808TPM2_TestParms()is used to determine if a TPM supports a particular combination of algorithm 30809parameters 30810 30811TPM2_GetCapability 30812 3081332.2.1 General Description 30814This command returns various information regarding the TPM and its current state. 30815The capability parameter determines the category of data returned. The property parameter selects the 30816first value of the selected category to be returned. If there is no property that corresponds to the value of 30817property, the next higher value is returned, if it exists. 30818EXAMPLE 1 30819 30820The list of handles of transient objects currently loaded in the TPM may be read one at a time. On 30821the first read, set the property to TRANSIENT_FIRST and propertyCount to one. If a transient object 30822is present, the lowest numbered handle is returned and moreData will be YES if transient objects 30823with higher handles are loaded. On the subsequent call, use returned handle value plus 1 in order to 30824access the next higher handle. 30825 30826The propertyCount parameter indicates the number of capabilities in the indicated group that are 30827requested. The TPM will return the number of requested values (propertyCount) or until the last property 30828of the requested type has been returned. 30829NOTE 1 30830 30831The type of the capability is determined by a combination of capability and property. 30832 30833When all of the properties of the requested type have been returned, the moreData parameter in the 30834response will be set to NO. Otherwise, it will be set to YES. 30835NOTE 2 30836 30837The moreData parameter will be YES if there are more properties e ven if the requested number of 30838capabilities has been returned. 30839 30840The TPM is not required to return more than one value at a time. It is not required to provide the same 30841number of values in response to subsequent requests. 30842EXAMPLE 2 30843 30844A TPM may return 4 properties in response to a TPM2_GetCapability(capability = 30845TPM_CAP_TPM_PROPERTY, property = TPM_PT_MANUFACTURER, propertyCount = 8 ) and for a 30846latter request with the same parameters, the TPM may return as few as one and as many as 8 30847values. 30848 30849When the TPM is in Failure mode, a TPM is required to allow use of this command for access of the 30850following capabilities: 30851 30852Family “2.0” 30853Level 00 Revision 00.99 30854 30855Published 30856Copyright © TCG 2006-2013 30857 30858Page 381 30859October 31, 2013 30860 30861 Part 3: Commands 30862 30863Trusted Platform Module Library 30864 30865 30866 30867TPM_PT_MANUFACTURER 30868 30869 30870 30871TPM_PT_VENDOR_STRING_1 30872 30873 30874 30875TPM_PT_VENDOR_STRING_2 30876 30877(3) 30878 30879 30880 30881TPM_PT_VENDOR_STRING_3 30882 30883(3) 30884 30885 30886 30887TPM_PT_VENDOR_STRING_4 30888 30889(3) 30890 30891 30892 30893TPM_PT_VENDOR_TPM_TYPE 30894 30895 30896 30897TPM_PT_FIRMWARE_VERSION_1 30898 30899 30900 30901TPM_PT_FIRMWARE_VERSION_2 30902 30903NOTE 3 30904 30905If the vendor string does not require one of these values, the property type does not need to exist. 30906 30907A vendor may optionally allow the TPM to return other values. 30908If in Failure mode and a capability is requested that is not available in Failure mode, the TPM shall return 30909no value. 30910EXAMPLE 3 30911 30912Assume the TPM is in Failure mode and the TPM only supports reporting of the minimum required 30913set of properties (the limited set to TPML_TAGGED_PCR_PROPERTY values). If a 30914TPM2_GetCapability is received requesting a capability that has a property type value greater than 30915TPM_PT_FIRMWARE_VERSION_2, the TPM will return a zero length list with the moreData 30916parameter set to NO. If the property type is less than TPM_PT_M ANUFACTURER, the TPM will 30917return TPM_PT_MANUFACTURER. 30918 30919In Failure mode, tag is required to be TPM_ST_NO_SESSIONS or the TPM shall return 30920TPM_RC_FAILURE. 30921The capability categories and the types of the return values are: 30922capability 30923 30924Return Type 30925 30926property 30927(1) 30928 30929TPM_CAP_ALGS 30930 30931TPM_ALG_ID 30932 30933TPML_ALG_PROPERTY 30934 30935TPM_CAP_HANDLES 30936 30937TPM_HANDLE 30938 30939TPML_HANDLE 30940 30941TPM_CAP_COMMANDS 30942 30943TPM_CC 30944 30945TPML_CCA 30946 30947TPM_CAP_PP_COMMANDS 30948 30949TPM_CC 30950 30951TPML_CC 30952 30953TPM_CAP_AUDIT_COMMANDS 30954 30955TPM_CC 30956 30957TPML_CC 30958 30959TPM_CAP_PCRS 30960 30961Reserved 30962 30963TPML_PCR_SELECTION 30964 30965TPM_CAP_TPM_PROPERTIES 30966 30967TPM_PT 30968 30969TPML_TAGGED_TPM_PROPERTY 30970 30971TPM_CAP_PCR_PROPERTIES 30972 30973TPM_PT_PCR 30974 30975TPML_TAGGED_PCR_PROPERTY 30976(1) 30977 30978TPM_CAP_ECC_CURVE 30979 30980TPM_ECC_CURVE 30981 30982TPM_CAP_VENDOR_PROPERTY 30983 30984manufacturer specific 30985 30986TPML_ECC_CURVE 30987manufacturer-specific values 30988 30989NOTES: 30990(1) The TPM_ALG_ID or TPM_ECC_CURVE is cast to a UINT32 30991 30992Page 382 30993October 31, 2013 30994 30995Published 30996Copyright © TCG 2006-2013 30997 30998Family “2.0” 30999Level 00 Revision 00.99 31000 31001 Trusted Platform Module Library 31002 31003Part 3: Commands 31004 31005 31006 31007TPM_CAP_ALGS – Returns a list of TPMS_ALG_PROPERTIES. Each entry is an algorithm ID and a 31008set of properties of the algorithm. 31009 31010 31011 31012TPM_CAP_HANDLES – Returns a list of all of the handles within the handle range of the property 31013parameter. The range of the returned handles is determined by the handle type (the most-significant 31014octet (MSO) of the property). Any of the defined handle types is allowed 31015EXAMPLE 4 31016 31017EXAMPLE 5 31018 31019 31020 31021If the MSO of property is TPM_HT_NV_INDEX, then the TPM will return a list of NV Index 31022values. 31023If the MSO of property is TPM_HT_PCR, then the TPM will return a list of PCR. 31024 31025For this capability, use of TPM_HT_LOADED_SESSION and TPM_HT_SAVED_SESSION is 31026allowed. Requesting handles with a handle type of TPM_HT_LOADED_SESSION will return handles 31027for loaded sessions. The returned handle values will have a handle type of either 31028TPM_HT_HMAC_SESSION or TPM_HT_POLICY_SESSION. If saved sessions are requested, all 31029returned values will have the TPM_HT_HMAC_SESSION handle type because the TPM does not 31030track the session type of saved sessions. 31031NOTE 2 31032 31033 31034 31035TPM_HT_LOADED_SESSION and TPM_HT_HMAC_SESSION have the same value, as do 31036TPM_HT_SAVED_SESSION and TPM_HT_POLICY_SESSION. It is not possible to request that 31037the TPM return a list of loaded HMAC sessions without including the policy sessions. 31038 31039TPM_CAP_COMMANDS – Returns a list of the command attributes for all of the commands 31040implemented in the TPM, starting with the TPM_CC indicated by the property parameter. If vendor 31041specific commands are implemented, the vendor-specific command attribute with the lowest 31042commandIndex, is returned after the non-vendor-specific (base) command. 31043NOTE 4 31044 31045The type of the property parameter is a TPM_CC while the type of the returned list is 31046TPML_CCA. 31047 31048 31049 31050TPM_CAP_PP_COMMANDS – Returns a list of all of the commands currently requiring Physical 31051Presence for confirmation of platform authorization. The list will start with the TPM_CC indicated by 31052property. 31053 31054 31055 31056TPM_CAP_AUDIT_COMMANDS – Returns a list of all of the commands currently set for command 31057audit. 31058 31059 31060 31061TPM_CAP_PCRS – Returns the current allocation of PCR in a TPML_PCR_SELECTION. The 31062property parameter shall be zero. The TPM will always respond to this command with the full PCR 31063allocation and moreData will be NO. 31064 31065 31066 31067TPM_CAP_TPM_PROPERTIES – Returns a list of tagged properties. The tag is a TPM_PT and the 31068property is a 32-bit value. The properties are returned in groups. Each property group is on a 256value boundary (that is, the boundary occurs when the TPM_PT is evenly divisible by 256). The TPM 31069will only return values in the same group as the property parameter in the command. 31070 31071 31072 31073TPM_CAP_PCR_PROPERTIES – Returns a list of tagged PCR properties. The tag is a 31074TPM_PT_PCR and the property is a TPMS_PCR_SELECT. 31075 31076The input command property is a TPM_PT_PCR (see Part 2 for PCR properties to be requested) that 31077specifies the first property to be returned. If propertyCount is greater than 1, the list of properties begins 31078with that property and proceeds in TPM_PT_PCR sequence. 31079NOTE 5 31080 31081If the propertyCount selects an unimplemented property, the next higher implemented property 31082is returned. 31083 31084Each item in the list is a TPMS_PCR_SELECT structure that contains a bitmap of all PCR. 31085NOTE 6 31086 31087A PCR index in all banks (all hash algorithms) has the same properties, so the hash algorithm is 31088not specified here. 31089 31090Family “2.0” 31091Level 00 Revision 00.99 31092 31093Published 31094Copyright © TCG 2006-2013 31095 31096Page 383 31097October 31, 2013 31098 31099 Part 3: Commands 31100 31101 31102Trusted Platform Module Library 31103 31104TPM_CAP_TPM_ECC_CURVES – Returns a list of ECC curve identifiers currently available for use 31105in the TPM. 31106 31107The moreData parameter will have a value of YES if there are more values of the requested type that 31108were not returned. 31109If no next capability exists, the TPM will return a zero-length list and moreData will have a value of NO. 31110 31111Page 384 31112October 31, 2013 31113 31114Published 31115Copyright © TCG 2006-2013 31116 31117Family “2.0” 31118Level 00 Revision 00.99 31119 31120 Trusted Platform Module Library 31121 31122Part 3: Commands 31123 3112432.2.2 Command and Response 31125Table 193 — TPM2_GetCapability Command 31126Type 31127 31128Name 31129 31130Description 31131 31132TPMI_ST_COMMAND_TAG 31133 31134tag 31135 31136UINT32 31137 31138commandSize 31139 31140TPM_CC 31141 31142commandCode 31143 31144TPM_CC_GetCapability 31145 31146TPM_CAP 31147 31148capability 31149 31150group selection; determines the format of the response 31151 31152UINT32 31153 31154property 31155 31156further definition of information 31157 31158UINT32 31159 31160propertyCount 31161 31162number of properties of the indicated type to return 31163 31164Table 194 — TPM2_GetCapability Response 31165Type 31166 31167Name 31168 31169Description 31170 31171TPM_ST 31172 31173tag 31174 31175see clause 8 31176 31177UINT32 31178 31179responseSize 31180 31181TPM_RC 31182 31183responseCode 31184 31185TPMI_YES_NO 31186 31187moreData 31188 31189flag to indicate if there are more values of this type 31190 31191TPMS_CAPABILITY_DATA 31192 31193capabilityData 31194 31195the capability data 31196 31197Family “2.0” 31198Level 00 Revision 00.99 31199 31200Published 31201Copyright © TCG 2006-2013 31202 31203Page 385 31204October 31, 2013 31205 31206 Part 3: Commands 31207 31208Trusted Platform Module Library 31209 3121032.2.3 Detailed Actions 312111 312122 31213 31214#include "InternalRoutines.h" 31215#include "GetCapability_fp.h" 31216Error Returns 31217TPM_RC_HANDLE 31218 31219value of property is in an unsupported handle range for the 31220TPM_CAP_HANDLES capability value 31221 31222TPM_RC_VALUE 31223 312243 312254 312265 312276 312287 312298 312309 3123110 3123211 3123312 3123413 3123514 3123615 3123716 3123817 3123918 3124019 3124120 3124221 3124322 3124423 3124524 3124625 3124726 3124827 3124928 3125029 3125130 3125231 3125332 3125433 3125534 3125635 3125736 3125837 3125938 3126039 3126140 3126241 3126342 3126443 3126544 3126645 3126746 3126847 3126948 3127049 3127150 3127251 31273 31274Meaning 31275 31276invalid capability; or property is not 0 for the TPM_CAP_PCRS 31277capability value 31278 31279TPM_RC 31280TPM2_GetCapability( 31281GetCapability_In 31282GetCapability_Out 31283 31284*in, 31285*out 31286 31287// IN: input parameter list 31288// OUT: output parameter list 31289 31290) 31291{ 31292// Command Output 31293// Set output capability type the same as input type 31294out->capabilityData.capability = in->capability; 31295switch(in->capability) 31296{ 31297case TPM_CAP_ALGS: 31298out->moreData = AlgorithmCapGetImplemented((TPM_ALG_ID) in->property, 31299in->propertyCount, &out->capabilityData.data.algorithms); 31300break; 31301case TPM_CAP_HANDLES: 31302switch(HandleGetType((TPM_HANDLE) in->property)) 31303{ 31304case TPM_HT_TRANSIENT: 31305// Get list of handles of loaded transient objects 31306out->moreData = ObjectCapGetLoaded((TPM_HANDLE) in->property, 31307in->propertyCount, 31308&out->capabilityData.data.handles); 31309break; 31310case TPM_HT_PERSISTENT: 31311// Get list of handles of persistent objects 31312out->moreData = NvCapGetPersistent((TPM_HANDLE) in->property, 31313in->propertyCount, 31314&out->capabilityData.data.handles); 31315break; 31316case TPM_HT_NV_INDEX: 31317// Get list of defined NV index 31318out->moreData = NvCapGetIndex((TPM_HANDLE) in->property, 31319in->propertyCount, 31320&out->capabilityData.data.handles); 31321break; 31322case TPM_HT_LOADED_SESSION: 31323// Get list of handles of loaded sessions 31324out->moreData = SessionCapGetLoaded((TPM_HANDLE) in->property, 31325in->propertyCount, 31326&out->capabilityData.data.handles); 31327break; 31328case TPM_HT_ACTIVE_SESSION: 31329// Get list of handles of 31330out->moreData = SessionCapGetSaved((TPM_HANDLE) in->property, 31331in->propertyCount, 31332&out->capabilityData.data.handles); 31333 31334Page 386 31335October 31, 2013 31336 31337Published 31338Copyright © TCG 2006-2013 31339 31340Family “2.0” 31341Level 00 Revision 00.99 31342 31343 Trusted Platform Module Library 3134452 3134553 3134654 3134755 3134856 3134957 3135058 3135159 3135260 3135361 3135462 3135563 3135664 3135765 3135866 3135967 3136068 3136169 3136270 3136371 3136472 3136573 3136674 3136775 3136876 3136977 3137078 3137179 3137280 3137381 3137482 3137583 3137684 3137785 3137886 3137987 3138088 3138189 3138290 3138391 3138492 3138593 3138694 3138795 3138896 3138997 3139098 3139199 31392100 31393101 31394102 31395103 31396104 31397105 31398106 31399107 31400108 31401109 31402110 31403111 31404112 31405113 31406114 31407115 31408 31409Part 3: Commands 31410 31411break; 31412case TPM_HT_PCR: 31413// Get list of handles of PCR 31414out->moreData = PCRCapGetHandles((TPM_HANDLE) in->property, 31415in->propertyCount, 31416&out->capabilityData.data.handles); 31417break; 31418case TPM_HT_PERMANENT: 31419// Get list of permanent handles 31420out->moreData = PermanentCapGetHandles( 31421(TPM_HANDLE) in->property, 31422in->propertyCount, 31423&out->capabilityData.data.handles); 31424break; 31425default: 31426// Unsupported input handle type 31427return TPM_RC_HANDLE + RC_GetCapability_property; 31428break; 31429} 31430break; 31431case TPM_CAP_COMMANDS: 31432out->moreData = CommandCapGetCCList((TPM_CC) in->property, 31433in->propertyCount, 31434&out->capabilityData.data.command); 31435break; 31436case TPM_CAP_PP_COMMANDS: 31437out->moreData = PhysicalPresenceCapGetCCList((TPM_CC) in->property, 31438in->propertyCount, &out->capabilityData.data.ppCommands); 31439break; 31440case TPM_CAP_AUDIT_COMMANDS: 31441out->moreData = CommandAuditCapGetCCList((TPM_CC) in->property, 31442in->propertyCount, 31443&out->capabilityData.data.auditCommands); 31444break; 31445case TPM_CAP_PCRS: 31446// Input property must be 0 31447if(in->property != 0) 31448return TPM_RC_VALUE + RC_GetCapability_property; 31449out->moreData = PCRCapGetAllocation(in->propertyCount, 31450&out->capabilityData.data.assignedPCR); 31451break; 31452case TPM_CAP_PCR_PROPERTIES: 31453out->moreData = PCRCapGetProperties((TPM_PT_PCR) in->property, 31454in->propertyCount, 31455&out->capabilityData.data.pcrProperties); 31456break; 31457case TPM_CAP_TPM_PROPERTIES: 31458out->moreData = TPMCapGetProperties((TPM_PT) in->property, 31459in->propertyCount, 31460&out->capabilityData.data.tpmProperties); 31461break; 31462#ifdef TPM_ALG_ECC 31463case TPM_CAP_ECC_CURVES: 31464out->moreData = CryptCapGetECCCurve((TPM_ECC_CURVE 31465) in->property, 31466in->propertyCount, 31467&out->capabilityData.data.eccCurves); 31468break; 31469#endif // TPM_ALG_ECC 31470case TPM_CAP_VENDOR_PROPERTY: 31471// vendor property is not implemented 31472default: 31473// Unexpected TPM_CAP value 31474return TPM_RC_VALUE; 31475break; 31476 31477Family “2.0” 31478Level 00 Revision 00.99 31479 31480Published 31481Copyright © TCG 2006-2013 31482 31483Page 387 31484October 31, 2013 31485 31486 Part 3: Commands 31487116 31488117 31489118 31490119 31491 31492Trusted Platform Module Library 31493 31494} 31495return TPM_RC_SUCCESS; 31496} 31497 31498Page 388 31499October 31, 2013 31500 31501Published 31502Copyright © TCG 2006-2013 31503 31504Family “2.0” 31505Level 00 Revision 00.99 31506 31507 Trusted Platform Module Library 31508 3150932.3 31510 31511Part 3: Commands 31512 31513TPM2_TestParms 31514 3151532.3.1 General Description 31516This command is used to check to see if specific combinations of algorithm parameters are supported. 31517The TPM will unmarshal the provided TPMT_PUBLIC_PARMS. If the parameters unmarshal correctly, 31518then the TPM will return TPM_RC_SUCCESS, indicating that the parameters are valid for the TPM. The 31519TPM will return the appropriate unmarshaling error if a parameter is not valid. 31520 31521Family “2.0” 31522Level 00 Revision 00.99 31523 31524Published 31525Copyright © TCG 2006-2013 31526 31527Page 389 31528October 31, 2013 31529 31530 Part 3: Commands 31531 31532Trusted Platform Module Library 31533 3153432.3.2 Command and Response 31535Table 195 — TPM2_TestParms Command 31536Type 31537 31538Name 31539 31540Description 31541 31542TPMI_ST_COMMAND_TAG 31543 31544tag 31545 31546UINT32 31547 31548commandSize 31549 31550TPM_CC 31551 31552commandCode 31553 31554TPM_CC_TestParms 31555 31556TPMT_PUBLIC_PARMS 31557 31558parameters 31559 31560algorithm parameters to be validated 31561 31562Table 196 — TPM2_TestParms Response 31563Type 31564 31565Name 31566 31567Description 31568 31569TPM_ST 31570 31571tag 31572 31573see clause 8 31574 31575UINT32 31576 31577responseSize 31578 31579TPM_RC 31580 31581responseCode 31582 31583Page 390 31584October 31, 2013 31585 31586Published 31587Copyright © TCG 2006-2013 31588 31589Family “2.0” 31590Level 00 Revision 00.99 31591 31592 Trusted Platform Module Library 31593 31594Part 3: Commands 31595 3159632.3.3 Detailed Actions 315971 315982 315993 316004 316015 316026 316037 316048 316059 3160610 3160711 3160812 3160913 3161014 31611 31612#include "InternalRoutines.h" 31613#include "TestParms_fp.h" 31614 31615TPM_RC 31616TPM2_TestParms( 31617TestParms_In 31618 31619*in 31620 31621// IN: input parameter list 31622 31623) 31624{ 31625// Input parameter is not reference in command action 31626in = NULL; 31627// The parameters are tested at unmarshal process. 31628// action 31629return TPM_RC_SUCCESS; 31630 31631We do nothing in command 31632 31633} 31634 31635Family “2.0” 31636Level 00 Revision 00.99 31637 31638Published 31639Copyright © TCG 2006-2013 31640 31641Page 391 31642October 31, 2013 31643 31644 Part 3: Commands 31645 3164633 31647 31648Trusted Platform Module Library 31649 31650Non-volatile Storage 31651 3165233.1 31653 31654Introduction 31655 31656The NV commands are used to create, update, read, and delete allocations of space in NV memory. 31657Before an Index may be used, it must be defined (TPM2_NV_DefineSpace()). 31658An Index may be modified if the proper write authorization is provided or read if the proper read 31659authorization is provided. Different controls are available for reading and writing. 31660An Index may have an Index-specific authValue and authPolicy. The authValue may be used to authorize 31661reading if TPMA_NV_AUTHREAD is SET and writing if TPMA_NV_AUTHREAD is SET. The authPolicy 31662may be used to authorize reading if TPMA_NV_POLICYREAD is SET and writing if 31663TPMA_NV_POLICYWRITE is SET. 31664TPMA_NV_PPREAD and TPMA_NV_PPWRITE indicate if reading or writing of the NV Index may be 31665authorized by platformAuth or platformPolicy. 31666TPMA_NV_OWNERREAD and TPMA_NV_OWNERWRITE indicate if reading or writing of the NV Index 31667may be authorized by ownerAuth or ownerPolicy. 31668If an operation on an NV index requires authorization, and the authHandle parameter is the handle of an 31669NV Index, then the nvIndex parameter must have the same value or the TPM will return 31670TPM_RC_NV_AUTHORIZATION. 31671NOTE 1 31672 31673This check ensures that the authorization that was provided is associated with the NV Index being 31674authorized. 31675 31676For creating an Index, ownerAuth may not be used if shEnable is CLEAR and platformAuth may not be 31677used if phEnableNV is CLEAR. 31678If an Index was defined using platformAuth, then that Index is not accessible when phEnableNV is 31679CLEAR. If an Index was defined using ownerAuth, then that Index is not accessible when shEnable is 31680CLEAR. 31681For read access control, any combination of TPMA_NV_PPREAD, TPMA_NV_OWNERREAD, 31682TPMA_NV_AUTHREAD, or TPMA_NV_POLICYREAD is allowed as long as at least one is SET. 31683For write access control, any combination of TPMA_NV_PPWRITE, TPMA_NV_OWNERWRITE, 31684TPMA_NV_AUTHWRITE, or TPMA_NV_POLICYWRITE is allowed as long as at least one is SET. 31685If an Index has been defined and not written, then any operation on the NV Index that requires read 31686authorization will fail (TPM_RC_NV_INITIALIZED). This check may be made before or after other 31687authorization checks but shall be performed before checking the NV Index authValue. An authorization 31688failure due to the NV Index not having been written shall not be logged by the dictionary attack logic. 31689If TPMA_NV_CLEAR_STCLEAR is SET, then the TPMA_NV_WRITTEN will be CLEAR on each 31690TPM2_Startup(TPM_SU_CLEAR). 31691TPMA_NV_CLEAR_STCLEAR 31692shall 31693not 31694be 31695SET 31696if 31697TPMA_NV_COUNTER is SET. 31698The code in the “Detailed Actions” clause of each command is written to interface with an implementationdependent library that allows access to NV memory. The actions assume no specific layout of the 31699structure of the NV data. 31700Only one NV Index may be directly referenced in a command. 31701NOTE 2 31702 31703This means that, if authHandle references an NV Index, then nvIndex will have the same value. 31704However, this does not limit the number of changes that may occur as side effects. For example, any 31705number of NV Indexes might be relocated as a result of deleting or adding a NV Ind ex. 31706 31707Page 392 31708October 31, 2013 31709 31710Published 31711Copyright © TCG 2006-2013 31712 31713Family “2.0” 31714Level 00 Revision 00.99 31715 31716 Trusted Platform Module Library 31717 3171833.2 31719 31720Part 3: Commands 31721 31722NV Counters 31723 31724When an Index has the TPMA_NV_COUNTER attribute set, it behaves as a monotonic counter and may 31725only be updated using TPM2_NV_Increment(). 31726When an NV counter is created, the TPM shall initialize the 8-octet counter value with a number that is 31727greater than any count value for any NV counter on the TPM since the time of TPM manufacture. 31728An NV counter may be defined with the TPMA_NV_ORDERLY attribute to indicate that the NV Index is 31729expected to be modified at a high frequency and that the data is only required to persist when the TPM 31730goes through an orderly shutdown process. The TPM may update the counter value in RAM and 31731occasionally update the non-volatile version of the counter. An orderly shutdown is one occasion to 31732update the non-volatile count. If the difference between the volatile and non-volatile version of the counter 31733becomes as large as MAX_ORDERLY_COUNT, this shall be another occasion for updating the nonvolatile count. 31734Before an NV counter can be used, the TPM shall validate that the count is not less than a previously 31735reported value. If the TPMA_NV_ORDERLY attribute is not SET, or if the TPM experienced an orderly 31736shutdown, then the count is assumed to be correct. If the TPMA_NV_ORDERLY attribute is SET, and the 31737TPM shutdown was not orderly, then the TPM shall OR MAX_ORDERLY_COUNT to the contents of the 31738non-volatile counter and set that as the current count. 31739NOTE 1 31740 31741Because the TPM would have updated the NV Index if the difference between the count values was 31742equal to MAX_ORDERLY_COUNT + 1, the highest value that could have been in the NV Index is 31743MAX_ORDERLY_COUNT so it is safe to restore that value. 31744 31745NOTE 2 31746 31747The TPM may implement the RAM portion of the counter such that the effective value of the NV 31748counter is the sum of both the volatile and non-volatile parts. If so, then the TPM may initialize the 31749RAM version of the counter to MAX_ORDERLY_COUNT and no update of NV is necessary. 31750 31751NOTE 3 31752 31753When a new NV counter is created, the TPM may search all the counters to determine which has the 31754highest value. In this search, the TPM would use the sum of the non -volatile and RAM portions of 31755the counter. The RAM portion of the counter shall be properly initialized to reflect shutdown p rocess 31756(orderly or not) of the TPM. 31757 31758Family “2.0” 31759Level 00 Revision 00.99 31760 31761Published 31762Copyright © TCG 2006-2013 31763 31764Page 393 31765October 31, 2013 31766 31767 Part 3: Commands 31768 3176933.3 31770 31771Trusted Platform Module Library 31772 31773TPM2_NV_DefineSpace 31774 3177533.3.1 General Description 31776This command defines the attributes of an NV Index and causes the TPM to reserve space to hold the 31777data associated with the NV Index. If a definition already exists at the NV Index, the TPM will return 31778TPM_RC_NV_DEFINED. 31779The TPM will return TPM_RC_ATTRIBUTES if more 31780TPMA_NV_BITS, or TPMA_NV_EXTEND is SET in publicInfo. 31781NOTE 31782 31783than 31784 31785one 31786 31787of 31788 31789TPMA_NV_COUNTER, 31790 31791It is not required that any of these three attributes be set. 31792 31793The TPM shall return TPM_RC_ATTRIBUTES if TPMA_NV_WRITTEN, TPM_NV_READLOCKED, or 31794TPMA_NV_WRITELOCKED is SET. 31795If TPMA_NV_COUNTER or TPMA_NV_BITS is SET, then publicInfo→dataSize shall be set to eight (8) or 31796the TPM shall return TPM_RC_SIZE. 31797If TPMA_NV_EXTEND is SET, then publicInfo→dataSize shall match the digest size of the 31798publicInfo.nameAlg or the TPM shall return TPM_RC_SIZE. 31799If the NV Index is an ordinary Index and publicInfo→dataSize is larger than supported by the TPM 31800implementation then the TPM shall return TPM_RC_SIZE. 31801NOTE 31802 31803The limit for the data size may vary according to the type of the index. For example, if the index is 31804has TPMA_NV_ORDERLY SET, then the maximum size of an ordin ary NV Index may be less than 31805the size of an ordinary NV Index that has TPMA_NV_ORDERLY CLEAR. 31806 31807At least one of TPMA_NV_PPREAD, TPMA_NV_OWNERREAD, TPMA_NV_AUTHREAD, 31808TPMA_NV_POLICYREAD shall be SET or the TPM shall return TPM_RC_ATTRIBUTES. 31809 31810or 31811 31812At least one of TPMA_NV_PPWRITE, TPMA_NV_OWNERWRITE, TPMA_NV_AUTHWRITE, or 31813TPMA_NV_POLICYWRITE shall be SET or the TPM shall return TPM_RC_ATTRIBUTES. 31814If TPMA_NV_CLEAR_STCLEAR is SET, then TPMA_NV_COUNTER shall be CLEAR or the TPM shall 31815return TPM_RC_ATTRIBUTES. 31816If platformAuth/platformPolicy is used for authorization, then TPMA_NV_PLATFORMCREATE shall be 31817SET in publicInfo. If ownerAuth/ownerPolicy is used for authorization, TPMA_NV_PLATFORMCREATE 31818shall be CLEAR in publicInfo. If TPMA_NV_PLATFORMCREATE is not set correctly for the authorization, 31819the TPM shall return TPM_RC_ATTRIBUTES. 31820If TPMA_NV_POLICY_DELETE is SET, then the authorization shall be with platformAuth or the TPM 31821shall return TPM_RC_ATTRIBUTES. 31822If the implementation does not support TPM2_NV_Increment(), 31823TPM_RC_ATTRIBUTES if TPMA_NV_COUNTER is SET. 31824 31825the 31826 31827TPM 31828 31829shall 31830 31831return 31832 31833If the implementation does not support TPM2_NV_SetBits(), 31834TPM_RC_ATTRIBUTES if TPMA_NV_BITS is SET. 31835 31836the 31837 31838TPM 31839 31840shall 31841 31842return 31843 31844If the implementation does not support TPM2_NV_Extend(), 31845TPM_RC_ATTRIBUTES if TPMA_NV_EXTEND is SET. 31846 31847the 31848 31849TPM 31850 31851shall 31852 31853return 31854 31855If the implementation does not support TPM2_NV_UndefineSpaceSpecial(), the TPM shall return 31856TPM_RC_ATTRIBUTES if TPMA_NV_POLICY_DELETE is SET. 31857After the successful completion of this command, the NV Index exists but TPMA_NV_WRITTEN will be 31858CLEAR. Any access of the NV data will return TPM_RC_NV_UINITIALIZED. 31859 31860Page 394 31861October 31, 2013 31862 31863Published 31864Copyright © TCG 2006-2013 31865 31866Family “2.0” 31867Level 00 Revision 00.99 31868 31869 Trusted Platform Module Library 31870 31871Part 3: Commands 31872 31873In some implementations, an NV Index with the TPMA_NV_COUNTER attribute may require special TPM 31874resources that provide higher endurance than regular NV. For those implementations, if this command 31875fails because of lack of resources, the TPM will return TPM_RC_NV_SPACE. 31876The value of auth is saved in the created structure. The size of auth is limited to be no larger than the size 31877of the digest produced by the NV Index's nameAlg (TPM_RC_SIZE). 31878 31879Family “2.0” 31880Level 00 Revision 00.99 31881 31882Published 31883Copyright © TCG 2006-2013 31884 31885Page 395 31886October 31, 2013 31887 31888 Part 3: Commands 31889 31890Trusted Platform Module Library 31891 3189233.3.2 Command and Response 31893Table 197 — TPM2_NV_DefineSpace Command 31894Type 31895 31896Name 31897 31898Description 31899 31900TPMI_ST_COMMAND_TAG 31901 31902tag 31903 31904UINT32 31905 31906commandSize 31907 31908TPM_CC 31909 31910commandCode 31911 31912TPM_CC_NV_DefineSpace {NV} 31913 31914TPMI_RH_PROVISION 31915 31916@authHandle 31917 31918TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 31919Auth Index: 1 31920Auth Role: USER 31921 31922TPM2B_AUTH 31923 31924auth 31925 31926the authorization value 31927 31928TPM2B_NV_PUBLIC 31929 31930publicInfo 31931 31932the public parameters of the NV area 31933 31934Table 198 — TPM2_NV_DefineSpace Response 31935Type 31936 31937Name 31938 31939Description 31940 31941TPM_ST 31942 31943tag 31944 31945see clause 8 31946 31947UINT32 31948 31949responseSize 31950 31951TPM_RC 31952 31953responseCode 31954 31955Page 396 31956October 31, 2013 31957 31958Published 31959Copyright © TCG 2006-2013 31960 31961Family “2.0” 31962Level 00 Revision 00.99 31963 31964 Trusted Platform Module Library 31965 31966Part 3: Commands 31967 3196833.3.3 Detailed Actions 319691 319702 31971 31972#include "InternalRoutines.h" 31973#include "NV_DefineSpace_fp.h" 31974Error Returns 31975TPM_RC_NV_ATTRIBUTES 31976 31977attributes of the index are not consistent 31978 31979TPM_RC_NV_DEFINED 31980 31981index already exists 31982 31983TPM_RC_HIERARCHY 31984 31985for authorizations using TPM_RH_PLATFORM phEnable_NV is 31986clear. 31987 31988TPM_RC_NV_SPACE 31989 31990Insufficient space for the index 31991 31992TPM_RC_SIZE 31993 319943 319954 319965 319976 319987 319998 320009 3200110 3200211 3200312 3200413 3200514 3200615 3200716 3200817 3200918 3201019 3201120 3201221 3201322 3201423 3201524 3201625 3201726 3201827 3201928 3202029 3202130 3202231 3202332 3202433 3202534 3202635 3202736 3202837 3202938 3203039 3203140 3203241 3203342 3203443 3203544 32036 32037Meaning 32038 32039'auth->size' or 'publicInfo->authPolicy. size' is larger than the digest 32040size of 'publicInfo->nameAlg', or 'publicInfo->dataSize' is not 32041consistent with 'publicInfo->attributes'. 32042 32043TPM_RC 32044TPM2_NV_DefineSpace( 32045NV_DefineSpace_In 32046 32047*in 32048 32049// IN: input parameter list 32050 32051) 32052{ 32053TPM_RC 32054TPMA_NV 32055UINT16 32056 32057result; 32058attributes; 32059nameSize; 32060 32061nameSize = CryptGetHashDigestSize(in->publicInfo.t.nvPublic.nameAlg); 32062// Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE 32063// TPM_RC_NV_RATE or TPM_RC_SUCCESS. 32064result = NvIsAvailable(); 32065if(result != TPM_RC_SUCCESS) 32066return result; 32067// Input Validation 32068// If an index is being created by the owner and shEnable is 32069// clear, then we would not reach this point because ownerAuth 32070// can't be given when shEnable is CLEAR. However, if phEnable 32071// is SET but phEnableNV is CLEAR, we have to check here 32072if(in->authHandle == TPM_RH_PLATFORM && gc.phEnableNV == CLEAR) 32073return TPM_RC_HIERARCHY + RC_NV_DefineSpace_authHandle; 32074attributes = in->publicInfo.t.nvPublic.attributes; 32075//TPMS_NV_PUBLIC validation. 32076// Counters and bit fields must have a size of 8 32077if ( 32078(attributes.TPMA_NV_COUNTER == SET || attributes.TPMA_NV_BITS == SET) 32079&& (in->publicInfo.t.nvPublic.dataSize != 8)) 32080return TPM_RC_SIZE + RC_NV_DefineSpace_publicInfo; 32081// check that the authPolicy consistent with hash algorithm 32082if( 32083in->publicInfo.t.nvPublic.authPolicy.t.size != 0 32084&& in->publicInfo.t.nvPublic.authPolicy.t.size != nameSize) 32085return TPM_RC_SIZE + RC_NV_DefineSpace_publicInfo; 32086// make sure that the authValue is not too large 32087MemoryRemoveTrailingZeros(&in->auth); 32088if(in->auth.t.size > nameSize) 32089return TPM_RC_SIZE + RC_NV_DefineSpace_auth; 32090 32091Family “2.0” 32092Level 00 Revision 00.99 32093 32094Published 32095Copyright © TCG 2006-2013 32096 32097Page 397 32098October 31, 2013 32099 32100 Part 3: Commands 3210145 3210246 3210347 3210448 3210549 3210650 3210751 3210852 3210953 3211054 3211155 3211256 3211357 3211458 3211559 3211660 3211761 3211862 3211963 3212064 3212165 3212266 3212367 3212468 3212569 3212670 3212771 3212872 3212973 3213074 3213175 3213276 3213377 3213478 3213579 3213680 3213781 3213882 3213983 3214084 3214185 3214286 3214387 3214488 3214589 3214690 3214791 3214892 3214993 3215094 3215195 3215296 3215397 3215498 3215599 32156100 32157101 32158102 32159103 32160104 32161105 32162106 32163107 32164108 32165 32166Trusted Platform Module Library 32167 32168//TPMA_NV validation. 32169// Locks may not be SET and written cannot be SET 32170if( 32171attributes.TPMA_NV_WRITTEN == SET 32172|| attributes.TPMA_NV_WRITELOCKED == SET 32173|| attributes.TPMA_NV_READLOCKED == SET) 32174return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32175// There must be a way to read the index 32176if( 32177attributes.TPMA_NV_OWNERREAD == CLEAR 32178&& attributes.TPMA_NV_PPREAD == CLEAR 32179&& attributes.TPMA_NV_AUTHREAD == CLEAR 32180&& attributes.TPMA_NV_POLICYREAD == CLEAR) 32181return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32182// There must be a way to write the index 32183if( 32184attributes.TPMA_NV_OWNERWRITE == CLEAR 32185&& attributes.TPMA_NV_PPWRITE == CLEAR 32186&& attributes.TPMA_NV_AUTHWRITE == CLEAR 32187&& attributes.TPMA_NV_POLICYWRITE == CLEAR) 32188return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32189// Make sure that no attribute is used that is not supported by the proper 32190// command 32191#if CC_NV_Increment == NO 32192if( attributes.TPMA_NV_COUNTER == SET) 32193return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32194#endif 32195#if CC_NV_SetBits == NO 32196if( attributes.TPMA_NV_BITS == SET) 32197return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32198#endif 32199#if CC_NV_Extend == NO 32200if( attributes.TPMA_NV_EXTEND == SET) 32201return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32202#endif 32203#if CC_NV_UndefineSpaceSpecial == NO 32204if( attributes.TPMA_NV_POLICY_DELETE == SET) 32205return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32206#endif 32207// Can be COUNTER or BITS or EXTEND but not more than one 32208if( attributes.TPMA_NV_COUNTER == SET 32209&& attributes.TPMA_NV_BITS == SET) 32210return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32211if( 32212attributes.TPMA_NV_COUNTER == SET 32213&& attributes.TPMA_NV_EXTEND == SET) 32214return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32215if( 32216attributes.TPMA_NV_BITS == SET 32217&& attributes.TPMA_NV_EXTEND == SET) 32218return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32219// An index with TPMA_NV_CLEAR_STCLEAR can't be a counter 32220if( 32221attributes.TPMA_NV_CLEAR_STCLEAR == SET 32222&& attributes.TPMA_NV_COUNTER == SET) 32223return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32224// The index is allowed to have one of GLOBALLOCK or WRITEDEFINE SET 32225if( 32226attributes.TPMA_NV_GLOBALLOCK == SET 32227&& attributes.TPMA_NV_WRITEDEFINE == SET) 32228return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32229// Make sure that the creator of the index can delete the index 32230 32231Page 398 32232October 31, 2013 32233 32234Published 32235Copyright © TCG 2006-2013 32236 32237Family “2.0” 32238Level 00 Revision 00.99 32239 32240 Trusted Platform Module Library 32241109 32242110 32243111 32244112 32245113 32246114 32247115 32248116 32249117 32250118 32251119 32252120 32253121 32254122 32255123 32256124 32257125 32258126 32259127 32260128 32261129 32262130 32263131 32264132 32265133 32266134 32267135 32268136 32269137 32270138 32271139 32272140 32273141 32274142 32275143 32276144 32277 32278if( 32279 32280Part 3: Commands 32281 32282( 32283 32284in->publicInfo.t.nvPublic.attributes.TPMA_NV_PLATFORMCREATE == SET 32285&& in->authHandle == TPM_RH_OWNER 32286) 32287|| ( 32288in->publicInfo.t.nvPublic.attributes.TPMA_NV_PLATFORMCREATE == CLEAR 32289&& in->authHandle == TPM_RH_PLATFORM 32290) 32291) 32292return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_authHandle; 32293 32294// If TPMA_NV_POLICY_DELETE is SET, then the index must be defined by 32295// the platform 32296if( 32297in->publicInfo.t.nvPublic.attributes.TPMA_NV_POLICY_DELETE == SET 32298&& TPM_RH_PLATFORM != in->authHandle 32299) 32300return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32301// If the NV index is used as a PCR, the data size must match the digest 32302// size 32303if( 32304in->publicInfo.t.nvPublic.attributes.TPMA_NV_EXTEND == SET 32305&& in->publicInfo.t.nvPublic.dataSize != nameSize 32306) 32307return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32308// See if the index is already defined. 32309if(NvIsUndefinedIndex(in->publicInfo.t.nvPublic.nvIndex)) 32310return TPM_RC_NV_DEFINED; 32311// Internal Data Update 32312// define the space. A TPM_RC_NV_SPACE error may be returned at this point 32313result = NvDefineIndex(&in->publicInfo.t.nvPublic, &in->auth); 32314if(result != TPM_RC_SUCCESS) 32315return result; 32316return TPM_RC_SUCCESS; 32317} 32318 32319Family “2.0” 32320Level 00 Revision 00.99 32321 32322Published 32323Copyright © TCG 2006-2013 32324 32325Page 399 32326October 31, 2013 32327 32328 Part 3: Commands 32329 3233033.4 32331 32332Trusted Platform Module Library 32333 32334TPM2_NV_UndefineSpace 32335 3233633.4.1 General Description 32337This command removes an Index from the TPM. 32338If nvIndex is not defined, the TPM shall return TPM_RC_HANDLE. 32339If nvIndex references an Index that has its TPMA_NV_PLATFORMCREATE attribute SET, the TPM shall 32340return TPM_RC_NV_AUTHORITY unless platformAuth is provided. 32341NOTE 32342 32343An Index with TPMA_NV_PLATFORMCREATE CLEAR may be deleted with platformAuth as long as 32344shEnable is SET. If shEnable is CLEAR, indexes created using ownerAuth are not accessible even 32345for deletion by the platform. 32346 32347Page 400 32348October 31, 2013 32349 32350Published 32351Copyright © TCG 2006-2013 32352 32353Family “2.0” 32354Level 00 Revision 00.99 32355 32356 Trusted Platform Module Library 32357 32358Part 3: Commands 32359 3236033.4.2 Command and Response 32361Table 199 — TPM2_NV_UndefineSpace Command 32362Type 32363 32364Name 32365 32366Description 32367 32368TPMI_ST_COMMAND_TAG 32369 32370tag 32371 32372UINT32 32373 32374commandSize 32375 32376TPM_CC 32377 32378commandCode 32379 32380TPM_CC_NV_UndefineSpace {NV} 32381 32382TPMI_RH_PROVISION 32383 32384@authHandle 32385 32386TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 32387Auth Index: 1 32388Auth Role: USER 32389 32390TPMI_RH_NV_INDEX 32391 32392nvIndex 32393 32394the NV Index to remove from NV space 32395Auth Index: None 32396 32397Table 200 — TPM2_NV_UndefineSpace Response 32398Type 32399 32400Name 32401 32402Description 32403 32404TPM_ST 32405 32406tag 32407 32408see clause 8 32409 32410UINT32 32411 32412responseSize 32413 32414TPM_RC 32415 32416responseCode 32417 32418Family “2.0” 32419Level 00 Revision 00.99 32420 32421Published 32422Copyright © TCG 2006-2013 32423 32424Page 401 32425October 31, 2013 32426 32427 Part 3: Commands 32428 32429Trusted Platform Module Library 32430 3243133.4.3 Detailed Actions 324321 324332 32434 32435#include "InternalRoutines.h" 32436#include "NV_UndefineSpace_fp.h" 32437Error Returns 32438TPM_RC_ATTRIBUTES 32439 32440TPMA_NV_POLICY_DELETE is SET in the Index referenced by 32441nvIndex so this command may not be used to delete this Index (see 32442TPM2_NV_UndefineSpaceSpecial()) 32443 32444TPM_RC_NV_AUTHORIZATION 324453 324464 324475 324486 324497 324508 324519 3245210 3245311 3245412 3245513 3245614 3245715 3245816 3245917 3246018 3246119 3246220 3246321 3246422 3246523 3246624 3246725 3246826 3246927 3247028 3247129 3247230 3247331 3247432 3247533 3247634 3247735 3247836 3247937 3248038 32481 32482Meaning 32483 32484attempt to use ownerAuth to delete an index created by the platform 32485 32486TPM_RC 32487TPM2_NV_UndefineSpace( 32488NV_UndefineSpace_In *in 32489 32490// IN: input parameter list 32491 32492) 32493{ 32494TPM_RC 32495NV_INDEX 32496 32497result; 32498nvIndex; 32499 32500// The command needs NV update. Check if NV is available. 32501// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 32502// this point 32503result = NvIsAvailable(); 32504if(result != TPM_RC_SUCCESS) return result; 32505// Input Validation 32506// Get NV index info 32507NvGetIndexInfo(in->nvIndex, &nvIndex); 32508// This command can't be used to delete an index with TPMA_NV_POLICY_DELETE SET 32509if(SET == nvIndex.publicArea.attributes.TPMA_NV_POLICY_DELETE) 32510return TPM_RC_ATTRIBUTES + RC_NV_UndefineSpace_nvIndex; 32511// The owner may only delete an index that was defined with ownerAuth. The 32512// platform may delete an index that was created with either auth. 32513if( 32514in->authHandle == TPM_RH_OWNER 32515&& nvIndex.publicArea.attributes.TPMA_NV_PLATFORMCREATE == SET) 32516return TPM_RC_NV_AUTHORIZATION; 32517// Internal Data Update 32518// Call implementation dependent internal routine to delete NV index 32519NvDeleteEntity(in->nvIndex); 32520return TPM_RC_SUCCESS; 32521} 32522 32523Page 402 32524October 31, 2013 32525 32526Published 32527Copyright © TCG 2006-2013 32528 32529Family “2.0” 32530Level 00 Revision 00.99 32531 32532 Trusted Platform Module Library 32533 3253433.5 32535 32536Part 3: Commands 32537 32538TPM2_NV_UndefineSpaceSpecial 32539 3254033.5.1 General Description 32541This command allows removal of a platform-created NV Index that has TPMA_NV_POLICY_DELETE 32542SET. 32543This command requires that the policy of the NV Index be satisfied before the NV Index may be deleted. 32544Because administrative role is required, the policy must contain a command that sets the policy command 32545code to TPM_CC_NV_UndefineSpaceSpecial. This indicates that the policy that is being used is a policy 32546that is for this command, and not a policy that would approve another use. That is, authority to use an 32547object does not grant authority to undefined the object. 32548If nvIndex is not defined, the TPM shall return TPM_RC_HANDLE. 32549If 32550nvIndex 32551references 32552an 32553Index 32554that 32555has 32556its 32557TPMA_NV_PLATFORMCREATE 32558TPMA_NV_POLICY_DELETE attribute CLEAR, the TPM shall return TPM_RC_NV_ATTRIBUTES. 32559NOTE 32560 32561or 32562 32563An 32564Index 32565with 32566TPMA_NV_PLATFORMCREATE 32567CLEAR 32568may 32569be 32570deleted 32571with 32572TPM2_UndefineSpace()as long as shEnable is SET. If shEnable is CLEAR, indexes created using 32573ownerAuth are not accessible even for deletion by the platform . 32574 32575Family “2.0” 32576Level 00 Revision 00.99 32577 32578Published 32579Copyright © TCG 2006-2013 32580 32581Page 403 32582October 31, 2013 32583 32584 Part 3: Commands 32585 32586Trusted Platform Module Library 32587 3258833.5.2 Command and Response 32589Table 201 — TPM2_NV_UndefineSpaceSpecial Command 32590Type 32591 32592Name 32593 32594Description 32595 32596TPMI_ST_COMMAND_TAG 32597 32598tag 32599 32600UINT32 32601 32602commandSize 32603 32604TPM_CC 32605 32606commandCode 32607 32608TPM_CC_NV_UndefineSpaceSpecial {NV} 32609 32610TPMI_RH_NV_INDEX 32611 32612@nvIndex 32613 32614Index to be deleted 32615Auth Index: 1 32616Auth Role: ADMIN 32617 32618TPMI_RH_PLATFORM 32619 32620@platform 32621 32622TPM_RH_PLATFORM + {PP} 32623Auth Index: 2 32624Auth Role: USER 32625 32626Table 202 — TPM2_NV_UndefineSpaceSpecial Response 32627Type 32628 32629Name 32630 32631Description 32632 32633TPM_ST 32634 32635tag 32636 32637see clause 8 32638 32639UINT32 32640 32641responseSize 32642 32643TPM_RC 32644 32645responseCode 32646 32647Page 404 32648October 31, 2013 32649 32650Published 32651Copyright © TCG 2006-2013 32652 32653Family “2.0” 32654Level 00 Revision 00.99 32655 32656 Trusted Platform Module Library 32657 32658Part 3: Commands 32659 3266033.5.3 Detailed Actions 326611 326622 32663 32664#include "InternalRoutines.h" 32665#include "NV_UndefineSpaceSpecial_fp.h" 32666Error Returns 32667TPM_RC_ATTRIBUTES 32668 326693 326704 326715 326726 326737 326748 326759 3267610 3267711 3267812 3267913 3268014 3268115 3268216 3268317 3268418 3268519 3268620 3268721 3268822 3268923 3269024 3269125 3269226 3269327 3269428 3269529 3269630 3269731 3269832 3269933 32700 32701Meaning 32702TPMA_NV_POLICY_DELETE is not SET in the Index referenced by 32703nvIndex 32704 32705TPM_RC 32706TPM2_NV_UndefineSpaceSpecial( 32707NV_UndefineSpaceSpecial_In *in 32708 32709// IN: input parameter list 32710 32711) 32712{ 32713TPM_RC 32714NV_INDEX 32715 32716result; 32717nvIndex; 32718 32719// The command needs NV update. Check if NV is available. 32720// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 32721// this point 32722result = NvIsAvailable(); 32723if(result != TPM_RC_SUCCESS) 32724return result; 32725// Input Validation 32726// Get NV index info 32727NvGetIndexInfo(in->nvIndex, &nvIndex); 32728// This operation only applies when the TPMA_NV_POLICY_DELETE attribute is SET 32729if(CLEAR == nvIndex.publicArea.attributes.TPMA_NV_POLICY_DELETE) 32730return TPM_RC_ATTRIBUTES + RC_NV_UndefineSpaceSpecial_nvIndex; 32731// Internal Data Update 32732// Call implementation dependent internal routine to delete NV index 32733NvDeleteEntity(in->nvIndex); 32734return TPM_RC_SUCCESS; 32735} 32736 32737Family “2.0” 32738Level 00 Revision 00.99 32739 32740Published 32741Copyright © TCG 2006-2013 32742 32743Page 405 32744October 31, 2013 32745 32746 Part 3: Commands 32747 3274833.6 32749 32750Trusted Platform Module Library 32751 32752TPM2_NV_ReadPublic 32753 3275433.6.1 General Description 32755This command is used to read the public area and Name of an NV Index. The public area of an Index is 32756not privacy-sensitive and no authorization is required to read this data. 32757 32758Page 406 32759October 31, 2013 32760 32761Published 32762Copyright © TCG 2006-2013 32763 32764Family “2.0” 32765Level 00 Revision 00.99 32766 32767 Trusted Platform Module Library 32768 32769Part 3: Commands 32770 3277133.6.2 Command and Response 32772Table 203 — TPM2_NV_ReadPublic Command 32773Type 32774 32775Name 32776 32777Description 32778 32779TPMI_ST_COMMAND_TAG 32780 32781tag 32782 32783UINT32 32784 32785commandSize 32786 32787TPM_CC 32788 32789commandCode 32790 32791TPM_CC_NV_ReadPublic 32792 32793TPMI_RH_NV_INDEX 32794 32795nvIndex 32796 32797the NV Index 32798Auth Index: None 32799 32800Table 204 — TPM2_NV_ReadPublic Response 32801Type 32802 32803Name 32804 32805Description 32806 32807TPM_ST 32808 32809tag 32810 32811see clause 8 32812 32813UINT32 32814 32815responseSize 32816 32817TPM_RC 32818 32819responseCode 32820 32821TPM2B_NV_PUBLIC 32822 32823nvPublic 32824 32825the public area of the NV Index 32826 32827TPM2B_NAME 32828 32829nvName 32830 32831the Name of the nvIndex 32832 32833Family “2.0” 32834Level 00 Revision 00.99 32835 32836Published 32837Copyright © TCG 2006-2013 32838 32839Page 407 32840October 31, 2013 32841 32842 Part 3: Commands 32843 32844Trusted Platform Module Library 32845 3284633.6.3 Detailed Actions 328471 328482 328493 328504 328515 328526 328537 328548 328559 3285610 3285711 3285812 3285913 3286014 3286115 3286216 3286317 3286418 3286519 3286620 3286721 3286822 3286923 32870 32871#include "InternalRoutines.h" 32872#include "NV_ReadPublic_fp.h" 32873 32874TPM_RC 32875TPM2_NV_ReadPublic( 32876NV_ReadPublic_In 32877NV_ReadPublic_Out 32878 32879*in, 32880*out 32881 32882// IN: input parameter list 32883// OUT: output parameter list 32884 32885) 32886{ 32887NV_INDEX 32888 32889nvIndex; 32890 32891// Command Output 32892// Get NV index info 32893NvGetIndexInfo(in->nvIndex, &nvIndex); 32894// Copy data to output 32895out->nvPublic.t.nvPublic = nvIndex.publicArea; 32896// Compute NV name 32897out->nvName.t.size = NvGetName(in->nvIndex, &out->nvName.t.name); 32898return TPM_RC_SUCCESS; 32899} 32900 32901Page 408 32902October 31, 2013 32903 32904Published 32905Copyright © TCG 2006-2013 32906 32907Family “2.0” 32908Level 00 Revision 00.99 32909 32910 Trusted Platform Module Library 32911 3291233.7 32913 32914Part 3: Commands 32915 32916TPM2_NV_Write 32917 3291833.7.1 General Description 32919This command writes a value to an area in NV memory that was previously defined by 32920TPM2_NV_DefineSpace(). 32921Proper authorizations are required for this command as determined by TPMA_NV_PPWRITE; 32922TPMA_NV_OWNERWRITE; TPMA_NV_AUTHWRITE; and, if TPMA_NV_POLICY_WRITE is SET, the 32923authPolicy of the NV Index. 32924If the TPMA_NV_WRITELOCKED attribute of the NV Index is SET, then the TPM shall return 32925TPM_RC_NV_LOCKED. 32926NOTE 1 32927 32928If authorization sessions are present, they are checked before checks to see if writes to the NV 32929Index are locked. 32930 32931If TPMA_NV_COUNTER, TPMA_NV_BITS or TPMA_NV_EXTEND of the NV Index is SET, then the 32932TPM shall return TPM_RC_NV_ATTRIBUTE. 32933If the size of the data parameter plus the offset parameter adds to a value that is greater than the size of 32934the NV Index data, the TPM shall return TPM_RC_NV_RANGE and not write any data to the NV Index. 32935If the TPMA_NV_WRITEALL attribute of the NV Index is SET, then the TPM shall return 32936TPM_RC_NV_RANGE if the size of the data parameter of the command is not the same as the data field 32937of the NV Index. 32938If all checks succeed, the TPM will merge the data.size octets of data.buffer value into the nvIndex→data 32939starting at nvIndex→data[offset]. If the NV memory is implemented with a technology that has endurance 32940limitations, the TPM shall check that the merged data is different from the current contents of the NV 32941Index and only perform a write to NV memory if they differ. 32942After successful completion of this command, TPMA_NV_WRITTEN for the NV Index will be SET. 32943NOTE 2 32944 32945Once SET, TPMA_NV_WRITTEN remains SET until the NV Index is undefined or the NV Index is 32946cleared. 32947 32948Family “2.0” 32949Level 00 Revision 00.99 32950 32951Published 32952Copyright © TCG 2006-2013 32953 32954Page 409 32955October 31, 2013 32956 32957 Part 3: Commands 32958 32959Trusted Platform Module Library 32960 3296133.7.2 Command and Response 32962Table 205 — TPM2_NV_Write Command 32963Type 32964 32965Name 32966 32967Description 32968 32969TPMI_ST_COMMAND_TAG 32970 32971tag 32972 32973UINT32 32974 32975commandSize 32976 32977TPM_CC 32978 32979commandCode 32980 32981TPM_CC_NV_Write {NV} 32982 32983TPMI_RH_NV_AUTH 32984 32985@authHandle 32986 32987handle indicating the source of the authorization value 32988Auth Index: 1 32989Auth Role: USER 32990 32991TPMI_RH_NV_INDEX 32992 32993nvIndex 32994 32995the NV Index of the area to write 32996Auth Index: None 32997 32998TPM2B_MAX_NV_BUFFER 32999 33000data 33001 33002the data to write 33003 33004UINT16 33005 33006offset 33007 33008the offset into the NV Area 33009 33010Table 206 — TPM2_NV_Write Response 33011Type 33012 33013Name 33014 33015Description 33016 33017TPM_ST 33018 33019tag 33020 33021see clause 8 33022 33023UINT32 33024 33025responseSize 33026 33027TPM_RC 33028 33029responseCode 33030 33031Page 410 33032October 31, 2013 33033 33034Published 33035Copyright © TCG 2006-2013 33036 33037Family “2.0” 33038Level 00 Revision 00.99 33039 33040 Trusted Platform Module Library 33041 33042Part 3: Commands 33043 3304433.7.3 Detailed Actions 330451 330462 330473 33048 33049#include "InternalRoutines.h" 33050#include "NV_Write_fp.h" 33051#include "NV_spt_fp.h" 33052Error Returns 33053TPM_RC_ATTRIBUTES 33054 33055Index referenced by nvIndex has either TPMA_NV_BITS, 33056TPMA_NV_COUNTER, or TPMA_NV_EVENT attribute SET 33057 33058TPM_RC_NV_AUTHORIZATION 33059 33060the authorization was valid but the authorizing entity (authHandle) is 33061not allowed to write to the Index referenced by nvIndex 33062 33063TPM_RC_NV_LOCKED 33064 33065Index referenced by nvIndex is write locked 33066 33067TPM_RC_NV_RANGE 33068 330694 330705 330716 330727 330738 330749 3307510 3307611 3307712 3307813 3307914 3308015 3308116 3308217 3308318 3308419 3308520 3308621 3308722 3308823 3308924 3309025 3309126 3309227 3309328 3309429 3309530 3309631 3309732 3309833 3309934 3310035 3310136 3310237 3310338 3310439 3310540 3310641 3310742 3310843 3310944 3311045 33111 33112Meaning 33113 33114if TPMA_NV_WRITEALL is SET then the write is not the size of the 33115Index referenced by nvIndex; otherwise, the write extends beyond the 33116limits of the Index 33117 33118TPM_RC 33119TPM2_NV_Write( 33120NV_Write_In 33121 33122*in 33123 33124// IN: input parameter list 33125 33126) 33127{ 33128NV_INDEX 33129TPM_RC 33130 33131nvIndex; 33132result; 33133 33134// Input Validation 33135// Get NV index info 33136NvGetIndexInfo(in->nvIndex, &nvIndex); 33137// common access checks. NvWrtieAccessChecks() may return 33138// TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED 33139result = NvWriteAccessChecks(in->authHandle, in->nvIndex); 33140if(result != TPM_RC_SUCCESS) 33141return result; 33142// Bits index, extend index or counter index may not be updated by 33143// TPM2_NV_Write 33144if( 33145nvIndex.publicArea.attributes.TPMA_NV_COUNTER == SET 33146|| nvIndex.publicArea.attributes.TPMA_NV_BITS == SET 33147|| nvIndex.publicArea.attributes.TPMA_NV_EXTEND == SET) 33148return TPM_RC_ATTRIBUTES; 33149// Too much data 33150if((in->data.t.size + in->offset) > nvIndex.publicArea.dataSize) 33151return TPM_RC_NV_RANGE; 33152// If this index requires a full sized write, make sure that input range is 33153// full sized 33154if( 33155nvIndex.publicArea.attributes.TPMA_NV_WRITEALL == SET 33156&& in->data.t.size < nvIndex.publicArea.dataSize) 33157return TPM_RC_NV_RANGE; 33158// Internal Data Update 33159// Perform the write. This called routine will SET the TPMA_NV_WRITTEN 33160// attribute if it has not already been SET. If NV isn't available, an error 33161// will be returned. 33162return NvWriteIndexData(in->nvIndex, &nvIndex, in->offset, 33163 33164Family “2.0” 33165Level 00 Revision 00.99 33166 33167Published 33168Copyright © TCG 2006-2013 33169 33170Page 411 33171October 31, 2013 33172 33173 Part 3: Commands 3317446 3317547 3317648 33177 33178Trusted Platform Module Library 33179in->data.t.size, in->data.t.buffer); 33180 33181} 33182 33183Page 412 33184October 31, 2013 33185 33186Published 33187Copyright © TCG 2006-2013 33188 33189Family “2.0” 33190Level 00 Revision 00.99 33191 33192 Trusted Platform Module Library 33193 3319433.8 33195 33196Part 3: Commands 33197 33198TPM2_NV_Increment 33199 3320033.8.1 General Description 33201This command is used to increment the value in an NV Index that has TPMA_NV_COUNTER SET. The 33202data value of the NV Index is incremented by one. 33203NOTE 1 33204 33205The NV Index counter is an unsigned value. 33206 33207If TPMA_NV_COUNTER 33208TPM_RC_ATTRIBUTES. 33209 33210is 33211 33212not 33213 33214SET 33215 33216in 33217 33218the 33219 33220indicated 33221 33222NV 33223 33224Index, 33225 33226the 33227 33228TPM 33229 33230shall 33231 33232return 33233 33234If TPMA_NV_WRITELOCKED is SET, the TPM shall return TPM_RC_NV_LOCKED. 33235If TPMA_NV_WRITTEN is CLEAR, it will be SET. 33236If TPMA_NV_ORDERLY is SET, and the difference between the volatile and non-volatile versions of this 33237field is greater than MAX_ORDERLY_COUNT, then the non-volatile version of the counter is updated. 33238NOTE 2 33239 33240If a TPM implements TPMA_NV_ORDERLY and an Index is defined with TPMA_NV_ORDERLY and 33241TPM_NV_COUNTER both SET, then in the Event of a non-orderly shutdown, the non-volatile value 33242for the counter Index will be advanced by MAX_ORDERLY_COUNT at the next TPM2_Startup(). 33243 33244NOTE 3 33245 33246An allowed implementation would keep a counter value in NV and a resettable counter in RAM. The 33247reported value of the NV Index would be the sum of the two values. When the RAM count increments 33248past the maximum allowed value (MAX_ORDERLY_COUNT), the non-volatile version of the count is 33249updated with the sum of the values and the RAM count is reset to zero. 33250 33251Family “2.0” 33252Level 00 Revision 00.99 33253 33254Published 33255Copyright © TCG 2006-2013 33256 33257Page 413 33258October 31, 2013 33259 33260 Part 3: Commands 33261 33262Trusted Platform Module Library 33263 3326433.8.2 Command and Response 33265Table 207 — TPM2_NV_Increment Command 33266Type 33267 33268Name 33269 33270Description 33271 33272TPMI_ST_COMMAND_TAG 33273 33274tag 33275 33276UINT32 33277 33278commandSize 33279 33280TPM_CC 33281 33282commandCode 33283 33284TPM_CC_NV_Increment {NV} 33285 33286TPMI_RH_NV_AUTH 33287 33288@authHandle 33289 33290handle indicating the source of the authorization value 33291Auth Index: 1 33292Auth Role: USER 33293 33294TPMI_RH_NV_INDEX 33295 33296nvIndex 33297 33298the NV Index to increment 33299Auth Index: None 33300 33301Table 208 — TPM2_NV_Increment Response 33302Type 33303 33304Name 33305 33306Description 33307 33308TPM_ST 33309 33310tag 33311 33312see clause 8 33313 33314UINT32 33315 33316responseSize 33317 33318TPM_RC 33319 33320responseCode 33321 33322Page 414 33323October 31, 2013 33324 33325Published 33326Copyright © TCG 2006-2013 33327 33328Family “2.0” 33329Level 00 Revision 00.99 33330 33331 Trusted Platform Module Library 33332 33333Part 3: Commands 33334 3333533.8.3 Detailed Actions 333361 333372 333383 33339 33340#include "InternalRoutines.h" 33341#include "NV_Increment_fp.h" 33342#include "NV_spt_fp.h" 33343Error Returns 33344TPM_RC_ATTRIBUTES 33345 33346NV index is not a counter 33347 33348TPM_RC_NV_AUTHORIZATION 33349 33350authorization failure 33351 33352TPM_RC_NV_LOCKED 333534 333545 333556 333567 333578 333589 3335910 3336011 3336112 3336213 3336314 3336415 3336516 3336617 3336718 3336819 3336920 3337021 3337122 3337223 3337324 3337425 3337526 3337627 3337728 3337829 3337930 3338031 3338132 3338233 3338334 3338435 3338536 3338637 3338738 3338839 3338940 3339041 3339142 3339243 3339344 3339445 3339546 3339647 3339748 3339849 3339950 3340051 33401 33402Meaning 33403 33404Index is write locked 33405 33406TPM_RC 33407TPM2_NV_Increment( 33408NV_Increment_In 33409 33410*in 33411 33412// IN: input parameter list 33413 33414) 33415{ 33416TPM_RC 33417NV_INDEX 33418UINT64 33419 33420result; 33421nvIndex; 33422countValue; 33423 33424// Input Validation 33425// Common access checks, a TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED 33426// error may be returned at this point 33427result = NvWriteAccessChecks(in->authHandle, in->nvIndex); 33428if(result != TPM_RC_SUCCESS) 33429return result; 33430// Get NV index info 33431NvGetIndexInfo(in->nvIndex, &nvIndex); 33432// Make sure that this is a counter 33433if(nvIndex.publicArea.attributes.TPMA_NV_COUNTER != SET) 33434return TPM_RC_ATTRIBUTES + RC_NV_Increment_nvIndex; 33435// Internal Data Update 33436// If counter index is not been written, initialize it 33437if(nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR) 33438countValue = NvInitialCounter(); 33439else 33440// Read NV data in native format for TPM CPU. 33441NvGetIntIndexData(in->nvIndex, &nvIndex, &countValue); 33442// Do the increment 33443countValue++; 33444// If this is an orderly counter that just rolled over, need to be able to 33445// write to NV to proceed. This check is done here, because NvWriteIndexData() 33446// does not see if the update is for counter rollover. 33447if( 33448nvIndex.publicArea.attributes.TPMA_NV_ORDERLY == SET 33449&& (countValue & MAX_ORDERLY_COUNT) == 0) 33450{ 33451result = NvIsAvailable(); 33452if(result != TPM_RC_SUCCESS) 33453return result; 33454// Need to force an NV update 33455 33456Family “2.0” 33457Level 00 Revision 00.99 33458 33459Published 33460Copyright © TCG 2006-2013 33461 33462Page 415 33463October 31, 2013 33464 33465 Part 3: Commands 3346652 3346753 3346854 3346955 3347056 3347157 3347258 3347359 3347460 33475 33476Trusted Platform Module Library 33477 33478g_updateNV = TRUE; 33479} 33480// Write NV data back. A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may 33481// be returned at this point. If necessary, this function will set the 33482// TPMA_NV_WRITTEN attribute 33483return NvWriteIndexData(in->nvIndex, &nvIndex, 0, 8, &countValue); 33484} 33485 33486Page 416 33487October 31, 2013 33488 33489Published 33490Copyright © TCG 2006-2013 33491 33492Family “2.0” 33493Level 00 Revision 00.99 33494 33495 Trusted Platform Module Library 33496 3349733.9 33498 33499Part 3: Commands 33500 33501TPM2_NV_Extend 33502 3350333.9.1 General Description 33504This command extends a value to an area in NV memory that was previously defined by 33505TPM2_NV_DefineSpace. 33506If TPMA_NV_EXTEND is not SET, then the TPM shall return TPM_RC_ATTRIBUTES. 33507Proper write authorizations are required for this command as determined by TPMA_NV_PPWRITE, 33508TPMA_NV_OWNERWRITE, TPMA_NV_AUTHWRITE, and the authPolicy of the NV Index. 33509After successful completion of this command, TPMA_NV_WRITTEN for the NV Index will be SET. 33510NOTE 1 33511 33512Once SET, TPMA_NV_WRITTEN remains SET until the NV Index is undefined or the NV Index is 33513cleared. 33514 33515If the TPMA_NV_WRITELOCKED attribute of the NV Index is SET, then the TPM shall return 33516TPM_RC_NV_LOCKED. 33517NOTE 2 33518 33519If authorization sessions are present, they are checked before checks to see if writes to the NV 33520Index are locked. 33521 33522The data.buffer parameter may be larger than the defined size of the NV Index. 33523The Index will be updated by: 33524 33525nvIndex→datanew ≔ HnameAkg(nvIndex→dataold || data.buffer) 33526 33527(39) 33528 33529where 33530 33531HnameAkg() 33532 33533the hash algorithm indicated in nvIndex→nameAlg 33534 33535nvIndex→data 33536 33537the value of the data field in the NV Index 33538 33539data.buffer 33540 33541the data buffer of the command parameter 33542 33543NOTE 3 33544 33545If TPMA_NV_WRITTEN is CLEAR, then nvIndex→data is a Zero Digest. 33546 33547Family “2.0” 33548Level 00 Revision 00.99 33549 33550Published 33551Copyright © TCG 2006-2013 33552 33553Page 417 33554October 31, 2013 33555 33556 Part 3: Commands 33557 33558Trusted Platform Module Library 33559 3356033.9.2 Command and Response 33561Table 209 — TPM2_NV_Extend Command 33562Type 33563 33564Name 33565 33566Description 33567 33568TPMI_ST_COMMAND_TAG 33569 33570tag 33571 33572UINT32 33573 33574commandSize 33575 33576TPM_CC 33577 33578commandCode 33579 33580TPM_CC_NV_Extend {NV} 33581 33582TPMI_RH_NV_AUTH 33583 33584@authHandle 33585 33586handle indicating the source of the authorization value 33587Auth Index: 1 33588Auth Role: USER 33589 33590TPMI_RH_NV_INDEX 33591 33592nvIndex 33593 33594the NV Index to extend 33595Auth Index: None 33596 33597TPM2B_MAX_NV_BUFFER 33598 33599data 33600 33601the data to extend 33602 33603Table 210 — TPM2_NV_Extend Response 33604Type 33605 33606Name 33607 33608Description 33609 33610TPM_ST 33611 33612tag 33613 33614see clause 8 33615 33616UINT32 33617 33618responseSize 33619 33620TPM_RC 33621 33622responseCode 33623 33624Page 418 33625October 31, 2013 33626 33627Published 33628Copyright © TCG 2006-2013 33629 33630Family “2.0” 33631Level 00 Revision 00.99 33632 33633 Trusted Platform Module Library 33634 33635Part 3: Commands 33636 3363733.9.3 Detailed Actions 336381 336392 336403 33641 33642#include "InternalRoutines.h" 33643#include "NV_Extend_fp.h" 33644#include "NV_spt_fp.h" 33645Error Returns 33646TPM_RC_ATTRIBUTES 33647 33648the TPMA_NV_EXTEND attribute is not SET in the Index referenced 33649by nvIndex 33650 33651TPM_RC_NV_AUTHORIZATION 33652 33653the authorization was valid but the authorizing entity (authHandle) is 33654not allowed to write to the Index referenced by nvIndex 33655 33656TPM_RC_NV_LOCKED 336574 336585 336596 336607 336618 336629 3366310 3366411 3366512 3366613 3366714 3366815 3366916 3367017 3367118 3367219 3367320 3367421 3367522 3367623 3367724 3367825 3367926 3368027 3368128 3368229 3368330 3368431 3368532 3368633 3368734 3368835 3368936 3369037 3369138 3369239 3369340 3369441 3369542 3369643 3369744 3369845 3369946 3370047 3370148 3370249 33703 33704Meaning 33705 33706the Index referenced by nvIndex is locked for writing 33707 33708TPM_RC 33709TPM2_NV_Extend( 33710NV_Extend_In 33711 33712*in 33713 33714// IN: input parameter list 33715 33716) 33717{ 33718TPM_RC 33719NV_INDEX 33720 33721result; 33722nvIndex; 33723 33724TPM2B_DIGEST 33725TPM2B_DIGEST 33726HASH_STATE 33727 33728oldDigest; 33729newDigest; 33730hashState; 33731 33732// Input Validation 33733// Common access checks, NvWriteAccessCheck() may return TPM_RC_NV_AUTHORIZATION 33734// or TPM_RC_NV_LOCKED 33735result = NvWriteAccessChecks(in->authHandle, in->nvIndex); 33736if(result != TPM_RC_SUCCESS) 33737return result; 33738// Get NV index info 33739NvGetIndexInfo(in->nvIndex, &nvIndex); 33740// Make sure that this is an extend index 33741if(nvIndex.publicArea.attributes.TPMA_NV_EXTEND != SET) 33742return TPM_RC_ATTRIBUTES + RC_NV_Extend_nvIndex; 33743// If the Index is not-orderly, or if this is the first write, NV will 33744// need to be updated. 33745if( 33746nvIndex.publicArea.attributes.TPMA_NV_ORDERLY == CLEAR 33747|| nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR) 33748{ 33749// Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE 33750// TPM_RC_NV_RATE or TPM_RC_SUCCESS. 33751result = NvIsAvailable(); 33752if(result != TPM_RC_SUCCESS) 33753return result; 33754} 33755// Internal Data Update 33756// Perform the write. 33757oldDigest.t.size = CryptGetHashDigestSize(nvIndex.publicArea.nameAlg); 33758if(nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == SET) 33759{ 33760NvGetIndexData(in->nvIndex, &nvIndex, 0, 33761 33762Family “2.0” 33763Level 00 Revision 00.99 33764 33765Published 33766Copyright © TCG 2006-2013 33767 33768Page 419 33769October 31, 2013 33770 33771 Part 3: Commands 3377250 3377351 3377452 3377553 3377654 3377755 3377856 3377957 3378058 3378159 3378260 3378361 3378462 3378563 3378664 3378765 3378866 3378967 3379068 3379169 3379270 3379371 3379472 33795 33796Trusted Platform Module Library 33797 33798oldDigest.t.size, oldDigest.t.buffer); 33799} 33800else 33801{ 33802MemorySet(oldDigest.t.buffer, 0, oldDigest.t.size); 33803} 33804// Start hash 33805newDigest.t.size = CryptStartHash(nvIndex.publicArea.nameAlg, &hashState); 33806// Adding old digest 33807CryptUpdateDigest2B(&hashState, &oldDigest.b); 33808// Adding new data 33809CryptUpdateDigest2B(&hashState, &in->data.b); 33810// Complete hash 33811CryptCompleteHash2B(&hashState, &newDigest.b); 33812// Write extended hash back. 33813// Note, this routine will SET the TPMA_NV_WRITTEN attribute if necessary 33814return NvWriteIndexData(in->nvIndex, &nvIndex, 0, 33815newDigest.t.size, newDigest.t.buffer); 33816} 33817 33818Page 420 33819October 31, 2013 33820 33821Published 33822Copyright © TCG 2006-2013 33823 33824Family “2.0” 33825Level 00 Revision 00.99 33826 33827 Trusted Platform Module Library 33828 33829Part 3: Commands 33830 3383133.10 TPM2_NV_SetBits 3383233.10.1 33833 33834General Description 33835 33836This command is used to SET bits in an NV Index that was created as a bit field. Any number of bits from 338370 to 64 may be SET. The contents of data are ORed with the current contents of the NV Index starting at 33838offset. The checks on data and offset are the same as for TPM2_NV_Write. 33839If TPMA_NV_WRITTEN is not SET, then, for the purposes of this command, the NV Index is considered 33840to contain all zero bits and data is OR with that value. 33841If TPMA_NV_BITS is not SET, then the TPM shall return TPM_RC_ATTRIBUTES. 33842After successful completion of this command, TPMA_NV_WRITTEN for the NV Index will be SET. 33843NOTE 33844 33845TPMA_NV_WRITTEN will be SET even if no bits were SET. 33846 33847Family “2.0” 33848Level 00 Revision 00.99 33849 33850Published 33851Copyright © TCG 2006-2013 33852 33853Page 421 33854October 31, 2013 33855 33856 Part 3: Commands 33857 3385833.10.2 33859 33860Trusted Platform Module Library 33861 33862Command and Response 33863Table 211 — TPM2_NV_SetBits Command 33864 33865Type 33866 33867Name 33868 33869Description 33870 33871TPMI_ST_COMMAND_TAG 33872 33873tag 33874 33875UINT32 33876 33877commandSize 33878 33879TPM_CC 33880 33881commandCode 33882 33883TPM_CC_NV_SetBits {NV} 33884 33885TPMI_RH_NV_AUTH 33886 33887@authHandle 33888 33889handle indicating the source of the authorization value 33890Auth Index: 1 33891Auth Role: USER 33892 33893TPMI_RH_NV_INDEX 33894 33895nvIndex 33896 33897NV Index of the area in which the bit is to be set 33898Auth Index: None 33899 33900UINT64 33901 33902bits 33903 33904the data to OR with the current contents 33905 33906Table 212 — TPM2_NV_SetBits Response 33907Type 33908 33909Name 33910 33911Description 33912 33913TPM_ST 33914 33915tag 33916 33917see clause 8 33918 33919UINT32 33920 33921responseSize 33922 33923TPM_RC 33924 33925responseCode 33926 33927Page 422 33928October 31, 2013 33929 33930Published 33931Copyright © TCG 2006-2013 33932 33933Family “2.0” 33934Level 00 Revision 00.99 33935 33936 Trusted Platform Module Library 33937 3393833.10.3 339391 339402 339413 33942 33943Part 3: Commands 33944 33945Detailed Actions 33946 33947#include "InternalRoutines.h" 33948#include "NV_SetBits_fp.h" 33949#include "NV_spt_fp.h" 33950Error Returns 33951TPM_RC_ATTRIBUTES 33952 33953the TPMA_NV_BITS attribute is not SET in the Index referenced by 33954nvIndex 33955 33956TPM_RC_NV_AUTHORIZATION 33957 33958the authorization was valid but the authorizing entity (authHandle) is 33959not allowed to write to the Index referenced by nvIndex 33960 33961TPM_RC_NV_LOCKED 339624 339635 339646 339657 339668 339679 3396810 3396911 3397012 3397113 3397214 3397315 3397416 3397517 3397618 3397719 3397820 3397921 3398022 3398123 3398224 3398325 3398426 3398527 3398628 3398729 3398830 3398931 3399032 3399133 3399234 3399335 3399436 3399537 3399638 3399739 3399840 3399941 3400042 3400143 3400244 3400345 3400446 3400547 3400648 3400749 34008 34009Meaning 34010 34011the Index referenced by nvIndex is locked for writing 34012 34013TPM_RC 34014TPM2_NV_SetBits( 34015NV_SetBits_In 34016 34017*in 34018 34019// IN: input parameter list 34020 34021) 34022{ 34023TPM_RC 34024NV_INDEX 34025UINT64 34026 34027result; 34028nvIndex; 34029bitValue; 34030 34031// Input Validation 34032// Common access checks, NvWriteAccessCheck() may return TPM_RC_NV_AUTHORIZATION 34033// or TPM_RC_NV_LOCKED 34034// error may be returned at this point 34035result = NvWriteAccessChecks(in->authHandle, in->nvIndex); 34036if(result != TPM_RC_SUCCESS) 34037return result; 34038// Get NV index info 34039NvGetIndexInfo(in->nvIndex, &nvIndex); 34040// Make sure that this is a bit field 34041if(nvIndex.publicArea.attributes.TPMA_NV_BITS != SET) 34042return TPM_RC_ATTRIBUTES + RC_NV_SetBits_nvIndex; 34043// If the Index is not-orderly, or if this is the first write, NV will 34044// need to be updated. 34045if( 34046nvIndex.publicArea.attributes.TPMA_NV_ORDERLY == CLEAR 34047|| nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR) 34048{ 34049// Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE 34050// TPM_RC_NV_RATE or TPM_RC_SUCCESS. 34051result = NvIsAvailable(); 34052if(result != TPM_RC_SUCCESS) 34053return result; 34054} 34055// Internal Data Update 34056// If index is not been written, initialize it 34057if(nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR) 34058bitValue = 0; 34059else 34060// Read index data 34061 34062Family “2.0” 34063Level 00 Revision 00.99 34064 34065Published 34066Copyright © TCG 2006-2013 34067 34068Page 423 34069October 31, 2013 34070 34071 Part 3: Commands 3407250 3407351 3407452 3407553 3407654 3407755 3407856 3407957 3408058 3408159 34082 34083Trusted Platform Module Library 34084 34085NvGetIntIndexData(in->nvIndex, &nvIndex, &bitValue); 34086// OR in the new bit setting 34087bitValue |= in->bits; 34088// Write index data back. If necessary, this function will SET 34089// TPMA_NV_WRITTEN. 34090return NvWriteIndexData(in->nvIndex, &nvIndex, 0, 8, &bitValue); 34091} 34092 34093Page 424 34094October 31, 2013 34095 34096Published 34097Copyright © TCG 2006-2013 34098 34099Family “2.0” 34100Level 00 Revision 00.99 34101 34102 Trusted Platform Module Library 34103 34104Part 3: Commands 34105 3410633.11 TPM2_NV_WriteLock 3410733.11.1 34108 34109General Description 34110 34111If the TPMA_NV_WRITEDEFINE or TPMA_NV_WRITE_STCLEAR attributes of an NV location are SET, 34112then this command may be used to inhibit further writes of the NV Index. 34113Proper write authorization is required for this command as determined by TPMA_NV_PPWRITE, 34114TPMA_NV_OWNERWRITE, TPMA_NV_AUTHWRITE, and the authPolicy of the NV Index. 34115It is not an error if TPMA_NV_WRITELOCKED for the NV Index is already SET. 34116If neither TPMA_NV_WRITEDEFINE nor TPMA_NV_WRITE_STCLEAR of the NV Index is SET, then the 34117TPM shall return TPM_RC_ATTRIBUTES. 34118If the command is properly authorized and TPMA_NV_WRITE_STCLEAR or TPMA_NV_WRITEDEFINE 34119is SET, then the TPM shall SET TPMA_NV_WRITELOCKED for the NV Index. 34120TPMA_NV_WRITELOCKED will be clear on the next TPM2_Startup(TPM_SU_CLEAR) unless 34121TPMA_NV_WRITEDEFINE is SET. 34122 34123Family “2.0” 34124Level 00 Revision 00.99 34125 34126Published 34127Copyright © TCG 2006-2013 34128 34129Page 425 34130October 31, 2013 34131 34132 Part 3: Commands 34133 3413433.11.2 34135 34136Trusted Platform Module Library 34137 34138Command and Response 34139Table 213 — TPM2_NV_WriteLock Command 34140 34141Type 34142 34143Name 34144 34145Description 34146 34147TPMI_ST_COMMAND_TAG 34148 34149tag 34150 34151UINT32 34152 34153commandSize 34154 34155TPM_CC 34156 34157commandCode 34158 34159TPM_CC_NV_WriteLock {NV} 34160 34161TPMI_RH_NV_AUTH 34162 34163@authHandle 34164 34165handle indicating the source of the authorization value 34166Auth Index: 1 34167Auth Role: USER 34168 34169TPMI_RH_NV_INDEX 34170 34171nvIndex 34172 34173the NV Index of the area to lock 34174Auth Index: None 34175 34176Table 214 — TPM2_NV_WriteLock Response 34177Type 34178 34179Name 34180 34181Description 34182 34183TPM_ST 34184 34185tag 34186 34187see clause 8 34188 34189UINT32 34190 34191responseSize 34192 34193TPM_RC 34194 34195responseCode 34196 34197Page 426 34198October 31, 2013 34199 34200Published 34201Copyright © TCG 2006-2013 34202 34203Family “2.0” 34204Level 00 Revision 00.99 34205 34206 Trusted Platform Module Library 34207 3420833.11.3 342091 342102 342113 34212 34213Part 3: Commands 34214 34215Detailed Actions 34216 34217#include "InternalRoutines.h" 34218#include "NV_WriteLock_fp.h" 34219#include "NV_spt_fp.h" 34220Error Returns 34221TPM_RC_ATTRIBUTES 34222 34223neither TPMA_NV_WRITEDEFINE nor 34224TPMA_NV_WRITE_STCLEAR is SET in Index referenced by 34225nvIndex 34226 34227TPM_RC_NV_AUTHORIZATION 34228 342294 342305 342316 342327 342338 342349 3423510 3423611 3423712 3423813 3423914 3424015 3424116 3424217 3424318 3424419 3424520 3424621 3424722 3424823 3424924 3425025 3425126 3425227 3425328 3425429 3425530 3425631 3425732 3425833 3425934 3426035 3426136 3426237 3426338 3426439 3426540 3426641 3426742 3426843 3426944 3427045 3427146 3427247 3427348 3427449 3427550 34276 34277Meaning 34278 34279the authorization was valid but the authorizing entity (authHandle) is 34280not allowed to write to the Index referenced by nvIndex 34281 34282TPM_RC 34283TPM2_NV_WriteLock( 34284NV_WriteLock_In *in 34285 34286// IN: input parameter list 34287 34288) 34289{ 34290TPM_RC 34291NV_INDEX 34292 34293result; 34294nvIndex; 34295 34296// The command needs NV update. Check if NV is available. 34297// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 34298// this point 34299result = NvIsAvailable(); 34300if(result != TPM_RC_SUCCESS) 34301return result; 34302// Input Validation: 34303// Common write access checks, a TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED 34304// error may be returned at this point 34305result = NvWriteAccessChecks(in->authHandle, in->nvIndex); 34306if(result != TPM_RC_SUCCESS) 34307{ 34308if(result == TPM_RC_NV_AUTHORIZATION) 34309return TPM_RC_NV_AUTHORIZATION; 34310// If write access failed because the index is already locked, then it is 34311// no error. 34312return TPM_RC_SUCCESS; 34313} 34314// Get NV index info 34315NvGetIndexInfo(in->nvIndex, &nvIndex); 34316// if non of TPMA_NV_WRITEDEFINE or TPMA_NV_WRITE_STCLEAR is set, the index 34317// can not be write-locked 34318if( 34319nvIndex.publicArea.attributes.TPMA_NV_WRITEDEFINE == CLEAR 34320&& nvIndex.publicArea.attributes.TPMA_NV_WRITE_STCLEAR == CLEAR) 34321return TPM_RC_ATTRIBUTES + RC_NV_WriteLock_nvIndex; 34322// Internal Data Update 34323// Set the WRITELOCK attribute 34324nvIndex.publicArea.attributes.TPMA_NV_WRITELOCKED = SET; 34325// Write index info back 34326NvWriteIndexInfo(in->nvIndex, &nvIndex); 34327 34328Family “2.0” 34329Level 00 Revision 00.99 34330 34331Published 34332Copyright © TCG 2006-2013 34333 34334Page 427 34335October 31, 2013 34336 34337 Part 3: Commands 3433851 3433952 34340 34341Trusted Platform Module Library 34342 34343return TPM_RC_SUCCESS; 34344} 34345 34346Page 428 34347October 31, 2013 34348 34349Published 34350Copyright © TCG 2006-2013 34351 34352Family “2.0” 34353Level 00 Revision 00.99 34354 34355 Trusted Platform Module Library 34356 34357Part 3: Commands 34358 3435933.12 TPM2_NV_GlobalWriteLock 3436033.12.1 34361 34362General Description 34363 34364The command will SET TPMA_NV_WRITELOCKED 34365TPMA_NV_GLOBALLOCK attribute SET. 34366 34367for 34368 34369all 34370 34371indexes 34372 34373that 34374 34375have 34376 34377their 34378 34379If an Index has both TPMA_NV_WRITELOCKED and TPMA_NV_WRITEDEFINE SET, then this 34380command will permanently lock the NV Index for writing. 34381NOTE 34382 34383If an Index is defined with TPMA_NV_GLOBALLOCK SET, then the global lock does not apply until 34384the next time this command is executed. 34385 34386This command requires either platformAuth/platformPolicy or ownerAuth/ownerPolicy. 34387 34388Family “2.0” 34389Level 00 Revision 00.99 34390 34391Published 34392Copyright © TCG 2006-2013 34393 34394Page 429 34395October 31, 2013 34396 34397 Part 3: Commands 34398 3439933.12.2 34400 34401Trusted Platform Module Library 34402 34403Command and Response 34404Table 215 — TPM2_NV_GlobalWriteLock Command 34405 34406Type 34407 34408Name 34409 34410TPMI_ST_COMMAND_TAG 34411 34412tag 34413 34414UINT32 34415 34416commandSize 34417 34418TPM_CC 34419 34420commandCode 34421 34422TPM_CC_NV_GlobalWriteLock 34423 34424TPMI_RH_PROVISION 34425 34426@authHandle 34427 34428TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 34429Auth Index: 1 34430Auth Role: USER 34431 34432Description 34433 34434Table 216 — TPM2_NV_GlobalWriteLock Response 34435Type 34436 34437Name 34438 34439Description 34440 34441TPM_ST 34442 34443tag 34444 34445see clause 8 34446 34447UINT32 34448 34449responseSize 34450 34451TPM_RC 34452 34453responseCode 34454 34455Page 430 34456October 31, 2013 34457 34458Published 34459Copyright © TCG 2006-2013 34460 34461Family “2.0” 34462Level 00 Revision 00.99 34463 34464 Trusted Platform Module Library 34465 3446633.12.3 344671 344682 344693 344704 344715 344726 344737 344748 344759 3447610 3447711 3447812 3447913 3448014 3448115 3448216 3448317 3448418 3448519 3448620 3448721 3448822 3448923 3449024 3449125 3449226 34493 34494Part 3: Commands 34495 34496Detailed Actions 34497 34498#include "InternalRoutines.h" 34499#include "NV_GlobalWriteLock_fp.h" 34500 34501TPM_RC 34502TPM2_NV_GlobalWriteLock( 34503NV_GlobalWriteLock_In *in 34504 34505// IN: input parameter list 34506 34507) 34508{ 34509TPM_RC 34510 34511result; 34512 34513// Input parameter is not reference in command action 34514in = NULL; // to silence compiler warnings. 34515// The command needs NV update. Check if NV is available. 34516// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 34517// this point 34518result = NvIsAvailable(); 34519if(result != TPM_RC_SUCCESS) 34520return result; 34521// Internal Data Update 34522// Implementation dependent method of setting the global lock 34523NvSetGlobalLock(); 34524return TPM_RC_SUCCESS; 34525} 34526 34527Family “2.0” 34528Level 00 Revision 00.99 34529 34530Published 34531Copyright © TCG 2006-2013 34532 34533Page 431 34534October 31, 2013 34535 34536 Part 3: Commands 34537 34538Trusted Platform Module Library 34539 3454033.13 TPM2_NV_Read 3454133.13.1 34542 34543General Description 34544 34545This command reads a 34546TPM2_NV_DefineSpace(). 34547 34548value 34549 34550from 34551 34552an 34553 34554area 34555 34556in 34557 34558NV 34559 34560memory 34561 34562previously 34563 34564defined 34565 34566by 34567 34568Proper authorizations are required for this command as determined by TPMA_NV_PPREAD, 34569TPMA_NV_OWNERREAD, TPMA_NV_AUTHREAD, and the authPolicy of the NV Index. 34570If TPMA_NV_READLOCKED of the NV Index is SET, then the TPM shall return TPM_RC_NV_LOCKED. 34571NOTE 34572 34573If authorization sessions are present, they are checked before the read -lock status of the NV Index 34574is checked. 34575 34576If the size parameter plus the offset parameter adds to a value that is greater than the size of the NV 34577Index data area, the TPM shall return TPM_RC_NV_RANGE and not read any data from the NV Index. 34578If the NV Index has been defined but the TPMA_NV_WRITTEN attribute is CLEAR, then this command 34579shall return TPM_RC_NV_UINITIALIZED even if size is zero. 34580The data parameter in the response may be encrypted using parameter encryption. 34581 34582Page 432 34583October 31, 2013 34584 34585Published 34586Copyright © TCG 2006-2013 34587 34588Family “2.0” 34589Level 00 Revision 00.99 34590 34591 Trusted Platform Module Library 34592 3459333.13.2 34594 34595Part 3: Commands 34596 34597Command and Response 34598Table 217 — TPM2_NV_Read Command 34599 34600Type 34601 34602Name 34603 34604Description 34605 34606TPMI_ST_COMMAND_TAG 34607 34608tag 34609 34610UINT32 34611 34612commandSize 34613 34614TPM_CC 34615 34616commandCode 34617 34618TPM_CC_NV_Read 34619 34620TPMI_RH_NV_AUTH 34621 34622@authHandle 34623 34624the handle indicating the source of the authorization 34625value 34626Auth Index: 1 34627Auth Role: USER 34628 34629TPMI_RH_NV_INDEX 34630 34631nvIndex 34632 34633the NV Index to be read 34634Auth Index: None 34635 34636UINT16 34637 34638size 34639 34640number of octets to read 34641 34642UINT16 34643 34644offset 34645 34646octet offset into the area 34647This value shall be less than or equal to the size of the 34648nvIndex data. 34649 34650Table 218 — TPM2_NV_Read Response 34651Type 34652 34653Name 34654 34655Description 34656 34657TPM_ST 34658 34659tag 34660 34661see clause 8 34662 34663UINT32 34664 34665responseSize 34666 34667TPM_RC 34668 34669responseCode 34670 34671TPM2B_MAX_NV_BUFFER 34672 34673data 34674 34675Family “2.0” 34676Level 00 Revision 00.99 34677 34678the data read 34679 34680Published 34681Copyright © TCG 2006-2013 34682 34683Page 433 34684October 31, 2013 34685 34686 Part 3: Commands 34687 3468833.13.3 346891 346902 346913 34692 34693Trusted Platform Module Library 34694 34695Detailed Actions 34696 34697#include "InternalRoutines.h" 34698#include "NV_Read_fp.h" 34699#include "NV_spt_fp.h" 34700Error Returns 34701TPM_RC_NV_AUTHORIZATION 34702 34703the authorization was valid but the authorizing entity (authHandle) is 34704not allowed to read from the Index referenced by nvIndex 34705 34706TPM_RC_NV_LOCKED 34707 34708the Index referenced by nvIndex is read locked 34709 34710TPM_RC_NV_RANGE 34711 34712read range defined by size and offset is outside the range of the 34713Index referenced by nvIndex 34714 34715TPM_RC_NV_UNINITIALIZED 347164 347175 347186 347197 347208 347219 3472210 3472311 3472412 3472513 3472614 3472715 3472816 3472917 3473018 3473119 3473220 3473321 3473422 3473523 3473624 3473725 3473826 3473927 3474028 3474129 3474230 3474331 3474432 3474533 3474634 3474735 3474836 3474937 34750 34751Meaning 34752 34753the Index referenced by nvIndex has not been initialized (written) 34754 34755TPM_RC 34756TPM2_NV_Read( 34757NV_Read_In 34758NV_Read_Out 34759 34760*in, 34761*out 34762 34763// IN: input parameter list 34764// OUT: output parameter list 34765 34766) 34767{ 34768NV_INDEX 34769TPM_RC 34770 34771nvIndex; 34772result; 34773 34774// Input Validation 34775// Get NV index info 34776NvGetIndexInfo(in->nvIndex, &nvIndex); 34777// Common read access checks. NvReadAccessChecks() returns 34778// TPM_RC_NV_AUTHORIZATION, TPM_RC_NV_LOCKED, or TPM_RC_NV_UNINITIALIZED 34779// error may be returned at this point 34780result = NvReadAccessChecks(in->authHandle, in->nvIndex); 34781if(result != TPM_RC_SUCCESS) 34782return result; 34783// Too much data 34784if((in->size + in->offset) > nvIndex.publicArea.dataSize) 34785return TPM_RC_NV_RANGE; 34786// Command Output 34787// Set the return size 34788out->data.t.size = in->size; 34789// Perform the read 34790NvGetIndexData(in->nvIndex, &nvIndex, in->offset, in->size, out->data.t.buffer); 34791return TPM_RC_SUCCESS; 34792} 34793 34794Page 434 34795October 31, 2013 34796 34797Published 34798Copyright © TCG 2006-2013 34799 34800Family “2.0” 34801Level 00 Revision 00.99 34802 34803 Trusted Platform Module Library 34804 34805Part 3: Commands 34806 3480733.14 TPM2_NV_ReadLock 3480833.14.1 34809 34810General Description 34811 34812If TPMA_NV_READ_STCLEAR is SET in an Index, then this command may be used to prevent further 34813reads of the NV Index until the next TPM2_Startup (TPM_SU_CLEAR). 34814Proper authorizations are required for this command as determined by TPMA_NV_PPREAD, 34815TPMA_NV_OWNERREAD, TPMA_NV_AUTHREAD, and the authPolicy of the NV Index. 34816NOTE 34817 34818Only an entity that may read an Index is allowed to lock the NV Index for read. 34819 34820If the command is properly authorized and TPMA_NV_READ_STCLEAR of the NV Index is SET, then the 34821TPM shall SET TPMA_NV_READLOCKED for the NV Index. If TPMA_NV_READ_STCLEAR of the NV 34822Index is CLEAR, then the TPM shall return TPM_RC_NV_ATTRIBUTE. TPMA_NV_READLOCKED will 34823be CLEAR by the next TPM2_Startup(TPM_SU_CLEAR). 34824It is not an error to use this command for an Index that is already locked for reading. 34825An Index that had not been written may be locked for reading. 34826 34827Family “2.0” 34828Level 00 Revision 00.99 34829 34830Published 34831Copyright © TCG 2006-2013 34832 34833Page 435 34834October 31, 2013 34835 34836 Part 3: Commands 34837 3483833.14.2 34839 34840Trusted Platform Module Library 34841 34842Command and Response 34843Table 219 — TPM2_NV_ReadLock Command 34844 34845Type 34846 34847Name 34848 34849Description 34850 34851TPMI_ST_COMMAND_TAG 34852 34853tag 34854 34855UINT32 34856 34857commandSize 34858 34859TPM_CC 34860 34861commandCode 34862 34863TPM_CC_NV_ReadLock 34864 34865TPMI_RH_NV_AUTH 34866 34867@authHandle 34868 34869the handle indicating the source of the authorization 34870value 34871Auth Index: 1 34872Auth Role: USER 34873 34874TPMI_RH_NV_INDEX 34875 34876nvIndex 34877 34878the NV Index to be locked 34879Auth Index: None 34880 34881Table 220 — TPM2_NV_ReadLock Response 34882Type 34883 34884Name 34885 34886Description 34887 34888TPM_ST 34889 34890tag 34891 34892see clause 8 34893 34894UINT32 34895 34896responseSize 34897 34898TPM_RC 34899 34900responseCode 34901 34902Page 436 34903October 31, 2013 34904 34905Published 34906Copyright © TCG 2006-2013 34907 34908Family “2.0” 34909Level 00 Revision 00.99 34910 34911 Trusted Platform Module Library 34912 3491333.14.3 349141 349152 349163 34917 34918Part 3: Commands 34919 34920Detailed Actions 34921 34922#include "InternalRoutines.h" 34923#include "NV_ReadLock_fp.h" 34924#include "NV_spt_fp.h" 34925Error Returns 34926TPM_RC_ATTRIBUTES 34927 34928TPMA_NV_READ_STCLEAR is not SET so Index referenced by 34929nvIndex may not be write locked 34930 34931TPM_RC_NV_AUTHORIZATION 34932 349334 349345 349356 349367 349378 349389 3493910 3494011 3494112 3494213 3494314 3494415 3494516 3494617 3494718 3494819 3494920 3495021 3495122 3495223 3495324 3495425 3495526 3495627 3495728 3495829 3495930 3496031 3496132 3496233 3496334 3496435 3496536 3496637 3496738 3496839 3496940 3497041 3497142 3497243 3497344 3497445 3497546 3497647 3497748 3497849 3497950 3498051 34981 34982Meaning 34983 34984the authorization was valid but the authorizing entity (authHandle) is 34985not allowed to read from the Index referenced by nvIndex 34986 34987TPM_RC 34988TPM2_NV_ReadLock( 34989NV_ReadLock_In *in 34990 34991// IN: input parameter list 34992 34993) 34994{ 34995TPM_RC 34996NV_INDEX 34997 34998result; 34999nvIndex; 35000 35001// The command needs NV update. Check if NV is available. 35002// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 35003// this point 35004result = NvIsAvailable(); 35005if(result != TPM_RC_SUCCESS) return result; 35006// Input Validation 35007// Common read access checks. NvReadAccessChecks() returns 35008// TPM_RC_NV_AUTHORIZATION, TPM_RC_NV_LOCKED, or TPM_RC_NV_UNINITIALIZED 35009// error may be returned at this point 35010result = NvReadAccessChecks(in->authHandle, in->nvIndex); 35011if(result != TPM_RC_SUCCESS) 35012{ 35013if(result == TPM_RC_NV_AUTHORIZATION) 35014return TPM_RC_NV_AUTHORIZATION; 35015// Index is already locked for write 35016else if(result == TPM_RC_NV_LOCKED) 35017return TPM_RC_SUCCESS; 35018// If NvReadAccessChecks return TPM_RC_NV_UNINITALIZED, then continue. 35019// It is not an error to read lock an uninitialized Index. 35020} 35021// Get NV index info 35022NvGetIndexInfo(in->nvIndex, &nvIndex); 35023// if TPMA_NV_READ_STCLEAR is not set, the index can not be read-locked 35024if(nvIndex.publicArea.attributes.TPMA_NV_READ_STCLEAR == CLEAR) 35025return TPM_RC_ATTRIBUTES + RC_NV_ReadLock_nvIndex; 35026// Internal Data Update 35027// Set the READLOCK attribute 35028nvIndex.publicArea.attributes.TPMA_NV_READLOCKED = SET; 35029// Write NV info back 35030NvWriteIndexInfo(in->nvIndex, &nvIndex); 35031return TPM_RC_SUCCESS; 35032} 35033 35034Family “2.0” 35035Level 00 Revision 00.99 35036 35037Published 35038Copyright © TCG 2006-2013 35039 35040Page 437 35041October 31, 2013 35042 35043 Part 3: Commands 35044 35045Trusted Platform Module Library 35046 3504733.15 TPM2_NV_ChangeAuth 3504833.15.1 35049 35050General Description 35051 35052This command allows the authorization secret for an NV Index to be changed. 35053If successful, the authorization secret (authValue) of the NV Index associated with nvIndex is changed. 35054This command requires that a policy session be used for authorization of nvIndex so that the ADMIN role 35055may be asserted and that commandCode in the policy session context shall be 35056TPM_CC_NV_ChangeAuth. That is, the policy must contain a specific authorization for changing the 35057authorization value of the referenced object. 35058NOTE 35059 35060The reason for this restriction is to ensure that the admin istrative actions on nvIndex require explicit 35061approval while other commands may use policy that is not command -dependent. 35062 35063The size of the newAuth value may be no larger than the size of authorization indicated when the NV 35064Index was defined. 35065Since the NV Index authorization is changed before the response HMAC is calculated, the newAuth value 35066is used when generating the response HMAC key if required. See Part 4 ComputeResponseHMAC(). 35067 35068Page 438 35069October 31, 2013 35070 35071Published 35072Copyright © TCG 2006-2013 35073 35074Family “2.0” 35075Level 00 Revision 00.99 35076 35077 Trusted Platform Module Library 35078 3507933.15.2 35080 35081Part 3: Commands 35082 35083Command and Response 35084Table 221 — TPM2_NV_ChangeAuth Command 35085 35086Type 35087 35088Name 35089 35090Description 35091 35092TPMI_ST_COMMAND_TAG 35093 35094tag 35095 35096UINT32 35097 35098commandSize 35099 35100TPM_CC 35101 35102commandCode 35103 35104TPM_CC_NV_ChangeAuth {NV} 35105 35106TPMI_RH_NV_INDEX 35107 35108@nvIndex 35109 35110handle of the object 35111Auth Index: 1 35112Auth Role: ADMIN 35113 35114TPM2B_AUTH 35115 35116newAuth 35117 35118new authorization value 35119 35120Table 222 — TPM2_NV_ChangeAuth Response 35121Type 35122 35123Name 35124 35125Description 35126 35127TPM_ST 35128 35129tag 35130 35131see clause 8 35132 35133UINT32 35134 35135responseSize 35136 35137TPM_RC 35138 35139responseCode 35140 35141Family “2.0” 35142Level 00 Revision 00.99 35143 35144Published 35145Copyright © TCG 2006-2013 35146 35147Page 439 35148October 31, 2013 35149 35150 Part 3: Commands 35151 3515233.15.3 351531 351542 35155 35156Trusted Platform Module Library 35157 35158Detailed Actions 35159 35160#include "InternalRoutines.h" 35161#include "NV_ChangeAuth_fp.h" 35162Error Returns 35163TPM_RC_SIZE 35164 351653 351664 351675 351686 351697 351708 351719 3517210 3517311 3517412 3517513 3517614 3517715 3517816 3517917 3518018 3518119 3518220 3518321 3518422 3518523 3518624 3518725 3518826 3518927 3519028 3519129 3519230 3519331 3519432 3519533 3519634 3519735 35198 35199Meaning 35200newAuth size is larger than the digest size of the Name algorithm for 35201the Index referenced by 'nvIndex 35202 35203TPM_RC 35204TPM2_NV_ChangeAuth( 35205NV_ChangeAuth_In 35206 35207*in 35208 35209// IN: input parameter list 35210 35211) 35212{ 35213TPM_RC 35214NV_INDEX 35215 35216result; 35217nvIndex; 35218 35219// Input Validation 35220// Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE 35221// TPM_RC_NV_RATE or TPM_RC_SUCCESS. 35222result = NvIsAvailable(); 35223if(result != TPM_RC_SUCCESS) return result; 35224// Read index info from NV 35225NvGetIndexInfo(in->nvIndex, &nvIndex); 35226// Remove any trailing zeros that might have been added by the caller 35227// to obfuscate the size. 35228MemoryRemoveTrailingZeros(&(in->newAuth)); 35229// Make sure that the authValue is no larger than the nameAlg of the Index 35230if(in->newAuth.t.size > CryptGetHashDigestSize(nvIndex.publicArea.nameAlg)) 35231return TPM_RC_SIZE + RC_NV_ChangeAuth_newAuth; 35232// Internal Data Update 35233// Change auth 35234nvIndex.authValue = in->newAuth; 35235// Write index info back to NV 35236NvWriteIndexInfo(in->nvIndex, &nvIndex); 35237return TPM_RC_SUCCESS; 35238} 35239 35240Page 440 35241October 31, 2013 35242 35243Published 35244Copyright © TCG 2006-2013 35245 35246Family “2.0” 35247Level 00 Revision 00.99 35248 35249 Trusted Platform Module Library 35250 35251Part 3: Commands 35252 3525333.16 TPM2_NV_Certify 3525433.16.1 35255 35256General Description 35257 35258The purpose of this command is to certify the contents of an NV Index or portion of an NV Index. 35259If proper authorization for reading the NV Index is provided, the portion of the NV Index selected by size 35260and offset are included in an attestation block and signed using the key indicated by signHandle. The 35261attestation also includes size and offset so that the range of the data can be determined. 35262NOTE 35263 35264See 20.1 for description of how the signing scheme is selected. 35265 35266Family “2.0” 35267Level 00 Revision 00.99 35268 35269Published 35270Copyright © TCG 2006-2013 35271 35272Page 441 35273October 31, 2013 35274 35275 Part 3: Commands 35276 3527733.16.2 35278 35279Trusted Platform Module Library 35280 35281Command and Response 35282Table 223 — TPM2_NV_Certify Command 35283 35284Type 35285 35286Name 35287 35288Description 35289 35290TPMI_ST_COMMAND_TAG 35291 35292tag 35293 35294UINT32 35295 35296commandSize 35297 35298TPM_CC 35299 35300commandCode 35301 35302TPM_CC_NV_Certify 35303 35304TPMI_DH_OBJECT+ 35305 35306@signHandle 35307 35308handle of the key used to sign the attestation structure 35309Auth Index: 1 35310Auth Role: USER 35311 35312TPMI_RH_NV_AUTH 35313 35314@authHandle 35315 35316handle indicating the source of the authorization value 35317for the NV Index 35318Auth Index: 2 35319Auth Role: USER 35320 35321TPMI_RH_NV_INDEX 35322 35323nvIndex 35324 35325Index for the area to be certified 35326Auth Index: None 35327 35328TPM2B_DATA 35329 35330qualifyingData 35331 35332user-provided qualifying data 35333 35334TPMT_SIG_SCHEME+ 35335 35336inScheme 35337 35338signing scheme to use if the scheme for signHandle is 35339TPM_ALG_NULL 35340 35341UINT16 35342 35343size 35344 35345number of octets to certify 35346 35347UINT16 35348 35349offset 35350 35351octet offset into the area 35352This value shall be less than or equal to the size of the 35353nvIndex data. 35354 35355Table 224 — TPM2_NV_Certify Response 35356Type 35357 35358Name 35359 35360Description 35361 35362TPM_ST 35363 35364tag 35365 35366see clause 8 35367 35368UINT32 35369 35370responseSize 35371 35372TPM_RC 35373 35374responseCode 35375 35376. 35377 35378TPM2B_ATTEST 35379 35380certifyInfo 35381 35382the structure that was signed 35383 35384TPMT_SIGNATURE 35385 35386signature 35387 35388the asymmetric signature over certifyInfo using the key 35389referenced by signHandle 35390 35391Page 442 35392October 31, 2013 35393 35394Published 35395Copyright © TCG 2006-2013 35396 35397Family “2.0” 35398Level 00 Revision 00.99 35399 35400 Trusted Platform Module Library 35401 3540233.16.3 354031 354042 354053 354064 35407 35408Detailed Actions 35409 35410#include 35411#include 35412#include 35413#include 35414 35415Part 3: Commands 35416 35417"InternalRoutines.h" 35418"Attest_spt_fp.h" 35419"NV_spt_fp.h" 35420"NV_Certify_fp.h" 35421 35422Error Returns 35423TPM_RC_NV_AUTHORIZATION 35424 35425the authorization was valid but the authorizing entity (authHandle) is 35426not allowed to read from the Index referenced by nvIndex 35427 35428TPM_RC_KEY 35429 35430signHandle does not reference a signing key 35431 35432TPM_RC_NV_LOCKED 35433 35434Index referenced by nvIndex is locked for reading 35435 35436TPM_RC_NV_RANGE 35437 35438offset plus size extends outside of the data range of the Index 35439referenced by nvIndex 35440 35441TPM_RC_NV_UNINITIALIZED 35442 35443Index referenced by nvIndex has not been written 35444 35445TPM_RC_SCHEME 354465 354476 354487 354498 354509 3545110 3545211 3545312 3545413 3545514 3545615 3545716 3545817 3545918 3546019 3546120 3546221 3546322 3546423 3546524 3546625 3546726 3546827 3546928 3547029 3547130 3547231 3547332 3547433 3547534 3547635 3547736 3547837 3547938 3548039 3548140 3548241 3548342 3548443 3548544 35486 35487Meaning 35488 35489inScheme is not an allowed value for the key definition 35490 35491TPM_RC 35492TPM2_NV_Certify( 35493NV_Certify_In 35494NV_Certify_Out 35495 35496*in, 35497*out 35498 35499// IN: input parameter list 35500// OUT: output parameter list 35501 35502) 35503{ 35504TPM_RC 35505NV_INDEX 35506TPMS_ATTEST 35507 35508result; 35509nvIndex; 35510certifyInfo; 35511 35512// Attestation command may cause the orderlyState to be cleared due to 35513// the reporting of clock info. If this is the case, check if NV is 35514// available first 35515if(gp.orderlyState != SHUTDOWN_NONE) 35516{ 35517// The command needs NV update. Check if NV is available. 35518// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 35519// this point 35520result = NvIsAvailable(); 35521if(result != TPM_RC_SUCCESS) 35522return result; 35523} 35524// Input Validation 35525// Get NV index info 35526NvGetIndexInfo(in->nvIndex, &nvIndex); 35527// Common access checks. A TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED 35528// error may be returned at this point 35529result = NvReadAccessChecks(in->authHandle, in->nvIndex); 35530if(result != TPM_RC_SUCCESS) 35531return result; 35532// See if the range to be certified is out of the bounds of the defined 35533// Index 35534if((in->size + in->offset) > nvIndex.publicArea.dataSize) 35535return TPM_RC_NV_RANGE; 35536// Command Output 35537 35538Family “2.0” 35539Level 00 Revision 00.99 35540 35541Published 35542Copyright © TCG 2006-2013 35543 35544Page 443 35545October 31, 2013 35546 35547 Part 3: Commands 3554845 3554946 3555047 3555148 3555249 3555350 3555451 3555552 3555653 3555754 3555855 3555956 3556057 3556158 3556259 3556360 3556461 3556562 3556663 3556764 3556865 3556966 3557067 3557168 3557269 3557370 3557471 3557572 3557673 3557774 3557875 3557976 3558077 3558178 3558279 3558380 3558481 3558582 3558683 3558784 3558885 3558986 3559087 3559188 3559289 3559390 3559491 3559592 3559693 3559794 3559895 3559996 3560097 3560198 3560299 35603100 35604 35605Trusted Platform Module Library 35606 35607// Filling in attest information 35608// Common fields 35609// FillInAttestInfo can return TPM_RC_SCHEME or TPM_RC_KEY 35610result = FillInAttestInfo(in->signHandle, 35611&in->inScheme, 35612&in->qualifyingData, 35613&certifyInfo); 35614if(result != TPM_RC_SUCCESS) 35615{ 35616if(result == TPM_RC_KEY) 35617return TPM_RC_KEY + RC_NV_Certify_signHandle; 35618else 35619return RcSafeAddToResult(result, RC_NV_Certify_inScheme); 35620} 35621// NV certify specific fields 35622// Attestation type 35623certifyInfo.type = TPM_ST_ATTEST_NV; 35624// Get the name of the index 35625certifyInfo.attested.nv.indexName.t.size = 35626NvGetName(in->nvIndex, &certifyInfo.attested.nv.indexName.t.name); 35627// Set the return size 35628certifyInfo.attested.nv.nvContents.t.size = in->size; 35629// Set the offset 35630certifyInfo.attested.nv.offset = in->offset; 35631// Perform the read 35632NvGetIndexData(in->nvIndex, &nvIndex, 35633in->offset, in->size, 35634certifyInfo.attested.nv.nvContents.t.buffer); 35635// Sign attestation structure. A NULL signature will be returned if 35636// signHandle is TPM_RH_NULL. SignAttestInfo() may return TPM_RC_VALUE, 35637// TPM_RC_SCHEME or TPM_RC_ATTRUBUTES. 35638// Note: SignAttestInfo may return TPM_RC_ATTRIBUTES if the key is not a 35639// signing key but that was checked above. TPM_RC_VALUE would mean that the 35640// data to sign is too large but the data to sign is a digest 35641result = SignAttestInfo(in->signHandle, 35642&in->inScheme, 35643&certifyInfo, 35644&in->qualifyingData, 35645&out->certifyInfo, 35646&out->signature); 35647if(result != TPM_RC_SUCCESS) 35648return result; 35649// orderly state should be cleared because of the reporting of clock info 35650// if signing happens 35651if(in->signHandle != TPM_RH_NULL) 35652g_clearOrderly = TRUE; 35653return TPM_RC_SUCCESS; 35654} 35655 35656Page 444 35657October 31, 2013 35658 35659Published 35660Copyright © TCG 2006-2013 35661 35662Family “2.0” 35663Level 00 Revision 00.99 35664 35665 35666