1 Trusted Platform Module Library 2 Part 3: Commands 3 Family 2.0 4 Level 00 Revision 00.99 5 October 31, 2013 6 7 Contact: admin (a] trustedcomputinggroup.org 8 9 Published 10 Copyright TCG 2006-2013 11 12 TCG 13 14 Part 3: Commands 16 17 Trusted Platform Module Library 18 19 Licenses and Notices 20 1. Copyright Licenses: 21 22 23 Trusted Computing Group (TCG) grants to the user of the source code in this specification (the 24 Source Code) a worldwide, irrevocable, nonexclusive, royalty free, copyright license to 25 reproduce, create derivative works, distribute, display and perform the Source Code and 26 derivative works thereof, and to grant others the rights granted herein. 27 28 29 30 The TCG grants to the user of the other parts of the specification (other than the Source Code) 31 the rights to reproduce, distribute, display, and perform the specification solely for the purpose of 32 developing products based on such documents. 33 34 2. Source Code Distribution Conditions: 35 36 37 Redistributions of Source Code must retain the above copyright licenses, this list of conditions 38 and the following disclaimers. 39 40 41 42 Redistributions in binary form must reproduce the above copyright licenses, this list of conditions 43 and the following disclaimers in the documentation and/or other materials provided with the 44 distribution. 45 46 3. Disclaimers: 47 48 49 THE COPYRIGHT LICENSES SET FORTH ABOVE DO NOT REPRESENT ANY FORM OF 50 LICENSE OR WAIVER, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, WITH 51 RESPECT TO PATENT RIGHTS HELD BY TCG MEMBERS (OR OTHER THIRD PARTIES) 52 THAT MAY BE NECESSARY TO IMPLEMENT THIS SPECIFICATION OR OTHERWISE. 53 Contact TCG Administration (admin (a] trustedcomputinggroup.org) for information on specification 54 licensing rights available through TCG membership agreements. 55 56 57 58 THIS SPECIFICATION IS PROVIDED "AS IS" WITH NO EXPRESS OR IMPLIED WARRANTIES 59 WHATSOEVER, INCLUDING ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A 60 PARTICULAR PURPOSE, ACCURACY, COMPLETENESS, OR NONINFRINGEMENT OF 61 INTELLECTUAL PROPERTY RIGHTS, OR ANY WARRANTY OTHERWISE ARISING OUT OF 62 ANY PROPOSAL, SPECIFICATION OR SAMPLE. 63 64 65 66 Without limitation, TCG and its members and licensors disclaim all liability, including liability for 67 infringement of any proprietary rights, relating to use of information in this specification and to the 68 implementation of this specification, and TCG disclaims all liability for cost of procurement of 69 substitute goods or services, lost profits, loss of use, loss of data or any incidental, consequential, 70 direct, indirect, or special damages, whether under contract, tort, warranty or otherwise, arising in 71 any way out of use or reliance upon this specification or any information herein. 72 73 Any marks and brands contained herein are the property of their respective owner 74 75 Page ii 76 October 31, 2013 77 78 Published 79 Copyright TCG 2006-2013 80 81 Family 2.0 82 Level 00 Revision 00.99 83 84 Trusted Platform Module Library 86 87 Part 3: Commands 88 89 CONTENTS 90 1 91 2 92 3 93 4 94 95 Scope .................................................................................................................................................... 1 96 Terms and Definitions ........................................................................................................................... 1 97 Symbols and abbreviated terms ............................................................................................................ 1 98 Notation ................................................................................................................................................. 1 99 4.1 100 4.2 101 4.3 102 4.4 103 104 5 105 6 106 7 107 108 Introduction ..................................................................................................................................... 1 109 Table Decorations ........................................................................................................................... 1 110 Handle and Parameter Demarcation .............................................................................................. 3 111 AuthorizationSize and ParameterSize ............................................................................................ 3 112 113 Normative References ........................................................................................................................... 4 114 Symbols and Abbreviated Terms .......................................................................................................... 4 115 Command Processing ........................................................................................................................... 4 116 7.1 117 7.2 118 7.3 119 7.4 120 7.5 121 7.6 122 7.7 123 7.8 124 7.9 125 126 8 127 128 Introduction ..................................................................................................................................... 4 129 Command Header Validation .......................................................................................................... 4 130 Mode Checks .................................................................................................................................. 4 131 Handle Area Validation ................................................................................................................... 5 132 Session Area Validation .................................................................................................................. 6 133 Authorization Checks ...................................................................................................................... 7 134 Parameter Decryption ..................................................................................................................... 8 135 Parameter Unmarshaling ................................................................................................................ 9 136 Command Post Processing .......................................................................................................... 10 137 138 Response Values ................................................................................................................................ 12 139 8.1 140 8.2 141 142 9 143 10 144 145 Implementation Dependent ................................................................................................................. 15 146 Detailed Actions Assumptions ............................................................................................................. 16 147 148 10.1 149 10.2 150 10.3 151 11 152 153 Introduction ................................................................................................................................... 28 154 TPM2_SelfTest ............................................................................................................................. 29 155 TPM2_IncrementalSelfTest .......................................................................................................... 32 156 TPM2_GetTestResult ................................................................................................................... 35 157 158 Session Commands ............................................................................................................................ 38 159 160 13.1 161 13.2 162 14 163 164 Introduction ................................................................................................................................... 17 165 _TPM_Init...................................................................................................................................... 17 166 TPM2_Startup ............................................................................................................................... 19 167 TPM2_Shutdown .......................................................................................................................... 24 168 169 Testing ................................................................................................................................................. 28 170 171 12.1 172 12.2 173 12.3 174 12.4 175 13 176 177 Introduction ................................................................................................................................... 16 178 Pre-processing .............................................................................................................................. 16 179 Post Processing ............................................................................................................................ 16 180 181 Start-up ................................................................................................................................................ 17 182 183 11.1 184 11.2 185 11.3 186 11.4 187 12 188 189 Tag ................................................................................................................................................ 12 190 Response Codes .......................................................................................................................... 12 191 192 TPM2_StartAuthSession .............................................................................................................. 38 193 TPM2_PolicyRestart ..................................................................................................................... 43 194 195 Object Commands............................................................................................................................... 46 196 197 Family 2.0 198 Level 00 Revision 00.99 199 200 Published 201 Copyright TCG 2006-2013 202 203 Page iii 204 October 31, 2013 205 206 Part 3: Commands 208 14.1 209 14.2 210 14.3 211 14.4 212 14.5 213 14.6 214 14.7 215 14.8 216 15 217 218 Introduction ................................................................................................................................. 132 219 TPM2_HMAC_Start .................................................................................................................... 132 220 TPM2_HashSequenceStart ........................................................................................................ 136 221 TPM2_SequenceUpdate ............................................................................................................ 139 222 TPM2_SequenceComplete......................................................................................................... 143 223 TPM2_EventSequenceComplete ............................................................................................... 147 224 225 Attestation Commands ...................................................................................................................... 151 226 227 20.1 228 20.2 229 20.3 230 20.4 231 20.5 232 20.6 233 20.7 234 21 235 236 TPM2_GetRandom ..................................................................................................................... 126 237 TPM2_StirRandom ..................................................................................................................... 129 238 239 Hash/HMAC/Event Sequences ......................................................................................................... 132 240 241 19.1 242 19.2 243 19.3 244 19.4 245 19.5 246 19.6 247 20 248 249 Introduction ................................................................................................................................. 113 250 TPM2_EncryptDecrypt ................................................................................................................ 115 251 TPM2_Hash ................................................................................................................................ 119 252 TPM2_HMAC .............................................................................................................................. 122 253 254 Random Number Generator .............................................................................................................. 126 255 256 18.1 257 18.2 258 19 259 260 Introduction ................................................................................................................................... 92 261 TPM2_RSA_Encrypt ..................................................................................................................... 92 262 TPM2_RSA_Decrypt .................................................................................................................... 97 263 TPM2_ECDH_KeyGen ............................................................................................................... 101 264 TPM2_ECDH_ZGen ................................................................................................................... 104 265 TPM2_ECC_Parameters ............................................................................................................ 107 266 TPM2_ZGen_2Phase ................................................................................................................. 108 267 268 Symmetric Primitives ......................................................................................................................... 113 269 270 17.1 271 17.2 272 17.3 273 17.4 274 18 275 276 TPM2_Duplicate ........................................................................................................................... 77 277 TPM2_Rewrap .............................................................................................................................. 81 278 TPM2_Import ................................................................................................................................ 86 279 280 Asymmetric Primitives ......................................................................................................................... 92 281 282 16.1 283 16.2 284 16.3 285 16.4 286 16.5 287 16.6 288 16.7 289 17 290 291 TPM2_Create................................................................................................................................ 46 292 TPM2_Load .................................................................................................................................. 51 293 TPM2_LoadExternal ..................................................................................................................... 55 294 TPM2_ReadPublic ........................................................................................................................ 60 295 TPM2_ActivateCredential ............................................................................................................. 63 296 TPM2_MakeCredential ................................................................................................................. 67 297 TPM2_Unseal ............................................................................................................................... 70 298 TPM2_ObjectChangeAuth ............................................................................................................ 73 299 300 Duplication Commands ....................................................................................................................... 77 301 302 15.1 303 15.2 304 15.3 305 16 306 307 Trusted Platform Module Library 308 309 Introduction ................................................................................................................................. 151 310 TPM2_Certify .............................................................................................................................. 153 311 TPM2_CertifyCreation ................................................................................................................ 157 312 TPM2_Quote............................................................................................................................... 161 313 TPM2_GetSessionAuditDigest ................................................................................................... 165 314 TPM2_GetCommandAuditDigest ............................................................................................... 169 315 TPM2_GetTime........................................................................................................................... 173 316 317 Ephemeral EC Keys .......................................................................................................................... 177 318 319 Page iv 320 October 31, 2013 321 322 Published 323 Copyright TCG 2006-2013 324 325 Family 2.0 326 Level 00 Revision 00.99 327 328 Trusted Platform Module Library 330 21.1 331 21.2 332 21.3 333 22 334 335 Introduction ................................................................................................................................. 200 336 TPM2_PCR_Extend ................................................................................................................... 201 337 TPM2_PCR_Event ..................................................................................................................... 204 338 TPM2_PCR_Read ...................................................................................................................... 207 339 TPM2_PCR_Allocate .................................................................................................................. 210 340 TPM2_PCR_SetAuthPolicy ........................................................................................................ 213 341 TPM2_PCR_SetAuthValue ......................................................................................................... 216 342 TPM2_PCR_Reset ..................................................................................................................... 219 343 _TPM_Hash_Start ...................................................................................................................... 222 344 _TPM_Hash_Data ...................................................................................................................... 224 345 _TPM_Hash_End ....................................................................................................................... 226 346 347 Enhanced Authorization (EA) Commands ........................................................................................ 229 348 349 25.1 350 25.2 351 25.3 352 25.4 353 25.5 354 25.6 355 25.7 356 25.8 357 25.9 358 25.10 359 25.11 360 25.12 361 25.13 362 25.14 363 25.15 364 25.16 365 25.17 366 25.18 367 25.19 368 25.20 369 26 370 371 Introduction ................................................................................................................................. 195 372 TPM2_SetCommandCodeAuditStatus ....................................................................................... 196 373 374 Integrity Collection (PCR) .................................................................................................................. 200 375 376 24.1 377 24.2 378 24.3 379 24.4 380 24.5 381 24.6 382 24.7 383 24.8 384 24.9 385 24.10 386 24.11 387 25 388 389 TPM2_VerifySignature ................................................................................................................ 187 390 TPM2_Sign ................................................................................................................................. 191 391 392 Command Audit ................................................................................................................................. 195 393 394 23.1 395 23.2 396 24 397 398 Introduction ................................................................................................................................. 177 399 TPM2_Commit ............................................................................................................................ 178 400 TPM2_EC_Ephemeral ................................................................................................................ 184 401 402 Signing and Signature Verification .................................................................................................... 187 403 404 22.1 405 22.2 406 23 407 408 Part 3: Commands 409 410 Introduction ................................................................................................................................. 229 411 Signed Authorization Actions ...................................................................................................... 230 412 TPM2_PolicySigned ................................................................................................................... 234 413 TPM2_PolicySecret .................................................................................................................... 240 414 TPM2_PolicyTicket ..................................................................................................................... 244 415 TPM2_PolicyOR ......................................................................................................................... 248 416 TPM2_PolicyPCR ....................................................................................................................... 252 417 TPM2_PolicyLocality .................................................................................................................. 256 418 TPM2_PolicyNV .......................................................................................................................... 260 419 TPM2_PolicyCounterTimer......................................................................................................... 265 420 TPM2_PolicyCommandCode ..................................................................................................... 270 421 TPM2_PolicyPhysicalPresence .................................................................................................. 273 422 TPM2_PolicyCpHash .................................................................................................................. 276 423 TPM2_PolicyNameHash ............................................................................................................. 280 424 TPM2_PolicyDuplicationSelect ................................................................................................... 283 425 TPM2_PolicyAuthorize ............................................................................................................... 287 426 TPM2_PolicyAuthValue .............................................................................................................. 291 427 TPM2_PolicyPassword ............................................................................................................... 294 428 TPM2_PolicyGetDigest ............................................................................................................... 297 429 TPM2_PolicyNvWritten ............................................................................................................... 300 430 431 Hierarchy Commands........................................................................................................................ 304 432 433 26.1 434 26.2 435 26.3 436 437 TPM2_CreatePrimary ................................................................................................................. 304 438 TPM2_HierarchyControl ............................................................................................................. 308 439 TPM2_SetPrimaryPolicy ............................................................................................................. 312 440 441 Family 2.0 442 Level 00 Revision 00.99 443 444 Published 445 Copyright TCG 2006-2013 446 447 Page v 448 October 31, 2013 449 450 Part 3: Commands 452 26.4 453 26.5 454 26.6 455 26.7 456 26.8 457 27 458 459 TPM2_ReadClock ....................................................................................................................... 372 460 TPM2_ClockSet .......................................................................................................................... 375 461 TPM2_ClockRateAdjust .............................................................................................................. 378 462 463 Capability Commands ....................................................................................................................... 381 464 465 32.1 466 32.2 467 32.3 468 33 469 470 Introduction ................................................................................................................................. 354 471 TPM2_ContextSave .................................................................................................................... 354 472 TPM2_ContextLoad .................................................................................................................... 359 473 TPM2_FlushContext ................................................................................................................... 364 474 TPM2_EvictControl ..................................................................................................................... 367 475 476 Clocks and Timers............................................................................................................................. 372 477 478 31.1 479 31.2 480 31.3 481 32 482 483 Introduction ................................................................................................................................. 343 484 TPM2_FieldUpgradeStart ........................................................................................................... 345 485 TPM2_FieldUpgradeData ........................................................................................................... 348 486 TPM2_FirmwareRead ................................................................................................................. 351 487 488 Context Management ........................................................................................................................ 354 489 490 30.1 491 30.2 492 30.3 493 30.4 494 30.5 495 31 496 497 Introduction ................................................................................................................................. 337 498 TPM2_PP_Commands ............................................................................................................... 337 499 TPM2_SetAlgorithmSet .............................................................................................................. 340 500 501 Field Upgrade .................................................................................................................................... 343 502 503 29.1 504 29.2 505 29.3 506 29.4 507 30 508 509 Introduction ................................................................................................................................. 331 510 TPM2_DictionaryAttackLockReset ............................................................................................. 331 511 TPM2_DictionaryAttackParameters............................................................................................ 334 512 513 Miscellaneous Management Functions ............................................................................................. 337 514 515 28.1 516 28.2 517 28.3 518 29 519 520 TPM2_ChangePPS .................................................................................................................... 315 521 TPM2_ChangeEPS .................................................................................................................... 318 522 TPM2_Clear ................................................................................................................................ 321 523 TPM2_ClearControl .................................................................................................................... 325 524 TPM2_HierarchyChangeAuth ..................................................................................................... 328 525 526 Dictionary Attack Functions ............................................................................................................... 331 527 528 27.1 529 27.2 530 27.3 531 28 532 533 Trusted Platform Module Library 534 535 Introduction ................................................................................................................................. 381 536 TPM2_GetCapability ................................................................................................................... 381 537 TPM2_TestParms ....................................................................................................................... 389 538 539 Non-volatile Storage .......................................................................................................................... 392 540 541 33.1 542 33.2 543 33.3 544 33.4 545 33.5 546 33.6 547 33.7 548 33.8 549 33.9 550 33.10 551 33.11 552 553 Introduction ................................................................................................................................. 392 554 NV Counters ............................................................................................................................... 393 555 TPM2_NV_DefineSpace ............................................................................................................. 394 556 TPM2_NV_UndefineSpace ......................................................................................................... 400 557 TPM2_NV_UndefineSpaceSpecial ............................................................................................. 403 558 TPM2_NV_ReadPublic ............................................................................................................... 406 559 TPM2_NV_Write ......................................................................................................................... 409 560 TPM2_NV_Increment ................................................................................................................. 413 561 TPM2_NV_Extend ...................................................................................................................... 417 562 TPM2_NV_SetBits ...................................................................................................................... 421 563 TPM2_NV_WriteLock ................................................................................................................. 425 564 565 Page vi 566 October 31, 2013 567 568 Published 569 Copyright TCG 2006-2013 570 571 Family 2.0 572 Level 00 Revision 00.99 573 574 Trusted Platform Module Library 576 33.12 577 33.13 578 33.14 579 33.15 580 33.16 581 582 Part 3: Commands 583 584 TPM2_NV_GlobalWriteLock ....................................................................................................... 429 585 TPM2_NV_Read ......................................................................................................................... 432 586 TPM2_NV_ReadLock ................................................................................................................. 435 587 TPM2_NV_ChangeAuth ............................................................................................................. 438 588 TPM2_NV_Certify ....................................................................................................................... 441 589 590 Family 2.0 591 Level 00 Revision 00.99 592 593 Published 594 Copyright TCG 2006-2013 595 596 Page vii 597 October 31, 2013 598 599 Part 3: Commands 601 602 Trusted Platform Module Library 603 604 Tables 605 Table 1 Command Modifiers and Decoration ........................................................................................... 2 606 Table 2 Separators ................................................................................................................................... 3 607 Table 3 Unmarshaling Errors ................................................................................................................. 10 608 Table 4 Command-Independent Response Codes ................................................................................ 13 609 Table 5 TPM2_Startup Command .......................................................................................................... 21 610 Table 6 TPM2_Startup Response .......................................................................................................... 21 611 Table 7 TPM2_Shutdown Command ..................................................................................................... 25 612 Table 8 TPM2_Shutdown Response ...................................................................................................... 25 613 Table 9 TPM2_SelfTest Command ........................................................................................................ 30 614 Table 10 TPM2_SelfTest Response ...................................................................................................... 30 615 Table 11 TPM2_IncrementalSelfTest Command ................................................................................... 33 616 Table 12 TPM2_IncrementalSelfTest Response ................................................................................... 33 617 Table 13 TPM2_GetTestResult Command ............................................................................................ 36 618 Table 14 TPM2_GetTestResult Response............................................................................................. 36 619 Table 15 TPM2_StartAuthSession Command ....................................................................................... 40 620 Table 16 TPM2_StartAuthSession Response ........................................................................................ 40 621 Table 17 TPM2_PolicyRestart Command .............................................................................................. 44 622 Table 18 TPM2_PolicyRestart Response .............................................................................................. 44 623 Table 19 TPM2_Create Command ........................................................................................................ 48 624 Table 20 TPM2_Create Response ......................................................................................................... 48 625 Table 21 TPM2_Load Command ........................................................................................................... 52 626 Table 22 TPM2_Load Response ............................................................................................................ 52 627 Table 23 TPM2_LoadExternal Command .............................................................................................. 57 628 Table 24 TPM2_LoadExternal Response .............................................................................................. 57 629 Table 25 TPM2_ReadPublic Command ................................................................................................. 61 630 Table 26 TPM2_ReadPublic Response ................................................................................................. 61 631 Table 27 TPM2_ActivateCredential Command ...................................................................................... 64 632 Table 28 TPM2_ActivateCredential Response ...................................................................................... 64 633 Table 29 TPM2_MakeCredential Command .......................................................................................... 68 634 Table 30 TPM2_MakeCredential Response .......................................................................................... 68 635 Table 31 TPM2_Unseal Command ........................................................................................................ 71 636 Table 32 TPM2_Unseal Response ........................................................................................................ 71 637 Table 33 TPM2_ObjectChangeAuth Command ..................................................................................... 74 638 Table 34 TPM2_ObjectChangeAuth Response ..................................................................................... 74 639 Table 35 TPM2_Duplicate Command .................................................................................................... 78 640 Table 36 TPM2_Duplicate Response ..................................................................................................... 78 641 Table 37 TPM2_Rewrap Command ....................................................................................................... 82 642 Table 38 TPM2_Rewrap Response ....................................................................................................... 82 643 Page viii 644 October 31, 2013 645 646 Published 647 Copyright TCG 2006-2013 648 649 Family 2.0 650 Level 00 Revision 00.99 651 652 Trusted Platform Module Library 654 655 Part 3: Commands 656 657 Table 39 TPM2_Import Command ......................................................................................................... 88 658 Table 40 TPM2_Import Response ......................................................................................................... 88 659 Table 41 Padding Scheme Selection ..................................................................................................... 92 660 Table 42 Message Size Limits Based on Padding ................................................................................. 93 661 Table 43 TPM2_RSA_Encrypt Command.............................................................................................. 94 662 Table 44 TPM2_RSA_Encrypt Response .............................................................................................. 94 663 Table 45 TPM2_RSA_Decrypt Command ............................................................................................. 98 664 Table 46 TPM2_RSA_Decrypt Response .............................................................................................. 98 665 Table 47 TPM2_ECDH_KeyGen Command ........................................................................................ 102 666 Table 48 TPM2_ECDH_KeyGen Response ........................................................................................ 102 667 Table 49 TPM2_ECDH_ZGen Command ............................................................................................ 105 668 Table 50 TPM2_ECDH_ZGen Response ............................................................................................ 105 669 Table 51 TPM2_ECC_Parameters Command ..................................................................................... 107 670 Table 52 TPM2_ECC_Parameters Response ..................................................................................... 107 671 Table 53 TPM2_ZGen_2Phase Command .......................................................................................... 110 672 Table 54 TPM2_ZGen_2Phase Response .......................................................................................... 110 673 Table 55 Symmetric Chaining Process ................................................................................................ 114 674 Table 56 TPM2_EncryptDecrypt Command......................................................................................... 116 675 Table 57 TPM2_EncryptDecrypt Response ......................................................................................... 116 676 Table 58 TPM2_Hash Command ......................................................................................................... 120 677 Table 59 TPM2_Hash Response ......................................................................................................... 120 678 Table 60 TPM2_HMAC Command ....................................................................................................... 123 679 Table 61 TPM2_HMAC Response ....................................................................................................... 123 680 Table 62 TPM2_GetRandom Command .............................................................................................. 127 681 Table 63 TPM2_GetRandom Response .............................................................................................. 127 682 Table 64 TPM2_StirRandom Command .............................................................................................. 130 683 Table 65 TPM2_StirRandom Response ............................................................................................... 130 684 Table 66 Hash Selection Matrix ........................................................................................................... 132 685 Table 67 TPM2_HMAC_Start Command ............................................................................................. 133 686 Table 68 TPM2_HMAC_Start Response ............................................................................................. 133 687 Table 69 TPM2_HashSequenceStart Command ................................................................................. 137 688 Table 70 TPM2_HashSequenceStart Response ................................................................................. 137 689 Table 71 TPM2_SequenceUpdate Command ..................................................................................... 140 690 Table 72 TPM2_SequenceUpdate Response ...................................................................................... 140 691 Table 73 TPM2_SequenceComplete Command ................................................................................. 144 692 Table 74 TPM2_SequenceComplete Response .................................................................................. 144 693 Table 75 TPM2_EventSequenceComplete Command ........................................................................ 148 694 Table 76 TPM2_EventSequenceComplete Response ......................................................................... 148 695 Table 77 TPM2_Certify Command ....................................................................................................... 154 696 Family 2.0 697 Level 00 Revision 00.99 698 699 Published 700 Copyright TCG 2006-2013 701 702 Page ix 703 October 31, 2013 704 705 Part 3: Commands 707 708 Trusted Platform Module Library 709 710 Table 78 TPM2_Certify Response ....................................................................................................... 154 711 Table 79 TPM2_CertifyCreation Command ......................................................................................... 158 712 Table 80 TPM2_CertifyCreation Response .......................................................................................... 158 713 Table 81 TPM2_Quote Command ....................................................................................................... 162 714 Table 82 TPM2_Quote Response ........................................................................................................ 162 715 Table 83 TPM2_GetSessionAuditDigest Command ............................................................................ 166 716 Table 84 TPM2_GetSessionAuditDigest Response ............................................................................ 166 717 Table 85 TPM2_GetCommandAuditDigest Command ........................................................................ 170 718 Table 86 TPM2_GetCommandAuditDigest Response ......................................................................... 170 719 Table 87 TPM2_GetTime Command ................................................................................................... 174 720 Table 88 TPM2_GetTime Response .................................................................................................... 174 721 Table 89 TPM2_Commit Command ..................................................................................................... 180 722 Table 90 TPM2_Commit Response ..................................................................................................... 180 723 Table 91 TPM2_EC_Ephemeral Command ......................................................................................... 185 724 Table 92 TPM2_EC_Ephemeral Response ......................................................................................... 185 725 Table 93 TPM2_VerifySignature Command......................................................................................... 188 726 Table 94 TPM2_VerifySignature Response ......................................................................................... 188 727 Table 95 TPM2_Sign Command .......................................................................................................... 192 728 Table 96 TPM2_Sign Response .......................................................................................................... 192 729 Table 97 TPM2_SetCommandCodeAuditStatus Command ................................................................ 197 730 Table 98 TPM2_SetCommandCodeAuditStatus Response ................................................................ 197 731 Table 99 TPM2_PCR_Extend Command ............................................................................................ 202 732 Table 100 TPM2_PCR_Extend Response ........................................................................................... 202 733 Table 101 TPM2_PCR_Event Command ............................................................................................ 205 734 Table 102 TPM2_PCR_Event Response ............................................................................................. 205 735 Table 103 TPM2_PCR_Read Command ............................................................................................. 208 736 Table 104 TPM2_PCR_Read Response ............................................................................................. 208 737 Table 105 TPM2_PCR_Allocate Command ......................................................................................... 211 738 Table 106 TPM2_PCR_Allocate Response ......................................................................................... 211 739 Table 107 TPM2_PCR_SetAuthPolicy Command ............................................................................... 214 740 Table 108 TPM2_PCR_SetAuthPolicy Response ............................................................................... 214 741 Table 109 TPM2_PCR_SetAuthValue Command ............................................................................... 217 742 Table 110 TPM2_PCR_SetAuthValue Response ................................................................................ 217 743 Table 111 TPM2_PCR_Reset Command ............................................................................................ 220 744 Table 112 TPM2_PCR_Reset Response ............................................................................................. 220 745 Table 113 TPM2_PolicySigned Command .......................................................................................... 236 746 Table 114 TPM2_PolicySigned Response ........................................................................................... 236 747 Table 115 TPM2_PolicySecret Command ........................................................................................... 241 748 Table 116 TPM2_PolicySecret Response ............................................................................................ 241 749 Page x 750 October 31, 2013 751 752 Published 753 Copyright TCG 2006-2013 754 755 Family 2.0 756 Level 00 Revision 00.99 757 758 Trusted Platform Module Library 760 761 Part 3: Commands 762 763 Table 117 TPM2_PolicyTicket Command ............................................................................................ 245 764 Table 118 TPM2_PolicyTicket Response ............................................................................................ 245 765 Table 119 TPM2_PolicyOR Command ................................................................................................ 249 766 Table 120 TPM2_PolicyOR Response ................................................................................................. 249 767 Table 121 TPM2_PolicyPCR Command .............................................................................................. 253 768 Table 122 TPM2_PolicyPCR Response .............................................................................................. 253 769 Table 123 TPM2_PolicyLocality Command ......................................................................................... 257 770 Table 124 TPM2_PolicyLocality Response .......................................................................................... 257 771 Table 125 TPM2_PolicyNV Command ................................................................................................. 261 772 Table 126 TPM2_PolicyNV Response ................................................................................................. 261 773 Table 127 TPM2_PolicyCounterTimer Command ............................................................................... 266 774 Table 128 TPM2_PolicyCounterTimer Response ................................................................................ 266 775 Table 129 TPM2_PolicyCommandCode Command ............................................................................ 271 776 Table 130 TPM2_PolicyCommandCode Response ............................................................................. 271 777 Table 131 TPM2_PolicyPhysicalPresence Command ......................................................................... 274 778 Table 132 TPM2_PolicyPhysicalPresence Response ......................................................................... 274 779 Table 133 TPM2_PolicyCpHash Command......................................................................................... 277 780 Table 134 TPM2_PolicyCpHash Response ......................................................................................... 277 781 Table 135 TPM2_PolicyNameHash Command.................................................................................... 281 782 Table 136 TPM2_PolicyNameHash Response .................................................................................... 281 783 Table 137 TPM2_PolicyDuplicationSelect Command .......................................................................... 284 784 Table 138 TPM2_PolicyDuplicationSelect Response .......................................................................... 284 785 Table 139 TPM2_PolicyAuthorize Command ...................................................................................... 288 786 Table 140 TPM2_PolicyAuthorize Response ....................................................................................... 288 787 Table 141 TPM2_PolicyAuthValue Command ..................................................................................... 292 788 Table 142 TPM2_PolicyAuthValue Response ..................................................................................... 292 789 Table 143 TPM2_PolicyPassword Command ...................................................................................... 295 790 Table 144 TPM2_PolicyPassword Response ...................................................................................... 295 791 Table 145 TPM2_PolicyGetDigest Command...................................................................................... 298 792 Table 146 TPM2_PolicyGetDigest Response ...................................................................................... 298 793 Table 133 TPM2_PolicyNvWritten Command ...................................................................................... 301 794 Table 134 TPM2_PolicyNvWritten Response ...................................................................................... 301 795 Table 147 TPM2_CreatePrimary Command ........................................................................................ 305 796 Table 148 TPM2_CreatePrimary Response ........................................................................................ 305 797 Table 149 TPM2_HierarchyControl Command .................................................................................... 309 798 Table 150 TPM2_HierarchyControl Response .................................................................................... 309 799 Table 151 TPM2_SetPrimaryPolicy Command .................................................................................... 313 800 Table 152 TPM2_SetPrimaryPolicy Response .................................................................................... 313 801 Table 153 TPM2_ChangePPS Command ........................................................................................... 316 802 Family 2.0 803 Level 00 Revision 00.99 804 805 Published 806 Copyright TCG 2006-2013 807 808 Page xi 809 October 31, 2013 810 811 Part 3: Commands 813 814 Trusted Platform Module Library 815 816 Table 154 TPM2_ChangePPS Response ............................................................................................ 316 817 Table 155 TPM2_ChangeEPS Command ........................................................................................... 319 818 Table 156 TPM2_ChangeEPS Response ............................................................................................ 319 819 Table 157 TPM2_Clear Command ....................................................................................................... 322 820 Table 158 TPM2_Clear Response ....................................................................................................... 322 821 Table 159 TPM2_ClearControl Command ........................................................................................... 326 822 Table 160 TPM2_ClearControl Response ........................................................................................... 326 823 Table 161 TPM2_HierarchyChangeAuth Command ............................................................................ 329 824 Table 162 TPM2_HierarchyChangeAuth Response ............................................................................ 329 825 Table 163 TPM2_DictionaryAttackLockReset Command .................................................................... 332 826 Table 164 TPM2_DictionaryAttackLockReset Response .................................................................... 332 827 Table 165 TPM2_DictionaryAttackParameters Command .................................................................. 335 828 Table 166 TPM2_DictionaryAttackParameters Response ................................................................... 335 829 Table 167 TPM2_PP_Commands Command ...................................................................................... 338 830 Table 168 TPM2_PP_Commands Response ...................................................................................... 338 831 Table 169 TPM2_SetAlgorithmSet Command ..................................................................................... 341 832 Table 170 TPM2_SetAlgorithmSet Response...................................................................................... 341 833 Table 171 TPM2_FieldUpgradeStart Command .................................................................................. 346 834 Table 172 TPM2_FieldUpgradeStart Response .................................................................................. 346 835 Table 173 TPM2_FieldUpgradeData Command .................................................................................. 349 836 Table 174 TPM2_FieldUpgradeData Response .................................................................................. 349 837 Table 175 TPM2_FirmwareRead Command........................................................................................ 352 838 Table 176 TPM2_FirmwareRead Response ........................................................................................ 352 839 Table 177 TPM2_ContextSave Command........................................................................................... 355 840 Table 178 TPM2_ContextSave Response ........................................................................................... 355 841 Table 179 TPM2_ContextLoad Command ........................................................................................... 360 842 Table 180 TPM2_ContextLoad Response ........................................................................................... 360 843 Table 181 TPM2_FlushContext Command .......................................................................................... 365 844 Table 182 TPM2_FlushContext Response .......................................................................................... 365 845 Table 183 TPM2_EvictControl Command ............................................................................................ 369 846 Table 184 TPM2_EvictControl Response ............................................................................................ 369 847 Table 185 TPM2_ReadClock Command.............................................................................................. 373 848 Table 186 TPM2_ReadClock Response .............................................................................................. 373 849 Table 187 TPM2_ClockSet Command ................................................................................................. 376 850 Table 188 TPM2_ClockSet Response ................................................................................................. 376 851 Table 189 TPM2_ClockRateAdjust Command..................................................................................... 379 852 Table 190 TPM2_ClockRateAdjust Response ..................................................................................... 379 853 Table 191 TPM2_GetCapability Command.......................................................................................... 385 854 Table 192 TPM2_GetCapability Response .......................................................................................... 385 855 Page xii 856 October 31, 2013 857 858 Published 859 Copyright TCG 2006-2013 860 861 Family 2.0 862 Level 00 Revision 00.99 863 864 Trusted Platform Module Library 866 867 Part 3: Commands 868 869 Table 193 TPM2_TestParms Command .............................................................................................. 390 870 Table 194 TPM2_TestParms Response .............................................................................................. 390 871 Table 195 TPM2_NV_DefineSpace Command ................................................................................... 396 872 Table 196 TPM2_NV_DefineSpace Response .................................................................................... 396 873 Table 197 TPM2_NV_UndefineSpace Command ............................................................................... 401 874 Table 198 TPM2_NV_UndefineSpace Response ................................................................................ 401 875 Table 199 TPM2_NV_UndefineSpaceSpecial Command .................................................................... 404 876 Table 200 TPM2_NV_UndefineSpaceSpecial Response .................................................................... 404 877 Table 201 TPM2_NV_ReadPublic Command ...................................................................................... 407 878 Table 202 TPM2_NV_ReadPublic Response ...................................................................................... 407 879 Table 203 TPM2_NV_Write Command ................................................................................................ 410 880 Table 204 TPM2_NV_Write Response ................................................................................................ 410 881 Table 205 TPM2_NV_Increment Command ........................................................................................ 414 882 Table 206 TPM2_NV_Increment Response......................................................................................... 414 883 Table 207 TPM2_NV_Extend Command ............................................................................................. 418 884 Table 208 TPM2_NV_Extend Response ............................................................................................. 418 885 Table 209 TPM2_NV_SetBits Command ............................................................................................. 422 886 Table 210 TPM2_NV_SetBits Response ............................................................................................. 422 887 Table 211 TPM2_NV_WriteLock Command ........................................................................................ 426 888 Table 212 TPM2_NV_WriteLock Response......................................................................................... 426 889 Table 213 TPM2_NV_GlobalWriteLock Command .............................................................................. 430 890 Table 214 TPM2_NV_GlobalWriteLock Response .............................................................................. 430 891 Table 215 TPM2_NV_Read Command................................................................................................ 433 892 Table 216 TPM2_NV_Read Response ................................................................................................ 433 893 Table 217 TPM2_NV_ReadLock Command ........................................................................................ 436 894 Table 218 TPM2_NV_ReadLock Response ........................................................................................ 436 895 Table 219 TPM2_NV_ChangeAuth Command .................................................................................... 439 896 Table 220 TPM2_NV_ChangeAuth Response .................................................................................... 439 897 Table 221 TPM2_NV_Certify Command .............................................................................................. 442 898 Table 222 TPM2_NV_Certify Response .............................................................................................. 442 899 900 Family 2.0 901 Level 00 Revision 00.99 902 903 Published 904 Copyright TCG 2006-2013 905 906 Page xiii 907 October 31, 2013 908 909 Trusted Platform Module Library 912 913 Part 3: Commands 914 915 Trusted Platform Module Library 916 Part 3: Commands 917 1 918 919 Scope 920 921 This part 3 of the Trusted Module Library specification contains the definitions of the TPM commands. 922 These commands make use of the constants, flags, structure, and union definitions defined in part 2: 923 Structures. 924 The detailed description of the operation of the commands is written in the C language with extensive 925 comments. The behavior of the C code in this part 3 is normative but does not fully describe the behavior 926 of a TPM. The combination of this part 3 and part 4: Supporting Routines is sufficient to fully describe the 927 required behavior of a TPM. 928 The code in parts 3 and 4 is written to define the behavior of a compliant TPM. In some cases (e.g., 929 firmware update), it is not possible to provide a compliant implementation. In those cases, any 930 implementation provided by the vendor that meets the general description of the function provided in part 931 3 would be compliant. 932 The code in parts 3 and 4 is not written to meet any particular level of conformance nor does this 933 specification require that a TPM meet any particular level of conformance. 934 2 935 936 Terms and Definitions 937 938 For the purposes of this document, the terms and definitions given in part 1 of this specification apply. 939 3 940 941 Symbols and abbreviated terms 942 943 For the purposes of this document, the symbols and abbreviated terms given in part 1 apply. 944 4 945 946 Notation 947 948 4.1 Introduction 949 In addition to the notation in this clause, the Notations clause in Part 1 of this specification is applicable 950 to this Part 3. 951 Command and response tables used various decorations to indicate the fields of the command and the 952 allowed types. These decorations are described in this clause. 953 4.2 954 955 Table Decorations 956 957 The symbols and terms in the Notation column of Table 1 are used in the tables for the command 958 schematics. These values indicate various qualifiers for the parameters or descriptions with which they 959 are associated. 960 961 Family 2.0 962 Level 00 Revision 00.99 963 964 Published 965 Copyright TCG 2006-2013 966 967 Page 1 968 October 31, 2013 969 970 Part 3: Commands 972 973 Trusted Platform Module Library 974 Table 1 Command Modifiers and Decoration 975 976 Notation 977 978 Meaning 979 980 + 981 982 A Type decoration When appended to a value in the Type column of a command, this symbol 983 indicates that the parameter is allowed to use the null value of the data type (see "Conditional 984 Types" in Part 2). The null value is usually TPM_RH_NULL for a handle or TPM_ALG_NULL for 985 an algorithm selector. 986 987 @ 988 989 A Name decoration When this symbol precedes a handle parameter in the Name column, it 990 indicates that an authorization session is required for use of the entity associated with the handle. 991 If a handle does not have this symbol, then an authorization session is not allowed. 992 993 +PP 994 995 A Description modifier This modifier may follow TPM_RH_PLATFORM in the Description 996 column to indicate that Physical Presence is required when platformAuth/platformPolicy is 997 provided. 998 999 +{PP} 1000 1001 A Description modifier This modifier may follow TPM_RH_PLATFORM to indicate that Physical 1002 Presence may be required when platformAuth/platformPolicy is provided. The commands with this 1003 notation may be in the setList or clearList of TPM2_PP_Commands(). 1004 1005 {NV} 1006 1007 A Description modifier This modifier may follow the commandCode in the Description column 1008 to indicate that the command may result in an update of NV memory and be subject to rate 1009 throttling by the TPM. If the command code does not have this notation, then a write to NV 1010 memory does not occur as part of the command actions. 1011 NOTE Any command that uses authorization may cause a write to NV if there is an authorization 1012 failure. A TPM may use the occasion of command execution to update the NV 1013 copy of clock. 1014 1015 {F} 1016 1017 A Description modifier This modifier indicates that the flushed attribute will be SET in the 1018 TPMA_CC for the command. The modifier may follow the commandCode in the Description 1019 column to indicate that any transient handle context used by the command will be flushed from the 1020 TPM when the command completes. This may be combined with the {NV} modifier but not with the 1021 {E} modifier. 1022 EXAMPLE 1 1023 1024 {E} 1025 1026 {NV F} 1027 1028 EXAMPLE 2 1029 1030 TPM2_SequenceComplete() will flush the context associated with the sequenceHandle. 1031 1032 A Description modifier This modifier indicates that the extensive attribute will be SET in the 1033 TPMA_CC for the command. This modifier may follow the commandCode in the Description 1034 column to indicate that the command may flush many objects and re-enumeration of the loaded 1035 context likely will be required. This may be combined with the {NV} modifier but not with the {F} 1036 modifier. 1037 EXAMPLE 1 1038 1039 Auth Index: 1040 1041 {NV E} 1042 1043 EXAMPLE 2 1044 1045 TPM2_Clear() will flush all contexts associated with the Storage hierarchy and the 1046 Endorsement hierarchy. 1047 1048 A Description modifier When a handle has a @ decoration, the Description column will 1049 contain an Auth Index: entry for the handle. This entry indicates the number of the authorization 1050 session. The authorization sessions associated with handles will occur in the session area in the 1051 order of the handles with the @ modifier. Sessions used only for encryption/decryption or only for 1052 audit will follow the handles used for authorization. 1053 1054 Page 2 1055 October 31, 2013 1056 1057 Published 1058 Copyright TCG 2006-2013 1059 1060 Family 2.0 1061 Level 00 Revision 00.99 1062 1063 Trusted Platform Module Library 1065 1066 Part 3: Commands 1067 1068 Notation 1069 1070 Meaning 1071 1072 Auth Role: 1073 1074 A Description modifier This will be in the Description column of a handle with the @ 1075 decoration. It may have a value of USER, ADMIN or DUP. If the handle has the Auth Role of 1076 USER and the handle is an Object, the type of authorization is determined by the setting of 1077 userWithAuth in the Object's attributes. If the Auth Role is ADMIN and the handle is an Object, the 1078 type of authorization is determined by the setting of adminWithPolicy in the Object's attributes. If 1079 the DUP role is selected, authorization may only be with a policy session (DUP role only applies to 1080 Objects). When either ADMIN or DUP role is selected, a policy command that selects the 1081 command being authorized is required to be part of the policy. 1082 EXAMPLE 1083 1084 TPM2_Certify requires the ADMIN role for the first handle (objectHandle). The policy authorization 1085 for objectHandle is required to contain TPM2_PolicyCommandCode(commandCode == 1086 TPM_CC_Certify). This sets the state of the policy so that it can be used for ADMIN role 1087 authorization in TPM2_Certify(). 1088 1089 If the handle references an NV Index, then the allowed authorizations are determined by the 1090 settings of the attributes of the NV Index as described in Part 2, "TPMA_NV (NV Index Attributes)." 1091 1092 4.3 1093 1094 Handle and Parameter Demarcation 1095 1096 The demarcations between the header, handle, and parameter parts are indicated by: 1097 Table 2 Separators 1098 Separator 1099 1100 Meaning 1101 the values immediately following are in the handle area 1102 the values immediately following are in the parameter area 1103 1104 4.4 1105 1106 AuthorizationSize and ParameterSize 1107 1108 Authorization sessions are not shown in the command or response schematics. When the tag of a 1109 command or response is TPM_ST_SESSIONS, then a 32-bit value will be present in the 1110 command/response buffer to indicate the size of the authorization field or the parameter field. This value 1111 shall immediately follow the handle area (which may contain no handles). For a command, this value 1112 (authorizationSize) indicates the size of the Authorization Area and shall have a value of 9 or more. For a 1113 response, this value (parameterSize) indicates the size of the parameter area and may have a value of 1114 zero. 1115 If the authorizationSize field is present in the command, parameterSize will be present in the response, 1116 but only if the responseCode is TPM_RC_SUCCESS. 1117 When the command tag is TPM_ST_NO_SESSIONS, no authorizations are present and no 1118 authorizationSize field is required and shall not be present. 1119 1120 Family 2.0 1121 Level 00 Revision 00.99 1122 1123 Published 1124 Copyright TCG 2006-2013 1125 1126 Page 3 1127 October 31, 2013 1128 1129 Part 3: Commands 1131 1132 5 1133 1134 Trusted Platform Module Library 1135 1136 Normative References 1137 1138 The Normative References clause in Part 1 of this specification is applicable to this Part 3. 1139 6 1140 1141 Symbols and Abbreviated Terms 1142 1143 The Symbols and Abbreviated Terms clause in Part 1 of this specification is applicable to this Part 3. 1144 1145 7 1146 7.1 1147 1148 Command Processing 1149 Introduction 1150 1151 This clause defines the command validations that are required of any implementation and the response 1152 code returned if the indicated check fails. Unless stated otherwise, the order of the checks is not 1153 normative and different TPM may give different responses when a command has multiple errors. 1154 In the description below, some statements that describe a check may be followed by a response code in 1155 parentheses. This is the normative response code should the indicated check fail. A normative response 1156 code may also be included in the statement. 1157 7.2 1158 1159 Command Header Validation 1160 1161 Before a TPM may begin the actions associated with a command, a set of command format and 1162 consistency checks shall be performed. These checks are listed below and should be performed in the 1163 indicated order. 1164 a) The TPM shall successfully unmarshal a TPMI_ST_COMMAND_TAG and verify that it is either 1165 TPM_ST_SESSIONS or TPM_ST_NO_SESSIONS (TPM_RC_BAD_TAG). 1166 b) The TPM shall successfully unmarshal a UINT32 as the commandSize. If the TPM has an interface 1167 buffer that is loaded by some hardware process, the number of octets in the input buffer for the 1168 command reported by the hardware process shall exactly match the value in commandSize 1169 (TPM_RC_COMMAND_SIZE). 1170 NOTE 1171 1172 A TPM may have direct access to system memory and unmarshal directly from that memory. 1173 1174 c) The TPM shall successfully unmarshal a TPM_CC and verify that the command is implemented 1175 (TPM_RC_COMMAND_CODE). 1176 7.3 1177 1178 Mode Checks 1179 1180 The following mode checks shall be performed in the order listed: 1181 1182 Page 4 1183 October 31, 2013 1184 1185 Published 1186 Copyright TCG 2006-2013 1187 1188 Family 2.0 1189 Level 00 Revision 00.99 1190 1191 Trusted Platform Module Library 1193 1194 Part 3: Commands 1195 1196 a) If the TPM is in Failure mode, then the commandCode is TPM_CC_GetTestResult or 1197 TPM_CC_GetCapability (TPM_RC_FAILURE) and the command tag is TPM_ST_NO_SESSIONS 1198 (TPM_RC_FAILURE). 1199 NOTE 1 1200 1201 In Failure mode, the TPM has no cryptographic capability and proc essing of sessions is not 1202 supported. 1203 1204 b) The TPM is in Field Upgrade mode (FUM), the commandCode is TPM_CC_FieldUpgradeData 1205 (TPM_RC_UPGRADE). 1206 c) If the TPM has not been initialized (TPM2_Startup()), then the commandCode is TPM_CC_Startup 1207 (TPM_RC_INITIALIZE). 1208 NOTE 2 1209 1210 The TPM may enter Failure mode during _TPM_Init processing, before TPM2_Startup(). Since 1211 the platform firmware cannot know that the TPM is in Failure mode without accessing it, and 1212 since the first command is required to be TPM2_Startup(), the expected sequence will be that 1213 platform firmware (the CRTM) will issue TPM2_Startup() and receive TPM_RC_FAILURE 1214 indicating that the TPM is in Failure mode. 1215 There may be failures where a TPM cannot record that it received TPM2_Startup(). In those 1216 cases, a TPM in failure mode may process TPM2_GetTestResult(), TPM2_GetCapability(), or 1217 the field upgrade commands. As a side effect, that TPM may process TPM2_GetTestResult(), 1218 TPM2_GetCapability() or the field upgrade commands before TPM2_Startup(). 1219 This is a corner case exception to the rule that TPM2_Startup() must be the first command. 1220 1221 The mode checks may be performed before or after the command header validation. 1222 7.4 Handle Area Validation 1223 After successfully unmarshaling and validating the command header, the TPM shall perform the following 1224 checks on the handles and sessions. These checks may be performed in any order. 1225 a) The TPM shall successfully unmarshal the number of handles required by the command and validate 1226 that the value of the handle is consistent with the command syntax. If not, the TPM shall return 1227 TPM_RC_VALUE. 1228 NOTE 1 1229 1230 The TPM may unmarshal a handle and validate that it references an entity on the TPM before 1231 unmarshaling a subsequent handle. 1232 1233 NOTE 2 1234 1235 If the submitted command contains fewer handles than required by the syntax of the command, 1236 the TPM may continue to read into the next area and attempt to interpret the data as a handle. 1237 1238 b) For all handles in the handle area of the command, the TPM will validate that the referenced entity is 1239 present in the TPM. 1240 1) If the handle references a transient object, the handle shall reference a loaded object 1241 (TPM_RC_REFERENCE_H0 + N where N is the number of the handle in the command). 1242 NOTE 3 1243 1244 If the hierarchy for a transient object is disabled, then the transient objects will be flushe d so this 1245 check will fail. 1246 1247 2) If the handle references a persistent object, then 1248 i) 1249 1250 the handle shall reference a persistent object that is currently in TPM non-volatile memory 1251 (TPM_RC_HANDLE); 1252 1253 ii) 1254 1255 the hierarchy associated with the object is not disabled (TPM_RC_HIERARCHY); and 1256 1257 iii) if the TPM implementation moves a persistent object to RAM for command processing then 1258 sufficient RAM space is available (TPM_RC_OBJECT_MEMORY). 1259 1260 Family 2.0 1261 Level 00 Revision 00.99 1262 1263 Published 1264 Copyright TCG 2006-2013 1265 1266 Page 5 1267 October 31, 2013 1268 1269 Part 3: Commands 1271 1272 Trusted Platform Module Library 1273 1274 3) If the handle references an NV Index, then 1275 i) 1276 1277 an Index exists that corresponds to the handle (TPM_RC_HANDLE); and 1278 1279 ii) 1280 1281 the hierarchy associated with the existing NV Index is not disabled (TPM_RC_HANDLE). 1282 1283 iii) the hierarchy associated 1284 (TPM_RC_HIERARCHY) 1285 1286 with 1287 1288 an 1289 1290 NV 1291 1292 index 1293 1294 being 1295 1296 defined 1297 1298 is 1299 1300 not 1301 1302 disabled 1303 1304 4) If the handle references a session, then the session context shall be present in TPM memory 1305 (TPM_RC_REFERENCE_S0 + N). 1306 5) If the handle references a primary seed for a hierarchy (TPM_RH_ENDORSEMENT, 1307 TPM_RH_OWNER, or TPM_RH_PLATFORM) then the enable for the hierarchy is SET 1308 (TPM_RC_HIERARCHY). 1309 6) If the handle references a PCR, then the value is within the range of PCR supported by the TPM 1310 (TPM_RC_VALUE) 1311 NOTE 4 1312 1313 7.5 1314 1315 In the reference implementation, this TPM_RC_VALUE is returned by the unmarshaling code for 1316 a TPMI_DH_PCR. 1317 1318 Session Area Validation 1319 1320 a) If the tag is TPM_ST_SESSIONS and the command is a context management command 1321 (TPM2_ContextSave(), TPM2_ContextLoad(), or TPM2_FlushContext()) the TPM will return 1322 TPM_RC_AUTH_CONTEXT. 1323 b) If the tag is TPM_ST_SESSIONS, the TPM will attempt to unmarshal an authorizationSize and return 1324 TPM_RC_AUTHSIZE if the value is not within an acceptable range. 1325 1) The minimum value is (sizeof(TPM_HANDLE) + sizeof(UINT16) + sizeof(TPMA_SESSION) + 1326 sizeof(UINT16)). 1327 2) The maximum value of authorizationSize is equal to commandSize (sizeof(TPM_ST) + 1328 sizeof(UINT32) + sizeof(TPM_CC) + (N * sizeof(TPM_HANDLE)) + sizeof(UINT32)) where N is 1329 the number of handles associated with the commandCode and may be zero. 1330 NOTE 1 1331 1332 (sizeof(TPM_ST) + sizeof(UINT32) + sizeof(TPM_CC)) is the size of a command header. The 1333 last UINT32 contains the authorizationSize octets, which are not counted as being in the 1334 authorization session area. 1335 1336 c) The TPM will unmarshal the authorization sessions and perform the following validations: 1337 1) If the session handle is not a handle for an HMAC session, a handle for a policy session, or, 1338 TPM_RS_PW then the TPM shall return TPM_RC_HANDLE. 1339 2) If the session is not loaded, the TPM will return the warning TPM_RC_REFERENCE_S0 + N 1340 where N is the number of the session. The first session is session zero, N = 0. 1341 NOTE 2 1342 1343 If the HMAC and policy session contexts use the same memory, the type of the context must 1344 match the type of the handle. 1345 1346 3) If the maximum allowed number of sessions have been unmarshaled and fewer octets than 1347 indicated in authorizationSize were unmarshaled (that is, authorizationSize is too large), the TPM 1348 shall return TPM_RC_AUTHSIZE. 1349 1350 Page 6 1351 October 31, 2013 1352 1353 Published 1354 Copyright TCG 2006-2013 1355 1356 Family 2.0 1357 Level 00 Revision 00.99 1358 1359 Trusted Platform Module Library 1361 1362 Part 3: Commands 1363 1364 4) The consistency of the authorization session attributes is checked. 1365 i) 1366 1367 An authorization session is present for each of the handles with the @ decoration 1368 (TPM_RC_AUTH_MISSING). 1369 1370 ii) 1371 1372 Only one session is allowed for: 1373 (a) session auditing (TPM_RC_ATTRIBUTES) this session may be used for encrypt or 1374 decrypt but may not be a session that is also used for authorization; 1375 (b) decrypting a command parameter (TPM_RC_ATTRIBUTES) this may be any of the 1376 authorization sessions, or the audit session, or a session may be added for the single 1377 purpose of decrypting a command parameter, as long as the total number of sessions 1378 does not exceed three; and 1379 (c) encrypting a response parameter (TPM_RC_ATTRIBUTES) this may be any of the 1380 authorization sessions, or the audit session if present, ora session may be added for the 1381 single purpose of encrypting a response parameter, as long as the total number of 1382 sessions does not exceed three. 1383 NOTE 3 1384 1385 7.6 1386 1387 A session used for decrypting a command parameter may also be used for 1388 encrypting a response parameter. 1389 1390 Authorization Checks 1391 1392 After unmarshaling and validating the handles and the consistency of the authorization sessions, the 1393 authorizations shall be checked. Authorization checks only apply to handles if the handle in the command 1394 schematic has the @ decoration. 1395 a) The public and sensitive portions 1396 (TPM_RC_AUTH_UNAVAILABLE). 1397 1398 of 1399 1400 the 1401 1402 object 1403 1404 shall 1405 1406 be 1407 1408 present 1409 1410 on 1411 1412 the 1413 1414 TPM 1415 1416 b) If the associated handle is TPM_RH_PLATFORM, and the command requires confirmation with 1417 physical presence, then physical presence is asserted (TPM_RC_PP). 1418 c) If the object or NV Index is subject to DA protection, and the authorization is with an HMAC or 1419 password, then the TPM is not in lockout (TPM_RC_LOCKOUT). 1420 NOTE 1 1421 1422 An object is subject to DA protection if its noDA attribute is CLEAR. An NV Index is subject to 1423 DA protection if its TPMA_NV_NO_DA attribute is CLEAR. 1424 1425 NOTE 2 1426 1427 An HMAC or password is required in a policy 1428 TPM2_PolicyAuthValue() or TPM2_PolicyPassword(). 1429 1430 session 1431 1432 when 1433 1434 the 1435 1436 policy 1437 1438 contains 1439 1440 d) If the command requires a handle to have DUP role authorization, then the associated authorization 1441 session is a policy session (TPM_RC_POLICY_FAIL). 1442 e) If the command requires a handle to have ADMIN role authorization: 1443 1) If the entity being authorized is an object and its adminWithPolicy attribute is SET, then the 1444 authorization session is a policy session (TPM_RC_POLICY_FAIL). 1445 NOTE 3 1446 1447 If adminWithPolicy is CLEAR, then any type of authorization session is allowed . 1448 1449 2) If the entity being authorized is an NV Index, then the associated authorization session is a policy 1450 session. 1451 NOTE 4 1452 1453 The only commands that are currently defined that required use of ADMIN role authorization are 1454 commands that operate on objects and NV Indices. 1455 1456 Family 2.0 1457 Level 00 Revision 00.99 1458 1459 Published 1460 Copyright TCG 2006-2013 1461 1462 Page 7 1463 October 31, 2013 1464 1465 Part 3: Commands 1467 f) 1468 1469 Trusted Platform Module Library 1470 1471 If the command requires a handle to have USER role authorization: 1472 1) If the entity being authorized is an object and its userWithAuth attribute is CLEAR, then the 1473 associated authorization session is a policy session (TPM_RC_POLICY_FAIL). 1474 2) If the entity being authorized is an NV Index; 1475 i) 1476 1477 if the authorization session is a policy session; 1478 (a) the TPMA_NV_POLICYWRITE attribute of the NV Index is SET if the command modifies 1479 the NV Index data (TPM_RC_AUTH_UNAVAILABLE); 1480 (b) the TPMA_NV_POLICYREAD attribute of the NV Index is SET if the command reads the 1481 NV Index data (TPM_RC_AUTH_UNAVAILABLE); 1482 1483 ii) 1484 1485 if the authorization is an HMAC session or a password; 1486 (a) the TPMA_NV_AUTHWRITE attribute of the NV Index is SET if the command modifies 1487 the NV Index data (TPM_RC_AUTH_UNAVAILABLE); 1488 (b) the TPMA_NV_AUTHREAD attribute of the NV Index is SET if the command reads the 1489 NV Index data (TPM_RC_AUTH_UNAVAILABLE). 1490 1491 g) If the authorization is provided by a policy session, then: 1492 1) if policySessiontimeOut 1493 (TPM_RC_EXPIRED); 1494 1495 has 1496 1497 been 1498 1499 set, 1500 1501 the 1502 1503 session 1504 1505 shall 1506 1507 not 1508 1509 have 1510 1511 expired 1512 1513 2) if policySessioncpHash has been set, it shall match the cpHash of the command 1514 (TPM_RC_POLICY_FAIL); 1515 3) if policySessioncommandCode has been set, then commandCode of the command shall match 1516 (TPM_RC_POLICY_CC); 1517 4) policySessionpolicyDigest 1518 (TPM_RC_POLICY_FAIL); 1519 1520 shall 1521 1522 match 1523 1524 the 1525 1526 authPolicy 1527 1528 associated 1529 1530 with 1531 1532 the 1533 1534 handle 1535 1536 5) if policySessionpcrUpdateCounter has been set, then it shall match the value of 1537 pcrUpdateCounter (TPM_RC_PCR_CHANGED); 1538 6) if policySession->commandLocality has been set, it shall match the locality of the command 1539 (TPM_RC_LOCALITY), and 1540 7) if the authorization uses an HMAC, then the HMAC is properly constructed using the authValue 1541 associated with the handle and/or the session secret (TPM_RC_AUTH_FAIL or 1542 TPM_RC_BAD_AUTH). 1543 NOTE 5 1544 1545 For a bound session, if the handle references the object us ed to initiate the session, then the 1546 authValue will not be required but proof of knowledge of the session secret is necessary. 1547 1548 NOTE 6 1549 1550 A policy session may require proof of knowledge of the authValue of the object being authorized. 1551 1552 If the TPM returns an error other than TPM_RC_AUTH_FAIL then the TPM shall not alter any TPM state. 1553 If the TPM return TPM_RC_AUTH_FAIL, then the TPM shall not alter any TPM state other than 1554 lockoutCount. 1555 NOTE 7 1556 1557 7.7 1558 1559 The TPM may decrease failedTries regardless of any other processing performed by the TPM. That 1560 is, the TPM may exit Lockout mode, regardless of the return code. 1561 1562 Parameter Decryption 1563 1564 If an authorization session has the TPMA_SESSION.decrypt attribute SET, and the command does not 1565 allow a command parameter to be encrypted, then the TPM will return TPM_RC_ATTRIBUTES. 1566 1567 Page 8 1568 October 31, 2013 1569 1570 Published 1571 Copyright TCG 2006-2013 1572 1573 Family 2.0 1574 Level 00 Revision 00.99 1575 1576 Trusted Platform Module Library 1578 1579 Part 3: Commands 1580 1581 Otherwise, the TPM will decrypt the parameter using the values associated with the session before 1582 parsing parameters. 1583 7.8 1584 7.8.1 1585 1586 Parameter Unmarshaling 1587 Introduction 1588 1589 The detailed actions for each command assume that the input parameters of the command have been 1590 unmarshaled into a command-specific structure with the structure defined by the command schematic. 1591 Additionally, a response-specific output structure is assumed which will receive the values produced by 1592 the detailed actions. 1593 NOTE 1594 1595 An implementation is not required to process parameters in this manner or to separate the 1596 parameter parsing from the command actions. This method was chosen for the specification so that 1597 the normative behavior described by the detailed actions would be clear and unencumbered. 1598 1599 Unmarshaling is the process of processing the parameters in the input buffer and preparing the 1600 parameters for use by the command-specific action code. No data movement need take place but it is 1601 required that the TPM validate that the parameters meet the requirements of the expected data type as 1602 defined in Part 2 of this specification. 1603 7.8.2 1604 1605 Unmarshaling Errors 1606 1607 When an error is encountered while unmarshaling a command parameter, an error response code is 1608 returned and no command processing occurs. A table defining a data type may have response codes 1609 embedded in the table to indicate the error returned when the input value does not match the parameters 1610 of the table. 1611 NOTE 1612 1613 In the reference implementation, a parameter number is added to the response code so that the 1614 offending parameter can be isolated. This is optional. 1615 1616 In many cases, the table contains no specific response code value and the return code will be determined 1617 as defined in Table 3. 1618 1619 Family 2.0 1620 Level 00 Revision 00.99 1621 1622 Published 1623 Copyright TCG 2006-2013 1624 1625 Page 9 1626 October 31, 2013 1627 1628 Part 3: Commands 1630 1631 Trusted Platform Module Library 1632 Table 3 Unmarshaling Errors 1633 1634 Response Code 1635 1636 Meaning 1637 1638 TPM_RC_ASYMMETRIC 1639 1640 a parameter that should be an asymmetric algorithm selection does not have a 1641 value that is supported by the TPM 1642 1643 TPM_RC_BAD_TAG 1644 1645 a parameter that should be a command tag selection has a value that is not 1646 supported by the TPM 1647 1648 TPM_RC_COMMAND_CODE 1649 1650 a parameter that should be a command code does not have a value that is 1651 supported by the TPM 1652 1653 TPM_RC_HASH 1654 1655 a parameter that should be a hash algorithm selection does not have a value that 1656 is supported by the TPM 1657 1658 TPM_RC_INSUFFICIENT 1659 1660 the input buffer did not contain enough octets to allow unmarshaling of the 1661 expected data type; 1662 1663 TPM_RC_KDF 1664 1665 a parameter that should be a key derivation scheme (KDF) selection does not 1666 have a value that is supported by the TPM 1667 1668 TPM_RC_KEY_SIZE 1669 1670 a parameter that is a key size has a value that is not supported by the TPM 1671 1672 TPM_RC_MODE 1673 1674 a parameter that should be a symmetric encryption mode selection does not have 1675 a value that is supported by the TPM 1676 1677 TPM_RC_RESERVED 1678 1679 a non-zero value was found in a reserved field of an attribute structure (TPMA_) 1680 1681 TPM_RC_SCHEME 1682 1683 a parameter that should be signing or encryption scheme selection does not have 1684 a value that is supported by the TPM 1685 1686 TPM_RC_SIZE 1687 1688 the value of a size parameter is larger or smaller than allowed 1689 1690 TPM_RC_SYMMETRIC 1691 1692 a parameter that should be a symmetric algorithm selection does not have a 1693 value that is supported by the TPM 1694 1695 TPM_RC_TAG 1696 1697 a parameter that should be a structure tag has a value that is not supported by 1698 the TPM 1699 1700 TPM_RC_TYPE 1701 1702 The type parameter of a TPMT_PUBLIC or TPMT_SENSITIVE has a value that is 1703 not supported by the TPM 1704 1705 TPM_RC_VALUE 1706 1707 a parameter does not have one of its allowed values 1708 1709 In some commands, a parameter may not be used because of various options of that command. 1710 However, the unmarshaling code is required to validate that all parameters have values that are allowed 1711 by the Part 2 definition of the parameter type even if that parameter is not used in the command actions. 1712 7.9 1713 1714 Command Post Processing 1715 1716 When the code that implements the detailed actions of the command completes, it returns a response 1717 code. If that code is not TPM_RC_SUCCESS, the post processing code will not update any session or 1718 audit data and will return a 10-octet response packet. 1719 If the command completes successfully, the tag of the command determines if any authorization sessions 1720 will be in the response. If so, the TPM will encrypt the first parameter of the response if indicated by the 1721 authorization attributes. The TPM will then generate a new nonce value for each session and, if 1722 appropriate, generate an HMAC. 1723 1724 Page 10 1725 October 31, 2013 1726 1727 Published 1728 Copyright TCG 2006-2013 1729 1730 Family 2.0 1731 Level 00 Revision 00.99 1732 1733 Trusted Platform Module Library 1735 1736 Part 3: Commands 1737 1738 NOTE 1 1739 1740 The authorization attributes were validated during the session area validation to ensure that only 1741 one session was used for parameter encryption of the response and that the command allowed 1742 encryption in the response. 1743 1744 NOTE 2 1745 1746 No session nonce value is used for a password authorization but the session data is present. 1747 1748 Additionally, if the command is being audited by Command Audit, the audit digest is updated with the 1749 cpHash of the command and rpHash of the response. 1750 1751 Family 2.0 1752 Level 00 Revision 00.99 1753 1754 Published 1755 Copyright TCG 2006-2013 1756 1757 Page 11 1758 October 31, 2013 1759 1760 Part 3: Commands 1762 1763 8 1764 8.1 1765 1766 Trusted Platform Module Library 1767 1768 Response Values 1769 Tag 1770 1771 When a command completes successfully, the tag parameter in the response shall have the same value 1772 as the tag parameter in the command (TPM_ST_SESSIONS or TPM_RC_NO_SESSIONS). When a 1773 command fails (the responseCode is not TPM_RC_SUCCESS), then the tag parameter in the response 1774 shall be TPM_ST_NO_SESSIONS. 1775 A special case exists when the command tag parameter is not an allowed value (TPM_ST_SESSIONS or 1776 TPM_ST_NO_SESSIONS). For this case, it is assumed that the system software is attempting to send a 1777 command formatted for a TPM 1.2 but the TPM is not capable of executing TPM 1.2 commands. So that 1778 the TPM 1.2 compatible software will have a recognizable response, the TPM sets tag to 1779 TPM_ST_RSP_COMMAND, responseSize to 00 00 00 0A16 and responseCode to TPM_RC_BAD_TAG. 1780 This is the same response as the TPM 1.2 fatal error for TPM_BADTAG. 1781 8.2 1782 1783 Response Codes 1784 1785 The normal response for any command is TPM_RC_SUCCESS. Any other value indicates that the 1786 command did not complete and the state of the TPM is unchanged. An exception to this general rule is 1787 that the logic associated with dictionary attack protection is allowed to be modified when an authorization 1788 failure occurs. 1789 Commands have response codes that are specific to that command, and those response codes are 1790 enumerated in the detailed actions of each command. The codes associated with the unmarshaling of 1791 parameters are documented Table 3. Another set of response code value are not command specific and 1792 indicate a problem that is not specific to the command. That is, if the indicated problem is remedied, the 1793 same command could be resubmitted and may complete normally. 1794 The response codes that are not command specific are listed and described in Table 4. 1795 The reference code for the command actions may have code that generates specific response codes 1796 associated with a specific check but the listing of responses may not have that response code listed. 1797 1798 Page 12 1799 October 31, 2013 1800 1801 Published 1802 Copyright TCG 2006-2013 1803 1804 Family 2.0 1805 Level 00 Revision 00.99 1806 1807 Trusted Platform Module Library 1809 1810 Part 3: Commands 1811 1812 Table 4 Command-Independent Response Codes 1813 Response Code 1814 1815 Meaning 1816 1817 TPM_RC_CANCELLED 1818 1819 This response code may be returned by a TPM that supports command cancel. 1820 When the TPM receives an indication that the current command should be 1821 cancelled, the TPM may complete the command or return this code. If this code 1822 is returned, then the TPM state is not changed and the same command may be 1823 retried. 1824 1825 TPM_RC_CONTEXT_GAP 1826 1827 This response code can be returned for commands that manage session 1828 contexts. It indicates that the gap between the lowest numbered active session 1829 and the highest numbered session is at the limits of the session tracking logic. 1830 The remedy is to load the session context with the lowest number so that its 1831 tracking number can be updated. 1832 1833 TPM_RC_LOCKOUT 1834 1835 This response indicates that authorizations for objects subject to DA protection 1836 are not allowed at this time because the TPM is in DA lockout mode. The remedy 1837 is to wait or to exeucte TPM2_DictionaryAttackLockoutReset(). 1838 1839 TPM_RC_MEMORY 1840 1841 A TPM may use a common pool of memory for objects, sessions, and other 1842 purposes. When the TPM does not have enough memory available to perform 1843 the actions of the command, it may return TPM_RC_MEMORY. This indicates 1844 that the TPM resource manager may flush either sessions or objects in order to 1845 make memory available for the command execution. A TPM may choose to 1846 return TPM_RC_OBJECT_MEMORY or TPM_RC_SESSION_MEMORY if it 1847 needs contexts of a particular type to be flushed. 1848 1849 TPM_RC_NV_RATE 1850 1851 This response code indicates that the TPM is rate-limiting writes to the NV 1852 memory in order to prevent wearout. This response is possible for any command 1853 that explicity writes to NV or commands that incidentally use NV such as a 1854 command that uses authorization session that may need to update the dictionary 1855 attack logic. 1856 1857 TPM_RC_NV_UNAVAILABLE 1858 1859 This response code is similar to TPM_RC_NV_RATE but indicates that access to 1860 NV memory is currently not available and the command is not allowed to proceed 1861 until it is. This would occur in a system where the NV memory used by the TPM 1862 is not exclusive to the TPM and is a shared system resource. 1863 1864 TPM_RC_OBJECT_HANDLES 1865 1866 This response code indicates that the TPM has exhausted its handle space and 1867 no new objects can be loaded unless the TPM is rebooted. This does not occur in 1868 the reference implementation because of the way that object handles are 1869 allocated. However, other implementations are allowed to assign each object a 1870 unique handle each time the object is loaded. A TPM using this implementation 1871 24 1872 would be able to load 2 objects before the object space is exhausted. 1873 1874 TPM_RC_OBJECT_MEMORY 1875 1876 This response code can be returned by any command that causes the TPM to 1877 need an object 'slot'. The most common case where this might be returned is 1878 when an object is loaded (TPM2_Load, TPM2_CreatePrimary(), or 1879 TPM2_ContextLoad()). However, the TPM implementation is allowed to use 1880 object slots for other reasons. In the reference implementation, the TPM copies a 1881 referenced persistent object into RAM for the duration of the commannd. If all the 1882 slots are previously occupied, the TPM may return this value. A TPM is allowed 1883 to use object slots for other purposes and return this value. The remedy when 1884 this response is returned is for the TPM resource manager to flush a transient 1885 object. 1886 1887 TPM_RC_REFERENCE_Hx 1888 1889 This response code indicates that a handle in the handle area of the command is 1890 not associated with a loaded object. The value of 'x' is in the range 0 to 6 with a 1891 st 1892 th 1893 value of 0 indicating the 1 handle and 6 representing the 7 . The TPM resource 1894 manager needs to find the correct object and load it. It may then adjust the 1895 handle and retry the command. 1896 NOTE 1897 1898 Family 2.0 1899 Level 00 Revision 00.99 1900 1901 Usually, this error indicates that the TPM resource manager has a corrupted 1902 database. 1903 1904 Published 1905 Copyright TCG 2006-2013 1906 1907 Page 13 1908 October 31, 2013 1909 1910 Part 3: Commands 1912 1913 Trusted Platform Module Library 1914 1915 Response Code 1916 1917 Meaning 1918 1919 TPM_RC_REFERENCE_Sx 1920 1921 This response code indicates that a handle in the session area of the command 1922 is not associated with a loaded session. The value of 'x' is in the range 0 to 6 with 1923 st 1924 th 1925 a value of 0 indicating the 1 session handle and 6 representing the 7 . The 1926 TPM resource manager needs to find the correct session and load it. It may then 1927 retry the command. 1928 NOTE Usually, this error indicates that the TPM resource manager has a 1929 corrupted database. 1930 1931 TPM_RC_RETRY 1932 1933 the TPM was not able to start the command 1934 1935 This response code indicates that the TPM does not have a handle to assign to a 1936 new session. This respose is only returned by TPM2_StartAuthSession(). It is 1937 TPM_RC_SESSION_HANDLES 1938 listed here because the command is not in error and the TPM resource manager 1939 can remedy the situation by flushing a session (TPM2_FlushContext(). 1940 1941 TPM_RC_SESSION_MEMORY 1942 1943 This response code can be returned by any command that causes the TPM to 1944 need a session 'slot'. The most common case where this might be returned is 1945 when a session is loaded (TPM2_StartAuthSession() or TPM2_ContextLoad()). 1946 However, the TPM implementation is allowed to use object slots for other 1947 purposes. The remedy when this response is returned is for the TPM resource 1948 manager to flush a transient object. 1949 1950 TPM_RC_SUCCESS 1951 1952 Normal completion for any command. If the responseCode is 1953 TPM_RC_SESSIONS, then the rest of the response has the format indicated in 1954 the response schematic. Otherwise, the response is a 10 octet value indicating 1955 an error. 1956 1957 TPM_RC_TESTING 1958 1959 This response code indicates that the TPM is performing tests and cannot 1960 respond to the request at this time. The command may be retried. 1961 1962 TPM_RC_YIELDED 1963 1964 the TPM has suspended operation on the command; forward progress was made 1965 and the command may be retried. 1966 See Part 1, Multi-tasking. 1967 NOTE 1968 1969 Page 14 1970 October 31, 2013 1971 1972 This cannot occur on the reference implementation. 1973 1974 Published 1975 Copyright TCG 2006-2013 1976 1977 Family 2.0 1978 Level 00 Revision 00.99 1979 1980 Trusted Platform Module Library 1982 1983 9 1984 1985 Part 3: Commands 1986 1987 Implementation Dependent 1988 1989 The actions code for each command makes assumptions about the behavior of various sub-systems. 1990 There are many possible implementations of the subsystems that would achieve equivalent results. The 1991 actions code is not written to anticipate all possible implementations of the sub-systems. Therefore, it is 1992 the responsibility of the implementer to ensure that the necessary changes are made to the actions code 1993 when the sub-system behavior changes. 1994 1995 Family 2.0 1996 Level 00 Revision 00.99 1997 1998 Published 1999 Copyright TCG 2006-2013 2000 2001 Page 15 2002 October 31, 2013 2003 2004 Part 3: Commands 2006 2007 Trusted Platform Module Library 2008 2009 Detailed Actions Assumptions 2010 2011 10 2012 10.1 2013 2014 Introduction 2015 2016 The C code in the Detailed Actions for each command is written with a set of assumptions about the 2017 processing performed before the action code is called and the processing that will be done after the 2018 action code completes. 2019 10.2 2020 2021 Pre-processing 2022 2023 Before calling the command actions code, the following actions have occurred. 2024 2025 2026 Verification that the handles in the handle area reference entities that are resident on the TPM. 2027 NOTE 2028 2029 If a handle is in the parameter portion of the command, the associated entity does not have to 2030 be loaded, but the handle is required to be the correct type. 2031 2032 2033 2034 If use of a handle requires authorization, the Password, HMAC, or Policy session associated with the 2035 handle has been verified. 2036 2037 2038 2039 If a command parameter was encrypted using parameter encryption, it was decrypted before being 2040 unmarshaled. 2041 2042 2043 2044 If the command uses handles or parameters, the calling stack contains a pointer to a data structure 2045 (in) that holds the unmarshaled values for the handles and commands. If the response has handles 2046 or parameters, the calling stack contains a pointer to a data structure ( out) to hold the handles and 2047 parameters generated by the command. 2048 2049 2050 2051 All parameters of the in structure have been validated and meet the requirements of the parameter 2052 type as defined in Part 2. 2053 2054 2055 2056 Space set aside for the out structure is sufficient to hold the largest out structure that could be 2057 produced by the command 2058 2059 10.3 2060 2061 Post Processing 2062 2063 When the function implementing the command actions completes, 2064 2065 2066 response parameters that require parameter encryption will be encrypted after the command actions 2067 complete; 2068 2069 2070 2071 audit and session contexts will be updated if the command response is TPM_RC_SUCCESS; and 2072 2073 2074 2075 the command header and command response parameters will be marshaled to the response buffer. 2076 2077 Page 16 2078 October 31, 2013 2079 2080 Published 2081 Copyright TCG 2006-2013 2082 2083 Family 2.0 2084 Level 00 Revision 00.99 2085 2086 Trusted Platform Module Library 2088 2089 11 2090 2091 Part 3: Commands 2092 2093 Start-up 2094 2095 11.1 2096 2097 Introduction 2098 2099 This clause contains the commands used to manage the startup and restart state of a TPM. 2100 11.2 2101 2102 _TPM_Init 2103 2104 11.2.1 General Description 2105 _TPM_Init initializes a TPM. 2106 Initialization actions include testing code required to execute the next expected command. If the TPM is in 2107 FUM, the next expected command is TPM2_FieldUpgradeData(); otherwise, the next expected command 2108 is TPM2_Startup(). 2109 NOTE 1 2110 2111 If the TPM performs self-tests after receiving _TPM_Init() and the TPM enters Failure mode before 2112 receiving TPM2_Startup() or TPM2_FieldUpgradeData(), then the TPM may be able to accept 2113 TPM2_GetTestResult() or TPM2_GetCapability(). 2114 2115 The means of signaling _TPM_Init shall be defined in the platform-specific specifications that define the 2116 physical interface to the TPM. The platform shall send this indication whenever the platform starts its boot 2117 process and only when the platform starts its boot process. 2118 There shall be no software method of generating this indication that does not also reset the platform and 2119 begin execution of the CRTM. 2120 NOTE 2 2121 2122 In the reference implementation, this signal causes an internal flag ( s_initialized) to be CLEAR. 2123 While this flag is CLEAR, the TPM will only accept the next expected command described above. 2124 2125 Family 2.0 2126 Level 00 Revision 00.99 2127 2128 Published 2129 Copyright TCG 2006-2013 2130 2131 Page 17 2132 October 31, 2013 2133 2134 Part 3: Commands 2136 2137 Trusted Platform Module Library 2138 2139 11.2.2 Detailed Actions 2140 1 2141 2142 #include "InternalRoutines.h" 2143 2144 This function is used to process a _TPM_Init() indication. 2145 2 2146 3 2147 4 2148 5 2149 6 2150 7 2151 8 2152 9 2153 10 2154 11 2155 12 2156 13 2157 14 2158 15 2159 16 2160 17 2161 18 2162 19 2163 20 2164 21 2165 22 2166 23 2167 24 2168 2169 void _TPM_Init(void) 2170 { 2171 // Initialize crypto engine 2172 CryptInitUnits(); 2173 // Initialize NV environment 2174 NvPowerOn(); 2175 // Start clock 2176 TimePowerOn(); 2177 // Set initialization state 2178 TPMInit(); 2179 // Set g_DRTMHandle as unassigned 2180 g_DRTMHandle = TPM_RH_UNASSIGNED; 2181 // No H-CRTM, yet. 2182 g_DrtmPreStartup = FALSE; 2183 return; 2184 } 2185 2186 Page 18 2187 October 31, 2013 2188 2189 Published 2190 Copyright TCG 2006-2013 2191 2192 Family 2.0 2193 Level 00 Revision 00.99 2194 2195 Trusted Platform Module Library 2197 2198 11.3 2199 2200 Part 3: Commands 2201 2202 TPM2_Startup 2203 2204 11.3.1 General Description 2205 TPM2_Startup() is always preceded by _TPM_Init, which is the physical indication that TPM initialization 2206 is necessary because of a system-wide reset. TPM2_Startup() is only valid after _TPM_Init Additional 2207 TPM2_Startup() commands are not allowed after it has completed successfully. If a TPM requires 2208 TPM2_Startup() and another command is received, or if the TPM receives TPM2_Startup() when it is not 2209 required, the TPM shall return TPM_RC_INITIALIZE. 2210 NOTE 1 2211 2212 See 11.2.1 for other command options for a TPM supporting field upgrade mode. 2213 2214 NOTE 2 2215 2216 _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(). 2217 2218 If in Failure mode the TPM shall accept TPM2_GetTestResult() and TPM2_GetCapability() even if 2219 TPM2_Startup() is not completed successfully or processed at all. 2220 A Shutdown/Startup sequence determines the way in which the TPM will operate in response to 2221 TPM2_Startup(). The three sequences are: 2222 1) TPM Reset This is a Startup(CLEAR) preceded by either Shutdown(CLEAR) or no 2223 TPM2_Shutdown(). On TPM Reset, all variables go back to their default initialization state. 2224 NOTE 3 2225 2226 Only those values that are specified as having a default initialization state are changed by TPM 2227 Reset. Persistent values that have no default initialization state are not changed by this 2228 command. Values such as seeds have no default initialization state and only change due to 2229 specific commands. 2230 2231 2) TPM Restart This is a Startup(CLEAR) preceded by Shutdown(STATE). This preserves much of the 2232 previous state of the TPM except that PCR and the controls associated with the Platform hierarchy 2233 are all returned to their default initialization state; 2234 3) TPM Resume This is a Startup(STATE) preceded by Shutdown(STATE). This preserves the 2235 previous state of the TPM including the static Root of Trust for Measurement (S-RTM) PCR and the 2236 platform controls other than the phEnable and phEnableNV. 2237 If a TPM receives Startup(STATE) and that was not preceded by Shutdown(STATE), the TPM shall return 2238 TPM_RC_VALUE. 2239 If, during TPM Restart or TPM Resume, the TPM fails to restore the state saved at the last 2240 Shutdown(STATE), the TPM shall enter Failure Mode and return TPM_RC_FAILURE. 2241 On any TPM2_Startup(), 2242 2243 2244 phEnable and phEnableNV shall be SET; 2245 2246 2247 2248 all transient contexts (objects, sessions, and sequences) shall be flushed from TPM memory; 2249 2250 2251 2252 TPMS_TIME_INFO.time shall be reset to zero; and 2253 2254 2255 2256 use of lockoutAuth shall be enabled if lockoutRecovery is zero. 2257 2258 Additional actions are performed based on the Shutdown/Startup sequence. 2259 On TPM Reset 2260 2261 Family 2.0 2262 Level 00 Revision 00.99 2263 2264 Published 2265 Copyright TCG 2006-2013 2266 2267 Page 19 2268 October 31, 2013 2269 2270 Part 3: Commands 2272 2273 Trusted Platform Module Library 2274 2275 2276 2277 platformAuth and platformPolicy shall be set to the Empty Buffer, 2278 2279 2280 2281 tracking data for saved session contexts shall be set to its initial value, 2282 2283 2284 2285 the object context sequence number is reset to zero, 2286 2287 2288 2289 a new context encryption key shall be generated, 2290 2291 2292 2293 TPMS_CLOCK_INFO.restartCount shall be reset to zero, 2294 2295 2296 2297 TPMS_CLOCK_INFO.resetCount shall be incremented, 2298 2299 2300 2301 the PCR Update Counter shall be clear to zero, 2302 2303 2304 2305 shEnable and ehEnable shall be SET, and 2306 2307 2308 2309 PCR in all banks are reset to their default initial conditions as determined by the relevant platformspecific specification. 2310 NOTE 4 2311 2312 PCR may be initialized any time between _TPM_Init and the end of TPM2_Startup(). PCR that 2313 are preserved by TPM Resume will need to be restored during TPM2_Startup(). 2314 2315 NOTE 5 2316 2317 See "Initializing PCR" in Part 1 of this specification for a description of the default initial 2318 conditions for a PCR. 2319 2320 On TPM Restart 2321 2322 2323 TPMS_CLOCK_INFO.restartCount shall be incremented, 2324 2325 2326 2327 shEnable and ehEnable shall be SET, 2328 2329 2330 2331 platformAuth and platformPolicy shall be set to the Empty Buffer, and 2332 2333 2334 2335 PCR in all banks are reset to their default initial conditions. 2336 2337 2338 2339 If a CRTM Event sequence is active, extend the PCR designated by the platform-specific 2340 specification. 2341 2342 On TPM Resume 2343 2344 2345 the H-CRTM startup method is the same for this TPM2_Startup() as for the previous TPM2_Startup(); 2346 (TPM_RC_LOCALITY) 2347 2348 2349 2350 TPMS_CLOCK_INFO.restartCount shall be incremented; and 2351 2352 2353 2354 PCR that are specified in a platform-specific specification to be preserved on TPM Resume are 2355 restored to their saved state and other PCR are set to their initial value as determined by a platformspecific specification. 2356 2357 Other TPM state may change as required to meet the needs of the implementation. 2358 If the startupType is TPM_SU_STATE and the TPM requires TPM_SU_CLEAR, then the TPM shall return 2359 TPM_RC_VALUE. 2360 NOTE 6 2361 2362 The TPM will require 2363 Shutdown(CLEAR). 2364 2365 NOTE 7 2366 2367 If startupType is neither TPM_SU_STATE nor TPM_SU_CLEAR, then the unmarshaling code returns 2368 TPM_RC_VALUE. 2369 2370 Page 20 2371 October 31, 2013 2372 2373 TPM_SU_CLEAR 2374 2375 when 2376 2377 no 2378 2379 Published 2380 Copyright TCG 2006-2013 2381 2382 shutdown 2383 2384 was 2385 2386 performed 2387 2388 or 2389 2390 after 2391 2392 Family 2.0 2393 Level 00 Revision 00.99 2394 2395 Trusted Platform Module Library 2397 2398 Part 3: Commands 2399 2400 11.3.2 Command and Response 2401 Table 5 TPM2_Startup Command 2402 Type 2403 2404 Name 2405 2406 Description 2407 2408 TPMI_ST_COMMAND_TAG 2409 2410 tag 2411 2412 TPM_ST_NO_SESSIONS 2413 2414 UINT32 2415 2416 commandSize 2417 2418 TPM_CC 2419 2420 commandCode 2421 2422 TPM_CC_Startup {NV} 2423 2424 TPM_SU 2425 2426 startupType 2427 2428 TPM_SU_CLEAR or TPM_SU_STATE 2429 2430 Table 6 TPM2_Startup Response 2431 Type 2432 2433 Name 2434 2435 Description 2436 2437 TPM_ST 2438 2439 tag 2440 2441 see clause 8 2442 2443 UINT32 2444 2445 responseSize 2446 2447 TPM_RC 2448 2449 responseCode 2450 2451 Family 2.0 2452 Level 00 Revision 00.99 2453 2454 Published 2455 Copyright TCG 2006-2013 2456 2457 Page 21 2458 October 31, 2013 2459 2460 Part 3: Commands 2462 2463 Trusted Platform Module Library 2464 2465 11.3.3 Detailed Actions 2466 1 2467 2 2468 2469 #include "InternalRoutines.h" 2470 #include "Startup_fp.h" 2471 Error Returns 2472 TPM_RC_VALUE 2473 2474 3 2475 4 2476 5 2477 6 2478 7 2479 8 2480 9 2481 10 2482 11 2483 12 2484 13 2485 14 2486 15 2487 16 2488 17 2489 18 2490 19 2491 20 2492 21 2493 22 2494 23 2495 24 2496 25 2497 26 2498 27 2499 28 2500 29 2501 30 2502 31 2503 32 2504 33 2505 34 2506 35 2507 36 2508 37 2509 38 2510 39 2511 40 2512 41 2513 42 2514 43 2515 44 2516 45 2517 46 2518 47 2519 48 2520 49 2521 50 2522 51 2523 52 2524 53 2525 54 2526 2527 Meaning 2528 start up type is not compatible with previous shutdown sequence 2529 2530 TPM_RC 2531 TPM2_Startup( 2532 Startup_In 2533 2534 *in 2535 2536 // IN: input parameter list 2537 2538 ) 2539 { 2540 STARTUP_TYPE 2541 TPM_RC 2542 BOOL 2543 2544 startup; 2545 result; 2546 prevDrtmPreStartup; 2547 2548 // The command needs NV update. Check if NV is available. 2549 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 2550 // this point 2551 result = NvIsAvailable(); 2552 if(result != TPM_RC_SUCCESS) 2553 return result; 2554 // Input Validation 2555 // Read orderly shutdown states from previous power cycle 2556 NvReadReserved(NV_ORDERLY, &g_prevOrderlyState); 2557 // HACK to extract the DRTM startup type associated with the previous shutdown 2558 prevDrtmPreStartup = (g_prevOrderlyState == (TPM_SU_STATE + 0x8000)); 2559 if(prevDrtmPreStartup) 2560 g_prevOrderlyState = TPM_SU_STATE; 2561 // if the previous power cycle was shut down with no StateSave command, or 2562 // with StateSave command for CLEAR, this cycle can not startup up with 2563 // STATE 2564 if( 2565 ( 2566 g_prevOrderlyState == SHUTDOWN_NONE 2567 || g_prevOrderlyState == TPM_SU_CLEAR 2568 ) 2569 && in->startupType == TPM_SU_STATE 2570 ) 2571 return TPM_RC_VALUE + RC_Startup_startupType; 2572 // Internal Date Update 2573 // Translate the TPM2_ShutDown and TPM2_Startup sequence into the startup 2574 // types. 2575 if(in->startupType == TPM_SU_CLEAR && g_prevOrderlyState == TPM_SU_STATE) 2576 { 2577 startup = SU_RESTART; 2578 // Read state reset data 2579 NvReadReserved(NV_STATE_RESET, &gr); 2580 } 2581 else if(in->startupType == TPM_SU_STATE && g_prevOrderlyState == TPM_SU_STATE) 2582 { 2583 // For a resume, the H-CRTM startup method must be the same 2584 if(g_DrtmPreStartup != prevDrtmPreStartup) 2585 return TPM_RC_LOCALITY; 2586 2587 Page 22 2588 October 31, 2013 2589 2590 Published 2591 Copyright TCG 2006-2013 2592 2593 Family 2.0 2594 Level 00 Revision 00.99 2595 2596 Trusted Platform Module Library 2598 55 2599 56 2600 57 2601 58 2602 59 2603 60 2604 61 2605 62 2606 63 2607 64 2608 65 2609 66 2610 67 2611 68 2612 69 2613 70 2614 71 2615 72 2616 73 2617 74 2618 75 2619 76 2620 77 2621 78 2622 79 2623 80 2624 81 2625 82 2626 83 2627 84 2628 85 2629 86 2630 87 2631 88 2632 89 2633 90 2634 91 2635 92 2636 93 2637 94 2638 95 2639 96 2640 97 2641 98 2642 99 2643 100 2644 101 2645 102 2646 103 2647 104 2648 105 2649 106 2650 107 2651 108 2652 109 2653 110 2654 111 2655 112 2656 113 2657 114 2658 115 2659 116 2660 2661 Part 3: Commands 2662 2663 // Read state clear and state reset data 2664 NvReadReserved(NV_STATE_CLEAR, &gc); 2665 NvReadReserved(NV_STATE_RESET, &gr); 2666 startup = SU_RESUME; 2667 } 2668 else 2669 { 2670 startup = SU_RESET; 2671 } 2672 // Read persistent data from NV 2673 NvReadPersistent(); 2674 // Crypto Startup 2675 CryptUtilStartup(startup); 2676 // Start up subsystems 2677 // Start counters and timers 2678 TimeStartup(startup); 2679 // Start dictionary attack subsystem 2680 DAStartup(startup); 2681 // Enable hierarchies 2682 HierarchyStartup(startup); 2683 // Restore/Initialize PCR 2684 PCRStartup(startup); 2685 // Restore/Initialize command audit information 2686 CommandAuditStartup(startup); 2687 // Object context variables 2688 if(startup == SU_RESET) 2689 { 2690 // Reset object context ID to 0 2691 gr.objectContextID = 0; 2692 // Reset clearCount to 0 2693 gr.clearCount= 0; 2694 } 2695 // Initialize object table 2696 ObjectStartup(); 2697 // Initialize session table 2698 SessionStartup(startup); 2699 // Initialize index/evict data. 2700 // in NV index 2701 NvEntityStartup(startup); 2702 2703 This function clear read/write locks 2704 2705 // Initialize the orderly shut down flag for this cycle to SHUTDOWN_NONE. 2706 gp.orderlyState = SHUTDOWN_NONE; 2707 NvWriteReserved(NV_ORDERLY, &gp.orderlyState); 2708 // Update TPM internal states if command succeeded. 2709 // Record a TPM2_Startup command has been received. 2710 TPMRegisterStartup(); 2711 return TPM_RC_SUCCESS; 2712 } 2713 2714 Family 2.0 2715 Level 00 Revision 00.99 2716 2717 Published 2718 Copyright TCG 2006-2013 2719 2720 Page 23 2721 October 31, 2013 2722 2723 Part 3: Commands 2725 2726 11.4 2727 2728 Trusted Platform Module Library 2729 2730 TPM2_Shutdown 2731 2732 11.4.1 General Description 2733 This command is used to prepare the TPM for a power cycle. The shutdownType parameter indicates 2734 how the subsequent TPM2_Startup() will be processed. 2735 For a shutdownType of any type, the volatile portion of Clock is saved to NV memory and the orderly 2736 shutdown indication is SET. NV with the TPMA_NV_ORDERY attribute will be updated. 2737 For a shutdownType of TPM_SU_STATE, the following additional items are saved: 2738 2739 2740 tracking information for saved session contexts; 2741 2742 2743 2744 the session context counter; 2745 2746 2747 2748 PCR that are designated as being preserved by TPM2_Shutdown(TPM_SU_STATE); 2749 2750 2751 2752 the PCR Update Counter; 2753 2754 2755 2756 flags associated with supporting the TPMA_NV_WRITESTCLEAR and TPMA_NV_READSTCLEAR 2757 attributes; and 2758 2759 2760 2761 the command audit digest and count. 2762 2763 The following items shall not be saved and will not be in TPM memory after the next TPM2_Startup: 2764 2765 2766 TPM-memory-resident session contexts; 2767 2768 2769 2770 TPM-memory-resident transient objects; or 2771 2772 2773 2774 TPM-memory-resident hash contexts created by TPM2_HashSequenceStart(). 2775 2776 Some values may be either derived from other values or saved to NV memory. 2777 This command saves TPM state but does not change the state other than the internal indication that the 2778 context has been saved. The TPM shall continue to accept commands. If a subsequent command 2779 changes TPM state saved by this command, then the effect of this command is nullified. The TPM MAY 2780 nullify this command for any subsequent command rather than check whether the command changed 2781 state saved by this command. If this command is nullified. and if no TPM2_Shutdown() occurs before the 2782 next TPM2_Startup(), then the next TPM2_Startup() shall be TPM2_Startup(CLEAR). 2783 2784 Page 24 2785 October 31, 2013 2786 2787 Published 2788 Copyright TCG 2006-2013 2789 2790 Family 2.0 2791 Level 00 Revision 00.99 2792 2793 Trusted Platform Module Library 2795 2796 Part 3: Commands 2797 2798 11.4.2 Command and Response 2799 Table 7 TPM2_Shutdown Command 2800 Type 2801 2802 Name 2803 2804 Description 2805 2806 TPMI_ST_COMMAND_TAG 2807 2808 tag 2809 2810 UINT32 2811 2812 commandSize 2813 2814 TPM_CC 2815 2816 commandCode 2817 2818 TPM_CC_Shutdown {NV} 2819 2820 TPM_SU 2821 2822 shutdownType 2823 2824 TPM_SU_CLEAR or TPM_SU_STATE 2825 2826 Table 8 TPM2_Shutdown Response 2827 Type 2828 2829 Name 2830 2831 Description 2832 2833 TPM_ST 2834 2835 tag 2836 2837 see clause 8 2838 2839 UINT32 2840 2841 responseSize 2842 2843 TPM_RC 2844 2845 responseCode 2846 2847 Family 2.0 2848 Level 00 Revision 00.99 2849 2850 Published 2851 Copyright TCG 2006-2013 2852 2853 Page 25 2854 October 31, 2013 2855 2856 Part 3: Commands 2858 2859 Trusted Platform Module Library 2860 2861 11.4.3 Detailed Actions 2862 1 2863 2 2864 2865 #include "InternalRoutines.h" 2866 #include "Shutdown_fp.h" 2867 Error Returns 2868 TPM_RC_TYPE 2869 2870 3 2871 4 2872 5 2873 6 2874 7 2875 8 2876 9 2877 10 2878 11 2879 12 2880 13 2881 14 2882 15 2883 16 2884 17 2885 18 2886 19 2887 20 2888 21 2889 22 2890 23 2891 24 2892 25 2893 26 2894 27 2895 28 2896 29 2897 30 2898 31 2899 32 2900 33 2901 34 2902 35 2903 36 2904 37 2905 38 2906 39 2907 40 2908 41 2909 42 2910 43 2911 44 2912 45 2913 46 2914 47 2915 48 2916 49 2917 50 2918 51 2919 52 2920 53 2921 2922 Meaning 2923 if PCR bank has been re-configured, a CLEAR StateSave() is 2924 required 2925 2926 TPM_RC 2927 TPM2_Shutdown( 2928 Shutdown_In 2929 2930 *in 2931 2932 // IN: input parameter list 2933 2934 ) 2935 { 2936 TPM_RC 2937 2938 result; 2939 2940 // The command needs NV update. Check if NV is available. 2941 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 2942 // this point 2943 result = NvIsAvailable(); 2944 if(result != TPM_RC_SUCCESS) return result; 2945 // Input Validation 2946 // If PCR bank has been reconfigured, a CLEAR state save is required 2947 if(g_pcrReConfig && in->shutdownType == TPM_SU_STATE) 2948 return TPM_RC_TYPE + RC_Shutdown_shutdownType; 2949 // Internal Data Update 2950 // PCR private date state save 2951 PCRStateSave(in->shutdownType); 2952 // Get DRBG state 2953 CryptDrbgGetPutState(GET_STATE); 2954 // Save all orderly data 2955 NvWriteReserved(NV_ORDERLY_DATA, &go); 2956 // Save RAM backed NV index data 2957 NvStateSave(); 2958 if(in->shutdownType == TPM_SU_STATE) 2959 { 2960 // Save STATE_RESET and STATE_CLEAR data 2961 NvWriteReserved(NV_STATE_CLEAR, &gc); 2962 NvWriteReserved(NV_STATE_RESET, &gr); 2963 } 2964 else if(in->shutdownType == TPM_SU_CLEAR) 2965 { 2966 // Save STATE_RESET data 2967 NvWriteReserved(NV_STATE_RESET, &gr); 2968 } 2969 // Write orderly shut down state 2970 if(in->shutdownType == TPM_SU_CLEAR) 2971 gp.orderlyState = TPM_SU_CLEAR; 2972 else if(in->shutdownType == TPM_SU_STATE) 2973 gp.orderlyState = TPM_SU_STATE; 2974 else 2975 2976 Page 26 2977 October 31, 2013 2978 2979 Published 2980 Copyright TCG 2006-2013 2981 2982 Family 2.0 2983 Level 00 Revision 00.99 2984 2985 Trusted Platform Module Library 2987 54 2988 55 2989 56 2990 57 2991 58 2992 59 2993 2994 Part 3: Commands 2995 2996 pAssert(FALSE); 2997 NvWriteReserved(NV_ORDERLY, &gp.orderlyState); 2998 return TPM_RC_SUCCESS; 2999 } 3000 3001 Family 2.0 3002 Level 00 Revision 00.99 3003 3004 Published 3005 Copyright TCG 2006-2013 3006 3007 Page 27 3008 October 31, 2013 3009 3010 Part 3: Commands 3012 3013 12 3014 12.1 3015 3016 Trusted Platform Module Library 3017 3018 Testing 3019 Introduction 3020 3021 Compliance to standards for hardware security modules may require that the TPM test its functions 3022 before the results that depend on those functions may be returned. The TPM may perform operations 3023 using testable functions before those functions have been tested as long as the TPM returns no value 3024 that depends on the correctness of the testable function. 3025 EXAMPLE 3026 3027 TPM2_PCR_Event() may be executed before the hash algorithms have been tested. However, until 3028 the hash algorithms have been tested, the contents of a PCR may not be used in any command if 3029 that command may result in a value being returned to the TPM user. This means tha t 3030 TPM2_PCR_Read() or TPM2_PolicyPCR() could not complete until the hashes have been checked 3031 but other TPM2_PCR_Event() commands may be executed even though the operation uses previous 3032 PCR values. 3033 3034 If a command is received that requires return of a value that depends on untested functions, the TPM 3035 shall test the required functions before completing the command. 3036 Once the TPM has received TPM2_SelfTest() and before completion of all tests, the TPM is required to 3037 return TPM_RC_TESTING for any command that uses a function that requires a test. 3038 If a self-test fails at any time, the TPM will enter Failure mode. While in Failure mode, the TPM will return 3039 TPM_RC_FAILURE for any command other than TPM2_GetTestResult() and TPM2_GetCapability(). The 3040 TPM will remain in Failure mode until the next _TPM_Init. 3041 3042 Page 28 3043 October 31, 2013 3044 3045 Published 3046 Copyright TCG 2006-2013 3047 3048 Family 2.0 3049 Level 00 Revision 00.99 3050 3051 Trusted Platform Module Library 3053 3054 12.2 3055 3056 Part 3: Commands 3057 3058 TPM2_SelfTest 3059 3060 12.2.1 General Description 3061 This command causes the TPM to perform a test of its capabilities. If the fullTest is YES, the TPM will test 3062 all functions. If fullTest = NO, the TPM will only test those functions that have not previously been tested. 3063 If any tests are required, the TPM shall either 3064 a) return TPM_RC_TESTING and begin self-test of the required functions, or 3065 NOTE 1 3066 3067 If fullTest is NO, and all functions have been tested, the TPM shall return TPM_RC_SUCCESS. 3068 3069 b) perform the tests and return the test result when complete. 3070 If the TPM uses option a), the TPM shall return TPM_RC_TESTING for any command that requires use 3071 of a testable function, even if the functions required for completion of the command have already been 3072 tested. 3073 NOTE 2 3074 3075 This command may cause the TPM to continue processing after it has returned the response. So 3076 that software can be notified of the completion of the testing, the interface may include controls that 3077 would allow the TPM to generate an interrupt when the background processing is complete. This 3078 would be in addition to the interrupt may be available for signaling normal command completion. It is 3079 not necessary that there be two interrupts, but the interface should provide a way to indicate the 3080 nature of the interrupt (normal command or deferred command). 3081 3082 Family 2.0 3083 Level 00 Revision 00.99 3084 3085 Published 3086 Copyright TCG 2006-2013 3087 3088 Page 29 3089 October 31, 2013 3090 3091 Part 3: Commands 3093 3094 Trusted Platform Module Library 3095 3096 12.2.2 Command and Response 3097 Table 9 TPM2_SelfTest Command 3098 Type 3099 3100 Name 3101 3102 Description 3103 3104 TPMI_ST_COMMAND_TAG 3105 3106 tag 3107 3108 UINT32 3109 3110 commandSize 3111 3112 TPM_CC 3113 3114 commandCode 3115 3116 TPM_CC_SelfTest {NV} 3117 3118 TPMI_YES_NO 3119 3120 fullTest 3121 3122 YES if full test to be performed 3123 NO if only test of untested functions required 3124 3125 Table 10 TPM2_SelfTest Response 3126 Type 3127 3128 Name 3129 3130 Description 3131 3132 TPM_ST 3133 3134 tag 3135 3136 see clause 8 3137 3138 UINT32 3139 3140 responseSize 3141 3142 TPM_RC 3143 3144 responseCode 3145 3146 Page 30 3147 October 31, 2013 3148 3149 Published 3150 Copyright TCG 2006-2013 3151 3152 Family 2.0 3153 Level 00 Revision 00.99 3154 3155 Trusted Platform Module Library 3157 3158 Part 3: Commands 3159 3160 12.2.3 Detailed Actions 3161 1 3162 2 3163 3164 #include "InternalRoutines.h" 3165 #include "SelfTest_fp.h" 3166 Error Returns 3167 TPM_RC_TESTING 3168 3169 3 3170 4 3171 5 3172 6 3173 7 3174 8 3175 9 3176 10 3177 11 3178 12 3179 3180 Meaning 3181 self test in process 3182 3183 TPM_RC 3184 TPM2_SelfTest( 3185 SelfTest_In 3186 ) 3187 { 3188 // Command Output 3189 3190 *in 3191 3192 // IN: input parameter list 3193 3194 // Call self test function in crypt module 3195 return CryptSelfTest(in->fullTest); 3196 } 3197 3198 Family 2.0 3199 Level 00 Revision 00.99 3200 3201 Published 3202 Copyright TCG 2006-2013 3203 3204 Page 31 3205 October 31, 2013 3206 3207 Part 3: Commands 3209 3210 12.3 3211 3212 Trusted Platform Module Library 3213 3214 TPM2_IncrementalSelfTest 3215 3216 12.3.1 General Description 3217 This command causes the TPM to perform a test of the selected algorithms. 3218 NOTE 1 3219 3220 The toTest list indicates the algorithms that software would like the TPM to test in anticipation of 3221 future use. This allows tests to be done so that a future commands will not be delayed due to 3222 testing. 3223 3224 If toTest contains an algorithm that has already been tested, it will not be tested again. 3225 NOTE 2 3226 3227 The only way to force retesting of an algorithm is with TPM2_SelfTest( fullTest = YES). 3228 3229 The TPM will return in toDoList a list of algorithms that are yet to be tested. This list is not the list of 3230 algorithms that are scheduled to be tested but the algorithms/functions that have not been tested. Only 3231 the algorithms on the toTest list are scheduled to be tested by this command. 3232 Making toTest an empty list allows the determination of the algorithms that remain untested without 3233 triggering any testing. 3234 If toTest is not an empty list, the TPM shall return TPM_RC_SUCCESS for this command and then return 3235 TPM_RC_TESTING for any subsequent command (including TPM2_IncrementalSelfTest()) until the 3236 requested testing is complete. 3237 NOTE 3 3238 3239 If toDoList is empty, then no additional tests are required and TPM_RC_TESTING will not be 3240 returned in subsequent commands and no additional delay will occur in a command due to testing. 3241 3242 NOTE 4 3243 3244 If none of the algorithms listed in toTest is in the toDoList, then no tests will be performed. 3245 3246 If all the parameters in this command are valid, the TPM returns TPM_RC_SUCCESS and the toDoList 3247 (which may be empty). 3248 NOTE 5 3249 3250 An implementation may perform all requested tests before returning TPM_RC_SUCCESS, or it may 3251 return TPM_RC_SUCCESS for this command and then return TPM_RC_TESTING for all 3252 subsequence commands (including TPM2_IncrementatSelfTest()) until the requested tests are 3253 complete. 3254 3255 Page 32 3256 October 31, 2013 3257 3258 Published 3259 Copyright TCG 2006-2013 3260 3261 Family 2.0 3262 Level 00 Revision 00.99 3263 3264 Trusted Platform Module Library 3266 3267 Part 3: Commands 3268 3269 12.3.2 Command and Response 3270 Table 11 TPM2_IncrementalSelfTest Command 3271 Type 3272 3273 Name 3274 3275 Description 3276 3277 TPMI_ST_COMMAND_TAG 3278 3279 tag 3280 3281 UINT32 3282 3283 commandSize 3284 3285 TPM_CC 3286 3287 commandCode 3288 3289 TPM_CC_IncrementalSelfTest {NV} 3290 3291 TPML_ALG 3292 3293 toTest 3294 3295 list of algorithms that should be tested 3296 3297 Table 12 TPM2_IncrementalSelfTest Response 3298 Type 3299 3300 Name 3301 3302 Description 3303 3304 TPM_ST 3305 3306 tag 3307 3308 see clause 8 3309 3310 UINT32 3311 3312 responseSize 3313 3314 TPM_RC 3315 3316 responseCode 3317 3318 TPML_ALG 3319 3320 toDoList 3321 3322 Family 2.0 3323 Level 00 Revision 00.99 3324 3325 list of algorithms that need testing 3326 3327 Published 3328 Copyright TCG 2006-2013 3329 3330 Page 33 3331 October 31, 2013 3332 3333 Part 3: Commands 3335 3336 Trusted Platform Module Library 3337 3338 12.3.3 Detailed Actions 3339 1 3340 2 3341 3 3342 4 3343 5 3344 6 3345 7 3346 8 3347 9 3348 10 3349 11 3350 12 3351 13 3352 3353 #include "InternalRoutines.h" 3354 #include "IncrementalSelfTest_fp.h" 3355 3356 TPM_RC 3357 TPM2_IncrementalSelfTest( 3358 IncrementalSelfTest_In 3359 IncrementalSelfTest_Out 3360 3361 *in, 3362 *out 3363 3364 // IN: input parameter list 3365 // OUT: output parameter list 3366 3367 ) 3368 { 3369 // Command Output 3370 // Call incremental self test function in crypt module 3371 return CryptIncrementalSelfTest(&in->toTest, &out->toDoList); 3372 } 3373 3374 Page 34 3375 October 31, 2013 3376 3377 Published 3378 Copyright TCG 2006-2013 3379 3380 Family 2.0 3381 Level 00 Revision 00.99 3382 3383 Trusted Platform Module Library 3385 3386 12.4 3387 3388 Part 3: Commands 3389 3390 TPM2_GetTestResult 3391 3392 12.4.1 General Description 3393 This command returns manufacturer-specific information regarding the results of a self-test and an 3394 indication of the test status. 3395 If TPM2_SelfTest() has not been executed and a testable function has not been tested, testResult will be 3396 TPM_RC_NEEDS_TEST. If TPM2_SelfTest() has been received and the tests are not complete, 3397 testResult will be TPM_RC_TESTING. If testing of all functions is complete without functional failures, 3398 testResult will be TPM_RC_SUCCESS. If any test failed, testResult will be TPM_RC_FAILURE. If the 3399 TPM is in Failure mode because of an invalid startupType in TPM2_Startup(), testResult will be 3400 TPM_RC_INITIALIZE. 3401 This command will operate when the TPM is in Failure mode so that software can determine the test 3402 status of the TPM and so that diagnostic information can be obtained for use in failure analysis. If the 3403 TPM is in Failure mode, then tag is required to be TPM_ST_NO_SESSIONS or the TPM shall return 3404 TPM_RC_FAILURE. 3405 3406 Family 2.0 3407 Level 00 Revision 00.99 3408 3409 Published 3410 Copyright TCG 2006-2013 3411 3412 Page 35 3413 October 31, 2013 3414 3415 Part 3: Commands 3417 3418 Trusted Platform Module Library 3419 3420 12.4.2 Command and Response 3421 Table 13 TPM2_GetTestResult Command 3422 Type 3423 3424 Name 3425 3426 Description 3427 3428 TPMI_ST_COMMAND_TAG 3429 3430 tag 3431 3432 UINT32 3433 3434 commandSize 3435 3436 TPM_CC 3437 3438 commandCode 3439 3440 TPM_CC_GetTestResult 3441 3442 Table 14 TPM2_GetTestResult Response 3443 Type 3444 3445 Name 3446 3447 Description 3448 3449 TPMI_ST_COMMAND_TAG 3450 3451 tag 3452 3453 see clause 8 3454 3455 UINT32 3456 3457 responseSize 3458 3459 TPM_RC 3460 3461 responseCode 3462 3463 TPM2B_MAX_BUFFER 3464 3465 outData 3466 3467 TPM_RC 3468 3469 testResult 3470 3471 Page 36 3472 October 31, 2013 3473 3474 test result data 3475 contains manufacturer-specific information 3476 3477 Published 3478 Copyright TCG 2006-2013 3479 3480 Family 2.0 3481 Level 00 Revision 00.99 3482 3483 Trusted Platform Module Library 3485 3486 Part 3: Commands 3487 3488 12.4.3 Detailed Actions 3489 1 3490 2 3491 3 3492 4 3493 5 3494 6 3495 7 3496 8 3497 9 3498 10 3499 11 3500 12 3501 13 3502 14 3503 3504 #include "InternalRoutines.h" 3505 #include "GetTestResult_fp.h" 3506 3507 TPM_RC 3508 TPM2_GetTestResult( 3509 GetTestResult_Out 3510 ) 3511 { 3512 // Command Output 3513 3514 *out 3515 3516 // OUT: output parameter list 3517 3518 // Call incremental self test function in crypt module 3519 out->testResult = CryptGetTestResult(&out->outData); 3520 return TPM_RC_SUCCESS; 3521 } 3522 3523 Family 2.0 3524 Level 00 Revision 00.99 3525 3526 Published 3527 Copyright TCG 2006-2013 3528 3529 Page 37 3530 October 31, 2013 3531 3532 Part 3: Commands 3534 3535 Trusted Platform Module Library 3536 3537 Session Commands 3538 3539 13 3540 13.1 3541 3542 TPM2_StartAuthSession 3543 3544 13.1.1 General Description 3545 This command is used to start an authorization session using alternative methods of establishing the 3546 session key (sessionKey). The session key is then used to derive values used for authorization and for 3547 encrypting parameters. 3548 This command allows injection of a secret into the TPM using either asymmetric or symmetric encryption. 3549 The type of tpmKey determines how the value in encryptedSalt is encrypted. The decrypted secret value 3550 is used to compute the sessionKey. 3551 NOTE 1 3552 3553 If tpmKey Is TPM_RH_NULL, then encryptedSalt is required to be an Empty Buffer. 3554 3555 The label value of SECRET (see Terms and Definitions in Part 1 of this specification) is used in the 3556 recovery of the secret value. 3557 The TPM generates the sessionKey from the recovered secret value. 3558 No authorization is required for tpmKey or bind. 3559 NOTE 2 3560 3561 The justification for using tpmKey without providing authorization is that the result o f using the key is 3562 not available to the caller, except indirectly through the sessionKey. This does not represent a point 3563 of attack on the value of the key. If the caller attempts to use the session without knowing the 3564 sessionKey value, it is an authorization failure that will trigger the dictionary attack logic. 3565 3566 The entity referenced with the bind parameter contributes an authorization value to the sessionKey 3567 generation process. 3568 If both tpmKey and bind are TPM_ALG_NULL, then sessionKey is set to the Empty Buffer. If tpmKey is 3569 not TPM_ALG_NULL, then encryptedSalt is used in the computation of sessionKey. If bind is not 3570 TPM_ALG_NULL, the authValue of bind is used in the sessionKey computation. 3571 If symmetric specifies a block cipher, then TPM_ALG_CFB is the only allowed value for the mode field in 3572 the symmetric parameter (TPM_RC_MODE). 3573 This command starts an authorization session and returns the session handle along with an initial 3574 nonceTPM in the response. 3575 If the TPM does not have 3576 TPM_RC_SESSION_HANDLES. 3577 3578 a 3579 3580 free 3581 3582 slot 3583 3584 for 3585 3586 an 3587 3588 authorization 3589 3590 session, 3591 3592 it 3593 3594 shall 3595 3596 return 3597 3598 If the TPM implements a gap scheme for assigning contextID values, then the TPM shall return 3599 TPM_RC_CONTEXT_GAP if creating the session would prevent recycling of old saved contexts (See 3600 Context Management in Part 1). 3601 If tpmKey is not TPM_ALG_NULL then encryptedSalt shall be a TPM2B_ENCRYPTED_SECRET of the 3602 proper type for tpmKey. The TPM shall return TPM_RC_VALUE if: 3603 a) tpmKey references an RSA key and 3604 1) encryptedSalt does not contain a value that is the size of the public modulus of tpmKey, 3605 2) encryptedSalt has a value that is greater than the public modulus of tpmKey, 3606 3) encryptedSalt is not a properly encode OAEP value, or 3607 4) the decrypted salt value is larger than the size of the digest produced by the nameAlg of tpmKey; 3608 or 3609 3610 Page 38 3611 October 31, 2013 3612 3613 Published 3614 Copyright TCG 2006-2013 3615 3616 Family 2.0 3617 Level 00 Revision 00.99 3618 3619 Trusted Platform Module Library 3621 3622 Part 3: Commands 3623 3624 b) tpmKey references an ECC key and encryptedSalt 3625 1) does not contain a TPMS_ECC_POINT or 3626 2) is not a point on the curve of tpmKey; 3627 NOTE 3 3628 3629 When ECC is used, the point multiply process produces a value (Z) that is used in a KDF to 3630 produce the final secret value. The size of the secret value is an input parameter to the KDF 3631 and the result will be set to be the size of the digest produced by the nameAlg of tpmKey. 3632 3633 c) tpmKey references a symmetric block cipher or a keyedHash object and encryptedSalt contains a 3634 value that is larger than the size of the digest produced by the nameAlg of tpmKey. 3635 For all session types, this command will cause initialization of the sessionKey and may establish binding 3636 between the session and an object (the bind object). If sessionType is TPM_SE_POLICY or 3637 TPM_SE_TRIAL, the additional session initialization is: 3638 3639 3640 set policySessionpolicyDigest to a Zero Digest (the digest size for policySessionpolicyDigest is 3641 the size of the digest produced by authHash); 3642 3643 3644 3645 authorization may be given at any locality; 3646 3647 3648 3649 authorization may apply to any command code; 3650 3651 3652 3653 authorization may apply to any command parameters or handles; 3654 3655 3656 3657 the authorization has no time limit; 3658 3659 3660 3661 an authValue is not needed when the authorization is used; 3662 3663 3664 3665 the session is not bound; 3666 3667 3668 3669 the session is not an audit session; and 3670 3671 3672 3673 the time at which the policy session was created is recorded. 3674 3675 Additionally, if sessionType is TPM_SE_TRIAL, the session will not be usable for authorization but can be 3676 used to compute the authPolicy for an object. 3677 NOTE 4 3678 3679 Although this command changes the session allocation information in the TPM, it does not invalidate 3680 a 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 3681 slot in the TPM and sessions in the TPM do not survive any TPM2_Startup(). However, if a created 3682 session is context saved, the orderly state does change. 3683 3684 The TPM shall return TPM_RC_SIZE if nonceCaller is less than 16 octets or is greater than the size of 3685 the digest produced by authHash. 3686 3687 Family 2.0 3688 Level 00 Revision 00.99 3689 3690 Published 3691 Copyright TCG 2006-2013 3692 3693 Page 39 3694 October 31, 2013 3695 3696 Part 3: Commands 3698 3699 Trusted Platform Module Library 3700 3701 13.1.2 Command and Response 3702 Table 15 TPM2_StartAuthSession Command 3703 Type 3704 3705 Name 3706 3707 TPMI_ST_COMMAND_TAG 3708 3709 tag 3710 3711 UINT32 3712 3713 commandSize 3714 3715 TPM_CC 3716 3717 commandCode 3718 3719 TPM_CC_StartAuthSession 3720 3721 tpmKey 3722 3723 handle of a loaded decrypt key used to encrypt salt 3724 may be TPM_RH_NULL 3725 Auth Index: None 3726 3727 TPMI_DH_ENTITY+ 3728 3729 bind 3730 3731 entity providing the authValue 3732 may be TPM_RH_NULL 3733 Auth Index: None 3734 3735 TPM2B_NONCE 3736 3737 nonceCaller 3738 3739 TPMI_DH_OBJECT+ 3740 3741 Description 3742 3743 initial nonceCaller, sets nonce size for the session 3744 shall be at least 16 octets 3745 3746 TPM2B_ENCRYPTED_SECRET encryptedSalt 3747 3748 value encrypted according to the type of tpmKey 3749 If tpmKey is TPM_RH_NULL, this shall be the Empty 3750 Buffer. 3751 3752 TPM_SE 3753 3754 sessionType 3755 3756 indicates the type of the session; simple HMAC or policy 3757 (including a trial policy) 3758 3759 TPMT_SYM_DEF+ 3760 3761 symmetric 3762 3763 the algorithm and key size for parameter encryption 3764 may select TPM_ALG_NULL 3765 3766 TPMI_ALG_HASH 3767 3768 authHash 3769 3770 hash algorithm to use for the session 3771 Shall be a hash algorithm supported by the TPM and 3772 not TPM_ALG_NULL 3773 3774 Table 16 TPM2_StartAuthSession Response 3775 Type 3776 3777 Name 3778 3779 Description 3780 3781 TPM_ST 3782 3783 tag 3784 3785 see clause 8 3786 3787 UINT32 3788 3789 responseSize 3790 3791 TPM_RC 3792 3793 responseCode 3794 3795 TPMI_SH_AUTH_SESSION 3796 3797 sessionHandle 3798 3799 handle for the newly created session 3800 3801 TPM2B_NONCE 3802 3803 nonceTPM 3804 3805 the initial nonce from the TPM, used in the computation 3806 of the sessionKey 3807 3808 Page 40 3809 October 31, 2013 3810 3811 Published 3812 Copyright TCG 2006-2013 3813 3814 Family 2.0 3815 Level 00 Revision 00.99 3816 3817 Trusted Platform Module Library 3819 3820 Part 3: Commands 3821 3822 13.1.3 Detailed Actions 3823 1 3824 2 3825 3826 #include "InternalRoutines.h" 3827 #include "StartAuthSession_fp.h" 3828 Error Returns 3829 TPM_RC_ATTRIBUTES 3830 3831 tpmKey does not reference a decrypt key 3832 3833 TPM_RC_CONTEXT_GAP 3834 3835 the difference between the most recently created active context and 3836 the oldest active context is at the limits of the TPM 3837 3838 TPM_RC_HANDLE 3839 3840 input decrypt key handle only has public portion loaded 3841 3842 TPM_RC_MODE 3843 3844 symmetric specifies a block cipher but the mode is not 3845 TPM_ALG_CFB. 3846 3847 TPM_RC_SESSION_HANDLES 3848 3849 no session handle is available 3850 3851 TPM_RC_SESSION_MEMORY 3852 3853 no more slots for loading a session 3854 3855 TPM_RC_SIZE 3856 3857 nonce less than 16 octets or greater than the size of the digest 3858 produced by authHash 3859 3860 TPM_RC_VALUE 3861 3862 3 3863 4 3864 5 3865 6 3866 7 3867 8 3868 9 3869 10 3870 11 3871 12 3872 13 3873 14 3874 15 3875 16 3876 17 3877 18 3878 19 3879 20 3880 21 3881 22 3882 23 3883 24 3884 25 3885 26 3886 27 3887 28 3888 29 3889 30 3890 31 3891 32 3892 33 3893 34 3894 35 3895 36 3896 3897 Meaning 3898 3899 secret size does not match decrypt key type; or the recovered secret 3900 is larget than the digest size of the nameAlg of tpmKey; or, for an 3901 RSA decrypt key, if encryptedSecret is greater than the public 3902 exponent of tpmKey. 3903 3904 TPM_RC 3905 TPM2_StartAuthSession( 3906 StartAuthSession_In 3907 StartAuthSession_Out 3908 3909 *in, 3910 *out 3911 3912 // IN: input parameter buffer 3913 // OUT: output parameter buffer 3914 3915 TPM_RC 3916 OBJECT 3917 SESSION 3918 TPM2B_DATA 3919 3920 result = TPM_RC_SUCCESS; 3921 *tpmKey; 3922 // TPM key for decrypt salt 3923 *session; 3924 // session internal data 3925 salt; 3926 3927 ) 3928 { 3929 3930 // Input Validation 3931 // Check input nonce size. IT should be at least 16 bytes but not larger 3932 // than the digest size of session hash. 3933 if( 3934 in->nonceCaller.t.size < 16 3935 || in->nonceCaller.t.size > CryptGetHashDigestSize(in->authHash)) 3936 return TPM_RC_SIZE + RC_StartAuthSession_nonceCaller; 3937 // If an decrypt key is passed in, check its validation 3938 if(in->tpmKey != TPM_RH_NULL) 3939 { 3940 // secret size cannot be 0 3941 if(in->encryptedSalt.t.size == 0) 3942 return TPM_RC_VALUE + RC_StartAuthSession_encryptedSalt; 3943 // Get pointer to loaded decrypt key 3944 tpmKey = ObjectGet(in->tpmKey); 3945 // Decrypting salt requires accessing the private portion of a key. 3946 // Therefore, tmpKey can not be a key with only public portion loaded 3947 if(tpmKey->attributes.publicOnly) 3948 return TPM_RC_HANDLE + RC_StartAuthSession_tpmKey; 3949 3950 Family 2.0 3951 Level 00 Revision 00.99 3952 3953 Published 3954 Copyright TCG 2006-2013 3955 3956 Page 41 3957 October 31, 2013 3958 3959 Part 3: Commands 3961 37 3962 38 3963 39 3964 40 3965 41 3966 42 3967 43 3968 44 3969 45 3970 46 3971 47 3972 48 3973 49 3974 50 3975 51 3976 52 3977 53 3978 54 3979 55 3980 56 3981 57 3982 58 3983 59 3984 60 3985 61 3986 62 3987 63 3988 64 3989 65 3990 66 3991 67 3992 68 3993 69 3994 70 3995 71 3996 72 3997 73 3998 74 3999 75 4000 76 4001 77 4002 78 4003 79 4004 80 4005 81 4006 82 4007 83 4008 84 4009 85 4010 86 4011 87 4012 88 4013 89 4014 90 4015 4016 Trusted Platform Module Library 4017 4018 // HMAC session input handle check. 4019 // tpmKey should be a decryption key 4020 if(tpmKey->publicArea.objectAttributes.decrypt != SET) 4021 return TPM_RC_ATTRIBUTES + RC_StartAuthSession_tpmKey; 4022 // Secret Decryption. A TPM_RC_VALUE, TPM_RC_KEY or Unmarshal errors 4023 // may be returned at this point 4024 result = CryptSecretDecrypt(in->tpmKey, &in->nonceCaller, "SECRET", 4025 &in->encryptedSalt, &salt); 4026 if(result != TPM_RC_SUCCESS) 4027 return TPM_RC_VALUE + RC_StartAuthSession_encryptedSalt; 4028 } 4029 else 4030 { 4031 // secret size must be 0 4032 if(in->encryptedSalt.t.size != 0) 4033 return TPM_RC_VALUE + RC_StartAuthSession_encryptedSalt; 4034 salt.t.size = 0; 4035 } 4036 // If 'symmetric' is a symmetric block cipher (not TPM_ALG_NULL or TPM_ALG_XOR) 4037 // then the mode must be CFB. 4038 if( 4039 in->symmetric.algorithm != TPM_ALG_NULL 4040 && in->symmetric.algorithm != TPM_ALG_XOR 4041 && in->symmetric.mode.sym != TPM_ALG_CFB) 4042 return TPM_RC_MODE + RC_StartAuthSession_symmetric; 4043 // Internal Data Update 4044 // Create internal session structure. TPM_RC_CONTEXT_GAP, TPM_RC_NO_HANDLES 4045 // or TPM_RC_SESSION_MEMORY errors may be returned returned at this point. 4046 // 4047 // The detailed actions for creating the session context are not shown here 4048 // as the details are implementation dependent 4049 // SessionCreate sets the output handle 4050 result = SessionCreate(in->sessionType, in->authHash, 4051 &in->nonceCaller, &in->symmetric, 4052 in->bind, &salt, &out->sessionHandle); 4053 if(result != TPM_RC_SUCCESS) 4054 return result; 4055 // Command Output 4056 // Get session pointer 4057 session = SessionGet(out->sessionHandle); 4058 // Copy nonceTPM 4059 out->nonceTPM = session->nonceTPM; 4060 return TPM_RC_SUCCESS; 4061 } 4062 4063 Page 42 4064 October 31, 2013 4065 4066 Published 4067 Copyright TCG 2006-2013 4068 4069 Family 2.0 4070 Level 00 Revision 00.99 4071 4072 Trusted Platform Module Library 4074 4075 13.2 4076 4077 Part 3: Commands 4078 4079 TPM2_PolicyRestart 4080 4081 13.2.1 General Description 4082 This command allows a policy authorization session to be returned to its initial state. This command is 4083 used after the TPM returns TPM_RC_PCR_CHANGED. That response code indicates that a policy will 4084 fail because the PCR have changed after TPM2_PolicyPCR() was executed. Restarting the session 4085 allows the authorizations to be replayed because the session restarts with the same nonceTPM. If the 4086 PCR are valid for the policy, the policy may then succeed. 4087 This command does not reset the policy ID or the policy start time. 4088 4089 Family 2.0 4090 Level 00 Revision 00.99 4091 4092 Published 4093 Copyright TCG 2006-2013 4094 4095 Page 43 4096 October 31, 2013 4097 4098 Part 3: Commands 4100 4101 Trusted Platform Module Library 4102 4103 13.2.2 Command and Response 4104 Table 17 TPM2_PolicyRestart Command 4105 Type 4106 4107 Name 4108 4109 Description 4110 4111 TPMI_ST_COMMAND_TAG 4112 4113 tag 4114 4115 UINT32 4116 4117 commandSize 4118 4119 TPM_CC 4120 4121 commandCode 4122 4123 TPM_CC_PolicyRestart 4124 4125 TPMI_SH_POLICY 4126 4127 sessionHandle 4128 4129 the handle for the policy session 4130 4131 Table 18 TPM2_PolicyRestart Response 4132 Type 4133 4134 Name 4135 4136 Description 4137 4138 TPM_ST 4139 4140 tag 4141 4142 see clause 8 4143 4144 UINT32 4145 4146 responseSize 4147 4148 TPM_RC 4149 4150 responseCode 4151 4152 Page 44 4153 October 31, 2013 4154 4155 Published 4156 Copyright TCG 2006-2013 4157 4158 Family 2.0 4159 Level 00 Revision 00.99 4160 4161 Trusted Platform Module Library 4163 4164 Part 3: Commands 4165 4166 13.2.3 Detailed Actions 4167 1 4168 2 4169 3 4170 4 4171 5 4172 6 4173 7 4174 8 4175 9 4176 10 4177 11 4178 12 4179 13 4180 14 4181 15 4182 16 4183 17 4184 18 4185 19 4186 20 4187 21 4188 22 4189 4190 #include "InternalRoutines.h" 4191 #include "PolicyRestart_fp.h" 4192 4193 TPM_RC 4194 TPM2_PolicyRestart( 4195 PolicyRestart_In 4196 4197 *in 4198 4199 // IN: input parameter list 4200 4201 SESSION 4202 BOOL 4203 4204 *session; 4205 wasTrialSession; 4206 4207 ) 4208 { 4209 4210 // Internal Data Update 4211 session = SessionGet(in->sessionHandle); 4212 wasTrialSession = session->attributes.isTrialPolicy == SET; 4213 // Initialize policy session 4214 SessionResetPolicyData(session); 4215 session->attributes.isTrialPolicy = wasTrialSession; 4216 return TPM_RC_SUCCESS; 4217 } 4218 4219 Family 2.0 4220 Level 00 Revision 00.99 4221 4222 Published 4223 Copyright TCG 2006-2013 4224 4225 Page 45 4226 October 31, 2013 4227 4228 Part 3: Commands 4230 4231 Trusted Platform Module Library 4232 4233 Object Commands 4234 4235 14 4236 14.1 4237 4238 TPM2_Create 4239 4240 14.1.1 General Description 4241 This command is used to create an object that can be loaded into a TPM using TPM2_Load(). If the 4242 command completes successfully, the TPM will create the new object and return the objects creation 4243 data (creationData), its public area (outPublic), and its encrypted sensitive area (outPrivate). Preservation 4244 of the returned data is the responsibility of the caller. The object will need to be loaded (TPM2_Load()) 4245 before it may be used. 4246 TPM2B_PUBLIC template (inPublic) contains all of the fields necessary to define the properties of the 4247 new object. The setting for these fields is defined in Public Area Template in Part 1 and 4248 TPMA_OBJECT in Part 2. 4249 The parentHandle parameter shall reference a loaded decryption key that has both the public and 4250 sensitive area loaded. 4251 When defining the object, the caller provides a template structure for the object in a TPM2B_PUBLIC 4252 structure (inPublic), an initial value for the objects authValue (inSensitive.authValue), and, if the object is 4253 a symmetric object, an optional initial data value (inSensitive.data). The TPM shall validate the 4254 consistency of inPublic.attributes according to the Creation rules in TPMA_OBJECT in Part 2. 4255 The sensitive parameter may be encrypted using parameter encryption. 4256 The methods in this clause are used by both TPM2_Create() and TPM2_CreatePrimary(). When a value 4257 is indicated as being TPM-generated, the value is filled in by bits from the RNG if the command is 4258 TPM2_Create() and with values from KDFa() if the command is TPM2_CreatePrimary(). The parameters 4259 of each creation value are specified in Part 1. 4260 The sensitiveDataOrigin attribute of inPublic shall be SET if inSensitive.data is an Empty Buffer and 4261 CLEAR if inSensitive.data is not an Empty Buffer or the TPM shall return TPM_RC_ATTRIBUTES. 4262 The TPM will create new data for the sensitive area and compute a TPMT_PUBLIC.unique from the 4263 sensitive area based on the object type: 4264 a) For a symmetric key: 4265 1) If inSensitive.data is the Empty Buffer, a TPM-generated key value is placed in the new objects 4266 TPMT_SENSITIVE.sensitive.sym. The size of the key will be determined by 4267 inPublic.publicArea.parameters. 4268 2) If inSensitive.data is not the Empty Buffer, the TPM will validate that the size of inSensitive.data is 4269 no larger than the key size indicated in the inPublic template (TPM_RC_SIZE) and copy the 4270 inSensitive.data to TPMT_SENSITIVE.sensitive.sym of the new object. 4271 3) A TPM-generated obfuscation value is placed in TPMT_SENSITIVE.sensitive.seedValue. The 4272 size of the obfuscation value is the size of the digest produced by the nameAlg in inPublic. This 4273 value prevents the public unique value from leaking information about the sensitive area. 4274 4) The TPMT_PUBLIC.unique.sym.buffer value for the new object is then generated, as shown in 4275 equation (1) below, by hashing the key and obfuscation values in the TPMT_SENSITIVE with the 4276 nameAlg of the object. 4277 4278 unique HnameAlg(sensitive.seedValue.buffer || sensitive.any.buffer) 4279 4280 (1) 4281 4282 b) If the Object is an asymmetric key: 4283 1) If sensitive.data is not the Empty Buffer, then the TPM shall return TPM_RC_VALUE. 4284 4285 Page 46 4286 October 31, 2013 4287 4288 Published 4289 Copyright TCG 2006-2013 4290 4291 Family 2.0 4292 Level 00 Revision 00.99 4293 4294 Trusted Platform Module Library 4296 4297 Part 3: Commands 4298 4299 2) A TPM-generated private key value is created with the size determined by the parameters of 4300 inPublic.publicArea.parameters. 4301 3) If the key is a Storage Key, a TPM-generated TPMT_SENSITIVE.symKey value is created; 4302 otherwise, TPMT_SENSITIVE.symKey.size is set to zero. 4303 4) The public unique value is computed from the private key according to the methods of the key 4304 type. 4305 5) If the key is an ECC key and the scheme required by the curveID is not the same as scheme in 4306 the public area of the template, then the TPM shall return TPM_RC_SCHEME. 4307 6) If the key is an ECC key and the KDF required by the curveID is not the same as kdf in the pubic 4308 area of the template, then the TPM shall return TPM_RC_KDF. 4309 NOTE 1 4310 4311 There is currently no command in which the caller may specify the KDF to be used with an 4312 ECC decryption key. Since there is no use for this capability, the reference implementation 4313 requires that the kdf in the template be set to TPM_ALG_NULL or TPM_RC_KDF is 4314 returned. 4315 4316 c) If the Object is a keyedHash object: 4317 1) If inSensitive.data is an Empty Buffer, and neither sign nor decrypt is SET in inPublic.attributes, 4318 the TPM shall return TPM_RC_ATTRIBUTES. This would be a data object with no data. 4319 2) If inSensitive.data is not an Empty Buffer, the TPM will copy the inSensitive.data to 4320 TPMT_SENSITIVE.sensitive of the new object. 4321 NOTE 2 4322 4323 The size of inSensitive.data is limited to be no larger 4324 TPMT_SENSITIVE.sensitive.bits.data by MAX_SYM_DATA. 4325 4326 than 4327 4328 the 4329 4330 largest 4331 4332 value 4333 4334 of 4335 4336 3) If inSensitive.data is an Empty Buffer, a TPM-generated key value that is the size of the digest 4337 produced by the nameAlg in inPublic is placed in TPMT_SENSITIVE.sensitive.any.buffer. 4338 4) A TPM-generated obfuscation value that is the size of the digest produced by the nameAlg of 4339 inPublic is placed in TPMT_SENSITIVE.symKey.buffer. 4340 5) The TPMT_PUBLIC.unique.sym.buffer value for the new object is then generated, as shown in 4341 equation (1) above, by hashing the key and obfuscation values in the TPMT_SENSITIVE with the 4342 nameAlg of the object. 4343 For TPM2_Load(), the TPM will apply normal symmetric protections to the created TPMT_SENSITIVE to 4344 create outPublic. 4345 NOTE 3 4346 4347 The encryption key is derived from the symmetric seed in the sensitive area of the parent. 4348 4349 In addition to outPublic and outPrivate, the TPM will build a TPMS_CREATION_DATA structure for the 4350 object. TPMS_CREATION_DATA.outsideInfo is set to outsideInfo. This structure is returned in 4351 creationData. Additionally, the digest of this structure is returned in creationHash, and, finally, a 4352 TPMT_TK_CREATION is created so that the association between the creation data and the object may 4353 be validated by TPM2_CertifyCreation(). 4354 If the object being created is a Storage Key and inPublic.objectAttributes.fixedParent is SET, then the 4355 algorithms of inPublic are required to match those of the parent. The algorithms that must match are 4356 inPublic.type, inPublic.nameAlg, and inPublic.parameters. If inPublic.type does not match, the TPM shall 4357 return TPM_RC_TYPE. If inPublic.nameAlg does not match, the TPM shall return TPM_RC_HASH. If 4358 inPublic.parameters does not match, the TPM shall return TPM_RC_ASSYMETRIC. The TPM shall not 4359 differentiate between mismatches of the components of inPublic.parameters. 4360 EXAMPLE 4361 4362 If the inPublic.parameters.ecc.symmetric.algorithm does not match the parent, the TPM shall return 4363 TPM_RC_ ASYMMETRIC rather than TPM_RC_SYMMETRIC. 4364 4365 Family 2.0 4366 Level 00 Revision 00.99 4367 4368 Published 4369 Copyright TCG 2006-2013 4370 4371 Page 47 4372 October 31, 2013 4373 4374 Part 3: Commands 4376 4377 Trusted Platform Module Library 4378 4379 14.1.2 Command and Response 4380 Table 19 TPM2_Create Command 4381 Type 4382 4383 Name 4384 4385 Description 4386 4387 TPMI_ST_COMMAND_TAG 4388 4389 tag 4390 4391 UINT32 4392 4393 commandSize 4394 4395 TPM_CC 4396 4397 commandCode 4398 4399 TPM_CC_Create 4400 4401 TPMI_DH_OBJECT 4402 4403 @parentHandle 4404 4405 handle of parent for new object 4406 Auth Index: 1 4407 Auth Role: USER 4408 4409 TPM2B_SENSITIVE_CREATE 4410 4411 inSensitive 4412 4413 the sensitive data 4414 4415 TPM2B_PUBLIC 4416 4417 inPublic 4418 4419 the public template 4420 4421 TPM2B_DATA 4422 4423 outsideInfo 4424 4425 data that will be included in the creation data for this 4426 object to provide permanent, verifiable linkage between 4427 this object and some object owner data 4428 4429 TPML_PCR_SELECTION 4430 4431 creationPCR 4432 4433 PCR that will be used in creation data 4434 4435 Table 20 TPM2_Create Response 4436 Type 4437 4438 Name 4439 4440 Description 4441 4442 TPM_ST 4443 4444 tag 4445 4446 see clause 8 4447 4448 UINT32 4449 4450 responseSize 4451 4452 TPM_RC 4453 4454 responseCode 4455 4456 TPM2B_PRIVATE 4457 4458 outPrivate 4459 4460 the private portion of the object 4461 4462 TPM2B_PUBLIC 4463 4464 outPublic 4465 4466 the public portion of the created object 4467 4468 TPM2B_CREATION_DATA 4469 4470 creationData 4471 4472 contains a TPMS_CREATION_DATA 4473 4474 TPM2B_DIGEST 4475 4476 creationHash 4477 4478 digest of creationData using nameAlg of outPublic 4479 4480 TPMT_TK_CREATION 4481 4482 creationTicket 4483 4484 ticket used by TPM2_CertifyCreation() to validate that 4485 the creation data was produced by the TPM 4486 4487 Page 48 4488 October 31, 2013 4489 4490 Published 4491 Copyright TCG 2006-2013 4492 4493 Family 2.0 4494 Level 00 Revision 00.99 4495 4496 Trusted Platform Module Library 4498 4499 Part 3: Commands 4500 4501 14.1.3 Detailed Actions 4502 1 4503 2 4504 3 4505 4506 #include "InternalRoutines.h" 4507 #include "Object_spt_fp.h" 4508 #include "Create_fp.h" 4509 Error Returns 4510 TPM_RC_ASYMMETRIC 4511 4512 non-duplicable storage key and its parent have different public 4513 params 4514 4515 TPM_RC_ATTRIBUTES 4516 4517 sensitiveDataOrigin is CLEAR when 'sensitive. data' is an Empty 4518 Buffer, or is SET when 'sensitive. data' is not empty; fixedTPM, 4519 fixedParent, or encryptedDuplication attributes are inconsistent 4520 between themselves or with those of the parent object; inconsistent 4521 restricted, decrypt and sign attributes; attempt to inject sensitive data 4522 for an asymmetric key; attempt to create a symmetric cipher key that 4523 is not a decryption key 4524 4525 TPM_RC_HASH 4526 4527 non-duplicable storage key and its parent have different name 4528 algorithm 4529 4530 TPM_RC_KDF 4531 4532 incorrect KDF specified for decrypting keyed hash object 4533 4534 TPM_RC_KEY 4535 4536 invalid key size values in an asymmetric key public area 4537 4538 TPM_RC_KEY_SIZE 4539 4540 key size in public area for symmetric key differs from the size in the 4541 sensitive creation area; may also be returned if the TPM does not 4542 allow the key size to be used for a Storage Key 4543 4544 TPM_RC_RANGE 4545 4546 FOr() an RSA key, the exponent value is not supported. 4547 4548 TPM_RC_SCHEME 4549 4550 inconsistent attributes decrypt, sign, restricted and key's scheme ID; 4551 or hash algorithm is inconsistent with the scheme ID for keyed hash 4552 object 4553 4554 TPM_RC_SIZE 4555 4556 size of public auth policy or sensitive auth value does not match 4557 digest size of the name algorithm sensitive data size for the keyed 4558 hash object is larger than is allowed for the scheme 4559 4560 TPM_RC_SYMMETRIC 4561 4562 a storage key with no symmetric algorithm specified; or non-storage 4563 key with symmetric algorithm different from TPM_ALG_NULL 4564 4565 TPM_RC_TYPE 4566 4567 unknown object type; non-duplicable storage key and its parent have 4568 different types; parentHandle does not reference a restricted 4569 decryption key in the storage hierarchy with both public and sensitive 4570 portion loaded 4571 4572 TPM_RC_VALUE 4573 4574 exponent is not prime or could not find a prime using the provided 4575 parameters for an RSA key; unsupported name algorithm for an ECC 4576 key 4577 4578 TPM_RC_OBJECT_MEMORY 4579 4580 4 4581 5 4582 6 4583 7 4584 8 4585 9 4586 10 4587 11 4588 12 4589 13 4590 4591 Meaning 4592 4593 there is no free slot for the object. This implementation does not 4594 return this error. 4595 4596 TPM_RC 4597 TPM2_Create( 4598 Create_In 4599 Create_Out 4600 4601 *in, 4602 *out 4603 4604 // IN: input parameter list 4605 // OUT: output parameter list 4606 4607 ) 4608 { 4609 TPM_RC 4610 TPMT_SENSITIVE 4611 TPM2B_NAME 4612 4613 Family 2.0 4614 Level 00 Revision 00.99 4615 4616 result = TPM_RC_SUCCESS; 4617 sensitive; 4618 name; 4619 4620 Published 4621 Copyright TCG 2006-2013 4622 4623 Page 49 4624 October 31, 2013 4625 4626 Part 3: Commands 4628 14 4629 15 4630 16 4631 17 4632 18 4633 19 4634 20 4635 21 4636 22 4637 23 4638 24 4639 25 4640 26 4641 27 4642 28 4643 29 4644 30 4645 31 4646 32 4647 33 4648 34 4649 35 4650 36 4651 37 4652 38 4653 39 4654 40 4655 41 4656 42 4657 43 4658 44 4659 45 4660 46 4661 47 4662 48 4663 49 4664 50 4665 51 4666 52 4667 53 4668 54 4669 55 4670 56 4671 57 4672 58 4673 59 4674 60 4675 61 4676 62 4677 63 4678 64 4679 65 4680 66 4681 67 4682 68 4683 69 4684 70 4685 71 4686 72 4687 73 4688 4689 Trusted Platform Module Library 4690 4691 // Input Validation 4692 OBJECT 4693 4694 *parentObject; 4695 4696 parentObject = ObjectGet(in->parentHandle); 4697 // Does parent have the proper attributes? 4698 if(!AreAttributesForParent(parentObject)) 4699 return TPM_RC_TYPE + RC_Create_parentHandle; 4700 // The sensitiveDataOrigin attribute must be consistent with the setting of 4701 // the size of the data object in inSensitive. 4702 if( 4703 (in->inPublic.t.publicArea.objectAttributes.sensitiveDataOrigin == SET) 4704 != (in->inSensitive.t.sensitive.data.t.size == 0)) 4705 // Mismatch between the object attributes and the parameter. 4706 return TPM_RC_ATTRIBUTES + RC_Create_inSensitive; 4707 // Check attributes in input public area. TPM_RC_ASYMMETRIC, TPM_RC_ATTRIBUTES, 4708 // TPM_RC_HASH, TPM_RC_KDF, TPM_RC_SCHEME, TPM_RC_SIZE, TPM_RC_SYMMETRIC, 4709 // or TPM_RC_TYPE error may be returned at this point. 4710 result = PublicAttributesValidation(FALSE, in->parentHandle, 4711 &in->inPublic.t.publicArea); 4712 if(result != TPM_RC_SUCCESS) 4713 return RcSafeAddToResult(result, RC_Create_inPublic); 4714 // Validate the sensitive area values 4715 if( MemoryRemoveTrailingZeros(&in->inSensitive.t.sensitive.userAuth) 4716 > CryptGetHashDigestSize(in->inPublic.t.publicArea.nameAlg)) 4717 return TPM_RC_SIZE + RC_Create_inSensitive; 4718 // Command Output 4719 // Create object crypto data 4720 result = CryptCreateObject(in->parentHandle, &in->inPublic.t.publicArea, 4721 &in->inSensitive.t.sensitive, &sensitive); 4722 if(result != TPM_RC_SUCCESS) 4723 return result; 4724 // Fill in creation data 4725 FillInCreationData(in->parentHandle, in->inPublic.t.publicArea.nameAlg, 4726 &in->creationPCR, &in->outsideInfo, 4727 &out->creationData, &out->creationHash); 4728 // Copy public area from input to output 4729 out->outPublic.t.publicArea = in->inPublic.t.publicArea; 4730 // Compute name from public area 4731 ObjectComputeName(&(out->outPublic.t.publicArea), &name); 4732 // Compute creation ticket 4733 TicketComputeCreation(EntityGetHierarchy(in->parentHandle), &name, 4734 &out->creationHash, &out->creationTicket); 4735 // Prepare output private data from sensitive 4736 SensitiveToPrivate(&sensitive, &name, in->parentHandle, 4737 out->outPublic.t.publicArea.nameAlg, 4738 &out->outPrivate); 4739 return TPM_RC_SUCCESS; 4740 } 4741 4742 Page 50 4743 October 31, 2013 4744 4745 Published 4746 Copyright TCG 2006-2013 4747 4748 Family 2.0 4749 Level 00 Revision 00.99 4750 4751 Trusted Platform Module Library 4753 4754 14.2 4755 4756 Part 3: Commands 4757 4758 TPM2_Load 4759 4760 14.2.1 General Description 4761 This command is used to load objects into the TPM. This command is used when both a TPM2B_PUBLIC 4762 and TPM2B_PRIVATE are to be loaded. If only a TPM2B_PUBLIC is to be loaded, the 4763 TPM2_LoadExternal command is used. 4764 NOTE 1 4765 4766 Loading an object is not the same as restoring a saved object context. 4767 4768 The objects TPMA_OBJECT attributes will be checked according to the rules defined in 4769 TPMA_OBJECT in Part 2 of this specification. 4770 Objects loaded using this command will have a Name. The Name is the concatenation of nameAlg and 4771 the digest of the public area using the nameAlg. 4772 NOTE 2 4773 4774 nameAlg is a parameter in the public area of the inPublic structure. 4775 4776 If inPrivate.size is zero, the load will fail. 4777 After inPrivate.buffer is decrypted using the symmetric key of the parent, the integrity value shall be 4778 checked before the sensitive area is used, or unmarshaled. 4779 NOTE 3 4780 4781 Checking the integrity before the data is used prevents attacks o n the sensitive area by fuzzing the 4782 data and looking at the differences in the response codes. 4783 4784 The command returns a handle for the loaded object and the Name that the TPM computed for 4785 inPublic.public (that is, the digest of the TPMT_PUBLIC structure in inPublic). 4786 NOTE 4 4787 4788 The TPM-computed Name is provided as a convenience to the caller for those cases where the 4789 caller does not implement the hash algorithms specified in the nameAlg of the object. 4790 4791 NOTE 5 4792 4793 The returned handle is associated with the object until the object is flushed (TPM2_FlushContext) or 4794 until the next TPM2_Startup. 4795 4796 For all objects, the size of the key in the sensitive area shall be consistent with the key size indicated in 4797 the public area or the TPM shall return TPM_RC_KEY_SIZE. 4798 Before use, a loaded object shall be checked to validate that the public and sensitive portions are 4799 properly linked, cryptographically. Use of an object includes use in any policy command. If the parts of the 4800 object are not properly linked, the TPM shall return TPM_RC_BINDING. 4801 EXAMPLE 1 4802 4803 For a symmetric object, the unique value in the public area shall be the digest of the sensitive key 4804 and the obfuscation value. 4805 4806 EXAMPLE 2 4807 4808 For a two-prime RSA key, the remainder when dividing the public modulus by the private key shall 4809 be zero and it shall be possible to form a private exponent from the two prime factors of the public 4810 modulus. 4811 4812 EXAMPLE 3 4813 4814 For an ECC key, the public point shall be f(x) where x is the private key. 4815 4816 Family 2.0 4817 Level 00 Revision 00.99 4818 4819 Published 4820 Copyright TCG 2006-2013 4821 4822 Page 51 4823 October 31, 2013 4824 4825 Part 3: Commands 4827 4828 Trusted Platform Module Library 4829 4830 14.2.2 Command and Response 4831 Table 21 TPM2_Load Command 4832 Type 4833 4834 Name 4835 4836 Description 4837 4838 TPMI_ST_COMMAND_TAG 4839 4840 tag 4841 4842 UINT32 4843 4844 commandSize 4845 4846 TPM_CC 4847 4848 commandCode 4849 4850 TPM_CC_Load 4851 4852 TPMI_DH_OBJECT 4853 4854 @parentHandle 4855 4856 TPM handle of parent key; shall not be a reserved 4857 handle 4858 Auth Index: 1 4859 Auth Role: USER 4860 4861 TPM2B_PRIVATE 4862 4863 inPrivate 4864 4865 the private portion of the object 4866 4867 TPM2B_PUBLIC 4868 4869 inPublic 4870 4871 the public portion of the object 4872 4873 Table 22 TPM2_Load Response 4874 Type 4875 4876 Name 4877 4878 Description 4879 4880 TPM_ST 4881 4882 tag 4883 4884 see clause 8 4885 4886 UINT32 4887 4888 responseSize 4889 4890 TPM_RC 4891 4892 responseCode 4893 4894 TPM_HANDLE 4895 4896 objectHandle 4897 4898 handle for the loaded object 4899 4900 TPM2B_NAME 4901 4902 name 4903 4904 Name of the loaded object 4905 4906 Page 52 4907 October 31, 2013 4908 4909 Published 4910 Copyright TCG 2006-2013 4911 4912 Family 2.0 4913 Level 00 Revision 00.99 4914 4915 Trusted Platform Module Library 4917 4918 Part 3: Commands 4919 4920 14.2.3 Detailed Actions 4921 1 4922 2 4923 3 4924 4925 #include "InternalRoutines.h" 4926 #include "Load_fp.h" 4927 #include "Object_spt_fp.h" 4928 Error Returns 4929 TPM_RC_ASYMMETRIC 4930 4931 storage key with different asymmetric type than parent 4932 4933 TPM_RC_ATTRIBUTES 4934 4935 inPulblic attributes are not allowed with selected parent 4936 4937 TPM_RC_BINDING 4938 4939 inPrivate and inPublic are not cryptographically bound 4940 4941 TPM_RC_HASH 4942 4943 incorrect hash selection for signing key 4944 4945 TPM_RC_INTEGRITY 4946 4947 HMAC on inPrivate was not valid 4948 4949 TPM_RC_KDF 4950 4951 KDF selection not allowed 4952 4953 TPM_RC_KEY 4954 4955 the size of the object's unique field is not consistent with the indicated 4956 size in the object's parameters 4957 4958 TPM_RC_OBJECT_MEMORY 4959 4960 no available object slot 4961 4962 TPM_RC_SCHEME 4963 4964 the signing scheme is not valid for the key 4965 4966 TPM_RC_SENSITIVE 4967 4968 the inPrivate did not unmarshal correctly 4969 4970 TPM_RC_SIZE 4971 4972 inPrivate missing, or authPolicy size for inPublic or is not valid 4973 4974 TPM_RC_SYMMETRIC 4975 4976 symmetric algorithm not provided when required 4977 4978 TPM_RC_TYPE 4979 4980 parentHandle is not a storage key, or the object to load is a storage 4981 key but its parameters do not match the parameters of the parent. 4982 4983 TPM_RC_VALUE 4984 4 4985 5 4986 6 4987 7 4988 8 4989 9 4990 10 4991 11 4992 12 4993 13 4994 14 4995 15 4996 16 4997 17 4998 18 4999 19 5000 20 5001 21 5002 22 5003 23 5004 24 5005 25 5006 26 5007 27 5008 28 5009 29 5010 30 5011 5012 Meaning 5013 5014 decryption failure 5015 5016 TPM_RC 5017 TPM2_Load( 5018 Load_In *in, 5019 Load_Out *out 5020 5021 // IN: input parameter list 5022 // OUT: output parameter list 5023 5024 ) 5025 { 5026 TPM_RC 5027 TPMT_SENSITIVE 5028 TPMI_RH_HIERARCHY 5029 OBJECT 5030 BOOL 5031 5032 result = TPM_RC_SUCCESS; 5033 sensitive; 5034 hierarchy; 5035 *parentObject = NULL; 5036 skipChecks = FALSE; 5037 5038 // Input Validation 5039 if(in->inPrivate.t.size == 0) 5040 return TPM_RC_SIZE + RC_Load_inPrivate; 5041 parentObject = ObjectGet(in->parentHandle); 5042 // Is the object that is being used as the parent actually a parent. 5043 if(!AreAttributesForParent(parentObject)) 5044 return TPM_RC_TYPE + RC_Load_parentHandle; 5045 // If the parent is fixedTPM, then the attributes of the object 5046 // are either "correct by construction" or were validated 5047 // when the object was imported. If they pass the integrity 5048 // check, then the values are valid 5049 if(parentObject->publicArea.objectAttributes.fixedTPM) 5050 skipChecks = TRUE; 5051 5052 Family 2.0 5053 Level 00 Revision 00.99 5054 5055 Published 5056 Copyright TCG 2006-2013 5057 5058 Page 53 5059 October 31, 2013 5060 5061 Part 3: Commands 5063 31 5064 32 5065 33 5066 34 5067 35 5068 36 5069 37 5070 38 5071 39 5072 40 5073 41 5074 42 5075 43 5076 44 5077 45 5078 46 5079 47 5080 48 5081 49 5082 50 5083 51 5084 52 5085 53 5086 54 5087 55 5088 56 5089 57 5090 58 5091 59 5092 60 5093 61 5094 62 5095 63 5096 64 5097 65 5098 66 5099 67 5100 68 5101 69 5102 70 5103 71 5104 72 5105 73 5106 74 5107 75 5108 76 5109 5110 Trusted Platform Module Library 5111 5112 else 5113 { 5114 // If parent doesn't have fixedTPM SET, then this can't have 5115 // fixedTPM SET. 5116 if(in->inPublic.t.publicArea.objectAttributes.fixedTPM == SET) 5117 return TPM_RC_ATTRIBUTES + RC_Load_inPublic; 5118 // Perform self check on input public area. A TPM_RC_SIZE, TPM_RC_SCHEME, 5119 // TPM_RC_VALUE, TPM_RC_SYMMETRIC, TPM_RC_TYPE, TPM_RC_HASH, 5120 // TPM_RC_ASYMMETRIC, TPM_RC_ATTRIBUTES or TPM_RC_KDF error may be returned 5121 // at this point 5122 result = PublicAttributesValidation(TRUE, in->parentHandle, 5123 &in->inPublic.t.publicArea); 5124 if(result != TPM_RC_SUCCESS) 5125 return RcSafeAddToResult(result, RC_Load_inPublic); 5126 } 5127 // Compute the name of object 5128 ObjectComputeName(&in->inPublic.t.publicArea, &out->name); 5129 // Retrieve sensitive data. PrivateToSensitive() may return TPM_RC_INTEGRITY or 5130 // TPM_RC_SENSITIVE 5131 // errors may be returned at this point 5132 result = PrivateToSensitive(&in->inPrivate, &out->name, in->parentHandle, 5133 in->inPublic.t.publicArea.nameAlg, 5134 &sensitive); 5135 if(result != TPM_RC_SUCCESS) 5136 return RcSafeAddToResult(result, RC_Load_inPrivate); 5137 // Internal Data Update 5138 // Get hierarchy of parent 5139 hierarchy = ObjectGetHierarchy(in->parentHandle); 5140 // Create internal object. A lot of different errors may be returned by this 5141 // loading operation as it will do several validations, including the public 5142 // binding check 5143 result = ObjectLoad(hierarchy, &in->inPublic.t.publicArea, &sensitive, 5144 &out->name, in->parentHandle, skipChecks, 5145 &out->objectHandle); 5146 if(result != TPM_RC_SUCCESS) 5147 return result; 5148 return TPM_RC_SUCCESS; 5149 } 5150 5151 Page 54 5152 October 31, 2013 5153 5154 Published 5155 Copyright TCG 2006-2013 5156 5157 Family 2.0 5158 Level 00 Revision 00.99 5159 5160 Trusted Platform Module Library 5162 5163 14.3 5164 5165 Part 3: Commands 5166 5167 TPM2_LoadExternal 5168 5169 14.3.1 General Description 5170 This command is used to load an object that is not a Protected Object into the TPM. The command allows 5171 loading of a public area or both a public and sensitive area. 5172 NOTE 1 5173 5174 Typical use for loading a public area is to allow the TPM to validate an asymmetric signature. 5175 Typical use for loading both a public and sensitive area is to allow the TPM to be used as a crypto 5176 accelerator. 5177 5178 Load of a public external object area allows the object be associated with a hierarchy so that the correct 5179 algorithms may be used when creating tickets. The hierarchy parameter provides this association. If the 5180 public and sensitive portions of the object are loaded, hierarchy is required to be TPM_RH_NULL. 5181 NOTE 2 5182 5183 If both the public and private portions of an object are loaded, the object is not allowed to appear to 5184 be part of a hierarchy. 5185 5186 The objects TPMA_OBJECT attributes will be checked according to the rules defined in 5187 TPMA_OBJECT in Part 2. In particular, fixedTPM, fixedParent, and restricted shall be CLEAR if 5188 inPrivate is not the Empty Buffer. 5189 NOTE 3 5190 5191 The duplication status of a public key needs to be able to be the same as the full key which may be 5192 resident on a different TPM. If both the public and private parts of the key are loaded, then it is not 5193 possible for the key to be either fixedTPM or fixedParent, since, its private area would not be 5194 available in the clear to load. 5195 5196 Objects loaded using this command will have a Name. The Name is the nameAlg of the object 5197 concatenated with the digest of the public area using the nameAlg. The Qualified Name for the object will 5198 be the same as its Name. The TPM will validate that the authPolicy is either the size of the digest 5199 produced by nameAlg or the Empty Buffer. 5200 NOTE 4 5201 5202 If nameAlg is TPM_ALG_NULL, then the Name is the Empty Buffer. When the authorization value for 5203 an object with no Name is computed, no Name value is included in the HMAC. To ensure that these 5204 unnamed entities are not substituted, they should have an authValue that is statistically unique. 5205 5206 NOTE 5 5207 5208 The digest size for TPM_ALG_NULL is zero. 5209 5210 If the nameAlg is TPM_ALG_NULL, the TPM shall not verify the cryptographic binding between the public 5211 and sensitive areas, but the TPM will validate that the size of the key in the sensitive area is consistent 5212 with the size indicated in the public area. If it is not, the TPM shall return TPM_RC_KEY_SIZE. 5213 NOTE 6 5214 5215 For an ECC object, the TPM will verify that the public key is on the curve of the key before the public 5216 area is used. 5217 5218 If nameAlg is not TPM_ALG_NULL, then the same consistency checks between inPublic and inPrivate 5219 are made as for TPM2_Load(). 5220 NOTE 7 5221 5222 Consistency checks are necessary because an object with a Name needs to have the public and 5223 sensitive portions cryptographically bound so that an attacker cannot mix pubic and sensitive areas. 5224 5225 The command returns a handle for the loaded object and the Name that the TPM computed for 5226 inPublic.public (that is, the TPMT_PUBLIC structure in inPublic). 5227 NOTE 8 5228 5229 The TPM-computed Name is provided as a convenience to the caller for those cases where the 5230 caller does not implement the hash algorithm specified in the nameAlg of the object. 5231 5232 Family 2.0 5233 Level 00 Revision 00.99 5234 5235 Published 5236 Copyright TCG 2006-2013 5237 5238 Page 55 5239 October 31, 2013 5240 5241 Part 3: Commands 5243 5244 Trusted Platform Module Library 5245 5246 The hierarchy parameter associates the external object with a hierarchy. External objects are flushed 5247 when their associated hierarchy is disabled. If hierarchy is TPM_RH_NULL, the object is part of no 5248 hierarchy, and there is no implicit flush. 5249 If hierarchy is TPM_RH_NULL or nameAlg is TPM_ALG_NULL, a ticket produced using the object shall 5250 be a NULL Ticket. 5251 EXAMPLE 5252 5253 If a key is loaded with hierarchy set to TPM_RH_NULL, then TPM2_VerifySignature() will produce a 5254 NULL Ticket of the required type. 5255 5256 External objects are Temporary Objects. The saved external object contexts shall be invalidated at the 5257 next TPM Reset. 5258 5259 Page 56 5260 October 31, 2013 5261 5262 Published 5263 Copyright TCG 2006-2013 5264 5265 Family 2.0 5266 Level 00 Revision 00.99 5267 5268 Trusted Platform Module Library 5270 5271 Part 3: Commands 5272 5273 14.3.2 Command and Response 5274 Table 23 TPM2_LoadExternal Command 5275 Type 5276 5277 Name 5278 5279 Description 5280 5281 TPMI_ST_COMMAND_TAG 5282 5283 tag 5284 5285 UINT32 5286 5287 commandSize 5288 5289 TPM_CC 5290 5291 commandCode 5292 5293 TPM_CC_LoadExternal 5294 5295 TPM2B_SENSITIVE 5296 5297 inPrivate 5298 5299 the sensitive portion of the object (optional) 5300 5301 TPM2B_PUBLIC+ 5302 5303 inPublic 5304 5305 the public portion of the object 5306 5307 TPMI_RH_HIERARCHY+ 5308 5309 hierarchy 5310 5311 hierarchy with which the object area is associated 5312 5313 Table 24 TPM2_LoadExternal Response 5314 Type 5315 5316 Name 5317 5318 Description 5319 5320 TPM_ST 5321 5322 tag 5323 5324 see clause 8 5325 5326 UINT32 5327 5328 responseSize 5329 5330 TPM_RC 5331 5332 responseCode 5333 5334 TPM_HANDLE 5335 5336 objectHandle 5337 5338 handle for the loaded object 5339 5340 TPM2B_NAME 5341 5342 name 5343 5344 name of the loaded object 5345 5346 Family 2.0 5347 Level 00 Revision 00.99 5348 5349 Published 5350 Copyright TCG 2006-2013 5351 5352 Page 57 5353 October 31, 2013 5354 5355 Part 3: Commands 5357 5358 Trusted Platform Module Library 5359 5360 14.3.3 Detailed Actions 5361 1 5362 2 5363 3 5364 5365 #include "InternalRoutines.h" 5366 #include "LoadExternal_fp.h" 5367 #include "Object_spt_fp.h" 5368 Error Returns 5369 TPM_RC_ATTRIBUTES 5370 5371 'fixedParent" and fixedTPM must be CLEAR on on an external key if 5372 both public and sensitive portions are loaded 5373 5374 TPM_RC_BINDING 5375 5376 the inPublic and inPrivate structures are not cryptographically bound. 5377 5378 TPM_RC_HASH 5379 5380 incorrect hash selection for signing key 5381 5382 TPM_RC_HIERARCHY 5383 5384 hierarchy is turned off, or only NULL hierarchy is allowed when 5385 loading public and private parts of an object 5386 5387 TPM_RC_KDF 5388 5389 incorrect KDF selection for decrypting keyedHash object 5390 5391 TPM_RC_KEY 5392 5393 the size of the object's unique field is not consistent with the indicated 5394 size in the object's parameters 5395 5396 TPM_RC_OBJECT_MEMORY 5397 5398 if there is no free slot for an object 5399 5400 TPM_RC_SCHEME 5401 5402 the signing scheme is not valid for the key 5403 5404 TPM_RC_SIZE 5405 5406 authPolicy is not zero and is not the size of a digest produced by the 5407 object's nameAlg TPM_RH_NULL hierarchy 5408 5409 TPM_RC_SYMMETRIC 5410 5411 symmetric algorithm not provided when required 5412 5413 TPM_RC_TYPE 5414 4 5415 5 5416 6 5417 7 5418 8 5419 9 5420 10 5421 11 5422 12 5423 13 5424 14 5425 15 5426 16 5427 17 5428 18 5429 19 5430 20 5431 21 5432 22 5433 23 5434 24 5435 25 5436 26 5437 27 5438 28 5439 29 5440 30 5441 31 5442 32 5443 33 5444 5445 Meaning 5446 5447 inPublic and inPrivate are not the same type 5448 5449 TPM_RC 5450 TPM2_LoadExternal( 5451 LoadExternal_In 5452 LoadExternal_Out 5453 5454 *in, 5455 *out 5456 5457 // IN: input parameter list 5458 // OUT: output parameter list 5459 5460 TPM_RC 5461 TPMT_SENSITIVE 5462 BOOL 5463 5464 result; 5465 *sensitive; 5466 skipChecks; 5467 5468 ) 5469 { 5470 5471 // Input Validation 5472 // If the target hierarchy is turned off, the object can not be loaded. 5473 if(!HierarchyIsEnabled(in->hierarchy)) 5474 return TPM_RC_HIERARCHY + RC_LoadExternal_hierarchy; 5475 // the size of authPolicy is either 0 or the digest size of nameAlg 5476 if(in->inPublic.t.publicArea.authPolicy.t.size != 0 5477 && in->inPublic.t.publicArea.authPolicy.t.size != 5478 CryptGetHashDigestSize(in->inPublic.t.publicArea.nameAlg)) 5479 return TPM_RC_SIZE + RC_LoadExternal_inPublic; 5480 // For loading an object with both public and sensitive 5481 if(in->inPrivate.t.size != 0) 5482 { 5483 // An external object can only be loaded at TPM_RH_NULL hierarchy 5484 if(in->hierarchy != TPM_RH_NULL) 5485 return TPM_RC_HIERARCHY + RC_LoadExternal_hierarchy; 5486 // An external object with a sensitive area must have fixedTPM == CLEAR 5487 // fixedParent == CLEAR, and must have restrict CLEAR so that it does not 5488 5489 Page 58 5490 October 31, 2013 5491 5492 Published 5493 Copyright TCG 2006-2013 5494 5495 Family 2.0 5496 Level 00 Revision 00.99 5497 5498 Trusted Platform Module Library 5500 34 5501 35 5502 36 5503 37 5504 38 5505 39 5506 40 5507 41 5508 42 5509 43 5510 44 5511 45 5512 46 5513 47 5514 48 5515 49 5516 50 5517 51 5518 52 5519 53 5520 54 5521 55 5522 56 5523 57 5524 58 5525 59 5526 60 5527 61 5528 62 5529 63 5530 64 5531 65 5532 5533 Part 3: Commands 5534 5535 // appear to be a key that was created by this TPM. 5536 if( 5537 in->inPublic.t.publicArea.objectAttributes.fixedTPM != CLEAR 5538 || in->inPublic.t.publicArea.objectAttributes.fixedParent != CLEAR 5539 || in->inPublic.t.publicArea.objectAttributes.restricted != CLEAR 5540 ) 5541 return TPM_RC_ATTRIBUTES + RC_LoadExternal_inPublic; 5542 } 5543 // Validate the scheme parameters 5544 result = SchemeChecks(TRUE, TPM_RH_NULL, &in->inPublic.t.publicArea); 5545 if(result != TPM_RC_SUCCESS) 5546 return RcSafeAddToResult(result, RC_LoadExternal_inPublic); 5547 // Internal Data Update 5548 // Need the name to compute the qualified name 5549 ObjectComputeName(&in->inPublic.t.publicArea, &out->name); 5550 skipChecks = (in->inPublic.t.publicArea.nameAlg == TPM_ALG_NULL); 5551 // If a sensitive area was provided, load it 5552 if(in->inPrivate.t.size != 0) 5553 sensitive = &in->inPrivate.t.sensitiveArea; 5554 else 5555 sensitive = NULL; 5556 // Create external object. A TPM_RC_BINDING, TPM_RC_KEY, TPM_RC_OBJECT_MEMORY 5557 // or TPM_RC_TYPE error may be returned by ObjectLoad() 5558 result = ObjectLoad(in->hierarchy, &in->inPublic.t.publicArea, 5559 sensitive, &out->name, TPM_RH_NULL, skipChecks, 5560 &out->objectHandle); 5561 return result; 5562 } 5563 5564 Family 2.0 5565 Level 00 Revision 00.99 5566 5567 Published 5568 Copyright TCG 2006-2013 5569 5570 Page 59 5571 October 31, 2013 5572 5573 Part 3: Commands 5575 5576 14.4 5577 5578 Trusted Platform Module Library 5579 5580 TPM2_ReadPublic 5581 5582 14.4.1 General Description 5583 This command allows access to the public area of a loaded object. 5584 Use of the objectHandle does not require authorization. 5585 NOTE 5586 5587 Since the caller is not likely to know the public area of the object associated with objectHandle, it 5588 would not be possible to include the Name associated with objectHandle in the cpHash computation. 5589 5590 If objectHandle references a sequence object, the TPM shall return TPM_RC_SEQUENCE. 5591 5592 Page 60 5593 October 31, 2013 5594 5595 Published 5596 Copyright TCG 2006-2013 5597 5598 Family 2.0 5599 Level 00 Revision 00.99 5600 5601 Trusted Platform Module Library 5603 5604 Part 3: Commands 5605 5606 14.4.2 Command and Response 5607 Table 25 TPM2_ReadPublic Command 5608 Type 5609 5610 Name 5611 5612 Description 5613 5614 TPMI_ST_COMMAND_TAG 5615 5616 tag 5617 5618 UINT32 5619 5620 commandSize 5621 5622 TPM_CC 5623 5624 commandCode 5625 5626 TPM_CC_ReadPublic 5627 5628 TPMI_DH_OBJECT 5629 5630 objectHandle 5631 5632 TPM handle of an object 5633 Auth Index: None 5634 5635 Table 26 TPM2_ReadPublic Response 5636 Type 5637 5638 Name 5639 5640 Description 5641 5642 TPM_ST 5643 5644 tag 5645 5646 see clause 8 5647 5648 UINT32 5649 5650 responseSize 5651 5652 TPM_RC 5653 5654 responseCode 5655 5656 TPM2B_PUBLIC 5657 5658 outPublic 5659 5660 structure containing the public area of an object 5661 5662 TPM2B_NAME 5663 5664 name 5665 5666 name of the object 5667 5668 TPM2B_NAME 5669 5670 qualifiedName 5671 5672 the Qualified Name of the object 5673 5674 Family 2.0 5675 Level 00 Revision 00.99 5676 5677 Published 5678 Copyright TCG 2006-2013 5679 5680 Page 61 5681 October 31, 2013 5682 5683 Part 3: Commands 5685 5686 Trusted Platform Module Library 5687 5688 14.4.3 Detailed Actions 5689 1 5690 2 5691 5692 #include "InternalRoutines.h" 5693 #include "ReadPublic_fp.h" 5694 Error Returns 5695 TPM_RC_SEQUENCE 5696 5697 3 5698 4 5699 5 5700 6 5701 7 5702 8 5703 9 5704 10 5705 11 5706 12 5707 13 5708 14 5709 15 5710 16 5711 17 5712 18 5713 19 5714 20 5715 21 5716 22 5717 23 5718 24 5719 25 5720 26 5721 27 5722 28 5723 29 5724 30 5725 31 5726 32 5727 33 5728 34 5729 35 5730 36 5731 5732 Meaning 5733 can not read the public area of a sequence object 5734 5735 TPM_RC 5736 TPM2_ReadPublic( 5737 ReadPublic_In 5738 ReadPublic_Out 5739 5740 *in, 5741 *out 5742 5743 // IN: input parameter list 5744 // OUT: output parameter list 5745 5746 OBJECT 5747 5748 *object; 5749 5750 ) 5751 { 5752 // Input Validation 5753 // Get loaded object pointer 5754 object = ObjectGet(in->objectHandle); 5755 // Can not read public area of a sequence object 5756 if(ObjectIsSequence(object)) 5757 return TPM_RC_SEQUENCE; 5758 // Command Output 5759 // Compute size of public area in canonical form 5760 out->outPublic.t.size = TPMT_PUBLIC_Marshal(&object->publicArea, NULL, NULL); 5761 // Copy public area to output 5762 out->outPublic.t.publicArea = object->publicArea; 5763 // Copy name to output 5764 out->name.t.size = ObjectGetName(in->objectHandle, &out->name.t.name); 5765 // Copy qualified name to output 5766 ObjectGetQualifiedName(in->objectHandle, &out->qualifiedName); 5767 return TPM_RC_SUCCESS; 5768 } 5769 5770 Page 62 5771 October 31, 2013 5772 5773 Published 5774 Copyright TCG 2006-2013 5775 5776 Family 2.0 5777 Level 00 Revision 00.99 5778 5779 Trusted Platform Module Library 5781 5782 14.5 5783 5784 Part 3: Commands 5785 5786 TPM2_ActivateCredential 5787 5788 14.5.1 General Description 5789 This command enables the association of a credential with an object in a way that ensures that the TPM 5790 has validated the parameters of the credentialed object. 5791 If both the public and private portions of activateHandle and keyHandle are not loaded, then the TPM 5792 shall return TPM_RC_AUTH_UNAVAILABLE. 5793 If keyHandle is not a Storage Key, then the TPM shall return TPM_RC_TYPE. 5794 Authorization for activateHandle requires the ADMIN role. 5795 The key associated with keyHandle is used to recover a seed from secret, which is the encrypted seed. 5796 The Name of the object associated with activateHandle and the recovered seed are used in a KDF to 5797 recover the symmetric key. The recovered seed (but not the Name) is used is used in a KDF to recover 5798 the HMAC key. 5799 The HMAC is used to validate that the credentialBlob is associated with activateHandle and that the data 5800 in credentialBlob has not been modified. The linkage to the object associated with activateHandle is 5801 achieved by including the Name in the HMAC calculation. 5802 If the integrity checks succeed, credentialBlob is decrypted and returned as certInfo. 5803 5804 Family 2.0 5805 Level 00 Revision 00.99 5806 5807 Published 5808 Copyright TCG 2006-2013 5809 5810 Page 63 5811 October 31, 2013 5812 5813 Part 3: Commands 5815 5816 Trusted Platform Module Library 5817 5818 14.5.2 Command and Response 5819 Table 27 TPM2_ActivateCredential Command 5820 Type 5821 5822 Name 5823 5824 TPMI_ST_COMMAND_TAG 5825 5826 tag 5827 5828 UINT32 5829 5830 commandSize 5831 5832 TPM_CC 5833 5834 commandCode 5835 5836 TPMI_DH_OBJECT 5837 5838 Description 5839 5840 TPM_CC_ActivateCredential 5841 5842 @activateHandle 5843 5844 handle of the object associated with certificate in 5845 credentialBlob 5846 Auth Index: 1 5847 Auth Role: ADMIN 5848 5849 TPMI_DH_OBJECT 5850 5851 @keyHandle 5852 5853 loaded key used to decrypt the TPMS_SENSITIVE in 5854 credentialBlob 5855 Auth Index: 2 5856 Auth Role: USER 5857 5858 TPM2B_ID_OBJECT 5859 5860 credentialBlob 5861 5862 the credential 5863 5864 TPM2B_ENCRYPTED_SECRET 5865 5866 secret 5867 5868 keyHandle algorithm-dependent encrypted seed that 5869 protects credentialBlob 5870 5871 Table 28 TPM2_ActivateCredential Response 5872 Type 5873 5874 Name 5875 5876 Description 5877 5878 TPM_ST 5879 5880 tag 5881 5882 see clause 8 5883 5884 UINT32 5885 5886 responseSize 5887 5888 TPM_RC 5889 5890 responseCode 5891 5892 TPM2B_DIGEST 5893 5894 certInfo 5895 5896 Page 64 5897 October 31, 2013 5898 5899 the decrypted certificate information 5900 the data should be no larger than the size of the digest 5901 of the nameAlg associated with keyHandle 5902 5903 Published 5904 Copyright TCG 2006-2013 5905 5906 Family 2.0 5907 Level 00 Revision 00.99 5908 5909 Trusted Platform Module Library 5911 5912 Part 3: Commands 5913 5914 14.5.3 Detailed Actions 5915 1 5916 2 5917 3 5918 5919 #include "InternalRoutines.h" 5920 #include "ActivateCredential_fp.h" 5921 #include "Object_spt_fp.h" 5922 Error Returns 5923 TPM_RC_ATTRIBUTES 5924 5925 keyHandle does not reference a decryption key 5926 5927 TPM_RC_ECC_POINT 5928 5929 secret is invalid (when keyHandle is an ECC key) 5930 5931 TPM_RC_INSUFFICIENT 5932 5933 secret is invalid (when keyHandle is an ECC key) 5934 5935 TPM_RC_INTEGRITY 5936 5937 credentialBlob fails integrity test 5938 5939 TPM_RC_NO_RESULT 5940 5941 secret is invalid (when keyHandle is an ECC key) 5942 5943 TPM_RC_SIZE 5944 5945 secret size is invalid or the credentialBlob does not unmarshal 5946 correctly 5947 5948 TPM_RC_TYPE 5949 5950 keyHandle does not reference an asymmetric key. 5951 5952 TPM_RC_VALUE 5953 4 5954 5 5955 6 5956 7 5957 8 5958 9 5959 10 5960 11 5961 12 5962 13 5963 14 5964 15 5965 16 5966 17 5967 18 5968 19 5969 20 5970 21 5971 22 5972 23 5973 24 5974 25 5975 26 5976 27 5977 28 5978 29 5979 30 5980 31 5981 32 5982 33 5983 34 5984 35 5985 36 5986 37 5987 38 5988 39 5989 40 5990 41 5991 5992 Meaning 5993 5994 secret is invalid (when keyHandle is an RSA key) 5995 5996 TPM_RC 5997 TPM2_ActivateCredential( 5998 ActivateCredential_In 5999 ActivateCredential_Out 6000 6001 *in, 6002 *out 6003 6004 // IN: input parameter list 6005 // OUT: output parameter list 6006 6007 TPM_RC 6008 OBJECT 6009 OBJECT 6010 // credential 6011 TPM2B_DATA 6012 6013 result = TPM_RC_SUCCESS; 6014 *object; 6015 // decrypt key 6016 *activateObject;// key associated with 6017 6018 ) 6019 { 6020 6021 data; 6022 6023 // credential data 6024 6025 // Input Validation 6026 // Get decrypt key pointer 6027 object = ObjectGet(in->keyHandle); 6028 // Get certificated object pointer 6029 activateObject = ObjectGet(in->activateHandle); 6030 // input decrypt key must be an asymmetric, restricted decryption key 6031 if( 6032 !CryptIsAsymAlgorithm(object->publicArea.type) 6033 || object->publicArea.objectAttributes.decrypt == CLEAR 6034 || object->publicArea.objectAttributes.restricted == CLEAR) 6035 return TPM_RC_TYPE + RC_ActivateCredential_keyHandle; 6036 // Command output 6037 // Decrypt input credential data via asymmetric decryption. A 6038 // TPM_RC_VALUE, TPM_RC_KEY or unmarshal errors may be returned at this 6039 // point 6040 result = CryptSecretDecrypt(in->keyHandle, NULL, 6041 "IDENTITY", &in->secret, &data); 6042 if(result != TPM_RC_SUCCESS) 6043 { 6044 if(result == TPM_RC_KEY) 6045 return TPM_RC_FAILURE; 6046 6047 Family 2.0 6048 Level 00 Revision 00.99 6049 6050 Published 6051 Copyright TCG 2006-2013 6052 6053 Page 65 6054 October 31, 2013 6055 6056 Part 3: Commands 6058 42 6059 43 6060 44 6061 45 6062 46 6063 47 6064 48 6065 49 6066 50 6067 51 6068 52 6069 53 6070 54 6071 55 6072 56 6073 6074 Trusted Platform Module Library 6075 6076 return RcSafeAddToResult(result, RC_ActivateCredential_secret); 6077 } 6078 // Retrieve secret data. A TPM_RC_INTEGRITY error or unmarshal 6079 // errors may be returned at this point 6080 result = CredentialToSecret(&in->credentialBlob, 6081 &activateObject->name, 6082 (TPM2B_SEED *) &data, 6083 in->keyHandle, 6084 &out->certInfo); 6085 if(result != TPM_RC_SUCCESS) 6086 return RcSafeAddToResult(result,RC_ActivateCredential_credentialBlob); 6087 return TPM_RC_SUCCESS; 6088 } 6089 6090 Page 66 6091 October 31, 2013 6092 6093 Published 6094 Copyright TCG 2006-2013 6095 6096 Family 2.0 6097 Level 00 Revision 00.99 6098 6099 Trusted Platform Module Library 6101 6102 14.6 6103 6104 Part 3: Commands 6105 6106 TPM2_MakeCredential 6107 6108 14.6.1 General Description 6109 This command allows the TPM to perform the actions required of a Certificate Authority (CA) in creating a 6110 TPM2B_ID_OBJECT containing an activation credential. 6111 The TPM will produce a TPM_ID_OBJECT according to the methods in Credential Protection in Part 1. 6112 The loaded public area referenced by handle is required to be the public area of a Storage key, 6113 otherwise, the credential cannot be properly sealed. 6114 This command does not use any TPM secrets nor does it require authorization. It is a convenience 6115 function, using the TPM to perform cryptographic calculations that could be done externally. 6116 6117 Family 2.0 6118 Level 00 Revision 00.99 6119 6120 Published 6121 Copyright TCG 2006-2013 6122 6123 Page 67 6124 October 31, 2013 6125 6126 Part 3: Commands 6128 6129 Trusted Platform Module Library 6130 6131 14.6.2 Command and Response 6132 Table 29 TPM2_MakeCredential Command 6133 Type 6134 6135 Name 6136 6137 Description 6138 6139 TPMI_ST_COMMAND_TAG 6140 6141 tag 6142 6143 UINT32 6144 6145 commandSize 6146 6147 TPM_CC 6148 6149 commandCode 6150 6151 TPM_CC_MakeCredential 6152 6153 TPMI_DH_OBJECT 6154 6155 handle 6156 6157 loaded public area, used to encrypt the sensitive area 6158 containing the credential key 6159 Auth Index: None 6160 6161 TPM2B_DIGEST 6162 6163 credential 6164 6165 the credential information 6166 6167 TPM2B_NAME 6168 6169 objectName 6170 6171 Name of the object to which the credential applies 6172 6173 Table 30 TPM2_MakeCredential Response 6174 Type 6175 6176 Name 6177 6178 Description 6179 6180 TPM_ST 6181 6182 tag 6183 6184 see clause 8 6185 6186 UINT32 6187 6188 responseSize 6189 6190 TPM_RC 6191 6192 responseCode 6193 6194 TPM2B_ID_OBJECT 6195 6196 credentialBlob 6197 6198 TPM2B_ENCRYPTED_SECRET secret 6199 6200 Page 68 6201 October 31, 2013 6202 6203 the credential 6204 handle algorithm-dependent data that wraps the key 6205 that encrypts credentialBlob 6206 6207 Published 6208 Copyright TCG 2006-2013 6209 6210 Family 2.0 6211 Level 00 Revision 00.99 6212 6213 Trusted Platform Module Library 6215 6216 Part 3: Commands 6217 6218 14.6.3 Detailed Actions 6219 1 6220 2 6221 3 6222 6223 #include "InternalRoutines.h" 6224 #include "MakeCredential_fp.h" 6225 #include "Object_spt_fp.h" 6226 Error Returns 6227 TPM_RC_KEY 6228 6229 handle referenced an ECC key that has a unique field that is not a 6230 point on the curve of the key 6231 6232 TPM_RC_SIZE 6233 6234 credential is larger than the digest size of Name algorithm of handle 6235 6236 TPM_RC_TYPE 6237 4 6238 5 6239 6 6240 7 6241 8 6242 9 6243 10 6244 11 6245 12 6246 13 6247 14 6248 15 6249 16 6250 17 6251 18 6252 19 6253 20 6254 21 6255 22 6256 23 6257 24 6258 25 6259 26 6260 27 6261 28 6262 29 6263 30 6264 31 6265 32 6266 33 6267 34 6268 35 6269 36 6270 37 6271 38 6272 39 6273 40 6274 41 6275 42 6276 43 6277 44 6278 45 6279 46 6280 47 6281 6282 Meaning 6283 6284 handle does not reference an asymmetric decryption key 6285 6286 TPM_RC 6287 TPM2_MakeCredential( 6288 MakeCredential_In 6289 MakeCredential_Out 6290 6291 *in, 6292 *out 6293 6294 // IN: input parameter list 6295 // OUT: output parameter list 6296 6297 TPM_RC 6298 6299 result = TPM_RC_SUCCESS; 6300 6301 OBJECT 6302 TPM2B_DATA 6303 6304 *object; 6305 data; 6306 6307 ) 6308 { 6309 6310 // Input Validation 6311 // Get object pointer 6312 object = ObjectGet(in->handle); 6313 // input key must be an asymmetric, restricted decryption key 6314 // NOTE: Needs to be restricted to have a symmetric value. 6315 if( 6316 !CryptIsAsymAlgorithm(object->publicArea.type) 6317 || object->publicArea.objectAttributes.decrypt == CLEAR 6318 || object->publicArea.objectAttributes.restricted == CLEAR 6319 ) 6320 return TPM_RC_TYPE + RC_MakeCredential_handle; 6321 // The credential information may not be larger than the digest size used for 6322 // the Name of the key associated with handle. 6323 if(in->credential.t.size > CryptGetHashDigestSize(object->publicArea.nameAlg)) 6324 return TPM_RC_SIZE + RC_MakeCredential_credential; 6325 // Command Output 6326 // Make encrypt key and its associated secret structure. 6327 // Even though CrypeSecretEncrypt() may return 6328 out->secret.t.size = sizeof(out->secret.t.secret); 6329 result = CryptSecretEncrypt(in->handle, "IDENTITY", &data, &out->secret); 6330 if(result != TPM_RC_SUCCESS) 6331 return result; 6332 // Prepare output credential data from secret 6333 SecretToCredential(&in->credential, &in->objectName, (TPM2B_SEED *) &data, 6334 in->handle, &out->credentialBlob); 6335 return TPM_RC_SUCCESS; 6336 } 6337 6338 Family 2.0 6339 Level 00 Revision 00.99 6340 6341 Published 6342 Copyright TCG 2006-2013 6343 6344 Page 69 6345 October 31, 2013 6346 6347 Part 3: Commands 6349 6350 14.7 6351 6352 Trusted Platform Module Library 6353 6354 TPM2_Unseal 6355 6356 14.7.1 General Description 6357 This command returns the data in a loaded Sealed Data Object. 6358 NOTE 6359 6360 A random, TPM-generated, Sealed Data Object may be created by the TPM with TPM2_Create() or 6361 TPM2_CreatePrimary() using the template for a Sealed Data Object. A Sealed Data Object is more 6362 likely to be created externally and imported (TPM2_Import()) so that the data is not created by the 6363 TPM. 6364 6365 The returned value may be encrypted using authorization session encryption. 6366 If either restricted, decrypt, or sign is SET in the attributes of itemHandle, then the TPM shall return 6367 TPM_RC_ATTRIBUTES. If the type of itemHandle is not TPM_ALG_KEYEDHASH, then the TPM shall 6368 return TPM_RC_TYPE. 6369 6370 Page 70 6371 October 31, 2013 6372 6373 Published 6374 Copyright TCG 2006-2013 6375 6376 Family 2.0 6377 Level 00 Revision 00.99 6378 6379 Trusted Platform Module Library 6381 6382 Part 3: Commands 6383 6384 14.7.2 Command and Response 6385 Table 31 TPM2_Unseal Command 6386 Type 6387 6388 Name 6389 6390 TPMI_ST_COMMAND_TAG 6391 6392 Tag 6393 6394 UINT32 6395 6396 commandSize 6397 6398 TPM_CC 6399 6400 commandCode 6401 6402 TPM_CC_Unseal 6403 6404 @itemHandle 6405 6406 handle of a loaded data object 6407 Auth Index: 1 6408 Auth Role: USER 6409 6410 TPMI_DH_OBJECT 6411 6412 Description 6413 6414 Table 32 TPM2_Unseal Response 6415 Type 6416 6417 Name 6418 6419 Description 6420 6421 TPM_ST 6422 6423 tag 6424 6425 see clause 8 6426 6427 UINT32 6428 6429 responseSize 6430 6431 TPM_RC 6432 6433 responseCode 6434 6435 TPM2B_SENSITIVE_DATA 6436 6437 outData 6438 6439 Family 2.0 6440 Level 00 Revision 00.99 6441 6442 unsealed data 6443 Size of outData is limited to be no more than 128 octets. 6444 6445 Published 6446 Copyright TCG 2006-2013 6447 6448 Page 71 6449 October 31, 2013 6450 6451 Part 3: Commands 6453 6454 Trusted Platform Module Library 6455 6456 14.7.3 Detailed Actions 6457 1 6458 2 6459 6460 #include "InternalRoutines.h" 6461 #include "Unseal_fp.h" 6462 Error Returns 6463 TPM_RC_ATTRIBUTES 6464 6465 itemHandle has wrong attributes 6466 6467 TPM_RC_TYPE 6468 3 6469 4 6470 5 6471 6 6472 7 6473 8 6474 9 6475 10 6476 11 6477 12 6478 13 6479 14 6480 15 6481 16 6482 17 6483 18 6484 19 6485 20 6486 21 6487 22 6488 23 6489 24 6490 25 6491 26 6492 27 6493 28 6494 6495 Meaning 6496 6497 itemHandle is not a KEYEDHASH data object 6498 6499 TPM_RC 6500 TPM2_Unseal(Unseal_In *in, Unseal_Out *out) 6501 { 6502 OBJECT 6503 6504 *object; 6505 6506 // Input Validation 6507 // Get pointer to loaded object 6508 object = ObjectGet(in->itemHandle); 6509 // Input handle must be a data object 6510 if(object->publicArea.type != TPM_ALG_KEYEDHASH) 6511 return TPM_RC_TYPE + RC_Unseal_itemHandle; 6512 if( 6513 object->publicArea.objectAttributes.decrypt == SET 6514 || object->publicArea.objectAttributes.sign == SET 6515 || object->publicArea.objectAttributes.restricted == SET) 6516 return TPM_RC_ATTRIBUTES + RC_Unseal_itemHandle; 6517 // Command Output 6518 // Copy data 6519 MemoryCopy2B(&out->outData.b, &object->sensitive.sensitive.bits.b, 6520 sizeof(out->outData.t.buffer)); 6521 return TPM_RC_SUCCESS; 6522 } 6523 6524 Page 72 6525 October 31, 2013 6526 6527 Published 6528 Copyright TCG 2006-2013 6529 6530 Family 2.0 6531 Level 00 Revision 00.99 6532 6533 Trusted Platform Module Library 6535 6536 14.8 6537 6538 Part 3: Commands 6539 6540 TPM2_ObjectChangeAuth 6541 6542 14.8.1 General Description 6543 This command is used to change the authorization secret for a TPM-resident object. 6544 If successful, a new private area for the TPM-resident object associated with objectHandle is returned, 6545 which includes the new authorization value. 6546 This command does not change the authorization of the TPM-resident object on which it operates. 6547 Therefore, the old authValue (of the TPM-resident object) is used when generating the response HMAC 6548 key if required.. 6549 NOTE 1 6550 6551 The returned outPrivate will need to be loaded before the new authorization will apply. 6552 6553 NOTE 2 6554 6555 The TPM-resident object may be persistent and changing the authorization value of the persistent 6556 object could prevent other users from accessing the object. This is why this command does not 6557 change the TPM-resident object. 6558 6559 EXAMPLE 6560 6561 If 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 6562 persistent key would deny access to other users. 6563 6564 This command may not be used to change the authorization value for an NV Index or a Primary Object. 6565 NOTE 3 6566 6567 If an NV Index is to have a new authorization, it is done with TPM2_NV_ChangeAuth(). 6568 6569 NOTE 4 6570 6571 If a Primary Object is to have a new authorization, it needs to be recreated (TPM2_CreatePrimary()). 6572 6573 Family 2.0 6574 Level 00 Revision 00.99 6575 6576 Published 6577 Copyright TCG 2006-2013 6578 6579 Page 73 6580 October 31, 2013 6581 6582 Part 3: Commands 6584 6585 Trusted Platform Module Library 6586 6587 14.8.2 Command and Response 6588 Table 33 TPM2_ObjectChangeAuth Command 6589 Type 6590 6591 Name 6592 6593 Description 6594 6595 TPMI_ST_COMMAND_TAG 6596 6597 tag 6598 6599 UINT32 6600 6601 commandSize 6602 6603 TPM_CC 6604 6605 commandCode 6606 6607 TPM_CC_ObjectChangeAuth 6608 6609 TPMI_DH_OBJECT 6610 6611 @objectHandle 6612 6613 handle of the object 6614 Auth Index: 1 6615 Auth Role: ADMIN 6616 6617 TPMI_DH_OBJECT 6618 6619 parentHandle 6620 6621 handle of the parent 6622 Auth Index: None 6623 6624 TPM2B_AUTH 6625 6626 newAuth 6627 6628 new authorization value 6629 6630 Table 34 TPM2_ObjectChangeAuth Response 6631 Type 6632 6633 Name 6634 6635 Description 6636 6637 TPM_ST 6638 6639 tag 6640 6641 see clause 8 6642 6643 UINT32 6644 6645 responseSize 6646 6647 TPM_RC 6648 6649 responseCode 6650 6651 TPM2B_PRIVATE 6652 6653 outPrivate 6654 6655 Page 74 6656 October 31, 2013 6657 6658 private area containing the new authorization value 6659 6660 Published 6661 Copyright TCG 2006-2013 6662 6663 Family 2.0 6664 Level 00 Revision 00.99 6665 6666 Trusted Platform Module Library 6668 6669 Part 3: Commands 6670 6671 14.8.3 Detailed Actions 6672 1 6673 2 6674 3 6675 6676 #include "InternalRoutines.h" 6677 #include "ObjectChangeAuth_fp.h" 6678 #include "Object_spt_fp.h" 6679 Error Returns 6680 TPM_RC_SIZE 6681 6682 newAuth is larger than the size of the digest of the Name algorithm of 6683 objectHandle 6684 6685 TPM_RC_TYPE 6686 6687 4 6688 5 6689 6 6690 7 6691 8 6692 9 6693 10 6694 11 6695 12 6696 13 6697 14 6698 15 6699 16 6700 17 6701 18 6702 19 6703 20 6704 21 6705 22 6706 23 6707 24 6708 25 6709 26 6710 27 6711 28 6712 29 6713 30 6714 31 6715 32 6716 33 6717 34 6718 35 6719 36 6720 37 6721 38 6722 39 6723 40 6724 41 6725 42 6726 43 6727 44 6728 45 6729 46 6730 47 6731 48 6732 49 6733 50 6734 51 6735 6736 Meaning 6737 6738 the key referenced by parentHandle is not the parent of the object 6739 referenced by objectHandle; or objectHandle is a sequence object. 6740 6741 TPM_RC 6742 TPM2_ObjectChangeAuth( 6743 ObjectChangeAuth_In 6744 ObjectChangeAuth_Out 6745 6746 *in, 6747 *out 6748 6749 // IN: input parameter list 6750 // OUT: output parameter list 6751 6752 ) 6753 { 6754 TPMT_SENSITIVE 6755 OBJECT 6756 TPM2B_NAME 6757 TPM2B_NAME 6758 6759 sensitive; 6760 *object; 6761 objectQN, QNCompare; 6762 parentQN; 6763 6764 // Input Validation 6765 // Get object pointer 6766 object = ObjectGet(in->objectHandle); 6767 // Can not change auth on sequence object 6768 if(ObjectIsSequence(object)) 6769 return TPM_RC_TYPE + RC_ObjectChangeAuth_objectHandle; 6770 // Make sure that the auth value is consistent with the nameAlg 6771 if( MemoryRemoveTrailingZeros(&in->newAuth) 6772 > CryptGetHashDigestSize(object->publicArea.nameAlg)) 6773 return TPM_RC_SIZE + RC_ObjectChangeAuth_newAuth; 6774 // Check parent for object 6775 // parent handle must be the parent of object handle. In this 6776 // implementation we verify this by checking the QN of object. Other 6777 // implementation may choose different method to verify this attribute. 6778 ObjectGetQualifiedName(in->parentHandle, &parentQN); 6779 ObjectComputeQualifiedName(&parentQN, object->publicArea.nameAlg, 6780 &object->name, &QNCompare); 6781 ObjectGetQualifiedName(in->objectHandle, &objectQN); 6782 if(!Memory2BEqual(&objectQN.b, &QNCompare.b)) 6783 return TPM_RC_TYPE + RC_ObjectChangeAuth_parentHandle; 6784 // Command Output 6785 // Copy internal sensitive area 6786 sensitive = object->sensitive; 6787 // Copy authValue 6788 sensitive.authValue = in->newAuth; 6789 // Prepare output private data from sensitive 6790 SensitiveToPrivate(&sensitive, &object->name, in->parentHandle, 6791 6792 Family 2.0 6793 Level 00 Revision 00.99 6794 6795 Published 6796 Copyright TCG 2006-2013 6797 6798 Page 75 6799 October 31, 2013 6800 6801 Part 3: Commands 6803 52 6804 53 6805 54 6806 55 6807 56 6808 6809 Trusted Platform Module Library 6810 object->publicArea.nameAlg, 6811 &out->outPrivate); 6812 6813 return TPM_RC_SUCCESS; 6814 } 6815 6816 Page 76 6817 October 31, 2013 6818 6819 Published 6820 Copyright TCG 2006-2013 6821 6822 Family 2.0 6823 Level 00 Revision 00.99 6824 6825 Trusted Platform Module Library 6827 6828 15 6829 6830 Part 3: Commands 6831 6832 Duplication Commands 6833 6834 15.1 6835 6836 TPM2_Duplicate 6837 6838 15.1.1 General Description 6839 This command duplicates a loaded object so that it may be used in a different hierarchy. The new parent 6840 key for the duplicate may be on the same or different TPM or TPM_RH_NULL. Only the public area of 6841 newParentHandle is required to be loaded. 6842 NOTE 1 6843 6844 Since the new parent may only be extant on a different TPM, it is likely that the new parents 6845 sensitive area could not be loaded in the TPM from which objectHandle is being duplicated. 6846 6847 If encryptedDuplication is SET in the object being duplicated, then the TPM shall return 6848 TPM_RC_SYMMETRIC if symmetricAlg is TPM_RH_NULL or TPM_RC_HIERARCHY if 6849 newParentHandle is TPM_RH_NULL. 6850 The authorization for this command shall be with a policy session. 6851 If fixedParent of objectHandleattributes is SET, the TPM shall return TPM_RC_ATTRIBUTES. If 6852 objectHandlenameAlg is TPM_ALG_NULL, the TPM shall return TPM_RC_TYPE. 6853 The policySessioncommandCode parameter in the policy session is required to be TPM_CC_Duplicate 6854 to indicate that authorization for duplication has been provided. This indicates that the policy that is being 6855 used is a policy that is for duplication, and not a policy that would approve another use. That is, authority 6856 to use an object does not grant authority to duplicate the object. 6857 The policy is likely to include cpHash in order to restrict where duplication can occur. 6858 If 6859 TPM2_PolicyCpHash() has been executed as part of the policy, the policySessioncpHash is compared 6860 to the cpHash of the command. 6861 If TPM2_PolicyDuplicationSelect() has 6862 policySessionnameHash is compared to 6863 6864 been 6865 6866 executed 6867 6868 as 6869 6870 part 6871 6872 of 6873 6874 the 6875 6876 policy, 6877 6878 HpolicyAlg(objectHandleName || newParentHandleName) 6879 6880 the 6881 (2) 6882 6883 If the compared hashes are not the same, then the TPM shall return TPM_RC_POLICY_FAIL. 6884 NOTE 2 6885 6886 It is allowed that policySesionnameHash and policySessioncpHash share the same memory 6887 space. 6888 6889 NOTE 3 6890 6891 A duplication policy is not required to have either TPM2_PolicyDuplicationSelect() or 6892 TPM2_PolicyCpHash() as part of the policy. If neither is present, then the duplication policy may be 6893 satisfied with a policy that only contains TPM2_PolicyCommaneCode( code = TPM_CC_Duplicate). 6894 6895 The TPM shall follow the process of encryption defined in the Duplication subclause of Protected 6896 Storage Hierarchy in Part 1 of this specification. 6897 6898 Family 2.0 6899 Level 00 Revision 00.99 6900 6901 Published 6902 Copyright TCG 2006-2013 6903 6904 Page 77 6905 October 31, 2013 6906 6907 Part 3: Commands 6909 6910 Trusted Platform Module Library 6911 6912 15.1.2 Command and Response 6913 Table 35 TPM2_Duplicate Command 6914 Type 6915 6916 Name 6917 6918 Description 6919 6920 TPMI_ST_COMMAND_TAG 6921 6922 tag 6923 6924 UINT32 6925 6926 commandSize 6927 6928 TPM_CC 6929 6930 commandCode 6931 6932 TPM_CC_Duplicate 6933 6934 TPMI_DH_OBJECT 6935 6936 @objectHandle 6937 6938 loaded object to duplicate 6939 Auth Index: 1 6940 Auth Role: DUP 6941 6942 TPMI_DH_OBJECT+ 6943 6944 newParentHandle 6945 6946 shall reference the public area of an asymmetric key 6947 Auth Index: None 6948 6949 TPM2B_DATA 6950 6951 encryptionKeyIn 6952 6953 optional symmetric encryption key 6954 The size for this key is set to zero when the TPM is to 6955 generate the key. This parameter may be encrypted. 6956 6957 TPMT_SYM_DEF_OBJECT+ 6958 6959 symmetricAlg 6960 6961 definition for the symmetric algorithm to be used for the 6962 inner wrapper 6963 may be TPM_ALG_NULL if no inner wrapper is applied 6964 6965 Table 36 TPM2_Duplicate Response 6966 Type 6967 6968 Name 6969 6970 Description 6971 6972 TPM_ST 6973 6974 tag 6975 6976 see clause 8 6977 6978 UINT32 6979 6980 responseSize 6981 6982 TPM_RC 6983 6984 responseCode 6985 6986 TPM2B_DATA 6987 6988 encryptionKeyOut 6989 6990 If the caller provided an encryption key or if 6991 symmetricAlg was TPM_ALG_NULL, then this will be 6992 the Empty Buffer; otherwise, it shall contain the TPMgenerated, symmetric encryption key for the inner 6993 wrapper. 6994 6995 TPM2B_PRIVATE 6996 6997 duplicate 6998 6999 private area that may be encrypted by encryptionKeyIn; 7000 and may be doubly encrypted 7001 7002 TPM2B_ENCRYPTED_SECRET outSymSeed 7003 7004 Page 78 7005 October 31, 2013 7006 7007 seed protected by the asymmetric algorithms of new 7008 parent (NP) 7009 7010 Published 7011 Copyright TCG 2006-2013 7012 7013 Family 2.0 7014 Level 00 Revision 00.99 7015 7016 Trusted Platform Module Library 7018 7019 Part 3: Commands 7020 7021 15.1.3 Detailed Actions 7022 1 7023 2 7024 3 7025 7026 #include "InternalRoutines.h" 7027 #include "Duplicate_fp.h" 7028 #include "Object_spt_fp.h" 7029 Error Returns 7030 TPM_RC_ATTRIBUTES 7031 7032 key to duplicate has fixedParent SET 7033 7034 TPM_RC_HIERARCHY 7035 7036 encryptedDuplication is SET and newParentHandle specifies Null 7037 Hierarchy 7038 7039 TPM_RC_KEY 7040 7041 newParentHandle references invalid ECC key (public point not on the 7042 curve) 7043 7044 TPM_RC_SIZE 7045 7046 input encryption key size does not match the size specified in 7047 symmetric algorithm 7048 7049 TPM_RC_SYMMETRIC 7050 7051 encryptedDuplication is SET but no symmetric algorithm is provided 7052 7053 TPM_RC_TYPE 7054 7055 4 7056 5 7057 6 7058 7 7059 8 7060 9 7061 10 7062 11 7063 12 7064 13 7065 14 7066 15 7067 16 7068 17 7069 18 7070 19 7071 20 7072 21 7073 22 7074 23 7075 24 7076 25 7077 26 7078 27 7079 28 7080 29 7081 30 7082 31 7083 32 7084 33 7085 34 7086 35 7087 36 7088 37 7089 38 7090 39 7091 40 7092 41 7093 42 7094 7095 Meaning 7096 7097 newParentHandle is neither a storage key nor TPM_RH_NULL; or 7098 the object has a NULL nameAlg 7099 7100 TPM_RC 7101 TPM2_Duplicate( 7102 Duplicate_In 7103 Duplicate_Out 7104 7105 *in, 7106 *out 7107 7108 // IN: input parameter list 7109 // OUT: output parameter list 7110 7111 ) 7112 { 7113 TPM_RC 7114 TPMT_SENSITIVE 7115 7116 result = TPM_RC_SUCCESS; 7117 sensitive; 7118 7119 UINT16 7120 7121 innerKeySize = 0; // encrypt key size for inner wrap 7122 7123 OBJECT 7124 TPM2B_DATA 7125 7126 *object; 7127 data; 7128 7129 // Input Validation 7130 // Get duplicate object pointer 7131 object = ObjectGet(in->objectHandle); 7132 // duplicate key must have fixParent bit CLEAR. 7133 if(object->publicArea.objectAttributes.fixedParent == SET) 7134 return TPM_RC_ATTRIBUTES + RC_Duplicate_objectHandle; 7135 // Do not duplicate object with NULL nameAlg 7136 if(object->publicArea.nameAlg == TPM_ALG_NULL) 7137 return TPM_RC_TYPE + RC_Duplicate_objectHandle; 7138 // new parent key must be a storage object or TPM_RH_NULL 7139 if(in->newParentHandle != TPM_RH_NULL 7140 && !ObjectIsStorage(in->newParentHandle)) 7141 return TPM_RC_TYPE + RC_Duplicate_newParentHandle; 7142 // If the duplicates object has encryptedDuplication SET, then there must be 7143 // an inner wrapper and the new parent may not be TPM_RH_NULL 7144 if(object->publicArea.objectAttributes.encryptedDuplication == SET) 7145 { 7146 if(in->symmetricAlg.algorithm == TPM_ALG_NULL) 7147 return TPM_RC_SYMMETRIC + RC_Duplicate_symmetricAlg; 7148 if(in->newParentHandle == TPM_RH_NULL) 7149 7150 Family 2.0 7151 Level 00 Revision 00.99 7152 7153 Published 7154 Copyright TCG 2006-2013 7155 7156 Page 79 7157 October 31, 2013 7158 7159 Part 3: Commands 7161 43 7162 44 7163 45 7164 46 7165 47 7166 48 7167 49 7168 50 7169 51 7170 52 7171 53 7172 54 7173 55 7174 56 7175 57 7176 58 7177 59 7178 60 7179 61 7180 62 7181 63 7182 64 7183 65 7184 66 7185 67 7186 68 7187 69 7188 70 7189 71 7190 72 7191 73 7192 74 7193 75 7194 76 7195 77 7196 78 7197 79 7198 80 7199 81 7200 82 7201 83 7202 84 7203 85 7204 86 7205 87 7206 88 7207 89 7208 90 7209 91 7210 92 7211 93 7212 94 7213 95 7214 96 7215 7216 Trusted Platform Module Library 7217 7218 return TPM_RC_HIERARCHY + RC_Duplicate_newParentHandle; 7219 } 7220 if(in->symmetricAlg.algorithm == TPM_ALG_NULL) 7221 { 7222 // if algorithm is TPM_ALG_NULL, input key size must be 0 7223 if(in->encryptionKeyIn.t.size != 0) 7224 return TPM_RC_SIZE + RC_Duplicate_encryptionKeyIn; 7225 } 7226 else 7227 { 7228 // Get inner wrap key size 7229 innerKeySize = in->symmetricAlg.keyBits.sym; 7230 // If provided the input symmetric key must match the size of the algorithm 7231 if(in->encryptionKeyIn.t.size != 0 7232 && in->encryptionKeyIn.t.size != (innerKeySize + 7) / 8) 7233 return TPM_RC_SIZE + RC_Duplicate_encryptionKeyIn; 7234 } 7235 // Command Output 7236 if(in->newParentHandle != TPM_RH_NULL) 7237 { 7238 // Make encrypt key and its associated secret structure. A TPM_RC_KEY 7239 // error may be returned at this point 7240 out->outSymSeed.t.size = sizeof(out->outSymSeed.t.secret); 7241 result = CryptSecretEncrypt(in->newParentHandle, 7242 "DUPLICATE", &data, &out->outSymSeed); 7243 pAssert(result != TPM_RC_VALUE); 7244 if(result != TPM_RC_SUCCESS) 7245 return result; 7246 } 7247 else 7248 { 7249 // Do not apply outer wrapper 7250 data.t.size = 0; 7251 out->outSymSeed.t.size = 0; 7252 } 7253 // Copy sensitive area 7254 sensitive = object->sensitive; 7255 // Prepare output private data from sensitive 7256 SensitiveToDuplicate(&sensitive, &object->name, in->newParentHandle, 7257 object->publicArea.nameAlg, (TPM2B_SEED *) &data, 7258 &in->symmetricAlg, &in->encryptionKeyIn, 7259 &out->duplicate); 7260 out->encryptionKeyOut = in->encryptionKeyIn; 7261 return TPM_RC_SUCCESS; 7262 } 7263 7264 Page 80 7265 October 31, 2013 7266 7267 Published 7268 Copyright TCG 2006-2013 7269 7270 Family 2.0 7271 Level 00 Revision 00.99 7272 7273 Trusted Platform Module Library 7275 7276 15.2 7277 7278 Part 3: Commands 7279 7280 TPM2_Rewrap 7281 7282 15.2.1 General Description 7283 This command allows the TPM to serve in the role as a Duplication Authority. If proper authorization for 7284 use of the oldParent is provided, then an HMAC key and a symmetric key are recovered from inSymSeed 7285 and used to integrity check and decrypt inDuplicate. A new protection seed value is generated according 7286 to the methods appropriate for newParent and the blob is re-encrypted and a new integrity value is 7287 computed. The re-encrypted blob is returned in outDuplicate and the symmetric key returned in 7288 outSymKey. 7289 In the rewrap process, L is DUPLICATE (see Terms and Definitions in Part 1). 7290 If inSymSeed has a zero length, then oldParent is required to be TPM_RH_NULL and no decryption of 7291 inDuplicate takes place. 7292 If newParent is TPM_RH_NULL, then no encryption is performed on outDuplicate. outSymSeed will have 7293 a zero length. See Part 2 encryptedDuplication. 7294 7295 Family 2.0 7296 Level 00 Revision 00.99 7297 7298 Published 7299 Copyright TCG 2006-2013 7300 7301 Page 81 7302 October 31, 2013 7303 7304 Part 3: Commands 7306 7307 Trusted Platform Module Library 7308 7309 15.2.2 Command and Response 7310 Table 37 TPM2_Rewrap Command 7311 Type 7312 7313 Name 7314 7315 TPMI_ST_COMMAND_TAG 7316 7317 tag 7318 7319 UINT32 7320 7321 commandSize 7322 7323 TPM_CC 7324 7325 commandCode 7326 7327 TPM_CC_Rewrap 7328 7329 TPMI_DH_OBJECT+ 7330 7331 @oldParent 7332 7333 parent of object 7334 Auth Index: 1 7335 Auth Role: User 7336 7337 TPMI_DH_OBJECT+ 7338 7339 newParent 7340 7341 new parent of the object 7342 Auth Index: None 7343 7344 TPM2B_PRIVATE 7345 7346 inDuplicate 7347 7348 an object encrypted using symmetric key derived from 7349 inSymSeed 7350 7351 TPM2B_NAME 7352 7353 name 7354 7355 the Name of the object being rewrapped 7356 7357 TPM2B_ENCRYPTED_SECRET inSymSeed 7358 7359 Description 7360 7361 seed for symmetric key 7362 needs oldParent private key to recover the seed and 7363 generate the symmetric key 7364 7365 Table 38 TPM2_Rewrap Response 7366 Type 7367 7368 Name 7369 7370 Description 7371 7372 TPM_ST 7373 7374 tag 7375 7376 see clause 8 7377 7378 UINT32 7379 7380 responseSize 7381 7382 TPM_RC 7383 7384 responseCode 7385 7386 TPM2B_PRIVATE 7387 7388 outDuplicate 7389 7390 TPM2B_ENCRYPTED_SECRET outSymSeed 7391 7392 Page 82 7393 October 31, 2013 7394 7395 an object encrypted using symmetric key derived from 7396 outSymSeed 7397 seed for a symmetric key protected by newParent 7398 asymmetric key 7399 7400 Published 7401 Copyright TCG 2006-2013 7402 7403 Family 2.0 7404 Level 00 Revision 00.99 7405 7406 Trusted Platform Module Library 7408 7409 Part 3: Commands 7410 7411 15.2.3 Detailed Actions 7412 1 7413 2 7414 3 7415 7416 #include "InternalRoutines.h" 7417 #include "Rewrap_fp.h" 7418 #include "Object_spt_fp.h" 7419 Error Returns 7420 TPM_RC_ATTRIBUTES 7421 7422 newParent is not a decryption key 7423 7424 TPM_RC_HANDLE 7425 7426 oldParent does not consistent with inSymSeed 7427 7428 TPM_RC_INTEGRITY 7429 7430 the integrity check of inDuplicate failed 7431 7432 TPM_RC_KEY 7433 7434 for an ECC key, the public key is not on the curve of the curve ID 7435 7436 TPM_RC_KEY_SIZE 7437 7438 the decrypted input symmetric key size does not matches the 7439 symmetric algorithm key size of oldParent 7440 7441 TPM_RC_TYPE 7442 7443 oldParent is not a storage key, or 'newParent is not a storage key 7444 7445 TPM_RC_VALUE 7446 7447 for an 'oldParent; RSA key, the data to be decrypted is greater than 7448 the public exponent 7449 7450 Unmarshal errors 7451 7452 4 7453 5 7454 6 7455 7 7456 8 7457 9 7458 10 7459 11 7460 12 7461 13 7462 14 7463 15 7464 16 7465 17 7466 18 7467 19 7468 20 7469 21 7470 22 7471 23 7472 24 7473 25 7474 26 7475 27 7476 28 7477 29 7478 30 7479 31 7480 32 7481 33 7482 34 7483 35 7484 36 7485 37 7486 38 7487 39 7488 7489 Meaning 7490 7491 errors during unmarshaling the input encrypted buffer to a ECC public 7492 key, or unmarshal the private buffer to sensitive 7493 7494 TPM_RC 7495 TPM2_Rewrap( 7496 Rewrap_In 7497 Rewrap_Out 7498 7499 *in, 7500 *out 7501 7502 // IN: input parameter list 7503 // OUT: output parameter list 7504 7505 TPM_RC 7506 OBJECT 7507 TPM2B_DATA 7508 UINT16 7509 TPM2B_PRIVATE 7510 7511 result = TPM_RC_SUCCESS; 7512 *oldParent; 7513 data; 7514 // symmetric key 7515 hashSize = 0; 7516 privateBlob; 7517 // A temporary private blob 7518 // to transit between old 7519 // and new wrappers 7520 7521 ) 7522 { 7523 7524 // Input Validation 7525 if((in->inSymSeed.t.size == 0 && in->oldParent != TPM_RH_NULL) 7526 || (in->inSymSeed.t.size != 0 && in->oldParent == TPM_RH_NULL)) 7527 return TPM_RC_HANDLE + RC_Rewrap_oldParent; 7528 if(in->oldParent != TPM_RH_NULL) 7529 { 7530 // Get old parent pointer 7531 oldParent = ObjectGet(in->oldParent); 7532 // old parent key must be a storage object 7533 if(!ObjectIsStorage(in->oldParent)) 7534 return TPM_RC_TYPE + RC_Rewrap_oldParent; 7535 // Decrypt input secret data via asymmetric decryption. A 7536 // TPM_RC_VALUE, TPM_RC_KEY or unmarshal errors may be returned at this 7537 // point 7538 result = CryptSecretDecrypt(in->oldParent, NULL, 7539 "DUPLICATE", &in->inSymSeed, &data); 7540 if(result != TPM_RC_SUCCESS) 7541 return TPM_RC_VALUE + RC_Rewrap_inSymSeed; 7542 7543 Family 2.0 7544 Level 00 Revision 00.99 7545 7546 Published 7547 Copyright TCG 2006-2013 7548 7549 Page 83 7550 October 31, 2013 7551 7552 Part 3: Commands 7554 40 7555 41 7556 42 7557 43 7558 44 7559 45 7560 46 7561 47 7562 48 7563 49 7564 50 7565 51 7566 52 7567 53 7568 54 7569 55 7570 56 7571 57 7572 58 7573 59 7574 60 7575 61 7576 62 7577 63 7578 64 7579 65 7580 66 7581 67 7582 68 7583 69 7584 70 7585 71 7586 72 7587 73 7588 74 7589 75 7590 76 7591 77 7592 78 7593 79 7594 80 7595 81 7596 82 7597 83 7598 84 7599 85 7600 86 7601 87 7602 88 7603 89 7604 90 7605 91 7606 92 7607 93 7608 94 7609 95 7610 96 7611 97 7612 98 7613 99 7614 100 7615 101 7616 102 7617 103 7618 7619 Trusted Platform Module Library 7620 7621 // Unwrap Outer 7622 result = UnwrapOuter(in->oldParent, &in->name, 7623 oldParent->publicArea.nameAlg, (TPM2B_SEED *) &data, 7624 FALSE, 7625 in->inDuplicate.t.size, in->inDuplicate.t.buffer); 7626 if(result != TPM_RC_SUCCESS) 7627 return RcSafeAddToResult(result, RC_Rewrap_inDuplicate); 7628 // Copy unwrapped data to temporary variable, remove the integrity field 7629 hashSize = sizeof(UINT16) + 7630 CryptGetHashDigestSize(oldParent->publicArea.nameAlg); 7631 privateBlob.t.size = in->inDuplicate.t.size - hashSize; 7632 MemoryCopy(privateBlob.t.buffer, in->inDuplicate.t.buffer + hashSize, 7633 privateBlob.t.size, sizeof(privateBlob.t.buffer)); 7634 } 7635 else 7636 { 7637 // No outer wrap from input blob. 7638 privateBlob = in->inDuplicate; 7639 } 7640 7641 Direct copy. 7642 7643 if(in->newParent != TPM_RH_NULL) 7644 { 7645 OBJECT 7646 *newParent; 7647 newParent = ObjectGet(in->newParent); 7648 // New parent must be a storage object 7649 if(!ObjectIsStorage(in->newParent)) 7650 return TPM_RC_TYPE + RC_Rewrap_newParent; 7651 // Make new encrypt key and its associated secret structure. A 7652 // TPM_RC_VALUE error may be returned at this point if RSA algorithm is 7653 // enabled in TPM 7654 out->outSymSeed.t.size = sizeof(out->outSymSeed.t.secret); 7655 result = CryptSecretEncrypt(in->newParent, 7656 "DUPLICATE", &data, &out->outSymSeed); 7657 if(result != TPM_RC_SUCCESS) return result; 7658 // Command output 7659 // Copy temporary variable to output, reserve the space for integrity 7660 hashSize = sizeof(UINT16) + 7661 CryptGetHashDigestSize(newParent->publicArea.nameAlg); 7662 out->outDuplicate.t.size = privateBlob.t.size; 7663 MemoryCopy(out->outDuplicate.t.buffer + hashSize, privateBlob.t.buffer, 7664 privateBlob.t.size, sizeof(out->outDuplicate.t.buffer)); 7665 // Produce outer wrapper for output 7666 out->outDuplicate.t.size = ProduceOuterWrap(in->newParent, &in->name, 7667 newParent->publicArea.nameAlg, 7668 (TPM2B_SEED *) &data, 7669 FALSE, 7670 out->outDuplicate.t.size, 7671 out->outDuplicate.t.buffer); 7672 } 7673 else // New parent is a null key so there is no seed 7674 { 7675 out->outSymSeed.t.size = 0; 7676 // Copy privateBlob directly 7677 out->outDuplicate = privateBlob; 7678 } 7679 7680 Page 84 7681 October 31, 2013 7682 7683 Published 7684 Copyright TCG 2006-2013 7685 7686 Family 2.0 7687 Level 00 Revision 00.99 7688 7689 Trusted Platform Module Library 7691 104 7692 105 7693 7694 Part 3: Commands 7695 7696 return TPM_RC_SUCCESS; 7697 } 7698 7699 Family 2.0 7700 Level 00 Revision 00.99 7701 7702 Published 7703 Copyright TCG 2006-2013 7704 7705 Page 85 7706 October 31, 2013 7707 7708 Part 3: Commands 7710 7711 15.3 7712 7713 Trusted Platform Module Library 7714 7715 TPM2_Import 7716 7717 15.3.1 General Description 7718 This command allows an object to be encrypted using the symmetric encryption values of a Storage Key. 7719 After encryption, the object may be loaded and used in the new hierarchy. The imported object (duplicate) 7720 may be singly encrypted, multiply encrypted, or unencrypted. 7721 If fixedTPM or fixedParent is SET in objectPublic, the TPM shall return TPM_RC_ATTRIBUTES. 7722 If encryptedDuplication is SET in the object referenced by parentHandle, then encryptedDuplication shall 7723 be set in objectPublic (TPM_RC_ATTRIBUTES). However, see Note 2. 7724 Recovery of the sensitive data of the object occurs in the TPM in a three-step process in the following 7725 order: 7726 7727 7728 If present, the outer layer of symmetric encryption is removed. If inSymSeed has a non-zero size, the 7729 asymmetric parameters and private key of parentHandle are used to recover the seed used in the 7730 creation of the HMAC key and encryption keys used to protect the duplication blob. When recovering 7731 the seed, L is DUPLICATE. 7732 NOTE 1 7733 7734 If the encryptedDuplication attribute of the object 7735 TPM_RC_ATTRIBUTES if inSymSeed is an empty buffer. 7736 7737 is 7738 7739 SET, 7740 7741 the 7742 7743 TPM 7744 7745 shall 7746 7747 return 7748 7749 7750 7751 If present, the inner layer of symmetric encryption is removed. If encryptionKey and symmetricAlg are 7752 provided, they are used to decrypt duplication. 7753 7754 7755 7756 If present, the integrity value of the blob is checked. The presence of the integrity value is indicated 7757 by a non-zero value for duplicate.data.integrity.size. The integrity of the private area is validated using 7758 the Name of objectPublic in the integrity HMAC computation. If either the outer layer or inner layer of 7759 encryption is performed, then the integrity value shall be present. 7760 7761 If the inner or outer wrapper is present, then a valid integrity value shall be present or the TPM shall 7762 return TPM_RC_INTEGRITY. 7763 NOTE 2 7764 7765 It is not necessary to validate that the sensitive area data is cryptographically bound to the public 7766 area other than that the Name of the public area is included in the HMAC. However, if the binding is 7767 not validated by this command, the binding must be checked each time the object is loaded. For an 7768 object that is imported under a parent with fixedTPM SET, binding need only be checked at import. If 7769 the parent has fixedTPM CLEAR, then the binding needs to be checked each time the object is 7770 loaded, or before the TPM performs an operation for which the binding affects the outcome of the 7771 operation (for example, TPM2_PolicySigned() or TPM2_Certify()). 7772 Similarly, if the new parent's fixedTPM is set, the encryptedDuplication state need only be checked 7773 at import. 7774 If the new parent is not fixedTPM, then that object will be loadable on any TPM (including SW 7775 versions) on which the new parent exists. This means that, each time an object is loaded under a 7776 parent that is not fixedTPM, it is necessary to validate all of the properties of that object. If the 7777 parent is fixedTPM, then the new private blob is integrity protected by the TPM that owns the 7778 parent. So, it is sufficient to validate the objects properties (attribute and public -private binding) on 7779 import and not again. 7780 7781 Before duplicate.buffer is decrypted using the symmetric key of the parent, the integrity value shall be 7782 checked before the sensitive area is used, or unmarshaled. 7783 After integrity checks and decryption, the TPM will create a new symmetrically encrypted private area 7784 using the encryption key of the parent. 7785 NOTE 3 7786 7787 Checking the integrity before the data is used prevents attacks on the sensitive area by fuzzing the 7788 data and looking at the differences in the response codes. 7789 7790 Page 86 7791 October 31, 2013 7792 7793 Published 7794 Copyright TCG 2006-2013 7795 7796 Family 2.0 7797 Level 00 Revision 00.99 7798 7799 Trusted Platform Module Library 7801 NOTE 4 7802 7803 Part 3: Commands 7804 7805 The symmetric re-encryption is the normal integrity generation and symmetric encryption applied to 7806 a child object. 7807 7808 Family 2.0 7809 Level 00 Revision 00.99 7810 7811 Published 7812 Copyright TCG 2006-2013 7813 7814 Page 87 7815 October 31, 2013 7816 7817 Part 3: Commands 7819 7820 Trusted Platform Module Library 7821 7822 15.3.2 Command and Response 7823 Table 39 TPM2_Import Command 7824 Type 7825 7826 Name 7827 7828 TPMI_ST_COMMAND_TAG 7829 7830 tag 7831 7832 UINT32 7833 7834 commandSize 7835 7836 TPM_CC 7837 7838 commandCode 7839 7840 TPM_CC_Import 7841 7842 TPMI_DH_OBJECT 7843 7844 @parentHandle 7845 7846 the handle of the new parent for the object 7847 Auth Index: 1 7848 Auth Role: USER 7849 7850 encryptionKey 7851 7852 the optional symmetric encryption key used as the inner 7853 wrapper for duplicate 7854 If symmetricAlg is TPM_ALG_NULL, then this 7855 parameter shall be the Empty Buffer. 7856 7857 TPM2B_DATA 7858 7859 TPM2B_PUBLIC 7860 7861 objectPublic 7862 7863 Description 7864 7865 the public area of the object to be imported 7866 This is provided so that the integrity value for duplicate 7867 and the object attributes can be checked. 7868 NOTE 7869 7870 TPM2B_PRIVATE 7871 7872 duplicate 7873 7874 Even if the integrity value of the object is not 7875 checked on input, the object Name is required to 7876 create the integrity value for the imported object. 7877 7878 the symmetrically encrypted duplicate object that may 7879 contain an inner symmetric wrapper 7880 7881 TPM2B_ENCRYPTED_SECRET inSymSeed 7882 7883 symmetric key used to encrypt duplicate 7884 inSymSeed is encrypted/encoded using the algorithms 7885 of newParent. 7886 7887 TPMT_SYM_DEF_OBJECT+ 7888 7889 definition for the symmetric algorithm to use for the inner 7890 wrapper 7891 If this algorithm is TPM_ALG_NULL, no inner wrapper is 7892 present and encryptionKey shall be the Empty Buffer. 7893 7894 symmetricAlg 7895 7896 Table 40 TPM2_Import Response 7897 Type 7898 7899 Name 7900 7901 Description 7902 7903 TPM_ST 7904 7905 tag 7906 7907 see clause 8 7908 7909 UINT32 7910 7911 responseSize 7912 7913 TPM_RC 7914 7915 responseCode 7916 7917 TPM2B_PRIVATE 7918 7919 outPrivate 7920 7921 Page 88 7922 October 31, 2013 7923 7924 the sensitive area encrypted with the symmetric key of 7925 parentHandle 7926 7927 Published 7928 Copyright TCG 2006-2013 7929 7930 Family 2.0 7931 Level 00 Revision 00.99 7932 7933 Trusted Platform Module Library 7935 7936 Part 3: Commands 7937 7938 15.3.3 Detailed Actions 7939 1 7940 2 7941 3 7942 7943 #include "InternalRoutines.h" 7944 #include "Import_fp.h" 7945 #include "Object_spt_fp.h" 7946 Error Returns 7947 7948 Meaning 7949 7950 TPM_RC_ASYMMETRIC 7951 7952 non-duplicable storage key represented by objectPublic and its 7953 parent referenced by parentHandle have different public params 7954 7955 TPM_RC_ATTRIBUTES 7956 7957 attributes FixedTPM and fixedParent of objectPublic are not both 7958 CLEAR; or inSymSeed is nonempty and parentHandle does not 7959 reference a decryption key; or objectPublic and parentHandle have 7960 incompatible or inconsistent attributes 7961 7962 TPM_RC_BINDING 7963 7964 duplicate and objectPublic are not cryptographically bound 7965 7966 TPM_RC_ECC_POINT 7967 7968 inSymSeed is nonempty and ECC point in inSymSeed is not on the 7969 curve 7970 7971 TPM_RC_HASH 7972 7973 non-duplicable storage key represented by objectPublic and its 7974 parent referenced by parentHandle have different name algorithm 7975 7976 TPM_RC_INSUFFICIENT 7977 7978 inSymSeed is nonempty and failed to retrieve ECC point from the 7979 secret; or unmarshaling sensitive value from duplicate failed the 7980 result of inSymSeed decryption 7981 7982 TPM_RC_INTEGRITY 7983 7984 duplicate integrity is broken 7985 7986 TPM_RC_KDF 7987 7988 objectPublic representing decrypting keyed hash object specifies 7989 invalid KDF 7990 7991 TPM_RC_KEY 7992 7993 inconsistent parameters of objectPublic; or inSymSeed is nonempty 7994 and parentHandle does not reference a key of supported type; or 7995 invalid key size in objectPublic representing an asymmetric key 7996 7997 TPM_RC_NO_RESULT 7998 7999 inSymSeed is nonempty and multiplication resulted in ECC point at 8000 infinity 8001 8002 TPM_RC_OBJECT_MEMORY 8003 8004 no available object slot 8005 8006 TPM_RC_SCHEME 8007 8008 inconsistent attributes decrypt, sign, restricted and key's scheme ID 8009 in objectPublic; or hash algorithm is inconsistent with the scheme ID 8010 for keyed hash object 8011 8012 TPM_RC_SIZE 8013 8014 authPolicy size does not match digest size of the name algorithm in 8015 objectPublic; or symmetricAlg and encryptionKey have different 8016 sizes; or inSymSeed is nonempty and it is not of the same size as 8017 RSA key referenced by parentHandle; or unmarshaling sensitive 8018 value from duplicate failed 8019 8020 TPM_RC_SYMMETRIC 8021 8022 objectPublic is either a storage key with no symmetric algorithm or a 8023 non-storage key with symmetric algorithm different from 8024 TPM_ALG_NULL 8025 8026 TPM_RC_TYPE 8027 8028 unsupported type of objectPublic; or non-duplicable storage key 8029 represented by objectPublic and its parent referenced by 8030 parentHandle are of different types; or parentHandle is not a storage 8031 key; or only the public portion of parentHandle is loaded; or 8032 objectPublic and duplicate are of different types 8033 8034 TPM_RC_VALUE 8035 8036 nonempty inSymSeed and its numeric value is greater than the 8037 modulus of the key referenced by parentHandle or inSymSeed is 8038 larger than the size of the digest produced by the name algorithm of 8039 the symmetric key referenced by parentHandle 8040 8041 Family 2.0 8042 Level 00 Revision 00.99 8043 8044 Published 8045 Copyright TCG 2006-2013 8046 8047 Page 89 8048 October 31, 2013 8049 8050 Part 3: Commands 8052 4 8053 5 8054 6 8055 7 8056 8 8057 9 8058 10 8059 11 8060 12 8061 13 8062 14 8063 15 8064 16 8065 17 8066 18 8067 19 8068 20 8069 21 8070 22 8071 23 8072 24 8073 25 8074 26 8075 27 8076 28 8077 29 8078 30 8079 31 8080 32 8081 33 8082 34 8083 35 8084 36 8085 37 8086 38 8087 39 8088 40 8089 41 8090 42 8091 43 8092 44 8093 45 8094 46 8095 47 8096 48 8097 49 8098 50 8099 51 8100 52 8101 53 8102 54 8103 55 8104 56 8105 57 8106 58 8107 59 8108 60 8109 61 8110 62 8111 63 8112 64 8113 65 8114 66 8115 67 8116 8117 Trusted Platform Module Library 8118 8119 TPM_RC 8120 TPM2_Import( 8121 Import_In 8122 Import_Out 8123 8124 *in, 8125 *out 8126 8127 // IN: input parameter list 8128 // OUT: output parameter list 8129 8130 ) 8131 { 8132 TPM_RC 8133 OBJECT 8134 TPM2B_DATA 8135 TPMT_SENSITIVE 8136 TPM2B_NAME 8137 8138 result = TPM_RC_SUCCESS; 8139 *parentObject; 8140 data; 8141 // symmetric key 8142 sensitive; 8143 name; 8144 8145 UINT16 8146 8147 innerKeySize = 0; 8148 8149 // encrypt key size for inner 8150 // wrapper 8151 8152 // Input Validation 8153 // FixedTPM and fixedParent must be CLEAR 8154 if( 8155 in->objectPublic.t.publicArea.objectAttributes.fixedTPM == SET 8156 || in->objectPublic.t.publicArea.objectAttributes.fixedParent == SET) 8157 return TPM_RC_ATTRIBUTES + RC_Import_objectPublic; 8158 // Get parent pointer 8159 parentObject = ObjectGet(in->parentHandle); 8160 if(!AreAttributesForParent(parentObject)) 8161 return TPM_RC_TYPE + RC_Import_parentHandle; 8162 if(in->symmetricAlg.algorithm != TPM_ALG_NULL) 8163 { 8164 // Get inner wrap key size 8165 innerKeySize = in->symmetricAlg.keyBits.sym; 8166 // Input symmetric key must match the size of algorithm. 8167 if(in->encryptionKey.t.size != (innerKeySize + 7) / 8) 8168 return TPM_RC_SIZE + RC_Import_encryptionKey; 8169 } 8170 else 8171 { 8172 // If input symmetric algorithm is NULL, input symmetric key size must 8173 // be 0 as well 8174 if(in->encryptionKey.t.size != 0) 8175 return TPM_RC_SIZE + RC_Import_encryptionKey; 8176 } 8177 // See if there is an outer wrapper 8178 if(in->inSymSeed.t.size != 0) 8179 { 8180 // Decrypt input secret data via asymmetric decryption. TPM_RC_ATTRIBUTES, 8181 // TPM_RC_ECC_POINT, TPM_RC_INSUFFICIENT, TPM_RC_KEY, TPM_RC_NO_RESULT, 8182 // TPM_RC_SIZE, TPM_RC_VALUE may be returned at this point 8183 result = CryptSecretDecrypt(in->parentHandle, NULL, "DUPLICATE", 8184 &in->inSymSeed, &data); 8185 pAssert(result != TPM_RC_BINDING); 8186 if(result != TPM_RC_SUCCESS) 8187 return TPM_RC_VALUE + RC_Import_inSymSeed; 8188 } 8189 else 8190 { 8191 data.t.size = 0; 8192 } 8193 // Compute name of object 8194 ObjectComputeName(&(in->objectPublic.t.publicArea), &name); 8195 8196 Page 90 8197 October 31, 2013 8198 8199 Published 8200 Copyright TCG 2006-2013 8201 8202 Family 2.0 8203 Level 00 Revision 00.99 8204 8205 Trusted Platform Module Library 8207 68 8208 69 8209 70 8210 71 8211 72 8212 73 8213 74 8214 75 8215 76 8216 77 8217 78 8218 79 8219 80 8220 81 8221 82 8222 83 8223 84 8224 85 8225 86 8226 87 8227 88 8228 89 8229 90 8230 91 8231 92 8232 93 8233 94 8234 95 8235 96 8236 97 8237 98 8238 99 8239 100 8240 101 8241 102 8242 103 8243 104 8244 105 8245 106 8246 107 8247 108 8248 109 8249 110 8250 111 8251 112 8252 113 8253 114 8254 8255 Part 3: Commands 8256 8257 // Retrieve sensitive from private. 8258 // TPM_RC_INSUFFICIENT, TPM_RC_INTEGRITY, TPM_RC_SIZE may be returned here. 8259 result = DuplicateToSensitive(&in->duplicate, &name, in->parentHandle, 8260 in->objectPublic.t.publicArea.nameAlg, 8261 (TPM2B_SEED *) &data, &in->symmetricAlg, 8262 &in->encryptionKey, &sensitive); 8263 if(result != TPM_RC_SUCCESS) 8264 return RcSafeAddToResult(result, RC_Import_duplicate); 8265 // If the parent of this object has fixedTPM SET, then fully validate this 8266 // object so that validation can be skipped when it is loaded 8267 if(parentObject->publicArea.objectAttributes.fixedTPM == SET) 8268 { 8269 TPM_HANDLE 8270 objectHandle; 8271 // Perform self check on input public area. A TPM_RC_SIZE, TPM_RC_SCHEME, 8272 // TPM_RC_VALUE, TPM_RC_SYMMETRIC, TPM_RC_TYPE, TPM_RC_HASH, 8273 // TPM_RC_ASYMMETRIC, TPM_RC_ATTRIBUTES or TPM_RC_KDF error may be returned 8274 // at this point 8275 result = PublicAttributesValidation(TRUE, in->parentHandle, 8276 &in->objectPublic.t.publicArea); 8277 if(result != TPM_RC_SUCCESS) 8278 return RcSafeAddToResult(result, RC_Import_objectPublic); 8279 // Create internal object. A TPM_RC_KEY_SIZE, TPM_RC_KEY or 8280 // TPM_RC_OBJECT_MEMORY error may be returned at this point 8281 result = ObjectLoad(TPM_RH_NULL, &in->objectPublic.t.publicArea, 8282 &sensitive, NULL, in->parentHandle, FALSE, 8283 &objectHandle); 8284 if(result != TPM_RC_SUCCESS) 8285 return result; 8286 // Don't need the object, just needed the checks to be performed so 8287 // flush the object 8288 ObjectFlush(objectHandle); 8289 } 8290 // Command output 8291 // Prepare output private data from sensitive 8292 SensitiveToPrivate(&sensitive, &name, in->parentHandle, 8293 in->objectPublic.t.publicArea.nameAlg, 8294 &out->outPrivate); 8295 return TPM_RC_SUCCESS; 8296 } 8297 8298 Family 2.0 8299 Level 00 Revision 00.99 8300 8301 Published 8302 Copyright TCG 2006-2013 8303 8304 Page 91 8305 October 31, 2013 8306 8307 Part 3: Commands 8309 8310 16 8311 8312 Trusted Platform Module Library 8313 8314 Asymmetric Primitives 8315 8316 16.1 8317 8318 Introduction 8319 8320 The commands in this clause provide low-level primitives for access to the asymmetric algorithms 8321 implemented in the TPM. Many of these commands are only allowed if the asymmetric key is an 8322 unrestricted key. 8323 16.2 8324 8325 TPM2_RSA_Encrypt 8326 8327 16.2.1 General Description 8328 This command performs RSA encryption using the indicated padding scheme according to PKCS#1v2.1 8329 (PKCS#1). If the scheme of keyHandle is TPM_ALG_NULL, then the caller may use inScheme to specify 8330 the padding scheme. If scheme of keyHandle is not TPM_ALG_NULL, then inScheme shall either be 8331 TPM_ALG_NULL or be the same as scheme (TPM_RC_SCHEME). 8332 The key referenced by keyHandle is required to be an RSA key (TPM_RC_KEY) with the decrypt attribute 8333 SET (TPM_RC_ATTRIBUTES). 8334 NOTE 8335 8336 Requiring that the decrypt attribute be set allows the TPM to ensure that the scheme selection is 8337 done with the presumption that the scheme of the key is a decryption scheme selection. It is 8338 understood that this command will operate on a key with only the publi c part loaded so the caller 8339 may modify any key in any desired way. So, this constraint only serves to simplify the TPM logic. 8340 8341 The three types of allowed padding are: 8342 1) TPM_ALG_OAEP Data is OAEP padded as described in 7.1 of PKCS#1 v2.1. The only 8343 supported mask generation is MGF1. 8344 2) TPM_ALG_RSAES Data is padded as described in 7.2 of PKCS#1 v2.1. 8345 3) TPM_ALG_NULL Data is not padded by the TPM and the TPM will treat message as an 8346 unsigned integer and perform a modular exponentiation of message using the public 8347 exponent of the key referenced by keyHandle. This scheme is only used if both the scheme 8348 in the key referenced by keyHandle is TPM_ALG_NULL, and the inScheme parameter of the 8349 command is TPM_ALG_NULL. The input value cannot be larger than the public modulus of 8350 the key referenced by keyHandle. 8351 Table 41 Padding Scheme Selection 8352 keyHandlescheme 8353 8354 OAEP 8355 RSAES 8356 8357 TPM_ALG_RSAES 8358 8359 RSAES 8360 error (TPM_RC_SCHEME) 8361 8362 TPM_ALG_NULL 8363 8364 OAEP 8365 8366 TPM_ALG_RSAES 8367 8368 error (TPM_RC_SCHEME) 8369 8370 TPM_AGL_OAEP 8371 8372 October 31, 2013 8373 8374 RSAES 8375 8376 TPM_ALG_OAEP 8377 8378 Page 92 8379 8380 TPM_ALG_RSAES 8381 8382 TPM_ALG_NULL 8383 8384 TPM_ALG_OAEP 8385 8386 none 8387 8388 TPM_ALG_OAEP 8389 8390 TPM_ALG_RSAES 8391 8392 padding scheme used 8393 8394 TPM_ALG_NULL 8395 TPM_ALG_NULL 8396 8397 inScheme 8398 8399 OAEP 8400 8401 Published 8402 Copyright TCG 2006-2013 8403 8404 Family 2.0 8405 Level 00 Revision 00.99 8406 8407 Trusted Platform Module Library 8409 8410 Part 3: Commands 8411 8412 After padding, the data is RSAEP encrypted according to 5.1.1 of PKCS#1v2.1. 8413 NOTE 1 8414 8415 It is required that decrypt be SET so that the commands that load a key can validate that the 8416 scheme is consistent rather than have that deferred until the key is used. 8417 8418 NOTE 2 8419 8420 If it is desired to use a key that had restricted SET, the caller may CLEAR restricted and load the 8421 public part of the key and use that unrestricted version of the key for encryption. 8422 8423 If inScheme is used, and the scheme requires a hash algorithm it may not be TPM_ALG_NULL. 8424 NOTE 3 8425 8426 Because only the public portion of the key needs to be loaded for this command, the caller can 8427 manipulate the attributes of the key in any way desired. As a result , the TPM shall not check the 8428 consistency of the attributes. The only property checking is that the key is an RSA key and that the 8429 padding scheme is supported. 8430 8431 The message parameter is limited in size by the padding scheme according to the following table: 8432 Table 42 Message Size Limits Based on Padding 8433 Scheme 8434 8435 Maximum Message Length 8436 (mLen) in Octets 8437 8438 TPM_ALG_OAEP 8439 8440 mLen k 2hLen 2 8441 8442 TPM_ALG_RSAES 8443 8444 mLen k 11 8445 8446 TPM_ALG_NULL 8447 8448 mLen k 8449 8450 Comments 8451 8452 The numeric value of the message must be 8453 less than the numeric value of the public 8454 modulus (n). 8455 8456 NOTES 8457 1) 8458 2) 8459 8460 k the number of byes in the public modulus 8461 hLen the number of octets in the digest produced by the hash algorithm used in the process 8462 8463 The label parameter is optional. If provided (label.size != 0) then the TPM shall return TPM_RC_VALUE if 8464 the last octet in label is not zero. If a zero octet occurs before label.buffer[label.size-1], the TPM shall 8465 truncate the label at that point. The terminating octet of zero is included in the label used in the padding 8466 scheme. 8467 NOTE 4 8468 8469 If the scheme does not use a label, the TPM will still verify that label is properly formatted if label is 8470 present. 8471 8472 The function returns padded and encrypted value outData. 8473 The message parameter in the command may be encrypted using parameter encryption. 8474 NOTE 5 8475 8476 Only the public area of keyHandle is required to be loaded. A public key may be loaded with any 8477 desired scheme. If the scheme is to be changed, a different public area must be loaded. 8478 8479 Family 2.0 8480 Level 00 Revision 00.99 8481 8482 Published 8483 Copyright TCG 2006-2013 8484 8485 Page 93 8486 October 31, 2013 8487 8488 Part 3: Commands 8490 8491 Trusted Platform Module Library 8492 8493 16.2.2 Command and Response 8494 Table 43 TPM2_RSA_Encrypt Command 8495 Type 8496 8497 Name 8498 8499 Description 8500 8501 TPMI_ST_COMMAND_TAG 8502 8503 tag 8504 8505 UINT32 8506 8507 commandSize 8508 8509 TPM_CC 8510 8511 commandCode 8512 8513 TPM_CC_RSA_Encrypt 8514 8515 TPMI_DH_OBJECT 8516 8517 keyHandle 8518 8519 reference to public portion of RSA key to use for 8520 encryption 8521 Auth Index: None 8522 message to be encrypted 8523 8524 TPM2B_PUBLIC_KEY_RSA 8525 8526 message 8527 8528 TPMT_RSA_DECRYPT+ 8529 8530 inScheme 8531 8532 TPM2B_DATA 8533 8534 label 8535 8536 NOTE 1 8537 8538 The data type was chosen because it limits the 8539 overall size of the input to no greater than the size 8540 of the largest RSA public key. This may be larger 8541 than allowed for keyHandle. 8542 8543 the padding scheme to use if scheme associated with 8544 keyHandle is TPM_ALG_NULL 8545 optional label L to be associated with the message 8546 Size of the buffer is zero if no label is present 8547 NOTE 2 8548 8549 See description of label above. 8550 8551 Table 44 TPM2_RSA_Encrypt Response 8552 Type 8553 8554 Name 8555 8556 Description 8557 8558 TPM_ST 8559 8560 tag 8561 8562 see clause 8 8563 8564 UINT32 8565 8566 responseSize 8567 8568 TPM_RC 8569 8570 responseCode 8571 8572 TPM2B_PUBLIC_KEY_RSA 8573 8574 outData 8575 8576 Page 94 8577 October 31, 2013 8578 8579 encrypted output 8580 8581 Published 8582 Copyright TCG 2006-2013 8583 8584 Family 2.0 8585 Level 00 Revision 00.99 8586 8587 Trusted Platform Module Library 8589 8590 Part 3: Commands 8591 8592 16.2.3 Detailed Actions 8593 1 8594 2 8595 3 8596 8597 #include "InternalRoutines.h" 8598 #include "RSA_Encrypt_fp.h" 8599 #ifdef TPM_ALG_RSA 8600 Error Returns 8601 TPM_RC_ATTRIBUTES 8602 8603 decrypt attribute is not SET in key referenced by keyHandle 8604 8605 TPM_RC_KEY 8606 8607 keyHandle does not reference an RSA key 8608 8609 TPM_RC_SCHEME 8610 8611 incorrect input scheme, or the chosen scheme is not a valid RSA 8612 decrypt scheme 8613 8614 TPM_RC_VALUE 8615 8616 4 8617 5 8618 6 8619 7 8620 8 8621 9 8622 10 8623 11 8624 12 8625 13 8626 14 8627 15 8628 16 8629 17 8630 18 8631 19 8632 20 8633 21 8634 22 8635 23 8636 24 8637 25 8638 26 8639 27 8640 28 8641 29 8642 30 8643 31 8644 32 8645 33 8646 34 8647 35 8648 36 8649 37 8650 38 8651 39 8652 40 8653 41 8654 42 8655 43 8656 44 8657 45 8658 46 8659 8660 Meaning 8661 8662 the numeric value of message is greater than the public modulus of 8663 the key referenced by keyHandle, or label is not a null-terminated 8664 string 8665 8666 TPM_RC 8667 TPM2_RSA_Encrypt( 8668 RSA_Encrypt_In 8669 RSA_Encrypt_Out 8670 8671 *in, 8672 *out 8673 8674 // IN: input parameter list 8675 // OUT: output parameter list 8676 8677 TPM_RC 8678 OBJECT 8679 TPMT_RSA_DECRYPT 8680 char 8681 8682 result; 8683 *rsaKey; 8684 *scheme; 8685 *label = NULL; 8686 8687 ) 8688 { 8689 8690 // Input Validation 8691 rsaKey = ObjectGet(in->keyHandle); 8692 // selected key must be an RSA key 8693 if(rsaKey->publicArea.type != TPM_ALG_RSA) 8694 return TPM_RC_KEY + RC_RSA_Encrypt_keyHandle; 8695 // selected key must have the decryption attribute 8696 if(rsaKey->publicArea.objectAttributes.decrypt != SET) 8697 return TPM_RC_ATTRIBUTES + RC_RSA_Encrypt_keyHandle; 8698 // Is there a label? 8699 if(in->label.t.size > 0) 8700 { 8701 // label is present, so make sure that is it NULL-terminated 8702 if(in->label.t.buffer[in->label.t.size - 1] != 0) 8703 return TPM_RC_VALUE + RC_RSA_Encrypt_label; 8704 label = (char *)in->label.t.buffer; 8705 } 8706 // Command Output 8707 // Select a scheme for encryption 8708 scheme = CryptSelectRSAScheme(in->keyHandle, &in->inScheme); 8709 if(scheme == NULL) 8710 return TPM_RC_SCHEME + RC_RSA_Encrypt_inScheme; 8711 // Encryption. TPM_RC_VALUE, or TPM_RC_SCHEME errors my be returned buy 8712 // CryptEncyptRSA. Note: It can also return TPM_RC_ATTRIBUTES if the key does 8713 // not have the decrypt attribute but that was checked above. 8714 out->outData.t.size = sizeof(out->outData.t.buffer); 8715 8716 Family 2.0 8717 Level 00 Revision 00.99 8718 8719 Published 8720 Copyright TCG 2006-2013 8721 8722 Page 95 8723 October 31, 2013 8724 8725 Part 3: Commands 8727 47 8728 48 8729 49 8730 50 8731 51 8732 52 8733 8734 Trusted Platform Module Library 8735 8736 result = CryptEncryptRSA(&out->outData.t.size, out->outData.t.buffer, rsaKey, 8737 scheme, in->message.t.size, in->message.t.buffer, 8738 label); 8739 return result; 8740 } 8741 #endif 8742 8743 Page 96 8744 October 31, 2013 8745 8746 Published 8747 Copyright TCG 2006-2013 8748 8749 Family 2.0 8750 Level 00 Revision 00.99 8751 8752 Trusted Platform Module Library 8754 8755 16.3 8756 8757 Part 3: Commands 8758 8759 TPM2_RSA_Decrypt 8760 8761 16.3.1 General Description 8762 This command performs RSA decryption using the indicated padding scheme according to PKCS#1v2.1 8763 (PKCS#1). 8764 The scheme selection for this command is the same as for TPM2_RSA_Encrypt() and is shown in Table 8765 41. 8766 The key referenced by keyHandle shall be an RSA key (TPM_RC_KEY) with restricted CLEAR and 8767 decrypt SET (TPM_RC_ATTRIBUTES). 8768 This command uses the private key of keyHandle for this operation and authorization is required. 8769 The TPM will perform a modular exponentiation of ciphertext using the private exponent associated with 8770 keyHandle (this is described in PKCS#1v2.1, clause 5.1.2). It will then validate the padding according to 8771 the selected scheme. If the padding checks fail, TPM_RC_VALUE is returned. Otherwise, the data is 8772 returned with the padding removed. If no padding is used, the returned value is an unsigned integer value 8773 that is the result of the modular exponentiation of cipherText using the private exponent of keyHandle. 8774 The returned value may include leading octets zeros so that it is the same size as the public modulus. For 8775 the other padding schemes, the returned value will be smaller than the public modulus but will contain all 8776 the data remaining after padding is removed and this may include leading zeros if the original encrypted 8777 value contained leading zeros.. 8778 If a label is used in the padding process of the scheme, the label parameter is required to be present in 8779 the decryption process and label is required to be the same in both cases. The TPM shall verify that the 8780 label is consistent and if not it shall return TPM_RC_VALUE. 8781 If label is present (label.size != 0), it 8782 shall be a NULL-terminated string or the TPM will return TPM_RC_VALUE. 8783 NOTE 1 8784 8785 The size of label includes the terminating null. 8786 8787 The message parameter in the response may be encrypted using parameter encryption. 8788 If the decryption scheme does not require a hash function, the hash parameter of inScheme may be set 8789 to any valid hash function or TPM_ALG_NULL. 8790 If the description scheme does not require a label, the value in label is not used but the size of the label 8791 field is checked for consistency with the indicated data type (TPM2B_DATA). That is, the field may not be 8792 larger than allowed for a TPM2B_DATA. 8793 8794 Family 2.0 8795 Level 00 Revision 00.99 8796 8797 Published 8798 Copyright TCG 2006-2013 8799 8800 Page 97 8801 October 31, 2013 8802 8803 Part 3: Commands 8805 8806 Trusted Platform Module Library 8807 8808 16.3.2 Command and Response 8809 Table 45 TPM2_RSA_Decrypt Command 8810 Type 8811 8812 Name 8813 8814 Description 8815 8816 TPMI_ST_COMMAND_TAG 8817 8818 tag 8819 8820 UINT32 8821 8822 commandSize 8823 8824 TPM_CC 8825 8826 commandCode 8827 8828 TPM_CC_RSA_Decrypt 8829 8830 TPMI_DH_OBJECT 8831 8832 @keyHandle 8833 8834 RSA key to use for decryption 8835 Auth Index: 1 8836 Auth Role: USER 8837 8838 TPM2B_PUBLIC_KEY_RSA 8839 8840 cipherText 8841 8842 NOTE 8843 8844 TPMT_RSA_DECRYPT+ 8845 8846 inScheme 8847 8848 the padding scheme to use if scheme associated with 8849 keyHandle is TPM_ALG_NULL 8850 8851 TPM2B_DATA 8852 8853 label 8854 8855 label whose association with the message is to be 8856 verified 8857 8858 cipher text to be decrypted 8859 An encrypted RSA data block is the size of the 8860 public modulus. 8861 8862 Table 46 TPM2_RSA_Decrypt Response 8863 Type 8864 8865 Name 8866 8867 Description 8868 8869 TPM_ST 8870 8871 tag 8872 8873 see clause 8 8874 8875 UINT32 8876 8877 responseSize 8878 8879 TPM_RC 8880 8881 responseCode 8882 8883 TPM2B_PUBLIC_KEY_RSA 8884 8885 message 8886 8887 Page 98 8888 October 31, 2013 8889 8890 decrypted output 8891 8892 Published 8893 Copyright TCG 2006-2013 8894 8895 Family 2.0 8896 Level 00 Revision 00.99 8897 8898 Trusted Platform Module Library 8900 8901 Part 3: Commands 8902 8903 16.3.3 Detailed Actions 8904 1 8905 2 8906 3 8907 8908 #include "InternalRoutines.h" 8909 #include "RSA_Decrypt_fp.h" 8910 #ifdef TPM_ALG_RSA 8911 Error Returns 8912 TPM_RC_KEY 8913 8914 keyHandle does not reference an unrestricted decrypt key 8915 8916 TPM_RC_SCHEME 8917 8918 incorrect input scheme, or the chosen scheme is not a valid RSA 8919 decrypt scheme 8920 8921 TPM_RC_SIZE 8922 8923 cipherText is not the size of the modulus of key referenced by 8924 keyHandle 8925 8926 TPM_RC_VALUE 8927 8928 4 8929 5 8930 6 8931 7 8932 8 8933 9 8934 10 8935 11 8936 12 8937 13 8938 14 8939 15 8940 16 8941 17 8942 18 8943 19 8944 20 8945 21 8946 22 8947 23 8948 24 8949 25 8950 26 8951 27 8952 28 8953 29 8954 30 8955 31 8956 32 8957 33 8958 34 8959 35 8960 36 8961 37 8962 38 8963 39 8964 40 8965 41 8966 42 8967 43 8968 44 8969 45 8970 46 8971 8972 Meaning 8973 8974 label is not a null terminated string or the value of cipherText is 8975 greater that the modulus of keyHandle 8976 8977 TPM_RC 8978 TPM2_RSA_Decrypt( 8979 RSA_Decrypt_In 8980 RSA_Decrypt_Out 8981 8982 *in, 8983 *out 8984 8985 // IN: input parameter list 8986 // OUT: output parameter list 8987 8988 TPM_RC 8989 OBJECT 8990 TPMT_RSA_DECRYPT 8991 char 8992 8993 result; 8994 *rsaKey; 8995 *scheme; 8996 *label = NULL; 8997 8998 ) 8999 { 9000 9001 // Input Validation 9002 rsaKey = ObjectGet(in->keyHandle); 9003 // The selected key must be an RSA key 9004 if(rsaKey->publicArea.type != TPM_ALG_RSA) 9005 return TPM_RC_KEY + RC_RSA_Decrypt_keyHandle; 9006 // The selected key must be an unrestricted decryption key 9007 if( 9008 rsaKey->publicArea.objectAttributes.restricted == SET 9009 || rsaKey->publicArea.objectAttributes.decrypt == CLEAR) 9010 return TPM_RC_ATTRIBUTES + RC_RSA_Decrypt_keyHandle; 9011 // 9012 // 9013 // 9014 // 9015 9016 NOTE: Proper operation of this command requires that the sensitive area 9017 of the key is loaded. This is assured because authorization is required 9018 to use the sensitive area of the key. In order to check the authorization, 9019 the sensitive area has to be loaded, even if authorization is with policy. 9020 9021 // If label is present, make sure that it is a NULL-terminated string 9022 if(in->label.t.size > 0) 9023 { 9024 // Present, so make sure that it is NULL-terminated 9025 if(in->label.t.buffer[in->label.t.size - 1] != 0) 9026 return TPM_RC_VALUE + RC_RSA_Decrypt_label; 9027 label = (char *)in->label.t.buffer; 9028 } 9029 // Command Output 9030 // Select a scheme for decrypt. 9031 scheme = CryptSelectRSAScheme(in->keyHandle, &in->inScheme); 9032 if(scheme == NULL) 9033 9034 Family 2.0 9035 Level 00 Revision 00.99 9036 9037 Published 9038 Copyright TCG 2006-2013 9039 9040 Page 99 9041 October 31, 2013 9042 9043 Part 3: Commands 9045 47 9046 48 9047 49 9048 50 9049 51 9050 52 9051 53 9052 54 9053 55 9054 56 9055 57 9056 58 9057 59 9058 60 9059 61 9060 9061 Trusted Platform Module Library 9062 9063 return TPM_RC_SCHEME + RC_RSA_Decrypt_inScheme; 9064 // Decryption. TPM_RC_VALUE, TPM_RC_SIZE, and TPM_RC_KEY error may be 9065 // returned by CryptDecryptRSA. 9066 // NOTE: CryptDecryptRSA can also return TPM_RC_ATTRIBUTES or TPM_RC_BINDING 9067 // when the key is not a decryption key but that was checked above. 9068 out->message.t.size = sizeof(out->message.t.buffer); 9069 result = CryptDecryptRSA(&out->message.t.size, out->message.t.buffer, rsaKey, 9070 scheme, in->cipherText.t.size, 9071 in->cipherText.t.buffer, 9072 label); 9073 return result; 9074 } 9075 #endif 9076 9077 Page 100 9078 October 31, 2013 9079 9080 Published 9081 Copyright TCG 2006-2013 9082 9083 Family 2.0 9084 Level 00 Revision 00.99 9085 9086 Trusted Platform Module Library 9088 9089 16.4 9090 9091 Part 3: Commands 9092 9093 TPM2_ECDH_KeyGen 9094 9095 16.4.1 General Description 9096 This command uses the TPM to generate an ephemeral key pair (de, Qe where Qe [de]G). It uses the private 9097 ephemeral key and a loaded public key (QS) to compute the shared secret value (P [hde]QS). 9098 9099 keyHandle shall refer to a loaded ECC key. The sensitive portion of this key need not be loaded. 9100 The curve parameters of the loaded ECC key are used to generate the ephemeral key. 9101 NOTE 1 9102 9103 This function is the equivalent of encrypting data to another objects public key. The seed value is 9104 used in a KDF to generate a symmetric key and that key is used to encrypt the data. Once the data 9105 is encrypted and the symmetric key discarded, only the ob ject with the private portion of the 9106 keyHandle will be able to decrypt it. 9107 9108 The zPoint in the response may be encrypted using parameter encryption. 9109 9110 Family 2.0 9111 Level 00 Revision 00.99 9112 9113 Published 9114 Copyright TCG 2006-2013 9115 9116 Page 101 9117 October 31, 2013 9118 9119 Part 3: Commands 9121 9122 Trusted Platform Module Library 9123 9124 16.4.2 Command and Response 9125 Table 47 TPM2_ECDH_KeyGen Command 9126 Type 9127 9128 Name 9129 9130 Description 9131 9132 TPMI_ST_COMMAND_TAG 9133 9134 tag 9135 9136 UINT32 9137 9138 commandSize 9139 9140 TPM_CC 9141 9142 commandCode 9143 9144 TPM_CC_ECDH_KeyGen 9145 9146 TPMI_DH_OBJECT 9147 9148 keyHandle 9149 9150 Handle of a loaded ECC key public area. 9151 Auth Index: None 9152 9153 Table 48 TPM2_ECDH_KeyGen Response 9154 Type 9155 9156 Name 9157 9158 Description 9159 9160 TPM_ST 9161 9162 tag 9163 9164 see clause 8 9165 9166 UINT32 9167 9168 responseSize 9169 9170 TPM_RC 9171 9172 responseCode 9173 9174 TPM2B_ECC_POINT 9175 9176 zPoint 9177 9178 results of P h[de]Qs 9179 9180 TPM2B_ECC_POINT 9181 9182 pubPoint 9183 9184 generated ephemeral public point (Qe) 9185 9186 Page 102 9187 October 31, 2013 9188 9189 Published 9190 Copyright TCG 2006-2013 9191 9192 Family 2.0 9193 Level 00 Revision 00.99 9194 9195 Trusted Platform Module Library 9197 9198 Part 3: Commands 9199 9200 16.4.3 Detailed Actions 9201 1 9202 2 9203 3 9204 9205 #include "InternalRoutines.h" 9206 #include "ECDH_KeyGen_fp.h" 9207 #ifdef TPM_ALG_ECC 9208 Error Returns 9209 TPM_RC_KEY 9210 9211 4 9212 5 9213 6 9214 7 9215 8 9216 9 9217 10 9218 11 9219 12 9220 13 9221 14 9222 15 9223 16 9224 17 9225 18 9226 19 9227 20 9228 21 9229 22 9230 23 9231 24 9232 25 9233 26 9234 27 9235 28 9236 29 9237 30 9238 31 9239 32 9240 33 9241 34 9242 35 9243 36 9244 37 9245 38 9246 39 9247 40 9248 41 9249 42 9250 43 9251 44 9252 45 9253 46 9254 47 9255 48 9256 49 9257 50 9258 51 9259 52 9260 53 9261 9262 Meaning 9263 keyHandle does not reference a non-restricted decryption ECC key 9264 9265 TPM_RC 9266 TPM2_ECDH_KeyGen( 9267 ECDH_KeyGen_In 9268 ECDH_KeyGen_Out 9269 9270 *in, 9271 *out 9272 9273 // IN: input parameter list 9274 // OUT: output parameter list 9275 9276 ) 9277 { 9278 OBJECT 9279 TPM2B_ECC_PARAMETER 9280 TPM_RC 9281 9282 *eccKey; 9283 sensitive; 9284 result; 9285 9286 // Input Validation 9287 eccKey = ObjectGet(in->keyHandle); 9288 // Input key must be a non-restricted, decrypt ECC key 9289 if( 9290 eccKey->publicArea.type != TPM_ALG_ECC 9291 || eccKey->publicArea.objectAttributes.restricted == SET 9292 || eccKey->publicArea.objectAttributes.decrypt != SET 9293 ) 9294 return TPM_RC_KEY + RC_ECDH_KeyGen_keyHandle; 9295 // Command Output 9296 do 9297 { 9298 // Create ephemeral ECC key 9299 CryptNewEccKey(eccKey->publicArea.parameters.eccDetail.curveID, 9300 &out->pubPoint.t.point, &sensitive); 9301 out->pubPoint.t.size = TPMS_ECC_POINT_Marshal(&out->pubPoint.t.point, 9302 NULL, NULL); 9303 // Compute Z 9304 result = CryptEccPointMultiply(&out->zPoint.t.point, 9305 eccKey->publicArea.parameters.eccDetail.curveID, 9306 &sensitive, &eccKey->publicArea.unique.ecc); 9307 // The point in the key is not on the curve. Indicate that the key is bad. 9308 if(result == TPM_RC_ECC_POINT) 9309 return TPM_RC_KEY + RC_ECDH_KeyGen_keyHandle; 9310 // The other possible error is TPM_RC_NO_RESULT indicating that the 9311 // multiplication resulted in the point at infinity, so get a new 9312 // random key and start over (hardly ever happens). 9313 } 9314 while(result != TPM_RC_SUCCESS); 9315 // Marshal the values to generate the point. 9316 out->zPoint.t.size = TPMS_ECC_POINT_Marshal(&out->zPoint.t.point, NULL, NULL); 9317 return TPM_RC_SUCCESS; 9318 } 9319 #endif 9320 9321 Family 2.0 9322 Level 00 Revision 00.99 9323 9324 Published 9325 Copyright TCG 2006-2013 9326 9327 Page 103 9328 October 31, 2013 9329 9330 Part 3: Commands 9332 9333 16.5 9334 9335 Trusted Platform Module Library 9336 9337 TPM2_ECDH_ZGen 9338 9339 16.5.1 General Description 9340 This command uses the TPM to recover the Z value from a public point (QB) and a private key (ds). It will 9341 perform the multiplication of the provided inPoint (QB) with the private key (ds) and return the coordinates 9342 of the resultant point (Z = (xZ , yZ) [hds]QB; where h is the cofactor of the curve). 9343 keyHandle shall refer to a loaded, ECC key (TPM_RC_KEY) with the restricted attribute CLEAR and the 9344 decrypt attribute SET (TPM_RC_ATTRIBUTES). 9345 The scheme of the key referenced by keyHandle is required to be either TPM_ALG_ECDH or 9346 TPM_ALG_NULL (TPM_RC_SCHEME). 9347 inPoint is required to be on the curve of the key referenced by keyHandle (TPM_RC_ECC_POINT). 9348 The parameters of the key referenced by keyHandle are used to perform the point multiplication. 9349 9350 Page 104 9351 October 31, 2013 9352 9353 Published 9354 Copyright TCG 2006-2013 9355 9356 Family 2.0 9357 Level 00 Revision 00.99 9358 9359 Trusted Platform Module Library 9361 9362 Part 3: Commands 9363 9364 16.5.2 Command and Response 9365 Table 49 TPM2_ECDH_ZGen Command 9366 Type 9367 9368 Name 9369 9370 Description 9371 9372 TPMI_ST_COMMAND_TAG 9373 9374 tag 9375 9376 UINT32 9377 9378 commandSize 9379 9380 TPM_CC 9381 9382 commandCode 9383 9384 TPM_CC_ECDH_ZGen 9385 9386 TPMI_DH_OBJECT 9387 9388 @keyHandle 9389 9390 handle of a loaded ECC key 9391 Auth Index: 1 9392 Auth Role: USER 9393 9394 TPM2B_ECC_POINT 9395 9396 inPoint 9397 9398 a public key 9399 9400 Table 50 TPM2_ECDH_ZGen Response 9401 Type 9402 9403 Name 9404 9405 Description 9406 9407 TPM_ST 9408 9409 tag 9410 9411 see clause 8 9412 9413 UINT32 9414 9415 responseSize 9416 9417 TPM_RC 9418 9419 responseCode 9420 9421 TPM2B_ECC_POINT 9422 9423 outPoint 9424 9425 Family 2.0 9426 Level 00 Revision 00.99 9427 9428 X and Y coordinates of the product of the multiplication 9429 9430 Z = (xZ , yZ) [hdS]QB 9431 9432 Published 9433 Copyright TCG 2006-2013 9434 9435 Page 105 9436 October 31, 2013 9437 9438 Part 3: Commands 9440 9441 Trusted Platform Module Library 9442 9443 16.5.3 Detailed Actions 9444 1 9445 2 9446 3 9447 9448 #include "InternalRoutines.h" 9449 #include "ECDH_ZGen_fp.h" 9450 #ifdef TPM_ALG_ECC 9451 Error Returns 9452 TPM_RC_KEY 9453 9454 keyHandle does not reference a non-restricted decryption ECC key 9455 9456 TPM_RC_ECC_POINT 9457 9458 invalid argument 9459 9460 TPM_RC_NO_RESULT 9461 4 9462 5 9463 6 9464 7 9465 8 9466 9 9467 10 9468 11 9469 12 9470 13 9471 14 9472 15 9473 16 9474 17 9475 18 9476 19 9477 20 9478 21 9479 22 9480 23 9481 24 9482 25 9483 26 9484 27 9485 28 9486 29 9487 30 9488 31 9489 32 9490 33 9491 34 9492 35 9493 36 9494 37 9495 38 9496 39 9497 9498 Meaning 9499 9500 multiplying inPoint resulted in a point at infinity 9501 9502 TPM_RC 9503 TPM2_ECDH_ZGen( 9504 ECDH_ZGen_In 9505 ECDH_ZGen_Out 9506 9507 *in, 9508 *out 9509 9510 // IN: input parameter list 9511 // OUT: output parameter list 9512 9513 ) 9514 { 9515 TPM_RC 9516 OBJECT 9517 9518 result; 9519 *eccKey; 9520 9521 // Input Validation 9522 eccKey = ObjectGet(in->keyHandle); 9523 // Input key must be a non-restricted, decrypt ECC key 9524 if( 9525 eccKey->publicArea.type != TPM_ALG_ECC 9526 || eccKey->publicArea.objectAttributes.restricted == SET 9527 || eccKey->publicArea.objectAttributes.decrypt != SET 9528 ) 9529 return TPM_RC_KEY + RC_ECDH_ZGen_keyHandle; 9530 // Command Output 9531 // Compute Z. TPM_RC_ECC_POINT or TPM_RC_NO_RESULT may be returned here. 9532 result = CryptEccPointMultiply(&out->outPoint.t.point, 9533 eccKey->publicArea.parameters.eccDetail.curveID, 9534 &eccKey->sensitive.sensitive.ecc, 9535 &in->inPoint.t.point); 9536 if(result != TPM_RC_SUCCESS) 9537 return RcSafeAddToResult(result, RC_ECDH_ZGen_inPoint); 9538 out->outPoint.t.size = TPMS_ECC_POINT_Marshal(&out->outPoint.t.point, 9539 NULL, NULL); 9540 return TPM_RC_SUCCESS; 9541 } 9542 #endif 9543 9544 Page 106 9545 October 31, 2013 9546 9547 Published 9548 Copyright TCG 2006-2013 9549 9550 Family 2.0 9551 Level 00 Revision 00.99 9552 9553 Trusted Platform Module Library 9555 9556 16.6 9557 9558 Part 3: Commands 9559 9560 TPM2_ECC_Parameters 9561 9562 16.6.1 General Description 9563 This command returns the parameters of an ECC curve identified by its TCG-assigned curveID. 9564 16.6.2 Command and Response 9565 Table 51 TPM2_ECC_Parameters Command 9566 Type 9567 9568 Name 9569 9570 Description 9571 9572 TPMI_ST_COMMAND_TAG 9573 9574 tag 9575 9576 UINT32 9577 9578 commandSize 9579 9580 TPM_CC 9581 9582 commandCode 9583 9584 TPM_CC_ECC_Parameters 9585 9586 TPMI_ECC_CURVE 9587 9588 curveID 9589 9590 parameter set selector 9591 9592 Table 52 TPM2_ECC_Parameters Response 9593 Type 9594 9595 Name 9596 9597 Description 9598 9599 TPM_ST 9600 9601 tag 9602 9603 see clause 8 9604 9605 UINT32 9606 9607 responseSize 9608 9609 TPM_RC 9610 9611 responseCode 9612 9613 TPMS_ALGORITHM_DETAIL_ECC 9614 9615 parameters 9616 9617 Family 2.0 9618 Level 00 Revision 00.99 9619 9620 ECC parameters for the selected curve 9621 9622 Published 9623 Copyright TCG 2006-2013 9624 9625 Page 107 9626 October 31, 2013 9627 9628 Part 3: Commands 9630 9631 Trusted Platform Module Library 9632 9633 16.6.3 Detailed Actions 9634 1 9635 2 9636 3 9637 9638 #include "InternalRoutines.h" 9639 #include "ECC_Parameters_fp.h" 9640 #ifdef TPM_ALG_ECC 9641 Error Returns 9642 TPM_RC_VALUE 9643 9644 4 9645 5 9646 6 9647 7 9648 8 9649 9 9650 10 9651 11 9652 12 9653 13 9654 14 9655 15 9656 16 9657 17 9658 18 9659 9660 Meaning 9661 Unsupported ECC curve ID 9662 9663 TPM_RC 9664 TPM2_ECC_Parameters( 9665 ECC_Parameters_In 9666 ECC_Parameters_Out 9667 9668 *in, 9669 *out 9670 9671 // IN: input parameter list 9672 // OUT: output parameter list 9673 9674 ) 9675 { 9676 // Command Output 9677 // Get ECC curve parameters 9678 if(CryptEccGetParameters(in->curveID, &out->parameters)) 9679 return TPM_RC_SUCCESS; 9680 else 9681 return TPM_RC_VALUE + RC_ECC_Parameters_curveID; 9682 } 9683 #endif 9684 9685 16.7 9686 16.7.1 9687 9688 TPM2_ZGen_2Phase 9689 General Description 9690 9691 This command supports two-phase key exchange protocols. The command is used in combination with 9692 TPM2_EC_Ephemeral(). TPM2_EC_Ephemeral() generates an ephemeral key and returns the public 9693 point of that ephemeral key along with a numeric value that allows the TPM to regenerate the associated 9694 private key. 9695 The input parameters for this command are a static public key (inQsU), an ephemeral key (inQeU) from 9696 party B, and the commitCounter returned by TPM2_EC_Ephemeral(). The TPM uses the counter value to 9697 regenerate the ephemeral private key (de,V) and the associated public key (Qe,V). keyA provides the static 9698 ephemeral elements ds,V and Qs,V. This provides the two pairs of ephemeral and static keys that are 9699 required for the schemes supported by this command. 9700 The TPM will compute Z or Zs and Ze according to the selected scheme. If the scheme is not a two-phase 9701 key exchange scheme or if the scheme is not supported, the TPM will return TPM_RC_SCHEME. 9702 It is an error if inQsB or inQeB are not on the curve of keyA (TPM_RC_ECC_POINT). 9703 The two-phase key schemes that were assigned an algorithm ID as of the time of the publication of this 9704 specification are TPM_ALG_ECDH, TPM_ALG_ECMQV, and TPM_ALG_SM2. 9705 If this command is supported, then support for TPM_ALG_ECDH is required. Support for 9706 TPM_ALG_ECMQV or TPM_ALG_SM2 is optional. 9707 NOTE 1 9708 9709 If SM2 is supported and this command is supported, then the implementation is required to support 9710 the key exchange protocol of SM2, part 3. 9711 9712 For TPM_ALG_ECDH outZ1 will be Zs and outZ2 will Ze as defined in 6.1.1.2 of SP800-56A. 9713 9714 Page 108 9715 October 31, 2013 9716 9717 Published 9718 Copyright TCG 2006-2013 9719 9720 Family 2.0 9721 Level 00 Revision 00.99 9722 9723 Trusted Platform Module Library 9725 NOTE 2 9726 9727 Part 3: Commands 9728 9729 A non-restricted decryption key using ECDH may be used in either TPM2_ECDH_ZGen() or 9730 TPM2_ZGen_2Phase as the computation done with the private part of keyA is the same in both 9731 cases. 9732 9733 For TPM_ALG_ECMQV or TPM_ALG_SM2 outZ1 will be Z and outZ2 will be an Empty Point. 9734 NOTE 3 9735 9736 An Empty Point has two Empty Buffers as coordinates meaning the minimum size value for outZ2 9737 will be four. 9738 9739 If the input scheme is TPM_ALG_ECDH, then outZ1 will be Zs and outZ2 will be Ze. For schemes like 9740 MQV (including SM2), outZ1 will contain the computed value and outZ2 will be an Empty Point. 9741 NOTE 9742 9743 The Z values returned by the TPM are a full point and not ju st an x-coordinate. 9744 9745 If a computation of either Z produces the point at infinity, then the corresponding Z value will be an Empty 9746 Point. 9747 9748 Family 2.0 9749 Level 00 Revision 00.99 9750 9751 Published 9752 Copyright TCG 2006-2013 9753 9754 Page 109 9755 October 31, 2013 9756 9757 Part 3: Commands 9759 9760 16.7.2 9761 9762 Trusted Platform Module Library 9763 9764 Command and Response 9765 Table 53 TPM2_ZGen_2Phase Command 9766 9767 Type 9768 9769 Name 9770 9771 TPMI_ST_COMMAND_TAG 9772 9773 tag 9774 9775 UINT32 9776 9777 commandSize 9778 9779 TPM_CC 9780 9781 commandCode 9782 9783 Description 9784 9785 TPM_CC_ ZGen_2Phase 9786 handle of an unrestricted decryption key ECC 9787 The private key referenced by this handle is used as dS,A 9788 9789 TPMI_DH_OBJECT 9790 9791 @keyA 9792 9793 TPM2B_ECC_POINT 9794 9795 inQsB 9796 9797 other partys static public key (Qs,B = (Xs,B, Ys,B)) 9798 9799 TPM2B_ECC_POINT 9800 9801 inQeB 9802 9803 other party's ephemeral public key (Qe,B = (Xe,B, Ye,B)) 9804 9805 TPMI_ECC_KEY_EXCHANGE 9806 9807 inScheme 9808 9809 the key exchange scheme 9810 9811 UINT16 9812 9813 counter 9814 9815 value returned by TPM2_EC_Ephemeral() 9816 9817 Auth Index: 1 9818 Auth Role: USER 9819 9820 Table 54 TPM2_ZGen_2Phase Response 9821 Type 9822 9823 Name 9824 9825 TPM_ST 9826 9827 tag 9828 9829 UINT32 9830 9831 responseSize 9832 9833 TPM_RC 9834 9835 responseCode 9836 9837 TPM2B_ECC_POINT 9838 9839 outZ1 9840 9841 X and Y coordinates of the computed value (scheme 9842 dependent) 9843 9844 TPM2B_ECC_POINT 9845 9846 outZ2 9847 9848 X and Y coordinates of the second computed value 9849 (scheme dependent) 9850 9851 Page 110 9852 October 31, 2013 9853 9854 Description 9855 9856 Published 9857 Copyright TCG 2006-2013 9858 9859 Family 2.0 9860 Level 00 Revision 00.99 9861 9862 Trusted Platform Module Library 9864 9865 16.7.3 9866 1 9867 2 9868 3 9869 9870 Part 3: Commands 9871 9872 Detailed Actions 9873 9874 #include "InternalRoutines.h" 9875 #include "ZGen_2Phase_fp.h" 9876 #if defined TPM_ALG_ECC && (CC_ZGen_2Phase == YES) 9877 9878 This command uses the TPM to recover one or two Z values in a two phase key exchange protocol 9879 Error Returns 9880 TPM_RC_ATTRIBUTES 9881 9882 key referenced by keyA is restricted or not a decrypt key 9883 9884 TPM_RC_ECC_POINT 9885 9886 inQsB or inQeB is not on the curve of the key reference by keyA 9887 9888 TPM_RC_KEY 9889 9890 key referenced by keyA is not an ECC key 9891 9892 TPM_RC_SCHEME 9893 9894 4 9895 5 9896 6 9897 7 9898 8 9899 9 9900 10 9901 11 9902 12 9903 13 9904 14 9905 15 9906 16 9907 17 9908 18 9909 19 9910 20 9911 21 9912 22 9913 23 9914 24 9915 25 9916 26 9917 27 9918 28 9919 29 9920 30 9921 31 9922 32 9923 33 9924 34 9925 35 9926 36 9927 37 9928 38 9929 39 9930 40 9931 41 9932 42 9933 43 9934 44 9935 45 9936 46 9937 47 9938 9939 Meaning 9940 9941 the scheme of the key referenced by keyA is not TPM_ALG_NULL, 9942 TPM_ALG_ECDH, TPM_ALG_ECMQV or TPM_ALG_SM2 9943 9944 TPM_RC 9945 TPM2_ZGen_2Phase( 9946 ZGen_2Phase_In 9947 ZGen_2Phase_Out 9948 9949 *in, 9950 *out 9951 9952 // IN: input parameter list 9953 // OUT: output parameter list 9954 9955 ) 9956 { 9957 TPM_RC 9958 OBJECT 9959 TPM2B_ECC_PARAMETER 9960 TPM_ALG_ID 9961 9962 result; 9963 *eccKey; 9964 r; 9965 scheme; 9966 9967 // Input Validation 9968 eccKey = ObjectGet(in->keyA); 9969 // keyA must be an ECC key 9970 if(eccKey->publicArea.type != TPM_ALG_ECC) 9971 return TPM_RC_KEY + RC_ZGen_2Phase_keyA; 9972 // keyA must not be restricted and must be a decrypt key 9973 if( 9974 eccKey->publicArea.objectAttributes.restricted == SET 9975 || eccKey->publicArea.objectAttributes.decrypt != SET 9976 ) 9977 return TPM_RC_ATTRIBUTES + RC_ZGen_2Phase_keyA; 9978 // if the scheme of keyA is TPM_ALG_NULL, then use the input scheme; otherwise 9979 // the input scheme must be the same as the scheme of keyA 9980 scheme = eccKey->publicArea.parameters.asymDetail.scheme.scheme; 9981 if(scheme != TPM_ALG_NULL) 9982 { 9983 if(scheme != in->inScheme) 9984 return TPM_RC_SCHEME + RC_ZGen_2Phase_inScheme; 9985 } 9986 else 9987 scheme = in->inScheme; 9988 if(scheme == TPM_ALG_NULL) 9989 return TPM_RC_SCHEME + RC_ZGen_2Phase_inScheme; 9990 // Input points must be on the curve of keyA 9991 if(!CryptEccIsPointOnCurve(eccKey->publicArea.parameters.eccDetail.curveID, 9992 &in->inQsB.t.point)) 9993 return TPM_RC_ECC_POINT + RC_ZGen_2Phase_inQsB; 9994 if(!CryptEccIsPointOnCurve(eccKey->publicArea.parameters.eccDetail.curveID, 9995 9996 Family 2.0 9997 Level 00 Revision 00.99 9998 9999 Published 10000 Copyright TCG 2006-2013 10001 10002 Page 111 10003 October 31, 2013 10004 10005 Part 3: Commands 10007 48 10008 49 10009 50 10010 51 10011 52 10012 53 10013 54 10014 55 10015 56 10016 57 10017 58 10018 59 10019 60 10020 61 10021 62 10022 63 10023 64 10024 65 10025 66 10026 67 10027 68 10028 69 10029 70 10030 71 10031 72 10032 73 10033 10034 Trusted Platform Module Library 10035 10036 &in->inQeB.t.point)) 10037 return TPM_RC_ECC_POINT + RC_ZGen_2Phase_inQeB; 10038 if(!CryptGenerateR(&r, &in->counter, 10039 eccKey->publicArea.parameters.eccDetail.curveID, 10040 NULL)) 10041 return TPM_RC_VALUE + RC_ZGen_2Phase_counter; 10042 // Command Output 10043 result = CryptEcc2PhaseKeyExchange(&out->outZ1.t.point, 10044 &out->outZ2.t.point, 10045 eccKey->publicArea.parameters.eccDetail.curveID, 10046 scheme, 10047 &eccKey->sensitive.sensitive.ecc, 10048 &r, 10049 &in->inQsB.t.point, 10050 &in->inQeB.t.point); 10051 if(result != TPM_RC_SUCCESS) 10052 return result; 10053 CryptEndCommit(in->counter); 10054 return TPM_RC_SUCCESS; 10055 } 10056 #endif 10057 10058 Page 112 10059 October 31, 2013 10060 10061 Published 10062 Copyright TCG 2006-2013 10063 10064 Family 2.0 10065 Level 00 Revision 00.99 10066 10067 Trusted Platform Module Library 10069 10070 17 10071 17.1 10072 10073 Part 3: Commands 10074 10075 Symmetric Primitives 10076 Introduction 10077 10078 The commands in this clause provide low-level primitives for access to the symmetric algorithms 10079 implemented in the TPM that operate on blocks of data. These include symmetric encryption and 10080 decryption as well as hash and HMAC. All of the commands in this group are stateless. That is, they have 10081 no persistent state that is retained in the TPM when the command is complete. 10082 For hashing, HMAC, and Events that require large blocks of data with retained state, the sequence 10083 commands are provided (see clause 1). 10084 Some of the symmetric encryption/decryption modes use an IV. When an IV is used, it may be an 10085 initiation value or a chained value from a previous stage. The chaining for each mode is: 10086 10087 Family 2.0 10088 Level 00 Revision 00.99 10089 10090 Published 10091 Copyright TCG 2006-2013 10092 10093 Page 113 10094 October 31, 2013 10095 10096 Part 3: Commands 10098 10099 Trusted Platform Module Library 10100 Table 55 Symmetric Chaining Process 10101 10102 Mode 10103 10104 Chaining process 10105 10106 TPM_ALG_CTR 10107 10108 The TPM will increment the entire IV provided by the caller. The last encrypted value will be 10109 returned to the caller as ivOut. This can be the input value to the next encrypted buffer. 10110 ivIn is required to be the size of a block encrypted by the selected algorithm and key 10111 combination. If the size of ivIn is not correct, the TPM shall return TPM_RC_SIZE. 10112 EXAMPLE 1 AES requires that ivIn be 128 bits (16 octets). 10113 10114 ivOut will be the size of a cipher block and not the size of the last encrypted block. 10115 NOTE 10116 10117 ivOut will be the value of the counter after the last block is encrypted. 10118 10119 EXAMPLE 2 If ivIn were 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0016 and four data blocks 10120 were encrypted, ivOut will have a value of 10121 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0416. 10122 10123 All the bits of the IV are incremented as if it were an unsigned integer. 10124 TPM_ALG_OFB 10125 10126 In Output Feedback (OFB), the output of the pseudo-random function (the block encryption 10127 algorithm) is XORed with a plaintext block to produce a ciphertext block. ivOut will be the 10128 value that was XORed with the last plaintext block. That value can be used as the ivIn for a 10129 next buffer. 10130 ivIn is required to be the size of a block encrypted by the selected algorithm and key 10131 combination. If the size of ivIn is not correct, the TPM shall return TPM_RC_SIZE. 10132 ivOut will be the size of a cipher block and not the size of the last encrypted block. 10133 10134 TPM_ALG_CBC 10135 10136 For Cipher Block Chaining (CBC), a block of ciphertext is XORed with the next plaintext 10137 block and that block is encrypted. The encrypted block is then input to the encryption of the 10138 next block. The last ciphertext block then is used as an IV for the next buffer. 10139 Even though the last ciphertext block is evident in the encrypted data, it is also returned in 10140 ivOut. 10141 ivIn is required to be the size of a block encrypted by the selected algorithm and key 10142 combination. If the size of ivIn is not correct, the TPM shall return TPM_RC_SIZE. 10143 inData is required to be an even multiple of the block encrypted by the selected algorithm 10144 and key combination. If the size of inData is not correct, the TPM shall return 10145 TPM_RC_SIZE. 10146 10147 TPM_ALG_CFB 10148 10149 Similar to CBC in that the last ciphertext block is an input to the encryption of the next block. 10150 ivOut will be the value that was XORed with the last plaintext block. That value can be used 10151 as the ivIn for a next buffer. 10152 ivIn is required to be the size of a block encrypted by the selected algorithm and key 10153 combination. If the size of ivIn is not correct, the TPM shall return TPM_RC_SIZE. 10154 ivOut will be the size of a cipher block and not the size of the last encrypted block. 10155 10156 TPM_ALG_ECB 10157 10158 Electronic Codebook (ECB) has no chaining. Each block of plaintext is encrypted using the 10159 key. ECB does not support chaining and ivIn shall be the Empty Buffer. ivOut will be the 10160 Empty Buffer. 10161 inData is required to be an even multiple of the block encrypted by the selected algorithm 10162 and key combination. If the size of inData is not correct, the TPM shall return 10163 TPM_RC_SIZE. 10164 10165 Page 114 10166 October 31, 2013 10167 10168 Published 10169 Copyright TCG 2006-2013 10170 10171 Family 2.0 10172 Level 00 Revision 00.99 10173 10174 Trusted Platform Module Library 10176 10177 17.2 10178 10179 Part 3: Commands 10180 10181 TPM2_EncryptDecrypt 10182 10183 17.2.1 General Description 10184 This command performs symmetric encryption or decryption. 10185 keyHandle shall reference a symmetric cipher object (TPM_RC_KEY). 10186 For a restricted key, mode shall be either the same as the mode of the key, or TPM_ALG_NULL 10187 (TPM_RC_VALUE). For an unrestricted key, mode may be the same or different from the mode of the key 10188 but both shall not be TPM_ALG_NULL (TPM_RC_VALUE). 10189 If the TPM allows this command to be canceled before completion, then the TPM may produce 10190 incremental results and return TPM_RC_SUCCESS rather than TPM_RC_CANCEL. In such case, 10191 outData may be less than inData. 10192 10193 Family 2.0 10194 Level 00 Revision 00.99 10195 10196 Published 10197 Copyright TCG 2006-2013 10198 10199 Page 115 10200 October 31, 2013 10201 10202 Part 3: Commands 10204 10205 Trusted Platform Module Library 10206 10207 17.2.2 Command and Response 10208 Table 56 TPM2_EncryptDecrypt Command 10209 Type 10210 10211 Name 10212 10213 Description 10214 10215 TPMI_ST_COMMAND_TAG 10216 10217 tag 10218 10219 UINT32 10220 10221 commandSize 10222 10223 TPM_CC 10224 10225 commandCode 10226 10227 TPM_CC_EncryptDecrypt 10228 10229 TPMI_DH_OBJECT 10230 10231 @keyHandle 10232 10233 the symmetric key used for the operation 10234 Auth Index: 1 10235 Auth Role: USER 10236 10237 TPMI_YES_NO 10238 10239 decrypt 10240 10241 if YES, then the operation is decryption; if NO, the 10242 operation is encryption 10243 10244 TPMI_ALG_SYM_MODE+ 10245 10246 mode 10247 10248 symmetric mode 10249 For a restricted key, this field shall match the default 10250 mode of the key or be TPM_ALG_NULL. 10251 10252 TPM2B_IV 10253 10254 ivIn 10255 10256 an initial value as required by the algorithm 10257 10258 TPM2B_MAX_BUFFER 10259 10260 inData 10261 10262 the data to be encrypted/decrypted 10263 10264 Table 57 TPM2_EncryptDecrypt Response 10265 Type 10266 10267 Name 10268 10269 Description 10270 10271 TPM_ST 10272 10273 tag 10274 10275 see clause 8 10276 10277 UINT32 10278 10279 responseSize 10280 10281 TPM_RC 10282 10283 responseCode 10284 10285 TPM2B_MAX_BUFFER 10286 10287 outData 10288 10289 encrypted output 10290 10291 TPM2B_IV 10292 10293 ivOut 10294 10295 chaining value to use for IV in next round 10296 10297 Page 116 10298 October 31, 2013 10299 10300 Published 10301 Copyright TCG 2006-2013 10302 10303 Family 2.0 10304 Level 00 Revision 00.99 10305 10306 Trusted Platform Module Library 10308 10309 Part 3: Commands 10310 10311 17.2.3 Detailed Actions 10312 1 10313 2 10314 10315 #include "InternalRoutines.h" 10316 #include "EncryptDecrypt_fp.h" 10317 Error Returns 10318 TPM_RC_KEY 10319 10320 is not a symmetric decryption key with both public and private 10321 portions loaded 10322 10323 TPM_RC_SIZE 10324 10325 IvIn size is incompatible with the block cipher mode; or inData size is 10326 not an even multiple of the block size for CBC or ECB mode 10327 10328 TPM_RC_VALUE 10329 10330 3 10331 4 10332 5 10333 6 10334 7 10335 8 10336 9 10337 10 10338 11 10339 12 10340 13 10341 14 10342 15 10343 16 10344 17 10345 18 10346 19 10347 20 10348 21 10349 22 10350 23 10351 24 10352 25 10353 26 10354 27 10355 28 10356 29 10357 30 10358 31 10359 32 10360 33 10361 34 10362 35 10363 36 10364 37 10365 38 10366 39 10367 40 10368 41 10369 42 10370 43 10371 44 10372 45 10373 46 10374 47 10375 48 10376 10377 Meaning 10378 10379 keyHandle is restricted and the argument mode does not match the 10380 key's mode 10381 10382 TPM_RC 10383 TPM2_EncryptDecrypt( 10384 EncryptDecrypt_In 10385 EncryptDecrypt_Out 10386 10387 *in, 10388 *out 10389 10390 // IN: input parameter list 10391 // OUT: output parameter list 10392 10393 ) 10394 { 10395 OBJECT 10396 UINT16 10397 UINT16 10398 BYTE 10399 TPM_ALG_ID 10400 10401 *symKey; 10402 keySize; 10403 blockSize; 10404 *key; 10405 alg; 10406 10407 // Input Validation 10408 symKey = ObjectGet(in->keyHandle); 10409 // The input key should be a symmetric decrypt key. 10410 if( 10411 symKey->publicArea.type != TPM_ALG_SYMCIPHER 10412 || symKey->attributes.publicOnly == SET) 10413 return TPM_RC_KEY + RC_EncryptDecrypt_keyHandle; 10414 // If the input mode is TPM_ALG_NULL, use the key's mode 10415 if( in->mode == TPM_ALG_NULL) 10416 in->mode = symKey->publicArea.parameters.symDetail.sym.mode.sym; 10417 // If the key is restricted, the input sym mode should match the key's sym 10418 // mode 10419 if( 10420 symKey->publicArea.objectAttributes.restricted == SET 10421 && symKey->publicArea.parameters.symDetail.sym.mode.sym != in->mode) 10422 return TPM_RC_VALUE + RC_EncryptDecrypt_mode; 10423 // If the mode is null, then we have a problem. 10424 // Note: Construction of a TPMT_SYM_DEF does not allow the 'mode' to be 10425 // TPM_ALG_NULL so setting in->mode to the mode of the key should have 10426 // produced a valid mode. However, this is suspenders. 10427 if(in->mode == TPM_ALG_NULL) 10428 return TPM_RC_VALUE + RC_EncryptDecrypt_mode; 10429 // The input iv for ECB mode should be null. All the other modes should 10430 // have an iv size same as encryption block size 10431 keySize = symKey->publicArea.parameters.symDetail.sym.keyBits.sym; 10432 alg = symKey->publicArea.parameters.symDetail.sym.algorithm; 10433 blockSize = CryptGetSymmetricBlockSize(alg, keySize); 10434 if( 10435 (in->mode == TPM_ALG_ECB && in->ivIn.t.size != 0) 10436 || (in->mode != TPM_ALG_ECB && in->ivIn.t.size != blockSize)) 10437 return TPM_RC_SIZE + RC_EncryptDecrypt_ivIn; 10438 10439 Family 2.0 10440 Level 00 Revision 00.99 10441 10442 Published 10443 Copyright TCG 2006-2013 10444 10445 Page 117 10446 October 31, 2013 10447 10448 Part 3: Commands 10450 49 10451 50 10452 51 10453 52 10454 53 10455 54 10456 55 10457 56 10458 57 10459 58 10460 59 10461 60 10462 61 10463 62 10464 63 10465 64 10466 65 10467 66 10468 67 10469 68 10470 69 10471 70 10472 71 10473 72 10474 73 10475 74 10476 75 10477 76 10478 77 10479 78 10480 79 10481 80 10482 81 10483 82 10484 83 10485 84 10486 85 10487 86 10488 87 10489 88 10490 89 10491 90 10492 91 10493 10494 Trusted Platform Module Library 10495 10496 // The input data size of CBC mode or ECB mode must be an even multiple of 10497 // the symmetric algorithm's block size 10498 if( 10499 (in->mode == TPM_ALG_CBC || in->mode == TPM_ALG_ECB) 10500 && (in->inData.t.size % blockSize) != 0) 10501 return TPM_RC_SIZE + RC_EncryptDecrypt_inData; 10502 // Copy IV 10503 // Note: This is copied here so that the calls to the encrypt/decrypt functions 10504 // will modify the output buffer, not the input buffer 10505 out->ivOut = in->ivIn; 10506 // Command Output 10507 key = symKey->sensitive.sensitive.sym.t.buffer; 10508 // For symmetric encryption, the cipher data size is the same as plain data 10509 // size. 10510 out->outData.t.size = in->inData.t.size; 10511 if(in->decrypt == YES) 10512 { 10513 // Decrypt data to output 10514 CryptSymmetricDecrypt(out->outData.t.buffer, 10515 alg, 10516 keySize, in->mode, key, 10517 &(out->ivOut), 10518 in->inData.t.size, 10519 in->inData.t.buffer); 10520 } 10521 else 10522 { 10523 // Encrypt data to output 10524 CryptSymmetricEncrypt(out->outData.t.buffer, 10525 alg, 10526 keySize, 10527 in->mode, key, 10528 &(out->ivOut), 10529 in->inData.t.size, 10530 in->inData.t.buffer); 10531 } 10532 return TPM_RC_SUCCESS; 10533 } 10534 10535 Page 118 10536 October 31, 2013 10537 10538 Published 10539 Copyright TCG 2006-2013 10540 10541 Family 2.0 10542 Level 00 Revision 00.99 10543 10544 Trusted Platform Module Library 10546 10547 17.3 10548 10549 Part 3: Commands 10550 10551 TPM2_Hash 10552 10553 17.3.1 General Description 10554 This command performs a hash operation on a data buffer and returns the results. 10555 NOTE 10556 10557 If the data buffer to be hashed is larger than will fit into the TPMs input buffer, then the sequence 10558 hash commands will need to be used. 10559 10560 If the results of the hash will be used in a signing operation that uses a restricted signing key, then the 10561 ticket returned by this command can indicate that the hash is safe to sign. 10562 If the digest is not safe to sign, then the TPM will return a TPMT_TK_HASHCHECK with the hierarchy set 10563 to TPM_RH_NULL and digest set to the Empty Buffer. 10564 If hierarchy is TPM_RH_NULL, then digest in the ticket will be the Empty Buffer. 10565 10566 Family 2.0 10567 Level 00 Revision 00.99 10568 10569 Published 10570 Copyright TCG 2006-2013 10571 10572 Page 119 10573 October 31, 2013 10574 10575 Part 3: Commands 10577 10578 Trusted Platform Module Library 10579 10580 17.3.2 Command and Response 10581 Table 58 TPM2_Hash Command 10582 Type 10583 10584 Name 10585 10586 Description 10587 10588 TPMI_ST_COMMAND_TAG 10589 10590 tag 10591 10592 Shall have at least one session 10593 10594 UINT32 10595 10596 commandSize 10597 10598 TPM_CC 10599 10600 commandCode 10601 10602 TPM_CC_Hash 10603 10604 TPM2B_MAX_BUFFER 10605 10606 data 10607 10608 data to be hashed 10609 10610 TPMI_ALG_HASH 10611 10612 hashAlg 10613 10614 algorithm for the hash being computed shall not be 10615 TPM_ALG_NULL 10616 10617 TPMI_RH_HIERARCHY+ 10618 10619 hierarchy 10620 10621 hierarchy to use for the ticket (TPM_RH_NULL allowed) 10622 10623 Table 59 TPM2_Hash Response 10624 Type 10625 10626 Name 10627 10628 Description 10629 10630 TPM_ST 10631 10632 tag 10633 10634 see clause 8 10635 10636 UINT32 10637 10638 responseSize 10639 10640 TPM_RC 10641 10642 responseCode 10643 10644 TPM2B_DIGEST 10645 10646 outHash 10647 10648 results 10649 10650 validation 10651 10652 ticket indicating that the sequence of octets used to 10653 compute outDigest did not start with 10654 TPM_GENERATED_VALUE 10655 will be a NULL ticket if the digest may not be signed 10656 with a restricted key 10657 10658 TPMT_TK_HASHCHECK 10659 10660 Page 120 10661 October 31, 2013 10662 10663 Published 10664 Copyright TCG 2006-2013 10665 10666 Family 2.0 10667 Level 00 Revision 00.99 10668 10669 Trusted Platform Module Library 10671 10672 Part 3: Commands 10673 10674 17.3.3 Detailed Actions 10675 1 10676 2 10677 3 10678 4 10679 5 10680 6 10681 7 10682 8 10683 9 10684 10 10685 11 10686 12 10687 13 10688 14 10689 15 10690 16 10691 17 10692 18 10693 19 10694 20 10695 21 10696 22 10697 23 10698 24 10699 25 10700 26 10701 27 10702 28 10703 29 10704 30 10705 31 10706 32 10707 33 10708 34 10709 35 10710 36 10711 37 10712 38 10713 39 10714 40 10715 41 10716 42 10717 43 10718 44 10719 45 10720 10721 #include "InternalRoutines.h" 10722 #include "Hash_fp.h" 10723 10724 TPM_RC 10725 TPM2_Hash( 10726 Hash_In 10727 Hash_Out 10728 10729 *in, 10730 *out 10731 10732 // IN: input parameter list 10733 // OUT: output parameter list 10734 10735 ) 10736 { 10737 HASH_STATE 10738 10739 hashState; 10740 10741 // Command Output 10742 // Output hash 10743 // Start hash stack 10744 out->outHash.t.size = CryptStartHash(in->hashAlg, &hashState); 10745 // Adding hash data 10746 CryptUpdateDigest2B(&hashState, &in->data.b); 10747 // Complete hash 10748 CryptCompleteHash2B(&hashState, &out->outHash.b); 10749 // Output ticket 10750 out->validation.tag = TPM_ST_HASHCHECK; 10751 out->validation.hierarchy = in->hierarchy; 10752 if(in->hierarchy == TPM_RH_NULL) 10753 { 10754 // Ticket is not required 10755 out->validation.hierarchy = TPM_RH_NULL; 10756 out->validation.digest.t.size = 0; 10757 } 10758 else if( in->data.t.size >= sizeof(TPM_GENERATED) 10759 && !TicketIsSafe(&in->data.b)) 10760 { 10761 // Ticket is not safe 10762 out->validation.hierarchy = TPM_RH_NULL; 10763 out->validation.digest.t.size = 0; 10764 } 10765 else 10766 { 10767 // Compute ticket 10768 TicketComputeHashCheck(in->hierarchy, &out->outHash, &out->validation); 10769 } 10770 return TPM_RC_SUCCESS; 10771 } 10772 10773 Family 2.0 10774 Level 00 Revision 00.99 10775 10776 Published 10777 Copyright TCG 2006-2013 10778 10779 Page 121 10780 October 31, 2013 10781 10782 Part 3: Commands 10784 10785 17.4 10786 10787 Trusted Platform Module Library 10788 10789 TPM2_HMAC 10790 10791 17.4.1 General Description 10792 This command performs an HMAC on the supplied data using the indicated hash algorithm. 10793 The caller shall provide proper authorization for use of handle. 10794 If the sign attribute is not SET in the key referenced by handle then the TPM shall return 10795 TPM_RC_ATTRIBUTES. If the key type is not TPM_ALG_KEYEDHASH then the TPM shall return 10796 TPM_RC_TYPE. 10797 If handle references a restricted key, then the hash algorithm specified in the key's scheme is used as the 10798 hash algorithm for the HMAC and the TPM shall return TPM_RC_VALUE if hashAlg is not 10799 TPM_ALG_NULL or the same algorithm as selected in the key's scheme. 10800 NOTE 1 10801 A restricted key may only have one of sign or decrypt SET and the default scheme may not 10802 be TPM_ALG_NULL. These restrictions are enforced by TPM2_Create() and TPM2_CreatePrimary(), 10803 If the key referenced by handle is not restricted, then the TPM will use hashAlg for the HMAC. However, if 10804 hashAlg is TPM_ALG_NULL the TPM will use the default scheme of the key. 10805 If both hashAlg and the key default are TPM_ALG_NULL, the TPM shall return TPM_RC_VALUE. 10806 NOTE 10807 10808 A key may only have both sign and decrypt SET if the key is unrestricted. When bo th sign and 10809 decrypt are set, there is no default scheme for the key and the hash algorithm must be specified . 10810 10811 Page 122 10812 October 31, 2013 10813 10814 Published 10815 Copyright TCG 2006-2013 10816 10817 Family 2.0 10818 Level 00 Revision 00.99 10819 10820 Trusted Platform Module Library 10822 10823 Part 3: Commands 10824 10825 17.4.2 Command and Response 10826 Table 60 TPM2_HMAC Command 10827 Type 10828 10829 Name 10830 10831 Description 10832 10833 TPMI_ST_COMMAND_TAG 10834 10835 tag 10836 10837 UINT32 10838 10839 commandSize 10840 10841 TPM_CC 10842 10843 commandCode 10844 10845 TPM_CC_HMAC 10846 10847 TPMI_DH_OBJECT 10848 10849 @handle 10850 10851 handle for the symmetric signing key providing the 10852 HMAC key 10853 Auth Index: 1 10854 Auth Role: USER 10855 10856 TPM2B_MAX_BUFFER 10857 10858 buffer 10859 10860 HMAC data 10861 10862 TPMI_ALG_HASH+ 10863 10864 hashAlg 10865 10866 algorithm to use for HMAC 10867 10868 Table 61 TPM2_HMAC Response 10869 Type 10870 10871 Name 10872 10873 Description 10874 10875 TPM_ST 10876 10877 tag 10878 10879 see clause 8 10880 10881 UINT32 10882 10883 responseSize 10884 10885 TPM_RC 10886 10887 responseCode 10888 10889 TPM2B_DIGEST 10890 10891 outHMAC 10892 10893 Family 2.0 10894 Level 00 Revision 00.99 10895 10896 the returned HMAC in a sized buffer 10897 10898 Published 10899 Copyright TCG 2006-2013 10900 10901 Page 123 10902 October 31, 2013 10903 10904 Part 3: Commands 10906 10907 Trusted Platform Module Library 10908 10909 17.4.3 Detailed Actions 10910 1 10911 2 10912 10913 #include "InternalRoutines.h" 10914 #include "HMAC_fp.h" 10915 Error Returns 10916 TPM_RC_ATTRIBUTES 10917 10918 key referenced by handle is not a signing key 10919 10920 TPM_RC_TYPE 10921 10922 key referenced by handle is not an HMAC key 10923 10924 TPM_RC_VALUE 10925 10926 3 10927 4 10928 5 10929 6 10930 7 10931 8 10932 9 10933 10 10934 11 10935 12 10936 13 10937 14 10938 15 10939 16 10940 17 10941 18 10942 19 10943 20 10944 21 10945 22 10946 23 10947 24 10948 25 10949 26 10950 27 10951 28 10952 29 10953 30 10954 31 10955 32 10956 33 10957 34 10958 35 10959 36 10960 37 10961 38 10962 39 10963 40 10964 41 10965 42 10966 43 10967 44 10968 45 10969 46 10970 47 10971 48 10972 49 10973 10974 Meaning 10975 10976 hashAlg specified when the key is restricted is neither 10977 TPM_ALG_NULL not equal to that of the key scheme; or both 10978 hashAlg and the key scheme's algorithm are TPM_ALG_NULL 10979 10980 TPM_RC 10981 TPM2_HMAC( 10982 HMAC_In 10983 HMAC_Out 10984 10985 *in, 10986 *out 10987 10988 // IN: input parameter list 10989 // OUT: output parameter list 10990 10991 HMAC_STATE 10992 OBJECT 10993 TPMI_ALG_HASH 10994 TPMT_PUBLIC 10995 10996 hmacState; 10997 *hmacObject; 10998 hashAlg; 10999 *publicArea; 11000 11001 ) 11002 { 11003 11004 // Input Validation 11005 // Get HMAC key object and public area pointers 11006 hmacObject = ObjectGet(in->handle); 11007 publicArea = &hmacObject->publicArea; 11008 // Make sure that the key is an HMAC signing key 11009 if(publicArea->type != TPM_ALG_KEYEDHASH) 11010 return TPM_RC_TYPE + RC_HMAC_handle; 11011 if(publicArea->objectAttributes.sign != SET) 11012 return TPM_RC_ATTRIBUTES + RC_HMAC_handle; 11013 // Assume that the key default scheme is used 11014 hashAlg = publicArea->parameters.keyedHashDetail.scheme.details.hmac.hashAlg; 11015 // if the key is restricted, then need to use the scheme of the key and the 11016 // input algorithm must be TPM_ALG_NULL or the same as the key scheme 11017 if(publicArea->objectAttributes.restricted == SET) 11018 { 11019 if(in->hashAlg != TPM_ALG_NULL && in->hashAlg != hashAlg) 11020 hashAlg = TPM_ALG_NULL; 11021 } 11022 else 11023 { 11024 // for a non-restricted key, use hashAlg if it is provided; 11025 if(in->hashAlg != TPM_ALG_NULL) 11026 hashAlg = in->hashAlg; 11027 } 11028 // if the hashAlg is TPM_ALG_NULL, then the input hashAlg is not compatible 11029 // with the key scheme or type 11030 if(hashAlg == TPM_ALG_NULL) 11031 return TPM_RC_VALUE + RC_HMAC_hashAlg; 11032 // Command Output 11033 11034 Page 124 11035 October 31, 2013 11036 11037 Published 11038 Copyright TCG 2006-2013 11039 11040 Family 2.0 11041 Level 00 Revision 00.99 11042 11043 Trusted Platform Module Library 11045 50 11046 51 11047 52 11048 53 11049 54 11050 55 11051 56 11052 57 11053 58 11054 59 11055 60 11056 61 11057 11058 Part 3: Commands 11059 11060 // Start HMAC stack 11061 out->outHMAC.t.size = CryptStartHMAC2B(hashAlg, 11062 &hmacObject->sensitive.sensitive.bits.b, 11063 &hmacState); 11064 // Adding HMAC data 11065 CryptUpdateDigest2B(&hmacState, &in->buffer.b); 11066 // Complete HMAC 11067 CryptCompleteHMAC2B(&hmacState, &out->outHMAC.b); 11068 return TPM_RC_SUCCESS; 11069 } 11070 11071 Family 2.0 11072 Level 00 Revision 00.99 11073 11074 Published 11075 Copyright TCG 2006-2013 11076 11077 Page 125 11078 October 31, 2013 11079 11080 Part 3: Commands 11082 11083 18 11084 11085 Trusted Platform Module Library 11086 11087 Random Number Generator 11088 11089 18.1 11090 11091 TPM2_GetRandom 11092 11093 18.1.1 General Description 11094 This command returns the next bytesRequested octets from the random number generator (RNG). 11095 NOTE 1 11096 11097 It is recommended that a TPM implement the RNG in a manner that would allow it to return RNG 11098 octets such that the frequency of bytesRequested being more than the number of octets available is 11099 an infrequent occurrence. 11100 11101 If bytesRequested is more than will fit into a TPM2B_DIGEST on the TPM, no error is returned but the 11102 TPM will only return as much data as will fit into a TPM2B_DIGEST buffer for the TPM. 11103 NOTE 2 11104 11105 TPM2B_DIGEST is large enough to hold the largest digest that may be produced by the TPM. 11106 Because that digest size changes according to the implemented hashes, the maximum amount of 11107 data returned by this command is TPM implementation-dependent. 11108 11109 Page 126 11110 October 31, 2013 11111 11112 Published 11113 Copyright TCG 2006-2013 11114 11115 Family 2.0 11116 Level 00 Revision 00.99 11117 11118 Trusted Platform Module Library 11120 11121 Part 3: Commands 11122 11123 18.1.2 Command and Response 11124 Table 62 TPM2_GetRandom Command 11125 Type 11126 11127 Name 11128 11129 Description 11130 11131 TPMI_ST_COMMAND_TAG 11132 11133 tag 11134 11135 UINT32 11136 11137 commandSize 11138 11139 TPM_CC 11140 11141 commandCode 11142 11143 TPM_CC_GetRandom 11144 11145 UINT16 11146 11147 bytesRequested 11148 11149 number of octets to return 11150 11151 Table 63 TPM2_GetRandom Response 11152 Type 11153 11154 Name 11155 11156 Description 11157 11158 TPM_ST 11159 11160 tag 11161 11162 see clause 8 11163 11164 UINT32 11165 11166 responseSize 11167 11168 TPM_RC 11169 11170 responseCode 11171 11172 TPM2B_DIGEST 11173 11174 randomBytes 11175 11176 Family 2.0 11177 Level 00 Revision 00.99 11178 11179 the random octets 11180 11181 Published 11182 Copyright TCG 2006-2013 11183 11184 Page 127 11185 October 31, 2013 11186 11187 Part 3: Commands 11189 11190 Trusted Platform Module Library 11191 11192 18.1.3 Detailed Actions 11193 1 11194 2 11195 3 11196 4 11197 5 11198 6 11199 7 11200 8 11201 9 11202 10 11203 11 11204 12 11205 13 11206 14 11207 15 11208 16 11209 17 11210 18 11211 19 11212 20 11213 21 11214 11215 #include "InternalRoutines.h" 11216 #include "GetRandom_fp.h" 11217 11218 TPM_RC 11219 TPM2_GetRandom( 11220 GetRandom_In 11221 GetRandom_Out 11222 11223 *in, 11224 *out 11225 11226 // IN: input parameter list 11227 // OUT: output parameter list 11228 11229 ) 11230 { 11231 // Command Output 11232 // if the requested bytes exceed the output buffer size, generates the 11233 // maximum bytes that the output buffer allows 11234 if(in->bytesRequested > sizeof(TPMU_HA)) 11235 out->randomBytes.t.size = sizeof(TPMU_HA); 11236 else 11237 out->randomBytes.t.size = in->bytesRequested; 11238 CryptGenerateRandom(out->randomBytes.t.size, out->randomBytes.t.buffer); 11239 return TPM_RC_SUCCESS; 11240 } 11241 11242 Page 128 11243 October 31, 2013 11244 11245 Published 11246 Copyright TCG 2006-2013 11247 11248 Family 2.0 11249 Level 00 Revision 00.99 11250 11251 Trusted Platform Module Library 11253 11254 18.2 11255 11256 Part 3: Commands 11257 11258 TPM2_StirRandom 11259 11260 18.2.1 General Description 11261 This command is used to add "additional information" to the RNG state. 11262 NOTE 11263 11264 The "additional information" is as defined in SP800 -90A. 11265 11266 The inData parameter may not be larger than 128 octets. 11267 11268 Family 2.0 11269 Level 00 Revision 00.99 11270 11271 Published 11272 Copyright TCG 2006-2013 11273 11274 Page 129 11275 October 31, 2013 11276 11277 Part 3: Commands 11279 11280 Trusted Platform Module Library 11281 11282 18.2.2 Command and Response 11283 Table 64 TPM2_StirRandom Command 11284 Type 11285 11286 Name 11287 11288 Description 11289 11290 TPMI_ST_COMMAND_TAG 11291 11292 tag 11293 11294 UINT32 11295 11296 commandSize 11297 11298 TPM_CC 11299 11300 commandCode 11301 11302 TPM_CC_StirRandom {NV} 11303 11304 TPM2B_SENSITIVE_DATA 11305 11306 inData 11307 11308 additional information 11309 11310 Table 65 TPM2_StirRandom Response 11311 Type 11312 11313 Name 11314 11315 Description 11316 11317 TPM_ST 11318 11319 tag 11320 11321 see clause 8 11322 11323 UINT32 11324 11325 responseSize 11326 11327 TPM_RC 11328 11329 responseCode 11330 11331 Page 130 11332 October 31, 2013 11333 11334 Published 11335 Copyright TCG 2006-2013 11336 11337 Family 2.0 11338 Level 00 Revision 00.99 11339 11340 Trusted Platform Module Library 11342 11343 Part 3: Commands 11344 11345 18.2.3 Detailed Actions 11346 1 11347 2 11348 3 11349 4 11350 5 11351 6 11352 7 11353 8 11354 9 11355 10 11356 11 11357 12 11358 11359 #include "InternalRoutines.h" 11360 #include "StirRandom_fp.h" 11361 11362 TPM_RC 11363 TPM2_StirRandom( 11364 StirRandom_In 11365 *in 11366 // IN: input parameter list 11367 ) 11368 { 11369 // Internal Data Update 11370 CryptStirRandom(in->inData.t.size, in->inData.t.buffer); 11371 return TPM_RC_SUCCESS; 11372 } 11373 11374 Family 2.0 11375 Level 00 Revision 00.99 11376 11377 Published 11378 Copyright TCG 2006-2013 11379 11380 Page 131 11381 October 31, 2013 11382 11383 Part 3: Commands 11385 11386 19 11387 11388 Trusted Platform Module Library 11389 11390 Hash/HMAC/Event Sequences 11391 11392 19.1 11393 11394 Introduction 11395 11396 All of the commands in this group are to support sequences for which an intermediate state must be 11397 maintained. For a description of sequences, see Hash, HMAC, and Event Sequences in Part 1. 11398 19.2 11399 11400 TPM2_HMAC_Start 11401 11402 19.2.1 General Description 11403 This command starts an HMAC sequence. The TPM will create and initialize an HMAC sequence 11404 structure, assign a handle to the sequence, and set the authValue of the sequence object to the value in 11405 auth. 11406 NOTE 1 11407 11408 The structure of a sequence object is vendor -dependent. 11409 11410 The caller shall provide proper authorization for use of handle. 11411 If the sign attribute is not SET in the key referenced by handle then the TPM shall return 11412 TPM_RC_ATTRIBUTES. If the key type is not TPM_ALG_KEYEDHASH then the TPM shall return 11413 TPM_RC_TYPE. 11414 If handle references a restricted key, then the hash algorithm specified in the key's scheme is used as the 11415 hash algorithm for the HMAC and the TPM shall return TPM_RC_VALUE if hashAlg is not 11416 TPM_ALG_NULL or the same algorithm in the key's scheme. 11417 If the key referenced by handle is not restricted, then the TPM will use hashAlg for the HMAC; unless 11418 hashAlg is TPM_ALG_NULL in which case it will use the default scheme of the key. 11419 Table 66 Hash Selection Matrix 11420 handlerestricted 11421 (key's restricted 11422 attribute) 11423 11424 handlescheme 11425 (hash algorithm 11426 from key's scheme) 11427 11428 CLEAR (unrestricted) 11429 11430 TPM_ALG_NULL 11431 11432 CLEAR 11433 11434 dont care 11435 11436 CLEAR 11437 11438 valid hash 11439 11440 hash used 11441 11442 TPM_ALG_NULL 11443 11444 error 11445 11446 valid hash 11447 11448 (1) 11449 11450 hashAlg 11451 11452 hashAlg 11453 11454 (2) 11455 11456 (TPM_RC_SCHEME) 11457 11458 TPM_ALG_NULL 11459 11460 handlescheme 11461 11462 same as handlescheme 11463 11464 handlescheme 11465 11466 (3) 11467 11468 SET 11469 11470 handlescheme 11471 11472 (3) 11473 11474 SET (restricted) 11475 11476 TPM_ALG_NULL 11477 11478 (3) 11479 11480 not same as 11481 handlescheme 11482 11483 error 11484 11485 valid hash 11486 valid hash 11487 11488 SET 11489 11490 valid hash 11491 11492 (4) 11493 11494 (TPM_RC_SCHEME) 11495 11496 NOTES: 11497 1) 11498 11499 The scheme for the handle may only be TPM_ALG_NULL if both sign and decrypt are SET. 11500 11501 2) 11502 11503 A hash algorithm is required for the HMAC. 11504 11505 3) 11506 11507 A restricted key is required to have a scheme with a valid hash algorithm. A restricted key may not have both sign and 11508 decrypt SET. 11509 11510 4) 11511 11512 The scheme for a restricted key cannot be overridden. 11513 11514 Page 132 11515 October 31, 2013 11516 11517 Published 11518 Copyright TCG 2006-2013 11519 11520 Family 2.0 11521 Level 00 Revision 00.99 11522 11523 Trusted Platform Module Library 11525 11526 Part 3: Commands 11527 11528 19.2.2 Command and Response 11529 Table 67 TPM2_HMAC_Start Command 11530 Type 11531 11532 Name 11533 11534 Description 11535 11536 TPMI_ST_COMMAND_TAG 11537 11538 tag 11539 11540 UINT32 11541 11542 commandSize 11543 11544 TPM_CC 11545 11546 commandCode 11547 11548 TPM_CC_HMAC_Start 11549 11550 TPMI_DH_OBJECT 11551 11552 @handle 11553 11554 handle of an HMAC key 11555 Auth Index: 1 11556 Auth Role: USER 11557 11558 TPM2B_AUTH 11559 11560 auth 11561 11562 authorization value for subsequent use of the sequence 11563 11564 TPMI_ALG_HASH+ 11565 11566 hashAlg 11567 11568 the hash algorithm to use for the HMAC 11569 11570 Table 68 TPM2_HMAC_Start Response 11571 Type 11572 11573 Name 11574 11575 Description 11576 11577 TPM_ST 11578 11579 tag 11580 11581 see clause 8 11582 11583 UINT32 11584 11585 responseSize 11586 11587 TPM_RC 11588 11589 responseCode 11590 11591 TPMI_DH_OBJECT 11592 11593 sequenceHandle 11594 11595 Family 2.0 11596 Level 00 Revision 00.99 11597 11598 a handle to reference the sequence 11599 11600 Published 11601 Copyright TCG 2006-2013 11602 11603 Page 133 11604 October 31, 2013 11605 11606 Part 3: Commands 11608 11609 Trusted Platform Module Library 11610 11611 19.2.3 Detailed Actions 11612 1 11613 2 11614 11615 #include "InternalRoutines.h" 11616 #include "HMAC_Start_fp.h" 11617 Error Returns 11618 TPM_RC_ATTRIBUTES 11619 11620 key referenced by handle is not a signing key 11621 11622 TPM_RC_OBJECT_MEMORY 11623 11624 no space to create an internal object 11625 11626 TPM_RC_TYPE 11627 11628 key referenced by handle is not an HMAC key 11629 11630 TPM_RC_VALUE 11631 11632 3 11633 4 11634 5 11635 6 11636 7 11637 8 11638 9 11639 10 11640 11 11641 12 11642 13 11643 14 11644 15 11645 16 11646 17 11647 18 11648 19 11649 20 11650 21 11651 22 11652 23 11653 24 11654 25 11655 26 11656 27 11657 28 11658 29 11659 30 11660 31 11661 32 11662 33 11663 34 11664 35 11665 36 11666 37 11667 38 11668 39 11669 40 11670 41 11671 42 11672 43 11673 44 11674 45 11675 46 11676 47 11677 11678 Meaning 11679 11680 hashAlg specified when the key is restricted is neither 11681 TPM_ALG_NULL not equal to that of the key scheme; or both 11682 hashAlg and the key scheme's algorithm are TPM_ALG_NULL 11683 11684 TPM_RC 11685 TPM2_HMAC_Start( 11686 HMAC_Start_In 11687 HMAC_Start_Out 11688 11689 *in, 11690 *out 11691 11692 // IN: input parameter list 11693 // OUT: output parameter list 11694 11695 ) 11696 { 11697 OBJECT 11698 TPMT_PUBLIC 11699 TPM_ALG_ID 11700 11701 *hmacObject; 11702 *publicArea; 11703 hashAlg; 11704 11705 // Input Validation 11706 // Get HMAC key object and public area pointers 11707 hmacObject = ObjectGet(in->handle); 11708 publicArea = &hmacObject->publicArea; 11709 // Make sure that the key is an HMAC signing key 11710 if(publicArea->type != TPM_ALG_KEYEDHASH) 11711 return TPM_RC_TYPE + RC_HMAC_Start_handle; 11712 if(publicArea->objectAttributes.sign != SET) 11713 return TPM_RC_ATTRIBUTES + RC_HMAC_Start_handle; 11714 // Assume that the key default scheme is used 11715 hashAlg = publicArea->parameters.keyedHashDetail.scheme.details.hmac.hashAlg; 11716 // if the key is restricted, then need to use the scheme of the key and the 11717 // input algorithm must be TPM_ALG_NULL or the same as the key scheme 11718 if(publicArea->objectAttributes.restricted == SET) 11719 { 11720 if(in->hashAlg != TPM_ALG_NULL && in->hashAlg != hashAlg) 11721 hashAlg = TPM_ALG_NULL; 11722 } 11723 else 11724 { 11725 // for a non-restricted key, use hashAlg if it is provided; 11726 if(in->hashAlg != TPM_ALG_NULL) 11727 hashAlg = in->hashAlg; 11728 } 11729 // if the algorithm selection ended up with TPM_ALG_NULL, then either the 11730 // schemes are not compatible or no hash was provided and both conditions 11731 // are errors. 11732 if(hashAlg == TPM_ALG_NULL) 11733 return TPM_RC_VALUE + RC_HMAC_Start_hashAlg; 11734 // Internal Data Update 11735 11736 Page 134 11737 October 31, 2013 11738 11739 Published 11740 Copyright TCG 2006-2013 11741 11742 Family 2.0 11743 Level 00 Revision 00.99 11744 11745 Trusted Platform Module Library 11747 48 11748 49 11749 50 11750 51 11751 52 11752 53 11753 54 11754 55 11755 11756 Part 3: Commands 11757 11758 // Create a HMAC sequence object. A TPM_RC_OBJECT_MEMORY error may be 11759 // returned at this point 11760 return ObjectCreateHMACSequence(hashAlg, 11761 in->handle, 11762 &in->auth, 11763 &out->sequenceHandle); 11764 } 11765 11766 Family 2.0 11767 Level 00 Revision 00.99 11768 11769 Published 11770 Copyright TCG 2006-2013 11771 11772 Page 135 11773 October 31, 2013 11774 11775 Part 3: Commands 11777 11778 19.3 11779 11780 Trusted Platform Module Library 11781 11782 TPM2_HashSequenceStart 11783 11784 19.3.1 General Description 11785 This command starts a hash or an Event sequence. If hashAlg is an implemented hash, then a hash 11786 sequence is started. If hashAlg is TPM_ALG_NULL, then an Event sequence is started. If hashAlg is 11787 neither an implemented algorithm nor TPM_ALG_NULL, then the TPM shall return TPM_RC_HASH. 11788 Depending on hashAlg, the TPM will create and initialize a hash sequence structure or an Event 11789 sequence structure. Additionally, it will assign a handle to the sequence and set the authValue of the 11790 sequence to the value in auth. A sequence structure for an Event (hashAlg = TPM_ALG_NULL) contains 11791 a hash context for each of the PCR banks implemented on the TPM. 11792 11793 Page 136 11794 October 31, 2013 11795 11796 Published 11797 Copyright TCG 2006-2013 11798 11799 Family 2.0 11800 Level 00 Revision 00.99 11801 11802 Trusted Platform Module Library 11804 11805 Part 3: Commands 11806 11807 19.3.2 Command and Response 11808 Table 69 TPM2_HashSequenceStart Command 11809 Type 11810 11811 Name 11812 11813 Description 11814 11815 TPMI_ST_COMMAND_TAG 11816 11817 tag 11818 11819 UINT32 11820 11821 commandSize 11822 11823 TPM_CC 11824 11825 commandCode 11826 11827 TPM_CC_HashSequenceStart 11828 11829 TPM2B_AUTH 11830 11831 auth 11832 11833 authorization value for subsequent use of the sequence 11834 11835 TPMI_ALG_HASH+ 11836 11837 hashAlg 11838 11839 the hash algorithm to use for the hash sequence 11840 An Event sequence starts if this is TPM_ALG_NULL. 11841 11842 Table 70 TPM2_HashSequenceStart Response 11843 Type 11844 11845 Name 11846 11847 Description 11848 11849 TPM_ST 11850 11851 tag 11852 11853 see clause 8 11854 11855 UINT32 11856 11857 responseSize 11858 11859 TPM_RC 11860 11861 responseCode 11862 11863 TPMI_DH_OBJECT 11864 11865 sequenceHandle 11866 11867 Family 2.0 11868 Level 00 Revision 00.99 11869 11870 a handle to reference the sequence 11871 11872 Published 11873 Copyright TCG 2006-2013 11874 11875 Page 137 11876 October 31, 2013 11877 11878 Part 3: Commands 11880 11881 Trusted Platform Module Library 11882 11883 19.3.3 Detailed Actions 11884 1 11885 2 11886 11887 #include "InternalRoutines.h" 11888 #include "HashSequenceStart_fp.h" 11889 Error Returns 11890 TPM_RC_OBJECT_MEMORY 11891 11892 3 11893 4 11894 5 11895 6 11896 7 11897 8 11898 9 11899 10 11900 11 11901 12 11902 13 11903 14 11904 15 11905 16 11906 17 11907 18 11908 19 11909 11910 Meaning 11911 no space to create an internal object 11912 11913 TPM_RC 11914 TPM2_HashSequenceStart( 11915 HashSequenceStart_In 11916 HashSequenceStart_Out 11917 11918 *in, 11919 *out 11920 11921 // IN: input parameter list 11922 // OUT: output parameter list 11923 11924 ) 11925 { 11926 // Internal Data Update 11927 if(in->hashAlg == TPM_ALG_NULL) 11928 // Start a event sequence. A TPM_RC_OBJECT_MEMORY error may be 11929 // returned at this point 11930 return ObjectCreateEventSequence(&in->auth, &out->sequenceHandle); 11931 // Start a hash sequence. A TPM_RC_OBJECT_MEMORY error may be 11932 // returned at this point 11933 return ObjectCreateHashSequence(in->hashAlg, &in->auth, &out->sequenceHandle); 11934 } 11935 11936 Page 138 11937 October 31, 2013 11938 11939 Published 11940 Copyright TCG 2006-2013 11941 11942 Family 2.0 11943 Level 00 Revision 00.99 11944 11945 Trusted Platform Module Library 11947 11948 19.4 11949 11950 Part 3: Commands 11951 11952 TPM2_SequenceUpdate 11953 11954 19.4.1 General Description 11955 This command is used to add data to a hash or HMAC sequence. The amount of data in buffer may be 11956 any size up to the limits of the TPM. 11957 NOTE 11958 11959 In all TPM, a buffer size of 1,024 octets is allowed. 11960 11961 Proper authorization for the sequence object associated with sequenceHandle is required. If an 11962 authorization or audit of this command requires computation of a cpHash and an rpHash, the Name 11963 associated with sequenceHandle will be the Empty Buffer. 11964 If the command does not return TPM_RC_SUCCESS, the state of the sequence is unmodified. 11965 If the sequence is intended to produce a digest that will be signed by a restricted signing key, then the 11966 first block of data shall contain sizeof(TPM_GENERATED) octets and the first octets shall not be 11967 TPM_GENERATED_VALUE. 11968 NOTE 11969 11970 This requirement allows the TPM to validate that the first block is safe to sign without having to 11971 accumulate octets over multiple calls. 11972 11973 Family 2.0 11974 Level 00 Revision 00.99 11975 11976 Published 11977 Copyright TCG 2006-2013 11978 11979 Page 139 11980 October 31, 2013 11981 11982 Part 3: Commands 11984 11985 Trusted Platform Module Library 11986 11987 19.4.2 Command and Response 11988 Table 71 TPM2_SequenceUpdate Command 11989 Type 11990 11991 Name 11992 11993 Description 11994 11995 TPMI_ST_COMMAND_TAG 11996 11997 tag 11998 11999 UINT32 12000 12001 commandSize 12002 12003 TPM_CC 12004 12005 commandCode 12006 12007 TPM_CC_SequenceUpdate 12008 12009 TPMI_DH_OBJECT 12010 12011 @sequenceHandle 12012 12013 handle for the sequence object 12014 Auth Index: 1 12015 Auth Role: USER 12016 12017 TPM2B_MAX_BUFFER 12018 12019 buffer 12020 12021 data to be added to hash 12022 12023 Table 72 TPM2_SequenceUpdate Response 12024 Type 12025 12026 Name 12027 12028 Description 12029 12030 TPM_ST 12031 12032 tag 12033 12034 see clause 8 12035 12036 UINT32 12037 12038 responseSize 12039 12040 TPM_RC 12041 12042 responseCode 12043 12044 Page 140 12045 October 31, 2013 12046 12047 Published 12048 Copyright TCG 2006-2013 12049 12050 Family 2.0 12051 Level 00 Revision 00.99 12052 12053 Trusted Platform Module Library 12055 12056 Part 3: Commands 12057 12058 19.4.3 Detailed Actions 12059 1 12060 2 12061 12062 #include "InternalRoutines.h" 12063 #include "SequenceUpdate_fp.h" 12064 Error Returns 12065 TPM_RC_MODE 12066 12067 3 12068 4 12069 5 12070 6 12071 7 12072 8 12073 9 12074 10 12075 11 12076 12 12077 13 12078 14 12079 15 12080 16 12081 17 12082 18 12083 19 12084 20 12085 21 12086 22 12087 23 12088 24 12089 25 12090 26 12091 27 12092 28 12093 29 12094 30 12095 31 12096 32 12097 33 12098 34 12099 35 12100 36 12101 37 12102 38 12103 39 12104 40 12105 41 12106 42 12107 43 12108 44 12109 45 12110 46 12111 47 12112 48 12113 49 12114 50 12115 51 12116 52 12117 53 12118 12119 Meaning 12120 sequenceHandle does not reference a hash or HMAC sequence 12121 object 12122 12123 TPM_RC 12124 TPM2_SequenceUpdate( 12125 SequenceUpdate_In 12126 12127 *in 12128 12129 // IN: input parameter list 12130 12131 ) 12132 { 12133 OBJECT 12134 12135 *object; 12136 12137 // Input Validation 12138 // Get sequence object pointer 12139 object = ObjectGet(in->sequenceHandle); 12140 // Check that referenced object is a sequence object. 12141 if(!ObjectIsSequence(object)) 12142 return TPM_RC_MODE + RC_SequenceUpdate_sequenceHandle; 12143 // Internal Data Update 12144 if(object->attributes.eventSeq == SET) 12145 { 12146 // Update event sequence object 12147 UINT32 12148 i; 12149 HASH_OBJECT 12150 *hashObject = (HASH_OBJECT *)object; 12151 for(i = 0; i < HASH_COUNT; i++) 12152 { 12153 // Update sequence object 12154 CryptUpdateDigest2B(&hashObject->state.hashState[i], &in->buffer.b); 12155 } 12156 } 12157 else 12158 { 12159 HASH_OBJECT 12160 *hashObject = (HASH_OBJECT *)object; 12161 // Update hash/HMAC sequence object 12162 if(hashObject->attributes.hashSeq == SET) 12163 { 12164 // Is this the first block of the sequence 12165 if(hashObject->attributes.firstBlock == CLEAR) 12166 { 12167 // If so, indicate that first block was received 12168 hashObject->attributes.firstBlock = SET; 12169 // Check the first block to see if the first block can contain 12170 // the TPM_GENERATED_VALUE. If it does, it is not safe for 12171 // a ticket. 12172 if(TicketIsSafe(&in->buffer.b)) 12173 hashObject->attributes.ticketSafe = SET; 12174 } 12175 // Update sequence object hash/HMAC stack 12176 CryptUpdateDigest2B(&hashObject->state.hashState[0], &in->buffer.b); 12177 12178 Family 2.0 12179 Level 00 Revision 00.99 12180 12181 Published 12182 Copyright TCG 2006-2013 12183 12184 Page 141 12185 October 31, 2013 12186 12187 Part 3: Commands 12189 54 12190 55 12191 56 12192 57 12193 58 12194 59 12195 60 12196 61 12197 62 12198 63 12199 64 12200 65 12201 12202 Trusted Platform Module Library 12203 12204 } 12205 else if(object->attributes.hmacSeq == SET) 12206 { 12207 HASH_OBJECT 12208 *hashObject = (HASH_OBJECT *)object; 12209 // Update sequence object hash/HMAC stack 12210 CryptUpdateDigest2B(&hashObject->state.hmacState, &in->buffer.b); 12211 } 12212 } 12213 return TPM_RC_SUCCESS; 12214 } 12215 12216 Page 142 12217 October 31, 2013 12218 12219 Published 12220 Copyright TCG 2006-2013 12221 12222 Family 2.0 12223 Level 00 Revision 00.99 12224 12225 Trusted Platform Module Library 12227 12228 19.5 12229 12230 Part 3: Commands 12231 12232 TPM2_SequenceComplete 12233 12234 19.5.1 General Description 12235 This command adds the last part of data, if any, to a hash/HMAC sequence and returns the result. 12236 NOTE 1 12237 12238 This command is not used to complete an Event sequence. TPM2_EventSequenceComplete() is 12239 used for that purpose. 12240 12241 For a hash sequence, if the results of the hash will be used in a signing operation that uses a restricted 12242 signing key, then the ticket returned by this command can indicate that the hash is safe to sign. 12243 If the digest is not safe to sign, then validation will be a TPMT_TK_HASHCHECK with the hierarchy set to 12244 TPM_RH_NULL and digest set to the Empty Buffer. 12245 NOTE 2 12246 12247 Regardless of the contents of the first octets of the hashed message, if the first buffer sent to the 12248 TPM had fewer than sizeof(TPM_GENERATED) octets, then the TPM will operate as if digest is not 12249 safe to sign. 12250 12251 If sequenceHandle references an Event sequence, then the TPM shall return TPM_RC_MODE. 12252 Proper authorization for the sequence object associated with sequenceHandle is required. If an 12253 authorization or audit of this command requires computation of a cpHash and an rpHash, the Name 12254 associated with sequenceHandle will be the Empty Buffer. 12255 If this command completes successfully, the sequenceHandle object will be flushed. 12256 12257 Family 2.0 12258 Level 00 Revision 00.99 12259 12260 Published 12261 Copyright TCG 2006-2013 12262 12263 Page 143 12264 October 31, 2013 12265 12266 Part 3: Commands 12268 12269 Trusted Platform Module Library 12270 12271 19.5.2 Command and Response 12272 Table 73 TPM2_SequenceComplete Command 12273 Type 12274 12275 Name 12276 12277 Description 12278 12279 TPMI_ST_COMMAND_TAG 12280 12281 tag 12282 12283 UINT32 12284 12285 commandSize 12286 12287 TPM_CC 12288 12289 commandCode 12290 12291 TPM_CC_SequenceComplete {F} 12292 12293 TPMI_DH_OBJECT 12294 12295 @sequenceHandle 12296 12297 authorization for the sequence 12298 Auth Index: 1 12299 Auth Role: USER 12300 12301 TPM2B_MAX_BUFFER 12302 12303 buffer 12304 12305 data to be added to the hash/HMAC 12306 12307 TPMI_RH_HIERARCHY+ 12308 12309 hierarchy 12310 12311 hierarchy of the ticket for a hash 12312 12313 Table 74 TPM2_SequenceComplete Response 12314 Type 12315 12316 Name 12317 12318 Description 12319 12320 TPM_ST 12321 12322 tag 12323 12324 see clause 8 12325 12326 UINT32 12327 12328 responseSize 12329 12330 TPM_RC 12331 12332 responseCode 12333 12334 TPM2B_DIGEST 12335 12336 result 12337 12338 the returned HMAC or digest in a sized buffer 12339 12340 validation 12341 12342 ticket indicating that the sequence of octets used to 12343 compute outDigest did not start with 12344 TPM_GENERATED_VALUE 12345 This is a NULL Ticket when the session is HMAC. 12346 12347 TPMT_TK_HASHCHECK 12348 12349 Page 144 12350 October 31, 2013 12351 12352 Published 12353 Copyright TCG 2006-2013 12354 12355 Family 2.0 12356 Level 00 Revision 00.99 12357 12358 Trusted Platform Module Library 12360 12361 Part 3: Commands 12362 12363 19.5.3 Detailed Actions 12364 1 12365 2 12366 3 12367 12368 #include "InternalRoutines.h" 12369 #include "SequenceComplete_fp.h" 12370 #include <Platform.h> 12371 Error Returns 12372 TPM_RC_TYPE 12373 12374 4 12375 5 12376 6 12377 7 12378 8 12379 9 12380 10 12381 11 12382 12 12383 13 12384 14 12385 15 12386 16 12387 17 12388 18 12389 19 12390 20 12391 21 12392 22 12393 23 12394 24 12395 25 12396 26 12397 27 12398 28 12399 29 12400 30 12401 31 12402 32 12403 33 12404 34 12405 35 12406 36 12407 37 12408 38 12409 39 12410 40 12411 41 12412 42 12413 43 12414 44 12415 45 12416 46 12417 47 12418 48 12419 49 12420 50 12421 51 12422 52 12423 53 12424 12425 Meaning 12426 sequenceHandle does not reference a hash or HMAC sequence 12427 object 12428 12429 TPM_RC 12430 TPM2_SequenceComplete( 12431 SequenceComplete_In 12432 SequenceComplete_Out 12433 12434 *in, 12435 *out 12436 12437 OBJECT 12438 12439 // IN: input parameter list 12440 // OUT: output parameter list 12441 12442 *object; 12443 12444 ) 12445 { 12446 // Input validation 12447 // Get hash object pointer 12448 object = ObjectGet(in->sequenceHandle); 12449 // input handle must be a hash or HMAC sequence object. 12450 if( 12451 object->attributes.hashSeq == CLEAR 12452 && object->attributes.hmacSeq == CLEAR) 12453 return TPM_RC_MODE + RC_SequenceComplete_sequenceHandle; 12454 // Command Output 12455 if(object->attributes.hashSeq == SET) 12456 // sequence object for hash 12457 { 12458 // Update last piece of data 12459 HASH_OBJECT 12460 *hashObject = (HASH_OBJECT *)object; 12461 CryptUpdateDigest2B(&hashObject->state.hashState[0], &in->buffer.b); 12462 // Complete hash 12463 out->result.t.size 12464 = CryptGetHashDigestSize( 12465 CryptGetContextAlg(&hashObject->state.hashState[0])); 12466 CryptCompleteHash2B(&hashObject->state.hashState[0], &out->result.b); 12467 // Check if the first block of the sequence has been received 12468 if(hashObject->attributes.firstBlock == CLEAR) 12469 { 12470 // If not, then this is the first block so see if it is 'safe' 12471 // to sign. 12472 if(TicketIsSafe(&in->buffer.b)) 12473 hashObject->attributes.ticketSafe = SET; 12474 } 12475 // Output ticket 12476 out->validation.tag = TPM_ST_HASHCHECK; 12477 out->validation.hierarchy = in->hierarchy; 12478 if(in->hierarchy == TPM_RH_NULL) 12479 { 12480 // Ticket is not required 12481 out->validation.digest.t.size = 0; 12482 12483 Family 2.0 12484 Level 00 Revision 00.99 12485 12486 Published 12487 Copyright TCG 2006-2013 12488 12489 Page 145 12490 October 31, 2013 12491 12492 Part 3: Commands 12494 54 12495 55 12496 56 12497 57 12498 58 12499 59 12500 60 12501 61 12502 62 12503 63 12504 64 12505 65 12506 66 12507 67 12508 68 12509 69 12510 70 12511 71 12512 72 12513 73 12514 74 12515 75 12516 76 12517 77 12518 78 12519 79 12520 80 12521 81 12522 82 12523 83 12524 84 12525 85 12526 86 12527 87 12528 88 12529 89 12530 90 12531 91 12532 92 12533 12534 Trusted Platform Module Library 12535 12536 } 12537 else if(object->attributes.ticketSafe == CLEAR) 12538 { 12539 // Ticket is not safe to generate 12540 out->validation.hierarchy = TPM_RH_NULL; 12541 out->validation.digest.t.size = 0; 12542 } 12543 else 12544 { 12545 // Compute ticket 12546 TicketComputeHashCheck(out->validation.hierarchy, 12547 &out->result, &out->validation); 12548 } 12549 } 12550 else 12551 { 12552 HASH_OBJECT 12553 12554 *hashObject = (HASH_OBJECT *)object; 12555 12556 // 12557 Update last piece of data 12558 CryptUpdateDigest2B(&hashObject->state.hmacState, &in->buffer.b); 12559 // Complete hash/HMAC 12560 out->result.t.size = 12561 CryptGetHashDigestSize( 12562 CryptGetContextAlg(&hashObject->state.hmacState.hashState)); 12563 CryptCompleteHMAC2B(&(hashObject->state.hmacState), &out->result.b); 12564 // No ticket is generated for HMAC sequence 12565 out->validation.tag = TPM_ST_HASHCHECK; 12566 out->validation.hierarchy = TPM_RH_NULL; 12567 out->validation.digest.t.size = 0; 12568 } 12569 // Internal Data Update 12570 // mark sequence object as evict so it will be flushed on the way out 12571 object->attributes.evict = SET; 12572 return TPM_RC_SUCCESS; 12573 } 12574 12575 Page 146 12576 October 31, 2013 12577 12578 Published 12579 Copyright TCG 2006-2013 12580 12581 Family 2.0 12582 Level 00 Revision 00.99 12583 12584 Trusted Platform Module Library 12586 12587 19.6 12588 12589 Part 3: Commands 12590 12591 TPM2_EventSequenceComplete 12592 12593 19.6.1 General Description 12594 This command adds the last part of data, if any, to an Event sequence and returns the result in a digest 12595 list. If pcrHandle references a PCR and not TPM_RH_NULL, then the returned digest list is processed in 12596 the same manner as the digest list input parameter to TPM2_PCR_Extend() with the pcrHandle in each 12597 bank extended with the associated digest value. 12598 If sequenceHandle references a hash or HMAC sequence, the TPM shall return TPM_RC_MODE. 12599 Proper authorization for the sequence object associated with sequenceHandle is required. If an 12600 authorization or audit of this command requires computation of a cpHash and an rpHash, the Name 12601 associated with sequenceHandle will be the Empty Buffer. 12602 If this command completes successfully, the sequenceHandle object will be flushed. 12603 12604 Family 2.0 12605 Level 00 Revision 00.99 12606 12607 Published 12608 Copyright TCG 2006-2013 12609 12610 Page 147 12611 October 31, 2013 12612 12613 Part 3: Commands 12615 12616 Trusted Platform Module Library 12617 12618 19.6.2 Command and Response 12619 Table 75 TPM2_EventSequenceComplete Command 12620 Type 12621 12622 Name 12623 12624 TPMI_ST_COMMAND_TAG 12625 12626 tag 12627 12628 UINT32 12629 12630 commandSize 12631 12632 TPM_CC 12633 12634 commandCode 12635 12636 TPM_CC_EventSequenceComplete {NV F} 12637 12638 @ pcrHandle 12639 12640 PCR to be extended with the Event data 12641 Auth Index: 1 12642 Auth Role: USER 12643 12644 TPMI_DH_OBJECT 12645 12646 @sequenceHandle 12647 12648 authorization for the sequence 12649 Auth Index: 2 12650 Auth Role: USER 12651 12652 TPM2B_MAX_BUFFER 12653 12654 buffer 12655 12656 data to be added to the Event 12657 12658 TPMI_DH_PCR+ 12659 12660 Description 12661 12662 Table 76 TPM2_EventSequenceComplete Response 12663 Type 12664 12665 Name 12666 12667 Description 12668 12669 TPM_ST 12670 12671 tag 12672 12673 see clause 8 12674 12675 UINT32 12676 12677 responseSize 12678 12679 TPM_RC 12680 12681 responseCode 12682 12683 TPML_DIGEST_VALUES 12684 12685 results 12686 12687 Page 148 12688 October 31, 2013 12689 12690 list of digests computed for the PCR 12691 12692 Published 12693 Copyright TCG 2006-2013 12694 12695 Family 2.0 12696 Level 00 Revision 00.99 12697 12698 Trusted Platform Module Library 12700 12701 Part 3: Commands 12702 12703 19.6.3 Detailed Actions 12704 1 12705 2 12706 12707 #include "InternalRoutines.h" 12708 #include "EventSequenceComplete_fp.h" 12709 Error Returns 12710 TPM_RC_LOCALITY 12711 12712 PCR extension is not allowed at the current locality 12713 12714 TPM_RC_MODE 12715 3 12716 4 12717 5 12718 6 12719 7 12720 8 12721 9 12722 10 12723 11 12724 12 12725 13 12726 14 12727 15 12728 16 12729 17 12730 18 12731 19 12732 20 12733 21 12734 22 12735 23 12736 24 12737 25 12738 26 12739 27 12740 28 12741 29 12742 30 12743 31 12744 32 12745 33 12746 34 12747 35 12748 36 12749 37 12750 38 12751 39 12752 40 12753 41 12754 42 12755 43 12756 44 12757 45 12758 46 12759 47 12760 48 12761 49 12762 50 12763 51 12764 52 12765 53 12766 12767 Meaning 12768 12769 input handle is not a valid event sequence object 12770 12771 TPM_RC 12772 TPM2_EventSequenceComplete( 12773 EventSequenceComplete_In 12774 EventSequenceComplete_Out 12775 12776 *in, 12777 *out 12778 12779 // IN: input parameter list 12780 // OUT: output parameter list 12781 12782 ) 12783 { 12784 TPM_RC 12785 HASH_OBJECT 12786 UINT32 12787 TPM_ALG_ID 12788 12789 result; 12790 *hashObject; 12791 i; 12792 hashAlg; 12793 12794 // Input validation 12795 // get the event sequence object pointer 12796 hashObject = (HASH_OBJECT *)ObjectGet(in->sequenceHandle); 12797 // input handle must reference an event sequence object 12798 if(hashObject->attributes.eventSeq != SET) 12799 return TPM_RC_MODE + RC_EventSequenceComplete_sequenceHandle; 12800 // see if a PCR extend is requested in call 12801 if(in->pcrHandle != TPM_RH_NULL) 12802 { 12803 // see if extend of the PCR is allowed at the locality of the command, 12804 if(!PCRIsExtendAllowed(in->pcrHandle)) 12805 return TPM_RC_LOCALITY; 12806 // if an extend is going to take place, then check to see if there has 12807 // been an orderly shutdown. If so, and the selected PCR is one of the 12808 // state saved PCR, then the orderly state has to change. The orderly state 12809 // does not change for PCR that are not preserved. 12810 // NOTE: This doesn't just check for Shutdown(STATE) because the orderly 12811 // state will have to change if this is a state-saved PCR regardless 12812 // of the current state. This is because a subsequent Shutdown(STATE) will 12813 // check to see if there was an orderly shutdown and not do anything if 12814 // there was. So, this must indicate that a future Shutdown(STATE) has 12815 // something to do. 12816 if(gp.orderlyState != SHUTDOWN_NONE && PCRIsStateSaved(in->pcrHandle)) 12817 { 12818 result = NvIsAvailable(); 12819 if(result != TPM_RC_SUCCESS) return result; 12820 g_clearOrderly = TRUE; 12821 } 12822 } 12823 // Command Output 12824 out->results.count = 0; 12825 for(i = 0; i < HASH_COUNT; i++) 12826 { 12827 hashAlg = CryptGetHashAlgByIndex(i); 12828 12829 Family 2.0 12830 Level 00 Revision 00.99 12831 12832 Published 12833 Copyright TCG 2006-2013 12834 12835 Page 149 12836 October 31, 2013 12837 12838 Part 3: Commands 12840 54 12841 55 12842 56 12843 57 12844 58 12845 59 12846 60 12847 61 12848 62 12849 63 12850 64 12851 65 12852 66 12853 67 12854 68 12855 69 12856 70 12857 71 12858 72 12859 73 12860 74 12861 75 12862 76 12863 12864 Trusted Platform Module Library 12865 12866 // Update last piece of data 12867 CryptUpdateDigest2B(&hashObject->state.hashState[i], &in->buffer.b); 12868 // Complete hash 12869 out->results.digests[out->results.count].hashAlg = hashAlg; 12870 CryptCompleteHash(&hashObject->state.hashState[i], 12871 CryptGetHashDigestSize(hashAlg), 12872 (BYTE *) &out->results.digests[out->results.count].digest); 12873 // Extend PCR 12874 if(in->pcrHandle != TPM_RH_NULL) 12875 PCRExtend(in->pcrHandle, hashAlg, 12876 CryptGetHashDigestSize(hashAlg), 12877 (BYTE *) &out->results.digests[out->results.count].digest); 12878 out->results.count++; 12879 } 12880 // Internal Data Update 12881 // mark sequence object as evict so it will be flushed on the way out 12882 hashObject->attributes.evict = SET; 12883 return TPM_RC_SUCCESS; 12884 } 12885 12886 Page 150 12887 October 31, 2013 12888 12889 Published 12890 Copyright TCG 2006-2013 12891 12892 Family 2.0 12893 Level 00 Revision 00.99 12894 12895 Trusted Platform Module Library 12897 12898 Part 3: Commands 12899 12900 Attestation Commands 12901 12902 20 12903 20.1 12904 12905 Introduction 12906 12907 The attestation commands cause the TPM to sign an internally generated data structure. The contents of 12908 the data structure vary according to the command. 12909 For all signing commands, provisions are made for the caller to provide a scheme to be used for the 12910 signing operation. This scheme will be applied only if the scheme of the key is TPM_ALG_NULL. If the 12911 scheme for signHandle is not TPM_ALG_NULL, then inScheme.scheme shall be TPM_ALG_NULL or the 12912 same as scheme in the public area of the key. If the scheme for signHandle is TPM_ALG_NULL, then 12913 inScheme will be used for the signing operation and may not be TPM_ALG_NULL. The TPM shall return 12914 TPM_RC_SCHEME to indicate that the scheme is not appropriate. 12915 For a signing key that is not restricted, the caller may specify the scheme to be used as long as the 12916 scheme is compatible with the family of the key (for example, TPM_ALG_RSAPSS cannot be selected for 12917 an ECC key). If the caller sets scheme to TPM_ALG_NULL, then the default scheme of the key is used. 12918 If the handle for the signing key (signHandle) is TPM_RH_NULL, then all of the actions of the command 12919 are performed and the attestation block is signed with the NULL Signature. 12920 NOTE 1 12921 12922 This mechanism is provided so that additional commands are not required to access the data that 12923 might be in an attestation structure. 12924 12925 NOTE 2 12926 12927 When signHandle is TPM_RH_NULL, scheme is still required to be a valid signing scheme (may be 12928 TPM_ALG_NULL), but the scheme will have no effect on the format of the signature. It will always 12929 be the NULL Signature. 12930 12931 TPM2_NV_Certify() is an attestation command that is documented in 1. The remaining attestation 12932 commands are collected in the remainder of this clause. 12933 Each of the attestation structures contains a TPMS_CLOCK_INFO structure and a firmware version 12934 number. These values may be considered privacy-sensitive, because they would aid in the correlation of 12935 attestations by different keys. To provide improved privacy, the resetCount, restartCount, and 12936 firmwareVersion numbers are obfuscated when the signing key is not in the Endorsement or Platform 12937 hierarchies. 12938 The obfuscation value is computed by: 12939 12940 obfuscation KDFa(signHandlenameAlg, shProof, OBFUSCATE, signHandleQN, 0, 128) (3) 12941 Of the returned 128 bits, 64 bits are added to the versionNumber field of the attestation structure; 32 bits 12942 are added to the clockInfo.resetCount and 32 bits are added to the clockInfo.restartCount. The order in 12943 which the bits are added is implementation-dependent. 12944 NOTE 3 12945 12946 The obfuscation value for each signing key will be unique to that key in a specific location. That is, 12947 each version of a duplicated signing key will have a different obfuscation value. 12948 12949 When the signing key is TPM_RH_NULL, the data structure is produced but not signed; and the values in 12950 the signed data structure are obfuscated. When computing the obfuscation value for TPM_RH_NULL, the 12951 hash used for context integrity is used. 12952 NOTE 4 12953 12954 The QN for TPM_RH_NULL is TPM_RH_NULL. 12955 12956 If the signing scheme of signHandle is an anonymous scheme, then the attestation blocks will not contain 12957 the Qualified Name of the signHandle. 12958 Each of the attestation structures allows the caller to provide some qualifying data (qualifyingData). For 12959 most signing schemes, this value will be placed in the TPMS_ATTEST.extraData parameter that is then 12960 12961 Family 2.0 12962 Level 00 Revision 00.99 12963 12964 Published 12965 Copyright TCG 2006-2013 12966 12967 Page 151 12968 October 31, 2013 12969 12970 Part 3: Commands 12972 12973 Trusted Platform Module Library 12974 12975 hashed and signed. However, for some schemes such as ECDAA, the qualifyingData is used in a 12976 different manner (for details, see ECDAA in Part 1). 12977 12978 Page 152 12979 October 31, 2013 12980 12981 Published 12982 Copyright TCG 2006-2013 12983 12984 Family 2.0 12985 Level 00 Revision 00.99 12986 12987 Trusted Platform Module Library 12989 12990 20.2 12991 12992 Part 3: Commands 12993 12994 TPM2_Certify 12995 12996 20.2.1 General Description 12997 The purpose of this command is to prove that an object with a specific Name is loaded in the TPM. By 12998 certifying 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 12999 same Name as a Name certified with this command, then the values in that public area are correct. 13000 NOTE 1 13001 13002 See 20.1 for description of how the signing scheme is selected. 13003 13004 Authorization for objectHandle requires ADMIN role authorization. If performed with a policy session, the 13005 session shall have a policySessioncommandCode set to TPM_CC_Certify. This indicates that the 13006 policy that is being used is a policy that is for certification, and not a policy that would approve another 13007 use. That is, authority to use an object does not grant authority to certify the object. 13008 The object may be any object that is loaded with TPM2_Load() or TPM2_CreatePrimary(). An object that 13009 only has its public area loaded cannot be certified. 13010 NOTE 2 13011 13012 The restriction occurs because the Name is used to identify the object being certified. If the TPM 13013 has not validated that the public area is associated with a matched sensitive area, then the public 13014 area may not represent a valid object a nd cannot be certified. 13015 13016 The certification includes the Name and Qualified Name of the certified object as well as the Name and 13017 the Qualified Name of the certifying object. 13018 13019 Family 2.0 13020 Level 00 Revision 00.99 13021 13022 Published 13023 Copyright TCG 2006-2013 13024 13025 Page 153 13026 October 31, 2013 13027 13028 Part 3: Commands 13030 13031 Trusted Platform Module Library 13032 13033 20.2.2 Command and Response 13034 Table 77 TPM2_Certify Command 13035 Type 13036 13037 Name 13038 13039 TPMI_ST_COMMAND_TAG 13040 13041 tag 13042 13043 UINT32 13044 13045 commandSize 13046 13047 TPM_CC 13048 13049 commandCode 13050 13051 TPM_CC_Certify 13052 13053 @objectHandle 13054 13055 handle of the object to be certified 13056 Auth Index: 1 13057 Auth Role: ADMIN 13058 13059 TPMI_DH_OBJECT+ 13060 13061 @signHandle 13062 13063 handle of the key used to sign the attestation structure 13064 Auth Index: 2 13065 Auth Role: USER 13066 13067 TPM2B_DATA 13068 13069 qualifyingData 13070 13071 user provided qualifying data 13072 13073 TPMT_SIG_SCHEME+ 13074 13075 inScheme 13076 13077 signing scheme to use if the scheme for signHandle is 13078 TPM_ALG_NULL 13079 13080 TPMI_DH_OBJECT 13081 13082 Description 13083 13084 Table 78 TPM2_Certify Response 13085 Type 13086 13087 Name 13088 13089 Description 13090 13091 TPM_ST 13092 13093 tag 13094 13095 see clause 8 13096 13097 UINT32 13098 13099 responseSize 13100 13101 TPM_RC 13102 13103 responseCode 13104 13105 . 13106 13107 TPM2B_ATTEST 13108 13109 certifyInfo 13110 13111 the structure that was signed 13112 13113 TPMT_SIGNATURE 13114 13115 signature 13116 13117 the asymmetric signature over certifyInfo using the key 13118 referenced by signHandle 13119 13120 Page 154 13121 October 31, 2013 13122 13123 Published 13124 Copyright TCG 2006-2013 13125 13126 Family 2.0 13127 Level 00 Revision 00.99 13128 13129 Trusted Platform Module Library 13131 13132 Part 3: Commands 13133 13134 20.2.3 Detailed Actions 13135 1 13136 2 13137 3 13138 13139 #include "InternalRoutines.h" 13140 #include "Attest_spt_fp.h" 13141 #include "Certify_fp.h" 13142 Error Returns 13143 TPM_RC_KEY 13144 13145 key referenced by signHandle is not a signing key 13146 13147 TPM_RC_SCHEME 13148 13149 inScheme is not compatible with signHandle 13150 13151 TPM_RC_VALUE 13152 13153 4 13154 5 13155 6 13156 7 13157 8 13158 9 13159 10 13160 11 13161 12 13162 13 13163 14 13164 15 13165 16 13166 17 13167 18 13168 19 13169 20 13170 21 13171 22 13172 23 13173 24 13174 25 13175 26 13176 27 13177 28 13178 29 13179 30 13180 31 13181 32 13182 33 13183 34 13184 35 13185 36 13186 37 13187 38 13188 39 13189 40 13190 41 13191 42 13192 43 13193 44 13194 45 13195 46 13196 47 13197 48 13198 13199 Meaning 13200 13201 digest generated for inScheme is greater or has larger size than the 13202 modulus of signHandle, or the buffer for the result in signature is too 13203 small (for an RSA key); invalid commit status (for an ECC key with a 13204 split scheme). 13205 13206 TPM_RC 13207 TPM2_Certify( 13208 Certify_In 13209 Certify_Out 13210 13211 *in, 13212 *out 13213 13214 // IN: input parameter list 13215 // OUT: output parameter list 13216 13217 ) 13218 { 13219 TPM_RC 13220 TPMS_ATTEST 13221 13222 result; 13223 certifyInfo; 13224 13225 // Command Output 13226 // Filling in attest information 13227 // Common fields 13228 result = FillInAttestInfo(in->signHandle, 13229 &in->inScheme, 13230 &in->qualifyingData, 13231 &certifyInfo); 13232 if(result != TPM_RC_SUCCESS) 13233 { 13234 if(result == TPM_RC_KEY) 13235 return TPM_RC_KEY + RC_Certify_signHandle; 13236 else 13237 return RcSafeAddToResult(result, RC_Certify_inScheme); 13238 } 13239 // Certify specific fields 13240 // Attestation type 13241 certifyInfo.type = TPM_ST_ATTEST_CERTIFY; 13242 // Certified object name 13243 certifyInfo.attested.certify.name.t.size = 13244 ObjectGetName(in->objectHandle, 13245 &certifyInfo.attested.certify.name.t.name); 13246 // Certified object qualified name 13247 ObjectGetQualifiedName(in->objectHandle, 13248 &certifyInfo.attested.certify.qualifiedName); 13249 // Sign attestation structure. A NULL signature will be returned if 13250 // signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, 13251 // TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned 13252 // by SignAttestInfo() 13253 result = SignAttestInfo(in->signHandle, 13254 &in->inScheme, 13255 &certifyInfo, 13256 &in->qualifyingData, 13257 &out->certifyInfo, 13258 13259 Family 2.0 13260 Level 00 Revision 00.99 13261 13262 Published 13263 Copyright TCG 2006-2013 13264 13265 Page 155 13266 October 31, 2013 13267 13268 Part 3: Commands 13270 49 13271 50 13272 51 13273 52 13274 53 13275 54 13276 55 13277 56 13278 57 13279 58 13280 59 13281 60 13282 61 13283 62 13284 63 13285 64 13286 13287 Trusted Platform Module Library 13288 &out->signature); 13289 13290 // TPM_RC_ATTRIBUTES cannot be returned here as FillInAttestInfo would already 13291 // have returned TPM_RC_KEY 13292 pAssert(result != TPM_RC_ATTRIBUTES); 13293 if(result != TPM_RC_SUCCESS) 13294 return result; 13295 // orderly state should be cleared because of the reporting of clock info 13296 // if signing happens 13297 if(in->signHandle != TPM_RH_NULL) 13298 g_clearOrderly = TRUE; 13299 return TPM_RC_SUCCESS; 13300 } 13301 13302 Page 156 13303 October 31, 2013 13304 13305 Published 13306 Copyright TCG 2006-2013 13307 13308 Family 2.0 13309 Level 00 Revision 00.99 13310 13311 Trusted Platform Module Library 13313 13314 20.3 13315 13316 Part 3: Commands 13317 13318 TPM2_CertifyCreation 13319 13320 20.3.1 General Description 13321 This command is used to prove the association between an object and its creation data. The TPM will 13322 validate that the ticket was produced by the TPM and that the ticket validates the association between a 13323 loaded public area and the provided hash of the creation data (creationHash). 13324 NOTE 1 13325 13326 See 20.1 for description of how the signing scheme is selected. 13327 13328 The TPM will create a test ticket using the Name associated with objectHandle and creationHash as: 13329 13330 HMAC(proof, (TPM_ST_CREATION || objectHandleName || creationHash)) 13331 13332 (4) 13333 13334 This ticket is then compared to creation ticket. If the tickets are not the same, the TPM shall return 13335 TPM_RC_TICKET. 13336 If the ticket is valid, then the TPM will create a TPMS_ATTEST structure and place creationHash of the 13337 command in the creationHash field of the structure. The Name associated with objectHandle will be 13338 included in the attestation data that is then signed using the key associated with signHandle. 13339 NOTE 2 13340 13341 If signHandle is TPM_RH_NULL, the TPMS_ATTEST structure is returned and signature is a NULL 13342 Signature. 13343 13344 ObjectHandle may be any object that is loaded with TPM2_Load() or TPM2_CreatePrimary(). 13345 13346 Family 2.0 13347 Level 00 Revision 00.99 13348 13349 Published 13350 Copyright TCG 2006-2013 13351 13352 Page 157 13353 October 31, 2013 13354 13355 Part 3: Commands 13357 13358 Trusted Platform Module Library 13359 13360 20.3.2 Command and Response 13361 Table 79 TPM2_CertifyCreation Command 13362 Type 13363 13364 Name 13365 13366 Description 13367 13368 TPMI_ST_COMMAND_TAG 13369 13370 tag 13371 13372 UINT32 13373 13374 commandSize 13375 13376 TPM_CC 13377 13378 commandCode 13379 13380 TPM_CC_CertifyCreation 13381 13382 TPMI_DH_OBJECT+ 13383 13384 @signHandle 13385 13386 handle of the key that will sign the attestation block 13387 Auth Index: 1 13388 Auth Role: USER 13389 13390 TPMI_DH_OBJECT 13391 13392 objectHandle 13393 13394 the object associated with the creation data 13395 Auth Index: None 13396 13397 TPM2B_DATA 13398 13399 qualifyingData 13400 13401 user-provided qualifying data 13402 13403 TPM2B_DIGEST 13404 13405 creationHash 13406 13407 hash of the creation data produced by TPM2_Create() 13408 or TPM2_CreatePrimary() 13409 13410 TPMT_SIG_SCHEME+ 13411 13412 inScheme 13413 13414 signing scheme to use if the scheme for signHandle is 13415 TPM_ALG_NULL 13416 13417 TPMT_TK_CREATION 13418 13419 creationTicket 13420 13421 ticket produced by TPM2_Create() or 13422 TPM2_CreatePrimary() 13423 13424 Table 80 TPM2_CertifyCreation Response 13425 Type 13426 13427 Name 13428 13429 Description 13430 13431 TPM_ST 13432 13433 tag 13434 13435 see clause 8 13436 13437 UINT32 13438 13439 responseSize 13440 13441 TPM_RC 13442 13443 responseCode 13444 13445 TPM2B_ATTEST 13446 13447 certifyInfo 13448 13449 the structure that was signed 13450 13451 TPMT_SIGNATURE 13452 13453 signature 13454 13455 the signature over certifyInfo 13456 13457 Page 158 13458 October 31, 2013 13459 13460 Published 13461 Copyright TCG 2006-2013 13462 13463 Family 2.0 13464 Level 00 Revision 00.99 13465 13466 Trusted Platform Module Library 13468 13469 Part 3: Commands 13470 13471 20.3.3 Detailed Actions 13472 1 13473 2 13474 3 13475 13476 #include "InternalRoutines.h" 13477 #include "Attest_spt_fp.h" 13478 #include "CertifyCreation_fp.h" 13479 Error Returns 13480 TPM_RC_KEY 13481 13482 key referenced by signHandle is not a signing key 13483 13484 TPM_RC_SCHEME 13485 13486 inScheme is not compatible with signHandle 13487 13488 TPM_RC_TICKET 13489 13490 creationTicket does not match objectHandle 13491 13492 TPM_RC_VALUE 13493 13494 4 13495 5 13496 6 13497 7 13498 8 13499 9 13500 10 13501 11 13502 12 13503 13 13504 14 13505 15 13506 16 13507 17 13508 18 13509 19 13510 20 13511 21 13512 22 13513 23 13514 24 13515 25 13516 26 13517 27 13518 28 13519 29 13520 30 13521 31 13522 32 13523 33 13524 34 13525 35 13526 36 13527 37 13528 38 13529 39 13530 40 13531 41 13532 42 13533 43 13534 44 13535 45 13536 46 13537 13538 Meaning 13539 13540 digest generated for inScheme is greater or has larger size than the 13541 modulus of signHandle, or the buffer for the result in signature is too 13542 small (for an RSA key); invalid commit status (for an ECC key with a 13543 split scheme). 13544 13545 TPM_RC 13546 TPM2_CertifyCreation( 13547 CertifyCreation_In 13548 CertifyCreation_Out 13549 13550 *in, 13551 *out 13552 13553 // IN: input parameter list 13554 // OUT: output parameter list 13555 13556 ) 13557 { 13558 TPM_RC 13559 TPM2B_NAME 13560 TPMT_TK_CREATION 13561 TPMS_ATTEST 13562 13563 result; 13564 name; 13565 ticket; 13566 certifyInfo; 13567 13568 // Input Validation 13569 // CertifyCreation specific input validation 13570 // Get certified object name 13571 name.t.size = ObjectGetName(in->objectHandle, &name.t.name); 13572 // Re-compute ticket 13573 TicketComputeCreation(in->creationTicket.hierarchy, &name, 13574 &in->creationHash, &ticket); 13575 // Compare ticket 13576 if(!Memory2BEqual(&ticket.digest.b, &in->creationTicket.digest.b)) 13577 return TPM_RC_TICKET + RC_CertifyCreation_creationTicket; 13578 // Command Output 13579 // Common fields 13580 result = FillInAttestInfo(in->signHandle, &in->inScheme, &in->qualifyingData, 13581 &certifyInfo); 13582 if(result != TPM_RC_SUCCESS) 13583 { 13584 if(result == TPM_RC_KEY) 13585 return TPM_RC_KEY + RC_CertifyCreation_signHandle; 13586 else 13587 return RcSafeAddToResult(result, RC_CertifyCreation_inScheme); 13588 } 13589 // CertifyCreation specific fields 13590 // Attestation type 13591 certifyInfo.type = TPM_ST_ATTEST_CREATION; 13592 certifyInfo.attested.creation.objectName = name; 13593 // Copy the creationHash 13594 certifyInfo.attested.creation.creationHash = in->creationHash; 13595 13596 Family 2.0 13597 Level 00 Revision 00.99 13598 13599 Published 13600 Copyright TCG 2006-2013 13601 13602 Page 159 13603 October 31, 2013 13604 13605 Part 3: Commands 13607 47 13608 48 13609 49 13610 50 13611 51 13612 52 13613 53 13614 54 13615 55 13616 56 13617 57 13618 58 13619 59 13620 60 13621 61 13622 62 13623 63 13624 64 13625 65 13626 66 13627 67 13628 68 13629 69 13630 70 13631 71 13632 13633 Trusted Platform Module Library 13634 13635 // Sign attestation structure. A NULL signature will be returned if 13636 // signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, 13637 // TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at 13638 // this point 13639 result = SignAttestInfo(in->signHandle, 13640 &in->inScheme, 13641 &certifyInfo, 13642 &in->qualifyingData, 13643 &out->certifyInfo, 13644 &out->signature); 13645 // TPM_RC_ATTRIBUTES cannot be returned here as FillInAttestInfo would already 13646 // have returned TPM_RC_KEY 13647 pAssert(result != TPM_RC_ATTRIBUTES); 13648 if(result != TPM_RC_SUCCESS) 13649 return result; 13650 // orderly state should be cleared because of the reporting of clock info 13651 // if signing happens 13652 if(in->signHandle != TPM_RH_NULL) 13653 g_clearOrderly = TRUE; 13654 return TPM_RC_SUCCESS; 13655 } 13656 13657 Page 160 13658 October 31, 2013 13659 13660 Published 13661 Copyright TCG 2006-2013 13662 13663 Family 2.0 13664 Level 00 Revision 00.99 13665 13666 Trusted Platform Module Library 13668 13669 20.4 13670 13671 Part 3: Commands 13672 13673 TPM2_Quote 13674 13675 20.4.1 General Description 13676 This command is used to quote PCR values. 13677 NOTE 13678 13679 See 20.1 for description of how the signing scheme is selected. 13680 13681 The TPM will hash the list of PCR selected by PCRselect using the hash algorithm associated with 13682 signHandle (this is the hash algorithm of the signing scheme, not the nameAlg of signHandle). 13683 The digest is computed as the hash of the concatenation of all of the digest values of the selected PCR. 13684 The concatenation of PCR is described in Part 1, Selecting Multiple PCR. 13685 13686 Family 2.0 13687 Level 00 Revision 00.99 13688 13689 Published 13690 Copyright TCG 2006-2013 13691 13692 Page 161 13693 October 31, 2013 13694 13695 Part 3: Commands 13697 13698 Trusted Platform Module Library 13699 13700 20.4.2 Command and Response 13701 Table 81 TPM2_Quote Command 13702 Type 13703 13704 Name 13705 13706 Description 13707 13708 TPMI_ST_COMMAND_TAG 13709 13710 tag 13711 13712 UINT32 13713 13714 commandSize 13715 13716 TPM_CC 13717 13718 commandCode 13719 13720 TPM_CC_Quote 13721 13722 TPMI_DH_OBJECT 13723 13724 @signHandle 13725 13726 handle of key that will perform signature 13727 Auth Index: 1 13728 Auth Role: USER 13729 13730 TPM2B_DATA 13731 13732 qualifyingData 13733 13734 data supplied by the caller 13735 13736 TPMT_SIG_SCHEME+ 13737 13738 inScheme 13739 13740 signing scheme to use if the scheme for signHandle is 13741 TPM_ALG_NULL 13742 13743 TPML_PCR_SELECTION 13744 13745 PCRselect 13746 13747 PCR set to quote 13748 13749 Table 82 TPM2_Quote Response 13750 Type 13751 13752 Name 13753 13754 Description 13755 13756 TPM_ST 13757 13758 tag 13759 13760 see clause 8 13761 13762 UINT32 13763 13764 responseSize 13765 13766 TPM_RC 13767 13768 responseCode 13769 13770 TPM2B_ATTEST 13771 13772 quoted 13773 13774 the quoted information 13775 13776 TPMT_SIGNATURE 13777 13778 signature 13779 13780 the signature over quoted 13781 13782 Page 162 13783 October 31, 2013 13784 13785 Published 13786 Copyright TCG 2006-2013 13787 13788 Family 2.0 13789 Level 00 Revision 00.99 13790 13791 Trusted Platform Module Library 13793 13794 Part 3: Commands 13795 13796 20.4.3 Detailed Actions 13797 1 13798 2 13799 3 13800 13801 #include "InternalRoutines.h" 13802 #include "Attest_spt_fp.h" 13803 #include "Quote_fp.h" 13804 Error Returns 13805 TPM_RC_KEY 13806 13807 signHandle does not reference a signing key; 13808 13809 TPM_RC_SCHEME 13810 13811 4 13812 5 13813 6 13814 7 13815 8 13816 9 13817 10 13818 11 13819 12 13820 13 13821 14 13822 15 13823 16 13824 17 13825 18 13826 19 13827 20 13828 21 13829 22 13830 23 13831 24 13832 25 13833 26 13834 27 13835 28 13836 29 13837 30 13838 31 13839 32 13840 33 13841 34 13842 35 13843 36 13844 37 13845 38 13846 39 13847 40 13848 41 13849 42 13850 43 13851 44 13852 45 13853 46 13854 47 13855 48 13856 49 13857 50 13858 51 13859 13860 Meaning 13861 13862 the scheme is not compatible with sign key type, or input scheme is 13863 not compatible with default scheme, or the chosen scheme is not a 13864 valid sign scheme 13865 13866 TPM_RC 13867 TPM2_Quote( 13868 Quote_In 13869 Quote_Out 13870 13871 *in, 13872 *out 13873 13874 // IN: input parameter list 13875 // OUT: output parameter list 13876 13877 ) 13878 { 13879 TPM_RC 13880 TPMI_ALG_HASH 13881 TPMS_ATTEST 13882 13883 result; 13884 hashAlg; 13885 quoted; 13886 13887 // Command Output 13888 // Filling in attest information 13889 // Common fields 13890 // FillInAttestInfo will return TPM_RC_SCHEME or TPM_RC_KEY 13891 result = FillInAttestInfo(in->signHandle, 13892 &in->inScheme, 13893 &in->qualifyingData, 13894 "ed); 13895 if(result != TPM_RC_SUCCESS) 13896 { 13897 if(result == TPM_RC_KEY) 13898 return TPM_RC_KEY + RC_Quote_signHandle; 13899 else 13900 return RcSafeAddToResult(result, RC_Quote_inScheme); 13901 } 13902 // Quote specific fields 13903 // Attestation type 13904 quoted.type = TPM_ST_ATTEST_QUOTE; 13905 // Get hash algorithm in sign scheme. This hash algorithm is used to 13906 // compute PCR digest. If there is no algorithm, then the PCR cannot 13907 // be digested and this command returns TPM_RC_SCHEME 13908 hashAlg = in->inScheme.details.any.hashAlg; 13909 if(hashAlg == TPM_ALG_NULL) 13910 return TPM_RC_SCHEME + RC_Quote_inScheme; 13911 // Compute PCR digest 13912 PCRComputeCurrentDigest(hashAlg, 13913 &in->PCRselect, 13914 "ed.attested.quote.pcrDigest); 13915 // Copy PCR select. "PCRselect" is modified in PCRComputeCurrentDigest 13916 // function 13917 quoted.attested.quote.pcrSelect = in->PCRselect; 13918 13919 Family 2.0 13920 Level 00 Revision 00.99 13921 13922 Published 13923 Copyright TCG 2006-2013 13924 13925 Page 163 13926 October 31, 2013 13927 13928 Part 3: Commands 13930 52 13931 53 13932 54 13933 55 13934 56 13935 57 13936 58 13937 59 13938 60 13939 61 13940 62 13941 63 13942 64 13943 65 13944 66 13945 67 13946 68 13947 69 13948 70 13949 71 13950 72 13951 73 13952 74 13953 13954 Trusted Platform Module Library 13955 13956 // Sign attestation structure. A NULL signature will be returned if 13957 // signHandle is TPM_RH_NULL. TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES 13958 // error may be returned by SignAttestInfo. 13959 // NOTE: TPM_RC_ATTRIBUTES means that the key is not a signing key but that 13960 // was checked above and TPM_RC_KEY was returned. TPM_RC_VALUE means that the 13961 // value to sign is too large but that means that the digest is too big and 13962 // that can't happen. 13963 result = SignAttestInfo(in->signHandle, 13964 &in->inScheme, 13965 "ed, 13966 &in->qualifyingData, 13967 &out->quoted, 13968 &out->signature); 13969 if(result != TPM_RC_SUCCESS) 13970 return result; 13971 // orderly state should be cleared because of the reporting of clock info 13972 // if signing happens 13973 if(in->signHandle != TPM_RH_NULL) 13974 g_clearOrderly = TRUE; 13975 return TPM_RC_SUCCESS; 13976 } 13977 13978 Page 164 13979 October 31, 2013 13980 13981 Published 13982 Copyright TCG 2006-2013 13983 13984 Family 2.0 13985 Level 00 Revision 00.99 13986 13987 Trusted Platform Module Library 13989 13990 20.5 13991 13992 Part 3: Commands 13993 13994 TPM2_GetSessionAuditDigest 13995 13996 20.5.1 General Description 13997 This command returns a digital signature of the audit session digest. 13998 NOTE 1 13999 14000 See 20.1 for description of how the signing scheme is selected. 14001 14002 If sessionHandle is not an audit session, the TPM shall return TPM_RC_TYPE. 14003 NOTE 2 14004 14005 A session does not become an audit session until the successful completion of the command in 14006 which the session is first used as an audit session. 14007 14008 This command requires authorization from the privacy administrator of the TPM (expressed with 14009 endorsementAuth) as well as authorization to use the key associated with signHandle. 14010 If this command is audited, then the audit digest that is signed will not include the digest of this command 14011 because the audit digest is only updated when the command completes successfully. 14012 This command does not cause the audit session to be closed and does not reset the digest value. 14013 NOTE 3 14014 14015 The audit session digest will be reset if the sessionHandle is used as the audit session for the 14016 command and the auditReset attribute of the session is set; and this command will be the first 14017 command in the audit digest. 14018 14019 NOTE 4 14020 14021 A reason for using 'sessionHahdle' in this command is so that the continueSession attribute may be 14022 CLEAR. This will flush the session at the end of the command. 14023 14024 Family 2.0 14025 Level 00 Revision 00.99 14026 14027 Published 14028 Copyright TCG 2006-2013 14029 14030 Page 165 14031 October 31, 2013 14032 14033 Part 3: Commands 14035 14036 Trusted Platform Module Library 14037 14038 20.5.2 Command and Response 14039 Table 83 TPM2_GetSessionAuditDigest Command 14040 Type 14041 14042 Name 14043 14044 TPMI_ST_COMMAND_TAG 14045 14046 tag 14047 14048 UINT32 14049 14050 commandSize 14051 14052 TPM_CC 14053 14054 commandCode 14055 14056 TPM_CC_GetSessionAuditDigest 14057 14058 @privacyAdminHandle 14059 14060 handle of the privacy administrator 14061 (TPM_RH_ENDORSEMENT) 14062 Auth Index: 1 14063 Auth Role: USER 14064 14065 TPMI_DH_OBJECT+ 14066 14067 @signHandle 14068 14069 handle of the signing key 14070 Auth Index: 2 14071 Auth Role: USER 14072 14073 TPMI_SH_HMAC 14074 14075 sessionHandle 14076 14077 handle of the audit session 14078 Auth Index: None 14079 14080 TPM2B_DATA 14081 14082 qualifyingData 14083 14084 user-provided qualifying data may be zero-length 14085 14086 TPMT_SIG_SCHEME+ 14087 14088 inScheme 14089 14090 signing scheme to use if the scheme for signHandle is 14091 TPM_ALG_NULL 14092 14093 TPMI_RH_ENDORSEMENT 14094 14095 Description 14096 14097 Table 84 TPM2_GetSessionAuditDigest Response 14098 Type 14099 14100 Name 14101 14102 Description 14103 14104 TPM_ST 14105 14106 tag 14107 14108 see clause 8 14109 14110 UINT32 14111 14112 responseSize 14113 14114 TPM_RC 14115 14116 responseCode 14117 14118 TPM2B_ATTEST 14119 14120 auditInfo 14121 14122 the audit information that was signed 14123 14124 TPMT_SIGNATURE 14125 14126 signature 14127 14128 the signature over auditInfo 14129 14130 Page 166 14131 October 31, 2013 14132 14133 Published 14134 Copyright TCG 2006-2013 14135 14136 Family 2.0 14137 Level 00 Revision 00.99 14138 14139 Trusted Platform Module Library 14141 14142 Part 3: Commands 14143 14144 20.5.3 Detailed Actions 14145 1 14146 2 14147 3 14148 14149 #include "InternalRoutines.h" 14150 #include "Attest_spt_fp.h" 14151 #include "GetSessionAuditDigest_fp.h" 14152 Error Returns 14153 TPM_RC_KEY 14154 14155 key referenced by signHandle is not a signing key 14156 14157 TPM_RC_SCHEME 14158 14159 inScheme is incompatible with signHandle type; or both scheme and 14160 key's default scheme are empty; or scheme is empty while key's 14161 default scheme requires explicit input scheme (split signing); or nonempty default key scheme differs from scheme 14162 14163 TPM_RC_TYPE 14164 14165 sessionHandle does not reference an audit session 14166 14167 TPM_RC_VALUE 14168 14169 4 14170 5 14171 6 14172 7 14173 8 14174 9 14175 10 14176 11 14177 12 14178 13 14179 14 14180 15 14181 16 14182 17 14183 18 14184 19 14185 20 14186 21 14187 22 14188 23 14189 24 14190 25 14191 26 14192 27 14193 28 14194 29 14195 30 14196 31 14197 32 14198 33 14199 34 14200 35 14201 36 14202 37 14203 38 14204 39 14205 40 14206 41 14207 42 14208 43 14209 44 14210 14211 Meaning 14212 14213 digest generated for the given scheme is greater than the modulus of 14214 signHandle (for an RSA key); invalid commit status or failed to 14215 generate r value (for an ECC key) 14216 14217 TPM_RC 14218 TPM2_GetSessionAuditDigest( 14219 GetSessionAuditDigest_In 14220 GetSessionAuditDigest_Out 14221 14222 *in, 14223 *out 14224 14225 // IN: input parameter list 14226 // OUT: output parameter list 14227 14228 ) 14229 { 14230 TPM_RC 14231 SESSION 14232 TPMS_ATTEST 14233 14234 result; 14235 *session; 14236 auditInfo; 14237 14238 // Input Validation 14239 // SessionAuditDigest specific input validation 14240 // Get session pointer 14241 session = SessionGet(in->sessionHandle); 14242 // session must be an audit session 14243 if(session->attributes.isAudit == CLEAR) 14244 return TPM_RC_TYPE + RC_GetSessionAuditDigest_sessionHandle; 14245 // Command Output 14246 // Filling in attest information 14247 // Common fields 14248 result = FillInAttestInfo(in->signHandle, 14249 &in->inScheme, 14250 &in->qualifyingData, 14251 &auditInfo); 14252 if(result != TPM_RC_SUCCESS) 14253 { 14254 if(result == TPM_RC_KEY) 14255 return TPM_RC_KEY + RC_GetSessionAuditDigest_signHandle; 14256 else 14257 return RcSafeAddToResult(result, RC_GetSessionAuditDigest_inScheme); 14258 } 14259 // SessionAuditDigest specific fields 14260 // Attestation type 14261 auditInfo.type = TPM_ST_ATTEST_SESSION_AUDIT; 14262 // Copy digest 14263 14264 Family 2.0 14265 Level 00 Revision 00.99 14266 14267 Published 14268 Copyright TCG 2006-2013 14269 14270 Page 167 14271 October 31, 2013 14272 14273 Part 3: Commands 14275 45 14276 46 14277 47 14278 48 14279 49 14280 50 14281 51 14282 52 14283 53 14284 54 14285 55 14286 56 14287 57 14288 58 14289 59 14290 60 14291 61 14292 62 14293 63 14294 64 14295 65 14296 66 14297 67 14298 68 14299 69 14300 70 14301 71 14302 72 14303 14304 Trusted Platform Module Library 14305 14306 auditInfo.attested.sessionAudit.sessionDigest = session->u2.auditDigest; 14307 // Exclusive audit session 14308 if(g_exclusiveAuditSession == in->sessionHandle) 14309 auditInfo.attested.sessionAudit.exclusiveSession = TRUE; 14310 else 14311 auditInfo.attested.sessionAudit.exclusiveSession = FALSE; 14312 // Sign attestation structure. A NULL signature will be returned if 14313 // signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, 14314 // TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at 14315 // this point 14316 result = SignAttestInfo(in->signHandle, 14317 &in->inScheme, 14318 &auditInfo, 14319 &in->qualifyingData, 14320 &out->auditInfo, 14321 &out->signature); 14322 if(result != TPM_RC_SUCCESS) 14323 return result; 14324 // orderly state should be cleared because of the reporting of clock info 14325 // if signing happens 14326 if(in->signHandle != TPM_RH_NULL) 14327 g_clearOrderly = TRUE; 14328 return TPM_RC_SUCCESS; 14329 } 14330 14331 Page 168 14332 October 31, 2013 14333 14334 Published 14335 Copyright TCG 2006-2013 14336 14337 Family 2.0 14338 Level 00 Revision 00.99 14339 14340 Trusted Platform Module Library 14342 14343 20.6 14344 14345 Part 3: Commands 14346 14347 TPM2_GetCommandAuditDigest 14348 14349 20.6.1 General Description 14350 This command returns the current value of the command audit digest, a digest of the commands being 14351 audited, and the audit hash algorithm. These values are placed in an attestation structure and signed with 14352 the key referenced by signHandle. 14353 NOTE 1 14354 14355 See 20.1 for description of how the signing scheme is selected. 14356 14357 When this command completes successfully, and signHandle is not TPM_RH_NULL, the audit digest is 14358 cleared. 14359 NOTE 2 14360 14361 The way that the TPM tracks that the digest is clear is vendor -dependent. The reference 14362 implementation resets the size of the digest to zero. 14363 14364 If this command is being audited, then the signed digest produced by the command will not include the 14365 command. At the end of this command, the audit digest will be extended with cpHash and the rpHash of 14366 the command which would change the command audit digest signed by the next invocation of this 14367 command. 14368 This command requires authorization from the privacy administrator of the TPM (expressed with 14369 endorsementAuth) as well as authorization to use the key associated with signHandle. 14370 14371 Family 2.0 14372 Level 00 Revision 00.99 14373 14374 Published 14375 Copyright TCG 2006-2013 14376 14377 Page 169 14378 October 31, 2013 14379 14380 Part 3: Commands 14382 14383 Trusted Platform Module Library 14384 14385 20.6.2 Command and Response 14386 Table 85 TPM2_GetCommandAuditDigest Command 14387 Type 14388 14389 Name 14390 14391 Description 14392 14393 TPMI_ST_COMMAND_TAG 14394 14395 tag 14396 14397 UINT32 14398 14399 commandSize 14400 14401 TPM_CC 14402 14403 commandCode 14404 14405 TPM_CC_GetCommandAuditDigest {NV} 14406 14407 TPMI_RH_ENDORSEMENT 14408 14409 @privacyHandle 14410 14411 handle of the privacy administrator 14412 (TPM_RH_ENDORSEMENT) 14413 Auth Index: 1 14414 Auth Role: USER 14415 14416 TPMI_DH_OBJECT+ 14417 14418 @signHandle 14419 14420 the handle of the signing key 14421 Auth Index: 2 14422 Auth Role: USER 14423 14424 TPM2B_DATA 14425 14426 qualifyingData 14427 14428 other data to associate with this audit digest 14429 14430 TPMT_SIG_SCHEME+ 14431 14432 inScheme 14433 14434 signing scheme to use if the scheme for signHandle is 14435 TPM_ALG_NULL 14436 14437 Table 86 TPM2_GetCommandAuditDigest Response 14438 Type 14439 14440 Name 14441 14442 Description 14443 14444 TPM_ST 14445 14446 tag 14447 14448 see clause 8 14449 14450 UINT32 14451 14452 responseSize 14453 14454 TPM_RC 14455 14456 responseCode 14457 14458 TPM2B_ATTEST 14459 14460 auditInfo 14461 14462 the auditInfo that was signed 14463 14464 TPMT_SIGNATURE 14465 14466 signature 14467 14468 the signature over auditInfo 14469 14470 Page 170 14471 October 31, 2013 14472 14473 Published 14474 Copyright TCG 2006-2013 14475 14476 Family 2.0 14477 Level 00 Revision 00.99 14478 14479 Trusted Platform Module Library 14481 14482 Part 3: Commands 14483 14484 20.6.3 Detailed Actions 14485 1 14486 2 14487 3 14488 14489 #include "InternalRoutines.h" 14490 #include "Attest_spt_fp.h" 14491 #include "GetCommandAuditDigest_fp.h" 14492 Error Returns 14493 TPM_RC_KEY 14494 14495 key referenced by signHandle is not a signing key 14496 14497 TPM_RC_SCHEME 14498 14499 inScheme is incompatible with signHandle type; or both scheme and 14500 key's default scheme are empty; or scheme is empty while key's 14501 default scheme requires explicit input scheme (split signing); or nonempty default key scheme differs from scheme 14502 14503 TPM_RC_VALUE 14504 14505 4 14506 5 14507 6 14508 7 14509 8 14510 9 14511 10 14512 11 14513 12 14514 13 14515 14 14516 15 14517 16 14518 17 14519 18 14520 19 14521 20 14522 21 14523 22 14524 23 14525 24 14526 25 14527 26 14528 27 14529 28 14530 29 14531 30 14532 31 14533 32 14534 33 14535 34 14536 35 14537 36 14538 37 14539 38 14540 39 14541 40 14542 41 14543 42 14544 43 14545 44 14546 45 14547 46 14548 14549 Meaning 14550 14551 digest generated for the given scheme is greater than the modulus of 14552 signHandle (for an RSA key); invalid commit status or failed to 14553 generate r value (for an ECC key) 14554 14555 TPM_RC 14556 TPM2_GetCommandAuditDigest( 14557 GetCommandAuditDigest_In 14558 GetCommandAuditDigest_Out 14559 14560 *in, 14561 *out 14562 14563 // IN: input parameter list 14564 // OUT: output parameter list 14565 14566 ) 14567 { 14568 TPM_RC 14569 TPMS_ATTEST 14570 14571 result; 14572 auditInfo; 14573 14574 // Command Output 14575 // Filling in attest information 14576 // Common fields 14577 result = FillInAttestInfo(in->signHandle, 14578 &in->inScheme, 14579 &in->qualifyingData, 14580 &auditInfo); 14581 if(result != TPM_RC_SUCCESS) 14582 { 14583 if(result == TPM_RC_KEY) 14584 return TPM_RC_KEY + RC_GetCommandAuditDigest_signHandle; 14585 else 14586 return RcSafeAddToResult(result, RC_GetCommandAuditDigest_inScheme); 14587 } 14588 // CommandAuditDigest specific fields 14589 // Attestation type 14590 auditInfo.type = TPM_ST_ATTEST_COMMAND_AUDIT; 14591 // Copy audit hash algorithm 14592 auditInfo.attested.commandAudit.digestAlg = gp.auditHashAlg; 14593 // Copy counter value 14594 auditInfo.attested.commandAudit.auditCounter = gp.auditCounter; 14595 // Copy command audit log 14596 auditInfo.attested.commandAudit.auditDigest = gr.commandAuditDigest; 14597 CommandAuditGetDigest(&auditInfo.attested.commandAudit.commandDigest); 14598 // 14599 // 14600 // 14601 // 14602 14603 Sign attestation structure. A NULL signature will be returned if 14604 signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, 14605 TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at 14606 this point 14607 14608 Family 2.0 14609 Level 00 Revision 00.99 14610 14611 Published 14612 Copyright TCG 2006-2013 14613 14614 Page 171 14615 October 31, 2013 14616 14617 Part 3: Commands 14619 47 14620 48 14621 49 14622 50 14623 51 14624 52 14625 53 14626 54 14627 55 14628 56 14629 57 14630 58 14631 59 14632 60 14633 61 14634 62 14635 63 14636 64 14637 65 14638 66 14639 67 14640 68 14641 69 14642 70 14643 14644 Trusted Platform Module Library 14645 14646 result = SignAttestInfo(in->signHandle, 14647 &in->inScheme, 14648 &auditInfo, 14649 &in->qualifyingData, 14650 &out->auditInfo, 14651 &out->signature); 14652 if(result != TPM_RC_SUCCESS) 14653 return result; 14654 // Internal Data Update 14655 if(in->signHandle != TPM_RH_NULL) 14656 { 14657 // Reset log 14658 gr.commandAuditDigest.t.size = 0; 14659 // orderly state should be cleared because of the update in 14660 // commandAuditDigest, as well as the reporting of clock info 14661 g_clearOrderly = TRUE; 14662 } 14663 return TPM_RC_SUCCESS; 14664 } 14665 14666 Page 172 14667 October 31, 2013 14668 14669 Published 14670 Copyright TCG 2006-2013 14671 14672 Family 2.0 14673 Level 00 Revision 00.99 14674 14675 Trusted Platform Module Library 14677 14678 20.7 14679 14680 Part 3: Commands 14681 14682 TPM2_GetTime 14683 14684 20.7.1 General Description 14685 This command returns the current values of Time and Clock. 14686 NOTE 1 14687 14688 See 20.1 for description of how the signing scheme is selected. 14689 14690 The values of Clock, resetCount and restartCount appear in two places in timeInfo: once in 14691 TPMS_ATTEST.clockInfo and again in TPMS_ATTEST.attested.time.clockInfo. The firmware version 14692 number 14693 also 14694 appears 14695 in 14696 two 14697 places 14698 (TPMS_ATTEST.firmwareVersion 14699 and 14700 TPMS_ATTEST.attested.time.firmwareVersion). If signHandle is in the endorsement or platform 14701 hierarchies, both copies of the data will be the same. However, if signHandle is in the storage hierarchy or 14702 is TPM_RH_NULL, the values in TPMS_ATTEST.clockInfo and TPMS_ATTEST.firmwareVersion are 14703 obfuscated but the values in TPM_ATTEST.attested.time are not. 14704 NOTE 2 14705 14706 The purpose of this duplication is to allow an entity who is trusted by the privacy Administrator to 14707 correlate the obfuscated values with the clear -text values. 14708 14709 Family 2.0 14710 Level 00 Revision 00.99 14711 14712 Published 14713 Copyright TCG 2006-2013 14714 14715 Page 173 14716 October 31, 2013 14717 14718 Part 3: Commands 14720 14721 Trusted Platform Module Library 14722 14723 20.7.2 Command and Response 14724 Table 87 TPM2_GetTime Command 14725 Type 14726 14727 Name 14728 14729 TPMI_ST_COMMAND_TAG 14730 14731 tag 14732 14733 UINT32 14734 14735 commandSize 14736 14737 TPM_CC 14738 14739 commandCode 14740 14741 TPM_CC_GetTime 14742 14743 @privacyAdminHandle 14744 14745 handle of the privacy administrator 14746 (TPM_RH_ENDORSEMENT) 14747 Auth Index: 1 14748 Auth Role: USER 14749 14750 TPMI_DH_OBJECT+ 14751 14752 @signHandle 14753 14754 the keyHandle identifier of a loaded key that can 14755 perform digital signatures 14756 Auth Index: 2 14757 Auth Role: USER 14758 14759 TPM2B_DATA 14760 14761 qualifyingData 14762 14763 data to tick stamp 14764 14765 TPMT_SIG_SCHEME+ 14766 14767 inScheme 14768 14769 signing scheme to use if the scheme for signHandle is 14770 TPM_ALG_NULL 14771 14772 TPMI_RH_ENDORSEMENT 14773 14774 Description 14775 14776 Table 88 TPM2_GetTime Response 14777 Type 14778 14779 Name 14780 14781 Description 14782 14783 TPM_ST 14784 14785 tag 14786 14787 see clause 8 14788 14789 UINT32 14790 14791 responseSize 14792 14793 TPM_RC 14794 14795 responseCode 14796 14797 . 14798 14799 TPM2B_ATTEST 14800 14801 timeInfo 14802 14803 standard TPM-generated attestation block 14804 14805 TPMT_SIGNATURE 14806 14807 signature 14808 14809 the signature over timeInfo 14810 14811 Page 174 14812 October 31, 2013 14813 14814 Published 14815 Copyright TCG 2006-2013 14816 14817 Family 2.0 14818 Level 00 Revision 00.99 14819 14820 Trusted Platform Module Library 14822 14823 Part 3: Commands 14824 14825 20.7.3 Detailed Actions 14826 1 14827 2 14828 3 14829 14830 #include "InternalRoutines.h" 14831 #include "Attest_spt_fp.h" 14832 #include "GetTime_fp.h" 14833 Error Returns 14834 TPM_RC_KEY 14835 14836 key referenced by signHandle is not a signing key 14837 14838 TPM_RC_SCHEME 14839 14840 inScheme is incompatible with signHandle type; or both scheme and 14841 key's default scheme are empty; or scheme is empty while key's 14842 default scheme requires explicit input scheme (split signing); or nonempty default key scheme differs from scheme 14843 14844 TPM_RC_VALUE 14845 14846 4 14847 5 14848 6 14849 7 14850 8 14851 9 14852 10 14853 11 14854 12 14855 13 14856 14 14857 15 14858 16 14859 17 14860 18 14861 19 14862 20 14863 21 14864 22 14865 23 14866 24 14867 25 14868 26 14869 27 14870 28 14871 29 14872 30 14873 31 14874 32 14875 33 14876 34 14877 35 14878 36 14879 37 14880 38 14881 39 14882 40 14883 41 14884 42 14885 43 14886 44 14887 45 14888 46 14889 14890 Meaning 14891 14892 digest generated for the given scheme is greater than the modulus of 14893 signHandle (for an RSA key); invalid commit status or failed to 14894 generate r value (for an ECC key) 14895 14896 TPM_RC 14897 TPM2_GetTime( 14898 GetTime_In 14899 GetTime_Out 14900 14901 *in, 14902 *out 14903 14904 // IN: input parameter list 14905 // OUT: output parameter list 14906 14907 ) 14908 { 14909 TPM_RC 14910 TPMS_ATTEST 14911 14912 result; 14913 timeInfo; 14914 14915 // Command Output 14916 // Filling in attest information 14917 // Common fields 14918 result = FillInAttestInfo(in->signHandle, 14919 &in->inScheme, 14920 &in->qualifyingData, 14921 &timeInfo); 14922 if(result != TPM_RC_SUCCESS) 14923 { 14924 if(result == TPM_RC_KEY) 14925 return TPM_RC_KEY + RC_GetTime_signHandle; 14926 else 14927 return RcSafeAddToResult(result, RC_GetTime_inScheme); 14928 } 14929 // GetClock specific fields 14930 // Attestation type 14931 timeInfo.type = TPM_ST_ATTEST_TIME; 14932 // current clock in plain text 14933 timeInfo.attested.time.time.time = g_time; 14934 TimeFillInfo(&timeInfo.attested.time.time.clockInfo); 14935 // Firmware version in plain text 14936 timeInfo.attested.time.firmwareVersion 14937 = ((UINT64) gp.firmwareV1) << 32; 14938 timeInfo.attested.time.firmwareVersion += gp.firmwareV2; 14939 // Sign attestation structure. A NULL signature will be returned if 14940 // signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, 14941 // TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at 14942 // this point 14943 result = SignAttestInfo(in->signHandle, 14944 14945 Family 2.0 14946 Level 00 Revision 00.99 14947 14948 Published 14949 Copyright TCG 2006-2013 14950 14951 Page 175 14952 October 31, 2013 14953 14954 Part 3: Commands 14956 47 14957 48 14958 49 14959 50 14960 51 14961 52 14962 53 14963 54 14964 55 14965 56 14966 57 14967 58 14968 59 14969 60 14970 61 14971 14972 Trusted Platform Module Library 14973 14974 &in->inScheme, 14975 &timeInfo, 14976 &in->qualifyingData, 14977 &out->timeInfo, 14978 &out->signature); 14979 if(result != TPM_RC_SUCCESS) 14980 return result; 14981 // orderly state should be cleared because of the reporting of clock info 14982 // if signing happens 14983 if(in->signHandle != TPM_RH_NULL) 14984 g_clearOrderly = TRUE; 14985 return TPM_RC_SUCCESS; 14986 } 14987 14988 Page 176 14989 October 31, 2013 14990 14991 Published 14992 Copyright TCG 2006-2013 14993 14994 Family 2.0 14995 Level 00 Revision 00.99 14996 14997 Trusted Platform Module Library 14999 15000 21 15001 15002 Part 3: Commands 15003 15004 Ephemeral EC Keys 15005 15006 21.1 15007 15008 Introduction 15009 15010 The TPM generates keys that have different lifetimes. TPM keys in a hierarchy can be persistent for as 15011 long 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 15012 command in which they are created. Examples of this use are TPM2_Duplicate() where an ephemeral 15013 key is created for a single pass key exchange with another TPM. However, there are other cases, such 15014 as anonymous attestation, where the protocol requires two passes where the public part of the ephemeral 15015 key is used outside of the TPM before the final command "consumes" the ephemeral key. 15016 For these uses, TPM2_Commit() or TPM2_EC_Ephemeral() may be used to have the TPM create an 15017 ephemeral EC key and return the public part of the key for external use. Then in a subsequent command, 15018 the caller provides a reference to the ephemeral key so that the TPM can retrieve or recreate the 15019 associated private key. 15020 When an ephemeral EC key is created, it is assigned a number and that number is returned to the caller 15021 as the identifier for the key. This number is not a handle. A handle is assigned to a key that may be 15022 context saved but these ephemeral EC keys may not be saved and do not have a full key context. When 15023 a subsequent command uses the ephemeral key, the caller provides the number of the ephemeral key. 15024 The TPM uses that number to either look up or recompute the associated private key. After the key is 15025 used, the TPM records the fact that the key has been used so that it cannot be used again. 15026 As mentioned, the TPM can keep each assigned private ephemeral key in memory until it is used. 15027 However, this could consume a large amount of memory. To limit the memory size, the TPM is allowed to 15028 restrict the number of pending private keys keys that have been allocated but not used. 15029 NOTE 15030 15031 The minimum number of ephemeral keys is determined by a platform specific specification 15032 15033 To further reduce the memory requirements for the ephemeral private keys, the TPM is allowed to use 15034 pseudo-random values for the ephemeral keys. Instead of keeping the full value of the key in memory, the 15035 TPM can use a counter as input to a KDF. Incrementing the counter will cause the TPM to generate a 15036 new pseudo-random value. 15037 Using the counter to generate pseudo-random private ephemeral keys greatly simplifies tracking of key 15038 usage. When a counter value is used to create a key, a bit in an array may be set to indicate that the key 15039 use is pending. When the ephemeral key is consumed, the bit is cleared. This prevents the key from 15040 being used more than once. 15041 Since the TPM is allowed to restrict the number of pending ephemeral keys, the array size can be limited. 15042 For example, a 128 bit array would allow 128 keys to be "pending". 15043 The management of the array is described in greater detail in the Split Operations clause in Annex C of 15044 part 1. 15045 15046 Family 2.0 15047 Level 00 Revision 00.99 15048 15049 Published 15050 Copyright TCG 2006-2013 15051 15052 Page 177 15053 October 31, 2013 15054 15055 Part 3: Commands 15057 15058 21.2 15059 15060 Trusted Platform Module Library 15061 15062 TPM2_Commit 15063 15064 21.2.1 General Description 15065 TPM2_Commit() performs the first part of an ECC anonymous signing operation. The TPM will perform 15066 the point multiplications on the provided points and return intermediate signing values. The signHandle 15067 parameter shall refer to an ECC key with the sign attribute (TPM_RC_ATTRIBUTES) using an 15068 anonymous signing scheme (TPM_RC_SCHEME). 15069 For this command, p1, s2 and y2 are optional parameters. If s2 is an Empty Buffer, then the TPM shall 15070 return TPM_RC_SIZE if y2 is not an Empty Buffer. If p1, s2, and y2 are all Empty Buffers, the TPM shall 15071 return TPM_RC_NO_RESULT. 15072 In the algorithm below, the following additional values are used in addition to the command parameters: 15073 15074 HnameAlg 15075 15076 hash function using the nameAlg of the key associated with 15077 signHandle 15078 15079 p 15080 15081 field modulus of the curve associated with signHandle 15082 15083 n 15084 15085 order of the curve associated with signHandle 15086 15087 ds 15088 15089 private key associated with signHandle 15090 15091 c 15092 15093 counter that increments each time a TPM2_Commit() is 15094 successfully completed 15095 15096 A[i] 15097 15098 array of bits used to indicate when a value of c has been used in 15099 a signing operation; values of i are 0 to 2n-1 15100 15101 k 15102 15103 nonce that is set to a random value on each TPM Reset; nonce 15104 size is twice the security strength of any ECDAA key supported 15105 by the TPM. 15106 15107 The algorithm is: 15108 a) set K, L, and E to be Empty Buffers. 15109 b) if s2 is not an Empty Buffer, compute x2 HnameAlg (s2) mod p, else skip to step (e) 15110 c) if (x2, y2) is not a point on the curve of signHandle, return TPM_RC_ECC_POINT 15111 d) set K [ds] (x2, y2) 15112 e) generate or derive r (see the "Commit Random Value" clause in Part 1) 15113 f) 15114 15115 set r r mod n 15116 15117 NOTE 1 15118 15119 nLen is the number of bits in n 15120 15121 g) if p1 is an Empty Buffer, skip to step i) 15122 h) if (p1) is not a point on the curve of signHandle, return TPM_RC_ECC_POINT 15123 i) 15124 15125 set E [r] (p1) 15126 15127 j) 15128 15129 if K is not an Empty Buffer, set L [r] (x2, y2) 15130 15131 k) if K, L, or E is the point at infinity, return TPM_RC_NO_RESULT 15132 l) 15133 15134 set counter commitCount 15135 15136 m) set commitCount commitCount + 1 15137 15138 Page 178 15139 October 31, 2013 15140 15141 Published 15142 Copyright TCG 2006-2013 15143 15144 Family 2.0 15145 Level 00 Revision 00.99 15146 15147 Trusted Platform Module Library 15149 NOTE 2 15150 15151 Part 3: Commands 15152 15153 Depending on the method of generating r, it may be necessary to update the tracking array here. 15154 15155 n) output K, L, E and counter 15156 NOTE 3 15157 15158 Depending on the input parameters K and L may be Empty Buffers or E may be an Empty Buffer 15159 15160 Family 2.0 15161 Level 00 Revision 00.99 15162 15163 Published 15164 Copyright TCG 2006-2013 15165 15166 Page 179 15167 October 31, 2013 15168 15169 Part 3: Commands 15171 15172 Trusted Platform Module Library 15173 15174 21.2.2 Command and Response 15175 Table 89 TPM2_Commit Command 15176 Type 15177 15178 Name 15179 15180 TPMI_ST_COMMAND_TAG 15181 15182 tag 15183 15184 UINT32 15185 15186 paramSize 15187 15188 TPM_CC 15189 15190 commandCode 15191 15192 Description 15193 15194 TPM_CC_Commit 15195 handle of the key that will be used in the signing 15196 operation 15197 15198 TPMI_DH_OBJECT 15199 15200 @signHandle 15201 15202 Auth Index: 1 15203 Auth Role: USER 15204 15205 TPM2B_ECC_POINT 15206 15207 P1 15208 15209 a point (M) on the curve used by signHandle 15210 15211 TPM2B_SENSITIVE_DATA 15212 15213 s2 15214 15215 octet array used to derive x-coordinate of a base point 15216 15217 TPM2B_ECC_PARAMETER 15218 15219 y2 15220 15221 y coordinate of the point associated with s2 15222 15223 Table 90 TPM2_Commit Response 15224 Type 15225 15226 Name 15227 15228 Description 15229 15230 TPM_ST 15231 15232 tag 15233 15234 see 8 15235 15236 UINT32 15237 15238 paramSize 15239 15240 TPM_RC 15241 15242 responseCode 15243 15244 TPM2B_ECC_POINT 15245 15246 K 15247 15248 ECC point K [ds](x2, y2) 15249 15250 TPM2B_ECC_POINT 15251 15252 L 15253 15254 ECC point L [r](x2, y2) 15255 15256 TPM2B_ECC_POINT 15257 15258 E 15259 15260 ECC point E [r]P1 15261 15262 UINT16 15263 15264 counter 15265 15266 least-significant 16 bits of commitCount 15267 15268 Page 180 15269 October 31, 2013 15270 15271 Published 15272 Copyright TCG 2006-2013 15273 15274 Family 2.0 15275 Level 00 Revision 00.99 15276 15277 Trusted Platform Module Library 15279 15280 Part 3: Commands 15281 15282 21.2.3 Detailed Actions 15283 1 15284 2 15285 3 15286 15287 #include "InternalRoutines.h" 15288 #include "Commit_fp.h" 15289 #ifdef TPM_ALG_ECC 15290 Error Returns 15291 TPM_RC_ATTRIBUTES 15292 15293 keyHandle references a restricted key that is not a signing key 15294 15295 TPM_RC_ECC_POINT 15296 15297 either P1 or the point derived from s2 is not on the curve of 15298 keyHandle 15299 15300 TPM_RC_HASH 15301 15302 invalid name algorithm in keyHandle 15303 15304 TPM_RC_KEY 15305 15306 keyHandle does not reference an ECC key 15307 15308 TPM_RC_SCHEME 15309 15310 keyHandle references a restricted signing key that does not use and 15311 anonymous scheme 15312 15313 TPM_RC_NO_RESULT 15314 15315 K, L or E was a point at infinity; or failed to generate r value 15316 15317 TPM_RC_SIZE 15318 4 15319 5 15320 6 15321 7 15322 8 15323 9 15324 10 15325 11 15326 12 15327 13 15328 14 15329 15 15330 16 15331 17 15332 18 15333 19 15334 20 15335 21 15336 22 15337 23 15338 24 15339 25 15340 26 15341 27 15342 28 15343 29 15344 30 15345 31 15346 32 15347 33 15348 34 15349 35 15350 36 15351 37 15352 38 15353 39 15354 40 15355 41 15356 42 15357 43 15358 15359 Meaning 15360 15361 s2 is empty but y2 is not or s2 provided but y2 is not 15362 15363 TPM_RC 15364 TPM2_Commit( 15365 Commit_In 15366 Commit_Out 15367 15368 *in, 15369 *out 15370 15371 // IN: input parameter list 15372 // OUT: output parameter list 15373 15374 ) 15375 { 15376 OBJECT 15377 TPMS_ECC_POINT 15378 TPMS_ECC_POINT 15379 TPMS_ECC_POINT 15380 TPM2B_ECC_PARAMETER 15381 TPM2B 15382 TPM_RC 15383 UINT16 15384 15385 *eccKey; 15386 P2; 15387 *pP2 = NULL; 15388 *pP1 = NULL; 15389 r; 15390 *p; 15391 result; 15392 hashResults; 15393 15394 // Input Validation 15395 eccKey = ObjectGet(in->signHandle); 15396 // Input key must be an ECC key 15397 if(eccKey->publicArea.type != TPM_ALG_ECC) 15398 return TPM_RC_KEY + RC_Commit_signHandle; 15399 // if the key is restricted, it must be a signing key using an anonymous scheme 15400 if(eccKey->publicArea.objectAttributes.restricted == SET) 15401 { 15402 if(eccKey->publicArea.objectAttributes.sign != SET) 15403 return TPM_RC_ATTRIBUTES + RC_Commit_signHandle; 15404 if(!CryptIsSchemeAnonymous( 15405 eccKey->publicArea.parameters.eccDetail.scheme.scheme)) 15406 return TPM_RC_SCHEME + RC_Commit_signHandle; 15407 } 15408 else 15409 { 15410 // if not restricted, s2, and y2 must be an Empty Buffer 15411 if(in->s2.t.size) 15412 return TPM_RC_SIZE + RC_Commit_s2; 15413 } 15414 // Make sure that both parts of P2 are present if either is present 15415 if((in->s2.t.size == 0) != (in->y2.t.size == 0)) 15416 15417 Family 2.0 15418 Level 00 Revision 00.99 15419 15420 Published 15421 Copyright TCG 2006-2013 15422 15423 Page 181 15424 October 31, 2013 15425 15426 Part 3: Commands 15428 44 15429 45 15430 46 15431 47 15432 48 15433 49 15434 50 15435 51 15436 52 15437 53 15438 54 15439 55 15440 56 15441 57 15442 58 15443 59 15444 60 15445 61 15446 62 15447 63 15448 64 15449 65 15450 66 15451 67 15452 68 15453 69 15454 70 15455 71 15456 72 15457 73 15458 74 15459 75 15460 76 15461 77 15462 78 15463 79 15464 80 15465 81 15466 82 15467 83 15468 84 15469 85 15470 86 15471 87 15472 88 15473 89 15474 90 15475 91 15476 92 15477 93 15478 94 15479 95 15480 96 15481 97 15482 98 15483 99 15484 100 15485 101 15486 102 15487 103 15488 104 15489 105 15490 106 15491 107 15492 15493 Trusted Platform Module Library 15494 15495 return TPM_RC_SIZE + RC_Commit_y2; 15496 // Get prime modulus for the curve. This is needed later but getting this now 15497 // allows confirmation that the curve exists 15498 p = (TPM2B *)CryptEccGetParameter('p', 15499 eccKey->publicArea.parameters.eccDetail.curveID); 15500 // if no p, then the curve ID is bad 15501 // NOTE: This should never occur if the input unmarshaling code is working 15502 // correctly 15503 if(p == NULL) 15504 return TPM_RC_KEY + RC_Commit_signHandle; 15505 // Get the random value that will be used in the point multiplications 15506 // Note: this does not commit the count. 15507 if(!CryptGenerateR(&r, 15508 NULL, 15509 eccKey->publicArea.parameters.eccDetail.curveID, 15510 &eccKey->name)) 15511 return TPM_RC_NO_RESULT; 15512 // Set up P2 if s2 and Y2 are provided 15513 if(in->s2.t.size != 0) 15514 { 15515 pP2 = &P2; 15516 // copy y2 for P2 15517 MemoryCopy2B(&P2.y.b, &in->y2.b, sizeof(P2.y.t.buffer)); 15518 // Compute x2 HnameAlg(s2) mod p 15519 // 15520 do the hash operation on s2 with the size of curve 'p' 15521 hashResults = CryptHashBlock(eccKey->publicArea.nameAlg, 15522 in->s2.t.size, 15523 in->s2.t.buffer, 15524 p->size, 15525 P2.x.t.buffer); 15526 // If there were error returns in the hash routine, indicate a problem 15527 // with the hash in 15528 if(hashResults == 0) 15529 return TPM_RC_HASH + RC_Commit_signHandle; 15530 // set the size of the X value to the size of the hash 15531 P2.x.t.size = hashResults; 15532 // set p2.x = hash(s2) mod p 15533 if(CryptDivide(&P2.x.b, p, NULL, &P2.x.b) != TPM_RC_SUCCESS) 15534 return TPM_RC_NO_RESULT; 15535 if(!CryptEccIsPointOnCurve(eccKey->publicArea.parameters.eccDetail.curveID, 15536 pP2)) 15537 return TPM_RC_ECC_POINT + RC_Commit_s2; 15538 if(eccKey->attributes.publicOnly == SET) 15539 return TPM_RC_KEY + RC_Commit_signHandle; 15540 } 15541 else 15542 // If there is a P1, make sure that it is on the curve 15543 // NOTE: an "empty" point has two UINT16 values which are the size values 15544 // for each of the coordinates. 15545 if(in->P1.t.size > 4) 15546 { 15547 15548 Page 182 15549 October 31, 2013 15550 15551 Published 15552 Copyright TCG 2006-2013 15553 15554 Family 2.0 15555 Level 00 Revision 00.99 15556 15557 Trusted Platform Module Library 15559 108 15560 109 15561 110 15562 111 15563 112 15564 113 15565 114 15566 115 15567 116 15568 117 15569 118 15570 119 15571 120 15572 121 15573 122 15574 123 15575 124 15576 125 15577 126 15578 127 15579 128 15580 129 15581 130 15582 131 15583 132 15584 133 15585 134 15586 135 15587 136 15588 137 15589 138 15590 139 15591 15592 Part 3: Commands 15593 15594 pP1 = &in->P1.t.point; 15595 if(!CryptEccIsPointOnCurve(eccKey->publicArea.parameters.eccDetail.curveID, 15596 pP1)) 15597 return TPM_RC_ECC_POINT + RC_Commit_P1; 15598 } 15599 // Pass the parameters to CryptCommit. 15600 // The work is not done inline because it does several point multiplies 15601 // with the same curve. There is significant optimization by not 15602 // having to reload the curve parameters multiple times. 15603 result = CryptCommitCompute(&out->K.t.point, 15604 &out->L.t.point, 15605 &out->E.t.point, 15606 eccKey->publicArea.parameters.eccDetail.curveID, 15607 pP1, 15608 pP2, 15609 &eccKey->sensitive.sensitive.ecc, 15610 &r); 15611 if(result != TPM_RC_SUCCESS) 15612 return result; 15613 out->K.t.size = TPMS_ECC_POINT_Marshal(&out->K.t.point, NULL, NULL); 15614 out->L.t.size = TPMS_ECC_POINT_Marshal(&out->L.t.point, NULL, NULL); 15615 out->E.t.size = TPMS_ECC_POINT_Marshal(&out->E.t.point, NULL, NULL); 15616 // The commit computation was successful so complete the commit by setting 15617 // the bit 15618 out->counter = CryptCommit(); 15619 return TPM_RC_SUCCESS; 15620 } 15621 #endif 15622 15623 Family 2.0 15624 Level 00 Revision 00.99 15625 15626 Published 15627 Copyright TCG 2006-2013 15628 15629 Page 183 15630 October 31, 2013 15631 15632 Part 3: Commands 15634 15635 21.3 15636 15637 Trusted Platform Module Library 15638 15639 TPM2_EC_Ephemeral 15640 15641 21.3.1 General Description 15642 TPM2_EC_Ephemeral() creates an ephemeral key for use in a two-phase key exchange protocol. 15643 The TPM will use the commit mechanism to assign an ephemeral key r and compute a public point Q 15644 [r]G where G is the generator point associated with curveID. 15645 15646 Page 184 15647 October 31, 2013 15648 15649 Published 15650 Copyright TCG 2006-2013 15651 15652 Family 2.0 15653 Level 00 Revision 00.99 15654 15655 Trusted Platform Module Library 15657 15658 Part 3: Commands 15659 15660 21.3.2 Command and Response 15661 Table 91 TPM2_EC_Ephemeral Command 15662 Type 15663 15664 Name 15665 15666 Description 15667 15668 TPMI_ST_COMMAND_TAG 15669 15670 tag 15671 15672 UINT32 15673 15674 paramSize 15675 15676 TPM_CC 15677 15678 commandCode 15679 15680 TPM_CC_EC_Ephemeral 15681 15682 TPMI_ECC_CURVE 15683 15684 curveID 15685 15686 The curve for the computed ephemeral point 15687 15688 Table 92 TPM2_EC_Ephemeral Response 15689 Type 15690 15691 Name 15692 15693 Description 15694 15695 TPM_ST 15696 15697 tag 15698 15699 see 8 15700 15701 UINT32 15702 15703 paramSize 15704 15705 TPM_RC 15706 15707 responseCode 15708 15709 TPM2B_ECC_POINT 15710 15711 Q 15712 15713 ephemeral public key Q [r]G 15714 15715 UINT16 15716 15717 counter 15718 15719 least-significant 16 bits of commitCount 15720 15721 Family 2.0 15722 Level 00 Revision 00.99 15723 15724 Published 15725 Copyright TCG 2006-2013 15726 15727 Page 185 15728 October 31, 2013 15729 15730 Part 3: Commands 15732 15733 Trusted Platform Module Library 15734 15735 21.3.3 Detailed Actions 15736 1 15737 2 15738 3 15739 15740 #include "InternalRoutines.h" 15741 #include "EC_Ephemeral_fp.h" 15742 #ifdef TPM_ALG_ECC 15743 Error Returns 15744 none 15745 15746 4 15747 5 15748 6 15749 7 15750 8 15751 9 15752 10 15753 11 15754 12 15755 13 15756 14 15757 15 15758 16 15759 17 15760 18 15761 19 15762 20 15763 21 15764 22 15765 23 15766 24 15767 25 15768 26 15769 27 15770 15771 Meaning 15772 ... 15773 15774 TPM_RC 15775 TPM2_EC_Ephemeral( 15776 EC_Ephemeral_In 15777 EC_Ephemeral_Out 15778 15779 *in, 15780 *out 15781 15782 // IN: input parameter list 15783 // OUT: output parameter list 15784 15785 ) 15786 { 15787 TPM2B_ECC_PARAMETER 15788 15789 r; 15790 15791 // Get the random value that will be used in the point multiplications 15792 // Note: this does not commit the count. 15793 if(!CryptGenerateR(&r, 15794 NULL, 15795 in->curveID, 15796 NULL)) 15797 return TPM_RC_NO_RESULT; 15798 CryptEccPointMultiply(&out->Q.t.point, in->curveID, &r, NULL); 15799 // commit the count value 15800 out->counter = CryptCommit(); 15801 return TPM_RC_SUCCESS; 15802 } 15803 #endif 15804 15805 Page 186 15806 October 31, 2013 15807 15808 Published 15809 Copyright TCG 2006-2013 15810 15811 Family 2.0 15812 Level 00 Revision 00.99 15813 15814 Trusted Platform Module Library 15816 15817 22 15818 15819 Part 3: Commands 15820 15821 Signing and Signature Verification 15822 15823 22.1 15824 15825 TPM2_VerifySignature 15826 15827 22.1.1 General Description 15828 This command uses loaded keys to validate a signature on a message with the message digest passed 15829 to the TPM. 15830 If the signature check succeeds, then the TPM will produce a TPMT_TK_VERIFIED. Otherwise, the TPM 15831 shall return TPM_RC_SIGNATURE. 15832 NOTE 1 15833 15834 A valid ticket may be used in subsequent commands to provide proof to the TPM that the TPM has 15835 validated the signature over the message using the key referenced by keyHandle. 15836 15837 If keyHandle references an asymmetric key, only the public portion of the key needs to be loaded. If 15838 keyHandle references a symmetric key, both the public and private portions need to be loaded. 15839 NOTE 2 15840 15841 The sensitive area of the symmetric object is required to allow verification of the symmetric 15842 signature (the HMAC). 15843 15844 Family 2.0 15845 Level 00 Revision 00.99 15846 15847 Published 15848 Copyright TCG 2006-2013 15849 15850 Page 187 15851 October 31, 2013 15852 15853 Part 3: Commands 15855 15856 Trusted Platform Module Library 15857 15858 22.1.2 Command and Response 15859 Table 93 TPM2_VerifySignature Command 15860 Type 15861 15862 Name 15863 15864 Description 15865 15866 TPMI_ST_COMMAND_TAG 15867 15868 tag 15869 15870 UINT32 15871 15872 commandSize 15873 15874 TPM_CC 15875 15876 commandCode 15877 15878 TPM_CC_VerifySignature 15879 15880 TPMI_DH_OBJECT 15881 15882 keyHandle 15883 15884 handle of public key that will be used in the validation 15885 Auth Index: None 15886 15887 TPM2B_DIGEST 15888 15889 digest 15890 15891 digest of the signed message 15892 15893 TPMT_SIGNATURE 15894 15895 signature 15896 15897 signature to be tested 15898 15899 Table 94 TPM2_VerifySignature Response 15900 Type 15901 15902 Name 15903 15904 Description 15905 15906 TPM_ST 15907 15908 tag 15909 15910 see clause 8 15911 15912 UINT32 15913 15914 responseSize 15915 15916 TPM_RC 15917 15918 responseCode 15919 15920 TPMT_TK_VERIFIED 15921 15922 validation 15923 15924 Page 188 15925 October 31, 2013 15926 15927 Published 15928 Copyright TCG 2006-2013 15929 15930 Family 2.0 15931 Level 00 Revision 00.99 15932 15933 Trusted Platform Module Library 15935 15936 Part 3: Commands 15937 15938 22.1.3 Detailed Actions 15939 1 15940 2 15941 15942 #include "InternalRoutines.h" 15943 #include "VerifySignature_fp.h" 15944 Error Returns 15945 TPM_RC_ATTRIBUTES 15946 15947 keyHandle does not reference a signing key 15948 15949 TPM_RC_SIGNATURE 15950 15951 signature is not genuine 15952 15953 TPM_RC_SCHEME 15954 15955 CryptVerifySignature() 15956 15957 TPM_RC_HANDLE 15958 3 15959 4 15960 5 15961 6 15962 7 15963 8 15964 9 15965 10 15966 11 15967 12 15968 13 15969 14 15970 15 15971 16 15972 17 15973 18 15974 19 15975 20 15976 21 15977 22 15978 23 15979 24 15980 25 15981 26 15982 27 15983 28 15984 29 15985 30 15986 31 15987 32 15988 33 15989 34 15990 35 15991 36 15992 37 15993 38 15994 39 15995 40 15996 41 15997 42 15998 43 15999 44 16000 45 16001 46 16002 47 16003 48 16004 49 16005 16006 Meaning 16007 16008 the input handle is not a sign key with private portion loaded 16009 16010 TPM_RC 16011 TPM2_VerifySignature( 16012 VerifySignature_In 16013 VerifySignature_Out 16014 16015 *in, 16016 *out 16017 16018 // IN: input parameter list 16019 // OUT: output parameter list 16020 16021 TPM_RC 16022 TPM2B_NAME 16023 OBJECT 16024 TPMI_RH_HIERARCHY 16025 16026 result; 16027 name; 16028 *signObject; 16029 hierarchy; 16030 16031 ) 16032 { 16033 16034 // Input Validation 16035 // Get sign object pointer 16036 signObject = ObjectGet(in->keyHandle); 16037 // The object to validate the signature must be a signing key. 16038 if(signObject->publicArea.objectAttributes.sign != SET) 16039 return TPM_RC_ATTRIBUTES + RC_VerifySignature_keyHandle; 16040 // If it doesn't have a sensitive area loaded 16041 // then it can't be a keyed hash signing key 16042 if( 16043 signObject->attributes.publicOnly == SET 16044 && signObject->publicArea.type == TPM_ALG_KEYEDHASH 16045 ) 16046 return TPM_RC_HANDLE + RC_VerifySignature_keyHandle; 16047 // Validate Signature. A TPM_RC_BINDING, TPM_RC_SCHEME or TPM_RC_SIGNATURE 16048 // error may be returned by CryptCVerifySignatrue() 16049 result = CryptVerifySignature(in->keyHandle, &in->digest, &in->signature); 16050 if(result != TPM_RC_SUCCESS) 16051 return RcSafeAddToResult(result, RC_VerifySignature_signature); 16052 // Command Output 16053 hierarchy = ObjectGetHierarchy(in->keyHandle); 16054 if( 16055 hierarchy == TPM_RH_NULL 16056 || signObject->publicArea.nameAlg == TPM_ALG_NULL) 16057 { 16058 // produce empty ticket if hierarchy is TPM_RH_NULL or nameAlg is 16059 // TPM_ALG_NULL 16060 out->validation.tag = TPM_ST_VERIFIED; 16061 out->validation.hierarchy = TPM_RH_NULL; 16062 out->validation.digest.t.size = 0; 16063 } 16064 else 16065 { 16066 16067 Family 2.0 16068 Level 00 Revision 00.99 16069 16070 Published 16071 Copyright TCG 2006-2013 16072 16073 Page 189 16074 October 31, 2013 16075 16076 Part 3: Commands 16078 50 16079 51 16080 52 16081 53 16082 54 16083 55 16084 56 16085 57 16086 16087 Trusted Platform Module Library 16088 16089 // Get object name that verifies the signature 16090 name.t.size = ObjectGetName(in->keyHandle, &name.t.name); 16091 // Compute ticket 16092 TicketComputeVerified(hierarchy, &in->digest, &name, &out->validation); 16093 } 16094 return TPM_RC_SUCCESS; 16095 } 16096 16097 Page 190 16098 October 31, 2013 16099 16100 Published 16101 Copyright TCG 2006-2013 16102 16103 Family 2.0 16104 Level 00 Revision 00.99 16105 16106 Trusted Platform Module Library 16108 16109 22.2 16110 16111 Part 3: Commands 16112 16113 TPM2_Sign 16114 16115 22.2.1 General Description 16116 This command causes the TPM to sign an externally provided hash with the specified asymmetric signing 16117 key. 16118 NOTE 1 16119 16120 Symmetric signing is done with an HMAC. 16121 16122 If keyHandle references a restricted signing key, then validation shall be provided indicating that the TPM 16123 performed the hash of the data and validation shall indicate that hashed data did not start with 16124 TPM_GENERATED_VALUE. 16125 NOTE 2 16126 16127 If the hashed data did start with TPM_GENERATED_VALUE, then the validation will be a NULL 16128 ticket. 16129 16130 If the scheme of keyHandle is not TPM_ALG_NULL, then inScheme shall either be the same scheme as 16131 keyHandle or TPM_ALG_NULL. 16132 If the scheme of keyHandle is TPM_ALG_NULL, the TPM will sign using inScheme; otherwise, it will sign 16133 using the scheme of keyHandle. 16134 NOTE 3 16135 16136 When the signing scheme requires a hash algorithm, the hash is defined in the qualifying data of the 16137 scheme. 16138 16139 If inScheme is not a valid signing scheme for the type of keyHandle (or TPM_ALG_NULL), then the TPM 16140 shall return TPM_RC_SCHEME. 16141 If the scheme of keyHandle is an anonymous scheme, then inScheme shall have the same scheme 16142 algorithm as keyHandle and inScheme will contain a counter value that will be used in the signing 16143 process. 16144 As long as it is no larger than allowed, the digest parameter is not required to have any specific size but 16145 the signature operation may fail if digest is too large for the selected scheme. 16146 If the validation parameter is not the Empty Buffer, then it will be checked even if the key referenced by 16147 keyHandle is not a restricted signing key. 16148 16149 Family 2.0 16150 Level 00 Revision 00.99 16151 16152 Published 16153 Copyright TCG 2006-2013 16154 16155 Page 191 16156 October 31, 2013 16157 16158 Part 3: Commands 16160 16161 Trusted Platform Module Library 16162 16163 22.2.2 Command and Response 16164 Table 95 TPM2_Sign Command 16165 Type 16166 16167 Name 16168 16169 TPMI_ST_COMMAND_TAG 16170 16171 tag 16172 16173 UINT32 16174 16175 commandSize 16176 16177 TPM_CC 16178 16179 commandCode 16180 16181 TPM_CC_Sign 16182 16183 TPMI_DH_OBJECT 16184 16185 @keyHandle 16186 16187 Handle of key that will perform signing 16188 Auth Index: 1 16189 Auth Role: USER 16190 16191 TPM2B_DIGEST 16192 16193 digest 16194 16195 digest to be signed 16196 16197 TPMT_SIG_SCHEME+ 16198 16199 inScheme 16200 16201 signing scheme to use if the scheme for keyHandle is 16202 TPM_ALG_NULL 16203 16204 validation 16205 16206 proof that digest was created by the TPM 16207 If keyHandle is not a restricted signing key, then this 16208 may be a NULL Ticket with tag = 16209 TPM_ST_CHECKHASH. 16210 16211 TPMT_TK_HASHCHECK 16212 16213 Description 16214 16215 Table 96 TPM2_Sign Response 16216 Type 16217 16218 Name 16219 16220 Description 16221 16222 TPM_ST 16223 16224 tag 16225 16226 see clause 8 16227 16228 UINT32 16229 16230 responseSize 16231 16232 TPM_RC 16233 16234 responseCode 16235 16236 TPMT_SIGNATURE 16237 16238 signature 16239 16240 Page 192 16241 October 31, 2013 16242 16243 the signature 16244 16245 Published 16246 Copyright TCG 2006-2013 16247 16248 Family 2.0 16249 Level 00 Revision 00.99 16250 16251 Trusted Platform Module Library 16253 16254 Part 3: Commands 16255 16256 22.2.3 Detailed Actions 16257 1 16258 2 16259 3 16260 16261 #include "InternalRoutines.h" 16262 #include "Sign_fp.h" 16263 #include "Attest_spt_fp.h" 16264 Error Returns 16265 TPM_RC_ATTRIBUTES 16266 16267 key referenced by keHandle is not a signing key 16268 16269 TPM_RC_BINDING 16270 16271 The public and private portions of the key are not properly bound. 16272 16273 TPM_RC_SCHEME 16274 16275 inScheme is not compatible with keyHandle; both inScheme and 16276 key's default scheme are empty; or inScheme is empty while key's 16277 default scheme requires explicit input scheme (split signing); or nonempty default key scheme differs from inScheme 16278 16279 TPM_RC_TICKET 16280 16281 validation is not a valid ticket 16282 16283 TPM_RC_VALUE 16284 4 16285 5 16286 6 16287 7 16288 8 16289 9 16290 10 16291 11 16292 12 16293 13 16294 14 16295 15 16296 16 16297 17 16298 18 16299 19 16300 20 16301 21 16302 22 16303 23 16304 24 16305 25 16306 26 16307 27 16308 28 16309 29 16310 30 16311 31 16312 32 16313 33 16314 34 16315 35 16316 36 16317 37 16318 38 16319 39 16320 40 16321 41 16322 42 16323 43 16324 44 16325 16326 Meaning 16327 16328 the value to sign is larger than allowed for the type of keyHandle 16329 16330 TPM_RC 16331 TPM2_Sign( 16332 Sign_In 16333 Sign_Out 16334 16335 *in, 16336 *out 16337 16338 // IN: input parameter list 16339 // OUT: output parameter list 16340 16341 TPM_RC 16342 TPMT_TK_HASHCHECK 16343 OBJECT 16344 16345 result; 16346 ticket; 16347 *signKey; 16348 16349 ) 16350 { 16351 16352 // Input Validation 16353 // Get sign key pointer 16354 signKey = ObjectGet(in->keyHandle); 16355 // If validation is provided, or the key is restricted, check the ticket 16356 if( 16357 in->validation.digest.t.size != 0 16358 || signKey->publicArea.objectAttributes.restricted == SET) 16359 { 16360 // Compute and compare ticket 16361 TicketComputeHashCheck(in->validation.hierarchy, &in->digest, &ticket); 16362 if(!Memory2BEqual(&in->validation.digest.b, &ticket.digest.b)) 16363 return TPM_RC_TICKET + RC_Sign_validation; 16364 } 16365 // Command Output 16366 // pick a scheme for sign. If the input sign scheme is not compatible with 16367 // the default scheme, return an error. 16368 result = CryptSelectSignScheme(in->keyHandle, &in->inScheme); 16369 if(result != TPM_RC_SUCCESS) 16370 { 16371 if(result == TPM_RC_KEY) 16372 return TPM_RC_KEY + RC_Sign_keyHandle; 16373 else 16374 return RcSafeAddToResult(result, RC_Sign_inScheme); 16375 } 16376 // Sign the hash. A TPM_RC_VALUE, TPM_RC_SCHEME, or TPM_RC_ATTRIBUTES 16377 // error may be returned at this point 16378 result = CryptSign(in->keyHandle, &in->inScheme, &in->digest, &out->signature); 16379 16380 Family 2.0 16381 Level 00 Revision 00.99 16382 16383 Published 16384 Copyright TCG 2006-2013 16385 16386 Page 193 16387 October 31, 2013 16388 16389 Part 3: Commands 16391 45 16392 46 16393 47 16394 16395 Trusted Platform Module Library 16396 16397 return result; 16398 } 16399 16400 Page 194 16401 October 31, 2013 16402 16403 Published 16404 Copyright TCG 2006-2013 16405 16406 Family 2.0 16407 Level 00 Revision 00.99 16408 16409 Trusted Platform Module Library 16411 16412 23 16413 16414 Part 3: Commands 16415 16416 Command Audit 16417 16418 23.1 16419 16420 Introduction 16421 16422 If a command has been selected for command audit, the command audit status will be updated when that 16423 command completes successfully. The digest is updated as: 16424 16425 commandAuditDigestnew HauditAlg(commandAuditDigestold || cpHash || rpHash) 16426 16427 (5) 16428 16429 where 16430 16431 HauditAlg 16432 16433 hash function using the algorithm of the audit sequence 16434 16435 commandAuditDigest 16436 16437 accumulated digest 16438 16439 cpHash 16440 16441 the command parameter hash 16442 16443 rpHash 16444 16445 the response parameter hash 16446 16447 TPM2_Shutdown() cannot be audited but TPM2_Startup() can be audited. If the cpHash of the 16448 TPM2_Startup() is TPM_SU_STATE, that would indicate that a TPM2_Shutdown() had been successfully 16449 executed. 16450 TPM2_SetCommandCodeAuditStatus() is always audited. 16451 If the TPM is in Failure mode, command audit is not functional. 16452 16453 Family 2.0 16454 Level 00 Revision 00.99 16455 16456 Published 16457 Copyright TCG 2006-2013 16458 16459 Page 195 16460 October 31, 2013 16461 16462 Part 3: Commands 16464 16465 23.2 16466 16467 Trusted Platform Module Library 16468 16469 TPM2_SetCommandCodeAuditStatus 16470 16471 23.2.1 General Description 16472 This command may be used by the Privacy Administrator or platform to change the audit status of a 16473 command or to set the hash algorithm used for the audit digest, but not both at the same time. 16474 If the auditAlg parameter is a supported hash algorithm and not the same as the current algorithm, then 16475 the TPM will check both setList and clearList are empty (zero length). If so, then the algorithm is changed, 16476 and the audit digest is cleared. If auditAlg is TPM_ALG_NULL or the same as the current algorithm, then 16477 the algorithm and audit digest are unchanged and the setList and clearList will be processed. 16478 NOTE 1 16479 16480 Because the audit digest is cleared, the audit counter will increment the next time that an audited 16481 command is executed. 16482 16483 Use of TPM2_SetCommandCodeAuditStatus() to change the list of audited commands is an audited 16484 event. If TPM_CC_SetCommandCodeAuditStatus is in clearList, it is ignored. 16485 NOTE 2 16486 16487 Use of this command to change the audit hash algorithm is not audited and the digest is reset when 16488 the command completes. The change in the audit hash algorithm is the evidence that this command 16489 was used to change the algorithm. 16490 16491 The commands in setList indicate the commands that to be added to the list of audited commands and 16492 the commands in clearList indicate the commands that will no longer be audited. It is not an error if a 16493 command in setList is already audited or is not implemented. It is not an error if a command in clearList is 16494 not currently being audited or is not implemented. 16495 If a command code is in both setList and clearList, then it will not be audited (that is, setList shall be 16496 processed first). 16497 16498 Page 196 16499 October 31, 2013 16500 16501 Published 16502 Copyright TCG 2006-2013 16503 16504 Family 2.0 16505 Level 00 Revision 00.99 16506 16507 Trusted Platform Module Library 16509 16510 Part 3: Commands 16511 16512 23.2.2 Command and Response 16513 Table 97 TPM2_SetCommandCodeAuditStatus Command 16514 Type 16515 16516 Name 16517 16518 Description 16519 16520 TPMI_ST_COMMAND_TAG 16521 16522 tag 16523 16524 UINT32 16525 16526 commandSize 16527 16528 TPM_CC 16529 16530 commandCode 16531 16532 TPM_CC_SetCommandCodeAuditStatus {NV} 16533 16534 TPMI_RH_PROVISION 16535 16536 @auth 16537 16538 TPM_RH_ENDORSEMENT or 16539 TPM_RH_PLATFORM+{PP} 16540 Auth Index: 1 16541 Auth Role: USER 16542 16543 TPMI_ALG_HASH+ 16544 16545 auditAlg 16546 16547 hash algorithm for the audit digest; if 16548 TPM_ALG_NULL, then the hash is not changed 16549 16550 TPML_CC 16551 16552 setList 16553 16554 list of commands that will be added to those that will 16555 be audited 16556 16557 TPML_CC 16558 16559 clearList 16560 16561 list of commands that will no longer be audited 16562 16563 Table 98 TPM2_SetCommandCodeAuditStatus Response 16564 Type 16565 16566 Name 16567 16568 Description 16569 16570 TPM_ST 16571 16572 tag 16573 16574 see clause 8 16575 16576 UINT32 16577 16578 responseSize 16579 16580 TPM_RC 16581 16582 responseCode 16583 16584 Family 2.0 16585 Level 00 Revision 00.99 16586 16587 Published 16588 Copyright TCG 2006-2013 16589 16590 Page 197 16591 October 31, 2013 16592 16593 Part 3: Commands 16595 16596 Trusted Platform Module Library 16597 16598 23.2.3 Detailed Actions 16599 1 16600 2 16601 3 16602 4 16603 5 16604 6 16605 7 16606 8 16607 9 16608 10 16609 11 16610 12 16611 13 16612 14 16613 15 16614 16 16615 17 16616 18 16617 19 16618 20 16619 21 16620 22 16621 23 16622 24 16623 25 16624 26 16625 27 16626 28 16627 29 16628 30 16629 31 16630 32 16631 33 16632 34 16633 35 16634 36 16635 37 16636 38 16637 39 16638 40 16639 41 16640 42 16641 43 16642 44 16643 45 16644 46 16645 47 16646 48 16647 49 16648 50 16649 51 16650 52 16651 53 16652 54 16653 55 16654 56 16655 57 16656 58 16657 59 16658 60 16659 16660 #include "InternalRoutines.h" 16661 #include "SetCommandCodeAuditStatus_fp.h" 16662 16663 TPM_RC 16664 TPM2_SetCommandCodeAuditStatus( 16665 SetCommandCodeAuditStatus_In 16666 16667 *in 16668 16669 // IN: input parameter list 16670 16671 ) 16672 { 16673 TPM_RC 16674 UINT32 16675 BOOL 16676 16677 result; 16678 i; 16679 changed = FALSE; 16680 16681 // The command needs NV update. Check if NV is available. 16682 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 16683 // this point 16684 result = NvIsAvailable(); 16685 if(result != TPM_RC_SUCCESS) 16686 return result; 16687 // Internal Data Update 16688 // Update hash algorithm 16689 if( 16690 in->auditAlg != TPM_ALG_NULL 16691 && in->auditAlg != gp.auditHashAlg) 16692 { 16693 // Can't change the algorithm and command list at the same time 16694 if(in->setList.count != 0 || in->clearList.count != 0) 16695 return TPM_RC_VALUE + RC_SetCommandCodeAuditStatus_auditAlg; 16696 // Change the hash algorithm for audit 16697 gp.auditHashAlg = in->auditAlg; 16698 // Set the digest size to a unique value that indicates that the digest 16699 // algorithm has been changed. The size will be cleared to zero in the 16700 // command audit processing on exit. 16701 gr.commandAuditDigest.t.size = 1; 16702 // Save the change of command audit data (this sets g_updateNV so that NV 16703 // will be updagted on exit.) 16704 NvWriteReserved(NV_AUDIT_HASH_ALG, &gp.auditHashAlg); 16705 } else { 16706 // Process set list 16707 for(i = 0; i < in->setList.count; i++) 16708 // If change is made in CommandAuditSet, set changed flag 16709 if(CommandAuditSet(in->setList.commandCodes[i])) 16710 changed = TRUE; 16711 // Process clear list 16712 for(i = 0; i < in->clearList.count; i++) 16713 // If change is made in CommandAuditClear, set changed flag 16714 if(CommandAuditClear(in->clearList.commandCodes[i])) 16715 changed = TRUE; 16716 // if change was made to command list, update NV 16717 if(changed) 16718 // this sets g_updateNV so that NV will be updagted on exit. 16719 NvWriteReserved(NV_AUDIT_COMMANDS, &gp.auditComands); 16720 16721 Page 198 16722 October 31, 2013 16723 16724 Published 16725 Copyright TCG 2006-2013 16726 16727 Family 2.0 16728 Level 00 Revision 00.99 16729 16730 Trusted Platform Module Library 16732 61 16733 62 16734 63 16735 64 16736 16737 Part 3: Commands 16738 16739 } 16740 return TPM_RC_SUCCESS; 16741 } 16742 16743 Family 2.0 16744 Level 00 Revision 00.99 16745 16746 Published 16747 Copyright TCG 2006-2013 16748 16749 Page 199 16750 October 31, 2013 16751 16752 Part 3: Commands 16754 16755 24 16756 16757 Trusted Platform Module Library 16758 16759 Integrity Collection (PCR) 16760 16761 24.1 16762 16763 Introduction 16764 16765 In TPM 1.2, an Event was hashed using SHA-1 and then the 20-octet digest was extended to a PCR 16766 using TPM_Extend(). This specification allows the use of multiple PCR at a given Index, each using a 16767 different hash algorithm. Rather than require that the external software generate multiple hashes of the 16768 Event with each being extended to a different PCR, the Event data may be sent to the TPM for hashing. 16769 This ensures that the resulting digests will properly reflect the algorithms chosen for the PCR even if the 16770 calling software is unable to implement the hash algorithm. 16771 NOTE 1 16772 16773 There is continued support for software hashing of events with TPM2_PCR_Extend(). 16774 16775 To support recording of an Event that is larger than the TPM input buffer, the caller may use the 16776 command sequence described in clause 1. 16777 Change to a PCR requires authorization. The authorization may be with either an authorization value or 16778 an authorization policy. The platform-specific specifications determine which PCR may be controlled by 16779 policy. All other PCR are controlled by authorization. 16780 If a PCR may be associated with a policy, then the algorithm ID of that policy determines whether the 16781 policy is to be applied. If the algorithm ID is not TPM_ALG_NULL, then the policy digest associated with 16782 the PCR must match the policySessionpolicyDigest in a policy session. If the algorithm ID is 16783 TPM_ALG_NULL, then no policy is present and the authorization requires an EmptyAuth. 16784 If a platform-specific specification indicates that PCR are grouped, then all the PCR in the group use the 16785 same authorization policy or authorization value. 16786 PcrUpdateCounter counter will be incremented on the successful completion of any command that 16787 modifies (Extends or resets) a PCR unless the platform-specific specification explicitly excludes the PCR 16788 from being counted. 16789 NOTE 2 16790 16791 If a command causes PCR in multiple banks to change, the PCR Update Counter may be 16792 incremented either once or once for each bank. 16793 16794 A platform-specific specification may designate a set of PCR that are under control of the TCB. These 16795 PCR may not be modified without the proper authorization. Updates of these PCR shall not cause the 16796 PCR Update Counter to increment. 16797 EXAMPLE 16798 16799 Updates of the TCB PCR will not cause the PCR update counter to increment b ecause these PCR 16800 are changed at the whim of the TCB and are not intended to represent the trust state of the platform. 16801 16802 Page 200 16803 October 31, 2013 16804 16805 Published 16806 Copyright TCG 2006-2013 16807 16808 Family 2.0 16809 Level 00 Revision 00.99 16810 16811 Trusted Platform Module Library 16813 16814 24.2 16815 16816 Part 3: Commands 16817 16818 TPM2_PCR_Extend 16819 16820 24.2.1 General Description 16821 This command is used to cause an update to the indicated PCR. The digests parameter contains one or 16822 more tagged digest value identified by an algorithm ID. For each digest, the PCR associated with 16823 pcrHandle is Extended into the bank identified by the tag (hashAlg). 16824 EXAMPLE 16825 16826 A SHA1 digest would be Extended into the SHA1 bank and a SHA256 digest would be Extended into 16827 a SHA256 bank. 16828 16829 For each list entry, the TPM will check to see if pcrNum is implemented for that algorithm. If so, the TPM 16830 shall perform the following operation: 16831 16832 PCR.digestnew [pcrNum][alg] Halg(PCR.digestold [pcrNum][alg] || data[alg].buffer)) 16833 16834 (6) 16835 16836 where 16837 16838 Halg() 16839 16840 hash function using the hash algorithm associated with the PCR 16841 instance 16842 16843 PCR.digest 16844 16845 the digest value in a PCR 16846 16847 pcrNum 16848 16849 the PCR numeric 16850 TPM_RH_PCR0) 16851 16852 alg 16853 16854 the PCR algorithm selector for the digest 16855 16856 data[alg].buffer 16857 16858 the bank-specific data to be extended 16859 16860 selector 16861 16862 (equal 16863 16864 to 16865 16866 pcrHandle 16867 16868 16869 16870 If no digest value is specified for a bank, then the PCR in that bank are not modified. 16871 NOTE 1 16872 16873 This allows consistent operation of the digests list for all of the Event recording commands. 16874 16875 If a digest is present and the PCR in that bank is not implemented, the digest value is not used. 16876 NOTE 2 16877 16878 If the caller includes digests for algorithms that are not implemented, then the TPM will fail the call 16879 because the unmarshalling of digests will fail. Each of the entries in the list is a TPMT_HA which is a 16880 hash algorithm followed by a digest. If the algorithm is not implemented, unmarshalling of the 16881 hashAlg will fail and the TPM will return TPM_RC_HASH. 16882 16883 If the TPM unmarshals the hashAlg of a list entry and the unmarshaled value is not a hash algorithm 16884 implemented on the TPM, the TPM shall return TPM_RC_HASH. 16885 The pcrHandle parameter is allowed to reference TPM_RH_NULL. If so, the input parameters are 16886 processed but no action is taken by the TPM. 16887 NOTE 3 16888 16889 This command allows a list of digests so that PCR in all banks may be updated in a single 16890 command. While the semantics of this command allow multiple extends to a single PCR bank, this is 16891 not the preferred use and the limit on the number of entries in the list make this use somewhat 16892 impractical. 16893 16894 Family 2.0 16895 Level 00 Revision 00.99 16896 16897 Published 16898 Copyright TCG 2006-2013 16899 16900 Page 201 16901 October 31, 2013 16902 16903 Part 3: Commands 16905 16906 Trusted Platform Module Library 16907 16908 24.2.2 Command and Response 16909 Table 99 TPM2_PCR_Extend Command 16910 Type 16911 16912 Name 16913 16914 Description 16915 16916 TPMI_ST_COMMAND_TAG 16917 16918 tag 16919 16920 UINT32 16921 16922 commandSize 16923 16924 TPM_CC 16925 16926 commandCode 16927 16928 TPM_CC_PCR_Extend {NV} 16929 16930 TPMI_DH_PCR+ 16931 16932 @pcrHandle 16933 16934 handle of the PCR 16935 Auth Handle: 1 16936 Auth Role: USER 16937 16938 TPML_DIGEST_VALUES 16939 16940 digests 16941 16942 list of tagged digest values to be extended 16943 16944 Table 100 TPM2_PCR_Extend Response 16945 Type 16946 16947 Name 16948 16949 Description 16950 16951 TPM_ST 16952 16953 tag 16954 16955 see clause 8 16956 16957 UINT32 16958 16959 responseSize 16960 16961 TPM_RC 16962 16963 responseCode 16964 16965 Page 202 16966 October 31, 2013 16967 16968 . 16969 16970 Published 16971 Copyright TCG 2006-2013 16972 16973 Family 2.0 16974 Level 00 Revision 00.99 16975 16976 Trusted Platform Module Library 16978 16979 Part 3: Commands 16980 16981 24.2.3 Detailed Actions 16982 1 16983 2 16984 16985 #include "InternalRoutines.h" 16986 #include "PCR_Extend_fp.h" 16987 Error Returns 16988 TPM_RC_LOCALITY 16989 16990 3 16991 4 16992 5 16993 6 16994 7 16995 8 16996 9 16997 10 16998 11 16999 12 17000 13 17001 14 17002 15 17003 16 17004 17 17005 18 17006 19 17007 20 17008 21 17009 22 17010 23 17011 24 17012 25 17013 26 17014 27 17015 28 17016 29 17017 30 17018 31 17019 32 17020 33 17021 34 17022 35 17023 36 17024 37 17025 38 17026 39 17027 40 17028 41 17029 42 17030 43 17031 44 17032 45 17033 46 17034 47 17035 48 17036 49 17037 17038 Meaning 17039 current command locality is not allowed to extend the PCR 17040 referenced by pcrHandle 17041 17042 TPM_RC 17043 TPM2_PCR_Extend( 17044 PCR_Extend_In 17045 17046 *in 17047 17048 // IN: input parameter list 17049 17050 ) 17051 { 17052 TPM_RC 17053 UINT32 17054 17055 result; 17056 i; 17057 17058 // Input Validation 17059 // 17060 // 17061 // 17062 // 17063 // 17064 // 17065 // 17066 17067 NOTE: This function assumes that the unmarshaling function for 'digests' will 17068 have validated that all of the indicated hash algorithms are valid. If the 17069 hash algorithms are correct, the unmarshaling code will unmarshal a digest 17070 of the size indicated by the hash algorithm. If the overall size is not 17071 consistent, the unmarshaling code will run out of input data or have input 17072 data left over. In either case, it will cause an unmarshaling error and this 17073 function will not be called. 17074 17075 // For NULL handle, do nothing and return success 17076 if(in->pcrHandle == TPM_RH_NULL) 17077 return TPM_RC_SUCCESS; 17078 // Check if the extend operation is allowed by the current command locality 17079 if(!PCRIsExtendAllowed(in->pcrHandle)) 17080 return TPM_RC_LOCALITY; 17081 // If PCR is state saved and we need to update orderlyState, check NV 17082 // availability 17083 if(PCRIsStateSaved(in->pcrHandle) && gp.orderlyState != SHUTDOWN_NONE) 17084 { 17085 result = NvIsAvailable(); 17086 if(result != TPM_RC_SUCCESS) return result; 17087 g_clearOrderly = TRUE; 17088 } 17089 // Internal Data Update 17090 // Iterate input digest list to extend 17091 for(i = 0; i < in->digests.count; i++) 17092 { 17093 PCRExtend(in->pcrHandle, in->digests.digests[i].hashAlg, 17094 CryptGetHashDigestSize(in->digests.digests[i].hashAlg), 17095 (BYTE *) &in->digests.digests[i].digest); 17096 } 17097 return TPM_RC_SUCCESS; 17098 } 17099 17100 Family 2.0 17101 Level 00 Revision 00.99 17102 17103 Published 17104 Copyright TCG 2006-2013 17105 17106 Page 203 17107 October 31, 2013 17108 17109 Part 3: Commands 17111 17112 24.3 17113 17114 Trusted Platform Module Library 17115 17116 TPM2_PCR_Event 17117 17118 24.3.1 General Description 17119 This command is used to cause an update to the indicated PCR. 17120 The data in eventData is hashed using the hash algorithm associated with each bank in which the 17121 indicated PCR has been allocated. After the data is hashed, the digests list is returned. If the pcrHandle 17122 references an implemented PCR and not TPM_ALG_NULL, digests list is processed as in 17123 TPM2_PCR_Extend(). 17124 A TPM shall support an Event.size of zero through 1,024 inclusive (Event.size is an octet count). An 17125 Event.size of zero indicates that there is no data but the indicated operations will still occur, 17126 EXAMPLE 1 17127 17128 If the command implements PCR[2] in a SHA1 bank and a SHA256 bank, then an extend to PCR[2] 17129 will cause eventData to be hashed twice, once with SHA1 and once with SHA256. The SHA1 hash of 17130 eventData will be Extended to PCR[2] in the SHA1 bank and the SHA256 hash of eventData will be 17131 Extended to PCR[2] of the SHA256 bank. 17132 17133 On successful command completion, digests will contain the list of tagged digests of eventData that was 17134 computed in preparation for extending the data into the PCR. At the option of the TPM, the list may 17135 contain a digest for each bank, or it may only contain a digest for each bank in which pcrHandle is extant. 17136 EXAMPLE 2 17137 17138 Assume a TPM that implements a SHA1 bank and a SHA256 bank and that PCR[22] is only 17139 implemented in the SHA1 bank. If pcrHandle references PCR[22], then digests may contain either a 17140 SHA1 and a SHA256 digest or just a SHA1 digest. 17141 17142 Page 204 17143 October 31, 2013 17144 17145 Published 17146 Copyright TCG 2006-2013 17147 17148 Family 2.0 17149 Level 00 Revision 00.99 17150 17151 Trusted Platform Module Library 17153 17154 Part 3: Commands 17155 17156 24.3.2 Command and Response 17157 Table 101 TPM2_PCR_Event Command 17158 Type 17159 17160 Name 17161 17162 Description 17163 17164 TPMI_ST_COMMAND_TAG 17165 17166 tag 17167 17168 UINT32 17169 17170 commandSize 17171 17172 TPM_CC 17173 17174 commandCode 17175 17176 TPM_CC_PCR_Event {NV} 17177 17178 TPMI_DH_PCR+ 17179 17180 @pcrHandle 17181 17182 Handle of the PCR 17183 Auth Handle: 1 17184 Auth Role: USER 17185 17186 TPM2B_EVENT 17187 17188 eventData 17189 17190 Event data in sized buffer 17191 17192 Table 102 TPM2_PCR_Event Response 17193 Type 17194 17195 Name 17196 17197 Description 17198 17199 TPM_ST 17200 17201 tag 17202 17203 see clause 8 17204 17205 UINT32 17206 17207 responseSize 17208 17209 TPM_RC 17210 17211 responseCode 17212 17213 TPML_DIGEST_VALUES 17214 17215 digests 17216 17217 Family 2.0 17218 Level 00 Revision 00.99 17219 17220 . 17221 17222 Published 17223 Copyright TCG 2006-2013 17224 17225 Page 205 17226 October 31, 2013 17227 17228 Part 3: Commands 17230 17231 Trusted Platform Module Library 17232 17233 24.3.3 Detailed Actions 17234 1 17235 2 17236 17237 #include "InternalRoutines.h" 17238 #include "PCR_Event_fp.h" 17239 Error Returns 17240 TPM_RC_LOCALITY 17241 17242 3 17243 4 17244 5 17245 6 17246 7 17247 8 17248 9 17249 10 17250 11 17251 12 17252 13 17253 14 17254 15 17255 16 17256 17 17257 18 17258 19 17259 20 17260 21 17261 22 17262 23 17263 24 17264 25 17265 26 17266 27 17267 28 17268 29 17269 30 17270 31 17271 32 17272 33 17273 34 17274 35 17275 36 17276 37 17277 38 17278 39 17279 40 17280 41 17281 42 17282 43 17283 44 17284 45 17285 46 17286 47 17287 48 17288 49 17289 50 17290 51 17291 52 17292 17293 Meaning 17294 current command locality is not allowed to extend the PCR 17295 referenced by pcrHandle 17296 17297 TPM_RC 17298 TPM2_PCR_Event( 17299 PCR_Event_In 17300 PCR_Event_Out 17301 17302 *in, 17303 *out 17304 17305 // IN: input parameter list 17306 // OUT: output parameter list 17307 17308 ) 17309 { 17310 TPM_RC 17311 HASH_STATE 17312 UINT32 17313 UINT16 17314 17315 result; 17316 hashState; 17317 i; 17318 size; 17319 17320 // Input Validation 17321 // If a PCR extend is required 17322 if(in->pcrHandle != TPM_RH_NULL) 17323 { 17324 // If the PCR is not allow to extend, return error 17325 if(!PCRIsExtendAllowed(in->pcrHandle)) 17326 return TPM_RC_LOCALITY; 17327 // If PCR is state saved and we need to update orderlyState, check NV 17328 // availability 17329 if(PCRIsStateSaved(in->pcrHandle) && gp.orderlyState != SHUTDOWN_NONE) 17330 { 17331 result = NvIsAvailable(); 17332 if(result != TPM_RC_SUCCESS) return result; 17333 g_clearOrderly = TRUE; 17334 } 17335 } 17336 // Internal Data Update 17337 out->digests.count = HASH_COUNT; 17338 // Iterate supported PCR bank algorithms to extend 17339 for(i = 0; i < HASH_COUNT; i++) 17340 { 17341 TPM_ALG_ID hash = CryptGetHashAlgByIndex(i); 17342 out->digests.digests[i].hashAlg = hash; 17343 size = CryptStartHash(hash, &hashState); 17344 CryptUpdateDigest2B(&hashState, &in->eventData.b); 17345 CryptCompleteHash(&hashState, size, 17346 (BYTE *) &out->digests.digests[i].digest); 17347 if(in->pcrHandle != TPM_RH_NULL) 17348 PCRExtend(in->pcrHandle, hash, size, 17349 (BYTE *) &out->digests.digests[i].digest); 17350 } 17351 return TPM_RC_SUCCESS; 17352 } 17353 17354 Page 206 17355 October 31, 2013 17356 17357 Published 17358 Copyright TCG 2006-2013 17359 17360 Family 2.0 17361 Level 00 Revision 00.99 17362 17363 Trusted Platform Module Library 17365 17366 24.4 17367 17368 Part 3: Commands 17369 17370 TPM2_PCR_Read 17371 17372 24.4.1 General Description 17373 This command returns the values of all PCR specified in pcrSelect. 17374 The TPM will process the list of TPMS_PCR_SELECTION in pcrSelectionIn in order. Within each 17375 TPMS_PCR_SELECTION, the TPM will process the bits in the pcrSelect array in ascending PCR order 17376 (see Part 2 for definition of the PCR order). If a bit is SET, and the indicated PCR is present, then the 17377 TPM will add the digest of the PCR to the list of values to be returned in pcrValue. 17378 The TPM will continue processing bits until all have been processed or until pcrValues would be too large 17379 to fit into the output buffer if additional values were added. 17380 The returned pcrSelectionOut will have a bit SET in its pcrSelect structures for each value present in 17381 pcrValues. 17382 The current value of the PCR Update Counter is returned in pcrUpdateCounter. 17383 The returned list may be empty if none of the selected PCR are implemented. 17384 NOTE 17385 17386 If no PCR are returned from a bank, the selector for the bank will be present in pcrSelectionOut. 17387 17388 No authorization is required to read a PCR and any implemented PCR may be read from any locality. 17389 17390 Family 2.0 17391 Level 00 Revision 00.99 17392 17393 Published 17394 Copyright TCG 2006-2013 17395 17396 Page 207 17397 October 31, 2013 17398 17399 Part 3: Commands 17401 17402 Trusted Platform Module Library 17403 17404 24.4.2 Command and Response 17405 Table 103 TPM2_PCR_Read Command 17406 Type 17407 17408 Name 17409 17410 Description 17411 17412 TPMI_ST_COMMAND_TAG 17413 17414 tag 17415 17416 UINT32 17417 17418 commandSize 17419 17420 TPM_CC 17421 17422 commandCode 17423 17424 TPM_CC_PCR_Read 17425 17426 TPML_PCR_SELECTION 17427 17428 pcrSelectionIn 17429 17430 The selection of PCR to read 17431 17432 Table 104 TPM2_PCR_Read Response 17433 Type 17434 17435 Name 17436 17437 Description 17438 17439 TPM_ST 17440 17441 tag 17442 17443 see clause 8 17444 17445 UINT32 17446 17447 responseSize 17448 17449 TPM_RC 17450 17451 responseCode 17452 17453 UINT32 17454 17455 pcrUpdateCounter 17456 17457 the current value of the PCR update counter 17458 17459 TPML_PCR_SELECTION 17460 17461 pcrSelectionOut 17462 17463 the PCR in the returned list 17464 17465 TPML_DIGEST 17466 17467 pcrValues 17468 17469 the contents of the PCR indicated in pcrSelect as 17470 tagged digests 17471 17472 Page 208 17473 October 31, 2013 17474 17475 Published 17476 Copyright TCG 2006-2013 17477 17478 Family 2.0 17479 Level 00 Revision 00.99 17480 17481 Trusted Platform Module Library 17483 17484 Part 3: Commands 17485 17486 24.4.3 Detailed Actions 17487 1 17488 2 17489 3 17490 4 17491 5 17492 6 17493 7 17494 8 17495 9 17496 10 17497 11 17498 12 17499 13 17500 14 17501 15 17502 16 17503 17 17504 18 17505 17506 #include "InternalRoutines.h" 17507 #include "PCR_Read_fp.h" 17508 17509 TPM_RC 17510 TPM2_PCR_Read( 17511 PCR_Read_In 17512 PCR_Read_Out 17513 17514 *in, 17515 *out 17516 17517 // IN: input parameter list 17518 // OUT: output parameter list 17519 17520 ) 17521 { 17522 // Command Output 17523 // Call PCR read function. input pcrSelectionIn parameter could be changed 17524 // to reflect the actual PCR being returned 17525 PCRRead(&in->pcrSelectionIn, &out->pcrValues, &out->pcrUpdateCounter); 17526 out->pcrSelectionOut = in->pcrSelectionIn; 17527 return TPM_RC_SUCCESS; 17528 } 17529 17530 Family 2.0 17531 Level 00 Revision 00.99 17532 17533 Published 17534 Copyright TCG 2006-2013 17535 17536 Page 209 17537 October 31, 2013 17538 17539 Part 3: Commands 17541 17542 24.5 17543 17544 Trusted Platform Module Library 17545 17546 TPM2_PCR_Allocate 17547 17548 24.5.1 General Description 17549 This command is used to set the desired PCR allocation of PCR and algorithms. This command requires 17550 platformAuth. 17551 The TPM will evaluate the request and, if sufficient memory is available for the requested allocation, the 17552 TPM will store the allocation request for use during the next TPM2_Startup(TPM_SU_CLEAR) operation. 17553 The PCR allocation in place when this command is executed will be retained until the next 17554 TPM2_Startup(TPM_SU_CLEAR). 17555 If no allocation is specified for a bank, then no PCR will be allocated to that bank. If a bank is listed more 17556 than once, then the last selection in the pcrAllocation list is the one that the TPM will attempt to allocate. 17557 This command shall not allocate more PCR in any bank than there are PCR attribute definitions. The 17558 PCR attribute definitions indicate how a PCR is to be managed if it is resettable, the locality for update, 17559 etc. In the response to this command, the TPM returns the maximum number of PCR allowed for any 17560 bank. 17561 If the command is properly authorized, it will return SUCCESS even though the request fails. This is to 17562 allow the TPM to return information about the size needed for the requested allocation and the size 17563 available. If the sizeNeeded parameter in the return is less than or equal to the sizeAvailable parameter, 17564 then the allocationSuccess parameter will be YES. 17565 After this command, TPM2_Shutdown() is only allowed to have a startupType equal to TPM_SU_CLEAR. 17566 NOTE 17567 17568 Even if this command does not cause the PCR allocation to change, the TPM cannot have its state 17569 saved. This is done in order to simplify the implementation. There is no need to optimize this 17570 command as it is not expected to be used more than once in the lifetime of the TPM (it can be used 17571 any number of times but there is no justification for optimization) . 17572 17573 Page 210 17574 October 31, 2013 17575 17576 Published 17577 Copyright TCG 2006-2013 17578 17579 Family 2.0 17580 Level 00 Revision 00.99 17581 17582 Trusted Platform Module Library 17584 17585 Part 3: Commands 17586 17587 24.5.2 Command and Response 17588 Table 105 TPM2_PCR_Allocate Command 17589 Type 17590 17591 Name 17592 17593 Description 17594 17595 TPMI_ST_COMMAND_TAG 17596 17597 tag 17598 17599 UINT32 17600 17601 commandSize 17602 17603 TPM_CC 17604 17605 commandCode 17606 17607 TPM_CC_PCR_Allocate {NV} 17608 17609 TPMI_RH_PLATFORM 17610 17611 @authHandle 17612 17613 TPM_RH_PLATFORM+{PP} 17614 Auth Index: 1 17615 Auth Role: USER 17616 17617 TPML_PCR_SELECTION 17618 17619 pcrAllocation 17620 17621 the requested allocation 17622 17623 Table 106 TPM2_PCR_Allocate Response 17624 Type 17625 17626 Name 17627 17628 Description 17629 17630 TPM_ST 17631 17632 tag 17633 17634 see clause 8 17635 17636 UINT32 17637 17638 responseSize 17639 17640 TPM_RC 17641 17642 responseCode 17643 17644 TPMI_YES_NO 17645 17646 allocationSuccess 17647 17648 YES if the allocation succeeded 17649 17650 UINT32 17651 17652 maxPCR 17653 17654 maximum number of PCR that may be in a bank 17655 17656 UINT32 17657 17658 sizeNeeded 17659 17660 number of octets required to satisfy the request 17661 17662 UINT32 17663 17664 sizeAvailable 17665 17666 Number of octets available. Computed before the 17667 allocation. 17668 17669 Family 2.0 17670 Level 00 Revision 00.99 17671 17672 Published 17673 Copyright TCG 2006-2013 17674 17675 Page 211 17676 October 31, 2013 17677 17678 Part 3: Commands 17680 17681 Trusted Platform Module Library 17682 17683 24.5.3 Detailed Actions 17684 1 17685 2 17686 3 17687 4 17688 5 17689 6 17690 7 17691 8 17692 9 17693 10 17694 11 17695 12 17696 13 17697 14 17698 15 17699 16 17700 17 17701 18 17702 19 17703 20 17704 21 17705 22 17706 23 17707 24 17708 25 17709 26 17710 27 17711 28 17712 29 17713 30 17714 31 17715 32 17716 33 17717 34 17718 17719 #include "InternalRoutines.h" 17720 #include "PCR_Allocate_fp.h" 17721 17722 TPM_RC 17723 TPM2_PCR_Allocate( 17724 PCR_Allocate_In 17725 PCR_Allocate_Out 17726 17727 *in, 17728 *out 17729 17730 // IN: input parameter list 17731 // OUT: output parameter list 17732 17733 ) 17734 { 17735 TPM_RC 17736 17737 result; 17738 17739 // The command needs NV update. Check if NV is available. 17740 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 17741 // this point. 17742 // Note: These codes are not listed in the return values above because it is 17743 // an implementation choice to check in this routine rather than in a common 17744 // function that is called before these actions are called. These return values 17745 // are described in the Response Code section of Part 3. 17746 result = NvIsAvailable(); 17747 if(result != TPM_RC_SUCCESS) 17748 return result; 17749 // Command Output 17750 // Call PCR Allocation function. 17751 out->allocationSuccess = PCRAllocate(&in->pcrAllocation, &out->maxPCR, 17752 &out->sizeNeeded, &out->sizeAvailable); 17753 // if re-configuration succeeds, set the flag to indicate PCR configuration is 17754 // going to be changed in next boot 17755 if(out->allocationSuccess == YES) 17756 g_pcrReConfig = TRUE; 17757 return TPM_RC_SUCCESS; 17758 } 17759 17760 Page 212 17761 October 31, 2013 17762 17763 Published 17764 Copyright TCG 2006-2013 17765 17766 Family 2.0 17767 Level 00 Revision 00.99 17768 17769 Trusted Platform Module Library 17771 17772 24.6 17773 17774 Part 3: Commands 17775 17776 TPM2_PCR_SetAuthPolicy 17777 17778 24.6.1 General Description 17779 This command is used to associate a policy with a PCR or group of PCR. The policy determines the 17780 conditions under which a PCR may be extended or reset. 17781 A policy may only be associated with a PCR that has been defined by a platform-specific specification as 17782 allowing a policy. If the TPM implementation does not allow a policy for pcrNum, the TPM shall return 17783 TPM_RC_VALUE. 17784 A platform-specific specification may group PCR so that they share a common policy. In such case, a 17785 pcrNum that selects any of the PCR in the group will change the policy for all PCR in the group. 17786 The policy setting is persistent and may only be changed by TPM2_PCR_SetAuthPolicy() or by 17787 TPM2_ChangePPS(). 17788 Before this command is first executed on a TPM or after TPM2_ChangePPS(), the access control on the 17789 PCR will be set to the default value defined in the platform-specific specification. 17790 NOTE 1 17791 17792 It is expected that the typical default will be with the policy hash set to TPM_ALG_NULL and an 17793 Empty Buffer for the authPolicy value. This will allow an EmptyAuth to be used as the authorization 17794 value. 17795 17796 If the size of the data buffer in authPolicy is not the size of a digest produced by hashAlg, the TPM shall 17797 return TPM_RC_SIZE. 17798 NOTE 2 17799 17800 If hashAlg is TPM_ALG_NULL, then the size is required to be zero. 17801 17802 This command requires platformAuth/platformPolicy. 17803 NOTE 3 17804 17805 If the PCR is in multiple policy sets, the policy will be changed in only one set. The set that is 17806 changed will be implementation dependent. 17807 17808 Family 2.0 17809 Level 00 Revision 00.99 17810 17811 Published 17812 Copyright TCG 2006-2013 17813 17814 Page 213 17815 October 31, 2013 17816 17817 Part 3: Commands 17819 17820 Trusted Platform Module Library 17821 17822 24.6.2 Command and Response 17823 Table 107 TPM2_PCR_SetAuthPolicy Command 17824 Type 17825 17826 Name 17827 17828 Description 17829 17830 TPMI_ST_COMMAND_TAG 17831 17832 tag 17833 17834 UINT32 17835 17836 commandSize 17837 17838 TPM_CC 17839 17840 commandCode 17841 17842 TPM_CC_PCR_SetAuthPolicy {NV} 17843 17844 TPMI_RH_PLATFORM 17845 17846 @authHandle 17847 17848 TPM_RH_PLATFORM+{PP} 17849 Auth Index: 1 17850 Auth Role: USER 17851 17852 TPM2B_DIGEST 17853 17854 authPolicy 17855 17856 the desired authPolicy 17857 17858 TPMI_ALG_HASH+ 17859 17860 policyDigest 17861 17862 the digest of the policy 17863 17864 TPMI_DH_PCR 17865 17866 pcrNum 17867 17868 the PCR for which the policy is to be set 17869 17870 Table 108 TPM2_PCR_SetAuthPolicy Response 17871 Type 17872 17873 Name 17874 17875 Description 17876 17877 TPM_ST 17878 17879 tag 17880 17881 see clause 8 17882 17883 UINT32 17884 17885 responseSize 17886 17887 TPM_RC 17888 17889 responseCode 17890 17891 Page 214 17892 October 31, 2013 17893 17894 Published 17895 Copyright TCG 2006-2013 17896 17897 Family 2.0 17898 Level 00 Revision 00.99 17899 17900 Trusted Platform Module Library 17902 17903 Part 3: Commands 17904 17905 24.6.3 Detailed Actions 17906 1 17907 2 17908 17909 #include "InternalRoutines.h" 17910 #include "PCR_SetAuthPolicy_fp.h" 17911 Error Returns 17912 TPM_RC_SIZE 17913 17914 size of authPolicy is not the size of a digest produced by policyDigest 17915 17916 TPM_RC_VALUE 17917 3 17918 4 17919 5 17920 6 17921 7 17922 8 17923 9 17924 10 17925 11 17926 12 17927 13 17928 14 17929 15 17930 16 17931 17 17932 18 17933 19 17934 20 17935 21 17936 22 17937 23 17938 24 17939 25 17940 26 17941 27 17942 28 17943 29 17944 30 17945 31 17946 32 17947 33 17948 34 17949 35 17950 36 17951 37 17952 38 17953 17954 Meaning 17955 17956 PCR referenced by pcrNum is not a member of a PCR policy group 17957 17958 TPM_RC 17959 TPM2_PCR_SetAuthPolicy( 17960 PCR_SetAuthPolicy_In 17961 17962 *in 17963 17964 // IN: input parameter list 17965 17966 ) 17967 { 17968 UINT32 17969 17970 groupIndex; 17971 17972 TPM_RC 17973 17974 result; 17975 17976 // The command needs NV update. Check if NV is available. 17977 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 17978 // this point 17979 result = NvIsAvailable(); 17980 if(result != TPM_RC_SUCCESS) return result; 17981 // Input Validation: 17982 // Check the authPolicy consistent with hash algorithm 17983 if(in->authPolicy.t.size != CryptGetHashDigestSize(in->policyDigest)) 17984 return TPM_RC_SIZE + RC_PCR_SetAuthPolicy_authPolicy; 17985 // If PCR does not belong to a policy group, return TPM_RC_VALUE 17986 if(!PCRBelongsPolicyGroup(in->pcrNum, &groupIndex)) 17987 return TPM_RC_VALUE + RC_PCR_SetAuthPolicy_pcrNum; 17988 // Internal Data Update 17989 // Set PCR policy 17990 gp.pcrPolicies.hashAlg[groupIndex] = in->policyDigest; 17991 gp.pcrPolicies.policy[groupIndex] = in->authPolicy; 17992 // Save new policy to NV 17993 NvWriteReserved(NV_PCR_POLICIES, &gp.pcrPolicies); 17994 return TPM_RC_SUCCESS; 17995 } 17996 17997 Family 2.0 17998 Level 00 Revision 00.99 17999 18000 Published 18001 Copyright TCG 2006-2013 18002 18003 Page 215 18004 October 31, 2013 18005 18006 Part 3: Commands 18008 18009 24.7 18010 18011 Trusted Platform Module Library 18012 18013 TPM2_PCR_SetAuthValue 18014 18015 24.7.1 General Description 18016 This command changes the authValue of a PCR or group of PCR. 18017 An authValue may only be associated with a PCR that has been defined by a platform-specific 18018 specification as allowing an authorization value. If the TPM implementation does not allow an 18019 authorization for pcrNum, the TPM shall return TPM_RC_VALUE. A platform-specific specification may 18020 group PCR so that they share a common authorization value. In such case, a pcrNum that selects any of 18021 the PCR in the group will change the authValue value for all PCR in the group. 18022 The authorization setting is set to EmptyAuth on each STARTUP(CLEAR) or by TPM2_Clear(). The 18023 authorization setting is preserved by SHUTDOWN(STATE). 18024 18025 Page 216 18026 October 31, 2013 18027 18028 Published 18029 Copyright TCG 2006-2013 18030 18031 Family 2.0 18032 Level 00 Revision 00.99 18033 18034 Trusted Platform Module Library 18036 18037 Part 3: Commands 18038 18039 24.7.2 Command and Response 18040 Table 109 TPM2_PCR_SetAuthValue Command 18041 Type 18042 18043 Name 18044 18045 Description 18046 18047 TPMI_ST_COMMAND_TAG 18048 18049 tag 18050 18051 UINT32 18052 18053 commandSize 18054 18055 TPM_CC 18056 18057 commandCode 18058 18059 TPM_CC_PCR_SetAuthValue 18060 18061 TPMI_DH_PCR 18062 18063 @pcrHandle 18064 18065 handle for a PCR that may have an authorization value 18066 set 18067 Auth Index: 1 18068 Auth Role: USER 18069 18070 TPM2B_DIGEST 18071 18072 auth 18073 18074 the desired authorization value 18075 18076 Table 110 TPM2_PCR_SetAuthValue Response 18077 Type 18078 18079 Name 18080 18081 Description 18082 18083 TPM_ST 18084 18085 tag 18086 18087 see clause 8 18088 18089 UINT32 18090 18091 responseSize 18092 18093 TPM_RC 18094 18095 responseCode 18096 18097 Family 2.0 18098 Level 00 Revision 00.99 18099 18100 Published 18101 Copyright TCG 2006-2013 18102 18103 Page 217 18104 October 31, 2013 18105 18106 Part 3: Commands 18108 18109 Trusted Platform Module Library 18110 18111 24.7.3 Detailed Actions 18112 1 18113 2 18114 18115 #include "InternalRoutines.h" 18116 #include "PCR_SetAuthValue_fp.h" 18117 Error Returns 18118 TPM_RC_VALUE 18119 18120 3 18121 4 18122 5 18123 6 18124 7 18125 8 18126 9 18127 10 18128 11 18129 12 18130 13 18131 14 18132 15 18133 16 18134 17 18135 18 18136 19 18137 20 18138 21 18139 22 18140 23 18141 24 18142 25 18143 26 18144 27 18145 28 18146 29 18147 30 18148 31 18149 32 18150 33 18151 34 18152 18153 Meaning 18154 PCR referenced by pcrHandle is not a member of a PCR 18155 authorization group 18156 18157 TPM_RC 18158 TPM2_PCR_SetAuthValue( 18159 PCR_SetAuthValue_In 18160 18161 *in 18162 18163 // IN: input parameter list 18164 18165 ) 18166 { 18167 UINT32 18168 TPM_RC 18169 18170 groupIndex; 18171 result; 18172 18173 // Input Validation: 18174 // If PCR does not belong to an auth group, return TPM_RC_VALUE 18175 if(!PCRBelongsAuthGroup(in->pcrHandle, &groupIndex)) 18176 return TPM_RC_VALUE; 18177 // The command may cause the orderlyState to be cleared due to the update of 18178 // state clear data. If this is the case, Check if NV is available. 18179 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 18180 // this point 18181 if(gp.orderlyState != SHUTDOWN_NONE) 18182 { 18183 result = NvIsAvailable(); 18184 if(result != TPM_RC_SUCCESS) return result; 18185 g_clearOrderly = TRUE; 18186 } 18187 // Internal Data Update 18188 // Set PCR authValue 18189 gc.pcrAuthValues.auth[groupIndex] = in->auth; 18190 return TPM_RC_SUCCESS; 18191 } 18192 18193 Page 218 18194 October 31, 2013 18195 18196 Published 18197 Copyright TCG 2006-2013 18198 18199 Family 2.0 18200 Level 00 Revision 00.99 18201 18202 Trusted Platform Module Library 18204 18205 24.8 18206 18207 Part 3: Commands 18208 18209 TPM2_PCR_Reset 18210 18211 24.8.1 General Description 18212 If the attribute of a PCR allows the PCR to be reset and proper authorization is provided, then this 18213 command may be used to set the PCR to zero. The attributes of the PCR may restrict the locality that can 18214 perform the reset operation. 18215 NOTE 1 18216 18217 The definition of TPMI_DH_PCR in Part 2 indicates that if pcrHandle is out of the allowed range for 18218 PCR, then the appropriate return value is TPM_RC_VALUE. 18219 18220 If pcrHandle references a PCR that cannot be reset, the TPM shall return TPM_RC_LOCALITY. 18221 NOTE 2 18222 18223 TPM_RC_LOCALITY is returned because the reset attributes are defined on a per -locality basis. 18224 18225 Family 2.0 18226 Level 00 Revision 00.99 18227 18228 Published 18229 Copyright TCG 2006-2013 18230 18231 Page 219 18232 October 31, 2013 18233 18234 Part 3: Commands 18236 18237 Trusted Platform Module Library 18238 18239 24.8.2 Command and Response 18240 Table 111 TPM2_PCR_Reset Command 18241 Type 18242 18243 Name 18244 18245 Description 18246 18247 TPMI_ST_COMMAND_TAG 18248 18249 tag 18250 18251 UINT32 18252 18253 commandSize 18254 18255 TPM_CC 18256 18257 commandCode 18258 18259 TPM_CC_PCR_Reset {NV} 18260 18261 TPMI_DH_PCR 18262 18263 @pcrHandle 18264 18265 the PCR to reset 18266 Auth Index: 1 18267 Auth Role: USER 18268 18269 Table 112 TPM2_PCR_Reset Response 18270 Type 18271 18272 Name 18273 18274 Description 18275 18276 TPM_ST 18277 18278 tag 18279 18280 see clause 8 18281 18282 UINT32 18283 18284 responseSize 18285 18286 TPM_RC 18287 18288 responseCode 18289 18290 Page 220 18291 October 31, 2013 18292 18293 Published 18294 Copyright TCG 2006-2013 18295 18296 Family 2.0 18297 Level 00 Revision 00.99 18298 18299 Trusted Platform Module Library 18301 18302 Part 3: Commands 18303 18304 24.8.3 Detailed Actions 18305 1 18306 2 18307 18308 #include "InternalRoutines.h" 18309 #include "PCR_Reset_fp.h" 18310 Error Returns 18311 TPM_RC_LOCALITY 18312 18313 3 18314 4 18315 5 18316 6 18317 7 18318 8 18319 9 18320 10 18321 11 18322 12 18323 13 18324 14 18325 15 18326 16 18327 17 18328 18 18329 19 18330 20 18331 21 18332 22 18333 23 18334 24 18335 25 18336 26 18337 27 18338 28 18339 29 18340 30 18341 31 18342 32 18343 33 18344 34 18345 35 18346 36 18347 18348 Meaning 18349 current command locality is not allowed to reset the PCR referenced 18350 by pcrHandle 18351 18352 TPM_RC 18353 TPM2_PCR_Reset( 18354 PCR_Reset_In 18355 18356 *in 18357 18358 // IN: input parameter list 18359 18360 ) 18361 { 18362 TPM_RC 18363 18364 result; 18365 18366 // Input Validation 18367 // Check if the reset operation is allowed by the current command locality 18368 if(!PCRIsResetAllowed(in->pcrHandle)) 18369 return TPM_RC_LOCALITY; 18370 // If PCR is state saved and we need to update orderlyState, check NV 18371 // availability 18372 if(PCRIsStateSaved(in->pcrHandle) && gp.orderlyState != SHUTDOWN_NONE) 18373 { 18374 result = NvIsAvailable(); 18375 if(result != TPM_RC_SUCCESS) 18376 return result; 18377 g_clearOrderly = TRUE; 18378 } 18379 // Internal Data Update 18380 // Reset seleccted PCR in all banks to 0 18381 PCRSetValue(in->pcrHandle, 0); 18382 // Indicate that the PCR changed so that pcrCounter will be incremented if 18383 // necessary. 18384 PCRChanged(in->pcrHandle); 18385 return TPM_RC_SUCCESS; 18386 } 18387 18388 Family 2.0 18389 Level 00 Revision 00.99 18390 18391 Published 18392 Copyright TCG 2006-2013 18393 18394 Page 221 18395 October 31, 2013 18396 18397 Part 3: Commands 18399 18400 24.9 18401 18402 Trusted Platform Module Library 18403 18404 _TPM_Hash_Start 18405 18406 24.9.1 Description 18407 This indication from the TPM interface indicates the start of a dynamic Core Root of Trust for 18408 Measurement (D-CRTM) measurement sequence. On receipt of this indication, the TPM will initialize an 18409 Event sequence context. 18410 If no object memory is available for creation of the sequence context, the TPM will flush the context of an 18411 object so that creation of the Event sequence context will always succeed. 18412 A platform-specific specification may allow this indication before TPM2_Startup(). 18413 NOTE 18414 18415 If this indication occurs after TPM2_Startup(), it is the responsibility of software to ensure that an 18416 object context slot is available or to deal with the consequences of having the TPM select an 18417 arbitrary object to be flushed. If this indication occurs before TPM2_Startup() then all context slots 18418 are available. 18419 18420 Page 222 18421 October 31, 2013 18422 18423 Published 18424 Copyright TCG 2006-2013 18425 18426 Family 2.0 18427 Level 00 Revision 00.99 18428 18429 Trusted Platform Module Library 18431 18432 Part 3: Commands 18433 18434 24.9.2 Detailed Actions 18435 1 18436 18437 #include "InternalRoutines.h" 18438 18439 This function is called to process a _TPM_Hash_Start() indication. 18440 2 18441 3 18442 4 18443 5 18444 6 18445 7 18446 8 18447 9 18448 10 18449 11 18450 12 18451 13 18452 14 18453 15 18454 16 18455 17 18456 18 18457 19 18458 20 18459 21 18460 22 18461 23 18462 24 18463 25 18464 26 18465 27 18466 28 18467 29 18468 30 18469 31 18470 32 18471 33 18472 34 18473 35 18474 36 18475 37 18476 38 18477 39 18478 40 18479 41 18480 42 18481 43 18482 44 18483 45 18484 46 18485 47 18486 48 18487 49 18488 50 18489 18490 void 18491 _TPM_Hash_Start(void) 18492 { 18493 TPM_RC 18494 TPMI_DH_OBJECT 18495 18496 result; 18497 handle; 18498 18499 // If a DRTM sequence object exists, terminate it. 18500 if(g_DRTMHandle != TPM_RH_UNASSIGNED) 18501 ObjectTerminateEvent(); 18502 // Create an event sequence object and store the handle in global 18503 // g_DRTMHandle. A TPM_RC_OBJECT_MEMORY error may be returned at this point 18504 // The null value for the 'auth' parameter will cause the sequence structure to 18505 // be allocated without being set as present. This keeps the sequence from 18506 // being left behind if the sequence is terminated early. 18507 result = ObjectCreateEventSequence(NULL, &g_DRTMHandle); 18508 // If a free slot was not available, then free up a slot. 18509 if(result != TPM_RC_SUCCESS) 18510 { 18511 // An implementation does not need to have a fixed relationship between 18512 // slot numbers and handle numbers. To handle the general case, scan for 18513 // a handle that is assigned an free it for the DRTM sequence. 18514 // In the reference implementation, the relationship between handles and 18515 // slots is fixed. So, if the call to ObjectCreateEvenSequence() 18516 // failed indicating that all slots are occupied, then the first handle we 18517 // are going to check (TRANSIENT_FIRST) will be occupied. It will be freed 18518 // so that it can be assigned for use as the DRTM sequence object. 18519 for(handle = TRANSIENT_FIRST; handle < TRANSIENT_LAST; handle++) 18520 { 18521 // try to flush the first object 18522 if(ObjectIsPresent(handle)) 18523 break; 18524 } 18525 // If the first call to find a slot fails but none of the slots is occupied 18526 // then there's a big problem 18527 pAssert(handle < TRANSIENT_LAST); 18528 // Free the slot 18529 ObjectFlush(handle); 18530 // Try to create an event sequence object again. This time, we must 18531 // succeed. 18532 result = ObjectCreateEventSequence(NULL, &g_DRTMHandle); 18533 pAssert(result == TPM_RC_SUCCESS); 18534 } 18535 return; 18536 } 18537 18538 Family 2.0 18539 Level 00 Revision 00.99 18540 18541 Published 18542 Copyright TCG 2006-2013 18543 18544 Page 223 18545 October 31, 2013 18546 18547 Part 3: Commands 18549 18550 Trusted Platform Module Library 18551 18552 24.10 _TPM_Hash_Data 18553 24.10.1 18554 18555 Description 18556 18557 This indication from the TPM interface indicates arrival of one or more octets of data that are to be 18558 included in the Core Root of Trust for Measurement (CRTM) sequence context created by the 18559 _TPM_Hash_Start indication. The context holds data for each hash algorithm for each PCR bank 18560 implemented on the TPM. 18561 If no DRTM Event Sequence context exists, this indication is discarded and no other action is performed. 18562 18563 Page 224 18564 October 31, 2013 18565 18566 Published 18567 Copyright TCG 2006-2013 18568 18569 Family 2.0 18570 Level 00 Revision 00.99 18571 18572 Trusted Platform Module Library 18574 18575 24.10.2 18576 1 18577 2 18578 18579 Part 3: Commands 18580 18581 Detailed Actions 18582 18583 #include "InternalRoutines.h" 18584 #include "Platform.h" 18585 18586 This function is called to process a _TPM_Hash_Data() indication. 18587 3 18588 4 18589 5 18590 6 18591 7 18592 8 18593 9 18594 10 18595 11 18596 12 18597 13 18598 14 18599 15 18600 16 18601 17 18602 18 18603 19 18604 20 18605 21 18606 22 18607 23 18608 24 18609 25 18610 26 18611 27 18612 28 18613 29 18614 30 18615 31 18616 18617 void 18618 _TPM_Hash_Data( 18619 UINT32 18620 BYTE 18621 18622 dataSize, 18623 *data 18624 18625 UINT32 18626 HASH_OBJECT 18627 18628 // IN: size of data to be extend 18629 // IN: data buffer 18630 18631 i; 18632 *hashObject; 18633 18634 ) 18635 { 18636 18637 // If there is no DRTM sequence object, then _TPM_Hash_Start 18638 // was not called so this function returns without doing 18639 // anything. 18640 if(g_DRTMHandle == TPM_RH_UNASSIGNED) 18641 return; 18642 hashObject = (HASH_OBJECT *)ObjectGet(g_DRTMHandle); 18643 pAssert(hashObject->attributes.eventSeq); 18644 // For each of the implemented hash algorithms, update the digest with the 18645 // data provided. NOTE: the implementation could be done such that the TPM 18646 // only computes the hash for the banks that contain the DRTM PCR. 18647 for(i = 0; i < HASH_COUNT; i++) 18648 { 18649 // Update sequence object 18650 CryptUpdateDigest(&hashObject->state.hashState[i], dataSize, data); 18651 } 18652 return; 18653 } 18654 18655 Family 2.0 18656 Level 00 Revision 00.99 18657 18658 Published 18659 Copyright TCG 2006-2013 18660 18661 Page 225 18662 October 31, 2013 18663 18664 Part 3: Commands 18666 18667 Trusted Platform Module Library 18668 18669 24.11 _TPM_Hash_End 18670 24.11.1 18671 18672 Description 18673 18674 This indication from the TPM interface indicates the end of the CRTM measurement. This indication is 18675 discarded and no other action performed if the TPM does not contain a CRTM Event sequence context. 18676 NOTE 18677 18678 A CRTM Event Sequence context is created by _TPM_Hash_Start(). 18679 18680 If the CRTM Event sequence occurs after TPM2_Startup(), the TPM will set all of the PCR designated in 18681 the platform-specific specifications as resettable by this event to the value indicated in the platform 18682 specific specification, and increment restartCount. The TPM will then Extend the Event Sequence 18683 digest/digests into the designated, DRTM PCR. 18684 PCR[DRTM][hashAlg] HhashAlg (initial_value || HhashAlg (hash_data)) 18685 18686 (7) 18687 18688 where 18689 DRTM 18690 18691 index for CRTM PCR designated by a platform-specific 18692 specification 18693 18694 hashAlg 18695 18696 hash algorithm associated with a bank of PCR 18697 18698 initial_value 18699 18700 initialization value specified in the platform-specific specification 18701 (should be 00) 18702 18703 hash_data 18704 18705 all the octets of data received in _TPM_Hash_Data indications 18706 18707 A _TPM_Hash_End indication that occurs after TPM2_Startup() will increment pcrUpdateCounter unless 18708 a platform-specific specification excludes modifications of PCR[DRTM] from causing an increment. 18709 A platform-specific specification may allow an H-CRTM Event Sequence before TPM2_Startup(). If so, 18710 _TPM_Hash_End will complete the digest, initialize PCR[0] with a digest-size value of 4, and then extend 18711 the H-CRTM Event Sequence data into PCR[0]. 18712 PCR[0][hashAlg] HhashAlg (004 || HhashAlg (hash_data)) 18713 NOTE 18714 18715 (8) 18716 18717 The entire sequence of _TPM_Hash_Start, _TPM_Hash_Data, and _TPM_Hash_End are required to 18718 complete before TPM2_Startup() or the sequence will have no effect on the TPM. 18719 18720 Page 226 18721 October 31, 2013 18722 18723 Published 18724 Copyright TCG 2006-2013 18725 18726 Family 2.0 18727 Level 00 Revision 00.99 18728 18729 Trusted Platform Module Library 18731 18732 24.11.2 18733 1 18734 18735 Part 3: Commands 18736 18737 Detailed Actions 18738 18739 #include "InternalRoutines.h" 18740 18741 This function is called to process a _TPM_Hash_End() indication. 18742 2 18743 3 18744 4 18745 5 18746 6 18747 7 18748 8 18749 9 18750 10 18751 11 18752 12 18753 13 18754 14 18755 15 18756 16 18757 17 18758 18 18759 19 18760 20 18761 21 18762 22 18763 23 18764 24 18765 25 18766 26 18767 27 18768 28 18769 29 18770 30 18771 31 18772 32 18773 33 18774 34 18775 35 18776 36 18777 37 18778 38 18779 39 18780 40 18781 41 18782 42 18783 43 18784 44 18785 45 18786 46 18787 47 18788 48 18789 49 18790 50 18791 51 18792 52 18793 53 18794 54 18795 55 18796 56 18797 57 18798 18799 void 18800 _TPM_Hash_End(void) 18801 { 18802 UINT32 18803 TPM2B_DIGEST 18804 HASH_OBJECT 18805 TPMI_DH_PCR 18806 18807 i; 18808 digest; 18809 *hashObject; 18810 pcrHandle; 18811 18812 // If the DRTM handle is not being used, then either _TPM_Hash_Start has not 18813 // been called, _TPM_Hash_End was previously called, or some other command 18814 // was executed and the sequence was aborted. 18815 if(g_DRTMHandle == TPM_RH_UNASSIGNED) 18816 return; 18817 // Get DRTM sequence object 18818 hashObject = (HASH_OBJECT *)ObjectGet(g_DRTMHandle); 18819 // Is this _TPM_Hash_End after Startup or before 18820 if(TPMIsStarted()) 18821 { 18822 // After 18823 // Reset the DRTM PCR 18824 PCRResetDynamics(); 18825 // Extend the DRTM_PCR. 18826 pcrHandle = PCR_FIRST + DRTM_PCR; 18827 // DRTM sequence increments restartCount 18828 gr.restartCount++; 18829 } 18830 else 18831 { 18832 pcrHandle = PCR_FIRST + HCRTM_PCR; 18833 } 18834 // Complete hash and extend PCR, or if this is an HCRTM, complete 18835 // the hash and write the PCR 18836 for(i = 0; i < HASH_COUNT; i++) 18837 { 18838 TPMI_ALG_HASH 18839 hash = CryptGetHashAlgByIndex(i); 18840 // Complete hash 18841 digest.t.size = CryptGetHashDigestSize(hash); 18842 CryptCompleteHash2B(&hashObject->state.hashState[i], &digest.b); 18843 // If this is DRTM, extend to zeroed PCR 18844 // If this is H-DRTM, copy to HCRM PCR 18845 if(TPMIsStarted()) 18846 // Extend PCR 18847 PCRExtend(pcrHandle, hash, digest.t.size, digest.t.buffer); 18848 else 18849 PcrWrite(pcrHandle, hash, &digest); 18850 18851 Family 2.0 18852 Level 00 Revision 00.99 18853 18854 Published 18855 Copyright TCG 2006-2013 18856 18857 Page 227 18858 October 31, 2013 18859 18860 Part 3: Commands 18862 58 18863 59 18864 60 18865 61 18866 62 18867 63 18868 64 18869 65 18870 66 18871 67 18872 68 18873 18874 Trusted Platform Module Library 18875 18876 } 18877 // Flush sequence object. 18878 ObjectFlush(g_DRTMHandle); 18879 g_DRTMHandle = TPM_RH_UNASSIGNED; 18880 g_DrtmPreStartup = TRUE; 18881 return; 18882 } 18883 18884 Page 228 18885 October 31, 2013 18886 18887 Published 18888 Copyright TCG 2006-2013 18889 18890 Family 2.0 18891 Level 00 Revision 00.99 18892 18893 Trusted Platform Module Library 18895 18896 25 18897 18898 Part 3: Commands 18899 18900 Enhanced Authorization (EA) Commands 18901 18902 25.1 18903 18904 Introduction 18905 18906 The commands in this clause 1 are used for policy evaluation. When successful, each command will 18907 update the policySessionpolicyDigest in a policy session context in order to establish that the 18908 authorizations required to use an object have been provided. Many of the commands will also modify 18909 other parts of a policy context so that the caller may constrain the scope of the authorization that is 18910 provided. 18911 NOTE 1 18912 18913 Many of the terms used in this clause are described in detail i n Part 1 and are not redefined in this 18914 clause. 18915 18916 The policySession parameter of the command is the handle of the policy session context to be modified 18917 by the command. 18918 If the policySession parameter indicates a trial policy session, then the policySessionpolicyDigest will 18919 be updated and the indicated validations are not performed. 18920 NOTE 2 18921 18922 A policy session is a trial policy by TPM2_StartAuthSession( sessionType = TPM_SE_TRIAL). 18923 18924 NOTE 3 18925 18926 Unless there is an unmarshaling error in the parameters of the command, these commands will 18927 return TPM_RC_SUCCESS when policySession references a trial session. 18928 18929 NOTE 4 18930 18931 Policy context other than the policySessionpolicyDigest may be updated for a trial policy but it is 18932 not required. 18933 18934 Family 2.0 18935 Level 00 Revision 00.99 18936 18937 Published 18938 Copyright TCG 2006-2013 18939 18940 Page 229 18941 October 31, 2013 18942 18943 Part 3: Commands 18945 18946 25.2 18947 18948 Trusted Platform Module Library 18949 18950 Signed Authorization Actions 18951 18952 25.2.1 Introduction 18953 The TPM2_PolicySigned, TPM_PolicySecret, and TPM2_PolicyTicket commands use many of the same 18954 functions. This clause consolidates those functions to simplify the document and to ensure uniformity of 18955 the operations. 18956 25.2.2 Policy Parameter Checks 18957 These parameter checks will be performed when indicated in the description of each of the commands: 18958 a) nonceTPM If this parameter is not the Empty Buffer, and 18959 policySessionnonceTPM, then the TPM shall return TPM_RC_VALUE. 18960 18961 it 18962 18963 does 18964 18965 not 18966 18967 match 18968 18969 b) expiration If this parameter is not zero, then its absolute value is compared to the time in seconds 18970 since the policySessionnonceTPM was generated. If more time has passed than indicted in 18971 expiration, the TPM shall return TPM_RC_EXPIRED. If nonceTPM is the Empty buffer, and expiration 18972 is non-zero, then the TPM shall return TPM_RC_EXPIRED. 18973 c) timeout This parameter is compared to the current TPM time. If policySessiontimeout is in the 18974 past, then the TPM shall return TPM_RC_EXPIRED. 18975 NOTE 1 18976 18977 The expiration parameter is present in the TPM2_PolicySigned and TPM2_PolicySecret 18978 command and timeout is the analogous parameter in the TPM2_PolicyTicket command. 18979 18980 d) cpHashA If this parameter is not an Empty Buffer 18981 NOTE 2 18982 18983 CpHashA is the hash of the command to be executed using this policy session in the 18984 authorization. The algorithm used to compute this hash is required to be the algorithm of the 18985 policy session. 18986 18987 1) the TPM shall return TPM_RC_CPHASH if policySessioncpHash does not have its default 18988 value or the contents of policySessioncpHash are not the same as cpHashA; or 18989 NOTE 3 18990 18991 CpHash is the expected cpHash value held in the policy session context. 18992 18993 2) the TPM shall return TPM_RC_SIZE 18994 policySessionpolicyDigest. 18995 NOTE 4 18996 18997 Page 230 18998 October 31, 2013 18999 19000 if 19001 19002 cpHashA 19003 19004 is 19005 19006 not 19007 19008 the 19009 19010 same 19011 19012 size 19013 19014 as 19015 19016 PolicySessionpolicyDigest is the size of the digest produced by the hash algorithm used to 19017 compute policyDigest. 19018 19019 Published 19020 Copyright TCG 2006-2013 19021 19022 Family 2.0 19023 Level 00 Revision 00.99 19024 19025 Trusted Platform Module Library 19027 19028 Part 3: Commands 19029 19030 25.2.3 PolicyDigest Update Function (PolicyUpdate()) 19031 This is the update process for policySessionpolicyDigest used by TPM2_PolicySigned(), 19032 TPM2_PolicySecret(), TPM2_PolicyTicket(), and TPM2_PolicyAuthorize(). The function prototype for the 19033 update function is: 19034 19035 PolicyUpdate(commandCode, arg2, arg3) 19036 19037 (9) 19038 19039 where 19040 19041 arg2 19042 19043 a TPM2B_NAME 19044 19045 arg3 19046 19047 a TPM2B 19048 19049 These parameters are used to update policySessionpolicyDigest by 19050 19051 policyDigestnew HpolicyAlg(policyDigestold || commandCode || arg2.name) 19052 19053 (10) 19054 19055 policyDigestnew+1 HpolicyAlg(policyDigestnew || arg3.buffer) 19056 19057 (11) 19058 19059 followed by 19060 19061 where 19062 19063 HpolicyAlg() 19064 19065 the hash algorithm chosen when the policy session was started 19066 19067 NOTE 1 19068 19069 If arg3 is a TPM2B_NAME, then arg3.buffer will actually be an arg3.name. 19070 19071 NOTE 2 19072 19073 The arg2.size and arg3.size fields are not included in the hashes. 19074 19075 NOTE 3 19076 19077 PolicyUpdate() uses two hashes because arg2 and arg3 are variable-sized and the concatenation of 19078 arg2 and arg3 in a single hash could produce the same digest even though arg2 and arg3 are 19079 different. Processing of the arguments separately in different Extend operation insures that the 19080 digest produced by PolicyUpdate() will be different if arg2 and arg3 are different. 19081 19082 Family 2.0 19083 Level 00 Revision 00.99 19084 19085 Published 19086 Copyright TCG 2006-2013 19087 19088 Page 231 19089 October 31, 2013 19090 19091 Part 3: Commands 19093 19094 Trusted Platform Module Library 19095 19096 25.2.4 Policy Context Updates 19097 When a policy command modifies some part of the policy session context other than the 19098 policySessionpolicyDigest, the following rules apply. 19099 19100 19101 cpHash this parameter may only be changed if it contains its initialization value (an Empty String). 19102 If cpHash is not the Empty String when a policy command attempts to update it, the TPM will return 19103 an error (TPM_RC_CPHASH) if the current and update values are not the same. 19104 19105 19106 19107 timeOut this parameter may only be changed to a smaller value. If a command attempts to update 19108 this value with a larger value (longer into the future), the TPM will discard the update value. This is 19109 not an error condition. 19110 19111 19112 19113 commandCode once set by a policy command, this value may not be change except by 19114 TPM2_PolicyRestart(). If a policy command tries to change this to a different value, an error is 19115 returned (TPM_RC_POLICY_CC). 19116 19117 19118 19119 pcrUpdateCounter this parameter is updated by TPM2_PolicyPCR(). This value may only be set 19120 once during a policy. Each time TPM2_PolicyPCR() executes, it checks to see if 19121 policySessionpcrUpdateCounter has its default state indicating that this is the first 19122 TPM2_PolicyPCR(). If it has its default value, then policySessionpcrUpdateCounter is set to the 19123 current value of pcrUpdateCounter. If policySessionpcrUpdateCounter does not have its default 19124 value and its value is not the same as pcrUpdateCounter, the TPM shall return 19125 TPM_RC_PCR_CHANGED. 19126 NOTE 19127 19128 If this parameter and pcrUpdateCounter are not the same, it indicates that PCR have changed 19129 since checked by the previous TPM2_PolicyPCR(). Since they have changed, the previous PCR 19130 validation is no longer valid. 19131 19132 19133 19134 commandLocality this parameter is the logical AND of all enabled localities. All localities are 19135 enabled for a policy when the policy session is created. TPM2_PolicyLocalities() selectively disables 19136 localities. Once use of a policy for a locality has been disabled, it cannot be enabled except by 19137 TPM2_PolicyRestart(). 19138 19139 19140 19141 isPPRequired once SET, this parameter may only be CLEARed by TPM2_PolicyRestart(). 19142 19143 19144 19145 isAuthValueNeeded once SET, this parameter may only be CLEARed by TPM2_PolicyPassword() 19146 or TPM2_PolicyRestart(). 19147 19148 19149 19150 isPasswordNeeded once SET, this parameter may only be CLEARed by TPM2_PolicyAuthValue() 19151 or TPM2_PolicyRestart(), 19152 19153 NOTE 19154 19155 Both TPM2_PolicyAuthValue() and TPM2_PolicyPassword() change policySessionpolicyDigest in 19156 the same way. The different commands simply indicate to the TPM the format used for the authValue 19157 (HMAC or clear text). Both commands could be in the same policy. The final instance of these 19158 commands determines the format. 19159 19160 Page 232 19161 October 31, 2013 19162 19163 Published 19164 Copyright TCG 2006-2013 19165 19166 Family 2.0 19167 Level 00 Revision 00.99 19168 19169 Trusted Platform Module Library 19171 19172 Part 3: Commands 19173 19174 25.2.5 Policy Ticket Creation 19175 If for TPM2_PolicySigned() or TPM2_PolicySecret() the caller specified a negative value for expiration, 19176 and the policy update succeeds, then the TPM will return a ticket that includes a value indicating when 19177 the authorization expires. The required computation for the digest in the authorization ticket is: 19178 19179 HMAC(proof, HpolicyAlg(ticketType || timeout || cpHashA || policyRef || authObjectName)) (12) 19180 where 19181 19182 proof 19183 19184 secret associated with the storage primary seed (SPS) of the 19185 TPM 19186 19187 HpolicyAlg 19188 19189 hash function using the hash algorithm associated with the policy 19190 session 19191 19192 ticketType 19193 19194 either TPM_ST_AUTH_SECRET or TPM_ST_AUTH_SIGNED, 19195 used to indicate type of the ticket 19196 19197 NOTE 1 19198 19199 If 19200 the 19201 ticket 19202 is 19203 produced 19204 by 19205 TPM2_PolicySecret() 19206 then 19207 ticketType 19208 is 19209 TPM_ST_AUTH_SECRET and if produced by TPM2_PolicySigned() then ticketType is 19210 TPM_ST_AUTH_SIGNED. 19211 19212 timeout 19213 19214 NOTE 2 19215 19216 implementation-specific representation of the expiration time of 19217 the ticket; required to be the implementation equivalent of 19218 policySessionstartTime plus the absolute value of expiration 19219 Timeout is not the same as expiration. The expiration value in the aHash is a relative time, 19220 using the creation time of the authorization session (TPM2_StartAuthSession()) as its 19221 reference. The timeout parameter is an absolute time, using TPM Clock as the reference. 19222 19223 cpHashA 19224 19225 the command parameter digest for the command being 19226 authorized; computed using the hash algorithm of the policy 19227 session 19228 19229 policyRef 19230 19231 the commands that use this function have a policyRef parameter 19232 and the value of that parameter is used here 19233 19234 authObjectName 19235 19236 Name associated with the authObject parameter 19237 19238 Family 2.0 19239 Level 00 Revision 00.99 19240 19241 Published 19242 Copyright TCG 2006-2013 19243 19244 Page 233 19245 October 31, 2013 19246 19247 Part 3: Commands 19249 25.3 19250 19251 Trusted Platform Module Library 19252 19253 TPM2_PolicySigned 19254 19255 25.3.1 General Description 19256 This command includes a signed authorization in a policy. The command ties the policy to a signing key 19257 by including the Name of the signing key in the policyDigest 19258 If policySession is a trial session, the TPM will not check the signature and will update 19259 policySessionpolicyDigest as described in 25.2.3 as if a properly signed authorization was received; but 19260 no ticket will be produced. 19261 If policySession is not a trial session, the TPM will validate auth and only perform the update if it is a valid 19262 signature over the fields of the command. 19263 The authorizing object will sign a digest of the authorization qualifiers: nonceTPM, expiration, cpHashA, 19264 and policyRef. The digest is computed as: 19265 19266 aHash HauthAlg(nonceTPM || expiration || cpHashA || policyRef) 19267 19268 (13) 19269 19270 where 19271 19272 HauthAlg() 19273 NOTE 1 19274 19275 the hash associated with the auth parameter of this command 19276 Each signature and key combination indicates the scheme and each scheme has an 19277 associated hash. 19278 19279 nonceTPM 19280 19281 the nonceTPM parameter from the TPM2_StartAuthSession() 19282 response. If the authorization is not limited to this session, the 19283 size of this value is zero. 19284 19285 expiration 19286 19287 time limit on authorization set by authorizing object. This 32-bit 19288 value is set to zero if the expiration time is not being set. 19289 19290 cpHashA 19291 19292 digest of the command parameters for the command being 19293 approved using the hash algorithm of the policy session. Set to 19294 an EmptyAuth if the authorization is not limited to a specific 19295 command. 19296 19297 NOTE 2 19298 19299 This is not the cpHash of this TPM2_PolicySigned() command. 19300 19301 policyRef 19302 EXAMPLE 19303 19304 an opaque value determined by the authorizing entity. Set to the 19305 Empty Buffer if no value is present. 19306 19307 The computation for an aHash if there are no restrictions is: 19308 19309 aHash HauthAlg(00 00 00 0016) 19310 which is the hash of an expiration time of zero. 19311 19312 The aHash is signed by the private key associated with key. The signature and signing parameters are 19313 combined to create the auth parameter. 19314 The TPM will perform the parameter checks listed in 25.2.2 19315 If the parameter checks succeed, the TPM will construct a test digest (tHash) over the provided 19316 parameters using the same formulation a shown in equation (13) above. 19317 If tHash does not match the digest of the signed aHash, then the authorization fails and the TPM shall 19318 return TPM_RC_POLICY_FAIL and make no change to policySessionpolicyDigest. 19319 19320 Page 234 19321 October 31, 2013 19322 19323 Published 19324 Copyright TCG 2006-2013 19325 19326 Family 2.0 19327 Level 00 Revision 00.99 19328 19329 Trusted Platform Module Library 19331 19332 Part 3: Commands 19333 19334 When all validations have succeeded, policySessionpolicyDigest is updated by PolicyUpdate() (see 19335 25.2.3). 19336 19337 PolicyUpdate(TPM_CC_PolicySigned, authObjectName, policyRef) 19338 19339 (14) 19340 19341 If the cpHashA parameter is not an Empty Buffer, it is copied to policySessioncpHash. 19342 The TPM will optionally produce a ticket as described in 25.2.5. 19343 Authorization to use authObject is not required. 19344 19345 Family 2.0 19346 Level 00 Revision 00.99 19347 19348 Published 19349 Copyright TCG 2006-2013 19350 19351 Page 235 19352 October 31, 2013 19353 19354 Part 3: Commands 19356 19357 Trusted Platform Module Library 19358 19359 25.3.2 Command and Response 19360 Table 113 TPM2_PolicySigned Command 19361 Type 19362 19363 Name 19364 19365 TPMI_ST_COMMAND_TAG 19366 19367 tag 19368 19369 UINT32 19370 19371 commandSize 19372 19373 TPM_CC 19374 19375 commandCode 19376 19377 TPM_CC_PolicySigned 19378 19379 TPMI_DH_OBJECT 19380 19381 authObject 19382 19383 handle for a public key that will validate the signature 19384 Auth Index: None 19385 19386 TPMI_SH_POLICY 19387 19388 policySession 19389 19390 handle for the policy session being extended 19391 Auth Index: None 19392 19393 TPM2B_NONCE 19394 19395 nonceTPM 19396 19397 the policy nonce for the session 19398 If the nonce is not included in the authorization 19399 qualification, this field is the Empty Buffer. 19400 19401 cpHashA 19402 19403 digest of the command parameters to which this 19404 authorization is limited 19405 This is not the cpHash for this command but the cpHash 19406 for the command to which this policy session will be 19407 applied. If it is not limited, the parameter will be the 19408 Empty Buffer. 19409 19410 TPM2B_NONCE 19411 19412 policyRef 19413 19414 a reference to a policy relating to the authorization 19415 may be the Empty Buffer 19416 Size is limited to be no larger than the nonce size 19417 supported on the TPM. 19418 19419 INT32 19420 19421 expiration 19422 19423 time when authorization will expire, measured in 19424 seconds from the time that nonceTPM was generated 19425 If expiration is zero, a NULL Ticket is returned. 19426 19427 TPMT_SIGNATURE 19428 19429 auth 19430 19431 signed authorization (not optional) 19432 19433 TPM2B_DIGEST 19434 19435 Description 19436 19437 Table 114 TPM2_PolicySigned Response 19438 Type 19439 19440 Name 19441 19442 Description 19443 19444 TPM_ST 19445 19446 tag 19447 19448 see clause 8 19449 19450 UINT32 19451 19452 responseSize 19453 19454 TPM_RC 19455 19456 responseCode 19457 19458 TPM2B_TIMEOUT 19459 19460 timeout 19461 19462 TPMT_TK_AUTH 19463 19464 policyTicket 19465 19466 Page 236 19467 October 31, 2013 19468 19469 implementation-specific time value, used to indicate to 19470 the TPM when the ticket expires 19471 NOTE 19472 19473 If policyTicket is a NULL Ticket, then this shall be 19474 the Empty Buffer. 19475 19476 produced if the command succeeds and expiration in 19477 the command was non-zero; this ticket will use the 19478 TPMT_ST_AUTH_SIGNED structure tag 19479 19480 Published 19481 Copyright TCG 2006-2013 19482 19483 Family 2.0 19484 Level 00 Revision 00.99 19485 19486 Trusted Platform Module Library 19488 19489 Part 3: Commands 19490 19491 25.3.3 Detailed Actions 19492 1 19493 2 19494 3 19495 19496 #include "InternalRoutines.h" 19497 #include "Policy_spt_fp.h" 19498 #include "PolicySigned_fp.h" 19499 Error Returns 19500 TPM_RC_CPHASH 19501 19502 cpHash was previously set to a different value 19503 19504 TPM_RC_EXPIRED 19505 19506 expiration indicates a time in the past or expiration is non-zero but no 19507 nonceTPM is present 19508 19509 TPM_RC_HANDLE 19510 19511 authObject need to have sensitive portion loaded 19512 19513 TPM_RC_KEY 19514 19515 authObject is not a signing scheme 19516 19517 TPM_RC_NONCE 19518 19519 nonceTPM is not the nonce associated with the policySession 19520 19521 TPM_RC_SCHEME 19522 19523 the signing scheme of auth is not supported by the TPM 19524 19525 TPM_RC_SIGNATURE 19526 19527 the signature is not genuine 19528 19529 TPM_RC_SIZE 19530 19531 input cpHash has wrong size 19532 19533 TPM_RC_VALUE 19534 19535 4 19536 5 19537 6 19538 7 19539 8 19540 9 19541 10 19542 11 19543 12 19544 13 19545 14 19546 15 19547 16 19548 17 19549 18 19550 19 19551 20 19552 21 19553 22 19554 23 19555 24 19556 25 19557 26 19558 27 19559 28 19560 29 19561 30 19562 31 19563 32 19564 33 19565 34 19566 35 19567 36 19568 37 19569 38 19570 39 19571 19572 Meaning 19573 19574 input policyID or expiration does not match the internal data in policy 19575 session 19576 19577 TPM_RC 19578 TPM2_PolicySigned( 19579 PolicySigned_In 19580 PolicySigned_Out 19581 19582 *in, 19583 *out 19584 19585 // IN: input parameter list 19586 // OUT: output parameter list 19587 19588 TPM_RC 19589 SESSION 19590 OBJECT 19591 TPM2B_NAME 19592 TPM2B_DIGEST 19593 HASH_STATE 19594 UINT32 19595 19596 result = TPM_RC_SUCCESS; 19597 *session; 19598 *authObject; 19599 entityName; 19600 authHash; 19601 hashState; 19602 expiration = (in->expiration < 0) 19603 ? -(in->expiration) : in->expiration; 19604 authTimeout = 0; 19605 19606 ) 19607 { 19608 19609 UINT64 19610 // Input Validation 19611 19612 // Set up local pointers 19613 session = SessionGet(in->policySession); 19614 authObject = ObjectGet(in->authObject); 19615 19616 // the session structure 19617 // pointer for the object 19618 // 19619 providing authorization 19620 // 19621 signature 19622 19623 // Only do input validation if this is not a trial policy session 19624 if(session->attributes.isTrialPolicy == CLEAR) 19625 { 19626 if(expiration != 0) 19627 authTimeout = expiration * 1000 + session->startTime; 19628 result = PolicyParameterChecks(session, authTimeout, 19629 &in->cpHashA, &in->nonceTPM, 19630 RC_PolicySigned_nonceTPM, 19631 RC_PolicySigned_cpHashA, 19632 RC_PolicySigned_expiration); 19633 if(result != TPM_RC_SUCCESS) 19634 19635 Family 2.0 19636 Level 00 Revision 00.99 19637 19638 Published 19639 Copyright TCG 2006-2013 19640 19641 Page 237 19642 October 31, 2013 19643 19644 Part 3: Commands 19646 40 19647 41 19648 42 19649 43 19650 44 19651 45 19652 46 19653 47 19654 48 19655 49 19656 50 19657 51 19658 52 19659 53 19660 54 19661 55 19662 56 19663 57 19664 58 19665 59 19666 60 19667 61 19668 62 19669 63 19670 64 19671 65 19672 66 19673 67 19674 68 19675 69 19676 70 19677 71 19678 72 19679 73 19680 74 19681 75 19682 76 19683 77 19684 78 19685 79 19686 80 19687 81 19688 82 19689 83 19690 84 19691 85 19692 86 19693 87 19694 88 19695 89 19696 90 19697 91 19698 92 19699 93 19700 94 19701 95 19702 96 19703 97 19704 98 19705 99 19706 100 19707 101 19708 102 19709 103 19710 19711 Trusted Platform Module Library 19712 19713 return result; 19714 // Re-compute the digest being signed 19715 /*(See part 3 specification) 19716 // The digest is computed as: 19717 // 19718 aHash := hash ( nonceTPM | expiration | cpHashA | policyRef) 19719 // where: 19720 // 19721 hash() 19722 the hash associated with the signed auth 19723 // 19724 nonceTPM 19725 the nonceTPM value from the TPM2_StartAuthSession . 19726 // 19727 response If the authorization is not limited to this 19728 // 19729 session, the size of this value is zero. 19730 // 19731 expiration time limit on authorization set by authorizing object. 19732 // 19733 This 32-bit value is set to zero if the expiration 19734 // 19735 time is not being set. 19736 // 19737 cpHashA 19738 hash of the command parameters for the command being 19739 // 19740 approved using the hash algorithm of the PSAP session. 19741 // 19742 Set to NULLauth if the authorization is not limited 19743 // 19744 to a specific command. 19745 // 19746 policyRef 19747 hash of an opaque value determined by the authorizing 19748 // 19749 object. Set to the NULLdigest if no hash is present. 19750 */ 19751 // Start hash 19752 authHash.t.size = CryptStartHash(CryptGetSignHashAlg(&in->auth), 19753 &hashState); 19754 // add nonceTPM 19755 CryptUpdateDigest2B(&hashState, &in->nonceTPM.b); 19756 // add expiration 19757 CryptUpdateDigestInt(&hashState, sizeof(UINT32), (BYTE*) &in->expiration); 19758 // add cpHashA 19759 CryptUpdateDigest2B(&hashState, &in->cpHashA.b); 19760 // add policyRef 19761 CryptUpdateDigest2B(&hashState, &in->policyRef.b); 19762 // Complete digest 19763 CryptCompleteHash2B(&hashState, &authHash.b); 19764 // Validate Signature. A TPM_RC_SCHEME, TPM_RC_TYPE or TPM_RC_SIGNATURE 19765 // error may be returned at this point 19766 result = CryptVerifySignature(in->authObject, &authHash, &in->auth); 19767 if(result != TPM_RC_SUCCESS) 19768 return RcSafeAddToResult(result, RC_PolicySigned_auth); 19769 } 19770 // Internal Data Update 19771 // Need the Name of the signing entity 19772 entityName.t.size = EntityGetName(in->authObject, &entityName.t.name); 19773 // Update policy with input policyRef and name of auth key 19774 // These values are updated even if the session is a trial session 19775 PolicyContextUpdate(TPM_CC_PolicySigned, &entityName, &in->policyRef, 19776 &in->cpHashA, authTimeout, session); 19777 // Command Output 19778 // Create ticket and timeout buffer if in->expiration < 0 and this is not 19779 // a trial session. 19780 // NOTE: PolicyParameterChecks() makes sure that nonceTPM is present 19781 // when expiration is non-zero. 19782 if( 19783 in->expiration < 0 19784 && session->attributes.isTrialPolicy == CLEAR 19785 ) 19786 19787 Page 238 19788 October 31, 2013 19789 19790 Published 19791 Copyright TCG 2006-2013 19792 19793 Family 2.0 19794 Level 00 Revision 00.99 19795 19796 Trusted Platform Module Library 19798 104 19799 105 19800 106 19801 107 19802 108 19803 109 19804 110 19805 111 19806 112 19807 113 19808 114 19809 115 19810 116 19811 117 19812 118 19813 119 19814 120 19815 121 19816 122 19817 123 19818 124 19819 125 19820 126 19821 127 19822 128 19823 129 19824 130 19825 131 19826 132 19827 19828 Part 3: Commands 19829 19830 { 19831 // Generate timeout buffer. The format of output timeout buffer is 19832 // TPM-specific. 19833 // Note: can't do a direct copy because the output buffer is a byte 19834 // array and it may not be aligned to accept a 64-bit value. The method 19835 // used has the side-effect of making the returned value a big-endian, 19836 // 64-bit value that is byte aligned. 19837 out->timeout.t.size = sizeof(UINT64); 19838 UINT64_TO_BYTE_ARRAY(authTimeout, out->timeout.t.buffer); 19839 // Compute policy ticket 19840 TicketComputeAuth(TPM_ST_AUTH_SIGNED, EntityGetHierarchy(in->authObject), 19841 authTimeout, &in->cpHashA, &in->policyRef, &entityName, 19842 &out->policyTicket); 19843 } 19844 else 19845 { 19846 // Generate a null ticket. 19847 // timeout buffer is null 19848 out->timeout.t.size = 0; 19849 // auth ticket is null 19850 out->policyTicket.tag = TPM_ST_AUTH_SIGNED; 19851 out->policyTicket.hierarchy = TPM_RH_NULL; 19852 out->policyTicket.digest.t.size = 0; 19853 } 19854 return TPM_RC_SUCCESS; 19855 } 19856 19857 Family 2.0 19858 Level 00 Revision 00.99 19859 19860 Published 19861 Copyright TCG 2006-2013 19862 19863 Page 239 19864 October 31, 2013 19865 19866 Part 3: Commands 19868 19869 25.4 19870 19871 Trusted Platform Module Library 19872 19873 TPM2_PolicySecret 19874 19875 25.4.1 General Description 19876 This command includes a secret-based authorization to a policy. The caller proves knowledge of the 19877 secret value using an authorization session using the authValue associated with authHandle. A 19878 password session, an HMAC session, or a policy session containing TPM2_PolicyAuthValue() or 19879 TPM2_PolicyPassword() will satisfy this requirement. 19880 If a policy session is used and use of the authValue of authHandle is not required, the TPM will return 19881 TPM_RC_MODE. 19882 The secret is the authValue of authObject, which may be any TPM entity with a handle and an associated 19883 authValue. This includes the reserved handles (for example, Platform, Storage, and Endorsement), NV 19884 Indexes, and loaded objects. 19885 NOTE 1 19886 19887 The authorization value for a hierarchy cannot be used in th is command if the hierarchy is disabled. 19888 19889 If the authorization check fails, then the normal dictionary attack logic is invoked. 19890 If the authorization provided by the authorization session is valid, the command parameters are checked 19891 as described in 25.2.2. 19892 When all validations have succeeded, policySessionpolicyDigest is updated by PolicyUpdate() (see 19893 25.2.3). 19894 19895 PolicyUpdate(TPM_CC_PolicySecret, authObjectName, policyRef) 19896 19897 (15) 19898 19899 If the cpHashA command parameter is not an Empty Buffer, it is copied to cpHash in the session context. 19900 The TPM will optionally produce a ticket as described in 25.2.5. 19901 If the session is a trial session, policySessionpolicyDigest is updated as if the authorization is valid but 19902 no check is performed. 19903 NOTE 2 19904 19905 If an HMAC is used to convey the authorization, a separate session is needed for the authorization. 19906 Because the HMAC in that authorization will include a nonce that prevents replay of the 19907 authorization, the value of the nonceTPM parameter in this command is limited. It is retained mostly 19908 to provide processing consistency with TPM2_PolicySigned(). 19909 19910 Page 240 19911 October 31, 2013 19912 19913 Published 19914 Copyright TCG 2006-2013 19915 19916 Family 2.0 19917 Level 00 Revision 00.99 19918 19919 Trusted Platform Module Library 19921 19922 Part 3: Commands 19923 19924 25.4.2 Command and Response 19925 Table 115 TPM2_PolicySecret Command 19926 Type 19927 19928 Name 19929 19930 Description 19931 19932 TPMI_ST_COMMAND_TAG 19933 19934 tag 19935 19936 see clause 8 19937 19938 UINT32 19939 19940 commandSize 19941 19942 TPM_CC 19943 19944 commandCode 19945 19946 TPM_CC_PolicySecret 19947 19948 TPMI_DH_ENTITY 19949 19950 @authHandle 19951 19952 handle for an entity providing the authorization 19953 Auth Index: 1 19954 Auth Role: USER 19955 19956 TPMI_SH_POLICY 19957 19958 policySession 19959 19960 handle for the policy session being extended 19961 Auth Index: None 19962 19963 TPM2B_NONCE 19964 19965 nonceTPM 19966 19967 the policy nonce for the session 19968 If the nonce is not included in the authorization 19969 qualification, this field is the Empty Buffer. 19970 19971 cpHashA 19972 19973 digest of the command parameters to which this 19974 authorization is limited 19975 This not the cpHash for this command but the cpHash 19976 for the command to which this policy session will be 19977 applied. If it is not limited, the parameter will be the 19978 Empty Buffer. 19979 19980 TPM2B_NONCE 19981 19982 policyRef 19983 19984 a reference to a policy relating to the authorization 19985 may be the Empty Buffer 19986 Size is limited to be no larger than the nonce size 19987 supported on the TPM. 19988 19989 INT32 19990 19991 expiration 19992 19993 time when authorization will expire, measured in 19994 seconds from the time that nonceTPM was generated 19995 If expiration is zero, a NULL Ticket is returned. 19996 19997 TPM2B_DIGEST 19998 19999 Table 116 TPM2_PolicySecret Response 20000 Type 20001 20002 Name 20003 20004 Description 20005 20006 TPM_ST 20007 20008 tag 20009 20010 see clause 8 20011 20012 UINT32 20013 20014 responseSize 20015 20016 TPM_RC 20017 20018 responseCode 20019 20020 TPM2B_TIMEOUT 20021 20022 timeout 20023 20024 implementation-specific time value used to indicate to 20025 the TPM when the ticket expires; this ticket will use the 20026 TPMT_ST_AUTH_SECRET structure tag 20027 20028 TPMT_TK_AUTH 20029 20030 policyTicket 20031 20032 produced if the command succeeds and expiration in 20033 the command was non-zero 20034 20035 Family 2.0 20036 Level 00 Revision 00.99 20037 20038 Published 20039 Copyright TCG 2006-2013 20040 20041 Page 241 20042 October 31, 2013 20043 20044 Part 3: Commands 20046 20047 Trusted Platform Module Library 20048 20049 25.4.3 Detailed Actions 20050 1 20051 2 20052 3 20053 20054 #include "InternalRoutines.h" 20055 #include "PolicySecret_fp.h" 20056 #include "Policy_spt_fp.h" 20057 Error Returns 20058 TPM_RC_CPHASH 20059 20060 cpHash for policy was previously set to a value that is not the same 20061 as cpHashA 20062 20063 TPM_RC_EXPIRED 20064 20065 expiration indicates a time in the past 20066 20067 TPM_RC_NONCE 20068 20069 nonceTPM does not match the nonce associated with policySession 20070 20071 TPM_RC_SIZE 20072 20073 cpHashA is not the size of a digest for the hash associated with 20074 policySession 20075 20076 TPM_RC_VALUE 20077 20078 4 20079 5 20080 6 20081 7 20082 8 20083 9 20084 10 20085 11 20086 12 20087 13 20088 14 20089 15 20090 16 20091 17 20092 18 20093 19 20094 20 20095 21 20096 22 20097 23 20098 24 20099 25 20100 26 20101 27 20102 28 20103 29 20104 30 20105 31 20106 32 20107 33 20108 34 20109 35 20110 36 20111 37 20112 38 20113 39 20114 40 20115 41 20116 42 20117 43 20118 44 20119 20120 Meaning 20121 20122 input policyID or expiration does not match the internal data in policy 20123 session 20124 20125 TPM_RC 20126 TPM2_PolicySecret( 20127 PolicySecret_In 20128 PolicySecret_Out 20129 20130 *in, 20131 *out 20132 20133 // IN: input parameter list 20134 // OUT: output parameter list 20135 20136 TPM_RC 20137 SESSION 20138 TPM2B_NAME 20139 UINT32 20140 20141 result; 20142 *session; 20143 entityName; 20144 expiration = (in->expiration < 0) 20145 ? -(in->expiration) : in->expiration; 20146 authTimeout = 0; 20147 20148 ) 20149 { 20150 20151 UINT64 20152 // Input Validation 20153 20154 // Get pointer to the session structure 20155 session = SessionGet(in->policySession); 20156 //Only do input validation if this is not a trial policy session 20157 if(session->attributes.isTrialPolicy == CLEAR) 20158 { 20159 if(expiration != 0) 20160 authTimeout = expiration * 1000 + session->startTime; 20161 result = PolicyParameterChecks(session, authTimeout, 20162 &in->cpHashA, &in->nonceTPM, 20163 RC_PolicySecret_nonceTPM, 20164 RC_PolicySecret_cpHashA, 20165 RC_PolicySecret_expiration); 20166 if(result != TPM_RC_SUCCESS) 20167 return result; 20168 } 20169 // Internal Data Update 20170 // Need the name of the authorizing entity 20171 entityName.t.size = EntityGetName(in->authHandle, &entityName.t.name); 20172 // Update policy context with input policyRef and name of auth key 20173 // This value is computed even for trial sessions. Possibly update the cpHash 20174 PolicyContextUpdate(TPM_CC_PolicySecret, &entityName, &in->policyRef, 20175 20176 Page 242 20177 October 31, 2013 20178 20179 Published 20180 Copyright TCG 2006-2013 20181 20182 Family 2.0 20183 Level 00 Revision 00.99 20184 20185 Trusted Platform Module Library 20187 45 20188 46 20189 47 20190 48 20191 49 20192 50 20193 51 20194 52 20195 53 20196 54 20197 55 20198 56 20199 57 20200 58 20201 59 20202 60 20203 61 20204 62 20205 63 20206 64 20207 65 20208 66 20209 67 20210 68 20211 69 20212 70 20213 71 20214 72 20215 73 20216 74 20217 75 20218 76 20219 77 20220 78 20221 79 20222 80 20223 81 20224 82 20225 83 20226 20227 Part 3: Commands 20228 20229 &in->cpHashA, authTimeout, session); 20230 // Command Output 20231 // Create ticket and timeout buffer if in->expiration < 0 and this is not 20232 // a trial session. 20233 // NOTE: PolicyParameterChecks() makes sure that nonceTPM is present 20234 // when expiration is non-zero. 20235 if( 20236 in->expiration < 0 20237 && session->attributes.isTrialPolicy == CLEAR 20238 ) 20239 { 20240 // Generate timeout buffer. The format of output timeout buffer is 20241 // TPM-specific. 20242 // Note: can't do a direct copy because the output buffer is a byte 20243 // array and it may not be aligned to accept a 64-bit value. The method 20244 // used has the side-effect of making the returned value a big-endian, 20245 // 64-bit value that is byte aligned. 20246 out->timeout.t.size = sizeof(UINT64); 20247 UINT64_TO_BYTE_ARRAY(authTimeout, out->timeout.t.buffer); 20248 // Compute policy ticket 20249 TicketComputeAuth(TPM_ST_AUTH_SECRET, EntityGetHierarchy(in->authHandle), 20250 authTimeout, &in->cpHashA, &in->policyRef, 20251 &entityName, &out->policyTicket); 20252 } 20253 else 20254 { 20255 // timeout buffer is null 20256 out->timeout.t.size = 0; 20257 // auth ticket is null 20258 out->policyTicket.tag = TPM_ST_AUTH_SECRET; 20259 out->policyTicket.hierarchy = TPM_RH_NULL; 20260 out->policyTicket.digest.t.size = 0; 20261 } 20262 return TPM_RC_SUCCESS; 20263 } 20264 20265 Family 2.0 20266 Level 00 Revision 00.99 20267 20268 Published 20269 Copyright TCG 2006-2013 20270 20271 Page 243 20272 October 31, 2013 20273 20274 Part 3: Commands 20276 20277 25.5 20278 20279 Trusted Platform Module Library 20280 20281 TPM2_PolicyTicket 20282 20283 25.5.1 General Description 20284 This command is similar to TPM2_PolicySigned() except that it takes a ticket instead of a signed 20285 authorization. The ticket represents a validated authorization that had an expiration time associated with 20286 it. 20287 The parameters of this command are checked as described in 25.2.2. 20288 If the checks succeed, the TPM uses the timeout, cpHashA, policyRef, and keyName to construct a ticket 20289 to compare with the value in ticket. If these tickets match, then the TPM will create a TPM2B_NAME 20290 (objectName) using authName and update the context of policySession by PolicyUpdate() (see 25.2.3). 20291 20292 PolicyUpdate(commandCode, authName, policyRef) 20293 20294 (16) 20295 20296 If the structure tag of ticket is TPM_ST_AUTH_SECRET, then commandCode will be 20297 TPM_CC_PolicySecret. If the structure tag of ticket is TPM_ST_AUTH_SIGNED, then commandCode will 20298 be TPM_CC_PolicySIgned. 20299 If the cpHashA command parameter is not an Empty Buffer, it may be copied to cpHash in the session 20300 context.as described in 25.2.1. 20301 20302 Page 244 20303 October 31, 2013 20304 20305 Published 20306 Copyright TCG 2006-2013 20307 20308 Family 2.0 20309 Level 00 Revision 00.99 20310 20311 Trusted Platform Module Library 20313 20314 Part 3: Commands 20315 20316 25.5.2 Command and Response 20317 Table 117 TPM2_PolicyTicket Command 20318 Type 20319 20320 Name 20321 20322 Description 20323 20324 TPMI_ST_COMMAND_TAG 20325 20326 tag 20327 20328 see clause 8 20329 20330 UINT32 20331 20332 commandSize 20333 20334 TPM_CC 20335 20336 commandCode 20337 20338 TPM_CC_PolicyTicket 20339 20340 TPMI_SH_POLICY 20341 20342 policySession 20343 20344 handle for the policy session being extended 20345 Auth Index: None 20346 20347 TPM2B_TIMEOUT 20348 20349 timeout 20350 20351 time when authorization will expire 20352 The contents are TPM specific. This shall be the value 20353 returned when ticket was produced. 20354 20355 TPM2B_DIGEST 20356 20357 cpHashA 20358 20359 digest of the command parameters to which this 20360 authorization is limited 20361 If it is not limited, the parameter will be the Empty 20362 Buffer. 20363 20364 TPM2B_NONCE 20365 20366 policyRef 20367 20368 reference to a qualifier for the policy may be the 20369 Empty Buffer 20370 20371 TPM2B_NAME 20372 20373 authName 20374 20375 name of the object that provided the authorization 20376 20377 TPMT_TK_AUTH 20378 20379 ticket 20380 20381 an authorization ticket returned by the TPM in response 20382 to a TPM2_PolicySigned() or TPM2_PolicySecret() 20383 20384 Table 118 TPM2_PolicyTicket Response 20385 Type 20386 20387 Name 20388 20389 Description 20390 20391 TPM_ST 20392 20393 tag 20394 20395 see clause 8 20396 20397 UINT32 20398 20399 responseSize 20400 20401 TPM_RC 20402 20403 responseCode 20404 20405 Family 2.0 20406 Level 00 Revision 00.99 20407 20408 Published 20409 Copyright TCG 2006-2013 20410 20411 Page 245 20412 October 31, 2013 20413 20414 Part 3: Commands 20416 20417 Trusted Platform Module Library 20418 20419 25.5.3 Detailed Actions 20420 1 20421 2 20422 3 20423 20424 #include "InternalRoutines.h" 20425 #include "PolicyTicket_fp.h" 20426 #include "Policy_spt_fp.h" 20427 Error Returns 20428 TPM_RC_CPHASH 20429 20430 policy's cpHash was previously set to a different value 20431 20432 TPM_RC_EXPIRED 20433 20434 timeout value in the ticket is in the past and the ticket has expired 20435 20436 TPM_RC_SIZE 20437 20438 timeout or cpHash has invalid size for the 20439 20440 TPM_RC_TICKET 20441 4 20442 5 20443 6 20444 7 20445 8 20446 9 20447 10 20448 11 20449 12 20450 13 20451 14 20452 15 20453 16 20454 17 20455 18 20456 19 20457 20 20458 21 20459 22 20460 23 20461 24 20462 25 20463 26 20464 27 20465 28 20466 29 20467 30 20468 31 20469 32 20470 33 20471 34 20472 35 20473 36 20474 37 20475 38 20476 39 20477 40 20478 41 20479 42 20480 43 20481 44 20482 45 20483 46 20484 47 20485 48 20486 49 20487 20488 Meaning 20489 20490 ticket is not valid 20491 20492 TPM_RC 20493 TPM2_PolicyTicket( 20494 PolicyTicket_In 20495 20496 *in 20497 20498 // IN: input parameter list 20499 20500 TPM_RC 20501 SESSION 20502 UINT64 20503 TPMT_TK_AUTH 20504 TPM_CC 20505 20506 result; 20507 *session; 20508 timeout; 20509 ticketToCompare; 20510 commandCode = TPM_CC_PolicySecret; 20511 20512 ) 20513 { 20514 20515 // Input Validation 20516 // Get pointer to the session structure 20517 session = SessionGet(in->policySession); 20518 // NOTE: A trial policy session is not allowed to use this command. 20519 // A ticket is used in place of a previously given authorization. Since 20520 // a trial policy doesn't actually authenticate, the validated 20521 // ticket is not necessary and, in place of using a ticket, one 20522 // should use the intended authorization for which the ticket 20523 // would be a subsitute. 20524 if(session->attributes.isTrialPolicy) 20525 return TPM_RCS_ATTRIBUTES + RC_PolicyTicket_policySession; 20526 // Restore timeout data. The format of timeout buffer is TPM-specific. 20527 // In this implementation, we simply copy the value of timeout to the 20528 // buffer. 20529 if(in->timeout.t.size != sizeof(UINT64)) 20530 return TPM_RC_SIZE + RC_PolicyTicket_timeout; 20531 timeout = BYTE_ARRAY_TO_UINT64(in->timeout.t.buffer); 20532 // Do the normal checks on the cpHashA and timeout values 20533 result = PolicyParameterChecks(session, timeout, 20534 &in->cpHashA, NULL, 20535 0, 20536 // no bad nonce return 20537 RC_PolicyTicket_cpHashA, 20538 RC_PolicyTicket_timeout); 20539 if(result != TPM_RC_SUCCESS) 20540 return result; 20541 // Validate Ticket 20542 // Re-generate policy ticket by input parameters 20543 TicketComputeAuth(in->ticket.tag, in->ticket.hierarchy, timeout, &in->cpHashA, 20544 &in->policyRef, &in->authName, &ticketToCompare); 20545 20546 Page 246 20547 October 31, 2013 20548 20549 Published 20550 Copyright TCG 2006-2013 20551 20552 Family 2.0 20553 Level 00 Revision 00.99 20554 20555 Trusted Platform Module Library 20557 50 20558 51 20559 52 20560 53 20561 54 20562 55 20563 56 20564 57 20565 58 20566 59 20567 60 20568 61 20569 62 20570 63 20571 64 20572 65 20573 66 20574 67 20575 68 20576 69 20577 70 20578 71 20579 72 20580 73 20581 20582 Part 3: Commands 20583 20584 // Compare generated digest with input ticket digest 20585 if(!Memory2BEqual(&in->ticket.digest.b, &ticketToCompare.digest.b)) 20586 return TPM_RC_TICKET + RC_PolicyTicket_ticket; 20587 // Internal Data Update 20588 // Is this ticket to take the place of a TPM2_PolicySigned() or 20589 // a TPM2_PolicySecret()? 20590 if(in->ticket.tag == TPM_ST_AUTH_SIGNED) 20591 commandCode = TPM_CC_PolicySigned; 20592 else if(in->ticket.tag == TPM_ST_AUTH_SECRET) 20593 commandCode = TPM_CC_PolicySecret; 20594 else 20595 // There could only be two possible tag values. Any other value should 20596 // be caught by the ticket validation process. 20597 pAssert(FALSE); 20598 // Update policy context 20599 PolicyContextUpdate(commandCode, &in->authName, &in->policyRef, 20600 &in->cpHashA, timeout, session); 20601 return TPM_RC_SUCCESS; 20602 } 20603 20604 Family 2.0 20605 Level 00 Revision 00.99 20606 20607 Published 20608 Copyright TCG 2006-2013 20609 20610 Page 247 20611 October 31, 2013 20612 20613 Part 3: Commands 20615 20616 25.6 20617 20618 Trusted Platform Module Library 20619 20620 TPM2_PolicyOR 20621 20622 25.6.1 General Description 20623 This command allows options in authorizations without requiring that the TPM evaluate all of the options. 20624 If a policy may be satisfied by different sets of conditions, the TPM need only evaluate one set that 20625 satisfies the policy. This command will indicate that one of the required sets of conditions has been 20626 satisfied. 20627 PolicySessionpolicyDigest is compared against the list of provided values. If the current 20628 policySessionpolicyDigest does not match any value in the list, the TPM shall return TPM_RC_VALUE. 20629 Otherwise, it will replace policySessionpolicyDigest with the digest of the concatenation of all of the 20630 digests and return TPM_RC_SUCCESS. 20631 If policySession is a trial session, the TPM will assume that policySessionpolicyDigest matches one of 20632 the list entries and compute the new value of policyDigest. 20633 The algorithm for computing the new value for policyDigest of policySession is: 20634 a) Concatenate all the digest values in pHashList: 20635 20636 digests pHashList.digests[1].buffer || || pHashList.digests[n].buffer 20637 NOTE 1 20638 20639 (17) 20640 20641 The TPM makes no check to see if the size of an entry matches the size of the digest of the 20642 policy. 20643 20644 b) Reset policyDigest to a Zero Digest. 20645 c) Extend the command code and the hashes computed in step a) above: 20646 20647 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyOR || digests) 20648 NOTE 2 20649 20650 (18) 20651 20652 The computation in b) and c) above is equivalent to: 20653 20654 policyDigestnew HpolicyAlg(00 || TPM_CC_PolicyOR || digests) 20655 20656 A TPM shall support a list with at least eight tagged digest values. 20657 NOTE 3 20658 20659 If policies are to be portable between TPMs, then they should not use more than eight values. 20660 20661 Page 248 20662 October 31, 2013 20663 20664 Published 20665 Copyright TCG 2006-2013 20666 20667 Family 2.0 20668 Level 00 Revision 00.99 20669 20670 Trusted Platform Module Library 20672 20673 Part 3: Commands 20674 20675 25.6.2 Command and Response 20676 Table 119 TPM2_PolicyOR Command 20677 Type 20678 20679 Name 20680 20681 Description 20682 20683 TPMI_ST_COMMAND_TAG 20684 20685 tag 20686 20687 UINT32 20688 20689 commandSize 20690 20691 TPM_CC 20692 20693 commandCode 20694 20695 TPM_CC_PolicyOR. 20696 20697 TPMI_SH_POLICY 20698 20699 policySession 20700 20701 handle for the policy session being extended 20702 Auth Index: None 20703 20704 TPML_DIGEST 20705 20706 pHashList 20707 20708 the list of hashes to check for a match 20709 20710 Table 120 TPM2_PolicyOR Response 20711 Type 20712 20713 Name 20714 20715 Description 20716 20717 TPM_ST 20718 20719 tag 20720 20721 see clause 8 20722 20723 UINT32 20724 20725 responseSize 20726 20727 TPM_RC 20728 20729 responseCode 20730 20731 Family 2.0 20732 Level 00 Revision 00.99 20733 20734 Published 20735 Copyright TCG 2006-2013 20736 20737 Page 249 20738 October 31, 2013 20739 20740 Part 3: Commands 20742 20743 Trusted Platform Module Library 20744 20745 25.6.3 Detailed Actions 20746 1 20747 2 20748 3 20749 20750 #include "InternalRoutines.h" 20751 #include "PolicyOR_fp.h" 20752 #include "Policy_spt_fp.h" 20753 Error Returns 20754 TPM_RC_VALUE 20755 20756 4 20757 5 20758 6 20759 7 20760 8 20761 9 20762 10 20763 11 20764 12 20765 13 20766 14 20767 15 20768 16 20769 17 20770 18 20771 19 20772 20 20773 21 20774 22 20775 23 20776 24 20777 25 20778 26 20779 27 20780 28 20781 29 20782 30 20783 31 20784 32 20785 33 20786 34 20787 35 20788 36 20789 37 20790 38 20791 39 20792 40 20793 41 20794 42 20795 43 20796 44 20797 45 20798 46 20799 47 20800 48 20801 49 20802 50 20803 51 20804 52 20805 53 20806 20807 Meaning 20808 no digest in pHashList matched the current value of policyDigest for 20809 policySession 20810 20811 TPM_RC 20812 TPM2_PolicyOR( 20813 PolicyOR_In *in 20814 20815 // IN: input parameter list 20816 20817 ) 20818 { 20819 SESSION 20820 UINT32 20821 20822 *session; 20823 i; 20824 20825 // Input Validation and Update 20826 // Get pointer to the session structure 20827 session = SessionGet(in->policySession); 20828 // Compare and Update Internal Session policy if match 20829 for(i = 0; i < in->pHashList.count; i++) 20830 { 20831 if( 20832 session->attributes.isTrialPolicy == SET 20833 || (Memory2BEqual(&session->u2.policyDigest.b, 20834 &in->pHashList.digests[i].b)) 20835 ) 20836 { 20837 // Found a match 20838 HASH_STATE 20839 hashState; 20840 TPM_CC 20841 commandCode = TPM_CC_PolicyOR; 20842 // Start hash 20843 session->u2.policyDigest.t.size = CryptStartHash(session->authHashAlg, 20844 &hashState); 20845 // Set policyDigest to 0 string and add it to hash 20846 MemorySet(session->u2.policyDigest.t.buffer, 0, 20847 session->u2.policyDigest.t.size); 20848 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 20849 // add command code 20850 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 20851 // Add each of the hashes in the list 20852 for(i = 0; i < in->pHashList.count; i++) 20853 { 20854 // Extend policyDigest 20855 CryptUpdateDigest2B(&hashState, &in->pHashList.digests[i].b); 20856 } 20857 // Complete digest 20858 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 20859 return TPM_RC_SUCCESS; 20860 } 20861 } 20862 // None of the values in the list matched the current policyDigest 20863 return TPM_RC_VALUE + RC_PolicyOR_pHashList; 20864 20865 Page 250 20866 October 31, 2013 20867 20868 Published 20869 Copyright TCG 2006-2013 20870 20871 Family 2.0 20872 Level 00 Revision 00.99 20873 20874 Trusted Platform Module Library 20876 54 20877 20878 Part 3: Commands 20879 20880 } 20881 20882 Family 2.0 20883 Level 00 Revision 00.99 20884 20885 Published 20886 Copyright TCG 2006-2013 20887 20888 Page 251 20889 October 31, 2013 20890 20891 Part 3: Commands 20893 20894 25.7 20895 20896 Trusted Platform Module Library 20897 20898 TPM2_PolicyPCR 20899 20900 25.7.1 General Description 20901 This command is used to cause conditional gating of a policy based on PCR. This allows one group of 20902 authorizations to occur when PCR are in one state and a different set of authorizations when the PCR are 20903 in a different state. If this command is used for a trial policySession, policySessionpolicyDigest will be 20904 updated using the values from the command rather than the values from digest of the TPM PCR. 20905 The TPM will modify the pcrs parameter so that bits that correspond to unimplemented PCR are CLEAR. 20906 If policySession is not a trial policy session, the TPM will use the modified value of pcrs to select PCR 20907 values to hash according to Part 1, Selecting Multiple PCR. The hash algorithm of the policy session is 20908 used to compute a digest (digestTPM) of the selected PCR. If pcrDigest does not have a length of zero, 20909 then it is compared to digestTPM; and if the values do not match, the TPM shall return TPM_RC_VALUE 20910 and make no change to policySessionpolicyDigest. If the values match, or if the length of pcrDigest is 20911 zero, then policySessionpolicyDigest is extended by: 20912 20913 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyPCR || pcrs || digestTPM) 20914 20915 (19) 20916 20917 where 20918 20919 pcrs 20920 20921 the pcrs parameter with bits corresponding to unimplemented 20922 PCR set to 0 20923 20924 digestTPM 20925 20926 the digest of the selected PCR using the hash algorithm of the 20927 policy session 20928 20929 NOTE 1 20930 20931 If the caller provides the expected PCR value, the intention is that the policy evaluation stop at that 20932 point if the PCR do not match. If the caller does not provide the expected PCR value, then the 20933 validity of the settings will not be determined until an attempt is made to use the policy for 20934 authorization. If the policy is constructed such that the PCR check comes before user authorization 20935 checks, this early termination would allow software to avoid unnecessary prompts for user input to 20936 satisfy a policy that would fail later due to incorr ect PCR values. 20937 20938 After this command completes successfully, the TPM shall return TPM_RC_PCR_CHANGED if the policy 20939 session is used for authorization and the PCR are not known to be correct. 20940 The TPM uses a generation number (pcrUpdateCounter) that is incremented each time PCR are 20941 updated (unless the PCR being changed is specified not to cause a change to this counter). The value of 20942 this counter is stored in the policy session context (policySessionpcrUpdateCounter) when this 20943 command is executed. When the policy is used for authorization, the current value of the counter is 20944 compared to the value in the policy session context and the authorization will fail if the values are not the 20945 same. 20946 When this command is executed, policySessionpcrUpdateCounter is checked to see if it has been 20947 previously set (in the reference implementation, it has a value of zero if not previously set). If it has been 20948 set, it will be compared with the current value of pcrUpdateCounter to determine if any PCR changes 20949 have occurred. If the values are different, the TPM shall return TPM_RC_PCR_CHANGED. If 20950 policySessionpcrUpdateCounter has not been set, then it is set to the current value of 20951 pcrUpdateCounter. 20952 If policySession is a trial policy session, the TPM will not check any PCR and will compute: 20953 20954 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyPCR || pcrs || pcrDigest) 20955 20956 (20) 20957 20958 In this computation, pcrs is the input parameter without modification. 20959 NOTE 2 20960 20961 The pcrs parameter is expected to match the configuration of the TPM for which the policy is being 20962 computed which may not be the same as the TPM on which the trial policy is being computed. 20963 20964 Page 252 20965 October 31, 2013 20966 20967 Published 20968 Copyright TCG 2006-2013 20969 20970 Family 2.0 20971 Level 00 Revision 00.99 20972 20973 Trusted Platform Module Library 20975 20976 Part 3: Commands 20977 20978 25.7.2 Command and Response 20979 Table 121 TPM2_PolicyPCR Command 20980 Type 20981 20982 Name 20983 20984 Description 20985 20986 TPMI_ST_COMMAND_TAG 20987 20988 tag 20989 20990 UINT32 20991 20992 commandSize 20993 20994 TPM_CC 20995 20996 commandCode 20997 20998 TPM_CC_PolicyPCR 20999 21000 TPMI_SH_POLICY 21001 21002 policySession 21003 21004 handle for the policy session being extended 21005 Auth Index: None 21006 21007 TPM2B_DIGEST 21008 21009 pcrDigest 21010 21011 expected digest value of the selected PCR using the 21012 hash algorithm of the session; may be zero length 21013 21014 TPML_PCR_SELECTION 21015 21016 pcrs 21017 21018 the PCR to include in the check digest 21019 21020 Table 122 TPM2_PolicyPCR Response 21021 Type 21022 21023 Name 21024 21025 Description 21026 21027 TPM_ST 21028 21029 tag 21030 21031 see clause 8 21032 21033 UINT32 21034 21035 responseSize 21036 21037 TPM_RC 21038 21039 responseCode 21040 21041 Family 2.0 21042 Level 00 Revision 00.99 21043 21044 Published 21045 Copyright TCG 2006-2013 21046 21047 Page 253 21048 October 31, 2013 21049 21050 Part 3: Commands 21052 21053 Trusted Platform Module Library 21054 21055 25.7.3 Detailed Actions 21056 1 21057 2 21058 21059 #include "InternalRoutines.h" 21060 #include "PolicyPCR_fp.h" 21061 Error Returns 21062 TPM_RC_VALUE 21063 21064 if provided, pcrDigest does not match the current PCR settings 21065 21066 TPM_RC_PCR_CHANGED 21067 3 21068 4 21069 5 21070 6 21071 7 21072 8 21073 9 21074 10 21075 11 21076 12 21077 13 21078 14 21079 15 21080 16 21081 17 21082 18 21083 19 21084 20 21085 21 21086 22 21087 23 21088 24 21089 25 21090 26 21091 27 21092 28 21093 29 21094 30 21095 31 21096 32 21097 33 21098 34 21099 35 21100 36 21101 37 21102 38 21103 39 21104 40 21105 41 21106 42 21107 43 21108 44 21109 45 21110 46 21111 47 21112 48 21113 49 21114 50 21115 51 21116 52 21117 53 21118 21119 Meaning 21120 21121 a previous TPM2_PolicyPCR() set pcrCounter and it has changed 21122 21123 TPM_RC 21124 TPM2_PolicyPCR( 21125 PolicyPCR_In 21126 21127 *in 21128 21129 // IN: input parameter list 21130 21131 SESSION 21132 TPM2B_DIGEST 21133 BYTE 21134 UINT32 21135 BYTE 21136 TPM_CC 21137 HASH_STATE 21138 21139 *session; 21140 pcrDigest; 21141 pcrs[sizeof(TPML_PCR_SELECTION)]; 21142 pcrSize; 21143 *buffer; 21144 commandCode = TPM_CC_PolicyPCR; 21145 hashState; 21146 21147 ) 21148 { 21149 21150 // Input Validation 21151 // Get pointer to the session structure 21152 session = SessionGet(in->policySession); 21153 // Do validation for non trial session 21154 if(session->attributes.isTrialPolicy == CLEAR) 21155 { 21156 // Make sure that this is not going to invalidate a previous PCR check 21157 if(session->pcrCounter != 0 && session->pcrCounter != gr.pcrCounter) 21158 return TPM_RC_PCR_CHANGED; 21159 // Compute current PCR digest 21160 PCRComputeCurrentDigest(session->authHashAlg, &in->pcrs, &pcrDigest); 21161 // If the caller specified the PCR digest and it does not 21162 // match the current PCR settings, return an error.. 21163 if(in->pcrDigest.t.size != 0) 21164 { 21165 if(!Memory2BEqual(&in->pcrDigest.b, &pcrDigest.b)) 21166 return TPM_RC_VALUE + RC_PolicyPCR_pcrDigest; 21167 } 21168 } 21169 else 21170 { 21171 // For trial session, just use the input PCR digest 21172 pcrDigest = in->pcrDigest; 21173 } 21174 // Internal Data Update 21175 // Update policy hash 21176 // policyDigestnew = hash( 21177 policyDigestold || TPM_CC_PolicyPCR 21178 // 21179 || pcrs || pcrDigest) 21180 // Start hash 21181 CryptStartHash(session->authHashAlg, &hashState); 21182 // add old digest 21183 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 21184 21185 Page 254 21186 October 31, 2013 21187 21188 Published 21189 Copyright TCG 2006-2013 21190 21191 Family 2.0 21192 Level 00 Revision 00.99 21193 21194 Trusted Platform Module Library 21196 54 21197 55 21198 56 21199 57 21200 58 21201 59 21202 60 21203 61 21204 62 21205 63 21206 64 21207 65 21208 66 21209 67 21210 68 21211 69 21212 70 21213 71 21214 72 21215 73 21216 74 21217 75 21218 76 21219 21220 Part 3: Commands 21221 21222 // add commandCode 21223 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 21224 // add PCRS 21225 buffer = pcrs; 21226 pcrSize = TPML_PCR_SELECTION_Marshal(&in->pcrs, &buffer, NULL); 21227 CryptUpdateDigest(&hashState, pcrSize, pcrs); 21228 // add PCR digest 21229 CryptUpdateDigest2B(&hashState, &pcrDigest.b); 21230 // complete the hash and get the results 21231 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 21232 // update pcrCounter in session context for non trial session 21233 if(session->attributes.isTrialPolicy == CLEAR) 21234 { 21235 session->pcrCounter = gr.pcrCounter; 21236 } 21237 return TPM_RC_SUCCESS; 21238 } 21239 21240 Family 2.0 21241 Level 00 Revision 00.99 21242 21243 Published 21244 Copyright TCG 2006-2013 21245 21246 Page 255 21247 October 31, 2013 21248 21249 Part 3: Commands 21251 21252 25.8 21253 21254 Trusted Platform Module Library 21255 21256 TPM2_PolicyLocality 21257 21258 25.8.1 General Description 21259 This command indicates that the authorization will be limited to a specific locality. 21260 policySessioncommandLocality is a parameter kept in the session context. It is initialized when the 21261 policy session is started to allow the policy to apply to any locality. 21262 If locality has a value greater than 31, then an extended locality is indicated. For an extended locality, the 21263 TPM will validate that policySessioncommandLocality is has not previously been set or that the current 21264 value of policySessioncommandLocality is the same as locality (TPM_RC_RANGE). 21265 When locality is not an extended locality, the TPM will validate that the policySessioncommandLocality 21266 is not set or is not set to an extended locality value (TPM_RC_RANGE). If not the TPM will disable any 21267 locality not SET in the locality parameter. If the result of disabling localities results in no locality being 21268 enabled, the TPM will return TPM_RC_RANGE. 21269 If no error occurred in the validation of locality, policySessionpolicyDigest is extended with 21270 21271 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyLocality || locality) 21272 21273 (21) 21274 21275 Then policySessioncommandLocality is updated to indicate which localities are still allowed after 21276 execution of TPM2_PolicyLocality(). 21277 When the policy session is used to authorize a command, the authorization will fail if the locality used for 21278 the command is not one of the enabled localities in policySessioncommandLocality. 21279 21280 Page 256 21281 October 31, 2013 21282 21283 Published 21284 Copyright TCG 2006-2013 21285 21286 Family 2.0 21287 Level 00 Revision 00.99 21288 21289 Trusted Platform Module Library 21291 21292 Part 3: Commands 21293 21294 25.8.2 Command and Response 21295 Table 123 TPM2_PolicyLocality Command 21296 Type 21297 21298 Name 21299 21300 Description 21301 21302 TPMI_ST_COMMAND_TAG 21303 21304 tag 21305 21306 UINT32 21307 21308 commandSize 21309 21310 TPM_CC 21311 21312 commandCode 21313 21314 TPM_CC_PolicyLocality 21315 21316 TPMI_SH_POLICY 21317 21318 policySession 21319 21320 handle for the policy session being extended 21321 Auth Index: None 21322 21323 TPMA_LOCALITY 21324 21325 locality 21326 21327 the allowed localities for the policy 21328 21329 Table 124 TPM2_PolicyLocality Response 21330 Type 21331 21332 Name 21333 21334 Description 21335 21336 TPM_ST 21337 21338 tag 21339 21340 see clause 8 21341 21342 UINT32 21343 21344 responseSize 21345 21346 TPM_RC 21347 21348 responseCode 21349 21350 Family 2.0 21351 Level 00 Revision 00.99 21352 21353 Published 21354 Copyright TCG 2006-2013 21355 21356 Page 257 21357 October 31, 2013 21358 21359 Part 3: Commands 21361 21362 Trusted Platform Module Library 21363 21364 25.8.3 Detailed Actions 21365 1 21366 2 21367 21368 #include "InternalRoutines.h" 21369 #include "PolicyLocality_fp.h" 21370 21371 Limit a policy to a specific locality 21372 Error Returns 21373 TPM_RC_RANGE 21374 21375 3 21376 4 21377 5 21378 6 21379 7 21380 8 21381 9 21382 10 21383 11 21384 12 21385 13 21386 14 21387 15 21388 16 21389 17 21390 18 21391 19 21392 20 21393 21 21394 22 21395 23 21396 24 21397 25 21398 26 21399 27 21400 28 21401 29 21402 30 21403 31 21404 32 21405 33 21406 34 21407 35 21408 36 21409 37 21410 38 21411 39 21412 40 21413 41 21414 42 21415 43 21416 44 21417 45 21418 46 21419 47 21420 48 21421 49 21422 50 21423 51 21424 52 21425 21426 Meaning 21427 all the locality values selected by locality have been disabled by 21428 previous TPM2_PolicyLocality() calls. 21429 21430 TPM_RC 21431 TPM2_PolicyLocality( 21432 PolicyLocality_In 21433 21434 *in 21435 21436 // IN: input parameter list 21437 21438 ) 21439 { 21440 SESSION 21441 BYTE 21442 BYTE 21443 UINT32 21444 BYTE 21445 TPM_CC 21446 HASH_STATE 21447 21448 *session; 21449 marshalBuffer[sizeof(TPMA_LOCALITY)]; 21450 prevSetting[sizeof(TPMA_LOCALITY)]; 21451 marshalSize; 21452 *buffer; 21453 commandCode = TPM_CC_PolicyLocality; 21454 hashState; 21455 21456 // Input Validation 21457 // Get pointer to the session structure 21458 session = SessionGet(in->policySession); 21459 // Get new locality setting in canonical form 21460 buffer = marshalBuffer; 21461 marshalSize = TPMA_LOCALITY_Marshal(&in->locality, &buffer, NULL); 21462 // Its an error if the locality parameter is zero 21463 if(marshalBuffer[0] == 0) 21464 return TPM_RC_RANGE + RC_PolicyLocality_locality; 21465 // Get existing locality setting in canonical form 21466 buffer = prevSetting; 21467 TPMA_LOCALITY_Marshal(&session->commandLocality, &buffer, NULL); 21468 // If the locality has been previously set, then it needs to be the same 21469 // tye as the input locality (i.e. both extended or both normal 21470 if(prevSetting[0] != 0 && ((prevSetting[0] <= 0) != (marshalBuffer[0] <= 0))) 21471 return TPM_RC_RANGE + RC_PolicyLocality_locality; 21472 // See if the input is a regular or extended locality 21473 if(marshalBuffer[0] < 32) 21474 { 21475 // For regular locality 21476 // The previous setting must not be an extended locality 21477 if(prevSetting[0] > 31) 21478 return TPM_RC_RANGE + RC_PolicyLocality_locality; 21479 // if there was no previous setting, start with all normal localities 21480 // enabled 21481 if(prevSetting[0] == 0) 21482 prevSetting[0] = 0x1F; 21483 // AND the new setting with the previous setting and store it in prevSetting 21484 21485 Page 258 21486 October 31, 2013 21487 21488 Published 21489 Copyright TCG 2006-2013 21490 21491 Family 2.0 21492 Level 00 Revision 00.99 21493 21494 Trusted Platform Module Library 21496 53 21497 54 21498 55 21499 56 21500 57 21501 58 21502 59 21503 60 21504 61 21505 62 21506 63 21507 64 21508 65 21509 66 21510 67 21511 68 21512 69 21513 70 21514 71 21515 72 21516 73 21517 74 21518 75 21519 76 21520 77 21521 78 21522 79 21523 80 21524 81 21525 82 21526 83 21527 84 21528 85 21529 86 21530 87 21531 88 21532 89 21533 90 21534 91 21535 92 21536 93 21537 94 21538 95 21539 96 21540 97 21541 21542 Part 3: Commands 21543 21544 prevSetting[0] &= marshalBuffer[0]; 21545 // The result setting can not be 0 21546 if(prevSetting[0] == 0) 21547 return TPM_RC_RANGE + RC_PolicyLocality_locality; 21548 } 21549 else 21550 { 21551 // for extended locality 21552 // if the locality has already been set, then it must match the 21553 if(prevSetting[0] != 0 && prevSetting[0] != marshalBuffer[0]) 21554 return TPM_RC_RANGE + RC_PolicyLocality_locality; 21555 // Setting is OK 21556 prevSetting[0] = marshalBuffer[0]; 21557 } 21558 // Internal Data Update 21559 // Update policy hash 21560 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyLocality || locality) 21561 // Start hash 21562 CryptStartHash(session->authHashAlg, &hashState); 21563 // add old digest 21564 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 21565 // add commandCode 21566 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 21567 // add input locality 21568 CryptUpdateDigest(&hashState, marshalSize, marshalBuffer); 21569 // complete the digest 21570 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 21571 // update session locality by unmarshal function. The function must succeed 21572 // because both input and existing locality setting have been validated. 21573 buffer = prevSetting; 21574 TPMA_LOCALITY_Unmarshal(&session->commandLocality, &buffer, 21575 (INT32 *) &marshalSize); 21576 return TPM_RC_SUCCESS; 21577 } 21578 21579 Family 2.0 21580 Level 00 Revision 00.99 21581 21582 Published 21583 Copyright TCG 2006-2013 21584 21585 Page 259 21586 October 31, 2013 21587 21588 Part 3: Commands 21590 21591 25.9 21592 21593 Trusted Platform Module Library 21594 21595 TPM2_PolicyNV 21596 21597 25.9.1 General Description 21598 This command is used to cause conditional gating of a policy based on the contents of an NV Index. 21599 If policySession is a trial policy session, the TPM will update policySessionpolicyDigest as shown in 21600 equations (22) and (23) below and return TPM_RC_SUCCESS. It will not perform any validation. The 21601 remainder of this general description would apply only if policySession is not a trial policy session. 21602 An authorization session providing authorization to read the NV Index shall be provided. 21603 NOTE 1 21604 21605 If read access is controlled by policy, the policy should include a branch that authorizes a 21606 TPM2_PolicyNV(). 21607 21608 If TPMA_NV_WRITTEN is not SET in the NV Index, the TPM shall return TPM_RC_NV_UNINITIALIZED. 21609 The TPM will validate that the size of operandB plus offset is not greater than the size of the NV Index. If 21610 it is, the TPM shall return TPM_RC_SIZE. 21611 The TPM will perform the indicated arithmetic check on the indicated portion of the selected NV Index. If 21612 the check fails, the TPM shall return TPM_RC_POLICY and not change policySessionpolicyDigest. If 21613 the check succeeds, the TPM will hash the arguments: 21614 21615 args HpolicyAlg(operand.buffer || offset || operation) 21616 21617 (22) 21618 21619 where 21620 21621 HpolicyAlg() 21622 21623 hash function using the algorithm of the policy session 21624 21625 operandB 21626 21627 the value used for the comparison 21628 21629 offset 21630 21631 offset from the start of the NV Index data to start the comparison 21632 21633 operation 21634 21635 the operation parameter indicating the comparison being 21636 performed 21637 21638 The value of args and the Name of the NV Index are extended to policySessionpolicyDigest by 21639 21640 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyNV || args || nvIndexName) 21641 21642 (23) 21643 21644 where 21645 21646 HpolicyAlg() 21647 21648 hash function using the algorithm of the policy session 21649 21650 args 21651 21652 value computed in equation (22) 21653 21654 nvIndexName 21655 21656 the Name of the NV Index 21657 21658 The signed arithmetic operations are performed using twos-compliment. 21659 Magnitude comparisons assume that the octet at offset zero in the referenced NV location and in 21660 operandB contain the most significant octet of the data. 21661 NOTE 2 21662 21663 When an Index is written, it has a different authorization name than an Index that has not been 21664 written. It is possible to use this change in the NV Index to create a write-once Index. 21665 21666 Page 260 21667 October 31, 2013 21668 21669 Published 21670 Copyright TCG 2006-2013 21671 21672 Family 2.0 21673 Level 00 Revision 00.99 21674 21675 Trusted Platform Module Library 21677 21678 Part 3: Commands 21679 21680 25.9.2 Command and Response 21681 Table 125 TPM2_PolicyNV Command 21682 Type 21683 21684 Name 21685 21686 Description 21687 21688 TPMI_ST_COMMAND_TAG 21689 21690 tag 21691 21692 UINT32 21693 21694 commandSize 21695 21696 TPM_CC 21697 21698 commandCode 21699 21700 TPM_CC_PolicyNV 21701 21702 TPMI_RH_NV_AUTH 21703 21704 @authHandle 21705 21706 handle indicating the source of the authorization value 21707 Auth Index: 1 21708 Auth Role: USER 21709 21710 TPMI_RH_NV_INDEX 21711 21712 nvIndex 21713 21714 the NV Index of the area to read 21715 Auth Index: None 21716 21717 TPMI_SH_POLICY 21718 21719 policySession 21720 21721 handle for the policy session being extended 21722 Auth Index: None 21723 21724 TPM2B_OPERAND 21725 21726 operandB 21727 21728 the second operand 21729 21730 UINT16 21731 21732 offset 21733 21734 the offset in the NV Index for the start of operand A 21735 21736 TPM_EO 21737 21738 operation 21739 21740 the comparison to make 21741 21742 Table 126 TPM2_PolicyNV Response 21743 Type 21744 21745 Name 21746 21747 Description 21748 21749 TPM_ST 21750 21751 tag 21752 21753 see clause 8 21754 21755 UINT32 21756 21757 responseSize 21758 21759 TPM_RC 21760 21761 responseCode 21762 21763 Family 2.0 21764 Level 00 Revision 00.99 21765 21766 Published 21767 Copyright TCG 2006-2013 21768 21769 Page 261 21770 October 31, 2013 21771 21772 Part 3: Commands 21774 21775 Trusted Platform Module Library 21776 21777 25.9.3 Detailed Actions 21778 1 21779 2 21780 3 21781 4 21782 21783 #include 21784 #include 21785 #include 21786 #include 21787 21788 "InternalRoutines.h" 21789 "PolicyNV_fp.h" 21790 "Policy_spt_fp.h" 21791 "NV_spt_fp.h" 21792 21793 // Include NV support routine for read access check 21794 21795 Error Returns 21796 TPM_RC_AUTH_TYPE 21797 21798 NV index authorization type is not correct 21799 21800 TPM_RC_NV_LOCKED 21801 21802 NV index read locked 21803 21804 TPM_RC_NV_UNINITIALIZED 21805 21806 the NV index has not been initialized 21807 21808 TPM_RC_POLICY 21809 21810 the comparison to the NV contents failed 21811 21812 TPM_RC_SIZE 21813 21814 5 21815 6 21816 7 21817 8 21818 9 21819 10 21820 11 21821 12 21822 13 21823 14 21824 15 21825 16 21826 17 21827 18 21828 19 21829 20 21830 21 21831 22 21832 23 21833 24 21834 25 21835 26 21836 27 21837 28 21838 29 21839 30 21840 31 21841 32 21842 33 21843 34 21844 35 21845 36 21846 37 21847 38 21848 39 21849 40 21850 41 21851 42 21852 43 21853 44 21854 45 21855 46 21856 21857 Meaning 21858 21859 the size of nvIndex data starting at offset is less than the size of 21860 operandB 21861 21862 TPM_RC 21863 TPM2_PolicyNV( 21864 PolicyNV_In 21865 21866 *in 21867 21868 // IN: input parameter list 21869 21870 TPM_RC 21871 SESSION 21872 NV_INDEX 21873 BYTE 21874 TPM2B_NAME 21875 TPM_CC 21876 HASH_STATE 21877 TPM2B_DIGEST 21878 21879 result; 21880 *session; 21881 nvIndex; 21882 nvBuffer[sizeof(in->operandB.t.buffer)]; 21883 nvName; 21884 commandCode = TPM_CC_PolicyNV; 21885 hashState; 21886 argHash; 21887 21888 ) 21889 { 21890 21891 // Input Validation 21892 // Get NV index information 21893 NvGetIndexInfo(in->nvIndex, &nvIndex); 21894 // Get pointer to the session structure 21895 session = SessionGet(in->policySession); 21896 //If this is a trial policy, skip all validations and the operation 21897 if(session->attributes.isTrialPolicy == CLEAR) 21898 { 21899 // NV Read access check. NV index should be allowed for read. A 21900 // TPM_RC_AUTH_TYPE or TPM_RC_NV_LOCKED error may be return at this 21901 // point 21902 result = NvReadAccessChecks(in->authHandle, in->nvIndex); 21903 if(result != TPM_RC_SUCCESS) return result; 21904 // Valid NV data size should not be smaller than input operandB size 21905 if((nvIndex.publicArea.dataSize - in->offset) < in->operandB.t.size) 21906 return TPM_RC_SIZE + RC_PolicyNV_operandB; 21907 // Arithmetic Comparison 21908 // Get NV data. The size of NV data equals the input operand B size 21909 NvGetIndexData(in->nvIndex, &nvIndex, in->offset, 21910 in->operandB.t.size, nvBuffer); 21911 switch(in->operation) 21912 21913 Page 262 21914 October 31, 2013 21915 21916 Published 21917 Copyright TCG 2006-2013 21918 21919 Family 2.0 21920 Level 00 Revision 00.99 21921 21922 Trusted Platform Module Library 21924 47 21925 48 21926 49 21927 50 21928 51 21929 52 21930 53 21931 54 21932 55 21933 56 21934 57 21935 58 21936 59 21937 60 21938 61 21939 62 21940 63 21941 64 21942 65 21943 66 21944 67 21945 68 21946 69 21947 70 21948 71 21949 72 21950 73 21951 74 21952 75 21953 76 21954 77 21955 78 21956 79 21957 80 21958 81 21959 82 21960 83 21961 84 21962 85 21963 86 21964 87 21965 88 21966 89 21967 90 21968 91 21969 92 21970 93 21971 94 21972 95 21973 96 21974 97 21975 98 21976 99 21977 100 21978 101 21979 102 21980 103 21981 104 21982 105 21983 106 21984 107 21985 108 21986 109 21987 110 21988 21989 Part 3: Commands 21990 21991 { 21992 case TPM_EO_EQ: 21993 // compare A = B 21994 if(CryptCompare(in->operandB.t.size, nvBuffer, 21995 in->operandB.t.size, in->operandB.t.buffer) 21996 return TPM_RC_POLICY; 21997 break; 21998 case TPM_EO_NEQ: 21999 // compare A != B 22000 if(CryptCompare(in->operandB.t.size, nvBuffer, 22001 in->operandB.t.size, in->operandB.t.buffer) 22002 return TPM_RC_POLICY; 22003 break; 22004 case TPM_EO_SIGNED_GT: 22005 // compare A > B signed 22006 if(CryptCompareSigned(in->operandB.t.size, nvBuffer, 22007 in->operandB.t.size, in->operandB.t.buffer) 22008 return TPM_RC_POLICY; 22009 break; 22010 case TPM_EO_UNSIGNED_GT: 22011 // compare A > B unsigned 22012 if(CryptCompare(in->operandB.t.size, nvBuffer, 22013 in->operandB.t.size, in->operandB.t.buffer) 22014 return TPM_RC_POLICY; 22015 break; 22016 case TPM_EO_SIGNED_LT: 22017 // compare A < B signed 22018 if(CryptCompareSigned(in->operandB.t.size, nvBuffer, 22019 in->operandB.t.size, in->operandB.t.buffer) 22020 return TPM_RC_POLICY; 22021 break; 22022 case TPM_EO_UNSIGNED_LT: 22023 // compare A < B unsigned 22024 if(CryptCompare(in->operandB.t.size, nvBuffer, 22025 in->operandB.t.size, in->operandB.t.buffer) 22026 return TPM_RC_POLICY; 22027 break; 22028 case TPM_EO_SIGNED_GE: 22029 // compare A >= B signed 22030 if(CryptCompareSigned(in->operandB.t.size, nvBuffer, 22031 in->operandB.t.size, in->operandB.t.buffer) 22032 return TPM_RC_POLICY; 22033 break; 22034 case TPM_EO_UNSIGNED_GE: 22035 // compare A >= B unsigned 22036 if(CryptCompare(in->operandB.t.size, nvBuffer, 22037 in->operandB.t.size, in->operandB.t.buffer) 22038 return TPM_RC_POLICY; 22039 break; 22040 case TPM_EO_SIGNED_LE: 22041 // compare A <= B signed 22042 if(CryptCompareSigned(in->operandB.t.size, nvBuffer, 22043 in->operandB.t.size, in->operandB.t.buffer) 22044 return TPM_RC_POLICY; 22045 break; 22046 case TPM_EO_UNSIGNED_LE: 22047 // compare A <= B unsigned 22048 if(CryptCompare(in->operandB.t.size, nvBuffer, 22049 in->operandB.t.size, in->operandB.t.buffer) 22050 return TPM_RC_POLICY; 22051 break; 22052 case TPM_EO_BITSET: 22053 // All bits SET in B are SET in A. ((A&B)=B) 22054 { 22055 22056 Family 2.0 22057 Level 00 Revision 00.99 22058 22059 Published 22060 Copyright TCG 2006-2013 22061 22062 != 0) 22063 22064 == 0) 22065 22066 <= 0) 22067 22068 <= 0) 22069 22070 >= 0) 22071 22072 >= 0) 22073 22074 < 0) 22075 22076 < 0) 22077 22078 > 0) 22079 22080 > 0) 22081 22082 Page 263 22083 October 31, 2013 22084 22085 Part 3: Commands 22087 111 22088 112 22089 113 22090 114 22091 115 22092 116 22093 117 22094 118 22095 119 22096 120 22097 121 22098 122 22099 123 22100 124 22101 125 22102 126 22103 127 22104 128 22105 129 22106 130 22107 131 22108 132 22109 133 22110 134 22111 135 22112 136 22113 137 22114 138 22115 139 22116 140 22117 141 22118 142 22119 143 22120 144 22121 145 22122 146 22123 147 22124 148 22125 149 22126 150 22127 151 22128 152 22129 153 22130 154 22131 155 22132 156 22133 157 22134 158 22135 159 22136 160 22137 161 22138 162 22139 163 22140 164 22141 165 22142 166 22143 167 22144 168 22145 169 22146 170 22147 171 22148 22149 Trusted Platform Module Library 22150 22151 UINT32 i; 22152 for (i = 0; i < in->operandB.t.size; i++) 22153 if((nvBuffer[i] & in->operandB.t.buffer[i]) 22154 != in->operandB.t.buffer[i]) 22155 return TPM_RC_POLICY; 22156 } 22157 break; 22158 case TPM_EO_BITCLEAR: 22159 // All bits SET in B are CLEAR in A. ((A&B)=0) 22160 { 22161 UINT32 i; 22162 for (i = 0; i < in->operandB.t.size; i++) 22163 if((nvBuffer[i] & in->operandB.t.buffer[i]) != 0) 22164 return TPM_RC_POLICY; 22165 } 22166 break; 22167 default: 22168 pAssert(FALSE); 22169 break; 22170 } 22171 } 22172 // Internal Data Update 22173 // Start argument hash 22174 argHash.t.size = CryptStartHash(session->authHashAlg, &hashState); 22175 // add operandB 22176 CryptUpdateDigest2B(&hashState, &in->operandB.b); 22177 // add offset 22178 CryptUpdateDigestInt(&hashState, sizeof(UINT16), &in->offset); 22179 // add operation 22180 CryptUpdateDigestInt(&hashState, sizeof(TPM_EO), &in->operation); 22181 // complete argument digest 22182 CryptCompleteHash2B(&hashState, &argHash.b); 22183 // Update policyDigest 22184 // Start digest 22185 CryptStartHash(session->authHashAlg, &hashState); 22186 // add old digest 22187 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 22188 // add commandCode 22189 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 22190 // add argument digest 22191 CryptUpdateDigest2B(&hashState, &argHash.b); 22192 // Adding nvName 22193 nvName.t.size = EntityGetName(in->nvIndex, &nvName.t.name); 22194 CryptUpdateDigest2B(&hashState, &nvName.b); 22195 // complete the digest 22196 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 22197 return TPM_RC_SUCCESS; 22198 } 22199 22200 Page 264 22201 October 31, 2013 22202 22203 Published 22204 Copyright TCG 2006-2013 22205 22206 Family 2.0 22207 Level 00 Revision 00.99 22208 22209 Trusted Platform Module Library 22211 22212 Part 3: Commands 22213 22214 25.10 TPM2_PolicyCounterTimer 22215 25.10.1 22216 22217 General Description 22218 22219 This command is used to cause conditional gating of a policy based on the contents of the 22220 TPMS_TIME_INFO structure. 22221 If policySession is a trial policy session, the TPM will update policySessionpolicyDigest as shown in 22222 equations (24) and (25) below and return TPM_RC_SUCCESS. It will not perform any validation. The 22223 remainder of this general description would apply only if policySession is not a trial policy session. 22224 The TPM will perform the indicated arithmetic check on the indicated portion of the TPMS_TIME_INFO 22225 structure. If the check fails, the TPM shall return TPM_RC_POLICY and not change 22226 policySessionpolicyDigest. If the check succeeds, the TPM will hash the arguments: 22227 22228 args HpolicyAlg(operandB.buffer || offset || operation) 22229 22230 (24) 22231 22232 where 22233 22234 HpolicyAlg() 22235 22236 hash function using the algorithm of the policy session 22237 22238 operandB.buffer 22239 22240 the value used for the comparison 22241 22242 offset 22243 22244 offset from the start of the TPMS_TIME_INFO structure at which 22245 the comparison starts 22246 22247 operation 22248 22249 the operation parameter indicating the comparison being 22250 performed 22251 22252 The value of args is extended to policySessionpolicyDigest by 22253 22254 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyCounterTimer || args) 22255 22256 (25) 22257 22258 where 22259 22260 HpolicyAlg() 22261 22262 hash function using the algorithm of the policy session 22263 22264 args 22265 22266 value computed in equation (24) 22267 22268 The signed arithmetic operations are performed using twos-compliment. 22269 Magnitude comparisons assume that the octet at offset zero in the referenced location and in operandB 22270 contain the most significant octet of the data. 22271 22272 Family 2.0 22273 Level 00 Revision 00.99 22274 22275 Published 22276 Copyright TCG 2006-2013 22277 22278 Page 265 22279 October 31, 2013 22280 22281 Part 3: Commands 22283 22284 25.10.2 22285 22286 Trusted Platform Module Library 22287 22288 Command and Response 22289 Table 127 TPM2_PolicyCounterTimer Command 22290 22291 Type 22292 22293 Name 22294 22295 Description 22296 22297 TPMI_ST_COMMAND_TAG 22298 22299 tag 22300 22301 UINT32 22302 22303 commandSize 22304 22305 TPM_CC 22306 22307 commandCode 22308 22309 TPM_CC_PolicyCounterTimer 22310 22311 TPMI_SH_POLICY 22312 22313 policySession 22314 22315 handle for the policy session being extended 22316 Auth Index: None 22317 22318 TPM2B_OPERAND 22319 22320 operandB 22321 22322 the second operand 22323 22324 UINT16 22325 22326 offset 22327 22328 the offset in TPMS_TIME_INFO structure for the start of 22329 operand A 22330 22331 TPM_EO 22332 22333 operation 22334 22335 the comparison to make 22336 22337 Table 128 TPM2_PolicyCounterTimer Response 22338 Type 22339 22340 Name 22341 22342 Description 22343 22344 TPM_ST 22345 22346 tag 22347 22348 see clause 8 22349 22350 UINT32 22351 22352 responseSize 22353 22354 TPM_RC 22355 22356 responseCode 22357 22358 Page 266 22359 October 31, 2013 22360 22361 Published 22362 Copyright TCG 2006-2013 22363 22364 Family 2.0 22365 Level 00 Revision 00.99 22366 22367 Trusted Platform Module Library 22369 22370 25.10.3 22371 1 22372 2 22373 3 22374 22375 Part 3: Commands 22376 22377 Detailed Actions 22378 22379 #include "InternalRoutines.h" 22380 #include "PolicyCounterTimer_fp.h" 22381 #include "Policy_spt_fp.h" 22382 Error Returns 22383 TPM_RC_POLICY 22384 22385 the comparison of the selected portion of the TPMS_TIME_INFO with 22386 operandB failed 22387 22388 TPM_RC_RANGE 22389 4 22390 5 22391 6 22392 7 22393 8 22394 9 22395 10 22396 11 22397 12 22398 13 22399 14 22400 15 22401 16 22402 17 22403 18 22404 19 22405 20 22406 21 22407 22 22408 23 22409 24 22410 25 22411 26 22412 27 22413 28 22414 29 22415 30 22416 31 22417 32 22418 33 22419 34 22420 35 22421 36 22422 37 22423 38 22424 39 22425 40 22426 41 22427 42 22428 43 22429 44 22430 45 22431 46 22432 47 22433 48 22434 49 22435 50 22436 51 22437 52 22438 22439 Meaning 22440 22441 offset + size exceed size of TPMS_TIME_INFO structure 22442 22443 TPM_RC 22444 TPM2_PolicyCounterTimer( 22445 PolicyCounterTimer_In 22446 22447 *in 22448 22449 // IN: input parameter list 22450 22451 ) 22452 { 22453 TPM_RC 22454 SESSION 22455 TIME_INFO 22456 TPM_CC 22457 HASH_STATE 22458 TPM2B_DIGEST 22459 22460 result; 22461 *session; 22462 infoData; 22463 // data buffer of TPMS_TIME_INFO 22464 commandCode = TPM_CC_PolicyCounterTimer; 22465 hashState; 22466 argHash; 22467 22468 // Input Validation 22469 // If the command is going to use any part of the counter or timer, need 22470 // to verify that time is advancing. 22471 // The time and clock vales are the first two 64-bit values in the clock 22472 if(in->offset < <K>sizeof(UINT64) + sizeof(UINT64)) 22473 { 22474 // Using Clock or Time so see if clock is running. Clock doesn't run while 22475 // NV is unavailable. 22476 // TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned here. 22477 result = NvIsAvailable(); 22478 if(result != TPM_RC_SUCCESS) 22479 return result; 22480 } 22481 // Get pointer to the session structure 22482 session = SessionGet(in->policySession); 22483 //If this is a trial policy, skip all validations and the operation 22484 if(session->attributes.isTrialPolicy == CLEAR) 22485 { 22486 // Get time data info. The size of time info data equals the input 22487 // operand B size. A TPM_RC_RANGE error may be returned at this point 22488 result = TimeGetRange(in->offset, in->operandB.t.size, &infoData); 22489 if(result != TPM_RC_SUCCESS) return result; 22490 // Arithmetic Comparison 22491 switch(in->operation) 22492 { 22493 case TPM_EO_EQ: 22494 // compare A = B 22495 if(CryptCompare(in->operandB.t.size, infoData, 22496 in->operandB.t.size, in->operandB.t.buffer) != 0) 22497 return TPM_RC_POLICY; 22498 break; 22499 case TPM_EO_NEQ: 22500 // compare A != B 22501 if(CryptCompare(in->operandB.t.size, infoData, 22502 22503 Family 2.0 22504 Level 00 Revision 00.99 22505 22506 Published 22507 Copyright TCG 2006-2013 22508 22509 Page 267 22510 October 31, 2013 22511 22512 Part 3: Commands 22514 53 22515 54 22516 55 22517 56 22518 57 22519 58 22520 59 22521 60 22522 61 22523 62 22524 63 22525 64 22526 65 22527 66 22528 67 22529 68 22530 69 22531 70 22532 71 22533 72 22534 73 22535 74 22536 75 22537 76 22538 77 22539 78 22540 79 22541 80 22542 81 22543 82 22544 83 22545 84 22546 85 22547 86 22548 87 22549 88 22550 89 22551 90 22552 91 22553 92 22554 93 22555 94 22556 95 22557 96 22558 97 22559 98 22560 99 22561 100 22562 101 22563 102 22564 103 22565 104 22566 105 22567 106 22568 107 22569 108 22570 109 22571 110 22572 111 22573 112 22574 113 22575 114 22576 115 22577 116 22578 22579 Trusted Platform Module Library 22580 22581 in->operandB.t.size, in->operandB.t.buffer) 22582 return TPM_RC_POLICY; 22583 break; 22584 case TPM_EO_SIGNED_GT: 22585 // compare A > B signed 22586 if(CryptCompareSigned(in->operandB.t.size, infoData, 22587 in->operandB.t.size, in->operandB.t.buffer) 22588 return TPM_RC_POLICY; 22589 break; 22590 case TPM_EO_UNSIGNED_GT: 22591 // compare A > B unsigned 22592 if(CryptCompare(in->operandB.t.size, infoData, 22593 in->operandB.t.size, in->operandB.t.buffer) 22594 return TPM_RC_POLICY; 22595 break; 22596 case TPM_EO_SIGNED_LT: 22597 // compare A < B signed 22598 if(CryptCompareSigned(in->operandB.t.size, infoData, 22599 in->operandB.t.size, in->operandB.t.buffer) 22600 return TPM_RC_POLICY; 22601 break; 22602 case TPM_EO_UNSIGNED_LT: 22603 // compare A < B unsigned 22604 if(CryptCompare(in->operandB.t.size, infoData, 22605 in->operandB.t.size, in->operandB.t.buffer) 22606 return TPM_RC_POLICY; 22607 break; 22608 case TPM_EO_SIGNED_GE: 22609 // compare A >= B signed 22610 if(CryptCompareSigned(in->operandB.t.size, infoData, 22611 in->operandB.t.size, in->operandB.t.buffer) 22612 return TPM_RC_POLICY; 22613 break; 22614 case TPM_EO_UNSIGNED_GE: 22615 // compare A >= B unsigned 22616 if(CryptCompare(in->operandB.t.size, infoData, 22617 in->operandB.t.size, in->operandB.t.buffer) 22618 return TPM_RC_POLICY; 22619 break; 22620 case TPM_EO_SIGNED_LE: 22621 // compare A <= B signed 22622 if(CryptCompareSigned(in->operandB.t.size, infoData, 22623 in->operandB.t.size, in->operandB.t.buffer) 22624 return TPM_RC_POLICY; 22625 break; 22626 case TPM_EO_UNSIGNED_LE: 22627 // compare A <= B unsigned 22628 if(CryptCompare(in->operandB.t.size, infoData, 22629 in->operandB.t.size, in->operandB.t.buffer) 22630 return TPM_RC_POLICY; 22631 break; 22632 case TPM_EO_BITSET: 22633 // All bits SET in B are SET in A. ((A&B)=B) 22634 { 22635 UINT32 i; 22636 for (i = 0; i < in->operandB.t.size; i++) 22637 if( 22638 (infoData[i] & in->operandB.t.buffer[i]) 22639 != in->operandB.t.buffer[i]) 22640 return TPM_RC_POLICY; 22641 } 22642 break; 22643 case TPM_EO_BITCLEAR: 22644 // All bits SET in B are CLEAR in A. ((A&B)=0) 22645 { 22646 22647 Page 268 22648 October 31, 2013 22649 22650 Published 22651 Copyright TCG 2006-2013 22652 22653 == 0) 22654 22655 <= 0) 22656 22657 <= 0) 22658 22659 >= 0) 22660 22661 >= 0) 22662 22663 < 0) 22664 22665 < 0) 22666 22667 > 0) 22668 22669 > 0) 22670 22671 Family 2.0 22672 Level 00 Revision 00.99 22673 22674 Trusted Platform Module Library 22676 117 22677 118 22678 119 22679 120 22680 121 22681 122 22682 123 22683 124 22684 125 22685 126 22686 127 22687 128 22688 129 22689 130 22690 131 22691 132 22692 133 22693 134 22694 135 22695 136 22696 137 22697 138 22698 139 22699 140 22700 141 22701 142 22702 143 22703 144 22704 145 22705 146 22706 147 22707 148 22708 149 22709 150 22710 151 22711 152 22712 153 22713 154 22714 155 22715 156 22716 157 22717 158 22718 159 22719 22720 Part 3: Commands 22721 22722 UINT32 i; 22723 for (i = 0; i < in->operandB.t.size; i++) 22724 if((infoData[i] & in->operandB.t.buffer[i]) != 0) 22725 return TPM_RC_POLICY; 22726 } 22727 break; 22728 default: 22729 pAssert(FALSE); 22730 break; 22731 } 22732 } 22733 // Internal Data Update 22734 // Start argument list hash 22735 argHash.t.size = CryptStartHash(session->authHashAlg, &hashState); 22736 // add operandB 22737 CryptUpdateDigest2B(&hashState, &in->operandB.b); 22738 // add offset 22739 CryptUpdateDigestInt(&hashState, sizeof(UINT16), &in->offset); 22740 // add operation 22741 CryptUpdateDigestInt(&hashState, sizeof(TPM_EO), &in->operation); 22742 // complete argument hash 22743 CryptCompleteHash2B(&hashState, &argHash.b); 22744 // update policyDigest 22745 // start hash 22746 CryptStartHash(session->authHashAlg, &hashState); 22747 // add old digest 22748 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 22749 // add commandCode 22750 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 22751 // add argument digest 22752 CryptUpdateDigest2B(&hashState, &argHash.b); 22753 // complete the digest 22754 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 22755 return TPM_RC_SUCCESS; 22756 } 22757 22758 Family 2.0 22759 Level 00 Revision 00.99 22760 22761 Published 22762 Copyright TCG 2006-2013 22763 22764 Page 269 22765 October 31, 2013 22766 22767 Part 3: Commands 22769 22770 Trusted Platform Module Library 22771 22772 25.11 TPM2_PolicyCommandCode 22773 25.11.1 22774 22775 General Description 22776 22777 This command indicates that the authorization will be limited to a specific command code. 22778 If policySessioncommandCode has its default value, then it will be set to code. If 22779 policySessioncommandCode does not have its default value, then the TPM will return 22780 TPM_RC_VALUE if the two values are not the same. 22781 If code is not implemented, the TPM will return TPM_RC_POLICY_CC. 22782 If the TPM does not return an error, it will update policySessionpolicyDigest by 22783 22784 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyCommandCode || code) 22785 22786 (26) 22787 22788 NOTE 1 22789 22790 If a previous TPM2_PolicyCommandCode() had been executed, then it is probable that the policy 22791 expression is improperly formed but the TPM does not return an error. 22792 22793 NOTE 2 22794 22795 A TPM2_PolicyOR() would be used to allow an authorization to be used for multiple commands. 22796 22797 When the policy session is used to authorize a command, the TPM will fail the command if the 22798 commandCode of that command does not match policySessioncommandCode. 22799 This command, or TPM2_PolicyDuplicationSelect(), is required to enable the policy to be used for ADMIN 22800 role authorization. 22801 EXAMPLE 22802 22803 Before TPM2_Certify() can 22804 TPM_CC_Certify is required. 22805 22806 Page 270 22807 October 31, 2013 22808 22809 be 22810 22811 executed, 22812 22813 TPM2_PolicyCommandCode() 22814 22815 Published 22816 Copyright TCG 2006-2013 22817 22818 with 22819 22820 code 22821 22822 set 22823 22824 to 22825 22826 Family 2.0 22827 Level 00 Revision 00.99 22828 22829 Trusted Platform Module Library 22831 22832 25.11.2 22833 22834 Part 3: Commands 22835 22836 Command and Response 22837 Table 129 TPM2_PolicyCommandCode Command 22838 22839 Type 22840 22841 Name 22842 22843 Description 22844 22845 TPMI_ST_COMMAND_TAG 22846 22847 tag 22848 22849 UINT32 22850 22851 commandSize 22852 22853 TPM_CC 22854 22855 commandCode 22856 22857 TPM_CC_PolicyCommandCode 22858 22859 TPMI_SH_POLICY 22860 22861 policySession 22862 22863 handle for the policy session being extended 22864 Auth Index: None 22865 22866 TPM_CC 22867 22868 code 22869 22870 the allowed commandCode 22871 22872 Table 130 TPM2_PolicyCommandCode Response 22873 Type 22874 22875 Name 22876 22877 Description 22878 22879 TPM_ST 22880 22881 tag 22882 22883 see clause 8 22884 22885 UINT32 22886 22887 responseSize 22888 22889 TPM_RC 22890 22891 responseCode 22892 22893 Family 2.0 22894 Level 00 Revision 00.99 22895 22896 Published 22897 Copyright TCG 2006-2013 22898 22899 Page 271 22900 October 31, 2013 22901 22902 Part 3: Commands 22904 22905 25.11.3 22906 1 22907 2 22908 22909 Trusted Platform Module Library 22910 22911 Detailed Actions 22912 22913 #include "InternalRoutines.h" 22914 #include "PolicyCommandCode_fp.h" 22915 Error Returns 22916 TPM_RC_VALUE 22917 22918 3 22919 4 22920 5 22921 6 22922 7 22923 8 22924 9 22925 10 22926 11 22927 12 22928 13 22929 14 22930 15 22931 16 22932 17 22933 18 22934 19 22935 20 22936 21 22937 22 22938 23 22939 24 22940 25 22941 26 22942 27 22943 28 22944 29 22945 30 22946 31 22947 32 22948 33 22949 34 22950 35 22951 36 22952 37 22953 38 22954 39 22955 40 22956 41 22957 42 22958 43 22959 44 22960 22961 Meaning 22962 commandCode of policySession previously set to a different value 22963 22964 TPM_RC 22965 TPM2_PolicyCommandCode( 22966 PolicyCommandCode_In *in 22967 22968 // IN: input parameter list 22969 22970 ) 22971 { 22972 SESSION 22973 TPM_CC 22974 HASH_STATE 22975 22976 *session; 22977 commandCode = TPM_CC_PolicyCommandCode; 22978 hashState; 22979 22980 // Input validation 22981 // Get pointer to the session structure 22982 session = SessionGet(in->policySession); 22983 if(session->commandCode != 0 && session->commandCode != in->code) 22984 return TPM_RC_VALUE + RC_PolicyCommandCode_code; 22985 if(!CommandIsImplemented(in->code)) 22986 return TPM_RC_POLICY_CC + RC_PolicyCommandCode_code; 22987 // Internal Data Update 22988 // Update policy hash 22989 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyCommandCode || code) 22990 // Start hash 22991 CryptStartHash(session->authHashAlg, &hashState); 22992 // add old digest 22993 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 22994 // add commandCode 22995 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 22996 // add input commandCode 22997 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &in->code); 22998 // complete the hash and get the results 22999 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 23000 // update commandCode value in session context 23001 session->commandCode = in->code; 23002 return TPM_RC_SUCCESS; 23003 } 23004 23005 Page 272 23006 October 31, 2013 23007 23008 Published 23009 Copyright TCG 2006-2013 23010 23011 Family 2.0 23012 Level 00 Revision 00.99 23013 23014 Trusted Platform Module Library 23016 23017 Part 3: Commands 23018 23019 25.12 TPM2_PolicyPhysicalPresence 23020 25.12.1 23021 23022 General Description 23023 23024 This command indicates that physical presence will need to be asserted at the time the authorization is 23025 performed. 23026 If this command is successful, policySessionisPPRequired will be SET to indicate that this check is 23027 required when the policy is used for authorization. Additionally, policySessionpolicyDigest is extended 23028 with 23029 23030 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyPhysicalPresence) 23031 23032 Family 2.0 23033 Level 00 Revision 00.99 23034 23035 Published 23036 Copyright TCG 2006-2013 23037 23038 (27) 23039 23040 Page 273 23041 October 31, 2013 23042 23043 Part 3: Commands 23045 23046 25.12.2 23047 23048 Trusted Platform Module Library 23049 23050 Command and Response 23051 Table 131 TPM2_PolicyPhysicalPresence Command 23052 23053 Type 23054 23055 Name 23056 23057 Description 23058 23059 TPMI_ST_COMMAND_TAG 23060 23061 tag 23062 23063 UINT32 23064 23065 commandSize 23066 23067 TPM_CC 23068 23069 commandCode 23070 23071 TPM_CC_PolicyPhysicalPresence 23072 23073 TPMI_SH_POLICY 23074 23075 policySession 23076 23077 handle for the policy session being extended 23078 Auth Index: None 23079 23080 Table 132 TPM2_PolicyPhysicalPresence Response 23081 Type 23082 23083 Name 23084 23085 Description 23086 23087 TPM_ST 23088 23089 tag 23090 23091 see clause 8 23092 23093 UINT32 23094 23095 responseSize 23096 23097 TPM_RC 23098 23099 responseCode 23100 23101 Page 274 23102 October 31, 2013 23103 23104 Published 23105 Copyright TCG 2006-2013 23106 23107 Family 2.0 23108 Level 00 Revision 00.99 23109 23110 Trusted Platform Module Library 23112 23113 25.12.3 23114 1 23115 2 23116 3 23117 4 23118 5 23119 6 23120 7 23121 8 23122 9 23123 10 23124 11 23125 12 23126 13 23127 14 23128 15 23129 16 23130 17 23131 18 23132 19 23133 20 23134 21 23135 22 23136 23 23137 24 23138 25 23139 26 23140 27 23141 28 23142 29 23143 30 23144 31 23145 32 23146 33 23147 34 23148 35 23149 23150 Part 3: Commands 23151 23152 Detailed Actions 23153 23154 #include "InternalRoutines.h" 23155 #include "PolicyPhysicalPresence_fp.h" 23156 23157 TPM_RC 23158 TPM2_PolicyPhysicalPresence( 23159 PolicyPhysicalPresence_In *in 23160 23161 // IN: input parameter list 23162 23163 ) 23164 { 23165 SESSION 23166 TPM_CC 23167 HASH_STATE 23168 23169 *session; 23170 commandCode = TPM_CC_PolicyPhysicalPresence; 23171 hashState; 23172 23173 // Internal Data Update 23174 // Get pointer to the session structure 23175 session = SessionGet(in->policySession); 23176 // Update policy hash 23177 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyPhysicalPresence) 23178 // Start hash 23179 CryptStartHash(session->authHashAlg, &hashState); 23180 // add old digest 23181 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 23182 // add commandCode 23183 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 23184 // complete the digest 23185 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 23186 // update session attribute 23187 session->attributes.isPPRequired = SET; 23188 return TPM_RC_SUCCESS; 23189 } 23190 23191 Family 2.0 23192 Level 00 Revision 00.99 23193 23194 Published 23195 Copyright TCG 2006-2013 23196 23197 Page 275 23198 October 31, 2013 23199 23200 Part 3: Commands 23202 23203 Trusted Platform Module Library 23204 23205 25.13 TPM2_PolicyCpHash 23206 25.13.1 23207 23208 General Description 23209 23210 This command is used to allow a policy to be bound to a specific command and command parameters. 23211 TPM2_PolicySigned(), TPM2_PolicySecret(), and TPM2_PolicyTIcket() are designed to allow an 23212 authorizing entity to execute an arbitrary command as the cpHashA parameter of those commands is not 23213 included in policySessionpolicyDigest. TPM2_PolicyCommandCode() allows the policy to be bound to a 23214 specific Command Code so that only certain entities may authorize specific command codes. This 23215 command allows the policy to be restricted such that an entity may only authorize a command with a 23216 specific set of parameters. 23217 If policySessioncpHash is already set and not the same as cpHashA, then the TPM shall return 23218 TPM_RC_VALUE. If cpHashA does not have the size of the policySessionpolicyDigest, the TPM shall 23219 return TPM_RC_SIZE. 23220 If the cpHashA checks succeed, policySessioncpHash 23221 policySessionpolicyDigest is updated with 23222 23223 is 23224 23225 set 23226 23227 to 23228 23229 cpHashA 23230 23231 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyCpHash || cpHashA) 23232 23233 Page 276 23234 October 31, 2013 23235 23236 Published 23237 Copyright TCG 2006-2013 23238 23239 and 23240 (28) 23241 23242 Family 2.0 23243 Level 00 Revision 00.99 23244 23245 Trusted Platform Module Library 23247 23248 25.13.2 23249 23250 Part 3: Commands 23251 23252 Command and Response 23253 Table 133 TPM2_PolicyCpHash Command 23254 23255 Type 23256 23257 Name 23258 23259 Description 23260 23261 TPMI_ST_COMMAND_TAG 23262 23263 tag 23264 23265 UINT32 23266 23267 commandSize 23268 23269 TPM_CC 23270 23271 commandCode 23272 23273 TPM_CC_PolicyCpHash 23274 23275 TPMI_SH_POLICY 23276 23277 policySession 23278 23279 handle for the policy session being extended 23280 Auth Index: None 23281 23282 TPM2B_DIGEST 23283 23284 cpHashA 23285 23286 the cpHash added to the policy 23287 23288 Table 134 TPM2_PolicyCpHash Response 23289 Type 23290 23291 Name 23292 23293 Description 23294 23295 TPM_ST 23296 23297 tag 23298 23299 see clause 8 23300 23301 UINT32 23302 23303 responseSize 23304 23305 TPM_RC 23306 23307 responseCode 23308 23309 Family 2.0 23310 Level 00 Revision 00.99 23311 23312 Published 23313 Copyright TCG 2006-2013 23314 23315 Page 277 23316 October 31, 2013 23317 23318 Part 3: Commands 23320 23321 25.13.3 23322 1 23323 2 23324 23325 Trusted Platform Module Library 23326 23327 Detailed Actions 23328 23329 #include "InternalRoutines.h" 23330 #include "PolicyCpHash_fp.h" 23331 Error Returns 23332 TPM_RC_CPHASH 23333 23334 cpHash of policySession has previously been set to a different value 23335 23336 TPM_RC_SIZE 23337 23338 3 23339 4 23340 5 23341 6 23342 7 23343 8 23344 9 23345 10 23346 11 23347 12 23348 13 23349 14 23350 15 23351 16 23352 17 23353 18 23354 19 23355 20 23356 21 23357 22 23358 23 23359 24 23360 25 23361 26 23362 27 23363 28 23364 29 23365 30 23366 31 23367 32 23368 33 23369 34 23370 35 23371 36 23372 37 23373 38 23374 39 23375 40 23376 41 23377 42 23378 43 23379 44 23380 45 23381 46 23382 47 23383 48 23384 49 23385 50 23386 51 23387 52 23388 23389 Meaning 23390 23391 cpHashA is not the size of a digest produced by the hash algorithm 23392 associated with policySession 23393 23394 TPM_RC 23395 TPM2_PolicyCpHash( 23396 PolicyCpHash_In *in 23397 23398 // IN: input parameter list 23399 23400 ) 23401 { 23402 SESSION 23403 TPM_CC 23404 HASH_STATE 23405 23406 *session; 23407 commandCode = TPM_CC_PolicyCpHash; 23408 hashState; 23409 23410 // Input Validation 23411 // Get pointer to the session structure 23412 session = SessionGet(in->policySession); 23413 // A new cpHash is given in input parameter, but cpHash in session context 23414 // is not empty, or is not the same as the new cpHash 23415 if( 23416 in->cpHashA.t.size != 0 23417 && session->u1.cpHash.t.size != 0 23418 && !Memory2BEqual(&in->cpHashA.b, &session->u1.cpHash.b) 23419 ) 23420 return TPM_RC_CPHASH; 23421 // A valid cpHash must have the same size as session hash digest 23422 if(in->cpHashA.t.size != CryptGetHashDigestSize(session->authHashAlg)) 23423 return TPM_RC_SIZE + RC_PolicyCpHash_cpHashA; 23424 // Internal Data Update 23425 // Update policy hash 23426 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyCpHash || cpHashA) 23427 // Start hash 23428 CryptStartHash(session->authHashAlg, &hashState); 23429 // add old digest 23430 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 23431 // add commandCode 23432 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 23433 // add cpHashA 23434 CryptUpdateDigest2B(&hashState, &in->cpHashA.b); 23435 // complete the digest and get the results 23436 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 23437 // update cpHash in session context 23438 session->u1.cpHash = in->cpHashA; 23439 session->attributes.iscpHashDefined = SET; 23440 return TPM_RC_SUCCESS; 23441 23442 Page 278 23443 October 31, 2013 23444 23445 Published 23446 Copyright TCG 2006-2013 23447 23448 Family 2.0 23449 Level 00 Revision 00.99 23450 23451 Trusted Platform Module Library 23453 53 23454 23455 Part 3: Commands 23456 23457 } 23458 23459 Family 2.0 23460 Level 00 Revision 00.99 23461 23462 Published 23463 Copyright TCG 2006-2013 23464 23465 Page 279 23466 October 31, 2013 23467 23468 Part 3: Commands 23470 23471 Trusted Platform Module Library 23472 23473 25.14 TPM2_PolicyNameHash 23474 25.14.1 23475 23476 General Description 23477 23478 This command allows a policy to be bound to a specific set of TPM entities without being bound to the 23479 parameters of the command. This is most useful for commands such as TPM2_Duplicate() and for 23480 TPM2_PCR_Event() when the referenced PCR requires a policy. 23481 The nameHash parameter should contain the digest of the Names associated with the handles to be used 23482 in the authorized command. 23483 EXAMPLE 23484 23485 For the TPM2_Duplicate() command, two handles are provided. One is the handle of the object 23486 being duplicated and the other is the handle of the new parent. For that command, nameHash would 23487 contain: 23488 23489 nameHash H policyAlg (objectHandleName || newParentHandleName) 23490 23491 If policySessioncpHash is already set, the TPM shall return TPM_RC_VALUE. If the size of nameHash 23492 is not the size of policySessionpolicyDigest, the TPM shall return TPM_RC_SIZE. Otherwise, 23493 policySessioncpHash is set to nameHash. 23494 If this command completes successfully, the cpHash of the authorized command will not be used for 23495 validation. Only the digest of the Names associated with the handles in the command will be used. 23496 NOTE 1 23497 23498 This allows the space normally 23499 policySessionnameHash instead. 23500 23501 used 23502 23503 to 23504 23505 hold 23506 23507 policySessioncpHash 23508 23509 to 23510 23511 be 23512 23513 used 23514 23515 for 23516 23517 The policySessionpolicyDigest will be updated with 23518 23519 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyNameHash || nameHash) 23520 NOTE 2 23521 23522 (29) 23523 23524 This command will often be used with TPM2_PolicyAuthorize() where the owner of the object being 23525 duplicated provides approval for their object to be migrated to a specific new parent. 23526 23527 Page 280 23528 October 31, 2013 23529 23530 Published 23531 Copyright TCG 2006-2013 23532 23533 Family 2.0 23534 Level 00 Revision 00.99 23535 23536 Trusted Platform Module Library 23538 23539 25.14.2 23540 23541 Part 3: Commands 23542 23543 Command and Response 23544 Table 135 TPM2_PolicyNameHash Command 23545 23546 Type 23547 23548 Name 23549 23550 Description 23551 23552 TPMI_ST_COMMAND_TAG 23553 23554 tag 23555 23556 UINT32 23557 23558 commandSize 23559 23560 TPM_CC 23561 23562 commandCode 23563 23564 TPM_CC_PolicyNameHash 23565 23566 TPMI_SH_POLICY 23567 23568 policySession 23569 23570 handle for the policy session being extended 23571 Auth Index: None 23572 23573 TPM2B_DIGEST 23574 23575 nameHash 23576 23577 the digest to be added to the policy 23578 23579 Table 136 TPM2_PolicyNameHash Response 23580 Type 23581 23582 Name 23583 23584 Description 23585 23586 TPM_ST 23587 23588 tag 23589 23590 see clause 8 23591 23592 UINT32 23593 23594 responseSize 23595 23596 TPM_RC 23597 23598 responseCode 23599 23600 Family 2.0 23601 Level 00 Revision 00.99 23602 23603 Published 23604 Copyright TCG 2006-2013 23605 23606 Page 281 23607 October 31, 2013 23608 23609 Part 3: Commands 23611 23612 25.14.3 23613 1 23614 2 23615 23616 Trusted Platform Module Library 23617 23618 Detailed Actions 23619 23620 #include "InternalRoutines.h" 23621 #include "PolicyNameHash_fp.h" 23622 Error Returns 23623 TPM_RC_CPHASH 23624 23625 nameHash has been previously set to a different value 23626 23627 TPM_RC_SIZE 23628 23629 3 23630 4 23631 5 23632 6 23633 7 23634 8 23635 9 23636 10 23637 11 23638 12 23639 13 23640 14 23641 15 23642 16 23643 17 23644 18 23645 19 23646 20 23647 21 23648 22 23649 23 23650 24 23651 25 23652 26 23653 27 23654 28 23655 29 23656 30 23657 31 23658 32 23659 33 23660 34 23661 35 23662 36 23663 37 23664 38 23665 39 23666 40 23667 41 23668 42 23669 43 23670 44 23671 45 23672 46 23673 47 23674 48 23675 49 23676 50 23677 51 23678 52 23679 23680 Meaning 23681 23682 nameHash is not the size of the digest produced by the hash 23683 algorithm associated with policySession 23684 23685 TPM_RC 23686 TPM2_PolicyNameHash( 23687 PolicyNameHash_In 23688 23689 *in 23690 23691 // IN: input parameter list 23692 23693 SESSION 23694 TPM_CC 23695 HASH_STATE 23696 23697 *session; 23698 commandCode = TPM_CC_PolicyNameHash; 23699 hashState; 23700 23701 ) 23702 { 23703 23704 // Input Validation 23705 // Get pointer to the session structure 23706 session = SessionGet(in->policySession); 23707 // A new nameHash is given in input parameter, but cpHash in session context 23708 // is not empty 23709 if(in->nameHash.t.size != 0 && session->u1.cpHash.t.size != 0) 23710 return TPM_RC_CPHASH; 23711 // A valid nameHash must have the same size as session hash digest 23712 if(in->nameHash.t.size != CryptGetHashDigestSize(session->authHashAlg)) 23713 return TPM_RC_SIZE + RC_PolicyNameHash_nameHash; 23714 // Internal Data Update 23715 // Update policy hash 23716 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyNameHash || nameHash) 23717 // Start hash 23718 CryptStartHash(session->authHashAlg, &hashState); 23719 // add old digest 23720 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 23721 // add commandCode 23722 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 23723 // add nameHash 23724 CryptUpdateDigest2B(&hashState, &in->nameHash.b); 23725 // complete the digest 23726 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 23727 // clear iscpHashDefined bit to indicate now this field contains a nameHash 23728 session->attributes.iscpHashDefined = CLEAR; 23729 // update nameHash in session context 23730 session->u1.cpHash = in->nameHash; 23731 return TPM_RC_SUCCESS; 23732 } 23733 23734 Page 282 23735 October 31, 2013 23736 23737 Published 23738 Copyright TCG 2006-2013 23739 23740 Family 2.0 23741 Level 00 Revision 00.99 23742 23743 Trusted Platform Module Library 23745 23746 Part 3: Commands 23747 23748 25.15 TPM2_PolicyDuplicationSelect 23749 25.15.1 23750 23751 General Description 23752 23753 This command allows qualification of duplication to allow duplication to a selected new parent. 23754 If this command not used in conjunction with TPM2_PolicyAuthorize(), then only the new parent is 23755 selected. 23756 EXAMPLE 23757 23758 When an object is created when the list of allowed duplication targets is known, the policy would be 23759 created with includeObject CLEAR. 23760 23761 NOTE 1 23762 23763 Only the new parent may be selected because, without TPM2_PolicyAuthorize() , the Name of the 23764 Object to be duplicated would need to be known at the time that Object's policy is created. However, 23765 since the Name of the Object includes its policy, the Name is not known. 23766 23767 If used in conjunction with TPM2_PolicyAuthorize(), then the authorizer of the new policy has the option 23768 of selecting just the new parent or of selecting both the new parent and the duplication Object.. 23769 NOTE 2 23770 23771 If the authorizing entity for an TPM2_PolicyAuthorize() only specifies the new parent, then that 23772 authorization may be applied to the duplication of any number of other Objects. If the authorizing 23773 entity specifies both a new parent and the duplicated Object, then the authorization only applies to 23774 that pairing of Object and new parent. 23775 23776 If either policySessioncpHash or policySessionnameHash has been previously set, the TPM shall 23777 return TPM_RC_CPHASH. Otherwise, policySessionnameHash will be set to: 23778 23779 nameHash HpolicyAlg(objectName || newParentName) 23780 23781 (30) 23782 23783 It is allowed that policySesionnameHash and policySessioncpHash share the same memory 23784 space. 23785 23786 NOTE 3 23787 23788 The policySessionpolicyDigest will be updated according to the setting of includeObject. If equal to 23789 YES, policySessionpolicyDigest is updated by: 23790 23791 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyDuplicationSelect || 23792 objectName || newParentName || includeObject) 23793 23794 (31) 23795 23796 If includeObject is NO, policySessionpolicyDigest is updated by: 23797 23798 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyDuplicationSelect || 23799 newParentName || includeObject) 23800 NOTE 4 23801 23802 (32) 23803 23804 PolicySessionCpHash receives the digest of both Names so that the check performed in 23805 TPM2_Duplicate() may be the same regardless of which Names are included in 23806 policySessionpolicyDigest. This means that, when TPM2_PolicyDuplicationSelect() is executed, it 23807 is only valid for a specific pair of duplication object and new parent. 23808 23809 If the command succeeds, commandCode in the policy session context is set to TPM_CC_Duplicate. 23810 NOTE 5 23811 23812 The normal use of this command is before a TPM2_PolicyAuthorize(). An authorized entity would 23813 approve a policyDigest that allowed duplication to a specific new parent. The authorizing entity may 23814 want to limit the authorization so that the approval allows only a specific object to be duplicated to 23815 the new parent. In that case, the authorizing entity would approve the policyDigest of equation (31). 23816 23817 Family 2.0 23818 Level 00 Revision 00.99 23819 23820 Published 23821 Copyright TCG 2006-2013 23822 23823 Page 283 23824 October 31, 2013 23825 23826 Part 3: Commands 23828 23829 25.15.2 23830 23831 Trusted Platform Module Library 23832 23833 Command and Response 23834 Table 137 TPM2_PolicyDuplicationSelect Command 23835 23836 Type 23837 23838 Name 23839 23840 Description 23841 23842 TPMI_ST_COMMAND_TAG 23843 23844 tag 23845 23846 UINT32 23847 23848 commandSize 23849 23850 TPM_CC 23851 23852 commandCode 23853 23854 TPM_CC_PolicyDuplicationSelect 23855 23856 TPMI_SH_POLICY 23857 23858 policySession 23859 23860 handle for the policy session being extended 23861 Auth Index: None 23862 23863 TPM2B_NAME 23864 23865 objectName 23866 23867 the Name of the object to be duplicated 23868 23869 TPM2B_NAME 23870 23871 newParentName 23872 23873 the Name of the new parent 23874 23875 TPMI_YES_NO 23876 23877 includeObject 23878 23879 if YES, the objectName will be included in the value in 23880 policySessionpolicyDigest 23881 23882 Table 138 TPM2_PolicyDuplicationSelect Response 23883 Type 23884 23885 Name 23886 23887 Description 23888 23889 TPM_ST 23890 23891 tag 23892 23893 see clause 8 23894 23895 UINT32 23896 23897 responseSize 23898 23899 TPM_RC 23900 23901 responseCode 23902 23903 Page 284 23904 October 31, 2013 23905 23906 Published 23907 Copyright TCG 2006-2013 23908 23909 Family 2.0 23910 Level 00 Revision 00.99 23911 23912 Trusted Platform Module Library 23914 23915 25.15.3 23916 1 23917 2 23918 23919 Part 3: Commands 23920 23921 Detailed Actions 23922 23923 #include "InternalRoutines.h" 23924 #include "PolicyDuplicationSelect_fp.h" 23925 Error Returns 23926 TPM_RC_COMMAND_CODE 23927 23928 commandCode of 'policySession; is not empty 23929 23930 TPM_RC_CPHASH 23931 3 23932 4 23933 5 23934 6 23935 7 23936 8 23937 9 23938 10 23939 11 23940 12 23941 13 23942 14 23943 15 23944 16 23945 17 23946 18 23947 19 23948 20 23949 21 23950 22 23951 23 23952 24 23953 25 23954 26 23955 27 23956 28 23957 29 23958 30 23959 31 23960 32 23961 33 23962 34 23963 35 23964 36 23965 37 23966 38 23967 39 23968 40 23969 41 23970 42 23971 43 23972 44 23973 45 23974 46 23975 47 23976 48 23977 49 23978 50 23979 51 23980 52 23981 53 23982 23983 Meaning 23984 23985 cpHash of policySession is not empty 23986 23987 TPM_RC 23988 TPM2_PolicyDuplicationSelect( 23989 PolicyDuplicationSelect_In *in 23990 23991 // IN: input parameter list 23992 23993 ) 23994 { 23995 SESSION 23996 HASH_STATE 23997 TPM_CC 23998 23999 *session; 24000 hashState; 24001 commandCode = TPM_CC_PolicyDuplicationSelect; 24002 24003 // Input Validation 24004 // Get pointer to the session structure 24005 session = SessionGet(in->policySession); 24006 // cpHash in session context must be empty 24007 if(session->u1.cpHash.t.size != 0) 24008 return TPM_RC_CPHASH; 24009 // commandCode in session context must be empty 24010 if(session->commandCode != 0) 24011 return TPM_RC_COMMAND_CODE; 24012 // Internal Data Update 24013 // Update name hash 24014 session->u1.cpHash.t.size = CryptStartHash(session->authHashAlg, &hashState); 24015 // add objectName 24016 CryptUpdateDigest2B(&hashState, &in->objectName.b); 24017 // add new parent name 24018 CryptUpdateDigest2B(&hashState, &in->newParentName.b); 24019 // complete hash 24020 CryptCompleteHash2B(&hashState, &session->u1.cpHash.b); 24021 // update policy hash 24022 // Old policyDigest size should be the same as the new policyDigest size since 24023 // they are using the same hash algorithm 24024 session->u2.policyDigest.t.size 24025 = CryptStartHash(session->authHashAlg, &hashState); 24026 // add old policy 24027 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 24028 // add command code 24029 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 24030 // add objectName 24031 if(in->includeObject == YES) 24032 CryptUpdateDigest2B(&hashState, &in->objectName.b); 24033 24034 Family 2.0 24035 Level 00 Revision 00.99 24036 24037 Published 24038 Copyright TCG 2006-2013 24039 24040 Page 285 24041 October 31, 2013 24042 24043 Part 3: Commands 24045 54 24046 55 24047 56 24048 57 24049 58 24050 59 24051 60 24052 61 24053 62 24054 63 24055 64 24056 65 24057 66 24058 67 24059 68 24060 69 24061 70 24062 71 24063 24064 Trusted Platform Module Library 24065 24066 // add new parent name 24067 CryptUpdateDigest2B(&hashState, &in->newParentName.b); 24068 // add includeObject 24069 CryptUpdateDigestInt(&hashState, sizeof(TPMI_YES_NO), &in->includeObject); 24070 // complete digest 24071 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 24072 // clear iscpHashDefined bit to indicate now this field contains a nameHash 24073 session->attributes.iscpHashDefined = CLEAR; 24074 // set commandCode in session context 24075 session->commandCode = TPM_CC_Duplicate; 24076 return TPM_RC_SUCCESS; 24077 } 24078 24079 Page 286 24080 October 31, 2013 24081 24082 Published 24083 Copyright TCG 2006-2013 24084 24085 Family 2.0 24086 Level 00 Revision 00.99 24087 24088 Trusted Platform Module Library 24090 24091 Part 3: Commands 24092 24093 25.16 TPM2_PolicyAuthorize 24094 25.16.1 24095 24096 General Description 24097 24098 This command allows policies to change. If a policy were static, then it would be difficult to add users to a 24099 policy. This command lets a policy authority sign a new policy so that it may be used in an existing policy. 24100 The authorizing entity signs a structure that contains 24101 24102 aHash HaHashAlg(approvedPolicy || policyRef) 24103 24104 (33) 24105 24106 The aHashAlg is required to be the nameAlg of the key used to sign the aHash. The aHash value is then 24107 signed (symmetric or asymmetric) by keySign. That signature is then checked by the TPM in 24108 TPM2_VerifySignature() which produces a ticket by 24109 24110 HMAC(proof, (TPM_ST_VERIFIED || aHash || keySignName)) 24111 NOTE 24112 24113 (34) 24114 24115 The reason for the validation is because of the expectation that the policy will be used multiple times 24116 and it is more efficient to check a ticket than to load an object each time to chec k a signature. 24117 24118 The ticket is then used in TPM2_PolicyAuthorize() to validate the parameters. 24119 The keySign parameter is required to be a valid object name using nameAlg other than TPM_ALG_NULL. 24120 If the first two octets of keySign are not a valid hash algorithm, the TPM shall return TPM_RC_HASH. If 24121 the remainder of the Name is not the size of the indicated digest, the TPM shall return TPM_RC_SIZE. 24122 The TPM validates that the approvedPolicy matches the current value of policySessionpolicyDigest and 24123 if not, shall return TPM_RC_VALUE. 24124 The TPM then validates that the parameters to TPM2_PolicyAuthorize() match the values used to 24125 generate the ticket. If so, the TPM will reset policySessionpolicyDigest to a Zero Digest. Then it will 24126 create a TPM2B_NAME (keyName) using keySign and update policySessionpolicyDigest with 24127 PolicyUpdate() (see 25.2.3). 24128 24129 PolicyUpdate(TPM_CC_PolicyAuthorize, keyName, policyRef) 24130 24131 (35) 24132 24133 If the ticket is not valid, the TPM shall return TPM_RC_POLICY. 24134 If policySession is a trial session, policySessionpolicyDigest is extended as if the ticket is valid without 24135 actual verification. 24136 NOTE 24137 24138 The unmarshaling process requires that a proper TPMT_TK_VERIFIED be provided for checkTicket 24139 but it may be a NULL Ticket. 24140 24141 Family 2.0 24142 Level 00 Revision 00.99 24143 24144 Published 24145 Copyright TCG 2006-2013 24146 24147 Page 287 24148 October 31, 2013 24149 24150 Part 3: Commands 24152 24153 25.16.2 24154 24155 Trusted Platform Module Library 24156 24157 Command and Response 24158 Table 139 TPM2_PolicyAuthorize Command 24159 24160 Type 24161 24162 Name 24163 24164 Description 24165 24166 TPMI_ST_COMMAND_TAG 24167 24168 tag 24169 24170 UINT32 24171 24172 commandSize 24173 24174 TPM_CC 24175 24176 commandCode 24177 24178 TPM_CC_PolicyAuthorize 24179 24180 TPMI_SH_POLICY 24181 24182 policySession 24183 24184 handle for the policy session being extended 24185 Auth Index: None 24186 24187 TPM2B_DIGEST 24188 24189 approvedPolicy 24190 24191 digest of the policy being approved 24192 24193 TPM2B_NONCE 24194 24195 policyRef 24196 24197 a policy qualifier 24198 24199 TPM2B_NAME 24200 24201 keySign 24202 24203 Name of a key that can sign a policy addition 24204 24205 TPMT_TK_VERIFIED 24206 24207 checkTicket 24208 24209 ticket validating that approvedPolicy and policyRef were 24210 signed by keySign 24211 24212 Table 140 TPM2_PolicyAuthorize Response 24213 Type 24214 24215 Name 24216 24217 Description 24218 24219 TPM_ST 24220 24221 tag 24222 24223 see clause 8 24224 24225 UINT32 24226 24227 responseSize 24228 24229 TPM_RC 24230 24231 responseCode 24232 24233 Page 288 24234 October 31, 2013 24235 24236 Published 24237 Copyright TCG 2006-2013 24238 24239 Family 2.0 24240 Level 00 Revision 00.99 24241 24242 Trusted Platform Module Library 24244 24245 25.16.3 24246 1 24247 2 24248 3 24249 24250 Part 3: Commands 24251 24252 Detailed Actions 24253 24254 #include "InternalRoutines.h" 24255 #include "PolicyAuthorize_fp.h" 24256 #include "Policy_spt_fp.h" 24257 Error Returns 24258 TPM_RC_HASH 24259 24260 hash algorithm in keyName is not supported 24261 24262 TPM_RC_SIZE 24263 24264 keyName is not the correct size for its hash algorithm 24265 24266 TPM_RC_VALUE 24267 24268 4 24269 5 24270 6 24271 7 24272 8 24273 9 24274 10 24275 11 24276 12 24277 13 24278 14 24279 15 24280 16 24281 17 24282 18 24283 19 24284 20 24285 21 24286 22 24287 23 24288 24 24289 25 24290 26 24291 27 24292 28 24293 29 24294 30 24295 31 24296 32 24297 33 24298 34 24299 35 24300 36 24301 37 24302 38 24303 39 24304 40 24305 41 24306 42 24307 43 24308 44 24309 45 24310 46 24311 47 24312 48 24313 49 24314 50 24315 24316 Meaning 24317 24318 the current policyDigest of policySession does not match 24319 approvedPolicy; or checkTicket doesn't match the provided values 24320 24321 TPM_RC 24322 TPM2_PolicyAuthorize( 24323 PolicyAuthorize_In 24324 24325 *in 24326 24327 // IN: input parameter list 24328 24329 SESSION 24330 TPM2B_DIGEST 24331 HASH_STATE 24332 TPMT_TK_VERIFIED 24333 TPM_ALG_ID 24334 UINT16 24335 24336 *session; 24337 authHash; 24338 hashState; 24339 ticket; 24340 hashAlg; 24341 digestSize; 24342 24343 ) 24344 { 24345 24346 // Input Validation 24347 // Get pointer to the session structure 24348 session = SessionGet(in->policySession); 24349 // Extract from the Name of the key, the algorithm used to compute it's Name 24350 hashAlg = BYTE_ARRAY_TO_UINT16(in->keySign.t.name); 24351 // 'keySign' parameter needs to use a supported hash algorithm, otherwise 24352 // can't tell how large the digest should be 24353 digestSize = CryptGetHashDigestSize(hashAlg); 24354 if(digestSize == 0) 24355 return TPM_RC_HASH + RC_PolicyAuthorize_keySign; 24356 if(digestSize != (in->keySign.t.size - 2)) 24357 return TPM_RC_SIZE + RC_PolicyAuthorize_keySign; 24358 //If this is a trial policy, skip all validations 24359 if(session->attributes.isTrialPolicy == CLEAR) 24360 { 24361 // Check that "approvedPolicy" matches the current value of the 24362 // policyDigest in policy session 24363 if(!Memory2BEqual(&session->u2.policyDigest.b, 24364 &in->approvedPolicy.b)) 24365 return TPM_RC_VALUE + RC_PolicyAuthorize_approvedPolicy; 24366 // Validate ticket TPMT_TK_VERIFIED 24367 // Compute aHash. The authorizing object sign a digest 24368 // aHash := hash(approvedPolicy || policyRef). 24369 // Start hash 24370 authHash.t.size = CryptStartHash(hashAlg, &hashState); 24371 // add approvedPolicy 24372 CryptUpdateDigest2B(&hashState, &in->approvedPolicy.b); 24373 24374 Family 2.0 24375 Level 00 Revision 00.99 24376 24377 Published 24378 Copyright TCG 2006-2013 24379 24380 Page 289 24381 October 31, 2013 24382 24383 Part 3: Commands 24385 51 24386 52 24387 53 24388 54 24389 55 24390 56 24391 57 24392 58 24393 59 24394 60 24395 61 24396 62 24397 63 24398 64 24399 65 24400 66 24401 67 24402 68 24403 69 24404 70 24405 71 24406 72 24407 73 24408 74 24409 75 24410 76 24411 77 24412 78 24413 24414 Trusted Platform Module Library 24415 24416 // add policyRef 24417 CryptUpdateDigest2B(&hashState, &in->policyRef.b); 24418 // complete hash 24419 CryptCompleteHash2B(&hashState, &authHash.b); 24420 // re-compute TPMT_TK_VERIFIED 24421 TicketComputeVerified(in->checkTicket.hierarchy, &authHash, 24422 &in->keySign, &ticket); 24423 // Compare ticket digest. If not match, return error 24424 if(!Memory2BEqual(&in->checkTicket.digest.b, &ticket.digest.b)) 24425 return TPM_RC_VALUE+ RC_PolicyAuthorize_checkTicket; 24426 } 24427 // Internal Data Update 24428 // Set policyDigest to zero digest 24429 MemorySet(session->u2.policyDigest.t.buffer, 0, 24430 session->u2.policyDigest.t.size); 24431 // Update policyDigest 24432 PolicyContextUpdate(TPM_CC_PolicyAuthorize, &in->keySign, &in->policyRef, 24433 NULL, 0, session); 24434 return TPM_RC_SUCCESS; 24435 } 24436 24437 Page 290 24438 October 31, 2013 24439 24440 Published 24441 Copyright TCG 2006-2013 24442 24443 Family 2.0 24444 Level 00 Revision 00.99 24445 24446 Trusted Platform Module Library 24448 24449 Part 3: Commands 24450 24451 25.17 TPM2_PolicyAuthValue 24452 25.17.1 24453 24454 General Description 24455 24456 This command allows a policy to be bound to the authorization value of the authorized object. 24457 When this command completes successfully, policySessionisAuthValueNeeded is SET to indicate that 24458 the authValue will be included in hmacKey when the authorization HMAC is computed for this session. 24459 Additionally, policySessionisPasswordNeeded will be CLEAR. 24460 NOTE 24461 24462 If a policy does not use this command, then the hmacKey for the authorized command would only 24463 use sessionKey. If sessionKey is not present, then the hmacKey is an Empty Buffer and no HMAC 24464 would be computed. 24465 24466 If successful, policySessionpolicyDigest will be updated with 24467 24468 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyAuthValue) 24469 24470 Family 2.0 24471 Level 00 Revision 00.99 24472 24473 Published 24474 Copyright TCG 2006-2013 24475 24476 (36) 24477 24478 Page 291 24479 October 31, 2013 24480 24481 Part 3: Commands 24483 24484 25.17.2 24485 24486 Trusted Platform Module Library 24487 24488 Command and Response 24489 Table 141 TPM2_PolicyAuthValue Command 24490 24491 Type 24492 24493 Name 24494 24495 Description 24496 24497 TPMI_ST_COMMAND_TAG 24498 24499 tag 24500 24501 UINT32 24502 24503 commandSize 24504 24505 TPM_CC 24506 24507 commandCode 24508 24509 TPM_CC_PolicyAuthValue 24510 24511 TPMI_SH_POLICY 24512 24513 policySession 24514 24515 handle for the policy session being extended 24516 Auth Index: None 24517 24518 Table 142 TPM2_PolicyAuthValue Response 24519 Type 24520 24521 Name 24522 24523 Description 24524 24525 TPM_ST 24526 24527 tag 24528 24529 see clause 8 24530 24531 UINT32 24532 24533 responseSize 24534 24535 TPM_RC 24536 24537 responseCode 24538 24539 Page 292 24540 October 31, 2013 24541 24542 Published 24543 Copyright TCG 2006-2013 24544 24545 Family 2.0 24546 Level 00 Revision 00.99 24547 24548 Trusted Platform Module Library 24550 24551 25.17.3 24552 1 24553 2 24554 3 24555 4 24556 5 24557 6 24558 7 24559 8 24560 9 24561 10 24562 11 24563 12 24564 13 24565 14 24566 15 24567 16 24568 17 24569 18 24570 19 24571 20 24572 21 24573 22 24574 23 24575 24 24576 25 24577 26 24578 27 24579 28 24580 29 24581 30 24582 31 24583 32 24584 33 24585 34 24586 35 24587 36 24588 37 24589 24590 Part 3: Commands 24591 24592 Detailed Actions 24593 24594 #include "InternalRoutines.h" 24595 #include "PolicyAuthValue_fp.h" 24596 #include "Policy_spt_fp.h" 24597 24598 TPM_RC 24599 TPM2_PolicyAuthValue( 24600 PolicyAuthValue_In 24601 24602 *in 24603 24604 // IN: input parameter list 24605 24606 SESSION 24607 TPM_CC 24608 HASH_STATE 24609 24610 *session; 24611 commandCode = TPM_CC_PolicyAuthValue; 24612 hashState; 24613 24614 ) 24615 { 24616 24617 // Internal Data Update 24618 // Get pointer to the session structure 24619 session = SessionGet(in->policySession); 24620 // Update policy hash 24621 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyAuthValue) 24622 // 24623 Start hash 24624 CryptStartHash(session->authHashAlg, &hashState); 24625 // add old digest 24626 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 24627 // add commandCode 24628 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 24629 // complete the hash and get the results 24630 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 24631 // update isAuthValueNeeded bit in the session context 24632 session->attributes.isAuthValueNeeded = SET; 24633 session->attributes.isPasswordNeeded = CLEAR; 24634 return TPM_RC_SUCCESS; 24635 } 24636 24637 Family 2.0 24638 Level 00 Revision 00.99 24639 24640 Published 24641 Copyright TCG 2006-2013 24642 24643 Page 293 24644 October 31, 2013 24645 24646 Part 3: Commands 24648 24649 Trusted Platform Module Library 24650 24651 25.18 TPM2_PolicyPassword 24652 25.18.1 24653 24654 General Description 24655 24656 This command allows a policy to be bound to the authorization value of the authorized object. 24657 When this command completes successfully, policySessionisPasswordNeeded is SET to indicate that 24658 authValue of the authorized object will be checked when the session is used for authorization. The caller 24659 will provide the authValue in clear text in the hmac parameter of the authorization. The comparison of 24660 hmac to authValue is performed as if the authorization is a password. 24661 NOTE 1 24662 24663 The parameter field in the policy session where the authorization value is provided is called hmac. If 24664 TPM2_PolicyPassword() is part of the sequence, then the field will contain a password and not an 24665 HMAC. 24666 24667 If successful, policySessionpolicyDigest will be updated with 24668 24669 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyAuthValue) 24670 NOTE 2 24671 24672 (37) 24673 24674 This is the same extend value as used with TPM2_PolicyAuthValue so that the evaluation may be 24675 done using either an HMAC or a password with no change to the authPolicy of the object. The 24676 reason that two commands are present is to indicate to the TPM if the hmac field in the authorization 24677 will contain an HMAC or a password value. 24678 24679 When this command is successful, policySessionisAuthValueNeeded will be CLEAR. 24680 24681 Page 294 24682 October 31, 2013 24683 24684 Published 24685 Copyright TCG 2006-2013 24686 24687 Family 2.0 24688 Level 00 Revision 00.99 24689 24690 Trusted Platform Module Library 24692 24693 25.18.2 24694 24695 Part 3: Commands 24696 24697 Command and Response 24698 Table 143 TPM2_PolicyPassword Command 24699 24700 Type 24701 24702 Name 24703 24704 Description 24705 24706 TPMI_ST_COMMAND_TAG 24707 24708 tag 24709 24710 UINT32 24711 24712 commandSize 24713 24714 TPM_CC 24715 24716 commandCode 24717 24718 TPM_CC_PolicyPassword 24719 24720 TPMI_SH_POLICY 24721 24722 policySession 24723 24724 handle for the policy session being extended 24725 Auth Index: None 24726 24727 Table 144 TPM2_PolicyPassword Response 24728 Type 24729 24730 Name 24731 24732 Description 24733 24734 TPM_ST 24735 24736 tag 24737 24738 see clause 8 24739 24740 UINT32 24741 24742 responseSize 24743 24744 TPM_RC 24745 24746 responseCode 24747 24748 Family 2.0 24749 Level 00 Revision 00.99 24750 24751 Published 24752 Copyright TCG 2006-2013 24753 24754 Page 295 24755 October 31, 2013 24756 24757 Part 3: Commands 24759 24760 25.18.3 24761 1 24762 2 24763 3 24764 4 24765 5 24766 6 24767 7 24768 8 24769 9 24770 10 24771 11 24772 12 24773 13 24774 14 24775 15 24776 16 24777 17 24778 18 24779 19 24780 20 24781 21 24782 22 24783 23 24784 24 24785 25 24786 26 24787 27 24788 28 24789 29 24790 30 24791 31 24792 32 24793 33 24794 34 24795 35 24796 36 24797 37 24798 24799 Trusted Platform Module Library 24800 24801 Detailed Actions 24802 24803 #include "InternalRoutines.h" 24804 #include "PolicyPassword_fp.h" 24805 #include "Policy_spt_fp.h" 24806 24807 TPM_RC 24808 TPM2_PolicyPassword( 24809 PolicyPassword_In 24810 24811 *in 24812 24813 // IN: input parameter list 24814 24815 SESSION 24816 TPM_CC 24817 HASH_STATE 24818 24819 *session; 24820 commandCode = TPM_CC_PolicyAuthValue; 24821 hashState; 24822 24823 ) 24824 { 24825 24826 // Internal Data Update 24827 // Get pointer to the session structure 24828 session = SessionGet(in->policySession); 24829 // Update policy hash 24830 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyAuthValue) 24831 // Start hash 24832 CryptStartHash(session->authHashAlg, &hashState); 24833 // add old digest 24834 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 24835 // add commandCode 24836 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 24837 // complete the digest 24838 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 24839 // Update isPasswordNeeded bit 24840 session->attributes.isPasswordNeeded = SET; 24841 session->attributes.isAuthValueNeeded = CLEAR; 24842 return TPM_RC_SUCCESS; 24843 } 24844 24845 Page 296 24846 October 31, 2013 24847 24848 Published 24849 Copyright TCG 2006-2013 24850 24851 Family 2.0 24852 Level 00 Revision 00.99 24853 24854 Trusted Platform Module Library 24856 24857 Part 3: Commands 24858 24859 25.19 TPM2_PolicyGetDigest 24860 25.19.1 24861 24862 General Description 24863 24864 This command returns the current policyDigest of the session. This command allows the TPM to be used 24865 to perform the actions required to pre-compute the authPolicy for an object. 24866 24867 Family 2.0 24868 Level 00 Revision 00.99 24869 24870 Published 24871 Copyright TCG 2006-2013 24872 24873 Page 297 24874 October 31, 2013 24875 24876 Part 3: Commands 24878 24879 25.19.2 24880 24881 Trusted Platform Module Library 24882 24883 Command and Response 24884 Table 145 TPM2_PolicyGetDigest Command 24885 24886 Type 24887 24888 Name 24889 24890 Description 24891 24892 TPMI_ST_COMMAND_TAG 24893 24894 tag 24895 24896 UINT32 24897 24898 commandSize 24899 24900 TPM_CC 24901 24902 commandCode 24903 24904 TPM_CC_PolicyGetDigest 24905 24906 TPMI_SH_POLICY 24907 24908 policySession 24909 24910 handle for the policy session 24911 Auth Index: None 24912 24913 Table 146 TPM2_PolicyGetDigest Response 24914 Type 24915 24916 Name 24917 24918 Description 24919 24920 TPM_ST 24921 24922 tag 24923 24924 see clause 8 24925 24926 UINT32 24927 24928 responseSize 24929 24930 TPM_RC 24931 24932 responseCode 24933 24934 TPM2B_DIGEST 24935 24936 policyDigest 24937 24938 Page 298 24939 October 31, 2013 24940 24941 the current value of the policySessionpolicyDigest 24942 24943 Published 24944 Copyright TCG 2006-2013 24945 24946 Family 2.0 24947 Level 00 Revision 00.99 24948 24949 Trusted Platform Module Library 24951 24952 25.19.3 24953 1 24954 2 24955 3 24956 4 24957 5 24958 6 24959 7 24960 8 24961 9 24962 10 24963 11 24964 12 24965 13 24966 14 24967 15 24968 16 24969 17 24970 18 24971 19 24972 24973 Part 3: Commands 24974 24975 Detailed Actions 24976 24977 #include "InternalRoutines.h" 24978 #include "PolicyGetDigest_fp.h" 24979 24980 TPM_RC 24981 TPM2_PolicyGetDigest( 24982 PolicyGetDigest_In 24983 PolicyGetDigest_Out 24984 24985 *in, 24986 *out 24987 24988 // IN: input parameter list 24989 // OUT: output parameter list 24990 24991 ) 24992 { 24993 SESSION 24994 24995 *session; 24996 24997 // Command Output 24998 // Get pointer to the session structure 24999 session = SessionGet(in->policySession); 25000 out->policyDigest = session->u2.policyDigest; 25001 return TPM_RC_SUCCESS; 25002 } 25003 25004 Family 2.0 25005 Level 00 Revision 00.99 25006 25007 Published 25008 Copyright TCG 2006-2013 25009 25010 Page 299 25011 October 31, 2013 25012 25013 Part 3: Commands 25015 25016 Trusted Platform Module Library 25017 25018 25.20 TPM2_PolicyNvWritten 25019 25.20.1 25020 25021 General Description 25022 25023 This command allows a policy to be bound to the TPMA_NV_WRITTEN attributes. This is a deferred 25024 assertion. Values are stored in the policy session context and checked when the policy is used for 25025 authorization. 25026 If policySessioncheckNVWritten is CLEAR, it is SET and policySessionnvWrittenState is set to 25027 writtenSet. 25028 If policySessioncheckNVWritten is SET, the TPM will return TPM_RC_VALUE if 25029 policySessionnvWrittenState and writtenSet are not the same. 25030 If the TPM does not return and error, it will update policySessionpolicyDigest by 25031 25032 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyNvWritten || writtenSet) 25033 25034 (38) 25035 25036 When the policy session is used to authorize a command, the TPM will fail the command if 25037 policySessioncheckNVWritten is SET and nvIndexattributesTPMA_NV_WRITTEN does not match 25038 policySessionnvWrittenState. 25039 NOTE 25040 25041 A typical use case is a simple policy for the first write during manufacturing provisioning that would 25042 require TPMA_NV_WRITTEN CLEAR and a more complex policy for later use that would require 25043 TPMA_NV_WRITTEN SET. 25044 25045 Page 300 25046 October 31, 2013 25047 25048 Published 25049 Copyright TCG 2006-2013 25050 25051 Family 2.0 25052 Level 00 Revision 00.99 25053 25054 Trusted Platform Module Library 25056 25057 25.20.2 25058 25059 Part 3: Commands 25060 25061 Command and Response 25062 Table 147 TPM2_PolicyNvWritten Command 25063 25064 Type 25065 25066 Name 25067 25068 Description 25069 25070 TPMI_ST_COMMAND_TAG 25071 25072 Tag 25073 25074 UINT32 25075 25076 commandSize 25077 25078 TPM_CC 25079 25080 commandCode 25081 25082 TPM_CC_PolicyNVWritten 25083 25084 TPMI_SH_POLICY 25085 25086 policySession 25087 25088 handle for the policy session being extended 25089 Auth Index: None 25090 25091 TPMI_YES_NO 25092 25093 writtenSet 25094 25095 YES if NV Index is required to have been written 25096 NO if NV Index is required not to have been written 25097 25098 Table 148 TPM2_PolicyNvWritten Response 25099 Type 25100 25101 Name 25102 25103 Description 25104 25105 TPM_ST 25106 25107 Tag 25108 25109 see clause 8 25110 25111 UINT32 25112 25113 responseSize 25114 25115 TPM_RC 25116 25117 responseCode 25118 25119 Family 2.0 25120 Level 00 Revision 00.99 25121 25122 Published 25123 Copyright TCG 2006-2013 25124 25125 Page 301 25126 October 31, 2013 25127 25128 Part 3: Commands 25130 25131 25.20.3 25132 1 25133 2 25134 25135 Trusted Platform Module Library 25136 25137 Detailed Actions 25138 25139 #include "InternalRoutines.h" 25140 #include "PolicyNvWritten_fp.h" 25141 25142 Make an NV Index policy dependent on the state of the TPMA_NV_WRITTEN attribute of the index. 25143 Error Returns 25144 TPM_RC_VALUE 25145 3 25146 4 25147 5 25148 6 25149 7 25150 8 25151 9 25152 10 25153 11 25154 12 25155 13 25156 14 25157 15 25158 16 25159 17 25160 18 25161 19 25162 20 25163 21 25164 22 25165 23 25166 24 25167 25 25168 26 25169 27 25170 28 25171 29 25172 30 25173 31 25174 32 25175 33 25176 34 25177 35 25178 36 25179 37 25180 38 25181 39 25182 40 25183 41 25184 42 25185 43 25186 44 25187 45 25188 46 25189 47 25190 48 25191 49 25192 50 25193 51 25194 52 25195 25196 Meaning 25197 a conflicting request for the attribute has already been processed 25198 25199 TPM_RC 25200 TPM2_PolicyNvWritten( 25201 PolicyNvWritten_In 25202 25203 *in 25204 25205 // IN: input parameter list 25206 25207 ) 25208 { 25209 SESSION 25210 TPM_CC 25211 HASH_STATE 25212 25213 *session; 25214 commandCode = TPM_CC_PolicyNvWritten; 25215 hashState; 25216 25217 // Input Validation 25218 // Get pointer to the session structure 25219 session = SessionGet(in->policySession); 25220 // If already set is this a duplicate (the same setting)? If it 25221 // is a conflicting setting, it is an error 25222 if(session->attributes.checkNvWritten == SET) 25223 { 25224 if(( 25225 (session->attributes.nvWrittenState == SET) 25226 != (in->writtenSet == YES))) 25227 return TPM_RC_VALUE + RC_PolicyNvWritten_writtenSet; 25228 } 25229 // Internal Data Update 25230 // Set session attributes so that the NV Index needs to be checked 25231 session->attributes.checkNvWritten = SET; 25232 session->attributes.nvWrittenState = (in->writtenSet == YES); 25233 // Update policy hash 25234 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyNvWritten 25235 // 25236 || writtenSet) 25237 // Start hash 25238 CryptStartHash(session->authHashAlg, &hashState); 25239 // add old digest 25240 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 25241 // add commandCode 25242 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 25243 // add the byte of writtenState 25244 CryptUpdateDigestInt(&hashState, sizeof(TPMI_YES_NO), &in->writtenSet); 25245 // complete the digest 25246 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 25247 return TPM_RC_SUCCESS; 25248 } 25249 25250 Page 302 25251 October 31, 2013 25252 25253 Published 25254 Copyright TCG 2006-2013 25255 25256 Family 2.0 25257 Level 00 Revision 00.99 25258 25259 Trusted Platform Module Library 25261 25262 Family 2.0 25263 Level 00 Revision 00.99 25264 25265 Part 3: Commands 25266 25267 Published 25268 Copyright TCG 2006-2013 25269 25270 Page 303 25271 October 31, 2013 25272 25273 Part 3: Commands 25275 25276 26 25277 25278 Trusted Platform Module Library 25279 25280 Hierarchy Commands 25281 25282 26.1 25283 25284 TPM2_CreatePrimary 25285 25286 26.1.1 General Description 25287 This command is used to create a Primary Object under one of the Primary Seeds or a Temporary Object 25288 under TPM_RH_NULL. The command uses a TPM2B_PUBLIC as a template for the object to be created. 25289 The command will create and load a Primary Object. The sensitive area is not returned. 25290 NOTE: 25291 25292 Since the sensitive data is not returned, the key cannot be reloaded. 25293 persistent or it can be recreated. 25294 25295 It can either be made 25296 25297 Any type of object and attributes combination that is allowed by TPM2_Create() may be created by this 25298 command. The constraints on templates and parameters are the same as TPM2_Create() except that a 25299 Primary Storage Key and a Temporary Storage Key are not constrained to use the algorithms of their 25300 parents. 25301 For setting of the attributes of the created object, fixedParent, fixedTPM, userWithAuth, adminWithPolicy, 25302 encrypt, and restricted are implied to be SET in the parent (a Permanent Handle). The remaining 25303 attributes are implied to be CLEAR. 25304 The TPM will derive the object from the Primary Seed indicated in primaryHandle using an approved 25305 KDF. All of the bits of the template are used in the creation of the Primary Key. Methods for creating a 25306 Primary Object from a Primary Seed are described in Part 1 of this specification and implemented in Part 25307 4. 25308 If this command is called multiple times with the same inPublic parameter, inSensitive.data, and Primary 25309 Seed, the TPM shall produce the same Primary Object. 25310 NOTE 25311 25312 If the Primary Seed is changed, the Primary Objects generated with the new seed shall be 25313 statistically unique even if the parameters of the call are the same. 25314 25315 This command requires authorization. Authorization for a Primary Object attached to the Platform Primary 25316 Seed (PPS) shall be provided by platformAuth or platformPolicy. Authorization for a Primary Object 25317 attached to the Storage Primary Seed (SPS) shall be provided by ownerAuth or ownerPolicy. 25318 Authorization for a Primary Key attached to the Endorsement Primary Seed (EPS) shall be provided by 25319 endorsementAuth or endorsementPolicy. 25320 25321 Page 304 25322 October 31, 2013 25323 25324 Published 25325 Copyright TCG 2006-2013 25326 25327 Family 2.0 25328 Level 00 Revision 00.99 25329 25330 Trusted Platform Module Library 25332 25333 Part 3: Commands 25334 25335 26.1.2 Command and Response 25336 Table 149 TPM2_CreatePrimary Command 25337 Type 25338 25339 Name 25340 25341 Description 25342 25343 TPMI_ST_COMMAND_TAG 25344 25345 tag 25346 25347 UINT32 25348 25349 commandSize 25350 25351 TPM_CC 25352 25353 commandCode 25354 25355 TPM_CC_CreatePrimary 25356 25357 TPMI_RH_HIERARCHY+ 25358 25359 @primaryHandle 25360 25361 TPM_RH_ENDORSEMENT, TPM_RH_OWNER, 25362 TPM_RH_PLATFORM+{PP}, or TPM_RH_NULL 25363 Auth Index: 1 25364 Auth Role: USER 25365 25366 TPM2B_SENSITIVE_CREATE 25367 25368 inSensitive 25369 25370 the sensitive data, see Part 1 Sensitive Values 25371 25372 TPM2B_PUBLIC 25373 25374 inPublic 25375 25376 the public template 25377 25378 TPM2B_DATA 25379 25380 outsideInfo 25381 25382 data that will be included in the creation data for this 25383 object to provide permanent, verifiable linkage between 25384 this object and some object owner data 25385 25386 TPML_PCR_SELECTION 25387 25388 creationPCR 25389 25390 PCR that will be used in creation data 25391 25392 Table 150 TPM2_CreatePrimary Response 25393 Type 25394 25395 Name 25396 25397 Description 25398 25399 TPM_ST 25400 25401 tag 25402 25403 see clause 8 25404 25405 UINT32 25406 25407 responseSize 25408 25409 TPM_RC 25410 25411 responseCode 25412 25413 TPM_HANDLE 25414 25415 objectHandle 25416 25417 Handle for created Primary Object 25418 25419 TPM2B_PUBLIC 25420 25421 outPublic 25422 25423 the public portion of the created object 25424 25425 TPM2B_CREATION_DATA 25426 25427 creationData 25428 25429 contains a TPMT_CREATION_DATA 25430 25431 TPM2B_DIGEST 25432 25433 creationHash 25434 25435 digest of creationData using nameAlg of outPublic 25436 25437 TPMT_TK_CREATION 25438 25439 creationTicket 25440 25441 ticket used by TPM2_CertifyCreation() to validate that 25442 the creation data was produced by the TPM 25443 25444 TPM2B_NAME 25445 25446 name 25447 25448 the name of the created object 25449 25450 Family 2.0 25451 Level 00 Revision 00.99 25452 25453 Published 25454 Copyright TCG 2006-2013 25455 25456 Page 305 25457 October 31, 2013 25458 25459 Part 3: Commands 25461 25462 Trusted Platform Module Library 25463 25464 26.1.3 Detailed Actions 25465 1 25466 2 25467 3 25468 4 25469 25470 #include 25471 #include 25472 #include 25473 #include 25474 25475 "InternalRoutines.h" 25476 "CreatePrimary_fp.h" 25477 "Object_spt_fp.h" 25478 <Platform.h> 25479 25480 Error Returns 25481 TPM_RC_ATTRIBUTES 25482 25483 sensitiveDataOrigin is CLEAR when 'sensitive. data' is an Empty 25484 Buffer, or is SET when 'sensitive. data' is not empty; fixedTPM, 25485 fixedParent, or encryptedDuplication attributes are inconsistent 25486 between themselves or with those of the parent object; inconsistent 25487 restricted, decrypt and sign attributes; attempt to inject sensitive data 25488 for an asymmetric key; attempt to create a symmetric cipher key that 25489 is not a decryption key 25490 25491 TPM_RC_KDF 25492 25493 incorrect KDF specified for decrypting keyed hash object 25494 25495 TPM_RC_OBJECT_MEMORY 25496 25497 there is no free slot for the object 25498 25499 TPM_RC_SCHEME 25500 25501 inconsistent attributes decrypt, sign, restricted and key's scheme ID; 25502 or hash algorithm is inconsistent with the scheme ID for keyed hash 25503 object 25504 25505 TPM_RC_SIZE 25506 25507 size of public auth policy or sensitive auth value does not match 25508 digest size of the name algorithm sensitive data size for the keyed 25509 hash object is larger than is allowed for the scheme 25510 25511 TPM_RC_SYMMETRIC 25512 25513 a storage key with no symmetric algorithm specified; or non-storage 25514 key with symmetric algorithm different from TPM_ALG_NULL 25515 25516 TPM_RC_TYPE 25517 5 25518 6 25519 7 25520 8 25521 9 25522 10 25523 11 25524 12 25525 13 25526 14 25527 15 25528 16 25529 17 25530 18 25531 19 25532 20 25533 21 25534 22 25535 23 25536 24 25537 25 25538 26 25539 27 25540 28 25541 29 25542 30 25543 31 25544 32 25545 33 25546 25547 Meaning 25548 25549 unknown object type; 25550 25551 TPM_RC 25552 TPM2_CreatePrimary( 25553 CreatePrimary_In 25554 CreatePrimary_Out 25555 ) 25556 { 25557 // Local variables 25558 TPM_RC 25559 TPMT_SENSITIVE 25560 25561 *in, 25562 *out 25563 25564 // IN: input parameter list 25565 // OUT: output parameter list 25566 25567 result = TPM_RC_SUCCESS; 25568 sensitive; 25569 25570 // Input Validation 25571 // The sensitiveDataOrigin attribute must be consistent with the setting of 25572 // the size of the data object in inSensitive. 25573 if( 25574 (in->inPublic.t.publicArea.objectAttributes.sensitiveDataOrigin == SET) 25575 != (in->inSensitive.t.sensitive.data.t.size == 0 )) 25576 // Mismatch between the object attributes and the parameter. 25577 return TPM_RC_ATTRIBUTES + RC_CreatePrimary_inSensitive; 25578 // Check attributes in input public area. TPM_RC_ATTRIBUTES, TPM_RC_KDF, 25579 // TPM_RC_SCHEME, TPM_RC_SIZE, TPM_RC_SYMMETRIC, or TPM_RC_TYPE error may 25580 // be returned at this point. 25581 result = PublicAttributesValidation(FALSE, in->primaryHandle, 25582 &in->inPublic.t.publicArea); 25583 if(result != TPM_RC_SUCCESS) 25584 return RcSafeAddToResult(result, RC_CreatePrimary_inPublic); 25585 // Validate the sensitive area values 25586 if( MemoryRemoveTrailingZeros(&in->inSensitive.t.sensitive.userAuth) 25587 > CryptGetHashDigestSize(in->inPublic.t.publicArea.nameAlg)) 25588 25589 Page 306 25590 October 31, 2013 25591 25592 Published 25593 Copyright TCG 2006-2013 25594 25595 Family 2.0 25596 Level 00 Revision 00.99 25597 25598 Trusted Platform Module Library 25600 34 25601 35 25602 36 25603 37 25604 38 25605 39 25606 40 25607 41 25608 42 25609 43 25610 44 25611 45 25612 46 25613 47 25614 48 25615 49 25616 50 25617 51 25618 52 25619 53 25620 54 25621 55 25622 56 25623 57 25624 58 25625 59 25626 60 25627 61 25628 62 25629 63 25630 64 25631 65 25632 66 25633 67 25634 68 25635 69 25636 25637 Part 3: Commands 25638 25639 return TPM_RC_SIZE + RC_CreatePrimary_inSensitive; 25640 // Command output 25641 // Generate Primary Object 25642 // The primary key generation process uses the Name of the input public 25643 // template to compute the key. The keys are generated from the template 25644 // before anything in the template is allowed to be changed. 25645 // A TPM_RC_KDF, TPM_RC_SIZE error may be returned at this point 25646 result = CryptCreateObject(in->primaryHandle, &in->inPublic.t.publicArea, 25647 &in->inSensitive.t.sensitive,&sensitive); 25648 if(result != TPM_RC_SUCCESS) 25649 return result; 25650 // Fill in creation data 25651 FillInCreationData(in->primaryHandle, in->inPublic.t.publicArea.nameAlg, 25652 &in->creationPCR, &in->outsideInfo, &out->creationData, 25653 &out->creationHash); 25654 // Copy public area 25655 out->outPublic = in->inPublic; 25656 // Fill in private area for output 25657 ObjectComputeName(&(out->outPublic.t.publicArea), &out->name); 25658 // Compute creation ticket 25659 TicketComputeCreation(EntityGetHierarchy(in->primaryHandle), &out->name, 25660 &out->creationHash, &out->creationTicket); 25661 // Create a internal object. A TPM_RC_OBJECT_MEMORY error may be returned 25662 // at this point. 25663 result = ObjectLoad(in->primaryHandle, &in->inPublic.t.publicArea, &sensitive, 25664 &out->name, in->primaryHandle, TRUE, &out->objectHandle); 25665 return result; 25666 } 25667 25668 Family 2.0 25669 Level 00 Revision 00.99 25670 25671 Published 25672 Copyright TCG 2006-2013 25673 25674 Page 307 25675 October 31, 2013 25676 25677 Part 3: Commands 25679 25680 26.2 25681 25682 Trusted Platform Module Library 25683 25684 TPM2_HierarchyControl 25685 25686 26.2.1 General Description 25687 This command enables and disables use of a hierarchy and its associated NV storage. The command 25688 allows phEnable, phEnableNV, shEnable, and ehEnable to be changed when the proper authorization is 25689 provided. 25690 This command may be used to CLEAR phEnable and phEnableNV if platformAuth/platformPolicy is 25691 provided. phEnable may not be SET using this command. 25692 This command may be used to CLEAR shEnable if either platformAuth/platformPolicy 25693 ownerAuth/ownerPolicy is provided. shEnable may be SET if platformAuth/platformPolicy is provided. 25694 25695 or 25696 25697 This command may be used to CLEAR ehEnable if either platformAuth/platformPolicy or 25698 endorsementAuth/endorsementPolicy is provided. ehEnable may be SET if platformAuth/platformPolicy is 25699 provided. 25700 When this command is used to CLEAR phEnable, shEnable, or ehEnable, the TPM will disable use of 25701 any persistent entity associated with the disabled hierarchy and will flush any transient objects associated 25702 with the disabled hierarchy. 25703 When this command is used to CLEAR shEnable, the TPM will disable access to any NV index that has 25704 TPMA_NV_PLATFORMCREATE CLEAR (indicating that the NV Index was defined using ownerAuth). As 25705 long as shEnable is CLEAR, the TPM will return an error in response to any command that attempts to 25706 operate upon an NV index that has TPMA_NV_PLATFORMCREATE CLEAR. 25707 When this command is used to CLEAR phEnableNV, the TPM will disable access to any NV index that 25708 has TPMA_NV_PLATFORMCREATE SET (indicating that the NV Index was defined using platformAuth). 25709 As long as phEnableNV is CLEAR, the TPM will return an error in response to any command that 25710 attempts to operate upon an NV index that has TPMA_NV_PLATFORMCREATE SET. 25711 25712 Page 308 25713 October 31, 2013 25714 25715 Published 25716 Copyright TCG 2006-2013 25717 25718 Family 2.0 25719 Level 00 Revision 00.99 25720 25721 Trusted Platform Module Library 25723 25724 Part 3: Commands 25725 25726 26.2.2 Command and Response 25727 Table 151 TPM2_HierarchyControl Command 25728 Type 25729 25730 Name 25731 25732 Description 25733 25734 TPMI_ST_COMMAND_TAG 25735 25736 tag 25737 25738 UINT32 25739 25740 commandSize 25741 25742 TPM_CC 25743 25744 commandCode 25745 25746 TPM_CC_HierarchyControl {NV E} 25747 25748 TPMI_RH_HIERARCHY 25749 25750 @authHandle 25751 25752 TPM_RH_ENDORSEMENT, TPM_RH_OWNER or 25753 TPM_RH_PLATFORM+{PP} 25754 Auth Index: 1 25755 Auth Role: USER 25756 25757 TPMI_RH_ENABLES 25758 25759 enable 25760 25761 the enable being modified 25762 TPM_RH_ENDORSEMENT, TPM_RH_OWNER, 25763 TPM_RH_PLATFORM, or TPM_RH_PLATFORM_NV 25764 25765 TPMI_YES_NO 25766 25767 state 25768 25769 YES if the enable should be SET, NO if the enable 25770 should be CLEAR 25771 25772 Table 152 TPM2_HierarchyControl Response 25773 Type 25774 25775 Name 25776 25777 Description 25778 25779 TPM_ST 25780 25781 tag 25782 25783 see clause 8 25784 25785 UINT32 25786 25787 responseSize 25788 25789 TPM_RC 25790 25791 responseCode 25792 25793 Family 2.0 25794 Level 00 Revision 00.99 25795 25796 Published 25797 Copyright TCG 2006-2013 25798 25799 Page 309 25800 October 31, 2013 25801 25802 Part 3: Commands 25804 25805 Trusted Platform Module Library 25806 25807 26.2.3 Detailed Actions 25808 1 25809 2 25810 25811 #include "InternalRoutines.h" 25812 #include "HierarchyControl_fp.h" 25813 Error Returns 25814 TPM_RC_AUTH_TYPE 25815 25816 3 25817 4 25818 5 25819 6 25820 7 25821 8 25822 9 25823 10 25824 11 25825 12 25826 13 25827 14 25828 15 25829 16 25830 17 25831 18 25832 19 25833 20 25834 21 25835 22 25836 23 25837 24 25838 25 25839 26 25840 27 25841 28 25842 29 25843 30 25844 31 25845 32 25846 33 25847 34 25848 35 25849 36 25850 37 25851 38 25852 39 25853 40 25854 41 25855 42 25856 43 25857 44 25858 45 25859 46 25860 47 25861 48 25862 49 25863 50 25864 51 25865 52 25866 53 25867 54 25868 25869 Meaning 25870 authHandle is not applicable to hierarchy in its current state 25871 25872 TPM_RC 25873 TPM2_HierarchyControl( 25874 HierarchyControl_In 25875 25876 *in 25877 25878 // IN: input parameter list 25879 25880 ) 25881 { 25882 TPM_RC 25883 BOOL 25884 BOOL 25885 25886 result; 25887 select = (in->state == YES); 25888 *selected = NULL; 25889 25890 // Input Validation 25891 switch(in->enable) 25892 { 25893 // Platform hierarchy has to be disabled by platform auth 25894 // If the platform hierarchy has already been disabled, only a reboot 25895 // can enable it again 25896 case TPM_RH_PLATFORM: 25897 case TPM_RH_PLATFORM_NV: 25898 if(in->authHandle != TPM_RH_PLATFORM) 25899 return TPM_RC_AUTH_TYPE; 25900 break; 25901 // ShEnable may be disabled if PlatformAuth/PlatformPolicy or 25902 // OwnerAuth/OwnerPolicy is provided. If ShEnable is disabled, then it 25903 // may only be enabled if PlatformAuth/PlatformPolicy is provided. 25904 case TPM_RH_OWNER: 25905 if( 25906 in->authHandle != TPM_RH_PLATFORM 25907 && in->authHandle != TPM_RH_OWNER) 25908 return TPM_RC_AUTH_TYPE; 25909 if( 25910 gc.shEnable == FALSE && in->state == YES 25911 && in->authHandle != TPM_RH_PLATFORM) 25912 return TPM_RC_AUTH_TYPE; 25913 break; 25914 // EhEnable may be disabled if either PlatformAuth/PlatformPolicy or 25915 // EndosementAuth/EndorsementPolicy is provided. If EhEnable is disabled, 25916 // then it may only be enabled if PlatformAuth/PlatformPolicy is 25917 // provided. 25918 case TPM_RH_ENDORSEMENT: 25919 if( 25920 in->authHandle != TPM_RH_PLATFORM 25921 && in->authHandle != TPM_RH_ENDORSEMENT) 25922 return TPM_RC_AUTH_TYPE; 25923 if( 25924 gc.ehEnable == FALSE && in->state == YES 25925 && in->authHandle != TPM_RH_PLATFORM) 25926 return TPM_RC_AUTH_TYPE; 25927 break; 25928 default: 25929 pAssert(FALSE); 25930 break; 25931 } 25932 // Internal Data Update 25933 25934 Page 310 25935 October 31, 2013 25936 25937 Published 25938 Copyright TCG 2006-2013 25939 25940 Family 2.0 25941 Level 00 Revision 00.99 25942 25943 Trusted Platform Module Library 25945 55 25946 56 25947 57 25948 58 25949 59 25950 60 25951 61 25952 62 25953 63 25954 64 25955 65 25956 66 25957 67 25958 68 25959 69 25960 70 25961 71 25962 72 25963 73 25964 74 25965 75 25966 76 25967 77 25968 78 25969 79 25970 80 25971 81 25972 82 25973 83 25974 84 25975 85 25976 86 25977 87 25978 88 25979 89 25980 90 25981 91 25982 92 25983 93 25984 94 25985 95 25986 96 25987 97 25988 98 25989 99 25990 100 25991 101 25992 102 25993 103 25994 104 25995 105 25996 106 25997 107 25998 25999 Part 3: Commands 26000 26001 // Enable or disable the selected hierarchy 26002 // Note: the authorization processing for this command may keep these 26003 // command actions from being executed. For example, if phEnable is 26004 // CLEAR, then platformAuth cannot be used for authorization. This 26005 // means that would not be possible to use platformAuth to change the 26006 // state of phEnable from CLEAR to SET. 26007 // If it is decided that platformPolicy can still be used when phEnable 26008 // is CLEAR, then this code could SET phEnable when proper platform 26009 // policy is provided. 26010 switch(in->enable) 26011 { 26012 case TPM_RH_OWNER: 26013 selected = &gc.shEnable; 26014 break; 26015 case TPM_RH_ENDORSEMENT: 26016 selected = &gc.ehEnable; 26017 break; 26018 case TPM_RH_PLATFORM: 26019 selected = &g_phEnable; 26020 break; 26021 case TPM_RH_PLATFORM_NV: 26022 selected = &gc.phEnableNV; 26023 break; 26024 default: 26025 pAssert(FALSE); 26026 break; 26027 } 26028 if(selected != NULL && *selected != select) 26029 { 26030 // Before changing the internal state, make sure that NV is available. 26031 // Only need to update NV if changing the orderly state 26032 if(gp.orderlyState != SHUTDOWN_NONE) 26033 { 26034 // The command needs NV update. Check if NV is available. 26035 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 26036 // this point 26037 result = NvIsAvailable(); 26038 if(result != TPM_RC_SUCCESS) 26039 return result; 26040 } 26041 // state is changing and NV is available so modify 26042 *selected = select; 26043 // If a hierarchy was just disabled, flush it 26044 if(select == CLEAR && in->enable != TPM_RH_PLATFORM_NV) 26045 // Flush hierarchy 26046 ObjectFlushHierarchy(in->enable); 26047 // orderly state should be cleared because of the update to state clear data 26048 // This gets processed in ExecuteCommand() on the way out. 26049 g_clearOrderly = TRUE; 26050 } 26051 return TPM_RC_SUCCESS; 26052 } 26053 26054 Family 2.0 26055 Level 00 Revision 00.99 26056 26057 Published 26058 Copyright TCG 2006-2013 26059 26060 Page 311 26061 October 31, 2013 26062 26063 Part 3: Commands 26065 26066 26.3 26067 26068 Trusted Platform Module Library 26069 26070 TPM2_SetPrimaryPolicy 26071 26072 26.3.1 General Description 26073 This command allows setting of the authorization policy for the platform hierarchy (platformPolicy), the 26074 storage hierarchy (ownerPolicy), and the endorsement hierarchy (endorsementPolicy). 26075 The command requires an authorization session. The session shall use the current authValue or satisfy 26076 the current authPolicy for the referenced hierarchy. 26077 The policy that is changed is the policy associated with authHandle. 26078 If the enable associated with authHandle is not SET, then the associated authorization values (authValue 26079 or authPolicy) may not be used. 26080 26081 Page 312 26082 October 31, 2013 26083 26084 Published 26085 Copyright TCG 2006-2013 26086 26087 Family 2.0 26088 Level 00 Revision 00.99 26089 26090 Trusted Platform Module Library 26092 26093 Part 3: Commands 26094 26095 26.3.2 Command and Response 26096 Table 153 TPM2_SetPrimaryPolicy Command 26097 Type 26098 26099 Name 26100 26101 Description 26102 26103 TPMI_ST_COMMAND_TAG 26104 26105 tag 26106 26107 UINT32 26108 26109 commandSize 26110 26111 TPM_CC 26112 26113 commandCode 26114 26115 TPM_CC_SetPrimaryPolicy {NV} 26116 26117 TPMI_RH_HIERARCHY 26118 26119 @authHandle 26120 26121 TPM_RH_ENDORSEMENT, TPM_RH_OWNER or 26122 TPM_RH_PLATFORM+{PP} 26123 Auth Index: 1 26124 Auth Role: USER 26125 26126 TPM2B_DIGEST 26127 26128 authPolicy 26129 26130 an authorization policy digest; may be the Empty Buffer 26131 If hashAlg is TPM_ALG_NULL, then this shall be an 26132 Empty Buffer. 26133 26134 TPMI_ALG_HASH+ 26135 26136 hashAlg 26137 26138 the hash algorithm to use for the policy 26139 If the authPolicy is an Empty Buffer, then this field shall 26140 be TPM_ALG_NULL. 26141 26142 Table 154 TPM2_SetPrimaryPolicy Response 26143 Type 26144 26145 Name 26146 26147 Description 26148 26149 TPM_ST 26150 26151 tag 26152 26153 see clause 8 26154 26155 UINT32 26156 26157 responseSize 26158 26159 TPM_RC 26160 26161 responseCode 26162 26163 Family 2.0 26164 Level 00 Revision 00.99 26165 26166 Published 26167 Copyright TCG 2006-2013 26168 26169 Page 313 26170 October 31, 2013 26171 26172 Part 3: Commands 26174 26175 Trusted Platform Module Library 26176 26177 26.3.3 Detailed Actions 26178 1 26179 2 26180 26181 #include "InternalRoutines.h" 26182 #include "SetPrimaryPolicy_fp.h" 26183 Error Returns 26184 TPM_RC_SIZE 26185 26186 3 26187 4 26188 5 26189 6 26190 7 26191 8 26192 9 26193 10 26194 11 26195 12 26196 13 26197 14 26198 15 26199 16 26200 17 26201 18 26202 19 26203 20 26204 21 26205 22 26206 23 26207 24 26208 25 26209 26 26210 27 26211 28 26212 29 26213 30 26214 31 26215 32 26216 33 26217 34 26218 35 26219 36 26220 37 26221 38 26222 39 26223 40 26224 41 26225 42 26226 43 26227 44 26228 45 26229 46 26230 47 26231 48 26232 49 26233 50 26234 51 26235 52 26236 53 26237 54 26238 26239 Meaning 26240 size of input authPolicy is not consistent with input hash algorithm 26241 26242 TPM_RC 26243 TPM2_SetPrimaryPolicy( 26244 SetPrimaryPolicy_In 26245 26246 *in 26247 26248 // IN: input parameter list 26249 26250 ) 26251 { 26252 TPM_RC 26253 26254 result; 26255 26256 // Input Validation 26257 // Check the authPolicy consistent with hash algorithm 26258 if( 26259 in->authPolicy.t.size != 0 26260 && in->authPolicy.t.size != CryptGetHashDigestSize(in->hashAlg)) 26261 return TPM_RC_SIZE + RC_SetPrimaryPolicy_authPolicy; 26262 // The command need NV update for OWNER and ENDORSEMENT hierarchy, and 26263 // might need orderlyState update for PLATFROM hierarchy. 26264 // Check if NV is available. A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE 26265 // error may be returned at this point 26266 result = NvIsAvailable(); 26267 if(result != TPM_RC_SUCCESS) 26268 return result; 26269 // Internal Data Update 26270 // Set hierarchy policy 26271 switch(in->authHandle) 26272 { 26273 case TPM_RH_OWNER: 26274 gp.ownerAlg = in->hashAlg; 26275 gp.ownerPolicy = in->authPolicy; 26276 NvWriteReserved(NV_OWNER_ALG, &gp.ownerAlg); 26277 NvWriteReserved(NV_OWNER_POLICY, &gp.ownerPolicy); 26278 break; 26279 case TPM_RH_ENDORSEMENT: 26280 gp.endorsementAlg = in->hashAlg; 26281 gp.endorsementPolicy = in->authPolicy; 26282 NvWriteReserved(NV_ENDORSEMENT_ALG, &gp.endorsementAlg); 26283 NvWriteReserved(NV_ENDORSEMENT_POLICY, &gp.endorsementPolicy); 26284 break; 26285 case TPM_RH_PLATFORM: 26286 gc.platformAlg = in->hashAlg; 26287 gc.platformPolicy = in->authPolicy; 26288 // need to update orderly state 26289 g_clearOrderly = TRUE; 26290 break; 26291 default: 26292 pAssert(FALSE); 26293 break; 26294 } 26295 return TPM_RC_SUCCESS; 26296 } 26297 26298 Page 314 26299 October 31, 2013 26300 26301 Published 26302 Copyright TCG 2006-2013 26303 26304 Family 2.0 26305 Level 00 Revision 00.99 26306 26307 Trusted Platform Module Library 26309 26310 26.4 26311 26312 Part 3: Commands 26313 26314 TPM2_ChangePPS 26315 26316 26.4.1 General Description 26317 This replaces the current PPS with a value from the RNG and sets platformPolicy to the default 26318 initialization value (the Empty Buffer). 26319 NOTE 1 26320 26321 A policy that is the Empty Buffer can match no policy. 26322 26323 NOTE 2 26324 26325 platformAuth is not changed. 26326 26327 All loaded transient and persistent objects in the Platform hierarchy are flushed. 26328 Saved contexts in the Platform hierarchy that were created under the old PPS will no longer be able to be 26329 loaded. 26330 The policy hash algorithm for PCR is reset to TPM_ALG_NULL. 26331 This command does not clear any NV Index values. 26332 NOTE 3 26333 26334 Index values belonging to the Platform are preserved because the indexes may have configuration 26335 information that will be the same after the PPS changes. The Platform may remove the indexes that 26336 are no longer needed using TPM2_NV_UndefineSpace(). 26337 26338 This command requires platformAuth. 26339 26340 Family 2.0 26341 Level 00 Revision 00.99 26342 26343 Published 26344 Copyright TCG 2006-2013 26345 26346 Page 315 26347 October 31, 2013 26348 26349 Part 3: Commands 26351 26352 Trusted Platform Module Library 26353 26354 26.4.2 Command and Response 26355 Table 155 TPM2_ChangePPS Command 26356 Type 26357 26358 Name 26359 26360 TPMI_ST_COMMAND_TAG 26361 26362 tag 26363 26364 UINT32 26365 26366 commandSize 26367 26368 TPM_CC 26369 26370 commandCode 26371 26372 TPM_CC_ChangePPS {NV E} 26373 26374 @authHandle 26375 26376 TPM_RH_PLATFORM+{PP} 26377 Auth Index: 1 26378 Auth Role: USER 26379 26380 TPMI_RH_PLATFORM 26381 26382 Description 26383 26384 Table 156 TPM2_ChangePPS Response 26385 Type 26386 26387 Name 26388 26389 Description 26390 26391 TPM_ST 26392 26393 tag 26394 26395 see clause 8 26396 26397 UINT32 26398 26399 responseSize 26400 26401 TPM_RC 26402 26403 responseCode 26404 26405 Page 316 26406 October 31, 2013 26407 26408 Published 26409 Copyright TCG 2006-2013 26410 26411 Family 2.0 26412 Level 00 Revision 00.99 26413 26414 Trusted Platform Module Library 26416 26417 Part 3: Commands 26418 26419 26.4.3 Detailed Actions 26420 1 26421 2 26422 3 26423 4 26424 5 26425 6 26426 7 26427 8 26428 9 26429 10 26430 11 26431 12 26432 13 26433 14 26434 15 26435 16 26436 17 26437 18 26438 19 26439 20 26440 21 26441 22 26442 23 26443 24 26444 25 26445 26 26446 27 26447 28 26448 29 26449 30 26450 31 26451 32 26452 33 26453 34 26454 35 26455 36 26456 37 26457 38 26458 39 26459 40 26460 41 26461 42 26462 43 26463 44 26464 45 26465 46 26466 47 26467 48 26468 49 26469 50 26470 51 26471 52 26472 53 26473 54 26474 26475 #include "InternalRoutines.h" 26476 #include "ChangePPS_fp.h" 26477 26478 TPM_RC 26479 TPM2_ChangePPS( 26480 ChangePPS_In 26481 26482 *in 26483 26484 // IN: input parameter list 26485 26486 ) 26487 { 26488 UINT32 26489 TPM_RC 26490 26491 i; 26492 result; 26493 26494 // Check if NV is available. A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE 26495 // error may be returned at this point 26496 result = NvIsAvailable(); 26497 if(result != TPM_RC_SUCCESS) return result; 26498 // Input parameter is not reference in command action 26499 in = NULL; 26500 // Internal Data Update 26501 // Reset platform hierarchy seed from RNG 26502 CryptGenerateRandom(PRIMARY_SEED_SIZE, gp.PPSeed.t.buffer); 26503 // Create a new phProof value from RNG to prevent the saved platform 26504 // hierarchy contexts being loaded 26505 CryptGenerateRandom(PROOF_SIZE, gp.phProof.t.buffer); 26506 // Set platform authPolicy to null 26507 gc.platformAlg = TPM_ALG_NULL; 26508 gc.platformPolicy.t.size = 0; 26509 // Flush loaded object in platform hierarchy 26510 ObjectFlushHierarchy(TPM_RH_PLATFORM); 26511 // Flush platform evict object and index in NV 26512 NvFlushHierarchy(TPM_RH_PLATFORM); 26513 // Save hierarchy changes to NV 26514 NvWriteReserved(NV_PP_SEED, &gp.PPSeed); 26515 NvWriteReserved(NV_PH_PROOF, &gp.phProof); 26516 // Re-initialize PCR policies 26517 for(i = 0; i < NUM_POLICY_PCR_GROUP; i++) 26518 { 26519 gp.pcrPolicies.hashAlg[i] = TPM_ALG_NULL; 26520 gp.pcrPolicies.policy[i].t.size = 0; 26521 } 26522 NvWriteReserved(NV_PCR_POLICIES, &gp.pcrPolicies); 26523 // orderly state should be cleared because of the update to state clear data 26524 g_clearOrderly = TRUE; 26525 return TPM_RC_SUCCESS; 26526 } 26527 26528 Family 2.0 26529 Level 00 Revision 00.99 26530 26531 Published 26532 Copyright TCG 2006-2013 26533 26534 Page 317 26535 October 31, 2013 26536 26537 Part 3: Commands 26539 26540 26.5 26541 26542 Trusted Platform Module Library 26543 26544 TPM2_ChangeEPS 26545 26546 26.5.1 General Description 26547 This replaces the current EPS with a value from the RNG and sets the Endorsement hierarchy controls to 26548 their default initialization values: ehEnable is SET, endorsementAuth and endorsementPolicy both equal 26549 to the Empty Buffer. It will flush any loaded objects in the EPS hierarchy and not allow objects in the 26550 hierarchy associated with the previous EPS to be loaded. 26551 NOTE 26552 26553 In the reference implementation, ehProof is a non-volatile value from the RNG. It is allowed that the 26554 ehProof be generated by a KDF using both the EPS and SPS as inputs. If generated with a KDF, the 26555 ehProof can be generated on an as-needed basis or made a non-volatile value. 26556 26557 This command requires platformAuth. 26558 26559 Page 318 26560 October 31, 2013 26561 26562 Published 26563 Copyright TCG 2006-2013 26564 26565 Family 2.0 26566 Level 00 Revision 00.99 26567 26568 Trusted Platform Module Library 26570 26571 Part 3: Commands 26572 26573 26.5.2 Command and Response 26574 Table 157 TPM2_ChangeEPS Command 26575 Type 26576 26577 Name 26578 26579 TPMI_ST_COMMAND_TAG 26580 26581 tag 26582 26583 UINT32 26584 26585 commandSize 26586 26587 TPM_CC 26588 26589 commandCode 26590 26591 TPM_CC_ChangeEPS {NV E} 26592 26593 @authHandle 26594 26595 TPM_RH_PLATFORM+{PP} 26596 Auth Handle: 1 26597 Auth Role: USER 26598 26599 TPMI_RH_PLATFORM 26600 26601 Description 26602 26603 Table 158 TPM2_ChangeEPS Response 26604 Type 26605 26606 Name 26607 26608 Description 26609 26610 TPM_ST 26611 26612 tag 26613 26614 see clause 8 26615 26616 UINT32 26617 26618 responseSize 26619 26620 TPM_RC 26621 26622 responseCode 26623 26624 Family 2.0 26625 Level 00 Revision 00.99 26626 26627 Published 26628 Copyright TCG 2006-2013 26629 26630 Page 319 26631 October 31, 2013 26632 26633 Part 3: Commands 26635 26636 Trusted Platform Module Library 26637 26638 26.5.3 Detailed Actions 26639 1 26640 2 26641 3 26642 4 26643 5 26644 6 26645 7 26646 8 26647 9 26648 10 26649 11 26650 12 26651 13 26652 14 26653 15 26654 16 26655 17 26656 18 26657 19 26658 20 26659 21 26660 22 26661 23 26662 24 26663 25 26664 26 26665 27 26666 28 26667 29 26668 30 26669 31 26670 32 26671 33 26672 34 26673 35 26674 36 26675 37 26676 38 26677 39 26678 40 26679 41 26680 42 26681 43 26682 44 26683 45 26684 46 26685 47 26686 48 26687 49 26688 50 26689 51 26690 52 26691 53 26692 54 26693 55 26694 56 26695 26696 #include "InternalRoutines.h" 26697 #include "ChangeEPS_fp.h" 26698 26699 TPM_RC 26700 TPM2_ChangeEPS( 26701 ChangeEPS_In 26702 26703 *in 26704 26705 // IN: input parameter list 26706 26707 ) 26708 { 26709 TPM_RC 26710 26711 result; 26712 26713 // The command needs NV update. Check if NV is available. 26714 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 26715 // this point 26716 result = NvIsAvailable(); 26717 if(result != TPM_RC_SUCCESS) return result; 26718 // Input parameter is not reference in command action 26719 in = NULL; 26720 // Internal Data Update 26721 // Reset endorsement hierarchy seed from RNG 26722 CryptGenerateRandom(PRIMARY_SEED_SIZE, gp.EPSeed.t.buffer); 26723 // Create new ehProof value from RNG 26724 CryptGenerateRandom(PROOF_SIZE, gp.ehProof.t.buffer); 26725 // Enable endorsement hierarchy 26726 gc.ehEnable = TRUE; 26727 // set authValue buffer to zeros 26728 MemorySet(gp.endorsementAuth.t.buffer, 0, gp.endorsementAuth.t.size); 26729 // Set endorsement authValue to null 26730 gp.endorsementAuth.t.size = 0; 26731 // Set endorsement authPolicy to null 26732 gp.endorsementAlg = TPM_ALG_NULL; 26733 gp.endorsementPolicy.t.size = 0; 26734 // Flush loaded object in endorsement hierarchy 26735 ObjectFlushHierarchy(TPM_RH_ENDORSEMENT); 26736 // Flush evict object of endorsement hierarchy stored in NV 26737 NvFlushHierarchy(TPM_RH_ENDORSEMENT); 26738 // Save hierarchy changes to NV 26739 NvWriteReserved(NV_EP_SEED, &gp.EPSeed); 26740 NvWriteReserved(NV_EH_PROOF, &gp.ehProof); 26741 NvWriteReserved(NV_ENDORSEMENT_AUTH, &gp.endorsementAuth); 26742 NvWriteReserved(NV_ENDORSEMENT_ALG, &gp.endorsementAlg); 26743 NvWriteReserved(NV_ENDORSEMENT_POLICY, &gp.endorsementPolicy); 26744 // orderly state should be cleared because of the update to state clear data 26745 g_clearOrderly = TRUE; 26746 return TPM_RC_SUCCESS; 26747 } 26748 26749 Page 320 26750 October 31, 2013 26751 26752 Published 26753 Copyright TCG 2006-2013 26754 26755 Family 2.0 26756 Level 00 Revision 00.99 26757 26758 Trusted Platform Module Library 26760 26761 26.6 26762 26763 Part 3: Commands 26764 26765 TPM2_Clear 26766 26767 26.6.1 General Description 26768 This command removes all TPM context associated with a specific Owner. 26769 The clear operation will: 26770 26771 26772 flush loaded objects (persistent and volatile) in the Storage and Endorsement hierarchies; 26773 26774 26775 26776 delete any NV Index with TPMA_NV_PLATFORMCREATE == CLEAR; 26777 26778 26779 26780 change the SPS to a new value from the TPMs random number generator (RNG), 26781 26782 26783 26784 change shProof and ehProof, 26785 NOTE 26786 26787 The proof values may be set from the RNG or derived from the associated new Primary Seed. If 26788 derived from the Primary Seeds, the derivation of ehProof shall use both the SPS and EPS. The 26789 computation shall use the SPS as an HMAC key and the derived value may then be a parameter 26790 in a second HMAC in which the EPS is the HMAC key. The reference design uses values from 26791 the RNG. 26792 26793 26794 26795 SET shEnable and ehEnable; 26796 26797 26798 26799 set ownerAuth, endorsementAuth, and lockoutAuth to the Empty Buffer; 26800 26801 26802 26803 set ownerPolicy and endorsementPolicy to the Empty Buffer; 26804 26805 26806 26807 set Clock to zero; 26808 26809 26810 26811 set resetCount to zero; 26812 26813 26814 26815 set restartCount to zero; and 26816 26817 26818 26819 set Safe to YES. 26820 26821 This command requires platformAuth or lockoutAuth. If TPM2_ClearControl() has disabled this command, 26822 the TPM shall return TPM_RC_DISABLED. 26823 If this command is authorized using lockoutAuth, the HMAC in the response shall use the new 26824 lockoutAuth value (that is, the Empty Buffer) when computing response HMAC. 26825 26826 Family 2.0 26827 Level 00 Revision 00.99 26828 26829 Published 26830 Copyright TCG 2006-2013 26831 26832 Page 321 26833 October 31, 2013 26834 26835 Part 3: Commands 26837 26838 Trusted Platform Module Library 26839 26840 26.6.2 Command and Response 26841 Table 159 TPM2_Clear Command 26842 Type 26843 26844 Name 26845 26846 TPMI_ST_COMMAND_TAG 26847 26848 tag 26849 26850 UINT32 26851 26852 commandSize 26853 26854 TPM_CC 26855 26856 commandCode 26857 26858 TPM_CC_Clear {NV E} 26859 26860 @authHandle 26861 26862 TPM_RH_LOCKOUT or TPM_RH_PLATFORM+{PP} 26863 Auth Handle: 1 26864 Auth Role: USER 26865 26866 TPMI_RH_CLEAR 26867 26868 Description 26869 26870 Table 160 TPM2_Clear Response 26871 Type 26872 26873 Name 26874 26875 Description 26876 26877 TPM_ST 26878 26879 tag 26880 26881 see clause 8 26882 26883 UINT32 26884 26885 responseSize 26886 26887 TPM_RC 26888 26889 responseCode 26890 26891 Page 322 26892 October 31, 2013 26893 26894 Published 26895 Copyright TCG 2006-2013 26896 26897 Family 2.0 26898 Level 00 Revision 00.99 26899 26900 Trusted Platform Module Library 26902 26903 Part 3: Commands 26904 26905 26.6.3 Detailed Actions 26906 1 26907 2 26908 26909 #include "InternalRoutines.h" 26910 #include "Clear_fp.h" 26911 Error Returns 26912 TPM_RC_DISABLED 26913 26914 3 26915 4 26916 5 26917 6 26918 7 26919 8 26920 9 26921 10 26922 11 26923 12 26924 13 26925 14 26926 15 26927 16 26928 17 26929 18 26930 19 26931 20 26932 21 26933 22 26934 23 26935 24 26936 25 26937 26 26938 27 26939 28 26940 29 26941 30 26942 31 26943 32 26944 33 26945 34 26946 35 26947 36 26948 37 26949 38 26950 39 26951 40 26952 41 26953 42 26954 43 26955 44 26956 45 26957 46 26958 47 26959 48 26960 49 26961 50 26962 51 26963 52 26964 53 26965 54 26966 26967 Meaning 26968 Clear command has been disabled 26969 26970 TPM_RC 26971 TPM2_Clear( 26972 Clear_In 26973 26974 *in 26975 26976 // IN: input parameter list 26977 26978 ) 26979 { 26980 TPM_RC 26981 26982 result; 26983 26984 // Input parameter is not reference in command action 26985 in = NULL; 26986 // The command needs NV update. Check if NV is available. 26987 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 26988 // this point 26989 result = NvIsAvailable(); 26990 if(result != TPM_RC_SUCCESS) return result; 26991 // Input Validation 26992 // If Clear command is disabled, return an error 26993 if(gp.disableClear) 26994 return TPM_RC_DISABLED; 26995 // Internal Data Update 26996 // Reset storage hierarchy seed from RNG 26997 CryptGenerateRandom(PRIMARY_SEED_SIZE, gp.SPSeed.t.buffer); 26998 // Create new shProof and ehProof value from RNG 26999 CryptGenerateRandom(PROOF_SIZE, gp.shProof.t.buffer); 27000 CryptGenerateRandom(PROOF_SIZE, gp.ehProof.t.buffer); 27001 // Enable storage and endorsement hierarchy 27002 gc.shEnable = gc.ehEnable = TRUE; 27003 // set the authValue buffers to zero 27004 MemorySet(gp.ownerAuth.t.buffer, 0, gp.ownerAuth.t.size); 27005 MemorySet(gp.endorsementAuth.t.buffer, 0, gp.endorsementAuth.t.size); 27006 MemorySet(gp.lockoutAuth.t.buffer, 0, gp.lockoutAuth.t.size); 27007 // Set storage, endorsement and lockout authValue to null 27008 gp.ownerAuth.t.size = gp.endorsementAuth.t.size = gp.lockoutAuth.t.size = 0; 27009 // Set storage and endorsement authPolicy to null 27010 gp.ownerAlg = gp.endorsementAlg = TPM_ALG_NULL; 27011 gp.ownerPolicy.t.size = gp.endorsementPolicy.t.size = 0; 27012 // Flush loaded object in storage and endorsement hierarchy 27013 ObjectFlushHierarchy(TPM_RH_OWNER); 27014 ObjectFlushHierarchy(TPM_RH_ENDORSEMENT); 27015 // Flush owner and endorsement object and owner index in NV 27016 NvFlushHierarchy(TPM_RH_OWNER); 27017 NvFlushHierarchy(TPM_RH_ENDORSEMENT); 27018 27019 Family 2.0 27020 Level 00 Revision 00.99 27021 27022 Published 27023 Copyright TCG 2006-2013 27024 27025 Page 323 27026 October 31, 2013 27027 27028 Part 3: Commands 27030 55 27031 56 27032 57 27033 58 27034 59 27035 60 27036 61 27037 62 27038 63 27039 64 27040 65 27041 66 27042 67 27043 68 27044 69 27045 70 27046 71 27047 72 27048 73 27049 74 27050 75 27051 76 27052 77 27053 78 27054 79 27055 80 27056 81 27057 82 27058 83 27059 84 27060 85 27061 86 27062 87 27063 88 27064 27065 Trusted Platform Module Library 27066 27067 // Save hierarchy changes to NV 27068 NvWriteReserved(NV_SP_SEED, &gp.SPSeed); 27069 NvWriteReserved(NV_SH_PROOF, &gp.shProof); 27070 NvWriteReserved(NV_EH_PROOF, &gp.ehProof); 27071 NvWriteReserved(NV_OWNER_AUTH, &gp.ownerAuth); 27072 NvWriteReserved(NV_ENDORSEMENT_AUTH, &gp.endorsementAuth); 27073 NvWriteReserved(NV_LOCKOUT_AUTH, &gp.lockoutAuth); 27074 NvWriteReserved(NV_OWNER_ALG, &gp.ownerAlg); 27075 NvWriteReserved(NV_ENDORSEMENT_ALG, &gp.endorsementAlg); 27076 NvWriteReserved(NV_OWNER_POLICY, &gp.ownerPolicy); 27077 NvWriteReserved(NV_ENDORSEMENT_POLICY, &gp.endorsementPolicy); 27078 // Initialize dictionary attack parameters 27079 DAPreInstall_Init(); 27080 // Reset clock 27081 go.clock = 0; 27082 go.clockSafe = YES; 27083 // Update the DRBG state whenever writing orderly state to NV 27084 CryptDrbgGetPutState(GET_STATE); 27085 NvWriteReserved(NV_ORDERLY_DATA, &go); 27086 // Reset counters 27087 gp.resetCount = gr.restartCount = gr.clearCount = 0; 27088 gp.auditCounter = 0; 27089 NvWriteReserved(NV_RESET_COUNT, &gp.resetCount); 27090 NvWriteReserved(NV_AUDIT_COUNTER, &gp.auditCounter); 27091 // orderly state should be cleared because of the update to state clear data 27092 g_clearOrderly = TRUE; 27093 return TPM_RC_SUCCESS; 27094 } 27095 27096 Page 324 27097 October 31, 2013 27098 27099 Published 27100 Copyright TCG 2006-2013 27101 27102 Family 2.0 27103 Level 00 Revision 00.99 27104 27105 Trusted Platform Module Library 27107 27108 26.7 27109 27110 Part 3: Commands 27111 27112 TPM2_ClearControl 27113 27114 26.7.1 General Description 27115 TPM2_ClearControl() disables and enables the execution of TPM2_Clear(). 27116 The TPM will SET the TPMs TPMA_PERMANENT.disableClear attribute if disable is YES and will 27117 CLEAR the attribute if disable is NO. When the attribute is SET, TPM2_Clear() may not be executed. 27118 NOTE 27119 27120 This is to simplify the logic of TPM2_Clear(). TPM2_ClearControl() can be called using platformAuth 27121 to CLEAR the disableClear attribute and then execute TPM2_Clear(). 27122 27123 LockoutAuth may be used to SET disableClear but not to CLEAR it. 27124 PlatformAuth may be used to SET or CLEAR disableClear. 27125 27126 Family 2.0 27127 Level 00 Revision 00.99 27128 27129 Published 27130 Copyright TCG 2006-2013 27131 27132 Page 325 27133 October 31, 2013 27134 27135 Part 3: Commands 27137 27138 Trusted Platform Module Library 27139 27140 26.7.2 Command and Response 27141 Table 161 TPM2_ClearControl Command 27142 Type 27143 27144 Name 27145 27146 Description 27147 27148 TPMI_ST_COMMAND_TAG 27149 27150 tag 27151 27152 UINT32 27153 27154 commandSize 27155 27156 TPM_CC 27157 27158 commandCode 27159 27160 TPM_CC_ClearControl {NV} 27161 27162 TPMI_RH_CLEAR 27163 27164 @auth 27165 27166 TPM_RH_LOCKOUT or TPM_RH_PLATFORM+{PP} 27167 Auth Handle: 1 27168 Auth Role: USER 27169 27170 TPMI_YES_NO 27171 27172 disable 27173 27174 YES if the disableOwnerClear flag is to be SET, NO if 27175 the flag is to be CLEAR. 27176 27177 Table 162 TPM2_ClearControl Response 27178 Type 27179 27180 Name 27181 27182 Description 27183 27184 TPM_ST 27185 27186 tag 27187 27188 see clause 8 27189 27190 UINT32 27191 27192 responseSize 27193 27194 TPM_RC 27195 27196 responseCode 27197 27198 Page 326 27199 October 31, 2013 27200 27201 Published 27202 Copyright TCG 2006-2013 27203 27204 Family 2.0 27205 Level 00 Revision 00.99 27206 27207 Trusted Platform Module Library 27209 27210 Part 3: Commands 27211 27212 26.7.3 Detailed Actions 27213 1 27214 2 27215 27216 #include "InternalRoutines.h" 27217 #include "ClearControl_fp.h" 27218 Error Returns 27219 TPM_RC_AUTH_FAIL 27220 27221 3 27222 4 27223 5 27224 6 27225 7 27226 8 27227 9 27228 10 27229 11 27230 12 27231 13 27232 14 27233 15 27234 16 27235 17 27236 18 27237 19 27238 20 27239 21 27240 22 27241 23 27242 24 27243 25 27244 26 27245 27 27246 28 27247 29 27248 30 27249 31 27250 32 27251 33 27252 27253 Meaning 27254 authorization is not properly given 27255 27256 TPM_RC 27257 TPM2_ClearControl( 27258 ClearControl_In 27259 27260 *in 27261 27262 // IN: input parameter list 27263 27264 ) 27265 { 27266 TPM_RC 27267 27268 result; 27269 27270 // The command needs NV update. Check if NV is available. 27271 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 27272 // this point 27273 result = NvIsAvailable(); 27274 if(result != TPM_RC_SUCCESS) return result; 27275 // Input Validation 27276 // LockoutAuth may be used to set disableLockoutClear to TRUE but not to FALSE 27277 if(in->auth == TPM_RH_LOCKOUT && in->disable == NO) 27278 return TPM_RC_AUTH_FAIL; 27279 // Internal Data Update 27280 if(in->disable == YES) 27281 gp.disableClear = TRUE; 27282 else 27283 gp.disableClear = FALSE; 27284 // Record the change to NV 27285 NvWriteReserved(NV_DISABLE_CLEAR, &gp.disableClear); 27286 return TPM_RC_SUCCESS; 27287 } 27288 27289 Family 2.0 27290 Level 00 Revision 00.99 27291 27292 Published 27293 Copyright TCG 2006-2013 27294 27295 Page 327 27296 October 31, 2013 27297 27298 Part 3: Commands 27300 27301 26.8 27302 27303 Trusted Platform Module Library 27304 27305 TPM2_HierarchyChangeAuth 27306 27307 26.8.1 General Description 27308 This command allows the authorization secret for a hierarchy or lockout to be changed using the current 27309 authorization value as the command authorization. 27310 If authHandle is TPM_RH_PLATFORM, then platformAuth is changed. If authHandle is 27311 TPM_RH_OWNER, then ownerAuth is changed. If authHandle is TPM_RH_ENDORSEMENT, then 27312 endorsementAuth is changed. If authHandle is TPM_RH_LOCKOUT, then lockoutAuth is changed. 27313 If authHandle is TPM_RH_PLATFORM, then Physical Presence may need to be asserted for this 27314 command to succeed (see 28.2, TPM2_PP_Commands). 27315 The authorization value may be no larger than the digest produced by the hash algorithm used for context 27316 integrity. 27317 EXAMPLE 27318 27319 If SHA384 is used in the computation of the integrity values for saved contexts, then the largest 27320 authorization value is 48 octets. 27321 27322 Page 328 27323 October 31, 2013 27324 27325 Published 27326 Copyright TCG 2006-2013 27327 27328 Family 2.0 27329 Level 00 Revision 00.99 27330 27331 Trusted Platform Module Library 27333 27334 Part 3: Commands 27335 27336 26.8.2 Command and Response 27337 Table 163 TPM2_HierarchyChangeAuth Command 27338 Type 27339 27340 Name 27341 27342 Description 27343 27344 TPMI_ST_COMMAND_TAG 27345 27346 tag 27347 27348 UINT32 27349 27350 commandSize 27351 27352 TPM_CC 27353 27354 commandCode 27355 27356 TPM_CC_HierarchyChangeAuth {NV} 27357 27358 TPMI_RH_HIERARCHY_AUTH 27359 27360 @authHandle 27361 27362 TPM_RH_LOCKOUT, TPM_RH_ENDORSEMENT, 27363 TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 27364 Auth Index: 1 27365 Auth Role: USER 27366 27367 TPM2B_AUTH 27368 27369 newAuth 27370 27371 new authorization value 27372 27373 Table 164 TPM2_HierarchyChangeAuth Response 27374 Type 27375 27376 Name 27377 27378 Description 27379 27380 TPM_ST 27381 27382 tag 27383 27384 see clause 8 27385 27386 UINT32 27387 27388 responseSize 27389 27390 TPM_RC 27391 27392 responseCode 27393 27394 Family 2.0 27395 Level 00 Revision 00.99 27396 27397 Published 27398 Copyright TCG 2006-2013 27399 27400 Page 329 27401 October 31, 2013 27402 27403 Part 3: Commands 27405 27406 Trusted Platform Module Library 27407 27408 26.8.3 Detailed Actions 27409 1 27410 2 27411 3 27412 27413 #include "InternalRoutines.h" 27414 #include "HierarchyChangeAuth_fp.h" 27415 #include "Object_spt_fp.h" 27416 Error Returns 27417 TPM_RC_SIZE 27418 27419 4 27420 5 27421 6 27422 7 27423 8 27424 9 27425 10 27426 11 27427 12 27428 13 27429 14 27430 15 27431 16 27432 17 27433 18 27434 19 27435 20 27436 21 27437 22 27438 23 27439 24 27440 25 27441 26 27442 27 27443 28 27444 29 27445 30 27446 31 27447 32 27448 33 27449 34 27450 35 27451 36 27452 37 27453 38 27454 39 27455 40 27456 41 27457 42 27458 43 27459 44 27460 45 27461 46 27462 47 27463 48 27464 49 27465 50 27466 51 27467 27468 Meaning 27469 newAuth size is greater than that of integrity hash digest 27470 27471 TPM_RC 27472 TPM2_HierarchyChangeAuth( 27473 HierarchyChangeAuth_In 27474 27475 *in 27476 27477 // IN: input parameter list 27478 27479 ) 27480 { 27481 TPM_RC 27482 27483 result; 27484 27485 // The command needs NV update. Check if NV is available. 27486 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 27487 // this point 27488 result = NvIsAvailable(); 27489 if(result != TPM_RC_SUCCESS) return result; 27490 // Make sure the the auth value is a reasonable size (not larger than 27491 // the size of the digest produced by the integrity hash. The integrity 27492 // hash is assumed to produce the longest digest of any hash implemented 27493 // on the TPM. 27494 if( MemoryRemoveTrailingZeros(&in->newAuth) 27495 > CryptGetHashDigestSize(CONTEXT_INTEGRITY_HASH_ALG)) 27496 return TPM_RC_SIZE + RC_HierarchyChangeAuth_newAuth; 27497 // Set hierarchy authValue 27498 switch(in->authHandle) 27499 { 27500 case TPM_RH_OWNER: 27501 gp.ownerAuth = in->newAuth; 27502 NvWriteReserved(NV_OWNER_AUTH, &gp.ownerAuth); 27503 break; 27504 case TPM_RH_ENDORSEMENT: 27505 gp.endorsementAuth = in->newAuth; 27506 NvWriteReserved(NV_ENDORSEMENT_AUTH, &gp.endorsementAuth); 27507 break; 27508 case TPM_RH_PLATFORM: 27509 gc.platformAuth = in->newAuth; 27510 // orderly state should be cleared 27511 g_clearOrderly = TRUE; 27512 break; 27513 case TPM_RH_LOCKOUT: 27514 gp.lockoutAuth = in->newAuth; 27515 NvWriteReserved(NV_LOCKOUT_AUTH, &gp.lockoutAuth); 27516 break; 27517 default: 27518 pAssert(FALSE); 27519 break; 27520 } 27521 return TPM_RC_SUCCESS; 27522 } 27523 27524 Page 330 27525 October 31, 2013 27526 27527 Published 27528 Copyright TCG 2006-2013 27529 27530 Family 2.0 27531 Level 00 Revision 00.99 27532 27533 Trusted Platform Module Library 27535 27536 27 27537 27538 Part 3: Commands 27539 27540 Dictionary Attack Functions 27541 27542 27.1 27543 27544 Introduction 27545 27546 A TPM is required to have support for logic that will help prevent a dictionary attack on an authorization 27547 value. The protection is provided by a counter that increments when a password authorization or an 27548 HMAC authorization fails. When the counter reaches a predefined value, the TPM will not accept, for 27549 some time interval, further requests that require authorization and the TPM is in Lockout mode. While the 27550 TPM is in Lockout mode, the TPM will return TPM_RC_LOCKED if the command requires use of an 27551 objects or Indexs authValue unless the authorization applies to an entry in the Platform hierarchy. 27552 NOTE 27553 27554 Authorizations for objects and NV Index values in the Platform hierarchy are never locked out. 27555 However, a command that requires multiple authorizations will not be accepted when the TPM is in 27556 Lockout mode unless all of the authorizations reference objects and indexes in the Platform 27557 hierarchy. 27558 27559 If the TPM is continuously powered for the duration of newRecoveryTime and no authorization failures 27560 occur, the authorization failure counter will be decremented by one. This property is called self-healing. 27561 Self-healing shall not cause the count of failed attempts to decrement below zero. 27562 The count of failed attempts, the lockout interval, and self-healing interval are settable using 27563 TPM2_DictionaryAttackParameters(). The lockout parameters and the current value of the lockout 27564 counter can be read with TPM2_GetCapability(). 27565 Dictionary attack protection does not apply to an entity associated with a permanent handle (handle type 27566 == TPM_HT_PERMANENT). 27567 27.2 27568 27569 TPM2_DictionaryAttackLockReset 27570 27571 27.2.1 General Description 27572 This command cancels the effect of a TPM lockout due to a number of successive authorization failures. 27573 If this command is properly authorized, the lockout counter is set to zero. 27574 Only one authorization failure is allowed for this command during a lockoutRecovery interval (set using 27575 TPM2_DictionaryAttackParameters(). 27576 27577 Family 2.0 27578 Level 00 Revision 00.99 27579 27580 Published 27581 Copyright TCG 2006-2013 27582 27583 Page 331 27584 October 31, 2013 27585 27586 Part 3: Commands 27588 27589 Trusted Platform Module Library 27590 27591 27.2.2 Command and Response 27592 Table 165 TPM2_DictionaryAttackLockReset Command 27593 Type 27594 27595 Name 27596 27597 TPMI_ST_COMMAND_TAG 27598 27599 tag 27600 27601 UINT32 27602 27603 commandSize 27604 27605 TPM_CC 27606 27607 commandCode 27608 27609 TPM_CC_DictionaryAttackLockReset {NV} 27610 27611 @lockHandle 27612 27613 TPM_RH_LOCKOUT 27614 Auth Index: 1 27615 Auth Role: USER 27616 27617 TPMI_RH_LOCKOUT 27618 27619 Description 27620 27621 Table 166 TPM2_DictionaryAttackLockReset Response 27622 Type 27623 27624 Name 27625 27626 Description 27627 27628 TPM_ST 27629 27630 tag 27631 27632 see clause 8 27633 27634 UINT32 27635 27636 responseSize 27637 27638 TPM_RC 27639 27640 responseCode 27641 27642 Page 332 27643 October 31, 2013 27644 27645 Published 27646 Copyright TCG 2006-2013 27647 27648 Family 2.0 27649 Level 00 Revision 00.99 27650 27651 Trusted Platform Module Library 27653 27654 Part 3: Commands 27655 27656 27.2.3 Detailed Actions 27657 1 27658 2 27659 3 27660 4 27661 5 27662 6 27663 7 27664 8 27665 9 27666 10 27667 11 27668 12 27669 13 27670 14 27671 15 27672 16 27673 17 27674 18 27675 19 27676 20 27677 21 27678 22 27679 23 27680 24 27681 25 27682 26 27683 27 27684 28 27685 27686 #include "InternalRoutines.h" 27687 #include "DictionaryAttackLockReset_fp.h" 27688 27689 TPM_RC 27690 TPM2_DictionaryAttackLockReset( 27691 DictionaryAttackLockReset_In 27692 27693 *in 27694 27695 // IN: input parameter list 27696 27697 ) 27698 { 27699 TPM_RC 27700 27701 result; 27702 27703 // Input parameter is not reference in command action 27704 in = NULL; 27705 // The command needs NV update. Check if NV is available. 27706 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 27707 // this point 27708 result = NvIsAvailable(); 27709 if(result != TPM_RC_SUCCESS) return result; 27710 // Internal Data Update 27711 // Set failed tries to 0 27712 gp.failedTries = 0; 27713 // Record the changes to NV 27714 NvWriteReserved(NV_FAILED_TRIES, &gp.failedTries); 27715 return TPM_RC_SUCCESS; 27716 } 27717 27718 Family 2.0 27719 Level 00 Revision 00.99 27720 27721 Published 27722 Copyright TCG 2006-2013 27723 27724 Page 333 27725 October 31, 2013 27726 27727 Part 3: Commands 27729 27730 27.3 27731 27732 Trusted Platform Module Library 27733 27734 TPM2_DictionaryAttackParameters 27735 27736 27.3.1 General Description 27737 This command changes the lockout parameters. 27738 The command requires lockoutAuth. 27739 The timeout parameters (newRecoveryTime and lockoutRecovery) indicate values that are measured with 27740 respect to the Time and not Clock. 27741 NOTE 27742 27743 Use of Time means that the TPM shall be continuously powered for the duration of a timeout. 27744 27745 If newRecoveryTime is zero, then DA protection is disabled. Authorizations are checked but authorization 27746 failures will not cause the TPM to enter lockout. 27747 If newMaxTries is zero, the TPM will be in lockout and use of DA protected entities will be disabled. 27748 If lockoutRecovery is zero, then the recovery interval is a boot cycle (_TPM_Init followed by 27749 Startup(CLEAR). 27750 This command will set the authorization failure count (failedTries) to zero. 27751 Only one authorization failure is allowed for this command during a lockoutRecovery interval. 27752 27753 Page 334 27754 October 31, 2013 27755 27756 Published 27757 Copyright TCG 2006-2013 27758 27759 Family 2.0 27760 Level 00 Revision 00.99 27761 27762 Trusted Platform Module Library 27764 27765 Part 3: Commands 27766 27767 27.3.2 Command and Response 27768 Table 167 TPM2_DictionaryAttackParameters Command 27769 Type 27770 27771 Name 27772 27773 Description 27774 27775 TPMI_ST_COMMAND_TAG 27776 27777 tag 27778 27779 UINT32 27780 27781 commandSize 27782 27783 TPM_CC 27784 27785 commandCode 27786 27787 TPM_CC_DictionaryAttackParameters {NV} 27788 27789 TPMI_RH_LOCKOUT 27790 27791 @lockHandle 27792 27793 TPM_RH_LOCKOUT 27794 Auth Index: 1 27795 Auth Role: USER 27796 27797 UINT32 27798 27799 newMaxTries 27800 27801 count of authorization failures before the lockout is 27802 imposed 27803 27804 UINT32 27805 27806 newRecoveryTime 27807 27808 time in seconds before the authorization failure count 27809 is automatically decremented 27810 A value of zero indicates that DA protection is 27811 disabled. 27812 27813 UINT32 27814 27815 lockoutRecovery 27816 27817 time in seconds after a lockoutAuth failure before use 27818 of lockoutAuth is allowed 27819 A value of zero indicates that a reboot is required. 27820 27821 Table 168 TPM2_DictionaryAttackParameters Response 27822 Type 27823 27824 Name 27825 27826 Description 27827 27828 TPM_ST 27829 27830 tag 27831 27832 see clause 8 27833 27834 UINT32 27835 27836 responseSize 27837 27838 TPM_RC 27839 27840 responseCode 27841 27842 Family 2.0 27843 Level 00 Revision 00.99 27844 27845 Published 27846 Copyright TCG 2006-2013 27847 27848 Page 335 27849 October 31, 2013 27850 27851 Part 3: Commands 27853 27854 Trusted Platform Module Library 27855 27856 27.3.3 Detailed Actions 27857 1 27858 2 27859 3 27860 4 27861 5 27862 6 27863 7 27864 8 27865 9 27866 10 27867 11 27868 12 27869 13 27870 14 27871 15 27872 16 27873 17 27874 18 27875 19 27876 20 27877 21 27878 22 27879 23 27880 24 27881 25 27882 26 27883 27 27884 28 27885 29 27886 30 27887 31 27888 32 27889 33 27890 27891 #include "InternalRoutines.h" 27892 #include "DictionaryAttackParameters_fp.h" 27893 27894 TPM_RC 27895 TPM2_DictionaryAttackParameters( 27896 DictionaryAttackParameters_In 27897 27898 *in 27899 27900 // IN: input parameter list 27901 27902 ) 27903 { 27904 TPM_RC 27905 27906 result; 27907 27908 // The command needs NV update. Check if NV is available. 27909 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 27910 // this point 27911 result = NvIsAvailable(); 27912 if(result != TPM_RC_SUCCESS) return result; 27913 // Internal Data Update 27914 // Set dictionary attack parameters 27915 gp.maxTries = in->newMaxTries; 27916 gp.recoveryTime = in->newRecoveryTime; 27917 gp.lockoutRecovery = in->lockoutRecovery; 27918 // Set failed tries to 0 27919 gp.failedTries = 0; 27920 // Record the changes to NV 27921 NvWriteReserved(NV_FAILED_TRIES, &gp.failedTries); 27922 NvWriteReserved(NV_MAX_TRIES, &gp.maxTries); 27923 NvWriteReserved(NV_RECOVERY_TIME, &gp.recoveryTime); 27924 NvWriteReserved(NV_LOCKOUT_RECOVERY, &gp.lockoutRecovery); 27925 return TPM_RC_SUCCESS; 27926 } 27927 27928 Page 336 27929 October 31, 2013 27930 27931 Published 27932 Copyright TCG 2006-2013 27933 27934 Family 2.0 27935 Level 00 Revision 00.99 27936 27937 Trusted Platform Module Library 27939 27940 28 27941 27942 Part 3: Commands 27943 27944 Miscellaneous Management Functions 27945 27946 28.1 27947 27948 Introduction 27949 27950 This clause contains commands that do not logically group with any other commands. 27951 28.2 27952 27953 TPM2_PP_Commands 27954 27955 28.2.1 General Description 27956 This command is used to determine which commands require assertion of Physical Presence (PP) in 27957 addition to platformAuth/platformPolicy. 27958 This command requires that auth is TPM_RH_PLATFORM and that Physical Presence be asserted. 27959 After this command executes successfully, the commands listed in setList will be added to the list of 27960 commands that require that Physical Presence be asserted when the handle associated with the 27961 authorization is TPM_RH_PLATFORM. The commands in clearList will no longer require assertion of 27962 Physical Presence in order to authorize a command. 27963 If a command is not in either list, its state is not changed. If a command is in both lists, then it will no 27964 longer require Physical Presence (for example, setList is processed first). 27965 Only commands with 27966 handle types of 27967 TPMI_RH_PLATFORM, TPMI_RH_PROVISION, 27968 TPMI_RH_CLEAR, or TPMI_RH_HIERARCHY can be gated with Physical Presence. If any other 27969 command is in either list, it is discarded. 27970 When a command requires that Physical Presence be provided, then Physical Presence shall be 27971 asserted for either an HMAC or a Policy authorization. 27972 NOTE 27973 27974 Physical Presence may be made a requirement of any policy. 27975 27976 TPM2_PP_Commands() always requires assertion of Physical Presence. 27977 27978 Family 2.0 27979 Level 00 Revision 00.99 27980 27981 Published 27982 Copyright TCG 2006-2013 27983 27984 Page 337 27985 October 31, 2013 27986 27987 Part 3: Commands 27989 27990 Trusted Platform Module Library 27991 27992 28.2.2 Command and Response 27993 Table 169 TPM2_PP_Commands Command 27994 Type 27995 27996 Name 27997 27998 Description 27999 28000 TPMI_ST_COMMAND_TAG 28001 28002 tag 28003 28004 UINT32 28005 28006 commandSize 28007 28008 TPM_CC 28009 28010 commandCode 28011 28012 TPM_CC_PP_Commands {NV} 28013 28014 TPMI_RH_PLATFORM 28015 28016 @auth 28017 28018 TPM_RH_PLATFORM+PP 28019 Auth Index: 1 28020 Auth Role: USER + Physical Presence 28021 28022 TPML_CC 28023 28024 setList 28025 28026 list of commands to be added to those that will require 28027 that Physical Presence be asserted 28028 28029 TPML_CC 28030 28031 clearList 28032 28033 list of commands that will no longer require that 28034 Physical Presence be asserted 28035 28036 Table 170 TPM2_PP_Commands Response 28037 Type 28038 28039 Name 28040 28041 Description 28042 28043 TPM_ST 28044 28045 tag 28046 28047 see clause 8 28048 28049 UINT32 28050 28051 responseSize 28052 28053 TPM_RC 28054 28055 responseCode 28056 28057 Page 338 28058 October 31, 2013 28059 28060 Published 28061 Copyright TCG 2006-2013 28062 28063 Family 2.0 28064 Level 00 Revision 00.99 28065 28066 Trusted Platform Module Library 28068 28069 Part 3: Commands 28070 28071 28.2.3 Detailed Actions 28072 1 28073 2 28074 3 28075 4 28076 5 28077 6 28078 7 28079 8 28080 9 28081 10 28082 11 28083 12 28084 13 28085 14 28086 15 28087 16 28088 17 28089 18 28090 19 28091 20 28092 21 28093 22 28094 23 28095 24 28096 25 28097 26 28098 27 28099 28 28100 29 28101 30 28102 31 28103 32 28104 33 28105 34 28106 35 28107 36 28108 37 28109 38 28110 39 28111 40 28112 41 28113 28114 #include "InternalRoutines.h" 28115 #include "PP_Commands_fp.h" 28116 28117 TPM_RC 28118 TPM2_PP_Commands( 28119 PP_Commands_In 28120 28121 *in 28122 28123 // IN: input parameter list 28124 28125 ) 28126 { 28127 UINT32 28128 TPM_RC 28129 28130 i; 28131 result; 28132 28133 // The command needs NV update. Check if NV is available. 28134 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 28135 // this point 28136 result = NvIsAvailable(); 28137 if(result != TPM_RC_SUCCESS) return result; 28138 // Internal Data Update 28139 // Process set list 28140 for(i = 0; i < in->setList.count; i++) 28141 // If command is implemented, set it as PP required. If the input 28142 // command is not a PP command, it will be ignored at 28143 // PhysicalPresenceCommandSet(). 28144 if(CommandIsImplemented(in->setList.commandCodes[i])) 28145 PhysicalPresenceCommandSet(in->setList.commandCodes[i]); 28146 // Process clear list 28147 for(i = 0; i < in->clearList.count; i++) 28148 // If command is implemented, clear it as PP required. If the input 28149 // command is not a PP command, it will be ignored at 28150 // PhysicalPresenceCommandClear(). If the input command is 28151 // TPM2_PP_Commands, it will be ignored as well 28152 if(CommandIsImplemented(in->clearList.commandCodes[i])) 28153 PhysicalPresenceCommandClear(in->clearList.commandCodes[i]); 28154 // Save the change of PP list 28155 NvWriteReserved(NV_PP_LIST, &gp.ppList); 28156 return TPM_RC_SUCCESS; 28157 } 28158 28159 Family 2.0 28160 Level 00 Revision 00.99 28161 28162 Published 28163 Copyright TCG 2006-2013 28164 28165 Page 339 28166 October 31, 2013 28167 28168 Part 3: Commands 28170 28171 28.3 28172 28173 Trusted Platform Module Library 28174 28175 TPM2_SetAlgorithmSet 28176 28177 28.3.1 General Description 28178 This command allows the platform to change the set of algorithms that are used by the TPM. The 28179 algorithmSet setting is a vendor-dependent value. 28180 If the changing of the algorithm set results in a change of the algorithms of PCR banks, then the TPM will 28181 need to be reset (_TPM_Init and TPM2_Startup(TPM_SU_CLEAR)) before the new PCR settings take 28182 effect. After this command executes successfully, if startupType in the next TPM2_Startup() is not 28183 TPM_SU_CLEAR, the TPM shall return TPM_RC_VALUE and enter Failure mode. 28184 This command does not change the algorithms available to the platform. 28185 NOTE 28186 28187 The reference implementation does not have support for this command. In particular, it does not 28188 support use of this command to selectively disable algorithms. Proper support wo uld require 28189 modification of the unmarshaling code so that each time an algorithm is unmarshaled, it would be 28190 verified as being enabled. 28191 28192 Page 340 28193 October 31, 2013 28194 28195 Published 28196 Copyright TCG 2006-2013 28197 28198 Family 2.0 28199 Level 00 Revision 00.99 28200 28201 Trusted Platform Module Library 28203 28204 Part 3: Commands 28205 28206 28.3.2 Command and Response 28207 Table 171 TPM2_SetAlgorithmSet Command 28208 Type 28209 28210 Name 28211 28212 Description 28213 28214 TPMI_ST_COMMAND_TAG 28215 28216 tag 28217 28218 UINT32 28219 28220 commandSize 28221 28222 TPM_CC 28223 28224 commandCode 28225 28226 TPM_CC_SetAlgorithmSet {NV} 28227 28228 TPMI_RH_PLATFORM 28229 28230 @authHandle 28231 28232 TPM_RH_PLATFORM 28233 Auth Index: 1 28234 Auth Role: USER 28235 28236 UINT32 28237 28238 algorithmSet 28239 28240 a TPM vendor-dependent value indicating the 28241 algorithm set selection 28242 28243 Table 172 TPM2_SetAlgorithmSet Response 28244 Type 28245 28246 Name 28247 28248 Description 28249 28250 TPM_ST 28251 28252 tag 28253 28254 see clause 8 28255 28256 UINT32 28257 28258 responseSize 28259 28260 TPM_RC 28261 28262 responseCode 28263 28264 Family 2.0 28265 Level 00 Revision 00.99 28266 28267 Published 28268 Copyright TCG 2006-2013 28269 28270 Page 341 28271 October 31, 2013 28272 28273 Part 3: Commands 28275 28276 Trusted Platform Module Library 28277 28278 28.3.3 Detailed Actions 28279 1 28280 2 28281 3 28282 4 28283 5 28284 6 28285 7 28286 8 28287 9 28288 10 28289 11 28290 12 28291 13 28292 14 28293 15 28294 16 28295 17 28296 18 28297 19 28298 20 28299 21 28300 22 28301 23 28302 28303 #include "InternalRoutines.h" 28304 #include "SetAlgorithmSet_fp.h" 28305 28306 TPM_RC 28307 TPM2_SetAlgorithmSet( 28308 SetAlgorithmSet_In 28309 28310 *in 28311 28312 // IN: input parameter list 28313 28314 ) 28315 { 28316 TPM_RC 28317 28318 result; 28319 28320 // The command needs NV update. Check if NV is available. 28321 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 28322 // this point 28323 result = NvIsAvailable(); 28324 if(result != TPM_RC_SUCCESS) return result; 28325 // Internal Data Update 28326 gp.algorithmSet = in->algorithmSet; 28327 // Write the algorithm set changes to NV 28328 NvWriteReserved(NV_ALGORITHM_SET, &gp.algorithmSet); 28329 return TPM_RC_SUCCESS; 28330 } 28331 28332 Page 342 28333 October 31, 2013 28334 28335 Published 28336 Copyright TCG 2006-2013 28337 28338 Family 2.0 28339 Level 00 Revision 00.99 28340 28341 Trusted Platform Module Library 28343 28344 Part 3: Commands 28345 28346 Field Upgrade 28347 28348 29 28349 29.1 28350 28351 Introduction 28352 28353 This clause contains the commands for managing field upgrade of the firmware in the TPM. The field 28354 upgrade scheme may be used for replacement or augmentation of the firmware installed in the TPM. 28355 EXAMPLE 1 28356 28357 If an algorithm is found to be flawed, a patch of that algorithm might be installed using the firmware 28358 upgrade process. The patch might be a replacement of a portion of the code or a complete 28359 replacement of the firmware. 28360 28361 EXAMPLE 2 28362 28363 If an additional set of ECC parameters is needed, the firmware process may be used to add the 28364 parameters to the TPM data set. 28365 28366 The 28367 field 28368 upgrade 28369 process 28370 uses 28371 two 28372 commands 28373 (TPM2_FieldUpgradeStart() 28374 and 28375 TPM2_FieldUpgradeData()). TPM2_FieldUpgradeStart() validates that a signature on the provided digest 28376 is from the TPM manufacturer and that proper authorization is provided using platformPolicy. 28377 NOTE 1 28378 28379 The platformPolicy for field upgraded is defined by the PM and may include requirements that the 28380 upgrade be signed by the PM or the TPM owner and include any other constraints that are desired 28381 by the PM. 28382 28383 If the proper authorization is given, the TPM will retain the signed digest and enter the Field Upgrade 28384 mode (FUM). While in FUM, the TPM will accept TPM2_FieldUpgradeData() commands. It may accept 28385 other commands if it is able to complete them using the previously installed firmware. Otherwise, it will 28386 return TPM_RC_UPGRADE. 28387 Each block of the field upgrade shall contain the digest of the next block of the field upgrade data. That 28388 digest shall be included in the digest of the previous block. The digest of the first block is signed by the 28389 TPM manufacturer. That signature and first block digest are the parameters for 28390 TPM2_FieldUpgradeStart(). The digest is saved in the TPM as the required digest for the next field 28391 upgrade data block and as the identifier of the field upgrade sequence. 28392 For each field upgrade data block that is sent to the TPM by TPM2_FieldUpgradeData(), the TPM shall 28393 validate that the digest matches the required digest and if not, shall return TPM_RC_VALUE. The TPM 28394 shall extract the digest of the next expected block and return that value to the caller, along with the digest 28395 of the first data block of the update sequence. 28396 The system may attempt to abandon the firmware upgrade by using a zero-length buffer in 28397 TPM2_FieldUpdateData(). If the TPM is able to resume operation using the firmware present when the 28398 upgrade started, then the TPM will indicate that it has abandon the update by setting the digest of the 28399 next block to the Empty Buffer. If the TPM cannot abandon the update, it will return the expected next 28400 digest. 28401 The system may also attempt to abandon the update because of a power interruption. If the TPM is able 28402 to resume normal operations, then it will respond normally to TPM2_Startup(). If the TPM is not able to 28403 resume normal operations, then it will respond to any command but TPM2_FieldUpgradeData() with 28404 TPM_RC_FIELDUPGRADE. 28405 After a _TPM_Init, system software may not be able to resume the field upgrade that was in process 28406 when the power interruption occurred. In such case, the TPM firmware may be reset to one of two other 28407 values: 28408 28409 28410 the original firmware that was installed at the factory (initial firmware); or 28411 28412 28413 28414 the firmware that was in the TPM when the field upgrade process started (previous firmware). 28415 28416 The TPM retains the digest of the first block for these firmware images and checks to see if the first block 28417 after _TPM_Init matches either of those digests. If so, the firmware update process restarts and the 28418 original firmware may be loaded. 28419 Family 2.0 28420 Level 00 Revision 00.99 28421 28422 Published 28423 Copyright TCG 2006-2013 28424 28425 Page 343 28426 October 31, 2013 28427 28428 Part 3: Commands 28430 NOTE 2 28431 28432 Trusted Platform Module Library 28433 28434 The TPM is required to accept the previous firmware as either a vendor -provided update or as 28435 recovered from the TPM using TPM2_FirmwareRead(). 28436 28437 When the last block of the firmware upgrade is loaded into the TPM (indicated to the TPM by data in the 28438 data block in a TPM vendor-specific manner), the TPM will complete the upgrade process. If the TPM is 28439 able to resume normal operations without a reboot, it will set the hash algorithm of the next block to 28440 TPM_ALG_NULL and return TPM_RC_SUCCESS. If a reboot is required, the TPM shall return 28441 TPM_RC_REBOOT in response to the last TPM2_FieldUpgradeData() and all subsequent TPM 28442 commands until a _TPM_Init is received. 28443 NOTE 3 28444 28445 Because no additional data is allowed when the res ponse code is not TPM_RC_SUCCESS, the TPM 28446 returns TPM_RC_SUCCESS for all calls to TPM2_FieldUpgradeData() except the last. In this 28447 manner, the TPM is able to indicate the digest of the next block. If a _TPM_Init occurs while the 28448 TPM is in FUM, the next block may be the digest for the first block of the original firmware. If it is 28449 not, then the TPM will not accept the original firmware until the next _TPM_Init when the TPM is in 28450 FUM. 28451 28452 During the field upgrade process, the TPM shall preserve: 28453 28454 28455 Primary Seeds; 28456 28457 28458 28459 Hierarchy authValue, authPolicy, and proof values; 28460 28461 28462 28463 Lockout authValue and authorization failure count values; 28464 28465 28466 28467 PCR authValue and authPolicy values; 28468 28469 28470 28471 NV Index allocations and contents; 28472 28473 28474 28475 Persistent object allocations and contents; and 28476 28477 28478 28479 Clock. 28480 28481 Page 344 28482 October 31, 2013 28483 28484 Published 28485 Copyright TCG 2006-2013 28486 28487 Family 2.0 28488 Level 00 Revision 00.99 28489 28490 Trusted Platform Module Library 28492 28493 29.2 28494 28495 Part 3: Commands 28496 28497 TPM2_FieldUpgradeStart 28498 28499 29.2.1 General Description 28500 This command uses platformPolicy and a TPM Vendor Authorization Key to authorize a Field Upgrade 28501 Manifest. 28502 If the signature checks 28503 TPM2_FieldUpgradeData(). 28504 28505 succeed, 28506 28507 the 28508 28509 authorization 28510 28511 is 28512 28513 valid 28514 28515 and 28516 28517 the 28518 28519 TPM 28520 28521 will 28522 28523 accept 28524 28525 This signature is checked against the loaded key referenced by keyHandle. This key will have a Name 28526 that is the same as a value that is part of the TPM firmware data. If the signature is not valid, the TPM 28527 shall return TPM_RC_SIGNATURE. 28528 NOTE 28529 28530 A loaded key is used rather than a hard-coded key to reduce the amount of memory needed for this 28531 key data in case more than one vendor key is needed. 28532 28533 Family 2.0 28534 Level 00 Revision 00.99 28535 28536 Published 28537 Copyright TCG 2006-2013 28538 28539 Page 345 28540 October 31, 2013 28541 28542 Part 3: Commands 28544 28545 Trusted Platform Module Library 28546 28547 29.2.2 Command and Response 28548 Table 173 TPM2_FieldUpgradeStart Command 28549 Type 28550 28551 Name 28552 28553 Description 28554 28555 TPMI_ST_COMMAND_TAG 28556 28557 tag 28558 28559 UINT32 28560 28561 commandSize 28562 28563 TPM_CC 28564 28565 commandCode 28566 28567 TPM_CC_FieldUpgradeStart 28568 28569 TPMI_RH_PLATFORM 28570 28571 @authorization 28572 28573 TPM_RH_PLATFORM+{PP} 28574 Auth Index:1 28575 Auth Role: ADMIN 28576 28577 TPMI_DH_OBJECT 28578 28579 keyHandle 28580 28581 handle of a public area that contains the TPM Vendor 28582 Authorization Key that will be used to validate 28583 manifestSignature 28584 Auth Index: None 28585 28586 TPM2B_DIGEST 28587 28588 fuDigest 28589 28590 digest of the first block in the field upgrade sequence 28591 28592 TPMT_SIGNATURE 28593 28594 manifestSignature 28595 28596 signature over fuDigest using the key associated with 28597 keyHandle (not optional) 28598 28599 Table 174 TPM2_FieldUpgradeStart Response 28600 Type 28601 28602 Name 28603 28604 Description 28605 28606 TPM_ST 28607 28608 tag 28609 28610 see clause 8 28611 28612 UINT32 28613 28614 responseSize 28615 28616 TPM_RC 28617 28618 responseCode 28619 28620 Page 346 28621 October 31, 2013 28622 28623 Published 28624 Copyright TCG 2006-2013 28625 28626 Family 2.0 28627 Level 00 Revision 00.99 28628 28629 Trusted Platform Module Library 28631 28632 Part 3: Commands 28633 28634 29.2.3 Detailed Actions 28635 1 28636 2 28637 3 28638 4 28639 5 28640 6 28641 7 28642 8 28643 9 28644 10 28645 11 28646 12 28647 13 28648 28649 #include "InternalRoutines.h" 28650 #include "FieldUpgradeStart_fp.h" 28651 #if CC_FieldUpgradeStart == YES 28652 28653 TPM_RC 28654 TPM2_FieldUpgradeStart( 28655 FieldUpgradeStart_In 28656 28657 *in 28658 28659 // IN: input parameter list 28660 28661 ) 28662 { 28663 // Not implemented 28664 UNUSED_PARAMETER(in); 28665 return TPM_RC_SUCCESS; 28666 } 28667 #endif 28668 28669 Family 2.0 28670 Level 00 Revision 00.99 28671 28672 Published 28673 Copyright TCG 2006-2013 28674 28675 Page 347 28676 October 31, 2013 28677 28678 Part 3: Commands 28680 28681 29.3 28682 28683 Trusted Platform Module Library 28684 28685 TPM2_FieldUpgradeData 28686 28687 29.3.1 General Description 28688 This command will take the actual field upgrade image to be installed on the TPM. The exact format of 28689 fuData is vendor-specific. This command is only possible following a successful 28690 TPM2_FieldUpgradeStart(). 28691 If 28692 the 28693 TPM 28694 has 28695 not 28696 received 28697 a 28698 properly 28699 authorized 28700 TPM2_FieldUpgradeStart(), then the TPM shall return TPM_RC_FIELDUPGRADE. 28701 The TPM will validate that the digest of fuData matches an expected value. If so, the TPM may buffer or 28702 immediately apply the update. If the digest of fuData does not match an expected value, the TPM shall 28703 return TPM_RC_VALUE. 28704 28705 Page 348 28706 October 31, 2013 28707 28708 Published 28709 Copyright TCG 2006-2013 28710 28711 Family 2.0 28712 Level 00 Revision 00.99 28713 28714 Trusted Platform Module Library 28716 28717 Part 3: Commands 28718 28719 29.3.2 Command and Response 28720 Table 175 TPM2_FieldUpgradeData Command 28721 Type 28722 28723 Name 28724 28725 Description 28726 28727 TPMI_ST_COMMAND_TAG 28728 28729 tag 28730 28731 UINT32 28732 28733 commandSize 28734 28735 TPM_CC 28736 28737 commandCode 28738 28739 TPM_CC_FieldUpgradeData {NV} 28740 28741 TPM2B_MAX_BUFFER 28742 28743 fuData 28744 28745 field upgrade image data 28746 28747 Table 176 TPM2_FieldUpgradeData Response 28748 Type 28749 28750 Name 28751 28752 Description 28753 28754 TPM_ST 28755 28756 tag 28757 28758 see clause 8 28759 28760 UINT32 28761 28762 responseSize 28763 28764 TPM_RC 28765 28766 responseCode 28767 28768 TPMT_HA+ 28769 28770 nextDigest 28771 28772 tagged digest of the next block 28773 TPM_ALG_NULL if field update is complete 28774 28775 TPMT_HA 28776 28777 firstDigest 28778 28779 tagged digest of the first block of the sequence 28780 28781 Family 2.0 28782 Level 00 Revision 00.99 28783 28784 Published 28785 Copyright TCG 2006-2013 28786 28787 Page 349 28788 October 31, 2013 28789 28790 Part 3: Commands 28792 28793 Trusted Platform Module Library 28794 28795 29.3.3 Detailed Actions 28796 1 28797 2 28798 3 28799 4 28800 5 28801 6 28802 7 28803 8 28804 9 28805 10 28806 11 28807 12 28808 13 28809 14 28810 15 28811 28812 #include "InternalRoutines.h" 28813 #include "FieldUpgradeData_fp.h" 28814 #if CC_FieldUpgradeData == YES 28815 28816 TPM_RC 28817 TPM2_FieldUpgradeData( 28818 FieldUpgradeData_In 28819 FieldUpgradeData_Out 28820 28821 *in, 28822 *out 28823 28824 // IN: input parameter list 28825 // OUT: output parameter list 28826 28827 ) 28828 { 28829 // Not implemented 28830 UNUSED_PARAMETER(in); 28831 UNUSED_PARAMETER(out); 28832 return TPM_RC_SUCCESS; 28833 } 28834 #endif 28835 28836 Page 350 28837 October 31, 2013 28838 28839 Published 28840 Copyright TCG 2006-2013 28841 28842 Family 2.0 28843 Level 00 Revision 00.99 28844 28845 Trusted Platform Module Library 28847 28848 29.4 28849 28850 Part 3: Commands 28851 28852 TPM2_FirmwareRead 28853 28854 29.4.1 General Description 28855 This command is used to read a copy of the current firmware installed in the TPM. 28856 The presumption is that the data will be returned in reverse order so that the last block in the sequence 28857 would be the first block given to the TPM in case of a failure recovery. If the TPM2_FirmwareRead 28858 sequence completes successfully, then the data provided from the TPM will be sufficient to allow the TPM 28859 to recover from an abandoned upgrade of this firmware. 28860 To start the sequence of retrieving the data, the caller sets sequenceNumber to zero. When the TPM has 28861 returned all the firmware data, the TPM will return the Empty Buffer as fuData. 28862 The contents of fuData are opaque to the caller. 28863 NOTE 1 28864 28865 The caller should retain the ordering of the update blocks so that the blocks sent to the TPM have 28866 the same size and inverse order as the blocks returned by a sequence of calls to this command. 28867 28868 NOTE 2 28869 28870 Support for this command is optional even if the TPM implements TPM2_FieldUpgradeStart() and 28871 TPM2_FieldUpgradeData(). 28872 28873 Family 2.0 28874 Level 00 Revision 00.99 28875 28876 Published 28877 Copyright TCG 2006-2013 28878 28879 Page 351 28880 October 31, 2013 28881 28882 Part 3: Commands 28884 28885 Trusted Platform Module Library 28886 28887 29.4.2 Command and Response 28888 Table 177 TPM2_FirmwareRead Command 28889 Type 28890 28891 Name 28892 28893 Description 28894 28895 TPMI_ST_COMMAND_TAG 28896 28897 tag 28898 28899 UINT32 28900 28901 commandSize 28902 28903 TPM_CC 28904 28905 commandCode 28906 28907 TPM_CC_FirmwareRead 28908 28909 UINT32 28910 28911 sequenceNumber 28912 28913 the number of previous calls to this command in this 28914 sequence 28915 set to 0 on the first call 28916 28917 Table 178 TPM2_FirmwareRead Response 28918 Type 28919 28920 Name 28921 28922 Description 28923 28924 TPM_ST 28925 28926 tag 28927 28928 see clause 8 28929 28930 UINT32 28931 28932 responseSize 28933 28934 TPM_RC 28935 28936 responseCode 28937 28938 TPM2B_MAX_BUFFER 28939 28940 fuData 28941 28942 Page 352 28943 October 31, 2013 28944 28945 field upgrade image data 28946 28947 Published 28948 Copyright TCG 2006-2013 28949 28950 Family 2.0 28951 Level 00 Revision 00.99 28952 28953 Trusted Platform Module Library 28955 28956 Part 3: Commands 28957 28958 29.4.3 Detailed Actions 28959 1 28960 2 28961 3 28962 4 28963 5 28964 6 28965 7 28966 8 28967 9 28968 10 28969 11 28970 12 28971 13 28972 28973 #include "InternalRoutines.h" 28974 #include "FirmwareRead_fp.h" 28975 28976 TPM_RC 28977 TPM2_FirmwareRead( 28978 FirmwareRead_In 28979 FirmwareRead_Out 28980 28981 *in, 28982 *out 28983 28984 // IN: input parameter list 28985 // OUT: output parameter list 28986 28987 ) 28988 { 28989 // Not implemented 28990 UNUSED_PARAMETER(in); 28991 UNUSED_PARAMETER(out); 28992 return TPM_RC_SUCCESS; 28993 } 28994 28995 Family 2.0 28996 Level 00 Revision 00.99 28997 28998 Published 28999 Copyright TCG 2006-2013 29000 29001 Page 353 29002 October 31, 2013 29003 29004 Part 3: Commands 29006 29007 30 29008 29009 Trusted Platform Module Library 29010 29011 Context Management 29012 29013 30.1 29014 29015 Introduction 29016 29017 Three of the commands in this clause (TPM2_ContextSave(), TPM2_ContextLoad(), and 29018 TPM2_FlushContext()) implement the resource management described in the "Context Management" 29019 clause in Part 1. 29020 The fourth command in this clause (TPM2_EvictControl()) is used to control the persistence of a loadable 29021 objects in TPM memory. Background for this command may be found in the "Owner and Platform Evict 29022 Objects" clause in Part 1. 29023 30.2 29024 29025 TPM2_ContextSave 29026 29027 30.2.1 General Description 29028 This command saves a session context, object context, or sequence object context outside the TPM. 29029 No authorization sessions of any type are allowed with this command and tag is required to be 29030 TPM_ST_NO_SESSIONS. 29031 NOTE 29032 29033 This preclusion avoids complex issues of dealing with the same session in handle and in the session 29034 area. While it might be possible to provide specificity, it would add unnecessary complexity to the 29035 TPM and, because this capability would provide no application benefit, use of authorization ses sions 29036 for audit or encryption is prohibited. 29037 29038 The TPM shall encrypt and integrity protect the context as described in the "Context Protection" clause in 29039 Part 1. 29040 See the Context Data clause in Part 2 for a description of the context structure in the response. 29041 29042 Page 354 29043 October 31, 2013 29044 29045 Published 29046 Copyright TCG 2006-2013 29047 29048 Family 2.0 29049 Level 00 Revision 00.99 29050 29051 Trusted Platform Module Library 29053 29054 Part 3: Commands 29055 29056 30.2.2 Command and Response 29057 Table 179 TPM2_ContextSave Command 29058 Type 29059 29060 Name 29061 29062 Description 29063 29064 TPMI_ST_COMMAND_TAG 29065 29066 tag 29067 29068 TPM_ST_NO_SESSIONS 29069 29070 UINT32 29071 29072 commandSize 29073 29074 TPM_CC 29075 29076 commandCode 29077 29078 TPM_CC_ContextSave 29079 29080 TPMI_DH_CONTEXT 29081 29082 saveHandle 29083 29084 handle of the resource to save 29085 Auth Index: None 29086 29087 Table 180 TPM2_ContextSave Response 29088 Type 29089 29090 Name 29091 29092 Description 29093 29094 TPM_ST 29095 29096 tag 29097 29098 see clause 8 29099 29100 UINT32 29101 29102 responseSize 29103 29104 TPM_RC 29105 29106 responseCode 29107 29108 TPMS_CONTEXT 29109 29110 context 29111 29112 Family 2.0 29113 Level 00 Revision 00.99 29114 29115 Published 29116 Copyright TCG 2006-2013 29117 29118 Page 355 29119 October 31, 2013 29120 29121 Part 3: Commands 29123 29124 Trusted Platform Module Library 29125 29126 30.2.3 Detailed Actions 29127 1 29128 2 29129 3 29130 29131 #include "InternalRoutines.h" 29132 #include "ContextSave_fp.h" 29133 #include "Context_spt_fp.h" 29134 Error Returns 29135 TPM_RC_CONTEXT_GAP 29136 29137 a contextID could not be assigned for a session context save 29138 29139 TPM_RC_TOO_MANY_CONTEXTS 29140 4 29141 5 29142 6 29143 7 29144 8 29145 9 29146 10 29147 11 29148 12 29149 13 29150 14 29151 15 29152 16 29153 17 29154 18 29155 19 29156 20 29157 21 29158 22 29159 23 29160 24 29161 25 29162 26 29163 27 29164 28 29165 29 29166 30 29167 31 29168 32 29169 33 29170 34 29171 35 29172 36 29173 37 29174 38 29175 39 29176 40 29177 41 29178 42 29179 43 29180 44 29181 45 29182 46 29183 47 29184 48 29185 49 29186 50 29187 51 29188 52 29189 53 29190 29191 Meaning 29192 29193 no more contexts can be saved as the counter has maxed out 29194 29195 TPM_RC 29196 TPM2_ContextSave( 29197 ContextSave_In 29198 ContextSave_Out 29199 29200 *in, 29201 *out 29202 29203 // IN: input parameter list 29204 // OUT: output parameter list 29205 29206 ) 29207 { 29208 TPM_RC 29209 UINT16 29210 // blob. 29211 UINT64 29212 TPM2B_SYM_KEY 29213 TPM2B_IV 29214 29215 result; 29216 fingerprintSize; 29217 29218 TPM2B_DIGEST 29219 UINT16 29220 BYTE 29221 29222 integrity; 29223 integritySize; 29224 *buffer; 29225 29226 contextID = 0; 29227 symKey; 29228 iv; 29229 29230 // The size of fingerprint in context 29231 // session context ID 29232 29233 // This command may cause the orderlyState to be cleared due to 29234 // the update of state reset data. If this is the case, check if NV is 29235 // available first 29236 if(gp.orderlyState != SHUTDOWN_NONE) 29237 { 29238 // The command needs NV update. Check if NV is available. 29239 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 29240 // this point 29241 result = NvIsAvailable(); 29242 if(result != TPM_RC_SUCCESS) return result; 29243 } 29244 // Internal Data Update 29245 // Initialize output handle. At the end of command action, the output 29246 // handle of an object will be replaced, while the output handle 29247 // for a session will be the same as input 29248 out->context.savedHandle = in->saveHandle; 29249 // Get the size of fingerprint in context blob. The sequence value in 29250 // TPMS_CONTEXT structure is used as the fingerprint 29251 fingerprintSize = sizeof(out->context.sequence); 29252 // Compute the integrity size at the beginning of context blob 29253 integritySize = sizeof(integrity.t.size) 29254 + CryptGetHashDigestSize(CONTEXT_INTEGRITY_HASH_ALG); 29255 // Perform object or session specific context save 29256 switch(HandleGetType(in->saveHandle)) 29257 { 29258 case TPM_HT_TRANSIENT: 29259 { 29260 29261 Page 356 29262 October 31, 2013 29263 29264 Published 29265 Copyright TCG 2006-2013 29266 29267 Family 2.0 29268 Level 00 Revision 00.99 29269 29270 Trusted Platform Module Library 29272 54 29273 55 29274 56 29275 57 29276 58 29277 59 29278 60 29279 61 29280 62 29281 63 29282 64 29283 65 29284 66 29285 67 29286 68 29287 69 29288 70 29289 71 29290 72 29291 73 29292 74 29293 75 29294 76 29295 77 29296 78 29297 79 29298 80 29299 81 29300 82 29301 83 29302 84 29303 85 29304 86 29305 87 29306 88 29307 89 29308 90 29309 91 29310 92 29311 93 29312 94 29313 95 29314 96 29315 97 29316 98 29317 99 29318 100 29319 101 29320 102 29321 103 29322 104 29323 105 29324 106 29325 107 29326 108 29327 109 29328 110 29329 111 29330 112 29331 113 29332 114 29333 115 29334 116 29335 117 29336 29337 OBJECT 29338 OBJECT 29339 29340 Part 3: Commands 29341 29342 *object = ObjectGet(in->saveHandle); 29343 *outObject = 29344 (OBJECT *)(out->context.contextBlob.t.buffer 29345 + integritySize + fingerprintSize); 29346 29347 // Set size of the context data. The contents of context blob is vendor 29348 // defined. In this implementation, the size is size of integrity 29349 // plus fingerprint plus the whole internal OBJECT structure 29350 out->context.contextBlob.t.size = integritySize + 29351 fingerprintSize + sizeof(*object); 29352 // Copy the whole internal OBJECT structure to context blob, leave 29353 // the size for fingerprint 29354 *outObject = *object; 29355 // Increment object context ID 29356 gr.objectContextID++; 29357 // If object context ID overflows, TPM should be put in failure mode 29358 if(gr.objectContextID == 0) 29359 FAIL(FATAL_ERROR_INTERNAL); 29360 // Fill in other return values for an object. 29361 out->context.sequence = gr.objectContextID; 29362 // For regular object, savedHandle is 0x80000000. For sequence object, 29363 // savedHandle is 0x80000001. For object with stClear, savedHandle 29364 // is 0x80000002 29365 if(ObjectIsSequence(object)) 29366 { 29367 out->context.savedHandle = 0x80000001; 29368 SequenceDataImportExport(object, outObject, EXPORT_STATE); 29369 } 29370 else if(object->attributes.stClear == SET) 29371 { 29372 out->context.savedHandle = 0x80000002; 29373 } 29374 else 29375 { 29376 out->context.savedHandle = 0x80000000; 29377 } 29378 // Get object hierarchy 29379 out->context.hierarchy = ObjectDataGetHierarchy(object); 29380 break; 29381 } 29382 case TPM_HT_HMAC_SESSION: 29383 case TPM_HT_POLICY_SESSION: 29384 { 29385 SESSION 29386 *session = SessionGet(in->saveHandle); 29387 // Set size of the context data. The contents of context blob is vendor 29388 // defined. In this implementation, the size of context blob is the 29389 // size of a internal session structure plus the size of 29390 // fingerprint plus the size of integrity 29391 out->context.contextBlob.t.size = integritySize + 29392 fingerprintSize + sizeof(*session); 29393 // Copy the whole internal SESSION structure to context blob. 29394 // Save space for fingerprint at the beginning of the buffer 29395 // This is done before anything else so that the actual context 29396 // can be reclaimed after this call 29397 MemoryCopy(out->context.contextBlob.t.buffer 29398 + integritySize + fingerprintSize, 29399 session, sizeof(*session), 29400 29401 Family 2.0 29402 Level 00 Revision 00.99 29403 29404 Published 29405 Copyright TCG 2006-2013 29406 29407 Page 357 29408 October 31, 2013 29409 29410 Part 3: Commands 29412 118 29413 119 29414 120 29415 121 29416 122 29417 123 29418 124 29419 125 29420 126 29421 127 29422 128 29423 129 29424 130 29425 131 29426 132 29427 133 29428 134 29429 135 29430 136 29431 137 29432 138 29433 139 29434 140 29435 141 29436 142 29437 143 29438 144 29439 145 29440 146 29441 147 29442 148 29443 149 29444 150 29445 151 29446 152 29447 153 29448 154 29449 155 29450 156 29451 157 29452 158 29453 159 29454 160 29455 161 29456 162 29457 163 29458 164 29459 165 29460 166 29461 167 29462 168 29463 169 29464 170 29465 171 29466 172 29467 173 29468 174 29469 29470 Trusted Platform Module Library 29471 sizeof(out->context.contextBlob.t.buffer) 29472 - integritySize - fingerprintSize); 29473 29474 // Fill in the other return parameters for a session 29475 // Get a context ID and set the session tracking values appropriately 29476 // TPM_RC_CONTEXT_GAP is a possible error. 29477 // SessionContextSave() will flush the in-memory context 29478 // so no additional errors may occur after this call. 29479 result = SessionContextSave(out->context.savedHandle, &contextID); 29480 if(result != TPM_RC_SUCCESS) return result; 29481 // sequence number is the current session contextID 29482 out->context.sequence = contextID; 29483 // use TPM_RH_NULL as hierarchy for session context 29484 out->context.hierarchy = TPM_RH_NULL; 29485 break; 29486 } 29487 default: 29488 // SaveContext may only take an object handle or a session handle. 29489 // All the other handle type should be filtered out at unmarshal 29490 pAssert(FALSE); 29491 break; 29492 } 29493 // Save fingerprint at the beginning of encrypted area of context blob. 29494 // Reserve the integrity space 29495 MemoryCopy(out->context.contextBlob.t.buffer + integritySize, 29496 &out->context.sequence, sizeof(out->context.sequence), 29497 sizeof(out->context.contextBlob.t.buffer) - integritySize); 29498 // Compute context encryption key 29499 ComputeContextProtectionKey(&out->context, &symKey, &iv); 29500 // Encrypt context blob 29501 CryptSymmetricEncrypt(out->context.contextBlob.t.buffer + integritySize, 29502 CONTEXT_ENCRYPT_ALG, CONTEXT_ENCRYPT_KEY_BITS, 29503 TPM_ALG_CFB, symKey.t.buffer, &iv, 29504 out->context.contextBlob.t.size - integritySize, 29505 out->context.contextBlob.t.buffer + integritySize); 29506 // Compute integrity hash for the object 29507 // In this implementation, the same routine is used for both sessions 29508 // and objects. 29509 ComputeContextIntegrity(&out->context, &integrity); 29510 // add integrity at the beginning of context blob 29511 buffer = out->context.contextBlob.t.buffer; 29512 TPM2B_DIGEST_Marshal(&integrity, &buffer, NULL); 29513 // orderly state should be cleared because of the update of state reset and 29514 // state clear data 29515 g_clearOrderly = TRUE; 29516 return TPM_RC_SUCCESS; 29517 } 29518 29519 Page 358 29520 October 31, 2013 29521 29522 Published 29523 Copyright TCG 2006-2013 29524 29525 Family 2.0 29526 Level 00 Revision 00.99 29527 29528 Trusted Platform Module Library 29530 29531 30.3 29532 29533 Part 3: Commands 29534 29535 TPM2_ContextLoad 29536 29537 30.3.1 General Description 29538 This command is used to reload a context that has been saved by TPM2_ContextSave(). 29539 No authorization sessions of any type are allowed with this command and tag is required to be 29540 TPM_ST_NO_SESSIONS (see note in 30.2.1). 29541 The TPM will return TPM_RC_HIERARCHY if the context is associated with a hierarchy that is disabled. 29542 NOTE 29543 29544 Contexts for authorization sessions and for sequence object s belong to the NULL hierarchy which is 29545 never disabled. 29546 29547 See the Context Data clause in Part 2 for a description of the values in the context parameter. 29548 If the integrity HMAC of the saved context is not valid, the TPM shall return TPM_RC_INTEGRITY. 29549 The TPM shall perform a check on the decrypted context as described in the "Context Confidentiality 29550 Protections" clause of Part 1 and enter failure mode if the check fails. 29551 29552 Family 2.0 29553 Level 00 Revision 00.99 29554 29555 Published 29556 Copyright TCG 2006-2013 29557 29558 Page 359 29559 October 31, 2013 29560 29561 Part 3: Commands 29563 29564 Trusted Platform Module Library 29565 29566 30.3.2 Command and Response 29567 Table 181 TPM2_ContextLoad Command 29568 Type 29569 29570 Name 29571 29572 Description 29573 29574 TPMI_ST_COMMAND_TAG 29575 29576 tag 29577 29578 TPM_ST_NO_SESSIONS 29579 29580 UINT32 29581 29582 commandSize 29583 29584 TPM_CC 29585 29586 commandCode 29587 29588 TPM_CC_ContextLoad 29589 29590 TPMS_CONTEXT 29591 29592 context 29593 29594 the context blob 29595 29596 Table 182 TPM2_ContextLoad Response 29597 Type 29598 29599 Name 29600 29601 Description 29602 29603 TPM_ST 29604 29605 tag 29606 29607 see clause 8 29608 29609 UINT32 29610 29611 responseSize 29612 29613 TPM_RC 29614 29615 responseCode 29616 29617 TPMI_DH_CONTEXT 29618 29619 loadedHandle 29620 29621 Page 360 29622 October 31, 2013 29623 29624 the handle assigned to the resource after it has been 29625 successfully loaded 29626 29627 Published 29628 Copyright TCG 2006-2013 29629 29630 Family 2.0 29631 Level 00 Revision 00.99 29632 29633 Trusted Platform Module Library 29635 29636 Part 3: Commands 29637 29638 30.3.3 Detailed Actions 29639 1 29640 2 29641 3 29642 29643 #include "InternalRoutines.h" 29644 #include "ContextLoad_fp.h" 29645 #include "Context_spt_fp.h" 29646 Error Returns 29647 TPM_RC_CONTEXT_GAP 29648 29649 there is only one available slot and this is not the oldest saved 29650 session context 29651 29652 TPM_RC_HANDLE 29653 29654 'context. savedHandle' does not reference a saved session 29655 29656 TPM_RC_HIERARCHY 29657 29658 'context.hierarchy' is disabled 29659 29660 TPM_RC_INTEGRITY 29661 29662 context integrity check fail 29663 29664 TPM_RC_OBJECT_MEMORY 29665 29666 no free slot for an object 29667 29668 TPM_RC_SESSION_MEMORY 29669 29670 no free session slots 29671 29672 TPM_RC_SIZE 29673 4 29674 5 29675 6 29676 7 29677 8 29678 9 29679 10 29680 11 29681 12 29682 13 29683 14 29684 15 29685 16 29686 17 29687 18 29688 19 29689 20 29690 21 29691 22 29692 23 29693 24 29694 25 29695 26 29696 27 29697 28 29698 29 29699 30 29700 31 29701 32 29702 33 29703 34 29704 35 29705 36 29706 37 29707 38 29708 39 29709 40 29710 41 29711 42 29712 43 29713 29714 Meaning 29715 29716 incorrect context blob size 29717 29718 TPM_RC 29719 TPM2_ContextLoad( 29720 ContextLoad_In 29721 ContextLoad_Out 29722 29723 *in, 29724 *out 29725 29726 // IN: input parameter list 29727 // OUT: output parameter list 29728 29729 ) 29730 { 29731 // Local Variables 29732 TPM_RC 29733 result = TPM_RC_SUCCESS; 29734 TPM2B_DIGEST 29735 TPM2B_DIGEST 29736 UINT16 29737 UINT64 29738 BYTE 29739 INT32 29740 29741 ingerityToCompare; 29742 integrity; 29743 integritySize; 29744 fingerprint; 29745 *buffer; 29746 size; 29747 29748 TPM_HT 29749 TPM2B_SYM_KEY 29750 TPM2B_IV 29751 29752 handleType; 29753 symKey; 29754 iv; 29755 29756 // Input Validation 29757 // Check context blob size 29758 handleType = HandleGetType(in->context.savedHandle); 29759 // Check integrity 29760 // In this implementation, the same routine is used for both sessions 29761 // and objects. 29762 integritySize = sizeof(integrity.t.size) 29763 + CryptGetHashDigestSize(CONTEXT_INTEGRITY_HASH_ALG); 29764 // Get integrity from context blob 29765 buffer = in->context.contextBlob.t.buffer; 29766 size = (INT32) in->context.contextBlob.t.size; 29767 result = TPM2B_DIGEST_Unmarshal(&integrity, &buffer, &size); 29768 if(result != TPM_RC_SUCCESS) 29769 return result; 29770 // Compute context integrity 29771 ComputeContextIntegrity(&in->context, &ingerityToCompare); 29772 29773 Family 2.0 29774 Level 00 Revision 00.99 29775 29776 Published 29777 Copyright TCG 2006-2013 29778 29779 Page 361 29780 October 31, 2013 29781 29782 Part 3: Commands 29784 44 29785 45 29786 46 29787 47 29788 48 29789 49 29790 50 29791 51 29792 52 29793 53 29794 54 29795 55 29796 56 29797 57 29798 58 29799 59 29800 60 29801 61 29802 62 29803 63 29804 64 29805 65 29806 66 29807 67 29808 68 29809 69 29810 70 29811 71 29812 72 29813 73 29814 74 29815 75 29816 76 29817 77 29818 78 29819 79 29820 80 29821 81 29822 82 29823 83 29824 84 29825 85 29826 86 29827 87 29828 88 29829 89 29830 90 29831 91 29832 92 29833 93 29834 94 29835 95 29836 96 29837 97 29838 98 29839 99 29840 100 29841 101 29842 102 29843 103 29844 104 29845 105 29846 106 29847 107 29848 29849 Trusted Platform Module Library 29850 29851 // Compare integrity 29852 if(!Memory2BEqual(&integrity.b, &ingerityToCompare.b)) 29853 return TPM_RC_INTEGRITY + RC_ContextLoad_context; 29854 // Compute context encryption key 29855 ComputeContextProtectionKey(&in->context, &symKey, &iv); 29856 // Decrypt context data in place 29857 CryptSymmetricDecrypt(in->context.contextBlob.t.buffer + integritySize, 29858 CONTEXT_ENCRYPT_ALG, CONTEXT_ENCRYPT_KEY_BITS, 29859 TPM_ALG_CFB, symKey.t.buffer, &iv, 29860 in->context.contextBlob.t.size - integritySize, 29861 in->context.contextBlob.t.buffer + integritySize); 29862 // Read the fingerprint value, skip the leading integrity size 29863 MemoryCopy(&fingerprint, in->context.contextBlob.t.buffer + integritySize, 29864 sizeof(fingerprint), sizeof(fingerprint)); 29865 // Check fingerprint. If the check fails, TPM should be put to failure mode 29866 if(fingerprint != in->context.sequence) 29867 FAIL(FATAL_ERROR_INTERNAL); 29868 // Perform object or session specific input check 29869 switch(handleType) 29870 { 29871 case TPM_HT_TRANSIENT: 29872 { 29873 // Get a pointer to the object in the context blob 29874 OBJECT 29875 *outObject = (OBJECT *)(in->context.contextBlob.t.buffer 29876 + integritySize + sizeof(fingerprint)); 29877 // Discard any changes to the handle that the TRM might have made 29878 in->context.savedHandle = TRANSIENT_FIRST; 29879 // If hierarchy is disabled, no object context can be loaded in this 29880 // hierarchy 29881 if(!HierarchyIsEnabled(in->context.hierarchy)) 29882 return TPM_RC_HIERARCHY + RC_ContextLoad_context; 29883 // Restore object. A TPM_RC_OBJECT_MEMORY error may be returned at 29884 // this point 29885 result = ObjectContextLoad(outObject, &out->loadedHandle); 29886 if(result != TPM_RC_SUCCESS) 29887 return result; 29888 // If this is a sequence object, the crypto library may need to 29889 // reformat the data into an internal format 29890 if(ObjectIsSequence(outObject)) 29891 SequenceDataImportExport(ObjectGet(out->loadedHandle), 29892 outObject, IMPORT_STATE); 29893 break; 29894 } 29895 case TPM_HT_POLICY_SESSION: 29896 case TPM_HT_HMAC_SESSION: 29897 { 29898 SESSION 29899 29900 *session = (SESSION *)(in->context.contextBlob.t.buffer 29901 + integritySize + sizeof(fingerprint)); 29902 29903 // This command may cause the orderlyState to be cleared due to 29904 // the update of state reset data. If this is the case, check if NV is 29905 // available first 29906 29907 Page 362 29908 October 31, 2013 29909 29910 Published 29911 Copyright TCG 2006-2013 29912 29913 Family 2.0 29914 Level 00 Revision 00.99 29915 29916 Trusted Platform Module Library 29918 108 29919 109 29920 110 29921 111 29922 112 29923 113 29924 114 29925 115 29926 116 29927 117 29928 118 29929 119 29930 120 29931 121 29932 122 29933 123 29934 124 29935 125 29936 126 29937 127 29938 128 29939 129 29940 130 29941 131 29942 132 29943 133 29944 134 29945 135 29946 136 29947 137 29948 138 29949 139 29950 140 29951 141 29952 142 29953 143 29954 144 29955 29956 Part 3: Commands 29957 29958 if(gp.orderlyState != SHUTDOWN_NONE) 29959 { 29960 // The command needs NV update. Check if NV is available. 29961 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned 29962 // at this point 29963 result = NvIsAvailable(); 29964 if(result != TPM_RC_SUCCESS) 29965 return result; 29966 } 29967 // Check if input handle points to a valid saved session 29968 if(!SessionIsSaved(in->context.savedHandle)) 29969 return TPM_RC_HANDLE + RC_ContextLoad_context; 29970 // Restore session. A TPM_RC_SESSION_MEMORY, TPM_RC_CONTEXT_GAP error 29971 // may be returned at this point 29972 result = SessionContextLoad(session, &in->context.savedHandle); 29973 if(result != TPM_RC_SUCCESS) 29974 return result; 29975 out->loadedHandle = in->context.savedHandle; 29976 // orderly state should be cleared because of the update of state 29977 // reset and state clear data 29978 g_clearOrderly = TRUE; 29979 break; 29980 } 29981 default: 29982 // Context blob may only have an object handle or a session handle. 29983 // All the other handle type should be filtered out at unmarshal 29984 pAssert(FALSE); 29985 break; 29986 } 29987 return TPM_RC_SUCCESS; 29988 } 29989 29990 Family 2.0 29991 Level 00 Revision 00.99 29992 29993 Published 29994 Copyright TCG 2006-2013 29995 29996 Page 363 29997 October 31, 2013 29998 29999 Part 3: Commands 30001 30002 30.4 30003 30004 Trusted Platform Module Library 30005 30006 TPM2_FlushContext 30007 30008 30.4.1 General Description 30009 This command causes all context associated with a loaded object or session to be removed from TPM 30010 memory. 30011 This command may not be used to remove a persistent object from the TPM. 30012 A session does not have to be loaded in TPM memory to have its context flushed. The saved session 30013 context associated with the indicated handle is invalidated. 30014 No sessions of any type are allowed with 30015 TPM_ST_NO_SESSIONS (see note in 30.2.1). 30016 30017 this 30018 30019 command 30020 30021 and 30022 30023 tag 30024 30025 is 30026 30027 required 30028 30029 to 30030 30031 be 30032 30033 If the handle is for a transient object and the handle is not associated with a loaded object, then the TPM 30034 shall return TPM_RC_HANDLE. 30035 If the handle is for an authorization session and the handle does not reference a loaded or active session, 30036 then the TPM shall return TPM_RC_HANDLE. 30037 NOTE 30038 30039 flushHandle is a parameter and not a handle. If it were in the handle area, the TPM would validate 30040 that the context for the referenced entity is in the TPM. When a TPM2_FlushContext references a 30041 saved session context, it is not necessary for the context to be in the TPM . 30042 30043 Page 364 30044 October 31, 2013 30045 30046 Published 30047 Copyright TCG 2006-2013 30048 30049 Family 2.0 30050 Level 00 Revision 00.99 30051 30052 Trusted Platform Module Library 30054 30055 Part 3: Commands 30056 30057 30.4.2 Command and Response 30058 Table 183 TPM2_FlushContext Command 30059 Type 30060 30061 Name 30062 30063 Description 30064 30065 TPMI_ST_COMMAND_TAG 30066 30067 tag 30068 30069 TPM_ST_NO_SESSIONS 30070 30071 UINT32 30072 30073 commandSize 30074 30075 TPM_CC 30076 30077 commandCode 30078 30079 TPMI_DH_CONTEXT 30080 30081 flushHandle 30082 30083 TPM_CC_FlushContext 30084 the handle of the item to flush 30085 NOTE 30086 30087 This is a use of a handle as a parameter. 30088 30089 Table 184 TPM2_FlushContext Response 30090 Type 30091 30092 Name 30093 30094 Description 30095 30096 TPM_ST 30097 30098 tag 30099 30100 see clause 8 30101 30102 UINT32 30103 30104 responseSize 30105 30106 TPM_RC 30107 30108 responseCode 30109 30110 Family 2.0 30111 Level 00 Revision 00.99 30112 30113 Published 30114 Copyright TCG 2006-2013 30115 30116 Page 365 30117 October 31, 2013 30118 30119 Part 3: Commands 30121 30122 Trusted Platform Module Library 30123 30124 30.4.3 Detailed Actions 30125 1 30126 2 30127 30128 #include "InternalRoutines.h" 30129 #include "FlushContext_fp.h" 30130 Error Returns 30131 TPM_RC_HANDLE 30132 30133 3 30134 4 30135 5 30136 6 30137 7 30138 8 30139 9 30140 10 30141 11 30142 12 30143 13 30144 14 30145 15 30146 16 30147 17 30148 18 30149 19 30150 20 30151 21 30152 22 30153 23 30154 24 30155 25 30156 26 30157 27 30158 28 30159 29 30160 30 30161 31 30162 32 30163 33 30164 34 30165 35 30166 36 30167 37 30168 38 30169 39 30170 40 30171 41 30172 42 30173 30174 Meaning 30175 flushHandle does not reference a loaded object or session 30176 30177 TPM_RC 30178 TPM2_FlushContext( 30179 FlushContext_In 30180 ) 30181 { 30182 // Internal Data Update 30183 30184 *in 30185 30186 // IN: input parameter list 30187 30188 // Call object or session specific routine to flush 30189 switch(HandleGetType(in->flushHandle)) 30190 { 30191 case TPM_HT_TRANSIENT: 30192 if(!ObjectIsPresent(in->flushHandle)) 30193 return TPM_RC_HANDLE; 30194 // Flush object 30195 ObjectFlush(in->flushHandle); 30196 break; 30197 case TPM_HT_HMAC_SESSION: 30198 case TPM_HT_POLICY_SESSION: 30199 if( 30200 !SessionIsLoaded(in->flushHandle) 30201 && !SessionIsSaved(in->flushHandle) 30202 ) 30203 return TPM_RC_HANDLE; 30204 // If the session to be flushed is the exclusive audit session, then 30205 // indicate that there is no exclusive audit session any longer. 30206 if(in->flushHandle == g_exclusiveAuditSession) 30207 g_exclusiveAuditSession = TPM_RH_UNASSIGNED; 30208 // Flush session 30209 SessionFlush(in->flushHandle); 30210 break; 30211 default: 30212 // This command only take object or session handle. 30213 // should be filtered out at handle unmarshal 30214 pAssert(FALSE); 30215 break; 30216 } 30217 30218 Other handles 30219 30220 return TPM_RC_SUCCESS; 30221 } 30222 30223 Page 366 30224 October 31, 2013 30225 30226 Published 30227 Copyright TCG 2006-2013 30228 30229 Family 2.0 30230 Level 00 Revision 00.99 30231 30232 Trusted Platform Module Library 30234 30235 30.5 30236 30237 Part 3: Commands 30238 30239 TPM2_EvictControl 30240 30241 30.5.1 General Description 30242 This command allows a transient object to be made persistent or a persistent object to be evicted. 30243 NOTE 1 30244 30245 A transient object is one that may be removed from TPM memory using either TPM2_FlushContext 30246 or TPM2_Startup(). A persistent object is not removed from TPM memory by TPM2_FlushContext() 30247 or TPM2_Startup(). 30248 30249 If objectHandle is a transient object, then the call is to make the object persistent and assign 30250 persistentHandle to the persistent version of the object. If objectHandle is a persistent object, then the call 30251 is to evict the persistent object. 30252 Before execution of TPM2_EvictControl code below, the TPM verifies that objectHandle references an 30253 object that is resident on the TPM and that persistentHandle is a valid handle for a persistent object. 30254 NOTE 2 30255 30256 This requirement simplifies the unmarshaling code so that it only need check that persistentHandle 30257 is always a persistent object. 30258 30259 If objectHandle references a transient object: 30260 a) The TPM shall return TPM_RC_ATTRIBUTES if 30261 1) it is in the hierarchy of TPM_RH_NULL, 30262 2) only the public portion of the object is loaded, or 30263 3) the stClear is SET in the object or in an ancestor key. 30264 b) The TPM shall return TPM_RC_HIERARCHY if the object is not in the proper hierarchy as 30265 determined by auth. 30266 1) If auth is TPM_RH_PLATFORM, the proper hierarchy is the Platform hierarchy. 30267 2) If auth is TPM_RH_OWNER, the proper hierarchy is either the Storage or the Endorsement 30268 hierarchy. 30269 c) The TPM shall return TPM_RC_RANGE if persistentHandle is not in the proper range as determined 30270 by auth. 30271 1) If auth is TPM_RH_OWNER, then persistentHandle shall be in the inclusive range of 30272 81 00 00 0016 to 81 7F FF FF16. 30273 2) If auth is TPM_RH_PLATFORM, then persistentHandle shall be in the inclusive range of 30274 81 80 00 0016 to 81 FF FF FF16. 30275 d) The TPM shall return TPM_RC_NV_DEFINED if a persistent object exists with the same handle as 30276 persistentHandle. 30277 e) The TPM shall return TPM_RC_NV_SPACE if insufficient space is available to make the object 30278 persistent. 30279 f) 30280 30281 The TPM shall return TPM_RC_NV_SPACE if execution of this command will prevent the TPM from 30282 being able to hold two transient objects of any kind. 30283 NOTE 3 30284 30285 This 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 30286 between memory of different types and it is necessary that the TPM ensure that it is always 30287 possible for the management software to move objects to/from TPM memory in order to ensure 30288 that the objects required for command execution can be context restored. 30289 30290 Family 2.0 30291 Level 00 Revision 00.99 30292 30293 Published 30294 Copyright TCG 2006-2013 30295 30296 Page 367 30297 October 31, 2013 30298 30299 Part 3: Commands 30301 30302 Trusted Platform Module Library 30303 30304 g) If the TPM returns TPM_RC_SUCCESS, the object referenced by objectHandle will not be flushed 30305 and both objectHandle and persistentHandle may be used to access the object. 30306 If objectHandle references a persistent object: 30307 h) The TPM shall return TPM_RC_RANGE if objectHandle is not in the proper range as determined by 30308 auth. If auth is TPM_RC_OWNER, objectHandle shall be in the inclusive range of 81 00 00 0016 to 30309 81 7F FF FF16. If auth is TPM_RC_PLATFORM, objectHandle may be any valid persistent object 30310 handle. 30311 i) 30312 30313 If the TPM returns TPM_RC_SUCCESS, objectHandle will be removed from persistent memory and 30314 no longer be accessible. 30315 30316 NOTE 4 30317 30318 The persistent object is not converted to a transient object, as this would prevent the immediate 30319 revocation of an object by removing it from persistent memory. 30320 30321 Page 368 30322 October 31, 2013 30323 30324 Published 30325 Copyright TCG 2006-2013 30326 30327 Family 2.0 30328 Level 00 Revision 00.99 30329 30330 Trusted Platform Module Library 30332 30333 Part 3: Commands 30334 30335 30.5.2 Command and Response 30336 Table 185 TPM2_EvictControl Command 30337 Type 30338 30339 Name 30340 30341 TPMI_ST_COMMAND_TAG 30342 30343 tag 30344 30345 UINT32 30346 30347 commandSize 30348 30349 TPM_CC 30350 30351 commandCode 30352 30353 TPM_CC_EvictControl {NV} 30354 30355 TPMI_RH_PROVISION 30356 30357 @auth 30358 30359 TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 30360 Auth Handle: 1 30361 Auth Role: USER 30362 30363 TPMI_DH_OBJECT 30364 30365 objectHandle 30366 30367 the handle of a loaded object 30368 Auth Index: None 30369 30370 persistentHandle 30371 30372 if objectHandle is a transient object handle, then this is 30373 the persistent handle for the object 30374 if objectHandle is a persistent object handle, then this 30375 shall be the same value as persistentHandle 30376 30377 TPMI_DH_PERSISTENT 30378 30379 Description 30380 30381 Table 186 TPM2_EvictControl Response 30382 Type 30383 30384 Name 30385 30386 Description 30387 30388 TPM_ST 30389 30390 tag 30391 30392 see clause 8 30393 30394 UINT32 30395 30396 responseSize 30397 30398 TPM_RC 30399 30400 responseCode 30401 30402 Family 2.0 30403 Level 00 Revision 00.99 30404 30405 Published 30406 Copyright TCG 2006-2013 30407 30408 Page 369 30409 October 31, 2013 30410 30411 Part 3: Commands 30413 30414 Trusted Platform Module Library 30415 30416 30.5.3 Detailed Actions 30417 1 30418 2 30419 30420 #include "InternalRoutines.h" 30421 #include "EvictControl_fp.h" 30422 Error Returns 30423 TPM_RC_ATTRIBUTES 30424 30425 an object with temporary, stClear or publicOnly attribute SET cannot 30426 be made persistent 30427 30428 TPM_RC_HIERARCHY 30429 30430 auth cannot authorize the operation in the hierarchy of evictObject 30431 30432 TPM_RC_HANDLE 30433 30434 evictHandle of the persistent object to be evicted is not the same as 30435 the persistentHandle argument 30436 30437 TPM_RC_NV_HANDLE 30438 30439 persistentHandle is unavailable 30440 30441 TPM_RC_NV_SPACE 30442 30443 no space in NV to make evictHandle persistent 30444 30445 TPM_RC_RANGE 30446 30447 3 30448 4 30449 5 30450 6 30451 7 30452 8 30453 9 30454 10 30455 11 30456 12 30457 13 30458 14 30459 15 30460 16 30461 17 30462 18 30463 19 30464 20 30465 21 30466 22 30467 23 30468 24 30469 25 30470 26 30471 27 30472 28 30473 29 30474 30 30475 31 30476 32 30477 33 30478 34 30479 35 30480 36 30481 37 30482 38 30483 39 30484 40 30485 41 30486 42 30487 43 30488 30489 Meaning 30490 30491 persistentHandle is not in the range corresponding to the hierarchy of 30492 evictObject 30493 30494 TPM_RC 30495 TPM2_EvictControl( 30496 EvictControl_In 30497 30498 *in 30499 30500 // IN: input parameter list 30501 30502 ) 30503 { 30504 TPM_RC 30505 OBJECT 30506 30507 result; 30508 *evictObject; 30509 30510 // The command needs NV update. Check if NV is available. 30511 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 30512 // this point 30513 result = NvIsAvailable(); 30514 if(result != TPM_RC_SUCCESS) return result; 30515 // Input Validation 30516 // Get internal object pointer 30517 evictObject = ObjectGet(in->objectHandle); 30518 // Temporary, stClear or public only objects can not be made persistent 30519 if( 30520 evictObject->attributes.temporary == SET 30521 || evictObject->attributes.stClear == SET 30522 || evictObject->attributes.publicOnly == SET 30523 ) 30524 return TPM_RC_ATTRIBUTES + RC_EvictControl_objectHandle; 30525 // If objectHandle refers to a persistent object, it should be the same as 30526 // input persistentHandle 30527 if( 30528 evictObject->attributes.evict == SET 30529 && evictObject->evictHandle != in->persistentHandle 30530 ) 30531 return TPM_RC_HANDLE + RC_EvictControl_objectHandle; 30532 // Additional auth validation 30533 if(in->auth == TPM_RH_PLATFORM) 30534 { 30535 // To make persistent 30536 if(evictObject->attributes.evict == CLEAR) 30537 { 30538 // Platform auth can not set evict object in storage or endorsement 30539 // hierarchy 30540 30541 Page 370 30542 October 31, 2013 30543 30544 Published 30545 Copyright TCG 2006-2013 30546 30547 Family 2.0 30548 Level 00 Revision 00.99 30549 30550 Trusted Platform Module Library 30552 44 30553 45 30554 46 30555 47 30556 48 30557 49 30558 50 30559 51 30560 52 30561 53 30562 54 30563 55 30564 56 30565 57 30566 58 30567 59 30568 60 30569 61 30570 62 30571 63 30572 64 30573 65 30574 66 30575 67 30576 68 30577 69 30578 70 30579 71 30580 72 30581 73 30582 74 30583 75 30584 76 30585 77 30586 78 30587 79 30588 80 30589 81 30590 82 30591 83 30592 84 30593 85 30594 86 30595 87 30596 88 30597 89 30598 90 30599 91 30600 30601 Part 3: Commands 30602 30603 if(evictObject->attributes.ppsHierarchy == CLEAR) 30604 return TPM_RC_HIERARCHY + RC_EvictControl_objectHandle; 30605 // Platform cannot use a handle outside of platform persistent range. 30606 if(!NvIsPlatformPersistentHandle(in->persistentHandle)) 30607 return TPM_RC_RANGE + RC_EvictControl_persistentHandle; 30608 } 30609 // Platform auth can delete any persistent object 30610 } 30611 else if(in->auth == TPM_RH_OWNER) 30612 { 30613 // Owner auth can not set or clear evict object in platform hierarchy 30614 if(evictObject->attributes.ppsHierarchy == SET) 30615 return TPM_RC_HIERARCHY + RC_EvictControl_objectHandle; 30616 // Owner cannot use a handle outside of owner persistent range. 30617 if( 30618 evictObject->attributes.evict == CLEAR 30619 && !NvIsOwnerPersistentHandle(in->persistentHandle) 30620 ) 30621 return TPM_RC_RANGE + RC_EvictControl_persistentHandle; 30622 } 30623 else 30624 { 30625 // Other auth is not allowed in this command and should be filtered out 30626 // at unmarshal process 30627 pAssert(FALSE); 30628 } 30629 // Internal Data Update 30630 // Change evict state 30631 if(evictObject->attributes.evict == CLEAR) 30632 { 30633 // Make object persistent 30634 // A TPM_RC_NV_HANDLE or TPM_RC_NV_SPACE error may be returned at this 30635 // point 30636 result = NvAddEvictObject(in->persistentHandle, evictObject); 30637 if(result != TPM_RC_SUCCESS) return result; 30638 } 30639 else 30640 { 30641 // Delete the persistent object in NV 30642 NvDeleteEntity(evictObject->evictHandle); 30643 } 30644 return TPM_RC_SUCCESS; 30645 } 30646 30647 Family 2.0 30648 Level 00 Revision 00.99 30649 30650 Published 30651 Copyright TCG 2006-2013 30652 30653 Page 371 30654 October 31, 2013 30655 30656 Part 3: Commands 30658 30659 31 30660 30661 Trusted Platform Module Library 30662 30663 Clocks and Timers 30664 30665 31.1 30666 30667 TPM2_ReadClock 30668 30669 31.1.1 General Description 30670 This command reads the current TPMS_TIME_INFO structure that contains the current setting of Time, 30671 Clock, resetCount, and restartCount. 30672 No authorization sessions of any type are allowed with this command and tag is required to be 30673 TPM_ST_NO_SESSIONS. 30674 NOTE 30675 30676 This command is intended to allow the TCB to have access to values that have the potential to be 30677 privacy sensitive. The values may be read without authorization because the TCB will not disclose 30678 these values. Since they are not signed and cannot be accessed in a command that uses an 30679 authorization session, it is not possible for any entity, other than the TCB, to be assured that the 30680 values are accurate. 30681 30682 Page 372 30683 October 31, 2013 30684 30685 Published 30686 Copyright TCG 2006-2013 30687 30688 Family 2.0 30689 Level 00 Revision 00.99 30690 30691 Trusted Platform Module Library 30693 30694 Part 3: Commands 30695 30696 31.1.2 Command and Response 30697 Table 187 TPM2_ReadClock Command 30698 Type 30699 30700 Name 30701 30702 Description 30703 30704 TPMI_ST_COMMAND_TAG 30705 30706 tag 30707 30708 TPM_ST_NO_SESSIONS 30709 30710 UINT32 30711 30712 commandSize 30713 30714 TPM_CC 30715 30716 commandCode 30717 30718 TPM_CC_ReadClock 30719 30720 Table 188 TPM2_ReadClock Response 30721 Type 30722 30723 Name 30724 30725 Description 30726 30727 TPM_ST 30728 30729 tag 30730 30731 see clause 8 30732 30733 UINT32 30734 30735 responseSize 30736 30737 TPM_RC 30738 30739 returnCode 30740 30741 TPMS_TIME_INFO 30742 30743 currentTime 30744 30745 Family 2.0 30746 Level 00 Revision 00.99 30747 30748 Published 30749 Copyright TCG 2006-2013 30750 30751 Page 373 30752 October 31, 2013 30753 30754 Part 3: Commands 30756 30757 Trusted Platform Module Library 30758 30759 31.1.3 Detailed Actions 30760 1 30761 2 30762 3 30763 4 30764 5 30765 6 30766 7 30767 8 30768 9 30769 10 30770 11 30771 12 30772 13 30773 14 30774 30775 #include "InternalRoutines.h" 30776 #include "ReadClock_fp.h" 30777 30778 TPM_RC 30779 TPM2_ReadClock( 30780 ReadClock_Out *out 30781 ) 30782 { 30783 // Command Output 30784 30785 // OUT: output parameter list 30786 30787 out->currentTime.time = g_time; 30788 TimeFillInfo(&out->currentTime.clockInfo); 30789 return TPM_RC_SUCCESS; 30790 } 30791 30792 Page 374 30793 October 31, 2013 30794 30795 Published 30796 Copyright TCG 2006-2013 30797 30798 Family 2.0 30799 Level 00 Revision 00.99 30800 30801 Trusted Platform Module Library 30803 30804 31.2 30805 30806 Part 3: Commands 30807 30808 TPM2_ClockSet 30809 30810 31.2.1 General Description 30811 This command is used to advance the value of the TPMs Clock. The command will fail if newTime is less 30812 than the current value of Clock or if the new time is greater than FF FF 00 00 00 00 00 0016. If both of 30813 these checks succeed, Clock is set to newTime. If either of these checks fails, the TPM shall return 30814 TPM_RC_VALUE and make no change to Clock. 30815 NOTE 30816 30817 This maximum setting would prevent Clock from rolling over to zero for approximately 8,000 years if 30818 the Clock update rate was set so that TPM time was passing 33 percent faster than real time. This 30819 would still be more than 6,000 years before Clock would roll over to zero. Because Clock will not roll 30820 over in the lifetime of the TPM, there is no need for external software to deal with the possibility that 30821 Clock may wrap around. 30822 30823 If the value of Clock after the update makes the volatile and non-volatile versions of 30824 TPMS_CLOCK_INFO.clock differ by more than the reported update interval, then the TPM shall update 30825 the non-volatile version of TPMS_CLOCK_INFO.clock before returning. 30826 This command requires platformAuth or ownerAuth. 30827 30828 Family 2.0 30829 Level 00 Revision 00.99 30830 30831 Published 30832 Copyright TCG 2006-2013 30833 30834 Page 375 30835 October 31, 2013 30836 30837 Part 3: Commands 30839 30840 Trusted Platform Module Library 30841 30842 31.2.2 Command and Response 30843 Table 189 TPM2_ClockSet Command 30844 Type 30845 30846 Name 30847 30848 Description 30849 30850 TPMI_ST_COMMAND_TAG 30851 30852 tag 30853 30854 UINT32 30855 30856 commandSize 30857 30858 TPM_CC 30859 30860 commandCode 30861 30862 TPM_CC_ClockSet {NV} 30863 30864 TPMI_RH_PROVISION 30865 30866 @auth 30867 30868 TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 30869 Auth Handle: 1 30870 Auth Role: USER 30871 30872 UINT64 30873 30874 newTime 30875 30876 new Clock setting in milliseconds 30877 30878 Table 190 TPM2_ClockSet Response 30879 Type 30880 30881 Name 30882 30883 Description 30884 30885 TPM_ST 30886 30887 tag 30888 30889 see clause 8 30890 30891 UINT32 30892 30893 responseSize 30894 30895 TPM_RC 30896 30897 returnCode 30898 30899 Page 376 30900 October 31, 2013 30901 30902 Published 30903 Copyright TCG 2006-2013 30904 30905 Family 2.0 30906 Level 00 Revision 00.99 30907 30908 Trusted Platform Module Library 30910 30911 Part 3: Commands 30912 30913 31.2.3 Detailed Actions 30914 1 30915 2 30916 30917 #include "InternalRoutines.h" 30918 #include "ClockSet_fp.h" 30919 30920 Read the current TPMS_TIMER_INFO structure settings 30921 Error Returns 30922 TPM_RC_VALUE 30923 3 30924 4 30925 5 30926 6 30927 7 30928 8 30929 9 30930 10 30931 11 30932 12 30933 13 30934 14 30935 15 30936 16 30937 17 30938 18 30939 19 30940 20 30941 21 30942 22 30943 23 30944 24 30945 25 30946 26 30947 27 30948 28 30949 29 30950 30 30951 31 30952 32 30953 33 30954 34 30955 35 30956 30957 Meaning 30958 invalid new clock 30959 30960 TPM_RC 30961 TPM2_ClockSet( 30962 ClockSet_In *in 30963 ) 30964 { 30965 #define CLOCK_UPDATE_MASK 30966 UINT64 30967 clockNow; 30968 30969 // IN: input parameter list 30970 ((1ULL << NV_CLOCK_UPDATE_INTERVAL)- 1) 30971 30972 // Input Validation 30973 // new time can not be bigger than 0xFFFF000000000000 or smaller than 30974 // current clock 30975 if(in->newTime > 0xFFFF000000000000ULL 30976 || in->newTime < go.clock) 30977 return TPM_RC_VALUE + RC_ClockSet_newTime; 30978 // Internal Data Update 30979 // Internal Data Update 30980 clockNow = go.clock; 30981 // grab the old value 30982 go.clock = in->newTime; 30983 // set the new value 30984 // Check to see if the update has caused a need for an nvClock update 30985 if((in->newTime & CLOCK_UPDATE_MASK) > (clockNow & CLOCK_UPDATE_MASK)) 30986 { 30987 CryptDrbgGetPutState(GET_STATE); 30988 NvWriteReserved(NV_ORDERLY_DATA, &go); 30989 // Now the time state is safe 30990 go.clockSafe = YES; 30991 } 30992 return TPM_RC_SUCCESS; 30993 } 30994 30995 Family 2.0 30996 Level 00 Revision 00.99 30997 30998 Published 30999 Copyright TCG 2006-2013 31000 31001 Page 377 31002 October 31, 2013 31003 31004 Part 3: Commands 31006 31007 31.3 31008 31009 Trusted Platform Module Library 31010 31011 TPM2_ClockRateAdjust 31012 31013 31.3.1 General Description 31014 This command adjusts the rate of advance of Clock and Time to provide a better approximation to real 31015 time. 31016 The rateAdjust value is relative to the current rate and not the nominal rate of advance. 31017 EXAMPLE 1 31018 31019 If this command had been called three times with rateAdjust = TPM_CLOCK_COARSE_SLOWER 31020 and once with rateAdjust = TPM_CLOCK_COARSE_FASTER, the net effect will be as if the 31021 command had been called twice with rateAdjust = TPM_CLOCK_COARSE_SLOWER. 31022 31023 The range of adjustment shall be sufficient to allow Clock and Time to advance at real time but no more. 31024 If the requested adjustment would make the rate advance faster or slower than the nominal accuracy of 31025 the input frequency, the TPM shall return TPM_RC_VALUE. 31026 EXAMPLE 2 31027 31028 If the frequency tolerance of the TPM's input clock is +/-10 percent, then the TPM will return 31029 TPM_RC_VALUE if the adjustment would make Clock run more than 10 percent faster or slower than 31030 nominal. That is, if the input oscillator were nominally 100 megahertz (MHz), then 1 millisecond (ms) 31031 would normally take 100,000 counts. The update Clock should be adjustable so that 1 ms is between 31032 90,000 and 110,000 counts. 31033 31034 The interpretation of fine and coarse adjustments is implementation-specific. 31035 The nominal rate of advance for Clock and Time shall be accurate to within 15 percent. That is, with no 31036 adjustment applied, Clock and Time shall be advanced at a rate within 15 percent of actual time. 31037 NOTE 31038 31039 If the adjustments are incorrect, it will be possible to m ake the difference between advance of 31040 Clock/Time and real time to be as much as 1.15 2 or ~1.33. 31041 31042 Changes to the current Clock update rate adjustment need not be persisted across TPM power cycles. 31043 31044 Page 378 31045 October 31, 2013 31046 31047 Published 31048 Copyright TCG 2006-2013 31049 31050 Family 2.0 31051 Level 00 Revision 00.99 31052 31053 Trusted Platform Module Library 31055 31056 Part 3: Commands 31057 31058 31.3.2 Command and Response 31059 Table 191 TPM2_ClockRateAdjust Command 31060 Type 31061 31062 Name 31063 31064 Description 31065 31066 TPMI_ST_COMMAND_TAG 31067 31068 tag 31069 31070 UINT32 31071 31072 commandSize 31073 31074 TPM_CC 31075 31076 commandCode 31077 31078 TPM_CC_ClockRateAdjust 31079 31080 TPMI_RH_PROVISION 31081 31082 @auth 31083 31084 TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 31085 Auth Handle: 1 31086 Auth Role: USER 31087 31088 TPM_CLOCK_ADJUST 31089 31090 rateAdjust 31091 31092 Adjustment to current Clock update rate 31093 31094 Table 192 TPM2_ClockRateAdjust Response 31095 Type 31096 31097 Name 31098 31099 Description 31100 31101 TPM_ST 31102 31103 tag 31104 31105 see clause 8 31106 31107 UINT32 31108 31109 responseSize 31110 31111 TPM_RC 31112 31113 returnCode 31114 31115 Family 2.0 31116 Level 00 Revision 00.99 31117 31118 Published 31119 Copyright TCG 2006-2013 31120 31121 Page 379 31122 October 31, 2013 31123 31124 Part 3: Commands 31126 31127 Trusted Platform Module Library 31128 31129 31.3.3 Detailed Actions 31130 1 31131 2 31132 3 31133 4 31134 5 31135 6 31136 7 31137 8 31138 9 31139 10 31140 11 31141 12 31142 31143 #include "InternalRoutines.h" 31144 #include "ClockRateAdjust_fp.h" 31145 31146 TPM_RC 31147 TPM2_ClockRateAdjust( 31148 ClockRateAdjust_In 31149 *in 31150 ) 31151 { 31152 // Internal Data Update 31153 TimeSetAdjustRate(in->rateAdjust); 31154 31155 // IN: input parameter list 31156 31157 return TPM_RC_SUCCESS; 31158 } 31159 31160 Page 380 31161 October 31, 2013 31162 31163 Published 31164 Copyright TCG 2006-2013 31165 31166 Family 2.0 31167 Level 00 Revision 00.99 31168 31169 Trusted Platform Module Library 31171 31172 32 31173 31174 Part 3: Commands 31175 31176 Capability Commands 31177 31178 32.1 31179 31180 Introduction 31181 31182 The TPM has numerous values that indicate the state, capabilities, and properties of the TPM. These 31183 values are needed for proper management of the TPM. The TPM2_GetCapability() command is used to 31184 access these values. 31185 TPM2_GetCapability() allows reporting of multiple values in a single call. The values are grouped 31186 according to type. 31187 NOTE 31188 31189 32.2 31190 31191 TPM2_TestParms()is used to determine if a TPM supports a particular combination of algorithm 31192 parameters 31193 31194 TPM2_GetCapability 31195 31196 32.2.1 General Description 31197 This command returns various information regarding the TPM and its current state. 31198 The capability parameter determines the category of data returned. The property parameter selects the 31199 first value of the selected category to be returned. If there is no property that corresponds to the value of 31200 property, the next higher value is returned, if it exists. 31201 EXAMPLE 1 31202 31203 The list of handles of transient objects currently loaded in the TPM may be read one at a time. On 31204 the first read, set the property to TRANSIENT_FIRST and propertyCount to one. If a transient object 31205 is present, the lowest numbered handle is returned and moreData will be YES if transient objects 31206 with higher handles are loaded. On the subsequent call, use returned handle value plus 1 in order to 31207 access the next higher handle. 31208 31209 The propertyCount parameter indicates the number of capabilities in the indicated group that are 31210 requested. The TPM will return the number of requested values (propertyCount) or until the last property 31211 of the requested type has been returned. 31212 NOTE 1 31213 31214 The type of the capability is determined by a combination of capability and property. 31215 31216 When all of the properties of the requested type have been returned, the moreData parameter in the 31217 response will be set to NO. Otherwise, it will be set to YES. 31218 NOTE 2 31219 31220 The moreData parameter will be YES if there are more properties e ven if the requested number of 31221 capabilities has been returned. 31222 31223 The TPM is not required to return more than one value at a time. It is not required to provide the same 31224 number of values in response to subsequent requests. 31225 EXAMPLE 2 31226 31227 A TPM may return 4 properties in response to a TPM2_GetCapability(capability = 31228 TPM_CAP_TPM_PROPERTY, property = TPM_PT_MANUFACTURER, propertyCount = 8 ) and for a 31229 latter request with the same parameters, the TPM may return as few as one and as many as 8 31230 values. 31231 31232 When the TPM is in Failure mode, a TPM is required to allow use of this command for access of the 31233 following capabilities: 31234 31235 Family 2.0 31236 Level 00 Revision 00.99 31237 31238 Published 31239 Copyright TCG 2006-2013 31240 31241 Page 381 31242 October 31, 2013 31243 31244 Part 3: Commands 31246 31247 Trusted Platform Module Library 31248 31249 31250 31251 TPM_PT_MANUFACTURER 31252 31253 31254 31255 TPM_PT_VENDOR_STRING_1 31256 31257 31258 31259 TPM_PT_VENDOR_STRING_2 31260 31261 (3) 31262 31263 31264 31265 TPM_PT_VENDOR_STRING_3 31266 31267 (3) 31268 31269 31270 31271 TPM_PT_VENDOR_STRING_4 31272 31273 (3) 31274 31275 31276 31277 TPM_PT_VENDOR_TPM_TYPE 31278 31279 31280 31281 TPM_PT_FIRMWARE_VERSION_1 31282 31283 31284 31285 TPM_PT_FIRMWARE_VERSION_2 31286 31287 NOTE 3 31288 31289 If the vendor string does not require one of these values, the property type does not need to exist. 31290 31291 A vendor may optionally allow the TPM to return other values. 31292 If in Failure mode and a capability is requested that is not available in Failure mode, the TPM shall return 31293 no value. 31294 EXAMPLE 3 31295 31296 Assume the TPM is in Failure mode and the TPM only supports reporting of the minimum required 31297 set of properties (the limited set to TPML_TAGGED_PCR_PROPERTY values). If a 31298 TPM2_GetCapability is received requesting a capability that has a property type value greater than 31299 TPM_PT_FIRMWARE_VERSION_2, the TPM will return a zero length list with the moreData 31300 parameter set to NO. If the property type is less than TPM_PT_M ANUFACTURER, the TPM will 31301 return TPM_PT_MANUFACTURER. 31302 31303 In Failure mode, tag is required to be TPM_ST_NO_SESSIONS or the TPM shall return 31304 TPM_RC_FAILURE. 31305 The capability categories and the types of the return values are: 31306 capability 31307 31308 Return Type 31309 31310 property 31311 (1) 31312 31313 TPM_CAP_ALGS 31314 31315 TPM_ALG_ID 31316 31317 TPML_ALG_PROPERTY 31318 31319 TPM_CAP_HANDLES 31320 31321 TPM_HANDLE 31322 31323 TPML_HANDLE 31324 31325 TPM_CAP_COMMANDS 31326 31327 TPM_CC 31328 31329 TPML_CCA 31330 31331 TPM_CAP_PP_COMMANDS 31332 31333 TPM_CC 31334 31335 TPML_CC 31336 31337 TPM_CAP_AUDIT_COMMANDS 31338 31339 TPM_CC 31340 31341 TPML_CC 31342 31343 TPM_CAP_PCRS 31344 31345 Reserved 31346 31347 TPML_PCR_SELECTION 31348 31349 TPM_CAP_TPM_PROPERTIES 31350 31351 TPM_PT 31352 31353 TPML_TAGGED_TPM_PROPERTY 31354 31355 TPM_CAP_PCR_PROPERTIES 31356 31357 TPM_PT_PCR 31358 31359 TPML_TAGGED_PCR_PROPERTY 31360 (1) 31361 31362 TPM_CAP_ECC_CURVE 31363 31364 TPM_ECC_CURVE 31365 31366 TPM_CAP_VENDOR_PROPERTY 31367 31368 manufacturer specific 31369 31370 TPML_ECC_CURVE 31371 manufacturer-specific values 31372 31373 NOTES: 31374 (1) The TPM_ALG_ID or TPM_ECC_CURVE is cast to a UINT32 31375 31376 Page 382 31377 October 31, 2013 31378 31379 Published 31380 Copyright TCG 2006-2013 31381 31382 Family 2.0 31383 Level 00 Revision 00.99 31384 31385 Trusted Platform Module Library 31387 31388 Part 3: Commands 31389 31390 31391 31392 TPM_CAP_ALGS Returns a list of TPMS_ALG_PROPERTIES. Each entry is an algorithm ID and a 31393 set of properties of the algorithm. 31394 31395 31396 31397 TPM_CAP_HANDLES Returns a list of all of the handles within the handle range of the property 31398 parameter. The range of the returned handles is determined by the handle type (the most-significant 31399 octet (MSO) of the property). Any of the defined handle types is allowed 31400 EXAMPLE 4 31401 31402 EXAMPLE 5 31403 31404 31405 31406 If the MSO of property is TPM_HT_NV_INDEX, then the TPM will return a list of NV Index 31407 values. 31408 If the MSO of property is TPM_HT_PCR, then the TPM will return a list of PCR. 31409 31410 For this capability, use of TPM_HT_LOADED_SESSION and TPM_HT_SAVED_SESSION is 31411 allowed. Requesting handles with a handle type of TPM_HT_LOADED_SESSION will return handles 31412 for loaded sessions. The returned handle values will have a handle type of either 31413 TPM_HT_HMAC_SESSION or TPM_HT_POLICY_SESSION. If saved sessions are requested, all 31414 returned values will have the TPM_HT_HMAC_SESSION handle type because the TPM does not 31415 track the session type of saved sessions. 31416 NOTE 2 31417 31418 31419 31420 TPM_HT_LOADED_SESSION and TPM_HT_HMAC_SESSION have the same value, as do 31421 TPM_HT_SAVED_SESSION and TPM_HT_POLICY_SESSION. It is not possible to request that 31422 the TPM return a list of loaded HMAC sessions without including the policy sessions. 31423 31424 TPM_CAP_COMMANDS Returns a list of the command attributes for all of the commands 31425 implemented in the TPM, starting with the TPM_CC indicated by the property parameter. If vendor 31426 specific commands are implemented, the vendor-specific command attribute with the lowest 31427 commandIndex, is returned after the non-vendor-specific (base) command. 31428 NOTE 4 31429 31430 The type of the property parameter is a TPM_CC while the type of the returned list is 31431 TPML_CCA. 31432 31433 31434 31435 TPM_CAP_PP_COMMANDS Returns a list of all of the commands currently requiring Physical 31436 Presence for confirmation of platform authorization. The list will start with the TPM_CC indicated by 31437 property. 31438 31439 31440 31441 TPM_CAP_AUDIT_COMMANDS Returns a list of all of the commands currently set for command 31442 audit. 31443 31444 31445 31446 TPM_CAP_PCRS Returns the current allocation of PCR in a TPML_PCR_SELECTION. The 31447 property parameter shall be zero. The TPM will always respond to this command with the full PCR 31448 allocation and moreData will be NO. 31449 31450 31451 31452 TPM_CAP_TPM_PROPERTIES Returns a list of tagged properties. The tag is a TPM_PT and the 31453 property 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 31454 will only return values in the same group as the property parameter in the command. 31455 31456 31457 31458 TPM_CAP_PCR_PROPERTIES Returns a list of tagged PCR properties. The tag is a 31459 TPM_PT_PCR and the property is a TPMS_PCR_SELECT. 31460 31461 The input command property is a TPM_PT_PCR (see Part 2 for PCR properties to be requested) that 31462 specifies the first property to be returned. If propertyCount is greater than 1, the list of properties begins 31463 with that property and proceeds in TPM_PT_PCR sequence. 31464 NOTE 5 31465 31466 If the propertyCount selects an unimplemented property, the next higher implemented property 31467 is returned. 31468 31469 Each item in the list is a TPMS_PCR_SELECT structure that contains a bitmap of all PCR. 31470 NOTE 6 31471 31472 A PCR index in all banks (all hash algorithms) has the same properties, so the hash algorithm is 31473 not specified here. 31474 31475 Family 2.0 31476 Level 00 Revision 00.99 31477 31478 Published 31479 Copyright TCG 2006-2013 31480 31481 Page 383 31482 October 31, 2013 31483 31484 Part 3: Commands 31486 31487 31488 Trusted Platform Module Library 31489 31490 TPM_CAP_TPM_ECC_CURVES Returns a list of ECC curve identifiers currently available for use 31491 in the TPM. 31492 31493 The moreData parameter will have a value of YES if there are more values of the requested type that 31494 were not returned. 31495 If no next capability exists, the TPM will return a zero-length list and moreData will have a value of NO. 31496 31497 Page 384 31498 October 31, 2013 31499 31500 Published 31501 Copyright TCG 2006-2013 31502 31503 Family 2.0 31504 Level 00 Revision 00.99 31505 31506 Trusted Platform Module Library 31508 31509 Part 3: Commands 31510 31511 32.2.2 Command and Response 31512 Table 193 TPM2_GetCapability Command 31513 Type 31514 31515 Name 31516 31517 Description 31518 31519 TPMI_ST_COMMAND_TAG 31520 31521 tag 31522 31523 UINT32 31524 31525 commandSize 31526 31527 TPM_CC 31528 31529 commandCode 31530 31531 TPM_CC_GetCapability 31532 31533 TPM_CAP 31534 31535 capability 31536 31537 group selection; determines the format of the response 31538 31539 UINT32 31540 31541 property 31542 31543 further definition of information 31544 31545 UINT32 31546 31547 propertyCount 31548 31549 number of properties of the indicated type to return 31550 31551 Table 194 TPM2_GetCapability Response 31552 Type 31553 31554 Name 31555 31556 Description 31557 31558 TPM_ST 31559 31560 tag 31561 31562 see clause 8 31563 31564 UINT32 31565 31566 responseSize 31567 31568 TPM_RC 31569 31570 responseCode 31571 31572 TPMI_YES_NO 31573 31574 moreData 31575 31576 flag to indicate if there are more values of this type 31577 31578 TPMS_CAPABILITY_DATA 31579 31580 capabilityData 31581 31582 the capability data 31583 31584 Family 2.0 31585 Level 00 Revision 00.99 31586 31587 Published 31588 Copyright TCG 2006-2013 31589 31590 Page 385 31591 October 31, 2013 31592 31593 Part 3: Commands 31595 31596 Trusted Platform Module Library 31597 31598 32.2.3 Detailed Actions 31599 1 31600 2 31601 31602 #include "InternalRoutines.h" 31603 #include "GetCapability_fp.h" 31604 Error Returns 31605 TPM_RC_HANDLE 31606 31607 value of property is in an unsupported handle range for the 31608 TPM_CAP_HANDLES capability value 31609 31610 TPM_RC_VALUE 31611 31612 3 31613 4 31614 5 31615 6 31616 7 31617 8 31618 9 31619 10 31620 11 31621 12 31622 13 31623 14 31624 15 31625 16 31626 17 31627 18 31628 19 31629 20 31630 21 31631 22 31632 23 31633 24 31634 25 31635 26 31636 27 31637 28 31638 29 31639 30 31640 31 31641 32 31642 33 31643 34 31644 35 31645 36 31646 37 31647 38 31648 39 31649 40 31650 41 31651 42 31652 43 31653 44 31654 45 31655 46 31656 47 31657 48 31658 49 31659 50 31660 51 31661 31662 Meaning 31663 31664 invalid capability; or property is not 0 for the TPM_CAP_PCRS 31665 capability value 31666 31667 TPM_RC 31668 TPM2_GetCapability( 31669 GetCapability_In 31670 GetCapability_Out 31671 31672 *in, 31673 *out 31674 31675 // IN: input parameter list 31676 // OUT: output parameter list 31677 31678 ) 31679 { 31680 // Command Output 31681 // Set output capability type the same as input type 31682 out->capabilityData.capability = in->capability; 31683 switch(in->capability) 31684 { 31685 case TPM_CAP_ALGS: 31686 out->moreData = AlgorithmCapGetImplemented((TPM_ALG_ID) in->property, 31687 in->propertyCount, &out->capabilityData.data.algorithms); 31688 break; 31689 case TPM_CAP_HANDLES: 31690 switch(HandleGetType((TPM_HANDLE) in->property)) 31691 { 31692 case TPM_HT_TRANSIENT: 31693 // Get list of handles of loaded transient objects 31694 out->moreData = ObjectCapGetLoaded((TPM_HANDLE) in->property, 31695 in->propertyCount, 31696 &out->capabilityData.data.handles); 31697 break; 31698 case TPM_HT_PERSISTENT: 31699 // Get list of handles of persistent objects 31700 out->moreData = NvCapGetPersistent((TPM_HANDLE) in->property, 31701 in->propertyCount, 31702 &out->capabilityData.data.handles); 31703 break; 31704 case TPM_HT_NV_INDEX: 31705 // Get list of defined NV index 31706 out->moreData = NvCapGetIndex((TPM_HANDLE) in->property, 31707 in->propertyCount, 31708 &out->capabilityData.data.handles); 31709 break; 31710 case TPM_HT_LOADED_SESSION: 31711 // Get list of handles of loaded sessions 31712 out->moreData = SessionCapGetLoaded((TPM_HANDLE) in->property, 31713 in->propertyCount, 31714 &out->capabilityData.data.handles); 31715 break; 31716 case TPM_HT_ACTIVE_SESSION: 31717 // Get list of handles of 31718 out->moreData = SessionCapGetSaved((TPM_HANDLE) in->property, 31719 in->propertyCount, 31720 &out->capabilityData.data.handles); 31721 31722 Page 386 31723 October 31, 2013 31724 31725 Published 31726 Copyright TCG 2006-2013 31727 31728 Family 2.0 31729 Level 00 Revision 00.99 31730 31731 Trusted Platform Module Library 31733 52 31734 53 31735 54 31736 55 31737 56 31738 57 31739 58 31740 59 31741 60 31742 61 31743 62 31744 63 31745 64 31746 65 31747 66 31748 67 31749 68 31750 69 31751 70 31752 71 31753 72 31754 73 31755 74 31756 75 31757 76 31758 77 31759 78 31760 79 31761 80 31762 81 31763 82 31764 83 31765 84 31766 85 31767 86 31768 87 31769 88 31770 89 31771 90 31772 91 31773 92 31774 93 31775 94 31776 95 31777 96 31778 97 31779 98 31780 99 31781 100 31782 101 31783 102 31784 103 31785 104 31786 105 31787 106 31788 107 31789 108 31790 109 31791 110 31792 111 31793 112 31794 113 31795 114 31796 115 31797 31798 Part 3: Commands 31799 31800 break; 31801 case TPM_HT_PCR: 31802 // Get list of handles of PCR 31803 out->moreData = PCRCapGetHandles((TPM_HANDLE) in->property, 31804 in->propertyCount, 31805 &out->capabilityData.data.handles); 31806 break; 31807 case TPM_HT_PERMANENT: 31808 // Get list of permanent handles 31809 out->moreData = PermanentCapGetHandles( 31810 (TPM_HANDLE) in->property, 31811 in->propertyCount, 31812 &out->capabilityData.data.handles); 31813 break; 31814 default: 31815 // Unsupported input handle type 31816 return TPM_RC_HANDLE + RC_GetCapability_property; 31817 break; 31818 } 31819 break; 31820 case TPM_CAP_COMMANDS: 31821 out->moreData = CommandCapGetCCList((TPM_CC) in->property, 31822 in->propertyCount, 31823 &out->capabilityData.data.command); 31824 break; 31825 case TPM_CAP_PP_COMMANDS: 31826 out->moreData = PhysicalPresenceCapGetCCList((TPM_CC) in->property, 31827 in->propertyCount, &out->capabilityData.data.ppCommands); 31828 break; 31829 case TPM_CAP_AUDIT_COMMANDS: 31830 out->moreData = CommandAuditCapGetCCList((TPM_CC) in->property, 31831 in->propertyCount, 31832 &out->capabilityData.data.auditCommands); 31833 break; 31834 case TPM_CAP_PCRS: 31835 // Input property must be 0 31836 if(in->property != 0) 31837 return TPM_RC_VALUE + RC_GetCapability_property; 31838 out->moreData = PCRCapGetAllocation(in->propertyCount, 31839 &out->capabilityData.data.assignedPCR); 31840 break; 31841 case TPM_CAP_PCR_PROPERTIES: 31842 out->moreData = PCRCapGetProperties((TPM_PT_PCR) in->property, 31843 in->propertyCount, 31844 &out->capabilityData.data.pcrProperties); 31845 break; 31846 case TPM_CAP_TPM_PROPERTIES: 31847 out->moreData = TPMCapGetProperties((TPM_PT) in->property, 31848 in->propertyCount, 31849 &out->capabilityData.data.tpmProperties); 31850 break; 31851 #ifdef TPM_ALG_ECC 31852 case TPM_CAP_ECC_CURVES: 31853 out->moreData = CryptCapGetECCCurve((TPM_ECC_CURVE 31854 ) in->property, 31855 in->propertyCount, 31856 &out->capabilityData.data.eccCurves); 31857 break; 31858 #endif // TPM_ALG_ECC 31859 case TPM_CAP_VENDOR_PROPERTY: 31860 // vendor property is not implemented 31861 default: 31862 // Unexpected TPM_CAP value 31863 return TPM_RC_VALUE; 31864 break; 31865 31866 Family 2.0 31867 Level 00 Revision 00.99 31868 31869 Published 31870 Copyright TCG 2006-2013 31871 31872 Page 387 31873 October 31, 2013 31874 31875 Part 3: Commands 31877 116 31878 117 31879 118 31880 119 31881 31882 Trusted Platform Module Library 31883 31884 } 31885 return TPM_RC_SUCCESS; 31886 } 31887 31888 Page 388 31889 October 31, 2013 31890 31891 Published 31892 Copyright TCG 2006-2013 31893 31894 Family 2.0 31895 Level 00 Revision 00.99 31896 31897 Trusted Platform Module Library 31899 31900 32.3 31901 31902 Part 3: Commands 31903 31904 TPM2_TestParms 31905 31906 32.3.1 General Description 31907 This command is used to check to see if specific combinations of algorithm parameters are supported. 31908 The TPM will unmarshal the provided TPMT_PUBLIC_PARMS. If the parameters unmarshal correctly, 31909 then the TPM will return TPM_RC_SUCCESS, indicating that the parameters are valid for the TPM. The 31910 TPM will return the appropriate unmarshaling error if a parameter is not valid. 31911 31912 Family 2.0 31913 Level 00 Revision 00.99 31914 31915 Published 31916 Copyright TCG 2006-2013 31917 31918 Page 389 31919 October 31, 2013 31920 31921 Part 3: Commands 31923 31924 Trusted Platform Module Library 31925 31926 32.3.2 Command and Response 31927 Table 195 TPM2_TestParms Command 31928 Type 31929 31930 Name 31931 31932 Description 31933 31934 TPMI_ST_COMMAND_TAG 31935 31936 tag 31937 31938 UINT32 31939 31940 commandSize 31941 31942 TPM_CC 31943 31944 commandCode 31945 31946 TPM_CC_TestParms 31947 31948 TPMT_PUBLIC_PARMS 31949 31950 parameters 31951 31952 algorithm parameters to be validated 31953 31954 Table 196 TPM2_TestParms Response 31955 Type 31956 31957 Name 31958 31959 Description 31960 31961 TPM_ST 31962 31963 tag 31964 31965 see clause 8 31966 31967 UINT32 31968 31969 responseSize 31970 31971 TPM_RC 31972 31973 responseCode 31974 31975 Page 390 31976 October 31, 2013 31977 31978 TPM_RC 31979 31980 Published 31981 Copyright TCG 2006-2013 31982 31983 Family 2.0 31984 Level 00 Revision 00.99 31985 31986 Trusted Platform Module Library 31988 31989 Part 3: Commands 31990 31991 32.3.3 Detailed Actions 31992 1 31993 2 31994 3 31995 4 31996 5 31997 6 31998 7 31999 8 32000 9 32001 10 32002 11 32003 12 32004 13 32005 14 32006 32007 #include "InternalRoutines.h" 32008 #include "TestParms_fp.h" 32009 32010 TPM_RC 32011 TPM2_TestParms( 32012 TestParms_In 32013 32014 *in 32015 32016 // IN: input parameter list 32017 32018 ) 32019 { 32020 // Input parameter is not reference in command action 32021 in = NULL; 32022 // The parameters are tested at unmarshal process. 32023 // action 32024 return TPM_RC_SUCCESS; 32025 32026 We do nothing in command 32027 32028 } 32029 32030 Family 2.0 32031 Level 00 Revision 00.99 32032 32033 Published 32034 Copyright TCG 2006-2013 32035 32036 Page 391 32037 October 31, 2013 32038 32039 Part 3: Commands 32041 32042 33 32043 32044 Trusted Platform Module Library 32045 32046 Non-volatile Storage 32047 32048 33.1 32049 32050 Introduction 32051 32052 The NV commands are used to create, update, read, and delete allocations of space in NV memory. 32053 Before an Index may be used, it must be defined (TPM2_NV_DefineSpace()). 32054 An Index may be modified if the proper write authorization is provided or read if the proper read 32055 authorization is provided. Different controls are available for reading and writing. 32056 An Index may have an Index-specific authValue and authPolicy. The authValue may be used to authorize 32057 reading if TPMA_NV_AUTHREAD is SET and writing if TPMA_NV_AUTHREAD is SET. The authPolicy 32058 may be used to authorize reading if TPMA_NV_POLICYREAD is SET and writing if 32059 TPMA_NV_POLICYWRITE is SET. 32060 TPMA_NV_PPREAD and TPMA_NV_PPWRITE indicate if reading or writing of the NV Index may be 32061 authorized by platformAuth or platformPolicy. 32062 TPMA_NV_OWNERREAD and TPMA_NV_OWNERWRITE indicate if reading or writing of the NV Index 32063 may be authorized by ownerAuth or ownerPolicy. 32064 If an operation on an NV index requires authorization, and the authHandle parameter is the handle of an 32065 NV Index, then the nvIndex parameter must have the same value or the TPM will return 32066 TPM_RC_NV_AUTHORIZATION. 32067 NOTE 1 32068 32069 This check ensures that the authorization that was provided is associated with the NV Index being 32070 authorized. 32071 32072 For creating an Index, ownerAuth may not be used if shEnable is CLEAR and platformAuth may not be 32073 used if phEnableNV is CLEAR. 32074 If an Index was defined using platformAuth, then that Index is not accessible when phEnableNV is 32075 CLEAR. If an Index was defined using ownerAuth, then that Index is not accessible when shEnable is 32076 CLEAR. 32077 For read access control, any combination of TPMA_NV_PPREAD, TPMA_NV_OWNERREAD, 32078 TPMA_NV_AUTHREAD, or TPMA_NV_POLICYREAD is allowed as long as at least one is SET. 32079 For write access control, any combination of TPMA_NV_PPWRITE, TPMA_NV_OWNERWRITE, 32080 TPMA_NV_AUTHWRITE, or TPMA_NV_POLICYWRITE is allowed as long as at least one is SET. 32081 If an Index has been defined and not written, then any operation on the NV Index that requires read 32082 authorization will fail (TPM_RC_NV_INITIALIZED). This check may be made before or after other 32083 authorization checks but shall be performed before checking the NV Index authValue. An authorization 32084 failure due to the NV Index not having been written shall not be logged by the dictionary attack logic. 32085 If TPMA_NV_CLEAR_STCLEAR is SET, then the TPMA_NV_WRITTEN will be CLEAR on each 32086 TPM2_Startup(TPM_SU_CLEAR). 32087 TPMA_NV_CLEAR_STCLEAR 32088 shall 32089 not 32090 be 32091 SET 32092 if 32093 TPMA_NV_COUNTER is SET. 32094 The 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 32095 structure of the NV data. 32096 Only one NV Index may be directly referenced in a command. 32097 NOTE 2 32098 32099 This means that, if authHandle references an NV Index, then nvIndex will have the same value. 32100 However, this does not limit the number of changes that may occur as side effects. For example, any 32101 number of NV Indexes might be relocated as a result of deleting or adding a NV Ind ex. 32102 32103 Page 392 32104 October 31, 2013 32105 32106 Published 32107 Copyright TCG 2006-2013 32108 32109 Family 2.0 32110 Level 00 Revision 00.99 32111 32112 Trusted Platform Module Library 32114 32115 33.2 32116 32117 Part 3: Commands 32118 32119 NV Counters 32120 32121 When an Index has the TPMA_NV_COUNTER attribute set, it behaves as a monotonic counter and may 32122 only be updated using TPM2_NV_Increment(). 32123 When an NV counter is created, the TPM shall initialize the 8-octet counter value with a number that is 32124 greater than any count value for any NV counter on the TPM since the time of TPM manufacture. 32125 An NV counter may be defined with the TPMA_NV_ORDERLY attribute to indicate that the NV Index is 32126 expected to be modified at a high frequency and that the data is only required to persist when the TPM 32127 goes through an orderly shutdown process. The TPM may update the counter value in RAM and 32128 occasionally update the non-volatile version of the counter. An orderly shutdown is one occasion to 32129 update the non-volatile count. If the difference between the volatile and non-volatile version of the counter 32130 becomes as large as MAX_ORDERLY_COUNT, this shall be another occasion for updating the nonvolatile count. 32131 Before an NV counter can be used, the TPM shall validate that the count is not less than a previously 32132 reported value. If the TPMA_NV_ORDERLY attribute is not SET, or if the TPM experienced an orderly 32133 shutdown, then the count is assumed to be correct. If the TPMA_NV_ORDERLY attribute is SET, and the 32134 TPM shutdown was not orderly, then the TPM shall OR MAX_ORDERLY_COUNT to the contents of the 32135 non-volatile counter and set that as the current count. 32136 NOTE 1 32137 32138 Because the TPM would have updated the NV Index if the difference between the count values was 32139 equal to MAX_ORDERLY_COUNT + 1, the highest value that could have been in the NV Index is 32140 MAX_ORDERLY_COUNT so it is safe to restore that value. 32141 32142 NOTE 2 32143 32144 The TPM may implement the RAM portion of the counter such that the effective value of the NV 32145 counter is the sum of both the volatile and non-volatile parts. If so, then the TPM may initialize the 32146 RAM version of the counter to MAX_ORDERLY_COUNT and no update of NV is necessary. 32147 32148 NOTE 3 32149 32150 When a new NV counter is created, the TPM may search all the counters to determine which has the 32151 highest value. In this search, the TPM would use the sum of the non -volatile and RAM portions of 32152 the counter. The RAM portion of the counter shall be properly initialized to reflect shutdown p rocess 32153 (orderly or not) of the TPM. 32154 32155 Family 2.0 32156 Level 00 Revision 00.99 32157 32158 Published 32159 Copyright TCG 2006-2013 32160 32161 Page 393 32162 October 31, 2013 32163 32164 Part 3: Commands 32166 32167 33.3 32168 32169 Trusted Platform Module Library 32170 32171 TPM2_NV_DefineSpace 32172 32173 33.3.1 General Description 32174 This command defines the attributes of an NV Index and causes the TPM to reserve space to hold the 32175 data associated with the NV Index. If a definition already exists at the NV Index, the TPM will return 32176 TPM_RC_NV_DEFINED. 32177 The TPM will return TPM_RC_ATTRIBUTES if more 32178 TPMA_NV_BITS, or TPMA_NV_EXTEND is SET in publicInfo. 32179 NOTE 32180 32181 than 32182 32183 one 32184 32185 of 32186 32187 TPMA_NV_COUNTER, 32188 32189 It is not required that any of these three attributes be set. 32190 32191 The TPM shall return TPM_RC_ATTRIBUTES if TPMA_NV_WRITTEN, TPM_NV_READLOCKED, or 32192 TPMA_NV_WRITELOCKED is SET. 32193 If TPMA_NV_COUNTER or TPMA_NV_BITS is SET, then publicInfodataSize shall be set to eight (8) or 32194 the TPM shall return TPM_RC_SIZE. 32195 If TPMA_NV_EXTEND is SET, then publicInfodataSize shall match the digest size of the 32196 publicInfo.nameAlg or the TPM shall return TPM_RC_SIZE. 32197 If the NV Index is an ordinary Index and publicInfodataSize is larger than supported by the TPM 32198 implementation then the TPM shall return TPM_RC_SIZE. 32199 NOTE 32200 32201 The limit for the data size may vary according to the type of the index. For example, if the index is 32202 has TPMA_NV_ORDERLY SET, then the maximum size of an ordin ary NV Index may be less than 32203 the size of an ordinary NV Index that has TPMA_NV_ORDERLY CLEAR. 32204 32205 At least one of TPMA_NV_PPREAD, TPMA_NV_OWNERREAD, TPMA_NV_AUTHREAD, 32206 TPMA_NV_POLICYREAD shall be SET or the TPM shall return TPM_RC_ATTRIBUTES. 32207 32208 or 32209 32210 At least one of TPMA_NV_PPWRITE, TPMA_NV_OWNERWRITE, TPMA_NV_AUTHWRITE, or 32211 TPMA_NV_POLICYWRITE shall be SET or the TPM shall return TPM_RC_ATTRIBUTES. 32212 If TPMA_NV_CLEAR_STCLEAR is SET, then TPMA_NV_COUNTER shall be CLEAR or the TPM shall 32213 return TPM_RC_ATTRIBUTES. 32214 If platformAuth/platformPolicy is used for authorization, then TPMA_NV_PLATFORMCREATE shall be 32215 SET in publicInfo. If ownerAuth/ownerPolicy is used for authorization, TPMA_NV_PLATFORMCREATE 32216 shall be CLEAR in publicInfo. If TPMA_NV_PLATFORMCREATE is not set correctly for the authorization, 32217 the TPM shall return TPM_RC_ATTRIBUTES. 32218 If TPMA_NV_POLICY_DELETE is SET, then the authorization shall be with platformAuth or the TPM 32219 shall return TPM_RC_ATTRIBUTES. 32220 If the implementation does not support TPM2_NV_Increment(), 32221 TPM_RC_ATTRIBUTES if TPMA_NV_COUNTER is SET. 32222 32223 the 32224 32225 TPM 32226 32227 shall 32228 32229 return 32230 32231 If the implementation does not support TPM2_NV_SetBits(), 32232 TPM_RC_ATTRIBUTES if TPMA_NV_BITS is SET. 32233 32234 the 32235 32236 TPM 32237 32238 shall 32239 32240 return 32241 32242 If the implementation does not support TPM2_NV_Extend(), 32243 TPM_RC_ATTRIBUTES if TPMA_NV_EXTEND is SET. 32244 32245 the 32246 32247 TPM 32248 32249 shall 32250 32251 return 32252 32253 If the implementation does not support TPM2_NV_UndefineSpaceSpecial(), the TPM shall return 32254 TPM_RC_ATTRIBUTES if TPMA_NV_POLICY_DELETE is SET. 32255 After the successful completion of this command, the NV Index exists but TPMA_NV_WRITTEN will be 32256 CLEAR. Any access of the NV data will return TPM_RC_NV_UINITIALIZED. 32257 32258 Page 394 32259 October 31, 2013 32260 32261 Published 32262 Copyright TCG 2006-2013 32263 32264 Family 2.0 32265 Level 00 Revision 00.99 32266 32267 Trusted Platform Module Library 32269 32270 Part 3: Commands 32271 32272 In some implementations, an NV Index with the TPMA_NV_COUNTER attribute may require special TPM 32273 resources that provide higher endurance than regular NV. For those implementations, if this command 32274 fails because of lack of resources, the TPM will return TPM_RC_NV_SPACE. 32275 The value of auth is saved in the created structure. The size of auth is limited to be no larger than the size 32276 of the digest produced by the NV Index's nameAlg (TPM_RC_SIZE). 32277 32278 Family 2.0 32279 Level 00 Revision 00.99 32280 32281 Published 32282 Copyright TCG 2006-2013 32283 32284 Page 395 32285 October 31, 2013 32286 32287 Part 3: Commands 32289 32290 Trusted Platform Module Library 32291 32292 33.3.2 Command and Response 32293 Table 197 TPM2_NV_DefineSpace Command 32294 Type 32295 32296 Name 32297 32298 Description 32299 32300 TPMI_ST_COMMAND_TAG 32301 32302 tag 32303 32304 UINT32 32305 32306 commandSize 32307 32308 TPM_CC 32309 32310 commandCode 32311 32312 TPM_CC_NV_DefineSpace {NV} 32313 32314 TPMI_RH_PROVISION 32315 32316 @authHandle 32317 32318 TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 32319 Auth Index: 1 32320 Auth Role: USER 32321 32322 TPM2B_AUTH 32323 32324 auth 32325 32326 the authorization value 32327 32328 TPM2B_NV_PUBLIC 32329 32330 publicInfo 32331 32332 the public parameters of the NV area 32333 32334 Table 198 TPM2_NV_DefineSpace Response 32335 Type 32336 32337 Name 32338 32339 Description 32340 32341 TPM_ST 32342 32343 tag 32344 32345 see clause 8 32346 32347 UINT32 32348 32349 responseSize 32350 32351 TPM_RC 32352 32353 responseCode 32354 32355 Page 396 32356 October 31, 2013 32357 32358 Published 32359 Copyright TCG 2006-2013 32360 32361 Family 2.0 32362 Level 00 Revision 00.99 32363 32364 Trusted Platform Module Library 32366 32367 Part 3: Commands 32368 32369 33.3.3 Detailed Actions 32370 1 32371 2 32372 32373 #include "InternalRoutines.h" 32374 #include "NV_DefineSpace_fp.h" 32375 Error Returns 32376 TPM_RC_NV_ATTRIBUTES 32377 32378 attributes of the index are not consistent 32379 32380 TPM_RC_NV_DEFINED 32381 32382 index already exists 32383 32384 TPM_RC_HIERARCHY 32385 32386 for authorizations using TPM_RH_PLATFORM phEnable_NV is 32387 clear. 32388 32389 TPM_RC_NV_SPACE 32390 32391 Insufficient space for the index 32392 32393 TPM_RC_SIZE 32394 32395 3 32396 4 32397 5 32398 6 32399 7 32400 8 32401 9 32402 10 32403 11 32404 12 32405 13 32406 14 32407 15 32408 16 32409 17 32410 18 32411 19 32412 20 32413 21 32414 22 32415 23 32416 24 32417 25 32418 26 32419 27 32420 28 32421 29 32422 30 32423 31 32424 32 32425 33 32426 34 32427 35 32428 36 32429 37 32430 38 32431 39 32432 40 32433 41 32434 42 32435 43 32436 44 32437 32438 Meaning 32439 32440 'auth->size' or 'publicInfo->authPolicy. size' is larger than the digest 32441 size of 'publicInfo->nameAlg', or 'publicInfo->dataSize' is not 32442 consistent with 'publicInfo->attributes'. 32443 32444 TPM_RC 32445 TPM2_NV_DefineSpace( 32446 NV_DefineSpace_In 32447 32448 *in 32449 32450 // IN: input parameter list 32451 32452 ) 32453 { 32454 TPM_RC 32455 TPMA_NV 32456 UINT16 32457 32458 result; 32459 attributes; 32460 nameSize; 32461 32462 nameSize = CryptGetHashDigestSize(in->publicInfo.t.nvPublic.nameAlg); 32463 // Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE 32464 // TPM_RC_NV_RATE or TPM_RC_SUCCESS. 32465 result = NvIsAvailable(); 32466 if(result != TPM_RC_SUCCESS) 32467 return result; 32468 // Input Validation 32469 // If an index is being created by the owner and shEnable is 32470 // clear, then we would not reach this point because ownerAuth 32471 // can't be given when shEnable is CLEAR. However, if phEnable 32472 // is SET but phEnableNV is CLEAR, we have to check here 32473 if(in->authHandle == TPM_RH_PLATFORM && gc.phEnableNV == CLEAR) 32474 return TPM_RC_HIERARCHY + RC_NV_DefineSpace_authHandle; 32475 attributes = in->publicInfo.t.nvPublic.attributes; 32476 //TPMS_NV_PUBLIC validation. 32477 // Counters and bit fields must have a size of 8 32478 if ( 32479 (attributes.TPMA_NV_COUNTER == SET || attributes.TPMA_NV_BITS == SET) 32480 && (in->publicInfo.t.nvPublic.dataSize != 8)) 32481 return TPM_RC_SIZE + RC_NV_DefineSpace_publicInfo; 32482 // check that the authPolicy consistent with hash algorithm 32483 if( 32484 in->publicInfo.t.nvPublic.authPolicy.t.size != 0 32485 && in->publicInfo.t.nvPublic.authPolicy.t.size != nameSize) 32486 return TPM_RC_SIZE + RC_NV_DefineSpace_publicInfo; 32487 // make sure that the authValue is not too large 32488 MemoryRemoveTrailingZeros(&in->auth); 32489 if(in->auth.t.size > nameSize) 32490 return TPM_RC_SIZE + RC_NV_DefineSpace_auth; 32491 32492 Family 2.0 32493 Level 00 Revision 00.99 32494 32495 Published 32496 Copyright TCG 2006-2013 32497 32498 Page 397 32499 October 31, 2013 32500 32501 Part 3: Commands 32503 45 32504 46 32505 47 32506 48 32507 49 32508 50 32509 51 32510 52 32511 53 32512 54 32513 55 32514 56 32515 57 32516 58 32517 59 32518 60 32519 61 32520 62 32521 63 32522 64 32523 65 32524 66 32525 67 32526 68 32527 69 32528 70 32529 71 32530 72 32531 73 32532 74 32533 75 32534 76 32535 77 32536 78 32537 79 32538 80 32539 81 32540 82 32541 83 32542 84 32543 85 32544 86 32545 87 32546 88 32547 89 32548 90 32549 91 32550 92 32551 93 32552 94 32553 95 32554 96 32555 97 32556 98 32557 99 32558 100 32559 101 32560 102 32561 103 32562 104 32563 105 32564 106 32565 107 32566 108 32567 32568 Trusted Platform Module Library 32569 32570 //TPMA_NV validation. 32571 // Locks may not be SET and written cannot be SET 32572 if( 32573 attributes.TPMA_NV_WRITTEN == SET 32574 || attributes.TPMA_NV_WRITELOCKED == SET 32575 || attributes.TPMA_NV_READLOCKED == SET) 32576 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32577 // There must be a way to read the index 32578 if( 32579 attributes.TPMA_NV_OWNERREAD == CLEAR 32580 && attributes.TPMA_NV_PPREAD == CLEAR 32581 && attributes.TPMA_NV_AUTHREAD == CLEAR 32582 && attributes.TPMA_NV_POLICYREAD == CLEAR) 32583 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32584 // There must be a way to write the index 32585 if( 32586 attributes.TPMA_NV_OWNERWRITE == CLEAR 32587 && attributes.TPMA_NV_PPWRITE == CLEAR 32588 && attributes.TPMA_NV_AUTHWRITE == CLEAR 32589 && attributes.TPMA_NV_POLICYWRITE == CLEAR) 32590 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32591 // Make sure that no attribute is used that is not supported by the proper 32592 // command 32593 #if CC_NV_Increment == NO 32594 if( attributes.TPMA_NV_COUNTER == SET) 32595 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32596 #endif 32597 #if CC_NV_SetBits == NO 32598 if( attributes.TPMA_NV_BITS == SET) 32599 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32600 #endif 32601 #if CC_NV_Extend == NO 32602 if( attributes.TPMA_NV_EXTEND == SET) 32603 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32604 #endif 32605 #if CC_NV_UndefineSpaceSpecial == NO 32606 if( attributes.TPMA_NV_POLICY_DELETE == SET) 32607 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32608 #endif 32609 // Can be COUNTER or BITS or EXTEND but not more than one 32610 if( attributes.TPMA_NV_COUNTER == SET 32611 && attributes.TPMA_NV_BITS == SET) 32612 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32613 if( 32614 attributes.TPMA_NV_COUNTER == SET 32615 && attributes.TPMA_NV_EXTEND == SET) 32616 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32617 if( 32618 attributes.TPMA_NV_BITS == SET 32619 && attributes.TPMA_NV_EXTEND == SET) 32620 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32621 // An index with TPMA_NV_CLEAR_STCLEAR can't be a counter 32622 if( 32623 attributes.TPMA_NV_CLEAR_STCLEAR == SET 32624 && attributes.TPMA_NV_COUNTER == SET) 32625 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32626 // The index is allowed to have one of GLOBALLOCK or WRITEDEFINE SET 32627 if( 32628 attributes.TPMA_NV_GLOBALLOCK == SET 32629 && attributes.TPMA_NV_WRITEDEFINE == SET) 32630 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32631 // Make sure that the creator of the index can delete the index 32632 32633 Page 398 32634 October 31, 2013 32635 32636 Published 32637 Copyright TCG 2006-2013 32638 32639 Family 2.0 32640 Level 00 Revision 00.99 32641 32642 Trusted Platform Module Library 32644 109 32645 110 32646 111 32647 112 32648 113 32649 114 32650 115 32651 116 32652 117 32653 118 32654 119 32655 120 32656 121 32657 122 32658 123 32659 124 32660 125 32661 126 32662 127 32663 128 32664 129 32665 130 32666 131 32667 132 32668 133 32669 134 32670 135 32671 136 32672 137 32673 138 32674 139 32675 140 32676 141 32677 142 32678 143 32679 144 32680 32681 if( 32682 32683 Part 3: Commands 32684 32685 ( 32686 32687 in->publicInfo.t.nvPublic.attributes.TPMA_NV_PLATFORMCREATE == SET 32688 && in->authHandle == TPM_RH_OWNER 32689 ) 32690 || ( 32691 in->publicInfo.t.nvPublic.attributes.TPMA_NV_PLATFORMCREATE == CLEAR 32692 && in->authHandle == TPM_RH_PLATFORM 32693 ) 32694 ) 32695 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_authHandle; 32696 32697 // If TPMA_NV_POLICY_DELETE is SET, then the index must be defined by 32698 // the platform 32699 if( 32700 in->publicInfo.t.nvPublic.attributes.TPMA_NV_POLICY_DELETE == SET 32701 && TPM_RH_PLATFORM != in->authHandle 32702 ) 32703 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32704 // If the NV index is used as a PCR, the data size must match the digest 32705 // size 32706 if( 32707 in->publicInfo.t.nvPublic.attributes.TPMA_NV_EXTEND == SET 32708 && in->publicInfo.t.nvPublic.dataSize != nameSize 32709 ) 32710 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32711 // See if the index is already defined. 32712 if(NvIsUndefinedIndex(in->publicInfo.t.nvPublic.nvIndex)) 32713 return TPM_RC_NV_DEFINED; 32714 // Internal Data Update 32715 // define the space. A TPM_RC_NV_SPACE error may be returned at this point 32716 result = NvDefineIndex(&in->publicInfo.t.nvPublic, &in->auth); 32717 if(result != TPM_RC_SUCCESS) 32718 return result; 32719 return TPM_RC_SUCCESS; 32720 } 32721 32722 Family 2.0 32723 Level 00 Revision 00.99 32724 32725 Published 32726 Copyright TCG 2006-2013 32727 32728 Page 399 32729 October 31, 2013 32730 32731 Part 3: Commands 32733 32734 33.4 32735 32736 Trusted Platform Module Library 32737 32738 TPM2_NV_UndefineSpace 32739 32740 33.4.1 General Description 32741 This command removes an Index from the TPM. 32742 If nvIndex is not defined, the TPM shall return TPM_RC_HANDLE. 32743 If nvIndex references an Index that has its TPMA_NV_PLATFORMCREATE attribute SET, the TPM shall 32744 return TPM_RC_NV_AUTHORITY unless platformAuth is provided. 32745 NOTE 32746 32747 An Index with TPMA_NV_PLATFORMCREATE CLEAR may be deleted with platformAuth as long as 32748 shEnable is SET. If shEnable is CLEAR, indexes created using ownerAuth are not accessible even 32749 for deletion by the platform. 32750 32751 Page 400 32752 October 31, 2013 32753 32754 Published 32755 Copyright TCG 2006-2013 32756 32757 Family 2.0 32758 Level 00 Revision 00.99 32759 32760 Trusted Platform Module Library 32762 32763 Part 3: Commands 32764 32765 33.4.2 Command and Response 32766 Table 199 TPM2_NV_UndefineSpace Command 32767 Type 32768 32769 Name 32770 32771 Description 32772 32773 TPMI_ST_COMMAND_TAG 32774 32775 tag 32776 32777 UINT32 32778 32779 commandSize 32780 32781 TPM_CC 32782 32783 commandCode 32784 32785 TPM_CC_NV_UndefineSpace {NV} 32786 32787 TPMI_RH_PROVISION 32788 32789 @authHandle 32790 32791 TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 32792 Auth Index: 1 32793 Auth Role: USER 32794 32795 TPMI_RH_NV_INDEX 32796 32797 nvIndex 32798 32799 the NV Index to remove from NV space 32800 Auth Index: None 32801 32802 Table 200 TPM2_NV_UndefineSpace Response 32803 Type 32804 32805 Name 32806 32807 Description 32808 32809 TPM_ST 32810 32811 tag 32812 32813 see clause 8 32814 32815 UINT32 32816 32817 responseSize 32818 32819 TPM_RC 32820 32821 responseCode 32822 32823 Family 2.0 32824 Level 00 Revision 00.99 32825 32826 Published 32827 Copyright TCG 2006-2013 32828 32829 Page 401 32830 October 31, 2013 32831 32832 Part 3: Commands 32834 32835 Trusted Platform Module Library 32836 32837 33.4.3 Detailed Actions 32838 1 32839 2 32840 32841 #include "InternalRoutines.h" 32842 #include "NV_UndefineSpace_fp.h" 32843 Error Returns 32844 TPM_RC_ATTRIBUTES 32845 32846 TPMA_NV_POLICY_DELETE is SET in the Index referenced by 32847 nvIndex so this command may not be used to delete this Index (see 32848 TPM2_NV_UndefineSpaceSpecial()) 32849 32850 TPM_RC_NV_AUTHORIZATION 32851 3 32852 4 32853 5 32854 6 32855 7 32856 8 32857 9 32858 10 32859 11 32860 12 32861 13 32862 14 32863 15 32864 16 32865 17 32866 18 32867 19 32868 20 32869 21 32870 22 32871 23 32872 24 32873 25 32874 26 32875 27 32876 28 32877 29 32878 30 32879 31 32880 32 32881 33 32882 34 32883 35 32884 36 32885 37 32886 38 32887 32888 Meaning 32889 32890 attempt to use ownerAuth to delete an index created by the platform 32891 32892 TPM_RC 32893 TPM2_NV_UndefineSpace( 32894 NV_UndefineSpace_In *in 32895 32896 // IN: input parameter list 32897 32898 ) 32899 { 32900 TPM_RC 32901 NV_INDEX 32902 32903 result; 32904 nvIndex; 32905 32906 // The command needs NV update. Check if NV is available. 32907 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 32908 // this point 32909 result = NvIsAvailable(); 32910 if(result != TPM_RC_SUCCESS) return result; 32911 // Input Validation 32912 // Get NV index info 32913 NvGetIndexInfo(in->nvIndex, &nvIndex); 32914 // This command can't be used to delete an index with TPMA_NV_POLICY_DELETE SET 32915 if(SET == nvIndex.publicArea.attributes.TPMA_NV_POLICY_DELETE) 32916 return TPM_RC_ATTRIBUTES + RC_NV_UndefineSpace_nvIndex; 32917 // The owner may only delete an index that was defined with ownerAuth. The 32918 // platform may delete an index that was created with either auth. 32919 if( 32920 in->authHandle == TPM_RH_OWNER 32921 && nvIndex.publicArea.attributes.TPMA_NV_PLATFORMCREATE == SET) 32922 return TPM_RC_NV_AUTHORIZATION; 32923 // Internal Data Update 32924 // Call implementation dependent internal routine to delete NV index 32925 NvDeleteEntity(in->nvIndex); 32926 return TPM_RC_SUCCESS; 32927 } 32928 32929 Page 402 32930 October 31, 2013 32931 32932 Published 32933 Copyright TCG 2006-2013 32934 32935 Family 2.0 32936 Level 00 Revision 00.99 32937 32938 Trusted Platform Module Library 32940 32941 33.5 32942 32943 Part 3: Commands 32944 32945 TPM2_NV_UndefineSpaceSpecial 32946 32947 33.5.1 General Description 32948 This command allows removal of a platform-created NV Index that has TPMA_NV_POLICY_DELETE 32949 SET. 32950 This command requires that the policy of the NV Index be satisfied before the NV Index may be deleted. 32951 Because administrative role is required, the policy must contain a command that sets the policy command 32952 code to TPM_CC_NV_UndefineSpaceSpecial. This indicates that the policy that is being used is a policy 32953 that is for this command, and not a policy that would approve another use. That is, authority to use an 32954 object does not grant authority to undefined the object. 32955 If nvIndex is not defined, the TPM shall return TPM_RC_HANDLE. 32956 If 32957 nvIndex 32958 references 32959 an 32960 Index 32961 that 32962 has 32963 its 32964 TPMA_NV_PLATFORMCREATE 32965 TPMA_NV_POLICY_DELETE attribute CLEAR, the TPM shall return TPM_RC_NV_ATTRIBUTES. 32966 NOTE 32967 32968 or 32969 32970 An 32971 Index 32972 with 32973 TPMA_NV_PLATFORMCREATE 32974 CLEAR 32975 may 32976 be 32977 deleted 32978 with 32979 TPM2_UndefineSpace()as long as shEnable is SET. If shEnable is CLEAR, indexes created using 32980 ownerAuth are not accessible even for deletion by the platform . 32981 32982 Family 2.0 32983 Level 00 Revision 00.99 32984 32985 Published 32986 Copyright TCG 2006-2013 32987 32988 Page 403 32989 October 31, 2013 32990 32991 Part 3: Commands 32993 32994 Trusted Platform Module Library 32995 32996 33.5.2 Command and Response 32997 Table 201 TPM2_NV_UndefineSpaceSpecial Command 32998 Type 32999 33000 Name 33001 33002 Description 33003 33004 TPMI_ST_COMMAND_TAG 33005 33006 tag 33007 33008 UINT32 33009 33010 commandSize 33011 33012 TPM_CC 33013 33014 commandCode 33015 33016 TPM_CC_NV_UndefineSpaceSpecial {NV} 33017 33018 TPMI_RH_NV_INDEX 33019 33020 @nvIndex 33021 33022 Index to be deleted 33023 Auth Index: 1 33024 Auth Role: ADMIN 33025 33026 TPMI_RH_PLATFORM 33027 33028 @platform 33029 33030 TPM_RH_PLATFORM + {PP} 33031 Auth Index: 2 33032 Auth Role: USER 33033 33034 Table 202 TPM2_NV_UndefineSpaceSpecial Response 33035 Type 33036 33037 Name 33038 33039 Description 33040 33041 TPM_ST 33042 33043 tag 33044 33045 see clause 8 33046 33047 UINT32 33048 33049 responseSize 33050 33051 TPM_RC 33052 33053 responseCode 33054 33055 Page 404 33056 October 31, 2013 33057 33058 Published 33059 Copyright TCG 2006-2013 33060 33061 Family 2.0 33062 Level 00 Revision 00.99 33063 33064 Trusted Platform Module Library 33066 33067 Part 3: Commands 33068 33069 33.5.3 Detailed Actions 33070 1 33071 2 33072 33073 #include "InternalRoutines.h" 33074 #include "NV_UndefineSpaceSpecial_fp.h" 33075 Error Returns 33076 TPM_RC_ATTRIBUTES 33077 33078 3 33079 4 33080 5 33081 6 33082 7 33083 8 33084 9 33085 10 33086 11 33087 12 33088 13 33089 14 33090 15 33091 16 33092 17 33093 18 33094 19 33095 20 33096 21 33097 22 33098 23 33099 24 33100 25 33101 26 33102 27 33103 28 33104 29 33105 30 33106 31 33107 32 33108 33 33109 33110 Meaning 33111 TPMA_NV_POLICY_DELETE is not SET in the Index referenced by 33112 nvIndex 33113 33114 TPM_RC 33115 TPM2_NV_UndefineSpaceSpecial( 33116 NV_UndefineSpaceSpecial_In *in 33117 33118 // IN: input parameter list 33119 33120 ) 33121 { 33122 TPM_RC 33123 NV_INDEX 33124 33125 result; 33126 nvIndex; 33127 33128 // The command needs NV update. Check if NV is available. 33129 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 33130 // this point 33131 result = NvIsAvailable(); 33132 if(result != TPM_RC_SUCCESS) 33133 return result; 33134 // Input Validation 33135 // Get NV index info 33136 NvGetIndexInfo(in->nvIndex, &nvIndex); 33137 // This operation only applies when the TPMA_NV_POLICY_DELETE attribute is SET 33138 if(CLEAR == nvIndex.publicArea.attributes.TPMA_NV_POLICY_DELETE) 33139 return TPM_RC_ATTRIBUTES + RC_NV_UndefineSpaceSpecial_nvIndex; 33140 // Internal Data Update 33141 // Call implementation dependent internal routine to delete NV index 33142 NvDeleteEntity(in->nvIndex); 33143 return TPM_RC_SUCCESS; 33144 } 33145 33146 Family 2.0 33147 Level 00 Revision 00.99 33148 33149 Published 33150 Copyright TCG 2006-2013 33151 33152 Page 405 33153 October 31, 2013 33154 33155 Part 3: Commands 33157 33158 33.6 33159 33160 Trusted Platform Module Library 33161 33162 TPM2_NV_ReadPublic 33163 33164 33.6.1 General Description 33165 This command is used to read the public area and Name of an NV Index. The public area of an Index is 33166 not privacy-sensitive and no authorization is required to read this data. 33167 33168 Page 406 33169 October 31, 2013 33170 33171 Published 33172 Copyright TCG 2006-2013 33173 33174 Family 2.0 33175 Level 00 Revision 00.99 33176 33177 Trusted Platform Module Library 33179 33180 Part 3: Commands 33181 33182 33.6.2 Command and Response 33183 Table 203 TPM2_NV_ReadPublic Command 33184 Type 33185 33186 Name 33187 33188 Description 33189 33190 TPMI_ST_COMMAND_TAG 33191 33192 tag 33193 33194 UINT32 33195 33196 commandSize 33197 33198 TPM_CC 33199 33200 commandCode 33201 33202 TPM_CC_NV_ReadPublic 33203 33204 TPMI_RH_NV_INDEX 33205 33206 nvIndex 33207 33208 the NV Index 33209 Auth Index: None 33210 33211 Table 204 TPM2_NV_ReadPublic Response 33212 Type 33213 33214 Name 33215 33216 Description 33217 33218 TPM_ST 33219 33220 tag 33221 33222 see clause 8 33223 33224 UINT32 33225 33226 responseSize 33227 33228 TPM_RC 33229 33230 responseCode 33231 33232 TPM2B_NV_PUBLIC 33233 33234 nvPublic 33235 33236 the public area of the NV Index 33237 33238 TPM2B_NAME 33239 33240 nvName 33241 33242 the Name of the nvIndex 33243 33244 Family 2.0 33245 Level 00 Revision 00.99 33246 33247 Published 33248 Copyright TCG 2006-2013 33249 33250 Page 407 33251 October 31, 2013 33252 33253 Part 3: Commands 33255 33256 Trusted Platform Module Library 33257 33258 33.6.3 Detailed Actions 33259 1 33260 2 33261 3 33262 4 33263 5 33264 6 33265 7 33266 8 33267 9 33268 10 33269 11 33270 12 33271 13 33272 14 33273 15 33274 16 33275 17 33276 18 33277 19 33278 20 33279 21 33280 22 33281 23 33282 33283 #include "InternalRoutines.h" 33284 #include "NV_ReadPublic_fp.h" 33285 33286 TPM_RC 33287 TPM2_NV_ReadPublic( 33288 NV_ReadPublic_In 33289 NV_ReadPublic_Out 33290 33291 *in, 33292 *out 33293 33294 // IN: input parameter list 33295 // OUT: output parameter list 33296 33297 ) 33298 { 33299 NV_INDEX 33300 33301 nvIndex; 33302 33303 // Command Output 33304 // Get NV index info 33305 NvGetIndexInfo(in->nvIndex, &nvIndex); 33306 // Copy data to output 33307 out->nvPublic.t.nvPublic = nvIndex.publicArea; 33308 // Compute NV name 33309 out->nvName.t.size = NvGetName(in->nvIndex, &out->nvName.t.name); 33310 return TPM_RC_SUCCESS; 33311 } 33312 33313 Page 408 33314 October 31, 2013 33315 33316 Published 33317 Copyright TCG 2006-2013 33318 33319 Family 2.0 33320 Level 00 Revision 00.99 33321 33322 Trusted Platform Module Library 33324 33325 33.7 33326 33327 Part 3: Commands 33328 33329 TPM2_NV_Write 33330 33331 33.7.1 General Description 33332 This command writes a value to an area in NV memory that was previously defined by 33333 TPM2_NV_DefineSpace(). 33334 Proper authorizations are required for this command as determined by TPMA_NV_PPWRITE; 33335 TPMA_NV_OWNERWRITE; TPMA_NV_AUTHWRITE; and, if TPMA_NV_POLICY_WRITE is SET, the 33336 authPolicy of the NV Index. 33337 If the TPMA_NV_WRITELOCKED attribute of the NV Index is SET, then the TPM shall return 33338 TPM_RC_NV_LOCKED. 33339 NOTE 1 33340 33341 If authorization sessions are present, they are checked before checks to see if writes to the NV 33342 Index are locked. 33343 33344 If TPMA_NV_COUNTER, TPMA_NV_BITS or TPMA_NV_EXTEND of the NV Index is SET, then the 33345 TPM shall return TPM_RC_NV_ATTRIBUTE. 33346 If the size of the data parameter plus the offset parameter adds to a value that is greater than the size of 33347 the NV Index data, the TPM shall return TPM_RC_NV_RANGE and not write any data to the NV Index. 33348 If the TPMA_NV_WRITEALL attribute of the NV Index is SET, then the TPM shall return 33349 TPM_RC_NV_RANGE if the size of the data parameter of the command is not the same as the data field 33350 of the NV Index. 33351 If all checks succeed, the TPM will merge the data.size octets of data.buffer value into the nvIndexdata 33352 starting at nvIndexdata[offset]. If the NV memory is implemented with a technology that has endurance 33353 limitations, the TPM shall check that the merged data is different from the current contents of the NV 33354 Index and only perform a write to NV memory if they differ. 33355 After successful completion of this command, TPMA_NV_WRITTEN for the NV Index will be SET. 33356 NOTE 2 33357 33358 Once SET, TPMA_NV_WRITTEN remains SET until the NV Index is undefined or the NV Index is 33359 cleared. 33360 33361 Family 2.0 33362 Level 00 Revision 00.99 33363 33364 Published 33365 Copyright TCG 2006-2013 33366 33367 Page 409 33368 October 31, 2013 33369 33370 Part 3: Commands 33372 33373 Trusted Platform Module Library 33374 33375 33.7.2 Command and Response 33376 Table 205 TPM2_NV_Write Command 33377 Type 33378 33379 Name 33380 33381 Description 33382 33383 TPMI_ST_COMMAND_TAG 33384 33385 tag 33386 33387 UINT32 33388 33389 commandSize 33390 33391 TPM_CC 33392 33393 commandCode 33394 33395 TPM_CC_NV_Write {NV} 33396 33397 TPMI_RH_NV_AUTH 33398 33399 @authHandle 33400 33401 handle indicating the source of the authorization value 33402 Auth Index: 1 33403 Auth Role: USER 33404 33405 TPMI_RH_NV_INDEX 33406 33407 nvIndex 33408 33409 the NV Index of the area to write 33410 Auth Index: None 33411 33412 TPM2B_MAX_NV_BUFFER 33413 33414 data 33415 33416 the data to write 33417 33418 UINT16 33419 33420 offset 33421 33422 the offset into the NV Area 33423 33424 Table 206 TPM2_NV_Write Response 33425 Type 33426 33427 Name 33428 33429 Description 33430 33431 TPM_ST 33432 33433 tag 33434 33435 see clause 8 33436 33437 UINT32 33438 33439 responseSize 33440 33441 TPM_RC 33442 33443 responseCode 33444 33445 Page 410 33446 October 31, 2013 33447 33448 Published 33449 Copyright TCG 2006-2013 33450 33451 Family 2.0 33452 Level 00 Revision 00.99 33453 33454 Trusted Platform Module Library 33456 33457 Part 3: Commands 33458 33459 33.7.3 Detailed Actions 33460 1 33461 2 33462 3 33463 33464 #include "InternalRoutines.h" 33465 #include "NV_Write_fp.h" 33466 #include "NV_spt_fp.h" 33467 Error Returns 33468 TPM_RC_ATTRIBUTES 33469 33470 Index referenced by nvIndex has either TPMA_NV_BITS, 33471 TPMA_NV_COUNTER, or TPMA_NV_EVENT attribute SET 33472 33473 TPM_RC_NV_AUTHORIZATION 33474 33475 the authorization was valid but the authorizing entity (authHandle) is 33476 not allowed to write to the Index referenced by nvIndex 33477 33478 TPM_RC_NV_LOCKED 33479 33480 Index referenced by nvIndex is write locked 33481 33482 TPM_RC_NV_RANGE 33483 33484 4 33485 5 33486 6 33487 7 33488 8 33489 9 33490 10 33491 11 33492 12 33493 13 33494 14 33495 15 33496 16 33497 17 33498 18 33499 19 33500 20 33501 21 33502 22 33503 23 33504 24 33505 25 33506 26 33507 27 33508 28 33509 29 33510 30 33511 31 33512 32 33513 33 33514 34 33515 35 33516 36 33517 37 33518 38 33519 39 33520 40 33521 41 33522 42 33523 43 33524 44 33525 45 33526 33527 Meaning 33528 33529 if TPMA_NV_WRITEALL is SET then the write is not the size of the 33530 Index referenced by nvIndex; otherwise, the write extends beyond the 33531 limits of the Index 33532 33533 TPM_RC 33534 TPM2_NV_Write( 33535 NV_Write_In 33536 33537 *in 33538 33539 // IN: input parameter list 33540 33541 ) 33542 { 33543 NV_INDEX 33544 TPM_RC 33545 33546 nvIndex; 33547 result; 33548 33549 // Input Validation 33550 // Get NV index info 33551 NvGetIndexInfo(in->nvIndex, &nvIndex); 33552 // common access checks. NvWrtieAccessChecks() may return 33553 // TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED 33554 result = NvWriteAccessChecks(in->authHandle, in->nvIndex); 33555 if(result != TPM_RC_SUCCESS) 33556 return result; 33557 // Bits index, extend index or counter index may not be updated by 33558 // TPM2_NV_Write 33559 if( 33560 nvIndex.publicArea.attributes.TPMA_NV_COUNTER == SET 33561 || nvIndex.publicArea.attributes.TPMA_NV_BITS == SET 33562 || nvIndex.publicArea.attributes.TPMA_NV_EXTEND == SET) 33563 return TPM_RC_ATTRIBUTES; 33564 // Too much data 33565 if((in->data.t.size + in->offset) > nvIndex.publicArea.dataSize) 33566 return TPM_RC_NV_RANGE; 33567 // If this index requires a full sized write, make sure that input range is 33568 // full sized 33569 if( 33570 nvIndex.publicArea.attributes.TPMA_NV_WRITEALL == SET 33571 && in->data.t.size < nvIndex.publicArea.dataSize) 33572 return TPM_RC_NV_RANGE; 33573 // Internal Data Update 33574 // Perform the write. This called routine will SET the TPMA_NV_WRITTEN 33575 // attribute if it has not already been SET. If NV isn't available, an error 33576 // will be returned. 33577 return NvWriteIndexData(in->nvIndex, &nvIndex, in->offset, 33578 33579 Family 2.0 33580 Level 00 Revision 00.99 33581 33582 Published 33583 Copyright TCG 2006-2013 33584 33585 Page 411 33586 October 31, 2013 33587 33588 Part 3: Commands 33590 46 33591 47 33592 48 33593 33594 Trusted Platform Module Library 33595 in->data.t.size, in->data.t.buffer); 33596 33597 } 33598 33599 Page 412 33600 October 31, 2013 33601 33602 Published 33603 Copyright TCG 2006-2013 33604 33605 Family 2.0 33606 Level 00 Revision 00.99 33607 33608 Trusted Platform Module Library 33610 33611 33.8 33612 33613 Part 3: Commands 33614 33615 TPM2_NV_Increment 33616 33617 33.8.1 General Description 33618 This command is used to increment the value in an NV Index that has TPMA_NV_COUNTER SET. The 33619 data value of the NV Index is incremented by one. 33620 NOTE 1 33621 33622 The NV Index counter is an unsigned value. 33623 33624 If TPMA_NV_COUNTER 33625 TPM_RC_ATTRIBUTES. 33626 33627 is 33628 33629 not 33630 33631 SET 33632 33633 in 33634 33635 the 33636 33637 indicated 33638 33639 NV 33640 33641 Index, 33642 33643 the 33644 33645 TPM 33646 33647 shall 33648 33649 return 33650 33651 If TPMA_NV_WRITELOCKED is SET, the TPM shall return TPM_RC_NV_LOCKED. 33652 If TPMA_NV_WRITTEN is CLEAR, it will be SET. 33653 If TPMA_NV_ORDERLY is SET, and the difference between the volatile and non-volatile versions of this 33654 field is greater than MAX_ORDERLY_COUNT, then the non-volatile version of the counter is updated. 33655 NOTE 2 33656 33657 If a TPM implements TPMA_NV_ORDERLY and an Index is defined with TPMA_NV_ORDERLY and 33658 TPM_NV_COUNTER both SET, then in the Event of a non-orderly shutdown, the non-volatile value 33659 for the counter Index will be advanced by MAX_ORDERLY_COUNT at the next TPM2_Startup(). 33660 33661 NOTE 3 33662 33663 An allowed implementation would keep a counter value in NV and a resettable counter in RAM. The 33664 reported value of the NV Index would be the sum of the two values. When the RAM count increments 33665 past the maximum allowed value (MAX_ORDERLY_COUNT), the non-volatile version of the count is 33666 updated with the sum of the values and the RAM count is reset to zero. 33667 33668 Family 2.0 33669 Level 00 Revision 00.99 33670 33671 Published 33672 Copyright TCG 2006-2013 33673 33674 Page 413 33675 October 31, 2013 33676 33677 Part 3: Commands 33679 33680 Trusted Platform Module Library 33681 33682 33.8.2 Command and Response 33683 Table 207 TPM2_NV_Increment Command 33684 Type 33685 33686 Name 33687 33688 Description 33689 33690 TPMI_ST_COMMAND_TAG 33691 33692 tag 33693 33694 UINT32 33695 33696 commandSize 33697 33698 TPM_CC 33699 33700 commandCode 33701 33702 TPM_CC_NV_Increment {NV} 33703 33704 TPMI_RH_NV_AUTH 33705 33706 @authHandle 33707 33708 handle indicating the source of the authorization value 33709 Auth Index: 1 33710 Auth Role: USER 33711 33712 TPMI_RH_NV_INDEX 33713 33714 nvIndex 33715 33716 the NV Index to increment 33717 Auth Index: None 33718 33719 Table 208 TPM2_NV_Increment Response 33720 Type 33721 33722 Name 33723 33724 Description 33725 33726 TPM_ST 33727 33728 tag 33729 33730 see clause 8 33731 33732 UINT32 33733 33734 responseSize 33735 33736 TPM_RC 33737 33738 responseCode 33739 33740 Page 414 33741 October 31, 2013 33742 33743 Published 33744 Copyright TCG 2006-2013 33745 33746 Family 2.0 33747 Level 00 Revision 00.99 33748 33749 Trusted Platform Module Library 33751 33752 Part 3: Commands 33753 33754 33.8.3 Detailed Actions 33755 1 33756 2 33757 3 33758 33759 #include "InternalRoutines.h" 33760 #include "NV_Increment_fp.h" 33761 #include "NV_spt_fp.h" 33762 Error Returns 33763 TPM_RC_ATTRIBUTES 33764 33765 NV index is not a counter 33766 33767 TPM_RC_NV_AUTHORIZATION 33768 33769 authorization failure 33770 33771 TPM_RC_NV_LOCKED 33772 4 33773 5 33774 6 33775 7 33776 8 33777 9 33778 10 33779 11 33780 12 33781 13 33782 14 33783 15 33784 16 33785 17 33786 18 33787 19 33788 20 33789 21 33790 22 33791 23 33792 24 33793 25 33794 26 33795 27 33796 28 33797 29 33798 30 33799 31 33800 32 33801 33 33802 34 33803 35 33804 36 33805 37 33806 38 33807 39 33808 40 33809 41 33810 42 33811 43 33812 44 33813 45 33814 46 33815 47 33816 48 33817 49 33818 50 33819 51 33820 33821 Meaning 33822 33823 Index is write locked 33824 33825 TPM_RC 33826 TPM2_NV_Increment( 33827 NV_Increment_In 33828 33829 *in 33830 33831 // IN: input parameter list 33832 33833 ) 33834 { 33835 TPM_RC 33836 NV_INDEX 33837 UINT64 33838 33839 result; 33840 nvIndex; 33841 countValue; 33842 33843 // Input Validation 33844 // Common access checks, a TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED 33845 // error may be returned at this point 33846 result = NvWriteAccessChecks(in->authHandle, in->nvIndex); 33847 if(result != TPM_RC_SUCCESS) 33848 return result; 33849 // Get NV index info 33850 NvGetIndexInfo(in->nvIndex, &nvIndex); 33851 // Make sure that this is a counter 33852 if(nvIndex.publicArea.attributes.TPMA_NV_COUNTER != SET) 33853 return TPM_RC_ATTRIBUTES + RC_NV_Increment_nvIndex; 33854 // Internal Data Update 33855 // If counter index is not been written, initialize it 33856 if(nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR) 33857 countValue = NvInitialCounter(); 33858 else 33859 // Read NV data in native format for TPM CPU. 33860 NvGetIntIndexData(in->nvIndex, &nvIndex, &countValue); 33861 // Do the increment 33862 countValue++; 33863 // If this is an orderly counter that just rolled over, need to be able to 33864 // write to NV to proceed. This check is done here, because NvWriteIndexData() 33865 // does not see if the update is for counter rollover. 33866 if( 33867 nvIndex.publicArea.attributes.TPMA_NV_ORDERLY == SET 33868 && (countValue & MAX_ORDERLY_COUNT) == 0) 33869 { 33870 result = NvIsAvailable(); 33871 if(result != TPM_RC_SUCCESS) 33872 return result; 33873 // Need to force an NV update 33874 33875 Family 2.0 33876 Level 00 Revision 00.99 33877 33878 Published 33879 Copyright TCG 2006-2013 33880 33881 Page 415 33882 October 31, 2013 33883 33884 Part 3: Commands 33886 52 33887 53 33888 54 33889 55 33890 56 33891 57 33892 58 33893 59 33894 60 33895 33896 Trusted Platform Module Library 33897 33898 g_updateNV = TRUE; 33899 } 33900 // Write NV data back. A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may 33901 // be returned at this point. If necessary, this function will set the 33902 // TPMA_NV_WRITTEN attribute 33903 return NvWriteIndexData(in->nvIndex, &nvIndex, 0, 8, &countValue); 33904 } 33905 33906 Page 416 33907 October 31, 2013 33908 33909 Published 33910 Copyright TCG 2006-2013 33911 33912 Family 2.0 33913 Level 00 Revision 00.99 33914 33915 Trusted Platform Module Library 33917 33918 33.9 33919 33920 Part 3: Commands 33921 33922 TPM2_NV_Extend 33923 33924 33.9.1 General Description 33925 This command extends a value to an area in NV memory that was previously defined by 33926 TPM2_NV_DefineSpace. 33927 If TPMA_NV_EXTEND is not SET, then the TPM shall return TPM_RC_ATTRIBUTES. 33928 Proper write authorizations are required for this command as determined by TPMA_NV_PPWRITE, 33929 TPMA_NV_OWNERWRITE, TPMA_NV_AUTHWRITE, and the authPolicy of the NV Index. 33930 After successful completion of this command, TPMA_NV_WRITTEN for the NV Index will be SET. 33931 NOTE 1 33932 33933 Once SET, TPMA_NV_WRITTEN remains SET until the NV Index is undefined or the NV Index is 33934 cleared. 33935 33936 If the TPMA_NV_WRITELOCKED attribute of the NV Index is SET, then the TPM shall return 33937 TPM_RC_NV_LOCKED. 33938 NOTE 2 33939 33940 If authorization sessions are present, they are checked before checks to see if writes to the NV 33941 Index are locked. 33942 33943 The data.buffer parameter may be larger than the defined size of the NV Index. 33944 The Index will be updated by: 33945 33946 nvIndexdatanew HnameAkg(nvIndexdataold || data.buffer) 33947 33948 (39) 33949 33950 where 33951 33952 HnameAkg() 33953 33954 the hash algorithm indicated in nvIndexnameAlg 33955 33956 nvIndexdata 33957 33958 the value of the data field in the NV Index 33959 33960 data.buffer 33961 33962 the data buffer of the command parameter 33963 33964 NOTE 3 33965 33966 If TPMA_NV_WRITTEN is CLEAR, then nvIndexdata is a Zero Digest. 33967 33968 Family 2.0 33969 Level 00 Revision 00.99 33970 33971 Published 33972 Copyright TCG 2006-2013 33973 33974 Page 417 33975 October 31, 2013 33976 33977 Part 3: Commands 33979 33980 Trusted Platform Module Library 33981 33982 33.9.2 Command and Response 33983 Table 209 TPM2_NV_Extend Command 33984 Type 33985 33986 Name 33987 33988 Description 33989 33990 TPMI_ST_COMMAND_TAG 33991 33992 tag 33993 33994 UINT32 33995 33996 commandSize 33997 33998 TPM_CC 33999 34000 commandCode 34001 34002 TPM_CC_NV_Extend {NV} 34003 34004 TPMI_RH_NV_AUTH 34005 34006 @authHandle 34007 34008 handle indicating the source of the authorization value 34009 Auth Index: 1 34010 Auth Role: USER 34011 34012 TPMI_RH_NV_INDEX 34013 34014 nvIndex 34015 34016 the NV Index to extend 34017 Auth Index: None 34018 34019 TPM2B_MAX_NV_BUFFER 34020 34021 data 34022 34023 the data to extend 34024 34025 Table 210 TPM2_NV_Extend Response 34026 Type 34027 34028 Name 34029 34030 Description 34031 34032 TPM_ST 34033 34034 tag 34035 34036 see clause 8 34037 34038 UINT32 34039 34040 responseSize 34041 34042 TPM_RC 34043 34044 responseCode 34045 34046 Page 418 34047 October 31, 2013 34048 34049 Published 34050 Copyright TCG 2006-2013 34051 34052 Family 2.0 34053 Level 00 Revision 00.99 34054 34055 Trusted Platform Module Library 34057 34058 Part 3: Commands 34059 34060 33.9.3 Detailed Actions 34061 1 34062 2 34063 3 34064 34065 #include "InternalRoutines.h" 34066 #include "NV_Extend_fp.h" 34067 #include "NV_spt_fp.h" 34068 Error Returns 34069 TPM_RC_ATTRIBUTES 34070 34071 the TPMA_NV_EXTEND attribute is not SET in the Index referenced 34072 by nvIndex 34073 34074 TPM_RC_NV_AUTHORIZATION 34075 34076 the authorization was valid but the authorizing entity (authHandle) is 34077 not allowed to write to the Index referenced by nvIndex 34078 34079 TPM_RC_NV_LOCKED 34080 4 34081 5 34082 6 34083 7 34084 8 34085 9 34086 10 34087 11 34088 12 34089 13 34090 14 34091 15 34092 16 34093 17 34094 18 34095 19 34096 20 34097 21 34098 22 34099 23 34100 24 34101 25 34102 26 34103 27 34104 28 34105 29 34106 30 34107 31 34108 32 34109 33 34110 34 34111 35 34112 36 34113 37 34114 38 34115 39 34116 40 34117 41 34118 42 34119 43 34120 44 34121 45 34122 46 34123 47 34124 48 34125 49 34126 34127 Meaning 34128 34129 the Index referenced by nvIndex is locked for writing 34130 34131 TPM_RC 34132 TPM2_NV_Extend( 34133 NV_Extend_In 34134 34135 *in 34136 34137 // IN: input parameter list 34138 34139 ) 34140 { 34141 TPM_RC 34142 NV_INDEX 34143 34144 result; 34145 nvIndex; 34146 34147 TPM2B_DIGEST 34148 TPM2B_DIGEST 34149 HASH_STATE 34150 34151 oldDigest; 34152 newDigest; 34153 hashState; 34154 34155 // Input Validation 34156 // Common access checks, NvWriteAccessCheck() may return TPM_RC_NV_AUTHORIZATION 34157 // or TPM_RC_NV_LOCKED 34158 result = NvWriteAccessChecks(in->authHandle, in->nvIndex); 34159 if(result != TPM_RC_SUCCESS) 34160 return result; 34161 // Get NV index info 34162 NvGetIndexInfo(in->nvIndex, &nvIndex); 34163 // Make sure that this is an extend index 34164 if(nvIndex.publicArea.attributes.TPMA_NV_EXTEND != SET) 34165 return TPM_RC_ATTRIBUTES + RC_NV_Extend_nvIndex; 34166 // If the Index is not-orderly, or if this is the first write, NV will 34167 // need to be updated. 34168 if( 34169 nvIndex.publicArea.attributes.TPMA_NV_ORDERLY == CLEAR 34170 || nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR) 34171 { 34172 // Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE 34173 // TPM_RC_NV_RATE or TPM_RC_SUCCESS. 34174 result = NvIsAvailable(); 34175 if(result != TPM_RC_SUCCESS) 34176 return result; 34177 } 34178 // Internal Data Update 34179 // Perform the write. 34180 oldDigest.t.size = CryptGetHashDigestSize(nvIndex.publicArea.nameAlg); 34181 if(nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == SET) 34182 { 34183 NvGetIndexData(in->nvIndex, &nvIndex, 0, 34184 34185 Family 2.0 34186 Level 00 Revision 00.99 34187 34188 Published 34189 Copyright TCG 2006-2013 34190 34191 Page 419 34192 October 31, 2013 34193 34194 Part 3: Commands 34196 50 34197 51 34198 52 34199 53 34200 54 34201 55 34202 56 34203 57 34204 58 34205 59 34206 60 34207 61 34208 62 34209 63 34210 64 34211 65 34212 66 34213 67 34214 68 34215 69 34216 70 34217 71 34218 72 34219 34220 Trusted Platform Module Library 34221 34222 oldDigest.t.size, oldDigest.t.buffer); 34223 } 34224 else 34225 { 34226 MemorySet(oldDigest.t.buffer, 0, oldDigest.t.size); 34227 } 34228 // Start hash 34229 newDigest.t.size = CryptStartHash(nvIndex.publicArea.nameAlg, &hashState); 34230 // Adding old digest 34231 CryptUpdateDigest2B(&hashState, &oldDigest.b); 34232 // Adding new data 34233 CryptUpdateDigest2B(&hashState, &in->data.b); 34234 // Complete hash 34235 CryptCompleteHash2B(&hashState, &newDigest.b); 34236 // Write extended hash back. 34237 // Note, this routine will SET the TPMA_NV_WRITTEN attribute if necessary 34238 return NvWriteIndexData(in->nvIndex, &nvIndex, 0, 34239 newDigest.t.size, newDigest.t.buffer); 34240 } 34241 34242 Page 420 34243 October 31, 2013 34244 34245 Published 34246 Copyright TCG 2006-2013 34247 34248 Family 2.0 34249 Level 00 Revision 00.99 34250 34251 Trusted Platform Module Library 34253 34254 Part 3: Commands 34255 34256 33.10 TPM2_NV_SetBits 34257 33.10.1 34258 34259 General Description 34260 34261 This command is used to SET bits in an NV Index that was created as a bit field. Any number of bits from 34262 0 to 64 may be SET. The contents of data are ORed with the current contents of the NV Index starting at 34263 offset. The checks on data and offset are the same as for TPM2_NV_Write. 34264 If TPMA_NV_WRITTEN is not SET, then, for the purposes of this command, the NV Index is considered 34265 to contain all zero bits and data is OR with that value. 34266 If TPMA_NV_BITS is not SET, then the TPM shall return TPM_RC_ATTRIBUTES. 34267 After successful completion of this command, TPMA_NV_WRITTEN for the NV Index will be SET. 34268 NOTE 34269 34270 TPMA_NV_WRITTEN will be SET even if no bits were SET. 34271 34272 Family 2.0 34273 Level 00 Revision 00.99 34274 34275 Published 34276 Copyright TCG 2006-2013 34277 34278 Page 421 34279 October 31, 2013 34280 34281 Part 3: Commands 34283 34284 33.10.2 34285 34286 Trusted Platform Module Library 34287 34288 Command and Response 34289 Table 211 TPM2_NV_SetBits Command 34290 34291 Type 34292 34293 Name 34294 34295 Description 34296 34297 TPMI_ST_COMMAND_TAG 34298 34299 tag 34300 34301 UINT32 34302 34303 commandSize 34304 34305 TPM_CC 34306 34307 commandCode 34308 34309 TPM_CC_NV_SetBits {NV} 34310 34311 TPMI_RH_NV_AUTH 34312 34313 @authHandle 34314 34315 handle indicating the source of the authorization value 34316 Auth Index: 1 34317 Auth Role: USER 34318 34319 TPMI_RH_NV_INDEX 34320 34321 nvIndex 34322 34323 NV Index of the area in which the bit is to be set 34324 Auth Index: None 34325 34326 UINT64 34327 34328 bits 34329 34330 the data to OR with the current contents 34331 34332 Table 212 TPM2_NV_SetBits Response 34333 Type 34334 34335 Name 34336 34337 Description 34338 34339 TPM_ST 34340 34341 tag 34342 34343 see clause 8 34344 34345 UINT32 34346 34347 responseSize 34348 34349 TPM_RC 34350 34351 responseCode 34352 34353 Page 422 34354 October 31, 2013 34355 34356 Published 34357 Copyright TCG 2006-2013 34358 34359 Family 2.0 34360 Level 00 Revision 00.99 34361 34362 Trusted Platform Module Library 34364 34365 33.10.3 34366 1 34367 2 34368 3 34369 34370 Part 3: Commands 34371 34372 Detailed Actions 34373 34374 #include "InternalRoutines.h" 34375 #include "NV_SetBits_fp.h" 34376 #include "NV_spt_fp.h" 34377 Error Returns 34378 TPM_RC_ATTRIBUTES 34379 34380 the TPMA_NV_BITS attribute is not SET in the Index referenced by 34381 nvIndex 34382 34383 TPM_RC_NV_AUTHORIZATION 34384 34385 the authorization was valid but the authorizing entity (authHandle) is 34386 not allowed to write to the Index referenced by nvIndex 34387 34388 TPM_RC_NV_LOCKED 34389 4 34390 5 34391 6 34392 7 34393 8 34394 9 34395 10 34396 11 34397 12 34398 13 34399 14 34400 15 34401 16 34402 17 34403 18 34404 19 34405 20 34406 21 34407 22 34408 23 34409 24 34410 25 34411 26 34412 27 34413 28 34414 29 34415 30 34416 31 34417 32 34418 33 34419 34 34420 35 34421 36 34422 37 34423 38 34424 39 34425 40 34426 41 34427 42 34428 43 34429 44 34430 45 34431 46 34432 47 34433 48 34434 49 34435 34436 Meaning 34437 34438 the Index referenced by nvIndex is locked for writing 34439 34440 TPM_RC 34441 TPM2_NV_SetBits( 34442 NV_SetBits_In 34443 34444 *in 34445 34446 // IN: input parameter list 34447 34448 ) 34449 { 34450 TPM_RC 34451 NV_INDEX 34452 UINT64 34453 34454 result; 34455 nvIndex; 34456 bitValue; 34457 34458 // Input Validation 34459 // Common access checks, NvWriteAccessCheck() may return TPM_RC_NV_AUTHORIZATION 34460 // or TPM_RC_NV_LOCKED 34461 // error may be returned at this point 34462 result = NvWriteAccessChecks(in->authHandle, in->nvIndex); 34463 if(result != TPM_RC_SUCCESS) 34464 return result; 34465 // Get NV index info 34466 NvGetIndexInfo(in->nvIndex, &nvIndex); 34467 // Make sure that this is a bit field 34468 if(nvIndex.publicArea.attributes.TPMA_NV_BITS != SET) 34469 return TPM_RC_ATTRIBUTES + RC_NV_SetBits_nvIndex; 34470 // If the Index is not-orderly, or if this is the first write, NV will 34471 // need to be updated. 34472 if( 34473 nvIndex.publicArea.attributes.TPMA_NV_ORDERLY == CLEAR 34474 || nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR) 34475 { 34476 // Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE 34477 // TPM_RC_NV_RATE or TPM_RC_SUCCESS. 34478 result = NvIsAvailable(); 34479 if(result != TPM_RC_SUCCESS) 34480 return result; 34481 } 34482 // Internal Data Update 34483 // If index is not been written, initialize it 34484 if(nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR) 34485 bitValue = 0; 34486 else 34487 // Read index data 34488 34489 Family 2.0 34490 Level 00 Revision 00.99 34491 34492 Published 34493 Copyright TCG 2006-2013 34494 34495 Page 423 34496 October 31, 2013 34497 34498 Part 3: Commands 34500 50 34501 51 34502 52 34503 53 34504 54 34505 55 34506 56 34507 57 34508 58 34509 59 34510 34511 Trusted Platform Module Library 34512 34513 NvGetIntIndexData(in->nvIndex, &nvIndex, &bitValue); 34514 // OR in the new bit setting 34515 bitValue |= in->bits; 34516 // Write index data back. If necessary, this function will SET 34517 // TPMA_NV_WRITTEN. 34518 return NvWriteIndexData(in->nvIndex, &nvIndex, 0, 8, &bitValue); 34519 } 34520 34521 Page 424 34522 October 31, 2013 34523 34524 Published 34525 Copyright TCG 2006-2013 34526 34527 Family 2.0 34528 Level 00 Revision 00.99 34529 34530 Trusted Platform Module Library 34532 34533 Part 3: Commands 34534 34535 33.11 TPM2_NV_WriteLock 34536 33.11.1 34537 34538 General Description 34539 34540 If the TPMA_NV_WRITEDEFINE or TPMA_NV_WRITE_STCLEAR attributes of an NV location are SET, 34541 then this command may be used to inhibit further writes of the NV Index. 34542 Proper write authorization is required for this command as determined by TPMA_NV_PPWRITE, 34543 TPMA_NV_OWNERWRITE, TPMA_NV_AUTHWRITE, and the authPolicy of the NV Index. 34544 It is not an error if TPMA_NV_WRITELOCKED for the NV Index is already SET. 34545 If neither TPMA_NV_WRITEDEFINE nor TPMA_NV_WRITE_STCLEAR of the NV Index is SET, then the 34546 TPM shall return TPM_RC_ATTRIBUTES. 34547 If the command is properly authorized and TPMA_NV_WRITE_STCLEAR or TPMA_NV_WRITEDEFINE 34548 is SET, then the TPM shall SET TPMA_NV_WRITELOCKED for the NV Index. 34549 TPMA_NV_WRITELOCKED will be clear on the next TPM2_Startup(TPM_SU_CLEAR) unless 34550 TPMA_NV_WRITEDEFINE is SET. 34551 34552 Family 2.0 34553 Level 00 Revision 00.99 34554 34555 Published 34556 Copyright TCG 2006-2013 34557 34558 Page 425 34559 October 31, 2013 34560 34561 Part 3: Commands 34563 34564 33.11.2 34565 34566 Trusted Platform Module Library 34567 34568 Command and Response 34569 Table 213 TPM2_NV_WriteLock Command 34570 34571 Type 34572 34573 Name 34574 34575 Description 34576 34577 TPMI_ST_COMMAND_TAG 34578 34579 tag 34580 34581 UINT32 34582 34583 commandSize 34584 34585 TPM_CC 34586 34587 commandCode 34588 34589 TPM_CC_NV_WriteLock {NV} 34590 34591 TPMI_RH_NV_AUTH 34592 34593 @authHandle 34594 34595 handle indicating the source of the authorization value 34596 Auth Index: 1 34597 Auth Role: USER 34598 34599 TPMI_RH_NV_INDEX 34600 34601 nvIndex 34602 34603 the NV Index of the area to lock 34604 Auth Index: None 34605 34606 Table 214 TPM2_NV_WriteLock Response 34607 Type 34608 34609 Name 34610 34611 Description 34612 34613 TPM_ST 34614 34615 tag 34616 34617 see clause 8 34618 34619 UINT32 34620 34621 responseSize 34622 34623 TPM_RC 34624 34625 responseCode 34626 34627 Page 426 34628 October 31, 2013 34629 34630 Published 34631 Copyright TCG 2006-2013 34632 34633 Family 2.0 34634 Level 00 Revision 00.99 34635 34636 Trusted Platform Module Library 34638 34639 33.11.3 34640 1 34641 2 34642 3 34643 34644 Part 3: Commands 34645 34646 Detailed Actions 34647 34648 #include "InternalRoutines.h" 34649 #include "NV_WriteLock_fp.h" 34650 #include "NV_spt_fp.h" 34651 Error Returns 34652 TPM_RC_ATTRIBUTES 34653 34654 neither TPMA_NV_WRITEDEFINE nor 34655 TPMA_NV_WRITE_STCLEAR is SET in Index referenced by 34656 nvIndex 34657 34658 TPM_RC_NV_AUTHORIZATION 34659 34660 4 34661 5 34662 6 34663 7 34664 8 34665 9 34666 10 34667 11 34668 12 34669 13 34670 14 34671 15 34672 16 34673 17 34674 18 34675 19 34676 20 34677 21 34678 22 34679 23 34680 24 34681 25 34682 26 34683 27 34684 28 34685 29 34686 30 34687 31 34688 32 34689 33 34690 34 34691 35 34692 36 34693 37 34694 38 34695 39 34696 40 34697 41 34698 42 34699 43 34700 44 34701 45 34702 46 34703 47 34704 48 34705 49 34706 50 34707 34708 Meaning 34709 34710 the authorization was valid but the authorizing entity (authHandle) is 34711 not allowed to write to the Index referenced by nvIndex 34712 34713 TPM_RC 34714 TPM2_NV_WriteLock( 34715 NV_WriteLock_In *in 34716 34717 // IN: input parameter list 34718 34719 ) 34720 { 34721 TPM_RC 34722 NV_INDEX 34723 34724 result; 34725 nvIndex; 34726 34727 // The command needs NV update. Check if NV is available. 34728 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 34729 // this point 34730 result = NvIsAvailable(); 34731 if(result != TPM_RC_SUCCESS) 34732 return result; 34733 // Input Validation: 34734 // Common write access checks, a TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED 34735 // error may be returned at this point 34736 result = NvWriteAccessChecks(in->authHandle, in->nvIndex); 34737 if(result != TPM_RC_SUCCESS) 34738 { 34739 if(result == TPM_RC_NV_AUTHORIZATION) 34740 return TPM_RC_NV_AUTHORIZATION; 34741 // If write access failed because the index is already locked, then it is 34742 // no error. 34743 return TPM_RC_SUCCESS; 34744 } 34745 // Get NV index info 34746 NvGetIndexInfo(in->nvIndex, &nvIndex); 34747 // if non of TPMA_NV_WRITEDEFINE or TPMA_NV_WRITE_STCLEAR is set, the index 34748 // can not be write-locked 34749 if( 34750 nvIndex.publicArea.attributes.TPMA_NV_WRITEDEFINE == CLEAR 34751 && nvIndex.publicArea.attributes.TPMA_NV_WRITE_STCLEAR == CLEAR) 34752 return TPM_RC_ATTRIBUTES + RC_NV_WriteLock_nvIndex; 34753 // Internal Data Update 34754 // Set the WRITELOCK attribute 34755 nvIndex.publicArea.attributes.TPMA_NV_WRITELOCKED = SET; 34756 // Write index info back 34757 NvWriteIndexInfo(in->nvIndex, &nvIndex); 34758 34759 Family 2.0 34760 Level 00 Revision 00.99 34761 34762 Published 34763 Copyright TCG 2006-2013 34764 34765 Page 427 34766 October 31, 2013 34767 34768 Part 3: Commands 34770 51 34771 52 34772 34773 Trusted Platform Module Library 34774 34775 return TPM_RC_SUCCESS; 34776 } 34777 34778 Page 428 34779 October 31, 2013 34780 34781 Published 34782 Copyright TCG 2006-2013 34783 34784 Family 2.0 34785 Level 00 Revision 00.99 34786 34787 Trusted Platform Module Library 34789 34790 Part 3: Commands 34791 34792 33.12 TPM2_NV_GlobalWriteLock 34793 33.12.1 34794 34795 General Description 34796 34797 The command will SET TPMA_NV_WRITELOCKED 34798 TPMA_NV_GLOBALLOCK attribute SET. 34799 34800 for 34801 34802 all 34803 34804 indexes 34805 34806 that 34807 34808 have 34809 34810 their 34811 34812 If an Index has both TPMA_NV_WRITELOCKED and TPMA_NV_WRITEDEFINE SET, then this 34813 command will permanently lock the NV Index for writing. 34814 NOTE 34815 34816 If an Index is defined with TPMA_NV_GLOBALLOCK SET, then the global lock does not apply until 34817 the next time this command is executed. 34818 34819 This command requires either platformAuth/platformPolicy or ownerAuth/ownerPolicy. 34820 34821 Family 2.0 34822 Level 00 Revision 00.99 34823 34824 Published 34825 Copyright TCG 2006-2013 34826 34827 Page 429 34828 October 31, 2013 34829 34830 Part 3: Commands 34832 34833 33.12.2 34834 34835 Trusted Platform Module Library 34836 34837 Command and Response 34838 Table 215 TPM2_NV_GlobalWriteLock Command 34839 34840 Type 34841 34842 Name 34843 34844 TPMI_ST_COMMAND_TAG 34845 34846 tag 34847 34848 UINT32 34849 34850 commandSize 34851 34852 TPM_CC 34853 34854 commandCode 34855 34856 TPM_CC_NV_GlobalWriteLock 34857 34858 @authHandle 34859 34860 TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 34861 Auth Index: 1 34862 Auth Role: USER 34863 34864 TPMI_RH_PROVISION 34865 34866 Description 34867 34868 Table 216 TPM2_NV_GlobalWriteLock Response 34869 Type 34870 34871 Name 34872 34873 Description 34874 34875 TPM_ST 34876 34877 tag 34878 34879 see clause 8 34880 34881 UINT32 34882 34883 responseSize 34884 34885 TPM_RC 34886 34887 responseCode 34888 34889 Page 430 34890 October 31, 2013 34891 34892 Published 34893 Copyright TCG 2006-2013 34894 34895 Family 2.0 34896 Level 00 Revision 00.99 34897 34898 Trusted Platform Module Library 34900 34901 33.12.3 34902 1 34903 2 34904 3 34905 4 34906 5 34907 6 34908 7 34909 8 34910 9 34911 10 34912 11 34913 12 34914 13 34915 14 34916 15 34917 16 34918 17 34919 18 34920 19 34921 20 34922 21 34923 22 34924 23 34925 24 34926 25 34927 26 34928 34929 Part 3: Commands 34930 34931 Detailed Actions 34932 34933 #include "InternalRoutines.h" 34934 #include "NV_GlobalWriteLock_fp.h" 34935 34936 TPM_RC 34937 TPM2_NV_GlobalWriteLock( 34938 NV_GlobalWriteLock_In *in 34939 34940 // IN: input parameter list 34941 34942 ) 34943 { 34944 TPM_RC 34945 34946 result; 34947 34948 // Input parameter is not reference in command action 34949 in = NULL; // to silence compiler warnings. 34950 // The command needs NV update. Check if NV is available. 34951 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 34952 // this point 34953 result = NvIsAvailable(); 34954 if(result != TPM_RC_SUCCESS) 34955 return result; 34956 // Internal Data Update 34957 // Implementation dependent method of setting the global lock 34958 NvSetGlobalLock(); 34959 return TPM_RC_SUCCESS; 34960 } 34961 34962 Family 2.0 34963 Level 00 Revision 00.99 34964 34965 Published 34966 Copyright TCG 2006-2013 34967 34968 Page 431 34969 October 31, 2013 34970 34971 Part 3: Commands 34973 34974 Trusted Platform Module Library 34975 34976 33.13 TPM2_NV_Read 34977 33.13.1 34978 34979 General Description 34980 34981 This command reads a 34982 TPM2_NV_DefineSpace(). 34983 34984 value 34985 34986 from 34987 34988 an 34989 34990 area 34991 34992 in 34993 34994 NV 34995 34996 memory 34997 34998 previously 34999 35000 defined 35001 35002 by 35003 35004 Proper authorizations are required for this command as determined by TPMA_NV_PPREAD, 35005 TPMA_NV_OWNERREAD, TPMA_NV_AUTHREAD, and the authPolicy of the NV Index. 35006 If TPMA_NV_READLOCKED of the NV Index is SET, then the TPM shall return TPM_RC_NV_LOCKED. 35007 NOTE 35008 35009 If authorization sessions are present, they are checked before the read -lock status of the NV Index 35010 is checked. 35011 35012 If the size parameter plus the offset parameter adds to a value that is greater than the size of the NV 35013 Index data area, the TPM shall return TPM_RC_NV_RANGE and not read any data from the NV Index. 35014 If the NV Index has been defined but the TPMA_NV_WRITTEN attribute is CLEAR, then this command 35015 shall return TPM_RC_NV_UINITIALIZED even if size is zero. 35016 The data parameter in the response may be encrypted using parameter encryption. 35017 35018 Page 432 35019 October 31, 2013 35020 35021 Published 35022 Copyright TCG 2006-2013 35023 35024 Family 2.0 35025 Level 00 Revision 00.99 35026 35027 Trusted Platform Module Library 35029 35030 33.13.2 35031 35032 Part 3: Commands 35033 35034 Command and Response 35035 Table 217 TPM2_NV_Read Command 35036 35037 Type 35038 35039 Name 35040 35041 Description 35042 35043 TPMI_ST_COMMAND_TAG 35044 35045 tag 35046 35047 UINT32 35048 35049 commandSize 35050 35051 TPM_CC 35052 35053 commandCode 35054 35055 TPM_CC_NV_Read 35056 35057 TPMI_RH_NV_AUTH 35058 35059 @authHandle 35060 35061 the handle indicating the source of the authorization 35062 value 35063 Auth Index: 1 35064 Auth Role: USER 35065 35066 TPMI_RH_NV_INDEX 35067 35068 nvIndex 35069 35070 the NV Index to be read 35071 Auth Index: None 35072 35073 UINT16 35074 35075 size 35076 35077 number of octets to read 35078 35079 UINT16 35080 35081 offset 35082 35083 octet offset into the area 35084 This value shall be less than or equal to the size of the 35085 nvIndex data. 35086 35087 Table 218 TPM2_NV_Read Response 35088 Type 35089 35090 Name 35091 35092 Description 35093 35094 TPM_ST 35095 35096 tag 35097 35098 see clause 8 35099 35100 UINT32 35101 35102 responseSize 35103 35104 TPM_RC 35105 35106 responseCode 35107 35108 TPM2B_MAX_NV_BUFFER 35109 35110 data 35111 35112 Family 2.0 35113 Level 00 Revision 00.99 35114 35115 the data read 35116 35117 Published 35118 Copyright TCG 2006-2013 35119 35120 Page 433 35121 October 31, 2013 35122 35123 Part 3: Commands 35125 35126 33.13.3 35127 1 35128 2 35129 3 35130 35131 Trusted Platform Module Library 35132 35133 Detailed Actions 35134 35135 #include "InternalRoutines.h" 35136 #include "NV_Read_fp.h" 35137 #include "NV_spt_fp.h" 35138 Error Returns 35139 TPM_RC_NV_AUTHORIZATION 35140 35141 the authorization was valid but the authorizing entity (authHandle) is 35142 not allowed to read from the Index referenced by nvIndex 35143 35144 TPM_RC_NV_LOCKED 35145 35146 the Index referenced by nvIndex is read locked 35147 35148 TPM_RC_NV_RANGE 35149 35150 read range defined by size and offset is outside the range of the 35151 Index referenced by nvIndex 35152 35153 TPM_RC_NV_UNINITIALIZED 35154 4 35155 5 35156 6 35157 7 35158 8 35159 9 35160 10 35161 11 35162 12 35163 13 35164 14 35165 15 35166 16 35167 17 35168 18 35169 19 35170 20 35171 21 35172 22 35173 23 35174 24 35175 25 35176 26 35177 27 35178 28 35179 29 35180 30 35181 31 35182 32 35183 33 35184 34 35185 35 35186 36 35187 37 35188 35189 Meaning 35190 35191 the Index referenced by nvIndex has not been initialized (written) 35192 35193 TPM_RC 35194 TPM2_NV_Read( 35195 NV_Read_In 35196 NV_Read_Out 35197 35198 *in, 35199 *out 35200 35201 // IN: input parameter list 35202 // OUT: output parameter list 35203 35204 ) 35205 { 35206 NV_INDEX 35207 TPM_RC 35208 35209 nvIndex; 35210 result; 35211 35212 // Input Validation 35213 // Get NV index info 35214 NvGetIndexInfo(in->nvIndex, &nvIndex); 35215 // Common read access checks. NvReadAccessChecks() returns 35216 // TPM_RC_NV_AUTHORIZATION, TPM_RC_NV_LOCKED, or TPM_RC_NV_UNINITIALIZED 35217 // error may be returned at this point 35218 result = NvReadAccessChecks(in->authHandle, in->nvIndex); 35219 if(result != TPM_RC_SUCCESS) 35220 return result; 35221 // Too much data 35222 if((in->size + in->offset) > nvIndex.publicArea.dataSize) 35223 return TPM_RC_NV_RANGE; 35224 // Command Output 35225 // Set the return size 35226 out->data.t.size = in->size; 35227 // Perform the read 35228 NvGetIndexData(in->nvIndex, &nvIndex, in->offset, in->size, out->data.t.buffer); 35229 return TPM_RC_SUCCESS; 35230 } 35231 35232 Page 434 35233 October 31, 2013 35234 35235 Published 35236 Copyright TCG 2006-2013 35237 35238 Family 2.0 35239 Level 00 Revision 00.99 35240 35241 Trusted Platform Module Library 35243 35244 Part 3: Commands 35245 35246 33.14 TPM2_NV_ReadLock 35247 33.14.1 35248 35249 General Description 35250 35251 If TPMA_NV_READ_STCLEAR is SET in an Index, then this command may be used to prevent further 35252 reads of the NV Index until the next TPM2_Startup (TPM_SU_CLEAR). 35253 Proper authorizations are required for this command as determined by TPMA_NV_PPREAD, 35254 TPMA_NV_OWNERREAD, TPMA_NV_AUTHREAD, and the authPolicy of the NV Index. 35255 NOTE 35256 35257 Only an entity that may read an Index is allowed to lock the NV Index for read. 35258 35259 If the command is properly authorized and TPMA_NV_READ_STCLEAR of the NV Index is SET, then the 35260 TPM shall SET TPMA_NV_READLOCKED for the NV Index. If TPMA_NV_READ_STCLEAR of the NV 35261 Index is CLEAR, then the TPM shall return TPM_RC_NV_ATTRIBUTE. TPMA_NV_READLOCKED will 35262 be CLEAR by the next TPM2_Startup(TPM_SU_CLEAR). 35263 It is not an error to use this command for an Index that is already locked for reading. 35264 An Index that had not been written may be locked for reading. 35265 35266 Family 2.0 35267 Level 00 Revision 00.99 35268 35269 Published 35270 Copyright TCG 2006-2013 35271 35272 Page 435 35273 October 31, 2013 35274 35275 Part 3: Commands 35277 35278 33.14.2 35279 35280 Trusted Platform Module Library 35281 35282 Command and Response 35283 Table 219 TPM2_NV_ReadLock Command 35284 35285 Type 35286 35287 Name 35288 35289 Description 35290 35291 TPMI_ST_COMMAND_TAG 35292 35293 tag 35294 35295 UINT32 35296 35297 commandSize 35298 35299 TPM_CC 35300 35301 commandCode 35302 35303 TPM_CC_NV_ReadLock 35304 35305 TPMI_RH_NV_AUTH 35306 35307 @authHandle 35308 35309 the handle indicating the source of the authorization 35310 value 35311 Auth Index: 1 35312 Auth Role: USER 35313 35314 TPMI_RH_NV_INDEX 35315 35316 nvIndex 35317 35318 the NV Index to be locked 35319 Auth Index: None 35320 35321 Table 220 TPM2_NV_ReadLock Response 35322 Type 35323 35324 Name 35325 35326 Description 35327 35328 TPM_ST 35329 35330 tag 35331 35332 see clause 8 35333 35334 UINT32 35335 35336 responseSize 35337 35338 TPM_RC 35339 35340 responseCode 35341 35342 Page 436 35343 October 31, 2013 35344 35345 Published 35346 Copyright TCG 2006-2013 35347 35348 Family 2.0 35349 Level 00 Revision 00.99 35350 35351 Trusted Platform Module Library 35353 35354 33.14.3 35355 1 35356 2 35357 3 35358 35359 Part 3: Commands 35360 35361 Detailed Actions 35362 35363 #include "InternalRoutines.h" 35364 #include "NV_ReadLock_fp.h" 35365 #include "NV_spt_fp.h" 35366 Error Returns 35367 TPM_RC_ATTRIBUTES 35368 35369 TPMA_NV_READ_STCLEAR is not SET so Index referenced by 35370 nvIndex may not be write locked 35371 35372 TPM_RC_NV_AUTHORIZATION 35373 35374 4 35375 5 35376 6 35377 7 35378 8 35379 9 35380 10 35381 11 35382 12 35383 13 35384 14 35385 15 35386 16 35387 17 35388 18 35389 19 35390 20 35391 21 35392 22 35393 23 35394 24 35395 25 35396 26 35397 27 35398 28 35399 29 35400 30 35401 31 35402 32 35403 33 35404 34 35405 35 35406 36 35407 37 35408 38 35409 39 35410 40 35411 41 35412 42 35413 43 35414 44 35415 45 35416 46 35417 47 35418 48 35419 49 35420 50 35421 51 35422 35423 Meaning 35424 35425 the authorization was valid but the authorizing entity (authHandle) is 35426 not allowed to read from the Index referenced by nvIndex 35427 35428 TPM_RC 35429 TPM2_NV_ReadLock( 35430 NV_ReadLock_In *in 35431 35432 // IN: input parameter list 35433 35434 ) 35435 { 35436 TPM_RC 35437 NV_INDEX 35438 35439 result; 35440 nvIndex; 35441 35442 // The command needs NV update. Check if NV is available. 35443 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 35444 // this point 35445 result = NvIsAvailable(); 35446 if(result != TPM_RC_SUCCESS) return result; 35447 // Input Validation 35448 // Common read access checks. NvReadAccessChecks() returns 35449 // TPM_RC_NV_AUTHORIZATION, TPM_RC_NV_LOCKED, or TPM_RC_NV_UNINITIALIZED 35450 // error may be returned at this point 35451 result = NvReadAccessChecks(in->authHandle, in->nvIndex); 35452 if(result != TPM_RC_SUCCESS) 35453 { 35454 if(result == TPM_RC_NV_AUTHORIZATION) 35455 return TPM_RC_NV_AUTHORIZATION; 35456 // Index is already locked for write 35457 else if(result == TPM_RC_NV_LOCKED) 35458 return TPM_RC_SUCCESS; 35459 // If NvReadAccessChecks return TPM_RC_NV_UNINITALIZED, then continue. 35460 // It is not an error to read lock an uninitialized Index. 35461 } 35462 // Get NV index info 35463 NvGetIndexInfo(in->nvIndex, &nvIndex); 35464 // if TPMA_NV_READ_STCLEAR is not set, the index can not be read-locked 35465 if(nvIndex.publicArea.attributes.TPMA_NV_READ_STCLEAR == CLEAR) 35466 return TPM_RC_ATTRIBUTES + RC_NV_ReadLock_nvIndex; 35467 // Internal Data Update 35468 // Set the READLOCK attribute 35469 nvIndex.publicArea.attributes.TPMA_NV_READLOCKED = SET; 35470 // Write NV info back 35471 NvWriteIndexInfo(in->nvIndex, &nvIndex); 35472 return TPM_RC_SUCCESS; 35473 } 35474 35475 Family 2.0 35476 Level 00 Revision 00.99 35477 35478 Published 35479 Copyright TCG 2006-2013 35480 35481 Page 437 35482 October 31, 2013 35483 35484 Part 3: Commands 35486 35487 Trusted Platform Module Library 35488 35489 33.15 TPM2_NV_ChangeAuth 35490 33.15.1 35491 35492 General Description 35493 35494 This command allows the authorization secret for an NV Index to be changed. 35495 If successful, the authorization secret (authValue) of the NV Index associated with nvIndex is changed. 35496 This command requires that a policy session be used for authorization of nvIndex so that the ADMIN role 35497 may be asserted and that commandCode in the policy session context shall be 35498 TPM_CC_NV_ChangeAuth. That is, the policy must contain a specific authorization for changing the 35499 authorization value of the referenced object. 35500 NOTE 35501 35502 The reason for this restriction is to ensure that the admin istrative actions on nvIndex require explicit 35503 approval while other commands may use policy that is not command -dependent. 35504 35505 The size of the newAuth value may be no larger than the size of authorization indicated when the NV 35506 Index was defined. 35507 Since the NV Index authorization is changed before the response HMAC is calculated, the newAuth value 35508 is used when generating the response HMAC key if required. See Part 4 ComputeResponseHMAC(). 35509 35510 Page 438 35511 October 31, 2013 35512 35513 Published 35514 Copyright TCG 2006-2013 35515 35516 Family 2.0 35517 Level 00 Revision 00.99 35518 35519 Trusted Platform Module Library 35521 35522 33.15.2 35523 35524 Part 3: Commands 35525 35526 Command and Response 35527 Table 221 TPM2_NV_ChangeAuth Command 35528 35529 Type 35530 35531 Name 35532 35533 Description 35534 35535 TPMI_ST_COMMAND_TAG 35536 35537 tag 35538 35539 UINT32 35540 35541 commandSize 35542 35543 TPM_CC 35544 35545 commandCode 35546 35547 TPM_CC_NV_ChangeAuth {NV} 35548 35549 TPMI_RH_NV_INDEX 35550 35551 @nvIndex 35552 35553 handle of the object 35554 Auth Index: 1 35555 Auth Role: ADMIN 35556 35557 TPM2B_AUTH 35558 35559 newAuth 35560 35561 new authorization value 35562 35563 Table 222 TPM2_NV_ChangeAuth Response 35564 Type 35565 35566 Name 35567 35568 Description 35569 35570 TPM_ST 35571 35572 tag 35573 35574 see clause 8 35575 35576 UINT32 35577 35578 responseSize 35579 35580 TPM_RC 35581 35582 responseCode 35583 35584 Family 2.0 35585 Level 00 Revision 00.99 35586 35587 Published 35588 Copyright TCG 2006-2013 35589 35590 Page 439 35591 October 31, 2013 35592 35593 Part 3: Commands 35595 35596 33.15.3 35597 1 35598 2 35599 35600 Trusted Platform Module Library 35601 35602 Detailed Actions 35603 35604 #include "InternalRoutines.h" 35605 #include "NV_ChangeAuth_fp.h" 35606 Error Returns 35607 TPM_RC_SIZE 35608 35609 3 35610 4 35611 5 35612 6 35613 7 35614 8 35615 9 35616 10 35617 11 35618 12 35619 13 35620 14 35621 15 35622 16 35623 17 35624 18 35625 19 35626 20 35627 21 35628 22 35629 23 35630 24 35631 25 35632 26 35633 27 35634 28 35635 29 35636 30 35637 31 35638 32 35639 33 35640 34 35641 35 35642 35643 Meaning 35644 newAuth size is larger than the digest size of the Name algorithm for 35645 the Index referenced by 'nvIndex 35646 35647 TPM_RC 35648 TPM2_NV_ChangeAuth( 35649 NV_ChangeAuth_In 35650 35651 *in 35652 35653 // IN: input parameter list 35654 35655 ) 35656 { 35657 TPM_RC 35658 NV_INDEX 35659 35660 result; 35661 nvIndex; 35662 35663 // Input Validation 35664 // Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE 35665 // TPM_RC_NV_RATE or TPM_RC_SUCCESS. 35666 result = NvIsAvailable(); 35667 if(result != TPM_RC_SUCCESS) return result; 35668 // Read index info from NV 35669 NvGetIndexInfo(in->nvIndex, &nvIndex); 35670 // Remove any trailing zeros that might have been added by the caller 35671 // to obfuscate the size. 35672 MemoryRemoveTrailingZeros(&(in->newAuth)); 35673 // Make sure that the authValue is no larger than the nameAlg of the Index 35674 if(in->newAuth.t.size > CryptGetHashDigestSize(nvIndex.publicArea.nameAlg)) 35675 return TPM_RC_SIZE + RC_NV_ChangeAuth_newAuth; 35676 // Internal Data Update 35677 // Change auth 35678 nvIndex.authValue = in->newAuth; 35679 // Write index info back to NV 35680 NvWriteIndexInfo(in->nvIndex, &nvIndex); 35681 return TPM_RC_SUCCESS; 35682 } 35683 35684 Page 440 35685 October 31, 2013 35686 35687 Published 35688 Copyright TCG 2006-2013 35689 35690 Family 2.0 35691 Level 00 Revision 00.99 35692 35693 Trusted Platform Module Library 35695 35696 Part 3: Commands 35697 35698 33.16 TPM2_NV_Certify 35699 33.16.1 35700 35701 General Description 35702 35703 The purpose of this command is to certify the contents of an NV Index or portion of an NV Index. 35704 If proper authorization for reading the NV Index is provided, the portion of the NV Index selected by size 35705 and offset are included in an attestation block and signed using the key indicated by signHandle. The 35706 attestation also includes size and offset so that the range of the data can be determined. 35707 NOTE 35708 35709 See 20.1 for description of how the signing scheme is selected. 35710 35711 Family 2.0 35712 Level 00 Revision 00.99 35713 35714 Published 35715 Copyright TCG 2006-2013 35716 35717 Page 441 35718 October 31, 2013 35719 35720 Part 3: Commands 35722 35723 33.16.2 35724 35725 Trusted Platform Module Library 35726 35727 Command and Response 35728 Table 223 TPM2_NV_Certify Command 35729 35730 Type 35731 35732 Name 35733 35734 Description 35735 35736 TPMI_ST_COMMAND_TAG 35737 35738 tag 35739 35740 UINT32 35741 35742 commandSize 35743 35744 TPM_CC 35745 35746 commandCode 35747 35748 TPM_CC_NV_Certify 35749 35750 TPMI_DH_OBJECT+ 35751 35752 @signHandle 35753 35754 handle of the key used to sign the attestation structure 35755 Auth Index: 1 35756 Auth Role: USER 35757 35758 TPMI_RH_NV_AUTH 35759 35760 @authHandle 35761 35762 handle indicating the source of the authorization value 35763 for the NV Index 35764 Auth Index: 2 35765 Auth Role: USER 35766 35767 TPMI_RH_NV_INDEX 35768 35769 nvIndex 35770 35771 Index for the area to be certified 35772 Auth Index: None 35773 35774 TPM2B_DATA 35775 35776 qualifyingData 35777 35778 user-provided qualifying data 35779 35780 TPMT_SIG_SCHEME+ 35781 35782 inScheme 35783 35784 signing scheme to use if the scheme for signHandle is 35785 TPM_ALG_NULL 35786 35787 UINT16 35788 35789 size 35790 35791 number of octets to certify 35792 35793 UINT16 35794 35795 offset 35796 35797 octet offset into the area 35798 This value shall be less than or equal to the size of the 35799 nvIndex data. 35800 35801 Table 224 TPM2_NV_Certify Response 35802 Type 35803 35804 Name 35805 35806 Description 35807 35808 TPM_ST 35809 35810 tag 35811 35812 see clause 8 35813 35814 UINT32 35815 35816 responseSize 35817 35818 TPM_RC 35819 35820 responseCode 35821 35822 . 35823 35824 TPM2B_ATTEST 35825 35826 certifyInfo 35827 35828 the structure that was signed 35829 35830 TPMT_SIGNATURE 35831 35832 signature 35833 35834 the asymmetric signature over certifyInfo using the key 35835 referenced by signHandle 35836 35837 Page 442 35838 October 31, 2013 35839 35840 Published 35841 Copyright TCG 2006-2013 35842 35843 Family 2.0 35844 Level 00 Revision 00.99 35845 35846 Trusted Platform Module Library 35848 35849 33.16.3 35850 1 35851 2 35852 3 35853 4 35854 35855 Detailed Actions 35856 35857 #include 35858 #include 35859 #include 35860 #include 35861 35862 Part 3: Commands 35863 35864 "InternalRoutines.h" 35865 "Attest_spt_fp.h" 35866 "NV_spt_fp.h" 35867 "NV_Certify_fp.h" 35868 35869 Error Returns 35870 TPM_RC_NV_AUTHORIZATION 35871 35872 the authorization was valid but the authorizing entity (authHandle) is 35873 not allowed to read from the Index referenced by nvIndex 35874 35875 TPM_RC_KEY 35876 35877 signHandle does not reference a signing key 35878 35879 TPM_RC_NV_LOCKED 35880 35881 Index referenced by nvIndex is locked for reading 35882 35883 TPM_RC_NV_RANGE 35884 35885 offset plus size extends outside of the data range of the Index 35886 referenced by nvIndex 35887 35888 TPM_RC_NV_UNINITIALIZED 35889 35890 Index referenced by nvIndex has not been written 35891 35892 TPM_RC_SCHEME 35893 5 35894 6 35895 7 35896 8 35897 9 35898 10 35899 11 35900 12 35901 13 35902 14 35903 15 35904 16 35905 17 35906 18 35907 19 35908 20 35909 21 35910 22 35911 23 35912 24 35913 25 35914 26 35915 27 35916 28 35917 29 35918 30 35919 31 35920 32 35921 33 35922 34 35923 35 35924 36 35925 37 35926 38 35927 39 35928 40 35929 41 35930 42 35931 43 35932 44 35933 35934 Meaning 35935 35936 inScheme is not an allowed value for the key definition 35937 35938 TPM_RC 35939 TPM2_NV_Certify( 35940 NV_Certify_In 35941 NV_Certify_Out 35942 35943 *in, 35944 *out 35945 35946 // IN: input parameter list 35947 // OUT: output parameter list 35948 35949 ) 35950 { 35951 TPM_RC 35952 NV_INDEX 35953 TPMS_ATTEST 35954 35955 result; 35956 nvIndex; 35957 certifyInfo; 35958 35959 // Attestation command may cause the orderlyState to be cleared due to 35960 // the reporting of clock info. If this is the case, check if NV is 35961 // available first 35962 if(gp.orderlyState != SHUTDOWN_NONE) 35963 { 35964 // The command needs NV update. Check if NV is available. 35965 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 35966 // this point 35967 result = NvIsAvailable(); 35968 if(result != TPM_RC_SUCCESS) 35969 return result; 35970 } 35971 // Input Validation 35972 // Get NV index info 35973 NvGetIndexInfo(in->nvIndex, &nvIndex); 35974 // Common access checks. A TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED 35975 // error may be returned at this point 35976 result = NvReadAccessChecks(in->authHandle, in->nvIndex); 35977 if(result != TPM_RC_SUCCESS) 35978 return result; 35979 // See if the range to be certified is out of the bounds of the defined 35980 // Index 35981 if((in->size + in->offset) > nvIndex.publicArea.dataSize) 35982 return TPM_RC_NV_RANGE; 35983 // Command Output 35984 35985 Family 2.0 35986 Level 00 Revision 00.99 35987 35988 Published 35989 Copyright TCG 2006-2013 35990 35991 Page 443 35992 October 31, 2013 35993 35994 Part 3: Commands 35996 45 35997 46 35998 47 35999 48 36000 49 36001 50 36002 51 36003 52 36004 53 36005 54 36006 55 36007 56 36008 57 36009 58 36010 59 36011 60 36012 61 36013 62 36014 63 36015 64 36016 65 36017 66 36018 67 36019 68 36020 69 36021 70 36022 71 36023 72 36024 73 36025 74 36026 75 36027 76 36028 77 36029 78 36030 79 36031 80 36032 81 36033 82 36034 83 36035 84 36036 85 36037 86 36038 87 36039 88 36040 89 36041 90 36042 91 36043 92 36044 93 36045 94 36046 95 36047 96 36048 97 36049 98 36050 99 36051 100 36052 36053 Trusted Platform Module Library 36054 36055 // Filling in attest information 36056 // Common fields 36057 // FillInAttestInfo can return TPM_RC_SCHEME or TPM_RC_KEY 36058 result = FillInAttestInfo(in->signHandle, 36059 &in->inScheme, 36060 &in->qualifyingData, 36061 &certifyInfo); 36062 if(result != TPM_RC_SUCCESS) 36063 { 36064 if(result == TPM_RC_KEY) 36065 return TPM_RC_KEY + RC_NV_Certify_signHandle; 36066 else 36067 return RcSafeAddToResult(result, RC_NV_Certify_inScheme); 36068 } 36069 // NV certify specific fields 36070 // Attestation type 36071 certifyInfo.type = TPM_ST_ATTEST_NV; 36072 // Get the name of the index 36073 certifyInfo.attested.nv.indexName.t.size = 36074 NvGetName(in->nvIndex, &certifyInfo.attested.nv.indexName.t.name); 36075 // Set the return size 36076 certifyInfo.attested.nv.nvContents.t.size = in->size; 36077 // Set the offset 36078 certifyInfo.attested.nv.offset = in->offset; 36079 // Perform the read 36080 NvGetIndexData(in->nvIndex, &nvIndex, 36081 in->offset, in->size, 36082 certifyInfo.attested.nv.nvContents.t.buffer); 36083 // Sign attestation structure. A NULL signature will be returned if 36084 // signHandle is TPM_RH_NULL. SignAttestInfo() may return TPM_RC_VALUE, 36085 // TPM_RC_SCHEME or TPM_RC_ATTRUBUTES. 36086 // Note: SignAttestInfo may return TPM_RC_ATTRIBUTES if the key is not a 36087 // signing key but that was checked above. TPM_RC_VALUE would mean that the 36088 // data to sign is too large but the data to sign is a digest 36089 result = SignAttestInfo(in->signHandle, 36090 &in->inScheme, 36091 &certifyInfo, 36092 &in->qualifyingData, 36093 &out->certifyInfo, 36094 &out->signature); 36095 if(result != TPM_RC_SUCCESS) 36096 return result; 36097 // orderly state should be cleared because of the reporting of clock info 36098 // if signing happens 36099 if(in->signHandle != TPM_RH_NULL) 36100 g_clearOrderly = TRUE; 36101 return TPM_RC_SUCCESS; 36102 } 36103 36104 Page 444 36105 October 31, 2013 36106 36107 Published 36108 Copyright TCG 2006-2013 36109 36110 Family 2.0 36111 Level 00 Revision 00.99 36112 36113
