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 3668tpmKey 3669 3670handle of a loaded decrypt key used to encrypt salt 3671may be TPM_RH_NULL 3672Auth Index: None 3673 3674TPMI_DH_ENTITY+ 3675 3676bind 3677 3678entity providing the authValue 3679may be TPM_RH_NULL 3680Auth Index: None 3681 3682TPM2B_NONCE 3683 3684nonceCaller 3685 3686TPMI_DH_OBJECT+ 3687 3688Description 3689 3690initial nonceCaller, sets nonce size for the session 3691shall be at least 16 octets 3692 3693TPM2B_ENCRYPTED_SECRET encryptedSalt 3694 3695value encrypted according to the type of tpmKey 3696If tpmKey is TPM_RH_NULL, this shall be the Empty 3697Buffer. 3698 3699TPM_SE 3700 3701sessionType 3702 3703indicates the type of the session; simple HMAC or policy 3704(including a trial policy) 3705 3706TPMT_SYM_DEF+ 3707 3708symmetric 3709 3710the algorithm and key size for parameter encryption 3711may select TPM_ALG_NULL 3712 3713TPMI_ALG_HASH 3714 3715authHash 3716 3717hash algorithm to use for the session 3718Shall be a hash algorithm supported by the TPM and 3719not TPM_ALG_NULL 3720 3721Table 16 — TPM2_StartAuthSession Response 3722Type 3723 3724Name 3725 3726Description 3727 3728TPM_ST 3729 3730tag 3731 3732see clause 8 3733 3734UINT32 3735 3736responseSize 3737 3738TPM_RC 3739 3740responseCode 3741 3742TPMI_SH_AUTH_SESSION 3743 3744sessionHandle 3745 3746handle for the newly created session 3747 3748TPM2B_NONCE 3749 3750nonceTPM 3751 3752the initial nonce from the TPM, used in the computation 3753of the sessionKey 3754 3755Page 40 3756October 31, 2013 3757 3758Published 3759Copyright © TCG 2006-2013 3760 3761Family “2.0” 3762Level 00 Revision 00.99 3763 3764 Trusted Platform Module Library 3765 3766Part 3: Commands 3767 376813.1.3 Detailed Actions 37691 37702 3771 3772#include "InternalRoutines.h" 3773#include "StartAuthSession_fp.h" 3774Error Returns 3775TPM_RC_ATTRIBUTES 3776 3777tpmKey does not reference a decrypt key 3778 3779TPM_RC_CONTEXT_GAP 3780 3781the difference between the most recently created active context and 3782the oldest active context is at the limits of the TPM 3783 3784TPM_RC_HANDLE 3785 3786input decrypt key handle only has public portion loaded 3787 3788TPM_RC_MODE 3789 3790symmetric specifies a block cipher but the mode is not 3791TPM_ALG_CFB. 3792 3793TPM_RC_SESSION_HANDLES 3794 3795no session handle is available 3796 3797TPM_RC_SESSION_MEMORY 3798 3799no more slots for loading a session 3800 3801TPM_RC_SIZE 3802 3803nonce less than 16 octets or greater than the size of the digest 3804produced by authHash 3805 3806TPM_RC_VALUE 3807 38083 38094 38105 38116 38127 38138 38149 381510 381611 381712 381813 381914 382015 382116 382217 382318 382419 382520 382621 382722 382823 382924 383025 383126 383227 383328 383429 383530 383631 383732 383833 383934 384035 384136 3842 3843Meaning 3844 3845secret size does not match decrypt key type; or the recovered secret 3846is larget than the digest size of the nameAlg of tpmKey; or, for an 3847RSA decrypt key, if encryptedSecret is greater than the public 3848exponent of tpmKey. 3849 3850TPM_RC 3851TPM2_StartAuthSession( 3852StartAuthSession_In 3853StartAuthSession_Out 3854 3855*in, 3856*out 3857 3858// IN: input parameter buffer 3859// OUT: output parameter buffer 3860 3861TPM_RC 3862OBJECT 3863SESSION 3864TPM2B_DATA 3865 3866result = TPM_RC_SUCCESS; 3867*tpmKey; 3868// TPM key for decrypt salt 3869*session; 3870// session internal data 3871salt; 3872 3873) 3874{ 3875 3876// Input Validation 3877// Check input nonce size. IT should be at least 16 bytes but not larger 3878// than the digest size of session hash. 3879if( 3880in->nonceCaller.t.size < 16 3881|| in->nonceCaller.t.size > CryptGetHashDigestSize(in->authHash)) 3882return TPM_RC_SIZE + RC_StartAuthSession_nonceCaller; 3883// If an decrypt key is passed in, check its validation 3884if(in->tpmKey != TPM_RH_NULL) 3885{ 3886// secret size cannot be 0 3887if(in->encryptedSalt.t.size == 0) 3888return TPM_RC_VALUE + RC_StartAuthSession_encryptedSalt; 3889// Get pointer to loaded decrypt key 3890tpmKey = ObjectGet(in->tpmKey); 3891// Decrypting salt requires accessing the private portion of a key. 3892// Therefore, tmpKey can not be a key with only public portion loaded 3893if(tpmKey->attributes.publicOnly) 3894return TPM_RC_HANDLE + RC_StartAuthSession_tpmKey; 3895 3896Family “2.0” 3897Level 00 Revision 00.99 3898 3899Published 3900Copyright © TCG 2006-2013 3901 3902Page 41 3903October 31, 2013 3904 3905 Part 3: Commands 390637 390738 390839 390940 391041 391142 391243 391344 391445 391546 391647 391748 391849 391950 392051 392152 392253 392354 392455 392556 392657 392758 392859 392960 393061 393162 393263 393364 393465 393566 393667 393768 393869 393970 394071 394172 394273 394374 394475 394576 394677 394778 394879 394980 395081 395182 395283 395384 395485 395586 395687 395788 395889 395990 3960 3961Trusted Platform Module Library 3962 3963// HMAC session input handle check. 3964// tpmKey should be a decryption key 3965if(tpmKey->publicArea.objectAttributes.decrypt != SET) 3966return TPM_RC_ATTRIBUTES + RC_StartAuthSession_tpmKey; 3967// Secret Decryption. A TPM_RC_VALUE, TPM_RC_KEY or Unmarshal errors 3968// may be returned at this point 3969result = CryptSecretDecrypt(in->tpmKey, &in->nonceCaller, "SECRET", 3970&in->encryptedSalt, &salt); 3971if(result != TPM_RC_SUCCESS) 3972return TPM_RC_VALUE + RC_StartAuthSession_encryptedSalt; 3973} 3974else 3975{ 3976// secret size must be 0 3977if(in->encryptedSalt.t.size != 0) 3978return TPM_RC_VALUE + RC_StartAuthSession_encryptedSalt; 3979salt.t.size = 0; 3980} 3981// If 'symmetric' is a symmetric block cipher (not TPM_ALG_NULL or TPM_ALG_XOR) 3982// then the mode must be CFB. 3983if( 3984in->symmetric.algorithm != TPM_ALG_NULL 3985&& in->symmetric.algorithm != TPM_ALG_XOR 3986&& in->symmetric.mode.sym != TPM_ALG_CFB) 3987return TPM_RC_MODE + RC_StartAuthSession_symmetric; 3988// Internal Data Update 3989// Create internal session structure. TPM_RC_CONTEXT_GAP, TPM_RC_NO_HANDLES 3990// or TPM_RC_SESSION_MEMORY errors may be returned returned at this point. 3991// 3992// The detailed actions for creating the session context are not shown here 3993// as the details are implementation dependent 3994// SessionCreate sets the output handle 3995result = SessionCreate(in->sessionType, in->authHash, 3996&in->nonceCaller, &in->symmetric, 3997in->bind, &salt, &out->sessionHandle); 3998if(result != TPM_RC_SUCCESS) 3999return result; 4000// Command Output 4001// Get session pointer 4002session = SessionGet(out->sessionHandle); 4003// Copy nonceTPM 4004out->nonceTPM = session->nonceTPM; 4005return TPM_RC_SUCCESS; 4006} 4007 4008Page 42 4009October 31, 2013 4010 4011Published 4012Copyright © TCG 2006-2013 4013 4014Family “2.0” 4015Level 00 Revision 00.99 4016 4017 Trusted Platform Module Library 4018 401913.2 4020 4021Part 3: Commands 4022 4023TPM2_PolicyRestart 4024 402513.2.1 General Description 4026This command allows a policy authorization session to be returned to its initial state. This command is 4027used after the TPM returns TPM_RC_PCR_CHANGED. That response code indicates that a policy will 4028fail because the PCR have changed after TPM2_PolicyPCR() was executed. Restarting the session 4029allows the authorizations to be replayed because the session restarts with the same nonceTPM. If the 4030PCR are valid for the policy, the policy may then succeed. 4031This command does not reset the policy ID or the policy start time. 4032 4033Family “2.0” 4034Level 00 Revision 00.99 4035 4036Published 4037Copyright © TCG 2006-2013 4038 4039Page 43 4040October 31, 2013 4041 4042 Part 3: Commands 4043 4044Trusted Platform Module Library 4045 404613.2.2 Command and Response 4047Table 17 — TPM2_PolicyRestart Command 4048Type 4049 4050Name 4051 4052Description 4053 4054TPMI_ST_COMMAND_TAG 4055 4056tag 4057 4058UINT32 4059 4060commandSize 4061 4062TPM_CC 4063 4064commandCode 4065 4066TPM_CC_PolicyRestart 4067 4068TPMI_SH_POLICY 4069 4070sessionHandle 4071 4072the handle for the policy session 4073 4074Table 18 — TPM2_PolicyRestart Response 4075Type 4076 4077Name 4078 4079Description 4080 4081TPM_ST 4082 4083tag 4084 4085see clause 8 4086 4087UINT32 4088 4089responseSize 4090 4091TPM_RC 4092 4093responseCode 4094 4095Page 44 4096October 31, 2013 4097 4098Published 4099Copyright © TCG 2006-2013 4100 4101Family “2.0” 4102Level 00 Revision 00.99 4103 4104 Trusted Platform Module Library 4105 4106Part 3: Commands 4107 410813.2.3 Detailed Actions 41091 41102 41113 41124 41135 41146 41157 41168 41179 411810 411911 412012 412113 412214 412315 412416 412517 412618 412719 412820 412921 413022 4131 4132#include "InternalRoutines.h" 4133#include "PolicyRestart_fp.h" 4134 4135TPM_RC 4136TPM2_PolicyRestart( 4137PolicyRestart_In 4138 4139*in 4140 4141// IN: input parameter list 4142 4143SESSION 4144BOOL 4145 4146*session; 4147wasTrialSession; 4148 4149) 4150{ 4151 4152// Internal Data Update 4153session = SessionGet(in->sessionHandle); 4154wasTrialSession = session->attributes.isTrialPolicy == SET; 4155// Initialize policy session 4156SessionResetPolicyData(session); 4157session->attributes.isTrialPolicy = wasTrialSession; 4158return TPM_RC_SUCCESS; 4159} 4160 4161Family “2.0” 4162Level 00 Revision 00.99 4163 4164Published 4165Copyright © TCG 2006-2013 4166 4167Page 45 4168October 31, 2013 4169 4170 Part 3: Commands 4171 4172Trusted Platform Module Library 4173 4174Object Commands 4175 417614 417714.1 4178 4179TPM2_Create 4180 418114.1.1 General Description 4182This command is used to create an object that can be loaded into a TPM using TPM2_Load(). If the 4183command completes successfully, the TPM will create the new object and return the object’s creation 4184data (creationData), its public area (outPublic), and its encrypted sensitive area (outPrivate). Preservation 4185of the returned data is the responsibility of the caller. The object will need to be loaded (TPM2_Load()) 4186before it may be used. 4187TPM2B_PUBLIC template (inPublic) contains all of the fields necessary to define the properties of the 4188new object. The setting for these fields is defined in “Public Area Template” in Part 1 and 4189“TPMA_OBJECT” in Part 2. 4190The parentHandle parameter shall reference a loaded decryption key that has both the public and 4191sensitive area loaded. 4192When defining the object, the caller provides a template structure for the object in a TPM2B_PUBLIC 4193structure (inPublic), an initial value for the object’s authValue (inSensitive.authValue), and, if the object is 4194a symmetric object, an optional initial data value (inSensitive.data). The TPM shall validate the 4195consistency of inPublic.attributes according to the Creation rules in “TPMA_OBJECT” in Part 2. 4196The sensitive parameter may be encrypted using parameter encryption. 4197The methods in this clause are used by both TPM2_Create() and TPM2_CreatePrimary(). When a value 4198is indicated as being TPM-generated, the value is filled in by bits from the RNG if the command is 4199TPM2_Create() and with values from KDFa() if the command is TPM2_CreatePrimary(). The parameters 4200of each creation value are specified in Part 1. 4201The sensitiveDataOrigin attribute of inPublic shall be SET if inSensitive.data is an Empty Buffer and 4202CLEAR if inSensitive.data is not an Empty Buffer or the TPM shall return TPM_RC_ATTRIBUTES. 4203The TPM will create new data for the sensitive area and compute a TPMT_PUBLIC.unique from the 4204sensitive area based on the object type: 4205a) For a symmetric key: 42061) If inSensitive.data is the Empty Buffer, a TPM-generated key value is placed in the new object’s 4207TPMT_SENSITIVE.sensitive.sym. The size of the key will be determined by 4208inPublic.publicArea.parameters. 42092) If inSensitive.data is not the Empty Buffer, the TPM will validate that the size of inSensitive.data is 4210no larger than the key size indicated in the inPublic template (TPM_RC_SIZE) and copy the 4211inSensitive.data to TPMT_SENSITIVE.sensitive.sym of the new object. 42123) A TPM-generated obfuscation value is placed in TPMT_SENSITIVE.sensitive.seedValue. The 4213size of the obfuscation value is the size of the digest produced by the nameAlg in inPublic. This 4214value prevents the public unique value from leaking information about the sensitive area. 42154) The TPMT_PUBLIC.unique.sym.buffer value for the new object is then generated, as shown in 4216equation (1) below, by hashing the key and obfuscation values in the TPMT_SENSITIVE with the 4217nameAlg of the object. 4218 4219unique ≔ HnameAlg(sensitive.seedValue.buffer || sensitive.any.buffer) 4220 4221(1) 4222 4223b) If the Object is an asymmetric key: 42241) If sensitive.data is not the Empty Buffer, then the TPM shall return TPM_RC_VALUE. 4225 4226Page 46 4227October 31, 2013 4228 4229Published 4230Copyright © TCG 2006-2013 4231 4232Family “2.0” 4233Level 00 Revision 00.99 4234 4235 Trusted Platform Module Library 4236 4237Part 3: Commands 4238 42392) A TPM-generated private key value is created with the size determined by the parameters of 4240inPublic.publicArea.parameters. 42413) If the key is a Storage Key, a TPM-generated TPMT_SENSITIVE.symKey value is created; 4242otherwise, TPMT_SENSITIVE.symKey.size is set to zero. 42434) The public unique value is computed from the private key according to the methods of the key 4244type. 42455) If the key is an ECC key and the scheme required by the curveID is not the same as scheme in 4246the public area of the template, then the TPM shall return TPM_RC_SCHEME. 42476) If the key is an ECC key and the KDF required by the curveID is not the same as kdf in the pubic 4248area of the template, then the TPM shall return TPM_RC_KDF. 4249NOTE 1 4250 4251There is currently no command in which the caller may specify the KDF to be used with an 4252ECC decryption key. Since there is no use for this capability, the reference implementation 4253requires that the kdf in the template be set to TPM_ALG_NULL or TPM_RC_KDF is 4254returned. 4255 4256c) If the Object is a keyedHash object: 42571) If inSensitive.data is an Empty Buffer, and neither sign nor decrypt is SET in inPublic.attributes, 4258the TPM shall return TPM_RC_ATTRIBUTES. This would be a data object with no data. 42592) If inSensitive.data is not an Empty Buffer, the TPM will copy the inSensitive.data to 4260TPMT_SENSITIVE.sensitive of the new object. 4261NOTE 2 4262 4263The size of inSensitive.data is limited to be no larger 4264TPMT_SENSITIVE.sensitive.bits.data by MAX_SYM_DATA. 4265 4266than 4267 4268the 4269 4270largest 4271 4272value 4273 4274of 4275 42763) If inSensitive.data is an Empty Buffer, a TPM-generated key value that is the size of the digest 4277produced by the nameAlg in inPublic is placed in TPMT_SENSITIVE.sensitive.any.buffer. 42784) A TPM-generated obfuscation value that is the size of the digest produced by the nameAlg of 4279inPublic is placed in TPMT_SENSITIVE.symKey.buffer. 42805) The TPMT_PUBLIC.unique.sym.buffer value for the new object is then generated, as shown in 4281equation (1) above, by hashing the key and obfuscation values in the TPMT_SENSITIVE with the 4282nameAlg of the object. 4283For TPM2_Load(), the TPM will apply normal symmetric protections to the created TPMT_SENSITIVE to 4284create outPublic. 4285NOTE 3 4286 4287The encryption key is derived from the symmetric seed in the sensitive area of the parent. 4288 4289In addition to outPublic and outPrivate, the TPM will build a TPMS_CREATION_DATA structure for the 4290object. TPMS_CREATION_DATA.outsideInfo is set to outsideInfo. This structure is returned in 4291creationData. Additionally, the digest of this structure is returned in creationHash, and, finally, a 4292TPMT_TK_CREATION is created so that the association between the creation data and the object may 4293be validated by TPM2_CertifyCreation(). 4294If the object being created is a Storage Key and inPublic.objectAttributes.fixedParent is SET, then the 4295algorithms of inPublic are required to match those of the parent. The algorithms that must match are 4296inPublic.type, inPublic.nameAlg, and inPublic.parameters. If inPublic.type does not match, the TPM shall 4297return TPM_RC_TYPE. If inPublic.nameAlg does not match, the TPM shall return TPM_RC_HASH. If 4298inPublic.parameters does not match, the TPM shall return TPM_RC_ASSYMETRIC. The TPM shall not 4299differentiate between mismatches of the components of inPublic.parameters. 4300EXAMPLE 4301 4302If the inPublic.parameters.ecc.symmetric.algorithm does not match the parent, the TPM shall return 4303TPM_RC_ ASYMMETRIC rather than TPM_RC_SYMMETRIC. 4304 4305Family “2.0” 4306Level 00 Revision 00.99 4307 4308Published 4309Copyright © TCG 2006-2013 4310 4311Page 47 4312October 31, 2013 4313 4314 Part 3: Commands 4315 4316Trusted Platform Module Library 4317 431814.1.2 Command and Response 4319Table 19 — TPM2_Create Command 4320Type 4321 4322Name 4323 4324Description 4325 4326TPMI_ST_COMMAND_TAG 4327 4328tag 4329 4330UINT32 4331 4332commandSize 4333 4334TPM_CC 4335 4336commandCode 4337 4338TPM_CC_Create 4339 4340TPMI_DH_OBJECT 4341 4342@parentHandle 4343 4344handle of parent for new object 4345Auth Index: 1 4346Auth Role: USER 4347 4348TPM2B_SENSITIVE_CREATE 4349 4350inSensitive 4351 4352the sensitive data 4353 4354TPM2B_PUBLIC 4355 4356inPublic 4357 4358the public template 4359 4360TPM2B_DATA 4361 4362outsideInfo 4363 4364data that will be included in the creation data for this 4365object to provide permanent, verifiable linkage between 4366this object and some object owner data 4367 4368TPML_PCR_SELECTION 4369 4370creationPCR 4371 4372PCR that will be used in creation data 4373 4374Table 20 — TPM2_Create Response 4375Type 4376 4377Name 4378 4379Description 4380 4381TPM_ST 4382 4383tag 4384 4385see clause 8 4386 4387UINT32 4388 4389responseSize 4390 4391TPM_RC 4392 4393responseCode 4394 4395TPM2B_PRIVATE 4396 4397outPrivate 4398 4399the private portion of the object 4400 4401TPM2B_PUBLIC 4402 4403outPublic 4404 4405the public portion of the created object 4406 4407TPM2B_CREATION_DATA 4408 4409creationData 4410 4411contains a TPMS_CREATION_DATA 4412 4413TPM2B_DIGEST 4414 4415creationHash 4416 4417digest of creationData using nameAlg of outPublic 4418 4419TPMT_TK_CREATION 4420 4421creationTicket 4422 4423ticket used by TPM2_CertifyCreation() to validate that 4424the creation data was produced by the TPM 4425 4426Page 48 4427October 31, 2013 4428 4429Published 4430Copyright © TCG 2006-2013 4431 4432Family “2.0” 4433Level 00 Revision 00.99 4434 4435 Trusted Platform Module Library 4436 4437Part 3: Commands 4438 443914.1.3 Detailed Actions 44401 44412 44423 4443 4444#include "InternalRoutines.h" 4445#include "Object_spt_fp.h" 4446#include "Create_fp.h" 4447Error Returns 4448TPM_RC_ASYMMETRIC 4449 4450non-duplicable storage key and its parent have different public 4451params 4452 4453TPM_RC_ATTRIBUTES 4454 4455sensitiveDataOrigin is CLEAR when 'sensitive. data' is an Empty 4456Buffer, or is SET when 'sensitive. data' is not empty; fixedTPM, 4457fixedParent, or encryptedDuplication attributes are inconsistent 4458between themselves or with those of the parent object; inconsistent 4459restricted, decrypt and sign attributes; attempt to inject sensitive data 4460for an asymmetric key; attempt to create a symmetric cipher key that 4461is not a decryption key 4462 4463TPM_RC_HASH 4464 4465non-duplicable storage key and its parent have different name 4466algorithm 4467 4468TPM_RC_KDF 4469 4470incorrect KDF specified for decrypting keyed hash object 4471 4472TPM_RC_KEY 4473 4474invalid key size values in an asymmetric key public area 4475 4476TPM_RC_KEY_SIZE 4477 4478key size in public area for symmetric key differs from the size in the 4479sensitive creation area; may also be returned if the TPM does not 4480allow the key size to be used for a Storage Key 4481 4482TPM_RC_RANGE 4483 4484FOr() an RSA key, the exponent value is not supported. 4485 4486TPM_RC_SCHEME 4487 4488inconsistent attributes decrypt, sign, restricted and key's scheme ID; 4489or hash algorithm is inconsistent with the scheme ID for keyed hash 4490object 4491 4492TPM_RC_SIZE 4493 4494size of public auth policy or sensitive auth value does not match 4495digest size of the name algorithm sensitive data size for the keyed 4496hash object is larger than is allowed for the scheme 4497 4498TPM_RC_SYMMETRIC 4499 4500a storage key with no symmetric algorithm specified; or non-storage 4501key with symmetric algorithm different from TPM_ALG_NULL 4502 4503TPM_RC_TYPE 4504 4505unknown object type; non-duplicable storage key and its parent have 4506different types; parentHandle does not reference a restricted 4507decryption key in the storage hierarchy with both public and sensitive 4508portion loaded 4509 4510TPM_RC_VALUE 4511 4512exponent is not prime or could not find a prime using the provided 4513parameters for an RSA key; unsupported name algorithm for an ECC 4514key 4515 4516TPM_RC_OBJECT_MEMORY 4517 45184 45195 45206 45217 45228 45239 452410 452511 452612 452713 4528 4529Meaning 4530 4531there is no free slot for the object. This implementation does not 4532return this error. 4533 4534TPM_RC 4535TPM2_Create( 4536Create_In 4537Create_Out 4538 4539*in, 4540*out 4541 4542// IN: input parameter list 4543// OUT: output parameter list 4544 4545) 4546{ 4547TPM_RC 4548TPMT_SENSITIVE 4549TPM2B_NAME 4550 4551Family “2.0” 4552Level 00 Revision 00.99 4553 4554result = TPM_RC_SUCCESS; 4555sensitive; 4556name; 4557 4558Published 4559Copyright © TCG 2006-2013 4560 4561Page 49 4562October 31, 2013 4563 4564 Part 3: Commands 456514 456615 456716 456817 456918 457019 457120 457221 457322 457423 457524 457625 457726 457827 457928 458029 458130 458231 458332 458433 458534 458635 458736 458837 458938 459039 459140 459241 459342 459443 459544 459645 459746 459847 459948 460049 460150 460251 460352 460453 460554 460655 460756 460857 460958 461059 461160 461261 461362 461463 461564 461665 461766 461867 461968 462069 462170 462271 462372 462473 4625 4626Trusted Platform Module Library 4627 4628// Input Validation 4629OBJECT 4630 4631*parentObject; 4632 4633parentObject = ObjectGet(in->parentHandle); 4634// Does parent have the proper attributes? 4635if(!AreAttributesForParent(parentObject)) 4636return TPM_RC_TYPE + RC_Create_parentHandle; 4637// The sensitiveDataOrigin attribute must be consistent with the setting of 4638// the size of the data object in inSensitive. 4639if( 4640(in->inPublic.t.publicArea.objectAttributes.sensitiveDataOrigin == SET) 4641!= (in->inSensitive.t.sensitive.data.t.size == 0)) 4642// Mismatch between the object attributes and the parameter. 4643return TPM_RC_ATTRIBUTES + RC_Create_inSensitive; 4644// Check attributes in input public area. TPM_RC_ASYMMETRIC, TPM_RC_ATTRIBUTES, 4645// TPM_RC_HASH, TPM_RC_KDF, TPM_RC_SCHEME, TPM_RC_SIZE, TPM_RC_SYMMETRIC, 4646// or TPM_RC_TYPE error may be returned at this point. 4647result = PublicAttributesValidation(FALSE, in->parentHandle, 4648&in->inPublic.t.publicArea); 4649if(result != TPM_RC_SUCCESS) 4650return RcSafeAddToResult(result, RC_Create_inPublic); 4651// Validate the sensitive area values 4652if( MemoryRemoveTrailingZeros(&in->inSensitive.t.sensitive.userAuth) 4653> CryptGetHashDigestSize(in->inPublic.t.publicArea.nameAlg)) 4654return TPM_RC_SIZE + RC_Create_inSensitive; 4655// Command Output 4656// Create object crypto data 4657result = CryptCreateObject(in->parentHandle, &in->inPublic.t.publicArea, 4658&in->inSensitive.t.sensitive, &sensitive); 4659if(result != TPM_RC_SUCCESS) 4660return result; 4661// Fill in creation data 4662FillInCreationData(in->parentHandle, in->inPublic.t.publicArea.nameAlg, 4663&in->creationPCR, &in->outsideInfo, 4664&out->creationData, &out->creationHash); 4665// Copy public area from input to output 4666out->outPublic.t.publicArea = in->inPublic.t.publicArea; 4667// Compute name from public area 4668ObjectComputeName(&(out->outPublic.t.publicArea), &name); 4669// Compute creation ticket 4670TicketComputeCreation(EntityGetHierarchy(in->parentHandle), &name, 4671&out->creationHash, &out->creationTicket); 4672// Prepare output private data from sensitive 4673SensitiveToPrivate(&sensitive, &name, in->parentHandle, 4674out->outPublic.t.publicArea.nameAlg, 4675&out->outPrivate); 4676return TPM_RC_SUCCESS; 4677} 4678 4679Page 50 4680October 31, 2013 4681 4682Published 4683Copyright © TCG 2006-2013 4684 4685Family “2.0” 4686Level 00 Revision 00.99 4687 4688 Trusted Platform Module Library 4689 469014.2 4691 4692Part 3: Commands 4693 4694TPM2_Load 4695 469614.2.1 General Description 4697This command is used to load objects into the TPM. This command is used when both a TPM2B_PUBLIC 4698and TPM2B_PRIVATE are to be loaded. If only a TPM2B_PUBLIC is to be loaded, the 4699TPM2_LoadExternal command is used. 4700NOTE 1 4701 4702Loading an object is not the same as restoring a saved object context. 4703 4704The object’s TPMA_OBJECT attributes will be checked according to the rules defined in 4705“TPMA_OBJECT” in Part 2 of this specification. 4706Objects loaded using this command will have a Name. The Name is the concatenation of nameAlg and 4707the digest of the public area using the nameAlg. 4708NOTE 2 4709 4710nameAlg is a parameter in the public area of the inPublic structure. 4711 4712If inPrivate.size is zero, the load will fail. 4713After inPrivate.buffer is decrypted using the symmetric key of the parent, the integrity value shall be 4714checked before the sensitive area is used, or unmarshaled. 4715NOTE 3 4716 4717Checking the integrity before the data is used prevents attacks o n the sensitive area by fuzzing the 4718data and looking at the differences in the response codes. 4719 4720The command returns a handle for the loaded object and the Name that the TPM computed for 4721inPublic.public (that is, the digest of the TPMT_PUBLIC structure in inPublic). 4722NOTE 4 4723 4724The TPM-computed Name is provided as a convenience to the caller for those cases where the 4725caller does not implement the hash algorithms specified in the nameAlg of the object. 4726 4727NOTE 5 4728 4729The returned handle is associated with the object until the object is flushed (TPM2_FlushContext) or 4730until the next TPM2_Startup. 4731 4732For all objects, the size of the key in the sensitive area shall be consistent with the key size indicated in 4733the public area or the TPM shall return TPM_RC_KEY_SIZE. 4734Before use, a loaded object shall be checked to validate that the public and sensitive portions are 4735properly linked, cryptographically. Use of an object includes use in any policy command. If the parts of the 4736object are not properly linked, the TPM shall return TPM_RC_BINDING. 4737EXAMPLE 1 4738 4739For a symmetric object, the unique value in the public area shall be the digest of the sensitive key 4740and the obfuscation value. 4741 4742EXAMPLE 2 4743 4744For a two-prime RSA key, the remainder when dividing the public modulus by the private key shall 4745be zero and it shall be possible to form a private exponent from the two prime factors of the public 4746modulus. 4747 4748EXAMPLE 3 4749 4750For an ECC key, the public point shall be f(x) where x is the private key. 4751 4752Family “2.0” 4753Level 00 Revision 00.99 4754 4755Published 4756Copyright © TCG 2006-2013 4757 4758Page 51 4759October 31, 2013 4760 4761 Part 3: Commands 4762 4763Trusted Platform Module Library 4764 476514.2.2 Command and Response 4766Table 21 — TPM2_Load Command 4767Type 4768 4769Name 4770 4771Description 4772 4773TPMI_ST_COMMAND_TAG 4774 4775tag 4776 4777UINT32 4778 4779commandSize 4780 4781TPM_CC 4782 4783commandCode 4784 4785TPM_CC_Load 4786 4787TPMI_DH_OBJECT 4788 4789@parentHandle 4790 4791TPM handle of parent key; shall not be a reserved 4792handle 4793Auth Index: 1 4794Auth Role: USER 4795 4796TPM2B_PRIVATE 4797 4798inPrivate 4799 4800the private portion of the object 4801 4802TPM2B_PUBLIC 4803 4804inPublic 4805 4806the public portion of the object 4807 4808Table 22 — TPM2_Load Response 4809Type 4810 4811Name 4812 4813Description 4814 4815TPM_ST 4816 4817tag 4818 4819see clause 8 4820 4821UINT32 4822 4823responseSize 4824 4825TPM_RC 4826 4827responseCode 4828 4829TPM_HANDLE 4830 4831objectHandle 4832 4833handle for the loaded object 4834 4835TPM2B_NAME 4836 4837name 4838 4839Name of the loaded object 4840 4841Page 52 4842October 31, 2013 4843 4844Published 4845Copyright © TCG 2006-2013 4846 4847Family “2.0” 4848Level 00 Revision 00.99 4849 4850 Trusted Platform Module Library 4851 4852Part 3: Commands 4853 485414.2.3 Detailed Actions 48551 48562 48573 4858 4859#include "InternalRoutines.h" 4860#include "Load_fp.h" 4861#include "Object_spt_fp.h" 4862Error Returns 4863TPM_RC_ASYMMETRIC 4864 4865storage key with different asymmetric type than parent 4866 4867TPM_RC_ATTRIBUTES 4868 4869inPulblic attributes are not allowed with selected parent 4870 4871TPM_RC_BINDING 4872 4873inPrivate and inPublic are not cryptographically bound 4874 4875TPM_RC_HASH 4876 4877incorrect hash selection for signing key 4878 4879TPM_RC_INTEGRITY 4880 4881HMAC on inPrivate was not valid 4882 4883TPM_RC_KDF 4884 4885KDF selection not allowed 4886 4887TPM_RC_KEY 4888 4889the size of the object's unique field is not consistent with the indicated 4890size in the object's parameters 4891 4892TPM_RC_OBJECT_MEMORY 4893 4894no available object slot 4895 4896TPM_RC_SCHEME 4897 4898the signing scheme is not valid for the key 4899 4900TPM_RC_SENSITIVE 4901 4902the inPrivate did not unmarshal correctly 4903 4904TPM_RC_SIZE 4905 4906inPrivate missing, or authPolicy size for inPublic or is not valid 4907 4908TPM_RC_SYMMETRIC 4909 4910symmetric algorithm not provided when required 4911 4912TPM_RC_TYPE 4913 4914parentHandle is not a storage key, or the object to load is a storage 4915key but its parameters do not match the parameters of the parent. 4916 4917TPM_RC_VALUE 49184 49195 49206 49217 49228 49239 492410 492511 492612 492713 492814 492915 493016 493117 493218 493319 493420 493521 493622 493723 493824 493925 494026 494127 494228 494329 494430 4945 4946Meaning 4947 4948decryption failure 4949 4950TPM_RC 4951TPM2_Load( 4952Load_In *in, 4953Load_Out *out 4954 4955// IN: input parameter list 4956// OUT: output parameter list 4957 4958) 4959{ 4960TPM_RC 4961TPMT_SENSITIVE 4962TPMI_RH_HIERARCHY 4963OBJECT 4964BOOL 4965 4966result = TPM_RC_SUCCESS; 4967sensitive; 4968hierarchy; 4969*parentObject = NULL; 4970skipChecks = FALSE; 4971 4972// Input Validation 4973if(in->inPrivate.t.size == 0) 4974return TPM_RC_SIZE + RC_Load_inPrivate; 4975parentObject = ObjectGet(in->parentHandle); 4976// Is the object that is being used as the parent actually a parent. 4977if(!AreAttributesForParent(parentObject)) 4978return TPM_RC_TYPE + RC_Load_parentHandle; 4979// If the parent is fixedTPM, then the attributes of the object 4980// are either "correct by construction" or were validated 4981// when the object was imported. If they pass the integrity 4982// check, then the values are valid 4983if(parentObject->publicArea.objectAttributes.fixedTPM) 4984skipChecks = TRUE; 4985 4986Family “2.0” 4987Level 00 Revision 00.99 4988 4989Published 4990Copyright © TCG 2006-2013 4991 4992Page 53 4993October 31, 2013 4994 4995 Part 3: Commands 499631 499732 499833 499934 500035 500136 500237 500338 500439 500540 500641 500742 500843 500944 501045 501146 501247 501348 501449 501550 501651 501752 501853 501954 502055 502156 502257 502358 502459 502560 502661 502762 502863 502964 503065 503166 503267 503368 503469 503570 503671 503772 503873 503974 504075 504176 5042 5043Trusted Platform Module Library 5044 5045else 5046{ 5047// If parent doesn't have fixedTPM SET, then this can't have 5048// fixedTPM SET. 5049if(in->inPublic.t.publicArea.objectAttributes.fixedTPM == SET) 5050return TPM_RC_ATTRIBUTES + RC_Load_inPublic; 5051// Perform self check on input public area. A TPM_RC_SIZE, TPM_RC_SCHEME, 5052// TPM_RC_VALUE, TPM_RC_SYMMETRIC, TPM_RC_TYPE, TPM_RC_HASH, 5053// TPM_RC_ASYMMETRIC, TPM_RC_ATTRIBUTES or TPM_RC_KDF error may be returned 5054// at this point 5055result = PublicAttributesValidation(TRUE, in->parentHandle, 5056&in->inPublic.t.publicArea); 5057if(result != TPM_RC_SUCCESS) 5058return RcSafeAddToResult(result, RC_Load_inPublic); 5059} 5060// Compute the name of object 5061ObjectComputeName(&in->inPublic.t.publicArea, &out->name); 5062// Retrieve sensitive data. PrivateToSensitive() may return TPM_RC_INTEGRITY or 5063// TPM_RC_SENSITIVE 5064// errors may be returned at this point 5065result = PrivateToSensitive(&in->inPrivate, &out->name, in->parentHandle, 5066in->inPublic.t.publicArea.nameAlg, 5067&sensitive); 5068if(result != TPM_RC_SUCCESS) 5069return RcSafeAddToResult(result, RC_Load_inPrivate); 5070// Internal Data Update 5071// Get hierarchy of parent 5072hierarchy = ObjectGetHierarchy(in->parentHandle); 5073// Create internal object. A lot of different errors may be returned by this 5074// loading operation as it will do several validations, including the public 5075// binding check 5076result = ObjectLoad(hierarchy, &in->inPublic.t.publicArea, &sensitive, 5077&out->name, in->parentHandle, skipChecks, 5078&out->objectHandle); 5079if(result != TPM_RC_SUCCESS) 5080return result; 5081return TPM_RC_SUCCESS; 5082} 5083 5084Page 54 5085October 31, 2013 5086 5087Published 5088Copyright © TCG 2006-2013 5089 5090Family “2.0” 5091Level 00 Revision 00.99 5092 5093 Trusted Platform Module Library 5094 509514.3 5096 5097Part 3: Commands 5098 5099TPM2_LoadExternal 5100 510114.3.1 General Description 5102This command is used to load an object that is not a Protected Object into the TPM. The command allows 5103loading of a public area or both a public and sensitive area. 5104NOTE 1 5105 5106Typical use for loading a public area is to allow the TPM to validate an asymmetric signature. 5107Typical use for loading both a public and sensitive area is to allow the TPM to be used as a crypto 5108accelerator. 5109 5110Load of a public external object area allows the object be associated with a hierarchy so that the correct 5111algorithms may be used when creating tickets. The hierarchy parameter provides this association. If the 5112public and sensitive portions of the object are loaded, hierarchy is required to be TPM_RH_NULL. 5113NOTE 2 5114 5115If both the public and private portions of an object are loaded, the object is not allowed to appear to 5116be part of a hierarchy. 5117 5118The object’s TPMA_OBJECT attributes will be checked according to the rules defined in 5119“TPMA_OBJECT” in Part 2. In particular, fixedTPM, fixedParent, and restricted shall be CLEAR if 5120inPrivate is not the Empty Buffer. 5121NOTE 3 5122 5123The duplication status of a public key needs to be able to be the same as the full key which may be 5124resident on a different TPM. If both the public and private parts of the key are loaded, then it is not 5125possible for the key to be either fixedTPM or fixedParent, since, its private area would not be 5126available in the clear to load. 5127 5128Objects loaded using this command will have a Name. The Name is the nameAlg of the object 5129concatenated with the digest of the public area using the nameAlg. The Qualified Name for the object will 5130be the same as its Name. The TPM will validate that the authPolicy is either the size of the digest 5131produced by nameAlg or the Empty Buffer. 5132NOTE 4 5133 5134If nameAlg is TPM_ALG_NULL, then the Name is the Empty Buffer. When the authorization value for 5135an object with no Name is computed, no Name value is included in the HMAC. To ensure that these 5136unnamed entities are not substituted, they should have an authValue that is statistically unique. 5137 5138NOTE 5 5139 5140The digest size for TPM_ALG_NULL is zero. 5141 5142If the nameAlg is TPM_ALG_NULL, the TPM shall not verify the cryptographic binding between the public 5143and sensitive areas, but the TPM will validate that the size of the key in the sensitive area is consistent 5144with the size indicated in the public area. If it is not, the TPM shall return TPM_RC_KEY_SIZE. 5145NOTE 6 5146 5147For an ECC object, the TPM will verify that the public key is on the curve of the key before the public 5148area is used. 5149 5150If nameAlg is not TPM_ALG_NULL, then the same consistency checks between inPublic and inPrivate 5151are made as for TPM2_Load(). 5152NOTE 7 5153 5154Consistency checks are necessary because an object with a Name needs to have the public and 5155sensitive portions cryptographically bound so that an attacker cannot mix pubic and sensitive areas. 5156 5157The command returns a handle for the loaded object and the Name that the TPM computed for 5158inPublic.public (that is, the TPMT_PUBLIC structure in inPublic). 5159NOTE 8 5160 5161The TPM-computed Name is provided as a convenience to the caller for those cases where the 5162caller does not implement the hash algorithm specified in the nameAlg of the object. 5163 5164Family “2.0” 5165Level 00 Revision 00.99 5166 5167Published 5168Copyright © TCG 2006-2013 5169 5170Page 55 5171October 31, 2013 5172 5173 Part 3: Commands 5174 5175Trusted Platform Module Library 5176 5177The hierarchy parameter associates the external object with a hierarchy. External objects are flushed 5178when their associated hierarchy is disabled. If hierarchy is TPM_RH_NULL, the object is part of no 5179hierarchy, and there is no implicit flush. 5180If hierarchy is TPM_RH_NULL or nameAlg is TPM_ALG_NULL, a ticket produced using the object shall 5181be a NULL Ticket. 5182EXAMPLE 5183 5184If a key is loaded with hierarchy set to TPM_RH_NULL, then TPM2_VerifySignature() will produce a 5185NULL Ticket of the required type. 5186 5187External objects are Temporary Objects. The saved external object contexts shall be invalidated at the 5188next TPM Reset. 5189 5190Page 56 5191October 31, 2013 5192 5193Published 5194Copyright © TCG 2006-2013 5195 5196Family “2.0” 5197Level 00 Revision 00.99 5198 5199 Trusted Platform Module Library 5200 5201Part 3: Commands 5202 520314.3.2 Command and Response 5204Table 23 — TPM2_LoadExternal Command 5205Type 5206 5207Name 5208 5209Description 5210 5211TPMI_ST_COMMAND_TAG 5212 5213tag 5214 5215UINT32 5216 5217commandSize 5218 5219TPM_CC 5220 5221commandCode 5222 5223TPM_CC_LoadExternal 5224 5225TPM2B_SENSITIVE 5226 5227inPrivate 5228 5229the sensitive portion of the object (optional) 5230 5231TPM2B_PUBLIC+ 5232 5233inPublic 5234 5235the public portion of the object 5236 5237TPMI_RH_HIERARCHY+ 5238 5239hierarchy 5240 5241hierarchy with which the object area is associated 5242 5243Table 24 — TPM2_LoadExternal Response 5244Type 5245 5246Name 5247 5248Description 5249 5250TPM_ST 5251 5252tag 5253 5254see clause 8 5255 5256UINT32 5257 5258responseSize 5259 5260TPM_RC 5261 5262responseCode 5263 5264TPM_HANDLE 5265 5266objectHandle 5267 5268handle for the loaded object 5269 5270TPM2B_NAME 5271 5272name 5273 5274name of the loaded object 5275 5276Family “2.0” 5277Level 00 Revision 00.99 5278 5279Published 5280Copyright © TCG 2006-2013 5281 5282Page 57 5283October 31, 2013 5284 5285 Part 3: Commands 5286 5287Trusted Platform Module Library 5288 528914.3.3 Detailed Actions 52901 52912 52923 5293 5294#include "InternalRoutines.h" 5295#include "LoadExternal_fp.h" 5296#include "Object_spt_fp.h" 5297Error Returns 5298TPM_RC_ATTRIBUTES 5299 5300'fixedParent" and fixedTPM must be CLEAR on on an external key if 5301both public and sensitive portions are loaded 5302 5303TPM_RC_BINDING 5304 5305the inPublic and inPrivate structures are not cryptographically bound. 5306 5307TPM_RC_HASH 5308 5309incorrect hash selection for signing key 5310 5311TPM_RC_HIERARCHY 5312 5313hierarchy is turned off, or only NULL hierarchy is allowed when 5314loading public and private parts of an object 5315 5316TPM_RC_KDF 5317 5318incorrect KDF selection for decrypting keyedHash object 5319 5320TPM_RC_KEY 5321 5322the size of the object's unique field is not consistent with the indicated 5323size in the object's parameters 5324 5325TPM_RC_OBJECT_MEMORY 5326 5327if there is no free slot for an object 5328 5329TPM_RC_SCHEME 5330 5331the signing scheme is not valid for the key 5332 5333TPM_RC_SIZE 5334 5335authPolicy is not zero and is not the size of a digest produced by the 5336object's nameAlg TPM_RH_NULL hierarchy 5337 5338TPM_RC_SYMMETRIC 5339 5340symmetric algorithm not provided when required 5341 5342TPM_RC_TYPE 53434 53445 53456 53467 53478 53489 534910 535011 535112 535213 535314 535415 535516 535617 535718 535819 535920 536021 536122 536223 536324 536425 536526 536627 536728 536829 536930 537031 537132 537233 5373 5374Meaning 5375 5376inPublic and inPrivate are not the same type 5377 5378TPM_RC 5379TPM2_LoadExternal( 5380LoadExternal_In 5381LoadExternal_Out 5382 5383*in, 5384*out 5385 5386// IN: input parameter list 5387// OUT: output parameter list 5388 5389TPM_RC 5390TPMT_SENSITIVE 5391BOOL 5392 5393result; 5394*sensitive; 5395skipChecks; 5396 5397) 5398{ 5399 5400// Input Validation 5401// If the target hierarchy is turned off, the object can not be loaded. 5402if(!HierarchyIsEnabled(in->hierarchy)) 5403return TPM_RC_HIERARCHY + RC_LoadExternal_hierarchy; 5404// the size of authPolicy is either 0 or the digest size of nameAlg 5405if(in->inPublic.t.publicArea.authPolicy.t.size != 0 5406&& in->inPublic.t.publicArea.authPolicy.t.size != 5407CryptGetHashDigestSize(in->inPublic.t.publicArea.nameAlg)) 5408return TPM_RC_SIZE + RC_LoadExternal_inPublic; 5409// For loading an object with both public and sensitive 5410if(in->inPrivate.t.size != 0) 5411{ 5412// An external object can only be loaded at TPM_RH_NULL hierarchy 5413if(in->hierarchy != TPM_RH_NULL) 5414return TPM_RC_HIERARCHY + RC_LoadExternal_hierarchy; 5415// An external object with a sensitive area must have fixedTPM == CLEAR 5416// fixedParent == CLEAR, and must have restrict CLEAR so that it does not 5417 5418Page 58 5419October 31, 2013 5420 5421Published 5422Copyright © TCG 2006-2013 5423 5424Family “2.0” 5425Level 00 Revision 00.99 5426 5427 Trusted Platform Module Library 542834 542935 543036 543137 543238 543339 543440 543541 543642 543743 543844 543945 544046 544147 544248 544349 544450 544551 544652 544753 544854 544955 545056 545157 545258 545359 545460 545561 545662 545763 545864 545965 5460 5461Part 3: Commands 5462 5463// appear to be a key that was created by this TPM. 5464if( 5465in->inPublic.t.publicArea.objectAttributes.fixedTPM != CLEAR 5466|| in->inPublic.t.publicArea.objectAttributes.fixedParent != CLEAR 5467|| in->inPublic.t.publicArea.objectAttributes.restricted != CLEAR 5468) 5469return TPM_RC_ATTRIBUTES + RC_LoadExternal_inPublic; 5470} 5471// Validate the scheme parameters 5472result = SchemeChecks(TRUE, TPM_RH_NULL, &in->inPublic.t.publicArea); 5473if(result != TPM_RC_SUCCESS) 5474return RcSafeAddToResult(result, RC_LoadExternal_inPublic); 5475// Internal Data Update 5476// Need the name to compute the qualified name 5477ObjectComputeName(&in->inPublic.t.publicArea, &out->name); 5478skipChecks = (in->inPublic.t.publicArea.nameAlg == TPM_ALG_NULL); 5479// If a sensitive area was provided, load it 5480if(in->inPrivate.t.size != 0) 5481sensitive = &in->inPrivate.t.sensitiveArea; 5482else 5483sensitive = NULL; 5484// Create external object. A TPM_RC_BINDING, TPM_RC_KEY, TPM_RC_OBJECT_MEMORY 5485// or TPM_RC_TYPE error may be returned by ObjectLoad() 5486result = ObjectLoad(in->hierarchy, &in->inPublic.t.publicArea, 5487sensitive, &out->name, TPM_RH_NULL, skipChecks, 5488&out->objectHandle); 5489return result; 5490} 5491 5492Family “2.0” 5493Level 00 Revision 00.99 5494 5495Published 5496Copyright © TCG 2006-2013 5497 5498Page 59 5499October 31, 2013 5500 5501 Part 3: Commands 5502 550314.4 5504 5505Trusted Platform Module Library 5506 5507TPM2_ReadPublic 5508 550914.4.1 General Description 5510This command allows access to the public area of a loaded object. 5511Use of the objectHandle does not require authorization. 5512NOTE 5513 5514Since the caller is not likely to know the public area of the object associated with objectHandle, it 5515would not be possible to include the Name associated with objectHandle in the cpHash computation. 5516 5517If objectHandle references a sequence object, the TPM shall return TPM_RC_SEQUENCE. 5518 5519Page 60 5520October 31, 2013 5521 5522Published 5523Copyright © TCG 2006-2013 5524 5525Family “2.0” 5526Level 00 Revision 00.99 5527 5528 Trusted Platform Module Library 5529 5530Part 3: Commands 5531 553214.4.2 Command and Response 5533Table 25 — TPM2_ReadPublic Command 5534Type 5535 5536Name 5537 5538Description 5539 5540TPMI_ST_COMMAND_TAG 5541 5542tag 5543 5544UINT32 5545 5546commandSize 5547 5548TPM_CC 5549 5550commandCode 5551 5552TPM_CC_ReadPublic 5553 5554TPMI_DH_OBJECT 5555 5556objectHandle 5557 5558TPM handle of an object 5559Auth Index: None 5560 5561Table 26 — TPM2_ReadPublic Response 5562Type 5563 5564Name 5565 5566Description 5567 5568TPM_ST 5569 5570tag 5571 5572see clause 8 5573 5574UINT32 5575 5576responseSize 5577 5578TPM_RC 5579 5580responseCode 5581 5582TPM2B_PUBLIC 5583 5584outPublic 5585 5586structure containing the public area of an object 5587 5588TPM2B_NAME 5589 5590name 5591 5592name of the object 5593 5594TPM2B_NAME 5595 5596qualifiedName 5597 5598the Qualified Name of the object 5599 5600Family “2.0” 5601Level 00 Revision 00.99 5602 5603Published 5604Copyright © TCG 2006-2013 5605 5606Page 61 5607October 31, 2013 5608 5609 Part 3: Commands 5610 5611Trusted Platform Module Library 5612 561314.4.3 Detailed Actions 56141 56152 5616 5617#include "InternalRoutines.h" 5618#include "ReadPublic_fp.h" 5619Error Returns 5620TPM_RC_SEQUENCE 5621 56223 56234 56245 56256 56267 56278 56289 562910 563011 563112 563213 563314 563415 563516 563617 563718 563819 563920 564021 564122 564223 564324 564425 564526 564627 564728 564829 564930 565031 565132 565233 565334 565435 565536 5656 5657Meaning 5658can not read the public area of a sequence object 5659 5660TPM_RC 5661TPM2_ReadPublic( 5662ReadPublic_In 5663ReadPublic_Out 5664 5665*in, 5666*out 5667 5668// IN: input parameter list 5669// OUT: output parameter list 5670 5671OBJECT 5672 5673*object; 5674 5675) 5676{ 5677// Input Validation 5678// Get loaded object pointer 5679object = ObjectGet(in->objectHandle); 5680// Can not read public area of a sequence object 5681if(ObjectIsSequence(object)) 5682return TPM_RC_SEQUENCE; 5683// Command Output 5684// Compute size of public area in canonical form 5685out->outPublic.t.size = TPMT_PUBLIC_Marshal(&object->publicArea, NULL, NULL); 5686// Copy public area to output 5687out->outPublic.t.publicArea = object->publicArea; 5688// Copy name to output 5689out->name.t.size = ObjectGetName(in->objectHandle, &out->name.t.name); 5690// Copy qualified name to output 5691ObjectGetQualifiedName(in->objectHandle, &out->qualifiedName); 5692return TPM_RC_SUCCESS; 5693} 5694 5695Page 62 5696October 31, 2013 5697 5698Published 5699Copyright © TCG 2006-2013 5700 5701Family “2.0” 5702Level 00 Revision 00.99 5703 5704 Trusted Platform Module Library 5705 570614.5 5707 5708Part 3: Commands 5709 5710TPM2_ActivateCredential 5711 571214.5.1 General Description 5713This command enables the association of a credential with an object in a way that ensures that the TPM 5714has validated the parameters of the credentialed object. 5715If both the public and private portions of activateHandle and keyHandle are not loaded, then the TPM 5716shall return TPM_RC_AUTH_UNAVAILABLE. 5717If keyHandle is not a Storage Key, then the TPM shall return TPM_RC_TYPE. 5718Authorization for activateHandle requires the ADMIN role. 5719The key associated with keyHandle is used to recover a seed from secret, which is the encrypted seed. 5720The Name of the object associated with activateHandle and the recovered seed are used in a KDF to 5721recover the symmetric key. The recovered seed (but not the Name) is used is used in a KDF to recover 5722the HMAC key. 5723The HMAC is used to validate that the credentialBlob is associated with activateHandle and that the data 5724in credentialBlob has not been modified. The linkage to the object associated with activateHandle is 5725achieved by including the Name in the HMAC calculation. 5726If the integrity checks succeed, credentialBlob is decrypted and returned as certInfo. 5727 5728Family “2.0” 5729Level 00 Revision 00.99 5730 5731Published 5732Copyright © TCG 2006-2013 5733 5734Page 63 5735October 31, 2013 5736 5737 Part 3: Commands 5738 5739Trusted Platform Module Library 5740 574114.5.2 Command and Response 5742Table 27 — TPM2_ActivateCredential Command 5743Type 5744 5745Name 5746 5747TPMI_ST_COMMAND_TAG 5748 5749tag 5750 5751UINT32 5752 5753commandSize 5754 5755TPM_CC 5756 5757commandCode 5758 5759TPMI_DH_OBJECT 5760 5761Description 5762 5763TPM_CC_ActivateCredential 5764 5765@activateHandle 5766 5767handle of the object associated with certificate in 5768credentialBlob 5769Auth Index: 1 5770Auth Role: ADMIN 5771 5772TPMI_DH_OBJECT 5773 5774@keyHandle 5775 5776loaded key used to decrypt the TPMS_SENSITIVE in 5777credentialBlob 5778Auth Index: 2 5779Auth Role: USER 5780 5781TPM2B_ID_OBJECT 5782 5783credentialBlob 5784 5785the credential 5786 5787TPM2B_ENCRYPTED_SECRET 5788 5789secret 5790 5791keyHandle algorithm-dependent encrypted seed that 5792protects credentialBlob 5793 5794Table 28 — TPM2_ActivateCredential Response 5795Type 5796 5797Name 5798 5799Description 5800 5801TPM_ST 5802 5803tag 5804 5805see clause 8 5806 5807UINT32 5808 5809responseSize 5810 5811TPM_RC 5812 5813responseCode 5814 5815TPM2B_DIGEST 5816 5817certInfo 5818 5819Page 64 5820October 31, 2013 5821 5822the decrypted certificate information 5823the data should be no larger than the size of the digest 5824of the nameAlg associated with keyHandle 5825 5826Published 5827Copyright © TCG 2006-2013 5828 5829Family “2.0” 5830Level 00 Revision 00.99 5831 5832 Trusted Platform Module Library 5833 5834Part 3: Commands 5835 583614.5.3 Detailed Actions 58371 58382 58393 5840 5841#include "InternalRoutines.h" 5842#include "ActivateCredential_fp.h" 5843#include "Object_spt_fp.h" 5844Error Returns 5845TPM_RC_ATTRIBUTES 5846 5847keyHandle does not reference a decryption key 5848 5849TPM_RC_ECC_POINT 5850 5851secret is invalid (when keyHandle is an ECC key) 5852 5853TPM_RC_INSUFFICIENT 5854 5855secret is invalid (when keyHandle is an ECC key) 5856 5857TPM_RC_INTEGRITY 5858 5859credentialBlob fails integrity test 5860 5861TPM_RC_NO_RESULT 5862 5863secret is invalid (when keyHandle is an ECC key) 5864 5865TPM_RC_SIZE 5866 5867secret size is invalid or the credentialBlob does not unmarshal 5868correctly 5869 5870TPM_RC_TYPE 5871 5872keyHandle does not reference an asymmetric key. 5873 5874TPM_RC_VALUE 58754 58765 58776 58787 58798 58809 588110 588211 588312 588413 588514 588615 588716 588817 588918 589019 589120 589221 589322 589423 589524 589625 589726 589827 589928 590029 590130 590231 590332 590433 590534 590635 590736 590837 590938 591039 591140 591241 5913 5914Meaning 5915 5916secret is invalid (when keyHandle is an RSA key) 5917 5918TPM_RC 5919TPM2_ActivateCredential( 5920ActivateCredential_In 5921ActivateCredential_Out 5922 5923*in, 5924*out 5925 5926// IN: input parameter list 5927// OUT: output parameter list 5928 5929TPM_RC 5930OBJECT 5931OBJECT 5932// credential 5933TPM2B_DATA 5934 5935result = TPM_RC_SUCCESS; 5936*object; 5937// decrypt key 5938*activateObject;// key associated with 5939 5940) 5941{ 5942 5943data; 5944 5945// credential data 5946 5947// Input Validation 5948// Get decrypt key pointer 5949object = ObjectGet(in->keyHandle); 5950// Get certificated object pointer 5951activateObject = ObjectGet(in->activateHandle); 5952// input decrypt key must be an asymmetric, restricted decryption key 5953if( 5954!CryptIsAsymAlgorithm(object->publicArea.type) 5955|| object->publicArea.objectAttributes.decrypt == CLEAR 5956|| object->publicArea.objectAttributes.restricted == CLEAR) 5957return TPM_RC_TYPE + RC_ActivateCredential_keyHandle; 5958// Command output 5959// Decrypt input credential data via asymmetric decryption. A 5960// TPM_RC_VALUE, TPM_RC_KEY or unmarshal errors may be returned at this 5961// point 5962result = CryptSecretDecrypt(in->keyHandle, NULL, 5963"IDENTITY", &in->secret, &data); 5964if(result != TPM_RC_SUCCESS) 5965{ 5966if(result == TPM_RC_KEY) 5967return TPM_RC_FAILURE; 5968 5969Family “2.0” 5970Level 00 Revision 00.99 5971 5972Published 5973Copyright © TCG 2006-2013 5974 5975Page 65 5976October 31, 2013 5977 5978 Part 3: Commands 597942 598043 598144 598245 598346 598447 598548 598649 598750 598851 598952 599053 599154 599255 599356 5994 5995Trusted Platform Module Library 5996 5997return RcSafeAddToResult(result, RC_ActivateCredential_secret); 5998} 5999// Retrieve secret data. A TPM_RC_INTEGRITY error or unmarshal 6000// errors may be returned at this point 6001result = CredentialToSecret(&in->credentialBlob, 6002&activateObject->name, 6003(TPM2B_SEED *) &data, 6004in->keyHandle, 6005&out->certInfo); 6006if(result != TPM_RC_SUCCESS) 6007return RcSafeAddToResult(result,RC_ActivateCredential_credentialBlob); 6008return TPM_RC_SUCCESS; 6009} 6010 6011Page 66 6012October 31, 2013 6013 6014Published 6015Copyright © TCG 2006-2013 6016 6017Family “2.0” 6018Level 00 Revision 00.99 6019 6020 Trusted Platform Module Library 6021 602214.6 6023 6024Part 3: Commands 6025 6026TPM2_MakeCredential 6027 602814.6.1 General Description 6029This command allows the TPM to perform the actions required of a Certificate Authority (CA) in creating a 6030TPM2B_ID_OBJECT containing an activation credential. 6031The TPM will produce a TPM_ID_OBJECT according to the methods in “Credential Protection” in Part 1. 6032The loaded public area referenced by handle is required to be the public area of a Storage key, 6033otherwise, the credential cannot be properly sealed. 6034This command does not use any TPM secrets nor does it require authorization. It is a convenience 6035function, using the TPM to perform cryptographic calculations that could be done externally. 6036 6037Family “2.0” 6038Level 00 Revision 00.99 6039 6040Published 6041Copyright © TCG 2006-2013 6042 6043Page 67 6044October 31, 2013 6045 6046 Part 3: Commands 6047 6048Trusted Platform Module Library 6049 605014.6.2 Command and Response 6051Table 29 — TPM2_MakeCredential Command 6052Type 6053 6054Name 6055 6056Description 6057 6058TPMI_ST_COMMAND_TAG 6059 6060tag 6061 6062UINT32 6063 6064commandSize 6065 6066TPM_CC 6067 6068commandCode 6069 6070TPM_CC_MakeCredential 6071 6072TPMI_DH_OBJECT 6073 6074handle 6075 6076loaded public area, used to encrypt the sensitive area 6077containing the credential key 6078Auth Index: None 6079 6080TPM2B_DIGEST 6081 6082credential 6083 6084the credential information 6085 6086TPM2B_NAME 6087 6088objectName 6089 6090Name of the object to which the credential applies 6091 6092Table 30 — TPM2_MakeCredential Response 6093Type 6094 6095Name 6096 6097Description 6098 6099TPM_ST 6100 6101tag 6102 6103see clause 8 6104 6105UINT32 6106 6107responseSize 6108 6109TPM_RC 6110 6111responseCode 6112 6113TPM2B_ID_OBJECT 6114 6115credentialBlob 6116 6117TPM2B_ENCRYPTED_SECRET secret 6118 6119Page 68 6120October 31, 2013 6121 6122the credential 6123handle algorithm-dependent data that wraps the key 6124that encrypts credentialBlob 6125 6126Published 6127Copyright © TCG 2006-2013 6128 6129Family “2.0” 6130Level 00 Revision 00.99 6131 6132 Trusted Platform Module Library 6133 6134Part 3: Commands 6135 613614.6.3 Detailed Actions 61371 61382 61393 6140 6141#include "InternalRoutines.h" 6142#include "MakeCredential_fp.h" 6143#include "Object_spt_fp.h" 6144Error Returns 6145TPM_RC_KEY 6146 6147handle referenced an ECC key that has a unique field that is not a 6148point on the curve of the key 6149 6150TPM_RC_SIZE 6151 6152credential is larger than the digest size of Name algorithm of handle 6153 6154TPM_RC_TYPE 61554 61565 61576 61587 61598 61609 616110 616211 616312 616413 616514 616615 616716 616817 616918 617019 617120 617221 617322 617423 617524 617625 617726 617827 617928 618029 618130 618231 618332 618433 618534 618635 618736 618837 618938 619039 619140 619241 619342 619443 619544 619645 619746 619847 6199 6200Meaning 6201 6202handle does not reference an asymmetric decryption key 6203 6204TPM_RC 6205TPM2_MakeCredential( 6206MakeCredential_In 6207MakeCredential_Out 6208 6209*in, 6210*out 6211 6212// IN: input parameter list 6213// OUT: output parameter list 6214 6215TPM_RC 6216 6217result = TPM_RC_SUCCESS; 6218 6219OBJECT 6220TPM2B_DATA 6221 6222*object; 6223data; 6224 6225) 6226{ 6227 6228// Input Validation 6229// Get object pointer 6230object = ObjectGet(in->handle); 6231// input key must be an asymmetric, restricted decryption key 6232// NOTE: Needs to be restricted to have a symmetric value. 6233if( 6234!CryptIsAsymAlgorithm(object->publicArea.type) 6235|| object->publicArea.objectAttributes.decrypt == CLEAR 6236|| object->publicArea.objectAttributes.restricted == CLEAR 6237) 6238return TPM_RC_TYPE + RC_MakeCredential_handle; 6239// The credential information may not be larger than the digest size used for 6240// the Name of the key associated with handle. 6241if(in->credential.t.size > CryptGetHashDigestSize(object->publicArea.nameAlg)) 6242return TPM_RC_SIZE + RC_MakeCredential_credential; 6243// Command Output 6244// Make encrypt key and its associated secret structure. 6245// Even though CrypeSecretEncrypt() may return 6246out->secret.t.size = sizeof(out->secret.t.secret); 6247result = CryptSecretEncrypt(in->handle, "IDENTITY", &data, &out->secret); 6248if(result != TPM_RC_SUCCESS) 6249return result; 6250// Prepare output credential data from secret 6251SecretToCredential(&in->credential, &in->objectName, (TPM2B_SEED *) &data, 6252in->handle, &out->credentialBlob); 6253return TPM_RC_SUCCESS; 6254} 6255 6256Family “2.0” 6257Level 00 Revision 00.99 6258 6259Published 6260Copyright © TCG 2006-2013 6261 6262Page 69 6263October 31, 2013 6264 6265 Part 3: Commands 6266 626714.7 6268 6269Trusted Platform Module Library 6270 6271TPM2_Unseal 6272 627314.7.1 General Description 6274This command returns the data in a loaded Sealed Data Object. 6275NOTE 6276 6277A random, TPM-generated, Sealed Data Object may be created by the TPM with TPM2_Create() or 6278TPM2_CreatePrimary() using the template for a Sealed Data Object. A Sealed Data Object is more 6279likely to be created externally and imported (TPM2_Import()) so that the data is not created by the 6280TPM. 6281 6282The returned value may be encrypted using authorization session encryption. 6283If either restricted, decrypt, or sign is SET in the attributes of itemHandle, then the TPM shall return 6284TPM_RC_ATTRIBUTES. If the type of itemHandle is not TPM_ALG_KEYEDHASH, then the TPM shall 6285return TPM_RC_TYPE. 6286 6287Page 70 6288October 31, 2013 6289 6290Published 6291Copyright © TCG 2006-2013 6292 6293Family “2.0” 6294Level 00 Revision 00.99 6295 6296 Trusted Platform Module Library 6297 6298Part 3: Commands 6299 630014.7.2 Command and Response 6301Table 31 — TPM2_Unseal Command 6302Type 6303 6304Name 6305 6306TPMI_ST_COMMAND_TAG 6307 6308Tag 6309 6310UINT32 6311 6312commandSize 6313 6314TPM_CC 6315 6316commandCode 6317 6318TPM_CC_Unseal 6319 6320@itemHandle 6321 6322handle of a loaded data object 6323Auth Index: 1 6324Auth Role: USER 6325 6326TPMI_DH_OBJECT 6327 6328Description 6329 6330Table 32 — TPM2_Unseal Response 6331Type 6332 6333Name 6334 6335Description 6336 6337TPM_ST 6338 6339tag 6340 6341see clause 8 6342 6343UINT32 6344 6345responseSize 6346 6347TPM_RC 6348 6349responseCode 6350 6351TPM2B_SENSITIVE_DATA 6352 6353outData 6354 6355Family “2.0” 6356Level 00 Revision 00.99 6357 6358unsealed data 6359Size of outData is limited to be no more than 128 octets. 6360 6361Published 6362Copyright © TCG 2006-2013 6363 6364Page 71 6365October 31, 2013 6366 6367 Part 3: Commands 6368 6369Trusted Platform Module Library 6370 637114.7.3 Detailed Actions 63721 63732 6374 6375#include "InternalRoutines.h" 6376#include "Unseal_fp.h" 6377Error Returns 6378TPM_RC_ATTRIBUTES 6379 6380itemHandle has wrong attributes 6381 6382TPM_RC_TYPE 63833 63844 63855 63866 63877 63888 63899 639010 639111 639212 639313 639414 639515 639616 639717 639818 639919 640020 640121 640222 640323 640424 640525 640626 640727 640828 6409 6410Meaning 6411 6412itemHandle is not a KEYEDHASH data object 6413 6414TPM_RC 6415TPM2_Unseal(Unseal_In *in, Unseal_Out *out) 6416{ 6417OBJECT 6418 6419*object; 6420 6421// Input Validation 6422// Get pointer to loaded object 6423object = ObjectGet(in->itemHandle); 6424// Input handle must be a data object 6425if(object->publicArea.type != TPM_ALG_KEYEDHASH) 6426return TPM_RC_TYPE + RC_Unseal_itemHandle; 6427if( 6428object->publicArea.objectAttributes.decrypt == SET 6429|| object->publicArea.objectAttributes.sign == SET 6430|| object->publicArea.objectAttributes.restricted == SET) 6431return TPM_RC_ATTRIBUTES + RC_Unseal_itemHandle; 6432// Command Output 6433// Copy data 6434MemoryCopy2B(&out->outData.b, &object->sensitive.sensitive.bits.b, 6435sizeof(out->outData.t.buffer)); 6436return TPM_RC_SUCCESS; 6437} 6438 6439Page 72 6440October 31, 2013 6441 6442Published 6443Copyright © TCG 2006-2013 6444 6445Family “2.0” 6446Level 00 Revision 00.99 6447 6448 Trusted Platform Module Library 6449 645014.8 6451 6452Part 3: Commands 6453 6454TPM2_ObjectChangeAuth 6455 645614.8.1 General Description 6457This command is used to change the authorization secret for a TPM-resident object. 6458If successful, a new private area for the TPM-resident object associated with objectHandle is returned, 6459which includes the new authorization value. 6460This command does not change the authorization of the TPM-resident object on which it operates. 6461Therefore, the old authValue (of the TPM-resident object) is used when generating the response HMAC 6462key if required.. 6463NOTE 1 6464 6465The returned outPrivate will need to be loaded before the new authorization will apply. 6466 6467NOTE 2 6468 6469The TPM-resident object may be persistent and changing the authorization value of the persistent 6470object could prevent other users from accessing the object. This is why this command does not 6471change the TPM-resident object. 6472 6473EXAMPLE 6474 6475If 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 6476persistent key would deny access to other users. 6477 6478This command may not be used to change the authorization value for an NV Index or a Primary Object. 6479NOTE 3 6480 6481If an NV Index is to have a new authorization, it is done with TPM2_NV_ChangeAuth(). 6482 6483NOTE 4 6484 6485If a Primary Object is to have a new authorization, it needs to be recreated (TPM2_CreatePrimary()). 6486 6487Family “2.0” 6488Level 00 Revision 00.99 6489 6490Published 6491Copyright © TCG 2006-2013 6492 6493Page 73 6494October 31, 2013 6495 6496 Part 3: Commands 6497 6498Trusted Platform Module Library 6499 650014.8.2 Command and Response 6501Table 33 — TPM2_ObjectChangeAuth Command 6502Type 6503 6504Name 6505 6506Description 6507 6508TPMI_ST_COMMAND_TAG 6509 6510tag 6511 6512UINT32 6513 6514commandSize 6515 6516TPM_CC 6517 6518commandCode 6519 6520TPM_CC_ObjectChangeAuth 6521 6522TPMI_DH_OBJECT 6523 6524@objectHandle 6525 6526handle of the object 6527Auth Index: 1 6528Auth Role: ADMIN 6529 6530TPMI_DH_OBJECT 6531 6532parentHandle 6533 6534handle of the parent 6535Auth Index: None 6536 6537TPM2B_AUTH 6538 6539newAuth 6540 6541new authorization value 6542 6543Table 34 — TPM2_ObjectChangeAuth Response 6544Type 6545 6546Name 6547 6548Description 6549 6550TPM_ST 6551 6552tag 6553 6554see clause 8 6555 6556UINT32 6557 6558responseSize 6559 6560TPM_RC 6561 6562responseCode 6563 6564TPM2B_PRIVATE 6565 6566outPrivate 6567 6568Page 74 6569October 31, 2013 6570 6571private area containing the new authorization value 6572 6573Published 6574Copyright © TCG 2006-2013 6575 6576Family “2.0” 6577Level 00 Revision 00.99 6578 6579 Trusted Platform Module Library 6580 6581Part 3: Commands 6582 658314.8.3 Detailed Actions 65841 65852 65863 6587 6588#include "InternalRoutines.h" 6589#include "ObjectChangeAuth_fp.h" 6590#include "Object_spt_fp.h" 6591Error Returns 6592TPM_RC_SIZE 6593 6594newAuth is larger than the size of the digest of the Name algorithm of 6595objectHandle 6596 6597TPM_RC_TYPE 6598 65994 66005 66016 66027 66038 66049 660510 660611 660712 660813 660914 661015 661116 661217 661318 661419 661520 661621 661722 661823 661924 662025 662126 662227 662328 662429 662530 662631 662732 662833 662934 663035 663136 663237 663338 663439 663540 663641 663742 663843 663944 664045 664146 664247 664348 664449 664550 664651 6647 6648Meaning 6649 6650the key referenced by parentHandle is not the parent of the object 6651referenced by objectHandle; or objectHandle is a sequence object. 6652 6653TPM_RC 6654TPM2_ObjectChangeAuth( 6655ObjectChangeAuth_In 6656ObjectChangeAuth_Out 6657 6658*in, 6659*out 6660 6661// IN: input parameter list 6662// OUT: output parameter list 6663 6664) 6665{ 6666TPMT_SENSITIVE 6667OBJECT 6668TPM2B_NAME 6669TPM2B_NAME 6670 6671sensitive; 6672*object; 6673objectQN, QNCompare; 6674parentQN; 6675 6676// Input Validation 6677// Get object pointer 6678object = ObjectGet(in->objectHandle); 6679// Can not change auth on sequence object 6680if(ObjectIsSequence(object)) 6681return TPM_RC_TYPE + RC_ObjectChangeAuth_objectHandle; 6682// Make sure that the auth value is consistent with the nameAlg 6683if( MemoryRemoveTrailingZeros(&in->newAuth) 6684> CryptGetHashDigestSize(object->publicArea.nameAlg)) 6685return TPM_RC_SIZE + RC_ObjectChangeAuth_newAuth; 6686// Check parent for object 6687// parent handle must be the parent of object handle. In this 6688// implementation we verify this by checking the QN of object. Other 6689// implementation may choose different method to verify this attribute. 6690ObjectGetQualifiedName(in->parentHandle, &parentQN); 6691ObjectComputeQualifiedName(&parentQN, object->publicArea.nameAlg, 6692&object->name, &QNCompare); 6693ObjectGetQualifiedName(in->objectHandle, &objectQN); 6694if(!Memory2BEqual(&objectQN.b, &QNCompare.b)) 6695return TPM_RC_TYPE + RC_ObjectChangeAuth_parentHandle; 6696// Command Output 6697// Copy internal sensitive area 6698sensitive = object->sensitive; 6699// Copy authValue 6700sensitive.authValue = in->newAuth; 6701// Prepare output private data from sensitive 6702SensitiveToPrivate(&sensitive, &object->name, in->parentHandle, 6703 6704Family “2.0” 6705Level 00 Revision 00.99 6706 6707Published 6708Copyright © TCG 2006-2013 6709 6710Page 75 6711October 31, 2013 6712 6713 Part 3: Commands 671452 671553 671654 671755 671856 6719 6720Trusted Platform Module Library 6721object->publicArea.nameAlg, 6722&out->outPrivate); 6723 6724return TPM_RC_SUCCESS; 6725} 6726 6727Page 76 6728October 31, 2013 6729 6730Published 6731Copyright © TCG 2006-2013 6732 6733Family “2.0” 6734Level 00 Revision 00.99 6735 6736 Trusted Platform Module Library 6737 673815 6739 6740Part 3: Commands 6741 6742Duplication Commands 6743 674415.1 6745 6746TPM2_Duplicate 6747 674815.1.1 General Description 6749This command duplicates a loaded object so that it may be used in a different hierarchy. The new parent 6750key for the duplicate may be on the same or different TPM or TPM_RH_NULL. Only the public area of 6751newParentHandle is required to be loaded. 6752NOTE 1 6753 6754Since the new parent may only be extant on a different TPM, it is likely that the new parent’s 6755sensitive area could not be loaded in the TPM from which objectHandle is being duplicated. 6756 6757If encryptedDuplication is SET in the object being duplicated, then the TPM shall return 6758TPM_RC_SYMMETRIC if symmetricAlg is TPM_RH_NULL or TPM_RC_HIERARCHY if 6759newParentHandle is TPM_RH_NULL. 6760The authorization for this command shall be with a policy session. 6761If fixedParent of objectHandle→attributes is SET, the TPM shall return TPM_RC_ATTRIBUTES. If 6762objectHandle→nameAlg is TPM_ALG_NULL, the TPM shall return TPM_RC_TYPE. 6763The policySession→commandCode parameter in the policy session is required to be TPM_CC_Duplicate 6764to indicate that authorization for duplication has been provided. This indicates that the policy that is being 6765used is a policy that is for duplication, and not a policy that would approve another use. That is, authority 6766to use an object does not grant authority to duplicate the object. 6767The policy is likely to include cpHash in order to restrict where duplication can occur. 6768If 6769TPM2_PolicyCpHash() has been executed as part of the policy, the policySession→cpHash is compared 6770to the cpHash of the command. 6771If TPM2_PolicyDuplicationSelect() has 6772policySession→nameHash is compared to 6773 6774been 6775 6776executed 6777 6778as 6779 6780part 6781 6782of 6783 6784the 6785 6786policy, 6787 6788HpolicyAlg(objectHandle→Name || newParentHandle→Name) 6789 6790the 6791(2) 6792 6793If the compared hashes are not the same, then the TPM shall return TPM_RC_POLICY_FAIL. 6794NOTE 2 6795 6796It is allowed that policySesion→nameHash and policySession→cpHash share the same memory 6797space. 6798 6799NOTE 3 6800 6801A duplication policy is not required to have either TPM2_PolicyDuplicationSelect() or 6802TPM2_PolicyCpHash() as part of the policy. If neither is present, then the duplication policy may be 6803satisfied with a policy that only contains TPM2_PolicyCommaneCode( code = TPM_CC_Duplicate). 6804 6805The TPM shall follow the process of encryption defined in the “Duplication” subclause of “Protected 6806Storage Hierarchy” in Part 1 of this specification. 6807 6808Family “2.0” 6809Level 00 Revision 00.99 6810 6811Published 6812Copyright © TCG 2006-2013 6813 6814Page 77 6815October 31, 2013 6816 6817 Part 3: Commands 6818 6819Trusted Platform Module Library 6820 682115.1.2 Command and Response 6822Table 35 — TPM2_Duplicate Command 6823Type 6824 6825Name 6826 6827Description 6828 6829TPMI_ST_COMMAND_TAG 6830 6831tag 6832 6833UINT32 6834 6835commandSize 6836 6837TPM_CC 6838 6839commandCode 6840 6841TPM_CC_Duplicate 6842 6843TPMI_DH_OBJECT 6844 6845@objectHandle 6846 6847loaded object to duplicate 6848Auth Index: 1 6849Auth Role: DUP 6850 6851TPMI_DH_OBJECT+ 6852 6853newParentHandle 6854 6855shall reference the public area of an asymmetric key 6856Auth Index: None 6857 6858TPM2B_DATA 6859 6860encryptionKeyIn 6861 6862optional symmetric encryption key 6863The size for this key is set to zero when the TPM is to 6864generate the key. This parameter may be encrypted. 6865 6866TPMT_SYM_DEF_OBJECT+ 6867 6868symmetricAlg 6869 6870definition for the symmetric algorithm to be used for the 6871inner wrapper 6872may be TPM_ALG_NULL if no inner wrapper is applied 6873 6874Table 36 — TPM2_Duplicate Response 6875Type 6876 6877Name 6878 6879Description 6880 6881TPM_ST 6882 6883tag 6884 6885see clause 8 6886 6887UINT32 6888 6889responseSize 6890 6891TPM_RC 6892 6893responseCode 6894 6895TPM2B_DATA 6896 6897encryptionKeyOut 6898 6899If the caller provided an encryption key or if 6900symmetricAlg was TPM_ALG_NULL, then this will be 6901the Empty Buffer; otherwise, it shall contain the TPMgenerated, symmetric encryption key for the inner 6902wrapper. 6903 6904TPM2B_PRIVATE 6905 6906duplicate 6907 6908private area that may be encrypted by encryptionKeyIn; 6909and may be doubly encrypted 6910 6911TPM2B_ENCRYPTED_SECRET outSymSeed 6912 6913Page 78 6914October 31, 2013 6915 6916seed protected by the asymmetric algorithms of new 6917parent (NP) 6918 6919Published 6920Copyright © TCG 2006-2013 6921 6922Family “2.0” 6923Level 00 Revision 00.99 6924 6925 Trusted Platform Module Library 6926 6927Part 3: Commands 6928 692915.1.3 Detailed Actions 69301 69312 69323 6933 6934#include "InternalRoutines.h" 6935#include "Duplicate_fp.h" 6936#include "Object_spt_fp.h" 6937Error Returns 6938TPM_RC_ATTRIBUTES 6939 6940key to duplicate has fixedParent SET 6941 6942TPM_RC_HIERARCHY 6943 6944encryptedDuplication is SET and newParentHandle specifies Null 6945Hierarchy 6946 6947TPM_RC_KEY 6948 6949newParentHandle references invalid ECC key (public point not on the 6950curve) 6951 6952TPM_RC_SIZE 6953 6954input encryption key size does not match the size specified in 6955symmetric algorithm 6956 6957TPM_RC_SYMMETRIC 6958 6959encryptedDuplication is SET but no symmetric algorithm is provided 6960 6961TPM_RC_TYPE 6962 69634 69645 69656 69667 69678 69689 696910 697011 697112 697213 697314 697415 697516 697617 697718 697819 697920 698021 698122 698223 698324 698425 698526 698627 698728 698829 698930 699031 699132 699233 699334 699435 699536 699637 699738 699839 699940 700041 700142 7002 7003Meaning 7004 7005newParentHandle is neither a storage key nor TPM_RH_NULL; or 7006the object has a NULL nameAlg 7007 7008TPM_RC 7009TPM2_Duplicate( 7010Duplicate_In 7011Duplicate_Out 7012 7013*in, 7014*out 7015 7016// IN: input parameter list 7017// OUT: output parameter list 7018 7019) 7020{ 7021TPM_RC 7022TPMT_SENSITIVE 7023 7024result = TPM_RC_SUCCESS; 7025sensitive; 7026 7027UINT16 7028 7029innerKeySize = 0; // encrypt key size for inner wrap 7030 7031OBJECT 7032TPM2B_DATA 7033 7034*object; 7035data; 7036 7037// Input Validation 7038// Get duplicate object pointer 7039object = ObjectGet(in->objectHandle); 7040// duplicate key must have fixParent bit CLEAR. 7041if(object->publicArea.objectAttributes.fixedParent == SET) 7042return TPM_RC_ATTRIBUTES + RC_Duplicate_objectHandle; 7043// Do not duplicate object with NULL nameAlg 7044if(object->publicArea.nameAlg == TPM_ALG_NULL) 7045return TPM_RC_TYPE + RC_Duplicate_objectHandle; 7046// new parent key must be a storage object or TPM_RH_NULL 7047if(in->newParentHandle != TPM_RH_NULL 7048&& !ObjectIsStorage(in->newParentHandle)) 7049return TPM_RC_TYPE + RC_Duplicate_newParentHandle; 7050// If the duplicates object has encryptedDuplication SET, then there must be 7051// an inner wrapper and the new parent may not be TPM_RH_NULL 7052if(object->publicArea.objectAttributes.encryptedDuplication == SET) 7053{ 7054if(in->symmetricAlg.algorithm == TPM_ALG_NULL) 7055return TPM_RC_SYMMETRIC + RC_Duplicate_symmetricAlg; 7056if(in->newParentHandle == TPM_RH_NULL) 7057 7058Family “2.0” 7059Level 00 Revision 00.99 7060 7061Published 7062Copyright © TCG 2006-2013 7063 7064Page 79 7065October 31, 2013 7066 7067 Part 3: Commands 706843 706944 707045 707146 707247 707348 707449 707550 707651 707752 707853 707954 708055 708156 708257 708358 708459 708560 708661 708762 708863 708964 709065 709166 709267 709368 709469 709570 709671 709772 709873 709974 710075 710176 710277 710378 710479 710580 710681 710782 710883 710984 711085 711186 711287 711388 711489 711590 711691 711792 711893 711994 712095 712196 7122 7123Trusted Platform Module Library 7124 7125return TPM_RC_HIERARCHY + RC_Duplicate_newParentHandle; 7126} 7127if(in->symmetricAlg.algorithm == TPM_ALG_NULL) 7128{ 7129// if algorithm is TPM_ALG_NULL, input key size must be 0 7130if(in->encryptionKeyIn.t.size != 0) 7131return TPM_RC_SIZE + RC_Duplicate_encryptionKeyIn; 7132} 7133else 7134{ 7135// Get inner wrap key size 7136innerKeySize = in->symmetricAlg.keyBits.sym; 7137// If provided the input symmetric key must match the size of the algorithm 7138if(in->encryptionKeyIn.t.size != 0 7139&& in->encryptionKeyIn.t.size != (innerKeySize + 7) / 8) 7140return TPM_RC_SIZE + RC_Duplicate_encryptionKeyIn; 7141} 7142// Command Output 7143if(in->newParentHandle != TPM_RH_NULL) 7144{ 7145// Make encrypt key and its associated secret structure. A TPM_RC_KEY 7146// error may be returned at this point 7147out->outSymSeed.t.size = sizeof(out->outSymSeed.t.secret); 7148result = CryptSecretEncrypt(in->newParentHandle, 7149"DUPLICATE", &data, &out->outSymSeed); 7150pAssert(result != TPM_RC_VALUE); 7151if(result != TPM_RC_SUCCESS) 7152return result; 7153} 7154else 7155{ 7156// Do not apply outer wrapper 7157data.t.size = 0; 7158out->outSymSeed.t.size = 0; 7159} 7160// Copy sensitive area 7161sensitive = object->sensitive; 7162// Prepare output private data from sensitive 7163SensitiveToDuplicate(&sensitive, &object->name, in->newParentHandle, 7164object->publicArea.nameAlg, (TPM2B_SEED *) &data, 7165&in->symmetricAlg, &in->encryptionKeyIn, 7166&out->duplicate); 7167out->encryptionKeyOut = in->encryptionKeyIn; 7168return TPM_RC_SUCCESS; 7169} 7170 7171Page 80 7172October 31, 2013 7173 7174Published 7175Copyright © TCG 2006-2013 7176 7177Family “2.0” 7178Level 00 Revision 00.99 7179 7180 Trusted Platform Module Library 7181 718215.2 7183 7184Part 3: Commands 7185 7186TPM2_Rewrap 7187 718815.2.1 General Description 7189This command allows the TPM to serve in the role as a Duplication Authority. If proper authorization for 7190use of the oldParent is provided, then an HMAC key and a symmetric key are recovered from inSymSeed 7191and used to integrity check and decrypt inDuplicate. A new protection seed value is generated according 7192to the methods appropriate for newParent and the blob is re-encrypted and a new integrity value is 7193computed. The re-encrypted blob is returned in outDuplicate and the symmetric key returned in 7194outSymKey. 7195In the rewrap process, L is “DUPLICATE” (see “Terms and Definitions” in Part 1). 7196If inSymSeed has a zero length, then oldParent is required to be TPM_RH_NULL and no decryption of 7197inDuplicate takes place. 7198If newParent is TPM_RH_NULL, then no encryption is performed on outDuplicate. outSymSeed will have 7199a zero length. See Part 2 encryptedDuplication. 7200 7201Family “2.0” 7202Level 00 Revision 00.99 7203 7204Published 7205Copyright © TCG 2006-2013 7206 7207Page 81 7208October 31, 2013 7209 7210 Part 3: Commands 7211 7212Trusted Platform Module Library 7213 721415.2.2 Command and Response 7215Table 37 — TPM2_Rewrap Command 7216Type 7217 7218Name 7219 7220TPMI_ST_COMMAND_TAG 7221 7222tag 7223 7224UINT32 7225 7226commandSize 7227 7228TPM_CC 7229 7230commandCode 7231 7232TPM_CC_Rewrap 7233 7234TPMI_DH_OBJECT+ 7235 7236@oldParent 7237 7238parent of object 7239Auth Index: 1 7240Auth Role: User 7241 7242TPMI_DH_OBJECT+ 7243 7244newParent 7245 7246new parent of the object 7247Auth Index: None 7248 7249TPM2B_PRIVATE 7250 7251inDuplicate 7252 7253an object encrypted using symmetric key derived from 7254inSymSeed 7255 7256TPM2B_NAME 7257 7258name 7259 7260the Name of the object being rewrapped 7261 7262TPM2B_ENCRYPTED_SECRET inSymSeed 7263 7264Description 7265 7266seed for symmetric key 7267needs oldParent private key to recover the seed and 7268generate the symmetric key 7269 7270Table 38 — TPM2_Rewrap Response 7271Type 7272 7273Name 7274 7275Description 7276 7277TPM_ST 7278 7279tag 7280 7281see clause 8 7282 7283UINT32 7284 7285responseSize 7286 7287TPM_RC 7288 7289responseCode 7290 7291TPM2B_PRIVATE 7292 7293outDuplicate 7294 7295TPM2B_ENCRYPTED_SECRET outSymSeed 7296 7297Page 82 7298October 31, 2013 7299 7300an object encrypted using symmetric key derived from 7301outSymSeed 7302seed for a symmetric key protected by newParent 7303asymmetric key 7304 7305Published 7306Copyright © TCG 2006-2013 7307 7308Family “2.0” 7309Level 00 Revision 00.99 7310 7311 Trusted Platform Module Library 7312 7313Part 3: Commands 7314 731515.2.3 Detailed Actions 73161 73172 73183 7319 7320#include "InternalRoutines.h" 7321#include "Rewrap_fp.h" 7322#include "Object_spt_fp.h" 7323Error Returns 7324TPM_RC_ATTRIBUTES 7325 7326newParent is not a decryption key 7327 7328TPM_RC_HANDLE 7329 7330oldParent does not consistent with inSymSeed 7331 7332TPM_RC_INTEGRITY 7333 7334the integrity check of inDuplicate failed 7335 7336TPM_RC_KEY 7337 7338for an ECC key, the public key is not on the curve of the curve ID 7339 7340TPM_RC_KEY_SIZE 7341 7342the decrypted input symmetric key size does not matches the 7343symmetric algorithm key size of oldParent 7344 7345TPM_RC_TYPE 7346 7347oldParent is not a storage key, or 'newParent is not a storage key 7348 7349TPM_RC_VALUE 7350 7351for an 'oldParent; RSA key, the data to be decrypted is greater than 7352the public exponent 7353 7354Unmarshal errors 7355 73564 73575 73586 73597 73608 73619 736210 736311 736412 736513 736614 736715 736816 736917 737018 737119 737220 737321 737422 737523 737624 737725 737826 737927 738028 738129 738230 738331 738432 738533 738634 738735 738836 738937 739038 739139 7392 7393Meaning 7394 7395errors during unmarshaling the input encrypted buffer to a ECC public 7396key, or unmarshal the private buffer to sensitive 7397 7398TPM_RC 7399TPM2_Rewrap( 7400Rewrap_In 7401Rewrap_Out 7402 7403*in, 7404*out 7405 7406// IN: input parameter list 7407// OUT: output parameter list 7408 7409TPM_RC 7410OBJECT 7411TPM2B_DATA 7412UINT16 7413TPM2B_PRIVATE 7414 7415result = TPM_RC_SUCCESS; 7416*oldParent; 7417data; 7418// symmetric key 7419hashSize = 0; 7420privateBlob; 7421// A temporary private blob 7422// to transit between old 7423// and new wrappers 7424 7425) 7426{ 7427 7428// Input Validation 7429if((in->inSymSeed.t.size == 0 && in->oldParent != TPM_RH_NULL) 7430|| (in->inSymSeed.t.size != 0 && in->oldParent == TPM_RH_NULL)) 7431return TPM_RC_HANDLE + RC_Rewrap_oldParent; 7432if(in->oldParent != TPM_RH_NULL) 7433{ 7434// Get old parent pointer 7435oldParent = ObjectGet(in->oldParent); 7436// old parent key must be a storage object 7437if(!ObjectIsStorage(in->oldParent)) 7438return TPM_RC_TYPE + RC_Rewrap_oldParent; 7439// Decrypt input secret data via asymmetric decryption. A 7440// TPM_RC_VALUE, TPM_RC_KEY or unmarshal errors may be returned at this 7441// point 7442result = CryptSecretDecrypt(in->oldParent, NULL, 7443"DUPLICATE", &in->inSymSeed, &data); 7444if(result != TPM_RC_SUCCESS) 7445return TPM_RC_VALUE + RC_Rewrap_inSymSeed; 7446 7447Family “2.0” 7448Level 00 Revision 00.99 7449 7450Published 7451Copyright © TCG 2006-2013 7452 7453Page 83 7454October 31, 2013 7455 7456 Part 3: Commands 745740 745841 745942 746043 746144 746245 746346 746447 746548 746649 746750 746851 746952 747053 747154 747255 747356 747457 747558 747659 747760 747861 747962 748063 748164 748265 748366 748467 748568 748669 748770 748871 748972 749073 749174 749275 749376 749477 749578 749679 749780 749881 749982 750083 750184 750285 750386 750487 750588 750689 750790 750891 750992 751093 751194 751295 751396 751497 751598 751699 7517100 7518101 7519102 7520103 7521 7522Trusted Platform Module Library 7523 7524// Unwrap Outer 7525result = UnwrapOuter(in->oldParent, &in->name, 7526oldParent->publicArea.nameAlg, (TPM2B_SEED *) &data, 7527FALSE, 7528in->inDuplicate.t.size, in->inDuplicate.t.buffer); 7529if(result != TPM_RC_SUCCESS) 7530return RcSafeAddToResult(result, RC_Rewrap_inDuplicate); 7531// Copy unwrapped data to temporary variable, remove the integrity field 7532hashSize = sizeof(UINT16) + 7533CryptGetHashDigestSize(oldParent->publicArea.nameAlg); 7534privateBlob.t.size = in->inDuplicate.t.size - hashSize; 7535MemoryCopy(privateBlob.t.buffer, in->inDuplicate.t.buffer + hashSize, 7536privateBlob.t.size, sizeof(privateBlob.t.buffer)); 7537} 7538else 7539{ 7540// No outer wrap from input blob. 7541privateBlob = in->inDuplicate; 7542} 7543 7544Direct copy. 7545 7546if(in->newParent != TPM_RH_NULL) 7547{ 7548OBJECT 7549*newParent; 7550newParent = ObjectGet(in->newParent); 7551// New parent must be a storage object 7552if(!ObjectIsStorage(in->newParent)) 7553return TPM_RC_TYPE + RC_Rewrap_newParent; 7554// Make new encrypt key and its associated secret structure. A 7555// TPM_RC_VALUE error may be returned at this point if RSA algorithm is 7556// enabled in TPM 7557out->outSymSeed.t.size = sizeof(out->outSymSeed.t.secret); 7558result = CryptSecretEncrypt(in->newParent, 7559"DUPLICATE", &data, &out->outSymSeed); 7560if(result != TPM_RC_SUCCESS) return result; 7561// Command output 7562// Copy temporary variable to output, reserve the space for integrity 7563hashSize = sizeof(UINT16) + 7564CryptGetHashDigestSize(newParent->publicArea.nameAlg); 7565out->outDuplicate.t.size = privateBlob.t.size; 7566MemoryCopy(out->outDuplicate.t.buffer + hashSize, privateBlob.t.buffer, 7567privateBlob.t.size, sizeof(out->outDuplicate.t.buffer)); 7568// Produce outer wrapper for output 7569out->outDuplicate.t.size = ProduceOuterWrap(in->newParent, &in->name, 7570newParent->publicArea.nameAlg, 7571(TPM2B_SEED *) &data, 7572FALSE, 7573out->outDuplicate.t.size, 7574out->outDuplicate.t.buffer); 7575} 7576else // New parent is a null key so there is no seed 7577{ 7578out->outSymSeed.t.size = 0; 7579// Copy privateBlob directly 7580out->outDuplicate = privateBlob; 7581} 7582 7583Page 84 7584October 31, 2013 7585 7586Published 7587Copyright © TCG 2006-2013 7588 7589Family “2.0” 7590Level 00 Revision 00.99 7591 7592 Trusted Platform Module Library 7593104 7594105 7595 7596Part 3: Commands 7597 7598return TPM_RC_SUCCESS; 7599} 7600 7601Family “2.0” 7602Level 00 Revision 00.99 7603 7604Published 7605Copyright © TCG 2006-2013 7606 7607Page 85 7608October 31, 2013 7609 7610 Part 3: Commands 7611 761215.3 7613 7614Trusted Platform Module Library 7615 7616TPM2_Import 7617 761815.3.1 General Description 7619This command allows an object to be encrypted using the symmetric encryption values of a Storage Key. 7620After encryption, the object may be loaded and used in the new hierarchy. The imported object (duplicate) 7621may be singly encrypted, multiply encrypted, or unencrypted. 7622If fixedTPM or fixedParent is SET in objectPublic, the TPM shall return TPM_RC_ATTRIBUTES. 7623If encryptedDuplication is SET in the object referenced by parentHandle, then encryptedDuplication shall 7624be set in objectPublic (TPM_RC_ATTRIBUTES). However, see Note 2. 7625Recovery of the sensitive data of the object occurs in the TPM in a three-step process in the following 7626order: 7627 7628 7629If present, the outer layer of symmetric encryption is removed. If inSymSeed has a non-zero size, the 7630asymmetric parameters and private key of parentHandle are used to recover the seed used in the 7631creation of the HMAC key and encryption keys used to protect the duplication blob. When recovering 7632the seed, L is “DUPLICATE”. 7633NOTE 1 7634 7635If the encryptedDuplication attribute of the object 7636TPM_RC_ATTRIBUTES if inSymSeed is an empty buffer. 7637 7638is 7639 7640SET, 7641 7642the 7643 7644TPM 7645 7646shall 7647 7648return 7649 7650 7651 7652If present, the inner layer of symmetric encryption is removed. If encryptionKey and symmetricAlg are 7653provided, they are used to decrypt duplication. 7654 7655 7656 7657If present, the integrity value of the blob is checked. The presence of the integrity value is indicated 7658by a non-zero value for duplicate.data.integrity.size. The integrity of the private area is validated using 7659the Name of objectPublic in the integrity HMAC computation. If either the outer layer or inner layer of 7660encryption is performed, then the integrity value shall be present. 7661 7662If the inner or outer wrapper is present, then a valid integrity value shall be present or the TPM shall 7663return TPM_RC_INTEGRITY. 7664NOTE 2 7665 7666It is not necessary to validate that the sensitive area data is cryptographically bound to the public 7667area other than that the Name of the public area is included in the HMAC. However, if the binding is 7668not validated by this command, the binding must be checked each time the object is loaded. For an 7669object that is imported under a parent with fixedTPM SET, binding need only be checked at import. If 7670the parent has fixedTPM CLEAR, then the binding needs to be checked each time the object is 7671loaded, or before the TPM performs an operation for which the binding affects the outcome of the 7672operation (for example, TPM2_PolicySigned() or TPM2_Certify()). 7673Similarly, if the new parent's fixedTPM is set, the encryptedDuplication state need only be checked 7674at import. 7675If the new parent is not fixedTPM, then that object will be loadable on any TPM (including SW 7676versions) on which the new parent exists. This means that, each time an object is loaded under a 7677parent that is not fixedTPM, it is necessary to validate all of the properties of that object. If the 7678parent is fixedTPM, then the new private blob is integrity protected by the TPM that “owns” the 7679parent. So, it is sufficient to validate the object’s properties (attribute and public -private binding) on 7680import and not again. 7681 7682Before duplicate.buffer is decrypted using the symmetric key of the parent, the integrity value shall be 7683checked before the sensitive area is used, or unmarshaled. 7684After integrity checks and decryption, the TPM will create a new symmetrically encrypted private area 7685using the encryption key of the parent. 7686NOTE 3 7687 7688Checking the integrity before the data is used prevents attacks on the sensitive area by fuzzing the 7689data and looking at the differences in the response codes. 7690 7691Page 86 7692October 31, 2013 7693 7694Published 7695Copyright © TCG 2006-2013 7696 7697Family “2.0” 7698Level 00 Revision 00.99 7699 7700 Trusted Platform Module Library 7701NOTE 4 7702 7703Part 3: Commands 7704 7705The symmetric re-encryption is the normal integrity generation and symmetric encryption applied to 7706a child object. 7707 7708Family “2.0” 7709Level 00 Revision 00.99 7710 7711Published 7712Copyright © TCG 2006-2013 7713 7714Page 87 7715October 31, 2013 7716 7717 Part 3: Commands 7718 7719Trusted Platform Module Library 7720 772115.3.2 Command and Response 7722Table 39 — TPM2_Import Command 7723Type 7724 7725Name 7726 7727TPMI_ST_COMMAND_TAG 7728 7729tag 7730 7731UINT32 7732 7733commandSize 7734 7735TPM_CC 7736 7737commandCode 7738 7739TPM_CC_Import 7740 7741TPMI_DH_OBJECT 7742 7743@parentHandle 7744 7745the handle of the new parent for the object 7746Auth Index: 1 7747Auth Role: USER 7748 7749encryptionKey 7750 7751the optional symmetric encryption key used as the inner 7752wrapper for duplicate 7753If symmetricAlg is TPM_ALG_NULL, then this 7754parameter shall be the Empty Buffer. 7755 7756TPM2B_DATA 7757 7758TPM2B_PUBLIC 7759 7760objectPublic 7761 7762Description 7763 7764the public area of the object to be imported 7765This is provided so that the integrity value for duplicate 7766and the object attributes can be checked. 7767NOTE 7768 7769TPM2B_PRIVATE 7770 7771duplicate 7772 7773Even if the integrity value of the object is not 7774checked on input, the object Name is required to 7775create the integrity value for the imported object. 7776 7777the symmetrically encrypted duplicate object that may 7778contain an inner symmetric wrapper 7779 7780TPM2B_ENCRYPTED_SECRET inSymSeed 7781 7782symmetric key used to encrypt duplicate 7783inSymSeed is encrypted/encoded using the algorithms 7784of newParent. 7785 7786TPMT_SYM_DEF_OBJECT+ 7787 7788definition for the symmetric algorithm to use for the inner 7789wrapper 7790If this algorithm is TPM_ALG_NULL, no inner wrapper is 7791present and encryptionKey shall be the Empty Buffer. 7792 7793symmetricAlg 7794 7795Table 40 — TPM2_Import Response 7796Type 7797 7798Name 7799 7800Description 7801 7802TPM_ST 7803 7804tag 7805 7806see clause 8 7807 7808UINT32 7809 7810responseSize 7811 7812TPM_RC 7813 7814responseCode 7815 7816TPM2B_PRIVATE 7817 7818outPrivate 7819 7820Page 88 7821October 31, 2013 7822 7823the sensitive area encrypted with the symmetric key of 7824parentHandle 7825 7826Published 7827Copyright © TCG 2006-2013 7828 7829Family “2.0” 7830Level 00 Revision 00.99 7831 7832 Trusted Platform Module Library 7833 7834Part 3: Commands 7835 783615.3.3 Detailed Actions 78371 78382 78393 7840 7841#include "InternalRoutines.h" 7842#include "Import_fp.h" 7843#include "Object_spt_fp.h" 7844Error Returns 7845 7846Meaning 7847 7848TPM_RC_ASYMMETRIC 7849 7850non-duplicable storage key represented by objectPublic and its 7851parent referenced by parentHandle have different public params 7852 7853TPM_RC_ATTRIBUTES 7854 7855attributes FixedTPM and fixedParent of objectPublic are not both 7856CLEAR; or inSymSeed is nonempty and parentHandle does not 7857reference a decryption key; or objectPublic and parentHandle have 7858incompatible or inconsistent attributes 7859 7860TPM_RC_BINDING 7861 7862duplicate and objectPublic are not cryptographically bound 7863 7864TPM_RC_ECC_POINT 7865 7866inSymSeed is nonempty and ECC point in inSymSeed is not on the 7867curve 7868 7869TPM_RC_HASH 7870 7871non-duplicable storage key represented by objectPublic and its 7872parent referenced by parentHandle have different name algorithm 7873 7874TPM_RC_INSUFFICIENT 7875 7876inSymSeed is nonempty and failed to retrieve ECC point from the 7877secret; or unmarshaling sensitive value from duplicate failed the 7878result of inSymSeed decryption 7879 7880TPM_RC_INTEGRITY 7881 7882duplicate integrity is broken 7883 7884TPM_RC_KDF 7885 7886objectPublic representing decrypting keyed hash object specifies 7887invalid KDF 7888 7889TPM_RC_KEY 7890 7891inconsistent parameters of objectPublic; or inSymSeed is nonempty 7892and parentHandle does not reference a key of supported type; or 7893invalid key size in objectPublic representing an asymmetric key 7894 7895TPM_RC_NO_RESULT 7896 7897inSymSeed is nonempty and multiplication resulted in ECC point at 7898infinity 7899 7900TPM_RC_OBJECT_MEMORY 7901 7902no available object slot 7903 7904TPM_RC_SCHEME 7905 7906inconsistent attributes decrypt, sign, restricted and key's scheme ID 7907in objectPublic; or hash algorithm is inconsistent with the scheme ID 7908for keyed hash object 7909 7910TPM_RC_SIZE 7911 7912authPolicy size does not match digest size of the name algorithm in 7913objectPublic; or symmetricAlg and encryptionKey have different 7914sizes; or inSymSeed is nonempty and it is not of the same size as 7915RSA key referenced by parentHandle; or unmarshaling sensitive 7916value from duplicate failed 7917 7918TPM_RC_SYMMETRIC 7919 7920objectPublic is either a storage key with no symmetric algorithm or a 7921non-storage key with symmetric algorithm different from 7922TPM_ALG_NULL 7923 7924TPM_RC_TYPE 7925 7926unsupported type of objectPublic; or non-duplicable storage key 7927represented by objectPublic and its parent referenced by 7928parentHandle are of different types; or parentHandle is not a storage 7929key; or only the public portion of parentHandle is loaded; or 7930objectPublic and duplicate are of different types 7931 7932TPM_RC_VALUE 7933 7934nonempty inSymSeed and its numeric value is greater than the 7935modulus of the key referenced by parentHandle or inSymSeed is 7936larger than the size of the digest produced by the name algorithm of 7937the symmetric key referenced by parentHandle 7938 7939Family “2.0” 7940Level 00 Revision 00.99 7941 7942Published 7943Copyright © TCG 2006-2013 7944 7945Page 89 7946October 31, 2013 7947 7948 Part 3: Commands 79494 79505 79516 79527 79538 79549 795510 795611 795712 795813 795914 796015 796116 796217 796318 796419 796520 796621 796722 796823 796924 797025 797126 797227 797328 797429 797530 797631 797732 797833 797934 798035 798136 798237 798338 798439 798540 798641 798742 798843 798944 799045 799146 799247 799348 799449 799550 799651 799752 799853 799954 800055 800156 800257 800358 800459 800560 800661 800762 800863 800964 801065 801166 801267 8013 8014Trusted Platform Module Library 8015 8016TPM_RC 8017TPM2_Import( 8018Import_In 8019Import_Out 8020 8021*in, 8022*out 8023 8024// IN: input parameter list 8025// OUT: output parameter list 8026 8027) 8028{ 8029TPM_RC 8030OBJECT 8031TPM2B_DATA 8032TPMT_SENSITIVE 8033TPM2B_NAME 8034 8035result = TPM_RC_SUCCESS; 8036*parentObject; 8037data; 8038// symmetric key 8039sensitive; 8040name; 8041 8042UINT16 8043 8044innerKeySize = 0; 8045 8046// encrypt key size for inner 8047// wrapper 8048 8049// Input Validation 8050// FixedTPM and fixedParent must be CLEAR 8051if( 8052in->objectPublic.t.publicArea.objectAttributes.fixedTPM == SET 8053|| in->objectPublic.t.publicArea.objectAttributes.fixedParent == SET) 8054return TPM_RC_ATTRIBUTES + RC_Import_objectPublic; 8055// Get parent pointer 8056parentObject = ObjectGet(in->parentHandle); 8057if(!AreAttributesForParent(parentObject)) 8058return TPM_RC_TYPE + RC_Import_parentHandle; 8059if(in->symmetricAlg.algorithm != TPM_ALG_NULL) 8060{ 8061// Get inner wrap key size 8062innerKeySize = in->symmetricAlg.keyBits.sym; 8063// Input symmetric key must match the size of algorithm. 8064if(in->encryptionKey.t.size != (innerKeySize + 7) / 8) 8065return TPM_RC_SIZE + RC_Import_encryptionKey; 8066} 8067else 8068{ 8069// If input symmetric algorithm is NULL, input symmetric key size must 8070// be 0 as well 8071if(in->encryptionKey.t.size != 0) 8072return TPM_RC_SIZE + RC_Import_encryptionKey; 8073} 8074// See if there is an outer wrapper 8075if(in->inSymSeed.t.size != 0) 8076{ 8077// Decrypt input secret data via asymmetric decryption. TPM_RC_ATTRIBUTES, 8078// TPM_RC_ECC_POINT, TPM_RC_INSUFFICIENT, TPM_RC_KEY, TPM_RC_NO_RESULT, 8079// TPM_RC_SIZE, TPM_RC_VALUE may be returned at this point 8080result = CryptSecretDecrypt(in->parentHandle, NULL, "DUPLICATE", 8081&in->inSymSeed, &data); 8082pAssert(result != TPM_RC_BINDING); 8083if(result != TPM_RC_SUCCESS) 8084return TPM_RC_VALUE + RC_Import_inSymSeed; 8085} 8086else 8087{ 8088data.t.size = 0; 8089} 8090// Compute name of object 8091ObjectComputeName(&(in->objectPublic.t.publicArea), &name); 8092 8093Page 90 8094October 31, 2013 8095 8096Published 8097Copyright © TCG 2006-2013 8098 8099Family “2.0” 8100Level 00 Revision 00.99 8101 8102 Trusted Platform Module Library 810368 810469 810570 810671 810772 810873 810974 811075 811176 811277 811378 811479 811580 811681 811782 811883 811984 812085 812186 812287 812388 812489 812590 812691 812792 812893 812994 813095 813196 813297 813398 813499 8135100 8136101 8137102 8138103 8139104 8140105 8141106 8142107 8143108 8144109 8145110 8146111 8147112 8148113 8149114 8150 8151Part 3: Commands 8152 8153// Retrieve sensitive from private. 8154// TPM_RC_INSUFFICIENT, TPM_RC_INTEGRITY, TPM_RC_SIZE may be returned here. 8155result = DuplicateToSensitive(&in->duplicate, &name, in->parentHandle, 8156in->objectPublic.t.publicArea.nameAlg, 8157(TPM2B_SEED *) &data, &in->symmetricAlg, 8158&in->encryptionKey, &sensitive); 8159if(result != TPM_RC_SUCCESS) 8160return RcSafeAddToResult(result, RC_Import_duplicate); 8161// If the parent of this object has fixedTPM SET, then fully validate this 8162// object so that validation can be skipped when it is loaded 8163if(parentObject->publicArea.objectAttributes.fixedTPM == SET) 8164{ 8165TPM_HANDLE 8166objectHandle; 8167// Perform self check on input public area. A TPM_RC_SIZE, TPM_RC_SCHEME, 8168// TPM_RC_VALUE, TPM_RC_SYMMETRIC, TPM_RC_TYPE, TPM_RC_HASH, 8169// TPM_RC_ASYMMETRIC, TPM_RC_ATTRIBUTES or TPM_RC_KDF error may be returned 8170// at this point 8171result = PublicAttributesValidation(TRUE, in->parentHandle, 8172&in->objectPublic.t.publicArea); 8173if(result != TPM_RC_SUCCESS) 8174return RcSafeAddToResult(result, RC_Import_objectPublic); 8175// Create internal object. A TPM_RC_KEY_SIZE, TPM_RC_KEY or 8176// TPM_RC_OBJECT_MEMORY error may be returned at this point 8177result = ObjectLoad(TPM_RH_NULL, &in->objectPublic.t.publicArea, 8178&sensitive, NULL, in->parentHandle, FALSE, 8179&objectHandle); 8180if(result != TPM_RC_SUCCESS) 8181return result; 8182// Don't need the object, just needed the checks to be performed so 8183// flush the object 8184ObjectFlush(objectHandle); 8185} 8186// Command output 8187// Prepare output private data from sensitive 8188SensitiveToPrivate(&sensitive, &name, in->parentHandle, 8189in->objectPublic.t.publicArea.nameAlg, 8190&out->outPrivate); 8191return TPM_RC_SUCCESS; 8192} 8193 8194Family “2.0” 8195Level 00 Revision 00.99 8196 8197Published 8198Copyright © TCG 2006-2013 8199 8200Page 91 8201October 31, 2013 8202 8203 Part 3: Commands 8204 820516 8206 8207Trusted Platform Module Library 8208 8209Asymmetric Primitives 8210 821116.1 8212 8213Introduction 8214 8215The commands in this clause provide low-level primitives for access to the asymmetric algorithms 8216implemented in the TPM. Many of these commands are only allowed if the asymmetric key is an 8217unrestricted key. 821816.2 8219 8220TPM2_RSA_Encrypt 8221 822216.2.1 General Description 8223This command performs RSA encryption using the indicated padding scheme according to PKCS#1v2.1 8224(PKCS#1). If the scheme of keyHandle is TPM_ALG_NULL, then the caller may use inScheme to specify 8225the padding scheme. If scheme of keyHandle is not TPM_ALG_NULL, then inScheme shall either be 8226TPM_ALG_NULL or be the same as scheme (TPM_RC_SCHEME). 8227The key referenced by keyHandle is required to be an RSA key (TPM_RC_KEY) with the decrypt attribute 8228SET (TPM_RC_ATTRIBUTES). 8229NOTE 8230 8231Requiring that the decrypt attribute be set allows the TPM to ensure that the scheme selection is 8232done with the presumption that the scheme of the key is a decryption scheme selection. It is 8233understood that this command will operate on a key with only the publi c part loaded so the caller 8234may modify any key in any desired way. So, this constraint only serves to simplify the TPM logic. 8235 8236The three types of allowed padding are: 82371) TPM_ALG_OAEP – Data is OAEP padded as described in 7.1 of PKCS#1 v2.1. The only 8238supported mask generation is MGF1. 82392) TPM_ALG_RSAES – Data is padded as described in 7.2 of PKCS#1 v2.1. 82403) TPM_ALG_NULL – Data is not padded by the TPM and the TPM will treat message as an 8241unsigned integer and perform a modular exponentiation of message using the public 8242exponent of the key referenced by keyHandle. This scheme is only used if both the scheme 8243in the key referenced by keyHandle is TPM_ALG_NULL, and the inScheme parameter of the 8244command is TPM_ALG_NULL. The input value cannot be larger than the public modulus of 8245the key referenced by keyHandle. 8246Table 41 — Padding Scheme Selection 8247keyHandle→scheme 8248 8249OAEP 8250RSAES 8251 8252TPM_ALG_RSAES 8253 8254RSAES 8255error (TPM_RC_SCHEME) 8256 8257TPM_ALG_NULL 8258 8259OAEP 8260 8261TPM_ALG_RSAES 8262 8263error (TPM_RC_SCHEME) 8264 8265TPM_AGL_OAEP 8266 8267October 31, 2013 8268 8269RSAES 8270 8271TPM_ALG_OAEP 8272 8273Page 92 8274 8275TPM_ALG_RSAES 8276 8277TPM_ALG_NULL 8278 8279TPM_ALG_OAEP 8280 8281none 8282 8283TPM_ALG_OAEP 8284 8285TPM_ALG_RSAES 8286 8287padding scheme used 8288 8289TPM_ALG_NULL 8290TPM_ALG_NULL 8291 8292inScheme 8293 8294OAEP 8295 8296Published 8297Copyright © TCG 2006-2013 8298 8299Family “2.0” 8300Level 00 Revision 00.99 8301 8302 Trusted Platform Module Library 8303 8304Part 3: Commands 8305 8306After padding, the data is RSAEP encrypted according to 5.1.1 of PKCS#1v2.1. 8307NOTE 1 8308 8309It is required that decrypt be SET so that the commands that load a key can validate that the 8310scheme is consistent rather than have that deferred until the key is used. 8311 8312NOTE 2 8313 8314If it is desired to use a key that had restricted SET, the caller may CLEAR restricted and load the 8315public part of the key and use that unrestricted version of the key for encryption. 8316 8317If inScheme is used, and the scheme requires a hash algorithm it may not be TPM_ALG_NULL. 8318NOTE 3 8319 8320Because only the public portion of the key needs to be loaded for this command, the caller can 8321manipulate the attributes of the key in any way desired. As a result , the TPM shall not check the 8322consistency of the attributes. The only property checking is that the key is an RSA key and that the 8323padding scheme is supported. 8324 8325The message parameter is limited in size by the padding scheme according to the following table: 8326Table 42 — Message Size Limits Based on Padding 8327Scheme 8328 8329Maximum Message Length 8330(mLen) in Octets 8331 8332TPM_ALG_OAEP 8333 8334mLen k – 2hLen – 2 8335 8336TPM_ALG_RSAES 8337 8338mLen k – 11 8339 8340TPM_ALG_NULL 8341 8342mLen k 8343 8344Comments 8345 8346The numeric value of the message must be 8347less than the numeric value of the public 8348modulus (n). 8349 8350NOTES 83511) 83522) 8353 8354k ≔ the number of byes in the public modulus 8355hLen ≔ the number of octets in the digest produced by the hash algorithm used in the process 8356 8357The label parameter is optional. If provided (label.size != 0) then the TPM shall return TPM_RC_VALUE if 8358the last octet in label is not zero. If a zero octet occurs before label.buffer[label.size-1], the TPM shall 8359truncate the label at that point. The terminating octet of zero is included in the label used in the padding 8360scheme. 8361NOTE 4 8362 8363If the scheme does not use a label, the TPM will still verify that label is properly formatted if label is 8364present. 8365 8366The function returns padded and encrypted value outData. 8367The message parameter in the command may be encrypted using parameter encryption. 8368NOTE 5 8369 8370Only the public area of keyHandle is required to be loaded. A public key may be loaded with any 8371desired scheme. If the scheme is to be changed, a different public area must be loaded. 8372 8373Family “2.0” 8374Level 00 Revision 00.99 8375 8376Published 8377Copyright © TCG 2006-2013 8378 8379Page 93 8380October 31, 2013 8381 8382 Part 3: Commands 8383 8384Trusted Platform Module Library 8385 838616.2.2 Command and Response 8387Table 43 — TPM2_RSA_Encrypt Command 8388Type 8389 8390Name 8391 8392Description 8393 8394TPMI_ST_COMMAND_TAG 8395 8396tag 8397 8398UINT32 8399 8400commandSize 8401 8402TPM_CC 8403 8404commandCode 8405 8406TPM_CC_RSA_Encrypt 8407 8408TPMI_DH_OBJECT 8409 8410keyHandle 8411 8412reference to public portion of RSA key to use for 8413encryption 8414Auth Index: None 8415message to be encrypted 8416 8417TPM2B_PUBLIC_KEY_RSA 8418 8419message 8420 8421TPMT_RSA_DECRYPT+ 8422 8423inScheme 8424 8425TPM2B_DATA 8426 8427label 8428 8429NOTE 1 8430 8431The data type was chosen because it limits the 8432overall size of the input to no greater than the size 8433of the largest RSA public key. This may be larger 8434than allowed for keyHandle. 8435 8436the padding scheme to use if scheme associated with 8437keyHandle is TPM_ALG_NULL 8438optional label L to be associated with the message 8439Size of the buffer is zero if no label is present 8440NOTE 2 8441 8442See description of label above. 8443 8444Table 44 — TPM2_RSA_Encrypt Response 8445Type 8446 8447Name 8448 8449Description 8450 8451TPM_ST 8452 8453tag 8454 8455see clause 8 8456 8457UINT32 8458 8459responseSize 8460 8461TPM_RC 8462 8463responseCode 8464 8465TPM2B_PUBLIC_KEY_RSA 8466 8467outData 8468 8469Page 94 8470October 31, 2013 8471 8472encrypted output 8473 8474Published 8475Copyright © TCG 2006-2013 8476 8477Family “2.0” 8478Level 00 Revision 00.99 8479 8480 Trusted Platform Module Library 8481 8482Part 3: Commands 8483 848416.2.3 Detailed Actions 84851 84862 84873 8488 8489#include "InternalRoutines.h" 8490#include "RSA_Encrypt_fp.h" 8491#ifdef TPM_ALG_RSA 8492Error Returns 8493TPM_RC_ATTRIBUTES 8494 8495decrypt attribute is not SET in key referenced by keyHandle 8496 8497TPM_RC_KEY 8498 8499keyHandle does not reference an RSA key 8500 8501TPM_RC_SCHEME 8502 8503incorrect input scheme, or the chosen scheme is not a valid RSA 8504decrypt scheme 8505 8506TPM_RC_VALUE 8507 85084 85095 85106 85117 85128 85139 851410 851511 851612 851713 851814 851915 852016 852117 852218 852319 852420 852521 852622 852723 852824 852925 853026 853127 853228 853329 853430 853531 853632 853733 853834 853935 854036 854137 854238 854339 854440 854541 854642 854743 854844 854945 855046 8551 8552Meaning 8553 8554the numeric value of message is greater than the public modulus of 8555the key referenced by keyHandle, or label is not a null-terminated 8556string 8557 8558TPM_RC 8559TPM2_RSA_Encrypt( 8560RSA_Encrypt_In 8561RSA_Encrypt_Out 8562 8563*in, 8564*out 8565 8566// IN: input parameter list 8567// OUT: output parameter list 8568 8569TPM_RC 8570OBJECT 8571TPMT_RSA_DECRYPT 8572char 8573 8574result; 8575*rsaKey; 8576*scheme; 8577*label = NULL; 8578 8579) 8580{ 8581 8582// Input Validation 8583rsaKey = ObjectGet(in->keyHandle); 8584// selected key must be an RSA key 8585if(rsaKey->publicArea.type != TPM_ALG_RSA) 8586return TPM_RC_KEY + RC_RSA_Encrypt_keyHandle; 8587// selected key must have the decryption attribute 8588if(rsaKey->publicArea.objectAttributes.decrypt != SET) 8589return TPM_RC_ATTRIBUTES + RC_RSA_Encrypt_keyHandle; 8590// Is there a label? 8591if(in->label.t.size > 0) 8592{ 8593// label is present, so make sure that is it NULL-terminated 8594if(in->label.t.buffer[in->label.t.size - 1] != 0) 8595return TPM_RC_VALUE + RC_RSA_Encrypt_label; 8596label = (char *)in->label.t.buffer; 8597} 8598// Command Output 8599// Select a scheme for encryption 8600scheme = CryptSelectRSAScheme(in->keyHandle, &in->inScheme); 8601if(scheme == NULL) 8602return TPM_RC_SCHEME + RC_RSA_Encrypt_inScheme; 8603// Encryption. TPM_RC_VALUE, or TPM_RC_SCHEME errors my be returned buy 8604// CryptEncyptRSA. Note: It can also return TPM_RC_ATTRIBUTES if the key does 8605// not have the decrypt attribute but that was checked above. 8606out->outData.t.size = sizeof(out->outData.t.buffer); 8607 8608Family “2.0” 8609Level 00 Revision 00.99 8610 8611Published 8612Copyright © TCG 2006-2013 8613 8614Page 95 8615October 31, 2013 8616 8617 Part 3: Commands 861847 861948 862049 862150 862251 862352 8624 8625Trusted Platform Module Library 8626 8627result = CryptEncryptRSA(&out->outData.t.size, out->outData.t.buffer, rsaKey, 8628scheme, in->message.t.size, in->message.t.buffer, 8629label); 8630return result; 8631} 8632#endif 8633 8634Page 96 8635October 31, 2013 8636 8637Published 8638Copyright © TCG 2006-2013 8639 8640Family “2.0” 8641Level 00 Revision 00.99 8642 8643 Trusted Platform Module Library 8644 864516.3 8646 8647Part 3: Commands 8648 8649TPM2_RSA_Decrypt 8650 865116.3.1 General Description 8652This command performs RSA decryption using the indicated padding scheme according to PKCS#1v2.1 8653(PKCS#1). 8654The scheme selection for this command is the same as for TPM2_RSA_Encrypt() and is shown in Table 865541. 8656The key referenced by keyHandle shall be an RSA key (TPM_RC_KEY) with restricted CLEAR and 8657decrypt SET (TPM_RC_ATTRIBUTES). 8658This command uses the private key of keyHandle for this operation and authorization is required. 8659The TPM will perform a modular exponentiation of ciphertext using the private exponent associated with 8660keyHandle (this is described in PKCS#1v2.1, clause 5.1.2). It will then validate the padding according to 8661the selected scheme. If the padding checks fail, TPM_RC_VALUE is returned. Otherwise, the data is 8662returned with the padding removed. If no padding is used, the returned value is an unsigned integer value 8663that is the result of the modular exponentiation of cipherText using the private exponent of keyHandle. 8664The returned value may include leading octets zeros so that it is the same size as the public modulus. For 8665the other padding schemes, the returned value will be smaller than the public modulus but will contain all 8666the data remaining after padding is removed and this may include leading zeros if the original encrypted 8667value contained leading zeros.. 8668If a label is used in the padding process of the scheme, the label parameter is required to be present in 8669the decryption process and label is required to be the same in both cases. The TPM shall verify that the 8670label is consistent and if not it shall return TPM_RC_VALUE. 8671If label is present (label.size != 0), it 8672shall be a NULL-terminated string or the TPM will return TPM_RC_VALUE. 8673NOTE 1 8674 8675The size of label includes the terminating null. 8676 8677The message parameter in the response may be encrypted using parameter encryption. 8678If the decryption scheme does not require a hash function, the hash parameter of inScheme may be set 8679to any valid hash function or TPM_ALG_NULL. 8680If the description scheme does not require a label, the value in label is not used but the size of the label 8681field is checked for consistency with the indicated data type (TPM2B_DATA). That is, the field may not be 8682larger than allowed for a TPM2B_DATA. 8683 8684Family “2.0” 8685Level 00 Revision 00.99 8686 8687Published 8688Copyright © TCG 2006-2013 8689 8690Page 97 8691October 31, 2013 8692 8693 Part 3: Commands 8694 8695Trusted Platform Module Library 8696 869716.3.2 Command and Response 8698Table 45 — TPM2_RSA_Decrypt Command 8699Type 8700 8701Name 8702 8703Description 8704 8705TPMI_ST_COMMAND_TAG 8706 8707tag 8708 8709UINT32 8710 8711commandSize 8712 8713TPM_CC 8714 8715commandCode 8716 8717TPM_CC_RSA_Decrypt 8718 8719TPMI_DH_OBJECT 8720 8721@keyHandle 8722 8723RSA key to use for decryption 8724Auth Index: 1 8725Auth Role: USER 8726 8727TPM2B_PUBLIC_KEY_RSA 8728 8729cipherText 8730 8731NOTE 8732 8733TPMT_RSA_DECRYPT+ 8734 8735inScheme 8736 8737the padding scheme to use if scheme associated with 8738keyHandle is TPM_ALG_NULL 8739 8740TPM2B_DATA 8741 8742label 8743 8744label whose association with the message is to be 8745verified 8746 8747cipher text to be decrypted 8748An encrypted RSA data block is the size of the 8749public modulus. 8750 8751Table 46 — TPM2_RSA_Decrypt Response 8752Type 8753 8754Name 8755 8756Description 8757 8758TPM_ST 8759 8760tag 8761 8762see clause 8 8763 8764UINT32 8765 8766responseSize 8767 8768TPM_RC 8769 8770responseCode 8771 8772TPM2B_PUBLIC_KEY_RSA 8773 8774message 8775 8776Page 98 8777October 31, 2013 8778 8779decrypted output 8780 8781Published 8782Copyright © TCG 2006-2013 8783 8784Family “2.0” 8785Level 00 Revision 00.99 8786 8787 Trusted Platform Module Library 8788 8789Part 3: Commands 8790 879116.3.3 Detailed Actions 87921 87932 87943 8795 8796#include "InternalRoutines.h" 8797#include "RSA_Decrypt_fp.h" 8798#ifdef TPM_ALG_RSA 8799Error Returns 8800TPM_RC_KEY 8801 8802keyHandle does not reference an unrestricted decrypt key 8803 8804TPM_RC_SCHEME 8805 8806incorrect input scheme, or the chosen scheme is not a valid RSA 8807decrypt scheme 8808 8809TPM_RC_SIZE 8810 8811cipherText is not the size of the modulus of key referenced by 8812keyHandle 8813 8814TPM_RC_VALUE 8815 88164 88175 88186 88197 88208 88219 882210 882311 882412 882513 882614 882715 882816 882917 883018 883119 883220 883321 883422 883523 883624 883725 883826 883927 884028 884129 884230 884331 884432 884533 884634 884735 884836 884937 885038 885139 885240 885341 885442 885543 885644 885745 885846 8859 8860Meaning 8861 8862label is not a null terminated string or the value of cipherText is 8863greater that the modulus of keyHandle 8864 8865TPM_RC 8866TPM2_RSA_Decrypt( 8867RSA_Decrypt_In 8868RSA_Decrypt_Out 8869 8870*in, 8871*out 8872 8873// IN: input parameter list 8874// OUT: output parameter list 8875 8876TPM_RC 8877OBJECT 8878TPMT_RSA_DECRYPT 8879char 8880 8881result; 8882*rsaKey; 8883*scheme; 8884*label = NULL; 8885 8886) 8887{ 8888 8889// Input Validation 8890rsaKey = ObjectGet(in->keyHandle); 8891// The selected key must be an RSA key 8892if(rsaKey->publicArea.type != TPM_ALG_RSA) 8893return TPM_RC_KEY + RC_RSA_Decrypt_keyHandle; 8894// The selected key must be an unrestricted decryption key 8895if( 8896rsaKey->publicArea.objectAttributes.restricted == SET 8897|| rsaKey->publicArea.objectAttributes.decrypt == CLEAR) 8898return TPM_RC_ATTRIBUTES + RC_RSA_Decrypt_keyHandle; 8899// 8900// 8901// 8902// 8903 8904NOTE: Proper operation of this command requires that the sensitive area 8905of the key is loaded. This is assured because authorization is required 8906to use the sensitive area of the key. In order to check the authorization, 8907the sensitive area has to be loaded, even if authorization is with policy. 8908 8909// If label is present, make sure that it is a NULL-terminated string 8910if(in->label.t.size > 0) 8911{ 8912// Present, so make sure that it is NULL-terminated 8913if(in->label.t.buffer[in->label.t.size - 1] != 0) 8914return TPM_RC_VALUE + RC_RSA_Decrypt_label; 8915label = (char *)in->label.t.buffer; 8916} 8917// Command Output 8918// Select a scheme for decrypt. 8919scheme = CryptSelectRSAScheme(in->keyHandle, &in->inScheme); 8920if(scheme == NULL) 8921 8922Family “2.0” 8923Level 00 Revision 00.99 8924 8925Published 8926Copyright © TCG 2006-2013 8927 8928Page 99 8929October 31, 2013 8930 8931 Part 3: Commands 893247 893348 893449 893550 893651 893752 893853 893954 894055 894156 894257 894358 894459 894560 894661 8947 8948Trusted Platform Module Library 8949 8950return TPM_RC_SCHEME + RC_RSA_Decrypt_inScheme; 8951// Decryption. TPM_RC_VALUE, TPM_RC_SIZE, and TPM_RC_KEY error may be 8952// returned by CryptDecryptRSA. 8953// NOTE: CryptDecryptRSA can also return TPM_RC_ATTRIBUTES or TPM_RC_BINDING 8954// when the key is not a decryption key but that was checked above. 8955out->message.t.size = sizeof(out->message.t.buffer); 8956result = CryptDecryptRSA(&out->message.t.size, out->message.t.buffer, rsaKey, 8957scheme, in->cipherText.t.size, 8958in->cipherText.t.buffer, 8959label); 8960return result; 8961} 8962#endif 8963 8964Page 100 8965October 31, 2013 8966 8967Published 8968Copyright © TCG 2006-2013 8969 8970Family “2.0” 8971Level 00 Revision 00.99 8972 8973 Trusted Platform Module Library 8974 897516.4 8976 8977Part 3: Commands 8978 8979TPM2_ECDH_KeyGen 8980 898116.4.1 General Description 8982This command uses the TPM to generate an ephemeral key pair (de, Qe where Qe ≔ [de]G). It uses the private 8983ephemeral key and a loaded public key (QS) to compute the shared secret value (P ≔ [hde]QS). 8984 8985keyHandle shall refer to a loaded ECC key. The sensitive portion of this key need not be loaded. 8986The curve parameters of the loaded ECC key are used to generate the ephemeral key. 8987NOTE 1 8988 8989This function is the equivalent of encrypting data to another object’s public key. The seed value is 8990used in a KDF to generate a symmetric key and that key is used to encrypt the data. Once the data 8991is encrypted and the symmetric key discarded, only the ob ject with the private portion of the 8992keyHandle will be able to decrypt it. 8993 8994The zPoint in the response may be encrypted using parameter encryption. 8995 8996Family “2.0” 8997Level 00 Revision 00.99 8998 8999Published 9000Copyright © TCG 2006-2013 9001 9002Page 101 9003October 31, 2013 9004 9005 Part 3: Commands 9006 9007Trusted Platform Module Library 9008 900916.4.2 Command and Response 9010Table 47 — TPM2_ECDH_KeyGen Command 9011Type 9012 9013Name 9014 9015Description 9016 9017TPMI_ST_COMMAND_TAG 9018 9019tag 9020 9021UINT32 9022 9023commandSize 9024 9025TPM_CC 9026 9027commandCode 9028 9029TPM_CC_ECDH_KeyGen 9030 9031TPMI_DH_OBJECT 9032 9033keyHandle 9034 9035Handle of a loaded ECC key public area. 9036Auth Index: None 9037 9038Table 48 — TPM2_ECDH_KeyGen Response 9039Type 9040 9041Name 9042 9043Description 9044 9045TPM_ST 9046 9047tag 9048 9049see clause 8 9050 9051UINT32 9052 9053responseSize 9054 9055TPM_RC 9056 9057responseCode 9058 9059TPM2B_ECC_POINT 9060 9061zPoint 9062 9063results of P ≔ h[de]Qs 9064 9065TPM2B_ECC_POINT 9066 9067pubPoint 9068 9069generated ephemeral public point (Qe) 9070 9071Page 102 9072October 31, 2013 9073 9074Published 9075Copyright © TCG 2006-2013 9076 9077Family “2.0” 9078Level 00 Revision 00.99 9079 9080 Trusted Platform Module Library 9081 9082Part 3: Commands 9083 908416.4.3 Detailed Actions 90851 90862 90873 9088 9089#include "InternalRoutines.h" 9090#include "ECDH_KeyGen_fp.h" 9091#ifdef TPM_ALG_ECC 9092Error Returns 9093TPM_RC_KEY 9094 90954 90965 90976 90987 90998 91009 910110 910211 910312 910413 910514 910615 910716 910817 910918 911019 911120 911221 911322 911423 911524 911625 911726 911827 911928 912029 912130 912231 912332 912433 912534 912635 912736 912837 912938 913039 913140 913241 913342 913443 913544 913645 913746 913847 913948 914049 914150 914251 914352 914453 9145 9146Meaning 9147keyHandle does not reference a non-restricted decryption ECC key 9148 9149TPM_RC 9150TPM2_ECDH_KeyGen( 9151ECDH_KeyGen_In 9152ECDH_KeyGen_Out 9153 9154*in, 9155*out 9156 9157// IN: input parameter list 9158// OUT: output parameter list 9159 9160) 9161{ 9162OBJECT 9163TPM2B_ECC_PARAMETER 9164TPM_RC 9165 9166*eccKey; 9167sensitive; 9168result; 9169 9170// Input Validation 9171eccKey = ObjectGet(in->keyHandle); 9172// Input key must be a non-restricted, decrypt ECC key 9173if( 9174eccKey->publicArea.type != TPM_ALG_ECC 9175|| eccKey->publicArea.objectAttributes.restricted == SET 9176|| eccKey->publicArea.objectAttributes.decrypt != SET 9177) 9178return TPM_RC_KEY + RC_ECDH_KeyGen_keyHandle; 9179// Command Output 9180do 9181{ 9182// Create ephemeral ECC key 9183CryptNewEccKey(eccKey->publicArea.parameters.eccDetail.curveID, 9184&out->pubPoint.t.point, &sensitive); 9185out->pubPoint.t.size = TPMS_ECC_POINT_Marshal(&out->pubPoint.t.point, 9186NULL, NULL); 9187// Compute Z 9188result = CryptEccPointMultiply(&out->zPoint.t.point, 9189eccKey->publicArea.parameters.eccDetail.curveID, 9190&sensitive, &eccKey->publicArea.unique.ecc); 9191// The point in the key is not on the curve. Indicate that the key is bad. 9192if(result == TPM_RC_ECC_POINT) 9193return TPM_RC_KEY + RC_ECDH_KeyGen_keyHandle; 9194// The other possible error is TPM_RC_NO_RESULT indicating that the 9195// multiplication resulted in the point at infinity, so get a new 9196// random key and start over (hardly ever happens). 9197} 9198while(result != TPM_RC_SUCCESS); 9199// Marshal the values to generate the point. 9200out->zPoint.t.size = TPMS_ECC_POINT_Marshal(&out->zPoint.t.point, NULL, NULL); 9201return TPM_RC_SUCCESS; 9202} 9203#endif 9204 9205Family “2.0” 9206Level 00 Revision 00.99 9207 9208Published 9209Copyright © TCG 2006-2013 9210 9211Page 103 9212October 31, 2013 9213 9214 Part 3: Commands 9215 921616.5 9217 9218Trusted Platform Module Library 9219 9220TPM2_ECDH_ZGen 9221 922216.5.1 General Description 9223This command uses the TPM to recover the Z value from a public point (QB) and a private key (ds). It will 9224perform the multiplication of the provided inPoint (QB) with the private key (ds) and return the coordinates 9225of the resultant point (Z = (xZ , yZ) ≔ [hds]QB; where h is the cofactor of the curve). 9226keyHandle shall refer to a loaded, ECC key (TPM_RC_KEY) with the restricted attribute CLEAR and the 9227decrypt attribute SET (TPM_RC_ATTRIBUTES). 9228The scheme of the key referenced by keyHandle is required to be either TPM_ALG_ECDH or 9229TPM_ALG_NULL (TPM_RC_SCHEME). 9230inPoint is required to be on the curve of the key referenced by keyHandle (TPM_RC_ECC_POINT). 9231The parameters of the key referenced by keyHandle are used to perform the point multiplication. 9232 9233Page 104 9234October 31, 2013 9235 9236Published 9237Copyright © TCG 2006-2013 9238 9239Family “2.0” 9240Level 00 Revision 00.99 9241 9242 Trusted Platform Module Library 9243 9244Part 3: Commands 9245 924616.5.2 Command and Response 9247Table 49 — TPM2_ECDH_ZGen Command 9248Type 9249 9250Name 9251 9252Description 9253 9254TPMI_ST_COMMAND_TAG 9255 9256tag 9257 9258UINT32 9259 9260commandSize 9261 9262TPM_CC 9263 9264commandCode 9265 9266TPM_CC_ECDH_ZGen 9267 9268TPMI_DH_OBJECT 9269 9270@keyHandle 9271 9272handle of a loaded ECC key 9273Auth Index: 1 9274Auth Role: USER 9275 9276TPM2B_ECC_POINT 9277 9278inPoint 9279 9280a public key 9281 9282Table 50 — TPM2_ECDH_ZGen Response 9283Type 9284 9285Name 9286 9287Description 9288 9289TPM_ST 9290 9291tag 9292 9293see clause 8 9294 9295UINT32 9296 9297responseSize 9298 9299TPM_RC 9300 9301responseCode 9302 9303TPM2B_ECC_POINT 9304 9305outPoint 9306 9307Family “2.0” 9308Level 00 Revision 00.99 9309 9310X and Y coordinates of the product of the multiplication 9311 9312Z = (xZ , yZ) ≔ [hdS]QB 9313 9314Published 9315Copyright © TCG 2006-2013 9316 9317Page 105 9318October 31, 2013 9319 9320 Part 3: Commands 9321 9322Trusted Platform Module Library 9323 932416.5.3 Detailed Actions 93251 93262 93273 9328 9329#include "InternalRoutines.h" 9330#include "ECDH_ZGen_fp.h" 9331#ifdef TPM_ALG_ECC 9332Error Returns 9333TPM_RC_KEY 9334 9335keyHandle does not reference a non-restricted decryption ECC key 9336 9337TPM_RC_ECC_POINT 9338 9339invalid argument 9340 9341TPM_RC_NO_RESULT 93424 93435 93446 93457 93468 93479 934810 934911 935012 935113 935214 935315 935416 935517 935618 935719 935820 935921 936022 936123 936224 936325 936426 936527 936628 936729 936830 936931 937032 937133 937234 937335 937436 937537 937638 937739 9378 9379Meaning 9380 9381multiplying inPoint resulted in a point at infinity 9382 9383TPM_RC 9384TPM2_ECDH_ZGen( 9385ECDH_ZGen_In 9386ECDH_ZGen_Out 9387 9388*in, 9389*out 9390 9391// IN: input parameter list 9392// OUT: output parameter list 9393 9394) 9395{ 9396TPM_RC 9397OBJECT 9398 9399result; 9400*eccKey; 9401 9402// Input Validation 9403eccKey = ObjectGet(in->keyHandle); 9404// Input key must be a non-restricted, decrypt ECC key 9405if( 9406eccKey->publicArea.type != TPM_ALG_ECC 9407|| eccKey->publicArea.objectAttributes.restricted == SET 9408|| eccKey->publicArea.objectAttributes.decrypt != SET 9409) 9410return TPM_RC_KEY + RC_ECDH_ZGen_keyHandle; 9411// Command Output 9412// Compute Z. TPM_RC_ECC_POINT or TPM_RC_NO_RESULT may be returned here. 9413result = CryptEccPointMultiply(&out->outPoint.t.point, 9414eccKey->publicArea.parameters.eccDetail.curveID, 9415&eccKey->sensitive.sensitive.ecc, 9416&in->inPoint.t.point); 9417if(result != TPM_RC_SUCCESS) 9418return RcSafeAddToResult(result, RC_ECDH_ZGen_inPoint); 9419out->outPoint.t.size = TPMS_ECC_POINT_Marshal(&out->outPoint.t.point, 9420NULL, NULL); 9421return TPM_RC_SUCCESS; 9422} 9423#endif 9424 9425Page 106 9426October 31, 2013 9427 9428Published 9429Copyright © TCG 2006-2013 9430 9431Family “2.0” 9432Level 00 Revision 00.99 9433 9434 Trusted Platform Module Library 9435 943616.6 9437 9438Part 3: Commands 9439 9440TPM2_ECC_Parameters 9441 944216.6.1 General Description 9443This command returns the parameters of an ECC curve identified by its TCG-assigned curveID. 944416.6.2 Command and Response 9445Table 51 — TPM2_ECC_Parameters Command 9446Type 9447 9448Name 9449 9450Description 9451 9452TPMI_ST_COMMAND_TAG 9453 9454tag 9455 9456UINT32 9457 9458commandSize 9459 9460TPM_CC 9461 9462commandCode 9463 9464TPM_CC_ECC_Parameters 9465 9466TPMI_ECC_CURVE 9467 9468curveID 9469 9470parameter set selector 9471 9472Table 52 — TPM2_ECC_Parameters Response 9473Type 9474 9475Name 9476 9477Description 9478 9479TPM_ST 9480 9481tag 9482 9483see clause 8 9484 9485UINT32 9486 9487responseSize 9488 9489TPM_RC 9490 9491responseCode 9492 9493TPMS_ALGORITHM_DETAIL_ECC 9494 9495parameters 9496 9497Family “2.0” 9498Level 00 Revision 00.99 9499 9500ECC parameters for the selected curve 9501 9502Published 9503Copyright © TCG 2006-2013 9504 9505Page 107 9506October 31, 2013 9507 9508 Part 3: Commands 9509 9510Trusted Platform Module Library 9511 951216.6.3 Detailed Actions 95131 95142 95153 9516 9517#include "InternalRoutines.h" 9518#include "ECC_Parameters_fp.h" 9519#ifdef TPM_ALG_ECC 9520Error Returns 9521TPM_RC_VALUE 9522 95234 95245 95256 95267 95278 95289 952910 953011 953112 953213 953314 953415 953516 953617 953718 9538 9539Meaning 9540Unsupported ECC curve ID 9541 9542TPM_RC 9543TPM2_ECC_Parameters( 9544ECC_Parameters_In 9545ECC_Parameters_Out 9546 9547*in, 9548*out 9549 9550// IN: input parameter list 9551// OUT: output parameter list 9552 9553) 9554{ 9555// Command Output 9556// Get ECC curve parameters 9557if(CryptEccGetParameters(in->curveID, &out->parameters)) 9558return TPM_RC_SUCCESS; 9559else 9560return TPM_RC_VALUE + RC_ECC_Parameters_curveID; 9561} 9562#endif 9563 956416.7 956516.7.1 9566 9567TPM2_ZGen_2Phase 9568General Description 9569 9570This command supports two-phase key exchange protocols. The command is used in combination with 9571TPM2_EC_Ephemeral(). TPM2_EC_Ephemeral() generates an ephemeral key and returns the public 9572point of that ephemeral key along with a numeric value that allows the TPM to regenerate the associated 9573private key. 9574The input parameters for this command are a static public key (inQsU), an ephemeral key (inQeU) from 9575party B, and the commitCounter returned by TPM2_EC_Ephemeral(). The TPM uses the counter value to 9576regenerate the ephemeral private key (de,V) and the associated public key (Qe,V). keyA provides the static 9577ephemeral elements ds,V and Qs,V. This provides the two pairs of ephemeral and static keys that are 9578required for the schemes supported by this command. 9579The TPM will compute Z or Zs and Ze according to the selected scheme. If the scheme is not a two-phase 9580key exchange scheme or if the scheme is not supported, the TPM will return TPM_RC_SCHEME. 9581It is an error if inQsB or inQeB are not on the curve of keyA (TPM_RC_ECC_POINT). 9582The two-phase key schemes that were assigned an algorithm ID as of the time of the publication of this 9583specification are TPM_ALG_ECDH, TPM_ALG_ECMQV, and TPM_ALG_SM2. 9584If this command is supported, then support for TPM_ALG_ECDH is required. Support for 9585TPM_ALG_ECMQV or TPM_ALG_SM2 is optional. 9586NOTE 1 9587 9588If SM2 is supported and this command is supported, then the implementation is required to support 9589the key exchange protocol of SM2, part 3. 9590 9591For TPM_ALG_ECDH outZ1 will be Zs and outZ2 will Ze as defined in 6.1.1.2 of SP800-56A. 9592 9593Page 108 9594October 31, 2013 9595 9596Published 9597Copyright © TCG 2006-2013 9598 9599Family “2.0” 9600Level 00 Revision 00.99 9601 9602 Trusted Platform Module Library 9603NOTE 2 9604 9605Part 3: Commands 9606 9607A non-restricted decryption key using ECDH may be used in either TPM2_ECDH_ZGen() or 9608TPM2_ZGen_2Phase as the computation done with the private part of keyA is the same in both 9609cases. 9610 9611For TPM_ALG_ECMQV or TPM_ALG_SM2 outZ1 will be Z and outZ2 will be an Empty Point. 9612NOTE 3 9613 9614An Empty Point has two Empty Buffers as coordinates meaning the minimum size value for outZ2 9615will be four. 9616 9617If the input scheme is TPM_ALG_ECDH, then outZ1 will be Zs and outZ2 will be Ze. For schemes like 9618MQV (including SM2), outZ1 will contain the computed value and outZ2 will be an Empty Point. 9619NOTE 9620 9621The Z values returned by the TPM are a full point and not ju st an x-coordinate. 9622 9623If a computation of either Z produces the point at infinity, then the corresponding Z value will be an Empty 9624Point. 9625 9626Family “2.0” 9627Level 00 Revision 00.99 9628 9629Published 9630Copyright © TCG 2006-2013 9631 9632Page 109 9633October 31, 2013 9634 9635 Part 3: Commands 9636 963716.7.2 9638 9639Trusted Platform Module Library 9640 9641Command and Response 9642Table 53 — TPM2_ZGen_2Phase Command 9643 9644Type 9645 9646Name 9647 9648TPMI_ST_COMMAND_TAG 9649 9650tag 9651 9652UINT32 9653 9654commandSize 9655 9656TPM_CC 9657 9658commandCode 9659 9660Description 9661 9662TPM_CC_ ZGen_2Phase 9663handle of an unrestricted decryption key ECC 9664The private key referenced by this handle is used as dS,A 9665 9666TPMI_DH_OBJECT 9667 9668@keyA 9669 9670TPM2B_ECC_POINT 9671 9672inQsB 9673 9674other party’s static public key (Qs,B = (Xs,B, Ys,B)) 9675 9676TPM2B_ECC_POINT 9677 9678inQeB 9679 9680other party's ephemeral public key (Qe,B = (Xe,B, Ye,B)) 9681 9682TPMI_ECC_KEY_EXCHANGE 9683 9684inScheme 9685 9686the key exchange scheme 9687 9688UINT16 9689 9690counter 9691 9692value returned by TPM2_EC_Ephemeral() 9693 9694Auth Index: 1 9695Auth Role: USER 9696 9697Table 54 — TPM2_ZGen_2Phase Response 9698Type 9699 9700Name 9701 9702TPM_ST 9703 9704tag 9705 9706UINT32 9707 9708responseSize 9709 9710TPM_RC 9711 9712responseCode 9713 9714TPM2B_ECC_POINT 9715 9716outZ1 9717 9718X and Y coordinates of the computed value (scheme 9719dependent) 9720 9721TPM2B_ECC_POINT 9722 9723outZ2 9724 9725X and Y coordinates of the second computed value 9726(scheme dependent) 9727 9728Page 110 9729October 31, 2013 9730 9731Description 9732 9733Published 9734Copyright © TCG 2006-2013 9735 9736Family “2.0” 9737Level 00 Revision 00.99 9738 9739 Trusted Platform Module Library 9740 974116.7.3 97421 97432 97443 9745 9746Part 3: Commands 9747 9748Detailed Actions 9749 9750#include "InternalRoutines.h" 9751#include "ZGen_2Phase_fp.h" 9752#if defined TPM_ALG_ECC && (CC_ZGen_2Phase == YES) 9753 9754This command uses the TPM to recover one or two Z values in a two phase key exchange protocol 9755Error Returns 9756TPM_RC_ATTRIBUTES 9757 9758key referenced by keyA is restricted or not a decrypt key 9759 9760TPM_RC_ECC_POINT 9761 9762inQsB or inQeB is not on the curve of the key reference by keyA 9763 9764TPM_RC_KEY 9765 9766key referenced by keyA is not an ECC key 9767 9768TPM_RC_SCHEME 9769 97704 97715 97726 97737 97748 97759 977610 977711 977812 977913 978014 978115 978216 978317 978418 978519 978620 978721 978822 978923 979024 979125 979226 979327 979428 979529 979630 979731 979832 979933 980034 980135 980236 980337 980438 980539 980640 980741 980842 980943 981044 981145 981246 981347 9814 9815Meaning 9816 9817the scheme of the key referenced by keyA is not TPM_ALG_NULL, 9818TPM_ALG_ECDH, TPM_ALG_ECMQV or TPM_ALG_SM2 9819 9820TPM_RC 9821TPM2_ZGen_2Phase( 9822ZGen_2Phase_In 9823ZGen_2Phase_Out 9824 9825*in, 9826*out 9827 9828// IN: input parameter list 9829// OUT: output parameter list 9830 9831) 9832{ 9833TPM_RC 9834OBJECT 9835TPM2B_ECC_PARAMETER 9836TPM_ALG_ID 9837 9838result; 9839*eccKey; 9840r; 9841scheme; 9842 9843// Input Validation 9844eccKey = ObjectGet(in->keyA); 9845// keyA must be an ECC key 9846if(eccKey->publicArea.type != TPM_ALG_ECC) 9847return TPM_RC_KEY + RC_ZGen_2Phase_keyA; 9848// keyA must not be restricted and must be a decrypt key 9849if( 9850eccKey->publicArea.objectAttributes.restricted == SET 9851|| eccKey->publicArea.objectAttributes.decrypt != SET 9852) 9853return TPM_RC_ATTRIBUTES + RC_ZGen_2Phase_keyA; 9854// if the scheme of keyA is TPM_ALG_NULL, then use the input scheme; otherwise 9855// the input scheme must be the same as the scheme of keyA 9856scheme = eccKey->publicArea.parameters.asymDetail.scheme.scheme; 9857if(scheme != TPM_ALG_NULL) 9858{ 9859if(scheme != in->inScheme) 9860return TPM_RC_SCHEME + RC_ZGen_2Phase_inScheme; 9861} 9862else 9863scheme = in->inScheme; 9864if(scheme == TPM_ALG_NULL) 9865return TPM_RC_SCHEME + RC_ZGen_2Phase_inScheme; 9866// Input points must be on the curve of keyA 9867if(!CryptEccIsPointOnCurve(eccKey->publicArea.parameters.eccDetail.curveID, 9868&in->inQsB.t.point)) 9869return TPM_RC_ECC_POINT + RC_ZGen_2Phase_inQsB; 9870if(!CryptEccIsPointOnCurve(eccKey->publicArea.parameters.eccDetail.curveID, 9871 9872Family “2.0” 9873Level 00 Revision 00.99 9874 9875Published 9876Copyright © TCG 2006-2013 9877 9878Page 111 9879October 31, 2013 9880 9881 Part 3: Commands 988248 988349 988450 988551 988652 988753 988854 988955 989056 989157 989258 989359 989460 989561 989662 989763 989864 989965 990066 990167 990268 990369 990470 990571 990672 990773 9908 9909Trusted Platform Module Library 9910 9911&in->inQeB.t.point)) 9912return TPM_RC_ECC_POINT + RC_ZGen_2Phase_inQeB; 9913if(!CryptGenerateR(&r, &in->counter, 9914eccKey->publicArea.parameters.eccDetail.curveID, 9915NULL)) 9916return TPM_RC_VALUE + RC_ZGen_2Phase_counter; 9917// Command Output 9918result = CryptEcc2PhaseKeyExchange(&out->outZ1.t.point, 9919&out->outZ2.t.point, 9920eccKey->publicArea.parameters.eccDetail.curveID, 9921scheme, 9922&eccKey->sensitive.sensitive.ecc, 9923&r, 9924&in->inQsB.t.point, 9925&in->inQeB.t.point); 9926if(result != TPM_RC_SUCCESS) 9927return result; 9928CryptEndCommit(in->counter); 9929return TPM_RC_SUCCESS; 9930} 9931#endif 9932 9933Page 112 9934October 31, 2013 9935 9936Published 9937Copyright © TCG 2006-2013 9938 9939Family “2.0” 9940Level 00 Revision 00.99 9941 9942 Trusted Platform Module Library 9943 994417 994517.1 9946 9947Part 3: Commands 9948 9949Symmetric Primitives 9950Introduction 9951 9952The commands in this clause provide low-level primitives for access to the symmetric algorithms 9953implemented in the TPM that operate on blocks of data. These include symmetric encryption and 9954decryption as well as hash and HMAC. All of the commands in this group are stateless. That is, they have 9955no persistent state that is retained in the TPM when the command is complete. 9956For hashing, HMAC, and Events that require large blocks of data with retained state, the sequence 9957commands are provided (see clause 1). 9958Some of the symmetric encryption/decryption modes use an IV. When an IV is used, it may be an 9959initiation value or a chained value from a previous stage. The chaining for each mode is: 9960 9961Family “2.0” 9962Level 00 Revision 00.99 9963 9964Published 9965Copyright © TCG 2006-2013 9966 9967Page 113 9968October 31, 2013 9969 9970 Part 3: Commands 9971 9972Trusted Platform Module Library 9973Table 55 — Symmetric Chaining Process 9974 9975Mode 9976 9977Chaining process 9978 9979TPM_ALG_CTR 9980 9981The TPM will increment the entire IV provided by the caller. The last encrypted value will be 9982returned to the caller as ivOut. This can be the input value to the next encrypted buffer. 9983ivIn is required to be the size of a block encrypted by the selected algorithm and key 9984combination. If the size of ivIn is not correct, the TPM shall return TPM_RC_SIZE. 9985EXAMPLE 1 AES requires that ivIn be 128 bits (16 octets). 9986 9987ivOut will be the size of a cipher block and not the size of the last encrypted block. 9988NOTE 9989 9990ivOut will be the value of the counter after the last block is encrypted. 9991 9992EXAMPLE 2 If ivIn were 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0016 and four data blocks 9993were encrypted, ivOut will have a value of 999400 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0416. 9995 9996All the bits of the IV are incremented as if it were an unsigned integer. 9997TPM_ALG_OFB 9998 9999In Output Feedback (OFB), the output of the pseudo-random function (the block encryption 10000algorithm) is XORed with a plaintext block to produce a ciphertext block. ivOut will be the 10001value that was XORed with the last plaintext block. That value can be used as the ivIn for a 10002next buffer. 10003ivIn is required to be the size of a block encrypted by the selected algorithm and key 10004combination. If the size of ivIn is not correct, the TPM shall return TPM_RC_SIZE. 10005ivOut will be the size of a cipher block and not the size of the last encrypted block. 10006 10007TPM_ALG_CBC 10008 10009For Cipher Block Chaining (CBC), a block of ciphertext is XORed with the next plaintext 10010block and that block is encrypted. The encrypted block is then input to the encryption of the 10011next block. The last ciphertext block then is used as an IV for the next buffer. 10012Even though the last ciphertext block is evident in the encrypted data, it is also returned in 10013ivOut. 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. 10016inData is required to be an even multiple of the block encrypted by the selected algorithm 10017and key combination. If the size of inData is not correct, the TPM shall return 10018TPM_RC_SIZE. 10019 10020TPM_ALG_CFB 10021 10022Similar to CBC in that the last ciphertext block is an input to the encryption of the next block. 10023ivOut will be the value that was XORed with the last plaintext block. That value can be used 10024as the ivIn for a next buffer. 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. 10027ivOut will be the size of a cipher block and not the size of the last encrypted block. 10028 10029TPM_ALG_ECB 10030 10031Electronic Codebook (ECB) has no chaining. Each block of plaintext is encrypted using the 10032key. ECB does not support chaining and ivIn shall be the Empty Buffer. ivOut will be the 10033Empty Buffer. 10034inData is required to be an even multiple of the block encrypted by the selected algorithm 10035and key combination. If the size of inData is not correct, the TPM shall return 10036TPM_RC_SIZE. 10037 10038Page 114 10039October 31, 2013 10040 10041Published 10042Copyright © TCG 2006-2013 10043 10044Family “2.0” 10045Level 00 Revision 00.99 10046 10047 Trusted Platform Module Library 10048 1004917.2 10050 10051Part 3: Commands 10052 10053TPM2_EncryptDecrypt 10054 1005517.2.1 General Description 10056This command performs symmetric encryption or decryption. 10057keyHandle shall reference a symmetric cipher object (TPM_RC_KEY). 10058For a restricted key, mode shall be either the same as the mode of the key, or TPM_ALG_NULL 10059(TPM_RC_VALUE). For an unrestricted key, mode may be the same or different from the mode of the key 10060but both shall not be TPM_ALG_NULL (TPM_RC_VALUE). 10061If the TPM allows this command to be canceled before completion, then the TPM may produce 10062incremental results and return TPM_RC_SUCCESS rather than TPM_RC_CANCEL. In such case, 10063outData may be less than inData. 10064 10065Family “2.0” 10066Level 00 Revision 00.99 10067 10068Published 10069Copyright © TCG 2006-2013 10070 10071Page 115 10072October 31, 2013 10073 10074 Part 3: Commands 10075 10076Trusted Platform Module Library 10077 1007817.2.2 Command and Response 10079Table 56 — TPM2_EncryptDecrypt Command 10080Type 10081 10082Name 10083 10084Description 10085 10086TPMI_ST_COMMAND_TAG 10087 10088tag 10089 10090UINT32 10091 10092commandSize 10093 10094TPM_CC 10095 10096commandCode 10097 10098TPM_CC_EncryptDecrypt 10099 10100TPMI_DH_OBJECT 10101 10102@keyHandle 10103 10104the symmetric key used for the operation 10105Auth Index: 1 10106Auth Role: USER 10107 10108TPMI_YES_NO 10109 10110decrypt 10111 10112if YES, then the operation is decryption; if NO, the 10113operation is encryption 10114 10115TPMI_ALG_SYM_MODE+ 10116 10117mode 10118 10119symmetric mode 10120For a restricted key, this field shall match the default 10121mode of the key or be TPM_ALG_NULL. 10122 10123TPM2B_IV 10124 10125ivIn 10126 10127an initial value as required by the algorithm 10128 10129TPM2B_MAX_BUFFER 10130 10131inData 10132 10133the data to be encrypted/decrypted 10134 10135Table 57 — TPM2_EncryptDecrypt Response 10136Type 10137 10138Name 10139 10140Description 10141 10142TPM_ST 10143 10144tag 10145 10146see clause 8 10147 10148UINT32 10149 10150responseSize 10151 10152TPM_RC 10153 10154responseCode 10155 10156TPM2B_MAX_BUFFER 10157 10158outData 10159 10160encrypted output 10161 10162TPM2B_IV 10163 10164ivOut 10165 10166chaining value to use for IV in next round 10167 10168Page 116 10169October 31, 2013 10170 10171Published 10172Copyright © TCG 2006-2013 10173 10174Family “2.0” 10175Level 00 Revision 00.99 10176 10177 Trusted Platform Module Library 10178 10179Part 3: Commands 10180 1018117.2.3 Detailed Actions 101821 101832 10184 10185#include "InternalRoutines.h" 10186#include "EncryptDecrypt_fp.h" 10187Error Returns 10188TPM_RC_KEY 10189 10190is not a symmetric decryption key with both public and private 10191portions loaded 10192 10193TPM_RC_SIZE 10194 10195IvIn size is incompatible with the block cipher mode; or inData size is 10196not an even multiple of the block size for CBC or ECB mode 10197 10198TPM_RC_VALUE 10199 102003 102014 102025 102036 102047 102058 102069 1020710 1020811 1020912 1021013 1021114 1021215 1021316 1021417 1021518 1021619 1021720 1021821 1021922 1022023 1022124 1022225 1022326 1022427 1022528 1022629 1022730 1022831 1022932 1023033 1023134 1023235 1023336 1023437 1023538 1023639 1023740 1023841 1023942 1024043 1024144 1024245 1024346 1024447 1024548 10246 10247Meaning 10248 10249keyHandle is restricted and the argument mode does not match the 10250key's mode 10251 10252TPM_RC 10253TPM2_EncryptDecrypt( 10254EncryptDecrypt_In 10255EncryptDecrypt_Out 10256 10257*in, 10258*out 10259 10260// IN: input parameter list 10261// OUT: output parameter list 10262 10263) 10264{ 10265OBJECT 10266UINT16 10267UINT16 10268BYTE 10269TPM_ALG_ID 10270 10271*symKey; 10272keySize; 10273blockSize; 10274*key; 10275alg; 10276 10277// Input Validation 10278symKey = ObjectGet(in->keyHandle); 10279// The input key should be a symmetric decrypt key. 10280if( 10281symKey->publicArea.type != TPM_ALG_SYMCIPHER 10282|| symKey->attributes.publicOnly == SET) 10283return TPM_RC_KEY + RC_EncryptDecrypt_keyHandle; 10284// If the input mode is TPM_ALG_NULL, use the key's mode 10285if( in->mode == TPM_ALG_NULL) 10286in->mode = symKey->publicArea.parameters.symDetail.sym.mode.sym; 10287// If the key is restricted, the input sym mode should match the key's sym 10288// mode 10289if( 10290symKey->publicArea.objectAttributes.restricted == SET 10291&& symKey->publicArea.parameters.symDetail.sym.mode.sym != in->mode) 10292return TPM_RC_VALUE + RC_EncryptDecrypt_mode; 10293// If the mode is null, then we have a problem. 10294// Note: Construction of a TPMT_SYM_DEF does not allow the 'mode' to be 10295// TPM_ALG_NULL so setting in->mode to the mode of the key should have 10296// produced a valid mode. However, this is suspenders. 10297if(in->mode == TPM_ALG_NULL) 10298return TPM_RC_VALUE + RC_EncryptDecrypt_mode; 10299// The input iv for ECB mode should be null. All the other modes should 10300// have an iv size same as encryption block size 10301keySize = symKey->publicArea.parameters.symDetail.sym.keyBits.sym; 10302alg = symKey->publicArea.parameters.symDetail.sym.algorithm; 10303blockSize = CryptGetSymmetricBlockSize(alg, keySize); 10304if( 10305(in->mode == TPM_ALG_ECB && in->ivIn.t.size != 0) 10306|| (in->mode != TPM_ALG_ECB && in->ivIn.t.size != blockSize)) 10307return TPM_RC_SIZE + RC_EncryptDecrypt_ivIn; 10308 10309Family “2.0” 10310Level 00 Revision 00.99 10311 10312Published 10313Copyright © TCG 2006-2013 10314 10315Page 117 10316October 31, 2013 10317 10318 Part 3: Commands 1031949 1032050 1032151 1032252 1032353 1032454 1032555 1032656 1032757 1032858 1032959 1033060 1033161 1033262 1033363 1033464 1033565 1033666 1033767 1033868 1033969 1034070 1034171 1034272 1034373 1034474 1034575 1034676 1034777 1034878 1034979 1035080 1035181 1035282 1035383 1035484 1035585 1035686 1035787 1035888 1035989 1036090 1036191 10362 10363Trusted Platform Module Library 10364 10365// The input data size of CBC mode or ECB mode must be an even multiple of 10366// the symmetric algorithm's block size 10367if( 10368(in->mode == TPM_ALG_CBC || in->mode == TPM_ALG_ECB) 10369&& (in->inData.t.size % blockSize) != 0) 10370return TPM_RC_SIZE + RC_EncryptDecrypt_inData; 10371// Copy IV 10372// Note: This is copied here so that the calls to the encrypt/decrypt functions 10373// will modify the output buffer, not the input buffer 10374out->ivOut = in->ivIn; 10375// Command Output 10376key = symKey->sensitive.sensitive.sym.t.buffer; 10377// For symmetric encryption, the cipher data size is the same as plain data 10378// size. 10379out->outData.t.size = in->inData.t.size; 10380if(in->decrypt == YES) 10381{ 10382// Decrypt data to output 10383CryptSymmetricDecrypt(out->outData.t.buffer, 10384alg, 10385keySize, in->mode, key, 10386&(out->ivOut), 10387in->inData.t.size, 10388in->inData.t.buffer); 10389} 10390else 10391{ 10392// Encrypt data to output 10393CryptSymmetricEncrypt(out->outData.t.buffer, 10394alg, 10395keySize, 10396in->mode, key, 10397&(out->ivOut), 10398in->inData.t.size, 10399in->inData.t.buffer); 10400} 10401return TPM_RC_SUCCESS; 10402} 10403 10404Page 118 10405October 31, 2013 10406 10407Published 10408Copyright © TCG 2006-2013 10409 10410Family “2.0” 10411Level 00 Revision 00.99 10412 10413 Trusted Platform Module Library 10414 1041517.3 10416 10417Part 3: Commands 10418 10419TPM2_Hash 10420 1042117.3.1 General Description 10422This command performs a hash operation on a data buffer and returns the results. 10423NOTE 10424 10425If the data buffer to be hashed is larger than will fit into the TPM’s input buffer, then the sequence 10426hash commands will need to be used. 10427 10428If the results of the hash will be used in a signing operation that uses a restricted signing key, then the 10429ticket returned by this command can indicate that the hash is safe to sign. 10430If the digest is not safe to sign, then the TPM will return a TPMT_TK_HASHCHECK with the hierarchy set 10431to TPM_RH_NULL and digest set to the Empty Buffer. 10432If hierarchy is TPM_RH_NULL, then digest in the ticket will be the Empty Buffer. 10433 10434Family “2.0” 10435Level 00 Revision 00.99 10436 10437Published 10438Copyright © TCG 2006-2013 10439 10440Page 119 10441October 31, 2013 10442 10443 Part 3: Commands 10444 10445Trusted Platform Module Library 10446 1044717.3.2 Command and Response 10448Table 58 — TPM2_Hash Command 10449Type 10450 10451Name 10452 10453Description 10454 10455TPMI_ST_COMMAND_TAG 10456 10457tag 10458 10459Shall have at least one session 10460 10461UINT32 10462 10463commandSize 10464 10465TPM_CC 10466 10467commandCode 10468 10469TPM_CC_Hash 10470 10471TPM2B_MAX_BUFFER 10472 10473data 10474 10475data to be hashed 10476 10477TPMI_ALG_HASH 10478 10479hashAlg 10480 10481algorithm for the hash being computed – shall not be 10482TPM_ALG_NULL 10483 10484TPMI_RH_HIERARCHY+ 10485 10486hierarchy 10487 10488hierarchy to use for the ticket (TPM_RH_NULL allowed) 10489 10490Table 59 — TPM2_Hash Response 10491Type 10492 10493Name 10494 10495Description 10496 10497TPM_ST 10498 10499tag 10500 10501see clause 8 10502 10503UINT32 10504 10505responseSize 10506 10507TPM_RC 10508 10509responseCode 10510 10511TPM2B_DIGEST 10512 10513outHash 10514 10515results 10516 10517validation 10518 10519ticket indicating that the sequence of octets used to 10520compute outDigest did not start with 10521TPM_GENERATED_VALUE 10522will be a NULL ticket if the digest may not be signed 10523with a restricted key 10524 10525TPMT_TK_HASHCHECK 10526 10527Page 120 10528October 31, 2013 10529 10530Published 10531Copyright © TCG 2006-2013 10532 10533Family “2.0” 10534Level 00 Revision 00.99 10535 10536 Trusted Platform Module Library 10537 10538Part 3: Commands 10539 1054017.3.3 Detailed Actions 105411 105422 105433 105444 105455 105466 105477 105488 105499 1055010 1055111 1055212 1055313 1055414 1055515 1055616 1055717 1055818 1055919 1056020 1056121 1056222 1056323 1056424 1056525 1056626 1056727 1056828 1056929 1057030 1057131 1057232 1057333 1057434 1057535 1057636 1057737 1057838 1057939 1058040 1058141 1058242 1058343 1058444 1058545 10586 10587#include "InternalRoutines.h" 10588#include "Hash_fp.h" 10589 10590TPM_RC 10591TPM2_Hash( 10592Hash_In 10593Hash_Out 10594 10595*in, 10596*out 10597 10598// IN: input parameter list 10599// OUT: output parameter list 10600 10601) 10602{ 10603HASH_STATE 10604 10605hashState; 10606 10607// Command Output 10608// Output hash 10609// Start hash stack 10610out->outHash.t.size = CryptStartHash(in->hashAlg, &hashState); 10611// Adding hash data 10612CryptUpdateDigest2B(&hashState, &in->data.b); 10613// Complete hash 10614CryptCompleteHash2B(&hashState, &out->outHash.b); 10615// Output ticket 10616out->validation.tag = TPM_ST_HASHCHECK; 10617out->validation.hierarchy = in->hierarchy; 10618if(in->hierarchy == TPM_RH_NULL) 10619{ 10620// Ticket is not required 10621out->validation.hierarchy = TPM_RH_NULL; 10622out->validation.digest.t.size = 0; 10623} 10624else if( in->data.t.size >= sizeof(TPM_GENERATED) 10625&& !TicketIsSafe(&in->data.b)) 10626{ 10627// Ticket is not safe 10628out->validation.hierarchy = TPM_RH_NULL; 10629out->validation.digest.t.size = 0; 10630} 10631else 10632{ 10633// Compute ticket 10634TicketComputeHashCheck(in->hierarchy, &out->outHash, &out->validation); 10635} 10636return TPM_RC_SUCCESS; 10637} 10638 10639Family “2.0” 10640Level 00 Revision 00.99 10641 10642Published 10643Copyright © TCG 2006-2013 10644 10645Page 121 10646October 31, 2013 10647 10648 Part 3: Commands 10649 1065017.4 10651 10652Trusted Platform Module Library 10653 10654TPM2_HMAC 10655 1065617.4.1 General Description 10657This command performs an HMAC on the supplied data using the indicated hash algorithm. 10658The caller shall provide proper authorization for use of handle. 10659If the sign attribute is not SET in the key referenced by handle then the TPM shall return 10660TPM_RC_ATTRIBUTES. If the key type is not TPM_ALG_KEYEDHASH then the TPM shall return 10661TPM_RC_TYPE. 10662If handle references a restricted key, then the hash algorithm specified in the key's scheme is used as the 10663hash algorithm for the HMAC and the TPM shall return TPM_RC_VALUE if hashAlg is not 10664TPM_ALG_NULL or the same algorithm as selected in the key's scheme. 10665NOTE 1 10666A restricted key may only have one of sign or decrypt SET and the default scheme may not 10667be TPM_ALG_NULL. These restrictions are enforced by TPM2_Create() and TPM2_CreatePrimary(), 10668If the key referenced by handle is not restricted, then the TPM will use hashAlg for the HMAC. However, if 10669hashAlg is TPM_ALG_NULL the TPM will use the default scheme of the key. 10670If both hashAlg and the key default are TPM_ALG_NULL, the TPM shall return TPM_RC_VALUE. 10671NOTE 10672 10673A key may only have both sign and decrypt SET if the key is unrestricted. When bo th sign and 10674decrypt are set, there is no default scheme for the key and the hash algorithm must be specified . 10675 10676Page 122 10677October 31, 2013 10678 10679Published 10680Copyright © TCG 2006-2013 10681 10682Family “2.0” 10683Level 00 Revision 00.99 10684 10685 Trusted Platform Module Library 10686 10687Part 3: Commands 10688 1068917.4.2 Command and Response 10690Table 60 — TPM2_HMAC Command 10691Type 10692 10693Name 10694 10695Description 10696 10697TPMI_ST_COMMAND_TAG 10698 10699tag 10700 10701UINT32 10702 10703commandSize 10704 10705TPM_CC 10706 10707commandCode 10708 10709TPM_CC_HMAC 10710 10711TPMI_DH_OBJECT 10712 10713@handle 10714 10715handle for the symmetric signing key providing the 10716HMAC key 10717Auth Index: 1 10718Auth Role: USER 10719 10720TPM2B_MAX_BUFFER 10721 10722buffer 10723 10724HMAC data 10725 10726TPMI_ALG_HASH+ 10727 10728hashAlg 10729 10730algorithm to use for HMAC 10731 10732Table 61 — TPM2_HMAC Response 10733Type 10734 10735Name 10736 10737Description 10738 10739TPM_ST 10740 10741tag 10742 10743see clause 8 10744 10745UINT32 10746 10747responseSize 10748 10749TPM_RC 10750 10751responseCode 10752 10753TPM2B_DIGEST 10754 10755outHMAC 10756 10757Family “2.0” 10758Level 00 Revision 00.99 10759 10760the returned HMAC in a sized buffer 10761 10762Published 10763Copyright © TCG 2006-2013 10764 10765Page 123 10766October 31, 2013 10767 10768 Part 3: Commands 10769 10770Trusted Platform Module Library 10771 1077217.4.3 Detailed Actions 107731 107742 10775 10776#include "InternalRoutines.h" 10777#include "HMAC_fp.h" 10778Error Returns 10779TPM_RC_ATTRIBUTES 10780 10781key referenced by handle is not a signing key 10782 10783TPM_RC_TYPE 10784 10785key referenced by handle is not an HMAC key 10786 10787TPM_RC_VALUE 10788 107893 107904 107915 107926 107937 107948 107959 1079610 1079711 1079812 1079913 1080014 1080115 1080216 1080317 1080418 1080519 1080620 1080721 1080822 1080923 1081024 1081125 1081226 1081327 1081428 1081529 1081630 1081731 1081832 1081933 1082034 1082135 1082236 1082337 1082438 1082539 1082640 1082741 1082842 1082943 1083044 1083145 1083246 1083347 1083448 1083549 10836 10837Meaning 10838 10839hashAlg specified when the key is restricted is neither 10840TPM_ALG_NULL not equal to that of the key scheme; or both 10841hashAlg and the key scheme's algorithm are TPM_ALG_NULL 10842 10843TPM_RC 10844TPM2_HMAC( 10845HMAC_In 10846HMAC_Out 10847 10848*in, 10849*out 10850 10851// IN: input parameter list 10852// OUT: output parameter list 10853 10854HMAC_STATE 10855OBJECT 10856TPMI_ALG_HASH 10857TPMT_PUBLIC 10858 10859hmacState; 10860*hmacObject; 10861hashAlg; 10862*publicArea; 10863 10864) 10865{ 10866 10867// Input Validation 10868// Get HMAC key object and public area pointers 10869hmacObject = ObjectGet(in->handle); 10870publicArea = &hmacObject->publicArea; 10871// Make sure that the key is an HMAC signing key 10872if(publicArea->type != TPM_ALG_KEYEDHASH) 10873return TPM_RC_TYPE + RC_HMAC_handle; 10874if(publicArea->objectAttributes.sign != SET) 10875return TPM_RC_ATTRIBUTES + RC_HMAC_handle; 10876// Assume that the key default scheme is used 10877hashAlg = publicArea->parameters.keyedHashDetail.scheme.details.hmac.hashAlg; 10878// if the key is restricted, then need to use the scheme of the key and the 10879// input algorithm must be TPM_ALG_NULL or the same as the key scheme 10880if(publicArea->objectAttributes.restricted == SET) 10881{ 10882if(in->hashAlg != TPM_ALG_NULL && in->hashAlg != hashAlg) 10883hashAlg = TPM_ALG_NULL; 10884} 10885else 10886{ 10887// for a non-restricted key, use hashAlg if it is provided; 10888if(in->hashAlg != TPM_ALG_NULL) 10889hashAlg = in->hashAlg; 10890} 10891// if the hashAlg is TPM_ALG_NULL, then the input hashAlg is not compatible 10892// with the key scheme or type 10893if(hashAlg == TPM_ALG_NULL) 10894return TPM_RC_VALUE + RC_HMAC_hashAlg; 10895// Command Output 10896 10897Page 124 10898October 31, 2013 10899 10900Published 10901Copyright © TCG 2006-2013 10902 10903Family “2.0” 10904Level 00 Revision 00.99 10905 10906 Trusted Platform Module Library 1090750 1090851 1090952 1091053 1091154 1091255 1091356 1091457 1091558 1091659 1091760 1091861 10919 10920Part 3: Commands 10921 10922// Start HMAC stack 10923out->outHMAC.t.size = CryptStartHMAC2B(hashAlg, 10924&hmacObject->sensitive.sensitive.bits.b, 10925&hmacState); 10926// Adding HMAC data 10927CryptUpdateDigest2B(&hmacState, &in->buffer.b); 10928// Complete HMAC 10929CryptCompleteHMAC2B(&hmacState, &out->outHMAC.b); 10930return TPM_RC_SUCCESS; 10931} 10932 10933Family “2.0” 10934Level 00 Revision 00.99 10935 10936Published 10937Copyright © TCG 2006-2013 10938 10939Page 125 10940October 31, 2013 10941 10942 Part 3: Commands 10943 1094418 10945 10946Trusted Platform Module Library 10947 10948Random Number Generator 10949 1095018.1 10951 10952TPM2_GetRandom 10953 1095418.1.1 General Description 10955This command returns the next bytesRequested octets from the random number generator (RNG). 10956NOTE 1 10957 10958It is recommended that a TPM implement the RNG in a manner that would allow it to return RNG 10959octets such that the frequency of bytesRequested being more than the number of octets available is 10960an infrequent occurrence. 10961 10962If bytesRequested is more than will fit into a TPM2B_DIGEST on the TPM, no error is returned but the 10963TPM will only return as much data as will fit into a TPM2B_DIGEST buffer for the TPM. 10964NOTE 2 10965 10966TPM2B_DIGEST is large enough to hold the largest digest that may be produced by the TPM. 10967Because that digest size changes according to the implemented hashes, the maximum amount of 10968data returned by this command is TPM implementation-dependent. 10969 10970Page 126 10971October 31, 2013 10972 10973Published 10974Copyright © TCG 2006-2013 10975 10976Family “2.0” 10977Level 00 Revision 00.99 10978 10979 Trusted Platform Module Library 10980 10981Part 3: Commands 10982 1098318.1.2 Command and Response 10984Table 62 — TPM2_GetRandom Command 10985Type 10986 10987Name 10988 10989Description 10990 10991TPMI_ST_COMMAND_TAG 10992 10993tag 10994 10995UINT32 10996 10997commandSize 10998 10999TPM_CC 11000 11001commandCode 11002 11003TPM_CC_GetRandom 11004 11005UINT16 11006 11007bytesRequested 11008 11009number of octets to return 11010 11011Table 63 — TPM2_GetRandom Response 11012Type 11013 11014Name 11015 11016Description 11017 11018TPM_ST 11019 11020tag 11021 11022see clause 8 11023 11024UINT32 11025 11026responseSize 11027 11028TPM_RC 11029 11030responseCode 11031 11032TPM2B_DIGEST 11033 11034randomBytes 11035 11036Family “2.0” 11037Level 00 Revision 00.99 11038 11039the random octets 11040 11041Published 11042Copyright © TCG 2006-2013 11043 11044Page 127 11045October 31, 2013 11046 11047 Part 3: Commands 11048 11049Trusted Platform Module Library 11050 1105118.1.3 Detailed Actions 110521 110532 110543 110554 110565 110576 110587 110598 110609 1106110 1106211 1106312 1106413 1106514 1106615 1106716 1106817 1106918 1107019 1107120 1107221 11073 11074#include "InternalRoutines.h" 11075#include "GetRandom_fp.h" 11076 11077TPM_RC 11078TPM2_GetRandom( 11079GetRandom_In 11080GetRandom_Out 11081 11082*in, 11083*out 11084 11085// IN: input parameter list 11086// OUT: output parameter list 11087 11088) 11089{ 11090// Command Output 11091// if the requested bytes exceed the output buffer size, generates the 11092// maximum bytes that the output buffer allows 11093if(in->bytesRequested > sizeof(TPMU_HA)) 11094out->randomBytes.t.size = sizeof(TPMU_HA); 11095else 11096out->randomBytes.t.size = in->bytesRequested; 11097CryptGenerateRandom(out->randomBytes.t.size, out->randomBytes.t.buffer); 11098return TPM_RC_SUCCESS; 11099} 11100 11101Page 128 11102October 31, 2013 11103 11104Published 11105Copyright © TCG 2006-2013 11106 11107Family “2.0” 11108Level 00 Revision 00.99 11109 11110 Trusted Platform Module Library 11111 1111218.2 11113 11114Part 3: Commands 11115 11116TPM2_StirRandom 11117 1111818.2.1 General Description 11119This command is used to add "additional information" to the RNG state. 11120NOTE 11121 11122The "additional information" is as defined in SP800 -90A. 11123 11124The inData parameter may not be larger than 128 octets. 11125 11126Family “2.0” 11127Level 00 Revision 00.99 11128 11129Published 11130Copyright © TCG 2006-2013 11131 11132Page 129 11133October 31, 2013 11134 11135 Part 3: Commands 11136 11137Trusted Platform Module Library 11138 1113918.2.2 Command and Response 11140Table 64 — TPM2_StirRandom Command 11141Type 11142 11143Name 11144 11145Description 11146 11147TPMI_ST_COMMAND_TAG 11148 11149tag 11150 11151UINT32 11152 11153commandSize 11154 11155TPM_CC 11156 11157commandCode 11158 11159TPM_CC_StirRandom {NV} 11160 11161TPM2B_SENSITIVE_DATA 11162 11163inData 11164 11165additional information 11166 11167Table 65 — TPM2_StirRandom Response 11168Type 11169 11170Name 11171 11172Description 11173 11174TPM_ST 11175 11176tag 11177 11178see clause 8 11179 11180UINT32 11181 11182responseSize 11183 11184TPM_RC 11185 11186responseCode 11187 11188Page 130 11189October 31, 2013 11190 11191Published 11192Copyright © TCG 2006-2013 11193 11194Family “2.0” 11195Level 00 Revision 00.99 11196 11197 Trusted Platform Module Library 11198 11199Part 3: Commands 11200 1120118.2.3 Detailed Actions 112021 112032 112043 112054 112065 112076 112087 112098 112109 1121110 1121211 1121312 11214 11215#include "InternalRoutines.h" 11216#include "StirRandom_fp.h" 11217 11218TPM_RC 11219TPM2_StirRandom( 11220StirRandom_In 11221*in 11222// IN: input parameter list 11223) 11224{ 11225// Internal Data Update 11226CryptStirRandom(in->inData.t.size, in->inData.t.buffer); 11227return TPM_RC_SUCCESS; 11228} 11229 11230Family “2.0” 11231Level 00 Revision 00.99 11232 11233Published 11234Copyright © TCG 2006-2013 11235 11236Page 131 11237October 31, 2013 11238 11239 Part 3: Commands 11240 1124119 11242 11243Trusted Platform Module Library 11244 11245Hash/HMAC/Event Sequences 11246 1124719.1 11248 11249Introduction 11250 11251All of the commands in this group are to support sequences for which an intermediate state must be 11252maintained. For a description of sequences, see “Hash, HMAC, and Event Sequences” in Part 1. 1125319.2 11254 11255TPM2_HMAC_Start 11256 1125719.2.1 General Description 11258This command starts an HMAC sequence. The TPM will create and initialize an HMAC sequence 11259structure, assign a handle to the sequence, and set the authValue of the sequence object to the value in 11260auth. 11261NOTE 1 11262 11263The structure of a sequence object is vendor -dependent. 11264 11265The caller shall provide proper authorization for use of handle. 11266If the sign attribute is not SET in the key referenced by handle then the TPM shall return 11267TPM_RC_ATTRIBUTES. If the key type is not TPM_ALG_KEYEDHASH then the TPM shall return 11268TPM_RC_TYPE. 11269If handle references a restricted key, then the hash algorithm specified in the key's scheme is used as the 11270hash algorithm for the HMAC and the TPM shall return TPM_RC_VALUE if hashAlg is not 11271TPM_ALG_NULL or the same algorithm in the key's scheme. 11272If the key referenced by handle is not restricted, then the TPM will use hashAlg for the HMAC; unless 11273hashAlg is TPM_ALG_NULL in which case it will use the default scheme of the key. 11274Table 66 — Hash Selection Matrix 11275handle→restricted 11276(key's restricted 11277attribute) 11278 11279handle→scheme 11280(hash algorithm 11281from key's scheme) 11282 11283CLEAR (unrestricted) 11284 11285TPM_ALG_NULL 11286 11287CLEAR 11288 11289don’t care 11290 11291CLEAR 11292 11293valid hash 11294 11295hash used 11296 11297TPM_ALG_NULL 11298 11299error 11300 11301valid hash 11302 11303(1) 11304 11305hashAlg 11306 11307hashAlg 11308 11309(2) 11310 11311(TPM_RC_SCHEME) 11312 11313TPM_ALG_NULL 11314 11315handle→scheme 11316 11317same as handle→scheme 11318 11319handle→scheme 11320 11321(3) 11322 11323SET 11324 11325handle→scheme 11326 11327(3) 11328 11329SET (restricted) 11330 11331TPM_ALG_NULL 11332 11333(3) 11334 11335not same as 11336handle→scheme 11337 11338error 11339 11340valid hash 11341valid hash 11342 11343SET 11344 11345valid hash 11346 11347(4) 11348 11349(TPM_RC_SCHEME) 11350 11351NOTES: 113521) 11353 11354The scheme for the handle may only be TPM_ALG_NULL if both sign and decrypt are SET. 11355 113562) 11357 11358A hash algorithm is required for the HMAC. 11359 113603) 11361 11362A restricted key is required to have a scheme with a valid hash algorithm. A restricted key may not have both sign and 11363decrypt SET. 11364 113654) 11366 11367The scheme for a restricted key cannot be overridden. 11368 11369Page 132 11370October 31, 2013 11371 11372Published 11373Copyright © TCG 2006-2013 11374 11375Family “2.0” 11376Level 00 Revision 00.99 11377 11378 Trusted Platform Module Library 11379 11380Part 3: Commands 11381 1138219.2.2 Command and Response 11383Table 67 — TPM2_HMAC_Start Command 11384Type 11385 11386Name 11387 11388Description 11389 11390TPMI_ST_COMMAND_TAG 11391 11392tag 11393 11394UINT32 11395 11396commandSize 11397 11398TPM_CC 11399 11400commandCode 11401 11402TPM_CC_HMAC_Start 11403 11404TPMI_DH_OBJECT 11405 11406@handle 11407 11408handle of an HMAC key 11409Auth Index: 1 11410Auth Role: USER 11411 11412TPM2B_AUTH 11413 11414auth 11415 11416authorization value for subsequent use of the sequence 11417 11418TPMI_ALG_HASH+ 11419 11420hashAlg 11421 11422the hash algorithm to use for the HMAC 11423 11424Table 68 — TPM2_HMAC_Start Response 11425Type 11426 11427Name 11428 11429Description 11430 11431TPM_ST 11432 11433tag 11434 11435see clause 8 11436 11437UINT32 11438 11439responseSize 11440 11441TPM_RC 11442 11443responseCode 11444 11445TPMI_DH_OBJECT 11446 11447sequenceHandle 11448 11449Family “2.0” 11450Level 00 Revision 00.99 11451 11452a handle to reference the sequence 11453 11454Published 11455Copyright © TCG 2006-2013 11456 11457Page 133 11458October 31, 2013 11459 11460 Part 3: Commands 11461 11462Trusted Platform Module Library 11463 1146419.2.3 Detailed Actions 114651 114662 11467 11468#include "InternalRoutines.h" 11469#include "HMAC_Start_fp.h" 11470Error Returns 11471TPM_RC_ATTRIBUTES 11472 11473key referenced by handle is not a signing key 11474 11475TPM_RC_OBJECT_MEMORY 11476 11477no space to create an internal object 11478 11479TPM_RC_TYPE 11480 11481key referenced by handle is not an HMAC key 11482 11483TPM_RC_VALUE 11484 114853 114864 114875 114886 114897 114908 114919 1149210 1149311 1149412 1149513 1149614 1149715 1149816 1149917 1150018 1150119 1150220 1150321 1150422 1150523 1150624 1150725 1150826 1150927 1151028 1151129 1151230 1151331 1151432 1151533 1151634 1151735 1151836 1151937 1152038 1152139 1152240 1152341 1152442 1152543 1152644 1152745 1152846 1152947 11530 11531Meaning 11532 11533hashAlg specified when the key is restricted is neither 11534TPM_ALG_NULL not equal to that of the key scheme; or both 11535hashAlg and the key scheme's algorithm are TPM_ALG_NULL 11536 11537TPM_RC 11538TPM2_HMAC_Start( 11539HMAC_Start_In 11540HMAC_Start_Out 11541 11542*in, 11543*out 11544 11545// IN: input parameter list 11546// OUT: output parameter list 11547 11548) 11549{ 11550OBJECT 11551TPMT_PUBLIC 11552TPM_ALG_ID 11553 11554*hmacObject; 11555*publicArea; 11556hashAlg; 11557 11558// Input Validation 11559// Get HMAC key object and public area pointers 11560hmacObject = ObjectGet(in->handle); 11561publicArea = &hmacObject->publicArea; 11562// Make sure that the key is an HMAC signing key 11563if(publicArea->type != TPM_ALG_KEYEDHASH) 11564return TPM_RC_TYPE + RC_HMAC_Start_handle; 11565if(publicArea->objectAttributes.sign != SET) 11566return TPM_RC_ATTRIBUTES + RC_HMAC_Start_handle; 11567// Assume that the key default scheme is used 11568hashAlg = publicArea->parameters.keyedHashDetail.scheme.details.hmac.hashAlg; 11569// if the key is restricted, then need to use the scheme of the key and the 11570// input algorithm must be TPM_ALG_NULL or the same as the key scheme 11571if(publicArea->objectAttributes.restricted == SET) 11572{ 11573if(in->hashAlg != TPM_ALG_NULL && in->hashAlg != hashAlg) 11574hashAlg = TPM_ALG_NULL; 11575} 11576else 11577{ 11578// for a non-restricted key, use hashAlg if it is provided; 11579if(in->hashAlg != TPM_ALG_NULL) 11580hashAlg = in->hashAlg; 11581} 11582// if the algorithm selection ended up with TPM_ALG_NULL, then either the 11583// schemes are not compatible or no hash was provided and both conditions 11584// are errors. 11585if(hashAlg == TPM_ALG_NULL) 11586return TPM_RC_VALUE + RC_HMAC_Start_hashAlg; 11587// Internal Data Update 11588 11589Page 134 11590October 31, 2013 11591 11592Published 11593Copyright © TCG 2006-2013 11594 11595Family “2.0” 11596Level 00 Revision 00.99 11597 11598 Trusted Platform Module Library 1159948 1160049 1160150 1160251 1160352 1160453 1160554 1160655 11607 11608Part 3: Commands 11609 11610// Create a HMAC sequence object. A TPM_RC_OBJECT_MEMORY error may be 11611// returned at this point 11612return ObjectCreateHMACSequence(hashAlg, 11613in->handle, 11614&in->auth, 11615&out->sequenceHandle); 11616} 11617 11618Family “2.0” 11619Level 00 Revision 00.99 11620 11621Published 11622Copyright © TCG 2006-2013 11623 11624Page 135 11625October 31, 2013 11626 11627 Part 3: Commands 11628 1162919.3 11630 11631Trusted Platform Module Library 11632 11633TPM2_HashSequenceStart 11634 1163519.3.1 General Description 11636This command starts a hash or an Event sequence. If hashAlg is an implemented hash, then a hash 11637sequence is started. If hashAlg is TPM_ALG_NULL, then an Event sequence is started. If hashAlg is 11638neither an implemented algorithm nor TPM_ALG_NULL, then the TPM shall return TPM_RC_HASH. 11639Depending on hashAlg, the TPM will create and initialize a hash sequence structure or an Event 11640sequence structure. Additionally, it will assign a handle to the sequence and set the authValue of the 11641sequence to the value in auth. A sequence structure for an Event (hashAlg = TPM_ALG_NULL) contains 11642a hash context for each of the PCR banks implemented on the TPM. 11643 11644Page 136 11645October 31, 2013 11646 11647Published 11648Copyright © TCG 2006-2013 11649 11650Family “2.0” 11651Level 00 Revision 00.99 11652 11653 Trusted Platform Module Library 11654 11655Part 3: Commands 11656 1165719.3.2 Command and Response 11658Table 69 — TPM2_HashSequenceStart Command 11659Type 11660 11661Name 11662 11663Description 11664 11665TPMI_ST_COMMAND_TAG 11666 11667tag 11668 11669UINT32 11670 11671commandSize 11672 11673TPM_CC 11674 11675commandCode 11676 11677TPM_CC_HashSequenceStart 11678 11679TPM2B_AUTH 11680 11681auth 11682 11683authorization value for subsequent use of the sequence 11684 11685TPMI_ALG_HASH+ 11686 11687hashAlg 11688 11689the hash algorithm to use for the hash sequence 11690An Event sequence starts if this is TPM_ALG_NULL. 11691 11692Table 70 — TPM2_HashSequenceStart Response 11693Type 11694 11695Name 11696 11697Description 11698 11699TPM_ST 11700 11701tag 11702 11703see clause 8 11704 11705UINT32 11706 11707responseSize 11708 11709TPM_RC 11710 11711responseCode 11712 11713TPMI_DH_OBJECT 11714 11715sequenceHandle 11716 11717Family “2.0” 11718Level 00 Revision 00.99 11719 11720a handle to reference the sequence 11721 11722Published 11723Copyright © TCG 2006-2013 11724 11725Page 137 11726October 31, 2013 11727 11728 Part 3: Commands 11729 11730Trusted Platform Module Library 11731 1173219.3.3 Detailed Actions 117331 117342 11735 11736#include "InternalRoutines.h" 11737#include "HashSequenceStart_fp.h" 11738Error Returns 11739TPM_RC_OBJECT_MEMORY 11740 117413 117424 117435 117446 117457 117468 117479 1174810 1174911 1175012 1175113 1175214 1175315 1175416 1175517 1175618 1175719 11758 11759Meaning 11760no space to create an internal object 11761 11762TPM_RC 11763TPM2_HashSequenceStart( 11764HashSequenceStart_In 11765HashSequenceStart_Out 11766 11767*in, 11768*out 11769 11770// IN: input parameter list 11771// OUT: output parameter list 11772 11773) 11774{ 11775// Internal Data Update 11776if(in->hashAlg == TPM_ALG_NULL) 11777// Start a event sequence. A TPM_RC_OBJECT_MEMORY error may be 11778// returned at this point 11779return ObjectCreateEventSequence(&in->auth, &out->sequenceHandle); 11780// Start a hash sequence. A TPM_RC_OBJECT_MEMORY error may be 11781// returned at this point 11782return ObjectCreateHashSequence(in->hashAlg, &in->auth, &out->sequenceHandle); 11783} 11784 11785Page 138 11786October 31, 2013 11787 11788Published 11789Copyright © TCG 2006-2013 11790 11791Family “2.0” 11792Level 00 Revision 00.99 11793 11794 Trusted Platform Module Library 11795 1179619.4 11797 11798Part 3: Commands 11799 11800TPM2_SequenceUpdate 11801 1180219.4.1 General Description 11803This command is used to add data to a hash or HMAC sequence. The amount of data in buffer may be 11804any size up to the limits of the TPM. 11805NOTE 11806 11807In all TPM, a buffer size of 1,024 octets is allowed. 11808 11809Proper authorization for the sequence object associated with sequenceHandle is required. If an 11810authorization or audit of this command requires computation of a cpHash and an rpHash, the Name 11811associated with sequenceHandle will be the Empty Buffer. 11812If the command does not return TPM_RC_SUCCESS, the state of the sequence is unmodified. 11813If the sequence is intended to produce a digest that will be signed by a restricted signing key, then the 11814first block of data shall contain sizeof(TPM_GENERATED) octets and the first octets shall not be 11815TPM_GENERATED_VALUE. 11816NOTE 11817 11818This requirement allows the TPM to validate that the first block is safe to sign without having to 11819accumulate octets over multiple calls. 11820 11821Family “2.0” 11822Level 00 Revision 00.99 11823 11824Published 11825Copyright © TCG 2006-2013 11826 11827Page 139 11828October 31, 2013 11829 11830 Part 3: Commands 11831 11832Trusted Platform Module Library 11833 1183419.4.2 Command and Response 11835Table 71 — TPM2_SequenceUpdate Command 11836Type 11837 11838Name 11839 11840Description 11841 11842TPMI_ST_COMMAND_TAG 11843 11844tag 11845 11846UINT32 11847 11848commandSize 11849 11850TPM_CC 11851 11852commandCode 11853 11854TPM_CC_SequenceUpdate 11855 11856TPMI_DH_OBJECT 11857 11858@sequenceHandle 11859 11860handle for the sequence object 11861Auth Index: 1 11862Auth Role: USER 11863 11864TPM2B_MAX_BUFFER 11865 11866buffer 11867 11868data to be added to hash 11869 11870Table 72 — TPM2_SequenceUpdate Response 11871Type 11872 11873Name 11874 11875Description 11876 11877TPM_ST 11878 11879tag 11880 11881see clause 8 11882 11883UINT32 11884 11885responseSize 11886 11887TPM_RC 11888 11889responseCode 11890 11891Page 140 11892October 31, 2013 11893 11894Published 11895Copyright © TCG 2006-2013 11896 11897Family “2.0” 11898Level 00 Revision 00.99 11899 11900 Trusted Platform Module Library 11901 11902Part 3: Commands 11903 1190419.4.3 Detailed Actions 119051 119062 11907 11908#include "InternalRoutines.h" 11909#include "SequenceUpdate_fp.h" 11910Error Returns 11911TPM_RC_MODE 11912 119133 119144 119155 119166 119177 119188 119199 1192010 1192111 1192212 1192313 1192414 1192515 1192616 1192717 1192818 1192919 1193020 1193121 1193222 1193323 1193424 1193525 1193626 1193727 1193828 1193929 1194030 1194131 1194232 1194333 1194434 1194535 1194636 1194737 1194838 1194939 1195040 1195141 1195242 1195343 1195444 1195545 1195646 1195747 1195848 1195949 1196050 1196151 1196252 1196353 11964 11965Meaning 11966sequenceHandle does not reference a hash or HMAC sequence 11967object 11968 11969TPM_RC 11970TPM2_SequenceUpdate( 11971SequenceUpdate_In 11972 11973*in 11974 11975// IN: input parameter list 11976 11977) 11978{ 11979OBJECT 11980 11981*object; 11982 11983// Input Validation 11984// Get sequence object pointer 11985object = ObjectGet(in->sequenceHandle); 11986// Check that referenced object is a sequence object. 11987if(!ObjectIsSequence(object)) 11988return TPM_RC_MODE + RC_SequenceUpdate_sequenceHandle; 11989// Internal Data Update 11990if(object->attributes.eventSeq == SET) 11991{ 11992// Update event sequence object 11993UINT32 11994i; 11995HASH_OBJECT 11996*hashObject = (HASH_OBJECT *)object; 11997for(i = 0; i < HASH_COUNT; i++) 11998{ 11999// Update sequence object 12000CryptUpdateDigest2B(&hashObject->state.hashState[i], &in->buffer.b); 12001} 12002} 12003else 12004{ 12005HASH_OBJECT 12006*hashObject = (HASH_OBJECT *)object; 12007// Update hash/HMAC sequence object 12008if(hashObject->attributes.hashSeq == SET) 12009{ 12010// Is this the first block of the sequence 12011if(hashObject->attributes.firstBlock == CLEAR) 12012{ 12013// If so, indicate that first block was received 12014hashObject->attributes.firstBlock = SET; 12015// Check the first block to see if the first block can contain 12016// the TPM_GENERATED_VALUE. If it does, it is not safe for 12017// a ticket. 12018if(TicketIsSafe(&in->buffer.b)) 12019hashObject->attributes.ticketSafe = SET; 12020} 12021// Update sequence object hash/HMAC stack 12022CryptUpdateDigest2B(&hashObject->state.hashState[0], &in->buffer.b); 12023 12024Family “2.0” 12025Level 00 Revision 00.99 12026 12027Published 12028Copyright © TCG 2006-2013 12029 12030Page 141 12031October 31, 2013 12032 12033 Part 3: Commands 1203454 1203555 1203656 1203757 1203858 1203959 1204060 1204161 1204262 1204363 1204464 1204565 12046 12047Trusted Platform Module Library 12048 12049} 12050else if(object->attributes.hmacSeq == SET) 12051{ 12052HASH_OBJECT 12053*hashObject = (HASH_OBJECT *)object; 12054// Update sequence object hash/HMAC stack 12055CryptUpdateDigest2B(&hashObject->state.hmacState, &in->buffer.b); 12056} 12057} 12058return TPM_RC_SUCCESS; 12059} 12060 12061Page 142 12062October 31, 2013 12063 12064Published 12065Copyright © TCG 2006-2013 12066 12067Family “2.0” 12068Level 00 Revision 00.99 12069 12070 Trusted Platform Module Library 12071 1207219.5 12073 12074Part 3: Commands 12075 12076TPM2_SequenceComplete 12077 1207819.5.1 General Description 12079This command adds the last part of data, if any, to a hash/HMAC sequence and returns the result. 12080NOTE 1 12081 12082This command is not used to complete an Event sequence. TPM2_EventSequenceComplete() is 12083used for that purpose. 12084 12085For a hash sequence, if the results of the hash will be used in a signing operation that uses a restricted 12086signing key, then the ticket returned by this command can indicate that the hash is safe to sign. 12087If the digest is not safe to sign, then validation will be a TPMT_TK_HASHCHECK with the hierarchy set to 12088TPM_RH_NULL and digest set to the Empty Buffer. 12089NOTE 2 12090 12091Regardless of the contents of the first octets of the hashed message, if the first buffer sent to the 12092TPM had fewer than sizeof(TPM_GENERATED) octets, then the TPM will operate as if digest is not 12093safe to sign. 12094 12095If sequenceHandle references an Event sequence, then the TPM shall return TPM_RC_MODE. 12096Proper authorization for the sequence object associated with sequenceHandle is required. If an 12097authorization or audit of this command requires computation of a cpHash and an rpHash, the Name 12098associated with sequenceHandle will be the Empty Buffer. 12099If this command completes successfully, the sequenceHandle object will be flushed. 12100 12101Family “2.0” 12102Level 00 Revision 00.99 12103 12104Published 12105Copyright © TCG 2006-2013 12106 12107Page 143 12108October 31, 2013 12109 12110 Part 3: Commands 12111 12112Trusted Platform Module Library 12113 1211419.5.2 Command and Response 12115Table 73 — TPM2_SequenceComplete Command 12116Type 12117 12118Name 12119 12120Description 12121 12122TPMI_ST_COMMAND_TAG 12123 12124tag 12125 12126UINT32 12127 12128commandSize 12129 12130TPM_CC 12131 12132commandCode 12133 12134TPM_CC_SequenceComplete {F} 12135 12136TPMI_DH_OBJECT 12137 12138@sequenceHandle 12139 12140authorization for the sequence 12141Auth Index: 1 12142Auth Role: USER 12143 12144TPM2B_MAX_BUFFER 12145 12146buffer 12147 12148data to be added to the hash/HMAC 12149 12150TPMI_RH_HIERARCHY+ 12151 12152hierarchy 12153 12154hierarchy of the ticket for a hash 12155 12156Table 74 — TPM2_SequenceComplete Response 12157Type 12158 12159Name 12160 12161Description 12162 12163TPM_ST 12164 12165tag 12166 12167see clause 8 12168 12169UINT32 12170 12171responseSize 12172 12173TPM_RC 12174 12175responseCode 12176 12177TPM2B_DIGEST 12178 12179result 12180 12181the returned HMAC or digest in a sized buffer 12182 12183validation 12184 12185ticket indicating that the sequence of octets used to 12186compute outDigest did not start with 12187TPM_GENERATED_VALUE 12188This is a NULL Ticket when the session is HMAC. 12189 12190TPMT_TK_HASHCHECK 12191 12192Page 144 12193October 31, 2013 12194 12195Published 12196Copyright © TCG 2006-2013 12197 12198Family “2.0” 12199Level 00 Revision 00.99 12200 12201 Trusted Platform Module Library 12202 12203Part 3: Commands 12204 1220519.5.3 Detailed Actions 122061 122072 122083 12209 12210#include "InternalRoutines.h" 12211#include "SequenceComplete_fp.h" 12212#include <Platform.h> 12213Error Returns 12214TPM_RC_TYPE 12215 122164 122175 122186 122197 122208 122219 1222210 1222311 1222412 1222513 1222614 1222715 1222816 1222917 1223018 1223119 1223220 1223321 1223422 1223523 1223624 1223725 1223826 1223927 1224028 1224129 1224230 1224331 1224432 1224533 1224634 1224735 1224836 1224937 1225038 1225139 1225240 1225341 1225442 1225543 1225644 1225745 1225846 1225947 1226048 1226149 1226250 1226351 1226452 1226553 12266 12267Meaning 12268sequenceHandle does not reference a hash or HMAC sequence 12269object 12270 12271TPM_RC 12272TPM2_SequenceComplete( 12273SequenceComplete_In 12274SequenceComplete_Out 12275 12276*in, 12277*out 12278 12279OBJECT 12280 12281// IN: input parameter list 12282// OUT: output parameter list 12283 12284*object; 12285 12286) 12287{ 12288// Input validation 12289// Get hash object pointer 12290object = ObjectGet(in->sequenceHandle); 12291// input handle must be a hash or HMAC sequence object. 12292if( 12293object->attributes.hashSeq == CLEAR 12294&& object->attributes.hmacSeq == CLEAR) 12295return TPM_RC_MODE + RC_SequenceComplete_sequenceHandle; 12296// Command Output 12297if(object->attributes.hashSeq == SET) 12298// sequence object for hash 12299{ 12300// Update last piece of data 12301HASH_OBJECT 12302*hashObject = (HASH_OBJECT *)object; 12303CryptUpdateDigest2B(&hashObject->state.hashState[0], &in->buffer.b); 12304// Complete hash 12305out->result.t.size 12306= CryptGetHashDigestSize( 12307CryptGetContextAlg(&hashObject->state.hashState[0])); 12308CryptCompleteHash2B(&hashObject->state.hashState[0], &out->result.b); 12309// Check if the first block of the sequence has been received 12310if(hashObject->attributes.firstBlock == CLEAR) 12311{ 12312// If not, then this is the first block so see if it is 'safe' 12313// to sign. 12314if(TicketIsSafe(&in->buffer.b)) 12315hashObject->attributes.ticketSafe = SET; 12316} 12317// Output ticket 12318out->validation.tag = TPM_ST_HASHCHECK; 12319out->validation.hierarchy = in->hierarchy; 12320if(in->hierarchy == TPM_RH_NULL) 12321{ 12322// Ticket is not required 12323out->validation.digest.t.size = 0; 12324 12325Family “2.0” 12326Level 00 Revision 00.99 12327 12328Published 12329Copyright © TCG 2006-2013 12330 12331Page 145 12332October 31, 2013 12333 12334 Part 3: Commands 1233554 1233655 1233756 1233857 1233958 1234059 1234160 1234261 1234362 1234463 1234564 1234665 1234766 1234867 1234968 1235069 1235170 1235271 1235372 1235473 1235574 1235675 1235776 1235877 1235978 1236079 1236180 1236281 1236382 1236483 1236584 1236685 1236786 1236887 1236988 1237089 1237190 1237291 1237392 12374 12375Trusted Platform Module Library 12376 12377} 12378else if(object->attributes.ticketSafe == CLEAR) 12379{ 12380// Ticket is not safe to generate 12381out->validation.hierarchy = TPM_RH_NULL; 12382out->validation.digest.t.size = 0; 12383} 12384else 12385{ 12386// Compute ticket 12387TicketComputeHashCheck(out->validation.hierarchy, 12388&out->result, &out->validation); 12389} 12390} 12391else 12392{ 12393HASH_OBJECT 12394 12395*hashObject = (HASH_OBJECT *)object; 12396 12397// 12398Update last piece of data 12399CryptUpdateDigest2B(&hashObject->state.hmacState, &in->buffer.b); 12400// Complete hash/HMAC 12401out->result.t.size = 12402CryptGetHashDigestSize( 12403CryptGetContextAlg(&hashObject->state.hmacState.hashState)); 12404CryptCompleteHMAC2B(&(hashObject->state.hmacState), &out->result.b); 12405// No ticket is generated for HMAC sequence 12406out->validation.tag = TPM_ST_HASHCHECK; 12407out->validation.hierarchy = TPM_RH_NULL; 12408out->validation.digest.t.size = 0; 12409} 12410// Internal Data Update 12411// mark sequence object as evict so it will be flushed on the way out 12412object->attributes.evict = SET; 12413return TPM_RC_SUCCESS; 12414} 12415 12416Page 146 12417October 31, 2013 12418 12419Published 12420Copyright © TCG 2006-2013 12421 12422Family “2.0” 12423Level 00 Revision 00.99 12424 12425 Trusted Platform Module Library 12426 1242719.6 12428 12429Part 3: Commands 12430 12431TPM2_EventSequenceComplete 12432 1243319.6.1 General Description 12434This command adds the last part of data, if any, to an Event sequence and returns the result in a digest 12435list. If pcrHandle references a PCR and not TPM_RH_NULL, then the returned digest list is processed in 12436the same manner as the digest list input parameter to TPM2_PCR_Extend() with the pcrHandle in each 12437bank extended with the associated digest value. 12438If sequenceHandle references a hash or HMAC sequence, the TPM shall return TPM_RC_MODE. 12439Proper authorization for the sequence object associated with sequenceHandle is required. If an 12440authorization or audit of this command requires computation of a cpHash and an rpHash, the Name 12441associated with sequenceHandle will be the Empty Buffer. 12442If this command completes successfully, the sequenceHandle object will be flushed. 12443 12444Family “2.0” 12445Level 00 Revision 00.99 12446 12447Published 12448Copyright © TCG 2006-2013 12449 12450Page 147 12451October 31, 2013 12452 12453 Part 3: Commands 12454 12455Trusted Platform Module Library 12456 1245719.6.2 Command and Response 12458Table 75 — TPM2_EventSequenceComplete Command 12459Type 12460 12461Name 12462 12463TPMI_ST_COMMAND_TAG 12464 12465tag 12466 12467UINT32 12468 12469commandSize 12470 12471TPM_CC 12472 12473commandCode 12474 12475TPM_CC_EventSequenceComplete {NV F} 12476 12477@ pcrHandle 12478 12479PCR to be extended with the Event data 12480Auth Index: 1 12481Auth Role: USER 12482 12483TPMI_DH_OBJECT 12484 12485@sequenceHandle 12486 12487authorization for the sequence 12488Auth Index: 2 12489Auth Role: USER 12490 12491TPM2B_MAX_BUFFER 12492 12493buffer 12494 12495data to be added to the Event 12496 12497TPMI_DH_PCR+ 12498 12499Description 12500 12501Table 76 — TPM2_EventSequenceComplete Response 12502Type 12503 12504Name 12505 12506Description 12507 12508TPM_ST 12509 12510tag 12511 12512see clause 8 12513 12514UINT32 12515 12516responseSize 12517 12518TPM_RC 12519 12520responseCode 12521 12522TPML_DIGEST_VALUES 12523 12524results 12525 12526Page 148 12527October 31, 2013 12528 12529list of digests computed for the PCR 12530 12531Published 12532Copyright © TCG 2006-2013 12533 12534Family “2.0” 12535Level 00 Revision 00.99 12536 12537 Trusted Platform Module Library 12538 12539Part 3: Commands 12540 1254119.6.3 Detailed Actions 125421 125432 12544 12545#include "InternalRoutines.h" 12546#include "EventSequenceComplete_fp.h" 12547Error Returns 12548TPM_RC_LOCALITY 12549 12550PCR extension is not allowed at the current locality 12551 12552TPM_RC_MODE 125533 125544 125555 125566 125577 125588 125599 1256010 1256111 1256212 1256313 1256414 1256515 1256616 1256717 1256818 1256919 1257020 1257121 1257222 1257323 1257424 1257525 1257626 1257727 1257828 1257929 1258030 1258131 1258232 1258333 1258434 1258535 1258636 1258737 1258838 1258939 1259040 1259141 1259242 1259343 1259444 1259545 1259646 1259747 1259848 1259949 1260050 1260151 1260252 1260353 12604 12605Meaning 12606 12607input handle is not a valid event sequence object 12608 12609TPM_RC 12610TPM2_EventSequenceComplete( 12611EventSequenceComplete_In 12612EventSequenceComplete_Out 12613 12614*in, 12615*out 12616 12617// IN: input parameter list 12618// OUT: output parameter list 12619 12620) 12621{ 12622TPM_RC 12623HASH_OBJECT 12624UINT32 12625TPM_ALG_ID 12626 12627result; 12628*hashObject; 12629i; 12630hashAlg; 12631 12632// Input validation 12633// get the event sequence object pointer 12634hashObject = (HASH_OBJECT *)ObjectGet(in->sequenceHandle); 12635// input handle must reference an event sequence object 12636if(hashObject->attributes.eventSeq != SET) 12637return TPM_RC_MODE + RC_EventSequenceComplete_sequenceHandle; 12638// see if a PCR extend is requested in call 12639if(in->pcrHandle != TPM_RH_NULL) 12640{ 12641// see if extend of the PCR is allowed at the locality of the command, 12642if(!PCRIsExtendAllowed(in->pcrHandle)) 12643return TPM_RC_LOCALITY; 12644// if an extend is going to take place, then check to see if there has 12645// been an orderly shutdown. If so, and the selected PCR is one of the 12646// state saved PCR, then the orderly state has to change. The orderly state 12647// does not change for PCR that are not preserved. 12648// NOTE: This doesn't just check for Shutdown(STATE) because the orderly 12649// state will have to change if this is a state-saved PCR regardless 12650// of the current state. This is because a subsequent Shutdown(STATE) will 12651// check to see if there was an orderly shutdown and not do anything if 12652// there was. So, this must indicate that a future Shutdown(STATE) has 12653// something to do. 12654if(gp.orderlyState != SHUTDOWN_NONE && PCRIsStateSaved(in->pcrHandle)) 12655{ 12656result = NvIsAvailable(); 12657if(result != TPM_RC_SUCCESS) return result; 12658g_clearOrderly = TRUE; 12659} 12660} 12661// Command Output 12662out->results.count = 0; 12663for(i = 0; i < HASH_COUNT; i++) 12664{ 12665hashAlg = CryptGetHashAlgByIndex(i); 12666 12667Family “2.0” 12668Level 00 Revision 00.99 12669 12670Published 12671Copyright © TCG 2006-2013 12672 12673Page 149 12674October 31, 2013 12675 12676 Part 3: Commands 1267754 1267855 1267956 1268057 1268158 1268259 1268360 1268461 1268562 1268663 1268764 1268865 1268966 1269067 1269168 1269269 1269370 1269471 1269572 1269673 1269774 1269875 1269976 12700 12701Trusted Platform Module Library 12702 12703// Update last piece of data 12704CryptUpdateDigest2B(&hashObject->state.hashState[i], &in->buffer.b); 12705// Complete hash 12706out->results.digests[out->results.count].hashAlg = hashAlg; 12707CryptCompleteHash(&hashObject->state.hashState[i], 12708CryptGetHashDigestSize(hashAlg), 12709(BYTE *) &out->results.digests[out->results.count].digest); 12710// Extend PCR 12711if(in->pcrHandle != TPM_RH_NULL) 12712PCRExtend(in->pcrHandle, hashAlg, 12713CryptGetHashDigestSize(hashAlg), 12714(BYTE *) &out->results.digests[out->results.count].digest); 12715out->results.count++; 12716} 12717// Internal Data Update 12718// mark sequence object as evict so it will be flushed on the way out 12719hashObject->attributes.evict = SET; 12720return TPM_RC_SUCCESS; 12721} 12722 12723Page 150 12724October 31, 2013 12725 12726Published 12727Copyright © TCG 2006-2013 12728 12729Family “2.0” 12730Level 00 Revision 00.99 12731 12732 Trusted Platform Module Library 12733 12734Part 3: Commands 12735 12736Attestation Commands 12737 1273820 1273920.1 12740 12741Introduction 12742 12743The attestation commands cause the TPM to sign an internally generated data structure. The contents of 12744the data structure vary according to the command. 12745For all signing commands, provisions are made for the caller to provide a scheme to be used for the 12746signing operation. This scheme will be applied only if the scheme of the key is TPM_ALG_NULL. If the 12747scheme for signHandle is not TPM_ALG_NULL, then inScheme.scheme shall be TPM_ALG_NULL or the 12748same as scheme in the public area of the key. If the scheme for signHandle is TPM_ALG_NULL, then 12749inScheme will be used for the signing operation and may not be TPM_ALG_NULL. The TPM shall return 12750TPM_RC_SCHEME to indicate that the scheme is not appropriate. 12751For a signing key that is not restricted, the caller may specify the scheme to be used as long as the 12752scheme is compatible with the family of the key (for example, TPM_ALG_RSAPSS cannot be selected for 12753an ECC key). If the caller sets scheme to TPM_ALG_NULL, then the default scheme of the key is used. 12754If the handle for the signing key (signHandle) is TPM_RH_NULL, then all of the actions of the command 12755are performed and the attestation block is “signed” with the NULL Signature. 12756NOTE 1 12757 12758This mechanism is provided so that additional commands are not required to access the data that 12759might be in an attestation structure. 12760 12761NOTE 2 12762 12763When signHandle is TPM_RH_NULL, scheme is still required to be a valid signing scheme (may be 12764TPM_ALG_NULL), but the scheme will have no effect on the format of the signature. It will always 12765be the NULL Signature. 12766 12767TPM2_NV_Certify() is an attestation command that is documented in 1. The remaining attestation 12768commands are collected in the remainder of this clause. 12769Each of the attestation structures contains a TPMS_CLOCK_INFO structure and a firmware version 12770number. These values may be considered privacy-sensitive, because they would aid in the correlation of 12771attestations by different keys. To provide improved privacy, the resetCount, restartCount, and 12772firmwareVersion numbers are obfuscated when the signing key is not in the Endorsement or Platform 12773hierarchies. 12774The obfuscation value is computed by: 12775 12776obfuscation ≔ KDFa(signHandle→nameAlg, shProof, “OBFUSCATE”, signHandle→QN, 0, 128) (3) 12777Of the returned 128 bits, 64 bits are added to the versionNumber field of the attestation structure; 32 bits 12778are added to the clockInfo.resetCount and 32 bits are added to the clockInfo.restartCount. The order in 12779which the bits are added is implementation-dependent. 12780NOTE 3 12781 12782The obfuscation value for each signing key will be unique to that key in a specific location. That is, 12783each version of a duplicated signing key will have a different obfuscation value. 12784 12785When the signing key is TPM_RH_NULL, the data structure is produced but not signed; and the values in 12786the signed data structure are obfuscated. When computing the obfuscation value for TPM_RH_NULL, the 12787hash used for context integrity is used. 12788NOTE 4 12789 12790The QN for TPM_RH_NULL is TPM_RH_NULL. 12791 12792If the signing scheme of signHandle is an anonymous scheme, then the attestation blocks will not contain 12793the Qualified Name of the signHandle. 12794Each of the attestation structures allows the caller to provide some qualifying data (qualifyingData). For 12795most signing schemes, this value will be placed in the TPMS_ATTEST.extraData parameter that is then 12796 12797Family “2.0” 12798Level 00 Revision 00.99 12799 12800Published 12801Copyright © TCG 2006-2013 12802 12803Page 151 12804October 31, 2013 12805 12806 Part 3: Commands 12807 12808Trusted Platform Module Library 12809 12810hashed and signed. However, for some schemes such as ECDAA, the qualifyingData is used in a 12811different manner (for details, see “ECDAA” in Part 1). 12812 12813Page 152 12814October 31, 2013 12815 12816Published 12817Copyright © TCG 2006-2013 12818 12819Family “2.0” 12820Level 00 Revision 00.99 12821 12822 Trusted Platform Module Library 12823 1282420.2 12825 12826Part 3: Commands 12827 12828TPM2_Certify 12829 1283020.2.1 General Description 12831The purpose of this command is to prove that an object with a specific Name is loaded in the TPM. By 12832certifying 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 12833same Name as a Name certified with this command, then the values in that public area are correct. 12834NOTE 1 12835 12836See 20.1 for description of how the signing scheme is selected. 12837 12838Authorization for objectHandle requires ADMIN role authorization. If performed with a policy session, the 12839session shall have a policySession→commandCode set to TPM_CC_Certify. This indicates that the 12840policy that is being used is a policy that is for certification, and not a policy that would approve another 12841use. That is, authority to use an object does not grant authority to certify the object. 12842The object may be any object that is loaded with TPM2_Load() or TPM2_CreatePrimary(). An object that 12843only has its public area loaded cannot be certified. 12844NOTE 2 12845 12846The restriction occurs because the Name is used to identify the object being certified. If the TPM 12847has not validated that the public area is associated with a matched sensitive area, then the public 12848area may not represent a valid object a nd cannot be certified. 12849 12850The certification includes the Name and Qualified Name of the certified object as well as the Name and 12851the Qualified Name of the certifying object. 12852 12853Family “2.0” 12854Level 00 Revision 00.99 12855 12856Published 12857Copyright © TCG 2006-2013 12858 12859Page 153 12860October 31, 2013 12861 12862 Part 3: Commands 12863 12864Trusted Platform Module Library 12865 1286620.2.2 Command and Response 12867Table 77 — TPM2_Certify Command 12868Type 12869 12870Name 12871 12872TPMI_ST_COMMAND_TAG 12873 12874tag 12875 12876UINT32 12877 12878commandSize 12879 12880TPM_CC 12881 12882commandCode 12883 12884TPM_CC_Certify 12885 12886@objectHandle 12887 12888handle of the object to be certified 12889Auth Index: 1 12890Auth Role: ADMIN 12891 12892TPMI_DH_OBJECT+ 12893 12894@signHandle 12895 12896handle of the key used to sign the attestation structure 12897Auth Index: 2 12898Auth Role: USER 12899 12900TPM2B_DATA 12901 12902qualifyingData 12903 12904user provided qualifying data 12905 12906TPMT_SIG_SCHEME+ 12907 12908inScheme 12909 12910signing scheme to use if the scheme for signHandle is 12911TPM_ALG_NULL 12912 12913TPMI_DH_OBJECT 12914 12915Description 12916 12917Table 78 — TPM2_Certify Response 12918Type 12919 12920Name 12921 12922Description 12923 12924TPM_ST 12925 12926tag 12927 12928see clause 8 12929 12930UINT32 12931 12932responseSize 12933 12934TPM_RC 12935 12936responseCode 12937 12938. 12939 12940TPM2B_ATTEST 12941 12942certifyInfo 12943 12944the structure that was signed 12945 12946TPMT_SIGNATURE 12947 12948signature 12949 12950the asymmetric signature over certifyInfo using the key 12951referenced by signHandle 12952 12953Page 154 12954October 31, 2013 12955 12956Published 12957Copyright © TCG 2006-2013 12958 12959Family “2.0” 12960Level 00 Revision 00.99 12961 12962 Trusted Platform Module Library 12963 12964Part 3: Commands 12965 1296620.2.3 Detailed Actions 129671 129682 129693 12970 12971#include "InternalRoutines.h" 12972#include "Attest_spt_fp.h" 12973#include "Certify_fp.h" 12974Error Returns 12975TPM_RC_KEY 12976 12977key referenced by signHandle is not a signing key 12978 12979TPM_RC_SCHEME 12980 12981inScheme is not compatible with signHandle 12982 12983TPM_RC_VALUE 12984 129854 129865 129876 129887 129898 129909 1299110 1299211 1299312 1299413 1299514 1299615 1299716 1299817 1299918 1300019 1300120 1300221 1300322 1300423 1300524 1300625 1300726 1300827 1300928 1301029 1301130 1301231 1301332 1301433 1301534 1301635 1301736 1301837 1301938 1302039 1302140 1302241 1302342 1302443 1302544 1302645 1302746 1302847 1302948 13030 13031Meaning 13032 13033digest generated for inScheme is greater or has larger size than the 13034modulus of signHandle, or the buffer for the result in signature is too 13035small (for an RSA key); invalid commit status (for an ECC key with a 13036split scheme). 13037 13038TPM_RC 13039TPM2_Certify( 13040Certify_In 13041Certify_Out 13042 13043*in, 13044*out 13045 13046// IN: input parameter list 13047// OUT: output parameter list 13048 13049) 13050{ 13051TPM_RC 13052TPMS_ATTEST 13053 13054result; 13055certifyInfo; 13056 13057// Command Output 13058// Filling in attest information 13059// Common fields 13060result = FillInAttestInfo(in->signHandle, 13061&in->inScheme, 13062&in->qualifyingData, 13063&certifyInfo); 13064if(result != TPM_RC_SUCCESS) 13065{ 13066if(result == TPM_RC_KEY) 13067return TPM_RC_KEY + RC_Certify_signHandle; 13068else 13069return RcSafeAddToResult(result, RC_Certify_inScheme); 13070} 13071// Certify specific fields 13072// Attestation type 13073certifyInfo.type = TPM_ST_ATTEST_CERTIFY; 13074// Certified object name 13075certifyInfo.attested.certify.name.t.size = 13076ObjectGetName(in->objectHandle, 13077&certifyInfo.attested.certify.name.t.name); 13078// Certified object qualified name 13079ObjectGetQualifiedName(in->objectHandle, 13080&certifyInfo.attested.certify.qualifiedName); 13081// Sign attestation structure. A NULL signature will be returned if 13082// signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, 13083// TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned 13084// by SignAttestInfo() 13085result = SignAttestInfo(in->signHandle, 13086&in->inScheme, 13087&certifyInfo, 13088&in->qualifyingData, 13089&out->certifyInfo, 13090 13091Family “2.0” 13092Level 00 Revision 00.99 13093 13094Published 13095Copyright © TCG 2006-2013 13096 13097Page 155 13098October 31, 2013 13099 13100 Part 3: Commands 1310149 1310250 1310351 1310452 1310553 1310654 1310755 1310856 1310957 1311058 1311159 1311260 1311361 1311462 1311563 1311664 13117 13118Trusted Platform Module Library 13119&out->signature); 13120 13121// TPM_RC_ATTRIBUTES cannot be returned here as FillInAttestInfo would already 13122// have returned TPM_RC_KEY 13123pAssert(result != TPM_RC_ATTRIBUTES); 13124if(result != TPM_RC_SUCCESS) 13125return result; 13126// orderly state should be cleared because of the reporting of clock info 13127// if signing happens 13128if(in->signHandle != TPM_RH_NULL) 13129g_clearOrderly = TRUE; 13130return TPM_RC_SUCCESS; 13131} 13132 13133Page 156 13134October 31, 2013 13135 13136Published 13137Copyright © TCG 2006-2013 13138 13139Family “2.0” 13140Level 00 Revision 00.99 13141 13142 Trusted Platform Module Library 13143 1314420.3 13145 13146Part 3: Commands 13147 13148TPM2_CertifyCreation 13149 1315020.3.1 General Description 13151This command is used to prove the association between an object and its creation data. The TPM will 13152validate that the ticket was produced by the TPM and that the ticket validates the association between a 13153loaded public area and the provided hash of the creation data (creationHash). 13154NOTE 1 13155 13156See 20.1 for description of how the signing scheme is selected. 13157 13158The TPM will create a test ticket using the Name associated with objectHandle and creationHash as: 13159 13160HMAC(proof, (TPM_ST_CREATION || objectHandle→Name || creationHash)) 13161 13162(4) 13163 13164This ticket is then compared to creation ticket. If the tickets are not the same, the TPM shall return 13165TPM_RC_TICKET. 13166If the ticket is valid, then the TPM will create a TPMS_ATTEST structure and place creationHash of the 13167command in the creationHash field of the structure. The Name associated with objectHandle will be 13168included in the attestation data that is then signed using the key associated with signHandle. 13169NOTE 2 13170 13171If signHandle is TPM_RH_NULL, the TPMS_ATTEST structure is returned and signature is a NULL 13172Signature. 13173 13174ObjectHandle may be any object that is loaded with TPM2_Load() or TPM2_CreatePrimary(). 13175 13176Family “2.0” 13177Level 00 Revision 00.99 13178 13179Published 13180Copyright © TCG 2006-2013 13181 13182Page 157 13183October 31, 2013 13184 13185 Part 3: Commands 13186 13187Trusted Platform Module Library 13188 1318920.3.2 Command and Response 13190Table 79 — TPM2_CertifyCreation Command 13191Type 13192 13193Name 13194 13195Description 13196 13197TPMI_ST_COMMAND_TAG 13198 13199tag 13200 13201UINT32 13202 13203commandSize 13204 13205TPM_CC 13206 13207commandCode 13208 13209TPM_CC_CertifyCreation 13210 13211TPMI_DH_OBJECT+ 13212 13213@signHandle 13214 13215handle of the key that will sign the attestation block 13216Auth Index: 1 13217Auth Role: USER 13218 13219TPMI_DH_OBJECT 13220 13221objectHandle 13222 13223the object associated with the creation data 13224Auth Index: None 13225 13226TPM2B_DATA 13227 13228qualifyingData 13229 13230user-provided qualifying data 13231 13232TPM2B_DIGEST 13233 13234creationHash 13235 13236hash of the creation data produced by TPM2_Create() 13237or TPM2_CreatePrimary() 13238 13239TPMT_SIG_SCHEME+ 13240 13241inScheme 13242 13243signing scheme to use if the scheme for signHandle is 13244TPM_ALG_NULL 13245 13246TPMT_TK_CREATION 13247 13248creationTicket 13249 13250ticket produced by TPM2_Create() or 13251TPM2_CreatePrimary() 13252 13253Table 80 — TPM2_CertifyCreation Response 13254Type 13255 13256Name 13257 13258Description 13259 13260TPM_ST 13261 13262tag 13263 13264see clause 8 13265 13266UINT32 13267 13268responseSize 13269 13270TPM_RC 13271 13272responseCode 13273 13274TPM2B_ATTEST 13275 13276certifyInfo 13277 13278the structure that was signed 13279 13280TPMT_SIGNATURE 13281 13282signature 13283 13284the signature over certifyInfo 13285 13286Page 158 13287October 31, 2013 13288 13289Published 13290Copyright © TCG 2006-2013 13291 13292Family “2.0” 13293Level 00 Revision 00.99 13294 13295 Trusted Platform Module Library 13296 13297Part 3: Commands 13298 1329920.3.3 Detailed Actions 133001 133012 133023 13303 13304#include "InternalRoutines.h" 13305#include "Attest_spt_fp.h" 13306#include "CertifyCreation_fp.h" 13307Error Returns 13308TPM_RC_KEY 13309 13310key referenced by signHandle is not a signing key 13311 13312TPM_RC_SCHEME 13313 13314inScheme is not compatible with signHandle 13315 13316TPM_RC_TICKET 13317 13318creationTicket does not match objectHandle 13319 13320TPM_RC_VALUE 13321 133224 133235 133246 133257 133268 133279 1332810 1332911 1333012 1333113 1333214 1333315 1333416 1333517 1333618 1333719 1333820 1333921 1334022 1334123 1334224 1334325 1334426 1334527 1334628 1334729 1334830 1334931 1335032 1335133 1335234 1335335 1335436 1335537 1335638 1335739 1335840 1335941 1336042 1336143 1336244 1336345 1336446 13365 13366Meaning 13367 13368digest generated for inScheme is greater or has larger size than the 13369modulus of signHandle, or the buffer for the result in signature is too 13370small (for an RSA key); invalid commit status (for an ECC key with a 13371split scheme). 13372 13373TPM_RC 13374TPM2_CertifyCreation( 13375CertifyCreation_In 13376CertifyCreation_Out 13377 13378*in, 13379*out 13380 13381// IN: input parameter list 13382// OUT: output parameter list 13383 13384) 13385{ 13386TPM_RC 13387TPM2B_NAME 13388TPMT_TK_CREATION 13389TPMS_ATTEST 13390 13391result; 13392name; 13393ticket; 13394certifyInfo; 13395 13396// Input Validation 13397// CertifyCreation specific input validation 13398// Get certified object name 13399name.t.size = ObjectGetName(in->objectHandle, &name.t.name); 13400// Re-compute ticket 13401TicketComputeCreation(in->creationTicket.hierarchy, &name, 13402&in->creationHash, &ticket); 13403// Compare ticket 13404if(!Memory2BEqual(&ticket.digest.b, &in->creationTicket.digest.b)) 13405return TPM_RC_TICKET + RC_CertifyCreation_creationTicket; 13406// Command Output 13407// Common fields 13408result = FillInAttestInfo(in->signHandle, &in->inScheme, &in->qualifyingData, 13409&certifyInfo); 13410if(result != TPM_RC_SUCCESS) 13411{ 13412if(result == TPM_RC_KEY) 13413return TPM_RC_KEY + RC_CertifyCreation_signHandle; 13414else 13415return RcSafeAddToResult(result, RC_CertifyCreation_inScheme); 13416} 13417// CertifyCreation specific fields 13418// Attestation type 13419certifyInfo.type = TPM_ST_ATTEST_CREATION; 13420certifyInfo.attested.creation.objectName = name; 13421// Copy the creationHash 13422certifyInfo.attested.creation.creationHash = in->creationHash; 13423 13424Family “2.0” 13425Level 00 Revision 00.99 13426 13427Published 13428Copyright © TCG 2006-2013 13429 13430Page 159 13431October 31, 2013 13432 13433 Part 3: Commands 1343447 1343548 1343649 1343750 1343851 1343952 1344053 1344154 1344255 1344356 1344457 1344558 1344659 1344760 1344861 1344962 1345063 1345164 1345265 1345366 1345467 1345568 1345669 1345770 1345871 13459 13460Trusted Platform Module Library 13461 13462// Sign attestation structure. A NULL signature will be returned if 13463// signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, 13464// TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at 13465// this point 13466result = SignAttestInfo(in->signHandle, 13467&in->inScheme, 13468&certifyInfo, 13469&in->qualifyingData, 13470&out->certifyInfo, 13471&out->signature); 13472// TPM_RC_ATTRIBUTES cannot be returned here as FillInAttestInfo would already 13473// have returned TPM_RC_KEY 13474pAssert(result != TPM_RC_ATTRIBUTES); 13475if(result != TPM_RC_SUCCESS) 13476return result; 13477// orderly state should be cleared because of the reporting of clock info 13478// if signing happens 13479if(in->signHandle != TPM_RH_NULL) 13480g_clearOrderly = TRUE; 13481return TPM_RC_SUCCESS; 13482} 13483 13484Page 160 13485October 31, 2013 13486 13487Published 13488Copyright © TCG 2006-2013 13489 13490Family “2.0” 13491Level 00 Revision 00.99 13492 13493 Trusted Platform Module Library 13494 1349520.4 13496 13497Part 3: Commands 13498 13499TPM2_Quote 13500 1350120.4.1 General Description 13502This command is used to quote PCR values. 13503NOTE 13504 13505See 20.1 for description of how the signing scheme is selected. 13506 13507The TPM will hash the list of PCR selected by PCRselect using the hash algorithm associated with 13508signHandle (this is the hash algorithm of the signing scheme, not the nameAlg of signHandle). 13509The digest is computed as the hash of the concatenation of all of the digest values of the selected PCR. 13510The concatenation of PCR is described in Part 1, Selecting Multiple PCR. 13511 13512Family “2.0” 13513Level 00 Revision 00.99 13514 13515Published 13516Copyright © TCG 2006-2013 13517 13518Page 161 13519October 31, 2013 13520 13521 Part 3: Commands 13522 13523Trusted Platform Module Library 13524 1352520.4.2 Command and Response 13526Table 81 — TPM2_Quote Command 13527Type 13528 13529Name 13530 13531Description 13532 13533TPMI_ST_COMMAND_TAG 13534 13535tag 13536 13537UINT32 13538 13539commandSize 13540 13541TPM_CC 13542 13543commandCode 13544 13545TPM_CC_Quote 13546 13547TPMI_DH_OBJECT 13548 13549@signHandle 13550 13551handle of key that will perform signature 13552Auth Index: 1 13553Auth Role: USER 13554 13555TPM2B_DATA 13556 13557qualifyingData 13558 13559data supplied by the caller 13560 13561TPMT_SIG_SCHEME+ 13562 13563inScheme 13564 13565signing scheme to use if the scheme for signHandle is 13566TPM_ALG_NULL 13567 13568TPML_PCR_SELECTION 13569 13570PCRselect 13571 13572PCR set to quote 13573 13574Table 82 — TPM2_Quote Response 13575Type 13576 13577Name 13578 13579Description 13580 13581TPM_ST 13582 13583tag 13584 13585see clause 8 13586 13587UINT32 13588 13589responseSize 13590 13591TPM_RC 13592 13593responseCode 13594 13595TPM2B_ATTEST 13596 13597quoted 13598 13599the quoted information 13600 13601TPMT_SIGNATURE 13602 13603signature 13604 13605the signature over quoted 13606 13607Page 162 13608October 31, 2013 13609 13610Published 13611Copyright © TCG 2006-2013 13612 13613Family “2.0” 13614Level 00 Revision 00.99 13615 13616 Trusted Platform Module Library 13617 13618Part 3: Commands 13619 1362020.4.3 Detailed Actions 136211 136222 136233 13624 13625#include "InternalRoutines.h" 13626#include "Attest_spt_fp.h" 13627#include "Quote_fp.h" 13628Error Returns 13629TPM_RC_KEY 13630 13631signHandle does not reference a signing key; 13632 13633TPM_RC_SCHEME 13634 136354 136365 136376 136387 136398 136409 1364110 1364211 1364312 1364413 1364514 1364615 1364716 1364817 1364918 1365019 1365120 1365221 1365322 1365423 1365524 1365625 1365726 1365827 1365928 1366029 1366130 1366231 1366332 1366433 1366534 1366635 1366736 1366837 1366938 1367039 1367140 1367241 1367342 1367443 1367544 1367645 1367746 1367847 1367948 1368049 1368150 1368251 13683 13684Meaning 13685 13686the scheme is not compatible with sign key type, or input scheme is 13687not compatible with default scheme, or the chosen scheme is not a 13688valid sign scheme 13689 13690TPM_RC 13691TPM2_Quote( 13692Quote_In 13693Quote_Out 13694 13695*in, 13696*out 13697 13698// IN: input parameter list 13699// OUT: output parameter list 13700 13701) 13702{ 13703TPM_RC 13704TPMI_ALG_HASH 13705TPMS_ATTEST 13706 13707result; 13708hashAlg; 13709quoted; 13710 13711// Command Output 13712// Filling in attest information 13713// Common fields 13714// FillInAttestInfo will return TPM_RC_SCHEME or TPM_RC_KEY 13715result = FillInAttestInfo(in->signHandle, 13716&in->inScheme, 13717&in->qualifyingData, 13718"ed); 13719if(result != TPM_RC_SUCCESS) 13720{ 13721if(result == TPM_RC_KEY) 13722return TPM_RC_KEY + RC_Quote_signHandle; 13723else 13724return RcSafeAddToResult(result, RC_Quote_inScheme); 13725} 13726// Quote specific fields 13727// Attestation type 13728quoted.type = TPM_ST_ATTEST_QUOTE; 13729// Get hash algorithm in sign scheme. This hash algorithm is used to 13730// compute PCR digest. If there is no algorithm, then the PCR cannot 13731// be digested and this command returns TPM_RC_SCHEME 13732hashAlg = in->inScheme.details.any.hashAlg; 13733if(hashAlg == TPM_ALG_NULL) 13734return TPM_RC_SCHEME + RC_Quote_inScheme; 13735// Compute PCR digest 13736PCRComputeCurrentDigest(hashAlg, 13737&in->PCRselect, 13738"ed.attested.quote.pcrDigest); 13739// Copy PCR select. "PCRselect" is modified in PCRComputeCurrentDigest 13740// function 13741quoted.attested.quote.pcrSelect = in->PCRselect; 13742 13743Family “2.0” 13744Level 00 Revision 00.99 13745 13746Published 13747Copyright © TCG 2006-2013 13748 13749Page 163 13750October 31, 2013 13751 13752 Part 3: Commands 1375352 1375453 1375554 1375655 1375756 1375857 1375958 1376059 1376160 1376261 1376362 1376463 1376564 1376665 1376766 1376867 1376968 1377069 1377170 1377271 1377372 1377473 1377574 13776 13777Trusted Platform Module Library 13778 13779// Sign attestation structure. A NULL signature will be returned if 13780// signHandle is TPM_RH_NULL. TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES 13781// error may be returned by SignAttestInfo. 13782// NOTE: TPM_RC_ATTRIBUTES means that the key is not a signing key but that 13783// was checked above and TPM_RC_KEY was returned. TPM_RC_VALUE means that the 13784// value to sign is too large but that means that the digest is too big and 13785// that can't happen. 13786result = SignAttestInfo(in->signHandle, 13787&in->inScheme, 13788"ed, 13789&in->qualifyingData, 13790&out->quoted, 13791&out->signature); 13792if(result != TPM_RC_SUCCESS) 13793return result; 13794// orderly state should be cleared because of the reporting of clock info 13795// if signing happens 13796if(in->signHandle != TPM_RH_NULL) 13797g_clearOrderly = TRUE; 13798return TPM_RC_SUCCESS; 13799} 13800 13801Page 164 13802October 31, 2013 13803 13804Published 13805Copyright © TCG 2006-2013 13806 13807Family “2.0” 13808Level 00 Revision 00.99 13809 13810 Trusted Platform Module Library 13811 1381220.5 13813 13814Part 3: Commands 13815 13816TPM2_GetSessionAuditDigest 13817 1381820.5.1 General Description 13819This command returns a digital signature of the audit session digest. 13820NOTE 1 13821 13822See 20.1 for description of how the signing scheme is selected. 13823 13824If sessionHandle is not an audit session, the TPM shall return TPM_RC_TYPE. 13825NOTE 2 13826 13827A session does not become an audit session until the successful completion of the command in 13828which the session is first used as an audit session. 13829 13830This command requires authorization from the privacy administrator of the TPM (expressed with 13831endorsementAuth) as well as authorization to use the key associated with signHandle. 13832If this command is audited, then the audit digest that is signed will not include the digest of this command 13833because the audit digest is only updated when the command completes successfully. 13834This command does not cause the audit session to be closed and does not reset the digest value. 13835NOTE 3 13836 13837The audit session digest will be reset if the sessionHandle is used as the audit session for the 13838command and the auditReset attribute of the session is set; and this command will be the first 13839command in the audit digest. 13840 13841NOTE 4 13842 13843A reason for using 'sessionHahdle' in this command is so that the continueSession attribute may be 13844CLEAR. This will flush the session at the end of the command. 13845 13846Family “2.0” 13847Level 00 Revision 00.99 13848 13849Published 13850Copyright © TCG 2006-2013 13851 13852Page 165 13853October 31, 2013 13854 13855 Part 3: Commands 13856 13857Trusted Platform Module Library 13858 1385920.5.2 Command and Response 13860Table 83 — TPM2_GetSessionAuditDigest Command 13861Type 13862 13863Name 13864 13865TPMI_ST_COMMAND_TAG 13866 13867tag 13868 13869UINT32 13870 13871commandSize 13872 13873TPM_CC 13874 13875commandCode 13876 13877TPM_CC_GetSessionAuditDigest 13878 13879@privacyAdminHandle 13880 13881handle of the privacy administrator 13882(TPM_RH_ENDORSEMENT) 13883Auth Index: 1 13884Auth Role: USER 13885 13886TPMI_DH_OBJECT+ 13887 13888@signHandle 13889 13890handle of the signing key 13891Auth Index: 2 13892Auth Role: USER 13893 13894TPMI_SH_HMAC 13895 13896sessionHandle 13897 13898handle of the audit session 13899Auth Index: None 13900 13901TPM2B_DATA 13902 13903qualifyingData 13904 13905user-provided qualifying data – may be zero-length 13906 13907TPMT_SIG_SCHEME+ 13908 13909inScheme 13910 13911signing scheme to use if the scheme for signHandle is 13912TPM_ALG_NULL 13913 13914TPMI_RH_ENDORSEMENT 13915 13916Description 13917 13918Table 84 — TPM2_GetSessionAuditDigest Response 13919Type 13920 13921Name 13922 13923Description 13924 13925TPM_ST 13926 13927tag 13928 13929see clause 8 13930 13931UINT32 13932 13933responseSize 13934 13935TPM_RC 13936 13937responseCode 13938 13939TPM2B_ATTEST 13940 13941auditInfo 13942 13943the audit information that was signed 13944 13945TPMT_SIGNATURE 13946 13947signature 13948 13949the signature over auditInfo 13950 13951Page 166 13952October 31, 2013 13953 13954Published 13955Copyright © TCG 2006-2013 13956 13957Family “2.0” 13958Level 00 Revision 00.99 13959 13960 Trusted Platform Module Library 13961 13962Part 3: Commands 13963 1396420.5.3 Detailed Actions 139651 139662 139673 13968 13969#include "InternalRoutines.h" 13970#include "Attest_spt_fp.h" 13971#include "GetSessionAuditDigest_fp.h" 13972Error Returns 13973TPM_RC_KEY 13974 13975key referenced by signHandle is not a signing key 13976 13977TPM_RC_SCHEME 13978 13979inScheme is incompatible with signHandle type; or both scheme and 13980key's default scheme are empty; or scheme is empty while key's 13981default scheme requires explicit input scheme (split signing); or nonempty default key scheme differs from scheme 13982 13983TPM_RC_TYPE 13984 13985sessionHandle does not reference an audit session 13986 13987TPM_RC_VALUE 13988 139894 139905 139916 139927 139938 139949 1399510 1399611 1399712 1399813 1399914 1400015 1400116 1400217 1400318 1400419 1400520 1400621 1400722 1400823 1400924 1401025 1401126 1401227 1401328 1401429 1401530 1401631 1401732 1401833 1401934 1402035 1402136 1402237 1402338 1402439 1402540 1402641 1402742 1402843 1402944 14030 14031Meaning 14032 14033digest generated for the given scheme is greater than the modulus of 14034signHandle (for an RSA key); invalid commit status or failed to 14035generate r value (for an ECC key) 14036 14037TPM_RC 14038TPM2_GetSessionAuditDigest( 14039GetSessionAuditDigest_In 14040GetSessionAuditDigest_Out 14041 14042*in, 14043*out 14044 14045// IN: input parameter list 14046// OUT: output parameter list 14047 14048) 14049{ 14050TPM_RC 14051SESSION 14052TPMS_ATTEST 14053 14054result; 14055*session; 14056auditInfo; 14057 14058// Input Validation 14059// SessionAuditDigest specific input validation 14060// Get session pointer 14061session = SessionGet(in->sessionHandle); 14062// session must be an audit session 14063if(session->attributes.isAudit == CLEAR) 14064return TPM_RC_TYPE + RC_GetSessionAuditDigest_sessionHandle; 14065// Command Output 14066// Filling in attest information 14067// Common fields 14068result = FillInAttestInfo(in->signHandle, 14069&in->inScheme, 14070&in->qualifyingData, 14071&auditInfo); 14072if(result != TPM_RC_SUCCESS) 14073{ 14074if(result == TPM_RC_KEY) 14075return TPM_RC_KEY + RC_GetSessionAuditDigest_signHandle; 14076else 14077return RcSafeAddToResult(result, RC_GetSessionAuditDigest_inScheme); 14078} 14079// SessionAuditDigest specific fields 14080// Attestation type 14081auditInfo.type = TPM_ST_ATTEST_SESSION_AUDIT; 14082// Copy digest 14083 14084Family “2.0” 14085Level 00 Revision 00.99 14086 14087Published 14088Copyright © TCG 2006-2013 14089 14090Page 167 14091October 31, 2013 14092 14093 Part 3: Commands 1409445 1409546 1409647 1409748 1409849 1409950 1410051 1410152 1410253 1410354 1410455 1410556 1410657 1410758 1410859 1410960 1411061 1411162 1411263 1411364 1411465 1411566 1411667 1411768 1411869 1411970 1412071 1412172 14122 14123Trusted Platform Module Library 14124 14125auditInfo.attested.sessionAudit.sessionDigest = session->u2.auditDigest; 14126// Exclusive audit session 14127if(g_exclusiveAuditSession == in->sessionHandle) 14128auditInfo.attested.sessionAudit.exclusiveSession = TRUE; 14129else 14130auditInfo.attested.sessionAudit.exclusiveSession = FALSE; 14131// Sign attestation structure. A NULL signature will be returned if 14132// signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, 14133// TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at 14134// this point 14135result = SignAttestInfo(in->signHandle, 14136&in->inScheme, 14137&auditInfo, 14138&in->qualifyingData, 14139&out->auditInfo, 14140&out->signature); 14141if(result != TPM_RC_SUCCESS) 14142return result; 14143// orderly state should be cleared because of the reporting of clock info 14144// if signing happens 14145if(in->signHandle != TPM_RH_NULL) 14146g_clearOrderly = TRUE; 14147return TPM_RC_SUCCESS; 14148} 14149 14150Page 168 14151October 31, 2013 14152 14153Published 14154Copyright © TCG 2006-2013 14155 14156Family “2.0” 14157Level 00 Revision 00.99 14158 14159 Trusted Platform Module Library 14160 1416120.6 14162 14163Part 3: Commands 14164 14165TPM2_GetCommandAuditDigest 14166 1416720.6.1 General Description 14168This command returns the current value of the command audit digest, a digest of the commands being 14169audited, and the audit hash algorithm. These values are placed in an attestation structure and signed with 14170the key referenced by signHandle. 14171NOTE 1 14172 14173See 20.1 for description of how the signing scheme is selected. 14174 14175When this command completes successfully, and signHandle is not TPM_RH_NULL, the audit digest is 14176cleared. 14177NOTE 2 14178 14179The way that the TPM tracks that the digest is clear is vendor -dependent. The reference 14180implementation resets the size of the digest to zero. 14181 14182If this command is being audited, then the signed digest produced by the command will not include the 14183command. At the end of this command, the audit digest will be extended with cpHash and the rpHash of 14184the command which would change the command audit digest signed by the next invocation of this 14185command. 14186This command requires authorization from the privacy administrator of the TPM (expressed with 14187endorsementAuth) as well as authorization to use the key associated with signHandle. 14188 14189Family “2.0” 14190Level 00 Revision 00.99 14191 14192Published 14193Copyright © TCG 2006-2013 14194 14195Page 169 14196October 31, 2013 14197 14198 Part 3: Commands 14199 14200Trusted Platform Module Library 14201 1420220.6.2 Command and Response 14203Table 85 — TPM2_GetCommandAuditDigest Command 14204Type 14205 14206Name 14207 14208Description 14209 14210TPMI_ST_COMMAND_TAG 14211 14212tag 14213 14214UINT32 14215 14216commandSize 14217 14218TPM_CC 14219 14220commandCode 14221 14222TPM_CC_GetCommandAuditDigest {NV} 14223 14224TPMI_RH_ENDORSEMENT 14225 14226@privacyHandle 14227 14228handle of the privacy administrator 14229(TPM_RH_ENDORSEMENT) 14230Auth Index: 1 14231Auth Role: USER 14232 14233TPMI_DH_OBJECT+ 14234 14235@signHandle 14236 14237the handle of the signing key 14238Auth Index: 2 14239Auth Role: USER 14240 14241TPM2B_DATA 14242 14243qualifyingData 14244 14245other data to associate with this audit digest 14246 14247TPMT_SIG_SCHEME+ 14248 14249inScheme 14250 14251signing scheme to use if the scheme for signHandle is 14252TPM_ALG_NULL 14253 14254Table 86 — TPM2_GetCommandAuditDigest Response 14255Type 14256 14257Name 14258 14259Description 14260 14261TPM_ST 14262 14263tag 14264 14265see clause 8 14266 14267UINT32 14268 14269responseSize 14270 14271TPM_RC 14272 14273responseCode 14274 14275TPM2B_ATTEST 14276 14277auditInfo 14278 14279the auditInfo that was signed 14280 14281TPMT_SIGNATURE 14282 14283signature 14284 14285the signature over auditInfo 14286 14287Page 170 14288October 31, 2013 14289 14290Published 14291Copyright © TCG 2006-2013 14292 14293Family “2.0” 14294Level 00 Revision 00.99 14295 14296 Trusted Platform Module Library 14297 14298Part 3: Commands 14299 1430020.6.3 Detailed Actions 143011 143022 143033 14304 14305#include "InternalRoutines.h" 14306#include "Attest_spt_fp.h" 14307#include "GetCommandAuditDigest_fp.h" 14308Error Returns 14309TPM_RC_KEY 14310 14311key referenced by signHandle is not a signing key 14312 14313TPM_RC_SCHEME 14314 14315inScheme is incompatible with signHandle type; or both scheme and 14316key's default scheme are empty; or scheme is empty while key's 14317default scheme requires explicit input scheme (split signing); or nonempty default key scheme differs from scheme 14318 14319TPM_RC_VALUE 14320 143214 143225 143236 143247 143258 143269 1432710 1432811 1432912 1433013 1433114 1433215 1433316 1433417 1433518 1433619 1433720 1433821 1433922 1434023 1434124 1434225 1434326 1434427 1434528 1434629 1434730 1434831 1434932 1435033 1435134 1435235 1435336 1435437 1435538 1435639 1435740 1435841 1435942 1436043 1436144 1436245 1436346 14364 14365Meaning 14366 14367digest generated for the given scheme is greater than the modulus of 14368signHandle (for an RSA key); invalid commit status or failed to 14369generate r value (for an ECC key) 14370 14371TPM_RC 14372TPM2_GetCommandAuditDigest( 14373GetCommandAuditDigest_In 14374GetCommandAuditDigest_Out 14375 14376*in, 14377*out 14378 14379// IN: input parameter list 14380// OUT: output parameter list 14381 14382) 14383{ 14384TPM_RC 14385TPMS_ATTEST 14386 14387result; 14388auditInfo; 14389 14390// Command Output 14391// Filling in attest information 14392// Common fields 14393result = FillInAttestInfo(in->signHandle, 14394&in->inScheme, 14395&in->qualifyingData, 14396&auditInfo); 14397if(result != TPM_RC_SUCCESS) 14398{ 14399if(result == TPM_RC_KEY) 14400return TPM_RC_KEY + RC_GetCommandAuditDigest_signHandle; 14401else 14402return RcSafeAddToResult(result, RC_GetCommandAuditDigest_inScheme); 14403} 14404// CommandAuditDigest specific fields 14405// Attestation type 14406auditInfo.type = TPM_ST_ATTEST_COMMAND_AUDIT; 14407// Copy audit hash algorithm 14408auditInfo.attested.commandAudit.digestAlg = gp.auditHashAlg; 14409// Copy counter value 14410auditInfo.attested.commandAudit.auditCounter = gp.auditCounter; 14411// Copy command audit log 14412auditInfo.attested.commandAudit.auditDigest = gr.commandAuditDigest; 14413CommandAuditGetDigest(&auditInfo.attested.commandAudit.commandDigest); 14414// 14415// 14416// 14417// 14418 14419Sign attestation structure. A NULL signature will be returned if 14420signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, 14421TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at 14422this point 14423 14424Family “2.0” 14425Level 00 Revision 00.99 14426 14427Published 14428Copyright © TCG 2006-2013 14429 14430Page 171 14431October 31, 2013 14432 14433 Part 3: Commands 1443447 1443548 1443649 1443750 1443851 1443952 1444053 1444154 1444255 1444356 1444457 1444558 1444659 1444760 1444861 1444962 1445063 1445164 1445265 1445366 1445467 1445568 1445669 1445770 14458 14459Trusted Platform Module Library 14460 14461result = SignAttestInfo(in->signHandle, 14462&in->inScheme, 14463&auditInfo, 14464&in->qualifyingData, 14465&out->auditInfo, 14466&out->signature); 14467if(result != TPM_RC_SUCCESS) 14468return result; 14469// Internal Data Update 14470if(in->signHandle != TPM_RH_NULL) 14471{ 14472// Reset log 14473gr.commandAuditDigest.t.size = 0; 14474// orderly state should be cleared because of the update in 14475// commandAuditDigest, as well as the reporting of clock info 14476g_clearOrderly = TRUE; 14477} 14478return TPM_RC_SUCCESS; 14479} 14480 14481Page 172 14482October 31, 2013 14483 14484Published 14485Copyright © TCG 2006-2013 14486 14487Family “2.0” 14488Level 00 Revision 00.99 14489 14490 Trusted Platform Module Library 14491 1449220.7 14493 14494Part 3: Commands 14495 14496TPM2_GetTime 14497 1449820.7.1 General Description 14499This command returns the current values of Time and Clock. 14500NOTE 1 14501 14502See 20.1 for description of how the signing scheme is selected. 14503 14504The values of Clock, resetCount and restartCount appear in two places in timeInfo: once in 14505TPMS_ATTEST.clockInfo and again in TPMS_ATTEST.attested.time.clockInfo. The firmware version 14506number 14507also 14508appears 14509in 14510two 14511places 14512(TPMS_ATTEST.firmwareVersion 14513and 14514TPMS_ATTEST.attested.time.firmwareVersion). If signHandle is in the endorsement or platform 14515hierarchies, both copies of the data will be the same. However, if signHandle is in the storage hierarchy or 14516is TPM_RH_NULL, the values in TPMS_ATTEST.clockInfo and TPMS_ATTEST.firmwareVersion are 14517obfuscated but the values in TPM_ATTEST.attested.time are not. 14518NOTE 2 14519 14520The purpose of this duplication is to allow an entity who is trusted by the privacy Administrator to 14521correlate the obfuscated values with the clear -text values. 14522 14523Family “2.0” 14524Level 00 Revision 00.99 14525 14526Published 14527Copyright © TCG 2006-2013 14528 14529Page 173 14530October 31, 2013 14531 14532 Part 3: Commands 14533 14534Trusted Platform Module Library 14535 1453620.7.2 Command and Response 14537Table 87 — TPM2_GetTime Command 14538Type 14539 14540Name 14541 14542TPMI_ST_COMMAND_TAG 14543 14544tag 14545 14546UINT32 14547 14548commandSize 14549 14550TPM_CC 14551 14552commandCode 14553 14554TPM_CC_GetTime 14555 14556@privacyAdminHandle 14557 14558handle of the privacy administrator 14559(TPM_RH_ENDORSEMENT) 14560Auth Index: 1 14561Auth Role: USER 14562 14563TPMI_DH_OBJECT+ 14564 14565@signHandle 14566 14567the keyHandle identifier of a loaded key that can 14568perform digital signatures 14569Auth Index: 2 14570Auth Role: USER 14571 14572TPM2B_DATA 14573 14574qualifyingData 14575 14576data to tick stamp 14577 14578TPMT_SIG_SCHEME+ 14579 14580inScheme 14581 14582signing scheme to use if the scheme for signHandle is 14583TPM_ALG_NULL 14584 14585TPMI_RH_ENDORSEMENT 14586 14587Description 14588 14589Table 88 — TPM2_GetTime Response 14590Type 14591 14592Name 14593 14594Description 14595 14596TPM_ST 14597 14598tag 14599 14600see clause 8 14601 14602UINT32 14603 14604responseSize 14605 14606TPM_RC 14607 14608responseCode 14609 14610. 14611 14612TPM2B_ATTEST 14613 14614timeInfo 14615 14616standard TPM-generated attestation block 14617 14618TPMT_SIGNATURE 14619 14620signature 14621 14622the signature over timeInfo 14623 14624Page 174 14625October 31, 2013 14626 14627Published 14628Copyright © TCG 2006-2013 14629 14630Family “2.0” 14631Level 00 Revision 00.99 14632 14633 Trusted Platform Module Library 14634 14635Part 3: Commands 14636 1463720.7.3 Detailed Actions 146381 146392 146403 14641 14642#include "InternalRoutines.h" 14643#include "Attest_spt_fp.h" 14644#include "GetTime_fp.h" 14645Error Returns 14646TPM_RC_KEY 14647 14648key referenced by signHandle is not a signing key 14649 14650TPM_RC_SCHEME 14651 14652inScheme is incompatible with signHandle type; or both scheme and 14653key's default scheme are empty; or scheme is empty while key's 14654default scheme requires explicit input scheme (split signing); or nonempty default key scheme differs from scheme 14655 14656TPM_RC_VALUE 14657 146584 146595 146606 146617 146628 146639 1466410 1466511 1466612 1466713 1466814 1466915 1467016 1467117 1467218 1467319 1467420 1467521 1467622 1467723 1467824 1467925 1468026 1468127 1468228 1468329 1468430 1468531 1468632 1468733 1468834 1468935 1469036 1469137 1469238 1469339 1469440 1469541 1469642 1469743 1469844 1469945 1470046 14701 14702Meaning 14703 14704digest generated for the given scheme is greater than the modulus of 14705signHandle (for an RSA key); invalid commit status or failed to 14706generate r value (for an ECC key) 14707 14708TPM_RC 14709TPM2_GetTime( 14710GetTime_In 14711GetTime_Out 14712 14713*in, 14714*out 14715 14716// IN: input parameter list 14717// OUT: output parameter list 14718 14719) 14720{ 14721TPM_RC 14722TPMS_ATTEST 14723 14724result; 14725timeInfo; 14726 14727// Command Output 14728// Filling in attest information 14729// Common fields 14730result = FillInAttestInfo(in->signHandle, 14731&in->inScheme, 14732&in->qualifyingData, 14733&timeInfo); 14734if(result != TPM_RC_SUCCESS) 14735{ 14736if(result == TPM_RC_KEY) 14737return TPM_RC_KEY + RC_GetTime_signHandle; 14738else 14739return RcSafeAddToResult(result, RC_GetTime_inScheme); 14740} 14741// GetClock specific fields 14742// Attestation type 14743timeInfo.type = TPM_ST_ATTEST_TIME; 14744// current clock in plain text 14745timeInfo.attested.time.time.time = g_time; 14746TimeFillInfo(&timeInfo.attested.time.time.clockInfo); 14747// Firmware version in plain text 14748timeInfo.attested.time.firmwareVersion 14749= ((UINT64) gp.firmwareV1) << 32; 14750timeInfo.attested.time.firmwareVersion += gp.firmwareV2; 14751// Sign attestation structure. A NULL signature will be returned if 14752// signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, 14753// TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at 14754// this point 14755result = SignAttestInfo(in->signHandle, 14756 14757Family “2.0” 14758Level 00 Revision 00.99 14759 14760Published 14761Copyright © TCG 2006-2013 14762 14763Page 175 14764October 31, 2013 14765 14766 Part 3: Commands 1476747 1476848 1476949 1477050 1477151 1477252 1477353 1477454 1477555 1477656 1477757 1477858 1477959 1478060 1478161 14782 14783Trusted Platform Module Library 14784 14785&in->inScheme, 14786&timeInfo, 14787&in->qualifyingData, 14788&out->timeInfo, 14789&out->signature); 14790if(result != TPM_RC_SUCCESS) 14791return result; 14792// orderly state should be cleared because of the reporting of clock info 14793// if signing happens 14794if(in->signHandle != TPM_RH_NULL) 14795g_clearOrderly = TRUE; 14796return TPM_RC_SUCCESS; 14797} 14798 14799Page 176 14800October 31, 2013 14801 14802Published 14803Copyright © TCG 2006-2013 14804 14805Family “2.0” 14806Level 00 Revision 00.99 14807 14808 Trusted Platform Module Library 14809 1481021 14811 14812Part 3: Commands 14813 14814Ephemeral EC Keys 14815 1481621.1 14817 14818Introduction 14819 14820The TPM generates keys that have different lifetimes. TPM keys in a hierarchy can be persistent for as 14821long 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 14822command in which they are created. Examples of this use are TPM2_Duplicate() where an ephemeral 14823key is created for a single pass key exchange with another TPM. However, there are other cases, such 14824as anonymous attestation, where the protocol requires two passes where the public part of the ephemeral 14825key is used outside of the TPM before the final command "consumes" the ephemeral key. 14826For these uses, TPM2_Commit() or TPM2_EC_Ephemeral() may be used to have the TPM create an 14827ephemeral EC key and return the public part of the key for external use. Then in a subsequent command, 14828the caller provides a reference to the ephemeral key so that the TPM can retrieve or recreate the 14829associated private key. 14830When an ephemeral EC key is created, it is assigned a number and that number is returned to the caller 14831as the identifier for the key. This number is not a handle. A handle is assigned to a key that may be 14832context saved but these ephemeral EC keys may not be saved and do not have a full key context. When 14833a subsequent command uses the ephemeral key, the caller provides the number of the ephemeral key. 14834The TPM uses that number to either look up or recompute the associated private key. After the key is 14835used, the TPM records the fact that the key has been used so that it cannot be used again. 14836As mentioned, the TPM can keep each assigned private ephemeral key in memory until it is used. 14837However, this could consume a large amount of memory. To limit the memory size, the TPM is allowed to 14838restrict the number of pending private keys – keys that have been allocated but not used. 14839NOTE 14840 14841The minimum number of ephemeral keys is determined by a platform specific specification 14842 14843To further reduce the memory requirements for the ephemeral private keys, the TPM is allowed to use 14844pseudo-random values for the ephemeral keys. Instead of keeping the full value of the key in memory, the 14845TPM can use a counter as input to a KDF. Incrementing the counter will cause the TPM to generate a 14846new pseudo-random value. 14847Using the counter to generate pseudo-random private ephemeral keys greatly simplifies tracking of key 14848usage. When a counter value is used to create a key, a bit in an array may be set to indicate that the key 14849use is pending. When the ephemeral key is consumed, the bit is cleared. This prevents the key from 14850being used more than once. 14851Since the TPM is allowed to restrict the number of pending ephemeral keys, the array size can be limited. 14852For example, a 128 bit array would allow 128 keys to be "pending". 14853The management of the array is described in greater detail in the Split Operations clause in Annex C of 14854part 1. 14855 14856Family “2.0” 14857Level 00 Revision 00.99 14858 14859Published 14860Copyright © TCG 2006-2013 14861 14862Page 177 14863October 31, 2013 14864 14865 Part 3: Commands 14866 1486721.2 14868 14869Trusted Platform Module Library 14870 14871TPM2_Commit 14872 1487321.2.1 General Description 14874TPM2_Commit() performs the first part of an ECC anonymous signing operation. The TPM will perform 14875the point multiplications on the provided points and return intermediate signing values. The signHandle 14876parameter shall refer to an ECC key with the sign attribute (TPM_RC_ATTRIBUTES) using an 14877anonymous signing scheme (TPM_RC_SCHEME). 14878For this command, p1, s2 and y2 are optional parameters. If s2 is an Empty Buffer, then the TPM shall 14879return TPM_RC_SIZE if y2 is not an Empty Buffer. If p1, s2, and y2 are all Empty Buffers, the TPM shall 14880return TPM_RC_NO_RESULT. 14881In the algorithm below, the following additional values are used in addition to the command parameters: 14882 14883HnameAlg 14884 14885hash function using the nameAlg of the key associated with 14886signHandle 14887 14888p 14889 14890field modulus of the curve associated with signHandle 14891 14892n 14893 14894order of the curve associated with signHandle 14895 14896ds 14897 14898private key associated with signHandle 14899 14900c 14901 14902counter that increments each time a TPM2_Commit() is 14903successfully completed 14904 14905A[i] 14906 14907array of bits used to indicate when a value of c has been used in 14908a signing operation; values of i are 0 to 2n-1 14909 14910k 14911 14912nonce that is set to a random value on each TPM Reset; nonce 14913size is twice the security strength of any ECDAA key supported 14914by the TPM. 14915 14916The algorithm is: 14917a) set K, L, and E to be Empty Buffers. 14918b) if s2 is not an Empty Buffer, compute x2 ≔ HnameAlg (s2) mod p, else skip to step (e) 14919c) if (x2, y2) is not a point on the curve of signHandle, return TPM_RC_ECC_POINT 14920d) set K ≔ [ds] (x2, y2) 14921e) generate or derive r (see the "Commit Random Value" clause in Part 1) 14922f) 14923 14924set r ≔ r mod n 14925 14926NOTE 1 14927 14928nLen is the number of bits in n 14929 14930g) if p1 is an Empty Buffer, skip to step i) 14931h) if (p1) is not a point on the curve of signHandle, return TPM_RC_ECC_POINT 14932i) 14933 14934set E ≔ [r] (p1) 14935 14936j) 14937 14938if K is not an Empty Buffer, set L ≔ [r] (x2, y2) 14939 14940k) if K, L, or E is the point at infinity, return TPM_RC_NO_RESULT 14941l) 14942 14943set counter ≔ commitCount 14944 14945m) set commitCount ≔ commitCount + 1 14946 14947Page 178 14948October 31, 2013 14949 14950Published 14951Copyright © TCG 2006-2013 14952 14953Family “2.0” 14954Level 00 Revision 00.99 14955 14956 Trusted Platform Module Library 14957NOTE 2 14958 14959Part 3: Commands 14960 14961Depending on the method of generating r, it may be necessary to update the tracking array here. 14962 14963n) output K, L, E and counter 14964NOTE 3 14965 14966Depending on the input parameters K and L may be Empty Buffers or E may be an Empty Buffer 14967 14968Family “2.0” 14969Level 00 Revision 00.99 14970 14971Published 14972Copyright © TCG 2006-2013 14973 14974Page 179 14975October 31, 2013 14976 14977 Part 3: Commands 14978 14979Trusted Platform Module Library 14980 1498121.2.2 Command and Response 14982Table 89 — TPM2_Commit Command 14983Type 14984 14985Name 14986 14987TPMI_ST_COMMAND_TAG 14988 14989tag 14990 14991UINT32 14992 14993paramSize 14994 14995TPM_CC 14996 14997commandCode 14998 14999Description 15000 15001TPM_CC_Commit 15002handle of the key that will be used in the signing 15003operation 15004 15005TPMI_DH_OBJECT 15006 15007@signHandle 15008 15009Auth Index: 1 15010Auth Role: USER 15011 15012TPM2B_ECC_POINT 15013 15014P1 15015 15016a point (M) on the curve used by signHandle 15017 15018TPM2B_SENSITIVE_DATA 15019 15020s2 15021 15022octet array used to derive x-coordinate of a base point 15023 15024TPM2B_ECC_PARAMETER 15025 15026y2 15027 15028y coordinate of the point associated with s2 15029 15030Table 90 — TPM2_Commit Response 15031Type 15032 15033Name 15034 15035Description 15036 15037TPM_ST 15038 15039tag 15040 15041see 8 15042 15043UINT32 15044 15045paramSize 15046 15047TPM_RC 15048 15049responseCode 15050 15051TPM2B_ECC_POINT 15052 15053K 15054 15055ECC point K ≔ [ds](x2, y2) 15056 15057TPM2B_ECC_POINT 15058 15059L 15060 15061ECC point L ≔ [r](x2, y2) 15062 15063TPM2B_ECC_POINT 15064 15065E 15066 15067ECC point E ≔ [r]P1 15068 15069UINT16 15070 15071counter 15072 15073least-significant 16 bits of commitCount 15074 15075Page 180 15076October 31, 2013 15077 15078Published 15079Copyright © TCG 2006-2013 15080 15081Family “2.0” 15082Level 00 Revision 00.99 15083 15084 Trusted Platform Module Library 15085 15086Part 3: Commands 15087 1508821.2.3 Detailed Actions 150891 150902 150913 15092 15093#include "InternalRoutines.h" 15094#include "Commit_fp.h" 15095#ifdef TPM_ALG_ECC 15096Error Returns 15097TPM_RC_ATTRIBUTES 15098 15099keyHandle references a restricted key that is not a signing key 15100 15101TPM_RC_ECC_POINT 15102 15103either P1 or the point derived from s2 is not on the curve of 15104keyHandle 15105 15106TPM_RC_HASH 15107 15108invalid name algorithm in keyHandle 15109 15110TPM_RC_KEY 15111 15112keyHandle does not reference an ECC key 15113 15114TPM_RC_SCHEME 15115 15116keyHandle references a restricted signing key that does not use and 15117anonymous scheme 15118 15119TPM_RC_NO_RESULT 15120 15121K, L or E was a point at infinity; or failed to generate r value 15122 15123TPM_RC_SIZE 151244 151255 151266 151277 151288 151299 1513010 1513111 1513212 1513313 1513414 1513515 1513616 1513717 1513818 1513919 1514020 1514121 1514222 1514323 1514424 1514525 1514626 1514727 1514828 1514929 1515030 1515131 1515232 1515333 1515434 1515535 1515636 1515737 1515838 1515939 1516040 1516141 1516242 1516343 15164 15165Meaning 15166 15167s2 is empty but y2 is not or s2 provided but y2 is not 15168 15169TPM_RC 15170TPM2_Commit( 15171Commit_In 15172Commit_Out 15173 15174*in, 15175*out 15176 15177// IN: input parameter list 15178// OUT: output parameter list 15179 15180) 15181{ 15182OBJECT 15183TPMS_ECC_POINT 15184TPMS_ECC_POINT 15185TPMS_ECC_POINT 15186TPM2B_ECC_PARAMETER 15187TPM2B 15188TPM_RC 15189UINT16 15190 15191*eccKey; 15192P2; 15193*pP2 = NULL; 15194*pP1 = NULL; 15195r; 15196*p; 15197result; 15198hashResults; 15199 15200// Input Validation 15201eccKey = ObjectGet(in->signHandle); 15202// Input key must be an ECC key 15203if(eccKey->publicArea.type != TPM_ALG_ECC) 15204return TPM_RC_KEY + RC_Commit_signHandle; 15205// if the key is restricted, it must be a signing key using an anonymous scheme 15206if(eccKey->publicArea.objectAttributes.restricted == SET) 15207{ 15208if(eccKey->publicArea.objectAttributes.sign != SET) 15209return TPM_RC_ATTRIBUTES + RC_Commit_signHandle; 15210if(!CryptIsSchemeAnonymous( 15211eccKey->publicArea.parameters.eccDetail.scheme.scheme)) 15212return TPM_RC_SCHEME + RC_Commit_signHandle; 15213} 15214else 15215{ 15216// if not restricted, s2, and y2 must be an Empty Buffer 15217if(in->s2.t.size) 15218return TPM_RC_SIZE + RC_Commit_s2; 15219} 15220// Make sure that both parts of P2 are present if either is present 15221if((in->s2.t.size == 0) != (in->y2.t.size == 0)) 15222 15223Family “2.0” 15224Level 00 Revision 00.99 15225 15226Published 15227Copyright © TCG 2006-2013 15228 15229Page 181 15230October 31, 2013 15231 15232 Part 3: Commands 1523344 1523445 1523546 1523647 1523748 1523849 1523950 1524051 1524152 1524253 1524354 1524455 1524556 1524657 1524758 1524859 1524960 1525061 1525162 1525263 1525364 1525465 1525566 1525667 1525768 1525869 1525970 1526071 1526172 1526273 1526374 1526475 1526576 1526677 1526778 1526879 1526980 1527081 1527182 1527283 1527384 1527485 1527586 1527687 1527788 1527889 1527990 1528091 1528192 1528293 1528394 1528495 1528596 1528697 1528798 1528899 15289100 15290101 15291102 15292103 15293104 15294105 15295106 15296107 15297 15298Trusted Platform Module Library 15299 15300return TPM_RC_SIZE + RC_Commit_y2; 15301// Get prime modulus for the curve. This is needed later but getting this now 15302// allows confirmation that the curve exists 15303p = (TPM2B *)CryptEccGetParameter('p', 15304eccKey->publicArea.parameters.eccDetail.curveID); 15305// if no p, then the curve ID is bad 15306// NOTE: This should never occur if the input unmarshaling code is working 15307// correctly 15308if(p == NULL) 15309return TPM_RC_KEY + RC_Commit_signHandle; 15310// Get the random value that will be used in the point multiplications 15311// Note: this does not commit the count. 15312if(!CryptGenerateR(&r, 15313NULL, 15314eccKey->publicArea.parameters.eccDetail.curveID, 15315&eccKey->name)) 15316return TPM_RC_NO_RESULT; 15317// Set up P2 if s2 and Y2 are provided 15318if(in->s2.t.size != 0) 15319{ 15320pP2 = &P2; 15321// copy y2 for P2 15322MemoryCopy2B(&P2.y.b, &in->y2.b, sizeof(P2.y.t.buffer)); 15323// Compute x2 HnameAlg(s2) mod p 15324// 15325do the hash operation on s2 with the size of curve 'p' 15326hashResults = CryptHashBlock(eccKey->publicArea.nameAlg, 15327in->s2.t.size, 15328in->s2.t.buffer, 15329p->size, 15330P2.x.t.buffer); 15331// If there were error returns in the hash routine, indicate a problem 15332// with the hash in 15333if(hashResults == 0) 15334return TPM_RC_HASH + RC_Commit_signHandle; 15335// set the size of the X value to the size of the hash 15336P2.x.t.size = hashResults; 15337// set p2.x = hash(s2) mod p 15338if(CryptDivide(&P2.x.b, p, NULL, &P2.x.b) != TPM_RC_SUCCESS) 15339return TPM_RC_NO_RESULT; 15340if(!CryptEccIsPointOnCurve(eccKey->publicArea.parameters.eccDetail.curveID, 15341pP2)) 15342return TPM_RC_ECC_POINT + RC_Commit_s2; 15343if(eccKey->attributes.publicOnly == SET) 15344return TPM_RC_KEY + RC_Commit_signHandle; 15345} 15346else 15347// If there is a P1, make sure that it is on the curve 15348// NOTE: an "empty" point has two UINT16 values which are the size values 15349// for each of the coordinates. 15350if(in->P1.t.size > 4) 15351{ 15352 15353Page 182 15354October 31, 2013 15355 15356Published 15357Copyright © TCG 2006-2013 15358 15359Family “2.0” 15360Level 00 Revision 00.99 15361 15362 Trusted Platform Module Library 15363108 15364109 15365110 15366111 15367112 15368113 15369114 15370115 15371116 15372117 15373118 15374119 15375120 15376121 15377122 15378123 15379124 15380125 15381126 15382127 15383128 15384129 15385130 15386131 15387132 15388133 15389134 15390135 15391136 15392137 15393138 15394139 15395 15396Part 3: Commands 15397 15398pP1 = &in->P1.t.point; 15399if(!CryptEccIsPointOnCurve(eccKey->publicArea.parameters.eccDetail.curveID, 15400pP1)) 15401return TPM_RC_ECC_POINT + RC_Commit_P1; 15402} 15403// Pass the parameters to CryptCommit. 15404// The work is not done inline because it does several point multiplies 15405// with the same curve. There is significant optimization by not 15406// having to reload the curve parameters multiple times. 15407result = CryptCommitCompute(&out->K.t.point, 15408&out->L.t.point, 15409&out->E.t.point, 15410eccKey->publicArea.parameters.eccDetail.curveID, 15411pP1, 15412pP2, 15413&eccKey->sensitive.sensitive.ecc, 15414&r); 15415if(result != TPM_RC_SUCCESS) 15416return result; 15417out->K.t.size = TPMS_ECC_POINT_Marshal(&out->K.t.point, NULL, NULL); 15418out->L.t.size = TPMS_ECC_POINT_Marshal(&out->L.t.point, NULL, NULL); 15419out->E.t.size = TPMS_ECC_POINT_Marshal(&out->E.t.point, NULL, NULL); 15420// The commit computation was successful so complete the commit by setting 15421// the bit 15422out->counter = CryptCommit(); 15423return TPM_RC_SUCCESS; 15424} 15425#endif 15426 15427Family “2.0” 15428Level 00 Revision 00.99 15429 15430Published 15431Copyright © TCG 2006-2013 15432 15433Page 183 15434October 31, 2013 15435 15436 Part 3: Commands 15437 1543821.3 15439 15440Trusted Platform Module Library 15441 15442TPM2_EC_Ephemeral 15443 1544421.3.1 General Description 15445TPM2_EC_Ephemeral() creates an ephemeral key for use in a two-phase key exchange protocol. 15446The TPM will use the commit mechanism to assign an ephemeral key r and compute a public point Q ≔ 15447[r]G where G is the generator point associated with curveID. 15448 15449Page 184 15450October 31, 2013 15451 15452Published 15453Copyright © TCG 2006-2013 15454 15455Family “2.0” 15456Level 00 Revision 00.99 15457 15458 Trusted Platform Module Library 15459 15460Part 3: Commands 15461 1546221.3.2 Command and Response 15463Table 91 — TPM2_EC_Ephemeral Command 15464Type 15465 15466Name 15467 15468Description 15469 15470TPMI_ST_COMMAND_TAG 15471 15472tag 15473 15474UINT32 15475 15476paramSize 15477 15478TPM_CC 15479 15480commandCode 15481 15482TPM_CC_EC_Ephemeral 15483 15484TPMI_ECC_CURVE 15485 15486curveID 15487 15488The curve for the computed ephemeral point 15489 15490Table 92 — TPM2_EC_Ephemeral Response 15491Type 15492 15493Name 15494 15495Description 15496 15497TPM_ST 15498 15499tag 15500 15501see 8 15502 15503UINT32 15504 15505paramSize 15506 15507TPM_RC 15508 15509responseCode 15510 15511TPM2B_ECC_POINT 15512 15513Q 15514 15515ephemeral public key Q ≔ [r]G 15516 15517UINT16 15518 15519counter 15520 15521least-significant 16 bits of commitCount 15522 15523Family “2.0” 15524Level 00 Revision 00.99 15525 15526Published 15527Copyright © TCG 2006-2013 15528 15529Page 185 15530October 31, 2013 15531 15532 Part 3: Commands 15533 15534Trusted Platform Module Library 15535 1553621.3.3 Detailed Actions 155371 155382 155393 15540 15541#include "InternalRoutines.h" 15542#include "EC_Ephemeral_fp.h" 15543#ifdef TPM_ALG_ECC 15544Error Returns 15545none 15546 155474 155485 155496 155507 155518 155529 1555310 1555411 1555512 1555613 1555714 1555815 1555916 1556017 1556118 1556219 1556320 1556421 1556522 1556623 1556724 1556825 1556926 1557027 15571 15572Meaning 15573... 15574 15575TPM_RC 15576TPM2_EC_Ephemeral( 15577EC_Ephemeral_In 15578EC_Ephemeral_Out 15579 15580*in, 15581*out 15582 15583// IN: input parameter list 15584// OUT: output parameter list 15585 15586) 15587{ 15588TPM2B_ECC_PARAMETER 15589 15590r; 15591 15592// Get the random value that will be used in the point multiplications 15593// Note: this does not commit the count. 15594if(!CryptGenerateR(&r, 15595NULL, 15596in->curveID, 15597NULL)) 15598return TPM_RC_NO_RESULT; 15599CryptEccPointMultiply(&out->Q.t.point, in->curveID, &r, NULL); 15600// commit the count value 15601out->counter = CryptCommit(); 15602return TPM_RC_SUCCESS; 15603} 15604#endif 15605 15606Page 186 15607October 31, 2013 15608 15609Published 15610Copyright © TCG 2006-2013 15611 15612Family “2.0” 15613Level 00 Revision 00.99 15614 15615 Trusted Platform Module Library 15616 1561722 15618 15619Part 3: Commands 15620 15621Signing and Signature Verification 15622 1562322.1 15624 15625TPM2_VerifySignature 15626 1562722.1.1 General Description 15628This command uses loaded keys to validate a signature on a message with the message digest passed 15629to the TPM. 15630If the signature check succeeds, then the TPM will produce a TPMT_TK_VERIFIED. Otherwise, the TPM 15631shall return TPM_RC_SIGNATURE. 15632NOTE 1 15633 15634A valid ticket may be used in subsequent commands to provide proof to the TPM that the TPM has 15635validated the signature over the message using the key referenced by keyHandle. 15636 15637If keyHandle references an asymmetric key, only the public portion of the key needs to be loaded. If 15638keyHandle references a symmetric key, both the public and private portions need to be loaded. 15639NOTE 2 15640 15641The sensitive area of the symmetric object is required to allow verification of the symmetric 15642signature (the HMAC). 15643 15644Family “2.0” 15645Level 00 Revision 00.99 15646 15647Published 15648Copyright © TCG 2006-2013 15649 15650Page 187 15651October 31, 2013 15652 15653 Part 3: Commands 15654 15655Trusted Platform Module Library 15656 1565722.1.2 Command and Response 15658Table 93 — TPM2_VerifySignature Command 15659Type 15660 15661Name 15662 15663Description 15664 15665TPMI_ST_COMMAND_TAG 15666 15667tag 15668 15669UINT32 15670 15671commandSize 15672 15673TPM_CC 15674 15675commandCode 15676 15677TPM_CC_VerifySignature 15678 15679TPMI_DH_OBJECT 15680 15681keyHandle 15682 15683handle of public key that will be used in the validation 15684Auth Index: None 15685 15686TPM2B_DIGEST 15687 15688digest 15689 15690digest of the signed message 15691 15692TPMT_SIGNATURE 15693 15694signature 15695 15696signature to be tested 15697 15698Table 94 — TPM2_VerifySignature Response 15699Type 15700 15701Name 15702 15703Description 15704 15705TPM_ST 15706 15707tag 15708 15709see clause 8 15710 15711UINT32 15712 15713responseSize 15714 15715TPM_RC 15716 15717responseCode 15718 15719TPMT_TK_VERIFIED 15720 15721validation 15722 15723Page 188 15724October 31, 2013 15725 15726Published 15727Copyright © TCG 2006-2013 15728 15729Family “2.0” 15730Level 00 Revision 00.99 15731 15732 Trusted Platform Module Library 15733 15734Part 3: Commands 15735 1573622.1.3 Detailed Actions 157371 157382 15739 15740#include "InternalRoutines.h" 15741#include "VerifySignature_fp.h" 15742Error Returns 15743TPM_RC_ATTRIBUTES 15744 15745keyHandle does not reference a signing key 15746 15747TPM_RC_SIGNATURE 15748 15749signature is not genuine 15750 15751TPM_RC_SCHEME 15752 15753CryptVerifySignature() 15754 15755TPM_RC_HANDLE 157563 157574 157585 157596 157607 157618 157629 1576310 1576411 1576512 1576613 1576714 1576815 1576916 1577017 1577118 1577219 1577320 1577421 1577522 1577623 1577724 1577825 1577926 1578027 1578128 1578229 1578330 1578431 1578532 1578633 1578734 1578835 1578936 1579037 1579138 1579239 1579340 1579441 1579542 1579643 1579744 1579845 1579946 1580047 1580148 1580249 15803 15804Meaning 15805 15806the input handle is not a sign key with private portion loaded 15807 15808TPM_RC 15809TPM2_VerifySignature( 15810VerifySignature_In 15811VerifySignature_Out 15812 15813*in, 15814*out 15815 15816// IN: input parameter list 15817// OUT: output parameter list 15818 15819TPM_RC 15820TPM2B_NAME 15821OBJECT 15822TPMI_RH_HIERARCHY 15823 15824result; 15825name; 15826*signObject; 15827hierarchy; 15828 15829) 15830{ 15831 15832// Input Validation 15833// Get sign object pointer 15834signObject = ObjectGet(in->keyHandle); 15835// The object to validate the signature must be a signing key. 15836if(signObject->publicArea.objectAttributes.sign != SET) 15837return TPM_RC_ATTRIBUTES + RC_VerifySignature_keyHandle; 15838// If it doesn't have a sensitive area loaded 15839// then it can't be a keyed hash signing key 15840if( 15841signObject->attributes.publicOnly == SET 15842&& signObject->publicArea.type == TPM_ALG_KEYEDHASH 15843) 15844return TPM_RC_HANDLE + RC_VerifySignature_keyHandle; 15845// Validate Signature. A TPM_RC_BINDING, TPM_RC_SCHEME or TPM_RC_SIGNATURE 15846// error may be returned by CryptCVerifySignatrue() 15847result = CryptVerifySignature(in->keyHandle, &in->digest, &in->signature); 15848if(result != TPM_RC_SUCCESS) 15849return RcSafeAddToResult(result, RC_VerifySignature_signature); 15850// Command Output 15851hierarchy = ObjectGetHierarchy(in->keyHandle); 15852if( 15853hierarchy == TPM_RH_NULL 15854|| signObject->publicArea.nameAlg == TPM_ALG_NULL) 15855{ 15856// produce empty ticket if hierarchy is TPM_RH_NULL or nameAlg is 15857// TPM_ALG_NULL 15858out->validation.tag = TPM_ST_VERIFIED; 15859out->validation.hierarchy = TPM_RH_NULL; 15860out->validation.digest.t.size = 0; 15861} 15862else 15863{ 15864 15865Family “2.0” 15866Level 00 Revision 00.99 15867 15868Published 15869Copyright © TCG 2006-2013 15870 15871Page 189 15872October 31, 2013 15873 15874 Part 3: Commands 1587550 1587651 1587752 1587853 1587954 1588055 1588156 1588257 15883 15884Trusted Platform Module Library 15885 15886// Get object name that verifies the signature 15887name.t.size = ObjectGetName(in->keyHandle, &name.t.name); 15888// Compute ticket 15889TicketComputeVerified(hierarchy, &in->digest, &name, &out->validation); 15890} 15891return TPM_RC_SUCCESS; 15892} 15893 15894Page 190 15895October 31, 2013 15896 15897Published 15898Copyright © TCG 2006-2013 15899 15900Family “2.0” 15901Level 00 Revision 00.99 15902 15903 Trusted Platform Module Library 15904 1590522.2 15906 15907Part 3: Commands 15908 15909TPM2_Sign 15910 1591122.2.1 General Description 15912This command causes the TPM to sign an externally provided hash with the specified asymmetric signing 15913key. 15914NOTE 1 15915 15916Symmetric “signing” is done with an HMAC. 15917 15918If keyHandle references a restricted signing key, then validation shall be provided indicating that the TPM 15919performed the hash of the data and validation shall indicate that hashed data did not start with 15920TPM_GENERATED_VALUE. 15921NOTE 2 15922 15923If the hashed data did start with TPM_GENERATED_VALUE, then the validation will be a NULL 15924ticket. 15925 15926If the scheme of keyHandle is not TPM_ALG_NULL, then inScheme shall either be the same scheme as 15927keyHandle or TPM_ALG_NULL. 15928If the scheme of keyHandle is TPM_ALG_NULL, the TPM will sign using inScheme; otherwise, it will sign 15929using the scheme of keyHandle. 15930NOTE 3 15931 15932When the signing scheme requires a hash algorithm, the hash is defined in the qualifying data of the 15933scheme. 15934 15935If inScheme is not a valid signing scheme for the type of keyHandle (or TPM_ALG_NULL), then the TPM 15936shall return TPM_RC_SCHEME. 15937If the scheme of keyHandle is an anonymous scheme, then inScheme shall have the same scheme 15938algorithm as keyHandle and inScheme will contain a counter value that will be used in the signing 15939process. 15940As long as it is no larger than allowed, the digest parameter is not required to have any specific size but 15941the signature operation may fail if digest is too large for the selected scheme. 15942If the validation parameter is not the Empty Buffer, then it will be checked even if the key referenced by 15943keyHandle is not a restricted signing key. 15944 15945Family “2.0” 15946Level 00 Revision 00.99 15947 15948Published 15949Copyright © TCG 2006-2013 15950 15951Page 191 15952October 31, 2013 15953 15954 Part 3: Commands 15955 15956Trusted Platform Module Library 15957 1595822.2.2 Command and Response 15959Table 95 — TPM2_Sign Command 15960Type 15961 15962Name 15963 15964TPMI_ST_COMMAND_TAG 15965 15966tag 15967 15968UINT32 15969 15970commandSize 15971 15972TPM_CC 15973 15974commandCode 15975 15976TPM_CC_Sign 15977 15978TPMI_DH_OBJECT 15979 15980@keyHandle 15981 15982Handle of key that will perform signing 15983Auth Index: 1 15984Auth Role: USER 15985 15986TPM2B_DIGEST 15987 15988digest 15989 15990digest to be signed 15991 15992TPMT_SIG_SCHEME+ 15993 15994inScheme 15995 15996signing scheme to use if the scheme for keyHandle is 15997TPM_ALG_NULL 15998 15999validation 16000 16001proof that digest was created by the TPM 16002If keyHandle is not a restricted signing key, then this 16003may be a NULL Ticket with tag = 16004TPM_ST_CHECKHASH. 16005 16006TPMT_TK_HASHCHECK 16007 16008Description 16009 16010Table 96 — TPM2_Sign Response 16011Type 16012 16013Name 16014 16015Description 16016 16017TPM_ST 16018 16019tag 16020 16021see clause 8 16022 16023UINT32 16024 16025responseSize 16026 16027TPM_RC 16028 16029responseCode 16030 16031TPMT_SIGNATURE 16032 16033signature 16034 16035Page 192 16036October 31, 2013 16037 16038the signature 16039 16040Published 16041Copyright © TCG 2006-2013 16042 16043Family “2.0” 16044Level 00 Revision 00.99 16045 16046 Trusted Platform Module Library 16047 16048Part 3: Commands 16049 1605022.2.3 Detailed Actions 160511 160522 160533 16054 16055#include "InternalRoutines.h" 16056#include "Sign_fp.h" 16057#include "Attest_spt_fp.h" 16058Error Returns 16059TPM_RC_ATTRIBUTES 16060 16061key referenced by keHandle is not a signing key 16062 16063TPM_RC_BINDING 16064 16065The public and private portions of the key are not properly bound. 16066 16067TPM_RC_SCHEME 16068 16069inScheme is not compatible with keyHandle; both inScheme and 16070key's default scheme are empty; or inScheme is empty while key's 16071default scheme requires explicit input scheme (split signing); or nonempty default key scheme differs from inScheme 16072 16073TPM_RC_TICKET 16074 16075validation is not a valid ticket 16076 16077TPM_RC_VALUE 160784 160795 160806 160817 160828 160839 1608410 1608511 1608612 1608713 1608814 1608915 1609016 1609117 1609218 1609319 1609420 1609521 1609622 1609723 1609824 1609925 1610026 1610127 1610228 1610329 1610430 1610531 1610632 1610733 1610834 1610935 1611036 1611137 1611238 1611339 1611440 1611541 1611642 1611743 1611844 16119 16120Meaning 16121 16122the value to sign is larger than allowed for the type of keyHandle 16123 16124TPM_RC 16125TPM2_Sign( 16126Sign_In 16127Sign_Out 16128 16129*in, 16130*out 16131 16132// IN: input parameter list 16133// OUT: output parameter list 16134 16135TPM_RC 16136TPMT_TK_HASHCHECK 16137OBJECT 16138 16139result; 16140ticket; 16141*signKey; 16142 16143) 16144{ 16145 16146// Input Validation 16147// Get sign key pointer 16148signKey = ObjectGet(in->keyHandle); 16149// If validation is provided, or the key is restricted, check the ticket 16150if( 16151in->validation.digest.t.size != 0 16152|| signKey->publicArea.objectAttributes.restricted == SET) 16153{ 16154// Compute and compare ticket 16155TicketComputeHashCheck(in->validation.hierarchy, &in->digest, &ticket); 16156if(!Memory2BEqual(&in->validation.digest.b, &ticket.digest.b)) 16157return TPM_RC_TICKET + RC_Sign_validation; 16158} 16159// Command Output 16160// pick a scheme for sign. If the input sign scheme is not compatible with 16161// the default scheme, return an error. 16162result = CryptSelectSignScheme(in->keyHandle, &in->inScheme); 16163if(result != TPM_RC_SUCCESS) 16164{ 16165if(result == TPM_RC_KEY) 16166return TPM_RC_KEY + RC_Sign_keyHandle; 16167else 16168return RcSafeAddToResult(result, RC_Sign_inScheme); 16169} 16170// Sign the hash. A TPM_RC_VALUE, TPM_RC_SCHEME, or TPM_RC_ATTRIBUTES 16171// error may be returned at this point 16172result = CryptSign(in->keyHandle, &in->inScheme, &in->digest, &out->signature); 16173 16174Family “2.0” 16175Level 00 Revision 00.99 16176 16177Published 16178Copyright © TCG 2006-2013 16179 16180Page 193 16181October 31, 2013 16182 16183 Part 3: Commands 1618445 1618546 1618647 16187 16188Trusted Platform Module Library 16189 16190return result; 16191} 16192 16193Page 194 16194October 31, 2013 16195 16196Published 16197Copyright © TCG 2006-2013 16198 16199Family “2.0” 16200Level 00 Revision 00.99 16201 16202 Trusted Platform Module Library 16203 1620423 16205 16206Part 3: Commands 16207 16208Command Audit 16209 1621023.1 16211 16212Introduction 16213 16214If a command has been selected for command audit, the command audit status will be updated when that 16215command completes successfully. The digest is updated as: 16216 16217commandAuditDigestnew ≔ HauditAlg(commandAuditDigestold || cpHash || rpHash) 16218 16219(5) 16220 16221where 16222 16223HauditAlg 16224 16225hash function using the algorithm of the audit sequence 16226 16227commandAuditDigest 16228 16229accumulated digest 16230 16231cpHash 16232 16233the command parameter hash 16234 16235rpHash 16236 16237the response parameter hash 16238 16239TPM2_Shutdown() cannot be audited but TPM2_Startup() can be audited. If the cpHash of the 16240TPM2_Startup() is TPM_SU_STATE, that would indicate that a TPM2_Shutdown() had been successfully 16241executed. 16242TPM2_SetCommandCodeAuditStatus() is always audited. 16243If the TPM is in Failure mode, command audit is not functional. 16244 16245Family “2.0” 16246Level 00 Revision 00.99 16247 16248Published 16249Copyright © TCG 2006-2013 16250 16251Page 195 16252October 31, 2013 16253 16254 Part 3: Commands 16255 1625623.2 16257 16258Trusted Platform Module Library 16259 16260TPM2_SetCommandCodeAuditStatus 16261 1626223.2.1 General Description 16263This command may be used by the Privacy Administrator or platform to change the audit status of a 16264command or to set the hash algorithm used for the audit digest, but not both at the same time. 16265If the auditAlg parameter is a supported hash algorithm and not the same as the current algorithm, then 16266the TPM will check both setList and clearList are empty (zero length). If so, then the algorithm is changed, 16267and the audit digest is cleared. If auditAlg is TPM_ALG_NULL or the same as the current algorithm, then 16268the algorithm and audit digest are unchanged and the setList and clearList will be processed. 16269NOTE 1 16270 16271Because the audit digest is cleared, the audit counter will increment the next time that an audited 16272command is executed. 16273 16274Use of TPM2_SetCommandCodeAuditStatus() to change the list of audited commands is an audited 16275event. If TPM_CC_SetCommandCodeAuditStatus is in clearList, it is ignored. 16276NOTE 2 16277 16278Use of this command to change the audit hash algorithm is not audited and the digest is reset when 16279the command completes. The change in the audit hash algorithm is the evidence that this command 16280was used to change the algorithm. 16281 16282The commands in setList indicate the commands that to be added to the list of audited commands and 16283the commands in clearList indicate the commands that will no longer be audited. It is not an error if a 16284command in setList is already audited or is not implemented. It is not an error if a command in clearList is 16285not currently being audited or is not implemented. 16286If a command code is in both setList and clearList, then it will not be audited (that is, setList shall be 16287processed first). 16288 16289Page 196 16290October 31, 2013 16291 16292Published 16293Copyright © TCG 2006-2013 16294 16295Family “2.0” 16296Level 00 Revision 00.99 16297 16298 Trusted Platform Module Library 16299 16300Part 3: Commands 16301 1630223.2.2 Command and Response 16303Table 97 — TPM2_SetCommandCodeAuditStatus Command 16304Type 16305 16306Name 16307 16308Description 16309 16310TPMI_ST_COMMAND_TAG 16311 16312tag 16313 16314UINT32 16315 16316commandSize 16317 16318TPM_CC 16319 16320commandCode 16321 16322TPM_CC_SetCommandCodeAuditStatus {NV} 16323 16324TPMI_RH_PROVISION 16325 16326@auth 16327 16328TPM_RH_ENDORSEMENT or 16329TPM_RH_PLATFORM+{PP} 16330Auth Index: 1 16331Auth Role: USER 16332 16333TPMI_ALG_HASH+ 16334 16335auditAlg 16336 16337hash algorithm for the audit digest; if 16338TPM_ALG_NULL, then the hash is not changed 16339 16340TPML_CC 16341 16342setList 16343 16344list of commands that will be added to those that will 16345be audited 16346 16347TPML_CC 16348 16349clearList 16350 16351list of commands that will no longer be audited 16352 16353Table 98 — TPM2_SetCommandCodeAuditStatus Response 16354Type 16355 16356Name 16357 16358Description 16359 16360TPM_ST 16361 16362tag 16363 16364see clause 8 16365 16366UINT32 16367 16368responseSize 16369 16370TPM_RC 16371 16372responseCode 16373 16374Family “2.0” 16375Level 00 Revision 00.99 16376 16377Published 16378Copyright © TCG 2006-2013 16379 16380Page 197 16381October 31, 2013 16382 16383 Part 3: Commands 16384 16385Trusted Platform Module Library 16386 1638723.2.3 Detailed Actions 163881 163892 163903 163914 163925 163936 163947 163958 163969 1639710 1639811 1639912 1640013 1640114 1640215 1640316 1640417 1640518 1640619 1640720 1640821 1640922 1641023 1641124 1641225 1641326 1641427 1641528 1641629 1641730 1641831 1641932 1642033 1642134 1642235 1642336 1642437 1642538 1642639 1642740 1642841 1642942 1643043 1643144 1643245 1643346 1643447 1643548 1643649 1643750 1643851 1643952 1644053 1644154 1644255 1644356 1644457 1644558 1644659 1644760 16448 16449#include "InternalRoutines.h" 16450#include "SetCommandCodeAuditStatus_fp.h" 16451 16452TPM_RC 16453TPM2_SetCommandCodeAuditStatus( 16454SetCommandCodeAuditStatus_In 16455 16456*in 16457 16458// IN: input parameter list 16459 16460) 16461{ 16462TPM_RC 16463UINT32 16464BOOL 16465 16466result; 16467i; 16468changed = FALSE; 16469 16470// The command needs NV update. Check if NV is available. 16471// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 16472// this point 16473result = NvIsAvailable(); 16474if(result != TPM_RC_SUCCESS) 16475return result; 16476// Internal Data Update 16477// Update hash algorithm 16478if( 16479in->auditAlg != TPM_ALG_NULL 16480&& in->auditAlg != gp.auditHashAlg) 16481{ 16482// Can't change the algorithm and command list at the same time 16483if(in->setList.count != 0 || in->clearList.count != 0) 16484return TPM_RC_VALUE + RC_SetCommandCodeAuditStatus_auditAlg; 16485// Change the hash algorithm for audit 16486gp.auditHashAlg = in->auditAlg; 16487// Set the digest size to a unique value that indicates that the digest 16488// algorithm has been changed. The size will be cleared to zero in the 16489// command audit processing on exit. 16490gr.commandAuditDigest.t.size = 1; 16491// Save the change of command audit data (this sets g_updateNV so that NV 16492// will be updagted on exit.) 16493NvWriteReserved(NV_AUDIT_HASH_ALG, &gp.auditHashAlg); 16494} else { 16495// Process set list 16496for(i = 0; i < in->setList.count; i++) 16497// If change is made in CommandAuditSet, set changed flag 16498if(CommandAuditSet(in->setList.commandCodes[i])) 16499changed = TRUE; 16500// Process clear list 16501for(i = 0; i < in->clearList.count; i++) 16502// If change is made in CommandAuditClear, set changed flag 16503if(CommandAuditClear(in->clearList.commandCodes[i])) 16504changed = TRUE; 16505// if change was made to command list, update NV 16506if(changed) 16507// this sets g_updateNV so that NV will be updagted on exit. 16508NvWriteReserved(NV_AUDIT_COMMANDS, &gp.auditComands); 16509 16510Page 198 16511October 31, 2013 16512 16513Published 16514Copyright © TCG 2006-2013 16515 16516Family “2.0” 16517Level 00 Revision 00.99 16518 16519 Trusted Platform Module Library 1652061 1652162 1652263 1652364 16524 16525Part 3: Commands 16526 16527} 16528return TPM_RC_SUCCESS; 16529} 16530 16531Family “2.0” 16532Level 00 Revision 00.99 16533 16534Published 16535Copyright © TCG 2006-2013 16536 16537Page 199 16538October 31, 2013 16539 16540 Part 3: Commands 16541 1654224 16543 16544Trusted Platform Module Library 16545 16546Integrity Collection (PCR) 16547 1654824.1 16549 16550Introduction 16551 16552In TPM 1.2, an Event was hashed using SHA-1 and then the 20-octet digest was extended to a PCR 16553using TPM_Extend(). This specification allows the use of multiple PCR at a given Index, each using a 16554different hash algorithm. Rather than require that the external software generate multiple hashes of the 16555Event with each being extended to a different PCR, the Event data may be sent to the TPM for hashing. 16556This ensures that the resulting digests will properly reflect the algorithms chosen for the PCR even if the 16557calling software is unable to implement the hash algorithm. 16558NOTE 1 16559 16560There is continued support for software hashing of events with TPM2_PCR_Extend(). 16561 16562To support recording of an Event that is larger than the TPM input buffer, the caller may use the 16563command sequence described in clause 1. 16564Change to a PCR requires authorization. The authorization may be with either an authorization value or 16565an authorization policy. The platform-specific specifications determine which PCR may be controlled by 16566policy. All other PCR are controlled by authorization. 16567If a PCR may be associated with a policy, then the algorithm ID of that policy determines whether the 16568policy is to be applied. If the algorithm ID is not TPM_ALG_NULL, then the policy digest associated with 16569the PCR must match the policySession→policyDigest in a policy session. If the algorithm ID is 16570TPM_ALG_NULL, then no policy is present and the authorization requires an EmptyAuth. 16571If a platform-specific specification indicates that PCR are grouped, then all the PCR in the group use the 16572same authorization policy or authorization value. 16573PcrUpdateCounter counter will be incremented on the successful completion of any command that 16574modifies (Extends or resets) a PCR unless the platform-specific specification explicitly excludes the PCR 16575from being counted. 16576NOTE 2 16577 16578If a command causes PCR in multiple banks to change, the PCR Update Counter may be 16579incremented either once or once for each bank. 16580 16581A platform-specific specification may designate a set of PCR that are under control of the TCB. These 16582PCR may not be modified without the proper authorization. Updates of these PCR shall not cause the 16583PCR Update Counter to increment. 16584EXAMPLE 16585 16586Updates of the TCB PCR will not cause the PCR update counter to increment b ecause these PCR 16587are changed at the whim of the TCB and are not intended to represent the trust state of the platform. 16588 16589Page 200 16590October 31, 2013 16591 16592Published 16593Copyright © TCG 2006-2013 16594 16595Family “2.0” 16596Level 00 Revision 00.99 16597 16598 Trusted Platform Module Library 16599 1660024.2 16601 16602Part 3: Commands 16603 16604TPM2_PCR_Extend 16605 1660624.2.1 General Description 16607This command is used to cause an update to the indicated PCR. The digests parameter contains one or 16608more tagged digest value identified by an algorithm ID. For each digest, the PCR associated with 16609pcrHandle is Extended into the bank identified by the tag (hashAlg). 16610EXAMPLE 16611 16612A SHA1 digest would be Extended into the SHA1 bank and a SHA256 digest would be Extended into 16613a SHA256 bank. 16614 16615For each list entry, the TPM will check to see if pcrNum is implemented for that algorithm. If so, the TPM 16616shall perform the following operation: 16617 16618PCR.digestnew [pcrNum][alg] ≔ Halg(PCR.digestold [pcrNum][alg] || data[alg].buffer)) 16619 16620(6) 16621 16622where 16623 16624Halg() 16625 16626hash function using the hash algorithm associated with the PCR 16627instance 16628 16629PCR.digest 16630 16631the digest value in a PCR 16632 16633pcrNum 16634 16635the PCR numeric 16636TPM_RH_PCR0) 16637 16638alg 16639 16640the PCR algorithm selector for the digest 16641 16642data[alg].buffer 16643 16644the bank-specific data to be extended 16645 16646selector 16647 16648(equal 16649 16650to 16651 16652pcrHandle 16653 16654– 16655 16656If no digest value is specified for a bank, then the PCR in that bank are not modified. 16657NOTE 1 16658 16659This allows consistent operation of the digests list for all of the Event recording commands. 16660 16661If a digest is present and the PCR in that bank is not implemented, the digest value is not used. 16662NOTE 2 16663 16664If the caller includes digests for algorithms that are not implemented, then the TPM will fail the call 16665because the unmarshalling of digests will fail. Each of the entries in the list is a TPMT_HA which is a 16666hash algorithm followed by a digest. If the algorithm is not implemented, unmarshalling of the 16667hashAlg will fail and the TPM will return TPM_RC_HASH. 16668 16669If the TPM unmarshals the hashAlg of a list entry and the unmarshaled value is not a hash algorithm 16670implemented on the TPM, the TPM shall return TPM_RC_HASH. 16671The pcrHandle parameter is allowed to reference TPM_RH_NULL. If so, the input parameters are 16672processed but no action is taken by the TPM. 16673NOTE 3 16674 16675This command allows a list of digests so that PCR in all banks may be updated in a single 16676command. While the semantics of this command allow multiple extends to a single PCR bank, this is 16677not the preferred use and the limit on the number of entries in the list make this use somewhat 16678impractical. 16679 16680Family “2.0” 16681Level 00 Revision 00.99 16682 16683Published 16684Copyright © TCG 2006-2013 16685 16686Page 201 16687October 31, 2013 16688 16689 Part 3: Commands 16690 16691Trusted Platform Module Library 16692 1669324.2.2 Command and Response 16694Table 99 — TPM2_PCR_Extend Command 16695Type 16696 16697Name 16698 16699Description 16700 16701TPMI_ST_COMMAND_TAG 16702 16703tag 16704 16705UINT32 16706 16707commandSize 16708 16709TPM_CC 16710 16711commandCode 16712 16713TPM_CC_PCR_Extend {NV} 16714 16715TPMI_DH_PCR+ 16716 16717@pcrHandle 16718 16719handle of the PCR 16720Auth Handle: 1 16721Auth Role: USER 16722 16723TPML_DIGEST_VALUES 16724 16725digests 16726 16727list of tagged digest values to be extended 16728 16729Table 100 — TPM2_PCR_Extend Response 16730Type 16731 16732Name 16733 16734Description 16735 16736TPM_ST 16737 16738tag 16739 16740see clause 8 16741 16742UINT32 16743 16744responseSize 16745 16746TPM_RC 16747 16748responseCode 16749 16750Page 202 16751October 31, 2013 16752 16753. 16754 16755Published 16756Copyright © TCG 2006-2013 16757 16758Family “2.0” 16759Level 00 Revision 00.99 16760 16761 Trusted Platform Module Library 16762 16763Part 3: Commands 16764 1676524.2.3 Detailed Actions 167661 167672 16768 16769#include "InternalRoutines.h" 16770#include "PCR_Extend_fp.h" 16771Error Returns 16772TPM_RC_LOCALITY 16773 167743 167754 167765 167776 167787 167798 167809 1678110 1678211 1678312 1678413 1678514 1678615 1678716 1678817 1678918 1679019 1679120 1679221 1679322 1679423 1679524 1679625 1679726 1679827 1679928 1680029 1680130 1680231 1680332 1680433 1680534 1680635 1680736 1680837 1680938 1681039 1681140 1681241 1681342 1681443 1681544 1681645 1681746 1681847 1681948 1682049 16821 16822Meaning 16823current command locality is not allowed to extend the PCR 16824referenced by pcrHandle 16825 16826TPM_RC 16827TPM2_PCR_Extend( 16828PCR_Extend_In 16829 16830*in 16831 16832// IN: input parameter list 16833 16834) 16835{ 16836TPM_RC 16837UINT32 16838 16839result; 16840i; 16841 16842// Input Validation 16843// 16844// 16845// 16846// 16847// 16848// 16849// 16850 16851NOTE: This function assumes that the unmarshaling function for 'digests' will 16852have validated that all of the indicated hash algorithms are valid. If the 16853hash algorithms are correct, the unmarshaling code will unmarshal a digest 16854of the size indicated by the hash algorithm. If the overall size is not 16855consistent, the unmarshaling code will run out of input data or have input 16856data left over. In either case, it will cause an unmarshaling error and this 16857function will not be called. 16858 16859// For NULL handle, do nothing and return success 16860if(in->pcrHandle == TPM_RH_NULL) 16861return TPM_RC_SUCCESS; 16862// Check if the extend operation is allowed by the current command locality 16863if(!PCRIsExtendAllowed(in->pcrHandle)) 16864return TPM_RC_LOCALITY; 16865// If PCR is state saved and we need to update orderlyState, check NV 16866// availability 16867if(PCRIsStateSaved(in->pcrHandle) && gp.orderlyState != SHUTDOWN_NONE) 16868{ 16869result = NvIsAvailable(); 16870if(result != TPM_RC_SUCCESS) return result; 16871g_clearOrderly = TRUE; 16872} 16873// Internal Data Update 16874// Iterate input digest list to extend 16875for(i = 0; i < in->digests.count; i++) 16876{ 16877PCRExtend(in->pcrHandle, in->digests.digests[i].hashAlg, 16878CryptGetHashDigestSize(in->digests.digests[i].hashAlg), 16879(BYTE *) &in->digests.digests[i].digest); 16880} 16881return TPM_RC_SUCCESS; 16882} 16883 16884Family “2.0” 16885Level 00 Revision 00.99 16886 16887Published 16888Copyright © TCG 2006-2013 16889 16890Page 203 16891October 31, 2013 16892 16893 Part 3: Commands 16894 1689524.3 16896 16897Trusted Platform Module Library 16898 16899TPM2_PCR_Event 16900 1690124.3.1 General Description 16902This command is used to cause an update to the indicated PCR. 16903The data in eventData is hashed using the hash algorithm associated with each bank in which the 16904indicated PCR has been allocated. After the data is hashed, the digests list is returned. If the pcrHandle 16905references an implemented PCR and not TPM_ALG_NULL, digests list is processed as in 16906TPM2_PCR_Extend(). 16907A TPM shall support an Event.size of zero through 1,024 inclusive (Event.size is an octet count). An 16908Event.size of zero indicates that there is no data but the indicated operations will still occur, 16909EXAMPLE 1 16910 16911If the command implements PCR[2] in a SHA1 bank and a SHA256 bank, then an extend to PCR[2] 16912will cause eventData to be hashed twice, once with SHA1 and once with SHA256. The SHA1 hash of 16913eventData will be Extended to PCR[2] in the SHA1 bank and the SHA256 hash of eventData will be 16914Extended to PCR[2] of the SHA256 bank. 16915 16916On successful command completion, digests will contain the list of tagged digests of eventData that was 16917computed in preparation for extending the data into the PCR. At the option of the TPM, the list may 16918contain a digest for each bank, or it may only contain a digest for each bank in which pcrHandle is extant. 16919EXAMPLE 2 16920 16921Assume a TPM that implements a SHA1 bank and a SHA256 bank and that PCR[22] is only 16922implemented in the SHA1 bank. If pcrHandle references PCR[22], then digests may contain either a 16923SHA1 and a SHA256 digest or just a SHA1 digest. 16924 16925Page 204 16926October 31, 2013 16927 16928Published 16929Copyright © TCG 2006-2013 16930 16931Family “2.0” 16932Level 00 Revision 00.99 16933 16934 Trusted Platform Module Library 16935 16936Part 3: Commands 16937 1693824.3.2 Command and Response 16939Table 101 — TPM2_PCR_Event Command 16940Type 16941 16942Name 16943 16944Description 16945 16946TPMI_ST_COMMAND_TAG 16947 16948tag 16949 16950UINT32 16951 16952commandSize 16953 16954TPM_CC 16955 16956commandCode 16957 16958TPM_CC_PCR_Event {NV} 16959 16960TPMI_DH_PCR+ 16961 16962@pcrHandle 16963 16964Handle of the PCR 16965Auth Handle: 1 16966Auth Role: USER 16967 16968TPM2B_EVENT 16969 16970eventData 16971 16972Event data in sized buffer 16973 16974Table 102 — TPM2_PCR_Event Response 16975Type 16976 16977Name 16978 16979Description 16980 16981TPM_ST 16982 16983tag 16984 16985see clause 8 16986 16987UINT32 16988 16989responseSize 16990 16991TPM_RC 16992 16993responseCode 16994 16995TPML_DIGEST_VALUES 16996 16997digests 16998 16999Family “2.0” 17000Level 00 Revision 00.99 17001 17002. 17003 17004Published 17005Copyright © TCG 2006-2013 17006 17007Page 205 17008October 31, 2013 17009 17010 Part 3: Commands 17011 17012Trusted Platform Module Library 17013 1701424.3.3 Detailed Actions 170151 170162 17017 17018#include "InternalRoutines.h" 17019#include "PCR_Event_fp.h" 17020Error Returns 17021TPM_RC_LOCALITY 17022 170233 170244 170255 170266 170277 170288 170299 1703010 1703111 1703212 1703313 1703414 1703515 1703616 1703717 1703818 1703919 1704020 1704121 1704222 1704323 1704424 1704525 1704626 1704727 1704828 1704929 1705030 1705131 1705232 1705333 1705434 1705535 1705636 1705737 1705838 1705939 1706040 1706141 1706242 1706343 1706444 1706545 1706646 1706747 1706848 1706949 1707050 1707151 1707252 17073 17074Meaning 17075current command locality is not allowed to extend the PCR 17076referenced by pcrHandle 17077 17078TPM_RC 17079TPM2_PCR_Event( 17080PCR_Event_In 17081PCR_Event_Out 17082 17083*in, 17084*out 17085 17086// IN: input parameter list 17087// OUT: output parameter list 17088 17089) 17090{ 17091TPM_RC 17092HASH_STATE 17093UINT32 17094UINT16 17095 17096result; 17097hashState; 17098i; 17099size; 17100 17101// Input Validation 17102// If a PCR extend is required 17103if(in->pcrHandle != TPM_RH_NULL) 17104{ 17105// If the PCR is not allow to extend, return error 17106if(!PCRIsExtendAllowed(in->pcrHandle)) 17107return TPM_RC_LOCALITY; 17108// If PCR is state saved and we need to update orderlyState, check NV 17109// availability 17110if(PCRIsStateSaved(in->pcrHandle) && gp.orderlyState != SHUTDOWN_NONE) 17111{ 17112result = NvIsAvailable(); 17113if(result != TPM_RC_SUCCESS) return result; 17114g_clearOrderly = TRUE; 17115} 17116} 17117// Internal Data Update 17118out->digests.count = HASH_COUNT; 17119// Iterate supported PCR bank algorithms to extend 17120for(i = 0; i < HASH_COUNT; i++) 17121{ 17122TPM_ALG_ID hash = CryptGetHashAlgByIndex(i); 17123out->digests.digests[i].hashAlg = hash; 17124size = CryptStartHash(hash, &hashState); 17125CryptUpdateDigest2B(&hashState, &in->eventData.b); 17126CryptCompleteHash(&hashState, size, 17127(BYTE *) &out->digests.digests[i].digest); 17128if(in->pcrHandle != TPM_RH_NULL) 17129PCRExtend(in->pcrHandle, hash, size, 17130(BYTE *) &out->digests.digests[i].digest); 17131} 17132return TPM_RC_SUCCESS; 17133} 17134 17135Page 206 17136October 31, 2013 17137 17138Published 17139Copyright © TCG 2006-2013 17140 17141Family “2.0” 17142Level 00 Revision 00.99 17143 17144 Trusted Platform Module Library 17145 1714624.4 17147 17148Part 3: Commands 17149 17150TPM2_PCR_Read 17151 1715224.4.1 General Description 17153This command returns the values of all PCR specified in pcrSelect. 17154The TPM will process the list of TPMS_PCR_SELECTION in pcrSelectionIn in order. Within each 17155TPMS_PCR_SELECTION, the TPM will process the bits in the pcrSelect array in ascending PCR order 17156(see Part 2 for definition of the PCR order). If a bit is SET, and the indicated PCR is present, then the 17157TPM will add the digest of the PCR to the list of values to be returned in pcrValue. 17158The TPM will continue processing bits until all have been processed or until pcrValues would be too large 17159to fit into the output buffer if additional values were added. 17160The returned pcrSelectionOut will have a bit SET in its pcrSelect structures for each value present in 17161pcrValues. 17162The current value of the PCR Update Counter is returned in pcrUpdateCounter. 17163The returned list may be empty if none of the selected PCR are implemented. 17164NOTE 17165 17166If no PCR are returned from a bank, the selector for the bank will be present in pcrSelectionOut. 17167 17168No authorization is required to read a PCR and any implemented PCR may be read from any locality. 17169 17170Family “2.0” 17171Level 00 Revision 00.99 17172 17173Published 17174Copyright © TCG 2006-2013 17175 17176Page 207 17177October 31, 2013 17178 17179 Part 3: Commands 17180 17181Trusted Platform Module Library 17182 1718324.4.2 Command and Response 17184Table 103 — TPM2_PCR_Read Command 17185Type 17186 17187Name 17188 17189Description 17190 17191TPMI_ST_COMMAND_TAG 17192 17193tag 17194 17195UINT32 17196 17197commandSize 17198 17199TPM_CC 17200 17201commandCode 17202 17203TPM_CC_PCR_Read 17204 17205TPML_PCR_SELECTION 17206 17207pcrSelectionIn 17208 17209The selection of PCR to read 17210 17211Table 104 — TPM2_PCR_Read Response 17212Type 17213 17214Name 17215 17216Description 17217 17218TPM_ST 17219 17220tag 17221 17222see clause 8 17223 17224UINT32 17225 17226responseSize 17227 17228TPM_RC 17229 17230responseCode 17231 17232UINT32 17233 17234pcrUpdateCounter 17235 17236the current value of the PCR update counter 17237 17238TPML_PCR_SELECTION 17239 17240pcrSelectionOut 17241 17242the PCR in the returned list 17243 17244TPML_DIGEST 17245 17246pcrValues 17247 17248the contents of the PCR indicated in pcrSelect as 17249tagged digests 17250 17251Page 208 17252October 31, 2013 17253 17254Published 17255Copyright © TCG 2006-2013 17256 17257Family “2.0” 17258Level 00 Revision 00.99 17259 17260 Trusted Platform Module Library 17261 17262Part 3: Commands 17263 1726424.4.3 Detailed Actions 172651 172662 172673 172684 172695 172706 172717 172728 172739 1727410 1727511 1727612 1727713 1727814 1727915 1728016 1728117 1728218 17283 17284#include "InternalRoutines.h" 17285#include "PCR_Read_fp.h" 17286 17287TPM_RC 17288TPM2_PCR_Read( 17289PCR_Read_In 17290PCR_Read_Out 17291 17292*in, 17293*out 17294 17295// IN: input parameter list 17296// OUT: output parameter list 17297 17298) 17299{ 17300// Command Output 17301// Call PCR read function. input pcrSelectionIn parameter could be changed 17302// to reflect the actual PCR being returned 17303PCRRead(&in->pcrSelectionIn, &out->pcrValues, &out->pcrUpdateCounter); 17304out->pcrSelectionOut = in->pcrSelectionIn; 17305return TPM_RC_SUCCESS; 17306} 17307 17308Family “2.0” 17309Level 00 Revision 00.99 17310 17311Published 17312Copyright © TCG 2006-2013 17313 17314Page 209 17315October 31, 2013 17316 17317 Part 3: Commands 17318 1731924.5 17320 17321Trusted Platform Module Library 17322 17323TPM2_PCR_Allocate 17324 1732524.5.1 General Description 17326This command is used to set the desired PCR allocation of PCR and algorithms. This command requires 17327platformAuth. 17328The TPM will evaluate the request and, if sufficient memory is available for the requested allocation, the 17329TPM will store the allocation request for use during the next TPM2_Startup(TPM_SU_CLEAR) operation. 17330The PCR allocation in place when this command is executed will be retained until the next 17331TPM2_Startup(TPM_SU_CLEAR). 17332If no allocation is specified for a bank, then no PCR will be allocated to that bank. If a bank is listed more 17333than once, then the last selection in the pcrAllocation list is the one that the TPM will attempt to allocate. 17334This command shall not allocate more PCR in any bank than there are PCR attribute definitions. The 17335PCR attribute definitions indicate how a PCR is to be managed – if it is resettable, the locality for update, 17336etc. In the response to this command, the TPM returns the maximum number of PCR allowed for any 17337bank. 17338If the command is properly authorized, it will return SUCCESS even though the request fails. This is to 17339allow the TPM to return information about the size needed for the requested allocation and the size 17340available. If the sizeNeeded parameter in the return is less than or equal to the sizeAvailable parameter, 17341then the allocationSuccess parameter will be YES. 17342After this command, TPM2_Shutdown() is only allowed to have a startupType equal to TPM_SU_CLEAR. 17343NOTE 17344 17345Even if this command does not cause the PCR allocation to change, the TPM cannot have its state 17346saved. This is done in order to simplify the implementation. There is no need to optimize this 17347command as it is not expected to be used more than once in the lifetime of the TPM (it can be used 17348any number of times but there is no justification for optimization) . 17349 17350Page 210 17351October 31, 2013 17352 17353Published 17354Copyright © TCG 2006-2013 17355 17356Family “2.0” 17357Level 00 Revision 00.99 17358 17359 Trusted Platform Module Library 17360 17361Part 3: Commands 17362 1736324.5.2 Command and Response 17364Table 105 — TPM2_PCR_Allocate Command 17365Type 17366 17367Name 17368 17369Description 17370 17371TPMI_ST_COMMAND_TAG 17372 17373tag 17374 17375UINT32 17376 17377commandSize 17378 17379TPM_CC 17380 17381commandCode 17382 17383TPM_CC_PCR_Allocate {NV} 17384 17385TPMI_RH_PLATFORM 17386 17387@authHandle 17388 17389TPM_RH_PLATFORM+{PP} 17390Auth Index: 1 17391Auth Role: USER 17392 17393TPML_PCR_SELECTION 17394 17395pcrAllocation 17396 17397the requested allocation 17398 17399Table 106 — TPM2_PCR_Allocate Response 17400Type 17401 17402Name 17403 17404Description 17405 17406TPM_ST 17407 17408tag 17409 17410see clause 8 17411 17412UINT32 17413 17414responseSize 17415 17416TPM_RC 17417 17418responseCode 17419 17420TPMI_YES_NO 17421 17422allocationSuccess 17423 17424YES if the allocation succeeded 17425 17426UINT32 17427 17428maxPCR 17429 17430maximum number of PCR that may be in a bank 17431 17432UINT32 17433 17434sizeNeeded 17435 17436number of octets required to satisfy the request 17437 17438UINT32 17439 17440sizeAvailable 17441 17442Number of octets available. Computed before the 17443allocation. 17444 17445Family “2.0” 17446Level 00 Revision 00.99 17447 17448Published 17449Copyright © TCG 2006-2013 17450 17451Page 211 17452October 31, 2013 17453 17454 Part 3: Commands 17455 17456Trusted Platform Module Library 17457 1745824.5.3 Detailed Actions 174591 174602 174613 174624 174635 174646 174657 174668 174679 1746810 1746911 1747012 1747113 1747214 1747315 1747416 1747517 1747618 1747719 1747820 1747921 1748022 1748123 1748224 1748325 1748426 1748527 1748628 1748729 1748830 1748931 1749032 1749133 1749234 17493 17494#include "InternalRoutines.h" 17495#include "PCR_Allocate_fp.h" 17496 17497TPM_RC 17498TPM2_PCR_Allocate( 17499PCR_Allocate_In 17500PCR_Allocate_Out 17501 17502*in, 17503*out 17504 17505// IN: input parameter list 17506// OUT: output parameter list 17507 17508) 17509{ 17510TPM_RC 17511 17512result; 17513 17514// The command needs NV update. Check if NV is available. 17515// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 17516// this point. 17517// Note: These codes are not listed in the return values above because it is 17518// an implementation choice to check in this routine rather than in a common 17519// function that is called before these actions are called. These return values 17520// are described in the Response Code section of Part 3. 17521result = NvIsAvailable(); 17522if(result != TPM_RC_SUCCESS) 17523return result; 17524// Command Output 17525// Call PCR Allocation function. 17526out->allocationSuccess = PCRAllocate(&in->pcrAllocation, &out->maxPCR, 17527&out->sizeNeeded, &out->sizeAvailable); 17528// if re-configuration succeeds, set the flag to indicate PCR configuration is 17529// going to be changed in next boot 17530if(out->allocationSuccess == YES) 17531g_pcrReConfig = TRUE; 17532return TPM_RC_SUCCESS; 17533} 17534 17535Page 212 17536October 31, 2013 17537 17538Published 17539Copyright © TCG 2006-2013 17540 17541Family “2.0” 17542Level 00 Revision 00.99 17543 17544 Trusted Platform Module Library 17545 1754624.6 17547 17548Part 3: Commands 17549 17550TPM2_PCR_SetAuthPolicy 17551 1755224.6.1 General Description 17553This command is used to associate a policy with a PCR or group of PCR. The policy determines the 17554conditions under which a PCR may be extended or reset. 17555A policy may only be associated with a PCR that has been defined by a platform-specific specification as 17556allowing a policy. If the TPM implementation does not allow a policy for pcrNum, the TPM shall return 17557TPM_RC_VALUE. 17558A platform-specific specification may group PCR so that they share a common policy. In such case, a 17559pcrNum that selects any of the PCR in the group will change the policy for all PCR in the group. 17560The policy setting is persistent and may only be changed by TPM2_PCR_SetAuthPolicy() or by 17561TPM2_ChangePPS(). 17562Before this command is first executed on a TPM or after TPM2_ChangePPS(), the access control on the 17563PCR will be set to the default value defined in the platform-specific specification. 17564NOTE 1 17565 17566It is expected that the typical default will be with the policy hash set to TPM_ALG_NULL and an 17567Empty Buffer for the authPolicy value. This will allow an EmptyAuth to be used as the authorization 17568value. 17569 17570If the size of the data buffer in authPolicy is not the size of a digest produced by hashAlg, the TPM shall 17571return TPM_RC_SIZE. 17572NOTE 2 17573 17574If hashAlg is TPM_ALG_NULL, then the size is required to be zero. 17575 17576This command requires platformAuth/platformPolicy. 17577NOTE 3 17578 17579If the PCR is in multiple policy sets, the policy will be changed in only one set. The set that is 17580changed will be implementation dependent. 17581 17582Family “2.0” 17583Level 00 Revision 00.99 17584 17585Published 17586Copyright © TCG 2006-2013 17587 17588Page 213 17589October 31, 2013 17590 17591 Part 3: Commands 17592 17593Trusted Platform Module Library 17594 1759524.6.2 Command and Response 17596Table 107 — TPM2_PCR_SetAuthPolicy Command 17597Type 17598 17599Name 17600 17601Description 17602 17603TPMI_ST_COMMAND_TAG 17604 17605tag 17606 17607UINT32 17608 17609commandSize 17610 17611TPM_CC 17612 17613commandCode 17614 17615TPM_CC_PCR_SetAuthPolicy {NV} 17616 17617TPMI_RH_PLATFORM 17618 17619@authHandle 17620 17621TPM_RH_PLATFORM+{PP} 17622Auth Index: 1 17623Auth Role: USER 17624 17625TPM2B_DIGEST 17626 17627authPolicy 17628 17629the desired authPolicy 17630 17631TPMI_ALG_HASH+ 17632 17633policyDigest 17634 17635the digest of the policy 17636 17637TPMI_DH_PCR 17638 17639pcrNum 17640 17641the PCR for which the policy is to be set 17642 17643Table 108 — TPM2_PCR_SetAuthPolicy Response 17644Type 17645 17646Name 17647 17648Description 17649 17650TPM_ST 17651 17652tag 17653 17654see clause 8 17655 17656UINT32 17657 17658responseSize 17659 17660TPM_RC 17661 17662responseCode 17663 17664Page 214 17665October 31, 2013 17666 17667Published 17668Copyright © TCG 2006-2013 17669 17670Family “2.0” 17671Level 00 Revision 00.99 17672 17673 Trusted Platform Module Library 17674 17675Part 3: Commands 17676 1767724.6.3 Detailed Actions 176781 176792 17680 17681#include "InternalRoutines.h" 17682#include "PCR_SetAuthPolicy_fp.h" 17683Error Returns 17684TPM_RC_SIZE 17685 17686size of authPolicy is not the size of a digest produced by policyDigest 17687 17688TPM_RC_VALUE 176893 176904 176915 176926 176937 176948 176959 1769610 1769711 1769812 1769913 1770014 1770115 1770216 1770317 1770418 1770519 1770620 1770721 1770822 1770923 1771024 1771125 1771226 1771327 1771428 1771529 1771630 1771731 1771832 1771933 1772034 1772135 1772236 1772337 1772438 17725 17726Meaning 17727 17728PCR referenced by pcrNum is not a member of a PCR policy group 17729 17730TPM_RC 17731TPM2_PCR_SetAuthPolicy( 17732PCR_SetAuthPolicy_In 17733 17734*in 17735 17736// IN: input parameter list 17737 17738) 17739{ 17740UINT32 17741 17742groupIndex; 17743 17744TPM_RC 17745 17746result; 17747 17748// The command needs NV update. Check if NV is available. 17749// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 17750// this point 17751result = NvIsAvailable(); 17752if(result != TPM_RC_SUCCESS) return result; 17753// Input Validation: 17754// Check the authPolicy consistent with hash algorithm 17755if(in->authPolicy.t.size != CryptGetHashDigestSize(in->policyDigest)) 17756return TPM_RC_SIZE + RC_PCR_SetAuthPolicy_authPolicy; 17757// If PCR does not belong to a policy group, return TPM_RC_VALUE 17758if(!PCRBelongsPolicyGroup(in->pcrNum, &groupIndex)) 17759return TPM_RC_VALUE + RC_PCR_SetAuthPolicy_pcrNum; 17760// Internal Data Update 17761// Set PCR policy 17762gp.pcrPolicies.hashAlg[groupIndex] = in->policyDigest; 17763gp.pcrPolicies.policy[groupIndex] = in->authPolicy; 17764// Save new policy to NV 17765NvWriteReserved(NV_PCR_POLICIES, &gp.pcrPolicies); 17766return TPM_RC_SUCCESS; 17767} 17768 17769Family “2.0” 17770Level 00 Revision 00.99 17771 17772Published 17773Copyright © TCG 2006-2013 17774 17775Page 215 17776October 31, 2013 17777 17778 Part 3: Commands 17779 1778024.7 17781 17782Trusted Platform Module Library 17783 17784TPM2_PCR_SetAuthValue 17785 1778624.7.1 General Description 17787This command changes the authValue of a PCR or group of PCR. 17788An authValue may only be associated with a PCR that has been defined by a platform-specific 17789specification as allowing an authorization value. If the TPM implementation does not allow an 17790authorization for pcrNum, the TPM shall return TPM_RC_VALUE. A platform-specific specification may 17791group PCR so that they share a common authorization value. In such case, a pcrNum that selects any of 17792the PCR in the group will change the authValue value for all PCR in the group. 17793The authorization setting is set to EmptyAuth on each STARTUP(CLEAR) or by TPM2_Clear(). The 17794authorization setting is preserved by SHUTDOWN(STATE). 17795 17796Page 216 17797October 31, 2013 17798 17799Published 17800Copyright © TCG 2006-2013 17801 17802Family “2.0” 17803Level 00 Revision 00.99 17804 17805 Trusted Platform Module Library 17806 17807Part 3: Commands 17808 1780924.7.2 Command and Response 17810Table 109 — TPM2_PCR_SetAuthValue Command 17811Type 17812 17813Name 17814 17815Description 17816 17817TPMI_ST_COMMAND_TAG 17818 17819tag 17820 17821UINT32 17822 17823commandSize 17824 17825TPM_CC 17826 17827commandCode 17828 17829TPM_CC_PCR_SetAuthValue 17830 17831TPMI_DH_PCR 17832 17833@pcrHandle 17834 17835handle for a PCR that may have an authorization value 17836set 17837Auth Index: 1 17838Auth Role: USER 17839 17840TPM2B_DIGEST 17841 17842auth 17843 17844the desired authorization value 17845 17846Table 110 — TPM2_PCR_SetAuthValue Response 17847Type 17848 17849Name 17850 17851Description 17852 17853TPM_ST 17854 17855tag 17856 17857see clause 8 17858 17859UINT32 17860 17861responseSize 17862 17863TPM_RC 17864 17865responseCode 17866 17867Family “2.0” 17868Level 00 Revision 00.99 17869 17870Published 17871Copyright © TCG 2006-2013 17872 17873Page 217 17874October 31, 2013 17875 17876 Part 3: Commands 17877 17878Trusted Platform Module Library 17879 1788024.7.3 Detailed Actions 178811 178822 17883 17884#include "InternalRoutines.h" 17885#include "PCR_SetAuthValue_fp.h" 17886Error Returns 17887TPM_RC_VALUE 17888 178893 178904 178915 178926 178937 178948 178959 1789610 1789711 1789812 1789913 1790014 1790115 1790216 1790317 1790418 1790519 1790620 1790721 1790822 1790923 1791024 1791125 1791226 1791327 1791428 1791529 1791630 1791731 1791832 1791933 1792034 17921 17922Meaning 17923PCR referenced by pcrHandle is not a member of a PCR 17924authorization group 17925 17926TPM_RC 17927TPM2_PCR_SetAuthValue( 17928PCR_SetAuthValue_In 17929 17930*in 17931 17932// IN: input parameter list 17933 17934) 17935{ 17936UINT32 17937TPM_RC 17938 17939groupIndex; 17940result; 17941 17942// Input Validation: 17943// If PCR does not belong to an auth group, return TPM_RC_VALUE 17944if(!PCRBelongsAuthGroup(in->pcrHandle, &groupIndex)) 17945return TPM_RC_VALUE; 17946// The command may cause the orderlyState to be cleared due to the update of 17947// state clear data. If this is the case, Check if NV is available. 17948// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 17949// this point 17950if(gp.orderlyState != SHUTDOWN_NONE) 17951{ 17952result = NvIsAvailable(); 17953if(result != TPM_RC_SUCCESS) return result; 17954g_clearOrderly = TRUE; 17955} 17956// Internal Data Update 17957// Set PCR authValue 17958gc.pcrAuthValues.auth[groupIndex] = in->auth; 17959return TPM_RC_SUCCESS; 17960} 17961 17962Page 218 17963October 31, 2013 17964 17965Published 17966Copyright © TCG 2006-2013 17967 17968Family “2.0” 17969Level 00 Revision 00.99 17970 17971 Trusted Platform Module Library 17972 1797324.8 17974 17975Part 3: Commands 17976 17977TPM2_PCR_Reset 17978 1797924.8.1 General Description 17980If the attribute of a PCR allows the PCR to be reset and proper authorization is provided, then this 17981command may be used to set the PCR to zero. The attributes of the PCR may restrict the locality that can 17982perform the reset operation. 17983NOTE 1 17984 17985The definition of TPMI_DH_PCR in Part 2 indicates that if pcrHandle is out of the allowed range for 17986PCR, then the appropriate return value is TPM_RC_VALUE. 17987 17988If pcrHandle references a PCR that cannot be reset, the TPM shall return TPM_RC_LOCALITY. 17989NOTE 2 17990 17991TPM_RC_LOCALITY is returned because the reset attributes are defined on a per -locality basis. 17992 17993Family “2.0” 17994Level 00 Revision 00.99 17995 17996Published 17997Copyright © TCG 2006-2013 17998 17999Page 219 18000October 31, 2013 18001 18002 Part 3: Commands 18003 18004Trusted Platform Module Library 18005 1800624.8.2 Command and Response 18007Table 111 — TPM2_PCR_Reset Command 18008Type 18009 18010Name 18011 18012Description 18013 18014TPMI_ST_COMMAND_TAG 18015 18016tag 18017 18018UINT32 18019 18020commandSize 18021 18022TPM_CC 18023 18024commandCode 18025 18026TPM_CC_PCR_Reset {NV} 18027 18028TPMI_DH_PCR 18029 18030@pcrHandle 18031 18032the PCR to reset 18033Auth Index: 1 18034Auth Role: USER 18035 18036Table 112 — TPM2_PCR_Reset Response 18037Type 18038 18039Name 18040 18041Description 18042 18043TPM_ST 18044 18045tag 18046 18047see clause 8 18048 18049UINT32 18050 18051responseSize 18052 18053TPM_RC 18054 18055responseCode 18056 18057Page 220 18058October 31, 2013 18059 18060Published 18061Copyright © TCG 2006-2013 18062 18063Family “2.0” 18064Level 00 Revision 00.99 18065 18066 Trusted Platform Module Library 18067 18068Part 3: Commands 18069 1807024.8.3 Detailed Actions 180711 180722 18073 18074#include "InternalRoutines.h" 18075#include "PCR_Reset_fp.h" 18076Error Returns 18077TPM_RC_LOCALITY 18078 180793 180804 180815 180826 180837 180848 180859 1808610 1808711 1808812 1808913 1809014 1809115 1809216 1809317 1809418 1809519 1809620 1809721 1809822 1809923 1810024 1810125 1810226 1810327 1810428 1810529 1810630 1810731 1810832 1810933 1811034 1811135 1811236 18113 18114Meaning 18115current command locality is not allowed to reset the PCR referenced 18116by pcrHandle 18117 18118TPM_RC 18119TPM2_PCR_Reset( 18120PCR_Reset_In 18121 18122*in 18123 18124// IN: input parameter list 18125 18126) 18127{ 18128TPM_RC 18129 18130result; 18131 18132// Input Validation 18133// Check if the reset operation is allowed by the current command locality 18134if(!PCRIsResetAllowed(in->pcrHandle)) 18135return TPM_RC_LOCALITY; 18136// If PCR is state saved and we need to update orderlyState, check NV 18137// availability 18138if(PCRIsStateSaved(in->pcrHandle) && gp.orderlyState != SHUTDOWN_NONE) 18139{ 18140result = NvIsAvailable(); 18141if(result != TPM_RC_SUCCESS) 18142return result; 18143g_clearOrderly = TRUE; 18144} 18145// Internal Data Update 18146// Reset seleccted PCR in all banks to 0 18147PCRSetValue(in->pcrHandle, 0); 18148// Indicate that the PCR changed so that pcrCounter will be incremented if 18149// necessary. 18150PCRChanged(in->pcrHandle); 18151return TPM_RC_SUCCESS; 18152} 18153 18154Family “2.0” 18155Level 00 Revision 00.99 18156 18157Published 18158Copyright © TCG 2006-2013 18159 18160Page 221 18161October 31, 2013 18162 18163 Part 3: Commands 18164 1816524.9 18166 18167Trusted Platform Module Library 18168 18169_TPM_Hash_Start 18170 1817124.9.1 Description 18172This indication from the TPM interface indicates the start of a dynamic Core Root of Trust for 18173Measurement (D-CRTM) measurement sequence. On receipt of this indication, the TPM will initialize an 18174Event sequence context. 18175If no object memory is available for creation of the sequence context, the TPM will flush the context of an 18176object so that creation of the Event sequence context will always succeed. 18177A platform-specific specification may allow this indication before TPM2_Startup(). 18178NOTE 18179 18180If this indication occurs after TPM2_Startup(), it is the responsibility of software to ensure that an 18181object context slot is available or to deal with the consequences of having the TPM select an 18182arbitrary object to be flushed. If this indication occurs before TPM2_Startup() then all context slots 18183are available. 18184 18185Page 222 18186October 31, 2013 18187 18188Published 18189Copyright © TCG 2006-2013 18190 18191Family “2.0” 18192Level 00 Revision 00.99 18193 18194 Trusted Platform Module Library 18195 18196Part 3: Commands 18197 1819824.9.2 Detailed Actions 181991 18200 18201#include "InternalRoutines.h" 18202 18203This function is called to process a _TPM_Hash_Start() indication. 182042 182053 182064 182075 182086 182097 182108 182119 1821210 1821311 1821412 1821513 1821614 1821715 1821816 1821917 1822018 1822119 1822220 1822321 1822422 1822523 1822624 1822725 1822826 1822927 1823028 1823129 1823230 1823331 1823432 1823533 1823634 1823735 1823836 1823937 1824038 1824139 1824240 1824341 1824442 1824543 1824644 1824745 1824846 1824947 1825048 1825149 1825250 18253 18254void 18255_TPM_Hash_Start(void) 18256{ 18257TPM_RC 18258TPMI_DH_OBJECT 18259 18260result; 18261handle; 18262 18263// If a DRTM sequence object exists, terminate it. 18264if(g_DRTMHandle != TPM_RH_UNASSIGNED) 18265ObjectTerminateEvent(); 18266// Create an event sequence object and store the handle in global 18267// g_DRTMHandle. A TPM_RC_OBJECT_MEMORY error may be returned at this point 18268// The null value for the 'auth' parameter will cause the sequence structure to 18269// be allocated without being set as present. This keeps the sequence from 18270// being left behind if the sequence is terminated early. 18271result = ObjectCreateEventSequence(NULL, &g_DRTMHandle); 18272// If a free slot was not available, then free up a slot. 18273if(result != TPM_RC_SUCCESS) 18274{ 18275// An implementation does not need to have a fixed relationship between 18276// slot numbers and handle numbers. To handle the general case, scan for 18277// a handle that is assigned an free it for the DRTM sequence. 18278// In the reference implementation, the relationship between handles and 18279// slots is fixed. So, if the call to ObjectCreateEvenSequence() 18280// failed indicating that all slots are occupied, then the first handle we 18281// are going to check (TRANSIENT_FIRST) will be occupied. It will be freed 18282// so that it can be assigned for use as the DRTM sequence object. 18283for(handle = TRANSIENT_FIRST; handle < TRANSIENT_LAST; handle++) 18284{ 18285// try to flush the first object 18286if(ObjectIsPresent(handle)) 18287break; 18288} 18289// If the first call to find a slot fails but none of the slots is occupied 18290// then there's a big problem 18291pAssert(handle < TRANSIENT_LAST); 18292// Free the slot 18293ObjectFlush(handle); 18294// Try to create an event sequence object again. This time, we must 18295// succeed. 18296result = ObjectCreateEventSequence(NULL, &g_DRTMHandle); 18297pAssert(result == TPM_RC_SUCCESS); 18298} 18299return; 18300} 18301 18302Family “2.0” 18303Level 00 Revision 00.99 18304 18305Published 18306Copyright © TCG 2006-2013 18307 18308Page 223 18309October 31, 2013 18310 18311 Part 3: Commands 18312 18313Trusted Platform Module Library 18314 1831524.10 _TPM_Hash_Data 1831624.10.1 18317 18318Description 18319 18320This indication from the TPM interface indicates arrival of one or more octets of data that are to be 18321included in the Core Root of Trust for Measurement (CRTM) sequence context created by the 18322_TPM_Hash_Start indication. The context holds data for each hash algorithm for each PCR bank 18323implemented on the TPM. 18324If no DRTM Event Sequence context exists, this indication is discarded and no other action is performed. 18325 18326Page 224 18327October 31, 2013 18328 18329Published 18330Copyright © TCG 2006-2013 18331 18332Family “2.0” 18333Level 00 Revision 00.99 18334 18335 Trusted Platform Module Library 18336 1833724.10.2 183381 183392 18340 18341Part 3: Commands 18342 18343Detailed Actions 18344 18345#include "InternalRoutines.h" 18346#include "Platform.h" 18347 18348This function is called to process a _TPM_Hash_Data() indication. 183493 183504 183515 183526 183537 183548 183559 1835610 1835711 1835812 1835913 1836014 1836115 1836216 1836317 1836418 1836519 1836620 1836721 1836822 1836923 1837024 1837125 1837226 1837327 1837428 1837529 1837630 1837731 18378 18379void 18380_TPM_Hash_Data( 18381UINT32 18382BYTE 18383 18384dataSize, 18385*data 18386 18387UINT32 18388HASH_OBJECT 18389 18390// IN: size of data to be extend 18391// IN: data buffer 18392 18393i; 18394*hashObject; 18395 18396) 18397{ 18398 18399// If there is no DRTM sequence object, then _TPM_Hash_Start 18400// was not called so this function returns without doing 18401// anything. 18402if(g_DRTMHandle == TPM_RH_UNASSIGNED) 18403return; 18404hashObject = (HASH_OBJECT *)ObjectGet(g_DRTMHandle); 18405pAssert(hashObject->attributes.eventSeq); 18406// For each of the implemented hash algorithms, update the digest with the 18407// data provided. NOTE: the implementation could be done such that the TPM 18408// only computes the hash for the banks that contain the DRTM PCR. 18409for(i = 0; i < HASH_COUNT; i++) 18410{ 18411// Update sequence object 18412CryptUpdateDigest(&hashObject->state.hashState[i], dataSize, data); 18413} 18414return; 18415} 18416 18417Family “2.0” 18418Level 00 Revision 00.99 18419 18420Published 18421Copyright © TCG 2006-2013 18422 18423Page 225 18424October 31, 2013 18425 18426 Part 3: Commands 18427 18428Trusted Platform Module Library 18429 1843024.11 _TPM_Hash_End 1843124.11.1 18432 18433Description 18434 18435This indication from the TPM interface indicates the end of the CRTM measurement. This indication is 18436discarded and no other action performed if the TPM does not contain a CRTM Event sequence context. 18437NOTE 18438 18439A CRTM Event Sequence context is created by _TPM_Hash_Start(). 18440 18441If the CRTM Event sequence occurs after TPM2_Startup(), the TPM will set all of the PCR designated in 18442the platform-specific specifications as resettable by this event to the value indicated in the platform 18443specific specification, and increment restartCount. The TPM will then Extend the Event Sequence 18444digest/digests into the designated, DRTM PCR. 18445PCR[DRTM][hashAlg] ≔ HhashAlg (initial_value || HhashAlg (hash_data)) 18446 18447(7) 18448 18449where 18450DRTM 18451 18452index for CRTM PCR designated by a platform-specific 18453specification 18454 18455hashAlg 18456 18457hash algorithm associated with a bank of PCR 18458 18459initial_value 18460 18461initialization value specified in the platform-specific specification 18462(should be 0…0) 18463 18464hash_data 18465 18466all the octets of data received in _TPM_Hash_Data indications 18467 18468A _TPM_Hash_End indication that occurs after TPM2_Startup() will increment pcrUpdateCounter unless 18469a platform-specific specification excludes modifications of PCR[DRTM] from causing an increment. 18470A platform-specific specification may allow an H-CRTM Event Sequence before TPM2_Startup(). If so, 18471_TPM_Hash_End will complete the digest, initialize PCR[0] with a digest-size value of 4, and then extend 18472the H-CRTM Event Sequence data into PCR[0]. 18473PCR[0][hashAlg] ≔ HhashAlg (0…04 || HhashAlg (hash_data)) 18474NOTE 18475 18476(8) 18477 18478The entire sequence of _TPM_Hash_Start, _TPM_Hash_Data, and _TPM_Hash_End are required to 18479complete before TPM2_Startup() or the sequence will have no effect on the TPM. 18480 18481Page 226 18482October 31, 2013 18483 18484Published 18485Copyright © TCG 2006-2013 18486 18487Family “2.0” 18488Level 00 Revision 00.99 18489 18490 Trusted Platform Module Library 18491 1849224.11.2 184931 18494 18495Part 3: Commands 18496 18497Detailed Actions 18498 18499#include "InternalRoutines.h" 18500 18501This function is called to process a _TPM_Hash_End() indication. 185022 185033 185044 185055 185066 185077 185088 185099 1851010 1851111 1851212 1851313 1851414 1851515 1851616 1851717 1851818 1851919 1852020 1852121 1852222 1852323 1852424 1852525 1852626 1852727 1852828 1852929 1853030 1853131 1853232 1853333 1853434 1853535 1853636 1853737 1853838 1853939 1854040 1854141 1854242 1854343 1854444 1854545 1854646 1854747 1854848 1854949 1855050 1855151 1855252 1855353 1855454 1855555 1855656 1855757 18558 18559void 18560_TPM_Hash_End(void) 18561{ 18562UINT32 18563TPM2B_DIGEST 18564HASH_OBJECT 18565TPMI_DH_PCR 18566 18567i; 18568digest; 18569*hashObject; 18570pcrHandle; 18571 18572// If the DRTM handle is not being used, then either _TPM_Hash_Start has not 18573// been called, _TPM_Hash_End was previously called, or some other command 18574// was executed and the sequence was aborted. 18575if(g_DRTMHandle == TPM_RH_UNASSIGNED) 18576return; 18577// Get DRTM sequence object 18578hashObject = (HASH_OBJECT *)ObjectGet(g_DRTMHandle); 18579// Is this _TPM_Hash_End after Startup or before 18580if(TPMIsStarted()) 18581{ 18582// After 18583// Reset the DRTM PCR 18584PCRResetDynamics(); 18585// Extend the DRTM_PCR. 18586pcrHandle = PCR_FIRST + DRTM_PCR; 18587// DRTM sequence increments restartCount 18588gr.restartCount++; 18589} 18590else 18591{ 18592pcrHandle = PCR_FIRST + HCRTM_PCR; 18593} 18594// Complete hash and extend PCR, or if this is an HCRTM, complete 18595// the hash and write the PCR 18596for(i = 0; i < HASH_COUNT; i++) 18597{ 18598TPMI_ALG_HASH 18599hash = CryptGetHashAlgByIndex(i); 18600// Complete hash 18601digest.t.size = CryptGetHashDigestSize(hash); 18602CryptCompleteHash2B(&hashObject->state.hashState[i], &digest.b); 18603// If this is DRTM, extend to zeroed PCR 18604// If this is H-DRTM, copy to HCRM PCR 18605if(TPMIsStarted()) 18606// Extend PCR 18607PCRExtend(pcrHandle, hash, digest.t.size, digest.t.buffer); 18608else 18609PcrWrite(pcrHandle, hash, &digest); 18610 18611Family “2.0” 18612Level 00 Revision 00.99 18613 18614Published 18615Copyright © TCG 2006-2013 18616 18617Page 227 18618October 31, 2013 18619 18620 Part 3: Commands 1862158 1862259 1862360 1862461 1862562 1862663 1862764 1862865 1862966 1863067 1863168 18632 18633Trusted Platform Module Library 18634 18635} 18636// Flush sequence object. 18637ObjectFlush(g_DRTMHandle); 18638g_DRTMHandle = TPM_RH_UNASSIGNED; 18639g_DrtmPreStartup = TRUE; 18640return; 18641} 18642 18643Page 228 18644October 31, 2013 18645 18646Published 18647Copyright © TCG 2006-2013 18648 18649Family “2.0” 18650Level 00 Revision 00.99 18651 18652 Trusted Platform Module Library 18653 1865425 18655 18656Part 3: Commands 18657 18658Enhanced Authorization (EA) Commands 18659 1866025.1 18661 18662Introduction 18663 18664The commands in this clause 1 are used for policy evaluation. When successful, each command will 18665update the policySession→policyDigest in a policy session context in order to establish that the 18666authorizations required to use an object have been provided. Many of the commands will also modify 18667other parts of a policy context so that the caller may constrain the scope of the authorization that is 18668provided. 18669NOTE 1 18670 18671Many of the terms used in this clause are described in detail i n Part 1 and are not redefined in this 18672clause. 18673 18674The policySession parameter of the command is the handle of the policy session context to be modified 18675by the command. 18676If the policySession parameter indicates a trial policy session, then the policySession→policyDigest will 18677be updated and the indicated validations are not performed. 18678NOTE 2 18679 18680A policy session is a trial policy by TPM2_StartAuthSession( sessionType = TPM_SE_TRIAL). 18681 18682NOTE 3 18683 18684Unless there is an unmarshaling error in the parameters of the command, these commands will 18685return TPM_RC_SUCCESS when policySession references a trial session. 18686 18687NOTE 4 18688 18689Policy context other than the policySession→policyDigest may be updated for a trial policy but it is 18690not required. 18691 18692Family “2.0” 18693Level 00 Revision 00.99 18694 18695Published 18696Copyright © TCG 2006-2013 18697 18698Page 229 18699October 31, 2013 18700 18701 Part 3: Commands 18702 1870325.2 18704 18705Trusted Platform Module Library 18706 18707Signed Authorization Actions 18708 1870925.2.1 Introduction 18710The TPM2_PolicySigned, TPM_PolicySecret, and TPM2_PolicyTicket commands use many of the same 18711functions. This clause consolidates those functions to simplify the document and to ensure uniformity of 18712the operations. 1871325.2.2 Policy Parameter Checks 18714These parameter checks will be performed when indicated in the description of each of the commands: 18715a) nonceTPM – If this parameter is not the Empty Buffer, and 18716policySession→nonceTPM, then the TPM shall return TPM_RC_VALUE. 18717 18718it 18719 18720does 18721 18722not 18723 18724match 18725 18726b) expiration – If this parameter is not zero, then its absolute value is compared to the time in seconds 18727since the policySession→nonceTPM was generated. If more time has passed than indicted in 18728expiration, the TPM shall return TPM_RC_EXPIRED. If nonceTPM is the Empty buffer, and expiration 18729is non-zero, then the TPM shall return TPM_RC_EXPIRED. 18730c) timeout – This parameter is compared to the current TPM time. If policySession→timeout is in the 18731past, then the TPM shall return TPM_RC_EXPIRED. 18732NOTE 1 18733 18734The expiration parameter is present in the TPM2_PolicySigned and TPM2_PolicySecret 18735command and timeout is the analogous parameter in the TPM2_PolicyTicket command. 18736 18737d) cpHashA – If this parameter is not an Empty Buffer 18738NOTE 2 18739 18740CpHashA is the hash of the command to be executed using this policy session in the 18741authorization. The algorithm used to compute this hash is required to be the algorithm of the 18742policy session. 18743 187441) the TPM shall return TPM_RC_CPHASH if policySession→cpHash does not have its default 18745value or the contents of policySession→cpHash are not the same as cpHashA; or 18746NOTE 3 18747 18748CpHash is the expected cpHash value held in the policy session context. 18749 187502) the TPM shall return TPM_RC_SIZE 18751policySession→policyDigest. 18752NOTE 4 18753 18754Page 230 18755October 31, 2013 18756 18757if 18758 18759cpHashA 18760 18761is 18762 18763not 18764 18765the 18766 18767same 18768 18769size 18770 18771as 18772 18773PolicySession→policyDigest is the size of the digest produced by the hash algorithm used to 18774compute policyDigest. 18775 18776Published 18777Copyright © TCG 2006-2013 18778 18779Family “2.0” 18780Level 00 Revision 00.99 18781 18782 Trusted Platform Module Library 18783 18784Part 3: Commands 18785 1878625.2.3 PolicyDigest Update Function (PolicyUpdate()) 18787This is the update process for policySession→policyDigest used by TPM2_PolicySigned(), 18788TPM2_PolicySecret(), TPM2_PolicyTicket(), and TPM2_PolicyAuthorize(). The function prototype for the 18789update function is: 18790 18791PolicyUpdate(commandCode, arg2, arg3) 18792 18793(9) 18794 18795where 18796 18797arg2 18798 18799a TPM2B_NAME 18800 18801arg3 18802 18803a TPM2B 18804 18805These parameters are used to update policySession→policyDigest by 18806 18807policyDigestnew ≔ HpolicyAlg(policyDigestold || commandCode || arg2.name) 18808 18809(10) 18810 18811policyDigestnew+1 ≔ HpolicyAlg(policyDigestnew || arg3.buffer) 18812 18813(11) 18814 18815followed by 18816 18817where 18818 18819HpolicyAlg() 18820 18821the hash algorithm chosen when the policy session was started 18822 18823NOTE 1 18824 18825If arg3 is a TPM2B_NAME, then arg3.buffer will actually be an arg3.name. 18826 18827NOTE 2 18828 18829The arg2.size and arg3.size fields are not included in the hashes. 18830 18831NOTE 3 18832 18833PolicyUpdate() uses two hashes because arg2 and arg3 are variable-sized and the concatenation of 18834arg2 and arg3 in a single hash could produce the same digest even though arg2 and arg3 are 18835different. Processing of the arguments separately in different Extend operation insures that the 18836digest produced by PolicyUpdate() will be different if arg2 and arg3 are different. 18837 18838Family “2.0” 18839Level 00 Revision 00.99 18840 18841Published 18842Copyright © TCG 2006-2013 18843 18844Page 231 18845October 31, 2013 18846 18847 Part 3: Commands 18848 18849Trusted Platform Module Library 18850 1885125.2.4 Policy Context Updates 18852When a policy command modifies some part of the policy session context other than the 18853policySession→policyDigest, the following rules apply. 18854 18855 18856cpHash – this parameter may only be changed if it contains its initialization value (an Empty String). 18857If cpHash is not the Empty String when a policy command attempts to update it, the TPM will return 18858an error (TPM_RC_CPHASH) if the current and update values are not the same. 18859 18860 18861 18862timeOut – this parameter may only be changed to a smaller value. If a command attempts to update 18863this value with a larger value (longer into the future), the TPM will discard the update value. This is 18864not an error condition. 18865 18866 18867 18868commandCode – once set by a policy command, this value may not be change except by 18869TPM2_PolicyRestart(). If a policy command tries to change this to a different value, an error is 18870returned (TPM_RC_POLICY_CC). 18871 18872 18873 18874pcrUpdateCounter – this parameter is updated by TPM2_PolicyPCR(). This value may only be set 18875once during a policy. Each time TPM2_PolicyPCR() executes, it checks to see if 18876policySession→pcrUpdateCounter has its default state indicating that this is the first 18877TPM2_PolicyPCR(). If it has its default value, then policySession→pcrUpdateCounter is set to the 18878current value of pcrUpdateCounter. If policySession→pcrUpdateCounter does not have its default 18879value and its value is not the same as pcrUpdateCounter, the TPM shall return 18880TPM_RC_PCR_CHANGED. 18881NOTE 18882 18883If this parameter and pcrUpdateCounter are not the same, it indicates that PCR have changed 18884since checked by the previous TPM2_PolicyPCR(). Since they have changed, the previous PCR 18885validation is no longer valid. 18886 18887 18888 18889commandLocality – this parameter is the logical AND of all enabled localities. All localities are 18890enabled for a policy when the policy session is created. TPM2_PolicyLocalities() selectively disables 18891localities. Once use of a policy for a locality has been disabled, it cannot be enabled except by 18892TPM2_PolicyRestart(). 18893 18894 18895 18896isPPRequired – once SET, this parameter may only be CLEARed by TPM2_PolicyRestart(). 18897 18898 18899 18900isAuthValueNeeded – once SET, this parameter may only be CLEARed by TPM2_PolicyPassword() 18901or TPM2_PolicyRestart(). 18902 18903 18904 18905isPasswordNeeded – once SET, this parameter may only be CLEARed by TPM2_PolicyAuthValue() 18906or TPM2_PolicyRestart(), 18907 18908NOTE 18909 18910Both TPM2_PolicyAuthValue() and TPM2_PolicyPassword() change policySession→policyDigest in 18911the same way. The different commands simply indicate to the TPM the format used for the authValue 18912(HMAC or clear text). Both commands could be in the same policy. The final instance of these 18913commands determines the format. 18914 18915Page 232 18916October 31, 2013 18917 18918Published 18919Copyright © TCG 2006-2013 18920 18921Family “2.0” 18922Level 00 Revision 00.99 18923 18924 Trusted Platform Module Library 18925 18926Part 3: Commands 18927 1892825.2.5 Policy Ticket Creation 18929If for TPM2_PolicySigned() or TPM2_PolicySecret() the caller specified a negative value for expiration, 18930and the policy update succeeds, then the TPM will return a ticket that includes a value indicating when 18931the authorization expires. The required computation for the digest in the authorization ticket is: 18932 18933HMAC(proof, HpolicyAlg(ticketType || timeout || cpHashA || policyRef || authObject→Name)) (12) 18934where 18935 18936proof 18937 18938secret associated with the storage primary seed (SPS) of the 18939TPM 18940 18941HpolicyAlg 18942 18943hash function using the hash algorithm associated with the policy 18944session 18945 18946ticketType 18947 18948either TPM_ST_AUTH_SECRET or TPM_ST_AUTH_SIGNED, 18949used to indicate type of the ticket 18950 18951NOTE 1 18952 18953If 18954the 18955ticket 18956is 18957produced 18958by 18959TPM2_PolicySecret() 18960then 18961ticketType 18962is 18963TPM_ST_AUTH_SECRET and if produced by TPM2_PolicySigned() then ticketType is 18964TPM_ST_AUTH_SIGNED. 18965 18966timeout 18967 18968NOTE 2 18969 18970implementation-specific representation of the expiration time of 18971the ticket; required to be the implementation equivalent of 18972policySession→startTime plus the absolute value of expiration 18973Timeout is not the same as expiration. The expiration value in the aHash is a relative time, 18974using the creation time of the authorization session (TPM2_StartAuthSession()) as its 18975reference. The timeout parameter is an absolute time, using TPM Clock as the reference. 18976 18977cpHashA 18978 18979the command parameter digest for the command being 18980authorized; computed using the hash algorithm of the policy 18981session 18982 18983policyRef 18984 18985the commands that use this function have a policyRef parameter 18986and the value of that parameter is used here 18987 18988authObject→Name 18989 18990Name associated with the authObject parameter 18991 18992Family “2.0” 18993Level 00 Revision 00.99 18994 18995Published 18996Copyright © TCG 2006-2013 18997 18998Page 233 18999October 31, 2013 19000 19001 Part 3: Commands 1900225.3 19003 19004Trusted Platform Module Library 19005 19006TPM2_PolicySigned 19007 1900825.3.1 General Description 19009This command includes a signed authorization in a policy. The command ties the policy to a signing key 19010by including the Name of the signing key in the policyDigest 19011If policySession is a trial session, the TPM will not check the signature and will update 19012policySession→policyDigest as described in 25.2.3 as if a properly signed authorization was received; but 19013no ticket will be produced. 19014If policySession is not a trial session, the TPM will validate auth and only perform the update if it is a valid 19015signature over the fields of the command. 19016The authorizing object will sign a digest of the authorization qualifiers: nonceTPM, expiration, cpHashA, 19017and policyRef. The digest is computed as: 19018 19019aHash ≔ HauthAlg(nonceTPM || expiration || cpHashA || policyRef) 19020 19021(13) 19022 19023where 19024 19025HauthAlg() 19026NOTE 1 19027 19028the hash associated with the auth parameter of this command 19029Each signature and key combination indicates the scheme and each scheme has an 19030associated hash. 19031 19032nonceTPM 19033 19034the nonceTPM parameter from the TPM2_StartAuthSession() 19035response. If the authorization is not limited to this session, the 19036size of this value is zero. 19037 19038expiration 19039 19040time limit on authorization set by authorizing object. This 32-bit 19041value is set to zero if the expiration time is not being set. 19042 19043cpHashA 19044 19045digest of the command parameters for the command being 19046approved using the hash algorithm of the policy session. Set to 19047an EmptyAuth if the authorization is not limited to a specific 19048command. 19049 19050NOTE 2 19051 19052This is not the cpHash of this TPM2_PolicySigned() command. 19053 19054policyRef 19055EXAMPLE 19056 19057an opaque value determined by the authorizing entity. Set to the 19058Empty Buffer if no value is present. 19059 19060The computation for an aHash if there are no restrictions is: 19061 19062aHash ≔ HauthAlg(00 00 00 0016) 19063which is the hash of an expiration time of zero. 19064 19065The aHash is signed by the private key associated with key. The signature and signing parameters are 19066combined to create the auth parameter. 19067The TPM will perform the parameter checks listed in 25.2.2 19068If the parameter checks succeed, the TPM will construct a test digest (tHash) over the provided 19069parameters using the same formulation a shown in equation (13) above. 19070If tHash does not match the digest of the signed aHash, then the authorization fails and the TPM shall 19071return TPM_RC_POLICY_FAIL and make no change to policySession→policyDigest. 19072 19073Page 234 19074October 31, 2013 19075 19076Published 19077Copyright © TCG 2006-2013 19078 19079Family “2.0” 19080Level 00 Revision 00.99 19081 19082 Trusted Platform Module Library 19083 19084Part 3: Commands 19085 19086When all validations have succeeded, policySession→policyDigest is updated by PolicyUpdate() (see 1908725.2.3). 19088 19089PolicyUpdate(TPM_CC_PolicySigned, authObject→Name, policyRef) 19090 19091(14) 19092 19093If the cpHashA parameter is not an Empty Buffer, it is copied to policySession→cpHash. 19094The TPM will optionally produce a ticket as described in 25.2.5. 19095Authorization to use authObject is not required. 19096 19097Family “2.0” 19098Level 00 Revision 00.99 19099 19100Published 19101Copyright © TCG 2006-2013 19102 19103Page 235 19104October 31, 2013 19105 19106 Part 3: Commands 19107 19108Trusted Platform Module Library 19109 1911025.3.2 Command and Response 19111Table 113 — TPM2_PolicySigned Command 19112Type 19113 19114Name 19115 19116TPMI_ST_COMMAND_TAG 19117 19118tag 19119 19120UINT32 19121 19122commandSize 19123 19124TPM_CC 19125 19126commandCode 19127 19128TPM_CC_PolicySigned 19129 19130TPMI_DH_OBJECT 19131 19132authObject 19133 19134handle for a public key that will validate the signature 19135Auth Index: None 19136 19137TPMI_SH_POLICY 19138 19139policySession 19140 19141handle for the policy session being extended 19142Auth Index: None 19143 19144TPM2B_NONCE 19145 19146nonceTPM 19147 19148the policy nonce for the session 19149If the nonce is not included in the authorization 19150qualification, this field is the Empty Buffer. 19151 19152cpHashA 19153 19154digest of the command parameters to which this 19155authorization is limited 19156This is not the cpHash for this command but the cpHash 19157for the command to which this policy session will be 19158applied. If it is not limited, the parameter will be the 19159Empty Buffer. 19160 19161TPM2B_NONCE 19162 19163policyRef 19164 19165a reference to a policy relating to the authorization – 19166may be the Empty Buffer 19167Size is limited to be no larger than the nonce size 19168supported on the TPM. 19169 19170INT32 19171 19172expiration 19173 19174time when authorization will expire, measured in 19175seconds from the time that nonceTPM was generated 19176If expiration is zero, a NULL Ticket is returned. 19177 19178TPMT_SIGNATURE 19179 19180auth 19181 19182signed authorization (not optional) 19183 19184TPM2B_DIGEST 19185 19186Description 19187 19188Table 114 — TPM2_PolicySigned Response 19189Type 19190 19191Name 19192 19193Description 19194 19195TPM_ST 19196 19197tag 19198 19199see clause 8 19200 19201UINT32 19202 19203responseSize 19204 19205TPM_RC 19206 19207responseCode 19208 19209TPM2B_TIMEOUT 19210 19211timeout 19212 19213TPMT_TK_AUTH 19214 19215policyTicket 19216 19217Page 236 19218October 31, 2013 19219 19220implementation-specific time value, used to indicate to 19221the TPM when the ticket expires 19222NOTE 19223 19224If policyTicket is a NULL Ticket, then this shall be 19225the Empty Buffer. 19226 19227produced if the command succeeds and expiration in 19228the command was non-zero; this ticket will use the 19229TPMT_ST_AUTH_SIGNED structure tag 19230 19231Published 19232Copyright © TCG 2006-2013 19233 19234Family “2.0” 19235Level 00 Revision 00.99 19236 19237 Trusted Platform Module Library 19238 19239Part 3: Commands 19240 1924125.3.3 Detailed Actions 192421 192432 192443 19245 19246#include "InternalRoutines.h" 19247#include "Policy_spt_fp.h" 19248#include "PolicySigned_fp.h" 19249Error Returns 19250TPM_RC_CPHASH 19251 19252cpHash was previously set to a different value 19253 19254TPM_RC_EXPIRED 19255 19256expiration indicates a time in the past or expiration is non-zero but no 19257nonceTPM is present 19258 19259TPM_RC_HANDLE 19260 19261authObject need to have sensitive portion loaded 19262 19263TPM_RC_KEY 19264 19265authObject is not a signing scheme 19266 19267TPM_RC_NONCE 19268 19269nonceTPM is not the nonce associated with the policySession 19270 19271TPM_RC_SCHEME 19272 19273the signing scheme of auth is not supported by the TPM 19274 19275TPM_RC_SIGNATURE 19276 19277the signature is not genuine 19278 19279TPM_RC_SIZE 19280 19281input cpHash has wrong size 19282 19283TPM_RC_VALUE 19284 192854 192865 192876 192887 192898 192909 1929110 1929211 1929312 1929413 1929514 1929615 1929716 1929817 1929918 1930019 1930120 1930221 1930322 1930423 1930524 1930625 1930726 1930827 1930928 1931029 1931130 1931231 1931332 1931433 1931534 1931635 1931736 1931837 1931938 1932039 19321 19322Meaning 19323 19324input policyID or expiration does not match the internal data in policy 19325session 19326 19327TPM_RC 19328TPM2_PolicySigned( 19329PolicySigned_In 19330PolicySigned_Out 19331 19332*in, 19333*out 19334 19335// IN: input parameter list 19336// OUT: output parameter list 19337 19338TPM_RC 19339SESSION 19340OBJECT 19341TPM2B_NAME 19342TPM2B_DIGEST 19343HASH_STATE 19344UINT32 19345 19346result = TPM_RC_SUCCESS; 19347*session; 19348*authObject; 19349entityName; 19350authHash; 19351hashState; 19352expiration = (in->expiration < 0) 19353? -(in->expiration) : in->expiration; 19354authTimeout = 0; 19355 19356) 19357{ 19358 19359UINT64 19360// Input Validation 19361 19362// Set up local pointers 19363session = SessionGet(in->policySession); 19364authObject = ObjectGet(in->authObject); 19365 19366// the session structure 19367// pointer for the object 19368// 19369providing authorization 19370// 19371signature 19372 19373// Only do input validation if this is not a trial policy session 19374if(session->attributes.isTrialPolicy == CLEAR) 19375{ 19376if(expiration != 0) 19377authTimeout = expiration * 1000 + session->startTime; 19378result = PolicyParameterChecks(session, authTimeout, 19379&in->cpHashA, &in->nonceTPM, 19380RC_PolicySigned_nonceTPM, 19381RC_PolicySigned_cpHashA, 19382RC_PolicySigned_expiration); 19383if(result != TPM_RC_SUCCESS) 19384 19385Family “2.0” 19386Level 00 Revision 00.99 19387 19388Published 19389Copyright © TCG 2006-2013 19390 19391Page 237 19392October 31, 2013 19393 19394 Part 3: Commands 1939540 1939641 1939742 1939843 1939944 1940045 1940146 1940247 1940348 1940449 1940550 1940651 1940752 1940853 1940954 1941055 1941156 1941257 1941358 1941459 1941560 1941661 1941762 1941863 1941964 1942065 1942166 1942267 1942368 1942469 1942570 1942671 1942772 1942873 1942974 1943075 1943176 1943277 1943378 1943479 1943580 1943681 1943782 1943883 1943984 1944085 1944186 1944287 1944388 1944489 1944590 1944691 1944792 1944893 1944994 1945095 1945196 1945297 1945398 1945499 19455100 19456101 19457102 19458103 19459 19460Trusted Platform Module Library 19461 19462return result; 19463// Re-compute the digest being signed 19464/*(See part 3 specification) 19465// The digest is computed as: 19466// 19467aHash := hash ( nonceTPM | expiration | cpHashA | policyRef) 19468// where: 19469// 19470hash() 19471the hash associated with the signed auth 19472// 19473nonceTPM 19474the nonceTPM value from the TPM2_StartAuthSession . 19475// 19476response If the authorization is not limited to this 19477// 19478session, the size of this value is zero. 19479// 19480expiration time limit on authorization set by authorizing object. 19481// 19482This 32-bit value is set to zero if the expiration 19483// 19484time is not being set. 19485// 19486cpHashA 19487hash of the command parameters for the command being 19488// 19489approved using the hash algorithm of the PSAP session. 19490// 19491Set to NULLauth if the authorization is not limited 19492// 19493to a specific command. 19494// 19495policyRef 19496hash of an opaque value determined by the authorizing 19497// 19498object. Set to the NULLdigest if no hash is present. 19499*/ 19500// Start hash 19501authHash.t.size = CryptStartHash(CryptGetSignHashAlg(&in->auth), 19502&hashState); 19503// add nonceTPM 19504CryptUpdateDigest2B(&hashState, &in->nonceTPM.b); 19505// add expiration 19506CryptUpdateDigestInt(&hashState, sizeof(UINT32), (BYTE*) &in->expiration); 19507// add cpHashA 19508CryptUpdateDigest2B(&hashState, &in->cpHashA.b); 19509// add policyRef 19510CryptUpdateDigest2B(&hashState, &in->policyRef.b); 19511// Complete digest 19512CryptCompleteHash2B(&hashState, &authHash.b); 19513// Validate Signature. A TPM_RC_SCHEME, TPM_RC_TYPE or TPM_RC_SIGNATURE 19514// error may be returned at this point 19515result = CryptVerifySignature(in->authObject, &authHash, &in->auth); 19516if(result != TPM_RC_SUCCESS) 19517return RcSafeAddToResult(result, RC_PolicySigned_auth); 19518} 19519// Internal Data Update 19520// Need the Name of the signing entity 19521entityName.t.size = EntityGetName(in->authObject, &entityName.t.name); 19522// Update policy with input policyRef and name of auth key 19523// These values are updated even if the session is a trial session 19524PolicyContextUpdate(TPM_CC_PolicySigned, &entityName, &in->policyRef, 19525&in->cpHashA, authTimeout, session); 19526// Command Output 19527// Create ticket and timeout buffer if in->expiration < 0 and this is not 19528// a trial session. 19529// NOTE: PolicyParameterChecks() makes sure that nonceTPM is present 19530// when expiration is non-zero. 19531if( 19532in->expiration < 0 19533&& session->attributes.isTrialPolicy == CLEAR 19534) 19535 19536Page 238 19537October 31, 2013 19538 19539Published 19540Copyright © TCG 2006-2013 19541 19542Family “2.0” 19543Level 00 Revision 00.99 19544 19545 Trusted Platform Module Library 19546104 19547105 19548106 19549107 19550108 19551109 19552110 19553111 19554112 19555113 19556114 19557115 19558116 19559117 19560118 19561119 19562120 19563121 19564122 19565123 19566124 19567125 19568126 19569127 19570128 19571129 19572130 19573131 19574132 19575 19576Part 3: Commands 19577 19578{ 19579// Generate timeout buffer. The format of output timeout buffer is 19580// TPM-specific. 19581// Note: can't do a direct copy because the output buffer is a byte 19582// array and it may not be aligned to accept a 64-bit value. The method 19583// used has the side-effect of making the returned value a big-endian, 19584// 64-bit value that is byte aligned. 19585out->timeout.t.size = sizeof(UINT64); 19586UINT64_TO_BYTE_ARRAY(authTimeout, out->timeout.t.buffer); 19587// Compute policy ticket 19588TicketComputeAuth(TPM_ST_AUTH_SIGNED, EntityGetHierarchy(in->authObject), 19589authTimeout, &in->cpHashA, &in->policyRef, &entityName, 19590&out->policyTicket); 19591} 19592else 19593{ 19594// Generate a null ticket. 19595// timeout buffer is null 19596out->timeout.t.size = 0; 19597// auth ticket is null 19598out->policyTicket.tag = TPM_ST_AUTH_SIGNED; 19599out->policyTicket.hierarchy = TPM_RH_NULL; 19600out->policyTicket.digest.t.size = 0; 19601} 19602return TPM_RC_SUCCESS; 19603} 19604 19605Family “2.0” 19606Level 00 Revision 00.99 19607 19608Published 19609Copyright © TCG 2006-2013 19610 19611Page 239 19612October 31, 2013 19613 19614 Part 3: Commands 19615 1961625.4 19617 19618Trusted Platform Module Library 19619 19620TPM2_PolicySecret 19621 1962225.4.1 General Description 19623This command includes a secret-based authorization to a policy. The caller proves knowledge of the 19624secret value using an authorization session using the authValue associated with authHandle. A 19625password session, an HMAC session, or a policy session containing TPM2_PolicyAuthValue() or 19626TPM2_PolicyPassword() will satisfy this requirement. 19627“If a policy session is used and use of the authValue of authHandle is not required, the TPM will return 19628TPM_RC_MODE.” 19629The secret is the authValue of authObject, which may be any TPM entity with a handle and an associated 19630authValue. This includes the reserved handles (for example, Platform, Storage, and Endorsement), NV 19631Indexes, and loaded objects. 19632NOTE 1 19633 19634The authorization value for a hierarchy cannot be used in th is command if the hierarchy is disabled. 19635 19636If the authorization check fails, then the normal dictionary attack logic is invoked. 19637If the authorization provided by the authorization session is valid, the command parameters are checked 19638as described in 25.2.2. 19639When all validations have succeeded, policySession→policyDigest is updated by PolicyUpdate() (see 1964025.2.3). 19641 19642PolicyUpdate(TPM_CC_PolicySecret, authObject→Name, policyRef) 19643 19644(15) 19645 19646If the cpHashA command parameter is not an Empty Buffer, it is copied to cpHash in the session context. 19647The TPM will optionally produce a ticket as described in 25.2.5. 19648If the session is a trial session, policySession→policyDigest is updated as if the authorization is valid but 19649no check is performed. 19650NOTE 2 19651 19652If an HMAC is used to convey the authorization, a separate session is needed for the authorization. 19653Because the HMAC in that authorization will include a nonce that prevents replay of the 19654authorization, the value of the nonceTPM parameter in this command is limited. It is retained mostly 19655to provide processing consistency with TPM2_PolicySigned(). 19656 19657Page 240 19658October 31, 2013 19659 19660Published 19661Copyright © TCG 2006-2013 19662 19663Family “2.0” 19664Level 00 Revision 00.99 19665 19666 Trusted Platform Module Library 19667 19668Part 3: Commands 19669 1967025.4.2 Command and Response 19671Table 115 — TPM2_PolicySecret Command 19672Type 19673 19674Name 19675 19676Description 19677 19678TPMI_ST_COMMAND_TAG 19679 19680tag 19681 19682see clause 8 19683 19684UINT32 19685 19686commandSize 19687 19688TPM_CC 19689 19690commandCode 19691 19692TPM_CC_PolicySecret 19693 19694TPMI_DH_ENTITY 19695 19696@authHandle 19697 19698handle for an entity providing the authorization 19699Auth Index: 1 19700Auth Role: USER 19701 19702TPMI_SH_POLICY 19703 19704policySession 19705 19706handle for the policy session being extended 19707Auth Index: None 19708 19709TPM2B_NONCE 19710 19711nonceTPM 19712 19713the policy nonce for the session 19714If the nonce is not included in the authorization 19715qualification, this field is the Empty Buffer. 19716 19717cpHashA 19718 19719digest of the command parameters to which this 19720authorization is limited 19721This not the cpHash for this command but the cpHash 19722for the command to which this policy session will be 19723applied. If it is not limited, the parameter will be the 19724Empty Buffer. 19725 19726TPM2B_NONCE 19727 19728policyRef 19729 19730a reference to a policy relating to the authorization – 19731may be the Empty Buffer 19732Size is limited to be no larger than the nonce size 19733supported on the TPM. 19734 19735INT32 19736 19737expiration 19738 19739time when authorization will expire, measured in 19740seconds from the time that nonceTPM was generated 19741If expiration is zero, a NULL Ticket is returned. 19742 19743TPM2B_DIGEST 19744 19745Table 116 — TPM2_PolicySecret Response 19746Type 19747 19748Name 19749 19750Description 19751 19752TPM_ST 19753 19754tag 19755 19756see clause 8 19757 19758UINT32 19759 19760responseSize 19761 19762TPM_RC 19763 19764responseCode 19765 19766TPM2B_TIMEOUT 19767 19768timeout 19769 19770implementation-specific time value used to indicate to 19771the TPM when the ticket expires; this ticket will use the 19772TPMT_ST_AUTH_SECRET structure tag 19773 19774TPMT_TK_AUTH 19775 19776policyTicket 19777 19778produced if the command succeeds and expiration in 19779the command was non-zero 19780 19781Family “2.0” 19782Level 00 Revision 00.99 19783 19784Published 19785Copyright © TCG 2006-2013 19786 19787Page 241 19788October 31, 2013 19789 19790 Part 3: Commands 19791 19792Trusted Platform Module Library 19793 1979425.4.3 Detailed Actions 197951 197962 197973 19798 19799#include "InternalRoutines.h" 19800#include "PolicySecret_fp.h" 19801#include "Policy_spt_fp.h" 19802Error Returns 19803TPM_RC_CPHASH 19804 19805cpHash for policy was previously set to a value that is not the same 19806as cpHashA 19807 19808TPM_RC_EXPIRED 19809 19810expiration indicates a time in the past 19811 19812TPM_RC_NONCE 19813 19814nonceTPM does not match the nonce associated with policySession 19815 19816TPM_RC_SIZE 19817 19818cpHashA is not the size of a digest for the hash associated with 19819policySession 19820 19821TPM_RC_VALUE 19822 198234 198245 198256 198267 198278 198289 1982910 1983011 1983112 1983213 1983314 1983415 1983516 1983617 1983718 1983819 1983920 1984021 1984122 1984223 1984324 1984425 1984526 1984627 1984728 1984829 1984930 1985031 1985132 1985233 1985334 1985435 1985536 1985637 1985738 1985839 1985940 1986041 1986142 1986243 1986344 19864 19865Meaning 19866 19867input policyID or expiration does not match the internal data in policy 19868session 19869 19870TPM_RC 19871TPM2_PolicySecret( 19872PolicySecret_In 19873PolicySecret_Out 19874 19875*in, 19876*out 19877 19878// IN: input parameter list 19879// OUT: output parameter list 19880 19881TPM_RC 19882SESSION 19883TPM2B_NAME 19884UINT32 19885 19886result; 19887*session; 19888entityName; 19889expiration = (in->expiration < 0) 19890? -(in->expiration) : in->expiration; 19891authTimeout = 0; 19892 19893) 19894{ 19895 19896UINT64 19897// Input Validation 19898 19899// Get pointer to the session structure 19900session = SessionGet(in->policySession); 19901//Only do input validation if this is not a trial policy session 19902if(session->attributes.isTrialPolicy == CLEAR) 19903{ 19904if(expiration != 0) 19905authTimeout = expiration * 1000 + session->startTime; 19906result = PolicyParameterChecks(session, authTimeout, 19907&in->cpHashA, &in->nonceTPM, 19908RC_PolicySecret_nonceTPM, 19909RC_PolicySecret_cpHashA, 19910RC_PolicySecret_expiration); 19911if(result != TPM_RC_SUCCESS) 19912return result; 19913} 19914// Internal Data Update 19915// Need the name of the authorizing entity 19916entityName.t.size = EntityGetName(in->authHandle, &entityName.t.name); 19917// Update policy context with input policyRef and name of auth key 19918// This value is computed even for trial sessions. Possibly update the cpHash 19919PolicyContextUpdate(TPM_CC_PolicySecret, &entityName, &in->policyRef, 19920 19921Page 242 19922October 31, 2013 19923 19924Published 19925Copyright © TCG 2006-2013 19926 19927Family “2.0” 19928Level 00 Revision 00.99 19929 19930 Trusted Platform Module Library 1993145 1993246 1993347 1993448 1993549 1993650 1993751 1993852 1993953 1994054 1994155 1994256 1994357 1994458 1994559 1994660 1994761 1994862 1994963 1995064 1995165 1995266 1995367 1995468 1995569 1995670 1995771 1995872 1995973 1996074 1996175 1996276 1996377 1996478 1996579 1996680 1996781 1996882 1996983 19970 19971Part 3: Commands 19972 19973&in->cpHashA, authTimeout, session); 19974// Command Output 19975// Create ticket and timeout buffer if in->expiration < 0 and this is not 19976// a trial session. 19977// NOTE: PolicyParameterChecks() makes sure that nonceTPM is present 19978// when expiration is non-zero. 19979if( 19980in->expiration < 0 19981&& session->attributes.isTrialPolicy == CLEAR 19982) 19983{ 19984// Generate timeout buffer. The format of output timeout buffer is 19985// TPM-specific. 19986// Note: can't do a direct copy because the output buffer is a byte 19987// array and it may not be aligned to accept a 64-bit value. The method 19988// used has the side-effect of making the returned value a big-endian, 19989// 64-bit value that is byte aligned. 19990out->timeout.t.size = sizeof(UINT64); 19991UINT64_TO_BYTE_ARRAY(authTimeout, out->timeout.t.buffer); 19992// Compute policy ticket 19993TicketComputeAuth(TPM_ST_AUTH_SECRET, EntityGetHierarchy(in->authHandle), 19994authTimeout, &in->cpHashA, &in->policyRef, 19995&entityName, &out->policyTicket); 19996} 19997else 19998{ 19999// timeout buffer is null 20000out->timeout.t.size = 0; 20001// auth ticket is null 20002out->policyTicket.tag = TPM_ST_AUTH_SECRET; 20003out->policyTicket.hierarchy = TPM_RH_NULL; 20004out->policyTicket.digest.t.size = 0; 20005} 20006return TPM_RC_SUCCESS; 20007} 20008 20009Family “2.0” 20010Level 00 Revision 00.99 20011 20012Published 20013Copyright © TCG 2006-2013 20014 20015Page 243 20016October 31, 2013 20017 20018 Part 3: Commands 20019 2002025.5 20021 20022Trusted Platform Module Library 20023 20024TPM2_PolicyTicket 20025 2002625.5.1 General Description 20027This command is similar to TPM2_PolicySigned() except that it takes a ticket instead of a signed 20028authorization. The ticket represents a validated authorization that had an expiration time associated with 20029it. 20030The parameters of this command are checked as described in 25.2.2. 20031If the checks succeed, the TPM uses the timeout, cpHashA, policyRef, and keyName to construct a ticket 20032to compare with the value in ticket. If these tickets match, then the TPM will create a TPM2B_NAME 20033(objectName) using authName and update the context of policySession by PolicyUpdate() (see 25.2.3). 20034 20035PolicyUpdate(commandCode, authName, policyRef) 20036 20037(16) 20038 20039If the structure tag of ticket is TPM_ST_AUTH_SECRET, then commandCode will be 20040TPM_CC_PolicySecret. If the structure tag of ticket is TPM_ST_AUTH_SIGNED, then commandCode will 20041be TPM_CC_PolicySIgned. 20042If the cpHashA command parameter is not an Empty Buffer, it may be copied to cpHash in the session 20043context.as described in 25.2.1. 20044 20045Page 244 20046October 31, 2013 20047 20048Published 20049Copyright © TCG 2006-2013 20050 20051Family “2.0” 20052Level 00 Revision 00.99 20053 20054 Trusted Platform Module Library 20055 20056Part 3: Commands 20057 2005825.5.2 Command and Response 20059Table 117 — TPM2_PolicyTicket Command 20060Type 20061 20062Name 20063 20064Description 20065 20066TPMI_ST_COMMAND_TAG 20067 20068tag 20069 20070see clause 8 20071 20072UINT32 20073 20074commandSize 20075 20076TPM_CC 20077 20078commandCode 20079 20080TPM_CC_PolicyTicket 20081 20082TPMI_SH_POLICY 20083 20084policySession 20085 20086handle for the policy session being extended 20087Auth Index: None 20088 20089TPM2B_TIMEOUT 20090 20091timeout 20092 20093time when authorization will expire 20094The contents are TPM specific. This shall be the value 20095returned when ticket was produced. 20096 20097TPM2B_DIGEST 20098 20099cpHashA 20100 20101digest of the command parameters to which this 20102authorization is limited 20103If it is not limited, the parameter will be the Empty 20104Buffer. 20105 20106TPM2B_NONCE 20107 20108policyRef 20109 20110reference to a qualifier for the policy – may be the 20111Empty Buffer 20112 20113TPM2B_NAME 20114 20115authName 20116 20117name of the object that provided the authorization 20118 20119TPMT_TK_AUTH 20120 20121ticket 20122 20123an authorization ticket returned by the TPM in response 20124to a TPM2_PolicySigned() or TPM2_PolicySecret() 20125 20126Table 118 — TPM2_PolicyTicket Response 20127Type 20128 20129Name 20130 20131Description 20132 20133TPM_ST 20134 20135tag 20136 20137see clause 8 20138 20139UINT32 20140 20141responseSize 20142 20143TPM_RC 20144 20145responseCode 20146 20147Family “2.0” 20148Level 00 Revision 00.99 20149 20150Published 20151Copyright © TCG 2006-2013 20152 20153Page 245 20154October 31, 2013 20155 20156 Part 3: Commands 20157 20158Trusted Platform Module Library 20159 2016025.5.3 Detailed Actions 201611 201622 201633 20164 20165#include "InternalRoutines.h" 20166#include "PolicyTicket_fp.h" 20167#include "Policy_spt_fp.h" 20168Error Returns 20169TPM_RC_CPHASH 20170 20171policy's cpHash was previously set to a different value 20172 20173TPM_RC_EXPIRED 20174 20175timeout value in the ticket is in the past and the ticket has expired 20176 20177TPM_RC_SIZE 20178 20179timeout or cpHash has invalid size for the 20180 20181TPM_RC_TICKET 201824 201835 201846 201857 201868 201879 2018810 2018911 2019012 2019113 2019214 2019315 2019416 2019517 2019618 2019719 2019820 2019921 2020022 2020123 2020224 2020325 2020426 2020527 2020628 2020729 2020830 2020931 2021032 2021133 2021234 2021335 2021436 2021537 2021638 2021739 2021840 2021941 2022042 2022143 2022244 2022345 2022446 2022547 2022648 2022749 20228 20229Meaning 20230 20231ticket is not valid 20232 20233TPM_RC 20234TPM2_PolicyTicket( 20235PolicyTicket_In 20236 20237*in 20238 20239// IN: input parameter list 20240 20241TPM_RC 20242SESSION 20243UINT64 20244TPMT_TK_AUTH 20245TPM_CC 20246 20247result; 20248*session; 20249timeout; 20250ticketToCompare; 20251commandCode = TPM_CC_PolicySecret; 20252 20253) 20254{ 20255 20256// Input Validation 20257// Get pointer to the session structure 20258session = SessionGet(in->policySession); 20259// NOTE: A trial policy session is not allowed to use this command. 20260// A ticket is used in place of a previously given authorization. Since 20261// a trial policy doesn't actually authenticate, the validated 20262// ticket is not necessary and, in place of using a ticket, one 20263// should use the intended authorization for which the ticket 20264// would be a subsitute. 20265if(session->attributes.isTrialPolicy) 20266return TPM_RCS_ATTRIBUTES + RC_PolicyTicket_policySession; 20267// Restore timeout data. The format of timeout buffer is TPM-specific. 20268// In this implementation, we simply copy the value of timeout to the 20269// buffer. 20270if(in->timeout.t.size != sizeof(UINT64)) 20271return TPM_RC_SIZE + RC_PolicyTicket_timeout; 20272timeout = BYTE_ARRAY_TO_UINT64(in->timeout.t.buffer); 20273// Do the normal checks on the cpHashA and timeout values 20274result = PolicyParameterChecks(session, timeout, 20275&in->cpHashA, NULL, 202760, 20277// no bad nonce return 20278RC_PolicyTicket_cpHashA, 20279RC_PolicyTicket_timeout); 20280if(result != TPM_RC_SUCCESS) 20281return result; 20282// Validate Ticket 20283// Re-generate policy ticket by input parameters 20284TicketComputeAuth(in->ticket.tag, in->ticket.hierarchy, timeout, &in->cpHashA, 20285&in->policyRef, &in->authName, &ticketToCompare); 20286 20287Page 246 20288October 31, 2013 20289 20290Published 20291Copyright © TCG 2006-2013 20292 20293Family “2.0” 20294Level 00 Revision 00.99 20295 20296 Trusted Platform Module Library 2029750 2029851 2029952 2030053 2030154 2030255 2030356 2030457 2030558 2030659 2030760 2030861 2030962 2031063 2031164 2031265 2031366 2031467 2031568 2031669 2031770 2031871 2031972 2032073 20321 20322Part 3: Commands 20323 20324// Compare generated digest with input ticket digest 20325if(!Memory2BEqual(&in->ticket.digest.b, &ticketToCompare.digest.b)) 20326return TPM_RC_TICKET + RC_PolicyTicket_ticket; 20327// Internal Data Update 20328// Is this ticket to take the place of a TPM2_PolicySigned() or 20329// a TPM2_PolicySecret()? 20330if(in->ticket.tag == TPM_ST_AUTH_SIGNED) 20331commandCode = TPM_CC_PolicySigned; 20332else if(in->ticket.tag == TPM_ST_AUTH_SECRET) 20333commandCode = TPM_CC_PolicySecret; 20334else 20335// There could only be two possible tag values. Any other value should 20336// be caught by the ticket validation process. 20337pAssert(FALSE); 20338// Update policy context 20339PolicyContextUpdate(commandCode, &in->authName, &in->policyRef, 20340&in->cpHashA, timeout, session); 20341return TPM_RC_SUCCESS; 20342} 20343 20344Family “2.0” 20345Level 00 Revision 00.99 20346 20347Published 20348Copyright © TCG 2006-2013 20349 20350Page 247 20351October 31, 2013 20352 20353 Part 3: Commands 20354 2035525.6 20356 20357Trusted Platform Module Library 20358 20359TPM2_PolicyOR 20360 2036125.6.1 General Description 20362This command allows options in authorizations without requiring that the TPM evaluate all of the options. 20363If a policy may be satisfied by different sets of conditions, the TPM need only evaluate one set that 20364satisfies the policy. This command will indicate that one of the required sets of conditions has been 20365satisfied. 20366PolicySession→policyDigest is compared against the list of provided values. If the current 20367policySession→policyDigest does not match any value in the list, the TPM shall return TPM_RC_VALUE. 20368Otherwise, it will replace policySession→policyDigest with the digest of the concatenation of all of the 20369digests and return TPM_RC_SUCCESS. 20370If policySession is a trial session, the TPM will assume that policySession→policyDigest matches one of 20371the list entries and compute the new value of policyDigest. 20372The algorithm for computing the new value for policyDigest of policySession is: 20373a) Concatenate all the digest values in pHashList: 20374 20375digests ≔ pHashList.digests[1].buffer || … || pHashList.digests[n].buffer 20376NOTE 1 20377 20378(17) 20379 20380The TPM makes no check to see if the size of an entry matches the size of the digest of the 20381policy. 20382 20383b) Reset policyDigest to a Zero Digest. 20384c) Extend the command code and the hashes computed in step a) above: 20385 20386policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyOR || digests) 20387NOTE 2 20388 20389(18) 20390 20391The computation in b) and c) above is equivalent to: 20392 20393policyDigestnew ≔ HpolicyAlg(0…0 || TPM_CC_PolicyOR || digests) 20394 20395A TPM shall support a list with at least eight tagged digest values. 20396NOTE 3 20397 20398If policies are to be portable between TPMs, then they should not use more than eight values. 20399 20400Page 248 20401October 31, 2013 20402 20403Published 20404Copyright © TCG 2006-2013 20405 20406Family “2.0” 20407Level 00 Revision 00.99 20408 20409 Trusted Platform Module Library 20410 20411Part 3: Commands 20412 2041325.6.2 Command and Response 20414Table 119 — TPM2_PolicyOR Command 20415Type 20416 20417Name 20418 20419Description 20420 20421TPMI_ST_COMMAND_TAG 20422 20423tag 20424 20425UINT32 20426 20427commandSize 20428 20429TPM_CC 20430 20431commandCode 20432 20433TPM_CC_PolicyOR. 20434 20435TPMI_SH_POLICY 20436 20437policySession 20438 20439handle for the policy session being extended 20440Auth Index: None 20441 20442TPML_DIGEST 20443 20444pHashList 20445 20446the list of hashes to check for a match 20447 20448Table 120 — TPM2_PolicyOR Response 20449Type 20450 20451Name 20452 20453Description 20454 20455TPM_ST 20456 20457tag 20458 20459see clause 8 20460 20461UINT32 20462 20463responseSize 20464 20465TPM_RC 20466 20467responseCode 20468 20469Family “2.0” 20470Level 00 Revision 00.99 20471 20472Published 20473Copyright © TCG 2006-2013 20474 20475Page 249 20476October 31, 2013 20477 20478 Part 3: Commands 20479 20480Trusted Platform Module Library 20481 2048225.6.3 Detailed Actions 204831 204842 204853 20486 20487#include "InternalRoutines.h" 20488#include "PolicyOR_fp.h" 20489#include "Policy_spt_fp.h" 20490Error Returns 20491TPM_RC_VALUE 20492 204934 204945 204956 204967 204978 204989 2049910 2050011 2050112 2050213 2050314 2050415 2050516 2050617 2050718 2050819 2050920 2051021 2051122 2051223 2051324 2051425 2051526 2051627 2051728 2051829 2051930 2052031 2052132 2052233 2052334 2052435 2052536 2052637 2052738 2052839 2052940 2053041 2053142 2053243 2053344 2053445 2053546 2053647 2053748 2053849 2053950 2054051 2054152 2054253 20543 20544Meaning 20545no digest in pHashList matched the current value of policyDigest for 20546policySession 20547 20548TPM_RC 20549TPM2_PolicyOR( 20550PolicyOR_In *in 20551 20552// IN: input parameter list 20553 20554) 20555{ 20556SESSION 20557UINT32 20558 20559*session; 20560i; 20561 20562// Input Validation and Update 20563// Get pointer to the session structure 20564session = SessionGet(in->policySession); 20565// Compare and Update Internal Session policy if match 20566for(i = 0; i < in->pHashList.count; i++) 20567{ 20568if( 20569session->attributes.isTrialPolicy == SET 20570|| (Memory2BEqual(&session->u2.policyDigest.b, 20571&in->pHashList.digests[i].b)) 20572) 20573{ 20574// Found a match 20575HASH_STATE 20576hashState; 20577TPM_CC 20578commandCode = TPM_CC_PolicyOR; 20579// Start hash 20580session->u2.policyDigest.t.size = CryptStartHash(session->authHashAlg, 20581&hashState); 20582// Set policyDigest to 0 string and add it to hash 20583MemorySet(session->u2.policyDigest.t.buffer, 0, 20584session->u2.policyDigest.t.size); 20585CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 20586// add command code 20587CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 20588// Add each of the hashes in the list 20589for(i = 0; i < in->pHashList.count; i++) 20590{ 20591// Extend policyDigest 20592CryptUpdateDigest2B(&hashState, &in->pHashList.digests[i].b); 20593} 20594// Complete digest 20595CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 20596return TPM_RC_SUCCESS; 20597} 20598} 20599// None of the values in the list matched the current policyDigest 20600return TPM_RC_VALUE + RC_PolicyOR_pHashList; 20601 20602Page 250 20603October 31, 2013 20604 20605Published 20606Copyright © TCG 2006-2013 20607 20608Family “2.0” 20609Level 00 Revision 00.99 20610 20611 Trusted Platform Module Library 2061254 20613 20614Part 3: Commands 20615 20616} 20617 20618Family “2.0” 20619Level 00 Revision 00.99 20620 20621Published 20622Copyright © TCG 2006-2013 20623 20624Page 251 20625October 31, 2013 20626 20627 Part 3: Commands 20628 2062925.7 20630 20631Trusted Platform Module Library 20632 20633TPM2_PolicyPCR 20634 2063525.7.1 General Description 20636This command is used to cause conditional gating of a policy based on PCR. This allows one group of 20637authorizations to occur when PCR are in one state and a different set of authorizations when the PCR are 20638in a different state. If this command is used for a trial policySession, policySession→policyDigest will be 20639updated using the values from the command rather than the values from digest of the TPM PCR. 20640The TPM will modify the pcrs parameter so that bits that correspond to unimplemented PCR are CLEAR. 20641If policySession is not a trial policy session, the TPM will use the modified value of pcrs to select PCR 20642values to hash according to Part 1, Selecting Multiple PCR. The hash algorithm of the policy session is 20643used to compute a digest (digestTPM) of the selected PCR. If pcrDigest does not have a length of zero, 20644then it is compared to digestTPM; and if the values do not match, the TPM shall return TPM_RC_VALUE 20645and make no change to policySession→policyDigest. If the values match, or if the length of pcrDigest is 20646zero, then policySession→policyDigest is extended by: 20647 20648policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyPCR || pcrs || digestTPM) 20649 20650(19) 20651 20652where 20653 20654pcrs 20655 20656the pcrs parameter with bits corresponding to unimplemented 20657PCR set to 0 20658 20659digestTPM 20660 20661the digest of the selected PCR using the hash algorithm of the 20662policy session 20663 20664NOTE 1 20665 20666If the caller provides the expected PCR value, the intention is that the policy evaluation stop at that 20667point if the PCR do not match. If the caller does not provide the expected PCR value, then the 20668validity of the settings will not be determined until an attempt is made to use the policy for 20669authorization. If the policy is constructed such that the PCR check comes before user authorization 20670checks, this early termination would allow software to avoid unnecessary prompts for user input to 20671satisfy a policy that would fail later due to incorr ect PCR values. 20672 20673After this command completes successfully, the TPM shall return TPM_RC_PCR_CHANGED if the policy 20674session is used for authorization and the PCR are not known to be correct. 20675The TPM uses a “generation” number (pcrUpdateCounter) that is incremented each time PCR are 20676updated (unless the PCR being changed is specified not to cause a change to this counter). The value of 20677this counter is stored in the policy session context (policySession→pcrUpdateCounter) when this 20678command is executed. When the policy is used for authorization, the current value of the counter is 20679compared to the value in the policy session context and the authorization will fail if the values are not the 20680same. 20681When this command is executed, policySession→pcrUpdateCounter is checked to see if it has been 20682previously set (in the reference implementation, it has a value of zero if not previously set). If it has been 20683set, it will be compared with the current value of pcrUpdateCounter to determine if any PCR changes 20684have occurred. If the values are different, the TPM shall return TPM_RC_PCR_CHANGED. If 20685policySession→pcrUpdateCounter has not been set, then it is set to the current value of 20686pcrUpdateCounter. 20687If policySession is a trial policy session, the TPM will not check any PCR and will compute: 20688 20689policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyPCR || pcrs || pcrDigest) 20690 20691(20) 20692 20693In this computation, pcrs is the input parameter without modification. 20694NOTE 2 20695 20696The pcrs parameter is expected to match the configuration of the TPM for which the policy is being 20697computed which may not be the same as the TPM on which the trial policy is being computed. 20698 20699Page 252 20700October 31, 2013 20701 20702Published 20703Copyright © TCG 2006-2013 20704 20705Family “2.0” 20706Level 00 Revision 00.99 20707 20708 Trusted Platform Module Library 20709 20710Part 3: Commands 20711 2071225.7.2 Command and Response 20713Table 121 — TPM2_PolicyPCR Command 20714Type 20715 20716Name 20717 20718Description 20719 20720TPMI_ST_COMMAND_TAG 20721 20722tag 20723 20724UINT32 20725 20726commandSize 20727 20728TPM_CC 20729 20730commandCode 20731 20732TPM_CC_PolicyPCR 20733 20734TPMI_SH_POLICY 20735 20736policySession 20737 20738handle for the policy session being extended 20739Auth Index: None 20740 20741TPM2B_DIGEST 20742 20743pcrDigest 20744 20745expected digest value of the selected PCR using the 20746hash algorithm of the session; may be zero length 20747 20748TPML_PCR_SELECTION 20749 20750pcrs 20751 20752the PCR to include in the check digest 20753 20754Table 122 — TPM2_PolicyPCR Response 20755Type 20756 20757Name 20758 20759Description 20760 20761TPM_ST 20762 20763tag 20764 20765see clause 8 20766 20767UINT32 20768 20769responseSize 20770 20771TPM_RC 20772 20773responseCode 20774 20775Family “2.0” 20776Level 00 Revision 00.99 20777 20778Published 20779Copyright © TCG 2006-2013 20780 20781Page 253 20782October 31, 2013 20783 20784 Part 3: Commands 20785 20786Trusted Platform Module Library 20787 2078825.7.3 Detailed Actions 207891 207902 20791 20792#include "InternalRoutines.h" 20793#include "PolicyPCR_fp.h" 20794Error Returns 20795TPM_RC_VALUE 20796 20797if provided, pcrDigest does not match the current PCR settings 20798 20799TPM_RC_PCR_CHANGED 208003 208014 208025 208036 208047 208058 208069 2080710 2080811 2080912 2081013 2081114 2081215 2081316 2081417 2081518 2081619 2081720 2081821 2081922 2082023 2082124 2082225 2082326 2082427 2082528 2082629 2082730 2082831 2082932 2083033 2083134 2083235 2083336 2083437 2083538 2083639 2083740 2083841 2083942 2084043 2084144 2084245 2084346 2084447 2084548 2084649 2084750 2084851 2084952 2085053 20851 20852Meaning 20853 20854a previous TPM2_PolicyPCR() set pcrCounter and it has changed 20855 20856TPM_RC 20857TPM2_PolicyPCR( 20858PolicyPCR_In 20859 20860*in 20861 20862// IN: input parameter list 20863 20864SESSION 20865TPM2B_DIGEST 20866BYTE 20867UINT32 20868BYTE 20869TPM_CC 20870HASH_STATE 20871 20872*session; 20873pcrDigest; 20874pcrs[sizeof(TPML_PCR_SELECTION)]; 20875pcrSize; 20876*buffer; 20877commandCode = TPM_CC_PolicyPCR; 20878hashState; 20879 20880) 20881{ 20882 20883// Input Validation 20884// Get pointer to the session structure 20885session = SessionGet(in->policySession); 20886// Do validation for non trial session 20887if(session->attributes.isTrialPolicy == CLEAR) 20888{ 20889// Make sure that this is not going to invalidate a previous PCR check 20890if(session->pcrCounter != 0 && session->pcrCounter != gr.pcrCounter) 20891return TPM_RC_PCR_CHANGED; 20892// Compute current PCR digest 20893PCRComputeCurrentDigest(session->authHashAlg, &in->pcrs, &pcrDigest); 20894// If the caller specified the PCR digest and it does not 20895// match the current PCR settings, return an error.. 20896if(in->pcrDigest.t.size != 0) 20897{ 20898if(!Memory2BEqual(&in->pcrDigest.b, &pcrDigest.b)) 20899return TPM_RC_VALUE + RC_PolicyPCR_pcrDigest; 20900} 20901} 20902else 20903{ 20904// For trial session, just use the input PCR digest 20905pcrDigest = in->pcrDigest; 20906} 20907// Internal Data Update 20908// Update policy hash 20909// policyDigestnew = hash( 20910policyDigestold || TPM_CC_PolicyPCR 20911// 20912|| pcrs || pcrDigest) 20913// Start hash 20914CryptStartHash(session->authHashAlg, &hashState); 20915// add old digest 20916CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 20917 20918Page 254 20919October 31, 2013 20920 20921Published 20922Copyright © TCG 2006-2013 20923 20924Family “2.0” 20925Level 00 Revision 00.99 20926 20927 Trusted Platform Module Library 2092854 2092955 2093056 2093157 2093258 2093359 2093460 2093561 2093662 2093763 2093864 2093965 2094066 2094167 2094268 2094369 2094470 2094571 2094672 2094773 2094874 2094975 2095076 20951 20952Part 3: Commands 20953 20954// add commandCode 20955CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 20956// add PCRS 20957buffer = pcrs; 20958pcrSize = TPML_PCR_SELECTION_Marshal(&in->pcrs, &buffer, NULL); 20959CryptUpdateDigest(&hashState, pcrSize, pcrs); 20960// add PCR digest 20961CryptUpdateDigest2B(&hashState, &pcrDigest.b); 20962// complete the hash and get the results 20963CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 20964// update pcrCounter in session context for non trial session 20965if(session->attributes.isTrialPolicy == CLEAR) 20966{ 20967session->pcrCounter = gr.pcrCounter; 20968} 20969return TPM_RC_SUCCESS; 20970} 20971 20972Family “2.0” 20973Level 00 Revision 00.99 20974 20975Published 20976Copyright © TCG 2006-2013 20977 20978Page 255 20979October 31, 2013 20980 20981 Part 3: Commands 20982 2098325.8 20984 20985Trusted Platform Module Library 20986 20987TPM2_PolicyLocality 20988 2098925.8.1 General Description 20990This command indicates that the authorization will be limited to a specific locality. 20991policySession→commandLocality is a parameter kept in the session context. It is initialized when the 20992policy session is started to allow the policy to apply to any locality. 20993If locality has a value greater than 31, then an extended locality is indicated. For an extended locality, the 20994TPM will validate that policySession→commandLocality is has not previously been set or that the current 20995value of policySession→commandLocality is the same as locality (TPM_RC_RANGE). 20996When locality is not an extended locality, the TPM will validate that the policySession→commandLocality 20997is not set or is not set to an extended locality value (TPM_RC_RANGE). If not the TPM will disable any 20998locality not SET in the locality parameter. If the result of disabling localities results in no locality being 20999enabled, the TPM will return TPM_RC_RANGE. 21000If no error occurred in the validation of locality, policySession→policyDigest is extended with 21001 21002policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyLocality || locality) 21003 21004(21) 21005 21006Then policySession→commandLocality is updated to indicate which localities are still allowed after 21007execution of TPM2_PolicyLocality(). 21008When the policy session is used to authorize a command, the authorization will fail if the locality used for 21009the command is not one of the enabled localities in policySession→commandLocality. 21010 21011Page 256 21012October 31, 2013 21013 21014Published 21015Copyright © TCG 2006-2013 21016 21017Family “2.0” 21018Level 00 Revision 00.99 21019 21020 Trusted Platform Module Library 21021 21022Part 3: Commands 21023 2102425.8.2 Command and Response 21025Table 123 — TPM2_PolicyLocality Command 21026Type 21027 21028Name 21029 21030Description 21031 21032TPMI_ST_COMMAND_TAG 21033 21034tag 21035 21036UINT32 21037 21038commandSize 21039 21040TPM_CC 21041 21042commandCode 21043 21044TPM_CC_PolicyLocality 21045 21046TPMI_SH_POLICY 21047 21048policySession 21049 21050handle for the policy session being extended 21051Auth Index: None 21052 21053TPMA_LOCALITY 21054 21055locality 21056 21057the allowed localities for the policy 21058 21059Table 124 — TPM2_PolicyLocality Response 21060Type 21061 21062Name 21063 21064Description 21065 21066TPM_ST 21067 21068tag 21069 21070see clause 8 21071 21072UINT32 21073 21074responseSize 21075 21076TPM_RC 21077 21078responseCode 21079 21080Family “2.0” 21081Level 00 Revision 00.99 21082 21083Published 21084Copyright © TCG 2006-2013 21085 21086Page 257 21087October 31, 2013 21088 21089 Part 3: Commands 21090 21091Trusted Platform Module Library 21092 2109325.8.3 Detailed Actions 210941 210952 21096 21097#include "InternalRoutines.h" 21098#include "PolicyLocality_fp.h" 21099 21100Limit a policy to a specific locality 21101Error Returns 21102TPM_RC_RANGE 21103 211043 211054 211065 211076 211087 211098 211109 2111110 2111211 2111312 2111413 2111514 2111615 2111716 2111817 2111918 2112019 2112120 2112221 2112322 2112423 2112524 2112625 2112726 2112827 2112928 2113029 2113130 2113231 2113332 2113433 2113534 2113635 2113736 2113837 2113938 2114039 2114140 2114241 2114342 2114443 2114544 2114645 2114746 2114847 2114948 2115049 2115150 2115251 2115352 21154 21155Meaning 21156all the locality values selected by locality have been disabled by 21157previous TPM2_PolicyLocality() calls. 21158 21159TPM_RC 21160TPM2_PolicyLocality( 21161PolicyLocality_In 21162 21163*in 21164 21165// IN: input parameter list 21166 21167) 21168{ 21169SESSION 21170BYTE 21171BYTE 21172UINT32 21173BYTE 21174TPM_CC 21175HASH_STATE 21176 21177*session; 21178marshalBuffer[sizeof(TPMA_LOCALITY)]; 21179prevSetting[sizeof(TPMA_LOCALITY)]; 21180marshalSize; 21181*buffer; 21182commandCode = TPM_CC_PolicyLocality; 21183hashState; 21184 21185// Input Validation 21186// Get pointer to the session structure 21187session = SessionGet(in->policySession); 21188// Get new locality setting in canonical form 21189buffer = marshalBuffer; 21190marshalSize = TPMA_LOCALITY_Marshal(&in->locality, &buffer, NULL); 21191// Its an error if the locality parameter is zero 21192if(marshalBuffer[0] == 0) 21193return TPM_RC_RANGE + RC_PolicyLocality_locality; 21194// Get existing locality setting in canonical form 21195buffer = prevSetting; 21196TPMA_LOCALITY_Marshal(&session->commandLocality, &buffer, NULL); 21197// If the locality has been previously set, then it needs to be the same 21198// tye as the input locality (i.e. both extended or both normal 21199if(prevSetting[0] != 0 && ((prevSetting[0] <= 0) != (marshalBuffer[0] <= 0))) 21200return TPM_RC_RANGE + RC_PolicyLocality_locality; 21201// See if the input is a regular or extended locality 21202if(marshalBuffer[0] < 32) 21203{ 21204// For regular locality 21205// The previous setting must not be an extended locality 21206if(prevSetting[0] > 31) 21207return TPM_RC_RANGE + RC_PolicyLocality_locality; 21208// if there was no previous setting, start with all normal localities 21209// enabled 21210if(prevSetting[0] == 0) 21211prevSetting[0] = 0x1F; 21212// AND the new setting with the previous setting and store it in prevSetting 21213 21214Page 258 21215October 31, 2013 21216 21217Published 21218Copyright © TCG 2006-2013 21219 21220Family “2.0” 21221Level 00 Revision 00.99 21222 21223 Trusted Platform Module Library 2122453 2122554 2122655 2122756 2122857 2122958 2123059 2123160 2123261 2123362 2123463 2123564 2123665 2123766 2123867 2123968 2124069 2124170 2124271 2124372 2124473 2124574 2124675 2124776 2124877 2124978 2125079 2125180 2125281 2125382 2125483 2125584 2125685 2125786 2125887 2125988 2126089 2126190 2126291 2126392 2126493 2126594 2126695 2126796 2126897 21269 21270Part 3: Commands 21271 21272prevSetting[0] &= marshalBuffer[0]; 21273// The result setting can not be 0 21274if(prevSetting[0] == 0) 21275return TPM_RC_RANGE + RC_PolicyLocality_locality; 21276} 21277else 21278{ 21279// for extended locality 21280// if the locality has already been set, then it must match the 21281if(prevSetting[0] != 0 && prevSetting[0] != marshalBuffer[0]) 21282return TPM_RC_RANGE + RC_PolicyLocality_locality; 21283// Setting is OK 21284prevSetting[0] = marshalBuffer[0]; 21285} 21286// Internal Data Update 21287// Update policy hash 21288// policyDigestnew = hash(policyDigestold || TPM_CC_PolicyLocality || locality) 21289// Start hash 21290CryptStartHash(session->authHashAlg, &hashState); 21291// add old digest 21292CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 21293// add commandCode 21294CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 21295// add input locality 21296CryptUpdateDigest(&hashState, marshalSize, marshalBuffer); 21297// complete the digest 21298CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 21299// update session locality by unmarshal function. The function must succeed 21300// because both input and existing locality setting have been validated. 21301buffer = prevSetting; 21302TPMA_LOCALITY_Unmarshal(&session->commandLocality, &buffer, 21303(INT32 *) &marshalSize); 21304return TPM_RC_SUCCESS; 21305} 21306 21307Family “2.0” 21308Level 00 Revision 00.99 21309 21310Published 21311Copyright © TCG 2006-2013 21312 21313Page 259 21314October 31, 2013 21315 21316 Part 3: Commands 21317 2131825.9 21319 21320Trusted Platform Module Library 21321 21322TPM2_PolicyNV 21323 2132425.9.1 General Description 21325This command is used to cause conditional gating of a policy based on the contents of an NV Index. 21326If policySession is a trial policy session, the TPM will update policySession→policyDigest as shown in 21327equations (22) and (23) below and return TPM_RC_SUCCESS. It will not perform any validation. The 21328remainder of this general description would apply only if policySession is not a trial policy session. 21329An authorization session providing authorization to read the NV Index shall be provided. 21330NOTE 1 21331 21332If read access is controlled by policy, the policy should include a branch that authorizes a 21333TPM2_PolicyNV(). 21334 21335If TPMA_NV_WRITTEN is not SET in the NV Index, the TPM shall return TPM_RC_NV_UNINITIALIZED. 21336The TPM will validate that the size of operandB plus offset is not greater than the size of the NV Index. If 21337it is, the TPM shall return TPM_RC_SIZE. 21338The TPM will perform the indicated arithmetic check on the indicated portion of the selected NV Index. If 21339the check fails, the TPM shall return TPM_RC_POLICY and not change policySession→policyDigest. If 21340the check succeeds, the TPM will hash the arguments: 21341 21342args ≔ HpolicyAlg(operand.buffer || offset || operation) 21343 21344(22) 21345 21346where 21347 21348HpolicyAlg() 21349 21350hash function using the algorithm of the policy session 21351 21352operandB 21353 21354the value used for the comparison 21355 21356offset 21357 21358offset from the start of the NV Index data to start the comparison 21359 21360operation 21361 21362the operation parameter indicating the comparison being 21363performed 21364 21365The value of args and the Name of the NV Index are extended to policySession→policyDigest by 21366 21367policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyNV || args || nvIndex→Name) 21368 21369(23) 21370 21371where 21372 21373HpolicyAlg() 21374 21375hash function using the algorithm of the policy session 21376 21377args 21378 21379value computed in equation (22) 21380 21381nvIndex→Name 21382 21383the Name of the NV Index 21384 21385The signed arithmetic operations are performed using twos-compliment. 21386Magnitude comparisons assume that the octet at offset zero in the referenced NV location and in 21387operandB contain the most significant octet of the data. 21388NOTE 2 21389 21390When an Index is written, it has a different authorization name than an Index that has not been 21391written. It is possible to use this change in the NV Index to create a write-once Index. 21392 21393Page 260 21394October 31, 2013 21395 21396Published 21397Copyright © TCG 2006-2013 21398 21399Family “2.0” 21400Level 00 Revision 00.99 21401 21402 Trusted Platform Module Library 21403 21404Part 3: Commands 21405 2140625.9.2 Command and Response 21407Table 125 — TPM2_PolicyNV Command 21408Type 21409 21410Name 21411 21412Description 21413 21414TPMI_ST_COMMAND_TAG 21415 21416tag 21417 21418UINT32 21419 21420commandSize 21421 21422TPM_CC 21423 21424commandCode 21425 21426TPM_CC_PolicyNV 21427 21428TPMI_RH_NV_AUTH 21429 21430@authHandle 21431 21432handle indicating the source of the authorization value 21433Auth Index: 1 21434Auth Role: USER 21435 21436TPMI_RH_NV_INDEX 21437 21438nvIndex 21439 21440the NV Index of the area to read 21441Auth Index: None 21442 21443TPMI_SH_POLICY 21444 21445policySession 21446 21447handle for the policy session being extended 21448Auth Index: None 21449 21450TPM2B_OPERAND 21451 21452operandB 21453 21454the second operand 21455 21456UINT16 21457 21458offset 21459 21460the offset in the NV Index for the start of operand A 21461 21462TPM_EO 21463 21464operation 21465 21466the comparison to make 21467 21468Table 126 — TPM2_PolicyNV Response 21469Type 21470 21471Name 21472 21473Description 21474 21475TPM_ST 21476 21477tag 21478 21479see clause 8 21480 21481UINT32 21482 21483responseSize 21484 21485TPM_RC 21486 21487responseCode 21488 21489Family “2.0” 21490Level 00 Revision 00.99 21491 21492Published 21493Copyright © TCG 2006-2013 21494 21495Page 261 21496October 31, 2013 21497 21498 Part 3: Commands 21499 21500Trusted Platform Module Library 21501 2150225.9.3 Detailed Actions 215031 215042 215053 215064 21507 21508#include 21509#include 21510#include 21511#include 21512 21513"InternalRoutines.h" 21514"PolicyNV_fp.h" 21515"Policy_spt_fp.h" 21516"NV_spt_fp.h" 21517 21518// Include NV support routine for read access check 21519 21520Error Returns 21521TPM_RC_AUTH_TYPE 21522 21523NV index authorization type is not correct 21524 21525TPM_RC_NV_LOCKED 21526 21527NV index read locked 21528 21529TPM_RC_NV_UNINITIALIZED 21530 21531the NV index has not been initialized 21532 21533TPM_RC_POLICY 21534 21535the comparison to the NV contents failed 21536 21537TPM_RC_SIZE 21538 215395 215406 215417 215428 215439 2154410 2154511 2154612 2154713 2154814 2154915 2155016 2155117 2155218 2155319 2155420 2155521 2155622 2155723 2155824 2155925 2156026 2156127 2156228 2156329 2156430 2156531 2156632 2156733 2156834 2156935 2157036 2157137 2157238 2157339 2157440 2157541 2157642 2157743 2157844 2157945 2158046 21581 21582Meaning 21583 21584the size of nvIndex data starting at offset is less than the size of 21585operandB 21586 21587TPM_RC 21588TPM2_PolicyNV( 21589PolicyNV_In 21590 21591*in 21592 21593// IN: input parameter list 21594 21595TPM_RC 21596SESSION 21597NV_INDEX 21598BYTE 21599TPM2B_NAME 21600TPM_CC 21601HASH_STATE 21602TPM2B_DIGEST 21603 21604result; 21605*session; 21606nvIndex; 21607nvBuffer[sizeof(in->operandB.t.buffer)]; 21608nvName; 21609commandCode = TPM_CC_PolicyNV; 21610hashState; 21611argHash; 21612 21613) 21614{ 21615 21616// Input Validation 21617// Get NV index information 21618NvGetIndexInfo(in->nvIndex, &nvIndex); 21619// Get pointer to the session structure 21620session = SessionGet(in->policySession); 21621//If this is a trial policy, skip all validations and the operation 21622if(session->attributes.isTrialPolicy == CLEAR) 21623{ 21624// NV Read access check. NV index should be allowed for read. A 21625// TPM_RC_AUTH_TYPE or TPM_RC_NV_LOCKED error may be return at this 21626// point 21627result = NvReadAccessChecks(in->authHandle, in->nvIndex); 21628if(result != TPM_RC_SUCCESS) return result; 21629// Valid NV data size should not be smaller than input operandB size 21630if((nvIndex.publicArea.dataSize - in->offset) < in->operandB.t.size) 21631return TPM_RC_SIZE + RC_PolicyNV_operandB; 21632// Arithmetic Comparison 21633// Get NV data. The size of NV data equals the input operand B size 21634NvGetIndexData(in->nvIndex, &nvIndex, in->offset, 21635in->operandB.t.size, nvBuffer); 21636switch(in->operation) 21637 21638Page 262 21639October 31, 2013 21640 21641Published 21642Copyright © TCG 2006-2013 21643 21644Family “2.0” 21645Level 00 Revision 00.99 21646 21647 Trusted Platform Module Library 2164847 2164948 2165049 2165150 2165251 2165352 2165453 2165554 2165655 2165756 2165857 2165958 2166059 2166160 2166261 2166362 2166463 2166564 2166665 2166766 2166867 2166968 2167069 2167170 2167271 2167372 2167473 2167574 2167675 2167776 2167877 2167978 2168079 2168180 2168281 2168382 2168483 2168584 2168685 2168786 2168887 2168988 2169089 2169190 2169291 2169392 2169493 2169594 2169695 2169796 2169897 2169998 2170099 21701100 21702101 21703102 21704103 21705104 21706105 21707106 21708107 21709108 21710109 21711110 21712 21713Part 3: Commands 21714 21715{ 21716case TPM_EO_EQ: 21717// compare A = B 21718if(CryptCompare(in->operandB.t.size, nvBuffer, 21719in->operandB.t.size, in->operandB.t.buffer) 21720return TPM_RC_POLICY; 21721break; 21722case TPM_EO_NEQ: 21723// compare A != B 21724if(CryptCompare(in->operandB.t.size, nvBuffer, 21725in->operandB.t.size, in->operandB.t.buffer) 21726return TPM_RC_POLICY; 21727break; 21728case TPM_EO_SIGNED_GT: 21729// compare A > B signed 21730if(CryptCompareSigned(in->operandB.t.size, nvBuffer, 21731in->operandB.t.size, in->operandB.t.buffer) 21732return TPM_RC_POLICY; 21733break; 21734case TPM_EO_UNSIGNED_GT: 21735// compare A > B unsigned 21736if(CryptCompare(in->operandB.t.size, nvBuffer, 21737in->operandB.t.size, in->operandB.t.buffer) 21738return TPM_RC_POLICY; 21739break; 21740case TPM_EO_SIGNED_LT: 21741// compare A < B signed 21742if(CryptCompareSigned(in->operandB.t.size, nvBuffer, 21743in->operandB.t.size, in->operandB.t.buffer) 21744return TPM_RC_POLICY; 21745break; 21746case TPM_EO_UNSIGNED_LT: 21747// compare A < B unsigned 21748if(CryptCompare(in->operandB.t.size, nvBuffer, 21749in->operandB.t.size, in->operandB.t.buffer) 21750return TPM_RC_POLICY; 21751break; 21752case TPM_EO_SIGNED_GE: 21753// compare A >= B signed 21754if(CryptCompareSigned(in->operandB.t.size, nvBuffer, 21755in->operandB.t.size, in->operandB.t.buffer) 21756return TPM_RC_POLICY; 21757break; 21758case TPM_EO_UNSIGNED_GE: 21759// compare A >= B unsigned 21760if(CryptCompare(in->operandB.t.size, nvBuffer, 21761in->operandB.t.size, in->operandB.t.buffer) 21762return TPM_RC_POLICY; 21763break; 21764case TPM_EO_SIGNED_LE: 21765// compare A <= B signed 21766if(CryptCompareSigned(in->operandB.t.size, nvBuffer, 21767in->operandB.t.size, in->operandB.t.buffer) 21768return TPM_RC_POLICY; 21769break; 21770case TPM_EO_UNSIGNED_LE: 21771// compare A <= B unsigned 21772if(CryptCompare(in->operandB.t.size, nvBuffer, 21773in->operandB.t.size, in->operandB.t.buffer) 21774return TPM_RC_POLICY; 21775break; 21776case TPM_EO_BITSET: 21777// All bits SET in B are SET in A. ((A&B)=B) 21778{ 21779 21780Family “2.0” 21781Level 00 Revision 00.99 21782 21783Published 21784Copyright © TCG 2006-2013 21785 21786!= 0) 21787 21788== 0) 21789 21790<= 0) 21791 21792<= 0) 21793 21794>= 0) 21795 21796>= 0) 21797 21798< 0) 21799 21800< 0) 21801 21802> 0) 21803 21804> 0) 21805 21806Page 263 21807October 31, 2013 21808 21809 Part 3: Commands 21810111 21811112 21812113 21813114 21814115 21815116 21816117 21817118 21818119 21819120 21820121 21821122 21822123 21823124 21824125 21825126 21826127 21827128 21828129 21829130 21830131 21831132 21832133 21833134 21834135 21835136 21836137 21837138 21838139 21839140 21840141 21841142 21842143 21843144 21844145 21845146 21846147 21847148 21848149 21849150 21850151 21851152 21852153 21853154 21854155 21855156 21856157 21857158 21858159 21859160 21860161 21861162 21862163 21863164 21864165 21865166 21866167 21867168 21868169 21869170 21870171 21871 21872Trusted Platform Module Library 21873 21874UINT32 i; 21875for (i = 0; i < in->operandB.t.size; i++) 21876if((nvBuffer[i] & in->operandB.t.buffer[i]) 21877!= in->operandB.t.buffer[i]) 21878return TPM_RC_POLICY; 21879} 21880break; 21881case TPM_EO_BITCLEAR: 21882// All bits SET in B are CLEAR in A. ((A&B)=0) 21883{ 21884UINT32 i; 21885for (i = 0; i < in->operandB.t.size; i++) 21886if((nvBuffer[i] & in->operandB.t.buffer[i]) != 0) 21887return TPM_RC_POLICY; 21888} 21889break; 21890default: 21891pAssert(FALSE); 21892break; 21893} 21894} 21895// Internal Data Update 21896// Start argument hash 21897argHash.t.size = CryptStartHash(session->authHashAlg, &hashState); 21898// add operandB 21899CryptUpdateDigest2B(&hashState, &in->operandB.b); 21900// add offset 21901CryptUpdateDigestInt(&hashState, sizeof(UINT16), &in->offset); 21902// add operation 21903CryptUpdateDigestInt(&hashState, sizeof(TPM_EO), &in->operation); 21904// complete argument digest 21905CryptCompleteHash2B(&hashState, &argHash.b); 21906// Update policyDigest 21907// Start digest 21908CryptStartHash(session->authHashAlg, &hashState); 21909// add old digest 21910CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 21911// add commandCode 21912CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 21913// add argument digest 21914CryptUpdateDigest2B(&hashState, &argHash.b); 21915// Adding nvName 21916nvName.t.size = EntityGetName(in->nvIndex, &nvName.t.name); 21917CryptUpdateDigest2B(&hashState, &nvName.b); 21918// complete the digest 21919CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 21920return TPM_RC_SUCCESS; 21921} 21922 21923Page 264 21924October 31, 2013 21925 21926Published 21927Copyright © TCG 2006-2013 21928 21929Family “2.0” 21930Level 00 Revision 00.99 21931 21932 Trusted Platform Module Library 21933 21934Part 3: Commands 21935 2193625.10 TPM2_PolicyCounterTimer 2193725.10.1 21938 21939General Description 21940 21941This command is used to cause conditional gating of a policy based on the contents of the 21942TPMS_TIME_INFO structure. 21943If policySession is a trial policy session, the TPM will update policySession→policyDigest as shown in 21944equations (24) and (25) below and return TPM_RC_SUCCESS. It will not perform any validation. The 21945remainder of this general description would apply only if policySession is not a trial policy session. 21946The TPM will perform the indicated arithmetic check on the indicated portion of the TPMS_TIME_INFO 21947structure. If the check fails, the TPM shall return TPM_RC_POLICY and not change 21948policySession→policyDigest. If the check succeeds, the TPM will hash the arguments: 21949 21950args ≔ HpolicyAlg(operandB.buffer || offset || operation) 21951 21952(24) 21953 21954where 21955 21956HpolicyAlg() 21957 21958hash function using the algorithm of the policy session 21959 21960operandB.buffer 21961 21962the value used for the comparison 21963 21964offset 21965 21966offset from the start of the TPMS_TIME_INFO structure at which 21967the comparison starts 21968 21969operation 21970 21971the operation parameter indicating the comparison being 21972performed 21973 21974The value of args is extended to policySession→policyDigest by 21975 21976policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyCounterTimer || args) 21977 21978(25) 21979 21980where 21981 21982HpolicyAlg() 21983 21984hash function using the algorithm of the policy session 21985 21986args 21987 21988value computed in equation (24) 21989 21990The signed arithmetic operations are performed using twos-compliment. 21991Magnitude comparisons assume that the octet at offset zero in the referenced location and in operandB 21992contain the most significant octet of the data. 21993 21994Family “2.0” 21995Level 00 Revision 00.99 21996 21997Published 21998Copyright © TCG 2006-2013 21999 22000Page 265 22001October 31, 2013 22002 22003 Part 3: Commands 22004 2200525.10.2 22006 22007Trusted Platform Module Library 22008 22009Command and Response 22010Table 127 — TPM2_PolicyCounterTimer Command 22011 22012Type 22013 22014Name 22015 22016Description 22017 22018TPMI_ST_COMMAND_TAG 22019 22020tag 22021 22022UINT32 22023 22024commandSize 22025 22026TPM_CC 22027 22028commandCode 22029 22030TPM_CC_PolicyCounterTimer 22031 22032TPMI_SH_POLICY 22033 22034policySession 22035 22036handle for the policy session being extended 22037Auth Index: None 22038 22039TPM2B_OPERAND 22040 22041operandB 22042 22043the second operand 22044 22045UINT16 22046 22047offset 22048 22049the offset in TPMS_TIME_INFO structure for the start of 22050operand A 22051 22052TPM_EO 22053 22054operation 22055 22056the comparison to make 22057 22058Table 128 — TPM2_PolicyCounterTimer Response 22059Type 22060 22061Name 22062 22063Description 22064 22065TPM_ST 22066 22067tag 22068 22069see clause 8 22070 22071UINT32 22072 22073responseSize 22074 22075TPM_RC 22076 22077responseCode 22078 22079Page 266 22080October 31, 2013 22081 22082Published 22083Copyright © TCG 2006-2013 22084 22085Family “2.0” 22086Level 00 Revision 00.99 22087 22088 Trusted Platform Module Library 22089 2209025.10.3 220911 220922 220933 22094 22095Part 3: Commands 22096 22097Detailed Actions 22098 22099#include "InternalRoutines.h" 22100#include "PolicyCounterTimer_fp.h" 22101#include "Policy_spt_fp.h" 22102Error Returns 22103TPM_RC_POLICY 22104 22105the comparison of the selected portion of the TPMS_TIME_INFO with 22106operandB failed 22107 22108TPM_RC_RANGE 221094 221105 221116 221127 221138 221149 2211510 2211611 2211712 2211813 2211914 2212015 2212116 2212217 2212318 2212419 2212520 2212621 2212722 2212823 2212924 2213025 2213126 2213227 2213328 2213429 2213530 2213631 2213732 2213833 2213934 2214035 2214136 2214237 2214338 2214439 2214540 2214641 2214742 2214843 2214944 2215045 2215146 2215247 2215348 2215449 2215550 2215651 2215752 22158 22159Meaning 22160 22161offset + size exceed size of TPMS_TIME_INFO structure 22162 22163TPM_RC 22164TPM2_PolicyCounterTimer( 22165PolicyCounterTimer_In 22166 22167*in 22168 22169// IN: input parameter list 22170 22171) 22172{ 22173TPM_RC 22174SESSION 22175TIME_INFO 22176TPM_CC 22177HASH_STATE 22178TPM2B_DIGEST 22179 22180result; 22181*session; 22182infoData; 22183// data buffer of TPMS_TIME_INFO 22184commandCode = TPM_CC_PolicyCounterTimer; 22185hashState; 22186argHash; 22187 22188// Input Validation 22189// If the command is going to use any part of the counter or timer, need 22190// to verify that time is advancing. 22191// The time and clock vales are the first two 64-bit values in the clock 22192if(in->offset < <K>sizeof(UINT64) + sizeof(UINT64)) 22193{ 22194// Using Clock or Time so see if clock is running. Clock doesn't run while 22195// NV is unavailable. 22196// TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned here. 22197result = NvIsAvailable(); 22198if(result != TPM_RC_SUCCESS) 22199return result; 22200} 22201// Get pointer to the session structure 22202session = SessionGet(in->policySession); 22203//If this is a trial policy, skip all validations and the operation 22204if(session->attributes.isTrialPolicy == CLEAR) 22205{ 22206// Get time data info. The size of time info data equals the input 22207// operand B size. A TPM_RC_RANGE error may be returned at this point 22208result = TimeGetRange(in->offset, in->operandB.t.size, &infoData); 22209if(result != TPM_RC_SUCCESS) return result; 22210// Arithmetic Comparison 22211switch(in->operation) 22212{ 22213case TPM_EO_EQ: 22214// compare A = B 22215if(CryptCompare(in->operandB.t.size, infoData, 22216in->operandB.t.size, in->operandB.t.buffer) != 0) 22217return TPM_RC_POLICY; 22218break; 22219case TPM_EO_NEQ: 22220// compare A != B 22221if(CryptCompare(in->operandB.t.size, infoData, 22222 22223Family “2.0” 22224Level 00 Revision 00.99 22225 22226Published 22227Copyright © TCG 2006-2013 22228 22229Page 267 22230October 31, 2013 22231 22232 Part 3: Commands 2223353 2223454 2223555 2223656 2223757 2223858 2223959 2224060 2224161 2224262 2224363 2224464 2224565 2224666 2224767 2224868 2224969 2225070 2225171 2225272 2225373 2225474 2225575 2225676 2225777 2225878 2225979 2226080 2226181 2226282 2226383 2226484 2226585 2226686 2226787 2226888 2226989 2227090 2227191 2227292 2227393 2227494 2227595 2227696 2227797 2227898 2227999 22280100 22281101 22282102 22283103 22284104 22285105 22286106 22287107 22288108 22289109 22290110 22291111 22292112 22293113 22294114 22295115 22296116 22297 22298Trusted Platform Module Library 22299 22300in->operandB.t.size, in->operandB.t.buffer) 22301return TPM_RC_POLICY; 22302break; 22303case TPM_EO_SIGNED_GT: 22304// compare A > B signed 22305if(CryptCompareSigned(in->operandB.t.size, infoData, 22306in->operandB.t.size, in->operandB.t.buffer) 22307return TPM_RC_POLICY; 22308break; 22309case TPM_EO_UNSIGNED_GT: 22310// compare A > B unsigned 22311if(CryptCompare(in->operandB.t.size, infoData, 22312in->operandB.t.size, in->operandB.t.buffer) 22313return TPM_RC_POLICY; 22314break; 22315case TPM_EO_SIGNED_LT: 22316// compare A < B signed 22317if(CryptCompareSigned(in->operandB.t.size, infoData, 22318in->operandB.t.size, in->operandB.t.buffer) 22319return TPM_RC_POLICY; 22320break; 22321case TPM_EO_UNSIGNED_LT: 22322// compare A < B unsigned 22323if(CryptCompare(in->operandB.t.size, infoData, 22324in->operandB.t.size, in->operandB.t.buffer) 22325return TPM_RC_POLICY; 22326break; 22327case TPM_EO_SIGNED_GE: 22328// compare A >= B signed 22329if(CryptCompareSigned(in->operandB.t.size, infoData, 22330in->operandB.t.size, in->operandB.t.buffer) 22331return TPM_RC_POLICY; 22332break; 22333case TPM_EO_UNSIGNED_GE: 22334// compare A >= B unsigned 22335if(CryptCompare(in->operandB.t.size, infoData, 22336in->operandB.t.size, in->operandB.t.buffer) 22337return TPM_RC_POLICY; 22338break; 22339case TPM_EO_SIGNED_LE: 22340// compare A <= B signed 22341if(CryptCompareSigned(in->operandB.t.size, infoData, 22342in->operandB.t.size, in->operandB.t.buffer) 22343return TPM_RC_POLICY; 22344break; 22345case TPM_EO_UNSIGNED_LE: 22346// compare A <= B unsigned 22347if(CryptCompare(in->operandB.t.size, infoData, 22348in->operandB.t.size, in->operandB.t.buffer) 22349return TPM_RC_POLICY; 22350break; 22351case TPM_EO_BITSET: 22352// All bits SET in B are SET in A. ((A&B)=B) 22353{ 22354UINT32 i; 22355for (i = 0; i < in->operandB.t.size; i++) 22356if( 22357(infoData[i] & in->operandB.t.buffer[i]) 22358!= in->operandB.t.buffer[i]) 22359return TPM_RC_POLICY; 22360} 22361break; 22362case TPM_EO_BITCLEAR: 22363// All bits SET in B are CLEAR in A. ((A&B)=0) 22364{ 22365 22366Page 268 22367October 31, 2013 22368 22369Published 22370Copyright © TCG 2006-2013 22371 22372== 0) 22373 22374<= 0) 22375 22376<= 0) 22377 22378>= 0) 22379 22380>= 0) 22381 22382< 0) 22383 22384< 0) 22385 22386> 0) 22387 22388> 0) 22389 22390Family “2.0” 22391Level 00 Revision 00.99 22392 22393 Trusted Platform Module Library 22394117 22395118 22396119 22397120 22398121 22399122 22400123 22401124 22402125 22403126 22404127 22405128 22406129 22407130 22408131 22409132 22410133 22411134 22412135 22413136 22414137 22415138 22416139 22417140 22418141 22419142 22420143 22421144 22422145 22423146 22424147 22425148 22426149 22427150 22428151 22429152 22430153 22431154 22432155 22433156 22434157 22435158 22436159 22437 22438Part 3: Commands 22439 22440UINT32 i; 22441for (i = 0; i < in->operandB.t.size; i++) 22442if((infoData[i] & in->operandB.t.buffer[i]) != 0) 22443return TPM_RC_POLICY; 22444} 22445break; 22446default: 22447pAssert(FALSE); 22448break; 22449} 22450} 22451// Internal Data Update 22452// Start argument list hash 22453argHash.t.size = CryptStartHash(session->authHashAlg, &hashState); 22454// add operandB 22455CryptUpdateDigest2B(&hashState, &in->operandB.b); 22456// add offset 22457CryptUpdateDigestInt(&hashState, sizeof(UINT16), &in->offset); 22458// add operation 22459CryptUpdateDigestInt(&hashState, sizeof(TPM_EO), &in->operation); 22460// complete argument hash 22461CryptCompleteHash2B(&hashState, &argHash.b); 22462// update policyDigest 22463// start hash 22464CryptStartHash(session->authHashAlg, &hashState); 22465// add old digest 22466CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 22467// add commandCode 22468CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 22469// add argument digest 22470CryptUpdateDigest2B(&hashState, &argHash.b); 22471// complete the digest 22472CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 22473return TPM_RC_SUCCESS; 22474} 22475 22476Family “2.0” 22477Level 00 Revision 00.99 22478 22479Published 22480Copyright © TCG 2006-2013 22481 22482Page 269 22483October 31, 2013 22484 22485 Part 3: Commands 22486 22487Trusted Platform Module Library 22488 2248925.11 TPM2_PolicyCommandCode 2249025.11.1 22491 22492General Description 22493 22494This command indicates that the authorization will be limited to a specific command code. 22495If policySession→commandCode has its default value, then it will be set to code. If 22496policySession→commandCode does not have its default value, then the TPM will return 22497TPM_RC_VALUE if the two values are not the same. 22498If code is not implemented, the TPM will return TPM_RC_POLICY_CC. 22499If the TPM does not return an error, it will update policySession→policyDigest by 22500 22501policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyCommandCode || code) 22502 22503(26) 22504 22505NOTE 1 22506 22507If a previous TPM2_PolicyCommandCode() had been executed, then it is probable that the policy 22508expression is improperly formed but the TPM does not return an error. 22509 22510NOTE 2 22511 22512A TPM2_PolicyOR() would be used to allow an authorization to be used for multiple commands. 22513 22514When the policy session is used to authorize a command, the TPM will fail the command if the 22515commandCode of that command does not match policySession→commandCode. 22516This command, or TPM2_PolicyDuplicationSelect(), is required to enable the policy to be used for ADMIN 22517role authorization. 22518EXAMPLE 22519 22520Before TPM2_Certify() can 22521TPM_CC_Certify is required. 22522 22523Page 270 22524October 31, 2013 22525 22526be 22527 22528executed, 22529 22530TPM2_PolicyCommandCode() 22531 22532Published 22533Copyright © TCG 2006-2013 22534 22535with 22536 22537code 22538 22539set 22540 22541to 22542 22543Family “2.0” 22544Level 00 Revision 00.99 22545 22546 Trusted Platform Module Library 22547 2254825.11.2 22549 22550Part 3: Commands 22551 22552Command and Response 22553Table 129 — TPM2_PolicyCommandCode Command 22554 22555Type 22556 22557Name 22558 22559Description 22560 22561TPMI_ST_COMMAND_TAG 22562 22563tag 22564 22565UINT32 22566 22567commandSize 22568 22569TPM_CC 22570 22571commandCode 22572 22573TPM_CC_PolicyCommandCode 22574 22575TPMI_SH_POLICY 22576 22577policySession 22578 22579handle for the policy session being extended 22580Auth Index: None 22581 22582TPM_CC 22583 22584code 22585 22586the allowed commandCode 22587 22588Table 130 — TPM2_PolicyCommandCode Response 22589Type 22590 22591Name 22592 22593Description 22594 22595TPM_ST 22596 22597tag 22598 22599see clause 8 22600 22601UINT32 22602 22603responseSize 22604 22605TPM_RC 22606 22607responseCode 22608 22609Family “2.0” 22610Level 00 Revision 00.99 22611 22612Published 22613Copyright © TCG 2006-2013 22614 22615Page 271 22616October 31, 2013 22617 22618 Part 3: Commands 22619 2262025.11.3 226211 226222 22623 22624Trusted Platform Module Library 22625 22626Detailed Actions 22627 22628#include "InternalRoutines.h" 22629#include "PolicyCommandCode_fp.h" 22630Error Returns 22631TPM_RC_VALUE 22632 226333 226344 226355 226366 226377 226388 226399 2264010 2264111 2264212 2264313 2264414 2264515 2264616 2264717 2264818 2264919 2265020 2265121 2265222 2265323 2265424 2265525 2265626 2265727 2265828 2265929 2266030 2266131 2266232 2266333 2266434 2266535 2266636 2266737 2266838 2266939 2267040 2267141 2267242 2267343 2267444 22675 22676Meaning 22677commandCode of policySession previously set to a different value 22678 22679TPM_RC 22680TPM2_PolicyCommandCode( 22681PolicyCommandCode_In *in 22682 22683// IN: input parameter list 22684 22685) 22686{ 22687SESSION 22688TPM_CC 22689HASH_STATE 22690 22691*session; 22692commandCode = TPM_CC_PolicyCommandCode; 22693hashState; 22694 22695// Input validation 22696// Get pointer to the session structure 22697session = SessionGet(in->policySession); 22698if(session->commandCode != 0 && session->commandCode != in->code) 22699return TPM_RC_VALUE + RC_PolicyCommandCode_code; 22700if(!CommandIsImplemented(in->code)) 22701return TPM_RC_POLICY_CC + RC_PolicyCommandCode_code; 22702// Internal Data Update 22703// Update policy hash 22704// policyDigestnew = hash(policyDigestold || TPM_CC_PolicyCommandCode || code) 22705// Start hash 22706CryptStartHash(session->authHashAlg, &hashState); 22707// add old digest 22708CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 22709// add commandCode 22710CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 22711// add input commandCode 22712CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &in->code); 22713// complete the hash and get the results 22714CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 22715// update commandCode value in session context 22716session->commandCode = in->code; 22717return TPM_RC_SUCCESS; 22718} 22719 22720Page 272 22721October 31, 2013 22722 22723Published 22724Copyright © TCG 2006-2013 22725 22726Family “2.0” 22727Level 00 Revision 00.99 22728 22729 Trusted Platform Module Library 22730 22731Part 3: Commands 22732 2273325.12 TPM2_PolicyPhysicalPresence 2273425.12.1 22735 22736General Description 22737 22738This command indicates that physical presence will need to be asserted at the time the authorization is 22739performed. 22740If this command is successful, policySession→isPPRequired will be SET to indicate that this check is 22741required when the policy is used for authorization. Additionally, policySession→policyDigest is extended 22742with 22743 22744policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyPhysicalPresence) 22745 22746Family “2.0” 22747Level 00 Revision 00.99 22748 22749Published 22750Copyright © TCG 2006-2013 22751 22752(27) 22753 22754Page 273 22755October 31, 2013 22756 22757 Part 3: Commands 22758 2275925.12.2 22760 22761Trusted Platform Module Library 22762 22763Command and Response 22764Table 131 — TPM2_PolicyPhysicalPresence Command 22765 22766Type 22767 22768Name 22769 22770Description 22771 22772TPMI_ST_COMMAND_TAG 22773 22774tag 22775 22776UINT32 22777 22778commandSize 22779 22780TPM_CC 22781 22782commandCode 22783 22784TPM_CC_PolicyPhysicalPresence 22785 22786TPMI_SH_POLICY 22787 22788policySession 22789 22790handle for the policy session being extended 22791Auth Index: None 22792 22793Table 132 — TPM2_PolicyPhysicalPresence Response 22794Type 22795 22796Name 22797 22798Description 22799 22800TPM_ST 22801 22802tag 22803 22804see clause 8 22805 22806UINT32 22807 22808responseSize 22809 22810TPM_RC 22811 22812responseCode 22813 22814Page 274 22815October 31, 2013 22816 22817Published 22818Copyright © TCG 2006-2013 22819 22820Family “2.0” 22821Level 00 Revision 00.99 22822 22823 Trusted Platform Module Library 22824 2282525.12.3 228261 228272 228283 228294 228305 228316 228327 228338 228349 2283510 2283611 2283712 2283813 2283914 2284015 2284116 2284217 2284318 2284419 2284520 2284621 2284722 2284823 2284924 2285025 2285126 2285227 2285328 2285429 2285530 2285631 2285732 2285833 2285934 2286035 22861 22862Part 3: Commands 22863 22864Detailed Actions 22865 22866#include "InternalRoutines.h" 22867#include "PolicyPhysicalPresence_fp.h" 22868 22869TPM_RC 22870TPM2_PolicyPhysicalPresence( 22871PolicyPhysicalPresence_In *in 22872 22873// IN: input parameter list 22874 22875) 22876{ 22877SESSION 22878TPM_CC 22879HASH_STATE 22880 22881*session; 22882commandCode = TPM_CC_PolicyPhysicalPresence; 22883hashState; 22884 22885// Internal Data Update 22886// Get pointer to the session structure 22887session = SessionGet(in->policySession); 22888// Update policy hash 22889// policyDigestnew = hash(policyDigestold || TPM_CC_PolicyPhysicalPresence) 22890// Start hash 22891CryptStartHash(session->authHashAlg, &hashState); 22892// add old digest 22893CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 22894// add commandCode 22895CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 22896// complete the digest 22897CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 22898// update session attribute 22899session->attributes.isPPRequired = SET; 22900return TPM_RC_SUCCESS; 22901} 22902 22903Family “2.0” 22904Level 00 Revision 00.99 22905 22906Published 22907Copyright © TCG 2006-2013 22908 22909Page 275 22910October 31, 2013 22911 22912 Part 3: Commands 22913 22914Trusted Platform Module Library 22915 2291625.13 TPM2_PolicyCpHash 2291725.13.1 22918 22919General Description 22920 22921This command is used to allow a policy to be bound to a specific command and command parameters. 22922TPM2_PolicySigned(), TPM2_PolicySecret(), and TPM2_PolicyTIcket() are designed to allow an 22923authorizing entity to execute an arbitrary command as the cpHashA parameter of those commands is not 22924included in policySession→policyDigest. TPM2_PolicyCommandCode() allows the policy to be bound to a 22925specific Command Code so that only certain entities may authorize specific command codes. This 22926command allows the policy to be restricted such that an entity may only authorize a command with a 22927specific set of parameters. 22928If policySession→cpHash is already set and not the same as cpHashA, then the TPM shall return 22929TPM_RC_VALUE. If cpHashA does not have the size of the policySession→policyDigest, the TPM shall 22930return TPM_RC_SIZE. 22931If the cpHashA checks succeed, policySession→cpHash 22932policySession→policyDigest is updated with 22933 22934is 22935 22936set 22937 22938to 22939 22940cpHashA 22941 22942policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyCpHash || cpHashA) 22943 22944Page 276 22945October 31, 2013 22946 22947Published 22948Copyright © TCG 2006-2013 22949 22950and 22951(28) 22952 22953Family “2.0” 22954Level 00 Revision 00.99 22955 22956 Trusted Platform Module Library 22957 2295825.13.2 22959 22960Part 3: Commands 22961 22962Command and Response 22963Table 133 — TPM2_PolicyCpHash Command 22964 22965Type 22966 22967Name 22968 22969Description 22970 22971TPMI_ST_COMMAND_TAG 22972 22973tag 22974 22975UINT32 22976 22977commandSize 22978 22979TPM_CC 22980 22981commandCode 22982 22983TPM_CC_PolicyCpHash 22984 22985TPMI_SH_POLICY 22986 22987policySession 22988 22989handle for the policy session being extended 22990Auth Index: None 22991 22992TPM2B_DIGEST 22993 22994cpHashA 22995 22996the cpHash added to the policy 22997 22998Table 134 — TPM2_PolicyCpHash Response 22999Type 23000 23001Name 23002 23003Description 23004 23005TPM_ST 23006 23007tag 23008 23009see clause 8 23010 23011UINT32 23012 23013responseSize 23014 23015TPM_RC 23016 23017responseCode 23018 23019Family “2.0” 23020Level 00 Revision 00.99 23021 23022Published 23023Copyright © TCG 2006-2013 23024 23025Page 277 23026October 31, 2013 23027 23028 Part 3: Commands 23029 2303025.13.3 230311 230322 23033 23034Trusted Platform Module Library 23035 23036Detailed Actions 23037 23038#include "InternalRoutines.h" 23039#include "PolicyCpHash_fp.h" 23040Error Returns 23041TPM_RC_CPHASH 23042 23043cpHash of policySession has previously been set to a different value 23044 23045TPM_RC_SIZE 23046 230473 230484 230495 230506 230517 230528 230539 2305410 2305511 2305612 2305713 2305814 2305915 2306016 2306117 2306218 2306319 2306420 2306521 2306622 2306723 2306824 2306925 2307026 2307127 2307228 2307329 2307430 2307531 2307632 2307733 2307834 2307935 2308036 2308137 2308238 2308339 2308440 2308541 2308642 2308743 2308844 2308945 2309046 2309147 2309248 2309349 2309450 2309551 2309652 23097 23098Meaning 23099 23100cpHashA is not the size of a digest produced by the hash algorithm 23101associated with policySession 23102 23103TPM_RC 23104TPM2_PolicyCpHash( 23105PolicyCpHash_In *in 23106 23107// IN: input parameter list 23108 23109) 23110{ 23111SESSION 23112TPM_CC 23113HASH_STATE 23114 23115*session; 23116commandCode = TPM_CC_PolicyCpHash; 23117hashState; 23118 23119// Input Validation 23120// Get pointer to the session structure 23121session = SessionGet(in->policySession); 23122// A new cpHash is given in input parameter, but cpHash in session context 23123// is not empty, or is not the same as the new cpHash 23124if( 23125in->cpHashA.t.size != 0 23126&& session->u1.cpHash.t.size != 0 23127&& !Memory2BEqual(&in->cpHashA.b, &session->u1.cpHash.b) 23128) 23129return TPM_RC_CPHASH; 23130// A valid cpHash must have the same size as session hash digest 23131if(in->cpHashA.t.size != CryptGetHashDigestSize(session->authHashAlg)) 23132return TPM_RC_SIZE + RC_PolicyCpHash_cpHashA; 23133// Internal Data Update 23134// Update policy hash 23135// policyDigestnew = hash(policyDigestold || TPM_CC_PolicyCpHash || cpHashA) 23136// Start hash 23137CryptStartHash(session->authHashAlg, &hashState); 23138// add old digest 23139CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 23140// add commandCode 23141CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 23142// add cpHashA 23143CryptUpdateDigest2B(&hashState, &in->cpHashA.b); 23144// complete the digest and get the results 23145CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 23146// update cpHash in session context 23147session->u1.cpHash = in->cpHashA; 23148session->attributes.iscpHashDefined = SET; 23149return TPM_RC_SUCCESS; 23150 23151Page 278 23152October 31, 2013 23153 23154Published 23155Copyright © TCG 2006-2013 23156 23157Family “2.0” 23158Level 00 Revision 00.99 23159 23160 Trusted Platform Module Library 2316153 23162 23163Part 3: Commands 23164 23165} 23166 23167Family “2.0” 23168Level 00 Revision 00.99 23169 23170Published 23171Copyright © TCG 2006-2013 23172 23173Page 279 23174October 31, 2013 23175 23176 Part 3: Commands 23177 23178Trusted Platform Module Library 23179 2318025.14 TPM2_PolicyNameHash 2318125.14.1 23182 23183General Description 23184 23185This command allows a policy to be bound to a specific set of TPM entities without being bound to the 23186parameters of the command. This is most useful for commands such as TPM2_Duplicate() and for 23187TPM2_PCR_Event() when the referenced PCR requires a policy. 23188The nameHash parameter should contain the digest of the Names associated with the handles to be used 23189in the authorized command. 23190EXAMPLE 23191 23192For the TPM2_Duplicate() command, two handles are provided. One is the handle of the object 23193being duplicated and the other is the handle of the new parent. For that command, nameHash would 23194contain: 23195 23196nameHash ≔ H policyAlg (objectHandle→Name || newParentHandle→Name) 23197 23198If policySession→cpHash is already set, the TPM shall return TPM_RC_VALUE. If the size of nameHash 23199is not the size of policySession→policyDigest, the TPM shall return TPM_RC_SIZE. Otherwise, 23200policySession→cpHash is set to nameHash. 23201If this command completes successfully, the cpHash of the authorized command will not be used for 23202validation. Only the digest of the Names associated with the handles in the command will be used. 23203NOTE 1 23204 23205This allows the space normally 23206policySession→nameHash instead. 23207 23208used 23209 23210to 23211 23212hold 23213 23214policySession→cpHash 23215 23216to 23217 23218be 23219 23220used 23221 23222for 23223 23224The policySession→policyDigest will be updated with 23225 23226policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyNameHash || nameHash) 23227NOTE 2 23228 23229(29) 23230 23231This command will often be used with TPM2_PolicyAuthorize() where the owner of the object being 23232duplicated provides approval for their object to be migrated to a specific new parent. 23233 23234Page 280 23235October 31, 2013 23236 23237Published 23238Copyright © TCG 2006-2013 23239 23240Family “2.0” 23241Level 00 Revision 00.99 23242 23243 Trusted Platform Module Library 23244 2324525.14.2 23246 23247Part 3: Commands 23248 23249Command and Response 23250Table 135 — TPM2_PolicyNameHash Command 23251 23252Type 23253 23254Name 23255 23256Description 23257 23258TPMI_ST_COMMAND_TAG 23259 23260tag 23261 23262UINT32 23263 23264commandSize 23265 23266TPM_CC 23267 23268commandCode 23269 23270TPM_CC_PolicyNameHash 23271 23272TPMI_SH_POLICY 23273 23274policySession 23275 23276handle for the policy session being extended 23277Auth Index: None 23278 23279TPM2B_DIGEST 23280 23281nameHash 23282 23283the digest to be added to the policy 23284 23285Table 136 — TPM2_PolicyNameHash Response 23286Type 23287 23288Name 23289 23290Description 23291 23292TPM_ST 23293 23294tag 23295 23296see clause 8 23297 23298UINT32 23299 23300responseSize 23301 23302TPM_RC 23303 23304responseCode 23305 23306Family “2.0” 23307Level 00 Revision 00.99 23308 23309Published 23310Copyright © TCG 2006-2013 23311 23312Page 281 23313October 31, 2013 23314 23315 Part 3: Commands 23316 2331725.14.3 233181 233192 23320 23321Trusted Platform Module Library 23322 23323Detailed Actions 23324 23325#include "InternalRoutines.h" 23326#include "PolicyNameHash_fp.h" 23327Error Returns 23328TPM_RC_CPHASH 23329 23330nameHash has been previously set to a different value 23331 23332TPM_RC_SIZE 23333 233343 233354 233365 233376 233387 233398 233409 2334110 2334211 2334312 2334413 2334514 2334615 2334716 2334817 2334918 2335019 2335120 2335221 2335322 2335423 2335524 2335625 2335726 2335827 2335928 2336029 2336130 2336231 2336332 2336433 2336534 2336635 2336736 2336837 2336938 2337039 2337140 2337241 2337342 2337443 2337544 2337645 2337746 2337847 2337948 2338049 2338150 2338251 2338352 23384 23385Meaning 23386 23387nameHash is not the size of the digest produced by the hash 23388algorithm associated with policySession 23389 23390TPM_RC 23391TPM2_PolicyNameHash( 23392PolicyNameHash_In 23393 23394*in 23395 23396// IN: input parameter list 23397 23398SESSION 23399TPM_CC 23400HASH_STATE 23401 23402*session; 23403commandCode = TPM_CC_PolicyNameHash; 23404hashState; 23405 23406) 23407{ 23408 23409// Input Validation 23410// Get pointer to the session structure 23411session = SessionGet(in->policySession); 23412// A new nameHash is given in input parameter, but cpHash in session context 23413// is not empty 23414if(in->nameHash.t.size != 0 && session->u1.cpHash.t.size != 0) 23415return TPM_RC_CPHASH; 23416// A valid nameHash must have the same size as session hash digest 23417if(in->nameHash.t.size != CryptGetHashDigestSize(session->authHashAlg)) 23418return TPM_RC_SIZE + RC_PolicyNameHash_nameHash; 23419// Internal Data Update 23420// Update policy hash 23421// policyDigestnew = hash(policyDigestold || TPM_CC_PolicyNameHash || nameHash) 23422// Start hash 23423CryptStartHash(session->authHashAlg, &hashState); 23424// add old digest 23425CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 23426// add commandCode 23427CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 23428// add nameHash 23429CryptUpdateDigest2B(&hashState, &in->nameHash.b); 23430// complete the digest 23431CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 23432// clear iscpHashDefined bit to indicate now this field contains a nameHash 23433session->attributes.iscpHashDefined = CLEAR; 23434// update nameHash in session context 23435session->u1.cpHash = in->nameHash; 23436return TPM_RC_SUCCESS; 23437} 23438 23439Page 282 23440October 31, 2013 23441 23442Published 23443Copyright © TCG 2006-2013 23444 23445Family “2.0” 23446Level 00 Revision 00.99 23447 23448 Trusted Platform Module Library 23449 23450Part 3: Commands 23451 2345225.15 TPM2_PolicyDuplicationSelect 2345325.15.1 23454 23455General Description 23456 23457This command allows qualification of duplication to allow duplication to a selected new parent. 23458If this command not used in conjunction with TPM2_PolicyAuthorize(), then only the new parent is 23459selected. 23460EXAMPLE 23461 23462When an object is created when the list of allowed duplication targets is known, the policy would be 23463created with includeObject CLEAR. 23464 23465NOTE 1 23466 23467Only the new parent may be selected because, without TPM2_PolicyAuthorize() , the Name of the 23468Object to be duplicated would need to be known at the time that Object's policy is created. However, 23469since the Name of the Object includes its policy, the Name is not known. 23470 23471If used in conjunction with TPM2_PolicyAuthorize(), then the authorizer of the new policy has the option 23472of selecting just the new parent or of selecting both the new parent and the duplication Object.. 23473NOTE 2 23474 23475If the authorizing entity for an TPM2_PolicyAuthorize() only specifies the new parent, then that 23476authorization may be applied to the duplication of any number of other Objects. If the authorizing 23477entity specifies both a new parent and the duplicated Object, then the authorization only applies to 23478that pairing of Object and new parent. 23479 23480If either policySession→cpHash or policySession→nameHash has been previously set, the TPM shall 23481return TPM_RC_CPHASH. Otherwise, policySession→nameHash will be set to: 23482 23483nameHash ≔ HpolicyAlg(objectName || newParentName) 23484 23485(30) 23486 23487It is allowed that policySesion→nameHash and policySession→cpHash share the same memory 23488space. 23489 23490NOTE 3 23491 23492The policySession→policyDigest will be updated according to the setting of includeObject. If equal to 23493YES, policySession→policyDigest is updated by: 23494 23495policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyDuplicationSelect || 23496objectName || newParentName || includeObject) 23497 23498(31) 23499 23500If includeObject is NO, policySession→policyDigest is updated by: 23501 23502policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyDuplicationSelect || 23503newParentName || includeObject) 23504NOTE 4 23505 23506(32) 23507 23508PolicySession→CpHash receives the digest of both Names so that the check performed in 23509TPM2_Duplicate() may be the same regardless of which Names are included in 23510policySession→policyDigest. This means that, when TPM2_PolicyDuplicationSelect() is executed, it 23511is only valid for a specific pair of duplication object and new parent. 23512 23513If the command succeeds, commandCode in the policy session context is set to TPM_CC_Duplicate. 23514NOTE 5 23515 23516The normal use of this command is before a TPM2_PolicyAuthorize(). An authorized entity would 23517approve a policyDigest that allowed duplication to a specific new parent. The authorizing entity may 23518want to limit the authorization so that the approval allows only a specific object to be duplicated to 23519the new parent. In that case, the authorizing entity would approve the policyDigest of equation (31). 23520 23521Family “2.0” 23522Level 00 Revision 00.99 23523 23524Published 23525Copyright © TCG 2006-2013 23526 23527Page 283 23528October 31, 2013 23529 23530 Part 3: Commands 23531 2353225.15.2 23533 23534Trusted Platform Module Library 23535 23536Command and Response 23537Table 137 — TPM2_PolicyDuplicationSelect Command 23538 23539Type 23540 23541Name 23542 23543Description 23544 23545TPMI_ST_COMMAND_TAG 23546 23547tag 23548 23549UINT32 23550 23551commandSize 23552 23553TPM_CC 23554 23555commandCode 23556 23557TPM_CC_PolicyDuplicationSelect 23558 23559TPMI_SH_POLICY 23560 23561policySession 23562 23563handle for the policy session being extended 23564Auth Index: None 23565 23566TPM2B_NAME 23567 23568objectName 23569 23570the Name of the object to be duplicated 23571 23572TPM2B_NAME 23573 23574newParentName 23575 23576the Name of the new parent 23577 23578TPMI_YES_NO 23579 23580includeObject 23581 23582if YES, the objectName will be included in the value in 23583policySession→policyDigest 23584 23585Table 138 — TPM2_PolicyDuplicationSelect Response 23586Type 23587 23588Name 23589 23590Description 23591 23592TPM_ST 23593 23594tag 23595 23596see clause 8 23597 23598UINT32 23599 23600responseSize 23601 23602TPM_RC 23603 23604responseCode 23605 23606Page 284 23607October 31, 2013 23608 23609Published 23610Copyright © TCG 2006-2013 23611 23612Family “2.0” 23613Level 00 Revision 00.99 23614 23615 Trusted Platform Module Library 23616 2361725.15.3 236181 236192 23620 23621Part 3: Commands 23622 23623Detailed Actions 23624 23625#include "InternalRoutines.h" 23626#include "PolicyDuplicationSelect_fp.h" 23627Error Returns 23628TPM_RC_COMMAND_CODE 23629 23630commandCode of 'policySession; is not empty 23631 23632TPM_RC_CPHASH 236333 236344 236355 236366 236377 236388 236399 2364010 2364111 2364212 2364313 2364414 2364515 2364616 2364717 2364818 2364919 2365020 2365121 2365222 2365323 2365424 2365525 2365626 2365727 2365828 2365929 2366030 2366131 2366232 2366333 2366434 2366535 2366636 2366737 2366838 2366939 2367040 2367141 2367242 2367343 2367444 2367545 2367646 2367747 2367848 2367949 2368050 2368151 2368252 2368353 23684 23685Meaning 23686 23687cpHash of policySession is not empty 23688 23689TPM_RC 23690TPM2_PolicyDuplicationSelect( 23691PolicyDuplicationSelect_In *in 23692 23693// IN: input parameter list 23694 23695) 23696{ 23697SESSION 23698HASH_STATE 23699TPM_CC 23700 23701*session; 23702hashState; 23703commandCode = TPM_CC_PolicyDuplicationSelect; 23704 23705// Input Validation 23706// Get pointer to the session structure 23707session = SessionGet(in->policySession); 23708// cpHash in session context must be empty 23709if(session->u1.cpHash.t.size != 0) 23710return TPM_RC_CPHASH; 23711// commandCode in session context must be empty 23712if(session->commandCode != 0) 23713return TPM_RC_COMMAND_CODE; 23714// Internal Data Update 23715// Update name hash 23716session->u1.cpHash.t.size = CryptStartHash(session->authHashAlg, &hashState); 23717// add objectName 23718CryptUpdateDigest2B(&hashState, &in->objectName.b); 23719// add new parent name 23720CryptUpdateDigest2B(&hashState, &in->newParentName.b); 23721// complete hash 23722CryptCompleteHash2B(&hashState, &session->u1.cpHash.b); 23723// update policy hash 23724// Old policyDigest size should be the same as the new policyDigest size since 23725// they are using the same hash algorithm 23726session->u2.policyDigest.t.size 23727= CryptStartHash(session->authHashAlg, &hashState); 23728// add old policy 23729CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 23730// add command code 23731CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 23732// add objectName 23733if(in->includeObject == YES) 23734CryptUpdateDigest2B(&hashState, &in->objectName.b); 23735 23736Family “2.0” 23737Level 00 Revision 00.99 23738 23739Published 23740Copyright © TCG 2006-2013 23741 23742Page 285 23743October 31, 2013 23744 23745 Part 3: Commands 2374654 2374755 2374856 2374957 2375058 2375159 2375260 2375361 2375462 2375563 2375664 2375765 2375866 2375967 2376068 2376169 2376270 2376371 23764 23765Trusted Platform Module Library 23766 23767// add new parent name 23768CryptUpdateDigest2B(&hashState, &in->newParentName.b); 23769// add includeObject 23770CryptUpdateDigestInt(&hashState, sizeof(TPMI_YES_NO), &in->includeObject); 23771// complete digest 23772CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 23773// clear iscpHashDefined bit to indicate now this field contains a nameHash 23774session->attributes.iscpHashDefined = CLEAR; 23775// set commandCode in session context 23776session->commandCode = TPM_CC_Duplicate; 23777return TPM_RC_SUCCESS; 23778} 23779 23780Page 286 23781October 31, 2013 23782 23783Published 23784Copyright © TCG 2006-2013 23785 23786Family “2.0” 23787Level 00 Revision 00.99 23788 23789 Trusted Platform Module Library 23790 23791Part 3: Commands 23792 2379325.16 TPM2_PolicyAuthorize 2379425.16.1 23795 23796General Description 23797 23798This command allows policies to change. If a policy were static, then it would be difficult to add users to a 23799policy. This command lets a policy authority sign a new policy so that it may be used in an existing policy. 23800The authorizing entity signs a structure that contains 23801 23802aHash ≔ HaHashAlg(approvedPolicy || policyRef) 23803 23804(33) 23805 23806The aHashAlg is required to be the nameAlg of the key used to sign the aHash. The aHash value is then 23807signed (symmetric or asymmetric) by keySign. That signature is then checked by the TPM in 23808TPM2_VerifySignature() which produces a ticket by 23809 23810HMAC(proof, (TPM_ST_VERIFIED || aHash || keySign→Name)) 23811NOTE 23812 23813(34) 23814 23815The reason for the validation is because of the expectation that the policy will be used multiple times 23816and it is more efficient to check a ticket than to load an object each time to chec k a signature. 23817 23818The ticket is then used in TPM2_PolicyAuthorize() to validate the parameters. 23819The keySign parameter is required to be a valid object name using nameAlg other than TPM_ALG_NULL. 23820If the first two octets of keySign are not a valid hash algorithm, the TPM shall return TPM_RC_HASH. If 23821the remainder of the Name is not the size of the indicated digest, the TPM shall return TPM_RC_SIZE. 23822The TPM validates that the approvedPolicy matches the current value of policySession→policyDigest and 23823if not, shall return TPM_RC_VALUE. 23824The TPM then validates that the parameters to TPM2_PolicyAuthorize() match the values used to 23825generate the ticket. If so, the TPM will reset policySession→policyDigest to a Zero Digest. Then it will 23826create a TPM2B_NAME (keyName) using keySign and update policySession→policyDigest with 23827PolicyUpdate() (see 25.2.3). 23828 23829PolicyUpdate(TPM_CC_PolicyAuthorize, keyName, policyRef) 23830 23831(35) 23832 23833If the ticket is not valid, the TPM shall return TPM_RC_POLICY. 23834If policySession is a trial session, policySession→policyDigest is extended as if the ticket is valid without 23835actual verification. 23836NOTE 23837 23838The unmarshaling process requires that a proper TPMT_TK_VERIFIED be provided for checkTicket 23839but it may be a NULL Ticket. 23840 23841Family “2.0” 23842Level 00 Revision 00.99 23843 23844Published 23845Copyright © TCG 2006-2013 23846 23847Page 287 23848October 31, 2013 23849 23850 Part 3: Commands 23851 2385225.16.2 23853 23854Trusted Platform Module Library 23855 23856Command and Response 23857Table 139 — TPM2_PolicyAuthorize Command 23858 23859Type 23860 23861Name 23862 23863Description 23864 23865TPMI_ST_COMMAND_TAG 23866 23867tag 23868 23869UINT32 23870 23871commandSize 23872 23873TPM_CC 23874 23875commandCode 23876 23877TPM_CC_PolicyAuthorize 23878 23879TPMI_SH_POLICY 23880 23881policySession 23882 23883handle for the policy session being extended 23884Auth Index: None 23885 23886TPM2B_DIGEST 23887 23888approvedPolicy 23889 23890digest of the policy being approved 23891 23892TPM2B_NONCE 23893 23894policyRef 23895 23896a policy qualifier 23897 23898TPM2B_NAME 23899 23900keySign 23901 23902Name of a key that can sign a policy addition 23903 23904TPMT_TK_VERIFIED 23905 23906checkTicket 23907 23908ticket validating that approvedPolicy and policyRef were 23909signed by keySign 23910 23911Table 140 — TPM2_PolicyAuthorize Response 23912Type 23913 23914Name 23915 23916Description 23917 23918TPM_ST 23919 23920tag 23921 23922see clause 8 23923 23924UINT32 23925 23926responseSize 23927 23928TPM_RC 23929 23930responseCode 23931 23932Page 288 23933October 31, 2013 23934 23935Published 23936Copyright © TCG 2006-2013 23937 23938Family “2.0” 23939Level 00 Revision 00.99 23940 23941 Trusted Platform Module Library 23942 2394325.16.3 239441 239452 239463 23947 23948Part 3: Commands 23949 23950Detailed Actions 23951 23952#include "InternalRoutines.h" 23953#include "PolicyAuthorize_fp.h" 23954#include "Policy_spt_fp.h" 23955Error Returns 23956TPM_RC_HASH 23957 23958hash algorithm in keyName is not supported 23959 23960TPM_RC_SIZE 23961 23962keyName is not the correct size for its hash algorithm 23963 23964TPM_RC_VALUE 23965 239664 239675 239686 239697 239708 239719 2397210 2397311 2397412 2397513 2397614 2397715 2397816 2397917 2398018 2398119 2398220 2398321 2398422 2398523 2398624 2398725 2398826 2398927 2399028 2399129 2399230 2399331 2399432 2399533 2399634 2399735 2399836 2399937 2400038 2400139 2400240 2400341 2400442 2400543 2400644 2400745 2400846 2400947 2401048 2401149 2401250 24013 24014Meaning 24015 24016the current policyDigest of policySession does not match 24017approvedPolicy; or checkTicket doesn't match the provided values 24018 24019TPM_RC 24020TPM2_PolicyAuthorize( 24021PolicyAuthorize_In 24022 24023*in 24024 24025// IN: input parameter list 24026 24027SESSION 24028TPM2B_DIGEST 24029HASH_STATE 24030TPMT_TK_VERIFIED 24031TPM_ALG_ID 24032UINT16 24033 24034*session; 24035authHash; 24036hashState; 24037ticket; 24038hashAlg; 24039digestSize; 24040 24041) 24042{ 24043 24044// Input Validation 24045// Get pointer to the session structure 24046session = SessionGet(in->policySession); 24047// Extract from the Name of the key, the algorithm used to compute it's Name 24048hashAlg = BYTE_ARRAY_TO_UINT16(in->keySign.t.name); 24049// 'keySign' parameter needs to use a supported hash algorithm, otherwise 24050// can't tell how large the digest should be 24051digestSize = CryptGetHashDigestSize(hashAlg); 24052if(digestSize == 0) 24053return TPM_RC_HASH + RC_PolicyAuthorize_keySign; 24054if(digestSize != (in->keySign.t.size - 2)) 24055return TPM_RC_SIZE + RC_PolicyAuthorize_keySign; 24056//If this is a trial policy, skip all validations 24057if(session->attributes.isTrialPolicy == CLEAR) 24058{ 24059// Check that "approvedPolicy" matches the current value of the 24060// policyDigest in policy session 24061if(!Memory2BEqual(&session->u2.policyDigest.b, 24062&in->approvedPolicy.b)) 24063return TPM_RC_VALUE + RC_PolicyAuthorize_approvedPolicy; 24064// Validate ticket TPMT_TK_VERIFIED 24065// Compute aHash. The authorizing object sign a digest 24066// aHash := hash(approvedPolicy || policyRef). 24067// Start hash 24068authHash.t.size = CryptStartHash(hashAlg, &hashState); 24069// add approvedPolicy 24070CryptUpdateDigest2B(&hashState, &in->approvedPolicy.b); 24071 24072Family “2.0” 24073Level 00 Revision 00.99 24074 24075Published 24076Copyright © TCG 2006-2013 24077 24078Page 289 24079October 31, 2013 24080 24081 Part 3: Commands 2408251 2408352 2408453 2408554 2408655 2408756 2408857 2408958 2409059 2409160 2409261 2409362 2409463 2409564 2409665 2409766 2409867 2409968 2410069 2410170 2410271 2410372 2410473 2410574 2410675 2410776 2410877 2410978 24110 24111Trusted Platform Module Library 24112 24113// add policyRef 24114CryptUpdateDigest2B(&hashState, &in->policyRef.b); 24115// complete hash 24116CryptCompleteHash2B(&hashState, &authHash.b); 24117// re-compute TPMT_TK_VERIFIED 24118TicketComputeVerified(in->checkTicket.hierarchy, &authHash, 24119&in->keySign, &ticket); 24120// Compare ticket digest. If not match, return error 24121if(!Memory2BEqual(&in->checkTicket.digest.b, &ticket.digest.b)) 24122return TPM_RC_VALUE+ RC_PolicyAuthorize_checkTicket; 24123} 24124// Internal Data Update 24125// Set policyDigest to zero digest 24126MemorySet(session->u2.policyDigest.t.buffer, 0, 24127session->u2.policyDigest.t.size); 24128// Update policyDigest 24129PolicyContextUpdate(TPM_CC_PolicyAuthorize, &in->keySign, &in->policyRef, 24130NULL, 0, session); 24131return TPM_RC_SUCCESS; 24132} 24133 24134Page 290 24135October 31, 2013 24136 24137Published 24138Copyright © TCG 2006-2013 24139 24140Family “2.0” 24141Level 00 Revision 00.99 24142 24143 Trusted Platform Module Library 24144 24145Part 3: Commands 24146 2414725.17 TPM2_PolicyAuthValue 2414825.17.1 24149 24150General Description 24151 24152This command allows a policy to be bound to the authorization value of the authorized object. 24153When this command completes successfully, policySession→isAuthValueNeeded is SET to indicate that 24154the authValue will be included in hmacKey when the authorization HMAC is computed for this session. 24155Additionally, policySession→isPasswordNeeded will be CLEAR. 24156NOTE 24157 24158If a policy does not use this command, then the hmacKey for the authorized command would only 24159use sessionKey. If sessionKey is not present, then the hmacKey is an Empty Buffer and no HMAC 24160would be computed. 24161 24162If successful, policySession→policyDigest will be updated with 24163 24164policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyAuthValue) 24165 24166Family “2.0” 24167Level 00 Revision 00.99 24168 24169Published 24170Copyright © TCG 2006-2013 24171 24172(36) 24173 24174Page 291 24175October 31, 2013 24176 24177 Part 3: Commands 24178 2417925.17.2 24180 24181Trusted Platform Module Library 24182 24183Command and Response 24184Table 141 — TPM2_PolicyAuthValue Command 24185 24186Type 24187 24188Name 24189 24190Description 24191 24192TPMI_ST_COMMAND_TAG 24193 24194tag 24195 24196UINT32 24197 24198commandSize 24199 24200TPM_CC 24201 24202commandCode 24203 24204TPM_CC_PolicyAuthValue 24205 24206TPMI_SH_POLICY 24207 24208policySession 24209 24210handle for the policy session being extended 24211Auth Index: None 24212 24213Table 142 — TPM2_PolicyAuthValue Response 24214Type 24215 24216Name 24217 24218Description 24219 24220TPM_ST 24221 24222tag 24223 24224see clause 8 24225 24226UINT32 24227 24228responseSize 24229 24230TPM_RC 24231 24232responseCode 24233 24234Page 292 24235October 31, 2013 24236 24237Published 24238Copyright © TCG 2006-2013 24239 24240Family “2.0” 24241Level 00 Revision 00.99 24242 24243 Trusted Platform Module Library 24244 2424525.17.3 242461 242472 242483 242494 242505 242516 242527 242538 242549 2425510 2425611 2425712 2425813 2425914 2426015 2426116 2426217 2426318 2426419 2426520 2426621 2426722 2426823 2426924 2427025 2427126 2427227 2427328 2427429 2427530 2427631 2427732 2427833 2427934 2428035 2428136 2428237 24283 24284Part 3: Commands 24285 24286Detailed Actions 24287 24288#include "InternalRoutines.h" 24289#include "PolicyAuthValue_fp.h" 24290#include "Policy_spt_fp.h" 24291 24292TPM_RC 24293TPM2_PolicyAuthValue( 24294PolicyAuthValue_In 24295 24296*in 24297 24298// IN: input parameter list 24299 24300SESSION 24301TPM_CC 24302HASH_STATE 24303 24304*session; 24305commandCode = TPM_CC_PolicyAuthValue; 24306hashState; 24307 24308) 24309{ 24310 24311// Internal Data Update 24312// Get pointer to the session structure 24313session = SessionGet(in->policySession); 24314// Update policy hash 24315// policyDigestnew = hash(policyDigestold || TPM_CC_PolicyAuthValue) 24316// 24317Start hash 24318CryptStartHash(session->authHashAlg, &hashState); 24319// add old digest 24320CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 24321// add commandCode 24322CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 24323// complete the hash and get the results 24324CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 24325// update isAuthValueNeeded bit in the session context 24326session->attributes.isAuthValueNeeded = SET; 24327session->attributes.isPasswordNeeded = CLEAR; 24328return TPM_RC_SUCCESS; 24329} 24330 24331Family “2.0” 24332Level 00 Revision 00.99 24333 24334Published 24335Copyright © TCG 2006-2013 24336 24337Page 293 24338October 31, 2013 24339 24340 Part 3: Commands 24341 24342Trusted Platform Module Library 24343 2434425.18 TPM2_PolicyPassword 2434525.18.1 24346 24347General Description 24348 24349This command allows a policy to be bound to the authorization value of the authorized object. 24350When this command completes successfully, policySession→isPasswordNeeded is SET to indicate that 24351authValue of the authorized object will be checked when the session is used for authorization. The caller 24352will provide the authValue in clear text in the hmac parameter of the authorization. The comparison of 24353hmac to authValue is performed as if the authorization is a password. 24354NOTE 1 24355 24356The parameter field in the policy session where the authorization value is provided is called hmac. If 24357TPM2_PolicyPassword() is part of the sequence, then the field will contain a password and not an 24358HMAC. 24359 24360If successful, policySession→policyDigest will be updated with 24361 24362policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyAuthValue) 24363NOTE 2 24364 24365(37) 24366 24367This is the same extend value as used with TPM2_PolicyAuthValue so that the evaluation may be 24368done using either an HMAC or a password with no change to the authPolicy of the object. The 24369reason that two commands are present is to indicate to the TPM if the hmac field in the authorization 24370will contain an HMAC or a password value. 24371 24372When this command is successful, policySession→isAuthValueNeeded will be CLEAR. 24373 24374Page 294 24375October 31, 2013 24376 24377Published 24378Copyright © TCG 2006-2013 24379 24380Family “2.0” 24381Level 00 Revision 00.99 24382 24383 Trusted Platform Module Library 24384 2438525.18.2 24386 24387Part 3: Commands 24388 24389Command and Response 24390Table 143 — TPM2_PolicyPassword Command 24391 24392Type 24393 24394Name 24395 24396Description 24397 24398TPMI_ST_COMMAND_TAG 24399 24400tag 24401 24402UINT32 24403 24404commandSize 24405 24406TPM_CC 24407 24408commandCode 24409 24410TPM_CC_PolicyPassword 24411 24412TPMI_SH_POLICY 24413 24414policySession 24415 24416handle for the policy session being extended 24417Auth Index: None 24418 24419Table 144 — TPM2_PolicyPassword Response 24420Type 24421 24422Name 24423 24424Description 24425 24426TPM_ST 24427 24428tag 24429 24430see clause 8 24431 24432UINT32 24433 24434responseSize 24435 24436TPM_RC 24437 24438responseCode 24439 24440Family “2.0” 24441Level 00 Revision 00.99 24442 24443Published 24444Copyright © TCG 2006-2013 24445 24446Page 295 24447October 31, 2013 24448 24449 Part 3: Commands 24450 2445125.18.3 244521 244532 244543 244554 244565 244576 244587 244598 244609 2446110 2446211 2446312 2446413 2446514 2446615 2446716 2446817 2446918 2447019 2447120 2447221 2447322 2447423 2447524 2447625 2447726 2447827 2447928 2448029 2448130 2448231 2448332 2448433 2448534 2448635 2448736 2448837 24489 24490Trusted Platform Module Library 24491 24492Detailed Actions 24493 24494#include "InternalRoutines.h" 24495#include "PolicyPassword_fp.h" 24496#include "Policy_spt_fp.h" 24497 24498TPM_RC 24499TPM2_PolicyPassword( 24500PolicyPassword_In 24501 24502*in 24503 24504// IN: input parameter list 24505 24506SESSION 24507TPM_CC 24508HASH_STATE 24509 24510*session; 24511commandCode = TPM_CC_PolicyAuthValue; 24512hashState; 24513 24514) 24515{ 24516 24517// Internal Data Update 24518// Get pointer to the session structure 24519session = SessionGet(in->policySession); 24520// Update policy hash 24521// policyDigestnew = hash(policyDigestold || TPM_CC_PolicyAuthValue) 24522// Start hash 24523CryptStartHash(session->authHashAlg, &hashState); 24524// add old digest 24525CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 24526// add commandCode 24527CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 24528// complete the digest 24529CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 24530// Update isPasswordNeeded bit 24531session->attributes.isPasswordNeeded = SET; 24532session->attributes.isAuthValueNeeded = CLEAR; 24533return TPM_RC_SUCCESS; 24534} 24535 24536Page 296 24537October 31, 2013 24538 24539Published 24540Copyright © TCG 2006-2013 24541 24542Family “2.0” 24543Level 00 Revision 00.99 24544 24545 Trusted Platform Module Library 24546 24547Part 3: Commands 24548 2454925.19 TPM2_PolicyGetDigest 2455025.19.1 24551 24552General Description 24553 24554This command returns the current policyDigest of the session. This command allows the TPM to be used 24555to perform the actions required to pre-compute the authPolicy for an object. 24556 24557Family “2.0” 24558Level 00 Revision 00.99 24559 24560Published 24561Copyright © TCG 2006-2013 24562 24563Page 297 24564October 31, 2013 24565 24566 Part 3: Commands 24567 2456825.19.2 24569 24570Trusted Platform Module Library 24571 24572Command and Response 24573Table 145 — TPM2_PolicyGetDigest Command 24574 24575Type 24576 24577Name 24578 24579Description 24580 24581TPMI_ST_COMMAND_TAG 24582 24583tag 24584 24585UINT32 24586 24587commandSize 24588 24589TPM_CC 24590 24591commandCode 24592 24593TPM_CC_PolicyGetDigest 24594 24595TPMI_SH_POLICY 24596 24597policySession 24598 24599handle for the policy session 24600Auth Index: None 24601 24602Table 146 — TPM2_PolicyGetDigest Response 24603Type 24604 24605Name 24606 24607Description 24608 24609TPM_ST 24610 24611tag 24612 24613see clause 8 24614 24615UINT32 24616 24617responseSize 24618 24619TPM_RC 24620 24621responseCode 24622 24623TPM2B_DIGEST 24624 24625policyDigest 24626 24627Page 298 24628October 31, 2013 24629 24630the current value of the policySession→policyDigest 24631 24632Published 24633Copyright © TCG 2006-2013 24634 24635Family “2.0” 24636Level 00 Revision 00.99 24637 24638 Trusted Platform Module Library 24639 2464025.19.3 246411 246422 246433 246444 246455 246466 246477 246488 246499 2465010 2465111 2465212 2465313 2465414 2465515 2465616 2465717 2465818 2465919 24660 24661Part 3: Commands 24662 24663Detailed Actions 24664 24665#include "InternalRoutines.h" 24666#include "PolicyGetDigest_fp.h" 24667 24668TPM_RC 24669TPM2_PolicyGetDigest( 24670PolicyGetDigest_In 24671PolicyGetDigest_Out 24672 24673*in, 24674*out 24675 24676// IN: input parameter list 24677// OUT: output parameter list 24678 24679) 24680{ 24681SESSION 24682 24683*session; 24684 24685// Command Output 24686// Get pointer to the session structure 24687session = SessionGet(in->policySession); 24688out->policyDigest = session->u2.policyDigest; 24689return TPM_RC_SUCCESS; 24690} 24691 24692Family “2.0” 24693Level 00 Revision 00.99 24694 24695Published 24696Copyright © TCG 2006-2013 24697 24698Page 299 24699October 31, 2013 24700 24701 Part 3: Commands 24702 24703Trusted Platform Module Library 24704 2470525.20 TPM2_PolicyNvWritten 2470625.20.1 24707 24708General Description 24709 24710This command allows a policy to be bound to the TPMA_NV_WRITTEN attributes. This is a deferred 24711assertion. Values are stored in the policy session context and checked when the policy is used for 24712authorization. 24713If policySession→checkNVWritten is CLEAR, it is SET and policySession→nvWrittenState is set to 24714writtenSet. 24715If policySession→checkNVWritten is SET, the TPM will return TPM_RC_VALUE if 24716policySession→nvWrittenState and writtenSet are not the same. 24717If the TPM does not return and error, it will update policySession→policyDigest by 24718 24719policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyNvWritten || writtenSet) 24720 24721(38) 24722 24723When the policy session is used to authorize a command, the TPM will fail the command if 24724policySession→checkNVWritten is SET and nvIndex→attributes→TPMA_NV_WRITTEN does not match 24725policySession→nvWrittenState. 24726NOTE 24727 24728A typical use case is a simple policy for the first write during manufacturing provisioning that would 24729require TPMA_NV_WRITTEN CLEAR and a more complex policy for later use that would require 24730TPMA_NV_WRITTEN SET. 24731 24732Page 300 24733October 31, 2013 24734 24735Published 24736Copyright © TCG 2006-2013 24737 24738Family “2.0” 24739Level 00 Revision 00.99 24740 24741 Trusted Platform Module Library 24742 2474325.20.2 24744 24745Part 3: Commands 24746 24747Command and Response 24748Table 147 — TPM2_PolicyNvWritten Command 24749 24750Type 24751 24752Name 24753 24754Description 24755 24756TPMI_ST_COMMAND_TAG 24757 24758Tag 24759 24760UINT32 24761 24762commandSize 24763 24764TPM_CC 24765 24766commandCode 24767 24768TPM_CC_PolicyNVWritten 24769 24770TPMI_SH_POLICY 24771 24772policySession 24773 24774handle for the policy session being extended 24775Auth Index: None 24776 24777TPMI_YES_NO 24778 24779writtenSet 24780 24781YES if NV Index is required to have been written 24782NO if NV Index is required not to have been written 24783 24784Table 148 — TPM2_PolicyNvWritten Response 24785Type 24786 24787Name 24788 24789Description 24790 24791TPM_ST 24792 24793Tag 24794 24795see clause 8 24796 24797UINT32 24798 24799responseSize 24800 24801TPM_RC 24802 24803responseCode 24804 24805Family “2.0” 24806Level 00 Revision 00.99 24807 24808Published 24809Copyright © TCG 2006-2013 24810 24811Page 301 24812October 31, 2013 24813 24814 Part 3: Commands 24815 2481625.20.3 248171 248182 24819 24820Trusted Platform Module Library 24821 24822Detailed Actions 24823 24824#include "InternalRoutines.h" 24825#include "PolicyNvWritten_fp.h" 24826 24827Make an NV Index policy dependent on the state of the TPMA_NV_WRITTEN attribute of the index. 24828Error Returns 24829TPM_RC_VALUE 248303 248314 248325 248336 248347 248358 248369 2483710 2483811 2483912 2484013 2484114 2484215 2484316 2484417 2484518 2484619 2484720 2484821 2484922 2485023 2485124 2485225 2485326 2485427 2485528 2485629 2485730 2485831 2485932 2486033 2486134 2486235 2486336 2486437 2486538 2486639 2486740 2486841 2486942 2487043 2487144 2487245 2487346 2487447 2487548 2487649 2487750 2487851 2487952 24880 24881Meaning 24882a conflicting request for the attribute has already been processed 24883 24884TPM_RC 24885TPM2_PolicyNvWritten( 24886PolicyNvWritten_In 24887 24888*in 24889 24890// IN: input parameter list 24891 24892) 24893{ 24894SESSION 24895TPM_CC 24896HASH_STATE 24897 24898*session; 24899commandCode = TPM_CC_PolicyNvWritten; 24900hashState; 24901 24902// Input Validation 24903// Get pointer to the session structure 24904session = SessionGet(in->policySession); 24905// If already set is this a duplicate (the same setting)? If it 24906// is a conflicting setting, it is an error 24907if(session->attributes.checkNvWritten == SET) 24908{ 24909if(( 24910(session->attributes.nvWrittenState == SET) 24911!= (in->writtenSet == YES))) 24912return TPM_RC_VALUE + RC_PolicyNvWritten_writtenSet; 24913} 24914// Internal Data Update 24915// Set session attributes so that the NV Index needs to be checked 24916session->attributes.checkNvWritten = SET; 24917session->attributes.nvWrittenState = (in->writtenSet == YES); 24918// Update policy hash 24919// policyDigestnew = hash(policyDigestold || TPM_CC_PolicyNvWritten 24920// 24921|| writtenSet) 24922// Start hash 24923CryptStartHash(session->authHashAlg, &hashState); 24924// add old digest 24925CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 24926// add commandCode 24927CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 24928// add the byte of writtenState 24929CryptUpdateDigestInt(&hashState, sizeof(TPMI_YES_NO), &in->writtenSet); 24930// complete the digest 24931CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 24932return TPM_RC_SUCCESS; 24933} 24934 24935Page 302 24936October 31, 2013 24937 24938Published 24939Copyright © TCG 2006-2013 24940 24941Family “2.0” 24942Level 00 Revision 00.99 24943 24944 Trusted Platform Module Library 24945 24946Family “2.0” 24947Level 00 Revision 00.99 24948 24949Part 3: Commands 24950 24951Published 24952Copyright © TCG 2006-2013 24953 24954Page 303 24955October 31, 2013 24956 24957 Part 3: Commands 24958 2495926 24960 24961Trusted Platform Module Library 24962 24963Hierarchy Commands 24964 2496526.1 24966 24967TPM2_CreatePrimary 24968 2496926.1.1 General Description 24970This command is used to create a Primary Object under one of the Primary Seeds or a Temporary Object 24971under TPM_RH_NULL. The command uses a TPM2B_PUBLIC as a template for the object to be created. 24972The command will create and load a Primary Object. The sensitive area is not returned. 24973NOTE: 24974 24975Since the sensitive data is not returned, the key cannot be reloaded. 24976persistent or it can be recreated. 24977 24978It can either be made 24979 24980Any type of object and attributes combination that is allowed by TPM2_Create() may be created by this 24981command. The constraints on templates and parameters are the same as TPM2_Create() except that a 24982Primary Storage Key and a Temporary Storage Key are not constrained to use the algorithms of their 24983parents. 24984For setting of the attributes of the created object, fixedParent, fixedTPM, userWithAuth, adminWithPolicy, 24985encrypt, and restricted are implied to be SET in the parent (a Permanent Handle). The remaining 24986attributes are implied to be CLEAR. 24987The TPM will derive the object from the Primary Seed indicated in primaryHandle using an approved 24988KDF. All of the bits of the template are used in the creation of the Primary Key. Methods for creating a 24989Primary Object from a Primary Seed are described in Part 1 of this specification and implemented in Part 249904. 24991If this command is called multiple times with the same inPublic parameter, inSensitive.data, and Primary 24992Seed, the TPM shall produce the same Primary Object. 24993NOTE 24994 24995If the Primary Seed is changed, the Primary Objects generated with the new seed shall be 24996statistically unique even if the parameters of the call are the same. 24997 24998This command requires authorization. Authorization for a Primary Object attached to the Platform Primary 24999Seed (PPS) shall be provided by platformAuth or platformPolicy. Authorization for a Primary Object 25000attached to the Storage Primary Seed (SPS) shall be provided by ownerAuth or ownerPolicy. 25001Authorization for a Primary Key attached to the Endorsement Primary Seed (EPS) shall be provided by 25002endorsementAuth or endorsementPolicy. 25003 25004Page 304 25005October 31, 2013 25006 25007Published 25008Copyright © TCG 2006-2013 25009 25010Family “2.0” 25011Level 00 Revision 00.99 25012 25013 Trusted Platform Module Library 25014 25015Part 3: Commands 25016 2501726.1.2 Command and Response 25018Table 149 — TPM2_CreatePrimary Command 25019Type 25020 25021Name 25022 25023Description 25024 25025TPMI_ST_COMMAND_TAG 25026 25027tag 25028 25029UINT32 25030 25031commandSize 25032 25033TPM_CC 25034 25035commandCode 25036 25037TPM_CC_CreatePrimary 25038 25039TPMI_RH_HIERARCHY+ 25040 25041@primaryHandle 25042 25043TPM_RH_ENDORSEMENT, TPM_RH_OWNER, 25044TPM_RH_PLATFORM+{PP}, or TPM_RH_NULL 25045Auth Index: 1 25046Auth Role: USER 25047 25048TPM2B_SENSITIVE_CREATE 25049 25050inSensitive 25051 25052the sensitive data, see Part 1 Sensitive Values 25053 25054TPM2B_PUBLIC 25055 25056inPublic 25057 25058the public template 25059 25060TPM2B_DATA 25061 25062outsideInfo 25063 25064data that will be included in the creation data for this 25065object to provide permanent, verifiable linkage between 25066this object and some object owner data 25067 25068TPML_PCR_SELECTION 25069 25070creationPCR 25071 25072PCR that will be used in creation data 25073 25074Table 150 — TPM2_CreatePrimary Response 25075Type 25076 25077Name 25078 25079Description 25080 25081TPM_ST 25082 25083tag 25084 25085see clause 8 25086 25087UINT32 25088 25089responseSize 25090 25091TPM_RC 25092 25093responseCode 25094 25095TPM_HANDLE 25096 25097objectHandle 25098 25099Handle for created Primary Object 25100 25101TPM2B_PUBLIC 25102 25103outPublic 25104 25105the public portion of the created object 25106 25107TPM2B_CREATION_DATA 25108 25109creationData 25110 25111contains a TPMT_CREATION_DATA 25112 25113TPM2B_DIGEST 25114 25115creationHash 25116 25117digest of creationData using nameAlg of outPublic 25118 25119TPMT_TK_CREATION 25120 25121creationTicket 25122 25123ticket used by TPM2_CertifyCreation() to validate that 25124the creation data was produced by the TPM 25125 25126TPM2B_NAME 25127 25128name 25129 25130the name of the created object 25131 25132Family “2.0” 25133Level 00 Revision 00.99 25134 25135Published 25136Copyright © TCG 2006-2013 25137 25138Page 305 25139October 31, 2013 25140 25141 Part 3: Commands 25142 25143Trusted Platform Module Library 25144 2514526.1.3 Detailed Actions 251461 251472 251483 251494 25150 25151#include 25152#include 25153#include 25154#include 25155 25156"InternalRoutines.h" 25157"CreatePrimary_fp.h" 25158"Object_spt_fp.h" 25159<Platform.h> 25160 25161Error Returns 25162TPM_RC_ATTRIBUTES 25163 25164sensitiveDataOrigin is CLEAR when 'sensitive. data' is an Empty 25165Buffer, or is SET when 'sensitive. data' is not empty; fixedTPM, 25166fixedParent, or encryptedDuplication attributes are inconsistent 25167between themselves or with those of the parent object; inconsistent 25168restricted, decrypt and sign attributes; attempt to inject sensitive data 25169for an asymmetric key; attempt to create a symmetric cipher key that 25170is not a decryption key 25171 25172TPM_RC_KDF 25173 25174incorrect KDF specified for decrypting keyed hash object 25175 25176TPM_RC_OBJECT_MEMORY 25177 25178there is no free slot for the object 25179 25180TPM_RC_SCHEME 25181 25182inconsistent attributes decrypt, sign, restricted and key's scheme ID; 25183or hash algorithm is inconsistent with the scheme ID for keyed hash 25184object 25185 25186TPM_RC_SIZE 25187 25188size of public auth policy or sensitive auth value does not match 25189digest size of the name algorithm sensitive data size for the keyed 25190hash object is larger than is allowed for the scheme 25191 25192TPM_RC_SYMMETRIC 25193 25194a storage key with no symmetric algorithm specified; or non-storage 25195key with symmetric algorithm different from TPM_ALG_NULL 25196 25197TPM_RC_TYPE 251985 251996 252007 252018 252029 2520310 2520411 2520512 2520613 2520714 2520815 2520916 2521017 2521118 2521219 2521320 2521421 2521522 2521623 2521724 2521825 2521926 2522027 2522128 2522229 2522330 2522431 2522532 2522633 25227 25228Meaning 25229 25230unknown object type; 25231 25232TPM_RC 25233TPM2_CreatePrimary( 25234CreatePrimary_In 25235CreatePrimary_Out 25236) 25237{ 25238// Local variables 25239TPM_RC 25240TPMT_SENSITIVE 25241 25242*in, 25243*out 25244 25245// IN: input parameter list 25246// OUT: output parameter list 25247 25248result = TPM_RC_SUCCESS; 25249sensitive; 25250 25251// Input Validation 25252// The sensitiveDataOrigin attribute must be consistent with the setting of 25253// the size of the data object in inSensitive. 25254if( 25255(in->inPublic.t.publicArea.objectAttributes.sensitiveDataOrigin == SET) 25256!= (in->inSensitive.t.sensitive.data.t.size == 0 )) 25257// Mismatch between the object attributes and the parameter. 25258return TPM_RC_ATTRIBUTES + RC_CreatePrimary_inSensitive; 25259// Check attributes in input public area. TPM_RC_ATTRIBUTES, TPM_RC_KDF, 25260// TPM_RC_SCHEME, TPM_RC_SIZE, TPM_RC_SYMMETRIC, or TPM_RC_TYPE error may 25261// be returned at this point. 25262result = PublicAttributesValidation(FALSE, in->primaryHandle, 25263&in->inPublic.t.publicArea); 25264if(result != TPM_RC_SUCCESS) 25265return RcSafeAddToResult(result, RC_CreatePrimary_inPublic); 25266// Validate the sensitive area values 25267if( MemoryRemoveTrailingZeros(&in->inSensitive.t.sensitive.userAuth) 25268> CryptGetHashDigestSize(in->inPublic.t.publicArea.nameAlg)) 25269 25270Page 306 25271October 31, 2013 25272 25273Published 25274Copyright © TCG 2006-2013 25275 25276Family “2.0” 25277Level 00 Revision 00.99 25278 25279 Trusted Platform Module Library 2528034 2528135 2528236 2528337 2528438 2528539 2528640 2528741 2528842 2528943 2529044 2529145 2529246 2529347 2529448 2529549 2529650 2529751 2529852 2529953 2530054 2530155 2530256 2530357 2530458 2530559 2530660 2530761 2530862 2530963 2531064 2531165 2531266 2531367 2531468 2531569 25316 25317Part 3: Commands 25318 25319return TPM_RC_SIZE + RC_CreatePrimary_inSensitive; 25320// Command output 25321// Generate Primary Object 25322// The primary key generation process uses the Name of the input public 25323// template to compute the key. The keys are generated from the template 25324// before anything in the template is allowed to be changed. 25325// A TPM_RC_KDF, TPM_RC_SIZE error may be returned at this point 25326result = CryptCreateObject(in->primaryHandle, &in->inPublic.t.publicArea, 25327&in->inSensitive.t.sensitive,&sensitive); 25328if(result != TPM_RC_SUCCESS) 25329return result; 25330// Fill in creation data 25331FillInCreationData(in->primaryHandle, in->inPublic.t.publicArea.nameAlg, 25332&in->creationPCR, &in->outsideInfo, &out->creationData, 25333&out->creationHash); 25334// Copy public area 25335out->outPublic = in->inPublic; 25336// Fill in private area for output 25337ObjectComputeName(&(out->outPublic.t.publicArea), &out->name); 25338// Compute creation ticket 25339TicketComputeCreation(EntityGetHierarchy(in->primaryHandle), &out->name, 25340&out->creationHash, &out->creationTicket); 25341// Create a internal object. A TPM_RC_OBJECT_MEMORY error may be returned 25342// at this point. 25343result = ObjectLoad(in->primaryHandle, &in->inPublic.t.publicArea, &sensitive, 25344&out->name, in->primaryHandle, TRUE, &out->objectHandle); 25345return result; 25346} 25347 25348Family “2.0” 25349Level 00 Revision 00.99 25350 25351Published 25352Copyright © TCG 2006-2013 25353 25354Page 307 25355October 31, 2013 25356 25357 Part 3: Commands 25358 2535926.2 25360 25361Trusted Platform Module Library 25362 25363TPM2_HierarchyControl 25364 2536526.2.1 General Description 25366This command enables and disables use of a hierarchy and its associated NV storage. The command 25367allows phEnable, phEnableNV, shEnable, and ehEnable to be changed when the proper authorization is 25368provided. 25369This command may be used to CLEAR phEnable and phEnableNV if platformAuth/platformPolicy is 25370provided. phEnable may not be SET using this command. 25371This command may be used to CLEAR shEnable if either platformAuth/platformPolicy 25372ownerAuth/ownerPolicy is provided. shEnable may be SET if platformAuth/platformPolicy is provided. 25373 25374or 25375 25376This command may be used to CLEAR ehEnable if either platformAuth/platformPolicy or 25377endorsementAuth/endorsementPolicy is provided. ehEnable may be SET if platformAuth/platformPolicy is 25378provided. 25379When this command is used to CLEAR phEnable, shEnable, or ehEnable, the TPM will disable use of 25380any persistent entity associated with the disabled hierarchy and will flush any transient objects associated 25381with the disabled hierarchy. 25382When this command is used to CLEAR shEnable, the TPM will disable access to any NV index that has 25383TPMA_NV_PLATFORMCREATE CLEAR (indicating that the NV Index was defined using ownerAuth). As 25384long as shEnable is CLEAR, the TPM will return an error in response to any command that attempts to 25385operate upon an NV index that has TPMA_NV_PLATFORMCREATE CLEAR. 25386When this command is used to CLEAR phEnableNV, the TPM will disable access to any NV index that 25387has TPMA_NV_PLATFORMCREATE SET (indicating that the NV Index was defined using platformAuth). 25388As long as phEnableNV is CLEAR, the TPM will return an error in response to any command that 25389attempts to operate upon an NV index that has TPMA_NV_PLATFORMCREATE SET. 25390 25391Page 308 25392October 31, 2013 25393 25394Published 25395Copyright © TCG 2006-2013 25396 25397Family “2.0” 25398Level 00 Revision 00.99 25399 25400 Trusted Platform Module Library 25401 25402Part 3: Commands 25403 2540426.2.2 Command and Response 25405Table 151 — TPM2_HierarchyControl Command 25406Type 25407 25408Name 25409 25410Description 25411 25412TPMI_ST_COMMAND_TAG 25413 25414tag 25415 25416UINT32 25417 25418commandSize 25419 25420TPM_CC 25421 25422commandCode 25423 25424TPM_CC_HierarchyControl {NV E} 25425 25426TPMI_RH_HIERARCHY 25427 25428@authHandle 25429 25430TPM_RH_ENDORSEMENT, TPM_RH_OWNER or 25431TPM_RH_PLATFORM+{PP} 25432Auth Index: 1 25433Auth Role: USER 25434 25435TPMI_RH_ENABLES 25436 25437enable 25438 25439the enable being modified 25440TPM_RH_ENDORSEMENT, TPM_RH_OWNER, 25441TPM_RH_PLATFORM, or TPM_RH_PLATFORM_NV 25442 25443TPMI_YES_NO 25444 25445state 25446 25447YES if the enable should be SET, NO if the enable 25448should be CLEAR 25449 25450Table 152 — TPM2_HierarchyControl Response 25451Type 25452 25453Name 25454 25455Description 25456 25457TPM_ST 25458 25459tag 25460 25461see clause 8 25462 25463UINT32 25464 25465responseSize 25466 25467TPM_RC 25468 25469responseCode 25470 25471Family “2.0” 25472Level 00 Revision 00.99 25473 25474Published 25475Copyright © TCG 2006-2013 25476 25477Page 309 25478October 31, 2013 25479 25480 Part 3: Commands 25481 25482Trusted Platform Module Library 25483 2548426.2.3 Detailed Actions 254851 254862 25487 25488#include "InternalRoutines.h" 25489#include "HierarchyControl_fp.h" 25490Error Returns 25491TPM_RC_AUTH_TYPE 25492 254933 254944 254955 254966 254977 254988 254999 2550010 2550111 2550212 2550313 2550414 2550515 2550616 2550717 2550818 2550919 2551020 2551121 2551222 2551323 2551424 2551525 2551626 2551727 2551828 2551929 2552030 2552131 2552232 2552333 2552434 2552535 2552636 2552737 2552838 2552939 2553040 2553141 2553242 2553343 2553444 2553545 2553646 2553747 2553848 2553949 2554050 2554151 2554252 2554353 2554454 25545 25546Meaning 25547authHandle is not applicable to hierarchy in its current state 25548 25549TPM_RC 25550TPM2_HierarchyControl( 25551HierarchyControl_In 25552 25553*in 25554 25555// IN: input parameter list 25556 25557) 25558{ 25559TPM_RC 25560BOOL 25561BOOL 25562 25563result; 25564select = (in->state == YES); 25565*selected = NULL; 25566 25567// Input Validation 25568switch(in->enable) 25569{ 25570// Platform hierarchy has to be disabled by platform auth 25571// If the platform hierarchy has already been disabled, only a reboot 25572// can enable it again 25573case TPM_RH_PLATFORM: 25574case TPM_RH_PLATFORM_NV: 25575if(in->authHandle != TPM_RH_PLATFORM) 25576return TPM_RC_AUTH_TYPE; 25577break; 25578// ShEnable may be disabled if PlatformAuth/PlatformPolicy or 25579// OwnerAuth/OwnerPolicy is provided. If ShEnable is disabled, then it 25580// may only be enabled if PlatformAuth/PlatformPolicy is provided. 25581case TPM_RH_OWNER: 25582if( 25583in->authHandle != TPM_RH_PLATFORM 25584&& in->authHandle != TPM_RH_OWNER) 25585return TPM_RC_AUTH_TYPE; 25586if( 25587gc.shEnable == FALSE && in->state == YES 25588&& in->authHandle != TPM_RH_PLATFORM) 25589return TPM_RC_AUTH_TYPE; 25590break; 25591// EhEnable may be disabled if either PlatformAuth/PlatformPolicy or 25592// EndosementAuth/EndorsementPolicy is provided. If EhEnable is disabled, 25593// then it may only be enabled if PlatformAuth/PlatformPolicy is 25594// provided. 25595case TPM_RH_ENDORSEMENT: 25596if( 25597in->authHandle != TPM_RH_PLATFORM 25598&& in->authHandle != TPM_RH_ENDORSEMENT) 25599return TPM_RC_AUTH_TYPE; 25600if( 25601gc.ehEnable == FALSE && in->state == YES 25602&& in->authHandle != TPM_RH_PLATFORM) 25603return TPM_RC_AUTH_TYPE; 25604break; 25605default: 25606pAssert(FALSE); 25607break; 25608} 25609// Internal Data Update 25610 25611Page 310 25612October 31, 2013 25613 25614Published 25615Copyright © TCG 2006-2013 25616 25617Family “2.0” 25618Level 00 Revision 00.99 25619 25620 Trusted Platform Module Library 2562155 2562256 2562357 2562458 2562559 2562660 2562761 2562862 2562963 2563064 2563165 2563266 2563367 2563468 2563569 2563670 2563771 2563872 2563973 2564074 2564175 2564276 2564377 2564478 2564579 2564680 2564781 2564882 2564983 2565084 2565185 2565286 2565387 2565488 2565589 2565690 2565791 2565892 2565993 2566094 2566195 2566296 2566397 2566498 2566599 25666100 25667101 25668102 25669103 25670104 25671105 25672106 25673107 25674 25675Part 3: Commands 25676 25677// Enable or disable the selected hierarchy 25678// Note: the authorization processing for this command may keep these 25679// command actions from being executed. For example, if phEnable is 25680// CLEAR, then platformAuth cannot be used for authorization. This 25681// means that would not be possible to use platformAuth to change the 25682// state of phEnable from CLEAR to SET. 25683// If it is decided that platformPolicy can still be used when phEnable 25684// is CLEAR, then this code could SET phEnable when proper platform 25685// policy is provided. 25686switch(in->enable) 25687{ 25688case TPM_RH_OWNER: 25689selected = &gc.shEnable; 25690break; 25691case TPM_RH_ENDORSEMENT: 25692selected = &gc.ehEnable; 25693break; 25694case TPM_RH_PLATFORM: 25695selected = &g_phEnable; 25696break; 25697case TPM_RH_PLATFORM_NV: 25698selected = &gc.phEnableNV; 25699break; 25700default: 25701pAssert(FALSE); 25702break; 25703} 25704if(selected != NULL && *selected != select) 25705{ 25706// Before changing the internal state, make sure that NV is available. 25707// Only need to update NV if changing the orderly state 25708if(gp.orderlyState != SHUTDOWN_NONE) 25709{ 25710// The command needs NV update. Check if NV is available. 25711// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 25712// this point 25713result = NvIsAvailable(); 25714if(result != TPM_RC_SUCCESS) 25715return result; 25716} 25717// state is changing and NV is available so modify 25718*selected = select; 25719// If a hierarchy was just disabled, flush it 25720if(select == CLEAR && in->enable != TPM_RH_PLATFORM_NV) 25721// Flush hierarchy 25722ObjectFlushHierarchy(in->enable); 25723// orderly state should be cleared because of the update to state clear data 25724// This gets processed in ExecuteCommand() on the way out. 25725g_clearOrderly = TRUE; 25726} 25727return TPM_RC_SUCCESS; 25728} 25729 25730Family “2.0” 25731Level 00 Revision 00.99 25732 25733Published 25734Copyright © TCG 2006-2013 25735 25736Page 311 25737October 31, 2013 25738 25739 Part 3: Commands 25740 2574126.3 25742 25743Trusted Platform Module Library 25744 25745TPM2_SetPrimaryPolicy 25746 2574726.3.1 General Description 25748This command allows setting of the authorization policy for the platform hierarchy (platformPolicy), the 25749storage hierarchy (ownerPolicy), and the endorsement hierarchy (endorsementPolicy). 25750The command requires an authorization session. The session shall use the current authValue or satisfy 25751the current authPolicy for the referenced hierarchy. 25752The policy that is changed is the policy associated with authHandle. 25753If the enable associated with authHandle is not SET, then the associated authorization values (authValue 25754or authPolicy) may not be used. 25755 25756Page 312 25757October 31, 2013 25758 25759Published 25760Copyright © TCG 2006-2013 25761 25762Family “2.0” 25763Level 00 Revision 00.99 25764 25765 Trusted Platform Module Library 25766 25767Part 3: Commands 25768 2576926.3.2 Command and Response 25770Table 153 — TPM2_SetPrimaryPolicy Command 25771Type 25772 25773Name 25774 25775Description 25776 25777TPMI_ST_COMMAND_TAG 25778 25779tag 25780 25781UINT32 25782 25783commandSize 25784 25785TPM_CC 25786 25787commandCode 25788 25789TPM_CC_SetPrimaryPolicy {NV} 25790 25791TPMI_RH_HIERARCHY 25792 25793@authHandle 25794 25795TPM_RH_ENDORSEMENT, TPM_RH_OWNER or 25796TPM_RH_PLATFORM+{PP} 25797Auth Index: 1 25798Auth Role: USER 25799 25800TPM2B_DIGEST 25801 25802authPolicy 25803 25804an authorization policy digest; may be the Empty Buffer 25805If hashAlg is TPM_ALG_NULL, then this shall be an 25806Empty Buffer. 25807 25808TPMI_ALG_HASH+ 25809 25810hashAlg 25811 25812the hash algorithm to use for the policy 25813If the authPolicy is an Empty Buffer, then this field shall 25814be TPM_ALG_NULL. 25815 25816Table 154 — TPM2_SetPrimaryPolicy Response 25817Type 25818 25819Name 25820 25821Description 25822 25823TPM_ST 25824 25825tag 25826 25827see clause 8 25828 25829UINT32 25830 25831responseSize 25832 25833TPM_RC 25834 25835responseCode 25836 25837Family “2.0” 25838Level 00 Revision 00.99 25839 25840Published 25841Copyright © TCG 2006-2013 25842 25843Page 313 25844October 31, 2013 25845 25846 Part 3: Commands 25847 25848Trusted Platform Module Library 25849 2585026.3.3 Detailed Actions 258511 258522 25853 25854#include "InternalRoutines.h" 25855#include "SetPrimaryPolicy_fp.h" 25856Error Returns 25857TPM_RC_SIZE 25858 258593 258604 258615 258626 258637 258648 258659 2586610 2586711 2586812 2586913 2587014 2587115 2587216 2587317 2587418 2587519 2587620 2587721 2587822 2587923 2588024 2588125 2588226 2588327 2588428 2588529 2588630 2588731 2588832 2588933 2589034 2589135 2589236 2589337 2589438 2589539 2589640 2589741 2589842 2589943 2590044 2590145 2590246 2590347 2590448 2590549 2590650 2590751 2590852 2590953 2591054 25911 25912Meaning 25913size of input authPolicy is not consistent with input hash algorithm 25914 25915TPM_RC 25916TPM2_SetPrimaryPolicy( 25917SetPrimaryPolicy_In 25918 25919*in 25920 25921// IN: input parameter list 25922 25923) 25924{ 25925TPM_RC 25926 25927result; 25928 25929// Input Validation 25930// Check the authPolicy consistent with hash algorithm 25931if( 25932in->authPolicy.t.size != 0 25933&& in->authPolicy.t.size != CryptGetHashDigestSize(in->hashAlg)) 25934return TPM_RC_SIZE + RC_SetPrimaryPolicy_authPolicy; 25935// The command need NV update for OWNER and ENDORSEMENT hierarchy, and 25936// might need orderlyState update for PLATFROM hierarchy. 25937// Check if NV is available. A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE 25938// error may be returned at this point 25939result = NvIsAvailable(); 25940if(result != TPM_RC_SUCCESS) 25941return result; 25942// Internal Data Update 25943// Set hierarchy policy 25944switch(in->authHandle) 25945{ 25946case TPM_RH_OWNER: 25947gp.ownerAlg = in->hashAlg; 25948gp.ownerPolicy = in->authPolicy; 25949NvWriteReserved(NV_OWNER_ALG, &gp.ownerAlg); 25950NvWriteReserved(NV_OWNER_POLICY, &gp.ownerPolicy); 25951break; 25952case TPM_RH_ENDORSEMENT: 25953gp.endorsementAlg = in->hashAlg; 25954gp.endorsementPolicy = in->authPolicy; 25955NvWriteReserved(NV_ENDORSEMENT_ALG, &gp.endorsementAlg); 25956NvWriteReserved(NV_ENDORSEMENT_POLICY, &gp.endorsementPolicy); 25957break; 25958case TPM_RH_PLATFORM: 25959gc.platformAlg = in->hashAlg; 25960gc.platformPolicy = in->authPolicy; 25961// need to update orderly state 25962g_clearOrderly = TRUE; 25963break; 25964default: 25965pAssert(FALSE); 25966break; 25967} 25968return TPM_RC_SUCCESS; 25969} 25970 25971Page 314 25972October 31, 2013 25973 25974Published 25975Copyright © TCG 2006-2013 25976 25977Family “2.0” 25978Level 00 Revision 00.99 25979 25980 Trusted Platform Module Library 25981 2598226.4 25983 25984Part 3: Commands 25985 25986TPM2_ChangePPS 25987 2598826.4.1 General Description 25989This replaces the current PPS with a value from the RNG and sets platformPolicy to the default 25990initialization value (the Empty Buffer). 25991NOTE 1 25992 25993A policy that is the Empty Buffer can match no policy. 25994 25995NOTE 2 25996 25997platformAuth is not changed. 25998 25999All loaded transient and persistent objects in the Platform hierarchy are flushed. 26000Saved contexts in the Platform hierarchy that were created under the old PPS will no longer be able to be 26001loaded. 26002The policy hash algorithm for PCR is reset to TPM_ALG_NULL. 26003This command does not clear any NV Index values. 26004NOTE 3 26005 26006Index values belonging to the Platform are preserved because the indexes may have configuration 26007information that will be the same after the PPS changes. The Platform may remove the indexes that 26008are no longer needed using TPM2_NV_UndefineSpace(). 26009 26010This command requires platformAuth. 26011 26012Family “2.0” 26013Level 00 Revision 00.99 26014 26015Published 26016Copyright © TCG 2006-2013 26017 26018Page 315 26019October 31, 2013 26020 26021 Part 3: Commands 26022 26023Trusted Platform Module Library 26024 2602526.4.2 Command and Response 26026Table 155 — TPM2_ChangePPS Command 26027Type 26028 26029Name 26030 26031TPMI_ST_COMMAND_TAG 26032 26033tag 26034 26035UINT32 26036 26037commandSize 26038 26039TPM_CC 26040 26041commandCode 26042 26043TPM_CC_ChangePPS {NV E} 26044 26045@authHandle 26046 26047TPM_RH_PLATFORM+{PP} 26048Auth Index: 1 26049Auth Role: USER 26050 26051TPMI_RH_PLATFORM 26052 26053Description 26054 26055Table 156 — TPM2_ChangePPS Response 26056Type 26057 26058Name 26059 26060Description 26061 26062TPM_ST 26063 26064tag 26065 26066see clause 8 26067 26068UINT32 26069 26070responseSize 26071 26072TPM_RC 26073 26074responseCode 26075 26076Page 316 26077October 31, 2013 26078 26079Published 26080Copyright © TCG 2006-2013 26081 26082Family “2.0” 26083Level 00 Revision 00.99 26084 26085 Trusted Platform Module Library 26086 26087Part 3: Commands 26088 2608926.4.3 Detailed Actions 260901 260912 260923 260934 260945 260956 260967 260978 260989 2609910 2610011 2610112 2610213 2610314 2610415 2610516 2610617 2610718 2610819 2610920 2611021 2611122 2611223 2611324 2611425 2611526 2611627 2611728 2611829 2611930 2612031 2612132 2612233 2612334 2612435 2612536 2612637 2612738 2612839 2612940 2613041 2613142 2613243 2613344 2613445 2613546 2613647 2613748 2613849 2613950 2614051 2614152 2614253 2614354 26144 26145#include "InternalRoutines.h" 26146#include "ChangePPS_fp.h" 26147 26148TPM_RC 26149TPM2_ChangePPS( 26150ChangePPS_In 26151 26152*in 26153 26154// IN: input parameter list 26155 26156) 26157{ 26158UINT32 26159TPM_RC 26160 26161i; 26162result; 26163 26164// Check if NV is available. A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE 26165// error may be returned at this point 26166result = NvIsAvailable(); 26167if(result != TPM_RC_SUCCESS) return result; 26168// Input parameter is not reference in command action 26169in = NULL; 26170// Internal Data Update 26171// Reset platform hierarchy seed from RNG 26172CryptGenerateRandom(PRIMARY_SEED_SIZE, gp.PPSeed.t.buffer); 26173// Create a new phProof value from RNG to prevent the saved platform 26174// hierarchy contexts being loaded 26175CryptGenerateRandom(PROOF_SIZE, gp.phProof.t.buffer); 26176// Set platform authPolicy to null 26177gc.platformAlg = TPM_ALG_NULL; 26178gc.platformPolicy.t.size = 0; 26179// Flush loaded object in platform hierarchy 26180ObjectFlushHierarchy(TPM_RH_PLATFORM); 26181// Flush platform evict object and index in NV 26182NvFlushHierarchy(TPM_RH_PLATFORM); 26183// Save hierarchy changes to NV 26184NvWriteReserved(NV_PP_SEED, &gp.PPSeed); 26185NvWriteReserved(NV_PH_PROOF, &gp.phProof); 26186// Re-initialize PCR policies 26187for(i = 0; i < NUM_POLICY_PCR_GROUP; i++) 26188{ 26189gp.pcrPolicies.hashAlg[i] = TPM_ALG_NULL; 26190gp.pcrPolicies.policy[i].t.size = 0; 26191} 26192NvWriteReserved(NV_PCR_POLICIES, &gp.pcrPolicies); 26193// orderly state should be cleared because of the update to state clear data 26194g_clearOrderly = TRUE; 26195return TPM_RC_SUCCESS; 26196} 26197 26198Family “2.0” 26199Level 00 Revision 00.99 26200 26201Published 26202Copyright © TCG 2006-2013 26203 26204Page 317 26205October 31, 2013 26206 26207 Part 3: Commands 26208 2620926.5 26210 26211Trusted Platform Module Library 26212 26213TPM2_ChangeEPS 26214 2621526.5.1 General Description 26216This replaces the current EPS with a value from the RNG and sets the Endorsement hierarchy controls to 26217their default initialization values: ehEnable is SET, endorsementAuth and endorsementPolicy both equal 26218to the Empty Buffer. It will flush any loaded objects in the EPS hierarchy and not allow objects in the 26219hierarchy associated with the previous EPS to be loaded. 26220NOTE 26221 26222In the reference implementation, ehProof is a non-volatile value from the RNG. It is allowed that the 26223ehProof be generated by a KDF using both the EPS and SPS as inputs. If generated with a KDF, the 26224ehProof can be generated on an as-needed basis or made a non-volatile value. 26225 26226This command requires platformAuth. 26227 26228Page 318 26229October 31, 2013 26230 26231Published 26232Copyright © TCG 2006-2013 26233 26234Family “2.0” 26235Level 00 Revision 00.99 26236 26237 Trusted Platform Module Library 26238 26239Part 3: Commands 26240 2624126.5.2 Command and Response 26242Table 157 — TPM2_ChangeEPS Command 26243Type 26244 26245Name 26246 26247TPMI_ST_COMMAND_TAG 26248 26249tag 26250 26251UINT32 26252 26253commandSize 26254 26255TPM_CC 26256 26257commandCode 26258 26259TPM_CC_ChangeEPS {NV E} 26260 26261@authHandle 26262 26263TPM_RH_PLATFORM+{PP} 26264Auth Handle: 1 26265Auth Role: USER 26266 26267TPMI_RH_PLATFORM 26268 26269Description 26270 26271Table 158 — TPM2_ChangeEPS Response 26272Type 26273 26274Name 26275 26276Description 26277 26278TPM_ST 26279 26280tag 26281 26282see clause 8 26283 26284UINT32 26285 26286responseSize 26287 26288TPM_RC 26289 26290responseCode 26291 26292Family “2.0” 26293Level 00 Revision 00.99 26294 26295Published 26296Copyright © TCG 2006-2013 26297 26298Page 319 26299October 31, 2013 26300 26301 Part 3: Commands 26302 26303Trusted Platform Module Library 26304 2630526.5.3 Detailed Actions 263061 263072 263083 263094 263105 263116 263127 263138 263149 2631510 2631611 2631712 2631813 2631914 2632015 2632116 2632217 2632318 2632419 2632520 2632621 2632722 2632823 2632924 2633025 2633126 2633227 2633328 2633429 2633530 2633631 2633732 2633833 2633934 2634035 2634136 2634237 2634338 2634439 2634540 2634641 2634742 2634843 2634944 2635045 2635146 2635247 2635348 2635449 2635550 2635651 2635752 2635853 2635954 2636055 2636156 26362 26363#include "InternalRoutines.h" 26364#include "ChangeEPS_fp.h" 26365 26366TPM_RC 26367TPM2_ChangeEPS( 26368ChangeEPS_In 26369 26370*in 26371 26372// IN: input parameter list 26373 26374) 26375{ 26376TPM_RC 26377 26378result; 26379 26380// The command needs NV update. Check if NV is available. 26381// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 26382// this point 26383result = NvIsAvailable(); 26384if(result != TPM_RC_SUCCESS) return result; 26385// Input parameter is not reference in command action 26386in = NULL; 26387// Internal Data Update 26388// Reset endorsement hierarchy seed from RNG 26389CryptGenerateRandom(PRIMARY_SEED_SIZE, gp.EPSeed.t.buffer); 26390// Create new ehProof value from RNG 26391CryptGenerateRandom(PROOF_SIZE, gp.ehProof.t.buffer); 26392// Enable endorsement hierarchy 26393gc.ehEnable = TRUE; 26394// set authValue buffer to zeros 26395MemorySet(gp.endorsementAuth.t.buffer, 0, gp.endorsementAuth.t.size); 26396// Set endorsement authValue to null 26397gp.endorsementAuth.t.size = 0; 26398// Set endorsement authPolicy to null 26399gp.endorsementAlg = TPM_ALG_NULL; 26400gp.endorsementPolicy.t.size = 0; 26401// Flush loaded object in endorsement hierarchy 26402ObjectFlushHierarchy(TPM_RH_ENDORSEMENT); 26403// Flush evict object of endorsement hierarchy stored in NV 26404NvFlushHierarchy(TPM_RH_ENDORSEMENT); 26405// Save hierarchy changes to NV 26406NvWriteReserved(NV_EP_SEED, &gp.EPSeed); 26407NvWriteReserved(NV_EH_PROOF, &gp.ehProof); 26408NvWriteReserved(NV_ENDORSEMENT_AUTH, &gp.endorsementAuth); 26409NvWriteReserved(NV_ENDORSEMENT_ALG, &gp.endorsementAlg); 26410NvWriteReserved(NV_ENDORSEMENT_POLICY, &gp.endorsementPolicy); 26411// orderly state should be cleared because of the update to state clear data 26412g_clearOrderly = TRUE; 26413return TPM_RC_SUCCESS; 26414} 26415 26416Page 320 26417October 31, 2013 26418 26419Published 26420Copyright © TCG 2006-2013 26421 26422Family “2.0” 26423Level 00 Revision 00.99 26424 26425 Trusted Platform Module Library 26426 2642726.6 26428 26429Part 3: Commands 26430 26431TPM2_Clear 26432 2643326.6.1 General Description 26434This command removes all TPM context associated with a specific Owner. 26435The clear operation will: 26436 26437 26438flush loaded objects (persistent and volatile) in the Storage and Endorsement hierarchies; 26439 26440 26441 26442delete any NV Index with TPMA_NV_PLATFORMCREATE == CLEAR; 26443 26444 26445 26446change the SPS to a new value from the TPM’s random number generator (RNG), 26447 26448 26449 26450change shProof and ehProof, 26451NOTE 26452 26453The proof values may be set from the RNG or derived from the associated new Primary Seed. If 26454derived from the Primary Seeds, the derivation of ehProof shall use both the SPS and EPS. The 26455computation shall use the SPS as an HMAC key and the derived value may then be a parameter 26456in a second HMAC in which the EPS is the HMAC key. The reference design uses values from 26457the RNG. 26458 26459 26460 26461SET shEnable and ehEnable; 26462 26463 26464 26465set ownerAuth, endorsementAuth, and lockoutAuth to the Empty Buffer; 26466 26467 26468 26469set ownerPolicy and endorsementPolicy to the Empty Buffer; 26470 26471 26472 26473set Clock to zero; 26474 26475 26476 26477set resetCount to zero; 26478 26479 26480 26481set restartCount to zero; and 26482 26483 26484 26485set Safe to YES. 26486 26487This command requires platformAuth or lockoutAuth. If TPM2_ClearControl() has disabled this command, 26488the TPM shall return TPM_RC_DISABLED. 26489If this command is authorized using lockoutAuth, the HMAC in the response shall use the new 26490lockoutAuth value (that is, the Empty Buffer) when computing response HMAC. 26491 26492Family “2.0” 26493Level 00 Revision 00.99 26494 26495Published 26496Copyright © TCG 2006-2013 26497 26498Page 321 26499October 31, 2013 26500 26501 Part 3: Commands 26502 26503Trusted Platform Module Library 26504 2650526.6.2 Command and Response 26506Table 159 — TPM2_Clear Command 26507Type 26508 26509Name 26510 26511TPMI_ST_COMMAND_TAG 26512 26513tag 26514 26515UINT32 26516 26517commandSize 26518 26519TPM_CC 26520 26521commandCode 26522 26523TPM_CC_Clear {NV E} 26524 26525@authHandle 26526 26527TPM_RH_LOCKOUT or TPM_RH_PLATFORM+{PP} 26528Auth Handle: 1 26529Auth Role: USER 26530 26531TPMI_RH_CLEAR 26532 26533Description 26534 26535Table 160 — TPM2_Clear Response 26536Type 26537 26538Name 26539 26540Description 26541 26542TPM_ST 26543 26544tag 26545 26546see clause 8 26547 26548UINT32 26549 26550responseSize 26551 26552TPM_RC 26553 26554responseCode 26555 26556Page 322 26557October 31, 2013 26558 26559Published 26560Copyright © TCG 2006-2013 26561 26562Family “2.0” 26563Level 00 Revision 00.99 26564 26565 Trusted Platform Module Library 26566 26567Part 3: Commands 26568 2656926.6.3 Detailed Actions 265701 265712 26572 26573#include "InternalRoutines.h" 26574#include "Clear_fp.h" 26575Error Returns 26576TPM_RC_DISABLED 26577 265783 265794 265805 265816 265827 265838 265849 2658510 2658611 2658712 2658813 2658914 2659015 2659116 2659217 2659318 2659419 2659520 2659621 2659722 2659823 2659924 2660025 2660126 2660227 2660328 2660429 2660530 2660631 2660732 2660833 2660934 2661035 2661136 2661237 2661338 2661439 2661540 2661641 2661742 2661843 2661944 2662045 2662146 2662247 2662348 2662449 2662550 2662651 2662752 2662853 2662954 26630 26631Meaning 26632Clear command has been disabled 26633 26634TPM_RC 26635TPM2_Clear( 26636Clear_In 26637 26638*in 26639 26640// IN: input parameter list 26641 26642) 26643{ 26644TPM_RC 26645 26646result; 26647 26648// Input parameter is not reference in command action 26649in = NULL; 26650// The command needs NV update. Check if NV is available. 26651// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 26652// this point 26653result = NvIsAvailable(); 26654if(result != TPM_RC_SUCCESS) return result; 26655// Input Validation 26656// If Clear command is disabled, return an error 26657if(gp.disableClear) 26658return TPM_RC_DISABLED; 26659// Internal Data Update 26660// Reset storage hierarchy seed from RNG 26661CryptGenerateRandom(PRIMARY_SEED_SIZE, gp.SPSeed.t.buffer); 26662// Create new shProof and ehProof value from RNG 26663CryptGenerateRandom(PROOF_SIZE, gp.shProof.t.buffer); 26664CryptGenerateRandom(PROOF_SIZE, gp.ehProof.t.buffer); 26665// Enable storage and endorsement hierarchy 26666gc.shEnable = gc.ehEnable = TRUE; 26667// set the authValue buffers to zero 26668MemorySet(gp.ownerAuth.t.buffer, 0, gp.ownerAuth.t.size); 26669MemorySet(gp.endorsementAuth.t.buffer, 0, gp.endorsementAuth.t.size); 26670MemorySet(gp.lockoutAuth.t.buffer, 0, gp.lockoutAuth.t.size); 26671// Set storage, endorsement and lockout authValue to null 26672gp.ownerAuth.t.size = gp.endorsementAuth.t.size = gp.lockoutAuth.t.size = 0; 26673// Set storage and endorsement authPolicy to null 26674gp.ownerAlg = gp.endorsementAlg = TPM_ALG_NULL; 26675gp.ownerPolicy.t.size = gp.endorsementPolicy.t.size = 0; 26676// Flush loaded object in storage and endorsement hierarchy 26677ObjectFlushHierarchy(TPM_RH_OWNER); 26678ObjectFlushHierarchy(TPM_RH_ENDORSEMENT); 26679// Flush owner and endorsement object and owner index in NV 26680NvFlushHierarchy(TPM_RH_OWNER); 26681NvFlushHierarchy(TPM_RH_ENDORSEMENT); 26682 26683Family “2.0” 26684Level 00 Revision 00.99 26685 26686Published 26687Copyright © TCG 2006-2013 26688 26689Page 323 26690October 31, 2013 26691 26692 Part 3: Commands 2669355 2669456 2669557 2669658 2669759 2669860 2669961 2670062 2670163 2670264 2670365 2670466 2670567 2670668 2670769 2670870 2670971 2671072 2671173 2671274 2671375 2671476 2671577 2671678 2671779 2671880 2671981 2672082 2672183 2672284 2672385 2672486 2672587 2672688 26727 26728Trusted Platform Module Library 26729 26730// Save hierarchy changes to NV 26731NvWriteReserved(NV_SP_SEED, &gp.SPSeed); 26732NvWriteReserved(NV_SH_PROOF, &gp.shProof); 26733NvWriteReserved(NV_EH_PROOF, &gp.ehProof); 26734NvWriteReserved(NV_OWNER_AUTH, &gp.ownerAuth); 26735NvWriteReserved(NV_ENDORSEMENT_AUTH, &gp.endorsementAuth); 26736NvWriteReserved(NV_LOCKOUT_AUTH, &gp.lockoutAuth); 26737NvWriteReserved(NV_OWNER_ALG, &gp.ownerAlg); 26738NvWriteReserved(NV_ENDORSEMENT_ALG, &gp.endorsementAlg); 26739NvWriteReserved(NV_OWNER_POLICY, &gp.ownerPolicy); 26740NvWriteReserved(NV_ENDORSEMENT_POLICY, &gp.endorsementPolicy); 26741// Initialize dictionary attack parameters 26742DAPreInstall_Init(); 26743// Reset clock 26744go.clock = 0; 26745go.clockSafe = YES; 26746// Update the DRBG state whenever writing orderly state to NV 26747CryptDrbgGetPutState(GET_STATE); 26748NvWriteReserved(NV_ORDERLY_DATA, &go); 26749// Reset counters 26750gp.resetCount = gr.restartCount = gr.clearCount = 0; 26751gp.auditCounter = 0; 26752NvWriteReserved(NV_RESET_COUNT, &gp.resetCount); 26753NvWriteReserved(NV_AUDIT_COUNTER, &gp.auditCounter); 26754// orderly state should be cleared because of the update to state clear data 26755g_clearOrderly = TRUE; 26756return TPM_RC_SUCCESS; 26757} 26758 26759Page 324 26760October 31, 2013 26761 26762Published 26763Copyright © TCG 2006-2013 26764 26765Family “2.0” 26766Level 00 Revision 00.99 26767 26768 Trusted Platform Module Library 26769 2677026.7 26771 26772Part 3: Commands 26773 26774TPM2_ClearControl 26775 2677626.7.1 General Description 26777TPM2_ClearControl() disables and enables the execution of TPM2_Clear(). 26778The TPM will SET the TPM’s TPMA_PERMANENT.disableClear attribute if disable is YES and will 26779CLEAR the attribute if disable is NO. When the attribute is SET, TPM2_Clear() may not be executed. 26780NOTE 26781 26782This is to simplify the logic of TPM2_Clear(). TPM2_ClearControl() can be called using platformAuth 26783to CLEAR the disableClear attribute and then execute TPM2_Clear(). 26784 26785LockoutAuth may be used to SET disableClear but not to CLEAR it. 26786PlatformAuth may be used to SET or CLEAR disableClear. 26787 26788Family “2.0” 26789Level 00 Revision 00.99 26790 26791Published 26792Copyright © TCG 2006-2013 26793 26794Page 325 26795October 31, 2013 26796 26797 Part 3: Commands 26798 26799Trusted Platform Module Library 26800 2680126.7.2 Command and Response 26802Table 161 — TPM2_ClearControl Command 26803Type 26804 26805Name 26806 26807Description 26808 26809TPMI_ST_COMMAND_TAG 26810 26811tag 26812 26813UINT32 26814 26815commandSize 26816 26817TPM_CC 26818 26819commandCode 26820 26821TPM_CC_ClearControl {NV} 26822 26823TPMI_RH_CLEAR 26824 26825@auth 26826 26827TPM_RH_LOCKOUT or TPM_RH_PLATFORM+{PP} 26828Auth Handle: 1 26829Auth Role: USER 26830 26831TPMI_YES_NO 26832 26833disable 26834 26835YES if the disableOwnerClear flag is to be SET, NO if 26836the flag is to be CLEAR. 26837 26838Table 162 — TPM2_ClearControl Response 26839Type 26840 26841Name 26842 26843Description 26844 26845TPM_ST 26846 26847tag 26848 26849see clause 8 26850 26851UINT32 26852 26853responseSize 26854 26855TPM_RC 26856 26857responseCode 26858 26859Page 326 26860October 31, 2013 26861 26862Published 26863Copyright © TCG 2006-2013 26864 26865Family “2.0” 26866Level 00 Revision 00.99 26867 26868 Trusted Platform Module Library 26869 26870Part 3: Commands 26871 2687226.7.3 Detailed Actions 268731 268742 26875 26876#include "InternalRoutines.h" 26877#include "ClearControl_fp.h" 26878Error Returns 26879TPM_RC_AUTH_FAIL 26880 268813 268824 268835 268846 268857 268868 268879 2688810 2688911 2689012 2689113 2689214 2689315 2689416 2689517 2689618 2689719 2689820 2689921 2690022 2690123 2690224 2690325 2690426 2690527 2690628 2690729 2690830 2690931 2691032 2691133 26912 26913Meaning 26914authorization is not properly given 26915 26916TPM_RC 26917TPM2_ClearControl( 26918ClearControl_In 26919 26920*in 26921 26922// IN: input parameter list 26923 26924) 26925{ 26926TPM_RC 26927 26928result; 26929 26930// The command needs NV update. Check if NV is available. 26931// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 26932// this point 26933result = NvIsAvailable(); 26934if(result != TPM_RC_SUCCESS) return result; 26935// Input Validation 26936// LockoutAuth may be used to set disableLockoutClear to TRUE but not to FALSE 26937if(in->auth == TPM_RH_LOCKOUT && in->disable == NO) 26938return TPM_RC_AUTH_FAIL; 26939// Internal Data Update 26940if(in->disable == YES) 26941gp.disableClear = TRUE; 26942else 26943gp.disableClear = FALSE; 26944// Record the change to NV 26945NvWriteReserved(NV_DISABLE_CLEAR, &gp.disableClear); 26946return TPM_RC_SUCCESS; 26947} 26948 26949Family “2.0” 26950Level 00 Revision 00.99 26951 26952Published 26953Copyright © TCG 2006-2013 26954 26955Page 327 26956October 31, 2013 26957 26958 Part 3: Commands 26959 2696026.8 26961 26962Trusted Platform Module Library 26963 26964TPM2_HierarchyChangeAuth 26965 2696626.8.1 General Description 26967This command allows the authorization secret for a hierarchy or lockout to be changed using the current 26968authorization value as the command authorization. 26969If authHandle is TPM_RH_PLATFORM, then platformAuth is changed. If authHandle is 26970TPM_RH_OWNER, then ownerAuth is changed. If authHandle is TPM_RH_ENDORSEMENT, then 26971endorsementAuth is changed. If authHandle is TPM_RH_LOCKOUT, then lockoutAuth is changed. 26972If authHandle is TPM_RH_PLATFORM, then Physical Presence may need to be asserted for this 26973command to succeed (see 28.2, “TPM2_PP_Commands”). 26974The authorization value may be no larger than the digest produced by the hash algorithm used for context 26975integrity. 26976EXAMPLE 26977 26978If SHA384 is used in the computation of the integrity values for saved contexts, then the largest 26979authorization value is 48 octets. 26980 26981Page 328 26982October 31, 2013 26983 26984Published 26985Copyright © TCG 2006-2013 26986 26987Family “2.0” 26988Level 00 Revision 00.99 26989 26990 Trusted Platform Module Library 26991 26992Part 3: Commands 26993 2699426.8.2 Command and Response 26995Table 163 — TPM2_HierarchyChangeAuth Command 26996Type 26997 26998Name 26999 27000Description 27001 27002TPMI_ST_COMMAND_TAG 27003 27004tag 27005 27006UINT32 27007 27008commandSize 27009 27010TPM_CC 27011 27012commandCode 27013 27014TPM_CC_HierarchyChangeAuth {NV} 27015 27016TPMI_RH_HIERARCHY_AUTH 27017 27018@authHandle 27019 27020TPM_RH_LOCKOUT, TPM_RH_ENDORSEMENT, 27021TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 27022Auth Index: 1 27023Auth Role: USER 27024 27025TPM2B_AUTH 27026 27027newAuth 27028 27029new authorization value 27030 27031Table 164 — TPM2_HierarchyChangeAuth Response 27032Type 27033 27034Name 27035 27036Description 27037 27038TPM_ST 27039 27040tag 27041 27042see clause 8 27043 27044UINT32 27045 27046responseSize 27047 27048TPM_RC 27049 27050responseCode 27051 27052Family “2.0” 27053Level 00 Revision 00.99 27054 27055Published 27056Copyright © TCG 2006-2013 27057 27058Page 329 27059October 31, 2013 27060 27061 Part 3: Commands 27062 27063Trusted Platform Module Library 27064 2706526.8.3 Detailed Actions 270661 270672 270683 27069 27070#include "InternalRoutines.h" 27071#include "HierarchyChangeAuth_fp.h" 27072#include "Object_spt_fp.h" 27073Error Returns 27074TPM_RC_SIZE 27075 270764 270775 270786 270797 270808 270819 2708210 2708311 2708412 2708513 2708614 2708715 2708816 2708917 2709018 2709119 2709220 2709321 2709422 2709523 2709624 2709725 2709826 2709927 2710028 2710129 2710230 2710331 2710432 2710533 2710634 2710735 2710836 2710937 2711038 2711139 2711240 2711341 2711442 2711543 2711644 2711745 2711846 2711947 2712048 2712149 2712250 2712351 27124 27125Meaning 27126newAuth size is greater than that of integrity hash digest 27127 27128TPM_RC 27129TPM2_HierarchyChangeAuth( 27130HierarchyChangeAuth_In 27131 27132*in 27133 27134// IN: input parameter list 27135 27136) 27137{ 27138TPM_RC 27139 27140result; 27141 27142// The command needs NV update. Check if NV is available. 27143// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 27144// this point 27145result = NvIsAvailable(); 27146if(result != TPM_RC_SUCCESS) return result; 27147// Make sure the the auth value is a reasonable size (not larger than 27148// the size of the digest produced by the integrity hash. The integrity 27149// hash is assumed to produce the longest digest of any hash implemented 27150// on the TPM. 27151if( MemoryRemoveTrailingZeros(&in->newAuth) 27152> CryptGetHashDigestSize(CONTEXT_INTEGRITY_HASH_ALG)) 27153return TPM_RC_SIZE + RC_HierarchyChangeAuth_newAuth; 27154// Set hierarchy authValue 27155switch(in->authHandle) 27156{ 27157case TPM_RH_OWNER: 27158gp.ownerAuth = in->newAuth; 27159NvWriteReserved(NV_OWNER_AUTH, &gp.ownerAuth); 27160break; 27161case TPM_RH_ENDORSEMENT: 27162gp.endorsementAuth = in->newAuth; 27163NvWriteReserved(NV_ENDORSEMENT_AUTH, &gp.endorsementAuth); 27164break; 27165case TPM_RH_PLATFORM: 27166gc.platformAuth = in->newAuth; 27167// orderly state should be cleared 27168g_clearOrderly = TRUE; 27169break; 27170case TPM_RH_LOCKOUT: 27171gp.lockoutAuth = in->newAuth; 27172NvWriteReserved(NV_LOCKOUT_AUTH, &gp.lockoutAuth); 27173break; 27174default: 27175pAssert(FALSE); 27176break; 27177} 27178return TPM_RC_SUCCESS; 27179} 27180 27181Page 330 27182October 31, 2013 27183 27184Published 27185Copyright © TCG 2006-2013 27186 27187Family “2.0” 27188Level 00 Revision 00.99 27189 27190 Trusted Platform Module Library 27191 2719227 27193 27194Part 3: Commands 27195 27196Dictionary Attack Functions 27197 2719827.1 27199 27200Introduction 27201 27202A TPM is required to have support for logic that will help prevent a dictionary attack on an authorization 27203value. The protection is provided by a counter that increments when a password authorization or an 27204HMAC authorization fails. When the counter reaches a predefined value, the TPM will not accept, for 27205some time interval, further requests that require authorization and the TPM is in Lockout mode. While the 27206TPM is in Lockout mode, the TPM will return TPM_RC_LOCKED if the command requires use of an 27207object’s or Index’s authValue unless the authorization applies to an entry in the Platform hierarchy. 27208NOTE 27209 27210Authorizations for objects and NV Index values in the Platform hierarchy are never locked out. 27211However, a command that requires multiple authorizations will not be accepted when the TPM is in 27212Lockout mode unless all of the authorizations reference objects and indexes in the Platform 27213hierarchy. 27214 27215If the TPM is continuously powered for the duration of newRecoveryTime and no authorization failures 27216occur, the authorization failure counter will be decremented by one. This property is called “self-healing.” 27217Self-healing shall not cause the count of failed attempts to decrement below zero. 27218The count of failed attempts, the lockout interval, and self-healing interval are settable using 27219TPM2_DictionaryAttackParameters(). The lockout parameters and the current value of the lockout 27220counter can be read with TPM2_GetCapability(). 27221Dictionary attack protection does not apply to an entity associated with a permanent handle (handle type 27222== TPM_HT_PERMANENT). 2722327.2 27224 27225TPM2_DictionaryAttackLockReset 27226 2722727.2.1 General Description 27228This command cancels the effect of a TPM lockout due to a number of successive authorization failures. 27229If this command is properly authorized, the lockout counter is set to zero. 27230Only one authorization failure is allowed for this command during a lockoutRecovery interval (set using 27231TPM2_DictionaryAttackParameters(). 27232 27233Family “2.0” 27234Level 00 Revision 00.99 27235 27236Published 27237Copyright © TCG 2006-2013 27238 27239Page 331 27240October 31, 2013 27241 27242 Part 3: Commands 27243 27244Trusted Platform Module Library 27245 2724627.2.2 Command and Response 27247Table 165 — TPM2_DictionaryAttackLockReset Command 27248Type 27249 27250Name 27251 27252TPMI_ST_COMMAND_TAG 27253 27254tag 27255 27256UINT32 27257 27258commandSize 27259 27260TPM_CC 27261 27262commandCode 27263 27264TPM_CC_DictionaryAttackLockReset {NV} 27265 27266@lockHandle 27267 27268TPM_RH_LOCKOUT 27269Auth Index: 1 27270Auth Role: USER 27271 27272TPMI_RH_LOCKOUT 27273 27274Description 27275 27276Table 166 — TPM2_DictionaryAttackLockReset Response 27277Type 27278 27279Name 27280 27281Description 27282 27283TPM_ST 27284 27285tag 27286 27287see clause 8 27288 27289UINT32 27290 27291responseSize 27292 27293TPM_RC 27294 27295responseCode 27296 27297Page 332 27298October 31, 2013 27299 27300Published 27301Copyright © TCG 2006-2013 27302 27303Family “2.0” 27304Level 00 Revision 00.99 27305 27306 Trusted Platform Module Library 27307 27308Part 3: Commands 27309 2731027.2.3 Detailed Actions 273111 273122 273133 273144 273155 273166 273177 273188 273199 2732010 2732111 2732212 2732313 2732414 2732515 2732616 2732717 2732818 2732919 2733020 2733121 2733222 2733323 2733424 2733525 2733626 2733727 2733828 27339 27340#include "InternalRoutines.h" 27341#include "DictionaryAttackLockReset_fp.h" 27342 27343TPM_RC 27344TPM2_DictionaryAttackLockReset( 27345DictionaryAttackLockReset_In 27346 27347*in 27348 27349// IN: input parameter list 27350 27351) 27352{ 27353TPM_RC 27354 27355result; 27356 27357// Input parameter is not reference in command action 27358in = NULL; 27359// The command needs NV update. Check if NV is available. 27360// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 27361// this point 27362result = NvIsAvailable(); 27363if(result != TPM_RC_SUCCESS) return result; 27364// Internal Data Update 27365// Set failed tries to 0 27366gp.failedTries = 0; 27367// Record the changes to NV 27368NvWriteReserved(NV_FAILED_TRIES, &gp.failedTries); 27369return TPM_RC_SUCCESS; 27370} 27371 27372Family “2.0” 27373Level 00 Revision 00.99 27374 27375Published 27376Copyright © TCG 2006-2013 27377 27378Page 333 27379October 31, 2013 27380 27381 Part 3: Commands 27382 2738327.3 27384 27385Trusted Platform Module Library 27386 27387TPM2_DictionaryAttackParameters 27388 2738927.3.1 General Description 27390This command changes the lockout parameters. 27391The command requires lockoutAuth. 27392The timeout parameters (newRecoveryTime and lockoutRecovery) indicate values that are measured with 27393respect to the Time and not Clock. 27394NOTE 27395 27396Use of Time means that the TPM shall be continuously powered for the duration of a timeout. 27397 27398If newRecoveryTime is zero, then DA protection is disabled. Authorizations are checked but authorization 27399failures will not cause the TPM to enter lockout. 27400If newMaxTries is zero, the TPM will be in lockout and use of DA protected entities will be disabled. 27401If lockoutRecovery is zero, then the recovery interval is a boot cycle (_TPM_Init followed by 27402Startup(CLEAR). 27403This command will set the authorization failure count (failedTries) to zero. 27404Only one authorization failure is allowed for this command during a lockoutRecovery interval. 27405 27406Page 334 27407October 31, 2013 27408 27409Published 27410Copyright © TCG 2006-2013 27411 27412Family “2.0” 27413Level 00 Revision 00.99 27414 27415 Trusted Platform Module Library 27416 27417Part 3: Commands 27418 2741927.3.2 Command and Response 27420Table 167 — TPM2_DictionaryAttackParameters Command 27421Type 27422 27423Name 27424 27425Description 27426 27427TPMI_ST_COMMAND_TAG 27428 27429tag 27430 27431UINT32 27432 27433commandSize 27434 27435TPM_CC 27436 27437commandCode 27438 27439TPM_CC_DictionaryAttackParameters {NV} 27440 27441TPMI_RH_LOCKOUT 27442 27443@lockHandle 27444 27445TPM_RH_LOCKOUT 27446Auth Index: 1 27447Auth Role: USER 27448 27449UINT32 27450 27451newMaxTries 27452 27453count of authorization failures before the lockout is 27454imposed 27455 27456UINT32 27457 27458newRecoveryTime 27459 27460time in seconds before the authorization failure count 27461is automatically decremented 27462A value of zero indicates that DA protection is 27463disabled. 27464 27465UINT32 27466 27467lockoutRecovery 27468 27469time in seconds after a lockoutAuth failure before use 27470of lockoutAuth is allowed 27471A value of zero indicates that a reboot is required. 27472 27473Table 168 — TPM2_DictionaryAttackParameters Response 27474Type 27475 27476Name 27477 27478Description 27479 27480TPM_ST 27481 27482tag 27483 27484see clause 8 27485 27486UINT32 27487 27488responseSize 27489 27490TPM_RC 27491 27492responseCode 27493 27494Family “2.0” 27495Level 00 Revision 00.99 27496 27497Published 27498Copyright © TCG 2006-2013 27499 27500Page 335 27501October 31, 2013 27502 27503 Part 3: Commands 27504 27505Trusted Platform Module Library 27506 2750727.3.3 Detailed Actions 275081 275092 275103 275114 275125 275136 275147 275158 275169 2751710 2751811 2751912 2752013 2752114 2752215 2752316 2752417 2752518 2752619 2752720 2752821 2752922 2753023 2753124 2753225 2753326 2753427 2753528 2753629 2753730 2753831 2753932 2754033 27541 27542#include "InternalRoutines.h" 27543#include "DictionaryAttackParameters_fp.h" 27544 27545TPM_RC 27546TPM2_DictionaryAttackParameters( 27547DictionaryAttackParameters_In 27548 27549*in 27550 27551// IN: input parameter list 27552 27553) 27554{ 27555TPM_RC 27556 27557result; 27558 27559// The command needs NV update. Check if NV is available. 27560// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 27561// this point 27562result = NvIsAvailable(); 27563if(result != TPM_RC_SUCCESS) return result; 27564// Internal Data Update 27565// Set dictionary attack parameters 27566gp.maxTries = in->newMaxTries; 27567gp.recoveryTime = in->newRecoveryTime; 27568gp.lockoutRecovery = in->lockoutRecovery; 27569// Set failed tries to 0 27570gp.failedTries = 0; 27571// Record the changes to NV 27572NvWriteReserved(NV_FAILED_TRIES, &gp.failedTries); 27573NvWriteReserved(NV_MAX_TRIES, &gp.maxTries); 27574NvWriteReserved(NV_RECOVERY_TIME, &gp.recoveryTime); 27575NvWriteReserved(NV_LOCKOUT_RECOVERY, &gp.lockoutRecovery); 27576return TPM_RC_SUCCESS; 27577} 27578 27579Page 336 27580October 31, 2013 27581 27582Published 27583Copyright © TCG 2006-2013 27584 27585Family “2.0” 27586Level 00 Revision 00.99 27587 27588 Trusted Platform Module Library 27589 2759028 27591 27592Part 3: Commands 27593 27594Miscellaneous Management Functions 27595 2759628.1 27597 27598Introduction 27599 27600This clause contains commands that do not logically group with any other commands. 2760128.2 27602 27603TPM2_PP_Commands 27604 2760528.2.1 General Description 27606This command is used to determine which commands require assertion of Physical Presence (PP) in 27607addition to platformAuth/platformPolicy. 27608This command requires that auth is TPM_RH_PLATFORM and that Physical Presence be asserted. 27609After this command executes successfully, the commands listed in setList will be added to the list of 27610commands that require that Physical Presence be asserted when the handle associated with the 27611authorization is TPM_RH_PLATFORM. The commands in clearList will no longer require assertion of 27612Physical Presence in order to authorize a command. 27613If a command is not in either list, its state is not changed. If a command is in both lists, then it will no 27614longer require Physical Presence (for example, setList is processed first). 27615Only commands with 27616handle types of 27617TPMI_RH_PLATFORM, TPMI_RH_PROVISION, 27618TPMI_RH_CLEAR, or TPMI_RH_HIERARCHY can be gated with Physical Presence. If any other 27619command is in either list, it is discarded. 27620When a command requires that Physical Presence be provided, then Physical Presence shall be 27621asserted for either an HMAC or a Policy authorization. 27622NOTE 27623 27624Physical Presence may be made a requirement of any policy. 27625 27626TPM2_PP_Commands() always requires assertion of Physical Presence. 27627 27628Family “2.0” 27629Level 00 Revision 00.99 27630 27631Published 27632Copyright © TCG 2006-2013 27633 27634Page 337 27635October 31, 2013 27636 27637 Part 3: Commands 27638 27639Trusted Platform Module Library 27640 2764128.2.2 Command and Response 27642Table 169 — TPM2_PP_Commands Command 27643Type 27644 27645Name 27646 27647Description 27648 27649TPMI_ST_COMMAND_TAG 27650 27651tag 27652 27653UINT32 27654 27655commandSize 27656 27657TPM_CC 27658 27659commandCode 27660 27661TPM_CC_PP_Commands {NV} 27662 27663TPMI_RH_PLATFORM 27664 27665@auth 27666 27667TPM_RH_PLATFORM+PP 27668Auth Index: 1 27669Auth Role: USER + Physical Presence 27670 27671TPML_CC 27672 27673setList 27674 27675list of commands to be added to those that will require 27676that Physical Presence be asserted 27677 27678TPML_CC 27679 27680clearList 27681 27682list of commands that will no longer require that 27683Physical Presence be asserted 27684 27685Table 170 — TPM2_PP_Commands Response 27686Type 27687 27688Name 27689 27690Description 27691 27692TPM_ST 27693 27694tag 27695 27696see clause 8 27697 27698UINT32 27699 27700responseSize 27701 27702TPM_RC 27703 27704responseCode 27705 27706Page 338 27707October 31, 2013 27708 27709Published 27710Copyright © TCG 2006-2013 27711 27712Family “2.0” 27713Level 00 Revision 00.99 27714 27715 Trusted Platform Module Library 27716 27717Part 3: Commands 27718 2771928.2.3 Detailed Actions 277201 277212 277223 277234 277245 277256 277267 277278 277289 2772910 2773011 2773112 2773213 2773314 2773415 2773516 2773617 2773718 2773819 2773920 2774021 2774122 2774223 2774324 2774425 2774526 2774627 2774728 2774829 2774930 2775031 2775132 2775233 2775334 2775435 2775536 2775637 2775738 2775839 2775940 2776041 27761 27762#include "InternalRoutines.h" 27763#include "PP_Commands_fp.h" 27764 27765TPM_RC 27766TPM2_PP_Commands( 27767PP_Commands_In 27768 27769*in 27770 27771// IN: input parameter list 27772 27773) 27774{ 27775UINT32 27776TPM_RC 27777 27778i; 27779result; 27780 27781// The command needs NV update. Check if NV is available. 27782// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 27783// this point 27784result = NvIsAvailable(); 27785if(result != TPM_RC_SUCCESS) return result; 27786// Internal Data Update 27787// Process set list 27788for(i = 0; i < in->setList.count; i++) 27789// If command is implemented, set it as PP required. If the input 27790// command is not a PP command, it will be ignored at 27791// PhysicalPresenceCommandSet(). 27792if(CommandIsImplemented(in->setList.commandCodes[i])) 27793PhysicalPresenceCommandSet(in->setList.commandCodes[i]); 27794// Process clear list 27795for(i = 0; i < in->clearList.count; i++) 27796// If command is implemented, clear it as PP required. If the input 27797// command is not a PP command, it will be ignored at 27798// PhysicalPresenceCommandClear(). If the input command is 27799// TPM2_PP_Commands, it will be ignored as well 27800if(CommandIsImplemented(in->clearList.commandCodes[i])) 27801PhysicalPresenceCommandClear(in->clearList.commandCodes[i]); 27802// Save the change of PP list 27803NvWriteReserved(NV_PP_LIST, &gp.ppList); 27804return TPM_RC_SUCCESS; 27805} 27806 27807Family “2.0” 27808Level 00 Revision 00.99 27809 27810Published 27811Copyright © TCG 2006-2013 27812 27813Page 339 27814October 31, 2013 27815 27816 Part 3: Commands 27817 2781828.3 27819 27820Trusted Platform Module Library 27821 27822TPM2_SetAlgorithmSet 27823 2782428.3.1 General Description 27825This command allows the platform to change the set of algorithms that are used by the TPM. The 27826algorithmSet setting is a vendor-dependent value. 27827If the changing of the algorithm set results in a change of the algorithms of PCR banks, then the TPM will 27828need to be reset (_TPM_Init and TPM2_Startup(TPM_SU_CLEAR)) before the new PCR settings take 27829effect. After this command executes successfully, if startupType in the next TPM2_Startup() is not 27830TPM_SU_CLEAR, the TPM shall return TPM_RC_VALUE and enter Failure mode. 27831This command does not change the algorithms available to the platform. 27832NOTE 27833 27834The reference implementation does not have support for this command. In particular, it does not 27835support use of this command to selectively disable algorithms. Proper support wo uld require 27836modification of the unmarshaling code so that each time an algorithm is unmarshaled, it would be 27837verified as being enabled. 27838 27839Page 340 27840October 31, 2013 27841 27842Published 27843Copyright © TCG 2006-2013 27844 27845Family “2.0” 27846Level 00 Revision 00.99 27847 27848 Trusted Platform Module Library 27849 27850Part 3: Commands 27851 2785228.3.2 Command and Response 27853Table 171 — TPM2_SetAlgorithmSet Command 27854Type 27855 27856Name 27857 27858Description 27859 27860TPMI_ST_COMMAND_TAG 27861 27862tag 27863 27864UINT32 27865 27866commandSize 27867 27868TPM_CC 27869 27870commandCode 27871 27872TPM_CC_SetAlgorithmSet {NV} 27873 27874TPMI_RH_PLATFORM 27875 27876@authHandle 27877 27878TPM_RH_PLATFORM 27879Auth Index: 1 27880Auth Role: USER 27881 27882UINT32 27883 27884algorithmSet 27885 27886a TPM vendor-dependent value indicating the 27887algorithm set selection 27888 27889Table 172 — TPM2_SetAlgorithmSet Response 27890Type 27891 27892Name 27893 27894Description 27895 27896TPM_ST 27897 27898tag 27899 27900see clause 8 27901 27902UINT32 27903 27904responseSize 27905 27906TPM_RC 27907 27908responseCode 27909 27910Family “2.0” 27911Level 00 Revision 00.99 27912 27913Published 27914Copyright © TCG 2006-2013 27915 27916Page 341 27917October 31, 2013 27918 27919 Part 3: Commands 27920 27921Trusted Platform Module Library 27922 2792328.3.3 Detailed Actions 279241 279252 279263 279274 279285 279296 279307 279318 279329 2793310 2793411 2793512 2793613 2793714 2793815 2793916 2794017 2794118 2794219 2794320 2794421 2794522 2794623 27947 27948#include "InternalRoutines.h" 27949#include "SetAlgorithmSet_fp.h" 27950 27951TPM_RC 27952TPM2_SetAlgorithmSet( 27953SetAlgorithmSet_In 27954 27955*in 27956 27957// IN: input parameter list 27958 27959) 27960{ 27961TPM_RC 27962 27963result; 27964 27965// The command needs NV update. Check if NV is available. 27966// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 27967// this point 27968result = NvIsAvailable(); 27969if(result != TPM_RC_SUCCESS) return result; 27970// Internal Data Update 27971gp.algorithmSet = in->algorithmSet; 27972// Write the algorithm set changes to NV 27973NvWriteReserved(NV_ALGORITHM_SET, &gp.algorithmSet); 27974return TPM_RC_SUCCESS; 27975} 27976 27977Page 342 27978October 31, 2013 27979 27980Published 27981Copyright © TCG 2006-2013 27982 27983Family “2.0” 27984Level 00 Revision 00.99 27985 27986 Trusted Platform Module Library 27987 27988Part 3: Commands 27989 27990Field Upgrade 27991 2799229 2799329.1 27994 27995Introduction 27996 27997This clause contains the commands for managing field upgrade of the firmware in the TPM. The field 27998upgrade scheme may be used for replacement or augmentation of the firmware installed in the TPM. 27999EXAMPLE 1 28000 28001If an algorithm is found to be flawed, a patch of that algorithm might be installed using the firmware 28002upgrade process. The patch might be a replacement of a portion of the code or a complete 28003replacement of the firmware. 28004 28005EXAMPLE 2 28006 28007If an additional set of ECC parameters is needed, the firmware process may be used to add the 28008parameters to the TPM data set. 28009 28010The 28011field 28012upgrade 28013process 28014uses 28015two 28016commands 28017(TPM2_FieldUpgradeStart() 28018and 28019TPM2_FieldUpgradeData()). TPM2_FieldUpgradeStart() validates that a signature on the provided digest 28020is from the TPM manufacturer and that proper authorization is provided using platformPolicy. 28021NOTE 1 28022 28023The platformPolicy for field upgraded is defined by the PM and may include requirements that the 28024upgrade be signed by the PM or the TPM owner and include any other constraints that are desired 28025by the PM. 28026 28027If the proper authorization is given, the TPM will retain the signed digest and enter the Field Upgrade 28028mode (FUM). While in FUM, the TPM will accept TPM2_FieldUpgradeData() commands. It may accept 28029other commands if it is able to complete them using the previously installed firmware. Otherwise, it will 28030return TPM_RC_UPGRADE. 28031Each block of the field upgrade shall contain the digest of the next block of the field upgrade data. That 28032digest shall be included in the digest of the previous block. The digest of the first block is signed by the 28033TPM manufacturer. That signature and first block digest are the parameters for 28034TPM2_FieldUpgradeStart(). The digest is saved in the TPM as the required digest for the next field 28035upgrade data block and as the identifier of the field upgrade sequence. 28036For each field upgrade data block that is sent to the TPM by TPM2_FieldUpgradeData(), the TPM shall 28037validate that the digest matches the required digest and if not, shall return TPM_RC_VALUE. The TPM 28038shall extract the digest of the next expected block and return that value to the caller, along with the digest 28039of the first data block of the update sequence. 28040The system may attempt to abandon the firmware upgrade by using a zero-length buffer in 28041TPM2_FieldUpdateData(). If the TPM is able to resume operation using the firmware present when the 28042upgrade started, then the TPM will indicate that it has abandon the update by setting the digest of the 28043next block to the Empty Buffer. If the TPM cannot abandon the update, it will return the expected next 28044digest. 28045The system may also attempt to abandon the update because of a power interruption. If the TPM is able 28046to resume normal operations, then it will respond normally to TPM2_Startup(). If the TPM is not able to 28047resume normal operations, then it will respond to any command but TPM2_FieldUpgradeData() with 28048TPM_RC_FIELDUPGRADE. 28049After a _TPM_Init, system software may not be able to resume the field upgrade that was in process 28050when the power interruption occurred. In such case, the TPM firmware may be reset to one of two other 28051values: 28052 28053 28054the original firmware that was installed at the factory (“initial firmware”); or 28055 28056 28057 28058the firmware that was in the TPM when the field upgrade process started (“previous firmware”). 28059 28060The TPM retains the digest of the first block for these firmware images and checks to see if the first block 28061after _TPM_Init matches either of those digests. If so, the firmware update process restarts and the 28062original firmware may be loaded. 28063Family “2.0” 28064Level 00 Revision 00.99 28065 28066Published 28067Copyright © TCG 2006-2013 28068 28069Page 343 28070October 31, 2013 28071 28072 Part 3: Commands 28073NOTE 2 28074 28075Trusted Platform Module Library 28076 28077The TPM is required to accept the previous firmware as either a vendor -provided update or as 28078recovered from the TPM using TPM2_FirmwareRead(). 28079 28080When the last block of the firmware upgrade is loaded into the TPM (indicated to the TPM by data in the 28081data block in a TPM vendor-specific manner), the TPM will complete the upgrade process. If the TPM is 28082able to resume normal operations without a reboot, it will set the hash algorithm of the next block to 28083TPM_ALG_NULL and return TPM_RC_SUCCESS. If a reboot is required, the TPM shall return 28084TPM_RC_REBOOT in response to the last TPM2_FieldUpgradeData() and all subsequent TPM 28085commands until a _TPM_Init is received. 28086NOTE 3 28087 28088Because no additional data is allowed when the res ponse code is not TPM_RC_SUCCESS, the TPM 28089returns TPM_RC_SUCCESS for all calls to TPM2_FieldUpgradeData() except the last. In this 28090manner, the TPM is able to indicate the digest of the next block. If a _TPM_Init occurs while the 28091TPM is in FUM, the next block may be the digest for the first block of the original firmware. If it is 28092not, then the TPM will not accept the original firmware until the next _TPM_Init when the TPM is in 28093FUM. 28094 28095During the field upgrade process, the TPM shall preserve: 28096 28097 28098Primary Seeds; 28099 28100 28101 28102Hierarchy authValue, authPolicy, and proof values; 28103 28104 28105 28106Lockout authValue and authorization failure count values; 28107 28108 28109 28110PCR authValue and authPolicy values; 28111 28112 28113 28114NV Index allocations and contents; 28115 28116 28117 28118Persistent object allocations and contents; and 28119 28120 28121 28122Clock. 28123 28124Page 344 28125October 31, 2013 28126 28127Published 28128Copyright © TCG 2006-2013 28129 28130Family “2.0” 28131Level 00 Revision 00.99 28132 28133 Trusted Platform Module Library 28134 2813529.2 28136 28137Part 3: Commands 28138 28139TPM2_FieldUpgradeStart 28140 2814129.2.1 General Description 28142This command uses platformPolicy and a TPM Vendor Authorization Key to authorize a Field Upgrade 28143Manifest. 28144If the signature checks 28145TPM2_FieldUpgradeData(). 28146 28147succeed, 28148 28149the 28150 28151authorization 28152 28153is 28154 28155valid 28156 28157and 28158 28159the 28160 28161TPM 28162 28163will 28164 28165accept 28166 28167This signature is checked against the loaded key referenced by keyHandle. This key will have a Name 28168that is the same as a value that is part of the TPM firmware data. If the signature is not valid, the TPM 28169shall return TPM_RC_SIGNATURE. 28170NOTE 28171 28172A loaded key is used rather than a hard-coded key to reduce the amount of memory needed for this 28173key data in case more than one vendor key is needed. 28174 28175Family “2.0” 28176Level 00 Revision 00.99 28177 28178Published 28179Copyright © TCG 2006-2013 28180 28181Page 345 28182October 31, 2013 28183 28184 Part 3: Commands 28185 28186Trusted Platform Module Library 28187 2818829.2.2 Command and Response 28189Table 173 — TPM2_FieldUpgradeStart Command 28190Type 28191 28192Name 28193 28194Description 28195 28196TPMI_ST_COMMAND_TAG 28197 28198tag 28199 28200UINT32 28201 28202commandSize 28203 28204TPM_CC 28205 28206commandCode 28207 28208TPM_CC_FieldUpgradeStart 28209 28210TPMI_RH_PLATFORM 28211 28212@authorization 28213 28214TPM_RH_PLATFORM+{PP} 28215Auth Index:1 28216Auth Role: ADMIN 28217 28218TPMI_DH_OBJECT 28219 28220keyHandle 28221 28222handle of a public area that contains the TPM Vendor 28223Authorization Key that will be used to validate 28224manifestSignature 28225Auth Index: None 28226 28227TPM2B_DIGEST 28228 28229fuDigest 28230 28231digest of the first block in the field upgrade sequence 28232 28233TPMT_SIGNATURE 28234 28235manifestSignature 28236 28237signature over fuDigest using the key associated with 28238keyHandle (not optional) 28239 28240Table 174 — TPM2_FieldUpgradeStart Response 28241Type 28242 28243Name 28244 28245Description 28246 28247TPM_ST 28248 28249tag 28250 28251see clause 8 28252 28253UINT32 28254 28255responseSize 28256 28257TPM_RC 28258 28259responseCode 28260 28261Page 346 28262October 31, 2013 28263 28264Published 28265Copyright © TCG 2006-2013 28266 28267Family “2.0” 28268Level 00 Revision 00.99 28269 28270 Trusted Platform Module Library 28271 28272Part 3: Commands 28273 2827429.2.3 Detailed Actions 282751 282762 282773 282784 282795 282806 282817 282828 282839 2828410 2828511 2828612 2828713 28288 28289#include "InternalRoutines.h" 28290#include "FieldUpgradeStart_fp.h" 28291#if CC_FieldUpgradeStart == YES 28292 28293TPM_RC 28294TPM2_FieldUpgradeStart( 28295FieldUpgradeStart_In 28296 28297*in 28298 28299// IN: input parameter list 28300 28301) 28302{ 28303// Not implemented 28304UNUSED_PARAMETER(in); 28305return TPM_RC_SUCCESS; 28306} 28307#endif 28308 28309Family “2.0” 28310Level 00 Revision 00.99 28311 28312Published 28313Copyright © TCG 2006-2013 28314 28315Page 347 28316October 31, 2013 28317 28318 Part 3: Commands 28319 2832029.3 28321 28322Trusted Platform Module Library 28323 28324TPM2_FieldUpgradeData 28325 2832629.3.1 General Description 28327This command will take the actual field upgrade image to be installed on the TPM. The exact format of 28328fuData is vendor-specific. This command is only possible following a successful 28329TPM2_FieldUpgradeStart(). 28330If 28331the 28332TPM 28333has 28334not 28335received 28336a 28337properly 28338authorized 28339TPM2_FieldUpgradeStart(), then the TPM shall return TPM_RC_FIELDUPGRADE. 28340The TPM will validate that the digest of fuData matches an expected value. If so, the TPM may buffer or 28341immediately apply the update. If the digest of fuData does not match an expected value, the TPM shall 28342return TPM_RC_VALUE. 28343 28344Page 348 28345October 31, 2013 28346 28347Published 28348Copyright © TCG 2006-2013 28349 28350Family “2.0” 28351Level 00 Revision 00.99 28352 28353 Trusted Platform Module Library 28354 28355Part 3: Commands 28356 2835729.3.2 Command and Response 28358Table 175 — TPM2_FieldUpgradeData Command 28359Type 28360 28361Name 28362 28363Description 28364 28365TPMI_ST_COMMAND_TAG 28366 28367tag 28368 28369UINT32 28370 28371commandSize 28372 28373TPM_CC 28374 28375commandCode 28376 28377TPM_CC_FieldUpgradeData {NV} 28378 28379TPM2B_MAX_BUFFER 28380 28381fuData 28382 28383field upgrade image data 28384 28385Table 176 — TPM2_FieldUpgradeData Response 28386Type 28387 28388Name 28389 28390Description 28391 28392TPM_ST 28393 28394tag 28395 28396see clause 8 28397 28398UINT32 28399 28400responseSize 28401 28402TPM_RC 28403 28404responseCode 28405 28406TPMT_HA+ 28407 28408nextDigest 28409 28410tagged digest of the next block 28411TPM_ALG_NULL if field update is complete 28412 28413TPMT_HA 28414 28415firstDigest 28416 28417tagged digest of the first block of the sequence 28418 28419Family “2.0” 28420Level 00 Revision 00.99 28421 28422Published 28423Copyright © TCG 2006-2013 28424 28425Page 349 28426October 31, 2013 28427 28428 Part 3: Commands 28429 28430Trusted Platform Module Library 28431 2843229.3.3 Detailed Actions 284331 284342 284353 284364 284375 284386 284397 284408 284419 2844210 2844311 2844412 2844513 2844614 2844715 28448 28449#include "InternalRoutines.h" 28450#include "FieldUpgradeData_fp.h" 28451#if CC_FieldUpgradeData == YES 28452 28453TPM_RC 28454TPM2_FieldUpgradeData( 28455FieldUpgradeData_In 28456FieldUpgradeData_Out 28457 28458*in, 28459*out 28460 28461// IN: input parameter list 28462// OUT: output parameter list 28463 28464) 28465{ 28466// Not implemented 28467UNUSED_PARAMETER(in); 28468UNUSED_PARAMETER(out); 28469return TPM_RC_SUCCESS; 28470} 28471#endif 28472 28473Page 350 28474October 31, 2013 28475 28476Published 28477Copyright © TCG 2006-2013 28478 28479Family “2.0” 28480Level 00 Revision 00.99 28481 28482 Trusted Platform Module Library 28483 2848429.4 28485 28486Part 3: Commands 28487 28488TPM2_FirmwareRead 28489 2849029.4.1 General Description 28491This command is used to read a copy of the current firmware installed in the TPM. 28492The presumption is that the data will be returned in reverse order so that the last block in the sequence 28493would be the first block given to the TPM in case of a failure recovery. If the TPM2_FirmwareRead 28494sequence completes successfully, then the data provided from the TPM will be sufficient to allow the TPM 28495to recover from an abandoned upgrade of this firmware. 28496To start the sequence of retrieving the data, the caller sets sequenceNumber to zero. When the TPM has 28497returned all the firmware data, the TPM will return the Empty Buffer as fuData. 28498The contents of fuData are opaque to the caller. 28499NOTE 1 28500 28501The caller should retain the ordering of the update blocks so that the blocks sent to the TPM have 28502the same size and inverse order as the blocks returned by a sequence of calls to this command. 28503 28504NOTE 2 28505 28506Support for this command is optional even if the TPM implements TPM2_FieldUpgradeStart() and 28507TPM2_FieldUpgradeData(). 28508 28509Family “2.0” 28510Level 00 Revision 00.99 28511 28512Published 28513Copyright © TCG 2006-2013 28514 28515Page 351 28516October 31, 2013 28517 28518 Part 3: Commands 28519 28520Trusted Platform Module Library 28521 2852229.4.2 Command and Response 28523Table 177 — TPM2_FirmwareRead Command 28524Type 28525 28526Name 28527 28528Description 28529 28530TPMI_ST_COMMAND_TAG 28531 28532tag 28533 28534UINT32 28535 28536commandSize 28537 28538TPM_CC 28539 28540commandCode 28541 28542TPM_CC_FirmwareRead 28543 28544UINT32 28545 28546sequenceNumber 28547 28548the number of previous calls to this command in this 28549sequence 28550set to 0 on the first call 28551 28552Table 178 — TPM2_FirmwareRead Response 28553Type 28554 28555Name 28556 28557Description 28558 28559TPM_ST 28560 28561tag 28562 28563see clause 8 28564 28565UINT32 28566 28567responseSize 28568 28569TPM_RC 28570 28571responseCode 28572 28573TPM2B_MAX_BUFFER 28574 28575fuData 28576 28577Page 352 28578October 31, 2013 28579 28580field upgrade image data 28581 28582Published 28583Copyright © TCG 2006-2013 28584 28585Family “2.0” 28586Level 00 Revision 00.99 28587 28588 Trusted Platform Module Library 28589 28590Part 3: Commands 28591 2859229.4.3 Detailed Actions 285931 285942 285953 285964 285975 285986 285997 286008 286019 2860210 2860311 2860412 2860513 28606 28607#include "InternalRoutines.h" 28608#include "FirmwareRead_fp.h" 28609 28610TPM_RC 28611TPM2_FirmwareRead( 28612FirmwareRead_In 28613FirmwareRead_Out 28614 28615*in, 28616*out 28617 28618// IN: input parameter list 28619// OUT: output parameter list 28620 28621) 28622{ 28623// Not implemented 28624UNUSED_PARAMETER(in); 28625UNUSED_PARAMETER(out); 28626return TPM_RC_SUCCESS; 28627} 28628 28629Family “2.0” 28630Level 00 Revision 00.99 28631 28632Published 28633Copyright © TCG 2006-2013 28634 28635Page 353 28636October 31, 2013 28637 28638 Part 3: Commands 28639 2864030 28641 28642Trusted Platform Module Library 28643 28644Context Management 28645 2864630.1 28647 28648Introduction 28649 28650Three of the commands in this clause (TPM2_ContextSave(), TPM2_ContextLoad(), and 28651TPM2_FlushContext()) implement the resource management described in the "Context Management" 28652clause in Part 1. 28653The fourth command in this clause (TPM2_EvictControl()) is used to control the persistence of a loadable 28654objects in TPM memory. Background for this command may be found in the "Owner and Platform Evict 28655Objects" clause in Part 1. 2865630.2 28657 28658TPM2_ContextSave 28659 2866030.2.1 General Description 28661This command saves a session context, object context, or sequence object context outside the TPM. 28662No authorization sessions of any type are allowed with this command and tag is required to be 28663TPM_ST_NO_SESSIONS. 28664NOTE 28665 28666This preclusion avoids complex issues of dealing with the same session in handle and in the session 28667area. While it might be possible to provide specificity, it would add unnecessary complexity to the 28668TPM and, because this capability would provide no application benefit, use of authorization ses sions 28669for audit or encryption is prohibited. 28670 28671The TPM shall encrypt and integrity protect the context as described in the "Context Protection" clause in 28672Part 1. 28673See the “Context Data” clause in Part 2 for a description of the context structure in the response. 28674 28675Page 354 28676October 31, 2013 28677 28678Published 28679Copyright © TCG 2006-2013 28680 28681Family “2.0” 28682Level 00 Revision 00.99 28683 28684 Trusted Platform Module Library 28685 28686Part 3: Commands 28687 2868830.2.2 Command and Response 28689Table 179 — TPM2_ContextSave Command 28690Type 28691 28692Name 28693 28694Description 28695 28696TPMI_ST_COMMAND_TAG 28697 28698tag 28699 28700TPM_ST_NO_SESSIONS 28701 28702UINT32 28703 28704commandSize 28705 28706TPM_CC 28707 28708commandCode 28709 28710TPM_CC_ContextSave 28711 28712TPMI_DH_CONTEXT 28713 28714saveHandle 28715 28716handle of the resource to save 28717Auth Index: None 28718 28719Table 180 — TPM2_ContextSave Response 28720Type 28721 28722Name 28723 28724Description 28725 28726TPM_ST 28727 28728tag 28729 28730see clause 8 28731 28732UINT32 28733 28734responseSize 28735 28736TPM_RC 28737 28738responseCode 28739 28740TPMS_CONTEXT 28741 28742context 28743 28744Family “2.0” 28745Level 00 Revision 00.99 28746 28747Published 28748Copyright © TCG 2006-2013 28749 28750Page 355 28751October 31, 2013 28752 28753 Part 3: Commands 28754 28755Trusted Platform Module Library 28756 2875730.2.3 Detailed Actions 287581 287592 287603 28761 28762#include "InternalRoutines.h" 28763#include "ContextSave_fp.h" 28764#include "Context_spt_fp.h" 28765Error Returns 28766TPM_RC_CONTEXT_GAP 28767 28768a contextID could not be assigned for a session context save 28769 28770TPM_RC_TOO_MANY_CONTEXTS 287714 287725 287736 287747 287758 287769 2877710 2877811 2877912 2878013 2878114 2878215 2878316 2878417 2878518 2878619 2878720 2878821 2878922 2879023 2879124 2879225 2879326 2879427 2879528 2879629 2879730 2879831 2879932 2880033 2880134 2880235 2880336 2880437 2880538 2880639 2880740 2880841 2880942 2881043 2881144 2881245 2881346 2881447 2881548 2881649 2881750 2881851 2881952 2882053 28821 28822Meaning 28823 28824no more contexts can be saved as the counter has maxed out 28825 28826TPM_RC 28827TPM2_ContextSave( 28828ContextSave_In 28829ContextSave_Out 28830 28831*in, 28832*out 28833 28834// IN: input parameter list 28835// OUT: output parameter list 28836 28837) 28838{ 28839TPM_RC 28840UINT16 28841// blob. 28842UINT64 28843TPM2B_SYM_KEY 28844TPM2B_IV 28845 28846result; 28847fingerprintSize; 28848 28849TPM2B_DIGEST 28850UINT16 28851BYTE 28852 28853integrity; 28854integritySize; 28855*buffer; 28856 28857contextID = 0; 28858symKey; 28859iv; 28860 28861// The size of fingerprint in context 28862// session context ID 28863 28864// This command may cause the orderlyState to be cleared due to 28865// the update of state reset data. If this is the case, check if NV is 28866// available first 28867if(gp.orderlyState != SHUTDOWN_NONE) 28868{ 28869// The command needs NV update. Check if NV is available. 28870// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 28871// this point 28872result = NvIsAvailable(); 28873if(result != TPM_RC_SUCCESS) return result; 28874} 28875// Internal Data Update 28876// Initialize output handle. At the end of command action, the output 28877// handle of an object will be replaced, while the output handle 28878// for a session will be the same as input 28879out->context.savedHandle = in->saveHandle; 28880// Get the size of fingerprint in context blob. The sequence value in 28881// TPMS_CONTEXT structure is used as the fingerprint 28882fingerprintSize = sizeof(out->context.sequence); 28883// Compute the integrity size at the beginning of context blob 28884integritySize = sizeof(integrity.t.size) 28885+ CryptGetHashDigestSize(CONTEXT_INTEGRITY_HASH_ALG); 28886// Perform object or session specific context save 28887switch(HandleGetType(in->saveHandle)) 28888{ 28889case TPM_HT_TRANSIENT: 28890{ 28891 28892Page 356 28893October 31, 2013 28894 28895Published 28896Copyright © TCG 2006-2013 28897 28898Family “2.0” 28899Level 00 Revision 00.99 28900 28901 Trusted Platform Module Library 2890254 2890355 2890456 2890557 2890658 2890759 2890860 2890961 2891062 2891163 2891264 2891365 2891466 2891567 2891668 2891769 2891870 2891971 2892072 2892173 2892274 2892375 2892476 2892577 2892678 2892779 2892880 2892981 2893082 2893183 2893284 2893385 2893486 2893587 2893688 2893789 2893890 2893991 2894092 2894193 2894294 2894395 2894496 2894597 2894698 2894799 28948100 28949101 28950102 28951103 28952104 28953105 28954106 28955107 28956108 28957109 28958110 28959111 28960112 28961113 28962114 28963115 28964116 28965117 28966 28967OBJECT 28968OBJECT 28969 28970Part 3: Commands 28971 28972*object = ObjectGet(in->saveHandle); 28973*outObject = 28974(OBJECT *)(out->context.contextBlob.t.buffer 28975+ integritySize + fingerprintSize); 28976 28977// Set size of the context data. The contents of context blob is vendor 28978// defined. In this implementation, the size is size of integrity 28979// plus fingerprint plus the whole internal OBJECT structure 28980out->context.contextBlob.t.size = integritySize + 28981fingerprintSize + sizeof(*object); 28982// Copy the whole internal OBJECT structure to context blob, leave 28983// the size for fingerprint 28984*outObject = *object; 28985// Increment object context ID 28986gr.objectContextID++; 28987// If object context ID overflows, TPM should be put in failure mode 28988if(gr.objectContextID == 0) 28989FAIL(FATAL_ERROR_INTERNAL); 28990// Fill in other return values for an object. 28991out->context.sequence = gr.objectContextID; 28992// For regular object, savedHandle is 0x80000000. For sequence object, 28993// savedHandle is 0x80000001. For object with stClear, savedHandle 28994// is 0x80000002 28995if(ObjectIsSequence(object)) 28996{ 28997out->context.savedHandle = 0x80000001; 28998SequenceDataImportExport(object, outObject, EXPORT_STATE); 28999} 29000else if(object->attributes.stClear == SET) 29001{ 29002out->context.savedHandle = 0x80000002; 29003} 29004else 29005{ 29006out->context.savedHandle = 0x80000000; 29007} 29008// Get object hierarchy 29009out->context.hierarchy = ObjectDataGetHierarchy(object); 29010break; 29011} 29012case TPM_HT_HMAC_SESSION: 29013case TPM_HT_POLICY_SESSION: 29014{ 29015SESSION 29016*session = SessionGet(in->saveHandle); 29017// Set size of the context data. The contents of context blob is vendor 29018// defined. In this implementation, the size of context blob is the 29019// size of a internal session structure plus the size of 29020// fingerprint plus the size of integrity 29021out->context.contextBlob.t.size = integritySize + 29022fingerprintSize + sizeof(*session); 29023// Copy the whole internal SESSION structure to context blob. 29024// Save space for fingerprint at the beginning of the buffer 29025// This is done before anything else so that the actual context 29026// can be reclaimed after this call 29027MemoryCopy(out->context.contextBlob.t.buffer 29028+ integritySize + fingerprintSize, 29029session, sizeof(*session), 29030 29031Family “2.0” 29032Level 00 Revision 00.99 29033 29034Published 29035Copyright © TCG 2006-2013 29036 29037Page 357 29038October 31, 2013 29039 29040 Part 3: Commands 29041118 29042119 29043120 29044121 29045122 29046123 29047124 29048125 29049126 29050127 29051128 29052129 29053130 29054131 29055132 29056133 29057134 29058135 29059136 29060137 29061138 29062139 29063140 29064141 29065142 29066143 29067144 29068145 29069146 29070147 29071148 29072149 29073150 29074151 29075152 29076153 29077154 29078155 29079156 29080157 29081158 29082159 29083160 29084161 29085162 29086163 29087164 29088165 29089166 29090167 29091168 29092169 29093170 29094171 29095172 29096173 29097174 29098 29099Trusted Platform Module Library 29100sizeof(out->context.contextBlob.t.buffer) 29101- integritySize - fingerprintSize); 29102 29103// Fill in the other return parameters for a session 29104// Get a context ID and set the session tracking values appropriately 29105// TPM_RC_CONTEXT_GAP is a possible error. 29106// SessionContextSave() will flush the in-memory context 29107// so no additional errors may occur after this call. 29108result = SessionContextSave(out->context.savedHandle, &contextID); 29109if(result != TPM_RC_SUCCESS) return result; 29110// sequence number is the current session contextID 29111out->context.sequence = contextID; 29112// use TPM_RH_NULL as hierarchy for session context 29113out->context.hierarchy = TPM_RH_NULL; 29114break; 29115} 29116default: 29117// SaveContext may only take an object handle or a session handle. 29118// All the other handle type should be filtered out at unmarshal 29119pAssert(FALSE); 29120break; 29121} 29122// Save fingerprint at the beginning of encrypted area of context blob. 29123// Reserve the integrity space 29124MemoryCopy(out->context.contextBlob.t.buffer + integritySize, 29125&out->context.sequence, sizeof(out->context.sequence), 29126sizeof(out->context.contextBlob.t.buffer) - integritySize); 29127// Compute context encryption key 29128ComputeContextProtectionKey(&out->context, &symKey, &iv); 29129// Encrypt context blob 29130CryptSymmetricEncrypt(out->context.contextBlob.t.buffer + integritySize, 29131CONTEXT_ENCRYPT_ALG, CONTEXT_ENCRYPT_KEY_BITS, 29132TPM_ALG_CFB, symKey.t.buffer, &iv, 29133out->context.contextBlob.t.size - integritySize, 29134out->context.contextBlob.t.buffer + integritySize); 29135// Compute integrity hash for the object 29136// In this implementation, the same routine is used for both sessions 29137// and objects. 29138ComputeContextIntegrity(&out->context, &integrity); 29139// add integrity at the beginning of context blob 29140buffer = out->context.contextBlob.t.buffer; 29141TPM2B_DIGEST_Marshal(&integrity, &buffer, NULL); 29142// orderly state should be cleared because of the update of state reset and 29143// state clear data 29144g_clearOrderly = TRUE; 29145return TPM_RC_SUCCESS; 29146} 29147 29148Page 358 29149October 31, 2013 29150 29151Published 29152Copyright © TCG 2006-2013 29153 29154Family “2.0” 29155Level 00 Revision 00.99 29156 29157 Trusted Platform Module Library 29158 2915930.3 29160 29161Part 3: Commands 29162 29163TPM2_ContextLoad 29164 2916530.3.1 General Description 29166This command is used to reload a context that has been saved by TPM2_ContextSave(). 29167No authorization sessions of any type are allowed with this command and tag is required to be 29168TPM_ST_NO_SESSIONS (see note in 30.2.1). 29169The TPM will return TPM_RC_HIERARCHY if the context is associated with a hierarchy that is disabled. 29170NOTE 29171 29172Contexts for authorization sessions and for sequence object s belong to the NULL hierarchy which is 29173never disabled. 29174 29175See the “Context Data” clause in Part 2 for a description of the values in the context parameter. 29176If the integrity HMAC of the saved context is not valid, the TPM shall return TPM_RC_INTEGRITY. 29177The TPM shall perform a check on the decrypted context as described in the "Context Confidentiality 29178Protections" clause of Part 1 and enter failure mode if the check fails. 29179 29180Family “2.0” 29181Level 00 Revision 00.99 29182 29183Published 29184Copyright © TCG 2006-2013 29185 29186Page 359 29187October 31, 2013 29188 29189 Part 3: Commands 29190 29191Trusted Platform Module Library 29192 2919330.3.2 Command and Response 29194Table 181 — TPM2_ContextLoad Command 29195Type 29196 29197Name 29198 29199Description 29200 29201TPMI_ST_COMMAND_TAG 29202 29203tag 29204 29205TPM_ST_NO_SESSIONS 29206 29207UINT32 29208 29209commandSize 29210 29211TPM_CC 29212 29213commandCode 29214 29215TPM_CC_ContextLoad 29216 29217TPMS_CONTEXT 29218 29219context 29220 29221the context blob 29222 29223Table 182 — TPM2_ContextLoad Response 29224Type 29225 29226Name 29227 29228Description 29229 29230TPM_ST 29231 29232tag 29233 29234see clause 8 29235 29236UINT32 29237 29238responseSize 29239 29240TPM_RC 29241 29242responseCode 29243 29244TPMI_DH_CONTEXT 29245 29246loadedHandle 29247 29248Page 360 29249October 31, 2013 29250 29251the handle assigned to the resource after it has been 29252successfully loaded 29253 29254Published 29255Copyright © TCG 2006-2013 29256 29257Family “2.0” 29258Level 00 Revision 00.99 29259 29260 Trusted Platform Module Library 29261 29262Part 3: Commands 29263 2926430.3.3 Detailed Actions 292651 292662 292673 29268 29269#include "InternalRoutines.h" 29270#include "ContextLoad_fp.h" 29271#include "Context_spt_fp.h" 29272Error Returns 29273TPM_RC_CONTEXT_GAP 29274 29275there is only one available slot and this is not the oldest saved 29276session context 29277 29278TPM_RC_HANDLE 29279 29280'context. savedHandle' does not reference a saved session 29281 29282TPM_RC_HIERARCHY 29283 29284'context.hierarchy' is disabled 29285 29286TPM_RC_INTEGRITY 29287 29288context integrity check fail 29289 29290TPM_RC_OBJECT_MEMORY 29291 29292no free slot for an object 29293 29294TPM_RC_SESSION_MEMORY 29295 29296no free session slots 29297 29298TPM_RC_SIZE 292994 293005 293016 293027 293038 293049 2930510 2930611 2930712 2930813 2930914 2931015 2931116 2931217 2931318 2931419 2931520 2931621 2931722 2931823 2931924 2932025 2932126 2932227 2932328 2932429 2932530 2932631 2932732 2932833 2932934 2933035 2933136 2933237 2933338 2933439 2933540 2933641 2933742 2933843 29339 29340Meaning 29341 29342incorrect context blob size 29343 29344TPM_RC 29345TPM2_ContextLoad( 29346ContextLoad_In 29347ContextLoad_Out 29348 29349*in, 29350*out 29351 29352// IN: input parameter list 29353// OUT: output parameter list 29354 29355) 29356{ 29357// Local Variables 29358TPM_RC 29359result = TPM_RC_SUCCESS; 29360TPM2B_DIGEST 29361TPM2B_DIGEST 29362UINT16 29363UINT64 29364BYTE 29365INT32 29366 29367ingerityToCompare; 29368integrity; 29369integritySize; 29370fingerprint; 29371*buffer; 29372size; 29373 29374TPM_HT 29375TPM2B_SYM_KEY 29376TPM2B_IV 29377 29378handleType; 29379symKey; 29380iv; 29381 29382// Input Validation 29383// Check context blob size 29384handleType = HandleGetType(in->context.savedHandle); 29385// Check integrity 29386// In this implementation, the same routine is used for both sessions 29387// and objects. 29388integritySize = sizeof(integrity.t.size) 29389+ CryptGetHashDigestSize(CONTEXT_INTEGRITY_HASH_ALG); 29390// Get integrity from context blob 29391buffer = in->context.contextBlob.t.buffer; 29392size = (INT32) in->context.contextBlob.t.size; 29393result = TPM2B_DIGEST_Unmarshal(&integrity, &buffer, &size); 29394if(result != TPM_RC_SUCCESS) 29395return result; 29396// Compute context integrity 29397ComputeContextIntegrity(&in->context, &ingerityToCompare); 29398 29399Family “2.0” 29400Level 00 Revision 00.99 29401 29402Published 29403Copyright © TCG 2006-2013 29404 29405Page 361 29406October 31, 2013 29407 29408 Part 3: Commands 2940944 2941045 2941146 2941247 2941348 2941449 2941550 2941651 2941752 2941853 2941954 2942055 2942156 2942257 2942358 2942459 2942560 2942661 2942762 2942863 2942964 2943065 2943166 2943267 2943368 2943469 2943570 2943671 2943772 2943873 2943974 2944075 2944176 2944277 2944378 2944479 2944580 2944681 2944782 2944883 2944984 2945085 2945186 2945287 2945388 2945489 2945590 2945691 2945792 2945893 2945994 2946095 2946196 2946297 2946398 2946499 29465100 29466101 29467102 29468103 29469104 29470105 29471106 29472107 29473 29474Trusted Platform Module Library 29475 29476// Compare integrity 29477if(!Memory2BEqual(&integrity.b, &ingerityToCompare.b)) 29478return TPM_RC_INTEGRITY + RC_ContextLoad_context; 29479// Compute context encryption key 29480ComputeContextProtectionKey(&in->context, &symKey, &iv); 29481// Decrypt context data in place 29482CryptSymmetricDecrypt(in->context.contextBlob.t.buffer + integritySize, 29483CONTEXT_ENCRYPT_ALG, CONTEXT_ENCRYPT_KEY_BITS, 29484TPM_ALG_CFB, symKey.t.buffer, &iv, 29485in->context.contextBlob.t.size - integritySize, 29486in->context.contextBlob.t.buffer + integritySize); 29487// Read the fingerprint value, skip the leading integrity size 29488MemoryCopy(&fingerprint, in->context.contextBlob.t.buffer + integritySize, 29489sizeof(fingerprint), sizeof(fingerprint)); 29490// Check fingerprint. If the check fails, TPM should be put to failure mode 29491if(fingerprint != in->context.sequence) 29492FAIL(FATAL_ERROR_INTERNAL); 29493// Perform object or session specific input check 29494switch(handleType) 29495{ 29496case TPM_HT_TRANSIENT: 29497{ 29498// Get a pointer to the object in the context blob 29499OBJECT 29500*outObject = (OBJECT *)(in->context.contextBlob.t.buffer 29501+ integritySize + sizeof(fingerprint)); 29502// Discard any changes to the handle that the TRM might have made 29503in->context.savedHandle = TRANSIENT_FIRST; 29504// If hierarchy is disabled, no object context can be loaded in this 29505// hierarchy 29506if(!HierarchyIsEnabled(in->context.hierarchy)) 29507return TPM_RC_HIERARCHY + RC_ContextLoad_context; 29508// Restore object. A TPM_RC_OBJECT_MEMORY error may be returned at 29509// this point 29510result = ObjectContextLoad(outObject, &out->loadedHandle); 29511if(result != TPM_RC_SUCCESS) 29512return result; 29513// If this is a sequence object, the crypto library may need to 29514// reformat the data into an internal format 29515if(ObjectIsSequence(outObject)) 29516SequenceDataImportExport(ObjectGet(out->loadedHandle), 29517outObject, IMPORT_STATE); 29518break; 29519} 29520case TPM_HT_POLICY_SESSION: 29521case TPM_HT_HMAC_SESSION: 29522{ 29523SESSION 29524 29525*session = (SESSION *)(in->context.contextBlob.t.buffer 29526+ integritySize + sizeof(fingerprint)); 29527 29528// This command may cause the orderlyState to be cleared due to 29529// the update of state reset data. If this is the case, check if NV is 29530// available first 29531 29532Page 362 29533October 31, 2013 29534 29535Published 29536Copyright © TCG 2006-2013 29537 29538Family “2.0” 29539Level 00 Revision 00.99 29540 29541 Trusted Platform Module Library 29542108 29543109 29544110 29545111 29546112 29547113 29548114 29549115 29550116 29551117 29552118 29553119 29554120 29555121 29556122 29557123 29558124 29559125 29560126 29561127 29562128 29563129 29564130 29565131 29566132 29567133 29568134 29569135 29570136 29571137 29572138 29573139 29574140 29575141 29576142 29577143 29578144 29579 29580Part 3: Commands 29581 29582if(gp.orderlyState != SHUTDOWN_NONE) 29583{ 29584// The command needs NV update. Check if NV is available. 29585// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned 29586// at this point 29587result = NvIsAvailable(); 29588if(result != TPM_RC_SUCCESS) 29589return result; 29590} 29591// Check if input handle points to a valid saved session 29592if(!SessionIsSaved(in->context.savedHandle)) 29593return TPM_RC_HANDLE + RC_ContextLoad_context; 29594// Restore session. A TPM_RC_SESSION_MEMORY, TPM_RC_CONTEXT_GAP error 29595// may be returned at this point 29596result = SessionContextLoad(session, &in->context.savedHandle); 29597if(result != TPM_RC_SUCCESS) 29598return result; 29599out->loadedHandle = in->context.savedHandle; 29600// orderly state should be cleared because of the update of state 29601// reset and state clear data 29602g_clearOrderly = TRUE; 29603break; 29604} 29605default: 29606// Context blob may only have an object handle or a session handle. 29607// All the other handle type should be filtered out at unmarshal 29608pAssert(FALSE); 29609break; 29610} 29611return TPM_RC_SUCCESS; 29612} 29613 29614Family “2.0” 29615Level 00 Revision 00.99 29616 29617Published 29618Copyright © TCG 2006-2013 29619 29620Page 363 29621October 31, 2013 29622 29623 Part 3: Commands 29624 2962530.4 29626 29627Trusted Platform Module Library 29628 29629TPM2_FlushContext 29630 2963130.4.1 General Description 29632This command causes all context associated with a loaded object or session to be removed from TPM 29633memory. 29634This command may not be used to remove a persistent object from the TPM. 29635A session does not have to be loaded in TPM memory to have its context flushed. The saved session 29636context associated with the indicated handle is invalidated. 29637No sessions of any type are allowed with 29638TPM_ST_NO_SESSIONS (see note in 30.2.1). 29639 29640this 29641 29642command 29643 29644and 29645 29646tag 29647 29648is 29649 29650required 29651 29652to 29653 29654be 29655 29656If the handle is for a transient object and the handle is not associated with a loaded object, then the TPM 29657shall return TPM_RC_HANDLE. 29658If the handle is for an authorization session and the handle does not reference a loaded or active session, 29659then the TPM shall return TPM_RC_HANDLE. 29660NOTE 29661 29662flushHandle is a parameter and not a handle. If it were in the handle area, the TPM would validate 29663that the context for the referenced entity is in the TPM. When a TPM2_FlushContext references a 29664saved session context, it is not necessary for the context to be in the TPM . 29665 29666Page 364 29667October 31, 2013 29668 29669Published 29670Copyright © TCG 2006-2013 29671 29672Family “2.0” 29673Level 00 Revision 00.99 29674 29675 Trusted Platform Module Library 29676 29677Part 3: Commands 29678 2967930.4.2 Command and Response 29680Table 183 — TPM2_FlushContext Command 29681Type 29682 29683Name 29684 29685Description 29686 29687TPMI_ST_COMMAND_TAG 29688 29689tag 29690 29691TPM_ST_NO_SESSIONS 29692 29693UINT32 29694 29695commandSize 29696 29697TPM_CC 29698 29699commandCode 29700 29701TPMI_DH_CONTEXT 29702 29703flushHandle 29704 29705TPM_CC_FlushContext 29706the handle of the item to flush 29707NOTE 29708 29709This is a use of a handle as a parameter. 29710 29711Table 184 — TPM2_FlushContext Response 29712Type 29713 29714Name 29715 29716Description 29717 29718TPM_ST 29719 29720tag 29721 29722see clause 8 29723 29724UINT32 29725 29726responseSize 29727 29728TPM_RC 29729 29730responseCode 29731 29732Family “2.0” 29733Level 00 Revision 00.99 29734 29735Published 29736Copyright © TCG 2006-2013 29737 29738Page 365 29739October 31, 2013 29740 29741 Part 3: Commands 29742 29743Trusted Platform Module Library 29744 2974530.4.3 Detailed Actions 297461 297472 29748 29749#include "InternalRoutines.h" 29750#include "FlushContext_fp.h" 29751Error Returns 29752TPM_RC_HANDLE 29753 297543 297554 297565 297576 297587 297598 297609 2976110 2976211 2976312 2976413 2976514 2976615 2976716 2976817 2976918 2977019 2977120 2977221 2977322 2977423 2977524 2977625 2977726 2977827 2977928 2978029 2978130 2978231 2978332 2978433 2978534 2978635 2978736 2978837 2978938 2979039 2979140 2979241 2979342 29794 29795Meaning 29796flushHandle does not reference a loaded object or session 29797 29798TPM_RC 29799TPM2_FlushContext( 29800FlushContext_In 29801) 29802{ 29803// Internal Data Update 29804 29805*in 29806 29807// IN: input parameter list 29808 29809// Call object or session specific routine to flush 29810switch(HandleGetType(in->flushHandle)) 29811{ 29812case TPM_HT_TRANSIENT: 29813if(!ObjectIsPresent(in->flushHandle)) 29814return TPM_RC_HANDLE; 29815// Flush object 29816ObjectFlush(in->flushHandle); 29817break; 29818case TPM_HT_HMAC_SESSION: 29819case TPM_HT_POLICY_SESSION: 29820if( 29821!SessionIsLoaded(in->flushHandle) 29822&& !SessionIsSaved(in->flushHandle) 29823) 29824return TPM_RC_HANDLE; 29825// If the session to be flushed is the exclusive audit session, then 29826// indicate that there is no exclusive audit session any longer. 29827if(in->flushHandle == g_exclusiveAuditSession) 29828g_exclusiveAuditSession = TPM_RH_UNASSIGNED; 29829// Flush session 29830SessionFlush(in->flushHandle); 29831break; 29832default: 29833// This command only take object or session handle. 29834// should be filtered out at handle unmarshal 29835pAssert(FALSE); 29836break; 29837} 29838 29839Other handles 29840 29841return TPM_RC_SUCCESS; 29842} 29843 29844Page 366 29845October 31, 2013 29846 29847Published 29848Copyright © TCG 2006-2013 29849 29850Family “2.0” 29851Level 00 Revision 00.99 29852 29853 Trusted Platform Module Library 29854 2985530.5 29856 29857Part 3: Commands 29858 29859TPM2_EvictControl 29860 2986130.5.1 General Description 29862This command allows a transient object to be made persistent or a persistent object to be evicted. 29863NOTE 1 29864 29865A transient object is one that may be removed from TPM memory using either TPM2_FlushContext 29866or TPM2_Startup(). A persistent object is not removed from TPM memory by TPM2_FlushContext() 29867or TPM2_Startup(). 29868 29869If objectHandle is a transient object, then the call is to make the object persistent and assign 29870persistentHandle to the persistent version of the object. If objectHandle is a persistent object, then the call 29871is to evict the persistent object. 29872Before execution of TPM2_EvictControl code below, the TPM verifies that objectHandle references an 29873object that is resident on the TPM and that persistentHandle is a valid handle for a persistent object. 29874NOTE 2 29875 29876This requirement simplifies the unmarshaling code so that it only need check that persistentHandle 29877is always a persistent object. 29878 29879If objectHandle references a transient object: 29880a) The TPM shall return TPM_RC_ATTRIBUTES if 298811) it is in the hierarchy of TPM_RH_NULL, 298822) only the public portion of the object is loaded, or 298833) the stClear is SET in the object or in an ancestor key. 29884b) The TPM shall return TPM_RC_HIERARCHY if the object is not in the proper hierarchy as 29885determined by auth. 298861) If auth is TPM_RH_PLATFORM, the proper hierarchy is the Platform hierarchy. 298872) If auth is TPM_RH_OWNER, the proper hierarchy is either the Storage or the Endorsement 29888hierarchy. 29889c) The TPM shall return TPM_RC_RANGE if persistentHandle is not in the proper range as determined 29890by auth. 298911) If auth is TPM_RH_OWNER, then persistentHandle shall be in the inclusive range of 2989281 00 00 0016 to 81 7F FF FF16. 298932) If auth is TPM_RH_PLATFORM, then persistentHandle shall be in the inclusive range of 2989481 80 00 0016 to 81 FF FF FF16. 29895d) The TPM shall return TPM_RC_NV_DEFINED if a persistent object exists with the same handle as 29896persistentHandle. 29897e) The TPM shall return TPM_RC_NV_SPACE if insufficient space is available to make the object 29898persistent. 29899f) 29900 29901The TPM shall return TPM_RC_NV_SPACE if execution of this command will prevent the TPM from 29902being able to hold two transient objects of any kind. 29903NOTE 3 29904 29905This 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 29906between memory of different types and it is necessary that the TPM ensure that it is always 29907possible for the management software to move objects to/from TPM memory in order to ensure 29908that the objects required for command execution can be context restored. 29909 29910Family “2.0” 29911Level 00 Revision 00.99 29912 29913Published 29914Copyright © TCG 2006-2013 29915 29916Page 367 29917October 31, 2013 29918 29919 Part 3: Commands 29920 29921Trusted Platform Module Library 29922 29923g) If the TPM returns TPM_RC_SUCCESS, the object referenced by objectHandle will not be flushed 29924and both objectHandle and persistentHandle may be used to access the object. 29925If objectHandle references a persistent object: 29926h) The TPM shall return TPM_RC_RANGE if objectHandle is not in the proper range as determined by 29927auth. If auth is TPM_RC_OWNER, objectHandle shall be in the inclusive range of 81 00 00 0016 to 2992881 7F FF FF16. If auth is TPM_RC_PLATFORM, objectHandle may be any valid persistent object 29929handle. 29930i) 29931 29932If the TPM returns TPM_RC_SUCCESS, objectHandle will be removed from persistent memory and 29933no longer be accessible. 29934 29935NOTE 4 29936 29937The persistent object is not converted to a transient object, as this would prevent the immediate 29938revocation of an object by removing it from persistent memory. 29939 29940Page 368 29941October 31, 2013 29942 29943Published 29944Copyright © TCG 2006-2013 29945 29946Family “2.0” 29947Level 00 Revision 00.99 29948 29949 Trusted Platform Module Library 29950 29951Part 3: Commands 29952 2995330.5.2 Command and Response 29954Table 185 — TPM2_EvictControl Command 29955Type 29956 29957Name 29958 29959TPMI_ST_COMMAND_TAG 29960 29961tag 29962 29963UINT32 29964 29965commandSize 29966 29967TPM_CC 29968 29969commandCode 29970 29971TPM_CC_EvictControl {NV} 29972 29973TPMI_RH_PROVISION 29974 29975@auth 29976 29977TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 29978Auth Handle: 1 29979Auth Role: USER 29980 29981TPMI_DH_OBJECT 29982 29983objectHandle 29984 29985the handle of a loaded object 29986Auth Index: None 29987 29988persistentHandle 29989 29990if objectHandle is a transient object handle, then this is 29991the persistent handle for the object 29992if objectHandle is a persistent object handle, then this 29993shall be the same value as persistentHandle 29994 29995TPMI_DH_PERSISTENT 29996 29997Description 29998 29999Table 186 — TPM2_EvictControl Response 30000Type 30001 30002Name 30003 30004Description 30005 30006TPM_ST 30007 30008tag 30009 30010see clause 8 30011 30012UINT32 30013 30014responseSize 30015 30016TPM_RC 30017 30018responseCode 30019 30020Family “2.0” 30021Level 00 Revision 00.99 30022 30023Published 30024Copyright © TCG 2006-2013 30025 30026Page 369 30027October 31, 2013 30028 30029 Part 3: Commands 30030 30031Trusted Platform Module Library 30032 3003330.5.3 Detailed Actions 300341 300352 30036 30037#include "InternalRoutines.h" 30038#include "EvictControl_fp.h" 30039Error Returns 30040TPM_RC_ATTRIBUTES 30041 30042an object with temporary, stClear or publicOnly attribute SET cannot 30043be made persistent 30044 30045TPM_RC_HIERARCHY 30046 30047auth cannot authorize the operation in the hierarchy of evictObject 30048 30049TPM_RC_HANDLE 30050 30051evictHandle of the persistent object to be evicted is not the same as 30052the persistentHandle argument 30053 30054TPM_RC_NV_HANDLE 30055 30056persistentHandle is unavailable 30057 30058TPM_RC_NV_SPACE 30059 30060no space in NV to make evictHandle persistent 30061 30062TPM_RC_RANGE 30063 300643 300654 300665 300676 300687 300698 300709 3007110 3007211 3007312 3007413 3007514 3007615 3007716 3007817 3007918 3008019 3008120 3008221 3008322 3008423 3008524 3008625 3008726 3008827 3008928 3009029 3009130 3009231 3009332 3009433 3009534 3009635 3009736 3009837 3009938 3010039 3010140 3010241 3010342 3010443 30105 30106Meaning 30107 30108persistentHandle is not in the range corresponding to the hierarchy of 30109evictObject 30110 30111TPM_RC 30112TPM2_EvictControl( 30113EvictControl_In 30114 30115*in 30116 30117// IN: input parameter list 30118 30119) 30120{ 30121TPM_RC 30122OBJECT 30123 30124result; 30125*evictObject; 30126 30127// The command needs NV update. Check if NV is available. 30128// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 30129// this point 30130result = NvIsAvailable(); 30131if(result != TPM_RC_SUCCESS) return result; 30132// Input Validation 30133// Get internal object pointer 30134evictObject = ObjectGet(in->objectHandle); 30135// Temporary, stClear or public only objects can not be made persistent 30136if( 30137evictObject->attributes.temporary == SET 30138|| evictObject->attributes.stClear == SET 30139|| evictObject->attributes.publicOnly == SET 30140) 30141return TPM_RC_ATTRIBUTES + RC_EvictControl_objectHandle; 30142// If objectHandle refers to a persistent object, it should be the same as 30143// input persistentHandle 30144if( 30145evictObject->attributes.evict == SET 30146&& evictObject->evictHandle != in->persistentHandle 30147) 30148return TPM_RC_HANDLE + RC_EvictControl_objectHandle; 30149// Additional auth validation 30150if(in->auth == TPM_RH_PLATFORM) 30151{ 30152// To make persistent 30153if(evictObject->attributes.evict == CLEAR) 30154{ 30155// Platform auth can not set evict object in storage or endorsement 30156// hierarchy 30157 30158Page 370 30159October 31, 2013 30160 30161Published 30162Copyright © TCG 2006-2013 30163 30164Family “2.0” 30165Level 00 Revision 00.99 30166 30167 Trusted Platform Module Library 3016844 3016945 3017046 3017147 3017248 3017349 3017450 3017551 3017652 3017753 3017854 3017955 3018056 3018157 3018258 3018359 3018460 3018561 3018662 3018763 3018864 3018965 3019066 3019167 3019268 3019369 3019470 3019571 3019672 3019773 3019874 3019975 3020076 3020177 3020278 3020379 3020480 3020581 3020682 3020783 3020884 3020985 3021086 3021187 3021288 3021389 3021490 3021591 30216 30217Part 3: Commands 30218 30219if(evictObject->attributes.ppsHierarchy == CLEAR) 30220return TPM_RC_HIERARCHY + RC_EvictControl_objectHandle; 30221// Platform cannot use a handle outside of platform persistent range. 30222if(!NvIsPlatformPersistentHandle(in->persistentHandle)) 30223return TPM_RC_RANGE + RC_EvictControl_persistentHandle; 30224} 30225// Platform auth can delete any persistent object 30226} 30227else if(in->auth == TPM_RH_OWNER) 30228{ 30229// Owner auth can not set or clear evict object in platform hierarchy 30230if(evictObject->attributes.ppsHierarchy == SET) 30231return TPM_RC_HIERARCHY + RC_EvictControl_objectHandle; 30232// Owner cannot use a handle outside of owner persistent range. 30233if( 30234evictObject->attributes.evict == CLEAR 30235&& !NvIsOwnerPersistentHandle(in->persistentHandle) 30236) 30237return TPM_RC_RANGE + RC_EvictControl_persistentHandle; 30238} 30239else 30240{ 30241// Other auth is not allowed in this command and should be filtered out 30242// at unmarshal process 30243pAssert(FALSE); 30244} 30245// Internal Data Update 30246// Change evict state 30247if(evictObject->attributes.evict == CLEAR) 30248{ 30249// Make object persistent 30250// A TPM_RC_NV_HANDLE or TPM_RC_NV_SPACE error may be returned at this 30251// point 30252result = NvAddEvictObject(in->persistentHandle, evictObject); 30253if(result != TPM_RC_SUCCESS) return result; 30254} 30255else 30256{ 30257// Delete the persistent object in NV 30258NvDeleteEntity(evictObject->evictHandle); 30259} 30260return TPM_RC_SUCCESS; 30261} 30262 30263Family “2.0” 30264Level 00 Revision 00.99 30265 30266Published 30267Copyright © TCG 2006-2013 30268 30269Page 371 30270October 31, 2013 30271 30272 Part 3: Commands 30273 3027431 30275 30276Trusted Platform Module Library 30277 30278Clocks and Timers 30279 3028031.1 30281 30282TPM2_ReadClock 30283 3028431.1.1 General Description 30285This command reads the current TPMS_TIME_INFO structure that contains the current setting of Time, 30286Clock, resetCount, and restartCount. 30287No authorization sessions of any type are allowed with this command and tag is required to be 30288TPM_ST_NO_SESSIONS. 30289NOTE 30290 30291This command is intended to allow the TCB to have access to values that have the potential to be 30292privacy sensitive. The values may be read without authorization because the TCB will not disclose 30293these values. Since they are not signed and cannot be accessed in a command that uses an 30294authorization session, it is not possible for any entity, other than the TCB, to be assured that the 30295values are accurate. 30296 30297Page 372 30298October 31, 2013 30299 30300Published 30301Copyright © TCG 2006-2013 30302 30303Family “2.0” 30304Level 00 Revision 00.99 30305 30306 Trusted Platform Module Library 30307 30308Part 3: Commands 30309 3031031.1.2 Command and Response 30311Table 187 — TPM2_ReadClock Command 30312Type 30313 30314Name 30315 30316Description 30317 30318TPMI_ST_COMMAND_TAG 30319 30320tag 30321 30322TPM_ST_NO_SESSIONS 30323 30324UINT32 30325 30326commandSize 30327 30328TPM_CC 30329 30330commandCode 30331 30332TPM_CC_ReadClock 30333 30334Table 188 — TPM2_ReadClock Response 30335Type 30336 30337Name 30338 30339Description 30340 30341TPM_ST 30342 30343tag 30344 30345see clause 8 30346 30347UINT32 30348 30349responseSize 30350 30351TPM_RC 30352 30353returnCode 30354 30355TPMS_TIME_INFO 30356 30357currentTime 30358 30359Family “2.0” 30360Level 00 Revision 00.99 30361 30362Published 30363Copyright © TCG 2006-2013 30364 30365Page 373 30366October 31, 2013 30367 30368 Part 3: Commands 30369 30370Trusted Platform Module Library 30371 3037231.1.3 Detailed Actions 303731 303742 303753 303764 303775 303786 303797 303808 303819 3038210 3038311 3038412 3038513 3038614 30387 30388#include "InternalRoutines.h" 30389#include "ReadClock_fp.h" 30390 30391TPM_RC 30392TPM2_ReadClock( 30393ReadClock_Out *out 30394) 30395{ 30396// Command Output 30397 30398// OUT: output parameter list 30399 30400out->currentTime.time = g_time; 30401TimeFillInfo(&out->currentTime.clockInfo); 30402return TPM_RC_SUCCESS; 30403} 30404 30405Page 374 30406October 31, 2013 30407 30408Published 30409Copyright © TCG 2006-2013 30410 30411Family “2.0” 30412Level 00 Revision 00.99 30413 30414 Trusted Platform Module Library 30415 3041631.2 30417 30418Part 3: Commands 30419 30420TPM2_ClockSet 30421 3042231.2.1 General Description 30423This command is used to advance the value of the TPM’s Clock. The command will fail if newTime is less 30424than the current value of Clock or if the new time is greater than FF FF 00 00 00 00 00 0016. If both of 30425these checks succeed, Clock is set to newTime. If either of these checks fails, the TPM shall return 30426TPM_RC_VALUE and make no change to Clock. 30427NOTE 30428 30429This maximum setting would prevent Clock from rolling over to zero for approximately 8,000 years if 30430the Clock update rate was set so that TPM time was passing 33 percent faster than real time. This 30431would still be more than 6,000 years before Clock would roll over to zero. Because Clock will not roll 30432over in the lifetime of the TPM, there is no need for external software to deal with the possibility that 30433Clock may wrap around. 30434 30435If the value of Clock after the update makes the volatile and non-volatile versions of 30436TPMS_CLOCK_INFO.clock differ by more than the reported update interval, then the TPM shall update 30437the non-volatile version of TPMS_CLOCK_INFO.clock before returning. 30438This command requires platformAuth or ownerAuth. 30439 30440Family “2.0” 30441Level 00 Revision 00.99 30442 30443Published 30444Copyright © TCG 2006-2013 30445 30446Page 375 30447October 31, 2013 30448 30449 Part 3: Commands 30450 30451Trusted Platform Module Library 30452 3045331.2.2 Command and Response 30454Table 189 — TPM2_ClockSet Command 30455Type 30456 30457Name 30458 30459Description 30460 30461TPMI_ST_COMMAND_TAG 30462 30463tag 30464 30465UINT32 30466 30467commandSize 30468 30469TPM_CC 30470 30471commandCode 30472 30473TPM_CC_ClockSet {NV} 30474 30475TPMI_RH_PROVISION 30476 30477@auth 30478 30479TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 30480Auth Handle: 1 30481Auth Role: USER 30482 30483UINT64 30484 30485newTime 30486 30487new Clock setting in milliseconds 30488 30489Table 190 — TPM2_ClockSet Response 30490Type 30491 30492Name 30493 30494Description 30495 30496TPM_ST 30497 30498tag 30499 30500see clause 8 30501 30502UINT32 30503 30504responseSize 30505 30506TPM_RC 30507 30508returnCode 30509 30510Page 376 30511October 31, 2013 30512 30513Published 30514Copyright © TCG 2006-2013 30515 30516Family “2.0” 30517Level 00 Revision 00.99 30518 30519 Trusted Platform Module Library 30520 30521Part 3: Commands 30522 3052331.2.3 Detailed Actions 305241 305252 30526 30527#include "InternalRoutines.h" 30528#include "ClockSet_fp.h" 30529 30530Read the current TPMS_TIMER_INFO structure settings 30531Error Returns 30532TPM_RC_VALUE 305333 305344 305355 305366 305377 305388 305399 3054010 3054111 3054212 3054313 3054414 3054515 3054616 3054717 3054818 3054919 3055020 3055121 3055222 3055323 3055424 3055525 3055626 3055727 3055828 3055929 3056030 3056131 3056232 3056333 3056434 3056535 30566 30567Meaning 30568invalid new clock 30569 30570TPM_RC 30571TPM2_ClockSet( 30572ClockSet_In *in 30573) 30574{ 30575#define CLOCK_UPDATE_MASK 30576UINT64 30577clockNow; 30578 30579// IN: input parameter list 30580((1ULL << NV_CLOCK_UPDATE_INTERVAL)- 1) 30581 30582// Input Validation 30583// new time can not be bigger than 0xFFFF000000000000 or smaller than 30584// current clock 30585if(in->newTime > 0xFFFF000000000000ULL 30586|| in->newTime < go.clock) 30587return TPM_RC_VALUE + RC_ClockSet_newTime; 30588// Internal Data Update 30589// Internal Data Update 30590clockNow = go.clock; 30591// grab the old value 30592go.clock = in->newTime; 30593// set the new value 30594// Check to see if the update has caused a need for an nvClock update 30595if((in->newTime & CLOCK_UPDATE_MASK) > (clockNow & CLOCK_UPDATE_MASK)) 30596{ 30597CryptDrbgGetPutState(GET_STATE); 30598NvWriteReserved(NV_ORDERLY_DATA, &go); 30599// Now the time state is safe 30600go.clockSafe = YES; 30601} 30602return TPM_RC_SUCCESS; 30603} 30604 30605Family “2.0” 30606Level 00 Revision 00.99 30607 30608Published 30609Copyright © TCG 2006-2013 30610 30611Page 377 30612October 31, 2013 30613 30614 Part 3: Commands 30615 3061631.3 30617 30618Trusted Platform Module Library 30619 30620TPM2_ClockRateAdjust 30621 3062231.3.1 General Description 30623This command adjusts the rate of advance of Clock and Time to provide a better approximation to real 30624time. 30625The rateAdjust value is relative to the current rate and not the nominal rate of advance. 30626EXAMPLE 1 30627 30628If this command had been called three times with rateAdjust = TPM_CLOCK_COARSE_SLOWER 30629and once with rateAdjust = TPM_CLOCK_COARSE_FASTER, the net effect will be as if the 30630command had been called twice with rateAdjust = TPM_CLOCK_COARSE_SLOWER. 30631 30632The range of adjustment shall be sufficient to allow Clock and Time to advance at real time but no more. 30633If the requested adjustment would make the rate advance faster or slower than the nominal accuracy of 30634the input frequency, the TPM shall return TPM_RC_VALUE. 30635EXAMPLE 2 30636 30637If the frequency tolerance of the TPM's input clock is +/-10 percent, then the TPM will return 30638TPM_RC_VALUE if the adjustment would make Clock run more than 10 percent faster or slower than 30639nominal. That is, if the input oscillator were nominally 100 megahertz (MHz), then 1 millisecond (ms) 30640would normally take 100,000 counts. The update Clock should be adjustable so that 1 ms is between 3064190,000 and 110,000 counts. 30642 30643The interpretation of “fine” and “coarse” adjustments is implementation-specific. 30644The nominal rate of advance for Clock and Time shall be accurate to within 15 percent. That is, with no 30645adjustment applied, Clock and Time shall be advanced at a rate within 15 percent of actual time. 30646NOTE 30647 30648If the adjustments are incorrect, it will be possible to m ake the difference between advance of 30649Clock/Time and real time to be as much as 1.15 2 or ~1.33. 30650 30651Changes to the current Clock update rate adjustment need not be persisted across TPM power cycles. 30652 30653Page 378 30654October 31, 2013 30655 30656Published 30657Copyright © TCG 2006-2013 30658 30659Family “2.0” 30660Level 00 Revision 00.99 30661 30662 Trusted Platform Module Library 30663 30664Part 3: Commands 30665 3066631.3.2 Command and Response 30667Table 191 — TPM2_ClockRateAdjust Command 30668Type 30669 30670Name 30671 30672Description 30673 30674TPMI_ST_COMMAND_TAG 30675 30676tag 30677 30678UINT32 30679 30680commandSize 30681 30682TPM_CC 30683 30684commandCode 30685 30686TPM_CC_ClockRateAdjust 30687 30688TPMI_RH_PROVISION 30689 30690@auth 30691 30692TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 30693Auth Handle: 1 30694Auth Role: USER 30695 30696TPM_CLOCK_ADJUST 30697 30698rateAdjust 30699 30700Adjustment to current Clock update rate 30701 30702Table 192 — TPM2_ClockRateAdjust Response 30703Type 30704 30705Name 30706 30707Description 30708 30709TPM_ST 30710 30711tag 30712 30713see clause 8 30714 30715UINT32 30716 30717responseSize 30718 30719TPM_RC 30720 30721returnCode 30722 30723Family “2.0” 30724Level 00 Revision 00.99 30725 30726Published 30727Copyright © TCG 2006-2013 30728 30729Page 379 30730October 31, 2013 30731 30732 Part 3: Commands 30733 30734Trusted Platform Module Library 30735 3073631.3.3 Detailed Actions 307371 307382 307393 307404 307415 307426 307437 307448 307459 3074610 3074711 3074812 30749 30750#include "InternalRoutines.h" 30751#include "ClockRateAdjust_fp.h" 30752 30753TPM_RC 30754TPM2_ClockRateAdjust( 30755ClockRateAdjust_In 30756*in 30757) 30758{ 30759// Internal Data Update 30760TimeSetAdjustRate(in->rateAdjust); 30761 30762// IN: input parameter list 30763 30764return TPM_RC_SUCCESS; 30765} 30766 30767Page 380 30768October 31, 2013 30769 30770Published 30771Copyright © TCG 2006-2013 30772 30773Family “2.0” 30774Level 00 Revision 00.99 30775 30776 Trusted Platform Module Library 30777 3077832 30779 30780Part 3: Commands 30781 30782Capability Commands 30783 3078432.1 30785 30786Introduction 30787 30788The TPM has numerous values that indicate the state, capabilities, and properties of the TPM. These 30789values are needed for proper management of the TPM. The TPM2_GetCapability() command is used to 30790access these values. 30791TPM2_GetCapability() allows reporting of multiple values in a single call. The values are grouped 30792according to type. 30793NOTE 30794 3079532.2 30796 30797TPM2_TestParms()is used to determine if a TPM supports a particular combination of algorithm 30798parameters 30799 30800TPM2_GetCapability 30801 3080232.2.1 General Description 30803This command returns various information regarding the TPM and its current state. 30804The capability parameter determines the category of data returned. The property parameter selects the 30805first value of the selected category to be returned. If there is no property that corresponds to the value of 30806property, the next higher value is returned, if it exists. 30807EXAMPLE 1 30808 30809The list of handles of transient objects currently loaded in the TPM may be read one at a time. On 30810the first read, set the property to TRANSIENT_FIRST and propertyCount to one. If a transient object 30811is present, the lowest numbered handle is returned and moreData will be YES if transient objects 30812with higher handles are loaded. On the subsequent call, use returned handle value plus 1 in order to 30813access the next higher handle. 30814 30815The propertyCount parameter indicates the number of capabilities in the indicated group that are 30816requested. The TPM will return the number of requested values (propertyCount) or until the last property 30817of the requested type has been returned. 30818NOTE 1 30819 30820The type of the capability is determined by a combination of capability and property. 30821 30822When all of the properties of the requested type have been returned, the moreData parameter in the 30823response will be set to NO. Otherwise, it will be set to YES. 30824NOTE 2 30825 30826The moreData parameter will be YES if there are more properties e ven if the requested number of 30827capabilities has been returned. 30828 30829The TPM is not required to return more than one value at a time. It is not required to provide the same 30830number of values in response to subsequent requests. 30831EXAMPLE 2 30832 30833A TPM may return 4 properties in response to a TPM2_GetCapability(capability = 30834TPM_CAP_TPM_PROPERTY, property = TPM_PT_MANUFACTURER, propertyCount = 8 ) and for a 30835latter request with the same parameters, the TPM may return as few as one and as many as 8 30836values. 30837 30838When the TPM is in Failure mode, a TPM is required to allow use of this command for access of the 30839following capabilities: 30840 30841Family “2.0” 30842Level 00 Revision 00.99 30843 30844Published 30845Copyright © TCG 2006-2013 30846 30847Page 381 30848October 31, 2013 30849 30850 Part 3: Commands 30851 30852Trusted Platform Module Library 30853 30854 30855 30856TPM_PT_MANUFACTURER 30857 30858 30859 30860TPM_PT_VENDOR_STRING_1 30861 30862 30863 30864TPM_PT_VENDOR_STRING_2 30865 30866(3) 30867 30868 30869 30870TPM_PT_VENDOR_STRING_3 30871 30872(3) 30873 30874 30875 30876TPM_PT_VENDOR_STRING_4 30877 30878(3) 30879 30880 30881 30882TPM_PT_VENDOR_TPM_TYPE 30883 30884 30885 30886TPM_PT_FIRMWARE_VERSION_1 30887 30888 30889 30890TPM_PT_FIRMWARE_VERSION_2 30891 30892NOTE 3 30893 30894If the vendor string does not require one of these values, the property type does not need to exist. 30895 30896A vendor may optionally allow the TPM to return other values. 30897If in Failure mode and a capability is requested that is not available in Failure mode, the TPM shall return 30898no value. 30899EXAMPLE 3 30900 30901Assume the TPM is in Failure mode and the TPM only supports reporting of the minimum required 30902set of properties (the limited set to TPML_TAGGED_PCR_PROPERTY values). If a 30903TPM2_GetCapability is received requesting a capability that has a property type value greater than 30904TPM_PT_FIRMWARE_VERSION_2, the TPM will return a zero length list with the moreData 30905parameter set to NO. If the property type is less than TPM_PT_M ANUFACTURER, the TPM will 30906return TPM_PT_MANUFACTURER. 30907 30908In Failure mode, tag is required to be TPM_ST_NO_SESSIONS or the TPM shall return 30909TPM_RC_FAILURE. 30910The capability categories and the types of the return values are: 30911capability 30912 30913Return Type 30914 30915property 30916(1) 30917 30918TPM_CAP_ALGS 30919 30920TPM_ALG_ID 30921 30922TPML_ALG_PROPERTY 30923 30924TPM_CAP_HANDLES 30925 30926TPM_HANDLE 30927 30928TPML_HANDLE 30929 30930TPM_CAP_COMMANDS 30931 30932TPM_CC 30933 30934TPML_CCA 30935 30936TPM_CAP_PP_COMMANDS 30937 30938TPM_CC 30939 30940TPML_CC 30941 30942TPM_CAP_AUDIT_COMMANDS 30943 30944TPM_CC 30945 30946TPML_CC 30947 30948TPM_CAP_PCRS 30949 30950Reserved 30951 30952TPML_PCR_SELECTION 30953 30954TPM_CAP_TPM_PROPERTIES 30955 30956TPM_PT 30957 30958TPML_TAGGED_TPM_PROPERTY 30959 30960TPM_CAP_PCR_PROPERTIES 30961 30962TPM_PT_PCR 30963 30964TPML_TAGGED_PCR_PROPERTY 30965(1) 30966 30967TPM_CAP_ECC_CURVE 30968 30969TPM_ECC_CURVE 30970 30971TPM_CAP_VENDOR_PROPERTY 30972 30973manufacturer specific 30974 30975TPML_ECC_CURVE 30976manufacturer-specific values 30977 30978NOTES: 30979(1) The TPM_ALG_ID or TPM_ECC_CURVE is cast to a UINT32 30980 30981Page 382 30982October 31, 2013 30983 30984Published 30985Copyright © TCG 2006-2013 30986 30987Family “2.0” 30988Level 00 Revision 00.99 30989 30990 Trusted Platform Module Library 30991 30992Part 3: Commands 30993 30994 30995 30996TPM_CAP_ALGS – Returns a list of TPMS_ALG_PROPERTIES. Each entry is an algorithm ID and a 30997set of properties of the algorithm. 30998 30999 31000 31001TPM_CAP_HANDLES – Returns a list of all of the handles within the handle range of the property 31002parameter. The range of the returned handles is determined by the handle type (the most-significant 31003octet (MSO) of the property). Any of the defined handle types is allowed 31004EXAMPLE 4 31005 31006EXAMPLE 5 31007 31008 31009 31010If the MSO of property is TPM_HT_NV_INDEX, then the TPM will return a list of NV Index 31011values. 31012If the MSO of property is TPM_HT_PCR, then the TPM will return a list of PCR. 31013 31014For this capability, use of TPM_HT_LOADED_SESSION and TPM_HT_SAVED_SESSION is 31015allowed. Requesting handles with a handle type of TPM_HT_LOADED_SESSION will return handles 31016for loaded sessions. The returned handle values will have a handle type of either 31017TPM_HT_HMAC_SESSION or TPM_HT_POLICY_SESSION. If saved sessions are requested, all 31018returned values will have the TPM_HT_HMAC_SESSION handle type because the TPM does not 31019track the session type of saved sessions. 31020NOTE 2 31021 31022 31023 31024TPM_HT_LOADED_SESSION and TPM_HT_HMAC_SESSION have the same value, as do 31025TPM_HT_SAVED_SESSION and TPM_HT_POLICY_SESSION. It is not possible to request that 31026the TPM return a list of loaded HMAC sessions without including the policy sessions. 31027 31028TPM_CAP_COMMANDS – Returns a list of the command attributes for all of the commands 31029implemented in the TPM, starting with the TPM_CC indicated by the property parameter. If vendor 31030specific commands are implemented, the vendor-specific command attribute with the lowest 31031commandIndex, is returned after the non-vendor-specific (base) command. 31032NOTE 4 31033 31034The type of the property parameter is a TPM_CC while the type of the returned list is 31035TPML_CCA. 31036 31037 31038 31039TPM_CAP_PP_COMMANDS – Returns a list of all of the commands currently requiring Physical 31040Presence for confirmation of platform authorization. The list will start with the TPM_CC indicated by 31041property. 31042 31043 31044 31045TPM_CAP_AUDIT_COMMANDS – Returns a list of all of the commands currently set for command 31046audit. 31047 31048 31049 31050TPM_CAP_PCRS – Returns the current allocation of PCR in a TPML_PCR_SELECTION. The 31051property parameter shall be zero. The TPM will always respond to this command with the full PCR 31052allocation and moreData will be NO. 31053 31054 31055 31056TPM_CAP_TPM_PROPERTIES – Returns a list of tagged properties. The tag is a TPM_PT and the 31057property 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 31058will only return values in the same group as the property parameter in the command. 31059 31060 31061 31062TPM_CAP_PCR_PROPERTIES – Returns a list of tagged PCR properties. The tag is a 31063TPM_PT_PCR and the property is a TPMS_PCR_SELECT. 31064 31065The input command property is a TPM_PT_PCR (see Part 2 for PCR properties to be requested) that 31066specifies the first property to be returned. If propertyCount is greater than 1, the list of properties begins 31067with that property and proceeds in TPM_PT_PCR sequence. 31068NOTE 5 31069 31070If the propertyCount selects an unimplemented property, the next higher implemented property 31071is returned. 31072 31073Each item in the list is a TPMS_PCR_SELECT structure that contains a bitmap of all PCR. 31074NOTE 6 31075 31076A PCR index in all banks (all hash algorithms) has the same properties, so the hash algorithm is 31077not specified here. 31078 31079Family “2.0” 31080Level 00 Revision 00.99 31081 31082Published 31083Copyright © TCG 2006-2013 31084 31085Page 383 31086October 31, 2013 31087 31088 Part 3: Commands 31089 31090 31091Trusted Platform Module Library 31092 31093TPM_CAP_TPM_ECC_CURVES – Returns a list of ECC curve identifiers currently available for use 31094in the TPM. 31095 31096The moreData parameter will have a value of YES if there are more values of the requested type that 31097were not returned. 31098If no next capability exists, the TPM will return a zero-length list and moreData will have a value of NO. 31099 31100Page 384 31101October 31, 2013 31102 31103Published 31104Copyright © TCG 2006-2013 31105 31106Family “2.0” 31107Level 00 Revision 00.99 31108 31109 Trusted Platform Module Library 31110 31111Part 3: Commands 31112 3111332.2.2 Command and Response 31114Table 193 — TPM2_GetCapability Command 31115Type 31116 31117Name 31118 31119Description 31120 31121TPMI_ST_COMMAND_TAG 31122 31123tag 31124 31125UINT32 31126 31127commandSize 31128 31129TPM_CC 31130 31131commandCode 31132 31133TPM_CC_GetCapability 31134 31135TPM_CAP 31136 31137capability 31138 31139group selection; determines the format of the response 31140 31141UINT32 31142 31143property 31144 31145further definition of information 31146 31147UINT32 31148 31149propertyCount 31150 31151number of properties of the indicated type to return 31152 31153Table 194 — TPM2_GetCapability Response 31154Type 31155 31156Name 31157 31158Description 31159 31160TPM_ST 31161 31162tag 31163 31164see clause 8 31165 31166UINT32 31167 31168responseSize 31169 31170TPM_RC 31171 31172responseCode 31173 31174TPMI_YES_NO 31175 31176moreData 31177 31178flag to indicate if there are more values of this type 31179 31180TPMS_CAPABILITY_DATA 31181 31182capabilityData 31183 31184the capability data 31185 31186Family “2.0” 31187Level 00 Revision 00.99 31188 31189Published 31190Copyright © TCG 2006-2013 31191 31192Page 385 31193October 31, 2013 31194 31195 Part 3: Commands 31196 31197Trusted Platform Module Library 31198 3119932.2.3 Detailed Actions 312001 312012 31202 31203#include "InternalRoutines.h" 31204#include "GetCapability_fp.h" 31205Error Returns 31206TPM_RC_HANDLE 31207 31208value of property is in an unsupported handle range for the 31209TPM_CAP_HANDLES capability value 31210 31211TPM_RC_VALUE 31212 312133 312144 312155 312166 312177 312188 312199 3122010 3122111 3122212 3122313 3122414 3122515 3122616 3122717 3122818 3122919 3123020 3123121 3123222 3123323 3123424 3123525 3123626 3123727 3123828 3123929 3124030 3124131 3124232 3124333 3124434 3124535 3124636 3124737 3124838 3124939 3125040 3125141 3125242 3125343 3125444 3125545 3125646 3125747 3125848 3125949 3126050 3126151 31262 31263Meaning 31264 31265invalid capability; or property is not 0 for the TPM_CAP_PCRS 31266capability value 31267 31268TPM_RC 31269TPM2_GetCapability( 31270GetCapability_In 31271GetCapability_Out 31272 31273*in, 31274*out 31275 31276// IN: input parameter list 31277// OUT: output parameter list 31278 31279) 31280{ 31281// Command Output 31282// Set output capability type the same as input type 31283out->capabilityData.capability = in->capability; 31284switch(in->capability) 31285{ 31286case TPM_CAP_ALGS: 31287out->moreData = AlgorithmCapGetImplemented((TPM_ALG_ID) in->property, 31288in->propertyCount, &out->capabilityData.data.algorithms); 31289break; 31290case TPM_CAP_HANDLES: 31291switch(HandleGetType((TPM_HANDLE) in->property)) 31292{ 31293case TPM_HT_TRANSIENT: 31294// Get list of handles of loaded transient objects 31295out->moreData = ObjectCapGetLoaded((TPM_HANDLE) in->property, 31296in->propertyCount, 31297&out->capabilityData.data.handles); 31298break; 31299case TPM_HT_PERSISTENT: 31300// Get list of handles of persistent objects 31301out->moreData = NvCapGetPersistent((TPM_HANDLE) in->property, 31302in->propertyCount, 31303&out->capabilityData.data.handles); 31304break; 31305case TPM_HT_NV_INDEX: 31306// Get list of defined NV index 31307out->moreData = NvCapGetIndex((TPM_HANDLE) in->property, 31308in->propertyCount, 31309&out->capabilityData.data.handles); 31310break; 31311case TPM_HT_LOADED_SESSION: 31312// Get list of handles of loaded sessions 31313out->moreData = SessionCapGetLoaded((TPM_HANDLE) in->property, 31314in->propertyCount, 31315&out->capabilityData.data.handles); 31316break; 31317case TPM_HT_ACTIVE_SESSION: 31318// Get list of handles of 31319out->moreData = SessionCapGetSaved((TPM_HANDLE) in->property, 31320in->propertyCount, 31321&out->capabilityData.data.handles); 31322 31323Page 386 31324October 31, 2013 31325 31326Published 31327Copyright © TCG 2006-2013 31328 31329Family “2.0” 31330Level 00 Revision 00.99 31331 31332 Trusted Platform Module Library 3133352 3133453 3133554 3133655 3133756 3133857 3133958 3134059 3134160 3134261 3134362 3134463 3134564 3134665 3134766 3134867 3134968 3135069 3135170 3135271 3135372 3135473 3135574 3135675 3135776 3135877 3135978 3136079 3136180 3136281 3136382 3136483 3136584 3136685 3136786 3136887 3136988 3137089 3137190 3137291 3137392 3137493 3137594 3137695 3137796 3137897 3137998 3138099 31381100 31382101 31383102 31384103 31385104 31386105 31387106 31388107 31389108 31390109 31391110 31392111 31393112 31394113 31395114 31396115 31397 31398Part 3: Commands 31399 31400break; 31401case TPM_HT_PCR: 31402// Get list of handles of PCR 31403out->moreData = PCRCapGetHandles((TPM_HANDLE) in->property, 31404in->propertyCount, 31405&out->capabilityData.data.handles); 31406break; 31407case TPM_HT_PERMANENT: 31408// Get list of permanent handles 31409out->moreData = PermanentCapGetHandles( 31410(TPM_HANDLE) in->property, 31411in->propertyCount, 31412&out->capabilityData.data.handles); 31413break; 31414default: 31415// Unsupported input handle type 31416return TPM_RC_HANDLE + RC_GetCapability_property; 31417break; 31418} 31419break; 31420case TPM_CAP_COMMANDS: 31421out->moreData = CommandCapGetCCList((TPM_CC) in->property, 31422in->propertyCount, 31423&out->capabilityData.data.command); 31424break; 31425case TPM_CAP_PP_COMMANDS: 31426out->moreData = PhysicalPresenceCapGetCCList((TPM_CC) in->property, 31427in->propertyCount, &out->capabilityData.data.ppCommands); 31428break; 31429case TPM_CAP_AUDIT_COMMANDS: 31430out->moreData = CommandAuditCapGetCCList((TPM_CC) in->property, 31431in->propertyCount, 31432&out->capabilityData.data.auditCommands); 31433break; 31434case TPM_CAP_PCRS: 31435// Input property must be 0 31436if(in->property != 0) 31437return TPM_RC_VALUE + RC_GetCapability_property; 31438out->moreData = PCRCapGetAllocation(in->propertyCount, 31439&out->capabilityData.data.assignedPCR); 31440break; 31441case TPM_CAP_PCR_PROPERTIES: 31442out->moreData = PCRCapGetProperties((TPM_PT_PCR) in->property, 31443in->propertyCount, 31444&out->capabilityData.data.pcrProperties); 31445break; 31446case TPM_CAP_TPM_PROPERTIES: 31447out->moreData = TPMCapGetProperties((TPM_PT) in->property, 31448in->propertyCount, 31449&out->capabilityData.data.tpmProperties); 31450break; 31451#ifdef TPM_ALG_ECC 31452case TPM_CAP_ECC_CURVES: 31453out->moreData = CryptCapGetECCCurve((TPM_ECC_CURVE 31454) in->property, 31455in->propertyCount, 31456&out->capabilityData.data.eccCurves); 31457break; 31458#endif // TPM_ALG_ECC 31459case TPM_CAP_VENDOR_PROPERTY: 31460// vendor property is not implemented 31461default: 31462// Unexpected TPM_CAP value 31463return TPM_RC_VALUE; 31464break; 31465 31466Family “2.0” 31467Level 00 Revision 00.99 31468 31469Published 31470Copyright © TCG 2006-2013 31471 31472Page 387 31473October 31, 2013 31474 31475 Part 3: Commands 31476116 31477117 31478118 31479119 31480 31481Trusted Platform Module Library 31482 31483} 31484return TPM_RC_SUCCESS; 31485} 31486 31487Page 388 31488October 31, 2013 31489 31490Published 31491Copyright © TCG 2006-2013 31492 31493Family “2.0” 31494Level 00 Revision 00.99 31495 31496 Trusted Platform Module Library 31497 3149832.3 31499 31500Part 3: Commands 31501 31502TPM2_TestParms 31503 3150432.3.1 General Description 31505This command is used to check to see if specific combinations of algorithm parameters are supported. 31506The TPM will unmarshal the provided TPMT_PUBLIC_PARMS. If the parameters unmarshal correctly, 31507then the TPM will return TPM_RC_SUCCESS, indicating that the parameters are valid for the TPM. The 31508TPM will return the appropriate unmarshaling error if a parameter is not valid. 31509 31510Family “2.0” 31511Level 00 Revision 00.99 31512 31513Published 31514Copyright © TCG 2006-2013 31515 31516Page 389 31517October 31, 2013 31518 31519 Part 3: Commands 31520 31521Trusted Platform Module Library 31522 3152332.3.2 Command and Response 31524Table 195 — TPM2_TestParms Command 31525Type 31526 31527Name 31528 31529Description 31530 31531TPMI_ST_COMMAND_TAG 31532 31533tag 31534 31535UINT32 31536 31537commandSize 31538 31539TPM_CC 31540 31541commandCode 31542 31543TPM_CC_TestParms 31544 31545TPMT_PUBLIC_PARMS 31546 31547parameters 31548 31549algorithm parameters to be validated 31550 31551Table 196 — TPM2_TestParms Response 31552Type 31553 31554Name 31555 31556Description 31557 31558TPM_ST 31559 31560tag 31561 31562see clause 8 31563 31564UINT32 31565 31566responseSize 31567 31568TPM_RC 31569 31570responseCode 31571 31572Page 390 31573October 31, 2013 31574 31575TPM_RC 31576 31577Published 31578Copyright © TCG 2006-2013 31579 31580Family “2.0” 31581Level 00 Revision 00.99 31582 31583 Trusted Platform Module Library 31584 31585Part 3: Commands 31586 3158732.3.3 Detailed Actions 315881 315892 315903 315914 315925 315936 315947 315958 315969 3159710 3159811 3159912 3160013 3160114 31602 31603#include "InternalRoutines.h" 31604#include "TestParms_fp.h" 31605 31606TPM_RC 31607TPM2_TestParms( 31608TestParms_In 31609 31610*in 31611 31612// IN: input parameter list 31613 31614) 31615{ 31616// Input parameter is not reference in command action 31617in = NULL; 31618// The parameters are tested at unmarshal process. 31619// action 31620return TPM_RC_SUCCESS; 31621 31622We do nothing in command 31623 31624} 31625 31626Family “2.0” 31627Level 00 Revision 00.99 31628 31629Published 31630Copyright © TCG 2006-2013 31631 31632Page 391 31633October 31, 2013 31634 31635 Part 3: Commands 31636 3163733 31638 31639Trusted Platform Module Library 31640 31641Non-volatile Storage 31642 3164333.1 31644 31645Introduction 31646 31647The NV commands are used to create, update, read, and delete allocations of space in NV memory. 31648Before an Index may be used, it must be defined (TPM2_NV_DefineSpace()). 31649An Index may be modified if the proper write authorization is provided or read if the proper read 31650authorization is provided. Different controls are available for reading and writing. 31651An Index may have an Index-specific authValue and authPolicy. The authValue may be used to authorize 31652reading if TPMA_NV_AUTHREAD is SET and writing if TPMA_NV_AUTHREAD is SET. The authPolicy 31653may be used to authorize reading if TPMA_NV_POLICYREAD is SET and writing if 31654TPMA_NV_POLICYWRITE is SET. 31655TPMA_NV_PPREAD and TPMA_NV_PPWRITE indicate if reading or writing of the NV Index may be 31656authorized by platformAuth or platformPolicy. 31657TPMA_NV_OWNERREAD and TPMA_NV_OWNERWRITE indicate if reading or writing of the NV Index 31658may be authorized by ownerAuth or ownerPolicy. 31659If an operation on an NV index requires authorization, and the authHandle parameter is the handle of an 31660NV Index, then the nvIndex parameter must have the same value or the TPM will return 31661TPM_RC_NV_AUTHORIZATION. 31662NOTE 1 31663 31664This check ensures that the authorization that was provided is associated with the NV Index being 31665authorized. 31666 31667For creating an Index, ownerAuth may not be used if shEnable is CLEAR and platformAuth may not be 31668used if phEnableNV is CLEAR. 31669If an Index was defined using platformAuth, then that Index is not accessible when phEnableNV is 31670CLEAR. If an Index was defined using ownerAuth, then that Index is not accessible when shEnable is 31671CLEAR. 31672For read access control, any combination of TPMA_NV_PPREAD, TPMA_NV_OWNERREAD, 31673TPMA_NV_AUTHREAD, or TPMA_NV_POLICYREAD is allowed as long as at least one is SET. 31674For write access control, any combination of TPMA_NV_PPWRITE, TPMA_NV_OWNERWRITE, 31675TPMA_NV_AUTHWRITE, or TPMA_NV_POLICYWRITE is allowed as long as at least one is SET. 31676If an Index has been defined and not written, then any operation on the NV Index that requires read 31677authorization will fail (TPM_RC_NV_INITIALIZED). This check may be made before or after other 31678authorization checks but shall be performed before checking the NV Index authValue. An authorization 31679failure due to the NV Index not having been written shall not be logged by the dictionary attack logic. 31680If TPMA_NV_CLEAR_STCLEAR is SET, then the TPMA_NV_WRITTEN will be CLEAR on each 31681TPM2_Startup(TPM_SU_CLEAR). 31682TPMA_NV_CLEAR_STCLEAR 31683shall 31684not 31685be 31686SET 31687if 31688TPMA_NV_COUNTER is SET. 31689The 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 31690structure of the NV data. 31691Only one NV Index may be directly referenced in a command. 31692NOTE 2 31693 31694This means that, if authHandle references an NV Index, then nvIndex will have the same value. 31695However, this does not limit the number of changes that may occur as side effects. For example, any 31696number of NV Indexes might be relocated as a result of deleting or adding a NV Ind ex. 31697 31698Page 392 31699October 31, 2013 31700 31701Published 31702Copyright © TCG 2006-2013 31703 31704Family “2.0” 31705Level 00 Revision 00.99 31706 31707 Trusted Platform Module Library 31708 3170933.2 31710 31711Part 3: Commands 31712 31713NV Counters 31714 31715When an Index has the TPMA_NV_COUNTER attribute set, it behaves as a monotonic counter and may 31716only be updated using TPM2_NV_Increment(). 31717When an NV counter is created, the TPM shall initialize the 8-octet counter value with a number that is 31718greater than any count value for any NV counter on the TPM since the time of TPM manufacture. 31719An NV counter may be defined with the TPMA_NV_ORDERLY attribute to indicate that the NV Index is 31720expected to be modified at a high frequency and that the data is only required to persist when the TPM 31721goes through an orderly shutdown process. The TPM may update the counter value in RAM and 31722occasionally update the non-volatile version of the counter. An orderly shutdown is one occasion to 31723update the non-volatile count. If the difference between the volatile and non-volatile version of the counter 31724becomes as large as MAX_ORDERLY_COUNT, this shall be another occasion for updating the nonvolatile count. 31725Before an NV counter can be used, the TPM shall validate that the count is not less than a previously 31726reported value. If the TPMA_NV_ORDERLY attribute is not SET, or if the TPM experienced an orderly 31727shutdown, then the count is assumed to be correct. If the TPMA_NV_ORDERLY attribute is SET, and the 31728TPM shutdown was not orderly, then the TPM shall OR MAX_ORDERLY_COUNT to the contents of the 31729non-volatile counter and set that as the current count. 31730NOTE 1 31731 31732Because the TPM would have updated the NV Index if the difference between the count values was 31733equal to MAX_ORDERLY_COUNT + 1, the highest value that could have been in the NV Index is 31734MAX_ORDERLY_COUNT so it is safe to restore that value. 31735 31736NOTE 2 31737 31738The TPM may implement the RAM portion of the counter such that the effective value of the NV 31739counter is the sum of both the volatile and non-volatile parts. If so, then the TPM may initialize the 31740RAM version of the counter to MAX_ORDERLY_COUNT and no update of NV is necessary. 31741 31742NOTE 3 31743 31744When a new NV counter is created, the TPM may search all the counters to determine which has the 31745highest value. In this search, the TPM would use the sum of the non -volatile and RAM portions of 31746the counter. The RAM portion of the counter shall be properly initialized to reflect shutdown p rocess 31747(orderly or not) of the TPM. 31748 31749Family “2.0” 31750Level 00 Revision 00.99 31751 31752Published 31753Copyright © TCG 2006-2013 31754 31755Page 393 31756October 31, 2013 31757 31758 Part 3: Commands 31759 3176033.3 31761 31762Trusted Platform Module Library 31763 31764TPM2_NV_DefineSpace 31765 3176633.3.1 General Description 31767This command defines the attributes of an NV Index and causes the TPM to reserve space to hold the 31768data associated with the NV Index. If a definition already exists at the NV Index, the TPM will return 31769TPM_RC_NV_DEFINED. 31770The TPM will return TPM_RC_ATTRIBUTES if more 31771TPMA_NV_BITS, or TPMA_NV_EXTEND is SET in publicInfo. 31772NOTE 31773 31774than 31775 31776one 31777 31778of 31779 31780TPMA_NV_COUNTER, 31781 31782It is not required that any of these three attributes be set. 31783 31784The TPM shall return TPM_RC_ATTRIBUTES if TPMA_NV_WRITTEN, TPM_NV_READLOCKED, or 31785TPMA_NV_WRITELOCKED is SET. 31786If TPMA_NV_COUNTER or TPMA_NV_BITS is SET, then publicInfo→dataSize shall be set to eight (8) or 31787the TPM shall return TPM_RC_SIZE. 31788If TPMA_NV_EXTEND is SET, then publicInfo→dataSize shall match the digest size of the 31789publicInfo.nameAlg or the TPM shall return TPM_RC_SIZE. 31790If the NV Index is an ordinary Index and publicInfo→dataSize is larger than supported by the TPM 31791implementation then the TPM shall return TPM_RC_SIZE. 31792NOTE 31793 31794The limit for the data size may vary according to the type of the index. For example, if the index is 31795has TPMA_NV_ORDERLY SET, then the maximum size of an ordin ary NV Index may be less than 31796the size of an ordinary NV Index that has TPMA_NV_ORDERLY CLEAR. 31797 31798At least one of TPMA_NV_PPREAD, TPMA_NV_OWNERREAD, TPMA_NV_AUTHREAD, 31799TPMA_NV_POLICYREAD shall be SET or the TPM shall return TPM_RC_ATTRIBUTES. 31800 31801or 31802 31803At least one of TPMA_NV_PPWRITE, TPMA_NV_OWNERWRITE, TPMA_NV_AUTHWRITE, or 31804TPMA_NV_POLICYWRITE shall be SET or the TPM shall return TPM_RC_ATTRIBUTES. 31805If TPMA_NV_CLEAR_STCLEAR is SET, then TPMA_NV_COUNTER shall be CLEAR or the TPM shall 31806return TPM_RC_ATTRIBUTES. 31807If platformAuth/platformPolicy is used for authorization, then TPMA_NV_PLATFORMCREATE shall be 31808SET in publicInfo. If ownerAuth/ownerPolicy is used for authorization, TPMA_NV_PLATFORMCREATE 31809shall be CLEAR in publicInfo. If TPMA_NV_PLATFORMCREATE is not set correctly for the authorization, 31810the TPM shall return TPM_RC_ATTRIBUTES. 31811If TPMA_NV_POLICY_DELETE is SET, then the authorization shall be with platformAuth or the TPM 31812shall return TPM_RC_ATTRIBUTES. 31813If the implementation does not support TPM2_NV_Increment(), 31814TPM_RC_ATTRIBUTES if TPMA_NV_COUNTER is SET. 31815 31816the 31817 31818TPM 31819 31820shall 31821 31822return 31823 31824If the implementation does not support TPM2_NV_SetBits(), 31825TPM_RC_ATTRIBUTES if TPMA_NV_BITS is SET. 31826 31827the 31828 31829TPM 31830 31831shall 31832 31833return 31834 31835If the implementation does not support TPM2_NV_Extend(), 31836TPM_RC_ATTRIBUTES if TPMA_NV_EXTEND is SET. 31837 31838the 31839 31840TPM 31841 31842shall 31843 31844return 31845 31846If the implementation does not support TPM2_NV_UndefineSpaceSpecial(), the TPM shall return 31847TPM_RC_ATTRIBUTES if TPMA_NV_POLICY_DELETE is SET. 31848After the successful completion of this command, the NV Index exists but TPMA_NV_WRITTEN will be 31849CLEAR. Any access of the NV data will return TPM_RC_NV_UINITIALIZED. 31850 31851Page 394 31852October 31, 2013 31853 31854Published 31855Copyright © TCG 2006-2013 31856 31857Family “2.0” 31858Level 00 Revision 00.99 31859 31860 Trusted Platform Module Library 31861 31862Part 3: Commands 31863 31864In some implementations, an NV Index with the TPMA_NV_COUNTER attribute may require special TPM 31865resources that provide higher endurance than regular NV. For those implementations, if this command 31866fails because of lack of resources, the TPM will return TPM_RC_NV_SPACE. 31867The value of auth is saved in the created structure. The size of auth is limited to be no larger than the size 31868of the digest produced by the NV Index's nameAlg (TPM_RC_SIZE). 31869 31870Family “2.0” 31871Level 00 Revision 00.99 31872 31873Published 31874Copyright © TCG 2006-2013 31875 31876Page 395 31877October 31, 2013 31878 31879 Part 3: Commands 31880 31881Trusted Platform Module Library 31882 3188333.3.2 Command and Response 31884Table 197 — TPM2_NV_DefineSpace Command 31885Type 31886 31887Name 31888 31889Description 31890 31891TPMI_ST_COMMAND_TAG 31892 31893tag 31894 31895UINT32 31896 31897commandSize 31898 31899TPM_CC 31900 31901commandCode 31902 31903TPM_CC_NV_DefineSpace {NV} 31904 31905TPMI_RH_PROVISION 31906 31907@authHandle 31908 31909TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 31910Auth Index: 1 31911Auth Role: USER 31912 31913TPM2B_AUTH 31914 31915auth 31916 31917the authorization value 31918 31919TPM2B_NV_PUBLIC 31920 31921publicInfo 31922 31923the public parameters of the NV area 31924 31925Table 198 — TPM2_NV_DefineSpace Response 31926Type 31927 31928Name 31929 31930Description 31931 31932TPM_ST 31933 31934tag 31935 31936see clause 8 31937 31938UINT32 31939 31940responseSize 31941 31942TPM_RC 31943 31944responseCode 31945 31946Page 396 31947October 31, 2013 31948 31949Published 31950Copyright © TCG 2006-2013 31951 31952Family “2.0” 31953Level 00 Revision 00.99 31954 31955 Trusted Platform Module Library 31956 31957Part 3: Commands 31958 3195933.3.3 Detailed Actions 319601 319612 31962 31963#include "InternalRoutines.h" 31964#include "NV_DefineSpace_fp.h" 31965Error Returns 31966TPM_RC_NV_ATTRIBUTES 31967 31968attributes of the index are not consistent 31969 31970TPM_RC_NV_DEFINED 31971 31972index already exists 31973 31974TPM_RC_HIERARCHY 31975 31976for authorizations using TPM_RH_PLATFORM phEnable_NV is 31977clear. 31978 31979TPM_RC_NV_SPACE 31980 31981Insufficient space for the index 31982 31983TPM_RC_SIZE 31984 319853 319864 319875 319886 319897 319908 319919 3199210 3199311 3199412 3199513 3199614 3199715 3199816 3199917 3200018 3200119 3200220 3200321 3200422 3200523 3200624 3200725 3200826 3200927 3201028 3201129 3201230 3201331 3201432 3201533 3201634 3201735 3201836 3201937 3202038 3202139 3202240 3202341 3202442 3202543 3202644 32027 32028Meaning 32029 32030'auth->size' or 'publicInfo->authPolicy. size' is larger than the digest 32031size of 'publicInfo->nameAlg', or 'publicInfo->dataSize' is not 32032consistent with 'publicInfo->attributes'. 32033 32034TPM_RC 32035TPM2_NV_DefineSpace( 32036NV_DefineSpace_In 32037 32038*in 32039 32040// IN: input parameter list 32041 32042) 32043{ 32044TPM_RC 32045TPMA_NV 32046UINT16 32047 32048result; 32049attributes; 32050nameSize; 32051 32052nameSize = CryptGetHashDigestSize(in->publicInfo.t.nvPublic.nameAlg); 32053// Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE 32054// TPM_RC_NV_RATE or TPM_RC_SUCCESS. 32055result = NvIsAvailable(); 32056if(result != TPM_RC_SUCCESS) 32057return result; 32058// Input Validation 32059// If an index is being created by the owner and shEnable is 32060// clear, then we would not reach this point because ownerAuth 32061// can't be given when shEnable is CLEAR. However, if phEnable 32062// is SET but phEnableNV is CLEAR, we have to check here 32063if(in->authHandle == TPM_RH_PLATFORM && gc.phEnableNV == CLEAR) 32064return TPM_RC_HIERARCHY + RC_NV_DefineSpace_authHandle; 32065attributes = in->publicInfo.t.nvPublic.attributes; 32066//TPMS_NV_PUBLIC validation. 32067// Counters and bit fields must have a size of 8 32068if ( 32069(attributes.TPMA_NV_COUNTER == SET || attributes.TPMA_NV_BITS == SET) 32070&& (in->publicInfo.t.nvPublic.dataSize != 8)) 32071return TPM_RC_SIZE + RC_NV_DefineSpace_publicInfo; 32072// check that the authPolicy consistent with hash algorithm 32073if( 32074in->publicInfo.t.nvPublic.authPolicy.t.size != 0 32075&& in->publicInfo.t.nvPublic.authPolicy.t.size != nameSize) 32076return TPM_RC_SIZE + RC_NV_DefineSpace_publicInfo; 32077// make sure that the authValue is not too large 32078MemoryRemoveTrailingZeros(&in->auth); 32079if(in->auth.t.size > nameSize) 32080return TPM_RC_SIZE + RC_NV_DefineSpace_auth; 32081 32082Family “2.0” 32083Level 00 Revision 00.99 32084 32085Published 32086Copyright © TCG 2006-2013 32087 32088Page 397 32089October 31, 2013 32090 32091 Part 3: Commands 3209245 3209346 3209447 3209548 3209649 3209750 3209851 3209952 3210053 3210154 3210255 3210356 3210457 3210558 3210659 3210760 3210861 3210962 3211063 3211164 3211265 3211366 3211467 3211568 3211669 3211770 3211871 3211972 3212073 3212174 3212275 3212376 3212477 3212578 3212679 3212780 3212881 3212982 3213083 3213184 3213285 3213386 3213487 3213588 3213689 3213790 3213891 3213992 3214093 3214194 3214295 3214396 3214497 3214598 3214699 32147100 32148101 32149102 32150103 32151104 32152105 32153106 32154107 32155108 32156 32157Trusted Platform Module Library 32158 32159//TPMA_NV validation. 32160// Locks may not be SET and written cannot be SET 32161if( 32162attributes.TPMA_NV_WRITTEN == SET 32163|| attributes.TPMA_NV_WRITELOCKED == SET 32164|| attributes.TPMA_NV_READLOCKED == SET) 32165return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32166// There must be a way to read the index 32167if( 32168attributes.TPMA_NV_OWNERREAD == CLEAR 32169&& attributes.TPMA_NV_PPREAD == CLEAR 32170&& attributes.TPMA_NV_AUTHREAD == CLEAR 32171&& attributes.TPMA_NV_POLICYREAD == CLEAR) 32172return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32173// There must be a way to write the index 32174if( 32175attributes.TPMA_NV_OWNERWRITE == CLEAR 32176&& attributes.TPMA_NV_PPWRITE == CLEAR 32177&& attributes.TPMA_NV_AUTHWRITE == CLEAR 32178&& attributes.TPMA_NV_POLICYWRITE == CLEAR) 32179return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32180// Make sure that no attribute is used that is not supported by the proper 32181// command 32182#if CC_NV_Increment == NO 32183if( attributes.TPMA_NV_COUNTER == SET) 32184return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32185#endif 32186#if CC_NV_SetBits == NO 32187if( attributes.TPMA_NV_BITS == SET) 32188return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32189#endif 32190#if CC_NV_Extend == NO 32191if( attributes.TPMA_NV_EXTEND == SET) 32192return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32193#endif 32194#if CC_NV_UndefineSpaceSpecial == NO 32195if( attributes.TPMA_NV_POLICY_DELETE == SET) 32196return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32197#endif 32198// Can be COUNTER or BITS or EXTEND but not more than one 32199if( attributes.TPMA_NV_COUNTER == SET 32200&& attributes.TPMA_NV_BITS == SET) 32201return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32202if( 32203attributes.TPMA_NV_COUNTER == SET 32204&& attributes.TPMA_NV_EXTEND == SET) 32205return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32206if( 32207attributes.TPMA_NV_BITS == SET 32208&& attributes.TPMA_NV_EXTEND == SET) 32209return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32210// An index with TPMA_NV_CLEAR_STCLEAR can't be a counter 32211if( 32212attributes.TPMA_NV_CLEAR_STCLEAR == SET 32213&& attributes.TPMA_NV_COUNTER == SET) 32214return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32215// The index is allowed to have one of GLOBALLOCK or WRITEDEFINE SET 32216if( 32217attributes.TPMA_NV_GLOBALLOCK == SET 32218&& attributes.TPMA_NV_WRITEDEFINE == SET) 32219return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32220// Make sure that the creator of the index can delete the index 32221 32222Page 398 32223October 31, 2013 32224 32225Published 32226Copyright © TCG 2006-2013 32227 32228Family “2.0” 32229Level 00 Revision 00.99 32230 32231 Trusted Platform Module Library 32232109 32233110 32234111 32235112 32236113 32237114 32238115 32239116 32240117 32241118 32242119 32243120 32244121 32245122 32246123 32247124 32248125 32249126 32250127 32251128 32252129 32253130 32254131 32255132 32256133 32257134 32258135 32259136 32260137 32261138 32262139 32263140 32264141 32265142 32266143 32267144 32268 32269if( 32270 32271Part 3: Commands 32272 32273( 32274 32275in->publicInfo.t.nvPublic.attributes.TPMA_NV_PLATFORMCREATE == SET 32276&& in->authHandle == TPM_RH_OWNER 32277) 32278|| ( 32279in->publicInfo.t.nvPublic.attributes.TPMA_NV_PLATFORMCREATE == CLEAR 32280&& in->authHandle == TPM_RH_PLATFORM 32281) 32282) 32283return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_authHandle; 32284 32285// If TPMA_NV_POLICY_DELETE is SET, then the index must be defined by 32286// the platform 32287if( 32288in->publicInfo.t.nvPublic.attributes.TPMA_NV_POLICY_DELETE == SET 32289&& TPM_RH_PLATFORM != in->authHandle 32290) 32291return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32292// If the NV index is used as a PCR, the data size must match the digest 32293// size 32294if( 32295in->publicInfo.t.nvPublic.attributes.TPMA_NV_EXTEND == SET 32296&& in->publicInfo.t.nvPublic.dataSize != nameSize 32297) 32298return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32299// See if the index is already defined. 32300if(NvIsUndefinedIndex(in->publicInfo.t.nvPublic.nvIndex)) 32301return TPM_RC_NV_DEFINED; 32302// Internal Data Update 32303// define the space. A TPM_RC_NV_SPACE error may be returned at this point 32304result = NvDefineIndex(&in->publicInfo.t.nvPublic, &in->auth); 32305if(result != TPM_RC_SUCCESS) 32306return result; 32307return TPM_RC_SUCCESS; 32308} 32309 32310Family “2.0” 32311Level 00 Revision 00.99 32312 32313Published 32314Copyright © TCG 2006-2013 32315 32316Page 399 32317October 31, 2013 32318 32319 Part 3: Commands 32320 3232133.4 32322 32323Trusted Platform Module Library 32324 32325TPM2_NV_UndefineSpace 32326 3232733.4.1 General Description 32328This command removes an Index from the TPM. 32329If nvIndex is not defined, the TPM shall return TPM_RC_HANDLE. 32330If nvIndex references an Index that has its TPMA_NV_PLATFORMCREATE attribute SET, the TPM shall 32331return TPM_RC_NV_AUTHORITY unless platformAuth is provided. 32332NOTE 32333 32334An Index with TPMA_NV_PLATFORMCREATE CLEAR may be deleted with platformAuth as long as 32335shEnable is SET. If shEnable is CLEAR, indexes created using ownerAuth are not accessible even 32336for deletion by the platform. 32337 32338Page 400 32339October 31, 2013 32340 32341Published 32342Copyright © TCG 2006-2013 32343 32344Family “2.0” 32345Level 00 Revision 00.99 32346 32347 Trusted Platform Module Library 32348 32349Part 3: Commands 32350 3235133.4.2 Command and Response 32352Table 199 — TPM2_NV_UndefineSpace Command 32353Type 32354 32355Name 32356 32357Description 32358 32359TPMI_ST_COMMAND_TAG 32360 32361tag 32362 32363UINT32 32364 32365commandSize 32366 32367TPM_CC 32368 32369commandCode 32370 32371TPM_CC_NV_UndefineSpace {NV} 32372 32373TPMI_RH_PROVISION 32374 32375@authHandle 32376 32377TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 32378Auth Index: 1 32379Auth Role: USER 32380 32381TPMI_RH_NV_INDEX 32382 32383nvIndex 32384 32385the NV Index to remove from NV space 32386Auth Index: None 32387 32388Table 200 — TPM2_NV_UndefineSpace Response 32389Type 32390 32391Name 32392 32393Description 32394 32395TPM_ST 32396 32397tag 32398 32399see clause 8 32400 32401UINT32 32402 32403responseSize 32404 32405TPM_RC 32406 32407responseCode 32408 32409Family “2.0” 32410Level 00 Revision 00.99 32411 32412Published 32413Copyright © TCG 2006-2013 32414 32415Page 401 32416October 31, 2013 32417 32418 Part 3: Commands 32419 32420Trusted Platform Module Library 32421 3242233.4.3 Detailed Actions 324231 324242 32425 32426#include "InternalRoutines.h" 32427#include "NV_UndefineSpace_fp.h" 32428Error Returns 32429TPM_RC_ATTRIBUTES 32430 32431TPMA_NV_POLICY_DELETE is SET in the Index referenced by 32432nvIndex so this command may not be used to delete this Index (see 32433TPM2_NV_UndefineSpaceSpecial()) 32434 32435TPM_RC_NV_AUTHORIZATION 324363 324374 324385 324396 324407 324418 324429 3244310 3244411 3244512 3244613 3244714 3244815 3244916 3245017 3245118 3245219 3245320 3245421 3245522 3245623 3245724 3245825 3245926 3246027 3246128 3246229 3246330 3246431 3246532 3246633 3246734 3246835 3246936 3247037 3247138 32472 32473Meaning 32474 32475attempt to use ownerAuth to delete an index created by the platform 32476 32477TPM_RC 32478TPM2_NV_UndefineSpace( 32479NV_UndefineSpace_In *in 32480 32481// IN: input parameter list 32482 32483) 32484{ 32485TPM_RC 32486NV_INDEX 32487 32488result; 32489nvIndex; 32490 32491// The command needs NV update. Check if NV is available. 32492// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 32493// this point 32494result = NvIsAvailable(); 32495if(result != TPM_RC_SUCCESS) return result; 32496// Input Validation 32497// Get NV index info 32498NvGetIndexInfo(in->nvIndex, &nvIndex); 32499// This command can't be used to delete an index with TPMA_NV_POLICY_DELETE SET 32500if(SET == nvIndex.publicArea.attributes.TPMA_NV_POLICY_DELETE) 32501return TPM_RC_ATTRIBUTES + RC_NV_UndefineSpace_nvIndex; 32502// The owner may only delete an index that was defined with ownerAuth. The 32503// platform may delete an index that was created with either auth. 32504if( 32505in->authHandle == TPM_RH_OWNER 32506&& nvIndex.publicArea.attributes.TPMA_NV_PLATFORMCREATE == SET) 32507return TPM_RC_NV_AUTHORIZATION; 32508// Internal Data Update 32509// Call implementation dependent internal routine to delete NV index 32510NvDeleteEntity(in->nvIndex); 32511return TPM_RC_SUCCESS; 32512} 32513 32514Page 402 32515October 31, 2013 32516 32517Published 32518Copyright © TCG 2006-2013 32519 32520Family “2.0” 32521Level 00 Revision 00.99 32522 32523 Trusted Platform Module Library 32524 3252533.5 32526 32527Part 3: Commands 32528 32529TPM2_NV_UndefineSpaceSpecial 32530 3253133.5.1 General Description 32532This command allows removal of a platform-created NV Index that has TPMA_NV_POLICY_DELETE 32533SET. 32534This command requires that the policy of the NV Index be satisfied before the NV Index may be deleted. 32535Because administrative role is required, the policy must contain a command that sets the policy command 32536code to TPM_CC_NV_UndefineSpaceSpecial. This indicates that the policy that is being used is a policy 32537that is for this command, and not a policy that would approve another use. That is, authority to use an 32538object does not grant authority to undefined the object. 32539If nvIndex is not defined, the TPM shall return TPM_RC_HANDLE. 32540If 32541nvIndex 32542references 32543an 32544Index 32545that 32546has 32547its 32548TPMA_NV_PLATFORMCREATE 32549TPMA_NV_POLICY_DELETE attribute CLEAR, the TPM shall return TPM_RC_NV_ATTRIBUTES. 32550NOTE 32551 32552or 32553 32554An 32555Index 32556with 32557TPMA_NV_PLATFORMCREATE 32558CLEAR 32559may 32560be 32561deleted 32562with 32563TPM2_UndefineSpace()as long as shEnable is SET. If shEnable is CLEAR, indexes created using 32564ownerAuth are not accessible even for deletion by the platform . 32565 32566Family “2.0” 32567Level 00 Revision 00.99 32568 32569Published 32570Copyright © TCG 2006-2013 32571 32572Page 403 32573October 31, 2013 32574 32575 Part 3: Commands 32576 32577Trusted Platform Module Library 32578 3257933.5.2 Command and Response 32580Table 201 — TPM2_NV_UndefineSpaceSpecial Command 32581Type 32582 32583Name 32584 32585Description 32586 32587TPMI_ST_COMMAND_TAG 32588 32589tag 32590 32591UINT32 32592 32593commandSize 32594 32595TPM_CC 32596 32597commandCode 32598 32599TPM_CC_NV_UndefineSpaceSpecial {NV} 32600 32601TPMI_RH_NV_INDEX 32602 32603@nvIndex 32604 32605Index to be deleted 32606Auth Index: 1 32607Auth Role: ADMIN 32608 32609TPMI_RH_PLATFORM 32610 32611@platform 32612 32613TPM_RH_PLATFORM + {PP} 32614Auth Index: 2 32615Auth Role: USER 32616 32617Table 202 — TPM2_NV_UndefineSpaceSpecial Response 32618Type 32619 32620Name 32621 32622Description 32623 32624TPM_ST 32625 32626tag 32627 32628see clause 8 32629 32630UINT32 32631 32632responseSize 32633 32634TPM_RC 32635 32636responseCode 32637 32638Page 404 32639October 31, 2013 32640 32641Published 32642Copyright © TCG 2006-2013 32643 32644Family “2.0” 32645Level 00 Revision 00.99 32646 32647 Trusted Platform Module Library 32648 32649Part 3: Commands 32650 3265133.5.3 Detailed Actions 326521 326532 32654 32655#include "InternalRoutines.h" 32656#include "NV_UndefineSpaceSpecial_fp.h" 32657Error Returns 32658TPM_RC_ATTRIBUTES 32659 326603 326614 326625 326636 326647 326658 326669 3266710 3266811 3266912 3267013 3267114 3267215 3267316 3267417 3267518 3267619 3267720 3267821 3267922 3268023 3268124 3268225 3268326 3268427 3268528 3268629 3268730 3268831 3268932 3269033 32691 32692Meaning 32693TPMA_NV_POLICY_DELETE is not SET in the Index referenced by 32694nvIndex 32695 32696TPM_RC 32697TPM2_NV_UndefineSpaceSpecial( 32698NV_UndefineSpaceSpecial_In *in 32699 32700// IN: input parameter list 32701 32702) 32703{ 32704TPM_RC 32705NV_INDEX 32706 32707result; 32708nvIndex; 32709 32710// The command needs NV update. Check if NV is available. 32711// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 32712// this point 32713result = NvIsAvailable(); 32714if(result != TPM_RC_SUCCESS) 32715return result; 32716// Input Validation 32717// Get NV index info 32718NvGetIndexInfo(in->nvIndex, &nvIndex); 32719// This operation only applies when the TPMA_NV_POLICY_DELETE attribute is SET 32720if(CLEAR == nvIndex.publicArea.attributes.TPMA_NV_POLICY_DELETE) 32721return TPM_RC_ATTRIBUTES + RC_NV_UndefineSpaceSpecial_nvIndex; 32722// Internal Data Update 32723// Call implementation dependent internal routine to delete NV index 32724NvDeleteEntity(in->nvIndex); 32725return TPM_RC_SUCCESS; 32726} 32727 32728Family “2.0” 32729Level 00 Revision 00.99 32730 32731Published 32732Copyright © TCG 2006-2013 32733 32734Page 405 32735October 31, 2013 32736 32737 Part 3: Commands 32738 3273933.6 32740 32741Trusted Platform Module Library 32742 32743TPM2_NV_ReadPublic 32744 3274533.6.1 General Description 32746This command is used to read the public area and Name of an NV Index. The public area of an Index is 32747not privacy-sensitive and no authorization is required to read this data. 32748 32749Page 406 32750October 31, 2013 32751 32752Published 32753Copyright © TCG 2006-2013 32754 32755Family “2.0” 32756Level 00 Revision 00.99 32757 32758 Trusted Platform Module Library 32759 32760Part 3: Commands 32761 3276233.6.2 Command and Response 32763Table 203 — TPM2_NV_ReadPublic Command 32764Type 32765 32766Name 32767 32768Description 32769 32770TPMI_ST_COMMAND_TAG 32771 32772tag 32773 32774UINT32 32775 32776commandSize 32777 32778TPM_CC 32779 32780commandCode 32781 32782TPM_CC_NV_ReadPublic 32783 32784TPMI_RH_NV_INDEX 32785 32786nvIndex 32787 32788the NV Index 32789Auth Index: None 32790 32791Table 204 — TPM2_NV_ReadPublic Response 32792Type 32793 32794Name 32795 32796Description 32797 32798TPM_ST 32799 32800tag 32801 32802see clause 8 32803 32804UINT32 32805 32806responseSize 32807 32808TPM_RC 32809 32810responseCode 32811 32812TPM2B_NV_PUBLIC 32813 32814nvPublic 32815 32816the public area of the NV Index 32817 32818TPM2B_NAME 32819 32820nvName 32821 32822the Name of the nvIndex 32823 32824Family “2.0” 32825Level 00 Revision 00.99 32826 32827Published 32828Copyright © TCG 2006-2013 32829 32830Page 407 32831October 31, 2013 32832 32833 Part 3: Commands 32834 32835Trusted Platform Module Library 32836 3283733.6.3 Detailed Actions 328381 328392 328403 328414 328425 328436 328447 328458 328469 3284710 3284811 3284912 3285013 3285114 3285215 3285316 3285417 3285518 3285619 3285720 3285821 3285922 3286023 32861 32862#include "InternalRoutines.h" 32863#include "NV_ReadPublic_fp.h" 32864 32865TPM_RC 32866TPM2_NV_ReadPublic( 32867NV_ReadPublic_In 32868NV_ReadPublic_Out 32869 32870*in, 32871*out 32872 32873// IN: input parameter list 32874// OUT: output parameter list 32875 32876) 32877{ 32878NV_INDEX 32879 32880nvIndex; 32881 32882// Command Output 32883// Get NV index info 32884NvGetIndexInfo(in->nvIndex, &nvIndex); 32885// Copy data to output 32886out->nvPublic.t.nvPublic = nvIndex.publicArea; 32887// Compute NV name 32888out->nvName.t.size = NvGetName(in->nvIndex, &out->nvName.t.name); 32889return TPM_RC_SUCCESS; 32890} 32891 32892Page 408 32893October 31, 2013 32894 32895Published 32896Copyright © TCG 2006-2013 32897 32898Family “2.0” 32899Level 00 Revision 00.99 32900 32901 Trusted Platform Module Library 32902 3290333.7 32904 32905Part 3: Commands 32906 32907TPM2_NV_Write 32908 3290933.7.1 General Description 32910This command writes a value to an area in NV memory that was previously defined by 32911TPM2_NV_DefineSpace(). 32912Proper authorizations are required for this command as determined by TPMA_NV_PPWRITE; 32913TPMA_NV_OWNERWRITE; TPMA_NV_AUTHWRITE; and, if TPMA_NV_POLICY_WRITE is SET, the 32914authPolicy of the NV Index. 32915If the TPMA_NV_WRITELOCKED attribute of the NV Index is SET, then the TPM shall return 32916TPM_RC_NV_LOCKED. 32917NOTE 1 32918 32919If authorization sessions are present, they are checked before checks to see if writes to the NV 32920Index are locked. 32921 32922If TPMA_NV_COUNTER, TPMA_NV_BITS or TPMA_NV_EXTEND of the NV Index is SET, then the 32923TPM shall return TPM_RC_NV_ATTRIBUTE. 32924If the size of the data parameter plus the offset parameter adds to a value that is greater than the size of 32925the NV Index data, the TPM shall return TPM_RC_NV_RANGE and not write any data to the NV Index. 32926If the TPMA_NV_WRITEALL attribute of the NV Index is SET, then the TPM shall return 32927TPM_RC_NV_RANGE if the size of the data parameter of the command is not the same as the data field 32928of the NV Index. 32929If all checks succeed, the TPM will merge the data.size octets of data.buffer value into the nvIndex→data 32930starting at nvIndex→data[offset]. If the NV memory is implemented with a technology that has endurance 32931limitations, the TPM shall check that the merged data is different from the current contents of the NV 32932Index and only perform a write to NV memory if they differ. 32933After successful completion of this command, TPMA_NV_WRITTEN for the NV Index will be SET. 32934NOTE 2 32935 32936Once SET, TPMA_NV_WRITTEN remains SET until the NV Index is undefined or the NV Index is 32937cleared. 32938 32939Family “2.0” 32940Level 00 Revision 00.99 32941 32942Published 32943Copyright © TCG 2006-2013 32944 32945Page 409 32946October 31, 2013 32947 32948 Part 3: Commands 32949 32950Trusted Platform Module Library 32951 3295233.7.2 Command and Response 32953Table 205 — TPM2_NV_Write Command 32954Type 32955 32956Name 32957 32958Description 32959 32960TPMI_ST_COMMAND_TAG 32961 32962tag 32963 32964UINT32 32965 32966commandSize 32967 32968TPM_CC 32969 32970commandCode 32971 32972TPM_CC_NV_Write {NV} 32973 32974TPMI_RH_NV_AUTH 32975 32976@authHandle 32977 32978handle indicating the source of the authorization value 32979Auth Index: 1 32980Auth Role: USER 32981 32982TPMI_RH_NV_INDEX 32983 32984nvIndex 32985 32986the NV Index of the area to write 32987Auth Index: None 32988 32989TPM2B_MAX_NV_BUFFER 32990 32991data 32992 32993the data to write 32994 32995UINT16 32996 32997offset 32998 32999the offset into the NV Area 33000 33001Table 206 — TPM2_NV_Write Response 33002Type 33003 33004Name 33005 33006Description 33007 33008TPM_ST 33009 33010tag 33011 33012see clause 8 33013 33014UINT32 33015 33016responseSize 33017 33018TPM_RC 33019 33020responseCode 33021 33022Page 410 33023October 31, 2013 33024 33025Published 33026Copyright © TCG 2006-2013 33027 33028Family “2.0” 33029Level 00 Revision 00.99 33030 33031 Trusted Platform Module Library 33032 33033Part 3: Commands 33034 3303533.7.3 Detailed Actions 330361 330372 330383 33039 33040#include "InternalRoutines.h" 33041#include "NV_Write_fp.h" 33042#include "NV_spt_fp.h" 33043Error Returns 33044TPM_RC_ATTRIBUTES 33045 33046Index referenced by nvIndex has either TPMA_NV_BITS, 33047TPMA_NV_COUNTER, or TPMA_NV_EVENT attribute SET 33048 33049TPM_RC_NV_AUTHORIZATION 33050 33051the authorization was valid but the authorizing entity (authHandle) is 33052not allowed to write to the Index referenced by nvIndex 33053 33054TPM_RC_NV_LOCKED 33055 33056Index referenced by nvIndex is write locked 33057 33058TPM_RC_NV_RANGE 33059 330604 330615 330626 330637 330648 330659 3306610 3306711 3306812 3306913 3307014 3307115 3307216 3307317 3307418 3307519 3307620 3307721 3307822 3307923 3308024 3308125 3308226 3308327 3308428 3308529 3308630 3308731 3308832 3308933 3309034 3309135 3309236 3309337 3309438 3309539 3309640 3309741 3309842 3309943 3310044 3310145 33102 33103Meaning 33104 33105if TPMA_NV_WRITEALL is SET then the write is not the size of the 33106Index referenced by nvIndex; otherwise, the write extends beyond the 33107limits of the Index 33108 33109TPM_RC 33110TPM2_NV_Write( 33111NV_Write_In 33112 33113*in 33114 33115// IN: input parameter list 33116 33117) 33118{ 33119NV_INDEX 33120TPM_RC 33121 33122nvIndex; 33123result; 33124 33125// Input Validation 33126// Get NV index info 33127NvGetIndexInfo(in->nvIndex, &nvIndex); 33128// common access checks. NvWrtieAccessChecks() may return 33129// TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED 33130result = NvWriteAccessChecks(in->authHandle, in->nvIndex); 33131if(result != TPM_RC_SUCCESS) 33132return result; 33133// Bits index, extend index or counter index may not be updated by 33134// TPM2_NV_Write 33135if( 33136nvIndex.publicArea.attributes.TPMA_NV_COUNTER == SET 33137|| nvIndex.publicArea.attributes.TPMA_NV_BITS == SET 33138|| nvIndex.publicArea.attributes.TPMA_NV_EXTEND == SET) 33139return TPM_RC_ATTRIBUTES; 33140// Too much data 33141if((in->data.t.size + in->offset) > nvIndex.publicArea.dataSize) 33142return TPM_RC_NV_RANGE; 33143// If this index requires a full sized write, make sure that input range is 33144// full sized 33145if( 33146nvIndex.publicArea.attributes.TPMA_NV_WRITEALL == SET 33147&& in->data.t.size < nvIndex.publicArea.dataSize) 33148return TPM_RC_NV_RANGE; 33149// Internal Data Update 33150// Perform the write. This called routine will SET the TPMA_NV_WRITTEN 33151// attribute if it has not already been SET. If NV isn't available, an error 33152// will be returned. 33153return NvWriteIndexData(in->nvIndex, &nvIndex, in->offset, 33154 33155Family “2.0” 33156Level 00 Revision 00.99 33157 33158Published 33159Copyright © TCG 2006-2013 33160 33161Page 411 33162October 31, 2013 33163 33164 Part 3: Commands 3316546 3316647 3316748 33168 33169Trusted Platform Module Library 33170in->data.t.size, in->data.t.buffer); 33171 33172} 33173 33174Page 412 33175October 31, 2013 33176 33177Published 33178Copyright © TCG 2006-2013 33179 33180Family “2.0” 33181Level 00 Revision 00.99 33182 33183 Trusted Platform Module Library 33184 3318533.8 33186 33187Part 3: Commands 33188 33189TPM2_NV_Increment 33190 3319133.8.1 General Description 33192This command is used to increment the value in an NV Index that has TPMA_NV_COUNTER SET. The 33193data value of the NV Index is incremented by one. 33194NOTE 1 33195 33196The NV Index counter is an unsigned value. 33197 33198If TPMA_NV_COUNTER 33199TPM_RC_ATTRIBUTES. 33200 33201is 33202 33203not 33204 33205SET 33206 33207in 33208 33209the 33210 33211indicated 33212 33213NV 33214 33215Index, 33216 33217the 33218 33219TPM 33220 33221shall 33222 33223return 33224 33225If TPMA_NV_WRITELOCKED is SET, the TPM shall return TPM_RC_NV_LOCKED. 33226If TPMA_NV_WRITTEN is CLEAR, it will be SET. 33227If TPMA_NV_ORDERLY is SET, and the difference between the volatile and non-volatile versions of this 33228field is greater than MAX_ORDERLY_COUNT, then the non-volatile version of the counter is updated. 33229NOTE 2 33230 33231If a TPM implements TPMA_NV_ORDERLY and an Index is defined with TPMA_NV_ORDERLY and 33232TPM_NV_COUNTER both SET, then in the Event of a non-orderly shutdown, the non-volatile value 33233for the counter Index will be advanced by MAX_ORDERLY_COUNT at the next TPM2_Startup(). 33234 33235NOTE 3 33236 33237An allowed implementation would keep a counter value in NV and a resettable counter in RAM. The 33238reported value of the NV Index would be the sum of the two values. When the RAM count increments 33239past the maximum allowed value (MAX_ORDERLY_COUNT), the non-volatile version of the count is 33240updated with the sum of the values and the RAM count is reset to zero. 33241 33242Family “2.0” 33243Level 00 Revision 00.99 33244 33245Published 33246Copyright © TCG 2006-2013 33247 33248Page 413 33249October 31, 2013 33250 33251 Part 3: Commands 33252 33253Trusted Platform Module Library 33254 3325533.8.2 Command and Response 33256Table 207 — TPM2_NV_Increment Command 33257Type 33258 33259Name 33260 33261Description 33262 33263TPMI_ST_COMMAND_TAG 33264 33265tag 33266 33267UINT32 33268 33269commandSize 33270 33271TPM_CC 33272 33273commandCode 33274 33275TPM_CC_NV_Increment {NV} 33276 33277TPMI_RH_NV_AUTH 33278 33279@authHandle 33280 33281handle indicating the source of the authorization value 33282Auth Index: 1 33283Auth Role: USER 33284 33285TPMI_RH_NV_INDEX 33286 33287nvIndex 33288 33289the NV Index to increment 33290Auth Index: None 33291 33292Table 208 — TPM2_NV_Increment Response 33293Type 33294 33295Name 33296 33297Description 33298 33299TPM_ST 33300 33301tag 33302 33303see clause 8 33304 33305UINT32 33306 33307responseSize 33308 33309TPM_RC 33310 33311responseCode 33312 33313Page 414 33314October 31, 2013 33315 33316Published 33317Copyright © TCG 2006-2013 33318 33319Family “2.0” 33320Level 00 Revision 00.99 33321 33322 Trusted Platform Module Library 33323 33324Part 3: Commands 33325 3332633.8.3 Detailed Actions 333271 333282 333293 33330 33331#include "InternalRoutines.h" 33332#include "NV_Increment_fp.h" 33333#include "NV_spt_fp.h" 33334Error Returns 33335TPM_RC_ATTRIBUTES 33336 33337NV index is not a counter 33338 33339TPM_RC_NV_AUTHORIZATION 33340 33341authorization failure 33342 33343TPM_RC_NV_LOCKED 333444 333455 333466 333477 333488 333499 3335010 3335111 3335212 3335313 3335414 3335515 3335616 3335717 3335818 3335919 3336020 3336121 3336222 3336323 3336424 3336525 3336626 3336727 3336828 3336929 3337030 3337131 3337232 3337333 3337434 3337535 3337636 3337737 3337838 3337939 3338040 3338141 3338242 3338343 3338444 3338545 3338646 3338747 3338848 3338949 3339050 3339151 33392 33393Meaning 33394 33395Index is write locked 33396 33397TPM_RC 33398TPM2_NV_Increment( 33399NV_Increment_In 33400 33401*in 33402 33403// IN: input parameter list 33404 33405) 33406{ 33407TPM_RC 33408NV_INDEX 33409UINT64 33410 33411result; 33412nvIndex; 33413countValue; 33414 33415// Input Validation 33416// Common access checks, a TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED 33417// error may be returned at this point 33418result = NvWriteAccessChecks(in->authHandle, in->nvIndex); 33419if(result != TPM_RC_SUCCESS) 33420return result; 33421// Get NV index info 33422NvGetIndexInfo(in->nvIndex, &nvIndex); 33423// Make sure that this is a counter 33424if(nvIndex.publicArea.attributes.TPMA_NV_COUNTER != SET) 33425return TPM_RC_ATTRIBUTES + RC_NV_Increment_nvIndex; 33426// Internal Data Update 33427// If counter index is not been written, initialize it 33428if(nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR) 33429countValue = NvInitialCounter(); 33430else 33431// Read NV data in native format for TPM CPU. 33432NvGetIntIndexData(in->nvIndex, &nvIndex, &countValue); 33433// Do the increment 33434countValue++; 33435// If this is an orderly counter that just rolled over, need to be able to 33436// write to NV to proceed. This check is done here, because NvWriteIndexData() 33437// does not see if the update is for counter rollover. 33438if( 33439nvIndex.publicArea.attributes.TPMA_NV_ORDERLY == SET 33440&& (countValue & MAX_ORDERLY_COUNT) == 0) 33441{ 33442result = NvIsAvailable(); 33443if(result != TPM_RC_SUCCESS) 33444return result; 33445// Need to force an NV update 33446 33447Family “2.0” 33448Level 00 Revision 00.99 33449 33450Published 33451Copyright © TCG 2006-2013 33452 33453Page 415 33454October 31, 2013 33455 33456 Part 3: Commands 3345752 3345853 3345954 3346055 3346156 3346257 3346358 3346459 3346560 33466 33467Trusted Platform Module Library 33468 33469g_updateNV = TRUE; 33470} 33471// Write NV data back. A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may 33472// be returned at this point. If necessary, this function will set the 33473// TPMA_NV_WRITTEN attribute 33474return NvWriteIndexData(in->nvIndex, &nvIndex, 0, 8, &countValue); 33475} 33476 33477Page 416 33478October 31, 2013 33479 33480Published 33481Copyright © TCG 2006-2013 33482 33483Family “2.0” 33484Level 00 Revision 00.99 33485 33486 Trusted Platform Module Library 33487 3348833.9 33489 33490Part 3: Commands 33491 33492TPM2_NV_Extend 33493 3349433.9.1 General Description 33495This command extends a value to an area in NV memory that was previously defined by 33496TPM2_NV_DefineSpace. 33497If TPMA_NV_EXTEND is not SET, then the TPM shall return TPM_RC_ATTRIBUTES. 33498Proper write authorizations are required for this command as determined by TPMA_NV_PPWRITE, 33499TPMA_NV_OWNERWRITE, TPMA_NV_AUTHWRITE, and the authPolicy of the NV Index. 33500After successful completion of this command, TPMA_NV_WRITTEN for the NV Index will be SET. 33501NOTE 1 33502 33503Once SET, TPMA_NV_WRITTEN remains SET until the NV Index is undefined or the NV Index is 33504cleared. 33505 33506If the TPMA_NV_WRITELOCKED attribute of the NV Index is SET, then the TPM shall return 33507TPM_RC_NV_LOCKED. 33508NOTE 2 33509 33510If authorization sessions are present, they are checked before checks to see if writes to the NV 33511Index are locked. 33512 33513The data.buffer parameter may be larger than the defined size of the NV Index. 33514The Index will be updated by: 33515 33516nvIndex→datanew ≔ HnameAkg(nvIndex→dataold || data.buffer) 33517 33518(39) 33519 33520where 33521 33522HnameAkg() 33523 33524the hash algorithm indicated in nvIndex→nameAlg 33525 33526nvIndex→data 33527 33528the value of the data field in the NV Index 33529 33530data.buffer 33531 33532the data buffer of the command parameter 33533 33534NOTE 3 33535 33536If TPMA_NV_WRITTEN is CLEAR, then nvIndex→data is a Zero Digest. 33537 33538Family “2.0” 33539Level 00 Revision 00.99 33540 33541Published 33542Copyright © TCG 2006-2013 33543 33544Page 417 33545October 31, 2013 33546 33547 Part 3: Commands 33548 33549Trusted Platform Module Library 33550 3355133.9.2 Command and Response 33552Table 209 — TPM2_NV_Extend Command 33553Type 33554 33555Name 33556 33557Description 33558 33559TPMI_ST_COMMAND_TAG 33560 33561tag 33562 33563UINT32 33564 33565commandSize 33566 33567TPM_CC 33568 33569commandCode 33570 33571TPM_CC_NV_Extend {NV} 33572 33573TPMI_RH_NV_AUTH 33574 33575@authHandle 33576 33577handle indicating the source of the authorization value 33578Auth Index: 1 33579Auth Role: USER 33580 33581TPMI_RH_NV_INDEX 33582 33583nvIndex 33584 33585the NV Index to extend 33586Auth Index: None 33587 33588TPM2B_MAX_NV_BUFFER 33589 33590data 33591 33592the data to extend 33593 33594Table 210 — TPM2_NV_Extend Response 33595Type 33596 33597Name 33598 33599Description 33600 33601TPM_ST 33602 33603tag 33604 33605see clause 8 33606 33607UINT32 33608 33609responseSize 33610 33611TPM_RC 33612 33613responseCode 33614 33615Page 418 33616October 31, 2013 33617 33618Published 33619Copyright © TCG 2006-2013 33620 33621Family “2.0” 33622Level 00 Revision 00.99 33623 33624 Trusted Platform Module Library 33625 33626Part 3: Commands 33627 3362833.9.3 Detailed Actions 336291 336302 336313 33632 33633#include "InternalRoutines.h" 33634#include "NV_Extend_fp.h" 33635#include "NV_spt_fp.h" 33636Error Returns 33637TPM_RC_ATTRIBUTES 33638 33639the TPMA_NV_EXTEND attribute is not SET in the Index referenced 33640by nvIndex 33641 33642TPM_RC_NV_AUTHORIZATION 33643 33644the authorization was valid but the authorizing entity (authHandle) is 33645not allowed to write to the Index referenced by nvIndex 33646 33647TPM_RC_NV_LOCKED 336484 336495 336506 336517 336528 336539 3365410 3365511 3365612 3365713 3365814 3365915 3366016 3366117 3366218 3366319 3366420 3366521 3366622 3366723 3366824 3366925 3367026 3367127 3367228 3367329 3367430 3367531 3367632 3367733 3367834 3367935 3368036 3368137 3368238 3368339 3368440 3368541 3368642 3368743 3368844 3368945 3369046 3369147 3369248 3369349 33694 33695Meaning 33696 33697the Index referenced by nvIndex is locked for writing 33698 33699TPM_RC 33700TPM2_NV_Extend( 33701NV_Extend_In 33702 33703*in 33704 33705// IN: input parameter list 33706 33707) 33708{ 33709TPM_RC 33710NV_INDEX 33711 33712result; 33713nvIndex; 33714 33715TPM2B_DIGEST 33716TPM2B_DIGEST 33717HASH_STATE 33718 33719oldDigest; 33720newDigest; 33721hashState; 33722 33723// Input Validation 33724// Common access checks, NvWriteAccessCheck() may return TPM_RC_NV_AUTHORIZATION 33725// or TPM_RC_NV_LOCKED 33726result = NvWriteAccessChecks(in->authHandle, in->nvIndex); 33727if(result != TPM_RC_SUCCESS) 33728return result; 33729// Get NV index info 33730NvGetIndexInfo(in->nvIndex, &nvIndex); 33731// Make sure that this is an extend index 33732if(nvIndex.publicArea.attributes.TPMA_NV_EXTEND != SET) 33733return TPM_RC_ATTRIBUTES + RC_NV_Extend_nvIndex; 33734// If the Index is not-orderly, or if this is the first write, NV will 33735// need to be updated. 33736if( 33737nvIndex.publicArea.attributes.TPMA_NV_ORDERLY == CLEAR 33738|| nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR) 33739{ 33740// Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE 33741// TPM_RC_NV_RATE or TPM_RC_SUCCESS. 33742result = NvIsAvailable(); 33743if(result != TPM_RC_SUCCESS) 33744return result; 33745} 33746// Internal Data Update 33747// Perform the write. 33748oldDigest.t.size = CryptGetHashDigestSize(nvIndex.publicArea.nameAlg); 33749if(nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == SET) 33750{ 33751NvGetIndexData(in->nvIndex, &nvIndex, 0, 33752 33753Family “2.0” 33754Level 00 Revision 00.99 33755 33756Published 33757Copyright © TCG 2006-2013 33758 33759Page 419 33760October 31, 2013 33761 33762 Part 3: Commands 3376350 3376451 3376552 3376653 3376754 3376855 3376956 3377057 3377158 3377259 3377360 3377461 3377562 3377663 3377764 3377865 3377966 3378067 3378168 3378269 3378370 3378471 3378572 33786 33787Trusted Platform Module Library 33788 33789oldDigest.t.size, oldDigest.t.buffer); 33790} 33791else 33792{ 33793MemorySet(oldDigest.t.buffer, 0, oldDigest.t.size); 33794} 33795// Start hash 33796newDigest.t.size = CryptStartHash(nvIndex.publicArea.nameAlg, &hashState); 33797// Adding old digest 33798CryptUpdateDigest2B(&hashState, &oldDigest.b); 33799// Adding new data 33800CryptUpdateDigest2B(&hashState, &in->data.b); 33801// Complete hash 33802CryptCompleteHash2B(&hashState, &newDigest.b); 33803// Write extended hash back. 33804// Note, this routine will SET the TPMA_NV_WRITTEN attribute if necessary 33805return NvWriteIndexData(in->nvIndex, &nvIndex, 0, 33806newDigest.t.size, newDigest.t.buffer); 33807} 33808 33809Page 420 33810October 31, 2013 33811 33812Published 33813Copyright © TCG 2006-2013 33814 33815Family “2.0” 33816Level 00 Revision 00.99 33817 33818 Trusted Platform Module Library 33819 33820Part 3: Commands 33821 3382233.10 TPM2_NV_SetBits 3382333.10.1 33824 33825General Description 33826 33827This command is used to SET bits in an NV Index that was created as a bit field. Any number of bits from 338280 to 64 may be SET. The contents of data are ORed with the current contents of the NV Index starting at 33829offset. The checks on data and offset are the same as for TPM2_NV_Write. 33830If TPMA_NV_WRITTEN is not SET, then, for the purposes of this command, the NV Index is considered 33831to contain all zero bits and data is OR with that value. 33832If TPMA_NV_BITS is not SET, then the TPM shall return TPM_RC_ATTRIBUTES. 33833After successful completion of this command, TPMA_NV_WRITTEN for the NV Index will be SET. 33834NOTE 33835 33836TPMA_NV_WRITTEN will be SET even if no bits were SET. 33837 33838Family “2.0” 33839Level 00 Revision 00.99 33840 33841Published 33842Copyright © TCG 2006-2013 33843 33844Page 421 33845October 31, 2013 33846 33847 Part 3: Commands 33848 3384933.10.2 33850 33851Trusted Platform Module Library 33852 33853Command and Response 33854Table 211 — TPM2_NV_SetBits Command 33855 33856Type 33857 33858Name 33859 33860Description 33861 33862TPMI_ST_COMMAND_TAG 33863 33864tag 33865 33866UINT32 33867 33868commandSize 33869 33870TPM_CC 33871 33872commandCode 33873 33874TPM_CC_NV_SetBits {NV} 33875 33876TPMI_RH_NV_AUTH 33877 33878@authHandle 33879 33880handle indicating the source of the authorization value 33881Auth Index: 1 33882Auth Role: USER 33883 33884TPMI_RH_NV_INDEX 33885 33886nvIndex 33887 33888NV Index of the area in which the bit is to be set 33889Auth Index: None 33890 33891UINT64 33892 33893bits 33894 33895the data to OR with the current contents 33896 33897Table 212 — TPM2_NV_SetBits Response 33898Type 33899 33900Name 33901 33902Description 33903 33904TPM_ST 33905 33906tag 33907 33908see clause 8 33909 33910UINT32 33911 33912responseSize 33913 33914TPM_RC 33915 33916responseCode 33917 33918Page 422 33919October 31, 2013 33920 33921Published 33922Copyright © TCG 2006-2013 33923 33924Family “2.0” 33925Level 00 Revision 00.99 33926 33927 Trusted Platform Module Library 33928 3392933.10.3 339301 339312 339323 33933 33934Part 3: Commands 33935 33936Detailed Actions 33937 33938#include "InternalRoutines.h" 33939#include "NV_SetBits_fp.h" 33940#include "NV_spt_fp.h" 33941Error Returns 33942TPM_RC_ATTRIBUTES 33943 33944the TPMA_NV_BITS attribute is not SET in the Index referenced by 33945nvIndex 33946 33947TPM_RC_NV_AUTHORIZATION 33948 33949the authorization was valid but the authorizing entity (authHandle) is 33950not allowed to write to the Index referenced by nvIndex 33951 33952TPM_RC_NV_LOCKED 339534 339545 339556 339567 339578 339589 3395910 3396011 3396112 3396213 3396314 3396415 3396516 3396617 3396718 3396819 3396920 3397021 3397122 3397223 3397324 3397425 3397526 3397627 3397728 3397829 3397930 3398031 3398132 3398233 3398334 3398435 3398536 3398637 3398738 3398839 3398940 3399041 3399142 3399243 3399344 3399445 3399546 3399647 3399748 3399849 33999 34000Meaning 34001 34002the Index referenced by nvIndex is locked for writing 34003 34004TPM_RC 34005TPM2_NV_SetBits( 34006NV_SetBits_In 34007 34008*in 34009 34010// IN: input parameter list 34011 34012) 34013{ 34014TPM_RC 34015NV_INDEX 34016UINT64 34017 34018result; 34019nvIndex; 34020bitValue; 34021 34022// Input Validation 34023// Common access checks, NvWriteAccessCheck() may return TPM_RC_NV_AUTHORIZATION 34024// or TPM_RC_NV_LOCKED 34025// error may be returned at this point 34026result = NvWriteAccessChecks(in->authHandle, in->nvIndex); 34027if(result != TPM_RC_SUCCESS) 34028return result; 34029// Get NV index info 34030NvGetIndexInfo(in->nvIndex, &nvIndex); 34031// Make sure that this is a bit field 34032if(nvIndex.publicArea.attributes.TPMA_NV_BITS != SET) 34033return TPM_RC_ATTRIBUTES + RC_NV_SetBits_nvIndex; 34034// If the Index is not-orderly, or if this is the first write, NV will 34035// need to be updated. 34036if( 34037nvIndex.publicArea.attributes.TPMA_NV_ORDERLY == CLEAR 34038|| nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR) 34039{ 34040// Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE 34041// TPM_RC_NV_RATE or TPM_RC_SUCCESS. 34042result = NvIsAvailable(); 34043if(result != TPM_RC_SUCCESS) 34044return result; 34045} 34046// Internal Data Update 34047// If index is not been written, initialize it 34048if(nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR) 34049bitValue = 0; 34050else 34051// Read index data 34052 34053Family “2.0” 34054Level 00 Revision 00.99 34055 34056Published 34057Copyright © TCG 2006-2013 34058 34059Page 423 34060October 31, 2013 34061 34062 Part 3: Commands 3406350 3406451 3406552 3406653 3406754 3406855 3406956 3407057 3407158 3407259 34073 34074Trusted Platform Module Library 34075 34076NvGetIntIndexData(in->nvIndex, &nvIndex, &bitValue); 34077// OR in the new bit setting 34078bitValue |= in->bits; 34079// Write index data back. If necessary, this function will SET 34080// TPMA_NV_WRITTEN. 34081return NvWriteIndexData(in->nvIndex, &nvIndex, 0, 8, &bitValue); 34082} 34083 34084Page 424 34085October 31, 2013 34086 34087Published 34088Copyright © TCG 2006-2013 34089 34090Family “2.0” 34091Level 00 Revision 00.99 34092 34093 Trusted Platform Module Library 34094 34095Part 3: Commands 34096 3409733.11 TPM2_NV_WriteLock 3409833.11.1 34099 34100General Description 34101 34102If the TPMA_NV_WRITEDEFINE or TPMA_NV_WRITE_STCLEAR attributes of an NV location are SET, 34103then this command may be used to inhibit further writes of the NV Index. 34104Proper write authorization is required for this command as determined by TPMA_NV_PPWRITE, 34105TPMA_NV_OWNERWRITE, TPMA_NV_AUTHWRITE, and the authPolicy of the NV Index. 34106It is not an error if TPMA_NV_WRITELOCKED for the NV Index is already SET. 34107If neither TPMA_NV_WRITEDEFINE nor TPMA_NV_WRITE_STCLEAR of the NV Index is SET, then the 34108TPM shall return TPM_RC_ATTRIBUTES. 34109If the command is properly authorized and TPMA_NV_WRITE_STCLEAR or TPMA_NV_WRITEDEFINE 34110is SET, then the TPM shall SET TPMA_NV_WRITELOCKED for the NV Index. 34111TPMA_NV_WRITELOCKED will be clear on the next TPM2_Startup(TPM_SU_CLEAR) unless 34112TPMA_NV_WRITEDEFINE is SET. 34113 34114Family “2.0” 34115Level 00 Revision 00.99 34116 34117Published 34118Copyright © TCG 2006-2013 34119 34120Page 425 34121October 31, 2013 34122 34123 Part 3: Commands 34124 3412533.11.2 34126 34127Trusted Platform Module Library 34128 34129Command and Response 34130Table 213 — TPM2_NV_WriteLock Command 34131 34132Type 34133 34134Name 34135 34136Description 34137 34138TPMI_ST_COMMAND_TAG 34139 34140tag 34141 34142UINT32 34143 34144commandSize 34145 34146TPM_CC 34147 34148commandCode 34149 34150TPM_CC_NV_WriteLock {NV} 34151 34152TPMI_RH_NV_AUTH 34153 34154@authHandle 34155 34156handle indicating the source of the authorization value 34157Auth Index: 1 34158Auth Role: USER 34159 34160TPMI_RH_NV_INDEX 34161 34162nvIndex 34163 34164the NV Index of the area to lock 34165Auth Index: None 34166 34167Table 214 — TPM2_NV_WriteLock Response 34168Type 34169 34170Name 34171 34172Description 34173 34174TPM_ST 34175 34176tag 34177 34178see clause 8 34179 34180UINT32 34181 34182responseSize 34183 34184TPM_RC 34185 34186responseCode 34187 34188Page 426 34189October 31, 2013 34190 34191Published 34192Copyright © TCG 2006-2013 34193 34194Family “2.0” 34195Level 00 Revision 00.99 34196 34197 Trusted Platform Module Library 34198 3419933.11.3 342001 342012 342023 34203 34204Part 3: Commands 34205 34206Detailed Actions 34207 34208#include "InternalRoutines.h" 34209#include "NV_WriteLock_fp.h" 34210#include "NV_spt_fp.h" 34211Error Returns 34212TPM_RC_ATTRIBUTES 34213 34214neither TPMA_NV_WRITEDEFINE nor 34215TPMA_NV_WRITE_STCLEAR is SET in Index referenced by 34216nvIndex 34217 34218TPM_RC_NV_AUTHORIZATION 34219 342204 342215 342226 342237 342248 342259 3422610 3422711 3422812 3422913 3423014 3423115 3423216 3423317 3423418 3423519 3423620 3423721 3423822 3423923 3424024 3424125 3424226 3424327 3424428 3424529 3424630 3424731 3424832 3424933 3425034 3425135 3425236 3425337 3425438 3425539 3425640 3425741 3425842 3425943 3426044 3426145 3426246 3426347 3426448 3426549 3426650 34267 34268Meaning 34269 34270the authorization was valid but the authorizing entity (authHandle) is 34271not allowed to write to the Index referenced by nvIndex 34272 34273TPM_RC 34274TPM2_NV_WriteLock( 34275NV_WriteLock_In *in 34276 34277// IN: input parameter list 34278 34279) 34280{ 34281TPM_RC 34282NV_INDEX 34283 34284result; 34285nvIndex; 34286 34287// The command needs NV update. Check if NV is available. 34288// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 34289// this point 34290result = NvIsAvailable(); 34291if(result != TPM_RC_SUCCESS) 34292return result; 34293// Input Validation: 34294// Common write access checks, a TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED 34295// error may be returned at this point 34296result = NvWriteAccessChecks(in->authHandle, in->nvIndex); 34297if(result != TPM_RC_SUCCESS) 34298{ 34299if(result == TPM_RC_NV_AUTHORIZATION) 34300return TPM_RC_NV_AUTHORIZATION; 34301// If write access failed because the index is already locked, then it is 34302// no error. 34303return TPM_RC_SUCCESS; 34304} 34305// Get NV index info 34306NvGetIndexInfo(in->nvIndex, &nvIndex); 34307// if non of TPMA_NV_WRITEDEFINE or TPMA_NV_WRITE_STCLEAR is set, the index 34308// can not be write-locked 34309if( 34310nvIndex.publicArea.attributes.TPMA_NV_WRITEDEFINE == CLEAR 34311&& nvIndex.publicArea.attributes.TPMA_NV_WRITE_STCLEAR == CLEAR) 34312return TPM_RC_ATTRIBUTES + RC_NV_WriteLock_nvIndex; 34313// Internal Data Update 34314// Set the WRITELOCK attribute 34315nvIndex.publicArea.attributes.TPMA_NV_WRITELOCKED = SET; 34316// Write index info back 34317NvWriteIndexInfo(in->nvIndex, &nvIndex); 34318 34319Family “2.0” 34320Level 00 Revision 00.99 34321 34322Published 34323Copyright © TCG 2006-2013 34324 34325Page 427 34326October 31, 2013 34327 34328 Part 3: Commands 3432951 3433052 34331 34332Trusted Platform Module Library 34333 34334return TPM_RC_SUCCESS; 34335} 34336 34337Page 428 34338October 31, 2013 34339 34340Published 34341Copyright © TCG 2006-2013 34342 34343Family “2.0” 34344Level 00 Revision 00.99 34345 34346 Trusted Platform Module Library 34347 34348Part 3: Commands 34349 3435033.12 TPM2_NV_GlobalWriteLock 3435133.12.1 34352 34353General Description 34354 34355The command will SET TPMA_NV_WRITELOCKED 34356TPMA_NV_GLOBALLOCK attribute SET. 34357 34358for 34359 34360all 34361 34362indexes 34363 34364that 34365 34366have 34367 34368their 34369 34370If an Index has both TPMA_NV_WRITELOCKED and TPMA_NV_WRITEDEFINE SET, then this 34371command will permanently lock the NV Index for writing. 34372NOTE 34373 34374If an Index is defined with TPMA_NV_GLOBALLOCK SET, then the global lock does not apply until 34375the next time this command is executed. 34376 34377This command requires either platformAuth/platformPolicy or ownerAuth/ownerPolicy. 34378 34379Family “2.0” 34380Level 00 Revision 00.99 34381 34382Published 34383Copyright © TCG 2006-2013 34384 34385Page 429 34386October 31, 2013 34387 34388 Part 3: Commands 34389 3439033.12.2 34391 34392Trusted Platform Module Library 34393 34394Command and Response 34395Table 215 — TPM2_NV_GlobalWriteLock Command 34396 34397Type 34398 34399Name 34400 34401TPMI_ST_COMMAND_TAG 34402 34403tag 34404 34405UINT32 34406 34407commandSize 34408 34409TPM_CC 34410 34411commandCode 34412 34413TPM_CC_NV_GlobalWriteLock 34414 34415@authHandle 34416 34417TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 34418Auth Index: 1 34419Auth Role: USER 34420 34421TPMI_RH_PROVISION 34422 34423Description 34424 34425Table 216 — TPM2_NV_GlobalWriteLock Response 34426Type 34427 34428Name 34429 34430Description 34431 34432TPM_ST 34433 34434tag 34435 34436see clause 8 34437 34438UINT32 34439 34440responseSize 34441 34442TPM_RC 34443 34444responseCode 34445 34446Page 430 34447October 31, 2013 34448 34449Published 34450Copyright © TCG 2006-2013 34451 34452Family “2.0” 34453Level 00 Revision 00.99 34454 34455 Trusted Platform Module Library 34456 3445733.12.3 344581 344592 344603 344614 344625 344636 344647 344658 344669 3446710 3446811 3446912 3447013 3447114 3447215 3447316 3447417 3447518 3447619 3447720 3447821 3447922 3448023 3448124 3448225 3448326 34484 34485Part 3: Commands 34486 34487Detailed Actions 34488 34489#include "InternalRoutines.h" 34490#include "NV_GlobalWriteLock_fp.h" 34491 34492TPM_RC 34493TPM2_NV_GlobalWriteLock( 34494NV_GlobalWriteLock_In *in 34495 34496// IN: input parameter list 34497 34498) 34499{ 34500TPM_RC 34501 34502result; 34503 34504// Input parameter is not reference in command action 34505in = NULL; // to silence compiler warnings. 34506// The command needs NV update. Check if NV is available. 34507// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 34508// this point 34509result = NvIsAvailable(); 34510if(result != TPM_RC_SUCCESS) 34511return result; 34512// Internal Data Update 34513// Implementation dependent method of setting the global lock 34514NvSetGlobalLock(); 34515return TPM_RC_SUCCESS; 34516} 34517 34518Family “2.0” 34519Level 00 Revision 00.99 34520 34521Published 34522Copyright © TCG 2006-2013 34523 34524Page 431 34525October 31, 2013 34526 34527 Part 3: Commands 34528 34529Trusted Platform Module Library 34530 3453133.13 TPM2_NV_Read 3453233.13.1 34533 34534General Description 34535 34536This command reads a 34537TPM2_NV_DefineSpace(). 34538 34539value 34540 34541from 34542 34543an 34544 34545area 34546 34547in 34548 34549NV 34550 34551memory 34552 34553previously 34554 34555defined 34556 34557by 34558 34559Proper authorizations are required for this command as determined by TPMA_NV_PPREAD, 34560TPMA_NV_OWNERREAD, TPMA_NV_AUTHREAD, and the authPolicy of the NV Index. 34561If TPMA_NV_READLOCKED of the NV Index is SET, then the TPM shall return TPM_RC_NV_LOCKED. 34562NOTE 34563 34564If authorization sessions are present, they are checked before the read -lock status of the NV Index 34565is checked. 34566 34567If the size parameter plus the offset parameter adds to a value that is greater than the size of the NV 34568Index data area, the TPM shall return TPM_RC_NV_RANGE and not read any data from the NV Index. 34569If the NV Index has been defined but the TPMA_NV_WRITTEN attribute is CLEAR, then this command 34570shall return TPM_RC_NV_UINITIALIZED even if size is zero. 34571The data parameter in the response may be encrypted using parameter encryption. 34572 34573Page 432 34574October 31, 2013 34575 34576Published 34577Copyright © TCG 2006-2013 34578 34579Family “2.0” 34580Level 00 Revision 00.99 34581 34582 Trusted Platform Module Library 34583 3458433.13.2 34585 34586Part 3: Commands 34587 34588Command and Response 34589Table 217 — TPM2_NV_Read Command 34590 34591Type 34592 34593Name 34594 34595Description 34596 34597TPMI_ST_COMMAND_TAG 34598 34599tag 34600 34601UINT32 34602 34603commandSize 34604 34605TPM_CC 34606 34607commandCode 34608 34609TPM_CC_NV_Read 34610 34611TPMI_RH_NV_AUTH 34612 34613@authHandle 34614 34615the handle indicating the source of the authorization 34616value 34617Auth Index: 1 34618Auth Role: USER 34619 34620TPMI_RH_NV_INDEX 34621 34622nvIndex 34623 34624the NV Index to be read 34625Auth Index: None 34626 34627UINT16 34628 34629size 34630 34631number of octets to read 34632 34633UINT16 34634 34635offset 34636 34637octet offset into the area 34638This value shall be less than or equal to the size of the 34639nvIndex data. 34640 34641Table 218 — TPM2_NV_Read Response 34642Type 34643 34644Name 34645 34646Description 34647 34648TPM_ST 34649 34650tag 34651 34652see clause 8 34653 34654UINT32 34655 34656responseSize 34657 34658TPM_RC 34659 34660responseCode 34661 34662TPM2B_MAX_NV_BUFFER 34663 34664data 34665 34666Family “2.0” 34667Level 00 Revision 00.99 34668 34669the data read 34670 34671Published 34672Copyright © TCG 2006-2013 34673 34674Page 433 34675October 31, 2013 34676 34677 Part 3: Commands 34678 3467933.13.3 346801 346812 346823 34683 34684Trusted Platform Module Library 34685 34686Detailed Actions 34687 34688#include "InternalRoutines.h" 34689#include "NV_Read_fp.h" 34690#include "NV_spt_fp.h" 34691Error Returns 34692TPM_RC_NV_AUTHORIZATION 34693 34694the authorization was valid but the authorizing entity (authHandle) is 34695not allowed to read from the Index referenced by nvIndex 34696 34697TPM_RC_NV_LOCKED 34698 34699the Index referenced by nvIndex is read locked 34700 34701TPM_RC_NV_RANGE 34702 34703read range defined by size and offset is outside the range of the 34704Index referenced by nvIndex 34705 34706TPM_RC_NV_UNINITIALIZED 347074 347085 347096 347107 347118 347129 3471310 3471411 3471512 3471613 3471714 3471815 3471916 3472017 3472118 3472219 3472320 3472421 3472522 3472623 3472724 3472825 3472926 3473027 3473128 3473229 3473330 3473431 3473532 3473633 3473734 3473835 3473936 3474037 34741 34742Meaning 34743 34744the Index referenced by nvIndex has not been initialized (written) 34745 34746TPM_RC 34747TPM2_NV_Read( 34748NV_Read_In 34749NV_Read_Out 34750 34751*in, 34752*out 34753 34754// IN: input parameter list 34755// OUT: output parameter list 34756 34757) 34758{ 34759NV_INDEX 34760TPM_RC 34761 34762nvIndex; 34763result; 34764 34765// Input Validation 34766// Get NV index info 34767NvGetIndexInfo(in->nvIndex, &nvIndex); 34768// Common read access checks. NvReadAccessChecks() returns 34769// TPM_RC_NV_AUTHORIZATION, TPM_RC_NV_LOCKED, or TPM_RC_NV_UNINITIALIZED 34770// error may be returned at this point 34771result = NvReadAccessChecks(in->authHandle, in->nvIndex); 34772if(result != TPM_RC_SUCCESS) 34773return result; 34774// Too much data 34775if((in->size + in->offset) > nvIndex.publicArea.dataSize) 34776return TPM_RC_NV_RANGE; 34777// Command Output 34778// Set the return size 34779out->data.t.size = in->size; 34780// Perform the read 34781NvGetIndexData(in->nvIndex, &nvIndex, in->offset, in->size, out->data.t.buffer); 34782return TPM_RC_SUCCESS; 34783} 34784 34785Page 434 34786October 31, 2013 34787 34788Published 34789Copyright © TCG 2006-2013 34790 34791Family “2.0” 34792Level 00 Revision 00.99 34793 34794 Trusted Platform Module Library 34795 34796Part 3: Commands 34797 3479833.14 TPM2_NV_ReadLock 3479933.14.1 34800 34801General Description 34802 34803If TPMA_NV_READ_STCLEAR is SET in an Index, then this command may be used to prevent further 34804reads of the NV Index until the next TPM2_Startup (TPM_SU_CLEAR). 34805Proper authorizations are required for this command as determined by TPMA_NV_PPREAD, 34806TPMA_NV_OWNERREAD, TPMA_NV_AUTHREAD, and the authPolicy of the NV Index. 34807NOTE 34808 34809Only an entity that may read an Index is allowed to lock the NV Index for read. 34810 34811If the command is properly authorized and TPMA_NV_READ_STCLEAR of the NV Index is SET, then the 34812TPM shall SET TPMA_NV_READLOCKED for the NV Index. If TPMA_NV_READ_STCLEAR of the NV 34813Index is CLEAR, then the TPM shall return TPM_RC_NV_ATTRIBUTE. TPMA_NV_READLOCKED will 34814be CLEAR by the next TPM2_Startup(TPM_SU_CLEAR). 34815It is not an error to use this command for an Index that is already locked for reading. 34816An Index that had not been written may be locked for reading. 34817 34818Family “2.0” 34819Level 00 Revision 00.99 34820 34821Published 34822Copyright © TCG 2006-2013 34823 34824Page 435 34825October 31, 2013 34826 34827 Part 3: Commands 34828 3482933.14.2 34830 34831Trusted Platform Module Library 34832 34833Command and Response 34834Table 219 — TPM2_NV_ReadLock Command 34835 34836Type 34837 34838Name 34839 34840Description 34841 34842TPMI_ST_COMMAND_TAG 34843 34844tag 34845 34846UINT32 34847 34848commandSize 34849 34850TPM_CC 34851 34852commandCode 34853 34854TPM_CC_NV_ReadLock 34855 34856TPMI_RH_NV_AUTH 34857 34858@authHandle 34859 34860the handle indicating the source of the authorization 34861value 34862Auth Index: 1 34863Auth Role: USER 34864 34865TPMI_RH_NV_INDEX 34866 34867nvIndex 34868 34869the NV Index to be locked 34870Auth Index: None 34871 34872Table 220 — TPM2_NV_ReadLock Response 34873Type 34874 34875Name 34876 34877Description 34878 34879TPM_ST 34880 34881tag 34882 34883see clause 8 34884 34885UINT32 34886 34887responseSize 34888 34889TPM_RC 34890 34891responseCode 34892 34893Page 436 34894October 31, 2013 34895 34896Published 34897Copyright © TCG 2006-2013 34898 34899Family “2.0” 34900Level 00 Revision 00.99 34901 34902 Trusted Platform Module Library 34903 3490433.14.3 349051 349062 349073 34908 34909Part 3: Commands 34910 34911Detailed Actions 34912 34913#include "InternalRoutines.h" 34914#include "NV_ReadLock_fp.h" 34915#include "NV_spt_fp.h" 34916Error Returns 34917TPM_RC_ATTRIBUTES 34918 34919TPMA_NV_READ_STCLEAR is not SET so Index referenced by 34920nvIndex may not be write locked 34921 34922TPM_RC_NV_AUTHORIZATION 34923 349244 349255 349266 349277 349288 349299 3493010 3493111 3493212 3493313 3493414 3493515 3493616 3493717 3493818 3493919 3494020 3494121 3494222 3494323 3494424 3494525 3494626 3494727 3494828 3494929 3495030 3495131 3495232 3495333 3495434 3495535 3495636 3495737 3495838 3495939 3496040 3496141 3496242 3496343 3496444 3496545 3496646 3496747 3496848 3496949 3497050 3497151 34972 34973Meaning 34974 34975the authorization was valid but the authorizing entity (authHandle) is 34976not allowed to read from the Index referenced by nvIndex 34977 34978TPM_RC 34979TPM2_NV_ReadLock( 34980NV_ReadLock_In *in 34981 34982// IN: input parameter list 34983 34984) 34985{ 34986TPM_RC 34987NV_INDEX 34988 34989result; 34990nvIndex; 34991 34992// The command needs NV update. Check if NV is available. 34993// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 34994// this point 34995result = NvIsAvailable(); 34996if(result != TPM_RC_SUCCESS) return result; 34997// Input Validation 34998// Common read access checks. NvReadAccessChecks() returns 34999// TPM_RC_NV_AUTHORIZATION, TPM_RC_NV_LOCKED, or TPM_RC_NV_UNINITIALIZED 35000// error may be returned at this point 35001result = NvReadAccessChecks(in->authHandle, in->nvIndex); 35002if(result != TPM_RC_SUCCESS) 35003{ 35004if(result == TPM_RC_NV_AUTHORIZATION) 35005return TPM_RC_NV_AUTHORIZATION; 35006// Index is already locked for write 35007else if(result == TPM_RC_NV_LOCKED) 35008return TPM_RC_SUCCESS; 35009// If NvReadAccessChecks return TPM_RC_NV_UNINITALIZED, then continue. 35010// It is not an error to read lock an uninitialized Index. 35011} 35012// Get NV index info 35013NvGetIndexInfo(in->nvIndex, &nvIndex); 35014// if TPMA_NV_READ_STCLEAR is not set, the index can not be read-locked 35015if(nvIndex.publicArea.attributes.TPMA_NV_READ_STCLEAR == CLEAR) 35016return TPM_RC_ATTRIBUTES + RC_NV_ReadLock_nvIndex; 35017// Internal Data Update 35018// Set the READLOCK attribute 35019nvIndex.publicArea.attributes.TPMA_NV_READLOCKED = SET; 35020// Write NV info back 35021NvWriteIndexInfo(in->nvIndex, &nvIndex); 35022return TPM_RC_SUCCESS; 35023} 35024 35025Family “2.0” 35026Level 00 Revision 00.99 35027 35028Published 35029Copyright © TCG 2006-2013 35030 35031Page 437 35032October 31, 2013 35033 35034 Part 3: Commands 35035 35036Trusted Platform Module Library 35037 3503833.15 TPM2_NV_ChangeAuth 3503933.15.1 35040 35041General Description 35042 35043This command allows the authorization secret for an NV Index to be changed. 35044If successful, the authorization secret (authValue) of the NV Index associated with nvIndex is changed. 35045This command requires that a policy session be used for authorization of nvIndex so that the ADMIN role 35046may be asserted and that commandCode in the policy session context shall be 35047TPM_CC_NV_ChangeAuth. That is, the policy must contain a specific authorization for changing the 35048authorization value of the referenced object. 35049NOTE 35050 35051The reason for this restriction is to ensure that the admin istrative actions on nvIndex require explicit 35052approval while other commands may use policy that is not command -dependent. 35053 35054The size of the newAuth value may be no larger than the size of authorization indicated when the NV 35055Index was defined. 35056Since the NV Index authorization is changed before the response HMAC is calculated, the newAuth value 35057is used when generating the response HMAC key if required. See Part 4 ComputeResponseHMAC(). 35058 35059Page 438 35060October 31, 2013 35061 35062Published 35063Copyright © TCG 2006-2013 35064 35065Family “2.0” 35066Level 00 Revision 00.99 35067 35068 Trusted Platform Module Library 35069 3507033.15.2 35071 35072Part 3: Commands 35073 35074Command and Response 35075Table 221 — TPM2_NV_ChangeAuth Command 35076 35077Type 35078 35079Name 35080 35081Description 35082 35083TPMI_ST_COMMAND_TAG 35084 35085tag 35086 35087UINT32 35088 35089commandSize 35090 35091TPM_CC 35092 35093commandCode 35094 35095TPM_CC_NV_ChangeAuth {NV} 35096 35097TPMI_RH_NV_INDEX 35098 35099@nvIndex 35100 35101handle of the object 35102Auth Index: 1 35103Auth Role: ADMIN 35104 35105TPM2B_AUTH 35106 35107newAuth 35108 35109new authorization value 35110 35111Table 222 — TPM2_NV_ChangeAuth Response 35112Type 35113 35114Name 35115 35116Description 35117 35118TPM_ST 35119 35120tag 35121 35122see clause 8 35123 35124UINT32 35125 35126responseSize 35127 35128TPM_RC 35129 35130responseCode 35131 35132Family “2.0” 35133Level 00 Revision 00.99 35134 35135Published 35136Copyright © TCG 2006-2013 35137 35138Page 439 35139October 31, 2013 35140 35141 Part 3: Commands 35142 3514333.15.3 351441 351452 35146 35147Trusted Platform Module Library 35148 35149Detailed Actions 35150 35151#include "InternalRoutines.h" 35152#include "NV_ChangeAuth_fp.h" 35153Error Returns 35154TPM_RC_SIZE 35155 351563 351574 351585 351596 351607 351618 351629 3516310 3516411 3516512 3516613 3516714 3516815 3516916 3517017 3517118 3517219 3517320 3517421 3517522 3517623 3517724 3517825 3517926 3518027 3518128 3518229 3518330 3518431 3518532 3518633 3518734 3518835 35189 35190Meaning 35191newAuth size is larger than the digest size of the Name algorithm for 35192the Index referenced by 'nvIndex 35193 35194TPM_RC 35195TPM2_NV_ChangeAuth( 35196NV_ChangeAuth_In 35197 35198*in 35199 35200// IN: input parameter list 35201 35202) 35203{ 35204TPM_RC 35205NV_INDEX 35206 35207result; 35208nvIndex; 35209 35210// Input Validation 35211// Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE 35212// TPM_RC_NV_RATE or TPM_RC_SUCCESS. 35213result = NvIsAvailable(); 35214if(result != TPM_RC_SUCCESS) return result; 35215// Read index info from NV 35216NvGetIndexInfo(in->nvIndex, &nvIndex); 35217// Remove any trailing zeros that might have been added by the caller 35218// to obfuscate the size. 35219MemoryRemoveTrailingZeros(&(in->newAuth)); 35220// Make sure that the authValue is no larger than the nameAlg of the Index 35221if(in->newAuth.t.size > CryptGetHashDigestSize(nvIndex.publicArea.nameAlg)) 35222return TPM_RC_SIZE + RC_NV_ChangeAuth_newAuth; 35223// Internal Data Update 35224// Change auth 35225nvIndex.authValue = in->newAuth; 35226// Write index info back to NV 35227NvWriteIndexInfo(in->nvIndex, &nvIndex); 35228return TPM_RC_SUCCESS; 35229} 35230 35231Page 440 35232October 31, 2013 35233 35234Published 35235Copyright © TCG 2006-2013 35236 35237Family “2.0” 35238Level 00 Revision 00.99 35239 35240 Trusted Platform Module Library 35241 35242Part 3: Commands 35243 3524433.16 TPM2_NV_Certify 3524533.16.1 35246 35247General Description 35248 35249The purpose of this command is to certify the contents of an NV Index or portion of an NV Index. 35250If proper authorization for reading the NV Index is provided, the portion of the NV Index selected by size 35251and offset are included in an attestation block and signed using the key indicated by signHandle. The 35252attestation also includes size and offset so that the range of the data can be determined. 35253NOTE 35254 35255See 20.1 for description of how the signing scheme is selected. 35256 35257Family “2.0” 35258Level 00 Revision 00.99 35259 35260Published 35261Copyright © TCG 2006-2013 35262 35263Page 441 35264October 31, 2013 35265 35266 Part 3: Commands 35267 3526833.16.2 35269 35270Trusted Platform Module Library 35271 35272Command and Response 35273Table 223 — TPM2_NV_Certify Command 35274 35275Type 35276 35277Name 35278 35279Description 35280 35281TPMI_ST_COMMAND_TAG 35282 35283tag 35284 35285UINT32 35286 35287commandSize 35288 35289TPM_CC 35290 35291commandCode 35292 35293TPM_CC_NV_Certify 35294 35295TPMI_DH_OBJECT+ 35296 35297@signHandle 35298 35299handle of the key used to sign the attestation structure 35300Auth Index: 1 35301Auth Role: USER 35302 35303TPMI_RH_NV_AUTH 35304 35305@authHandle 35306 35307handle indicating the source of the authorization value 35308for the NV Index 35309Auth Index: 2 35310Auth Role: USER 35311 35312TPMI_RH_NV_INDEX 35313 35314nvIndex 35315 35316Index for the area to be certified 35317Auth Index: None 35318 35319TPM2B_DATA 35320 35321qualifyingData 35322 35323user-provided qualifying data 35324 35325TPMT_SIG_SCHEME+ 35326 35327inScheme 35328 35329signing scheme to use if the scheme for signHandle is 35330TPM_ALG_NULL 35331 35332UINT16 35333 35334size 35335 35336number of octets to certify 35337 35338UINT16 35339 35340offset 35341 35342octet offset into the area 35343This value shall be less than or equal to the size of the 35344nvIndex data. 35345 35346Table 224 — TPM2_NV_Certify Response 35347Type 35348 35349Name 35350 35351Description 35352 35353TPM_ST 35354 35355tag 35356 35357see clause 8 35358 35359UINT32 35360 35361responseSize 35362 35363TPM_RC 35364 35365responseCode 35366 35367. 35368 35369TPM2B_ATTEST 35370 35371certifyInfo 35372 35373the structure that was signed 35374 35375TPMT_SIGNATURE 35376 35377signature 35378 35379the asymmetric signature over certifyInfo using the key 35380referenced by signHandle 35381 35382Page 442 35383October 31, 2013 35384 35385Published 35386Copyright © TCG 2006-2013 35387 35388Family “2.0” 35389Level 00 Revision 00.99 35390 35391 Trusted Platform Module Library 35392 3539333.16.3 353941 353952 353963 353974 35398 35399Detailed Actions 35400 35401#include 35402#include 35403#include 35404#include 35405 35406Part 3: Commands 35407 35408"InternalRoutines.h" 35409"Attest_spt_fp.h" 35410"NV_spt_fp.h" 35411"NV_Certify_fp.h" 35412 35413Error Returns 35414TPM_RC_NV_AUTHORIZATION 35415 35416the authorization was valid but the authorizing entity (authHandle) is 35417not allowed to read from the Index referenced by nvIndex 35418 35419TPM_RC_KEY 35420 35421signHandle does not reference a signing key 35422 35423TPM_RC_NV_LOCKED 35424 35425Index referenced by nvIndex is locked for reading 35426 35427TPM_RC_NV_RANGE 35428 35429offset plus size extends outside of the data range of the Index 35430referenced by nvIndex 35431 35432TPM_RC_NV_UNINITIALIZED 35433 35434Index referenced by nvIndex has not been written 35435 35436TPM_RC_SCHEME 354375 354386 354397 354408 354419 3544210 3544311 3544412 3544513 3544614 3544715 3544816 3544917 3545018 3545119 3545220 3545321 3545422 3545523 3545624 3545725 3545826 3545927 3546028 3546129 3546230 3546331 3546432 3546533 3546634 3546735 3546836 3546937 3547038 3547139 3547240 3547341 3547442 3547543 3547644 35477 35478Meaning 35479 35480inScheme is not an allowed value for the key definition 35481 35482TPM_RC 35483TPM2_NV_Certify( 35484NV_Certify_In 35485NV_Certify_Out 35486 35487*in, 35488*out 35489 35490// IN: input parameter list 35491// OUT: output parameter list 35492 35493) 35494{ 35495TPM_RC 35496NV_INDEX 35497TPMS_ATTEST 35498 35499result; 35500nvIndex; 35501certifyInfo; 35502 35503// Attestation command may cause the orderlyState to be cleared due to 35504// the reporting of clock info. If this is the case, check if NV is 35505// available first 35506if(gp.orderlyState != SHUTDOWN_NONE) 35507{ 35508// The command needs NV update. Check if NV is available. 35509// A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 35510// this point 35511result = NvIsAvailable(); 35512if(result != TPM_RC_SUCCESS) 35513return result; 35514} 35515// Input Validation 35516// Get NV index info 35517NvGetIndexInfo(in->nvIndex, &nvIndex); 35518// Common access checks. A TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED 35519// error may be returned at this point 35520result = NvReadAccessChecks(in->authHandle, in->nvIndex); 35521if(result != TPM_RC_SUCCESS) 35522return result; 35523// See if the range to be certified is out of the bounds of the defined 35524// Index 35525if((in->size + in->offset) > nvIndex.publicArea.dataSize) 35526return TPM_RC_NV_RANGE; 35527// Command Output 35528 35529Family “2.0” 35530Level 00 Revision 00.99 35531 35532Published 35533Copyright © TCG 2006-2013 35534 35535Page 443 35536October 31, 2013 35537 35538 Part 3: Commands 3553945 3554046 3554147 3554248 3554349 3554450 3554551 3554652 3554753 3554854 3554955 3555056 3555157 3555258 3555359 3555460 3555561 3555662 3555763 3555864 3555965 3556066 3556167 3556268 3556369 3556470 3556571 3556672 3556773 3556874 3556975 3557076 3557177 3557278 3557379 3557480 3557581 3557682 3557783 3557884 3557985 3558086 3558187 3558288 3558389 3558490 3558591 3558692 3558793 3558894 3558995 3559096 3559197 3559298 3559399 35594100 35595 35596Trusted Platform Module Library 35597 35598// Filling in attest information 35599// Common fields 35600// FillInAttestInfo can return TPM_RC_SCHEME or TPM_RC_KEY 35601result = FillInAttestInfo(in->signHandle, 35602&in->inScheme, 35603&in->qualifyingData, 35604&certifyInfo); 35605if(result != TPM_RC_SUCCESS) 35606{ 35607if(result == TPM_RC_KEY) 35608return TPM_RC_KEY + RC_NV_Certify_signHandle; 35609else 35610return RcSafeAddToResult(result, RC_NV_Certify_inScheme); 35611} 35612// NV certify specific fields 35613// Attestation type 35614certifyInfo.type = TPM_ST_ATTEST_NV; 35615// Get the name of the index 35616certifyInfo.attested.nv.indexName.t.size = 35617NvGetName(in->nvIndex, &certifyInfo.attested.nv.indexName.t.name); 35618// Set the return size 35619certifyInfo.attested.nv.nvContents.t.size = in->size; 35620// Set the offset 35621certifyInfo.attested.nv.offset = in->offset; 35622// Perform the read 35623NvGetIndexData(in->nvIndex, &nvIndex, 35624in->offset, in->size, 35625certifyInfo.attested.nv.nvContents.t.buffer); 35626// Sign attestation structure. A NULL signature will be returned if 35627// signHandle is TPM_RH_NULL. SignAttestInfo() may return TPM_RC_VALUE, 35628// TPM_RC_SCHEME or TPM_RC_ATTRUBUTES. 35629// Note: SignAttestInfo may return TPM_RC_ATTRIBUTES if the key is not a 35630// signing key but that was checked above. TPM_RC_VALUE would mean that the 35631// data to sign is too large but the data to sign is a digest 35632result = SignAttestInfo(in->signHandle, 35633&in->inScheme, 35634&certifyInfo, 35635&in->qualifyingData, 35636&out->certifyInfo, 35637&out->signature); 35638if(result != TPM_RC_SUCCESS) 35639return result; 35640// orderly state should be cleared because of the reporting of clock info 35641// if signing happens 35642if(in->signHandle != TPM_RH_NULL) 35643g_clearOrderly = TRUE; 35644return TPM_RC_SUCCESS; 35645} 35646 35647Page 444 35648October 31, 2013 35649 35650Published 35651Copyright © TCG 2006-2013 35652 35653Family “2.0” 35654Level 00 Revision 00.99 35655 35656